@intentic/sandbox-contract 1.246.1 → 1.248.0

package/src/schemas/agent.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ModelRoleSchema } from "../model-roles.js";
 import { NATIVE_PROVIDERS } from "../provider-specs.js";
 import { AgentPlacementSchema } from "../runner-protocol.js";
 import { entryId } from "./internal.js";
@@ -267,6 +268,23 @@ export const AgentTurnSchema = z
             .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. */
+        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.
@@ -311,7 +329,7 @@ export const AgentTurnSchema = z
          * 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 agentRunModels for any turn that says
+         * 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
@@ -416,14 +434,14 @@ export type AgentTurn = z.infer<typeof AgentTurnSchema>;
  * Shared rather than re-declared per route because every surface that starts an agent for the user now carries
  * that caret, and they must all mean the same thing by it: the pair rides onto the turn as `agent`/`model`, and
  * the daemon's own fill step then leaves it alone (turn-resume.ts fills only what is absent). ABSENT is the
- * ordinary case and the one to keep cheap, nobody touched the caret, so `agentRunModels` answers.
+ * ordinary case and the one to keep cheap, nobody touched the caret, so the turn's `runRole` list answers.
  *
  * Both halves or neither, because a model id is only meaningful to the provider that vends it: half a pick
  * would send a Codex model id to Claude. Routes that accept this pass it through verbatim; a model this build
  * has never heard of is a supported pick, since the picker offers a custom-id escape hatch.
  *
  * 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 (AgentRunPinSchema), and the daemon applies the pin's knobs ONLY to a turn that
+ * 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
@@ -442,29 +460,36 @@ export const AgentRunPickSchema = z
     })
     .optional();
 export type AgentRunPick = z.infer<typeof AgentRunPickSchema>;
-/* A MODEL PINNED FOR EVERY SURFACE-STARTED RUN, one entry of settings.agentRunModels: the standing version of
- * the pick above, and not merely which model but HOW it is to be run.
+/* 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.
  *
- * THE KNOBS RIDE THE ENTRY RATHER THAN THE LIST, which is the whole reason this is an object where the setting
- * used to hold a `${provider}:${model}` string. The reasoning effort was a single field beside the list, so one
- * tier answered for every model in it — and the entries of that list are deliberately NOT interchangeable: it
- * is a frontier pin with the cheap account underneath that catches it when the first is spent. A tier scale is
- * a property of the MODEL as well ('max' is off Kimi's scale entirely, and off Claude's own the moment thinking
+ * THE KNOBS RIDE THE ENTRY RATHER THAN THE LIST, which is the whole reason this is an object rather than a
+ * `${provider}:${model}` string. The reasoning effort was once a single field beside a list, so one tier
+ * answered for every model in it — and the entries of such a list are deliberately NOT interchangeable: it is a
+ * frontier pin with the cheap account underneath that catches it when the first is spent. A tier scale is a
+ * property of the MODEL as well ('max' is off Kimi's scale entirely, and off Claude's own the moment thinking
  * is switched off), so a shared effort was either off-scale for half the list or the lowest common rung for all
- * of it. Each entry now carries what the composer's picker configures for the turn in front of you.
+ * of it. Each entry carries what the composer's picker configures for the turn in front of you.
+ *
+ * THE SAME SHAPE FOR EVERY ROLE, one-shot helpers included, and that is a deliberate widening. A commit
+ * message or a session title used to be pinnable by model alone, on the argument that the daemon runs those
+ * with reasoning off and no effort, so a control for either would be a switch with nothing behind it. True of
+ * the machinery, and it made the machinery the argument: an owner who pins a reasoning model to their commit
+ * subjects was paying that model's price to have its distinguishing feature suppressed. The knobs now travel
+ * through the one-shot path too, so an entry means the same thing wherever it is written.
  *
- * EVERY FIELD BUT THE PAIR IS OPTIONAL, AND ABSENT MEANS ABSENT: the turn goes out without the field and the
+ * EVERY FIELD BUT THE PAIR IS OPTIONAL, AND ABSENT MEANS ABSENT: the work goes out without the field and the
  * provider's own default answers, exactly as an unconfigured pin always did. Nothing here invents a "low".
  *
  * NO TIER HOLD, and its absence is the rule rather than an omission: automatic tier selection gates on
- * `unattended` (prompt-complexity.ts), so a surface-started run is never downgraded in the first place and a
- * veto over it would be a control whose state can make no difference to anything.
+ * `unattended` (prompt-complexity.ts), so a role-started run is never downgraded in the first place and a veto
+ * over it would be a control whose state can make no difference to anything.
  *
  * The pair is BOTH HALVES for the reason the pick above is: a model id is only meaningful to the provider that
  * vends it, so half a pin would send a Codex id to Claude. Taken verbatim, never validated against a catalog:
  * the picker offers a custom-id escape hatch, so a model this build has never heard of is a supported pin. */
