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

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,12 @@ 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[];
 }
 export interface CodexProviderConfig {
     type: 'codex';
@@ -27,6 +34,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 +52,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 +73,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;
@@ -73,9 +103,71 @@ export interface RunResult {
     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[];
     error?: string;
 }
+/**
+ * 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;
+}
 export interface Provider {
     name: string;
     config: ProviderConfig;
@@ -88,7 +180,89 @@ export interface RunOptions {
     cwd?: string;
     effort?: Effort;
     sandboxPolicy?: SandboxPolicy;
+    /** 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;
 }
+/**
+ * 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' | '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 +276,13 @@ 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 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":"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"}

package/dist/types.js

@@ -1,5 +1,21 @@
-// === Tier & Capability ===
 // === 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 inRate = config.inputCostPerMTok;
+    const outRate = config.outputCostPerMTok;
+    if (inRate === undefined || outRate === undefined ||
+        !Number.isFinite(inRate) || !Number.isFinite(outRate) ||
+        inRate < 0 || outRate < 0) {
+        return null;
+    }
+    return (inputTokens * inRate + outputTokens * outRate) / 1_000_000;
+}
 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":"AAkUA,oBAAoB;AAEpB;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,WAAmB,EACnB,YAAoB,EACpB,MAAsB;IAEtB,MAAM,MAAM,GAAG,MAAM,CAAC,gBAAgB,CAAC;IACvC,MAAM,OAAO,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACzC,IACE,MAAM,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS;QAC7C,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;QACrD,MAAM,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,EACzB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,CAAC,WAAW,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC,GAAG,SAAS,CAAC;AACrE,CAAC;AAED,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhixuan92/multi-model-agent-core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "description": "Core library for multi-model-agent: provider runners (Claude, Codex, OpenAI-compatible), routing logic, config schema, and tool/sandbox primitives.",
@@ -22,7 +22,9 @@
   },
   "homepage": "https://github.com/zhixuan312/multi-model-agent#readme",
   "bugs": "https://github.com/zhixuan312/multi-model-agent/issues",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -74,7 +76,9 @@
   "scripts": {
     "build": "tsc"
   },
-  "engines": { "node": ">=22.0.0" },
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.98",
     "@openai/agents": "^0.8.0",