agenticreplay 0.1.0 → 0.1.2

package/RELEASING.md

@@ -1,183 +0,0 @@
-# Releasing
-
-Publishing is irreversible in the way that matters: npm allows an unpublish only briefly, and never
-lets the same version be published twice. So the whole thing is one gated workflow rather than a
-sequence of `npm publish` calls run by hand at the end of a long day.
-
-## Once, before the first release
-
-- An **`NPM_TOKEN`** repository secret, from an npm account that owns the `agenticreplay` name and the
-  `@agenticreplay` scope. An automation token, not a personal one.
-- **Actions enabled** for the repository, and Actions billing active on the org.
-- For the three Python packages, a **pending publisher** registered at pypi.org under
-  *Publishing → Add a pending publisher*, and a repository **environment named `pypi`**. There is
-  no PyPI secret: Trusted Publishing exchanges GitHub's OIDC identity for a short-lived upload
-  token, so there is nothing here to leak or rotate. One registration per package, all four other
-  fields identical:
-
-  | PyPI project | owner | repository | workflow | environment |
-  | --- | --- | --- | --- | --- |
-  | `agenticreplay-trace` | `Continuum-AI-Corp` | `AgenticReplay` | `release-python.yml` | `pypi` |
-  | `agenticreplay-openai-agents` | `Continuum-AI-Corp` | `AgenticReplay` | `release-openai-agents.yml` | `pypi` |
-  | `agenticreplay-langgraph` | `Continuum-AI-Corp` | `AgenticReplay` | `release-langgraph.yml` | `pypi` |
-
-  A pending publisher does not reserve the name — it is only honoured on the first upload, and
-  another account registering that name first invalidates it. So publish reasonably soon after
-  registering.
-
-## Two channels
-
-| | what it is | who gets it |
-| --- | --- | --- |
-| `latest` | a version someone decided to release | `npm i agenticreplay` |
-| `next` | main, once a day, as `0.2.4-main.g<sha>` | `npm i agenticreplay@next` |
-
-`next` is published by `.github/workflows/publish-next.yml` on a daily schedule — 04:00 UTC, which
-is noon in Beijing — and needs nothing from you. Every version on it is a **prerelease**, which npm
-excludes from `npm i agenticreplay` even though `0.2.4-main.gabc1234` sorts above `0.2.3`, so main is
-always installable and nobody is opted in to it by accident. `--tag next` never moves `latest`.
-
-It publishes **the newest commit on main that CI passed**, not whatever main happens to be at
-04:00, and it skips a day on which nothing merged — the version it would publish is already on the
-registry, and it asks npm rather than keeping state. Needing main on npm sooner than tomorrow is
-what **Actions → Publish next → Run workflow** is for; uncheck *dry run*.
-
-> **Why daily rather than on every merge.** A version is not free. npm serves a *packument* — the
-> metadata for every version of a package — on each install, and it grows with the version count:
-> `agenticreplay` is 20 KB at seven versions, `typescript` is 15.6 MB at 3820. That is roughly 4 KB
-> each, paid by everyone who installs, including people who only ever ask for `latest`. Publishing
-> per merge at this repository's rate would add ~2900 versions a year and land in that territory
-> inside twelve months. Daily is an eighth of it, and it is what `typescript` does for its own
-> `-dev` builds.
->
-> GitHub's cron is UTC only and best-effort — a scheduled run is commonly minutes late and can be
-> dropped under load — so read the schedule as "some time after noon", not as a clock.
-
-That is what keeps the rest of this page short: releasing is no longer the only way to get main
-into someone's hands, so it can stay deliberate.
-
-## Every release
-
-A release is a pull request that changes a version number. Merging it publishes `latest` and
-creates the tag.
-
-```console
-node scripts/set-version.mjs 0.3.0 --lock   # 13 manifests, every internal pin, and the lockfile
-node scripts/publish-order.mjs              # sanity: prints the order, fails if versions disagree
-npm run check                               # what the workflow runs anyway, faster to find here
-git commit -am "release 0.3.0" && git push  # open a PR, merge it
-```
-
-Merging that into main fires `.github/workflows/release.yml`, which sees a version with no tag,
-runs the full gate, publishes, and creates `v0.3.0` itself. Nothing else lands a release: every
-other merge leaves the version alone, and the workflow's `decide` job costs seconds to say so.
-
-A `v*` tag pushed by hand still works and does the same thing, for a release made from somewhere
-other than main.
-
-> **Why there is a script for what looks like one edit.** Twelve packages name each other by exact
-> version, so a bump is thirty-eight fields across thirteen manifests — and `npm version
-> --workspaces` moves each package's own `version` while leaving its dependants naming the previous
-> release. Publish that and `agenticreplay@0.3.0` depends on `@agenticreplay/core@0.2.0`, which npm will
-> never let you replace.
->
-> **And why `--lock` rather than `npm version`.** When a workspace sits at the new version and its
-> dependants still name the old one, npm stops treating them as satisfiable workspace links and
-> resolves the *published* old version instead, into `packages/<name>/node_modules/`. Those copies
-> shadow the source, `tsc` then checks the CLI against last release's `.d.ts`, and the errors it
-> reports name symbols that plainly do exist. `npm version` writes `package-lock.json` itself at
-> exactly that moment, so the bad resolution is recorded before the pins can be fixed — 0.2.1
-> shipped with correct manifests and two poisoned lockfile entries, and every later `npm ci`
-> honoured them. `set-version.mjs` moves the pins first and reconciles the lockfile after, so the
-> window does not exist.
->
-> Both halves are still checked rather than trusted: `publish-order.mjs` catches a manifest
-> mismatch, and `scripts/set-version.test.ts` asserts the committed lockfile links every
-> `@agenticreplay/*` instead of fetching it. The manifests can be perfectly consistent while the
-> lockfile is not.
-
-> **The registry step waits for npm, and has to.** The MCP Registry validates that the npm version
-> it is being told about exists, and npm's own publish output says a tarball "may take a few minutes
-> to become available". 0.2.3 published at `:06` and the registry call ran three seconds later, got
-> a 404 for the version that had just gone out, and failed the release — after npm had succeeded, so
-> re-running the whole workflow was not an option. The step now polls `npm view` for up to five
-> minutes before publishing. `registry-only` exists for the case where it still needs a retry.
-
-`.github/workflows/release.yml`, however it was triggered:
-
-1. decides whether there is anything to release — from main, a version that already has a tag is
-   not one, which is what makes an ordinary merge cost seconds instead of the whole suite;
-2. runs the full gate — format, build, 1000+ tests, conformance, neutrality;
-3. for a `v*` tag, checks it matches `packages/cli`'s version, so a published version always has a
-   tag pointing at it;
-4. publishes every workspace **in dependency order**, with npm provenance — skipping any package
-   already on npm at that version *from this commit*, so a run that died half way can be retried;
-5. creates the tag, when the release came from main — *after* the publish, so a tag means "this
-   went out" rather than "this was attempted", and so the next merge does not try again.
-
-> **A retry may resume, but only from the same commit.** A release version is a number a human
-> chose, and main can carry it across several commits, so "0.3.0 is on npm" does not mean this
-> commit put it there. If the loop dies at package five and someone then pushes the fix to main —
-> same version, still untagged — resuming would publish 6-12 from the new tree and leave 1-5 from
-> the old one, making `agenticreplay@0.3.0` a mixture no commit corresponds to, permanently. So the
-> skip compares npm's recorded `gitHead` with the commit being published and stops the release when
-> they disagree: bump the version instead.
-
-Both publishing workflows are `concurrency`-grouped and queue rather than cancel. The publish loop
-walks twelve packages one at a time, and a run cancelled half way leaves some of them on the
-registry at a version the rest do not name — which is the one state npm will not let anyone fix.
-
-To rehearse without sending anything: **Actions → Release → Run workflow**, leaving *dry run*
-checked. It packs and validates every tarball and publishes nothing.
-
-## The three Python packages
-
-They are not part of the npm release and do not share its version. Each ships on its own tag:
-
-| package | source | tag | workflow |
-| --- | --- | --- | --- |
-| `agenticreplay-trace` — the read-only reader for the trace format | `python/` | `py-v<version>` | `release-python.yml` |
-| `agenticreplay-openai-agents` — records the Agents SDK's own run structure | `python-openai-agents/` | `agents-v<version>` | `release-openai-agents.yml` |
-| `agenticreplay-langgraph` — records which LangGraph node ran, and in which superstep | `python-langgraph/` | `langgraph-v<version>` | `release-langgraph.yml` |
-
-```console
-# edit the version in the package's pyproject.toml, merge that, then:
-git tag agents-v0.1.0 && git push origin agents-v0.1.0
-```
-
-Each workflow refuses a tag that disagrees with its own `pyproject.toml`, runs the package's tests,
-builds, and `twine check`s before it uploads — the same gate the npm release applies, for the same
-reason. **Actions → Release (…) → Run workflow** with *dry run* left checked does everything except
-the upload, which is how to find out whether a release would work without making one.
-
-> **Why four workflows rather than one.** A Python-only fix must not force a version bump across
-> twelve npm packages, and the npm publish must not fail because PyPI had a bad day. The Python
-> packages are separated from each other for the same reason: they share a repository and nothing
-> else, so one tag publishing several would make every `agenticreplay-trace` fix reissue the adapters — and
-> PyPI does not allow reusing a version number.
-
-## Why order matters
-
-Internal dependencies are pinned to an exact version — `"@agenticreplay/core": "0.1.0"`, never `"*"`.
-A `*` resolves to whatever is latest on the registry, so a 0.1.0 CLI would silently pull a 0.9.0
-core, and on the very first publish it cannot resolve at all because nothing exists yet.
-
-The cost of pinning is that the CLI cannot be published before the core it names. `scripts/publish-order.mjs`
-topologically sorts the workspaces so that order is computed from the manifests rather than written
-down somewhere that quietly goes stale — and it exits non-zero if two packages disagree about a
-version, or if the dependency graph has a cycle.
-
-## Verifying a release actually works
-
-The end-to-end check that matters is not "did npm accept it" but "does a fresh install run":
-
-```console
-npm pack --workspaces --pack-destination /tmp/tarballs
-mkdir /tmp/verify && cd /tmp/verify && npm init -y
-npm i /tmp/tarballs/*.tgz
-./node_modules/.bin/agenticreplay doctor       # both shims must report ok — they run out of dist/
-```
-
-That last line is the one worth keeping. The MCP shim was resolved through a path that only worked
-inside the monorepo for the whole of v0's development; nothing caught it until a packaged install
-was actually run.

