@intentic/sandbox-contract 1.226.0 → 1.227.0

package/src/prompt-complexity.test.ts

@@ -158,3 +158,72 @@ test("the score never leaves 0..1, so a stored row is always comparable against
     expect(floor.score).toBeGreaterThanOrEqual(0);
     expect(ceiling.score).toBeLessThanOrEqual(1);
 });
+
+// --- the one dial, and the property it may not move ------------------------------------------------------
+
+/* The owner can move the cutoff (settings.autoTierEagerness) because "err toward my model or toward the cheap
+ * one" is a preference nobody else can hold for them. What these pin is that the dial moves the cutoff and
+ * NOTHING else, in particular not the rule that a downgrade needs something positively easy to have been said,
+ * which was the property the old ceiling held only by arithmetic coincidence. */
+
+test("the dial widens what counts as simple, in the direction it says", () => {
+    // A question about a real file: eased by its words, held back by naming a path. The middle stop keeps it on
+    // the user's pick, and the eager stop is precisely the choice to let it through.
+    const aboutAFile = `explain what src/app.ts does`;
+
+    expect(tierOf(aboutAFile, { eagerness: `balanced` })).toBe(`standard`);
+    expect(tierOf(aboutAFile, { eagerness: `eager` })).toBe(`fast`);
+});
+
+test("the cautious stop wants every easing signal at once, not merely an easy word", () => {
+    // Its whole content: leave no room for doubt. A statement in easy words still qualifies at the default,
+    // and does not here; only a short bare question naming no file survives every stop.
+    expect(tierOf(`explain closures`, { eagerness: `balanced` })).toBe(`fast`);
+    expect(tierOf(`explain closures`, { eagerness: `cautious` })).toBe(`standard`);
+    expect(tierOf(`what is a closure?`, { eagerness: `cautious` })).toBe(`fast`);
+});
+
+test("an absent dial is the balanced stop, so every row recorded before it existed still compares", () => {
+    const bare = judgeComplexity(turn(`what is this?`));
+
+    expect(bare.ceiling).toBe(FAST_CEILING);
+    expect(bare.tier).toBe(judgeComplexity(turn(`what is this?`, { eagerness: `balanced` })).tier);
+});
+
+test("no setting of the dial can downgrade a short vague request", () => {
+    // The whole safety argument for offering an eager stop at all. Absence of complexity is not evidence of
+    // simplicity at ANY cutoff, so this is a rule in the judge rather than a sum that happens to clear it.
+    for (const eagerness of [`cautious`, `balanced`, `eager`] as const) {
+        expect(tierOf(`fix the bug`, { eagerness })).toBe(`standard`);
+        expect(tierOf(`have a look at the thing we discussed`, { eagerness })).toBe(`standard`);
+    }
+});
+
+test("the deceptive follow-up is standard at every stop, because it never says anything easy", () => {
+    /* "now do the same for the other file" is the case the whole afterHardTurn signal was built for, and the
+     * easing rule turns out to answer it more strongly than any cutoff can: those words make no positive claim
+     * of ease, so no setting of the dial reaches them. The weight still does its own job one test down. */
+    for (const eagerness of [`cautious`, `balanced`, `eager`] as const) {
+        expect(tierOf(`now do the same for the other file`, { eagerness, afterHardTurn: true })).toBe(`standard`);
+    }
+});
+
+test("a turn following hard work has to clear a higher bar, and at the default an eased one no longer does", () => {
+    // It raises the bar rather than locking the door (see ComplexityInput.afterHardTurn), so this is a shift of
+    // one stop's worth, not a gate: the same words that route in a fresh conversation stay put in a hard one.
+    expect(tierOf(`explain closures`)).toBe(`fast`);
+    expect(tierOf(`explain closures`, { afterHardTurn: true })).toBe(`standard`);
+});
+
+test("the verdict carries the cutoff it was judged against, because a score alone stopped being an answer", () => {
+    // With the cutoff an owner setting, the same 0.35 is standard on one stop and fast on another. A ledger of
+    // bare scores could not tell those two rows apart; the ceiling beside each is what keeps a refit honest.
+    const cautious = judgeComplexity(turn(`explain closures`, { eagerness: `cautious` }));
+    const eager = judgeComplexity(turn(`explain closures`, { eagerness: `eager` }));
+
+    expect(cautious.ceiling).toBeLessThan(FAST_CEILING);
+    expect(eager.ceiling).toBeGreaterThan(FAST_CEILING);
+    // Same words, same score, opposite verdicts: the pair that a column of bare scores could not have told apart.
+    expect(cautious.score).toBe(eager.score);
+    expect([cautious.tier, eager.tier]).toEqual([`standard`, `fast`]);
+});

