@intentic/sandbox-contract 1.223.0 → 1.225.0

package/src/fast-tier.test.ts

@@ -0,0 +1,88 @@
+import { expect, test } from "vitest";
+import { fastTierModel } from "./fast-tier.js";
+
+/* WHERE A DOWNGRADED TURN ACTUALLY LANDS. The judge (prompt-complexity.ts) says a turn could be cheaper; this
+ * says whether there is anywhere cheaper to put it, on the provider it is already on.
+ *
+ * Two properties carry the whole feature, and everything below is one of them: a downgrade is only ever to a
+ * genuinely CHEAPER rung of the same catalog (so "cheaper" can never quietly become "older", or "the same model
+ * with less thinking"), and it never crosses PROVIDER (because that retires the conversation's session, which
+ * throws away the context that made the follow-up cheap to answer in the first place). */
+
+const CLAUDE = [`claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5-20251001`];
+const GOOGLE = [`gemini-3-pro`, `gemini-3-flash`, `gemini-3-flash-lite`];
+
+const fastFor = (model: string, over: { models?: readonly string[]; pinned?: readonly string[]; provider?: string } = {}) =>
+    fastTierModel({ provider: over.provider ?? `claude`, model, models: over.models ?? CLAUDE, pinned: over.pinned ?? [] });
+
+// --- Auto: the cheapest rung the provider publishes ----------------------------------------------------
+
+test("sends a frontier turn to the provider's own cheap rung", () => {
+    expect(fastFor(`claude-opus-5`)).toBe(`claude-haiku-4-5-20251001`);
+});
+
+test("reads the cheap end the same way the quick model does, on every vendor's vocabulary", () => {
+    expect(fastFor(`gemini-3-pro`, { provider: `gemini`, models: GOOGLE })).toBe(`gemini-3-flash-lite`);
+});
+
+// --- the ceiling: the user's own pick -------------------------------------------------------------------
+
+test("a user already on the cheap rung has nowhere to be sent", () => {
+    // The common case worth being exact about rather than an edge case. Undefined means "run what they asked
+    // for", which is the honest answer and the one that costs nothing to be wrong about.
+    expect(fastFor(`claude-haiku-4-5-20251001`)).toBeUndefined();
+});
+
+test("never swaps a model for an older build of the same tier", () => {
+    // A downgrade has to be legible AS a downgrade. Last year's Sonnet under this year's Sonnet is not a
+    // saving the feature promised, it is a different turn wearing the user's own model name.
+    expect(fastFor(`claude-sonnet-5`, { models: [`claude-sonnet-5`, `claude-sonnet-4`] })).toBeUndefined();
+});
+
+test("never downgrades a model whose family this build does not recognise", () => {
+    // An id carrying no tier word is a provider's base line or a family nobody here has heard of, and betting
+    // a user's turn on the guess that an unknown id is the budget one is the wrong direction to be wrong in.
+    expect(fastFor(`claude-opus-5`, { models: [`some-new-thing`] })).toBeUndefined();
+    expect(fastFor(`some-new-thing`, { models: CLAUDE })).toBeUndefined();
+});
+
+test("an unloaded catalog resolves to no downgrade rather than to a guess", () => {
+    expect(fastFor(`claude-opus-5`, { models: [] })).toBeUndefined();
+});
+
+test("no pick yet means nothing to be cheaper than", () => {
+    expect(fastFor(``)).toBeUndefined();
+});
+
+// --- pins -----------------------------------------------------------------------------------------------
+
+test("a pin on this provider wins over the catalog's own cheap end", () => {
+    expect(fastFor(`claude-opus-5`, { pinned: [`claude:claude-sonnet-5`] })).toBe(`claude-sonnet-5`);
+});
+
+test("takes a pinned id verbatim, so a model the static catalog has not caught up with is still pinnable", () => {
+    // The same call resolveQuickModels makes, and for the same reason: the picker offers a custom-id escape
+    // hatch, and second-guessing the id here would run a different model than the settings row names.
+    expect(fastFor(`claude-opus-5`, { pinned: [`claude:claude-haiku-9`] })).toBe(`claude-haiku-9`);
+});
+
+test("drops a pin naming another provider rather than crossing to it", () => {
+    // Switching provider retires the conversation's session (turnRequest.ts `resumes`). Starting the
+    // conversation over to save a fraction of a cent is not a saving, so the pin is ignored and Auto answers.
+    expect(fastFor(`claude-opus-5`, { pinned: [`gemini:gemini-3-flash-lite`] })).toBe(`claude-haiku-4-5-20251001`);
+});
+
+test("skips a pin that is not actually cheaper than what the user picked", () => {
+    // A pin is a preference about WHICH cheap rung, never a licence to swap a model for its equal or better.
+    expect(fastFor(`claude-sonnet-5`, { pinned: [`claude:claude-opus-5`] })).toBe(`claude-haiku-4-5-20251001`);
+});
+
+test("walks past an unusable pin to the next one that names this provider", () => {
+    const pinned = [`gemini:gemini-3-flash`, `claude:claude-opus-5`, `claude:claude-haiku-4-5`];
+
+    expect(fastFor(`claude-opus-5`, { pinned })).toBe(`claude-haiku-4-5`);
+});
+
+test("falls back to Auto when no pin survives, rather than to no downgrade at all", () => {
+    expect(fastFor(`claude-opus-5`, { pinned: [`nonsense`, `gemini:gemini-3-flash`] })).toBe(`claude-haiku-4-5-20251001`);
+});

