@intentic/sandbox-contract 1.247.0 → 1.248.0

package/src/model-roles.ts

@@ -23,19 +23,26 @@ import { z } from "zod";
  * went on the chat this morning, and one spent provider takes the role down for hours while three others sit
  * idle. Written in order, the next entry catches it.
  *
- * TWO KINDS, and the only thing that separates them is what an EMPTY list means. That is a real fork rather
- * than a leftover of the old grouping, and it is declared per role because it is a property of the job:
+ * AN EMPTY LIST IS THE JOB SWITCHED OFF, and NOTHING IS DERIVED FOR IT. A helper role used to fall to an
+ * "Auto ladder" worked out from whatever was connected — every provider's cheapest row, best-first — so a
+ * sandbox that had never been configured still spent somebody's account on commit messages and safety
+ * verdicts, on a recommendation this table invented, which re-ranked itself the day another account was
+ * connected. Not set now means not set: no auto-selection, no recommendation, and the owner names the models
+ * for a job or the job does not happen.
  *
- *   helper — a one-shot. One prompt, no tools, one string back, and it is over. An empty list resolves to the
- *            AUTO LADDER: every connected provider's cheapest row, best-first (model-pins.ts). Deriving is the
- *            right default here because the job is small and repeatable, so the cost of a wrong guess is one
- *            cheap call, and because a derived answer improves by itself when an account is connected tomorrow.
+ * TWO KINDS, and what separates them is what the CALLER does with that empty answer. It is declared per role
+ * because it is a property of the job:
+ *
+ *   helper — a one-shot. One prompt, no tools, one string back, and it is over. With no list the job does not
+ *            run at all: no commit subject is drafted, no session is renamed, no command is judged. Every one
+ *            of them already had a road for "the model could not answer" (the derived title stands, the
+ *            commit box stays empty, the gate falls to its standing rule), so an owner who wants none of them
+ *            leaves the row empty and pays nothing.
  *
  *   run    — a whole session with tools and a worktree, started by a surface rather than by a person at a
- *            composer. An empty list resolves to NOTHING, and the caller's own floor answers: the model the
- *            owner picked for their chat. Nothing here can judge whether a job is worth the frontier tier, and
- *            a wrong guess is billed in whole sessions rather than in tokens, so the honest fallback is a
- *            choice they made rather than one this table invented.
+ *            composer. With no list the caller's own floor answers: the model the owner picked for their chat.
+ *            That is not this table recommending anything — it is a choice they already made, in front of
+ *            them, on the composer they work in.
  *
  * EVERY ENTRY IS A FULL PIN (ModelPinSchema): which model, and how it runs — effort, thinking, speed, harness.
  * The helper roles carry them too, which they did not use to: a one-shot ran with reasoning forcibly off, so
@@ -51,6 +58,18 @@ import { z } from "zod";
 export const ModelRoleKindSchema = z.enum(["helper", "run"]);
 export type ModelRoleKind = z.infer<typeof ModelRoleKindSchema>;
 
+/* WHAT STARTS A RUN, declared for the run roles alone.
+ *
+ * It is not a wire value and never has been: it decides which BLOCK a job is read in, and the argument for
+ * reading them apart is the same one that separates a helper from a run — an owner holds a session nobody is
+ * watching to a different budget from one they are sitting in front of. The settings page used to make that
+ * argument in a comment over a thirteen-row list ("the ones somebody presses ahead of the ones that fire on
+ * their own"), which is a claim no reader can check and no row has to honour. Declared, it draws the page.
+ *
+ * A HELPER DECLARES NONE, and that is the honest answer rather than a gap: nobody presses "write me a commit
+ * subject". It happens because something else did. */
+export type ModelRoleTrigger = "pressed" | "unprompted";
+
 /* The shape of a row. `id` is a bare string HERE and narrowed on the exported type below, because the id union
  * is derived from this very table: a self-referential `satisfies` would be a type that has to know its own
  * answer before it can check it. */
