@intentic/sandbox-contract 1.231.0 → 1.233.0

package/src/definition.ts

@@ -0,0 +1,235 @@
+import { z } from "zod";
+import { DefinitionActionSchema } from "./definition-action.js";
+import { CapabilitySchema } from "./schemas/capabilities.js";
+import { SandboxSettingsSchema } from "./schemas/settings.js";
+
+/* THE SANDBOX DEFINITION: the declarable SHAPE of a sandbox, split off from its state.
+ *
+ * A bundle (BundleSchema, schemas/maintenance.ts) moves everything a sandbox holds; this is the half of it that
+ * is a REFERENCE to a source of truth rather than bytes only this sandbox has: which repos (as remotes a
+ * target can clone), which connections (as shapes a target re-authenticates), which overlay steps (as source
+ * a target's owner approves), which secrets (as NAMES a target asks for), which agent settings. Everything
+ * here can be reproduced against the world; everything a bundle carries beyond it (transcripts, checkpoint
+ * timelines, unpushed branches, ledgers) cannot, which is the line between the two formats.
+ *
+ * ON THE WIRE AND ON DISK IT IS TOML (`sandbox.toml`), hand-writable and diffable; these schemas are what the
+ * parsed document must satisfy. The choice of a definition never relaxes the consent model: applying one
+ * writes the overlay as a PROPOSAL for the owner's approval gate, lands capabilities unauthenticated, and
+ * never carries a credential value, so a definition is safe to publish in a way a bundle never is.
+ */
+
+// One repository, by reference: the id it lands under in the workspace, where a target clones it from, and
+// (optionally) the branch to check out. A repo with NO remote cannot appear here, the exporter reports it as
+// omitted instead of inventing a source for bytes only the source sandbox holds.
+export const DefinitionRepositorySchema = z.strictObject({
+    // Workspace-relative repo id ("intentic", "clients/foo"), the same id the wire {repo} routes use.
+    id: z.string().min(1),
+    // The clone URL, verbatim from the source repo's own remote.
+    remote: z.string().min(1),
+    // The branch to check out; absent means the remote's default.
+    ref: z.string().optional(),
+});
+export type DefinitionRepository = z.infer<typeof DefinitionRepositorySchema>;
+
+/* THE WORKSPACE ITSELF, by reference. `/work` is a git repo of its own (the daemon's `root` scope, git dir on
+ * /history), tracking every workspace file that is not a nested repo, the reference shelf, or daemon-internal
+ * state — which by the versioned-state allowlist means the owner's AUTHORED content: notes, skills, personas,
+ * automations, workflow and loop designs, drafts, workspace extensions. None of that has a source anywhere else,
+ * so before this section a definition could only shrug at it and a bundle was the sole way to move it.
+ *
+ * With a remote it becomes referenceable like any other repo, which is the whole point: `[workspace]` plus
+ * `[[repositories]]` is a sandbox's code AND its way of working, and what remains bundle-only is exactly what
+ * cannot be pushed anywhere — secrets, identity, /history, the built image.
+ *
+ * A workspace with no remote cannot appear here; the exporter says so in `omitted` rather than inventing one. */
+export const DefinitionWorkspaceSchema = z.strictObject({
+    // The clone URL, verbatim from the workspace repo's own remote.
+    remote: z.string().min(1),
+    // The branch to check out; absent means the remote's default.
+    ref: z.string().optional(),
+});
+export type DefinitionWorkspace = z.infer<typeof DefinitionWorkspaceSchema>;
+
+export const DefinitionEnvironmentSchema = z.strictObject({
+    // The image the overlay extends, informational: the target composes against ITS OWN base (see
+    // composeEnvironment's baseImageOf), this records what the source was on.
+    baseImage: z.string().optional(),
+    /* The owner-approved CUSTOM overlay section, as source. Deliberately not the composed file and
+     * deliberately without the approval hash: consent does not travel, so an applied definition parks this at
+     * the target owner's approval gate rather than executing it. */
+    dockerfile: z.string().optional(),
+});
+export type DefinitionEnvironment = z.infer<typeof DefinitionEnvironmentSchema>;
+
+/* The settings section: every SandboxSettings field, optional, WITHOUT its default. `.partial()` alone keeps
+ * each field's `.default()`, so a document naming two flags would parse into the whole surface at today's
+ * defaults — the opposite of "state only decisions", and it would freeze those defaults into every future
+ * apply. Unwrapping first is what makes an absent key STAY absent, so applying merges over the target's own
+ * settings and a definition round-trips through parse byte-identically. */
+// Both wrapper classes, in a loop: a field can be a default inside a prefault, and either one left on would
+// re-materialize its value for an absent key.
+const bareField = (field: z.ZodType): z.ZodType => {
+    let inner = field;
+    while (inner instanceof z.ZodDefault || inner instanceof z.ZodPrefault) {
+        inner = inner.unwrap() as z.ZodType;
+    }
+    return inner;
+};
+
+const definitionSettings = (): z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>> => {
+    const shape = Object.fromEntries(Object.entries(SandboxSettingsSchema.shape).map(([key, field]) => [key, bareField(field).optional()]));
+    return z.strictObject(shape).prefault({}) as unknown as z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>>;
+};
+
+export const SandboxDefinitionSchema = z.strictObject({
+    // Bumped when the layout changes in a way an older daemon would misread. Refused rather than guessed at,
+    // the bundle manifest's own rule.
+    schemaVersion: z.literal(1),
+    // What the source sandbox was called, for the reader; never used to authorize anything.
+    name: z.string().optional(),
+    environment: DefinitionEnvironmentSchema.prefault({}),
+    // The workspace repo itself, when it has a remote to be named by. Absent is the ordinary state of a
+    // workspace nobody has published, not an error.
+    workspace: DefinitionWorkspaceSchema.optional(),
+    repositories: z.array(DefinitionRepositorySchema).prefault([]),
+    /* Each connection IN FULL (id, kind, config), not merely named: the manifest they come from carries the
+     * SHAPE of a connection and never its credential (workspace-state.ts argues the split on the
+     * capabilities.json entry, and the exporter sweeps before reading), so what lands on a target is the card,
+     * visibly unauthenticated, waiting for one credential apiece. */
+    capabilities: z.array(CapabilitySchema).prefault([]),
+    // Secret NAMES only, what the target should ask its owner for. Values never enter a definition.
+    secrets: z.array(z.string()).prefault([]),
+    // The agent settings that differ from their defaults. Partial on purpose: a definition states decisions,
+    // not the whole flag surface, so a flag it does not mention keeps the target's own default.
+    settings: definitionSettings(),
+});
+export type SandboxDefinition = z.infer<typeof SandboxDefinitionSchema>;
+
+// One "do this by hand" line, the same honesty unit ImportReportSchema carries: a subject the UI bolds and a
+// detail written as an instruction to the owner. Defined in its own leaf module (definition-action.ts says
+// why) and re-exported here, where every consumer of the definition surface finds it.
+export { DefinitionActionSchema, type DefinitionAction } from "./definition-action.js";
+
+// What GET /definition answers: the emitted TOML, plus what the derivation could not express (a repo with no
+// remote), listed rather than silent, the export's own `excluded` discipline.
+export const DefinitionExportSchema = z.object({
+    toml: z.string(),
+    omitted: z.array(DefinitionActionSchema),
+});
+export type DefinitionExport = z.infer<typeof DefinitionExportSchema>;
+
+// One appliable piece of a held definition, the checklist row the owner ticks. Mirrors MigrationItemSchema's
+// role; the ids are deterministic ("repo:intentic", "capability:github") so the re-derived apply names the
+// same items the owner reviewed.
+export const DefinitionItemSchema = z.object({
+    id: z.string(),
+    kind: z.enum(["workspace", "repo", "capability", "environment", "settings"]),
+    label: z.string(),
+    detail: z.string().optional(),
+    /* False when the target already holds this piece (the repo's directory exists, a capability with that id
+     * exists): a definition lands BESIDE what is there, never over it, so an inapplicable item renders greyed
+     * with its reason rather than disappearing. */
+    applicable: z.boolean(),
+    reason: z.string().optional(),
+});
+export type DefinitionItem = z.infer<typeof DefinitionItemSchema>;
+
+export const DefinitionPlanSchema = z.object({
+    // Names the held definition for the apply call. Minted per plan; a new plan replaces the held one.
+    token: z.string(),
+    name: z.string().optional(),
+    items: z.array(DefinitionItemSchema),
+    // What is already known not to move mechanically (credentials to enter, an overlay to approve), surfaced
+    // at PREVIEW time so the owner ticks with open eyes, the migration surface's rule.
+    needsAction: z.array(DefinitionActionSchema),
+});
+export type DefinitionPlan = z.infer<typeof DefinitionPlanSchema>;
+
+export const DefinitionApplySchema = z.object({
+    token: z.string(),
+    // The ticked item ids. Ids the re-derived plan does not contain are ignored rather than erroring.
+    items: z.array(z.string()),
+});
+export type DefinitionApply = z.infer<typeof DefinitionApplySchema>;
+
+export const DefinitionReportSchema = z.object({
+    applied: z.array(z.object({ id: z.string(), label: z.string() })),
+    // Ticked and did not land, each with the reason (a clone that failed, a full disk). Distinct from
+    // inapplicable items, which were never attempted.
+    failed: z.array(z.object({ id: z.string(), label: z.string(), error: z.string() })),
+    needsAction: z.array(DefinitionActionSchema),
+});
+export type DefinitionReport = z.infer<typeof DefinitionReportSchema>;
+
+// Where this sandbox stands relative to a definition: one line per difference, empty when they agree. The
+// drift answer, computable because the emitter is deterministic.
+export const DefinitionDiffSchema = z.object({
+    differences: z.array(DefinitionActionSchema),
+});
+export type DefinitionDiff = z.infer<typeof DefinitionDiffSchema>;
+
+/* ---- publishing the workspace repo, the one step a definition cannot take for itself ----
+ *
+ * `[workspace]` names a remote; nothing can name one that does not exist. So the owner-facing half of the
+ * feature is this: create a PRIVATE repo on a connected git host and push /work to it, or adopt a URL the
+ * owner made themselves. Deliberately its own route rather than a side effect of the export, publishing a
+ * workspace is an outward act with its own confirmation, and deriving a document must stay read-only.
+ */
+export const WorkspacePublishSchema = z.object({
+    /* An existing repo's clone URL. Given, nothing is created: the remote is wired up and pushed to, which is
+     * the path for an owner who made the repo themselves or is moving hosts. */
+    remote: z.string().min(1).optional(),
+    // The repo to create when `remote` is absent. Owner-side default is the sandbox's own name.
+    name: z.string().min(1).optional(),
+    /* The account or organization to create it under; absent means the authenticated user. Ignored when
+     * `remote` is given. */
+    owner: z.string().min(1).optional(),
+});
+export type WorkspacePublish = z.infer<typeof WorkspacePublishSchema>;
+
+// Where the workspace now lives, and what a definition will name. `created` distinguishes "made you a repo"
+// from "wired up the one you gave me", which is the difference the card reports back.
+export const WorkspacePublishResultSchema = z.object({
+    remote: z.string(),
+    branch: z.string(),
+    created: z.boolean(),
+});
+export type WorkspacePublishResult = z.infer<typeof WorkspacePublishResultSchema>;
+
+// What the card renders before anything is published: whether /work has a remote, and which connected git
+// hosts could make one. Read-only, so the button can say "Publish to github.com" rather than opening a form
+// into a void.
+export const WorkspaceRemoteSchema = z.object({
+    remote: z.string().optional(),
+    branch: z.string().optional(),
+    // Hostnames of connected github/gitlab accounts, in the order they would be tried. Empty means the owner
+    // must connect one (or paste a URL).
+    hosts: z.array(z.string()),
+});
+export type WorkspaceRemote = z.infer<typeof WorkspaceRemoteSchema>;
+
+/* ---- the bundle manifest, restated on the definition ----
+ *
+ * A bundle is DEFINITION + STATE: its manifest embeds the same definition `GET /definition` emits, and the
+ * tar entries behind it carry what no definition can reference (git dirs, transcripts, ledgers). One schema,
+ * two doors, which is what keeps the two formats from drifting into different answers about what an
+ * environment IS. Version 2 replaced the ad-hoc `environment` facts block with the definition; a v1 bundle is
+ * refused by version rather than guessed at, like any other manifest this daemon cannot read.
+ */
+export const BundleManifestSchema = z.object({
+    // Bumped when the layout changes in a way an older daemon would misread. Refused rather than guessed at.
+    version: z.literal(2),
+    // Where it came from, for the report's first line. Never used to authorize anything.
+    sandbox: z.object({ name: z.string() }).optional(),
+    createdAt: z.number(),
+    // The owner's export-time choice; the restorer re-derives every decision from the manifests rather than
+    // trusting this, and uses it only to explain what is missing.
+    secrets: z.boolean(),
+    // The declarable shape, exactly what a definition export emits, so the restore report reasons over the
+    // same facts either door delivers.
+    definition: SandboxDefinitionSchema,
+    // Every path class the bundle deliberately left out, with the manifest's own note where it has one. This is
+    // what turns "the export skipped things" from a silence into a list the owner can act on.
+    excluded: z.array(z.object({ path: z.string(), portability: z.string(), note: z.string().optional() })),
+});
+export type BundleManifest = z.infer<typeof BundleManifestSchema>;

