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): finish the sign-up when a coding agent runs graft trail push (#495)
anirudhkumar-nanonets81e92725ab08
diff --git a/TELEMETRY.md b/TELEMETRY.mdindex d00fc73a..8d7ca937 100644--- a/TELEMETRY.md+++ b/TELEMETRY.md@@ -46,8 +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 trail push` on a repo with no brain opens your browser to make one |-| `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`no_tty`/`bad_callback`/`stopped`), `duration_bucket` | That handoff ends, one way or the other |+| `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 || `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/link.ts b/src/brain/link.tsindex b6992ffd..01fdb3f2 100644--- a/src/brain/link.ts+++ b/src/brain/link.ts@@ -144,6 +144,39 @@ export function baseUrlFor(link: BrainLink): string {return (process.env.GRAFT_BRAIN_URL || link.baseUrl || DEFAULT_BRAIN_BASE_URL).replace(/\/+$/, '');}+/** The API host before there is a link to read one from: signing up. */+export function apiBaseUrl(): string {+ return (process.env.GRAFT_BRAIN_URL || DEFAULT_BRAIN_BASE_URL).replace(/\/+$/, '');+}++/** A sign-up an agent-run push started and has not collected yet. */+export interface PendingSignup {+ /** The state in the link, which is what claims the trail. */+ state: string;+ /** The repository the link was for, so a changed remote starts over. */+ repo: string;+ createdAt: number;+}++/** The sign-up waiting on repo `dir`, or null when there is none or it is too+ * old to claim, or it was for a different repository. */+export function readPendingSignup(dir: string, repo: string, maxAgeMs: number, now = Date.now()): PendingSignup | null {+ const p = readBuildConfig(dir)?.pendingSignup;+ if (!p?.state || p.repo !== repo || !(now - p.createdAt < maxAgeMs)) return null;+ return p;+}++/** Save the sign-up an agent-run push just started. Git-ignored like the link,+ * because the state claims a read token. */+export function writePendingSignup(dir: string, pending: PendingSignup): void {+ patchBuildConfig(dir, { pendingSignup: pending });+ ensureGitignored(dir, join(dir, BUILD_CONFIG_DIR), LINK_NOTE);+}++export function clearPendingSignup(dir: string): void {+ patchBuildConfig(dir, { pendingSignup: undefined });+}+/** Timeout for one rules fetch. Short: `ask` must never block on this. */const FETCH_TIMEOUT_MS = 5000;diff --git a/src/brain/signup.ts b/src/brain/signup.tsindex 9f161d1e..ab2ee7b9 100644--- a/src/brain/signup.ts+++ b/src/brain/signup.ts@@ -210,18 +210,108 @@ export function reviewUrl(brainId: string, baseUrl?: string): string {return `${webBaseUrl(baseUrl)}/brain/${encodeURIComponent(brainId)}/context-files`;}-/** Where to send the browser for a repo's brain. */-export function signupUrl(opts: { repo: string; port: number; state: string; baseUrl?: string }): string {+/** Where to send the browser for a repo's brain.+ *+ * No port when an agent runs the push: nothing stays listening on loopback, so+ * Trail keeps the trail it made under `state` and graft asks for it by that. */+export function signupUrl(opts: { repo: string; port?: number; state: string; baseUrl?: string }): string {const base = webBaseUrl(opts.baseUrl);- const q = new URLSearchParams({- step: "repo",- graft_repo: opts.repo,- graft_port: String(opts.port),- graft_state: opts.state,- });+ const q = new URLSearchParams({ step: "repo", graft_repo: opts.repo });+ if (opts.port !== undefined) q.set("graft_port", String(opts.port));+ q.set("graft_state", opts.state);return `${base}/get-started?${q.toString()}`;}+/*+ * Signing up when an agent runs the push.+ *+ * Claude Code, Cursor and the rest run `graft trail push` with no terminal, and+ * show the person nothing until the command exits. A loopback listener cannot+ * work there: the link would sit unseen inside a running command, and anything+ * the browser is sent back to is gone by the time the person finishes signing+ * up. So the push runs in two short steps instead. The first opens the sign-up+ * page, saves the state it put in the link, and exits at once so the agent can+ * tell the person what to do. The next asks Trail every couple of seconds,+ * by that state, whether the sign-up has finished, and carries on with the push+ * when it has.+ */++/** A fresh state for a sign-up link: 24 random bytes, which is what Trail+ * accepts and what makes the link impossible to guess. */+export function newSignupState(): string {+ return randomBytes(24).toString("base64url");+}++/** How long one agent-run push waits for the sign-up. Under the two minutes an+ * agent gives a command by default, so the wait ends with a message it can read+ * rather than a killed process. */+export const AGENT_WAIT_MS = 90 * 1000;++/** How often it asks. */+export const AGENT_POLL_MS = 2000;++/** How long a saved state is worth asking about: a minute under the fifteen+ * Trail keeps an unclaimed sign-up, so graft never waits on one Trail dropped. */+export const PENDING_SIGNUP_TTL_MS = 14 * 60 * 1000;++/** Why asking stopped short of a link. */+export type ClaimFailure = "expired" | "unsupported";+export type ClaimResult = { link: BrainLink } | { pending: true } | { error: string; reason: ClaimFailure };++/**+ * Ask Trail once whether the sign-up for `state` has finished.+ *+ * A network error or a server error counts as "not yet": one bad request in a+ * ninety-second wait is not a reason to give up on it.+ */+export async function claimSignup(state: string, apiBase: string, fetchImpl: typeof fetch = fetch): Promise<ClaimResult> {+ let res: Response;+ try {+ res = await fetchImpl(`${apiBase}/api/public/graft-handoffs/claim`, {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({ state }),+ signal: AbortSignal.timeout(10_000),+ });+ } catch {+ return { pending: true };+ }+ if (res.status === 200) {+ const body = (await res.json().catch(() => ({}))) as { brain_id?: string; token?: string };+ if (body.brain_id && body.token) return { link: { brainId: body.brain_id, token: body.token } };+ return { pending: true };+ }+ await res.body?.cancel().catch(() => undefined);+ if (res.status === 410) {+ return { error: "that sign-up link was already used or has expired · run graft trail push again for a new one", reason: "expired" };+ }+ // An older Trail, without the route. Waiting on it would never end.+ if (res.status === 404 || res.status === 405) {+ return {+ error: "this Trail can't hand a sign-up to an agent yet · run graft trail push in a terminal, or graft trail connect <trailId>:<token>",+ reason: "unsupported",+ };+ }+ return { pending: true };+}++/** Ask until the sign-up finishes, Trail says it never will, or `timeoutMs`+ * passes — which comes back as `{ pending: true }`. */+export async function waitForSignup(+ state: string,+ apiBase: string,+ opts: { timeoutMs?: number; intervalMs?: number; fetchImpl?: typeof fetch } = {},+): Promise<ClaimResult> {+ const deadline = Date.now() + (opts.timeoutMs ?? AGENT_WAIT_MS);+ const interval = opts.intervalMs ?? AGENT_POLL_MS;+ for (;;) {+ const got = await claimSignup(state, apiBase, opts.fetchImpl);+ if (!("pending" in got)) return got;+ if (Date.now() + interval > deadline) return got;+ await new Promise((r) => setTimeout(r, interval));+ }+}+/** Open the user's browser, best effort. A machine with no opener is not an* error: the URL is printed too, and that is the fallback everywhere.*diff --git a/src/cli.ts b/src/cli.tsindex f8c661a4..d95fdb5c 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -31,10 +31,20 @@ import {sameRepo,uploadCaps,} from "./brain/push.js";-import { readLink, writeLink } from "./brain/link.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 { brainUrl, openBrowser, reviewUrl, signupUrl, startHandoff } from "./brain/signup.js";+import {+ AGENT_WAIT_MS,+ brainUrl,+ newSignupState,+ openBrowser,+ PENDING_SIGNUP_TTL_MS,+ reviewUrl,+ signupUrl,+ startHandoff,+ waitForSignup,+} from "./brain/signup.js";import { runTrailPull } from "./brain/pull.js";import { readByWired, readersOf } from "./brain/context-files.js";import { startSpinner } from "./util/spinner.js";@@ -1395,6 +1405,9 @@ const brain = program* by then, and every message says so.*/async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | null> {+ // No terminal means an agent is running this, and a loopback listener cannot+ // outlive the command it is waiting in: see signUpWithoutTerminal.+ if (!process.stderr.isTTY) return signUpWithoutTerminal(repo, slug);const handoff = await startHandoff();const url = signupUrl({ repo: slug, port: handoff.port, state: handoff.state });const startedAt = Date.now();@@ -1403,27 +1416,14 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | n// 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 });+ track("brain_signup_opened", { mode: "terminal" }, { 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// behind the terminal. The URL is the thing that always works.- // "Opening your browser" only where one is about to open.- console.error(`· ${slug} has no trail yet — ${process.stderr.isTTY ? "opening your browser to make one" : "make one at"}:`);+ console.error(`· ${slug} has no trail yet — opening your browser to make one:`);console.error(` ${url}`);- // A non-interactive shell has nobody to click anything, so waiting five- // minutes for a browser that will never come is worse than saying so now.- if (!process.stderr.isTTY) {- console.error("· not a terminal — open the link above, then run graft trail connect <trailId>:<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;- }-openBrowser(url);const spinner = startSpinner("waiting for you to finish signing up · Ctrl-C to stop");@@ -1440,22 +1440,82 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | nif (got === "stopped") {handoff.close();console.error("· stopped — nothing was sent; run graft trail push again when you're ready");- track("brain_signup_settled", { outcome: "stopped", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });+ track("brain_signup_settled", { outcome: "stopped", mode: "terminal", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });process.exitCode = 130;return null;}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 });+ track("brain_signup_settled", { outcome: got.reason, mode: "terminal", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });return null;}writeLink(repo, got.link);console.error(`✓ trail connected · ${slug} — your browser shows it building`);- track("brain_signup_settled", { outcome: "linked", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });+ track("brain_signup_settled", { outcome: "linked", mode: "terminal", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });return got.link;}+/**+ * The same sign-up when an agent runs the push, in two runs of one command.+ *+ * An agent shows the person nothing until a command exits, so the first run+ * opens the sign-up page, saves the state in its link and exits at once, with+ * a line telling the agent what to do next. The run after that finds the saved+ * state and asks Trail for the trail it made, for up to AGENT_WAIT_MS, then+ * carries on with the push. Still not signed up by then, it says so and the+ * agent runs it again. Nothing about the repository is read or sent until the+ * trail is linked.+ */+async function signUpWithoutTerminal(repo: string, slug: string): Promise<BrainLink | null> {+ const startedAt = Date.now();+ const settled = (outcome: string) =>+ track("brain_signup_settled", { outcome, mode: "agent", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });+ const pending = readPendingSignup(repo, slug, PENDING_SIGNUP_TTL_MS);++ if (!pending) {+ const state = newSignupState();+ writePendingSignup(repo, { state, repo: slug, createdAt: Date.now() });+ const url = signupUrl({ repo: slug, state });+ track("brain_signup_opened", { mode: "agent" }, { repo });+ openBrowser(url);+ console.error(`· ${slug} has no trail yet — opened Trail's sign-up page in the browser:`);+ console.error(` ${url}`);+ console.error("· nothing has been read or sent yet.");+ console.error(+ "· next: ask the user to sign up in the tab that just opened (or at the link above), then run `graft trail push` again straight away — it waits for the sign-up to finish and carries on with the push. Don't wait for them to reply first.",+ );+ settled("agent_link_opened");+ process.exitCode = 1;+ return null;+ }++ const url = signupUrl({ repo: slug, state: pending.state });+ console.error(`· waiting up to ${Math.round(AGENT_WAIT_MS / 1000)} s for the sign-up for ${slug} to finish:`);+ console.error(` ${url}`);+ const got = await waitForSignup(pending.state, apiBaseUrl());++ if ("link" in got) {+ clearPendingSignup(repo);+ writeLink(repo, got.link);+ console.error(`✓ trail connected · ${slug}`);+ settled("linked");+ return got.link;+ }+ if ("pending" in got) {+ console.error("· not signed up yet — nothing has been read or sent.");+ console.error("· next: run `graft trail push` again to keep waiting. The link above stays valid for about 15 minutes.");+ settled("still_waiting");+ process.exitCode = 1;+ return null;+ }+ clearPendingSignup(repo);+ console.error(`✗ ${got.error}`);+ settled(got.reason);+ process.exitCode = 1;+ return null;+}+brain.command("connect").description("Attach a brain to this repo and pull its rules")diff --git a/src/telemetry/contract.ts b/src/telemetry/contract.tsindex 49c09378..3b7c930e 100644--- a/src/telemetry/contract.ts+++ b/src/telemetry/contract.ts@@ -55,10 +55,10 @@ export const EVENTS: Record<string, ReadonlySet<string>> = {* 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>(),+ brain_signup_opened: new Set<string>(['mode']),/** 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']),+ brain_signup_settled: new Set<string>(['outcome', 'mode', '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,diff --git a/src/util/state.ts b/src/util/state.tsindex 3c4aec17..a83aec68 100644--- a/src/util/state.ts+++ b/src/util/state.ts@@ -107,6 +107,10 @@ export interface BuildConfig {* `~/.graft/`, because a brain belongs to one repository and two checkouts on* one machine must not share one. `undefined` clears it. */brain?: { brainId: string; token: string; baseUrl?: string };+ /** A sign-up an agent-run `graft trail push` opened and has not collected+ * yet: the state in its link, and which repository it was for. Cleared once+ * collected. `undefined` clears it. */+ pendingSignup?: { state: string; repo: string; createdAt: number };}/** Local, Git-ignored repository configuration. Kept outside generateddiff --git a/test/brain-signup.test.ts b/test/brain-signup.test.tsindex 84c0b0eb..5b55bc4c 100644--- a/test/brain-signup.test.ts+++ b/test/brain-signup.test.ts@@ -9,7 +9,11 @@*/import { test } from "node:test";import assert from "node:assert/strict";-import { CALLBACK_PATH, signupUrl, startHandoff } from "../src/brain/signup.js";+import { mkdtempSync, readFileSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { CALLBACK_PATH, claimSignup, newSignupState, signupUrl, startHandoff, waitForSignup } from "../src/brain/signup.js";+import { clearPendingSignup, readPendingSignup, writePendingSignup } from "../src/brain/link.js";/** Drive the callback the way the browser would. */async function callback(port: number, q: Record<string, string>): Promise<number> {@@ -116,3 +120,82 @@ test('the accepted handoff sends the browser to the build screen, not an empty gdelete process.env.GRAFT_BRAIN_URL;}});++// --- signing up when an agent runs the push ---++/** A fetch that answers each call with the next status in `script`. */+function scripted(script: Array<{ status: number; body?: unknown }>) {+ const calls: Array<{ url: string; body: string }> = [];+ const impl = (async (url: string | URL | Request, init?: RequestInit) => {+ calls.push({ url: String(url), body: String(init?.body ?? "") });+ const next = script[Math.min(calls.length - 1, script.length - 1)];+ return new Response(next.body === undefined ? null : JSON.stringify(next.body), { status: next.status });+ }) as typeof fetch;+ return { impl, calls };+}++test("agent signup: the link carries no port, because nothing is listening", () => {+ const url = new URL(signupUrl({ repo: "acme/app", state: "st", baseUrl: "https://trail.example" }));+ assert.equal(url.searchParams.get("graft_port"), null);+ assert.equal(url.searchParams.get("graft_repo"), "acme/app");+ assert.equal(url.searchParams.get("graft_state"), "st");+});++test("agent signup: a fresh state is long enough for Trail to accept", () => {+ // Trail refuses anything under 32 characters of base64url.+ assert.match(newSignupState(), /^[A-Za-z0-9_-]{32,128}$/);+});++test("agent signup: the state goes in the body, not the URL", async () => {+ const f = scripted([{ status: 202, body: { status: "pending" } }]);+ const got = await claimSignup("secret-state", "https://api.example", f.impl);+ assert.deepEqual(got, { pending: true });+ assert.equal(f.calls[0].url, "https://api.example/api/public/graft-handoffs/claim");+ assert.ok(!f.calls[0].url.includes("secret-state"));+ assert.deepEqual(JSON.parse(f.calls[0].body), { state: "secret-state" });+});++test("agent signup: keeps asking until the sign-up finishes, then hands back the link", async () => {+ const f = scripted([+ { status: 202, body: { status: "pending" } },+ { status: 503 },+ { status: 200, body: { brain_id: "brain-1", token: "gbt_1.sig" } },+ ]);+ const got = await waitForSignup("st", "https://api.example", { timeoutMs: 5000, intervalMs: 1, fetchImpl: f.impl });+ assert.deepEqual(got, { link: { brainId: "brain-1", token: "gbt_1.sig" } });+ assert.equal(f.calls.length, 3, "a server error in the middle is not a reason to stop");+});++test("agent signup: stops at once on a used or expired link", async () => {+ const f = scripted([{ status: 410, body: { error: "gone" } }]);+ const got = await waitForSignup("st", "https://api.example", { timeoutMs: 5000, intervalMs: 1, fetchImpl: f.impl });+ assert.ok("error" in got && got.reason === "expired");+ assert.equal(f.calls.length, 1);+});++test("agent signup: an older Trail without the route is unsupported, not an endless wait", async () => {+ const f = scripted([{ status: 404 }]);+ const got = await waitForSignup("st", "https://api.example", { timeoutMs: 5000, intervalMs: 1, fetchImpl: f.impl });+ assert.ok("error" in got && got.reason === "unsupported");+});++test("agent signup: gives up as still pending when the wait runs out", async () => {+ const f = scripted([{ status: 202, body: { status: "pending" } }]);+ const got = await waitForSignup("st", "https://api.example", { timeoutMs: 30, intervalMs: 10, fetchImpl: f.impl });+ assert.deepEqual(got, { pending: true });+});++test("agent signup: the saved state is for one repo, for a while, and git-ignored", () => {+ const dir = mkdtempSync(join(tmpdir(), "graft-pending-"));+ try {+ writePendingSignup(dir, { state: "st", repo: "acme/app", createdAt: 1_000 });+ assert.equal(readPendingSignup(dir, "acme/app", 60_000, 2_000)?.state, "st");+ assert.equal(readPendingSignup(dir, "acme/other", 60_000, 2_000), null, "a different remote starts over");+ assert.equal(readPendingSignup(dir, "acme/app", 60_000, 70_000), null, "too old to claim");+ assert.match(readFileSync(join(dir, ".gitignore"), "utf8"), /\.graft/);+ clearPendingSignup(dir);+ assert.equal(readPendingSignup(dir, "acme/app", 60_000, 2_000), null);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});diff --git a/test/telemetry-contract.test.ts b/test/telemetry-contract.test.tsindex cd5886cb..bdaf8704 100644--- a/test/telemetry-contract.test.ts+++ b/test/telemetry-contract.test.ts@@ -197,10 +197,11 @@ test('brain signup: the outcome is a category, never the sentence the user saw',assert.equal(ev?.properties.error, undefined);});-test('brain signup: opened carries no properties of its own', () => {+test('brain signup: opened carries only whether an agent ran it', () => {const home = sandbox('tel-brain-signup-opened');- const ev = track('brain_signup_opened', { repo: 'acme/app', port: '51234' }, { home, env: OPEN });+ const ev = track('brain_signup_opened', { mode: 'agent', repo: 'acme/app', port: '51234' }, { home, env: OPEN });assert.ok(ev);+ assert.equal(ev.properties.mode, 'agent');assert.equal(ev.properties.repo, undefined);assert.equal(ev.properties.port, undefined);});