@lincoln504/pi-research 0.1.12 → 1.0.0

package/src/orchestration/deep-research-types.ts

@@ -4,51 +4,63 @@
  * Defines the schema for the monolithic ResearchState persisted in the session tree.
  */
 
-export type ResearchStatus = 'planning' | 'researching' | 'evaluating' | 'synthesizing' | 'completed' | 'failed';
-export type SiblingStatus = 'pending' | 'running' | 'completed' | 'failed';
+import { Type, type Static } from 'typebox';
 
-export type DeepResearchEvent =
-  | { type: 'PLANNING_COMPLETE'; agenda: string[]; initialCount: number }
-  | { type: 'SIBLING_STARTED'; id: string }
-  | { type: 'SIBLING_COMPLETED'; id: string; report: string }
-  | { type: 'SIBLING_FAILED'; id: string; error: string }
-  | { type: 'LINKS_SCRAPED'; links: string[] }
-  | { type: 'PROMOTION_STARTED'; id: string }
-  | { type: 'PROMOTION_DECISION'; nextQueries: string[]; finalSynthesis?: string; maxRounds: number }
-  | { type: 'SIBLING_TOKENS'; id: string; tokens: number; cost: number };
+export const ResearchStatusSchema = Type.Union([
+  Type.Literal('planning'),
+  Type.Literal('researching'),
+  Type.Literal('evaluating'),
+  Type.Literal('synthesizing'),
+  Type.Literal('completed'),
+  Type.Literal('failed')
+]);
 
-export interface ResearchSibling {
-  id: string; // e.g. "1.1", "2.1"
-  query: string;
-  status: SiblingStatus;
-  report?: string;
-  error?: string;
-  tokens?: number;
-  cost?: number;
-}
+export const SiblingStatusSchema = Type.Union([
+  Type.Literal('pending'),
+  Type.Literal('running'),
+  Type.Literal('completed'),
+  Type.Literal('failed')
+]);
 
-export interface SystemResearchState {
-  version: number;
-  rootQuery: string;
-  complexity: 1 | 2 | 3; // 1: Normal, 2: Deep, 3: Ultra
-  currentRound: number;
-  status: ResearchStatus;
-  lastUpdated: number;
+/**
+ * Individual research researcher (sibling) schema
+ */
+export const ResearchSiblingSchema = Type.Object({
+  id: Type.String(), // e.g. "1.1", "2.1"
+  query: Type.String(),
+  status: SiblingStatusSchema,
+  report: Type.Optional(Type.String()),
+  error: Type.Optional(Type.String()),
+  tokens: Type.Optional(Type.Number()),
+  cost: Type.Optional(Type.Number()),
+});
+
+/**
+ * Main deep research state schema
+ */
+export const SystemResearchStateSchema = Type.Object({
+  version: Type.Number(),
+  researchId: Type.String(), // Unique session ID
+  rootQuery: Type.String(),
+  complexity: Type.Union([Type.Literal(1), Type.Literal(2), Type.Literal(3)]), // 1: Normal, 2: Deep, 3: Ultra
+  currentRound: Type.Number(),
+  status: ResearchStatusSchema,
+  lastUpdated: Type.Number(),
   
   // The full exhaustive list of aspects planned by the initial coordinator
-  initialAgenda: string[];
+  initialAgenda: Type.Array(Type.String()),
   
   // Global pool updated IMMEDIATELY by the scrape tool
-  allScrapedLinks: string[];
+  allScrapedLinks: Type.Array(Type.String()),
   
   // Sequence of research aspects actively being worked or completed
-  aspects: {
-    [id: string]: ResearchSibling;
-  };
+  aspects: Type.Record(Type.String(), ResearchSiblingSchema),
   
   // Track who was promoted to Lead Evaluator in this round to prevent race conditions
-  promotedId?: string;
+  promotedId: Type.Optional(Type.String()),
 
   // Final result if completed
-  finalSynthesis?: string;
-}
+  finalSynthesis: Type.Optional(Type.String()),
+});
+
+export type SystemResearchState = Static<typeof SystemResearchStateSchema>;

package/src/orchestration/headless-observer.ts

