@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/routes.ts

@@ -1,219 +0,0 @@
-import { z } from "zod";
-
-/* The daemon's route surface, named. A sandbox daemon is baked into an image, so the browser talking to it is
- * routinely NEWER than the daemon: a released app plane serves every user's sandbox, whatever image they last
- * pulled, and in local development the web app is always ahead of the last `pnpm build:sandbox`. Both are
- * normal and neither should force an update.
- *
- * What must not happen is the failure being SILENT. A route the daemon predates answers 404, which the browser
- * has no way to tell apart from "you asked for a file that isn't there", so a missing feature reads as a
- * broken one, and diagnosing it costs an hour of "did the image rebuild?".
- *
- * So the daemon ADVERTISES the routes it implements (the /events hello frame) and the browser compares that
- * against the contract it was itself built with. Everything present on both sides works exactly as before;
- * anything the daemon lacks is a KNOWN, NAMED gap the UI can gate a feature on or explain in an error, instead
- * of a mystery 404. Old daemon + new browser stays fully supported, it just stops being confusing.
- *
- * Route names are `<group>.<route>` (`vpn.list`, `kimi.models`), derived from the contract object both sides
- * import. Nothing is generated and nothing is hand-maintained: adding a route to the contract adds it here.
- *
- * Everything here is a pure function of a contract passed in, index.ts binds them to `sandboxContract` once it
- * is assembled, which is what keeps this module out of an import cycle with it. */
-
-// The shape we read off an oRPC contract procedure. `~orpc.route` is the contract metadata oRPC attaches to
-// every `oc.route(...)` procedure; we only need the wire method + path, so this is deliberately structural
-// rather than an import of oRPC's internal types (which are not part of its public surface).
-interface ContractProcedureLike {
-    readonly "~orpc": { readonly route?: { readonly method?: string; readonly path?: string } };
-}
-
-const procedureRoute = (value: unknown): { method: string; path: string } | undefined => {
-    if (typeof value !== "object" || value === null || !("~orpc" in value)) {
-        return undefined;
-    }
-    const { route } = (value as ContractProcedureLike)["~orpc"];
-    if (route?.method === undefined || route.path === undefined) {
-        return undefined;
-    }
-    return { method: route.method, path: route.path };
-};
-
-// One advertised route: its contract name plus the wire shape, so a concrete request path can be matched back
-// to the name it came from (see routeNameForRequest).
-export interface ContractRoute {
-    readonly name: string;
-    readonly method: string;
-    // The oRPC path template, with `{param}` placeholders, e.g. `/system/terminals/{name}`.
-    readonly path: string;
-}
-
-// Walk a contract object (two levels: group → procedure) into its flat route list, sorted by name so the
-// advertised array is stable and diffable.
-export const contractRoutes = (contract: Record<string, unknown>): ContractRoute[] => {
-    const routes: ContractRoute[] = [];
-    for (const [group, procedures] of Object.entries(contract)) {
-        if (typeof procedures !== "object" || procedures === null) {
-            continue;
-        }
-        for (const [name, procedure] of Object.entries(procedures as Record<string, unknown>)) {
-            const route = procedureRoute(procedure);
-            if (route !== undefined) {
-                routes.push({ name: `${group}.${name}`, method: route.method, path: route.path });
-            }
-        }
-    }
-    return routes.toSorted((a, b) => a.name.localeCompare(b.name));
-};
-
-/* ---- the SHAPE of a route, not just its name ----
- *
- * The route list above answers "does this daemon have it". It cannot answer the other half: a route that
- * exists on BOTH sides but whose payload changed between the two builds. Names match, so the call goes out,
- * and a field the browser expects is simply missing from the answer, no 404, no message, nothing to attribute
- * it to. That is the one skew failure the named-gap mechanism still leaves silent.
- *
- * So each route also advertises a fingerprint of its wire shape: input and output schema together, reduced to
- * one short string. Same string ⇒ the two builds agree, which is the overwhelmingly common case and costs a
- * comparison. Different ⇒ a NAMED route whose payload moved, which the UI can explain in exactly the words it
- * already uses for a missing one.
- *
- * NOTHING IS HAND-MAINTAINED, which is the whole reason this is a fingerprint and not a version number. The
- * codebase already rejected the hand-bumped alternative once (see the web app's buildEpoch.ts: a SCHEMA_VERSION
- * "hangs on someone remembering"). Changing a field in a contract schema changes that route's fingerprint by
- * itself, on both sides, with nobody to remember anything. */
-
-// The schemas oRPC hangs off a contract procedure, read structurally for the same reason as `route` above,
-// they are internal metadata, not part of its public surface.
-interface ContractSchemasLike {
-    readonly "~orpc": { readonly inputSchema?: unknown; readonly outputSchema?: unknown };
-}
-
-/* The JSON Schema keywords whose array value is a SET, order carries no meaning, so two schemas that differ
- * only in it are the same wire shape. `required` is the one that matters in practice: JSON Schema spells an
- * object's fields twice, once as `properties` (an object, so key-sorting settles it) and once as `required`
- * (an array, in declaration order), so without this, moving a field up a `z.object` for readability reads as
- * drift on every route that carries it. The union keywords are here for the same reason a step lower down. */
-const UNORDERED = new Set(["required", "enum", "anyOf", "oneOf", "allOf"]);
-
-/* Canonical JSON: object keys sorted, set-valued arrays sorted, everything else left in the order it was
- * written. So the fingerprint depends on what the schema SAYS rather than how zod happened to emit it, which
- * is what keeps a purely cosmetic edit from being reported to a user as a payload that moved.
- *
- * Ordered arrays stay ordered: a tuple's `prefixItems` is positional, and sorting it would call two genuinely
- * different shapes identical, the failure that actually costs something here. */
-const canonical = (value: unknown, key?: string): unknown => {
-    if (Array.isArray(value)) {
-        const items = value.map((item) => canonical(item));
-        return key !== undefined && UNORDERED.has(key) ? items.toSorted((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))) : items;
-    }
-    if (typeof value !== "object" || value === null) {
-        return value;
-    }
-    const entries = Object.entries(value as Record<string, unknown>).toSorted(([a], [b]) => a.localeCompare(b));
-    return entries.map(([name, nested]) => [name, canonical(nested, name)]);
-};
-
-/* FNV-1a over the canonical JSON, base36. Deliberately not a cryptographic hash: this is a drift SIGNAL, and
- * the cost of a collision is one warning that never appears, never a wrong action, never a blocked call. A
- * crypto digest would mean a subtle-crypto round trip in the browser (async, and unavailable on insecure
- * origins) to buy nothing this use has any need of. */
-const fingerprint = (value: unknown): string => {
-    const text = JSON.stringify(canonical(value));
-    let hash = 0x811c9dc5;
-    for (let i = 0; i < text.length; i++) {
-        hash ^= text.charCodeAt(i);
-        hash = Math.imul(hash, 0x01000193) >>> 0;
-    }
-    return hash.toString(36);
-};
-
-/* One route's wire shape, or undefined when it cannot be expressed.
- *
- * `io` matters and is not cosmetic: a field with `.default()` is OPTIONAL on the way in and REQUIRED on the
- * way out, so reading both sides in the same direction would call two genuinely different shapes identical.
- *
- * A schema that will not convert yields undefined rather than throwing the walk away. Every such route in the
- * contract today is a streaming one, oRPC wraps an event iterator's output in an opaque type with no schema
- * underneath it, and their absence lands them in exactly the right place: a route with no advertised shape is
- * assumed compatible, which is the same "positive evidence only" rule the missing-route check already runs on. */
-const procedureShape = (value: unknown): string | undefined => {
-    if (typeof value !== "object" || value === null || !("~orpc" in value)) {
-        return undefined;
-    }
-    const { inputSchema, outputSchema } = (value as ContractSchemasLike)["~orpc"];
-    try {
-        return fingerprint({
-            in: inputSchema === undefined ? undefined : z.toJSONSchema(inputSchema as z.ZodType, { io: "input" }),
-            out: outputSchema === undefined ? undefined : z.toJSONSchema(outputSchema as z.ZodType, { io: "output" }),
-        });
-    } catch {
-        return undefined;
-    }
-};
-
-// Every route whose shape THIS build can express, as name → fingerprint. Same walk as contractRoutes, and
-// deliberately a separate map rather than a field on ContractRoute: the two are advertised independently
-// (existence covers every route, shape covers the ones that can be expressed) and read by different checks.
-export const routeShapes = (contract: Record<string, unknown>): Record<string, string> => {
-    const shapes: Record<string, string> = {};
-    for (const [group, procedures] of Object.entries(contract)) {
-        if (typeof procedures !== "object" || procedures === null) {
-            continue;
-        }
-        for (const [name, procedure] of Object.entries(procedures as Record<string, unknown>)) {
-            if (procedureRoute(procedure) === undefined) {
-                continue;
-            }
-            const shape = procedureShape(procedure);
-            if (shape !== undefined) {
-                shapes[`${group}.${name}`] = shape;
-            }
-        }
-    }
-    return shapes;
-};
-
-// Does a concrete request path match this route's template? Segment-wise, with `{param}` matching exactly one
-// segment, the same shape oRPC mounts, so a template can never match a longer or shorter path.
-const pathMatches = (template: string, path: string): boolean => {
-    const wanted = template.split("/");
-    const actual = path.split("/");
-    if (wanted.length !== actual.length) {
-        return false;
-    }
-    return wanted.every((segment, index) => (segment.startsWith("{") && segment.endsWith("}") ? actual[index] !== "" : segment === actual[index]));
-};
-
-// The contract route a concrete request belongs to, or undefined when the path is not a contract route at all
-// (the daemon also serves hand-written Hono routes like /health and /workspace/raw, those are never gated).
-// The query string is stripped first; callers pass whatever they handed to fetch.
-export const routeNameForRequest = (routes: readonly ContractRoute[], method: string, pathWithQuery: string): string | undefined => {
-    const path = pathWithQuery.split("?")[0] ?? pathWithQuery;
-    const upper = method.toUpperCase();
-    return routes.find((route) => route.method.toUpperCase() === upper && pathMatches(route.path, path))?.name;
-};
-
-// The route a typed client call belongs to. oRPC addresses a procedure by its position in the contract,
-// `['git','stashApply']`, which is the contract's own name for it, so this is a lookup rather than a match.
-export const routeForProcedure = (routes: readonly ContractRoute[], procedure: readonly string[]): ContractRoute | undefined =>
-    routes.find((route) => route.name === procedure.join("."));
-
-// THE CONCRETE PATH A TYPED CALL WILL CARRY, the route template with every `{param}` replaced by the input
-// field of the same name, which is how the OpenAPI link fills them.
-//
-// This exists so a permission gate can check the string the daemon will actually route on rather than the
-// template it came from. Checking the template would quietly widen every grant: a wildcard glob matches the
-// literal `{repo}` braces just as happily as it matches a repo name, so a manifest that narrowed the grant to
-// one repo would still admit calls for every other, the gate would be comparing two patterns instead of
-// testing a value against one.
-//
-// A param with no matching input field keeps its placeholder. That cannot be reached through the typed client
-// (the contract's input schema requires the field), and leaving the braces in is the safe failure: a glob
-// segment still matches it, a literal segment does not.
-export const requestPathFor = (route: ContractRoute, input: unknown): string => {
-    const fields = typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {};
-    return route.path.replace(/\{([^}]+)\}/g, (placeholder, name: string) => {
-        const value = fields[name];
-        return value === undefined ? placeholder : encodeURIComponent(String(value));
-    });
-};

