@intentic/sandbox-contract 1.341.0 → 1.342.0

package/src/contracts/workspace.contract.ts

@@ -35,6 +35,8 @@ import {
     WorkspaceMediaTicketQuerySchema,
     WorkspaceMediaTicketSchema,
     WorkspaceDownloadTicketQuerySchema,
+    WorkspacePreviewTicketQuerySchema,
+    WorkspacePreviewTicketSchema,
     WorkspaceDownloadTicketSchema,
     WorkspaceMoveSchema,
     WorkspaceResolveQuerySchema,
@@ -134,6 +136,19 @@ export const workspaceContract = {
         .meta({ floor: "viewer", guest: true })
         .input(WorkspaceDownloadTicketQuerySchema)
         .output(WorkspaceDownloadTicketSchema),
+    // Mints the ticket GET /workspace/preview/{ticket}/* (a plain Hono route serving a page and its files) requires.
+    previewTicket: procedure
+        .route({
+            method: "POST",
+            path: "/workspace/preview-ticket",
+            summary: "Get an address to preview a web page at",
+            description:
+                "Mints a short-lived address a frame loads a workspace web page from, so the page runs as it would on a static file server: its scripts, modules, fetches and links resolve against real addresses beside it. The address serves the files of the page's own repository, never hidden files or the sandbox's own state, and the page runs sandboxed, with no access to the editor or this API.",
+        })
+        // Previewing a page is reading it and the files beside it, and the ticket is narrower than the bearer.
+        .meta({ floor: "viewer", guest: true })
+        .input(WorkspacePreviewTicketQuerySchema)
+        .output(WorkspacePreviewTicketSchema),
     // Matches a prose-written path, often just a suffix, against the tree rather than trusting it as root-relative.
     resolve: procedure
         .route({

package/src/models/agent-standing.ts

@@ -111,7 +111,8 @@ export const limited = (agent: AgentStanding): boolean => agent.status === "erro
 
 // A message held at the door because the sandbox is short of memory (turn-admission): nothing ran and nothing failed,
 // it waits for a person's "send anyway". The daemon files it as an `error`, so this is read off the code, as `limited`
-// is, and the chip and glyph say held rather than error; the lane stays Attention, since the press is the reader's.
+// is, and the chip and glyph say held rather than error; the lane stays Attention, since the press is the reader's,
+// until its words are booked for later (bookingAnswers).
 export const memoryHeld = (agent: Pick<AgentStanding, "status" | "failureCode">): boolean =>
     agent.status === "error" && agent.failureCode === "sandbox-memory-low";
 
@@ -218,13 +219,29 @@ export const writingNow = (agent: AgentStanding): boolean => agent.status === "r
 // `stopped`/`interrupted` leave a half-written worktree only a new message can carry forward; `stopping` is
 // counted the moment the press lands rather than once the unwind finishes, since it settles in the same lane
 // either way; `failed` is the same kind of dead end one step earlier, before a worktree existed. A spent allowance
-// counts until something is booked to carry it on (limitScheduled): a resend at the reset, or a move now.
+// counts until something is booked to carry it on (limitScheduled): a resend at the reset, or a move now. Any settled
+// dead end counts until a booking answers it (bookingAnswers).
 const BLOCKING_ENDINGS: ReadonlySet<AgentStatus | ClientAgentStatus> = new Set(["error", "interrupted", "stopping", "stopped", "failed"]);
 
 // A land that broke and still stands: its work is stuck on the branch, whatever the turn after it did, so the card is
 // the reader's to look at. Not while a turn or a land is under way, which ends in another land of its own.
 export const landBroken = (agent: AgentStanding): boolean => agent.landFailure !== undefined && !turnInFlight(agent);
 
+// The settled dead ends a booking can answer. Not `stopping`, which is still unwinding and rests in Attention whatever
+// waits behind it.
+const ANSWERABLE_ENDINGS: ReadonlySet<AgentStatus | ClientAgentStatus> = new Set(["error", "interrupted", "stopped", "failed"]);
+
+/**
+ * A turn that ended badly, with something booked to go by itself after it: a message for a time, a continuation at a
+ * spent allowance's reopen, words held for memory re-timed to that reopen. That booking is the person's answer to the
+ * ending, or the sandbox's on their standing word, so the next move is the sandbox's, at the booking, and the ending no
+ * longer calls the reader: the card is Active, and its corner says when it goes. Before 2026-10-18 only the sandbox's own
+ * booked resend after a spent allowance (limitScheduled) answered an ending, so an expired account's card stayed in
+ * Attention under a clock already saying "sends Sun 05:00", the reader's answer to it booked and not counted. Answers
+ * only the ending: an ask (a plan, a question, a permission, a land only the reader can clear) still calls them.
+ */
+export const bookingAnswers = (agent: AgentStanding): boolean => ANSWERABLE_ENDINGS.has(agent.status) && scheduledSend(agent);
+
 export const blocked = (agent: AgentStanding): boolean =>
     limitScheduled(agent)
         ? false
@@ -238,7 +255,7 @@ export const blocked = (agent: AgentStanding): boolean =>
           (agent.attention.need === true && agent.status !== "running") ||
           landBroken(agent) ||
           heldByPrompt(agent) ||
-          BLOCKING_ENDINGS.has(agent.status);
+          (BLOCKING_ENDINGS.has(agent.status) && !bookingAnswers(agent));
 
 // The half of `blocked` that is literally waiting on an answer (plan, question, permission, capability), narrower
 // than `blocked`: dead ends (a failed turn, an unlandable conflict) want looking at but owe the user nothing, so
@@ -273,6 +290,7 @@ export const heardByParent = (child: AgentStanding & { readonly updatedAt: numbe
     child.status !== "stopping" &&
     // Booked to run again by itself: not over, whatever its parent made of the pause.
     !limitScheduled(child) &&
+    !bookingAnswers(child) &&
     !child.attention.question &&
     !child.attention.conflict &&
     !landBroken(child) &&

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

@@ -40,6 +40,9 @@ export const RAW_ROUTES = {
     "GET /workspace/media": { auth: "door", guest: true, lane: "bulk" },
     // Navigated to for a ZIP of a selection, so no header either: the ticket it carries names the selection.
     "GET /workspace/download": { auth: "door", guest: true, lane: "bulk" },
+    // A previewed web page and the files it names, loaded by a frame, which sends no header: the ticket is the path's
+    // first segment, so the page's relative addresses carry it, and it is checked in the handler.
+    "GET /workspace/preview/{ticket}/*": { auth: "door", guest: true },
     // An attachment is part of the message it rides with; any other target edits the shared tree.
     "POST /workspace/upload": { floor: "writer", attachmentFloor: "collaborator", lane: "bulk" },
     "POST /workspace/upload-diff": {},

package/src/schemas/agent.ts

@@ -533,6 +533,12 @@ export const QueuedMessageSchema = z.object({
     after: ConversationIdSchema.optional().describe(
         "The conversation whose finished work must land before this message goes out by itself, in place of `until`.",
     ),
+    continues: z
+        .literal(true)
+        .optional()
+        .describe(
+            "A continuation, not words: when it goes, the conversation carries on from where its last turn stopped, as `agent.run` with `continues` does, and nothing is added to it as anybody's message. `text` is empty. A turn that starts in the conversation before it goes makes it moot, and it is dropped.",
+        ),
 });
 export type QueuedMessage = z.infer<typeof QueuedMessageSchema>;
 // Why a queue holds its messages rather than letting them go when the conversation is free.

package/src/schemas/dev-rebuild-log.test.ts

@@ -1,4 +1,4 @@
-import { DEV_REBUILD_EXIT_MARK, DEV_REBUILD_QUIET_MARK, devRebuildLogPath, readDevRebuildLog } from "./devices.js";
+import { DEV_REBUILD_EXIT_MARK, DEV_REBUILD_QUIET_MARK, devRebuildLogPath, readDevRebuildLog } from "./dev-rebuild-log.js";
 
 // The one account a detached rebuild gives of itself. The daemon builds the shell that writes this text and the browser
 // draws what it means, so the grammar is pinned here, where both of them read it.

package/src/schemas/dev-rebuild-log.ts

@@ -0,0 +1,58 @@
+// What a detached `dev-rebuild` leaves behind on the machine that runs it, and how `dev-rebuild-log` reads it back.
+// devices.ts re-exports all of it beside the device commands that name it.
+
+// WHERE A DETACHED REBUILD REPORTS ITSELF. `dev-rebuild` returns the moment the build is under way and nothing streams
+// back from it — a cold build outruns any timeout this door has, and the container swap at the end kills the daemon that
+// would have read the answer — so the build writes here instead, in the folder ic logs its own recreates into, and
+// `dev-rebuild-log` reads it back. Spelled once, here, because the daemon builds both command lines from it and the
+// browser names the same path to a reader whose rebuild never came back.
+export const devRebuildLogPath = (slug: string): string => `~/.intentic/logs/dev-rebuild-${slug}.log`;
+
+// The build's own shell appends this when the build ends, with its exit status: since the log outlives the daemon, the
+// container and the page that started it, this mark is the only thing that can say a rebuild is OVER rather than slow.
+export const DEV_REBUILD_EXIT_MARK = "@intentic-rebuild-exit";
+// `dev-rebuild-log` prints this first, then how many seconds it is since the log last grew — `-` when there is no log on
+// that machine at all. A running build goes quiet for a minute at a time inside a docker layer; a build whose machine
+// slept never writes its exit mark, and only this tells the two apart.
+export const DEV_REBUILD_QUIET_MARK = "@intentic-rebuild-quiet";
+
+export interface DevRebuildLog {
+    /** Nothing has ever rebuilt this sandbox from a checkout on that machine. */
+    readonly missing: boolean;
+    /** Seconds since the log last grew; undefined when the machine's `stat` wouldn't say. */
+    readonly quietFor: number | undefined;
+    /** The build's own exit status, present only once it has ended. */
+    readonly exitCode: number | undefined;
+    /** The tail as the machine printed it, both marks removed. */
+    readonly lines: readonly string[];
+}
+
+// Reads `dev-rebuild-log`'s stdout. Shared rather than parsed at the reader, so the shell line that produces this and the
+// card that draws it cannot drift apart. Unparseable is never an error: an answer with no marks at all is simply a log
+// with nothing to say yet.
+const markValue = (line: string, mark: string): string | undefined => (line.startsWith(`${mark} `) ? line.slice(mark.length + 1).trim() : undefined);
+const wholeNumber = (value: string): number | undefined => (/^\d+$/.test(value) ? Number(value) : undefined);
+
+export const readDevRebuildLog = (text: string): DevRebuildLog => {
+    let missing = false;
+    let quietFor: number | undefined;
+    let exitCode: number | undefined;
+    const lines: string[] = [];
+    for (const line of text.split(/\r?\n/)) {
+        const quiet = markValue(line, DEV_REBUILD_QUIET_MARK);
+        const exit = markValue(line, DEV_REBUILD_EXIT_MARK);
+        if (quiet !== undefined) {
+            missing = quiet === "-";
+            quietFor = wholeNumber(quiet);
+        } else if (exit !== undefined) {
+            // A mark whose status is unreadable still means the build ENDED, and not well.
+            exitCode = wholeNumber(exit) ?? 1;
+        } else {
+            lines.push(line);
+        }
+    }
+    while (lines.at(-1)?.trim() === "") {
+        lines.pop();
+    }
+    return { missing, quietFor, exitCode, lines };
+};

package/src/schemas/devices.ts

@@ -266,61 +266,9 @@ export type DeviceCommand = z.infer<typeof DeviceCommandSchema>;
 export const DeviceSyncSwitchSchema = DeviceCommandSchema.exclude(["dev-restart", "dev-rebuild", "dev-rebuild-log", "sync-install", "sync-clean"]);
 export type DeviceSyncSwitch = z.infer<typeof DeviceSyncSwitchSchema>;
 
-// WHERE A DETACHED REBUILD REPORTS ITSELF. `dev-rebuild` returns the moment the build is under way and nothing streams
-// back from it — a cold build outruns any timeout this door has, and the container swap at the end kills the daemon that
-// would have read the answer — so the build writes here instead, in the folder ic logs its own recreates into, and
-// `dev-rebuild-log` reads it back. Spelled once, here, because the daemon builds both command lines from it and the
-// browser names the same path to a reader whose rebuild never came back.
-export const devRebuildLogPath = (slug: string): string => `~/.intentic/logs/dev-rebuild-${slug}.log`;
-
-// The build's own shell appends this when the build ends, with its exit status: since the log outlives the daemon, the
-// container and the page that started it, this mark is the only thing that can say a rebuild is OVER rather than slow.
-export const DEV_REBUILD_EXIT_MARK = "@intentic-rebuild-exit";
-// `dev-rebuild-log` prints this first, then how many seconds it is since the log last grew — `-` when there is no log on
-// that machine at all. A running build goes quiet for a minute at a time inside a docker layer; a build whose machine
-// slept never writes its exit mark, and only this tells the two apart.
-export const DEV_REBUILD_QUIET_MARK = "@intentic-rebuild-quiet";
-
-export interface DevRebuildLog {
-    /** Nothing has ever rebuilt this sandbox from a checkout on that machine. */
-    readonly missing: boolean;
-    /** Seconds since the log last grew; undefined when the machine's `stat` wouldn't say. */
-    readonly quietFor: number | undefined;
-    /** The build's own exit status, present only once it has ended. */
-    readonly exitCode: number | undefined;
-    /** The tail as the machine printed it, both marks removed. */
-    readonly lines: readonly string[];
-}
+// Where a detached rebuild reports itself, and the reader of that report (dev-rebuild-log.ts).
+export { DEV_REBUILD_EXIT_MARK, DEV_REBUILD_QUIET_MARK, type DevRebuildLog, devRebuildLogPath, readDevRebuildLog } from "./dev-rebuild-log.js";
 
-// Reads `dev-rebuild-log`'s stdout. Shared rather than parsed at the reader, so the shell line that produces this and the
-// card that draws it cannot drift apart. Unparseable is never an error: an answer with no marks at all is simply a log
-// with nothing to say yet.
-const markValue = (line: string, mark: string): string | undefined => (line.startsWith(`${mark} `) ? line.slice(mark.length + 1).trim() : undefined);
-const wholeNumber = (value: string): number | undefined => (/^\d+$/.test(value) ? Number(value) : undefined);
-
-export const readDevRebuildLog = (text: string): DevRebuildLog => {
-    let missing = false;
-    let quietFor: number | undefined;
-    let exitCode: number | undefined;
-    const lines: string[] = [];
-    for (const line of text.split(/\r?\n/)) {
-        const quiet = markValue(line, DEV_REBUILD_QUIET_MARK);
-        const exit = markValue(line, DEV_REBUILD_EXIT_MARK);
-        if (quiet !== undefined) {
-            missing = quiet === "-";
-            quietFor = wholeNumber(quiet);
-        } else if (exit !== undefined) {
-            // A mark whose status is unreadable still means the build ENDED, and not well.
-            exitCode = wholeNumber(exit) ?? 1;
-        } else {
-            lines.push(line);
-        }
-    }
-    while (lines.at(-1)?.trim() === "") {
-        lines.pop();
-    }
-    return { missing, quietFor, exitCode, lines };
-};
 // Machine's sandbox id (absent = every paired sandbox); must start alphanumeric, else it parses as a CLI flag.
 export const DeviceSandboxIdSchema = z
     .string()

package/src/schemas/keep-warm.ts

@@ -131,3 +131,37 @@ export type PromptFingerprint = z.infer<typeof PromptFingerprintSchema>;
 /** Which parts differ between two fingerprints, by name; empty when they match. */
 export const changedParts = (before: PromptFingerprint, after: PromptFingerprint): string[] =>
     [...new Set([...Object.keys(before.parts), ...Object.keys(after.parts)])].filter((name) => before.parts[name] !== after.parts[name]).toSorted();
+
+// keep-warm's knobs, one object since each only means anything beside the others (cache-keepwarm.ts).
+export const KeepWarmSettingsSchema = z.object({
+    auto: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Keep a Claude conversation's prompt cache warm after each turn a person asked for. Each refresh re-reads the cached context at the cache price and adds nothing to the conversation.",
+        ),
+    hours: z
+        .number()
+        .min(1)
+        .max(8)
+        .default(4)
+        .describe(
+            "How long an idle conversation is kept warm after its last turn, in hours, and what a press on one offers first. Shortened where refreshing would cost more than the cold resume it saves, and at midnight where the agent runs, when the date in its prompt changes.",
+        ),
+    minTokens: z
+        .number()
+        .int()
+        .min(0)
+        .default(100_000)
+        .describe("Only conversations at least this large, in tokens, are kept warm by `auto`: a small one is cheap to re-read anyway."),
+    reserve: z
+        .number()
+        .int()
+        .min(0)
+        .max(90)
+        .default(15)
+        .describe(
+            "How much of an account's usage limit, in percent, keeping conversations warm must leave untouched for real work. Refreshing stops once any limit that account's model spends is fuller than that.",
+        ),
+});
+export type KeepWarmSettings = z.infer<typeof KeepWarmSettingsSchema>;

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

@@ -484,6 +484,35 @@ export const QueueScheduleSchema = z
         message: "a conversation cannot wait for its own work to land",
     });
 export type QueueSchedule = z.infer<typeof QueueScheduleSchema>;
+// Books the conversation to carry on from where its last turn stopped, at an instant or once another conversation's work
+// lands: a Continue (`agent.run` with `continues`) that waits in the queue, where every window draws it as scheduled,
+// rather than words. What a spent allowance's "Continue at 05:00" books, where it once booked the word "Continue".
+export const QueueContinueSchema = z
+    .object({
+        conversationId: z.string().min(1).describe("Which conversation carries on."),
+        sendAt: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Carry on at this instant (epoch milliseconds). At most a month ahead; an instant already past carries on now."),
+        sendAfter: ConversationIdSchema.optional().describe("Carry on once that conversation has finished and all of its work has landed, instead."),
+        routing: ResumeRoutingSchema.optional().describe(
+            "Who serves the turn it starts. Leave it out to carry on where the conversation runs when it goes.",
+        ),
+        messageId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Names the booking, so the same press sent twice books it once."),
+    })
+    .refine((input) => (input.sendAt === undefined) !== (input.sendAfter === undefined), {
+        message: "name exactly one of sendAt and sendAfter",
+    })
+    .refine((input) => input.sendAfter !== input.conversationId, {
+        message: "a conversation cannot wait for its own work to land",
+    });
+export type QueueContinue = z.infer<typeof QueueContinueSchema>;
 // 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({

package/src/schemas/providers/usage.ts

@@ -96,6 +96,15 @@ export const UsageTurnSchema = z.object({
     // Hash of the brief that was sent, recorded on control turns too. Load-bearing rather than decorative: the file is
     // rewritten monthly, so a 30-day window holds two different treatments and pooling them would measure neither.
     notesCohort: z.string().optional(),
+    // Arm of the tool-search experiment, stable per conversation: true loads connected tools' schemas on demand, false
+    // sends them all with every request. Absent where the turn was not a native Claude one on the Claude Code loop.
+    toolSearchArm: z.boolean().optional(),
+    // Arm of the stable-prompt experiment, stable per conversation: true says the guidance that moves between turns on
+    // the message when it changed, false keeps it in the system block. Absent outside the Claude Code loop.
+    stablePromptArm: z.boolean().optional(),
+    // Assigned on cold-eligible follow-ups only, including controls; cleared results only when a copy was resumed.
+    coldTrimArm: z.boolean().optional(),
+    coldTrimmed: z.number().int().min(0).optional(),
     // What became of pre-turn retrieval on this turn, and how long it took. Assignment and DELIVERY are different
     // facts: the first version of this mechanism was assigned to every eligible turn and reached four in five of them,
     // which is the difference between a null result and a mechanism that never ran. Absent means the flag was off, so

package/src/schemas/settings-experiments.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+
+// Agent experiments share conversation-stable arms; the sandbox settings schema owns their persisted shape.
+export const claudeExperimentSettings = {
+    // Claude Code turns itself out of tool search whenever its base URL is not Anthropic's own host, and the privacy
+    // shield's gateway is a loopback address, so every shielded native Claude turn paid every MCP tool's schema on every
+    // call (2026-10-18: a median 83k-token prompt before the first tool ran). The gateway forwards `tool_reference`
+    // blocks and the beta header untouched, so this asks for it by name. Native Claude only: a translator or minted
+    // endpoint may not speak the beta.
+    toolSearch: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Load the schemas of connected tools (browsers, devices, accounts, phones) only when the agent looks one up, instead of sending all of them with every request. The tools the agent leans on every turn stay loaded. Applies to Claude models on the Claude Code loop.",
+        ),
+    // Both arms set the CLI's switch explicitly, so a shielded turn and an unshielded one compare the same two things.
+    toolSearchHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.5)
+        .describe(
+            "What share of conversations to run with every tool loaded up front, so the two can be compared. Whole conversations rather than individual turns, because switching mid-conversation would rewrite the prompt the cache holds.",
+        ),
+    // Until 2026-10-18 this switch was read by nothing. The guidance paragraphs whose condition moves between turns (who
+    // is watching, which of the owner's machines, browsers and phones are online) sat in the system block, so each move
+    // rewrote the whole conversation to the provider's cache, and where Claude Code records a session's system prompt
+    // once the move never reached the model. Now they ride the turn's message, said when they changed.
+    stableSystemPrompt: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Keep the instructions identical between turns so the provider can cache them, saying what changes between turns (who is watching, which of your computers, browsers and phones are connected) on the message instead, and only when it changed. Applies to the Claude Code loop.",
+        ),
+    stableSystemPromptHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.5)
+        .describe(
+            "What share of conversations to run with those changing paragraphs kept in the instructions, so the two can be compared. Whole conversations rather than individual turns, because moving them mid-conversation would itself rewrite the cached prompt.",
+        ),
+    coldTrim: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Resume large Claude Code conversations with older tool output cleared once their prompt cache has expired. Keeps the conversation and tool calls, with directions to recover cleared output, and shows a trim notice.",
+        ),
+    coldTrimHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.5)
+        .describe(
+            "What share of conversations to resume whole when their cache is cold, so opening prompt size and failed tool calls can be compared. Whole conversations keep the same arm across follow-up turns.",
+        ),
+    coldTrimMinTokens: z
+        .number()
+        .int()
+        .min(0)
+        .default(100_000)
+        .describe(
+            "How many measured context tokens a Claude Code session must exceed before a cold follow-up can clear older tool output. Smaller sessions save little from trimming.",
+        ),
+};
+
+export const iqSearchSettings = {
+    iqSearch: z
+        .boolean()
+        .default(false)
+        .describe("Teach the agent how to use this workspace's own search tool, rather than leaving it to grep around."),
+    iqSearchHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe(
+            "What share of conversations to run without that teaching, so the two can be compared. Whole conversations rather than individual turns, because once the teaching is in a session, withholding it from the next request does not make the model forget it.",
+        ),
+};

