@zhixuan92/multi-model-agent-core 0.1.1 → 0.3.0

package/dist/tools/scratchpad.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TextScratchpad — accumulates assistant text emissions across turns of a
+ * sub-agent run. The runner appends text from each turn so that, on any
+ * termination (clean exit, abort, timeout, error), the salvage layer can
+ * return the best buffered text instead of an empty string.
+ *
+ * See docs/superpowers/specs/2026-04-10-subagent-completion-supervision-design.md
+ * Part A.2.1 for the design rationale.
+ */
+export declare class TextScratchpad {
+    private turns;
+    /** Record a non-empty text emission for the given turn. Empty/whitespace
+     *  emissions are ignored — they have no salvage value. */
+    append(turn: number, text: string): void;
+    isEmpty(): boolean;
+    /** All buffered text concatenated, in turn order, separated by a fixed
+     *  delimiter. Used as the salvage payload when no clean final answer
+     *  was produced. */
+    toString(): string;
+    /** The most recent buffered emission. Empty string if isEmpty(). */
+    latest(): string;
+    /** The longest buffered emission across all turns. Empty string if
+     *  isEmpty(). Used by the escalation layer to pick the best salvageable
+     *  result across multiple provider attempts. */
+    longest(): string;
+    reset(): void;
+}
+//# sourceMappingURL=scratchpad.d.ts.map

package/dist/tools/scratchpad.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratchpad.d.ts","sourceRoot":"","sources":["../../src/tools/scratchpad.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAwC;IAErD;8DAC0D;IAC1D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxC,OAAO,IAAI,OAAO;IAIlB;;wBAEoB;IACpB,QAAQ,IAAI,MAAM;IAIlB,oEAAoE;IACpE,MAAM,IAAI,MAAM;IAIhB;;oDAEgD;IAChD,OAAO,IAAI,MAAM;IASjB,KAAK,IAAI,IAAI;CAGd"}

package/dist/tools/scratchpad.js

@@ -0,0 +1,49 @@
+/**
+ * TextScratchpad — accumulates assistant text emissions across turns of a
+ * sub-agent run. The runner appends text from each turn so that, on any
+ * termination (clean exit, abort, timeout, error), the salvage layer can
+ * return the best buffered text instead of an empty string.
+ *
+ * See docs/superpowers/specs/2026-04-10-subagent-completion-supervision-design.md
+ * Part A.2.1 for the design rationale.
+ */
+export class TextScratchpad {
+    turns = [];
+    /** Record a non-empty text emission for the given turn. Empty/whitespace
+     *  emissions are ignored — they have no salvage value. */
+    append(turn, text) {
+        if (!text || text.trim().length === 0)
+            return;
+        this.turns.push({ turn, text });
+    }
+    isEmpty() {
+        return this.turns.length === 0;
+    }
+    /** All buffered text concatenated, in turn order, separated by a fixed
+     *  delimiter. Used as the salvage payload when no clean final answer
+     *  was produced. */
+    toString() {
+        return this.turns.map((t) => t.text).join('\n\n---\n\n');
+    }
+    /** The most recent buffered emission. Empty string if isEmpty(). */
+    latest() {
+        return this.turns.length === 0 ? '' : this.turns[this.turns.length - 1].text;
+    }
+    /** The longest buffered emission across all turns. Empty string if
+     *  isEmpty(). Used by the escalation layer to pick the best salvageable
+     *  result across multiple provider attempts. */
+    longest() {
+        if (this.turns.length === 0)
+            return '';
+        let best = this.turns[0].text;
+        for (const t of this.turns) {
+            if (t.text.length > best.length)
+                best = t.text;
+        }
+        return best;
+    }
+    reset() {
+        this.turns = [];
+    }
+}
+//# sourceMappingURL=scratchpad.js.map

package/dist/tools/scratchpad.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratchpad.js","sourceRoot":"","sources":["../../src/tools/scratchpad.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAc;IACjB,KAAK,GAAqC,EAAE,CAAC;IAErD;8DAC0D;IAC1D,MAAM,CAAC,IAAY,EAAE,IAAY;QAC/B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC9C,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;IACjC,CAAC;IAED;;wBAEoB;IACpB,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC3D,CAAC;IAED,oEAAoE;IACpE,MAAM;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/E,CAAC;IAED;;oDAEgD;IAChD,OAAO;QACL,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACvC,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC3B,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM;gBAAE,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QACjD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;CACF"}

package/dist/tools/tracker.d.ts

