@intentic/sandbox-contract 1.322.0 → 1.323.0

package/src/models/agent-runtimes.ts

@@ -51,6 +51,11 @@ export interface AgentCapabilities {
     readonly rulebook: "hooks" | "approval" | "refuse-only" | "none";
     // Whether a credential is masked; "none" is structural, only the Claude Code loop can rewrite a model's read.
     readonly secrets: "masked" | "none";
+    // Whether the privacy shield can stand between this loop and its provider: `gateway` when the daemon names the base
+    // URL the loop sends its model requests to (so the gateway reads and masks every byte of them), `none` when the loop
+    // talks to its provider on a wire or a configuration the daemon does not own. A `none` loop on an untrusted provider
+    // is refused while the shield is on.
+    readonly privacy: "gateway" | "none";
 }
 
 // The Claude Code Agent SDK loop, the ceiling every other runtime is measured against: the only one that owns the whole
@@ -75,6 +80,8 @@ export const CLAUDE_CODE: AgentCapabilities = {
     // The only runtime with its own pre-execution hook, so the only one where a hold can park instead of refusing.
     rulebook: "hooks",
     secrets: "masked",
+    // Every request goes to ANTHROPIC_BASE_URL, which the daemon sets per turn.
+    privacy: "gateway",
 };
 
 // Codex app-server: item-level events, the turn's remote MCP servers over http, and four seams (steer, a question
@@ -100,6 +107,8 @@ export const CODEX: AgentCapabilities = {
     // Asked only when the owner has written command rules; an unconfigured workspace pays nothing for it.
     rulebook: "approval",
     secrets: "none",
+    // Its model provider's base_url is the daemon's, written into the per-thread config.
+    privacy: "gateway",
 };
 
 // OpenCode (the Grok runtime): its own agentic loop and tools, with the turn's remote MCP servers mounted on the shared
@@ -126,6 +135,8 @@ export const OPENCODE: AgentCapabilities = {
     // hold parked on a card while the turn's inactivity watchdog is held.
     rulebook: "approval",
     secrets: "none",
+    // The shared server's provider baseURLs are written by the daemon at spawn.
+    privacy: "gateway",
 };
 
 // The same OpenCode loop, serving Gemini instead of xAI, identical abilities. The Claude Code loop announces itself in
@@ -157,6 +168,8 @@ export const ACP: AgentCapabilities = {
     // In the protocol floor, so every agent has it; which calls it asks about is entirely its own choice.
     rulebook: "approval",
     secrets: "none",
+    // The agent picks its own provider and endpoint from its own login and environment.
+    privacy: "none",
 };
 
 // Pi driven over its RPC mode: above the ACP floor and below the Claude Code ceiling. Real mid-turn steering, an effort
@@ -181,6 +194,8 @@ export const PI: AgentCapabilities = {
     // The one runtime with no seam at all: bash runs in-process, and no rule the owner writes can apply.
     rulebook: "none",
     secrets: "none",
+    // Pi calls its provider from its own login; the daemon names no endpoint.
+    privacy: "none",
 };
 
 // Cursor's own runtime, driven through `@cursor/sdk` from this daemon's process; an embedding surface, so most seams
@@ -219,4 +234,6 @@ export const CURSOR: AgentCapabilities = {
     rulebook: "hooks",
     // none, structurally: its hooks only allow/deny or are discarded, nothing here to substitute a reference into.
     secrets: "none",
+    // Cursor's own RPC to its own servers, which then reach the model: redirectable, not readable.
+    privacy: "none",
 };

package/src/models/capability-ledger.test.ts

