@intentic/sandbox-contract 1.126.0 → 1.133.0

package/src/effects.ts

@@ -0,0 +1,138 @@
+import type { ConnectorContribution, ExtensionManifest } from "@intentic/extension-api";
+import type { CapabilityKind } from "./schemas.js";
+
+/* What adding a capability DOES to the sandbox, as data — the structured counterpart of the handlers' side
+ * effects (the sandbox's capabilities/handlers/*), rendered by the web as the "This will add to your sandbox"
+ * panel before an add and as per-instance effect strips after. Derived, not declared per card: config-dependent
+ * effects (a plugin's clone URL, the SQL card's engine-dependent client image) and connector/extension-declared
+ * ones (secret fields, image fragments, processes) are computed from the same contribution data the handlers
+ * consume, so there is no per-card effects list to drift. The streamed apply log stays the post-apply record;
+ * this is the pre-add disclosure. */
+
+export type CapabilityEffect =
+    // Writes .claude/skills/<name>/SKILL.md, auto-loaded by the agent next turn. `name` is the instance id for
+    // cli/browser (per-instance skills), the fixed shared skill for ssh/vpn; absent while the instance is unnamed.
+    | { readonly kind: "skill"; readonly name?: string | undefined }
+    // Stores a credential in the sandbox. "agent-env": injected into the agent's environment each turn, never
+    // written to a file (cli). "disk": a 0600 file or a denylisted manifest field (ssh key, vpn conf, git token).
+    | { readonly kind: "secret"; readonly exposure: "agent-env" | "disk" }
+    // Git-clones a repo into .intentic/plugins|extensions/<id>. `url` absent until the form field is filled.
+    | { readonly kind: "clone"; readonly url?: string | undefined }
+    // Bakes a Dockerfile fragment into the sandbox image overlay — needs a one-time owner rebuild.
+    | { readonly kind: "image" }
+    // The baked fragment carries a privileged runtime directive: "net-admin" (vpn NET_ADMIN + tun) or
+    // "privileged" (docker — the full --privileged run its dockerd needs).
+    | { readonly kind: "runtime"; readonly level: "net-admin" | "privileged" }
+    // Runs long-lived background processes in the sandbox (an extension's declared processes).
+    | { readonly kind: "process"; readonly names: readonly string[] }
+    // Registers an mcp__<id>__ server the agent connects to next turn.
+    | { readonly kind: "mcp" }
+    // Scaffolds workspace repositories. Empty while a name-derived repo is still unnamed.
+    | { readonly kind: "scaffold"; readonly repos: readonly string[] }
+    // Writes a managed deploy.config.ts entry; `provisions` = also runs the infra apply job now (service).
+    | { readonly kind: "deploy"; readonly provisions: boolean }
+    // Extension code runs inside the app with the owner's session — the owner-only trust decision.
+    | { readonly kind: "trusted-code" }
+    // Keeps a logged-in Chromium profile under .intentic/browser/<platform> that the agent drives.
+    | { readonly kind: "profile"; readonly platform: string };
+
+export interface CapabilityEffectInput {
+    readonly kind: CapabilityKind;
+    // The instance name — the skill name for cli/browser, the repo name for monorepo.
+    readonly id?: string | undefined;
+    // Live form values, or a CapabilitySummary's secret-stripped config echo (hasToken/hasSecret booleans).
+    readonly config: Record<string, string | number | boolean | undefined>;
+    // The cli provider's connector spec — the source of truth for its secret/fragment declarations.
+    readonly connector?: ConnectorContribution | undefined;
+    // An installed extension's manifest — resolves its process/image contributions (unknowable before install).
+    readonly manifest?: ExtensionManifest | undefined;
+}
+
+const filled = (value: string | number | boolean | undefined): boolean => typeof value === "string" && value.length > 0;
+// A token either typed into the form (`token`) or echoed as present on an installed instance (`hasToken`).
+const hasToken = (config: CapabilityEffectInput["config"]): boolean => filled(config["token"]) || config["hasToken"] === true;
+const cloneUrl = (config: CapabilityEffectInput["config"]): string | undefined => (filled(config["url"]) ? String(config["url"]) : undefined);
+
+export const capabilityEffects = (input: CapabilityEffectInput): readonly CapabilityEffect[] => {
+    switch (input.kind) {
+        case "devops":
+            return [{ kind: "scaffold", repos: ["intent", "desired-state"] }];
+        case "monorepo":
+            return [{ kind: "scaffold", repos: input.id === undefined || input.id.length === 0 ? [] : [input.id] }];
+        case "mcp": {
+            const effects: CapabilityEffect[] = [{ kind: "mcp" }];
+            if (hasToken(input.config)) {
+                effects.push({ kind: "secret", exposure: "disk" });
+            }
+            return effects;
+        }
+        case "service":
+            return [{ kind: "deploy", provisions: true }];
+        case "integration":
+            return [{ kind: "deploy", provisions: false }];
+        case "cli": {
+            // Without the connector spec (extensions query pending / sandbox unreachable) fall back to the
+            // echoed hasSecret — which the web also synthesizes from the card's own secret-marked fields, so
+            // the secret row never waits on /extensions. The image row does wait: a connector's fragment
+            // (postgres/mysql clients, discord's whisper) is spec data with no static counterpart on the card.
+            const effects: CapabilityEffect[] = [{ kind: "skill", name: input.id }];
+            const secret =
+                input.connector === undefined ? input.config["hasSecret"] === true : input.connector.fields.some((field) => field.secret === true);
+            if (secret) {
+                effects.push({ kind: "secret", exposure: "agent-env" });
+            }
+            if (input.connector?.fragment !== undefined) {
+                effects.push({ kind: "image" });
+            }
+            return effects;
+        }
+        case "plugin": {
+            const effects: CapabilityEffect[] = [{ kind: "clone", url: cloneUrl(input.config) }];
+            if (hasToken(input.config)) {
+                effects.push({ kind: "secret", exposure: "disk" });
+            }
+            return effects;
+        }
+        case "extension": {
+            const effects: CapabilityEffect[] = [{ kind: "trusted-code" }, { kind: "clone", url: cloneUrl(input.config) }];
+            if (hasToken(input.config)) {
+                effects.push({ kind: "secret", exposure: "disk" });
+            }
+            const contributes = input.manifest?.contributes;
+            if (contributes?.environment !== undefined) {
+                effects.push({ kind: "image" });
+            }
+            if (contributes?.processes !== undefined && contributes.processes.length > 0) {
+                effects.push({ kind: "process", names: contributes.processes.map((process) => process.name) });
+            }
+            return effects;
+        }
+        case "ssh":
+            return [
+                { kind: "secret", exposure: "disk" },
+                { kind: "skill", name: "ssh" },
+            ];
+        case "vpn":
+            return [{ kind: "secret", exposure: "disk" }, { kind: "skill", name: "vpn" }, { kind: "image" }, { kind: "runtime", level: "net-admin" }];
+        case "docker":
+            // The engine is baked into the base image — the "image" effect here is the overlay rebuild that
+            // applies the fragment's --privileged directive, not new tooling.
+            return [{ kind: "image" }, { kind: "runtime", level: "privileged" }, { kind: "process", names: ["dockerd"] }];
+        case "browser": {
+            const effects: CapabilityEffect[] = [{ kind: "skill", name: input.id }, { kind: "image" }];
+            const platform = input.config["platform"];
+            if (typeof platform === "string") {
+                effects.push({ kind: "profile", platform });
+            }
+            return effects;
+        }
+        case "agent": {
+            // The spawned ACP subprocess is the standing consequence; a pasted env block is a stored credential.
+            const effects: CapabilityEffect[] = [{ kind: "process", names: input.id === undefined || input.id.length === 0 ? [] : [input.id] }];
+            if (filled(input.config["env"]) || input.config["hasSecret"] === true) {
+                effects.push({ kind: "secret", exposure: "disk" });
+            }
+            return effects;
+        }
+    }
+};

