@intentic/sandbox-contract 1.311.0 → 1.313.0

package/src/schemas/hosts.ts

@@ -9,9 +9,22 @@ import { z } from "zod";
 export const WslEnvironmentSchema = z.object({ distro: z.string() });
 export type WslEnvironment = z.infer<typeof WslEnvironmentSchema>;
 
+// WHICH PHYSICAL COMPUTER A DOOR IS ON. The machine agent mints this once, at install, and keeps it in its own state
+// (`~/.intentic/machine/machine-id`); a WSL distro's agent is handed its Windows side's, since a distro is an
+// environment of the PC, not a second computer. It is what an enrollment, a sync enrollment and a device row are
+// joined on — never a hostname, which WSL shares between a PC and its distros and a user can rename.
+export const MachineIdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/);
+// An id the daemon stands in for a machine that has not said its own yet (an enrollment made before agents reported
+// one): named after the card, so every environment of that card shares it until each reports the real id. Never
+// sent by an agent, and never the join key of two different cards.
+export const derivedMachineId = (card: string): string => `card:${card}`;
+export const isDerivedMachineId = (machineId: string): boolean => machineId.startsWith("card:");
+
 // What a machine reports once at connect (`host.describe`), cached until it reconnects: the skill pack says how to
 // drive Windows, this says which Windows it is.
 export const DeviceFactsSchema = z.object({
+    // The computer this environment is on (MachineIdSchema). Absent from an agent older than the field.
+    machineId: MachineIdSchema.optional(),
     // The OS's own name for itself, e.g. "Windows 11 Pro 24H2".
     os: z.string(),
     arch: z.string(),
@@ -24,8 +37,7 @@ export const DeviceFactsSchema = z.object({
     // Docker engine's size (WSL guest on Windows, Desktop VM on macOS, host on Linux); the ceiling a sandbox's share is
     // bounded by.
     engine: z.object({ memoryBytes: z.number(), cpus: z.number() }).optional(),
-    // OS hostname: the key that joins the doors of one physical machine. Reported by every agent that also reports
-    // `wsl`, so a hostname with no `wsl` beside it is a native install; absent from an agent older than both.
+    // OS hostname, for the owner to read. Not a join key: `machineId` is.
     hostname: z.string().optional(),
     // Present only inside a WSL distro.
     wsl: WslEnvironmentSchema.optional(),
@@ -35,9 +47,33 @@ export const DeviceFactsSchema = z.object({
     // the rest are other sandboxes' addresses, and a sandbox has no business learning its siblings'. Absent from an
     // agent older than this field, which is why "none unreachable" is not the same value as "did not say".
     links: z.object({ total: z.number(), unreachable: z.number(), unreachableSince: z.number().optional() }).optional(),
+    // Which of the optional ops this agent AND the `ic` it drives implement (DeviceFeatureSchema), for a page to offer
+    // only what works and for the daemon to refuse an op before sending it. Strings on the wire, so a newer agent's
+    // feature never fails an older daemon's read; `deviceFeatures` keeps the ones this build knows. Nothing is
+    // detected by a field's presence any more: the device RPC inputs are strict, and an agent rejects a field it does
+    // not know rather than dropping it.
+    features: z.array(z.string()).optional(),
 });
 export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 
+// The optional device ops, by what enables them:
+// - `reshape-later`: the old `reshape` op with `later`, saving the change for the next restart. An agent from before it
+//   strips `later` and reshapes NOW, which is why a later-reshape is never sent to one.
+// - `set-shape`: the `set-shape`/`forget-shape` ops, and `start`/`restart` applying a saved shape, all through an `ic`
+//   whose `ic sandbox shape` takes the contract's own shape (`--set`); advertised only when the agent's `ic` does.
+//   Both features ride that verb, so an agent advertises both or neither.
+export const DeviceFeatureSchema = z.enum(["reshape-later", "set-shape"]);
+export type DeviceFeature = z.infer<typeof DeviceFeatureSchema>;
+export const DEVICE_FEATURE_RESHAPE_LATER: DeviceFeature = "reshape-later";
+export const DEVICE_FEATURE_SET_SHAPE: DeviceFeature = "set-shape";
+// The features an agent advertised that this build knows; an unknown one is a newer agent's and means nothing here.
+export const deviceFeatures = (facts: Pick<DeviceFacts, "features"> | undefined): DeviceFeature[] =>
+    (facts?.features ?? []).flatMap((feature) => {
+        const known = DeviceFeatureSchema.safeParse(feature);
+        return known.success ? [known.data] : [];
+    });
+export const deviceSupports = (facts: Pick<DeviceFacts, "features"> | undefined, feature: DeviceFeature): boolean => deviceFeatures(facts).includes(feature);
+
 // Docker Desktop's own distros: `wsl -l -q` lists them like any other, and none ever runs an agent or holds a checkout.
 export const WSL_SYSTEM_DISTROS: ReadonlySet<string> = new Set(["docker-desktop", "docker-desktop-data"]);
 
@@ -56,11 +92,7 @@ export const windowsPathOf = (distro: string, linuxPath: string): string => `\\\
 // ONE CARD IS ONE COMPUTER, AND EACH OS INSTALL ON IT IS A CONNECTION OF THAT CARD. A PC's Windows side and every WSL
 // distro on it hold their own agent — mutagen has to watch the filesystem it syncs, and a distro's login shell is its
 // own — but the owner connected a computer, not a shell, so the grant, the row and the tools are the machine's.
-// The native environment's connection key IS the card id, by definition rather than as a fallback: a machine with one
-// OS install has one connection named after itself, and a sibling hangs off it as `<card>::wsl:<distro>`. `::` cannot
-// collide with the single colon in an environment key.
 export const HOST_NATIVE_ENVIRONMENT = "native";
-const ENVIRONMENT_SEPARATOR = "::";
 
 // Which environment a machine is describing when it connects: the distro by the name WSL registered (what `wsl -l -q`
 // prints and `in: "wsl:<name>"` takes), or the metal. Facts arrive at connect and no scope withholds them, so this is
@@ -68,14 +100,27 @@ const ENVIRONMENT_SEPARATOR = "::";
 export const environmentKeyOf = (facts: Pick<DeviceFacts, "wsl">): string =>
     facts.wsl === undefined ? HOST_NATIVE_ENVIRONMENT : `wsl:${facts.wsl.distro}`;
 
-export const hostConnectionKey = (entry: string, environment: string): string =>
-    environment === HOST_NATIVE_ENVIRONMENT ? entry : `${entry}${ENVIRONMENT_SEPARATOR}${environment}`;
+// A CONNECTION'S KEY, spelled and read in exactly one place. The key is what the hub, a device RPC and a page's row
+// address a connection by: the native environment's key IS the card id, and a sibling hangs off it as
+// `<card>::wsl:<distro>` (`::` cannot collide with the single colon in an environment key). What a connection IS —
+// its card, its environment, its computer — is the enrollment's own record (a host enrollment says all three, and a
+// device row carries `card`), so the parser is only for a key with nothing beside it: the key the owner asks to pair,
+// an enrollment written before records said, a row from a daemon older than `card`. A rename relabels the record and
+// the key follows from the label; the live connection is held under the new key without being cut (PeerHub.rekey).
+export interface HostConnection {
+    readonly card: string;
+    readonly environment: string;
+}
+const ENVIRONMENT_SEPARATOR = "::";
 
-export const hostEntryOf = (connection: string): string => connection.split(ENVIRONMENT_SEPARATOR)[0] ?? connection;
+export const hostConnectionKey = (card: string, environment: string): string =>
+    environment === HOST_NATIVE_ENVIRONMENT ? card : `${card}${ENVIRONMENT_SEPARATOR}${environment}`;
 
-export const hostEnvironmentOf = (connection: string): string => {
-    const at = connection.indexOf(ENVIRONMENT_SEPARATOR);
-    return at === -1 ? HOST_NATIVE_ENVIRONMENT : connection.slice(at + ENVIRONMENT_SEPARATOR.length);
+export const parseHostConnection = (key: string): HostConnection => {
+    const at = key.indexOf(ENVIRONMENT_SEPARATOR);
+    return at === -1
+        ? { card: key, environment: HOST_NATIVE_ENVIRONMENT }
+        : { card: key.slice(0, at), environment: key.slice(at + ENVIRONMENT_SEPARATOR.length) };
 };
 
 // One OS install of a machine, as its card knows it. `key` is the environment (`native`, `wsl:archlinux`); everything
@@ -83,6 +128,9 @@ export const hostEnvironmentOf = (connection: string): string => {
 // version — one side can be asleep, or running a build behind.
 export const HostEnvironmentSchema = z.object({
     key: z.string().min(1),
+    // The computer this environment's enrollment is on, once its agent has said (never a derived id): what joins it to
+    // a sync enrollment and to the other environments of that computer, whether or not it is connected right now.
+    machineId: MachineIdSchema.optional(),
     online: z.boolean(),
     version: z.string().optional(),
     lastSeen: z.number().optional(),
@@ -91,8 +139,11 @@ export const HostEnvironmentSchema = z.object({
 export type HostEnvironment = z.infer<typeof HostEnvironmentSchema>;
 
 export const HostSummarySchema = z.object({
-    // The capability id, the machine's name, and the prefix of its tools (mcp__<id>__run_command).
+    // The capability id, the machine's name, and the prefix of its tools (mcp__<id>__run_command). On a per-connection
+    // row (`hostConnections`) it is that connection's key instead, and `card` names the machine.
     id: z.string(),
+    // The card a per-connection row is a connection of: a label on the row, read rather than parsed out of `id`.
+    card: z.string().optional(),
     platform: z.string().min(1),
     // Every environment of this machine, native first: what the page draws a row per, and what a command picks from.
     // Never empty — a card that has never connected still has its native environment, offline.

package/src/schemas/ic-shape-args.test.ts

@@ -0,0 +1,64 @@
+import { DeviceSandboxFlowSchema, icForgetShapeArgs, icPowerArgs, icShapeArgs, SandboxShapeSchema } from "./devices.js";
+
+// The one spelling of ic's shape and power verbs outside ic: the machine agent runs these and the Devices view prints them for a
+// person to type, so a drift here is a command that fails on the machine, or one that does something else there.
+
+test("a whole shape is one `--set` per field, in the contract's own names and values", () => {
+    expect(icShapeArgs("work", { memoryGib: 20, cpus: null, privileged: false, gpu: true }, "nextRestart")).toEqual([
+        "sandbox",
+        "shape",
+        "work",
+        "--set",
+        "memoryGib=20",
+        "--set",
+        "cpus=null",
+        "--set",
+        "privileged=false",
+        "--set",
+        "gpu=true",
+        "--when",
+        "nextRestart",
+    ]);
+    expect(icShapeArgs("work", { memoryGib: null, cpus: 4, privileged: true, gpu: false }, "now").slice(3)).toEqual([
+        "--set",
+        "memoryGib=null",
+        "--set",
+        "cpus=4",
+        "--set",
+        "privileged=true",
+        "--set",
+        "gpu=false",
+        "--when",
+        "now",
+    ]);
+});
+
+test("a field left out is left to ic, which keeps what it has for it", () => {
+    expect(icShapeArgs("work", { memoryGib: 12, gpu: undefined }, "now")).toEqual(["sandbox", "shape", "work", "--set", "memoryGib=12", "--when", "now"]);
+});
+
+test("forgetting and power name only the sandbox", () => {
+    expect(icForgetShapeArgs("work")).toEqual(["sandbox", "shape", "work", "--forget"]);
+    expect(icPowerArgs("restart", "work")).toEqual(["sandbox", "restart", "work"]);
+});
+
+// A shape is whole: a delta would put the merge back into every reader, which is what this schema exists to end.
+test("a shape missing a field is not a shape", () => {
+    expect(SandboxShapeSchema.safeParse({ memoryGib: 20, cpus: null, privileged: false }).success).toBe(false);
+    expect(SandboxShapeSchema.safeParse({ memoryGib: 0, cpus: null, privileged: false, gpu: false }).success).toBe(false);
+    expect(SandboxShapeSchema.safeParse({ memoryGib: null, cpus: null, privileged: false, gpu: false }).success).toBe(true);
+});
+
+// Every device input is strict, the shape nested in one included: an agent that dropped a field it did not know would
+// carry out a different order than the one sent.
+test("a device order refuses a shape or delta field it does not know", () => {
+    const whole = { memoryGib: 20, cpus: null, privileged: false, gpu: false };
+    // As the order arrives off the wire, where the nested object is only ever JSON.
+    const accepted = (fields: object): boolean =>
+        DeviceSandboxFlowSchema.safeParse(JSON.parse(`{"op":"set-shape","slug":"work","when":"now","shape":${JSON.stringify(fields)}}`)).success;
+    expect(accepted(whole)).toBe(true);
+    expect(accepted({ ...whole, swapGib: 4 })).toBe(false);
+    expect(DeviceSandboxFlowSchema.safeParse({ op: "reshape", slug: "work", resources: { memoryGib: 20, swapGib: 4 } }).success).toBe(false);
+    // A report is read leniently: a newer ic's extra field must not fail an older reader.
+    expect(SandboxShapeSchema.safeParse({ ...whole, swapGib: 4 }).success).toBe(true);
+});

package/src/schemas/keep-warm.test.ts

@@ -5,7 +5,6 @@ import {
     keepWarmDueAt,
     keepWarmHorizon,
     keepWarmLeadMs,
-    keepWarmMaxRefreshes,
     keepWarmRefreshes,
     keptWarmLine,
 } from "./keep-warm.js";
@@ -13,20 +12,13 @@ import {
 const MINUTE = 60_000;
 const HOUR = 60 * MINUTE;
 
-// The arithmetic both the daemon and every press read, so the price shown before a press is the price the daemon keeps.
+// The clock both the daemon and every press read, so the refreshes shown before a press are the ones the daemon sends.
 describe("keep-warm economics", () => {
     test("refreshes a fifth of an entry's life early, never under a minute or over ten", () => {
         expect(keepWarmLeadMs(HOUR)).toBe(10 * MINUTE);
         expect(keepWarmLeadMs(5 * MINUTE)).toBe(MINUTE);
     });
 
-    test("spends at most half of what a cold resume would rewrite", () => {
-        // A 1h rewrite costs 2x base input and a read 0.1x: nineteen reads break even, so nine.
-        expect(keepWarmMaxRefreshes(HOUR)).toBe(9);
-        // A 5m rewrite costs 1.25x: eleven reads break even, so five.
-        expect(keepWarmMaxRefreshes(5 * MINUTE)).toBe(5);
-    });
-
     test("counts the refreshes that keep an entry alive through the deadline", () => {
         const cache = { at: 0, ttlMs: HOUR };
         expect(keepWarmRefreshes(cache, HOUR)).toBe(0);
@@ -34,11 +26,12 @@ describe("keep-warm economics", () => {
         expect(keepWarmDueAt(cache)).toBe(50 * MINUTE);
     });
 
-    test("reaches no further than the horizon, or the date change when that comes first", () => {
+    test("reaches no further than the refreshes left carry it, or the date change when that comes first", () => {
         const cache = { at: 0, ttlMs: HOUR };
-        expect(keepWarmHorizon(cache)).toBe(HOUR + 9 * 50 * MINUTE);
-        expect(keepWarmCap(cache, 3 * HOUR)).toBe(3 * HOUR);
-        expect(keepWarmCap({ at: 0, ttlMs: 5 * MINUTE }, undefined)).toBe(5 * MINUTE + 5 * 4 * MINUTE);
+        expect(keepWarmHorizon(cache, 9)).toBe(HOUR + 9 * 50 * MINUTE);
+        expect(keepWarmHorizon(cache, -2)).toBe(HOUR);
+        expect(keepWarmCap(cache, 3 * HOUR, 9)).toBe(3 * HOUR);
+        expect(keepWarmCap({ at: 0, ttlMs: 5 * MINUTE }, undefined, 5)).toBe(5 * MINUTE + 5 * 4 * MINUTE);
     });
 
     test("names the parts two fingerprints disagree on", () => {

package/src/schemas/keep-warm.ts

@@ -1,13 +1,8 @@
-// keep-warm: holding an idle conversation's prompt cache open by re-reading it shortly before it expires.
+// keep-warm: holding an idle conversation's prompt cache open by re-reading it shortly before it expires. Only the
+// clock lives here; how many refreshes a hold may spend is priced by the provider that serves it (runtimes/claude).
 
 import { z } from "zod";
 
-const HOUR_MS = 3_600_000;
-
-// Anthropic's price multipliers on base input: a read costs 0.1x, a write 2x under the 1h TTL and 1.25x under 5m.
-const READ_COST = 0.1;
-const writeCost = (ttlMs: number): number => (ttlMs >= HOUR_MS ? 2 : 1.25);
-
 // A cache clock as the daemon publishes it: the last request that touched the entry, and the entry's lifetime.
 export interface CacheClock {
     readonly at: number;
@@ -17,28 +12,26 @@ export interface CacheClock {
 /** How long before expiry a refresh starts: a fifth of the entry's life, never under a minute or over ten. */
 export const keepWarmLeadMs = (ttlMs: number): number => Math.min(10 * 60_000, Math.max(60_000, Math.round(ttlMs / 5)));
 
-/** Refreshes one hold may spend: half of what a cold resume rewrites, the other half left for each refresh's own tail. */
-export const keepWarmMaxRefreshes = (ttlMs: number): number => Math.floor((writeCost(ttlMs) - READ_COST) / READ_COST / 2);
-
 /** How many refreshes keep an entry alive through `until`. */
 export const keepWarmRefreshes = (cache: CacheClock, until: number): number => {
     const beyond = until - (cache.at + cache.ttlMs);
     return beyond <= 0 ? 0 : Math.ceil(beyond / (cache.ttlMs - keepWarmLeadMs(cache.ttlMs)));
 };
 
-/** The latest instant a hold may reach, given the refreshes it already spent: past it, refreshing costs more than the cold resume it saves. */
-export const keepWarmHorizon = (cache: CacheClock, spent = 0): number =>
-    cache.at + cache.ttlMs + Math.max(0, keepWarmMaxRefreshes(cache.ttlMs) - spent) * (cache.ttlMs - keepWarmLeadMs(cache.ttlMs));
+/** The latest instant `left` more refreshes can carry an entry to: past it, refreshing costs more than the cold resume it saves. */
+export const keepWarmHorizon = (cache: CacheClock, left: number): number =>
+    cache.at + cache.ttlMs + Math.max(0, left) * (cache.ttlMs - keepWarmLeadMs(cache.ttlMs));
 
 /** When the next refresh is due for an entry last touched at `cache.at`. */
 export const keepWarmDueAt = (cache: CacheClock): number => cache.at + cache.ttlMs - keepWarmLeadMs(cache.ttlMs);
 
 /** The furthest `until` a hold can honestly promise: the economic horizon, or the date change, whichever comes first. */
-export const keepWarmCap = (cache: CacheClock, rollsAt: number | undefined, spent = 0): number =>
-    rollsAt === undefined ? keepWarmHorizon(cache, spent) : Math.min(keepWarmHorizon(cache, spent), rollsAt);
+export const keepWarmCap = (cache: CacheClock, rollsAt: number | undefined, left: number): number =>
+    rollsAt === undefined ? keepWarmHorizon(cache, left) : Math.min(keepWarmHorizon(cache, left), rollsAt);
 
-// Why a hold ended before anyone picked the conversation up. `elapsed` is the one ending that is not a problem.
-export const KeepWarmEndSchema = z.enum(["elapsed", "allowance", "limited", "changed", "rewrote", "cold", "failed", "midnight", "moved"]);
+// Why a hold ended before anyone picked the conversation up, one per thing a person would do about it; `detail` carries
+// the specifics. `elapsed` is the one ending that is not a problem.
+export const KeepWarmEndSchema = z.enum(["elapsed", "allowance", "changed", "cold", "failed"]);
 export type KeepWarmEnd = z.infer<typeof KeepWarmEndSchema>;
 
 export const KeepWarmSchema = z.object({
@@ -48,7 +41,6 @@ export const KeepWarmSchema = z.object({
         .describe(
             "When it stops by itself, in milliseconds: the time asked for, shortened to what the sandbox can honestly keep, which is never past the point where refreshing costs more than re-reading, nor past the date change that rewrites the prompt.",
         ),
-    auto: z.boolean().optional().describe("Started by the sandbox-wide setting after a turn, rather than by a press on this conversation."),
     refreshes: z.number().int().min(0).describe("Refreshes sent so far."),
     readTokens: z
         .number()
@@ -58,9 +50,12 @@ export const KeepWarmSchema = z.object({
         .object({
             at: z.number().describe("When it stopped, in milliseconds."),
             reason: KeepWarmEndSchema.describe(
-                "Why: `elapsed` the time asked for ran out; `allowance` the account reached the reserve kept for real work; `limited` the provider refused a refresh; `changed` what the next turn would send no longer matches the cache; `rewrote` a refresh found the cache already gone; `cold` it expired before a refresh could run; `failed` a refresh failed; `midnight` the date in the prompt changed; `moved` the conversation's session or account changed.",
+                "Why: `elapsed` the time asked for ran out; `allowance` the account reached the reserve kept for real work, or the provider refused a refresh for its limit; `changed` what the next turn would send no longer matches the cache (a part of the prompt, the date in it, or the conversation's session or account); `cold` the cache was gone, expired before a refresh could run or found missing by one; `failed` a refresh failed.",
             ),
-            detail: z.string().optional().describe("The specifics, when there are any: which parts of the prompt changed, or the failure's own words."),
+            detail: z
+                .string()
+                .optional()
+                .describe("The specifics, when there are any: which parts of the prompt changed, how full the account was, or the failure's own words."),
         })
         .optional()
         .describe("Why keeping it warm stopped before anyone picked the conversation up. Absent while it is still being kept."),

package/src/schemas/metrics.ts

@@ -53,15 +53,38 @@ export const PressureMetricsSchema = z.object({
 });
 export type PressureMetrics = z.infer<typeof PressureMetricsSchema>;
 
+// The memory figures the daemon admits work by (its resource budget), so a gauge built on them warns exactly when a turn
+// would be held.
+export const MemoryRoomSchema = z.object({
+    freeBytes: z
+        .number()
+        .optional()
+        .describe("The limit less what is used and what work admitted in the last minute and a half still holds. Absent where nothing measures it."),
+    reservedBytes: z.number().describe("What work admitted in the last minute and a half holds before it shows in `memoryBytes`."),
+    personNeedBytes: z.number().describe("What a person's turn needs free to start without a warning: below it, the sandbox is short."),
+    stallPercent: z.number().describe("Percent of the last ten seconds in which everything in the sandbox waited on memory (pressure `full`)."),
+    stallLimitPercent: z.number().describe("The stall at or past which the sandbox counts as short of memory, whatever `freeBytes` says."),
+});
+export type MemoryRoom = z.infer<typeof MemoryRoomSchema>;
+
 export const SandboxUsageSchema = z.object({
     cpuPercent: z
         .number()
         .optional()
         .describe("CPU the whole sandbox used over the window, as a percentage of all it may use (`cores`). Absent on a first reading."),
     cores: z.number().describe("How many cores the sandbox may use: its CPU quota, or every core it is allowed to run on when it has none."),
-    memoryBytes: z.number().describe("Memory in use, less the file cache the kernel takes back on demand: the figure that runs into the limit."),
-    memoryLimitBytes: z.number().describe("The memory limit: the container's own, or the machine's memory when the container has none."),
-    swapBytes: z.number().optional().describe("Memory pushed out to swap. Absent where the sandbox cannot see its own swap."),
+    memoryBytes: z
+        .number()
+        .describe(
+            "Memory in use as the daemon admits work by it: resident memory less the file cache the kernel takes back on demand, plus what was pushed to swap.",
+        ),
+    memoryLimitBytes: z
+        .number()
+        .describe(
+            "The memory limit work is admitted against: where the kernel starts throttling the container (memory.high), else its hard limit, else the machine's memory.",
+        ),
+    swapBytes: z.number().optional().describe("Of `memoryBytes`, what was pushed out to swap. Absent where the sandbox cannot see its own memory."),
+    memoryRoom: MemoryRoomSchema.optional().describe("What admission reads off the same reading. Absent from a daemon that predates it."),
     diskBytes: z.number().optional().describe("Space used on the volume the workspace lives on. Absent when the volume would not say."),
     diskTotalBytes: z.number().optional().describe("That volume's size. Absent when the volume would not say."),
     loadAverage: z
@@ -140,6 +163,8 @@ export const STORAGE_CLEANABILITY = {
     other: "none",
     // Git data and checkouts of repositories deleted from the workspace; nothing reads it again, but it may hold commits never pushed.
     trash: "confirm",
+    // Transcripts as they were before the sandbox converted them to its current format; nothing reads them again.
+    backups: "confirm",
     // Copies of the sandbox packed for download.
     exports: "confirm",
     // Files agents produced: generated images, reports, harness output.

package/src/schemas/offload.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { RunnerCommandFrameSchema, RunnerCommandSchema } from "../protocol/runner-protocol.js";
+
+// OFFLOADED WORK, as the in-sandbox `offload-run` command and the editor see it (settings `offload`): a heavy line this
+// sandbox hands a runner on one of the owner's machines instead of running it itself.
+
+// Whether a runner can take a line right now, asked before the tree is snapshotted, so a machine that is asleep costs
+// nothing. `name` is the machine the runner sits on, the word the owner picked it by.
+export const OffloadTargetSchema = z.object({
+    runner: z.string().min(1),
+    name: z.string().min(1),
+    ready: z.boolean(),
+    // Why not, in the words the command prints before it runs the line here instead.
+    why: z.string().optional(),
+});
+export type OffloadTarget = z.infer<typeof OffloadTargetSchema>;
+
+export const OffloadRunSchema = RunnerCommandSchema.extend({ runner: z.string().min(1) });
+export type OffloadRun = z.infer<typeof OffloadRunSchema>;
+
+// What a run streams back: the runner's own frames, or one refusal when the runner could not take it after all (it went
+// offline between the question and the run, or it predates offloading), which sends the line back here.
+export const OffloadFrameSchema = z.union([...RunnerCommandFrameSchema.options, z.object({ kind: z.literal("refused"), why: z.string() })]);
+export type OffloadFrame = z.infer<typeof OffloadFrameSchema>;
+
+// One offloaded run as the runner card lists it: the recent ones, kept in memory, newest first.
+export const OffloadRecordSchema = z.object({
+    runId: z.string(),
+    runner: z.string(),
+    name: z.string(),
+    label: z.string(),
+    // The line, cut to a readable length.
+    command: z.string(),
+    startedAt: z.number(),
+    endedAt: z.number().optional(),
+    code: z.number().int().optional(),
+    failure: z.string().optional(),
+});
+export type OffloadRecord = z.infer<typeof OffloadRecordSchema>;
+
+// One kind of heavy work the owner can send elsewhere: a heavy-command rule this sandbox queues (its id, as settings
+// `offload.commands` keys it) and the pattern that sorts a line into it.
+export const OffloadKindSchema = z.object({ id: z.string().min(1), pattern: z.string() });
+export type OffloadKind = z.infer<typeof OffloadKindSchema>;

package/src/schemas/personas.ts

@@ -42,6 +42,21 @@ export const PersonaPowersSchema = z.object({
     connectors: z.array(entryId).max(100).optional(),
     devices: z.array(entryId).max(50).optional(),
     mcp: z.array(entryId).max(50).optional(),
+    // By extension id (`publisher.name`, or a git install's card id), the same tri-state. A card an extension serves
+    // rides `connectors`; this is what the extension brings of its own.
+    extensions: z
+        .array(
+            z
+                .string()
+                .min(1)
+                .max(121)
+                .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/),
+        )
+        .max(100)
+        .optional()
+        .describe(
+            "Which extensions' own agent tools and agent plugin (skills, commands, subagents) it gets, by extension id. Absent means every enabled one; empty means none. The tools an extension serves for a connected card follow the connectors list instead.",
+        ),
 });
 export type PersonaPowers = z.infer<typeof PersonaPowersSchema>;
 // `folders` only refuses file-tool calls outside it; it stops a misread instruction, not a shell. The container is the
@@ -125,9 +140,9 @@ export const TURN_BRIEFING_NOTES: readonly TurnBriefingNote[] = [
     },
     {
         id: "checks",
-        label: "Automatic end-of-turn checks",
-        when: "First message, and again after a compaction, when you have rules that run at the end of a turn.",
-        cost: "Your checks still run; the agent just does not know they are coming, so a failure arrives as a surprise it has to re-read the turn to understand.",
+        label: "Checks after landing",
+        when: "First message and after a compaction, and again whenever the main tree's own check turns red or back to green: what runs after its work lands, and which failures the main tree already has.",
+        cost: "The agent does not know which failures are the main tree's own and not its doing, so it may spend a turn chasing one somebody else is already fixing.",
     },
     {
         id: "dependencies",

package/src/schemas/ports.ts

@@ -45,6 +45,16 @@ export const PortSummarySchema = z.object({
         .describe(
             'The terminal it came from, to watch it in or stop it from. Absent when nothing in its ancestry is one, which is the honest "you cannot reach this from here".',
         ),
+    // A job an agent's turn left running for the person (AgentSummary.jobs[].handed); ports listed anywhere else stay
+    // unclaimed by any conversation.
+    job: z
+        .object({
+            conversationId: z.string().describe("The conversation whose turn left it running."),
+            jobId: z.string().describe("The job, as that conversation's card names it; stopping it stops this port."),
+            label: z.string().describe("What the job is, in the agent's own words when it gave any."),
+        })
+        .optional()
+        .describe("The background job an agent left running for you on this port, when that is what answers here."),
     forwarded: z.boolean().describe("Whether it is currently reachable from outside."),
     // `https://port-<slot>-<sandboxId>.<zone>`.
     previewUrl: z.string().optional().describe("Where to open it. Present only while forwarded, and only on a sandbox that has an outside address."),

package/src/schemas/providers/plan-limits.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ChildRunSchema } from "../../events/requests.js";
 import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../../models/provider-specs.js";
 import { AgentHarnessSchema, AgentProviderSchema, EditorContextSchema } from "../agent.js";
 import { MENTION_LIMIT } from "../../text/mentions.js";
@@ -24,13 +25,58 @@ export const UsageWindowSchema = z.object({
     gates: WindowGatesSchema,
 });
 export type UsageWindow = z.infer<typeof UsageWindowSchema>;
+// A failed re-read, whatever the cause: a 429 park, a 403 asking for verification, a 5xx, a timeout. Recorded as the fact
+// "the last attempt failed", never inferred from a list of known failure kinds, so a surface that dates readings by
+// age can leave out every reading that cannot move, including one whose failure nobody has seen before.
+export const UsageUnreadSchema = z.object({
+    since: z.number().describe("When re-reading this account first failed, in milliseconds. It has failed on every attempt since."),
+    reason: z
+        .string()
+        .describe("Why, in the provider's own words where it gave some (\"Verify your account to continue.\"). Short enough to print; never a pasted response body."),
+});
+export type UsageUnread = z.infer<typeof UsageUnreadSchema>;
 // Every window kept, not just the binding one, since which pool binds changes between turns. Utilization only climbs
 // within a window, so a stale reading is still a valid floor. `measuredAt` is epoch ms — windows are seconds.
 export const AccountUsageSchema = z.object({
     windows: z.array(UsageWindowSchema),
     measuredAt: z.number(),
+    unread: UsageUnreadSchema.optional().describe(
+        "Present while re-reading this account keeps failing: these windows are the last reading that succeeded, and `measuredAt` will not move until a read succeeds again.",
+    ),
 });
 export type AccountUsage = z.infer<typeof AccountUsageSchema>;
+// Who has to act for a blocked account, which is the only thing a surface chooses its instruction by: the reason is the
+// words for a person, never a key.
+export const AccountFixSchema = z.enum(["reconnect", "admin", "wait"]);
+export type AccountFix = z.infer<typeof AccountFixSchema>;
+// Whether an account can serve a turn, decided once by the daemon (models/plan-pools.ts `serviceState`) from every fact
+// it holds about it: a revoked sign-in, a lost seat, a translator bench, a refusal still standing, and its plan limits.
+// Every picker (an unnamed turn, a limit move, a keep-warm refresh) and every surface reads this one verdict.
+export const AccountStateSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("ready"),
+        room: z
+            .number()
+            .describe("How much of the fullest pool that gates the turn is left, in percent (above 0, up to 100). Pickers take the most room."),
+    }),
+    z.object({
+        kind: z.literal("spent"),
+        reopensAt: z
+            .number()
+            .optional()
+            .describe("When every full pool has reopened, in epoch seconds, where the plan publishes it. Absent means unknown, never now."),
+    }),
+    z.object({
+        kind: z.literal("blocked"),
+        fix: AccountFixSchema.describe(
+            "Who can make it serve again: `reconnect` (sign in again on this sandbox), `admin` (an organisation admin hands the seat back), or `wait` (it lifts by itself, at `until` where known).",
+        ),
+        reason: z.string().describe("Why, in words a person can act on: the provider's own sentence where it gave one."),
+        until: z.number().optional().describe("When waiting lifts it, in epoch seconds, for `wait` only."),
+    }),
+    z.object({ kind: z.literal("unknown").describe("Nothing blocks it and nothing has been measured: usable, never read as room.") }),
+]);
+export type AccountState = z.infer<typeof AccountStateSchema>;
 // Anthropic's once-a-week reset of the session window only; the weekly allowance is untouched. The answer is entirely
 // the provider's — never infer `available` from a 100% window. `reason` is its own word, carried verbatim.
 export const LimitResetStatusSchema = z.object({
@@ -107,6 +153,9 @@ export const TranslatorAccountSchema = z.object({
             reason: z.string().optional(),
         })
         .optional(),
+    state: AccountStateSchema.optional().describe(
+        "Whether it can serve a turn now, judged from everything above plus the provider's last refusal. Absent from a daemon older than this field.",
+    ),
 });
 export type TranslatorAccount = z.infer<typeof TranslatorAccountSchema>;
 // A list per provider, not a flag: CLIProxyAPI holds several auth files per provider and balances across them. Built
