@tangle-network/agent-app 0.44.27 → 0.44.29

package/dist/eval/index.d.ts

@@ -1,6 +1,113 @@
 import { CompletionRequirement, RuntimeEventLike } from '@tangle-network/agent-eval';
 export { CompletionRequirement, CompletionVerdict, CorrectnessChecker, ProducedState, RuntimeEventLike, SatisfiedBy, TaskGold, createLlmCorrectnessChecker, extractProducedState, verifyCompletion, weightedComposite } from '@tangle-network/agent-eval';
-import { A as AppToolProducedEvent } from '../types-BCxK0wyS.js';
+import { c as AppToolProducedEvent } from '../types-DbU-oO5h.js';
+
+/**
+ * Calibration — prove a gate can FAIL before believing that it PASSED, and
+ * prove a probe can SEE before believing the zero it reported.
+ *
+ * Every expensive failure this package has shipped was a check that verified
+ * its own input instead of the world, and reported green:
+ *
+ *   - `quote_verification 16/16` passed a work product whose nine citations
+ *     claimed a figure the cited document never mentions.
+ *   - `audit_form passed=3 failed=0` passed a form fill whose values landed in
+ *     "Combat zone" — the audit re-read the field paths the writer had just
+ *     invented, so a wrong path could not be wrong.
+ *   - `evidence_coverage 0/0` passed vacuously because the artifact it was
+ *     counting targets from was null.
+ *   - A benchmark reported 6/8 for the product while a bare
+ *     "You are a helpful assistant." scored 8/8 on the same cases.
+ *
+ * A gate is only evidence if it REJECTS something. A metric is only evidence
+ * if a worse system scores worse on it. Neither property is implied by a
+ * green run, and neither is visible in the output — which is why both have to
+ * be asserted separately, in code, next to the gate.
+ *
+ * This module is deliberately domain-free: a "gate" is any predicate over any
+ * input. Products supply the known-good and known-bad cases, because only the
+ * product knows what bad looks like in its domain.
+ */
+/** A case whose verdict is known in advance, used to calibrate a gate. */
+interface CalibrationCase<TInput> {
+    /** What this case represents, e.g. `'quote that does not occur in the source'`. */
+    readonly label: string;
+    readonly input: TInput;
+    /** `'reject'` — the gate MUST refuse this. `'accept'` — it MUST allow it. */
+    readonly expect: 'accept' | 'reject';
+}
+interface CalibrationOutcome {
+    readonly label: string;
+    readonly expected: 'accept' | 'reject';
+    readonly actual: 'accept' | 'reject';
+    readonly ok: boolean;
+    /** Set when the gate threw; a throw counts as `'reject'`. */
+    readonly threw?: string;
+}
+interface CalibrationReport {
+    /** True only when every case matched AND both controls were present. */
+    readonly discriminates: boolean;
+    readonly outcomes: readonly CalibrationOutcome[];
+    readonly failures: readonly CalibrationOutcome[];
+    /** Why the gate is not trustworthy. Absent when `discriminates` is true. */
+    readonly reason?: string;
+}
+/**
+ * A gate under calibration. Returning `false` OR throwing both count as a
+ * rejection — a fail-loud gate (`ToolInputError`) and a boolean gate calibrate
+ * through the same path.
+ */
+type GateFn<TInput> = (input: TInput) => boolean | Promise<boolean>;
+/**
+ * Run a gate against cases whose verdicts are known, and report whether it
+ * actually discriminates.
+ *
+ * Requires BOTH controls:
+ *   - at least one `'reject'` case — without it a gate that returns `true`
+ *     unconditionally is indistinguishable from a working one. This is the
+ *     control that all four failures above were missing.
+ *   - at least one `'accept'` case — without it a gate that refuses everything
+ *     scores perfectly, and an unsatisfiable gate does not stop bad work, it
+ *     selects for invented work (measured: 38 fabricated citations written to
+ *     clear a coverage gate no honest answer could satisfy).
+ */
+declare function calibrateGate<TInput>(gate: GateFn<TInput>, cases: readonly CalibrationCase<TInput>[]): Promise<CalibrationReport>;
+/**
+ * `calibrateGate`, but throws instead of reporting. Use in a test or at wiring
+ * time so an uncalibrated gate cannot ship silently.
+ */
+declare function assertGateDiscriminates<TInput>(name: string, gate: GateFn<TInput>, cases: readonly CalibrationCase<TInput>[]): Promise<CalibrationReport>;
+interface ProbeReport<TValue> {
+    /** True when the positive control registered something, so a zero is real. */
+    readonly canSee: boolean;
+    readonly measured: number;
+    readonly control: number;
+    readonly value: TValue;
+    readonly reason?: string;
+}
+/**
+ * Measure something, but only after proving the instrument can register a
+ * non-zero — because an absence is a claim about the measurement first.
+ *
+ * Six blind probes were mistaken for real zeros in a single day: a SQL `LIKE`
+ * over a column the product encrypts (which equally returned 0 for `"text"`
+ * across every row — the tell), a `grep` run against worktrees on stale
+ * branches, a status-code comparison that never read the response bodies, a
+ * live event count taken from a run that was never dispatched, `rg --hidden`
+ * silently exiting 2 because `rg` was aliased to `grep`, and an intercepted
+ * `git show` returning an empty diff. Each nearly caused a wrong fix.
+ *
+ * `control` must count something that MUST exist. If it counts zero, the
+ * measurement is unusable regardless of what `measure` returned.
+ */
+declare function measureWithControl<TValue>(opts: {
+    readonly measure: () => TValue | Promise<TValue>;
+    /** Must return a value whose count is non-zero, or the probe is blind. */
+    readonly control: () => TValue | Promise<TValue>;
+    readonly count: (value: TValue) => number;
+    /** Describes what the control counts, for the failure message. */
+    readonly controlLabel: string;
+}): Promise<ProbeReport<TValue>>;
 
 /**
  * Eval — the app-shell BRIDGE to `@tangle-network/agent-eval`, not a reimpl.
@@ -47,4 +154,4 @@ declare function createTokenRecallChecker(opts?: {
     reason: string;
 }>;
 
-export { createTokenRecallChecker, producedFromToolEvents };
+export { type CalibrationCase, type CalibrationOutcome, type CalibrationReport, type GateFn, type ProbeReport, assertGateDiscriminates, calibrateGate, createTokenRecallChecker, measureWithControl, producedFromToolEvents };

package/dist/eval/index.js

@@ -1,5 +1,46 @@
 // src/eval/index.ts
 import { verifyCompletion, extractProducedState, weightedComposite, createLlmCorrectnessChecker } from "@tangle-network/agent-eval";
+
+// src/eval/calibration.ts
+async function calibrateGate(gate, cases) {
+  const outcomes = [];
+  for (const c of cases) {
+    let actual;
+    let threw;
+    try {
+      actual = await gate(c.input) ? "accept" : "reject";
+    } catch (err) {
+      actual = "reject";
+      threw = err instanceof Error ? err.message : String(err);
+    }
+    outcomes.push({ label: c.label, expected: c.expect, actual, ok: actual === c.expect, ...threw ? { threw } : {} });
+  }
+  const failures = outcomes.filter((o) => !o.ok);
+  const hasNegative = cases.some((c) => c.expect === "reject");
+  const hasPositive = cases.some((c) => c.expect === "accept");
+  const reason = !hasNegative ? "no negative control: every case expects acceptance, so a gate that never refuses would score perfectly" : !hasPositive ? "no positive control: every case expects rejection, so a gate that refuses everything would score perfectly" : failures.length > 0 ? `${failures.length}/${outcomes.length} cases disagreed: ${failures.map((f) => `${f.label} expected ${f.expected}, got ${f.actual}`).join("; ")}` : void 0;
+  return { discriminates: reason === void 0, outcomes, failures, ...reason ? { reason } : {} };
+}
+async function assertGateDiscriminates(name, gate, cases) {
+  const report = await calibrateGate(gate, cases);
+  if (!report.discriminates) throw new Error(`gate "${name}" is not evidence \u2014 ${report.reason}`);
+  return report;
+}
+async function measureWithControl(opts) {
+  const value = await opts.measure();
+  const controlValue = await opts.control();
+  const measured = opts.count(value);
+  const control = opts.count(controlValue);
+  return control > 0 ? { canSee: true, measured, control, value } : {
+    canSee: false,
+    measured,
+    control,
+    value,
+    reason: `probe is blind: the positive control (${opts.controlLabel}) counted 0, so the measured ${measured} carries no information`
+  };
+}
+
+// src/eval/index.ts
 function producedFromToolEvents(events) {
   return events.map(
     (e) => e.type === "proposal_created" ? { type: "proposal_created", proposalId: e.proposalId, title: e.title, status: e.status, content: e.content } : { type: "artifact", artifactId: `vault:${e.path}`, name: e.path, uri: `vault://${e.path}`, mimeType: "text/markdown", content: e.content }
@@ -21,9 +62,12 @@ function createTokenRecallChecker(opts = {}) {
   };
 }
 export {
+  assertGateDiscriminates,
+  calibrateGate,
   createLlmCorrectnessChecker,
   createTokenRecallChecker,
   extractProducedState,
+  measureWithControl,
   producedFromToolEvents,
   verifyCompletion,
   weightedComposite

package/dist/eval/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/eval/index.ts"],"sourcesContent":["/**\n * Eval — the app-shell BRIDGE to `@tangle-network/agent-eval`, not a reimpl.\n *\n * The completion/scoring ENGINE lives in agent-eval (a peer dependency):\n * `verifyCompletion`, `extractProducedState`, `weightedComposite`,\n * `createLlmCorrectnessChecker`, and the `CompletionRequirement` / `TaskGold` /\n * `ProducedState` types — all re-exported here so a consumer has one import\n * root. This module adds only what agent-eval doesn't have and what is\n * app-shell-specific:\n *\n *   1. {@link producedFromToolEvents} — the bridge: turn the structured app-tool\n *      side channel's `AppToolProducedEvent`s (from a tool runtime executor's\n *      `onProduced`) into the `RuntimeEventLike`s agent-eval's\n *      `extractProducedState` consumes. This is the one piece that knows about\n *      the app-tool channel, so it belongs here, not in the engine.\n *   2. {@link createTokenRecallChecker} — a deterministic, no-LLM\n *      `CorrectnessChecker` (agent-eval ships only the LLM one). For apps/tests\n *      that gate completion without a judge call.\n *\n * Full campaigns (persona simulation, traces, scorecards, held-out gates) are\n * agent-eval's `runEvalCampaign` / `AgentDriver` / `BenchmarkRunner` — use them\n * directly; this module composes with them.\n */\nimport type { RuntimeEventLike, CompletionRequirement } from '@tangle-network/agent-eval'\nimport type { AppToolProducedEvent } from '../tools/types'\n\n// Re-export the engine so consumers import completion + scoring from one place.\nexport { verifyCompletion, extractProducedState, weightedComposite, createLlmCorrectnessChecker } from '@tangle-network/agent-eval'\nexport type {\n  CompletionRequirement,\n  TaskGold,\n  ProducedState,\n  SatisfiedBy,\n  CompletionVerdict,\n  CorrectnessChecker,\n  RuntimeEventLike,\n} from '@tangle-network/agent-eval'\n\n/**\n * Bridge the app-tool side channel's produced events into the runtime-event\n * shape agent-eval's `extractProducedState` reads. Pipe it:\n *   `verifyCompletion(taskGold, extractProducedState(producedFromToolEvents(events)), checker)`\n */\nexport function producedFromToolEvents(events: readonly AppToolProducedEvent[]): RuntimeEventLike[] {\n  return events.map((e) =>\n    e.type === 'proposal_created'\n      ? { type: 'proposal_created', proposalId: e.proposalId, title: e.title, status: e.status, content: e.content }\n      : { type: 'artifact', artifactId: `vault:${e.path}`, name: e.path, uri: `vault://${e.path}`, mimeType: 'text/markdown', content: e.content },\n  )\n}\n\nconst STOPWORDS = new Set(['the', 'a', 'an', 'and', 'or', 'for', 'to', 'of', 'in', 'on', 'with', 'review', 'update', 'new', 'proposed'])\n\n/**\n * A deterministic `CorrectnessChecker` (agent-eval exports only\n * `createLlmCorrectnessChecker`). A produced item fulfils a requirement when\n * its content is substantive and recalls ≥ `minRecall` of the requirement\n * title's significant tokens. No network — the default gate for apps/tests\n * without an LLM judge. Pass to `verifyCompletion` as the checker.\n */\nexport function createTokenRecallChecker(opts: { minRecall?: number; minContentLength?: number } = {}): (\n  requirement: CompletionRequirement,\n  content: string,\n) => Promise<{ correct: boolean; reason: string }> {\n  const minRecall = opts.minRecall ?? 0.5\n  const minLen = opts.minContentLength ?? 120\n  return async (requirement, content) => {\n    const body = content.trim()\n    if (body.length < minLen) return { correct: false, reason: `content too thin (${body.length} chars) to be the deliverable` }\n    const tokens = requirement.title.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 2 && !STOPWORDS.has(t))\n    if (tokens.length === 0) return { correct: true, reason: 'requirement title has no significant tokens — structural match accepted' }\n    const lower = body.toLowerCase()\n    const hits = tokens.filter((t) => lower.includes(t)).length\n    const recall = hits / tokens.length\n    return recall >= minRecall\n      ? { correct: true, reason: `content recalls ${hits}/${tokens.length} requirement tokens` }\n      : { correct: false, reason: `content recalls only ${hits}/${tokens.length} requirement tokens` }\n  }\n}\n"],"mappings":";AA2BA,SAAS,kBAAkB,sBAAsB,mBAAmB,mCAAmC;AAgBhG,SAAS,uBAAuB,QAA6D;AAClG,SAAO,OAAO;AAAA,IAAI,CAAC,MACjB,EAAE,SAAS,qBACP,EAAE,MAAM,oBAAoB,YAAY,EAAE,YAAY,OAAO,EAAE,OAAO,QAAQ,EAAE,QAAQ,SAAS,EAAE,QAAQ,IAC3G,EAAE,MAAM,YAAY,YAAY,SAAS,EAAE,IAAI,IAAI,MAAM,EAAE,MAAM,KAAK,WAAW,EAAE,IAAI,IAAI,UAAU,iBAAiB,SAAS,EAAE,QAAQ;AAAA,EAC/I;AACF;AAEA,IAAM,YAAY,oBAAI,IAAI,CAAC,OAAO,KAAK,MAAM,OAAO,MAAM,OAAO,MAAM,MAAM,MAAM,MAAM,QAAQ,UAAU,UAAU,OAAO,UAAU,CAAC;AAShI,SAAS,yBAAyB,OAA0D,CAAC,GAGjD;AACjD,QAAM,YAAY,KAAK,aAAa;AACpC,QAAM,SAAS,KAAK,oBAAoB;AACxC,SAAO,OAAO,aAAa,YAAY;AACrC,UAAM,OAAO,QAAQ,KAAK;AAC1B,QAAI,KAAK,SAAS,OAAQ,QAAO,EAAE,SAAS,OAAO,QAAQ,qBAAqB,KAAK,MAAM,gCAAgC;AAC3H,UAAM,SAAS,YAAY,MAAM,YAAY,EAAE,MAAM,YAAY,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC;AAClH,QAAI,OAAO,WAAW,EAAG,QAAO,EAAE,SAAS,MAAM,QAAQ,+EAA0E;AACnI,UAAM,QAAQ,KAAK,YAAY;AAC/B,UAAM,OAAO,OAAO,OAAO,CAAC,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE;AACrD,UAAM,SAAS,OAAO,OAAO;AAC7B,WAAO,UAAU,YACb,EAAE,SAAS,MAAM,QAAQ,mBAAmB,IAAI,IAAI,OAAO,MAAM,sBAAsB,IACvF,EAAE,SAAS,OAAO,QAAQ,wBAAwB,IAAI,IAAI,OAAO,MAAM,sBAAsB;AAAA,EACnG;AACF;","names":[]}
+{"version":3,"sources":["../../src/eval/index.ts","../../src/eval/calibration.ts"],"sourcesContent":["/**\n * Eval — the app-shell BRIDGE to `@tangle-network/agent-eval`, not a reimpl.\n *\n * The completion/scoring ENGINE lives in agent-eval (a peer dependency):\n * `verifyCompletion`, `extractProducedState`, `weightedComposite`,\n * `createLlmCorrectnessChecker`, and the `CompletionRequirement` / `TaskGold` /\n * `ProducedState` types — all re-exported here so a consumer has one import\n * root. This module adds only what agent-eval doesn't have and what is\n * app-shell-specific:\n *\n *   1. {@link producedFromToolEvents} — the bridge: turn the structured app-tool\n *      side channel's `AppToolProducedEvent`s (from a tool runtime executor's\n *      `onProduced`) into the `RuntimeEventLike`s agent-eval's\n *      `extractProducedState` consumes. This is the one piece that knows about\n *      the app-tool channel, so it belongs here, not in the engine.\n *   2. {@link createTokenRecallChecker} — a deterministic, no-LLM\n *      `CorrectnessChecker` (agent-eval ships only the LLM one). For apps/tests\n *      that gate completion without a judge call.\n *\n * Full campaigns (persona simulation, traces, scorecards, held-out gates) are\n * agent-eval's `runEvalCampaign` / `AgentDriver` / `BenchmarkRunner` — use them\n * directly; this module composes with them.\n */\nimport type { RuntimeEventLike, CompletionRequirement } from '@tangle-network/agent-eval'\nimport type { AppToolProducedEvent } from '../tools/types'\n\n// Re-export the engine so consumers import completion + scoring from one place.\nexport { verifyCompletion, extractProducedState, weightedComposite, createLlmCorrectnessChecker } from '@tangle-network/agent-eval'\n\n// Calibration: prove a gate can FAIL before believing it PASSED, and prove a\n// probe can SEE before believing the zero it reported. Domain-free, so it\n// calibrates a citation gate, a form audit, or a benchmark equally.\nexport { calibrateGate, assertGateDiscriminates, measureWithControl } from './calibration'\nexport type { CalibrationCase, CalibrationOutcome, CalibrationReport, GateFn, ProbeReport } from './calibration'\nexport type {\n  CompletionRequirement,\n  TaskGold,\n  ProducedState,\n  SatisfiedBy,\n  CompletionVerdict,\n  CorrectnessChecker,\n  RuntimeEventLike,\n} from '@tangle-network/agent-eval'\n\n/**\n * Bridge the app-tool side channel's produced events into the runtime-event\n * shape agent-eval's `extractProducedState` reads. Pipe it:\n *   `verifyCompletion(taskGold, extractProducedState(producedFromToolEvents(events)), checker)`\n */\nexport function producedFromToolEvents(events: readonly AppToolProducedEvent[]): RuntimeEventLike[] {\n  return events.map((e) =>\n    e.type === 'proposal_created'\n      ? { type: 'proposal_created', proposalId: e.proposalId, title: e.title, status: e.status, content: e.content }\n      : { type: 'artifact', artifactId: `vault:${e.path}`, name: e.path, uri: `vault://${e.path}`, mimeType: 'text/markdown', content: e.content },\n  )\n}\n\nconst STOPWORDS = new Set(['the', 'a', 'an', 'and', 'or', 'for', 'to', 'of', 'in', 'on', 'with', 'review', 'update', 'new', 'proposed'])\n\n/**\n * A deterministic `CorrectnessChecker` (agent-eval exports only\n * `createLlmCorrectnessChecker`). A produced item fulfils a requirement when\n * its content is substantive and recalls ≥ `minRecall` of the requirement\n * title's significant tokens. No network — the default gate for apps/tests\n * without an LLM judge. Pass to `verifyCompletion` as the checker.\n */\nexport function createTokenRecallChecker(opts: { minRecall?: number; minContentLength?: number } = {}): (\n  requirement: CompletionRequirement,\n  content: string,\n) => Promise<{ correct: boolean; reason: string }> {\n  const minRecall = opts.minRecall ?? 0.5\n  const minLen = opts.minContentLength ?? 120\n  return async (requirement, content) => {\n    const body = content.trim()\n    if (body.length < minLen) return { correct: false, reason: `content too thin (${body.length} chars) to be the deliverable` }\n    const tokens = requirement.title.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 2 && !STOPWORDS.has(t))\n    if (tokens.length === 0) return { correct: true, reason: 'requirement title has no significant tokens — structural match accepted' }\n    const lower = body.toLowerCase()\n    const hits = tokens.filter((t) => lower.includes(t)).length\n    const recall = hits / tokens.length\n    return recall >= minRecall\n      ? { correct: true, reason: `content recalls ${hits}/${tokens.length} requirement tokens` }\n      : { correct: false, reason: `content recalls only ${hits}/${tokens.length} requirement tokens` }\n  }\n}\n","/**\n * Calibration — prove a gate can FAIL before believing that it PASSED, and\n * prove a probe can SEE before believing the zero it reported.\n *\n * Every expensive failure this package has shipped was a check that verified\n * its own input instead of the world, and reported green:\n *\n *   - `quote_verification 16/16` passed a work product whose nine citations\n *     claimed a figure the cited document never mentions.\n *   - `audit_form passed=3 failed=0` passed a form fill whose values landed in\n *     \"Combat zone\" — the audit re-read the field paths the writer had just\n *     invented, so a wrong path could not be wrong.\n *   - `evidence_coverage 0/0` passed vacuously because the artifact it was\n *     counting targets from was null.\n *   - A benchmark reported 6/8 for the product while a bare\n *     \"You are a helpful assistant.\" scored 8/8 on the same cases.\n *\n * A gate is only evidence if it REJECTS something. A metric is only evidence\n * if a worse system scores worse on it. Neither property is implied by a\n * green run, and neither is visible in the output — which is why both have to\n * be asserted separately, in code, next to the gate.\n *\n * This module is deliberately domain-free: a \"gate\" is any predicate over any\n * input. Products supply the known-good and known-bad cases, because only the\n * product knows what bad looks like in its domain.\n */\n\n/** A case whose verdict is known in advance, used to calibrate a gate. */\nexport interface CalibrationCase<TInput> {\n  /** What this case represents, e.g. `'quote that does not occur in the source'`. */\n  readonly label: string\n  readonly input: TInput\n  /** `'reject'` — the gate MUST refuse this. `'accept'` — it MUST allow it. */\n  readonly expect: 'accept' | 'reject'\n}\n\nexport interface CalibrationOutcome {\n  readonly label: string\n  readonly expected: 'accept' | 'reject'\n  readonly actual: 'accept' | 'reject'\n  readonly ok: boolean\n  /** Set when the gate threw; a throw counts as `'reject'`. */\n  readonly threw?: string\n}\n\nexport interface CalibrationReport {\n  /** True only when every case matched AND both controls were present. */\n  readonly discriminates: boolean\n  readonly outcomes: readonly CalibrationOutcome[]\n  readonly failures: readonly CalibrationOutcome[]\n  /** Why the gate is not trustworthy. Absent when `discriminates` is true. */\n  readonly reason?: string\n}\n\n/**\n * A gate under calibration. Returning `false` OR throwing both count as a\n * rejection — a fail-loud gate (`ToolInputError`) and a boolean gate calibrate\n * through the same path.\n */\nexport type GateFn<TInput> = (input: TInput) => boolean | Promise<boolean>\n\n/**\n * Run a gate against cases whose verdicts are known, and report whether it\n * actually discriminates.\n *\n * Requires BOTH controls:\n *   - at least one `'reject'` case — without it a gate that returns `true`\n *     unconditionally is indistinguishable from a working one. This is the\n *     control that all four failures above were missing.\n *   - at least one `'accept'` case — without it a gate that refuses everything\n *     scores perfectly, and an unsatisfiable gate does not stop bad work, it\n *     selects for invented work (measured: 38 fabricated citations written to\n *     clear a coverage gate no honest answer could satisfy).\n */\nexport async function calibrateGate<TInput>(\n  gate: GateFn<TInput>,\n  cases: readonly CalibrationCase<TInput>[],\n): Promise<CalibrationReport> {\n  const outcomes: CalibrationOutcome[] = []\n  for (const c of cases) {\n    let actual: 'accept' | 'reject'\n    let threw: string | undefined\n    try {\n      actual = (await gate(c.input)) ? 'accept' : 'reject'\n    } catch (err) {\n      actual = 'reject'\n      threw = err instanceof Error ? err.message : String(err)\n    }\n    outcomes.push({ label: c.label, expected: c.expect, actual, ok: actual === c.expect, ...(threw ? { threw } : {}) })\n  }\n\n  const failures = outcomes.filter((o) => !o.ok)\n  const hasNegative = cases.some((c) => c.expect === 'reject')\n  const hasPositive = cases.some((c) => c.expect === 'accept')\n\n  const reason = !hasNegative\n    ? 'no negative control: every case expects acceptance, so a gate that never refuses would score perfectly'\n    : !hasPositive\n      ? 'no positive control: every case expects rejection, so a gate that refuses everything would score perfectly'\n      : failures.length > 0\n        ? `${failures.length}/${outcomes.length} cases disagreed: ${failures.map((f) => `${f.label} expected ${f.expected}, got ${f.actual}`).join('; ')}`\n        : undefined\n\n  return { discriminates: reason === undefined, outcomes, failures, ...(reason ? { reason } : {}) }\n}\n\n/**\n * `calibrateGate`, but throws instead of reporting. Use in a test or at wiring\n * time so an uncalibrated gate cannot ship silently.\n */\nexport async function assertGateDiscriminates<TInput>(\n  name: string,\n  gate: GateFn<TInput>,\n  cases: readonly CalibrationCase<TInput>[],\n): Promise<CalibrationReport> {\n  const report = await calibrateGate(gate, cases)\n  if (!report.discriminates) throw new Error(`gate \"${name}\" is not evidence — ${report.reason}`)\n  return report\n}\n\nexport interface ProbeReport<TValue> {\n  /** True when the positive control registered something, so a zero is real. */\n  readonly canSee: boolean\n  readonly measured: number\n  readonly control: number\n  readonly value: TValue\n  readonly reason?: string\n}\n\n/**\n * Measure something, but only after proving the instrument can register a\n * non-zero — because an absence is a claim about the measurement first.\n *\n * Six blind probes were mistaken for real zeros in a single day: a SQL `LIKE`\n * over a column the product encrypts (which equally returned 0 for `\"text\"`\n * across every row — the tell), a `grep` run against worktrees on stale\n * branches, a status-code comparison that never read the response bodies, a\n * live event count taken from a run that was never dispatched, `rg --hidden`\n * silently exiting 2 because `rg` was aliased to `grep`, and an intercepted\n * `git show` returning an empty diff. Each nearly caused a wrong fix.\n *\n * `control` must count something that MUST exist. If it counts zero, the\n * measurement is unusable regardless of what `measure` returned.\n */\nexport async function measureWithControl<TValue>(opts: {\n  readonly measure: () => TValue | Promise<TValue>\n  /** Must return a value whose count is non-zero, or the probe is blind. */\n  readonly control: () => TValue | Promise<TValue>\n  readonly count: (value: TValue) => number\n  /** Describes what the control counts, for the failure message. */\n  readonly controlLabel: string\n}): Promise<ProbeReport<TValue>> {\n  const value = await opts.measure()\n  const controlValue = await opts.control()\n  const measured = opts.count(value)\n  const control = opts.count(controlValue)\n  return control > 0\n    ? { canSee: true, measured, control, value }\n    : {\n        canSee: false,\n        measured,\n        control,\n        value,\n        reason: `probe is blind: the positive control (${opts.controlLabel}) counted 0, so the measured ${measured} carries no information`,\n      }\n}\n"],"mappings":"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","names":[]}

