docs(api): describe Connection-owned transport

2026-08-29 04:26:38 +00:00 · 2026-08-27 22:26:30 +08:00
parent 4f00a8b82a
commit e57e7c3f25
154 changed files with 464 additions and 444 deletions
@@ -2,5 +2,5 @@
 # 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 apps/cli/reference/README.md
-README.md: dcb5f7fd36ba2f5db3e4ce65abc23f266872c4d3
-README.zh.md: bc87059883f641d850e18516b86f4bb089d8158e
+README.md: 03ec7c3a14b35f20b748a1534ae7f98861cc6a49
+README.zh.md: d8655832656d73d6b7193be918da422648c50e84
@@ -30,7 +30,7 @@ The shipped apps own these command lines:
 | `sdk-minimal` | no options; stdio carries the same JSON-RPC protocol |
 | `acp` | no options; stdio carries Agent Client Protocol |

-A one-shot task (`dsh --profile headless "run the tests"`) creates one fresh persisted Agent through the core registry, submits the task, waits for quiescence, and flushes the Session before deriving the last non-empty assistant text and final `turn/end` reason from its durable interval. It streams non-empty provider reasoning deltas to stderr under a `dsh: reasoning:` heading, prints only the final text on stdout, and exits 0 for `completed`, else 1; a successful response with no reasoning leaves stderr empty. An invocation with no task is a usage error from that app. The shipped headless profile mounts no ApiProxy, Host, HTTP server, Web runtime, or browser client, and opens no listening port.
+A one-shot task (`dsh --profile headless "run the tests"`) creates one fresh persisted Agent through the core registry, submits the task, waits for quiescence, and flushes the Session before deriving the last non-empty assistant text and final `turn/end` reason from its durable interval. It streams non-empty provider reasoning deltas to stderr under a `dsh: reasoning:` heading, prints only the final text on stdout, and exits 0 for `completed`, else 1; a successful response with no reasoning leaves stderr empty. An invocation with no task is a usage error from that app. The shipped headless profile mounts no browser Connection, HTTP server, Web runtime, or browser client, and opens no listening port.

 Inspect the composed tree without booting it:

@@ -30,7 +30,7 @@
 | `sdk-minimal` | 无选项；stdio 携带相同的 JSON-RPC 协议 |
 | `acp` | 无选项；stdio 携带 Agent Client Protocol |

-一次性任务（`dsh --profile headless "run the tests"`）通过核心注册表创建一个全新的持久化 Agent（智能体），提交任务、等待完全停稳并对会话执行 flush，再从其持久化事件区间中推导最后一个非空 assistant 文本与最终 `turn/end` 原因。它在 `dsh: reasoning:` 标题下将非空的提供方推理分片流式写入 stderr，只在 stdout 打印最终文本，并在原因为 `completed` 时以 0 退出，否则以 1 退出；没有推理内容的成功响应会保持 stderr 为空。没有任务的调用是该应用的用法错误。随附 headless profile 不挂载 ApiProxy、Host、HTTP 服务器、Web 运行时或浏览器客户端，也不会打开监听端口。
+一次性任务（`dsh --profile headless "run the tests"`）通过核心注册表创建一个全新的持久化 Agent（智能体），提交任务、等待完全停稳并对会话执行 flush，再从其持久化事件区间中推导最后一个非空 assistant 文本与最终 `turn/end` 原因。它在 `dsh: reasoning:` 标题下将非空的提供方推理分片流式写入 stderr，只在 stdout 打印最终文本，并在原因为 `completed` 时以 0 退出，否则以 1 退出；没有推理内容的成功响应会保持 stderr 为空。没有任务的调用是该应用的用法错误。随附 headless profile 不挂载浏览器 Connection、HTTP 服务器、Web 运行时或浏览器客户端，也不会打开监听端口。

 可在不启动的情况下检查组合出的配置树：

@@ -2,5 +2,5 @@
 # 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 apps/web/tests/README.md
-README.md: 2104d9422cfbbcbc7ffc4b12e491c0a62daa3b9d
-README.zh.md: 4dfa5b2f61c757e481d9b8e012b37a5e71d75093
+README.md: e5b97f0b7527da01ce7c926360145fee49e168f0
+README.zh.md: f360c2b487bbf5b1a1c81492e5b4c2d4eaa8d749
@@ -11,8 +11,8 @@ the deliberate composition divergences from `dsh web` — are documented in
 ## These are Host-face tests

 They type-check in the root `tsconfig.host.json`, not in the Client aggregate,
-because they read Host services directly: `ctx.apiProxy`, the Host
-`SessionStore`, `ctx.sessionProjectionCache`. Driving a browser at runtime does
+because they read Host services directly: `ctx.connection`, the Host
+`SessionStore`, and `ctx.sessionProjectionCache`. Driving a browser at runtime does
 not make a file part of the Client program — the two faces merge cordis
 `Context` under the same keys with different services, so one program cannot see
 both. Moving these files into the Client aggregate makes every Host-service
@@ -10,7 +10,7 @@
 ## 这些是 Host 面的测试

 它们在根 `tsconfig.host.json` 中做类型检查，而不在 Client aggregate 中，因为它们直接读取
-Host 服务：`ctx.apiProxy`、Host 侧 `SessionStore`、`ctx.sessionProjectionCache`。运行时驱动
+Host 服务：`ctx.connection`、Host 侧 `SessionStore` 与 `ctx.sessionProjectionCache`。运行时驱动
 浏览器并不使一个文件成为 Client 程序的一部分——两个 face 在相同的键上以不同服务合并 cordis
 `Context`，因此单个程序无法同时看见两者。把这些文件挪进 Client aggregate 会让每一处
 Host 服务访问都无法编译。
@@ -1,5 +1,5 @@
 // Web e2e scenario: fresh round trip. A real chromium types a prompt into the
-// real composer; the wire, apiproxy, agent loop, and the REAL bash tool (echo
+// real composer; the wire, Remote gateway, agent loop, and the REAL bash tool (echo
 // in the temp workspace) all run; the model adapter is dsh-llm-replay (keyless)
 // or the live adapter (record). Drive steps run in every mode and wait only
 // on generic completion (whenTurnSettled — never model-content selectors, so