tracehub 0.5.3 → 0.5.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -78,7 +78,7 @@ Everything is computed on the developer's machine, redacted there, checked again
78
78
  Set it up once with `setup` (the other commands are under [Commands](#commands)). Run it in your terminal:
79
79
 
80
80
  ```sh
81
- npx --yes tracehub@0.5.3 setup
81
+ npx --yes tracehub@0.5.5 setup
82
82
  ```
83
83
 
84
84
  Setup is a form of three steps. Each step saves what you chose before the next one starts; cancelling (Ctrl-C) keeps the steps already done.
@@ -89,11 +89,11 @@ Setup is a form of three steps. Each step saves what you chose before the next o
89
89
 
90
90
  It ends with a summary of the account, the allowed rules and the hooks, and what is left to do. Setup needs an interactive terminal; without one it exits 1.
91
91
 
92
- To skip npx on every commit, install it globally instead: `npm install -g tracehub@0.5.3`, then `tracehub setup`.
92
+ To skip npx on every commit, install it globally instead: `npm install -g tracehub@0.5.5`, then `tracehub setup`.
93
93
 
94
94
  ### Git hooks
95
95
 
96
- Setup installs global Git hooks: it points the global `core.hooksPath` at `~/.config/tracehub/hooks`, which holds a dispatcher for every standard Git hook. Two of them run the CLI: the same Node and `cli.js` that ran setup, by absolute path, so a global install or `npm link` needs no network on commit. A setup run through npx installs hooks that run `npx --yes --prefer-offline tracehub@<version> hook …`, pinned to that published version. Every dispatcher then runs the hook you had before: from your previous global or inherited system hooks directory, or else the repository's own `.git/hooks`. Hook files, arguments, pre-push input, failure status and warnings are preserved.
96
+ Setup installs global Git hooks: it points the global `core.hooksPath` at `~/.config/tracehub/hooks`, which holds a dispatcher for every standard Git hook. Two of them run the CLI: the same Node and `cli.js` that ran setup, by absolute path, so a global install or `npm link` needs no network on commit. A setup run through npx installs hooks that run `npx --yes --prefer-offline --registry=https://registry.npmjs.org tracehub@<version> hook …`, pinned to that published version. They run npx from your home directory, so a repository's own `.npmrc` or `node_modules` never decides what runs. Every dispatcher then runs the hook you had before: from your previous global or inherited system hooks directory, or else the repository's own `.git/hooks`. Hook files, arguments, pre-push input, failure status and warnings are preserved.
97
97
 
98
98
  | hook | does |
99
99
  | --- | --- |
@@ -110,7 +110,7 @@ Setup installs global Git hooks: it points the global `core.hooksPath` at `~/.co
110
110
  ### Uninstall
111
111
 
112
112
  ```sh
113
- npx --yes tracehub@0.5.3 uninstall
113
+ npx --yes tracehub@0.5.5 uninstall
114
114
  ```
115
115
 
116
116
  Lists what it removes and asks first (default no); with nothing set up it says so and asks nothing. Then it removes the global Git hooks and restores your previous global `core.hooksPath` setting, deletes the permission rules (`consent.json`) and signs you out (`auth.json`). It asks before deleting the deny list and the current repository's `.git/tracehub` (its markers, including ones not uploaded yet). Other repositories keep their `.git/tracehub`; delete it by hand if you want. Before signing out it asks TraceHub to forget this machine's rules (see [Consent registry](#consent-registry)); when TraceHub can't be reached it says that TraceHub still lists them, and goes on. If the global hooks setting was changed by another tool since setup, uninstall leaves the hooks alone, still removes the rest, and exits 1.
@@ -120,8 +120,8 @@ Lists what it removes and asks first (default no); with nothing set up it says s
120
120
  Uploads are restricted to repositories verified as owned by the GitHub organization **`assistant-ui`** (CLI 0.4.0 and later).
121
121
 
122
122
  - The repository is `origin`'s: all of its effective fetch and push URLs must name the same repository on `github.com`, with the exact owner `assistant-ui` (case insensitive). HTTPS, GitHub SSH URLs and `git@github.com:…` are accepted. A missing `origin`, or one with unknown or conflicting URLs, blocks uploads. A personal fork as `origin` with an organization upstream is blocked. Other remotes, such as contributors' forks kept for reviewing their pull requests, play no part.
123
- - Git's URL rewrites are resolved. A push uploads only when it goes to `origin`'s repository: the destination URL Git passes to the hook, and the pushed remote's own URLs, must name it. A push to a fork remote uploads nothing and the traces stay pending. The hooks forward `"$@"` and Git's stdin ref updates; missing arguments or ref input block upload, even if the configured origin is eligible. The commit hook skips trace markers for ineligible remotes; it makes no network request. When `TRACEHUB_ID` names a session but `origin` is not eligible, the commit hook says so in one line instead of skipping silently.
124
- - Before sending any trace or marker, the upload run asks GitHub for the canonical repository owner using the signed-in user's token. The returned owner must be the `assistant-ui` organization and the canonical repository name must match the remotes. Redirects, transfers, renames, missing fields, access failures and network failures block uploads. Update remotes after a rename. An organization-owned fork remains eligible; a fork owned elsewhere does not.
123
+ - Git's URL rewrites are resolved. A push uploads when it goes to `origin`'s repository or to a fork of it, such as a contributor's pull request branch a maintainer pushes to: the destination URL Git passes to the hook, and the pushed remote's own URLs, must name one repository on `github.com`. A push anywhere else uploads nothing and the traces stay pending. The hooks forward `"$@"` and Git's stdin ref updates; missing arguments or ref input block upload, even if the configured origin is eligible. The commit hook skips trace markers for ineligible remotes; it makes no network request. When `TRACEHUB_ID` names a session but `origin` is not eligible, the commit hook says so in one line instead of skipping silently.
124
+ - Before sending any trace or marker, the upload run asks GitHub for the canonical repository owner using the signed-in user's token. The returned owner must be the `assistant-ui` organization and the canonical repository name must match the remotes. Redirects, transfers, renames, missing fields, access failures and network failures block uploads. Update remotes after a rename. An organization-owned fork remains eligible as `origin`; a fork owned elsewhere does not. A push to a fork also asks GitHub for the pushed repository, which must be a fork whose parent is `origin`'s repository; anything else blocks the upload.
125
125
  - This applies to every upload of the pre-push hook, including previously pending markers. Upload methods also verify ownership themselves. A refused hook still exits 0, preserving pending work for a later push.
126
126
  - A permission rule and a sign-in remain required. This check does not grant access, change trace visibility, or send traces to GitHub; it runs fresh at upload time.
127
127
 
@@ -166,11 +166,11 @@ TraceHub keeps a copy of your rules (`_consent/users/<your id>`).
166
166
 
167
167
  ## How it works
168
168
 
169
- 1. **Commit.** `prepare-commit-msg` finds the sessions of the commit (see Discovery). If the message has no `Assisted-by` trailer yet, it adds one with a new 16-hex trace id. For each session it appends a marker to `.git/tracehub/markers.jsonl` (in the repository's common git directory, so a linked worktree's markers outlive the worktree): `{traceId, session, line, ts, context?, uploaded}`, where `line` is the number of complete lines the session file had and `context` the references of `TRACEHUB_CONTEXT`. Merge and squash commits are skipped.
169
+ 1. **Commit.** `prepare-commit-msg` finds the sessions of the commit (see Discovery). If the message has no `Assisted-by` trailer yet, it uses a new 16-hex trace id and adds the trailer once at least one session's marker is recorded; a commit whose sessions are all missing from this machine gets no trailer. For each session found it appends a marker to `.git/tracehub/markers.jsonl` (in the repository's common git directory, so a linked worktree's markers outlive the worktree): `{traceId, session, line, ts, context?, file, committer?, uploaded}`, where `line` is the number of complete lines the session file had, `context` the references of `TRACEHUB_CONTEXT`, `file` the session file it was found in, and `committer` that the session made the commit with a call of its own (see Discovery). The marker never leaves the machine. Merge and squash commits are skipped.
170
170
  2. **Amend, rebase, squash.** The message keeps its trailer, so the commit keeps its trace id. A new marker for the same trace id and session replaces the old one.
171
- 3. **Push.** `pre-push` reads Git's ref updates and uploads only the traces of commits being pushed. New branches exclude commits already known on that remote. Deletions upload nothing; an unavailable remote base leaves traces pending with a recovery warning. For each pending marker the CLI builds the trace (below), fetches its context conversations from their providers and `PUT`s it; each success is recorded before the next. A later push also retries the pending traces of earlier commits in its history. When the 15 s run out, the push says so and a detached `tracehub hook upload` goes on with the same traces for up to 10 minutes, writing to `.git/tracehub/upload.log`.
171
+ 3. **Push.** `pre-push` reads Git's ref updates and uploads only the traces of commits being pushed. New branches exclude commits already known on that remote. Deletions upload nothing; an unavailable remote base leaves traces pending with a recovery warning. For each pending marker the CLI builds the trace (below) from the marker's `file`, or the session's file wherever the push's environment keeps it when that one is gone, so a push from a plain terminal uploads what an agent with its own `CLAUDE_CONFIG_DIR` committed; fetches its context conversations from their providers and `PUT`s it; each success is recorded before the next. A later push also retries the pending traces of earlier commits in its history. When the 15 s run out, the push says so and a detached `tracehub hook upload` goes on with the same traces for up to 10 minutes, writing to `.git/tracehub/upload.log`.
172
172
  4. **Pull request.** The GitHub App receives the `pull_request` event, reads the trace ids from the commit messages, and writes a link at the bottom of the description, between `<!-- tracehub:start -->` and `<!-- tracehub:end -->`: an "Agent traces" badge, next to Rupic's "Track in Rupic" badge when there is one. A pull request with attached context gets the link too.
173
- 5. **Reading.** The badge links to `/pr/<owner>/<repo>/<number>`: the intent and effort at a glance (first prompt, wall-clock time, prompts, commits, agents), then one timeline of the context conversations and the sessions of its commits, each message clamped to three lines, subagent runs folded to one line. A trace is at `/t/<owner>/<repo>/<trace id>`, a commit's traces at `/c/<owner>/<repo>/<sha>`. Add `.json` to any of them for the data (sign-in cookie or `Authorization: Bearer <GitHub token>`). The pages are rendered when their data changes and served from the cache.
173
+ 5. **Reading.** The badge links to `/pr/<owner>/<repo>/<number>`: the intent and effort at a glance (first prompt, wall-clock time, prompts, commits, agents), then one timeline of the context conversations and the sessions of its commits, each message clamped to three lines, subagent runs folded to one line. A trace is at `/t/<owner>/<repo>/<trace id>`, a commit's traces at `/c/<owner>/<repo>/<sha>`. Add `.json` to any of them for the data (sign-in cookie or `Authorization: Bearer <token>` with the token `tracehub setup` keeps). The pages are rendered when their data changes and served from the cache.
174
174
  6. **Without a pull request.** A push prints a link per commit it marked, `/t/<owner>/<repo>/<trace id>`.
175
175
 
176
176
  ### What a trace holds
@@ -193,22 +193,26 @@ The upload replaces the trace of that commit and session, and the API rebuilds t
193
193
  The sessions of a commit, by precedence:
194
194
 
195
195
  1. `TRACEHUB_ID=<claude|codex|opencode>:<id>` in the environment (comma-separated for several).
196
- 2. Recently active sessions with an open agent tool call executing `git commit`. This preserves several sessions when several commit calls are active.
197
- 3. If no committing session is found, the sessions of the repository written to since the last commit (the last 24 hours in a repository without a commit). This fallback preserves sessions for commits made manually.
196
+ 2. The session the agent's own environment names. Claude Code gives every command it runs `CLAUDE_CODE_SESSION_ID`, Codex `CODEX_THREAD_ID`, so the hook of a commit an agent makes inherits the id of the session making it. Each one whose file is on this machine is attached:
197
+ - when it has the open `git commit` call, as the session that made the commit, wherever it ran (an app that runs its threads in a project's directory and commits with `cd <worktree> && git commit`);
198
+ - else, for Claude Code, when one of its subagents has the open call (a subagent's commands carry its parent's id): the parent when it ran in the repository, with the subagent as a run of its trace, else the subagent alone (as below). Of several subagents with an open call, those whose call names this checkout;
199
+ - else only when it ran in the repository, like discovery. A session elsewhere that commits nothing (a terminal that inherited the id) leaves the commit to the next rule.
200
+ 3. Recently active sessions with an open agent tool call executing `git commit`. This preserves several sessions when several commit calls are active.
201
+ 4. If no committing session is found, the sessions of the repository written to since the last commit (the last 24 hours in a repository without a commit). This fallback preserves sessions for commits made manually.
198
202
 
199
- A session belongs to the repository only when its working directory is inside the repository's checkout: discovery never attaches a session that ran elsewhere, for example a coordinator agent in `~/.nomos/coordinator` whose subagents commit in a worktree. A session named by `TRACEHUB_ID` that ran outside the repository (or one of its worktrees) shares nothing of its own: its trace holds only the subagent runs that changed files of the repository, without the parent's messages or title, and when no subagent changed any, nothing is uploaded and the marker is settled.
203
+ A session belongs to the repository only when its working directory is inside the repository's checkout: discovery never attaches a session that ran elsewhere, for example a coordinator agent in `~/.nomos/coordinator` whose subagents commit in a worktree. A session that ran outside the repository (or one of its worktrees), even one named by `TRACEHUB_ID`, shares nothing of its own: its trace holds only the subagent runs that changed files of the repository, without the parent's messages or title, and when no subagent changed any, nothing is uploaded and the marker is settled. The one exception is the session rule 2 found making the commit: it shares its own turns as a session in the repository would.
200
204
 
201
- Such a coordinator's subagents are found on their own. Claude Code files a subagent's transcript under its parent's project, and its lines carry the parent's `cwd`, so discovery also reads the subagent transcripts of the last 24 hours (and since the last commit) under `~/.claude/projects/*/*/subagents/` whose parent ran outside the repository, and tells by what each one did whether it worked in the checkout being committed (the worktree, when the commit is in one):
205
+ Such a coordinator's subagents are found on their own. Claude Code files a subagent's transcript under its parent's project, and its lines carry the parent's `cwd`, so discovery also reads the subagent transcripts of the last 24 hours (and since the last commit) under `~/.claude/projects/*/*/subagents/` (or `$CLAUDE_CONFIG_DIR/projects/*/*/subagents/`) whose parent ran outside the repository, and tells by what each one did whether it worked in the checkout being committed (the worktree, when the commit is in one):
202
206
 
203
207
  - for rule 2, an open `git commit` call whose command names the checkout (`cd <checkout> && git commit`, `git -C <checkout> commit`, `~/…` spellings included), or a plain `git commit` from a subagent whose own `cwd` is inside it (a worktree-isolated agent);
204
208
  - for rule 3, an edit of a file in the checkout since the last commit, or a `cwd` inside it.
205
209
 
206
210
  Such a subagent is attached as `claude:agent-<id>` and uploaded alone: the prompt its parent gave it as its first message, its text replies, its per-turn changes and its sourcemap, titled with the description from its `agent-<id>.meta.json`, redacted like any trace. Its parent's messages and title, and its sibling subagents that didn't work in the checkout, are never read into it. A subagent of a session inside the repository stays a run of that session's trace. Codex sub-threads are sessions of their own with their own `cwd`, so the usual rule finds them when they ran in the repository; an OpenCode task's session shares its parent's `directory` and is not found on its own.
207
211
 
208
- Where the sessions are:
212
+ Where the sessions are, read where the agent of the commit's environment writes them:
209
213
 
210
- - Claude Code: `~/.claude/projects/<encoded cwd>/<session id>.jsonl`. The cwd is encoded by replacing every character outside `[A-Za-z0-9-]` with `-`. The `cwd` of its first line that has one has to be inside the repository. Subagents are in `<session id>/subagents/agent-<id>.jsonl`, with an optional `agent-<id>.meta.json`; one found on its own is `claude:agent-<id>`, and `TRACEHUB_ID` can name it so too.
211
- - Codex: `~/.codex/sessions/YYYY/MM/DD/rollout-<time>-<thread id>.jsonl`. The first line (`session_meta`) has the `cwd`, which has to be inside the repository. A sub-thread names its parent in `parent_thread_id`.
214
+ - Claude Code: `~/.claude/projects/<encoded cwd>/<session id>.jsonl`, or `$CLAUDE_CONFIG_DIR/projects/…` when `CLAUDE_CONFIG_DIR` is set. Claude Code then writes nothing to `~/.claude`, so only that directory is read: an app that runs one Claude Code per account (T3 Code gives each provider instance its own) is read by the commits its agents make, and a commit from a plain terminal reads `~/.claude`. The cwd is encoded by replacing every character outside `[A-Za-z0-9-]` with `-`. The `cwd` of its first line that has one has to be inside the repository. Subagents are in `<session id>/subagents/agent-<id>.jsonl`, with an optional `agent-<id>.meta.json`; one found on its own is `claude:agent-<id>`, and `TRACEHUB_ID` can name it so too.
215
+ - Codex: `~/.codex/sessions/YYYY/MM/DD/rollout-<time>-<thread id>.jsonl`, or under `$CODEX_HOME/sessions` when `CODEX_HOME` is set. The first line (`session_meta`) has the `cwd`, which has to be inside the repository. A sub-thread names its parent in `parent_thread_id`.
212
216
  - OpenCode: the database `~/.local/share/opencode/opencode.db`. A session has the `directory` it was started in, which has to be inside the repository. The session a task started names its parent in `parent_id`. The CLI reads the database with `node:sqlite`, so it needs Node 22.13 or newer.
213
217
 
214
218
  ## Commands
@@ -222,9 +226,48 @@ Where the sessions are:
222
226
  | `providers remove <name>` | removes a provider |
223
227
  | `context add --pr <n> (<provider>:<id> … \| --from <file\|->) [--dry-run]` | attaches context conversations to a pull request |
224
228
  | `context remove --pr <n> <provider>:<id>…` | detaches context conversations from a pull request |
229
+ | `backfill --pr <n> [--repo <owner/repo>] [--session <agent:id>,…] [--dry-run]` | finds and uploads the agent sessions behind a pull request's untraced commits |
230
+ | `backfill <commit>… [--session <agent:id>,…] [--dry-run]` | the same for commits named |
225
231
 
226
232
  The hooks run `tracehub hook prepare-commit-msg` and `tracehub hook pre-push`, an internal entry point that `--help` leaves out. `docs/pages/cli-reference.mdx` renders the reference from `src/cli/usage.ts`, as `--help` does.
227
233
 
234
+ ## Backfill
235
+
236
+ Commits made before `tracehub setup`, or whose trace never reached TraceHub (a lost push), have no trace, and their pull request's check fails. `tracehub backfill` finds the agent sessions behind them on this machine and uploads them, so the check passes:
237
+
238
+ ```sh
239
+ npx --yes tracehub backfill --pr 386 --dry-run # print the evidence, upload nothing
240
+ npx --yes tracehub backfill --pr 386 # upload the sure matches
241
+ ```
242
+
243
+ Run it in a clone of the pull request's repository, on the machine where the agent ran; `--repo <owner/repo>` only confirms the clone. It needs a sign-in and a permission rule, as uploads do, and only works on pull requests you opened. Commits whose trace TraceHub already has, and merges, are skipped; a commit whose message names a trace TraceHub never got is backfilled under that trace id.
244
+
245
+ For each commit it scores the Claude Code sessions and subagents (`~/.claude/projects`), Codex rollouts (`~/.codex/sessions`) and OpenCode sessions that were written to after the commit's time and name one of its short shas or paths:
246
+
247
+ | evidence | points |
248
+ | --- | --- |
249
+ | `git commit` output (`[branch abc1234] …`) naming the commit | 6, ties |
250
+ | a `git commit` call carrying the commit's subject | 3 |
251
+ | its cwd, an edited file, or a `cd <dir> && git commit` in a checkout of the repository (this clone's worktrees, or any directory whose origin is the repository) | 2, ties |
252
+ | the pull request's URL in it (`gh pr create` prints it) | 3, ties |
253
+ | else the repository's GitHub URL in it (a push) | 1, ties |
254
+ | on the pull request's branch (Claude Code's `gitBranch`) | 2 |
255
+ | edits of the commit's files, up to 3 | 1 each |
256
+ | of the commit's added lines, the share its edits wrote: ≥50%, ≥20%, any | 3, 2, 1 |
257
+
258
+ Only what the session did before the commit counts (author time for a rebased or amended commit). A session with no tie to the repository is never uploaded. Confidence is **high** at 7 points with a tie, **medium** at 4. It prints, per commit, the likely sessions with their evidence, and uploads the high ones. `--session <agent>:<id>[,…]` considers only those sessions and uploads them at medium too: for an agent that has checked the evidence itself. A subagent whose parent session is uploaded is a run of that session's trace instead.
259
+
260
+ An upload is a normal one: the session cut where the commit was made, redacted on this machine (the detectors, the deny list, the home directory), checked again by the API, with the context its briefs name. The trace is then linked to the commit (`PUT /repos/:owner/:repo/commits/:sha/traces/:trace`), and the pull request's check is run again. Running it again reuses each commit's trace id, so it replaces rather than adds.
261
+
262
+ ### For coding agents
263
+
264
+ Asked to "upload traces for these PRs":
265
+
266
+ 1. In a clone of the repository, run `npx --yes tracehub backfill --pr <n> --dry-run` for each pull request.
267
+ 2. Read the evidence. High matches upload as they are. For a commit with only medium or low matches, look at the sessions yourself (their cwd, their `git commit` calls, the files they edited) and, when one clearly made the commit, name it with `--session`.
268
+ 3. Run it without `--dry-run`, then check the pull request's **TraceHub traces** check.
269
+ 4. Never name a session from another repository or unrelated work, and never backfill someone else's pull request.
270
+
228
271
  ## Context conversations
229
272
 
230
273
  A context conversation is what asked for the work. TraceHub gets it from a provider, by reference: `<provider>:<id>`, for example `nomos:t_16da1c327635`.
@@ -331,6 +374,7 @@ Literals in `~/.config/tracehub/deny.txt`, one per line, are always redacted. Ed
331
374
  | `PUT /repos/:owner/:repo/traces/:trace/sessions/:name` | stores a session's trace at a commit, replacing the one there |
332
375
  | `PUT /repos/:owner/:repo/pulls/:number/context` | attaches context conversations to a pull request (`{context: [...]}`), merged into the uploader's by conversation and message id |
333
376
  | `DELETE /repos/:owner/:repo/pulls/:number/context?ref=<provider>:<id>` | detaches the conversations (`ref` repeated) from every uploader's document; answers `{removed}`, 404 when none was attached |
377
+ | `PUT /repos/:owner/:repo/commits/:sha/traces/:trace` | links an uploaded trace to a commit whose message does not name it (a backfill); only who uploaded one of its sessions may; answers `{sha, traceId, pulls}`, 404 without a session, 503 when the GitHub App is not configured |
334
378
  | `POST /repos/:owner/:repo/pulls/:number/check` | recomputes the pull request's head check; answers `{submitted: true}` (bearer, push access), 503 when the GitHub App is not configured |
335
379
  | `PUT /consent` | registers a machine's permission rules for the signed-in user; `rules: []` forgets the machine |
336
380
  | `GET /login`, `/logout`, `/api/auth/callback` | browser sign-in (through the web app) |
@@ -341,7 +385,7 @@ Bucket keys: `<owner>/<repo>/traces/<trace id>/<session name>` (an uploaded sess
341
385
 
342
386
  A trace or context is shown to who uploaded it and to the repository's maintainers (GitHub write, maintain or admin access); everyone else sees nothing.
343
387
 
344
- The `PUT` routes and the pull request's `/check` route take `Authorization: Bearer <access token of the GitHub user>` with push access to the repository. The web app's pages (`/t`, `/c`, `/pr`, each with a `.json` twin) take the cookie of the browser sign-in or a bearer GitHub token, and send a signed-out browser to `/login`; `tracehub/README.md` has the page list and the JSON schemas.
388
+ The `PUT` routes and the pull request's `/check` route take `Authorization: Bearer <access token of the GitHub user>` with push access to the repository. The web app's pages (`/t`, `/c`, `/pr`, each with a `.json` twin) take the cookie of the browser sign-in or a bearer token GitHub issued to TraceHub's App, and send a signed-out browser to `/login`; `tracehub/README.md` has the page list and the JSON schemas.
345
389
 
346
390
  ### GitHub App (once)
347
391
 
@@ -349,7 +393,7 @@ The App of the deployed Tracehub API exists; the Tracehub API reads its key from
349
393
 
350
394
  For another deployment, create an App in the GitHub organization:
351
395
 
352
- - Permissions: Pull requests: write, Checks: write (the TraceHub traces check), Contents: read, Metadata: read, Merge queues: read. Events: Pull request, Push, Merge group. Webhook `<tracehub>/github/webhook`.
396
+ - Permissions: Pull requests: write, Checks: write (the TraceHub traces check), Contents: read, Metadata: read, Merge queues: read. Events: Pull request, Push, Merge group, Check run, Check suite. Webhook `<tracehub>/github/webhook`.
353
397
  - Callback URL `<tracehub>/api/auth/callback`, for the browser sign-in.
354
398
  - Device flow enabled, for the sign-in of `tracehub setup`.
355
399
  - A client secret, for the browser sign-in.
@@ -366,17 +410,19 @@ printf %s "<webhook secret>" | npx wrangler secret put GITHUB_WEBHOOK_SECRET
366
410
 
367
411
  ### The TraceHub traces check
368
412
 
369
- The App reports a check run named **TraceHub traces** on the head of every pull request of `assistant-ui` repositories, and on commits that have a known trace (an uploaded session marked by a trace id the commit message names).
413
+ The App reports a check run named **TraceHub traces** on the head of every pull request of `assistant-ui` repositories, and on commits that have a known trace (an uploaded session marked by a trace id the commit message names, or linked to the commit by `tracehub backfill`).
370
414
 
371
415
  - First party: the pull request's author is an organization member or collaborator, or has write access. Bots (`[bot]` logins, `type: Bot`) and outside contributors are exempt.
372
- - **Success** when at least one of the pull request's current commits has a known trace. The output lists each trace with a link to its TraceHub page, its agents and its number of sessions; the details link goes to the pull request's TraceHub page.
373
- - **Success** also when no commit has one but the pull request has context attached (`tracehub context add --pr`): at least one conversation with at least one message, from any uploader; a withheld message counts. The output says it passed on the attached context, with the number of conversations and a link to the pull request's TraceHub page, which the details link also opens.
416
+ - **Success** when at least one of the pull request's current commits has a known trace with content: a session that shows at least one prompt or reply with text, in its turns or a subagent's. A session whose messages are all empty or withheld is empty, and a trace of only empty sessions does not count. The output lists each trace with content with a link to its TraceHub page, its agents and its number of sessions with content; the details link goes to the pull request's TraceHub page.
417
+ - **Success** also when no commit has one but the pull request has context fetched from a provider attached (`tracehub context add --pr <n> <provider>:<id>`): at least one conversation with at least one message with text, from any uploader; withheld messages do not count. Conversations pasted from a file (`--from`, ref `manual:…`) stay on the page but never pass the check alone. The output says it passed on the attached context, with the number of conversations and a link to the pull request's TraceHub page, which the details link also opens.
374
418
  - **Skipped** when every pull request headed at the commit is exempt and has neither a trace nor context. GitHub treats this as passing for a required check.
375
- - **Failure** when a first-party pull request has neither. The output links to the public npm package and says how to fix it: run `npx --yes tracehub setup`, then push a new commit made in an agent session (Claude Code, Codex, OpenCode). A pull request without agent work passes once context is attached with `npx --yes tracehub context add --pr <n> …`. No comment is posted.
376
- - Any other commit gets a success when it has a known trace itself: on a push, and when an upload attaches a trace to a commit TraceHub has seen.
419
+ - **Failure** when a first-party pull request has neither. The title says what was found: `No trace found`, `<n> traces found, all empty` (the summary lists them), or `Only pasted context found`. The output links to the public npm package and says how to fix it: run `npx --yes tracehub setup`, then push a new commit made in an agent session (Claude Code, Codex, OpenCode), or, for commits made before that, run `npx --yes tracehub backfill --pr <n>` (see Backfill). A pull request without agent work passes once the conversation that asked for it is attached from its provider with `npx --yes tracehub context add --pr <n> <provider>:<id>`. No comment is posted.
420
+ - Any other commit gets a success when it has a known trace with content itself: on a push, and when an upload attaches a trace to a commit TraceHub has seen.
377
421
  - A trace uploaded later updates the check on the pull request heads and commits the index knows for the trace, so a failure turns into a success.
378
422
  - Attaching context (`PUT …/pulls/<n>/context`) or detaching it (`DELETE`) runs the check on the pull request's head again right away: a failure turns into a success, and detaching the last conversation can turn it back into a failure.
379
423
  - An unchanged check is not written again; a changed one updates the same check run.
424
+ - **Re-run** on GitHub (`check_run` or `check_suite` with action `rerequested`) lists the pull request's commits again and writes a new check run on the head, changed or not.
425
+ - R2 calls it turns away for a moment (10058 too many reads or writes of one object, 10001, 10043) are tried again a few times with a short backoff, so a busy object does not drop the job that updates the check.
380
426
  - On `merge_group` with action `checks_requested`, the App refreshes the pull request named by the queue ref and mirrors its stored head check onto the merge-group commit, including its conclusion, title, summary and details link. Queue branch pushes are ignored. A missing stored output is logged and no queue check is written.
381
427
  - `POST /repos/:owner/:repo/pulls/:number/check` recomputes the head check for a pull request opened before the App handled it. Push access is required.
382
428
 
@@ -388,7 +434,7 @@ Do not try it with the session you are working in: what is uploaded stays in the
388
434
 
389
435
  ```sh
390
436
  gh repo create assistant-ui/tracehub-playground --private --clone && cd tracehub-playground
391
- npx --yes tracehub@0.5.3 setup # allow this repository, install the hooks
437
+ npx --yes tracehub@0.5.5 setup # allow this repository, install the hooks
392
438
 
393
439
  # open a fresh agent session in this directory, ask it for something harmless
394
440
  export TRACEHUB_ID=claude:<throwaway session id>
@@ -406,6 +452,8 @@ unset TRACEHUB_ID
406
452
 
407
453
  ## Develop
408
454
 
455
+ Needs Node.js 26.13.0 (pinned in `.node-version`).
456
+
409
457
  Development on `main` is allowed; feature branches and pull requests are optional. Preserve other contributors' changes and validate before pushing. Use a separate checkout when the working tree contains unrelated edits.
410
458
 
411
459
  ```sh
@@ -413,7 +461,7 @@ npm run format:fix && npm run typecheck && npm test
413
461
  cd tracehub && npm test
414
462
  ```
415
463
 
416
- Tests are in `test/` and `tracehub/test/`, fixtures in `fixtures/`. The end-to-end tests run the built CLI against the real Tracehub API over an in-memory bucket (`test/support/fakeTracehub.ts`); nothing in the tests reads a real session.
464
+ Tests are in `test/` and `tracehub/test/`, fixtures in `fixtures/`, and run on Vitest; `npm run test:coverage` also checks the coverage thresholds in `vitest.config.ts`. The end-to-end tests run the built CLI against the real Tracehub API over an in-memory bucket (`test/support/fakeTracehub.ts`); nothing in the tests reads a real session. The CLI and the fake Tracehub run outside Vitest, so `npm test` compiles them to `dist-test` first. The test setup file clears the agent variables (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, `TRACEHUB_ID`) a suite run by an agent inherits.
417
465
 
418
466
  The CLI is published to npm as [`tracehub`](https://www.npmjs.com/package/tracehub). `npm pack` builds a fresh `dist` (`prepack`) and ships only `dist`, `README.md` and `package.json`. A clone needs `npm run build` after pulling; `npm install` doesn't build.
419
467
 
package/dist/cli/args.js CHANGED
@@ -1,5 +1,5 @@
1
1
  // Flags that take a value: `--pr 12` or `--pr=12`.
2
- const VALUE_FLAGS = new Set(["pr", "from", "timeout"]);
2
+ const VALUE_FLAGS = new Set(["pr", "from", "timeout", "repo", "session"]);
3
3
  export function parseArgs(argv) {
4
4
  const positional = [];
5
5
  const flags = {};
@@ -37,7 +37,7 @@ function run(command, args, text) {
37
37
  // Never under the test runner, which must not touch the user's clipboard.
38
38
  export async function copyToClipboard(text) {
39
39
  if (process.env[ENV_TEST] !== undefined ||
40
- process.env["NODE_TEST_CONTEXT"] !== undefined)
40
+ process.env["VITEST"] !== undefined)
41
41
  return false;
42
42
  for (const [command, args] of candidates())
43
43
  if (await run(command, args, text))
@@ -0,0 +1,320 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { basename, dirname, join } from "node:path";
3
+ import { freshAuth } from "../../client/auth.js";
4
+ import { pullCommits } from "../../client/github.js";
5
+ import { traceUploaded, tracehubUrl, } from "../../client/tracehub.js";
6
+ import { uploadMarkers } from "../../client/upload.js";
7
+ import { sameTarget, targetOfUploadRemotes, UPLOAD_POLICY_ERROR, } from "../../client/uploadPolicy.js";
8
+ import { addedLines, git, remoteUrls, repoRoot, tryGit, } from "../../git/git.js";
9
+ import { appendMarkers, readMarkers, } from "../../git/markers.js";
10
+ import { newTraceId, traceIds } from "../../git/trailers.js";
11
+ import { candidateOf, chosen, commitTimeMs, rankMatches, } from "../../local/backfill.js";
12
+ import { claudeIdFromFile, ranInside, walkCodexFiles, } from "../../local/discover.js";
13
+ import { fileEntry, firstLineOf, listDir } from "../../local/files.js";
14
+ import { completeLines } from "../../local/lines.js";
15
+ import { listOpencodeSessions, opencodeLines } from "../../local/opencode.js";
16
+ import { claudeProjectsDir, home, opencodeDb } from "../../local/paths.js";
17
+ import { formatSessionRef, parseSessionRef, } from "../../protocol/sessionRef.js";
18
+ import { codexSessionMeta } from "../../transcript/parseCodex.js";
19
+ import { flagValue } from "../args.js";
20
+ import { out, warn } from "../io.js";
21
+ import { clientFor, redactOptions, reportUpload, usableAuth, } from "../remote.js";
22
+ import { consentFor, stateDir, uploadTargetFor } from "../repo.js";
23
+ import { commandUsage } from "../usage.js";
24
+ const HOUR_MS = 3600_000;
25
+ function prOf(args) {
26
+ const raw = flagValue(args, "pr");
27
+ if (raw === undefined)
28
+ return undefined;
29
+ const pr = Number(raw);
30
+ if (!Number.isSafeInteger(pr) || pr < 1)
31
+ throw new Error("--pr <number> must be a pull request number");
32
+ return pr;
33
+ }
34
+ // The commit as git has it; undefined when this clone does not have it.
35
+ function commitFacts(cwd, sha) {
36
+ const head = tryGit(["show", "-s", "--format=%H%x00%P%x00%s%x00%at%x00%ct", sha], { cwd });
37
+ if (!head)
38
+ return undefined;
39
+ const [full, parents, subject, at, ct] = head.split("\0");
40
+ // A merge's changes are its other parent's, not a session's.
41
+ if ((parents ?? "").trim().split(/\s+/).length > 1)
42
+ return undefined;
43
+ const files = git([
44
+ "-c",
45
+ "core.quotePath=false",
46
+ "show",
47
+ "--first-parent",
48
+ "--format=",
49
+ "--name-only",
50
+ full,
51
+ ], { cwd })
52
+ .split("\n")
53
+ .filter(Boolean);
54
+ return {
55
+ sha: full,
56
+ subject: subject ?? "",
57
+ authorMs: Number(at) * 1000,
58
+ committerMs: Number(ct) * 1000,
59
+ files,
60
+ added: addedLines(cwd, full),
61
+ };
62
+ }
63
+ // Every checkout of the repository: this clone's worktrees, and any other
64
+ // directory whose origin is the same GitHub repository.
65
+ function repoOf(cwd, target, branch, pull) {
66
+ const checkouts = (tryGit(["worktree", "list", "--porcelain"], { cwd }) ?? "")
67
+ .split("\n")
68
+ .filter((l) => l.startsWith("worktree "))
69
+ .map((l) => l.slice("worktree ".length));
70
+ const roots = new Map();
71
+ const nearestDir = (path) => {
72
+ for (let at = path;; at = dirname(at)) {
73
+ if (existsSync(at))
74
+ return at;
75
+ if (dirname(at) === at)
76
+ return undefined;
77
+ }
78
+ };
79
+ return {
80
+ branch,
81
+ home: home(),
82
+ slug: `${target.owner}/${target.repo}`,
83
+ pull,
84
+ contains(path) {
85
+ if (checkouts.some((c) => ranInside(path, c)))
86
+ return true;
87
+ const dir = nearestDir(path);
88
+ if (!dir)
89
+ return false;
90
+ const root = repoRoot(dir);
91
+ if (!root)
92
+ return false;
93
+ if (!roots.has(root)) {
94
+ const other = targetOfUploadRemotes(remoteUrls(root, "origin"));
95
+ roots.set(root, !!other && sameTarget(other, target));
96
+ }
97
+ return roots.get(root);
98
+ },
99
+ };
100
+ }
101
+ // The sessions written to since `sinceMs` whose text names one of the
102
+ // commits or one of their files: Claude Code sessions and subagents, Codex
103
+ // rollouts, OpenCode sessions.
104
+ function candidates(sinceMs, hints) {
105
+ const found = [];
106
+ const mentions = (text) => hints.some((h) => text.includes(h));
107
+ const read = (file) => {
108
+ try {
109
+ return readFileSync(file, "utf8");
110
+ }
111
+ catch {
112
+ return "";
113
+ }
114
+ };
115
+ const base = claudeProjectsDir();
116
+ for (const project of listDir(base)) {
117
+ for (const name of listDir(join(base, project))) {
118
+ const path = join(base, project, name);
119
+ if (name.endsWith(".jsonl")) {
120
+ const id = claudeIdFromFile(name);
121
+ const entry = fileEntry(path);
122
+ if (!id || !entry || entry.mtimeMs < sinceMs)
123
+ continue;
124
+ const text = read(path);
125
+ if (!mentions(text))
126
+ continue;
127
+ found.push(candidateOf({ agent: "claude", id }, path, completeLines(text)));
128
+ continue;
129
+ }
130
+ const dir = join(path, "subagents");
131
+ for (const sub of listDir(dir)) {
132
+ if (!/^agent-[A-Za-z0-9_-]+\.jsonl$/.test(sub))
133
+ continue;
134
+ const file = join(dir, sub);
135
+ const entry = fileEntry(file);
136
+ if (!entry || entry.mtimeMs < sinceMs)
137
+ continue;
138
+ const text = read(file);
139
+ if (!mentions(text))
140
+ continue;
141
+ found.push(candidateOf({ agent: "claude", id: basename(sub, ".jsonl") }, file, completeLines(text), { sidechain: true, parent: `claude:${name}` }));
142
+ }
143
+ }
144
+ }
145
+ for (const { file } of walkCodexFiles(sinceMs)) {
146
+ const meta = codexSessionMeta(firstLineOf(file));
147
+ if (!meta)
148
+ continue;
149
+ const text = read(file);
150
+ if (!mentions(text))
151
+ continue;
152
+ found.push(candidateOf({ agent: "codex", id: meta.id }, file, completeLines(text), {
153
+ ...(meta.parentId ? { parent: `codex:${meta.parentId}` } : {}),
154
+ }));
155
+ }
156
+ for (const { id } of listOpencodeSessions(sinceMs)) {
157
+ const lines = opencodeLines(id);
158
+ if (!mentions(lines.join("\n")))
159
+ continue;
160
+ found.push(candidateOf({ agent: "opencode", id }, opencodeDb(), lines));
161
+ }
162
+ return found;
163
+ }
164
+ const day = (ms) => new Date(ms).toISOString().slice(0, 16).replace("T", " ");
165
+ // Finds the sessions that made commits traced nowhere, prints the evidence,
166
+ // and uploads the ones it is sure of through the normal upload path, linked
167
+ // to their commits.
168
+ async function backfill(args, cwd) {
169
+ const pr = prOf(args);
170
+ const shas = args.positional.slice(1);
171
+ if (!pr && !shas.length)
172
+ throw new Error('name a pull request with --pr <n>, or commits; see "tracehub backfill --help"');
173
+ const root = repoRoot(cwd);
174
+ if (!root)
175
+ throw new Error("not a git repository; run it in a clone of the repository");
176
+ const target = uploadTargetFor(cwd);
177
+ if (!target)
178
+ throw new Error(UPLOAD_POLICY_ERROR);
179
+ const named = flagValue(args, "repo");
180
+ if (named && named.toLowerCase() !== `${target.owner}/${target.repo}`)
181
+ throw new Error(`this clone's origin is ${target.owner}/${target.repo}, not ${named}; run it in a clone of ${named}`);
182
+ const dryRun = !!args.flags["dry-run"];
183
+ const only = (flagValue(args, "session") ?? "")
184
+ .split(",")
185
+ .filter(Boolean)
186
+ .map((s) => {
187
+ const ref = parseSessionRef(s);
188
+ if (!ref)
189
+ throw new Error(`--session: "${s}" is not <claude|codex|opencode>:<id>`);
190
+ return formatSessionRef(ref);
191
+ });
192
+ if (!dryRun && consentFor(cwd) !== true)
193
+ throw new Error(`no permission rule allows uploads for ${target.owner}/${target.repo}; run "tracehub setup"`);
194
+ const stored = usableAuth();
195
+ if (!stored)
196
+ throw new Error('not signed in; run "tracehub setup"');
197
+ const auth = await freshAuth(stored);
198
+ // The commits and their messages, and the pull request's head branch.
199
+ let branch;
200
+ let listed;
201
+ if (pr) {
202
+ const pull = await pullCommits(target, pr, auth.accessToken);
203
+ if (pull.author.toLowerCase() !== auth.login.toLowerCase())
204
+ throw new Error(`${target.owner}/${target.repo}#${pr} was opened by ${pull.author}, not ${auth.login}; backfill only uploads to your own pull requests`);
205
+ branch = pull.head;
206
+ listed = pull.commits;
207
+ if (listed.some(({ sha }) => !tryGit(["cat-file", "-e", `${sha}^{commit}`], { cwd })))
208
+ tryGit(["fetch", "--quiet", "origin", `pull/${pr}/head`], { cwd });
209
+ }
210
+ else
211
+ listed = shas.map((sha) => ({
212
+ sha,
213
+ message: tryGit(["log", "-1", "--format=%B", sha], { cwd }) ?? "",
214
+ }));
215
+ // A commit whose message names a trace that was uploaded is traced; one
216
+ // whose named trace never reached TraceHub (its push was lost) is
217
+ // backfilled under that trace id.
218
+ const commits = [];
219
+ const traceOf = new Map();
220
+ for (const { sha, message } of listed) {
221
+ const named = traceIds(message);
222
+ let uploaded = false;
223
+ for (const id of named) {
224
+ try {
225
+ uploaded ||= await traceUploaded(target, id, auth.accessToken);
226
+ }
227
+ catch (err) {
228
+ warn(`trace ${id}: ${err.message}; counted as uploaded`);
229
+ uploaded = true;
230
+ }
231
+ }
232
+ if (uploaded) {
233
+ out(`${sha.slice(0, 7)} already has trace ${named.join(", ")}; skipped`);
234
+ continue;
235
+ }
236
+ const facts = commitFacts(cwd, sha);
237
+ if (!facts) {
238
+ warn(`commit ${sha.slice(0, 7)} is a merge or not in this clone; skipped`);
239
+ continue;
240
+ }
241
+ commits.push(facts);
242
+ if (named[0])
243
+ traceOf.set(facts.sha, named[0]);
244
+ }
245
+ if (!commits.length) {
246
+ out("nothing to backfill");
247
+ return;
248
+ }
249
+ const since = Math.min(...commits.map(commitTimeMs)) - HOUR_MS;
250
+ const hints = [
251
+ ...commits.map((c) => c.sha.slice(0, 7)),
252
+ ...commits.flatMap((c) => c.files),
253
+ ];
254
+ const repo = repoOf(cwd, target, branch, pr);
255
+ let pool = candidates(since, hints);
256
+ if (only.length)
257
+ pool = pool.filter((c) => only.includes(formatSessionRef(c.ref)));
258
+ // A commit's earlier backfill keeps its trace id.
259
+ const dir = stateDir(cwd);
260
+ const earlier = new Map(readMarkers(dir)
261
+ .filter((m) => m.commit)
262
+ .map((m) => [m.commit, m.traceId]));
263
+ const markers = [];
264
+ for (const commit of commits) {
265
+ out(`${commit.sha.slice(0, 7)} ${commit.subject} (${day(commitTimeMs(commit))} UTC)`);
266
+ // The likely ones, or the best of the unlikely.
267
+ const all = rankMatches(commit, pool, repo);
268
+ const likely = all.filter((r) => r.match.confidence !== "low");
269
+ const ranked = (likely.length ? likely : all.slice(0, 1)).slice(0, 5);
270
+ if (!ranked.length)
271
+ out(" no session found");
272
+ const traceId = traceOf.get(commit.sha) ?? earlier.get(commit.sha) ?? newTraceId();
273
+ for (const { match } of ranked) {
274
+ const take = chosen(match, only.includes(match.session));
275
+ out(` ${take ? "upload" : "skip "} ${match.confidence.padEnd(6)} ${String(match.score).padStart(2)} ${match.session}${match.tied ? "" : " (not tied to this repository)"}`);
276
+ out(` ${match.evidence.join("; ") || "no evidence"}`);
277
+ if (take)
278
+ markers.push({
279
+ traceId,
280
+ session: match.session,
281
+ line: match.cut,
282
+ ts: new Date(commitTimeMs(commit)).toISOString(),
283
+ commit: commit.sha,
284
+ uploaded: false,
285
+ });
286
+ }
287
+ }
288
+ const traced = new Set(markers.map((m) => m.commit)).size;
289
+ out(`${traced} of ${commits.length} commit(s) have a session to upload`);
290
+ if (dryRun || !markers.length) {
291
+ if (dryRun)
292
+ out("dry run: nothing uploaded");
293
+ return;
294
+ }
295
+ appendMarkers(dir, markers);
296
+ const client = clientFor(auth);
297
+ const result = await uploadMarkers(client, target, dir, cwd, root, markers, redactOptions(), true);
298
+ reportUpload(result, target, out);
299
+ const linked = new Map();
300
+ for (const m of result.uploaded)
301
+ linked.set(m.commit, m.traceId);
302
+ for (const [sha, traceId] of linked) {
303
+ await client.linkCommit(target, sha, traceId);
304
+ out(`linked trace ${traceId} to ${sha.slice(0, 7)}`);
305
+ }
306
+ if (pr && linked.size) {
307
+ await client.checkPull(target, pr);
308
+ out(`asked TraceHub to check ${target.owner}/${target.repo}#${pr} again`);
309
+ out(`${tracehubUrl()}/pr/${target.owner}/${target.repo}/${pr}`);
310
+ }
311
+ if (result.failed)
312
+ throw new Error(`upload incomplete: ${result.failed.error}`);
313
+ }
314
+ export async function cmdBackfill(args, cwd) {
315
+ if (args.flags["help"] || args.flags["h"]) {
316
+ out(commandUsage("backfill"));
317
+ return;
318
+ }
319
+ await backfill(args, cwd);
320
+ }