@lincoln504/pi-research 1.0.6 → 1.0.9

package/src/sdk.ts

@@ -22,11 +22,12 @@ import { getService, resetServiceContainer, getServiceContainer } from './core/s
 import type { ServiceContainer } from './core/service-registry.ts';
 import { ServiceNames } from './core/service-interfaces.ts';
 import type { IKnowledgeStoreService } from './core/interfaces/knowledge-interfaces.ts';
-import type { 
-  IResearchOrchestration, 
+import type {
+  IResearchOrchestration,
   IResearchSynthesisService,
-  ResearchOptions 
+  ResearchOptions
 } from './core/interfaces/orchestration-interfaces.ts';
+import type { IPlanningService } from './core/interfaces/planning-interfaces.ts';
 import type { Model } from '@earendil-works/pi-ai';
 import { type ExtensionContext, ModelRegistry } from '@earendil-works/pi-coding-agent';
 import { logger, createLogger, setLogger } from './logger.ts';
@@ -78,6 +79,22 @@ let _lastRunSummary: RunSummary | null = null;
 // run end when errors occurred, and consumers can read the full report after the run.
 let _lastErrorReport: ErrorReport | null = null;
 
+/**
+ * Researcher-outcome summary for the most recent runDeepResearch call: how many
+ * researchers were planned/launched vs. how many ultimately failed (never landed
+ * a report) vs. succeeded, plus the first recorded failure reason per failed
+ * researcher. Lets a caller distinguish "thin report, little material out there"
+ * from "thin report because most researchers died" without opening the log file.
+ */
+export interface ResearcherOutcome {
+  planned: number;
+  launched: number;
+  succeeded: number;
+  failed: number;
+  failureReasons: Record<string, string>;
+}
+let _lastResearcherOutcome: ResearcherOutcome | null = null;
+
 // Signal handler state — registered once, removed on clean shutdown.
 let _onSignal: ((signal: string) => void) | null = null;
 let _sigintHandler: (() => void) | null = null;
@@ -269,7 +286,7 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
   }
 
   // Build and cache the registry (one instance for the lifetime of this init cycle).
