@intentic/sandbox-contract 1.333.1 → 1.335.0

package/src/protocol/doors/listener-protocol.ts

@@ -1,14 +1,15 @@
 import { z } from "zod";
+import type { ToolKind } from "../../events/requests.js";
 import { ActivityStatusSchema } from "../../schemas/activity.js";
 import { rawRouteUrl } from "../raw/raw-routes.js";
 
 // Wire between the daemon and an extension's realtime-listener gateway (ext-discord, ext-slack, ext-telegram,
-// ext-whatsapp, ext-imap, ext-google-workspace): the four /listeners/:provider routes (state, dispatch, failure,
-// status). Shared here so both ends compile against one declaration.
+// ext-whatsapp, ext-imap, ext-google-workspace): the five /listeners/:provider routes (state, dispatch, failure,
+// status, stop). Shared here so both ends compile against one declaration.
 
-// The path of one of the four listener routes for a provider, built from RAW_ROUTES so the gateway and the daemon
+// The path of one of the five listener routes for a provider, built from RAW_ROUTES so the gateway and the daemon
 // cannot spell it two ways.
-export const listenerRouteUrl = (route: "state" | "dispatch" | "failure" | "status", provider: string): string =>
+export const listenerRouteUrl = (route: "state" | "dispatch" | "failure" | "status" | "stop", provider: string): string =>
     route === "state"
         ? rawRouteUrl("GET /listeners/{provider}/state", { provider })
         : rawRouteUrl(`POST /listeners/{provider}/${route}`, { provider });