package/src/fast-tier.ts

@@ -0,0 +1,72 @@
+import { compareCheapestFirst, isCheaperRung } from "./model-order.js";
+import { parsePinned } from "./quick-model.js";
+import type { AgentProvider } from "./schemas.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
+ * it on, and names it.
+ *
+ * THERE IS NO "STANDARD TIER" SETTING, and its absence is the design rather than an omission. The standard tier
+ * is whatever the user already picked for this conversation. So this mechanism can only ever route DOWN, from a
+ * model somebody chose to a cheaper rung of the same catalog, which means the worst case of a wrong answer is
+ * one turn's quality on a model the user can see and correct, never a bill they did not ask for. Every
+ * ambiguous case in this file therefore resolves to `undefined`, which the caller reads as "run what they
+ * asked for".
+ *
+ * THE PROVIDER IS NEVER CROSSED, and this is the constraint the rest of the app imposes rather than one this
+ * file would have chosen. A conversation's provider session is resumed only while the selection still matches
+ * the runtime and account that minted it (turnRequest.ts `resumes`, which compares provider, account and
+ * harness, and pointedly NOT model). A model swap inside one provider is free, and the session carries on. A
+ * provider swap RETIRES the session and cuts a new segment, which throws away the very context that made the
+ * follow-up cheap to answer. So a cross-provider pin here is dropped rather than honoured: saving a fraction of
+ * a cent by starting the conversation over is not a saving.
+ *
+ * THE ORDER IS A LADDER, for the reason quick-model.ts is one, but a shorter one: the caller spends the head
+ * and falls back to the user's own pick, rather than walking rungs. A downgrade that cannot be started is not
+ * worth a second attempt when the honest answer (their model) is sitting right there. */
+
+export interface FastTierInput {
+    // The provider this turn is on. Both the pick and every candidate belong to it; see above.
+    readonly provider: AgentProvider;
+    // The model the user picked, i.e. the standard tier and the ceiling. Empty when the composer has not
+    // resolved one yet, which resolves to no downgrade: there is nothing to be cheaper THAN.
+    readonly model: string;
+    // That provider's catalog as the caller can see it. Empty is a real state (a catalog that has not loaded),
+    // and it resolves to no downgrade rather than to a guess.
+    readonly models: readonly string[];
+    // settings.autoFastModels: an ordered list of `${provider}:${modelId}` keys (quickModelKey), or empty for
+    // Auto. Entries naming another provider are dropped, not honoured.
+    readonly pinned: readonly string[];
+}
+
+/* THE CHEAPER MODEL TO RUN THIS TURN ON, or undefined for "there isn't one, use their pick".
+ *
+ * A PIN IS TAKEN VERBATIM against the catalog, the same call resolveQuickModels makes and for the same reason:
+ * the model picker offers a custom-id escape hatch for a model the static catalog has not caught up with, and
+ * second-guessing the id here would run a different model than the settings row names. It is still checked for
+ * being CHEAPER, because that is not a fact about the catalog, it is a fact about the id, and a pin that is not
+ * cheaper than the pick is not a downgrade at all.
+ *
+ * AUTO IS THE CHEAPEST ROW THE PROVIDER PUBLISHES, read through the same cheap-end order the quick model uses,
+ * so the two features cannot disagree about which rung is the cheap one. Derived, never stored: connect an
+ * account tomorrow and the answer improves by itself, exactly as quickModel's empty default does.
+ *
+ * NOTHING CHEAPER THAN THE PICK ⇒ UNDEFINED, and that is the common case worth being exact about rather than
+ * the edge case: a user already working on the cheap rung has nowhere to be sent, and a user on a model whose
+ * family this build does not recognize is not going to be downgraded on a guess (isCheaperRung). */
+export const fastTierModel = (input: FastTierInput): string | undefined => {
+    if (input.model === "") {
+        return undefined;
+    }
+    const pinned = input.pinned
+        .flatMap((key) => {
+            const choice = parsePinned(key);
+            return choice === undefined || choice.provider !== input.provider ? [] : [choice.model];
+        })
+        .find((model) => isCheaperRung(model, input.model));
+    if (pinned !== undefined) {
+        return pinned;
+    }
+    const cheapest = input.models.toSorted(compareCheapestFirst)[0];
+    return cheapest !== undefined && isCheaperRung(cheapest, input.model) ? cheapest : undefined;
+};

package/src/history-state.ts

@@ -1,14 +1,14 @@
 import type { StateFile } from "./state-portability.js";
 