@@ -1,7 +1,47 @@
+/**
+ * Tracks file accesses and tool invocations inside a sub-agent run so the
+ * runner can report what the worker actually did. Reads, writes, and tool
+ * calls are stored separately because they answer different questions for
+ * the caller:
+ *
+ *   - filesRead    → "what did the worker look at?" (debugging, audit trail)
+ *   - directoriesListed → "which directories were enumerated?" (exploration)
+ *   - filesWritten → "what changed on disk?"        (review, rollback)
+ *   - toolCalls    → "what did the worker actually do, in order?"
+ *                                                   (debugging, post-mortem)
+ *
+ * Read-only tasks (audits, surveys, exploration) used to return an empty
+ * `files` array because the original tracker only recorded writes. That made
+ * it impossible to tell whether the worker had done substantial work or had
+ * bailed out immediately.
+ */
 export declare class FileTracker {
-    private files;
+    private reads;
+    private dirs;
+    private writes;
+    private toolCalls;
+    private readonly onToolCall?;
+    /**
+     * @param onToolCall Optional callback invoked synchronously after every
+     *   `trackToolCall(...)`. Used by runners (Task 9+) to stream tool
+     *   invocations out as `ProgressEvent`s in real time. The callback must
+     *   not throw; the runner wraps it in `safeSink` before passing it in.
+     */
+    constructor(onToolCall?: (summary: string) => void);
+    trackRead(filePath: string): void;
+    trackDirectoryList(dirPath: string): void;
     trackWrite(filePath: string): void;
-    getFiles(): string[];
+    /**
+     * Record a one-line summary of a tool invocation. Order is preserved so
+     * the caller can reconstruct what the worker actually did. If an
+     * `onToolCall` callback was supplied at construction, it is fired
+     * synchronously after the summary is recorded.
+     */
+    trackToolCall(summary: string): void;
+    getReads(): string[];
+    getDirectoriesListed(): string[];
+    getWrites(): string[];
+    getToolCalls(): string[];
     reset(): void;
 }
 //# sourceMappingURL=tracker.d.ts.map

package/dist/tools/tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/tools/tracker.ts"],"names":[],"mappings":"AAAA,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAqB;IAElC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIlC,QAAQ,IAAI,MAAM,EAAE;IAIpB,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/tools/tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA4B;IAExD;;;;;OAKG;gBACS,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;IAIlD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIjC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIzC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIlC;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKpC,QAAQ,IAAI,MAAM,EAAE;IAIpB,oBAAoB,IAAI,MAAM,EAAE;IAIhC,SAAS,IAAI,MAAM,EAAE;IAIrB,YAAY,IAAI,MAAM,EAAE;IAIxB,KAAK,IAAI,IAAI;CAMd"}

package/dist/tools/tracker.js

