@intentic/sandbox-contract 1.331.0 → 1.333.0

package/src/protocol/pairing-redeem.test.ts

@@ -0,0 +1,86 @@
+import { redeemWhileWarming, type RedeemRetry } from "./pairing-redeem.js";
+
+/* The redeem loop both pairing peers run, over a sandbox the test plays one answer at a time. */
+
+const scripted = (answers: readonly (number | "offline" | "hang")[]) => {
+    const tries: number[] = [];
+    const send = async (attempt: number, signal: AbortSignal | undefined): Promise<Response> => {
+        tries.push(attempt);
+        const next = answers[attempt - 1] ?? answers.at(-1) ?? "offline";
+        if (next === "offline") {
+            throw new TypeError("fetch failed");
+        }
+        if (next === "hang") {
+            return new Promise<Response>((_resolve, reject) => signal?.addEventListener("abort", () => reject(signal.reason)));
+        }
+        return new Response(`status ${next}`, { status: next });
+    };
+    return { tries, send };
+};
+
+const statusOf = (outcome: Awaited<ReturnType<typeof redeemWhileWarming>>): number | undefined =>
+    outcome.kind === "answered" ? outcome.response.status : undefined;
+
+describe("redeemWhileWarming", () => {
+    it("answers the first reply below 500 without asking again", async () => {
+        const { tries, send } = scripted([200]);
+        expect(statusOf(await redeemWhileWarming(send, { attempts: 3, delayMs: 0 }))).toBe(200);
+        expect(tries).toEqual([1]);
+    });
+
+    it("asks again through a warming sandbox and an unreachable one, saying why each time", async () => {
+        const { tries, send } = scripted(["offline", 502, 200]);
+        const heard: { attempt: number; why: RedeemRetry["kind"] }[] = [];
+        const outcome = await redeemWhileWarming(send, { attempts: 5, delayMs: 0, onRetry: (attempt, why) => heard.push({ attempt, why: why.kind }) });
+        expect(statusOf(outcome)).toBe(200);
+        expect(tries).toEqual([1, 2, 3]);
+        expect(heard).toEqual([
+            { attempt: 1, why: "unreachable" },
+            { attempt: 2, why: "warming" },
+        ]);
+    });
+
+    it("hands back a 401 at once: an expired code is an answer, not a blip", async () => {
+        const { tries, send } = scripted([401, 200]);
+        expect(statusOf(await redeemWhileWarming(send, { attempts: 5, delayMs: 0 }))).toBe(401);
+        expect(tries).toEqual([1]);
+    });
+
+    it("answers the last 5xx when the sandbox is still warming after every try", async () => {
+        const { tries, send } = scripted([503]);
+        const heard: number[] = [];
+        const outcome = await redeemWhileWarming(send, { attempts: 3, delayMs: 0, onRetry: (attempt) => heard.push(attempt) });
+        expect(outcome.kind).toBe("answered");
+        expect(outcome.kind === "answered" ? await outcome.response.text() : undefined).toBe("status 503");
+        expect(tries).toEqual([1, 2, 3]);
+        // The last try is not retried, so it is not narrated as one.
+        expect(heard).toEqual([1, 2]);
+    });
+
+    it("is unreachable, with the last try's failure, when nothing ever answered", async () => {
+        const { tries, send } = scripted(["offline"]);
+        const outcome = await redeemWhileWarming(send, { attempts: 2, delayMs: 0 });
+        expect(outcome.kind).toBe("unreachable");
+        expect(outcome.kind === "unreachable" ? outcome.error : undefined).toBeInstanceOf(TypeError);
+        expect(tries).toEqual([1, 2]);
+    });
+
+    it("abandons a try that outlives its timeout and asks again", async () => {
+        const { tries, send } = scripted(["hang", 200]);
+        expect(statusOf(await redeemWhileWarming(send, { attempts: 2, delayMs: 0, timeoutMs: 10 }))).toBe(200);
+        expect(tries).toEqual([1, 2]);
+    });
+
+    it("rejects with the stop's reason rather than answering when its signal aborts", async () => {
+        const stop = new AbortController();
+        const { tries, send } = scripted([502]);
+        const running = redeemWhileWarming(send, {
+            attempts: 5,
+            delayMs: 60_000,
+            signal: stop.signal,
+            onRetry: () => stop.abort(new Error("stopped")),
+        });
+        await expect(running).rejects.toThrow("stopped");
+        expect(tries).toEqual([1]);
+    });
+});

