@data-fair/lib-agents-sim 0.2.0

package/bridge/server.d.ts

@@ -0,0 +1,38 @@
+/**
+ * HTTP layer for the Claude Code bridge. Dev-only: presents the Claude Agent SDK
+ * as an OpenAI-compatible provider so the dev workspace can run on subscription
+ * models. Never imported by api/, ui/ or the published libs.
+ */
+import http from 'node:http';
+import { type Options } from '@anthropic-ai/claude-agent-sdk';
+import { type SdkMessage } from './conversation.ts';
+export declare const MODELS: {
+    id: string;
+    name: string;
+}[];
+/**
+ * The SDK's own `Options`, with every key the bridge depends on made REQUIRED.
+ *
+ * Every one of these is optional upstream, and the call site builds them by
+ * spreading `isolationOptions(...)` — so dropping the spread, or deleting the
+ * `abortController` line, used to leave tsc, eslint and the whole suite green
+ * while silently handing the model the repository's own settings, memory and
+ * 27 built-in tools. Naming the keys through `Pick` also makes an upstream
+ * RENAME fail closed: `Pick<Options, 'settingSources'>` stops compiling if the
+ * key goes away, where a spread would just have dropped it.
+ */
+type BridgeQueryOptions = Options & Required<Pick<Options, 'cwd' | 'env' | 'settingSources' | 'tools' | 'strictMcpConfig' | 'model' | 'systemPrompt' | 'mcpServers' | 'allowedTools' | 'abortController'>>;
+/**
+ * The SDK's `query`, narrowed to what the bridge uses. Injectable so a test can
+ * observe the options actually handed over without a network or a model — the
+ * isolation guarantee is a property of this call site, not only of the factory.
+ */
+export type BridgeQuery = (args: {
+    prompt: string;
+    options: BridgeQueryOptions;
+}) => AsyncIterable<SdkMessage>;
+export declare function createServer(opts: {
+    port: number;
+    query?: BridgeQuery;
+}): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+export {};

package/bridge/server.js

