Skip to content

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

feat(trail): finish the sign-up when a coding agent runs graft trail push (#495)

anirudhkumar-nanonets81e92725ab08
diff --git a/TELEMETRY.md b/TELEMETRY.md
index 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 by
diff --git a/src/brain/link.ts b/src/brain/link.ts
index 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.ts
index 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.ts
index 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 | n
if (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.ts
index 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.ts
index 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 generated
diff --git a/test/brain-signup.test.ts b/test/brain-signup.test.ts
index 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 g
delete 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.ts
index 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);
});