@intentic/sandbox-contract 1.160.0 → 1.161.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/sandbox-contract",
-  "version": "1.160.0",
+  "version": "1.161.0",
   "description": "oRPC wire contract for the intentic sandbox daemon — shared by the daemon and its browser client",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,7 @@
     "@orpc/contract": "1.14.3",
     "tslib": "2.8.1",
     "zod": "4.4.3",
-    "@intentic/extension-api": "1.160.0"
+    "@intentic/extension-api": "1.161.0"
   },
   "devDependencies": {
     "@types/node": "24.13.2",

package/src/contracts/settings.contract.ts

@@ -1,15 +1,23 @@
 import { oc } from "@orpc/contract";
-import { BuiltinPromptSchema, BuiltinPromptTextSchema, CleanerSavingsSchema, OkSchema, SandboxSettingsSchema } from "../schemas.js";
+import {
+    BuiltinPromptSchema,
+    BuiltinPromptTextSchema,
+    DayWindowQuerySchema,
+    OkSchema,
+    SandboxSettingsSchema,
+    SavingsReportSchema,
+} from "../schemas.js";
 
 // Per-sandbox agent settings (.intentic/settings.json). `get` returns the current flags with defaults applied
-// when the file is absent; `set` overwrites them. `savings` reports the output-cleaner token savings aggregated
-// from the live filter-stats ledger (the rtk-`gain` surface — read-only, so a UI card can show what's working).
+// when the file is absent; `set` overwrites them. `savings` reports what each token-reduction mechanism was
+// worth — the cleaners' realized per-command savings and the terse steer's measured A/B — over an inclusive
+// UTC day window, the same one the spend ledger takes, so a screen can filter both with one calendar.
 // `builtinPrompt` returns one of the two built-in system prompts as text — Intentic's own, or Claude Code's
 // read out of the installed CLI — so the settings page can SHOW the prompt behind a mode instead of asking the
 // user to trust a description of it, and can fork either into a custom one.
 export const settingsContract = {
     get: oc.route({ method: "GET", path: "/settings" }).output(SandboxSettingsSchema),
     set: oc.route({ method: "POST", path: "/settings" }).input(SandboxSettingsSchema).output(OkSchema),
-    savings: oc.route({ method: "GET", path: "/settings/savings" }).output(CleanerSavingsSchema),
+    savings: oc.route({ method: "GET", path: "/settings/savings" }).input(DayWindowQuerySchema).output(SavingsReportSchema),
     builtinPrompt: oc.route({ method: "GET", path: "/settings/system-prompt/{base}" }).input(BuiltinPromptSchema).output(BuiltinPromptTextSchema),
 };

package/src/contracts/usage.contract.ts

@@ -1,10 +1,10 @@
 import { oc } from "@orpc/contract";
-import { UsageRollupQuerySchema, UsageRollupSchema } from "../schemas.js";
+import { DayWindowQuerySchema, UsageRollupSchema } from "../schemas.js";
 
 // The durable spend ledger (see UsageTurnSchema). Read-only over the wire — rows are appended daemon-side at
 // turn end, so the ledger stays a trustworthy record of what was actually spent, the same principle as the
 // activity log. `rollup` serves every cost/usage panel: it groups by day × provider × account × model, and the
 // browser re-projects from there (spend per day, cost by model, cache hit rate) without another round trip.
 export const usageContract = {
-    rollup: oc.route({ method: "GET", path: "/usage/rollup" }).input(UsageRollupQuerySchema).output(UsageRollupSchema),
+    rollup: oc.route({ method: "GET", path: "/usage/rollup" }).input(DayWindowQuerySchema).output(UsageRollupSchema),
 };

package/src/events.ts

@@ -239,6 +239,27 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // The live gate: the provider's answer to "may this turn run", pushed mid-turn. Drives the rate-limited
     // notice, not the headroom readouts — see RateLimitInfoSchema.
     RateLimitInfoSchema.extend({ kind: z.literal("rate_limit_info"), account: z.string().optional() }),
+    /* The turn is alive but WAITING on the provider: a request failed transiently (5xx, 529, a dropped socket)
+     * and the harness is retrying it inside this same turn. A status, not a failure — nothing has been lost and
+     * the turn may still finish normally, so the client renders it where "thinking" goes rather than in the
+     * transcript.
+     *
+     * It exists because the retry budget is deliberately long (see CLAUDE_CODE_RETRY_WATCHDOG in
+     * harness-credentials.ts): a turn can now sit silent for minutes riding out an outage, and silence reads as
+     * a hang. The one action a user takes against an apparent hang is Stop, which is the only action that
+     * actually loses the work — so the wait has to be visible, with its own next-attempt clock.
+     *
+     * `attempt`/`maxAttempts` are the harness's own counters; `nextAttemptAt` (epoch ms) is when it will try
+     * again, so the readout counts down instead of freezing on a number nobody can interpret. */
+    z.object({
+        kind: z.literal("provider_retry"),
+        attempt: z.number(),
+        maxAttempts: z.number(),
+        nextAttemptAt: z.number(),
+        // The HTTP status behind it when there was one (529 reads as capacity, 500 as a fault — the client says
+        // which). Absent for a transport failure that never got a response.
+        status: z.number().optional(),
+    }),
     // Every plan-limit pool for the account that served the turn, read from the CLI's usage endpoint once the
     // turn settles. `account` tags which Claude account it belongs to, so the client keys headroom by account;
     // absent on an env-token turn, which has no account to attribute it to. No `measuredAt` on the wire: both
@@ -291,6 +312,12 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 // that resumed itself, not a request for the user to do anything. It only reaches the client
                 // when the resume could NOT start, which is when reconnecting really is the fix.
                 "claude-token-refused",
+                // The model provider itself failed transiently — 500/502/503, a 529 at capacity, a dropped
+                // socket — and the harness's own in-turn retries did not outlast it. Nothing about the workspace
+                // or the request is wrong, so the daemon remembers the turn and re-runs it on an escalating
+                // backoff (provider-health.ts): the frame is a notice about a turn that is coming back, and
+                // reaches the client as a plain failure only once the attempts are spent.
+                "provider-outage",
                 // The harness read the message as a slash command it doesn't have, and discarded everything
                 // after the name — the model never saw the message. Nothing was processed, so the client holds
                 // the text back instead of leaving the user to retype it (same treatment as claude-reauth).
@@ -302,13 +329,24 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
             ])
             .optional(),
         // rate_limit only: when the exhausted window reopens (epoch seconds, from the stream's own
