@intentic/sandbox-contract 1.226.1 → 1.228.0

package/dist/starter.d.ts

@@ -0,0 +1,3 @@
+export declare const STARTER_REPO = "site";
+export declare const STARTER_APP = "landing";
+//# sourceMappingURL=starter.d.ts.map

package/dist/starter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter.d.ts","sourceRoot":"","sources":["../src/starter.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,YAAY,SAAS,CAAC;AACnC,eAAO,MAAM,WAAW,YAAY,CAAC"}

package/dist/starter.js

@@ -0,0 +1,3 @@
+export const STARTER_REPO = "site";
+export const STARTER_APP = "landing";
+//# sourceMappingURL=starter.js.map

package/dist/starter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter.js","sourceRoot":"","sources":["../src/starter.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AACnC,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/sandbox-contract",
-  "version": "1.226.1",
+  "version": "1.228.0",
   "description": "oRPC wire contract for the intentic sandbox daemon, shared by the daemon and its browser client",
   "license": "MIT",
   "type": "module",
@@ -89,15 +89,16 @@
     "@orpc/contract": "1.14.13",
     "tslib": "2.8.1",
     "zod": "4.4.3",
-    "@intentic/constants": "1.226.1",
-    "@intentic/extension-manifest": "1.226.1",
-    "@intentic/registry": "1.226.1"
+    "@intentic/constants": "1.228.0",
+    "@intentic/extension-manifest": "1.228.0",
+    "@intentic/registry": "1.228.0"
   },
   "devDependencies": {
     "@types/node": "24.13.2",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "vitest": "4.1.10",
-    "@intentic/tsconfig": "0.0.0"
+    "@intentic/tsconfig": "0.0.0",
+    "@intentic/testing": "0.0.0"
   },
   "scripts": {
     "build": "tsgo",

package/src/agent-catalog.test.ts

@@ -39,9 +39,9 @@ describe("every provider/harness pair declares what it can do", () => {
 
         // Nothing may be left to inference: a `permissions` a surface can't read, or a runtime nobody serves,
         // is the drift this record exists to end.
-        expect(["claude-code", "codex", "opencode", "opencode-gemini", "acp", "pi"]).toContain(capabilities.runtime);
+        expect(["claude-code", "codex", "cursor", "opencode", "opencode-gemini", "acp", "pi"]).toContain(capabilities.runtime);
         expect(["modes", "plan"]).toContain(capabilities.permissions);
-        expect(["full", "browser", "http", "none"]).toContain(capabilities.mcp);
+        expect(["full", "tools", "browser", "http", "none"]).toContain(capabilities.mcp);
         // Every runtime executes SOMETHING: a record listing no backend would hide the shell every loop has.
         expect(capabilities.execution).toContain("shell");
         for (const backend of capabilities.execution) {

package/src/agent-catalog.ts

@@ -30,6 +30,10 @@ export const PROVIDERS: readonly { label: string; value: NativeProvider }[] = [
     // and that channel vends Claude and GPT-OSS models alongside Gemini's own (see gemini-models.ts). A section
     // headed "Gemini" holding Claude Opus would be a lie; "Google" is what the whole list has in common.
     { label: "Google", value: "gemini" },
+    // Cursor's own agent runtime, driven through the SDK Anysphere publishes, on the user's Cursor subscription.
+    // Like Google above, the label names the ACCOUNT rather than a model family: the channel vends Anthropic,
+    // OpenAI and xAI models alongside Cursor's own Composer, and no model name covers that list.
+    { label: "Cursor", value: "cursor" },
 ];
 
 // What it COSTS to unlock a provider, and what the user connects to do it, the axis the picker groups on, since
@@ -52,6 +56,11 @@ export const PROVIDER_ACCESS: Record<NativeProvider, ProviderAccess> = {
     grok: { kind: "subscription", requirement: "SuperGrok subscription", runs: "Grok" },
     kimi: { kind: "subscription", requirement: "Kimi Code subscription", runs: "Kimi Code" },
     gemini: { kind: "free", requirement: "Google sign-in", runs: "Gemini, Claude and GPT-OSS under Claude Code" },
+    // A `subscription` like the first four, and the requirement names the PLAN rather than the account, because
+    // a free Cursor account signs in perfectly and still cannot run a turn here: the SDK behind this provider is
+    // gated to the paid tiers. Saying "Cursor account" would send someone to a sign-in that ends in a refusal
+    // they had no way to predict.
+    cursor: { kind: "subscription", requirement: "Cursor Pro subscription", runs: "Cursor Agent" },
 };
 
 /* THE PROVIDERS THAT COST NOTHING, derived from the table above rather than named a second time, and read by
@@ -59,14 +68,14 @@ export const PROVIDER_ACCESS: Record<NativeProvider, ProviderAccess> = {
  *
  * The distinction is worth the export. `accessBadge` answers "what does this row cost" for a row the user is
  * already looking at; this answers "which row should a user who has connected nothing be shown FIRST", which is
- * the connect gate's whole job. Ranking the one free channel fifth among five equal buttons is how a user with
+ * the connect gate's whole job. Ranking the one free channel last among equal buttons is how a user with
  * no subscription concluded the product needed one. Deriving the list keeps that promotion honest: a channel
  * that stops being free stops being promoted, from one edit to PROVIDER_ACCESS. */
 export const FREE_PROVIDERS: readonly NativeProvider[] = NATIVE_PROVIDERS.filter((provider) => PROVIDER_ACCESS[provider].kind === "free");
 export const isFreeProvider = (provider: AgentProvider): boolean => FREE_PROVIDERS.includes(provider as NativeProvider);
 
 /* WHOSE ALLOWANCE A TURN ON THIS PROVIDER SPENDS, as the subject of a sentence, a third naming of the same
- * five ids, and the third is not redundancy. PROVIDERS names the RUNTIME the user picks ("Claude Code", "Kimi
+ * six ids, and the third is not redundancy. PROVIDERS names the RUNTIME the user picks ("Claude Code", "Kimi
  * Code") and PROVIDER_ACCESS.requirement names the thing they CONNECT ("Claude subscription", "Google sign-in");
  * neither reads as English in "… usage limit reached", and neither is what a spent quota belongs to.
  *
@@ -80,6 +89,10 @@ export const PROVIDER_VENDOR: Record<NativeProvider, string> = {
     grok: "xAI",
     kimi: "Kimi Code",
     gemini: "Google",
+    // The plan that gets billed is Cursor's, whichever vendor's model actually answered. A Cursor turn on Claude
+    // Opus spends Cursor's included usage and Anthropic has no part in it, the same reasoning that makes a
+    // `gemini` turn say "Google" above.
+    cursor: "Cursor",
 };
 
 // What a turn on this provider costs at the MARGIN, ordering the same three kinds by the only question a
@@ -190,8 +203,8 @@ export const HARNESSES: readonly { label: string; value: AgentHarness }[] = [
 
 /* WHAT A PROVIDER/HARNESS PAIR CAN ACTUALLY DO, one declaration, read by both sides of the wire.
  *
- * Five runtimes serve turns behind one seam (AgentRequest in, AgentEvent frames out): the Claude Code Agent SDK
- * loop, Codex app-server, OpenCode, any ACP agent, and Pi's RPC surface. They do NOT do the same things, and for a long time
+ * Six runtimes serve turns behind one seam (AgentRequest in, AgentEvent frames out): the Claude Code Agent SDK
+ * loop, Codex app-server, OpenCode, Cursor's own loop run in-process, any ACP agent, and Pi's RPC surface. They do NOT do the same things, and for a long time
  * the only thing that said so was a comment inside each adapter, "Ignores the Claude-only request fields",
  * which no surface above it could read. So the composer offered "Ask before each file edit" on a runtime whose
  * every tool call is pre-approved, and offered a reasoning-effort scale to a runtime that drops the field.
@@ -217,7 +230,7 @@ export interface AgentCapabilities {
     // `opencode-gemini` is the OpenCode loop pointed at Gemini rather than at xAI, and it is a SEPARATE runtime
     // id from `opencode` on purpose: adapter health is keyed by this field (adapter-health.ts), so sharing one
     // would make Grok's xAI credential decide whether the picker greys out Gemini, and the reverse.
-    readonly runtime: "claude-code" | "codex" | "opencode" | "opencode-gemini" | "acp" | "pi";
+    readonly runtime: "claude-code" | "codex" | "opencode" | "opencode-gemini" | "acp" | "pi" | "cursor";
     // Mid-turn injection (the SteeringQueue behind /agent/steer). Needs the SDK's streaming-input mode.
     readonly steering: boolean;
     // How much of the permission-mode axis the runtime honours. "modes" = every PermissionMode, with per-tool
@@ -226,12 +239,20 @@ export interface AgentCapabilities {
     readonly permissions: "modes" | "plan";
     // Can stop mid-turn and ask the user a multiple-choice question (`question` frames).
     readonly questions: boolean;
-    // Which of the turn's tools reach the agent. "full" = http MCP tools + in-process SDK servers + plugin
-    // checkouts + the browser servers; "browser" = the process-backed browser servers alone; "http" = the http
-    // MCP tools alone, and only if the agent advertises http MCP support; "none" = the runtime has no seam for
-    // them at all. Keeping the partial answers distinct matters: a runtime that can drive a connected account
-    // must not be described as tool-less, and one that cannot host daemon-side SDK servers must not claim full.
-    readonly mcp: "full" | "browser" | "http" | "none";
+    /* Which of the turn's tools reach the agent. "full" = http MCP tools + in-process SDK servers + plugin
+     * checkouts + the browser servers; "tools" = all of that EXCEPT plugin checkouts; "browser" = the
+     * process-backed browser servers alone; "http" = the http MCP tools alone, and only if the agent advertises
+     * http MCP support; "none" = the runtime has no seam for them at all. Keeping the partial answers distinct
+     * matters: a runtime that can drive a connected account must not be described as tool-less, and one that
+     * cannot host daemon-side SDK servers must not claim full.
+     *
+     * "tools" exists for the Cursor runtime and would have been a lie either way without it. Cursor's SDK takes
+     * stdio AND http/sse MCP servers, and its `customTools` run host callbacks in this process, which is the
+     * seam an in-process SDK server needs, so calling it "browser" would understate it by three whole
+     * categories. What it genuinely cannot host is a Claude Code PLUGIN checkout: that is a directory layout the
+     * Agent SDK loads, not a protocol, and no other runtime will ever read one. So the gap is real, permanent
+     * and worth its own word rather than being rounded to "full". */
+    readonly mcp: "full" | "tools" | "browser" | "http" | "none";
     /* WHICH EXECUTION BACKENDS THE RUNTIME HOSTS, the ways a turn RUNS things, as opposed to the tools it is
      * handed. "shell" is the runtime's own command tool (Bash on the Claude Code loop, each foreign loop's
      * equivalent); "js" is the sandbox's JavaScript backend (execution/ in the daemon): the model writes a
@@ -468,7 +489,7 @@ const ACP: AgentCapabilities = {
     secrets: "none",
 };
 
-/* THE PI CAPABILITY ID IS RESERVED, the same way the five native ids are: an `agent`-kind capability installed
+/* THE PI CAPABILITY ID IS RESERVED, the same way the six native ids are: an `agent`-kind capability installed
  * under it is served over Pi's own RPC protocol rather than ACP. Pi closed ACP support deliberately (its RPC
  * mode is the embedding surface), and the two want different records. A bare id rather than a namespace like
  * `endpoint/`, because there is exactly one Pi runtime to name; capabilitiesOf still answers from the id alone,
@@ -504,6 +525,86 @@ const PI: AgentCapabilities = {
     secrets: "none",
 };
 
+/* CURSOR'S OWN AGENT RUNTIME, driven through `@cursor/sdk`, the SDK Anysphere publishes, in this daemon's own
+ * process. The second-richest row in this file after the Claude Code loop, and the reason is the SDK rather
+ * than the vendor: it is an EMBEDDING surface, not a CLI wrapped in a pipe, so most of the seams the other
+ * foreign runtimes lack are simply function arguments here.
+ *
+ * WHY NOT THROUGH OPENCODE, which is already in this image and already serves two providers. Every Cursor
+ * bridge for OpenCode is a community reverse-engineering of Cursor's private agent RPC or a localhost shim
+ * around its CLI, and the OPENCODE record above is the weakest in this file. Routing Cursor through it would
+ * have capped a first-party SDK at Grok's ceiling and made the row depend on a third party's spare time.
+ *
+ * WHY THE HARNESS AXIS DOESN'T APPLY, the same way it doesn't for Gemini, and for the mirror-image reason.
+ * Gemini has no Claude Code route because Google refuses that traffic; Cursor has none because there is no
+ * translator route at all, CLIProxyAPI does not serve Cursor as a provider (asked for repeatedly upstream and
+ * closed as not planned), and Cursor publishes no OpenAI-compatible endpoint on a subscription. The SDK IS the
+ * only door, so `capabilitiesOf` answers this record whatever harness the client sent.
+ *
+ * The three axes below that read weaker than they could are deliberate, not unfinished: see the notes on each. */
+const CURSOR: AgentCapabilities = {
+    runtime: "cursor",
+    // The SDK's Run can be cancelled but not written to mid-flight: a second `send` on a busy agent is an
+    // AgentBusyError, not an injection. So the steering queue has nowhere to go and the composer hides it.
+    steering: false,
+    /* Cursor's OWN plan mode (`mode: "agent" | "plan"`), not this repo's two-phase emulation, which is the
+     * better version of the same bargain: the model is put in a read-only posture by the vendor rather than
+     * being asked to behave.
+     *
+     * Not "modes", and that is the honest half. The hook seam below can gate shell, MCP, file reads and file
+     * edits, which is most of the tool surface but not all of it, and a per-tool posture with a silent gap in
+     * it is worse than one that says where it stops. */
+    permissions: "plan",
+    /* TRUE BECAUSE WE SUPPLY THE TOOL, not because Cursor's own askQuestion is wired. That one is put in
+     * `disallowedTools`: in a headless run it has been reported to answer itself with a fabricated "Questions
+     * skipped by the user", which is the single worst failure shape available here, an agent acting on consent
+     * nobody gave. The ask tool the daemon registers through `customTools` runs in this process, parks on a
+     * real card, and cannot invent an answer because it is the thing that receives one. */
+    questions: true,
+    // stdio + http/sse MCP servers, plus host callbacks through `customTools` (which is where the browser stack
+    // and the in-process SDK servers land). Everything but a Claude Code plugin checkout, see the axis note.
+    mcp: "tools",
+    execution: ["shell"],
+    /* Cursor publishes effort as MODEL PARAMETERS rather than as one scale (`ModelListItem.parameters` /
+     * `variants` → `ModelSelection.params`), so the shared tiers are mapped onto whatever the selected model
+     * declares, and a model that declares none simply offers no control. True here because the axis is
+     * forwardable at all; which tiers exist is the live catalog's answer, not this record's. */
+    effort: true,
+    fastMode: false,
+    /* "cwd", and this is the one place the SDK's in-process design costs something. A namespace is built around
+     * a CHILD the daemon spawns (that is how the Claude Code loop and Codex app-server get theirs); Cursor's
+     * loop runs inside the daemon, whose own /work must stay the shared checkout, so an isolated conversation
+     * gets its worktree by working directory and the turn is told where its tree is (turn-preamble.ts). */
+    isolation: "cwd",
+    // Cursor's commands are files on disk (`.cursor/commands`), which the SDK loads but does not publish back,
+    // so there is no list to hand the `/` popover.
+    commands: false,
+    // The SDK runs its shell in-process; there is no tmux session for the terminal panel to attach to.
+    terminals: false,
+    // The SDK throws typed errors (RateLimitError and friends) rather than dissolving a refusal into prose, so
+    // the adapter can file the coded frames auto-resume keys off.
+    recovery: true,
+    /* "append", the OpenCode answer, reached by a completely different road. There is no system-prompt argument
+     * on `Agent.create`; what there is, is the `beforeSubmitPrompt` hook, whose reply carries
+     * `additional_context` that is folded into the request. So the owner's prompt and the persona note DO reach
+     * the model, on top of Cursor's own base prompt, and nothing can replace that base. */
+    instructions: "append",
+    /* THE FULL HOOK TIER, the only foreign runtime that reaches it. Cursor reads `.cursor/hooks.json` in its
+     * local runtime, and `beforeShellExecution` answers with `allow` / `deny` / `ask` plus the messages that
+     * explain it, with `failClosed` available so a crashed gate blocks instead of waving the command through.
+     *
+     * What earns "hooks" rather than "approval" is that a HOLD can genuinely park: the hook is a process the
+     * daemon wrote, so it blocks on the card and the vendor is simply waiting on a script, exactly the shape
+     * that makes the Claude Code loop's PreToolUse hook able to stop and ask. The vendor never decides which
+     * calls to raise, either, which is the caveat the "approval" tier carries and this one does not. */
+    rulebook: "hooks",
+    /* "none", and structurally so, like every other foreign runtime. Masking needs a seam that rewrites what
+     * the model READS after a tool ran; Cursor's `afterShellExecution` fires with the output but its reply is
+     * discarded upstream, and `beforeReadFile` sees the content only to allow or deny it. Both are gates, not
+     * filters, so there is nothing here to substitute a reference back into. */
+    secrets: "none",
+};
+
 // The pair → its record. An `endpoint/<id>` provider is a model API the user configured, driven BY the Claude
 // Code loop on either harness, so it gets that loop's full ceiling, which is the entire point of routing a
 // model through it rather than adopting a second runtime. The reserved `pi` id is the Pi coding agent on its
@@ -528,6 +629,13 @@ export const capabilitiesOf = (provider: AgentProvider, harness: AgentHarness):
     if (provider === "gemini") {
         return OPENCODE_GEMINI;
     }
+    // Cursor ignores the harness for the mirror of Gemini's reason: there is no route to it but its own SDK. No
+    // translator serves Cursor and Cursor publishes no model endpoint on a subscription, so "Cursor under Claude
+    // Code" names a road that does not exist. Answering this record whatever was asked for is what keeps that a
+    // fact of the catalog rather than a rule each surface has to remember.
+    if (provider === "cursor") {
+        return CURSOR;
+    }
     if (isEndpointProvider(provider)) {
         return CLAUDE_CODE;
     }
@@ -565,7 +673,9 @@ export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
           ? ["MCP tools only: no plugins or browser"]
           : capabilities.mcp === "browser"
             ? ["browser tools only: no plugins or other MCP tools"]
-            : []),
+            : capabilities.mcp === "tools"
+              ? ["no plugins: every other tool reaches it"]
+              : []),
     ...(capabilities.execution.includes("js") ? [] : ["no code runs, its shell is the one way to execute"]),
     ...(capabilities.effort ? [] : ["no effort control"]),
     ...(capabilities.commands ? [] : ["no slash commands"]),

package/src/contract-lock.test.ts

@@ -5,8 +5,14 @@ import { currentLock } from "./contract-lock.js";
 /* The committed lock and the code must say the same thing: see contract-lock.ts for what the pair buys.
  *
  * This is the HALF that runs everywhere the tests run; the other half (a shrunk lock needs a declared break)
- * lives in prepass.mjs, which has git and this suite does not. */
-test("contract.lock.json matches the schemas this package exports", () => {
+ * lives in prepass.mjs, which has git and this suite does not.
+ *
+ * ITS OWN BUDGET, because the default one is a HANG DETECTOR and this test does real work: it serializes every
+ * schema this package exports, ~500 of them, to JSON Schema. That is ~100ms with the machine to itself and it
+ * measured 8.8s on a runner running every package's suite at once, so vitest's 5s default failed it as a hang
+ * over a contract that had not moved: green on a box, red on a busy runner, the trap _tools/testing/src/vitest
+ * .ts is written against. 30s is well clear of the work and still reports a genuine hang inside half a minute. */
+test("contract.lock.json matches the schemas this package exports", { timeout: 30_000 }, () => {
     const committed: unknown = JSON.parse(readFileSync(new URL("../contract.lock.json", import.meta.url), "utf8"));
     expect(
         currentLock(),

package/src/contracts/agents.contract.ts

@@ -13,6 +13,7 @@ import {
     AgentResumeAfterOutageSchema,
     AgentSearchQuerySchema,
     AgentSearchResultSchema,
+    AgentsArchivedSchema,
     AgentsListSchema,
     AgentsMovedSchema,
     AgentsRemovedSchema,
@@ -233,7 +234,7 @@ export const agentsContract = {
                 "The gentle counterpart to discarding. Commits whatever the conversation still has in progress onto its own branch, releases its working copy, and keeps the entry and the record. It leaves the live fleet and joins the archive. Refused for a conversation that is running.",
         })
         .input(AgentArchiveSchema)
-        .output(AgentsMovedSchema),
+        .output(AgentsArchivedSchema),
     unarchive: oc
         .route({
             method: "POST",

package/src/contracts/cursor.contract.ts

@@ -0,0 +1,74 @@
+import { oc } from "@orpc/contract";
+import {
+    AccountIdSchema,
+    AccountListQuerySchema,
+    AccountRenameSchema,
+    CursorLoginCancelSchema,
+    CursorLoginStartSchema,
+    OauthAccountListSchema,
+    OauthAccountSchema,
+    OkSchema,
+} from "../schemas.js";
+
+/* Cursor subscription sign-in, the sandbox owns the credential and the platform never sees it, the same bargain
+ * claude.contract.ts strikes. What differs is who finishes the handshake.
+ *
+ * Claude's flow is start → the browser gets a code → `exchange` hands it back. Cursor's PKCE verifier is
+ * redeemable on its own, so it never leaves the daemon: `start` begins the flow, keeps the verifier in memory,
+ * polls Cursor until the browser completes the sign-in, mints a 90-day user key and writes it as an account.
+ * The caller opens the URL and then watches `accounts`, exactly as it does for a device login, which is why
+ * there is no `exchange` route here and a `cancel` one instead.
+ *
+ * The model catalog is deliberately absent, as it is for every provider: it is the one question they all answer
+ * identically, so it lives on the shared /providers/{provider}/models route (providers.contract.ts). */
+export const cursorContract = {
+    start: oc
+        .route({
+            method: "POST",
+            path: "/cursor/login/start",
+            summary: "Begin connecting a Cursor account",
+            description:
+                "Hands back the page to sign in on. The sandbox finishes the handshake itself and stores the credential, so nothing has to be pasted back: watch the account list instead.",
+        })
+        .output(CursorLoginStartSchema),
+    cancel: oc
+        .route({
+            method: "POST",
+            path: "/cursor/login/cancel",
+            summary: "Abandon a Cursor sign-in",
+            description: "Stops waiting on a sign-in nobody completed. An abandoned attempt also expires on its own.",
+        })
+        .input(CursorLoginCancelSchema)
+        .output(OkSchema),
+    // Shaped like Claude's, including `force`, so the two account lists render through one component. Cursor
+    // publishes no account-wide headroom today, so `usage` stays absent on these rows and they draw a dot rather
+    // than a ring, which is what an unmeasured account has always meant here.
+    accounts: oc
+        .route({
+            method: "GET",
+            path: "/cursor/accounts",
+            summary: "Connected Cursor accounts",
+            description:
+                "Each connected account, and whether its stored key is still good. Cursor publishes no plan-wide allowance, so these rows carry no usage reading.",
+        })
+        .input(AccountListQuerySchema)
+        .output(OauthAccountListSchema),
+    rename: oc
+        .route({
+            method: "POST",
+            path: "/cursor/account/rename",
+            summary: "Rename a Cursor account",
+            description: "Changes the label one account shows under, so several are tellable apart.",
+        })
+        .input(AccountRenameSchema)
+        .output(OauthAccountSchema),
+    disconnect: oc
+        .route({
+            method: "POST",
+            path: "/cursor/account/disconnect",
+            summary: "Disconnect a Cursor account",
+            description: "Clears the stored key for one account. The others stay connected.",
+        })
+        .input(AccountIdSchema)
+        .output(OkSchema),
+};

package/src/contracts/logs.contract.ts

@@ -1,8 +1,10 @@
 import { oc } from "@orpc/contract";
-import { LogReadQuerySchema, LogReadSchema, LogsListSchema } from "../schemas.js";
+import { ClientDiagnosticsAcceptedSchema, ClientDiagnosticsReportSchema, LogReadQuerySchema, LogReadSchema, LogsListSchema } from "../schemas.js";
 
 // Daemon-owned debug logs (historyRoot/logs): terminal pipe-pane captures, intentic CLI run logs, daemon.log.
-// Read-only by design, the files are written by the daemon/tmux only, so the record stays trustworthy.
+// Reads are read-only by design, the files are written by the daemon/tmux only, so the record stays
+// trustworthy. `report` is the one write, and the exception that proves the rule: the browser is the only
+// witness to its own crashes, and a record it cannot reach is a record that has nothing to say about them.
 export const logsContract = {
     list: oc
         .route({
@@ -22,4 +24,23 @@ export const logsContract = {
         })
         .input(LogReadQuerySchema)
         .output(LogReadSchema),
+    /* What the browser saw. The counterpart to every other route here: those serve what the daemon wrote down,
+     * this accepts what only the browser could have known.
+     *
+     * A WRITE from the client, which every other log route deliberately is not, and the trust argument is the
+     * inverse of theirs: the reads are trustworthy because only the daemon writes them, and this is trustworthy
+     * only about ITSELF. So it lands in its own file, never daemon.log, and its lines say plainly that a browser
+     * said them. It floors at viewer rather than the maintainer the logs prefix takes, because a viewer whose
+     * page just white-screened is exactly who needs to be able to report it, and cannot raise their own role to
+     * do it. */
+    report: oc
+        .route({
+            method: "POST",
+            path: "/logs/client",
+            summary: "Report what the browser saw",
+            description:
+                "Errors the app caught, stalls it measured, and recoveries it performed, written to a log of their own. The browser is the only witness to these, so without it a bug someone hit in their own browser leaves no record at all.",
+        })
+        .input(ClientDiagnosticsReportSchema)
+        .output(ClientDiagnosticsAcceptedSchema),
 };

package/src/events.ts

@@ -387,6 +387,19 @@ export const RestoredMessageSchema = z.object({
         .describe(
             "A person wrote this in the agent's voice, with no turn behind it. Marked for the human re-reading the conversation months later, so their own words do not pass as the agent's. The agent itself never sees the mark.",
         ),
+    /* THE ONE-PRESS OFFER A RECORDED NOTICE CARRIES (notice rows only), named rather than inferred from its
+     * words. Only `tierHold` today: the line saying this turn ran on a cheaper model, whose offer is "keep this
+     * chat on my pick".
+     *
+     * It is on the wire because the offer has to survive a reopen, and a reopened tab has only the record. The
+     * chat's other one-press notices are drawn live and never recorded, so they never needed this; a routed turn
+     * is different precisely because the whole point of recording it is that somebody reads it LATER. A KIND, not
+     * a callback, exactly as the live ones are: the reader decides what the press does and whether the offer
+     * still stands (a chat already holding its pick shows a settled sentence, not a stale button). */
+    noticeAction: z
+        .enum(["tierHold"])
+        .optional()
+        .describe("A one-press follow-up this recorded notice offers, by name. The chat decides what it does and whether it still applies."),
 });
 export type RestoredMessage = z.infer<typeof RestoredMessageSchema>;
 
@@ -667,6 +680,33 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         // wasn't asked for.
         reason: z.string().optional(),
     }),
+    /* WHAT THE COMPLEXITY JUDGE MADE OF THIS TURN, emitted once at turn start on every judged turn (that is,
+     * whenever settings.autoTier is not "off"), for the same reason fast_mode exists: a mechanism that can
+     * change what a turn runs on fails silently unless the daemon says what it decided. One tiny frame per
+     * turn, deliberately on the standard verdicts too, because the client's composer preview needs the
+     * conversation's LAST verdict (prompt-complexity.ts `afterHardTurn`) and a frame only on the interesting
+     * turns would leave it guessing on the common ones.
+     *
+     * `tier`/`score`/`rules` are the verdict verbatim (judgeComplexity): the rules are the named-feature
+     * vocabulary of ComplexityRule, carried as strings so a frame from a build with a rule this client hasn't
+     * heard of still parses. `model` is present only when a substitution actually applies to THIS turn, which
+     * is `routed` (mode on, verdict fast, something cheaper published) or `held` (the same turn the user pinned
+     * to their pick, see AgentTurn.tierHold): measure mode never names one because naming it would cost the
+     * catalog read shadow mode exists to avoid.
+     *
+     * `routed` is what HAPPENED, never implied by the verdict: a fast verdict in measure mode, under a hold, or
+     * with nothing cheaper published all run the user's own pick and say `routed: false`. */
+    z.object({
+        kind: z.literal("tier"),
+        tier: z.enum(["fast", "standard"]),
+        score: z.number(),
+        rules: z.array(z.string()),
+        // The cheaper model this turn ran on (routed) or would have run on (held). Absent otherwise.
+        model: z.string().optional(),
+        routed: z.boolean(),
+        // The user pinned this turn to their pick (AgentTurn.tierHold), so a fast verdict moved nothing.
+        held: z.boolean().optional(),
+    }),
     /* The turn is alive but WAITING on the provider: a request failed transiently (5xx, 529, a dropped socket)
      * and the harness is retrying it inside this same turn. A status, not a failure, nothing has been lost and
      * the turn may still finish normally, so the client renders it where "thinking" goes rather than in the
@@ -677,7 +717,10 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
      * a hang. The one action a user takes against an apparent hang is Stop, which is the only action that
      * actually loses the work, so the wait has to be visible, with its own next-attempt clock.
      *
-     * `attempt`/`maxAttempts` are the harness's own counters; `nextAttemptAt` (epoch ms) is when it will try
+     * `attempt` is the harness's own counter and `maxAttempts` is the bound that will actually be honoured,
+     * which on the Claude path is the daemon's own cap on how deep a storm may get rather than the harness's
+     * far longer budget (MAX_IN_TURN_RETRIES in sdk-stream.ts, which ends the turn at the cap and hands the
+     * waiting to the outage breaker). `nextAttemptAt` (epoch ms) is when it will try
      * again, so the readout counts down instead of freezing on a number nobody can interpret. BOTH are optional
      * for the same reason, which is that each runtime publishes a different half of the wait and none of them
      * publishes all of it: Claude's harness reports the delay and the bound, Codex says which attempt it is on
@@ -836,11 +879,16 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                  * is, so nothing is re-run and nothing asks the user to reconnect, the one recovery that looks
                  * plausible and is guaranteed to waste their time. */
                 "claude-not-entitled",
-                // The model provider itself failed transiently: 500/502/503, a 529 at capacity, a dropped
-                // socket, and the harness's own in-turn retries did not outlast it. Nothing about the workspace
-                // or the request is wrong, so the daemon remembers the turn and re-runs it on an escalating
-                // backoff (provider-health.ts): the frame is a notice about a turn that is coming back, and
-                // reaches the client as a plain failure only once the attempts are spent.
+                /* The model provider itself failed transiently: 500/502/503, a 529 at capacity, a dropped
+                 * socket, and the harness's own in-turn retries did not outlast it. Nothing about the workspace
+                 * or the request is wrong, so the daemon remembers the turn and re-runs it on an escalating
+                 * backoff (provider-health.ts): the frame is a notice about a turn that is coming back, and
+                 * reaches the client as a plain failure only once the attempts are spent.
+                 *
+                 * ONE 4xx JOINS THEM, the provider refusing a request PARAMETER nothing here sends (its own
+                 * cache-retention default, or one a proxy added). It wears a client error's status code and is
+                 * still a provider fault: there is no request of the user's to fix, and the same send goes
+                 * through moments later, so it recovers the same way (agent/failure-sentences.ts). */
                 "provider-outage",
                 // The platform-owned free-trial pool failed after its bounded key walk. Unlike provider-outage,
                 // this is never auto-resumed: failed calls are refunded and the user's message is held to retry.
@@ -855,6 +903,14 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 "unknown-command",
                 "grok-model-invalid",
                 "codex-model-invalid",
+                /* THE MODEL CANNOT HOLD A TURN OF THIS AGENT LOOP, so the daemon refused before sending
+                 * (agent/context-budget.ts). Its own code because none of the neighbours describes it: nothing is
+                 * disconnected, nothing is spent, nothing comes back on a clock, and re-sending the same request
+                 * at the same model fails identically forever. What changes the outcome is the model or the
+                 * server's context flag, so the message names both and the client HOLDS the words: they never
+                 * reached anything, and losing them to a configuration fact would be the one part of this that
+                 * was our fault. */
+                "context-window-too-small",
                 "subscription-required",
                 "agent-busy",
             ])

package/src/index.ts

@@ -8,6 +8,7 @@ import { capabilitiesContract } from "./contracts/capabilities.contract.js";
 import { choresContract } from "./contracts/chores.contract.js";
 import { ciContract } from "./contracts/ci.contract.js";
 import { claudeContract } from "./contracts/claude.contract.js";
+import { cursorContract } from "./contracts/cursor.contract.js";
 import { draftsContract } from "./contracts/drafts.contract.js";
 import { endpointsContract } from "./contracts/endpoints.contract.js";
 import { exitContract } from "./contracts/exit.contract.js";
@@ -46,6 +47,7 @@ export { capabilitiesContract } from "./contracts/capabilities.contract.js";
 export { choresContract } from "./contracts/chores.contract.js";
 export { ciContract } from "./contracts/ci.contract.js";
 export { claudeContract } from "./contracts/claude.contract.js";
+export { cursorContract } from "./contracts/cursor.contract.js";
 export { draftsContract } from "./contracts/drafts.contract.js";
 export { endpointsContract, type TrialHealth, TrialStatusSchema, type TrialStatusResponse } from "./contracts/endpoints.contract.js";
 export { exitContract } from "./contracts/exit.contract.js";
@@ -60,6 +62,7 @@ export { hostContract } from "./contracts/host.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
+export { REQUEST_ID_EVIDENCE_ROUTE, REQUEST_ID_HEADER } from "./request-id.js";
 export { loopsContract } from "./contracts/loops.contract.js";
 export { panelsContract } from "./contracts/panels.contract.js";
 export { portsContract } from "./contracts/ports.contract.js";
@@ -113,6 +116,7 @@ export * from "./output-fields.js";
 export * from "./publish-drafts.js";
 export * from "./schemas.js";
 export * from "./search-globs.js";
+export * from "./starter.js";
 export * from "./terminal-protocol.js";
 export * from "./title.js";
 export * from "./versions.js";
@@ -130,6 +134,7 @@ export const sandboxContract = {
     chores: choresContract,
     ci: ciContract,
     claude: claudeContract,
+    cursor: cursorContract,
     drafts: draftsContract,
     endpoints: endpointsContract,
     extensions: extensionsContract,