@intentic/sandbox-contract 1.227.0 → 1.228.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/sandbox-contract",
-  "version": "1.227.0",
+  "version": "1.228.1",
   "description": "oRPC wire contract for the intentic sandbox daemon, shared by the daemon and its browser client",
   "license": "MIT",
   "type": "module",
@@ -89,16 +89,16 @@
     "@orpc/contract": "1.14.13",
     "tslib": "2.8.1",
     "zod": "4.4.3",
-    "@intentic/constants": "1.227.0",
-    "@intentic/registry": "1.227.0",
-    "@intentic/extension-manifest": "1.227.0"
+    "@intentic/constants": "1.228.1",
+    "@intentic/extension-manifest": "1.228.1",
+    "@intentic/registry": "1.228.1"
   },
   "devDependencies": {
     "@types/node": "24.13.2",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "vitest": "4.1.10",
-    "@intentic/testing": "0.0.0",
-    "@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/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/events.ts

@@ -879,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.

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";
@@ -132,6 +134,7 @@ export const sandboxContract = {
     chores: choresContract,
     ci: ciContract,
     claude: claudeContract,
+    cursor: cursorContract,
     drafts: draftsContract,
     endpoints: endpointsContract,
     extensions: extensionsContract,

package/src/schemas.ts

@@ -54,7 +54,7 @@ export const RepoParamSchema = z.object({
 // ACP (Agent Client Protocol).
 // Kept as a bare string on the wire (not an enum) so an unknown id is a clean error frame from the agent
 // route, the same bet RepoParamSchema makes, and adding an ACP agent needs no contract change.
-export const NATIVE_PROVIDERS = ["claude", "codex", "grok", "kimi", "gemini"] as const;
+export const NATIVE_PROVIDERS = ["claude", "codex", "grok", "kimi", "gemini", "cursor"] as const;
 export type NativeProvider = (typeof NATIVE_PROVIDERS)[number];
 export const AgentProviderSchema = z.string().min(1);
 export type AgentProvider = z.infer<typeof AgentProviderSchema>;
@@ -1367,6 +1367,22 @@ export const AgentsMovedSchema = z.object({
         ),
 });
 export type AgentsMoved = z.infer<typeof AgentsMovedSchema>;
+/* AN ARCHIVE ALSO REPORTS WHAT IT COULD NOT DO, which is the half that used to go missing. Releasing a working
+ * copy is git work, and it can fail for reasons no press can fix: the repository behind a checkout was deleted
+ * from the workspace, a checkout is locked. Those agents stay on the board, so the answer carries them and the
+ * sentence each failed with, otherwise the only true thing the caller could say about an archive that moved
+ * nothing was "there was nothing to archive": to a user looking straight at the card it refused. */
+export const AgentsArchivedSchema = AgentsMovedSchema.extend({
+    failed: z
+        .array(
+            z.object({
+                id: z.string().describe("Which conversation stayed on the board."),
+                reason: z.string().describe("Why its working copy could not be released, in the words the failure came with."),
+            }),
+        )
+        .describe("The conversations this press could not put away, each with the reason, so the board can say it instead of reporting silence."),
+});
+export type AgentsArchived = z.infer<typeof AgentsArchivedSchema>;
 // What a purge actually deleted. Ids, not summaries: these agents no longer exist anywhere, there is nothing
 // left to show and nothing to put back, so the only thing the caller can do with the answer is drop those rows
 // and count them. No revision either: archived agents are already off the broadcast roster (see `list`), so a
@@ -1981,6 +1997,33 @@ export const AuthorizeChallengeSchema = z.object({
     verifier: z.string().describe("Keep this and send it back when finishing. It is what proves the code that comes back belongs to this handshake."),
     state: z.string().describe("The handshake's own id, sent back with it."),
 });
+
+/* CURSOR'S SIGN-IN START. A third login shape, and the reason it is not one of the two above is where the
+ * SECRET lives during the handshake.
+ *
+ * Claude's is paste-back: the browser receives a code and the caller hands it plus its verifier to `exchange`,
+ * so the handshake's proof has to travel on the wire and AuthorizeChallengeSchema carries it. Cursor's PKCE
+ * verifier must never leave the process that generated it, anyone holding it can redeem the login and mint a
+ * durable key, so the daemon starts the whole flow, keeps the verifier in memory, polls Cursor itself, and
+ * writes the account when it lands. Nothing redeemable is on this shape at all.
+ *
+ * Which makes it behave like a DEVICE flow from the caller's side (open the page, then watch the account list),
+ * except that there is no one-time code to display: the login page is addressed to this handshake already. So
+ * DeviceStartSchema's `code` would be a permanently blank field on every card, and TranslatorStartSchema's
+ * `state` a value nothing sends back. `handshake` is neither, it is a cancellation handle. */
+export const CursorLoginStartSchema = z.object({
+    url: z.string().describe("The page to open and sign in on. It is already addressed to this attempt, so there is no code to type."),
+    handshake: z
+        .string()
+        .describe(
+            "This attempt's id, for abandoning it. Not a credential and not redeemable: the proof that finishes the sign-in never leaves the sandbox.",
+        ),
+    expiresAt: z.number().describe("When this attempt stops being answerable, in milliseconds, so a card can stop waiting instead of spinning."),
+});
+export type CursorLoginStart = z.infer<typeof CursorLoginStartSchema>;
+// Abandon a sign-in nobody completed, so the daemon stops polling Cursor for it. Ordinary tidiness rather than
+// a security boundary: an unanswered attempt also times out on its own (see `expiresAt`).
+export const CursorLoginCancelSchema = z.object({ handshake: z.string().min(1).describe("Which attempt to stop waiting on.") });
 // xAI Grok (via OpenCode) uses subscription OAuth via the headless device-code method. `start` returns the
 // `url` the user opens (xAI's verification_uri_complete, which pre-fills the code) and `code`, the same
 // one-time code, surfaced so the card matches x.ai exactly. There is no paste-back: OpenCode polls to
@@ -4977,11 +5020,48 @@ export const EndpointConfigSchema = z.object({
  *
  * `gpu` mirrors the docker card's option and rides the same allowlisted `--gpus=all` directive: the ASK lives
  * here, what became of it is SANDBOX_GPU, stamped by the runner (see the docker handler's gpuState). "on"/"off"
- * rather than a boolean for the manifest-wide reason DockerConfigSchema gives. */
+ * rather than a boolean for the manifest-wide reason DockerConfigSchema gives.
+ *
+ * `context`/`contextTokens` are HOW MUCH CONVERSATION the server holds, the `model`/`url` pair's shape for the
+ * same reason: a short list of rungs anyone can choose between, and one escape hatch for a person who knows the
+ * exact number they want. Resolved to a single token count in exactly one place (the daemon's
+ * endpoints/local-model.ts localModelWindow), because the flag llama-server is started with and the number the
+ * card promises must never be two opinions. */
+export const LOCAL_MODEL_WINDOWS = ["16384", "32768", "65536", "131072"] as const;
+export type LocalModelWindow = (typeof LOCAL_MODEL_WINDOWS)[number];
+
+/* THE RUNG A CARD WITH NO OPINION LANDS ON, and the one number in this block that is a product decision rather
+ * than an arithmetic one.
+ *
+ * It is 65,536 because this sandbox runs a TOOL-CALLING AGENT LOOP, and that loop's own fixed cost, its
+ * instructions plus one JSON schema per tool it can call, times every capability the owner has connected, is
+ * tens of thousands of tokens before the user has typed anything (agent/context-budget.ts holds the measurement
+ * and the refusal built on it). A window that cannot hold that cost is not a smaller version of the product; it
+ * is a model whose every real turn is refused, which is what the previous flat 32,768 shipped: a 27B model,
+ * seventeen gigabytes downloaded, and a first message that died on `36216 tokens exceeds 32768`.
+ *
+ * So the default is the smallest rung a full turn fits in, and the smaller rungs stay on the list because they
+ * are honestly useful: pinned as the quick model (titles, commit messages) a window this size is waste, and the
+ * gigabyte it gives back is the difference between running one of these models on an eight-gigabyte laptop and
+ * not. What each rung costs in memory is the card's job to say (capability-catalog): roughly 2 GB of quantized
+ * cache per 32k of window, on top of the weights. */
+export const LOCAL_MODEL_WINDOW_DEFAULT: LocalModelWindow = "65536";
+
+/* THE BOUNDS ON THE TYPED NUMBER, and they are bounds against a TYPO rather than against a preference. Below
+ * the floor there is no conversation left to have once the loop's own instructions land; above the ceiling is a
+ * number no GGUF on offer was trained for, and llama-server would spend minutes reserving a cache for it before
+ * failing. Everything between is the owner's call: their machine, their memory. */
+export const LOCAL_MODEL_WINDOW_MIN = 2048;
+export const LOCAL_MODEL_WINDOW_MAX = 1_048_576;
+
 export const LocalModelConfigSchema = z.object({
     model: z.string().min(1),
     gpu: z.enum(["on", "off"]).default("off"),
     url: z.url().optional(),
+    context: z.union([z.enum(LOCAL_MODEL_WINDOWS), z.literal("custom")]).default(LOCAL_MODEL_WINDOW_DEFAULT),
+    // Coerced because it arrives from a text field as a string, the ssh card's `port` precedent, and only read
+    // when `context` is "custom" (the `url`/`model` relationship exactly).
+    contextTokens: z.coerce.number().int().min(LOCAL_MODEL_WINDOW_MIN).max(LOCAL_MODEL_WINDOW_MAX).optional(),
 });
 export type LocalModelConfig = z.infer<typeof LocalModelConfigSchema>;
 /* THE SANDBOX WALLET, a USDC balance the agent can spend on x402-payable endpoints, under owner policy.