pi-para 0.6.5 → 0.6.7

package/src/store.ts

@@ -5,6 +5,7 @@
  * re-indexing after wiki changes, and embedding lifecycle.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import { readFileSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -73,6 +74,51 @@ const RAW_CONTEXT = "Immutable source material: articles, documents, notes. Not
 
 const pendingEmbeds = new WeakMap<QMDStore, Promise<void>>();
 
+export type QmdEmbedOperationResult<T> =
+  | { ok: true; value: T; diagnostics: string[] }
+  | { ok: false; error: unknown; diagnostics: string[] };
+
+// qmd-engine's API adapter logs recoverable provider failures directly to
+// console.error before returning null. Capture only those known messages so
+// best-effort vector search and scheduler retries do not flash raw errors in
+// the Pi UI. Other console errors continue to pass through unchanged.
+const qmdEmbedDiagnosticContext = new AsyncLocalStorage<string[]>();
+let qmdEmbedCaptureCount = 0;
+let qmdEmbedOriginalConsoleError: typeof console.error | null = null;
+const qmdEmbedConsoleInterceptor = (...args: unknown[]): void => {
+  const sink = qmdEmbedDiagnosticContext.getStore();
+  const first = String(args[0] ?? "");
+  if (sink && /^embed(?:Batch)? error:/i.test(first)) {
+    sink.push(args.map((arg) => arg instanceof Error ? arg.message : String(arg)).join(" "));
+    return;
+  }
+  qmdEmbedOriginalConsoleError?.(...args);
+};
+
+/** Run a QMD embedding operation without leaking its recoverable raw stderr. */
+export async function captureQmdEmbedErrors<T>(operation: () => Promise<T>): Promise<QmdEmbedOperationResult<T>> {
+  const diagnostics: string[] = [];
+  if (qmdEmbedCaptureCount++ === 0) {
+    qmdEmbedOriginalConsoleError = console.error;
+    console.error = qmdEmbedConsoleInterceptor;
+  }
+  try {
+    return await qmdEmbedDiagnosticContext.run(diagnostics, async () => {
+      try {
+        return { ok: true, value: await operation(), diagnostics };
+      } catch (error) {
+        return { ok: false, error, diagnostics };
+      }
+    });
+  } finally {
+    qmdEmbedCaptureCount--;
+    if (qmdEmbedCaptureCount === 0) {
+      if (console.error === qmdEmbedConsoleInterceptor && qmdEmbedOriginalConsoleError) console.error = qmdEmbedOriginalConsoleError;
+      qmdEmbedOriginalConsoleError = null;
+    }
+  }
+}
+
 // -- Inert-provider tracking ---------------------------------------------------
 
 /** Stores opened with the NO_LOCAL_PROVIDERS shim (no real API provider). */
@@ -184,22 +230,10 @@ export async function openStore(wikiDir: string, opts: OpenStoreOptions = {}): P
   if (opts.backgroundEmbed !== false && opts.paraConfig?.qmd.embedEnabled !== false) {
     // Schedule embedding in background (non-blocking).
     // BM25 search works immediately; hybrid search improves once embed completes.
-    // Suppress console.error from qmd's internal embed failures.
-    const origError = console.error;
-    const embedPromise = store.embed().then(() => {
-      pendingEmbeds.delete(store);
-    }).catch(() => {
-      // Embedding failures are non-fatal — hybrid search degrades to BM25
+    const embedPromise = captureQmdEmbedErrors(() => store.embed()).then(() => {
+      // Embedding failures are non-fatal — hybrid search degrades to BM25.
       pendingEmbeds.delete(store);
-    }).finally(() => {
-      console.error = origError;
     });
-    // Temporarily suppress embed error noise during background embed
-    console.error = (...args: unknown[]) => {
-      const msg = String(args[0] ?? "");
-      if (msg.includes("embed error") || msg.includes("fetch failed")) return;
-      origError(...args);
-    };
     pendingEmbeds.set(store, embedPromise);
   }
 
@@ -317,7 +351,10 @@ async function mergeLexAndVectorResults(
     const llm = (store.internal as unknown as { llm?: unknown }).llm;
     const embedModel = (llm as { embedModelName?: string } | undefined)?.embedModelName;
     if (status.hasVectorIndex && llm && embedModel) {
-      vecResults = await store.internal.searchVec(query, embedModel, limit, "wiki", llm as any) as RawQmdSearchResult[];
+      const vectorAttempt = await captureQmdEmbedErrors(
+        () => store.internal.searchVec(query, embedModel, limit, "wiki", llm as any) as Promise<RawQmdSearchResult[]>,
+      );
+      if (vectorAttempt.ok) vecResults = vectorAttempt.value;
     }
   } catch {
     // Semantic search is best-effort; lexical BM25 remains the reliable fallback.

package/src/wiki-tool-guidance.ts

@@ -39,7 +39,7 @@ const TOOL_SPECIFIC_GUIDELINES: Record<WikiToolName, readonly string[]> = {
     "After ingesting, synthesize durable knowledge with wiki_write/wiki_edit when the source contains reusable facts.",
   ],
   wiki_query: [
-    "Use wiki_query before answering questions that may depend on past architecture decisions, debugging history, conventions, or domain knowledge.",
+    "Call wiki_query FIRST — before other tools — for any non-trivial planning, implementation, debugging, architecture, or review request; the wiki may hold prior decisions, root causes, and conventions.",
     "Use global=true only when the answer should search across project scopes.",
   ],
   wiki_edit: [
@@ -76,7 +76,7 @@ export function buildWikiToolGuidanceSection(): string {
   return [
     "## pi-para Wiki Tool Guidance",
     "",
-    "- Search with wiki_query when past architecture, debugging, conventions, domain facts, or prior discussion may matter.",
+    "- Start non-trivial work with wiki_query using keywords from the request; past architecture, debugging, conventions, domain facts, or prior discussion may already be documented.",
     "- Treat AGING/STALE/VERY STALE code/config/API claims as untrusted until verified against source; fix wrong pages with wiki_edit.",
     "- Persist major decisions/debugging/conventions without being asked. Use wiki_edit for surgical fixes; wiki_write create/append for new/additive knowledge; replace only for deliberate full rewrites.",
     "- Prefer resources/, kebab-case scope/tags, [[wikilinks]], and no secrets.",