@pome-sh/cli 0.1.0 → 0.2.0

package/dist/src/recorder/inspect.js

@@ -61,11 +61,13 @@ export function computeTraceHealth(input) {
     };
     // CAS adapter layer — only active when the agent is wired through
     // `@pome-sh/claude-agent-sdk`. Heuristic: any of ToolUse/ToolResult/
-    // SubagentSpawn/Hook indicates adapter is live.
+    // SubagentSpawn/Hook/LlmTurn indicates adapter is live. LlmTurnEvent (F-766)
+    // is adapter-emitted like its siblings, so it counts toward this layer.
     const casCount = counts.ToolUseEvent +
         counts.ToolResultEvent +
         counts.SubagentSpawnEvent +
-        counts.HookEvent;
+        counts.HookEvent +
+        counts.LlmTurnEvent;
     const casExpected = input.scenarioExpectsCas ? 1 : casCount > 0 ? 1 : 0;
     const cas = {
         name: "CAS adapter",
@@ -91,6 +93,7 @@ function emptyCounts() {
         ToolResultEvent: 0,
         SubagentSpawnEvent: 0,
         HookEvent: 0,
+        LlmTurnEvent: 0,
     };
 }
 function countByKind(events) {
@@ -139,6 +142,8 @@ function renderEventLines(event) {
             return renderSubagentSpawn(event);
         case "HookEvent":
             return renderHook(event);
+        case "LlmTurnEvent":
+            return renderLlmTurn(event);
     }
 }
 function renderTwinHttp(event) {
@@ -175,3 +180,16 @@ function renderHook(event) {
     const tool = event.tool_name ? ` tool=${event.tool_name}` : "";
     return [`- HookEvent      ${event.hook_name}${tool}`];
 }
+function renderLlmTurn(event) {
+    const model = event.model ?? "unknown";
+    const tokens = `${event.input_tokens ?? "?"}/${event.output_tokens ?? "?"}`;
+    const cache = `${event.cache_read_input_tokens ?? "?"}/${event.cache_creation_input_tokens ?? "?"}`;
+    const est = event.latency_ms_estimated ? "~" : "";
+    const finish = event.finish_reasons && event.finish_reasons.length > 0
+        ? `  finish=${event.finish_reasons.join(",")}`
+        : "";
+    return [
+        `- LlmTurnEvent   turn ${event.turn_index}  model=${model}  tokens=${tokens} (${est}${event.latency_ms}ms)`,
+        `    cache read/create=${cache}${finish}`,
+    ];
+}

package/dist/src/runner/mergeAdapterSignals.js

@@ -12,8 +12,8 @@ import { redactEvent } from "../recorder/redaction.js";
 //   2. The trace writer then appends `TwinHttpEvent` rows from the in-process
 //      twin recorder (FDRS-415).
 //   3. This helper reads `signals.jsonl` (HookEvent / ToolUseEvent /
-//      ToolResultEvent / SubagentSpawnEvent rows written by the agent
-//      subprocess via `POME_ADAPTER_SIGNALS_PATH`), validates each line
+//      ToolResultEvent / SubagentSpawnEvent / LlmTurnEvent rows written by the
+//      agent subprocess via `POME_ADAPTER_SIGNALS_PATH`), validates each line
 //      against the M0 unified `eventSchema`, then **interleaves** the signal
 //      rows with the existing events.jsonl rows by ts ascending and rewrites
 //      the file. The merged file is the canonical view for `pome inspect`

package/dist/src/runner/ports.js

@@ -1,5 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 import { createServer } from "node:net";
+// NOTE: allocate-then-close hands back a port that is free at close time; a
+// caller that rebinds it races any other process that grabs it in the gap.
+// Pre-existing and acceptable for local dev twins (loopback, short-lived).
 export async function getAvailablePort() {
     return new Promise((resolve, reject) => {
         const server = createServer();

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

@@ -23,6 +23,7 @@ export declare function runScenario(options: RunScenarioOptions): Promise<{
         criteria: {
             type: "model" | "code";
             text: string;
+            twin?: string | undefined;
         }[];
         config: {
             twins: string[];
@@ -74,7 +75,7 @@ export declare function runScenario(options: RunScenarioOptions): Promise<{
                     }[];
                     statuses: {
                         context: string;
-                        state: "error" | "success" | "failure" | "pending";
+                        state: "error" | "failure" | "pending" | "success";
                         description: string;
                     }[];
                     number?: number | undefined;
@@ -106,7 +107,83 @@ export declare function runScenario(options: RunScenarioOptions): Promise<{
             users: Record<string, unknown>[];
             channels: Record<string, unknown>[];
             team?: Record<string, unknown> | undefined;
-        };
+        } | Record<string, {
+            users: {
+                login: string;
+                type: "User" | "Organization";
+                name: string;
+            }[];
+            repositories: {
+                owner: string;
+                name: string;
+                description: string;
+                private: boolean;
+                default_branch: string;
+                collaborators: string[];
+                labels: {
+                    name: string;
+                    color: string;
+                    description: string;
+                }[];
+                files: {
+                    path: string;
+                    content: string;
+                    branch?: string | undefined;
+                }[];
+                issues: {
+                    title: string;
+                    body: string;
+                    state: "open" | "closed";
+                    labels: string[];
+                    assignees: string[];
+                    number?: number | undefined;
+                }[];
+                pull_requests: {
+                    title: string;
+                    body: string;
+                    head: string;
+                    base: string;
+                    state: "open" | "closed";
+                    reviews: {
+                        author: string;
+                        state: "APPROVED" | "CHANGES_REQUESTED" | "COMMENTED";
+                        body: string;
+                    }[];
+                    statuses: {
+                        context: string;
+                        state: "error" | "failure" | "pending" | "success";
+                        description: string;
+                    }[];
+                    number?: number | undefined;
+                    author?: string | undefined;
+                }[];
+            }[];
+        } | {
+            api_keys: {
+                key: string;
+                sid: string;
+                account_id?: string | undefined;
+            }[];
+            customers: Record<string, unknown>[];
+            products: Record<string, unknown>[];
+            prices: Record<string, unknown>[];
+            payment_intents: Record<string, unknown>[];
+            charges: Record<string, unknown>[];
+            events: Record<string, unknown>[];
+            balances: Record<string, unknown>[];
+            failure_injection: {
+                method: string;
+                path: string;
+                attempt: number;
+                mode: "before_handler" | "after_handler";
+                status: number;
+                body: unknown;
+            }[];
+        } | {
+            users: Record<string, unknown>[];
+            channels: Record<string, unknown>[];
+            team?: Record<string, unknown> | undefined;
+        }>;
     };
     runId: string;
     artifacts: import("../recorder/artifacts.js").RunArtifacts;

package/dist/src/runner/runScenario.js

@@ -4,14 +4,23 @@ import { randomBytes, randomUUID } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, resolve as resolvePath, sep as pathSep } from "node:path";
 import { sign } from "hono/jwt";
-import { parseScenarioFile } from "../scenario/parseScenario.js";
+import { parseScenarioFile, seedStateForTwin } from "../scenario/parseScenario.js";
 import { bootTwin } from "../twin/twinHarness.js";
+import { createRecorder } from "../recorder/recorder.js";
+import { redactSecrets } from "../recorder/redaction.js";
 import { getAvailablePort } from "./ports.js";
 import { runAgentCommand } from "./agentRunner.js";
 import { egressArgs, spawnCaptureServerChild } from "./captureServerChild.js";
 import { buildEgressAllowlist, readBlockedEgress } from "../capture-server/egress.js";
 import { mergeAdapterSignalsIntoEvents } from "./mergeAdapterSignals.js";
 import { writeRunNoScore } from "./runScenarioCore.js";
+// Promisify a Hono/node server `close()` so teardown can await in-flight
+// handlers draining before the twin's DB handle is released.
+function closeServer(server) {
+    return new Promise((resolvePromise, reject) => {
+        server.close((err) => (err ? reject(err) : resolvePromise()));
+    });
+}
 export async function runScenario(options) {
     const scenario = await parseScenarioFile(options.scenarioPath);
     const runId = `run_${randomUUID()}`;
@@ -81,23 +90,50 @@ export async function runScenario(options) {
         await captureServer.shutdown();
         return readBlockedEgress(egressJsonlPath);
     };
-    const twinName = scenario.config.twins[0] ?? "github";
-    const port = await getAvailablePort();
-    const baseUrl = `http://127.0.0.1:${port}`;
-    // F-698: stream twin HTTP events into the same events.jsonl the
-    // capture-server appends to. Durable store writes TwinHttpEvent rows;
-    // finalize dedupes against disk so upload shape stays one row per event.
-    const harness = await bootTwin({
-        twin: twinName,
-        seedState: scenario.seedState,
-        runId,
-        twinBaseUrl: baseUrl,
-        eventsPath: eventsJsonlPath,
-    });
-    const stateInitial = await harness.exportState();
+    const twins = scenario.config.twins.length ? scenario.config.twins : ["github"];
+    const primaryTwin = twins[0];
+    const isMultiTwin = twins.length > 1;
     const sid = runId;
     const authSecret = process.env.TWIN_AUTH_SECRET ?? randomBytes(32).toString("hex");
     process.env.TWIN_AUTH_SECRET = authSecret;
+    // Multi-twin (M3): all twins in one local run share ONE recorder so their
+    // HTTP events stream into a single events.jsonl (the same file the
+    // capture-server appends to). The runner owns the recorder's lifecycle here;
+    // each harness's `close()` releases only its own DB handle. For single-twin
+    // this is behaviorally identical to the old bootTwin-internal recorder.
+    // The durable store writes TwinHttpEvent rows; finalize dedupes against disk
+    // so upload shape stays one row per event.
+    const recorder = createRecorder({ eventsPath: eventsJsonlPath });
+    // Boot one twin harness per config twin, each on its own localhost port.
+    // Merge every twin's POME_<envName>_{REST,MCP}_URL and its extra JWT claims;
+    // one token carries the union of claims (e.g. Stripe's account_id).
+    const booted = [];
+    const twinEnv = {};
+    const stateInitialByTwin = {};
+    let mergedClaims = {};
+    for (const twin of twins) {
+        const port = await getAvailablePort();
+        const baseUrl = `http://127.0.0.1:${port}`;
+        const harness = await bootTwin({
+            twin,
+            seedState: seedStateForTwin(scenario, twin),
+            runId,
+            twinBaseUrl: baseUrl,
+            recorder,
+        });
+        stateInitialByTwin[twin] = await harness.exportState();
+        const sessionBase = `${baseUrl}/s/${sid}`;
+        // Twin-agnostic URL contract: the agent reads `POME_<TWIN>_{REST,MCP}_URL`.
+        // For github this resolves to the historical `POME_GITHUB_{REST,MCP}_URL`;
+        // slack/stripe get their own prefixes (the mcp-loop scaffold's
+        // `resolveMcpUrl` already keys off `POME_<TWIN>_MCP_URL`).
+        twinEnv[`POME_${harness.envName}_REST_URL`] = sessionBase;
+        twinEnv[`POME_${harness.envName}_MCP_URL`] = `${sessionBase}/mcp`;
+        mergedClaims = { ...mergedClaims, ...(harness.extraClaims ?? {}) };
+        const server = serve({ fetch: harness.app.fetch, port, hostname: "127.0.0.1" });
+        booted.push({ twin, harness, server });
+    }
+    const stateInitial = stateInitialByTwin[primaryTwin];
     const token = await sign({
         sid,
         team_id: "tm_local",
@@ -108,12 +144,11 @@ export async function runScenario(options) {
         // was invisible until a scripted REST agent needed to merge.
         login: "pome-agent",
         // Twin-supplied claims (e.g. Stripe's `account_id`, so the token resolves
-        // to the account the seed data lives in). github/slack supply none.
-        ...(harness.extraClaims ?? {}),
+        // to the account the seed data lives in) — merged across all twins.
+        // github/slack supply none.
+        ...mergedClaims,
         exp: Math.floor(Date.now() / 1000) + Math.max(scenario.config.timeout * 2, 600),
     }, authSecret);
-    const sessionBase = `${baseUrl}/s/${sid}`;
-    const server = serve({ fetch: harness.app.fetch, port, hostname: "127.0.0.1" });
     const proxyEnv = captureServer
         ? {
             // FDRS-399 — agent's outbound traffic flows through the capture-server.
@@ -127,13 +162,8 @@ export async function runScenario(options) {
         : {};
     const env = {
         POME_TASK: scenario.prompt,
-        POME_TWIN_NAMES: scenario.config.twins.join(","),
-        // Twin-agnostic URL contract: the agent reads `POME_<TWIN>_{REST,MCP}_URL`.
-        // For github this resolves to the historical `POME_GITHUB_{REST,MCP}_URL`;
-        // slack/stripe get their own prefixes (the mcp-loop scaffold's
-        // `resolveMcpUrl` already keys off `POME_<TWIN>_MCP_URL`).
-        [`POME_${harness.envName}_REST_URL`]: sessionBase,
-        [`POME_${harness.envName}_MCP_URL`]: `${sessionBase}/mcp`,
+        POME_TWIN_NAMES: twins.join(","),
+        ...twinEnv,
         POME_AUTH_TOKEN: token,
         POME_RUN_ID: runId,
         POME_ARTIFACTS_DIR: runDir,
@@ -141,6 +171,28 @@ export async function runScenario(options) {
         ...(options.extraAgentEnv ?? {}),
         ...proxyEnv,
     };
+    // Capture each twin's final state: the primary is the legacy `stateFinal`
+    // (state_final.json); every other twin is written alongside as
+    // `state_final.<twin>.json`. Best-effort disk writes for the extras.
+    const captureFinalStates = async () => {
+        const finals = {};
+        for (const { twin, harness } of booted) {
+            finals[twin] = await harness.exportState();
+        }
+        if (isMultiTwin) {
+            for (const { twin } of booted) {
+                if (twin === primaryTwin)
+                    continue;
+                try {
+                    await writeFile(join(runDir, `state_final.${twin}.json`), `${JSON.stringify(redactSecrets(finals[twin]), null, 2)}\n`);
+                }
+                catch {
+                    // best-effort — the primary state_final.json is what writeRun persists
+                }
+            }
+        }
+        return finals[primaryTwin];
+    };
     try {
         const preflight = await runAgentCommand({
             command: options.agentCommand,
@@ -153,8 +205,8 @@ export async function runScenario(options) {
         if (preflight.exitCode !== 0) {
             // Flush durable twin rows before finalize/merge so pending TwinHttpEvent
             // lines are on disk before events.jsonl is rewritten (not only in finally).
-            await harness.flush();
-            const stateFinal = await harness.exportState();
+            await recorder.flush?.();
+            const stateFinal = await captureFinalStates();
             const { artifacts, exitCode } = await writeRun({
                 artifactsDir,
                 runId,
@@ -165,7 +217,7 @@ export async function runScenario(options) {
                 agentStderr: preflight.stderr,
                 agentExitCode: preflight.exitCode,
                 agentTimedOut: preflight.timedOut ?? false,
-                events: harness.events(),
+                events: recorder.events(),
                 stateInitial,
                 stateFinal
             });
@@ -180,8 +232,8 @@ export async function runScenario(options) {
             env,
             timeoutSeconds: scenario.config.timeout
         });
-        await harness.flush();
-        const stateFinal = await harness.exportState();
+        await recorder.flush?.();
+        const stateFinal = await captureFinalStates();
         const { artifacts, exitCode } = await writeRun({
             artifactsDir,
             runId,
@@ -192,7 +244,7 @@ export async function runScenario(options) {
             agentStderr: agent.stderr,
             agentExitCode: agent.exitCode,
             agentTimedOut: agent.timedOut ?? false,
-            events: harness.events(),
+            events: recorder.events(),
             stateInitial,
             stateFinal
         });
@@ -202,11 +254,17 @@ export async function runScenario(options) {
     }
     finally {
         // Drain capture-server first so any in-flight LlmCallEvent rows land
-        // in events.jsonl before we move on; THEN close the twin (which flushes
-        // the durable recorder and resets twin-side sockets).
+        // in events.jsonl before we move on; THEN close each twin (releasing its
+        // DB handle) and finally the shared recorder (flush + close).
         if (captureServer)
             await captureServer.shutdown();
-        server.close();
-        await harness.close();
+        // Await each twin's HTTP server close (letting in-flight handlers drain)
+        // BEFORE releasing that twin's DB handle, so a late handler can't run
+        // against a closed DB (teardown errors / lost final recorder writes).
+        await Promise.all(booted.map(async ({ server, harness }) => {
+            await closeServer(server);
+            await harness.close();
+        }));
+        await recorder.close?.();
     }
 }

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

@@ -47,4 +47,41 @@ export interface RunScenarioHostedResult {
      *  row's duration. */
     durationMs: number;
 }
+/** Build the agent subprocess env for a hosted run.
+ *
+ * Two layers, in this order:
+ *
+ *  1. The LEGACY block (origin/main parity). Every hosted run — regardless of
+ *     which twins the session mounts — ALWAYS injected github + stripe vars
+ *     pointing at the primary/bare `twin_url`, plus POME_TWIN_BASE_URL and the
+ *     OTEL/task/run scaffolding. Byte-identical single-twin env is the bar, so
+ *     this block reproduces main's exact keys, values, AND insertion order.
+ *
+ *  2. The per-twin fan-out OVERLAY (M3). For each twin actually in the session,
+ *     set POME_<T>_REST_URL / POME_<T>_MCP_URL from `per_twin[T]` (distinct URLs
+ *     per twin) plus its provider bearer. For github/stripe this overwrites the
+ *     legacy values IN PLACE (same key → insertion order preserved); other twins
+ *     append new keys.
+ *
+ * MCP URL rule (regression guard): only trust `per_twin[T].mcp_url` when the
+ * cloud ACTUALLY RETURNED `per_twin` (`perTwinFromCloud`). A single-twin OLD
+ * cloud returns no `per_twin`; the schema synthesizes one whose `mcp_url`
+ * host-rewrites api.pome.sh→mcp.pome.sh with NO `/mcp` suffix. Trusting it would
+ * drift POME_*_MCP_URL off main's `${twin_url}/mcp`. So for a synthesized entry
+ * we construct `${api_url}/mcp`; only a cloud-returned value gets ensureMcpSuffix
+ * (the same normalization `pome session create` applies). */
+export declare function buildAgentEnv(params: {
+    session: CreateSessionResponse;
+    twins: string[];
+    /** True iff the cloud's create-session body carried a `per_twin` key. */
+    perTwinFromCloud: boolean;
+    prompt: string;
+    otlpEndpoint: string;
+    apiKey: string;
+    agentId?: string;
+    runId: string;
+    artifactsDir: string;
+    slug: string;
+    signalsPath: string;
+}): Record<string, string>;
 export declare function runScenarioHosted(options: RunScenarioHostedOptions): Promise<RunScenarioHostedResult>;