@intentic/sandbox-contract 1.332.0 → 1.333.1

package/src/ids/project-dir.ts

@@ -56,6 +56,20 @@ export const projectDirNameFor = (folderBasename: string): string => {
     return RESERVED_PROJECT_DIR_NAMES.includes(name) ? `${name}-project` : name;
 };
 
+// The names a folder may take in this computer's sandbox, best first: its own name, then its parent's name in front of
+// it, then its grandparent's too (`app`, `code-app`, `radar-code-app`), each one `isProjectDirName` accepts and none
+// twice. The desktop app takes the first one free (machine_sandbox.rs `unique_name`) and numbers only past all of them,
+// so a second folder called `app` reads as `code-app`, which says which one it is, rather than `app-2` (2026-10-12). A
+// drive (`C:`) and a network share's server and share (`\\server\share`, `\\wsl.localhost\<distro>`) are where a folder
+// is, not what it is called, so they never lend a name.
+export const projectDirCandidates = (hostPath: string): string[] => {
+    const unc = /^[\\/]{2}[^\\/]/.test(hostPath);
+    const segments = hostPath.split(/[\\/]+/).filter((segment) => segment !== "");
+    const named = (unc ? segments.slice(2) : segments).filter((segment) => !/^[A-Za-z]:$/.test(segment));
+    const candidates = [1, 2, 3].flatMap((depth) => (named.length < depth ? [] : [projectDirNameFor(named.slice(-depth).join("-"))]));
+    return [...new Set(candidates)];
+};
+
 // Where a project folder lands in the sandbox, and the name back out of such a path: exactly `<root>/<name>`, anything
 // else (a deeper path, a trailing slash, a reserved name) is not a project dir.
 export const projectRemoteDir = (name: string): string => `${WORKSPACE_ROOT}/${name}`;

package/src/ids/tunnel-ids.test.ts

@@ -1,5 +1,16 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { repoRoot } from "@intentic/constants/node";
 import { hostSshIdFromToken, PORT_SLOT_COUNT, portSlotsFromToken, sandboxIdFromToken } from "./tunnel-ids.js";
 
+// The digests every language spells again (ic's util.rs, connect-host.ps1, sandbox-run's Web Crypto twin) are held to the
+// run contract's names.fixture.json, which each of them is tested against. SAFETY: the fixture is this repository's own
+// file; the assertions below fail on any field it lacks.
+const SHARED = JSON.parse(readFileSync(join(repoRoot(import.meta.url), "_shared/sandbox-run/src/names.fixture.json"), "utf8")) as {
+    readonly sandboxIds: { readonly vectors: { readonly token: string; readonly id: string }[] };
+    readonly hostSshIds: { readonly vectors: { readonly token: string; readonly hostName: string; readonly id: string }[] };
+};
+
 const TOKEN = "connect-token-one";
 const OTHER = "connect-token-two";
 
@@ -35,3 +46,22 @@ test("slots are not derivable from the sandbox id: only from the token behind it
     expect(portSlotsFromToken(TOKEN)).not.toContain(id);
     expect(portSlotsFromToken(TOKEN).some((slot) => slot.length === 1)).toBe(false);
 });
+
+test.each(SHARED.sandboxIds.vectors)("the sandbox id of $token is $id, the digest ic and the browser derive too", ({ token, id }) => {
+    expect(sandboxIdFromToken(token)).toBe(id);
+});
+
+test.each(SHARED.hostSshIds.vectors)("the host ssh id of $token on $hostName is $id", ({ token, hostName, id }) => {
+    expect(hostSshIdFromToken(token, hostName)).toBe(id);
+});
+
+// connect-host.ps1 digests a server's id itself when a code's answer carries no HOST_ID, and no PowerShell runs in the
+// suites. What can be held is its source: the same salted input (`<token>:<host name>`), the same hash, the same cut, over
+// UTF-8 bytes, so a change to one half reads as a change to the other here.
+test("connect-host.ps1 digests the host ssh id the way hostSshIdFromToken does", () => {
+    const script = readFileSync(join(repoRoot(import.meta.url), "_site/site/public/scripts/connect-host.ps1"), "utf8");
+    expect(script).toContain("$slugInput = '{0}:{1}' -f $ConnectToken, $HostName");
+    expect(script).toContain("[System.Security.Cryptography.SHA256]::Create()");
+    expect(script).toContain("[System.Text.Encoding]::UTF8.GetBytes($slugInput)");
+    expect(script).toContain("-replace '-', '').Substring(0, 12).ToLower()");
+});

package/src/index.ts