package/src/runner-protocol.ts

@@ -1,239 +0,0 @@
-import { z } from "zod";
-import { NeedsActionSchema } from "./needs-action.js";
-
-/* THE RUNNER LINK'S EDGES: the handshake on /system/runners/connect, the env a runner boots with, and the
- * placement value a turn request carries. The procedures spoken over the link once it exists live in
- * contracts/runner.contract.ts; the design is docs/remote-runners-plan.md (workspace root).
- *
- * A runner is the sandbox image booted in runner mode: no browser owner, no tunnel, no public name. It dials
- * its PARENT sandbox and executes turns the parent dispatches; the parent keeps owning the conversation. The
- * host link (host-protocol.ts) is the pattern for everything here, one outbound socket that authenticates in
- * its first frame, because a runner sits behind the same NATs and private networks a laptop does. */
-
-// The env the runner container boots with: who to dial, and the single-use pairing that gets it enrolled.
-// Named here so `ic runner up`, the Fly provisioner and the daemon's boot detection spell them identically.
-export const RUNNER_PARENT_URL_ENV = "RUNNER_PARENT_URL";
-export const RUNNER_PAIR_TOKEN_ENV = "RUNNER_PAIR_TOKEN";
-
-/* The first frame on /system/runners/connect, plain JSON, never oRPC, for host-protocol.ts's reason: a socket
- * must prove whose it is before a typed link attaches, and the proof cannot be a call on a link that does not
- * exist yet. The token rides the FRAME, never the URL (edge logs). */
-export const RunnerHelloSchema = z.object({
-    type: z.literal("runner-hello"),
-    // The runner's durable token, redeemed once from the pairing over /system/runners/enroll.
-    token: z.string(),
-    // The daemon build the runner runs, surfaced per runner so an old image is visible rather than
-    // mysteriously wrong.
-    version: z.string(),
-    /* Parity, reported rather than enforced: the parent knows what IT runs (image, channel, overlay hash) and
-     * shows a runner that drifted as "outdated" with a rebuild action. An outdated runner still runs turns, a
-     * stale toolchain is a fact the user can weigh, where a refusal would strand work. */
-    image: z.string(),
-    channel: z.string().optional(),
-    overlayHash: z.string().optional(),
-    /* The runner's DECLARED SHAPE, as the definition format spells it (definition.ts): a sandbox.toml whose
-     * only populated section is settings, because that is all a runner declares — capabilities and secrets
-     * never travel to one, and its repos are a mirror of the parent's git rather than clones with remotes.
-     * The parent diffs this against its own settings to itemize drift (a stale toolchain is a rebuild; a
-     * drifted setting is one applyDefinition call over this same socket), so parity stops being a bare
-     * "outdated" and becomes lines naming what differs. Absent on an image too old to derive one. */
-    definitionToml: z.string().optional(),
-});
-export type RunnerHello = z.infer<typeof RunnerHelloSchema>;
-
-// The URL a runner dials, given its parent's public URL. One builder, so `ic`, the Fly provisioner and the
-// daemon route cannot disagree about where the door is (hostConnectUrl's rule).
-export const runnerConnectUrl = (parentUrl: string): string => `${parentUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/runners/connect`;
-
-// Where a runner redeems its pairing for the durable token, once, over plain HTTPS.
-export const runnerEnrollUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/enroll`;
-
-/* The parent's git door for ONE repository: stock `git fetch`/`git push` against the smart-HTTP pair the
- * parent serves from its real git dirs (<historyRoot>/gits/<encoded id>), authenticated by the runner's own
- * token as a bearer. One builder because three parties spell it: the parent's route, the runner's sync, and
- * anyone debugging with a hand-typed clone. */
-export const runnerGitUrl = (parentUrl: string, repo: string): string =>
-    `${parentUrl.replace(/\/$/, "")}/system/runners/git/${encodeURIComponent(repo)}`;
-
-/* Where a runner's push LANDS in the parent's git dirs. Never refs/heads/agent/<id> directly: that branch is
- * checked out in the parent's mirror worktree, and git itself refuses updating a checked-out ref, which is a
- * safety property worth keeping rather than configuring away. The parent moves the branch by hard-resetting
- * the mirror worktree to this ref, which advances the checked-out branch through the door git sanctions. */
-export const runnerIncomingRef = (conversationId: string): string => `refs/runner-incoming/${conversationId}`;
-
-/* THE CONTAINER A RUNNER'S NAME MEANS on the machine holding it, which is how the update and rebuild flows
- * address it. The prefix is `ic`'s own (runner.rs SLUG_PREFIX) and the two must stay identical: a mismatch
- * does not fail loudly, it sends an update at a container that does not exist and reports "no such sandbox"
- * about a runner sitting right there in the list. */
-export const runnerSlug = (name: string): string => `runner-${name}`;
-
-/* THE CREDENTIAL DOORS: a runner's turns spend the ORIGIN sandbox's model providers, never accounts of their
- * own. The shape is a service, not a sync: the parent resolves each turn's credential with the same code its
- * local turns use and answers with the least that travels — an access token minted for the turn, or a route.
- * Refresh tokens never leave the parent, which is what closes the rotation race two daemons refreshing one
- * account would otherwise run. Design: docs/remote-runners-plan.md §8 (workspace root). */
-export const runnerCredentialsUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/credentials`;
-export const runnerCredentialRefreshUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/credentials/refresh`;
-
-/* The parent's model translator, re-served to runners: subscription-routed turns (codex/grok/kimi under the
- * Claude Code harness, OpenAI-protocol endpoints, the trial) authenticate against a translator whose auth
- * files live on the PARENT's /history. Rather than syncing those (the same rotation race), the runner's
- * harness dials this authenticated proxy and the parent forwards to its loopback translator. The bearer is
- * the runner's own token. */
-export const runnerTranslatorPath = "/system/runners/translator";
-export const runnerTranslatorUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}${runnerTranslatorPath}`;
-
-export const RunnerCredentialRequestSchema = z.object({
-    // The provider as the turn names it (absent = claude), an open vocabulary: endpoint/<id> included.
-    agent: z.string().optional(),
-    account: z.string().optional(),
-    model: z.string().optional(),
-});
-export type RunnerCredentialRequest = z.infer<typeof RunnerCredentialRequestSchema>;
-
-/* What travels back, by kind:
- *   oauth             — a native-Claude access token minted for this turn; `account` present when it is a
- *                       stored account (then the refresh door re-mints mid-turn), absent for the parent's
- *                       container-env fallback, which has nothing to rotate.
- *   parent-translator — run against the parent's translator through the proxy above; the runner supplies its
- *                       own token as the bearer (the parent never echoes a credential it only holds hashed).
- *   endpoint          — a foreign endpoint the runner can dial directly (an anthropic-protocol Endpoint
- *                       capability), with the bearer that endpoint wants.
- * A refusal is a value with the same codes local resolution uses, so the composer's connect gates read a
- * remote refusal exactly as a local one. */
-export const RunnerCredentialSchema = z.union([
-    z.object({ ok: z.literal(true), kind: z.literal("oauth"), accessToken: z.string(), account: z.string().optional() }),
-    z.object({ ok: z.literal(true), kind: z.literal("parent-translator"), model: z.string(), trial: z.boolean().optional() }),
-    z.object({
-        ok: z.literal(true),
-        kind: z.literal("endpoint"),
-        baseUrl: z.string(),
-        authToken: z.string(),
-        model: z.string(),
-        trial: z.boolean().optional(),
-    }),
-    z.object({
-        ok: z.literal(false),
-        code: z.enum(["subscription-required", "claude-reauth", "trial-unavailable"]).optional(),
-        message: z.string(),
-    }),
-]);
-export type RunnerCredential = z.infer<typeof RunnerCredentialSchema>;
-
-export const RunnerCredentialRefreshRequestSchema = z.object({
-    account: z.string().min(1),
-    // The token the harness was refused with, so the parent's rotation supersedes exactly that one and a
-    // token another turn already rotated is adopted, never re-refreshed (claude-credentials' own rule).
-    rejected: z.string().min(1),
-});
-export type RunnerCredentialRefreshRequest = z.infer<typeof RunnerCredentialRefreshRequestSchema>;
-
-// `accessToken` absent ⇒ the parent could not re-mint (a revoked account); the harness gives up exactly as a
-// local turn whose refresh returned nothing does.
-export const RunnerCredentialRefreshSchema = z.object({ accessToken: z.string().optional() });
-export type RunnerCredentialRefresh = z.infer<typeof RunnerCredentialRefreshSchema>;
-
-// What a runner is, hardware-wise: what the placement picker shows and what a future scheduler weighs.
-export const RunnerFactsSchema = z.object({
-    cpus: z.number().int().positive(),
-    memoryMb: z.number().int().positive(),
-    freeDiskMb: z.number().int().nonnegative(),
-    // 0..1 of the last minute, the coarse "is it busy" a picker needs, not a metrics feed.
-    load: z.number().nonnegative(),
-});
-export type RunnerFacts = z.infer<typeof RunnerFactsSchema>;
-
-/* WHETHER IT IS RUNNING WHAT THIS SANDBOX IS RUNNING (§7 of the design): `current` matches on image, channel
- * and approved overlay; `outdated` differs on one of them and gets the update button; `unknown` is a runner
- * that has never connected, or a parent that cannot name its own image (a dev daemon), where a warning would
- * be one nobody can act on. Reported, never enforced: an outdated runner still runs turns. */
-export const RunnerParitySchema = z.enum(["current", "outdated", "unknown"]);
-export type RunnerParity = z.infer<typeof RunnerParitySchema>;
-
-// One runner as the owner's views list it: enrolled state plus whatever the hub knows right now, the
-// HostSummary shape retold for a runner (no platform/scopes, parity instead).
-export const RunnerSummarySchema = z.object({
-    id: z.string(),
-    // The connected device holding it, when this sandbox is what asked for it (the Devices view's create
-    // flow). Absent for one started by hand on a machine, which this sandbox can dispatch to but not manage.
-    host: z.string().optional(),
-    online: z.boolean(),
-    version: z.string().optional(),
-    image: z.string().optional(),
-    channel: z.string().optional(),
-    overlayHash: z.string().optional(),
-    facts: RunnerFactsSchema.optional(),
-    lastSeen: z.number().optional(),
-    // Computed by the daemon (runners/runner-parity.ts) rather than by each surface, so the badge on a row and
-    // the note in the placement picker cannot disagree about the same runner.
-    parity: RunnerParitySchema,
-    /* Where the runner's environment stands against this sandbox's, one line per difference (the definition
-     * surface's drift unit, computed parent-side from the hello's definitionToml plus the overlay hashes).
-     * Absent when the runner never said, empty when they agree. Lines whose subject is a Setting are fixable
-     * over the live link (the sync door); an overlay line takes a rebuild. */
-    drift: z.array(NeedsActionSchema).optional(),
-});
-export type RunnerSummary = z.infer<typeof RunnerSummarySchema>;
-
-/* A workspace sync, narrated as it happens: a first contact clones whole repositories, and a person may be
- * watching the "preparing runner" state, so the lines travel while they are produced (runSandboxFlow's
- * argument). `op` says which direction: `pull` brings the runner's checkout of the conversation's branch (and
- * each repo's main line) up to date before a turn, `push` returns the branch after one.
- *
- * `repos` is the conversation's composition as the parent recorded it, because only the parent can know it:
- * the runner's own discovery would see whatever its mirror held from LAST time, and a repo added to the
- * workspace since would silently fall out of the conversation. Each entry names the repo id (the git-door
- * address), the workspace-relative dir the checkout lives at, and the repo's own main branch name. */
-export const RunnerSyncSchema = z.object({
-    op: z.enum(["pull", "push"]),
-    conversationId: z.string().min(1),
-    branch: z.string().min(1),
-    repos: z.array(
-        z.object({
-            repo: z.string().min(1),
-            // "" for the workspace root itself; every other repo sits at its root-relative dir.
-            dir: z.string(),
-            mainBranch: z.string().min(1),
-        }),
-    ),
-});
-export type RunnerSync = z.infer<typeof RunnerSyncSchema>;
-
-export const RunnerSyncLineSchema = z.union([
-    z.object({ kind: z.literal("line"), text: z.string() }),
-    z.object({ kind: z.literal("done"), ok: z.boolean(), detail: z.string().optional() }),
-]);
-export type RunnerSyncLine = z.infer<typeof RunnerSyncLineSchema>;
-
-/* One turn, as dispatched. Deliberately NOT AgentTurnSchema: that schema is the browser's request to the
- * parent, full of fields the parent resolves before anything executes (persona, account, title, forks). What
- * crosses the link is the residue after resolution, what the runner's harness spawn actually needs, plus the
- * attachments inline, because the runner has no route onto the parent's attachment store. */
-export const RunnerTurnSchema = z.object({
-    conversationId: z.string().min(1),
-    branch: z.string().min(1),
-    prompt: z.string(),
-    provider: z.string(),
-    harness: z.string(),
-    model: z.string().optional(),
-    effort: z.string().optional(),
-    thinking: z.boolean().optional(),
-    fast: z.boolean().optional(),
-    // Which of the ORIGIN sandbox's connected accounts pays for the turn: the runner resolves credentials
-    // against the parent (the credential doors below), so this names an account THERE.
-    account: z.string().optional(),
-    sessionId: z.string().optional(),
-    // Base64 because frames are JSON: small by policy (the request schema already caps attachment count), and
-    // a turn's attachments are the one payload with no git road to travel. `path` is the workspace-relative
-    // path the prompt already names; the runner writes the bytes there so the words and the file agree.
-    attachments: z.array(z.object({ path: z.string().min(1), bytesBase64: z.string() })).optional(),
-});
-export type RunnerTurn = z.infer<typeof RunnerTurnSchema>;
-
-/* WHERE A CONVERSATION RUNS, decided on its first turn and owned by the conversation from then on, exactly as
- * `isolated` placement already works (agent.routes.ts): later turns follow the registry entry, not whichever
- * client sends them. `runner` implies isolation, a remote conversation is always branch-anchored, because its
- * branch is the unit that moves between machines. Absent means local, which is why this is optional
- * everywhere: the default costs nothing to anyone who never uses it. */
-export const AgentPlacementSchema = z.union([z.object({ kind: z.literal("local") }), z.object({ kind: z.literal("runner"), id: z.string().min(1) })]);
-export type AgentPlacement = z.infer<typeof AgentPlacementSchema>;

