@pome-sh/cli 0.1.0

package/dist/src/runner/runTrialGroup.js

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: Apache-2.0
+// FDRS-636 — `pome run <task> -n k`: real trial groups end-to-end.
+// FDRS-663 — bounded/lazy minting + bounded trial parallelism.
+//
+// Flow per the 2026-07-05 [DECISION] set, revised by FDRS-663's 2026-07-06
+// [DECISION] (option A — the free-tier `concurrentTwins: 3` mint gate was
+// killing the k=5 default at the 4th upfront mint):
+//   1. Mint sessions upfront (POST /v1/sessions), one shared
+//      `grp_` + nanoid21 group_id on EVERY mint body and a FRESH
+//      idempotency key per mint — the design's "provisioning k isolated
+//      github twins … ready" moment. A QUOTA error mid-mint no longer
+//      aborts: it discovers the plan's concurrent-twin bound, and the
+//      group proceeds with the sessions it holds (k stays the design
+//      default; the wall-clock stretches). Any other failed mint — or a
+//      quota error before the FIRST mint succeeds — still rolls the
+//      half-group back (best-effort DELETEs) and aborts before any agent
+//      spawns.
+//   2. Run the k trials with concurrency = the number of upfront mints
+//      (= k when quota never pushed back). runScenarioHosted stays the
+//      isolation unit: each trial gets its session via the
+//      `premintedSession` seam, `abandonOnFailure` on, and still DELETEs
+//      its own session in its `finally` — that delete frees the quota slot
+//      the next lazy mint reuses. Trials beyond the bound mint lazily as
+//      slots free (quota retries with a pause: deletes propagate async);
+//      rows render in trial order regardless of completion order.
+//   3. Errored trials (preflight failure / agent timeout / crash / a lazy
+//      mint that never cleared quota) were abandoned inside the trial where
+//      possible; here they render as errored rows EXCLUDED from the verdict
+//      fraction — remaining trials continue.
+//   4. Verdicts are NUMERIC cloud-judge scores (capture-only CLI, ADR-013);
+//      the summary hands off to the task's reliability page.
+//
+// k=1 never reaches this module: the single-run path in cli/main.ts stays
+// exactly as it was (no group stamped — a group of 1 would flip the
+// reliability page off its implicit latest-k fallback).
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createHostedClient } from "../hosted/client.js";
+import { HostedQuotaError, HostedTrialError } from "../hosted/errors.js";
+import { newGroupId } from "../demo/ids.js";
+import { criterionPhrase } from "../demo/render.js";
+import { parseScenarioFile } from "../scenario/parseScenario.js";
+import { outcomeOf } from "../hosted/evalResultView.js";
+import { normalizeConfigAgentId, normalizeConfigAgentSlug, readProjectConfig, } from "../cli/project-config.js";
+import { runScenarioHosted } from "./runScenarioHosted.js";
+import { fixHandoffLines, flagHintLine, groupExitCode, groupSummaryLines, mostCommonFailedCriterion, provisioningLine, shortReason, spawningAgentLine, trialRowLine, } from "./groupRender.js";
+/** Explicit finalize timeout for -n runs ([DECISION]) — the hosted client
+ *  defaults to 30s; the judge measured 5-8s, 60s is belt-and-braces (same
+ *  constant `pome demo` locked for its trial finalizes). */
+export const GROUP_FINALIZE_TIMEOUT_MS = 60_000;
+/** FDRS-663 — a lazy mint can quota-fail even though a trial just finished:
+ *  the finished trial's DELETE propagates asynchronously. Pause and retry a
+ *  bounded number of times before declaring that trial errored. */
+export const LAZY_MINT_RETRY_MS = 2_000;
+export const LAZY_MINT_MAX_ATTEMPTS = 5;
+export async function runTrialGroup(options) {
+    if (!Number.isInteger(options.trials) || options.trials < 2) {
+        throw new Error(`runTrialGroup requires k>1 (got ${options.trials}); k=1 takes the single-run path so no group is stamped.`);
+    }
+    const out = options.out ?? ((line) => console.error(line));
+    const runFn = options.runScenarioHostedFn ?? runScenarioHosted;
+    const client = options.client ??
+        createHostedClient({
+            baseUrl: options.hosted.baseUrl,
+            apiKey: options.hosted.apiKey,
+            timeoutMs: GROUP_FINALIZE_TIMEOUT_MS,
+        });
+    const groupId = options.groupId ?? newGroupId();
+    const agentCommandSource = options.agentCommandSource ?? "pome.config.json";
+    const scenario = await parseScenarioFile(options.scenarioPath);
+    const scenarioSource = await readFile(options.scenarioPath, "utf8");
+    // Same agent resolution as the single-run path (ADR-013): the group's
+    // trials are recorded under the agent pinned in pome.config.json.
+    const configRead = await readProjectConfig(dirname(options.scenarioPath));
+    const agentId = configRead
+        ? normalizeConfigAgentId(configRead.config)
+        : undefined;
+    const agentSlug = configRead
+        ? normalizeConfigAgentSlug(configRead.config)
+        : undefined;
+    out(flagHintLine(agentCommandSource));
+    out("");
+    const sleep = options.sleepFn ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const mintOne = () => client.createSession({
+        scenarioSource,
+        twins: scenario.config.twins,
+        agentId,
+        seed: scenario.seedState,
+        groupId,
+        // Fresh idempotency key per mint — the mint bodies are otherwise
+        // identical, and the cloud would collapse them onto one session.
+        idempotencyKey: randomUUID(),
+    });
+    // 1. Mint upfront, quota-bounded (FDRS-663). The group exists before the
+    // first agent spawns, and auth/orch failures surface HERE as one clean
+    // error instead of half-way through a run. A quota push-back mid-mint is
+    // NOT an error: it discovers the plan's concurrent-twin bound and the
+    // group proceeds at that concurrency, reusing slots as trials finish.
+    const sessions = [];
+    try {
+        for (let i = 0; i < options.trials; i += 1) {
+            try {
+                sessions.push(await mintOne());
+            }
+            catch (err) {
+                if (err instanceof HostedQuotaError && sessions.length > 0)
+                    break;
+                throw err;
+            }
+        }
+    }
+    catch (err) {
+        // Roll the half-group back so abandoned mints never linger as open
+        // sessions polluting the reliability view; then let the caller map the
+        // error to the documented exit code.
+        await Promise.all(sessions.map((s) => client.deleteSession(s.session_id).catch(() => undefined)));
+        throw err;
+    }
+    const concurrency = sessions.length;
+    out(provisioningLine(options.trials, scenario.config.twins, concurrency));
+    out(spawningAgentLine(options.agentCommand, agentCommandSource));
+    out("");
+    // A trial past the upfront bound mints its session lazily, once its worker
+    // slot frees. The slot's previous trial deleted its session on the way out,
+    // but that DELETE propagates asynchronously — quota errors here retry with
+    // a pause before the trial is declared errored.
+    const mintLazily = async () => {
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                return await mintOne();
+            }
+            catch (err) {
+                if (err instanceof HostedQuotaError && attempt < LAZY_MINT_MAX_ATTEMPTS) {
+                    await sleep(LAZY_MINT_RETRY_MS);
+                    continue;
+                }
+                throw err;
+            }
+        }
+    };
+    // 2. Trials at bounded concurrency (FDRS-663 resolves FDRS-636's deferred
+    // "bounded trial parallelism" thread: the bound IS the plan's quota).
+    // Rows render in trial order — a finished trial's line waits for every
+    // earlier trial's line.
+    const rows = new Array(options.trials);
+    const failedCriteria = [];
+    let printedRows = 0;
+    const flushRows = () => {
+        while (printedRows < options.trials && rows[printedRows] !== undefined) {
+            out(trialRowLine(printedRows + 1, rows[printedRows]));
+            printedRows += 1;
+        }
+    };
+    const runOneTrial = async (index) => {
+        let row;
+        try {
+            const session = index < sessions.length ? sessions[index] : await mintLazily();
+            const result = await runFn({
+                scenarioPath: options.scenarioPath,
+                agentCommand: options.agentCommand,
+                artifactsDir: options.artifactsDir,
+                hosted: options.hosted,
+                client,
+                agentModel: options.agentModel,
+                premintedSession: session,
+                abandonOnFailure: true,
+                // FDRS-644 — stamped into the trial's verdict.json so fix-prompt
+                // can reassemble this run set from local artifacts.
+                groupId,
+            });
+            const failing = result.score.results.filter((r) => outcomeOf(r) === "failed");
+            for (const r of failing)
+                failedCriteria.push(r.criterion.text);
+            row = {
+                kind: "completed",
+                score: result.score.satisfaction,
+                passed: result.exitCode === 0,
+                seconds: result.durationMs / 1000,
+                note: failing.length > 0
+                    ? failing.map((r) => criterionPhrase(r.criterion.text)).join(" · ")
+                    : undefined,
+            };
+        }
+        catch (err) {
+            // The trial abandoned its session before throwing (or crashed past
+            // the point where a verdict was possible — or its lazy mint never
+            // cleared quota). Errored rows are excluded from the fraction; the
+            // remaining trials continue.
+            row = {
+                kind: "errored",
+                reason: err instanceof HostedTrialError
+                    ? err.message
+                    : shortReason(err instanceof Error ? err.message : String(err)),
+            };
+        }
+        rows[index] = row;
+        flushRows();
+    };
+    let nextTrial = 0;
+    await Promise.all(Array.from({ length: Math.max(1, concurrency) }, async () => {
+        while (nextTrial < options.trials) {
+            const index = nextTrial;
+            nextTrial += 1;
+            await runOneTrial(index);
+        }
+    }));
+    // 3. Summary + the framed handoff to the task's reliability page.
+    // FDRS-665 — the URL carries the agent by construction (Reliability IA v1
+    // decision 1): a registered repo prints /agents/<slug>/tasks/<taskName>
+    // with ?group for the run set (forward-compat — the page honors it in M1).
+    // Legacy fallbacks, both served by FDRS-668's cloud-side redirects:
+    // agentId without a slug → /runs/task/<name>?agent=<id> (server-side
+    // id→slug redirect); unregistered repo → the bare task URL, which
+    // auto-selects when exactly one agent has runs for that task. Task name =
+    // the slug /finalize recorded as runs.task_name.
+    const failing = mostCommonFailedCriterion(failedCriteria);
+    const base = options.dashboardBaseUrl.replace(/\/$/, "");
+    const taskPart = encodeURIComponent(scenario.slug);
+    const reliabilityUrl = agentSlug
+        ? `${base}/agents/${encodeURIComponent(agentSlug)}/tasks/${taskPart}?group=${encodeURIComponent(groupId)}`
+        : `${base}/runs/task/${taskPart}${agentId ? `?agent=${encodeURIComponent(agentId)}` : ""}`;
+    for (const line of groupSummaryLines({
+        rows,
+        failingCriterionPhrase: failing?.phrase,
+        failingCriterionCount: failing?.count,
+        reliabilityUrl,
+    })) {
+        out(line);
+    }
+    // 4. FDRS-644 — the fix & green handoff, only when a COMPLETED trial
+    // failed. Errored trials are sandbox noise: the answer there is re-run,
+    // not a code fix, so an errored-only group gets no handoff.
+    const failedCompleted = rows.filter((r) => r.kind === "completed" && !r.passed).length;
+    if (failedCompleted > 0) {
+        const artifactsDir = options.artifactsDir ?? "runs";
+        const fixPromptCommand = artifactsDir === "runs"
+            ? "pome fix-prompt"
+            : `pome fix-prompt ${artifactsDir}`;
+        const rerunCommand = options.rerunCommand ??
+            `pome run ${options.scenarioPath} -n ${options.trials}`;
+        for (const line of fixHandoffLines({ fixPromptCommand, rerunCommand })) {
+            out(line);
+        }
+    }
+    return { groupId, rows, exitCode: groupExitCode(rows), reliabilityUrl };
+}

