@intentic/sandbox-contract 1.337.0 → 1.339.0

package/src/schemas/privacy.ts

@@ -44,6 +44,183 @@ export const PRIVACY_TRUSTED_MAX = 200;
 export const PRIVACY_ALLOW_MAX = 1000;
 export const PRIVACY_CONVERSATIONS_MAX = 200;
 
+// The owner's own additions to what the shield finds. The policy travels whole on every write, so each is kept to what a
+// person types or pastes; a dataset of thousands of values is taught to the vault instead (privacy learn).
+export const PRIVACY_OWN_LISTS_MAX = 20;
+export const PRIVACY_OWN_LIST_WORDS_MAX = 2000;
+export const PRIVACY_WORD_MAX = 60;
+export const PRIVACY_RULES_MAX = 50;
+export const PRIVACY_RULE_TERMS_MAX = 1000;
+export const PRIVACY_TERM_MAX = 200;
+export const PRIVACY_PATTERN_MAX = 500;
+export const PRIVACY_TITLE_MAX = 80;
+
+// What a word on a name list says about a name: a first name or a surname (a name when the two stand together), a word
+// that is a name only beside other evidence, a title after which a capitalized word is a person, or never part of one.
+export const PrivacyNameListKindSchema = z.enum(["first-name", "surname", "ambiguous", "title", "never"]);
+export type PrivacyNameListKind = z.infer<typeof PrivacyNameListKindSchema>;
+
+// inflected: every Polish grammatical form of a listed word ("Kasia", "Kasi", "Kasię"); as-written: only as listed.
+export const PrivacyNameMatchingSchema = z.enum(["inflected", "as-written"]);
+export type PrivacyNameMatching = z.infer<typeof PrivacyNameMatchingSchema>;
+
+// Ids the editor mints for the owner's lists and rules: stable across renames, so a write never confuses two of them.
+const OwnIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,39}$/u);
+
+export const PrivacyOwnNameListSchema = z.object({
+    id: OwnIdSchema,
+    title: z.string().min(1).max(PRIVACY_TITLE_MAX),
+    kind: PrivacyNameListKindSchema,
+    matching: PrivacyNameMatchingSchema.default("as-written"),
+    words: z
+        .array(z.string().min(1).max(PRIVACY_WORD_MAX))
+        .max(PRIVACY_OWN_LIST_WORDS_MAX)
+        .default([])
+        .describe("One word each, in any case: the list is read as the built-in lists are."),
+    on: z.boolean().default(true),
+});
+export type PrivacyOwnNameList = z.infer<typeof PrivacyOwnNameListSchema>;
+
+export const PrivacyDictionaryPolicySchema = z.object({
+    off: z.array(z.string().min(1).max(64)).max(64).default([]).describe("Built-in name lists switched off, by id (privacy.dictionary names them)."),
+    lists: z
+        .array(PrivacyOwnNameListSchema)
+        .max(PRIVACY_OWN_LISTS_MAX)
+        .default([])
+        .describe("The owner's own name lists, read beside the built-in ones."),
+});
+export type PrivacyDictionaryPolicy = z.infer<typeof PrivacyDictionaryPolicySchema>;
+
+// One of the owner's own rules: what it matches is masked wherever it stands, with no context asked for, as the kind it
+// names. terms: each word or phrase as a whole word, in any case unless matchCase. pattern: a regular expression (with the
+// `u` flag, `i` unless matchCase); a group named `value` masks only that part of a match.
+export const PrivacyRuleMatchSchema = z.enum(["terms", "pattern"]);
+export type PrivacyRuleMatch = z.infer<typeof PrivacyRuleMatchSchema>;
+
+export const PrivacyRuleSchema = z.object({
+    id: OwnIdSchema,
+    title: z.string().min(1).max(PRIVACY_TITLE_MAX),
+    on: z.boolean().default(true),
+    class: PersonalDataClassSchema.describe("The kind what it matches is masked as; switching that kind off stops the rule too."),
+    match: PrivacyRuleMatchSchema,
+    terms: z.array(z.string().min(1).max(PRIVACY_TERM_MAX)).max(PRIVACY_RULE_TERMS_MAX).default([]),
+    // Only its size is held here: whether a pattern is safe to run is judged when it is saved (patternProblem), so a
+    // stored one never turns unreadable because a later build judges more strictly.
+    pattern: z.string().max(PRIVACY_PATTERN_MAX).default(""),
+    matchCase: z.boolean().default(false),
+});
+export type PrivacyRule = z.infer<typeof PrivacyRuleSchema>;
+
+// Why a pattern cannot be saved. Owner-written patterns run on every string bound for an untrusted provider, in the
+// daemon's one thread, so beside not compiling: one that matches empty text masks nothing and only costs, and a repeat
+// inside a repeat (`(a+)+`, `(\w+\s?)*`) can take minutes on one line that almost matches.
+export type PrivacyPatternProblem = "invalid" | "tooLong" | "empty" | "nested";
+
+// The length of a quantifier at `at`, and whether it repeats a variable number of times (`*`, `+`, `{2,}`, `{2,5}`); `?`
+// and `{3}` do not. A lazy `?` after it is part of it.
+const quantifierAt = (source: string, at: number): { readonly length: number; readonly varies: boolean } | undefined => {
+    const char = source[at];
+    let length: number;
+    let varies: boolean;
+    if (char === "*" || char === "+" || char === "?") {
+        length = 1;
+        varies = char !== "?";
+    } else if (char === "{") {
+        const braces = /^\{(\d+)(?:(,)(\d*))?\}/u.exec(source.slice(at));
+        if (braces === null) {
+            return undefined;
+        }
+        const [whole, min = "0", comma, max] = braces;
+        length = whole.length;
+        varies = comma !== undefined && (max === undefined || max === "" || Number(max) > Number(min));
+    } else {
+        return undefined;
+    }
+    return { length: source[at + length] === "?" ? length + 1 : length, varies };
+};
+
+// One step of the walk below: where the next one starts, and what this one was.
+interface PatternStep {
+    readonly next: number;
+    readonly kind: "open" | "close" | "repeat" | "other";
+}
+
+// Past a character class, escapes inside it included.
+const classEnd = (source: string, at: number): number => {
+    let end = at + 1;
+    while (end < source.length && source[end] !== "]") {
+        end += source[end] === "\\" ? 2 : 1;
+    }
+    return end + 1;
+};
+
+// Past a group's opening and its own prefix (`?:`, `?=`, `?<name>`), which is no quantifier.
+const groupStart = (source: string, at: number): number => {
+    if (source[at + 1] !== "?") {
+        return at + 1;
+    }
+    const name = /^\?<(?![=!])[^>]*>/u.exec(source.slice(at + 1));
+    return at + 1 + (name === null ? 2 : name[0].length);
+};
+
+const stepAt = (source: string, at: number): PatternStep => {
+    const char = source[at];
+    if (char === "\\") {
+        return { next: at + 2, kind: "other" };
+    }
+    if (char === "[") {
+        return { next: classEnd(source, at), kind: "other" };
+    }
+    if (char === "(") {
+        return { next: groupStart(source, at), kind: "open" };
+    }
+    if (char === ")") {
+        return { next: at + 1, kind: "close" };
+    }
+    const quantifier = quantifierAt(source, at);
+    return quantifier === undefined
+        ? { next: at + 1, kind: "other" }
+        : { next: at + quantifier.length, kind: quantifier.varies ? "repeat" : "other" };
+};
+
+// Whether a group that repeats a variable number of times holds such a repeat itself: a star height above one.
+const nestedRepeat = (source: string): boolean => {
+    // Per open group, whether something inside it repeats.
+    const open: boolean[] = [];
+    // Whether the step before was the close of a group that held a repeat.
+    let closedRepeating = false;
+    for (let at = 0; at < source.length;) {
+        const step = stepAt(source, at);
+        at = step.next;
+        if (step.kind === "open") {
+            open.push(false);
+        } else if (step.kind === "repeat") {
+            if (closedRepeating) {
+                return true;
+            }
+            open.fill(true);
+        }
+        closedRepeating = step.kind === "close" && (open.pop() ?? false);
+    }
+    return false;
+};
+
+export const patternProblem = (source: string): PrivacyPatternProblem | undefined => {
+    if (source.length > PRIVACY_PATTERN_MAX) {
+        return "tooLong";
+    }
+    let compiled: RegExp;
+    try {
+        compiled = new RegExp(source, "u");
+    } catch {
+        return "invalid";
+    }
+    if (source.trim() === "" || compiled.test("")) {
+        return "empty";
+    }
+    return nestedRepeat(source) ? "nested" : undefined;
+};
+
 // One conversation the owner let an untrusted provider read as it is, granted from that conversation's own composer:
 // narrower than the trusted list, and the way on for a provider whose runtime the gateway cannot sit in front of
 // (Cursor's own wire, an ACP agent, Pi), which the shield otherwise refuses outright.