package/src/events.ts

@@ -0,0 +1,277 @@
+import { z } from "zod";
+import { AgentSummarySchema } from "./schemas.js";
+
+// The wire shapes streamed from the daemon's event-iterator procedures. This is their canonical home: the
+// daemon yields them and the browser client consumes them from the same schema, so the two can't drift (they
+// used to be hand-duplicated across repos). Schemas, not bare types, because oRPC's `eventIterator(...)`
+// validates each frame against them.
+
+// One interactive question the agent asks via the `ask` tool (mirrors AskUserQuestion's input shape).
+export const AskOptionSchema = z.object({
+    label: z.string(),
+    description: z.string(),
+    preview: z.string().optional(),
+});
+export type AskOption = z.infer<typeof AskOptionSchema>;
+
+export const AskQuestionSchema = z.object({
+    question: z.string(),
+    header: z.string(),
+    multiSelect: z.boolean(),
+    options: z.array(AskOptionSchema),
+});
+export type AskQuestion = z.infer<typeof AskQuestionSchema>;
+
+// One provider-advertised slash command (an ACP agent's available_commands entry). `hint` is the argument
+// placeholder the popover shows after the name.
+export const AgentCommandSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    hint: z.string().optional(),
+});
+export type AgentCommand = z.infer<typeof AgentCommandSchema>;
+
+// One TodoWrite/Task checklist item, surfaced live so the UI shows the agent's plan-of-work (Claude Code style).
+export const TodoItemSchema = z.object({
+    content: z.string(),
+    status: z.enum(["pending", "in_progress", "completed"]),
+    activeForm: z.string().optional(),
+});
+export type TodoItem = z.infer<typeof TodoItemSchema>;
+
+// Claude subscription usage for a turn (the SDK's rate_limit_event): which window is active, how much of it is
+// spent, and when it resets. Emitted on the stream at no token cost; only Claude turns report it. Its own
+// schema so the browser can hold the latest snapshot as a plain value, separate from the `kind`-tagged frame.
+export const RateLimitInfoSchema = z.object({
+    status: z.enum(["allowed", "allowed_warning", "rejected"]),
+    resetsAt: z.number().optional(), // epoch seconds
+    rateLimitType: z.string().optional(), // 'five_hour' | 'seven_day' | 'seven_day_opus' | ...
+    utilization: z.number().optional(), // 0-100, how much of the window is used
+});
+export type RateLimitInfo = z.infer<typeof RateLimitInfoSchema>;
+
+// Context-window fill for a conversation: how many tokens the latest request sent vs the model's window, so
+// the UI can warn as the chat nears auto-compaction. Per-conversation, unlike the account-wide usage above.
+export const ContextUsageSchema = z.object({
+    tokens: z.number(), // full input of the latest request (input + cache read + cache creation)
+    contextWindow: z.number(), // the model's context window
+});
+export type ContextUsage = z.infer<typeof ContextUsageSchema>;
+
+// ACP-aligned tool taxonomy (Agent Client Protocol's ToolKind, verbatim): what a tool call *does*, driving
+// the card icon and follow-along behavior regardless of which backend named the tool.
+export const ToolKindSchema = z.enum(["read", "edit", "delete", "move", "search", "execute", "think", "fetch", "other"]);
+export type ToolKind = z.infer<typeof ToolKindSchema>;
+
+export const ToolCallStatusSchema = z.enum(["pending", "in_progress", "completed", "failed"]);
+export type ToolCallStatus = z.infer<typeof ToolCallStatusSchema>;
+
+// A file a tool call touches. Workspace-root-relative, forward-slash (the tree/file route space) — adapters
+// normalize from the turn's cwd. `line` is 1-based.
+export const ToolCallLocationSchema = z.object({
+    path: z.string(),
+    line: z.number().optional(),
+});
+export type ToolCallLocation = z.infer<typeof ToolCallLocationSchema>;
+
+// Structured tool output (ACP's ToolCallContent diff shape, verbatim). `diff` is hunk-level for Edit-style
+// tools (old_string/new_string) and whole-file for Write; an absent oldText means a new file / unknown
+// previous content. Sides are capped daemon-side; `truncated` marks a clipped side.
+export const ToolCallContentSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("text"), text: z.string() }),
+    z.object({
+        type: z.literal("diff"),
+        path: z.string(),
+        oldText: z.string().optional(),
+        newText: z.string(),
+        truncated: z.boolean().optional(),
+    }),
+]);
+export type ToolCallContent = z.infer<typeof ToolCallContentSchema>;
+
+// One frame from an agent turn, relayed to the UI. `kind`-discriminated. The daemon normalizes the SDK's
+// ~40 SDKMessage types down to this union: high-value block types get a dedicated frame
+// (delta/thinking/tool_call/tool_call_update/todos/usage/rate_limit_info/context_usage/init/compact); any SDK message
+// without a UI mapping is dropped. `plan`/`question` pause the turn until the user answers on a side channel.
+// `parentToolUseId` tags frames produced inside a subagent (Task tool).
+export const AgentEventSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("session"), sessionId: z.string() }),
+    // First frame of an isolated turn: the conversation's worktree identity — its branch (agent/<id>) and the
+    // ROOT repo's short base sha (the checkout moment). Emitted before any provider frames.
+    z.object({ kind: z.literal("worktree"), branch: z.string(), base: z.string() }),
+    // Emitted after a clean isolated turn whose delta auto-landed (or failed to): landed ⇒ the work is now
+    // UNCOMMITTED changes in the main tree (the Changes panel is the review); conflicts ⇒ it stayed safely in
+    // the worktree — the named paths collide with the user's own edits, "Land now" recovers after they resolve.
+    z.object({
+        kind: z.literal("landed"),
+        landed: z.boolean(),
+        conflicts: z.array(z.object({ repo: z.string(), paths: z.array(z.string()) })).optional(),
+    }),
+    // The SDK's init handshake; carries the model it actually resolved for the turn.
+    z.object({ kind: z.literal("init"), model: z.string() }),
+    // The pre-turn workspace snapshot's id (the attribution-fence "user" capture), emitted once before the
+    // provider stream so the client can offer "restore to before this message" on the turn's user bubble.
+    // Absent on isolated turns (they snapshot nothing) and when the tree was already clean at turn start.
+    z.object({ kind: z.literal("checkpoint"), id: z.string() }),
+    z.object({ kind: z.literal("delta"), text: z.string(), parentToolUseId: z.string().optional() }),
+    z.object({ kind: z.literal("thinking"), text: z.string(), parentToolUseId: z.string().optional() }),
+    // A tool call starting (or, for backends that only report completions, arriving whole). `content` carries
+    // structured output known at call time — an Edit's diff is derived from its input, no result needed.
+    z.object({
+        kind: z.literal("tool_call"),
+        id: z.string(),
+        name: z.string(),
+        category: ToolKindSchema,
+        status: ToolCallStatusSchema,
+        target: z.string().optional(),
+        locations: z.array(ToolCallLocationSchema).optional(),
+        content: z.array(ToolCallContentSchema).optional(),
+        parentToolUseId: z.string().optional(),
+    }),
+    // A later state of a tool call, correlated by `id`. N updates per call: status transitions and/or fresh
+    // content/locations — both REPLACE the prior value (snapshot semantics, not append); absent ⇒ unchanged.
+    z.object({
+        kind: z.literal("tool_call_update"),
+        id: z.string(),
+        status: ToolCallStatusSchema.optional(),
+        content: z.array(ToolCallContentSchema).optional(),
+        locations: z.array(ToolCallLocationSchema).optional(),
+    }),
+    // The agent just started running Bash in its live `agent-<id>` tmux session — the client surfaces that
+    // terminal in the global panel. One per turn (the session is reused across a turn's commands, incl. subagents').
+    z.object({ kind: z.literal("terminal"), session: z.string() }),
+    z.object({ kind: z.literal("todos"), items: z.array(TodoItemSchema) }),
+    // The provider's own slash commands (ACP available_commands_update), replaced whole each time — the
+    // composer's `/` popover lists them; invoking one is plain `/name …` prompt text (the ACP convention).
+    z.object({ kind: z.literal("commands"), items: z.array(AgentCommandSchema) }),
+    z.object({
+        kind: z.literal("usage"),
+        // The account that served this turn — the client attributes the totals to it (tagged by streamAgent).
+        account: z.string().optional(),
+        costUsd: z.number().optional(),
+        inputTokens: z.number().optional(),
+        outputTokens: z.number().optional(),
+        // Provider prompt-cache buckets for the turn: tokens served from cache (read) and written to cache
+        // (creation). Optional per provider — Codex reports only cached input (read); runtimes/turns that
+        // don't report a bucket omit it. Lets the client show cache hit rate = read / (read + input).
+        cacheReadTokens: z.number().optional(),
+        cacheCreationTokens: z.number().optional(),
+        durationMs: z.number().optional(),
+        numTurns: z.number().optional(),
+    }),
+    // account tags which Claude account the snapshot belongs to, so the client keys usageStatus by account.
+    RateLimitInfoSchema.extend({ kind: z.literal("rate_limit_info"), account: z.string().optional() }),
+    ContextUsageSchema.extend({ kind: z.literal("context_usage") }),
+    z.object({ kind: z.literal("compact"), trigger: z.string(), preTokens: z.number().optional(), postTokens: z.number().optional() }),
+    z.object({ kind: z.literal("plan"), decisionId: z.string(), text: z.string() }),
+    z.object({ kind: z.literal("question"), requestId: z.string(), questions: z.array(AskQuestionSchema) }),
+    // `code` is a machine-readable discriminator for errors the UI reacts to programmatically (dropping a
+    // dead session id so the next send self-heals). Absent on plain failures.
+    z.object({
+        kind: z.literal("error"),
+        message: z.string(),
+        code: z
+            .enum([
+                "session-not-found",
+                "rate_limit",
+                "codex-reauth",
+                "grok-model-invalid",
+                "codex-model-invalid",
+                "subscription-required",
+                "agent-busy",
+            ])
+            .optional(),
+    }),
+    z.object({ kind: z.literal("done") }),
+]);
+export type AgentEvent = z.infer<typeof AgentEventSchema>;
+
+// The /agent/attach stream: a head frame identifying the run, then its AgentEvents stamped with their 1-based
+// seq (the client's resume cursor), then `end` when the run is over — every frame delivered, nothing more
+// coming. A stream that closes WITHOUT `end` was dropped mid-run; the client re-attaches with `after` = the
+// last seq it holds. The head's `prompt`/`startedAt` let a window that didn't initiate the turn (a reload, a
+// second window, another device) synthesize the user bubble and the elapsed readout; its `seq` is the log
+// length at attach time — the replay/live boundary.
+export const AttachFrameSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("attached"), run: z.string(), prompt: z.string(), startedAt: z.number(), seq: z.number() }),
+    z.object({ kind: z.literal("frame"), seq: z.number(), event: AgentEventSchema }),
+    z.object({ kind: z.literal("end") }),
+]);
+export type AttachFrame = z.infer<typeof AttachFrameSchema>;
+
+// One parsed line from `intentic … --output ndjson` (engine events, provider `log`, the terminal `result`).
+// Open-ended by design — the sandbox consumes the wire shape, not @intentic/engine's types — so a string
+// `kind` plus arbitrary extra fields pass through. The apply-events tail (intentic.contract `applyEvents`) rides
+// this same loose shape with three daemon/CLI-minted sentinel kinds alongside the engine ones: {kind:"start"}
+// (first line, written when the run's file is reset), {kind:"exit",code} (last line, on the CLI process exit),
+// and {kind:"heartbeat"} (interleaved by the tail while idle to keep the held-open stream alive).
+export const IntenticLineSchema = z.looseObject({ kind: z.string() });
+export type IntenticLine = z.infer<typeof IntenticLineSchema>;
+
+// The daemon's liveness heartbeat frame: the browser holds the events stream open and trips a watchdog if the
+// frames stop (the tunnel drops the proxied response when the origin dies).
+export const HeartbeatSchema = z.object({ kind: z.literal("heartbeat") });
+export type Heartbeat = z.infer<typeof HeartbeatSchema>;
+
+// The stream's first frame: the workspace's stable identity, minted at the first boot of an empty /work. The
+// browser remembers it per sandbox id and drops that sandbox's persisted query cache when it changes — a wiped
+// and recreated workspace (cleanup.sh + reconnect keeps the same sandbox id) must not be painted from the
+// previous workspace's cache.
+export const HelloSchema = z.object({ kind: z.literal("hello"), workspaceId: z.string() });
+export type Hello = z.infer<typeof HelloSchema>;
+
+// The FULL discovered repo set (sorted root-relative ids), pushed whenever it changes — a clone, a scaffold,
+// or a deleted repo re-frames it. The watcher descent-ignores .git, so no workspaceChanged path pattern can
+// detect a repo appearing; the daemon diffs its own discovery instead. Snapshot-not-diff, last frame wins.
+export const ReposChangedSchema = z.object({ kind: z.literal("reposChanged"), repos: z.array(z.string()) });
+export type ReposChanged = z.infer<typeof ReposChangedSchema>;
+
+// A batch of workspace paths that just changed on disk (created/edited/deleted), pushed on the same /events
+// stream as the heartbeat so the browser refreshes the tree + any open file live — the agent edits files
+// out-of-band (its own Write/Edit/Bash tools), so there's no HTTP mutation to hang an invalidate on. Paths are
+// root-relative, forward-slash (the tree/file route space). An empty array means "something changed, refetch the
+// tree" — a burst too large to enumerate, or a reconnect recovery where we don't know what was missed.
+export const WorkspaceChangedSchema = z.object({ kind: z.literal("workspaceChanged"), paths: z.array(z.string()) });
+export type WorkspaceChanged = z.infer<typeof WorkspaceChangedSchema>;
+
+// One connected browser tab of a sandbox member. Identity fields come from the caller's verified Google ID
+// token; activity fields from the tab's own /system/presence reports. No timestamps on the wire — an entry's
+// lifetime IS its /events connection's lifetime, so there is nothing to age out or compare clocks over.
+export const PresenceUserSchema = z.object({
+    // Per-CONNECTION id, minted by the browser for each /events attempt — never reused across reconnects.
+    clientId: z.string(),
+    email: z.string(),
+    name: z.string().optional(),
+    picture: z.string().optional(),
+    idle: z.boolean(),
+    // Route/view name the tab is on ("workspace", "automations", "ext:<id>/<key>", …).
+    view: z.string().optional(),
+    // The chat conversation the tab has active.
+    sessionId: z.string().optional(),
+    // The workspace file the tab has open (root-relative, forward-slash).
+    path: z.string().optional(),
+});
+export type PresenceUser = z.infer<typeof PresenceUserSchema>;
+
+// The FULL roster of connected members, broadcast on every change — snapshots, not diffs, so a reconnecting
+// browser is consistent from its first frame and ordering never matters (last frame wins).
+export const PresenceSchema = z.object({ kind: z.literal("presence"), users: z.array(PresenceUserSchema) });
+export type Presence = z.infer<typeof PresenceSchema>;
+
+// The FULL fleet roster, broadcast on every registry change — same snapshot-not-diff contract as presence:
+// a reconnecting browser is consistent from its first frame and last frame wins.
+export const AgentsSchema = z.object({ kind: z.literal("agents"), agents: z.array(AgentSummarySchema) });
+export type Agents = z.infer<typeof AgentsSchema>;
+
+// The /events stream union: the hello identity frame, then liveness heartbeats interleaved with
+// workspace-change batches, repo-set snapshots, and presence + fleet roster snapshots. oRPC validates every
+// yielded frame against this, so all kinds must live here.
+export const SystemEventSchema = z.discriminatedUnion("kind", [
+    HelloSchema,
+    HeartbeatSchema,
+    WorkspaceChangedSchema,
+    ReposChangedSchema,
+    PresenceSchema,
+    AgentsSchema,
+]);
+export type SystemEvent = z.infer<typeof SystemEventSchema>;

