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(brain): send CLAUDE.md and the newest PRs first so suggestions start early (#466)
anirudhkumar-nanonets6d0ecc2e58c7
diff --git a/src/app/history.ts b/src/app/history.tsindex de192ba1..b2677e06 100644--- a/src/app/history.ts+++ b/src/app/history.ts@@ -169,6 +169,9 @@ export async function readThreads(fetchImpl: Fetch,api = "https://api.github.com",max = MAX_THREADS,+ // Threads already read (the early upload's newest ones), reused rather than+ // fetched a second time.+ known: ReadonlyMap<number, HistoryThread> = new Map(),): Promise<HistoryThread[]> {const headers = ghHeaders(token);@@ -197,6 +200,8 @@ export async function readThreads(const slice = candidates.slice(i, i + THREAD_FETCH_CONCURRENCY);const fetched = await Promise.all(slice.map(async (p) => {+ const seen = known.get(p.number);+ if (seen) return seen;const [issueComments, reviewComments] = await Promise.all([readComments(`${api}/repos/${owner}/${repo}/issues/${p.number}/comments`, headers, fetchImpl),readComments(`${api}/repos/${owner}/${repo}/pulls/${p.number}/comments`, headers, fetchImpl),diff --git a/src/brain/push.ts b/src/brain/push.tsindex d641cfec..9cbf5d01 100644--- a/src/brain/push.ts+++ b/src/brain/push.ts@@ -20,6 +20,7 @@ import {readCommits,readSymbols,readThreads,+ type HistoryThread,type RepoDigest,} from "../app/history.js";import {@@ -114,6 +115,8 @@ export interface ExpectedRepo {slug: string;status: string;brainName: string;+ /** The brain accepts an early upload (see pushEarlyDigest). */+ earlyUpload: boolean;}/**@@ -135,9 +138,18 @@ export async function fetchExpectedRepo(link: BrainLink, fetchImpl: typeof fetchsignal: AbortSignal.timeout(5000),});if (!res.ok) return null;- const body = (await res.json()) as { repo?: { slug?: string; status?: string } | null; brain_name?: string };+ const body = (await res.json()) as {+ repo?: { slug?: string; status?: string } | null;+ brain_name?: string;+ early_upload?: boolean;+ };if (!body.repo?.slug) return null;- return { slug: body.repo.slug, status: String(body.repo.status ?? ""), brainName: String(body.brain_name ?? "") };+ return {+ slug: body.repo.slug,+ status: String(body.repo.status ?? ""),+ brainName: String(body.brain_name ?? ""),+ earlyUpload: body.early_upload === true,+ };} catch {return null;}@@ -148,11 +160,84 @@ export function sameRepo(a: string, b: string): boolean {return a.trim().toLowerCase() === b.trim().toLowerCase();}+/** How many of the newest pull requests and commits the early upload carries —+ * what Trail's quick CLAUDE.md pass reads, and no more. */+export const EARLY_THREADS = 30;+export const EARLY_COMMITS = 80;++/**+ * The early upload: the instruction files, the newest pull requests and the+ * newest commits, read before the rest of the history.+ *+ * Reading the history is most of a push's wait — up to 200 pull requests at two+ * GitHub calls each — and Trail's first CLAUDE.md suggestions need none of it+ * beyond the newest few. Sent first, they start while the full read is still+ * going here, and the full upload that follows mines as before.+ *+ * Returns the threads it read, so the full read reuses them instead of asking+ * GitHub twice. Null when there is nothing worth sending early.+ */+export async function buildEarlyDigest(+ root: string,+ opts: { fetchImpl?: typeof fetch } = {},+): Promise<{ digest: RepoDigest; threads: HistoryThread[] } | null> {+ const slug = repoSlugFromGit(root);+ if (!slug) return null;+ const fetchImpl = opts.fetchImpl ?? fetch;+ const token = githubToken();+ // Oldest first, like the full read, so the newest are the tail.+ const commits = readCommits(root).slice(-EARLY_COMMITS);+ if (commits.length === 0) return null;+ let threads: HistoryThread[] = [];+ if (token) {+ try {+ threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never, undefined, EARLY_THREADS);+ } catch {+ threads = [];+ }+ }+ const digest = buildDigest({+ owner: slug.owner,+ name: slug.name,+ headSha: git(root, ["rev-parse", "HEAD"]) ?? "",+ defaultBranch: currentBranch(root),+ isPrivate: await isPrivate(slug.owner, slug.name, token, fetchImpl),+ commits,+ threads,+ symbols: [],+ sources: budgetSources(readAgentInstructions(root)),+ autoApprove: true,+ });+ return { digest, threads };+}++/** Send the early upload. Best-effort: false on any failure, and the full+ * upload still does everything. */+export async function pushEarlyDigest(link: BrainLink, digest: RepoDigest, fetchImpl: typeof fetch = fetch): Promise<boolean> {+ const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo?stage=early`;+ try {+ const res = await fetchImpl(url, {+ method: "POST",+ headers: {+ authorization: `Bearer ${link.token}`,+ "content-type": "application/json",+ accept: "application/json",+ },+ body: JSON.stringify(digest),+ signal: AbortSignal.timeout(15_000),+ });+ if (!res.ok) return false;+ return ((await res.json()) as { early?: boolean }).early === true;+ } catch {+ return false;+ }+}+/** Build the digest for the checkout at `root`. Reads nothing but text. */export async function buildLocalDigest(root: string,graph: GraphV1 | null,- opts: { autoApprove?: boolean; fetchImpl?: typeof fetch } = {},+ opts: { autoApprove?: boolean; fetchImpl?: typeof fetch; knownThreads?: HistoryThread[] } = {},): Promise<{ digest: RepoDigest; warning?: string } | { error: string }> {const slug = repoSlugFromGit(root);if (!slug) {@@ -171,7 +256,8 @@ export async function buildLocalDigest(let warning: string | undefined;if (token) {try {- threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never);+ const known = new Map((opts.knownThreads ?? []).map((t) => [t.number, t]));+ threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never, undefined, undefined, known);} catch {warning = "could not read pull-request discussion; mining commits and repo files only";}diff --git a/src/cli.ts b/src/cli.tsindex 4ca77ff1..c1037526 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -20,7 +20,16 @@ import { hostIds } from "./hosts/registry.js";import { parseBrainArg, connectBrain, pullBrain, brainStatus } from "./brain/connect.js";import { rulesForPointers } from "./brain/attach.js";import { clearLink, type BrainLink } from "./brain/link.js";-import { buildLocalDigest, fetchExpectedRepo, pushDigest, repoSlugFromGit, sameRepo } from "./brain/push.js";+import {+ buildEarlyDigest,+ buildLocalDigest,+ fetchExpectedRepo,+ pushDigest,+ pushEarlyDigest,+ repoSlugFromGit,+ sameRepo,+} from "./brain/push.js";+import type { HistoryThread } from "./app/history.js";import { readLink, writeLink } from "./brain/link.js";import { watchBuild } from "./brain/watch.js";import { openBrowser, signupUrl, startHandoff } from "./brain/signup.js";@@ -1392,7 +1401,23 @@ brainconst label = expected?.slug ?? (here ? `${here.owner}/${here.name}` : "this repository");console.error(`· reading ${label} — commit messages, pull-request discussion and the docs in the tree.`);console.error(" No file contents leave this machine.");- const built = await buildLocalDigest(repo, graph, { autoApprove: opts.approve !== false });+ // The instruction file and the newest pull requests go first, when the brain+ // takes them: its CLAUDE.md suggestions start from those while the rest of+ // the history is still being read here. Not awaited — the full read starts+ // at once, reusing the threads the early one already fetched.+ let early: Promise<unknown> = Promise.resolve();+ let knownThreads: HistoryThread[] = [];+ if (expected?.earlyUpload) {+ const first = await buildEarlyDigest(repo);+ if (first) {+ knownThreads = first.threads;+ early = pushEarlyDigest(link, first.digest).then((ok) => {+ if (ok) console.error("· CLAUDE.md suggestions are on their way in your browser, from the newest pull requests");+ });+ }+ }+ const built = await buildLocalDigest(repo, graph, { autoApprove: opts.approve !== false, knownThreads });+ await early;if ("error" in built) {console.error(`✗ ${built.error}`);process.exitCode = 1;diff --git a/test/brain-early-upload.test.ts b/test/brain-early-upload.test.tsnew file mode 100644index 00000000..52613dd3--- /dev/null+++ b/test/brain-early-upload.test.ts@@ -0,0 +1,73 @@+/**+ * The early upload sends the instruction file and the newest pull requests+ * before the rest of the history, so Trail's first CLAUDE.md suggestions start+ * while the full read is still on this machine. Two things make that safe, and+ * both are tested here: it is only sent to a brain that says it takes it, and+ * the full read does not ask GitHub again for threads the early one read.+ */+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { fetchExpectedRepo, pushEarlyDigest } from '../src/brain/push.js';+import { readThreads, type HistoryThread, type RepoDigest } from '../src/app/history.js';+import type { BrainLink } from '../src/brain/link.js';++const link = { brainId: 'b1', token: 'gbt_1.x', baseUrl: 'http://trail.test' } as unknown as BrainLink;++const json = (body: unknown, status = 200) =>+ new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });++// --- only to a brain that takes it -------------------------------------------++// An older Trail ignores ?stage=early and would read the partial history as a+// whole ingest, then refuse the real one as already running. So the flag is+// read, and absent means no.+test('a brain that does not say it takes the early upload is not sent one', async () => {+ const older = await fetchExpectedRepo(link, (async () => json({ repo: { slug: 'chalk/chalk', status: 'pending' } })) as typeof fetch);+ assert.equal(older?.earlyUpload, false);++ const newer = await fetchExpectedRepo(link, (async () =>+ json({ repo: { slug: 'chalk/chalk', status: 'pending' }, early_upload: true })) as typeof fetch);+ assert.equal(newer?.earlyUpload, true);+});++test('the early upload is posted with ?stage=early and reports whether Trail took it', async () => {+ let url = '';+ const took = await pushEarlyDigest(link, { owner: 'chalk', name: 'chalk' } as RepoDigest, (async (u: string) => {+ url = u;+ return json({ early: true }, 202);+ }) as typeof fetch);+ assert.equal(took, true);+ assert.match(url, /\/api\/public\/brains\/b1\/repo\?stage=early$/);++ const ignored = await pushEarlyDigest(link, {} as RepoDigest, (async () => json({ early: false }, 202)) as typeof fetch);+ assert.equal(ignored, false, 'a brain without the CLAUDE.md step accepts and ignores it');++ const refused = await pushEarlyDigest(link, {} as RepoDigest, (async () => json({ error: 'no' }, 409)) as typeof fetch);+ assert.equal(refused, false);++ const down = await pushEarlyDigest(link, {} as RepoDigest, (async () => {+ throw new Error('ECONNREFUSED');+ }) as typeof fetch);+ assert.equal(down, false, 'best-effort: the full upload still does everything');+});++// --- no second read of the same threads --------------------------------------++test('the full read reuses threads the early upload already fetched', async () => {+ const fetched: string[] = [];+ const fake = (async (u: string) => {+ fetched.push(u);+ if (u.includes('/pulls?state=closed')) {+ return json(u.includes('page=1') ? [{ number: 2, title: 'two' }, { number: 1, title: 'one' }] : []);+ }+ return json([{ body: 'use the whole test script', user: { login: 'dev', type: 'User' } }]);+ }) as never;++ const early: HistoryThread = { number: 2, title: 'two', body: '', mergeSha: '', comments: [{ body: 'from the early read' }] };+ const threads = await readThreads('chalk', 'chalk', 'tok', fake, 'https://api.test', 200, new Map([[2, early]]));++ assert.equal(threads.find((t) => t.number === 2)?.comments[0]?.body, 'from the early read');+ assert.ok(threads.some((t) => t.number === 1), 'the rest is still read');+ assert.ok(!fetched.some((u) => /\/(issues|pulls)\/2\/comments/.test(u)), 'no comment request for #2');+ assert.ok(fetched.some((u) => /\/(issues|pulls)\/1\/comments/.test(u)));+});