@data-fair/lib-agents-sim 0.2.0

package/gateway-capture.js

@@ -0,0 +1,64 @@
+function extractUserMessageText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content === null || content === undefined)
+        return '';
+    if (Array.isArray(content)) {
+        const texts = content
+            .filter((part) => typeof part === 'object' && part !== null && part.type === 'text')
+            .map((part) => part.text)
+            .filter((text) => typeof text === 'string');
+        if (texts.length > 0)
+            return texts.join(' ');
+        if (content.length > 0)
+            return JSON.stringify(content);
+    }
+    return '';
+}
+export function summariseRequest(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const b = body;
+    if (!Array.isArray(b.messages))
+        return null;
+    const users = b.messages.filter(m => m.role === 'user');
+    const last = users[users.length - 1];
+    return {
+        at: Date.now(),
+        model: b.model ?? '',
+        toolNames: (b.tools ?? []).map(t => t.function?.name ?? '').filter(Boolean),
+        messageCount: b.messages.length,
+        lastUserMessage: extractUserMessageText(last?.content),
+        toolCalls: b.messages.flatMap(m => (m.tool_calls ?? []).map(c => ({
+            name: c.function?.name ?? '',
+            arguments: c.function?.arguments ?? ''
+        })))
+    };
+}
+export function captureGateway(page) {
+    const exchanges = [];
+    page.on('request', req => {
+        if (!req.url().includes('/v1/chat/completions'))
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(req.postData() ?? '');
+        }
+        catch {
+            exchanges.push({
+                at: Date.now(),
+                model: '',
+                toolNames: [],
+                messageCount: 0,
+                lastUserMessage: '',
+                toolCalls: [],
+                unparsed: true
+            });
+            return;
+        }
+        const summary = summariseRequest(parsed);
+        if (summary)
+            exchanges.push(summary);
+    });
+    return exchanges;
+}

package/index.d.ts

@@ -0,0 +1,8 @@
+export type { SimulationCase, Transcript, RunSidecar } from './types.ts';
+export { createNeutralCwd, scrubEnv, isolationOptions, type Env } from './isolation.ts';
+export { captureGateway, summariseRequest, type GatewayExchange } from './gateway-capture.ts';
+export { nextUserMessage, personaSystemPrompt, personaPrompt, isDone, DONE } from './persona.ts';
+export { writeEvidence, evidenceDir } from './transcript.ts';
+export { selectCases } from './cases.ts';
+export { reportCases } from './report.ts';
+export { createChatDriver, type ChatRoot, TURN_TIMEOUT_MS } from './chat-driver.ts';

package/index.js

@@ -0,0 +1,7 @@
+export { createNeutralCwd, scrubEnv, isolationOptions } from "./isolation.js";
+export { captureGateway, summariseRequest } from "./gateway-capture.js";
+export { nextUserMessage, personaSystemPrompt, personaPrompt, isDone, DONE } from "./persona.js";
+export { writeEvidence, evidenceDir } from "./transcript.js";
+export { selectCases } from "./cases.js";
+export { reportCases } from "./report.js";
+export { createChatDriver, TURN_TIMEOUT_MS } from "./chat-driver.js";

package/isolation.d.ts

@@ -0,0 +1,16 @@
+export declare function createNeutralCwd(): string;
+/**
+ * Spelled structurally rather than as `NodeJS.ProcessEnv`, which would make
+ * `@types/node` an undeclared type dependency of this package: a consumer
+ * without it hits `TS2503: Cannot find namespace 'NodeJS'` on this .d.ts.
+ * `process.env` satisfies it, so nothing is lost at the call sites.
+ */
+export type Env = Record<string, string | undefined>;
+export declare function scrubEnv(env: Env): Env;
+export declare function isolationOptions(cwd: string, env?: Env): {
+    cwd: string;
+    env: Env;
+    settingSources: never[];
+    tools: never[];
+    strictMcpConfig: true;
+};

package/isolation.js