package/src/events.ts

@@ -1,18 +1,12 @@
 import { z } from "zod";
-import {
-    AgentProviderSchema,
-    AgentReplySchema,
-    AgentSummarySchema,
-    FastModeStateSchema,
-    LandConflictSchema,
-    MemberRoleSchema,
-    PermissionModeSchema,
-    RateLimitInfoSchema,
-    ShareDetailSchema,
-    SubagentKindSchema,
-    SubagentStatusSchema,
-    UsageWindowSchema,
-} from "./schemas.js";
+import { AgentProviderSchema, PermissionModeSchema } from "./schemas/agent.js";
+import { AgentSummarySchema, LandConflictSchema } from "./schemas/agents.js";
+import { RateLimitInfoSchema } from "./schemas/claude-gate.js";
+import { FastModeStateSchema } from "./schemas/fast-mode.js";
+import { AgentReplySchema, UsageWindowSchema } from "./schemas/plan-limits.js";
+import { ShareDetailSchema } from "./schemas/share.js";
+import { MemberRoleSchema } from "./schemas/shared.js";
+import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "./schemas/terminal.js";
 
 // The wire shapes streamed from the daemon's event-iterator procedures. This is their canonical home: the
 // daemon yields them and the browser client consumes them from the same schema, so the two can't drift (they