-  globalRegistry = sharedBuildModelRegistry(globalApiKey, parsedProvider);
+  globalRegistry = await sharedBuildModelRegistry(globalApiKey, parsedProvider);
 
   try {
     // Resolve the model. Precedence: explicit option (a Model object is used
@@ -512,6 +529,7 @@ export async function runDeepResearch(
     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();
@@ -524,6 +542,7 @@ export async function runDeepResearch(
     metrics.recordRunSummary(_lastRunSummary);
     _lastErrorReport = runTracker.getReport();
     logRunErrorSummary(_lastErrorReport, depthLabel, 'error');
+    _lastResearcherOutcome = await captureResearcherOutcome(sessionId, researchId, _lastRunSummary.snapshot);
     throw err;
   } finally {
     // Free the per-run PiSessionState that shouldStopResearch()/getFailedResearchers()
@@ -564,6 +583,14 @@ export function getLastErrorReport(): ErrorReport | null {
   return _lastErrorReport;
 }
 
+/**
+ * Researcher-outcome summary (planned/launched/succeeded/failed + failure reasons)
+ * for the most recent run. Null until the first run completes; cleared on shutdown.
+ */
+export function getLastResearcherOutcome(): ResearcherOutcome | null {
+  return _lastResearcherOutcome;
+}
+
 /**
  * Emit a single compact line summarizing a run's tracked errors, so they are visible in
  * the operator's log instead of silently accumulating. No-op when the run was clean.
@@ -576,6 +603,31 @@ function logRunErrorSummary(report: ErrorReport | null, depthLabel: string, stat
   logger.warn(`[SDK] run ${status} with ${report.totalErrors} tracked error(s) across ${report.uniquePatterns} pattern(s) [${depthLabel}]${top ? ` — top: ${top}` : ''}`);
 }
 
+/**
+ * Capture how many researchers were planned/launched/failed for this run, BEFORE
+ * the caller's `finally` block frees the PiSessionState (endResearchSession) that
+ * getFailedResearchers()/getResearcherFailureReasons() read from. Best-effort:
+ * this is instrumentation only and must never affect the run's own result.
+ */
+async function captureResearcherOutcome(sessionId: string, researchId: string, snapshot: IMetricsSnapshot): Promise<ResearcherOutcome | null> {
+  try {
+    const planningService = await getService<IPlanningService>(ServiceNames.PLANNING, undefined, 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;
+  }
+}
+
 /**
  * Distilled, human-relevant stats from the most recent run (researchers launched,
  * searches, URLs analyzed/failed, tokens, cost, per-tool usage). Null if no run
@@ -744,7 +796,7 @@ export async function searchKnowledge(
   };
 }
 
-import { clearAllSessionState, endResearchSession } from './orchestration/session-state.ts';
+import { clearAllSessionState, endResearchSession, getFailedResearchers, getResearcherFailureReasons } from './orchestration/session-state.ts';
 import { shutdownManager } from './utils/shutdown-manager.ts';
 
 /**
@@ -833,6 +885,7 @@ async function _doShutdown(): Promise<void> {
   _lastResearchId = null;
   _lastRunSummary = null;
   _lastErrorReport = null;
+  _lastResearcherOutcome = null;
   // The module-level config cache survives the globals above. Without this, a
   // shutdown → env/config-file change → re-init cycle in one process silently
   // reuses the first init's config. (The CLI/skill are unaffected — they pass

package/src/utils/make-resource-loader.ts

@@ -5,31 +5,21 @@
  * Both files use identical ResourceLoader implementations.
  */
 
-import type { ResourceLoader, ExtensionRuntime } from '@earendil-works/pi-coding-agent';
+import { createExtensionRuntime, type ResourceLoader } from '@earendil-works/pi-coding-agent';
 
 export function makeResourceLoader(systemPromptText: string): ResourceLoader {
-  const mockRuntime: ExtensionRuntime = {
-    flagValues: new Map(),
-    pendingProviderRegistrations: [],
-    registerProvider: () => {},
-    unregisterProvider: () => {},
-    sendMessage: async () => {},
-    sendUserMessage: async () => {},
-    appendEntry: async () => {},
-    setSessionName: () => undefined,
-    getSessionName: () => undefined,
-    setLabel: async () => {},
-    getActiveTools: () => [],
-    getAllTools: () => [],
-    setActiveTools: () => {},
-    refreshTools: () => {},
-    getCommands: () => [],
-    setModel: async () => true,
-    getThinkingLevel: () => 'off',
-    setThinkingLevel: () => {},
-    assertActive: () => {},
-    invalidate: () => {},
-  };
+  // Use pi's own createExtensionRuntime() instead of hand-maintaining a mock.
+  //
+  // A literal mock object drifted out of sync with the ExtensionRuntime contract:
+  // pi 0.81.0 ("Full provider extensions") added `pendingNativeProviderRegistrations`
+  // + `registerNativeProvider`, which this mock omitted. Under pi >= 0.81.0 the
+  // host's runner.bindCore() / createAgentSessionServices() iterate that field —
+  // `for (... of runtime.pendingNativeProviderRegistrations)` — and an `undefined`
+  // field threw `this.runtime.pendingNativeProviderRegistrations is not iterable`,
+  // aborting EVERY researcher session ("Research produced no report — no source
+  // material was collected"). createExtensionRuntime() always returns a runtime
+  // that satisfies the current host's full contract, so this can't drift again.
+  const mockRuntime = createExtensionRuntime();
 
   return {
     getExtensions: () => ({ extensions: [], errors: [], runtime: mockRuntime }),

package/src/web-research/browser-search.ts

@@ -61,10 +61,22 @@ export async function performSearch(
     if (onProgress) onProgress(0);
 
     // Hard cap per query so a single Cloudflare block or hung browser worker
-    // cannot stall the entire Promise.all burst. Derived from the configured
-    // search timeout (default 45s) so raising SEARCH_TIMEOUT_MS actually takes
-    // effect here instead of being silently overridden by a lower literal.
-    const QUERY_TIMEOUT_MS = config?.SEARCH_TIMEOUT_MS ?? 45_000;
+    // cannot stall the entire Promise.all burst.
+    //
+    // The budget is the worker's nav budget (SEARCH_TIMEOUT_MS) PLUS the
+    // queue-wait/overhead margin (BROWSER_TASK_TIMEOUT_MS), mirroring the
+    // scheduler's own task-timeout ceiling in BrowserTaskScheduler.runSearch
+    // (= SEARCH_TIMEOUT_MS + BROWSER_TASK_TIMEOUT_MS). This clock starts at
+    // ENQUEUE (before runWorkerSearch queues onto the shared browser pool), so
+    // a budget of only SEARCH_TIMEOUT_MS would let a query that sat in the
+    // saturated worker queue burn its ENTIRE nav budget waiting for a slot and
+    // abort with zero actual search work — exactly the "Query timed out after
+    // 45000ms (likely blocked or slow startup)" cascade observed under
+    // concurrent load. Including the margin lets a queued query still use its
+    // full nav budget once a worker picks it up, and keeps this layer's hard
+    // cap coherent with the scheduler's so it never preempts the worker's own
+    // (post-dequeue) deadline.
+    const QUERY_TIMEOUT_MS = (config?.SEARCH_TIMEOUT_MS ?? 45_000) + (config?.BROWSER_TASK_TIMEOUT_MS ?? 10_000);
 
     const filteredQueries = queries.filter(q => q.trim());
     let timeoutCount = 0;
@@ -133,7 +145,7 @@ export async function performSearch(
             metrics.increment('browser_search_queries_total', 1, { status });
             
             if (isTimeout) {
-                logger.warn(`[Search] Query timed out after ${QUERY_TIMEOUT_MS}ms (likely blocked or slow startup): "${query}"`);
+                logger.warn(`[Search] Query timed out after ${QUERY_TIMEOUT_MS}ms — likely starved waiting for a free browser worker under concurrent load, or a slow/blocked search provider: "${query}"`);
             } else {
                 const msg = error instanceof Error ? error.message : String(error);
                 if (msg !== 'Aborted') {

package/src/youtube/index.ts

@@ -126,10 +126,11 @@ function formatResults(results: VideoTranscript[], rejected: string[]): string {
     // citation pipeline (parseCitations extracts URLs), so the transcript's
     // provenance would silently drop out of the final report's CITED LINKS.
     // The title/channel follows so the report names the real video, not a
-    // paraphrase (the watch URL alone is not human-identifiable).
-    if (r.title) {
-      md += `**Cite as:** ${r.url} — '${r.title}'${r.author ? ` by ${r.author}` : ''}\n`;
-    }
+    // paraphrase (the watch URL alone is not human-identifiable). Emit this line
+    // unconditionally — an untitled video still needs a parseable "Cite as" the
+    // model can copy verbatim; omitting the line entirely for untitled videos
+    // left them without any prompt-visible citation string to reuse.
+    md += `**Cite as:** ${r.url}${r.title ? ` — '${r.title}'${r.author ? ` by ${r.author}` : ''}` : ''}\n`;
     md += `\n${r.text}\n\n---\n\n`;
   }