package/dist/src/runner/trialCount.d.ts

@@ -0,0 +1,8 @@
+/** Hard cap on trials per group — matches the reliability read's bound. */
+export declare const MAX_TRIALS = 20;
+/** Parse the raw `-n` flag value. Throws HostedUsageError (documented
+ *  exit 5) on anything but an integer 1..MAX_TRIALS. */
+export declare function parseTrialsFlag(raw: string): number;
+/** Effective k for one scenario: the validated -n flag when present,
+ *  otherwise the scenario config's `runs` field capped at MAX_TRIALS. */
+export declare function effectiveTrialCount(flagValue: number | undefined, configRuns: number): number;

package/dist/src/runner/trialCount.js

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+// FDRS-636 — trial-count resolution for `pome run -n k`.
+//
+// [DECISION 2026-07-05]: -n is an integer 1..20 on the hosted run path. The
+// DEFAULT is the scenario config's `runs` field (scenarioConfigSchema parses
+// it, defaulting 1; nothing consumed it before this ticket) — -n overrides;
+// both are capped at 20. k=1 keeps EXACTLY today's single-run behavior (no
+// group is ever stamped — a group of 1 would flip the reliability page off
+// its implicit latest-k fallback and regress the view).
+import { HostedUsageError } from "../hosted/errors.js";
+/** Hard cap on trials per group — matches the reliability read's bound. */
+export const MAX_TRIALS = 20;
+/** Parse the raw `-n` flag value. Throws HostedUsageError (documented
+ *  exit 5) on anything but an integer 1..MAX_TRIALS. */
+export function parseTrialsFlag(raw) {
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        throw new HostedUsageError(`Invalid -n "${raw}" (expected an integer 1-${MAX_TRIALS}).`);
+    }
+    const n = Number.parseInt(trimmed, 10);
+    if (n < 1 || n > MAX_TRIALS) {
+        throw new HostedUsageError(`Invalid -n "${raw}" (expected an integer 1-${MAX_TRIALS}).`);
+    }
+    return n;
+}
+/** Effective k for one scenario: the validated -n flag when present,
+ *  otherwise the scenario config's `runs` field capped at MAX_TRIALS. */
+export function effectiveTrialCount(flagValue, configRuns) {
+    if (flagValue !== undefined)
+        return flagValue;
+    return Math.min(Math.max(1, Math.trunc(configRuns)), MAX_TRIALS);
+}

