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 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.0 setup
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.0`, then `tracehub setup`.
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.0 uninstall
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
- - All effective fetch and push remote 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. Missing, unknown or conflicting remotes block uploads. A personal fork with an organization upstream is blocked. Duplicate remotes to the same repository are allowed.
125
- - Git's URL rewrites are resolved, and pre-push also checks the destination URL Git passes to the hook. 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.
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 start of the description, between `<!-- tracehub:start -->` and `<!-- tracehub:end -->`: a small icon in the top right corner. A pull request with attached context gets the link too.
175
- 5. **Reading.** The icon 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.
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.0 setup # allow this repository, install the hooks
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, pushedUrl);
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
- export function uploadTargetFor(cwd, pushedUrl) {
57
- if (!originUrl(cwd))
58
- return undefined;
59
- const remotes = remoteUrls(cwd);
60
- if (!remotes.length)
61
- return undefined;
62
- if (pushedUrl !== undefined)
63
- remotes.push(pushedUrl);
64
- return targetOfUploadRemotes(remotes);
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 URL must identify the same org-owned repository.
18
- // A personal fork plus an org upstream is ambiguous, so it cannot upload.
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
- // get-url expands insteadOf/pushInsteadOf and includes every configured URL.
39
- export function remoteUrls(cwd) {
40
- const names = tryGit(["remote"], { cwd });
41
- if (!names)
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 name of names.split("\n")) {
45
- for (const mode of [[], ["--push"]]) {
46
- const found = tryGit(["remote", "get-url", ...mode, "--all", name], {
47
- cwd,
48
- });
49
- if (!found)
50
- return [];
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.0",
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": "^24.19.2",
28
+ "@types/node": "^26.6.6",
31
29
  "oxfmt": "^0.74.0",
32
30
  "typescript": "^7.0.2"
33
31
  },