package/SECURITY.md

@@ -1,149 +0,0 @@
-# Security Policy
-
-## Reporting a vulnerability
-
-Please report security issues privately through
-[GitHub Security Advisories](https://github.com/askdkc/AgenticReplay/security/advisories/new)
-rather than a public issue. We aim to acknowledge within three working days.
-
-## The threat model, stated plainly
-
-An AgenticReplay trace contains full model requests, tool results, shell output, file contents and
-selected environment. **That is a near-perfect credential harvester if we get it wrong**, so
-redaction is in the write path from the first commit rather than bolted on later.
-
-What we do:
-
-- Environment capture is **deny-by-default** — nothing is recorded unless allowlisted. The inverse
-  is unshippable, because the interesting secrets are always the ones nobody thought of.
-- Auth material (`authorization`, `x-api-key`, `cookie`, `proxy-authorization`) is forwarded
-  upstream — an agent that cannot authenticate cannot run — and dropped at the proxy before the
-  exchange reaches the writer. It is never written at all, redacted or otherwise.
-- Everything that *is* written goes through the redactor: known key shapes (private key blocks,
-  JWTs, `sk-`, `gh[posur]_`, `AKIA…`, `xox[baprs]-`, `AIza…`) and high-entropy tokens become
-  `<secret:kind:hash8>`, hashed with a per-run salt that is never persisted. The same secret always
-  yields the same placeholder, so replay still matches structurally and repeated occurrences still
-  compare equal, while the secret itself is not recoverable from the trace.
-- Filesystem capture excludes `.env*`, `.ssh/`, `.aws/`, `.netrc`, `*.pem`, `*.key`, `id_rsa*` and
-  `id_ed25519*`, along with `.git/`, `node_modules/` and `.agenticreplay/`. That is a fixed list, not a rule
-  that generalises: `id_ecdsa` is not on it. A shape we miss is a bug worth filing — there is an
-  issue template for exactly that.
-- Trace files and blobs are written mode `0600`, run directories `0700` — and on Windows,
-  where those are not something the filesystem has, the equivalent ACL: `.agenticreplay/runs` grants
-  only its owner, SYSTEM and Administrators, and everything written beneath it inherits that.
-  Said plainly because it did not used to be true: `chmod` on Windows sets the read-only
-  attribute and discards the mode, so the store was left with whatever the workspace handed
-  down — typically readable by every account on the machine. On Windows the ACL is applied
-  whether or not agenticreplay created the store that run, since an inherited one is not a choice
-  anybody made. What it cannot do is rewrite runs already on disk from before: those keep the
-  ACEs they were written with, and `icacls` on the parent does not re-propagate.
-  The account running agenticreplay, SYSTEM and Administrators are the trusted principals. Before
-  changing a Windows ACL, agenticreplay also checks the actual owner: another account's ownership can
-  otherwise retain the right to restore access even after its ACE is removed. An unreadable or
-  foreign owner, a junction, or an entry replaced during setup causes a refusal. Owner lookup
-  uses the built-in Windows PowerShell .NET API; it needs neither elevation nor `Get-Acl` module
-  loading. If that API is unavailable, private-data setup fails closed.
-- Redaction lives in the writer, so a file agenticreplay does not write itself has not been through it. A
-  capture layer that runs inside the agent's process, or in a child of it, produces exactly that:
-  the bytes are on disk before agenticreplay ever reads them. Where nothing reads such a file after the run,
-  it is kept out of the run directory — the OpenAI Agents tracing layer and the shell shim both
-  write to a temporary directory made private the moment it is created and before anything is
-  written into it, agenticreplay reads each once and appends what it keeps through the redactor like
-  anything else, and the directory is removed when the run ends. "Private" is `mkdtemp`'s 0700 on
-  POSIX and the same owner-only ACL as the store on Windows, where `mkdtemp` alone gives whatever
-  `%TEMP%` hands down — which is not always the profile, and `shell-frames.jsonl` holds argv and
-  cwd verbatim. What the agents
-  layer writes is an allow-list of structural fields — agent and tool names, which agent handed off
-  to which, whether a guardrail tripped — never a tool's input or output.
-- Where something *does* read such a file later, it stays. `mcp-frames.jsonl` holds the recorded
-  JSON-RPC a replay answers from, so it cannot be deleted and must not be rewritten: the frames are
-  keyed on the request, and editing one makes the replay serve a different recorded response
-  instead of failing. It is not redacted. Treat a run directory as sensitive material, not just the
-  trace inside it.
-- The recorder opens no network connection of its own and sends no telemetry. It passes through
-  only what your agent was already sending.
-- The recording proxy binds `127.0.0.1`, and the local viewer binds loopback only — it refuses any
-  other host outright rather than warning about it.
-- Trace content is treated as untrusted input by the viewer and is escaped before rendering.
-
-**What we do not promise:** redaction is best-effort mitigation, not a guarantee. Treat a trace as
-sensitive material.
-
-Keep the workspace and temporary-directory ancestors under trusted control. The Windows checks
-detect replacements during setup; they are path-based checks, not a filesystem sandbox or an
-atomic handle-based defense against an account that can replace ancestors throughout a run.
-
-`agenticreplay scrub` is the second pass, for what the write path missed and for the internal hostname that
-is only sensitive in your organisation. It rewrites `events.jsonl`, `manifest.json` and every text
-blob in place, then refreshes the integrity digest. Two things it cannot do, and says out loud
-rather than papering over:
-
-- An event line whose scrubbed form would no longer parse or validate is **put back unchanged**.
-  Scrub warns per event (`scrub_reverted`) that what it matched is still on disk, and does not
-  count it as removed. A scrubber that under-reports is disappointing; one that hands you a false
-  all-clear is worse than no scrubber.
-- A run directory holds more than the trace, and scrub rewrites only the trace. Everything else in
-  it — `mcp-frames.jsonl`, the rewritten MCP config, anything a later version adds — is **searched
-  and named** rather than rewritten, and finding something there suppresses the all-clear. So
-  "nothing matched" is an answer about the whole directory, not only about the part scrub edits.
-- The shadow filesystem store (`<run>/fs`) **cannot be rewritten**. Its objects are addressed by the
-  hash of their own contents, so editing one changes its id, every tree naming it, and every
-  `fs.snapshot` event naming those trees. Scrub searches the store instead and reports how many
-  objects still hold the material; `--drop-fs` deletes the store outright for anyone who would
-  rather lose the snapshots than keep what is in them.
-
-`agenticreplay export` prints what it is about to write before it writes it.
-
-## TLS interception
-
-Capture is normally base-URL injection: point an environment variable at a local origin server and
-the agent's traffic arrives in plaintext. A harness that reads no such variable is invisible to
-that mechanism — a Codex CLI signed in with a ChatGPT subscription is the concrete case, because it
-talks to its own backend over TLS it established itself.
-
-`agenticreplay record --tls-intercept` closes that gap. It is the most invasive thing this tool does, so
-here is exactly what it does and does not do.
-
-**Off by default, and per run.** There is no global switch and no persistent install. Off is the
-absence of a `CONNECT` listener rather than a branch inside one, so a proxy that was not asked to
-intercept cannot be talked into it. The run says out loud that interception is on, which hosts it
-will decrypt, and where the CA lives, before the agent starts.
-
-**The CA is ephemeral and local.** Generated per run into `<run>/tls/` — key `0600`, directory
-`0700`, or the ACL that means the same on Windows — and deleted when the run ends, including when the run fails, is interrupted, or the agent
-binary does not exist. It expires 24 hours after minting regardless. It is **never** installed into
-a system or browser trust store, and agenticreplay will not offer to.
-
-**The key never reaches a trace.** Not `events.jsonl`, not a blob, not the manifest. `RunCa` does
-not expose it — it is a private field, and the file is the only place it exists. A test copies the
-real key material out while a run is live and then greps the entire run directory for it.
-
-**The child trusts it, and nothing else does.** `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`,
-`REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `AWS_CA_BUNDLE` and `DENO_CERT` are set on that process
-alone. Note that `SSL_CERT_FILE` *replaces* a trust store rather than adding to it, so the bundle
-those variables point at is the run CA **plus** the public roots — otherwise every host agenticreplay
-deliberately does not intercept would stop working.
-
-**Only the allowlist is decrypted.** The default is model API hosts and nothing else.
-`auth.openai.com` and other sign-in origins are deliberately excluded: that flow carries the
-credential itself, and decrypting it would capture the thing we are trying not to record.
-Everything else is tunnelled opaquely — agenticreplay records the host, port, byte counts and duration, and
-nothing of the contents. `--tls-hosts` overrides the list. A bare `*` is refused, because it is a
-request to decrypt everything.
-
-**Origin verification is never disabled.** The re-encrypt leg to the real origin verifies its
-certificate, and an origin that cannot be verified is refused rather than downgraded.
-`AGENTICREPLAY_TLS_UPSTREAM_CA` *adds* roots, for a machine already behind a TLS-inspecting middlebox.
-Nothing removes the check.
-
-**Auth is handled exactly as on the base-URL path.** Headers are forwarded upstream so the agent
-can authenticate, and dropped before the writer. `set-cookie` is dropped from recorded response
-headers.
-
-Two things it will not do, both failing loudly rather than silently: HTTP/2 (ALPN is pinned to
-`http/1.1`, and a client offering only h2 fails the handshake with a named warning) and WebSocket
-upgrades inside an intercepted session (refused with a 501 that names the reason — take the host
-off the allowlist and the whole connection tunnels untouched).
-
-The general advice stands regardless of whether we ever build it: if a tool asks you to install its
-CA system-wide, refusing is reasonable — including if some future version of this one asks.

package/capture/CAPTURE-RUNBOOK.md

@@ -1,271 +0,0 @@
-# Capturing an agent's system prompt
-
-How to read the system prompt a coding agent assembled on your own machine, using AgenticReplay's
-proxy as the vantage point. Nothing here talks to a service about anything but the agent's own
-model call: the prompt is captured from the request the harness sent, on the way out.
-
-`node capture/capture.mjs <claude|codex|opencode>` does all of this in one command. This document
-is the manual procedure behind it, for porting the approach to a harness the script does not cover
-or to a platform it does not run on.
-
-Measured against Claude Code 2.1.258, Codex 0.149.0 and OpenCode 1.18.26 on Windows 10, node
-22.23.2, AgenticReplay 0.1.2.
-
-## What you get
-
-| piece | where it lives |
-|---|---|
-| the prompt on its own | `prompt/<HARNESS>/<model>-system-prompt.md` |
-| the same text with block boundaries | `capture/<name>/<name>-prompt-annotated.txt` |
-| the whole request body | `capture/<name>/<name>-request.json` |
-| tool definitions | `capture/<name>/<name>-tools.json` |
-| run id, sizes, token counts | `capture/<name>/<name>-meta.json` |
-| the raw agenticreplay run | `capture/<name>/trace/` |
-
-Everything but `trace/` is scrubbed.
-
-## Prerequisites
-
-| | |
-|---|---|
-| node | 20.19+ or 22.12+ |
-| agenticreplay | `npm i -g agenticreplay` |
-| the agent | installed, signed in, and able to reach the model it names |
-| terminal | PowerShell is needed for step 4 on Windows |
-
-On Linux and macOS steps 3 to 5 collapse into a single `agenticreplay record`: a pipe there still sits
-behind a pty, so the harness assembles its interactive prompt anyway. Windows is the case that
-needs the extra work, for the reason in the pitfalls below.
-
-## Steps
-
-### 1. Find out where agenticreplay will forward
-
-If `agenticreplay setup` has configured a gateway, `resolveUpstream()` (`packages/cli/src/config.ts:132`)
-sends every Anthropic call there, and a third-party router usually does not serve the model.
-
-```console
-$ cat ~/.config/agenticreplay/config.json
-{ "gateway": { "url": "http://<your-gateway>:8317", "api_key": "<key>" },
-  "models": [ "gpt-5.6-sol" ] }
-```
-
-If that file names a gateway, add `--upstream-anthropic https://api.anthropic.com` to every agenticreplay
-command below. Codex is the opposite case: its own `config.toml` already points at that gateway, so
-leaving the upstream alone is what makes its model resolve.
-
-### 2. Capture the non-interactive prompt first
-
-Optional, but cheap, and it confirms the proxy, the credential and the model id in one go.
-
-```console
-$ agenticreplay record claude --no-fs --no-shell \
-    --upstream-anthropic https://api.anthropic.com \
-    -- -p "reply with just: ok" --model claude-fable-5-1
-info recording run=run_8e6d567d4ca4 adapter=claude-code proxy=:58642
-ok
-info recorded run=run_8e6d567d4ca4 events=7 blobs=3 exit=0
-```
-
-`exit=0` means the path works. Note this is the `-p` prompt, tagged `cc_entrypoint=sdk-cli`, not the
-interactive one.
-
-### 3. Hold a proxy open
-
-`agenticreplay attach` does not launch the agent. It holds the proxy and prints the variable to export.
-`--port` is not in `--help` but it exists, and a fixed port saves parsing the output.
-
-```console
-$ agenticreplay attach --for claude --port 46001 \
-    --upstream-anthropic https://api.anthropic.com
-info attached run=run_bc749535e248 proxy=http://127.0.0.1:46001 for=claude-code
-
-  # in the sandbox, before starting your agent:
-  export ANTHROPIC_BASE_URL='http://127.0.0.1:46001'
-  # your agent's own credential is unchanged - agenticreplay forwards it upstream
-
-  Recording. Press ctrl-C when the agent is done.
-```
-
-This command stays up. Use a second window for the next step.
-
-### 4. Start the agent in a console of its own
-
-`Start-Process` without `-NoNewWindow` is the whole trick: Windows hands a console application a
-real console, so `process.stdin.isTTY` is true and the harness assembles its interactive prompt.
-
-```powershell
-$claude = "$env:APPDATA\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe"
-foreach ($n in @('CLAUDECODE','CLAUDE_CODE_ENTRYPOINT','CLAUDE_CODE_CHILD_SESSION',
-  'CLAUDE_CODE_SESSION_ID','CLAUDE_CODE_MESSAGING_SOCKET','CLAUDE_CODE_MESSAGING_TOKEN',
-  'CLAUDE_PID','CLAUDE_EFFORT','CLAUDE_CODE_EXECPATH','AI_AGENT')) {
-  if (Test-Path "Env:\$n") { Remove-Item "Env:\$n" }
-}
-$env:ANTHROPIC_BASE_URL = 'http://127.0.0.1:46001'
-Start-Process -FilePath $claude -WindowStyle Minimized -PassThru `
-  -WorkingDirectory 'D:\your\repo' `
-  -ArgumentList @('--model','claude-fable-5-1','"say only the word ok"')
-```
-
-Wrap the prompt in embedded quotes so it arrives as a **single** argument. Choose a working
-directory the agent already trusts, or it stops on the trust dialog with nobody to answer it.
-
-### 5. Wait for the request that carries tools
-
-The first `model.request` is the title generator, `tools=0`, and it is not the one you want. Wait
-for the one where `tools` is greater than zero.
-
-```console
-$ until grep -q '"tools":3' .agenticreplay/runs/*/events.jsonl; do sleep 2; done
-seq 4  model.request   claude-fable-5-1  tools=35  blob=175255
-seq 5  model.response  200  end_turn  cache_read=59811
-```
-
-### 6. Clean up
-
-Both processes have to stop. Killing the shell that started `agenticreplay attach` does not reach the node
-process behind it, and the port stays bound.
-
-```powershell
-Stop-Process -Id 18544 -Force
-Get-NetTCPConnection -LocalPort 46001 -State Listen |
-  ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }
-```
-
-### 7. Read the request body out of the trace
-
-Events hold the blob's sha256, sharded by its first two characters. Take the **first** request with
-tools, not the largest: later turns load deferred tools, so the tool count climbs from 35 to 37 and
-the biggest request describes a state the first turn was never in.
-
-```js
-const evs = readFileSync(dir + '/events.jsonl', 'utf8')
-  .split('\n').filter(Boolean).map(JSON.parse);
-const r = evs.filter(e => e.type === 'model.request' && e.attrs.tools > 0)[0];
-const sha = r.payload.$blob.replace('sha256:', '');
-let body = JSON.parse(readFileSync(`${dir}/blobs/${sha.slice(0,2)}/${sha}`, 'utf8'));
-if (typeof body === 'string') body = JSON.parse(body);   // blobs are double-encoded
-```
-
-### 8. Assemble the prompt and scrub it
-
-Where the prompt lives depends on the dialect.
-
-**Claude Code**, Anthropic messages: the `system` array, then the injected `role: "system"` message
-that carries agent types, the skill list and a paragraph about the permission mode.
-
-```js
-const prompt = body.system.map(s => s.text).join('\n\n')
-  + '\n\n' + body.messages.find(m => m.role === 'system').content[0].text;
-```
-
-```
-  [0]     70 chars  cache=none    billing header
-  [1]     57 chars  cache=1h      identity
-  [2]    907 chars  cache=none    reporting outcomes
-  [3]  13919 chars  cache=1h      the body
-  role:system  11478 chars
-```
-
-**Codex**, OpenAI responses: no `instructions` field and no top-level `tools`. The prompt arrives as
-`developer`-role messages inside `input`, and the tools hang off a custom `additional_tools` item as
-a namespace tree, which is why the recorded event reads `tools: 0`.
-
-**OpenCode**, OpenAI chat completions: a single `system` message, tools in the standard `tools`
-array.
-
-Then replace the machine-specific values with placeholders. Derive them from the machine rather
-than hard-coding them: home directory, username, git name and email, the gateway host from
-`~/.config/agenticreplay/config.json`, the Claude Code project slug, the OS build, plus generic rules for
-emails, uuids and hex runs of 32 or more. Order matters, because the memory directory sits inside
-the home directory. Re-scan afterwards and refuse to write the file if anything survives.
-
-## How much the mode changes
-
-| | print (`sdk-cli`) | interactive (`cli`) |
-|---|---|---|
-| `system[]` | 13,641 chars | 14,953 chars |
-| `role:system` | 7,585 chars | 11,529 chars |
-| tools | 29 | 35 |
-| request | 104,492 bytes | 168,303 bytes |
-| tokens | 37,831 | 59,811 |
-
-Interactive adds the `! <command>` hint, the whole Scratchpad Directory section, a `gitStatus` block
-when the working directory is a repository, and `Artifact`, `AskUserQuestion`, `EnterPlanMode` and
-`ExitPlanMode`.
-
-The identity line changes too:
-
-- print — `You are a Claude agent, built on Anthropic's Claude Agent SDK.`
-- interactive — `You are Claude Code, Anthropic's official CLI for Claude.`
-
-## Pitfalls
-
-**A gateway rewrites the upstream silently.** `400 unknown provider for model claude-fable-5-1`
-comes from the gateway you configured, not from Anthropic, and has nothing to do with whether the
-agent is installed. The agent works on its own because it talks to the official endpoint directly.
-
-**Credentials are forwarded upstream.** `SECRET_REQUEST_HEADERS` in
-`packages/proxy/src/server.ts` forwards auth headers, though it never writes them to a trace. With
-the upstream pointed at a third-party gateway that sends an OAuth token there along with the whole
-prompt, and over plain HTTP if that is what the gateway speaks.
-
-**`agenticreplay record claude` cannot reach the interactive prompt.** It launches through a pipe, `isTTY` is
-false, and the harness takes the non-interactive path. The adapter also hard-codes `command:
-'claude'`, so there is no room to slip a pty shim in front of it.
-
-**winpty will not start without a console.** It asserts `cols > 0 && rows > 0` at
-`winpty.cc:924`, because it cannot learn the window size from a pipe and the command line has no
-`--cols`. Letting `Start-Process` allocate a console is less work than building a pty. Node's own
-`detached` is no help either: on Windows it means `DETACHED_PROCESS`, so no console at all.
-
-**PowerShell splits an argument containing spaces.** Passing `'reply with just: ok'` in
-`-ArgumentList` delivers only `reply`, and the agent then goes looking through git and pull requests
-for context. The system prompt is unaffected, but the tokens are wasted.
-
-**A nested session inherits `CLAUDE_*`.** Starting the agent from inside another Claude Code session
-passes down `CLAUDECODE=1` and `CLAUDE_CODE_CHILD_SESSION=1`, which changes the prompt. That is what
-the `Remove-Item` loop in step 4 is for.
-
-**The working directory is part of the prompt.** Capturing in a temporary non-repository loses the
-whole `gitStatus` block: 4,271 characters on a measured Opus 5 run. Capture where you actually work.
-
-**A failed turn still produces a prompt.** A wrong `--model` and a transient `overloaded_error` fail
-the same way, and in both cases the request was already recorded. Check the response before filing
-the capture, or a typo creates a folder for a model that does not exist.
-
-**OpenCode keeps its origin in a config file, so redirect it at the socket instead.**
-`OPENAI_BASE_URL` alone leaves the run talking straight past the proxy. A project-level
-`opencode.json` carrying the proxy origin does redirect it when the command is typed in a shell,
-and did not when the same file and command were launched from a script. `--tls-intercept
---tls-hosts '+opencode.ai,+*.opencode.ai'` sidesteps the question: agenticreplay terminates the TLS OpenCode
-established itself and the config is left alone. Expect a few `tls.handshake_failed` warnings for
-connections that are not the model call; the model call still records.
-
-## Proving a capture is genuine
-
-Run it twice and diff `system[3]`. Everything but the values below should be byte for byte
-identical.
-
-| difference | why |
-|---|---|
-| scratchpad path | one uuid per session |
-| memory directory | derived from the working directory |
-| `gitStatus` block | tracks the repository state |
-| `cc_version` suffix | a hash over the assembled prompt, so the above change it |
-
-There is a second, sharper check. Compare a run the gateway rejected with a run that returned 200:
-`system[3]` differs only in the working directory and the memory hash, while the tool definitions
-and the `role:system` turn are identical. **What the upstream returns does not affect the request
-already recorded** — the prompt is assembled locally and written to disk before it is forwarded.
-
-## Reference runs
-
-| run | harness | mode | result |
-|---|---|---|---|
-| `run_bc749535e248` | claude | interactive | 200 |
-| `run_8e6d567d4ca4` | claude | print | 200 |
-| `run_7a02fa0c8266` | claude | print | rejected by the gateway; request body still complete |
-| `run_31102b8bde19` | codex | exec | 200 |
-| `run_6e92b193d46d` | opencode | run | 200, redirected by a project config |
-| `run_578faf1d269e` | opencode | run | 200, `--tls-intercept` on a free model |