tracehub 0.5.0 → 0.5.2
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 +17 -10
- package/dist/cli/commands/hook.js +11 -5
- package/dist/cli/repo.js +15 -10
- package/dist/client/uploadPolicy.js +2 -2
- package/dist/git/git.js +11 -14
- package/package.json +3 -5
package/README.md
CHANGED
|
@@ -6,8 +6,6 @@ Attach the conversations behind coding-agent work (Claude Code, Codex, OpenCode)
|
|
|
6
6
|
|
|
7
7
|
A commit made while an agent session is active gets an `Assisted-by: https://tracehub.aui.dev/t/<owner>/<repo>/<trace id>` trailer: a link to its trace, under a random trace id that says nothing about the session. The commit also records where each session stood when it was made. On push, the CLI turns each session into its trace at that commit, fetches the context conversations the session names from their providers, redacts everything and uploads it; TraceHub keeps one self-contained document per commit.
|
|
8
8
|
|
|
9
|
-
`SPEC.md` describes the whole system in detail.
|
|
10
|
-
|
|
11
9
|
## Design
|
|
12
10
|
|
|
13
11
|
A trace is everything that produced one commit, in one JSON document:
|
|
@@ -80,7 +78,7 @@ Everything is computed on the developer's machine, redacted there, checked again
|
|
|
80
78
|
Set it up once with `setup` (the other commands are under [Commands](#commands)). Run it in your terminal:
|
|
81
79
|
|
|
82
80
|
```sh
|
|
83
|
-
npx --yes tracehub@0.5.
|
|
81
|
+
npx --yes tracehub@0.5.2 setup
|
|
84
82
|
```
|
|
85
83
|
|
|
86
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.
|
|
@@ -91,7 +89,7 @@ Setup is a form of three steps. Each step saves what you chose before the next o
|
|
|
91
89
|
|
|
92
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.
|
|
93
91
|
|
|
94
|
-
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.2`, then `tracehub setup`.
|
|
95
93
|
|
|
96
94
|
### Git hooks
|
|
97
95
|
|
|
@@ -112,7 +110,7 @@ Setup installs global Git hooks: it points the global `core.hooksPath` at `~/.co
|
|
|
112
110
|
### Uninstall
|
|
113
111
|
|
|
114
112
|
```sh
|
|
115
|
-
npx --yes tracehub@0.5.
|
|
113
|
+
npx --yes tracehub@0.5.2 uninstall
|
|
116
114
|
```
|
|
117
115
|
|
|
118
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.
|
|
@@ -121,8 +119,8 @@ Lists what it removes and asks first (default no); with nothing set up it says s
|
|
|
121
119
|
|
|
122
120
|
Uploads are restricted to repositories verified as owned by the GitHub organization **`assistant-ui`** (CLI 0.4.0 and later).
|
|
123
121
|
|
|
124
|
-
-
|
|
125
|
-
- Git's URL rewrites are resolved
|
|
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.
|
|
126
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.
|
|
127
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.
|
|
128
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.
|
|
@@ -171,8 +169,8 @@ TraceHub keeps a copy of your rules (`_consent/users/<your id>`).
|
|
|
171
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.
|
|
172
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.
|
|
173
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`.
|
|
174
|
-
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
|
|
175
|
-
5. **Reading.** The
|
|
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.
|
|
176
174
|
6. **Without a pull request.** A push prints a link per commit it marked, `/t/<owner>/<repo>/<trace id>`.
|
|
177
175
|
|
|
178
176
|
### What a trace holds
|
|
@@ -311,6 +309,15 @@ The agent's own file is never changed. The `pre-push` hook reports what it maske
|
|
|
311
309
|
|
|
312
310
|
Messages are asked in windows of 4000 characters; a window that is sensitive is asked again message by message. The redacted messages leave the Tracehub API for TypeSafe's API. Without `TYPESAFE_API_KEY` the Tracehub API skips steps 2 to 4.
|
|
313
311
|
|
|
312
|
+
### Translation
|
|
313
|
+
|
|
314
|
+
Pages show a message written in another language in English, with "Translated from <language> · Show original" to read it as written. The stored trace and context keep the original; the `.json` twins carry both (`translation: { from, text }` beside `text`).
|
|
315
|
+
|
|
316
|
+
- Which messages: a count of the prose's letters by script (code, links, paths and identifiers left out). A message mostly in Han, kana, Hangul, Cyrillic, Arabic, Hebrew, Greek, Thai or Devanagari is translated; English never reaches the model. Latin-script languages (Spanish, German…) are not detected.
|
|
317
|
+
- How: Cloudflare Workers AI (`@cf/qwen/qwen3.8-27b`), called by the Tracehub API Worker on the messages it already stores, after the redaction and the sensitivity check above; withheld messages are never sent. Code blocks, inline code, URLs, paths and identifiers are replaced by tokens before the model sees the text and put back after; a translation that loses one is dropped.
|
|
318
|
+
- When: as a page's data is read for rendering (after each upload, and for traces stored before translation existed, on their next render). Each text is translated once and cached in the bucket under `_translations/<sha256 of model and text>`; a changed message is translated again.
|
|
319
|
+
- Limits: messages over 8000 characters are not translated; at most 100 model calls per read, 4 at a time.
|
|
320
|
+
|
|
314
321
|
### Deny list
|
|
315
322
|
|
|
316
323
|
Literals in `~/.config/tracehub/deny.txt`, one per line, are always redacted. Edit the file by hand (keep it mode `0600`); lines under 6 characters are ignored. The file holds the literals themselves, so treat it like the secrets.
|
|
@@ -374,7 +381,7 @@ Do not try it with the session you are working in: what is uploaded stays in the
|
|
|
374
381
|
|
|
375
382
|
```sh
|
|
376
383
|
gh repo create assistant-ui/tracehub-playground --private --clone && cd tracehub-playground
|
|
377
|
-
npx --yes tracehub@0.5.
|
|
384
|
+
npx --yes tracehub@0.5.2 setup # allow this repository, install the hooks
|
|
378
385
|
|
|
379
386
|
# open a fresh agent session in this directory, ask it for something harmless
|
|
380
387
|
export TRACEHUB_ID=claude:<throwaway session id>
|
|
@@ -8,13 +8,13 @@ import { tracehubUrl } from "../../client/tracehub.js";
|
|
|
8
8
|
import { consentFile } from "../../local/paths.js";
|
|
9
9
|
import { firstLine } from "../../client/errors.js";
|
|
10
10
|
import { uploadMarkers } from "../../client/upload.js";
|
|
11
|
-
import { UPLOAD_POLICY_ERROR } from "../../client/uploadPolicy.js";
|
|
11
|
+
import { UPLOAD_OWNER, UPLOAD_POLICY_ERROR, } from "../../client/uploadPolicy.js";
|
|
12
12
|
import { git, pushedTraceIds, repoRoot, tracesInPushedHistory, } from "../../git/git.js";
|
|
13
13
|
import { pendingMarkers, readMarkers, recordMarkers, } from "../../git/markers.js";
|
|
14
14
|
import { interpretTrailersArgs, newTraceId, shouldSkipCommit, traceIds, } from "../../git/trailers.js";
|
|
15
15
|
import { formatContextRef, parseContextRef } from "../../protocol/context.js";
|
|
16
16
|
import { formatSessionRef } from "../../protocol/sessionRef.js";
|
|
17
|
-
import { ENV_CONTEXT } from "../../local/paths.js";
|
|
17
|
+
import { ENV_CONTEXT, ENV_SESSION_ID } from "../../local/paths.js";
|
|
18
18
|
import { warn } from "../io.js";
|
|
19
19
|
import { BACKGROUND_BUDGET_MS, clientFor, commitCount, pushBudgetMs, ranOutOfTime, reportUpload, redactOptions, usableAuth, } from "../remote.js";
|
|
20
20
|
import { consentFor, hooksDisabled, resolveSessions, stateDir, uploadTargetFor, } from "../repo.js";
|
|
@@ -29,8 +29,11 @@ function hookPrepareCommitMsg(args, cwd) {
|
|
|
29
29
|
if (!root)
|
|
30
30
|
return;
|
|
31
31
|
const target = uploadTargetFor(cwd);
|
|
32
|
-
if (!target)
|
|
32
|
+
if (!target) {
|
|
33
|
+
if (process.env[ENV_SESSION_ID]?.trim())
|
|
34
|
+
warn(`${ENV_SESSION_ID} is set, but origin is not one GitHub repository owned by ${UPLOAD_OWNER}; no trace attached to this commit`);
|
|
33
35
|
return;
|
|
36
|
+
}
|
|
34
37
|
const consent = consentFor(cwd);
|
|
35
38
|
if (consent === false)
|
|
36
39
|
return;
|
|
@@ -72,7 +75,10 @@ async function hookPrePush(args, cwd) {
|
|
|
72
75
|
warn('pre-push requires Git\'s destination arguments; forward "$@" from the hook; nothing was uploaded');
|
|
73
76
|
return;
|
|
74
77
|
}
|
|
75
|
-
const target = uploadTargetFor(cwd,
|
|
78
|
+
const target = uploadTargetFor(cwd, {
|
|
79
|
+
remote: args.positional[2],
|
|
80
|
+
url: pushedUrl,
|
|
81
|
+
});
|
|
76
82
|
if (!target) {
|
|
77
83
|
warn(UPLOAD_POLICY_ERROR);
|
|
78
84
|
return;
|
|
@@ -148,7 +154,7 @@ async function hookUpload(args, cwd) {
|
|
|
148
154
|
const [pushedUrl, ...ids] = args.positional.slice(2);
|
|
149
155
|
if (!pushedUrl || !ids.length)
|
|
150
156
|
return;
|
|
151
|
-
const target = uploadTargetFor(cwd, pushedUrl);
|
|
157
|
+
const target = uploadTargetFor(cwd, { url: pushedUrl });
|
|
152
158
|
if (!target) {
|
|
153
159
|
warn(UPLOAD_POLICY_ERROR);
|
|
154
160
|
return;
|
package/dist/cli/repo.js
CHANGED
|
@@ -2,7 +2,7 @@ import { mkdirSync } from "node:fs";
|
|
|
2
2
|
import { join } from "node:path";
|
|
3
3
|
import { getConsent, readConsent } from "../client/consent.js";
|
|
4
4
|
import { gitDir, headTimestampMs, originUrl, remoteUrls } from "../git/git.js";
|
|
5
|
-
import { targetOfUploadRemotes } from "../client/uploadPolicy.js";
|
|
5
|
+
import { sameTarget, targetOfUploadRemotes } from "../client/uploadPolicy.js";
|
|
6
6
|
import { pendingCommitCall } from "../local/commitBoundary.js";
|
|
7
7
|
import { sessionLines } from "../local/lines.js";
|
|
8
8
|
import { opencodePendingCommitCall } from "../local/opencode.js";
|
|
@@ -53,13 +53,18 @@ export function consentFor(cwd) {
|
|
|
53
53
|
return undefined;
|
|
54
54
|
return getConsent(readConsent(consentFile()), remote);
|
|
55
55
|
}
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
56
|
+
// The repository traces upload to is origin's: every effective fetch/push
|
|
57
|
+
// URL of origin must name it. Other remotes (contributors' forks kept for
|
|
58
|
+
// review) play no part. A push must go to that same repository: the URLs of
|
|
59
|
+
// the remote being pushed to, when it is a configured remote, and the URL Git
|
|
60
|
+
// passes to the hook.
|
|
61
|
+
export function uploadTargetFor(cwd, push) {
|
|
62
|
+
const target = targetOfUploadRemotes(remoteUrls(cwd, "origin"));
|
|
63
|
+
if (!target || !push)
|
|
64
|
+
return target;
|
|
65
|
+
const pushed = [push.url];
|
|
66
|
+
if (push.remote && push.remote !== push.url)
|
|
67
|
+
pushed.push(...remoteUrls(cwd, push.remote));
|
|
68
|
+
const destination = targetOfUploadRemotes(pushed);
|
|
69
|
+
return destination && sameTarget(destination, target) ? target : undefined;
|
|
65
70
|
}
|
|
@@ -14,8 +14,8 @@ export function parseUploadRemote(remote) {
|
|
|
14
14
|
export function sameTarget(a, b) {
|
|
15
15
|
return a.owner === b.owner && a.repo === b.repo;
|
|
16
16
|
}
|
|
17
|
-
// Every effective fetch/push
|
|
18
|
-
//
|
|
17
|
+
// Every given URL (one remote's effective fetch/push URLs, a push
|
|
18
|
+
// destination) must identify the same org-owned repository.
|
|
19
19
|
export function targetOfUploadRemotes(remotes) {
|
|
20
20
|
if (!remotes.length)
|
|
21
21
|
return undefined;
|
package/dist/git/git.js
CHANGED
|
@@ -35,21 +35,18 @@ export function headTimestampMs(cwd) {
|
|
|
35
35
|
export function originUrl(cwd) {
|
|
36
36
|
return tryGit(["remote", "get-url", "origin"], { cwd }) || undefined;
|
|
37
37
|
}
|
|
38
|
-
//
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
return [];
|
|
38
|
+
// One remote's effective fetch and push URLs: get-url expands
|
|
39
|
+
// insteadOf/pushInsteadOf and includes every configured URL. Empty when the
|
|
40
|
+
// remote does not exist.
|
|
41
|
+
export function remoteUrls(cwd, name) {
|
|
43
42
|
const urls = [];
|
|
44
|
-
for (const
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
urls.push(...found.split("\n"));
|
|
52
|
-
}
|
|
43
|
+
for (const mode of [[], ["--push"]]) {
|
|
44
|
+
const found = tryGit(["remote", "get-url", ...mode, "--all", name], {
|
|
45
|
+
cwd,
|
|
46
|
+
});
|
|
47
|
+
if (!found)
|
|
48
|
+
return [];
|
|
49
|
+
urls.push(...found.split("\n"));
|
|
53
50
|
}
|
|
54
51
|
return urls;
|
|
55
52
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tracehub",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.2",
|
|
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",
|
|
@@ -22,12 +22,10 @@
|
|
|
22
22
|
"test": "tsc -p tsconfig.test.json && node --test --import ./dist-test/test/support/testEnv.js dist-test/test/*.test.js",
|
|
23
23
|
"prepack": "npm run build",
|
|
24
24
|
"docs:install": "pnpm --dir docs install",
|
|
25
|
-
"docs:dev": "pnpm --dir docs dev"
|
|
26
|
-
"docs:approve": "pnpm --dir docs run approve",
|
|
27
|
-
"specs:watch": "pnpm --dir docs run specs:watch"
|
|
25
|
+
"docs:dev": "pnpm --dir docs dev"
|
|
28
26
|
},
|
|
29
27
|
"devDependencies": {
|
|
30
|
-
"@types/node": "^
|
|
28
|
+
"@types/node": "^26.6.6",
|
|
31
29
|
"oxfmt": "^0.74.0",
|
|
32
30
|
"typescript": "^7.0.2"
|
|
33
31
|
},
|