-        // rate_limit_event or the account's persisted usage windows), and what the daemon did about it —
-        // "scheduled" = auto-resume is on and this turn re-runs itself a minute after `resetsAt`;
-        // "available" = the daemon remembered the failed turn and enabling the autoResumeOnLimit setting
-        // arms that same resume, which is what the chat's offer banner hangs off. Absent together when the
-        // reset instant is unknown (nothing to schedule against).
+        // rate_limit_event or the account's persisted usage windows). Absent when the reset instant is unknown
+        // (nothing to schedule against).
         resetsAt: z.number().optional(),
+        // Where the daemon's resume of THIS turn stands — the same two states for a spent allowance and for a
+        // provider outage, because the client's reading of them is the same: "scheduled" = the resume is armed
+        // and this turn comes back by itself; "available" = the daemon remembered the failed turn and turning
+        // the setting on (autoResumeOnLimit / resumeAfterOutage) arms that same resume, which is what the
+        // chat's offer banner hangs off. Absent ⇒ there is nothing to resume.
         autoResume: z.enum(["scheduled", "available"]).optional(),
+        /* provider-outage only: the shape of the wait. `retryAt` (epoch seconds) is when the next attempt is
+         * due — not a fixed cadence, because an outage has no reset instant to aim at and hammering a provider
+         * that is down only spends tokens on refusals, so each attempt waits longer than the last
+         * (provider-health.ts owns the schedule).
+         *
+         * `attempt`/`maxAttempts` are on the wire so the notice can say the automation is BOUNDED. An
+         * on-by-default retry that gives no account of how long it will keep going is the kind users switch off
+         * defensively; one that says "attempt 2 of 6" is one they leave on. */
+        outage: z.object({ retryAt: z.number(), attempt: z.number(), maxAttempts: z.number() }).optional(),
         // rate_limit only: the account whose allowance is spent, as the DAEMON resolved it (the client's own
         // selection can be empty, which means "the provider's first"). It is what lets the chat offer the
         // provider's OTHER accounts as a resume-now instead of a wait — see /agent/resume-limit.

