@selesai/code 0.13.37 → 0.13.38

package/dist/extensions/jev-find-source.ts

@@ -0,0 +1,190 @@
+/**
+ * jev-find-source — the source units `jev_find` asks Jev about and returns verbatim.
+ *
+ * A unit is a line range of one file. JavaScript and TypeScript files are split with the
+ * TypeScript parser into top-level statements (consecutive imports merged, and a class or
+ * interface longer than FIND_CHUNK_LINES split into its members, each keeping the header line),
+ * each with the comments directly above it. Every other file, and a script file when the parser
+ * is not installed, is split into blank-line-separated chunks of at most FIND_CHUNK_LINES lines.
+ * Line numbers are 1-based and always the file's own: excerpts are cut from the file, never
+ * reconstructed.
+ */
+import { extname } from "node:path";
+import type * as TypeScript from "typescript";
+
+type TypeScriptApi = typeof TypeScript;
+
+/** ponytail: 40-line chunks for non-script files; raise once Jev is measured on longer units. */
+export const FIND_CHUNK_LINES = 40;
+const UNIT_NAME_CHARS = 40;
+
+export interface SourceUnit {
+	/** What the unit is: a declaration name, `Class.member`, `imports`, or the chunk's first line. */
+	name: string;
+	/** First line, 1-based, inclusive. */
+	start: number;
+	/** Last line, 1-based, inclusive. */
+	end: number;
+	/** Header line of the enclosing class or interface, kept with a member unit. */
+	header?: number;
+}
+
+let typeScript: Promise<TypeScriptApi | undefined> | undefined;
+
+/**
+ * The TypeScript compiler, or undefined when it is not installed: it is a devDependency, so a
+ * published install parses nothing and every file is chunked instead.
+ */
+export function loadTypeScript(): Promise<TypeScriptApi | undefined> {
+	typeScript ??= import("typescript").then(
+		(module: unknown) => {
+			const api = ((module as { default?: TypeScriptApi }).default ?? module) as TypeScriptApi;
+			return typeof api.createSourceFile === "function" ? api : undefined;
+		},
+		() => undefined,
+	);
+	return typeScript;
+}
+
+const SCRIPT_KINDS: Record<string, "TS" | "TSX" | "JS" | "JSX"> = {
+	".ts": "TS",
+	".tsx": "TSX",
+	".js": "JS",
+	".jsx": "JSX",
+	".mjs": "JS",
+	".cjs": "JS",
+};
+
+/** Whether `path` is split with the TypeScript parser (when it is installed). */
+export function isScriptPath(path: string): boolean {
+	return extname(path).toLowerCase() in SCRIPT_KINDS;
+}
+
+/** A file's source units in file order; `ts` undefined chunks every file. */
+export function splitSourceUnits(path: string, text: string, ts: TypeScriptApi | undefined): SourceUnit[] {
+	const kind = SCRIPT_KINDS[extname(path).toLowerCase()];
+	if (ts && kind) {
+		try {
+			const units = scriptUnits(ts, path, text, ts.ScriptKind[kind]);
+			if (units.length > 0) return units;
+		} catch {
+			// A parser crash on odd input falls back to chunks; the file is still readable.
+		}
+	}
+	return chunkUnits(text);
+}
+
+function firstLine(text: string): string {
+	const line = text.split("\n").find((row) => row.trim() !== "") ?? "";
+	return line.trim().slice(0, UNIT_NAME_CHARS);
+}
+
+function scriptUnits(ts: TypeScriptApi, path: string, text: string, kind: TypeScript.ScriptKind): SourceUnit[] {
+	const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, kind);
+	const lineOf = (pos: number) => source.getLineAndCharacterOfPosition(pos).line + 1;
+	/**
+	 * A node's first line, counting the comments directly above it: a comment separated by a blank
+	 * line (a section banner) or sitting on the previous node's last line (`a(); // note`) is not its own.
+	 */
+	const startOf = (node: TypeScript.Node, floor: number): number => {
+		let start = lineOf(node.getStart(source));
+		const comments = ts.getLeadingCommentRanges(text, node.pos) ?? [];
+		for (let i = comments.length - 1; i >= 0; i -= 1) {
+			const comment = comments[i];
+			const from = lineOf(comment.pos);
+			if (from <= floor || lineOf(comment.end) < start - 1) break;
+			start = from;
+		}
+		return start;
+	};
+	const nameOf = (node: TypeScript.Node): string => {
+		const named = (node as { name?: TypeScript.Node }).name;
+		if (named) return named.getText(source);
+		if (ts.isVariableStatement(node)) {
+			return node.declarationList.declarations.map((declaration) => declaration.name.getText(source)).join(", ");
+		}
+		if (ts.isConstructorDeclaration(node)) return "constructor";
+		if (ts.isExportAssignment(node)) return "export default";
+		return firstLine(node.getText(source));
+	};
+
+	const units: SourceUnit[] = [];
+	let floor = 0;
+	for (const statement of source.statements) {
+		const start = startOf(statement, floor);
+		const end = lineOf(statement.end);
+		floor = end;
+		if (ts.isImportDeclaration(statement) || ts.isImportEqualsDeclaration(statement)) {
+			const last = units.at(-1);
+			if (last?.name === "imports" && last.end >= start - 1) last.end = end;
+			else units.push({ name: "imports", start, end });
+			continue;
+		}
+		const container =
+			ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement) ? statement : undefined;
+		const members = container?.members;
+		if (container && members && members.length > 0 && end - start + 1 > FIND_CHUNK_LINES) {
+			const owner = nameOf(container);
+			const header = lineOf((container.name ?? container).getStart(source));
+			let memberFloor = header;
+			for (const member of members) {
+				const memberStart = startOf(member, memberFloor);
+				const memberEnd = lineOf(member.end);
+				memberFloor = memberEnd;
+				units.push({
+					name: `${owner}.${nameOf(member)}`,
+					start: memberStart,
+					end: memberEnd,
+					...(memberStart > header ? { header } : {}),
+				});
+			}
+			continue;
+		}
+		units.push({ name: nameOf(statement), start, end });
+	}
+	return units;
+}
+
+/** Blank-line-separated paragraphs packed into chunks of at most FIND_CHUNK_LINES lines. */
+export function chunkUnits(text: string): SourceUnit[] {
+	const rows = text.split("\n");
+	const paragraphs: Array<{ start: number; end: number }> = [];
+	rows.forEach((row, index) => {
+		if (row.trim() === "") return;
+		const last = paragraphs.at(-1);
+		if (last && last.end === index) last.end = index + 1;
+		else paragraphs.push({ start: index + 1, end: index + 1 });
+	});
+	const ranges: Array<{ start: number; end: number }> = [];
+	for (const paragraph of paragraphs) {
+		const current = ranges.at(-1);
+		if (current && paragraph.end - current.start + 1 <= FIND_CHUNK_LINES) {
+			current.end = paragraph.end;
+			continue;
+		}
+		// A paragraph longer than a chunk is cut into chunk-sized pieces.
+		for (let start = paragraph.start; start <= paragraph.end; start += FIND_CHUNK_LINES) {
+			ranges.push({ start, end: Math.min(paragraph.end, start + FIND_CHUNK_LINES - 1) });
+		}
+	}
+	return ranges.map((range) => ({ ...range, name: firstLine(rows[range.start - 1]) }));
+}
+
+/**
+ * Line windows around the best keyword lines (±`context` lines), merged where they overlap: the
+ * source returned when Jev could not judge a file's units. With no keyword line, the file's head.
+ */
+export function keywordWindows(lineCount: number, hits: readonly number[], context = 3, maxWindows = 3): SourceUnit[] {
+	if (lineCount <= 0) return [];
+	const anchors = [...new Set(hits.filter((line) => line >= 1 && line <= lineCount))].slice(0, maxWindows);
+	if (anchors.length === 0) return [{ name: "file head", start: 1, end: Math.min(lineCount, 2 * context + 1) }];
+	const windows: SourceUnit[] = [];
+	for (const line of anchors.sort((a, b) => a - b)) {
+		const start = Math.max(1, line - context);
+		const end = Math.min(lineCount, line + context);
+		const last = windows.at(-1);
+		if (last && start <= last.end + 1) last.end = Math.max(last.end, end);
+		else windows.push({ name: "keyword window", start, end });
+	}
+	return windows;
+}