@@ -35,6 +29,29 @@ export const AskQuestionSchema = z.object({
 });
 export type AskQuestion = z.infer<typeof AskQuestionSchema>;
 
+/* THE PROGRAM A COMMAND CARD IS HOLDING, as the thing it is rather than as prose about it.
+ *
+ * It used to ride in `description`, the field every other permission ask fills with a sentence, which left the
+ * card with no way to know it was holding four hundred characters of shell: it rendered them as a paragraph,
+ * wrapped mid-flag, and the fragment that caused the hold was somewhere in the middle of it.
+ *
+ * `spans` is the gate's own evidence, computed by the classifier at the moment the rule fired (contract's
+ * command-classes.ts, matchCommand) and carried rather than re-derived: a browser that re-ran the patterns
+ * would be a second classifier, and the day the two disagreed the card would be marking a fragment that is not
+ * the one anybody was held for. Offsets are into `text` AFTER truncation, so they are always paintable.
+ *
+ * `language` is a Shiki grammar id, and the two are the two execution backends the gate reads (command-gate's
+ * EXECUTION_SOURCES): a shell line and a script. */
+export const ProgramAskSchema = z.object({
+    text: z.string().describe("What would run."),
+    language: z.enum(["bash", "javascript"]).describe("Which of the two backends it is written for, named as the grammar that colours it."),
+    truncated: z.boolean().describe("Whether this is the head of a longer program, so the card can say so instead of ending mid-word."),
+    spans: z
+        .array(z.object({ start: z.number().int().nonnegative(), end: z.number().int().nonnegative() }))
+        .describe("Which fragments of the text put it in the class that held it. Offsets into text, in order, never overlapping."),
+});
+export type ProgramAsk = z.infer<typeof ProgramAskSchema>;
+
 // One per-tool permission prompt (the SDK's canUseTool callback, surfaced as a card). The daemon passes the
 // bridge's own rendered strings through rather than re-deriving them, so the prompt reads exactly as Claude
 // Code words it. `alwaysLabel` is present only when the SDK offered rules to persist, without it the card