@@ -0,0 +1,37 @@
+/**
+ * The isolation guarantee (spec §1.2).
+ *
+ * Measured, not assumed: with `settingSources: []` but the repository as cwd, the
+ * model answered with the project's auto-memory index — naming the bugs this
+ * tooling exists to find. Auto-memory is keyed to the project directory, so only
+ * a neutral cwd removes it. `tools: []` matters just as much: without it the SDK
+ * offers 27 built-in tools and the model reaches for ToolSearch instead of the
+ * tools the request actually declared.
+ *
+ * These options are fixed. Nothing in a request may override them.
+ */
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+export function createNeutralCwd() {
+    // Deliberately meaningless name: ~367 tokens of SDK preamble are irreducible and
+    // include the cwd path, so the path itself must carry no signal about the product.
+    return fs.mkdtempSync(path.join(os.tmpdir(), 'bridge-'));
+}
+export function scrubEnv(env) {
+    const scrubbed = { ...env };
+    for (const key of Object.keys(scrubbed)) {
+        if (key.startsWith('CLAUDE_CODE_'))
+            delete scrubbed[key];
+    }
+    return scrubbed;
+}
+export function isolationOptions(cwd, env = process.env) {
+    return {
+        cwd,
+        env: scrubEnv(env),
+        settingSources: [],
+        tools: [],
+        strictMcpConfig: true
+    };
+}

package/missing-sdk.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The Agent SDK and MCP SDK are optional peers (see package.json) so a
+ * consumer who only wants the harness primitives (createChatDriver,
+ * captureGateway, selectCases, reportCases, ...) is not forced to install
+ * them. Two places load the Agent SDK lazily, inside the function that needs
+ * it rather than at module top level, so importing the barrel never requires
+ * it: `persona.ts`'s `nextUserMessage` (the simulated user) and the
+ * `df-agents-bridge` bin. Both catch a resulting ERR_MODULE_NOT_FOUND here
+ * and surface this message instead of node's raw error, naming the install
+ * command.
+ *
+ * Exported as a constant (not inlined) so a unit test can assert it still
+ * exists and still names the right packages.
+ */
+export declare const MISSING_SDK_MESSAGE: string;
+export declare function isMissingSdkError(err: unknown): boolean;

package/missing-sdk.js

@@ -0,0 +1,27 @@
+/**
+ * The Agent SDK and MCP SDK are optional peers (see package.json) so a
+ * consumer who only wants the harness primitives (createChatDriver,
+ * captureGateway, selectCases, reportCases, ...) is not forced to install
+ * them. Two places load the Agent SDK lazily, inside the function that needs
+ * it rather than at module top level, so importing the barrel never requires
+ * it: `persona.ts`'s `nextUserMessage` (the simulated user) and the
+ * `df-agents-bridge` bin. Both catch a resulting ERR_MODULE_NOT_FOUND here
+ * and surface this message instead of node's raw error, naming the install
+ * command.
+ *
+ * Exported as a constant (not inlined) so a unit test can assert it still
+ * exists and still names the right packages.
+ */
+export const MISSING_SDK_MESSAGE = [
+    '@data-fair/lib-agents-sim needs the Agent SDK and MCP SDK, which are optional peer dependencies and are not installed.',
+    'Install them with:',
+    '  npm i -D @anthropic-ai/claude-agent-sdk @modelcontextprotocol/sdk'
+].join('\n');
+export function isMissingSdkError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    if (err.code !== 'ERR_MODULE_NOT_FOUND')
+        return false;
+    const message = String(err.message ?? '');
+    return message.includes('@anthropic-ai/claude-agent-sdk') || message.includes('@modelcontextprotocol/sdk');
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@data-fair/lib-agents-sim",
+  "version": "0.2.0",
+  "description": "Primitives for judged browser simulations of the data-fair agents chat, plus a Claude Code bridge exposing the Agent SDK as an OpenAI-compatible provider.",
+  "main": "index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "df-agents-bridge": "bridge/index.js",
+    "df-agents-sim-init": "bin/init.js"
+  },
+  "files": [
+    "**/*.js",
+    "**/*.d.ts",
+    "templates/**"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@playwright/test": "^1.58.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.269",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    },
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  }
+}

package/persona.d.ts

