@intentic/sandbox-contract 1.323.0 → 1.324.0

package/src/schemas/settings.ts

@@ -20,13 +20,15 @@ export const SYSTEM_PROMPT_MAX = 20_000;
 export const AUTO_MODEL_GUIDANCE_MAX = 2000;
 // Rules: "at this moment, if this is true, do this". The owner's rules decide (land, hold, version); every command a
 // moment runs is a repository's own check (`<repo>/.intentic/checks.json`), compiled into this same table by the daemon,
-// so no command lives in settings. Nothing verifies inside a turn, after a land or on the way to a push: CI checks what
-// the owner pushes, and nothing here holds anything (schemas/ci.ts).
+// so no command lives in settings. Nothing verifies after a land or on the way to a push, and nothing here holds
+// anything: what a check finds inside a turn is said back to the model, and CI checks what the owner pushes
+// (schemas/ci.ts).
 export const RuleMomentSchema = z.enum([
     // A command here runs on the just-written file (`{file}` is its path); the cheapest moment to catch a defect.
     "file.edited",
-    // Retired: the assistant stopping. Nothing runs here any more and nothing sends a turn back to work; the value stays
-    // so settings written before it went still read, and a rule standing here is inert.
+    // An isolated turn about to stop: a repository's own `turn` check runs here once, on what the turn changed, and what
+    // it finds is said back to the model, which may fix it or say why not. It holds and refuses nothing. Only what a
+    // repository declares stands here; an owner's rule left here from before is inert, and no save stands a new one.
     "turn.ending",
     // An agent's turn is over and its delta is sitting on its branch. A rule here decides whether it lands.
     "agent.finished",
@@ -55,8 +57,8 @@ export const RuleActionSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("builtin"), name: RuleBuiltinSchema }),
 ]);
 export type RuleAction = z.infer<typeof RuleActionSchema>;
-// `checks-failed` was a clean turn whose `turn.ending` check failed. Nothing produces it now that no check runs inside a
-// turn, and a check never holds work; it stays so older rules naming it still read.
+// `checks-failed` was a clean turn whose `turn.ending` check failed. Nothing produces it now: a `turn` check's findings
+// are said back to the model and never decide whether its work lands. It stays so older rules naming it still read.
 export const RuleOutcomeSchema = z.enum(["clean", "error", "conflict", "checks-failed"]);
 export type RuleOutcome = z.infer<typeof RuleOutcomeSchema>;
 // Every key absent means the rule always matches.
@@ -68,7 +70,8 @@ export const RuleConditionSchema = z.object({
     // How the turn ended. Absent/empty ⇒ any.
     outcome: z.array(RuleOutcomeSchema).optional(),
     // The fraction of occasions a rule fires on, at a moment that draws one; absent ⇒ every occasion. No moment draws
-    // now that `turn.ending` is retired, so a sampled rule fires every time.
+    // one any more (`turn.ending` did, before it held only the checks a repository declares), so a sampled rule fires
+    // every time.
     sample: z.number().gt(0).lt(1).optional(),
 });
 export type RuleCondition = z.infer<typeof RuleConditionSchema>;
@@ -103,7 +106,8 @@ export const RuleSchema = z
         path: ["action"],
     });
 export type Rule = z.infer<typeof RuleSchema>;
-// A rule at a retired moment or with a retired built-in: read, so an older file parses, but never written again.
+// A rule the owner's settings no longer take: one at `turn.ending`, where only a repository's own checks stand, or one
+// with the retired `verify-ui-edits` built-in. Read, so an older file parses, but never written again.
 export const isRetiredMomentRule = (rule: Pick<Rule, "moment" | "action">): boolean =>
     rule.moment === "turn.ending" || (rule.action.kind === "builtin" && rule.action.name === "verify-ui-edits");
 // Kept out of the settings object on purpose: a firing is not an edit, and writing config on every push would make
@@ -314,6 +318,23 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "What share of conversations to keep on the long form, so the two can be compared. Whole conversations rather than individual turns, because the guidance sits in the prompt for the whole session.",
         ),