package/src/protocol/pairing-redeem.ts

@@ -0,0 +1,79 @@
+import { retry, withDeadline } from "@intentic/base/async";
+
+// Redeeming a pairing code's one-time token, as every peer that takes one does it (the machine agent's
+// `postWhileWarming`, the webext's `redeemPairing`): a sandbox still warming up answers 5xx through its tunnel, or
+// nothing at all, and is asked again. Any other answer, a 401 above all (the code has expired), is the caller's to read
+// at once: asking again would only delay the fresh code the person has to fetch.
+
+// Why a try is being asked again: no answer at all, or a 5xx from a sandbox not ready yet.
+export type RedeemRetry = { readonly kind: "unreachable"; readonly error: unknown } | { readonly kind: "warming"; readonly status: number };
+
+export type RedeemOutcome =
+    // The sandbox's answer: below 500 at once, or still 5xx when the tries ran out.
+    | { readonly kind: "answered"; readonly response: Response }
+    // No answer at all on the last try; `error` is that try's failure.
+    | { readonly kind: "unreachable"; readonly error: unknown };
+
+export interface RedeemOptions {
+    // Tries in all, the first included.
+    readonly attempts: number;
+    // The wait between tries.
+    readonly delayMs: number;
+    // How long one try may take before it is abandoned and counts as unreachable; none when absent.
+    readonly timeoutMs?: number | undefined;
+    // Stops the tries: a stop rejects with the signal's reason rather than answering.
+    readonly signal?: AbortSignal | undefined;
+    // Hears each try that is about to be asked again, before the wait.
+    readonly onRetry?: ((attempt: number, why: RedeemRetry) => void) | undefined;
+}
+
+// A 5xx carried out of a try so `retry` asks again, and handed back as the answer when the tries run out.
+class Warming extends Error {
+    constructor(readonly response: Response) {
+        super(`the sandbox is warming up (HTTP ${response.status})`);
+    }
+}
+
+// Runs `send` (one POST, handed the try's number and a signal to pass to its fetch, undefined when there is neither a
+// deadline nor a stop) until the sandbox answers below 500 or the tries run out.
+export const redeemWhileWarming = async (
+    send: (attempt: number, signal: AbortSignal | undefined) => Promise<Response>,
+    options: RedeemOptions,
+): Promise<RedeemOutcome> => {
+    const { attempts, delayMs, timeoutMs, signal, onRetry } = options;
+    const once = (attempt: number): Promise<Response> =>
+        timeoutMs === undefined ? send(attempt, signal) : withDeadline((bounded) => send(attempt, bounded), timeoutMs, { signal });
+    try {
+        const response = await retry(
+            async (attempt) => {
+                let answer: Response;
+                try {
+                    answer = await once(attempt);
+                } catch (error) {
+                    if (attempt < attempts && signal?.aborted !== true) {
+                        onRetry?.(attempt, { kind: "unreachable", error });
+                    }
+                    throw error;
+                }
+                if (answer.status < 500) {
+                    return answer;
+                }
+                if (attempt < attempts) {
+                    onRetry?.(attempt, { kind: "warming", status: answer.status });
+                }
+                throw new Warming(answer);
+            },
+            { attempts, delayMs: () => delayMs, signal },
+        );
+        return { kind: "answered", response };
+    } catch (error) {
+        if (signal?.aborted === true) {
+            // oxlint-disable-next-line typescript/only-throw-error -- the stop's own reason, as an aborted fetch rejects with it
+            throw signal.reason;
+        }
+        if (error instanceof Warming) {
+            return { kind: "answered", response: error.response };
+        }
+        return { kind: "unreachable", error };
+    }
+};