package/src/schemas/settings.ts

@@ -2,10 +2,12 @@
 // itself, which those settings adopt.
 import { STATE_DIR } from "@intentic/constants";
 import { z } from "zod";
+import { claudeExperimentSettings, iqSearchSettings } from "./settings-experiments.js";
 import { CommandJudgeModeSchema, ProjectInstallModeSchema } from "../policy/safety-policy.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
 import { MODEL_SETUP_ID, ModelSetupSchema } from "../models/model-setups.js";
 import { AdmissionPolicySchema, AdmissionRuleSchema } from "./agent.js";
+import { KeepWarmSettingsSchema } from "./keep-warm.js";
 import { LimitHandoffSchema } from "./providers/handoff.js";
 import { SessionsPlacementSchema } from "./offload.js";
 import { LimitPolicySchema, RetryPolicySchema, RoomPolicySchema } from "./turn-break.js";
@@ -211,39 +213,8 @@ export type SkillSwitch = z.infer<typeof SkillSwitchSchema>;
 // picks rather than failing whole. A setting removed or reshaped here gets its conversion in settings-history.ts, which
 // also names every retired setting, none of whose names may come back.
 
-// keep-warm's knobs, one object since each only means anything beside the others (cache-keepwarm.ts).
-export const KeepWarmSettingsSchema = z.object({
-    auto: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Keep a Claude conversation's prompt cache warm after each turn a person asked for. Each refresh re-reads the cached context at the cache price and adds nothing to the conversation.",
-        ),
-    hours: z
-        .number()
-        .min(1)
-        .max(8)
-        .default(4)
-        .describe(
-            "How long an idle conversation is kept warm after its last turn, in hours, and what a press on one offers first. Shortened where refreshing would cost more than the cold resume it saves, and at midnight where the agent runs, when the date in its prompt changes.",
-        ),
-    minTokens: z
-        .number()
-        .int()
-        .min(0)
-        .default(100_000)
-        .describe("Only conversations at least this large, in tokens, are kept warm by `auto`: a small one is cheap to re-read anyway."),
-    reserve: z
-        .number()
-        .int()
-        .min(0)
-        .max(90)
-        .default(15)
-        .describe(
-            "How much of an account's usage limit, in percent, keeping conversations warm must leave untouched for real work. Refreshing stops once any limit that account's model spends is fuller than that.",
-        ),
-});
-export type KeepWarmSettings = z.infer<typeof KeepWarmSettingsSchema>;
+// keep-warm's knobs live with its clock (keep-warm.ts); re-exported, as every settings reader imports them from here.
+export { type KeepWarmSettings, KeepWarmSettingsSchema } from "./keep-warm.js";
 
 // Who the editor's screens are written for: `developer` reads git's own words (branch, land, commit), `maker` plain ones
 // (draft, accept, save) over the same mechanisms. The editor's vocabulary, never anything an agent does. A person's own
