@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/schemas/agent.ts

@@ -1,43 +1,28 @@
 import { z } from "zod";
-import { ModelRoleSchema } from "../model-roles.js";
-import { NATIVE_PROVIDERS } from "../provider-specs.js";
-import { AgentPlacementSchema } from "../runner-protocol.js";
+import { CONVERSATION_ID } from "../ids/conversation-ids.js";
+import { ModelRoleSchema } from "../models/model-roles.js";
+import { NATIVE_PROVIDERS } from "../models/provider-specs.js";
+import { AgentPlacementSchema } from "../protocol/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.
-//
-// NATIVE_PROVIDERS itself is DERIVED from the one row-per-provider table (provider-specs.ts) and imported
-// here rather than written out again, so the wire vocabulary cannot name a provider the product does not
-// describe, or miss one it does.
+// Agent runtimes the daemon can serve: native providers have dedicated adapters, `endpoint/<id>` names an installed
+// endpoint capability, anything else is an ACP agent capability id. A bare string, not an enum, so an unknown id is a
+// clean error, not a contract change.
 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 ones 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.
+// Provider naming a catalog in providers.contract.ts; an enum, not the open string above, since only native providers
+// have a daemon-held catalog to look up. An unknown id is a 400 here, not an empty list.
 export const NativeProviderParamSchema = z.object({ provider: z.enum(NATIVE_PROVIDERS) });
-// The provider naming an account on the routes whose sign-in mints the vendor's own key (minted.contract.ts).
-// The harness (agentic loop) a turn runs on, orthogonal to the provider. See AgentTurnSchema.harness.
+// The harness (agentic loop) a turn runs on, orthogonal to the provider.
 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.
+// One repo at one immutable commit; used both as the checkout instruction and as handoffs' comparison base, so a
+// multi-repo run has one provenance record instead of a hard-coded branch name.
 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.
+// What the user has open in the editor, attached only when they opt in (composer chip, off by default); folded into the
+// prompt so deictic prompts ("fix this") resolve.
 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()
