pi-ast-sgrep 2.1.1 → 2.2.0

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

@@ -103,4 +103,5 @@ export declare function createAsgrepConnector(host: BatchCapableHost, context: {
     cwd: string;
 }, options?: {
     signal?: AbortSignal;
+    scope?: string;
 }): ConnectorBundle;

package/dist/codemode/connector.js

@@ -20,6 +20,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)
@@ -35,7 +60,7 @@ export function createAsgrepConnector(host, context, options = {}) {
     };
     const call = (tool, args, signal) => dispatcher.host.call(tool, args, context, callOptions(signal));
     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 +76,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 +88,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/native.d.ts

@@ -9,7 +9,7 @@
  * 2. `@ast-sgrep/<platform>/ast-sgrep-codemode.node` via launcher (release install)
  * 3. Local `extension/native/` / cargo `target/release` (dev builds)
  */
-export declare const CODEMODE_BINDING_VERSION = "2.0.0";
+export declare const CODEMODE_BINDING_VERSION = "2.1.0";
 export type NativeSessionConfig = {
     root?: string;
     indexPath?: string;

package/dist/codemode/native.js

@@ -13,7 +13,7 @@ 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.1.0";
 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: {

package/dist/host/results.js

@@ -19,14 +19,46 @@ export function success(command, response, extra = {}) {
                 : command === "read"
                     ? formatReadResult(response)
                     : formatSearchResult(response, { command, ...extra });
+    // Notes qualify the answer the agent is about to trust (stale index, empty
+    // index): they stay in the model-visible text, not only in the details bag.
+    const body = (extra.notes ?? []).length > 0
+        ? `${text}\n${(extra.notes ?? []).map((note) => `  ! ${note}`).join("\n")}`
+        : text;
     return {
-        content: [{ type: "text", text: bounded(text) }],
+        content: [{ type: "text", text: bounded(body) }],
         // The tool execute owns its machine command: normalize the envelope's
         // command (native catalog names like index_status/index_repo must surface
         // as the machine commands status/index/reindex).
         details: { ok: true, command, response: { ...response, command }, ...extra },
     };
 }
+/**
+ * Failure families the native session raises as *text*: the NAPI boundary
+ * carries `err.to_string()`, so the code has to be reconstructed from the
+ * message instead of being read off a struct. Everything here maps to
+ * OPERATIONAL_ERROR — a real answer about the index, not a mystery failure.
+ *
+ * Keep this list bounded and message-precise: an unrecognised failure stays
+ * UNEXPECTED_ERROR, which is honest, while a false positive would hide one.
+ */
+const OPERATIONAL_FAILURES = [
+    {
+        pattern: /database is locked|database table is locked/i,
+        hint: "another process holds the index write lock (a concurrent asgrep index build); retry in a few seconds, or scope the search with in:/fileFilter",
+    },
+    {
+        pattern: /index changed while preparing|retry the rebuild/i,
+        hint: "the index changed while this query was preparing; retry once the running index build finishes",
+    },
+    {
+        pattern: /index is empty|index does not exist|failed to open index|failed to resolve index path|index schema version|unsupported schema|newer than supported/i,
+    },
+    {
+        pattern: /database disk image is malformed|file is not a database|not a database/i,
+        hint: "the index file is damaged; run /asgrep-reindex to rebuild it",
+    },
+    { pattern: /unable to open database file|no such table/i },
+];
 export function errorDetails(cause, signal) {
     if (signal?.aborted) {
         return { code: "CANCELLED", message: "cancelled", details: {} };
@@ -45,6 +77,20 @@ export function errorDetails(cause, signal) {
             details: {},
         };
     }
+    // An aborted call is not a mystery failure: the caller's deadline or cancel
+    // fired. (Checked after timeout so a timed-out abort still reads as TIMEOUT.)
+    if ((cause instanceof Error && cause.name === "AbortError") || /aborted|was cancelled|operation cancelled/i.test(message)) {
+        return { code: "CANCELLED", message: "cancelled", details: {} };
+    }
+    for (const family of OPERATIONAL_FAILURES) {
+        if (!family.pattern.test(message))
+            continue;
+        return {
+            code: "OPERATIONAL_ERROR",
+            message,
+            details: family.hint ? { hint: family.hint } : {},
+        };
+    }
     return { code: "UNEXPECTED_ERROR", message, details: {} };
 }
 export function isFreshnessTimeout(cause, userSignal) {

package/dist/host/tools.d.ts

@@ -6,4 +6,23 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type FreshnessLike, type RuntimeLike } from "./results.js";
 export declare const DEFAULT_LIMIT = 8;
+/**
+ * pi ships `read`, `edit`, `write`, `bash`, `grep`, `find`, `ls` built in, so on
+ * a normal Pi host our one-shot file tools would be paid for twice and never
+ * needed. They stay REGISTERED — an MCP-style host, a `--no-builtin-tools`
+ * 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.
+ *
+ * ASGREP_KEEP_FILE_TOOLS=1 pins them active regardless.
+ */
+/**
+ * Tools that MUTATE the index never ride the warm session: its calls are
+ * serialized, so a write there blocks every read queued behind it.
+ *
+ * Exported so the routing contract is testable without a live session.
+ */
+export declare function writesOffSession(tool: string): boolean;
+export declare function hostProvidesFileTools(pi: ExtensionAPI, env?: NodeJS.ProcessEnv): boolean;
 export declare function registerAstSgrepTools(pi: ExtensionAPI, runtime?: RuntimeLike, freshness?: FreshnessLike): void;