@@ -62,6 +81,8 @@ interface ModelRoleRow {
     // cannot rather than restating it.
     readonly blurb: string;
     readonly kind: ModelRoleKind;
+    /** Runs only, and required for every one of them: see `ModelRoleTrigger`. */
+    readonly trigger?: ModelRoleTrigger;
     // The row's glyph, from the shared icon set. Here rather than in a web-side map because the whole value of
     // this table is that a role is declared ONCE; a second table keyed by the same ids is the drift this
     // replaced, moved one layer up.
@@ -71,7 +92,8 @@ interface ModelRoleRow {
 /* THE TABLE. Ordered as the settings page draws it, and the order is an argument about reach: the one-shots
  * first, because nobody chose a model for them and they run constantly; then the runs somebody's click starts;
  * then the runs that start themselves, which are the ones an owner is least likely to be watching and most
- * likely to want held to a budget.
+ * likely to want held to a budget. Those three are BLOCKS now (see MODEL_ROLE_BLOCKS) rather than an ordering
+ * this comment asserts and nothing holds to.
  *
  * The ids are the wire vocabulary: a turn carries one (AgentTurn.runRole), so they are kebab-case and stable,
  * and renaming one is a breaking change to the setting rather than a cosmetic edit. */
@@ -108,11 +130,23 @@ export const MODEL_ROLES = [
         kind: "helper",
         icon: "check-square",
     },
+    {
+        /* THE ONE HELPER THAT ANSWERS A CLASSIFICATION rather than writing prose: one card id, or none, from the
+         * owner's own short list (schemas/personas.ts `brief`). Cheap by construction, once per chat, and the
+         * job a small model does well, which is the whole argument for routing chats onto static cards rather
+         * than asking a model to compose a context per session. */
+        id: "persona-router",
+        label: "Persona routing",
+        blurb: "Which model reads a new chat's first message and picks the persona for it.",
+        kind: "helper",
+        icon: "users",
+    },
     {
         id: "pipeline-fix",
         label: "Pipeline fixes",
         blurb: "The agent started by Fix on a red pipeline.",
         kind: "run",
+        trigger: "pressed",
         icon: "wave-pulse",
     },
     {
@@ -120,6 +154,7 @@ export const MODEL_ROLES = [
         label: "Deployment fixes",
         blurb: "The agent started by Fix on a deployment that is down.",
         kind: "run",
+        trigger: "pressed",
         icon: "server",
     },
     {
@@ -127,6 +162,7 @@ export const MODEL_ROLES = [
         label: "Maintenance chores",
         blurb: "A chore run started from the Maintenance board.",
         kind: "run",
+        trigger: "pressed",
         icon: "wrench",
     },
     {
@@ -134,6 +170,7 @@ export const MODEL_ROLES = [
         label: "Documentation runs",
         blurb: "A pass over a repo's own documentation.",
         kind: "run",
+        trigger: "pressed",
         icon: "book",
     },
     {
@@ -141,6 +178,7 @@ export const MODEL_ROLES = [
         label: "Acceptance runs",
         blurb: "One session per story in an acceptance fan-out.",
         kind: "run",
+        trigger: "pressed",
         icon: "list-check",
     },
     {
@@ -148,27 +186,34 @@ export const MODEL_ROLES = [
         label: "Pre-push fixes",
         blurb: "The fix proposed when a check fails on the way to a push.",
         kind: "run",
+        trigger: "pressed",
         icon: "cloud-upload",
     },
     {
-        id: "automation-wake",
-        label: "Automation wakes",
-        blurb: "A turn an automation fires: a schedule, a webhook, a message from outside.",
-        kind: "run",
-        icon: "clock",
-    },
-    {
+        /* PRESSED, ON THE STRENGTH OF THE APPROVAL. Nothing here runs until somebody reads the item and says
+         * yes, and that press is the start of this turn as much as Fix is the start of a pipeline run — the
+         * queue between the two is machinery, not a second decision. */
         id: "approval-queue",
         label: "Approvals queue",
         blurb: "The turn that publishes or acts on what you approved.",
         kind: "run",
+        trigger: "pressed",
         icon: "check-circle",
     },
+    {
+        id: "automation-wake",
+        label: "Automation wakes",
+        blurb: "A turn an automation fires: a schedule, a webhook, a message from outside.",
+        kind: "run",
+        trigger: "unprompted",
+        icon: "clock",
+    },
     {
         id: "extension-review",
         label: "Extension update reviews",
         blurb: "The agent that reads an extension update before it is applied.",
         kind: "run",
+        trigger: "unprompted",
         icon: "box",
     },
     {
@@ -176,6 +221,7 @@ export const MODEL_ROLES = [
         label: "Loop iterations",
         blurb: "Each round of a loop working towards its goal.",
         kind: "run",
+        trigger: "unprompted",
         icon: "repeat",
     },
     {
@@ -183,6 +229,7 @@ export const MODEL_ROLES = [
         label: "Watch wakes",
         blurb: "The turn a watch starts when the thing it was watching happens.",
         kind: "run",
+        trigger: "unprompted",
         icon: "eye",
     },
     {
@@ -190,6 +237,7 @@ export const MODEL_ROLES = [
         label: "Verify nudges",
         blurb: "The follow-up turn sent when work was left unverified.",
         kind: "run",
+        trigger: "unprompted",
         icon: "search",
     },
     {
@@ -200,6 +248,7 @@ export const MODEL_ROLES = [
         label: "Child agents",
         blurb: "What an agent's own subagents run on when it names no model for them.",
         kind: "run",
+        trigger: "unprompted",
         icon: "users",
     },
 ] as const satisfies readonly ModelRoleRow[];
@@ -215,10 +264,57 @@ export const MODEL_ROLE_IDS = MODEL_ROLES.map((role) => role.id) as readonly Mod
  * silently ignored. */
 export const ModelRoleSchema = z.enum(MODEL_ROLE_IDS as [ModelRole, ...ModelRole[]]);
 
-const BY_ID = new Map<string, ModelRoleSpec>(MODEL_ROLES.map((role) => [role.id, role]));
+/* ═══ THE BLOCKS THE SETTINGS PAGE READS IN ═══
+ *
+ * EIGHTEEN JOBS IN ONE LIST IS A TABLE, NOT A PAGE. The unit being the role is right and is not in question —
+ * it is what lets an owner pin Opus to commit subjects without pinning it to every session title — but the cost
+ * lands on whoever opens the page: one unbroken run of eighteen rows, each with a name, a sentence, a control
+ * and a list under it, with no landmark to say where you are in it or which rows are like the one you came for.
+ *
+ * SO THE BLOCKS ARE DECLARED, AND THEY ARE THE DISTINCTIONS THE TABLE ALREADY MAKES. Nothing here is a fresh
+ * taxonomy invented for the layout: `kind` was always the difference between a one-shot and a whole session,
+ * and `trigger` is the sentence the old table wrote in a comment about its own ordering. A block is what those
+ * two answers already separate, given a name and a heading.
+ *
+ * THE LABELS LIVE HERE, beside the role labels, for the same reason those do: a heading kept in a web-side map
+ * keyed by the same ids is the drift a single table exists to stop. What is NOT here is anything about how the
+ * page draws them — that is the page's, and it changes on its own schedule.
+ *
+ * ORDER IS REACH, and it is the order of the table itself: jobs nobody picked a model for, then sessions a
+ * click of yours starts, then sessions that start without one. Every role belongs to exactly one block and
+ * every block keeps the table's order, which is what makes a role added upstairs appear on the page by
+ * existing. */
+export type ModelRoleBlockId = "helper" | "pressed" | "unprompted";
 
-/** What this role is, or undefined for an id no build of this table declares. */
-export const modelRole = (id: string): ModelRoleSpec | undefined => BY_ID.get(id);
+export interface ModelRoleBlock {
+    readonly id: ModelRoleBlockId;
+    /** The group's heading on the settings page. */
+    readonly label: string;
+    /** One line beside it: what the jobs in this block have in common that the others do not. */
+    readonly caption: string;
+    /** Its roles, in table order. */
+    readonly roles: readonly ModelRoleSpec[];
+}
+
+const rolesWhere = (match: (role: ModelRoleSpec) => boolean): readonly ModelRoleSpec[] => MODEL_ROLES.filter((role) => match(role));
 
-/** The roles of one kind, in table order: the two blocks the settings page draws. */
-export const modelRolesOfKind = (kind: ModelRoleKind): readonly ModelRoleSpec[] => MODEL_ROLES.filter((role) => role.kind === kind);
+export const MODEL_ROLE_BLOCKS: readonly ModelRoleBlock[] = [
+    {
+        id: "helper",
+        label: "Automatic helpers",
+        caption: "One prompt, no tools, one answer back.",
+        roles: rolesWhere((role) => role.kind === "helper"),
+    },
+    {
+        id: "pressed",
+        label: "Runs you start",
+        caption: "Whole sessions, begun by a click of yours.",
+        roles: rolesWhere((role) => role.kind === "run" && role.trigger === "pressed"),
+    },
+    {
+        id: "unprompted",
+        label: "Runs that start themselves",
+        caption: "Whole sessions nobody pressed for.",
+        roles: rolesWhere((role) => role.kind === "run" && role.trigger === "unprompted"),
+    },
+];

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/settings.ts

@@ -307,17 +307,21 @@ export const SandboxSettingsSchema = z.object({
             "Keep the instructions identical between turns so the provider can cache them, moving anything that varies into the message instead. Cheaper, at the cost of some flexibility.",
         ),
     skills: z.array(z.string()).default(["lsp", "fileq"]).describe("Which skills are switched on."),
-    /* WHICH CONTEXT SHELF A CONVERSATION OPENS ON when nothing closer to it says (schemas/context.ts). A persona
-     * card's own `context` wins where a turn wears one; this is the sandbox's answer for the turns that do not.
-     * Empty means no shelf, so a conversation carries every repository the workspace has, which is what every
-     * conversation did before shelves existed. Empty rather than optional because a settings object is parsed
-     * from `{}` until the owner first changes something, and every field here has to answer to that. */
-    contextShelf: z
-        .string()
-        .max(60)
-        .default("")
+    /* WHETHER A NEW CHAT IS ROUTED ONTO A PERSONA, and how far the answer goes without a press. The router is
+     * the `persona-router` helper role (model-roles.ts): it reads the first message and one line per card and
+     * names one card or none, once per chat, before the first turn (the sandbox's agent/persona-router.ts).
+     *   off      — never asked. A chat wears the persona the user picked, or none.
+     *   suggest  — asked, and the answer is a chip on the composer that the user presses to apply. The default:
+     *              a persona takes accounts and repositories AWAY from a chat, and the first time that happens
+     *              it should happen because somebody pressed it.
+     *   auto     — the answer is applied when the message is sent, unless the chip was dismissed first.
+     * Attended chats only, whatever this says: a wake nobody is watching names its persona on its own form,
+     * and routing one onto a card would GRANT it accounts the owner never named for it. */
+    personaRouting: z
+        .enum(["off", "suggest", "auto"])
+        .default("suggest")
         .describe(
-            "Which context shelf a conversation opens on when its persona names none: the part of the workspace it carries. Empty means every repository, as before shelves existed.",
+            "Whether a new chat is matched to one of your personas from its first message. Suggest shows the match on the composer for you to press; auto applies it when you send unless you dismiss it first. Never applies to unwatched runs, which name their persona themselves.",
         ),
     hashlineEdits: z
         .boolean()
@@ -478,12 +482,13 @@ export const SandboxSettingsSchema = z.object({
      * that is connected and will not answer today: the account's allowance went on the chat, and one spent
      * provider takes that job down for hours while the others sit idle.
      *
-     * AN ABSENT OR EMPTY LIST IS THE INTERESTING CASE and means the role's declared floor (resolveRoleModels): a
-     * one-shot helper derives an Auto ladder from whatever is connected right now — so it can never name a
-     * provider this sandbox has no credential for, and it improves by itself as accounts are added — while a
-     * whole session falls to the model the owner picked for their own chat, because nothing here can judge what
-     * a session is worth and a wrong guess is billed whole. Storing resolved ids instead would go stale exactly
-     * as a pinned model does. */
+     * AN ABSENT OR EMPTY LIST IS THE JOB SWITCHED OFF, and nothing is derived to fill it. A one-shot helper
+     * used to fall to an "Auto ladder" worked out from whatever was connected, which meant a sandbox nobody
+     * had configured still spent an account on every commit subject, every session title and every safety
+     * verdict, on a ranking this repo invented and re-ranked whenever an account was added. Not set now means
+     * not set: no auto-selection and no recommendation. A one-shot with no list does not run; a whole session
+     * with no list opens on the model the owner picked for their own chat, which is a choice they made rather
+     * than one this schema guessed. */
     // `partialRecord`, not `record`: an exhaustive one would make every role a required key, so a settings file
     // that has never been touched would have to spell out seventeen empty arrays to be valid, and adding a role
     // would invalidate every settings file in existence. An absent key IS the answer "this role has no list".
@@ -491,7 +496,7 @@ export const SandboxSettingsSchema = z.object({
         .partialRecord(ModelRoleSchema, z.array(ModelPinSchema).max(10))
         .default({})
         .describe(
-            "Which models do which job, one ordered list per job: commit messages, session titles, the safety judge, pipeline fixes, and every other place this sandbox picks a model for you. Tried in order, so one spent account does not take a job down. A job with no list falls back to its own default: cheapest connected for the one-shot helpers, your own chat model for whole sessions.",
+            "Which models do which job, one ordered list per job: commit messages, session titles, the safety judge, pipeline fixes, and every other place this sandbox picks a model for you. Tried in order, so one spent account does not take a job down. Nothing is chosen for you: a one-shot job with no list does not run, and a whole session with no list opens on whatever your own chat is set to.",
         ),
     /* WHICH REPOS KEEP A CHANGELOG, the repos whose commits carry a `Release-Note:` trailer, written by the
      * same quick model that drafts the subject (git/commit-message.ts) and harvested at release time.

package/src/workspace-state.test.ts

@@ -380,7 +380,6 @@ describe(`VERSIONED_STATE_PATHS`, () => {
             `${STATE_DIR}/config/capability-dismissals.json`,
             // The context shelves: which repositories a conversation opened on one carries. A list of names, and
             // the decision about what a session may see, which is what a review is for.
-            `${STATE_DIR}/config/context/`,
             /* The two entries the AGENT authors on its own initiative, and the reason `versioned` is not read as
              * config-only. Both are the sandbox acting outward: a draft publishes words under the owner's name,
              * a workspace extension is code that runs in the app and can serve HTTP with the workspace under

package/src/workspace-state.ts

@@ -738,12 +738,6 @@ const STATE_FILES = [
      * behaves, it holds no credential, and it belongs in a pull request, which is also what makes it
      * searchable, since every versioned entry already is. */
     { path: ".intentic/config/personas/", invalidates: ["personas"], portability: "carry", versioned: true },
-
-    /* THE CONTEXT SHELVES, one JSON file per shelf (schemas/context.ts): which part of the workspace a
-     * conversation opened on it carries. `versioned` and `carry` on the persona card's own argument, a shelf is
-     * a list of item ids and holds no credential, and which repositories a session can see is exactly the kind
-     * of decision that belongs in a pull request. */
-    { path: ".intentic/config/context/", invalidates: ["context"], portability: "carry", versioned: true },
 ] as const satisfies readonly WorkspaceStateFile[];
 
 export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = STATE_FILES;

package/dist/schemas/context.d.ts

@@ -1,30 +0,0 @@
-import { z } from "zod";
-export declare const CONTEXT_ITEM_KINDS: readonly ["repo"];
-export type ContextItemKind = (typeof CONTEXT_ITEM_KINDS)[number];
-export declare const ContextItemIdSchema: z.ZodString;
-export type ContextItemId = z.infer<typeof ContextItemIdSchema>;
-export declare const contextItem: (id: ContextItemId) => {
-    readonly kind: ContextItemKind;
-    readonly name: string;
-};
-export declare const ContextCapsSchema: z.ZodObject<{
-    repos: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-export type ContextCaps = z.infer<typeof ContextCapsSchema>;
-export declare const ContextShelfSchema: z.ZodObject<{
-    id: z.ZodString;
-    label: z.ZodOptional<z.ZodString>;
-    pinned: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    allowed: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    denied: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    caps: z.ZodOptional<z.ZodObject<{
-        repos: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export type ContextShelf = z.infer<typeof ContextShelfSchema>;
-export declare const ContextCompositionSchema: z.ZodObject<{
-    shelf: z.ZodOptional<z.ZodString>;
-    items: z.ZodArray<z.ZodString>;
-}, z.core.$strip>;
-export type ContextComposition = z.infer<typeof ContextCompositionSchema>;
-//# sourceMappingURL=context.d.ts.map

package/dist/schemas/context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/schemas/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoBxB,eAAO,MAAM,kBAAkB,YAAI,MAAM,CAAU,CAAC;AACpD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAKlE,eAAO,MAAM,mBAAmB,aAK0I,CAAC;AAC3K,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAGhE,eAAO,MAAM,WAAW,OAAQ,aAAa,KAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAGtG,CAAC;AAMF,eAAO,MAAM,iBAAiB;;iBAE5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAa5D,eAAO,MAAM,kBAAkB;;;;;;;;;iBAW7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAS9D,eAAO,MAAM,wBAAwB;;;iBAGnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/schemas/context.js

@@ -1,34 +0,0 @@
-import { z } from "zod";
-import { entryId } from "./internal.js";
-export const CONTEXT_ITEM_KINDS = ["repo"];
-const ITEM = /^(repo):[a-zA-Z0-9][a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$/;
-export const ContextItemIdSchema = z
-    .string()
-    .min(1)
-    .max(200)
-    .regex(ITEM)
-    .describe("One thing in the workspace a conversation can carry, as `<kind>:<name>`. Today the kind is `repo` and the name is a repository's workspace-relative path.");
-export const contextItem = (id) => {
-    const at = id.indexOf(":");
-    return { kind: id.slice(0, at), name: id.slice(at + 1) };
-};
-export const ContextCapsSchema = z.object({
-    repos: z.number().int().min(0).optional().describe("How many repositories a composition may hold. Absent means as many as the shelf allows."),
-});
-export const ContextShelfSchema = z.object({
-    id: entryId.describe("The shelf's id, which is also its file name."),
-    label: z.string().max(60).optional().describe("What to call it on screen. Absent falls back to the id."),
-    pinned: z.array(ContextItemIdSchema).max(200).default([]).describe("Items every composition from this shelf carries."),
-    allowed: z
-        .array(ContextItemIdSchema)
-        .max(500)
-        .default([])
-        .describe("Items a composition may carry, in the order they are loaded and shed. The order is the priority; nothing else is."),
-    denied: z.array(ContextItemIdSchema).max(200).default([]).describe("Items no composition from this shelf carries, whatever else says so."),
-    caps: ContextCapsSchema.optional().describe("How many of each kind a composition may hold."),
-});
-export const ContextCompositionSchema = z.object({
-    shelf: entryId.optional().describe("Which shelf this pick was made from. Absent when the items were set without one."),
-    items: z.array(ContextItemIdSchema).max(500).describe("What the conversation carries, in shelf order. The root repository is always carried and never listed."),
-});
-//# sourceMappingURL=context.js.map

package/dist/schemas/context.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/schemas/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAmBxC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAM,CAAU,CAAC;AAKpD,MAAM,IAAI,GAAG,oEAAoE,CAAC;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KAC/B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,KAAK,CAAC,IAAI,CAAC;KACX,QAAQ,CAAC,2JAA2J,CAAC,CAAC;AAI3K,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAAiB,EAA6D,EAAE;IACxG,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAoB,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;AAChF,CAAC,CAAC;AAMF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yFAAyF,CAAC;CAChJ,CAAC,CAAC;AAcH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,OAAO,CAAC,QAAQ,CAAC,8CAA8C,CAAC;IACpE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yDAAyD,CAAC;IACxG,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,kDAAkD,CAAC;IACtH,OAAO,EAAE,CAAC;SACL,KAAK,CAAC,mBAAmB,CAAC;SAC1B,GAAG,CAAC,GAAG,CAAC;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,mHAAmH,CAAC;IAClI,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,sEAAsE,CAAC;IAC1I,IAAI,EAAE,iBAAiB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;CAC/F,CAAC,CAAC;AAUH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kFAAkF,CAAC;IACtH,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,wGAAwG,CAAC;CAClK,CAAC,CAAC"}