Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(telemetry): trail_pulled event for graft trail pull (#496)

anirudhkumar-nanonetsdfc46f0b6eac
diff --git a/TELEMETRY.md b/TELEMETRY.md
index 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 by
diff --git a/src/brain/pull.ts b/src/brain/pull.ts
index 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: PullOpti
const 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: PullOpti
for (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: PullOpti
write("· 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: PullOpti
if (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: PullOpti
const 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.ts
index 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.ts
index 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);
+});