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(telemetry): trail_pulled event for graft trail pull (#496)
anirudhkumar-nanonetsdfc46f0b6eac
diff --git a/TELEMETRY.md b/TELEMETRY.mdindex 8d7ca937..2ec25284 100644--- a/TELEMETRY.md+++ b/TELEMETRY.md@@ -48,6 +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 || `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 6c62d53e..09b3319d 100644--- a/src/brain/pull.ts+++ b/src/brain/pull.ts@@ -25,6 +25,8 @@ import {} from "./context-files.js";import type { BrainLink } from "./link.js";import { reviewUrl } from "./signup.js";+import { CONTEXT_FILE_KINDS, countBucket, type TrailPullOutcome } from "../telemetry/contract.js";+import { track } from "../telemetry/track.js";export interface PullOptions {home: string;@@ -57,6 +59,30 @@ export function rulesLine(repo: string, res: ConnectResult): string | null {interface Planned {plan: FilePlan;source: "claude-md" | "context-files";+ kind: string;+}++/**+ * 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 {+ 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))+ .sort()+ .join(",");+ track(+ "trail_pulled",+ {+ outcome,+ kinds,+ files_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)),+ },+ { repo, home },+ );}/**@@ -93,7 +119,7 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOpticonst file: ContextFile = { kind: kindForPath(md.path || "CLAUDE.md"), path: md.path || "CLAUDE.md", changes: md.changes };if (readByWired(file.kind, opts.wired)) {accepted += file.changes.length;- planned.push({ plan: planContextFile(repo, file), source: "claude-md" });+ planned.push({ plan: planContextFile(repo, file), source: "claude-md", kind: file.kind });}}@@ -105,7 +131,7 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOptifor (const file of ctx.files) {if (file.changes.length === 0 || !readByWired(file.kind, opts.wired)) continue;accepted += file.changes.length;- planned.push({ plan: planContextFile(repo, file), source: "context-files" });+ planned.push({ plan: planContextFile(repo, file), source: "context-files", kind: file.kind });}}@@ -114,6 +140,7 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOptiwrite("· nothing accepted in Trail yet — review:");write(` ${reviewUrl(link.brainId)}`);}+ trackPull(repo, opts.home, code === 0 ? "nothing_accepted" : "error");return code;}@@ -140,6 +167,7 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOptiif (opts.dryRun) {write("· dry run — nothing written, and Trail was not told");+ trackPull(repo, opts.home, "dry_run", planned);return code;}@@ -161,5 +189,16 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOpticonst told = (await markApplied(link, done("claude-md"), fetchImpl)) && (await markContextFilesApplied(link, done("context-files"), fetchImpl));if (!told) write("⚠ could not tell Trail which changes were written; it may still list them");if (writing.length > 0) write("· review with git diff, then commit");+ const anyWritten = planned.some((p) => p.plan.status && p.plan.written.length > 0);+ const anyPresent = planned.some((p) => p.plan.present.length > 0);+ const anySkipped = planned.some((p) => p.plan.skipped.length > 0);+ const outcome: TrailPullOutcome = anyWritten+ ? "written"+ : anyPresent+ ? "already_present"+ : anySkipped+ ? "skipped"+ : "error";+ trackPull(repo, opts.home, outcome, planned);return code;}diff --git a/src/telemetry/contract.ts b/src/telemetry/contract.tsindex 3b7c930e..c423adc4 100644--- a/src/telemetry/contract.ts+++ b/src/telemetry/contract.ts@@ -59,6 +59,12 @@ export const EVENTS: Record<string, ReadonlySet<string>> = {/** That handoff reaching an end. `outcome` is a closed set, so the reason a* signup failed travels as a category and never as the error's own words. */brain_signup_settled: new Set<string>(['outcome', 'mode', 'duration_bucket']),+ /** `graft trail pull` reaching an end: whether accepted Trail suggestions+ * made it into this checkout. `kinds` is which kinds of context file were+ * 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']),/** 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,@@ -120,6 +126,20 @@ export function isTrackedCommand(name: string): name is TrackedCommand {export const BRAIN_SIGNUP_OUTCOMES = ['linked', 'timed_out', 'no_tty', 'bad_callback', 'stopped'] as const;export type BrainSignupOutcome = (typeof BRAIN_SIGNUP_OUTCOMES)[number];+/**+ * How a `graft trail pull` ended. `written`: at least one file changed.+ * `already_present`: everything accepted was already in the files.+ * `nothing_accepted`: Trail had nothing accepted for this repo's agents.+ * `skipped`: accepted changes existed but none could be applied (the local+ * file moved on). `error`: Trail could not be read or a file not written.+ * `dry_run`: `--dry-run`, nothing written.+ */+export const TRAIL_PULL_OUTCOMES = ['written', 'already_present', 'nothing_accepted', 'skipped', 'error', 'dry_run'] as const;+export type TrailPullOutcome = (typeof TRAIL_PULL_OUTCOMES)[number];++/** The context-file kinds `trail_pulled.kinds` may name; anything else is dropped. */+export const CONTEXT_FILE_KINDS = ['claude_md', 'folder_claude_md', 'agents_md', 'cursor_rule', 'skill'] as const;+/** Where a failing build died. Coarse on purpose: enough to route a bug, not* enough to describe anyone's repo. */export const BUILD_STAGES = ['walk', 'extract', 'graph', 'summarize', 'synthesize', 'write'] as const;diff --git a/test/telemetry-contract.test.ts b/test/telemetry-contract.test.tsindex bdaf8704..af27f271 100644--- a/test/telemetry-contract.test.ts+++ b/test/telemetry-contract.test.ts@@ -75,10 +75,10 @@ test('every event carries the common properties, and no identifier beyond them',// Pinned rather than counted, so adding an event is a deliberate edit here and// a matching row in TELEMETRY.md, never something that arrives with a feature.-test('the contract lists exactly the nine documented events', () => {+test('the contract lists exactly the ten documented events', () => {assert.deepEqual(Object.keys(EVENTS).sort(), ['brain_signup_opened', 'brain_signup_settled', 'build_completed', 'build_failed',- 'first_run', 'init_completed', 'install', 'query', 'session_summary',+ 'first_run', 'init_completed', 'install', 'query', 'session_summary', 'trail_pulled',]);});@@ -210,3 +210,18 @@ test('brain signup: both events are in the contract', () => {assert.ok(EVENTS.brain_signup_opened);assert.ok(EVENTS.brain_signup_settled);});++// --- trail pull ---++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' },+ { 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.path, undefined);+});