@lincoln504/pi-research 1.0.6 → 1.0.8

package/dist/cli.mjs

@@ -2295,6 +2295,7 @@ function saveConfig(config, scope = "local", cwd = process.cwd(), changedKeys) {
     PI_RESEARCH_MAX_RESEARCHERS: String(config.MAX_CONCURRENT_RESEARCHERS),
     PI_RESEARCH_MAX_RETRIES: String(config.RESEARCHER_MAX_RETRIES),
     PI_RESEARCH_RETRY_DELAY_MS: String(config.RESEARCHER_MAX_RETRY_DELAY_MS),
+    PI_RESEARCH_MAX_FAILED_RESEARCHERS: String(config.MAX_FAILED_RESEARCHERS ?? DEFAULTS.MAX_FAILED_RESEARCHERS),
     PI_RESEARCH_HEALTH_CHECK_TIMEOUT_MS: String(config.HEALTH_CHECK_TIMEOUT_MS ?? DEFAULTS.HEALTH_CHECK_TIMEOUT_MS),
     PI_RESEARCH_SEARCH_TIMEOUT_MS: String(config.SEARCH_TIMEOUT_MS),
     PI_RESEARCH_TUI_REFRESH_DEBOUNCE_MS: String(config.TUI_REFRESH_DEBOUNCE_MS),
@@ -2457,6 +2458,7 @@ function createConfig(env, processEnv) {
     MAX_CONCURRENT_RESEARCHERS: parseEnvNumber(e, "PI_RESEARCH_MAX_RESEARCHERS", DEFAULTS.MAX_CONCURRENT_RESEARCHERS, 1, 5, true),
     RESEARCHER_MAX_RETRIES: parseEnvNumber(e, "PI_RESEARCH_MAX_RETRIES", DEFAULTS.RESEARCHER_MAX_RETRIES, 0, 5, true),
     RESEARCHER_MAX_RETRY_DELAY_MS: parseEnvNumber(e, "PI_RESEARCH_RETRY_DELAY_MS", DEFAULTS.RESEARCHER_MAX_RETRY_DELAY_MS, 100, 1e4),
+    MAX_FAILED_RESEARCHERS: parseEnvNumber(e, "PI_RESEARCH_MAX_FAILED_RESEARCHERS", DEFAULTS.MAX_FAILED_RESEARCHERS, 1, 10, true),
     DEFAULT_RESEARCH_DEPTH: parseEnvNumber(e, "PI_RESEARCH_DEFAULT_RESEARCH_DEPTH", DEFAULTS.DEFAULT_RESEARCH_DEPTH, 1, 3, true),
     MAX_SCRAPE_BATCHES: parseEnvNumber(e, "PI_RESEARCH_MAX_SCRAPE_BATCHES", DEFAULTS.MAX_SCRAPE_BATCHES, 0, 99, true),
     MAX_GATHERING_CALLS: parseEnvNumber(e, "PI_RESEARCH_MAX_GATHERING_CALLS", DEFAULTS.MAX_GATHERING_CALLS, 1, 100, true),
@@ -2580,6 +2582,8 @@ var init_config = __esm({
       RESEARCHER_MAX_RETRIES: Type.Number({ minimum: 0, maximum: 5, default: 2 }),
       /** Base delay between retries in milliseconds (default: 2000, range: 100-10000) */
       RESEARCHER_MAX_RETRY_DELAY_MS: Type.Number({ minimum: 100, maximum: 1e4, default: 2e3 }),
+      /** Unique researcher failures that abort the entire run (default: 2, range: 1-10) */
+      MAX_FAILED_RESEARCHERS: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
       /** Target depth for recursive research (default: 1, range: 1-3) */
       DEFAULT_RESEARCH_DEPTH: Type.Number({ minimum: 1, maximum: 3, default: 1 }),
       /** Number of batches to allow for a single scrape tool call (default: 2, 0=unlimited) */
@@ -14650,7 +14654,7 @@ async function runBrowserTask(taskOrUrl, type = "scrape", config, signal, retrie
         if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
           lastRestartTime = now;
           logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-          await forceSchedulerRestart2(true, container);
+          await forceSchedulerRestart2(false, container);
           await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
         } else {
           logger.warn(`[BrowserManager] Scheduler restart recently triggered, waiting for pool idle...`);
@@ -14685,7 +14689,7 @@ async function runBrowserHealthCheck(config, retries = 1, signal, container = ge
         if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
           lastRestartTime = now;
           logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-          await forceSchedulerRestart2(true, container);
+          await forceSchedulerRestart2(false, container);
           await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
         } else {
           await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
@@ -14724,7 +14728,7 @@ async function runWorkerSearch(query, config, signal, retries = 1, sessionId, co
         if (now - lastRestartTime > RESTART_COOLDOWN_MS) {
           lastRestartTime = now;
           logger.warn(`[BrowserManager] Forcing scheduler restart and retrying...`);
-          await forceSchedulerRestart2(true, container);
+          await forceSchedulerRestart2(false, container);
           await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
         } else {
           await waitForBrowserPoolIdle(15e3).catch((err) => logger.debug("Wait for browser idle timed out or failed:", err));
@@ -19445,10 +19449,8 @@ function formatResults(results, rejected) {
     if (typeof r.charCount === "number") meta.push(`${r.charCount.toLocaleString()} chars`);
     if (meta.length) md += `**${meta.join(" \xB7 ")}**
 `;
-    if (r.title) {
-      md += `**Cite as:** ${r.url} \u2014 '${r.title}'${r.author ? ` by ${r.author}` : ""}
+    md += `**Cite as:** ${r.url}${r.title ? ` \u2014 '${r.title}'${r.author ? ` by ${r.author}` : ""}` : ""}
 `;
-    }
     md += `
 ${r.text}
 
@@ -20108,10 +20110,10 @@ function getFailedResearchers(piSessionId, researchId) {
   const failures = state.failures.get(researchId) || [];
   return [...new Set(failures)];
 }
-var MAX_FAILED_RESEARCHERS = 2;
-function shouldStopResearch(piSessionId, researchId) {
+var DEFAULT_MAX_FAILED_RESEARCHERS = 2;
+function shouldStopResearch(piSessionId, researchId, maxFailedResearchers = DEFAULT_MAX_FAILED_RESEARCHERS) {
   const sid = normalizeSessionId(piSessionId);
-  return getFailedResearchers(sid, researchId).length >= MAX_FAILED_RESEARCHERS;
+  return getFailedResearchers(sid, researchId).length >= maxFailedResearchers;
 }
 function getResearchStopMessage(piSessionId, researchId) {
   const sid = normalizeSessionId(piSessionId);
@@ -20137,6 +20139,12 @@ function getResearchStopMessage(piSessionId, researchId) {
     "Partial results may be available below."
   ].join("\n");
 }
+var RESEARCH_STOPPED_ERROR_CODE = "RESEARCH_STOPPED";
+function createResearchStopError(piSessionId, researchId) {
+  const err = new Error(getResearchStopMessage(piSessionId, researchId));
+  err.code = RESEARCH_STOPPED_ERROR_CODE;
+  return err;
+}
 
 // src/orchestration/researcher-executor.ts
 async function runResearcher(options) {
@@ -20171,18 +20179,42 @@ ${currentPlan.allQueries.map((q) => `- ${q}`).join("\n")}
   Previous summary: ${e.description}`).join("\n");
   }
   const researcherPromptTemplate = loadPrompt("researcher");
-  if (initialLinks.length === 0 && historicalUrls.length === 0) {
-    logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results or historical links; skipping.`);
-    recordResearcherFailure(sessionId, researchId, id, "no initial search results or historical links (search produced nothing usable)");
-    metrics.increment("researcher_skipped_total", 1, { mode: "deep", complexity: String(complexity), reason: "no_initial_links" });
-    observer?.onResearcherFailure?.(id, "No initial search results or historical links available");
-    return;
+  let effectiveInitialLinks = initialLinks;
+  if (effectiveInitialLinks.length === 0 && historicalUrls.length === 0) {
+    const retryQueries = researcherConfig.queries?.length ? researcherConfig.queries : [researcherConfig.goal];
+    const maxLinkAttempts = config.RESEARCHER_MAX_RETRIES + 1;
+    for (let linkAttempt = 1; linkAttempt <= maxLinkAttempts && effectiveInitialLinks.length === 0; linkAttempt++) {
+      if (linkAttempt > 1) {
+        if (signal?.aborted || container?.isDisposing) break;
+        const delay2 = Math.min(1e3 * Math.pow(2, linkAttempt - 2), config.RESEARCHER_MAX_RETRY_DELAY_MS);
+        logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results; retry ${linkAttempt - 1}/${config.RESEARCHER_MAX_RETRIES} after ${delay2}ms`);
+        await new Promise((r) => setTimeout(r, delay2));
+      }
+      if (signal?.aborted || container?.isDisposing) break;
+      try {
+        const queryResults = await search(retryQueries, config, signal, void 0, container);
+        const urls = /* @__PURE__ */ new Set();
+        for (const qr of queryResults) {
+          for (const r of qr.results || []) urls.add(r.url);
+        }
+        effectiveInitialLinks = [...urls];
+      } catch (err) {
+        logger.debug(`[ResearcherExecutor] Researcher ${id} link-retry search burst failed:`, err);
+      }
+    }
+    if (effectiveInitialLinks.length === 0) {
+      logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results or historical links after ${maxLinkAttempts} attempt(s); skipping.`);
+      recordResearcherFailure(sessionId, researchId, id, "no initial search results or historical links (search produced nothing usable)");
+      metrics.increment("researcher_skipped_total", 1, { mode: "deep", complexity: String(complexity), reason: "no_initial_links" });
+      observer?.onResearcherFailure?.(id, "No initial search results or historical links available");
+      return;
+    }
   }
   let evidenceSection = "";
-  if (initialLinks.length > 0) {
+  if (effectiveInitialLinks.length > 0) {
     evidenceSection = `## Evidence Provided
 Initial search results provided the following URLs to investigate:
-${initialLinks.map((l) => `- ${l}`).join("\n")}`;
+${effectiveInitialLinks.map((l) => `- ${l}`).join("\n")}`;
   }
   const maxAttempts = config.RESEARCHER_MAX_RETRIES + 1;
   let lastError;
@@ -21414,12 +21446,13 @@ var ResearchOrchestrationService = class {
     const researchers = plan.researchers || [];
     const active = /* @__PURE__ */ new Set();
     const maxConcurrent = orchestratorOptions.config?.MAX_CONCURRENT_RESEARCHERS ?? DEFAULTS.MAX_CONCURRENT_RESEARCHERS;
+    const maxFailedResearchers = orchestratorOptions.config?.MAX_FAILED_RESEARCHERS ?? DEFAULTS.MAX_FAILED_RESEARCHERS;
     for (const configItem of researchers) {
       if (signal?.aborted) break;
-      if (shouldStopResearch(sessionId, researchId)) {
+      if (shouldStopResearch(sessionId, researchId, maxFailedResearchers)) {
         const sessionService = await getService(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
         await sessionService.abortAllSessions(researchId);
-        throw new Error(getResearchStopMessage(sessionId, researchId));
+        throw createResearchStopError(sessionId, researchId);
       }
       if (active.size >= maxConcurrent) {
         if (signal?.aborted) break;
@@ -21488,11 +21521,10 @@ var ResearchOrchestrationService = class {
         });
         if (signal?.aborted) break;
       }
-      if (shouldStopResearch(sessionId, researchId)) {
+      if (shouldStopResearch(sessionId, researchId, maxFailedResearchers)) {
         const sessionService = await getService(ServiceNames.RESEARCH_SESSION_SERVICE, ctx, container);
         await sessionService.abortAllSessions(researchId);
-        const stopMessage = getResearchStopMessage(sessionId, researchId);
-        throw new Error(stopMessage);
+        throw createResearchStopError(sessionId, researchId);
       }
     }
     await Promise.all(active);
@@ -21889,18 +21921,26 @@ Research performed using ${modelId}`;
   ensureCitedLinks(sessionId, synthesis) {
     const reports = this.getSessionReports(sessionId);
     let globalCitations = reports.size > 0 ? normalizeCitations(reports).globalCitations : [];
-    if (globalCitations.length === 0) {
+    if (reports.size > 0) {
       const scraped = getScrapedLinks(sessionId);
       if (scraped.length > 0) {
-        globalCitations = scraped.map((url, i) => ({
-          id: i + 1,
-          url,
-          description: "",
-          source: isTranscribedLink(sessionId, url) ? "YouTube Transcript" : "Scrape"
-        }));
-        logger.warn(
-          `[ResearchSynthesisService] No citations parsed from reports; rebuilt ${scraped.length} source(s) from scrape/transcript provenance.`
-        );
+        const known = new Set(globalCitations.map((c) => normalizeUrl(c.url)));
+        const missing = scraped.filter((url) => !known.has(normalizeUrl(url)));
+        if (missing.length > 0) {
+          const startId = globalCitations.reduce((max, c) => Math.max(max, c.id), 0) + 1;
+          globalCitations = [
+            ...globalCitations,
+            ...missing.map((url, i) => ({
+              id: startId + i,
+              url,
+              description: "",
+              source: isTranscribedLink(sessionId, url) ? "YouTube Transcript" : "Scrape"
+            }))
+          ];
+          logger.warn(
+            `[ResearchSynthesisService] Folded in ${missing.length} source(s) from scrape/transcript provenance not covered by parsed citations.`
+          );
+        }
       }
     }
     if (globalCitations.length > 0) {
@@ -22114,6 +22154,79 @@ init_metrics();
 
 // src/utils/metrics-summary.ts
 init_text_utils();
+function sumCounter(counters, baseName) {
+  let total = 0;
+  for (const [key, value] of Object.entries(counters)) {
+    if (key === baseName || key.startsWith(baseName + "{")) {
+      total += value;
+    }
+  }
+  return total;
+}
+function getLabeledCounter(counters, baseName, labels) {
+  const labelParts = Object.entries(labels).map(([k, v]) => `${k}="${v}"`);
+  const suffix = `{${labelParts.join(",")}}`;
+  for (const [key, value] of Object.entries(counters)) {
+    if (key === `${baseName}${suffix}`) {
+      return value;
+    }
+  }
+  return 0;
+}
+function extractRunStats(snapshot) {
+  const counters = snapshot.counters || {};
+  const histograms = snapshot.histograms || {};
+  const researchersLaunched = sumCounter(counters, "researchers_launched_total");
+  const browserSearchQueries = sumCounter(counters, "browser_search_queries_total");
+  const searchQueries = sumCounter(counters, "search_queries_total") + browserSearchQueries;
+  const urlsDiscovered = sumCounter(counters, "browser_search_results_total") + sumCounter(counters, "browser_search_unique_urls_total");
+  const fetchSuccess = getLabeledCounter(counters, "scrape_results_total", { outcome: "fetch_success" });
+  const browserSuccess = getLabeledCounter(counters, "scrape_results_total", { outcome: "browser_success" });
+  const totalFailure = getLabeledCounter(counters, "scrape_results_total", { outcome: "total_failure" });
+  const browserFallbacks = sumCounter(counters, "scrape_layer_fallbacks_total");
+  const urlsAnalyzed = fetchSuccess + browserSuccess;
+  const urlsFailed = totalFailure;
+  const toolUsage = {
+    searches: sumCounter(counters, "tool_search_calls_total"),
+    scrapes: sumCounter(counters, "tool_scrape_calls_total"),
+    securitySearches: sumCounter(counters, "tool_security_search_calls_total"),
+    stackexchangeQueries: sumCounter(counters, "stackexchange_requests_total"),
+    knowledgeLookups: sumCounter(counters, "research_knowledge_search_total")
+  };
+  const errors = sumCounter(counters, "researcher_errors_total") + sumCounter(counters, "llm_api_errors_total");
+  const tokens = sumCounter(counters, "llm_tokens_total");
+  const cost = sumCounter(counters, "llm_cost_total");
+  const durationMs = histograms['research_session_duration_ms{mode="deep",complexity="1",status="success"}']?.max || histograms['research_session_duration_ms{mode="deep",complexity="2",status="success"}']?.max || histograms['research_session_duration_ms{mode="deep",complexity="3",status="success"}']?.max || histograms['research_session_duration_ms{mode="quick",complexity="0",status="success"}']?.max || 0;
+  const roundsCompleted = sumCounter(counters, "evaluator_runs_total");
+  let complexity = 1;
+  for (const key of Object.keys(counters)) {
+    if (key.startsWith("research_sessions_total{")) {
+      const match = key.match(/complexity="(\d+)"/);
+      if (match?.[1]) complexity = parseInt(match[1], 10);
+      break;
+    }
+  }
+  if (researchersLaunched === 0 && searchQueries === 0 && urlsAnalyzed === 0 && tokens === 0) {
+    return null;
+  }
+  return {
+    durationMs,
+    complexity,
+    researchersLaunched,
+    roundsCompleted,
+    searchQueries,
+    urlsDiscovered,
+    fetchSuccess,
+    browserSuccess,
+    browserFallbacks,
+    urlsAnalyzed,
+    urlsFailed,
+    errors,
+    tokens,
+    cost,
+    toolUsage
+  };
+}
 
 // src/sdk.ts
 init_error_tracker();
@@ -22135,6 +22248,7 @@ var _isRunning = false;
 var _lastResearchId = null;
 var _lastRunSummary = null;
 var _lastErrorReport = null;
+var _lastResearcherOutcome = null;
 var _onSignal = null;
 var _sigintHandler = null;
 var _sigtermHandler = null;
@@ -22321,6 +22435,7 @@ async function runDeepResearch(query, options = {}, signal) {
     metrics.recordRunSummary(_lastRunSummary);
     _lastErrorReport = runTracker.getReport();
     logRunErrorSummary(_lastErrorReport, depthLabel, "success");
+    _lastResearcherOutcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot);
     return result;
   } catch (err) {
     const completedAt = Date.now();
@@ -22336,6 +22451,7 @@ async function runDeepResearch(query, options = {}, signal) {
     metrics.recordRunSummary(_lastRunSummary);
     _lastErrorReport = runTracker.getReport();
     logRunErrorSummary(_lastErrorReport, depthLabel, "error");
+    _lastResearcherOutcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot);
     throw err;
   } finally {
     try {
@@ -22345,11 +22461,35 @@ async function runDeepResearch(query, options = {}, signal) {
     _isRunning = false;
   }
 }
+function getLastErrorReport() {
+  return _lastErrorReport;
+}
+function getLastResearcherOutcome() {
+  return _lastResearcherOutcome;
+}
 function logRunErrorSummary(report, depthLabel, status) {
   if (!report || report.totalErrors === 0) return;
   const top = report.patterns.slice(0, 3).map((p) => `"${String(p.message ?? p.signature ?? "error").slice(0, 48)}" \xD7${p.count}`).join(", ");
   logger.warn(`[SDK] run ${status} with ${report.totalErrors} tracked error(s) across ${report.uniquePatterns} pattern(s) [${depthLabel}]${top ? ` \u2014 top: ${top}` : ""}`);
 }
+async function captureResearcherOutcome(sessionId, researchId, snapshot) {
+  try {
+    const planningService = await getService(ServiceNames.PLANNING, void 0, globalContainer);
+    const planned = planningService.getTotalResearchersPlanned(researchId);
+    const launched = extractRunStats(snapshot)?.researchersLaunched ?? 0;
+    const failed = getFailedResearchers(sessionId, researchId);
+    return {
+      planned,
+      launched,
+      succeeded: Math.max(0, launched - failed.length),
+      failed: failed.length,
+      failureReasons: getResearcherFailureReasons(sessionId, researchId)
+    };
+  } catch (err) {
+    logger.debug("[SDK] Failed to capture researcher outcome (non-fatal):", err);
+    return null;
+  }
+}
 async function searchKnowledge(queries, signal) {
   if (!isInitialized || !globalContainer) {
     throw new Error("SDK not initialized. Call initResearchSDK() first.");
@@ -22433,6 +22573,7 @@ async function _doShutdown() {
   _lastResearchId = null;
   _lastRunSummary = null;
   _lastErrorReport = null;
+  _lastResearcherOutcome = null;
   resetConfig();
   _removeSignalHandlers();
   if (errors.length > 0) {
@@ -22938,6 +23079,8 @@ Error: ${vmsg}
 `);
   const observer = makeProgressObserver();
   let exit = EXIT.OK;
+  const abortController = new AbortController();
+  activeResearchAbortController = abortController;
   try {
     await initResearchSDK({
       model: runModel,
@@ -22954,7 +23097,7 @@ Error: ${vmsg}
       observer,
       ...args.excludeTools ? { excludeTools: args.excludeTools } : {},
       ...args.initialLinks ? { initialLinks: args.initialLinks } : {}
-    });
+    }, abortController.signal);
     let reportPath = null;
     const exportCfg = getConfig(process.cwd(), "cli");
     if (exportCfg.RESEARCH_REPORT_EXPORT_ENABLED) {
@@ -22966,13 +23109,25 @@ Error: ${vmsg}
       }
     }
     if (args.json) {
-      toStdout(pretty({ ok: true, depth, report, ...reportPath ? { reportPath } : {} }));
+      const outcome = getLastResearcherOutcome();
+      const errorReport = getLastErrorReport();
+      toStdout(pretty({
+        ok: true,
+        depth,
+        report,
+        ...reportPath ? { reportPath } : {},
+        ...outcome ? { researchers: { planned: outcome.planned, launched: outcome.launched, succeeded: outcome.succeeded, failed: outcome.failed } } : {},
+        ...errorReport && errorReport.totalErrors > 0 ? {
+          trackedErrors: { total: errorReport.totalErrors, uniquePatterns: errorReport.uniquePatterns }
+        } : {}
+      }));
     } else {
       toStdout(report.endsWith("\n") ? report : report + "\n");
     }
   } catch (err) {
     exit = reportError(err, "research", args.json);
   } finally {
+    if (activeResearchAbortController === abortController) activeResearchAbortController = null;
     await safeShutdown();
   }
   return exit;
@@ -23249,7 +23404,8 @@ function describeUninstall(r) {
 function reportError(err, what, json) {
   const msg2 = err instanceof Error ? err.message : String(err);
   const lower = msg2.toLowerCase();
-  const isConfigError = lower.includes("no llm model available") || lower.includes("not found in pi") || lower.includes("no api key") || lower.includes("provider must be specified") || lower.includes("invalid model string") || lower.includes("authentication") || lower.includes("unauthorized") || lower.includes("api key");
+  const isTaggedResearchStop = err?.code === RESEARCH_STOPPED_ERROR_CODE;
+  const isConfigError = !isTaggedResearchStop && (lower.includes("no llm model available") || lower.includes("not found in pi") || lower.includes("no api key") || lower.includes("provider must be specified") || lower.includes("invalid model string") || lower.includes("authentication") || lower.includes("unauthorized") || lower.includes("api key"));
   const isRateLimit = lower.includes("429") || lower.includes("rate limit") || lower.includes("too many requests");
   const exitCode = isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
   if (json) {
@@ -23557,6 +23713,7 @@ var flushAndExit = (code) => {
     });
   });
 };
+var activeResearchAbortController = null;
 async function main(argv) {
   let _signalCleanupDone = false;
   const onSignal = (sig) => {
@@ -23565,6 +23722,7 @@ async function main(argv) {
     toStderr(`
 [pi-research] ${sig} \u2014 cleaning up\u2026
 `);
+    activeResearchAbortController?.abort();
     void safeShutdown().finally(() => flushAndExit(EXIT.SOFTWARE));
   };
   process.once("SIGINT", () => onSignal("SIGINT"));
@@ -23634,5 +23792,6 @@ export {
   EXIT,
   UsageError,
   bridgeConfigEnv,
-  parseArgs
+  parseArgs,
+  reportError
 };

package/dist/prompts/research-tool-usage.md

@@ -85,6 +85,7 @@ The coordinator will plan as many researchers as needed (up to the max). You do
 
 **Multiple Topics:**
 - If you need to research multiple unrelated topics of **truly distinct scope**, you may emit multiple `research` calls **simultaneously in a single turn**. Each call gets its own isolated research run with its own coordinator and researchers.
+- **Maximum 4 simultaneous calls** — Do NOT make more than 4 `research` calls in a single turn, even if you have more unrelated topics. Exceeding 4 simultaneous research runs can overload the system and degrade performance. If you have more than 4 truly distinct topics, they can likely be consolidated into fewer calls (group related subtopics, use broader queries, or batch across multiple turns).
 - Example: `research("bananas")` and `research("quantum computing")` in the same turn — these have zero overlap.
 - **Group related topics**: If topics share ANY scope or could inform each other, combine them into a single `research` call. The internal coordinator will decompose them into parallel researcher agents. Do NOT split related sub-topics into separate calls.
 - Example: `research("Python async performance and Rust async performance comparison")` — NOT separate calls for Python and Rust, since the comparison IS the research goal.

package/dist/thread-worker.mjs

@@ -2219,6 +2219,8 @@ var ConfigSchema = Type.Object({
   RESEARCHER_MAX_RETRIES: Type.Number({ minimum: 0, maximum: 5, default: 2 }),
   /** Base delay between retries in milliseconds (default: 2000, range: 100-10000) */
   RESEARCHER_MAX_RETRY_DELAY_MS: Type.Number({ minimum: 100, maximum: 1e4, default: 2e3 }),
+  /** Unique researcher failures that abort the entire run (default: 2, range: 1-10) */
+  MAX_FAILED_RESEARCHERS: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
   /** Target depth for recursive research (default: 1, range: 1-3) */
   DEFAULT_RESEARCH_DEPTH: Type.Number({ minimum: 1, maximum: 3, default: 1 }),
   /** Number of batches to allow for a single scrape tool call (default: 2, 0=unlimited) */

package/docs/ARCHITECTURE.md

@@ -84,10 +84,23 @@ Two conventions apply:
   report. A mid-round evaluation that cannot be parsed continues the existing agenda
   rather than finalizing early, so a parse failure never truncates a run.
 
-### Research tools
+### Tool inventory
 
-Each researcher has a fixed tool set and a shared budget of 12 gathering calls per phase
-(`MAX_GATHERING_CALLS`).
+This is the canonical list of every tool the system exposes, on both surfaces.
+
+**Host-facing tools** — registered with the pi session (`src/index.ts`) for the calling
+agent to invoke:
+
+| Tool | Purpose |
+|------|---------|
+| `research` | Run a full multi-source research session and return the cited Markdown report |
+| `research_knowledge_search` | Instant local search of the knowledge store — checked before live research; always registered, reports why when the store is disabled |
+| `health` | Verify system status (browser pool, knowledge store, GPU lock); optional liveness probe |
+
+**Researcher-agent tools** — the fixed set each researcher sub-agent works with
+(`src/tools/index.ts`). `search`, `security_search`, `stackexchange`, and
+`youtube_transcript` share a budget of 12 gathering calls per phase
+(`MAX_GATHERING_CALLS`); `scrape` and local `grep` have their own budgets:
 
 | Tool | Quick | Deep | Backend |
 |------|-------|------|---------|
@@ -102,7 +115,9 @@ Each researcher has a fixed tool set and a shared budget of 12 gathering calls p
 In deep research `search` is excluded — the coordinator runs the search burst and hands
 out URLs directly. In quick research `grep` is excluded — the single session is not
 expected to traverse a local codebase. Researchers cannot write files, run shell
-commands, or reach the network outside these tools.
+commands, or reach the network outside these tools. Individual researcher tools can be
+disabled per run with `PI_RESEARCH_DISABLED_TOOLS`
+(see [CONFIGURATION.md](CONFIGURATION.md)).
 
 ### Browser infrastructure
 

package/docs/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.8] - 2024-07-17
+
+### Added
+- **CHANGELOG** — Added comprehensive CHANGELOG.md documenting all versions from 0.1.13 through 1.0.7
+- **System prompt constraint** — Added "Maximum 4 simultaneous calls" constraint to research-tool-usage prompt to prevent system overload
+
+### Changed
+- **Topic consolidation guidance** — Emphasized that topics can likely be consolidated to fit the 4-call maximum, with strategies for grouping related subtopics
+- **Package structure** — CHANGELOG.md now included in published package (docs/CHANGELOG.md)
+
+## [1.0.7] - 2024-07-14
+
+### Fixed
+- **Browser-pool leader-election race** - Fixed a critical bug where a single client's transient socket error could force-clear shared leader state, causing a live, healthy leader to self-destruct via the leadership-miss watchdog. The fix reserves the "unreachable, force clear" path for cases where liveness probes actually confirm the registered leader PID or port is gone.
+- **Researcher retry-exemption** - Fixed the "no initial search results or historical links" failure path that bypassed the retry loop entirely. This now routes through the same `RESEARCHER_MAX_RETRIES`/`RESEARCHER_MAX_RETRY_DELAY_MS` retry loop as other failures.
+- **Exit-code misclassification** - Fixed false-positive classification of "Research stopped" errors as config errors (exit 78) via substring matching on the boilerplate "API key" advice text. Error classification now properly distinguishes infrastructure failures from credential problems.
+- **Unsurfaced quality signals** - Added per-run error tracking and per-researcher grounding signals to the log output for better debugging of report quality variance.
+- **SIGINT/SIGTERM cancellation wiring** - Improved cancellation handling for graceful shutdown on interrupt signals.
+- **Multi-researcher citation-provenance folding** - Fixed citation provenance tracking when multiple researchers contribute to a report.
+- **Untitled YouTube video citation line** - Fixed citation formatting for YouTube videos without titles.
+
+### Security
+- Several hardening improvements from the adversarial-review audit:
+  - Migration abort safety gates
+  - Hollow-run detection gates
+  - Streaming caps for large responses
+  - Socket drain on Content-Length pre-screen throws
+  - Observer isolation improvements
+
+## [1.0.6] - 2024-07-01
+
+### Fixed
+- **Observer isolation** - Fixed `makeSafeObserver` proxying the observer directly, which could cause state leakage.
+
+### Documentation
+- Corrected depth-0 availability documentation
+- Fixed migration.ts attribution in architecture docs
+
+## [1.0.5] - 2024-06-28
+
+### Fixed
+- **Content-Length pre-screen throws** - Added proper body draining to prevent resource leaks
+- **TTL refresh for transcribed links** - Fixed TTL handling for YouTube transcripts
+
+### Fixed
+- **YouTube transcript provenance** - Fixed transcript provenance tracking in final report citations
+
+## [1.0.4] - 2024-06-25
+
+### Fixed
+- **Credential detection** - Detect pi keys by pi's own semantics, not file presence; registry no longer gated on auth.json
+- **Configuration clarity** - Updated docs to reflect that pi has configuration files, not a named 'auth' feature
+
+## [1.0.3] - 2024-06-20
+
+### Fixed
+- **Model resolution** - Require a configured model on the standalone CLI/skill; align SDK session model with RESEARCH_MODEL
+- **Configuration requirement** - Added proper error messages when model is not configured
+
+### Documentation
+- Updated installation and configuration documentation
+
+## [1.0.2] - 2024-06-15
+
+### Fixed
+- **Timeout robustness** - Improved timeout handling for long-running operations
+- De-emphasized the markdown-conversion fallback in favor of native HTML-to-markdown conversion
+
+## [1.0.1] - 2024-06-10
+
+### Fixed
+- Initial stable release after rebuild against current pi APIs
+- Stealth-browser stack integration
+
+## [0.1.13] - 2024-04-15
+
+### Added
+- Initial research functionality
+- Knowledge store integration
+- Multi-agent orchestration
+
+---
+
+## Deferred Findings (from v1.0.7 audit)
+
+The following issues were identified during the v1.0.7 audit but intentionally deferred to future releases:
+
+1. **KnowledgeStore.close() timeout behavior** - The close() method proceeds even when the pending-write wait times out. A correct fix requires threading cancellation tokens through write paths or documenting the 10s timeout as intended behavior.
+
+2. **Cross-session teardown via shared singletons** - Session shutdown handlers run process-wide cleanup for reload/new/fork events. The correct behavior depends on pi's session model semantics and needs further investigation.
+
+3. **Lower-severity hardening items** - Various low-confidence or low-impact findings noted for future investigation:
+   - SIGINT-adjacent cancellation race
+   - Knowledge-store migration vs. concurrent access
+   - Global activity gate reused for per-session decisions
+   - Zombie queued browser tasks after timeout
+   - Non-atomic `clearBrowserServer`
+   - Inconsistent `knowledge --json` payload shapes
+   - Backward-clock-step tolerance across multiple rate limiters
+
+See `DEFERRED-FINDINGS-2026-07-14.md` for full details.

package/docs/CONFIGURATION.md

@@ -73,6 +73,7 @@ Research
 | `PI_RESEARCH_MAX_CONCURRENT_SCRAPES` | `3` | 1–20 | Concurrent URLs fetched per scrape batch. |
 | `PI_RESEARCH_MAX_RETRIES` | `2` | 0–5 | Retries per researcher request. |
 | `PI_RESEARCH_RETRY_DELAY_MS` | `2000` | 100–10000 | Base delay between retries. |
+| `PI_RESEARCH_MAX_FAILED_RESEARCHERS` | `2` | 1–10 | Unique researcher failures that abort the whole run. Raise to let slower, still-in-flight researchers finish before giving up. |
 | `PI_RESEARCH_WORKER_THREADS` | `4` | 1–10 | Browser worker processes. Higher = more throughput, more CPU/RAM. |
 | `PI_RESEARCH_WORKER_CONCURRENCY` | `2` | 1–10 | Tasks per worker process. |
 | `PI_RESEARCH_MODEL` | _(pi: session model; CLI/skill: required)_ | — | The model research runs on. **Required for the standalone CLI / agent skill** — they use only this configured model (never the model selected inside the pi extension) and refuse to start without one (the CLI's per-run `--model` flag also satisfies this). On the SDK it selects the session model when no `model` option is given. In the pi extension it overrides researcher sub-agents and knowledge synthesis, while the coordinator and evaluator keep using the session model. Accepts `provider/id` or a bare model id. |

package/docs/SDK.md

@@ -76,7 +76,10 @@ await shutdownResearchSDK();
 `runResearchDetailed`, `searchKnowledge`, `scrapeUrl`, `getResearchHealth`,
 `getLastRunStats`, and `getSessionMetrics`, plus `exportKnowledge` (write the
 knowledge store to a web-consumable JSON file) and the post-run telemetry accessors
-`getLastRunMetrics`, `getLastRunSummary`, and `getLastErrorReport`. Both
+`getLastRunMetrics`, `getLastRunSummary`, `getLastErrorReport`, and
+`getLastResearcherOutcome` (planned/launched/succeeded/failed researcher counts plus
+per-researcher failure reasons for the most recent run — lets a caller tell a thin
+report caused by a sparse topic apart from one where most researchers failed). Both
 `@lincoln504/pi-research` and `@lincoln504/pi-research/sdk` export these symbols.
 
 > Concurrency: a single initialized SDK instance runs one research call at a time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "A set of web research tools (search, scrape, and others) and research agent system that uses them safely and efficiently.",
   "type": "module",
   "private": false,
@@ -37,7 +37,8 @@
     "scripts/prepare.cjs",
     "LICENSE",
     "docs/THIRD-PARTY-NOTICES.md",
-    "README.md"
+    "README.md",
+    "docs/CHANGELOG.md"
   ],
   "repository": {
     "type": "git",
@@ -109,9 +110,9 @@
     "image": "https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/hero.png"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": ">=0.80.2 <1",
-    "@earendil-works/pi-coding-agent": ">=0.80.2 <1",
-    "@earendil-works/pi-tui": ">=0.80.2 <1",
+    "@earendil-works/pi-ai": ">=0.80.7 <1",
+    "@earendil-works/pi-coding-agent": ">=0.80.7 <1",
+    "@earendil-works/pi-tui": ">=0.80.7 <1",
     "@huggingface/transformers": "4.2.0",
     "@kreuzberg/html-to-markdown-node": "^3.5.5",
     "@lancedb/lancedb": "0.29.0",