@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/src/harness/deepseek-adapter.js

@@ -0,0 +1,102 @@
+/**
+ * deepseek-adapter — routes a task to a DeepSeek model, either:
+ *   - direct DeepSeek API (DEEPSEEK_API_KEY), or
+ *   - OpenRouter (OPENROUTER_API_KEY) using a deepseek/* route
+ *
+ * Cost-optimized alternative to the local opencode harness: one stateless chat
+ * completion per task with per-task token + cost tracking. No tool use /
+ * filesystem access, so registry policy routes tool-dependent tasks to opencode.
+ */
+import { HarnessAdapter, baseResult, nowIso } from "./types.js";
+import {
+  chatCompletion, computeCost, isPeakNow, defaultModel, probe,
+  resolveProvider, providerKey, DEEPSEEK_MODELS, OPENROUTER_MODELS,
+} from "./deepseek.js";
+
+export class DeepSeekAdapter extends HarnessAdapter {
+  constructor(opts = {}) {
+    super({ id: "deepseek", label: "DeepSeek (cost-optimized)", ...opts });
+    this.provider = opts.provider || resolveProvider();
+    this.apiKey = opts.apiKey || providerKey(this.provider);
+  }
+
+  capabilities() {
+    const table = this.provider === "openrouter" ? OPENROUTER_MODELS : DEEPSEEK_MODELS;
+    const m = table[defaultModel(this.provider)];
+    const costIn = this.provider === "openrouter" ? (m?.input ?? 0.051) : (m?.inPeak ?? 0.30);
+    const costOut = this.provider === "openrouter" ? (m?.output ?? 0.567) : (m?.outPeak ?? 1.20);
+    return {
+      streaming: false,
+      checkpoint: false,   // stateless API — nothing to resume
+      cancel: true,        // AbortSignal per request
+      files: false,        // no filesystem access
+      tools: false,        // pure completion, no tool calls in v1
+      modelChoice: true,
+      provider: this.provider,
+      costPerMTokIn: costIn,
+      costPerMTokOut: costOut,
+    };
+  }
+
+  async status() {
+    if (!this.apiKey) {
+      const envName = this.provider === "openrouter" ? "OPENROUTER_API_KEY" : "DEEPSEEK_API_KEY";
+      return { ready: false, reason: `missing ${envName}`, detail: `add ${envName} to ~/.huckleberry/.env` };
+    }
+    const p = await probe(this.apiKey, this.provider);
+    if (!p.ok) return { ready: false, reason: `${this.provider} probe failed: ${p.error}`, detail: "check key/network/credits" };
+    return { ready: true, detail: `${this.provider} · ${p.models.length} models · ${defaultModel(this.provider)}` };
+  }
+
+  /**
+   * @param {import("./types.js").TaskRequest} task
+   * @returns {Promise<import("./types.js").TaskResult>}
+   */
+  async submit(task) {
+    const started = Date.now();
+    const out = baseResult({ ...task, adapterId: this.id });
+    const model = task.model || defaultModel(this.provider);
+    if (!this.apiKey) {
+      out.status = "error";
+      out.error = `${this.provider === "openrouter" ? "OPENROUTER_API_KEY" : "DEEPSEEK_API_KEY"} not set — cannot run deepseek adapter`;
+      out.durationMs = Date.now() - started;
+      return out;
+    }
+    try {
+      const messages = [];
+      if (task.system) messages.push({ role: "system", content: task.system });
+      messages.push({ role: "user", content: task.prompt });
+      const r = await chatCompletion({
+        provider: this.provider,
+        apiKey: this.apiKey,
+        model,
+        messages,
+        maxTokens: task.maxTokens || 4096,
+        timeoutMs: task.timeoutMs || 180000,
+      });
+      out.output = r.content;
+      out.model = r.model;
+      const cacheHit = r.usage.prompt_cache_hit_tokens ?? r.usage.cache_read_input_tokens ?? 0;
+      out.usage = {
+        input: r.usage.prompt_tokens || 0,
+        output: r.usage.completion_tokens || 0,
+        cacheHit,
+        cacheMiss: r.usage.prompt_cache_miss_tokens ?? Math.max(0, (r.usage.prompt_tokens || 0) - cacheHit),
+      };
+      out.costUsd = computeCost({ model: r.model, usage: r.usage }, !isPeakNow(), this.provider);
+      out.status = out.output ? "ok" : "error";
+      if (!out.output) out.error = "empty completion (model returned no content)";
+    } catch (e) {
+      out.status = "error";
+      out.error = e.message;
+    }
+    out.durationMs = Date.now() - started;
+    out.startedAt = nowIso();
+    return out;
+  }
+
+  async cancel(_taskId) {
+    // stateless: each call uses its own AbortSignal; nothing to cancel post-hoc
+    return false;
+  }
+}

