tracehub 0.5.5 → 0.5.6

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
@@ -11,7 +11,7 @@ A commit made while an agent session is active gets an `Assisted-by: https://tra
11
11
  A trace is everything that produced one commit, in one JSON document:
12
12
 
13
13
  1. **Context conversations.** The conversations that asked for the work: a nomOS thread, a Slack thread, an issue, pasted prompts. A **provider** (a local command registered with `tracehub providers add`) returns all messages of a conversation by its id. A session names its conversation with a `tracehub-context: <provider>:<id>` line in its first message (an agent's brief to a subagent), or the commit with `TRACEHUB_CONTEXT=<provider>:<id>`; `tracehub context add --pr <n>` attaches one to a pull request by hand. See [Context conversations](#context-conversations).
14
- 2. **Sessions.** For each agent session attached to the commit: the user's messages and the agent's text replies, grouped into turns (a turn starts at a user prompt). Each turn lists the files it changed (`path`, lines added, lines removed). A subagent the turn launched is a **run** nested under it, with its own turns: the prompt the parent gave it, its replies, its changes. Tool calls, tool results, thinking, token metrics and local paths never leave the machine.
14
+ 2. **Sessions.** For each agent session attached to the commit, the part of it that made the commit (see [What a trace holds](#what-a-trace-holds)): the user's messages and the agent's text replies, grouped into turns (a turn starts at a user prompt). Each turn lists the files it changed (`path`, lines added, lines removed). A subagent the turn launched is a **run** nested under it, with its own turns: the prompt the parent gave it, its replies, its changes. Tool calls, tool results, thinking, token metrics and local paths never leave the machine.
15
15
  3. **A sourcemap** (optional). For each line the commit adds, the turn that last wrote it, blame-style.
16
16
 
17
17
  Everything is computed on the developer's machine, redacted there, checked again by the API (detectors and the sensitivity model), and shown only to the uploader and the repository's maintainers.
@@ -68,7 +68,7 @@ Everything is computed on the developer's machine, redacted there, checked again
68
68
  `{ "<path>": { "<line hash>": "<turn path>" } }`, for the lines the commit adds (`git show` of the commit against its first parent).
69
69
 
70
70
  - The line hash is FNV-1a 64 of the line with surrounding whitespace removed, as 16 hex characters; blank lines are left out. Hashes, not text, so the map says nothing the diff doesn't.
71
- - The turn path is the turn's index in the session, `"3"`; a subagent's turn adds the run and its turn, `"3.0.1"` (turn 3, its first run, that run's second turn), so the deepest turn that wrote a line is named, with the path up to the user's prompt.
71
+ - The turn path is the turn's index in the trace, `"3"`; a subagent's turn adds the run and its turn, `"3.0.1"` (turn 3, its first run, that run's second turn), so the deepest turn that wrote a line is named, with the path up to the user's prompt.
72
72
  - A line is attributed to the last edit, by time, whose new text contains it: Claude Code's `Write`, `Edit` and `MultiEdit`, Codex's `apply_patch` and OpenCode's `write`, `edit` and `patch`, parsed from the transcript up to the commit. Edits from before the session's previous commits count too, since a line written in turn 2 can be committed in turn 5.
73
73
  - Why tool inputs and not snapshots of the working tree: the hooks only run at commit and push, so there is no snapshot of the tree at each turn boundary to diff, while every edit tool records exactly what it wrote and when. Lines no edit tool wrote (a formatter, a shell command, a hand edit) stay unattributed.
74
74
  - A trace page's **Line map** lists, per file, the prompts that wrote the commit's lines and how many.
@@ -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.5 setup
81
+ npx --yes tracehub@0.5.6 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.5`, then `tracehub setup`.
92
+ To skip npx on every commit, install it globally instead: `npm install -g tracehub@0.5.6`, 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.5 uninstall
113
+ npx --yes tracehub@0.5.6 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.
@@ -175,7 +175,9 @@ TraceHub keeps a copy of your rules (`_consent/users/<your id>`).
175
175
 
176
176
  ### What a trace holds
177
177
 
178
- The trace of a session at a commit, built from the session's file up to the marker's line:
178
+ The trace of a session at a commit, built from the session's file up to the marker's line and scoped to that commit, so a session that commits many times (a coordinator working through several pull requests) shows each commit its own part:
179
+
180
+ - **Scope.** A turn is kept when it or one of its runs wrote a line the commit adds (by the sourcemap), or when it has messages since the session's previous commit in the repository; the commit's turn is always kept. A run is kept when it wrote one of the commit's lines; when no line is attributed, the runs active since the previous commit are kept instead. A turn kept only for a run keeps its prompt and its messages since the previous commit. A session's first commit has no previous one, so every turn before it is in scope; its runs still follow the rule above.
179
181
 
180
182
  - **Turns.** A turn starts at each user prompt; its messages are the user's (the prompt, then any steering) and the agent's text replies. The replies after the commit that finish the commit's turn are included; the next prompt is not.