package/dist/extensions/package.json

@@ -24,9 +24,9 @@
 			"./tokenin-onboarding.ts",
 			"./pi-graft",
 			"./undo.ts",
+			"./pi-web-agent",
 			"./pi-subagents",
 			"./pi-tool-display",
-			"./pi-web-agent",
 			"./pi-hermes-memory",
 			"./tps.ts",
 			"./capability-gateway",

package/dist/extensions/pi-subagents/agents/researcher.md

@@ -1,7 +1,7 @@
 ---
 name: researcher
 description: Autonomous web researcher — searches, evaluates, and synthesizes a focused research brief
-tools: read, write, web_search, fetch_content, get_search_content, source_check
+tools: read, write, web_explore
 thinking: medium
 systemPromptMode: replace
 inheritProjectContext: true
@@ -16,11 +16,10 @@ Given a question or topic, run focused web research and produce a concise, well-
 
 Working rules:
 - Break the problem into 2-4 distinct research angles.
-- Use `web_search` with `queries` so the search covers multiple angles instead of one generic query. Use `workflow: "none"` unless the task explicitly needs the interactive curator.
-- Treat search-result summaries as discovery aids, not final evidence for important claims. Fetch the original source when a claim is important, disputed, surprising, or decision-relevant.
+- Use `web_explore` once per research angle with a focused `query`; it handles search, fetch, and source ranking internally. Call it again with a narrower query to fill gaps.
+- Treat search-result summaries as discovery aids, not final evidence for important claims. Re-check important, disputed, surprising, or decision-relevant claims against the original source with a narrower `web_explore` query.
 - Prefer primary, official, authoritative, or directly relevant sources. Keep a smaller set of strong sources rather than many weak or redundant ones; reject stale, redundant, or SEO-heavy sources, and flag stale evidence when freshness materially affects the answer.
