@intentic/sandbox-contract 1.308.2 → 1.309.0

package/src/protocol/peer-mcp-server.ts

@@ -12,11 +12,22 @@ export const MCP_PROTOCOL_VERSION = "2025-06-18";
 // whole surface. A failed tool returns isError, never a JSON-RPC error. Each tool's zod schema is both what tools/list
 // advertises and what a call is checked against.
 
+// What one call can do to the world: `read` changes nothing, so a runtime may run several at once and allow it where
+// writes are held; `write` changes something recoverable; `destructive` may lose something.
+export type ToolEffect = "read" | "write" | "destructive";
+
+// MCP tool annotations for an effect. Both hints are always spelled out: an absent destructiveHint reads as true.
+export const toolAnnotations = (effect: ToolEffect): { readonly readOnlyHint: boolean; readonly destructiveHint: boolean } => ({
+    readOnlyHint: effect === "read",
+    destructiveHint: effect === "destructive",
+});
+
 export interface McpTool<Ctx> {
     readonly name: string;
     readonly description: string;
     // JSON Schema for `tools/list`, derived from the zod schema once at module load, not per request.
     readonly inputSchema: Record<string, unknown>;
+    readonly annotations: ReturnType<typeof toolAnnotations>;
     readonly call: (args: unknown, ctx: Ctx) => Promise<Record<string, unknown>>;
 }
 