@@ -56,6 +73,15 @@ export const PermissionAskSchema = z.object({
         .describe(
             "The wording for an always-allow answer. Present only when there is something an always could actually remember; without it the only answers are once and no.",
         ),
+    program: ProgramAskSchema.optional().describe(
+        "The program this card is holding, when the card is about one. Present on a command gate's card and absent on every other permission ask.",
+    ),
+    explain: z
+        .string()
+        .optional()
+        .describe(
+            "One plain sentence saying what the program does and why the agent wants it. Written by the quick model, never by the agent being gated, and only when the owner switched the setting on.",
+        ),
 });
 export type PermissionAsk = z.infer<typeof PermissionAskSchema>;
 
@@ -360,8 +386,9 @@ export const RestoredMessageSchema = z.object({
     thinking: z.string().optional().describe("What the agent was reasoning about."),
     tools: z.array(RestoredToolCallSchema).optional().describe("The tool calls this part of the turn made."),
     /* What the daemon added to this turn's message (user rows only), the same notes the live `preamble` frame
-     * carries, recovered from the stored prompt when the transcript is read back. The reader that strips them out
-     * of the user's words is the one that hands them over here instead of dropping them on the floor.
+     * carries. A daemon-recorded turn takes them straight off that frame in its own log, typed end to end
+     * (sessions/turn-transcript.ts); only a conversation adopted from a provider's session store recovers them
+     * by parsing the composed prompt kept there, the one store the daemon never wrote typed.
      *
      * On the message rather than as a row of its own, and that matters twice: they ARE part of what was
      * sent, and a record row per turn preamble would break the one-row-per-bubble correspondence a branch counts
@@ -489,8 +516,9 @@ export type ParkedCard = z.infer<typeof ParkedCardSchema>;
 // ~40 SDKMessage types down to this union: high-value block types get a dedicated frame
 // (delta/thinking/tool_call/tool_call_update/todos/usage/rate_limit_info/account_usage/context_usage/init/compact); any SDK message
 // without a UI mapping is dropped. `plan`/`question`/`permission` pause the turn until the user answers on the
-// `POST /agent/reply` side channel, and `resolved` releases the one it names; `mode` reports the live
-// permission posture as the agent changes it.
+// `POST /agent/reply` side channel, and `resolved` releases the one it names; `permission_note` adds a sentence
+// to a permission card already on screen without settling it; `mode` reports the live permission posture as the
+// agent changes it.
 // `parentToolUseId` tags frames produced inside a subagent (Task tool); `subagent`/`subagent_update` report the
 // subagent itself, keyed by the same tool_use id those tagged frames carry.
 export const AgentEventSchema = z.discriminatedUnion("kind", [
@@ -554,12 +582,14 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
      * way to find out what those instructions said. This frame is the fix: the note text verbatim, one entry per
      * note, rendered collapsed so it costs a click rather than a scroll.
      *
-     * `title` is the note's own opening header, which is what the stripper already anchors on, so the two
-     * cannot drift, and a note nobody thought to title cannot reach the wire unlabelled.
+     * Emitted from the TYPED notes the wire prompt is serialized from at the same point (turn-preamble.ts,
+     * composeWirePrompt), so the disclosure and what the model receives cannot drift: a note is in both or in
+     * neither, and a note nobody thought to title cannot reach the wire unlabelled.
      *
      * ONE MOMENT, always: the notes went in front of the user's own message before the turn started, so they hang
-     * off that message and are stored on it, which is how a reopened tab still has them. Nothing is injected into
-     * a RUNNING turn, the rebase taken while a card sat waiting was the only thing that ever was, and it no
+     * off that message and are stored on it, the transcript fold reads this very frame out of the turn's own
+     * frame log (sessions/turn-transcript.ts), which is how a reopened tab still has them. Nothing is injected
+     * into a RUNNING turn, the rebase taken while a card sat waiting was the only thing that ever was, and it no
      * longer says anything to the model at all (agent/turn-preamble.ts). */
     z.object({ kind: z.literal("preamble"), notes: z.array(TurnNoteSchema) }),
     // The SDK's init handshake; carries the model it actually resolved for the turn.
@@ -666,6 +696,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         lastTool: z.string().optional(),
         summary: z.string().optional(),
         error: z.string().optional(),
+        // Whether anything checked the work the report describes (SubagentVerificationSchema). Rides the frame
+        // that ENDS the child, beside the report itself, so the card carries both at once.
+        verification: SubagentVerificationSchema.optional(),
     }),
     z.object({ kind: z.literal("todos"), items: z.array(TodoItemSchema) }),
     // The provider's own slash commands (ACP available_commands_update), replaced whole each time, the