@@ -39,7 +40,14 @@ export const ListenerMessageSchema = z.object({
     provider: z.string().min(1),
     type: z.string().min(1),
     id: z.string(),
+    // The room the message was posted in, as an automation's channel filter names it: for a message inside a thread,
+    // the channel the thread hangs off.
     channelId: z.string(),
+    // The thread inside that channel the message belongs to, by the provider's own id: a Discord thread's channel id (a
+    // thread started from a message carries that message's id, so a mention names the thread its answer will open), a
+    // Slack thread's root ts. One conversation per thread, and where the reply goes. Absent, the channel is the
+    // conversation.
+    thread: z.string().min(1).optional(),
     // `id` is what the service vouches for and what sender rules match; `name` is display only. `groups` are the
     // service's own group ids on this sender (Discord role ids), absent on a source without them.
     author: z.object({ id: z.string(), name: z.string(), groups: z.array(z.string()).optional() }),
@@ -64,16 +72,76 @@ export const ListenerMessageSchema = z.object({
 });
 export type ListenerMessage = z.infer<typeof ListenerMessageSchema>;
 
-// One ndjson frame of a /listeners/<provider>/dispatch?stream=1 response: a text delta, a failure sentence, or a
-// terminal marker. A type, not a schema, since only the daemon produces these.
+// The turn a message started or continued: the conversation it runs in, and where a person opens it in the app.
+export interface ListenerTurnOpened {
+    readonly conversationId: string;
+    readonly link?: string;
+}
+
+// One piece of the agent's work as a status line shows it: what kind of work, on what, and how it went. Never the
+// call's output. `delegate` is a subagent the turn started, its target the task it was given.
+export interface ListenerStep {
+    readonly id: string;
+    readonly tool: string;
+    readonly kind: ToolKind | "delegate";
+    readonly target?: string;
+    readonly status: "running" | "done" | "failed";
+}
+
+// One item of the agent's own checklist, replaced whole each time the agent rewrites it.
+export interface ListenerPlanItem {
+    readonly text: string;
+    readonly status: "pending" | "in_progress" | "completed";
+}
+
+// One ndjson frame of a /listeners/<provider>/dispatch?stream=1 response, per matched automation: the reply's text, the
+// turn's progress, or how the message was taken. A type, not a schema, since only the daemon produces these; every field
+// but `automationId` is optional, so a gateway older than one of them reads the rest.
 export interface ListenerDispatchFrame {
     readonly automationId: string;
+    // The reply's text as the model writes it, the turn's own words only (a subagent's stay in the conversation).
     readonly delta?: string;
     // The turn's failure, forwarded verbatim since a gateway delivers it into the owner's own channel.
     readonly failed?: string;
+    // A turn began for this message; sent once, before any of its work.
+    readonly opened?: ListenerTurnOpened;
+    // A tool call starting or settling, keyed by `id`: a later frame with the same id replaces the earlier one.
+    readonly step?: ListenerStep;
+    // The agent's checklist as it now stands.
+    readonly plan?: readonly ListenerPlanItem[];
+    // The wake waits for a person's approval before anything runs; the sentence to say where the message came from.
+    readonly held?: string;
+    // The wake waits for other turns of this automation to finish first; the sentence to say why.
+    readonly queued?: string;
+    // The message went into the turn already running in its thread instead of starting one; that turn answers it.
+    readonly steered?: boolean;
     readonly end?: boolean;
 }
 
+// The body the daemon POSTs to a gateway's loopback /deliver: a message to post outside any live turn, into a channel by
+// the provider's own id, and into the thread inside it the conversation lives in, when it lives in one.
+export const ListenerDeliverSchema = z.object({
+    channelId: z.string().min(1),
+    text: z.string().min(1),
+    thread: z.string().min(1).optional(),
+});
+export type ListenerDeliver = z.infer<typeof ListenerDeliverSchema>;
+
+// The body of POST /listeners/<provider>/stop: which conversation's running turn to stop, and who in the channel asked,
+// as the gateway vouches for them. The daemon lets them only if the automation's sender rules would let them talk to it
+// without a person's approval.
+export const ListenerStopSchema = z.object({
+    conversationId: z.string().min(1),
+    author: z.object({ id: z.string(), name: z.string(), groups: z.array(z.string()).optional() }),
+});
+export type ListenerStop = z.infer<typeof ListenerStopSchema>;
+
+// What the stop route answers: whether a turn was stopped, and the sentence to show the person when it was not.
+export interface ListenerStopAnswer {
+    readonly stopped: boolean;
+    readonly reason?: string;
+}
+
 // Where a device-linking ceremony stands (whatsapp), reported per status tick; every state here means not yet paired.
 // `since` stamps the current code's age, since WhatsApp reissues a fresh one on each reopen.
 export const ListenerPairingSchema = z.object({

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

@@ -15,7 +15,7 @@ import {
 import { SyncStatusSchema } from "../../schemas/devices.js";
 import { HostsListSchema } from "../../schemas/hosts.js";
 import { VoicesViewSchema } from "../../schemas/voice.js";
-import { MemberEmailSchema, MemberGrantSchema, MembersListSchema, MembersRosterSchema } from "../../schemas/members.js";
+import { MemberEmailSchema, MemberGrantSchema, MemberSelfSchema, MembersListSchema, MembersRosterSchema } from "../../schemas/members.js";
 import { PhonesListSchema, PhoneWakeRegistrationSchema } from "../../schemas/phone.js";
 import { OkSchema } from "../../schemas/shared.js";
 import { EnrollCodeAnswerSchema, EnrollCodeRequestSchema, PeerPairingAnswerSchema, SyncPairAnswerSchema, SyncPairRequestSchema } from "../../schemas/short-codes.js";
@@ -75,6 +75,7 @@ export const RAW_JSON_ROUTES = {
     "POST /members": { input: MemberGrantSchema, output: MembersListSchema },
     "DELETE /members": { input: MemberEmailSchema, output: MembersListSchema },
     "DELETE /members/self": { output: OkSchema },
+    "GET /members/self": { output: MemberSelfSchema },
     // Every environment write answers the environment after it. `/environment/contents` takes `?refresh` to probe again.
     "GET /environment": { output: EnvironmentSchema },
     "GET /environment/contents": { output: EnvironmentContentsSchema },

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

@@ -79,6 +79,8 @@ export const RAW_ROUTES = {
     "POST /members": { control: "never" },
     "DELETE /members": { control: "never" },
     "DELETE /members/self": { floor: "viewer", guest: true, control: "never" },
+    // What one's own grant allows, read by the editor to offer only what will be taken.
+    "GET /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": {},
@@ -126,6 +128,8 @@ export const RAW_ROUTES = {
     // The `agents` CLI's children: start, follow up, answer (never a consent card), cancel, merge held work, list.
     "POST /children/spawn": { agent: true, control: "never" },
     "GET /children/providers": { agent: true, control: "never" },
+    // Marking a provider's model spent (or clearing the mark) by hand, for a plan that publishes no allowance to read.
+    "POST /children/providers/spent": { agent: true, control: "never" },
     "POST /children/wait": { agent: true, control: "never" },
     "POST /children/send": { agent: true, control: "never" },
     "POST /children/answer": { agent: true, control: "never" },
@@ -153,6 +157,9 @@ export const RAW_ROUTES = {
     "POST /listeners/{provider}/dispatch": { panel: false, control: "never" },
     "POST /listeners/{provider}/failure": { panel: false, control: "never" },
     "POST /listeners/{provider}/status": { panel: false, control: "never" },
+    // A person in the channel pressing Stop on a turn that channel started; the handler asks the automation's own
+    // sender rules whether that person may.
+    "POST /listeners/{provider}/stop": { panel: false, control: "never" },
     // What an extension's own code asks about itself (extension-protocol.ts): its settings with their secrets, and its
     // event stream. Every extension token reaches both undeclared, and each answers only about the extension asking, so
     // no other credential reaches them; the handler resolves the caller from its token again.

package/src/schemas/activity.ts

@@ -1,8 +1,8 @@
 // Activity audit log schemas (historyRoot/activity.jsonl).
 import { z } from "zod";
 import { AgentOriginSchema } from "./agent.js";
-// One provider-agnostic event per agent↔provider interaction, appended only by the daemon; the log lives outside /work,
-// so an agent can't read or rewrite its own trail.
+// One provider-agnostic event per agent↔provider interaction, appended only by the daemon; the log lives outside /work.
+// It is not tamper-evident (an unfenced agent can reach /history); the hash-chained audit trail (audit.ts) is.
 
 export const ActivityEventSchema = z.object({
     id: z.string().describe("The entry's own id."),

package/src/schemas/agent.ts

@@ -1,6 +1,7 @@
 import { TurnErrandSchema } from "./speaker.js";
 import { z } from "zod";
 import { CONVERSATION_ID } from "../ids/conversation-ids.js";
+import { canonicalHarness } from "../models/agent-catalog.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
 import { NATIVE_PROVIDERS } from "../models/provider-specs.js";
 import { AgentPlacementSchema } from "../protocol/doors/runner-protocol.js";
@@ -14,9 +15,14 @@ export type AgentProvider = z.infer<typeof AgentProviderSchema>;
 // Provider naming a catalog in providers.contract.ts; an enum, not the open string above, since only native providers
 // have a daemon-held catalog to look up. An unknown id is a 400 here, not an empty list.
 export const NativeProviderParamSchema = z.object({ provider: z.enum(NATIVE_PROVIDERS) });
-// The harness (agentic loop) a turn runs on, orthogonal to the provider.
-export const AgentHarnessSchema = z.enum(["native", "claude-code"]);
+// The harness (agentic loop) a turn runs on, orthogonal to the provider. `native` is an alias for whichever loop the
+// provider runs by default; every other value names a loop outright. `vendor` is the provider's own agent where that is
+// none of the named host loops (Cursor's SDK, the Devin CLI, an installed ACP agent). Which loops a provider offers is
+// its row's `loops` (models/provider-specs.ts); values are only ever appended, since stored turns and pins carry them.
+export const AgentHarnessSchema = z.enum(["native", "claude-code", "codex", "opencode", "pi", "muse", "vendor"]);
 export type AgentHarness = z.infer<typeof AgentHarnessSchema>;
+// A loop named outright, as a provider row offers it; `native` only ever resolves to one of these (loopOf).
+export type AgentLoop = Exclude<AgentHarness, "native">;
 // One repo at one immutable commit; used both as the checkout instruction and as handoffs' comparison base, so a
 // multi-repo run has one provenance record instead of a hard-coded branch name.
 export const RepoBaseSchema = z.object({ repo: z.string(), base: z.string().min(1) });
@@ -53,6 +59,9 @@ export const AgentOriginSchema = z.object({
     provider: z.string(),
     // External thread it arrived on (Discord channel id, widget conversation id); absent for webhooks.
     channelId: z.string().optional(),
+    // The thread inside that channel (a Discord thread, a Slack thread's root ts), when the conversation is one; what is
+    // said back between turns goes into it rather than onto the channel.
+    threadId: z.string().optional(),
     // Who sent it, as the source names them.
     author: z.string().optional(),
 });
@@ -169,8 +178,8 @@ const AgentTurnFieldsSchema = z.object({
         ),
     // Which provider serves the turn, absent = claude; a sessionId resumes only on the provider that minted it.
     agent: AgentProviderSchema.optional().describe("Which model provider serves this turn. Leave it out for Claude."),
-    // Which agentic loop runs the turn, absent = provider's own; "claude-code" forces the SDK loop for any
-    // provider.
+    // Which agentic loop runs the turn, absent = provider's own; a loop the provider doesn't offer runs its own too
+    // (withRuntimeDefaults), rather than refusing a turn a stale composer setting named.
     harness: AgentHarnessSchema.optional().describe("Which agentic loop runs the turn. Leave it out to use each provider's own."),
     // Intent, not a guess: absent continues on the conversation's own account, or picks by serviceability where there is
     // none on this provider yet (agent/providers/accounts/routing.ts).
@@ -376,13 +385,17 @@ export const AgentRunSchema = AgentTurnSchema.safeExtend({
 export type RoutedAgentTurn = AgentTurn & { readonly agent: AgentProvider; readonly harness: AgentHarness };
 export const DEFAULT_PROVIDER: AgentProvider = "claude";
 export const DEFAULT_HARNESS: AgentHarness = "native";
+// A loop the provider does not offer is not the loop that runs (capabilitiesOf answers its own runtime either way), so the
+// turn is named for the one that does: one composer setting left on Claude Code must not stamp "claude-code" on a Cursor,
+// Google or Devin turn's profile, transcript and ledger row.
+// Naming the provider's default loop outright is the same turn as naming none, so it is stamped `native` too: one turn,
+// one spelling, whichever way the request put it.
 export const withRuntimeDefaults = <T extends { readonly agent?: AgentProvider | undefined; readonly harness?: AgentHarness | undefined }>(
     turn: T,
-): T & { readonly agent: AgentProvider; readonly harness: AgentHarness } => ({
-    ...turn,
-    agent: turn.agent ?? DEFAULT_PROVIDER,
-    harness: turn.harness ?? DEFAULT_HARNESS,
-});
+): T & { readonly agent: AgentProvider; readonly harness: AgentHarness } => {
+    const agent = turn.agent ?? DEFAULT_PROVIDER;
+    return { ...turn, agent, harness: canonicalHarness(agent, turn.harness) };
+};
 // Which turn this is, as opposed to what it says: who serves it and how (agent, harness, account, model and its knobs),
 // as whom (actsAs), where (isolated), whether anyone watches (unattended) and for which job (runRole). A turn that
 // continues another (a resume, a wake, a nudge, a child's follow-up) carries this whole, never a hand-picked part.

package/src/schemas/ai-literacy.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+export const AI_LITERACY_TEXT = {
+    en: "You are working with an AI assistant. It can be wrong or invent facts, legal references and quotations. Check important claims against their sources. You remain responsible for decisions and anything you send. Share only the personal data needed for the task. Follow your office's rules for using AI. Report problems to the sandbox owner.",
+    pl: "Pracujesz z asystentem AI. Może się mylić lub wymyślać fakty, przepisy i cytaty. Ważne informacje sprawdzaj w źródłach. Odpowiadasz za swoje decyzje i za to, co wysyłasz. Podawaj tylko dane osobowe potrzebne do zadania. Stosuj zasady korzystania z AI obowiązujące w urzędzie. Problemy zgłaszaj osobie, która zarządza tym sandboxem.",
+    de: "Sie arbeiten mit einem KI-Assistenten. Er kann Fehler machen oder Fakten, Rechtsverweise und Zitate erfinden. Prüfen Sie wichtige Aussagen anhand der Quellen. Sie sind für Entscheidungen und versendete Inhalte verantwortlich. Geben Sie nur personenbezogene Daten ein, die für die Aufgabe nötig sind. Beachten Sie die KI-Regeln Ihrer Dienststelle. Melden Sie Probleme der verantwortlichen Person für diesen Arbeitsbereich.",
+    fr: "Vous travaillez avec un assistant IA. Il peut se tromper ou inventer des faits, des références juridiques et des citations. Vérifiez les points importants dans les sources. Vous restez responsable de vos décisions et de ce que vous envoyez. Ne saisissez que les données personnelles nécessaires à la tâche. Respectez les règles de votre service sur l'IA. Signalez les problèmes au responsable de cet espace.",
+    es: "Trabaja con un asistente de IA. Puede equivocarse o inventar hechos, referencias legales y citas. Compruebe los datos importantes en sus fuentes. Usted sigue siendo responsable de sus decisiones y de lo que envía. Introduzca solo los datos personales necesarios para la tarea. Siga las normas de su oficina sobre el uso de IA. Informe de los problemas a quien administra este espacio.",
+} as const;
+export const AiLiteracyLocaleSchema = z.enum(["en", "pl", "de", "fr", "es"]);
+// The read names its language in the path, which an OpenAPI route takes from an object keyed by the parameter.
+export const AiLiteracyQuerySchema = z.object({ locale: AiLiteracyLocaleSchema });
+export const AiLiteracyConfirmSchema = z.object({ version: z.string().length(64), locale: AiLiteracyLocaleSchema });
+export const AiLiteracyStatusSchema = z.object({ show: z.boolean(), text: z.string(), version: z.string(), confirmedAt: z.string().optional() });
+export const AiLiteracyRecordSchema = z.object({ member: z.string(), version: z.string(), confirmedAt: z.string() });
+export type AiLiteracyRecord = z.infer<typeof AiLiteracyRecordSchema>;
+export const AiLiteracyListSchema = z.object({ records: z.array(AiLiteracyRecordSchema) });

package/src/schemas/audit.ts

@@ -0,0 +1,131 @@
+// audit: the sandbox's audit trail (historyRoot/audit/), who changed a policy, a member, a secret's gate or a setting,
+// who signed in, and (when `settings.audit.recordReads` is on) who read what. Separate from the activity log, which
+// records what team-chat bots sent and received. Every record carries the hash of the one before it, so a record
+// changed, removed or inserted afterwards breaks the chain at that point, and /audit/verify names where.
+import { z } from "zod";
+
+// Who did it, as the daemon verified it, never as a client said it. A member is named by the address they signed in
+// with and the tier they held at that moment; a program by its control token; an agent by its conversation; the
+// sandbox itself (a retention sweep, a boot) as `system`.
+export const AuditActorSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("member"),
+        email: z.string().describe("The address they signed in with, lowercased."),
+        role: z.string().describe("Their tier at the moment they acted: owner, maintainer, writer, collaborator, viewer or guest."),
+    }),
+    z.object({
+        kind: z.literal("token"),
+        id: z.string().describe("The control token's id."),
+        label: z.string().describe("The name its owner gave the token."),
+    }),
+    z.object({ kind: z.literal("agent"), conversationId: z.string().describe("The conversation whose agent did it.") }),
+    z.object({
+        kind: z.literal("system"),
+        reason: z.string().optional().describe("What part of the sandbox acted, such as a retention sweep or a change found in a file."),
+    }),
+]);
+export type AuditActor = z.infer<typeof AuditActorSchema>;
+
+export const AUDIT_ACTION_MAX = 120;
+export const AUDIT_TARGET_MAX = 500;
+
+// What a module hands services.audit.record: the daemon fills in the id, the time and the chain.
+export const AuditEventSchema = z.object({
+    actor: AuditActorSchema,
+    action: z
+        .string()
+        .min(1)
+        .max(AUDIT_ACTION_MAX)
+        .describe("What happened, as a dotted name: settings.change, member.grant, secret.gate.set, auth.sign_in, conversation.read."),
+    target: z.string().max(AUDIT_TARGET_MAX).optional().describe("What it happened to: a member's address, a secret's name, a conversation id, a file's path."),
+    outcome: z.enum(["ok", "refused", "failed"]).optional().describe("How it ended. Absent means it succeeded."),
+    details: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("A few facts that make the record readable: which settings changed, a new role. Never a secret's value, and as little personal data as will do."),
+});
+export type AuditEvent = z.infer<typeof AuditEventSchema>;
+
+// One line of a segment. `v` is the record format, so a later build that adds a field still verifies an older line:
+// the hash is over exactly the fields the line holds.
+export const AuditRecordSchema = AuditEventSchema.extend({
+    v: z.literal(1).describe("The record format."),
+    id: z.string().describe("The record's own id."),
+    at: z.number().describe("When it was written, in milliseconds since 1970. Strictly increasing, so it is also what you page by."),
+    prevHash: z.string().describe("The hash of the record before it, or of the checkpoint left by pruning, or 64 zeros for the first record ever written."),
+    hash: z.string().describe("SHA-256, in hex, over this record's canonical JSON without `hash` itself."),
+});
+export type AuditRecord = z.infer<typeof AuditRecordSchema>;
+
+export const AuditQuerySchema = z.object({
+    from: z.coerce.number().optional().describe("Only records written at or after this time, in milliseconds."),
+    to: z.coerce.number().optional().describe("Only records written before this time, in milliseconds."),
+    action: z.string().max(AUDIT_ACTION_MAX).optional().describe("Only actions starting with this, such as `member.` or `settings.change`."),
+    actor: z.string().max(200).optional().describe("Only records whose actor's address, token name or conversation id contains this."),
+    target: z.string().max(AUDIT_TARGET_MAX).optional().describe("Only records whose target contains this."),
+    before: z.coerce.number().optional().describe("Paging cursor: only records written before this time. Pass the previous page's `next`."),
+    limit: z.coerce.number().int().min(1).max(500).default(100).describe("How many records to return."),
+});
+export type AuditQuery = z.infer<typeof AuditQuerySchema>;
+
+export const AuditListSchema = z.object({
+    records: z.array(AuditRecordSchema).describe("The records, newest first."),
+    next: z.number().optional().describe("The cursor for the next, older page. Absent on the last page."),
+});
+export type AuditList = z.infer<typeof AuditListSchema>;
+
+export const AuditVerifySchema = z.object({
+    ok: z.boolean().describe("Whether every record kept is intact and in an unbroken chain."),
+    checked: z.number().describe("How many records were checked."),
+    segments: z.number().describe("How many monthly files were checked."),
+    prunedThrough: z
+        .object({ at: z.number(), hash: z.string() })
+        .optional()
+        .describe("Where the kept chain starts: the time and hash of the last record retention deleted. Absent while nothing was ever deleted."),
+    broken: z
+        .object({
+            segment: z.string().describe("The monthly file it is in."),
+            line: z.number().describe("Its line number in that file, from 1."),
+            id: z.string().optional().describe("The record's id, when the line could still be read."),
+            at: z.number().optional().describe("When the record says it was written."),
+            reason: z
+                .enum(["unreadable", "hash-mismatch", "chain-break"])
+                .describe(
+                    "unreadable: the line is not a record. hash-mismatch: the record was changed after it was written. chain-break: a record before it was removed, inserted or reordered.",
+                ),
+        })
+        .optional()
+        .describe("The first record that does not check out. Absent when the chain is whole."),
+    torn: z.boolean().describe("Whether the newest file ends in a half-written line, which a crash mid-write leaves. It is skipped, not counted as tampering."),
+});
+export type AuditVerify = z.infer<typeof AuditVerifySchema>;
+
+export const AuditExportQuerySchema = z.object({
+    from: z.coerce.number().describe("The first moment to include, in milliseconds."),
+    to: z.coerce.number().describe("The moment to stop before, in milliseconds."),
+});
+export type AuditExportQuery = z.infer<typeof AuditExportQuerySchema>;
+
+export const AuditExportSchema = z.object({
+    filename: z.string().describe("A file name to save it under."),
+    jsonl: z.string().describe("The records, one JSON object per line, oldest first, exactly as stored, so the hashes still check out."),
+    count: z.number().describe("How many records it holds."),
+});
+export type AuditExport = z.infer<typeof AuditExportSchema>;
+
+// The forwarder's state, so the settings page can say whether the outside copy is keeping up.
+export const AuditStatusSchema = z.object({
+    forwarding: z
+        .object({
+            url: z.string().describe("Where records are sent."),
+            pending: z.number().describe("How many records are waiting to be sent."),
+            lastSentAt: z.number().optional().describe("When the last record reached it."),
+            lastError: z.string().optional().describe("Why the last attempt failed, when it did."),
+            nextAttemptAt: z.number().optional().describe("When the next attempt is due, while it is backing off."),
+        })
+        .optional()
+        .describe("Absent while no forward address is set."),
+    oldestAt: z.number().optional().describe("When the oldest record kept was written."),
+    segments: z.array(z.string()).describe("The monthly files kept, oldest first."),
+});
+export type AuditStatus = z.infer<typeof AuditStatusSchema>;

package/src/schemas/automations.ts

@@ -253,6 +253,17 @@ export const WebchatConfigSchema = z.object({
     // How long a visitor thread resumes the same conversation before a new message starts a fresh one; absent uses the
     // daemon's own default.
     sessionTtlMinutes: z.number().int().positive().optional(),
+    // The AI Act (Art. 50(1)) has a person told they are talking to an AI unless it is obvious. Absent means shown, since
+    // a one-line label costs nothing and leaving it out is the decision that needs making on purpose.
+    aiDisclosure: z
+        .boolean()
+        .optional()
+        .describe("Tell visitors, in the panel, that the replies come from an AI. Absent means on."),
+    aiDisclosureText: z
+        .string()
+        .max(300)
+        .optional()
+        .describe("Your own wording for that line. Absent uses the built-in one in the visitor's language."),
 });
 export type WebchatConfig = z.infer<typeof WebchatConfigSchema>;
 // Default daily agent-turn ceiling for an unconfigured Visitor chat; high enough for real traffic, low enough to blunt a
@@ -276,6 +287,8 @@ export const WebchatPublicConfigSchema = z.object({
     antiBot: z.enum(["turnstile", "pow", "off"]),
     turnstileSiteKey: z.string().optional(),
     googleClientId: z.string().optional(),
+    aiDisclosure: z.boolean(),
+    aiDisclosureText: z.string().optional(),
 });
 export type WebchatPublicConfig = z.infer<typeof WebchatPublicConfigSchema>;
 // A proof-of-work challenge: find a nonce whose SHA-256 of `${salt}:${nonce}` starts with `difficulty` zero bits. One

package/src/schemas/compliance.ts

@@ -0,0 +1,195 @@
+// compliance: what a data protection officer (in Poland, the IOD) needs before a sandbox handles anyone's personal data,
+// read off the sandbox's LIVE configuration rather than written from memory. Three answers: where data can leave
+// (`flows`), what protects it (`measures`), and the documents an office files about it (the record of processing under
+// GDPR Art. 30, the impact assessment under Art. 35, the technical and organisational measures under Art. 32). Plus the
+// public-office preset: a list of stricter settings, each shown as current → proposed, applied only item by item on
+// request. Nothing here changes a default; a sandbox that never opens the page behaves as it did before it existed.
+import { z } from "zod";
+
+export const ComplianceLanguageSchema = z.enum(["pl", "en"]);
+export type ComplianceLanguage = z.infer<typeof ComplianceLanguageSchema>;
+
+// The groups the data-flow page draws, in this order.
+export const DATA_FLOW_GROUPS = ["models", "messaging", "connectors", "speech", "web", "platform", "maintenance", "analytics"] as const;
+export const DataFlowGroupSchema = z.enum(DATA_FLOW_GROUPS);
+export type DataFlowGroup = z.infer<typeof DataFlowGroupSchema>;
+
+// One kind per outbound path the code has; the editor and the documents both word each kind in the reader's language,
+// so the daemon sends the kind and the facts, never a sentence.
+export const DATA_FLOW_KINDS = [
+    "model-provider",
+    "model-endpoint",
+    "local-model",
+    "email-imap",
+    "email-smtp",
+    "team-chat",
+    "webchat",
+    "connector",
+    "speech",
+    "web-search",
+    "web-fetch",
+    "browser",
+    "platform-link",
+    "ingress",
+    "update-check",
+    "model-download",
+    "product-analytics",
+    "push-notifications",
+] as const;
+export const DataFlowKindSchema = z.enum(DATA_FLOW_KINDS);
+export type DataFlowKind = z.infer<typeof DataFlowKindSchema>;
+
+// Whether personal data can ride this path: `yes` when it carries what people wrote, `possible` when only what an agent
+// chose to send or look up, `no` when it carries only the sandbox's own metadata.
+export const PersonalDataReachSchema = z.enum(["yes", "possible", "no"]);
+export type PersonalDataReach = z.infer<typeof PersonalDataReachSchema>;
+
+// What the privacy shield does on this path: `masked` (personal data becomes tokens before it leaves), `trusted` (the
+// shield is on but lets this destination read values as they are), `watched` (the shield only records), `local` (it
+// never leaves the machine), `blocked` (the shield is on and refuses what it cannot read, so nothing is sent unmasked),
+// `none` (the shield does not sit on this path, or is off).
+export const ShieldCoverSchema = z.enum(["masked", "trusted", "watched", "local", "blocked", "none"]);
+export type ShieldCover = z.infer<typeof ShieldCoverSchema>;
+
+export const DataFlowSchema = z.object({
+    id: z.string().describe("Stable id of this path, such as `model-provider:claude` or `team-chat:discord`."),
+    group: DataFlowGroupSchema,
+    kind: DataFlowKindSchema,
+    name: z.string().describe("The destination's own name, such as Anthropic Claude or a connector's title. Proper nouns only."),
+    hosts: z.array(z.string()).describe("The hosts data is sent to, as configured. Empty when the code cannot know them in advance."),
+    operator: z.string().optional().describe("Who runs the destination, where known."),
+    region: z.string().optional().describe("Where it is processed, as far as the operator says: `EU`, `US`, `this machine`, or a hosting region."),
+    thirdCountry: z
+        .boolean()
+        .optional()
+        .describe("True when the operator processes the data outside the European Economic Area, which makes this a transfer to a third country."),
+    active: z.boolean().describe("Whether this path is in use now. An inactive one is listed because a single switch would open it."),
+    personalData: PersonalDataReachSchema,
+    shield: ShieldCoverSchema,
+    switch: z
+        .string()
+        .optional()
+        .describe("What opens or closes this path: a settings key (`productAnalytics`), a page, or an environment variable."),
+    question: z
+        .string()
+        .optional()
+        .describe("Set when the sandbox cannot tell something about this path and the office must answer it, as a short key the editor words."),
+});
+export type DataFlow = z.infer<typeof DataFlowSchema>;
+
+// `on`: in place. `partial`: in place for some of what it covers. `off`: available, switched off. `unavailable`: this
+// sandbox cannot offer it as it runs now. `unknown`: outside what the sandbox can see (backups), so the office says.
+export const MeasureStatusSchema = z.enum(["on", "partial", "off", "unavailable", "unknown"]);
+export type MeasureStatus = z.infer<typeof MeasureStatusSchema>;
+
+export const MEASURE_IDS = [
+    "privacy-shield",
+    "privacy-images",
+    "privacy-names",
+    "trusted-providers",
+    "local-models",
+    "member-roles",
+    "areas",
+    "guest-jail",
+    "sign-in",
+    "action-rules",
+    "admission",
+    "command-judge",
+    "credential-gates",
+    "host-guards",
+    "retention",
+    "audit",
+    "audit-reads",
+    "audit-forward",
+    "encryption-at-rest",
+    "encryption-in-transit",
+    "agent-domain",
+    "product-analytics",
+    "ai-notice",
+    "webchat-ai-disclosure",
+    "backups",
+] as const;
+export const MeasureIdSchema = z.enum(MEASURE_IDS);
+export type MeasureId = z.infer<typeof MeasureIdSchema>;
+
+// The TOMs categories of GDPR Art. 32(1) the documents sort measures under.
+export const MeasureCategorySchema = z.enum(["confidentiality", "minimisation", "integrity", "accountability", "transparency", "availability"]);
+export type MeasureCategory = z.infer<typeof MeasureCategorySchema>;
+
+export const MeasureSchema = z.object({
+    id: MeasureIdSchema,
+    category: MeasureCategorySchema,
+    status: MeasureStatusSchema,
+    facts: z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+        .describe("The configured values behind the status, such as `{ mode: \"on\", trusted: 2 }`, for the reader to word."),
+    preset: z.boolean().describe("The public-office preset changes this measure."),
+});
+export type Measure = z.infer<typeof MeasureSchema>;
+
+export const ComplianceReportSchema = z.object({
+    generatedAt: z.string().describe("When this was read, as an ISO timestamp."),
+    flows: z.array(DataFlowSchema),
+    measures: z.array(MeasureSchema),
+});
+export type ComplianceReport = z.infer<typeof ComplianceReportSchema>;
+
+export const ComplianceDocumentKindSchema = z.enum(["ropa", "dpia", "toms"]);
+export type ComplianceDocumentKind = z.infer<typeof ComplianceDocumentKindSchema>;
+export const ComplianceDocumentFormatSchema = z.enum(["md", "docx"]);
+export type ComplianceDocumentFormat = z.infer<typeof ComplianceDocumentFormatSchema>;
+
+export const ComplianceDocumentQuerySchema = z.object({
+    kind: ComplianceDocumentKindSchema.describe("ropa: the record of processing activities entry. dpia: the impact assessment draft. toms: the measures."),
+    language: ComplianceLanguageSchema.default("pl").describe("pl or en."),
+    format: ComplianceDocumentFormatSchema.default("md").describe("md for Markdown text, docx for a Word document."),
+});
+export type ComplianceDocumentQuery = z.input<typeof ComplianceDocumentQuerySchema>;
+
+export const ComplianceDocumentSchema = z.object({
+    filename: z.string(),
+    mediaType: z.string(),
+    encoding: z.enum(["utf8", "base64"]).describe("utf8 for Markdown, base64 for a Word document's bytes."),
+    content: z.string(),
+});
+export type ComplianceDocument = z.infer<typeof ComplianceDocumentSchema>;
+
+// The preset. Each item is one setting, keyed by where it lives: `privacy.mode`, `retention.transcriptDays`,
+// `actionRules.discord.message.send`, `admission.webchat`. A value absent today (an action rule nobody wrote) is null.
+export const PresetValueSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export type PresetValue = z.infer<typeof PresetValueSchema>;
+
+export const PRESET_GROUPS = ["privacy", "retention", "audit", "analytics", "notice", "actions", "admission", "judge"] as const;
+export const PresetGroupSchema = z.enum(PRESET_GROUPS);
+export type PresetGroup = z.infer<typeof PresetGroupSchema>;
+
+export const PresetItemSchema = z.object({
+    id: z.string(),
+    group: PresetGroupSchema,
+    current: PresetValueSchema,
+    proposed: PresetValueSchema,
+    changes: z.boolean().describe("Applying it would change something; false when the sandbox already has the proposed value."),
+    available: z.boolean().describe("It can be applied here. False when what it needs is missing, such as a local name model."),
+    owner: z.boolean().describe("Only the owner may apply it, since it changes the privacy shield."),
+});
+export type PresetItem = z.infer<typeof PresetItemSchema>;
+
+export const PresetPreviewSchema = z.object({ items: z.array(PresetItemSchema) });
+export type PresetPreview = z.infer<typeof PresetPreviewSchema>;
+
+export const PRESET_APPLY_MAX = 200;
+export const PresetApplySchema = z.object({
+    items: z
+        .array(z.string().min(1).max(200))
+        .min(1)
+        .max(PRESET_APPLY_MAX)
+        .describe("The ids of the items to apply, as the preview lists them. Anything not named is left as it is."),
+});
+export type PresetApply = z.infer<typeof PresetApplySchema>;
+
+export const PresetSkipReasonSchema = z.enum(["unknown", "unavailable", "unchanged", "owner"]);
+export const PresetApplyResultSchema = z.object({
+    applied: z.array(z.string()),
+    skipped: z.array(z.object({ id: z.string(), reason: PresetSkipReasonSchema })),
+});
+export type PresetApplyResult = z.infer<typeof PresetApplyResultSchema>;

package/src/schemas/daemon-health.test.ts

@@ -10,6 +10,7 @@ const answer: DaemonHealth = {
     reach: { state: "reachable", at: 3 },
     reachedBy: "tunnel",
     build: { version: "1.2.3" },
+    atRestEncryption: { active: false, stores: [] },
 };
 
 test("the daemon's answer parses whole as the contract's health", () => {
@@ -23,6 +24,7 @@ test("a reader takes any daemon's answer, a field of the wrong shape reading as
         boot: undefined,
         state: { journal: undefined },
         reachedBy: "tunnel",
+        atRestEncryption: undefined,
     });
     expect(DaemonHealthReadingSchema.parse(answer)).toMatchObject({ sandboxId: "0123456789ab", boot: { ready: true }, announce: { state: "registered" } });
 });