@@ -0,0 +1,196 @@
+/**
+ * HTTP layer for the Claude Code bridge. Dev-only: presents the Claude Agent SDK
+ * as an OpenAI-compatible provider so the dev workspace can run on subscription
+ * models. Never imported by api/, ui/ or the published libs.
+ */
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { createNeutralCwd, isolationOptions } from "../isolation.js";
+import { createToolServer, TOOL_TIMEOUT_MS } from "./tool-server.js";
+import { SessionStore, continuationOf, hashMessages, sameToolSet } from "./sessions.js";
+import { Conversation } from "./conversation.js";
+import { extractSystemPrompt, renderTranscript, toolNameToMcp, textChunk, toolCallsChunk, finalChunk, errorBody, MCP_SERVER_NAME } from "./openai.js";
+// The settings UI populates its dropdown from GET {baseURL}/models
+// (api/src/models/router.ts fetchOpenAICompatibleModels). A fixed list avoids a
+// network round trip; ids are what get passed back as the `model` field.
+export const MODELS = [
+    { id: 'opus', name: 'Claude Opus (Claude Code default alias)' },
+    { id: 'sonnet', name: 'Claude Sonnet (Claude Code default alias)' },
+    { id: 'haiku', name: 'Claude Haiku (Claude Code default alias)' },
+    { id: 'claude-haiku-4-5-20251001', name: 'Claude Haiku 4.5' }
+];
+// Hard ceiling on one HTTP request, so no upstream failure can hang the client
+// forever. Equal to TOOL_TIMEOUT_MS in tool-server.ts: a suspended tool handler
+// may legitimately wait that long (a tool wired to a human action button), so a
+// shorter ceiling would cut off a legitimate turn, and a longer one would leave
+// the client waiting past the point the SDK itself has given up.
+const TURN_CEILING_MS = TOOL_TIMEOUT_MS;
+// Dev-only and unauthenticated: it spends the developer's subscription. Binding
+// 0.0.0.0 would offer that to anyone on the network.
+const HOST = '127.0.0.1';
+// One neutral cwd for the process: the isolation guarantee only needs it to be
+// outside any project, and re-creating it per request would litter /tmp.
+// Created lazily, on first use, not at module load: importing this module
+// (e.g. from a test) must not have the side effect of creating a temp dir.
+let neutralCwd;
+function getNeutralCwd() {
+    neutralCwd ??= createNeutralCwd();
+    return neutralCwd;
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let raw = '';
+        req.on('data', c => { raw += c; });
+        req.on('end', () => { resolve(raw); });
+        req.on('error', reject);
+    });
+}
+export function createServer(opts) {
+    const runQuery = opts.query ?? query;
+    const store = new SessionStore();
+    const sweeper = setInterval(() => { store.sweep(); }, 60000);
+    sweeper.unref();
+    const server = http.createServer((req, res) => {
+        if (req.method === 'GET' && req.url === '/v1/models') {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ object: 'list', data: MODELS }));
+            return;
+        }
+        if (req.method === 'GET' && req.url === '/_bridge/status') {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ liveSessions: store.size, cwd: getNeutralCwd() }));
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/v1/chat/completions') {
+            handleCompletion(req, res, store, runQuery).catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error('claude-bridge request failed:', message);
+                if (res.writableEnded)
+                    return;
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify(errorBody(message)));
+                }
+                else {
+                    res.write(`data: ${JSON.stringify(errorBody(message))}\n\n`);
+                    res.end();
+                }
+            });
+            return;
+        }
+        res.writeHead(404, { 'content-type': 'application/json' });
+        res.end(JSON.stringify(errorBody('not found', 'invalid_request_error')));
+    });
+    server.listen(opts.port, HOST);
+    return server;
+}
+/**
+ * Race a turn against the ceiling. Every await of a turn goes through here:
+ * a promise that never settles used to leave the SSE response open forever.
+ */
+function withCeiling(turn) {
+    let timer;
+    const ceiling = new Promise(resolve => {
+        timer = setTimeout(() => { resolve({ type: 'error', message: `the upstream query produced nothing for ${TURN_CEILING_MS}ms` }); }, TURN_CEILING_MS);
+        if (timer.unref)
+            timer.unref();
+    });
+    return Promise.race([turn, ceiling]).finally(() => { if (timer)
+        clearTimeout(timer); });
+}
+async function handleCompletion(req, res, store, runQuery) {
+    const body = JSON.parse(await readBody(req));
+    const messages = body.messages ?? [];
+    const tools = body.tools ?? [];
+    const toolNames = tools.map(t => t.function.name);
+    const model = body.model ?? 'sonnet';
+    const id = `chatcmpl-${crypto.randomUUID()}`;
+    res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive'
+    });
+    const send = (payload) => {
+        if (res.writableEnded || res.destroyed)
+            return;
+        res.write(`data: ${JSON.stringify(payload)}\n\n`);
+    };
+    const sink = (text) => { send(textChunk(id, model, text)); };
+    // The client can vanish mid-turn: the tab closes, or the UI's idle watchdog
+    // aborts the fetch. Without this the conversation would stay in the store with
+    // a claude subprocess alive, streaming into a dead socket.
+    let active = null;
+    res.on('close', () => {
+        if (res.writableEnded)
+            return;
+        if (active)
+            store.delete(active.key);
+    });
+    // --- fast path: hand the tool results to the query that is waiting for them ---
+    const continuation = continuationOf(messages);
+    if (continuation) {
+        const live = store.get(continuation.key);
+        if (live && !live.isDead && live.awaits(continuation.toolResults.map(r => r.id)) && sameToolSet(live.toolNames, toolNames)) {
+            active = live;
+            live.lastSeen = Date.now();
+            // The history has grown by this turn, so the NEXT continuation hashes
+            // against it. rekey, never delete+set: delete aborts the query.
+            store.rekey(continuation.key, hashMessages(messages));
+            const turn = live.beginTurn(sink);
+            live.deliverToolResults(continuation.toolResults);
+            finish(await withCeiling(turn), live, store, res, send, id, model);
+            return;
+        }
+        // Diverged, expired, dead, answering calls this session never made, or
+        // declaring a tool set the live query was not built with.
+        if (live)
+            store.delete(continuation.key);
+    }
+    // --- replay path: a fresh session carrying the whole history ---
+    const key = hashMessages(messages);
+    store.delete(key);
+    const conv = new Conversation(key, toolNames);
+    active = conv;
+    const toolServer = createToolServer(tools, (name, args) => conv.handleToolCall(name, args));
+    const iterator = runQuery({
+        prompt: renderTranscript(messages),
+        options: {
+            ...isolationOptions(getNeutralCwd()),
+            model,
+            systemPrompt: extractSystemPrompt(messages),
+            // The tool server deliberately holds the LOW-LEVEL MCP `Server` (see
+            // tool-server.ts: the high-level `McpServer` helper rejects raw JSON
+            // Schema, which is exactly what an OpenAI request hands us). The SDK's
+            // config type names the helper; the two are wire-compatible, so the cast
+            // keeps the deliberate choice while letting the file type-check.
+            mcpServers: { [MCP_SERVER_NAME]: toolServer },
+            allowedTools: tools.map(t => toolNameToMcp(t.function.name)),
+            // Without this the SDK query is unabortable and every eviction — TTL, LRU,
+            // divergence, client disconnect — would drop the map entry while leaving a
+            // claude subprocess running.
+            abortController: conv.controller
+        }
+    });
+    store.set(conv);
+    finish(await withCeiling(conv.beginTurn(sink, iterator)), conv, store, res, send, id, model);
+}
+function finish(outcome, conv, store, res, send, id, model) {
+    if (outcome.type === 'tools') {
+        send(toolCallsChunk(id, model, outcome.calls));
+        conv.handedBack(outcome.calls.length);
+        send(finalChunk(id, model, 'tool_calls'));
+        // The session stays alive: its handlers are suspended, waiting for the
+        // results the client is about to compute.
+    }
+    else {
+        if (outcome.type === 'error')
+            send(errorBody(outcome.message));
+        send(finalChunk(id, model, 'stop', outcome.type === 'done' ? outcome.usage : undefined));
+        store.delete(conv.key);
+    }
+    if (res.writableEnded || res.destroyed)
+        return;
+    res.write('data: [DONE]\n\n');
+    res.end();
+}