package/src/hostnames.test.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "vitest";
+import {
+    labelHostname,
+    panelFromHost,
+    portHostname,
+    portLabel,
+    portSlotFromHost,
+    portUrl,
+    previewHostname,
+    previewLabel,
+    previewUrl,
+} from "./hostnames.js";
+
+const ID = "abc123def456";
+
+test("preview and port hostnames round-trip through their Host-header parsers", () => {
+    expect(panelFromHost(`${previewHostname("shop--web", ID, "example.com")}:443`, ID)).toBe("shop--web");
+    expect(portSlotFromHost(`${portHostname("a", ID, "example.com")}:443`, ID)).toBe("a");
+    // The id-less form (loopback tests / provider-deployed workspaces fronting the proxy themselves).
+    expect(panelFromHost("preview-app.example.com", undefined)).toBe("app");
+    expect(portSlotFromHost("port-a.example.com", undefined)).toBe("a");
+});
+
+test("the two schemes never bleed into each other, and stray/wrong-id hosts parse to nothing", () => {
+    expect(portSlotFromHost("preview-app-" + ID + ".example.com", ID)).toBeUndefined();
+    expect(panelFromHost("port-a-" + ID + ".example.com", ID)).toBeUndefined();
+    expect(panelFromHost("app.example.com", ID)).toBeUndefined();
+    expect(panelFromHost(`preview-app-000000000000.example.com`, ID)).toBeUndefined();
+    expect(portSlotFromHost(`port-a-000000000000.example.com`, ID)).toBeUndefined();
+    expect(panelFromHost(undefined, ID)).toBeUndefined();
+});
+
+test("labels are the mintable unit: hostname = <label>-<id>.<zone> for both schemes", () => {
+    expect(labelHostname(previewLabel("app"), ID, "example.com")).toBe(previewHostname("app", ID, "example.com"));
+    expect(labelHostname(portLabel("a"), ID, "example.com")).toBe(portHostname("a", ID, "example.com"));
+});
+
+test("preview/port URLs require both a zone and a sandbox id", () => {
+    expect(previewUrl("app", "example.com", ID)).toBe(`https://preview-app-${ID}.example.com`);
+    expect(portUrl("a", "example.com", ID)).toBe(`https://port-a-${ID}.example.com`);
+    expect(portUrl("a", undefined, ID)).toBeUndefined();
+    expect(portUrl("a", "", ID)).toBeUndefined();
+    expect(portUrl("a", "example.com", undefined)).toBeUndefined();
+});

