@intentic/sandbox-contract 1.230.2 → 1.231.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/sandbox-contract",
-  "version": "1.230.2",
+  "version": "1.231.0",
   "description": "oRPC wire contract for the intentic sandbox daemon, shared by the daemon and its browser client",
   "license": "MIT",
   "type": "module",
@@ -89,9 +89,9 @@
     "@orpc/contract": "1.14.13",
     "tslib": "2.8.1",
     "zod": "4.4.3",
-    "@intentic/constants": "1.230.2",
-    "@intentic/extension-manifest": "1.230.2",
-    "@intentic/registry": "1.230.2"
+    "@intentic/constants": "1.231.0",
+    "@intentic/extension-manifest": "1.231.0",
+    "@intentic/registry": "1.231.0"
   },
   "devDependencies": {
     "@types/node": "24.13.2",

package/src/contracts/capabilities.contract.ts

@@ -7,6 +7,7 @@ import {
     CapabilityIdParamSchema,
     CapabilityLoginSchema,
     CapabilityOtpSchema,
+    CapabilityProbeSchema,
     CapabilityRenameSchema,
     CapabilitySchema,
     CapabilitySecretInputSchema,
@@ -48,6 +49,21 @@ export const capabilitiesContract = {
         })
         .input(CapabilitySchema)
         .output(eventIterator(IntenticLineSchema)),
+    /* TRY THE SETTINGS BEFORE SAVING THEM. Nothing is written and nothing is applied: the daemon dials the
+     * service the way the connection would and hands back what it said. It exists because the alternative is
+     * the form's only feedback being the card afterwards reading "not connected", which names none of the six
+     * answers that could have been wrong. A credential the caller is keeping arrives as VAULTED here too, so
+     * an edit can be tested without re-typing a key. */
+    probe: oc
+        .route({
+            method: "POST",
+            path: "/capabilities/probe",
+            summary: "Test a connection's settings without saving them",
+            description:
+                "Dials the service the way this connection would and hands back what it said, before anything is written. The answer is the service's own confirmation or its exact refusal, so a wrong token or an unreachable host is found on the form rather than on a card afterwards.",
+        })
+        .input(CapabilitySchema)
+        .output(CapabilityProbeSchema),
     remove: oc
         .route({
             method: "DELETE",

package/src/contracts/runner.contract.ts

@@ -0,0 +1,33 @@
+import { eventIterator, oc } from "@orpc/contract";
+import { AgentEventSchema } from "../events.js";
+import { RunnerFactsSchema, RunnerSyncLineSchema, RunnerSyncSchema, RunnerTurnSchema } from "../runner-protocol.js";
+import { OkSchema } from "../schemas.js";
+
+/* What a RUNNER can be asked, over the socket it opened to its parent sandbox. Phase-1 skeleton: the shape is
+ * decided (docs/remote-runners-plan.md §5, workspace root), the implementations land with runner mode.
+ *
+ * Same inversion as hostContract: the runner dialled, but the runner is the oRPC SERVER and the parent holds
+ * the client, because a runner sits behind NAT or inside a Fly private network and can only ever be the side
+ * that connects. No `.route()` on these, the link never touches HTTP; the procedure path IS the address.
+ *
+ * TYPED THROUGHOUT, where hostContract keeps its deliberate `mcp` hole, and the difference is who releases
+ * what. A machine's tools must outlive the daemon's release cycle, so their schemas stay on the machine. A
+ * runner IS this daemon, the same image the parent runs, released together by construction, so an untyped
+ * channel would buy independence nobody has while costing the parent's persistence layer its guarantee that
+ * every frame is exactly what a local turn would have produced. */
+export const runnerContract = {
+    // What this runner is, hardware-wise: pulled after the socket authenticates and again whenever the
+    // placement picker wants it fresh. Parity facts (image, overlay hash) ride the hello instead, they change
+    // only with a rebuild, which drops the socket anyway.
+    describe: oc.output(RunnerFactsSchema),
+    // Bring the runner's checkout of one conversation's branch up to date (`pull`), or return the result
+    // after a turn (`push`). Streamed: a first sync clones repositories, and a person may be watching.
+    syncWorkspace: oc.input(RunnerSyncSchema).output(eventIterator(RunnerSyncLineSchema)),
+    // The dispatch: one turn in, the frames a local turn would have produced out. The parent republishes them
+    // into the same pipeline local frames enter, which is the whole "feels local" mechanism.
+    runTurn: oc.input(RunnerTurnSchema).output(eventIterator(AgentEventSchema)),
+    // Stop the running turn; the parent's stop button reaching through.
+    interrupt: oc.input(RunnerTurnSchema.pick({ conversationId: true })).output(OkSchema),
+    // Liveness, driven by the parent: keepalive and gone-detection in one, the host hub's heartbeat verbatim.
+    ping: oc.output(OkSchema),
+};

package/src/documents.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "vitest";
+import { documentOf, documentTitle, isDocumentPath, isPlanDocumentPath, PLAN_DOCUMENTS_DIR } from "./documents.js";
+
+const write = (path: string, newText: string, extra: { oldText?: string; truncated?: boolean } = {}) => [
+    { type: "diff" as const, path, newText, ...extra },
+];
+
+describe("documentOf", () => {
+    test("a markdown file written whole is a document, titled by its opening heading", () => {
+        expect(documentOf("Write", write("docs/findings.md", "# Why it is slow\n\nBecause of the poll."))).toEqual({
+            path: "docs/findings.md",
+            title: "Why it is slow",
+            markdown: "# Why it is slow\n\nBecause of the poll.",
+        });
+    });
+
+    test("a plan file says so, which is what gives it the plan card's face", () => {
+        const document = documentOf("Write", write(`${PLAN_DOCUMENTS_DIR}/wiggly-spring.md`, "## The plan\n\nStep one."));
+        expect(document?.plan).toBe(true);
+        expect(document?.title).toBe("The plan");
+    });
+
+    test("carries the wire cap forward, so a clipped document can say it is clipped", () => {
+        expect(documentOf("Write", write("notes.md", "# Notes", { truncated: true }))?.truncated).toBe(true);
+    });
+
+    test("an EDIT to a document is not one: its newText is a fragment, and the change is what a reader wants", () => {
+        expect(documentOf("Edit", write("docs/findings.md", "a replaced paragraph", { oldText: "the old paragraph" }))).toBeUndefined();
+    });
+
+    test("code is not a document, whatever it was written with", () => {
+        expect(documentOf("Write", write("src/foo.ts", "export const x = 1;"))).toBeUndefined();
+    });
+
+    test("a call with no diff has written nothing to show", () => {
+        expect(documentOf("Write", [{ type: "text", text: "File created successfully." }])).toBeUndefined();
+        expect(documentOf("Write", undefined)).toBeUndefined();
+    });
+
+    test("names arrive in whatever case a backend spells them", () => {
+        expect(documentOf("write", write("notes.md", "# Notes"))?.path).toBe("notes.md");
+    });
+});
+
+describe("documentTitle", () => {
+    test("falls back to the file name when the document opens with prose", () => {
+        expect(documentTitle("No heading here, just prose.", "docs/some-notes.md")).toBe("some-notes.md");
+    });
+
+    test("takes the heading whatever its depth", () => {
+        expect(documentTitle("###### deep\n", "notes.md")).toBe("deep");
+    });
+});
+
+describe("paths", () => {
+    test("markdown, by either extension, in any case", () => {
+        expect(isDocumentPath("a/b.md")).toBe(true);
+        expect(isDocumentPath("a/b.MARKDOWN")).toBe(true);
+        expect(isDocumentPath("a/b.txt")).toBe(false);
+    });
+
+    test("a plan is one by where it lives, not by what it is called", () => {
+        expect(isPlanDocumentPath(`${PLAN_DOCUMENTS_DIR}/anything.md`)).toBe(true);
+        expect(isPlanDocumentPath("docs/plans/anything.md")).toBe(false);
+    });
+});

package/src/documents.ts

@@ -0,0 +1,71 @@
+import { STATE_DIR } from "@intentic/constants";
+import type { CardDocument, ToolCallContent } from "./events.js";
+import { planParts } from "./title.js";
+
+/* A DOCUMENT A TURN WROTE FOR A PERSON TO READ, told apart from the files it changed for the machine.
+ *
+ * A transcript renders ACTS: a file was written, a command ran, a page was fetched. That is the right shape for
+ * nearly everything an agent does, and the wrong shape for the one thing it produces that is addressed to the
+ * reader. An analysis, a findings write-up, a plan: the card for those said `Write · +135 −0` and folded, so the
+ * document the next question was ABOUT was the one thing the chat would not show. Worse, the model reaches for a
+ * file precisely BECAUSE prose in the answer is expensive, so the better it behaves the less the reader sees.
+ *
+ * The rules live here, in the contract, because both sides run them and they must not drift: the daemon reads
+ * them to decide what a parked card is about (agent.ts), the browser to decide how a tool card draws
+ * (toolPresentation.ts). Two copies would let a card render a document the question card had never heard of.
+ *
+ * ONLY A WHOLE-FILE WRITE COUNTS. An Edit's `newText` is the replacement fragment, not the document: rendered as
+ * prose it is a mid-sentence slice with no heading, and the DIFF is what a reader wants from an edit anyway. So
+ * a Write of a markdown file is a document, and an edit to one stays a diff. */
+
+/* WHERE THE CLI'S PLAN FILES LAND, workspace-relative.
+ *
+ * `~/.claude/plans` is a symlink onto this directory (sessions/session-store.ts links the SDK's conversation
+ * state onto the workspace volume), which makes a plan file the one document with a HARNESS-OWNED address: no
+ * guessing whether prose is a plan, no threshold on length, the path says so. That is why plan documents get
+ * their own treatment while everything else rides the general markdown rule above. */
+export const PLAN_DOCUMENTS_DIR = `${STATE_DIR}/records/sessions/claude/plans`;
+
+// Prose, by extension. Deliberately short: a document is something the chat can RENDER, and markdown is what
+// the chat's prose pipeline speaks. A `.txt` report would render as an unstyled wall and reads better as the
+// plain text box it already gets.
+const DOCUMENT_EXTENSIONS = [".md", ".markdown"];
+
+export const isDocumentPath = (path: string): boolean => {
+    const lower = path.toLowerCase();
+    return DOCUMENT_EXTENSIONS.some((extension) => lower.endsWith(extension));
+};
+
+// Whether a path is one of the CLI's plan files. Matched on the directory rather than on the name, which is a
+// mint-fresh three-word phrase (`map-of-this-wiggly-spring.md`) carrying no signal at all.
+export const isPlanDocumentPath = (path: string): boolean => path.startsWith(`${PLAN_DOCUMENTS_DIR}/`);
+
+/* What a document is CALLED. Its opening heading when it has one, which is the line the author wrote to name
+ * the whole thing (planParts, the same split the plan card titles from), and its file name when it does not.
+ *
+ * Never the path: a card that says `.intentic/records/sessions/claude/plans/map-of-this-wiggly-spring.md`
+ * has told the reader nothing about what is in it, and that string is the CLI's mint, not anybody's title. */
+export const documentTitle = (markdown: string, path: string): string => planParts(markdown).title ?? path.split("/").pop() ?? path;
+
+/* The document a tool call produced, or undefined when it produced none, the ONE test both sides ask.
+ *
+ * Reads the call's structured diff rather than its result text, because the content is already there: a Write's
+ * whole file rides the tool_call frame as `newText` (capped at the wire limit, which `truncated` reports), so
+ * nothing has to be re-read from disk to draw it, and a published transcript with no workspace behind it draws
+ * exactly the same document. */
+export const documentOf = (name: string, content: readonly ToolCallContent[] | undefined): CardDocument | undefined => {
+    if (name.toLowerCase() !== "write") {
+        return undefined;
+    }
+    const diff = content?.find((entry) => entry.type === "diff" && isDocumentPath(entry.path));
+    if (diff === undefined || diff.type !== "diff") {
+        return undefined;
+    }
+    return {
+        path: diff.path,
+        title: documentTitle(diff.newText, diff.path),
+        markdown: diff.newText,
+        ...(diff.truncated === true ? { truncated: true } : {}),
+        ...(isPlanDocumentPath(diff.path) ? { plan: true } : {}),
+    };
+};

package/src/events.ts

@@ -434,6 +434,30 @@ export const SharePayloadSchema = z.object({
 });
 export type SharePayload = z.infer<typeof SharePayloadSchema>;
 
+/* WHAT A PARKED CARD IS ABOUT: the document the turn wrote and is now asking a question against.
+ *
+ * A card asks for a decision; until this it carried no SUBJECT. The commonest shape of a real decision is "I
+ * analysed this and wrote it up, now choose", and the write-up went into a file whose card had already folded
+ * itself into `Write · +135 −0` twenty tool calls back. So the reader was asked to choose between options
+ * describing a document the chat had never shown them.
+ *
+ * Carried BY VALUE rather than as a path, for the same reason the diff on a tool call is: the bytes are already
+ * in hand when the card is raised, a path would make the card's meaning depend on a file that keeps changing
+ * under it, and a restored or published transcript has no workspace to go read. The path rides along anyway, so
+ * a document past the wire cap still has somewhere to send the reader.
+ *
+ * Nothing is asked of the MODEL for this. It calls `ask` exactly as before; the daemon knows what the turn
+ * wrote, because every write came past it as a frame (documents.ts decides which of them is a document). A
+ * harness that can see the answer must not spend prompt on asking the model to repeat it. */
+export const CardDocumentSchema = z.object({
+    path: z.string().describe("Where it lives, as a workspace path."),
+    title: z.string().describe("What it is called: its opening heading, or its file name."),
+    markdown: z.string().describe("The document itself."),
+    truncated: z.boolean().optional().describe("It was clipped at the wire cap; the file on disk has more."),
+    plan: z.boolean().optional().describe("It is one of the CLI's plan files, written to be approved rather than merely read."),
+});
+export type CardDocument = z.infer<typeof CardDocumentSchema>;
+
 /* THE THREE RESTORABLE CARDS, named so the turn journal can hold them verbatim: a parked turn's raised cards
  * are written down beside its prompt (sandbox turn-journal.ts), and a daemon death under the park restores the
  * very same frames instead of ending the turn `interrupted`, the card the user was about to answer survives
@@ -444,11 +468,15 @@ const PlanCardSchema = z.object({
     kind: z.literal("plan").describe("The agent has written a plan and is waiting for a yes."),
     requestId: z.string().describe("What to send back when you answer."),
     text: z.string().describe("The plan itself."),
+    // Present when the plan text POINTS at a document instead of being one: the model wrote the real plan to a
+    // file and summarised it here. Absent when the text already is the whole plan, which is the ordinary case.
+    document: CardDocumentSchema.optional().describe("The write-up this plan refers to, when the plan itself is a pointer to one."),
 });
 const QuestionCardSchema = z.object({
     kind: z.literal("question").describe("The agent has asked you something and is waiting."),
     requestId: z.string().describe("What to send back when you answer."),
     questions: z.array(AskQuestionSchema).describe("What it wants to know."),
+    document: CardDocumentSchema.optional().describe("The document this turn wrote and is asking about, so the choice can be read beside it."),
 });
 const PermissionCardSchema = PermissionAskSchema.extend({
     kind: z.literal("permission").describe("The agent wants to use a tool it needs permission for."),
@@ -493,6 +521,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         base: z.string(),
         unenforced: z.boolean().optional(),
         sync: z.object({ commits: z.number(), blocked: z.array(z.string()) }).optional(),
+        // The runner this turn executes on, when the conversation is placed remotely (runners/): the
+        // transcript's own statement of where the work is happening. Absent ⇒ this sandbox.
+        remote: z.string().optional(),
     }),
     // Emitted after a clean isolated turn whose delta auto-landed (or failed to): landed ⇒ the work is now
     // UNCOMMITTED changes in the main tree (the Changes panel is the review); conflicts ⇒ it stayed safely in
@@ -621,9 +652,10 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         agentType: z.string().optional(),
         description: z.string().optional(),
         model: z.string().optional(),
+        // Which provider serves a `spawned` child (SubagentSessionSchema.provider), absent for an SDK
+        // subagent, whose provider is its parent's.
+        provider: z.string().optional(),
         background: z.boolean().optional(),
-        // A delegation's tmux session, the one live view a subagent doesn't have (SubagentSessionSchema).
-        terminal: z.string().optional(),
     }),
     z.object({
         kind: z.literal("subagent_update"),
@@ -913,6 +945,16 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 "context-window-too-small",
                 "subscription-required",
                 "agent-busy",
+                /* THE SANDBOX HAS NO MEMORY LEFT TO RUN THIS TURN, refused before anything was spawned
+                 * (platform/memory-admission.ts). Its own code because it is the only refusal here that is
+                 * about the BOX rather than the request: the prompt, the model and the credential are all
+                 * fine, and the identical request succeeds once something inside frees room, which is the
+                 * opposite of context-window-too-small next door. Transient without being on a clock, so
+                 * there is no resetsAt to offer — what changes the outcome is a turn finishing or a session
+                 * closing, and the message says so. The client HOLDS the words for the same reason
+                 * context-window-too-small does: they never reached a provider, and losing them to a
+                 * capacity fact the user did not cause would be ours to answer for. */
+                "sandbox-memory-low",
             ])
             .optional(),
         // rate_limit only: when the exhausted window reopens (epoch seconds, from the stream's own

package/src/history-state.ts

@@ -131,5 +131,12 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // The burn list for setup-time computer pairings. Identity, like sync's beside it, and for a sharper reason:
     // carrying it into another sandbox would mark that sandbox's own fresh pairing as already spent.
     { path: "host-pair-consumed.json", portability: "identity" },
+    // A runner's enrollment names THIS sandbox as its parent (runners/runners-store.ts): in another sandbox the
+    // digest would admit a socket whose runner still dials the old parent. Identity, both files, hosts' reasons.
+    { path: "runner-enrollments.json", portability: "identity" },
+    { path: "runner-pair-consumed.json", portability: "identity" },
+    // The runner-SIDE half: who this container belongs to and the token its reconnects present
+    // (runners/runner-identity.ts). Carried into another box it would dial the parent as this runner.
+    { path: "runner-identity.json", portability: "identity" },
     { path: "local-cert/", portability: "identity" },
 ];

package/src/index.ts

@@ -59,6 +59,8 @@ export { historyContract } from "./contracts/history.contract.js";
 /* Deliberately NOT part of `sandboxContract` below: that map is the daemon's own HTTP surface, and this one is
  * spoken the other way round, over a connected computer's WebSocket, with the MACHINE implementing it. */
 export { hostContract } from "./contracts/host.contract.js";
+// Same inversion, other direction of trust: spoken over a RUNNER's WebSocket, with the runner implementing it.
+export { runnerContract } from "./contracts/runner.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
@@ -104,8 +106,10 @@ export * from "./agent-run-model.js";
 export * from "./capability-env.js";
 export * from "./capability-secrets.js";
 export * from "./conversation-ids.js";
+export * from "./documents.js";
 export * from "./fast-tier.js";
 export * from "./host-protocol.js";
+export * from "./runner-protocol.js";
 export * from "./listener-protocol.js";
 export * from "./hostnames.js";
 export * from "./model-order.js";

package/src/runner-protocol.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+
+/* 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(),
+});
+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 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>;
+
+// 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(),
+    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(),
+});
+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>;