@@ -0,0 +1,12 @@
+import type { SimulationCase } from './types.ts';
+export declare const DONE = "DONE";
+export declare function isDone(message: string): boolean;
+export declare function personaSystemPrompt(c: SimulationCase): string;
+export declare function personaPrompt(conversation: Array<{
+    role: string;
+    text: string;
+}>, turnsLeft: number): string;
+export declare function nextUserMessage(c: SimulationCase, conversation: Array<{
+    role: string;
+    text: string;
+}>, turnsLeft: number): Promise<string>;

package/persona.js

@@ -0,0 +1,96 @@
+/**
+ * The simulated user.
+ *
+ * It is a person with a goal, not a test script: it may be vague, change its
+ * mind, or push back, which is what makes this a simulation rather than a
+ * fixture. It runs under the same isolation as every other Claude role here —
+ * launched from this repo it would inherit the auto-memory index and know the
+ * bugs the scenario exists to find (spec §1.2).
+ */
+import { createNeutralCwd, isolationOptions } from "./isolation.js";
+import { MISSING_SDK_MESSAGE, isMissingSdkError } from "./missing-sdk.js";
+export const DONE = 'DONE';
+let neutralCwd;
+export function isDone(message) {
+    if (!message)
+        return false;
+    // Normalize the message: trim, strip quotes/backticks, strip trailing punctuation, uppercase
+    let normalized = message.trim();
+    // Strip surrounding quotes or backticks
+    if ((normalized.startsWith('"') && normalized.endsWith('"')) ||
+        (normalized.startsWith("'") && normalized.endsWith("'")) ||
+        (normalized.startsWith('`') && normalized.endsWith('`'))) {
+        normalized = normalized.slice(1, -1);
+    }
+    // Strip trailing punctuation
+    normalized = normalized.replace(/[.!,:]+$/, '');
+    // Uppercase and check if exactly DONE
+    normalized = normalized.toUpperCase().trim();
+    // Only true if it is exactly DONE, not a sentence containing the word
+    return normalized === DONE;
+}
+export function personaSystemPrompt(c) {
+    return [
+        c.persona,
+        '',
+        `What you want: ${c.goal}`,
+        '',
+        'You are talking to an assistant through a chat box on a web page. Behave like a real person:',
+        '- Say what you want in your own words. Do not explain how the assistant should do it.',
+        '- If a reply is vague, unhelpful, or does not actually show you the result, say so.',
+        '- If you are asked a question, answer it.',
+        '- Do not be artificially cooperative, and do not thank the assistant for work it has not done.',
+        '',
+        'Reply with ONLY the message you would type next — no quotes, no narration, no stage directions.',
+        `When you have what you wanted, or you are convinced you will not get it, reply with exactly ${DONE} and nothing else.`
+    ].join('\n');
+}
+export function personaPrompt(conversation, turnsLeft) {
+    if (conversation.length === 0)
+        return 'Write your first message to the assistant.';
+    const transcript = conversation.map(m => `${m.role === 'user' ? 'you' : 'assistant'}: ${m.text}`).join('\n\n');
+    const warning = turnsLeft <= 1
+        ? '\n\nThis is your last message. If you already have what you needed, reply ' + DONE + '.'
+        : '';
+    return [
+        'The conversation so far:',
+        '',
+        transcript,
+        '',
+        `Write your next message, or ${DONE} if you are finished.${warning}`
+    ].join('\n');
+}
+export async function nextUserMessage(c, conversation, turnsLeft) {
+    // Loaded here, not at module top level, so importing the package barrel
+    // never requires the Agent SDK — it is an optional peer, and a consumer who
+    // only wants the harness primitives must not pay for it. This is the only
+    // place in the exported surface that reaches for it at runtime.
+    let query;
+    try {
+        ({ query } = await import('@anthropic-ai/claude-agent-sdk'));
+    }
+    catch (err) {
+        if (isMissingSdkError(err))
+            throw new Error(MISSING_SDK_MESSAGE);
+        throw err;
+    }
+    neutralCwd ??= createNeutralCwd();
+    let text = '';
+    for await (const msg of query({
+        prompt: personaPrompt(conversation, turnsLeft),
+        options: {
+            ...isolationOptions(neutralCwd),
+            model: process.env.SIM_USER_MODEL ?? 'haiku',
+            systemPrompt: personaSystemPrompt(c),
+            maxTurns: 1
+        }
+    })) {
+        if (msg.type === 'assistant') {
+            for (const block of msg.message?.content ?? []) {
+                if (block.type === 'text' && block.text)
+                    text += block.text;
+            }
+        }
+    }
+    return text.trim();
+}

