@intentic/sandbox-contract 1.325.0 → 1.327.0

package/src/protocol/peer-dial.test.ts

@@ -178,8 +178,8 @@ test("a far end that never answers is reported a few times, then retried quietly
             expect.stringContaining("14 failed attempts"),
         ]);
         // The retries themselves are untouched while the outage is young: one dial per ladder delay, twenty of them.
-        // The twentieth failure is what arms the long rest, so the dial after it is LONG_OUTAGE_MS away rather than
-        // one more rung — quiet in the log and quiet on the wire, which are separate rules meeting here.
+        // The twentieth failure is what arms the long rest, so the dial after it is LONG_OUTAGE_MS past its rung rather
+        // than one more rung — quiet in the log and quiet on the wire, which are separate rules meeting here.
         expect(sockets).toHaveLength(20);
         await advanceTimersByTimeAsync(LONG_OUTAGE_MS);
         await waitFor(() => expect(sockets).toHaveLength(21));
@@ -286,8 +286,11 @@ test("a link nobody has answered in a long time rests between tries, and is neve
         await advanceTimersByTimeAsync(RUNG_MS);
         expect(sockets).toHaveLength(LONG_OUTAGE_ATTEMPTS);
 
-        // And it does come round: slowed, never abandoned.
-        await advanceTimersByTimeAsync(LONG_OUTAGE_MS - RUNG_MS);
+        // And it does come round, the rest on top of the ladder's own (jittered) draw so links that went quiet together
+        // do not come back together: slowed, never abandoned.
+        await advanceTimersByTimeAsync(LONG_OUTAGE_MS - 1);
+        expect(sockets).toHaveLength(LONG_OUTAGE_ATTEMPTS);
+        await advanceTimersByTimeAsync(1);
         await waitFor(() => expect(sockets).toHaveLength(LONG_OUTAGE_ATTEMPTS + 1));
 
         // And one answer puts it straight back on the fast ladder — the outage is over, the penalty goes with it.
@@ -357,6 +360,82 @@ test("a stop during resolution opens nothing, and a socket a slow resolver still
     await waitFor(() => expect(late[0]?.closed).toEqual({ code: 1000, reason: "stopping" }));
 });
 