@@ -154,6 +203,10 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             .enum(["once", "always", "deny"])
             .describe("Once allows this call alone; always allows that whole tool for the rest of the conversation; no blocks it."),
         feedback: z.string().optional().describe("Why not, which goes back to the model as the reason."),
+        // Whole, not a patch: effort or an account named for one model means nothing on another.
+        child: ChildRunSchema.optional().describe(
+            "For a request to start a child agent: what to start it on instead of what the agent asked for. It replaces the whole run (model, account, effort and the rest), not only the fields it names. Ignored with a no, and on any other request.",
+        ),
     }),
     z.object({
         kind: z
@@ -208,6 +261,11 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
     }),
 ]);
 export type AgentReply = z.infer<typeof AgentReplySchema>;
+// Every card a turn can park on its person with, one per reply kind, so a new card reaches every park reader at once.
+export type ParkKind = AgentReply["kind"];
+export const PARK_KINDS: readonly ParkKind[] = AgentReplySchema.options.map((option) => option.shape.kind.value);
+const PARKING = new Set<string>(PARK_KINDS);
+export const isParkKind = (kind: string): kind is ParkKind => PARKING.has(kind);
 // A message injected into a running turn between tool calls; NOT_FOUND when none is steerable, and the client queues it
 // as the next turn instead. Carries everything a fresh prompt can (files, editor context).
 export const SteerSchema = z