package/src/schemas.test.ts

@@ -20,6 +20,7 @@ test("a payload from a build that predates a toggle parses, with the new toggle
     };
     expect(SandboxSettingsSchema.parse(older)).toEqual({
         ...older,
+        terseHoldout: 0,
         filterBackend: "native",
         systemPromptMode: "intentic",
         systemPrompt: "",
@@ -27,6 +28,7 @@ test("a payload from a build that predates a toggle parses, with the new toggle
         agentRetentionDays: 3,
         autoLand: true,
         autoResumeOnLimit: false,
+        resumeAfterOutage: true,
     });
 });
 
@@ -36,6 +38,8 @@ test("an empty object is the full default settings object", () => {
         skills: [],
         hashlineEdits: false,
         terseOutput: false,
+        // Off: the steer's turn-level control spends the tokens it measures, so measuring is opt-in.
+        terseHoldout: 0,
         iqSearch: false,
         outputCleaners: "off",
         outputHoldout: 0,
@@ -54,6 +58,9 @@ test("an empty object is the full default settings object", () => {
         // sandbox's finished work on branches nobody is watching.
         autoLand: true,
         autoResumeOnLimit: false,
+        // On, unlike the limit resume beside it: an outage resume spends nothing the dead turn hadn't already
+        // committed, and the turns it saves are the unattended ones nobody is watching to restart by hand.
+        resumeAfterOutage: true,
     });
 });
 

package/src/schemas.ts