@@ -78,6 +255,14 @@ export const PrivacyShieldPolicySchema = z.object({
         .max(PRIVACY_CONVERSATIONS_MAX)
         .default([])
         .describe("Providers that may read one conversation's personal data as it is, each granted from that conversation; oldest first."),
+    dictionary: PrivacyDictionaryPolicySchema.default({ off: [], lists: [] }).describe(
+        "The name dictionary as the owner adjusted it: built-in lists switched off, and lists of their own.",
+    ),
+    rules: z
+        .array(PrivacyRuleSchema)
+        .max(PRIVACY_RULES_MAX)
+        .default([])
+        .describe("The owner's own rules: words, phrases and patterns masked wherever they stand."),
 });
 export type PrivacyShieldPolicy = z.infer<typeof PrivacyShieldPolicySchema>;
 
@@ -204,18 +389,21 @@ export const PrivacyKnownSourceSchema = z.object({
 export type PrivacyKnownSource = z.infer<typeof PrivacyKnownSourceSchema>;
 
 // The name lists the shield finds names by when no model is asked for (and alongside one when it is): what each list
-// holds, how many, and where it came from.
+// holds, how many, and where it came from; the owner's own lists among them.
 export const PrivacyNameListSchema = z.object({
     id: z.string().describe("Stable id of the list."),
-    kind: z.enum(["first-name", "surname", "ambiguous", "title", "never"]).describe("What a word on it says about a name."),
+    kind: PrivacyNameListKindSchema.describe("What a word on it says about a name."),
     languages: z.array(z.enum(["pl", "en", "multi"])).describe("The languages its words come from; multi: many languages at once."),
     count: z.number().int().describe("How many words it holds."),
-    matching: z
-        .enum(["inflected", "as-written"])
-        .describe("inflected: matched in every grammatical form of a listed word; as-written: matched only exactly as listed."),
+    matching: PrivacyNameMatchingSchema.describe(
+        "inflected: matched in every grammatical form of a listed word; as-written: matched only exactly as listed.",
+    ),
     source: z.string().describe("Where the words come from: the register or dataset, or that they were written by hand."),
     url: z.string().optional().describe("The source's page, where it has one."),
     license: z.string().optional(),
+    on: z.boolean().describe("Read by the shield; the owner can switch any list off."),
+    own: z.boolean().optional().describe("One of the owner's own lists (policy.dictionary.lists), titled by them."),
+    title: z.string().optional().describe("An own list's title."),
 });
 export type PrivacyNameList = z.infer<typeof PrivacyNameListSchema>;
 
@@ -255,3 +443,23 @@ export const PrivacyDictionarySchema = z.object({
     lookup: PrivacyNameLookupSchema.optional(),
 });
 export type PrivacyDictionary = z.infer<typeof PrivacyDictionarySchema>;
+
+// What the shield would mask in a text the owner tries it on, with the policy as saved: where each find sits, its kind,
+// and what found it. Nothing is given a token and nothing is kept, so trying a value teaches the vault nothing.
+export const PRIVACY_PREVIEW_MAX = 4000;
+
+export const PrivacyPreviewSpanSchema = z.object({
+    start: z.number().int(),
+    end: z.number().int().describe("Exclusive."),
+    class: PersonalDataClassSchema,
+    by: z
+        .enum(["detector", "rule", "learned", "model"])
+        .describe(
+            "detector: the built-in detectors and name lists, the owner's lists included; rule: one of the owner's rules; learned: a value the vault knows; model: the local name model.",
+        ),
+    rule: z.string().optional().describe("The id of the owner's rule that found it."),
+});
+export type PrivacyPreviewSpan = z.infer<typeof PrivacyPreviewSpanSchema>;
+
+export const PrivacyPreviewSchema = z.object({ spans: z.array(PrivacyPreviewSpanSchema) });
+export type PrivacyPreview = z.infer<typeof PrivacyPreviewSchema>;

package/src/schemas/secrets.ts

@@ -1,6 +1,7 @@
 // secrets: user-supplied env-var secrets the daemon writes to desired-state/.env
 import { BrokerRuleSchema } from "@intentic/extension-manifest";
 import { z } from "zod";
+import { KEYRING_PROGRAMS_MAX, KeyringPackageSchema, KeyringProgramSchema, KeyringShareModeSchema, KeyringSourceSchema } from "./keyring.js";
 import { SECRET_HOST_MAX, SECRET_HOST_PATTERN_RE, SECRET_HOSTS_MAX } from "../policy/secret-hosts.js";
 // Straight to the sandbox daemon, never through the platform; `apply` reloads .env with no restart. `list` returns keys
 // only; `reveal` is the one owner-only exception that returns a value.
@@ -61,9 +62,9 @@ export const CredentialGateKindSchema = z
 export type CredentialGateKind = z.infer<typeof CredentialGateKindSchema>;
 
 export const CredentialLaneSchema = z
-    .enum(["shell", "code", "browser", "session", "otp", "gateway", "ssh"])
+    .enum(["shell", "code", "browser", "session", "otp", "gateway", "ssh", "device", "desktop"])
     .describe(
-        "What the credential was about to be used for: a shell command, a script, typing into a page, mounting a connected account, one one-time code, a request the credential gateway attaches it to, or a signature the sandbox's ssh agent makes with a held key.",
+        "What the credential was about to be used for: a shell command, a script, typing into a page, mounting a connected account, one one-time code, a request the credential gateway attaches it to, a signature the sandbox's ssh agent makes with a held key, typing into a window or phone app on one of the owner's computers, or typing into a window on the sandbox's own desktop.",
     );
 export type CredentialLane = z.infer<typeof CredentialLaneSchema>;
 
@@ -121,9 +122,9 @@ export const SecretHostSchema = z
     );
 
 export const SecretHostSourceSchema = z
-    .enum(["owner", "connector"])
+    .enum(["owner", "connector", "keyring"])
     .describe(
-        "Who set it: the owner, or the connector the credential belongs to, whose guard is on with its own service's hosts until the owner changes it.",
+        "Who set it: the owner, the connector the credential belongs to (whose guard is on with its own service's hosts until the owner changes it), or the keyring on the computer that holds the secret, whose list is changed there.",
     );
 export type SecretHostSource = z.infer<typeof SecretHostSourceSchema>;
 
@@ -208,12 +209,84 @@ export const CredentialPolicySetSchema = z.object({
 });
 export type CredentialPolicySet = z.infer<typeof CredentialPolicySetSchema>;
 
+// The program guard: the host guard's counterpart for typing into windows. A sandbox-held secret typed into a window on
+// one of the owner's computers goes unasked only into a program on its list and, unless `anyField`, only into a field the
+// program marks as a password field; anywhere else it waits for a person. A keyring entry carries its own list, kept on
+// that computer (schemas/keyring.ts), which the sandbox can show and never widen.
+export const SecretProgramsSchema = z.object({
+    programs: z.array(KeyringProgramSchema).max(KEYRING_PROGRAMS_MAX).describe("Programs, by executable name or whole path, it may be typed into unasked."),
+    packages: z.array(KeyringPackageSchema).max(KEYRING_PROGRAMS_MAX).describe("Android apps, by package name, it may be typed into unasked."),
+    anyField: z.boolean().describe("Whether it may go into a field not marked as a password field without asking."),
+    source: z.enum(["owner", "keyring"]).describe("Who keeps the list: the owner, here, or the keyring on the computer that holds the secret."),
+});
+export type SecretPrograms = z.infer<typeof SecretProgramsSchema>;
+
+export const SecretProgramGuardSchema = SecretProgramsSchema.omit({ source: true }).extend({
+    subject: z.string().min(1).describe("Which secret, by the name its reference carries."),
+});
+export type SecretProgramGuard = z.infer<typeof SecretProgramGuardSchema>;
+
+export const SecretProgramGuardsSchema = z.object({
+    guards: z.array(SecretProgramGuardSchema).describe("Every sandbox-held secret whose program list has been set. Names and programs only, never a value."),
+});
+
+export const SecretProgramGuardSetSchema = SecretProgramGuardSchema.extend({
+    conversationId: z.string().optional().describe("Which conversation to ask the owner in, when the change needs them. The CLI fills this from the running turn."),
+});
+
+export const SecretProgramGuardSetResultSchema = SecretProgramsSchema.omit({ source: true }).extend({
+    approvedBy: z.string().optional().describe("Who approved the change, when it needed the owner's click. Absent when nobody had to."),
+});
+
+// The owner's Type into…: one secret typed into whatever has focus on one of their computers, after a countdown that
+// leaves time to put the cursor there. Through that computer's keyring, which still asks when its entry's mode says to.
+export const SecretTypeIntoSchema = z.object({
+    key: secretKey.describe("Which secret, by name."),
+    device: z.string().min(1).describe("Which computer, by its device card (`rog`, or `rog::wsl:archlinux` for a distro's own keyring)."),
+    countdownSeconds: z.number().int().min(0).max(10).default(3).describe("How long to wait before typing, for the cursor to be put in place."),
+});
+export const SecretTypeIntoResultSchema = z.object({
+    program: z.string().describe("What it was typed into."),
+    field: z.enum(["password", "text"]).describe("Whether the focused field was a password field."),
+    asked: z.boolean().describe("Whether the person at the computer was asked."),
+});
+
+// The keyrings on the owner's computers this sandbox can reach: where a secret can be kept or typed, and which two can be
+// paired to keep one set of entries.
+export const SandboxKeyringSchema = z.object({
+    machine: z.string().describe("The computer, by its device card."),
+    online: z.boolean().describe("Whether it answers now."),
+    locked: z.boolean().optional().describe("Whether its keyring is locked, as last heard. Absent while offline."),
+    version: z.string().optional().describe("The keyring's release, as last heard."),
+    pendingInbox: z.number().int().nonnegative().optional().describe("Values sent to be kept there that wait for its next unlock."),
+    shared: z.number().int().nonnegative().describe("How many of its entries are shared with this sandbox."),
+    sync: z
+        .object({
+            fingerprint: z.string().describe("Its sync key's fingerprint, to compare with what the other computer shows when pairing."),
+            peers: z.array(z.string()).describe("The computers it is paired with, by device card."),
+        })
+        .optional()
+        .describe("Its pairing with the owner's other keyrings. Absent while offline or before it was heard."),
+});
+export type SandboxKeyring = z.infer<typeof SandboxKeyringSchema>;
+export const SandboxKeyringsSchema = z.object({ keyrings: z.array(SandboxKeyringSchema) });
+
+export const SandboxKeyringPairSchema = z.object({
+    a: z.string().min(1).describe("One computer, by its device card."),
+    b: z.string().min(1).describe("The other."),
+});
+export const SandboxKeyringPairResultSchema = z.object({
+    fingerprints: z.object({ a: z.string(), b: z.string() }).describe("Each keyring's sync-key fingerprint, as both prompts showed them."),
+});
+
 export const SecretInventoryEntrySchema = z.object({
     // Env-var key for env|generated; `<provider>:<accountId>` for provider; capability instance id otherwise.
     key: z.string().describe("What identifies it. Unique across the whole inventory, so several accounts of one provider each get their own entry."),
     kind: z
-        .enum(["env", "generated", "capability", "provider"])
-        .describe("Where it came from: you set it, the sandbox generated it, a connection needs it, or it is a model account's credential."),
+        .enum(["env", "generated", "capability", "provider", "device"])
+        .describe(
+            "Where it came from: you set it, the sandbox generated it, a connection needs it, it is a model account's credential, or it lives in the keyring on one of your computers and this sandbox holds only a pointer to it.",
+        ),
     // e.g. "<ProviderName> · <accountLabel>" for provider entries; absent on env/generated.
     label: z.string().optional().describe("A friendlier name, for entries that have one."),
     status: z.enum(["missing", "set", "connected"]).describe("Whether it exists and, for a connection, whether it is working."),
@@ -237,9 +310,9 @@ export const SecretInventoryEntrySchema = z.object({
         .object({
             at: z.number().describe("When, in milliseconds."),
             lane: z
-                .enum(["shell", "code", "browser", "gateway", "ssh"])
+                .enum(["shell", "code", "browser", "gateway", "ssh", "device", "desktop"])
                 .describe(
-                    "How it was used: a command, a script, typed into a page, attached by the credential gateway to a request the agent sent, or a key the sandbox's ssh agent signed with for the agent.",
+                    "How it was used: a command, a script, typed into a page, attached by the credential gateway to a request the agent sent, a key the sandbox's ssh agent signed with for the agent, typed into a window or app on one of the owner's computers, or typed into a window on the sandbox's desktop.",
                 ),
             detail: z
                 .string()
@@ -272,6 +345,21 @@ export const SecretInventoryEntrySchema = z.object({
         })
         .optional()
         .describe("Its host guard. Absent when none was ever set and no connector sets one: the guard is off."),
+    // Joined from the program guards: which windows and phone apps a use may type it into unasked.
+    programs: SecretProgramsSchema.optional().describe(
+        "Which programs on the owner's computers, and which phone apps, it may be typed into without asking. Absent when none was set: typing it into any window asks first.",
+    ),
+    // A device row only: the keyring entry the pointer names. Everything here is the keyring's to change, on that computer.
+    device: z
+        .object({
+            machine: z.string().describe("Which computer's keyring holds it, by its device card."),
+            mode: KeyringShareModeSchema,
+            online: z.boolean().describe("Whether that computer answers now. Offline, an `each-use` or `while-here` secret cannot be used until it does."),
+            locked: z.boolean().optional().describe("Whether the keyring there is locked, as last heard. Absent while the computer is offline."),
+            source: KeyringSourceSchema,
+        })
+        .optional()
+        .describe("Where a secret held on one of your computers lives and how it is shared. Present on `device` rows only."),
 });
 export type SecretInventoryEntry = z.infer<typeof SecretInventoryEntrySchema>;
 export const SecretInventorySchema = z.object({

package/src/schemas/settings.ts

@@ -298,6 +298,14 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Let the agent answer with a page drawn right in the chat: a chart, a table, a diagram, a mock-up, or a small form you answer it on. Off, the agent is not offered the tools at all, so it spends nothing on them.",
         ),
+    // The daemon's shadow keeper (derived/shadow-keeper.ts) and the ripgrep config agents' shells get with it. On by
+    // default: it renders without asking any model (OCR excepted, on this machine), one low-priority process at a time.
+    documentSearch: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Keep the text of every document in the workspace (pdf, Word, OpenDocument, spreadsheets, presentations, epub, and scans where OCR is installed) ready to search. In the background, one low-priority process at a time, each document is rendered to text when it appears or changes, so `rg` and iq find what documents say under their own paths, cited by page. Off, nothing renders until someone opens a document, and searches skip them.",
+        ),
     hashlineEdits: z
         .boolean()
         .default(false)

package/src/schemas/speech.ts

@@ -74,7 +74,9 @@ export type SpeechTranscript = z.infer<typeof SpeechTranscriptSchema>;
 // 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`
 // abandons it. The daemon answers with `partial` text while the phrase is still being spoken, one `final` per ended
-// phrase, in order, and `status` whenever the model's readiness moves. The language is the socket's `lang` query.
+// phrase, in order, and `status` whenever the model's readiness moves. The language is the socket's `lang` query;
+// `guesses=0` asks for finals alone, which the wake listener does: nobody reads a running guess at a room's talk, and
+// each one is a decode.
 export const SpeechClientMessageSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("begin"), id: z.number() }),
     z.object({ type: z.literal("end"), id: z.number(), keep: z.number() }),
@@ -98,3 +100,38 @@ export type SpeechServerMessage = z.infer<typeof SpeechServerMessageSchema>;
 // The longest phrase either door takes: a minute at 16 kHz. The composer's segmenter cuts a monologue at the same
 // length, so nothing it sends is ever refused.
 export const MAX_SPEECH_SAMPLES = 60 * 16_000;
+
+// THE WAKE WORD: what a person says to the editor across the room to be heard without touching it ("Leon, fix the
+// build"). The editor listens for it on a device the person switched it on for, and hears it with this sandbox's own
+// model, so it is a word the model writes down: letters (any script), with a space, hyphen or apostrophe between them.
+export const WAKE_WORD_DEFAULT = "Leon";
+export const WakeWordSchema = z
+    .string()
+    .trim()
+    .regex(/^[\p{L}\p{M}](?:[\p{L}\p{M}' -]{0,38}[\p{L}\p{M}])?$/u)
+    .refine((word) => [...word].length >= 2, { message: "a wake word has at least two letters" });
+
+// POST /speech/wake: one device's claim on a wake it just heard. Every device listening for the same person hears the
+// same "Leon", and each would open its own session; the first to claim within a few seconds is granted it and the rest
+// stand down. A device keeps its own claims, so its next wake a moment later is never refused by its last one, and a
+// device in the middle of an exchange holds it longer, so a follow-up the other devices also hear stays with it.
+export const WAKE_HOLD_MAX_MS = 10 * 60_000;
+export const SpeechWakeClaimSchema = z.object({
+    device: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{8,64}$/u)
+        .describe("A random id this browser or app minted for itself once, so its own claims are told from another device's."),
+    holdMs: z
+        .number()
+        .int()
+        .min(0)
+        .max(WAKE_HOLD_MAX_MS)
+        .optional()
+        .describe("Keep the person's other devices off for this long rather than the few seconds a lone wake holds: an exchange this device is in the middle of."),
+});
+export type SpeechWakeClaim = z.infer<typeof SpeechWakeClaimSchema>;
+
+export const SpeechWakeGrantSchema = z.object({
+    granted: z.boolean().describe("This device acts on the wake; false when another device of the same person claimed it first."),
+});
+export type SpeechWakeGrant = z.infer<typeof SpeechWakeGrantSchema>;

package/src/schemas/system.ts

@@ -208,8 +208,11 @@ export type DaemonSession = z.infer<typeof DaemonSessionSchema>;
 // How a session's identity was proven. A session carries the set it was minted from; the require-passkey policy reads
 // it on every request, so a session minted before the switch stops working on its next call. `email` is the platform's
 // signed word that the person controls the address (policy/identity-assertion.ts), accepted only where the owner opted
-// that person in, and on hosted machines.
-export const ProofMethodSchema = z.enum(["google", "ticket", "passkey", "recovery", "email"]);
+// that person in, and on hosted machines. `host` is the machine that runs the sandbox: a session `ic sandbox session`
+// minted through `docker exec` for the bound owner, so the desktop app and Intentic OS reach their own sandboxes with no
+// network (the daemon's auth/host/host-session.ts). It is never a sign-in a browser can offer, so no daemon lists it in
+// `signIn.proofs`.
+export const ProofMethodSchema = z.enum(["google", "ticket", "passkey", "recovery", "email", "host"]);
 export type ProofMethod = z.infer<typeof ProofMethodSchema>;
 
 // The `reason` a daemon's refusal of an identity assertion carries beside its `error`, so the editor can say what to do:

package/src/schemas/terminal.ts

@@ -191,7 +191,8 @@ export type DesktopState = z.infer<typeof DesktopStateSchema>;
 // turn, be steered, and land its own work.
 // id is the spawning tool call's id for an in-process one, its own conversation id for a spawned one. The kind changes
 // only where its record is read from and what else can be done with it, never how it looks.
-export const SubagentKindSchema = z.enum(["subagent", "spawned"]);
+// `linked`: a task handed to another of the owner's sandboxes over a link; it runs and lands there, never in this checkout.
+export const SubagentKindSchema = z.enum(["subagent", "spawned", "linked"]);
 export type SubagentKind = z.infer<typeof SubagentKindSchema>;
 // pending/running/blocked/paused are live, the rest terminal. Uses the SDK's own task vocabulary rather than AgentStatus.
 // `blocked` is one addition: a spawned child's question/permission/plan card raises it. `paused` the other: a spawned
@@ -225,7 +226,7 @@ export const SubagentSessionSchema = z.object({
             "The id of the tool call that started it (an SDK child) or the child's own conversation id (a spawned one); either way both sides already hold it, so a card links to its subagent with the id it has and the subagent points back the same way.",
         ),
     kind: SubagentKindSchema.describe(
-        "How it was started: in-process by the runtime's own Agent/Task tool, or spawned by the daemon as a conversation of its own, on any provider. It changes where its record is read from and what else can be done with it, never what it is.",
+        "How it was started: in-process by the runtime's own Agent/Task tool, spawned by the daemon as a conversation of its own, on any provider, or handed to another of the owner's sandboxes over a link, where it runs and lands. It changes where its record is read from and what else can be done with it, never what it is.",
     ),
     // The conversation whose turn started it; how a card links back to the chat it belongs to.
     conversationId: z.string().describe("The conversation whose turn started it, and the way back to the chat it belongs to."),
@@ -279,6 +280,16 @@ export const SubagentSessionSchema = z.object({
     error: z.string().optional().describe("Why it failed, when it did."),
     // Filled once the subagent ends; a standing read mid-work would judge a job not yet done.
     verification: SubagentVerificationSchema.optional().describe("Whether anything proved the work its report describes."),
+    // A `linked` one's far end: where its conversation lives, so a row opens it there rather than here.
+    linked: z
+        .object({
+            link: z.string().describe("The link card it went through: the agent's name for that sandbox."),
+            sandbox: z.string().describe("What that sandbox is called."),
+            sandboxId: z.string().optional().describe("That sandbox's id on the owner's account, when the card knows it."),
+            conversationId: z.string().describe("The conversation it opened there."),
+        })
+        .optional()
+        .describe("For a task handed to another sandbox: which one, and the conversation it runs in there."),
 });
 export type SubagentSession = z.infer<typeof SubagentSessionSchema>;
 export const SubagentsListSchema = z.object({

package/src/schemas/voice.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { WAKE_WORD_DEFAULT, WakeWordSchema } from "./speech.js";
 
 // Speaking a reply aloud: which voices a sandbox can speak with, which one speaks a language, and the live wire the
 // editor plays speech over. The daemon's engine is src/speech/voice; the editor's half is
@@ -60,6 +61,16 @@ export const VoiceSettingsSchema = z.object({
     cloud: CloudVoiceSchema.optional().describe(
         "A speech provider of your own, used for every language it speaks unless you picked a voice on this sandbox for it. Its key is a stored secret; text it speaks leaves the sandbox for that provider.",
     ),
+    wake: z
+        .object({
+            word: WakeWordSchema.default(WAKE_WORD_DEFAULT).describe(
+                "The name you call the agent by. Two or three syllables wake it reliably; a short or everyday word wakes it by mistake.",
+            ),
+        })
+        .prefault({})
+        .describe(
+            "Talking to the agent from across the room: say this word and what you want, on a device where listening for it is switched on. Each device is switched on by its own reader, since it is that device's microphone.",
+        ),
 });
 export type VoiceSettings = z.infer<typeof VoiceSettingsSchema>;
 

package/src/schemas/webext.ts

@@ -1,7 +1,7 @@
 // webext: the user's own browser (the `webext` capability's live half)
 // Named imports rather than the `z` namespace: this module is bundled into the browser extension, where the
 // namespace keeps zod's 60 locales (~250 kB) that esbuild can otherwise drop. _devices/webext/scripts/size-budget.mjs holds the ceiling.
-import { array, boolean, enum as zEnum, number, object, string } from "zod";
+import { array, boolean, enum as zEnum, literal, number, object, string, union } from "zod";
 import type * as z from "zod";
 // The card's switches, here rather than in capabilities.ts because the extension bundles this module and would
 // otherwise ship every other capability's schema to the store.
@@ -105,3 +105,18 @@ export const WebExtSessionExportResultSchema = object({
     cookies: array(WebExtCookieSchema).optional(),
 });
 export type WebExtSessionExportResult = z.infer<typeof WebExtSessionExportResultSchema>;
+
+// The extension collecting a secret it was handed a ticket to type (webextSecretUrl): the ticket, and the page it is
+// about to type into, which the daemon's host guard judges. The value never rides a request, only the answer.
+export const WebExtSecretRequestSchema = object({
+    ticket: string().min(1),
+    url: string().min(1),
+    // A password input or any other text field, which an approval card names.
+    field: zEnum(["password", "text"]),
+});
+export type WebExtSecretRequest = z.infer<typeof WebExtSecretRequestSchema>;
+
+// The value for that one field, read only by the extension and written straight into the page; or the sentence why
+// not, which reaches the agent as the tool's refusal.
+export const WebExtSecretAnswerSchema = union([object({ ok: literal(true), value: string() }), object({ ok: literal(false), message: string() })]);
+export type WebExtSecretAnswer = z.infer<typeof WebExtSecretAnswerSchema>;

package/src/state/contract-lock.test.ts

@@ -18,9 +18,9 @@ const ACCESS_MOVED =
 // Needs 30s: serializing ~500 schemas can run past the unit hang detector under load.
 test(
     "contract.lock.json matches the schemas this package exports",
-    () => {
+    async () => {
         const committed = committedText();
-        const current = currentLock();
+        const current = await currentLock();
         // Named first, so a reach change says which route before the whole-lock diff does.
         expect(accessChanges(committed, serializeLock(current)), ACCESS_MOVED).toEqual([]);
         expect(
@@ -35,8 +35,8 @@ test(
 
 // The wire outside oRPC is pinned the same way: a changed tunnel path, a gone control message or a renamed verdict is a
 // shrink the push gate and the landing draft both flag, where before nothing could see it.
-test("the lock flags a change to the wire no oRPC route carries", () => {
-    const base = currentLock() as Record<string, Record<string, unknown>>;
+test("the lock flags a change to the wire no oRPC route carries", async () => {
+    const base = (await currentLock()) as Record<string, Record<string, unknown>>;
     const moved = structuredClone(base);
     (moved["wire:tunnel"] as { path: string }).path = "/tunnel/v3";
     delete (moved["wire:browser-wire"] as { webTransport?: unknown }).webTransport;
@@ -45,7 +45,7 @@ test("the lock flags a change to the wire no oRPC route carries", () => {
 });
 
 // The lock as it would be with one raw route declared otherwise: the declaration is swapped in place, and back.
-const lockWith = (name: string, change: (declared: RouteMeta) => RouteMeta): Record<string, unknown> => {
+const lockWith = async (name: string, change: (declared: RouteMeta) => RouteMeta): Promise<Record<string, unknown>> => {
     const route = RAW_ROUTE_LIST.find((candidate) => candidate.name === name);
     if (route === undefined) {
         throw new Error(`${name} is gone; pick another raw route with a maintainer floor and no grants`);
@@ -53,7 +53,7 @@ const lockWith = (name: string, change: (declared: RouteMeta) => RouteMeta): Rec
     const declared = route.meta;
     Reflect.set(route, "meta", change(declared));
     try {
-        return currentLock();
+        return await currentLock();
     } finally {
         Reflect.set(route, "meta", declared);
     }
@@ -63,18 +63,18 @@ const ROUTE = "POST /system/sync/report";
 
 // A lowered floor on any route, not only the ones route-reach.test.ts pins: the lock check names it, and the push gate and
 // the landing draft read it as a shrink that needs a declared break.
-test("lowering one route's floor fails the lock check, naming the route", () => {
-    const committed = currentLock();
-    const lowered = lockWith(ROUTE, (declared) => ({ ...declared, floor: "viewer" }));
+test("lowering one route's floor fails the lock check, naming the route", async () => {
+    const committed = await currentLock();
+    const lowered = await lockWith(ROUTE, (declared) => ({ ...declared, floor: "viewer" }));
     expect(accessChanges(serializeLock(committed), serializeLock(lowered))).toEqual([`${ROUTE}: floor "maintainer" → "viewer"`]);
     expect(shrunkSurfaces(committed, lowered)).toEqual([`access:${ROUTE}.floor`]);
 });
 
 // A grant a route never declared still has a value in the lock, so granting it is a changed value, not growth that
 // passes; taking one away reads the same way, since it locks out a caller that relied on it.
-test("granting guest or agent reach reads as a shrink, and so does taking it back", () => {
-    const committed = currentLock();
-    const granted = lockWith(ROUTE, (declared) => ({ ...declared, guest: true, agent: true }));
+test("granting guest or agent reach reads as a shrink, and so does taking it back", async () => {
+    const committed = await currentLock();
+    const granted = await lockWith(ROUTE, (declared) => ({ ...declared, guest: true, agent: true }));
     expect(accessChanges(serializeLock(committed), serializeLock(granted))).toEqual([`${ROUTE}: agent false → true, guest false → true`]);
     expect(shrunkSurfaces(committed, granted)).toEqual([`access:${ROUTE}.agent`, `access:${ROUTE}.guest`]);
     expect(shrunkSurfaces(granted, committed)).toEqual([`access:${ROUTE}.agent`, `access:${ROUTE}.guest`]);