package/src/hostnames.ts

@@ -0,0 +1,97 @@
+// 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
+// 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
+// the zone's SOA TTL. This module is that agreement.
+
+// The sandbox daemon's subdomain + hostname: `sandbox-<id>` / `sandbox-<id>.<zone>`.
+export const sandboxSubdomain = (id: string): string => `sandbox-${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 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;
+
+// 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>
+// is one of the sandbox's fixed forward slots (see PORT_SLOTS), not the port number itself: slots keep the
+// intentic-provided path's minted routes bounded and warm while dev servers churn ephemeral ports.
+//
+// A *label* is the first-DNS-label prefix before `-<sandboxId>` (`preview-<panel>` / `port-<slot>`) — the unit
+// the platform's /sandbox/preview-route mints, so one endpoint serves both schemes.
+export const previewLabel = (panel: string): string => `preview-${panel}`;
+export const portLabel = (slot: string): string => `port-${slot}`;
+
+// The fixed per-sandbox forward slots. Eight is deliberate: enough for a monorepo's worth of concurrent dev
+// servers, and the hard cap on preview DNS records a sandbox can ever cost the shared intentic zone.
+export const PORT_SLOTS = ["a", "b", "c", "d", "e", "f", "g", "h"] as const;
+
+// 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);
+
+// A panel's / forwarded port's preview URL — undefined unless the sandbox has both a zone and an id
+// (headless/loopback sandboxes have neither and advertise no preview).
+export const previewUrl = (panel: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
+    zone !== undefined && zone !== "" && sandboxId !== undefined ? `https://${previewHostname(panel, sandboxId, zone)}` : undefined;
+export const portUrl = (slot: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
+    zone !== undefined && zone !== "" && sandboxId !== undefined ? `https://${portHostname(slot, sandboxId, zone)}` : undefined;
+
+// 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.
+// 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 => {
+    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);
+
+// 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
+// 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 => {
+    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/index.ts

