pi-ast-sgrep 2.2.0 → 2.5.2

package/dist/codemode/connector.d.ts

@@ -1,6 +1,6 @@
 import type { MachineEnvelope } from "../runtime/runtime.js";
-import type { ChainArgs, EditArgs, FindArgs, ReadArgs, SearchArgs } from "./types.js";
 import { type BatchCapableHost, type DispatchCall, type DispatchStats } from "./dispatch.js";
+import type { ChainArgs, EditArgs, FindArgs, ReadArgs, SearchArgs } from "./types.js";
 /**
  * Spawn/CLI transport. Hosts provide argv `run` only — never a typed twin.
  * Typed entry lives solely on {@link DispatchSurface} (dispatcher output).

package/dist/codemode/connector.js

@@ -1,7 +1,15 @@
+import { argvFor, asEnvelope, createCodemodeDispatcher, } from "./dispatch.js";
+import { editFilesFallback, readWindowsFallback } from "./fallback.js";
 import { coerceHostArgs } from "./guest-api.js";
 import { defined } from "./types.js";
-import { createCodemodeDispatcher, } from "./dispatch.js";
 const DEFAULT_LIMIT = 8;
+/** Native tools the extension serves itself when the launcher predates them. */
+const NATIVE_FALLBACK_TOOLS = new Set(["read", "edit", "find"]);
+/** Stable unknown-tool prefix, byte-identical in every native generation. */
+function isUnknownToolError(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return message.includes("unknown tool:");
+}
 function clampLimit(limit) {
     if (limit === undefined)
         return DEFAULT_LIMIT;
@@ -58,7 +66,35 @@ export function createAsgrepConnector(host, context, options = {}) {
         }
         return { signal: combined };
     };