+// The redial used to be a bare timer: a link stopped while it waited on the ladder still dialled when the wait ran
+// out (a real socket, closed again only once the resolver had answered), read "connecting" while it did, and held
+// the process open for as long as the rung, fifteen minutes and more in a long outage.
+test("a stop during the wait on the ladder ends the wait: nothing is dialled and nothing is left armed", async () => {
+    jest.useFakeTimers();
+    try {
+        const { link, sockets } = dialling(60_000);
+        await waitFor(() => expect(sockets).toHaveLength(1));
+        sockets[0]?.opens();
+        sockets[0]?.drops(1006);
+        expect(link.state()).toBe("connecting");
+
+        link.stop();
+        await link.done;
+        expect(link.state()).toBe("closed");
+        expect(jest.getTimerCount()).toBe(0);
+        await advanceTimersByTimeAsync(120_000);
+        expect(sockets).toHaveLength(1);
+        expect(link.state()).toBe("closed");
+    } finally {
+        jest.useRealTimers();
+    }
+});
+
+// A socket abandoned for its silence can still deliver a frame it had buffered; that is no reason to arm a watchdog
+// for it again, which used to fire later only to find the socket already given up.
+test("a frame from a socket already abandoned arms nothing", async () => {
+    jest.useFakeTimers();
+    try {
+        const { link, sockets } = dialling(60_000);
+        await waitFor(() => expect(sockets).toHaveLength(1));
+        sockets[0]?.opens();
+        await advanceTimersByTimeAsync(SILENCE_MS);
+        expect(sockets[0]?.closed).toEqual({ code: 1000, reason: "no heartbeat" });
+        // The ladder's wait is the one timer now.
+        expect(jest.getTimerCount()).toBe(1);
+        sockets[0]?.says();
+        expect(jest.getTimerCount()).toBe(1);
+        link.stop();
+        await link.done;
+    } finally {
+        jest.useRealTimers();
+    }
+});
+
+// A hello that has to be fetched (the webext reads its token from storage) can resolve after the link is gone.
+test("a hello that resolves after a stop sends nothing and announces no connection", async () => {
+    let hand: ((hello: Record<string, unknown>) => void) | undefined;
+    const sockets: FakeSocket[] = [];
+    const said: string[] = [];
+    const link = dialPeer<FakeSocket>({
+        open: async () => {
+            const socket = new FakeSocket();
+            sockets.push(socket);
+            return { socket, said: "connected" };
+        },
+        hello: () =>
+            new Promise((resolve) => {
+                hand = resolve;
+            }),
+        attach: () => undefined,
+        backoff: ladder(),
+        silenceMs: SILENCE_MS,
+        log: (message) => void said.push(message),
+        revoked: () => undefined,
+    });
+    await waitFor(() => expect(sockets).toHaveLength(1));
+    sockets[0]?.opens();
+    link.stop();
+    await link.done;
+    hand?.({ type: "hello" });
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    expect(sockets[0]?.sent).toEqual([]);
+    expect(said).toEqual([]);
+});
+
 test("a pairing that is gone by the next attempt ends the loop rather than dialling nowhere", async () => {
     let pairings = 1;
     const sockets: FakeSocket[] = [];

package/src/protocol/peer-dial.ts

@@ -1,3 +1,5 @@
+import { anySignal, sleep, whenAborted } from "@intentic/base/async";
+
 // The one outbound socket a peer (machine agent, webext, runner) holds to its sandbox: hello carries the enrollment
 // token in the frame, then the link is pure oRPC. Reconnects on backoff after any drop except a revoked enrollment
 // (code 1008), which never retries.
@@ -85,17 +87,13 @@ export interface PeerLink {
 }
 
 export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink => {
+    // The loop's whole life: every way it ends (a stop, a revocation, a pairing gone) aborts this, and everything the
+    // loop arms hangs off it, so nothing it left behind can dial, wait or fire once it is over. A stopped link that
+    // kept a timer armed is a process the runtime keeps alive for a socket nobody holds any more.
     const stopping = new AbortController();
+    const done = new Promise<void>((resolve) => void whenAborted(stopping.signal, () => resolve()));
     let socket: S | undefined;
-    let waiting = false;
     let openedAt: number | undefined;
-    // The live attempt's watchdog, reachable from `stop`: a stopped link that left a timer armed is a process
-    // the runtime keeps alive for a socket nobody holds any more.
-    let disarmWatchdog: () => void = () => undefined;
-    let resolveDone: () => void = () => undefined;
-    const done = new Promise<void>((resolve) => {
-        resolveDone = resolve;
-    });
     // Consecutive attempts that have failed since this link was last open, and when the loop last complained out
     // loud: between them they are the whole of the quiet rule above.
     let failures = 0;
@@ -124,9 +122,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
     };
 
     const open = async (): Promise<void> => {
-        waiting = true;
         const attempt = await spec.open(stopping.signal);
-        waiting = false;
         // Aborted while resolving: nothing to open, `done` settled; a socket handed over late is closed, not dialled.
         if (stopping.signal.aborted) {
             attempt?.socket.close(1000, "stopping");
@@ -134,48 +130,44 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
         }
         if (attempt === undefined) {
             stopping.abort();
-            resolveDone();
             return;
         }
         const ws = attempt.socket;
         socket = ws;
 
+        // This socket's own life, ended by its drop or by the loop's. Its watchdog is cleared with it, so no way out of
+        // an attempt leaves a timer armed, and whatever the socket still emits afterwards speaks for nothing.
+        const dropped = new AbortController();
+        const live = anySignal(dropped.signal, stopping.signal);
         let watchdog: ReturnType<typeof setTimeout> | undefined;
-        const disarm = (): void => {
-            if (watchdog !== undefined) {
-                clearTimeout(watchdog);
-                watchdog = undefined;
-            }
-        };
-        disarmWatchdog = disarm;
+        whenAborted(live, () => clearTimeout(watchdog));
 
-        /* An attempt drop is recorded when either endpoint notices the closed far end. */
-        let dropped = false;
+        /* An attempt drop is recorded when either endpoint notices the closed far end; the first to notice ends it. */
         const drop = (said: string): void => {
-            if (dropped) {
-                return;
+            if (live.aborted) {
+                return; // noticed already, or the link was stopped and owes the ladder nothing
             }
-            dropped = true;
-            disarm();
+            dropped.abort();
             if (socket === ws) {
                 socket = undefined;
             }
-            if (stopping.signal.aborted) {
-                resolveDone();
-                return;
-            }
             const rung = spec.backoff.next(openedAt === undefined ? 0 : Date.now() - openedAt);
             openedAt = undefined;
             failures += 1;
             failingSince ??= Date.now();
-            const delay = failures >= LONG_OUTAGE_ATTEMPTS ? Math.max(rung, LONG_OUTAGE_MS) : rung;
+            // The rest is added to the ladder's draw rather than replacing it: a flat fifteen minutes would bring back in
+            // lockstep every link that entered the long outage together.
+            const delay = failures >= LONG_OUTAGE_ATTEMPTS ? LONG_OUTAGE_MS + rung : rung;
             complain(said, delay);
-            waiting = true;
-            setTimeout(() => void open(), delay);
+            // The wait hangs off the stop: a link stopped during it is done at once and never dials again.
+            void sleep(delay, { signal: stopping.signal }).then(() => (stopping.signal.aborted ? undefined : open()));
         };
 
         const arm = (): void => {
-            disarm();
+            clearTimeout(watchdog);
+            if (live.aborted) {
+                return; // a frame from a socket already abandoned proves nothing about the link
+            }
             watchdog = setTimeout(() => {
                 /* ABANDONED, not closed politely. A close frame sent to an end that is gone waits on a reply. */
                 ws.close(1000, "no heartbeat");
@@ -189,7 +181,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
         ws.addEventListener("message", arm);
 
         ws.addEventListener("open", () => {
-            if (dropped) {
+            if (live.aborted) {
                 return; // abandoned mid-connect: this socket is already closed and its replacement is on the ladder
             }
             openedAt = Date.now();
@@ -201,6 +193,10 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
             arm();
             spec.attach(ws);
             const send = (hello: Record<string, unknown>): void => {
+                // A hello that resolves after its socket dropped, or the link stopped, has no connection to announce.
+                if (live.aborted) {
+                    return;
+                }
                 ws.send(JSON.stringify(hello));
                 if (attempt.said !== undefined) {
                     spec.log(attempt.said);
@@ -218,13 +214,10 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
         ws.addEventListener("close", (event) => {
             /* A revocation is answered here rather than through `drop`: it is the one close that ends the loop. */
             if (event.code === PEER_UNAUTHORIZED) {
-                dropped = true;
-                disarm();
                 if (socket === ws) {
                     socket = undefined;
                 }
                 stopping.abort();
-                resolveDone();
                 spec.revoked();
                 return;
             }
@@ -247,15 +240,15 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
         done,
         stop: (reason = "stopping") => {
             stopping.abort();
-            waiting = false;
-            disarmWatchdog();
             // Forgotten before the close frame arrives, so `state` reads closed the moment the peer asked.
             const held = socket;
             socket = undefined;
             held?.close(1000, reason);
-            resolveDone();
         },
-        state: () => (socket?.readyState === OPEN ? "open" : socket !== undefined || waiting ? "connecting" : "closed"),
+        // Short of an open socket, a loop still running is "connecting" (a dial resolving, a handshake, a wait on the
+        // ladder) and a finished one is closed: read off the loop itself, not a flag kept beside it that a redial
+        // firing after the stop could set back.
+        state: () => (socket?.readyState === OPEN ? "open" : stopping.signal.aborted ? "closed" : "connecting"),
         outage: () => (failingSince === undefined ? undefined : { failures, since: failingSince }),
     };
 };

package/src/protocol/raw/extension-protocol.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { rawRouteUrl } from "./raw-routes.js";
+
+// The wire between the daemon and an extension's own code, its backend in the shared host and its declared processes
+// alike: the two routes every extension token reaches about itself (EXTENSION_OWN_ROUTES in extension-manifest), and
+// the environment a process is started with. `@intentic/extension-api/runtime` reads both, so the daemon and the SDK
+// compile against one declaration. A subpath of its own, since a gateway process loads no more of the contract than it
+// needs (the root builds every schema there is).
+
+// GET /extension/settings: the calling extension's own settings, secret values included, keyed by the declaration.
+export const ExtensionOwnSettingsSchema = z.object({
+    settings: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
+});
+export type ExtensionOwnSettings = z.infer<typeof ExtensionOwnSettingsSchema>;
+
+// GET /extension/events: one ndjson frame per line, for as long as the caller holds the stream. A heartbeat every
+// EXTENSION_EVENTS_HEARTBEAT_MS says the daemon is still there; the rest name what moved. `settings` carries only the
+// calling extension's own keys whose value changed.
+export const ExtensionEventSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("heartbeat") }),
+    z.object({ kind: z.literal("files"), paths: z.array(z.string()) }),
+    z.object({ kind: z.literal("refs"), repos: z.array(z.string()) }),
+    z.object({ kind: z.literal("repos"), repos: z.array(z.string()) }),
+    z.object({ kind: z.literal("settings"), keys: z.array(z.string()) }),
+]);
+export type ExtensionEvent = z.infer<typeof ExtensionEventSchema>;
+
+export const EXTENSION_EVENTS_HEARTBEAT_MS = 15_000;
+
+// The kinds a listener subscribes to, every frame but the heartbeat.
+export const EXTENSION_EVENT_KINDS = ["files", "refs", "repos", "settings"] as const;
+export type ExtensionEventKind = (typeof EXTENSION_EVENT_KINDS)[number];
+
+// A backend's own account of itself (`ServerActivation.health` in @intentic/extension-api), as the host reads it from
+// the extension's code and passes it on: a closed set of states and an optional sentence.
+export const ExtensionHealthSchema = z.object({
+    state: z.enum(["ok", "starting", "degraded", "failed"]),
+    detail: z.string().optional(),
+});
+
+export const extensionSettingsUrl = (): string => rawRouteUrl("GET /extension/settings");
+export const extensionEventsUrl = (): string => rawRouteUrl("GET /extension/events");
+
+// What the daemon starts an extension's process with, and what `connectExtensionProcess` reads. The token is the same
+// minted per-extension token its backend carries; the directories are the ones the backend api names.
+export const EXTENSION_PROCESS_ENV = {
+    daemon: "INTENTIC_DAEMON",
+    token: "INTENTIC_EXTENSION_TOKEN",
+    id: "INTENTIC_EXTENSION_ID",
+    workspace: "INTENTIC_WORKSPACE",
+    dir: "INTENTIC_EXTENSION_DIR",
+    state: "INTENTIC_EXTENSION_STATE",
+    cache: "INTENTIC_EXTENSION_CACHE",
+    // The manifest's `permissions.daemon` as a JSON array, so a typed call outside it is refused before it is sent.
+    permissions: "INTENTIC_EXTENSION_PERMISSIONS",
+} as const;
+
+// What the permissions variable holds.
+export const ExtensionPermissionsSchema = z.array(z.string());

package/src/protocol/raw/raw-json-routes.ts

@@ -0,0 +1,61 @@
+import type { z } from "zod";
+import { EngineChannelInputSchema, EngineRevertInputSchema, EnginesViewSchema, EngineUpdateInputSchema, EngineWriteResultSchema } from "../../schemas/engines.js";
+import {
+    EnvironmentApproveSchema,
+    EnvironmentContentsSchema,
+    EnvironmentRebuildWhenIdleSchema,
+    EnvironmentRemoveSchema,
+    EnvironmentRuntimeDecisionSchema,
+    EnvironmentSchema,
+} from "../../schemas/environment.js";
+import { MemberEmailSchema, MemberGrantSchema, MembersListSchema, MembersRosterSchema } from "../../schemas/members.js";
+import { OkSchema } from "../../schemas/shared.js";
+import { DefinitionDiffSchema, DefinitionExportSchema, WorkspacePublishResultSchema, WorkspacePublishSchema, WorkspaceRemoteSchema } from "../../state/definition.js";
+import type { RawRouteKey } from "./raw-routes.js";
+
+// What a raw route that answers plain JSON takes and answers, under its RAW_ROUTES key. `input` is the JSON body a write
+// sends; `text` marks one whose body is a document rather than JSON (a sandbox.toml to diff). A caller reaches these by
+// key through a typed helper that parses the answer with `output`, so a hand-written route is as typed as a procedure.
+// A refusal is the daemon's `{ "error": … }` with a 4xx status on every one of them, outside these schemas.
+export interface RawJsonRoute {
+    readonly input?: z.ZodType;
+    readonly text?: true;
+    readonly output: z.ZodType;
+}
+
+export const RAW_JSON_ROUTES = {
+    // The roster is ownership's; every write answers the roster after it.
+    "GET /members": { output: MembersRosterSchema },
+    "POST /members": { input: MemberGrantSchema, output: MembersListSchema },
+    "DELETE /members": { input: MemberEmailSchema, output: MembersListSchema },
+    "DELETE /members/self": { output: OkSchema },
+    // Every environment write answers the environment after it. `/environment/contents` takes `?refresh` to probe again.
+    "GET /environment": { output: EnvironmentSchema },
+    "GET /environment/contents": { output: EnvironmentContentsSchema },
+    "POST /environment/approve": { input: EnvironmentApproveSchema, output: EnvironmentSchema },
+    "POST /environment/reject": { output: EnvironmentSchema },
+    "POST /environment/runtime-install": { input: EnvironmentRuntimeDecisionSchema, output: EnvironmentSchema },
+    "POST /environment/remove": { input: EnvironmentRemoveSchema, output: EnvironmentSchema },
+    "POST /environment/rebuild-when-idle": { input: EnvironmentRebuildWhenIdleSchema, output: EnvironmentSchema },
+    "DELETE /environment/rebuild-when-idle": { output: EnvironmentSchema },
+    "GET /engines": { output: EnginesViewSchema },
+    "POST /engines/channel": { input: EngineChannelInputSchema, output: EngineWriteResultSchema },
+    "POST /engines/update": { input: EngineUpdateInputSchema, output: EngineWriteResultSchema },
+    "POST /engines/revert": { input: EngineRevertInputSchema, output: EngineWriteResultSchema },
+    "GET /definition": { output: DefinitionExportSchema },
+    "POST /definition/diff": { text: true, output: DefinitionDiffSchema },
+    "GET /definition/workspace": { output: WorkspaceRemoteSchema },
+    "POST /definition/workspace/publish": { input: WorkspacePublishSchema, output: WorkspacePublishResultSchema },
+} as const satisfies Partial<Record<RawRouteKey, RawJsonRoute>>;
+
+export type RawJsonRouteKey = keyof typeof RAW_JSON_ROUTES;
+
+// What a JSON raw route answers, parsed.
+export type RawJsonOutput<Key extends RawJsonRouteKey> = z.output<(typeof RAW_JSON_ROUTES)[Key]["output"]>;
+
+// What a JSON raw route's body is: its input's shape, a string for a document body, undefined for one that takes none.
+export type RawJsonInput<Key extends RawJsonRouteKey> = (typeof RAW_JSON_ROUTES)[Key] extends { readonly input: infer Input extends z.ZodType }
+    ? z.input<Input>
+    : (typeof RAW_JSON_ROUTES)[Key] extends { readonly text: true }
+      ? string
+      : undefined;

package/src/protocol/{raw-routes.ts → raw/raw-routes.ts}

@@ -1,10 +1,12 @@
-import type { RouteMeta } from "./route-meta.js";
-import type { ContractRoute } from "./routes.js";
-import { runnerTranslatorPath } from "./runner-protocol.js";
+import type { RouteMeta } from "../route-meta.js";
+import { fillRoutePath, type RoutePathParams } from "./route-path.js";
+import type { ContractRoute } from "../routes.js";
+import { runnerTranslatorPath } from "../doors/runner-protocol.js";
 
 // Every route the daemon serves outside oRPC (streamed bytes, WebSocket upgrades, doors checking their own credential),
 // keyed `METHOD /path` in the order the daemon registers them: among overlapping ones the first registered answers.
 // `{param}` is one path segment, a trailing `/*` any further ones, `ALL` every method; the daemon serves no other.
+// A route that answers plain JSON has its input and answer schemas in raw-json-routes.ts, under the same key.
 export const RAW_ROUTES = {
     // The "is a daemon there" probe every flow uses; it names the sandbox and says whether it is still converging.
     "GET /health": { auth: "door", beforeBoot: true },
@@ -29,15 +31,18 @@ export const RAW_ROUTES = {
     "POST /workspace/upload-archive": { lane: "bulk" },
     // Minting is cheap: each WebSocket upgrade floors its own redemption.
     "POST /system/ws-ticket": { beforeBoot: true, floor: "collaborator", control: "never" },
-    // A WebSocket upgrade carries no Authorization header; the terminal and both browser wires check a query ticket.
-    "GET /system/terminal": { auth: "door", beforeBoot: true, control: "never", front: true },
-    // The front's proof of life (vitals.ts): no credential and nothing of the workspace, readable by any origin, answered
+    // A WebSocket upgrade carries no Authorization header; the terminal, both browser wires and the desktop's check a
+    // query ticket.
+    "GET /system/terminal": { auth: "door", beforeBoot: true, control: "never", netd: true },
+    // netd's proof of life (vitals.ts): no credential and nothing of the workspace, readable by any origin, answered
     // whatever state the daemon is in.
-    "GET /system/vitals": { auth: "door", beforeBoot: true, front: true },
+    "GET /system/vitals": { auth: "door", beforeBoot: true, netd: true },
     // Desktop sync's byte pipe, guarded again by sshd's own key check against the same enrollment.
     "GET /system/sync/ssh": { sync: "pipe", control: "never", lane: "bulk" },
     "GET /system/browser-profile": { auth: "door", beforeBoot: true, control: "never" },
     "GET /system/browser-view": { auth: "door", beforeBoot: true, control: "never" },
+    // The sandbox's own desktop, watched and driven by the owner (desktop/desktop-view.ts); the same query ticket.
+    "GET /system/desktop-view": { auth: "door", beforeBoot: true, control: "never" },
     // Deploy-target enrollment, gated by the connect token.
     "POST /enroll": { auth: "door", control: "never" },
     // An event automation's webhook, gated by the automation's own token.
@@ -90,6 +95,9 @@ export const RAW_ROUTES = {
     "GET /arrivals/hosts": {},
     "POST /arrivals/scan": {},
     "POST /arrivals/apply": {},
+    // Model API keys on the owner's devices, and turning the picked ones into model endpoints.
+    "GET /arrivals/keys": {},
+    "POST /arrivals/keys/apply": {},
     "DELETE /arrivals": {},
     "GET /extensions/{id}/bundle": { lane: "bulk" },
     // An extension backend's own namespace, proxied verbatim.
@@ -122,6 +130,11 @@ export const RAW_ROUTES = {
     "POST /listeners/{provider}/dispatch": { panel: false, control: "never" },
     "POST /listeners/{provider}/failure": { panel: false, control: "never" },
     "POST /listeners/{provider}/status": { panel: false, control: "never" },
+    // What an extension's own code asks about itself (extension-protocol.ts): its settings with their secrets, and its
+    // event stream. Every extension token reaches both undeclared, and each answers only about the extension asking, so
+    // no other credential reaches them; the handler resolves the caller from its token again.
+    "GET /extension/settings": { floor: "maintainer", panel: false, control: "never" },
+    "GET /extension/events": { floor: "maintainer", panel: false, control: "never", stream: true },
     // The CI webhook receiver, gated by the per-sandbox webhook secret.
     "POST /ci/webhook/{host}": { auth: "door" },
     // Below maintainer a pairing is capped to port-mirror, so a collaborator may mint a preview tunnel.
@@ -138,6 +151,13 @@ export const RAW_ROUTES = {
     "GET /system/webext": { control: "never" },
     "DELETE /system/webext/{id}": { control: "never" },
     "GET /system/webext/connect": { auth: "door", beforeBoot: true, control: "never" },
+    "POST /system/phones/pair": { control: "never" },
+    "POST /system/phones/enroll": { auth: "door", control: "never" },
+    "GET /system/phones": { control: "never" },
+    "DELETE /system/phones/{id}": { control: "never" },
+    "GET /system/phones/connect": { auth: "door", beforeBoot: true, control: "never" },
+    // The editor hands over the push-relay channel it registered for a phone, so the sandbox can wake it.
+    "POST /system/phones/{id}/wake": { control: "never" },
     "POST /system/runners/pair": { control: "never" },
     "POST /system/runners/enroll": { auth: "door", control: "never" },
     "GET /system/runners": { control: "never" },
@@ -162,6 +182,9 @@ export const RAW_ROUTES = {
     // (privacy/gateway/session-token.ts), which names the provider and the only upstream it may forward to. Held open
     // while a model streams its answer.
     "ALL /privacy/gateway/{session}/*": { auth: "door", control: "never", stream: true },
+    // Its sibling for MCP: a hooked runtime's (Cursor's) calls to its turn's MCP servers, on a session signed the same
+    // way, naming the provider and the one server it may forward to. Held open while a server streams its answer.
+    "ALL /privacy/mcp/{session}": { auth: "door", control: "never", stream: true },
     "POST /system/control/tokens": { control: "never" },
     "GET /system/control/tokens": { control: "never" },
     "DELETE /system/control/tokens/{id}": { control: "never" },
@@ -196,6 +219,16 @@ export type RawRouteKey = keyof typeof RAW_ROUTES;
 // A raw route's path, for a caller that builds a URL to it rather than registering it.
 export const rawRoutePath = (key: RawRouteKey): string => key.slice(key.indexOf(" ") + 1);
 
+// The `{param}` values a raw route's path needs, by name; an empty record for a route with none.
+export type RawRouteParams<Key extends RawRouteKey> = Readonly<Record<RoutePathParams<Key>, string>>;
+
+// The path to call a raw route at: its template with every `{param}` filled and encoded as one segment. The one place a
+// caller outside the daemon spells a raw route, so a path that moves in the table moves for every caller.
+export const rawRouteUrl = <Key extends RawRouteKey>(
+    key: Key,
+    ...[params]: [RoutePathParams<Key>] extends [never] ? [] : [params: RawRouteParams<Key>]
+): string => fillRoutePath(rawRoutePath(key), params);
+
 // The table as routes of their own, each named by its key, in registration order.
 export const RAW_ROUTE_LIST: readonly (ContractRoute & { readonly name: RawRouteKey })[] = (Object.keys(RAW_ROUTES) as RawRouteKey[]).map((name) => ({
     name,

package/src/protocol/raw/route-path.ts

@@ -0,0 +1,13 @@
+// A route template's `{param}` names, read off the template itself so a caller cannot leave one out.
+export type RoutePathParams<Path extends string> = Path extends `${string}{${infer Name}}${infer Rest}` ? Name | RoutePathParams<Rest> : never;
+
+// A route template with each `{param}` filled by its value, encoded as exactly one path segment. A value missing for a
+// name the template carries throws: the path it would build names some other route.
+export const fillRoutePath = (template: string, params: Readonly<Record<string, string>> = {}): string =>
+    template.replace(/\{([^}]+)\}/gu, (_, name: string) => {
+        const value = params[name];
+        if (value === undefined) {
+            throw new Error(`${template} needs a value for {${name}}`);
+        }
+        return encodeURIComponent(value);
+    });

package/src/protocol/route-meta.ts

@@ -33,11 +33,11 @@ export interface RouteMeta {
     // Withheld from the panel token, which reaches every other route: it puts a stored credential in motion.
     readonly panel?: false;
     readonly control?: ControlReach;
-    // A transfer: announced to the edge through the front (tunnel-bulk.ts), which sends it down the tunnel's bulk socket,
+    // A transfer: announced to the edge through netd (tunnel-bulk.ts), which sends it down the tunnel's bulk socket,
     // off the connection every keystroke and call waits on.
     readonly lane?: "bulk";
-    // Served by intentic-front itself (_sandbox/front, term/): the daemon only answers the front's question about it.
-    readonly front?: true;
+    // Served by intentic-netd itself (_sandbox/netd, term/): the daemon only answers netd's question about it.
+    readonly netd?: true;
 }
 
 // The floor a route gets when it declares none: a read (GET, HEAD) floors at viewer, anything else (`ALL` included) at
@@ -45,7 +45,7 @@ export interface RouteMeta {
 export const defaultFloor = (method: string): MemberRole => (method === "GET" || method === "HEAD" ? "viewer" : "maintainer");
 
 // The fields that say how a request travels, not who may send it; every other RouteMeta field decides reach.
-type TransportField = "lane" | "front";
+type TransportField = "lane" | "netd";
 
 // Every field that decides who reaches a route, with its default resolved, so an absent field and a declared one read
 // alike and loosening either is a changed value: what contract.lock.json records per route (`access:METHOD /path`),

package/src/protocol/routes.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { RouteMeta } from "./route-meta.js";
+import { fillRoutePath } from "./raw/route-path.js";
 import { FRAME, streamOf } from "./stream-of.js";
 
 // Named route surface of the daemon's contract (`<group>.<route>`), derived automatically so nothing here is
@@ -38,6 +39,17 @@ export interface ContractRoute {
     readonly meta: RouteMeta;
 }
 
+// The path to call one contract procedure at, its `{param}`s filled and encoded, for a caller that speaks to the daemon
+// without oRPC's client (a stream it reads itself, a published tool keeping its install small): the path comes from
+// the contract, never spelled a second time.
+export const procedurePath = (procedure: unknown, params?: Readonly<Record<string, string>>): string => {
+    const route = procedureRoute(procedure);
+    if (route === undefined) {
+        throw new Error("not a contract procedure with a route");
+    }
+    return fillRoutePath(route.path, params);
+};
+
 // Walks a contract object (group → procedure) into a flat route list, sorted by name for a stable diff.
 export const contractRoutes = (contract: Record<string, unknown>): ContractRoute[] => {
     const routes: ContractRoute[] = [];

package/src/protocol/sse.test.ts

@@ -0,0 +1,49 @@
+import { sseData, sseFrames } from "./sse.js";
+
+const encoder = new TextEncoder();
+
+// A body that hands over `chunks` in order, then either closes or stays open saying nothing, as a daemon behind a
+// wedged tunnel does. `cancelled` records whether the reader let go of it.
+const body = (chunks: readonly string[], close: boolean): { stream: ReadableStream<Uint8Array>; cancelled: () => boolean } => {
+    let cancelled = false;
+    let index = 0;
+    const stream = new ReadableStream<Uint8Array>({
+        pull(controller) {
+            const chunk = chunks[index++];
+            if (chunk !== undefined) {
+                controller.enqueue(encoder.encode(chunk));
+            } else if (close) {
+                controller.close();
+            }
+        },
+        cancel() {
+            cancelled = true;
+        },
+    });
+    return { stream, cancelled: () => cancelled };
+};
+
+const collect = async (frames: AsyncGenerator<string>): Promise<string[]> => {
+    const seen: string[] = [];
+    for await (const frame of frames) {
+        seen.push(frame);
+    }
+    return seen;
+};
+
+it("reassembles frames split across chunks and ends when the stream closes", async () => {
+    const { stream } = body([`data: {"a":1}\n`, `\ndata: {"b"`, `:2}\n\n`], true);
+    expect(await collect(sseFrames(stream))).toEqual([`data: {"a":1}`, `data: {"b":2}`]);
+});
+
+it("ends a stream that goes silent past the idle window, and lets go of it", async () => {
+    const { stream, cancelled } = body([`data: {"a":1}\n\n`], false);
+    expect(await collect(sseFrames(stream, 20))).toEqual([`data: {"a":1}`]);
+    expect(cancelled()).toBe(true);
+});
+
+it("reads a frame's data line as JSON, and nothing from a frame without one or with a malformed payload", () => {
+    expect(sseData(`event: turn\ndata: {"kind":"end"}`)).toEqual({ kind: `end` });
+    expect(sseData(`: keep-alive`)).toBeUndefined();
+    expect(sseData(`data: {not json`)).toBeUndefined();
+});