-- Use `source_check` against fetched source content for decision-critical or disputed claims, benchmark/performance claims, pricing/licensing claims, security claims, and wording that could materially affect a recommendation. Do not use it for every trivial fact.
-- `source_check` must be registered by the loaded provider before launch. If a registered `source_check` call fails, continue by fetching and inspecting the original source directly, and disclose the validation limitation rather than failing the research run.
+- Verify decision-critical or disputed claims, benchmark/performance claims, pricing/licensing claims, security claims, and wording that could materially affect a recommendation against the original source. Do not do this for every trivial fact. Disclose any validation limitation rather than failing the research run.
 - Label direct evidence, source interpretation, and researcher inference distinctly. Never present an inference as if the source stated it directly.
 - Record contradictions instead of silently resolving them. Record missing evidence when a claim cannot be verified.
 - Never invent dates, quotations, citations, or unsupported precision.

package/dist/extensions/pi-subagents/docs/agents.md

@@ -73,13 +73,7 @@ Native `oracle` runs inside Pi and can use its configured read tools. The Claude
 | `external-job-requests/` and `external-job-responses/` | Host-mediated provider bridge | pending request, terminal response | Host process writes a matching response and removes the request | Bridge timeout or malformed request response | Requests are operation-scoped. Recovery sends `reattach`/`result`, not `start` or `follow-up`, when job metadata exists. `start` and `follow-up` use durable dispatch claims | Provider not registered, host bridge not loaded, malformed request, provider exception, ambiguous dispatch without a provider job id |
 | Provider artifact path | External provider | provider-defined terminal artifact | Provider returns `artifactPath`, or Pi writes returned text to `external-job-<index>.result.md` | Provider reports failure or no result | Existing artifact path is retained in `status.json` | Missing artifact with no text output returns a terminal message instead of inventing content |
 