@@ -1,13 +1,71 @@
+/**
+ * Tracks file accesses and tool invocations inside a sub-agent run so the
+ * runner can report what the worker actually did. Reads, writes, and tool
+ * calls are stored separately because they answer different questions for
+ * the caller:
+ *
+ *   - filesRead    → "what did the worker look at?" (debugging, audit trail)
+ *   - directoriesListed → "which directories were enumerated?" (exploration)
+ *   - filesWritten → "what changed on disk?"        (review, rollback)
+ *   - toolCalls    → "what did the worker actually do, in order?"
+ *                                                   (debugging, post-mortem)
+ *
+ * Read-only tasks (audits, surveys, exploration) used to return an empty
+ * `files` array because the original tracker only recorded writes. That made
+ * it impossible to tell whether the worker had done substantial work or had
+ * bailed out immediately.
+ */
 export class FileTracker {
-    files = new Set();
+    reads = new Set();
+    dirs = [];
+    writes = new Set();
+    toolCalls = [];
+    onToolCall;
+    /**
+     * @param onToolCall Optional callback invoked synchronously after every
+     *   `trackToolCall(...)`. Used by runners (Task 9+) to stream tool
+     *   invocations out as `ProgressEvent`s in real time. The callback must
+     *   not throw; the runner wraps it in `safeSink` before passing it in.
+     */
+    constructor(onToolCall) {
+        this.onToolCall = onToolCall;
+    }
+    trackRead(filePath) {
+        this.reads.add(filePath);
+    }
+    trackDirectoryList(dirPath) {
+        this.dirs.push(dirPath);
+    }
     trackWrite(filePath) {
-        this.files.add(filePath);
+        this.writes.add(filePath);
+    }
+    /**
+     * Record a one-line summary of a tool invocation. Order is preserved so
+     * the caller can reconstruct what the worker actually did. If an
+     * `onToolCall` callback was supplied at construction, it is fired
+     * synchronously after the summary is recorded.
+     */
+    trackToolCall(summary) {
+        this.toolCalls.push(summary);
+        this.onToolCall?.(summary);
+    }
+    getReads() {
+        return [...this.reads].sort();
+    }
+    getDirectoriesListed() {
+        return [...this.dirs];
+    }
+    getWrites() {
+        return [...this.writes].sort();
     }
-    getFiles() {
-        return [...this.files].sort();
+    getToolCalls() {
+        return [...this.toolCalls];
     }
     reset() {
-        this.files.clear();
+        this.reads.clear();
+        this.dirs = [];
+        this.writes.clear();
+        this.toolCalls = [];
     }
 }
 //# sourceMappingURL=tracker.js.map

package/dist/tools/tracker.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../src/tools/tracker.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,WAAW;IACd,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,UAAU,CAAC,QAAgB;QACzB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;IAED,QAAQ;QACN,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../src/tools/tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,WAAW;IACd,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1B,IAAI,GAAa,EAAE,CAAC;IACpB,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IAC3B,SAAS,GAAa,EAAE,CAAC;IAChB,UAAU,CAA6B;IAExD;;;;;OAKG;IACH,YAAY,UAAsC;QAChD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,SAAS,CAAC,QAAgB;QACxB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;IAED,kBAAkB,CAAC,OAAe;QAChC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,UAAU,CAAC,QAAgB;QACzB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,OAAe;QAC3B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAED,QAAQ;QACN,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,CAAC;IAED,oBAAoB;QAClB,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,CAAC;IAED,YAAY;QACV,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QACf,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;CACF"}

package/dist/types.d.ts

@@ -1,10 +1,11 @@
+import type { ContextBlockStore } from './context/context-block-store.js';
 export type Tier = 'trivial' | 'standard' | 'reasoning';
 export type Capability = 'file_read' | 'file_write' | 'grep' | 'glob' | 'shell' | 'web_search' | 'web_fetch';
 export type ToolMode = 'none' | 'full';
 export type SandboxPolicy = 'none' | 'cwd-only';
 export type Effort = 'none' | 'low' | 'medium' | 'high';
 export type CostTier = 'free' | 'low' | 'medium' | 'high';
-export type RunStatus = 'ok' | 'error' | 'timeout' | 'max_turns';
+export type RunStatus = 'ok' | 'incomplete' | 'max_turns' | 'timeout' | 'api_aborted' | 'api_error' | 'network_error' | 'error';
 export interface TaskSpec {
     prompt: string;
     /** Provider name. If omitted, core auto-selects. */
@@ -17,6 +18,27 @@ export interface TaskSpec {
     cwd?: string;
     effort?: Effort;
     sandboxPolicy?: SandboxPolicy;
+    /** Optional context block ids to expand into the prompt before dispatch.
+     *  Each id is resolved against `RunTasksRuntime.contextBlockStore` in
+     *  order and its content is prepended to `prompt` separated by
+     *  '\n\n---\n\n'. The field is stripped from the task that reaches the
+     *  provider so runners never see it. See `expandContextBlocks`. */
+    contextBlockIds?: string[];
+    /** Optional caller-declared output expectations. When supplied, the
+     *  supervision layer can validate the output for enumerable deliverables
+     *  after syntactic completion checks pass. */
+    expectedCoverage?: {
+        /** Minimum section count. A section is a line matching `sectionPattern`. */
+        minSections?: number;
+        /** Regex for section headings. Applied with the multiline flag. */
+        sectionPattern?: string;
+        /** Substrings that must all appear somewhere in the output. */
+        requiredMarkers?: string[];
+    };
+    /** Opt-in progress capture for post-hoc execution observability. */
+    includeProgressTrace?: boolean;
+    /** Optional hint about the parent session's model for saved-cost estimates. */
+    parentModel?: string;
 }
 export interface CodexProviderConfig {
     type: 'codex';
@@ -27,6 +49,14 @@ export interface CodexProviderConfig {
     sandboxPolicy?: SandboxPolicy;
     hostedTools?: ('web_search' | 'image_generation' | 'code_interpreter')[];
     costTier?: CostTier;
+    /** Optional pricing in USD per million input tokens. Used to compute RunResult.usage.costUSD. */
+    inputCostPerMTok?: number;
+    /** Optional pricing in USD per million output tokens. Used to compute RunResult.usage.costUSD. */
+    outputCostPerMTok?: number;
+    /** Optional override for the per-provider input token soft limit
+     *  used by the watchdog. When unset, falls back to the model profile
+     *  default, then to a hardcoded 100_000 fallback. See spec A.1.4. */
+    inputTokenSoftLimit?: number;
 }
 export interface ClaudeProviderConfig {
     type: 'claude';
@@ -37,6 +67,13 @@ export interface ClaudeProviderConfig {
     sandboxPolicy?: SandboxPolicy;
     hostedTools?: ('web_search' | 'image_generation' | 'code_interpreter')[];
     costTier?: CostTier;
+    /** Optional pricing override; if set, recomputes costUSD from token usage instead of trusting the SDK. */
+    inputCostPerMTok?: number;
+    outputCostPerMTok?: number;
+    /** Optional override for the per-provider input token soft limit
+     *  used by the watchdog. When unset, falls back to the model profile
+     *  default, then to a hardcoded 100_000 fallback. See spec A.1.4. */
+    inputTokenSoftLimit?: number;
 }
 export interface OpenAICompatibleProviderConfig {
     type: 'openai-compatible';
@@ -51,6 +88,14 @@ export interface OpenAICompatibleProviderConfig {
     sandboxPolicy?: SandboxPolicy;
     hostedTools?: ('web_search' | 'image_generation' | 'code_interpreter')[];
     costTier?: CostTier;
+    /** Optional pricing in USD per million input tokens. Used to compute RunResult.usage.costUSD. */
+    inputCostPerMTok?: number;
+    /** Optional pricing in USD per million output tokens. Used to compute RunResult.usage.costUSD. */
+    outputCostPerMTok?: number;
+    /** Optional override for the per-provider input token soft limit
+     *  used by the watchdog. When unset, falls back to the model profile
+     *  default, then to a hardcoded 100_000 fallback. See spec A.1.4. */
+    inputTokenSoftLimit?: number;
 }
 /** Discriminated union — each provider type has distinct required fields. */
 export type ProviderConfig = CodexProviderConfig | ClaudeProviderConfig | OpenAICompatibleProviderConfig;
@@ -60,6 +105,11 @@ export interface MultiModelConfig {
         maxTurns: number;
         timeoutMs: number;
         tools: ToolMode;
+        /** Character threshold that triggers auto-switch from 'full' to
+         *  'summary' response mode when the caller uses `responseMode: 'auto'`
+         *  (the default). Optional — defaults to 65_536 when absent.
+         *  Env var and buildMcpServer option can override at higher precedence. */
+        largeResponseThresholdChars?: number;
     };
 }
 export interface TokenUsage {
@@ -67,15 +117,115 @@ export interface TokenUsage {
     outputTokens: number;
     totalTokens: number;
     costUSD: number | null;
+    /** Estimated cost savings versus the declared parent model, if known. */
+    savedCostUSD?: number | null;
 }
 export interface RunResult {
     output: string;
     status: RunStatus;
     usage: TokenUsage;
     turns: number;
-    files: string[];
+    /** Files whose contents the worker read (via readFile/grep/listFiles). */
+    filesRead: string[];
+    /** Files the worker wrote (via writeFile). */
+    filesWritten: string[];
+    /** Compact one-line summaries of every tool the worker invoked, in order. */
+    toolCalls: string[];
+    /** `true` when `output` is a runner-synthesized diagnostic template
+     *  (`"Sub-agent error: …"`, `"Agent timed out after …"`, the incomplete
+     *  template from `buildXxxIncompleteDiagnostic`, etc.) because the
+     *  scratchpad was empty at termination. `false` when `output` contains
+     *  real model-produced content — either a clean final answer on the
+     *  `ok` path, or `scratchpad.latest()` on any salvage path where the
+     *  scratchpad had buffered text.
+     *
+     *  Used by the escalation orchestrator's all-fail fallback to prefer
+     *  real content over diagnostic templates regardless of status or
+     *  length (otherwise a long `"Sub-agent error: <stack trace>"` string
+     *  could beat a shorter genuine partial answer from an earlier
+     *  attempt). */
+    outputIsDiagnostic: boolean;
+    /** One entry per provider attempt within this dispatch. Length === 1
+     *  for tasks that succeeded on the first try; longer when escalation
+     *  occurred. Runners initialize this to `[]`; the escalation
+     *  orchestrator populates it on each return path. */
+    escalationLog: AttemptRecord[];
+    /** Wall-clock duration of this task in milliseconds. */
+    durationMs?: number;
+    /** Directories whose entries the worker listed. */
+    directoriesListed?: string[];
+    /** Bounded trace of progress events emitted during this task's run. */
+    progressTrace?: ProgressTraceEntry[];
     error?: string;
 }
+/** A captured progress entry, or a synthetic marker when trace trimming occurred. */
+export type ProgressTraceEntry = ProgressEvent | {
+    kind: '_trimmed';
+    droppedCount: number;
+    droppedKinds: Partial<Record<ProgressEvent['kind'], number>>;
+    capExceededByBoundaryEvents?: boolean;
+};
+/** Aggregate timing metrics for a `delegate_tasks` batch. */
+export interface BatchTimings {
+    wallClockMs: number;
+    sumOfTaskMs: number;
+    estimatedParallelSavingsMs: number;
+}
+/** Aggregate completion counts for a `delegate_tasks` batch. */
+export interface BatchProgress {
+    totalTasks: number;
+    completedTasks: number;
+    incompleteTasks: number;
+    failedTasks: number;
+    successPercent: number;
+}
+/** Aggregate cost metrics for a `delegate_tasks` batch. */
+export interface BatchAggregateCost {
+    totalActualCostUSD: number;
+    totalSavedCostUSD: number;
+    actualCostUnavailableTasks: number;
+    savedCostUnavailableTasks: number;
+}
+/**
+ * Single provider-attempt record inside an escalation chain. The orchestrator
+ * (`delegateWithEscalation`) pushes one entry per `provider.run(...)` call.
+ */
+export interface AttemptRecord {
+    provider: string;
+    status: RunStatus;
+    turns: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUSD: number | null;
+    /** Character count of the canonical orchestrator-side initial brief for
+     *  this attempt — the exact string
+     *  `${buildSystemPrompt()}\n\n${buildBudgetHint(...)}\n\n${prompt}`
+     *  (as assembled before any runner-specific wrapping). Populated by the
+     *  escalation orchestrator via the `RunOptions.onInitialRequest` callback
+     *  the runner invokes exactly once per attempt.
+     *
+     *  NOTE: This is a canonical identifier, NOT a wire-level checksum. The
+     *  provider's SDK may wrap or transform this string before sending (e.g.
+     *  the Anthropic SDK prepends its `claude_code` preset to the system
+     *  prompt via `{ type: 'preset', preset: 'claude_code', append: ... }`;
+     *  the OpenAI SDKs wrap it in a `messages` array). All three runners use
+     *  the same canonical form so the hash is cross-runner stable: identical
+     *  briefs produce identical hashes regardless of which runner executed
+     *  them. Use this to verify "did the orchestrator send the same brief
+     *  across retries?", not "were the literal bytes on the wire identical?".
+     *
+     *  Defaults to 0 if the runner never invoked the callback. */
+    initialPromptLengthChars: number;
+    /** sha256 hex of the canonical orchestrator-side initial brief. See the
+     *  comment on `initialPromptLengthChars` above for the exact hashed
+     *  string and the wire-level caveat. Defaults to the empty string if the
+     *  runner never invoked the callback. */
+    initialPromptHash: string;
+    /** Why this attempt was abandoned, if it was. Empty if status === 'ok'. */
+    reason?: string;
+    /** Bounded progress trace captured for this attempt, when enabled. */
+    progressTrace?: ProgressTraceEntry[];
+}
 export interface Provider {
     name: string;
     config: ProviderConfig;
@@ -88,7 +238,107 @@ export interface RunOptions {
     cwd?: string;
     effort?: Effort;
     sandboxPolicy?: SandboxPolicy;
+    /** Optional caller-declared output expectations. When supplied, the
+     *  supervision layer runs `validateCoverage` after `validateCompletion`'s
+     *  syntactic check passes, and re-prompts with specific missing-item
+     *  guidance if coverage is insufficient. Same 3-retry budget as other
+     *  degeneracy classes. Opt-in: callers who omit this field see zero
+     *  change in runner behavior. Generic across all workload shapes that
+     *  produce enumerable deliverables. */
+    expectedCoverage?: TaskSpec['expectedCoverage'];
+    /** Optional callback invoked by runners and the escalation orchestrator to
+     *  stream in-flight progress events. See `ProgressEvent` for the full set
+     *  of variants. Runners receive this via `provider.run(..., { onProgress })`
+     *  and call it synchronously from their loop; the callback MUST NOT throw
+     *  and should return quickly. Wired in Task 8 (interface + plumbing);
+     *  runners emit events in Tasks 9-11. */
+    onProgress?: (event: ProgressEvent) => void;
+    /** Called exactly once per attempt, when the runner has assembled the
+     *  canonical orchestrator-side initial brief — the string
+     *  `${buildSystemPrompt()}\n\n${buildBudgetHint(...)}\n\n${prompt}`,
+     *  after prevention scaffolding has been produced but before any tool
+     *  cycles, re-grounding, supervision, or watchdog injections happen.
+     *  The escalation orchestrator passes a closure here to capture the
+     *  metadata into the `AttemptRecord` it builds.
+     *
+     *  This is a canonical identifier, NOT a wire-level checksum: each
+     *  runner computes it from the same canonical string so the hash is
+     *  cross-runner stable, even though the SDK underneath may wrap the
+     *  inputs before sending (Claude prepends its `claude_code` preset to
+     *  the system prompt; OpenAI/Codex wrap inputs in structured message
+     *  arrays). See `AttemptRecord.initialPromptHash` for the full caveat.
+     *
+     *  If a runner is re-invoked by escalation, the callback fires again
+     *  for the new attempt because the orchestrator resets its per-attempt
+     *  closure. Passing nothing keeps existing behaviour (no-op). */
+    onInitialRequest?: (meta: {
+        lengthChars: number;
+        sha256: string;
+    }) => void;
+    /** Optional hint about the parent session's model for saved-cost estimates.
+     *  When supplied, `RunResult.usage.savedCostUSD` is computed against this
+     *  model's profile rates. */
+    parentModel?: string;
+    /** Opt-in: when true, the runner captures every progress event fired
+     *  during this task's execution into a bounded, priority-trimmed
+     *  `progressTrace` on the final RunResult. Useful for post-hoc
+     *  execution observability on long-running delegated tasks. Zero
+     *  cost when false (the default). */
+    includeProgressTrace?: boolean;
+}
+/**
+ * Runtime dependencies for `runTasks`. Kept separate from static `MultiModelConfig`
+ * because these are per-session objects (today: the context-block store) the
+ * caller owns and passes in explicitly, not config loaded from disk.
+ */
+export interface RunTasksRuntime {
+    /** Optional store of registered context blocks. When provided, each task's
+     *  `contextBlockIds` are resolved against this store before dispatch; when
+     *  omitted, tasks with `contextBlockIds` are passed through unchanged. */
+    contextBlockStore?: ContextBlockStore;
 }
+/**
+ * In-flight progress signal emitted by runners and the escalation
+ * orchestrator. Consumers (today: the MCP cli bridge) translate these into
+ * transport-level notifications so callers can observe a sub-agent's work
+ * without polling. One `ProgressEvent` per meaningful state transition.
+ *
+ * Variants mirror spec Part B.1. Runner emission lives in Tasks 9-11; the
+ * escalation `escalation_start` hop is emitted by `delegateWithEscalation`
+ * itself in Task 8.
+ */
+export type ProgressEvent = {
+    kind: 'turn_start';
+    turn: number;
+    provider: string;
+} | {
+    kind: 'tool_call';
+    turn: number;
+    toolSummary: string;
+} | {
+    kind: 'text_emission';
+    turn: number;
+    chars: number;
+    preview: string;
+} | {
+    kind: 'turn_complete';
+    turn: number;
+    cumulativeInputTokens: number;
+    cumulativeOutputTokens: number;
+} | {
+    kind: 'injection';
+    injectionType: 'reground' | 'supervise_empty' | 'supervise_thinking' | 'supervise_fragment' | 'supervise_insufficient_coverage' | 'watchdog_warning' | 'watchdog_force_salvage';
+    turn: number;
+    contentLengthChars: number;
+} | {
+    kind: 'escalation_start';
+    previousProvider: string;
+    previousReason: string;
+    nextProvider: string;
+} | {
+    kind: 'done';
+    status: RunStatus;
+};
 export type EligibilityFailureCheck = 'capability' | 'tier' | 'tool_mode' | 'provider_not_found' | 'unsupported_provider_type' | 'missing_required_field' | string;
 export interface EligibilityFailure {
     check: EligibilityFailureCheck;
@@ -102,5 +352,14 @@ export interface ProviderEligibility {
     /** Reasons only present when eligible === false. */
     reasons: EligibilityFailure[];
 }
+/**
+ * Compute USD cost from token usage and the provider config's optional
+ * per-million-token rates. Returns null when either rate is missing — that
+ * way the caller can distinguish "we know the cost is zero" (free provider
+ * with both rates set to 0) from "we don't know the cost" (rates not
+ * configured). Negative or non-finite rates are treated as missing.
+ */
+export declare function computeCostUSD(inputTokens: number, outputTokens: number, config: ProviderConfig): number | null;
+export declare function computeSavedCostUSD(actualCostUSD: number | null, inputTokens: number, outputTokens: number, parentModel: string | undefined): number | null;
 export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, onTimeout: () => T, abort?: AbortController): Promise<T>;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAK1E,MAAM,MAAM,IAAI,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;AACxD,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,YAAY,GAAG,WAAW,CAAC;AAC7G,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AACvC,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,UAAU,CAAC;AAChD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AACxD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAC1D,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,YAAY,GACZ,WAAW,GACX,SAAS,GACT,aAAa,GACb,WAAW,GACX,eAAe,GACf,OAAO,CAAC;AAIZ,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,IAAI,CAAA;IACV,oBAAoB,EAAE,UAAU,EAAE,CAAA;IAClC,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;uEAImE;IACnE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B;;kDAE8C;IAC9C,gBAAgB,CAAC,EAAE;QACjB,4EAA4E;QAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,mEAAmE;QACnE,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,+DAA+D;QAC/D,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;KAC3B,CAAA;IACD,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAID,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,WAAW,CAAC,EAAE,CAAC,YAAY,GAAG,kBAAkB,GAAG,kBAAkB,CAAC,EAAE,CAAA;IACxE,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kGAAkG;IAClG,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;yEAEqE;IACrE,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,QAAQ,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,WAAW,CAAC,EAAE,CAAC,YAAY,GAAG,kBAAkB,GAAG,kBAAkB,CAAC,EAAE,CAAA;IACxE,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,0GAA0G;IAC1G,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;yEAEqE;IACrE,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,mBAAmB,CAAA;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,WAAW,CAAC,EAAE,CAAC,YAAY,GAAG,kBAAkB,GAAG,kBAAkB,CAAC,EAAE,CAAA;IACxE,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kGAAkG;IAClG,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;yEAEqE;IACrE,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GACtB,mBAAmB,GACnB,oBAAoB,GACpB,8BAA8B,CAAA;AAIlC,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IACzC,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE,QAAQ,CAAA;QACf;;;mFAG2E;QAC3E,2BAA2B,CAAC,EAAE,MAAM,CAAA;KACrC,CAAA;CACF;AAID,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,SAAS,CAAA;IACjB,KAAK,EAAE,UAAU,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB;;;;;;;;;;;;oBAYgB;IAChB,kBAAkB,EAAE,OAAO,CAAA;IAC3B;;;yDAGqD;IACrD,aAAa,EAAE,aAAa,EAAE,CAAA;IAC9B,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,uEAAuE;IACvE,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAA;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,qFAAqF;AACrF,MAAM,MAAM,kBAAkB,GAC1B,aAAa,GACb;IACE,IAAI,EAAE,UAAU,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5D,2BAA2B,CAAC,EAAE,OAAO,CAAA;CACtC,CAAA;AAEL,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,0BAA0B,EAAE,MAAM,CAAA;CACnC;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,EAAE,MAAM,CAAA;IACvB,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAA;IAC1B,iBAAiB,EAAE,MAAM,CAAA;IACzB,0BAA0B,EAAE,MAAM,CAAA;IAClC,yBAAyB,EAAE,MAAM,CAAA;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,SAAS,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;;;;;;;;;;;;;;;;kEAiB8D;IAC9D,wBAAwB,EAAE,MAAM,CAAA;IAChC;;;6CAGyC;IACzC,iBAAiB,EAAE,MAAM,CAAA;IACzB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAA;CACrC;AAID,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,cAAc,CAAA;IACtB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;CAC9D;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;;;2CAMuC;IACvC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAA;IAC/C;;;;;6CAKyC;IACzC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IAC3C;;;;;;;;;;;;;;;;;qEAiBiE;IACjE,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IAC1E;;iCAE6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;yCAIqC;IACrC,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;8EAE0E;IAC1E,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;CACtC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvE;IACE,IAAI,EAAE,eAAe,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,qBAAqB,EAAE,MAAM,CAAA;IAC7B,sBAAsB,EAAE,MAAM,CAAA;CAC/B,GACD;IACE,IAAI,EAAE,WAAW,CAAA;IACjB,aAAa,EACT,UAAU,GACV,iBAAiB,GACjB,oBAAoB,GACpB,oBAAoB,GACpB,iCAAiC,GACjC,kBAAkB,GAClB,wBAAwB,CAAA;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,kBAAkB,EAAE,MAAM,CAAA;CAC3B,GACD;IACE,IAAI,EAAE,kBAAkB,CAAA;IACxB,gBAAgB,EAAE,MAAM,CAAA;IACxB,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;CACrB,GACD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAA;AAIvC,MAAM,MAAM,uBAAuB,GAC/B,YAAY,GACZ,MAAM,GACN,WAAW,GACX,oBAAoB,GACpB,2BAA2B,GAC3B,wBAAwB,GACxB,MAAM,CAAA;AAEV,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,uBAAuB,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,cAAc,CAAA;IACtB,QAAQ,EAAE,OAAO,CAAA;IACjB,oDAAoD;IACpD,OAAO,EAAE,kBAAkB,EAAE,CAAA;CAC9B;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,cAAc,GACrB,MAAM,GAAG,IAAI,CAaf;AAED,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,GAAG,IAAI,CAcf;AAmBD,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,CAAC,EAClB,KAAK,CAAC,EAAE,eAAe,GACtB,OAAO,CAAC,CAAC,CAAC,CAmBZ"}

package/dist/types.js

@@ -1,5 +1,47 @@
-// === Tier & Capability ===
+import { findModelProfile } from './routing/model-profiles.js';
 // === Utilities ===
+/**
+ * Compute USD cost from token usage and the provider config's optional
+ * per-million-token rates. Returns null when either rate is missing — that
+ * way the caller can distinguish "we know the cost is zero" (free provider
+ * with both rates set to 0) from "we don't know the cost" (rates not
+ * configured). Negative or non-finite rates are treated as missing.
+ */
+export function computeCostUSD(inputTokens, outputTokens, config) {
+    const explicitRates = resolveRatePair(config.inputCostPerMTok, config.outputCostPerMTok);
+    if (explicitRates !== null) {
+        return (inputTokens * explicitRates.input + outputTokens * explicitRates.output) / 1_000_000;
+    }
+    const profile = findModelProfile(config.model);
+    const profileRates = resolveRatePair(profile.inputCostPerMTok, profile.outputCostPerMTok);
+    if (profileRates === null) {
+        return null;
+    }
+    return (inputTokens * profileRates.input + outputTokens * profileRates.output) / 1_000_000;
+}
+export function computeSavedCostUSD(actualCostUSD, inputTokens, outputTokens, parentModel) {
+    if (actualCostUSD === null || parentModel === undefined) {
+        return null;
+    }
+    const profile = findModelProfile(parentModel);
+    const profileRates = resolveRatePair(profile.inputCostPerMTok, profile.outputCostPerMTok);
+    if (profileRates === null) {
+        return null;
+    }
+    const hypotheticalParentCostUSD = (inputTokens * profileRates.input + outputTokens * profileRates.output) / 1_000_000;
+    return hypotheticalParentCostUSD - actualCostUSD;
+}
+function resolveRatePair(inputCostPerMTok, outputCostPerMTok) {
+    if (inputCostPerMTok !== undefined &&
+        outputCostPerMTok !== undefined &&
+        Number.isFinite(inputCostPerMTok) &&
+        Number.isFinite(outputCostPerMTok) &&
+        inputCostPerMTok >= 0 &&
+        outputCostPerMTok >= 0) {
+        return { input: inputCostPerMTok, output: outputCostPerMTok };
+    }
+    return null;
+}
 export function withTimeout(promise, timeoutMs, onTimeout, abort) {
     let timeoutId;
     const timeoutPromise = new Promise((resolve) => {

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4BAA4B;AA8I5B,oBAAoB;AAEpB,MAAM,UAAU,WAAW,CACzB,OAAmB,EACnB,SAAiB,EACjB,SAAkB,EAClB,KAAuB;IAEvB,IAAI,SAAoD,CAAC;IAEzD,MAAM,cAAc,GAAG,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,EAAE;QAChD,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;YAC1B,KAAK,EAAE,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;QACvB,CAAC,EAAE,SAAS,CAAC,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO;SACX,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;QACf,IAAI,SAAS,KAAK,SAAS;YAAE,YAAY,CAAC,SAAS,CAAC,CAAC;QACrD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;SACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,SAAS,KAAK,SAAS;YAAE,YAAY,CAAC,SAAS,CAAC,CAAC;QACrD,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}