@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/schemas/plan-limits.ts

@@ -1,41 +1,20 @@
 import { z } from "zod";
-import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../provider-specs.js";
+import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../models/provider-specs.js";
 import { AgentHarnessSchema, AgentProviderSchema, 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.
+// Headroom is one shape shared by every provider, not a Claude idea others imitate: a native account and a routed
+// subscription differ in who holds the credential, never in what a reading is. Every surface that draws a percentage
+// reads this one type.
 
-/* WHICH MODELS A POOL GATES, said by the reader that parsed it and carried on the wire, so every surface and
- * every picker answers "does this pool stand between me and THIS model" from one fact instead of six rules.
- *
- * A plan is not one allowance. Google meters Gemini separately from the Claude and GPT models it serves off the
- * same sign-in; a Claude plan carries a per-model weekly slice ("Opus", "Fable") beside its all-models pools;
- * ChatGPT publishes a code-review limit that no chat turn spends. Before this field the relation lived in six
- * places that disagreed (a static Google table, a Claude kind list, a max-over-everything ranking, a fullest-
- * window reset, and two client-side matchers), so a Google account with its Gemini pool spent drew a red ring
- * over Claude Opus, and a Claude account with its Opus slice spent was ranked "spent" for a Haiku call.
- *
- *   "all"      every model on this plan spends it: the 5-hour and weekly pools, Kimi's throttles.
- *   "none"     nothing a turn here runs spends it: a code-review limit, a surface-scoped pool for another
- *              product. Still shown, never binding.
- *   { models } a slice scoped to the models the names match. Names are matched as runs of whole words against
- *              the model id AND its label ("opus" is in "claude-opus-4-6" and in "Claude Opus 4.6"; "gemini"
- *              is in "gemini-3-pro"), see plan-pools.ts, because the plan names a pool by the vendor's word for
- *              the tier and nothing else connects the two.
- *
- * Decided by the READER, never inferred later: the payload is the only place the grouping is known, and it is
- * the plan's to change, so the fact travels with the reading it describes. */
+// Which models a pool gates, decided once by the reader that parsed it, so every picker answers from one fact instead
+// of re-deriving it.
+// all: every model on this plan spends it.
+// none: nothing spends it; still shown, never binding.
+// { models }: scoped to models matching these names (whole-word match against id and label).
 export const WindowGatesSchema = z.union([z.literal("all"), z.literal("none"), z.object({ models: z.array(z.string().min(1)).min(1) })]);
 export type WindowGates = z.infer<typeof WindowGatesSchema>;
 
-// 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). `gates` says which models the pool stands in the way
-// of, see WindowGatesSchema.
+// `kind` is the provider's own key (a string, not an enum): an unrecognised pool shows under its raw key rather than
+// folding into a neighbour. `label` wins over anything inferred; `resetsAt` is epoch seconds.
 export const UsageWindowSchema = z.object({
     kind: z.string(),
     label: z.string().optional(),
@@ -44,36 +23,15 @@ export const UsageWindowSchema = z.object({
     gates: WindowGatesSchema,
 });
 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.
+// Every window kept, not just the binding one, since which pool binds changes between turns. Utilization only climbs
+// within a window, so a stale reading is still a valid floor. `measuredAt` is epoch ms — windows are seconds.
 export const AccountUsageSchema = z.object({
     windows: z.array(UsageWindowSchema),
     measuredAt: z.number(),
 });
 export type AccountUsage = z.infer<typeof AccountUsageSchema>;
-/* THE ONE WAY PAST A SPENT SESSION WINDOW THAT IS NOT WAITING, which Anthropic grants once a week per account.
- *
- * Every other affordance around a refused turn is about WHEN: arm the appointment, count down to the reset,
- * press when it opens. This one moves the clock. The provider reopens the five-hour window immediately and
- * charges the account one of its weekly resets; the WEEKLY allowance is untouched and still binds, so this
- * buys back the session pool and nothing else. Upstream's own CLI spells it `/limit-reset`.
- *
- * THE ANSWER IS THE PROVIDER'S, NEVER OURS. There is no rule here to re-derive: eligibility turns on the plan
- * tier, how long the account has existed, whether it is actually at the wall, whether another experiment holds
- * it, and whether the week's reset is already spent — all of it decided server-side and none of it visible from
- * a usage reading. So this shape is a transcription of what the endpoint said, and the button exists only while
- * it says `available`. A client must never infer availability from a 100% window.
- *
- * `reason` is the provider's own word for the refusal ("tier", "tenure", "not_at_wall", "weekly_limit",
- * "already_used", …) and is carried rather than translated, because the set is the provider's to extend and a
- * word we don't recognise is still worth showing to somebody asking why the button is not there. */
+// Anthropic's once-a-week reset of the session window only; the weekly allowance is untouched. The answer is entirely
+// the provider's — never infer `available` from a 100% window. `reason` is its own word, carried verbatim.
 export const LimitResetStatusSchema = z.object({
     available: z
         .boolean()
@@ -82,7 +40,7 @@ export const LimitResetStatusSchema = z.object({
         .string()
         .optional()
         .describe("Why not, in the provider's own word, when it gave one. Absent when it is available, or when the provider said nothing."),
-    // Both epoch SECONDS, matching every other reset instant on the wire (UsageWindow.resetsAt, limitResetsAt).
+    // Epoch seconds, like every reset instant on this wire.
     nextAvailableAt: z
         .number()
         .optional()
@@ -90,16 +48,8 @@ export const LimitResetStatusSchema = z.object({
     weeklyResetsAt: z.number().optional().describe("When the weekly allowance itself reopens, in epoch seconds, where the provider publishes it."),
 });
 export type LimitResetStatus = z.infer<typeof LimitResetStatusSchema>;
-/* WHAT CLAIMING IT DID, in the provider's own vocabulary plus the two failures that are ours.
- *
- * `reset` is the only outcome that changed anything, and the caller's cue to send the held turn again. The rest
- * are all "nothing happened", and they are kept APART rather than folded into one failure because they are read
- * by somebody who just pressed a button and is owed the difference: `already_used` means come back next week,
- * `not_limited` means the window reopened while they were reading, `ineligible` means this account never had
- * it, and `unavailable`/`error` mean try again. Collapsing them would make every one of those read as a fault.
- *
- * Never throws over the wire: a claim that fails leaves the account exactly as it was, and the honest answer to
- * a press is a word, not a stack trace. */
+// Only `reset` changed anything; the rest are all "nothing happened" but kept apart since each is owed a different next
+// step (wait, retry, this account never had it). Never throws: a failed claim leaves the account as it was.
 export const LimitResetClaimSchema = z.object({
     result: z
         .enum(["reset", "already_used", "not_limited", "ineligible", "unavailable", "error"])
@@ -108,46 +58,22 @@ export const LimitResetClaimSchema = z.object({
     detail: z.string().optional().describe("What went wrong, in words, for the two outcomes that are this sandbox's fault rather than the plan's."),
 });
 export type LimitResetClaim = z.infer<typeof LimitResetClaimSchema>;
-/* 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. */
+// Observed and exact, unlike a polled usage snapshot that can be stale; keyed by provider, not account, since a routed
+// turn doesn't know which served it. `kind` is read off what the provider said, not the frame code.
 export const ProviderRefusalSchema = z.object({
-    // Epoch MS, matching AccountUsage.measuredAt, the two are read side by side.
+    // Read side by side with `AccountUsage.measuredAt` (also ms).
     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. */
+    // Only a turn that actually runs settles an entitlement refusal — nothing else can.
     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).
+    // Known for native turns only; a routed turn doesn't say which account served it.
     account: z.string().optional().describe("Which account was serving, where that is known."),
-    // The model the refused turn ran, so a `limit` refusal can be read against the POOL that model spends
-    // (UsageWindow.gates) rather than against the account's fullest pool, which on a plan that meters models
-    // separately is routinely a different allowance from the one that said no.
+    // Lets a `limit` refusal be read against the pool that model spends (`UsageWindow.gates`), not the account's
+    // fullest pool.
     model: z.string().optional().describe("Which model the refused turn was on, where that is known."),
 });
 export type ProviderRefusal = z.infer<typeof ProviderRefusalSchema>;
@@ -159,23 +85,19 @@ export const ProviderRefusalsSchema = z.object({
         ),
 });
 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).
+// `name` is CLIProxyAPI's auth-file name, the stable key a disconnect addresses; `label` is the reported sign-in
+// identity (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.
+    // Same shape as `OauthAccount`'s, so account rows are one list. Absent for a provider this sandbox can't read quota
+    // from (Grok) — still renders, as a dot not a ring.
     usage: AccountUsageSchema.optional(),
-    /* THE TRANSLATOR'S OWN VERDICT ON THE CREDENTIAL, the one live fact no quota read can produce. CLIProxyAPI
-     * benches an auth file the moment upstream refuses it (a quota 429, an expired token) and routes around it
-     * until `until`; a reading taken five minutes ago cannot know that, and a green ring over a benched file is
-     * exactly the gap a refusal used to be the only way to see. Absent ⇒ the proxy is routing to it. */
+    // The one live fact a quota read can't produce: CLIProxyAPI benches an auth file the instant upstream refuses it
+    // (quota, expired token) and routes around it until `until`. Absent means the proxy is routing to it.
     cooling: z
         .object({
-            // Epoch SECONDS, like every reset on this wire. Absent when the proxy named no retry instant.
+            // Epoch seconds, like every reset on this wire; absent when the proxy named no retry instant.
             until: z.number().optional(),
             // The proxy's own sentence, when it gave one.
             reason: z.string().optional(),
@@ -183,15 +105,8 @@ export const TranslatorAccountSchema = z.object({
         .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.
- *
- * ONE KEY PER TRANSLATOR PROVIDER, built over the derived list rather than typed out, because this object and
- * the enum beside it (KeyedProviderSchema) are the same fact twice and the browser reads a provider's slot
- * without checking it exists: a provider present in the enum and missing here is `undefined.length`, at the
- * exact moment somebody is asking whether they can send. */
+// A list per provider, not a flag: CLIProxyAPI holds several auth files per provider and balances across them. Built
+// from the same derived list as `KeyedProviderSchema`, so the two can't drift apart.
 export const TranslatorAccountsSchema = z.object(
     Object.fromEntries(TRANSLATOR_PROVIDERS.map((provider) => [provider, z.array(TranslatorAccountSchema)] as const)) as Record<
         TranslatorProvider,
@@ -199,15 +114,11 @@ export const TranslatorAccountsSchema = z.object(
     >,
 );
 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.
+// Un-parks a turn waiting on the user; every interactive card parks on one registry keyed by `requestId`, so one route
+// resolves all of them, and `kind` says which card answered.
 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.
+    // Approving sets `bypassPermissions` on the SDK session; the container, not per-tool prompts, is the isolation
+    // boundary from here on.
     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."),
@@ -218,8 +129,7 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             ),
         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.
+    // Keyed by question text, valued by chosen option label(s), including free-text "Other".
     z.object({
         kind: z.literal("question").describe("Answering a question the agent asked."),
         requestId: z.string().min(1).describe("Which card you are answering."),
@@ -232,9 +142,7 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             .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.
+    // "always" may be narrowed further by the SDK's own suggestions.
     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."),
@@ -243,11 +151,6 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             .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")
@@ -260,10 +163,6 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             ),
         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")
@@ -276,20 +175,6 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             ),
         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."),
@@ -299,9 +184,6 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
                 "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."),
@@ -309,16 +191,8 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             .boolean()
             .describe("Yes releases exactly one payment. Anything else spends nothing. This click is the only way the money can move."),
     }),
-    /* A GATED CREDENTIAL's release, and the one reply on this list whose sender is CHECKED. Every other card
-     * here is answered by whoever holds a session, because every other card is the owner's to decide; this one
-     * is addressed to a named list, so the daemon reads the verified identity off the request and refuses a
-     * click from anybody else with the card left standing for whoever can answer it. The refusal covers `no`
-     * as well: a stranger may not skip a release on the approver's behalf either, or the gate would be a
-     * denial-of-service anybody with a session could aim at a turn.
-     *
-     * `approve` carries no qualifiers because the gate's own policy decides how far one yes goes: a per-use
-     * gate releases exactly this use and the next one asks again, a conversation-scoped gate covers the rest
-     * of the conversation. The card says which, so the click is never wider than it reads. */
+    // The one reply whose sender is checked: the daemon verifies identity against the card's named list and refuses
+    // anyone else, including a `no` — otherwise a stranger could deny-of-service the approver.
     z.object({
         kind: z.literal("credential_offer").describe("Releasing a credential the agent may only use once a named person says so."),
         requestId: z.string().min(1).describe("Which card you are answering."),
@@ -330,11 +204,8 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
     }),
 ]);
 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.
+// A message injected into a running turn between tool calls; NOT_FOUND when none is steerable, and the client queues it
+// as the next turn instead. Carries everything a fresh prompt can (files, editor context).
 export const SteerSchema = z
     .object({
         conversationId: z.string().min(1).describe("Which running conversation to interrupt."),
@@ -350,38 +221,28 @@ export const SteerSchema = z
     .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).
+// True cancel, aborted 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.") });
-/* WHO SERVES THE RE-RUN, the one part of a held turn a press is allowed to move, and the field that exists
- * because leaving it out made the press useless in exactly the case it was built for.
- *
- * A spent allowance is a refusal by an ACCOUNT, and the fix a person reaches for is the account switcher in the
- * composer: switch to one with headroom, press Continue. Replaying the turn with everything it carried replayed
- * the refused account too, so the press bounced off the same limit, reported it in the same words, and the user's
- * only way through was to type "Continue" by hand — a send, which reads the composer's current selection, which
- * is the very thing the press was ignoring.
- *
- * So the press carries WHO, and the daemon keeps WHAT. Everything that makes the turn the turn (the prompt, the
- * attachments, the effort, the mode, the worktree, the session holding whatever it managed to do) stays on the
- * daemon's own copy, because a client re-deriving those from its transcript would be re-deriving them from the
- * STRIPPED copy it renders, which is how a re-send comes to run a different turn from the one it claims to
- * repeat. Routing is the exception, and it is the exception on purpose: it is not a property of the request, it
- * is the answer to "who pays for it", and the whole reason the user is pressing is that they have changed it. */
+// The press carries WHO serves the re-run; the daemon keeps WHAT the turn is (prompt, attachments, worktree) from its
+// own record, since re-deriving from a stripped client transcript would replay a different turn.
 export const ResumeRoutingSchema = z.object({
     agent: AgentProviderSchema.describe("Which provider serves the re-run."),
     harness: AgentHarnessSchema.describe("Which agentic loop runs it."),
     account: z.string().optional().describe("Which of that provider's accounts pays for it. Leave it out for the first one."),
-    // Omitted rather than guessed: a client whose catalog hasn't loaded has no pick to send, and the turn's own
-    // model is a better answer than a blank one.
+    // A client whose catalog hasn't loaded has nothing to send; the turn's own model is the better fallback.
     model: z.string().optional().describe("Which model. Leave it out to keep the one the refused turn named."),
+    // A session is a file the daemon keeps; a credential is an env var. That's what lets a same-provider account switch
+    // resume the existing session instead of opening a fresh one.
+    carry: z
+        .boolean()
+        .optional()
+        .describe(
+            "When the account changes, keep the provider session (the model keeps everything, and re-reads all of it once on the other account) rather than opening a fresh one seeded from the record. Ignored when the provider changes, or when nothing changes.",
+        ),
 });
 export type ResumeRouting = z.infer<typeof ResumeRoutingSchema>;
-/* RUN THE HELD TURN AGAIN: which conversation, and who serves it now.
- *
- * 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). */
+// Returns an ordinary `StartedTurn`; the caller attaches to it like any turn someone else started. A resume note on the
+// prompt tells an attaching window to reuse the existing bubble, not redraw it.
 export const ResumeTurnSchema = z.object({
     conversationId: z.string().min(1).describe("Which conversation's held turn to run again."),
     routing: ResumeRoutingSchema.optional().describe(

package/src/schemas/ports.ts

@@ -1,41 +1,28 @@
 // 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.
+// Terminal-bound ports (a TUI, an ad-hoc process) that the panel machinery can't see; `list` scans procfs live,
+// `forward` exposes one at port-<slot>-<sandboxId>.<zone> through the preview proxy. Forwarding is explicit — nothing
+// is public until asked for.
 
 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.
+    // Vite, for one, binds only ::1; the preview proxy and the desktop mirror both dial this address.
     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.
+    // e.g. Docker's embedded DNS at 127.0.0.11, which only answers at its own address.
     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.
+    // workspace: dev servers, terminal processes, published container ports. system: agent runtimes, translator,
+    // dockerd, sshd.
     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. */
+    // All three are required, even when nothing can explain the listener ("Unclaimed port"); resolved daemon-side,
+    // where the facts that attribute it actually live.
     title: z
         .string()
         .describe(
@@ -45,17 +32,13 @@ export const PortSummarySchema = z.object({
     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.
+    // Resolved via /proc/*/fd matching 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.
+    // Process argv joined with spaces, falling back to the kernel `comm` name, or a synthesized name when the pid walk
+    // can't reach it.
     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.
+    // Absent for daemon-managed runtimes and published container ports, which have no pane to open.
     session: z
         .string()
         .optional()
@@ -63,7 +46,7 @@ export const PortSummarySchema = z.object({
             '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.
+    // `https://port-<slot>-<sandboxId>.<zone>`.
     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>;
@@ -74,7 +57,6 @@ export const PortsListSchema = z.object({
 });
 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()