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): count the brain-push signup handoff (#418)
anirudhkumar-nanonets33d805905b01
diff --git a/TELEMETRY.md b/TELEMETRY.mdindex dcb57d75..110df85b 100644--- a/TELEMETRY.md+++ b/TELEMETRY.md@@ -46,6 +46,8 @@ The events:| `build_completed` | `files_bucket`, `langs`, `mode` (`fast`/`deep`), `duration_bucket`, `incremental` | A build succeeds || `build_failed` | `stage`, `code` — both fixed enums | A build throws || `query` | `command`, `surface` (`cli`/`mcp`/`hook`), `hit` (`ask` only) | Any query command |+| `brain_signup_opened` | — | `graft brain push` on a repo with no brain opens your browser to make one |+| `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`no_tty`/`bad_callback`), `duration_bucket` | That handoff ends, one way or the other || `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/signup.ts b/src/brain/signup.tsindex 815b96bd..6cc0e86a 100644--- a/src/brain/signup.ts+++ b/src/brain/signup.ts@@ -40,8 +40,17 @@ export const HANDOFF_TIMEOUT_MS = 5 * 60 * 1000;/** The one path the listener answers on. */export const CALLBACK_PATH = "/graft/callback";-/** What the browser sends back, or why it could not be accepted. */-export type HandoffResult = { link: BrainLink } | { error: string };+/**+ * What the browser sends back, or why it could not be accepted.+ *+ * `error` is the sentence printed to the user and `reason` is the same fact as a+ * category. They are separate because the sentence names the repo and the link,+ * so it can never be the thing telemetry reports — and matching on its text to+ * recover the category would put a user-facing string in a position where+ * rewording it silently changes what gets counted.+ */+export type HandoffFailure = "timed_out" | "bad_callback";+export type HandoffResult = { link: BrainLink } | { error: string; reason: HandoffFailure };export interface Handoff {/** The loopback port Trail must redirect to. */@@ -107,7 +116,7 @@ export async function startHandoff(): Promise<Handoff> {if (!brainId || !token) {res.writeHead(400, { "content-type": "text/html; charset=utf-8" });res.end(donePage(false));- settle({ error: "the browser came back without a brain id and token" });+ settle({ error: "the browser came back without a brain id and token", reason: "bad_callback" });return;}@@ -146,7 +155,7 @@ export async function startHandoff(): Promise<Handoff> {let timer: NodeJS.Timeout | undefined;const timeout = new Promise<HandoffResult>((resolve) => {timer = setTimeout(- () => resolve({ error: "timed out waiting for the browser — run `graft brain push` again, or use the link above" }),+ () => resolve({ error: "timed out waiting for the browser — run `graft brain push` again, or use the link above", reason: "timed_out" }),timeoutMs,);// The timer must not hold the process open once the browser has answered.diff --git a/src/cli.ts b/src/cli.tsindex cc62fdb3..5f54f856 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -1251,6 +1251,13 @@ const brain = programasync function signUpForBrain(repo: string, slug: string): Promise<BrainLink | null> {const handoff = await startHandoff();const url = signupUrl({ repo: slug, port: handoff.port, state: handoff.state });+ const startedAt = Date.now();++ // Queued before the link is printed rather than after the outcome, because+ // the outcome is the one thing a terminal handoff can lose: a user who reads+ // the URL and walks away kills the process, and only an event already on disk+ // survives that. This is the denominator; `brain_signup_settled` is not.+ track("brain_signup_opened", {}, { repo });// Printed before the browser opens, and printed whether or not it opens: on a// remote shell nothing can open, and on a desktop the window sometimes lands@@ -1262,6 +1269,10 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | n// minutes for a browser that will never come is worse than saying so now.if (!process.stderr.isTTY) {console.error("· not a terminal — open that link, then run `graft brain connect <brainId>:<token>` here");+ // Its own outcome, not a timeout: nothing here could have opened a browser,+ // so folding the two together would read as people abandoning signup when+ // it is only a remote shell doing what it has to.+ track("brain_signup_settled", { outcome: "no_tty", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });handoff.close();return null;}@@ -1272,10 +1283,13 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | nconst got = await handoff.wait();if ("error" in got) {console.error(`✗ ${got.error}`);+ // The category, never the sentence: `got.error` names the repo and the link.+ track("brain_signup_settled", { outcome: got.reason, duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });return null;}writeLink(repo, got.link);console.error(`✓ brain connected to ${slug}`);+ track("brain_signup_settled", { outcome: "linked", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });return got.link;}diff --git a/src/telemetry/contract.ts b/src/telemetry/contract.tsindex 10663153..386ef139 100644--- a/src/telemetry/contract.ts+++ b/src/telemetry/contract.ts@@ -51,6 +51,14 @@ export const EVENTS: Record<string, ReadonlySet<string>> = {build_failed: new Set<string>(['stage', 'code']),/** One query, from any surface. The DAU backbone and the dead-command detector. */query: new Set<string>(['command', 'surface', 'hit']),+ /** `graft brain push` in a repo with no brain, sending the user to Trail to+ * make one. Queued the moment the link is printed, so a signup somebody+ * walked away from is still counted — the settle below never fires for those,+ * and abandonment is exactly the thing a terminal handoff loses silently. */+ brain_signup_opened: new Set<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', 'duration_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,@@ -98,6 +106,19 @@ export function isTrackedCommand(name: string): name is TrackedCommand {return (TRACKED_COMMANDS as readonly string[]).includes(name);}+/**+ * How a `graft brain push` signup ended.+ *+ * Four categories and nothing else, because the alternative — the error string+ * the CLI already prints — carries a repo slug and a URL. `timed_out` and+ * `no_tty` are deliberately apart: one is a person who opened the browser and+ * did not finish, the other is a machine that was never able to open one, and+ * treating them alike would read as a product problem where there is only a+ * remote shell.+ */+export const BRAIN_SIGNUP_OUTCOMES = ['linked', 'timed_out', 'no_tty', 'bad_callback'] as const;+export type BrainSignupOutcome = (typeof BRAIN_SIGNUP_OUTCOMES)[number];+/** 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 a9c65200..e31a13ca 100644--- a/test/telemetry-contract.test.ts+++ b/test/telemetry-contract.test.ts@@ -73,10 +73,12 @@ test('every event carries the common properties, and no identifier beyond them',assert.match(ev.distinct_id, /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);});-test('the contract lists exactly the seven documented events', () => {+// 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', () => {assert.deepEqual(Object.keys(EVENTS).sort(), [- 'build_completed', 'build_failed', 'first_run', 'init_completed', 'install', 'query',- 'session_summary',+ 'brain_signup_opened', 'brain_signup_settled', 'build_completed', 'build_failed',+ 'first_run', 'init_completed', 'install', 'query', 'session_summary',]);});@@ -170,3 +172,40 @@ test('langsValue drops anything that is not a plain language token', () => {// Real language labels survive, including the awkward ones.assert.equal(langsValue(['c++', 'c#', 'objective-c', 'f#']), 'c#,c++,f#,objective-c');});++// --- the brain signup handoff ---++// The push handoff is the one flow that spans both products, and the outcome is+// the half that can vanish: a user who reads the URL and walks away kills the+// process. Only an event already queued survives that, which is why `opened` is+// the denominator and `settled` is not.+test('brain signup: the outcome is a category, never the sentence the user saw', () => {+ const home = sandbox('tel-brain-signup-outcome');+ const ev = track(+ 'brain_signup_settled',+ {+ outcome: 'timed_out',+ duration_bucket: durationBucket(5 * 60 * 1000),+ error: 'timed out waiting for the browser — run `graft brain push` again',+ },+ { home, env: OPEN },+ );+ assert.equal(ev?.properties.outcome, 'timed_out');+ assert.equal(ev?.properties.duration_bucket, '2-10m');+ // The printed sentence names the repo and the link, so it must not ride along+ // even when a call site passes it.+ assert.equal(ev?.properties.error, undefined);+});++test('brain signup: opened carries no properties of its own', () => {+ const home = sandbox('tel-brain-signup-opened');+ const ev = track('brain_signup_opened', { repo: 'acme/app', port: '51234' }, { home, env: OPEN });+ assert.ok(ev);+ assert.equal(ev.properties.repo, undefined);+ assert.equal(ev.properties.port, undefined);+});++test('brain signup: both events are in the contract', () => {+ assert.ok(EVENTS.brain_signup_opened);+ assert.ok(EVENTS.brain_signup_settled);+});