@lincoln504/pi-research 1.0.5 → 1.0.8

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;
@@ -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/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`;
   }