-    const call = (tool, args, signal) => dispatcher.host.call(tool, args, context, callOptions(signal));
+    // Unknown-tool fallback engages once per tool: after the first miss the
+    // native attempt is skipped for this bundle (a backend cannot gain tools
+    // mid-session). Any other error still propagates untouched, unmemoized.
+    const nativeMissing = new Set();
+    const fallbackCall = async (tool, args, signal) => {
+        if (tool === "find")
+            return host.run(argvFor("find", args), context, signal === undefined ? {} : { signal });
+        const value = tool === "read"
+            ? await readWindowsFallback(context.cwd, args, signal)
+            : await editFilesFallback(context.cwd, args, signal);
+        return asEnvelope(value, tool);
+    };
+    const call = async (tool, args, signal) => {
+        const opts = callOptions(signal);
+        if (NATIVE_FALLBACK_TOOLS.has(tool) && nativeMissing.has(tool))
+            return fallbackCall(tool, args, opts.signal);
+        try {
+            return await dispatcher.host.call(tool, args, context, opts);
+        }
+        catch (cause) {
+            // No memo check here: concurrent same-tool misses must all fall back —
+            // the memo only skips future native attempts, never a fresh miss.
+            if (NATIVE_FALLBACK_TOOLS.has(tool) && isUnknownToolError(cause)) {
+                nativeMissing.add(tool);
+                return fallbackCall(tool, args, opts.signal);
+            }
+            throw cause;
+        }
+    };
     const searchPayload = (method, input) => {
         const scoped = coerceHostArgs(method, withScope({ ...input }));
         const payload = {

package/dist/codemode/fallback.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Extension-side read/edit for launchers that predate the native tools.
+ *
+ * Severed-lane contract: when native answers `unknown tool: <name>` for
+ * read/edit/find, the connector serves the call here instead of failing, so
+ * an extension tracking main keeps working on an official launcher. Every
+ * shape, default, cap, jail rule, and error string mirrors
+ * crates/ast-sgrep-codemode/src/io.rs exactly — callers cannot distinguish
+ * this lane from a native one. Errors are plain Errors carrying the native
+ * text (the native lane surfaces them the same way); no new error codes.
+ *
+ * Deliberate divergences from native, both strictly safer:
+ * - Reads come from disk, never the index (the extension has no row reader
+ *   here). Disk is fresher than a possibly stale index row.
+ * - Edits skip the native targeted reindex. A fallback edit is exactly like
+ *   an external editor write, which the freshness layer already reconciles.
+ */
+/** Mirror read_windows (disk-backed; see module note). */
+export declare function readWindowsFallback(configuredCwd: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<{
+    ok: true;
+    count: number;
+    windows: Array<{
+        path: string;
+        ref: string;
+        start: number;
+        end: number;
+        truncated: boolean;
+        text: string;
+    }>;
+}>;
+/** Mirror edit_files (validate-all-then-write; no targeted reindex — freshness covers). */
+export declare function editFilesFallback(configuredCwd: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<{
+    ok: true;
+    changed: number;
+    edits: Array<{
+        path: string;
+        changed: boolean;
+        line: number;
+        removed: string[];
+        added: string[];
+        truncated?: true;
+    }>;
+}>;

package/dist/codemode/fallback.js

@@ -0,0 +1,303 @@
+/**
+ * Extension-side read/edit for launchers that predate the native tools.
+ *
+ * Severed-lane contract: when native answers `unknown tool: <name>` for
+ * read/edit/find, the connector serves the call here instead of failing, so
+ * an extension tracking main keeps working on an official launcher. Every
+ * shape, default, cap, jail rule, and error string mirrors
+ * crates/ast-sgrep-codemode/src/io.rs exactly — callers cannot distinguish
+ * this lane from a native one. Errors are plain Errors carrying the native
+ * text (the native lane surfaces them the same way); no new error codes.
+ *
+ * Deliberate divergences from native, both strictly safer:
+ * - Reads come from disk, never the index (the extension has no row reader
+ *   here). Disk is fresher than a possibly stale index row.
+ * - Edits skip the native targeted reindex. A fallback edit is exactly like
+ *   an external editor write, which the freshness layer already reconciles.
+ */
+import { readFile, realpath, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
+import { pathContained } from "../runtime/index-health.js";
+// Native caps (crates/ast-sgrep-codemode/src/io.rs + core limits).
+const MAX_READ_REFS = 32;
+const MAX_READ_CHARS = 100_000;
+const MAX_EDITS = 16;
+const MAX_LINE_CHARS = 2_000;
+const MAX_INDEX_FILE_BYTES = 64 * 1024 * 1024;
+const MAX_EXCERPT_LINES = 100;
+const U32_MAX = 4_294_967_295;
+/** Mirror serde as_u64 (integers only, then wrapping `as u32`). */
+function u32(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > Number.MAX_SAFE_INTEGER)
+        return undefined;
+    return value % (U32_MAX + 1);
+}
+/** Mirror serde as_u64 without narrowing (context/max budgets). */
+function u64(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > Number.MAX_SAFE_INTEGER)
+        return undefined;
+    return value;
+}
+/** First present key wins even when its value is unusable (or_else chain). */
+function present(args, ...keys) {
+    for (const key of keys)
+        if (key in args)
+            return args[key];
+    return undefined;
+}
+/** Mirror str::lines: \n or \r\n separators, no phantom trailing line. */
+function rustLines(text) {
+    if (text === "")
+        return [];
+    const lines = text.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+    if (text.endsWith("\n"))
+        lines.pop();
+    return lines;
+}
+function charCount(text) {
+    return [...text].length;
+}
+function clampLine(line) {
+    if (charCount(line) <= MAX_LINE_CHARS)
+        return { line, clamped: false };
+    return { line: [...line].slice(0, MAX_LINE_CHARS).join(""), clamped: true };
+}
+/** Mirror session root_arg: configured root, optional contained override. */
+async function jailRoot(configuredCwd, args) {
+    const configured = await realpath(configuredCwd).catch(() => {
+        throw new Error(`cannot resolve session root: ${configuredCwd}`);
+    });
+    const raw = args.root;
+    if (typeof raw !== "string")
+        return configured;
+    const candidate = isAbsolute(raw) ? raw : join(configured, raw);
+    const resolved = await realpath(candidate).catch(() => {
+        throw new Error(`cannot resolve requested root: ${candidate}`);
+    });
+    if (!pathContained(configured, resolved)) {
+        throw new Error(`requested root is outside the configured session root: ${resolved}`);
+    }
+    return resolved;
+}
+/** Mirror jail_rel_path: explicit '..' rejection, canonicalize, containment. */
+async function jailPath(root, raw) {
+    if (raw.split(/[\\/]/u).includes(".."))
+        throw new Error("path must not contain '..'");
+    const candidate = isAbsolute(raw) ? raw : join(root, raw);
+    const abs = await realpath(candidate).catch(() => {
+        throw new Error(`cannot resolve path ${raw}`);
+    });
+    if (!pathContained(root, abs))
+        throw new Error(`path escapes session root: ${raw}`);
+    return { abs, display: relative(root, abs).replace(/\\/g, "/") };
+}
+function parseU32Strict(text) {
+    const digits = /^(?:\+)?(\d+)$/.exec(text)?.[1];
+    if (digits === undefined)
+        return undefined;
+    const value = Number(digits);
+    return Number.isSafeInteger(value) && value <= U32_MAX ? value : undefined;
+}
+function parseRefString(raw) {
+    const hash = raw.lastIndexOf("#L");
+    if (hash === -1)
+        return { path: raw, start: 1, end: 40 };
+    const rest = raw.slice(hash + 2).trim();
+    const dash = rest.indexOf("-L");
+    const startText = dash === -1 ? rest : rest.slice(0, dash);
+    const endText = dash === -1 ? rest : rest.slice(dash + 2);
+    const start = parseU32Strict(startText);
+    if (start === undefined)
+        throw new Error(`invalid ref start in ${raw}`);
+    const end = parseU32Strict(endText);
+    if (end === undefined)
+        throw new Error(`invalid ref end in ${raw}`);
+    if (start === 0 || end < start)
+        throw new Error(`invalid ref range in ${raw}`);
+    return { path: raw.slice(0, hash), start, end };
+}
+function parseRefValue(value) {
+    if (typeof value === "string")
+        return parseRefString(value);
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("ref must be a string or object");
+    const obj = value;
+    if (typeof obj.ref === "string")
+        return parseRefString(obj.ref);
+    const path = present(obj, "path", "file");
+    if (typeof path !== "string")
+        throw new Error("ref.path is required");
+    const start = u32(present(obj, "start", "line_start")) ?? 1;
+    const end = u32(present(obj, "end", "line_end")) ?? start;
+    return { path, start: Math.max(1, start), end: Math.max(start, end) };
+}
+function collectRefs(args) {
+    if (Array.isArray(args.refs))
+        return args.refs.map(parseRefValue);
+    if (args.ref !== undefined)
+        return [parseRefValue(args.ref)];
+    const path = present(args, "path", "file");
+    if (typeof path !== "string")
+        throw new Error("path is required");
+    const start = u32(present(args, "start", "line_start")) ?? 1;
+    const end = u32(present(args, "end", "line_end")) ?? start;
+    return [{ path, start: Math.max(1, start), end: Math.max(start, end) }];
+}
+function sliceWindow(numbered, start, end, maxChars) {
+    let out = "";
+    let actualStart = start;
+    let actualEnd = start;
+    let first = true;
+    let truncated = false;
+    let chars = 0;
+    for (const [no, content] of numbered) {
+        if (no < start)
+            continue;
+        if (no > end)
+            break;
+        const { line, clamped } = clampLine(content);
+        if (clamped)
+            truncated = true;
+        const add = (first ? 0 : 1) + charCount(line);
+        if (chars + add > maxChars) {
+            truncated = true;
+            break;
+        }
+        if (first) {
+            actualStart = no;
+            first = false;
+        }
+        if (out !== "")
+            out += "\n";
+        out += line;
+        actualEnd = no;
+        chars += add;
+    }
+    if (first)
+        return { text: "", actualStart: start, actualEnd: start, truncated: false };
+    return { text: out, actualStart, actualEnd, truncated };
+}
+async function readFileCapped(abs, display, signal) {
+    const text = await readFile(abs, "utf8").catch(() => {
+        throw new Error(`cannot read ${display}`);
+    });
+    if (Buffer.byteLength(text) > MAX_INDEX_FILE_BYTES)
+        throw new Error(`${display} exceeds max ${MAX_INDEX_FILE_BYTES} bytes`);
+    signal?.throwIfAborted();
+    return text;
+}
+/** Mirror read_windows (disk-backed; see module note). */
+export async function readWindowsFallback(configuredCwd, args, signal) {
+    signal?.throwIfAborted();
+    const root = await jailRoot(configuredCwd, args);
+    const contextLines = Math.min(u64(present(args, "context_lines", "contextLines")) ?? 0, MAX_EXCERPT_LINES);
+    const maxChars = Math.min(Math.max(u64(present(args, "max_chars", "maxChars")) ?? MAX_READ_CHARS, 1), MAX_READ_CHARS);
+    const refs = collectRefs(args);
+    if (refs.length === 0)
+        throw new Error("read requires path, ref, or refs");
+    if (refs.length > MAX_READ_REFS)
+        throw new Error(`read exceeds max ${MAX_READ_REFS} windows`);
+    const windows = [];
+    for (const spec of refs) {
+        signal?.throwIfAborted();
+        const { abs, display } = await jailPath(root, spec.path);
+        const text = await readFileCapped(abs, display, signal);
+        const numbered = rustLines(text).map((line, index) => [index + 1, line]);
+        const start = Math.max(1, spec.start - contextLines);
+        const end = Math.min(spec.end + contextLines, U32_MAX);
+        const slice = sliceWindow(numbered, start, end, maxChars);
+        windows.push({
+            path: display,
+            ref: `${display}#L${slice.actualStart}-L${slice.actualEnd}`,
+            start: slice.actualStart,
+            end: slice.actualEnd,
+            truncated: slice.truncated,
+            text: slice.text,
+        });
+    }
+    return { ok: true, count: windows.length, windows };
+}
+function parseEditValue(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("edit must be an object");
+    const obj = value;
+    const path = present(obj, "path", "file");
+    if (typeof path !== "string")
+        throw new Error("path is required");
+    const oldText = present(obj, "oldText", "old_string", "old");
+    if (typeof oldText !== "string")
+        throw new Error("oldText is required");
+    const newText = present(obj, "newText", "new_string", "new");
+    if (typeof newText !== "string")
+        throw new Error("newText is required");
+    if (oldText === "")
+        throw new Error("oldText must not be empty");
+    return { path, oldText, newText };
+}
+function collectEdits(args) {
+    if (Array.isArray(args.edits))
+        return args.edits.map(parseEditValue);
+    if (typeof args.path === "string")
+        return [parseEditValue(args)];
+    return [];
+}
+function diffLines(text) {
+    const all = rustLines(text);
+    return { lines: all.slice(0, 24), more: all.length > 24 };
+}
+function matchLine(buffer, offset) {
+    return buffer.slice(0, offset).split("\n").length;
+}
+/** Mirror edit_files (validate-all-then-write; no targeted reindex — freshness covers). */
+export async function editFilesFallback(configuredCwd, args, signal) {
+    signal?.throwIfAborted();
+    const root = await jailRoot(configuredCwd, args);
+    const edits = collectEdits(args);
+    if (edits.length === 0)
+        throw new Error("edit requires path+oldText+newText or edits[]");
+    if (edits.length > MAX_EDITS)
+        throw new Error(`edit exceeds max ${MAX_EDITS} replacements`);
+    // Phase 1: resolve, read, and compute every rewrite before any write.
+    const plan = new Map();
+    const applied = [];
+    for (const edit of edits) {
+        signal?.throwIfAborted();
+        const { abs, display } = await jailPath(root, edit.path);
+        let entry = plan.get(display);
+        if (!entry) {
+            const original = await readFileCapped(abs, display, signal);
+            entry = { abs, display, original, rewritten: original };
+            plan.set(display, entry);
+        }
+        const first = entry.rewritten.indexOf(edit.oldText);
+        if (first === -1)
+            throw new Error("oldText must match exactly once (found 0)");
+        if (entry.rewritten.indexOf(edit.oldText, first + edit.oldText.length) !== -1) {
+            throw new Error("oldText must match exactly once (found 2+)");
+        }
+        const line = matchLine(entry.rewritten, first);
+        const next = entry.rewritten.slice(0, first) + edit.newText + entry.rewritten.slice(first + edit.oldText.length);
+        const changed = next !== entry.rewritten;
+        entry.rewritten = next;
+        const removed = diffLines(edit.oldText);
+        const added = diffLines(edit.newText);
+        applied.push({
+            path: display,
+            changed,
+            line,
+            removed: removed.lines,
+            added: added.lines,
+            ...(removed.more || added.more ? { truncated: true } : {}),
+        });
+    }
+    // Phase 2: every edit validated — write each touched file once.
+    for (const entry of plan.values()) {
+        if (entry.rewritten === entry.original)
+            continue;
+        signal?.throwIfAborted();
+        await writeFile(entry.abs, entry.rewritten).catch(() => {
+            throw new Error(`cannot write ${entry.display}`);
+        });
+    }
+    return { ok: true, changed: applied.filter((row) => row.changed).length, edits: applied };
+}

package/dist/codemode/native.d.ts

@@ -8,8 +8,12 @@
  * 1. `ASGREP_CODEMODE_NAPI_PATH` (dev override)
  * 2. `@ast-sgrep/<platform>/ast-sgrep-codemode.node` via launcher (release install)
  * 3. Local `extension/native/` / cargo `target/release` (dev builds)
+ *
+ * Severed-lane policy: the in-process binding requires an exact native
+ * generation (an ABI mismatch risks crashes, not errors). Older launchers
+ * serve Code Mode over CLI sticky/batch/spawn instead — same tools, slower.
  */
-export declare const CODEMODE_BINDING_VERSION = "2.1.0";
+export declare const CODEMODE_BINDING_VERSION = "2.5.2";
 export type NativeSessionConfig = {
     root?: string;
     indexPath?: string;

package/dist/codemode/native.js

@@ -8,12 +8,16 @@
  * 1. `ASGREP_CODEMODE_NAPI_PATH` (dev override)
  * 2. `@ast-sgrep/<platform>/ast-sgrep-codemode.node` via launcher (release install)
  * 3. Local `extension/native/` / cargo `target/release` (dev builds)
+ *
+ * Severed-lane policy: the in-process binding requires an exact native
+ * generation (an ABI mismatch risks crashes, not errors). Older launchers
+ * serve Code Mode over CLI sticky/batch/spawn instead — same tools, slower.
  */
 import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-export const CODEMODE_BINDING_VERSION = "2.1.0";
+export const CODEMODE_BINDING_VERSION = "2.5.2";
 let cached;
 function platformTriple() {
     const { platform, arch } = process;

package/dist/host/tools.d.ts

@@ -13,7 +13,7 @@ export declare const DEFAULT_LIMIT = 8;
  * session, or a host that drops the built-ins still gets them — but they are
  * left out of the active set when the host already provides read+edit. Pi only
  * sends ACTIVE tools (schema, snippet, guidelines) to the model, so this is the
- * difference between ~296 tokens per request and nothing.
+ * difference between ~271 tokens per request and nothing.
  *
  * ASGREP_KEEP_FILE_TOOLS=1 pins them active regardless.
  */

package/dist/host/tools.js

@@ -4,22 +4,21 @@ import { Type } from "typebox";
 import { createAsgrepConnector, runCodemode, runNativeBatch, runBatchViaStdin, CODEMODE_TYPES_FOR_MODEL, NativeSessionPool, argvFor, asEnvelope, applyQueryScope, warmCodemodeSandbox, resetCodemodeSandboxForTests, isClosedWorkerError, } from "../codemode/index.js";
 import { AstSgrepRuntime, FreshnessCoordinator, RuntimeError } from "../runtime/runtime.js";
 import { RESOLVED_ROOT } from "../runtime/types.js";
-import { ASGREP_PROMPT_GUIDELINES, ASGREP_PROMPT_SNIPPET, formatCodemodeResult, } from "../ui/present.js";
+import { ASGREP_PROMPT_GUIDELINES, ASGREP_PROMPT_GUIDELINES_HOST_FILES, ASGREP_PROMPT_SNIPPET, formatCodemodeResult, } from "../ui/present.js";
 import { EMPTY_CALL, renderAsgrepResult } from "../ui/card.js";
 import { bounded, errorDetails, failure, isFreshnessTimeout, extractInPath, report, success, } from "./results.js";
 export const DEFAULT_LIMIT = 8;
 const MAX_LIMIT = 100;
 const MAX_EXCERPT_LINES = 100;
 const searchParameters = Type.Object({
-    query: Type.String({ maxLength: 4_096, description: "Query, symbol, or pattern" }),
+    query: Type.String({ maxLength: 4_096 }),
     mode: Type.Optional(Type.Unsafe({
         type: "string",
         enum: ["natural", "pattern", "defs", "callers", "chain", "semantic", "word", "literal", "regex", "imports"],
         default: "natural",
-        description: "Search strategy",
     })),
     limit: Type.Optional(Type.Integer({ default: DEFAULT_LIMIT })),
-    excerptLines: Type.Optional(Type.Integer({ default: 0, description: "Inline N excerpt lines per hit" })),
+    excerptLines: Type.Optional(Type.Integer({ default: 0 })),
     in: Type.Optional(Type.String({ maxLength: 512, description: "Bound to a directory or glob" })),
     lang: Type.Optional(Type.String({ maxLength: 32, description: "Language filter (rs, ts, py)" })),
 }, { additionalProperties: false });
@@ -27,9 +26,9 @@ const indexParameters = Type.Object({
     force: Type.Optional(Type.Boolean({ default: false, description: "Rebuild the index from scratch" })),
 }, { additionalProperties: false });
 const editParameters = Type.Object({
-    path: Type.Optional(Type.String({ maxLength: 512, description: "File to edit" })),
+    path: Type.Optional(Type.String({ maxLength: 512 })),
     oldText: Type.Optional(Type.String({ description: "Exact text to replace (must match once)" })),
-    newText: Type.Optional(Type.String({ description: "Replacement" })),
+    newText: Type.Optional(Type.String()),
     edits: Type.Optional(Type.Array(Type.Object({
         path: Type.Optional(Type.String({ minLength: 1, maxLength: 512 })),
         oldText: Type.String({ minLength: 1 }),
@@ -37,7 +36,7 @@ const editParameters = Type.Object({
     }), { maxItems: 64, description: "Multi-edit entries; top-level path is the default" })),
 }, { additionalProperties: false });
 const readParameters = Type.Object({
-    path: Type.Optional(Type.String({ maxLength: 512, description: "File to read" })),
+    path: Type.Optional(Type.String({ maxLength: 512 })),
     ref: Type.Optional(Type.String({ description: "Hit ref path#L12-L40" })),
     refs: Type.Optional(Type.Array(Type.String(), { maxItems: 24, description: "Several refs in one call" })),
     start: Type.Optional(Type.Integer()),
@@ -49,7 +48,7 @@ const codemodeParameters = Type.Object({
     code: Type.String({
         minLength: 1,
         maxLength: 32_000,
-        description: "JavaScript: async () => { ... } or a bare body with return. The returned value is the tool result.",
+        description: "JavaScript: async () => { ... } or a bare body with return.",
     }),
     timeoutMs: Type.Optional(Type.Integer({ description: "Timeout ms (default 30000)" })),
 }, { additionalProperties: false });
@@ -84,7 +83,7 @@ function withSearchLang(argv, lang) {
  * session, or a host that drops the built-ins still gets them — but they are
  * left out of the active set when the host already provides read+edit. Pi only
  * sends ACTIVE tools (schema, snippet, guidelines) to the model, so this is the
- * difference between ~296 tokens per request and nothing.
+ * difference between ~271 tokens per request and nothing.
  *
  * ASGREP_KEEP_FILE_TOOLS=1 pins them active regardless.
  */
@@ -518,10 +517,10 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
         name: "asgrep",
         label: "asgrep",
         promptSnippet: ASGREP_PROMPT_SNIPPET,
-        promptGuidelines: [...ASGREP_PROMPT_GUIDELINES],
+        promptGuidelines: [...(hostProvidesFileTools(pi) ? ASGREP_PROMPT_GUIDELINES_HOST_FILES : ASGREP_PROMPT_GUIDELINES)],
         description: [
-            "Code search (in-process, warm Searcher): use it for any code lookup instead of grep.",
-            "Write JavaScript; the returned value is your result.",
+            "Code search: use it for any code lookup instead of grep.",
+            "The returned value is your result.",
             CODEMODE_TYPES_FOR_MODEL,
             "Example: async () => (await asgrep.search(\"auth\", { limit: 5 })).hits",
         ].join("\n"),
@@ -608,7 +607,7 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
     pi.registerTool({
         name: "asgrep_search",
         label: "asgrep search",
-        promptSnippet: "One-shot asgrep search",
+        promptSnippet: "One-shot search",
         description: "One-shot search. Use asgrep (Code Mode) for anything multi-step, parallel, or filtered.",
         parameters: searchParameters,
         renderShell: "self",
@@ -675,7 +674,7 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
         name: "asgrep_edit",
         label: "asgrep edit",
         promptSnippet: "Exact-string edit",
-        description: "Edit by exact-string replace; oldText must match once. edits[] applies many atomically.",
+        description: "Edit by exact-string replace. edits[] applies many atomically.",
         parameters: editParameters,
         renderShell: "self",
         renderCall() {
@@ -735,7 +734,7 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
         name: "asgrep_index",
         label: "asgrep index",
         promptSnippet: "Build or rebuild the index",
-        description: "Build or rebuild the index (embeddings included).",
+        description: "Build or rebuild the index.",
         parameters: indexParameters,
         renderShell: "self",
         renderCall() {

package/dist/runtime/runtime.js

@@ -47,10 +47,26 @@ function getBinary(config, env, resolver) {
     return binary;
 }
 function byteLength(value) { return Buffer.byteLength(value, "utf8"); }
-/** Present-field version identity checks. Pass `requireIdentity` for version --json. */
+/**
+ * Binary-generation check. The extension tracks main ahead of official
+ * launcher releases (severed lane), so any binary of the same major is
+ * accepted: features gate on envelope content and the index negotiates its
+ * schema with the binary. A different major or an unparseable version still
+ * fails closed, as does a missing version when identity is required.
+ */
+function binaryMajor(version) {
+    if (typeof version !== "string")
+        return undefined;
+    const major = version.match(/^(\d+)\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/)?.[1];
+    return major === undefined ? undefined : Number(major);
+}
+// RUNTIME_VERSION is contract-pinned semver, so this is total. A malformed
+// constant (-1) would reject every binary — fail closed.
+const RUNTIME_MAJOR = binaryMajor(RUNTIME_VERSION) ?? -1;
+/** Present-field version checks. Pass `requireIdentity` for version --json. */
 function assertVersionTriple(envelope, requireIdentity = false) {
     // Compound guards (same short-circuit as nested if): check only when required or field present.
-    if ((requireIdentity || envelope.version !== undefined) && envelope.version !== RUNTIME_VERSION) {
+    if ((requireIdentity || envelope.version !== undefined) && binaryMajor(envelope.version) !== RUNTIME_MAJOR) {
         throw new RuntimeError("VERSION_MISMATCH", "ast-sgrep binary version does not match the extension", { expected: RUNTIME_VERSION, actual: envelope.version });
     }
     if ((requireIdentity || envelope.machine_schema_version !== undefined) && envelope.machine_schema_version !== MACHINE_SCHEMA_VERSION) {

package/dist/runtime/types.d.ts

@@ -2,7 +2,7 @@
  * Shared leaf module: version constants, wire types, RuntimeError.
  * Imports nothing from sibling modules — any file may depend on it.
  */
-export declare const RUNTIME_VERSION = "2.1.0";
+export declare const RUNTIME_VERSION = "2.5.2";
 export declare const MACHINE_SCHEMA_VERSION = "1.0.0";
 export declare const CONFIG_SCHEMA_VERSION: 1;
 /** Index format this release ships. Must equal INDEX_SCHEMA_VERSION in crates/ast-sgrep-core (check-contract gates it). */

package/dist/runtime/types.js

@@ -2,7 +2,7 @@
  * Shared leaf module: version constants, wire types, RuntimeError.
  * Imports nothing from sibling modules — any file may depend on it.
  */
-export const RUNTIME_VERSION = "2.1.0";
+export const RUNTIME_VERSION = "2.5.2";
 export const MACHINE_SCHEMA_VERSION = "1.0.0";
 export const CONFIG_SCHEMA_VERSION = 1;
 /** Index format this release ships. Must equal INDEX_SCHEMA_VERSION in crates/ast-sgrep-core (check-contract gates it). */

package/dist/ui/present.d.ts

@@ -27,8 +27,16 @@ export type EnvelopeLike = {
     backend?: unknown;
     [key: string]: unknown;
 };
-export declare const ASGREP_PROMPT_SNIPPET = "Code search by intent, symbol, defs, callers, pattern (asgrep; use without being asked)";
-export declare const ASGREP_PROMPT_GUIDELINES: readonly ["Any code lookup (function, def, caller, intent, pattern): call asgrep first.", "Compose in Code Mode (search/defs/read with Promise.all, return a small shaped value); grep only for exact strings or filenames. Bound with in: \"path\"; on 0 hits use suggested_next."];
+export declare const ASGREP_PROMPT_SNIPPET = "Code search by intent, symbol, defs, callers, pattern (use without being asked)";
+export declare const ASGREP_PROMPT_GUIDELINES: readonly ["Any code lookup: call asgrep first; read code with asgrep_read, change it with asgrep_edit.", "Compose in Code Mode (search/defs/read, Promise.all, small shaped value); grep only exact strings/filenames. Bound with in:\"path\"; on 0 hits use suggested_next."];
+/**
+ * Guideline variant for hosts that already ship read/edit built in: our
+ * one-shot file tools are inactive there, so naming them would point the
+ * model at tools it cannot see. The host's own builtins describe
+ * themselves; this keeps only the asgrep-first routing plus the shared
+ * composition guideline.
+ */
+export declare const ASGREP_PROMPT_GUIDELINES_HOST_FILES: readonly ["Any code lookup: call asgrep first.", "Compose in Code Mode (search/defs/read, Promise.all, small shaped value); grep only exact strings/filenames. Bound with in:\"path\"; on 0 hits use suggested_next."];
 export declare function paint(theme: PresentTheme | undefined, role: string, text: string, bold?: boolean): string;
 export declare function hitLocation(hit: HitLike): string;
 export declare function hitLabel(hit: HitLike): string;

package/dist/ui/present.js

@@ -1,8 +1,19 @@
 /** Neat asgrep tool chrome for the Pi TUI and the model-visible content. */
-export const ASGREP_PROMPT_SNIPPET = "Code search by intent, symbol, defs, callers, pattern (asgrep; use without being asked)";
+export const ASGREP_PROMPT_SNIPPET = "Code search by intent, symbol, defs, callers, pattern (use without being asked)";
 export const ASGREP_PROMPT_GUIDELINES = [
-    "Any code lookup (function, def, caller, intent, pattern): call asgrep first.",
-    "Compose in Code Mode (search/defs/read with Promise.all, return a small shaped value); grep only for exact strings or filenames. Bound with in: \"path\"; on 0 hits use suggested_next.",
+    "Any code lookup: call asgrep first; read code with asgrep_read, change it with asgrep_edit.",
+    "Compose in Code Mode (search/defs/read, Promise.all, small shaped value); grep only exact strings/filenames. Bound with in:\"path\"; on 0 hits use suggested_next.",
+];
+/**
+ * Guideline variant for hosts that already ship read/edit built in: our
+ * one-shot file tools are inactive there, so naming them would point the
+ * model at tools it cannot see. The host's own builtins describe
+ * themselves; this keeps only the asgrep-first routing plus the shared
+ * composition guideline.
+ */
+export const ASGREP_PROMPT_GUIDELINES_HOST_FILES = [
+    "Any code lookup: call asgrep first.",
+    ASGREP_PROMPT_GUIDELINES[1],
 ];
 export function paint(theme, role, text, bold = false) {
     const body = bold && theme ? theme.bold(text) : text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ast-sgrep",
-  "version": "2.2.0",
+  "version": "2.5.2",
   "description": "Native Code Mode, structural, graph, and semantic code search for Pi",
   "type": "module",
   "license": "MIT",
@@ -53,7 +53,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/copy-guest-worker.mjs",
     "build:native": "cargo build -p ast-sgrep-codemode-napi --release && node ./scripts/copy-native.mjs",
-    "test": "ASGREP_CODEMODE_BACKEND=cli node --import tsx --test ../../../tests/pi/extension/code-mode.test.ts ../../../tests/pi/extension/codemode.test.ts ../../../tests/pi/extension/commands.test.ts ../../../tests/pi/extension/present.test.ts ../../../tests/pi/extension/runtime.test.ts ../../../tests/pi/extension/security.test.ts ../../../tests/pi/extension/session-pool.test.ts ../../../tests/pi/extension/skill-workflow.test.ts ../../../tests/pi/extension/sqlite.test.ts ../../../tests/pi/extension/../../../tests/pi/extension/token-budget.test.ts ../../../tests/pi/extension/tools.test.ts",
+    "test": "ASGREP_CODEMODE_BACKEND=cli node --import tsx --test ../../../tests/pi/extension/code-mode.test.ts ../../../tests/pi/extension/codemode.test.ts ../../../tests/pi/extension/codemode-fallback.test.ts ../../../tests/pi/extension/commands.test.ts ../../../tests/pi/extension/present.test.ts ../../../tests/pi/extension/runtime.test.ts ../../../tests/pi/extension/security.test.ts ../../../tests/pi/extension/session-pool.test.ts ../../../tests/pi/extension/skill-workflow.test.ts ../../../tests/pi/extension/sqlite.test.ts ../../../tests/pi/extension/../../../tests/pi/extension/token-budget.test.ts ../../../tests/pi/extension/tools.test.ts",
     "test:native": "node --import tsx --test ../../../tests/pi/extension/native-inprocess.test.ts",
     "test:all": "npm test && npm run test:native",
     "prepack": "npm run build",
@@ -63,7 +63,7 @@
     "node": ">=22.19.0"
   },
   "dependencies": {
-    "ast-sgrep": ">=2.1.0 <3",
+    "ast-sgrep": ">=2.0.0 <3",
     "typebox": "^1.0.0"
   },
   "peerDependencies": {