package/src/protocol/peer-mcp-server.ts

@@ -2,6 +2,7 @@
 // namespace keeps zod's 60 locales (~250 kB) that esbuild can otherwise drop. _devices/webext/scripts/size-budget.mjs holds the ceiling.
 import { prettifyError, toJSONSchema } from "zod";
 import type * as z from "zod";
+import { isRecord } from "@intentic/base/escape";
 
 // The MCP version every peer announces, here rather than in host-protocol.ts because a browser extension bundles this
 // module and would otherwise carry the machine handshake's schemas to a store. Also read by the daemon's peer bridge,
@@ -99,8 +100,6 @@ export interface McpServerSpec<Ctx> {
     readonly audit: (entry: McpAuditEntry) => Promise<void> | void;
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
-
 // Handles one JSON-RPC message; returns undefined for a notification. `ctx` is read per call, so a grant pushed
 // mid-session takes effect on the next call.
 export const createMcpServer = <Ctx>(spec: McpServerSpec<Ctx>): ((message: unknown, ctx: Ctx) => Promise<Record<string, unknown> | undefined>) => {

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

@@ -0,0 +1,87 @@
+import { RAW_JSON_ROUTES, type RawJsonRoute } from "./raw-json-routes.js";
+import { RAW_ROUTES, rawRouteUrl } from "./raw-routes.js";
+
+// The table the editor calls the daemon's plain-JSON routes by: each entry is a route the daemon registers, says what it
+// takes and answers, and parses what the editor reads off the wire.
+
+const entries = Object.entries<RawJsonRoute>(RAW_JSON_ROUTES);
+const keys = entries.map(([key]) => key);
+const bodies = (route: RawJsonRoute): number => [route.input !== undefined, route.text === true, route.bytes === true].filter(Boolean).length;
+
+describe(`RAW_JSON_ROUTES`, () => {
+    it(`names only routes the daemon registers, so a typed call can never aim at a path nothing serves`, () => {
+        expect(keys.filter((key) => !(key in RAW_ROUTES))).toEqual([]);
+    });
+
+    it(`gives a route one kind of body: JSON, a document, or bytes`, () => {
+        expect(entries.filter(([, route]) => bodies(route) > 1).map(([key]) => key)).toEqual([]);
+    });
+
+    it(`takes a body only on a route that writes: a read has none to send`, () => {
+        expect(entries.filter(([key, route]) => key.startsWith(`GET `) && bodies(route) > 0).map(([key]) => key)).toEqual([]);
+    });
+
+    it(`holds the routes the editor's rosters, access tab, uploads and dictation reach by key`, () => {
+        expect(keys).toEqual(
+            expect.arrayContaining([
+                `GET /system/hosts`,
+                `GET /system/webext`,
+                `GET /system/phones`,
+                `GET /system/runners`,
+                `GET /system/sync`,
+                `POST /system/sync/pair`,
+                `GET /system/passkeys`,
+                `POST /system/passkeys/register`,
+                `GET /system/control/tokens`,
+                `GET /bundles`,
+                `POST /arrivals/plan`,
+                `GET /speech/status`,
+                `POST /workspace/upload`,
+                `POST /workspace/upload-diff`,
+            ]),
+        );
+    });
+
+    it(`has a path every {param} of which is filled and encoded as one segment`, () => {
+        expect(rawRouteUrl(`DELETE /system/hosts/{id}`, { id: `my laptop/1` })).toBe(`/system/hosts/my%20laptop%2F1`);
+        expect(rawRouteUrl(`POST /system/runners/{id}/definition/sync`, { id: `r 1` })).toBe(`/system/runners/r%201/definition/sync`);
+    });
+});
+
+describe(`what the rosters and pairings answer`, () => {
+    it(`reads a peer's pairing from an older daemon, which sent a token and no code`, () => {
+        expect(RAW_JSON_ROUTES[`POST /system/webext/pair`].output.parse({ token: `iht_x` })).toEqual({ token: `iht_x` });
+        expect(RAW_JSON_ROUTES[`POST /system/hosts/pair`].output.parse({ token: `iht_x`, expiresIn: 600, code: `ABCD1234` })).toEqual({
+            token: `iht_x`,
+            expiresIn: 600,
+            code: `ABCD1234`,
+        });
+    });
+
+    it(`reads the sync pairing with the mode the daemon granted`, () => {
+        expect(RAW_JSON_ROUTES[`POST /system/sync/pair`].output.parse({ token: `t`, expiresIn: 600, code: `ABCD1234`, mode: `mirror` })).toMatchObject({ mode: `mirror` });
+        expect(() => RAW_JSON_ROUTES[`POST /system/sync/pair`].output.parse({ token: `t`, mode: `both` })).toThrow();
+    });
+
+    it(`reads a runner list, which two screens used to each describe themselves`, () => {
+        expect(RAW_JSON_ROUTES[`GET /system/runners`].output.parse({ runners: [{ id: `r1`, online: false, parity: `unknown` }] })).toEqual({
+            runners: [{ id: `r1`, online: false, parity: `unknown` }],
+        });
+        expect(() => RAW_JSON_ROUTES[`GET /system/runners`].output.parse({ runners: [{ id: `r1` }] })).toThrow();
+    });
+
+    it(`accepts the WebAuthn options only with the challenge the browser's own parser needs`, () => {
+        expect(RAW_JSON_ROUTES[`POST /system/passkeys/register/options`].output.safeParse({ challenge: `AwQ`, rp: { id: `app.test`, name: `work` } }).success).toBe(true);
+        expect(RAW_JSON_ROUTES[`POST /system/passkeys/register/options`].output.safeParse({ rp: { id: `app.test` } }).success).toBe(false);
+        expect(RAW_JSON_ROUTES[`POST /system/passkeys/assert/options`].output.safeParse({ challenge: `AQID`, available: true }).success).toBe(true);
+    });
+
+    it(`reads a session recovery as the session and the codes still unspent`, () => {
+        expect(RAW_JSON_ROUTES[`POST /system/session/recover`].output.parse({ token: `s`, expiresAt: 5, email: `a@example.com`, remaining: 3 })).toEqual({
+            token: `s`,
+            expiresAt: 5,
+            email: `a@example.com`,
+            remaining: 3,
+        });
+    });
+});

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

@@ -1,6 +1,10 @@
 import type { z } from "zod";
+import { ControlTokenMintedSchema, ControlTokenMintSchema, ControlTokensListSchema } from "../../policy/control-scopes.js";
 import { EngineChannelInputSchema, EngineRevertInputSchema, EnginesViewSchema, EngineUpdateInputSchema, EngineWriteResultSchema } from "../../schemas/engines.js";
 import {
+    BundleExportsSchema,
+    BundleStartedSchema,
+    BundleTicketSchema,
     EnvironmentApproveSchema,
     EnvironmentContentsSchema,
     EnvironmentRebuildWhenIdleSchema,
@@ -8,22 +12,64 @@ import {
     EnvironmentRuntimeDecisionSchema,
     EnvironmentSchema,
 } from "../../schemas/environment.js";
+import { SyncStatusSchema } from "../../schemas/devices.js";
+import { HostsListSchema } from "../../schemas/hosts.js";
+import { VoicesViewSchema } from "../../schemas/voice.js";
 import { MemberEmailSchema, MemberGrantSchema, MembersListSchema, MembersRosterSchema } from "../../schemas/members.js";
+import { PhonesListSchema, PhoneWakeRegistrationSchema } from "../../schemas/phone.js";
 import { OkSchema } from "../../schemas/shared.js";
+import { EnrollCodeAnswerSchema, EnrollCodeRequestSchema, PeerPairingAnswerSchema, SyncPairAnswerSchema, SyncPairRequestSchema } from "../../schemas/short-codes.js";
+import { SpeechStatusSchema, SpeechTranscriptSchema } from "../../schemas/speech.js";
+import {
+    AuthenticationOptionsSchema,
+    DaemonSessionSchema,
+    PasskeyAssertRequestSchema,
+    PasskeyPolicyAnswerSchema,
+    PasskeyPolicySchema,
+    PasskeyRecoverRequestSchema,
+    PasskeyRegisteredSchema,
+    PasskeyRegisterRequestSchema,
+    PasskeysListSchema,
+    RecoveryCodesSchema,
+    RegistrationOptionsSchema,
+    SessionRecoveredSchema,
+} from "../../schemas/system.js";
+import { WebExtsListSchema } from "../../schemas/webext.js";
+import { UploadManifestSchema, UploadSkipSchema } from "../../schemas/workspace/workspace-upload.js";
+import {
+    ArrivalAbandonedSchema,
+    ArrivalApplySchema,
+    ArrivalHostsSchema,
+    ArrivalPlanSchema,
+    ArrivalReportSchema,
+    ArrivalScanSchema,
+    ProviderKeysAppliedSchema,
+    ProviderKeysApplySchema,
+    ProviderKeysSchema,
+} from "../../state/arrival.js";
 import { DefinitionDiffSchema, DefinitionExportSchema, WorkspacePublishResultSchema, WorkspacePublishSchema, WorkspaceRemoteSchema } from "../../state/definition.js";
+import { RunnerDefinitionAppliedSchema, RunnersListSchema } from "../doors/runner-protocol.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.
+// sends; `text` marks one whose body is a document rather than JSON (a sandbox.toml to diff), and `bytes` one whose body
+// is the thing itself (a file's bytes, a WAV, a tar), which the caller hands over as a Blob, an ArrayBuffer or a string.
+// 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. What a route takes in its query string (`?id=`, `?path=`) and in a header is the helper's
+// `query` and `headers`, since the daemon reads them by name and there is nothing to parse. 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 bytes?: true;
     readonly output: z.ZodType;
 }
 
 export const RAW_JSON_ROUTES = {
+    // The voices a sandbox speaks with, for the Voice settings (schemas/voice.ts).
+    "GET /speech/voices": { output: VoicesViewSchema },
+    // A server-connect code for the owner's command (short-codes.ts).
+    "POST /system/enroll/code": { input: EnrollCodeRequestSchema, output: EnrollCodeAnswerSchema },
     // The roster is ownership's; every write answers the roster after it.
     "GET /members": { output: MembersRosterSchema },
     "POST /members": { input: MemberGrantSchema, output: MembersListSchema },
@@ -46,6 +92,70 @@ export const RAW_JSON_ROUTES = {
     "POST /definition/diff": { text: true, output: DefinitionDiffSchema },
     "GET /definition/workspace": { output: WorkspaceRemoteSchema },
     "POST /definition/workspace/publish": { input: WorkspacePublishSchema, output: WorkspacePublishResultSchema },
+    // Sandboxes moving in: a plan read off an archive (`bytes`) or a connected device, applied by its token, and the
+    // model keys the owner's devices hold.
+    "GET /arrivals/hosts": { output: ArrivalHostsSchema },
+    "POST /arrivals/scan": { input: ArrivalScanSchema, output: ArrivalPlanSchema },
+    "POST /arrivals/plan": { bytes: true, output: ArrivalPlanSchema },
+    "POST /arrivals/apply": { input: ArrivalApplySchema, output: ArrivalReportSchema },
+    "GET /arrivals/keys": { output: ProviderKeysSchema },
+    "POST /arrivals/keys/apply": { input: ProviderKeysApplySchema, output: ProviderKeysAppliedSchema },
+    "DELETE /arrivals": { output: ArrivalAbandonedSchema },
+    // Exports: `?secrets=1` on the start, `?name=` on the delete and the ticket.
+    "GET /bundles": { output: BundleExportsSchema },
+    "POST /bundles": { output: BundleStartedSchema },
+    "DELETE /bundles": { output: OkSchema },
+    "POST /bundles/ticket": { output: BundleTicketSchema },
+    // Paired machines: each door's roster, the pairing minted for one id (`?id=`), and dropping one's enrollment. The
+    // devices' answer is `hosts`, the browsers' `browsers`, the phones' `phones`, the runners' `runners`.
+    "GET /system/hosts": { output: HostsListSchema },
+    "POST /system/hosts/pair": { output: PeerPairingAnswerSchema },
+    "DELETE /system/hosts/{id}": { output: OkSchema },
+    "GET /system/webext": { output: WebExtsListSchema },
+    "POST /system/webext/pair": { output: PeerPairingAnswerSchema },
+    "DELETE /system/webext/{id}": { output: OkSchema },
+    "GET /system/phones": { output: PhonesListSchema },
+    "POST /system/phones/pair": { output: PeerPairingAnswerSchema },
+    "DELETE /system/phones/{id}": { output: OkSchema },
+    "POST /system/phones/{id}/wake": { input: PhoneWakeRegistrationSchema, output: OkSchema },
+    "GET /system/runners": { output: RunnersListSchema },
+    "DELETE /system/runners/{id}": { output: OkSchema },
+    "POST /system/runners/{id}/definition/sync": { output: RunnerDefinitionAppliedSchema },
+    // Desktop sync: the sandbox-level state, the pairing (`?mode=mirror` asks for the narrower one), one machine's key.
+    "GET /system/sync": { output: SyncStatusSchema },
+    "POST /system/sync/pair": { input: SyncPairRequestSchema, output: SyncPairAnswerSchema },
+    "DELETE /system/authorized-key/{machine}": { output: OkSchema },
+    // Every browser session revoked, the owner's own included.
+    "POST /system/sessions/revoke": { output: OkSchema },
+    "GET /system/control/tokens": { output: ControlTokensListSchema },
+    "POST /system/control/tokens": { input: ControlTokenMintSchema, output: ControlTokenMintedSchema },
+    "DELETE /system/control/tokens/{id}": { output: OkSchema },
+    // One's own passkeys, the require rule and its recovery codes. The two registration calls carry the WebAuthn ceremony's
+    // options out and its response back, the shapes the browser's own parser reads and writes.
+    "GET /system/passkeys": { output: PasskeysListSchema },
+    "POST /system/passkeys/register/options": { output: RegistrationOptionsSchema },
+    "POST /system/passkeys/register": { input: PasskeyRegisterRequestSchema, output: PasskeyRegisteredSchema },
+    "POST /system/passkeys/policy": { input: PasskeyPolicySchema, output: PasskeyPolicyAnswerSchema },
+    "POST /system/passkeys/recovery": { output: RecoveryCodesSchema },
+    "DELETE /system/passkeys/{id}": { output: OkSchema },
+    // The sign-in's own calls, before any session exists: the assertion is how one is minted, and recovery is the owner's
+    // way back in with the code a policy handed out. Their credential is the door's (a challenge, a recovery code under the
+    // caller's own proof), so the editor sends them outside its session client (client/session/passkeySignIn.ts) and reads
+    // their answers with these schemas.
+    "POST /system/passkeys/assert/options": { output: AuthenticationOptionsSchema },
+    "POST /system/passkeys/assert": { input: PasskeyAssertRequestSchema, output: DaemonSessionSchema },
+    "POST /system/session/recover": { input: PasskeyRecoverRequestSchema, output: SessionRecoveredSchema },
+    // Dictation over HTTP, for a daemon without the phrase stream (`?lang=`): the model's readiness, arming it, and one
+    // phrase as WAV.
+    "GET /speech/status": { output: SpeechStatusSchema },
+    "POST /speech/prepare": { output: SpeechStatusSchema },
+    "POST /speech/transcribe": { bytes: true, output: SpeechTranscriptSchema },
+    // A file written into the tree (`?path=`, the body its bytes, `x-intentic-base-hash` refusing a stale save), and the
+    // pre-drop check of which dropped files are already there.
+    "POST /workspace/upload": { bytes: true, output: OkSchema },
+    // A dropped tree as one tar, extracted entry by entry.
+    "POST /workspace/upload-archive": { bytes: true, output: OkSchema },
+    "POST /workspace/upload-diff": { input: UploadManifestSchema, output: UploadSkipSchema },
 } as const satisfies Partial<Record<RawRouteKey, RawJsonRoute>>;
 
 export type RawJsonRouteKey = keyof typeof RAW_JSON_ROUTES;
@@ -53,9 +163,21 @@ 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.
+// The routes that take their body as bytes: a file, a WAV, a tar. Some of these also go up in parts with progress.
+export type RawBytesRouteKey = {
+    [Key in RawJsonRouteKey]: (typeof RAW_JSON_ROUTES)[Key] extends { readonly bytes: true } ? Key : never;
+}[RawJsonRouteKey];
+
+// The body a `bytes` route takes: a Blob or typed array (a file, a tar), an ArrayBuffer (an encoded WAV) or a string
+// (a saved file's text).
+export type RawBytes = Blob | ArrayBuffer | ArrayBufferView | string;
+
+// What a JSON raw route's body is: its input's shape, a string for a document body, the bytes for a `bytes` route,
+// 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;
+      : (typeof RAW_JSON_ROUTES)[Key] extends { readonly bytes: true }
+        ? RawBytes
+        : undefined;

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

@@ -21,6 +21,12 @@ export const RAW_ROUTES = {
     // The live phrase stream (schemas/speech.ts): a WebSocket, so the query ticket, floored at the collaborator in the
     // handler like the transcribe it streams.
     "GET /speech/stream": { auth: "door" },
+    // Speaking (schemas/voice.ts): the voices to choose from is a read any tier makes; speech costs this box's CPU or
+    // the owner's provider credits, so saying anything is the collaborator's, like dictating. The WebSocket floors its
+    // query ticket in the handler; the HTTP door is Discord's calls and anything without a socket.
+    "GET /speech/voices": { guest: true },
+    "POST /speech/say": { floor: "collaborator" },
+    "GET /speech/say": { auth: "door" },
     // The bytes behind the workspace reads; each applies the caller's fence itself.
     "GET /workspace/raw": { guest: true, lane: "bulk" },
     // No door, unlike media: the page fetches a thumbnail itself, so the request carries the header.
@@ -49,6 +55,8 @@ export const RAW_ROUTES = {
     "GET /system/desktop-view": { auth: "door", beforeBoot: true, control: "never" },
     // Deploy-target enrollment, gated by the connect token.
     "POST /enroll": { auth: "door", control: "never" },
+    // A server-connect code for the owner's command: its single-use enroll token stands in for the connect token.
+    "POST /system/enroll/code": { floor: "owner", control: "never" },
     // An event automation's webhook, gated by the automation's own token.
     "POST /automations/{id}/fire": { auth: "door" },
     // The release gate a pipeline runner waits on, gated by the workflow's minted gate token.
@@ -154,6 +162,9 @@ export const RAW_ROUTES = {
     "POST /ci/webhook/{host}": { auth: "door" },
     // Below maintainer a pairing is capped to port-mirror, so a collaborator may mint a preview tunnel.
     "POST /system/sync/pair": { floor: "collaborator", control: "never" },
+    // A copy-paste command's short code, redeemed by the install script it was handed to: a device's first contact,
+    // gated by the code itself and a limit on failed attempts (peers/redeem-codes.ts).
+    "POST /system/redeem/{code}": { auth: "door", control: "never" },
     // The peer doors: a device, browser or runner redeems its pairing at `enroll` and dials `connect` with the token.
     "POST /system/hosts/pair": { control: "never" },
     "POST /system/hosts/enroll": { auth: "door", control: "never" },

package/src/protocol/sse.test.ts

@@ -1,4 +1,4 @@
-import { sseData, sseFrames } from "./sse.js";
+import { parseSseText, type SseEvent, sseData, sseEvents, sseFrames, sseJson } from "./sse.js";
 
 const encoder = new TextEncoder();
 
@@ -47,3 +47,52 @@ it("reads a frame's data line as JSON, and nothing from a frame without one or w
     expect(sseData(`: keep-alive`)).toBeUndefined();
     expect(sseData(`data: {not json`)).toBeUndefined();
 });
+
+const collectEvents = async (events: AsyncGenerator<SseEvent>): Promise<SseEvent[]> => {
+    const seen: SseEvent[] = [];
+    for await (const event of events) {
+        seen.push(event);
+    }
+    return seen;
+};
+
+it("ends events at CRLF, CR and LF blank lines alike, a CRLF split across chunks included", async () => {
+    const { stream } = body([`data: 1\r\n\r`, `\ndata: 2\r\rdata: 3\n\n`], true);
+    expect((await collectEvents(sseEvents(stream))).map((event) => event.data)).toEqual([`1`, `2`, `3`]);
+});
+
+it("joins every data line of an event with a newline", () => {
+    expect(parseSseText(`data: {"a":\ndata: 1}\n\n`).map((event) => event.data)).toEqual([`{"a":\n1}`]);
+    expect(sseData(`data: {"a":\ndata: 1}`)).toEqual({ a: 1 });
+});
+
+it("reads event, id and retry, keeps the last id across events, and skips comments", () => {
+    const events = parseSseText(`: hello\nevent: turn\nid: 7\nretry: 3000\ndata: x\n\ndata: y\n\n`);
+    expect(events.map(({ event, data, id, retry }) => ({ event, data, id, retry }))).toEqual([
+        { event: `turn`, data: `x`, id: `7`, retry: 3000 },
+        { event: undefined, data: `y`, id: `7`, retry: undefined },
+    ]);
+});
+
+it("drops one space after the colon and no more, and a leading byte-order mark", () => {
+    expect(parseSseText(`\uFEFFdata:  two spaces\n\n`).map((event) => event.data)).toEqual([` two spaces`]);
+});
+
+it("keeps each event's raw text, its blank line included, for a reader forwarding it unchanged", () => {
+    expect(parseSseText(`event: a\r\ndata: 1\r\n\r\n: ping\n\n`).map((event) => event.raw)).toEqual([`event: a\r\ndata: 1\r\n\r\n`, `: ping\n\n`]);
+});
+
+it("dispatches an event the stream ended inside", async () => {
+    const { stream } = body([`data: last`], true);
+    expect((await collectEvents(sseEvents(stream))).map((event) => event.data)).toEqual([`last`]);
+});
+
+it("ends an event stream that goes silent past the idle window", async () => {
+    const { stream, cancelled } = body([`data: 1\n\n`], false);
+    expect((await collectEvents(sseEvents(stream, 20))).map((event) => event.data)).toEqual([`1`]);
+    expect(cancelled()).toBe(true);
+});
+
+it("sseJson reads a parsed event's data", () => {
+    expect([sseJson(parseSseText(`data: [1]\n\n`)[0]!), sseJson(parseSseText(`: c\n\n`)[0]!)]).toEqual([[1], undefined]);
+});