-The `researcher` builtin uses `web_search`, `fetch_content`, `get_search_content`, and selective `source_check` validation. Those require [pi-web-access](https://github.com/nicobailon/pi-web-access):
-
-```bash
-pi install npm:pi-web-access
-```
-
-The loaded provider must register all four tools, including `source_check`, before launch; a missing required tool prevents a successful run. Fetched-source inspection is a fallback for a registered `source_check` call failing, not for missing registration.
+The `researcher` builtin uses `web_explore` from the bundled `pi-web-agent` extension. Because the `tools` field is a strict allowlist, `web_explore` must be registered in the child; run `researcher` as a background child (`async: true`) so ambient extensions load.
 
 ## Overriding builtins and custom agents
 

package/dist/extensions/pi-subagents/test/unit/agent-frontmatter.test.ts

@@ -1904,7 +1904,7 @@ Do work
 				delegate: ["read", "grep", "find", "ls", "bash", "edit", "write", "contact_supervisor"],
 				reviewer: ["read", "grep", "find", "ls", "contact_supervisor"],
 				scout: ["read", "grep", "find", "ls", "bash", "write", "contact_supervisor"],
-				researcher: ["read", "write", "web_search", "fetch_content", "get_search_content", "source_check"],
+				researcher: ["read", "write", "web_explore"],
 			};
 			for (const [name, tools] of Object.entries(expectedTools)) {
 				const agent = agents.find((candidate) => candidate.name === name);
@@ -1914,12 +1914,11 @@ Do work
 
 			const researcherPrompt = agents.find((candidate) => candidate.name === "researcher")?.systemPrompt ?? "";
 			assert.match(researcherPrompt, /search-result summaries as discovery aids, not final evidence/);
-			assert.match(researcherPrompt, /source_check.*decision-critical or disputed claims/);
+			assert.match(researcherPrompt, /Verify decision-critical or disputed claims/);
 			assert.match(researcherPrompt, /direct evidence, source interpretation, and researcher inference distinctly/);
 			assert.match(researcherPrompt, /Record contradictions.*Record missing evidence/);
 			assert.match(researcherPrompt, /Never invent dates, quotations, citations, or unsupported precision/);
-			assert.match(researcherPrompt, /`source_check` must be registered by the loaded provider before launch/);
-			assert.match(researcherPrompt, /If a registered `source_check` call fails, continue/);
+			assert.match(researcherPrompt, /`web_explore`/);
 			assert.match(researcherPrompt, /\*\*Support:\*\* direct evidence \| interpretation\. \*\*Confidence:\*\* high \| medium \| low/);
 		} finally {
 			if (previousHome === undefined) delete process.env.HOME;

package/dist/extensions/pi-web-agent/src/extension.ts

@@ -1,3 +1,4 @@
+import { fileURLToPath } from 'node:url';
 import type { ExtensionAPI } from '@selesai/code';
 import { getDefaultBackendConfig, type BackendConfig } from './backends/config.js';
 import { Type } from 'typebox';
@@ -71,6 +72,16 @@ async function getEffectiveBackendConfig(pi: ExtensionAPI): Promise<BackendConfi
 export default function extension(pi: ExtensionAPI) {
   registerWebAgentConfigCommands(pi);
 
+  // Lets foreground `researcher` children load this extension (see pi-subagents builtin augmentations).
+  pi.events.on('pi-subagents:request-builtin-agent-augmentations', (request: unknown) => {
+    (request as { register?: (a: unknown) => void } | undefined)?.register?.({
+      id: 'pi-web-agent',
+      agentNames: ['researcher'],
+      addTools: ['web_explore'],
+      subagentOnlyExtensions: [fileURLToPath(import.meta.url)]
+    });
+  });
+
   const injectedWebExplore = (pi as ExtensionAPI & { __webExploreTool?: ReturnType<typeof createWebExploreTool> }).__webExploreTool;
   let cachedBackendKey: string | undefined;
   let cachedWebExplore: ReturnType<typeof createWebExploreTool> | undefined;

package/docs/settings.md

@@ -67,12 +67,14 @@ routing. The host-side routes stay off until they are enabled in `jevAdvisory`;
   of the agent's loadout before each run (it returns after `/tokenin add`, no reload needed), and a call
   that slips through reads no file and runs no command.
 
-  The same route also offers `jev_find`, a file finder: ripgrep gathers up to 48 candidate files
-  (those matching `pattern`, or every file under `path` filtered by `glob`, ranked by question words),
-  Jev judges each file's best-matching lines against the agent's `question` in parallel batches of 16,
-  and the agent gets ranked `path:lines (relevance)` pointers — never file contents. It respects
-  `.gitignore`, stays inside the working directory, skips secret-named files, and still returns the
-  unranked candidates when Jev is unavailable.
+  The same route also offers `jev_find`, a behavior finder: ripgrep gathers candidate files (those
+  matching `pattern`, or every file under `path` filtered by `glob`); on large trees Jev first judges
+  directories and descends only into relevant ones, then judges files, then the declarations (source
+  units) inside relevant files. The agent gets a ranked file list with reading leads plus the accepted
+  units verbatim with original line numbers (at most 12 Jev requests and 16 KiB of source per call).
+  It respects `.gitignore`, stays inside the working directory, skips secret-named files, retries a
+  transport failure once, and still returns ripgrep-ranked candidates with keyword-window source when
+  Jev is unavailable.
 - `subagent` — sets up a single-child `subagent` call from the parent agent (off by default). Jev only
   fills what the parent left open, and can only narrow: (1) when `agent` is omitted or generic
   (`genericAgents`, default `["delegate"]`), it picks an agent by function from enabled native agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selesai/code",
-  "version": "0.13.37",
+  "version": "0.13.38",
   "description": "Maintained, extension-first Pi coding agent with built-in workflows, subagents, web research, questions, skills, and an enhanced terminal UI.",
   "type": "module",
   "engines": {