@te-river/opencode-team-mode 1.7.7 → 1.7.9

package/docs/research/host-http-api.md

@@ -1,132 +1,132 @@
-# OpenCode 2.0.18 — the host's own HTTP API, and what it changes for a plugin
-
-**Status: mapped, not called.** Every route below was read out of the installed host's
-embedded JS (the SDK client factory: `method:"GET", path:"/api/…"` entries, both literal and
-template-literal), cross-checked against the official v2 API page for the plugin endpoints. **No
-request has been made to any of them** — so "exists in the client" is not the same claim as
-"works from a plugin process", and nothing here is a verified capability.
-
-**Why it matters.** The v2 plugin context is thin: no SDK client, no `session.children`, no
-message domain, no dialog. Several conclusions this repo recorded as host limitations are
-actually *ctx* limitations — the server behind the ctx has a much larger surface. This page
-separates the two so a future change does not re-accept a limitation that is really a missing
-transport.
-
-## 1. Discovery and authentication
-
-`[B]`+`[D]` `GET /api/info` returns "the server identity, connection URLs, paths, and
-readiness status". The CLI reaches a server through a helper that yields `{url, password}`, and
-the transport is HTTP Basic with a fixed username:
-
-```js
-{ type: "basic", username: "opencode", password: e.password }
-await fetch(new URL("/api/info", e.url), { headers: X(i), signal: AbortSignal.timeout(r) })
-```
-
-`[B]` The password is **not** per-process random-only: `<global-config>/service.json` holds a
-single `password` string (43 chars on this machine). The port is dynamic (`serve --stdio
---port 0`), which is why `/api/info` exists.
-
-`[U]` Whether a plugin can obtain `{url, password}` from its own context instead of reading
-that file is the open question, and it is the whole cost of every item below: **reading the
-user's credential file to call back into the host is a new trust boundary**, and a plugin that
-does it silently would be doing exactly what goal #6 forbids. Nothing in this repo does it
-today, and `src/host/v2-session-client.ts` says so where the temptation is documented.
-
-## 2. The routes that touch our recorded conclusions
-
-| route family (`[B]`) | what it offers | which claim it reopens |
-|---|---|---|
-| `GET /api/plugin`, `POST /api/plugin/check`, `POST /api/plugin/update` | the enabled server plugins **with live status**, plus update checking | the install-verification story: this is a cleaner arrival check than grepping `msg="loading plugin"` (which is what `docs/installation-v2.md` currently tells an agent to do) |
-| `GET /api/session/{id}/message`, `GET /api/session/{id}/message/{messageID}`, `GET /api/session/{id}/context` | read a session's messages — including a CHILD session | `tm_join`'s "the body arrives by injection, we cannot read it" limit. The in-process `ctx.session.context` is tried first (see §4); the API is the fallback with a price |
-| `GET /api/permission/request`, `POST /api/session/{id}/permission`, `GET /api/permission/saved`, `DELETE /api/permission/saved/{id}` | the permission queue, answering it, and the saved-rule store | **"a plugin cannot raise a dialog on v2"** — that was measured against the ctx (`options.permission` on our own tool produced no evaluation). The server clearly has a dialog surface; whether a plugin may drive it is unmeasured, and driving it *for* the user would be self-allowing, which this project never does |
-| `GET /api/pty`, `POST /api/pty`, `GET /api/pty/{id}/output?`, `GET /api/experimental/persistent-pty/{id}`, `.../snapshot`, `.../connect-token`, `POST /api/experimental/persistent-pty/{id}/connect-token` | terminal sessions with **snapshot/read**, i.e. exactly the capture capability `tm_pty` lacked | task #21 ("v2 has no `client.pty` → retire `tm_pty`") was decided on the ctx surface. The host has a persistent-pty API. Retirement still looks right (a plugin spawning terminals the user cannot see is its own problem), but the reason is now "no in-process seam + trust boundary", not "the host has no such thing" |
-| `GET /api/fs/read/{path}`, `GET /api/fs/list`, `GET /api/fs/find`, `POST /api/experimental/fs/write` | file access through the host's own permission layer | reinforces the 1.7.x decision to retire `tm_read`/`tm_grep`/`tm_bash` in favour of the native ladder — the native path is where the host's `external_directory` dialog lives |
-| `POST /api/websearch`, `GET /api/websearch/provider` | server-side search | all four native providers need a key/`/connect`, so `tm_search`'s zero-key front stays (unchanged conclusion, now with the reason visible) |
-| `POST /api/session/{id}/wait`, `POST /api/experimental/session/{id}/wait`, `GET /api/experimental/session/stats`, `GET /api/experimental/session/{id}/export`, `POST /api/session/{id}/synthetic`, `.../interrupt`, `.../compact`, `.../fork` | waiting on and injecting into sessions | the shape of what a *session-owning* API looks like — useful for judging whether `tm_join`'s bounded wait is fighting the host or duplicating it |
-| `GET /api/event` | the SSE feed | `ctx.event.subscribe()` is this stream, in-process. No reason to prefer HTTP |
-
-## 3. The question the user actually asked: is there a todo list?
-
-**No.** `[B]` Across **136 distinct `METHOD /path` pairs** in the scanned window (55 literal +
-81 template-literal paths, deduplicated — a lower bound, since the scan covered 2 MB of the
-embedded JS rather than the whole client factory) there is no `todo`, no `plan`, no `task`
-resource; the only `message` routes are `GET /api/session/{id}/message` and
-`GET /api/session/{id}/message/{messageID}`. `[D]` The official API page lists none either. The
-v1 REST endpoint `GET /session/{id}/todo` that `tm_join`'s goal tripwire was written against
-does not exist on 2.x, which is the same fact as "the host has no `todowrite` tool" seen from
-the other side. So `tm_ledger` is not a workaround we settled for: it is the only ledger there
-is. What *is* available for the same purpose is `GET /api/session/{id}/context` (in-process)
-and `/message` (HTTP) — reading what the model was told, rather than a list the model
-maintains.
-
-## 4. What was verified instead, in-process
-
-`[B]` The host's own call sites give the plugin-facing argument shape, and that fixed a bridge
-that had never worked:
-
-```
-te = (schema, fn) => (input) => decode(schema, input ?? {}) → fn(decoded)
-await e.session.get({ sessionID: n })
-await e.message.list({ sessionID: n, limit: 200, cursor: r })
-```
-
-`ctx.session.get` therefore takes a **single flat object `{sessionID}`** — not v1's
-`{path:{id}}`, and not an array. `src/host/v2-session-client.ts` had both wrong, which is why
-every lookup failed silently for a release cycle.
-
-`[L]` **The full ctx domain set, measured 2026-09-26 with zero model tokens** (a plugin that
-only inspects its own context, booted under `--standalone --model nope/nope`; every method
-called with `{}` so the host's own decode error names the required key):
-
-| domain | what the host gives a plugin |
-|---|---|
-| `session` | `hook create get switchAgent switchModel prompt generate command synthetic interrupt update move wait context` |
-| `permission` | `hook list get reply` — all of `list/get/reply` decode as `{sessionID}` |
-| `experimental` | `terminal.read` (decodes as `{sessionID}`; a terminal-id spelling has not been found) |
-| `storage` | `get set remove scan` |
-| `agent` / `model` / `command` / `mcp` / `worktree` | `list/get/transform/reload` families |
-| `event` | `subscribe` (an async iterable, already used by `v2-events.ts`) |
-| `rpc` | a single function of arity 1 — its calling convention has NOT been read out |
-
-`[L]` **`ctx.session.context({sessionID})` answers with an ARRAY of flat items**, measured
-against a real background child from a live round:
-
-```
-array(5) < { id: string, time: { created: number }, text: string, type: string }  // type "user" …
-```
-
-That is NOT v1's `[{info:{role},parts:[…]}]`, and it is the reason a child's report was lost for
-a release: `v2-session-client.ts` already called `context`, then handed the array to
-`lastAssistantMessage`, which tolerates an unknown shape by returning no text. The seam
-ANSWERED and the body was discarded, while `tm_join` told the lead 正文不经本工具 — our decode
-miss reported as the host's limit. The flat shape is now normalised at the seam
-(`normaliseContextMessages`), and no `time.completed` is invented there, because that field *is*
-the settle verdict.
-
-## 5. Deliberate non-goals
-
-`[U]` No HTTP call is made by this plugin today. The reasons are recorded rather than implied:
-the credential read is a trust boundary the user has not been asked about; a plugin answering
-`/api/permission/request` would be self-allowing; and a plugin that can `POST
-/api/experimental/fs/write` bypasses the very `session.hook("context")` trim that keeps a
-denied role from being offered a tool. If any of these is ever pursued, it goes through the
-same gate as everything else here: Team-scoped, counted, and visible in `tm_stats`.
-
-## 6. The #32 decision, and what closed it
-
-The user authorised the HTTP API on one condition — 保证不会被泄露. That condition is the reason
-§4's probe happened first, and the probe made the condition moot:
-
-- **子会话正文**: `ctx.session.context` in process (§4). No credential exists to leak.
-- **权限队列**: `ctx.permission.list({sessionID})` answers in process — verified as a seam,
-  NOT yet used. Reading it to tell the user "N dialogs are waiting" is legitimate; calling
-  `reply` is not, because that is self-allowing, and `reply` stays uncalled.
-- **pty 捕获**: `ctx.experimental.terminal.read({sessionID})` exists but its second argument
-  has not been found, so `tm_pty`'s retirement decision (§21) is unchanged for now — the
-  reason is updated from "the host has no such thing" to "the plugin seam is unread".
-
-What the scan still settles on its own: there is **no todo/plan/task resource anywhere**, so
-`tm_ledger` is not a compromise. And `~/.config/opencode/service.json` has never been opened by
-this plugin, which `test-v2-adapter.mjs` group 12 asserts against the shipped source.
-
+# OpenCode 2.0.18 — the host's own HTTP API, and what it changes for a plugin
+
+**Status: mapped, not called.** Every route below was read out of the installed host's
+embedded JS (the SDK client factory: `method:"GET", path:"/api/…"` entries, both literal and
+template-literal), cross-checked against the official v2 API page for the plugin endpoints. **No
+request has been made to any of them** — so "exists in the client" is not the same claim as
+"works from a plugin process", and nothing here is a verified capability.
+
+**Why it matters.** The v2 plugin context is thin: no SDK client, no `session.children`, no
+message domain, no dialog. Several conclusions this repo recorded as host limitations are
+actually *ctx* limitations — the server behind the ctx has a much larger surface. This page
+separates the two so a future change does not re-accept a limitation that is really a missing
+transport.
+
+## 1. Discovery and authentication
+
+`[B]`+`[D]` `GET /api/info` returns "the server identity, connection URLs, paths, and
+readiness status". The CLI reaches a server through a helper that yields `{url, password}`, and
+the transport is HTTP Basic with a fixed username:
+
+```js
+{ type: "basic", username: "opencode", password: e.password }
+await fetch(new URL("/api/info", e.url), { headers: X(i), signal: AbortSignal.timeout(r) })
+```
+
+`[B]` The password is **not** per-process random-only: `<global-config>/service.json` holds a
+single `password` string (43 chars on this machine). The port is dynamic (`serve --stdio
+--port 0`), which is why `/api/info` exists.
+
+`[U]` Whether a plugin can obtain `{url, password}` from its own context instead of reading
+that file is the open question, and it is the whole cost of every item below: **reading the
+user's credential file to call back into the host is a new trust boundary**, and a plugin that
+does it silently would be doing exactly what goal #6 forbids. Nothing in this repo does it
+today, and `src/host/v2-session-client.ts` says so where the temptation is documented.
+
+## 2. The routes that touch our recorded conclusions
+
+| route family (`[B]`) | what it offers | which claim it reopens |
+|---|---|---|
+| `GET /api/plugin`, `POST /api/plugin/check`, `POST /api/plugin/update` | the enabled server plugins **with live status**, plus update checking | the install-verification story: this is a cleaner arrival check than grepping `msg="loading plugin"` (which is what `docs/installation-v2.md` currently tells an agent to do) |
+| `GET /api/session/{id}/message`, `GET /api/session/{id}/message/{messageID}`, `GET /api/session/{id}/context` | read a session's messages — including a CHILD session | `tm_join`'s "the body arrives by injection, we cannot read it" limit. The in-process `ctx.session.context` is tried first (see §4); the API is the fallback with a price |
+| `GET /api/permission/request`, `POST /api/session/{id}/permission`, `GET /api/permission/saved`, `DELETE /api/permission/saved/{id}` | the permission queue, answering it, and the saved-rule store | **"a plugin cannot raise a dialog on v2"** — that was measured against the ctx (`options.permission` on our own tool produced no evaluation). The server clearly has a dialog surface; whether a plugin may drive it is unmeasured, and driving it *for* the user would be self-allowing, which this project never does |
+| `GET /api/pty`, `POST /api/pty`, `GET /api/pty/{id}/output?`, `GET /api/experimental/persistent-pty/{id}`, `.../snapshot`, `.../connect-token`, `POST /api/experimental/persistent-pty/{id}/connect-token` | terminal sessions with **snapshot/read**, i.e. exactly the capture capability `tm_pty` lacked | task #21 ("v2 has no `client.pty` → retire `tm_pty`") was decided on the ctx surface. The host has a persistent-pty API. Retirement still looks right (a plugin spawning terminals the user cannot see is its own problem), but the reason is now "no in-process seam + trust boundary", not "the host has no such thing" |
+| `GET /api/fs/read/{path}`, `GET /api/fs/list`, `GET /api/fs/find`, `POST /api/experimental/fs/write` | file access through the host's own permission layer | reinforces the 1.7.x decision to retire `tm_read`/`tm_grep`/`tm_bash` in favour of the native ladder — the native path is where the host's `external_directory` dialog lives |
+| `POST /api/websearch`, `GET /api/websearch/provider` | server-side search | all four native providers need a key/`/connect`, so `tm_search`'s zero-key front stays (unchanged conclusion, now with the reason visible) |
+| `POST /api/session/{id}/wait`, `POST /api/experimental/session/{id}/wait`, `GET /api/experimental/session/stats`, `GET /api/experimental/session/{id}/export`, `POST /api/session/{id}/synthetic`, `.../interrupt`, `.../compact`, `.../fork` | waiting on and injecting into sessions | the shape of what a *session-owning* API looks like — useful for judging whether `tm_join`'s bounded wait is fighting the host or duplicating it |
+| `GET /api/event` | the SSE feed | `ctx.event.subscribe()` is this stream, in-process. No reason to prefer HTTP |
+
+## 3. The question the user actually asked: is there a todo list?
+
+**No.** `[B]` Across **136 distinct `METHOD /path` pairs** in the scanned window (55 literal +
+81 template-literal paths, deduplicated — a lower bound, since the scan covered 2 MB of the
+embedded JS rather than the whole client factory) there is no `todo`, no `plan`, no `task`
+resource; the only `message` routes are `GET /api/session/{id}/message` and
+`GET /api/session/{id}/message/{messageID}`. `[D]` The official API page lists none either. The
+v1 REST endpoint `GET /session/{id}/todo` that `tm_join`'s goal tripwire was written against
+does not exist on 2.x, which is the same fact as "the host has no `todowrite` tool" seen from
+the other side. So `tm_ledger` is not a workaround we settled for: it is the only ledger there
+is. What *is* available for the same purpose is `GET /api/session/{id}/context` (in-process)
+and `/message` (HTTP) — reading what the model was told, rather than a list the model
+maintains.
+
+## 4. What was verified instead, in-process
+
+`[B]` The host's own call sites give the plugin-facing argument shape, and that fixed a bridge
+that had never worked:
+
+```
+te = (schema, fn) => (input) => decode(schema, input ?? {}) → fn(decoded)
+await e.session.get({ sessionID: n })
+await e.message.list({ sessionID: n, limit: 200, cursor: r })
+```
+
+`ctx.session.get` therefore takes a **single flat object `{sessionID}`** — not v1's
+`{path:{id}}`, and not an array. `src/host/v2-session-client.ts` had both wrong, which is why
+every lookup failed silently for a release cycle.
+
+`[L]` **The full ctx domain set, measured 2026-09-26 with zero model tokens** (a plugin that
+only inspects its own context, booted under `--standalone --model nope/nope`; every method
+called with `{}` so the host's own decode error names the required key):
+
+| domain | what the host gives a plugin |
+|---|---|
+| `session` | `hook create get switchAgent switchModel prompt generate command synthetic interrupt update move wait context` |
+| `permission` | `hook list get reply` — all of `list/get/reply` decode as `{sessionID}` |
+| `experimental` | `terminal.read` (decodes as `{sessionID}`; a terminal-id spelling has not been found) |
+| `storage` | `get set remove scan` |
+| `agent` / `model` / `command` / `mcp` / `worktree` | `list/get/transform/reload` families |
+| `event` | `subscribe` (an async iterable, already used by `v2-events.ts`) |
+| `rpc` | a single function of arity 1 — its calling convention has NOT been read out |
+
+`[L]` **`ctx.session.context({sessionID})` answers with an ARRAY of flat items**, measured
+against a real background child from a live round:
+
+```
+array(5) < { id: string, time: { created: number }, text: string, type: string }  // type "user" …
+```
+
+That is NOT v1's `[{info:{role},parts:[…]}]`, and it is the reason a child's report was lost for
+a release: `v2-session-client.ts` already called `context`, then handed the array to
+`lastAssistantMessage`, which tolerates an unknown shape by returning no text. The seam
+ANSWERED and the body was discarded, while `tm_join` told the lead 正文不经本工具 — our decode
+miss reported as the host's limit. The flat shape is now normalised at the seam
+(`normaliseContextMessages`), and no `time.completed` is invented there, because that field *is*
+the settle verdict.
+
+## 5. Deliberate non-goals
+
+`[U]` No HTTP call is made by this plugin today. The reasons are recorded rather than implied:
+the credential read is a trust boundary the user has not been asked about; a plugin answering
+`/api/permission/request` would be self-allowing; and a plugin that can `POST
+/api/experimental/fs/write` bypasses the very `session.hook("context")` trim that keeps a
+denied role from being offered a tool. If any of these is ever pursued, it goes through the
+same gate as everything else here: Team-scoped, counted, and visible in `tm_stats`.
+
+## 6. The #32 decision, and what closed it
+
+The user authorised the HTTP API on one condition — 保证不会被泄露. That condition is the reason
+§4's probe happened first, and the probe made the condition moot:
+
+- **子会话正文**: `ctx.session.context` in process (§4). No credential exists to leak.
+- **权限队列**: `ctx.permission.list({sessionID})` answers in process — verified as a seam,
+  NOT yet used. Reading it to tell the user "N dialogs are waiting" is legitimate; calling
+  `reply` is not, because that is self-allowing, and `reply` stays uncalled.
+- **pty 捕获**: `ctx.experimental.terminal.read({sessionID})` exists but its second argument
+  has not been found, so `tm_pty`'s retirement decision (§21) is unchanged for now — the
+  reason is updated from "the host has no such thing" to "the plugin seam is unread".
+
+What the scan still settles on its own: there is **no todo/plan/task resource anywhere**, so
+`tm_ledger` is not a compromise. And `~/.config/opencode/service.json` has never been opened by
+this plugin, which `test-v2-adapter.mjs` group 12 asserts against the shipped source.
+