@@ -648,6 +648,14 @@ export const SandboxSettingsSchema = z.object({
     skills: z.array(z.string()).default([]),
     hashlineEdits: z.boolean().default(false),
     terseOutput: z.boolean().default(false),
+    /* Measurement control for the terse steer, at TURN level — the same trick `outputHoldout` plays over
+     * commands, one layer up. A fraction [0,1] of otherwise-eligible turns run WITHOUT the steer and record
+     * which arm they ran on (UsageTurn.terse), so the savings report can compare two real populations.
+     *
+     * It has to be an experiment: unlike a cleaned command, which yields its own raw baseline in the same
+     * event, a turn cannot be re-run to see what it would have said unsteered. 0 ⇒ no measurement (every
+     * eligible turn is steered), which is the default because the control costs the very tokens it measures. */
+    terseHoldout: z.number().min(0).max(1).default(0),
     /* WHICH SYSTEM PROMPT THE AGENT RUNS ON — the base, before anything this turn composes.
      *
      *   intentic — Intentic's own prompt, tuned for this harness (intentic-prompt.ts). The default.
@@ -697,6 +705,16 @@ export const SandboxSettingsSchema = z.object({
     // records every limit-hit either way and the chat OFFERS the toggle at the moment it would have helped —
     // enabling it then still resumes the turn that just bounced.
     autoResumeOnLimit: z.boolean().default(false),
+    /* When a turn dies because the MODEL PROVIDER was failing (500/502/503, a 529 at capacity, a dropped
+     * socket), re-run it on an escalating backoff until it goes through or the attempts are spent.
+     *
+     * Defaults ON, unlike autoResumeOnLimit, and the difference is not an inconsistency: a spent allowance is
+     * the user's own budget, and resuming into a fresh window spends something they may have been saving. An
+     * outage resume spends nothing the dead turn had not already committed, resolves in minutes rather than
+     * hours, and — the deciding argument — the turns hurt worst by it are the ones with nobody in the room
+     * (automation wakes, Discord, webhooks), which no browser-held preference could ever rescue. It is the same
+     * reasoning that leaves the auth resume ungated: this is the provider's failure, not the user's decision. */
+    resumeAfterOutage: z.boolean().default(true),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
 
@@ -710,22 +728,43 @@ export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
 export const BuiltinPromptTextSchema = z.object({ text: z.string(), version: z.string() });
 export type BuiltinPromptText = z.infer<typeof BuiltinPromptTextSchema>;
 
-// ---- output-cleaner savings report (rtk-`gain`-style) ----
-// Whichever cleaner is ACTUALLY compressing output owns the numbers, so the report is read from that backend's
+/* ---- savings report: what each token-reduction mechanism actually saved ----
+ *
+ * TWO FAMILIES, deliberately never one list of bars. They are measured differently, and a chart that ranks
+ * them side by side claims a confidence and a denominator that only one of them has:
+ *
+ *   input  — shell output the cleaners trimmed before the model ever saw it. Both sides of the comparison come
+ *            off the SAME command (raw in, emitted out), so the counterfactual is observed rather than
+ *            estimated: exact, per command, no sample size to argue about.
+ *   output — the model's own tokens under the terse steer. There is no second run of the same turn to compare
+ *            against, so the only honest number is an experiment: a turn-level holdout, an n per arm, and a
+ *            margin. It is absent entirely until both arms are large enough for the delta to mean anything.
+ *
+ * The two are also in different units of value — a saved tool-output token is saved again on every later
+ * request of that conversation, an output token is saved once but costs several times as much — which is the
+ * other reason they are separate sections with separate totals rather than one number.
+ */
+
+// One mechanism's realized saving, biggest first. `savedTokens` is what THIS stage removed from what reached
+// it in pipeline order — sequential attribution, which is why the stages sum exactly to raw − emitted and can
+// be drawn as one stacked bar. It is NOT "what turning this cleaner off would cost you": the cap downstream
+// would have eaten some of the same lines. `commands` is how many commands the stage ran on. Negative for the
+// `footer` stage, which adds the retrieval pointer back — a cost on the same ledger as what it bought.
+export const SavingsStageSchema = z.object({ id: z.string(), commands: z.number(), savedTokens: z.number() });
+
+// Whichever cleaner is ACTUALLY compressing output owns these numbers, so they are read from that backend's
 // own ledger: "native" aggregates historyRoot/logs/filter-stats.jsonl (one row per agent Bash command, written
 // by agent-output-filter), "rtk" reads rtk's own gain ledger. Reading one ledger regardless of backend is how
 // this card went stale: under rtk the native filter is switched off, nothing appends, and the last numbers
 // written — a test run's, as it happened — sat on the card looking live.
-//
-// `perCleaner` attributes which cleaner ids fired across commands; `holdout` is the measured control (commands
-// the holdout bypassed) vs the cleaned population — a real saved-% rather than an estimate; `gaps` are
-// high-volume commands that matched no cleaner (the next handler to write). All three are native-only: rtk
-// reports totals, not per-command attribution, so they arrive empty under that backend. Empty/zeroed when no
-// commands have run yet.
-export const CleanerSavingsSchema = z.object({
+export const InputSavingsSchema = z.object({
     // Which backend's ledger these numbers came from — shown on the card, because a number without its source
     // cannot be told apart from a stale one. Defaulted for the same daemon-older-than-browser seam as settings.
     source: z.enum(["native", "rtk"]).default("native"),
+    // False ⇒ these totals cover the ledger's whole life, not the range the reader selected: `rtk gain` reports
+    // no timestamps, so its numbers cannot be windowed and the screen has to say so rather than let a 7-day
+    // filter sit above an all-time figure.
+    windowed: z.boolean(),
     // When that ledger last recorded a command (epoch ms), so the card can show its age instead of implying
     // freshness it doesn't have. Absent when the ledger has never been written or its age can't be read.
     updatedAt: z.number().optional(),
@@ -733,11 +772,43 @@ export const CleanerSavingsSchema = z.object({
     rawTokens: z.number(),
     emittedTokens: z.number(),
     savedPct: z.number(),
-    perCleaner: z.array(z.object({ id: z.string(), commands: z.number() })),
+    // Per-stage attribution, biggest first. Native-only: rtk reports totals, not which of its handlers fired.
+    perCleaner: z.array(SavingsStageSchema),
+    // The measured control — commands the holdout left raw — against the cleaned population. A real saved-%
+    // for the pipeline as a whole rather than an estimate, and the only whole-pipeline counterfactual there is.
     holdout: z.object({ cleaned: z.number(), heldOut: z.number(), measuredSavedPct: z.number().optional() }),
+    // High-volume commands that matched no cleaner: where the next handler is worth writing. Native-only.
     gaps: z.array(z.object({ command: z.string(), tokens: z.number() })),
 });
-export type CleanerSavings = z.infer<typeof CleanerSavingsSchema>;
+export type InputSavings = z.infer<typeof InputSavingsSchema>;
+
+// One arm of the turn-level experiment: the turns that ran with the steer, and the turns the holdout ran
+// without it. Mean output tokens PER TURN, because the arms never hold the same number of turns.
+export const SavingsArmSchema = z.object({ turns: z.number(), meanOutputTokens: z.number() });
+
+// The terse steer, as measured. Only turns where the steer was ELIGIBLE are counted — a turn under a custom
+// system prompt drops the steer along with everything else the daemon appends, so it belongs to neither arm.
+export const OutputSavingsSchema = z.object({
+    on: SavingsArmSchema,
+    off: SavingsArmSchema,
+    // Turns per arm before a delta is reported at all. Carried on the wire so the screen's "measuring…" state
+    // counts toward the daemon's real threshold instead of a number the browser guessed.
+    minTurns: z.number(),
+    /* The three below are present TOGETHER, and only once both arms clear `minTurns` — a schema that can't
+     * express a half-measured experiment is how a 34%-that-becomes-8%-tomorrow never reaches the screen.
+     *   deltaPct   — change in mean output tokens per turn under the steer; negative is a saving.
+     *   marginPct  — ± percentage points, 95% (Welch, unequal variances and unequal arms).
+     *   savedTokens — what the delta is worth over the turns that actually ran with the steer, in this window. */
+    deltaPct: z.number().optional(),
+    marginPct: z.number().optional(),
+    savedTokens: z.number().optional(),
+});
+export type OutputSavings = z.infer<typeof OutputSavingsSchema>;
+
+// `output` is absent when the experiment isn't running at all (terse off, or no holdout set) — a section that
+// isn't there reads as "not measured", which is the truth, while zeros would read as "measured, worth nothing".
+export const SavingsReportSchema = z.object({ input: InputSavingsSchema, output: OutputSavingsSchema.optional() });
+export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 
 // ---- intentic CLI ----
 
@@ -2260,6 +2331,14 @@ export const UsageTurnSchema = z.object({
     cacheCreationTokens: z.number(),
     costUsd: z.number(),
     durationMs: z.number(),
+    /* Which arm of the terse experiment this turn ran on (settings.terseHoldout) — the only record of it, and
+     * the reason the savings report can say what the steer is worth instead of guessing.
+     *
+     * ABSENT means "not part of the experiment", not "off": a turn under a custom system prompt drops the
+     * steer along with everything else the daemon appends, and a turn run with the experiment switched off has
+     * no control to be compared against. Pooling those into the off-arm would compare steered turns against a
+     * population selected by something other than the coin flip, which is not a control at all. */
+    terse: z.boolean().optional(),
 });
 export type UsageTurn = z.infer<typeof UsageTurnSchema>;
 
@@ -2287,12 +2366,14 @@ export const UsageRollupRowSchema = z.object({
     durationMs: z.number(),
 });
 export type UsageRollupRow = z.infer<typeof UsageRollupRowSchema>;
-// Inclusive UTC day bounds (YYYY-MM-DD). Both absent ⇒ the whole ledger.
-export const UsageRollupQuerySchema = z.object({
+// Inclusive UTC day bounds (YYYY-MM-DD). Both absent ⇒ the whole ledger. Shared by every windowed read of a
+// daemon ledger (spend, savings): one window shape, so a screen that filters two ledgers at once filters them
+// with the same calendar.
+export const DayWindowQuerySchema = z.object({
     from: z.string().optional(),
     to: z.string().optional(),
 });
-export type UsageRollupQuery = z.infer<typeof UsageRollupQuerySchema>;
+export type DayWindowQuery = z.infer<typeof DayWindowQuerySchema>;
 export const UsageRollupSchema = z.object({ rows: z.array(UsageRollupRowSchema) });
 
 // ---- usage: per-account token/cost totals ----