pome-sh 0.6.6

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,
+    };
+}

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

@@ -0,0 +1,29 @@
+import type { LanguageModel } from "ai";
+export declare function gatewayEnabled(env?: NodeJS.ProcessEnv): boolean;
+export type ProviderId = "anthropic" | "openai" | "openrouter" | "google";
+export type ResolvedProvider = {
+    provider: ProviderId;
+    /** The single env var that must be set for this provider. */
+    envKey: string;
+    /** The provider-native model id (the part after `provider/`, or the bare id). */
+    modelId: string;
+};
+export declare function resolveProvider(model: string): ResolvedProvider | null;
+export declare function resolveLlmHost(model: string, env?: NodeJS.ProcessEnv): string;
+export type ModelPreflight = {
+    ok: true;
+    provider: ProviderId | "gateway";
+    envKey: string;
+} | {
+    ok: false;
+    reason: "unknown-provider";
+    model: string;
+} | {
+    ok: false;
+    reason: "missing-key";
+    provider: ProviderId;
+    envKey: string;
+};
+export declare function preflightModel(model: string, env?: NodeJS.ProcessEnv): ModelPreflight;
+export declare function preflightModelMessage(pf: ModelPreflight): string;
+export declare function resolveModel(model: string, env?: NodeJS.ProcessEnv): LanguageModel;

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

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Model-string → Vercel AI SDK model resolver, plus a key-preflight helper the
+// matrix (and the entrypoint) can call before any network I/O.
+//
+// One env var per provider (spec §2). A provider-prefixed model string like
+// `openai/gpt-5`, `anthropic/claude-opus-4-8`, `openrouter/qwen-3-235b`, or
+// `google/gemini-2.5-pro` picks the provider; bare ids (`claude-*`, `gpt-*`,
+// `gemini-*`, `o1`/`o3`) are mapped by prefix to stay back-compatible with the
+// claude-agent-sdk-style native ids. The piece after the first `/` (or the bare
+// id) is the provider-native model id handed to the SDK.
+//
+// Resolution is dependency-light at module load: the provider factory packages
+// are imported, but a model is only constructed when `resolveModel()` is called,
+// so a missing key fails at preflight (clear) rather than at the first token.
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import { gateway } from "@ai-sdk/gateway";
+// When a Vercel AI Gateway key is present, every provider/model slug routes
+// through the gateway with that ONE key — no per-provider key needed, and it
+// reaches providers the per-provider path doesn't model (deepseek/, meta/,
+// xai/, qwen, ...). This is the preferred path for the model matrix: one key,
+// the whole fleet.
+export function gatewayEnabled(env = process.env) {
+    const v = env.AI_GATEWAY_API_KEY;
+    return v !== undefined && v.trim() !== "";
+}
+// Map a (possibly provider-prefixed) model string to its provider + native id +
+// required env var. Mirrors the matrix preflight table in
+// cli/src/matrix/preflight.ts — keep the two in sync. Returns null for an
+// unknown prefix so callers can fail clearly.
+export function resolveProvider(model) {
+    const m = model.trim();
+    const slash = m.indexOf("/");
+    const prefix = slash >= 0 ? m.slice(0, slash) : "";
+    const rest = slash >= 0 ? m.slice(slash + 1) : m;
+    if (prefix === "anthropic" || m.startsWith("claude")) {
+        return { provider: "anthropic", envKey: "ANTHROPIC_API_KEY", modelId: rest };
+    }
+    if (prefix === "openrouter") {
+        // OpenRouter model ids are themselves slashed (`qwen/qwen-3-235b`), so keep
+        // everything after the FIRST segment intact.
+        return { provider: "openrouter", envKey: "OPENROUTER_API_KEY", modelId: rest };
+    }
+    if (prefix === "openai" ||
+        m.startsWith("gpt-") ||
+        m.startsWith("o1") ||
+        m.startsWith("o3")) {
+        return { provider: "openai", envKey: "OPENAI_API_KEY", modelId: rest };
+    }
+    if (prefix === "google" || m.startsWith("gemini")) {
+        return { provider: "google", envKey: "GOOGLE_API_KEY", modelId: rest };
+    }
+    return null;
+}
+// Resolve the synthetic host the scaffold stamps on its emitted LlmCallEvent
+// rows (the scaffold talks to the AI SDK, never the HTTP/byte layer). When the
+// gateway key is present every slug routes through "ai-gateway"; otherwise map
+// the resolved provider to its public API host. An unknown provider defaults to
+// "ai-gateway" (the only reachable path without a per-provider mapping). Kept
+// here alongside gatewayEnabled/resolveProvider so host derivation lives where
+// the provider knowledge already is.
+const PROVIDER_HOSTS = {
+    anthropic: "api.anthropic.com",
+    openai: "api.openai.com",
+    google: "generativelanguage.googleapis.com",
+    openrouter: "openrouter.ai",
+};
+export function resolveLlmHost(model, env = process.env) {
+    if (gatewayEnabled(env))
+        return "ai-gateway";
+    const resolved = resolveProvider(model);
+    if (!resolved)
+        return "ai-gateway";
+    return PROVIDER_HOSTS[resolved.provider];
+}
+export function preflightModel(model, env = process.env) {
+    // Gateway key present → any slug is reachable with that one key.
+    if (gatewayEnabled(env)) {
+        const known = resolveProvider(model);
+        return {
+            ok: true,
+            provider: known?.provider ?? "gateway",
+            envKey: "AI_GATEWAY_API_KEY",
+        };
+    }
+    const resolved = resolveProvider(model);
+    if (!resolved)
+        return { ok: false, reason: "unknown-provider", model };
+    const value = env[resolved.envKey];
+    if (value === undefined || value.trim() === "") {
+        return {
+            ok: false,
+            reason: "missing-key",
+            provider: resolved.provider,
+            envKey: resolved.envKey,
+        };
+    }
+    return { ok: true, provider: resolved.provider, envKey: resolved.envKey };
+}
+// Human-readable one-liner for a failed model preflight.
+export function preflightModelMessage(pf) {
+    if (pf.ok)
+        return `model preflight ok (${pf.provider})`;
+    if (pf.reason === "unknown-provider") {
+        return `mcp-loop: unknown provider for model "${pf.model}" (expected one of anthropic/ openai/ openrouter/ google/, or a bare claude*/gpt-*/o1/o3/gemini* id)`;
+    }
+    return `mcp-loop: missing ${pf.envKey} (${pf.provider}) — set it and re-run`;
+}
+// Construct the AI SDK LanguageModel for a model string. Throws (clearly) on an
+// unknown provider or a missing key — call preflightModel() first if you want to
+// fail before any model construction. The provider factory reads the key from
+// the env var explicitly (not the SDK default) so the key the matrix preflighted
+// is exactly the one used — notably Google's SDK default reads
+// GOOGLE_GENERATIVE_AI_API_KEY, but we standardize on GOOGLE_API_KEY.
+export function resolveModel(model, env = process.env) {
+    // Gateway key present → hand the full provider/model slug to the gateway,
+    // which routes it with the single AI_GATEWAY_API_KEY.
+    if (gatewayEnabled(env)) {
+        return gateway(model.trim());
+    }
+    const resolved = resolveProvider(model);
+    if (!resolved) {
+        throw new Error(`mcp-loop: cannot resolve provider for model "${model}"`);
+    }
+    const apiKey = env[resolved.envKey];
+    if (!apiKey || apiKey.trim() === "") {
+        throw new Error(`mcp-loop: ${resolved.envKey} is not set`);
+    }
+    switch (resolved.provider) {
+        case "anthropic":
+            return createAnthropic({ apiKey })(resolved.modelId);
+        case "openai":
+            return createOpenAI({ apiKey })(resolved.modelId);
+        case "openrouter":
+            return createOpenRouter({ apiKey }).chat(resolved.modelId);
+        case "google":
+            return createGoogleGenerativeAI({ apiKey })(resolved.modelId);
+    }
+}

package/dist/src/scenario/parseScenario.d.ts

@@ -0,0 +1,4 @@
+import { type Scenario } from "./scenarioSchema.js";
+export declare function parseScenarioFile(path: string): Promise<Scenario>;
+export declare function parseScenario(markdown: string, slug?: string, sidecarSeed?: unknown, scenarioPath?: string): Scenario;
+export declare function formatScenarioError(error: unknown, filePath: string): string;