-export const AgentRunPinSchema = z.object({
-    provider: AgentProviderSchema.describe("Which provider serves the run."),
+export const ModelPinSchema = z.object({
+    provider: AgentProviderSchema.describe("Which provider serves this work."),
     model: z.string().min(1).describe("Which of its models. Both halves, because a model name only means anything to the provider that serves it."),
     effort: z
         .string()
@@ -474,7 +499,7 @@ export const AgentRunPinSchema = z.object({
     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."),
     harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it. Leave it out to use the provider's own."),
 });
-export type AgentRunPin = z.infer<typeof AgentRunPinSchema>;
+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.
 export const StartedTurnSchema = z.object({

package/src/schemas/agents.ts

@@ -182,8 +182,8 @@ export const LandedMessageSchema = z.object({
         .describe("What this change takes away, for anything already relying on it. Nearly always absent: it is for removals, not for additions."),
 });
 export type LandedMessage = z.infer<typeof LandedMessageSchema>;
-/* ONE MODEL'S TURN IN THE DRAFTING WALK, asked, and what became of the ask. The quick-model chain tries the
- * connected models in order (agent/quick-model.ts), and each rung ends one of four ways:
+/* ONE MODEL'S TURN IN THE DRAFTING WALK, asked, and what became of the ask. The one-shot helper chain tries the
+ * connected models in order (agent/role-model.ts), and each rung ends one of four ways:
  *   asking  , in flight right now; `ms` absent because it is still being spent.
  *   answered, it wrote the sentence, in `ms`.
  *   refused , it failed or declined, in `ms`, with its own words in `reason`.

package/src/schemas/automations.ts

@@ -264,7 +264,9 @@ export type WebchatMessage = z.infer<typeof WebchatMessageSchema>;
 export const AutomationSchema = z.object({
     id: entryId.describe("The automation's id."),
     trigger: TriggerSchema.describe("What sets it off: a schedule, an event in the workspace, a message arriving from outside, or a webhook."),
-    // Shell command run in the workspace root before waking; exit 0 ⇒ wake, non-zero ⇒ the run is "skipped".
+    /* Shell command run in the workspace root before waking; exit 0 ⇒ wake, non-zero ⇒ the run is "skipped".
+     * Its environment carries `AUTOMATION_ID` (this automation's own id, so a guard can look up what its past
+     * fires did) and, for a trigger that arrived with one, `AUTOMATION_PAYLOAD`. */
     guard: z
         .string()
         .min(1)
@@ -279,7 +281,9 @@ export const AutomationSchema = z.object({
     // field rather than a shared "public endpoint" bag: the two sources answer different questions (a chat's
     // greeting and access model, an intake's dedup ceiling and ingest key) and a union of both would be a
     // schema where most fields are wrong for whichever source is reading it.
-    issues: IssuesConfigSchema.optional().describe("Settings for the bug reporter, for an automation that takes crash reports from your own sites and apps."),
+    issues: IssuesConfigSchema.optional().describe(
+        "Settings for the bug reporter, for an automation that takes crash reports from your own sites and apps.",
+    ),
     /* NARROW THIS ONE JOB FURTHER than the persona it runs as, raw tool names, and the escape hatch under the
      * shelves rather than the way anyone is expected to answer this question.
      *

package/src/schemas/personas.ts

@@ -1,14 +1,25 @@
 // 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 { type ModelSource, readyChain } from "../model-pins.js";
+import { type ModelPin, ModelPinSchema } from "./agent.js";
 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.
+ * IT ANSWERS FIVE QUESTIONS AND NO MORE: who it speaks as, what it may do, where it works, what it is told, and
+ * what it runs on (the repositories its tree holds, the models it runs on). 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.
+ *
+ * A CARD IS THE SANDBOX'S ONE STATIC DESCRIPTION OF A WORKING POSTURE, and static is the design. Everything a
+ * session sees before the user's first word is a function of the card it wears: the accounts, the tool set the
+ * powers leave, the kit's prompt and skills, and now the tree it opens on. Two sessions on one card open on
+ * the same prefix, which is what lets a provider's prompt cache serve the second. The only per-task decision
+ * left is WHICH card, and that is a classification over the owner's own short list (`brief`), once per chat,
+ * which a cheap model does reliably; asking a model to compose a context per session instead either picks
+ * badly or costs a second strong run and a hand-off of everything it decided.
  *
  *   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
@@ -122,6 +133,28 @@ export const PersonaWorkspaceSchema = z.object({
     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>;
+/* WHAT A CONVERSATION WEARING THIS CARD CARRIES: which repositories its checkout HOLDS, as opposed to
+ * `workspace.folders`, which fences what the file tools may TOUCH inside a tree that holds everything.
+ *
+ * `repos` names NESTED repositories by their workspace-relative dir (the ids repo-discovery reports). The root
+ * repository is the workspace itself and is always carried, never listed, so an empty list is the workspace
+ * alone. ABSENT `context` is every repository the workspace has, which is what every card meant before this
+ * existed and what a card that has never thought about it should get. The sandbox brings a conversation's
+ * checkout to this list on every turn (agents/worktrees.ts `selection`): a repository the list names joins,
+ * one it stops naming leaves with its work committed to the branch.
+ *
+ * An OBJECT rather than a bare list, so the next kinds of thing a session can carry (a directory inside a
+ * repository through a sparse cone, a documents folder) arrive as fields beside this one rather than as a
+ * grammar inside it. */
+export const PersonaContextSchema = z.object({
+    repos: z
+        .array(z.string().min(1).max(200))
+        .max(50)
+        .describe(
+            "Which nested repositories a conversation wearing this card carries, by workspace-relative path. The workspace itself is always carried; empty means the workspace alone.",
+        ),
+});
+export type PersonaContext = z.infer<typeof PersonaContextSchema>;
 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.
@@ -138,28 +171,40 @@ export const PersonaSchema = z.object({
         .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)
+    /* WHAT THIS PERSONA IS FOR, in one line: the sentence a new chat is routed on (the sandbox's
+     * agent/persona-router.ts reads one line per card and names one) and the row's subtitle on the Personas
+     * page. Written by the owner rather than derived from the card, because a classifier reading "backend work
+     * on the api and billing services, never the marketing site" routes better than one reading a list of
+     * account ids, and because it is the one sentence a reader scanning the list wants under each name. Absent
+     * is a card the router can still name from what else the card says, with less to go on. */
+    brief: z
+        .string()
+        .max(200)
         .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.",
-        ),
+        .describe("What this persona is for, in one line. A new chat is routed onto a persona by this sentence, and the Personas page shows it under the name."),
     // 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 PART OF THE WORKSPACE A SESSION WEARING THIS CARD CARRIES, the id of a context shelf
-     * (schemas/context.ts). A different question from `workspace.folders`: that one fences what the file tools
-     * may TOUCH inside a tree that holds everything, this one decides what the tree HOLDS. Absent falls through to
-     * the sandbox's `contextShelf` setting, and from there to everything. */
-    context: entryId.optional().describe("Which context shelf a conversation wearing it opens on: the part of the workspace it carries. Absent follows the sandbox setting."),
+    context: PersonaContextSchema.optional().describe(
+        "Which part of the workspace a conversation wearing it carries: the repositories its checkout holds. Absent means every repository.",
+    ),
+    /* WHICH MODELS A CONVERSATION WEARING THIS CARD RUNS ON, in order: the ladder shape every role list has
+     * (settings.modelRoles, model-pins.ts), for the same reason, a single pin is a single point of failure and
+     * the next entry catches an account that is spent today. ABSENT is the caller's own answer: the composer's
+     * pick for a chat, the run role's list for a turn a surface started. Present, the composer moves its model
+     * pill to the ladder's head when the card is picked (so a chat routed onto a card runs on that card's
+     * model as well as in its context), and the sandbox fills an unattended turn's silence from it before the
+     * run role's list (agent/turn-resume.ts). A model named on the turn itself always wins. */
+    models: z
+        .array(ModelPinSchema)
+        .max(10)
+        .optional()
+        .describe(
+            "Which models a conversation wearing it runs on, tried in order. Absent means whatever the chat or the job would have run on anyway; a model chosen for the turn itself always wins.",
+        ),
     /* 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.
@@ -179,6 +224,28 @@ export const PersonaSchema = z.object({
     systemPromptMode: SystemPromptModeSchema.optional(),
 });
 export type Persona = z.infer<typeof PersonaSchema>;
+/* WHICH OF A CARD'S MODELS THIS SANDBOX CAN RUN, IN ORDER: the ladder filtered to connected providers and
+ * deduplicated — exactly the walk a role list gets, and now the SAME CALL rather than a sibling of one
+ * (model-pins.ts readyChain). It used to be "that walk minus the role's floor"; there is no floor any more, so
+ * the two lists ask one question. An absent ladder, or one whose every provider is disconnected, is empty
+ * here, and empty means the caller's own answer: a card that says nothing about models has not asked for a
+ * cheap one, it has left the question to whoever opened the chat. */
+export const personaModels = (card: Pick<Persona, "models">, sources: readonly ModelSource[]): readonly ModelPin[] => readyChain(sources, card.models ?? []);
+/* WHAT A NEW CHAT IS ROUTED ON, and what comes back. The composer asks once per settled draft on a chat that
+ * has no turns and no persona pinned by hand (its personaRoute composable), and the sandbox answers with the
+ * one card the message belongs to, or none. `folder` and `paths` are the two facts a card's `context` and
+ * `workspace.startIn` can be matched against and the words alone cannot supply. */
+export const PersonaRouteAskSchema = z.object({
+    prompt: z.string().min(1).max(20000).describe("The message a new chat is about to open with."),
+    folder: z.string().max(200).optional().describe("The workspace folder the chat was opened in, when it was opened in one."),
+    paths: z.array(z.string().min(1).max(500)).max(50).default([]).describe("Workspace paths the message names: uploads, @-mentions, the editor's own file."),
+});
+export type PersonaRouteAsk = z.infer<typeof PersonaRouteAskSchema>;
+export const PersonaRouteSchema = z.object({
+    persona: entryId.optional().describe("The card this message belongs to, or absent when none does and the chat should stay open to everything."),
+    reason: z.string().describe("Why, in the one line a chip can show. Present whether or not a card was named."),
+});
+export type PersonaRoute = z.infer<typeof PersonaRouteSchema>;
 /* 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

package/src/schemas/plan-limits.ts

@@ -58,6 +58,56 @@ export const AccountUsageSchema = z.object({
     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. */
+export const LimitResetStatusSchema = z.object({
+    available: z
+        .boolean()
+        .describe("Whether the provider will reopen this account's session window right now. The only thing a button may be drawn from."),
+    reason: z
+        .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).
+    nextAvailableAt: z
+        .number()
+        .optional()
+        .describe("When the next reset may be claimed, in epoch seconds, where the provider publishes it. Absent means unknown, never 'now'."),
+    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. */
+export const LimitResetClaimSchema = z.object({
+    result: z
+        .enum(["reset", "already_used", "not_limited", "ineligible", "unavailable", "error"])
+        .describe("What the provider did. Only `reset` reopened the window; every other value means nothing changed."),
+    nextAvailableAt: z.number().optional().describe("When another reset may be claimed, in epoch seconds, where the provider published it."),
+    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.
  *