@intentic/sandbox-contract 1.325.0 → 1.327.0

package/src/policy/reserved-servers.ts

@@ -10,8 +10,8 @@ import { contributedServerMintingKinds } from "@intentic/extension-manifest";
 export type ServerProvenance = "control" | "outside";
 
 // Every server agent/run/agent.ts and agent/run/harness/harness-servers.ts mount themselves, plus the browser router's two
-// names (web, browser), which every turn mounts on its lease at the daemon's MCP door (browser-tools.ts) and which the
-// text scan reads from their constants. A server added anywhere else without a row here fails the conformance test in the sandbox guard package.
+// names (web, browser) and the virtual desktop's (desktop), which a turn mounts on its lease at the daemon's MCP door
+// (browser-tools.ts, desktop/desktop-tools.ts) and which the text scan reads from their constants. A server added anywhere else without a row here fails the conformance test in the sandbox guard package.
 export const DAEMON_MCP_SERVERS: Readonly<Record<string, ServerProvenance>> = {
     ui: "control", // agent.ts: AskUserQuestion
     accounts: "control", // agent.ts: the account roster and the credential typists
@@ -25,6 +25,7 @@ export const DAEMON_MCP_SERVERS: Readonly<Record<string, ServerProvenance>> = {
     diagnostics: "outside", // harness: two tools relay a provider's own sentence verbatim
     web: "outside", // the turn's mounts: the anonymous browser router; the page is the internet
     browser: "outside", // the turn's mounts: the signed-in browser router; the page is the internet
+    desktop: "outside", // the turn's mounts: the sandbox's own virtual desktop; whatever its windows show is outside content
 };
 
 // Every daemon-mounted server name, the set a capability id may not collide with.

package/src/policy/tests/credential-material.test.ts

@@ -1,4 +1,4 @@
-import { holdsCredentialMaterial, maskCredentialMaterial } from "../credential-material.js";
+import { holdsCredentialMaterial, holdsCredentialToken, maskCredentialMaterial } from "../credential-material.js";
 
 // The two directions aren't symmetric: a miss just raises an extra card, a wrong clear un-gates a real credential read.
 // The "no" cases have to be exactly right; every "yes" case is a real file's real shape.
@@ -159,3 +159,51 @@ describe("masking what a credential file holds", () => {
         }
     });
 });
+
+// A masked key keeps the lines that say what it was, and those lines alone must not read as a key: the public outbox
+// sniffs a share page this masker produced, and refusing it would leave the share unserved.
+describe("a private key once masked", () => {
+    const keys = [
+        "-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEAAAAA\n-----END OPENSSH PRIVATE KEY-----\n",
+        "-----BEGIN RSA PRIVATE KEY-----\nMIIEow",
+        '{"private_key":"-----BEGIN PRIVATE KEY-----\\nMIIEvQIBADANBg\\n-----END PRIVATE KEY-----\\n"}',
+        "-----BEGIN PGP PRIVATE KEY BLOCK-----\nVersion: GnuPG v2\n\nlQOYBF0x8bEBCAC5\n=Xy1Z\n-----END PGP PRIVATE KEY BLOCK-----",
+        "PuTTY-User-Key-File-3: ssh-ed25519\nEncryption: none\nPrivate-Lines: 1\nAAAAIGr3dHg0\nPrivate-MAC: ab12ab12\n",
+    ];
+
+    test.each(keys)("no longer holds one: %s", (key) => {
+        expect(holdsCredentialMaterial(key)).toBe(true);
+        expect(holdsCredentialMaterial(maskCredentialMaterial(key))).toBe(false);
+    });
+
+    test("a key cut short is masked through its last body line", () => {
+        expect(maskCredentialMaterial("-----BEGIN RSA PRIVATE KEY-----\nMIIEow\nAKCAQEA\nnext line of prose")).toBe(
+            "-----BEGIN RSA PRIVATE KEY-----\n***\nnext line of prose",
+        );
+        expect(maskCredentialMaterial('{"key":"-----BEGIN RSA PRIVATE KEY-----\\nMIIEow\\nAKCAQEA"}')).toBe(
+            '{"key":"-----BEGIN RSA PRIVATE KEY-----\n***"}',
+        );
+    });
+
+    test("a putty key keeps only its first line's label", () => {
+        expect(maskCredentialMaterial(keys[4] ?? "")).toBe("PuTTY-User-Key-File-3: ***\n");
+    });
+
+    test.each(keys)("masking twice changes nothing: %s", (key) => {
+        const once = maskCredentialMaterial(key);
+        expect(maskCredentialMaterial(once)).toBe(once);
+    });
+});
+
+// The self-identifying half the outbox sniffs published files with: a key=value guess is the gate's, not the outbox's.
+describe("a credential token in text that is not a credential file", () => {
+    test("is a shape that names itself", () => {
+        expect(holdsCredentialToken(`npm_${"a1B2".repeat(9)}`)).toBe(true);
+        expect(holdsCredentialToken("-----BEGIN PRIVATE KEY-----\nMIIEvQ")).toBe(true);
+    });
+
+    test("is never a credential-named key beside a value", () => {
+        expect(holdsCredentialToken("const config={apiKey:process.env.API_KEY,password:hunter22x}")).toBe(false);
+        expect(holdsCredentialMaterial("const config={apiKey:process.env.API_KEY,password:hunter22x}")).toBe(true);
+    });
+});

