@intentic/sandbox-contract 1.232.0 → 1.234.0

package/src/schemas/share.ts

@@ -0,0 +1,71 @@
+// share: a conversation published as a page
+import { z } from "zod";
+/* The outbox holds FILES; a conversation is not one, so sharing it means RENDERING it into one. The result is
+ * an ordinary published page under the same `public-<slot>` hostname, with the same guards in front of it,
+ * which is the whole reason this rides the outbox rather than inventing a second public surface with its own
+ * auth story to get wrong.
+ *
+ * A share is a SNAPSHOT, not a window. The page holds the conversation as it read at the moment of sharing and
+ * does not move again until the owner re-takes it, because the alternative, a link that keeps publishing
+ * whatever is said next, makes every later turn a disclosure the user did not consciously make. `sharedAt`
+ * is therefore relied on by the row: it dates what the recipient can actually see. */
+
+/* HOW MUCH OF A CONVERSATION TRAVELS, decided per share rather than by a setting, because the two answers suit
+ * genuinely different acts. `messages` is the two speakers' words and nothing else, what you send a friend to
+ * show what the thing said. `everything` adds the agent's work (its tool cards, the diffs of what it edited,
+ * the pictures it took) and its thinking, what you send a colleague to show HOW it got there, and which
+ * necessarily publishes the code and command output that appear in those cards.
+ *
+ * Two levels, not a set of switches: every extra toggle is another thing to get wrong about a link that cannot
+ * be recalled once sent, and the honest distinction here is between "the conversation" and "the record". */
+export const ShareDetailSchema = z.enum(["messages", "everything"]);
+export type ShareDetail = z.infer<typeof ShareDetailSchema>;
+// One shared conversation, as the Public view lists it.
+export const SharedConversationSchema = z.object({
+    /* The share's own id, and the name its page is filed under in the outbox. NOT the conversation's id: that
+     * one is a memorable pair (`swift-otter-k9m2`, see conversation-ids.ts) chosen to be guessable BY A HUMAN
+     * at a glance, which is the opposite of what should name a page whose only protection is that its address
+     * is not enumerable. Minted per share, so re-sharing the same conversation twice yields two links. */
+    id: z
+        .string()
+        .describe(
+            "The share's own id, minted fresh each time, so sharing one conversation twice gives two links. Deliberately not the conversation's id, which is memorable by design and would make a page's address guessable.",
+        ),
+    // Which conversation the snapshot was taken from, what Update re-reads, and what the chat matches against
+    // to know it already has a share.
+    conversationId: z.string().describe("Which conversation it was taken from."),
+    title: z.string().describe("The title on the page, which is the sharer's choice rather than the conversation's own."),
+    detail: ShareDetailSchema.describe(
+        "How much travels: the two speakers' words alone, or the whole record including the agent's work and thinking, which necessarily publishes the code and command output in it.",
+    ),
+    // When the snapshot was taken (epoch ms). A share is frozen, so this dates what a recipient can see,
+    // not when the conversation happened.
+    sharedAt: z
+        .number()
+        .describe(
+            "When the snapshot was taken, in milliseconds. A share is frozen, so this dates what a recipient can see rather than when the conversation happened.",
+        ),
+    // How many messages the snapshot holds, so a row can say how much is behind the link without opening it.
+    messages: z.number().describe("How many messages are behind the link."),
+    // The page's public URL. Absent on a sandbox with no tunnel, which has nowhere to publish to, the same
+    // rule (and the same cause) as PublicFile.url.
+    url: z.string().optional().describe("The page's address. Absent on a sandbox with nowhere to publish to."),
+});
+export type SharedConversation = z.infer<typeof SharedConversationSchema>;
+export const ShareListSchema = z.object({ shares: z.array(SharedConversationSchema).describe("Every conversation currently published as a page.") });
+export type ShareList = z.infer<typeof ShareListSchema>;
+// The title is the sharer's, not the conversation's: the chat's own name is only the default the dialog opens
+// with. Bounded at the registry's title budget (title.ts MAX_LENGTH) so one surface can't store what the others
+// truncate away.
+export const ShareCreateSchema = z.object({
+    conversationId: z.string().min(1).describe("Which conversation to publish."),
+    title: z.string().min(1).max(80).describe("The title for the page. The conversation's own name is only what a dialog would open with."),
+    detail: ShareDetailSchema.describe(
+        "How much to publish. Two levels rather than a set of switches, because every extra toggle is another thing to get wrong about a link that cannot be recalled.",
+    ),
+});
+// Re-take an existing share's snapshot, keeping its id, and therefore its link, which has already been sent.
+export const ShareUpdateSchema = z.object({
+    id: z.string().min(1).describe("Which share to re-take. Its link stays the same, which matters because it has already been sent."),
+});
+export const ShareRemoveSchema = z.object({ id: z.string().min(1).describe("Which share to take down.") });

