pi-ast-sgrep 2.0.2 → 2.2.0

package/dist/codemode/session-pool.d.ts

@@ -7,7 +7,7 @@
  * Fallback: sticky `codemode-serve` child only when the `.node` addon is missing
  * (unsupported host / incomplete install). Doctor reports that as degraded.
  */
-import type { MachineEnvelope } from "../runtime.js";
+import type { MachineEnvelope } from "../runtime/runtime.js";
 import { type StickyWorker } from "./dispatch.js";
 import { type StickyWorkerOptions } from "./worker.js";
 export type SessionPoolOptions = {
@@ -22,6 +22,9 @@ export type SessionPoolOptions = {
     limit?: number;
 };
 export type StickyStarter = (options: StickyWorkerOptions) => Promise<StickyWorker>;
+/** Unique search must not run on the JS thread; cache hits may. */
+export declare function isUncachedSearchError(cause: unknown): boolean;
+export declare function isClosedWorkerError(cause: unknown): boolean;
 export declare class NativeSessionPool {
     #private;
     constructor(startFn?: StickyStarter);
@@ -29,6 +32,8 @@ export declare class NativeSessionPool {
     configured(): boolean;
     /** Active backend after first successful acquire. */
     backend(): "napi" | "cli" | "none";
+    /** Why the last start attempt failed — for doctor/status and error fidelity. */
+    lastStartError(root: string): string | undefined;
     acquire(root: string): Promise<StickyWorker | null>;
     call(root: string, tool: string, args?: Record<string, unknown>, options?: {
         signal?: AbortSignal;

package/dist/codemode/session-pool.js

@@ -9,6 +9,7 @@
  */
 import { asEnvelope } from "./dispatch.js";
 import { loadCodemodeNative } from "./native.js";
+import { defined } from "./types.js";
 import { startStickyWorker } from "./worker.js";
 const abortError = () => Object.assign(new Error("native call aborted"), { name: "AbortError" });
 /** Bounded metadata and symbol lookups that may run on the JS thread. */
@@ -19,11 +20,43 @@ const FAST_LOOKUP = new Set([
     "index_status",
     "catalog_search",
     "catalog_describe",
+    "find",
+    "read",
 ]);
 function isBusyError(cause) {
     const message = cause instanceof Error ? cause.message : String(cause);
     return /session is busy/i.test(message);
 }
+/** Unique search must not run on the JS thread; cache hits may. */
+export function isUncachedSearchError(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return /use call\(\) for search/i.test(message);
+}
+/** NAPI can surface SQLite u64 counters as BigInt (writer_generation exceeds
+ * 2^53). BigInt breaks JSON.stringify downstream (pi serializes result
+ * details) — normalize to Number at the boundary. Precision past 2^53 is
+ * display-only here; equality comparisons still hold since both sides
+ * convert the same integer identically. */
+function normalizeNativeValue(value) {
+    if (typeof value === "bigint")
+        return Number(value);
+    if (Array.isArray(value))
+        return value.map(normalizeNativeValue);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, entry] of Object.entries(value))
+            out[key] = normalizeNativeValue(entry);
+        return out;
+    }
+    return value;
+}
+export function isClosedWorkerError(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return /codemode-serve is closed|native session is closed/i.test(message);
+}
+function workerIsClosed(worker) {
+    return worker.closed?.() === true;
+}
 function inProcessWorker(session) {
     let tail = Promise.resolve();
     let closed = false;
@@ -53,26 +86,34 @@ function inProcessWorker(session) {
         });
     };
     return {
+        closed: () => closed,
         call(tool, args, options) {
             if (options?.signal?.aborted)
                 return Promise.reject(abortError());
             const sync = session.callNow;
-            if (inflight === 0 && !closed && sync && FAST_LOOKUP.has(tool)) {
+            if (inflight === 0 && !closed && sync && (FAST_LOOKUP.has(tool) || tool === "search")) {
                 try {
-                    return Promise.resolve(asEnvelope(sync.call(session, tool, args ?? {}), tool));
+                    const value = sync.call(session, tool, args ?? {});
+                    if (!(tool === "search" && value == null)) {
+                        return Promise.resolve(asEnvelope(normalizeNativeValue(value), tool));
+                    }
                 }
                 catch (cause) {
-                    if (!isBusyError(cause))
+                    if (tool === "search" && isUncachedSearchError(cause)) {
+                        // Older native addons threw on unique search.
+                    }
+                    else if (!isBusyError(cause)) {
                         return Promise.reject(cause);
+                    }
                 }
             }
-            return enqueue(async () => asEnvelope(await session.call(tool, args, options?.signal), tool), options?.signal);
+            return enqueue(async () => asEnvelope(normalizeNativeValue(await session.call(tool, args, options?.signal)), tool), options?.signal);
         },
         batch(calls, options) {
             return enqueue(async () => {
                 const response = await session.batch(calls, options?.signal);
                 const result = {
-                    results: response.results,
+                    results: normalizeNativeValue(response.results),
                     all_ok: response.allOk,
                     wall_ms: response.wallMs,
                     mode: response.mode,
@@ -95,6 +136,10 @@ export class NativeSessionPool {
     #startFn;
     #backend = "none";
     #shutdownPromise = null;
+    /** Real start failure per root — surfaced instead of a stale "closed" error. */
+    #startFailures = new Map();
+    /** Crash-loop guard: a failing backend gets this long before respawn retries. */
+    static #RESTART_BACKOFF_MS = 15_000;
     constructor(startFn = startStickyWorker) {
         this.#startFn = startFn;
     }
@@ -108,12 +153,26 @@ export class NativeSessionPool {
     backend() {
         return this.#backend;
     }
+    /** Why the last start attempt failed — for doctor/status and error fidelity. */
+    lastStartError(root) {
+        return this.#startFailures.get(root)?.error;
+    }
     async acquire(root) {
         if (this.#shutdownPromise)
             return null;
         const existing = this.#entries.get(root);
-        if (existing)
-            return existing.worker;
+        if (existing) {
+            if (!workerIsClosed(existing.worker))
+                return existing.worker;
+            await this.invalidate(root);
+        }
+        // A backend that just failed is crash-looping: skip the respawn for a
+        // bounded window so callers fall back instead of paying a doomed spawn
+        // per call. The window expires and recovery still happens automatically.
+        const failure = this.#startFailures.get(root);
+        if (failure && Date.now() - failure.at < NativeSessionPool.#RESTART_BACKOFF_MS) {
+            return null;
+        }
         const inFlight = this.#starting.get(root);
         if (inFlight)
             return inFlight;
@@ -130,10 +189,31 @@ export class NativeSessionPool {
     async call(root, tool, args = {}, options) {
         if (options?.signal?.aborted)
             throw abortError();
-        const worker = await this.acquire(root);
-        if (!worker)
-            throw new Error("native Code Mode backend unavailable");
-        return worker.call(tool, args, options);
+        try {
+            const worker = await this.acquire(root);
+            if (!worker) {
+                const startError = this.lastStartError(root);
+                throw new Error(startError
+                    ? "codemode backend unavailable: " + startError
+                    : "native Code Mode backend unavailable");
+            }
+            return await worker.call(tool, args, options);
+        }
+        catch (cause) {
+            if (options?.signal?.aborted || !isClosedWorkerError(cause))
+                throw cause;
+            await this.invalidate(root);
+            const retry = await this.acquire(root);
+            if (!retry) {
+                // Surface the real restart failure (spawn error / schema refusal), not
+                // the stale "closed" message that hides it.
+                const startError = this.lastStartError(root);
+                if (startError)
+                    throw new Error("codemode backend unavailable: " + startError);
+                throw cause;
+            }
+            return retry.call(tool, args, options);
+        }
     }
     async invalidate(root) {
         this.#generations.set(root, this.#generationFor(root) + 1);
@@ -141,6 +221,7 @@ export class NativeSessionPool {
         this.#starting.delete(root);
         const entry = this.#entries.get(root);
         this.#entries.delete(root);
+        this.#startFailures.delete(root);
         if (entry)
             await entry.worker.end().catch(() => undefined);
         if (starting)
@@ -181,17 +262,24 @@ export class NativeSessionPool {
     async #start(root) {
         const gen = this.#generationFor(root);
         const opts = this.#options ?? {};
+        const fail = (error) => {
+            this.#startFailures.set(root, {
+                at: Date.now(),
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        };
         // 1) In-process NAPI (preferred — zero spawn).
         const binding = loadCodemodeNative();
+        let napiError = null;
         if (binding) {
             try {
-                const config = { root };
-                if (opts.indexPath)
-                    config.indexPath = opts.indexPath;
-                if (opts.limit !== undefined)
-                    config.limit = opts.limit;
-                if (opts.useEmbed !== undefined)
-                    config.useEmbed = opts.useEmbed;
+                const config = defined({
+                    root,
+                    indexPath: opts.indexPath,
+                    limit: opts.limit,
+                    useEmbed: opts.useEmbed,
+                });
                 const session = new binding.Session(config);
                 const worker = inProcessWorker(session);
                 if (gen !== this.#generationFor(root)) {
@@ -200,37 +288,42 @@ export class NativeSessionPool {
                 }
                 this.#entries.set(root, { root, worker, generation: gen, backend: "napi" });
                 this.#backend = "napi";
+                this.#startFailures.delete(root);
                 return worker;
             }
-            catch {
-                // Fall through to CLI sticky.
+            catch (cause) {
+                // Fall through to CLI sticky, but keep the real error for fidelity.
+                napiError = cause;
             }
         }
         // 2) CLI sticky fallback (degraded).
-        if (!opts.binary)
-            return null;
+        if (!opts.binary) {
+            return fail(napiError ?? new Error("native Code Mode backend unavailable (no addon, no binary)"));
+        }
         try {
-            const stickyOpts = {
+            const stickyOpts = defined({
                 binary: opts.binary,
                 cwd: root,
-            };
-            if (opts.env)
-                stickyOpts.env = opts.env;
-            if (opts.timeoutMs !== undefined)
-                stickyOpts.timeoutMs = opts.timeoutMs;
-            if (opts.maxOutputBytes !== undefined)
-                stickyOpts.maxOutputBytes = opts.maxOutputBytes;
+                env: opts.env,
+                timeoutMs: opts.timeoutMs,
+                maxOutputBytes: opts.maxOutputBytes,
+            });
             const worker = await this.#startFn(stickyOpts);
             if (gen !== this.#generationFor(root)) {
                 await worker.end().catch(() => undefined);
                 return null;
             }
+            if (workerIsClosed(worker)) {
+                await worker.end().catch(() => undefined);
+                return fail(new Error("codemode-serve exited during startup"));
+            }
             this.#entries.set(root, { root, worker, generation: gen, backend: "cli" });
             this.#backend = "cli";
+            this.#startFailures.delete(root);
             return worker;
         }
-        catch {
-            return null;
+        catch (cause) {
+            return fail(cause);
         }
     }
 }

package/dist/codemode/types.d.ts

@@ -1,18 +1,58 @@
 /** Typed surface the model sees inside a Code Mode program (`asgrep.*`). */
+/** Drop undefined keys — replaces spread-conditional arg-building chains. */
+export declare function defined<T extends Record<string, unknown>>(args: T): Record<string, unknown>;
 export type SearchArgs = {
     query: string;
     limit?: number;
     excerptLines?: number;
     format?: "capsule" | "agent";
+    /** Directory or glob; injected as an `in:` query token. */
+    in?: string;
+    fileFilter?: string;
+    file_filter?: string;
+    lang?: string;
+};
+export type FindArgs = SearchArgs;
+export type ReadArgs = {
+    path?: string;
+    start?: number;
+    end?: number;
+    ref?: string;
+    refs?: unknown[];
+    contextLines?: number;
+    maxChars?: number;
+};
+export type EditArgs = {
+    path?: string;
+    oldText?: string;
+    newText?: string;
+    edits?: Array<{
+        path?: string;
+        oldText: string;
+        newText: string;
+    }>;
 };
 export type ChainArgs = {
     query: string;
     limit?: number;
     excerptLines?: number;
 };
+/** Host methods the program may invoke. Primary lookup methods first. */
+export declare const CODEMODE_HOST_METHODS: readonly ["search", "find", "read", "edit", "semantic", "chain", "defs", "callers", "imports", "indexStatus", "indexRepo", "doctor", "catalogSearch", "catalogDescribe"];
+export type CodemodeHostMethod = (typeof CODEMODE_HOST_METHODS)[number];
 /**
  * Compact TypeScript declarations for the `asgrep` tool description.
- * Keep short — every token here is paid on every turn (schema landfill lesson
- * from pi-codex-conversion: compose inside Code Mode, don't dump 17 schemas).
+ * Four commands only — every token here is paid on every turn.
+ * 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

@@ -1,21 +1,46 @@
 /** Typed surface the model sees inside a Code Mode program (`asgrep.*`). */
+/** Drop undefined keys — replaces spread-conditional arg-building chains. */
+export function defined(args) {
+    const out = {};
+    for (const [key, value] of Object.entries(args))
+        if (value !== undefined)
+            out[key] = value;
+    return out;
+}
+/** Host methods the program may invoke. Primary lookup methods first. */
+export const CODEMODE_HOST_METHODS = [
+    "search",
+    "find",
+    "read",
+    "edit",
+    "semantic",
+    "chain",
+    "defs",
+    "callers",
+    "imports",
+    "indexStatus",
+    "indexRepo",
+    "doctor",
+    "catalogSearch",
+    "catalogDescribe",
+];
 /**
  * Compact TypeScript declarations for the `asgrep` tool description.
- * Keep short — every token here is paid on every turn (schema landfill lesson
- * from pi-codex-conversion: compose inside Code Mode, don't dump 17 schemas).
+ * Four commands only — every token here is paid on every turn.
+ * 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 = `
-declare const asgrep: {
-  search(input: { query: string; limit?: number; excerptLines?: number }): Promise<unknown>;
-  semantic(input: { query: string; limit?: number; excerptLines?: number }): Promise<unknown>;
-  chain(input: { query: string; limit?: number }): Promise<unknown>;
-  defs(input: { symbol: string; limit?: number }): Promise<unknown>;
-  callers(input: { symbol: string; limit?: number }): Promise<unknown>;
-  imports(input: { module: string; limit?: number }): Promise<unknown>;
-  indexStatus(): Promise<unknown>;
-  indexRepo(input?: { force?: boolean }): Promise<unknown>;
-  catalogSearch(input: { query: string }): Promise<unknown>;
-  catalogDescribe(input: { name: string }): Promise<unknown>;
-};
-/** JS: Promise, JSON, Array, Object, Map, Set, Math. No require/process/fetch/fs. */
+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/codemode/worker.d.ts

@@ -4,7 +4,7 @@
  * One process, one warm Searcher, for the entire Code Mode program — the biggest
  * Amdahl win over per-wave `codemode-batch` spawns.
  */
-import type { MachineEnvelope } from "../runtime.js";
+import type { MachineEnvelope } from "../runtime/runtime.js";
 import { type StickyWorker } from "./dispatch.js";
 export type StickyWorkerOptions = {
     binary: string;

package/dist/codemode/worker.js

@@ -16,9 +16,26 @@ export async function startStickyWorker(options) {
         env: { ...process.env, ...options.env, NO_COLOR: "1" },
         stdio: ["pipe", "pipe", "pipe"],
     });
+    // Fail fast on spawn errors (ENOENT / EACCES): callers get the spawn error
+    // now instead of a dead transport that only fails on first use.
+    await new Promise((resolve, reject) => {
+        const onError = (err) => {
+            child.removeListener("spawn", onSpawn);
+            reject(err);
+        };
+        const onSpawn = () => {
+            child.removeListener("error", onError);
+            resolve();
+        };
+        child.once("error", onError);
+        child.once("spawn", onSpawn);
+    });
     const pending = new Map();
     let nextId = 0;
     let closed = false;
+    // The real termination cause (exit code + stderr) — callers that hit a dead
+    // transport must see WHY it died, not a bare "is closed".
+    let deadCause = null;
     let stderr = "";
     let stdout = Buffer.alloc(0);
     const decoder = new TextDecoder("utf-8", { fatal: true });
@@ -32,6 +49,7 @@ export async function startStickyWorker(options) {
         if (closed)
             return;
         closed = true;
+        deadCause ??= err;
         options.signal?.removeEventListener("abort", onAbort);
         killChild(child);
         failAll(err);
@@ -112,15 +130,19 @@ export async function startStickyWorker(options) {
     child.on("close", (code, signal) => {
         closed = true;
         options.signal?.removeEventListener("abort", onAbort);
+        deadCause ??= new Error(`codemode-serve exited code=${code ?? "null"} signal=${signal ?? "null"} stderr=${stderr.slice(0, 512)}`);
         if (pending.size > 0) {
-            failAll(new Error(`codemode-serve exited code=${code ?? "null"} signal=${signal ?? "null"} stderr=${stderr.slice(0, 512)}`));
+            failAll(deadCause);
         }
     });
     const onAbort = () => terminate(new Error("codemode-serve aborted"));
     options.signal?.addEventListener("abort", onAbort, { once: true });
+    const closedError = () => deadCause
+        ? new Error("codemode-serve is closed (" + deadCause.message + ")")
+        : new Error("codemode-serve is closed");
     const write = (payload) => {
         if (closed || !child.stdin.writable) {
-            return Promise.reject(new Error("codemode-serve is closed"));
+            return Promise.reject(closedError());
         }
         const id = typeof payload.id === "string" ? payload.id : String(nextId++);
         payload.id = id;
@@ -168,6 +190,7 @@ export async function startStickyWorker(options) {
     // Probe: empty End would close — instead send a tiny catalog call to verify protocol,
     // or just return and let first real call fail. Prefer lazy: no probe.
     return {
+        closed: () => closed || !child.stdin.writable,
         async call(tool, args, callOptions) {
             const msg = await writeWithControls({ type: "call", tool, args }, "codemode call", callOptions?.signal);
             if (msg.type === "error") {

package/dist/host/commands.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Slash commands: /asgrep-doctor /asgrep-status /asgrep-index /asgrep-reindex.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type RuntimeLike } from "./results.js";
+export declare function registerAstSgrepCommands(pi: ExtensionAPI, runtime?: RuntimeLike): void;

package/dist/host/commands.js

@@ -0,0 +1,49 @@
+import { AstSgrepRuntime } from "../runtime/runtime.js";
+import { bounded, errorDetails } from "./results.js";
+const COMMANDS = [
+    ["asgrep-doctor", "Check the ast-sgrep runtime, native binary, index, and project configuration", "doctor"],
+    ["asgrep-status", "Show ast-sgrep runtime, index, backend, and capability status", "status"],
+    ["asgrep-index", "Build the ast-sgrep index for the current project", "index"],
+    ["asgrep-reindex", "Rebuild the ast-sgrep index for the current project", "reindex"],
+];
+async function runCommand(runtime, command, ctx, args) {
+    if (args.trim() !== "") {
+        return {
+            ok: false,
+            command,
+            error: { code: "INVALID_ARGUMENTS", message: `/${command} does not accept arguments`, details: { args } },
+        };
+    }
+    try {
+        const response = await runtime.run([command.slice("asgrep-".length), ".", "--json"], { cwd: ctx.cwd });
+        return { ok: true, command, response };
+    }
+    catch (cause) {
+        return { ok: false, command, error: errorDetails(cause) };
+    }
+}
+function compactCommandResult(result) {
+    if (!result.ok)
+        return `${result.command} failed [${result.error.code}]: ${result.error.message}`;
+    const response = result.response;
+    const counts = response.counts && typeof response.counts === "object"
+        ? Object.entries(response.counts).map(([key, value]) => `${key}=${String(value)}`).join(" ")
+        : "";
+    const state = typeof response.status === "string" ? response.status
+        : typeof response.index_status === "string" ? response.index_status
+            : response.ok ? "healthy" : "failed";
+    return bounded([`${result.command}: ${state}`, counts].filter(Boolean).join(" · "));
+}
+export function registerAstSgrepCommands(pi, runtime = new AstSgrepRuntime(pi)) {
+    for (const [name, description] of COMMANDS) {
+        pi.registerCommand(name, {
+            description,
+            async handler(args, context) {
+                const ctx = context;
+                const result = await runCommand(runtime, name, ctx, args);
+                const output = ctx.hasUI ? compactCommandResult(result) : JSON.stringify(result);
+                ctx.ui.notify(output, result.ok ? "info" : "error");
+            },
+        });
+    }
+}

package/dist/host/results.d.ts

@@ -0,0 +1,123 @@
+import { type MachineEnvelope, type RunOptions } from "../runtime/types.js";
+import type { FreshnessCoordinator } from "../runtime/freshness.js";
+export declare const MAX_CONTENT_CHARS = 8000;
+export type RuntimeLike = {
+    run(args: readonly string[], context: {
+        cwd: string;
+    }, options?: RunOptions): Promise<MachineEnvelope>;
+    resolveRoot?(context: {
+        cwd: string;
+    }): Promise<string>;
+    resolveBinaryPath?(options?: {
+        env?: NodeJS.ProcessEnv;
+    }): string;
+    nativeEnv?(options?: {
+        env?: NodeJS.ProcessEnv;
+    }): NodeJS.ProcessEnv;
+    config?: {
+        timeoutMs?: number;
+        maxOutputBytes?: number;
+        refreshIntervalMs?: number;
+    };
+    inspectIndexCompatibility?(context: {
+        cwd: string;
+    }): Promise<"ready" | "missing" | "incompatible">;
+    rebuildIncompatibleIndex?(context: {
+        cwd: string;
+    }, options?: RunOptions): Promise<MachineEnvelope>;
+    resolveIndexPath?(root: string): string;
+    watchExternalChanges?: boolean;
+};
+export type FreshnessLike = Pick<FreshnessCoordinator, "ensureFresh" | "markAffectedPath"> & {
+    markRootDirty?(root: string): void;
+    shutdown?(): void;
+};
+export type ToolContext = {
+    cwd: string;
+};
+export type CommandContext = ToolContext & {
+    hasUI: boolean;
+    ui: {
+        notify(message: string, type?: "info" | "warning" | "error"): void;
+    };
+};
+export type CommandResult = {
+    ok: true;
+    command: string;
+    response: MachineEnvelope;
+} | {
+    ok: false;
+    command: string;
+    error: {
+        code: string;
+        message: string;
+        details: Readonly<Record<string, unknown>>;
+    };
+};
+export type Update = (result: {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: Record<string, unknown>;
+}) => void;
+export declare function bounded(text: string): string;
+export declare function success(command: string, response: MachineEnvelope, extra?: {
+    query?: string;
+    mode?: string;
+    activationMs?: number;
+    backend?: string;
+    freshness?: "stale";
+    indexState?: "empty" | "ready";
+    excerptLines?: number;
+    notes?: string[];
+}): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        query?: string;
+        mode?: string;
+        activationMs?: number;
+        backend?: string;
+        freshness?: "stale";
+        indexState?: "empty" | "ready";
+        excerptLines?: number;
+        notes?: string[];
+        ok: boolean;
+        command: string;
+        response: {
+            command: string;
+            tool: "asgrep";
+            schema_version: string;
+            ok: boolean;
+            version?: string;
+            machine_schema_version?: string;
+        };
+    };
+};
+export declare function errorDetails(cause: unknown, signal?: AbortSignal): {
+    code: string;
+    message: string;
+    details: Readonly<Record<string, unknown>>;
+};
+export declare function isFreshnessTimeout(cause: unknown, userSignal?: AbortSignal): boolean;
+/** Leading or mid-query `in:path` scope used to bound a fresh-directory index. */
+export declare function extractInPath(query: string): string | undefined;
+export declare function failure(command: string, cause: unknown, signal?: AbortSignal): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        ok: boolean;
+        command: string;
+        error: {
+            code: string;
+            message: string;
+            details: Readonly<Record<string, unknown>>;
+        };
+    };
+};
+export declare function report(onUpdate: Update | undefined, command: string, phase: "started" | "completed"): void;