+    // Measured by the `clearing` experiment: the gateway in front of a native Claude turn replaces old tool results with
+    // a placeholder, a chunk at a time, so the cached prompt breaks once per chunk rather than on every call
+    // (privacy/gateway/tool-result-clearing.ts). Off by default until that experiment says it pays.
+    toolResultClearing: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Replace old tool results from a Claude conversation once it grows long, a large chunk at a time, keeping the most recent ones whole. The agent sees a short placeholder where each one was and can run the tool again. Smaller prompts cost less and answer sooner, at the risk of the agent re-reading what it already saw.",
+        ),
+    toolResultClearingHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.5)
+        .describe(
+            "What share of conversations keep every tool result, so the two can be compared. Whole conversations rather than individual turns, because what was dropped stays dropped for the rest of the session.",
+        ),
     iqSearch: z
         .boolean()
         .default(false)
@@ -557,10 +578,11 @@ export const SandboxSettingsSchema = z.object({
         .describe("How many levels deep the delegation may go, since a subagent can start subagents of its own."),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
-// What a save takes: the settings as read, less what is only read. `turn.ending` (and its `verify-ui-edits` built-in) is
-// retired; a file written before still parses (and its conversion drops such rules), but no save may stand a new one.
+// What a save takes: the settings as read, less what is only read. `turn.ending` holds only the checks a repository
+// declares, which the daemon adds to a turn's rules and never saves, and the `verify-ui-edits` built-in is retired; a
+// file written before still parses (and its conversion drops such rules), but no save may stand a new one.
 export const SandboxSettingsWriteSchema = SandboxSettingsSchema.refine((settings) => !settings.rules.some(isRetiredMomentRule), {
-    message: "turn.ending is retired: nothing runs when a turn ends any more, so a rule cannot stand there",
+    message: "turn.ending runs only the checks a repository declares in its own .intentic/checks.json, so a rule cannot stand there",
     path: ["rules"],
 });
 
@@ -632,9 +654,13 @@ export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() }
 // openingListings: directory listings a turn ran to orient itself (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).
-// Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest.
+// roundTrips: model calls a turn took (the guidance form, whose batching and context-reuse paragraphs exist to save them).
+// contextPerCall: prompt tokens per model call, cached or not (tool-result clearing, which exists to shrink it).
+// Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest. Round trips are the
+// nearest a reading comes to it, and still a count of calls, not of tokens or money; the prompt a call carries is the
+// one exception, for the one mechanism that changes nothing else.
 export const TurnMetricReadingSchema = z.object({
-    metric: z.enum(["searchCalls", "openingSearches", "openingListings", "callsBeforeTarget", "failedCalls"]),
+    metric: z.enum(["searchCalls", "openingSearches", "openingListings", "callsBeforeTarget", "failedCalls", "roundTrips", "contextPerCall"]),
     on: SavingsArmSchema,
     off: SavingsArmSchema,
     // Additional control turns to reach a fixed target resolution, not today's delta (which inherits noise and always
@@ -698,6 +724,7 @@ export const SavingsReportSchema = z.object({
     map: TurnExperimentSchema.optional(),
     notes: TurnExperimentSchema.optional(),
     guidance: TurnExperimentSchema.optional(),
+    clearing: TurnExperimentSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 
@@ -712,17 +739,18 @@ export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 // spelling for the daemon that reads it, the screen that names it and the demo that mimics it.
 export const REPO_CHECKS_FILE = `${STATE_DIR}/checks.json`;
 
-// Named for the occasion as a repository would say it: `edit` is `file.edited` (rules/repo-checks.ts maps it). `turn`
-// and `land` are retired: nothing runs when a turn ends or after work lands any more (CI checks what the owner pushes),
-// and a declaration naming either still reads but runs nothing. No check refuses a land, a commit or a push.
-// `edit` runs on one file (`{file}`) and its output rides back in the edit's own response, so a command declared there is
-// paid per edit and has to take the file.
+// Named for the occasion as a repository would say it: `edit` is `file.edited` and `turn` is `turn.ending`
+// (rules/repo-checks.ts maps them). `edit` runs on one file (`{file}`) and its output rides back in the edit's own
+// response, so a command declared there is paid per edit and has to take the file. `turn` runs once when an isolated
+// turn is about to stop, on the whole tree, and what it prints when it fails is said back to the model once, which may
+// fix it or say why not. `land` is retired: nothing runs after work lands any more (CI checks what the owner pushes), and
+// a declaration naming it still reads but runs nothing. No check refuses a land, a commit or a push.
 export const RepoCheckMomentSchema = z.enum(["edit", "turn", "land"]);
 export type RepoCheckMoment = z.infer<typeof RepoCheckMomentSchema>;
 
 export const RepoCheckSchema = z.object({
     when: RepoCheckMomentSchema.describe(
-        "When to run it: `edit` on each file as it is written (`{file}` is its path). `turn` and `land` are retired and run nothing: checks no longer run while a conversation works or after its work lands, since CI checks what is pushed.",
+        "When to run it: `edit` on each file as it is written (`{file}` is its path); `turn` once when an isolated turn is about to stop, for at most three minutes, with what it prints on failure said back to the model once. Neither holds or refuses anything. `land` is retired and runs nothing, since CI checks what is pushed.",
     ),
     run: z.string().min(1).max(500).describe("The command, run in this repository's own directory, so it reads as it would in a terminal there."),
     label: z.string().min(1).max(80).optional().describe("What to call it on screen. Absent names it after the command."),

package/src/schemas/system.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { StatePlanSchema } from "./state-plan.js";
-import { UpdateOutcomeSchema, WithdrawnReleaseSchema } from "./updates.js";
+import { AutoUpdateSchema, UpdateOutcomeSchema, WithdrawnReleaseSchema } from "./updates.js";
 // version is this build's baked-in version; latest/updateAvailable come from comparing it to the published stable
 // release.
 // Whether a runtime can serve a turn, probed off the turn path. "unknown" reads as available-but-unverified, never as
@@ -122,6 +122,11 @@ export const InfoSchema = z.object({
         .string()
         .optional()
         .describe("A release the owner chose to skip. While it is the newest, no update is offered; a newer one is. Absent when nothing is skipped."),
+    // Taking a downloaded update by itself at a quiet moment (system/updates/auto-update.ts); absent where the daemon
+    // cannot (a hosted machine, a checkout-built base, a daemon outside a container) and from a daemon older than it.
+    autoUpdate: AutoUpdateSchema.optional().describe(
+        "Whether and when this sandbox takes a downloaded update by itself, and what it is waiting on. Absent where it cannot: a hosted sandbox, one built from a checkout, or one older than automatic updates.",
+    ),
 });
 export type Info = z.infer<typeof InfoSchema>;
 // What the daemon could not read in its own `.intentic/` state files, and in the files on its volume that

package/src/schemas/updates.ts

@@ -54,3 +54,74 @@ export const RollbackTargetSchema = z.object({
     version: z.string().optional().describe("What that image says it is. Absent when it would not say."),
 });
 export type RollbackTarget = z.infer<typeof RollbackTargetSchema>;
+
+// UPDATING BY ITSELF. Everything an update costs nobody is done unasked: the machine downloads and builds the next
+// release in the background (`ic sandbox prepare --auto`) and checks its state conversions against this sandbox's files.
+// What is left is a restart of about half a minute, and THAT is what this decides the moment of: the daemon holds a staged
+// update until nothing it can see would feel the restart (no agent mid-turn, nobody at the editor, terminals quiet,
+// nothing due), says so to anyone still connected, and then hands the machine the same `update` the button sends, asking
+// the next boot to pick up any turn the restart cut. Only a STAGED update is taken this way: one that still has to be
+// downloaded is minutes of downtime, which stays a person's decision. `system/updates/auto-update.ts` in the daemon.
+
+// One thing keeping an update waiting. `kind` is a string rather than an enum, as UpdateOutcome's `verb` is: a newer
+// daemon's reason must not make an older page drop the whole answer. The ones this build names:
+// - agents: an agent is mid-turn, or a subagent, a workflow or a land is still running (`names` says which).
+// - people: somebody has the editor on screen and is using it (`names` says who).
+// - terminal: a terminal printed something in the last few minutes, the trace of a person or a build still at work.
+// - schedule: an automation or a scheduled message is due within minutes, and the restart would land on it (`until`).
+// - paused: the owner asked for no automatic update until `until`.
+// - machine: the machine that runs this sandbox is not connected, so nothing here can ask it to restart anything.
+// - retry: the last try did not take; it is tried again at `until`.
+// - consent: the release changes something developers build on (its breaking notes), so it waits for a person to take
+//   it, however quiet the sandbox is. Never lifts by itself.
+export const AutoUpdateHoldSchema = z.object({
+    kind: z
+        .string()
+        .describe(
+            "What it waits on: agents (an agent is mid-turn, or a subagent, workflow or land is running), people (somebody is using the editor), terminal (a terminal was busy in the last few minutes), schedule (an automation or a scheduled message is due shortly), paused (the owner asked it to wait), machine (the machine that runs this sandbox is not connected), retry (the last try did not take), or consent (the release changes something developers build on, so a person takes it). A newer sandbox may name others.",
+        ),
+    names: z.array(z.string()).optional().describe("Who or what, by name: the agents still working, the people at the editor. Absent when there is nobody to name."),
+    until: z
+        .number()
+        .optional()
+        .describe("When this lifts by itself, in milliseconds, for a hold with a moment of its own: a pause, a retry, an automation's next run."),
+});
+export type AutoUpdateHold = z.infer<typeof AutoUpdateHoldSchema>;
+
+export const AutoUpdateSchema = z.object({
+    enabled: z.boolean().describe("Whether this sandbox takes downloaded updates by itself. On unless the owner turned it off."),
+    // A string for the same reason as a hold's kind.
+    phase: z
+        .string()
+        .describe(
+            "Where it stands: idle (nothing downloaded to take, or turned off), waiting (an update is downloaded and waits for the holds to clear), countdown (it restarts at startsAt unless somebody stops it), or updating (the machine is restarting this sandbox onto it now).",
+        ),
+    version: z.string().optional().describe("The downloaded version it will take. Absent while idle, or when the download did not say."),
+    holds: z.array(AutoUpdateHoldSchema).describe("Everything keeping it waiting right now, the one most likely to last first. Empty unless waiting."),
+    startsAt: z.number().optional().describe("During a countdown, when the restart begins, in milliseconds."),
+    pausedUntil: z.number().optional().describe("The owner's pause: no automatic update before this moment, in milliseconds. Absent when not paused."),
+    failure: z.string().optional().describe("Why the last automatic try did not take, in the machine's own words, while that is still the news."),
+    // The update this daemon itself started, read back by the version it moved onto: what lets the card say the
+    // restart happened by itself, while nobody was looking.
+    lastApplied: z
+        .object({ at: z.number(), to: z.string().optional() })
+        .optional()
+        .describe("The last update this sandbox took by itself: when it began and which version it moved onto."),
+});
+export type AutoUpdate = z.infer<typeof AutoUpdateSchema>;
+
+// The owner's say over it. Every field is optional and only what is named changes: the switch, a pause (null lifts it),
+// or "now", which skips the wait and the countdown for the update already downloaded.
+export const AutoUpdateInputSchema = z.object({
+    enabled: z.boolean().optional().describe("Turn taking downloaded updates by itself on or off."),
+    pausedUntil: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("Hold automatic updates until this moment, in milliseconds; null lifts a pause. A moment already past lifts it too."),
+    applyNow: z
+        .literal(true)
+        .optional()
+        .describe("Take the downloaded update now, without waiting for a quiet moment or counting down. Refused when nothing is downloaded."),
+});
+export type AutoUpdateInput = z.infer<typeof AutoUpdateInputSchema>;

package/src/state/history-state.ts

@@ -88,6 +88,9 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // last boot could not start (the daemon writes it, the host's probation reads it): all rebuilt by whoever next says.
     { path: "update-outcome.json", portability: "derived" },
     { path: "update-skipped.json", portability: "derived" },
+    // Whether this sandbox takes downloaded updates by itself, a pause, and the update it last started unasked
+    // (system/updates/update-policy.ts): about this machine's restarts, so a moved sandbox starts on the default.
+    { path: "update-policy.json", portability: "derived" },
     { path: "boot-failure.json", portability: "derived" },
     // A rebuild's ask that the next boot resume the turns it cuts (restart-resume.ts): about this machine's next boot only,
     // read once by it, so a moved sandbox starts without one.

package/src/state/runtime-state.ts

@@ -58,6 +58,10 @@ const RUNTIME_DOMAINS = [
 
     // The audit log grew or a gateway's status moved or aged out; the log lives outside /work, so no file push carries it.
     { domain: "activity", invalidates: [["activity"], ["activity-status"]] },
+
+    // An automatic update started waiting, changed what it waits on, began counting down or handed itself to the
+    // machine: what every page needs to hear before the sandbox goes quiet under it, wherever the reader is.
+    { domain: "update", invalidates: [["update"]] },
 ] as const satisfies readonly RuntimeDomainBinding[];
 
 export const RUNTIME_DOMAIN_BINDINGS: readonly RuntimeDomainBinding[] = RUNTIME_DOMAINS;

package/src/text/transcript-fold.test.ts

@@ -408,6 +408,21 @@ describe("foldTurn", () => {
         });
     });
 
+    // What a runtime's extension said is a notice row a reopened chat still shows; its status line is live state only.
+    it("folds an extension's notice into a notice row and keeps its status entries out of the rows", () => {
+        const rows = foldOf("go", [
+            { kind: "agent_status", key: "lint", text: "linting…", source: "lint-ext" },
+            { kind: "agent_notice", level: "warning", text: "Command blocked by user", source: "guard-ext" },
+            { kind: "agent_notice", level: "info", text: "Compacting soon" },
+            { kind: "agent_notice", level: "error", text: "   " },
+        ]);
+        expect(rows.slice(1)).toEqual([
+            { role: "notice", text: "Command blocked by user", agentNotice: { level: "warning", source: "guard-ext" } },
+            { role: "notice", text: "Compacting soon", agentNotice: { level: "info" } },
+        ]);
+        expect(rows.slice(1).map((row) => TranscriptRowSchema.parse(row))).toEqual(rows.slice(1));
+    });
+
     // An agent's own install, let through the command gate, says where it writes before its output arrives.
     it("says where an agent's own install writes, naming its projects", () => {
         expect(foldOf("go", [{ kind: "install", reach: "own-copy", projects: ["video"] }]).at(-1)).toEqual({

package/src/text/transcript-fold.ts

@@ -459,6 +459,15 @@ export class TranscriptFold {
                 return this.pushRow(compactedRow());
             case "install":
                 return this.pushRow(installRow(event));
+            case "agent_notice":
+                // A runtime's own extension or loop said it: a notice row, so a reopened conversation still says it.
+                return event.text.trim() === ""
+                    ? []
+                    : this.pushRow({
+                          role: "notice",
+                          text: event.text,
+                          agentNotice: { level: event.level, ...(event.source === undefined ? {} : { source: event.source }) },
+                      });
             case "error":
                 // Keeps a refusal (no prose from the provider) from reading as a session that ended mid-question.
                 // A refusal that ran nothing takes its message back out ahead of the notice standing in for it.
@@ -554,6 +563,7 @@ export class TranscriptFold {
             case "account_usage":
             case "context_usage":
             case "mode":
+            case "agent_status":
             case "done":
                 return [];
         }