orcareplay 0.1.0

package/dist/commands/setup.js

@@ -0,0 +1,177 @@
+import { createInterface } from 'node:readline/promises';
+import { modelInfoFor } from '@orcareplay/providers';
+import { configPath, gatewayHeaders, ORCAROUTER_CONSOLE, ORCAROUTER_URL, readConfig, writeConfig, } from '../config.js';
+/** OpenAI-compatible model listing, which every gateway worth pointing orca at implements. */
+async function probeModels(gateway, headers) {
+    const res = await fetch(`${gateway.replace(/\/+$/, '')}/v1/models`, { headers });
+    if (!res.ok)
+        throw new Error(`${res.status} ${res.statusText}`);
+    const body = (await res.json());
+    return (body.data ?? [])
+        .map((m) => m.id)
+        .filter((id) => typeof id === 'string')
+        .sort();
+}
+/** Prompts on a real terminal, and refuses to be one when nothing is attached. */
+function terminalAsk() {
+    if (!process.stdin.isTTY)
+        return undefined;
+    return async (question) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            return (await rl.question(question)).trim();
+        }
+        finally {
+            rl.close();
+        }
+    };
+}
+export async function setupCommand(args, out, deps = {}) {
+    const env = deps.env ?? process.env;
+    const probe = deps.probe ?? probeModels;
+    const ask = deps.ask ?? terminalAsk();
+    let url = args.str('gateway');
+    let key = args.str('key');
+    const keyEnv = args.str('key-env');
+    // OrcaRouter fills the blank, and Enter accepts it. Offered rather than imposed: the whole point
+    // of a gateway is that one origin serves several models, and most people asking for that do not
+    // have one already — but anyone who does types over it, and `--gateway` skips the question.
+    if (!url && ask)
+        url = await ask(`Gateway URL (serves the model APIs) [${ORCAROUTER_URL}]: `);
+    if (!url)
+        url = ORCAROUTER_URL;
+    if (!key && !keyEnv && ask) {
+        if (sameOrigin(url, ORCAROUTER_URL)) {
+            out.plain(`  get a key at ${ORCAROUTER_CONSOLE} — OrcaRouter keys start sk-orca-`);
+        }
+        key = await ask('API key (stored 0600; leave blank for none): ');
+    }
+    const gateway = { url };
+    // Stored key wins if both are given, and only one is ever written: keeping both would leave a
+    // credential on disk for someone who explicitly asked not to have one.
+    if (key)
+        gateway.api_key = key;
+    else if (keyEnv)
+        gateway.api_key_env = keyEnv;
+    const existing = await readConfig(env);
+    const config = { ...existing, gateway };
+    // Ask before saving is tempting, but saving first means an unreachable gateway still leaves you
+    // configured — being offline should not stop you setting up the thing you will use online.
+    const path = await writeConfig(config, env);
+    // `auth:`, not `key:` — the terminal guard redacts any field named `key`, which is right in
+    // general and would hide the one thing this line exists to tell you: whether a key was stored at
+    // all, and where it came from. The value is a description, never the credential.
+    out.info('config.saved', { path, mode: '0600', gateway: url, auth: describeKey(gateway) });
+    let available = [];
+    try {
+        available = await probe(url, gatewayHeaders(config, env));
+        if (available.length === 0) {
+            out.warn('gateway.no_models', { note: 'reachable, but it listed no models' });
+        }
+        else {
+            out.plain('');
+            out.plain(`  ${available.length} models available:`);
+            for (const m of available.slice(0, 20))
+                out.plain(`    ${m}`);
+            if (available.length > 20)
+                out.plain(`    … and ${available.length - 20} more — orca models`);
+        }
+        // Ask which of them to compare by default, so `orca compare` needs no flags afterwards. This
+        // is the half that makes setup worth running: a gateway with nothing chosen still leaves you
+        // typing a model list on every invocation, which is what the command exists to remove.
+        const chosen = args.str('models') ?? (ask ? await askModels(ask, available) : undefined);
+        if (chosen) {
+            config.models = chosen
+                .split(',')
+                .map((m) => m.trim())
+                .filter((m) => m !== '');
+            if (config.models.length > 0) {
+                await writeConfig(config, env);
+                out.info('config.models', { models: config.models.join(',') });
+            }
+        }
+    }
+    catch (err) {
+        out.warn('gateway.unreachable', {
+            why: String(err instanceof Error ? err.message : err),
+            note: 'the config was saved; fix the URL or key and run orca setup again',
+        });
+    }
+    out.plain('');
+    // Built from what the gateway actually serves, never from two model names picked here. Model ids
+    // are gateway-specific — OrcaRouter namespaces them by provider, a direct provider does not — so a
+    // hardcoded pair is a copyable line that fails against the gateway orca just configured.
+    out.plain(nextStep(config, available));
+    return config;
+}
+/** The line worth copying next, using real model ids wherever we have them. */
+function nextStep(config, available) {
+    if (config.models && config.models.length > 0)
+        return '  orca compare last --verify "npm test"';
+    if (available.length > 0) {
+        return `  orca compare last --models ${available.slice(0, 2).join(',')} --verify "npm test"`;
+    }
+    return '  orca models                    # what this gateway serves, then compare two of them';
+}
+/** Offer the gateway's own list, so the answer is a choice rather than a spelling test. */
+async function askModels(ask, available) {
+    const suggestion = available.slice(0, 3).join(',');
+    const answer = await ask(`Models to compare by default${suggestion ? ` [${suggestion}]` : ''} (comma-separated, blank to skip): `);
+    return answer === '' ? (suggestion === '' ? undefined : suggestion) : answer;
+}
+export async function modelsCommand(args, out, deps = {}) {
+    const env = deps.env ?? process.env;
+    const probe = deps.probe ?? probeModels;
+    const config = await readConfig(env);
+    if (!config.gateway?.url) {
+        out.plain('no gateway configured');
+        out.plain('');
+        out.plain(`  orca setup                    # ${ORCAROUTER_URL}, or any gateway you name`);
+        out.plain(`  orca setup --gateway <url> --key <key>`);
+        out.plain('');
+        out.plain(`  a key for the default gateway: ${ORCAROUTER_CONSOLE}`);
+        return [];
+    }
+    let models;
+    try {
+        models = await probe(config.gateway.url, gatewayHeaders(config, env));
+    }
+    catch (err) {
+        out.failure({
+            event: 'gateway.unreachable',
+            what: `could not reach ${config.gateway.url}`,
+            why: String(err instanceof Error ? err.message : err),
+            next: `check the URL and key in ${configPath(env)}, or run orca setup again`,
+        });
+        return [];
+    }
+    // Price where we know it, a dash where we do not. Inventing a number for an unknown model is
+    // how a comparison table ends up quoting a cost that was never real.
+    out.table(['MODEL', '$/MTOK IN', '$/MTOK OUT'], models.map((id) => {
+        const info = modelInfoFor(id);
+        return [
+            id,
+            info ? String(info.input_price_per_mtok) : '—',
+            info ? String(info.output_price_per_mtok) : '—',
+        ];
+    }));
+    return models;
+}
+/** Same origin, tolerating a trailing slash — used only to decide whether to print the key hint. */
+function sameOrigin(a, b) {
+    try {
+        return new URL(a).origin === new URL(b).origin;
+    }
+    catch {
+        return a.replace(/\/+$/, '') === b.replace(/\/+$/, '');
+    }
+}
+/** Says whether a key is set and where it came from, never what it is. */
+function describeKey(gateway) {
+    if (gateway.api_key)
+        return 'stored';
+    if (gateway.api_key_env)
+        return `from $${gateway.api_key_env}`;
+    return 'none';
+}
+//# sourceMappingURL=setup.js.map