package/dist/src/scaffolds/mcp-loop/loop.d.ts

@@ -0,0 +1,47 @@
+import { type LanguageModel } from "ai";
+export type McpToolDef = {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+};
+export type McpCallResult = {
+    text: string;
+    isError: boolean;
+};
+export interface McpClient {
+    listTools(): Promise<McpToolDef[]>;
+    callTool(name: string, args: unknown): Promise<McpCallResult>;
+}
+export declare function createHttpMcpClient(opts: {
+    url: string;
+    authToken?: string;
+    fetchImpl?: typeof fetch;
+}): McpClient;
+export declare const DEFAULT_MAX_TURNS = 12;
+export type RunLoopOptions = {
+    model: LanguageModel;
+    mcp: McpClient;
+    task: string;
+    system?: string;
+    maxTurns?: number;
+    signalsPath?: string | null;
+    modelId?: string;
+    host?: string;
+};
+export type RunLoopResult = {
+    text: string;
+    toolCallCount: number;
+    steps: number;
+    finishReason: string;
+};
+export declare function runMcpLoop(options: RunLoopOptions): Promise<RunLoopResult>;
+export type LoopEnvContract = {
+    task: string;
+    mcpUrl: string;
+    authToken?: string;
+    model: string;
+    promptPath?: string;
+    signalsPath: string | null;
+};
+export declare function resolveMcpUrl(env?: NodeJS.ProcessEnv): string | null;
+export declare function resolveLoopEnv(env?: NodeJS.ProcessEnv): LoopEnvContract;