package/src/schemas/shared.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+// Success ack for routes that only report completion (push / disconnect / self-host register). A turn paused on
+// a plan/question that no longer exists, or a missing repo/path, is an ORPCError thrown by the handler instead.
+export const OkSchema = z.object({
+    ok: z
+        .literal(true)
+        .describe("Always true. A route that answers this either did the thing or refused with a status; there is no third outcome to report."),
+});
+// The trust tiers of everyone who can open this sandbox, ordered. `owner` is the one bound identity
+// (auth/auth.ts); the other three are granted per email on the daemon's /members list. viewer watches,
+// collaborator drives agents (outward actions become requests), maintainer has the owner's operating authority
+// while remaining revokable. Ownership itself is not a grant and controls the access roster.
+export const MemberRoleSchema = z.enum(["viewer", "collaborator", "maintainer", "owner"]);
+export type MemberRole = z.infer<typeof MemberRoleSchema>;
+// The roles an invite can grant, everything but `owner`, which is bound at first sign-in, never granted.
+export const GrantedRoleSchema = z.enum(["viewer", "collaborator", "maintainer"]);
+export type GrantedRole = z.infer<typeof GrantedRoleSchema>;
+// Shared by every surface that gates on a role (daemon route floors, web affordances) so the order lives in
+// exactly one place.
+const MEMBER_ROLE_RANK: Record<MemberRole, number> = { viewer: 0, collaborator: 1, maintainer: 2, owner: 3 };
+export const roleAtLeast = (role: MemberRole, floor: MemberRole): boolean => MEMBER_ROLE_RANK[role] >= MEMBER_ROLE_RANK[floor];
+// Which repo a git route targets: "root" (the /work workspace repo) or a repo id, the repo's root-relative
+// dir, which may be nested ("clients/foo"; URL-encoded in the path param). Kept as a bare string on the wire
+// (not an enum) so an unknown repo is a handler-thrown NOT_FOUND, matching the daemon's prior 404, rather
+// than an input-validation rejection.
+export const RepoParamSchema = z.object({
+    repo: z
+        .string()
+        .describe(
+            'Which repository. "root" is the workspace itself; anything else is a repository\'s folder relative to the workspace root, URL-encoded.',
+        ),
+});

package/src/schemas/system.ts

