orcareplay 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,104 @@
+# OrcaReplay
+
+### Your agent broke something at 2am. Replay it at 9am — exactly, offline, as many times as you like.
+
+Record any coding agent. Reproduce the run byte-for-byte with the network off. Fork it from any
+step onto a different model and see who gets it right.
+
+<a href="https://www.orcarouter.ai">
+  <img src="https://raw.githubusercontent.com/Continuum-AI-Corp/OrcaReplay/main/docs/orcarouter.svg" alt="OrcaRouter" height="28" align="left" hspace="10">
+</a>
+
+**Built by the team behind [OrcaRouter](https://www.orcarouter.ai)** — one API key and one endpoint
+for Claude, GPT, Gemini, Grok, DeepSeek, Qwen and the rest. It is what `orca setup` points at by
+default, and what makes `orca compare` a single command instead of four provider accounts.
+
+[All models](https://www.orcarouter.ai/models) · [OrcaCode Review](https://www.orcarouter.ai/code-review) · [X](https://x.com/OrcaRouter) · [Hugging Face](https://huggingface.co/orcarouter)
+
+<br clear="left">
+
+![Recording a Claude Code run, replaying it offline, then forking it onto two models](https://raw.githubusercontent.com/Continuum-AI-Corp/OrcaReplay/main/docs/demo-cli.gif)
+
+<sup>Real output from one session — a Claude Code run recorded, replayed with the network off, then
+forked at checkpoint 4 onto two models and graded by `npx tsc --noEmit`. Nothing here is mocked
+up.</sup>
+
+## Install
+
+```console
+npm i -g orcareplay
+orca doctor          # checks this machine can record at all
+```
+
+Node 20 or newer. No native dependencies — nothing to compile, nothing to download at install time.
+
+## Three commands
+
+```console
+orca record claude              # your agent, unmodified, doing whatever it does
+orca replay last                # the same run again — no network, no tokens, no charge
+orca replay last --from 4 --model claude-haiku-4-5 --ui
+```
+
+The third line is the one people stay for: same files, same conversation prefix, different model
+from step 4 onward. The model is the only variable, which is what makes the answer mean anything.
+
+## What it gives you
+
+**A timeline of what actually happened.** Every model turn with its token counts and stop reason,
+every tool call with its arguments and result, every shell command with its exit code, every file
+the run touched.
+
+```console
+$ orca show last
+SEQ  KIND   WHAT                          DETAIL
+12   TOOL   edit_file
+14   FILE   src/auth.ts                   modified +18 −4
+15   SHELL  ["npm","test","--","auth"]    /home/dev/api
+16   SHELL  shell result                  exit 1 · 8.4s
+17   ERROR  error
+```
+
+**What caused what.** Every edge says whether the recorder watched it happen or orca derived it
+just now, and names the rule either way.
+
+```console
+$ orca graph last --to 17
+FROM              TO                KIND      WHY
+12 tool.call      15 shell.exec     recorded  causes
+15 shell.exec     16 shell.result   recorded  shell result answers its exec
+16 shell.result   17 error          recorded  causes
+```
+
+**The same task on several models, graded by a command you choose.** Not a model marking its own
+homework — the verdict is the exit code of whatever you tell it to run, so the same prompt costs
+you a number you can act on rather than an opinion.
+
+```console
+$ orca compare last --from 4 --models claude-sonnet-5,claude-haiku-4-5 --verify "npx tsc --noEmit"
+MODEL                      VERDICT  TOKENS   COST       WALL
+claude-sonnet-5            pass     124/429  $0.006807  12.2s
+claude-haiku-4-5-20251001  pass     184/650  $0.003434  14.3s
+```
+
+Both passed here; the interesting column is what each one cost to get there.
+
+Plus a browser timeline (`orca ui`), a single self-contained HTML file you can attach to an issue
+(`orca export`), and shareable cards of one causal chain (`orca export --card`).
+
+## Which agents
+
+Claude Code, Codex, OpenCode, grok-cli, the Anthropic and OpenAI Agents SDKs, the Vercel AI SDK,
+and any harness that reads a base-URL environment variable — including ones this project has never
+heard of, via `ORCA_BASE_URL_VARS`. Harnesses that refuse to be redirected can be captured through
+TLS interception with a certificate authority minted for that one run and thrown away after it.
+
+`orca doctor` reports which of them it can find on your machine.
+
+## Full documentation
+
+**[github.com/Continuum-AI-Corp/OrcaReplay](https://github.com/Continuum-AI-Corp/OrcaReplay)** —
+the worked bug hunt, the trace format spec, the programmatic API, CI usage, what is stored and
+where, and the privacy model.
+
+Apache-2.0. The trace format spec is CC BY 4.0, so anything can read or write these traces.

package/dist/attach.d.ts

@@ -0,0 +1,48 @@
+export interface AdvertiseRequest {
+    /** The address the proxy is listening on. */
+    bind: string;
+    /** The port it actually bound, which is not the advertised one behind a port mapping. */
+    port: number;
+    /** An explicit host, optionally with its own `:port`, overriding both of the above. */
+    advertise?: string;
+}
+/**
+ * The origin a remote agent should be pointed at.
+ *
+ * `0.0.0.0` is a statement about listening, not an address: an agent handed `http://0.0.0.0:8080`
+ * fails in a way that looks like orca is broken rather than like the invocation was incomplete. So
+ * a wildcard bind must be paired with the name the sandbox actually reaches this machine by, and
+ * refusing is the only honest option — orca cannot discover that name, and guessing one produces a
+ * run that records nothing.
+ */
+export declare function advertisedUrl(req: AdvertiseRequest): string;
+export interface AttachRequest {
+    /** Where the remote agent should send its model traffic. */
+    proxyUrl: string;
+    /** Variables the named adapter would have set, already pointed at `proxyUrl`. */
+    adapterEnv: Record<string, string>;
+    /** Present only when the run is intercepting. Paths are local, and are only for the copy step. */
+    ca?: {
+        certPath: string;
+        bundlePath: string;
+    };
+    /** Where the CA will live *in the sandbox* once copied. Every printed path uses this. */
+    remoteCaPath?: string;
+}
+/**
+ * The variables to set on the far side.
+ *
+ * The CA paths are the remote ones throughout. Printing this machine's path is the subtle failure
+ * this function exists to prevent: the block runs cleanly, every variable is set, and the agent
+ * trusts nothing — because the file those variables name is not there.
+ */
+export declare function attachExports(req: AttachRequest): Record<string, string>;
+/**
+ * The block the operator pastes into the sandbox.
+ *
+ * The copy step comes first because the export block references a file that has to exist by the
+ * time the agent starts, and an operator who pastes the second half alone gets an agent that
+ * cannot verify the proxy it was just told to trust.
+ */
+export declare function attachInstructions(req: AttachRequest): string[];
+//# sourceMappingURL=attach.d.ts.map

package/dist/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../src/attach.ts"],"names":[],"mappings":"AAsCA,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAkB3D;AA2BD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,kGAAkG;IAClG,EAAE,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4BxE;AAOD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,EAAE,CAgB/D"}

package/dist/attach.js

@@ -0,0 +1,153 @@
+import { isIP } from 'node:net';
+/**
+ * Recording an agent orca does not launch.
+ *
+ * Every other capture path here ends in a child process: an adapter builds an environment and orca
+ * spawns the agent inside it. That is the design, and it has exactly one boundary it cannot cross
+ * — an agent that is not on this machine. A bot on a VPS, an agent inside a dev container or a
+ * cloud sandbox, a harness someone else's CI runs: there is no process to spawn, so there is no
+ * environment to build.
+ *
+ * Orca can still be reachable, and can still say precisely what to set. The proxy already accepts
+ * a bind address. What was missing is this half: the block of variables the operator pastes on the
+ * far side, which has to be right or the run comes back empty with nothing to explain why.
+ *
+ * Everything here is pure and returns data rather than printing, because the failure mode being
+ * guarded against is a *wrong instruction* — a path that exists here and not there, a wildcard
+ * address nothing can dial — and those are only testable if the strings are values.
+ */
+/**
+ * Variable names whose values must never be printed.
+ *
+ * The block goes to a terminal, and a terminal is scrollback, a screen share, a pasted ticket and
+ * a CI log. Over-matching here costs a line the operator did not need; under-matching prints
+ * somebody's API key, so the pattern is deliberately broad.
+ *
+ * Omitting them is also simply correct. The agent in the sandbox already holds whatever credential
+ * it authenticates with, and orca forwards it upstream untouched. Exporting the local machine's
+ * key would leak it; exporting the `orca-recorded` placeholder an adapter substitutes when the
+ * local environment has none would be worse — it would overwrite a working key over there and turn
+ * a functioning setup into a 401.
+ */
+const CREDENTIAL_LIKE = /(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIALS?)$/;
+/** Bind addresses that mean "every interface", and so mean nothing as a destination. */
+const WILDCARD_BINDS = new Set(['0.0.0.0', '::', '[::]', '*']);
+/**
+ * The origin a remote agent should be pointed at.
+ *
+ * `0.0.0.0` is a statement about listening, not an address: an agent handed `http://0.0.0.0:8080`
+ * fails in a way that looks like orca is broken rather than like the invocation was incomplete. So
+ * a wildcard bind must be paired with the name the sandbox actually reaches this machine by, and
+ * refusing is the only honest option — orca cannot discover that name, and guessing one produces a
+ * run that records nothing.
+ */
+export function advertisedUrl(req) {
+    if (req.advertise !== undefined && req.advertise.trim() !== '') {
+        const host = req.advertise
+            .trim()
+            .replace(/^https?:\/\//, '')
+            .replace(/\/+$/, '');
+        // A host the operator wrote a port into is used as-is: behind a port-mapped container the
+        // reachable port is not the one orca bound, and orca has no way to learn the mapping.
+        return `http://${hasPort(host) ? host : `${bracketed(host)}:${req.port}`}`;
+    }
+    if (WILDCARD_BINDS.has(req.bind)) {
+        throw new Error(`--bind ${req.bind} listens on every interface, which is not an address an agent can ` +
+            'connect to. Add --advertise <host> naming how the sandbox reaches this machine, ' +
+            'e.g. --advertise 10.0.0.5 or --advertise host.docker.internal.');
+    }
+    return `http://${bracketed(req.bind)}:${req.port}`;
+}
+/** A bare IPv6 literal is not a URL host until it is bracketed. */
+function bracketed(host) {
+    if (host.startsWith('['))
+        return host;
+    return isIP(host) === 6 ? `[${host}]` : host;
+}
+/**
+ * Does this host already carry its own port?
+ *
+ * An IPv6 literal is mostly colons, so the last one says nothing on its own: `fd00::1` ends in
+ * `:1`, which reads as a port and is not one. Answering wrongly drops the real port and hands the
+ * sandbox `http://fd00::1`, which means port 80 and connects to nothing.
+ *
+ * A bracketed host is unambiguous — anything after the `]` is a port. An unbracketed one carries a
+ * port only if it has exactly one colon, because more than one makes it an address rather than a
+ * host-and-port.
+ */
+function hasPort(host) {
+    const close = host.lastIndexOf(']');
+    if (close !== -1)
+        return /^:\d+$/.test(host.slice(close + 1));
+    const first = host.indexOf(':');
+    if (first === -1 || first !== host.lastIndexOf(':'))
+        return false;
+    return /^\d+$/.test(host.slice(first + 1));
+}
+/**
+ * The variables to set on the far side.
+ *
+ * The CA paths are the remote ones throughout. Printing this machine's path is the subtle failure
+ * this function exists to prevent: the block runs cleanly, every variable is set, and the agent
+ * trusts nothing — because the file those variables name is not there.
+ */
+export function attachExports(req) {
+    const env = {};
+    for (const [name, value] of Object.entries(req.adapterEnv)) {
+        if (CREDENTIAL_LIKE.test(name))
+            continue;
+        env[name] = value;
+    }
+    if (!req.ca || !req.remoteCaPath)
+        return env;
+    env.HTTPS_PROXY = req.proxyUrl;
+    env.https_proxy = req.proxyUrl;
+    // One path for all of them, unlike a local run. The bundle exists so an intercepted child keeps
+    // reaching the hosts orca deliberately does not decrypt; a sandbox that already trusts the
+    // public roots needs only the run CA added, and shipping one file is what makes the copy step a
+    // single line the operator will actually run.
+    for (const name of [
+        'NODE_EXTRA_CA_CERTS',
+        'SSL_CERT_FILE',
+        'REQUESTS_CA_BUNDLE',
+        'CURL_CA_BUNDLE',
+        'AWS_CA_BUNDLE',
+        'DENO_CERT',
+    ]) {
+        env[name] = req.remoteCaPath;
+    }
+    // Deliberately not carried across. `NO_PROXY` is set for a local run so the agent's plaintext
+    // calls to the proxy do not loop back through it; inherited into a sandbox it is just a list of
+    // hosts that machine will refuse to proxy, which is a silent way to record nothing.
+    return env;
+}
+/** Single-quote a value so no shell can reinterpret it, however it was spelled. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The block the operator pastes into the sandbox.
+ *
+ * The copy step comes first because the export block references a file that has to exist by the
+ * time the agent starts, and an operator who pastes the second half alone gets an agent that
+ * cannot verify the proxy it was just told to trust.
+ */
+export function attachInstructions(req) {
+    const lines = [];
+    if (req.ca && req.remoteCaPath) {
+        lines.push(`# 1. copy the run's certificate authority into the sandbox:`);
+        lines.push(`#    scp ${req.ca.bundlePath} <sandbox>:${req.remoteCaPath}`);
+        lines.push(`#    (or: docker cp ${req.ca.bundlePath} <container>:${req.remoteCaPath})`);
+        lines.push(`# 2. then, in the sandbox, before starting your agent:`);
+    }
+    else {
+        lines.push(`# in the sandbox, before starting your agent:`);
+    }
+    for (const [name, value] of Object.entries(attachExports(req))) {
+        lines.push(`export ${name}=${shellQuote(value)}`);
+    }
+    // Said out loud, because a block with no key in it reads as an incomplete one.
+    lines.push(`# your agent's own credential is unchanged — orca forwards it upstream`);
+    return lines;
+}
+//# sourceMappingURL=attach.js.map

package/dist/attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../src/attach.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,eAAe,GAAG,6CAA6C,CAAC;AAEtE,wFAAwF;AACxF,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAW/D;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,GAAqB;IACjD,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC/D,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS;aACvB,IAAI,EAAE;aACN,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;aAC3B,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACvB,0FAA0F;QAC1F,sFAAsF;QACtF,OAAO,UAAU,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;IAC7E,CAAC;IACD,IAAI,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,UAAU,GAAG,CAAC,IAAI,oEAAoE;YACpF,kFAAkF;YAClF,gEAAgE,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;AACrD,CAAC;AAED,mEAAmE;AACnE,SAAS,SAAS,CAAC,IAAY;IAC7B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,KAAK,KAAK,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAClE,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC;AAaD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAkB;IAC9C,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3D,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QACzC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACpB,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY;QAAE,OAAO,GAAG,CAAC;IAE7C,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,QAAQ,CAAC;IAC/B,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,QAAQ,CAAC;IAC/B,gGAAgG;IAChG,2FAA2F;IAC3F,gGAAgG;IAChG,8CAA8C;IAC9C,KAAK,MAAM,IAAI,IAAI;QACjB,qBAAqB;QACrB,eAAe;QACf,oBAAoB;QACpB,gBAAgB;QAChB,eAAe;QACf,WAAW;KACZ,EAAE,CAAC;QACF,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,YAAY,CAAC;IAC/B,CAAC;IACD,8FAA8F;IAC9F,gGAAgG;IAChG,oFAAoF;IACpF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mFAAmF;AACnF,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAkB;IACnD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,YAAY,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;QAC1E,KAAK,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC,UAAU,cAAc,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC;QAC1E,KAAK,CAAC,IAAI,CAAC,uBAAuB,GAAG,CAAC,EAAE,CAAC,UAAU,gBAAgB,GAAG,CAAC,YAAY,GAAG,CAAC,CAAC;QACxF,KAAK,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IACvE,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;IAC9D,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAC/D,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,+EAA+E;IAC/E,KAAK,CAAC,IAAI,CAAC,wEAAwE,CAAC,CAAC;IACrF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/commands/attach.d.ts

@@ -0,0 +1,52 @@
+import type { ParsedArgs } from '../args.js';
+import type { Output } from '../out.js';
+/**
+ * `orca attach` — record an agent this machine did not start.
+ *
+ * Everything else here launches the agent: an adapter builds an environment, orca spawns the
+ * process, and capture follows from that. It is a good design with one boundary it cannot cross —
+ * an agent that is not on this machine. A bot on a VPS, an agent inside a dev container or a cloud
+ * sandbox, a harness in someone else's CI: there is no process to spawn, so there is no
+ * environment to build and no way to say `orca record` at all.
+ *
+ * So this inverts it. Orca holds the proxy open, prints exactly what to export on the far side,
+ * and records whatever arrives until it is stopped. The recording that comes out is not a lesser
+ * one: same matcher, same events, same `orca replay`.
+ *
+ * The adapters are still what produce the variables — `--for claude` prints what the Claude Code
+ * adapter would have set, pointed at the advertised address instead of a loopback one. That keeps
+ * one source of truth for "which variable does this harness read", so a sandbox recording cannot
+ * drift from a local one.
+ */
+export interface AttachResult {
+    runId: string;
+    runDir: string;
+    modelExchanges: number;
+    events: number;
+    proxyUrl: string;
+    /** Replay sessions only: recorded exchanges served back, and requests nothing matched. */
+    reused: number;
+    unmatched: number;
+    /**
+     * Non-zero only when a replay session could not answer something the agent asked for.
+     *
+     * A recording session cannot fail this way: it ends because the operator stopped it, which is
+     * how it is meant to end. Whether it captured anything is reported by `capture.empty`, because
+     * an empty capture is a mistake to point at rather than an error to exit on.
+     */
+    exitCode: number;
+}
+export interface AttachOptions {
+    /**
+     * Resolves when the session should stop. Defaults to SIGINT — the operator pressing ctrl-C,
+     * which is how a session with no child process to wait on ends.
+     */
+    until?: Promise<void>;
+    /** Called once the proxy is listening, with the address a remote agent should use. */
+    onReady?: (info: {
+        proxyUrl: string;
+        runId: string;
+    }) => void;
+}
+export declare function attachCommand(args: ParsedArgs, out: Output, cwd?: string, options?: AttachOptions): Promise<AttachResult>;
+//# sourceMappingURL=attach.d.ts.map

package/dist/commands/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../src/commands/attach.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AASxC;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,sFAAsF;IACtF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC/D;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,SAAgB,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAQvB"}

package/dist/commands/attach.js

@@ -0,0 +1,285 @@
+import { once } from 'node:events';
+import { TraceReader, TraceWriter, ensureRunsDir, resolveRunSelector } from '@orcareplay/core';
+import { createProxy } from '@orcareplay/proxy';
+import { defaultAdapters } from '@orcareplay/adapters';
+import { advertisedUrl, attachExports, attachInstructions } from '../attach.js';
+import { ExchangeEventDeriver, appendDerivedEvents } from '../exchange-events.js';
+import { SerialQueue } from '../serial.js';
+import { planTlsCapture, recordedTlsHosts, setupTlsCapture } from '../tls-capture.js';
+import { loadExchanges } from './replay.js';
+import { upstreamPlan } from '../upstream.js';
+import { ORCA_VERSION } from '../version.js';
+export async function attachCommand(args, out, cwd = process.cwd(), options = {}) {
+    const minted = [];
+    try {
+        return await runAttached(args, out, cwd, options, minted);
+    }
+    catch (err) {
+        for (const ca of minted)
+            await ca.dispose().catch(() => undefined);
+        throw err;
+    }
+}
+async function runAttached(args, out, cwd, options, minted) {
+    const registry = defaultAdapters();
+    const bind = args.str('bind') ?? '127.0.0.1';
+    const advertise = args.str('advertise');
+    const requestedPort = args.num('port') ?? 0;
+    // Resolved before the run directory is made, so an invocation that cannot work — a wildcard bind
+    // with nothing to advertise — leaves nothing behind to clean up. The port is not known yet when
+    // orca is choosing one, and does not need to be: only the host can make this fail.
+    advertisedUrl({
+        bind,
+        port: requestedPort === 0 ? 1 : requestedPort,
+        ...(advertise === undefined ? {} : { advertise }),
+    });
+    /**
+     * Serving a recording back instead of recording a new one.
+     *
+     * `orca replay` launches the agent, which is right for a run orca recorded by launching it and
+     * impossible for one that came from a sandbox — the agent may not exist on this machine at all.
+     * So replay attaches too: same proxy, same matcher, same blocked egress, and the operator points
+     * the same remote agent at it.
+     */
+    // The parser turns a flag with no value into `true`, so a bare `--replay` — or `--replay
+    // --tls-intercept`, where the next token is itself a flag — would read as absent and start a
+    // *recording* session against the live provider. That is the worst direction to fail in.
+    if (args.has('replay') && args.str('replay') === undefined) {
+        throw new Error('--replay needs the run to serve: orca attach --replay <run>, or --replay last');
+    }
+    const replaySelector = args.str('replay');
+    const replaying = replaySelector
+        ? await (async () => {
+            const runDir = (await resolveRunSelector(cwd, replaySelector)).dir;
+            const reader = await TraceReader.open(runDir);
+            return {
+                exchanges: await loadExchanges(reader),
+                hosts: recordedTlsHosts(await reader.events()),
+                // Which harness made the recording. It will be the one connecting again, so it is the
+                // right default for the block the operator pastes.
+                adapter: reader.manifest().adapter?.id,
+            };
+        })()
+        : undefined;
+    /**
+     * `exec` is the honest default for a fresh session: orca does not know what will connect, and
+     * detecting an agent from this directory would be a guess about a machine it cannot see. For a
+     * replay it is the wrong default and a useless one — `exec` sets no variables, so the block the
+     * operator is meant to paste comes out empty. The recording names the harness, so use it.
+     */
+    const adapterName = args.str('for') ?? replaying?.adapter ?? 'exec';
+    const adapter = registry.get(adapterName);
+    // The last thing that can refuse the run, and it runs before the trace exists: a writer created
+    // first and abandoned by a throw leaves an unsealed run directory behind, which then wins `last`
+    // — so the next command someone types operates on the session that never happened.
+    planTlsCapture(args, replaying?.hosts);
+    const dir = await ensureRunsDir(cwd);
+    const writer = await TraceWriter.create(dir, {
+        adapter: { id: adapter.id, version: ORCA_VERSION, harness_version: adapter.harnessVersions },
+        argv: [adapterName],
+        cwd,
+        orcaVersion: ORCA_VERSION,
+    });
+    let modelExchanges = 0;
+    let turn = 0;
+    let unmatched = 0;
+    const writes = new SerialQueue();
+    const plan = await upstreamPlan(args);
+    const tls = await setupTlsCapture({
+        args,
+        out,
+        ...(replaying ? { recordedHosts: replaying.hosts } : {}),
+        writer,
+        writes,
+        // Out-of-band traffic belongs to whichever turn was in progress when it happened, exactly as in
+        // a launched recording. A fixed 0 filed every net.* event against the start of the session.
+        turn: () => turn,
+    });
+    if (tls.ca)
+        minted.push(tls.ca);
+    // Read before the proxy closes: `stats()` is a snapshot of a live object, and the teardown in
+    // `finally` is the last moment it is still meaningful.
+    let stats = {
+        matchedExact: 0,
+        matchedInexact: 0,
+        unmatched: 0,
+    };
+    const deriver = new ExchangeEventDeriver();
+    const proxy = await createProxy({
+        // A replay session serves the recording and blocks egress, exactly as `orca replay` does. The
+        // only difference is which side starts the agent, and that is not a difference the proxy has.
+        mode: replaying ? 'replay' : 'record',
+        ...(replaying ? { exchanges: replaying.exchanges, loose: args.bool('loose') } : {}),
+        host: bind,
+        port: requestedPort,
+        upstream: plan.upstream,
+        upstreamHeaders: plan.headers,
+        ...tls.proxyOptions,
+        onUnmatched: () => {
+            unmatched += 1;
+        },
+        onExchange: (exchange) => {
+            modelExchanges += 1;
+            turn += 1;
+            const at = turn;
+            writes.push(() => appendDerivedEvents(writer, deriver, exchange, at));
+        },
+    });
+    const advertised = advertisedUrl({
+        bind,
+        port: proxy.port,
+        ...(advertise === undefined ? {} : { advertise }),
+    });
+    try {
+        const proxyUrl = advertised;
+        // What the adapter would have put into a child's environment, pointed at the reachable
+        // address rather than a loopback one. `runDir` is this machine's, and is only ever used by
+        // adapters that write a scratch file — none of which a remote agent would read, which is why
+        // `--for` is documented as the variables rather than as full instrumentation.
+        const launch = await adapter.prepare({
+            runId: writer.runId,
+            cwd,
+            runDir: writer.runDir,
+            proxyUrl,
+            userArgs: ['<your agent>'],
+            env: process.env,
+        });
+        const remoteCaPath = args.str('remote-ca-path') ?? '/tmp/orca-ca.crt';
+        const instructions = attachInstructions({
+            proxyUrl,
+            adapterEnv: launch.env,
+            ...(proxy.tls
+                ? {
+                    ca: { certPath: proxy.tls.caCertPath, bundlePath: proxy.tls.caBundlePath },
+                    remoteCaPath,
+                }
+                : {}),
+        });
+        out.phase('attached', {
+            run: writer.runId,
+            proxy: proxyUrl,
+            for: adapter.id,
+            ...(replaying
+                ? { serving: replaySelector, exchanges: replaying.exchanges.length, egress: 'blocked' }
+                : {}),
+        });
+        if (proxy.tls) {
+            out.warn('tls.intercepting', {
+                hosts: proxy.tls.hosts,
+                ca_sha256: proxy.tls.fingerprint,
+            });
+            await writer.append({
+                type: 'note',
+                actor: 'orca',
+                turn: 0,
+                attrs: {
+                    rule: 'tls_intercept',
+                    hosts: proxy.tls.hosts,
+                    ca_sha256: proxy.tls.fingerprint,
+                },
+            });
+        }
+        /**
+         * An instruction the operator cannot act on is worse than none: the block pastes cleanly, the
+         * session waits, and nothing ever connects. Both shapes of that are visible from here.
+         */
+        const exported = attachExports({
+            proxyUrl,
+            adapterEnv: launch.env,
+            ...(proxy.tls
+                ? {
+                    ca: { certPath: proxy.tls.caCertPath, bundlePath: proxy.tls.caBundlePath },
+                    remoteCaPath,
+                }
+                : {}),
+        });
+        if (Object.keys(exported).length === 0) {
+            out.warn('attach.nothing_to_set', {
+                for: adapter.id,
+                cause: `${adapter.id} redirects nothing, and this session is not intercepting`,
+                next: 'name the harness with --for <agent>, or add --tls-intercept',
+            });
+        }
+        // A path under the run directory exists on this machine and nowhere else. The fetch hook is
+        // the live example: `--for node` names a preload orca just wrote here, so the block would
+        // instrument nothing over there while looking exactly as though it had.
+        const local = Object.entries(exported)
+            .filter(([, value]) => value.includes(writer.runDir))
+            .map(([name]) => name);
+        if (local.length > 0) {
+            out.warn('attach.local_path', {
+                vars: local.join(','),
+                cause: `${adapter.id} instruments by writing a file here and naming it in the environment`,
+                effect: 'those paths do not exist in the sandbox, so that half of the capture will not run',
+                next: 'copy the named files across, or use --tls-intercept instead',
+            });
+        }
+        out.plain('');
+        for (const line of instructions)
+            out.plain(`  ${line}`);
+        out.plain('');
+        out.plain(replaying
+            ? '  Serving the recording. Press ctrl-C when the agent is done.'
+            : '  Recording. Press ctrl-C when the agent is done.');
+        options.onReady?.({ proxyUrl, runId: writer.runId });
+        await (options.until ?? firstInterrupt());
+    }
+    finally {
+        stats = proxy.stats();
+        await writes.drain();
+        // The proxy closes after the writes drain, for the same reason recording does: a tunnel record
+        // arriving after the writer shut would have nowhere to go.
+        await proxy.close();
+        await tls.ca?.dispose();
+    }
+    /**
+     * The same warning a launched run gets, and it matters more here. A remote agent that was never
+     * given the block — or was given it in a shell that had already started the agent — produces a
+     * session that ends cleanly and records nothing, and there is no exit code to hint at it.
+     */
+    if (modelExchanges === 0 && !replaying) {
+        out.warn('capture.empty', {
+            exchanges: 0,
+            cause: 'nothing connected to the proxy while the session was open',
+            next: 'check the sandbox can reach the advertised address, and that the exports were set',
+        });
+    }
+    const manifest = await writer.close(0);
+    // A replay session did not record a run, and saying it did would send someone looking for turns
+    // in a trace that holds none. It reports what it actually did: how much of the recording the
+    // agent asked for, and what it asked for that the recording could not answer.
+    if (replaying) {
+        out.info('served', {
+            serving: replaySelector,
+            reused: `${stats.matchedExact + stats.matchedInexact}/${replaying.exchanges.length}`,
+            unmatched: stats.unmatched,
+        });
+    }
+    else {
+        out.info('recorded', {
+            run: writer.runId,
+            events: manifest.counts?.events ?? 0,
+            exchanges: modelExchanges,
+            dir: writer.runDir,
+        });
+    }
+    return {
+        runId: writer.runId,
+        runDir: writer.runDir,
+        modelExchanges,
+        events: manifest.counts?.events ?? 0,
+        // The address the agent should use, not the one orca bound — a caller reading this from
+        // `--json` needs something it can connect to, which a wildcard bind is not.
+        proxyUrl: advertised,
+        // Exact plus inexact: both were served from the recording, which is what "reused" means here.
+        // The distinction between them is a divergence, and divergences are reported on their own.
+        reused: replaying ? stats.matchedExact + stats.matchedInexact : 0,
+        unmatched: replaying ? stats.unmatched : unmatched,
+        exitCode: replaying && stats.unmatched > 0 ? 1 : 0,
+    };
+}
+/** Ctrl-C, which is the only way an operator ends a session with no child process to wait on. */
+async function firstInterrupt() {
+    await once(process, 'SIGINT');
+}
+//# sourceMappingURL=attach.js.map