@intentic/sandbox-contract 1.231.0 → 1.233.0

package/src/runner-protocol.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { DefinitionActionSchema } from "./definition-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
@@ -30,6 +31,13 @@ export const RunnerHelloSchema = z.object({
     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>;
 
@@ -44,7 +52,8 @@ export const runnerEnrollUrl = (parentUrl: string): string => `${parentUrl.repla
  * 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)}`;
+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
@@ -52,6 +61,12 @@ export const runnerGitUrl = (parentUrl: string, repo: string): string => `${pare
  * 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.
@@ -128,10 +143,20 @@ export const RunnerFactsSchema = z.object({
 });
 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 computer holding it, when this sandbox is what asked for it (the Computers 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(),
@@ -139,6 +164,14 @@ export const RunnerSummarySchema = z.object({
     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(DefinitionActionSchema).optional(),
 });
 export type RunnerSummary = z.infer<typeof RunnerSummarySchema>;
 
@@ -202,8 +235,5 @@ export type RunnerTurn = z.infer<typeof RunnerTurnSchema>;
  * 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 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/schemas/activity.ts

@@ -0,0 +1,123 @@
+// activity: the activity audit log (historyRoot/activity.jsonl)
+import { z } from "zod";
+import { AgentOriginSchema } from "./agent.js";
+// One provider-agnostic event per agent↔provider interaction, appended by the daemon only (never the agent,
+// the log lives under historyRoot, outside /work, so the agent can't read or rewrite its own trail). Discord
+// is the first source; other cli providers reuse the same shape.
+
+export const ActivityEventSchema = z.object({
+    id: z.string().describe("The entry's own id."),
+    // Epoch ms; also the paging cursor.
+    at: z.number().describe("When it happened, in milliseconds. Also what you page by."),
+    // "discord", …; absent on provider-less system events (a cron automation.run).
+    provider: z.string().optional().describe("Which outside service, when one was involved. Absent for the sandbox's own events."),
+    // Which provider account handled the turn, the attribution key for per-account usage totals. Absent on
+    // provider-less events and turns that ran on the provider's default account.
+    account: z
+        .string()
+        .optional()
+        .describe("Which account handled it. Absent for the sandbox's own events and for work run on a provider's default."),
+    direction: z.enum(["in", "out", "system"]).describe("Whether something arrived, something went out, or the sandbox did it to itself."),
+    // in: message.received | voice_utterance.received | voice_transcript.received
+    // out: message.send | reaction.add | messages.read | api.call (unclassified provider endpoint)
+    // system: gateway.login_failed | dispatch.failed | voice.session_started | voice.session_ended | automation.run
+    //         | turn.started | turn.plan | turn.error | turn.completed (agent turn lifecycle; provider = claude/codex)
+    //         | rule.blocked_push | rule.held_work | rule.continued_turn (a rule DID something, see RuleSchema.
+    //           Only the three outcomes a person would otherwise have no explanation for: a push that did not
+    //           go, work that did not arrive, a turn that did not end. A rule that ran and passed says nothing,
+    //           because a feed that logs every green check is one the eye learns to skip.)
+    type: z
+        .string()
+        .describe(
+            "Exactly what happened: a message received or sent, a reaction, a turn starting or ending, a rule doing something. A rule that ran and passed says nothing here, because a feed of green ticks is one the eye learns to skip.",
+        ),
+    channelId: z.string().optional().describe("Which channel or thread it happened in."),
+    // Inbound author display name.
+    author: z.string().optional().describe("Who sent it, for something that arrived."),
+    // Full message text (inbound) or sent payload content (outbound).
+    content: z.string().optional().describe("The message, in full, whichever direction it went."),
+    // Outbound HTTP method + endpoint path (tokens ride headers, never URLs).
+    method: z.string().optional().describe("The verb of an outgoing call."),
+    endpoint: z.string().optional().describe("The address of an outgoing call. Credentials travel in headers, so they are never here."),
+    // The agent turn that made/handled it, the join key between an inbound wake and its outbound calls.
+    sessionId: z.string().optional().describe("The provider session behind it."),
+    /* ONE TURN'S EVENTS, TIED TOGETHER. A turn writes four lifecycle events plus one per outbound provider call,
+     * and read as five rows they say one thing five times, so the feed groups on this instead. It cannot be
+     * sessionId: the runtime does not mint one until the stream's first frame, which is AFTER turn.started, so
+     * the very event carrying the prompt is the one that could never be joined. Minted by the turn itself. */
+    turnId: z
+        .string()
+        .optional()
+        .describe(
+            "Ties one turn's entries together. A turn writes several, and read as separate rows they say one thing several times, so a feed groups on this.",
+        ),
+    // The stable conversation the turn belongs to. Outlives sessionId, which a provider/account/harness switch
+    // retires mid-conversation, so this, not sessionId, is what "the same agent" means across a feed.
+    conversationId: z
+        .string()
+        .optional()
+        .describe(
+            "Which conversation. This, rather than the provider session, is what the same agent means across a feed, because a session is retired whenever the model changes.",
+        ),
+    // The conversation's display title as it stood when the event was written. Denormalised on purpose: the
+    // registry entry it came from is prunable and renameable, and an audit row must still read as words years
+    // later. Absent on the first event of a fresh conversation, the auto-namer has not run yet.
+    title: z
+        .string()
+        .optional()
+        .describe(
+            "What that conversation was called at the time. Copied in rather than looked up, because an audit entry must still read as words years later, after the conversation has been renamed or pruned.",
+        ),
+    // What woke the conversation from outside, when something did (see AgentOriginSchema), the feed's "who
+    // called me" attribution, and how a turn is filed under Discord rather than under the runtime that served it.
+    origin: AgentOriginSchema.optional().describe(
+        "What woke the conversation from outside, when something did. It is how a turn gets filed under the chat service that caused it rather than under the model that served it.",
+    ),
+    automationIds: z.array(z.string()).optional().describe("Which automations were involved."),
+    outcome: z.enum(["ok", "error"]).optional().describe("How it ended."),
+    error: z.string().optional().describe("What went wrong, when something did."),
+    // Source-specific detail: guildId, attachments, transcript path, participants…
+    extra: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Whatever else the source had to say: attachments, participants, a recording's path. Shape varies by source."),
+});
+export type ActivityEvent = z.infer<typeof ActivityEventSchema>;
+export const ActivityQuerySchema = z.object({
+    provider: z.string().optional().describe("Narrow it to one outside service."),
+    limit: z.coerce.number().min(1).max(500).default(100).describe("How many entries to return."),
+    // `at` cursor, exclusive, newest-first paging.
+    before: z.coerce.number().optional().describe("Only entries older than this timestamp, so paging walks backwards through the feed."),
+});
+export type ActivityQuery = z.infer<typeof ActivityQuerySchema>;
+export const ActivityListSchema = z.object({ events: z.array(ActivityEventSchema).describe("The audit entries, newest first.") });
+// Live connection health, probed per provider capability (not stored): gateway state from the client pool
+// (idle = the gateway is up but has no enabled listener automation to connect for, distinct from a
+// connection that should be up but isn't; pairing = the socket is up but the credential is a ceremony nobody
+// has finished, which no amount of waiting fixes), lastError from the newest system-error event in the log.
+export const ActivityConnectionSchema = z.object({
+    capabilityId: z.string().describe("Which connection."),
+    provider: z.string().describe("Which service it is."),
+    gateway: z
+        .enum(["ready", "connecting", "pairing", "disconnected", "idle"])
+        .describe(
+            "Idle means it is up but has nothing to listen for, which is different from a connection that should be up and is not. Pairing means somebody started a sign-in and never finished it, which no amount of waiting will fix.",
+        ),
+    lastError: z.string().optional().describe("The most recent thing that went wrong on it."),
+});
+export const ActivityStatusSchema = z.object({
+    connections: z
+        .array(ActivityConnectionSchema)
+        .describe("Each source feeding the record, and whether it is working. Probed now rather than remembered."),
+    // The daemon's live voice session, when one is up.
+    voice: z
+        .object({
+            channelId: z.string().describe("Which channel."),
+            channelName: z.string().describe("What it is called."),
+            startedAt: z.number().describe("When it joined, in milliseconds."),
+            participants: z.array(z.string()).describe("Who else is in it."),
+        })
+        .optional()
+        .describe("A voice call the sandbox is currently in, when it is in one."),
+});
+export type ActivityStatus = z.infer<typeof ActivityStatusSchema>;

package/src/schemas/agent.ts

@@ -0,0 +1,409 @@
+import { z } from "zod";
+import { AgentPlacementSchema } from "../runner-protocol.js";
+import { entryId } from "./internal.js";
+// The agent runtimes the daemon can serve, the vocabulary every surface that picks an agent shares (chat
+// turns, automations). The NATIVE providers have dedicated adapters (and their ids are reserved); an
+// `endpoint/<id>` value names an installed `endpoint`-kind capability (a model API the user pointed us at,
+// see EndpointConfigSchema); any other value is the id of an installed `agent`-kind capability served over
+// ACP (Agent Client Protocol).
+// Kept as a bare string on the wire (not an enum) so an unknown id is a clean error frame from the agent
+// route, the same bet RepoParamSchema makes, and adding an ACP agent needs no contract change.
+export const NATIVE_PROVIDERS = ["claude", "codex", "grok", "kimi", "gemini", "cursor"] as const;
+export type NativeProvider = (typeof NATIVE_PROVIDERS)[number];
+export const AgentProviderSchema = z.string().min(1);
+export type AgentProvider = z.infer<typeof AgentProviderSchema>;
+// The provider naming a catalog in the one route every native provider shares (providers.contract.ts). An ENUM
+// rather than the bare-string schema above, and deliberately so: the open vocabulary exists because an ACP agent
+// or an endpoint can be added without a contract change, but neither has a daemon-held catalog, this route's
+// subjects are exactly the five the daemon keeps one for. Closing it here is what makes an unknown id a 400 from
+// the contract instead of a registry lookup that reads back `undefined` and serves an empty list.
+export const NativeProviderParamSchema = z.object({ provider: z.enum(NATIVE_PROVIDERS) });
+// The harness (agentic loop) a turn runs on, orthogonal to the provider. See AgentTurnSchema.harness.
+export const AgentHarnessSchema = z.enum(["native", "claude-code"]);
+export type AgentHarness = z.infer<typeof AgentHarnessSchema>;
+// One repository at one immutable commit. Workflow runs use this both as the checkout instruction for every
+// candidate and as the comparison base written into handoffs, so a multi-repo run has one provenance record
+// rather than a hard-coded branch name that only happens to work in the root repository.
+export const RepoBaseSchema = z.object({ repo: z.string(), base: z.string().min(1) });
+export type RepoBase = z.infer<typeof RepoBaseSchema>;
+// What the user is looking at in the editor, attached to a turn only when they explicitly opt in (the
+// composer chip, off by default). The daemon folds it into the prompt as a context note, so deictic
+// prompts ("fix this") resolve without an @-mention. Selection is bounded, it's context, not an upload.
+export const EditorContextSchema = z.object({
+    // Workspace-relative path of the file open in the editor.
+    file: z.string().min(1).describe("The file open in the editor, as a workspace path."),
+    // 1-based line range of the selection; absent when the whole file is the context.
+    startLine: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("First line of the selection, counting from one. Leave both out when the whole file is the context."),
+    endLine: z.number().int().min(1).optional().describe("Last line of the selection, counting from one."),
+    // The selected text itself, truncated client-side to the cap.
+    selection: z
+        .string()
+        .max(20_000)
+        .optional()
+        .describe("The selected text itself. Cut it down before sending if it is long: this is context, not an upload."),
+});
+export type EditorContext = z.infer<typeof EditorContextSchema>;
+// The client-minted stable conversation identity. Constrained because isolated conversations also use it in
+// branch names (agent/<id>) and filesystem paths, the regex is the injection guard. Shared by turn + attach,
+// and by the workspace scope (WorkspaceScopeSchema), which names a conversation to read a file tree AS.
+export const ConversationIdSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/);
+// Where a conversation came from when nobody typed it into the browser: an automation wake carrying a message
+// from OUTSIDE the sandbox (a Discord mention, a web-chat visitor, a webhook). Such a wake runs as an ordinary
+// isolated conversation, registry entry, worktree, chat tab, land flow, and this is the only thing that
+// distinguishes it on the surface: the card's provenance line and the reason its first prompt is not the
+// user's. Set daemon-side by the dispatcher that received the message; the browser never sends one.
+export const AgentOriginSchema = z.object({
+    // The automation whose configured prompt opened the conversation.
+    automationId: z.string(),
+    // The listener provider that received the message ("discord", "webchat", …) or "webhook" for an event
+    // trigger. An open string for the same reason Trigger.provider is: sources are extension-declared.
+    provider: z.string(),
+    // The external thread it arrived on, a Discord channel id, a widget conversation id. Absent for webhooks.
+    channelId: z.string().optional(),
+    // Who sent it, as the source names them.
+    author: z.string().optional(),
+});
+export type AgentOrigin = z.infer<typeof AgentOriginSchema>;
+/* The class of thing asking to START a session, the admission policy's key space. Derived daemon-side from
+ * the automation's trigger (guard/actions.ts wakeSourceOf) or named by the door itself (the workflow release
+ * gate); never sent by a client. Chat and loops are absent deliberately: both begin with the owner's own
+ * click, and holding the owner's work in their own queue is a queue entry that says nothing (the same argument
+ * fireAutomation's `cleared` makes about a by-hand fire). */
+export const WakeSourceSchema = z.enum(["schedule", "event", "listener", "webchat", "workspace", "workflow"]);
+export type WakeSource = z.infer<typeof WakeSourceSchema>;
+// One admission verdict the owner can configure: let it run, hold it for approval, or refuse it outright.
+export const AdmissionRuleSchema = z.enum(["allow", "hold", "deny"]);
+export type AdmissionRule = z.infer<typeof AdmissionRuleSchema>;
+/* WHAT KIND OF THING A SHELL COMMAND IS, the command gate's key space, the second layer under the admission
+ * floor above. The floor decides whether a session may START; these decide whether one PARTICULAR command
+ * inside a running session may go ahead, which is the only question left once the agent is already working.
+ *
+ * Five, chosen for one property: everything in them is hard or impossible to take back, so a person seeing it
+ * once beats an audit trail read afterwards. Everything else an agent runs, builds, tests, greps, edits, is
+ * recoverable in a container that is itself disposable, and gating it would be friction bought with nothing. */
+export const CommandClassSchema = z.enum([
+    // Rewrites or discards committed work: force-push, hard reset, force-delete a branch, clean -f, filter-branch.
+    "git.destructive",
+    // Recursive-force deletion (`rm -rf`), and its spelling in a script (`fs.rm(p, { recursive: true })`).
+    "files.destructive",
+    /* State nothing here brings back: a formatted or overwritten disk, a deleted Docker volume, a recursive
+     * delete aimed at a root rather than at something inside one. The only class the daemon holds where the
+     * owner wrote no rule, which is why it is separate from files.destructive rather than a shade of it:
+     * `rm -rf build` is ordinary work in a disposable container and `rm -rf /` is the end of the machine. */
+    "system.destructive",
+    // Names credential material: a .env file, an ssh key, ~/.aws/credentials, .npmrc, a stored token file.
+    "secrets.access",
+    // Publishes outward and irreversibly: npm/pnpm/yarn/cargo publish, gh release create, docker push.
+    "package.publish",
+    // curl/wget to a non-local address, the general exfiltration channel under the per-provider actionRules.
+    "network.outbound",
+]);
+export type CommandClass = z.infer<typeof CommandClassSchema>;
+/* THE ADMISSION FLOOR, the workspace-wide rule per wake source, consulted by the session.start guard on every
+ * outside-driven wake. Per-automation `requireApproval` / `holdForSeconds` remain the per-object override; the
+ * floor composes with them most-restrictive-wins, so "hold every webchat session" needs no edit to each
+ * automation. `workflow` is allow|deny only: the release gate answers a CI runner holding a connection with a
+ * deadline, so a hold there is indistinguishable from a timeout, deny is the honest refusal. */
+export const AdmissionPolicySchema = z.object({
+    schedule: AdmissionRuleSchema.default("allow"),
+    event: AdmissionRuleSchema.default("allow"),
+    listener: AdmissionRuleSchema.default("allow"),
+    webchat: AdmissionRuleSchema.default("allow"),
+    workspace: AdmissionRuleSchema.default("allow"),
+    workflow: z.enum(["allow", "deny"]).default("allow"),
+});
+export type AdmissionPolicy = z.infer<typeof AdmissionPolicySchema>;
+// How tool calls are gated, the Claude Agent SDK's PermissionMode, narrowed to the four the composer offers
+// (the SDK also has 'dontAsk'/'auto', which have no UI here). The user picks one per turn AND the agent can
+// move itself between them mid-turn, so this is both a turn input and the payload of the `mode` frame.
+export const PermissionModeSchema = z.enum(["default", "acceptEdits", "plan", "bypassPermissions"]);
+export type PermissionMode = z.infer<typeof PermissionModeSchema>;
+/* WHERE A CONVERSATION WAS CUT FROM, the durable half of a fork, carried on the registry entry so both ends
+ * can find each other. `index` is the message the cut sat above in the SOURCE, which is what lets the source's
+ * transcript put the mark back in the right gap. */
+export const ForkedFromSchema = z.object({
+    conversationId: ConversationIdSchema,
+    index: z.number().int().nonnegative(),
+    // Which files this fork opened on, the half of the choice that used to be silent, kept so the fork can
+    // still say it tomorrow rather than only in the seconds after the click.
+    files: z.enum(["then", "now"]),
+});
+export type ForkedFrom = z.infer<typeof ForkedFromSchema>;
+export const AgentTurnSchema = z
+    .object({
+        prompt: z.string().describe("What to say to the agent. May be empty if you are only attaching files."),
+        // The client's display title for the conversation, seeds a FRESH registry entry (so a renamed draft's
+        // first turn keeps its user-chosen title); an existing entry's title always wins.
+        title: z
+            .string()
+            .max(80)
+            .optional()
+            .describe("A title for a conversation this turn is opening. Ignored for a conversation that already has one."),
+        // Workspace-relative paths of files the user attached, already uploaded via /workspace/upload
+        // (the browser puts them under .intentic/records/artifacts/attachments/<uuid>/<name>). The daemon hands them to the
+        // provider: Claude reads them from disk via its Read tool; Codex gets images as native inputs.
+        attachments: z
+            .array(z.string().min(1))
+            .max(20)
+            .optional()
+            .describe("Files to hand the agent along with the prompt, as workspace paths. Upload them first."),
+        // Which provider (model + account) serves the turn; absent = claude. A sessionId only resumes on the
+        // provider that minted it (Claude Code sessions vs Codex threads vs Grok/OpenCode sessions are separate
+        // stores), a mid-conversation provider/account/harness switch sends `history` instead of resuming.
+        agent: AgentProviderSchema.optional().describe("Which model provider serves this turn. Leave it out for Claude."),
+        // Which harness (agentic loop) runs the turn, orthogonal to the provider above. Absent = "native": each
+        // provider on its own runtime (Claude Code SDK / Codex CLI / opencode) with its subscription OAuth.
+        // "claude-code" forces the Claude Code Agent SDK loop for ANY provider, codex/grok then drive their model
+        // through the sandbox's bundled Anthropic↔OpenAI translator, which needs that provider's API key (its
+        // subscription OAuth can't reach a gateway). For the claude provider the two are identical.
+        harness: AgentHarnessSchema.optional().describe("Which agentic loop runs the turn. Leave it out to use each provider's own."),
+        // Which connected account of that provider serves the turn; absent = the provider's first account.
+        account: z.string().optional().describe("Which of that provider's connected accounts pays for the turn. Leave it out for the first one."),
+        /* WHICH PERSONA THE TURN SHOWS THE OUTSIDE WORLD, a PersonaSchema id, deliberately NOT the `account`
+         * directly above it. The two words are one letter apart in meaning and a world apart in consequence:
+         * `account` is which subscription PAYS for the turn, `actsAs` is whose name is on what the turn posts.
+         * Naming both "account" is how someone eventually pins a nightly job to the right billing and the wrong
+         * Reddit.
+         *
+         * Absent means opposite things either side of the "is anyone watching" line, which is the owner's chosen
+         * posture and the reason this is resolved in one place (turnPersona): an ordinary chat with no persona
+         * keeps every connected account, because a person is there to catch a mistake; an `unattended` turn with
+         * no persona gets NONE, because at 3am the prompt's wording is the only thing left and that is not
+         * enough to bet an unrepeatable post on. */
+        actsAs: entryId.optional().describe("Which persona the turn speaks as out in the world. Not the same as which account pays for it."),
+        sessionId: z.string().optional().describe("Resume this provider session instead of starting a fresh one."),
+        // The client-minted stable conversation identity (survives provider/account/harness switches, which
+        // retire sessions). Keys the fleet registry entry and turn run, plus the worktree when isolated.
+        conversationId: ConversationIdSchema.optional().describe(
+            "The conversation this turn belongs to. You choose it, it survives model switches, and it is how you address the conversation later. Naming one that does not exist opens it.",
+        ),
+        // When true, the turn runs in the conversation's isolated git worktree (created lazily on first use)
+        // instead of the shared /work tree, the parallel-agents mode. Requires conversationId.
+        isolated: z
+            .boolean()
+            .optional()
+            .describe(
+                "Work in this conversation's own private copy of the repos rather than the shared tree, so several agents can work at once. Needs a conversation id.",
+            ),
+        /* WHERE the conversation executes, decided like `isolated` directly above: the request's choice on the
+         * first turn, the registry entry's on every turn after. `runner` implies isolation (the branch is what
+         * moves between machines) and needs a conversation id for the same reason `isolated` does. Absent =
+         * local. Design: docs/remote-runners-plan.md; refused until runners ship. */
+        placement: AgentPlacementSchema.optional().describe(
+            "Where this conversation runs: this sandbox (leave it out), or a paired runner by id. Decided on the first turn; later turns follow the conversation.",
+        ),
+        /* Pin a NEW isolated conversation's worktree composition to these repository commits. Daemon-owned:
+         * ordinary chats omit it and keep rebasing onto the current workspace; a workflow supplies the one
+         * snapshot all of its candidates must share. Repeated iterations carry it too, which suppresses the
+         * ordinary pre-turn rebase for the lifetime of that workflow step. */
+        worktreeBase: z
+            .array(RepoBaseSchema)
+            .min(1)
+            .max(50)
+            .optional()
+            .describe(
+                "Pin a new private copy to these exact commits instead of today's workspace. Used when several agents must start from identical files.",
+            ),
+        // Override landing for this turn only. Workflow steps set false so candidate branches cannot leak into
+        // the workspace before the synthesis step has compared them; ordinary turns inherit agent/workspace
+        // posture exactly as before.
+        autoLand: z
+            .boolean()
+            .optional()
+            .describe(
+                "Whether this turn's work merges into the workspace when it finishes. Overrides the conversation's own setting for this turn only.",
+            ),
+        // Set ONLY by the daemon's own automation dispatchers: this turn opens a conversation on behalf of an
+        // outside message rather than a user. Recorded on the registry entry so the fleet can say where the
+        // agent came from. Requires conversationId, there is nothing to record it on otherwise.
+        origin: AgentOriginSchema.optional().describe(
+            "Set by the sandbox alone: this turn opened a conversation on behalf of a message from outside rather than a person.",
+        ),
+        // No `history` field: a turn that switched provider/account/harness carries no transcript up the wire.
+        // The daemon seeds the replacement session from its OWN record of the conversation, which is keyed by
+        // conversationId and outlives every session (sessions/turn-transcript.ts → handoffHistory).
+        /* WHERE A FORK WAS CUT FROM, on its first turn, the one case the daemon cannot work out for itself,
+         * because a fork is a NEW conversation whose record is empty and the cut is a gesture only the client
+         * saw. `keep` counts the source's RECORD rows to copy, not its bubbles (see the web transcript's
+         * recordedRows). The daemon copies that prefix into the new conversation's record before the turn runs,
+         * after which a fork is an ordinary conversation: it seeds like any other and reads back in full.
+         * Requires conversationId, the fork it describes IS that conversation.
+         *
+         * `files` is the half the user actually chooses between, and the half that used to be silent. "now"
+         * inherits the workspace as it stands (the fork is a fresh line of conversation over today's files);
+         * "then" puts the fork on the files as they were AT THE CUT, which it can only do in a checkout of its
+         * own, so it implies `isolated`, and the daemon resolves the cut's per-repo commits from the source's
+         * own turn anchors rather than trusting the client with shas. A "then" fork of a conversation that has
+         * no anchor at that index falls back to "now" and says so on the turn, because silently starting from
+         * the wrong files is the failure this whole field exists to prevent. */
+        forkOf: z
+            .object({
+                conversationId: ConversationIdSchema.describe("The conversation this one was cut from."),
+                keep: z.number().int().nonnegative().describe("How many of that conversation's messages to copy in before this turn runs."),
+                files: z
+                    .enum(["then", "now"])
+                    .describe(
+                        'Which files the fork opens on: "now" is the workspace as it stands, "then" is the files as they were at the cut, which needs a private copy.',
+                    ),
+            })
+            .optional()
+            .describe("Where this conversation was cut from, on its first turn only. Only the client knows this, so only the client can say it."),
+        // The browser sends the chosen model per turn; the provider token is the sandbox's own stored credential.
+        model: z.string().optional().describe("Which model to use. Leave it out for the provider's default."),
+        /* NOBODY PICKED A MODEL FOR THIS TURN, a surface started it (Fix with agent, a Maintenance chore, a
+         * Documentation or Acceptance run, the fix a failed pre-push check proposes) rather than a person at a
+         * composer. That is the whole distinction the flag carries, and it is why it cannot be inferred: a chat
+         * turn ALSO arrives with no `model` whenever the live catalog hasn't loaded yet, and the two want
+         * opposite defaults, the chat wants the provider's own catalog default, an unattended run wants the
+         * tier its owner chose for work that spends money while they are not watching.
+         *
+         * The daemon fills `agent`/`model`/`effort` from agentRunModels/agentRunEffort for any turn that says
+         * this and names none of them (startConversationTurn), walking that list until one can actually be
+         * started. Naming one still wins: every surface-started run now carries a caret that overrides the list
+         * for that run alone, and Acceptance picks per run because it fans a session out per story. Either way
+         * the pick is the user's, made a second ago. */
+        unattended: z
+            .boolean()
+            .optional()
+            .describe(
+                "Nobody chose a model for this turn because a screen started it rather than a person. The sandbox then fills in the model its owner picked for unwatched work.",
+            ),
+        /* OUTSIDE CONTENT CAUSED THIS TURN, and what to call the source, "discord", "webchat", whichever
+         * listener provider carried the message. Set by the dispatchers that wake an agent on somebody else's
+         * words; absent for a turn the owner started, a schedule, or a workspace event.
+         *
+         * It is the birth half of the turn's taint (guard/turn-taint.ts). The other half marks itself as the
+         * turn works, a fetched page, a foreign MCP server's answer, and together they are what the command
+         * gate reads before letting a command read credential material unasked. Distinct from `unattended`,
+         * which is about whether anyone is WATCHING: a Front Desk wake is both, an owner asking the agent to read
+         * a web page is neither, and each flag governs a different decision. */
+        outsideWake: z
+            .string()
+            .min(1)
+            .optional()
+            .describe(
+                "Content from outside caused this turn, and what to call the source. It is what makes the sandbox treat the turn as carrying somebody else's words.",
+            ),
+        // How tool calls are gated for this turn (the SDK's permissionMode, verbatim). 'plan' runs the
+        // propose → approve → execute flow; 'default' prompts per tool on the permission side channel;
+        // 'acceptEdits' auto-accepts file edits; 'bypassPermissions' runs everything. The agent can move
+        // itself between modes mid-turn (EnterPlanMode/ExitPlanMode), which rides back as a `mode` frame.
+        permissionMode: PermissionModeSchema.optional().describe(
+            "How tool calls are gated: ask each time, accept file edits, propose a plan first, or run everything. The agent can move itself between these mid-turn.",
+        ),
+        /* Narrows the turn to these tool names (the SDK option of the same name, not to be confused with the
+         * daemon's MCP `tools`, which are servers). Absent ⇒ every tool the runtime has, which is what an
+         * owner-driven chat wants. Set by the automation dispatchers from Automation.allowedTools: a wake driven
+         * by an OUTSIDE message runs bypassPermissions like any other automation turn, so for a public Front Desk
+         * this list is the actual boundary, prompt wording is advice, an empty toolbox is not. */
+        allowedTools: z
+            .array(z.string().min(1))
+            .optional()
+            .describe(
+                "Narrow the turn to these tools. Leave it out for everything the runtime has. For a turn driven by an outside message this list is the real boundary, because prompt wording is only advice.",
+            ),
+        effort: z.string().optional().describe("How hard the model should think, where the provider offers a choice."),
+        thinking: z.boolean().optional().describe("Whether to show the model's reasoning as it works."),
+        /* Ask the harness to serve this turn at fast speed, the same tokens at a higher rate, for a higher
+         * per-token price. A REQUEST, never a promise: the harness answers it against the plan, the model and
+         * the endpoint, and reports what it actually did on the `fast_mode` frame. Absent/false ⇒ standard
+         * speed, which is also what a runtime that doesn't declare the capability gets (turn-plan drops it).
+         *
+         * Not a sandbox setting, for the same reason effort isn't: it changes what a turn COSTS, so it belongs
+         * to the turn that spends it rather than to the workspace it ran in. */
+        fast: z
+            .boolean()
+            .optional()
+            .describe(
+                "Ask for the same work at a higher rate for a higher price. A request rather than a promise: the answer says what actually happened.",
+            ),
+        /* KEEP THIS TURN ON THE MODEL I PICKED: the user's veto over automatic tier selection, riding the turn
+         * like `fast` does because it changes what the turn costs and so belongs to the turn rather than to the
+         * workspace. The judge still runs and the verdict is still recorded — a deny is the strongest label the
+         * calibration ledger ever gets (UsageTurn.tierDenied) — but nothing is substituted. The composer sends
+         * its conversation-level toggle here every turn, and the registry persists it beside `fast`, so the
+         * choice survives reopening the tab. Absent ⇒ no opinion, routing follows settings.autoTier. */
+        tierHold: z
+            .boolean()
+            .optional()
+            .describe(
+                "Run exactly the model that was picked, even when the turn looks simple enough for a cheaper one. The judgement is still recorded; nothing is substituted.",
+            ),
+        // The opt-in editor context chip: what the user is looking at, folded into the prompt daemon-side.
+        editorContext: EditorContextSchema.optional().describe(
+            'What the user has open in their editor, folded into the prompt so that pointing words like "this" resolve.',
+        ),
+    })
+    // An attachment-only send (no text) is legal; an entirely empty turn is not.
+    .refine((turn) => turn.prompt.trim().length > 0 || (turn.attachments?.length ?? 0) > 0, {
+        message: "prompt or attachments required",
+    })
+    .refine((turn) => turn.isolated !== true || turn.conversationId !== undefined, {
+        message: "isolated requires conversationId",
+    })
+    .refine((turn) => turn.worktreeBase === undefined || (turn.isolated === true && turn.conversationId !== undefined), {
+        message: "worktreeBase requires an isolated conversationId",
+    })
+    .refine((turn) => turn.origin === undefined || turn.conversationId !== undefined, {
+        message: "origin requires conversationId",
+    })
+    .refine((turn) => turn.forkOf === undefined || turn.conversationId !== undefined, {
+        message: "forkOf requires conversationId",
+    })
+    // A fork that wants the files as they were needs a checkout of its own to put them in, the shared tree is
+    // everyone else's too, and rolling it back under them is what `files: "then"` must never mean.
+    .refine((turn) => turn.forkOf?.files !== "then" || turn.isolated === true, {
+        message: 'forkOf.files "then" requires isolated',
+    });
+export type AgentTurn = z.infer<typeof AgentTurnSchema>;
+/* A MODEL CHOSEN FOR ONE SURFACE-STARTED RUN, what the caret on the shared run button (<AgentRunButton>) sends
+ * along with the click that starts it.
+ *
+ * Shared rather than re-declared per route because every surface that starts an agent for the user now carries
+ * that caret, and they must all mean the same thing by it: the pair rides onto the turn as `agent`/`model`, and
+ * the daemon's own fill step then leaves it alone (turn-resume.ts fills only what is absent). ABSENT is the
+ * ordinary case and the one to keep cheap, nobody touched the caret, so `agentRunModels` answers.
+ *
+ * Both halves or neither, because a model id is only meaningful to the provider that vends it: half a pick
+ * would send a Codex model id to Claude. Routes that accept this pass it through verbatim; a model this build
+ * has never heard of is a supported pick, since the picker offers a custom-id escape hatch. */
+export const AgentRunPickSchema = z
+    .object({
+        agent: z.string().min(1).describe("Which provider."),
+        model: z
+            .string()
+            .min(1)
+            .describe("Which of its models. Both or neither, because a model name only means anything to the provider that serves it."),
+    })
+    .optional();
+export type AgentRunPick = z.infer<typeof AgentRunPickSchema>;
+// POST /agent's ack: the daemon-minted id of the detached turn run it started. The turn executes daemon-side
+// regardless of any client connection; every window, the initiator included, renders it via /agent/attach.
+export const StartedTurnSchema = z.object({
+    run: z.string().describe("The id of the run that just started. Hand it back when you attach, so the stream resumes rather than replaying."),
+});
+export type StartedTurn = z.infer<typeof StartedTurnSchema>;
+// Attach to a conversation's turn run (live, or finished within the retention window). `run`+`after` is the
+// resume cursor of a client whose stream dropped: frames after `after` replay when `run` still names the
+// current run; a mismatch (a newer turn started meanwhile) replays that run from its first frame instead.
+export const AttachTurnSchema = z.object({
+    conversationId: ConversationIdSchema.describe("Which conversation to watch."),
+    run: z
+        .string()
+        .optional()
+        .describe("The run you were watching. If a newer turn has started since, the stream replays that one from its beginning instead."),
+    after: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe(
+            "The last frame you already have. Everything after it replays, then the stream goes live. Leave it out to start from the beginning.",
+        ),
+});
+export type AttachTurn = z.infer<typeof AttachTurnSchema>;