-/* WHAT LIVES ON /history — the second half of the daemon's state, and the half nothing declared until an
+/* WHAT LIVES ON /history, the second half of the daemon's state, and the half nothing declared until an
  * export had to reason about it.
  *
  * `WORKSPACE_STATE_FILES` covers `<workspace>/.intentic/`, which is where the manifests live. It is not where
- * the machinery lives. Every repo's REAL git dir is here (a repo's in-tree `.git` is a pointer file — see
+ * the machinery lives. Every repo's REAL git dir is here (a repo's in-tree `.git` is a pointer file, see
  * git/repo-git-dirs.ts for the invariant that forces it), and so are the fleet registry, the turn journal, the
  * ledgers, the checkpoint scopes and the isolated agents' checkouts. A "workspace export" that took `/work`
- * alone would carry a tree of repos with dangling gitdir pointers — every git command in the restored sandbox
- * answering `fatal: not a git repository` — and an empty agent board.
+ * alone would carry a tree of repos with dangling gitdir pointers, every git command in the restored sandbox
+ * answering `fatal: not a git repository`, and an empty agent board.
  *
  * The two tables stay separate rather than becoming one keyed by volume, because they answer different
  * questions. A `.intentic` entry also declares which browser QUERY it makes stale, since the file watcher
@@ -17,7 +17,7 @@ import type { StateFile } from "./state-portability.js";
  * imported rather than duplicated.
  *
  * `history-state-coverage.test.ts` fails when a daemon store builds a `/history` path this list doesn't carry, in both
- * directions — the same shape-recognizing guard that covers the workspace table.
+ * directions, the same shape-recognizing guard that covers the workspace table.
  */
 
 // Paths are historyRoot-relative, forward-slash, matched by PREFIX; a directory entry keeps its trailing slash
@@ -27,7 +27,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
 
     /* THE ONE THAT MAKES A BUNDLE A WORKSPACE. Every repo's real git dir, including the /work root's own
      * ("root"), keyed by URI-encoded repo id. Carrying the working tree without this hands the target files
-     * whose `.git` points at a path that does not exist there — which is not a degraded repo but a broken one,
+     * whose `.git` points at a path that does not exist there, which is not a degraded repo but a broken one,
      * and it takes the Changes review, the diff, land and every agent branch with it. The agent BRANCHES live
      * in here too, which is what lets the checkouts below be left out. */
     { path: "gits/", portability: "carry" },
@@ -38,7 +38,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "agents.json", portability: "carry" },
     { path: "turns/", portability: "carry" },
     { path: "transcripts/", portability: "carry" },
-    // What each message can be put back to — a workspace checkpoint, or an isolated conversation's own commits.
+    // What each message can be put back to, a workspace checkpoint, or an isolated conversation's own commits.
     // Carried WITH the transcripts and the scopes above, because it is the join between them: without it a
     // restored conversation reads back whole and offers no way back into it, even though both the messages and
     // the states they name travelled.
@@ -48,7 +48,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
      * Carried, and it is the entry with the most to say for itself: the PAGES live in the workspace's outbox
      * (`public/`), so they travel with `/work` whatever this says. Leaving the index behind would restore a
      * sandbox that is still serving somebody's conversation on the internet with nothing in the app that knows
-     * it — no row, no link, and no way to stop sharing short of deleting files by hand. The index is what makes
+     * it, no row, no link, and no way to stop sharing short of deleting files by hand. The index is what makes
      * a published page withdrawable, so it goes wherever the pages go. */
     { path: "shares.json", portability: "carry" },
     { path: "activity.jsonl", portability: "carry" },
@@ -58,7 +58,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // Explicit first-time dependency setup requests. Carrying the worklist preserves the owner's decision when
     // an export interrupts the queue before its terminal starts; fulfilled entries remove themselves.
     { path: "dependency-requests.json", portability: "carry" },
-    // The deploy engine's own ledgers — a run's events and the check results the Pipelines view reads back.
+    // The deploy engine's own ledgers, a run's events and the check results the Pipelines view reads back.
     { path: "apply-events.ndjson", portability: "carry" },
     { path: "check-events/", portability: "carry" },
 
@@ -68,7 +68,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
      *
      * A conversation's worktree is a full checkout of the monorepo per agent (plus its overlay upper dir), and
      * there can be a hundred of them. None of it is unique: the branch it holds is in `gits/` above, and the
-     * registry entry naming it travels in agents.json — so an imported conversation arrives in exactly the
+     * registry entry naming it travels in agents.json, so an imported conversation arrives in exactly the
      * shape the system already has a name for. `attached()` reports its checkout as absent, the board renders
      * it, and the next turn's `ensure()` re-creates it from the recorded composition, which is the same path an
      * archived agent takes when it runs again. The boot sweep's `git worktree prune` clears the stale admin
@@ -84,7 +84,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: ".isolation-probe", portability: "derived" },
     /* The finished bundles themselves. `derived` is doing real work here rather than describing leftovers: an
      * export that carried the export directory would pack every previous bundle into the new one, and the next
-     * export would pack THAT — each one a multiple of the last. Living on this volume is the other half of the
+     * export would pack THAT, each one a multiple of the last. Living on this volume is the other half of the
      * same guard; under `/work` the file would also be watched, indexed by iq, and snapshotted into history. */
     { path: "exports/", portability: "derived" },
 