@@ -0,0 +1,114 @@
+/**
+ * Headless Research Observer
+ *
+ * A clean implementation of the ResearchObserver interface that forwards
+ * events to callbacks or logs them, rather than updating a TUI.
+ * Ideal for programmatic SDK use.
+ */
+
+import { logger } from '../logger.ts';
+import type { ResearchObserver, HeadlessObserverOptions } from '../core/interfaces/observer-interfaces.ts';
+import type { ResearchPlan } from '../core/interfaces/research-plan-types.ts';
+
+export type { HeadlessObserverOptions };
+
+export class HeadlessObserver implements ResearchObserver {
+  constructor(private options: HeadlessObserverOptions = {}) {}
+
+  private emit(event: string, data?: any) {
+    if (this.options.enableLogging) {
+      logger.debug(`[HeadlessObserver] ${event}`, data);
+    }
+    // User-supplied SDK callback: a throw must not propagate into research
+    // event dispatch (same isolation TuiPulse applies to its subscribers).
+    try {
+      this.options.onProgress?.(event, data);
+    } catch (err) {
+      logger.debug('[HeadlessObserver] onProgress callback threw:', err);
+    }
+  }
+
+  onStart(query: string, complexity: number): void {
+    this.emit('start', { query, complexity });
+  }
+
+  onPlanningStart(attempt: number): void {
+    this.emit('planning_start', { attempt });
+  }
+
+  onPlanningProgress(status: string): void {
+    this.emit('planning_progress', { status });
+  }
+
+  onPlanningTokens(tokens: number, cost: number): void {
+    this.emit('planning_tokens', { tokens, cost });
+  }
+
+  onPlanningSuccess(plan: ResearchPlan): void {
+    this.emit('planning_success', { plan });
+  }
+
+  onRoundStart(round: number): void {
+    this.emit('round_start', { round });
+  }
+
+  onSearchStart(queries: string[]): void {
+    this.emit('search_start', { queries });
+  }
+
+  onSearchProgress(resultsCount: number): void {
+    this.emit('search_progress', { resultsCount });
+  }
+
+  onSearchComplete(resultsCount: number): void {
+    this.emit('search_complete', { resultsCount });
+  }
+
+  onResearcherStart(id: string, name: string, goal: string, roundNumber?: number): void {
+    this.emit('researcher_start', { id, name, goal, roundNumber });
+  }
+
+  onResearcherProgress(id: string, status?: string, tokens?: number, cost?: number): void {
+    this.emit('researcher_progress', { id, status, tokens, cost });
+  }
+
+  onResearcherComplete(id: string, report: string): void {
+    this.emit('researcher_complete', { id, report });
+  }
+
+  onResearcherFailure(id: string, error: string): void {
+    this.emit('researcher_failure', { id, error });
+  }
+
+  onToolResult(researcherId: string, success: boolean): void {
+    this.emit('tool_result', { researcherId, success });
+  }
+
+  onEvaluationStart(round: number): void {
+    this.emit('evaluation_start', { round });
+  }
+
+  onEvaluationProgress(status: string): void {
+    this.emit('evaluation_progress', { status });
+  }
+
+  onEvaluationTokens(tokens: number, cost: number): void {
+    this.emit('evaluation_tokens', { tokens, cost });
+  }
+
+  onEvaluationDecision(action: 'synthesize' | 'delegate', plan?: ResearchPlan, round?: number): void {
+    this.emit('evaluation_decision', { action, plan, round });
+  }
+
+  onComplete(result: string): void {
+    this.emit('complete', { result });
+  }
+
+  onError(error: Error): void {
+    this.emit('error', { message: error.message });
+  }
+
+  onTokensConsumed(tokens: number, cost: number): void {
+    this.emit('tokens_consumed', { tokens, cost });
+  }
+}

package/src/orchestration/orchestration-types.ts

@@ -0,0 +1,33 @@
+/**
+ * Research Orchestration Types
+ */
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { Model } from '@earendil-works/pi-ai';
+import type { ResearcherConfig } from '../core/service-interfaces.ts';
+import type { IPlanningService } from '../core/interfaces/planning-interfaces.ts';
+import type { StoreUrlEntry } from '../core/interfaces/knowledge-interfaces.ts';
+import type { Config } from '../config.ts';
+import type { ResearchObserver } from '../core/interfaces/observer-interfaces.ts';
+export type { RunResearchersOptions } from '../core/interfaces/orchestration-interfaces.ts';
+
+/**
+ * Options for running a single researcher
+ */
+export interface RunResearcherOptions {
+  config: ResearcherConfig;
+  initialLinks: string[];
+  historicalUrls: StoreUrlEntry[];
+  sessionId: string;
+  researchId: string;
+  round: number;
+  query: string;
+  complexity: 1 | 2 | 3;
+  ctx: ExtensionContext;
+  model: Model<any>;
+  researchConfig: Config;
+  planningService: IPlanningService;
+  observer?: ResearchObserver;
+  signal?: AbortSignal;
+  excludeTools?: string[];
+}