package/src/runtime-state.ts

@@ -1,140 +0,0 @@
-/* WHICH RUNNING THING BACKS WHICH VIEW, the twin of workspace-state.ts, for state that never touches a file.
- *
- * That table answers "the agent wrote a file, so which view is stale". This one answers the same question for
- * the half of the sandbox that has no file to watch: the tmux sessions, the dev-server panels, the listening
- * sockets, the agent's Chromiums, the children its turns spawn. None of them are on disk, so no
- * `workspaceChanged` batch can ever mention them, and for want of a push, every one of those views polled.
- *
- * The polls were the tell. Six always-on timers (a 10s terminals relist behind THREE mounted surfaces, a 15s
- * port scan behind the shell rail, a 4s panel relist for as long as any dev server ran) that each asked a
- * question whose answer is almost always "nothing changed", forever, in every open tab. The daemon knew the real
- * answer the whole time: it is the process that starts the panel, mints the browser, and opens the session.
- *
- * So the daemon says so, on the stream that already carries every other change, and the browser asks only when
- * told to. The declaration lives HERE for the reason its twin does: the daemon publishes a DOMAIN and the
- * browser turns it into query keys, and those two facts drift the moment they are written down in two packages.
- *
- * A key belongs to whoever queries it, the extension views that render ports and panels ask under the SAME key
- * as core (api.sandbox.key("ports") is sandboxKey("ports")), so one entry here refreshes both surfaces and an
- * extension needs no declaration of its own. */
-
-/* One query key as the browser files it, a segment per level, so a binding can name a NESTED key and not only
- * a top-level one. Most domains here are a single segment and read as they always did; the review is not. Its
- * key is `["git", "changes"]` (the browser appends the sandbox id, and every open file diff hangs beneath it),
- * and a domain that could only say `"git"` would drop the commit log along with it, a second read of the graph
- * to deliver a sentence that has nothing to do with it. */
-export type QueryKeyPath = readonly string[];
-
-export interface RuntimeDomainBinding {
-    // What moved, in the daemon's words. Wire data: it rides the runtimeChanged frame.
-    readonly domain: string;
-    /* The browser query keys this domain's state feeds. Invalidation reaches only queries something is
-     * OBSERVING, so a domain nobody has on screen costs a frame and no request, which is what lets a domain be
-     * pushed eagerly without billing every tab for a view it isn't showing. */
-    readonly invalidates: readonly QueryKeyPath[];
-}
-
-/* Declared `as const` so the domain names survive as literal types (see RuntimeDomain below), then published
- * under the interface, the same two-binding shape, for the same reason, as WORKSPACE_STATE_FILES. */
-const RUNTIME_DOMAINS = [
-    /* Every attachable tmux session: the terminal panel's tab strip, the rail's activity badge, and the work
-     * popover's background-process rows all read this one list. Sampled rather than announced, a pane dies
-     * when its command exits and tmux tells nobody, but sampled ONCE in the daemon, on a connection the
-     * browsers already hold, instead of once per browser per 10s over the tunnel. */
-    { domain: "terminals", invalidates: [["terminals"]] },
-
-    /* A repo's dev server: running, healthy, and the preview URL it answers on. Two independent things move it,
-     * and it needs both, the process manager starting or reaping a session (announced), and the server
-     * actually binding its port some seconds later, which is what flips "starting" to "healthy" (seen by the
-     * port sampler, since panel health is read off the listening sockets, see panels.ts listenersByRepo).
-     *
-     * `apps` rides it because a monorepo's per-app previews ARE managed processes under the same manager
-     * (workspace.routes appsList reads processes.portOf), just listed per repo instead of per repo-root. One
-     * domain, because there is one fact: a dev server the daemon runs started, settled, or died. */
-    { domain: "panels", invalidates: [["panels"], ["apps"]] },
-
-    /* Every listening TCP socket in the sandbox, and which of them are forwarded to a public preview hostname.
-     * The daemon runs no port poller for the ANSWER, attributing a socket to its process walks every /proc fd
-     * table, far too much to do on a timer, so what is sampled is only the LISTEN set out of /proc/net/tcp:
-     * two file reads, enough to know that the answer changed and worth nobody's while to compute until a view
-     * asks. Change detection and payload are deliberately different sizes here. */
-    { domain: "ports", invalidates: [["ports"]] },
-
-    // The agent's Chromiums and the pages each holds open, daemon-held records, minted from the hooks that see
-    // the agent's own browser tool calls, so every change to this roster passes through this process.
-    { domain: "browsers", invalidates: [["browsers"]] },
-
-    // The agents this sandbox's agents started. Daemon-held like the browsers, and the one roster here that
-    // changes while nothing starts or stops: a working child reports tool uses and tokens continuously, which
-    // is why the daemon rate-limits this domain rather than pushing every mutation (see runtime-watch.ts).
-    { domain: "subagents", invalidates: [["subagents"]] },
-
-    /* THE MACHINES ON THE OTHER END OF A SOCKET, three domains that are one story: the user's devices, the
-     * browsers holding the extension, and this sandbox's runners.
-     *
-     * Announced, and about as announced as a fact can be. "Online" here is not sampled, inferred or timed out
-     * of, it IS a socket in this process: the hub accepts one, replaces one, drops one on a failed heartbeat, or
-     * cuts one on a revoke, and those four moments are the entire set of ways the answer changes. Nothing on
-     * disk moves, no pane appears, and no other feed could carry it.
-     *
-     * They land on `capabilities` because a host or webext card's state is LITERALLY the hub's answer
-     * (handlers/host.ts: `hub.online(id) ? active : pending`), which is what a person watches while they paste a
-     * pairing command into a laptop. That wait is the whole reason these are here: it was three seconds of
-     * polling per card, running only because nobody had told the browser that the daemon already knew. */
-    { domain: "hosts", invalidates: [["capabilities"], ["devices"]] },
-    { domain: "webext", invalidates: [["capabilities"]] },
-    { domain: "runners", invalidates: [["runners"]] },
-
-    /* The approvals queue, when the DAEMON moves it rather than the owner. Approving is the owner's own mutation
-     * and refetches itself, but everything after that happens while nobody is touching the page: a held item
-     * coming due, a Discord send landing, an executing turn writing back what happened. Those are the moments
-     * the row on screen stops being true, and this queue is watched precisely because its rows act in public,
-     * so it is the last place to leave someone reading a stale one. */
-    { domain: "approvals", invalidates: [["approvals"]] },
-
-    /* WHAT A LANDED AGENT'S WORK IS CALLED, the commit message drafted from the diff the moment that work
-     * reaches the main tree (agents/landed-subject.ts), which the review's "From" chip files into the commit box.
-     *
-     * It needs a push of its own because it arrives LATE, and alone. The review refreshes when a turn ends; the
-     * sentence is a model call that STARTS there and answers seconds later, so the refresh the landing itself
-     * causes is always too early to carry it. Nothing followed. The message then sat in the daemon, correct and
-     * unread, until some unrelated write happened to refresh the panel again, and a chip clicked in that window
-     * filed nothing at all, which is indistinguishable from the feature having been removed.
-     *
-     * Neither a file nor a ref, so this is the only feed that could carry it: the entry holding it lives on
-     * /history, outside the watched tree, and no ref moves when a sentence is written.
-     *
-     * Being in this table also puts the review on the reconnect re-ask (runtimeBoundQueryKeys), and that is the
-     * half of the fix nothing else covers: a publish with no browser connected is dropped, so a landing drafted
-     * while the app was closed or the tunnel was down would otherwise stay invisible for as long as the panel's
-     * snapshot survived, which, at staleTime Infinity, is until something unrelated moved. It costs one review
-     * read per (re)connect, against a chip that files nothing for the rest of the session. */
-    { domain: "landings", invalidates: [["git", "changes"]] },
-] as const satisfies readonly RuntimeDomainBinding[];
-
-export const RUNTIME_DOMAIN_BINDINGS: readonly RuntimeDomainBinding[] = RUNTIME_DOMAINS;
-
-/* Every domain this table declares, as a type, so a publish site names one of THESE and nothing else, and a
- * renamed domain is a compile error in the daemon rather than a frame the browser silently routes nowhere. */
-export type RuntimeDomain = (typeof RUNTIME_DOMAINS)[number]["domain"];
-
-/* Distinct key paths, in table order, two domains in one frame routinely feed the same view, and a Set cannot
- * see that because each path is its own array. Compared by their segments joined, which is exact: a segment is
- * one identifier from this file, never a caller's string, so there is no separator to collide on. */
-const dedupe = (keys: readonly QueryKeyPath[]): readonly QueryKeyPath[] => [...new Map(keys.map((key) => [key.join(`/`), key])).values()];
-
-/* The query keys a pushed set of domains makes stale, deduped and stable, the browser's `/events` handler
- * calls this, exactly as it calls staleQueryKeys for a path batch. Kept here rather than in the web so the rule
- * is unit-testable without a query client, and so the daemon can assert against the same table.
- *
- * An unknown domain contributes nothing rather than throwing: a daemon newer than the browser may name a domain
- * this build has never heard of, and the honest response to that is to refresh what we do understand. */
-export const staleRuntimeQueryKeys = (domains: readonly string[]): readonly QueryKeyPath[] =>
-    dedupe(RUNTIME_DOMAIN_BINDINGS.filter((binding) => domains.includes(binding.domain)).flatMap((binding) => binding.invalidates));
-
-/* Every query key any runtime domain feeds, what a NEW /events connection re-asks wholesale, for precisely the
- * reason fileBoundQueryKeys exists: this push is these views' ONLY live feed, and a frame produced while the
- * stream was down is a frame nobody will resend. A panel that finished starting, a session that exited, a port
- * that closed while the browser was away would otherwise sit wrong until the next unrelated change. Re-asking
- * on connect bounds that at one cheap read per key, which is what lets these views go entirely unpolled. */
-export const runtimeBoundQueryKeys = (): readonly QueryKeyPath[] => dedupe(RUNTIME_DOMAIN_BINDINGS.flatMap((binding) => binding.invalidates));