@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/ids/hostnames.ts

@@ -0,0 +1,129 @@
+// The single source for tunnel/preview hostnames and scheme, shared by the CLI, platform API, daemon and browser; pure
+// string builders, no node imports, so the browser can derive identical names. All four must agree, or a divergence
+// resolves to a negative-cached NXDOMAIN.
+
+// The sandbox daemon's subdomain + hostname: `sandbox-<id>` / `sandbox-<id>.<zone>`.
+const SANDBOX_PREFIX = "sandbox-";
+export const sandboxSubdomain = (id: string): string => `${SANDBOX_PREFIX}${id}`;
+export const sandboxHostname = (id: string, zone: string): string => `${sandboxSubdomain(id)}.${zone}`;
+
+// The container sshd hostname the desktop-sync (Mutagen) reaches over the sandbox tunnel: `ssh-<id>.<zone>`.
+export const sshHostname = (id: string, zone: string): string => `ssh-${id}.${zone}`;
+
+// A public HTTPS name for 127.0.0.1, needed since Safari refuses http from an https page. One label deeper than other
+// names, so a single `*.local.<zone>` wildcard covers every sandbox rather than needing a record each.
+export const localHostname = (id: string, zone: string): string => `${id}.${LOCAL_LABEL}.${zone}`;
+
+// The label the loopback names live under, so the wildcard has something to be a wildcard OF.
+export const LOCAL_LABEL = "local";
+
+// The single record that answers for all of them. Never per-sandbox, never reaped.
+export const localWildcardHostname = (zone: string): string => `*.${LOCAL_LABEL}.${zone}`;
+
+// What that record points at, and the reason it is safe to publish: every resolver on earth gets 127.0.0.1.
+export const LOCAL_ADDRESS = "127.0.0.1";
+
+// A per-host SSH tunnel's Cloudflare tunnel name; its hostname reuses sshHostname with the host-ssh id.
+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.
+export const CATCH_ALL = { service: "http_status:404" } as const;
+
+// Three schemes share one shape, `<label>-<sandboxId>.<zone>`: preview, port-forward (`port-<slot>`, salted,
+// unguessable from the sandbox id alone), and outbox (`public-<slot>`, one record per sandbox).
+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. Nothing mints it: the edge parses the sandbox id back out of the name.
+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 advertise
+// nothing). One builder, three vocabularies.
+const labelUrl = (label: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
+    zone !== undefined && zone !== "" && sandboxId !== undefined ? `https://${labelHostname(label, sandboxId, zone)}` : undefined;
+export const previewUrl = (panel: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
+    labelUrl(previewLabel(panel), zone, sandboxId);
+export const portUrl = (slot: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
+    labelUrl(portLabel(slot), zone, sandboxId);
+export const publicUrl = (slot: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
+    labelUrl(publicLabel(slot), zone, sandboxId);
+
+// The key after `<prefix>` in the Host header; with an id, the label must end in the exact `-<sandboxId>` suffix so a
+// key containing `-` stays unambiguous. Without one, the bare label is the key.
+const keyFromHost = (prefix: string, hostHeader: string | undefined, sandboxId: string | undefined): string | undefined => {
+    const label = hostHeader?.split(":")[0]?.split(".")[0] ?? "";
+    if (!label.startsWith(prefix)) {
+        return undefined;
+    }
+    const key = label.slice(prefix.length);
+    if (sandboxId === undefined) {
+        return key === "" ? undefined : key;
+    }
+    const suffix = `-${sandboxId}`;
+    return key.length > suffix.length && key.endsWith(suffix) ? key.slice(0, -suffix.length) : undefined;
+};
+
+export const panelFromHost = (hostHeader: string | undefined, sandboxId: string | undefined): string | undefined =>
+    keyFromHost("preview-", hostHeader, sandboxId);
+export const portSlotFromHost = (hostHeader: string | undefined, sandboxId: string | undefined): string | undefined =>
+    keyFromHost("port-", hostHeader, sandboxId);
+export const publicSlotFromHost = (hostHeader: string | undefined, sandboxId: string | undefined): string | undefined =>
+    keyFromHost("public-", hostHeader, sandboxId);
+
+// The sandbox's identity as the user sees it: the URL's leading DNS label minus the `sandbox-` prefix. On the
+// own-Cloudflare path the label is whatever subdomain the owner chose, so that is the id there.
+export const sandboxIdFromUrl = (url: string | undefined): string | undefined => {
+    if (url === undefined || url === "") {
+        return undefined;
+    }
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`;
+    let label: string;
+    try {
+        label = new URL(withScheme).hostname.split(".")[0] ?? "";
+    } catch {
+        return undefined;
+    }
+    if (label === "" || label === SANDBOX_PREFIX) {
+        return undefined;
+    }
+    return label.startsWith(SANDBOX_PREFIX) ? label.slice(SANDBOX_PREFIX.length) : label;
+};
+
+// Where desktop sync mirrors /work to: `~/intentic/<name>-<sandboxIdFromUrl>`. Keyed on the URL, not the name alone, so
+// a sandbox recreated under the same name gets a fresh folder instead of colliding with the old one's.
+export const syncFolder = (name: string, url: string | undefined): string => {
+    const slug =
+        name
+            .replace(/[^a-zA-Z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .toLowerCase() || "sandbox";
+    const id = sandboxIdFromUrl(url);
+    return `~/intentic/${slug}${id === undefined ? "" : `-${id}`}`;
+};
+
+// The zone from a sandbox's public URL: the hostname minus its first DNS label. Undefined when unparsable or under
+// three labels, so a two-label host doesn't yield a bare TLD; accepts scheme-less input too.
+export const zoneFromUrl = (url: string | undefined): string | undefined => {
+    if (url === undefined || url === "") {
+        return undefined;
+    }
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`;
+    let hostname: string;
+    try {
+        hostname = new URL(withScheme).hostname;
+    } catch {
+        return undefined;
+    }
+    const labels = hostname.split(".");
+    if (labels.length < 3) {
+        return undefined;
+    }
+    return labels.slice(1).join(".");
+};

package/src/ids/session-names.ts

@@ -0,0 +1,29 @@
+// Names of the sessions one turn opens: a tmux session for Bash, a CDP-watched Chromium for browsing, both derived from
+// the SDK session id and listed together by GET /system/terminals. Three parties derive this name (daemon, web app, an
+// extension) and none may guess, so the derivation lives here, not copied.
+
+export const WEB_SESSION_PREFIX = "web-";
+export const AGENT_SESSION_PREFIX = "agent-";
+export const JOB_SESSION_PREFIX = "job-";
+export const BROWSER_SESSION_PREFIX = "browser-";
+
+// Eight characters of the SDK session UUID, sanitized to the name-guard charset; groups a turn's work, including its
+// subagents', under one name. Undefined when it sanitizes to empty.
+export const sessionSuffix = (sessionId: string): string | undefined => {
+    const id = sessionId.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 8);
+    return id === "" ? undefined : id;
+};
+
+// The tmux session one SDK session's Bash commands run in, the same derivation the Bash hook routes commands through,
+// so an emitted `terminal` frame and the live session can't drift.
+export const agentSessionName = (sessionId: string): string | undefined => {
+    const suffix = sessionSuffix(sessionId);
+    return suffix === undefined ? undefined : `${AGENT_SESSION_PREFIX}${suffix}`;
+};
+
+// The browser session one SDK session drives. Shares the suffix with agentSessionName on purpose: a conversation's
+// shell and its browser read as the pair they are.
+export const browserSessionName = (sessionId: string): string | undefined => {
+    const suffix = sessionSuffix(sessionId);
+    return suffix === undefined ? undefined : `${BROWSER_SESSION_PREFIX}${suffix}`;
+};

package/src/ids/share-paths.ts

@@ -0,0 +1,43 @@
+// Where a shared conversation lives inside the outbox; the viewer's build, the daemon and the outbox's dot-file rule
+// all agree on it.
+// public/conversations/_viewer/ - the page's built assets, shared by every share
+// public/conversations/<id>/ - index.html plus a files/ directory for its pictures
+// A directory per share, not a bare file, so removing one removes all of it, pictures included.
+
+// Top-level folder inside `public/`; reads as itself in the address bar, a string people paste to each other.
+export const SHARE_DIR = "conversations";
+
+// The one copy of the page's assets; underscored to sort away from shares, reading as machinery.
+export const SHARE_VIEWER_DIR = "_viewer";
+
+// Where a share's pictures sit relative to its own page; also the prefix every rewritten image path carries.
+export const SHARE_FILES_DIR = "files";
+
+// The absolute path the built assets are served from, and the `base` the page is built with.
+export const SHARE_VIEWER_BASE = `/${SHARE_DIR}/${SHARE_VIEWER_DIR}/`;
+
+// The id a share is filed under: a readable stem from the title, plus a random tail that is the only thing standing
+// between a stranger and the conversation. The stem must never be relied on for that: it's guessable by construction.
+const STEM_MAX = 48;
+
+export const shareStem = (title: string): string => {
+    const stem = title
+        .toLowerCase()
+        .normalize("NFKD")
+        // Anything not a plain letter or digit becomes a separator, dropping accents, punctuation, emoji.
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, STEM_MAX)
+        .replace(/-+$/, "");
+    // A title with nothing left after stripping (CJK, emoji) leaves an empty stem; the id is the random half alone.
+    return stem;
+};
+
+// `<stem>-<random>`, or the random half alone when the title had no letters to give.
+export const shareId = (title: string, random: string): string => {
+    const stem = shareStem(title);
+    return stem === "" ? random : `${stem}-${random}`;
+};
+
+// The shape a share id must have before joining it onto a path, same as transcript-record.ts's FILE_ID.
+export const SHARE_ID = /^[a-z0-9][a-z0-9-]{0,95}$/;

package/src/{tunnel-ids.test.ts → ids/tunnel-ids.test.ts}

@@ -18,34 +18,21 @@ test("a host ssh id is salted per host, so two deploy targets never collide", ()
 
 test("port slots are a fixed-size pool of DNS-safe labels, stable per token", () => {
     const slots = portSlotsFromToken(TOKEN);
-    // Fixed size: the pool is the cap on preview DNS records a sandbox costs the shared zone.
     expect(slots).toHaveLength(PORT_SLOT_COUNT);
-    // Every label must survive as one DNS label AND pass the platform's mint filter
-    // (/^(preview|port)-[a-z0-9][a-z0-9-]*$/, ≤50 chars), which `port-<slot>` has to satisfy.
     for (const slot of slots) {
         expect(slot).toMatch(/^[0-9a-f]{12}$/);
         expect(`port-${slot}`).toMatch(/^port-[a-z0-9][a-z0-9-]*$/);
         expect(`port-${slot}`.length).toBeLessThanOrEqual(50);
     }
-    // Distinct, or two forwards would fight over one hostname.
     expect(new Set(slots).size).toBe(PORT_SLOT_COUNT);
-    // Stable: the daemon and the platform derive these independently and must agree, and a restart has to
-    // land on the records already minted rather than orphaning them.
     expect(portSlotsFromToken(TOKEN)).toEqual(slots);
 });
 
-/* The whole point of the salt. The sandbox id is public: it is the leading label of the sandbox's own URL and
- * of every preview link its owner has shared, so anything derived from the id ALONE is derivable by whoever
- * holds one of those links. Slots must not be: knowing a sandbox's id must not tell you where its forwarded
- * ports live. */
 test("slots are not derivable from the sandbox id: only from the token behind it", () => {
     expect(portSlotsFromToken(OTHER)).not.toEqual(portSlotsFromToken(TOKEN));
-    // No slot leaks the id it will be paired with in `port-<slot>-<sandboxId>`.
     const id = sandboxIdFromToken(TOKEN);
-    // Load-bearing, and not merely tidy: `not.toContain(undefined)` is true of every slot list ever produced,
-    // so without a real id the leak check below would pass on a function that had stopped deriving one at all.
+    // Guards a false pass: `not.toContain(undefined)` holds for any slot list, even from a broken id function.
     expect(id).toEqual(expect.any(String));
     expect(portSlotsFromToken(TOKEN)).not.toContain(id);
-    // And none of them is the old fixed alphabet, which is what made the hostnames guessable.
     expect(portSlotsFromToken(TOKEN).some((slot) => slot.length === 1)).toBe(false);
 });

package/src/ids/tunnel-ids.ts

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+
+// The one sha256-hex digest every stable content/token identity derives from (tunnel ids, token lookups, bridge-token
+// hashes, hashline anchors). node:crypto makes this subpath node-only.
+export const sha256Hex = (value: string): string => createHash("sha256").update(value).digest("hex");
+
+// Twelve lowercase hex characters, a gate applied before trusting an id off the wire (a hostname, a ticket).
+export const SANDBOX_ID = /^[0-9a-f]{12}$/;
+
+// The sandbox's stable 12-hex id, digested from the connect token; every public hostname embeds it, and the platform's
+// grant mint, tunnelId lookup and the desktop agent's loopback dial all must derive the identical value.
+export const sandboxIdFromToken = (connectToken: string): string | undefined =>
+    connectToken === "" ? undefined : sha256Hex(connectToken).slice(0, 12);
+
+// A per-host SSH tunnel's stable 12-hex id, salted with the host name so each enrolled deploy target gets its own
+// ssh-<id>.<zone>. Shared by the CLI and the platform API, which must derive the identical id.
+export const hostSshIdFromToken = (connectToken: string, hostName: string): string => sha256Hex(`${connectToken}:${hostName}`).slice(0, 12);
+
+// Eight is enough for a monorepo's dev servers, and the hard cap on preview DNS records one sandbox can cost.
+export const PORT_SLOT_COUNT = 8;
+
+// Salted with the connect token, so a port's hostname isn't a pure function of the public sandbox id; any party holding
+// the token derives it with no coordination. The browser never does: it reads `previewUrl` off the daemon.
+export const portSlotsFromToken = (connectToken: string): readonly string[] =>
+    Array.from({ length: PORT_SLOT_COUNT }, (_, index) => sha256Hex(`${connectToken}:port:${index}`).slice(0, 12));
+
+// Salted like the port slots, and matters more here: a published file sits there indefinitely. With no directory
+// listing, reaching anything needs guessing both this label and a filename.
+export const publicSlotFromToken = (connectToken: string): string => sha256Hex(`${connectToken}:public`).slice(0, 12);

package/src/index.ts

@@ -1,5 +1,5 @@
-import type { ContractRoute } from "./routes.js";
-import { contractRoutes, requestPathFor, routeForProcedure, routeNameForRequest, routeShapes } from "./routes.js";
+import type { ContractRoute } from "./protocol/routes.js";
+import { contractRoutes, requestPathFor, routeForProcedure, routeNameForRequest, routeShapes } from "./protocol/routes.js";
 import { accountsContract } from "./contracts/accounts.contract.js";
 import { activityContract } from "./contracts/activity.contract.js";
 import { agentContract } from "./contracts/agent.contract.js";
@@ -54,19 +54,17 @@ export { extensionsContract } from "./contracts/extensions.contract.js";
 export { personasContract } from "./contracts/personas.contract.js";
 export { gitContract } from "./contracts/git.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 device's WebSocket, with the MACHINE implementing it. */
+// Not part of `sandboxContract` below: spoken over a device's WebSocket, with the machine implementing it.
 export { hostContract } from "./contracts/host.contract.js";
-// The same inversion again, one layer in: spoken over the socket a BROWSER EXTENSION opened, with the
-// extension implementing it (contracts/webext.contract.ts).
+// Same inversion, spoken over a browser extension's socket, with the extension implementing it.
 export { webextContract } from "./contracts/webext.contract.js";
-// Same inversion, other direction of trust: spoken over a RUNNER's WebSocket, with the runner implementing it.
+// Same inversion again: spoken over a runner's WebSocket, with the runner implementing it.
 export { runnerContract } from "./contracts/runner.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
 export { issuesContract } from "./contracts/issues.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
-export { REQUEST_ID_EVIDENCE_ROUTE, REQUEST_ID_HEADER } from "./request-id.js";
+export { REQUEST_ID_EVIDENCE_ROUTE, REQUEST_ID_HEADER } from "./protocol/request-id.js";
 export { loopsContract } from "./contracts/loops.contract.js";
 export { panelsContract } from "./contracts/panels.contract.js";
 export { portsContract } from "./contracts/ports.contract.js";
@@ -86,64 +84,54 @@ export { usageContract } from "./contracts/usage.contract.js";
 export { vpnContract } from "./contracts/vpn.contract.js";
 export { workflowsContract } from "./contracts/workflows.contract.js";
 export { workspaceContract } from "./contracts/workspace.contract.js";
-export * from "./events.js";
-export * from "./card-status.js";
-export * from "./mentions.js";
-export * from "./sse.js";
-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
- * 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. */
+export * from "./events/agent-events.js";
+export * from "./events/cards.js";
+export * from "./events/resume.js";
+export * from "./events/system-events.js";
+export * from "./events/transcript.js";
+export * from "./policy/card-status.js";
+export * from "./text/mentions.js";
+export * from "./protocol/sse.js";
+export * from "./protocol/routes.js";
+export * from "./policy/control-scopes.js";
+// The container's directory layout, re-exported since extensions can't import @intentic/constants directly.
 export { HISTORY_ROOT, HOST_STATE_ROOT, STATE_DIR, WORKSPACE_ROOT } from "@intentic/constants";
-export * from "./workspace-state.js";
-export * from "./runtime-state.js";
-export * from "./state-portability.js";
-export * from "./history-state.js";
-/* THE PROVIDER VOCABULARY, bottom-up: what each agentic loop can do (agent-runtimes), the one row-per-provider
- * table built on those records (provider-specs), and the shapes each surface reads that table in
- * (agent-catalog). Exported as three modules rather than folded into one, because the arrow between them only
- * points one way and saying so here is what stops it curling back. */
-export * from "./agent-runtimes.js";
-export * from "./provider-specs.js";
-export * from "./agent-catalog.js";
-export * from "./capability-env.js";
-export * from "./command-classes.js";
-export * from "./command-run.js";
-export * from "./safety-policy.js";
-export * from "./credential-material.js";
-export * from "./capability-secrets.js";
-export * from "./conversation-ids.js";
-export * from "./documents.js";
-export * from "./fast-tier.js";
-export * from "./host-protocol.js";
-export * from "./webext-protocol.js";
-export * from "./webext-links.js";
-export * from "./runner-protocol.js";
-export * from "./listener-protocol.js";
-export * from "./hostnames.js";
-export * from "./overlay-lint.js";
-export * from "./model-order.js";
-export * from "./model-pins.js";
-export * from "./model-roles.js";
-export * from "./plan-pools.js";
-export * from "./path-refs.js";
-export * from "./prompt-complexity.js";
-export * from "./output-fields.js";
-export * from "./approvals-execution.js";
-/* The wire shapes, one module per subject area, mirroring `contracts/` above: every request and response the
- * daemon speaks is declared in exactly one of them. Inputs that carry a `{param}` in their route path (repo /
- * id / name) merge the path param into the same flat object, oRPC fills the path placeholder from the matching
- * key and routes the rest to the body (POST/PUT) or query (GET).
- *
- * `schemas/internal.ts` is deliberately absent: it holds the id and ref primitives these modules are written
- * in, which are vocabulary rather than shapes either side of the wire sends. */
+export * from "./state/workspace-state.js";
+export * from "./state/runtime-state.js";
+export * from "./state/state-portability.js";
+export * from "./state/history-state.js";
+// Provider vocabulary bottom-up: agent-runtimes, provider-specs, agent-catalog; three modules since the dependency
+// points one way.
+export * from "./models/agent-runtimes.js";
+export * from "./models/provider-specs.js";
+export * from "./models/agent-catalog.js";
+export * from "./policy/capability-env.js";
+export * from "./policy/command-classes.js";
+export * from "./policy/command-run.js";
+export * from "./policy/safety-policy.js";
+export * from "./policy/credential-material.js";
+export * from "./policy/capability-secrets.js";
+export * from "./ids/conversation-ids.js";
+export * from "./text/documents.js";
+export * from "./models/fast-tier.js";
+export * from "./protocol/host-protocol.js";
+export * from "./protocol/webext-protocol.js";
+export * from "./protocol/webext-links.js";
+export * from "./protocol/runner-protocol.js";
+export * from "./protocol/listener-protocol.js";
+export * from "./protocol/container-requirements.js";
+export * from "./ids/hostnames.js";
+export * from "./policy/overlay-lint.js";
+export * from "./models/model-order.js";
+export * from "./models/model-pins.js";
+export * from "./models/model-roles.js";
+export * from "./models/plan-pools.js";
+export * from "./text/path-refs.js";
+export * from "./models/prompt-complexity.js";
+export * from "./policy/output-fields.js";
+export * from "./policy/approvals-execution.js";
+// Wire shapes, one module per subject area, mirroring `contracts/`; a `{param}` in the route path merges into the same
+// flat object, split back into path/body/query. `schemas/internal.ts` is absent: it's vocabulary, not a wire shape.
 export * from "./schemas/activity.js";
 export * from "./schemas/agent.js";
 export * from "./schemas/agents.js";
@@ -153,7 +141,6 @@ export * from "./schemas/capabilities.js";
 export * from "./schemas/ci.js";
 export * from "./schemas/claude-gate.js";
 export * from "./schemas/codebase-health.js";
-export * from "./schemas/context.js";
 export * from "./schemas/devices.js";
 export * from "./schemas/engines.js";
 export * from "./schemas/environment.js";
@@ -194,18 +181,19 @@ export * from "./schemas/workspace-repos.js";
 export * from "./schemas/workspace-search.js";
 export * from "./schemas/workspace-setup.js";
 export * from "./schemas/workspace-tree.js";
-export * from "./arrival.js";
-export * from "./definition.js";
-export * from "./search-globs.js";
-export * from "./starter.js";
-export * from "./terminal-protocol.js";
-export * from "./title.js";
-export * from "./versions.js";
-export * from "./workflow-faults.js";
+export * from "./state/arrival.js";
+export * from "./state/definition.js";
+export * from "./policy/search-globs.js";
+export * from "./state/starter.js";
+export * from "./protocol/terminal-protocol.js";
+export * from "./text/title.js";
+export * from "./state/versions.js";
+export * from "./text/model-answer.js";
+export * from "./text/whisper.js";
+export * from "./text/workflow-faults.js";
 
-// 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.
+// The aggregated contract; implemented server-side by per-domain route factories, consumed by the browser's typed oRPC
+// client. Mounted at the sandbox root, alongside plain Hono routes like /health and /workspace/raw.
 export const sandboxContract = {
     accounts: accountsContract,
     activity: activityContract,
@@ -247,26 +235,21 @@ export const sandboxContract = {
     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
-// `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.
+// Every route in this build, and the names advertised on the hello frame; bound here, not in routes.ts, to avoid a
+// load-time cycle back through this file.
 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
- * 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. */
+// Each route's shape, for the failure names alone can't describe: a route both builds have, but whose payload only one
+// expects. Computed once at load, since it's too expensive to repeat per connection.
 export const SANDBOX_ROUTE_SHAPES: Readonly<Record<string, string>> = routeShapes(sandboxContract);
 
 // The contract route a concrete browser request belongs to, bound to this build's route table.
 export const sandboxRouteName = (method: string, pathWithQuery: string): string | undefined =>
     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
-// gate treats it as a refusal rather than assuming it is harmless.
+// The method and path a typed call is about to send, bound to this build's route table. Undefined for an undeclared
+// procedure; the host gate then refuses it rather than assuming it's harmless.
 export const sandboxRequestFor = (procedure: readonly string[], input: unknown): { method: string; path: string } | undefined => {
     const route = routeForProcedure(SANDBOX_ROUTES, procedure);
     return route === undefined ? undefined : { method: route.method, path: requestPathFor(route, input) };