Skip to content

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

feat(telemetry): count the brain-push signup handoff (#418)

anirudhkumar-nanonets33d805905b01
diff --git a/TELEMETRY.md b/TELEMETRY.md
index 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 by
diff --git a/src/brain/signup.ts b/src/brain/signup.ts
index 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.ts
index cc62fdb3..5f54f856 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -1251,6 +1251,13 @@ const brain = program
async 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 | n
const 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.ts
index 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.ts
index 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);
+});