docs: document controller Remote transport

packages/api/session-controller/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/api/session-controller/README.md
+README.md: 55e5894ad1e8d2ab1f6c4c8373e87c3fc4fe397f
+README.zh.md: 2c308902088d8c445fb6f421111d514bf84e9de3

packages/api/session-controller/README.md

@@ -0,0 +1,22 @@
+# Session Controller
+
+English | [中文](README.zh.md)
+
+`@deepseek-ai/dsh-api-session-controller` owns the Host `ctx.sessionController` service and the generated Client `ctx.remote.session` namespace. It serves Session list, search, creation, model selection, rename, fork, prompt, attachment, queue, cancellation, message-aligned history, live log following, Host-wide control state, and pending-interaction responses.
+
+Each endpoint states its activation policy. List, search, attachment, history pages, and log following can inspect persistence without activating an Agent; queue mutation, cancellation, and interaction responses require the corresponding live state; model, rename, and prompt commands may explicitly resume an ordinary Session. Create and fork are the only operations that create a new Agent. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces.
+
+The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, and `append` changes, and repairs reconnect or sequence gaps through a tail page. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, projection, approval, and question state instead of treating transient values as durable events.
+
+## Model Experience
+
+None, as invoked Agent commands own any model-visible effect.
+
+#### KV Cache effect
+
+No direct effect; model requests remain owned by the Agent and LLM packages.
+
+## Known Limitations and Deferred Work
+
+- Control baselines represent process-local state and therefore cannot reconstruct pending interactions or jobs after a Host restart.
+- A failed follow resumption remains visible to the caller instead of retrying indefinitely.

packages/api/session-controller/README.zh.md

@@ -0,0 +1,22 @@
+# Session Controller
+
+[English](README.md) | 中文
+
+`@deepseek-ai/dsh-api-session-controller` 拥有 Host 的 `ctx.sessionController` 服务和生成的 Client `ctx.remote.session` namespace。它提供 Session 列表、搜索、创建、模型选择、重命名、fork、prompt、附件、queue、取消、按消息对齐的历史、live 日志跟随、Host 范围 control 状态和 pending interaction 响应。
+
+每个 endpoint 都声明自己的激活策略。列表、搜索、附件、历史页和日志跟随可以在不激活 Agent 的情况下检查 persistence；queue 变更、取消和 interaction 响应要求对应 live 状态仍然存在；模型、重命名和 prompt 命令可以显式恢复普通 Session。只有 create 和 fork 会创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。
+
+Client adapter 提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend` 和 `append` 变更，并通过 tail page 修复重连或 seq 缺口。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 queue、jobs、projection、approval 和 question 状态，而不会把瞬态值当作 durable event。
+
+## 模型体验
+
+无，因为被调用的 Agent 命令拥有任何模型可见效果。
+
+#### KV Cache 影响
+
+无直接影响；模型请求仍由 Agent 和 LLM 包拥有。
+
+## 已知限制与延期工作
+
+- Control baseline 表示进程本地状态，因此 Host 重启后无法重建 pending interaction 或 jobs。
+- follow 恢复失败会对调用方可见，而不会无限重试。