package/src/prompt-complexity.ts

@@ -89,6 +89,10 @@ export interface ComplexityInput {
      * or the feature switched off) says nothing about the difficulty of the work, and reading it as escalation
      * would make the sandbox's configuration leak into its opinion about a sentence. */
     readonly afterHardTurn: boolean;
+    /* HOW EAGER THE OWNER ASKED THIS TO BE (settings.autoTierEagerness), the one preference the judge takes.
+     * Absent ⇒ `balanced`, which is the stop every verdict recorded before the knob existed was judged
+     * against, so an absent value and an old row mean the same thing. See FAST_CEILINGS. */
+    readonly eagerness?: TierEagerness;
 }
 
 export interface ComplexityVerdict {
@@ -99,6 +103,10 @@ export interface ComplexityVerdict {
     // Every rule that fired, in declaration order. Empty is legal and means "nothing distinctive": the score is
     // the base, which sits above the fast ceiling, so an unremarkable turn stays on the user's own pick.
     readonly rules: readonly ComplexityRule[];
+    /* The cutoff this score was judged against, carried out so the caller can record it beside the score.
+     * A score is only half a verdict once the ceiling is a setting: 0.35 was standard yesterday and is fast
+     * today, and a refit reading a column of bare scores could not tell those rows apart. */
+    readonly ceiling: number;
 }
 
 /* WHERE AN UNREMARKABLE TURN STARTS, and it starts ABOVE the fast ceiling on purpose: a prompt that matches no
@@ -107,10 +115,35 @@ export interface ComplexityVerdict {
  * escalation, and a user who stops trusting the feature. */
 const BASE_SCORE = 0.5;
 
-// Fast iff the score lands at or below this. Exported because the shadow ledger's whole purpose is to let this
-// be re-fitted against real traffic rather than argued about, and a reader of a stored score needs the ceiling
-// that score was judged against.
-export const FAST_CEILING = 0.25;
+/* HOW EAGER THE JUDGE IS, the one knob this feature exposes, and deliberately the only one.
+ *
+ * The routing literature's own answer to "how do you tune a router in public" is a single aggressiveness
+ * threshold (RouteLLM ships it in the model name, `router-mf-0.3` against `router-mf-0.7`); everything else it
+ * learns stays inside. Same here: the weights below are a hypothesis with a ledger under them and are nobody's
+ * business, while "should this err toward my model or toward the cheap one" is a preference only the owner can
+ * hold, and the shadow numbers are useless without a way to act on what they say.
+ *
+ * THREE NAMED STOPS, not a slider, because the page has no slider idiom and, more to the point, a continuous
+ * control here invites fiddling with a number whose meaning nobody can feel. Each stop is a sentence about
+ * which turns move:
+ *   cautious — every easing signal at once and nothing pulling the other way: a short bare question, in easy
+ *              words, naming no file. "what is a closure?" and very little else. The zero is not a disabled
+ *              state, it is the floor the score clamps to, so it means exactly "leave no room for doubt".
+ *   balanced — the shipped default, and what every stored verdict before this knob existed was judged against.
+ *              Easy words carry a turn on their own; naming a file still holds it back.
+ *   eager    — an easy-worded question about real code goes too ("explain what this file does").
+ *
+ * NONE OF THEM CAN REACH THE ABSENCE FEATURES, at any setting, because that property is enforced structurally
+ * now rather than by the weights happening to sum above the ceiling (see `easing` below). That is what makes an
+ * eager stop safe to offer at all: raising a bare number would, at 0.3, have started downgrading every short
+ * vague request in the product, which is the single worst population to be wrong about. */
+export const FAST_CEILINGS = { cautious: 0, balanced: 0.25, eager: 0.4 } as const;
+export type TierEagerness = keyof typeof FAST_CEILINGS;
+
+// The stop a turn is judged against when nobody has chosen one, and the one every verdict recorded before the
+// knob existed was judged against. Exported because a reader of a stored score needs the ceiling behind it, and
+// a row written before ceilings were recorded was written against exactly this.
+export const FAST_CEILING = FAST_CEILINGS.balanced;
 
 // Characters, not tokens: nothing here can tokenize, and for a threshold the constant cancels. ~600 chars is
 // where a request stops being a sentence and starts being a brief; ~2400 is where it is carrying pasted
@@ -215,38 +248,56 @@ const forcing = (input: ComplexityInput, text: string): ComplexityRule[] => {
  * nothing, which is exactly why the mechanism ships in shadow first — see docs/model-routing-design.md §4. They
  * are not a claim, they are a hypothesis with a ledger under it.
  *
- * ONE PROPERTY IS NOT A HYPOTHESIS AND MUST SURVIVE ANY REFIT: the two ABSENCE features (`short-prompt`,
- * `no-workspace-reference`) are too light to reach the ceiling together. Absence of complexity is not evidence
- * of simplicity — "fix the bug" is four words naming no file and is not a cheap turn — so a downgrade always
- * requires something POSITIVE to have been said, which in practice means `easy-words` or `bare-question`
- * carrying it. Weighted the obvious way instead, the judge downgraded every short vague request in the
- * product, which is the single worst population to be wrong about. */
-const GRADED: readonly { readonly rule: ComplexityRule; readonly weight: number; readonly of: (input: ComplexityInput, text: string) => boolean }[] =
-    [
-        { rule: "medium-prompt", weight: +0.2, of: (_input, text) => text.length > MEDIUM_PROMPT_CHARS },
-        { rule: "attachment", weight: +0.15, of: (input) => input.attachments > 0 },
-        { rule: "editor-context", weight: +0.1, of: (input) => input.editorContext },
-        // Enough on its own to hold an easy-worded question at standard: "explain what this file does" is a
-        // question about real code in this repo, and the cheap rung's failures on real code are the silent kind.
-        { rule: "paths", weight: +0.15, of: (_input, text) => PATH_LIKE.test(text) },
-        {
-            rule: "many-verbs",
-            weight: +0.15,
-            of: (_input, text) => new Set((text.match(VERBS) ?? []).map((verb) => verb.toLowerCase())).size >= MANY_VERBS,
-        },
-        // The heaviest single weight, because it is the only feature that can see past the words. See
-        // ComplexityInput.afterHardTurn for why it is a weight rather than the gate it was designed as.
-        { rule: "after-hard-turn", weight: +0.25, of: (input) => input.afterHardTurn },
-        // The two absence features, deliberately light; see the note above the list.
-        { rule: "short-prompt", weight: -0.1, of: (_input, text) => text.length <= SHORT_PROMPT_CHARS },
-        { rule: "easy-words", weight: -0.25, of: (_input, text) => EASY_WORDS.test(text) },
-        { rule: "bare-question", weight: -0.15, of: (_input, text) => BARE_QUESTION.test(text) },
-        {
-            rule: "no-workspace-reference",
-            weight: -0.1,
-            of: (input, text) => input.attachments === 0 && !input.editorContext && !PATH_LIKE.test(text),
-        },
-    ];
+ * ONE PROPERTY IS NOT A HYPOTHESIS AND MUST SURVIVE ANY REFIT, and it is a RULE here rather than an accident of
+ * arithmetic: absence of complexity is not evidence of simplicity. "fix the bug" is four words naming no file
+ * and is not a cheap turn, so a downgrade always requires something POSITIVE to have been said — an easy word,
+ * or a bare question. Those two are marked `easing`, and `judgeComplexity` refuses a fast verdict without one
+ * whatever the score says.
+ *
+ * It used to hold only because the two ABSENCE features (`short-prompt`, `no-workspace-reference`) summed to
+ * 0.3 against a ceiling of 0.25, which is a coincidence of two numbers rather than a property, and the moment
+ * the ceiling became a setting it was one click from being false. Weighted the obvious way, the judge
+ * downgraded every short vague request in the product, which is the single worst population to be wrong
+ * about. */
+interface GradedFeature {
+    readonly rule: ComplexityRule;
+    readonly weight: number;
+    readonly of: (input: ComplexityInput, text: string) => boolean;
+    // A POSITIVE reason to think this is easy, as opposed to the mere absence of reasons to think it is hard.
+    // At least one has to fire before any turn is called fast; see the note above.
+    readonly easing?: true;
+}
+
+const GRADED: readonly GradedFeature[] = [
+    { rule: "medium-prompt", weight: +0.2, of: (_input, text) => text.length > MEDIUM_PROMPT_CHARS },
+    { rule: "attachment", weight: +0.15, of: (input) => input.attachments > 0 },
+    { rule: "editor-context", weight: +0.1, of: (input) => input.editorContext },
+    // Enough on its own to hold an easy-worded question at standard on the middle stop: "explain what this file
+    // does" is a question about real code in this repo, and the cheap rung's failures on real code are the
+    // silent kind. The `eager` stop is precisely the choice to let that one through.
+    { rule: "paths", weight: +0.15, of: (_input, text) => PATH_LIKE.test(text) },
+    {
+        rule: "many-verbs",
+        weight: +0.15,
+        of: (_input, text) => new Set((text.match(VERBS) ?? []).map((verb) => verb.toLowerCase())).size >= MANY_VERBS,
+    },
+    // The heaviest single weight, because it is the only feature that can see past the words. See
+    // ComplexityInput.afterHardTurn for why it is a weight rather than the gate it was designed as. Heavy enough
+    // that even the eager stop cannot route a follow-up to hard work on easy words alone.
+    { rule: "after-hard-turn", weight: +0.25, of: (input) => input.afterHardTurn },
+    /* The easing half, in the order it has always been declared, because that order is the order a verdict
+     * lists its rules in and the ledger has rows written against it. `easing` marks the two POSITIVE ones, one
+     * of which every fast verdict must carry; the other two are the absence features, deliberately light and,
+     * by the rule above, never enough by themselves. */
+    { rule: "short-prompt", weight: -0.1, of: (_input, text) => text.length <= SHORT_PROMPT_CHARS },
+    { rule: "easy-words", weight: -0.25, easing: true, of: (_input, text) => EASY_WORDS.test(text) },
+    { rule: "bare-question", weight: -0.15, easing: true, of: (_input, text) => BARE_QUESTION.test(text) },
+    {
+        rule: "no-workspace-reference",
+        weight: -0.1,
+        of: (input, text) => input.attachments === 0 && !input.editorContext && !PATH_LIKE.test(text),
+    },
+];
 
 // Three places, so a stored score is a value rather than a float artefact and two rows written by the same
 // rules compare equal.
@@ -258,14 +309,26 @@ const round3 = (value: number): number => Math.round(value * 1000) / 1000;
  * up a tier, never silently move a different set of turns down.
  *
  * Only what survives all of that gets scored, which keeps the graded layer doing the one job it is good at:
- * separating "explain this" from "wire this up" among requests that look alike. */
+ * separating "explain this" from "wire this up" among requests that look alike.
+ *
+ * TWO CONDITIONS FOR FAST, not one, and the second is the one that does not move: the score has to clear the
+ * owner's chosen ceiling AND something POSITIVE has to have been said (a `easing` feature). The ceiling is a
+ * preference and belongs to whoever pays the bill; "we downgraded it because you didn't say much" is not a
+ * preference, it is a bug, and it stays impossible at every stop of the knob. */
 export const judgeComplexity = (input: ComplexityInput): ComplexityVerdict => {
+    const ceiling = FAST_CEILINGS[input.eagerness ?? "balanced"];
     const text = input.prompt.trim();
     const forced = forcing(input, text);
     if (forced.length > 0) {
-        return { tier: "standard", score: 1, rules: forced };
+        return { tier: "standard", score: 1, rules: forced, ceiling };
     }
     const hits = GRADED.filter((feature) => feature.of(input, text));
     const score = Math.min(1, Math.max(0, BASE_SCORE + hits.reduce((total, feature) => total + feature.weight, 0)));
-    return { tier: score <= FAST_CEILING ? "fast" : "standard", score: round3(score), rules: hits.map((feature) => feature.rule) };
+    const eased = hits.some((feature) => feature.easing === true);
+    return {
+        tier: eased && score <= ceiling ? "fast" : "standard",
+        score: round3(score),
+        rules: hits.map((feature) => feature.rule),
+        ceiling,
+    };
 };

package/src/request-id.ts

@@ -0,0 +1,41 @@
+/* THE ONE HEADER THAT JOINS A BROWSER CALL TO THE DAEMON LINE THAT SERVED IT.
+ *
+ * Both halves of a slow interaction were already measured and could not be put together. The browser times
+ * `rpc.request`, what the user actually waited for; the daemon times `http.request`, what it served; and on a
+ * sandbox answering several calls a second the only way to pair them was by timestamp and hope. So "the panel
+ * stuttered" stayed unattributable even with both numbers in hand, which is the gap the daemon's own perf module
+ * says it exists to close and could only close on its own side of the wire.
+ *
+ * Here rather than as a literal on each side, because a header name that disagrees across the wire fails
+ * SILENTLY: the browser sends a field nobody reads and the daemon logs nothing, which looks exactly like a quiet
+ * system. Both sides import this.
+ *
+ * The NAME only. The browser mints the value with the app's own `composables/uuid.ts`, which already solves the
+ * one hard part (`crypto.randomUUID` is a secure-context api and a self-hosted instance on a LAN address does
+ * not have it), and the daemon only ever reads what it is given. A generator here would be a second answer to a
+ * question that already has a better one. The value is a correlation token and never a security boundary: the
+ * daemon records it and decides nothing on it, so a caller repeating one confuses a log and nothing else. */
+export const REQUEST_ID_HEADER = "x-intentic-request-id";
+
+/* WHEN A BROWSER MAY SEND IT, and this is not the additive change it looks like.
+ *
+ * A custom request header is the one wire addition that is NOT backward compatible, because the browser does not
+ * get to decide it: a header outside the CORS safelist forces a preflight, and a daemon whose `allowHeaders`
+ * predates this name answers a preflight that omits it. The browser then fails the whole request rather than
+ * dropping the header. Sent unconditionally, this turns "one field the daemon never logs" into EVERY typed call
+ * to that daemon failing at the transport, `system.events` included, so the stream never opens, the connection
+ * never reaches `online`, and the app settles on "Busy, catching up" forever against a sandbox that is up and
+ * healthy and answering `/health` in a millisecond.
+ *
+ * That state is not exotic. A browser newer than its daemon is the NORMAL case and a supported one, both in
+ * production (every user's sandbox runs whatever image they last chose to pull, and COMPATIBILITY.md's second
+ * promise is that no update is ever forced) and in development (the web app runs from the working tree, the
+ * daemon is baked into the last `pnpm build:sandbox`). See the web app's useDaemonRoutes.ts, which exists to say
+ * exactly this.
+ *
+ * So the header ships gated on POSITIVE evidence, and this names the evidence: `logs.report` is the route that
+ * landed in the same commit as the `allowHeaders` entry, so a daemon advertising it on its hello frame is a
+ * daemon whose CORS accepts the header. Note the polarity is the opposite of `supportsRoute`'s: there, no
+ * evidence means assume-supported, because hiding a working feature is the greater harm; here, no evidence must
+ * mean DO NOT SEND, because sending costs the entire connection and the header buys a log field. */
+export const REQUEST_ID_EVIDENCE_ROUTE = "logs.report";