@@ -875,6 +908,19 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // already moved on. It rides verbatim, exactly as the client POSTed it; absent, nobody answered (the turn
     // was stopped, or died under the card), which is not a decision and must not replay as one.
     z.object({ kind: z.literal("resolved"), requestId: z.string(), reply: AgentReplySchema.optional() }),
+    /* A LATE SENTENCE FOR A CARD ALREADY ON SCREEN: the quick model's plain-language reading of a held command,
+     * landing on the permission card named by `requestId` (see PermissionAsk.explain).
+     *
+     * A frame of its own rather than a field on the card, because the card MUST NOT WAIT FOR IT. This is a
+     * safety prompt and the turn is parked on it; a quick-model rung can take tens of seconds before the chain
+     * steps down (agent/quick-model.ts measured one at 58), and holding the card back for that reads exactly
+     * like the agent freezing, which is the failure the explanation was meant to prevent rather than cause. So
+     * the card goes out complete and unexplained, and this arrives if and when it does. Same shape and the same
+     * reason as `service_event`, which streams a running service's status onto an offer already rendered.
+     *
+     * Never arrives at all when the setting is off, when nothing is connected to answer, or when the user
+     * settles the card first, and none of those change what the card says. */
+    z.object({ kind: z.literal("permission_note"), requestId: z.string(), explain: z.string() }),
     // The turn's permission mode, whenever it changes, the user's pick at turn start, then every move the
     // AGENT makes on its own (EnterPlanMode on a request that needs thinking through, ExitPlanMode once the
     // user approves). The composer's mode selector follows this, so the UI never lies about the live posture.
@@ -955,6 +1001,22 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                  * context-window-too-small does: they never reached a provider, and losing them to a
                  * capacity fact the user did not cause would be ours to answer for. */
                 "sandbox-memory-low",