@@ -0,0 +1,84 @@
+import { activityContract } from "./contracts/activity.contract.js";
+import { agentContract } from "./contracts/agent.contract.js";
+import { agentsContract } from "./contracts/agents.contract.js";
+import { automationsContract } from "./contracts/automations.contract.js";
+import { capabilitiesContract } from "./contracts/capabilities.contract.js";
+import { claudeContract } from "./contracts/claude.contract.js";
+import { codexContract } from "./contracts/codex.contract.js";
+import { draftsContract } from "./contracts/drafts.contract.js";
+import { extensionsContract } from "./contracts/extensions.contract.js";
+import { gitContract } from "./contracts/git.contract.js";
+import { grokContract } from "./contracts/grok.contract.js";
+import { historyContract } from "./contracts/history.contract.js";
+import { intenticContract } from "./contracts/intentic.contract.js";
+import { inventoryContract } from "./contracts/inventory.contract.js";
+import { logsContract } from "./contracts/logs.contract.js";
+import { panelsContract } from "./contracts/panels.contract.js";
+import { portsContract } from "./contracts/ports.contract.js";
+import { secretsContract } from "./contracts/secrets.contract.js";
+import { sessionsContract } from "./contracts/sessions.contract.js";
+import { settingsContract } from "./contracts/settings.contract.js";
+import { systemContract } from "./contracts/system.contract.js";
+import { translatorContract } from "./contracts/translator.contract.js";
+import { workspaceContract } from "./contracts/workspace.contract.js";
+
+export { activityContract } from "./contracts/activity.contract.js";
+export { agentContract } from "./contracts/agent.contract.js";
+export { agentsContract } from "./contracts/agents.contract.js";
+export { automationsContract } from "./contracts/automations.contract.js";
+export { capabilitiesContract } from "./contracts/capabilities.contract.js";
+export { claudeContract } from "./contracts/claude.contract.js";
+export { codexContract } from "./contracts/codex.contract.js";
+export { draftsContract } from "./contracts/drafts.contract.js";
+export { extensionsContract } from "./contracts/extensions.contract.js";
+export { gitContract } from "./contracts/git.contract.js";
+export { grokContract } from "./contracts/grok.contract.js";
+export { historyContract } from "./contracts/history.contract.js";
+export { intenticContract } from "./contracts/intentic.contract.js";
+export { inventoryContract } from "./contracts/inventory.contract.js";
+export { logsContract } from "./contracts/logs.contract.js";
+export { panelsContract } from "./contracts/panels.contract.js";
+export { portsContract } from "./contracts/ports.contract.js";
+export { secretsContract } from "./contracts/secrets.contract.js";
+export { sessionsContract } from "./contracts/sessions.contract.js";
+export { settingsContract } from "./contracts/settings.contract.js";
+export { systemContract } from "./contracts/system.contract.js";
+export { translatorContract } from "./contracts/translator.contract.js";
+export { workspaceContract } from "./contracts/workspace.contract.js";
+export * from "./effects.js";
+export * from "./events.js";
+export * from "./sse.js";
+export * from "./agent-catalog.js";
+export * from "./hostnames.js";
+export * from "./model-metadata.js";
+export * from "./schemas.js";
+export * from "./terminal-protocol.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.
+export const sandboxContract = {
+    activity: activityContract,
+    agent: agentContract,
+    agents: agentsContract,
+    automations: automationsContract,
+    capabilities: capabilitiesContract,
+    claude: claudeContract,
+    codex: codexContract,
+    drafts: draftsContract,
+    extensions: extensionsContract,
+    sessions: sessionsContract,
+    settings: settingsContract,
+    intentic: intenticContract,
+    git: gitContract,
+    grok: grokContract,
+    history: historyContract,
+    workspace: workspaceContract,
+    inventory: inventoryContract,
+    logs: logsContract,
+    panels: panelsContract,
+    ports: portsContract,
+    secrets: secretsContract,
+    system: systemContract,
+    translator: translatorContract,
+};