@intentic/sandbox-contract 1.231.0 → 1.233.0

package/src/schemas/personas.ts

@@ -0,0 +1,281 @@
+// Personas: the named faces a sandbox shows the outside world — which accounts each speaks for, what a
+// session wearing one may do, and where it works.
+import { z } from "zod";
+import { entryId } from "./internal.js";
+import { SkillDraftSchema, SkillNameSchema, SystemPromptModeSchema } from "./settings.js";
+/* A NAMED PERSONA THE SANDBOX SHOWS THE OUTSIDE WORLD, "work-reddit", "the studio account", and the layer
+ * that decides which connected accounts a given turn may act through.
+ *
+ * IT ANSWERS FOUR QUESTIONS AND NO MORE: who it speaks as, what it may do, where it works, and what it is told.
+ * Making one is then a name, a few accounts, some switches and, only if you want one, a prompt. That is the
+ * whole of what an owner is deciding, and short enough that they finish.
+ *
+ *   NO PUBLISH-OR-DRAFT SWITCH. It read as a lock and was a sentence: it asked the turn to route outward things
+ *   through the approvals queue and could not stop it posting. The queue is the mechanism, and a control whose
+ *   label promises more than it delivers is worse than no control, it is the one an owner trusts.
+ *
+ *   THE FOURTH QUESTION IS THE SYSTEM PROMPT, NOT A TONE NOTE, and the difference is why the field that used to
+ *   sit here was removed and this one is not it. What was removed was a paragraph on how a persona WRITES:
+ *   optional, answered by almost nobody, and shaping nothing a person could see afterwards. `systemPromptMode`
+ *   is the same setting the sandbox has, asked per card, it replaces the whole prompt, and with the kit folder
+ *   beside it (persona-kit.ts) a card can carry its own skills and tools too. That is a persona being a working
+ *   posture rather than a label, and it shows: a release-notes writer and a code reviewer are two prompts, not
+ *   two adjectives.
+ *
+ * THE CARD AND THE KEYS ARE DELIBERATELY SEPARATE. This is the card: a name, the accounts it speaks for, what a
+ * session wearing it may do, where it works. It carries NO credential, which is what lets it be the one thing under
+ * .intentic that is committed and reviewed like the workspace's instructions are (see personas-store.ts for
+ * the exclude carve-out that makes that true). The keys, the logged-in browser profile, its cookies, its
+ * passkey, stay where they already are: private to the sandbox, never exported without an explicit opt-in. So a
+ * cloned workspace arrives listing its personas, each visibly unconnected, waiting for one sign-in apiece.
+ *
+ * WHAT IT IS NOT is a security boundary. A chat still reaches every connected account by default (that is the
+ * owner's chosen posture, a chat has a human in the room), and an agent with a shell can reach a token whatever
+ * this file says. What it prevents is the mistake this codebase already names as the one that cannot be undone:
+ * a post from the wrong account. Where nobody is watching, an unattended wake, it is a real fence, because
+ * there the resolver's default is NOTHING rather than everything (see turnPersona in personas.ts). */
+/* WHAT A PERSONA MAY DO, the shelves, one switch each, and the half of the card that bounds the turn rather
+ * than the account it speaks for.
+ *
+ * SHELVES, NOT TOOL NAMES. Every field here is a phrase a person decides about ("run commands", "read the
+ * web"), never the name of a tool. Tool names drift with every runtime upgrade, one power answers to several of
+ * them, and a connector is not a tool at all, it is a shell command plus a credential. Naming the shelf means
+ * a tool added next month lands inside an answer the owner already gave, and a card written today still means
+ * what it said after the SDK renames something.
+ *
+ * TWO STRENGTHS, AND THE DIFFERENCE IS VISIBLE FROM HERE. Everything capability-shaped (`connectors`,
+ * `computers`, `mcp`, and the accounts in `capabilities`) is enforced by ABSENCE, the credential is never
+ * injected, the server never mounted, the browser never launched, which is the same mechanism the account
+ * filter already uses and needs no cooperation from the model. The plain switches are enforced by taking the
+ * tools out of the turn's context, which holds for every tool the harness owns and cannot reach a program the
+ * agent runs for itself.
+ *
+ * WHICH IS WHY `shell` IS THE ONE THAT DECIDES. A session with a shell can read a credential this card never
+ * granted it, so switching it off is what turns the rest of these into a fence; leaving it on leaves them a
+ * strong default. The card's own UI says so at the switch, see PersonaForm.vue, because a limit that is
+ * weaker than it looks is worse than no limit at all.
+ *
+ * PERMISSIVE BY DEFAULT, deliberately, and the opposite of the account rule directly below it. An unrepeatable
+ * public post is worth defaulting to nothing for; an over-powered turn inside a container the owner can throw
+ * away is not, and it is the same reasoning that makes bypassPermissions this sandbox's default posture. So an
+ * absent `powers` means today's full toolbox, and a workspace that never opens this notices nothing. */
+export const PersonaPowersSchema = z.object({
+    // "read" is look-and-search only; "write" adds creating and changing; "none" takes both away.
+    files: z
+        .enum(["none", "read", "write"])
+        .default("write")
+        .describe("What it may do with files: nothing, look and search, or also create and change."),
+    // Shell commands, and with them the terminals, the test runs, and every CLI on the image. See the header:
+    // this is the switch the others' strength depends on.
+    shell: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Whether it may run commands, and with them the terminals, the test runs and every tool on the image. The switch the strength of the others depends on.",
+        ),
+    /* The JS execution backend (AgentCapabilities.execution): the model writes a script instead of a command
+     * line, run in a permission-fenced Node subprocess. Its fence is REAL where the shell's is not, reads and
+     * writes follow the `files` answer, and it can start no other program unless `shell` is also on, with one
+     * stated gap: the fence cannot cut the network, so a script can fetch whatever `web` says. */
+    code: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Whether it may write and run a script rather than a command line. Its fence is real where the shell's is not: reads and writes follow the files answer, and it can start no other program unless commands are allowed too. The one stated gap is that the fence cannot cut the network.",
+        ),
+    // Fetch a page, run a search.
+    web: z.boolean().default(true).describe("Whether it may fetch a page or run a search."),
+    // The credential-free browser. The SIGNED-IN browsers are `capabilities` below, a different question, and
+    // the reason this one is safe to leave on: it holds nobody's account.
+    browser: z.boolean().default(true),
+    // Spawn sub-agents and run workflows.
+    delegate: z.boolean().default(true),
+    /* Change the sandbox itself: its settings and manifests, and the public outbox that publishes a file to
+     * anyone with the link. Enforced as a refusal on the paths that carry those, not as a tool switch, there
+     * is no "install a capability" tool to take away, only files that mean it. */
+    sandbox: z.boolean().default(true),
+    /* The connected accounts and services this persona may reach, BY ID. Absent means every one of them, which
+     * is what a card that has never thought about it should get; an empty list means none. That tri-state is the
+     * whole reason these are optional rather than defaulted arrays, "all" and "none" are both real answers and
+     * an empty default could only spell one of them. */
+    connectors: z.array(entryId).max(100).optional(),
+    computers: z.array(entryId).max(50).optional(),
+    mcp: z.array(entryId).max(50).optional(),
+});
+export type PersonaPowers = z.infer<typeof PersonaPowersSchema>;
+/* WHERE A PERSONA WORKS, the third question after who it is and what it may do.
+ *
+ * `folders` is the one field here that promises less than it looks like it promises, and the card says so where
+ * it is set: it is enforced by refusing file tool calls that point outside, which stops a misread instruction
+ * and an honest mistake, and does not stop a shell. The workspace-wide fence is the container. */
+/* WHERE A SESSION WEARING THIS CARD WORKS, the folder it opens in, and the folders its file tools may touch.
+ *
+ * There is no placement field, and that is a decision rather than an omission. A card used to be able to ask
+ * for the SHARED tree instead of its own copy; every surface already defaults to a private worktree
+ * (conversation.ts), so the setting existed only to opt out of the isolation that makes parallel work safe,
+ * expressed in three words ("whatever started it", "its own copy", "the shared workspace") that a reader had no
+ * way to choose between. A persona starts where it is told and works in its own copy. */
+export const PersonaWorkspaceSchema = z.object({
+    // The repo (or folder) under the workspace a session starts in. Absent ⇒ the workspace root, as today.
+    startIn: z.string().max(200).optional().describe("Which folder a conversation opens in."),
+    // Workspace-relative folders the file tools may touch. Absent ⇒ anywhere under the workspace.
+    folders: z.array(z.string().min(1)).max(50).optional().describe("Which folders it may touch at all. Absent means the whole workspace."),
+});
+export type PersonaWorkspace = z.infer<typeof PersonaWorkspaceSchema>;
+export const PersonaSchema = z.object({
+    id: entryId.describe("The persona's id."),
+    // What the owner calls it in the composer chip. Absent ⇒ surfaces read the id, which is already human-chosen.
+    label: z.string().max(60).optional().describe("What to call it on screen. Absent falls back to the id, which somebody chose anyway."),
+    /* The capability ids this persona acts THROUGH, the logged-in browser accounts (and, later, the credential
+     * connectors) that are its hands. Ids rather than platforms, because "two accounts of one site" is the whole
+     * problem: `reddit-work` and `reddit-personal` are two capabilities and exactly one of them belongs here.
+     *
+     * An id naming a capability that isn't connected is not an error, it is a card describing an account this
+     * sandbox has yet to sign into, which is precisely what a freshly cloned workspace looks like. */
+    capabilities: z
+        .array(entryId)
+        .max(50)
+        .describe(
+            "Which connected accounts are its hands. Named individually rather than by site, because two accounts on one site is the whole problem this solves. Naming one that is not connected yet is not an error: it is a card describing an account this sandbox has still to sign into.",
+        ),
+    /* Which workspace repos prefer this persona, so a chat opened on a project starts with the right chip already
+     * selected. A PREFERENCE, not a fence, the owner's chosen chat default is still "every account", and it
+     * lives on the card rather than in each project's own config so that one account named by three repos stays
+     * one definition instead of three that drift. */
+    repos: z
+        .array(z.string().min(1))
+        .max(50)
+        .optional()
+        .describe(
+            "Which repositories prefer this persona, so a conversation opened on one starts with the right choice already made. A preference rather than a fence.",
+        ),
+    // What a session wearing this card may do, and where it works. Both absent ⇒ the full toolbox and the whole
+    // workspace, so a card written before these existed keeps behaving exactly as it did.
+    powers: PersonaPowersSchema.optional().describe(
+        "What a conversation wearing it may do. Absent means the full toolbox, so a card written before this existed behaves exactly as it did.",
+    ),
+    workspace: PersonaWorkspaceSchema.optional().describe("Where it works. Absent means the whole workspace."),
+    /* WHICH SYSTEM PROMPT A SESSION WEARING THIS CARD RUNS ON, the same three bases the sandbox chooses
+     * between, asked per card. ABSENT is the fourth answer and the default: follow the sandbox, which is what
+     * every card meant before this field existed and what almost every card will go on meaning.
+     *
+     * Absent rather than a fifth enum value spelling the same thing. "inherit" and "not set" would be two
+     * spellings of one answer, and the surface that offers four options maps its first to leaving this off.
+     *
+     * THE TEXT IS NOT HERE. Under "custom" it is `PROMPT.md` in the card's own kit folder
+     * (personas/persona-kit.ts), for two reasons that point the same way: a system prompt is prose, and prose
+     * belongs in a file where it diffs line by line rather than as one escaped string inside a record nobody
+     * writes by hand, and the kit is already where that persona's skills and tools live, so there is one folder
+     * to look in rather than a field here and a directory there.
+     *
+     * "custom" with no PROMPT.md written yet falls back to the sandbox's answer rather than running the turn on
+     * an empty prompt: the card is half-made, and a half-made card should behave like the one it was before
+     * somebody started editing it. */
+    systemPromptMode: SystemPromptModeSchema.optional(),
+});
+export type Persona = z.infer<typeof PersonaSchema>;
+/* THE ONE CARD ID THE PRODUCT NAMES ITSELF, the read-only persona a public web chat answers through.
+ *
+ * Nothing else is stock: a fresh workspace has no personas at all, and every card on the Personas page is one
+ * the owner wrote. This id is the exception because a Front Desk is driven by a stranger with nobody watching, so
+ * it is the one wake whose bounds cannot be left to the prompt's wording, the daemon writes the card the moment
+ * a Front Desk is saved (personas/front-desk.ts) and the automations form fills a blank Front Desk persona with it.
+ *
+ * It lives HERE because those two are in different packages and must agree exactly. A literal in each would
+ * drift into a Front Desk pinned to a card nobody creates, and turnPersona answers a missing card by denying
+ * everything, a public chat that cannot even read, which is safe and useless.
+ *
+ * It is FRONT DESK and not "visitor": the card is who answers the people who arrive, not the person arriving. */
+export const FRONT_DESK_PERSONA = "front-desk";
+/* HOW BOUNDED A CARD IS, in one phrase, for the row badge on the Personas page and for the sentence under the
+ * automations composer's persona picker.
+ *
+ * It lives in the contract rather than in either surface because those two are in different packages and would
+ * otherwise each grow their own vocabulary for the same card: a workspace where the Personas page says
+ * "Read-only" and the automation under it says "3 limits" is one where the reader cannot tell whether they are
+ * looking at the same thing.
+ *
+ * TWO NAMED SHAPES AND THEN A COUNT. "Read-only" and "no shell" are the two people actually reach for, so they
+ * get words; everything else gets a number, because listing four switched-off shelves in a badge produces a line
+ * nobody reads and buries the one fact that matters, that this card is limited at all. */
+export const personaBounds = (persona: Persona): string => {
+    const powers = persona.powers;
+    if (powers === undefined) {
+        return "Full powers";
+    }
+    const resolved = PersonaPowersSchema.parse(powers);
+    if (resolved.files === "read" && !resolved.shell) {
+        return "Read-only";
+    }
+    if (!resolved.shell) {
+        return "No shell";
+    }
+    const limits = [
+        resolved.files === "none",
+        !resolved.code,
+        !resolved.web,
+        !resolved.browser,
+        !resolved.delegate,
+        !resolved.sandbox,
+        resolved.connectors !== undefined,
+        resolved.computers !== undefined,
+        resolved.mcp !== undefined,
+    ].filter(Boolean).length;
+    return limits === 0 ? "Full powers" : `${limits} limit${limits === 1 ? "" : "s"}`;
+};
+export const PersonaIdParamSchema = z.object({ id: entryId.describe("Which persona.") });
+/* Every persona, plus which of the accounts they name this sandbox is actually signed into. The second half is
+ * what makes the list honest on a freshly cloned workspace: every card is present and most of them cannot act
+ * yet, and a surface that showed only the cards would present a persona that is one login away from working as
+ * though it already did. Ids the manifest has no capability for at all are `connected: false` too, a card may
+ * name an account nobody has added here. */
+export const PersonasListSchema = z.object({
+    personas: z.array(PersonaSchema).describe("The characters an agent can wear."),
+    connected: z
+        .array(z.string())
+        .describe(
+            "Which accounts are actually connected right now, so a persona naming one that has since been disconnected can be shown as broken rather than as working.",
+        ),
+});
+/* A PERSONA'S KIT, as one read, the prompt it runs on and the skills it carries.
+ *
+ * ONE ROUTE FOR BOTH because they are one folder and one screen: the card's editor draws them together, and two
+ * requests to render one section is two chances for it to arrive half-drawn. The skills come back as name and
+ * description only, for the same reason the sandbox's own skill list does, a body runs to thousands of words
+ * and a group of one-line rows should not cost a hundred kilobytes to draw.
+ *
+ * An empty prompt is a card with no PROMPT.md, which is every card until somebody writes one. It is "" rather
+ * than absent because the field behind it is a textarea, and a textarea's empty value is "". */
+export const PersonaKitSchema = z.object({
+    prompt: z
+        .string()
+        .describe("What this persona is told, on top of everything else. Empty means it simply follows the sandbox's own instructions."),
+    skills: z
+        .array(
+            z.object({
+                name: z.string().describe("The skill's name."),
+                description: z.string().describe("What it is for."),
+            }),
+        )
+        .describe(
+            "Skills only this persona's conversations can reach. A different question from what the agent knows generally, with a different answer.",
+        ),
+});
+export type PersonaKit = z.infer<typeof PersonaKitSchema>;
+export const PersonaPromptSchema = PersonaIdParamSchema.extend({
+    prompt: z
+        .string()
+        .max(20000)
+        .describe(
+            "What to tell this persona. Sending an empty one removes it entirely rather than storing a blank, so the persona falls back to the sandbox's own instructions.",
+        ),
+});
+export const PersonaSkillSchema = PersonaIdParamSchema.extend(SkillDraftSchema.shape);
+export const PersonaSkillNameSchema = PersonaIdParamSchema.extend({ name: SkillNameSchema.describe("Which skill.") });
+// One kit skill's instructions, for editing it, the same split the sandbox's own skills make between a listing
+// and a body, and for the same reason.
+export const PersonaSkillBodySchema = z.object({
+    name: z.string().describe("The skill's name."),
+    description: z.string().describe("What it is for."),
+    body: z.string().describe("The skill itself, in full."),
+});