package/dist/{mcp-D3qVzbE1.d.ts → mcp-Dt4V4ZLT.d.ts}

@@ -1,5 +1,5 @@
-import { a as AppToolContext, b as AppToolName, c as AppToolDefinition } from './types-BCxK0wyS.js';
-import { T as ToolHeaderNames } from './auth-anc7mv2W.js';
+import { A as AppToolContext, a as AppToolName, b as AppToolDefinition } from './types-DbU-oO5h.js';
+import { T as ToolHeaderNames } from './auth-DJs6lfAs.js';
 
 /** Default route path each app tool is served at. A product mounts its routes
  *  at these paths (or supplies its own via {@link BuildMcpServerOptions.paths}). */

package/dist/preset-cloudflare/index.d.ts

@@ -1,6 +1,6 @@
 import { KeyProvisioner, KeyCrypto, WorkspaceKeyManager, WorkspaceKeyStore } from '../billing/index.js';
 import { KnowledgeStateAccessor } from '../knowledge/index.js';
-import { d as AppToolHandlers } from '../types-BCxK0wyS.js';
+import { d as AppToolHandlers } from '../types-DbU-oO5h.js';
 import { KvLike } from '../web/index.js';
 import '@tangle-network/agent-eval';
 

package/dist/runtime/index.d.ts