package/dist/src/scaffolds/mcp-loop/loop.js

@@ -0,0 +1,331 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Model-agnostic MCP tool-call loop (spec §2 — the "mcp-loop" scaffold).
+//
+// Speaks the SAME agent contract as the existing example agents: it reads
+// POME_TASK, the twin's POME_<TWIN>_MCP_URL, and POME_AUTH_TOKEN from the
+// environment (the CLI runner sets these per cell). It connects to the twin's
+// stateless MCP endpoint (JSON-RPC over Streamable HTTP), exposes the twin's
+// tools to the model via the Vercel AI SDK, and runs a tool-call loop until the
+// model finishes or hits the turn budget.
+//
+// NO new runtime dep: the MCP client is a ~40-line JSON-RPC-over-fetch client
+// against the twin's stateless Streamable-HTTP server (see
+// packages/twin-github/src/mcp.ts — single POST per request, `application/json`
+// response, `tools/list` → { tools }, `tools/call` → { content:[{text}], isError }).
+//
+// Trace signals (best-effort, NOT analyzed in v1): when POME_ADAPTER_SIGNALS_PATH
+// is set, the loop appends ToolUseEvent / ToolResultEvent rows whose on-disk
+// shape is isomorphic with @pome-sh/adapter-claude-sdk's signals.ts, so traces
+// stay comparable across scaffolds and v2's explanation layer inherits them.
+import { appendFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { generateText, stepCountIs, dynamicTool, jsonSchema, } from "ai";
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+// A minimal Streamable-HTTP MCP client. Each request is one POST; the twin is
+// stateless (no Mcp-Session-Id, no SSE for single requests). We still send an
+// `initialize` once for protocol-correctness even though the twin doesn't
+// require session state.
+export function createHttpMcpClient(opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    let nextId = 1;
+    let initialized = false;
+    async function rpc(method, params) {
+        const id = nextId++;
+        const headers = {
+            "content-type": "application/json",
+            // The twin replies with application/json for single requests, but a
+            // spec-compliant client advertises it accepts SSE too.
+            accept: "application/json, text/event-stream",
+        };
+        if (opts.authToken)
+            headers.authorization = `Bearer ${opts.authToken}`;
+        const res = await doFetch(opts.url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ jsonrpc: "2.0", id, method, params }),
+        });
+        if (!res.ok) {
+            throw new Error(`MCP ${method} failed: HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        if ("error" in body) {
+            throw new Error(`MCP ${method} error ${body.error.code}: ${body.error.message}`);
+        }
+        return body.result;
+    }
+    async function ensureInitialized() {
+        if (initialized)
+            return;
+        await rpc("initialize", {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "pome-mcp-loop", version: "1" },
+        });
+        initialized = true;
+    }
+    return {
+        async listTools() {
+            await ensureInitialized();
+            const result = (await rpc("tools/list"));
+            const tools = Array.isArray(result.tools) ? result.tools : [];
+            return tools.flatMap((t) => {
+                if (t &&
+                    typeof t === "object" &&
+                    typeof t.name === "string") {
+                    const obj = t;
+                    const schema = obj.inputSchema && typeof obj.inputSchema === "object"
+                        ? obj.inputSchema
+                        : { type: "object", properties: {} };
+                    return [
+                        {
+                            name: obj.name,
+                            description: typeof obj.description === "string" ? obj.description : undefined,
+                            inputSchema: schema,
+                        },
+                    ];
+                }
+                return [];
+            });
+        },
+        async callTool(name, args) {
+            await ensureInitialized();
+            const result = (await rpc("tools/call", { name, arguments: args ?? {} }));
+            const content = Array.isArray(result.content) ? result.content : [];
+            const text = content
+                .map((part) => part &&
+                typeof part === "object" &&
+                typeof part.text === "string"
+                ? (part.text)
+                : "")
+                .join("");
+            return { text, isError: result.isError === true };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Best-effort trace signals (isomorphic with @pome-sh/adapter-claude-sdk).
+// ---------------------------------------------------------------------------
+// Hand-built JSON-line rows matching the adapter's on-disk shapes (no
+// shared-types runtime dep). The CLI runner merges this file into the canonical
+// events.jsonl after the subprocess exits.
+function emitToolUse(signalsPath, row) {
+    if (!signalsPath)
+        return;
+    try {
+        appendFileSync(signalsPath, JSON.stringify({
+            ts: new Date().toISOString(),
+            event_id: randomUUID(),
+            parent_id: null,
+            kind: "ToolUseEvent",
+            tool_use_id: row.tool_use_id,
+            tool_name: row.tool_name,
+            input: row.input,
+        }) + "\n");
+    }
+    catch {
+        // best-effort: never let trace I/O fail the agent.
+    }
+}
+function emitToolResult(signalsPath, row) {
+    if (!signalsPath)
+        return;
+    try {
+        appendFileSync(signalsPath, JSON.stringify({
+            ts: new Date().toISOString(),
+            event_id: randomUUID(),
+            parent_id: null,
+            kind: "ToolResultEvent",
+            tool_use_id: row.tool_use_id,
+            output: row.output,
+            is_error: row.is_error,
+        }) + "\n");
+    }
+    catch {
+        // best-effort.
+    }
+}
+// Append ONE authoritative LlmCallEvent per generateText step (one model
+// round-trip). The capture-server proxy can't read token/cost from the
+// encrypted CONNECT tunnel; the scaffold holds the AI SDK response and is the
+// only source that knows usage. The matrix runs mcp-loop cells with capture
+// OFF (see cli/src/matrix/index.ts), so these rows are the SOLE LlmCallEvent
+// rows and runResourceMetrics sums them without double-counting proxy latency.
+//
+// On-disk shape matches llmCallEventSchema (src/types/shared.ts): host/port/
+// bytes_in/bytes_out are non-null (the scaffold never sees the HTTP/byte layer,
+// so bytes are honestly 0 and host is synthetic); url/method/status are null;
+// model/prompt_tokens/completion_tokens/cost_usd carry real values.
+function emitLlmCall(signalsPath, row) {
+    if (!signalsPath)
+        return;
+    try {
+        appendFileSync(signalsPath, JSON.stringify({
+            ts: new Date().toISOString(),
+            event_id: randomUUID(),
+            parent_id: null,
+            kind: "LlmCallEvent",
+            host: row.host,
+            port: 443,
+            latency_ms: row.latency_ms,
+            bytes_in: 0,
+            bytes_out: 0,
+            url: null,
+            method: null,
+            status: null,
+            model: row.model,
+            prompt_tokens: row.prompt_tokens,
+            completion_tokens: row.completion_tokens,
+            cost_usd: row.cost_usd,
+        }) + "\n");
+    }
+    catch {
+        // best-effort: never let trace I/O fail the agent.
+    }
+}
+// Read the Vercel AI Gateway's per-call cost from a step's providerMetadata.
+// ProviderMetadata = Record<string, Record<string, JSONValue>>; the gateway
+// surfaces cost under providerMetadata.gateway.cost. Defensive: returns the
+// number only when finite, else null (provider/route dependent — may be absent).
+function readGatewayCost(pm) {
+    if (!pm || typeof pm !== "object")
+        return null;
+    const gateway = pm.gateway;
+    if (!gateway || typeof gateway !== "object")
+        return null;
+    const cost = gateway.cost;
+    return typeof cost === "number" && Number.isFinite(cost) ? cost : null;
+}
+// Coerce a possibly-undefined SDK token count to a schema-valid non-negative
+// integer, or null when absent/non-finite.
+function coerceTokenCount(n) {
+    return typeof n === "number" && Number.isFinite(n) ? Math.max(0, Math.round(n)) : null;
+}
+// ---------------------------------------------------------------------------
+// The loop.
+// ---------------------------------------------------------------------------
+// 12 turns: matches the example agents' 8-turn loop with headroom for
+// multi-step (T5) scenarios. Wall-clock is the runner's scenario-timeout SIGTERM
+// (spec §2 / plan) — the loop does not run a second timeout.
+export const DEFAULT_MAX_TURNS = 12;
+// Build the AI SDK tool set from the twin's MCP tools. Each tool's `execute`
+// dispatches back through the MCP client and emits best-effort trace signals.
+function buildToolSet(tools, mcp, signalsPath, onToolCall) {
+    const set = {};
+    for (const t of tools) {
+        set[t.name] = dynamicTool({
+            description: t.description ?? `MCP tool ${t.name}`,
+            inputSchema: jsonSchema(t.inputSchema),
+            execute: async (input) => {
+                onToolCall();
+                const toolUseId = randomUUID();
+                emitToolUse(signalsPath, {
+                    tool_use_id: toolUseId,
+                    tool_name: t.name,
+                    input,
+                });
+                const result = await mcp.callTool(t.name, input);
+                emitToolResult(signalsPath, {
+                    tool_use_id: toolUseId,
+                    output: result.text,
+                    is_error: result.isError,
+                });
+                // Hand the raw tool text back to the model; the AI SDK serializes it.
+                return result.text;
+            },
+        });
+    }
+    return set;
+}
+// Run the tool-call loop. The model + MCP client are injected so this is fully
+// unit-testable with a mocked model and a fake MCP client (no network, no key).
+export async function runMcpLoop(options) {
+    const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
+    const signalsPath = options.signalsPath ?? null;
+    const mcpTools = await options.mcp.listTools();
+    let toolCallCount = 0;
+    const toolSet = buildToolSet(mcpTools, options.mcp, signalsPath, () => {
+        toolCallCount += 1;
+    });
+    const messages = [{ role: "user", content: options.task }];
+    const modelId = options.modelId ?? "unknown";
+    const host = options.host ?? "ai-gateway";
+    const t0 = Date.now();
+    const result = await generateText({
+        model: options.model,
+        system: options.system,
+        messages,
+        tools: toolSet,
+        // Keep stepping while the model emits tool calls, up to the turn budget.
+        stopWhen: stepCountIs(maxTurns),
+    });
+    const elapsed = Date.now() - t0;
+    // Emit one authoritative LlmCallEvent per step (each step = one model call).
+    // The generateText wall-clock is split evenly across steps so the summed
+    // latency_ms over rows equals the real wall-clock (the SDK exposes no
+    // per-step timing). Tokens/cost are exact per step.
+    const stepCount = result.steps.length;
+    const perStepLatency = Math.max(0, Math.round(elapsed / Math.max(1, stepCount)));
+    for (const step of result.steps) {
+        emitLlmCall(signalsPath, {
+            host,
+            latency_ms: perStepLatency,
+            model: modelId,
+            prompt_tokens: coerceTokenCount(step.usage?.inputTokens),
+            completion_tokens: coerceTokenCount(step.usage?.outputTokens),
+            cost_usd: readGatewayCost(step.providerMetadata),
+        });
+    }
+    return {
+        text: result.text,
+        toolCallCount,
+        steps: result.steps.length,
+        // The ai-level finishReason is a string union (the provider-level
+        // {unified, raw} object is flattened by generateText).
+        finishReason: result.finishReason,
+    };
+}
+// Discover the twin MCP URL from POME_<TWIN>_MCP_URL. The runner currently sets
+// POME_GITHUB_MCP_URL; this is generic over twins (Stripe/Slack land the same
+// shape). POME_TWIN_NAMES, when present, picks the active twin; otherwise the
+// first POME_*_MCP_URL wins.
+export function resolveMcpUrl(env = process.env) {
+    const names = (env.POME_TWIN_NAMES ?? "")
+        .split(",")
+        .map((s) => s.trim().toUpperCase())
+        .filter(Boolean);
+    for (const name of names) {
+        const v = env[`POME_${name}_MCP_URL`];
+        if (v && v.trim())
+            return v.trim();
+    }
+    // Fall back to any POME_<X>_MCP_URL in the environment.
+    for (const [k, v] of Object.entries(env)) {
+        if (/^POME_[A-Z0-9]+_MCP_URL$/.test(k) && v && v.trim())
+            return v.trim();
+    }
+    return null;
+}
+// Resolve the full env contract or throw a clear error naming the missing var.
+export function resolveLoopEnv(env = process.env) {
+    const task = env.POME_TASK?.trim();
+    if (!task)
+        throw new Error("mcp-loop: POME_TASK is required");
+    const mcpUrl = resolveMcpUrl(env);
+    if (!mcpUrl) {
+        throw new Error("mcp-loop: no POME_<TWIN>_MCP_URL found in the environment (e.g. POME_GITHUB_MCP_URL)");
+    }
+    const model = env.POME_MATRIX_MODEL?.trim();
+    if (!model) {
+        throw new Error("mcp-loop: POME_MATRIX_MODEL is required (set by the matrix)");
+    }
+    const signalsRaw = env.POME_ADAPTER_SIGNALS_PATH;
+    return {
+        task,
+        mcpUrl,
+        authToken: env.POME_AUTH_TOKEN?.trim() || undefined,
+        model,
+        promptPath: env.POME_MATRIX_PROMPT_PATH?.trim() || undefined,
+        signalsPath: signalsRaw && signalsRaw.length > 0 ? signalsRaw : null,
+    };
+}