@intentic/sandbox-contract 1.332.0 → 1.333.0

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,23 +12,62 @@ 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 } from "../../schemas/short-codes.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.
@@ -49,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;
@@ -56,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.

package/src/schemas/automations.ts

@@ -435,7 +435,7 @@ export const AutomationSchema = z.object({
     enabled: z.boolean().describe("Whether it fires at all."),
 });
 export type Automation = z.infer<typeof AutomationSchema>;
-// A wake held for owner approval (.intentic/records/approvals/<id>.json); snapshots the trigger payload so an approved
+// A wake held for owner approval (automation-holds/<id>.json on the history volume); snapshots the trigger payload so an approved
 // run replays exactly what fired, even across a daemon restart.
 export const AutomationApprovalSchema = z.object({
     id: entryId.describe("This waiting item's own id, which approving and rejecting take."),
@@ -476,7 +476,7 @@ export const AutomationApprovalSchema = z.object({
         .number()
         .optional()
         .describe(
-            "When it goes ahead on its own, in milliseconds, for a hold that is only a delay. Absent for one that genuinely waits on a person.",
+            "When it goes ahead on its own, in milliseconds, for a hold that is only a delay. Absent for one that genuinely waits on a person, and for one the sandbox did not itself queue, which only a person releases.",
         ),
 });
 export type AutomationApproval = z.infer<typeof AutomationApprovalSchema>;
@@ -484,7 +484,14 @@ export type AutomationApproval = z.infer<typeof AutomationApprovalSchema>;
 // Whether a held wake waits on a person. A countdown hold (`autoRunAt`) releases itself, so counting it would ask the
 // owner about something already about to happen on its own.
 export const awaitsOwner = (wake: Pick<AutomationApproval, "autoRunAt">): boolean => wake.autoRunAt === undefined;
-export const AutomationApprovalsListSchema = z.object({ approvals: z.array(AutomationApprovalSchema).describe("Everything waiting for a yes.") });
+export const AutomationApprovalsListSchema = z.object({
+    approvals: z.array(AutomationApprovalSchema).describe("Everything waiting for a yes."),
+    // Reported, never dropped: a file in the queue the sandbox cannot read would otherwise be a hold that never runs and never says why.
+    unreadable: z
+        .array(z.string())
+        .default([])
+        .describe("Files in the queue this sandbox could not read, by name. Each is a held wake that cannot be released until it is fixed or removed."),
+});
 export const AutomationApprovalIdParamSchema = z.object({ id: z.string().describe("Which waiting item.") });
 export const AutomationRunSchema = z.object({
     at: z.number(),

package/src/schemas/device-swaps.test.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import { DeviceSwapsSchema } from "./device-swaps.js";
+
+// The rows `ic sandbox swaps --json` answers, as examples: golden/swap-verdicts.json holds each of ic's records and the
+// row it gives (the Rust test, _sandbox/ic/src/sandbox/swaps.rs, builds every one; the machine agent's fallback is held
+// to the same rows). This is the TS half: the rows ic gives are the rows the contract reads, to the field.
+
+interface VerdictCase {
+    readonly name: string;
+    readonly record: string;
+    readonly now: number;
+    readonly swap: Record<string, unknown> | null;
+}
+
+// SAFETY: the golden is this package's own file; the assertions below fail on any field it lacks.
+const GOLDEN = JSON.parse(readFileSync(join(packageRoot(import.meta.url), "golden", "swap-verdicts.json"), "utf8")) as {
+    readonly slug: string;
+    readonly cases: readonly VerdictCase[];
+};
+const rows: unknown[] = GOLDEN.cases.flatMap((one) => (one.swap === null ? [] : [one.swap]));
+
+test("every row ic gives for the golden records is a row the contract reads, field for field", () => {
+    expect(rows.length).toBeGreaterThan(8);
+    const read: unknown = DeviceSwapsSchema.parse(rows);
+    expect(read).toEqual(rows);
+});
+
+test("a row from a newer ic keeps the swap going on: an unknown phase and an extra field still read", () => {
+    const [row] = DeviceSwapsSchema.parse([{ slug: "work", phase: "staging", at: 5, cutoverInProgress: false, next: "later" }]);
+    expect(row).toMatchObject({ slug: "work", phase: "staging", at: 5, cutoverInProgress: false });
+});
+
+test("a field of the wrong type is a field that is not there, but a row without its verdict is no row", () => {
+    const [row] = DeviceSwapsSchema.parse([{ slug: "work", phase: "cutover", at: 5, alive: "soon", cutoverInProgress: true }]);
+    expect(row?.alive).toBeUndefined();
+    expect(DeviceSwapsSchema.safeParse([{ slug: "work", phase: "cutover", at: 5 }]).success).toBe(false);
+});

package/src/schemas/device-swaps.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+// WHAT `ic sandbox swaps --json` ANSWERS, one row per sandbox whose channel record names a swap in flight or on
+// probation. `ic` is the one reader of its own swap records: `cutoverInProgress` is its verdict (a live ic run's
+// heartbeat, `swap_alive`, is fresh), and every other process asks for it here instead of judging the record again. The
+// command reads ic's home and not Docker, so it answers while Docker is down. golden/swap-verdicts.json holds each
+// record's row, and ic's Rust test and the machine agent's tests both read it.
+
+// Read loosely: a `phase` a newer ic adds is still a swap going on, and a field of an unexpected shape is a field that
+// is not there. A row that lacks its identity or its verdict is no row at all (the caller falls back to the records).
+export const DeviceSwapSchema = z.looseObject({
+    slug: z.string().min(1),
+    // ic's word: `cutover` (the old container is parked, the new one not yet proven) or `probation` (it is being watched).
+    phase: z.string().min(1),
+    // When the cutover began, epoch milliseconds.
+    at: z.number().int().nonnegative(),
+    // The last heartbeat of the ic run doing the cutover.
+    alive: z.number().int().nonnegative().optional().catch(undefined),
+    // When a probation ends and the parked container is let go.
+    probationUntil: z.number().int().nonnegative().optional().catch(undefined),
+    // ic's verdict at the moment it answered: this cutover is being done right now by a live ic run.
+    cutoverInProgress: z.boolean(),
+});
+export type DeviceSwap = z.infer<typeof DeviceSwapSchema>;
+
+export const DeviceSwapsSchema = z.array(DeviceSwapSchema);

package/src/schemas/environment.ts

@@ -216,3 +216,7 @@ export const BundleExportSchema = z.object({
 });
 export type BundleExport = z.infer<typeof BundleExportSchema>;
 export const BundleExportsSchema = z.object({ exports: z.array(BundleExportSchema) });
+// POST /bundles names the export it started, which fills in as it packs.
+export const BundleStartedSchema = z.object({ name: z.string() });
+// POST /bundles/ticket: the short-lived credential a download navigation carries, since it cannot send a bearer header.
+export const BundleTicketSchema = z.object({ ticket: z.string(), expiresAt: z.number() });

package/src/schemas/members.ts

@@ -8,6 +8,10 @@ export const MemberSchema = z.object({
     email: z.string().describe("Who, lowercased."),
     role: GrantedRoleSchema.describe("The tier they were granted."),
     areas: z.array(z.string()).optional().describe("The areas they are fenced to. Absent means the whole workspace."),
+    emailSignIn: z
+        .boolean()
+        .optional()
+        .describe("Whether they may sign in with an email code the platform confirmed, rather than only with Google or a passkey. Absent means no."),
 });
 export type Member = z.infer<typeof MemberSchema>;
 
@@ -22,10 +26,14 @@ export type MembersRoster = z.infer<typeof MembersRosterSchema>;
 
 // POST /members: a grant is a role decision, so the role is required. Areas are optional, their absence being the whole
 // workspace; a writer and a guest are refused without them, since for those two tiers the fence is the tier.
+// `emailSignIn` lets the platform's identity assertion open this sandbox for them (policy/identity-assertion.ts): true
+// allows it, false takes it back, absent keeps what the row already says, so a re-grade from an editor that predates
+// the field never drops it.
 export const MemberGrantSchema = z.object({
     email: z.string(),
     role: GrantedRoleSchema,
     areas: z.array(z.string().min(1)).max(20).optional(),
+    emailSignIn: z.boolean().optional(),
 });
 export type MemberGrant = z.infer<typeof MemberGrantSchema>;
 

package/src/schemas/needs.ts

@@ -333,6 +333,38 @@ export const ConversationGrantSchema = z.object({
 });
 export type ConversationGrant = z.infer<typeof ConversationGrantSchema>;
 
+// A yes that names no conversation: it applies to the whole sandbox, so it is listed beside the per-conversation ones and
+// taken back from the same place (docs/architecture/needs.md). Each is kept off the workspace, where no agent writes.
+export const OWNER_GRANT_KINDS = ["command-policy", "hook-set", "extension"] as const;
+export const OwnerGrantKindSchema = z.enum(OWNER_GRANT_KINDS);
+export type OwnerGrantKind = z.infer<typeof OwnerGrantKindSchema>;
+
+export const OwnerGrantSchema = z.discriminatedUnion("kind", [
+    // A permission card's "Always: <line>" on a command: the line joins the owner's policy for the safety judge, in every
+    // conversation, until somebody takes it back.
+    z.object({
+        kind: z.literal("command-policy"),
+        line: z.string().describe("The policy line the judge reads, exactly as it was accepted on the card."),
+        at: z.number().describe("When it was allowed, in milliseconds."),
+        by: z.string().optional().describe("Who allowed it, off the verified reply."),
+    }),
+    // A set of Claude Code hooks approved by its digest (guard/hook-approvals.ts): turns run its hooks until it is taken back.
+    z.object({
+        kind: z.literal("hook-set"),
+        digest: z.string().describe("The set's fingerprint, what taking it back names."),
+        hooks: z.array(z.string()).describe("Each hook in the set in the daemon's words: when it runs and what it runs."),
+        at: z.number().describe("When it was approved, in milliseconds."),
+    }),
+    // A workspace extension approved for the powers it declared then (extensions/extension-approvals.ts).
+    z.object({
+        kind: z.literal("extension"),
+        id: z.string().describe("The extension, by its publisher.name id."),
+        powers: z.array(z.string()).describe("What it was approved to do, one power per entry."),
+        at: z.number().describe("When it was approved, in milliseconds."),
+    }),
+]);
+export type OwnerGrant = z.infer<typeof OwnerGrantSchema>;
+
 // Every yes still standing, by conversation: what its grants widened past its persona or area, and which gated
 // credentials a named person released to it. Reviewed and taken back from Needs you.
 export const StandingGrantsSchema = z.object({
@@ -353,10 +385,18 @@ export const StandingGrantsSchema = z.object({
                 .describe("Gated credentials released to it, until somebody takes one back."),
         }),
     ),
+    ownerWide: z
+        .array(OwnerGrantSchema)
+        .default([])
+        .describe("Yeses that name no conversation: command policy lines allowed with Always, approved hook sets, approved workspace extensions."),
+    unreadable: z
+        .array(OwnerGrantKindSchema)
+        .default([])
+        .describe("Kinds of owner-wide yes whose record this build could not read: none of that kind stands, and none is listed, until the file is fixed."),
 });
 export type StandingGrants = z.infer<typeof StandingGrantsSchema>;
 
-export const GrantRevokeSchema = z.object({
+export const ConversationGrantRevokeSchema = z.object({
     conversationId: z.string(),
     kind: z
         .enum(["capability", "folder", "shelf", "release", "install", "secret", "everything", "rule"])
@@ -368,6 +408,16 @@ export const GrantRevokeSchema = z.object({
         .describe("The capability id, folder, shelf, released credential or secret it named, or the rule's identity; empty for installs and everything."),
     capability: z.string().optional().describe("For a rule, the capability whose rule it is; a rule's identity alone does not say."),
 });
+export type ConversationGrantRevoke = z.infer<typeof ConversationGrantRevokeSchema>;
+
+// Taking back a yes that names no conversation: the kind says which list, `what` which entry of it.
+export const OwnerGrantRevokeSchema = z.object({
+    kind: OwnerGrantKindSchema.describe("Which kind of owner-wide yes: a command policy line, an approved hook set, or an approved extension."),
+    what: z.string().min(1).describe("The policy line, the hook set's digest, or the extension's id."),
+});
+export type OwnerGrantRevoke = z.infer<typeof OwnerGrantRevokeSchema>;
+
+export const GrantRevokeSchema = z.union([ConversationGrantRevokeSchema, OwnerGrantRevokeSchema]);
 export type GrantRevoke = z.infer<typeof GrantRevokeSchema>;
 
 // The file the needs store keeps: every open need and the recent closed ones, by id.

package/src/schemas/restart-intent.test.ts

@@ -0,0 +1,45 @@
+import { ReadRestartIntentSchema, RESTART_ACTIONS, RESTART_INITIATORS, RESTART_SIDES, type RestartIntent, RestartIntentSchema } from "./restart-intent.js";
+
+// The one schema every writer of /history/logs/restart-intent.json is held to; the daemon's golden/host-files.json carries its
+// enumerations and an example for ic's Rust and the keeper's test to read back (host-files.test.ts).
+
+const intent: RestartIntent = {
+    at: "2026-10-05T22:45:30.000Z",
+    by: "keeper",
+    host: "rog",
+    side: "wsl",
+    action: "restart",
+    reason: "the sandbox's /health stopped answering",
+    checks: ["health"],
+};
+
+test("an intent a writer may leave reads back, to the field", () => {
+    expect(RestartIntentSchema.parse(intent)).toEqual(intent);
+    expect(RestartIntentSchema.parse({ at: intent.at, by: "daemon", action: "stop", reason: "idle-stop" })).toEqual({ at: intent.at, by: "daemon", action: "stop", reason: "idle-stop" });
+});
+
+test.each([
+    ["an initiator nobody is", { ...intent, by: "netd" }],
+    ["an action nothing does", { ...intent, action: "kill" }],
+    ["a side no computer has", { ...intent, side: "macos" }],
+    ["a moment that is not one", { ...intent, at: "yesterday" }],
+    ["no reason", { at: intent.at, by: "ic", action: "restart" }],
+])("a writer cannot leave %s", (_what, body) => {
+    expect(RestartIntentSchema.safeParse(body).success).toBe(false);
+});
+
+// A writer newer than the daemon reading it: still an intent, in the words it used.
+test("the daemon reads what a newer writer names, and only an unreadable moment or a missing reason is no intent", () => {
+    const newer = { at: intent.at, by: "netd", side: "macos", action: "kill", reason: "stuck" };
+    expect(ReadRestartIntentSchema.parse(newer)).toEqual(newer);
+    expect(ReadRestartIntentSchema.safeParse({ ...newer, at: "yesterday" }).success).toBe(false);
+    expect(ReadRestartIntentSchema.safeParse({ at: intent.at, by: "", action: "kill", reason: "x" }).success).toBe(false);
+});
+
+test("the enumerations are the words every writer and the reader share", () => {
+    expect([RESTART_INITIATORS, RESTART_ACTIONS, RESTART_SIDES]).toEqual([
+        ["owner", "daemon", "ic", "keeper", "desktop"],
+        ["restart", "stop", "update", "swap", "reshape", "recreate", "rebuild"],
+        ["wsl", "windows", "linux", "mac"],
+    ]);
+});

package/src/schemas/restart-intent.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+
+// WHY THE SANDBOX IS ABOUT TO GO DOWN, as the file whoever restarts it leaves on its volume (/history/logs/restart-intent.json).
+//
+// Four writers, three languages: the daemon itself (an idle-stop, an update when quiet, an owner's restart from the Devices
+// card), `ic` (Rust: the verb it is about to run), the machine agent's keeper (TypeScript: the restart a repair makes), and the
+// desktop app. The daemon reads it at its next boot and files the previous run's end against it (boot/restarts/restart-record.ts).
+// One schema, so a writer cannot name an initiator, an action or a side the reader's words do not have: `ic`'s Rust and the
+// keeper's TypeScript are held to it by the daemon's golden/host-files.json (host-files.test.ts writes the enumerations and an
+// example from here; ic's host_files.rs and the keeper's test read them back).
+
+// Who acted. `owner` is a person at the editor, `daemon` the sandbox itself, `ic` a person running ic or the desktop app's ic,
+// `keeper` the machine agent's unattended round, `desktop` the desktop app's own restart.
+export const RESTART_INITIATORS = ["owner", "daemon", "ic", "keeper", "desktop"] as const;
+// What is about to happen to the container: `swap` is onto another version that is not the channel's newest (a rollback, or
+// going back from a failed update).
+export const RESTART_ACTIONS = ["restart", "stop", "update", "swap", "reshape", "recreate", "rebuild"] as const;
+// The side of a computer the initiator runs on.
+export const RESTART_SIDES = ["wsl", "windows", "linux", "mac"] as const;
+
+// What a writer puts in the file.
+export const RestartIntentSchema = z.object({
+    // ISO time it was written, right before the stop it announces.
+    at: z.string().refine((at) => Number.isFinite(Date.parse(at)), "an ISO moment"),
+    by: z.enum(RESTART_INITIATORS),
+    // The machine the initiator runs on, and which side of it.
+    host: z.string().optional(),
+    side: z.enum(RESTART_SIDES).optional(),
+    action: z.enum(RESTART_ACTIONS),
+    reason: z.string(),
+    // For a keeper's repair: the health checks that failed and made it act.
+    checks: z.array(z.string()).optional(),
+});
+export type RestartIntent = z.infer<typeof RestartIntentSchema>;
+export type RestartInitiator = RestartIntent["by"];
+export type RestartAction = RestartIntent["action"];
+export type RestartSide = NonNullable<RestartIntent["side"]>;
+
+// What the daemon makes of a file it reads. Lenient where a writer newer than this daemon may be ahead of it: an initiator, an
+// action or a side it does not know still says more than no intent at all, so those three read as the words they were. `at` is
+// held to its meaning, since freshness is decided on it.
+export const ReadRestartIntentSchema = RestartIntentSchema.extend({
+    by: z.string().min(1),
+    side: z.string().optional(),
+    action: z.string().min(1),
+});
+export type ReadRestartIntent = z.infer<typeof ReadRestartIntentSchema>;

package/src/schemas/settings.ts

@@ -10,6 +10,7 @@ import { LimitHandoffSchema } from "./providers/handoff.js";
 import { SessionsPlacementSchema } from "./offload.js";
 import { LimitPolicySchema, RetryPolicySchema, RoomPolicySchema } from "./turn-break.js";
 import { ZoneSchema } from "../time/zone.js";
+import { VoiceSettingsSchema } from "./voice.js";
 // Which prompt base the agent runs before this turn composes anything on top: Intentic's own (default), Claude Code's
 // preset, or the owner's text. Declared out here since both the daemon and the browser branch on it.
 // Kept in the daemon's auth root, never in SandboxSettings: an agent cannot edit its execution boundary.
@@ -560,6 +561,11 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "How many failures in a row before an automation switches itself off. Zero means never, which is the default, because the failure is not always the automation's fault and a job disabled at three in the morning is one nobody re-enables. Only real errors count: a guard deciding there was nothing to do, or the sandbox dying mid-run, say nothing about the automation.",
         ),
+    // Speaking replies aloud (schemas/voice.ts): which voice speaks each language, and whether a hands-free turn is
+    // answered out loud. Read by the daemon's voice engine on every utterance, so a change is heard on the next one.
+    voice: VoiceSettingsSchema.prefault({}).describe(
+        "How the agent's replies are spoken aloud: whether a hands-free conversation is answered out loud, which voice speaks each language, and a speech provider of your own if you connected one.",
+    ),
     // Defaults all-allow, so a fresh sandbox behaves as it did before this floor existed.
     admission: AdmissionPolicySchema.prefault({}).describe(
         "Whether work started from outside may run, per kind of trigger: let it, hold it for approval, or refuse it. Composes with each automation's own setting, and the stricter of the two wins, so holding every visitor's message needs no edit to each automation.",

package/src/schemas/short-codes.ts

@@ -28,6 +28,17 @@ export const PairingAnswerSchema = z.object({
 });
 export type PairingAnswer = z.infer<typeof PairingAnswerSchema>;
 
+// What POST /system/<door>/pair answers on any peer door (device, browser, phone, runner): the token, and the short code
+// only the device door mints beside it. `expiresIn` is optional on read since a reader meets daemons older than the
+// field; the editor then shows the token without a countdown.
+export const PeerPairingAnswerSchema = PairingAnswerSchema.partial({ code: true, expiresIn: true });
+export type PeerPairingAnswer = z.infer<typeof PeerPairingAnswerSchema>;
+
+// POST /system/sync/pair: the pairing with the mode the daemon granted, which may be less than the one asked for (a
+// member's "sync" comes back "mirror"), and the code that stands for it.
+export const SyncPairAnswerSchema = PeerPairingAnswerSchema.extend({ mode: z.enum(["sync", "mirror"]).optional() });
+export type SyncPairAnswer = z.infer<typeof SyncPairAnswerSchema>;
+
 // POST /system/sync/pair's optional body: the person's chosen local folder and takeover, handed out with the code.
 // It goes to their own sandbox, never the platform.
 export const SyncPairRequestSchema = z.object({

package/src/schemas/speech.ts

@@ -66,6 +66,10 @@ export const SpeechStatusSchema = z.object({
 });
 export type SpeechStatus = z.infer<typeof SpeechStatusSchema>;
 
+// POST /speech/transcribe: one phrase as WAV in, its words out; empty when it held none.
+export const SpeechTranscriptSchema = z.object({ text: z.string() });
+export type SpeechTranscript = z.infer<typeof SpeechTranscriptSchema>;
+
 // GET /speech/stream, a WebSocket: the composer cuts the microphone into phrases itself (its silence segmenter) and
 // streams each one as it is spoken. A text frame `begin` opens phrase `id`; binary frames that follow are its audio,
 // 16 kHz mono s16le; `end` closes it, keeping its first `keep` samples (the trailing pause trimmed off); `drop`