@@ -0,0 +1,156 @@
+import { z } from "zod";
+// version: what this daemon runs (baked). latest/updateAvailable: the daemon compares its version to the
+// latest published `stable` release so the web can offer a non-blocking update (see system/version-check.ts).
+/* Whether an agent runtime can serve a turn right now, probed off the turn path (see the sandbox's
+ * agent/adapter-health.ts). "unknown" is a real answer, a probe that could not run must not read as
+ * "unavailable" and grey out a provider the user can in fact use, so surfaces treat it as
+ * available-but-unverified rather than as a soft no. */
+export const AdapterHealthSchema = z.object({
+    state: z
+        .enum(["ready", "unavailable", "unknown"])
+        .describe(
+            "Whether this runtime can serve a turn. Unknown is a real answer rather than a soft no: a check that could not run must not grey out a provider you can in fact use.",
+        ),
+    // Why it cannot serve, in the user's terms and naming what to do about it. Absent when ready.
+    detail: z.string().optional().describe("Why it cannot, and what to do about it. Absent when it can."),
+    checkedAt: z.number().describe("When it was last checked, in milliseconds."),
+});
+export type AdapterHealthReport = z.infer<typeof AdapterHealthSchema>;
+/* AN UPDATE ALREADY DOWNLOADED AND BUILT, waiting for the restart that applies it.
+ *
+ * An update is one blocking operation but it was never one kind of work: pulling the new image and re-applying
+ * the environment recipe take the overwhelming majority of the wall clock, and the sandbox is up and serving
+ * through both of them. Only the cutover is downtime, and it is seconds.
+ *
+ * The daemon cannot know any of this by itself, it holds no host Docker socket, so `ic sandbox prepare`
+ * tells it, on the machine that runs the container. That is the whole reason this exists: without it, the
+ * update card had to quote the download as if it were an outage, and "a few minutes, this page loses the
+ * sandbox" is a completely different decision from "about half a minute".
+ *
+ * Advisory only, in the strict sense: it decides what a card SAYS and never what gets installed. The swap
+ * re-derives every one of these facts from the host-side record and refuses the fast path if any has drifted. */
+export const StagedUpdateSchema = z.object({
+    // The version the staged image reports about itself. Absent when the image would not say (an older build,
+    // a probe that failed), which reads as "ready, version unknown", never as nothing being ready.
+    version: z.string().optional().describe("What the downloaded build says it is. Absent means ready but unnamed, never that nothing is ready."),
+    // The release channel it was staged FROM, which is not necessarily the one this sandbox follows: preparing
+    // a beta build is not moving onto beta.
+    channel: z
+        .string()
+        .describe(
+            "Which channel it was taken from. Not necessarily the one this sandbox follows: downloading a beta build is not the same as moving onto beta.",
+        ),
+    // When it finished downloading, epoch ms, what answers "is this still the update I am being offered?"
+    at: z.number().describe("When the download finished, in milliseconds, which answers whether this is still the update being offered."),
+});
+export type StagedUpdate = z.infer<typeof StagedUpdateSchema>;
+export const InfoSchema = z.object({
+    name: z.string().optional().describe("What this sandbox is called."),
+    image: z.string().optional().describe("The image it is running."),
+    version: z.string().optional().describe("The version of that image."),
+    latest: z.string().optional().describe("The newest published version on its channel."),
+    updateAvailable: z.boolean().optional().describe("Whether those two differ."),
+    // Keyed by AgentCapabilities.runtime. Absent until the first background sweep lands, which reads the same
+    // as every entry being "unknown", one of the two cannot go stale, so the daemon sends the absence.
+    runtimes: z
+        .record(z.string(), AdapterHealthSchema)
+        .optional()
+        .describe(
+            "Which agent runtimes can serve a turn right now, keyed by runtime. Absent until the first check has run, which reads the same as every entry being unknown.",
+        ),
+    /* Which release channel this sandbox follows (`stable` unless it was moved), and the base image the last
+     * swap replaced, both set on the container by the host script that performed the swap, since neither is
+     * knowable from inside afterwards. `previousImage` is what a rollback returns to; absent means there is
+     * nothing to go back to and no rollback is offered. */
+    channel: z.string().optional().describe("Which release channel this sandbox follows."),
+    previousImage: z
+        .string()
+        .optional()
+        .describe("The image the last update replaced, which is what a rollback would return to. Absent means there is nothing to go back to."),
+    /* WHAT IS IN THE UPDATE, in the words of the people it is for, the user-facing lines from every release
+     * between `version` and `latest`, newest first (platform/release-notes.ts reads them off the published
+     * GitHub Releases).
+     *
+     * The update card's other half. It could always say an update exists and what taking it costs, recreating
+     * the container interrupts every agent mid-turn, and never what the update was worth, which left the
+     * decision it asks for with nothing on one side of it.
+     *
+     * Absent, or empty, whenever there is nothing to say: the notes cache is cold, GitHub is unreachable, or
+     * every release in the gap changed only things nobody outside the project would notice. All three read the
+     * same way on the card, which shows the offer without them, exactly as it did before. */
+    updateNotes: z
+        .array(z.string())
+        .optional()
+        .describe(
+            "What is in the update, in the words of the people it is for, newest first. Absent or empty whenever there is nothing worth saying, which reads on screen exactly as it did before there were notes at all.",
+        ),
+    // How many further notes the gap holds beyond the ones sent, for a sandbox that has been left alone a long
+    // time. Absent or 0 ⇒ `updateNotes` is the whole of it.
+    moreUpdateNotes: z
+        .number()
+        .optional()
+        .describe(
+            "How many further notes there are beyond the ones sent, for a sandbox left alone a long time. Absent or zero means you have all of them.",
+        ),
+    /* WHAT THE UPDATE TAKES AWAY, the "Breaking changes" lines from every release in the same gap, uncapped
+     * (a warning that fell off a truncated list is a breaking update taken unwarned). Their presence is what
+     * turns the update card from an offer into a warning that asks to be read before it hands over the
+     * command. Absent for the overwhelming majority of updates, which break nothing. */
+    breakingNotes: z
+        .array(z.string())
+        .optional()
+        .describe(
+            "What the update takes away, uncapped, because a warning that fell off a shortened list is a breaking update taken unwarned. Absent for the overwhelming majority, which break nothing.",
+        ),
+    /* AN UPDATE THAT HAS ALREADY BEEN DOWNLOADED AND BUILT on the machine that runs this container, and is
+     * waiting for the restart that applies it. Absent for the ordinary case where nothing is staged. */
+    staged: StagedUpdateSchema.optional().describe(
+        "An update already downloaded and built on the machine running this container, waiting only for the restart that applies it. That restart is seconds, where an unprepared update is minutes, which is a different decision entirely. Absent when nothing is waiting.",
+    ),
+});
+export type Info = z.infer<typeof InfoSchema>;
+/* WHAT THE DAEMON COULD NOT READ IN ITS OWN STATE FILES.
+ *
+ * Every manifest under `.intentic/` is read through a schema and falls back when that schema says no, which
+ * keeps the daemon up and, until this route, ended there. A settings file with one bad character read as
+ * every setting at its default, a misspelled flag was stripped in silence, and a skipped capability said so
+ * only in the daemon log. All three look identical from a browser: the feature is simply off.
+ *
+ * `kind` is what to do about it, which is why it is not just a message:
+ *   unreadable  , the whole file is being ignored. Everything in it is at its default.
+ *   unknownKey  , one key this build does not know. Only that key is ignored, and `suggestion` carries the
+ *                  name it was probably meant to be, when one is close enough to guess honestly.
+ *   invalidEntry, one entry of a list was skipped. The rest of the file is unaffected.
+ *
+ * Reported per file rather than as one flat list because the file is the unit a person fixes, and only for the
+ * files a person CAN fix (REPORTED_MANIFEST_PATHS in workspace-state.ts). A daemon-written ledger that stops
+ * matching a tightened schema is not a repair job to hand the owner; it recovers on its own next write. */
+export const ManifestProblemSchema = z.object({
+    kind: z
+        .enum(["unreadable", "unknownKey", "invalidEntry"])
+        .describe(
+            "What to do about it. Unreadable means the whole file is being ignored and everything in it is at its default. An unknown key means only that key is ignored. An invalid entry means one item of a list was skipped and the rest is fine.",
+        ),
+    detail: z.string().describe("What exactly was wrong."),
+    suggestion: z.string().optional().describe("The name it was probably meant to be, when one is close enough to guess honestly."),
+});
+export type ManifestProblem = z.infer<typeof ManifestProblemSchema>;
+// Workspace-relative path (`.intentic/config/settings.json`) and everything currently wrong with that file. A file
+// with nothing wrong is absent from the list rather than present and empty.
+export const ManifestProblemReportSchema = z.object({
+    path: z.string().describe("The file, as a workspace path. The file is the unit somebody fixes, which is why problems are grouped by it."),
+    problems: z
+        .array(ManifestProblemSchema)
+        .describe("Everything currently wrong with it. A file with nothing wrong is absent rather than present and empty."),
+});
+export type ManifestProblemReport = z.infer<typeof ManifestProblemReportSchema>;
+export const ManifestProblemsSchema = z.array(ManifestProblemReportSchema);
+// A daemon-minted session (system.session): the steady-state browser credential, exchanged for a verified
+// Google ID token so Google UI is a sign-in moment instead of an hourly renewal. `expiresAt` is epoch ms,
+// the browser renews ahead of it without parsing the token; `email` is who the daemon verified.
+export const DaemonSessionSchema = z.object({
+    token: z.string().describe("The credential every other call carries. Present it as a bearer token."),
+    expiresAt: z.number().describe("When it stops working, in milliseconds, so a caller can renew ahead of it without reading the token."),
+    email: z.string().describe("Who the sandbox verified you as."),
+});
+export type DaemonSession = z.infer<typeof DaemonSessionSchema>;