package/src/policy/tests/message-limits.test.ts

@@ -0,0 +1,27 @@
+import { awaitsOwner } from "../../schemas/automations.js";
+import { extensionGatewayUrlFile } from "../../state/workspace-state.js";
+import { MESSAGE_LIMITS, messageLimitOf } from "../message-limits.js";
+
+test("a platform's limit is found whatever case the post spelled it in", () => {
+    expect(messageLimitOf("Discord")).toBe(2_000);
+    expect(messageLimitOf("TELEGRAM")).toBe(4_096);
+    expect(messageLimitOf("whatsapp")).toBe(MESSAGE_LIMITS.whatsapp);
+    expect(MESSAGE_LIMITS.whatsapp).toBe(65_536);
+});
+
+test("an unknown platform has no limit, and neither does a name only an object prototype answers to", () => {
+    expect(messageLimitOf("myspace")).toBeUndefined();
+    // A plain record lookup answered these with Object.prototype's own members, a function where a number belongs.
+    expect(messageLimitOf("constructor")).toBeUndefined();
+    expect(messageLimitOf("toString")).toBeUndefined();
+});
+
+test("only a held wake with no countdown waits on the owner", () => {
+    expect(awaitsOwner({})).toBe(true);
+    expect(awaitsOwner({ autoRunAt: 1_700_000_000_000 })).toBe(false);
+});
+
+test("a gateway's control address lives beside the extensions' own directories, under its provider", () => {
+    expect(extensionGatewayUrlFile("whatsapp")).toBe(".intentic/local/runtime/gateways/whatsapp.url");
+    expect(extensionGatewayUrlFile("../x")).toBe(".intentic/local/runtime/gateways/.._x.url");
+});

package/src/policy/tests/reserved-servers.test.ts