@@ -273,12 +244,6 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Which clock this sandbox's schedules are set by, as a zone name like Europe/Warsaw. Automations that repeat on a clock fire by this, not by the machine's own time. Leave it empty and they fire by UTC, which is almost certainly not what you meant when you typed a time.",
         ),
-    stableSystemPrompt: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Keep the instructions identical between turns so the provider can cache them, moving anything that varies into the message instead. Cheaper, at the cost of some flexibility.",
-        ),
     skills: z.array(z.string()).default(["lsp", "fileq"]).describe("Which built-in tools are switched on. A skill of your own is not listed here: it is on while the agent's copy of it exists."),
     // One half of the reading a new chat gets between send and its first turn (chat-router.ts): with this on, the
     // message and one line per card are put to the same model that chooses what the chat runs on, in the same call.
@@ -306,6 +271,15 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Keep the text of every document in the workspace (pdf, Word, OpenDocument, spreadsheets, presentations, epub, and scans where OCR is installed) ready to search. In the background, one low-priority process at a time, each document is rendered to text when it appears or changes, so `rg` and iq find what documents say under their own paths, cited by page. Off, nothing renders until someone opens a document, and searches skip them.",
         ),
+    // Whether the daemon tells its host it is unneeded (system/quiet-watch.ts): off, the work signal carries no
+    // `quietSince` and says `keepAwake`, so the machine's keeper never puts it to sleep (ic's `sandbox sleep`). Only a
+    // sandbox on somebody's own computer sleeps that way; a hosted machine's idle stop is the plan's and ignores this.
+    sleepWhenUnused: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Let the computer this sandbox runs on put it to sleep after a stretch nobody needs it (no editor open, no agent working, no terminal typed in, no app of it open), which frees its memory. It starts again when somebody opens it, and a few minutes before anything it has scheduled comes due, so automations still run on time. Off keeps it running. Applies only to a sandbox on your own computer.",
+        ),
     hashlineEdits: z
         .boolean()
         .default(false)