@@ -48,6 +59,7 @@ export const converterReadable = (value: unknown): unknown => {
 export const tool = <Schema extends z.ZodType, Ctx>(spec: {
     readonly name: string;
     readonly description: string;
+    readonly effect: ToolEffect;
     readonly input: Schema;
     readonly run: (args: z.output<Schema>, ctx: Ctx) => Promise<Record<string, unknown>>;
 }): McpTool<Ctx> => {
@@ -56,6 +68,7 @@ export const tool = <Schema extends z.ZodType, Ctx>(spec: {
         name: spec.name,
         description: spec.description,
         inputSchema: converterReadable(inputSchema) as Record<string, unknown>,
+        annotations: toolAnnotations(spec.effect),
         call: async (args, ctx) => {
             const parsed = spec.input.safeParse(args);
             // Readable enough for a model to fix its own call: which field, and what was expected.
@@ -92,7 +105,7 @@ const isRecord = (value: unknown): value is Record<string, unknown> => typeof va
 // mid-session takes effect on the next call.
 export const createMcpServer = <Ctx>(spec: McpServerSpec<Ctx>): ((message: unknown, ctx: Ctx) => Promise<Record<string, unknown> | undefined>) => {
     const byName = new Map(spec.tools.map((entry) => [entry.name, entry]));
-    const listing = spec.tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));
+    const listing = spec.tools.map(({ name, description, inputSchema, annotations }) => ({ name, description, inputSchema, annotations }));
     const audited = async (entry: McpAuditEntry): Promise<void> => {
         try {
             await spec.audit(entry);

package/src/protocol/tunnel-heartbeat.test.ts

@@ -0,0 +1,76 @@
+import { describe, test, expect, mock } from "bun:test";
+import { createHeartbeat, DEAD_AFTER_MS } from "./tunnel-heartbeat.js";
+
+// The clock is injected, so these read as "what happens after N seconds of silence" rather than as timer
+// plumbing — which is the only question the heartbeat answers.
+const world = (deadAfterMs = DEAD_AFTER_MS) => {
+    let clock = 0;
+    const ping = mock();
+    const onDead = mock();
+    const heartbeat = createHeartbeat({ ping, onDead, deadAfterMs, now: () => clock });
+    return { heartbeat, ping, onDead, advance: (ms: number) => (clock += ms) };
+};
+
+describe(`createHeartbeat`, () => {
+    test(`pings a peer that is still answering`, () => {
+        const { heartbeat, ping, onDead } = world();
+        heartbeat.tick();
+        heartbeat.tick();
+
+        expect(ping).toHaveBeenCalledTimes(2);
+        expect(onDead).toHaveBeenCalledTimes(0);
+    });
+
+    // Three missed intervals, not one: a single dropped pong is ordinary on a congested link, and tearing down
+    // a working tunnel for it is the more expensive mistake.
+    test(`survives a lost pong inside the dead window`, () => {
+        const { heartbeat, onDead, advance } = world();
+        advance(DEAD_AFTER_MS - 1);
+        heartbeat.tick();
+
+        expect(onDead).toHaveBeenCalledTimes(0);
+        expect(heartbeat.alive()).toBe(true);
+    });
+
+    test(`declares a peer dead once it has been silent past the window`, () => {
+        const { heartbeat, ping, onDead, advance } = world();
+        advance(DEAD_AFTER_MS + 1);
+        heartbeat.tick();
+
+        expect(onDead).toHaveBeenCalledTimes(1);
+        // Not pinged on the way out: a peer that has gone quiet is not sent one more frame it will never answer.
+        expect(ping).toHaveBeenCalledTimes(0);
+        expect(heartbeat.alive()).toBe(false);
+    });
+
+    // Any frame counts as life, not just a pong: a tunnel carrying traffic is alive by definition.
+    test(`a frame from the peer restarts the window`, () => {
+        const { heartbeat, onDead, advance } = world();
+        advance(DEAD_AFTER_MS - 1);
+        heartbeat.saw();
+        advance(DEAD_AFTER_MS - 1);
+        heartbeat.tick();
+
+        expect(onDead).toHaveBeenCalledTimes(0);
+    });
+
+    // The socket is torn down once; a tick that raced the teardown must not report it dead a second time.
+    test(`reports death once, and never after stopping`, () => {
+        const { heartbeat, onDead, advance } = world();
+        advance(DEAD_AFTER_MS + 1);
+        heartbeat.tick();
+        heartbeat.tick();
+
+        expect(onDead).toHaveBeenCalledTimes(1);
+    });
+
+    test(`a stopped heartbeat neither pings nor fires`, () => {
+        const { heartbeat, ping, onDead, advance } = world();
+        heartbeat.stop();
+        advance(DEAD_AFTER_MS + 1);
+        heartbeat.tick();
+
+        expect(ping).toHaveBeenCalledTimes(0);
+        expect(onDead).toHaveBeenCalledTimes(0);
+    });
+});

package/src/protocol/tunnel-heartbeat.ts

@@ -0,0 +1,67 @@
+// Detects a tunnel peer TCP won't report as gone (a killed container, a dropped NAT mapping, a host that slept), from
+// both ends: the edge forgets a silent sandbox and the sandbox redials a silent edge, and only each end can do its half.
+// A state machine, not a timer, so `tick` (one interval) can be driven directly by tests.
+
+// Ping every 15s, dead after three missed intervals (45s); one miss alone is ordinary on a congested link.
+export const PING_INTERVAL_MS = 15_000;
+export const DEAD_AFTER_MS = 45_000;
+
+export interface HeartbeatOptions {
+    readonly ping: () => void;
+    readonly onDead: () => void;
+    readonly now?: () => number;
+    readonly deadAfterMs?: number;
+}
+
+export interface Heartbeat {
+    // Peer said something; any frame counts, since a busy tunnel is alive even if it drops a pong.
+    readonly saw: () => void;
+    // One interval elapsed: ping the peer, or declare it dead.
+    readonly tick: () => void;
+    readonly stop: () => void;
+    readonly alive: () => boolean;
+}
+
+export const createHeartbeat = (options: HeartbeatOptions): Heartbeat => {
+    const now = options.now ?? Date.now;
+    const deadAfterMs = options.deadAfterMs ?? DEAD_AFTER_MS;
+    let lastSeen = now();
+    let stopped = false;
+
+    return {
+        saw: () => {
+            lastSeen = now();
+        },
+        tick: () => {
+            if (stopped) {
+                return;
+            }
+            // Declared dead before pinging: a peer already quiet gets no extra frame, and the deadline window stays
+            // exact.
+            if (now() - lastSeen > deadAfterMs) {
+                stopped = true;
+                options.onDead();
+                return;
+            }
+            options.ping();
+        },
+        stop: () => {
+            stopped = true;
+        },
+        alive: () => !stopped,
+    };
+};
+
+// Wired to a real clock; unrefed so a heartbeat never keeps the process alive.
+export const startHeartbeat = (options: HeartbeatOptions & { readonly intervalMs?: number }): Heartbeat => {
+    const heartbeat = createHeartbeat(options);
+    const timer = setInterval(() => heartbeat.tick(), options.intervalMs ?? PING_INTERVAL_MS);
+    timer.unref();
+    return {
+        ...heartbeat,
+        stop: () => {
+            clearInterval(timer);
+            heartbeat.stop();
+        },
+    };
+};

package/src/schemas/agent.ts

@@ -91,7 +91,8 @@ export const CommandClassSchema = z.enum([
     "secrets.access",
     // Publishes outward and irreversibly: npm/pnpm/yarn/cargo publish, gh release create, docker push.
     "package.publish",
-    // curl/wget to a non-local address, the general exfiltration channel under the per-provider actionRules.
+    // A network program (curl, nc, ssh, scp, …) or interpreter one-liner aimed at a non-loopback or run-time-built
+    // destination, the general exfiltration channel under the per-provider actionRules.
     "network.outbound",
 ]);
 export type CommandClass = z.infer<typeof CommandClassSchema>;
@@ -128,6 +129,15 @@ export type ForkedFrom = z.infer<typeof ForkedFromSchema>;
 // The turn's fields before the cross-field refinements below, so a subset (TurnProfileSchema) can be picked from them.
 const AgentTurnFieldsSchema = z.object({
     prompt: z.string().describe("What to say to the agent. May be empty if you are only attaching files."),
+    // Minted by the sender so a send whose answer was lost can be sent again without being delivered twice.
+    messageId: z
+        .string()
+        .min(1)
+        .max(128)
+        .optional()
+        .describe(
+            "Your id for this message. Sending again under an id the sandbox already took is answered with what it did with it the first time, never a second delivery. Leave it out and the sandbox names the message itself.",
+        ),
     // Seeds a fresh registry entry's title; an existing entry's title always wins over this.
     title: z
         .string()
@@ -392,16 +402,78 @@ export type ModelPin = z.infer<typeof ModelPinSchema>;
 // POST /agent's ack: the daemon-minted id of the detached run it started. The turn runs daemon-side regardless of any
 // client connection; every window renders it via /agent/attach.
 export const StartedTurnSchema = z.object({
-    run: z.string().describe("The id of the run that just started. Hand it back when you attach, so the stream resumes rather than replaying."),
+    run: z
+        .string()
+        .describe(
+            "The id of the run that just started. Hand it back when you attach: the stream always opens on the conversation's newest run, so a different id there means another turn has started since.",
+        ),
 });
 export type StartedTurn = z.infer<typeof StartedTurnSchema>;
-// Attaches to a conversation's run (live, or finished within retention); no cursor to resume from, the head carries all
-// rows. `run` names what the client was watching, so a newer run's head id tells it to catch up.
+// What the sandbox did with one message, keyed by the id its sender gave it: the same id sent again gets this answer
+// back as a duplicate, never a second delivery.
+export const MessageReceiptSchema = z.object({
+    delivered: z
+        .enum(["started", "steered", "queued"])
+        .describe(
+            "What became of the message: it started a turn, it was said into the turn already running, or it waits in the conversation's queue for the next one.",
+        ),
+    run: z
+        .string()
+        .optional()
+        .describe(
+            "The run the message is in: the turn it started, or the one it was said into. Hand it back when you attach. Absent while the message waits in the queue.",
+        ),
+    duplicate: z
+        .literal(true)
+        .optional()
+        .describe("The sandbox had already taken a message under this id: this is what became of it, and nothing new happened."),
+});
+export type MessageReceipt = z.infer<typeof MessageReceiptSchema>;
+// Who a message to a conversation is from: a person (a composer, an API caller), the sandbox itself (a watch that fired,
+// a job that ended, a land that broke something), or another agent (a child reporting back).
+export const MessageVoiceSchema = z.enum(["person", "sandbox", "agent"]);
+export type MessageVoice = z.infer<typeof MessageVoiceSchema>;
+// One message waiting for the conversation's next turn, as every window shows it.
+export const QueuedMessageSchema = z.object({
+    id: z.string().describe("The message's id: what its sender named it, or what the sandbox did."),
+    text: z.string().describe("The words, as they will go out."),
+    attachments: z.array(z.string()).optional().describe("Files that go with it, as workspace paths."),
+    voice: MessageVoiceSchema.describe("Who it is from: a person, the sandbox itself, or another agent."),
+    queuedAt: z.number().describe("When it joined the queue, in milliseconds."),
+    revision: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("The queue's revision when this message was last written. An edit or a removal names it, and is refused if the message has changed since."),
+});
+export type QueuedMessage = z.infer<typeof QueuedMessageSchema>;
+// Why a queue holds its messages rather than letting them go when the conversation is free.
+export const QueuePauseSchema = z.enum(["stopped", "refused"]);
+export type QueuePause = z.infer<typeof QueuePauseSchema>;
+// What waits for a conversation's next turn: messages that arrived while a turn that could not take them ran, and
+// held ones. Conversation state, the same for every window and kept across a restart.
+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, or the turn these messages started was refused before it ran. Resuming, or sending another message, lets them go.",
+    ),
+});
+export type ConversationQueue = z.infer<typeof ConversationQueueSchema>;
+// What resuming a queue did: started a turn with what waited, when nothing else ran.
+export const QueueResumedSchema = z.object({
+    run: z.string().optional().describe("The turn the waiting messages started. Absent when a turn was already running, and they go after it."),
+});
+export type QueueResumed = z.infer<typeof QueueResumedSchema>;
+// Attaches to a conversation's newest run (live, or finished within retention); no cursor to resume from, the head
+// carries all rows. `run` names what the client was watching, so a newer run's head id tells it to catch up.
 export const AttachTurnSchema = z.object({
     conversationId: ConversationIdSchema.describe("Which conversation to watch."),
     run: z
         .string()
         .optional()
-        .describe("The run you were watching. If a newer turn has started since, the head names that one instead, and its rows are that turn's."),
+        .describe(
+            "The run you were watching. The stream opens on the conversation's newest run whatever you name: if a newer turn has started since, the head names that one instead, and its rows are that turn's.",
+        ),
 });
 export type AttachTurn = z.infer<typeof AttachTurnSchema>;

package/src/schemas/agents.ts

@@ -1,6 +1,6 @@
 // agents: the conversation fleet
 import { z } from "zod";
-import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ForkedFromSchema } from "./agent.js";
+import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ConversationQueueSchema, ForkedFromSchema } from "./agent.js";
 import { LoopStateSchema } from "./loops.js";
 import { LimitPolicySchema, RetryPolicySchema, TurnBreakPolicySchema, TurnBreakSchema } from "./turn-break.js";
 import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
@@ -351,6 +351,16 @@ export const AgentSummarySchema = z.object({
         "What this conversation's merged work is called, once the drafting above has finished. It arrives on the same push that ends the draft, so the promise and the answer travel together.",
     ),
     startedAt: z.number().optional().describe("When the running turn started, in milliseconds. Absent when none is running."),
+    run: z
+        .string()
+        .optional()
+        .describe(
+            "The run under way right now: what a stop names, so it cannot cancel a turn that started after it was pressed. Absent when none is running, and for a turn with no run to attach to.",
+        ),
+    // On the card because every window and the board read it here: the queue is the conversation's, not any window's.
+    queue: ConversationQueueSchema.optional().describe(
+        "Messages waiting for its next turn, and whether they are held. Absent for a conversation nothing has ever waited for.",
+    ),
     updatedAt: z.number().describe("When it last did something, in milliseconds. Reading it does not count."),
     // Daemon-side, not browser-side: read state is a fact about the work, so clearing site data or switching devices
     // can't resurrect a badge.

package/src/schemas/approvals.ts

@@ -124,3 +124,70 @@ export const ApprovalsListSchema = z.object({
 export type ApprovalsList = z.infer<typeof ApprovalsListSchema>;
 // entryId, not a bare string: the id becomes a filename under .intentic/config/approvals/.
 export const ApprovalIdParamSchema = z.object({ id: entryId.describe("Which approval.") });
+
+/* WORKSPACE HOOKS: what Claude Code would run on a turn from its settings files and skill or subagent definitions, held
+ * off until the owner approves that exact set by its digest. Never a workspace file: whoever can write the hooks must not
+ * also be able to write their yes, so the record lives with the daemon and only the owner's routes below move it. */
+
+const hookDigest = z.string().regex(/^[0-9a-f]{64}$/);
+
+export const SettingsHookSchema = z.object({
+    source: z
+        .enum(["user", "project"])
+        .describe("Whose configuration declares it: the sandbox's own (~/.claude) or the workspace's (.claude/ in the project)."),
+    declaredIn: z
+        .string()
+        .optional()
+        .describe(
+            "The skill, subagent or command whose frontmatter declares it, spelled like a script path. Absent when it comes from the settings.json of its source.",
+        ),
+    event: z.string().describe("When it runs, in Claude Code's own words: before a tool, after one, when a prompt is sent, when a session starts."),
+    matcher: z.string().optional().describe("Which tools it is limited to, when it is limited at all."),
+    type: z.string().describe("What kind of hook it is: a shell command, an address it calls, a prompt it asks a model."),
+    run: z.string().describe("Exactly what it runs: the command line, the address, the prompt."),
+});
+export type SettingsHook = z.infer<typeof SettingsHookSchema>;
+
+export const HookScriptSchema = z.object({
+    path: z
+        .string()
+        .describe(
+            "A file one of the hooks runs, spelled the way the hook names it: inside the workspace as $CLAUDE_PROJECT_DIR/…, under the home directory as ~/…, otherwise absolute.",
+        ),
+    sha256: z
+        .string()
+        .describe(
+            "Its contents when the hooks were found. The approval covers these bytes, so editing the file asks again, the same as editing the command would.",
+        ),
+});
+export type HookScript = z.infer<typeof HookScriptSchema>;
+
+export const HookRequestSchema = z.object({
+    digest: hookDigest.describe(
+        "The set's fingerprint: every hook as declared plus the bytes of every file they run. Approving it approves exactly this, and nothing that differs from it by a character.",
+    ),
+    seenAt: z.number().describe("When a turn first found this set, in milliseconds."),
+    conversationId: z.string().optional().describe("The conversation whose turn found it, when one did."),
+    hooks: z
+        .array(SettingsHookSchema)
+        .describe("Every hook in the set. Until it is approved, turns run with all of them off, and so with every other hook the agent would load."),
+    scripts: z.array(HookScriptSchema).describe("The files those hooks run by name, which the approval pins byte for byte."),
+    dismissed: z
+        .boolean()
+        .optional()
+        .describe("Kept off on purpose: no longer counted as waiting, and still approvable. Present only when it was dismissed."),
+});
+export type HookRequest = z.infer<typeof HookRequestSchema>;
+
+export const HookRequestsSchema = z.object({
+    requests: z.array(HookRequestSchema).describe("Hook sets waiting for a yes, newest first, then the dismissed ones."),
+    ledgerUnreadable: z
+        .boolean()
+        .optional()
+        .describe(
+            "The record of what was approved could not be read, so no settings-file hook runs anywhere until a set is approved again. Present only when that is the case.",
+        ),
+});
+export type HookRequests = z.infer<typeof HookRequestsSchema>;
+
+export const HookDigestParamSchema = z.object({ digest: hookDigest.describe("Which hook set, by its fingerprint.") });

package/src/schemas/context-trim.test.ts

@@ -5,10 +5,10 @@ import { contextTrimLine } from "./context-trim.js";
 // thin, what it lost, and whether the reader's own instructions were among the losses.
 
 test("the window comes first, then what went, then what stayed", () => {
-    const line = contextTrimLine({ window: 16_384, omitted: ["Map of this project", "How this sandbox asks agents to work"], base: true });
+    const line = contextTrimLine({ window: 16_384, omitted: ["Map of this project", "Working in this sandbox"], base: true });
 
     expect(line).toContain("16k window");
-    expect(line).toContain("Map of this project, How this sandbox asks agents to work");
+    expect(line).toContain("Map of this project, Working in this sandbox");
     // Without this clause the line reads as "your AGENTS.md may not have arrived", which is the one thing it is not.
     expect(line).toContain("Your workspace rules");
 });

package/src/schemas/devices.ts

@@ -88,6 +88,8 @@ export const DeviceSandboxFlowSchema = z.object({
     pair: z.string().optional().meta({ secret: true }),
     // Required by `reconnect` and `create`; single-sandbox and short-lived, so a leak only buys one recreate.
     setupCode: z.string().optional().meta({ secret: true }),
+    // `reconnect`/`create` only, daemon-filled: the platform that minted `setupCode`, the only one that redeems it.
+    platformUrl: z.string().optional(),
     // `runner-up` only, daemon-filled: `definition` carries no capabilities or secrets; `overlay`/`overlayHash` are
     // re-verified by hash before build.
     definition: z.string().optional(),

package/src/schemas/extension-updates.ts

@@ -206,6 +206,31 @@ export const InvalidWorkspaceExtensionSchema = z.object({
     error: z.string().describe("Why it could not be read."),
 });
 export type InvalidWorkspaceExtension = z.infer<typeof InvalidWorkspaceExtensionSchema>;
+// A workspace extension nobody has approved in its current shape. It stands in for the install moment a folder
+// otherwise never has: until the owner says yes, none of its code runs and none of its contributions are wired.
+export const PendingWorkspaceExtensionSchema = z.object({
+    id: extensionId.describe("The extension's id."),
+    dir: z.string().describe("Which folder under .intentic/config/workspace-extensions/."),
+    manifest: ExtensionManifestSchema.describe("What it declares about itself."),
+    powers: PowersDiffSchema.describe(
+        "What saying yes allows, as plain sentences. Against what was approved before when something was: `added` is what it asks for now that it did not then. Never approved before, everything it declares is `added`.",
+    ),
+    approvedBefore: z
+        .boolean()
+        .describe("An earlier shape of it was approved, and the powers it declares have changed since, which is what put it back here."),
+    digest: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .describe("The fingerprint of the powers shown, sent back with the approval so a change made while you were reading is caught rather than approved."),
+});
+export type PendingWorkspaceExtension = z.infer<typeof PendingWorkspaceExtensionSchema>;
+export const ExtensionApproveInputSchema = z.object({
+    id: extensionId.describe("Which extension."),
+    digest: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .describe("The fingerprint of the powers you read, from the pending list. A mismatch means they changed since, and nothing is approved."),
+});
 export const ExtensionsListSchema = z.object({
     extensions: z.array(ExtensionSummarySchema).describe("What is installed."),
     invalid: z
@@ -213,6 +238,11 @@ export const ExtensionsListSchema = z.object({
         .describe(
             "Extensions written here that could not be read at all. Listed rather than dropped, because there is no install moment at which to reject a broken one, so this is its only way of saying anything.",
         ),
+    pending: z
+        .array(PendingWorkspaceExtensionSchema)
+        .describe(
+            "Extensions written in this workspace that wait for the owner's approval before anything of theirs runs: never approved, or approved when they declared less than they do now.",
+        ),
     updatesCheckedAt: z
         .string()
         .optional()

package/src/schemas/history.ts

@@ -25,7 +25,8 @@ export interface SnapshotTurn {
 }
 export const SnapshotsListSchema = z.object({ snapshots: z.array(SnapshotSchema).describe("Every point you can go back to, newest first.") });
 // Restores the workspace to that turn's checkpoint, drops every message after it, and forgets the provider session so
-// the next turn opens fresh.
+// the next turn opens fresh. `messageId` is what makes `index` safe to act on: a position is only as current as the
+// transcript it was read from.
 export const RewindTurnSchema = z.object({
     conversationId: z.string().min(1).describe("Which conversation to rewind."),
     index: z
@@ -35,6 +36,12 @@ export const RewindTurnSchema = z.object({
         .describe(
             "Which message to go back to, counting from the start. It is also how many messages survive: rewinding to the first keeps none of them and puts the files back to before it ran.",
         ),
+    messageId: z
+        .string()
+        .min(1)
+        .describe(
+            "The id of the message at that position, as its row names it. If that position now holds a different message, nothing is rewound: the transcript has moved since you read it.",
+        ),
 });
 export const RewindResultSchema = z.object({
     snapshot: z

package/src/schemas/metrics.ts

@@ -105,3 +105,151 @@ export const SandboxMetricsSchema = z.object({
         .describe("Every process in the sandbox but the daemon, by what kind of work it is. A kind with nothing running is absent."),
 });
 export type SandboxMetrics = z.infer<typeof SandboxMetricsSchema>;
+
+// What is filling the sandbox's disk, by what it is for (GET /system/storage). Sizes are apparent bytes, and a file
+// with several hard links counts once, toward the first place the scan met it.
+
+// Every category a byte on the sandbox's volumes can belong to; STORAGE_CLEANABILITY below says which may be cleaned.
+export const STORAGE_CATEGORIES = [
+    // The workspace's own files: repositories, their dependencies, anything the owner or an agent put there.
+    "workspace",
+    // Transcripts, runtime session stores, attachments and loop memory of every conversation, archived ones included.
+    "conversations",
+    // Each open conversation's own checkout of the repositories, and the dependencies its turns installed over them.
+    "checkouts",
+    // The minute-by-minute and per-turn snapshots the History timeline restores from.
+    "restorePoints",
+    // The repositories' own git data: every commit and branch, pushed or not.
+    "repositories",
+    // Installed versions of the agent runtimes: the one turns use and the one kept for Revert.
+    "engines",
+    // Search indexes and caches the sandbox keeps up to date by itself while it runs.
+    "indexes",
+    // Installed extensions and their scratch.
+    "extensions",
+    // The sandbox's own Docker: images, containers, volumes.
+    "docker",
+    // Settings, credentials, sign-ins and the ledgers of what was spent and done.
+    "state",
+    // Anything no part of the sandbox claims.
+    "other",
+    // Git data and checkouts of repositories deleted from the workspace.
+    "trash",
+    // Copies of the sandbox packed for download.
+    "exports",
+    // Files agents produced: generated images, reports, harness output.
+    "artifacts",
+    // Screenshots and page snapshots the agent's browser took.
+    "browserCaptures",
+    // The agent browser's profiles, with the sites it is signed in to.
+    "browserProfiles",
+    // Weights downloaded for local models.
+    "modelWeights",
+    // The sandbox's own logs and terminal captures.
+    "logs",
+    // Scratch space agents and checks leave behind.
+    "scratch",
+    // Package managers' content stores, which the next install refills.
+    "packageStores",
+    // Build tools' output caches.
+    "buildCaches",
+] as const;
+export const StorageCategoryIdSchema = z.enum(STORAGE_CATEGORIES);
+export type StorageCategoryId = z.infer<typeof StorageCategoryIdSchema>;
+
+// none: never removed from here; safe: comes back by itself, removed without asking; confirm: removed only once the
+// owner has read what it costs.
+export const StorageCleanabilitySchema = z.enum(["none", "safe", "confirm"]);
+export type StorageCleanability = z.infer<typeof StorageCleanabilitySchema>;
+
+// Which categories may be cleaned, and which ask first: the daemon's cleaner refuses by it, the editor words its
+// confirm by it. State, credentials and live work are `none`; what regenerates is `safe`; the owner's own data asks.
+export const STORAGE_CLEANABILITY = {
+    workspace: "none",
+    conversations: "none",
+    // A live conversation's working copy; archiving the conversation is what frees it.
+    checkouts: "none",
+    // No compaction is safe to offer: `git gc --auto` already runs after every snapshot, and every object is reachable.
+    restorePoints: "none",
+    repositories: "none",
+    // The Engines card keeps two versions and owns which is which; removing one here would strand its Revert.
+    engines: "none",
+    // Held open by what maintains them: removing a file frees nothing until they close it.
+    indexes: "none",
+    extensions: "none",
+    docker: "none",
+    state: "none",
+    other: "none",
+    // Nothing reads it again, but it may hold commits never pushed anywhere.
+    trash: "confirm",
+    exports: "confirm",
+    artifacts: "confirm",
+    browserCaptures: "confirm",
+    browserProfiles: "confirm",
+    modelWeights: "confirm",
+    logs: "safe",
+    scratch: "safe",
+    packageStores: "safe",
+    buildCaches: "safe",
+} as const satisfies Record<StorageCategoryId, StorageCleanability>;
+
+export const StorageItemSchema = z.object({
+    path: z.string().describe("Where it is, as an absolute path inside the sandbox."),
+    bytes: z.number().describe("Its size in bytes."),
+});
+export type StorageItem = z.infer<typeof StorageItemSchema>;
+
+export const StorageCategoryUsageSchema = z.object({
+    id: StorageCategoryIdSchema,
+    cleanability: StorageCleanabilitySchema.describe("Whether this category can be cleaned from here, and whether cleaning it asks first."),
+    bytes: z.number().describe("Its size in bytes."),
+    files: z.number().describe("How many files it holds."),
+    cleanableBytes: z
+        .number()
+        .optional()
+        .describe(
+            "What cleaning it would free right now: only what is old enough and not in use. Absent where nothing here may be cleaned, and for a package store, whose own tool decides what no project needs.",
+        ),
+    items: z.array(StorageItemSchema).describe("Its biggest parts, largest first, at most eight."),
+});
+export type StorageCategoryUsage = z.infer<typeof StorageCategoryUsageSchema>;
+
+export const StorageScanSchema = z.object({
+    startedAt: z.number().describe("When the scan began, in milliseconds."),
+    finishedAt: z.number().describe("When it ended, in milliseconds: the moment these sizes describe."),
+    outcome: z
+        .enum(["complete", "partial"])
+        .describe("`partial` when the scan hit its time limit first, so every size is at least what it says rather than exactly it."),
+    disk: z
+        .object({
+            usedBytes: z.number().describe("Space used on the volume the workspace lives on."),
+            totalBytes: z.number().describe("That volume's size."),
+        })
+        .optional()
+        .describe("The volume as a whole. Absent when the volume would not say."),
+    categories: z.array(StorageCategoryUsageSchema).describe("Every category that holds anything, largest first."),
+    unreadable: z.number().describe("Files and folders the scan could not read, and so did not count."),
+});
+export type StorageScan = z.infer<typeof StorageScanSchema>;
+
+export const StorageReportSchema = z.object({
+    scan: StorageScanSchema.optional().describe("The last scan that finished. Absent until one has, and again after the daemon restarts."),
+    scanning: z.boolean().describe("Whether a scan is running now."),
+});
+export type StorageReport = z.infer<typeof StorageReportSchema>;
+
+export const StorageCleanInputSchema = z.object({
+    category: StorageCategoryIdSchema.describe("The category to clean; one whose cleanability is `none` is refused."),
+});
+export type StorageCleanInput = z.infer<typeof StorageCleanInputSchema>;
+
+export const StorageCleanResultSchema = z.object({
+    category: StorageCategoryIdSchema,
+    freedBytes: z.number().describe("Space the removals gave back, in bytes. A file that is still linked elsewhere frees nothing and is not counted."),
+    removed: z.number().describe("How many items were removed."),
+    kept: z
+        .number()
+        .describe("How many were left in place: changed too recently, in use by a running program, or no longer this category's."),
+    failed: z.number().describe("How many removals the filesystem refused."),
+});
+export type StorageCleanResult = z.infer<typeof StorageCleanResultSchema>;