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): hand the prompt back on the first slice of mined rules (#434)
anirudhkumar-nanonetscbe4556a7803
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bd845ee8..5ef248a3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,24 @@# Changelog+## 0.19.0++### Added++- **Push a repo's brain from the terminal** (#422): a loopback handoff hands the+ browser a finished brain instead of a half-built one — the push waits for the+ build, then lands the browser on the result.+- **A public repo can be read without installing the App** (#349): access is+ answered on its own, without first reading the repo.++### Fixed++- **The finished push lands in Trail** (#417), not on a local page, and signup+ goes to Trail's own front end rather than the shared agents host.+- **A repo read runs in a child process** so the app keeps answering while it+ works, and the digest finishes sending before the child disconnects.+- **Public reads borrow an installation token** instead of falling back to the+ anonymous rate limit.+## 0.18.0### Addeddiff --git a/package-lock.json b/package-lock.jsonindex 6c0727d2..c67910fa 100644--- a/package-lock.json+++ b/package-lock.json@@ -1,12 +1,12 @@{"name": "@nanonets/graft",- "version": "0.18.0",+ "version": "0.19.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@nanonets/graft",- "version": "0.18.0",+ "version": "0.19.0","hasInstallScript": true,"license": "MIT","dependencies": {diff --git a/package.json b/package.jsonindex 1c801d7f..0ba4b6ba 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "@nanonets/graft",- "version": "0.18.0",+ "version": "0.19.0","description": "Build a repo's context graph as a folder of linked markdown files: a local, regenerable cache that every query keeps in sync with your code.","keywords": ["ai",diff --git a/src/brain/watch.ts b/src/brain/watch.tsindex 3e36648e..0e32b8c0 100644--- a/src/brain/watch.ts+++ b/src/brain/watch.ts@@ -14,6 +14,15 @@* shows, off the same row. Ctrl-C detaches without cancelling anything, because* the work is server-side and killing a watcher must never look like killing* the build.+ *+ * What it holds the line UNTIL changed with slicing. The history is now mined in+ * several calls rather than one, and the first of them returns in about ten+ * seconds; filing all of the rules into the graph takes minutes more. Mining is+ * where the failures are — the thing this watcher exists to report — and filing+ * is long, dull and reliable, so the line is held through the first and handed+ * back before the second. Holding a terminal through five minutes of successful+ * filing buys nobody anything, and on a CI runner it is five minutes of a job+ * sitting idle.*/import type { BrainLink } from "./link.js";import { baseUrlFor } from "./link.js";@@ -47,10 +56,27 @@ export interface RepoState {ruleCount: number;commitCount: number;threadCount: number;+ /** Rules in the graph right now, from the job still running. The row's own+ * `ruleCount` is only written when that job finishes, so mid-build it is+ * zero however many rules are already there.+ *+ * Optional because an older Trail does not send it, and a graft pointed at+ * one must fall back to waiting for the finished row rather than reading a+ * missing field as "no rules". */+ filedSoFar?: number;+ /** Rules the miner has handed over so far. Grows with every slice of the+ * history that comes back, so it is a floor and never a total. */+ foundSoFar?: number;}export interface BuildView {stages: Stage[];+ /**+ * True once rules are in the graph — which is when this watcher has nothing+ * left to report, not when the job ends. The rest of the slices keep mining+ * and filing after the prompt comes back.+ */+ ready: boolean;done: boolean;/** The server's own words, when it failed. */error: string | null;@@ -71,12 +97,17 @@ export function stagesFrom(repo: RepoState | null): BuildView {const threads = num(repo?.threadCount);const rules = num(repo?.ruleCount);+ const filedSoFar = num(repo?.filedSoFar);+ const foundSoFar = num(repo?.foundSoFar);+const reached = !!repo && repo.status !== "pending";const readIt = commits > 0 || threads > 0;+ // Rules that exist, whether the job has finished writing its count or not.+ const hasRules = filedSoFar > 0 || rules > 0;const filed = rules > 0;const failed = repo?.status === "failed";- const failedAt: StageId | null = !failed ? null : !reached || !readIt ? "reach" : !filed ? "mine" : "file";+ const failedAt: StageId | null = !failed ? null : !reached || !readIt ? "reach" : !hasRules ? "mine" : "file";const order = STAGES.map((s) => s.id);const state = (id: StageId): StageState => {@@ -88,9 +119,12 @@ export function stagesFrom(repo: RepoState | null): BuildView {case "read":return readIt ? "done" : reached ? "doing" : "waiting";case "mine":- return filed ? "done" : readIt ? "doing" : "waiting";+ // Done on the first slice's rules. The remaining slices are still being+ // mined at this point, behind the prompt this watcher is about to+ // return — which is the whole change.+ return hasRules ? "done" : readIt ? "doing" : "waiting";case "file":- return filed ? "done" : readIt ? "doing" : "waiting";+ return filed ? "done" : hasRules ? "doing" : readIt ? "waiting" : "waiting";}};@@ -98,12 +132,17 @@ export function stagesFrom(repo: RepoState | null): BuildView {if (id === "read" && (commits || threads)) {return [commits ? `${commits} commits` : null, threads ? `${threads} discussions` : null].filter(Boolean).join(", ");}+ // "so far" because the count grows with each slice that lands. Printing it+ // as a total would promise history that has not been read yet.+ if (id === "mine" && foundSoFar) return `${foundSoFar} rules so far`;if (id === "file" && rules) return `${rules} rules`;+ if (id === "file" && filedSoFar) return `${filedSoFar} rules so far`;return undefined;};return {stages: STAGES.map((s) => ({ id: s.id, label: s.label, state: state(s.id), detail: detail(s.id) })),+ ready: hasRules && !failed,done: repo?.status === "completed" && filed,error: failed ? (repo?.errorMessage?.trim() || "the read stopped before it finished") : null,};@@ -125,6 +164,10 @@ export async function fetchRepoState(link: BrainLink, fetchImpl: typeof fetch =if (!res.ok) return null;const body = (await res.json()) as {repo?: { status?: string; error_message?: string; rule_count?: number; commit_count?: number; thread_count?: number } | null;+ // Absent on an older API, which is why every read of it defaults to zero:+ // a graft that cannot see the in-flight counts falls back to waiting for+ // the finished row, exactly as it did before.+ build?: { found_so_far?: number; filed_so_far?: number } | null;};if (!body.repo) return null;return {@@ -133,6 +176,8 @@ export async function fetchRepoState(link: BrainLink, fetchImpl: typeof fetch =ruleCount: num(body.repo.rule_count),commitCount: num(body.repo.commit_count),threadCount: num(body.repo.thread_count),+ filedSoFar: num(body.build?.filed_so_far),+ foundSoFar: num(body.build?.found_so_far),};} catch {return null;@@ -166,15 +211,28 @@ export interface WatchOptions {sleep?: (ms: number) => Promise<void>;}-export type WatchOutcome = "completed" | "failed" | "timed_out" | "unreachable";+/**+ * How the watch ended.+ *+ * `building` is the ordinary success: rules are in the brain and the rest of the+ * history is still being read behind the prompt. `completed` is the same thing+ * after the whole job has finished, which only happens for a repository small+ * enough to be mined in one slice.+ */+export type WatchOutcome = "completed" | "building" | "failed" | "timed_out" | "unreachable";/**- * Hold until the brain is built, printing each stage as it settles.+ * Hold until the brain has rules, printing each stage as it settles.+ *+ * Returns on the first rules rather than on the finished job: mining is what+ * fails and it is done by then, and filing the rest is minutes of work nobody+ * needs to watch. The caller prints where to see the rest.*- * Fifteen minutes by default: a large repository's mining is minutes of work,- * and a watcher that gives up before the build does would report a healthy- * build as a timeout — the exact confusion this is meant to remove. Giving up- * says so and says the work continues, because it does.+ * Fifteen minutes by default. That is far more than the mining now takes, and it+ * stays generous on purpose: a watcher that gives up before the build does would+ * report a healthy build as a timeout, which is the exact confusion this is+ * meant to remove. Giving up says so and says the work continues, because it+ * does.*/export async function watchBuild(link: BrainLink, opts: WatchOptions = {}): Promise<WatchOutcome> {const timeoutMs = opts.timeoutMs ?? 15 * 60 * 1000;@@ -200,6 +258,10 @@ export async function watchBuild(link: BrainLink, opts: WatchOptions = {}): Promreturn "failed";}if (view.done) return "completed";+ // The ordinary ending now. The job is still filing the rules the miner+ // has handed over, and still mining the older slices of the history, and+ // neither is worth a terminal sitting on it.+ if (view.ready) return "building";}if (Date.now() - startedAt >= timeoutMs) return everRead ? "timed_out" : "unreachable";await sleep(pollMs);diff --git a/src/cli.ts b/src/cli.tsindex ef4eb5d8..4ca77ff1 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -1431,6 +1431,16 @@ brainconsole.error("✓ the brain is built — its rules reach this repo on their own; nothing else to run");return;}+ // The ordinary ending for anything but a small repository. The history is+ // mined in slices, and the prompt comes back on the first of them: mining is+ // the part that fails and it has now succeeded, and the rest is filing,+ // which is minutes of reliable work nobody gains by watching. The rules+ // already in the brain are already being served.+ if (outcome === "building") {+ console.error("✓ the brain has its first rules — they reach this repo on their own; nothing else to run");+ console.error(" The rest of the history is still being read. Watch it fill in your browser.");+ return;+ }if (outcome === "failed") {// A non-zero exit, unlike every other ending here: this is the one case// where the work did not produce a brain, and a CI step that ran the pushdiff --git a/test/brain-watch.test.ts b/test/brain-watch.test.tsindex 3766680b..cbd64a85 100644--- a/test/brain-watch.test.ts+++ b/test/brain-watch.test.ts@@ -84,6 +84,16 @@ function fetchSeries(rows: (Record<string, unknown> | null)[]): typeof fetch {}) as unknown as typeof fetch;}+/** Like fetchSeries, but each entry is the whole response body, so a test can+ * carry the in-flight `build` counts the repo row does not have yet. */+function fetchBodies(bodies: Record<string, unknown>[]): typeof fetch {+ let i = 0;+ return (async () => {+ const body = bodies[Math.min(i++, bodies.length - 1)];+ return { ok: true, json: async () => body } as unknown as Response;+ }) as unknown as typeof fetch;+}+const LINK = { brainId: '8f2a1c04-0000-0000-0000-000000000000', token: 'gbt_1.sig' };const NOW = { timeoutMs: 60_000, pollMs: 0, sleep: async () => {} };@@ -151,3 +161,59 @@ test('the handoff lands on the build screen, never on an empty graph', () => {assert.ok(!url.includes('/brain/'), 'must not go to the brain route, which redirects to the graph');assert.match(url, /\/get-started\?step=build&brain=8f2a1c04-0000-0000-0000-000000000000$/);});++// --- slices: the prompt comes back on the first rules -------------------------++// The history is mined in several calls now. The first returns in about ten+// seconds and the rest keep going for minutes, so holding the terminal to the+// end would be holding it through the part that neither fails nor needs+// watching.+test('mining is finished, for this watcher, as soon as rules are in the graph', () => {+ const midBuild = row({ status: 'ingesting', commitCount: 412, threadCount: 89, ruleCount: 0, foundSoFar: 62, filedSoFar: 12 });+ assert.equal(stateOf(midBuild, 'mine'), 'done');+ assert.equal(stateOf(midBuild, 'file'), 'doing');+ assert.equal(stagesFrom(midBuild).ready, true);+ assert.equal(stagesFrom(midBuild).done, false, 'the job has not finished; only the watching has');+});++// The count grows with every slice that lands, so printing it as a total would+// promise history that has not been read yet.+test('the miner count is printed as a floor, not as a total', () => {+ const view = stagesFrom(row({ status: 'ingesting', commitCount: 412, foundSoFar: 62, filedSoFar: 12 }));+ assert.equal(view.stages.find((s) => s.id === 'mine')?.detail, '62 rules so far');+});++test('nothing placed yet is not ready, however much has been read', () => {+ const view = stagesFrom(row({ status: 'ingesting', commitCount: 412, threadCount: 89, foundSoFar: 0, filedSoFar: 0 }));+ assert.equal(view.ready, false);+ assert.equal(stateOf(row({ status: 'ingesting', commitCount: 412, foundSoFar: 0 }), 'mine'), 'doing');+});++test('the watcher hands the prompt back on the first rules, while the job runs on', async () => {+ const lines: string[] = [];+ const outcome = await watchBuild(LINK, {+ ...NOW,+ write: (l) => lines.push(l),+ fetchImpl: fetchBodies([+ { repo: { status: 'pending', rule_count: 0, commit_count: 0, thread_count: 0 } },+ { repo: { status: 'ingesting', rule_count: 0, commit_count: 412, thread_count: 89 }, build: { found_so_far: 0, filed_so_far: 0 } },+ { repo: { status: 'ingesting', rule_count: 0, commit_count: 412, thread_count: 89 }, build: { found_so_far: 62, filed_so_far: 3 } },+ ]),+ });+ assert.equal(outcome, 'building');+ assert.match(lines.join('\n'), /mining the rules — 62 rules so far/);+});++// A graft pointed at a Trail that does not send the in-flight counts must fall+// back to the old behaviour rather than read a missing field as "no rules".+test('an older API with no build counts still waits for the finished row', async () => {+ const outcome = await watchBuild(LINK, {+ ...NOW,+ write: () => {},+ fetchImpl: fetchSeries([+ { status: 'ingesting', rule_count: 0, commit_count: 412, thread_count: 89 },+ { status: 'completed', rule_count: 42, commit_count: 412, thread_count: 89 },+ ]),+ });+ assert.equal(outcome, 'completed');+});