@@ -329,18 +303,8 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Your own instructions, used only when the mode above says custom. Then it is the whole of them: both built-in bases go, and so does everything this product would otherwise add, including the guidance the chat's own cards are driven by. That is the price of total control.",
         ),
-    iqSearch: z
-        .boolean()
-        .default(false)
-        .describe("Teach the agent how to use this workspace's own search tool, rather than leaving it to grep around."),
-    iqSearchHoldout: z
-        .number()
-        .min(0)
-        .max(1)
-        .default(0)
-        .describe(
-            "What share of conversations to run without that teaching, so the two can be compared. Whole conversations rather than individual turns, because once the teaching is in a session, withholding it from the next request does not make the model forget it.",
-        ),
+    ...iqSearchSettings,
+    ...claudeExperimentSettings,
     // Rooted at the run's own starting folder (a persona's, an isolated conversation's worktree), not the workspace
     // root — it maps the project containing that folder.
     workspaceMap: z
@@ -738,10 +702,14 @@ export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() }
 // openedWithListing: whether a turn listed directories to orient itself, as a share of turns (the project map).
 // callsBeforeTarget: how far a turn walked before touching a file it went on to edit.
 // failedCalls: tool calls that ended in error (the field notes, whose largest section is a failure taxonomy).
+// openingPrompt: tokens a turn's first request sent (cache reads plus cache writes), which is what every later call of
+// the turn reads again (tool search, which moves the tool schemas out of it).
+// openingWrite: tokens a follow-up turn's first request wrote to the cache instead of reading them (the stable prompt).
 // Every reading is the main agent's own: a subagent's calls are counted toward the turn and read for nothing.
-// Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest.
+// Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest. The prompt's size is
+// the exception that proves it: it is the part every call pays again, so it is read directly rather than through cost.
 export const TurnMetricReadingSchema = z.object({
-    metric: z.enum(["searchCalls", "openingSearches", "openedWithListing", "callsBeforeTarget", "failedCalls"]),
+    metric: z.enum(["searchCalls", "openingSearches", "openedWithListing", "callsBeforeTarget", "failedCalls", "openingPrompt", "openingWrite"]),
     on: SavingsArmSchema,
     off: SavingsArmSchema,
     // Additional control turns to reach a fixed target resolution, not today's delta (which inherits noise and always
@@ -810,6 +778,9 @@ export const SavingsReportSchema = z.object({
     // Same absence rule as `search`: not measured, never zero.
     map: TurnExperimentSchema.optional(),
     notes: TurnExperimentSchema.optional(),
+    toolSearch: TurnExperimentSchema.optional(),
+    stablePrompt: TurnExperimentSchema.optional(),
+    coldTrim: TurnExperimentSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 

package/src/schemas/workspace/workspace-tree.ts

@@ -160,6 +160,26 @@ export const WorkspaceDownloadTicketSchema = z.object({
     expiresAt: z.number().describe("When it stops working, in milliseconds. It is meant to be used at once."),
     filename: z.string().describe("What the archive is saved as, so a caller can say what is on its way."),
 });
+// Credential for GET /workspace/preview/{ticket}/*, which a frame loads a web page from so it runs as it would on a
+// static file server: its scripts, modules, fetches and links resolve against real addresses. The ticket is the path's
+// first segment, so every relative address the page names carries it on.
+export const WorkspacePreviewTicketQuerySchema = WorkspaceScopeSchema.extend({
+    path: z.string().min(1).describe("The web page to preview, as a workspace path."),
+    source: z
+        .string()
+        .max(8 * 1024 * 1024)
+        .optional()
+        .describe("The page's text as the editor holds it, when it has edits not yet saved; served in place of the file on disk."),
+});
+export const WorkspacePreviewTicketSchema = z.object({
+    page: z.string().describe("The page's address on this daemon, a path to put after its base URL; the ticket is inside it."),
+    root: z
+        .string()
+        .describe(
+            "The folder the ticket serves, as a workspace path (empty for the workspace's root): the page's own repository. An address under the ticket names the file at the same place under this folder.",
+        ),
+    expiresAt: z.number().describe("When it stops working, in milliseconds."),
+});
 // A read of a window: offset negative reads that many bytes from the end (for following a growing log); limit is
 // clamped to the daemon's own cap. Coerced from query strings.
 export const WorkspaceFileReadQuerySchema = WorkspaceScopeSchema.extend({