tracehub 0.5.2 → 0.5.3

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.2 setup
81
+ npx --yes tracehub@0.5.3 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,7 +89,7 @@ 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.2`, then `tracehub setup`.
92
+ To skip npx on every commit, install it globally instead: `npm install -g tracehub@0.5.3`, then `tracehub setup`.
93
93
 
94
94
  ### Git hooks
95
95
 
@@ -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.2 uninstall
113
+ npx --yes tracehub@0.5.3 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.
@@ -331,6 +331,7 @@ Literals in `~/.config/tracehub/deny.txt`, one per line, are always redacted. Ed
331
331
  | `PUT /repos/:owner/:repo/traces/:trace/sessions/:name` | stores a session's trace at a commit, replacing the one there |
332
332
  | `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
333
  | `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 |
334
+ | `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 |
334
335
  | `PUT /consent` | registers a machine's permission rules for the signed-in user; `rules: []` forgets the machine |
335
336
  | `GET /login`, `/logout`, `/api/auth/callback` | browser sign-in (through the web app) |
336
337
  | `POST /github/webhook` | the GitHub App's webhook |
@@ -340,7 +341,7 @@ Bucket keys: `<owner>/<repo>/traces/<trace id>/<session name>` (an uploaded sess
340
341
 
341
342
  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.
342
343
 
343
- The `PUT` routes 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.
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.
344
345
 
345
346
  ### GitHub App (once)
346
347
 
@@ -348,12 +349,12 @@ The App of the deployed Tracehub API exists; the Tracehub API reads its key from
348
349
 
349
350
  For another deployment, create an App in the GitHub organization:
350
351
 
351
- - Permissions: pull requests: write, checks: write (the TraceHub traces check), contents: read, metadata: read. Events: pull request, push. Webhook `<tracehub>/github/webhook`.
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`.
352
353
  - Callback URL `<tracehub>/api/auth/callback`, for the browser sign-in.
353
354
  - Device flow enabled, for the sign-in of `tracehub setup`.
354
355
  - A client secret, for the browser sign-in.
355
356
 
356
- Install it on the repositories, set its client id as `GITHUB_CLIENT_ID` in `tracehub/wrangler.jsonc` and as `TRACEHUB_GITHUB_CLIENT_ID` for the CLI, and store its values as secrets; the three of the key win over the bucket:
357
+ Install it on the repositories. An existing App installation must accept the new Merge queues: read permission. Set its client id as `GITHUB_CLIENT_ID` in `tracehub/wrangler.jsonc` and as `TRACEHUB_GITHUB_CLIENT_ID` for the CLI, and store its values as secrets; the three of the key win over the bucket:
357
358
 
358
359
  ```sh
359
360
  cd tracehub
@@ -365,15 +366,21 @@ printf %s "<webhook secret>" | npx wrangler secret put GITHUB_WEBHOOK_SECRET
365
366
 
366
367
  ### The TraceHub traces check
367
368
 
368
- The App reports a check run named **TraceHub traces** on commits of `assistant-ui` repositories that have a known trace, that is an uploaded session marked by a trace id the commit message names. It is always a success; where there is no known trace, nothing is reported.
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).
369
370
 
370
- - A pull request's head commit gets it when at least one of the pull request's current commits has a known trace; the output lists the traces of all of them.
371
- - Any other commit gets it when it has a known trace itself: on a push, and when a trace upload attaches a trace to a commit TraceHub has seen.
372
- - The output lists each attached trace with a link to its TraceHub page, its agent and its number of sessions; the run's details link goes to the pull request's (or the trace's) TraceHub page.
373
- - A trace attached later, by an upload, posts the check then, on the pull request heads and commits the index knows for the trace.
374
- - An unchanged check is not written again; a changed one updates the same check run. A check run already on a commit without a known trace is left as it is.
371
+ - 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.
374
+ - **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.
377
+ - 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
+ - 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
+ - An unchanged check is not written again; a changed one updates the same check run.
380
+ - 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
+ - `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.
375
382
 
376
- The check can be required, in the repository's (or the organization's) **Settings → Rules → Rulesets**: a branch ruleset for the default branch with **Require status checks to pass** and the check **TraceHub traces** (pick the TraceHub App as its source), or with classic branch protection, **Settings → Branches → Branch protection rule → Require status checks to pass before merging → TraceHub traces**. Then only pull requests with a known trace can be merged: one without never gets the check, so it stays waiting for it. The check must have run once on the repository before GitHub offers it.
383
+ To require the check, add **TraceHub traces** from the **TraceHub App** as a required status check in the branch's ruleset. The `merge_group` mirror covers the merge queue, including squash merges.
377
384
 
378
385
  ## Trying it end to end
379
386
 
@@ -381,7 +388,7 @@ Do not try it with the session you are working in: what is uploaded stays in the
381
388
 
382
389
  ```sh
383
390
  gh repo create assistant-ui/tracehub-playground --private --clone && cd tracehub-playground
384
- npx --yes tracehub@0.5.2 setup # allow this repository, install the hooks
391
+ npx --yes tracehub@0.5.3 setup # allow this repository, install the hooks
385
392
 
386
393
  # open a fresh agent session in this directory, ask it for something harmless
387
394
  export TRACEHUB_ID=claude:<throwaway session id>
@@ -1,5 +1,7 @@
1
1
  import { editsOf, firstArg, parseJsonl, } from "./transcript.js";
2
- const INJECTED = /^\s*<[a-z_]+[\s>]/;
2
+ // Codex writes the context it injects (environment, AGENTS.md) as user
3
+ // messages; only the person's own prompts are kept.
4
+ const INJECTED = /^\s*(?:<[a-z_]+[\s>]|# AGENTS\.md instructions for )/;
3
5
  const TEXT_BLOCKS = ["input_text", "output_text", "text"];
4
6
  function textOf(content) {
5
7
  if (typeof content === "string")
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tracehub",
3
- "version": "0.5.2",
3
+ "version": "0.5.3",
4
4
  "description": "Attach coding-agent sessions (Claude Code, Codex, OpenCode) to git commits and pull requests, redacted.",
5
5
  "type": "module",
6
6
  "license": "MIT",