@@ -95,7 +95,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     {
         path: "ssh-hosts/",
         portability: "secret",
-        note: "Re-add each ssh host on the Capabilities view — its key does not travel.",
+        note: "Re-add each ssh host on the Capabilities view, its key does not travel.",
     },
     // The cli-proxy's config, which holds the routed subscriptions' provider tokens.
     {
@@ -107,8 +107,8 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     /* ---- identity: what binds this sandbox to its owner, its browsers and its host ---- */
 
     /* Signs every browser session cookie. Carrying it would let a bundle's holder mint sessions against the
-     * target — an export becomes a credential — and the target minting its own costs exactly one sign-in. */
-    { path: "session-secret", portability: "identity", note: "Sign in again — the target signs its own sessions." },
+     * target, an export becomes a credential, and the target minting its own costs exactly one sign-in. */
+    { path: "session-secret", portability: "identity", note: "Sign in again, the target signs its own sessions." },
     {
         path: "browser-access-disabled",
         portability: "identity",
@@ -117,7 +117,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     {
         path: "push.json",
         portability: "identity",
-        note: "Re-enable notifications in the browsers you use — a push subscription is bound to the sandbox that minted it.",
+        note: "Re-enable notifications in the browsers you use, a push subscription is bound to the sandbox that minted it.",
     },
     { path: "sync-enrollments.json", portability: "identity", note: "Re-pair desktop sync from the Sync tab." },
     { path: "sync-pair-consumed.json", portability: "identity" },

package/src/host-protocol.ts

@@ -1,36 +1,36 @@
 import { z } from "zod";
 
-/* The handshake on /system/hosts/connect — the ONE message that is not oRPC.
+/* The handshake on /system/hosts/connect, the ONE message that is not oRPC.
  *
  * Everything a connected computer is asked lives in `hostContract` (contracts/host.contract.ts), spoken over
  * this socket by oRPC's websocket adapter: the machine hosts the server, the daemon holds the client. But a
  * socket has to prove whose it is before it can be given a typed client, and that proof cannot itself be an
- * oRPC call — the daemon has nothing to call yet, and would be attaching a link to a stranger.
+ * oRPC call, the daemon has nothing to call yet, and would be attaching a link to a stranger.
  *
  * So the machine's first act is this frame, in plain JSON. The daemon verifies the token, learns which
  * capability the socket belongs to, and only then attaches the link; from that message on, every byte on the
  * wire is oRPC. Anything arriving before the link exists is either this frame or a closed socket. */
 
 // The MCP protocol revision the machine's tool server implements. Shared because the daemon answers the
-// handshake ITSELF when the machine is asleep (hosts/host.routes.ts) — two spellings of this would mean an
+// handshake ITSELF when the machine is asleep (hosts/host.routes.ts), two spellings of this would mean an
 // offline machine negotiating a different protocol than the same machine awake.
 export const MCP_PROTOCOL_VERSION = "2025-06-18";
 
 export const HostHelloSchema = z.object({
     type: z.literal("hello"),
-    /* The machine's enrollment token — in the FIRST FRAME, never in the URL. A WebSocket has no headers to put
+    /* The machine's enrollment token, in the FIRST FRAME, never in the URL. A WebSocket has no headers to put
      * it in, and the obvious `?token=` would write a durable key to somebody's laptop into Cloudflare's edge
      * logs, the connector's logs and every proxy in between (the reasoning that moved the browser's upgrades
-     * onto one-shot tickets — auth/ws-tickets.ts). A frame is body, not URL, so it is logged nowhere. Until this
+     * 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/host 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(),
 });
 export type HostHello = z.infer<typeof HostHelloSchema>;
 
-// The URL the machine's agent dials, given the sandbox's public URL. Carries no credential — the token rides
+// The URL the machine's agent dials, given the sandbox's public URL. Carries no credential, the token rides
 // the hello frame. One place builds it, so the agent and the daemon route can't disagree about where it lives.
 export const hostConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/hosts/connect`;

package/src/hostnames.test.ts

@@ -42,7 +42,7 @@ test("the local sync folder carries the very id the sandbox's URL does", () => {
     const url = `https://${sandboxHostname(ID, "intentic.dev")}`;
     expect(sandboxIdFromUrl(url)).toBe(ID);
     expect(syncFolder("Radarsu Local", url)).toBe(`~/intentic/radarsu-local-${ID}`);
-    // A bare host (no scheme) and a port are both accepted — the daemon/CLI and the browser pass different shapes.
+    // A bare host (no scheme) and a port are both accepted: the daemon/CLI and the browser pass different shapes.
     expect(sandboxIdFromUrl(`${sandboxHostname(ID, "intentic.dev")}:443`)).toBe(ID);
     // Own-Cloudflare: the owner's chosen subdomain IS the id, so the folder still matches what they browse to.
     expect(syncFolder("shop", "https://dev-box.example.com")).toBe("~/intentic/shop-dev-box");

package/src/hostnames.ts

@@ -1,6 +1,6 @@
 // The single source for the tunnel/preview hostname + ingress scheme, shared by the CLI, platform API, daemon,
 // AND the browser. Pure string builders/parsers with NO node imports (unlike ./tunnel-ids, which needs
-// node:crypto for the digest) — so the web bundle can import them and derive identical names. The caller supplies
+// node:crypto for the digest), so the web bundle can import them and derive identical names. The caller supplies
 // the 12-hex id (sandboxIdFromToken/hostSshIdFromToken in node; WebCrypto in the browser).
 //
 // All four apps MUST agree on these strings: a divergence resolves to NXDOMAIN that resolvers negative-cache for
@@ -18,7 +18,7 @@ export const sshHostname = (id: string, zone: string): string => `ssh-${id}.${zo
  *
  * A public DNS name for a private address looks odd until you ask what the alternative is. A browser on the
  * same machine as the sandbox can reach its daemon in microseconds instead of crossing to a Cloudflare edge
- * and back — but only over HTTPS, because Safari refuses http://127.0.0.1 from an HTTPS page as mixed content
+ * and back, but only over HTTPS, because Safari refuses http://127.0.0.1 from an HTTPS page as mixed content
  * (WebKit 171934, open since 2017), and HTTPS needs a name a public CA will certify. An IP literal cannot have
  * one; this can. The daemon holds the key and gets the certificate by proving control of the zone over
  * DNS-01 (there is nothing on the public internet for a CA to connect to).
@@ -36,36 +36,36 @@ export const hostSshTunnelName = (id: string): string => `host-ssh-${id}`;
 // The proxied-CNAME target every tunnel points its DNS record at.
 export const cfargotunnelCname = (tunnelId: string): string => `${tunnelId}.cfargotunnel.com`;
 
-// The cloudflared ingress catch-all — must be the LAST rule.
+// The cloudflared ingress catch-all, must be the LAST rule.
 export const CATCH_ALL = { service: "http_status:404" } as const;
 
-// Preview scheme: `preview-<panel>-<sandboxId>.<zone>` — one DNS label (the free Universal SSL `*.<zone>` cert
+// Preview scheme: `preview-<panel>-<sandboxId>.<zone>`, one DNS label (the free Universal SSL `*.<zone>` cert
 // covers exactly one level), where <panel> is `<repo>` or `<repo>--<app>` and <sandboxId> pins the hostname to
 // this sandbox (the shared intentic zone hosts many sandboxes; without the id two users' panels would collide).
-// Port-forward scheme: `port-<slot>-<sandboxId>.<zone>` — the same shape with a `port-` prefix, where <slot>
+// Port-forward scheme: `port-<slot>-<sandboxId>.<zone>`, the same shape with a `port-` prefix, where <slot>
 // is one of the sandbox's forward slots (portSlotsFromToken in ./tunnel-ids), not the port number itself:
 // slots keep the intentic-provided path's minted routes bounded and warm while dev servers churn ephemeral
 // ports. The slot labels are salted with the connect token rather than being the letters a…h, so a forwarded
-// port's hostname is not derivable from the (public) sandbox id alone — see tunnel-ids for why that matters.
+// port's hostname is not derivable from the (public) sandbox id alone, see tunnel-ids for why that matters.
 //
-// Outbox scheme: `public-<slot>-<sandboxId>.<zone>` — the same shape again, serving the workspace's `public/`
+// Outbox scheme: `public-<slot>-<sandboxId>.<zone>`, the same shape again, serving the workspace's `public/`
 // directory as static files. <slot> is publicSlotFromToken (./tunnel-ids), salted for the same reason the port
 // slots are, and one record per sandbox rather than a pool: there is one outbox, and its link has to stay good
 // for as long as the file does.
 //
 // A *label* is the first-DNS-label prefix before `-<sandboxId>` (`preview-<panel>` / `port-<slot>` /
-// `public-<slot>`) — the unit the platform's /sandbox/preview-route mints, so one endpoint serves all three.
+// `public-<slot>`), the unit the platform's /sandbox/preview-route mints, so one endpoint serves all three.
 export const previewLabel = (panel: string): string => `preview-${panel}`;
 export const portLabel = (slot: string): string => `port-${slot}`;
 export const publicLabel = (slot: string): string => `public-${slot}`;
 
-// The hostname a label resolves to — what the platform's /sandbox/preview-route mints from the label alone.
+// The hostname a label resolves to, what the platform's /sandbox/preview-route mints from the label alone.
 export const labelHostname = (label: string, id: string, zone: string): string => `${label}-${id}.${zone}`;
 export const previewHostname = (panel: string, id: string, zone: string): string => labelHostname(previewLabel(panel), id, zone);
 export const portHostname = (slot: string, id: string, zone: string): string => labelHostname(portLabel(slot), id, zone);
 export const publicHostname = (slot: string, id: string, zone: string): string => labelHostname(publicLabel(slot), id, zone);
 
-// A label's public URL — undefined unless the sandbox has both a zone and an id (headless/loopback sandboxes
+// A label's public URL, undefined unless the sandbox has both a zone and an id (headless/loopback sandboxes
 // have neither and advertise nothing). One builder, three vocabularies: a panel's preview, a forwarded port's,
 // and the outbox's.
 const labelUrl = (label: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
@@ -79,7 +79,7 @@ export const publicUrl = (slot: string, zone: string | undefined, sandboxId: str
 
 // The key after `<prefix>` from a request's Host header. The first DNS label must carry the prefix (the
 // own-Cloudflare wildcard also catches stray subdomains → undefined → the caller's 404) and, when the sandbox
-// has an id, the exact `-<sandboxId>` suffix — a fixed-length match, so keys containing `-` stay unambiguous.
+// has an id, the exact `-<sandboxId>` suffix, a fixed-length match, so keys containing `-` stay unambiguous.
 // Without an id the bare label is the key (loopback tests and provider-deployed workspaces, which front the
 // proxy themselves).
 const keyFromHost = (prefix: string, hostHeader: string | undefined, sandboxId: string | undefined): string | undefined => {
@@ -103,7 +103,7 @@ export const publicSlotFromHost = (hostHeader: string | undefined, sandboxId: st
     keyFromHost("public-", hostHeader, sandboxId);
 
 // The sandbox's identity AS THE USER SEES IT: the leading DNS label of its public URL, minus the `sandbox-`
-// prefix — `https://sandbox-0f310c3c4db4.intentic.dev` → `0f310c3c4db4`, i.e. sandboxIdFromToken's digest read
+// prefix, `https://sandbox-0f310c3c4db4.intentic.dev` → `0f310c3c4db4`, i.e. sandboxIdFromToken's digest read
 // back off the wire by anyone holding only the URL. On the own-Cloudflare path the label is whatever subdomain
 // the owner chose, so that is the id there. undefined until the sandbox has a URL at all.
 export const sandboxIdFromUrl = (url: string | undefined): string | undefined => {
@@ -124,8 +124,8 @@ export const sandboxIdFromUrl = (url: string | undefined): string | undefined =>
 };
 
 // The LOCAL folder desktop sync mirrors /work into: `~/intentic/<sandbox name>-<sandboxIdFromUrl>`. Both halves
-// are strings the user already has in front of them — the name in the sandbox switcher, the id in the address
-// bar — so the folder on disk and the sandbox it mirrors read as ONE identity: `~/intentic/shop-0f310c3c4db4`
+// are strings the user already has in front of them, the name in the sandbox switcher, the id in the address
+// bar, so the folder on disk and the sandbox it mirrors read as ONE identity: `~/intentic/shop-0f310c3c4db4`
 // belongs to `https://sandbox-0f310c3c4db4.intentic.dev` and nothing else. Keyed on the URL rather than the
 // name alone for the same reason the hostname is: a torn-down sandbox recreated under the same name gets a new
 // id, hence its own fresh folder instead of reusing the dead one's (which cleanup never deletes) and colliding
@@ -142,7 +142,7 @@ export const syncFolder = (name: string, url: string | undefined): string => {
 
 // The Cloudflare zone from a sandbox public URL (https://sandbox-<id>.<zone> → <zone>): the hostname minus its
 // first DNS label. undefined when the URL is unparsable OR the hostname has fewer than three labels (no zone
-// suffix to strip — e.g. a 2-label host would otherwise yield a bare TLD). Accepts scheme-less input too, so it
+// suffix to strip, e.g. a 2-label host would otherwise yield a bare TLD). Accepts scheme-less input too, so it
 // works whether the caller passes `https://…` (daemon/CLI) or a bare host. This is the single reconciled
 // implementation of what used to be the daemon's `zoneFromPublicUrl` and the web's `zoneFromDaemonUrl`.
 export const zoneFromUrl = (url: string | undefined): string | undefined => {

package/src/index.ts

@@ -10,6 +10,7 @@ import { ciContract } from "./contracts/ci.contract.js";
 import { claudeContract } from "./contracts/claude.contract.js";
 import { draftsContract } from "./contracts/drafts.contract.js";
 import { endpointsContract } from "./contracts/endpoints.contract.js";
+import { exitContract } from "./contracts/exit.contract.js";
 import { extensionsContract } from "./contracts/extensions.contract.js";
 import { personasContract } from "./contracts/personas.contract.js";
 import { gitContract } from "./contracts/git.contract.js";
@@ -47,13 +48,14 @@ export { ciContract } from "./contracts/ci.contract.js";
 export { claudeContract } from "./contracts/claude.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";
 export { extensionsContract } from "./contracts/extensions.contract.js";
 export { personasContract } from "./contracts/personas.contract.js";
 export { gitContract } from "./contracts/git.contract.js";
 export { grokContract } from "./contracts/grok.contract.js";
 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. */
+ * spoken the other way round, over a connected computer's WebSocket, with the MACHINE implementing it. */
 export { hostContract } from "./contracts/host.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
@@ -82,13 +84,13 @@ export * from "./routes.js";
 /* THE CONTAINER'S FIXED DIRECTORY LAYOUT, re-exported so extensions can reach it.
  *
  * The names are defined once in @intentic/constants, which sits at the bottom of the dependency graph. An
- * EXTENSION may not import that package — the boundary rule (.oxlintrc.json, _extensions/README.md) allows
+ * EXTENSION may not import that package, the boundary rule (.oxlintrc.json, _extensions/README.md) allows
  * only the SDK halves and this contract, so that an extension cannot couple itself to app or engine internals.
  * That rule is right, and it left extensions with no way to name the workspace root except by spelling it.
  *
  * Re-exporting here is what closes that gap without widening the boundary: the layout is exactly the kind of
- * thing this package already carries — shared vocabulary both sides of the wire must agree on, alongside the
- * state-file table below — and there is still one definition, in one place, that everything resolves to. */
+ * thing this package already carries, shared vocabulary both sides of the wire must agree on, alongside the
+ * state-file table below, and there is still one definition, in one place, that everything resolves to. */
 export { HISTORY_ROOT, HOST_STATE_ROOT, STATE_DIR, WORKSPACE_ROOT } from "@intentic/constants";
 export * from "./workspace-state.js";
 export * from "./runtime-state.js";
@@ -99,11 +101,13 @@ export * from "./agent-run-model.js";
 export * from "./capability-env.js";
 export * from "./capability-secrets.js";
 export * from "./conversation-ids.js";
+export * from "./fast-tier.js";
 export * from "./host-protocol.js";
 export * from "./listener-protocol.js";
 export * from "./hostnames.js";
 export * from "./model-order.js";
 export * from "./path-refs.js";
+export * from "./prompt-complexity.js";
 export * from "./quick-model.js";
 export * from "./output-fields.js";
 export * from "./publish-drafts.js";
@@ -114,7 +118,7 @@ export * from "./title.js";
 export * from "./versions.js";
 export * from "./workflow-faults.js";
 
-// The aggregated contract — implemented on the server by the per-domain route factories and consumed by the
+// The aggregated contract, implemented on the server by the per-domain route factories and consumed by the
 // browser's typed oRPC client (ContractRouterClient<typeof sandboxContract>). The wire paths it declares are
 // mounted at the sandbox root, so /health and /workspace/raw (plain Hono routes) sit alongside it.
 export const sandboxContract = {
@@ -153,18 +157,19 @@ export const sandboxContract = {
     translator: translatorContract,
     usage: usageContract,
     vpn: vpnContract,
+    exit: exitContract,
     workflows: workflowsContract,
 };
 
 // Every route in THIS build of the contract, and the names the daemon advertises on its hello frame. Bound here
-// rather than in routes.ts so that module stays a pure function of whatever contract it is handed — importing
+// rather than in routes.ts so that module stays a pure function of whatever contract it is handed, importing
 // `sandboxContract` from there would close a load-time cycle back through this file. See routes.ts for why a
 // daemon advertises its route surface at all.
 export const SANDBOX_ROUTES: readonly ContractRoute[] = contractRoutes(sandboxContract);
 export const SANDBOX_ROUTE_NAMES: readonly string[] = SANDBOX_ROUTES.map((route) => route.name);
 
 /* And the SHAPE of each of those routes, advertised beside the names for the failure the names cannot describe:
- * a route both builds have, answering a payload only one of them expects. Computed once at module load — it
+ * a route both builds have, answering a payload only one of them expects. Computed once at module load, it
  * walks every contract schema through `z.toJSONSchema`, which is far too much work to repeat per connection and
  * exactly the kind of thing that never changes for the life of a process. See routes.ts. */
 export const SANDBOX_ROUTE_SHAPES: Readonly<Record<string, string>> = routeShapes(sandboxContract);
@@ -174,7 +179,7 @@ export const sandboxRouteName = (method: string, pathWithQuery: string): string
     routeNameForRequest(SANDBOX_ROUTES, method, pathWithQuery);
 
 // The method and concrete path a TYPED call is about to put on the wire, bound to this build's route table.
-// Undefined when the procedure is not one this contract declares, which a typed caller cannot reach — the host
+// Undefined when the procedure is not one this contract declares, which a typed caller cannot reach, the host
 // gate treats it as a refusal rather than assuming it is harmless.
 export const sandboxRequestFor = (procedure: readonly string[], input: unknown): { method: string; path: string } | undefined => {
     const route = routeForProcedure(SANDBOX_ROUTES, procedure);

package/src/listener-protocol.ts

@@ -3,14 +3,14 @@ import { ActivityStatusSchema } from "./schemas.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
- * /listeners/:provider — state, dispatch, failure, status. These shapes used to live daemon-side only, with
+ * /listeners/:provider, state, dispatch, failure, status. These shapes used to live daemon-side only, with
  * every gateway hand-writing its own copy of the payloads as untyped literals; a field rename broke five
- * producers silently. They live in the contract now so BOTH ends compile against one declaration — the daemon
+ * producers silently. They live in the contract now so BOTH ends compile against one declaration, the daemon
  * parses with the schemas, the gateways (via @intentic/connector-runtime) type against the inferred types. */
 
-// One normalized inbound event — serialized as a JSON line in the automation's payload, and the JSON body a
+// One normalized inbound event, serialized as a JSON line in the automation's payload, and the JSON body a
 // realtime source POSTs to /listeners/<provider>/dispatch. A zod schema (not a bare interface) because it's
-// parsed from an extension gateway's request; `provider` and `type` are open strings — the source is
+// parsed from an extension gateway's request; `provider` and `type` are open strings, the source is
 // extension-declared (contributes.listener), not a core enum.
 export const ListenerMessageSchema = z.object({
     provider: z.string().min(1),
@@ -22,7 +22,7 @@ export const ListenerMessageSchema = z.object({
     // Discord message: it @mentions one of our bots or replies to a bot's message. Voice events never set it.
     mentioned: z.boolean().optional(),
     // CI pipeline event: the ref it ran on. Top-level rather than inside `extra` for the same reason
-    // `mentioned` is — the dispatcher MATCHES on it, and a narrowing axis the trigger can name has to be
+    // `mentioned` is, the dispatcher MATCHES on it, and a narrowing axis the trigger can name has to be
     // a field of the message rather than a key in a provider's opaque bag.
     branch: z.string().optional(),
     // Prior channel messages (chronological) fetched when a bot is tagged, so the agent can reason about why.
@@ -45,13 +45,13 @@ export const ListenerMessageSchema = z.object({
 });
 export type ListenerMessage = z.infer<typeof ListenerMessageSchema>;
 
-// One ndjson frame of a /listeners/<provider>/dispatch?stream=1 response — a text delta for one automation's
+// One ndjson frame of a /listeners/<provider>/dispatch?stream=1 response, a text delta for one automation's
 // reply, the provider's own failure sentence, or that automation's terminal marker. A type, not a schema: the
 // DAEMON produces these (listener.routes.ts), so nothing parses them from untrusted input.
 export interface ListenerDispatchFrame {
     readonly automationId: string;
     readonly delta?: string;
-    // The turn refused or broke, in the provider's own words — forwarded verbatim because a gateway delivers
+    // The turn refused or broke, in the provider's own words, forwarded verbatim because a gateway delivers
     // into the owner's own channel, where the actual sentence is the useful thing.
     readonly failed?: string;
     readonly end?: boolean;
@@ -61,16 +61,16 @@ export interface ListenerDispatchFrame {
  *
  * A CODE IS NOT THE ONLY THING WORTH SAYING, and publishing only codes is what made a phone that had never
  * linked read as connected: the seconds before the first code, a gateway that just restarted, and a number
- * WhatsApp refused all looked identical from the daemon's side — an absent code — so the card fell through to
+ * WhatsApp refused all looked identical from the daemon's side, an absent code, so the card fell through to
  * "ready" and the owner was sent away from the one screen that could have shown them the step. Each of those is
  * its own state here, and every one of them means NOT PAIRED YET.
  *
  * `since` stamps the CURRENT code. WhatsApp closes an unpaired socket after a minute or so and each reopen mints
- * a fresh code, so a code is a thing with an age — the card says how old the one on screen is rather than
+ * a fresh code, so a code is a thing with an age, the card says how old the one on screen is rather than
  * leaving the owner to type a dead one twice. */
 export const ListenerPairingSchema = z.object({
     // waiting: a socket is up and the code hasn't arrived (or the last one died with its socket).
-    // code: `code` is live — type it on the phone. failed: `detail` says what WhatsApp refused.
+    // code: `code` is live, type it on the phone. failed: `detail` says what WhatsApp refused.
     state: z.enum(["waiting", "code", "failed"]),
     code: z.string().optional(),
     detail: z.string().optional(),
@@ -79,11 +79,11 @@ export const ListenerPairingSchema = z.object({
 export type ListenerPairing = z.infer<typeof ListenerPairingSchema>;
 
 // Push-based listener status: a gateway process POSTs its live connection/voice snapshot to
-// /listeners/<provider>/status, and the activity route reads it from there — the daemon holds no provider
+// /listeners/<provider>/status, and the activity route reads it from there, the daemon holds no provider
 // connection of its own to probe. The body IS the ActivityStatus the /activity/status probe used to build from
 // in-process discord singletons, plus the per-gateway extras that ride the same channel: whether whisper is
 // present (discord's voice-pending signal) and each unpaired capability's ceremony by id (whatsapp's
-// link-a-device flow — the capability card renders it as the step the owner is standing in front of).
+// link-a-device flow, the capability card renders it as the step the owner is standing in front of).
 export const ListenerStatusSchema = ActivityStatusSchema.extend({
     whisperReady: z.boolean().optional(),
     pairing: z.record(z.string(), ListenerPairingSchema).optional(),