Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
feat(trail): show how many changes were suggested in graft trail pull (#507)
anirudhkumar-nanonets5c3a67465732
diff --git a/TELEMETRY.md b/TELEMETRY.mdindex 2ec25284..166788ee 100644--- a/TELEMETRY.md+++ b/TELEMETRY.md@@ -48,7 +48,7 @@ The events:| `query` | `command`, `surface` (`cli`/`mcp`/`hook`), `hit` (`ask` only) | Any query command || `brain_signup_opened` | `mode` (`terminal`/`agent`) | `graft trail push` on a repo with no brain opens your browser to make one || `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`bad_callback`/`stopped`, and for an agent-run push `agent_link_opened`/`still_waiting`/`expired`/`unsupported`), `mode` (`terminal`/`agent`), `duration_bucket` | That handoff ends, one way or the other — for an agent-run push, each of its runs |-| `trail_pulled` | `outcome` (`written`/`already_present`/`nothing_accepted`/`skipped`/`error`/`dry_run`), `kinds` (which kinds of context file were written: `claude_md`, `folder_claude_md`, `agents_md`, `cursor_rule`, `skill`), `files_bucket`, `changes_bucket`, `skipped_bucket` | `graft trail pull` (or `graft claude-md pull`) finishes |+| `trail_pulled` | `outcome` (`written`/`already_present`/`nothing_accepted`/`skipped`/`error`/`dry_run`), `kinds` (which kinds of context file were written: `claude_md`, `folder_claude_md`, `agents_md`, `cursor_rule`, `skill`), `files_bucket`, `changes_bucket`, `skipped_bucket`, `suggested_bucket` (every change Trail has suggested for the wired agents' files, whatever became of it) | `graft trail pull` (or `graft claude-md pull`) finishes || `session_summary` | `graft_reads_bucket`, `source_reads_bucket`, `saved_tokens_bucket`, `graft_turns_bucket`, `reported_turns_bucket` | Once, after an agent session ends |Two rules govern every value above, and both are enforced in code rather than bydiff --git a/src/brain/pull.ts b/src/brain/pull.tsindex 09b3319d..f91ba6e8 100644--- a/src/brain/pull.ts+++ b/src/brain/pull.ts@@ -19,12 +19,14 @@ import {markContextFilesApplied,planContextFile,readByWired,+ readersOf,writePlannedFile,type ContextFile,type FilePlan,} from "./context-files.js";import type { BrainLink } from "./link.js";import { reviewUrl } from "./signup.js";+import { fetchRepoState, type Suggestions } from "./watch.js";import { CONTEXT_FILE_KINDS, countBucket, type TrailPullOutcome } from "../telemetry/contract.js";import { track } from "../telemetry/track.js";@@ -55,6 +57,71 @@ export function rulesLine(repo: string, res: ConnectResult): string | null {return `✓ ${rules} refreshed in ${where}`;}+/** `a, b and c`. */+function joinAnd(items: string[]): string {+ if (items.length <= 1) return items.join("");+ return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;+}++/**+ * Trail's suggestions, cut to the files the wired agents read: how many, and+ * whose files they are (`the files claude and cursor read`).+ *+ * Every suggestion Trail has made, whatever became of it — the counts it sends+ * do not say which are still waiting for review and which were dismissed.+ */+export function suggestedFor(s: Suggestions | undefined, wired: string[]): { count: number; whose: string } {+ if (!s) return { count: 0, whose: "" };+ let count = 0;+ const kinds = new Set<string>();+ if (s.claudeMd > 0 && readByWired("claude_md", wired)) {+ count += s.claudeMd;+ kinds.add("claude_md");+ }+ if (s.files) {+ for (const f of s.files) {+ if (f.changes <= 0 || !readByWired(f.kind, wired)) continue;+ count += f.changes;+ kinds.add(f.kind);+ }+ } else if (s.contextFiles > 0) {+ // No per-file list from this Trail, so no way to cut it to the wired agents'+ // files: the count is Trail's total.+ count += s.contextFiles;+ for (const k of ["agents_md", "folder_claude_md", "cursor_rule", "skill"]) kinds.add(k);+ }+ const readers = wired.length+ ? wired.filter((w) => [...kinds].some((k) => readersOf(k, [w]).length > 0))+ : [];+ return { count, whose: readers.length ? `the files ${joinAnd(readers)} read` : "this repo's context files" };+}++/**+ * The suggestions line after a build:+ * `● 18 suggestions for the files claude, agents and cursor read`. Null when+ * there are none to mention.+ */+export function suggestionsLine(s: Suggestions | undefined, wired: string[], again: boolean): string | null {+ const { count, whose } = suggestedFor(s, wired);+ if (count === 0) return null;+ return `● ${count.toLocaleString("en-US")} ${again ? "new " : ""}suggestion${count === 1 ? "" : "s"} for ${whose}`;+}++/**+ * What a pull says about the suggestions it did not write:+ * `● 20 suggested so far for the files claude read, 2 of them accepted`.+ *+ * This is what lets an agent watching the trail say "there are suggestions+ * waiting for you" before anything has been accepted. "So far", because the+ * build keeps adding them after the push returns. Null when Trail sent no+ * counts, or counts that cannot hold what was accepted.+ */+export function suggestedLine(suggested: { count: number; whose: string }, accepted: number): string | null {+ if (suggested.count === 0 || suggested.count < accepted) return null;+ const taken = accepted === 0 ? "none accepted yet" : `${accepted.toLocaleString("en-US")} of them accepted`;+ return `● ${suggested.count.toLocaleString("en-US")} suggested so far for ${suggested.whose}, ${taken}`;+}+/** Everything the pull will write, file by file, with where each change came from. */interface Planned {plan: FilePlan;@@ -66,7 +133,7 @@ interface Planned {* The `trail_pulled` event for one pull. Only the outcome, which kinds of file* were written, and bucketed counts leave the machine — see TELEMETRY.md.*/-function trackPull(repo: string, home: string | undefined, outcome: TrailPullOutcome, planned: Planned[] = []): void {+function trackPull(repo: string, home: string | undefined, outcome: TrailPullOutcome, planned: Planned[] = [], suggested = 0): void {const wrote = planned.filter((p) => p.plan.status && p.plan.written.length > 0);const kinds = [...new Set(wrote.map((p) => p.kind))].filter((k) => (CONTEXT_FILE_KINDS as readonly string[]).includes(k))@@ -80,6 +147,7 @@ function trackPull(repo: string, home: string | undefined, outcome: TrailPullOutfiles_bucket: countBucket(wrote.length),changes_bucket: countBucket(wrote.reduce((n, p) => n + p.plan.written.length, 0)),skipped_bucket: countBucket(planned.reduce((n, p) => n + p.plan.skipped.length, 0)),+ suggested_bucket: countBucket(suggested),},{ repo, home },);@@ -92,6 +160,9 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOpticonst write = opts.write ?? ((l: string) => console.error(l));const fetchImpl = opts.fetchImpl ?? fetch;let code = 0;+ // Read beside everything else: it only adds a line, and a Trail that cannot+ // answer it costs the pull nothing.+ const repoState = fetchRepoState(link, fetchImpl);// 1. The rules. Skipped on a dry run, which writes nothing at all.if (!opts.dryRun) {@@ -135,12 +206,20 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOpti}}+ const suggested = suggestedFor((await repoState)?.suggestions, opts.wired);+ const waiting = suggestedLine(suggested, accepted);+if (accepted === 0) {if (code === 0) {- write("· nothing accepted in Trail yet — review:");- write(` ${reviewUrl(link.brainId)}`);+ if (waiting) {+ write(waiting);+ write(` review: ${reviewUrl(link.brainId)}`);+ } else {+ write("· nothing accepted in Trail yet — review:");+ write(` ${reviewUrl(link.brainId)}`);+ }}- trackPull(repo, opts.home, code === 0 ? "nothing_accepted" : "error");+ trackPull(repo, opts.home, code === 0 ? "nothing_accepted" : "error", [], suggested.count);return code;}@@ -165,9 +244,14 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOpti}}+ if (waiting) {+ write(waiting);+ write(` review: ${reviewUrl(link.brainId)}`);+ }+if (opts.dryRun) {write("· dry run — nothing written, and Trail was not told");- trackPull(repo, opts.home, "dry_run", planned);+ trackPull(repo, opts.home, "dry_run", planned, suggested.count);return code;}@@ -199,6 +283,6 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOpti: anySkipped? "skipped": "error";- trackPull(repo, opts.home, outcome, planned);+ trackPull(repo, opts.home, outcome, planned, suggested.count);return code;}diff --git a/src/brain/watch.ts b/src/brain/watch.tsindex c72066ff..eaf072b2 100644--- a/src/brain/watch.ts+++ b/src/brain/watch.ts@@ -177,7 +177,10 @@ interface RepoBody {// the finished row, exactly as it did before.build?: { found_so_far?: number; filed_so_far?: number } | null;claude_md?: { status?: string; quick_ready?: boolean; full_ready?: boolean; changes?: unknown } | null;- context_files?: { files?: unknown; changes?: unknown } | null;+ // An object on every SSE frame. On the polled GET it is the `true` that says+ // the routes exist, and the counts ride in `context_files_progress` instead.+ context_files?: { files?: unknown; changes?: unknown } | boolean | null;+ context_files_progress?: { files?: unknown; changes?: unknown } | null;}/**@@ -196,15 +199,16 @@ export function parseRepoBody(body: unknown): RepoState | null {filedSoFar: num(b.build?.filed_so_far),foundSoFar: num(b.build?.found_so_far),};- if (b.claude_md || b.context_files) {- const files = Array.isArray(b.context_files?.files)- ? (b.context_files!.files as Array<{ kind?: unknown; path?: unknown; changes?: unknown }>)+ const cf = b.context_files && typeof b.context_files === "object" ? b.context_files : b.context_files_progress;+ if (b.claude_md || cf) {+ const files = Array.isArray(cf?.files)+ ? (cf!.files as Array<{ kind?: unknown; path?: unknown; changes?: unknown }>).filter((f) => f && typeof f === "object").map((f) => ({ kind: String(f.kind ?? ""), path: String(f.path ?? ""), changes: countOf(f.changes) })): undefined;state.suggestions = {claudeMd: countOf(b.claude_md?.changes),- contextFiles: b.context_files?.changes !== undefined ? countOf(b.context_files.changes) : (files ?? []).reduce((n, f) => n + f.changes, 0),+ contextFiles: cf?.changes !== undefined ? countOf(cf.changes) : (files ?? []).reduce((n, f) => n + f.changes, 0),...(files ? { files } : {}),};}diff --git a/src/cli.ts b/src/cli.tsindex d95fdb5c..9b674b65 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -33,7 +33,7 @@ import {} from "./brain/push.js";import { apiBaseUrl, clearPendingSignup, readLink, readPendingSignup, writeLink, writePendingSignup } from "./brain/link.js";import { withLegacyNames } from "./legacy-args.js";-import { currentStage, DOING_LABEL, rulesSoFar, watchBuild, type RepoState, type Suggestions } from "./brain/watch.js";+import { currentStage, DOING_LABEL, rulesSoFar, watchBuild, type RepoState } from "./brain/watch.js";import {AGENT_WAIT_MS,brainUrl,@@ -45,8 +45,7 @@ import {startHandoff,waitForSignup,} from "./brain/signup.js";-import { runTrailPull } from "./brain/pull.js";-import { readByWired, readersOf } from "./brain/context-files.js";+import { runTrailPull, suggestionsLine } from "./brain/pull.js";import { startSpinner } from "./util/spinner.js";import { contextDirFor } from "./context/node-file.js";import { loadGraphCached } from "./graph/load.js";@@ -1570,39 +1569,6 @@ async function runTrailPullCommand(dir: string, opts: { dryRun?: boolean }): Proif (code !== 0) process.exitCode = code;}-/**- * The suggestions line after a build, cut to the files the wired agents read:- * `● 18 suggestions for the files claude, agents and cursor read`. Null when- * there are none to mention.- */-function suggestionsLine(s: Suggestions | undefined, wired: string[], again: boolean): string | null {- if (!s) return null;- let count = 0;- const kinds = new Set<string>();- if (s.claudeMd > 0 && readByWired("claude_md", wired)) {- count += s.claudeMd;- kinds.add("claude_md");- }- if (s.files) {- for (const f of s.files) {- if (f.changes <= 0 || !readByWired(f.kind, wired)) continue;- count += f.changes;- kinds.add(f.kind);- }- } else if (s.contextFiles > 0) {- // No per-file list from this Trail, so no way to cut it to the wired agents'- // files: the count is Trail's total.- count += s.contextFiles;- for (const k of ["agents_md", "folder_claude_md", "cursor_rule", "skill"]) kinds.add(k);- }- if (count === 0) return null;- const readers = wired.length- ? wired.filter((w) => [...kinds].some((k) => readersOf(k, [w]).length > 0))- : [];- const whose = readers.length ? `the files ${joinAnd(readers)} read` : "this repo's context files";- return `● ${count.toLocaleString("en-US")} ${again ? "new " : ""}suggestion${count === 1 ? "" : "s"} for ${whose}`;-}-brain.command("push").description("Read THIS repo on your machine and build its trail — no GitHub App, works on private repos")diff --git a/src/telemetry/contract.ts b/src/telemetry/contract.tsindex c423adc4..e44d6e11 100644--- a/src/telemetry/contract.ts+++ b/src/telemetry/contract.ts@@ -64,7 +64,7 @@ export const EVENTS: Record<string, ReadonlySet<string>> = {* written (a fixed set, sorted); every count is a bucket. Paths, headings and* the changes' text never travel. The adoption number for Trail's context* files: how many people actually take a suggestion home. */- trail_pulled: new Set<string>(['outcome', 'kinds', 'files_bucket', 'changes_bucket', 'skipped_bucket']),+ trail_pulled: new Set<string>(['outcome', 'kinds', 'files_bucket', 'changes_bucket', 'skipped_bucket', 'suggested_bucket']),/** One closed agent session, summarised. `graft_reads` vs `source_reads` is* the single number that says whether an agent prefers graft to grep; the two* `*_turns` buckets are the follow-up question — of the turns that used graft,diff --git a/test/brain-context-files-pull.test.ts b/test/brain-context-files-pull.test.tsindex 6449429b..c38cf8a7 100644--- a/test/brain-context-files-pull.test.ts+++ b/test/brain-context-files-pull.test.ts@@ -141,14 +141,15 @@ const link = { brainId: 'b1', token: 'gbt_1.x', baseUrl: 'http://trail.test' } aconst json = (body: unknown, status = 200) =>new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });-function fakeTrail(files: ContextFile[], opts: { contextFiles?: 'ok' | 'missing' } = {}) {+function fakeTrail(files: ContextFile[], opts: { contextFiles?: 'ok' | 'missing'; repo?: unknown; claudeMd?: unknown[] } = {}) {const applied: Record<string, string[]> = {};const f = (async (u: string, init?: RequestInit) => {const path = new URL(u).pathname;if (path.endsWith('/rules/anchors')) return json({ anchors: [] });if (path.endsWith('/claude-md')) {- return json({ path: 'CLAUDE.md', head_sha: 'abc', changes: [{ id: 'm1', kind: 'add', heading: 'Money', after_heading: '', text: 'Integer cents.' }] });+ return json({ path: 'CLAUDE.md', head_sha: 'abc', changes: opts.claudeMd ?? [{ id: 'm1', kind: 'add', heading: 'Money', after_heading: '', text: 'Integer cents.' }] });}+ if (path.endsWith('/repo') && opts.repo) return json(opts.repo);if (path.endsWith('/context-files')) {return opts.contextFiles === 'missing' ? json({ error: 'not found' }, 404) : json({ head_sha: 'abc', files });}@@ -213,3 +214,48 @@ test('a Trail without context files still pulls CLAUDE.md, silently', async () =assert.match(lines.join('\n'), /✓ wrote 1 accepted change\n A CLAUDE\.md +\+ Money/);assert.doesNotMatch(lines.join('\n'), /✗/);});++/** Trail's GET /repo mid-review: 3 CLAUDE.md suggestions, 2 skills, 4 Cursor rules. */+const REVIEWING = {+ repo: { status: 'completed', rule_count: 75 },+ claude_md: { status: 'ready', changes: 3 },+ context_files: true,+ context_files_progress: {+ changes: 6,+ files: [+ { kind: 'skill', path: '.claude/skills/a/SKILL.md', changes: 2 },+ { kind: 'cursor_rule', path: '.cursor/rules/a.mdc', changes: 4 },+ ],+ },+};++test('with nothing accepted, a pull says how many suggestions are waiting for the wired agents', async () => {+ const root = tmpRepo('ctx-waiting');+ const { f } = fakeTrail([], { repo: REVIEWING, claudeMd: [] });+ const lines: string[] = [];+ const code = await runTrailPull(root, link, { home: root, wired: ['claude'], dryRun: true, fetchImpl: f, write: (l) => lines.push(l) });+ const out = lines.join('\n');+ assert.equal(code, 0);+ assert.match(out, /● 5 suggested so far for the files claude read, none accepted yet\n review: \S+\/brain\/b1\/context-files/);+ assert.doesNotMatch(out, /nothing accepted in Trail yet/);+});++test('a dry run with accepted changes also says how many were suggested, and where to review', async () => {+ const root = tmpRepo('ctx-waiting-dry');+ const { f } = fakeTrail([], { repo: REVIEWING });+ const lines: string[] = [];+ await runTrailPull(root, link, { home: root, wired: ['claude', 'cursor'], dryRun: true, fetchImpl: f, write: (l) => lines.push(l) });+ const out = lines.join('\n');+ assert.match(out, /✓ would write 1 accepted change/);+ assert.match(out, /● 9 suggested so far for the files claude and cursor read, 1 of them accepted\n review: /);+ assert.match(out, /dry run — nothing written/);+});++test('a Trail that sends no counts leaves the pull as it was', async () => {+ const root = tmpRepo('ctx-no-counts');+ const { f } = fakeTrail([], { claudeMd: [] });+ const lines: string[] = [];+ await runTrailPull(root, link, { home: root, wired: ['claude'], fetchImpl: f, write: (l) => lines.push(l) });+ assert.match(lines.join('\n'), /· nothing accepted in Trail yet — review:/);+ assert.doesNotMatch(lines.join('\n'), /suggested so far/);+});diff --git a/test/brain-watch-events.test.ts b/test/brain-watch-events.test.tsindex 3ee65fe9..c14e223b 100644--- a/test/brain-watch-events.test.ts+++ b/test/brain-watch-events.test.ts@@ -52,6 +52,21 @@ test('the suggestion counts are read whether Trail sends numbers or lists', () =assert.equal(parseRepoBody({ repo: { status: 'ingesting' } })?.suggestions, undefined, 'an older Trail sends none');});+test('the polled GET carries the context-file counts in context_files_progress', () => {+ // On GET /repo, `context_files` is the flag that says the routes exist.+ const polled = parseRepoBody({+ repo: { status: 'completed' },+ claude_md: { status: 'analyzing', changes: 3 },+ context_files: true,+ context_files_progress: { changes: 2, files: [{ kind: 'skill', path: '.claude/skills/a/SKILL.md', changes: 2 }] },+ });+ assert.deepEqual(polled?.suggestions, {+ claudeMd: 3,+ contextFiles: 2,+ files: [{ kind: 'skill', path: '.claude/skills/a/SKILL.md', changes: 2 }],+ });+});+// --- the stream ---------------------------------------------------------------/** A text/event-stream response that sends each part in turn, then ends (or not). */diff --git a/test/telemetry-contract.test.ts b/test/telemetry-contract.test.tsindex af27f271..1d32b823 100644--- a/test/telemetry-contract.test.ts+++ b/test/telemetry-contract.test.ts@@ -217,11 +217,12 @@ test('trail pull: counts travel as buckets, and a path never rides along', () =>const home = sandbox('tel-trail-pulled');const ev = track('trail_pulled',- { outcome: 'written', kinds: 'agents_md,claude_md', files_bucket: '1-4', changes_bucket: '5-19', skipped_bucket: '0', path: 'web/CLAUDE.md' },+ { outcome: 'written', kinds: 'agents_md,claude_md', files_bucket: '1-4', changes_bucket: '5-19', skipped_bucket: '0', suggested_bucket: '20-49', path: 'web/CLAUDE.md' },{ home, env: OPEN },);assert.equal(ev?.properties.outcome, 'written');assert.equal(ev?.properties.kinds, 'agents_md,claude_md');assert.equal(ev?.properties.changes_bucket, '5-19');+ assert.equal(ev?.properties.suggested_bucket, '20-49');assert.equal(ev?.properties.path, undefined);});