From 977d281d64a9d72077fd058c6058c81690ff3b16 Mon Sep 17 00:00:00 2001 From: Simon Klee Date: Thu, 29 Oct 2026 08:59:06 +0100 Subject: [PATCH] feat(client): fall back to per-Session reads on servers without the family route A client from this branch talking to an older server got a 404 for every family read, so the TUI closed the session it was opening. The data layer now learns once per connection whether the server has the family route. An older server answers it with a 404 that has no typed error body; a missing Session still returns SessionNotFoundError and still rejects. On the first untyped 404 the client falls back for the rest of the connection and tries the route again after every reconnect. The fallback restores the reads that preceded the family route: the Session and its paged direct children, merged into the membership already known, then pending permissions and forms for every known family member, waiting only for the requested Session's. Status comes only from /session/active and execution events, since older servers send none. A stale read neither falls back nor marks the route missing. Delete the fallback once the oldest supported server has the family route. --- packages/client/src/solid/data.ts | 71 +++++++++++++- packages/client/test/solid-data.test.ts | 93 ++++++++++++++++++- packages/tui/test/completion-notices.test.tsx | 56 +++++++++++ specs/v2/session-family-api.md | 6 +- 4 files changed, 217 insertions(+), 9 deletions(-) diff --git a/packages/client/src/solid/data.ts b/packages/client/src/solid/data.ts index 027f8bf018c..7bc9edfd50c 100644 --- a/packages/client/src/solid/data.ts +++ b/packages/client/src/solid/data.ts @@ -29,6 +29,7 @@ import type { SessionMessageAssistantText, SessionMessageAssistantTool, SessionInfo, + SessionListInput, SessionInboxInfo, SessionInboxCompaction, ShellInfo, @@ -44,6 +45,7 @@ import { Worktree } from "@opencode/schema/worktree" import { SessionID } from "@opencode/schema/session-id" import { SessionMessage } from "@opencode/schema/session-message" import { + ClientError, isFormAlreadySettledError, isFormNotFoundError, isMessageNotFoundError, @@ -255,8 +257,18 @@ function createSync() { } } +const CHILD_PAGE = 200 const DELETED_SESSION_LIMIT = 512 +// Servers that predate the family route answer it with an empty 404. This also matches any declared status without a +// readable JSON error body, such as a non-JSON 401 or a proxy page; the fallback reads then fail the same way. A missing +// Session is a typed SessionNotFoundError, and transport failures and undeclared statuses keep their own reasons. +function isMissingRoute(error: unknown) { + return ( + error instanceof ClientError && (error.reason === "UnsupportedContentType" || error.reason === "MalformedResponse") + ) +} + export function createData(config: CreateDataInput) { const api = config.api let disposed = false @@ -318,6 +330,8 @@ export function createData(config: CreateDataInput) { const stored = (message: SessionMessageInfo) => (config.omitToolFileData ? omitMessageFileData(message) : message) const sync = createSync() let activeUpdates: Map | undefined + // Learned once per connection, since a reconnect may reach an upgraded server. + let familyRouteMissing = false const pendingUpdates = new Map>() // One journal per Session, family, or pending-request read in flight. Reads and events arrive in either order, and an // event recorded during a read is newer than the read, so the read applies its response and then replays the events @@ -601,6 +615,16 @@ export function createData(config: CreateDataInput) { return created } + // Every direct subagent, not only the server's default first page, so a root's family cost + // counts all of them. Pages stay newest first, the order the family index has always used. + async function listChildren(input: SessionListInput): Promise { + const page = await api().session.list(input) + + if (page.data.length < CHILD_PAGE || !page.cursor.next) return page.data + + return [...page.data, ...(await listChildren({ cursor: page.cursor.next, limit: CHILD_PAGE }))] + } + // Walk parentID upward through loaded session info to the family root. When a // parent's info is missing, that missing ID is the furthest-known ancestor and // is returned so orphan subtrees group under it until the parent arrives. A @@ -731,6 +755,7 @@ export function createData(config: CreateDataInput) { function handleEvent(event: OpenCodeEvent) { switch (event.type) { case "server.connected": { + familyRouteMissing = false const updates = new Map() activeUpdates = updates refresh(() => @@ -1864,8 +1889,41 @@ export function createData(config: CreateDataInput) { ), ) // The family's membership is unknown until the read lands, so events for every Session are recorded. - return sync.run(`session.family:${sessionID}`, (stale) => - observeRead( + return sync.run(`session.family:${sessionID}`, (stale) => { + // Servers without the family route: the Session and its direct children, merged into what is already known. + // Status comes only from /session/active and events, and pending requests are read per member. + const fallback = async () => { + const loaded: string[] = [] + await observeRead( + () => + Promise.all([ + api().session.get({ sessionID }).catch(evictMissing), + listChildren({ parentID: sessionID, order: "desc", limit: CHILD_PAGE }), + ]).then(([info, children]) => [info, ...children]), + (sessions) => { + for (const session of sessions) { + clearDeleted(session.id) + setStore("session", "info", session.id, reconcile(session)) + registerSession(session.id) + sync.complete(`session:${session.id}`) + loaded.push(session.id) + } + return (id) => loaded.includes(id) + }, + stale, + ) + // Read every known member's pending requests, but wait only for the requested Session's. Older servers fail + // a member's reads when its worktree is gone; the other members still load. + const pending = (id: string) => [result.session.permission.sync(id), result.session.form.sync(id)] + void Promise.allSettled( + [...new Set([...loaded, ...(store.session.family[resolveRoot(sessionID)] ?? [])])] + .filter((id) => id !== sessionID) + .flatMap(pending), + ) + await Promise.allSettled(pending(sessionID)) + } + if (familyRouteMissing) return fallback() + return observeRead( () => api().experimental.sessionFamily.get({ sessionID }).catch(evictMissing), (family, journal) => { const ids = new Set(family.sessions.map((session) => session.id)) @@ -1919,8 +1977,13 @@ export function createData(config: CreateDataInput) { }, // A read invalidated in flight is superseded by a newer one, and its older snapshot would undo that read. stale, - ), - ) + ).catch((error: unknown) => { + if (!isMissingRoute(error)) throw error + if (stale()) return + familyRouteMissing = true + return fallback() + }) + }) }, invalidate(sessionID: string) { sync.invalidate(`session:${sessionID}`) diff --git a/packages/client/test/solid-data.test.ts b/packages/client/test/solid-data.test.ts index ce3a7cd2f07..879c1a90903 100644 --- a/packages/client/test/solid-data.test.ts +++ b/packages/client/test/solid-data.test.ts @@ -372,6 +372,91 @@ test("a family member without status keeps the status already known", async () = } }) +test("reads families from servers without the family route, once per connection", async () => { + const older = ({ status: _, ...info }: SessionInfo) => info + const setup = sessionFixture((path, url) => { + if (path.endsWith("/family")) return new Response(null, { status: 404 }) + if (path === "/api/session/active") return Response.json({ data: { ses_a: { type: "running" } } }) + const id = path.match(/^\/api\/session\/([^/]+)$/)?.[1] + if (id) return Response.json({ data: older(member(id, id === "ses_root" ? undefined : "ses_root")) }) + if (path === "/api/session") + return Response.json({ + data: + url.searchParams.get("parentID") === "ses_root" + ? [older(member("ses_a", "ses_root")), older(member("ses_b", "ses_root"))] + : [], + cursor: {}, + }) + if (path === "/api/session/ses_a/permission") return Response.json({ data: [permission("per_a", "ses_a")] }) + if (path === "/api/session/ses_b/permission") + return Response.json( + { _tag: "LocationNotFoundError", location: { directory: "/gone" }, message: "Location not found" }, + { status: 404 }, + ) + if (path === "/api/session/ses_grandchild/permission") + return Response.json({ data: [permission("per_grandchild", "ses_grandchild")] }) + if (path === "/api/session/ses_b/form") return Response.json({ data: [form("frm_b", "ses_b")] }) + if (path.endsWith("/permission") || path.endsWith("/form")) return Response.json({ data: [] }) + if (path === "/api/project") return Response.json([]) + if (path === "/api/location") return Response.json({ directory: "/project" }) + return Response.json({ location: { directory: "/project" }, data: { branch: "main" } }) + }) + const familyReads = () => setup.requests.filter((path) => path.endsWith("/family")) + + try { + setup.data.session.remember(member("ses_known", "ses_root")) + // Beyond the direct children the fallback lists, so only the family index knows it. + setup.data.session.remember(member("ses_grandchild", "ses_known")) + setup.emit(sessionEvent("session.execution.started", { sessionID: "ses_b" })) + await setup.data.session.sync("ses_root", { children: true }) + + expect(setup.data.session.family("ses_root").toSorted()).toEqual([ + "ses_a", + "ses_b", + "ses_grandchild", + "ses_known", + "ses_root", + ]) + // Only the requested Session's pending requests are awaited; the other members' load in the background. + await wait(() => setup.data.session.permission.list("ses_grandchild")?.[0]?.id === "per_grandchild") + await wait(() => setup.data.session.form.list("ses_b")?.[0]?.id === "frm_b") + expect(setup.data.session.permission.list("ses_a")?.map((request) => request.id)).toEqual(["per_a"]) + expect(setup.data.session.status("ses_b")).toBe("running") + + await setup.data.session.sync("ses_a", { children: true }) + expect(familyReads()).toEqual(["/api/experimental/session/ses_root/family"]) + + setup.emit({ type: "server.connected", data: {} }) + await wait(() => setup.data.session.status("ses_a") === "running") + await setup.data.session.sync("ses_b", { children: true }) + expect(familyReads()).toEqual([ + "/api/experimental/session/ses_root/family", + "/api/experimental/session/ses_b/family", + ]) + expect(setup.data.session.status("ses_a")).toBe("running") + } finally { + setup.dispose() + } +}) + +test("a missing Session on the family route rejects without falling back", async () => { + const setup = sessionFixture(() => + Response.json( + { _tag: "SessionNotFoundError", sessionID: "ses_gone", message: "Session not found" }, + { status: 404 }, + ), + ) + + try { + await expect(setup.data.session.sync("ses_gone", { children: true })).rejects.toMatchObject({ + _tag: "SessionNotFoundError", + }) + expect(setup.requests).toEqual(["/api/experimental/session/ses_gone/family"]) + } finally { + setup.dispose() + } +}) + test("events recorded during a family read survive its response", async () => { const release = Promise.withResolvers() const setup = sessionFixture(async (path) => { @@ -1662,15 +1747,15 @@ function activityFixture(read: () => Response | Promise, family?: Sess }) } -function sessionFixture(respond: (path: string) => Response | Promise) { +function sessionFixture(respond: (path: string, url: URL) => Response | Promise) { const listeners = new Set[0]>() const requests: string[] = [] const api = OpenCode.make({ baseUrl: "http://opencode.local", fetch: async (input, init) => { - const path = new URL((input instanceof Request ? input : new Request(input, init)).url).pathname - requests.push(path) - return respond(path) + const url = new URL((input instanceof Request ? input : new Request(input, init)).url) + requests.push(url.pathname) + return respond(url.pathname, url) }, }) return createRoot((dispose) => ({ diff --git a/packages/tui/test/completion-notices.test.tsx b/packages/tui/test/completion-notices.test.tsx index fd142e8ac14..efd99f63027 100644 --- a/packages/tui/test/completion-notices.test.tsx +++ b/packages/tui/test/completion-notices.test.tsx @@ -212,3 +212,59 @@ test.each([40, 120])("subagent completion notices navigate to the child session await server.stop() } }) + +test("a root session opens with its subagent's pending permission on a server without the family route", async () => { + await using state = await tmpdir() + const setup = await createTestRenderer({ width: 120, height: 30, kittyKeyboard: true }) + await setup.renderer.setupTerminal() + setup.renderer.start() + const parent = { + id: "ses_parent", + title: "Parent session", + projectID: "project", + location: { directory }, + cost: 0, + tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } }, + time: { created: 0, updated: 0 }, + } + const child = { ...parent, id: "ses_child", title: "Diagnose authentication", parentID: parent.id } + const requests: string[] = [] + // An older server: no family route, so the client reads the Session, its children, and each member's requests. + const calls = createFetch((url) => { + requests.push(url.pathname) + if (url.pathname.endsWith("/family")) return new Response(null, { status: 404 }) + if (url.pathname === "/api/session") return json({ data: [child], cursor: {} }) + if (url.pathname === `/api/session/${parent.id}`) return json({ data: parent }) + if (url.pathname === `/api/session/${child.id}/permission`) + return json({ data: [{ id: "per_child", sessionID: child.id, action: "bash", resources: ["rm -rf build"] }] }) + if (url.pathname.endsWith("/message")) return json({ data: [], cursor: {} }) + if (url.pathname.endsWith("/inbox") || url.pathname.endsWith("/permission")) return json({ data: [] }) + return undefined + }, createEventStream()) + const server = Bun.serve({ port: 0, idleTimeout: 0, fetch: (request) => calls.fetch(request) }) + const { run } = await import("../src/app") + const task = Effect.runPromise( + run({ + app: { name: "test", version: "test", channel: "test" }, + server: { endpoint: { url: server.url.toString() } }, + config: { + get: async () => ({ animations: false, tabs: { mode: "off" } }), + update: async () => ({}), + }, + packages: { prepare: async () => ({ directory: "" }) }, + args: { sessionID: parent.id }, + terminalHandoff: async () => ({ renderer: setup.renderer, mode: "dark", complete: () => {} }), + log: () => {}, + }).pipe(Effect.provide(Global.layerWith({ state: state.path })), Effect.provide(FileSystem.layerNoop({}))), + ) + try { + // The prompt shows only for members of the route's family, so it also proves the subagent joined it. + await setup.waitForFrame((frame) => frame.includes("Permission required")) + expect(requests).toContain(`/api/experimental/session/${parent.id}/family`) + expect(requests).toContain(`/api/session/${child.id}/permission`) + } finally { + setup.renderer.destroy() + await task + await server.stop() + } +}) diff --git a/specs/v2/session-family-api.md b/specs/v2/session-family-api.md index 79a1f2da99b..4044d0616de 100644 --- a/specs/v2/session-family-api.md +++ b/specs/v2/session-family-api.md @@ -177,7 +177,11 @@ A client must not discard a `session.created` event because the parent has not l ## Compatibility -`Session.Info.status` and the family endpoint are additive for existing clients. The TypeScript clients are regenerated from the assembled `HttpApi`. The reverse holds too: `status` and `rootID` are optional in the contract, so a newer Effect client, which decodes responses, accepts Sessions and `/session/active` entries from an older server that sends neither. The desktop browser pane is the one in-repo Effect client that can reach a server of another version. The Promise client used by the TUI and CLI does not decode responses. App and desktop exports, which assemble the transcript from `session.get`, drop `status` too. The iOS app decodes Sessions with hand-written Swift payloads, which ignore keys they do not know. Plugins receive `status` from Core's facade. Session export and import keep their status-less shape, and `rootID` on `/session/active` entries is a new field the iOS app already ignores alongside `type`. +Both directions are supported. `Session.Info.status` and the family endpoint are additive for existing clients. The TypeScript clients are regenerated from the assembled `HttpApi`. + +A newer client also works against an older server. `status` and `rootID` are optional in the contract, so a newer Effect client, which decodes responses, accepts Sessions and `/session/active` entries from a server that sends neither. The shared data layer learns once per connection whether the server has the family route. An older server answers it with an empty `404`, while a missing Session is a `404` with a `SessionNotFoundError` body, which still rejects. The client treats any declared error status without a readable JSON body as a missing route; a non-JSON `400` or `401`, or a proxy page, would match too, and the fallback reads then fail the same way. After the first such answer the data layer falls back for the rest of the connection, and every reconnect tries the route again. The fallback reads the Session and its direct children, paged, and merges them into the membership already known. It then reads pending permissions and forms for every known member of the family, waiting only for the requested Session's and ignoring per-member failures. Status comes only from `/session/active` and execution events. Delete the fallback once the oldest supported server has the family route. + +The desktop browser pane is the one in-repo Effect client that can reach a server of another version. The Promise client used by the TUI and CLI does not decode responses. App and desktop exports, which assemble the transcript from `session.get`, drop `status` too. The iOS app decodes Sessions with hand-written Swift payloads, which ignore keys they do not know. Plugins receive `status` from Core's facade. Session export and import keep their status-less shape, and `rootID` on `/session/active` entries is a new field the iOS app already ignores alongside `type`. Two behaviors change. `session.permission.list` returns `[]` instead of `LocationNotFoundError` for a Session whose directory is gone and no longer starts an idle Location, as `session.form.list` already does. Both stop waiting on a Location that is still starting. No current client relies on the old behavior. The TUI discards those failures, and the iOS app never calls these endpoints. `mini` retries each failed child on its own timer, backing off from 50 ms to a 2-second cap and never giving up, and every hydration, including each reconnect, reads pending requests for up to 100 children. By that code, a `mini` view of `BURROW` sends 31 failing permission reads every 2 seconds for as long as it stays open; before #59083 fixed forms it was 62. I have not run `mini` against `BURROW` to observe it.