openmerit 0.4.1 → 0.4.2

package/dist/harness/harness.js

@@ -0,0 +1,221 @@
+// OpenMerit Harness: Scout's reasoning steps run on Pi's model runtime. Pi is powered by one of:
+// - Claude Code through pi-claude-bridge, with the machine's Claude Code login;
+// - Codex models through pi's ChatGPT sign-in (`openai-codex`, the login pi's own `/login` uses),
+//   whose tokens pi keeps in ~/.openmerit/agent/auth.json;
+// - a Pi API provider (anthropic, openai, openrouter, ...) with a configured key.
+// Every connection reads the repository only through pi's read-only tools (read, grep, find, ls),
+// which refuse paths outside it. The harness never reads coding-agent credential files, and never
+// switches provider silently.
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { validateToolCall } from "@earendil-works/pi-ai";
+import { createReadOnlyTools, ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { harnessLabel, resolveCredential } from "../state/config.js";
+import { openmeritHome } from "../state/paths.js";
+import { CLAUDE_BRIDGE_PROVIDER, claudeBinary, DEFAULT_CLAUDE_MODEL, inBridgeSession, loadClaudeBridge } from "./claude-bridge.js";
+/** Pi's provider for ChatGPT Plus/Pro sign-ins, which serves Codex models. */
+export const CODEX_PROVIDER = "openai-codex";
+/** Used only when saved settings name no model; `openmerit connect codex` saves the best one the plan accepts. */
+export const DEFAULT_CODEX_MODEL = "gpt-5.6-terra";
+/** Pi's model runtime on OpenMerit's agent directory, ~/.openmerit/agent: auth.json (the ChatGPT sign-in), models.json and the bridge's config. */
+export function harnessRuntime(env = process.env) {
+    const agentDir = env.PI_CODING_AGENT_DIR ?? join(openmeritHome(env), "agent");
+    // The bridge and pi's tools read these from the process environment.
+    process.env.PI_CODING_AGENT_DIR ??= agentDir;
+    process.env.PI_SKIP_VERSION_CHECK ??= "1";
+    return ModelRuntime.create({ authPath: join(agentDir, "auth.json"), modelsPath: join(agentDir, "models.json"), allowModelNetwork: false, refreshOnCreate: false });
+}
+/** True when `path` (a tool argument, relative to `root` or absolute) is inside `root` after resolving symlinks. */
+function insideRoot(root, path) {
+    if (path !== undefined && typeof path !== "string")
+        return false;
+    const raw = (path ?? ".").replace(/^@/, "");
+    if (raw.startsWith("~"))
+        return false;
+    const real = (target) => (existsSync(target) ? realpathSync(target) : target);
+    const base = real(root), target = real(resolve(root, raw || "."));
+    return target === base || target.startsWith(base + sep);
+}
+/** Pi's read-only tools in `root`, refusing paths outside it. */
+function repositoryTools(root) {
+    return createReadOnlyTools(root).map(tool => ({
+        ...tool,
+        execute: (id, params, signal, onUpdate) => {
+            if (!insideRoot(root, params.path))
+                return Promise.reject(new Error(`OpenMerit Harness reads only files inside ${root}.`));
+            return tool.execute(id, params, signal, onUpdate);
+        },
+    }));
+}
+async function runTool(tools, call, signal) {
+    const result = (content, isError) => ({ role: "toolResult", toolCallId: call.id, toolName: call.name, content, isError, timestamp: Date.now() });
+    try {
+        const tool = tools.find(item => item.name === call.name);
+        if (!tool)
+            throw new Error(`Unknown tool ${call.name}`);
+        const output = await tool.execute(call.id, validateToolCall(tools, call), signal);
+        return result(output.content, false);
+    }
+    catch (error) {
+        return result([{ type: "text", text: error instanceof Error ? error.message : String(error) }], true);
+    }
+}
+/** Tool rounds one harness request may take before it is stopped. */
+const MAX_TOOL_ROUNDS = 40;
+/** The first JSON object in a reply, with code fences removed. With `required`, the object must have those keys. */
+export function parseJsonObject(reply, required = []) {
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(reply)?.[1] ?? reply;
+    const start = fenced.indexOf("{");
+    for (let end = fenced.length; start >= 0 && end > start; end--) {
+        let value;
+        try {
+            value = JSON.parse(fenced.slice(start, end));
+        }
+        catch {
+            continue;
+        }
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            break;
+        const missing = required.filter(key => !(key in value));
+        if (missing.length)
+            throw new Error(`The harness reply is missing ${missing.join(", ")}: ${reply.slice(0, 200)}`);
+        return value;
+    }
+    throw new Error(`The harness did not reply with a JSON object: ${reply.slice(0, 200)}`);
+}
+/** Builds the harness from saved settings. Fails clearly, without falling back, when it cannot. */
+export async function createHarness(settings, env = process.env) {
+    const runtime = await harnessRuntime(env);
+    let model;
+    let apiKey;
+    let bridge;
+    if (settings.kind === "api") {
+        if (!settings.api)
+            throw new Error("The API harness has no provider and model. Run `openmerit connect api`.");
+        model = runtime.getModel(settings.api.provider, settings.api.model);
+        if (!model)
+            throw new Error(`Pi does not know ${settings.api.provider}/${settings.api.model}. Run \`openmerit connect api\` to pick another model.`);
+        apiKey = resolveCredential(settings.api.apiKey, env) ?? undefined;
+        if (!apiKey)
+            throw new Error(`The harness API key (${JSON.stringify(settings.api.apiKey)}) is not set. Run \`openmerit connect api\`.`);
+    }
+    else if (settings.kind === "claude-code") {
+        bridge = await loadClaudeBridge();
+        runtime.registerProvider(CLAUDE_BRIDGE_PROVIDER, bridge.provider);
+        model = runtime.getModel(CLAUDE_BRIDGE_PROVIDER, settings.model ?? DEFAULT_CLAUDE_MODEL);
+        if (!model)
+            throw new Error(`Claude Code has no model ${settings.model}. Run \`openmerit connect claude-code --model <id>\` with one of: ${runtime.getModels(CLAUDE_BRIDGE_PROVIDER).map(item => item.id).join(", ")}.`);
+    }
+    else {
+        model = runtime.getModel(CODEX_PROVIDER, settings.model ?? DEFAULT_CODEX_MODEL);
+        if (!model)
+            throw new Error(`Codex has no model ${settings.model}. Run \`openmerit connect codex --model <id>\` with one of: ${runtime.getModels(CODEX_PROVIDER).map(item => item.id).join(", ")}.`);
+        // checkAuth reads the stored credential; hasConfiguredAuth waits for an availability refresh, which create() skips.
+        if (!(await runtime.checkAuth(CODEX_PROVIDER)))
+            throw new Error("OpenMerit is not signed in to ChatGPT. Run `openmerit connect codex`.");
+    }
+    const chosen = model;
+    const usage = { calls: 0, costUsd: 0, unknownCost: 0, inputTokens: 0, outputTokens: 0 };
+    const complete = async (system, messages, tools, input, sessionId) => {
+        const reply = await runtime.complete(chosen, { systemPrompt: system, messages, ...(tools.length ? { tools } : {}) }, { ...(input.signal ? { signal: input.signal } : {}), ...(apiKey ? { apiKey } : {}), sessionId, maxTokens: 16_000 });
+        usage.calls++;
+        // Pi reports cached prompt tokens apart from `input`, which is then only the uncached remainder.
+        usage.inputTokens += reply.usage.input + reply.usage.cacheRead + reply.usage.cacheWrite;
+        usage.outputTokens += reply.usage.output;
+        if (Number.isFinite(reply.usage.cost.total))
+            usage.costUsd += reply.usage.cost.total;
+        else
+            usage.unknownCost++;
+        if (reply.stopReason === "error" || reply.stopReason === "aborted")
+            throw new Error(reply.errorMessage ?? reply.stopReason);
+        return reply;
+    };
+    const replyText = (reply) => reply.content.filter(part => part.type === "text").map(part => part.text).join("");
+    return {
+        kind: settings.kind, label: harnessLabel(settings), usage,
+        async json(input) {
+            const system = `${input.system}\n\nReply with one JSON object that matches this JSON Schema, and nothing else. Give your answer's values, not the schema itself:\n${JSON.stringify(input.schema)}`;
+            const messages = [{ role: "user", content: input.prompt, timestamp: Date.now() }];
+            const tools = input.cwd ? repositoryTools(input.cwd) : [];
+            const sessionId = `openmerit-${randomUUID()}`;
+            const required = Array.isArray(input.schema.required) ? input.schema.required.map(String) : [];
+            const ask = async () => {
+                let reasked = false;
+                for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+                    const reply = await complete(system, messages, tools, input, sessionId);
+                    const calls = reply.content.filter((part) => part.type === "toolCall");
+                    if (reply.stopReason === "toolUse" && calls.length) {
+                        messages.push(reply);
+                        for (const call of calls)
+                            messages.push(await runTool(tools, call, input.signal));
+                        continue;
+                    }
+                    try {
+                        return parseJsonObject(replyText(reply), required);
+                    }
+                    catch (error) {
+                        // Some models echo the schema's "type" and "properties" around their answer and drop a brace: ask once more.
+                        if (reasked)
+                            throw error;
+                        reasked = true;
+                        messages.push(reply, { role: "user", content: `${error instanceof Error ? error.message : String(error)}\nReply again with only the JSON object of your answer's values, without the schema's "type" or "properties".`, timestamp: Date.now() });
+                    }
+                }
+                throw new Error(`OpenMerit Harness stopped after ${MAX_TOOL_ROUNDS} rounds of file reads without an answer.`);
+            };
+            try {
+                // Claude Code: one bridge session per request, so its query starts in the repository and closes afterwards.
+                return bridge ? await inBridgeSession(bridge, { sessionId, cwd: input.cwd ?? tmpdir(), systemPrompt: system, tools: tools.map(tool => tool.name) }, ask) : await ask();
+            }
+            finally {
+                // A refreshed ChatGPT token replaces the old one; save it before the process can exit.
+                await runtime.settleCredentialWrites();
+            }
+        },
+    };
+}
+/** One round trip that proves the configured connection powers the harness. */
+export async function verifyHarness(harness, cwd) {
+    try {
+        const reply = await harness.json({
+            system: "You are OpenMerit Harness checking its connection.", cwd,
+            prompt: "Reply with status \"OPENMERIT_READY\" and, in harness, the name of the model you are.",
+            schema: { type: "object", properties: { status: { type: "string" }, harness: { type: "string" } }, required: ["status", "harness"], additionalProperties: false },
+        });
+        if (reply.status !== "OPENMERIT_READY")
+            return { ok: false, detail: `Unexpected reply ${JSON.stringify(reply).slice(0, 200)}` };
+        return { ok: true, detail: `answered as ${String(reply.harness).slice(0, 80)}` };
+    }
+    catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Runs the Claude Code executable the bridge uses, such as `auth status` or `auth login`. */
+export function runClaude(args, options = {}) {
+    return new Promise((done, reject) => {
+        const child = spawn(claudeBinary(options.env), args, { env: options.env ?? process.env, stdio: options.interactive ? "inherit" : ["ignore", "pipe", "ignore"], ...(options.signal ? { signal: options.signal } : {}) });
+        let stdout = "";
+        child.stdout?.on("data", chunk => { stdout += chunk; });
+        child.on("error", reject);
+        child.on("close", code => done({ code: code ?? 1, stdout }));
+    });
+}
+/** Whether Claude Code reports a login (its own status command), and whether OpenMerit has a ChatGPT sign-in. */
+export async function detectAgents(env = process.env) {
+    let claudeLogin = false;
+    try {
+        claudeLogin = JSON.parse((await runClaude(["auth", "status"], { env, signal: AbortSignal.timeout(20_000) })).stdout).loggedIn === true;
+    }
+    catch { /* no status */ }
+    // Claude Code also runs with ANTHROPIC_API_KEY or a third-party provider; its status only covers logins.
+    if (env.ANTHROPIC_API_KEY || env.CLAUDE_CODE_OAUTH_TOKEN || env.CLAUDE_CODE_USE_BEDROCK || env.CLAUDE_CODE_USE_VERTEX)
+        claudeLogin = true;
+    const codexLogin = (await (await harnessRuntime(env)).checkAuth(CODEX_PROVIDER)) !== undefined;
+    return [
+        { kind: "claude-code", loggedIn: claudeLogin, detail: claudeLogin ? "logged in" : "not logged in" },
+        { kind: "codex", loggedIn: codexLogin, detail: codexLogin ? "signed in to ChatGPT" : "not signed in to ChatGPT" },
+    ];
+}

package/dist/index.d.ts

@@ -1,11 +1,10 @@
-export { rankCandidates, rank, openRouterToolSupport, type Candidate, type CandidateFilter, type RunnableModel } from "./scout/candidates.js";
-export { loadEci, parseEciScores, ECI_ATTRIBUTION, type EciRow, type EciSource } from "./scout/eci.js";
-export { scoutSearch, CandidateUnavailable, outward, compareFinals, meanCost, SAMPLE_SIZE, FINALISTS, type EvalItem, type Evaluate, type Outcome, type SearchOptions, type SearchResult, type Stage, type Trial } from "./scout/search.js";
-export { runScout, type ScoutReport, type ScoutRunOptions, type FinalVerdict, type DatasetSource } from "./scout/pipeline.js";
-export { reportMarkdown } from "./scout/report.js";
-export { piEvaluator, jsonMatches, extractJson, type Grader, type ModelCaller, type PiTaskSpec } from "./scout/evaluators/pi.js";
-export { loadEvaluatorPlugin, type EvaluatorPlugin } from "./scout/evaluators/module.js";
-export * as scout from "./scout/service.js";
-export { createScoutExtension, type ScoutExtensionOptions } from "./pi/extension.js";
-export { configureHarness } from "./pi/harness.js";
+export { loadCatalogue, catalogueIndex, requestPrice, type Catalogue, type CatalogueModel } from "./catalogue/catalogue.js";
+export { rankCandidates, rank, type Candidate, type CandidateFilter, type RunnableModel } from "./scout/candidates.js";
+export { parseEciScores, parseEciEstimates, ECI_ATTRIBUTION, type EciRow, type EciEstimate } from "./scout/eci.js";
+export { scanRepo, redact, type Usage, type ScanResult } from "./scout/scan.js";
+export { advance, eligibleCandidates, TASK_QUESTION, CONFIGURE_QUESTION, type Answers, type Question, type Step, type TaskComparison, type ModelResult } from "./scout/workflow.js";
+export { localContext, missingSetup, startRun } from "./local.js";
+export { createHarness, verifyHarness, detectAgents, type Harness } from "./harness/harness.js";
+export { State, type RunRow, type Spend } from "./state/db.js";
+export { serveMcp } from "./mcp.js";
 export * as langfuse from "./connectors/langfuse/index.js";

package/dist/index.js

@@ -1,11 +1,10 @@
-export { rankCandidates, rank, openRouterToolSupport } from "./scout/candidates.js";
-export { loadEci, parseEciScores, ECI_ATTRIBUTION } from "./scout/eci.js";
-export { scoutSearch, CandidateUnavailable, outward, compareFinals, meanCost, SAMPLE_SIZE, FINALISTS } from "./scout/search.js";
-export { runScout } from "./scout/pipeline.js";
-export { reportMarkdown } from "./scout/report.js";
-export { piEvaluator, jsonMatches, extractJson } from "./scout/evaluators/pi.js";
-export { loadEvaluatorPlugin } from "./scout/evaluators/module.js";
-export * as scout from "./scout/service.js";
-export { createScoutExtension } from "./pi/extension.js";
-export { configureHarness } from "./pi/harness.js";
+export { loadCatalogue, catalogueIndex, requestPrice } from "./catalogue/catalogue.js";
+export { rankCandidates, rank } from "./scout/candidates.js";
+export { parseEciScores, parseEciEstimates, ECI_ATTRIBUTION } from "./scout/eci.js";
+export { scanRepo, redact } from "./scout/scan.js";
+export { advance, eligibleCandidates, TASK_QUESTION, CONFIGURE_QUESTION } from "./scout/workflow.js";
+export { localContext, missingSetup, startRun } from "./local.js";
+export { createHarness, verifyHarness, detectAgents } from "./harness/harness.js";
+export { State } from "./state/db.js";
+export { serveMcp } from "./mcp.js";
 export * as langfuse from "./connectors/langfuse/index.js";

package/dist/local.d.ts

@@ -0,0 +1,12 @@
+import { type Context } from "./scout/workflow.js";
+export interface LocalOptions {
+    cwd: string;
+    env?: Record<string, string | undefined>;
+    log?: (line: string) => void;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+}
+export declare function localContext(options: LocalOptions): Context;
+/** Settings a run needs before it starts; each entry is something `openmerit setup` configures. */
+export declare function missingSetup(ctx: Context): string[];
+export declare function startRun(ctx: Context): string;

package/dist/local.js

@@ -0,0 +1,40 @@
+// What the CLI and the MCP server share: one repository's local context, and starting a run.
+import { loadCatalogue } from "./catalogue/catalogue.js";
+import { createHarness } from "./harness/harness.js";
+import { DEFAULT_BUDGET_USD, harnessLabel, readGlobalConfig, readRepoConfig } from "./state/config.js";
+import { State } from "./state/db.js";
+import { findRepo } from "./state/paths.js";
+import { packageVersion } from "./update.js";
+import { newRunId } from "./scout/workflow.js";
+export function localContext(options) {
+    const env = options.env ?? process.env;
+    const repo = findRepo(options.cwd);
+    let harness = null;
+    return {
+        state: new State(env), repo, catalogue: loadCatalogue(), env, log: options.log ?? (() => { }),
+        ...(options.signal ? { signal: options.signal } : {}), ...(options.fetch ? { fetch: options.fetch } : {}),
+        harness: () => {
+            const settings = readGlobalConfig(env).harness;
+            if (!settings)
+                return Promise.reject(new Error("OpenMerit Harness is not set up. Run `openmerit setup`."));
+            return (harness ??= createHarness(settings, env).catch(error => { harness = null; throw error; }));
+        },
+    };
+}
+/** Settings a run needs before it starts; each entry is something `openmerit setup` configures. */
+export function missingSetup(ctx) {
+    const missing = [];
+    if (!readGlobalConfig(ctx.env).harness)
+        missing.push("harness: choose Claude Code, Codex or an API key to power OpenMerit Harness");
+    if (!(readRepoConfig(ctx.repo.root).endpoints ?? []).length)
+        missing.push("endpoints: add at least one candidate endpoint (default: OpenRouter, every model eligible)");
+    return missing;
+}
+export function startRun(ctx) {
+    const id = newRunId();
+    ctx.state.createRun({
+        id, repo: ctx.repo, packageVersion: packageVersion(), catalogueVersion: ctx.catalogue.version, harness: harnessLabel(readGlobalConfig(ctx.env).harness),
+        budgetUsd: readRepoConfig(ctx.repo.root).budget?.defaultUsd ?? DEFAULT_BUDGET_USD, state: {},
+    });
+    return id;
+}

package/dist/mcp.d.ts

@@ -0,0 +1 @@
+export declare function serveMcp(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream, env?: Record<string, string | undefined>): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,155 @@
+// OpenMerit's local MCP server: newline-delimited JSON-RPC 2.0 over stdio, for Claude Code, Codex and
+// other MCP clients. Stdout carries protocol messages only; progress goes to stderr. It runs the
+// same workflow and SQLite state as the CLI. Questions and approvals come back as structured
+// `questions` for the client to ask the user; the server never prompts on a terminal.
+import { createInterface } from "node:readline";
+import { renderRun, renderStep } from "./cli/render.js";
+import { localContext, missingSetup, startRun } from "./local.js";
+import { advanceInDaemon } from "./daemon/daemon.js";
+import { step } from "./scout/workflow.js";
+import { checkForUpdate, packageVersion, updateNotice } from "./update.js";
+const PROTOCOL = "2025-06-18";
+const TOOLS = [
+    {
+        name: "openmerit_status",
+        title: "OpenMerit status",
+        description: "Read-only. Reports whether OpenMerit is set up for a repository (harness, candidate endpoints, Langfuse, eval budget), the installed package and catalogue versions, and whether a newer openmerit is available.",
+        inputSchema: { type: "object", properties: { cwd: { type: "string", description: "Repository directory (default: the server's working directory)" } }, additionalProperties: false },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: "openmerit_scout",
+        title: "OpenMerit Scout",
+        description: "Runs OpenMerit Scout: scans the repository's model usages, lets the user pick a model and its agents/tasks, runs Scout Model Binary Search with the task's existing eval (the current model on every item, ECI-ranked candidates screened on five items it passes, five finalists on every item; paid model requests, within the run's eval budget; per-item results read back read-only from the Langfuse experiment the eval records, or from the eval's own report), ranks the cheapest finalists at least as good as the current model, and can edit the application's model configuration. Call without runId to start; each call returns `questions` when it needs the user. Show every question (with its detail) to the user and pass their answers back in `answers`, keyed by question id, with the same runId. Never answer approval, budget or configuration questions on the user's behalf. Not read-only: it sends code context to the harness, spends on evals and can change files, each only after the matching approval.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cwd: { type: "string", description: "Repository directory (default: the server's working directory)" },
+                runId: { type: "string", description: "Run to continue; omit to start a new run" },
+                answers: { type: "object", description: "Answers keyed by question id: strings, string arrays, booleans or numbers", additionalProperties: true },
+            },
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    },
+    {
+        name: "openmerit_history",
+        title: "OpenMerit history",
+        description: "Read-only. Lists this repository's Scout runs, including failed, interrupted and budget-paused ones, or shows one run's results, eval runs, spend, budget approvals and configuration decisions.",
+        inputSchema: { type: "object", properties: { cwd: { type: "string" }, runId: { type: "string" } }, additionalProperties: false },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+export async function serveMcp(input = process.stdin, output = process.stdout, env = process.env) {
+    const send = (message) => output.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+    const log = (line) => process.stderr.write(`[openmerit] ${line}\n`);
+    let update = null;
+    const updateCheck = checkForUpdate(env).then(info => { update = info; return info; });
+    const running = new Set();
+    const call = async (name, args) => {
+        const cwd = typeof args.cwd === "string" && args.cwd ? args.cwd : process.cwd();
+        const progress = [];
+        const ctx = localContext({ cwd, env, log: line => { progress.push(line); log(line); } });
+        const notice = update ? updateNotice(update) : null;
+        try {
+            if (name === "openmerit_status") {
+                const missing = missingSetup(ctx);
+                const data = { repository: ctx.repo.root, ready: !missing.length, missing, packageVersion: packageVersion(), catalogueVersion: ctx.catalogue.version, update, history: ctx.state.listRuns(ctx.repo.id, 5).map(run => ({ id: run.id, status: run.status, phase: run.phase })) };
+                return { text: `${missing.length ? `Not ready. Run \`openmerit setup\` in ${ctx.repo.root} for: ${missing.join("; ")}.` : `Ready in ${ctx.repo.root}.`} openmerit ${data.packageVersion}, catalogue ${data.catalogueVersion}.${notice ? ` ${notice}` : ""}`, data };
+            }
+            if (name === "openmerit_history") {
+                ctx.state.reapInterrupted(ctx.repo.id);
+                if (typeof args.runId === "string") {
+                    const run = ctx.state.getRun(args.runId);
+                    if (!run || run.repoId !== ctx.repo.id)
+                        return { text: `No run ${args.runId} in ${ctx.repo.root}.`, data: {}, isError: true };
+                    const current = step(ctx, run.id, [], []);
+                    return { text: renderRun(ctx.state, run, current), data: { run: { ...run, state: undefined }, step: current, units: ctx.state.units(run.id), budget: ctx.state.budgetEvents(run.id), decisions: ctx.state.decisions(run.id) } };
+                }
+                const runs = ctx.state.listRuns(ctx.repo.id);
+                return { text: runs.map(run => `${run.id} ${run.status} ${run.phase} ${run.createdAt}`).join("\n") || "No runs yet.", data: { runs: runs.map(run => ({ id: run.id, status: run.status, phase: run.phase, createdAt: run.createdAt, model: run.state.model ?? null, tasks: run.state.selected ?? [], spend: ctx.state.spend(run.id), budgetUsd: run.budgetUsd, packageVersion: run.packageVersion, catalogueVersion: run.catalogueVersion })) } };
+            }
+            if (name === "openmerit_scout") {
+                const missing = missingSetup(ctx);
+                if (missing.length)
+                    return { text: `OpenMerit is not set up for ${ctx.repo.root}. Ask the user to run \`openmerit setup\` in a terminal there.`, data: { status: "needs_setup", missing } };
+                const runId = typeof args.runId === "string" && args.runId ? args.runId : startRun(ctx);
+                if (running.has(runId))
+                    return { text: `Run ${runId} is already being advanced by another call.`, data: { runId, status: "busy" }, isError: true };
+                running.add(runId);
+                try {
+                    const result = await advanceInDaemon({ runId, cwd, env, answers: (args.answers && typeof args.answers === "object" ? args.answers : {}), log: line => { progress.push(line); log(line); } });
+                    const questions = result.questions.map(question => `- [${question.id}] (${question.kind}) ${question.prompt}${question.options ? `\n  Options: ${question.options.map(option => `${option.value}${option.label !== option.value ? ` = ${option.label}` : ""}`).join(" | ")}` : ""}${question.detail ? `\n  ${question.detail.split("\n").join("\n  ")}` : ""}`).join("\n");
+                    const text = [
+                        ...(notice ? [notice] : []), ...result.notices,
+                        questions ? `Run ${runId} needs the user (${result.status}). Ask them, then call openmerit_scout again with runId "${runId}" and answers keyed by question id:\n${questions}` : renderStep(result),
+                    ].join("\n\n");
+                    return { text, data: { ...result, progress: progress.slice(-40), ...(update ? { update } : {}) }, ...(result.status === "failed" ? { isError: true } : {}) };
+                }
+                finally {
+                    running.delete(runId);
+                }
+            }
+            return { text: `Unknown tool ${name}`, data: {}, isError: true };
+        }
+        finally {
+            ctx.state.close();
+        }
+    };
+    const handle = async (message) => {
+        const id = message.id;
+        const method = message.method;
+        if (!method)
+            return;
+        try {
+            if (method === "initialize") {
+                const info = await Promise.race([updateCheck, new Promise(resolve => setTimeout(() => resolve(null), 3000))]);
+                const notice = info ? updateNotice(info) : null;
+                send({ id, result: { protocolVersion: message.params?.protocolVersion ?? PROTOCOL, capabilities: { tools: {}, logging: {} }, serverInfo: { name: "openmerit", version: packageVersion() },
+                        instructions: `OpenMerit Scout finds cheaper models that perform at least as well as the current one on a repository's own evals. Relay every question it returns to the user.${notice ? ` ${notice}` : ""}` } });
+                return;
+            }
+            if (method === "notifications/initialized") {
+                const info = await updateCheck;
+                const notice = updateNotice(info);
+                if (notice)
+                    send({ method: "notifications/message", params: { level: "warning", logger: "openmerit", data: notice } });
+                return;
+            }
+            if (method === "ping")
+                return void send({ id, result: {} });
+            if (method === "tools/list")
+                return void send({ id, result: { tools: TOOLS } });
+            if (method === "tools/call") {
+                const params = (message.params ?? {});
+                const result = await call(params.name ?? "", params.arguments ?? {});
+                return void send({ id, result: { content: [{ type: "text", text: result.text }], structuredContent: result.data, ...(result.isError ? { isError: true } : {}) } });
+            }
+            if (method === "logging/setLevel")
+                return void send({ id, result: {} });
+            if (id !== undefined)
+                send({ id, error: { code: -32601, message: `Method not found: ${method}` } });
+        }
+        catch (error) {
+            if (id !== undefined)
+                send({ id, result: { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true } });
+        }
+    };
+    const lines = createInterface({ input });
+    const pending = new Set();
+    for await (const line of lines) {
+        if (!line.trim())
+            continue;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            send({ id: null, error: { code: -32700, message: "Parse error" } });
+            continue;
+        }
+        const work = handle(message).finally(() => pending.delete(work));
+        pending.add(work);
+    }
+    await Promise.all(pending);
+}

package/dist/scout/pool.d.ts

@@ -0,0 +1,17 @@
+import { type Catalogue, type CatalogueModel } from "../catalogue/catalogue.js";
+import type { Endpoint } from "../state/config.js";
+export interface PoolModel {
+    endpoint: Endpoint;
+    endpointModel: string;
+    model: CatalogueModel;
+}
+/** How an endpoint names a catalogue model: OpenRouter uses catalogue IDs; OpenAI drops the `openai/` vendor prefix. */
+export declare function endpointModelId(endpoint: Endpoint, model: CatalogueModel): string | null;
+/** Every model an endpoint may run under the repository's allowed list. */
+export declare function endpointPool(endpoint: Endpoint, catalogue: Catalogue): PoolModel[];
+export declare function pool(endpoints: readonly Endpoint[], catalogue: Catalogue): PoolModel[];
+/** The proxy's pool check for one endpoint: catalogue model, null for an allowed model without a catalogue entry, undefined when not allowed. */
+export declare function allowedOn(endpoint: Endpoint, catalogue: Catalogue): (endpointModel: string) => CatalogueModel | null | undefined;
+/** The endpoint that would run the current (baseline) model: the first one that may run it. */
+export declare function baselineEndpoint(endpoints: readonly Endpoint[], catalogue: Catalogue, modelId: string): PoolModel | null;
+export declare const blendedPrice: (model: CatalogueModel) => number | null;

package/dist/scout/pool.js

@@ -0,0 +1,56 @@
+// The repository's candidate pool: which catalogue models each configured endpoint may run.
+import { catalogueIndex } from "../catalogue/catalogue.js";
+/** How an endpoint names a catalogue model: OpenRouter uses catalogue IDs; OpenAI drops the `openai/` vendor prefix. */
+export function endpointModelId(endpoint, model) {
+    if (endpoint.kind === "openrouter")
+        return model.id;
+    if (endpoint.kind === "openai")
+        return model.id.startsWith("openai/") ? model.id.slice("openai/".length) : null;
+    return null;
+}
+/** Every model an endpoint may run under the repository's allowed list. */
+export function endpointPool(endpoint, catalogue) {
+    const index = catalogueIndex(catalogue);
+    if (endpoint.allowedModels === "all") {
+        if (endpoint.kind === "openai-compatible")
+            return [];
+        return catalogue.models.flatMap(model => {
+            const endpointModel = endpointModelId(endpoint, model);
+            return endpointModel ? [{ endpoint, endpointModel, model }] : [];
+        });
+    }
+    return endpoint.allowedModels.flatMap(id => {
+        const model = index.find(id) ?? index.find(`${endpoint.kind === "openai" ? "openai/" : ""}${id}`);
+        if (!model)
+            return [];
+        const endpointModel = endpoint.kind === "openai-compatible" ? id : endpointModelId(endpoint, model);
+        return endpointModel ? [{ endpoint, endpointModel, model }] : [];
+    });
+}
+export function pool(endpoints, catalogue) {
+    const seen = new Set();
+    return endpoints.flatMap(endpoint => endpointPool(endpoint, catalogue)).filter(item => !seen.has(item.model.id) && seen.add(item.model.id));
+}
+/** The proxy's pool check for one endpoint: catalogue model, null for an allowed model without a catalogue entry, undefined when not allowed. */
+export function allowedOn(endpoint, catalogue) {
+    const allowed = new Map(endpointPool(endpoint, catalogue).map(item => [item.endpointModel.toLowerCase(), item.model]));
+    const explicit = endpoint.allowedModels === "all" ? null : new Set(endpoint.allowedModels.map(item => item.toLowerCase()));
+    return model => allowed.get(model.toLowerCase()) ?? (explicit?.has(model.toLowerCase()) ? null : undefined);
+}
+/** The endpoint that would run the current (baseline) model: the first one that may run it. */
+export function baselineEndpoint(endpoints, catalogue, modelId) {
+    for (const endpoint of endpoints) {
+        const match = endpointPool(endpoint, catalogue).find(item => item.model.id === modelId);
+        if (match)
+            return match;
+    }
+    // The baseline must run even when the allowed list leaves it out: it is the model already in production.
+    const model = catalogue.models.find(item => item.id === modelId);
+    for (const endpoint of endpoints) {
+        const endpointModel = model ? endpointModelId(endpoint, model) : null;
+        if (model && endpointModel)
+            return { endpoint, endpointModel, model };
+    }
+    return null;
+}
+export const blendedPrice = (model) => (model.inputPerM === null || model.outputPerM === null ? null : model.inputPerM + model.outputPerM);

package/dist/scout/scan.d.ts

@@ -0,0 +1,42 @@
+import { type Catalogue } from "../catalogue/catalogue.js";
+export interface Usage {
+    id: string;
+    kind: "model" | "endpoint";
+    file: string;
+    line: number;
+    /** The literal value (model ID or URL), or the expression for a dynamic use. Redacted. */
+    value: string;
+    /** Set when the value is computed at run time (an environment variable, a variable, a function call). */
+    dynamic: boolean;
+    /** Environment variable a dynamic use reads, when the code names one. */
+    envVar?: string;
+    /** Catalogue model this literal names, or null for an unknown model or an endpoint. */
+    catalogueId: string | null;
+    /** The line, redacted. */
+    snippet: string;
+}
+export interface ScanResult {
+    files: number;
+    usages: Usage[];
+    /** Catalogue models found, with their usage IDs. */
+    models: {
+        catalogueId: string | null;
+        value: string;
+        usageIds: string[];
+    }[];
+    /** JSON files skipped as data because they name more than MAX_DATA_FILE_MODELS models. */
+    skipped: string[];
+}
+export interface ScanOptions {
+    /** Glob patterns, relative to the repository root, of files or directories not to scan. */
+    exclude?: string[];
+}
+/** More model usages than this in one JSON file make it data rather than configuration. */
+export declare const MAX_DATA_FILE_MODELS = 20;
+/** Replaces key- and token-shaped text with [redacted]. */
+export declare function redact(text: string): string;
+export declare function listFiles(root: string): string[];
+/** Scans the repository. Deterministic; no model is called. */
+export declare function scanRepo(root: string, catalogue: Catalogue, options?: ScanOptions): ScanResult;
+/** A few lines around a usage, redacted, for the harness. */
+export declare function context(root: string, usage: Pick<Usage, "file" | "line">, radius?: number): string;