+                /* THE LOOP RAN OUT OF ITERATIONS, not out of work: the runtime hit its own turn ceiling and
+                 * stopped. Nothing failed, nothing is disconnected and nothing is spent, which is exactly why
+                 * it needs a code of its own rather than a sentence: it is the one ending that LOOKS like a
+                 * finished turn from the outside, and a ledger that filed it as an ordinary error told a
+                 * reader nothing they could act on.
+                 *
+                 * The recovery is the user's, not the daemon's: whatever the turn was doing is half done, and
+                 * re-running it blind would either redo the finished half or resume work nobody looked at. */
+                "turn-cap",
+                /* THE HARNESS ENDED THE TURN WITHOUT SUCCEEDING and did not say why in terms anything here
+                 * models: an internal execution error, or a result subtype a later vendor build invented. The
+                 * sentence carries the subtype verbatim, because that word is the only thing separating two of
+                 * these, and a code that meant "one of several unrelated things" would be worse than none. It
+                 * is a real classification all the same: it says the failure came from the LOOP rather than
+                 * from the provider, the credential or the request, which rules out every recovery next door. */
+                "harness-incomplete",
             ])
             .optional(),
         // rate_limit only: when the exhausted window reopens (epoch seconds, from the stream's own
@@ -971,6 +1033,25 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         // Absent means there is nothing automatic to resume: a spent usage limit never has one,
         // and a refused credential has none once re-minting it has already been tried and failed.
         autoResume: z.enum(["scheduled", "available"]).optional(),
+        /* THE DAEMON IS STILL HOLDING THIS EXACT TURN, so the way on is to RE-RUN it rather than to send
+         * something after it. rate_limit only, and the counterpart to `autoResume` rather than a member of it:
+         * that field answers "is a machine bringing this back", and a spent allowance is the one failure where
+         * the answer is deliberately no (the allowance is the user's own budget to spend, turn-resume.ts). This
+         * answers the question that was never asked, "and if the user says go, what happens", which had exactly
+         * one possible answer for as long as it went unasked: a new user message reading "Continue".
+         *
+         * That answer was wrong in a way the chat could not show. The press is not a new instruction, it is the
+         * same one again, and appending it said otherwise to the only reader that matters: the provider session
+         * grew one "Continue" per press, each with a synthetic "No response requested." above it, so a chat that
+         * bounced four times handed the model four turns in which it appeared to have declined to answer. With
+         * this field the press re-runs the held turn instead, which is idempotent by construction (a second press
+         * finds a live turn and supersedes nothing) and leaves the transcript one row for one press.
+         *
+         * `ran` is whether the held turn got anywhere before it was refused, and it changes both what the model
+         * is told (RESUME_NOTES.limit vs .refused, and telling a model to carry on from work that never happened
+         * is how it comes to invent some) and what the strip can honestly say. A spent allowance refuses the
+         * FIRST request most of the time, so false is the common case, not the corner. */
+        held: z.object({ ran: z.boolean() }).optional(),
         /* provider-outage only: the shape of the wait. `retryAt` (epoch seconds) is when the next attempt is
          * due, not a fixed cadence, because an outage has no reset instant to aim at and hammering a provider
          * that is down only spends tokens on refusals, so each attempt waits longer than the last
@@ -1035,6 +1116,23 @@ export const RESUME_NOTES = {
     auth: `The Claude credential that interrupted this conversation has been renewed, and this turn resumed automatically. ${REPEATED}`,
     outage: `The model provider was briefly unavailable and interrupted this conversation; this turn resumed automatically. ${REPEATED}`,
     restart: `The sandbox restarted while this turn was running, which stopped it, and this turn resumed automatically once it came back. ${REPEATED}`,
+    /* A SPENT ALLOWANCE STRANDS A TURN IN TWO SHAPES, and they must not share a note.
+     *
+     * `limit` is the mid-turn one and reads like its three neighbours above: the session holds real work, and
+     * carrying on from it is exactly right.
+     *
+     * `refused` is the turn the provider turned away at the door, before the model read one word of it, and it
+     * is the COMMONER of the two, because an allowance that is already spent refuses the first request it is
+     * asked. REPEATED is actively wrong for it: "part of it was already completed in this session, continue from
+     * that point instead of starting over" is an instruction to continue from work that does not exist, and a
+     * model handed that instruction answers it by inventing the work. So it says the opposite, plainly.
+     *
+     * Both are unlike their neighbours in one way worth stating: nothing resumed automatically. A spent
+     * allowance is the user's own budget and stays their call to spend (turn-resume.ts), so what re-ran this
+     * turn was a person pressing Continue. */
+    limit: `The model provider's usage allowance ran out while this turn was running, which stopped it, and it has been sent again. ${REPEATED}`,
+    refused:
+        "The model provider refused the previous attempt at this request outright, because its usage allowance was spent: no part of the request below was read or acted on, and nothing has been done towards it. It has been sent again, and starts from the beginning.",
     // A turn that was PARKED on the user when the daemon died: nothing re-runs at boot, the card is restored
     // instead, and this is the turn their answer starts (turn-resume.ts). What rides below the note is the
     // answer itself, so the model picks the session back up at exactly the decision it had handed over.