181
183
  - **Changes.** Each turn lists the files its edit tools changed, as paths in the repository with lines added and removed. Edits outside the repository are left out.
@@ -434,7 +436,7 @@ Do not try it with the session you are working in: what is uploaded stays in the
434
436
 
435
437
  ```sh
436
438
  gh repo create assistant-ui/tracehub-playground --private --clone && cd tracehub-playground
437
- npx --yes tracehub@0.5.5 setup # allow this repository, install the hooks
439
+ npx --yes tracehub@0.5.6 setup # allow this repository, install the hooks
438
440
 
439
441
  # open a fresh agent session in this directory, ask it for something harmless
440
442
  export TRACEHUB_ID=claude:<throwaway session id>
@@ -1,6 +1,6 @@
1
1
  import { existsSync } from "node:fs";
2
2
  import { addedLines, commitOfTrace } from "../git/git.js";
3
- import { pendingMarkers, saveUploaded, } from "../git/markers.js";
3
+ import { pendingMarkers, readMarkers, saveUploaded, } from "../git/markers.js";
4
4
  import { findSessionFile, isClaudeSubagent } from "../local/discover.js";
5
5
  import { sessionLines } from "../local/lines.js";
6
6
  import { fetchAll, readProviders } from "../local/providers.js";
@@ -26,12 +26,23 @@ function sessionFileOf(marker, ref) {
26
26
  ? marker.file
27
27
  : findSessionFile(ref);
28
28
  }
29
- // Uploads the trace of each pending marker: the session's turns up to the
30
- // commit, the sourcemap of the lines the commit adds, and the context
31
- // conversations its marker and briefs name. `contextAllowed` is the
32
- // repository's permission rule: without it no provider runs.
29
+ // When the session of a marker made its previous commit in the repository.
30
+ function previousCommit(all, marker) {
31
+ const earlier = all
32
+ .filter((m) => m.session === marker.session)
33
+ .map((m) => Date.parse(m.ts))
34
+ .filter((ms) => ms < Date.parse(marker.ts));
35
+ return earlier.length
36
+ ? new Date(Math.max(...earlier)).toISOString()
37
+ : undefined;
38
+ }
39
+ // Uploads the trace of each pending marker: the session's part of the
40
+ // turns up to the commit, the sourcemap of the lines the commit adds, and
41
+ // the context conversations its marker and briefs name. `contextAllowed`
42
+ // is the repository's permission rule: without it no provider runs.
33
43
  export async function uploadMarkers(client, target, stateDir, cwd, root, markers, opts = {}, contextAllowed = false) {
34
44
  const pending = pendingMarkers(markers);
45
+ const all = readMarkers(stateDir);
35
46
  const result = {
36
47
  uploaded: [],
37
48
  skipped: [],
@@ -68,6 +79,7 @@ export async function uploadMarkers(client, target, stateDir, cwd, root, markers
68
79
  lines: sessionLines(ref, file),
69
80
  cut: marker.line,
70
81
  committedAt: marker.ts,
82
+ since: previousCommit(all, marker),
71
83
  subagents: subagentsOf(ref, file),
72
84
  root,
73
85
  added: sha ? addedLines(cwd, sha) : new Map(),
@@ -115,7 +115,13 @@ function turnsOf(events, cwd, prefix, ctx, children) {
115
115
  runs: [],
116
116
  });
117
117
  }
118
- turn.runs.push({ label: child.label, turns: runTurns });
118
+ const run = { label: child.label, turns: runTurns };
119
+ const times = child.transcript.events
120
+ .map((e) => Date.parse(e.ts))
121
+ .filter((ms) => !Number.isNaN(ms));
122
+ if (times.length)
123
+ ctx.ends.set(run, Math.max(...times));
124
+ turn.runs.push(run);
119
125
  }
120
126
  return turns;
121
127
  }
@@ -144,6 +150,50 @@ function sourcemapOf(written, added) {
144
150
  }
145
151
  return map;
146
152
  }
153
+ // The part of a session that made one commit, so a long session that
154
+ // commits many times shows each commit its own work: the turns and runs
155
+ // that wrote the commit's lines, and the turns with messages since the
156
+ // session's previous commit. A turn kept only for a run keeps its prompt
157
+ // and its messages since that commit. Without attributed lines, the runs
158
+ // active since that commit stay. The sourcemap's turn paths follow the
159
+ // kept turns.
160
+ function scopeToCommit(turns, sourcemap, sinceMs, ends) {
161
+ const hits = new Set(Object.values(sourcemap).flatMap((lines) => Object.values(lines)));
162
+ const paths = new Map();
163
+ const kept = [];
164
+ turns.forEach((turn, i) => {
165
+ const own = hits.has(`${i}`);
166
+ const recent = i === turns.length - 1 ||
167
+ [turn.at, ...turn.messages.map((m) => m.at)].some((at) => Date.parse(at) >= sinceMs);
168
+ const runs = [];
169
+ turn.runs.forEach((run, j) => {
170
+ const prefix = `${i}.${j}.`;
171
+ const wrote = [...hits].filter((h) => h.startsWith(prefix));
172
+ if (!wrote.length &&
173
+ (hits.size > 0 || !((ends.get(run) ?? -Infinity) > sinceMs)))
174
+ return;
175
+ for (const h of wrote)
176
+ paths.set(h, `${kept.length}.${runs.length}.${h.slice(prefix.length)}`);
177
+ runs.push(run);
178
+ });
179
+ if (!own && !recent && !runs.length)
180
+ return;
181
+ if (own)
182
+ paths.set(`${i}`, `${kept.length}`);
183
+ kept.push({
184
+ at: turn.at,
185
+ messages: own
186
+ ? turn.messages
187
+ : turn.messages.filter((m, k) => (k === 0 && m.role === "user") || Date.parse(m.at) >= sinceMs),
188
+ changes: own || recent ? turn.changes : [],
189
+ runs,
190
+ });
191
+ });
192
+ const scoped = {};
193
+ for (const [path, lines] of Object.entries(sourcemap))
194
+ scoped[path] = Object.fromEntries(Object.entries(lines).map(([hash, turn]) => [hash, paths.get(turn)]));
195
+ return { turns: kept, sourcemap: scoped };
196
+ }
147
197
  // The first user message of the session and of each run: the briefs, where
148
198
  // a coordinator names the conversation the work is for.
149
199
  function briefsOf(turns) {
@@ -153,15 +203,15 @@ function briefsOf(turns) {
153
203
  ...turns.flatMap((t) => t.runs.flatMap((r) => briefsOf(r.turns))),
154
204
  ];
155
205
  }
156
- // What leaves the machine for one session at one commit: the turns up to
157
- // the commit (and the agent's replies that finish the commit's turn), the
158
- // changes of each turn and the sourcemap of the commit's lines, redacted.
159
206
  // Whether any of the turns, or their runs, changed a file.
160
207
  function changed(turns) {
161
208
  return turns.some((t) => t.changes.length > 0 || t.runs.some((r) => changed(r.turns)));
162
209
  }
163
- // Undefined when there is nothing to share: a session that ran outside the
164
- // repository and whose subagents changed none of its files.
210
+ // What leaves the machine for one session at one commit: its part of the
211
+ // turns up to the commit (and the agent's replies that finish the commit's
212
+ // turn), the changes of each turn and the sourcemap of the commit's lines,
213
+ // redacted. Undefined when there is nothing to share: a session that ran
214
+ // outside the repository and whose subagents changed none of its files.
165
215
  export function buildTrace(input, opts = {}) {
166
216
  const { agent, id, lines, cut, committedAt } = input;
167
217
  const cutoffMs = Date.parse(committedAt);
@@ -215,7 +265,7 @@ export function buildTrace(input, opts = {}) {
215
265
  }
216
266
  };
217
267
  const roots = (dir) => [input.root, realOrSelf(input.root), nearest(dir)].filter((r) => !!r);
218
- const ctx = { roots, written: [] };
268
+ const ctx = { roots, written: [], ends: new Map() };
219
269
  const cwd = before.cwd || input.root;
220
270
  let turns = turnsOf(events, cwd, "", ctx, children.filter((c) => c.transcript.events.length));
221
271
  // A session that ran outside the repository (a coordinator whose
@@ -244,17 +294,25 @@ export function buildTrace(input, opts = {}) {
244
294
  : agent === "claude" && !outside
245
295
  ? sessionTitle(lines.slice(0, cut))
246
296
  : undefined;
297
+ const since = Date.parse(input.since ?? "");
298
+ const scoped = scopeToCommit(turns, sourcemapOf(ctx.written, input.added), Number.isNaN(since) ? -Infinity : since, ctx.ends);
299
+ // The session's first message names its conversation even when its turn
300
+ // is out of scope; a run's brief counts only for the runs in scope.
301
+ const first = turns[0]?.messages.find((m) => m.role === "user");
302
+ const briefs = [
303
+ ...(first ? [first.text] : []),
304
+ ...scoped.turns.flatMap((t) => t.runs.flatMap((r) => briefsOf(r.turns))),
305
+ ];
306
+ const refs = [
307
+ ...new Set(briefs.flatMap((t) => contextRefsIn(t, input.providers ?? []))),
308
+ ];
247
309
  const upload = {
248
310
  agent,
249
311
  ...(title ? { title } : {}),
250
312
  ...(whole.model ? { model: whole.model } : {}),
251
313
  committedAt,
252
- turns,
253
- sourcemap: sourcemapOf(ctx.written, input.added),
314
+ ...scoped,
254
315
  };
255
- const refs = [
256
- ...new Set(briefsOf(turns).flatMap((t) => contextRefsIn(t, input.providers ?? []))),
257
- ];
258
316
  const redacted = redactValue(upload, opts);
259
317
  return { upload: redacted.value, findings: redacted.findings, refs };
260
318
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tracehub",
3
- "version": "0.5.5",
3
+ "version": "0.5.6",
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",