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 +21 -14
- package/dist/transcript/parseCodex.js +3 -1
- package/package.json +1 -1
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.
|
|
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.
|
|
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.
|
|
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:
|
|
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
|
|
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
|
|
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
|
-
-
|
|
371
|
-
-
|
|
372
|
-
-
|
|
373
|
-
-
|
|
374
|
-
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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")
|