pi-ast-sgrep 2.1.1 → 2.2.1

package/README.md

@@ -44,6 +44,7 @@ No Rust toolchain or separate MCP server is required. The npm package selects th
 | `asgrep_search` | Run one natural, structural, symbol, graph, semantic, word, literal, or regex lookup. |
 | `asgrep_index` | Create, refresh, or explicitly rebuild the current project index. |
 | `asgrep_status` | Inspect the selected root, index, backend, counts, and capabilities. |
+| `asgrep_read`, `asgrep_edit` | One-shot file window / exact-string edit. Registered on every host, but **kept out of the active tool set when the host already provides built-in `read` and `edit`** (pi does), because Pi sends only active tools to the model. Sessions started with `--no-builtin-tools`, MCP-style hosts, and any host without tool-set control keep them active; `ASGREP_KEEP_FILE_TOOLS=1` pins them active anywhere. |
 
 The package also registers `/asgrep-doctor`, `/asgrep-status`, `/asgrep-index`, and `/asgrep-reindex`.
 

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).
@@ -103,4 +103,5 @@ export declare function createAsgrepConnector(host: BatchCapableHost, context: {
     cwd: string;
 }, options?: {
     signal?: AbortSignal;
+    scope?: string;
 }): ConnectorBundle;

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;
@@ -20,6 +28,31 @@ function clampExcerpt(excerptLines) {
  */
 export function createAsgrepConnector(host, context, options = {}) {
     const dispatcher = createCodemodeDispatcher(host);
+    // One index per checkout: when the caller's cwd is a subdirectory of the
+    // checkout that owns the index, path arguments are rebased onto that checkout
+    // root and searches are scoped to the subdirectory. Callers never see a
+    // second `.asgrep` grow inside the tree.
+    const scope = options.scope && options.scope !== "."
+        ? options.scope.replace(/^(?:\.\/)+/u, "").replace(/\/+$/u, "")
+        : undefined;
+    const rebasePath = (path) => {
+        if (!scope || path.startsWith("/") || path.startsWith("~"))
+            return path;
+        const clean = path.replace(/^(?:\.\/)+/u, "");
+        return clean === "" || clean === "." ? scope : `${scope}/${clean}`;
+    };
+    const rebaseRef = (ref) => {
+        const hash = ref.indexOf("#");
+        return hash === -1 ? rebasePath(ref) : rebasePath(ref.slice(0, hash)) + ref.slice(hash);
+    };
+    /** Directories below the checkout combine with the anchor scope, never replace it. */
+    const withScope = (input) => {
+        if (!scope)
+            return input;
+        const nested = input.in ?? input.fileFilter ?? input.file_filter;
+        const combined = typeof nested === "string" && nested.trim() ? `${scope}/${nested.replace(/^(?:\.\/)+/u, "")}` : scope;
+        return { ...input, in: combined };
+    };
     const combinedSignals = new WeakMap();
     const callOptions = (signal) => {
         if (!options.signal)
@@ -33,9 +66,37 @@ 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, { ...input });
+        const scoped = coerceHostArgs(method, withScope({ ...input }));
         const payload = {
             query: scoped.query,
             limit: clampLimit(input.limit),
@@ -51,11 +112,11 @@ export function createAsgrepConnector(host, context, options = {}) {
         search: (input, callOptions) => call("search", searchPayload("search", input), callOptions?.signal),
         find: (input, callOptions) => call("find", searchPayload("find", input), callOptions?.signal),
         read: (input, callOptions) => call("read", defined({
-            path: input.path,
+            path: typeof input.path === "string" ? rebasePath(input.path) : input.path,
             start: input.start,
             end: input.end,
-            ref: input.ref,
-            refs: input.refs,
+            ref: typeof input.ref === "string" ? rebaseRef(input.ref) : input.ref,
+            refs: Array.isArray(input.refs) ? input.refs.map((ref) => (typeof ref === "string" ? rebaseRef(ref) : ref)) : input.refs,
             context_lines: input.contextLines,
             max_chars: input.maxChars,
         }), callOptions?.signal),
@@ -63,11 +124,12 @@ export function createAsgrepConnector(host, context, options = {}) {
             // Multi-edit wire contract: every entry carries its own path; the
             // top-level path is the default for entries that omit it.
             const edits = input.edits?.map((entry) => ({
-                ...(typeof input.path === "string" ? { path: input.path } : {}),
+                ...(typeof input.path === "string" ? { path: rebasePath(input.path) } : {}),
                 ...entry,
+                ...(typeof entry.path === "string" ? { path: rebasePath(entry.path) } : {}),
             }));
             return call("edit", defined({
-                path: input.path,
+                path: typeof input.path === "string" ? rebasePath(input.path) : input.path,
                 oldText: input.oldText,
                 newText: input.newText,
                 edits,

package/dist/codemode/dispatch.js

@@ -287,7 +287,10 @@ export function argvFor(tool, args) {
         const paths = Array.isArray(args.paths)
             ? args.paths.filter((path) => typeof path === "string")
             : [];
-        return [command, ".", "--json", ...paths.flatMap((path) => ["--path", path])];
+        // Callers that index on the hot path (freshness) pass use_embed:false so a
+        // cold repo answers with lexical/AST rows instead of waiting on vectors.
+        const embed = args.use_embed === false ? ["--no-embed"] : [];
+        return [command, ".", "--json", ...embed, ...paths.flatMap((path) => ["--path", path])];
     }
     const limit = num(args.limit, 8);
     if (spec.form === "chain") {

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.0.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.0.0";
+export const CODEMODE_BINDING_VERSION = "2.5.2";
 let cached;
 function platformTriple() {
     const { platform, arch } = process;

package/dist/codemode/types.d.ts

@@ -46,4 +46,13 @@ export type CodemodeHostMethod = (typeof CODEMODE_HOST_METHODS)[number];
  * Return shapes are muscle memory (Blacksmith): field names, never values.
  * defs:/callers:/imports:/pattern:/blast: go through find or search prefixes.
  */
+/**
+ * Always-on API cheat sheet for the Code Mode tool description.
+ *
+ * Deliberately minimal: every token here rides in the system prompt of every
+ * request. The full per-method schema is one call away through
+ * `asgrep.catalogSearch(query)` / `asgrep.catalogDescribe(name)`, which returns
+ * the same shapes from the native catalog, so the model pays for the reference
+ * only when it needs it.
+ */
 export declare const CODEMODE_TYPES_FOR_MODEL: string;

package/dist/codemode/types.js

@@ -30,18 +30,17 @@ export const CODEMODE_HOST_METHODS = [
  * Return shapes are muscle memory (Blacksmith): field names, never values.
  * defs:/callers:/imports:/pattern:/blast: go through find or search prefixes.
  */
+/**
+ * Always-on API cheat sheet for the Code Mode tool description.
+ *
+ * Deliberately minimal: every token here rides in the system prompt of every
+ * request. The full per-method schema is one call away through
+ * `asgrep.catalogSearch(query)` / `asgrep.catalogDescribe(name)`, which returns
+ * the same shapes from the native catalog, so the model pays for the reference
+ * only when it needs it.
+ */
 export const CODEMODE_TYPES_FOR_MODEL = `
-type Hit = { file: string; symbol?: string; kind?: string; score?: number; line?: number; ref?: string };
-type Hits = { ok: boolean; hits: Hit[]; suggested_next?: string[] };
-type Window = { path: string; ref: string; start: number; end: number; truncated: boolean; text: string };
-declare const asgrep: {
-  search(query: string | { query: string; limit?: number; in?: string; lang?: string; excerptLines?: number }): Promise<Hits>;
-  find(query: string | { query: string; limit?: number }): Promise<Hits>;
-  defs(symbol: string | { symbol: string; limit?: number }): Promise<Hits>;
-  callers(symbol: string | { symbol: string; limit?: number }): Promise<Hits>;
-  read(input: { path?: string; start?: number; end?: number; ref?: string; refs?: unknown[]; contextLines?: number }): Promise<{ ok: boolean; count: number; windows: Window[] }>;
-  edit(path: string | { path?: string; oldText?: string; newText?: string; edits?: Array<{ path: string; oldText: string; newText: string }> }, oldText?: string, newText?: string): Promise<{ ok: boolean; changed: number }>;
-  indexStatus(): Promise<{ ok: boolean }>;
-};
-/** Positional args work: search("auth"), defs("Foo"). Promise.all independent calls. 0 hits include suggested_next. Return a small value. */
+asgrep.search(query|{query,in,lang,limit,excerptLines}) | find(q) | semantic(q) | defs(sym) | callers(sym)
+ | imports(mod) | chain(q) | read({path|ref|refs,start,end}) | edit({path,oldText,newText}|{edits}) | indexStatus()
+hits[{file,ref,symbol,kind,preview}] | windows[{path,start,end,text}] | catalogDescribe("name") for schemas
 `.trim();

package/dist/host/results.d.ts

@@ -67,6 +67,10 @@ export declare function success(command: string, response: MachineEnvelope, extr
     mode?: string;
     activationMs?: number;
     backend?: string;
+    freshness?: "stale";
+    indexState?: "empty" | "ready";
+    excerptLines?: number;
+    notes?: string[];
 }): {
     content: {
         type: "text";
@@ -77,6 +81,10 @@ export declare function success(command: string, response: MachineEnvelope, extr
         mode?: string;
         activationMs?: number;
         backend?: string;
+        freshness?: "stale";
+        indexState?: "empty" | "ready";
+        excerptLines?: number;
+        notes?: string[];
         ok: boolean;
         command: string;
         response: {