@@ -4,9 +4,9 @@ import * as _tangle_network_agent_runtime from '@tangle-network/agent-runtime';
 import { ToolLoopMessage } from '@tangle-network/agent-runtime';
 export { RunToolLoopOptions as AppToolLoopOptions, ToolLoopAssistantToolCall as LoopAssistantToolCall, ToolLoopMessage as LoopMessage, ToolLoopCall as LoopToolCall, StreamToolLoopOptions as StreamAppToolLoopOptions, StreamToolLoopYield as StreamLoopYield, ToolLoopEvent, ToolLoopResult, ToolLoopStopReason, runToolLoop as runAppToolLoop, streamToolLoop as streamAppToolLoop } from '@tangle-network/agent-runtime';
 import { CertifiedProfile } from '@tangle-network/agent-runtime/intelligence';
-import { A as AppToolMcpServer } from '../mcp-D3qVzbE1.js';
-import '../types-BCxK0wyS.js';
-import '../auth-anc7mv2W.js';
+import { A as AppToolMcpServer } from '../mcp-Dt4V4ZLT.js';
+import '../types-DbU-oO5h.js';
+import '../auth-DJs6lfAs.js';
 
 /**
  * Events the app's OpenAI-compat stream adapter ({@link toLoopEvents}) yields.

package/dist/sandbox/index.d.ts

@@ -1,8 +1,8 @@
 import { SandboxInstance, ProvisionEvent, StorageConfig, ScopedTokenScope, TurnDriveResult, Sandbox, MintScopedTokenOptions } from '@tangle-network/sandbox';
 export { StorageConfig } from '@tangle-network/sandbox';
 import { AgentProfileMcpServer, AgentProfileFileMount, AgentProfile } from '@tangle-network/agent-interface';
-import { T as ToolHeaderNames } from '../auth-anc7mv2W.js';
-import { b as AppToolName, a as AppToolContext } from '../types-BCxK0wyS.js';
+import { T as ToolHeaderNames } from '../auth-DJs6lfAs.js';
+import { a as AppToolName, A as AppToolContext } from '../types-DbU-oO5h.js';
 import { Harness } from '../harness/index.js';
 import { a as TangleExecutionEnvironment } from '../model-CdCDfBA9.js';
 import { b as ProfileFingerprint, C as ComposeProfileBudget } from '../budget-BOucfcb_.js';
@@ -369,6 +369,29 @@ interface SandboxApiCredentials {
     baseUrl: string;
     apiKey: string;
 }
+/**
+ * Build the sandbox API's sidecar-proxy base for a box:
+ * `{baseUrl}/v1/sidecar-proxy/{sandboxId}`.
+ *
+ * This is the ONLY upstream that serves the interactive terminal. Measured on
+ * production (`sandbox.tangle.tools`, one box, `ws` client, same credential in
+ * every arm):
+ *
+ * | upstream base                          | result                          |
+ * |----------------------------------------|---------------------------------|
+ * | `/v1/sidecar-proxy/{id}`               | 101 -> `ready` 2551ms -> shell  |
+ * | `/v1/sandboxes/{id}/runtime/`          | HTTP 500                        |
+ * | `connection.runtimeUrl` (the box host) | 101 then close 1000, 0 bytes    |
+ *
+ * The box's own `connection.runtimeUrl` (`https://sandbox-*.tangle.sh`) accepts
+ * the upgrade — its Caddy front end upgrades every path, including ones that do
+ * not exist — and then hangs up without a PTY. A 101 from that host therefore
+ * proves nothing; only a `ready` control frame does. Two products shipped a
+ * terminal against it and rendered a permanent spinner.
+ *
+ * Exported so no product writes the path literal a fourth time.
+ */
+declare function sandboxSidecarProxyUrl(baseUrl: string, sandboxId: string): string;
 /** Define a connection configuration for sandbox runtime including URL and optional server-side auth token */
 interface SandboxRuntimeConnection {
     runtimeUrl: string;
@@ -464,6 +487,42 @@ interface WorkspaceSandboxTerminalUpgradeHandlerOptions {
  * ```
  */
 declare function createWorkspaceSandboxTerminalUpgradeHandler(opts: WorkspaceSandboxTerminalUpgradeHandlerOptions): (request: Request) => Promise<Response | null>;
+/** A response-like shape carrying just what the subprotocol echo decision reads. */
+interface TerminalUpgradeResponseLike {
+    status: number;
+    statusText?: string;
+    headers: Headers;
+}
+/**
+ * Decide whether a terminal upgrade's 101 needs the browser's own subprotocol
+ * echoed back onto it, and return the headers to answer with. `null` means
+ * "pass the upstream response through untouched".
+ *
+ * Why this exists: the browser's terminal credential rides in a
+ * `bearer.<base64url>` WebSocket subprotocol, because a browser cannot set
+ * `Authorization` on a WS handshake. That subprotocol is a browser-to-Worker
+ * credential, so it is stripped before the upstream hop — and the upstream then
+ * answers the 101 selecting nothing. A browser MUST fail the connection when a
+ * 101 selects no subprotocol after it offered one (RFC 6455 s4.1), so the socket
+ * dies on open and the terminal renders a spinner forever.
+ *
+ * Kept as a pure function because a 101 `Response` cannot be constructed off
+ * Workers, so this is the only part of the decision a test can drive directly.
+ */
+declare function terminalUpgradeSubprotocolEcho(upstream: TerminalUpgradeResponseLike, browserProtocol: string | null): {
+    status: number;
+    statusText: string;
+    headers: Headers;
+} | null;
+/**
+ * The exact `bearer.*` subprotocol string the browser offered, so it can be
+ * echoed verbatim on the 101. Returns null when the browser offered none.
+ *
+ * Takes the raw `Sec-WebSocket-Protocol` value rather than the `Headers`, to
+ * match its siblings `bearerSubprotocolToken` and `stripBearerSubprotocol` —
+ * one shape for the whole family, and the caller reads the header once.
+ */
+declare function selectedBearerSubprotocol(value: string | null): string | null;
 /** Build proxy headers for sandbox runtime including authorization and forwarded headers */
 declare function buildSandboxRuntimeProxyHeaders(source: Headers, sandboxApiKey: string, forwardHeaders?: string[]): Headers;
 /** Encode a runtime path by URI-encoding each valid segment and returning null for invalid segments */
@@ -475,6 +534,199 @@ declare function bearerSubprotocolToken(value: string | null): string | null;
 /** Resolve the terminal token from request headers using Authorization or Sec-WebSocket-Protocol fields */
 declare function terminalTokenFromRequest(headers: Headers): string | null;
 
+/**
+ * `createSandboxPrewarmer` — "this user just opened this project; start warming
+ * their box" as a shell primitive, so every agent-app product gets the same
+ * answer instead of forking one.
+ *
+ * WHY THIS IS SHELL, NOT ENGINE. The engine rule asks whether the capability
+ * makes sense without a specific app's side channel. "Warm a box" does — but
+ * `@tangle-network/sandbox` has no notion of a WORKSPACE. It keys boxes by an
+ * opaque sandbox id; the workspace→box mapping, the harness match, and the
+ * profile materialisation all live in `ensureWorkspaceSandbox` here. A
+ * prewarmer is that mapping plus a scheduling policy, so it belongs beside it.
+ * It is deliberately NOT a new subpath: it composes `peekWorkspaceSandbox` and
+ * `ensureWorkspaceSandbox` directly and needs exactly the peers `/sandbox`
+ * already needs, so a separate entry would add a second place to look for "how
+ * do I get a box" and buy no peer isolation (the reason `/work-product-react`
+ * is split out).
+ *
+ * WHAT IT IS NOT. It does not make cold starts fast — they already are.
+ * Measured on the real platform (staging-sandbox, n=5, 2026-07-28): a box goes
+ * from nothing to terminal-ready in 2.34–3.19 s (median 2.73 s), and an
+ * already-running box answers in 1.16–2.29 s (median 1.35 s). Prewarming buys
+ * ~1.4 s. The reason it matters is not latency: it is that a product which
+ * only ever provisions lazily, on a path whose guard never passes, never
+ * provisions AT ALL — and the UI then shows a spinner over a box that does not
+ * exist and is not being created. That is the failure this primitive removes.
+ *
+ * ── COST POSTURE (read before adopting) ────────────────────────────────────
+ * A warmed box is a REAL charge. It bills from creation until the platform's
+ * idle timeout reclaims it — `SandboxRuntimeConfig`'s create-time
+ * `idleTimeoutSeconds`, not anything this module sets. A product warming on
+ * every project open pays that timeout for every user who opens and bounces.
+ * With a 3600 s idle timeout against a ~131 s mean session life, a bounce
+ * costs an hour of box time to save ~1.4 s. THAT TRADE IS USUALLY WRONG.
+ *
+ * So the levers are explicit and the defaults are the cheap ones:
+ *   - `mode: 'resume-only'` (DEFAULT) never creates a box that does not exist.
+ *     It only revives one the user already has, so the spend is bounded by
+ *     boxes the user already caused. This is the safe fleet default.
+ *   - `mode: 'create-or-resume'` is the owner-requested behaviour — warm on
+ *     open even for a first-time user. Opt in per product, and lower the
+ *     shell's `idleTimeoutSeconds` when you do.
+ *   - `shouldPrewarm(scope)` is the product's own policy hook (paid tier only,
+ *     returning user only, has-documents only …). Returning false costs nothing.
+ *   - `failureCooldownMs` stops a hard-failing workspace from retry-storming;
+ *     every retry is another create attempt, which is more spend.
+ * Warm with the SAME harness the next turn will use. `ensureWorkspaceSandbox`
+ * DELETES and recreates a name-matched box whose harness differs, so warming
+ * `opencode` and then turning `claude-code` pays for two boxes and is slower
+ * than not warming at all. The prewarm key includes the harness so the two are
+ * never deduped into one.
+ *
+ * ── SINGLE-FLIGHT (measured, not assumed) ──────────────────────────────────
+ * The sandbox platform does NOT dedupe by box name. Two concurrent
+ * `POST /v1/sandboxes` with an identical name both returned HTTP 201 and left
+ * two running boxes (verified against staging-sandbox, 2026-07-28). So two
+ * tabs, or two isolates, racing a warm genuinely leak a box — a prewarm that
+ * races is worse than no prewarm. Hence two layers:
+ *   1. an in-process map, which is free and catches same-isolate races
+ *      (double-mount, two requests on one isolate);
+ *   2. a `claim` store the product supplies, which is the only thing that can
+ *      make this correct ACROSS isolates — the usual deployment target here is
+ *      Cloudflare Workers, where "same isolate" guarantees nothing.
+ * `claim` is REQUIRED, with `'single-isolate-only'` as the explicit opt-out,
+ * so nobody gets the unsafe behaviour by forgetting a field. Say it out loud
+ * or supply a store.
+ *
+ * ── FAILURE IS LOUD, NEVER FATAL ───────────────────────────────────────────
+ * A failed warm degrades to exactly today's lazy path: the next real request
+ * calls `ensureWorkspaceSandbox` itself. It never throws into the caller's
+ * render path — `completion` RESOLVES with `{ ok: false }` rather than
+ * rejecting, because an unhandled rejection handed to `waitUntil` can fail the
+ * request it rode in on. But it is never silent: every failure fires
+ * `onEvent({ type: 'failed' })` and is readable afterwards through
+ * `readiness()` as `{ status: 'failed' }`. The bug class this whole module
+ * exists to kill is a soft failure that surfaces as an unusable panel ten
+ * minutes later, so a warm that dies must leave a trace a product can render.
+ */
+
+/** The workspace a warm targets. Mirrors `EnsureWorkspaceSandboxOptions`'
+ *  identity fields — the prewarmer forwards them verbatim so a warmed box is
+ *  byte-identical to the one the lazy path would have built. */
+interface SandboxPrewarmScope {
+    workspaceId: string;
+    userId?: string;
+    /** Must match the harness the next turn will use — see the cost note above. */
+    harness: Harness;
+    billingOwnerId?: string;
+}
+/**
+ * Cross-isolate claim. `acquire` must be atomic (a D1 conditional insert, a DO,
+ * a KV `put` with `onlyIf`) — a read-then-write is exactly the race this exists
+ * to close. `ttlSeconds` bounds a claim leaked by an isolate that died
+ * mid-warm; without expiry a single crash wedges a workspace forever.
+ */
+interface PrewarmClaimStore {
+    /** True when THIS caller now owns the right to warm `key`. */
+    acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    /** Best-effort release. A throw here is swallowed — the TTL is the backstop. */
+    release(key: string): Promise<void>;
+    /** Optional: lets `readiness()` report `warming` for a warm running in
+     *  ANOTHER isolate. Without it, `warming` is only visible in the isolate
+     *  that started it, and every other one reports `absent`. */
+    isHeld?(key: string): Promise<boolean>;
+}
+/** What `prewarm()` decided. Every value except `started` means no box was
+ *  created and nothing was spent on this call. */
+type PrewarmOutcome = 'started' | 'already-running' | 'already-warming' | 'warming-elsewhere' | 'declined-by-policy' | 'cooling-down' | 'absent-and-resume-only';
+/** Terminal result of a warm this caller owns. Never a rejection. */
+interface PrewarmResult {
+    ok: boolean;
+    boxId?: string;
+    error?: string;
+    /** Wall time of the warm itself, for the product's own timing trace. */
+    ms: number;
+}
+interface PrewarmDecision {
+    outcome: PrewarmOutcome;
+    /** Present ONLY when `outcome === 'started'`. Hand it to `ctx.waitUntil` so a
+     *  client disconnect cannot kill the warm. Never rejects. */
+    completion?: Promise<PrewarmResult>;
+}
+/** Readiness for the UI. `ready`/`warming` reuse the vocabulary
+ *  `createSandboxFileIndexRoute` (`/chat-routes`) and `useFileMentions`
+ *  (`/web-react`) already speak, so a product renders ONE warming state rather
+ *  than inventing a second spinner for boxes. */
+type SandboxReadiness = {
+    status: 'ready';
+    boxId: string;
+} | {
+    status: 'warming';
+} | {
+    status: 'absent';
+} | {
+    status: 'failed';
+    error: string;
+    retryAfterMs: number;
+};
+type PrewarmEvent = {
+    type: 'started';
+    key: string;
+    workspaceId: string;
+} | {
+    type: 'succeeded';
+    key: string;
+    workspaceId: string;
+    boxId: string;
+    ms: number;
+} | {
+    type: 'failed';
+    key: string;
+    workspaceId: string;
+    error: string;
+    ms: number;
+} | {
+    type: 'skipped';
+    key: string;
+    workspaceId: string;
+    outcome: PrewarmOutcome;
+};
+interface SandboxPrewarmerOptions {
+    /** Cross-isolate single-flight, or the explicit acknowledgement that you are
+     *  accepting per-isolate dedupe only. No default — see the header. */
+    claim: PrewarmClaimStore | 'single-isolate-only';
+    /** `'resume-only'` (default) never creates a box that does not exist.
+     *  `'create-or-resume'` warms from nothing — the expensive one. */
+    mode?: 'resume-only' | 'create-or-resume';
+    /** Product policy gate. Not called when a box is already running. */
+    shouldPrewarm?(scope: SandboxPrewarmScope): boolean | Promise<boolean>;
+    /** Observability seam. A failed warm MUST be visible somewhere. */
+    onEvent?(event: PrewarmEvent): void;
+    /** Claim lifetime. Default 180 s — comfortably over a cold create. */
+    claimTtlSeconds?: number;
+    /** Suppress re-warming a workspace that just failed. Default 60_000 ms. */
+    failureCooldownMs?: number;
+    /** Clock seam for tests. */
+    now?(): number;
+}
+interface SandboxPrewarmer {
+    /**
+     * Non-blocking warm. The returned promise settles as soon as the DECISION is
+     * known (at most one `list()` against the platform, plus a claim `acquire`);
+     * the provisioning itself rides on `completion`. On a render path either
+     * ignore the returned promise or run the whole call inside `waitUntil` — do
+     * not await `completion` before responding.
+     */
+    prewarm(scope: SandboxPrewarmScope): Promise<PrewarmDecision>;
+    /** Zero-provisioning status read for a UI. Never creates or resumes. */
+    readiness(scope: SandboxPrewarmScope): Promise<SandboxReadiness>;
+    /** Clear a recorded failure so the next `prewarm` retries immediately. */
+    clearFailure(scope: SandboxPrewarmScope): void;
+}
+declare function createSandboxPrewarmer(shell: SandboxRuntimeConfig, options: SandboxPrewarmerOptions): SandboxPrewarmer;
+
 /** Define client credentials for accessing the sandbox environment with API key and base URL */
 interface SandboxClientCredentials {
     apiKey: string;
@@ -976,4 +1228,4 @@ declare function isTerminalPromptEvent(event: unknown): boolean;
 /** Resolve the interactive question text from a structured event or return null if none found */
 declare function detectInteractiveQuestion(event: unknown): string | null;
 
-export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, type DriveSandboxTurnOptions, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type ModelSelection, type ModelSelectionError, type ModelSelectionFailure, type ModelSelectionSource, type Outcome, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxExecChannel, type SandboxExecOptions, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, SandboxModelResolutionError, type SandboxPermissionLevel, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };
+export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, type DriveSandboxTurnOptions, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type ModelSelection, type ModelSelectionError, type ModelSelectionFailure, type ModelSelectionSource, type Outcome, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, type PrewarmClaimStore, type PrewarmDecision, type PrewarmEvent, type PrewarmOutcome, type PrewarmResult, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxExecChannel, type SandboxExecOptions, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, SandboxModelResolutionError, type SandboxPermissionLevel, type SandboxPrewarmScope, type SandboxPrewarmer, type SandboxPrewarmerOptions, type SandboxReadiness, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type TerminalUpgradeResponseLike, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createSandboxPrewarmer, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxSidecarProxyUrl, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, selectedBearerSubprotocol, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, terminalUpgradeSubprotocolEcho, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };

package/dist/sandbox/index.js

@@ -17,6 +17,7 @@ import {
   buildSandboxToolPathSetupScript,
   classifySeveredStream,
   collectSandboxPromptText,
+  createSandboxPrewarmer,
   createSandboxTerminalToken,
   createWorkspaceSandboxConnectionHandler,
   createWorkspaceSandboxManager,
@@ -47,10 +48,12 @@ import {
   resolveSandboxClientCredentials,
   runSandboxPrompt,
   runSandboxToolPathSetup,
+  sandboxSidecarProxyUrl,
   sandboxToolBinDir,
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
+  selectedBearerSubprotocol,
   shellQuote,
   splitDeferredProfileFiles,
   statSandboxFileSize,
@@ -60,10 +63,11 @@ import {
   syncSandboxMemberRemove,
   syncSandboxMemberRole,
   terminalTokenFromRequest,
+  terminalUpgradeSubprotocolEcho,
   verifySandboxTerminalToken,
   verifyTerminalProxyToken,
   writeProfileFilesToBox
-} from "../chunk-7775L5NN.js";
+} from "../chunk-BAC2B2KI.js";
 import "../chunk-LWSJK546.js";
 import "../chunk-CQZSAR77.js";
 import "../chunk-ICOHEZK6.js";
@@ -90,6 +94,7 @@ export {
   buildSandboxToolPathSetupScript,
   classifySeveredStream,
   collectSandboxPromptText,
+  createSandboxPrewarmer,
   createSandboxTerminalToken,
   createWorkspaceSandboxConnectionHandler,
   createWorkspaceSandboxManager,
@@ -120,10 +125,12 @@ export {
   resolveSandboxClientCredentials,
   runSandboxPrompt,
   runSandboxToolPathSetup,
+  sandboxSidecarProxyUrl,
   sandboxToolBinDir,
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
+  selectedBearerSubprotocol,
   shellQuote,
   splitDeferredProfileFiles,
   statSandboxFileSize,
@@ -133,6 +140,7 @@ export {
   syncSandboxMemberRemove,
   syncSandboxMemberRole,
   terminalTokenFromRequest,
+  terminalUpgradeSubprotocolEcho,
   verifySandboxTerminalToken,
   verifyTerminalProxyToken,
   writeProfileFilesToBox

package/dist/sequences/index.d.ts

@@ -1,10 +1,10 @@
 import { j as SequenceMediaKind, f as SequenceTimeline, k as TimelineInterval, b as SequenceStore } from '../store-B7LLlk9p.js';
 export { M as MIN_SEQUENCE_CLIP_FRAMES, N as NewSequenceClip, l as NewSequenceDecision, m as NewSequenceTrack, g as SequenceClip, a as SequenceClipMedia, n as SequenceClipPatch, o as SequenceDecision, d as SequenceExportFormat, h as SequenceExportRecord, p as SequenceExportStatus, q as SequenceFrameSnapshot, i as SequenceMeta, r as SequenceStatus, S as SequenceStoreScope, e as SequenceTrack, c as SequenceTrackKind, T as TimelineClipBounds, s as assertClipFitsSequence, t as chooseCaptionPlacement, u as clampClipDuration, v as clampClipStart, w as formatSeconds, x as formatTimecode, y as framesToSeconds, z as secondsToFrames, A as snapshotFrame, B as trackIntervals } from '../store-B7LLlk9p.js';
 export { A as AddCaptionOperation, C as CaptionTargetResolution, a as CreateTrackOperation, D as DeleteClipOperation, E as ExtendSequenceOperation, M as MoveClipOperation, P as PlaceClipOperation, Q as QueueExportOperation, S as SEQUENCE_OPERATION_TYPES, b as SequenceApplyResult, c as SequenceOperation, d as SequenceOperationContext, e as SequenceOperationType, f as SequencePlan, g as SetClipDisabledOperation, h as SetClipTextOperation, i as SplitClipOperation, T as TrimClipOperation, j as applySequenceOperation, k as applySequenceOperations, l as assertSequenceMediaUrl, m as captionTrackNameForLanguage, n as lastClipEndFrame, p as parseSequenceOperations, r as resolveCaptionPlacement, o as resolveCaptionTarget, q as resolvePlaceClipTrack, v as validateAddCaption, s as validateCreateTrack, t as validateDeleteClip, u as validateExtendSequence, w as validateMoveClip, x as validatePlaceClip, y as validateQueueExport, z as validateSequenceOperation, B as validateSequenceOperations, F as validateSetClipDisabled, G as validateSetClipText, H as validateSplitClip, I as validateTrimClip } from '../apply-6wlMOLf8.js';
-import { S as ScopedMcpServerEntryOptions, A as AppToolMcpServer } from '../mcp-D3qVzbE1.js';
+import { S as ScopedMcpServerEntryOptions, A as AppToolMcpServer } from '../mcp-Dt4V4ZLT.js';
 export { M as SEQUENCES_MCP_PROTOCOL_VERSIONS } from '../mcp-rpc-CzU5LWWT.js';
-import '../types-BCxK0wyS.js';
-import '../auth-anc7mv2W.js';
+import '../types-DbU-oO5h.js';
+import '../auth-DJs6lfAs.js';
 
 /**
  * Pure interchange-format builders over `SequenceTimeline` — SRT, WebVTT,