@@ -45,7 +30,7 @@ export const EditorContextSchema = z.object({
         .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.
+    // Truncated client-side to the cap before it's sent.
     selection: z
         .string()
         .max(20_000)
@@ -53,48 +38,33 @@ export const EditorContextSchema = z.object({
         .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.
+// Client-minted stable conversation id; the regex is an injection guard, since isolated conversations also use it in
+// branch names and filesystem paths.
+export const ConversationIdSchema = z.string().regex(CONVERSATION_ID);
+// Where a conversation came from when nobody typed it into the browser: an automation wake carrying an outside message.
+// Set daemon-side by the receiving dispatcher; 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.
+    // Listener provider that received the message, or "webhook" for an event trigger; open string, sources are
+    // extension-declared.
     provider: z.string(),
-    // The external thread it arrived on, a Discord channel id, a widget conversation id. Absent for webhooks.
+    // External thread it arrived on (Discord channel id, 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). */
+// The class of thing asking to start a session, the admission policy's key space; derived daemon-side, never sent by a
+// client. Chat and loops are absent since both begin with the owner's own click.
 export const WakeSourceSchema = z.enum(["schedule", "event", "listener", "webchat", "issues", "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>;
-/* WHERE A COMMAND WOULD RUN, and it changes what half of these classes MEAN.
- *
- * The same string is two different acts depending on which machine reads it. `rm -rf /usr` inside this
- * container deletes files that come back with the image; on somebody's laptop it ends the laptop. A named
- * Docker volume here is a dev database the agent created three commands ago; there it is whatever they run.
- * `/work` and `/history` are this product's own trees and mean nothing on a device; `/Users` and `C:` are a
- * device's and never appear here.
- *
- * So the catalog is read with a locus (command-classes.ts CommandContext), and the classes below are the
- * answer to "what would this DO", asked of a stated place. Callers do not get to omit it: a default would be
- * one of these two answers applied silently to the other machine, which is the bug this type exists to end. */
+// Where a command would run; the same string means different things on each machine (rm -rf /usr is recoverable here,
+// fatal on a laptop). Read with a locus (command-classes.ts CommandContext); callers must state one rather than
+// default.
 export const CommandLocusSchema = z.enum([
     // This sandbox's own shell: a disposable container, /work a git worktree, /history every other agent's.
     "sandbox",
@@ -102,42 +72,18 @@ export const CommandLocusSchema = z.enum([
     "device",
 ]);
 export type CommandLocus = z.infer<typeof CommandLocusSchema>;
-/* 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.
- *
- * Six, chosen for one property: everything in them is hard or impossible to take back SOMEWHERE, 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. "Somewhere" is the locus above: which class a command lands in is asked of a place. */
+// What kind of thing a shell command is, the command gate's key space under the admission floor; gates one command
+// inside an already-running session. Six classes, chosen because each is hard or impossible to undo somewhere.
 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 brings back AT THIS LOCUS: a formatted or overwritten disk, and a recursive delete aimed
-     * at a root rather than at something inside one. The 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.
-     *
-     * WHICH ROOTS COUNT IS THE LOCUS'S ANSWER, not a constant. In the sandbox it is `/` and `/history` — the
-     * filesystem itself, and the one tree holding work this turn cannot recreate because it is other
-     * conversations'. `/usr`, `/etc`, `/work` are NOT roots here: the container comes back from its image and
-     * the worktree's delta is uncommitted changes, both of which cost an afternoon rather than everything. On a
-     * device the full list applies, because nothing there is rebuilt from an image. */
+    // State nothing recovers at this locus; which roots count (/, /history in the sandbox) depends on the locus.
     "system.destructive",
-    /* A CONTAINER VOLUME OR THE DATA IN IT: `docker volume rm`, `system prune`, `compose down -v`. Split out of
-     * system.destructive because the two loci disagree about it more sharply than about anything else in this
-     * enum. In the sandbox these reach the NESTED engine (the host's socket is never mounted, see
-     * capabilities/handlers/docker.ts), so the blast radius is dev databases the agent has been working
-     * against, and tearing down a smoke-test stack is ordinary work. Sent to somebody's own computer it is
-     * whatever they run on it, and their policy says never. */
+    // A container volume or its data; the sandbox's blast radius (nested engine) differs sharply from a device's.
     "container.state",
-    /* READS credential material: a `{{secret:NAME}}` reference (which becomes the value on the way into the
-     * process), or a file that actually holds one — a dotenv, a private key, ~/.aws/credentials, an npmrc.
-     * "Actually" is load-bearing and is checked rather than assumed where the caller can open the file: an
-     * npmrc with no token in it, a dotenv of ports, a public key, a path that is not there, are none of them
-     * this class, however much they look like it from the command line. See command-classes.ts. */
+    // Reads credential material: a secret reference, or a file confirmed to actually hold one.
     "secrets.access",
     // Publishes outward and irreversibly: npm/pnpm/yarn/cargo publish, gh release create, docker push.
     "package.publish",
@@ -145,112 +91,80 @@ export const CommandClassSchema = z.enum([
     "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. */
+// Workspace-wide admission floor per wake source, consulted on every outside-driven wake; composes with per-automation
+// overrides most-restrictive-wins. `workflow` is allow|deny only, since a hold there is indistinguishable from a CI
+// runner's timeout.
 export const AdmissionPolicySchema = z.object({
     schedule: AdmissionRuleSchema.default("allow"),
     event: AdmissionRuleSchema.default("allow"),
     listener: AdmissionRuleSchema.default("allow"),
     webchat: AdmissionRuleSchema.default("allow"),
-    /* THE ONE SOURCE THAT HOLDS BY DEFAULT, and the exception is argued rather than assumed. A Front Desk wake
-     * runs the read-only Front Desk persona: a stranger drives the prompt and the toolbox is a shelf of two.
-     * A bug-report wake is the opposite on both counts, it is pointed at the repository with the powers to
-     * change it, and the brief is a stack trace and a sentence somebody else's browser wrote.
-     *
-     * Held is not blocked: the wake sits in the same approvals queue every other hold uses, with the issue's
-     * own title on the card, and one click runs it. An owner who wants their crashes fixed while they sleep
-     * sets this to `allow` deliberately, which is the direction that decision should have to be made in. */
+    // Defaults to hold, unlike the others: a bug-report wake has full repo powers and a stranger's stack trace as its
+    // brief.
     issues: AdmissionRuleSchema.default("hold"),
     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.
+// How tool calls are gated, the Claude Agent SDK's PermissionMode narrowed to the four the composer offers. Both a turn
+// input and the payload of the `mode` frame, since the agent can move itself between them mid-turn.
 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. */
+// Where a conversation was cut from, the durable half of a fork, carried on the registry entry. `index` is the message
+// the cut sat above in the source, so its transcript can put the mark back.
 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.
+    // Which files this fork opened on; kept so the fork can still say it later, not only right 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.
+        // Seeds a fresh registry entry's title; an existing entry's title always wins over this.
         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.
+        // Already uploaded via /workspace/upload; Claude reads them via Read, Codex gets images as native input.
         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.
+        // Which provider serves the turn, absent = claude; a sessionId resumes only on the provider that minted it.
         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.
+        // Which agentic loop runs the turn, absent = provider's own; "claude-code" forces the SDK loop for any
+        // provider.
         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. */
+        // Distinct from `account` (who pays): whose name the turn posts as; absent means something different for each
+        // mode.
         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.
+        // Stable id surviving provider/account/harness switches; keys the registry entry, the turn run, and 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.
+        // Runs in the conversation's own git worktree (created lazily) instead of shared /work; 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. */
+        // Decided like `isolated`: the request's choice on the first turn, the registry's after. `runner` implies
+        // isolation; absent means local.
         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. */
+        // Pins a new isolated conversation's worktree to these commits; a workflow step's candidates share one snapshot
+        // and skip the ordinary rebase.
         worktreeBase: z
             .array(RepoBaseSchema)
             .min(1)
@@ -259,55 +173,27 @@ export const AgentTurnSchema = z
             .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.
+        // Overrides landing for this turn only; a workflow step sets false so candidates can't leak in before synthesis
+        // compares them.
         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.",
             ),
-        /* WHAT STARTED THIS TURN, when it was not a person at a composer, and therefore which of the owner's
-         * model lists answers for it (settings.modelRoles, model-roles.ts declares the roles).
-         *
-         * IT NAMES THE JOB, NOT THE TIER. Before this field there was one list for every unattended turn, so a
-         * production incident and a documentation sweep were configured together, and a surface added tomorrow
-         * inherited that tier by saying nothing. Now a starter says what it IS, and the owner gets to answer
-         * per job: cheap for the sweep, frontier for the incident.
-         *
-         * ONLY FILLS A SILENCE. The daemon applies the role's list to a turn that named no model AND no
-         * provider (turn-resume.ts): a caret pick, an acceptance run's own choice, a workflow step pinned to a
-         * provider — all of those already answered the question, and this must not overrule them.
-         *
-         * A `run` role, always. The `helper` roles never reach here: a one-shot is not a turn, it has no
-         * conversation and no worktree, and it asks its own role directly at the seam that spends it. */
+        // Which per-job model list answers when nobody named a model or provider (turn-resume.ts); names the job, not a
+        // tier, and never overrides an explicit pick.
         runRole: ModelRoleSchema.optional().describe(
             "What started this turn, when it was not a person typing: which of the sandbox's per-job model lists answers for it. Only used when the turn names no model of its own.",
         ),
-        // 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.
+        // Set only by the daemon's own dispatchers, never a client; requires conversationId to record it on.
         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. */
+        // No `history` field: a provider/account/harness switch carries no transcript over the wire; the daemon seeds
+        // the new session from its own conversationId-keyed record.
+        // Where a fork was cut from, on its first turn only; requires conversationId, and files:"then" implies
+        // isolated.
         forkOf: z
             .object({
                 conversationId: ConversationIdSchema.describe("The conversation this one was cut from."),
@@ -322,33 +208,15 @@ export const AgentTurnSchema = z
             .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` and the pinned entry's own knobs from the turn's own role list 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. */
+        // True when a surface started the turn, not a person; the sandbox then fills the model from the owner's role
+        // list for unwatched work.
         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. */
+        // Outside content caused this turn, naming the source; distinct from `unattended` (whether anyone is watching).
         outsideWake: z
             .string()
             .min(1)
@@ -356,18 +224,17 @@ export const AgentTurnSchema = z
             .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.
+        // How tool calls are gated for this turn (the SDK's permissionMode, verbatim):
+        // plan: propose → approve → execute
+        // 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, riding 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. */
+        // Narrows the turn to these tool names (the SDK option, not the daemon's MCP `tools`/servers); absent means
+        // everything the runtime has.
         allowedTools: z
             .array(z.string().min(1))
             .optional()
@@ -376,25 +243,16 @@ export const AgentTurnSchema = z
             ),
         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. */
+        // Requests the harness serve this turn faster at a higher price; a request, not a promise, the `fast_mode`
+        // frame reports what happened.
         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. */
+        // Vetoes automatic tier selection for this turn; the judge still runs and records its verdict, but nothing is
+        // substituted.
         tierHold: z
             .boolean()
             .optional()
@@ -422,8 +280,7 @@ export const AgentTurnSchema = z
     .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.
+    // "then" needs a checkout of its own; rolling back the shared tree under everyone else is what it must never mean.
     .refine((turn) => turn.forkOf?.files !== "then" || turn.isolated === true, {
         message: 'forkOf.files "then" requires isolated',
     });
@@ -440,12 +297,18 @@ export type AgentTurn = z.infer<typeof AgentTurnSchema>;
  * 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.
  *
- * AND THE TIER IT RUNS AT, because naming a model is only half of what the standing setting says. A pinned
- * entry carries its own effort (ModelPinSchema), and the daemon applies the pin's knobs ONLY to a turn that
- * named no model (turn-resume.ts): so a caret that could re-point the model but not the tier moved every
- * override onto the provider's own default effort, and the one moment somebody reaches for the caret is the
- * failure that just beat the standing order. Optional, and absent means absent, the turn goes out without an
- * effort and the model's own answers. */
+ * AND EVERYTHING ELSE THE PANEL CAN SET, which is the half this schema used to drop on the floor. A pinned entry
+ * carries its own account, harness, effort, thinking and speed (ModelPinSchema), the daemon applies a pin's
+ * knobs ONLY to a turn that named no model (turn-resume.ts), and the picker the caret opens offers every one of
+ * them — so a pick that carried the pair alone moved each override onto the provider's own defaults for the
+ * rest. That is worst exactly where the caret gets reached for: the one moment somebody opens it is the failure
+ * that just beat the standing order, and a run re-pointed at a frontier model but not at the tier, the loop or
+ * the account that model was pinned under is not the run they configured.
+ *
+ * The fields are AgentTurn's own (it carries all five already), so a route that accepts this spreads it onto
+ * the turn verbatim. Every one is optional and absent means absent: the turn goes out without the field and the
+ * model's own default answers. `thinking: false` is therefore a different statement from no thinking at all,
+ * which is the distinction Claude's own refusal of `max` beside disabled thinking turns on. */
 export const AgentRunPickSchema = z
     .object({
         agent: z.string().min(1).describe("Which provider."),
@@ -453,13 +316,44 @@ export const AgentRunPickSchema = 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."),
+        account: z
+            .string()
+            .optional()
+            .describe("Which connected account of that provider pays, by its daemon-minted id. Leave it out for whichever has headroom."),
+        harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it. Leave it out to use the provider's own."),
         effort: z
             .string()
             .optional()
             .describe("How hard that model should think, where it offers a choice. Leave it out to take the model's own default."),
+        thinking: z.boolean().optional().describe("Whether this model reasons before it answers, where that is a choice it offers."),
+        fast: z.boolean().optional().describe("Ask for this model's work at a higher rate for a higher price. A request rather than a promise."),
     })
     .optional();
 export type AgentRunPick = z.infer<typeof AgentRunPickSchema>;
+/* THE PICK A RUN BUTTON HOLDS, AS THE WIRE SPELLS IT. The picker answers in the shell's own vocabulary
+ * (`provider`, the kit's AgentRunChoice) and a turn calls the same field `agent`, so every surface that starts
+ * an agent had this translation written out by hand — seven of them, each re-deciding which fields to carry,
+ * which is exactly how the tier came to travel from four of them and the account from none.
+ *
+ * ABSENT STAYS ABSENT, field by field: `undefined` means the turn goes out without it and the model's own
+ * default answers, which is not the same as any value this could invent. */
+export const runPickOf = (choice: {
+    readonly provider: string;
+    readonly model: string;
+    readonly account?: string | undefined;
+    readonly harness?: string | undefined;
+    readonly effort?: string | undefined;
+    readonly thinking?: boolean | undefined;
+    readonly fast?: boolean | undefined;
+}): NonNullable<AgentRunPick> => ({
+    agent: choice.provider,
+    model: choice.model,
+    ...(choice.account === undefined ? {} : { account: choice.account }),
+    ...(choice.harness === undefined ? {} : { harness: choice.harness as AgentHarness }),
+    ...(choice.effort === undefined ? {} : { effort: choice.effort }),
+    ...(choice.thinking === undefined ? {} : { thinking: choice.thinking }),
+    ...(choice.fast === undefined ? {} : { fast: choice.fast }),
+});
 /* ONE ENTRY OF ONE ROLE'S MODEL LIST (settings.modelRoles): the standing version of the pick above, and not
  * merely which model but HOW it is to be run.
  *
@@ -500,16 +394,14 @@ export const ModelPinSchema = z.object({
     harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it. Leave it out to use the provider's own."),
 });
 export type ModelPin = z.infer<typeof ModelPinSchema>;
-// 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.
+// POST /agent's ack: the daemon-minted id of the detached run it started. The turn runs daemon-side regardless of any
+// client connection; every window 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). The head carries the
-// run's rows whole, so there is no cursor to resume from: a client that reconnects takes the rows again and
-// applies what follows. `run` names the run the client was watching, so the head's own id tells it whether a
-// newer turn has started meanwhile.
+// Attaches to a conversation's run (live, or finished within retention); no cursor to resume from, the head carries all
+// rows. `run` names what the client was watching, so a newer run's head id tells it to catch up.
 export const AttachTurnSchema = z.object({
     conversationId: ConversationIdSchema.describe("Which conversation to watch."),
     run: z