@deepthonk/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xule Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+# DeepThonk
+
+*thonk harder, not richer.*
+
+DeepThonk implements the OpenDeepThink algorithm (Zhou et al., 2026, [arXiv:2605.15177](https://arxiv.org/abs/2605.15177)) as a budget-friendly, provider-neutral "deep think / pro mode" wrapper, with first-class DeepSeek support. See [Acknowledgments](#acknowledgments).
+
+DeepThonk runs a population of candidate answers through pairwise judging, Bradley-Terry ranking, critique-guided mutation, elite preservation, and a final dense ranking pass. The CLI and MCP server both call the same TypeScript core engine.
+
+**Designed for agents.** Every algorithm dimension — population shape (`n`, `k`, `t`, `m`), regularization (`lambda`), per-phase temperatures, prompt style, and per-phase prompt templates — is reachable inline through MCP arguments and CLI flags. No filesystem detours required. Every intermediate artifact (candidates, comparisons, scores, per-call usage, status) is exposed as a streaming MCP resource so an agent can inspect any step. See [Customization](https://github.com/linxule/deepthonk/blob/main/docs/customization.md) for the full agent-composable surface.
+
+Use it for hard, verifiable reasoning, coding, planning, and synthesis where breadth plus judgment can beat one expensive single shot. Avoid it for highly subjective tasks where judge noise dominates.
+
+## Quickstart
+
+Run without installing:
+
+```bash
+npx -y deepthonk plan --profile paper
+npx -y deepthonk run --provider fake --profile quick \
+  --task "Find the smallest positive integer divisible by 3, 4, and 5." \
+  --out runs/test-quick
+npx -y deepthonk inspect runs/test-quick
+```
+
+Or install globally:
+
+```bash
+npm install -g deepthonk
+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 only inspects trace state, it does not replay; 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.
+
+## Setup
+
+Create a reusable local config:
+
+```bash
+deepthonk setup \
+  --provider deepseek \
+  --api-key-env DEEPSEEK_API_KEY \
+  --fast-model deepseek-v4-flash \
+  --judge-model deepseek-v4-pro
+```
+
+By default this writes `~/.config/deepthonk/config.yaml`. `deepthonk run` loads that file automatically when `--config` is not supplied. If you pass `--api-key`, setup stores it in `~/.config/deepthonk/env`; otherwise it uses the named environment variable from your shell.
+
+## DeepSeek
+
+```bash
+export DEEPSEEK_API_KEY=...
+deepthonk run \
+  --task task.md \
+  --profile paper \
+  --provider deepseek \
+  --generator-model deepseek-v4-flash \
+  --mutator-model deepseek-v4-flash \
+  --judge-model deepseek-v4-pro \
+  --out runs/task-paper
+```
+
+DeepSeek is implemented as an OpenAI-compatible profile using `https://api.deepseek.com/v1`. DeepThonk ships default USD pricing for `deepseek-v4-flash` and `deepseek-v4-pro` from the official DeepSeek pricing page, including cache-hit/cache-miss input rates. Model names and prices are still editable config because both can change.
+
+Before paid runs, inspect cost shape and resolved config:
+
+```bash
+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.
+
+## OpenAI-Compatible Providers
+
+```bash
+export DEEPTHONK_API_KEY=...
+deepthonk run \
+  --task task.md \
+  --profile balanced \
+  --provider openai-compatible \
+  --base-url https://provider.example.com/v1 \
+  --api-key-env DEEPTHONK_API_KEY \
+  --generator-model cheap-model \
+  --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.
+
+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:
+
+```bash
+export OPENROUTER_API_KEY=...
+deepthonk run \
+  --task task.md \
+  --profile balanced \
+  --provider openrouter \
+  --generator-model openrouter/auto \
+  --mutator-model openrouter/auto \
+  --judge-model openrouter/auto
+```
+
+For mixed-provider runs, use YAML config and override individual roles under `providers`, especially `judge`.
+
+Optional `finalizer_model` / `--finalizer-model` can post-process the ranked winner. Leave it unset when you want the raw ranked answer as the final artifact.
+
+## MCP
+
+The MCP server exposes the same engine the CLI runs. Once wired into an MCP host, the host can plan budgets, kick off background runs, poll status, fetch winners, and stream structured trace artifacts — all through MCP tools, resources, and prompts.
+
+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.
+
+### Claude Code
+
+```bash
+claude mcp add deepthonk \
+  -e DEEPSEEK_API_KEY=$DEEPSEEK_API_KEY \
+  -- npx -y deepthonk serve-mcp --transport stdio
+```
+
+Use `-s user` for cross-project scope or `-s project` to commit registration into `.claude/`. Verify with `claude mcp list`. See `claude mcp --help` for the authoritative flag set.
+
+### Claude Desktop
+
+Config path: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\Claude\claude_desktop_config.json` (Windows), `~/.config/Claude/claude_desktop_config.json` (Linux). Add:
+
+```json
+{
+  "mcpServers": {
+    "deepthonk": {
+      "command": "npx",
+      "args": ["-y", "deepthonk", "serve-mcp", "--transport", "stdio"],
+      "env": {
+        "DEEPSEEK_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing.
+
+### Cursor
+
+Project-scoped: `.cursor/mcp.json` in the workspace. User-global: `~/.cursor/mcp.json`. Same JSON shape as Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "deepthonk": {
+      "command": "npx",
+      "args": ["-y", "deepthonk", "serve-mcp", "--transport", "stdio"],
+      "env": { "DEEPSEEK_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+
+### Other MCP hosts (stdio)
+
+Any host that speaks MCP stdio launches:
+
+```bash
+npx -y deepthonk serve-mcp --transport stdio
+```
+
+with the relevant provider env vars set on the process. If you'd rather install globally, `npm install -g deepthonk` then use `command: "deepthonk"` directly. Refer to the host's MCP registration docs for the configuration shape.
+
+### Streamable HTTP
+
+For local web hosts, or when stdio isn't available:
+
+```bash
+deepthonk serve-mcp --transport http --port 3333
+```
+
+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. Do not expose this port through a reverse proxy without re-evaluating that trust boundary.
+
+### Tools
+
+| Tool | Purpose |
+|---|---|
+| `deepthonk.plan` | Estimate calls and sequential rounds for a profile (no model calls). Use before paid runs. |
+| `deepthonk.start` | Start a run in the background; returns `run_dir` + `job_id`. |
+| `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.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). |
+| `deepthonk.resume` | Detect whether a run can be resumed. Reports state only; does not replay yet. |
+| `deepthonk.export` | Export run summary or full trace in JSON or markdown. |
+
+All tools accept inline provider/model fields, or `config_path` pointing at a DeepThonk YAML config.
+
+### Resources
+
+- `deepthonk://runs` — JSON index of all runs in `runs/`.
+- `deepthonk://runs/{run_id}/summary` — run summary (JSON).
+- `deepthonk://runs/{run_id}/{candidates|comparisons|scores|trace}` — per-phase NDJSON.
+- `deepthonk://runs/{run_id}/{winner|final}` — text artifacts.
+- `deepthonk://runs/{run_id}/status` — run state (JSON).
+- `deepthonk://jobs/{job_id}/{status|result}?run_dir=...` — job-scoped lookup; the `run_dir` query param is required.
+
+### Prompts
+
+Four templates mirror the core loop: `deepthonk/generate`, `deepthonk/compare`, `deepthonk/mutate`, `deepthonk/finalize`. Hosts can render them directly to drive the algorithm by hand without invoking the tool surface.
+
+### Limits
+
+MCP Sampling is deferred and not exposed as a provider mode — direct provider mode is the only option in v0.1. `deepthonk.resume` reports trace state and safe phase boundaries but does not replay interrupted runs. The HTTP transport is loopback-only by design.
+
+## Customization
+
+Every algorithm dimension is reachable through MCP arguments and CLI flags:
+
+- **Population shape**: `n`, `k`, `t`, `m` — override profile defaults inline.
+- **Algorithm constants**: `lambda`, `sample_temperature`, `mutate_temperature`, `judge_temperature`.
+- **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}`). Unknown variables throw a fail-fast error at run-start.
+- **Concurrency**: per-phase caps for `generate`, `judge`, `mutate`.
+
+Example agent call (MCP), no YAML file required:
+
+```json
+{
+  "task": "Draft a concise non-solicitation clause for a senior sales employee.",
+  "profile": "balanced",
+  "n": 6, "t": 1,
+  "provider": "deepseek",
+  "judge_model": "deepseek-v4-pro",
+  "prompts": {
+    "generate": { "system": "You are an experienced employment-law attorney." },
+    "compare":  { "system": "Prefer enforceable clauses under California law. Return strict JSON only." }
+  }
+}
+```
+
+CLI accepts the same surface, except prompt overrides are loaded from a YAML file via `--prompts <yaml>` (shell-quoting multi-line templates is hostile). MCP and CLI both merge over any `--config`/`config_path` YAML defaults.
+
+See the [Customization guide](https://github.com/linxule/deepthonk/blob/main/docs/customization.md) for the complete variable contract, the compare-phase JSON safety rule, and three worked examples. Per-role provider routing (`providers.judge.provider = openrouter`) and per-model pricing remain YAML-only — they're nested structured config, not inline ergonomics.
+
+## Trace Files
+
+A successful run writes:
+
+```txt
+runs/{run_id}/
+  config.json
+  events.jsonl
+  candidates.jsonl
+  comparisons.jsonl
+  scores.jsonl
+  usage.jsonl
+  summary.json
+  artifacts/winner.txt
+  artifacts/final.txt
+```
+
+`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.
+
+`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.
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+pnpm test
+pnpm run lint
+```
+
+This repository is source-only. Generated run traces, paper notes, build output, coverage, logs, and `node_modules` are intentionally ignored.
+
+Known limits for this release:
+
+- Conservative resume reports trace state and safe phase boundaries, but does not replay interrupted runs yet.
+- MCP Sampling is deferred until there is a real host-backed Sampling driver.
+- `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
+
+DeepThonk is an independent TypeScript reimplementation of the OpenDeepThink algorithm. It is not a fork; no source code from the reference implementation is vendored. Credit for the algorithm, the benchmark methodology, and the empirical results belongs to the paper authors.
+
+- **Paper**: Shang Zhou, Wenhao Chai, Kaiyuan Liu, Huanzhi Mao, Qiuyang Mang, Jingbo Shang. *OpenDeepThink: Parallel Reasoning via Bradley–Terry Aggregation*. arXiv:2605.15177, 2026. <https://arxiv.org/abs/2605.15177>
+- **Reference Python implementation**: <https://github.com/ZhouShang0817/open-deep-think> (MIT). This is the authors' code release and the canonical implementation for reproducing paper results (CF-73, HLE).
+
+DeepThonk's contribution is an integration layer: a provider-neutral TypeScript core, an MCP server, a CLI, structured trace artifacts, and budget enforcement. The algorithm itself is theirs.

package/dist/artifacts.d.ts

@@ -0,0 +1,36 @@
+export declare const runArtifactFiles: {
+    readonly config: "config.json";
+    readonly summary: "summary.json";
+    readonly candidates: "candidates.jsonl";
+    readonly comparisons: "comparisons.jsonl";
+    readonly scores: "scores.jsonl";
+    readonly usage: "usage.jsonl";
+    readonly trace: "events.jsonl";
+    readonly final: "artifacts/final.txt";
+    readonly winner: "artifacts/winner.txt";
+    readonly status: "status.json";
+    readonly cancel: "cancel.json";
+    readonly lock: "run.lock";
+};
+export type RunArtifactName = keyof typeof runArtifactFiles;
+export type RunExportFormat = "json" | "markdown" | "jsonl";
+export declare const traceJsonlFiles: readonly ["events.jsonl", "candidates.jsonl", "comparisons.jsonl", "scores.jsonl"];
+export interface ResumeStatus {
+    status: "completed" | "interrupted" | "missing" | "running" | "cancel_requested" | "cancelled" | "failed" | "budget_exceeded" | "resumable";
+    message: string;
+    run_id?: string;
+    phase?: string;
+    generation?: number | "final";
+    safe_to_continue?: boolean;
+}
+export interface RunRecord {
+    run_id: string;
+    run_dir: string;
+}
+export declare function readRunArtifact(runDir: string, artifact: RunArtifactName): Promise<string>;
+export declare function readRunSummary(runDir: string): Promise<Record<string, unknown>>;
+export declare function exportRun(runDir: string, format: RunExportFormat): Promise<Record<string, unknown>>;
+export declare function detectResumeState(runDir: string): Promise<ResumeStatus>;
+export declare function resolveRunDir(runId: string, runsRoot?: string): Promise<string>;
+export declare function listRunRecords(runsRoot?: string): Promise<RunRecord[]>;
+export declare function recordRunIndex(runId: string, runDir: string, runsRoot?: string): Promise<void>;

package/dist/artifacts.js

@@ -0,0 +1,211 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export const runArtifactFiles = {
+    config: "config.json",
+    summary: "summary.json",
+    candidates: "candidates.jsonl",
+    comparisons: "comparisons.jsonl",
+    scores: "scores.jsonl",
+    usage: "usage.jsonl",
+    trace: "events.jsonl",
+    final: "artifacts/final.txt",
+    winner: "artifacts/winner.txt",
+    status: "status.json",
+    cancel: "cancel.json",
+    lock: "run.lock"
+};
+export const traceJsonlFiles = [
+    runArtifactFiles.trace,
+    runArtifactFiles.candidates,
+    runArtifactFiles.comparisons,
+    runArtifactFiles.scores
+];
+export async function readRunArtifact(runDir, artifact) {
+    return readFile(join(runDir, runArtifactFiles[artifact]), "utf8");
+}
+export async function readRunSummary(runDir) {
+    return JSON.parse(await readRunArtifact(runDir, "summary"));
+}
+export async function exportRun(runDir, format) {
+    if (format === "json")
+        return readRunSummary(runDir);
+    if (format === "jsonl") {
+        const text = await Promise.all(traceJsonlFiles.map((file) => readFile(join(runDir, file), "utf8").catch(() => "")));
+        return { jsonl: text.join("") };
+    }
+    if (format !== "markdown")
+        throw new Error(`Unsupported export format: ${format}. Use json, markdown, or jsonl.`);
+    const summary = await readRunSummary(runDir);
+    const final = await readRunArtifact(runDir, "final").catch(() => "");
+    return { markdown: `# DeepThonk Run ${summary.run_id}\n\nWinner: ${summary.winner_id}\n\nCalls: ${summary.calls}\n\n## Final Answer\n\n${final}` };
+}
+export async function detectResumeState(runDir) {
+    try {
+        const summary = await readRunSummary(runDir);
+        return {
+            status: "completed",
+            message: "Run already has summary.json; nothing to resume.",
+            run_id: typeof summary.run_id === "string" ? summary.run_id : undefined,
+            safe_to_continue: false
+        };
+    }
+    catch {
+        const status = await readStatusArtifact(runDir);
+        if (status) {
+            if ((status.state === "running" || status.state === "pending") && isLiveWorker(status.worker_pid)) {
+                return {
+                    status: "running",
+                    message: `Run is ${status.state} at phase ${status.phase}. Use status/result or cancel before starting a replay.`,
+                    run_id: status.run_id,
+                    phase: status.phase,
+                    generation: status.generation,
+                    safe_to_continue: false
+                };
+            }
+            if (status.state === "running" || status.state === "pending") {
+                return {
+                    status: "interrupted",
+                    message: `Run status is stale at phase ${status.phase}; the recorded worker is no longer live.`,
+                    run_id: status.run_id,
+                    phase: status.phase,
+                    generation: status.generation,
+                    safe_to_continue: false
+                };
+            }
+            if (status.state === "cancelled" || status.state === "failed" || status.state === "budget_exceeded") {
+                return {
+                    status: status.state,
+                    message: resumeMessage(status),
+                    run_id: status.run_id,
+                    phase: status.phase,
+                    generation: status.generation,
+                    safe_to_continue: false
+                };
+            }
+        }
+        try {
+            await readRunArtifact(runDir, "cancel");
+            return { status: "cancel_requested", message: "Cancellation has been requested, but no active run status exists.", safe_to_continue: false };
+        }
+        catch {
+            // Continue with trace detection.
+        }
+        try {
+            await readRunArtifact(runDir, "trace");
+            return {
+                status: "interrupted",
+                message: "Interrupted trace detected. Conservative resume is trace-boundary only; this trace has no complete resumable boundary marker.",
+                safe_to_continue: false
+            };
+        }
+        catch {
+            return { status: "missing", message: "No DeepThonk trace found in run directory.", safe_to_continue: false };
+        }
+    }
+}
+async function readStatusArtifact(runDir) {
+    try {
+        return JSON.parse(await readRunArtifact(runDir, "status"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isLiveWorker(pid) {
+    if (!pid)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resumeMessage(status) {
+    const phase = status.phase ? ` at phase ${status.phase}` : "";
+    const error = status.error?.message ? ` Last error: ${status.error.message}` : "";
+    const fix = status.error?.fix ? ` Fix: ${status.error.fix}` : "";
+    return `Run is ${status.state ?? "interrupted"}${phase}.${error}${fix}`;
+}
+export async function resolveRunDir(runId, runsRoot = "runs") {
+    const direct = join(runsRoot, runId);
+    try {
+        await readRunArtifact(direct, "summary");
+        return direct;
+    }
+    catch {
+        // Fall through and scan the run index plus run summaries.
+    }
+    const indexed = await readRunIndex(runId, runsRoot);
+    if (indexed)
+        return indexed;
+    const entries = await readdir(runsRoot, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const candidate = join(runsRoot, entry.name);
+        try {
+            const summary = (await readRunSummary(candidate));
+            if (summary.run_id === runId)
+                return candidate;
+        }
+        catch {
+            // Ignore incomplete or non-DeepThonk directories.
+        }
+    }
+    return direct;
+}
+export async function listRunRecords(runsRoot = "runs") {
+    const records = new Map();
+    for (const entry of await readRunIndexEntries(runsRoot)) {
+        if (!entry.run_id || !entry.run_dir)
+            continue;
+        try {
+            await readRunSummary(entry.run_dir);
+            records.set(entry.run_id, { run_id: entry.run_id, run_dir: entry.run_dir });
+        }
+        catch {
+            // Ignore stale index entries.
+        }
+    }
+    const entries = await readdir(runsRoot, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const runDir = join(runsRoot, entry.name);
+        try {
+            const summary = (await readRunSummary(runDir));
+            const runId = summary.run_id ?? entry.name;
+            records.set(runId, { run_id: runId, run_dir: runDir });
+        }
+        catch {
+            // Ignore incomplete or non-DeepThonk directories.
+        }
+    }
+    return [...records.values()].sort((left, right) => left.run_id.localeCompare(right.run_id));
+}
+export async function recordRunIndex(runId, runDir, runsRoot = "runs") {
+    await mkdir(runsRoot, { recursive: true });
+    await writeFile(join(runsRoot, "index.jsonl"), `${JSON.stringify({ run_id: runId, run_dir: runDir })}\n`, {
+        encoding: "utf8",
+        flag: "a"
+    });
+}
+async function readRunIndex(runId, runsRoot) {
+    const entries = await readRunIndexEntries(runsRoot);
+    return entries.reverse().find((entry) => entry.run_id === runId)?.run_dir;
+}
+async function readRunIndexEntries(runsRoot) {
+    try {
+        const text = await readFile(join(runsRoot, "index.jsonl"), "utf8");
+        return text
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/bradleyTerry.d.ts

@@ -0,0 +1,2 @@
+import type { BtScore, Candidate, Comparison } from "./schemas.js";
+export declare function fitBradleyTerry(candidates: Candidate[] | string[], comparisons: Comparison[], lambda?: number, generation?: number | "final"): BtScore[];