@@ -164,6 +164,8 @@ export * from "./models/agent-catalog.js";
 export * from "./policy/capability-env.js";
 export * from "./policy/command-classes.js";
 export * from "./policy/command-run.js";
+export * from "./policy/device-programs.js";
+export * from "./policy/sandbox-power.js";
 export * from "./policy/safety-policy.js";
 export * from "./policy/reserved-servers.js";
 export * from "./policy/credential-material.js";
@@ -205,6 +207,7 @@ export * from "./policy/persona-home.js";
 export * from "./schemas/agents.js";
 export * from "./schemas/speaker.js";
 export * from "./schemas/speech.js";
+export * from "./schemas/voice.js";
 export * from "./schemas/approvals.js";
 export * from "./schemas/automations.js";
 export * from "./schemas/agents-list.js";
@@ -215,6 +218,7 @@ export * from "./schemas/providers/claude-gate.js";
 export * from "./schemas/codebase-health.js";
 export * from "./schemas/context-trim.js";
 export * from "./schemas/devices.js";
+export * from "./schemas/device-swaps.js";
 export * from "./schemas/project-delivery.js";
 export * from "./schemas/device-artifacts.js";
 export * from "./schemas/run-targets.js";
@@ -265,6 +269,7 @@ export * from "./schemas/short-codes.js";
 export * from "./schemas/system-prompt.js";
 export * from "./schemas/system.js";
 export * from "./schemas/state-plan.js";
+export * from "./schemas/restart-intent.js";
 export * from "./schemas/updates.js";
 export * from "./schemas/terminal.js";
 export * from "./schemas/turn-break.js";
@@ -280,11 +285,13 @@ export * from "./schemas/workspace/workspace-repos.js";
 export * from "./schemas/workspace/workspace-search.js";
 export * from "./schemas/workspace/workspace-setup.js";
 export * from "./schemas/workspace/workspace-tree.js";
+export * from "./schemas/workspace/workspace-upload.js";
 export * from "./state/arrival.js";
 export * from "./state/definition.js";
 export * from "./policy/search-globs.js";
 export * from "./state/starter.js";
 export * from "./text/title.js";
+export * from "./state/update-probation.js";
 export * from "./state/versions.js";
 export * from "./text/model-answer.js";
 export * from "./text/shell-regions.js";

package/src/models/model-roles.ts

@@ -73,6 +73,16 @@ export const MODEL_ROLES = [
         icon: "align-left",
         setup: "low",
     },
+    {
+        // Reads one finished reply (and the ask it answered) and writes what a person hears in hands-free voice: a few
+        // short sentences, never markdown. A fast model matters more than a strong one, since the person is waiting.
+        id: "spoken-reply",
+        label: "Spoken replies",
+        blurb: "The few sentences you hear when you talk to the agent hands-free: what it did and what it needs from you, while the full reply stays on screen.",
+        kind: "helper",
+        icon: "volume-up",
+        setup: "low",
+    },
     {
         // One reading answering both halves of "what does this chat open on": an offered `provider:model` line with an
         // effort and an account, and a persona id, each a classification over a fixed list rather than free text. The

package/src/policy/control-scopes.ts

@@ -36,3 +36,30 @@ export const CONTROL_SCOPE_REACH: readonly ControlScopeReach[] = [
         note: "Separate because the usual arrangement is a program that works and a person who decides.",
     },
 ];
+
+// One control token as the roster lists it: everything but the secret, which the daemon keeps only as a hash.
+export const ControlTokenSummarySchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    scope: ControlScopeSchema,
+    createdAt: z.number(),
+    // The owner or maintainer who minted it, so the roster says whose decision each token was.
+    createdBy: z.string().optional(),
+    // Epoch ms after which the token is refused; absent means it lives until revoked.
+    expiresAt: z.number().optional(),
+    // Epoch ms of the last authorized request, coarse on purpose; absent means never used.
+    lastUsedAt: z.number().optional(),
+});
+export type ControlTokenSummary = z.infer<typeof ControlTokenSummarySchema>;
+export const ControlTokensListSchema = z.object({ tokens: z.array(ControlTokenSummarySchema) });
+
+// POST /system/control/tokens: scope is required, never defaulted; expiry is optional and absent means never.
+export const ControlTokenMintSchema = z.object({
+    scope: ControlScopeSchema,
+    label: z.string().optional(),
+    expiresAt: z.number().optional(),
+});
+export type ControlTokenMint = z.infer<typeof ControlTokenMintSchema>;
+// The raw token, shown exactly once.
+export const ControlTokenMintedSchema = z.object({ id: z.string(), token: z.string() });
+export type ControlTokenMinted = z.infer<typeof ControlTokenMintedSchema>;