package/src/schemas/plan-limits.ts

@@ -0,0 +1,255 @@
+import { z } from "zod";
+import { EditorContextSchema } from "./agent.js";
+// Declared ABOVE both account shapes because both carry it: headroom is one idea in this product, not a Claude
+// idea that other providers imitate. A native account (OauthAccount) and a routed subscription
+// (TranslatorAccount) differ in who holds the credential and how the reading is taken, never in what a
+// reading IS, so every surface that draws a percentage reads this one type and no other.
+
+// One plan-limit pool. `kind` is the provider's own key ('five_hour' | 'seven_day' | 'seven_day_opus' |
+// 'seven_day_sonnet' | 'model:Fable' | …) rather than an enum we'd have to keep in step with the provider: an
+// unrecognised pool is shown under its raw key, which is far better than being silently folded into a
+// neighbour. `label` is the provider's OWN display name where it supplies one (the per-model buckets do), it
+// wins over anything we'd infer, because the model names in a plan's limits are the provider's to rename.
+// `resetsAt` is epoch SECONDS (matching the SDK's frame).
+export const UsageWindowSchema = z.object({
+    kind: z.string(),
+    label: z.string().optional(),
+    utilization: z.number(), // 0-100
+    resetsAt: z.number().optional(),
+});
+export type UsageWindow = z.infer<typeof UsageWindowSchema>;
+// An account's headroom: EVERY window the provider reports, read together, plus when the reading was taken.
+// All of them, not the binding one, because "which pool is binding" changes between turns and a reader
+// comparing accounts needs the same pools on every row. How the reading is TAKEN is per provider and stops at
+// the daemon's readers: Claude's rides the turn's own stream, ChatGPT's, Google's and Kimi's are pulled through
+// CLIProxyAPI's credential-scoped management call. All of them are control requests, so none costs tokens.
+//
+// Within one window utilization only climbs, so an un-reset window stays a valid FLOOR however old it is; past
+// its `resetsAt` it describes a pool that no longer exists and the store drops it. `measuredAt` is epoch MS
+// (matching connectedAt), deliberately a different unit from the windows' seconds.
+export const AccountUsageSchema = z.object({
+    windows: z.array(UsageWindowSchema),
+    measuredAt: z.number(),
+});
+export type AccountUsage = z.infer<typeof AccountUsageSchema>;
+/* THE LAST TIME A PROVIDER ACTUALLY REFUSED A TURN, the other half of "can I run on this", and the half no
+ * meter can supply.
+ *
+ * A snapshot above is POLLED and therefore always a floor: read at turn end (Claude) or on a five-minute sweep
+ * (the routed subscriptions), and account-wide, so every other client on the plan spends the same pools without
+ * this sandbox hearing about it. A refusal is the opposite kind of fact, observed, exact, and timestamped by
+ * the only event that proves the plan said no. Between them they answer a question neither can alone: a green
+ * meter beside "refused a turn 4 minutes ago" means the reading is stale, not that the account has room.
+ *
+ * Keyed by PROVIDER rather than by account, because that is the resolution the daemon honestly has. A native
+ * Claude turn knows which account served it and names it; a routed turn does not. CLIProxyAPI picks the auth
+ * file itself and only refuses once every credential it holds is cooling down, which makes the refusal a fact
+ * about the provider in the first place.
+ *
+ * `kind` is read off what the provider SAID, not off the frame code the harness filed it under, because those
+ * two disagree: Kimi answers a spent plan with `403 You've reached your usage limit for this billing cycle`,
+ * which the CLI prints under "Failed to authenticate" and the stream codes as a refused credential. Sending
+ * someone to reconnect a perfectly good account is the cost of believing the code over the sentence. */
+export const ProviderRefusalSchema = z.object({
+    // Epoch MS, matching AccountUsage.measuredAt, the two are read side by side.
+    at: z.number().describe("When it refused, in milliseconds."),
+    /* Three ways a plan says no, kept apart because WHAT ANSWERS EACH is different and a screen that conflates
+     * them tells the user to do the wrong thing. A spent allowance is answered by a later reading with room in
+     * it; a refused credential by the account being read at all through it; and an entitlement refusal, an
+     * organization that has turned Claude Code off for this seat, by NOTHING either of those can produce. Its
+     * token authenticates and its usage endpoint answers with real pools the whole time it cannot run a turn,
+     * so filing it as `auth` let the very next quota sweep dismiss it and leave a full green ring over an
+     * account that refused everything asked of it. Only a turn that actually runs settles this one. */
+    kind: z
+        .enum(["limit", "auth", "entitlement"])
+        .describe(
+            "Three different noes, kept apart because what fixes each is different. A spent allowance is answered by waiting; a refused credential by signing in again; and an entitlement refusal, where somebody has switched this off for your seat, by neither of those. That last one authenticates fine and reports healthy limits the whole time it refuses everything.",
+        ),
+    // The provider's own sentence, verbatim. It is the only part that says WHICH pool or WHICH credential.
+    message: z.string().describe("The provider's own words, verbatim. The only part that says which limit or which credential."),
+    // The account that was serving, when the daemon knows it (native turns only, see above).
+    account: z.string().optional().describe("Which account was serving, where that is known."),
+});
+export type ProviderRefusal = z.infer<typeof ProviderRefusalSchema>;
+export const ProviderRefusalsSchema = z.object({
+    refusals: z
+        .record(z.string(), ProviderRefusalSchema)
+        .describe(
+            "The most recent refusal per provider. Read alongside an account's usage: that says how full it was when last checked, this says whether it has since started saying no.",
+        ),
+});
+export type ProviderRefusals = z.infer<typeof ProviderRefusalsSchema>;
+// One connected subscription in the translator. `name` is CLIProxyAPI's auth-file name, the stable store key a
+// disconnect addresses, and `label` the sign-in identity it reported (the account email, else the file name).
+export const TranslatorAccountSchema = z.object({
+    name: z.string(),
+    label: z.string(),
+    // The same headroom an OauthAccount carries, on the same field, for the same reason: the account rows are
+    // one list to the reader. Optional because a provider whose quota this sandbox cannot read (Grok),
+    // or one that did not answer, must still render as the connected account it is, with a dot instead of a
+    // ring.
+    usage: AccountUsageSchema.optional(),
+});
+export type TranslatorAccount = z.infer<typeof TranslatorAccountSchema>;
+// Which routed-provider subscriptions are connected in the translator, per provider, a LIST per provider, not
+// a flag: CLIProxyAPI holds any number of auth files per provider side by side and balances requests across
+// them, so connecting a second ChatGPT or Google account is more headroom, and each is disconnectable on its
+// own. Drives the account rows in Sandbox ▸ Agent.
+export const TranslatorAccountsSchema = z.object({
+    codex: z.array(TranslatorAccountSchema),
+    grok: z.array(TranslatorAccountSchema),
+    kimi: z.array(TranslatorAccountSchema),
+    gemini: z.array(TranslatorAccountSchema),
+});
+export type TranslatorAccounts = z.infer<typeof TranslatorAccountsSchema>;
+// The side-channel body that un-parks a turn waiting on the user. Every interactive card, plan approval,
+// clarifying questions, a per-tool permission prompt, parks on the SAME registry keyed by `requestId`, so
+// one route resolves all three; the `kind` says which card answered and carries its payload.
+export const AgentReplySchema = z.discriminatedUnion("kind", [
+    // ExitPlanMode approval. Approving carries NO posture: an approved plan executes under bypassPermissions,
+    // set on the SDK session by the gate that raised the card. The container is the isolation boundary, so a
+    // plan the user has read and approved is exactly the point where per-tool prompts stop earning their
+    // interruption, landing anywhere else means approving a plan to run `git log` and then being asked whether
+    // `git log` may run. Rejection feedback loops back into the model as the denial reason.
+    z.object({
+        kind: z.literal("plan").describe("Answering a plan the agent proposed."),
+        requestId: z.string().min(1).describe("Which card you are answering, from the frame that raised it."),
+        approve: z
+            .boolean()
+            .describe(
+                "Whether to go ahead. Approving means the plan then runs without asking again per tool, because being asked whether a plan you just approved may run its first command is not a question worth having.",
+            ),
+        feedback: z.string().optional().describe("Why not, which goes back to the model as the reason."),
+    }),
+    // AskUserQuestion picks: question text → chosen option label(s) (+ any free-text "Other"). `cancelled`
+    // is the dismissal, which tells the model to proceed on sensible defaults rather than leaving it parked.
+    z.object({
+        kind: z.literal("question").describe("Answering a question the agent asked."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        answers: z
+            .record(z.string(), z.array(z.string()))
+            .optional()
+            .describe("What you chose, keyed by the question, with the chosen labels or your own words."),
+        cancelled: z
+            .boolean()
+            .optional()
+            .describe("Dismissing it instead, which tells the agent to carry on using sensible defaults rather than leaving it waiting."),
+    }),
+    // A per-tool permission prompt. 'once' allows this call only; 'always' allows the whole TOOL for the rest
+    // of the session (plus the SDK's own narrower suggestions), which is what the card's label promises;
+    // 'deny' blocks it and feeds `feedback` back as the reason.
+    z.object({
+        kind: z.literal("permission").describe("Answering a request to use a tool."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        decision: z
+            .enum(["once", "always", "deny"])
+            .describe("Once allows this call alone; always allows that whole tool for the rest of the conversation; no blocks it."),
+        feedback: z.string().optional().describe("Why not, which goes back to the model as the reason."),
+    }),
+    // A browser help request (the agent parked mid-sign-in on something only a person can clear, a captcha, a
+    // password it does not hold). `helped: true` is "done, hand back": the user took control of the agent's
+    // browser, fixed the step, and the turn continues from the page as they left it. `helped: false` is "can't
+    // help now", the agent is told so and moves on rather than waiting forever. `note` rides back to the model
+    // either way ("typed the password, don't touch the remember-me box").
+    z.object({
+        kind: z
+            .literal("browser_help")
+            .describe("Answering a request for help in the agent's browser: a captcha, a password it does not hold, a check on your phone."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        helped: z
+            .boolean()
+            .describe(
+                "Whether you cleared it. Yes means the turn carries on from the page as you left it; no tells the agent so, and it moves on rather than waiting for ever.",
+            ),
+        note: z.string().optional().describe("Anything the agent should know, which goes back to it either way."),
+    }),
+    // A terminal help request, the same two answers as the browser's, for a command parked at a prompt only a
+    // person can answer. `helped: true` is "typed it, carry on"; false is "can't right now". `note` rides back
+    // either way, and on `helped` the daemon adds what the pane SAYS to the tool result: the user answering the
+    // prompt is exactly the moment the agent cannot see, and it would otherwise have to ask them how it went.
+    z.object({
+        kind: z
+            .literal("terminal_help")
+            .describe("Answering a request for help at a terminal: a code to type, a confirmation only a person can give."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        helped: z
+            .boolean()
+            .describe(
+                "Whether you did it. Yes also hands the agent what the terminal now says, because a person answering a prompt is exactly the moment the agent cannot see.",
+            ),
+        note: z.string().optional().describe("Anything the agent should know, which goes back to it either way."),
+    }),
+    // A premium service run's yes or no. The click is the ONLY way the spend can happen, the daemon holds the
+    // agent's run request parked until this settles it (platform/service-offer.ts), so `approve` carries no
+    // qualifiers: one true releases exactly one run, and anything else charges nothing.
+    z.object({
+        kind: z.literal("service_offer").describe("Answering a request to spend on a paid service."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        approve: z
+            .boolean()
+            .describe("Yes releases exactly one run. Anything else charges nothing. This click is the only way the spend can happen."),
+    }),
+    // A missing-capability ask's yes or no. `connect: true` is "I'll set it up", it opens the card's setup
+    // and keeps the agent's request parked while the daemon watches for the connection to come live
+    // (capabilities/capability-offer.ts); false tells the agent to continue without it. The click decides
+    // only the WATCHING: nothing is connected by the reply itself, the setup is the owner's own flow.
+    z.object({
+        kind: z.literal("capability_offer").describe("Answering a request to connect something the agent needs."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        connect: z
+            .boolean()
+            .describe(
+                "Yes keeps the agent waiting while you set it up, and it carries on the moment the connection comes alive. No tells it to continue without. The reply itself connects nothing: setting it up is still your own doing.",
+            ),
+    }),
+    // A USDC payment's yes or no. The click is the ONLY way the money can move, the daemon holds the agent's
+    // `wallet fetch` parked until this settles it (wallet/payment-offer.ts), so `approve` carries no
+    // qualifiers: one true releases exactly one payment, and anything else spends nothing.
+    z.object({
+        kind: z.literal("payment_offer").describe("Answering a request to pay for something."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        approve: z
+            .boolean()
+            .describe("Yes releases exactly one payment. Anything else spends nothing. This click is the only way the money can move."),
+    }),
+]);
+export type AgentReply = z.infer<typeof AgentReplySchema>;
+// Steering: a user message delivered INTO the running turn (injected between tool calls, Claude Code style),
+// keyed by the conversation whose turn is in flight. NOT_FOUND when no steerable turn is running, the client
+// then holds the message in its queue and sends it as the next turn instead. Carries everything a turn's own
+// prompt can carry (files, the editor-context chip), because "add more while it works" is worth nothing if it
+// only takes bare text: the daemon folds the same notes into the injected message that a fresh turn gets.
+export const SteerSchema = z
+    .object({
+        conversationId: z.string().min(1).describe("Which running conversation to interrupt."),
+        text: z.string().max(20_000).describe("What to say to it. It arrives mid-turn without stopping the turn."),
+        attachments: z
+            .array(z.string().min(1))
+            .max(20)
+            .optional()
+            .describe("Files to send with it, as workspace paths. A screenshot dropped in mid-turn with no words is a legitimate thing to send."),
+        editorContext: EditorContextSchema.optional().describe("What you have open, folded in so that pointing words resolve."),
+    })
+    // An attachment-only steer (a screenshot dropped in mid-turn) is legal; an entirely empty one is not.
+    .refine((steer) => steer.text.trim().length > 0 || (steer.attachments?.length ?? 0) > 0, {
+        message: "text or attachments required",
+    });
+// True cancel for the conversation's in-flight turn, aborts the agent daemon-side, unlike closing the
+// /agent fetch (which sends no cancel frame).
+export const StopTurnSchema = z.object({ conversationId: z.string().min(1).describe("Which conversation's running turn to cancel.") });
+/* RUN THE HELD TURN AGAIN, and it carries a conversation id and NOTHING else, which is the entire point of it
+ * existing as its own route rather than as a flag on a turn.
+ *
+ * A spent allowance leaves a turn stranded that the daemon still holds in full: the prompt, the attachments, the
+ * model, the effort, the mode, the worktree, the session that holds whatever it managed to do. Every one of
+ * those is on the turn the daemon already has, and a client that re-derived them from its own transcript would
+ * be re-deriving them from the STRIPPED copy it renders (no preamble notes, no attachment note, no model), which
+ * is how a re-send comes to run a different turn from the one it claims to repeat.
+ *
+ * So the caller says only WHICH conversation, and the daemon re-runs the turn it kept. What comes back is an
+ * ordinary StartedTurn, and the caller then attaches to it exactly as it would to a turn somebody else started
+ * (the resume note on the prompt is what tells an attaching window to reuse the bubble that is already there
+ * instead of drawing the same message twice). */
+export const ResumeTurnSchema = z.object({
+    conversationId: z.string().min(1).describe("Which conversation's held turn to run again."),
+});

package/src/schemas/ports.ts

@@ -0,0 +1,84 @@
+// ports: every listening TCP socket in the sandbox + explicit port forwarding
+import { z } from "zod";
+// Anything run in a terminal (a turbo TUI fanning out dev servers, `python -m http.server`, an agent's ad-hoc
+// process) binds ports the daemon never assigned, the panel machinery can't see them. The /ports routes are
+// the generic complement: `list` reports the live listeners (procfs scan, on demand), `forward` makes one
+// reachable at port-<slot>-<sandboxId>.<zone> through the preview proxy. Forwarding is an explicit gesture,
+// previews are public, so nothing is exposed until the owner (or an agent acting for them) asks.
+
+export const PortSummarySchema = z.object({
+    port: z.number().describe("The port number."),
+    // The loopback address the listener actually answers at inside the sandbox, a `localhost` bind can land
+    // on ::1 only (Vite). The preview proxy and the desktop mirror (Mutagen forward) both dial this.
+    host: z
+        .enum(["127.0.0.1", "::1"])
+        .describe("Which loopback address it actually answers on. Some tools bind only one of the two, and anything dialling it has to know which."),
+    // Whether the proxy can actually reach the listener at `host`. False for a bind to a loopback alias like
+    // Docker's embedded DNS (127.0.0.11), which answers only at its own address, not 127.0.0.1, such rows are
+    // listed for transparency but the Ports view hides Preview and forwarding them is refused.
+    forwardable: z
+        .boolean()
+        .describe(
+            "Whether it can be exposed at all. Some listeners answer only at their own address and nowhere else; those are listed for honesty and refused for forwarding.",
+        ),
+    // Which bucket the Ports view files it under: `workspace` = user-run (dev servers in repos, terminal
+    // processes, published container ports), the previewable set; `system` = the sandbox's own machinery
+    // (agent runtimes, translator, dockerd, sshd), listed for transparency but nobody previews it.
+    kind: z
+        .enum(["workspace", "system"])
+        .describe("Whether somebody's own work put it there, or the sandbox's own machinery did. Only the first kind is worth previewing."),
+    /* WHAT IS ON THIS PORT, IN WORDS: resolved by the daemon (ports/port-identity.ts), because the two facts
+     * that attribute a listener (the panel key → extension index, the workspace root) exist there and nowhere
+     * else. `title` is what a person would call it ("Vite dev server", "Sandbox service", "Container port"),
+     * `purpose` is the one sentence a row shows under it, and `origin` says who put it there, which is what
+     * the reader is really asking when they ask what a port is: mine, my agent's, or the box's own.
+     *
+     * All three are required. A listener nothing can explain still gets a name ("Unclaimed port") and a
+     * sentence that says so out loud, because the alternative (a raw argv, or nothing) is what made this
+     * view unreadable, and the button beside the row publishes the port to the internet. */
+    title: z
+        .string()
+        .describe(
+            "What a person would call it. Always present: a listener nothing can explain is still named, because the button beside it publishes the port to the internet.",
+        ),
+    purpose: z.string().describe("One sentence about what it is for, including when the honest answer is that nothing could work it out."),
+    origin: z
+        .enum(["terminal", "agent", "panel", "extension", "container", "sandbox", "unknown"])
+        .describe("Who put it there, which is the question somebody is really asking: mine, my agent's, or the box's own."),
+    // The owning process, resolved from procfs; absent when no /proc/*/fd entry matched the socket's inode.
+    pid: z.number().optional().describe("The process holding it. Absent when nothing could be matched to the socket."),
+    // How the row is labeled: the process argv joined with spaces ("node /work/app/node_modules/.bin/vite"),
+    // falling back to the kernel `comm` name when argv is empty, or a synthesized name for attributable
+    // infrastructure the pid walk can't reach ("Docker embedded DNS"). Absent only when wholly unattributable.
+    command: z.string().optional().describe("The command behind it, as it was run. Absent only when nothing could be attributed at all."),
+    // The process working directory (how the UI attributes a port to a repo).
+    cwd: z.string().optional().describe("Where it is running from, which is how a port gets attributed to a repository."),
+    // The tmux session the listener descends from, the terminal to watch it in or stop it from. Absent when
+    // nothing in its ancestry is a pane (a daemon-managed runtime, a published container's docker-proxy), which
+    // is the honest "you cannot reach this from here" rather than a terminal that would open onto nothing.
+    session: z
+        .string()
+        .optional()
+        .describe(
+            'The terminal it came from, to watch it in or stop it from. Absent when nothing in its ancestry is one, which is the honest "you cannot reach this from here".',
+        ),
+    forwarded: z.boolean().describe("Whether it is currently reachable from outside."),
+    // https://port-<slot>-<sandboxId>.<zone>; present only while forwarded AND the sandbox has a zone + id.
+    previewUrl: z.string().optional().describe("Where to open it. Present only while forwarded, and only on a sandbox that has an outside address."),
+});
+export type PortSummary = z.infer<typeof PortSummarySchema>;
+export const PortsListSchema = z.object({
+    ports: z
+        .array(PortSummarySchema)
+        .describe("Everything listening inside the sandbox right now, read fresh each time rather than from a register the sandbox keeps."),
+});
+export type PortsList = z.infer<typeof PortsListSchema>;
+export const PortParamSchema = z.object({ port: z.number().int().min(1).max(65535).describe("Which port.") });
+// `previewUrl` is absent on a loopback/no-tunnel sandbox, the slot is mapped, but no public hostname exists.
+export const PortForwardResultSchema = z.object({
+    previewUrl: z
+        .string()
+        .optional()
+        .describe("Where it can now be reached. Absent on a sandbox with no outside address, where the mapping exists but has no public name."),
+});
+export type PortForwardResult = z.infer<typeof PortForwardResultSchema>;