package/src/schemas/terminal.ts

@@ -0,0 +1,288 @@
+import { z } from "zod";
+// EVERY live surface in the sandbox the web app's ONE global panel can show. Mostly tmux sessions (the
+// interactive I/O is the /system/terminal WebSocket, not oRPC), plus the agent's browser, which is not a
+// terminal at all, no more than a `process` row is, but IS the same question: what is running right now,
+// and can I look at it? One list, because the panel that answers that question is one panel.
+//
+// `shell` = a web-* session the user opened (numbered pill),
+// `panel` = a panel-* dev-server session (labeled by its panel key, started via Start; running:false =
+// untracked, e.g. a finished one-shot job's lingering shell), `agent` = an agent-* session the Claude agent's
+// Bash commands run in (live-watchable, AI-marked in the UI; running:false once every window is a finished
+// command's dead pane, which is what lets the panel sweep it), `job` = a job-* session the daemon's terminal
+// runner executes user-triggered flows in (capability adds, infra check), `process` = a managed background
+// process: a supervised daemon child for an extension's declared processes (name `svc-<key>`, whose
+// "terminal" is a tail of the service's log file), or a tmux-riding one for dockerd and the local model
+// servers, which outlive daemon restarts on purpose. Surfaced in the panel's background-processes popover
+// with read-only log views, never as a killable tab; running is the actual process. A process row that maps
+// to an installed extension's declared process carries extensionId+processName, the address for its
+// /extensions start/stop routes. The
+// `{name}` kill-route param is a bare string validated in the handler (a bad name is a BAD_REQUEST) since the
+// same charset gates a `tmux kill-session -t` shell-out. The agent's BROWSER is deliberately NOT one of these
+// kinds: a Chromium with its own tab strip is a surface in its own right, not a pane in the terminal panel, so
+// it lists from /system/browsers with the pages it has open (BrowserSessionSchema below).
+//
+// `activityAt` (epoch ms of the session's last output) and `exitCode` (the LAST window's exit status, absent
+// while that pane still lives) describe a session beyond "it exists": the panel's work popover orders its live
+// rows by the one and dates them off it, and the daemon's retention sweep ages sessions out by the same clock.
+// 0 is "tmux didn't say", treated as unknown by both, never as 1970.
+export const TerminalSessionSchema = z.object({
+    name: z.string().describe("Its id, and what the close route takes."),
+    label: z.string().optional().describe("What to call it on screen."),
+    kind: z
+        .enum(["shell", "panel", "agent", "job", "process"])
+        .describe(
+            "What sort of thing it is: a terminal somebody opened, a repository's dev server, where an agent's commands run, a job the sandbox started, or a background process that is watched rather than typed into.",
+        ),
+    running: z
+        .boolean()
+        .describe("Whether it is alive. A finished one-shot job leaves a dead shell behind, which reads as false and is how it gets swept up."),
+    activityAt: z.number().describe("When it last produced output, in milliseconds. Zero means it did not say, which is unknown rather than 1970."),
+    exitCode: z.number().optional().describe("How the last thing in it ended. Absent while that pane is still alive."),
+    /* WHAT THIS SESSION IS RUNNING RIGHT NOW, `pane_current_command` of its live pane, and ABSENT when it is
+     * sitting at its shell prompt. Not a second spelling of `running`: that field says whether a session is a
+     * live thing at all (and for a `web-*` shell it is unconditionally true, prompt or build), whereas this one
+     * says whether anything is HAPPENING in it. Killing a terminal is final, so the panel confirms on this
+     * field before its × ends a session that has work in it, and names the command in the question, see the
+     * daemon's `foreground` (system/system.routes.ts) for why a word rather than a flag. */
+    command: z
+        .string()
+        .optional()
+        .describe(
+            "What is running in it right now. Absent when it is sitting at a prompt. Not a second spelling of whether it is alive: this says whether anything is happening, which is what a close button should ask about before it ends something.",
+        ),
+    extensionId: z.string().optional().describe("Which extension declared this process, when one did."),
+    processName: z
+        .string()
+        .optional()
+        .describe("Which of that extension's processes it is, which together with the id above addresses its start and stop routes."),
+    // The agent has parked on a command that stopped for a PERSON, an OTP prompt, a security-key touch, a
+    // confirm it cannot answer, and is waiting at this session's live pane. `message` is its own account of
+    // what it needs. The terminal panel renders it as a banner over that session's tab (where the prompt the
+    // user has to answer already is) and its buttons settle the parked card through `POST /agent/reply` with
+    // `requestId`, exactly as the chat card does. The same shape as a browser's `help` below, on purpose: the
+    // two handovers differ in WHERE the person acts, not in what is being asked. Present only while open.
+    help: z
+        .object({
+            requestId: z.string().describe("What to send back when you answer, through the agent reply route."),
+            message: z.string().describe("What the agent needs, in its own words."),
+            requestedAt: z.number().describe("When it asked, in milliseconds."),
+        })
+        .optional()
+        .describe("The agent has stopped at something only a person can clear, and is waiting at this terminal. Present only while it is waiting."),
+});
+export const TerminalsListSchema = z.object({
+    sessions: z
+        .array(TerminalSessionSchema)
+        .describe("Every live surface the sandbox is holding, in one list, because the question they all answer is the same one."),
+});
+export type TerminalsList = z.infer<typeof TerminalsListSchema>;
+export const TerminalNameParamSchema = z.object({ name: z.string().describe("Which terminal.") });
+// One session's PANE HISTORY as plain text. This route exists because the browser cannot reach it any other
+// way: a tmux client runs on the ALTERNATE screen, which has no scrollback of its own, so what the wheel moves
+// through lives in tmux on the far side of the socket and never enters the xterm buffer the page could select.
+// `lines` is how far back to ask for, tmux clamps it to the history it actually has, and `truncated` says the
+// answer stopped at the request rather than at the beginning.
+export const TerminalScrollbackQuerySchema = z.object({
+    name: z.string().describe("Which terminal."),
+    lines: z.coerce.number().min(1).max(100_000).default(20_000).describe("How far back to ask for. Clamped to the history that actually exists."),
+});
+export const TerminalScrollbackSchema = z.object({
+    name: z.string().describe("Which terminal this is from."),
+    // Oldest line first, wrapped lines rejoined so a copied URL or path comes back whole.
+    text: z.string().describe("The history, oldest line first, with wrapped lines rejoined so a copied address or path comes back whole."),
+    lines: z.number().describe("How many lines you got."),
+    truncated: z.boolean().describe("It stopped because you asked for that many, not because the history ran out."),
+});
+export type TerminalScrollback = z.infer<typeof TerminalScrollbackSchema>;
+/* ---- browsers: the Chromium the agent drives through its @playwright/mcp tools ----
+ *
+ * A `browser-<sdk session>` Chromium (browser/browser-sessions.ts), watchable live over the
+ * /system/browser-view WebSocket. It lists apart from the terminals because it is shaped differently in the one
+ * way that decides a UI: a terminal is ONE stream of bytes, while a browser holds SEVERAL pages at once and the
+ * question "what is the agent looking at?" only has an answer if the wire carries all of them. So `pages` is the
+ * point of this schema, the view renders them as a tab strip and binds the screencast to whichever the user
+ * picks, and `active` is the one the agent itself last touched (what the view follows until the user says
+ * otherwise).
+ *
+ * `id` is opaque and minted per session, and it is what makes a tab survive a relist: it is stable for the life
+ * of the page, unlike its url (the agent navigates away) or its position (a closed tab renumbers the rest). */
+export const BrowserPageSchema = z.object({
+    id: z
+        .string()
+        .describe(
+            "Stable for the life of the page, which is what lets a tab survive a refresh of this list. Its address changes as the agent navigates and its position changes when a sibling closes.",
+        ),
+    // The page's own title. Absent mid-navigation, which is exactly when a tab still needs to render.
+    title: z.string().optional().describe("The page's title. Absent mid-navigation, which is exactly when a tab still has to be drawn."),
+    url: z.string().describe("Where it is."),
+    // The page the agent last drove, on a finished session, the one it ended on. Exactly one page has it.
+    active: z.boolean().describe("The one the agent last touched, or for a finished session, the one it ended on. Exactly one page has this."),
+});
+export const BrowserSessionSchema = z.object({
+    name: z.string().describe("Its id, and what the close route takes."),
+    // The pill's text: the active page's title, else its host, else which browser this is.
+    label: z.string().describe("What to call it on screen: the open page's title, or its site, or which browser this is."),
+    // Which MCP server drives it: `web` (the credential-free browser) or a logged-in capability's id, the
+    // difference between a throwaway page and one signed in as the user, which is worth saying out loud.
+    server: z
+        .string()
+        .describe(
+            "Which browser drives it: the credential-free one, or a signed-in account's. The difference between a throwaway page and one logged in as you, which is worth saying out loud.",
+        ),
+    // False once that Chromium is gone (the turn ended, the agent closed it, it crashed). A finished session
+    // still lists for a while, with the pages it had, the record of where the agent went.
+    running: z
+        .boolean()
+        .describe("Whether it is still open. A closed one is listed for a while with the pages it had, as the record of where the agent went."),
+    activityAt: z.number().describe("When it last did anything, in milliseconds."),
+    // When that Chromium went away, for the "closed 20m ago" line a finished session leads with. Absent while
+    // running, which is the same fact as `running`, but the view needs the timestamp, not just the flag.
+    finishedAt: z.number().optional().describe("When it closed, in milliseconds. Absent while it is open."),
+    // The agent has hit something only a person can clear (a captcha, a password it does not hold, a phone
+    // check) and is PARKED on it: `message` is its own account of what it needs, in the user's language. The
+    // Browsers view renders it as a banner over the live stage, where "Take control" already is, and its
+    // buttons settle the parked card through `POST /agent/reply` with `requestId`, exactly as the chat card
+    // does; the field clears when the waiter settles, never by direct edit. Present only while open.
+    help: z
+        .object({
+            requestId: z.string().describe("What to send back when you answer, through the agent reply route."),
+            message: z.string().describe("What the agent needs, in its own words."),
+            requestedAt: z.number().describe("When it asked, in milliseconds."),
+        })
+        .optional()
+        .describe(
+            "The agent has hit something only a person can clear: a captcha, a password it does not hold, a check on your phone. Present only while it is waiting.",
+        ),
+    pages: z
+        .array(BrowserPageSchema)
+        .describe("Every page it has open. A browser holds several at once, which is the reason it is listed apart from the terminals."),
+});
+export type BrowserPage = z.infer<typeof BrowserPageSchema>;
+export type BrowserSession = z.infer<typeof BrowserSessionSchema>;
+export const BrowsersListSchema = z.object({
+    sessions: z.array(BrowserSessionSchema).describe("Every browser the agents have running, open or recently closed."),
+});
+export type BrowsersList = z.infer<typeof BrowsersListSchema>;
+export const BrowserNameParamSchema = z.object({ name: z.string().describe("Which browser.") });
+/* ---- subagents: the agents an agent starts ----
+ *
+ * The third thing a turn spawns that the operator can be shown, after its shell and its browser, and the only
+ * one that is itself an agent. Two kinds land in this one list, because from outside they are the same fact
+ * (another agent, working, that you did not start):
+ *   • `subagent`, the SDK's Agent/Task tool. The daemon learns of it from the SubagentStart/SubagentStop hooks
+ *     and the task_* stream messages, joined on `toolUseId`.
+ *   • `spawned`, a full agent the turn started through the daemon's own spawn door (children/children.ts), on
+ *     ANY connected provider, Cursor's Composer, Codex, Gemini, another Claude. The daemon runs the child
+ *     itself, so its whole life is reported by direct calls rather than reconstructed from hooks or stdout.
+ *
+ * `id` IS THE SPAWNING TOOL CALL'S id for an SDK child (the one key its meta file, its task messages and the
+ * client's `parentToolUseId` nesting all carry), and the child's own conversation id for a `spawned` one (the
+ * spawn door returns it, so both sides hold it). A card links to its subagent with the id it has, and the
+ * subagent points back at the card the same way. The ids the transcripts are actually READ with, the SDK's
+ * agent id, stay daemon-side, because no surface asks a question they answer.
+ *
+ * WHAT A KIND CHANGES, and it is only ever the live view: an SDK subagent has no process of its own to look
+ * at, so watching it means reading its transcript; a spawned child is a conversation of its own, so its live
+ * view is that conversation's stream. */
+export const SubagentKindSchema = z.enum(["subagent", "spawned"]);
+export type SubagentKind = z.infer<typeof SubagentKindSchema>;
+// running/pending/blocked are live; the rest are terminal. Deliberately the SDK's own task vocabulary
+// (SDKTaskUpdatedMessage.patch.status) rather than AgentStatus: this is not a fleet card's lifecycle (no
+// draft/landed/conflict), and mapping the two would invent states neither side reports. `blocked` is the one
+// addition the SDK never says: a spawned child's own question/permission/plan card raises it
+// (children/children.ts), and it exists because "the child needs an answer" is the one live state a parent or
+// an operator acts on differently from "the child is working".
+export const SubagentStatusSchema = z.enum(["pending", "running", "blocked", "completed", "failed", "killed", "paused"]);
+export type SubagentStatus = z.infer<typeof SubagentStatusSchema>;
+/* WHETHER ANYTHING CHECKED WHAT THE HELPER DID, carried beside its report rather than left for the reader to
+ * assume. Computed from the helper's own tool calls, the files it edited against the checks that ran after
+ * them (the daemon's child-verification.ts), so it holds on every provider rather than only where the Claude
+ * hooks reach.
+ *
+ * The four states are deliberately not two. `verified` and `failing` each name the command that spoke, so a
+ * targeted test is never read as the suite; `unproven` is the one that matters most, work changed and nothing
+ * ran; and `no-code` says the helper edited nothing, which is the honest answer for a research helper and
+ * must not be rendered as approval. Absent ⇒ the daemon saw no tool calls from it at all. */
+export const SubagentVerificationSchema = z.object({
+    state: z
+        .enum(["verified", "unproven", "failing", "no-code"])
+        .describe(
+            "Whether anything proved its work: a check passed after its last edit, it changed code and nothing checked it, a check ran and failed, or it changed no code at all.",
+        ),
+    paths: z.array(z.string()).optional().describe("The code files it changed, most recent last. The first few; the record holds the rest."),
+    check: z
+        .string()
+        .optional()
+        .describe(
+            "The command that spoke: the one that cleared it, or the one that failed. Named rather than summarised, so a targeted test is not read as the whole suite.",
+        ),
+});
+export type SubagentVerification = z.infer<typeof SubagentVerificationSchema>;
+export const SubagentSessionSchema = z.object({
+    id: z
+        .string()
+        .describe(
+            "The id of the tool call that started it (an SDK child) or the child's own conversation id (a spawned one); either way both sides already hold it, so a card links to its helper with the id it has and the helper points back the same way.",
+        ),
+    kind: SubagentKindSchema.describe(
+        "What sort of helper: one the runtime's own Task tool spawned in-process, or a full agent the daemon started for the turn. It changes only how you watch it.",
+    ),
+    // The conversation whose turn spawned this, what the area groups its rows by, and the way back to the chat
+    // the card lives in.
+    conversationId: z.string().describe("The conversation whose turn started it, and the way back to the chat it belongs to."),
+    // What it is and what it was asked to do: the subagent type (`Explore`, `general-purpose`) or a spawned
+    // child's provider label, and the caller's one-line description. The area's row and the card's title read
+    // as `Explore · Locate claimIndexer definition`.
+    agentType: z.string().optional().describe("What kind of helper it is."),
+    description: z.string().optional().describe("What it was asked to do, in one line."),
+    model: z.string().optional().describe("Which model it runs on."),
+    // Which provider serves a `spawned` child (its AgentProvider id), so the row can wear the right logo. An
+    // SDK subagent implies its own: it runs on its parent's provider.
+    provider: z.string().optional().describe("Which provider serves it, for a helper spawned across providers."),
+    // How deep in the spawn tree (1 = spawned by the turn itself). From the SDK's meta.json; a subagent may
+    // itself delegate, and a flat list that cannot say so reads as though the turn started all of them.
+    spawnDepth: z
+        .number()
+        .optional()
+        .describe(
+            "How deep in the chain it sits, where one means the turn itself started it. A helper can start helpers, and a flat list that could not say so would read as though the turn started all of them.",
+        ),
+    // Backgrounded: the parent went on working instead of waiting for it. This is the whole reason the list
+    // exists, a backgrounded child used to be invisible until its result landed, sometimes minutes later.
+    background: z
+        .boolean()
+        .optional()
+        .describe(
+            "The parent carried on working instead of waiting for it. This is the whole reason the list exists: such a helper used to be invisible until its result landed, sometimes minutes later.",
+        ),
+    status: SubagentStatusSchema.describe(
+        "How it is going. Blocked means it needs an answer, which a parent and an operator act on differently from it simply working.",
+    ),
+    startedAt: z.number().describe("When it started, in milliseconds."),
+    endedAt: z.number().optional().describe("When it finished, in milliseconds. Absent while it works."),
+    activityAt: z.number().describe("When it last did anything, in milliseconds."),
+    // What it has spent and done so far (task_progress). Tokens are the child's own, so a parent's cost line and
+    // the sum of its children's are two different true numbers.
+    tokens: z
+        .number()
+        .optional()
+        .describe("What it has spent. Its own, so a parent's cost and the sum of its helpers' are two different true numbers."),
+    toolUses: z.number().optional().describe("How many tools it has used."),
+    lastTool: z.string().optional().describe("The last one it reached for."),
+    // Its report, the last assistant message (SubagentStop) or the task summary. The answer to "what did it
+    // conclude?" without opening the transcript, which is the question a finished child is read for.
+    summary: z
+        .string()
+        .optional()
+        .describe("Its report: what it concluded, without opening its record. The question a finished helper gets read for."),
+    error: z.string().optional().describe("Why it failed, when it did."),
+    // Whether anything checked the work behind that report (SubagentVerificationSchema). Filled once it ends:
+    // a standing read while it is still working would be a verdict on a job half done.
+    verification: SubagentVerificationSchema.optional().describe("Whether anything proved the work its report describes."),
+});
+export type SubagentSession = z.infer<typeof SubagentSessionSchema>;
+export const SubagentsListSchema = z.object({
+    sessions: z.array(SubagentSessionSchema).describe("Every helper this sandbox's conversations have started."),
+});
+export type SubagentsList = z.infer<typeof SubagentsListSchema>;
+export const SubagentIdParamSchema = z.object({ id: z.string() });