package/bridge/sessions.d.ts

@@ -0,0 +1,46 @@
+import type { OpenAIMessage } from './openai.ts';
+export type LiveSession = {
+    key: string;
+    pending: Map<string, (result: string) => void>;
+    abort: () => void;
+    lastSeen: number;
+};
+export declare function hashMessages(messages: OpenAIMessage[]): string;
+/**
+ * A continuation request has exactly one shape: an assistant message carrying
+ * tool_calls, followed by the tool messages answering every one of them. Strip
+ * that suffix and you have the array the bridge saw when it suspended.
+ * Anything else is not a continuation.
+ */
+export declare function continuationOf(messages: OpenAIMessage[]): {
+    key: string;
+    toolResults: {
+        id: string;
+        content: string;
+    }[];
+} | null;
+/**
+ * The live query keeps the MCP tool server it was built with on the FIRST request
+ * of the turn, but the product registers tools mid-turn (use-agent-chat.ts
+ * reconciles the set as panels open). Adopting a live session whose tool set no
+ * longer matches would offer the model a stale set and make a freshly registered
+ * tool uncallable — so a mismatch forfeits the cache and replays instead.
+ */
+export declare function sameToolSet(a: string[], b: string[]): boolean;
+export declare class SessionStore {
+    #private;
+    constructor(opts?: {
+        ttlMs?: number;
+        max?: number;
+    });
+    get size(): number;
+    get(key: string, now?: number): LiveSession | undefined;
+    set(session: LiveSession): void;
+    delete(key: string): void;
+    /**
+     * Move a still-running session to the key its grown history now hashes to.
+     * Deliberately not `delete` + `set`: delete aborts the query.
+     */
+    rekey(oldKey: string, newKey: string): void;
+    sweep(now?: number): void;
+}

package/bridge/sessions.js