@@ -34,6 +34,9 @@ const LEDGER: Record<keyof AgentCapabilities, Backing> = {
     rulebook: "enforced",
     // agent/run/turn/cache-keepwarm.ts files nothing to keep warm for a turn whose runtime lacks it.
     warm: "enforced",
+    // agent/run/decide/turn-decision.ts refuses a "none" runtime on an untrusted provider while the privacy shield is
+    // on; "gateway" runtimes get the daemon's gateway as their base URL (privacy/gateway).
+    privacy: "enforced",
 
     // Descriptive: true of the runtime but nothing consults these; wiring one up moves it to enforced.
     questions: "descriptive",

package/src/policy/request-status.ts

@@ -1,4 +1,4 @@
-import { REQUEST_FIELDS, type RequestField, type TranscriptRequests, type TranscriptRow } from "../events/transcript.js";
+import { type PermissionStatus, REQUEST_FIELDS, type RequestField, type TranscriptRequests, type TranscriptRow } from "../events/transcript.js";
 import type { AgentReply } from "../schemas/providers/plan-limits.js";
 import { startedChildCard } from "../events/child-run.js";
 
@@ -7,6 +7,21 @@ import { startedChildCard } from "../events/child-run.js";
 // of the wrong kind cannot settle a card of another, since requestId is what matches them.
 type Cards = { -readonly [K in RequestField]?: TranscriptRow[K] };
 
+// A permission card's ending, from the reply that released it: each kind of yes keeps its own word.
+const permissionStatusOf = (reply: AgentReply | undefined): PermissionStatus => {
+    if (reply?.kind !== "permission") {
+        return "cancelled";
+    }
+    switch (reply.decision) {
+        case "deny":
+            return "denied";
+        case "once":
+            return "allowed";
+        default:
+            return reply.decision;
+    }
+};
+
 export const settledRequests = (cards: TranscriptRequests, reply: AgentReply | undefined): TranscriptRequests => {
     const out: Cards = {};
     const { plan, question, permission, browserHelp, terminalHelp, capabilityOffer, paymentOffer, credentialOffer } = cards;
@@ -15,23 +30,18 @@ export const settledRequests = (cards: TranscriptRequests, reply: AgentReply | u
     }
     if (question !== undefined) {
         const answers = reply?.kind === "question" ? reply.answers : undefined;
+        const attachments = reply?.kind === "question" ? reply.attachments : undefined;
         out.question = {
             ...question,
             status: reply?.kind === "question" && reply.cancelled !== true ? "answered" : "cancelled",
             ...(answers === undefined ? {} : { answers }),
+            ...(attachments === undefined ? {} : { attachments }),
         };
     }
     if (permission !== undefined) {
         out.permission = {
             ...startedChildCard(permission, reply),
-            status:
-                reply?.kind !== "permission"
-                    ? "cancelled"
-                    : reply.decision === "deny"
-                      ? "denied"
-                      : reply.decision === "always"
-                        ? "always"
-                        : "allowed",
+            status: permissionStatusOf(reply),
         };
     }
     if (browserHelp !== undefined) {

package/src/policy/turned-away.ts

@@ -11,6 +11,8 @@ const TURNED_AWAY: ReadonlySet<string> = new Set([
     "unknown-command",
     "context-window-too-small",
     "model-helper-only",
+    // The privacy shield refused an untrusted provider on a runtime it cannot stand in front of.
+    "privacy-unshielded",
     "sandbox-memory-low",
     "trial-unavailable",
     "trial-model-unavailable",

package/src/protocol/raw-routes.ts

@@ -8,6 +8,9 @@ import { runnerTranslatorPath } from "./runner-protocol.js";
 export const RAW_ROUTES = {
     // The "is a daemon there" probe every flow uses; it names the sandbox and says whether it is still converging.
     "GET /health": { auth: "door", beforeBoot: true },
+    // A person opening this sandbox's own address in a browser: sent to the app's /open on it, the address being what
+    // they may still hold when the platform has lost the rest. Anything else gets the same 401 as before it existed.
+    "GET /": { auth: "door", beforeBoot: true },
     "GET /diff/raw": { lane: "bulk" },
     // Arming the dictation model is a read any tier makes; dictating is writing a message, the collaborator's grant.
     "GET /speech/status": { guest: true },
@@ -59,6 +62,8 @@ export const RAW_ROUTES = {
     "POST /members": { control: "never" },
     "DELETE /members": { control: "never" },
     "DELETE /members/self": { floor: "viewer", guest: true, control: "never" },
+    // The owner's Reconnect: register with the platform now, having it adopt the sandbox first when it holds no record.
+    "POST /platform/relink": { control: "never" },
     "GET /environment": {},
     "GET /environment/contents": {},
     "POST /environment/approve": {},
@@ -153,6 +158,10 @@ export const RAW_ROUTES = {
     "POST /system/runners/credentials": { auth: "door", control: "never" },
     "POST /system/runners/credentials/refresh": { auth: "door", control: "never" },
     [`ALL ${runnerTranslatorPath}/*` as const]: { auth: "door", control: "never" },
+    // The privacy shield's gateway: every shielded runtime's model requests, on the signed session its base URL carries
+    // (privacy/gateway/session-token.ts), which names the provider and the only upstream it may forward to. Held open
+    // while a model streams its answer.
+    "ALL /privacy/gateway/{session}/*": { auth: "door", control: "never", stream: true },
     "POST /system/control/tokens": { control: "never" },
     "GET /system/control/tokens": { control: "never" },
     "DELETE /system/control/tokens/{id}": { control: "never" },

package/src/schemas/agent.ts

@@ -304,15 +304,28 @@ const AgentTurnFieldsSchema = z.object({
     editorContext: EditorContextSchema.optional().describe(
         'What the user has open in their editor, folded into the prompt so that pointing words like "this" resolve.',
     ),
-    // The composer's scheduled send: a person who knows the account is spent books the message for its reopen instead of
-    // sending it into a refusal. Held in the conversation's queue, never started early; the queue's `until` is this.
+    // The composer's scheduled send: a time the person chose, or a spent account's reopen they would rather wait for than
+    // send into a refusal. Held in the conversation's queue, never started early; the queue's `until` is this.
     sendAt: z
         .number()
         .int()
         .positive()
         .optional()
         .describe(
-            "Hold this message until then (epoch milliseconds) instead of starting a turn now, for an allowance you know is spent. It waits in the conversation's queue, where it can be sent early, reworded or removed, and goes by itself at that instant. Ignored when already past, or when a turn is running.",
+            "Hold this message until then (epoch milliseconds) instead of starting a turn now: a time you chose, or the reopen of an allowance you know is spent. It waits in the conversation's queue, where it can be sent early, reworded, rescheduled or removed, and goes by itself at that instant, even for a conversation this message opens or one whose turn is running now. Ignored when already past; at most a month ahead.",
+        ),
+    // The other scheduled send: work that builds on another agent's, held until that agent's work is in the workspace.
+    // Held in the queue like `sendAt`; the queue's `after` is this. Never both: a hold waits on exactly one thing.
+    sendAfter: ConversationIdSchema.optional().describe(
+        "Hold this message until the conversation named here has finished and all of its work has landed in the workspace, instead of starting a turn now: for work that builds on another agent's. It waits in this conversation's queue, where it can be sent early, reworded, rescheduled or removed. Sent at once when that conversation has nothing running and nothing left to land.",
+    ),
+    // Decided like `isolated`: the opening turn's answer, latched on the entry it opens. A maintainer's alone, since the
+    // standing answer it sets is what `agents.autoLand` sets, and that route is a maintainer's.
+    conversationAutoLand: z
+        .boolean()
+        .optional()
+        .describe(
+            "Whether this conversation's finished work merges into the workspace by itself from now on: its own answer to the sandbox-wide setting, the one `agents.autoLand` changes later. Read only from the message that opens the conversation, and only from a maintainer. Unlike `autoLand`, it holds for every later turn.",
         ),
 });
 export const AgentTurnSchema = AgentTurnFieldsSchema
@@ -335,8 +348,24 @@ export const AgentTurnSchema = AgentTurnFieldsSchema
     // "then" needs a checkout of its own; rolling back the shared tree under everyone else is what it must never mean.
     .refine((turn) => turn.forkOf?.files !== "then" || turn.isolated === true, {
         message: 'forkOf.files "then" requires isolated',
+    })
+    .refine((turn) => turn.sendAt === undefined || turn.sendAfter === undefined, {
+        message: "sendAt and sendAfter are two different holds: name one",
+    })
+    .refine((turn) => turn.sendAfter === undefined || turn.sendAfter !== turn.conversationId, {
+        message: "a conversation cannot wait for its own work to land",
     });
 export type AgentTurn = z.infer<typeof AgentTurnSchema>;
+// What `agent.run` takes: a turn, plus the one field only a request carries and no stored turn keeps. A daemon from before
+// `continues` reads past it and takes `prompt` as the words, which is why a client still sends some.
+export const AgentRunSchema = AgentTurnSchema.safeExtend({
+    continues: z
+        .literal(true)
+        .optional()
+        .describe(
+            "Carry the conversation on from where its last turn stopped instead of saying anything: nothing of yours is added to the conversation, and `prompt` is ignored. A turn the sandbox still holds runs again as it was; otherwise the agent is told to continue in its own session. Refused while a turn is running.",
+        ),
+});
 // What a turn naming no provider or loop runs on, stated once. Applied where a request comes in (the daemon's turn port),
 // so nothing downstream defaults them again: the engine takes a turn with both named (withRuntimeDefaults).
 /** A turn with its provider and loop named, as the engine takes it past the door. */
@@ -491,12 +520,15 @@ export const ConversationQueueSchema = z.object({
     items: z.array(QueuedMessageSchema).describe("What waits, in the order it goes out."),
     revision: z.number().int().nonnegative().describe("Moves with every change to the queue, so of two copies the higher is the newer."),
     paused: QueuePauseSchema.optional().describe(
-        "Why nothing goes out by itself: somebody stopped the turn, the turn these messages started was refused before it ran, or they were scheduled for later. Resuming lets them go, and so does sending another message unless they are scheduled.",
+        "Why nothing goes out by itself: somebody stopped the turn, the turn these messages started was refused before it ran, or they were scheduled for a time or for after another conversation's work lands. Resuming lets them go, and so does sending another message.",
     ),
     until: z
         .number()
         .optional()
         .describe("When scheduled messages go out by themselves, in milliseconds. Only on a queue paused as `scheduled`."),
+    after: ConversationIdSchema.optional().describe(
+        "The conversation whose finished work must land before scheduled messages go out by themselves. Only on a queue paused as `scheduled`, in place of `until`.",
+    ),
 });
 export type ConversationQueue = z.infer<typeof ConversationQueueSchema>;
 // What resuming a queue did: started a turn with what waited, when nothing else ran.

package/src/schemas/agents.ts

@@ -357,7 +357,7 @@ export const AgentSummarySchema = z.object({
     // Root repo's short base sha; per-repo bases stay daemon-internal.
     base: z.string().optional().describe("The commit its private copy started from, shortened."),
     costUsd: z.number().optional().describe("What it has cost so far, in dollars. A subagent's spend is its own and is not folded in here."),
-    inputTokens: z.number().optional().describe("Tokens sent."),
+    inputTokens: z.number().optional().describe("Uncached input tokens, excluding cache reads and cache writes."),
     outputTokens: z.number().optional().describe("Tokens received."),
     contextTokens: z.number().optional().describe("How much of the window the conversation currently fills."),
     contextWindow: z.number().optional().describe("How large that window is."),

package/src/schemas/automations.ts

@@ -9,10 +9,10 @@ import { ZoneSchema } from "../time/zone.js";
 // (non-zero exit skips the wake), then runs one turn with the prompt. The manifest is user config; run history is
 // daemon-recorded.
 
-// schedule: fires on its cron
-// once: fires a single time at `at`, then retires itself (the daemon switches it off as it fires). Unlike a cron, a
-// fire missed while the sandbox was down still lands, late, on the next poll: a recurring wake that skips a beat has
-// another one coming, a one-time wake has nothing behind it
+// schedule: fires on its cron. Moments missed while the sandbox was down fire once, late, as the daemon starts, however
+// many there were: a recurring wake is owed its work, not a backlog
+// once: fires a single time at `at`, then retires itself (the daemon switches it off as it fires). A fire missed while
+// the sandbox was down still lands, late, on the next poll
 // event: fires when an external system POSTs /automations/{id}/fire; its auth token lives outside the manifest
 // (.intentic/secrets/doors.json), never in this versioned, widely-readable file
 // listener: fires from a realtime source's own connection (an extension's gateway), no cron, no token, never reachable

package/src/schemas/git/git.ts

@@ -379,6 +379,7 @@ export type WorkspaceModules = z.infer<typeof WorkspaceModulesSchema>;
 // One file an agent touched that still differs from main, plus whether main's working tree already holds it:
 // in main's history: accepted, no longer a difference — no row (see `absorbed`).
 // in main's tree, uncommitted: `landed: true`.
+// taken by the last land and edited in main since (committed or not): `landed: true`, since no land has anything to apply.
 // neither (never landed, or landed then discarded): `landed: false` — what "Land now" applies to.
 // A landed row stays until committed; that is the only act that retires it.
 export const AgentChangeSchema = GitChangeSchema.extend({

package/src/schemas/loops.ts

@@ -186,7 +186,8 @@ export type LoopIteration = z.infer<typeof LoopIterationSchema>;
 // overspent: maxSpendUsd reached.
 // stopped: the user pressed Stop.
 // error: the loop itself failed, not a turn inside it (see `LoopIteration.outcome`).
-export const LoopStateSchema = z.enum(["running", "done", "exhausted", "stalled", "overspent", "stopped", "error"]);
+// unpriced: a spend ceiling was set but the runtime does not report cost, so the ceiling cannot be enforced.
+export const LoopStateSchema = z.enum(["running", "done", "exhausted", "stalled", "overspent", "stopped", "error", "unpriced"]);
 export type LoopState = z.infer<typeof LoopStateSchema>;
 export const LoopRecordSchema = LoopSchema.extend({
     state: LoopStateSchema.describe(

package/src/schemas/needs.ts

@@ -262,6 +262,17 @@ export const ConversationGrantSchema = z.object({
         .boolean()
         .default(false)
         .describe("Whether its own dependency installs run without asking, where the owner's setting would otherwise ask first."),
+    // Answered on a host guard's card, "Allow <secret> anywhere in this conversation", read live by the host guard.
+    secrets: z
+        .array(z.string())
+        .default([])
+        .describe("Secrets whose host guard it may send past without asking, by registry name."),
+    // Answered on any permission card's Allow menu, read live by the card registry: every later request a person could
+    // have allowed once settles as allowed. A request that always asks still asks.
+    everything: z
+        .boolean()
+        .default(false)
+        .describe("Whether every request an allow-once could settle is allowed without asking, until somebody takes it back."),
     updatedAt: z.number().describe("When it last changed, in milliseconds."),
     by: z.string().optional().describe("Who last allowed something here."),
 });
@@ -277,6 +288,8 @@ export const StandingGrantsSchema = z.object({
             folders: z.array(z.string()).describe("Workspace folders its file tools may touch beyond its fence."),
             shelves: z.array(GrantShelfSchema).describe("Shelves of tools opened for it."),
             installs: z.boolean().default(false).describe("Whether its own dependency installs run without asking."),
+            secrets: z.array(z.string()).default([]).describe("Secrets it may send past their host guard without asking."),
+            everything: z.boolean().default(false).describe("Whether every request an allow-once could settle is allowed without asking."),
             by: z.string().optional().describe("Who last allowed one of those."),
             updatedAt: z.number().optional().describe("When one of those last changed, in milliseconds."),
             releases: z
@@ -290,9 +303,11 @@ export type StandingGrants = z.infer<typeof StandingGrantsSchema>;
 export const GrantRevokeSchema = z.object({
     conversationId: z.string(),
     kind: z
-        .enum(["capability", "folder", "shelf", "release", "install"])
-        .describe("Which kind of yes: a grant past the persona or area, a credential's release, or letting its installs run unasked."),
-    what: z.string().describe("The capability id, folder, shelf or released credential it named; empty for installs."),
+        .enum(["capability", "folder", "shelf", "release", "install", "secret", "everything"])
+        .describe(
+            "Which kind of yes: a grant past the persona or area, a credential's release, letting its installs run unasked, a secret sent past its host guard, or allowing everything.",
+        ),
+    what: z.string().describe("The capability id, folder, shelf, released credential or secret it named; empty for installs and everything."),
 });
 export type GrantRevoke = z.infer<typeof GrantRevokeSchema>;
 

package/src/schemas/platform-link.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+
+// THE DAEMON'S LINK WITH THE PLATFORM, as /health reports it (`announce`) and as the owner's Reconnect renews it (POST
+// /platform/relink). The one link nothing outside the container can probe: whether this daemon's registration was
+// taken, and, when it was refused, whether the platform has no record of the sandbox (`unknown`, which a platform that
+// forgot it says too) or deleted it (`deleted`). `ic sandbox doctor`, the setup wizard and the editor's recovery screen
+// read it.
+export const AnnounceStateSchema = z.object({
+    // off: nothing to register with; pending: the first attempt is in flight; registered: the platform took it;
+    // rejected: it answered no; unreachable: it could not be reached.
+    state: z.enum(["off", "pending", "registered", "rejected", "unreachable"]),
+    // Why, for the failing states, already in the owner's terms.
+    detail: z.string().optional(),
+    // On a failing state: false only once the platform said the sandbox was deleted; every other failure is retried.
+    retrying: z.boolean().optional(),
+    // Which no: `unknown` the platform has no record of this sandbox, and its owner's Reconnect can have it adopted;
+    // `deleted` it holds a deletion record, which ends the retrying.
+    reason: z.enum(["unknown", "deleted"]).optional(),
+    // The identity of the database that took the registration (the platform's GET /api/identity), when it said.
+    identity: z.string().optional(),
+    // When this state was last confirmed, ms since epoch.
+    at: z.number().optional(),
+});
+export type AnnounceState = z.infer<typeof AnnounceStateSchema>;
+
+// The owner's Reconnect: registers now, and with a ticket (the platform's adoption ticket, carried opaque), first asks a
+// platform that has no record of the sandbox to make one (its POST /sandbox/adopt). `name` and `image` are what the
+// owner's browser remembers of it, since only the platform held them.
+export const RelinkRequestSchema = z.object({
+    ticket: z.string().min(1).optional(),
+    name: z.string().max(60).optional(),
+    image: z.string().max(150_000).optional(),
+});
+export type RelinkRequest = z.infer<typeof RelinkRequestSchema>;
+
+export const RelinkAnswerSchema = z.object({
+    announce: AnnounceStateSchema,
+    // What the platform said to the adoption, when one was asked for and needed: its HTTP status (0 when it could not
+    // be reached) and its reason, in the owner's terms.
+    adoption: z.object({ status: z.number(), detail: z.string() }).optional(),
+});
+export type RelinkAnswer = z.infer<typeof RelinkAnswerSchema>;

package/src/schemas/privacy.ts

@@ -0,0 +1,204 @@
+// The privacy shield: personal data (names, national ids, document numbers, accounts…) kept away from model providers
+// the owner does not trust. The daemon puts a gateway between every runtime it can point at one and the provider, which
+// replaces what it finds with stable tokens on the way out and puts the real values back on the way in, so the agent
+// works on real data while an untrusted provider only ever reads tokens. Off unless the owner turns it on.
+
+import { z } from "zod";
+
+// What the shield looks for, one switch each. `known` values (a dataset the owner taught it) carry the class they were
+// taught under, so there is no class of their own.
+export const PERSONAL_DATA_CLASSES = [
+    "person-name",
+    "national-id",
+    "tax-id",
+    "identity-document",
+    "bank-account",
+    "payment-card",
+    "email",
+    "phone",
+    "address",
+] as const;
+export const PersonalDataClassSchema = z.enum(PERSONAL_DATA_CLASSES);
+export type PersonalDataClass = z.infer<typeof PersonalDataClassSchema>;
+
+// off: nothing is routed or read. watch: every shieldable turn goes through the gateway, which reads and records what it
+// would have masked and sends everything unchanged. on: untrusted providers get tokens, and a turn that cannot be
+// shielded (a runtime the gateway cannot sit in front of) is refused unless its provider is trusted.
+export const PrivacyShieldModeSchema = z.enum(["off", "watch", "on"]);
+export type PrivacyShieldMode = z.infer<typeof PrivacyShieldModeSchema>;
+
+// What an image bound for an untrusted provider becomes. mask: it is sent, with every stretch of its text the shield
+// reads on this machine (OCR) and finds to be personal data painted over with that value's token; one that cannot be
+// read is held back with a note, never sent unchecked. allow: sent as it is. (Before 2026-10, `withhold` sent a note
+// in place of every image and `read` sent its masked text instead of the picture; both read as `mask` now.)
+export const PrivacyImagesSchema = z.enum(["mask", "allow"]);
+export type PrivacyImages = z.infer<typeof PrivacyImagesSchema>;
+
+// How names are found. dictionary: the first-name and surname lists, with titles and inflection. model: those plus a
+// local named-entity model, where one is installed; without it, the dictionary alone.
+export const PrivacyNamesSchema = z.enum(["dictionary", "model"]);
+export type PrivacyNames = z.infer<typeof PrivacyNamesSchema>;
+
+export const PRIVACY_TRUSTED_MAX = 200;
+export const PRIVACY_ALLOW_MAX = 1000;
+export const PRIVACY_CONVERSATIONS_MAX = 200;
+
+// 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.
+export const PrivacyConversationTrustSchema = z.object({
+    conversationId: z.string().min(1).max(200),
+    provider: z.string().min(1).max(200).describe("Provider id, as the trusted list names it."),
+});
+export type PrivacyConversationTrust = z.infer<typeof PrivacyConversationTrustSchema>;
+
+export const PrivacyShieldPolicySchema = z.object({
+    mode: PrivacyShieldModeSchema.default("off").describe("Whether the shield is off, only watching, or masking."),
+    trusted: z
+        .array(z.string().min(1).max(200))
+        .max(PRIVACY_TRUSTED_MAX)
+        .default([])
+        .describe(
+            "Providers that may read personal data as it is, by provider id (`claude`, `codex`, `endpoint/<id>`). A local model is always trusted.",
+        ),
+    classes: z
+        .array(PersonalDataClassSchema)
+        .default([...PERSONAL_DATA_CLASSES])
+        .describe("Which kinds of personal data are looked for."),
+    images: PrivacyImagesSchema.default("mask").describe("What an image bound for an untrusted provider becomes."),
+    names: PrivacyNamesSchema.default("dictionary").describe("How names are found."),
+    allow: z
+        .array(z.string().min(1).max(200))
+        .max(PRIVACY_ALLOW_MAX)
+        .default([])
+        .describe("Values never masked: your own company, a public figure, a word the detector keeps mistaking for a name."),
+    conversations: z
+        .array(PrivacyConversationTrustSchema)
+        .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."),
+});
+export type PrivacyShieldPolicy = z.infer<typeof PrivacyShieldPolicySchema>;
+
+// Whether the owner let this provider read this conversation as it is. A turn outside any conversation (a helper job)
+// never is.
+export const trustedInConversation = (
+    policy: Pick<PrivacyShieldPolicy, "conversations">,
+    provider: string,
+    conversationId: string | undefined,
+): boolean => conversationId !== undefined && policy.conversations.some((entry) => entry.conversationId === conversationId && entry.provider === provider);
+
+// The policy with that grant made or taken back. A full list drops its oldest grant to make room, since the newest is
+// the one somebody is waiting on.
+export const withConversationTrust = (policy: PrivacyShieldPolicy, conversationId: string, provider: string, on: boolean): PrivacyShieldPolicy => {
+    const others = policy.conversations.filter((entry) => !(entry.conversationId === conversationId && entry.provider === provider));
+    return { ...policy, conversations: on ? [...others, { conversationId, provider }].slice(-PRIVACY_CONVERSATIONS_MAX) : others };
+};
+
+// The policy a sandbox that never wrote one runs on.
+export const DEFAULT_PRIVACY_SHIELD: PrivacyShieldPolicy = PrivacyShieldPolicySchema.parse({});
+
+// How a provider stands against the gateway, for the trusted list: whether its traffic can be shielded at all, and
+// whether it never leaves this machine.
+export const PrivacyProviderSchema = z.object({
+    id: z.string().describe("Provider id, as the trusted list names it."),
+    label: z.string(),
+    shieldable: z.boolean().describe("Its runtime can be put behind the gateway; one that cannot is refused while the shield is on, unless trusted."),
+    local: z.boolean().describe("It runs on this machine, so it is trusted whatever the list says."),
+});
+export type PrivacyProvider = z.infer<typeof PrivacyProviderSchema>;
+
+export const PrivacyShieldStatusSchema = z.object({
+    policy: PrivacyShieldPolicySchema,
+    known: z.number().int().describe("Values taught from your datasets, matched exactly wherever they appear."),
+    tokens: z.number().int().describe("Values the shield has given a token so far."),
+    readers: z.object({
+        ocr: z.boolean().describe("The local text reader (PaddleOCR) that finds personal data in images is installed."),
+        model: z.boolean().describe("A local named-entity model for names is installed."),
+    }),
+    providers: z.array(PrivacyProviderSchema),
+});
+export type PrivacyShieldStatus = z.infer<typeof PrivacyShieldStatusSchema>;
+
+// One request the gateway handled, as the log keeps it: counts and kinds, never a value.
+export const PrivacyLedgerActionSchema = z.enum(["masked", "watched", "passed", "refused"]);
+export type PrivacyLedgerAction = z.infer<typeof PrivacyLedgerActionSchema>;
+
+export const PrivacyLedgerEntrySchema = z.object({
+    at: z.string().describe("When, as an ISO timestamp."),
+    conversationId: z.string().optional(),
+    provider: z.string(),
+    trusted: z.boolean(),
+    action: PrivacyLedgerActionSchema,
+    counts: z.partialRecord(PersonalDataClassSchema, z.number().int()).describe("How many of each kind were found in what this request added."),
+    images: z.number().int().describe("Images the shield changed: personal data painted over, or held back when they could not be read."),
+    documents: z.number().int().describe("Documents replaced by their masked text."),
+    protocol: z.string().describe("Which wire format the request spoke."),
+    detail: z.string().optional().describe("Why it was refused, when it was."),
+});
+export type PrivacyLedgerEntry = z.infer<typeof PrivacyLedgerEntrySchema>;
+
+// A dataset taught to the shield: each value is matched exactly from then on, in every form it is written.
+export const PRIVACY_KNOWN_BATCH_MAX = 50_000;
+
+export const PrivacyKnownValueSchema = z.object({
+    value: z.string().min(2).max(500),
+    class: PersonalDataClassSchema,
+});
+export type PrivacyKnownValue = z.infer<typeof PrivacyKnownValueSchema>;
+
+export const PrivacyKnownSourceSchema = z.object({
+    source: z.string().describe("Where the values came from, as whoever taught them named it."),
+    count: z.number().int(),
+    at: z.string().describe("When they were last taught."),
+});
+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.
+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."),
+    languages: z.array(z.enum(["pl", "en"])).describe("The languages its words come from."),
+    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."),
+    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(),
+});
+export type PrivacyNameList = z.infer<typeof PrivacyNameListSchema>;
+
+// What the lists say of one word.
+export const PrivacyNameWordSchema = z.object({
+    word: z.string(),
+    firstName: z.boolean().describe("A listed first name, in this form or as an inflection of one."),
+    surname: z.boolean().describe("A listed surname, in this form or as an inflection of one."),
+    surnameForm: z.boolean().describe("Shaped like a Polish surname (-ski, -cki, -wicz…), listed or not."),
+    ambiguous: z.boolean().describe("Also an ordinary word, so found only beside other evidence (a surname, a title)."),
+    never: z.boolean().describe("Never taken as part of a name (a title, an institution, a function word)."),
+});
+export type PrivacyNameWord = z.infer<typeof PrivacyNameWordSchema>;
+
+// What the dictionary makes of a word or a full name, for checking whether it would be found.
+export const PrivacyNameLookupSchema = z.object({
+    text: z.string().describe("The query as a name is written: each word capitalized."),
+    found: z.boolean().describe("Whether the dictionary alone masks it as a name, written so on its own."),
+    words: z.array(PrivacyNameWordSchema),
+});
+export type PrivacyNameLookup = z.infer<typeof PrivacyNameLookupSchema>;
+
+export const PRIVACY_DICTIONARY_SAMPLE_MAX = 200;
+
+export const PrivacyDictionarySchema = z.object({
+    lists: z.array(PrivacyNameListSchema),
+    totals: z
+        .object({ firstNames: z.number().int(), surnames: z.number().int() })
+        .describe("Distinct words across the first-name lists, and across the surname lists."),
+    // Words of the lists that start with a one-word query, for browsing; empty without one.
+    matches: z.array(z.object({ word: z.string(), lists: z.array(z.string()).describe("Ids of the lists holding it.") })),
+    // The query read as a name, when there is one.
+    lookup: PrivacyNameLookupSchema.optional(),
+});
+export type PrivacyDictionary = z.infer<typeof PrivacyDictionarySchema>;