@@ -24,10 +24,10 @@ describe("reserved MCP server names", () => {
 });
 
 describe("collidesWithReservedServer", () => {
-    // Derived from the manifest schema's meanings: a cli card mints a server when it serves tools, a device and a
-    // connected browser always do, and `mcp` is the core kind that is its own endpoint.
+    // Derived from the manifest schema's meanings: a cli card mints a server when it serves tools, a device, a
+    // connected browser and a connected phone always do, and `mcp` is the core kind that is its own endpoint.
     test("the minting kinds are exactly the ones whose id becomes a server name", () => {
-        expect([...MCP_SERVER_MINTING_KINDS].toSorted()).toEqual(["cli", "device", "mcp", "webext"]);
+        expect([...MCP_SERVER_MINTING_KINDS].toSorted()).toEqual(["cli", "device", "mcp", "phone", "webext"]);
     });
 
     test("a kind whose id becomes a server name may not reuse a reserved one", () => {

package/src/policy/turned-away.ts

@@ -11,8 +11,12 @@ const TURNED_AWAY: ReadonlySet<string> = new Set([
     "unknown-command",
     "context-window-too-small",
     "model-helper-only",
-    // The privacy shield refused an untrusted provider on a runtime it cannot stand in front of.
+    // The privacy shield refused an untrusted provider on a runtime it cannot read by content at all.
     "privacy-unshielded",
+    // The protected execution boundary refused admission, not an executed provider/runtime failure.
+    "agent-domain-refused",
+    // The privacy shield found personal data in instructions a runtime loads itself, where it could not mask them.
+    "privacy-instructions",
     "sandbox-memory-low",
     "trial-unavailable",
     "trial-model-unavailable",

package/src/protocol/container-requirements.ts

@@ -23,11 +23,10 @@ export const CONTAINER_REQUIREMENTS: readonly ContainerRequirement[] = [
         key: "reachability",
         requires: ["SANDBOX_GRANT", "INGRESS_URL"],
         given: ["SANDBOX_PUBLIC_URL"],
-        enables: "reaching this sandbox at its public address, from anywhere",
-        lost:
-            "Its public address answers 502 to everyone, including this browser when it is not on the same machine as the sandbox. " +
-            "On that machine the workspace still works, over a direct connection that never leaves it — which is why this can go unnoticed for a long time.",
-        repair: "Re-run this sandbox's setup command. It carries a freshly signed grant, and it keeps the workspace, its history and its Docker engine.",
+        // Kept to a sentence each: a client may show them as sent (the editor words this key itself, translated).
+        enables: "reaching it at its public address",
+        lost: "Its public address answers 502 everywhere except on the computer it runs on.",
+        repair: "Re-run its setup command. Files, history and Docker are kept.",
     },
 ];
 

package/src/protocol/{listener-protocol.ts → doors/listener-protocol.ts}

@@ -1,9 +1,35 @@
 import { z } from "zod";
-import { ActivityStatusSchema } from "../schemas/activity.js";
+import { ActivityStatusSchema } from "../../schemas/activity.js";
+import { rawRouteUrl } from "../raw/raw-routes.js";
 
 // Wire between the daemon and an extension's realtime-listener gateway (ext-discord, ext-slack, ext-telegram,
-// ext-whatsapp, ext-imap): the four /listeners/:provider routes (state, dispatch, failure, status). Shared here so both
-// ends compile against one declaration.
+// ext-whatsapp, ext-imap, ext-google-workspace): the four /listeners/:provider routes (state, dispatch, failure,
+// status). Shared here so both ends compile against one declaration.
+
+// The path of one of the four listener routes for a provider, built from RAW_ROUTES so the gateway and the daemon
+// cannot spell it two ways.
+export const listenerRouteUrl = (route: "state" | "dispatch" | "failure" | "status", provider: string): string =>
+    route === "state" ? rawRouteUrl("GET /listeners/{provider}/state", { provider }) : rawRouteUrl(`POST /listeners/{provider}/${route}`, { provider });
+
+// The reconcile feed GET /listeners/<provider>/state answers: the enabled automations listening to this provider and
+// the connectors the asking extension contributes, each with its whole config, secrets included, since the gateway
+// connects with them. The gateway reads only an automation's id and whether it is on; a connector's config is the
+// connector's own shape, which the connector reads itself.
+export const ListenerStateSchema = z.object({
+    automations: z.array(z.object({ id: z.string(), enabled: z.boolean() })),
+    connectors: z.array(z.object({ id: z.string(), config: z.record(z.string(), z.unknown()) })),
+});
+export type ListenerState = z.infer<typeof ListenerStateSchema>;
+
+// One prior message a gateway hands over with a mention, oldest first; `self` marks one of our own bots' posts, so the
+// model recognizes its earlier replies.
+export const ListenerHistoryEntrySchema = z.object({
+    author: z.object({ id: z.string(), name: z.string() }),
+    content: z.string(),
+    timestamp: z.string(),
+    self: z.boolean().optional(),
+});
+export type ListenerHistoryEntry = z.infer<typeof ListenerHistoryEntrySchema>;
 
 // One normalized inbound event: the JSON body a realtime source POSTs to /listeners/<provider>/dispatch. A zod schema
 // since it's parsed from untrusted gateway input; `provider` and `type` are open strings, not a core enum.
@@ -16,24 +42,20 @@ export const ListenerMessageSchema = z.object({
     // service's own group ids on this sender (Discord role ids), absent on a source without them.
     author: z.object({ id: z.string(), name: z.string(), groups: z.array(z.string()).optional() }),
     content: z.string(),
-    // Discord only: the message @mentions or replies to one of our bots; voice events never set it.
+    // The message is addressed to us, by each provider's own rule: an @mention of or reply to one of our bots, a direct
+    // message, a Slack thread we already answered in, or mail whose To line holds the connected address. Voice events
+    // never set it.
     mentioned: z.boolean().optional(),
     // CI pipeline event: the ref it ran on. Top-level, not in `extra`, since the dispatcher matches triggers on it.
     branch: z.string().optional(),
     // Prior channel messages fetched when tagged; top-level so it reaches the model but skips the activity feed.
-    history: z
-        .array(
-            z.object({
-                author: z.object({ id: z.string(), name: z.string() }),
-                content: z.string(),
-                timestamp: z.string(),
-                self: z.boolean().optional(),
-            }),
-        )
-        .optional(),
+    history: z.array(ListenerHistoryEntrySchema).optional(),
     timestamp: z.string(),
-    // Provider-specific fields:
+    // Provider-specific fields, for example:
     // - discord message: guildId, attachments
+    // - slack message: threadTs, teamId, attachments
+    // - telegram message: chatType, messageId, chatTitle, messageThreadId, attachments
+    // - whatsapp message: chatType, chatName, replyTo, attachments
     // - voice_utterance: path
     // - voice_transcript: path, participants, durationSeconds
     extra: z.record(z.string(), z.unknown()).optional(),

package/src/protocol/doors/phone-links.ts

@@ -0,0 +1,50 @@
+// Zod-free half of the phone door's wire: URL builders and the pairing code. Split from phone-protocol.ts so the
+// editor's pairing dialog does not pull zod in for two string functions. No imports allowed here, ever.
+
+const base = (sandboxUrl: string): string => sandboxUrl.replace(/\/$/, "");
+
+// URL the phone dials, from the sandbox's public URL; carries no credential, the token rides the hello frame.
+export const phoneConnectUrl = (sandboxUrl: string): string => `${base(sandboxUrl).replace(/^http/, "ws")}/system/phones/connect`;
+
+// Where the phone redeems its one-time pairing for its durable token (header `x-intentic-pair`).
+export const phoneEnrollUrl = (sandboxUrl: string): string => `${base(sandboxUrl)}/system/phones/enroll`;
+
+// One code rather than two fields, like the browser extension's: base64url of {url, token}, the prefix versioning the
+// format. `token` is single-use and expires in ten minutes.
+const PAIRING_PREFIX = "ixp1_";
+
+// Where a pairing opens: an App Link the app claims (intentic.dev serves its assetlinks.json), so scanning the code
+// with the phone's camera opens the app straight on the pairing screen, and a phone without the app lands on the page
+// that offers it. The code rides the fragment, which no server ever receives, so no access log holds a live pairing.
+export const PHONE_PAIR_LINK = "https://intentic.dev/phone/pair";
+
+const base64url = (value: string): string => btoa(value).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+
+export const phonePairingCode = (pairing: { readonly url: string; readonly token: string }): string =>
+    `${PAIRING_PREFIX}${base64url(JSON.stringify({ url: pairing.url, token: pairing.token }))}`;
+
+export const phonePairingLink = (pairing: { readonly url: string; readonly token: string }): string =>
+    `${PHONE_PAIR_LINK}#${phonePairingCode(pairing)}`;
+
+// The phone's side, and the editor's for a pasted code; undefined for anything not one of ours. Accepts the bare code
+// or the whole link, since a person may paste either.
+export const parsePhonePairingCode = (input: string): { readonly url: string; readonly token: string } | undefined => {
+    const trimmed = input.trim();
+    // The site serves the page with a trailing slash, so a link copied out of the browser may carry one.
+    const linked = [`${PHONE_PAIR_LINK}#`, `${PHONE_PAIR_LINK}/#`].find((prefix) => trimmed.startsWith(prefix));
+    const code = linked === undefined ? trimmed : trimmed.slice(linked.length);
+    if (!code.startsWith(PAIRING_PREFIX)) {
+        return undefined;
+    }
+    try {
+        const padded = code.slice(PAIRING_PREFIX.length).replaceAll("-", "+").replaceAll("_", "/");
+        const decoded = JSON.parse(atob(padded)) as { url?: unknown; token?: unknown };
+        if (typeof decoded.url !== "string" || typeof decoded.token !== "string" || decoded.token === "" || !/^https?:\/\//.test(decoded.url)) {
+            return undefined;
+        }
+        return { url: decoded.url, token: decoded.token };
+    } catch {
+        // allow(silent-catch): atob and JSON.parse only throw on a code that is not base64 or not JSON, which is no pairing code, the same as the checks above.
+        return undefined;
+    }
+};

package/src/protocol/doors/phone-protocol.test.ts

@@ -0,0 +1,136 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import { OkSchema } from "../../schemas/shared.js";
+import { PhoneFactsSchema, PhoneScopesSchema } from "../../schemas/phone.js";
+import { PHONE_ERROR, PhoneHelloSchema, PhoneRequestSchema, PhoneResponseSchema } from "./phone-protocol.js";
+import { parsePhonePairingCode, phoneConnectUrl, phoneEnrollUrl, phonePairingCode, phonePairingLink } from "./phone-links.js";
+
+// The phone door's wire as examples, spelled once here: golden/phone-wire.json is this file's `wire` as JSON, and both
+// far ends test against it — the daemon's JSON-RPC link (_sandbox/sandbox/src/phones/json-rpc-link.test.ts) sends
+// exactly each `request` for its `call` and resolves each `response` to `resolves`, and the Android app's tests
+// (_devices/android) parse every request and answer in the same shapes. A change here the committed file does not carry
+// fails, naming the file; `INTENTIC_WRITE_GOLDEN=1` rewrites it.
+
+const GOLDEN = join(packageRoot(import.meta.url), "golden", "phone-wire.json");
+
+const facts = PhoneFactsSchema.parse({
+    device: "Google Pixel 8",
+    android: "16",
+    sdk: 36,
+    build: "direct",
+    paused: false,
+    access: { accessibility: true, notifications: false, screenCapture: "accessibility" },
+    folders: [{ name: "Download", writable: true }],
+    apps: [{ package: "com.android.chrome", label: "Chrome", mode: "act" }],
+    battery: { level: 81, charging: false },
+    wake: { fcm: "fcm-token-example" },
+    features: ["touch", "notifications"],
+});
+
+const scopes = { ...PhoneScopesSchema.parse({}), platform: "android" };
+
+const toolsList = {
+    tools: [
+        {
+            name: "screenshot",
+            description: "What the phone's screen shows now, as an image with a frame id.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            annotations: { readOnlyHint: true },
+        },
+    ],
+};
+
+const callResult = { content: [{ type: "text", text: 'Tapped [e4] "Send".' }] };
+
+const wire = {
+    hello: PhoneHelloSchema.parse({ type: "hello", token: "iph_example-enrollment-token", version: "1.0.0" }),
+    exchanges: [
+        {
+            name: "describe",
+            call: { path: ["describe"] },
+            request: { jsonrpc: "2.0", id: 0, method: "describe" },
+            response: { jsonrpc: "2.0", id: 0, result: facts },
+            resolves: facts,
+        },
+        {
+            name: "setScopes",
+            call: { path: ["setScopes"], input: scopes },
+            request: { jsonrpc: "2.0", id: 1, method: "setScopes", params: scopes },
+            response: { jsonrpc: "2.0", id: 1, result: OkSchema.parse({ ok: true }) },
+            resolves: { ok: true },
+        },
+        {
+            name: "ping",
+            call: { path: ["ping"] },
+            request: { jsonrpc: "2.0", id: 2, method: "ping" },
+            response: { jsonrpc: "2.0", id: 2, result: { ok: true } },
+            resolves: { ok: true },
+        },
+        {
+            name: "mcp tools/list",
+            call: { path: ["mcp"], input: { jsonrpc: "2.0", id: "phones-tools", method: "tools/list", params: {} } },
+            request: { jsonrpc: "2.0", id: 3, method: "mcp", params: { jsonrpc: "2.0", id: "phones-tools", method: "tools/list", params: {} } },
+            response: { jsonrpc: "2.0", id: 3, result: { jsonrpc: "2.0", id: "phones-tools", result: toolsList } },
+            resolves: { jsonrpc: "2.0", id: "phones-tools", result: toolsList },
+        },
+        {
+            name: "mcp tools/call",
+            call: {
+                path: ["mcp"],
+                input: { jsonrpc: "2.0", id: 9, method: "tools/call", params: { name: "ui_act", arguments: { ref: "e4", action: "tap" } } },
+            },
+            request: {
+                jsonrpc: "2.0",
+                id: 4,
+                method: "mcp",
+                params: { jsonrpc: "2.0", id: 9, method: "tools/call", params: { name: "ui_act", arguments: { ref: "e4", action: "tap" } } },
+            },
+            response: { jsonrpc: "2.0", id: 4, result: { jsonrpc: "2.0", id: 9, result: callResult } },
+            resolves: { jsonrpc: "2.0", id: 9, result: callResult },
+        },
+        {
+            name: "refused",
+            call: { path: ["describe"] },
+            request: { jsonrpc: "2.0", id: 5, method: "describe" },
+            response: { jsonrpc: "2.0", id: 5, error: { code: PHONE_ERROR.refused, message: "The person paused the agent on this phone." } },
+            rejects: "The person paused the agent on this phone.",
+        },
+    ],
+};
+
+test("every example frame is one the protocol's schemas accept", () => {
+    for (const exchange of wire.exchanges) {
+        expect(PhoneRequestSchema.safeParse(exchange.request).success).toBe(true);
+        expect(PhoneResponseSchema.safeParse(exchange.response).success).toBe(true);
+        expect(exchange.request.id).toBe(exchange.response.id);
+    }
+});
+
+test("golden/phone-wire.json is the protocol's example, as the app reads it", () => {
+    const expected = `${JSON.stringify(wire, undefined, 2)}\n`;
+    if (process.env["INTENTIC_WRITE_GOLDEN"] === "1") {
+        writeFileSync(GOLDEN, expected);
+    }
+    expect(readFileSync(GOLDEN, "utf8")).toBe(expected);
+});
+
+test("a pairing round-trips as a code and as the link the QR carries", () => {
+    const pairing = { url: "https://sandbox-abc.sbx.intentic.dev", token: "one-time" };
+    expect(parsePhonePairingCode(phonePairingCode(pairing))).toEqual(pairing);
+    expect(parsePhonePairingCode(phonePairingLink(pairing))).toEqual(pairing);
+    expect(phonePairingLink(pairing).startsWith("https://intentic.dev/phone/pair#ixp1_")).toBe(true);
+    expect(parsePhonePairingCode(phonePairingLink(pairing).replace("/pair#", "/pair/#"))).toEqual(pairing);
+});
+
+test("a code that is not ours, or carries no usable url or token, is refused rather than attempted", () => {
+    expect(parsePhonePairingCode("ixb1_abc")).toBeUndefined();
+    expect(parsePhonePairingCode("ixp1_not-base64!")).toBeUndefined();
+    expect(parsePhonePairingCode(phonePairingCode({ url: "ftp://x", token: "t" }))).toBeUndefined();
+    expect(parsePhonePairingCode(phonePairingCode({ url: "https://x", token: "" }))).toBeUndefined();
+});
+
+test("the phone dials and enrolls at the sandbox's own address", () => {
+    expect(phoneConnectUrl("https://sandbox-abc.sbx.intentic.dev/")).toBe("wss://sandbox-abc.sbx.intentic.dev/system/phones/connect");
+    expect(phoneEnrollUrl("https://sandbox-abc.sbx.intentic.dev")).toBe("https://sandbox-abc.sbx.intentic.dev/system/phones/enroll");
+});

package/src/protocol/doors/phone-protocol.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+
+// The phone door's wire, /system/phones/connect. The first frame is the same hello every peer sends. After it, unlike
+// the machine and browser doors, the socket carries plain JSON-RPC 2.0 rather than oRPC's own framing: the far end is
+// a Kotlin app, and JSON-RPC is a format it can implement from its one-page spec, where oRPC's is an internal of a
+// TypeScript library. The daemon still drives it through the same typed client every door has (phones/json-rpc-link.ts
+// on the daemon side), so only the bytes differ. fixtures/phone-wire.json holds example exchanges both sides test
+// against.
+//
+// The daemon sends requests, the phone only answers:
+//   → {"jsonrpc":"2.0","id":7,"method":"describe"}
+//   ← {"jsonrpc":"2.0","id":7,"result":{...PhoneFacts}}
+// `method` is a procedure of phoneContract; `params` is its input, absent when it takes none. A failure is an `error`
+// with a code and a message the agent may read.
+
+/* HOW OFTEN THIS DOOR PINGS A CONNECTED PHONE, read by both sides of the socket. Longer than a computer's: every ping
+wakes the phone's radio, and the phone holds the socket only while it is working or set to stay connected. Carrier NATs
+drop an idle connection after a few minutes, so the ping still has to come well inside that. The app declares the link
+dead after three missed pings, as every peer does. */
+export const PHONE_HEARTBEAT_MS = 60_000;
+
+/* How long a call to a sleeping phone waits for it to wake and dial in, after the sandbox pushed it awake. Long enough
+for a push to arrive and a phone on mobile data to connect, short enough that a phone that will not come answers the
+agent with "asleep" while the turn can still do something else. */
+export const PHONE_WAKE_WAIT_MS = 20_000;
+
+/* How long an awake phone keeps its socket after its last call, unless the person set it to stay connected. Read by
+the app; the sandbox only learns of it as a socket that closed normally. */
+export const PHONE_LINGER_MS = 5 * 60_000;
+
+export const PhoneHelloSchema = z.object({
+    type: z.literal("hello"),
+    // Enrollment token, in the first frame and never the URL.
+    token: z.string(),
+    // The app's build, so an outdated one is visible rather than mysteriously missing a tool.
+    version: z.string(),
+});
+export type PhoneHello = z.infer<typeof PhoneHelloSchema>;
+
+// The procedures the daemon calls; each is a key of phoneContract.
+export const PHONE_METHODS = ["describe", "setScopes", "ping", "mcp"] as const;
+export type PhoneMethod = (typeof PHONE_METHODS)[number];
+
+export const PhoneRequestSchema = z.object({
+    jsonrpc: z.literal("2.0"),
+    id: z.number().int().nonnegative(),
+    method: z.enum(PHONE_METHODS),
+    params: z.unknown().optional(),
+});
+export type PhoneRequest = z.infer<typeof PhoneRequestSchema>;
+
+// JSON-RPC's own codes, plus the two the phone answers with for a refusal the agent should read as a refusal.
+export const PHONE_ERROR = {
+    parse: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internal: -32603,
+    // The person paused the app, or a switch is off.
+    refused: -32001,
+} as const;
+
+export const PhoneResponseSchema = z.union([
+    z.object({ jsonrpc: z.literal("2.0"), id: z.number().int().nonnegative(), result: z.unknown() }),
+    z.object({
+        jsonrpc: z.literal("2.0"),
+        id: z.number().int().nonnegative().nullable(),
+        error: z.object({ code: z.number().int(), message: z.string(), data: z.unknown().optional() }),
+    }),
+]);
+export type PhoneResponse = z.infer<typeof PhoneResponseSchema>;

package/src/protocol/{runner-protocol.ts → doors/runner-protocol.ts}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { NeedsActionSchema } from "../policy/needs-action.js";
+import { NeedsActionSchema } from "../../policy/needs-action.js";
 
 // The runner link's edges: the /system/runners/connect handshake, boot env, and turn placement (procedures live in
 // contracts/runner.contract.ts). A runner is a sandbox image in runner mode, no browser owner or tunnel, that dials its

package/src/protocol/{webext-links.ts → doors/webext-links.ts}

@@ -5,6 +5,10 @@
 // URL the extension dials, from the sandbox's public URL; carries no credential, the token rides the hello frame.
 export const webextConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/webext/connect`;
 
+// Where the extension redeems a pairing code's one-time token (sent as `x-intentic-pair`) for its durable token; the
+// answer is a PeerEnrollmentAnswer.
+export const webextEnrollUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/enroll`;
+
 // Where the extension POSTs a site's session when the owner connects it, bearer-authenticated. A separate door from the
 // socket, since the socket's answers land in the agent's context and cookies must never reach a model.
 export const webextSessionUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/session`;

package/src/protocol/edge-verdict.ts

@@ -3,7 +3,7 @@
 // JavaScript unless the responder allows it — so the verdict rides an exposed header and the edge CORS-allows its own
 // errors. Ingress writes it, the editor's connection machine reads it; both sides import this file so they cannot drift.
 
-import type { EdgeVerdict } from "../front/generated/browser-wire.js";
+import type { EdgeVerdict } from "../netd/generated/browser-wire.js";
 
 export const EDGE_VERDICT_HEADER = "x-intentic-edge";
 

package/src/protocol/headers.ts

@@ -0,0 +1,14 @@
+// The header names the daemon, the platform, `ic` and extensions agree on, each spelled once.
+
+// Correlates a browser call to the daemon request that served it; a token only, never a security boundary.
+export const REQUEST_ID_HEADER = "x-intentic-request-id";
+
+// The header a sandbox's connect token travels in: the platform's routes a sandbox calls as itself
+// (api-contract's PLATFORM_INGRESS), the daemon's own gate, which takes the token from `ic` and the owner's browser,
+// and its `/enroll`. `ic` spells it in Rust; api-contract's ingress test holds that spelling to this value.
+export const CONNECT_TOKEN_HEADER = "x-intentic-connect";
+
+// The header an extension's backend and its processes present their per-extension token in, checked against the
+// manifest's `permissions.daemon` (the daemon's auth/grants.ts). Declared here so the daemon's grant, the backend host
+// that proxies to it and the connector runtime's daemon client spell it once.
+export const EXTENSION_TOKEN_HEADER = "x-intentic-extension";

package/src/protocol/ingress-contract.ts

@@ -53,18 +53,14 @@ export const verifyReachabilityGrant = (publicKeyPem: string, token: string): Re
 
 // Host to owner routing
 
-// Resolves which sandbox owns a Host: the leftmost DNS label is `sandbox-<id>` or ends in `-<id>` (12-hex); anything
-// else, including the loopback `<id>.local.<zone>` label, returns undefined.
-export const hostOwnerId = (host: string): string | undefined => {
-    const label = host.split(":")[0]?.split(".")[0] ?? "";
-    const match = /-([0-9a-f]{12})$/.exec(label);
-    return match === null ? undefined : match[1];
-};
+// Which sandbox owns a Host, declared with the names it parses (ids/hostnames.ts) and re-exported for this subpath's
+// callers: the leftmost DNS label is `sandbox-<id>` or ends in `-<id>` (12-hex).
+export { hostOwnerId } from "../ids/hostnames.js";
 
 // Wire constants
 
 // Tunnel door on the ingress (the tunnel crate's TUNNEL_PATH); versioned, so a new session shape adds a path. `/tunnel/v1`
-// is the edge's alone to answer now, for fronts that predate this one.
+// is the edge's alone to answer now, for netd versions that predate this one.
 export const INGRESS_TUNNEL_PATH = "/tunnel/v2";
 
 // Grant travels as a header on the tunnel upgrade; this connection is never a browser's.
@@ -79,9 +75,9 @@ export const ENV_SANDBOX_GRANT = "SANDBOX_GRANT";
 //   and cache the answer, failing open if the platform doesn't respond. A 404 refuses the tunnel.
 // - Displacement: a new tunnel for an id closes the old session (code 4001) and takes the registration.
 // - Streams: every exchange is a stream of its own carrying HTTP/1.1 (yamux over a WebSocket, or QUIC). Over TCP a
-//   transfer rides the bulk socket: a preview's request, or a route the front announced (tunnel-bulk.ts); over QUIC a
+//   transfer rides the bulk socket: a preview's request, or a route netd announced (tunnel-bulk.ts); over QUIC a
 //   stream that sends a megabyte without pausing yields to the others.
-// - Liveness: the front pings every 15s; a peer silent for 45s is unregistered.
+// - Liveness: netd pings every 15s; a peer silent for 45s is unregistered.
 // - Routing: host maps via hostOwnerId to a registered tunnel; no tunnel answers 502 naming the sandbox label, with
 //   the verdict header and CORS of edge-verdict.ts, and admits the preflight of the request it is about to refuse.
 // - The tunnel door and any host without a sandbox id are served directly by the ingress, never routed.