@@ -0,0 +1,109 @@
+/**
+ * Live session continuity (spec §2.4).
+ *
+ * The bridge keeps one SDK query alive per conversation so the prompt cache
+ * carries across turns. Correctness rests on one property: the key is a content
+ * hash of the exact history prefix, so ANY change upstream — compaction replacing
+ * turns with a summary, media tool results being redacted, a user retrying —
+ * produces a different key and therefore a MISS, which degrades to a full replay.
+ * There is no path by which a superseded history is silently answered.
+ */
+import crypto from 'node:crypto';
+export function hashMessages(messages) {
+    return crypto.createHash('sha256').update(JSON.stringify(messages)).digest('hex');
+}
+/**
+ * A continuation request has exactly one shape: an assistant message carrying
+ * tool_calls, followed by the tool messages answering every one of them. Strip
+ * that suffix and you have the array the bridge saw when it suspended.
+ * Anything else is not a continuation.
+ */
+export function continuationOf(messages) {
+    let i = messages.length;
+    const results = [];
+    while (i > 0 && messages[i - 1].role === 'tool') {
+        i--;
+        results.unshift({ id: messages[i].tool_call_id ?? '', content: messages[i].content ?? '' });
+    }
+    if (results.length === 0)
+        return null;
+    const assistant = messages[i - 1];
+    if (!assistant || assistant.role !== 'assistant' || !assistant.tool_calls?.length)
+        return null;
+    // Every call must be answered; a partial answer is not a continuation.
+    const answered = new Set(results.map(r => r.id));
+    if (assistant.tool_calls.some(c => !answered.has(c.id)))
+        return null;
+    return { key: hashMessages(messages.slice(0, i - 1)), toolResults: results };
+}
+/**
+ * The live query keeps the MCP tool server it was built with on the FIRST request
+ * of the turn, but the product registers tools mid-turn (use-agent-chat.ts
+ * reconciles the set as panels open). Adopting a live session whose tool set no
+ * longer matches would offer the model a stale set and make a freshly registered
+ * tool uncallable — so a mismatch forfeits the cache and replays instead.
+ */
+export function sameToolSet(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const set = new Set(a);
+    return b.every(name => set.has(name));
+}
+export class SessionStore {
+    #sessions = new Map();
+    #ttlMs;
+    #max;
+    constructor(opts = {}) {
+        this.#ttlMs = opts.ttlMs ?? 15 * 60 * 1000;
+        this.#max = opts.max ?? 20;
+    }
+    get size() { return this.#sessions.size; }
+    get(key, now = Date.now()) {
+        const s = this.#sessions.get(key);
+        if (!s)
+            return undefined;
+        if (now - s.lastSeen > this.#ttlMs) {
+            this.delete(key);
+            return undefined;
+        }
+        return s;
+    }
+    set(session) {
+        this.#sessions.set(session.key, session);
+        while (this.#sessions.size > this.#max) {
+            let oldest;
+            for (const s of this.#sessions.values()) {
+                if (!oldest || s.lastSeen < oldest.lastSeen)
+                    oldest = s;
+            }
+            if (!oldest)
+                break;
+            this.delete(oldest.key);
+        }
+    }
+    delete(key) {
+        const s = this.#sessions.get(key);
+        if (!s)
+            return;
+        this.#sessions.delete(key);
+        s.abort();
+    }
+    /**
+     * Move a still-running session to the key its grown history now hashes to.
+     * Deliberately not `delete` + `set`: delete aborts the query.
+     */
+    rekey(oldKey, newKey) {
+        const s = this.#sessions.get(oldKey);
+        if (!s)
+            return;
+        this.#sessions.delete(oldKey);
+        s.key = newKey;
+        this.#sessions.set(newKey, s);
+    }
+    sweep(now = Date.now()) {
+        for (const [key, s] of [...this.#sessions]) {
+            if (now - s.lastSeen > this.#ttlMs)
+                this.delete(key);
+        }
+    }
+}

package/bridge/tool-server.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Republishes the tool definitions from an OpenAI request as an in-process MCP
+ * server the SDK can offer to the model.
+ *
+ * Two non-obvious choices:
+ *  - the LOW-LEVEL `Server` is used, not the `McpServer` helper: the helper rejects
+ *    raw JSON Schema and demands Zod, while a request hands us JSON Schema already.
+ *  - handlers SUSPEND. `onCall` returns a promise the HTTP layer resolves when the
+ *    client's next request delivers the tool result, so the same query — and its
+ *    prompt cache — carries the whole conversation, and the model's tool_use is
+ *    answered by a real tool_result rather than by user text.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type OpenAIToolDef } from './openai.ts';
+export declare const TOOL_TIMEOUT_MS = 600000;
+export declare function listToolsFor(tools: OpenAIToolDef[]): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}[];
+export declare function createToolServer(tools: OpenAIToolDef[], onCall: (name: string, args: Record<string, unknown>) => Promise<string>): {
+    type: "sdk";
+    name: string;
+    instance: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    alwaysLoad: true;
+    timeout: number;
+};

package/bridge/tool-server.js

@@ -0,0 +1,40 @@
+/**
+ * Republishes the tool definitions from an OpenAI request as an in-process MCP
+ * server the SDK can offer to the model.
+ *
+ * Two non-obvious choices:
+ *  - the LOW-LEVEL `Server` is used, not the `McpServer` helper: the helper rejects
+ *    raw JSON Schema and demands Zod, while a request hands us JSON Schema already.
+ *  - handlers SUSPEND. `onCall` returns a promise the HTTP layer resolves when the
+ *    client's next request delivers the tool result, so the same query — and its
+ *    prompt cache — carries the whole conversation, and the model's tool_use is
+ *    answered by a real tool_result rather than by user text.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { MCP_SERVER_NAME } from "./openai.js";
+// A suspended handler must outlive a slow client turn — a tool wired to a human
+// action button can wait minutes. The default MCP timeout would abort it.
+export const TOOL_TIMEOUT_MS = 600000;
+export function listToolsFor(tools) {
+    return tools.map(t => ({
+        name: t.function.name,
+        description: t.function.description ?? '',
+        inputSchema: t.function.parameters ?? { type: 'object', properties: {} }
+    }));
+}
+export function createToolServer(tools, onCall) {
+    const instance = new Server({ name: MCP_SERVER_NAME, version: '1.0.0' }, { capabilities: { tools: {} } });
+    instance.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listToolsFor(tools) }));
+    instance.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const text = await onCall(req.params.name, (req.params.arguments ?? {}));
+        return { content: [{ type: 'text', text }] };
+    });
+    return {
+        type: 'sdk',
+        name: MCP_SERVER_NAME,
+        instance,
+        alwaysLoad: true,
+        timeout: TOOL_TIMEOUT_MS
+    };
+}

package/cases.d.ts

@@ -0,0 +1,10 @@
+import type { SimulationCase } from './types.ts';
+/**
+ * Select cases by name, or all of them when no name is given. Throws on an
+ * unknown name rather than silently running a subset — a typo that quietly
+ * runs nothing is worse than an error.
+ *
+ * Generic in the case type so a host repo's own case fields (added on top of
+ * SimulationCase) survive the round trip through this function.
+ */
+export declare function selectCases<T extends SimulationCase>(all: T[], names: string[]): T[];

package/cases.js

@@ -0,0 +1,18 @@
+/**
+ * Select cases by name, or all of them when no name is given. Throws on an
+ * unknown name rather than silently running a subset — a typo that quietly
+ * runs nothing is worse than an error.
+ *
+ * Generic in the case type so a host repo's own case fields (added on top of
+ * SimulationCase) survive the round trip through this function.
+ */
+export function selectCases(all, names) {
+    if (names.length === 0)
+        return all;
+    return names.map(name => {
+        const found = all.find(c => c.name === name);
+        if (!found)
+            throw new Error(`unknown simulation case: ${name} (have: ${all.map(c => c.name).join(', ')})`);
+        return found;
+    });
+}

package/chat-driver.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser-side interaction with the agents chat.
+ *
+ * The root is a Page when the chat IS the page (this repo's _dev pages) and a
+ * FrameLocator when it is embedded (data-fair, portals — lib-vuetify renders
+ * agents' own UI in an iframe, so the selectors are identical either way).
+ *
+ * Turn completion is detected from the composer button, not from message text:
+ * AgentChatInput renders a Stop button while streaming and a Send button
+ * otherwise. Waiting for text would end the turn at the first token of a
+ * multi-step tool conversation.
+ */
+import { type Page, type FrameLocator } from '@playwright/test';
+export type ChatRoot = Page | FrameLocator;
+export declare const TURN_TIMEOUT_MS: number;
+export declare function createChatDriver(root: ChatRoot): {
+    sendMessage(text: string): Promise<void>;
+    waitForTurn(timeoutMs?: number): Promise<void>;
+    readConversation(): Promise<{
+        role: "user" | "assistant";
+        text: string;
+    }[]>;
+};

package/chat-driver.js

@@ -0,0 +1,41 @@
+/**
+ * Browser-side interaction with the agents chat.
+ *
+ * The root is a Page when the chat IS the page (this repo's _dev pages) and a
+ * FrameLocator when it is embedded (data-fair, portals — lib-vuetify renders
+ * agents' own UI in an iframe, so the selectors are identical either way).
+ *
+ * Turn completion is detected from the composer button, not from message text:
+ * AgentChatInput renders a Stop button while streaming and a Send button
+ * otherwise. Waiting for text would end the turn at the first token of a
+ * multi-step tool conversation.
+ */
+import { expect } from '@playwright/test';
+const INPUT = 'Type your message...';
+// The app's own watchdog is a 90s IDLE timer that re-arms per stream part, so a
+// legitimate multi-step turn has no fixed ceiling on total time. This bounds the
+// harness generously rather than recording a slow-but-working turn as a failure.
+export const TURN_TIMEOUT_MS = 10 * 60 * 1000;
+export function createChatDriver(root) {
+    return {
+        async sendMessage(text) {
+            await root.getByPlaceholder(INPUT).fill(text);
+            await root.getByRole('button', { name: 'Send' }).click();
+        },
+        async waitForTurn(timeoutMs = TURN_TIMEOUT_MS) {
+            const stop = root.getByRole('button', { name: 'Stop' });
+            // The turn may already be finished by the time we look, so a missing Stop
+            // button is not an error — only one that never goes away is.
+            await stop.waitFor({ state: 'visible', timeout: 15000 }).catch(() => { });
+            await expect(stop).toHaveCount(0, { timeout: timeoutMs });
+        },
+        async readConversation() {
+            // evaluateAll, not page.evaluate: FrameLocator has no evaluate, and this
+            // runs in the right frame's context either way while preserving document order.
+            return await root.locator('.agent-chat__user-bubble, .assistant-content').evaluateAll(els => els.map(el => ({
+                role: el.classList.contains('agent-chat__user-bubble') ? 'user' : 'assistant',
+                text: (el.textContent ?? '').trim()
+            })));
+        }
+    };
+}

package/gateway-capture.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The evidence a run is judged on.
+ *
+ * Requests to the gateway carry the full message array AND the tool definitions
+ * the page registered, so they show what the assistant was actually offered and
+ * what it did with it — including sub-agent turns and compaction. The rendered
+ * DOM only shows what survived to the screen.
+ */
+import type { Page } from '@playwright/test';
+export type GatewayExchange = {
+    at: number;
+    model: string;
+    toolNames: string[];
+    messageCount: number;
+    lastUserMessage: string;
+    /** Tool calls are cumulative over the conversation so far, because the chat-completions
+     * protocol resends the entire message history on every request. Exchange N contains
+     * every tool call from turns 1..N, not just that turn's calls. This ensures the evidence
+     * shows the complete instruction context the assistant saw.
+     */
+    toolCalls: Array<{
+        name: string;
+        arguments: string;
+    }>;
+    /** When true, this exchange was received but postData could not be parsed. Evidence of
+     * a failed capture rather than an absent request.
+     */
+    unparsed?: true;
+};
+export declare function summariseRequest(body: unknown): GatewayExchange | null;
+export declare function captureGateway(page: Page): GatewayExchange[];