@@ -282,7 +340,12 @@ export type StopResult = z.infer<typeof StopResultSchema>;
 export const ResumeRoutingSchema = z.object({
     agent: AgentProviderSchema.describe("Which provider serves the re-run."),
     harness: AgentHarnessSchema.describe("Which agentic loop runs it."),
-    account: z.string().optional().describe("Which of that provider's accounts pays for it. Leave it out for the first one."),
+    account: z
+        .string()
+        .optional()
+        .describe(
+            "Which of that provider's accounts pays for it. Leave it out to keep the account the conversation runs on, or, on another provider, to take whichever of its accounts can serve with the most room. Moving to another account of the same provider is `switchAccount`'s job; naming one here still works.",
+        ),
     // A client whose catalog hasn't loaded has nothing to send; the turn's own model is the better fallback.
     model: z.string().optional().describe("Which model. Leave it out to keep the one the refused turn named."),
     // A session is a file the daemon keeps; a credential is an env var. That's what lets a same-provider account switch
@@ -326,3 +389,23 @@ export const QueueResumeSchema = z.object({
     ),
 });
 export type QueueResume = z.infer<typeof QueueResumeSchema>;
+// Moves a conversation to another account of the provider it runs on: the one command that changes who pays, so the
+// account a conversation runs on is always the daemon's record and never a window's guess.
+export const SwitchAccountSchema = z.object({
+    conversationId: z.string().min(1).describe("Which conversation to move."),
+    account: z.string().min(1).describe("Which of the conversation's provider's connected accounts pays for its turns from now on."),
+    carry: z
+        .boolean()
+        .optional()
+        .describe(
+            "Keep the provider session across the move (the model keeps everything, and re-reads all of it once on the other account) rather than opening a fresh one seeded from the record.",
+        ),
+});
+export type SwitchAccount = z.infer<typeof SwitchAccountSchema>;
+export const AccountSwitchedSchema = z.object({
+    run: z
+        .string()
+        .optional()
+        .describe("The run that re-ran a held turn on the new account, when one was waiting: attach to it. Absent when nothing was held."),
+});
+export type AccountSwitched = z.infer<typeof AccountSwitchedSchema>;