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.
This commit is contained in:
Simon Klee
2026-10-29 08:59:06 +01:00
Unverified
parent 7094aefe1e
commit 977d281d64
4 changed files with 217 additions and 9 deletions
+67 -4
View File
@@ -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<string, DataSessionStatus | undefined> | undefined
// Learned once per connection, since a reconnect may reach an upgraded server.
let familyRouteMissing = false
const pendingUpdates = new Map<string, Map<string, SessionInboxInfo | SessionInbox.Delivery | undefined>>()
// 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<SessionInfo[]> {
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<string, DataSessionStatus | undefined>()
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}`)
+89 -4
View File
@@ -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<void>()
const setup = sessionFixture(async (path) => {
@@ -1662,15 +1747,15 @@ function activityFixture(read: () => Response | Promise<Response>, family?: Sess
})
}
function sessionFixture(respond: (path: string) => Response | Promise<Response>) {
function sessionFixture(respond: (path: string, url: URL) => Response | Promise<Response>) {
const listeners = new Set<Parameters<CreateDataInput["event"]["listen"]>[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) => ({
@@ -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()
}
})
+5 -1
View File
@@ -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.