package/report.d.ts

@@ -0,0 +1,2 @@
+import type { SimulationCase } from './types.ts';
+export declare function reportCases(cases: SimulationCase[], evidenceDir: string): number;

package/report.js

@@ -0,0 +1,68 @@
+/**
+ * Reads the evidence and says what happened. Returns the failure count so the
+ * caller sets the exit code — a suite that cannot fail is not a suite.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+// The verdict is written by a model and is untrusted by construction — a
+// well-known slip is a stringified boolean ("false" instead of false), which
+// would otherwise pass truthiness checks and silently report success.
+function isValidVerdict(v, caseName) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    return o.case === caseName &&
+        typeof o.satisfied === 'boolean' &&
+        Array.isArray(o.frictions) &&
+        typeof o.summary === 'string';
+}
+export function reportCases(cases, evidenceDir) {
+    const read = (file) => {
+        try {
+            return JSON.parse(fs.readFileSync(path.join(evidenceDir, file), 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    };
+    let failures = 0;
+    const rows = [['case', 'model', 'turns', 'verdict', 'frictions', 'duration']];
+    for (const c of cases) {
+        const run = read(`sim-${c.name}.run.json`);
+        const verdict = read(`sim-${c.name}.verdict.json`);
+        let state;
+        let frictions = '-';
+        if (!run) {
+            state = 'not run';
+            failures++;
+        }
+        else if (!run.valid) {
+            state = `invalid (${run.error ?? 'unknown'})`;
+            failures++;
+        }
+        else if (!isValidVerdict(verdict, c.name)) {
+            state = 'not judged';
+            failures++;
+        }
+        else {
+            state = verdict.satisfied === true ? 'satisfied' : 'UNSATISFACTORY';
+            if (verdict.satisfied !== true)
+                failures++;
+            frictions = String(verdict.frictions.length);
+        }
+        rows.push([c.name, run?.assistantModel ?? '-', String(run?.turns ?? '-'), state, frictions, run ? `${Math.round(run.durationMs / 1000)}s` : '-']);
+    }
+    const widths = rows[0].map((_, i) => Math.max(...rows.map(r => r[i].length)));
+    for (const row of rows)
+        console.log(row.map((cell, i) => cell.padEnd(widths[i])).join('  '));
+    for (const c of cases) {
+        const verdict = read(`sim-${c.name}.verdict.json`);
+        if (!isValidVerdict(verdict, c.name) || verdict.frictions.length === 0)
+            continue;
+        console.log(`\n${c.name}: ${verdict.summary}`);
+        for (const f of verdict.frictions)
+            console.log(`  - turn ${f.turn}: ${f.what} → ${f.effect}`);
+    }
+    console.log(failures === 0 ? '\nall cases satisfied' : `\n${failures} case(s) need attention`);
+    return failures;
+}

package/templates/simulate-skill.md

@@ -0,0 +1,83 @@
+---
+name: simulate
+description: Run the scenario simulations - drive real browser conversations with a simulated user, then dispatch a judge per transcript. Use when asked to run the simulations, or after changing a system prompt, a tool description, or the chat orchestration.
+---
+
+# Running the scenario simulations
+
+Unit and e2e tests answer "does this mechanism work". This answers "did a person
+get what they came for", by having a simulated one try and then judging the
+transcript.
+
+## Before you start
+
+Three things must be true, and each fails confusingly if it is not:
+
+1. The dev stack is up — `bash dev/status.sh`.
+2. The workspace packages are built — `ls lib-vue/*.js lib-vuetify/*.js`. If they
+   are missing, e2e-style runs fail with "element not found".
+3. The bridge is running — `npm run dev-bridge`. The runner checks this and says so.
+
+Ask the user to start anything that is down. Never start or stop dev processes yourself.
+
+## Steps
+
+1. **Read the case list** in `simulations/cases/index.ts`. Note each `name` and `goal`.
+
+2. **Delete evidence from earlier runs.**
+
+   ```bash
+   rm -f simulations/tmp/sim-*
+   ```
+
+   Evidence persists and is only rewritten by a case that actually runs. Without
+   this, a case that fails to dispatch reports the previous run's verdict as
+   though it were this one's. Deleting first turns that into a visible `not run`.
+
+3. **Run the cases.**
+
+   ```bash
+   npm run simulate                              # every case
+   SIM_CASES=air-quality npm run simulate        # one case
+   ```
+
+   Models are pinned by `SIM_ASSISTANT_MODEL` (default `sonnet`) and
+   `SIM_USER_MODEL` (default `haiku`), and recorded per run, so verdicts from
+   different tiers are never compared silently.
+
+4. **Ignore the runner's own account of how it went.** The transcript at
+   `simulations/tmp/sim-<case>.json` is the evidence. A Playwright `passed` line
+   means the run was valid, not that the product behaved.
+
+   A case whose sidecar says `valid: false` must NOT be judged — read
+   `simulations/tmp/sim-<case>.run.json` for the recorded error instead.
+
+5. **Dispatch one `simulation-judge` subagent per valid case.** Give it paths, not
+   pasted content — transcripts carry every gateway request:
+
+   - the case name and its goal
+   - the transcript path, `simulations/tmp/sim-<case>.json`
+   - ask for the JSON verdict its own definition specifies
+
+6. **Write each verdict** to `simulations/tmp/sim-<case>.verdict.json` as raw JSON.
+   Strip any code fence the judge added. A malformed verdict reports as
+   `not judged`, which is deliberate — check the file rather than being surprised.
+
+7. **Report.**
+
+   ```bash
+   npm run simulate:report
+   ```
+
+   Relay the summary and the friction list. Exit code is non-zero if any case was
+   unsatisfactory, invalid, not judged, or never ran.
+
+## Reading the result
+
+The friction list is the point. "Unsatisfactory" tells you a run went badly; a
+friction point names the reply or tool result that misled the person and what they
+did next — that is what turns a run into a concrete change.
+
+Rate limits are the practical ceiling: three Claude roles per case on one
+subscription. A run cut short by a rate limit is an **invalid run**, not a product
+failure — check the sidecar before concluding anything.

package/templates/simulation-judge.md

@@ -0,0 +1,65 @@
+---
+name: simulation-judge
+description: Judge one scenario simulation transcript and return a JSON verdict. Use when asked to verdict a simulation run produced by the /simulate skill.
+tools: Read
+---
+
+You are judging whether a chat assistant actually served a person, from the
+transcript of one simulated conversation.
+
+You are given a case name, the person's goal, and a path to a transcript. Read
+the transcript with `Read`; do not ask for it to be pasted.
+
+The transcript holds:
+- `conversation` — what the person and the assistant said, as rendered on screen
+- `gateway` — every request the page made, carrying the tools it offered and the
+  tool calls the assistant actually made
+- `consoleErrors` — browser errors during the run
+
+`gateway` records what the browser SENT to the server, and each request carries
+the whole conversation so far — so the assistant's FINAL reply of a conversation
+never appears there, because no later request resends it. Read the final
+assistant turn from `conversation`, not `gateway`, and never conclude "the
+assistant never answered" from its absence in `gateway`.
+
+`gateway[].toolCalls` is CUMULATIVE: exchange N contains every tool call from
+turns 1..N, not just that turn's. Do not treat this as the same tool call being
+repeated — compare call counts across exchanges before filing repetition as a
+friction point, or you will report calls that never actually recurred.
+
+Judge the run against the goal, not against your idea of a good answer. The
+person is not a tester: if they had to ask three times, that is a finding even
+if the final answer was correct.
+
+**The friction list is the point.** A score says a run went badly; a friction
+point says which reply or tool result misled the person and what they concluded.
+That is what turns a run into a concrete change to a prompt or a tool
+description. Look especially for:
+- the assistant claiming it did something the `gateway` record shows it never did
+- a tool offered but never used when it was obviously needed, or called with
+  arguments that misread the person's words
+- the same tool called repeatedly with no progress
+- the person having to supply information the assistant could have looked up
+- an answer that is correct but never shown where the person asked for it
+
+Return ONLY raw JSON, no code fence, in exactly this shape:
+
+{
+  "case": "<case name>",
+  "satisfied": true | false,
+  "summary": "<one sentence: did the person get what they came for>",
+  "frictions": [
+    { "turn": <number>, "what": "<what the assistant or a tool did>", "effect": "<what the person concluded or had to do>" }
+  ],
+  "notes": "<anything a maintainer should know, or empty>"
+}
+
+`satisfied` is true only if the person's goal was actually met and visibly so.
+An empty `frictions` array is a real answer when a run went cleanly.
+
+A friction's `turn` is the 1-based index of the USER turn it occurred on — the
+Nth message the person sent, counting only the person's messages in
+`conversation` and not the assistant's. So a friction caused by the
+assistant's reply to the person's 3rd message is still `"turn": 3`. Count
+consistently this way so that two judges reading the same transcript would
+agree on the number.

package/transcript.d.ts

@@ -0,0 +1,9 @@
+import type { Transcript, RunSidecar } from './types.ts';
+/**
+ * Default evidence location, resolved against the host repo's cwd. Kept as the
+ * default rather than baked in: `reportCases(cases, evidenceDir)` already lets
+ * the host choose where evidence lives, so writing had to be able to follow it.
+ */
+export declare const evidenceDir: string;
+export type { Transcript, RunSidecar };
+export declare function writeEvidence(name: string, transcript: Transcript, sidecar: RunSidecar, dir?: string): void;

