@deepthonk/providers 0.1.4 → 0.2.0

package/README.md

@@ -31,7 +31,7 @@ deepthonk plan --profile paper
 
 The paper profile plans 285 model calls and 8 sequential rounds. Confirm budget and provider pricing before pointing it at paid models. The short alias `dt` is installed alongside `deepthonk`. Develop from source: see [Development](#development).
 
-> v0.1 scope: an independent TypeScript reimplementation of the OpenDeepThink algorithm as a CLI + MCP server. The published algorithm is the load-bearing part; this release is a practical integration layer with explicit limits documented below. Cost guarantees rely on provider pricing being present in config; resume inspects trace state by default and can replay from validated phase boundaries with `--continue` / MCP `continue: true`; the MCP HTTP transport is loopback-only. The included acceptance smoke uses the deterministic fake provider and a toy task — it is not a CF-73 / HLE reproduction; see `docs/` and [Acknowledgments](#acknowledgments) for the canonical paper and Python reference.
+> DeepThonk is an independent TypeScript reimplementation and practical integration layer; the published algorithm is the load-bearing part. Cost guarantees rely on provider pricing being present in config. Trace-v2 resume can reuse validated per-item receipts after a crash, while older traces replay an incomplete phase wholesale. The MCP HTTP transport remains loopback-only. The included acceptance smoke uses the deterministic fake provider and a toy task — it is not a CF-73 / HLE reproduction; see `docs/` and [Acknowledgments](#acknowledgments) for the canonical paper and Python reference.
 
 ## Setup
 
@@ -70,7 +70,7 @@ deepthonk plan --config ~/.config/deepthonk/config.yaml
 deepthonk run --task task.md --config ~/.config/deepthonk/config.yaml --profile quick --dry-run
 ```
 
-Start with `--profile quick` and consider `--max-concurrency`, `--max-input-tokens`, `--max-output-tokens`, `--max-usd`, and `--request-timeout-ms` before larger paid profiles. Runtime token/USD budgets are enforced after completed provider calls and can overshoot by at most the active concurrency window. Every completed run summary includes call/token usage, and includes `usage.usd` when matching model pricing is available.
+Start with `--profile quick` and consider `--max-concurrency`, `--max-calls`, `--max-input-tokens`, `--max-output-tokens`, `--max-usd`, and `--request-timeout-ms` before larger paid profiles. `max_calls` is reserved before dispatch and counts logical model invocations, including failed calls and invalid-JSON retries; provider-internal HTTP retries are reported separately. Token/USD totals are known only after responses and can overshoot by at most the active concurrency window. Plans keep nominal `calls` separate from finalizer and retry headroom in `worst_case_calls`.
 
 ## OpenAI-Compatible Providers
 
@@ -86,7 +86,7 @@ deepthonk run \
   --judge-model strong-model
 ```
 
-The driver calls `POST {base_url}/chat/completions` and requests JSON mode for comparisons when supported. If a provider returns a `400` with a body that mentions `response_format` or `json`, the driver retries without JSON mode and uses robust JSON extraction on the plain text response. Providers that reject JSON mode with a different status code (e.g. `422`) surface as a normal provider error — set `supportsJsonMode: false` in YAML to disable JSON mode up front.
+The driver calls `POST {base_url}/chat/completions` and requests JSON mode for comparisons when supported. If a provider returns `400` or `422` with a body that mentions `response_format` or `json`, the driver retries without JSON mode, coordinates that capability probe across concurrent calls, and remembers the result for the process. Set `supports_json_mode: false` in YAML to disable JSON mode up front.
 
 Provider names are flexible. For a custom OpenAI-compatible endpoint, use any provider label with `--base-url`, `--api-key-env`, and role-specific model flags. For OpenRouter:
 
@@ -111,7 +111,7 @@ The MCP server exposes the same engine the CLI runs. Once wired into an MCP host
 
 Provider API keys come from the host process's environment, not from DeepThonk's config alone. Each host handles env passthrough slightly differently — see the concrete patterns below.
 
-MCP Sampling is supported as `provider: "sampling"` when the connected host advertises the MCP sampling capability. Sampling is not available from standalone CLI runs; use `deepseek`, `openrouter`, or `openai-compatible` there.
+MCP Sampling is supported as `provider: "sampling"` when the connected host advertises the MCP sampling capability. Blocking `run`, `rank`, and `mutate` work over stdio and stateful Streamable HTTP. HTTP background `start` rejects Sampling because nested Sampling must remain attached to the initiating request; stdio background runs and direct-provider HTTP background runs remain available. Sampling is not available from standalone CLI runs.
 
 ### Claude Code
 
@@ -174,10 +174,11 @@ with the relevant provider env vars set on the process. If you'd rather install
 For local web hosts, or when stdio isn't available:
 
 ```bash
-deepthonk serve-mcp --transport http --port 3333
+deepthonk serve-mcp --transport http --port 3333 \
+  --max-active-jobs 2 --max-queued-jobs 32
 ```
 
-The server binds `127.0.0.1:3333` only (loopback) and the endpoint is `POST http://127.0.0.1:3333/mcp`. DNS rebinding protection is on (CVE-2025-66414): requests with `Host` headers outside `127.0.0.1:3333` / `localhost:3333` are rejected. The HTTP wrapper also rejects non-`application/json` POSTs, non-loopback `Origin` headers, and `Sec-Fetch-Site: cross-site` before reading the body. It has no bearer auth. Do not expose this port through a reverse proxy without re-evaluating that trust boundary.
+The server binds `127.0.0.1:3333` only and exposes stateful `POST`, `GET`, and `DELETE` at `http://127.0.0.1:3333/mcp`. Sessions use cryptographic IDs, expire after 30 idle minutes when no request is active, and are capped at 64. DNS rebinding protection is on (CVE-2025-66414): requests with `Host` headers outside `127.0.0.1:3333` / `localhost:3333` are rejected. The wrapper also rejects non-JSON POSTs, non-loopback `Origin` headers, and `Sec-Fetch-Site: cross-site` before reading the body. It has no bearer auth. Do not expose this port through a reverse proxy without re-evaluating that trust boundary.
 
 ### Tools
 
@@ -188,6 +189,8 @@ The server binds `127.0.0.1:3333` only (loopback) and the endpoint is `POST http
 | `deepthonk.status` | Poll job status from a `run_dir`. |
 | `deepthonk.result` | Return final summary + winner once a job is complete. |
 | `deepthonk.cancel` | Request cancellation by writing `cancel.json` into the run directory. |
+| `deepthonk.lock_inspect` / `deepthonk.lock_reclaim` | Inspect lock ownership and explicitly reclaim only an exact fingerprint. |
+| `deepthonk.repair_budget` | Replace legacy `[redacted]` numeric budget fields with explicit original values. |
 | `deepthonk.run` | Blocking convenience: start + await completion in one call. Prefer `start` + polling for long-running jobs. |
 | `deepthonk.rank` | Rank a user-supplied candidate set with pairwise judging + Bradley-Terry (skip generation). |
 | `deepthonk.mutate` | Mutate one supplied candidate with critique (one-shot). |
@@ -209,8 +212,12 @@ All tools accept inline provider/model fields, or `config_path` pointing at a De
 - `deepthonk://runs/{run_id}/population/{generation}` — population snapshot for a generation (JSON).
 - `deepthonk://runs/{run_id}/{winner|final}` — text artifacts.
 - `deepthonk://runs/{run_id}/status` — run state (JSON).
+- `deepthonk://runs/{run_id}/prompts/{sha256}` — verified content-addressed rendered prompt (JSON).
+- `deepthonk://runs/{run_id}/trace-v2` — bounded phase index; follow its manifest, commit, checkpoint-index, and checkpoint URIs to inspect every receipt.
 - `deepthonk://jobs/{job_id}/{status|result|config|candidates|comparisons|scores|usage|trace|final|winner}?run_dir=...` — job-scoped lookup; the `run_dir` query param is required.
 - `deepthonk://jobs/{job_id}/population/{generation}?run_dir=...` — job-scoped population snapshots before or after completion.
+- Job results also include `prompt_template` and `trace_v2_template` for the job-scoped equivalents.
+- `deepthonk://runs/{run_id}/{resource}/page/{cursor}` and job equivalents — opaque bounded pages. Whole reads are limited to 1 MiB; pages contain at most 1,000 records and 1 MiB.
 
 ### Prompts
 
@@ -218,7 +225,7 @@ Four templates mirror the core loop: `deepthonk/generate`, `deepthonk/compare`,
 
 ### Limits
 
-`deepthonk.resume` reports trace state by default. With `continue: true`, it validates the stored config/version/provider, prunes to the last completed phase boundary, and replays from there without reusing partial in-flight outputs. The HTTP transport is loopback-only by design. MCP Sampling depends on the host's sampling implementation; model hints are preferences, token usage may be unavailable, and sampling concurrency is capped at 4.
+`deepthonk.resume` reports trace state by default. With `continue: true`, it validates phase order, artifacts, run/provider/model identity, scores, usage, deterministic pair schedules, trace-v2 receipts, and phase commits. Valid incomplete-phase receipts are reused without another provider call. MCP Sampling model hints are preferences and token usage may be unavailable. Its shared adaptive limiter starts at 4; direct providers start at 8.
 
 ## Customization
 
@@ -229,6 +236,10 @@ Every algorithm dimension is reachable through MCP arguments and CLI flags:
 - **Prompt style**: `general` or `paper-programming`.
 - **Per-phase prompt templates**: override `generate`, `compare`, `mutate`, or `finalize` with custom system/user templates and variable substitution (`{task}`, `{rubric}`, `{candidate}`, `{candidateA}`, `{candidateB}`, `{critique}`). CLI supports `--prompts <yaml>` and `--prompts-json <json>`; MCP supports inline `prompts`. Unknown variables throw a fail-fast error at run-start.
 - **Concurrency**: per-phase caps for `generate`, `judge`, `mutate`.
+- **Provider backpressure**: `provider_max_concurrency` sets the recovery ceiling for the shared adaptive provider-route limiter.
+- **Per-call output bounds**: independent generation, mutation, judge, and finalizer token caps.
+- **Final ranking schedule**: seeded `all-pairs` or `k-regular`, with an explicit logical call cap.
+- **Critique bound**: deterministic deduplication and a configurable aggregate-character cap before mutation.
 
 Example agent call (MCP), no YAML file required:
 
@@ -266,18 +277,22 @@ runs/{run_id}/
   usage.jsonl
   population-0.json
   population-{generation}.json
+  manifests/*.json
+  checkpoints/*/*.json
+  commits/*.json
   summary.json
   artifacts/winner.txt
   artifacts/final.txt
+  artifacts/prompts/<sha256>.json  # only when prompt capture is enabled
 ```
 
 `status.json` is written when the run is launched through MCP `deepthonk.start` (so async clients can poll). `cancel.json` is written only when cancellation is requested. A `run.lock` file is held for the duration of the run.
 
-JSONL writes are streamed as each candidate / comparison / call completes, and all appends go through a per-trace serialization queue. If a run is killed mid-tournament, completed pairs are durable on disk and the JSONL files remain readable.
+Trace rows are batch-appended through a single writer and flushed before lifecycle boundaries. Per-item output and usage receipts are written atomically before a phase commit. If a run is killed mid-tournament, trace-v2 resume validates and reuses completed receipts, re-materializes their JSONL rows, and calls the provider only for missing or invalid work.
 
 `usage.jsonl` carries one row per provider call (generator, judge, mutator, finalizer) with phase/role/provider/model/token/USD/latency/retry. It contains no prompt content. `jq` over `usage.jsonl` is the simplest way to break a run's cost down by role.
 
-Prompts and raw model outputs are off by default. API keys are never written. Candidate answers, critiques, scores, and final artifacts are trace data and are stored/exported by design, so do not use a shared run directory for sensitive tasks unless that is acceptable.
+Prompts and raw model outputs are off by default. When prompt capture is enabled, candidate/comparison rows carry a `promptRef` and identical rendered prompts share one content-addressed blob under `artifacts/prompts/`; the full prompt is not repeated in every JSONL row or receipt. API keys are never written. Candidate answers, critiques, scores, and final artifacts are trace data and are stored/exported by design, so do not use a shared run directory for sensitive tasks unless that is acceptable.
 
 ## Development
 
@@ -294,8 +309,8 @@ Release publishing is tag-triggered through npm Trusted Publishing. See [docs/re
 
 Known limits for this release:
 
-- Conservative resume reports trace state by default; replay requires an explicit `--continue` / MCP `continue: true` and only starts from validated phase boundaries.
-- MCP Sampling is MCP-host-only. Standalone CLI runs need a direct provider.
+- Trace-v1 resume replays an interrupted phase wholesale; per-item reuse requires a trace-v2 run created by DeepThonk v0.2.
+- HTTP Sampling is blocking-only. Use stdio or a direct provider for background `deepthonk.start` work.
 - `maxUsd` requires known model pricing; add explicit prices in YAML for custom providers and model IDs. Optional fields `longContextThresholdTokens`, `inputUsdPerMillionLong`, and `outputUsdPerMillionLong` enable tiered pricing for models with a long-context surcharge (e.g., Gemini at 200K input tokens). Cache hit/miss rates remain flat.
 
 ## Acknowledgments

package/dist/defaults.d.ts

@@ -9,6 +9,8 @@ export interface ProviderModelOverrides {
 }
 export interface ProviderConfigOptions {
     provider: string;
+    routeFingerprint?: string;
+    providerMaxConcurrency?: number;
     baseUrl?: string;
     apiKeyEnv?: string;
     apiKey?: string;
@@ -16,6 +18,14 @@ export interface ProviderConfigOptions {
     retry?: ProviderConfig["retry"];
     supportsJsonMode?: boolean;
     samplingTransport?: SamplingTransport;
+    modelHints?: string[];
+    costPriority?: number;
+    speedPriority?: number;
+    intelligencePriority?: number;
+    includeRawOutputs?: boolean;
+    requestTimeoutMs?: number;
+    /** Disable implicit endpoint and credential defaults for an explicitly replaced route. */
+    inheritProviderDefaults?: boolean;
     roleProviders?: Partial<Record<ProviderRole, Partial<Omit<RoleProviderConfig, "model">> & {
         model?: string;
     }>>;

package/dist/defaults.js

@@ -8,16 +8,25 @@ export function resolveProviderModels(provider, overrides = {}) {
 }
 export function resolveProviderConfig(options) {
     const models = resolveProviderModels(options.provider, options.models);
+    const inheritProviderDefaults = options.inheritProviderDefaults ?? true;
     return {
         provider: options.provider,
-        baseUrl: options.baseUrl ?? defaultBaseUrl(options.provider),
-        apiKeyEnv: options.apiKeyEnv ?? defaultApiKeyEnv(options.provider),
+        routeFingerprint: options.routeFingerprint,
+        providerMaxConcurrency: options.providerMaxConcurrency,
+        baseUrl: options.baseUrl ?? (inheritProviderDefaults ? defaultBaseUrl(options.provider) : undefined),
+        apiKeyEnv: options.apiKeyEnv ?? (inheritProviderDefaults ? defaultApiKeyEnv(options.provider) : undefined),
         apiKey: options.apiKey,
         models,
         retry: options.retry,
         supportsJsonMode: options.supportsJsonMode,
         samplingTransport: options.samplingTransport,
-        roleProviders: resolveRoleProviders(options.provider, models, options.roleProviders, options.retry, options.supportsJsonMode)
+        modelHints: options.modelHints,
+        costPriority: options.costPriority,
+        speedPriority: options.speedPriority,
+        intelligencePriority: options.intelligencePriority,
+        includeRawOutputs: options.includeRawOutputs,
+        requestTimeoutMs: options.requestTimeoutMs,
+        roleProviders: resolveRoleProviders(options.provider, models, options.roleProviders, options.retry, options.supportsJsonMode, options.providerMaxConcurrency)
     };
 }
 export function defaultModel(provider, role) {
@@ -49,7 +58,7 @@ export function defaultApiKeyEnv(provider) {
         return "DEEPTHONK_API_KEY";
     return undefined;
 }
-function resolveRoleProviders(baseProvider, models, roleProviders, baseRetry, baseSupportsJsonMode) {
+function resolveRoleProviders(baseProvider, models, roleProviders, baseRetry, baseSupportsJsonMode, providerMaxConcurrency) {
     if (!roleProviders)
         return undefined;
     const resolved = {};
@@ -58,15 +67,17 @@ function resolveRoleProviders(baseProvider, models, roleProviders, baseRetry, ba
         if (!input)
             continue;
         const provider = input.provider ?? baseProvider;
-        const model = input.model ?? models[role] ?? defaultModel(provider, role);
+        const isolatedRoute = input.baseUrl !== undefined || (input.provider !== undefined && input.provider !== baseProvider);
+        const model = input.model ?? (isolatedRoute ? defaultModel(provider, role) : models[role]) ?? defaultModel(provider, role);
         resolved[role] = {
             provider,
             baseUrl: input.baseUrl ?? defaultBaseUrl(provider),
-            apiKeyEnv: input.apiKeyEnv ?? defaultApiKeyEnv(provider),
+            apiKeyEnv: input.apiKeyEnv ?? (input.baseUrl === undefined ? defaultApiKeyEnv(provider) : undefined),
             apiKey: input.apiKey,
             model,
+            providerMaxConcurrency,
             retry: input.retry ?? baseRetry,
-            supportsJsonMode: input.supportsJsonMode ?? baseSupportsJsonMode
+            supportsJsonMode: input.supportsJsonMode ?? (isolatedRoute ? undefined : baseSupportsJsonMode)
         };
     }
     return Object.keys(resolved).length ? resolved : undefined;

package/dist/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAkCA,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,YAAoC,EAAE;IAC5F,OAAO;QACL,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,YAAY,CAAC,QAAQ,EAAE,WAAW,CAAC;QACrE,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC;QAC/D,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC;QACzD,SAAS,EAAE,SAAS,CAAC,SAAS;KAC/B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAA8B;IAClE,MAAM,MAAM,GAAG,qBAAqB,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,MAAM,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,IAAI,IAAI,CAAC;IACxE,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;QACtD,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,CAAC,uBAAuB,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACpG,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,CAAC,uBAAuB,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1G,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM;QACN,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;QAC5C,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;QAClD,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;QAC5C,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,aAAa,EAAE,oBAAoB,CACjC,OAAO,CAAC,QAAQ,EAChB,MAAM,EACN,OAAO,CAAC,aAAa,EACrB,OAAO,CAAC,KAAK,EACb,OAAO,CAAC,gBAAgB,EACxB,OAAO,CAAC,sBAAsB,CAC/B;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,IAAkB;IAC/D,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACjE,IAAI,QAAQ,KAAK,UAAU;QAAE,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,mBAAmB,CAAC;IAC/F,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,YAAY,CAAC;IAC7C,IAAI,QAAQ,KAAK,UAAU;QAAE,OAAO,UAAU,CAAC;IAC/C,IAAI,QAAQ,KAAK,YAAY;QAAE,OAAO,iBAAiB,CAAC;IACxD,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,sBAAsB,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,IAAI,QAAQ,KAAK,UAAU;QAAE,OAAO,6BAA6B,CAAC;IAClE,IAAI,QAAQ,KAAK,YAAY;QAAE,OAAO,8BAA8B,CAAC;IACrE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,IAAI,QAAQ,KAAK,UAAU;QAAE,OAAO,kBAAkB,CAAC;IACvD,IAAI,QAAQ,KAAK,YAAY;QAAE,OAAO,oBAAoB,CAAC;IAC3D,IAAI,QAAQ,KAAK,mBAAmB;QAAE,OAAO,mBAAmB,CAAC;IACjE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,oBAAoB,CAC3B,YAAoB,EACpB,MAAgC,EAChC,aAAsD,EACtD,SAAmC,EACnC,oBAA8B,EAC9B,sBAA+B;IAE/B,IAAI,CAAC,aAAa;QAAE,OAAO,SAAS,CAAC;IACrC,MAAM,QAAQ,GAAoC,EAAE,CAAC;IACrD,KAAK,MAAM,IAAI,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,CAAU,EAAE,CAAC;QAC3E,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,YAAY,CAAC;QAChD,MAAM,aAAa,GACjB,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,YAAY,CAAC,CAAC;QACnG,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC3H,QAAQ,CAAC,IAAI,CAAC,GAAG;YACf,QAAQ;YACR,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,cAAc,CAAC,QAAQ,CAAC;YAClD,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACpG,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,KAAK;YACL,sBAAsB;YACtB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,SAAS;YAC/B,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC;SAC/F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC"}

package/dist/externalConfig.d.ts

@@ -0,0 +1,67 @@
+import { type BuiltInProfileName, type RunConfig } from "@deepthonk/core";
+import type { ProviderRole } from "./types.js";
+export interface ExternalConfigFile {
+    runId?: string;
+    profile?: BuiltInProfileName;
+    provider?: string;
+    base_url?: string;
+    api_key_env?: string;
+    supports_json_mode?: boolean;
+    models?: {
+        generator?: string;
+        mutator?: string;
+        judge?: string;
+        finalizer?: string;
+    };
+    providers?: Partial<Record<ProviderRole, ExternalRoleProviderConfig>>;
+    concurrency?: Partial<RunConfig["concurrency"]>;
+    retry?: Partial<RunConfig["retry"]>;
+    budget?: RunConfig["budget"];
+    output?: Partial<RunConfig["output"]>;
+    prompt_style?: RunConfig["promptStyle"];
+    algorithm?: ExternalAlgorithmOverrides;
+    prompts?: ExternalPromptOverrides;
+    modelOutputTokens?: RunConfig["modelOutputTokens"];
+    critiqueLimits?: RunConfig["critiqueLimits"];
+    rank?: RunConfig["rank"];
+    providerMaxConcurrency?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface ExternalAlgorithmOverrides {
+    n?: number;
+    k?: number;
+    t?: number;
+    m?: number;
+    lambda?: number;
+    sample_temperature?: number;
+    mutate_temperature?: number;
+    judge_temperature?: number;
+}
+export interface ExternalPromptOverrides {
+    generate?: {
+        system?: string;
+        user?: string;
+    };
+    compare?: {
+        system?: string;
+        user?: string;
+    };
+    mutate?: {
+        system?: string;
+        user?: string;
+    };
+    finalize?: {
+        system?: string;
+        user?: string;
+    };
+}
+interface ExternalRoleProviderConfig {
+    provider?: string;
+    base_url?: string;
+    api_key_env?: string;
+    model?: string;
+    supports_json_mode?: boolean;
+}
+/** Normalize the public YAML contract to the camelCase core/provider shape. */
+export declare function normalizeExternalConfig(value: unknown, source?: string): ExternalConfigFile;
+export {};

package/dist/externalConfig.js

@@ -0,0 +1,318 @@
+import { ConfigError, maxPhaseConcurrency } from "@deepthonk/core";
+import { z } from "zod";
+const nonEmptyString = z.string().trim().min(1);
+const promptBlockSchema = z.object({ system: z.string().optional(), user: z.string().optional() }).strict();
+const priceSchema = z
+    .object({
+    provider: nonEmptyString,
+    model: nonEmptyString,
+    inputUsdPerMillion: z.number().min(0).optional(),
+    inputCacheHitUsdPerMillion: z.number().min(0).optional(),
+    inputCacheMissUsdPerMillion: z.number().min(0).optional(),
+    outputUsdPerMillion: z.number().min(0).optional(),
+    longContextThresholdTokens: z.number().int().min(1).optional(),
+    inputUsdPerMillionLong: z.number().min(0).optional(),
+    outputUsdPerMillionLong: z.number().min(0).optional()
+})
+    .strict()
+    .superRefine((price, context) => {
+    const longFields = [price.longContextThresholdTokens, price.inputUsdPerMillionLong, price.outputUsdPerMillionLong];
+    if (longFields.every((entry) => entry === undefined))
+        return;
+    if (price.longContextThresholdTokens === undefined ||
+        price.inputUsdPerMillion === undefined ||
+        price.outputUsdPerMillion === undefined ||
+        price.inputUsdPerMillionLong === undefined ||
+        price.outputUsdPerMillionLong === undefined) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Long-context pricing requires threshold and complete flat/long input/output rates."
+        });
+    }
+});
+const externalConfigSchema = z
+    .object({
+    runId: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/).optional(),
+    profile: z.enum(["quick", "balanced", "paper"]).optional(),
+    provider: nonEmptyString.optional(),
+    base_url: z.string().url().optional(),
+    api_key_env: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/).optional(),
+    supports_json_mode: z.boolean().optional(),
+    models: z.object({ generator: nonEmptyString.optional(), mutator: nonEmptyString.optional(), judge: nonEmptyString.optional(), finalizer: nonEmptyString.optional() }).strict().optional(),
+    providers: z.record(z.enum(["generator", "mutator", "judge", "finalizer"]), z.object({
+        provider: nonEmptyString.optional(),
+        base_url: z.string().url().optional(),
+        api_key_env: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/).optional(),
+        model: nonEmptyString.optional(),
+        supports_json_mode: z.boolean().optional()
+    }).strict()).optional(),
+    concurrency: z.object({ generate: z.number().int().min(1).optional(), judge: z.number().int().min(1).optional(), mutate: z.number().int().min(1).optional() }).strict().optional(),
+    retry: z.object({ httpRetries: z.number().int().min(0).optional(), invalidJsonRetries: z.number().int().min(0).optional(), requestTimeoutMs: z.number().int().min(1).optional() }).strict().optional(),
+    budget: z.object({
+        maxCalls: z.number().int().min(1).optional(),
+        maxInputTokens: z.number().int().min(1).optional(),
+        maxOutputTokens: z.number().int().min(1).optional(),
+        maxUsd: z.number().min(0).optional(),
+        prices: z.array(priceSchema).optional()
+    }).strict().optional(),
+    output: z.object({ includeRawModelOutputs: z.boolean().optional(), includePrompts: z.boolean().optional() }).strict().optional(),
+    modelOutputTokens: z.object({
+        generation: z.number().int().min(1).optional(),
+        mutation: z.number().int().min(1).optional(),
+        judge: z.number().int().min(1).optional(),
+        finalizer: z.number().int().min(1).optional()
+    }).strict().optional(),
+    critiqueLimits: z.object({ aggregateChars: z.number().int().min(256).optional() }).strict().optional(),
+    rank: z.object({
+        mode: z.enum(["all-pairs", "k-regular"]),
+        k: z.number().int().min(1).optional(),
+        seed: z.number().int().optional(),
+        maxCalls: z.number().int().min(1).optional()
+    }).strict().optional(),
+    providerMaxConcurrency: z.number().int().min(1).max(maxPhaseConcurrency).optional(),
+    prompt_style: z.enum(["general", "paper-programming"]).optional(),
+    algorithm: z.object({
+        n: z.number().int().min(2).optional(),
+        k: z.number().int().min(1).optional(),
+        t: z.number().int().min(0).optional(),
+        m: z.number().int().min(1).optional(),
+        lambda: z.number().min(0).optional(),
+        sample_temperature: z.number().min(0).optional(),
+        mutate_temperature: z.number().min(0).optional(),
+        judge_temperature: z.number().min(0).optional()
+    }).strict().optional(),
+    prompts: z.object({ generate: promptBlockSchema.optional(), compare: promptBlockSchema.optional(), mutate: promptBlockSchema.optional(), finalize: promptBlockSchema.optional() }).strict().optional(),
+    metadata: z.record(z.unknown()).optional()
+})
+    .strict();
+/** Normalize the public YAML contract to the camelCase core/provider shape. */
+export function normalizeExternalConfig(value, source = "config") {
+    const root = configRecord(value, source);
+    assertKnownKeys(root, [
+        "profile", "run_id", "runId", "provider", "base_url", "baseUrl", "api_key_env", "apiKeyEnv",
+        "supports_json_mode", "supportsJsonMode", "models", "providers", "concurrency", "retry", "budget",
+        "output", "prompt_style", "promptStyle", "algorithm", "prompts", "model_output_tokens", "modelOutputTokens",
+        "critique_limits", "critiqueLimits", "rank", "provider_max_concurrency", "providerMaxConcurrency", "metadata"
+    ], source);
+    const normalized = {
+        runId: aliased(root, "run_id", "runId", source),
+        profile: root.profile,
+        provider: root.provider,
+        base_url: aliased(root, "base_url", "baseUrl", source),
+        api_key_env: aliased(root, "api_key_env", "apiKeyEnv", source),
+        supports_json_mode: aliased(root, "supports_json_mode", "supportsJsonMode", source),
+        models: normalizeModels(root.models, `${source}.models`),
+        providers: normalizeProviders(root.providers, `${source}.providers`),
+        concurrency: normalizeConcurrency(root.concurrency, `${source}.concurrency`),
+        retry: normalizeRetry(root.retry, `${source}.retry`),
+        budget: normalizeBudget(root.budget, `${source}.budget`),
+        output: normalizeOutput(root.output, `${source}.output`),
+        prompt_style: aliased(root, "prompt_style", "promptStyle", source),
+        algorithm: normalizeAlgorithm(root.algorithm, `${source}.algorithm`),
+        prompts: normalizePrompts(root.prompts, `${source}.prompts`),
+        modelOutputTokens: normalizeModelOutputTokens(aliased(root, "model_output_tokens", "modelOutputTokens", source), `${source}.model_output_tokens`),
+        critiqueLimits: normalizeCritiqueLimits(aliased(root, "critique_limits", "critiqueLimits", source), `${source}.critique_limits`),
+        rank: normalizeRank(root.rank, `${source}.rank`),
+        providerMaxConcurrency: aliased(root, "provider_max_concurrency", "providerMaxConcurrency", source),
+        metadata: root.metadata === undefined ? undefined : configRecord(root.metadata, `${source}.metadata`)
+    };
+    const compact = compactConfig(normalized);
+    const parsed = externalConfigSchema.safeParse(compact);
+    if (!parsed.success) {
+        throw new ConfigError(`Invalid config value at ${source}: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`).join("; ")}.`, {
+            code: "config.invalid_value",
+            retryable: false,
+            fix: "Use the documented strings, booleans, enums, and numeric ranges. YAML numeric values must not be quoted."
+        });
+    }
+    return parsed.data;
+}
+function normalizeModels(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["generator", "mutator", "judge", "finalizer"], path);
+    return compactConfig({ generator: record.generator, mutator: record.mutator, judge: record.judge, finalizer: record.finalizer });
+}
+function normalizeProviders(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["generator", "mutator", "judge", "finalizer"], path);
+    const providers = {};
+    for (const role of ["generator", "mutator", "judge", "finalizer"]) {
+        if (record[role] === undefined)
+            continue;
+        const rolePath = `${path}.${role}`;
+        const input = configRecord(record[role], rolePath);
+        assertKnownKeys(input, ["provider", "base_url", "baseUrl", "api_key_env", "apiKeyEnv", "model", "supports_json_mode", "supportsJsonMode"], rolePath);
+        providers[role] = compactConfig({
+            provider: input.provider,
+            base_url: aliased(input, "base_url", "baseUrl", rolePath),
+            api_key_env: aliased(input, "api_key_env", "apiKeyEnv", rolePath),
+            model: input.model,
+            supports_json_mode: aliased(input, "supports_json_mode", "supportsJsonMode", rolePath)
+        });
+    }
+    return providers;
+}
+function normalizeConcurrency(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["generate", "judge", "mutate"], path);
+    return compactConfig({ generate: record.generate, judge: record.judge, mutate: record.mutate });
+}
+function normalizeRetry(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["http_retries", "httpRetries", "invalid_json_retries", "invalidJsonRetries", "request_timeout_ms", "requestTimeoutMs"], path);
+    return compactConfig({
+        httpRetries: aliased(record, "http_retries", "httpRetries", path),
+        invalidJsonRetries: aliased(record, "invalid_json_retries", "invalidJsonRetries", path),
+        requestTimeoutMs: aliased(record, "request_timeout_ms", "requestTimeoutMs", path)
+    });
+}
+function normalizeBudget(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["max_calls", "maxCalls", "max_input_tokens", "maxInputTokens", "max_output_tokens", "maxOutputTokens", "max_usd", "maxUsd", "prices"], path);
+    return compactConfig({
+        maxCalls: aliased(record, "max_calls", "maxCalls", path),
+        maxInputTokens: aliased(record, "max_input_tokens", "maxInputTokens", path),
+        maxOutputTokens: aliased(record, "max_output_tokens", "maxOutputTokens", path),
+        maxUsd: aliased(record, "max_usd", "maxUsd", path),
+        prices: record.prices === undefined ? undefined : normalizePrices(record.prices, `${path}.prices`)
+    });
+}
+function normalizePrices(value, path) {
+    if (!Array.isArray(value))
+        throw invalidConfigShape(path, "an array");
+    return value.map((entry, index) => {
+        const entryPath = `${path}[${index}]`;
+        const record = configRecord(entry, entryPath);
+        const aliases = [
+            ["input_usd_per_million", "inputUsdPerMillion"], ["input_cache_hit_usd_per_million", "inputCacheHitUsdPerMillion"],
+            ["input_cache_miss_usd_per_million", "inputCacheMissUsdPerMillion"], ["output_usd_per_million", "outputUsdPerMillion"],
+            ["long_context_threshold_tokens", "longContextThresholdTokens"], ["input_usd_per_million_long", "inputUsdPerMillionLong"],
+            ["output_usd_per_million_long", "outputUsdPerMillionLong"]
+        ];
+        assertKnownKeys(record, ["provider", "model", ...aliases.flat()], entryPath);
+        return compactConfig({
+            provider: record.provider, model: record.model,
+            inputUsdPerMillion: aliased(record, ...aliases[0], entryPath),
+            inputCacheHitUsdPerMillion: aliased(record, ...aliases[1], entryPath),
+            inputCacheMissUsdPerMillion: aliased(record, ...aliases[2], entryPath),
+            outputUsdPerMillion: aliased(record, ...aliases[3], entryPath),
+            longContextThresholdTokens: aliased(record, ...aliases[4], entryPath),
+            inputUsdPerMillionLong: aliased(record, ...aliases[5], entryPath),
+            outputUsdPerMillionLong: aliased(record, ...aliases[6], entryPath)
+        });
+    });
+}
+function normalizeOutput(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["include_raw_model_outputs", "includeRawModelOutputs", "include_prompts", "includePrompts"], path);
+    return compactConfig({
+        includeRawModelOutputs: aliased(record, "include_raw_model_outputs", "includeRawModelOutputs", path),
+        includePrompts: aliased(record, "include_prompts", "includePrompts", path)
+    });
+}
+function normalizeAlgorithm(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["n", "k", "t", "m", "lambda", "sample_temperature", "sampleTemperature", "mutate_temperature", "mutateTemperature", "judge_temperature", "judgeTemperature"], path);
+    return compactConfig({
+        n: record.n, k: record.k, t: record.t, m: record.m, lambda: record.lambda,
+        sample_temperature: aliased(record, "sample_temperature", "sampleTemperature", path),
+        mutate_temperature: aliased(record, "mutate_temperature", "mutateTemperature", path),
+        judge_temperature: aliased(record, "judge_temperature", "judgeTemperature", path)
+    });
+}
+function normalizePrompts(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["generate", "compare", "mutate", "finalize"], path);
+    const prompts = {};
+    for (const phase of ["generate", "compare", "mutate", "finalize"]) {
+        if (record[phase] === undefined)
+            continue;
+        const phasePath = `${path}.${phase}`;
+        const prompt = configRecord(record[phase], phasePath);
+        assertKnownKeys(prompt, ["system", "user"], phasePath);
+        prompts[phase] = compactConfig({ system: prompt.system, user: prompt.user });
+    }
+    return prompts;
+}
+function normalizeModelOutputTokens(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["generation", "mutation", "judge", "finalizer"], path);
+    return compactConfig({
+        generation: record.generation,
+        mutation: record.mutation,
+        judge: record.judge,
+        finalizer: record.finalizer
+    });
+}
+function normalizeCritiqueLimits(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["aggregate_chars", "aggregateChars"], path);
+    return compactConfig({
+        aggregateChars: aliased(record, "aggregate_chars", "aggregateChars", path)
+    });
+}
+function normalizeRank(value, path) {
+    if (value === undefined)
+        return undefined;
+    const record = configRecord(value, path);
+    assertKnownKeys(record, ["mode", "k", "seed", "max_calls", "maxCalls"], path);
+    return compactConfig({
+        mode: record.mode,
+        k: record.k,
+        seed: record.seed,
+        maxCalls: aliased(record, "max_calls", "maxCalls", path)
+    });
+}
+function configRecord(value, path) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw invalidConfigShape(path, "a mapping");
+    return value;
+}
+function assertKnownKeys(record, allowed, path) {
+    const allowedSet = new Set(allowed);
+    const unknown = Object.keys(record).filter((key) => !allowedSet.has(key));
+    if (!unknown.length)
+        return;
+    throw new ConfigError(`Unknown config key${unknown.length === 1 ? "" : "s"} at ${path}: ${unknown.join(", ")}.`, {
+        code: "config.unknown_key", retryable: false,
+        fix: "Remove misspelled or unsupported operational keys. Arbitrary application data is allowed only below metadata."
+    });
+}
+function aliased(record, canonical, camel, path) {
+    const hasCanonical = Object.prototype.hasOwnProperty.call(record, canonical);
+    const hasCamel = Object.prototype.hasOwnProperty.call(record, camel);
+    if (hasCanonical && hasCamel && JSON.stringify(record[canonical]) !== JSON.stringify(record[camel])) {
+        throw new ConfigError(`Conflicting config aliases at ${path}: '${canonical}' and '${camel}' have different values.`, {
+            code: "config.alias_conflict", retryable: false,
+            fix: `Keep the canonical snake_case '${canonical}' key, or make both aliases identical during migration.`
+        });
+    }
+    return hasCanonical ? record[canonical] : record[camel];
+}
+function compactConfig(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entryValue]) => entryValue !== undefined));
+}
+function invalidConfigShape(path, expected) {
+    return new ConfigError(`${path} must be ${expected}.`, { code: "config.invalid_shape", retryable: false, fix: "Use the documented YAML mapping and array structure." });
+}
+//# sourceMappingURL=externalConfig.js.map