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
fix(brain): read a repository in a child process so the app keeps answering
anirudhkumar-nanonets270edcccddf7
diff --git a/src/app/brain-build-process.ts b/src/app/brain-build-process.tsnew file mode 100644index 00000000..501e1993--- /dev/null+++ b/src/app/brain-build-process.ts@@ -0,0 +1,151 @@+/**+ * Running a repository read somewhere it cannot stop the App answering.+ *+ * The same problem the reviewer had, and the same fix — see review-process.ts+ * for the full reasoning and the production measurements behind it. In short:+ * every expensive step of a read is synchronous (git through `spawnSync`, the+ * parse a loop of native tree-sitter calls, the graph written with a blocking+ * stringify), so in-process one read holds the event loop for its whole+ * duration.+ *+ * Onboarding made that visible in a way reviews did not. Measured on+ * NanoNets/assign: 0.7s to check access, 7s to clone, 81s to build the symbol+ * graph, 21s to walk the pull requests. During those 81 seconds the App+ * answered nothing at all — including the one-second question "can we see this+ * other repository", asked by the next person to paste a URL, who then waited+ * out someone else's clone before being told their repo is private. At a+ * hundred signups there is nearly always a read in flight, so that is not an+ * edge case, it is the normal case.+ *+ * The split is where the credential is: the parent resolves access and mints+ * the token (network, never blocking), and the child does the work with it.+ */+import { fork, type ChildProcess } from "node:child_process";+import { existsSync } from "node:fs";+import { fileURLToPath } from "node:url";+import { resolveRepoRead, type BrainBuildDeps, type BrainBuildJob, type BrainBuildResult } from "./brain-build.js";+import type { FromChild, StartMessage } from "./brain-build-worker.js";++/**+ * How long one read may take before the process running it is killed.+ *+ * Well above the worst honest read seen (110s on a large monorepo) plus the+ * clone budget checkout.ts allows itself, because the cost of being wrong is a+ * read that never happens. It bounds a lost slot, not responsiveness — the+ * server stopped caring how long a read takes the moment it left this process.+ */+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;++export interface ChildBuilderOptions {+ /** The module the child runs. Only tests pass this. */+ entry?: string;+ timeoutMs?: number;+}++/**+ * The module a read runs in. `dist/app/brain-build-worker.js` when installed or+ * containerised; the TypeScript source next door when run from a checkout,+ * since `fork` inherits `process.execArgv` and a parent started through tsx+ * hands the child the same loader.+ */+export function brainBuildWorkerEntry(): string {+ const js = fileURLToPath(new URL("./brain-build-worker.js", import.meta.url));+ if (existsSync(js)) return js;+ const ts = js.replace(/\.js$/, ".ts");+ return existsSync(ts) ? ts : js;+}++/** Reads in flight, so a shutdown does not leave a clone made with a token. */+const live = new Set<ChildProcess>();+let hooked = false;++function track(child: ChildProcess): void {+ live.add(child);+ if (hooked) return;+ hooked = true;+ process.on("exit", () => {+ for (const c of live) c.kill("SIGKILL");+ });+}++/**+ * A builder with buildRepoIntoBrain's signature that runs the heavy half in a+ * child process. Same shape on purpose: server.ts swaps one for the other in a+ * single line, and a test injecting its own builder keeps running in-process.+ */+export function childBuilder(opts: ChildBuilderOptions = {}): (job: BrainBuildJob, deps: BrainBuildDeps) => Promise<BrainBuildResult> {+ const entry = opts.entry ?? brainBuildWorkerEntry();+ const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;+ return async (job, deps) => {+ // In the parent, deliberately: it is pure network, it is what decides+ // whether there is anything to fork for, and a RepoNotAccessibleError has+ // to reach the caller as itself rather than as a dead child process.+ const auth = await resolveRepoRead(job, deps);+ return runInChild(job, deps, auth, entry, timeoutMs);+ };+}++async function runInChild(+ job: BrainBuildJob,+ deps: BrainBuildDeps,+ auth: Awaited<ReturnType<typeof resolveRepoRead>>,+ entry: string,+ timeoutMs: number,+): Promise<BrainBuildResult> {+ const log = deps.log ?? ((): void => {});+ const tag = `${job.owner}/${job.repo}`;+ // The repository as argv makes `ps` in a container say which read each+ // process is; the token stays out of it.+ const child = fork(entry, [tag], { stdio: ["ignore", "inherit", "inherit", "ipc"] });+ track(child);++ try {+ return await new Promise<BrainBuildResult>((resolve, reject) => {+ let settled = false;+ const settle = (fn: () => void): void => {+ if (settled) return;+ settled = true;+ clearTimeout(timer);+ fn();+ };++ const timer = setTimeout(() => {+ settle(() => reject(new Error(`read of ${tag} exceeded ${timeoutMs}ms and was killed`)));+ }, timeoutMs);+ timer.unref();++ child.on("message", (raw) => {+ const msg = raw as FromChild;+ if (msg.t === "log") {+ log(msg.msg);+ return;+ }+ if (msg.t === "done") {+ settle(() => resolve(msg.result));+ return;+ }+ settle(() => reject(new Error(msg.message)));+ });++ child.on("error", (err) => settle(() => reject(err)));++ // The case that used to be an outage: a child that dies without+ // reporting. An OOM kill on a large repository, a grammar segfault on a+ // stranger's source. Now it costs one read, named, with the signal.+ child.on("exit", (code, signal) =>+ settle(() =>+ reject(new Error(`read of ${tag} exited ${signal ? `on ${signal}` : `with code ${code}`} before reporting a result`)),+ ),+ );++ const start: StartMessage = { t: "start", job, auth, api: deps.api, githubHost: deps.githubHost };+ if (child.connected) child.send(start);+ });+ } finally {+ live.delete(child);+ if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");+ }+}++/** The App's default builder. */+export const buildRepoInChildProcess = childBuilder();diff --git a/src/app/brain-build-worker.ts b/src/app/brain-build-worker.tsnew file mode 100644index 00000000..f21dbc19--- /dev/null+++ b/src/app/brain-build-worker.ts@@ -0,0 +1,72 @@+/**+ * The process one repository read runs in.+ *+ * Forked by brain-build-process.ts, one per read, and it exits when the read+ * does. It receives the credential it needs rather than the App's private key,+ * for the same reason the reviewer's worker does: `ps` and `/proc/<pid>/environ`+ * are readable, and a key that never crosses the boundary cannot leak across it.+ *+ * Everything expensive happens here — the clone, the tree-sitter parse, the+ * pull-request walk — and none of it can reach the server's event loop.+ */+import { readRepository, type BrainBuildJob, type RepoReadAuth } from "./brain-build.js";++/** Parent → child, once, immediately after the fork. */+export interface StartMessage {+ t: "start";+ job: BrainBuildJob;+ auth: RepoReadAuth;+ api?: string;+ githubHost?: string;+}++/** Child → parent: a line for the App's log, so a read is still traceable. */+export interface LogMessage {+ t: "log";+ msg: string;+}++export interface DoneMessage {+ t: "done";+ result: Awaited<ReturnType<typeof readRepository>>;+}++export interface FailedMessage {+ t: "failed";+ message: string;+}++export type FromChild = LogMessage | DoneMessage | FailedMessage;++function send(msg: FromChild): void {+ if (!process.send) return;+ try {+ process.send(msg);+ } catch {+ /* parent went away; the exit is the report */+ }+}++process.on("message", (raw) => {+ const msg = raw as StartMessage;+ if (msg.t !== "start") return;+ void readRepository(msg.job, {+ // No creds: this half needs none. resolveRepoRead already did every call+ // that requires the App's identity, and its answer is in `auth`.+ creds: { appId: "", privateKey: "" },+ fetch: globalThis.fetch,+ api: msg.api,+ githubHost: msg.githubHost,+ log: (line: string) => send({ t: "log", msg: line }),+ }, msg.auth)+ .then((result) => {+ send({ t: "done", result });+ // The digest can be several megabytes and the channel is asynchronous, so+ // let the write drain rather than exiting out from under it.+ process.disconnect?.();+ })+ .catch((e: unknown) => {+ send({ t: "failed", message: e instanceof Error ? e.message : String(e) });+ process.disconnect?.();+ });+});diff --git a/src/app/brain-build.ts b/src/app/brain-build.tsindex 83c01c30..8b9d1094 100644--- a/src/app/brain-build.ts+++ b/src/app/brain-build.ts@@ -173,17 +173,90 @@ export async function checkRepoAccess(job: { owner: string; repo: string }, deps* both ways is one we genuinely cannot see, and that is the case the UI turns* into "read it on your machine".*/-export async function buildRepoIntoBrain(- job: BrainBuildJob,- deps: BrainBuildDeps,-): Promise<BrainBuildResult> {+/** Everything the heavy half needs, and nothing it could mint for itself. */+export interface RepoReadAuth {+ /** Installation or public-read token, for the GitHub API calls. */+ token: string;+ /** Credential for the clone. Empty for a public repository we are not+ * installed on: git serves those to anyone, and a token minted for another+ * account is not promised to work on this one. */+ cloneToken: string;+ meta: RepoMeta;+}++/**+ * Decide how this repository gets read, and mint the credential for it.+ *+ * The network half of a build, kept separate from the work: an installation+ * lookup, a token, a repository lookup. About a second, none of it blocking.+ *+ * Throws RepoNotAccessibleError when there is no way in. That is the answer the+ * onboarding UI turns into a choice, which is why it is raised here — before a+ * single byte is cloned — rather than discovered somewhere inside the read.+ */+export async function resolveRepoRead(job: BrainBuildJob, deps: BrainBuildDeps): Promise<RepoReadAuth> {+ const api = deps.api ?? "https://api.github.com";+ const tag = `${job.owner}/${job.repo}`;+ const installationId = await installationFor(deps.creds, job.owner, job.repo, deps.fetch, (deps.now ?? Date.now)(), api);+ if (installationId !== null) {+ const token = await installationToken(deps, installationId, tag, api);+ const meta = await repoMeta(job.owner, job.repo, token, deps.fetch, api);+ return { token, cloneToken: token, meta: meta ?? { isPrivate: true, defaultBranch: "" } };+ }++ // No installation on this repository. That rules out nothing yet: a public+ // repo clones with no credential at all, and its API answers to any token we+ // hold. So find a credential for the reading, then ask whether it is public.+ const token = await publicReadToken(deps, api);+ const meta = await repoMeta(job.owner, job.repo, token, deps.fetch, api);+ if (!meta || meta.isPrivate) {+ // Which of the two gaps it is decides what the UI can offer, so it is+ // resolved here rather than guessed there.+ const gap = await repoAccessGap(deps.creds, job.owner, deps.fetch, (deps.now ?? Date.now)(), api);+ throw new RepoNotAccessibleError(+ gap.reason === "repo_not_selected"+ ? `graft is installed on ${job.owner} but ${tag} is not in the list of repositories it can see`+ : `graft is not installed on ${job.owner}`,+ gap,+ );+ }+ return { token, cloneToken: "", meta };+}++/**+ * Read the repository and hand its history to the brain.+ *+ * An installation is the preferred way in: it is the only way into a private+ * repository, and it carries a rate limit worth having. It is not required for+ * a public one, though — those clone anonymously and answer the API+ * anonymously — so a failed installation lookup is a reason to try the open+ * door, not a reason to stop. Only a repository that is private or unreadable+ * both ways is one we genuinely cannot see, and that is the case the UI turns+ * into "read it on your machine".+ */+export async function buildRepoIntoBrain(job: BrainBuildJob, deps: BrainBuildDeps): Promise<BrainBuildResult> {+ return readRepository(job, deps, await resolveRepoRead(job, deps));+}++/**+ * The heavy half: clone, graph, history, digest.+ *+ * Takes its credential rather than minting one, because this is the half that+ * runs somewhere else. Every expensive thing in it is synchronous — the git+ * calls are spawnSync, the parse is a loop of native tree-sitter calls, the+ * graph is written with a blocking stringify — so in the server process it+ * holds the event loop for the whole read, and a second person pasting a URL+ * waits behind the first. See brain-build-process.ts.+ */+export async function readRepository(job: BrainBuildJob, deps: BrainBuildDeps, auth: RepoReadAuth): Promise<BrainBuildResult> {const rawLog = deps.log ?? ((): void => {});const api = deps.api ?? "https://api.github.com";const tag = `${job.owner}/${job.repo}`;+ const { token, cloneToken, meta } = auth;// Every line carries how long we have been at it. A read that feels slow is- // four things in a trench coat — the access check, the clone, the graph- // build, the pull-request walk — and without the elapsed time on each, the+ // four things in a trench coat — the clone, the graph build, the+ // pull-request walk, the digest — and without the elapsed time on each, the// only observation anyone can make is "it took two minutes".const startedAt = (deps.now ?? Date.now)();const log = (msg: string): void => rawLog(`[+${(((deps.now ?? Date.now)() - startedAt) / 1000).toFixed(1)}s] ${msg}`);@@ -192,59 +265,12 @@ export async function buildRepoIntoBrain(return () => log(`${tag}: ${name} took ${(((deps.now ?? Date.now)() - at) / 1000).toFixed(1)}s`);};- const doneAccess = phase("access check");-- const installationId = await installationFor(- deps.creds,- job.owner,- job.repo,- deps.fetch,- (deps.now ?? Date.now)(),- api,- );- // Whether the repository is private decides what the UI may show before- // signup, and the default branch is not discoverable from a shallow- // single-ref fetch (there is no origin/HEAD to resolve), so both are read- // from the API rather than guessed.- let token = "";- let cloneToken: string | null = null;- let meta: RepoMeta | null = null;- if (installationId !== null) {- token = await installationToken(deps, installationId, tag, api);- meta = await repoMeta(job.owner, job.repo, token, deps.fetch, api);- } else {- // No installation on this repository. That rules out nothing yet: a public- // repo clones with no credential at all, and its API answers to any token- // we hold. So find a credential for the reading, then ask the repo whether- // it is in fact public.- token = await publicReadToken(deps, api);- meta = await repoMeta(job.owner, job.repo, token, deps.fetch, api);- if (!meta || meta.isPrivate) {- // Which of the two gaps it is decides what the UI can offer, so it is- // resolved here rather than guessed there.- const gap = await repoAccessGap(deps.creds, job.owner, deps.fetch, (deps.now ?? Date.now)(), api);- throw new RepoNotAccessibleError(- gap.reason === "repo_not_selected"- ? `graft is installed on ${job.owner} but ${tag} is not in the list of repositories it can see`- : `graft is not installed on ${job.owner}`,- gap,- );- }- log(`${tag}: no installation, reading it as a public repository${token ? "" : " anonymously"}`);- // The clone is the one part that stays anonymous. A public repository- // serves it to anyone, and a token minted for a different account is not- // something git is promised to accept on this one.- cloneToken = "";- }- if (!meta) meta = { isPrivate: true, defaultBranch: "" };- doneAccess();-const doneClone = phase("clone");const checkout = checkoutRepository({owner: job.owner,repo: job.repo,ref: job.ref || meta.defaultBranch,- token: cloneToken ?? token,+ token: cloneToken,api: deps.githubHost,log,});diff --git a/src/app/server.ts b/src/app/server.tsindex c1bc1ad7..b23553bf 100644--- a/src/app/server.ts+++ b/src/app/server.ts@@ -21,6 +21,7 @@ import { timingSafeEqual } from "node:crypto";import { jobKey, reviewJobFor, type ReviewJob } from "./events.js";import { InstallationTokens, verifySignature, type AppCredentials, type Fetch } from "./identity.js";import { buildRepoIntoBrain, checkRepoAccess, RepoNotAccessibleError, type BrainBuildJob } from "./brain-build.js";+import { buildRepoInChildProcess } from "./brain-build-process.js";import { PageStore } from "./pages.js";import { WorkQueue } from "./queue.js";import { reviewInChildProcess } from "./review-process.js";@@ -223,7 +224,12 @@ export function createApp(// The deployment's platform URL wins over anything a caller sends, so a// request cannot redirect a repository's history to another host.if (config.brainBaseUrl) job.brainBaseUrl = config.brainBaseUrl;- const built = await (seams.brainBuild ?? buildRepoIntoBrain)(job, {+ // Out of this process by default. A read is minutes of blocking work+ // and the App has to keep answering — including the one-second access+ // question the next person's onboarding is waiting on. A test that+ // injects its own builder still runs in-process, which is what a test+ // wants.+ const built = await (seams.brainBuild ?? buildRepoInChildProcess)(job, {creds: config,fetch: fetchImpl,api: config.api,diff --git a/test/app-brain-build-process.test.ts b/test/app-brain-build-process.test.tsnew file mode 100644index 00000000..16b21122--- /dev/null+++ b/test/app-brain-build-process.test.ts@@ -0,0 +1,39 @@+/**+ * The one failure in forking a read that no protocol test would catch: the+ * entry path being wrong, or the read stack failing to load in a child.+ *+ * Everything else about the child protocol is the reviewer's, tested next door+ * in app-review-process.test.ts. What is specific here is that a deployed App+ * forks THIS module, and that importing it pulls in the same nine tree-sitter+ * native addons at graph/extract.ts's module scope. A grammar that cannot load+ * in a forked child dies during import — silently, at runtime, on every read.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { existsSync } from "node:fs";+import { fork } from "node:child_process";+import { brainBuildWorkerEntry } from "../src/app/brain-build-process.js";++const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));++test("the brain build worker is where a deployed App looks for it, and it comes up", async () => {+ const entry = brainBuildWorkerEntry();+ assert.ok(existsSync(entry), `${entry} must exist — it is what a deployed App forks`);++ const child = fork(entry, ["load-probe"], { stdio: ["ignore", "pipe", "pipe", "ipc"] });+ let stderr = "";+ child.stderr?.on("data", (c) => {+ stderr += String(c);+ });+ const ended = new Promise<string>((resolve) => {+ child.on("exit", (code, signal) => resolve(signal ? `signal ${signal}` : `code ${code}`));+ });+ try {+ // No read runs — a read wants a clone and a token. Still waiting for work+ // after this long means the stack imported cleanly, which is the assertion.+ const outcome = await Promise.race([ended, sleep(2500).then(() => "still waiting for work")]);+ assert.equal(outcome, "still waiting for work", `the brain build worker did not come up: ${stderr}`);+ } finally {+ child.kill("SIGKILL");+ }+});