@@ -1080,6 +1178,14 @@ const RESUME_DISCLOSURES: Record<ResumeReason, ResumeDisclosure> = {
     auth: { kind: "notice", text: "Claude sign-in renewed, this turn picked up where it left off." },
     outage: { kind: "notice", text: "The model provider came back, this turn picked up where it left off." },
     restart: { kind: "notice", text: "The sandbox came back, this turn picked up where it left off." },
+    /* THE ONE PAIR NOBODY AUTOMATED, said in the passive voice the other three earn honestly and these two do
+     * not: a person pressed Continue. Which is the whole reason these rows exist at all. A press used to append
+     * the word "Continue" as a message of its own, so a chat that bounced off a spent allowance four times read
+     * back as the user saying "Continue" four times to an agent that had answered none of them, and the provider
+     * session the model actually reads accumulated all four (plus a synthetic "No response requested." per
+     * press). One row for one press was never the problem; a row that claims the user said something new is. */
+    limit: { kind: "notice", text: "Sent again after the allowance ran out mid-turn, picking up where it left off." },
+    refused: { kind: "notice", text: "Sent again after the allowance refused it: nothing had run." },
     answered: { kind: "note", note: { title: "Picked back up after a sandbox restart", text: RESUME_NOTES.answered } },
 };
 

package/src/fast-tier.ts

@@ -1,6 +1,6 @@
 import { compareCheapestFirst, isCheaperRung } from "./model-order.js";
 import { parsePinned } from "./quick-model.js";
-import type { AgentProvider } from "./schemas.js";
+import type { AgentProvider } from "./schemas/agent.js";
 
 /* WHICH MODEL A DOWNGRADED TURN ACTUALLY RUNS ON, the second half of automatic tier selection.
  * prompt-complexity.ts decides a turn COULD be cheaper; this decides whether there is anything cheaper to put

package/src/history-state.ts

@@ -128,6 +128,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "sync-enrollments.json", portability: "identity", note: "Re-pair desktop sync from the Sync tab." },
     { path: "sync-pair-consumed.json", portability: "identity" },
     { path: "host-enrollments.json", portability: "identity" },
+    /* A connected BROWSER's enrollment (webext/webext-store.ts). Identity for the hosts file's reason and one
+     * more of its own: the token admits a socket into somebody's signed-in browser, and that browser was paired
+     * with THIS sandbox — carried into another one it would either be dead weight or, worse, a second sandbox
+     * holding a live key to a browser its owner never connected it to. Re-pairing is a code and one click. */
+    { path: "webext-enrollments.json", portability: "identity", note: "Pair your browser again from its card: the extension is still installed." },
     // The burn list for setup-time computer pairings. Identity, like sync's beside it, and for a sharper reason:
     // carrying it into another sandbox would mark that sandbox's own fresh pairing as already spent.
     { path: "host-pair-consumed.json", portability: "identity" },

package/src/host-protocol.ts