package/src/policy/device-programs.ts

@@ -0,0 +1,137 @@
+import { z } from "zod";
+
+// WHICH DEVICE TOOLS CARRY A PROGRAM (2026-10-12). A command on somebody's own computer arrives by more doors than
+// `run_command`: `app_start` starts a program with arguments, `open` starts whatever its target names (on Linux a
+// target with spaces is split into a program and arguments and spawned), `android_shell` hands a line to a phone's
+// shell, and the input tools put text where a terminal could run it. The daemon's gate used to know two of those by
+// name, the machine's own checks a different few, and `app_start program=powershell args=[…]` slipped past the judge, the
+// card and the unattended refusal. This is the one table both ends read: the tool, and how to lift the command line
+// out of its arguments. A device tool that carries a program is added here, or the machine's test says it is missing.
+
+/**
+ * What a call's program is, which decides how it is read:
+ * - `command`: a command line for the machine's own shell, or a program started with arguments; judged as `run_command`.
+ * - `phone-command`: a line for an attached phone's shell, judged as the `adb shell` program the machine runs for it.
+ * - `app-launch`: an application, URL or document started with nothing to interpret; the ordinary GUI launch, low risk.
+ * - `typed`: text put where a terminal could run it (typed, pasted, set into a field).
+ */
+export type ProgramKind = "command" | "phone-command" | "app-launch" | "typed";
+
+/** The program a tool call carries, as the classifier and the judge read it. */
+export interface ProgramReading {
+    readonly tool: string;
+    readonly kind: ProgramKind;
+    /** The command line as a shell would read it. */
+    readonly commandLine: string;
+}
+
+// The fields of every tool in the table below. One that is the wrong type reads as absent rather than failing the
+// parse: such a call never runs, since the device checks its input against its own schema before anything else.
+export const ProgramArgumentsSchema = z.looseObject({
+    command: z.string().optional().catch(undefined),
+    serial: z.string().optional().catch(undefined),
+    program: z.string().optional().catch(undefined),
+    args: z.array(z.string()).optional().catch(undefined),
+    target: z.string().optional().catch(undefined),
+    action: z.string().optional().catch(undefined),
+    text: z.string().optional().catch(undefined),
+    value: z.string().optional().catch(undefined),
+});
+export type ProgramArguments = z.infer<typeof ProgramArgumentsSchema>;
+
+interface ProgramCarrier {
+    readonly tool: string;
+    /** In words: where the program is in the arguments. */
+    readonly carries: string;
+    readonly read: (args: ProgramArguments) => Omit<ProgramReading, "tool"> | undefined;
+}
+
+const present = (value: string | undefined): string | undefined => (value === undefined || value.trim() === "" ? undefined : value);
+
+// A program by the name it is known by (`rm`, `powershell`), not the path or the `.exe` it was started through.
+const programName = (program: string): string => (program.split(/[/\\]/).at(-1) ?? program).replace(/\.exe$/i, "");
+
+/**
+ * The program and its arguments as the one command line they amount to: the program by its name, each argument quoted
+ * only where a shell would need it, so the line reads the way a person would type it.
+ */
+export const commandLineOf = (program: string, args: readonly string[]): string =>
+    [
+        programName(program),
+        ...args.map((arg) => (arg === "" || /[\s'"|;&<>()$`\\]/.test(arg) ? (arg.includes("'") ? `"${arg}"` : `'${arg}'`) : arg)),
+    ].join(" ");
+
+// A phone's serial as adb prints one (a USB serial, `ip:port`, an mDNS name), and nothing else: a serial is spliced into
+// the program judged below, where a `#` or a quote in it could make the command after it read as inert.
+const ADB_SERIAL = /^[\w.:-]+$/;
+
+// A URL, or `www.`/`mailto:` which the machine opens the same way (desktop-automation's looksLikeUrl).
+const URL_TARGET = /^(?:[a-z][a-z0-9+.-]*:\/\/|www\.|mailto:)/i;
+
+const typedBy = (tool: string, action: string, field: "text" | "value"): ProgramCarrier => ({
+    tool,
+    carries: `${field}, when action is ${action}`,
+    read: (args) => {
+        const typed = args.action === action ? present(args[field]) : undefined;
+        return typed === undefined ? undefined : { kind: "typed", commandLine: typed };
+    },
+});
+
+/** Every device tool that carries a program. */
+export const DEVICE_PROGRAM_TOOLS: readonly ProgramCarrier[] = [
+    {
+        tool: "run_command",
+        carries: "command",
+        read: ({ command }) => {
+            const line = present(command);
+            return line === undefined ? undefined : { kind: "command", commandLine: line };
+        },
+    },
+    {
+        tool: "android_shell",
+        carries: "command, run as `adb [-s serial] shell <command>`",
+        read: ({ command, serial }) => {
+            const line = present(command);
+            if (line === undefined) {
+                return undefined;
+            }
+            return { kind: "phone-command", commandLine: `adb ${serial !== undefined && ADB_SERIAL.test(serial) ? `-s ${serial} ` : ""}shell ${line}` };
+        },
+    },
+    {
+        tool: "app_start",
+        carries: "program and args",
+        read: ({ program, args }) => {
+            const started = present(program);
+            if (started === undefined) {
+                return undefined;
+            }
+            // With nothing to interpret it is a launch; with arguments it is a command by another door, whatever the
+            // program is: `rm -rf ~`, `curl … | sh` and `powershell -c …` read the same here as in run_command.
+            return { kind: args === undefined || args.length === 0 ? "app-launch" : "command", commandLine: commandLineOf(started, args ?? []) };
+        },
+    },
+    {
+        tool: "open",
+        carries: "target",
+        read: ({ target }) => {
+            const opened = present(target);
+            if (opened === undefined) {
+                return undefined;
+            }
+            // A URL or a single word (an application name, a file path) is opened. A target with spaces that is not a URL
+            // can be split into a program and arguments and spawned, so it is read as the command it may be.
+            return { kind: URL_TARGET.test(opened) || !/\s/.test(opened.trim()) ? "app-launch" : "command", commandLine: opened };
+        },
+    },
+    typedBy("device", "type", "text"),
+    typedBy("android_act", "type", "text"),
+    typedBy("clipboard", "write", "text"),
+    typedBy("ui_act", "set_value", "value"),
+];
+
+/** The program a `tools/call` of `tool` carries, or undefined for a tool that carries none or a call with nothing in the place the table looks. */
+export const programInCall = (tool: string, args: ProgramArguments): ProgramReading | undefined => {
+    const read = DEVICE_PROGRAM_TOOLS.find((carrier) => carrier.tool === tool)?.read(args);
+    return read === undefined ? undefined : { tool, ...read };
+};

package/src/policy/identity-assertion.ts

@@ -0,0 +1,130 @@
+import { createPrivateKey, createPublicKey, randomBytes, sign as edSign, verify as edVerify } from "node:crypto";
+import { z } from "zod";
+import { SANDBOX_ID } from "../ids/tunnel-ids.js";
+
+// The platform's signed word that a signed-in person controls an email address, spent on one sandbox's daemon. It is how
+// an address no identity provider vouches for (a custom domain on Fastmail, Proton, a company's own mail server) reaches
+// a sandbox: the platform confirmed the address by mailing it a code, and nobody else could. The daemon accepts it only
+// where its owner opted in for that person (the owner record or the member row says `emailSignIn`), and on hosted
+// machines, where the platform already holds the machine. Signed with a key of its own (IDENTITY_SIGNING_KEY), never the
+// ingress key, so neither credential can stand in for the other.
+
+const ASSERTION_PREFIX = "pa1";
+
+// One round trip to the daemon and a retry; a lifted assertion is dead before anyone reads the log it sat in.
+export const IDENTITY_ASSERTION_TTL_MS = 2 * 60_000;
+// The longest life a daemon accepts whatever the claim says, so a platform minting with a wrong clock or a wrong ttl
+// still cannot hand out a credential that outlives a replay window the daemon can hold in memory.
+export const IDENTITY_ASSERTION_MAX_TTL_MS = 5 * 60_000;
+
+// The env var that carries the platform's identity key on a hosted machine, which boots before its first announce. A
+// sandbox on its owner's own machine learns the same key from the announce answer (`AnnounceAcceptedSchema`).
+export const ENV_PLATFORM_IDENTITY_KEY = "PLATFORM_IDENTITY_KEY";
+
+// How the platform confirmed the address it vouches for: a code it mailed, or a Google sign-in it verified.
+export const IdentityAssertionMethodSchema = z.enum(["email", "google"]);
+export type IdentityAssertionMethod = z.infer<typeof IdentityAssertionMethodSchema>;
+
+// The signed claim, times in seconds like the owner ticket's. `nonce` is unique per mint: the daemon spends each once.
+export interface IdentityAssertion {
+    readonly sandboxId: string;
+    readonly email: string;
+    readonly method: IdentityAssertionMethod;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+    readonly nonce: string;
+}
+
+const base64url = (bytes: Buffer): string => bytes.toString("base64url");
+
+// The prefix is part of what is signed, so an assertion is never a valid signature over anything else the same key
+// might one day sign, and an owner ticket or a grant (which sign their bare payload) is never an assertion.
+const signedBytes = (payload: Buffer): Buffer => Buffer.concat([Buffer.from(`${ASSERTION_PREFIX}.`, "utf8"), payload]);
+
+export const isIdentityAssertion = (bearer: string): boolean => bearer.startsWith(`${ASSERTION_PREFIX}.`);
+
+export const mintIdentityAssertion = (
+    privateKeyPem: string,
+    claim: {
+        readonly sandboxId: string;
+        readonly email: string;
+        readonly method: IdentityAssertionMethod;
+        readonly issuedAtMs: number;
+        readonly ttlMs?: number;
+    },
+): string => {
+    if (!SANDBOX_ID.test(claim.sandboxId)) {
+        throw new Error(`an identity assertion names a 12-hex sandbox id, got "${claim.sandboxId}"`);
+    }
+    if (claim.email.trim() === "") {
+        throw new Error("an identity assertion names an address");
+    }
+    const ttlMs = claim.ttlMs ?? IDENTITY_ASSERTION_TTL_MS;
+    if (ttlMs <= 0 || ttlMs > IDENTITY_ASSERTION_MAX_TTL_MS) {
+        throw new Error(`an identity assertion lives at most ${IDENTITY_ASSERTION_MAX_TTL_MS} ms`);
+    }
+    const iat = Math.floor(claim.issuedAtMs / 1000);
+    const exp = Math.floor((claim.issuedAtMs + ttlMs) / 1000);
+    const payload = Buffer.from(
+        JSON.stringify({
+            v: 1,
+            sub: claim.sandboxId,
+            email: claim.email.trim().toLowerCase(),
+            amr: claim.method,
+            iat,
+            exp,
+            jti: base64url(randomBytes(16)),
+        }),
+        "utf8",
+    );
+    const signature = edSign(null, signedBytes(payload), createPrivateKey(privateKeyPem));
+    return `${ASSERTION_PREFIX}.${base64url(payload)}.${base64url(signature)}`;
+};
+
+// What the signed payload must be, read only after the signature checked out.
+const AssertionPayloadSchema = z.object({
+    v: z.literal(1),
+    sub: z.string().regex(SANDBOX_ID),
+    email: z.string().min(1),
+    amr: IdentityAssertionMethodSchema,
+    iat: z.number(),
+    exp: z.number(),
+    jti: z.string().min(16),
+});
+
+const parsePayload = (payload: Buffer): z.infer<typeof AssertionPayloadSchema> | undefined => {
+    try {
+        return AssertionPayloadSchema.safeParse(JSON.parse(payload.toString("utf8"))).data;
+    } catch {
+        // allow(silent-catch): a payload that is not JSON is an invalid assertion, which undefined is how this says.
+        return undefined;
+    }
+};
+
+// Verifies an assertion against the platform's public key at nowMs; undefined for any way of being invalid (wrong
+// prefix, bad signature, malformed claim, expired, issued in the future, living longer than the daemon allows). The
+// caller checks sandboxId against its own id and spends the nonce.
+export const verifyIdentityAssertion = (publicKeyPem: string, token: string, nowMs: number): IdentityAssertion | undefined => {
+    const [prefix, encodedPayload, encodedSignature, ...rest] = token.split(".");
+    if (prefix !== ASSERTION_PREFIX || encodedPayload === undefined || encodedSignature === undefined || rest.length > 0) {
+        return undefined;
+    }
+    const payload = Buffer.from(encodedPayload, "base64url");
+    try {
+        if (!edVerify(null, signedBytes(payload), createPublicKey(publicKeyPem), Buffer.from(encodedSignature, "base64url"))) {
+            return undefined;
+        }
+    } catch {
+        // allow(silent-catch): a key or signature that does not parse verifies nothing: the assertion is invalid, said as undefined.
+        return undefined;
+    }
+    const claim = parsePayload(payload);
+    if (claim === undefined) {
+        return undefined;
+    }
+    // A minute of clock skew either way, as the daemon allows Google's tokens; never a claim from further ahead.
+    if (claim.exp * 1000 <= nowMs || claim.iat * 1000 > nowMs + 60_000 || (claim.exp - claim.iat) * 1000 > IDENTITY_ASSERTION_MAX_TTL_MS) {
+        return undefined;
+    }
+    return { sandboxId: claim.sub, email: claim.email, method: claim.amr, issuedAt: claim.iat, expiresAt: claim.exp, nonce: claim.jti };
+};