package/transcript.js

@@ -0,0 +1,21 @@
+/**
+ * Evidence files, split in two on purpose.
+ *
+ * The transcript is what the judge reads. The sidecar records whether the run
+ * was VALID — a case that fails to dispatch must report `not run` rather than
+ * silently re-reporting the previous run's verdict, which is why both are
+ * deleted before a suite and only rewritten by a case that actually executes.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Default evidence location, resolved against the host repo's cwd. Kept as the
+ * default rather than baked in: `reportCases(cases, evidenceDir)` already lets
+ * the host choose where evidence lives, so writing had to be able to follow it.
+ */
+export const evidenceDir = path.join(process.cwd(), 'simulations', 'tmp');
+export function writeEvidence(name, transcript, sidecar, dir = evidenceDir) {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, `sim-${name}.json`), JSON.stringify(transcript, null, 2));
+    fs.writeFileSync(path.join(dir, `sim-${name}.run.json`), JSON.stringify(sidecar, null, 2));
+}

package/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The shapes a host repo needs to write cases and read evidence.
+ */
+import type { GatewayExchange } from './gateway-capture.ts';
+export type SimulationCase = {
+    /** Evidence files are named after this; keep it filesystem-safe. */
+    name: string;
+    route: string;
+    /** Who the simulated user is. Becomes its system prompt. */
+    persona: string;
+    /** What they came for, in their own words. */
+    goal: string;
+    /** Give up after this many user turns; the judge sees how far it got. */
+    maxTurns: number;
+};
+export type Transcript = {
+    case: string;
+    goal: string;
+    persona: string;
+    route: string;
+    conversation: Array<{
+        role: string;
+        text: string;
+    }>;
+    gateway: GatewayExchange[];
+    consoleErrors: string[];
+};
+export type RunSidecar = {
+    case: string;
+    valid: boolean;
+    error?: string;
+    assistantModel: string;
+    userModel: string;
+    turns: number;
+    durationMs: number;
+    finishedAt: string;
+};

package/types.js

@@ -0,0 +1,4 @@
+/**
+ * The shapes a host repo needs to write cases and read evidence.
+ */
+export {};