@intentic/sandbox-contract 1.226.1 → 1.227.0

package/src/schemas.ts

@@ -378,6 +378,18 @@ export const AgentTurnSchema = z
             .describe(
                 "Ask for the same work at a higher rate for a higher price. A request rather than a promise: the answer says what actually happened.",
             ),
+        /* KEEP THIS TURN ON THE MODEL I PICKED: the user's veto over automatic tier selection, riding the turn
+         * like `fast` does because it changes what the turn costs and so belongs to the turn rather than to the
+         * workspace. The judge still runs and the verdict is still recorded — a deny is the strongest label the
+         * calibration ledger ever gets (UsageTurn.tierDenied) — but nothing is substituted. The composer sends
+         * its conversation-level toggle here every turn, and the registry persists it beside `fast`, so the
+         * choice survives reopening the tab. Absent ⇒ no opinion, routing follows settings.autoTier. */
+        tierHold: z
+            .boolean()
+            .optional()
+            .describe(
+                "Run exactly the model that was picked, even when the turn looks simple enough for a cheaper one. The judgement is still recorded; nothing is substituted.",
+            ),
         // The opt-in editor context chip: what the user is looking at, folded into the prompt daemon-side.
         editorContext: EditorContextSchema.optional().describe(
             'What the user has open in their editor, folded into the prompt so that pointing words like "this" resolve.',
@@ -1080,6 +1092,21 @@ export const AgentSummarySchema = z.object({
     effort: z.string().optional().describe("How hard that turn was told to think."),
     thinking: z.boolean().optional().describe("Whether that turn showed its reasoning."),
     fast: z.boolean().optional().describe("Whether that turn asked for higher speed. What was asked for, not what was served."),
+    /* WHAT THE COMPLEXITY JUDGE MADE OF THE LAST TURN HERE, mirrored from the persisted entry (agents-store.ts
+     * `tier`) so a client opening the conversation tomorrow can seed its composer preview with the one judge
+     * input a draft cannot contain (prompt-complexity.ts `afterHardTurn`). The JUDGEMENT, never what ran, for
+     * the reason the store states: what ran is a fact about configuration, the next turn is asking about the
+     * difficulty of the work. Absent ⇒ nothing judged yet. */
+    tier: z
+        .enum(["fast", "standard"])
+        .optional()
+        .describe("How hard its last turn looked to the complexity judge. What the next turn's preview needs, not what actually ran."),
+    // The conversation's standing "keep every turn on my pick" choice, the composer's memory of it, the same
+    // shape as `fast` above: what was asked for, restored into the composer on open, sent back on every turn.
+    tierHold: z
+        .boolean()
+        .optional()
+        .describe("Whether this conversation is pinned to the picked model, so a turn that looks simple is never moved to a cheaper one."),
     account: z.string().optional().describe("Which connected account paid for it."),
     // The worktree branch (agent/<id>); absent for a non-isolated (main-tree) conversation.
     branch: z.string().optional().describe("The branch its private copy works on. Absent for a conversation that works directly in the shared tree."),
@@ -2018,6 +2045,15 @@ export const ModelSchema = z.object({
             "What it is good for, in the provider's own words. Absent where the provider publishes only ids, which is the honest answer rather than something to paper over with a hand-written table.",
         ),
     badges: z.array(ModelBadgeSchema).optional().describe("What it is known for, where the provider says so."),
+    /* HOW MUCH THE SERVER WILL ACCEPT IN ONE REQUEST, where the server says so, and the one field here that a
+     * turn is refused against rather than merely rendered (agent/context-budget.ts).
+     *
+     * The SERVED window, never the weights' training length. An inference server takes its context size from a
+     * flag and then clamps it to the memory it actually has, so a 3B model whose GGUF advertises 131k can be
+     * serving 16k, and it is the 16k that refuses the request. Read from llama.cpp's /props and vLLM's
+     * `max_model_len`; absent for every provider that publishes no such number, which is most of them, and
+     * absent means unknown rather than unlimited: nothing gates on a window it was never told. */
+    contextWindow: z.number().optional().describe("How many tokens this model will accept in one request, where the server publishes it."),
 });
 export type Model = z.infer<typeof ModelSchema>;
 export const ModelsSchema = z.object({
@@ -2521,6 +2557,23 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Whether an easy-looking turn may run on a cheaper model from the same provider. Three states rather than a switch, because the middle one is the only honest road to the third: it scores every turn and routes nothing, so the guess can become a measurement before it changes anything. It can only ever route down, so the worst case is one turn's quality rather than a bill nobody asked for.",
         ),
+    /* HOW EAGER THE JUDGE IS, the one dial this feature exposes and the answer to what the Measure mode is for:
+     * the numbers say how many turns were called simple, and this is the control that acts on them.
+     *
+     * Three named stops rather than a number, because the number means nothing to anyone who has not read the
+     * weights, while "only the unmistakable" / "the default" / "an easy question about real code too" are three
+     * sentences an owner can actually hold an opinion about (FAST_CEILINGS spells out each). It moves the
+     * cutoff and nothing else: the rule that a downgrade needs something POSITIVE to have been said holds at
+     * every stop, so no setting of this can start downgrading short vague requests.
+     *
+     * `balanced` is the default and is what every verdict recorded before this existed was judged against, so
+     * the shadow history stays comparable across the change rather than silently becoming two populations. */
+    autoTierEagerness: z
+        .enum(["cautious", "balanced", "eager"])
+        .default("balanced")
+        .describe(
+            "How readily a turn counts as simple enough for the cheaper model. It moves only the cutoff: at every setting a turn still has to say something positively easy, so nothing here can downgrade a short vague request.",
+        ),
     /* WHICH CHEAP MODEL A DOWNGRADED TURN LANDS ON, an ordered list of `${provider}:${model}` keys
      * (quickModelKey), or EMPTY for Auto.
      *
@@ -2843,10 +2896,45 @@ export type TurnExperiment = z.infer<typeof TurnExperimentSchema>;
 // `output`/`search` are absent when that experiment isn't running at all (its flag 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".
+/* WHAT THE COMPLEXITY JUDGE HAS BEEN SAYING, read back off the spend ledger's tier fields (UsageTurn.tierScore
+ * and friends) over the requested window. The three numbers docs/model-routing-design.md §4 says the feature
+ * cannot be defended without, plus the veto count, and nothing else: no counterfactual "you would have saved
+ * $X", because the ledger holds what turns COST, not what they would have cost on a model they never ran.
+ *
+ * NOT a TurnExperiment, deliberately. The experiments compare two randomized arms of one population; this is a
+ * tally of what one mechanism observed and did. Dressing it in arms and margins would claim a control group that
+ * does not exist (routing follows the settings mode, which follows time, not a coin flip).
+ *
+ * The whole section is absent when no turn in the window was judged at all (autoTier "off" throughout), which a
+ * screen renders as absence: "not measured" is the truth, zeros would read as "measured, found nothing". */
+export const TierReportSchema = z.object({
+    // Turns the judge ran on in the window, the denominator under everything below.
+    judged: z.number(),
+    // …of which landed at or below FAST_CEILING: the turns that looked simple. fast ÷ judged is the fast share.
+    fast: z.number(),
+    /* What the fast-judged turns that STAYED on the user's pick actually cost, the money measure mode is
+     * pointing at. An upper bound on any saving, never an estimate of one: moving those turns to the cheap rung
+     * would have cost something too, and this schema refuses to guess how much. */
+    atStakeUsd: z.number(),
+    // Turns that actually ran the cheap rung, and what they cost there. Realized, not projected.
+    routed: z.number(),
+    routedUsd: z.number(),
+    /* THE GUARDRAIL: fast-judged turns whose conversation's very next ledger row asked for a dearer model, the
+     * user reaching for the model picker right after a turn the judge called simple. The strongest negative
+     * signal the ledger can carry (§4's first calibration row). Past a few percent of `fast`, the judge is
+     * costing more in retries and trust than it saves in tokens. */
+    escalated: z.number(),
+    // Fast-judged turns the user vetoed outright (UsageTurn.tierDenied): the same signal, said even louder.
+    denied: z.number(),
+});
+export type TierReport = z.infer<typeof TierReportSchema>;
+
 export const SavingsReportSchema = z.object({
     input: InputSavingsSchema,
     output: TurnExperimentSchema.optional(),
     search: TurnExperimentSchema.optional(),
+    // Automatic tier selection's readout, see TierReportSchema. Absent ⇒ nothing was judged in the window.
+    tier: TierReportSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 
@@ -8839,7 +8927,47 @@ export const UsageTurnSchema = z.object({
         .describe(
             "The model that actually ran, past whatever was asked for and every default. Absent only when the provider's own default served it without being named.",
         ),
+    /* WHAT THE CLIENT ASKED FOR, beside `model` above, which is what ran. The pair is the point: a routing
+     * surprise is then a diff on one row rather than an investigation through the routing code.
+     *
+     * The gap between the two is real and was unreadable. A pick is resolved past the tier judge's downgrade,
+     * a provider's own subscription default, a catalog validity check that silently substitutes (Grok rejects
+     * a retired models.dev id, so an invalid pin becomes the catalog default), and CLIProxyAPI's own choice on
+     * a routed turn. Every one of those is a legitimate substitution and none of them was recorded, so "I
+     * chose one model and got another's error" could only be answered by reading four resolution paths and
+     * guessing which had fired.
+     *
+     * Absent ⇒ the client named nothing and asked for the default, which is not the same as asking for what it
+     * got. Equal to `model` on the overwhelming majority of turns; the rows where they differ are the whole
+     * reason this is here. */
+    modelRequested: z
+        .string()
+        .optional()
+        .describe("The model that was asked for, when one was named. Differs from `model` when something resolved it."),
     harness: z.string().describe("Which agentic loop it ran on."),
+    /* HOW THE TURN ENDED. The field that turns the ledger from an accounting record into a diagnostic one.
+     *
+     * Without it a turn that died is byte-for-byte indistinguishable from one that succeeded, except that it
+     * cost less, so "four sessions all broke a minute ago" had no record to read and had to be answered by
+     * re-running the destructive act in a live sandbox. The failure was never nowhere: it was in the activity
+     * log, which prunes to its most recent entries, so an incident survives only until the feed rolls past it.
+     * This log is never pruned, which is the entire difference.
+     *
+     * "cancelled" is a user pressing Stop, which is not a failure and must never be read as one, the registry
+     * learned that lesson already (see the abort branch in streamAgent). "error" is a turn the provider or the
+     * request killed. Both still carry whatever they spent before they ended.
+     *
+     * Absent ⇒ the row predates this being recorded, NOT a turn that succeeded. Readers that count failures
+     * must treat absent as unknown, and the experiment readers do exactly that. */
+    outcome: z.enum(["ok", "error", "cancelled"]).optional().describe("How it ended: finished, failed, or was stopped by the user."),
+    // The failing frame's code, when it carried one, e.g. `rate_limit`, `provider-outage`, `claude-not-entitled`.
+    // Present only alongside outcome "error", and absent even then for a failure that named no code, which is
+    // itself the interesting case: an unclassified failure is one nothing downstream knows how to handle.
+    errorCode: z.string().optional().describe("The failure's code, when it had one."),
+    // The failing frame's own sentence, capped at ERROR_MESSAGE_CHARS. Capped rather than omitted because the
+    // provider's wording is routinely the only thing that distinguishes two failures sharing one code, and
+    // uncapped it would let one bad provider message dominate a file that must stay cheap to read whole.
+    errorMessage: z.string().optional().describe("What the failure said, trimmed."),
     // The conversation this turn belonged to, so spend can join to a fleet agent. Absent only for an internal
     // one-shot turn that has no conversation identity.
     conversationId: z
@@ -8942,6 +9070,24 @@ export const UsageTurnSchema = z.object({
     tierScore: z.number().optional(),
     tierRules: z.array(z.string()).optional(),
     tierRouted: z.boolean().optional(),
+    /* THE VERDICT ITSELF, and the cutoff it was reached against.
+     *
+     * `tierScore` stopped being able to answer "was this called simple" the moment the cutoff became the owner's
+     * to choose (settings.autoTierEagerness): 0.35 is standard on the middle stop and fast on the eager one, and
+     * a fast verdict also requires a positively-easy signal that no score can express. So the answer is written
+     * down rather than re-derived, and the ceiling goes with it because a refit reading a column of bare scores
+     * could not otherwise tell two rows apart.
+     *
+     * Absent on rows written before the knob existed, which were all judged at the `balanced` cutoff — which is
+     * exactly what a reader falls back to (FAST_CEILING), so old and new rows stay one population. */
+    tierFast: z.boolean().optional(),
+    tierCeiling: z.number().optional(),
+    /* THE USER SAID NO: the turn carried AgentTurn.tierHold, so a fast verdict moved nothing. Recorded rather
+     * than folded into `tierRouted: false` because it is the strongest calibration label this ledger ever gets,
+     * a person looking at this very conversation deciding the cheap rung was not to be trusted with it, and the
+     * refit (docs/model-routing-design.md §4) needs it kept apart from "nothing cheaper was published". Absent ⇒
+     * no veto, which is every row written before the control existed and most rows after. */
+    tierDenied: z.boolean().optional(),
 });
 export type UsageTurn = z.infer<typeof UsageTurnSchema>;
 
@@ -9043,6 +9189,54 @@ export const LogReadSchema = z.object({
 });
 export type LogRead = z.infer<typeof LogReadSchema>;
 
+/* ---- client diagnostics: what the BROWSER saw, landed where the daemon's own records live ----
+ *
+ * The one gap no daemon-side record could ever close. Everything the editor measured or caught ended at
+ * `console.warn`: the perf ring buffer dies on reload, a render error reaches Vue's handler and stops there, and
+ * the startup self-heal CLEARS this origin's storage and reloads, destroying the evidence for the one class of
+ * bug that reproduces least often. So when a user hit a bug in their own browser the durable record was
+ * nothing, and the only way to investigate was to re-drive a browser and hope. Measured over 728 sessions that
+ * is 1,545 screenshots against 65 console reads, and a quarter of all prompts arriving with a picture attached
+ * because there was no other channel.
+ *
+ * Deliberately NARROW. This is not analytics (PostHog owns product events) and not a log pipe: it carries the
+ * things a person cannot describe and a screenshot cannot show, which are caught errors, self-heal wipes, and
+ * spans that blew their frame budget. Everything is capped at the schema so one looping component cannot fill
+ * the /history volume, and the daemon appends to logs/client.jsonl under the same prune sweep as the rest. */
+export const ClientDiagnosticSchema = z.object({
+    // When the BROWSER saw it. Distinct from the `time` the daemon stamps on the record, because a batch can
+    // arrive seconds late and a reader correlating a stutter to a daemon span needs the moment it happened.
+    seenAt: z.number().describe("When the browser saw it, in milliseconds."),
+    level: z.enum(["warn", "error"]).describe("How bad it was."),
+    // A stable name, not free text: this is what a reader filters on. e.g. `vue.render`, `window.error`,
+    // `unhandled.rejection`, `self-heal.wipe`, `perf.slow`.
+    event: z.string().min(1).max(100).describe("What kind of thing it was, as a stable name."),
+    message: z.string().max(2_000).describe("What it said."),
+    // The app route the user was on, which is the single most useful field for reproducing anything.
+    route: z.string().max(300).optional().describe("Which page they were on."),
+    /* The id this browser put on the daemon call it was making, when there was one. The join key: without it
+     * "the UI stuttered at 15:22" and "slow http.request at 15:22" can only be matched by eye. */
+    requestId: z.string().max(100).optional().describe("Which daemon call it belonged to, when it belonged to one."),
+    // Which build this browser was running, so a report from a tab nobody has reloaded in a week says so.
+    build: z.string().max(100).optional().describe("Which build of the app was running."),
+    // Bounded and primitive: a stack, an op name, a duration. Kept flat so a line stays greppable.
+    fields: z
+        .record(z.string().max(60), z.union([z.string().max(4_000), z.number(), z.boolean()]))
+        .optional()
+        .describe("Whatever else was worth keeping."),
+});
+export type ClientDiagnostic = z.infer<typeof ClientDiagnosticSchema>;
+
+// A batch. Capped: the client coalesces and drops on its own side too, and a route that accepts an unbounded
+// array is a way to fill a disk with one request.
+export const ClientDiagnosticsReportSchema = z.object({
+    events: z.array(ClientDiagnosticSchema).min(1).max(50).describe("What the browser has to report, oldest first."),
+});
+export type ClientDiagnosticsReport = z.infer<typeof ClientDiagnosticsReportSchema>;
+export const ClientDiagnosticsAcceptedSchema = z.object({
+    recorded: z.number().describe("How many were written down."),
+});
+
 // A tab's self-report of what it is looking at, keyed by its /events connection's clientId. Full replace,
 // not a merge, an absent field means "cleared", so a tab leaving a file drops the path with the same report.
 export const PresenceReportSchema = z.object({

package/src/starter.ts

@@ -0,0 +1,13 @@
+/* THE STARTER SITE'S NAMES, declared where both sides of the wire read them.
+ *
+ * A fresh sandbox opens with one real, running thing in it: a one-page site, copied out of the image and
+ * started by the daemon's first boot (sandbox src/scaffold/starter-site.ts). The browser's job is the other
+ * half of that promise, to have it on screen when the user arrives (web shell/ShellDesktop.vue), and to do
+ * that it has to name the same repo and the same app the daemon seeded.
+ *
+ * Two constants rather than one because they are two different kinds of name: `site` is the repo directory a
+ * person would have picked, and `landing` is the template's own app name, which the apps extension, the
+ * preview hostname (preview-site--landing-<id>.<zone>) and the folder under `_apps/` all inherit. Renaming
+ * either is a product decision, not a rename: the seeded workspaces already out there keep the old names. */
+export const STARTER_REPO = "site";
+export const STARTER_APP = "landing";