package/dist/commands/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,80 @@
+import type { ParsedArgs } from './args.js';
+/**
+ * User-level configuration, which exists for exactly one job: let
+ * `orca compare --models a,b,c` reach several models without re-typing a gateway URL and a key on
+ * every invocation.
+ *
+ * That means this file holds a credential, and everything here follows from it. The file is
+ * `0600` inside a `0700` directory, the key can live in an environment variable instead of on
+ * disk, and nothing ever prints it back. The key itself never enters a trace either — the proxy
+ * adds it to the outbound request only, while what gets recorded is derived from the *incoming*
+ * request with auth stripped, so a gateway key orca injects is invisible to the recording by
+ * construction rather than by a rule someone has to remember.
+ */
+/**
+ * OrcaRouter, the gateway orca suggests when you do not name one.
+ *
+ * A default, never a redirect. It fills in the blank when you ask for a gateway — `orca setup` with
+ * no `--gateway` — and nothing more: a run with no gateway configured still proxies the agent's own
+ * traffic straight to the provider the agent was already talking to, on the agent's own key. Sending
+ * that somewhere the user never named would mean posting their source code to a third party as a
+ * side effect of pressing record, and their existing provider key would not authenticate there
+ * anyway. Naming a default is a recommendation; rerouting unconfigured traffic would be a decision
+ * taken on someone's behalf.
+ *
+ * The **origin**, deliberately without the `/v1` an OpenAI SDK wants. That SDK is configured with
+ * `base_url=https://api.orcarouter.ai/v1` because it appends only `/chat/completions`; orca appends
+ * the whole dialect path (`/v1/messages` or `/v1/chat/completions`) and probes `/v1/models`, so a
+ * `/v1` here would produce `/v1/v1/chat/completions`. Confirmed against the maintainers' own
+ * published action, whose `orcarouter-url` input defaults to
+ * `https://api.orcarouter.ai/v1/chat/completions`.
+ *
+ * Model ids there are namespaced by provider — `anthropic/claude-sonnet-4.6`,
+ * `openai/gpt-4o-mini`. Both places that read a model id already cope: dialect selection matches
+ * `(?:.*\/)?claude[-.]`, and `resolveModelId` strips the namespace before pricing.
+ */
+export declare const ORCAROUTER_URL = "https://api.orcarouter.ai";
+/** Where a person gets a key for the default gateway. Printed, never fetched. */
+export declare const ORCAROUTER_CONSOLE = "https://www.orcarouter.ai/console/token";
+export interface GatewayConfig {
+    /** Origin that serves the model APIs. One gateway usually serves both wire formats. */
+    url: string;
+    /** Stored key. Prefer `api_key_env` if you would rather not keep a credential on disk. */
+    api_key?: string;
+    /** Name of an environment variable to read the key from at call time. */
+    api_key_env?: string;
+}
+export interface OrcaConfig {
+    gateway?: GatewayConfig;
+    /** Default model list for `orca compare` when `--models` is not given. */
+    models?: string[];
+}
+/** XDG, with the documented fallback. Honours `XDG_CONFIG_HOME` so tests need no real home. */
+export declare function configPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Read the config, or an empty one.
+ *
+ * Never throws. A hand-edited file with a stray comma should cost you the gateway setting, not
+ * every orca command — and a tool people reach for when something is already broken is the worst
+ * possible thing to have its own unrecoverable failure mode.
+ */
+export declare function readConfig(env?: NodeJS.ProcessEnv): Promise<OrcaConfig>;
+export declare function writeConfig(config: OrcaConfig, env?: NodeJS.ProcessEnv): Promise<string>;
+/**
+ * The auth header for the configured gateway, or nothing.
+ *
+ * Returns `{}` rather than an empty bearer when no key is available. An `Authorization: Bearer `
+ * with nothing after it is worse than sending none: a gateway may accept it as an anonymous
+ * session, and the user never learns their key was not applied.
+ */
+export declare function gatewayHeaders(config: OrcaConfig, env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Where live model calls go: flag, then environment, then the configured gateway.
+ *
+ * Needed by record *and* by replay — `--loose` and any fork continue live, and a fork that ignored
+ * the override would quietly talk to the real provider instead of the gateway the user pointed it
+ * at. Same precedence, whichever command is running: the more specific and more recent the
+ * instruction, the more it wins.
+ */
+export declare function resolveUpstream(args: ParsedArgs, env?: NodeJS.ProcessEnv): Promise<Record<string, string> | undefined>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,8BAA8B,CAAC;AAE1D,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,4CAA4C,CAAC;AAE5E,MAAM,WAAW,aAAa;IAC5B,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC;IACZ,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,+FAA+F;AAC/F,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAGvE;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,UAAU,CAAC,CAQ1F;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAClB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,MAAM,CAAC,CASjB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,EAClB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,UAAU,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAgB7C"}

package/dist/config.js

@@ -0,0 +1,117 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * User-level configuration, which exists for exactly one job: let
+ * `orca compare --models a,b,c` reach several models without re-typing a gateway URL and a key on
+ * every invocation.
+ *
+ * That means this file holds a credential, and everything here follows from it. The file is
+ * `0600` inside a `0700` directory, the key can live in an environment variable instead of on
+ * disk, and nothing ever prints it back. The key itself never enters a trace either — the proxy
+ * adds it to the outbound request only, while what gets recorded is derived from the *incoming*
+ * request with auth stripped, so a gateway key orca injects is invisible to the recording by
+ * construction rather than by a rule someone has to remember.
+ */
+/**
+ * OrcaRouter, the gateway orca suggests when you do not name one.
+ *
+ * A default, never a redirect. It fills in the blank when you ask for a gateway — `orca setup` with
+ * no `--gateway` — and nothing more: a run with no gateway configured still proxies the agent's own
+ * traffic straight to the provider the agent was already talking to, on the agent's own key. Sending
+ * that somewhere the user never named would mean posting their source code to a third party as a
+ * side effect of pressing record, and their existing provider key would not authenticate there
+ * anyway. Naming a default is a recommendation; rerouting unconfigured traffic would be a decision
+ * taken on someone's behalf.
+ *
+ * The **origin**, deliberately without the `/v1` an OpenAI SDK wants. That SDK is configured with
+ * `base_url=https://api.orcarouter.ai/v1` because it appends only `/chat/completions`; orca appends
+ * the whole dialect path (`/v1/messages` or `/v1/chat/completions`) and probes `/v1/models`, so a
+ * `/v1` here would produce `/v1/v1/chat/completions`. Confirmed against the maintainers' own
+ * published action, whose `orcarouter-url` input defaults to
+ * `https://api.orcarouter.ai/v1/chat/completions`.
+ *
+ * Model ids there are namespaced by provider — `anthropic/claude-sonnet-4.6`,
+ * `openai/gpt-4o-mini`. Both places that read a model id already cope: dialect selection matches
+ * `(?:.*\/)?claude[-.]`, and `resolveModelId` strips the namespace before pricing.
+ */
+export const ORCAROUTER_URL = 'https://api.orcarouter.ai';
+/** Where a person gets a key for the default gateway. Printed, never fetched. */
+export const ORCAROUTER_CONSOLE = 'https://www.orcarouter.ai/console/token';
+/** XDG, with the documented fallback. Honours `XDG_CONFIG_HOME` so tests need no real home. */
+export function configPath(env = process.env) {
+    const base = env.XDG_CONFIG_HOME ?? join(env.HOME ?? homedir(), '.config');
+    return join(base, 'orca', 'config.json');
+}
+/**
+ * Read the config, or an empty one.
+ *
+ * Never throws. A hand-edited file with a stray comma should cost you the gateway setting, not
+ * every orca command — and a tool people reach for when something is already broken is the worst
+ * possible thing to have its own unrecoverable failure mode.
+ */
+export async function readConfig(env = process.env) {
+    try {
+        const raw = await readFile(configPath(env), 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed !== null && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function writeConfig(config, env = process.env) {
+    const path = configPath(env);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    // Set explicitly as well as passed to mkdir: an existing directory keeps whatever mode it had,
+    // and a 0755 directory makes the file's 0600 decoration.
+    await chmod(dirname(path), 0o700).catch(() => { });
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    await chmod(path, 0o600);
+    return path;
+}
+/**
+ * The auth header for the configured gateway, or nothing.
+ *
+ * Returns `{}` rather than an empty bearer when no key is available. An `Authorization: Bearer `
+ * with nothing after it is worse than sending none: a gateway may accept it as an anonymous
+ * session, and the user never learns their key was not applied.
+ */
+export function gatewayHeaders(config, env = process.env) {
+    const gateway = config.gateway;
+    if (!gateway)
+        return {};
+    const key = gateway.api_key ?? (gateway.api_key_env ? env[gateway.api_key_env] : undefined) ?? '';
+    if (key === '')
+        return {};
+    // Both header names, because a gateway fronting both wire formats reads whichever its callers
+    // send — and sending an extra header costs nothing while guessing wrong costs a confusing 401.
+    return { authorization: `Bearer ${key}`, 'x-api-key': key };
+}
+/**
+ * Where live model calls go: flag, then environment, then the configured gateway.
+ *
+ * Needed by record *and* by replay — `--loose` and any fork continue live, and a fork that ignored
+ * the override would quietly talk to the real provider instead of the gateway the user pointed it
+ * at. Same precedence, whichever command is running: the more specific and more recent the
+ * instruction, the more it wins.
+ */
+export async function resolveUpstream(args, env = process.env) {
+    const config = await readConfig(env);
+    const gateway = config.gateway?.url;
+    const out = {};
+    const anthropic = args.str('upstream-anthropic') ?? env.ORCA_UPSTREAM_ANTHROPIC ?? gateway;
+    const openai = args.str('upstream-openai') ?? env.ORCA_UPSTREAM_OPENAI ?? gateway;
+    if (anthropic)
+        out.anthropic = anthropic;
+    if (openai) {
+        out.openai = openai;
+        // The proxy resolves an origin by dialect id, and chat completions and the Responses API are
+        // two dialects sharing one provider — so a map holding only `openai` sends every Codex and
+        // Agents-SDK call straight past a gateway the user configured, on their own key, silently.
+        // `--upstream-openai` names a provider, not a wire format.
+        out['openai-responses'] = openai;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/exchange-events.d.ts

@@ -0,0 +1,72 @@
+import type { RecordedExchange } from '@orcareplay/proxy';
+import type { TraceWriter } from '@orcareplay/core';
+/**
+ * Turning intercepted model exchanges into trace events.
+ *
+ * This is where the project's central observation is cashed in. A tool result never appears in the
+ * response that requested it — the harness runs the tool and hands the result back on the *next*
+ * request. So we hold each `tool_use` open and close it when a later request carries the matching
+ * `tool_result`, which is how a proxy that only sees model traffic still reconstructs the whole
+ * tool loop without touching the agent.
+ *
+ * The consequence to keep in mind: a tool call whose result never comes back (the run ended, the
+ * agent crashed) stays unresolved, and `unresolved()` reports it rather than silently dropping it.
+ */
+export interface PendingToolCall {
+    id: string;
+    name: string;
+    input: unknown;
+    /** seq of the tool.call event, so the tool.result can point back at it. */
+    seq: number;
+    turn: number;
+}
+export interface DerivedEvent {
+    type: 'model.request' | 'model.response' | 'tool.call' | 'tool.result';
+    actor: 'agent' | 'model' | 'harness';
+    attrs: Record<string, unknown>;
+    payload?: unknown;
+    /** Index into the pending map, resolved to a real seq by the caller. */
+    causesToolId?: string;
+    /**
+     * Positions of earlier events *in this same batch* that caused this one.
+     *
+     * Seqs do not exist until the writer has appended, so the deriver cannot name them. It names
+     * positions in the array it is about to return instead, and the recorder swaps each one for the
+     * seq it wrote. Both edges this carries are observed rather than inferred: a `tool_use` block is
+     * inside the response that emitted it, and a `tool_result` block is inside the request that
+     * carried it back.
+     */
+    causesIndex?: number[];
+}
+export declare class ExchangeEventDeriver {
+    #private;
+    /** Tool calls that were issued but whose result never came back. */
+    unresolved(): PendingToolCall[];
+    /**
+     * Derive the events for one exchange. Returns them in the order they should be appended;
+     * `tool.result` events come first because they describe work that happened *before* this
+     * request was made.
+     */
+    derive(exchange: RecordedExchange, turn: number): DerivedEvent[];
+    markPending(toolUseId: string, seq: number): void;
+    seqOf(toolUseId: string): number | undefined;
+}
+/**
+ * Derive one exchange's events, resolve their causal references, and write them.
+ *
+ * Shared because it has two callers — `orca record` and the live half of a fork — and they drifted:
+ * the fork wrote every model exchange with no `causes` at all, so a forked run could be replayed
+ * and forked again but not explained. The seq resolution is the part that is easy to leave out,
+ * since it cannot happen until the writer has appended, so it lives here rather than in either
+ * caller.
+ */
+export declare function appendDerivedEvents(writer: TraceWriter, deriver: ExchangeEventDeriver, exchange: RecordedExchange, turn: number, 
+/**
+ * Each derived event as it is written.
+ *
+ * The recorder needs to know whether the agent ran any commands, so it can say when the shell
+ * layer was on and saw none of them. That is only knowable from what the model asked for, and
+ * this is the one place the derived events exist.
+ */
+onDerived?: (derived: DerivedEvent) => void): Promise<void>;
+//# sourceMappingURL=exchange-events.d.ts.map

package/dist/exchange-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-events.d.ts","sourceRoot":"","sources":["../src/exchange-events.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,eAAe,GAAG,gBAAgB,GAAG,WAAW,GAAG,aAAa,CAAC;IACvE,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,qBAAa,oBAAoB;;IAS/B,oEAAoE;IACpE,UAAU,IAAI,eAAe,EAAE;IAO/B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE;IA+EhE,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKjD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAI7C;AAyBD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,MAAM;AACZ;;;;;;GAMG;AACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,GAC1C,OAAO,CAAC,IAAI,CAAC,CA2Bf"}

package/dist/exchange-events.js

@@ -0,0 +1,170 @@
+export class ExchangeEventDeriver {
+    #pending = new Map();
+    /**
+     * Tool results already turned into events. Necessary because the conversation is resent in
+     * full every turn: without this, a result would be re-emitted on every subsequent request and
+     * a long run would accumulate one duplicate per turn per tool call.
+     */
+    #closed = new Set();
+    /** Tool calls that were issued but whose result never came back. */
+    unresolved() {
+        // A pending entry now outlives the result that answered it, so that the recorder can still
+        // resolve the call's seq for `causes` after derive has returned. `#closed` is the authority on
+        // whether a call was actually answered; "still in #pending" no longer means "unanswered".
+        return [...this.#pending.values()].filter((p) => !this.#closed.has(p.id));
+    }
+    /**
+     * Derive the events for one exchange. Returns them in the order they should be appended;
+     * `tool.result` events come first because they describe work that happened *before* this
+     * request was made.
+     */
+    derive(exchange, turn) {
+        const events = [];
+        /** Where the results this batch produced ended up, so the request can name them. */
+        const resultsAt = [];
+        for (const result of collectToolResults(exchange.canonicalRequest)) {
+            // Already accounted for on an earlier turn — the resent conversation is not new information.
+            if (this.#closed.has(result.tool_use_id))
+                continue;
+            // No pending call either: recording began mid-conversation, so this result is the first
+            // thing we know about that tool use. Record it rather than lose it.
+            const pending = this.#pending.get(result.tool_use_id);
+            events.push({
+                type: 'tool.result',
+                actor: 'harness',
+                attrs: {
+                    tool_use_id: result.tool_use_id,
+                    name: pending?.name ?? 'unknown',
+                    is_error: result.is_error ?? false,
+                    bytes: result.content.length,
+                },
+                payload: result.content,
+                causesToolId: result.tool_use_id,
+            });
+            resultsAt.push(events.length - 1);
+            // Deliberately not deleted here. The recorder resolves the call's seq *after* derive
+            // returns — it has to, since the seq only exists once the event is written — so dropping the
+            // entry in this loop meant `causes` came back empty on every tool result ever recorded, with
+            // no error to notice. `#closed` is what stops a resent result being re-emitted, so the
+            // pending entry can outlive the result it answered without any duplication.
+            this.#closed.add(result.tool_use_id);
+        }
+        events.push({
+            type: 'model.request',
+            actor: 'agent',
+            attrs: {
+                model: exchange.canonicalRequest.model,
+                dialect: exchange.dialect,
+                path: exchange.path,
+                messages: exchange.canonicalRequest.messages.length,
+                tools: exchange.canonicalRequest.tools?.length ?? 0,
+            },
+            payload: exchange.rawRequest,
+            // Absent rather than empty when nothing came back: an edge list naming nothing is noise a
+            // reader has to interpret, and `causes` is optional precisely so it can be left off.
+            ...(resultsAt.length > 0 ? { causesIndex: resultsAt } : {}),
+        });
+        const response = exchange.canonicalResponse;
+        events.push({
+            type: 'model.response',
+            actor: 'model',
+            attrs: {
+                model: response?.model ?? exchange.canonicalRequest.model,
+                stop_reason: response?.stop_reason ?? 'unknown',
+                input_tokens: response?.usage.input_tokens ?? 0,
+                output_tokens: response?.usage.output_tokens ?? 0,
+                status: exchange.status,
+                duration_ms: exchange.durationMs ?? 0,
+                streamed: exchange.streamed,
+            },
+            payload: exchange.rawResponse,
+        });
+        const responseAt = events.length - 1;
+        for (const use of collectToolUses(response)) {
+            events.push({
+                type: 'tool.call',
+                actor: 'model',
+                attrs: { tool_use_id: use.id, name: use.name, input: use.input },
+                causesIndex: [responseAt],
+            });
+            // seq is assigned by the writer; the caller patches it back in via markPending.
+            this.#pending.set(use.id, { id: use.id, name: use.name, input: use.input, seq: -1, turn });
+        }
+        return events;
+    }
+    markPending(toolUseId, seq) {
+        const p = this.#pending.get(toolUseId);
+        if (p)
+            p.seq = seq;
+    }
+    seqOf(toolUseId) {
+        const seq = this.#pending.get(toolUseId)?.seq;
+        return seq === undefined || seq < 0 ? undefined : seq;
+    }
+}
+function collectToolResults(req) {
+    const out = [];
+    // Only the trailing user message can carry results for the calls we are still holding open;
+    // scanning the whole conversation would re-emit every earlier result on every turn.
+    const last = req.messages[req.messages.length - 1];
+    if (!last || last.role !== 'user')
+        return out;
+    for (const block of last.content) {
+        if (block.type === 'tool_result')
+            out.push(block);
+    }
+    return out;
+}
+function collectToolUses(res) {
+    if (!res)
+        return [];
+    return res.content.filter((b) => b.type === 'tool_use');
+}
+/**
+ * Derive one exchange's events, resolve their causal references, and write them.
+ *
+ * Shared because it has two callers — `orca record` and the live half of a fork — and they drifted:
+ * the fork wrote every model exchange with no `causes` at all, so a forked run could be replayed
+ * and forked again but not explained. The seq resolution is the part that is easy to leave out,
+ * since it cannot happen until the writer has appended, so it lives here rather than in either
+ * caller.
+ */
+export async function appendDerivedEvents(writer, deriver, exchange, turn, 
+/**
+ * Each derived event as it is written.
+ *
+ * The recorder needs to know whether the agent ran any commands, so it can say when the shell
+ * layer was on and saw none of them. That is only knowable from what the model asked for, and
+ * this is the one place the derived events exist.
+ */
+onDerived) {
+    /** `written[i]` is the seq of the i-th derived event, which is what `causesIndex` refers to. */
+    const written = [];
+    for (const derived of deriver.derive(exchange, turn)) {
+        const causes = [];
+        if (derived.causesToolId) {
+            const seq = deriver.seqOf(derived.causesToolId);
+            if (seq !== undefined)
+                causes.push(seq);
+        }
+        for (const index of derived.causesIndex ?? []) {
+            const seq = written[index];
+            if (seq !== undefined)
+                causes.push(seq);
+        }
+        const event = await writer.append({
+            type: derived.type,
+            actor: derived.actor,
+            turn,
+            attrs: derived.attrs,
+            payload: derived.payload,
+            ...(causes.length > 0 ? { causes } : {}),
+        });
+        written.push(event.seq);
+        onDerived?.(derived);
+        if (derived.type === 'tool.call') {
+            deriver.markPending(String(derived.attrs['tool_use_id']), event.seq);
+        }
+    }
+}
+//# sourceMappingURL=exchange-events.js.map