Skip to content

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

feat(brain): hand the prompt back on the first slice of mined rules (#434)

anirudhkumar-nanonetscbe4556a7803
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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
### Added
diff --git a/package-lock.json b/package-lock.json
index 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.json
index 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.ts
index 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 = {}): Prom
return "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.ts
index ef4eb5d8..4ca77ff1 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -1431,6 +1431,16 @@ brain
console.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 push
diff --git a/test/brain-watch.test.ts b/test/brain-watch.test.ts
index 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');
+});