package/src/harness/deepseek.js

@@ -0,0 +1,225 @@
+/**
+ * DeepSeek client — OpenAI-compatible, two providers:
+ *   - direct:  https://api.deepseek.com   (needs DEEPSEEK_API_KEY)
+ *   - openrouter: https://openrouter.ai/api/v1 (needs OPENROUTER_API_KEY)
+ *
+ * Direct DeepSeek pricing (per 1M tokens, verified api-docs.deepseek.com 2026-11-04):
+ *   deepseek-flash:  in $0.15 off-peak / $0.30 peak (cache hit: $0.003/$0.006) · out $0.60/$1.20
+ *   deepseek-v4-pro: in $0.66 off-peak / $1.32 peak (cache hit: $0.022/$0.044) · out $1.98/$3.96
+ * Off-peak = all hours except 01:00-04:00 & 06:00-10:00 UTC Mon-Fri (excluding CN holidays).
+ *
+ * OpenRouter pricing differs per model route and is fetched live where possible;
+ * the table below is a fallback snapshot (verified via /models 2026-11-06, $/1M tok).
+ */
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Load key=value pairs from ~/.huckleberry/.env into a flat object. The harness
+ * runs as a subprocess that does not inherit a user's shell env, so credentials
+ * written by `huckleberry install` must be read from the state file.
+ * @returns {Record<string,string>}
+ */
+export function loadHarnessEnv() {
+  const out = {};
+  const root = process.env.HUCKLEBERRY_HOME || homedir();
+  const envPath = join(root, ".huckleberry", ".env");
+  if (!existsSync(envPath)) return out;
+  try {
+    for (const line of readFileSync(envPath, "utf8").split("\n")) {
+      const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+      if (m && m[2]) out[m[1]] = m[2].replace(/^["']|["']$/g, "").trim();
+    }
+  } catch { /* unreadable — treat as empty */ }
+  return out;
+}
+
+/**
+ * Merged env for credential resolution. Precedence: ~/.huckleberry/.env WINS over
+ * ambient process env for credential keys. Rationale: the install's own .env is the
+ * documented place keys are set, and an unrelated ambient OPENROUTER_API_KEY (e.g.
+ * from a workspace .env with an expired key) must not silently break the harness.
+ * Per-task overrides are passed explicitly via TaskRequest.env.
+ */
+function envWithFile() {
+  return { ...process.env, ...loadHarnessEnv() };
+}
+
+export const DEEPSEEK_BASE_URL = process.env.DEEPSEEK_BASE_URL || "https://api.deepseek.com";
+export const OPENROUTER_BASE_URL = process.env.OPENROUTER_BASE_URL || "https://openrouter.ai/api/v1";
+
+export const DEEPSEEK_MODELS = {
+  "deepseek-flash": {
+    inPeak: 0.30, inOffPeak: 0.15, inCacheHitPeak: 0.006, inCacheHitOffPeak: 0.003,
+    outPeak: 1.20, outOffPeak: 0.60,
+  },
+  "deepseek-v4-pro": {
+    inPeak: 1.32, inOffPeak: 0.66, inCacheHitPeak: 0.044, inCacheHitOffPeak: 0.022,
+    outPeak: 3.96, outOffPeak: 1.98,
+  },
+};
+
+/**
+ * OpenRouter route pricing ($/1M tok). Snapshot 2026-11-06; used when the live
+ * /models lookup has not run. `input`/`output` are list prices, cache reads billed lower.
+ */
+export const OPENROUTER_MODELS = {
+  "deepseek/deepseek-v4.1-flash": { input: 0.051, output: 0.567, cacheRead: 0.0102 },
+  "deepseek/deepseek-v4.1-flash-1017": { input: 0.15, output: 0.60, cacheRead: 0.03 },
+  "deepseek/deepseek-v4-pro": { input: 0.88, output: 1.76, cacheRead: 0.176 },
+  "deepseek/deepseek-v4-pro-0813": { input: 0.1165, output: 4.66, cacheRead: 0.0233 },
+  "deepseek/deepseek-v3.2": { input: 0.26, output: 0.38, cacheRead: 0.052 },
+};
+
+/** Resolve the active provider from env (process env + ~/.huckleberry/.env). Defaults to direct DeepSeek. */
+export function resolveProvider(env = envWithFile()) {
+  const explicit = (env.HUCKLEBERRY_DEEPSEEK_PROVIDER || "").toLowerCase();
+  if (explicit === "openrouter" || explicit === "deepseek") return explicit;
+  if (env.DEEPSEEK_API_KEY) return "deepseek";
+  if (env.OPENROUTER_API_KEY) return "openrouter";
+  return "deepseek";
+}
+
+export function providerKey(provider = resolveProvider()) {
+  const env = envWithFile();
+  return provider === "openrouter"
+    ? (env.OPENROUTER_API_KEY || "")
+    : (env.DEEPSEEK_API_KEY || "");
+}
+
+export function providerBaseUrl(provider = resolveProvider()) {
+  return provider === "openrouter" ? OPENROUTER_BASE_URL : DEEPSEEK_BASE_URL;
+}
+
+export function defaultModel(provider = resolveProvider()) {
+  const env = envWithFile();
+  if (provider === "openrouter") return env.DEEPSEEK_MODEL || "deepseek/deepseek-v4.1-flash";
+  return env.DEEPSEEK_MODEL || "deepseek-flash";
+}
+
+/** Peak windows: 01:00-04:00 and 06:00-10:00 UTC, Mon-Fri. */
+export function isPeakNow(date = new Date()) {
+  const d = date.getUTCDay();
+  const h = date.getUTCHours();
+  if (d === 0 || d === 6) return false; // weekends always off-peak
+  return (h >= 1 && h < 4) || (h >= 6 && h < 10);
+}
+
+/**
+ * Compute USD cost from token usage.
+ * - direct provider: peak rates unless offPeak=true
+ * - openrouter provider: list prices from OPENROUTER_MODELS (input/output + cache read)
+ * @param {{model:string, usage:Object}} r
+ * @param {boolean} [offPeak]
+ * @param {string} [provider]
+ * @returns {number} cost in USD (6dp)
+ */
+export function computeCost(r, offPeak = !isPeakNow(), provider = resolveProvider()) {
+  if (provider === "openrouter") {
+    const p = OPENROUTER_MODELS[r.model] || OPENROUTER_MODELS[defaultModel("openrouter")] || { input: 0.051, output: 0.567, cacheRead: 0.01 };
+    const hit = r.usage.prompt_cache_hit_tokens || r.usage.cache_read_input_tokens || 0;
+    const miss = r.usage.prompt_cache_miss_tokens ?? Math.max(0, (r.usage.prompt_tokens || 0) - hit);
+    const cost = (hit / 1e6) * p.cacheRead + (miss / 1e6) * p.input + ((r.usage.completion_tokens || 0) / 1e6) * p.output;
+    return Math.round(cost * 1e6) / 1e6;
+  }
+  const p = DEEPSEEK_MODELS[r.model] || DEEPSEEK_MODELS[defaultModel("deepseek")];
+  const hit = r.usage.prompt_cache_hit_tokens || 0;
+  const miss = r.usage.prompt_cache_miss_tokens ?? Math.max(0, (r.usage.prompt_tokens || 0) - hit);
+  const inRate = offPeak ? p.inOffPeak : p.inPeak;
+  const hitRate = offPeak ? p.inCacheHitOffPeak : p.inCacheHitPeak;
+  const outRate = offPeak ? p.outOffPeak : p.outPeak;
+  const cost = (hit / 1e6) * hitRate + (miss / 1e6) * inRate + ((r.usage.completion_tokens || 0) / 1e6) * outRate;
+  return Math.round(cost * 1e6) / 1e6;
+}
+
+/**
+ * Minimal OpenAI-compatible chat completions call. Works against DeepSeek direct
+ * and OpenRouter (same wire shape). OpenRouter additionally accepts attribution headers.
+ * @param {Object} opts
+ * @param {string} [opts.apiKey]   defaults to provider key from env
+ * @param {string} [opts.provider] "deepseek" | "openrouter"
+ * @param {Array<{role:string, content:string}>} opts.messages
+ * @param {string} [opts.model]
+ * @param {number} [opts.maxTokens]
+ * @param {number} [opts.temperature]
+ * @param {number} [opts.timeoutMs] default 120000
+ * @param {string} [opts.baseUrl]
+ * @returns {Promise<{content:string, usage:Object, model:string, raw:Object}>}
+ */
+export async function chatCompletion(opts) {
+  const provider = opts.provider || resolveProvider();
+  const model = opts.model || defaultModel(provider);
+  const apiKey = opts.apiKey || providerKey(provider);
+  const baseUrl = opts.baseUrl || providerBaseUrl(provider);
+  const headers = { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` };
+  if (provider === "openrouter") {
+    headers["HTTP-Referer"] = "https://huckleberry.ai";
+    headers["X-Title"] = "Huckleberry Harness";
+  }
+  const res = await fetch(`${baseUrl}/chat/completions`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      model,
+      messages: opts.messages,
+      // Some routes require an explicit cap; default keeps replies bounded.
+      max_tokens: opts.maxTokens || 4096,
+      ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
+      stream: false,
+    }),
+    signal: AbortSignal.timeout(opts.timeoutMs || 120000),
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    const err = new Error(`${provider} API ${res.status}: ${body.slice(0, 400)}`);
+    err.status = res.status;
+    throw err;
+  }
+  const json = await res.json();
+  const msg = json.choices?.[0]?.message || {};
+  // Some reasoning models put the answer in `content`, others only in `reasoning`.
+  const content = msg.content || msg.reasoning || "";
+  return {
+    content,
+    usage: json.usage || {},
+    model: json.model || model,
+    raw: json,
+  };
+}
+
+/**
+ * Wire-format smoke test: cheap GET /models probe against the active provider.
+ * @param {string} [apiKey]
+ * @param {string} [provider]
+ * @returns {Promise<{ok:boolean, models?:string[], error?:string, provider?:string}>}
+ */
+export async function probe(apiKey, provider = resolveProvider()) {
+  const key = apiKey || providerKey(provider);
+  const baseUrl = providerBaseUrl(provider);
+  try {
+    const res = await fetch(`${baseUrl}/models`, {
+      headers: { Authorization: `Bearer ${key}` },
+      signal: AbortSignal.timeout(15000),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      return { ok: false, error: `HTTP ${res.status}${body ? `: ${body.slice(0, 120)}` : ""}`, provider };
+    }
+    const json = await res.json();
+    return { ok: true, models: (json.data || []).map(m => m.id), provider };
+  } catch (e) {
+    return { ok: false, error: e.message, provider };
+  }
+}
+
+/**
+ * Save a captured API exchange as a fixture (for wire-format tests without API calls).
+ * @param {string} dir output dir
+ * @param {string} name fixture name
+ * @param {Object} obj the response JSON (never includes the key)
+ */
+export function saveFixture(dir, name, obj) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${name}.json`), JSON.stringify(obj, null, 2));
+}

package/src/harness/opencode-adapter.js

@@ -0,0 +1,174 @@
+/**
+ * opencode-adapter — DEFAULT harness. Wraps the existing `opencode run` behavior.
+ *
+ * CRITICAL: this adapter must be a NO-OP for existing installs. It invokes the
+ * same `opencode run "<prompt>"` command the CLI already used for `cro`/`review`,
+ * with the same default (no explicit model/agent unless the task sets one). No new
+ * env vars are required; if opencode is absent the adapter reports not-ready and
+ * the CLI falls back exactly as before.
+ */
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { tmpdir, homedir } from "node:os";
+import { mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { HarnessAdapter, baseResult, nowIso } from "./types.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Neutral working directory so opencode does not load a host repo's context. */
+const NEUTRAL_CWD = join(tmpdir(), "huckleberry-harness");
+function neutralCwd() {
+  try { mkdirSync(NEUTRAL_CWD, { recursive: true }); } catch { /* exists */ }
+  return NEUTRAL_CWD;
+}
+
+/**
+ * Resolve the opencode binary against PATH plus common install dirs, so the
+ * adapter works from processes (cron, sandbox runners) that lack the shell PATH.
+ */
+function opencodeBin() {
+  const extra = [
+    join(homedir(), ".opencode", "bin"),
+    "/usr/local/bin",
+    "/opt/homebrew/bin",
+    join(homedir(), ".bun", "bin"),
+  ];
+  for (const d of extra) {
+    const p = join(d, "opencode");
+    if (existsSync(p)) return p;
+  }
+  return "opencode"; // fall back to PATH lookup
+}
+
+const DEFAULT_TIMEOUT_MS = 900000; // 15 min — opencode cold boot + agent work
+
+function runOpenCode(args, cwd, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(opencodeBin(), args, {
+      cwd,
+      env: { ...process.env, PATH: process.env.PATH + ":" + join(homedir(), ".opencode", "bin") },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "", stderr = "";
+    child.stdout.on("data", d => { stdout += d; });
+    child.stderr.on("data", d => { stderr += d; });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(Object.assign(new Error("timeout"), { stdout, stderr, code: "ETIMEDOUT" }));
+    }, timeoutMs);
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (code === 0) resolve({ stdout, stderr });
+      else reject(Object.assign(new Error(`exit ${code}${signal ? ` (${signal})` : ""}`), { stdout, stderr, code, signal }));
+    });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+  });
+}
+
+export class OpenCodeAdapter extends HarnessAdapter {
+  constructor(opts = {}) {
+    super({ id: "opencode", label: "opencode CLI (local, default)", ...opts });
+    /** @type {Map<string, {task:Object, output:string, startedAt:string}>} */
+    this.checkpoints = new Map();
+  }
+
+  capabilities() {
+    return {
+      streaming: false,      // opencode run prints at the end; we capture stdout
+      checkpoint: true,      // we snapshot the task for re-run
+      cancel: true,
+      files: true,
+      tools: true,           // full agent with tool/filesystem access
+      modelChoice: true,     // via --model / named agent
+      costPerMTokIn: 0,      // local engine — no per-token charge (uses the user's provider)
+      costPerMTokOut: 0,
+    };
+  }
+
+  async status() {
+    try {
+      const { stdout } = await execFileAsync(opencodeBin(), ["--version"], { timeout: 20000 });
+      return { ready: true, detail: `opencode ${stdout.trim()}` };
+    } catch (e) {
+      return { ready: false, reason: "opencode not on PATH", detail: "npm install -g opencode" };
+    }
+  }
+
+  /**
+   * @param {import("./types.js").TaskRequest} task
+   * @returns {Promise<import("./types.js").TaskResult>}
+   */
+  async submit(task) {
+    const started = Date.now();
+    const out = baseResult({ ...task, adapterId: this.id });
+    // Run from a NEUTRAL cwd by default: running opencode inside the clawd workspace
+    // loads its full AGENTS.md + 200+ skills and can exceed any sane timeout. The
+    // harness task carries its own prompt; it doesn't need the caller's repo context.
+    const runCwd = task.cwd || neutralCwd();
+    const args = ["run"];
+    // Harness tasks are execution tasks — use build agent (not plan) to get output.
+    if (!task.agent) args.push("--agent", "build");
+    if (task.agent) args.push("--agent", task.agent);
+    if (task.model) args.push("--model", task.model);
+    args.push(task.prompt);
+
+    try {
+      const { stdout, stderr } = await runOpenCode(args, runCwd, task.timeoutMs || DEFAULT_TIMEOUT_MS);
+      out.output = stdout.trim();
+      out.status = "ok";
+      // opencode prints MCP boot noise to stderr; keep it as a diagnostic, not an error
+      if (stderr?.trim()) out.stderr = stderr.trim();
+      // opencode merges usage into stderr on some versions; parse if present
+      const usage = parseOpenCodeUsage(stdout + "\n" + stderr);
+      if (usage) out.usage = usage;
+    } catch (e) {
+      out.status = "error";
+      out.error = e.message;
+      out.output = (e.stdout || "").trim();
+    }
+    out.durationMs = Date.now() - started;
+    out.startedAt = nowIso();
+    // checkpoint snapshot (enables resume = re-run)
+    this.checkpoints.set(task.id, { task, output: out.output, startedAt: out.startedAt });
+    out.checkpointId = task.id;
+    return out;
+  }
+
+  async cancel(_taskId) {
+    // spawn() children can't be signalled from here without keeping handles;
+    // the runOpenCode timeout already caps run time.
+    return false;
+  }
+
+  async checkpoint(taskId) {
+    return this.checkpoints.has(taskId) ? taskId : null;
+  }
+
+  async resume(checkpointId) {
+    const cp = this.checkpoints.get(checkpointId);
+    if (!cp) throw new Error(`opencode: no checkpoint ${checkpointId}`);
+    return this.submit(cp.task); // local engine: resume == re-run
+  }
+
+  async downloadFiles(taskId) {
+    const cp = this.checkpoints.get(taskId);
+    if (!cp) return [];
+    // opencode writes files itself; we report the cwd the task ran in as the search root
+    return [];
+  }
+}
+
+/**
+ * Best-effort parse of token usage from opencode output. Returns null when absent
+ * (older versions print nothing) — callers treat 0 usage as "unavailable".
+ * @param {string} text
+ */
+function parseOpenCodeUsage(text) {
+  const m = text.match(/tokens?:?\s*(\d+)\s*(?:in|input)[^\d]*(\d+)\s*(?:out|output)/i);
+  if (m) return { input: Number(m[1]), output: Number(m[2]) };
+  return null;
+}