@@ -24,7 +24,7 @@ export const HostHelloSchema = z.object({
      * onto one-shot tickets, auth/ws-tickets.ts). A frame is body, not URL, so it is logged nowhere. Until this
      * arrives the socket is anonymous and short-lived: the daemon closes it in seconds if it never does. */
     token: z.string(),
-    // The @intentic/host build the machine is running, surfaced per machine so an old binary is visible rather
+    // The @intentic/machine build the machine is running, surfaced per machine so an old binary is visible rather
     // than mysteriously missing a tool. What the machine IS (`describe`) is not here: it is pulled over the
     // typed link a moment later, so there is one definition of those facts rather than two.
     version: z.string(),

package/src/hostnames.test.ts

@@ -25,8 +25,8 @@ test("preview and port hostnames round-trip through their Host-header parsers",
 });
 
 test("the two schemes never bleed into each other, and stray/wrong-id hosts parse to nothing", () => {
-    expect(portSlotFromHost("preview-app-" + ID + ".example.com", ID)).toBeUndefined();
-    expect(panelFromHost("port-a-" + ID + ".example.com", ID)).toBeUndefined();
+    expect(portSlotFromHost(`preview-app-${ID}.example.com`, ID)).toBeUndefined();
+    expect(panelFromHost(`port-a-${ID}.example.com`, ID)).toBeUndefined();
     expect(panelFromHost("app.example.com", ID)).toBeUndefined();
     expect(panelFromHost(`preview-app-000000000000.example.com`, ID)).toBeUndefined();
     expect(portSlotFromHost(`port-a-000000000000.example.com`, ID)).toBeUndefined();

package/src/index.ts

@@ -59,6 +59,9 @@ export { historyContract } from "./contracts/history.contract.js";
 /* Deliberately NOT part of `sandboxContract` below: that map is the daemon's own HTTP surface, and this one is
  * spoken the other way round, over a connected computer's WebSocket, with the MACHINE implementing it. */
 export { hostContract } from "./contracts/host.contract.js";
+// The same inversion again, one layer in: spoken over the socket a BROWSER EXTENSION opened, with the
+// extension implementing it (contracts/webext.contract.ts).
+export { webextContract } from "./contracts/webext.contract.js";
 // Same inversion, other direction of trust: spoken over a RUNNER's WebSocket, with the runner implementing it.
 export { runnerContract } from "./contracts/runner.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
@@ -104,11 +107,14 @@ export * from "./history-state.js";
 export * from "./agent-catalog.js";
 export * from "./agent-run-model.js";
 export * from "./capability-env.js";
+export * from "./command-classes.js";
 export * from "./capability-secrets.js";
 export * from "./conversation-ids.js";
 export * from "./documents.js";
 export * from "./fast-tier.js";
 export * from "./host-protocol.js";
+export * from "./webext-protocol.js";
+export * from "./webext-links.js";
 export * from "./runner-protocol.js";
 export * from "./listener-protocol.js";
 export * from "./hostnames.js";
@@ -118,7 +124,61 @@ export * from "./prompt-complexity.js";
 export * from "./quick-model.js";
 export * from "./output-fields.js";
 export * from "./publish-drafts.js";
-export * from "./schemas.js";
+/* The wire shapes, one module per subject area, mirroring `contracts/` above: every request and response the
+ * daemon speaks is declared in exactly one of them. Inputs that carry a `{param}` in their route path (repo /
+ * id / name) merge the path param into the same flat object, oRPC fills the path placeholder from the matching
+ * key and routes the rest to the body (POST/PUT) or query (GET).
+ *
+ * `schemas/internal.ts` is deliberately absent: it holds the id and ref primitives these modules are written
+ * in, which are vocabulary rather than shapes either side of the wire sends. */
+export * from "./schemas/activity.js";
+export * from "./schemas/agent.js";
+export * from "./schemas/agents.js";
+export * from "./schemas/automations.js";
+export * from "./schemas/capabilities.js";
+export * from "./schemas/ci.js";
+export * from "./schemas/claude-gate.js";
+export * from "./schemas/codebase-health.js";
+export * from "./schemas/computers.js";
+export * from "./schemas/drafts.js";
+export * from "./schemas/environment.js";
+export * from "./schemas/exit.js";
+export * from "./schemas/extension-updates.js";
+export * from "./schemas/fast-mode.js";
+export * from "./schemas/git.js";
+export * from "./schemas/git-history.js";
+export * from "./schemas/history.js";
+export * from "./schemas/hosts.js";
+export * from "./schemas/intentic.js";
+export * from "./schemas/inventory.js";
+export * from "./schemas/logs.js";
+export * from "./schemas/loops.js";
+export * from "./schemas/maintenance.js";
+export * from "./schemas/marketplace.js";
+export * from "./schemas/panels.js";
+export * from "./schemas/personas.js";
+export * from "./schemas/plan-limits.js";
+export * from "./schemas/ports.js";
+export * from "./schemas/provider-oauth.js";
+export * from "./schemas/provider-subscriptions.js";
+export * from "./schemas/public.js";
+export * from "./schemas/push.js";
+export * from "./schemas/secrets.js";
+export * from "./schemas/sessions.js";
+export * from "./schemas/settings.js";
+export * from "./schemas/share.js";
+export * from "./schemas/shared.js";
+export * from "./schemas/system.js";
+export * from "./schemas/terminal.js";
+export * from "./schemas/usage.js";
+export * from "./schemas/vpn.js";
+export * from "./schemas/webext.js";
+export * from "./schemas/workflows.js";
+export * from "./schemas/workspace-repos.js";
+export * from "./schemas/workspace-search.js";
+export * from "./schemas/workspace-setup.js";
+export * from "./schemas/workspace-tree.js";
+export * from "./definition.js";
 export * from "./search-globs.js";
 export * from "./starter.js";
 export * from "./terminal-protocol.js";

package/src/listener-protocol.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ActivityStatusSchema } from "./schemas.js";
+import { ActivityStatusSchema } from "./schemas/activity.js";
 
 /* The wire between the daemon and an extension's realtime-listener GATEWAY process (ext-discord, ext-slack,
  * ext-telegram, ext-whatsapp, ext-imap): the four provider-scoped routes app.ts mounts under

package/src/quick-model.ts

@@ -1,6 +1,6 @@
 import { ACCESS_COST, accessFor, modelsFor, PROVIDERS } from "./agent-catalog.js";
 import { compareCheapestFirst, familyOf, tierRankOf } from "./model-order.js";
-import type { AgentProvider } from "./schemas.js";
+import type { AgentProvider } from "./schemas/agent.js";
 
 /* THE QUICK MODEL, the cheap, fast model a small automatic job spends instead of the frontier model the chat
  * runs on. Today that is the commit message written when an agent's work lands; anything else of that shape (a