package/src/harness/pi-adapter.js

@@ -0,0 +1,172 @@
+/**
+ * pi-adapter — routes a task to the Pi coding-agent CLI (earendil-works/pi).
+ *
+ * WHY: Pi ships a markedly smaller cold-start prompt than opencode (benchmark
+ * discussion #6646: Pi ~2.8k first-turn input tokens vs opencode ~12.4k, ~5 tools
+ * vs ~12). For many short cold sessions that 4x overhead gap dominates cost. For
+ * long cached sessions opencode can be cheaper per turn, so harness selection is
+ * workload-dependent — this adapter makes that choice available.
+ *
+ * Install: npm install -g @earendil-works/pi-coding-agent   (binary: `pi`)
+ * Model selection: pass task.model as `provider/id` (e.g. deepseek/deepseek-v4.1-flash).
+ * Auth: Pi reads provider creds from its own config/`pi auth`; OPENROUTER_API_KEY is
+ * honoured via `--api-key` override when provided through task.env.
+ */
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { tmpdir, homedir } from "node:os";
+import { mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { HarnessAdapter, baseResult, nowIso } from "./types.js";
+import { loadHarnessEnv } from "./deepseek.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Resolve the OpenRouter key: huckleberry .env wins over ambient env. */
+function openRouterKey() {
+  const env = { ...process.env, ...loadHarnessEnv() };
+  return env.OPENROUTER_API_KEY || "";
+}
+
+const NEUTRAL_CWD = join(tmpdir(), "huckleberry-harness-pi");
+function neutralCwd() {
+  try { mkdirSync(NEUTRAL_CWD, { recursive: true }); } catch { /* exists */ }
+  return NEUTRAL_CWD;
+}
+
+function piBin() {
+  const extra = [
+    join(homedir(), ".npm-global", "bin"),
+    join(homedir(), ".local", "bin"),
+    "/usr/local/bin",
+    "/opt/homebrew/bin",
+    join(homedir(), ".bun", "bin"),
+  ];
+  for (const d of extra) {
+    const p = join(d, "pi");
+    if (existsSync(p)) return p;
+  }
+  return "pi";
+}
+
+const DEFAULT_TIMEOUT_MS = 900000;
+
+/**
+ * Model id default. pi requires a provider-qualified id; we default to the
+ * OpenRouter route so a single OpenRouter key drives all adapters consistently.
+ */
+function piDefaultModel() {
+  const env = process.env;
+  if (env.PI_MODEL) return env.PI_MODEL;
+  if (env.DEEPSEEK_MODEL && env.DEEPSEEK_MODEL.includes("/")) return env.DEEPSEEK_MODEL;
+  return "openrouter/deepseek/deepseek-v4.1-flash";
+}
+
+function runPi(args, cwd, timeoutMs, env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(piBin(), args, {
+      cwd,
+      env: { ...process.env, ...(env || {}) },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "", stderr = "";
+    child.stdout.on("data", d => { stdout += d; });
+    child.stderr.on("data", d => { stderr += d; });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(Object.assign(new Error("timeout"), { stdout, stderr, code: "ETIMEDOUT" }));
+    }, timeoutMs);
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (code === 0) resolve({ stdout, stderr });
+      else reject(Object.assign(new Error(`exit ${code}${signal ? ` (${signal})` : ""}`), { stdout, stderr, code, signal }));
+    });
+    child.on("error", (e) => { clearTimeout(timer); reject(e); });
+  });
+}
+
+export class PiAdapter extends HarnessAdapter {
+  constructor(opts = {}) {
+    super({ id: "pi", label: "Pi coding agent (lean cold-start)", ...opts });
+    this.checkpoints = new Map();
+  }
+
+  capabilities() {
+    return {
+      streaming: false,
+      checkpoint: true,   // snapshot for re-run
+      cancel: true,
+      files: true,        // Pi is a coding agent with filesystem tools
+      tools: true,
+      modelChoice: true,  // --model provider/id
+      costPerMTokIn: 0,   // local engine — cost is the routed model's, not Pi's
+      costPerMTokOut: 0,
+    };
+  }
+
+  async status() {
+    try {
+      const { stdout } = await execFileAsync(piBin(), ["--version"], { timeout: 20000 });
+      return { ready: true, detail: `pi ${stdout.trim()}` };
+    } catch (e) {
+      return { ready: false, reason: "pi not installed", detail: "npm install -g @earendil-works/pi-coding-agent" };
+    }
+  }
+
+  /**
+   * @param {import("./types.js").TaskRequest} task
+   * @returns {Promise<import("./types.js").TaskResult>}
+   */
+  async submit(task) {
+    const started = Date.now();
+    const out = baseResult({ ...task, adapterId: this.id });
+    // Print mode: non-interactive, single-shot. --print emits only the answer.
+    // Pi resolves models as `provider/id`; our default pins the OpenRouter route.
+    const args = ["--print"];
+    const model = task.model || piDefaultModel();
+    args.push("--model", model);
+    const key = task.env?.OPENROUTER_API_KEY || openRouterKey();
+    if (key) args.push("--api-key", key);
+    args.push(task.prompt);
+
+    try {
+      const { stdout, stderr } = await runPi(args, task.cwd || neutralCwd(), task.timeoutMs || DEFAULT_TIMEOUT_MS, task.env);
+      out.output = stdout.trim();
+      out.status = "ok";
+      if (stderr?.trim()) out.stderr = stderr.trim();
+      const usage = parsePiUsage(stderr + "\n" + stdout);
+      if (usage) out.usage = usage;
+    } catch (e) {
+      out.status = "error";
+      out.error = e.message;
+      out.output = (e.stdout || "").trim();
+    }
+    out.durationMs = Date.now() - started;
+    out.startedAt = nowIso();
+    this.checkpoints.set(task.id, { task, output: out.output, startedAt: out.startedAt });
+    out.checkpointId = task.id;
+    return out;
+  }
+
+  async cancel(_taskId) { return false; }
+
+  async checkpoint(taskId) { return this.checkpoints.has(taskId) ? taskId : null; }
+
+  async resume(checkpointId) {
+    const cp = this.checkpoints.get(checkpointId);
+    if (!cp) throw new Error(`pi: no checkpoint ${checkpointId}`);
+    return this.submit(cp.task);
+  }
+
+  async downloadFiles(_taskId) { return []; }
+}
+
+/**
+ * Best-effort token parse from pi output (varies by version). Null when absent.
+ * @param {string} text
+ */
+function parsePiUsage(text) {
+  const m = text.match(/input[^\d]*(\d+)[^\d]*output[^\d]*(\d+)/i) || text.match(/(\d+)\s*(?:in|input)[^\d]*(\d+)\s*(?:out|output)/i);
+  if (m) return { input: Number(m[1]), output: Number(m[2]) };
+  return null;
+}