@lincoln504/pi-research 0.1.12 → 1.0.0

package/src/core/interfaces/knowledge-interfaces.ts

@@ -0,0 +1,190 @@
+/**
+ * Knowledge Store Service Interfaces
+ */
+
+import type { IService } from '../service-registry.ts';
+
+/**
+ * Single document record in the knowledge store
+ */
+export interface StoreDocument {
+  url: string;
+  text: string;
+  content?: string;
+  metadata: Record<string, any>;
+  timestamp: number;
+  workspace?: string;
+  is_global?: boolean;
+  ingestion_type?: string;
+}
+
+/**
+ * ONNX runtime environment
+ */
+export interface ONNXRuntimeEnv {
+  logLevel?: 'verbose' | 'info' | 'warning' | 'error' | 'fatal';
+  debug?: boolean;
+}
+
+/**
+ * HuggingFace environment with ONNX support (Transformers.js v4)
+ */
+export interface HFEnv {
+  cacheDir: string;
+  backends: {
+    onnx: ONNXRuntimeEnv;
+  };
+}
+
+/**
+ * Disposable pipeline interface
+ */
+export interface DisposablePipeline {
+  dispose(): Promise<void>;
+}
+
+/**
+ * Embedder configuration options
+ */
+export interface EmbedderOptions {
+  model: string;
+  pooling?: 'mean' | 'cls' | 'last_token';
+  queryPrefix?: string;
+  initializationTimeoutMs?: number;
+  device?: string;
+  maxTokens?: number;
+  batchSize?: number;
+  charsPerToken?: number;
+  documentPrefix?: string;
+  stateManager?: any; // To avoid circular dependency with IStateManager
+  useCache?: boolean;
+}
+
+/**
+ * Embedder state
+ */
+export type EmbedderState = 'idle' | 'initializing' | 'ready' | 'failed' | 'disposing';
+
+/**
+ * Item to be ingested into the knowledge store
+ */
+export interface IngestionItem {
+  url: string;
+  markdown: string;
+  content?: string;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * A URL entry returned from the knowledge store with its description
+ */
+export interface StoreUrlEntry {
+  url: string;
+  description: string;
+  provenance?: string;
+}
+
+/**
+ * Embedder interface for text embedding operations
+ */
+export interface IEmbedder {
+  getDevice(): string | null;
+  getOriginalDevice(): string | null;
+  getDimension(): number | null;
+  setDimension(dim: number): void;
+  isInitialized(): boolean;
+  embed(text: string): Promise<Float32Array | number[]>;
+  embedMany(texts: string[]): Promise<(Float32Array | number[])[]>;
+  dispose(): Promise<void>;
+}
+
+/**
+ * Core Knowledge Store interface for raw storage operations.
+ */
+export interface IKnowledgeStore extends IService {
+  open(): Promise<void>;
+  close(): Promise<void>;
+  clear(filter?: string): Promise<void>;
+  /** Rebuild FTS indexes; returns true if a rebuild ran, false if skipped (empty/unchanged). */
+  rebuildFtsIndex(): Promise<boolean>;
+  /** Compact data fragments and prune stale versions/indices to reclaim disk. Returns true if it ran. */
+  optimize(options?: { cleanupOlderThan?: Date; deleteUnverified?: boolean }): Promise<boolean>;
+  count(): Promise<number>;
+  search(query: string, options?: { limit?: number }): Promise<StoreDocument[]>;
+  findRelevantUrls(query: string, options?: { limit?: number }): Promise<StoreUrlEntry[]>;
+  rebuildDocument(url: string): Promise<{ text: string; description: string | null; metadata: Record<string, any>; ageDays?: number } | null>;
+  findDocumentsByUrl(url: string): Promise<StoreDocument[]>;
+  findByUrl(url: string): Promise<StoreDocument[]>;
+  countScoped(workspace?: string): Promise<{ local: number; global: number; projects: number }>;
+  
+  /** Extended operations */
+  addDocuments(docs: StoreDocument[]): Promise<void>;
+  deleteByUrl(url: string): Promise<void>;
+  deleteByUrlAndType(url: string, ingestionType: string): Promise<void>;
+  isStoreClosed?(): boolean;
+
+  /**
+   * Export the knowledge store entries (summaries and vectors) for use in a web application.
+   * @param outputPath - Path to save the exported JSON file
+   */
+  exportForWeb(outputPath: string): Promise<void>;
+}
+
+/**
+ * Higher-level service interface for Knowledge Store management.
+ */
+export interface IKnowledgeStoreService extends IService {
+  isReady(): boolean;
+  /** The working directory this service initialized against (from ctx.cwd). */
+  getCwd(): string;
+  /**
+   * Why the store is DISABLED, if it is: 'native' (no ML/vector native stack on this
+   * platform — permanent), 'mode' (Knowledge Mode is/was `none` — revivable), or null
+   * (not disabled). Lets an observer report the accurate reason without forcing init.
+   */
+  getDisabledReason(): 'mode' | 'native' | null;
+  getDevice(): string | null;
+  getStore(): Promise<IKnowledgeStore | null>;
+  getEmbedder(): Promise<IEmbedder | null>;
+  getWriterQueue(): Promise<IWriterQueue | null>;
+  clear(): Promise<void>;
+  clearLocal(): Promise<void>;
+  clearGlobal(): Promise<void>;
+  
+  /**
+   * Export the knowledge store for web use.
+   * @param outputPath - Path to save the exported JSON file
+   */
+  exportForWeb(outputPath: string): Promise<void>;
+}
+
+/**
+ * Writer queue interface for batching write operations
+ */
+export interface IWriterQueue extends IService {
+  drain(): Promise<void>;
+  enqueue(item: IngestionItem): void;
+}
+
+/**
+ * Metrics snapshot interface
+ */
+export interface IMetricsSnapshot {
+  counters: Record<string, number>;
+  gauges: Record<string, number>;
+  histograms: Record<string, IMetricHistogram>;
+}
+
+/**
+ * Metric histogram statistics interface
+ */
+export interface IMetricHistogram {
+  count: number;
+  min: number;
+  max: number;
+  avg: number;
+  p50: number;
+  p90: number;
+  p95: number;
+  p99: number;
+}

package/src/core/interfaces/observer-interfaces.ts

@@ -0,0 +1,67 @@
+/**
+ * Observer Interfaces
+ *
+ * Defines the ResearchObserver interface used by the planning service and
+ * orchestration layer to emit research lifecycle events. Lives in core/interfaces
+ * so both planning-interfaces.ts and the orchestration layer can import it
+ * without creating a circular dependency.
+ */
+
+import type { ResearchPlan } from './research-plan-types.ts';
+export interface HeadlessObserverOptions {
+  /** Callback for progress updates */
+  onProgress?: (event: string, data?: any) => void;
+  /** Whether to log events to the console/logger */
+  enableLogging?: boolean;
+}
+
+export interface ResearchObserver {
+  onStart?(query: string, complexity: number): void;
+
+  // Coordinator/Planning phase
+  onPlanningStart?(attempt: number): void;
+  onPlanningProgress?(status: string): void;
+  onPlanningTokens?(tokens: number, cost: number): void;
+  onPlanningSuccess?(plan: ResearchPlan): void;
+
+  // Research phase (rounds)
+  onRoundStart?(round: number): void;
+  onSearchStart?(queries: string[]): void;
+  onSearchProgress?(resultsCount: number): void;
+  onSearchComplete?(resultsCount: number): void;
+
+  // Individual researcher agents
+  onResearcherStart?(id: string, name: string, goal: string, roundNumber?: number): void;
+  onResearcherProgress?(id: string, status?: string, tokens?: number, cost?: number): void;
+  onResearcherTokensHint?(id: string, inputTokens: number): void;
+  onResearcherComplete?(id: string, report: string): void;
+  onResearcherFailure?(id: string, error: string): void;
+
+  /** Per-URL or per-tool-action result feedback (triggers TUI flash). */
+  onToolResult?(researcherId: string, success: boolean): void;
+
+  // Evaluation phase
+  onEvaluationStart?(round: number): void;
+  onEvaluationProgress?(status: string): void;
+  onEvaluationTokens?(tokens: number, cost: number): void;
+  onEvaluationDecision?(action: 'synthesize' | 'delegate', plan?: ResearchPlan, round?: number): void;
+
+  // Synthesis/Completion
+  /**
+   * Fired when the run enters FINAL synthesis / stops consuming steering:
+   *   - deep mode: right before the forced (mustSynthesize) evaluator call, and
+   *     on the evaluator-chose-synthesize path (idempotent there — the flag is
+   *     already off via onEvaluationDecision('synthesize')).
+   *   - quick mode: as soon as the researcher session settles, i.e. the point
+   *     the 500ms steering-consume poller stops running.
+   * TUI consequence: steeringAcceptable flips false, so a late steer takes the
+   * fall-through path (forwarded to pi with an accurate toast) instead of being
+   * queued for a "next round" that will never happen.
+   */
+  onSynthesisStart?(): void;
+  onComplete?(result: string): void;
+  onError?(error: Error): void;
+
+  // Global token/cost tracking
+  onTokensConsumed?(tokens: number, cost: number): void;
+}

package/src/core/interfaces/orchestration-interfaces.ts

@@ -0,0 +1,86 @@
+/**
+ * Orchestration Service Interfaces
+ */
+
+import type { IService } from '../service-registry.ts';
+import type { Config } from '../../config.ts';
+import type { ResearchPlan, ResearcherConfig } from './planning-interfaces.ts';
+import type { QueryResultWithError } from '../../web-research/types.ts';
+import type { StoreUrlEntry } from './knowledge-interfaces.ts';
+
+import type { Model } from '@earendil-works/pi-ai';
+import type { ExtensionContext, AgentToolResult } from '@earendil-works/pi-coding-agent';
+import type { ResearchObserver, HeadlessObserverOptions } from './observer-interfaces.ts';
+import type { SteeringMessage } from './steering-interfaces.ts';
+
+/**
+ * Options for running a research task
+ */
+export interface ResearchOptions {
+  ctx: ExtensionContext;
+  query: string;
+  depth?: 0 | 1 | 2 | 3;
+  complexity?: 1 | 2 | 3;
+  model?: Model<any>;
+  observer?: ResearchObserver | HeadlessObserverOptions;
+  onUpdate?: (update: AgentToolResult<any>) => void;
+  sessionId: string;
+  researchId: string;
+  config?: Config;
+  excludeTools?: string[];
+  initialLinks?: string[];
+  signal?: AbortSignal;
+}
+
+/**
+ * Options for running researchers in parallel
+ */
+export interface RunResearchersOptions {
+  plan: { researchers?: ResearcherConfig[] };
+  options: {
+    sessionId: string;
+    researchId: string;
+    query: string;
+    complexity: 1 | 2 | 3;
+    excludeTools?: string[];
+    ctx: ExtensionContext;
+    model: Model<any>;
+    config?: Config;
+    observer?: ResearchObserver;
+    initialLinks?: string[];
+  };
+  currentRound: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * Research Synthesis Service Interface
+ */
+export interface IResearchSynthesisService extends IService {
+  storeReport(researchId: string, researcherId: string, report: string): void;
+  getAllReports(researchId: string): Map<string, string>;
+  getReport(researchId: string, id: string): string | undefined;
+  getReportsForRound(researchId: string, round: number): Map<string, string>;
+  getReportCount(researchId: string): number;
+  hasReports(researchId: string): boolean;
+  clearReports(researchId?: string): void;
+  buildFallbackSynthesis(researchId: string, currentRound?: number): string;
+  ensureCitedLinks(researchId: string, result: string): string;
+  appendSteeringGuidance(result: string, steeringMessages: SteeringMessage[]): string;
+  appendMetadata(result: string, modelId: string): string;
+}
+
+/**
+ * Research Orchestration Service Interface
+ */
+export interface IResearchOrchestration extends IService {
+  resolveResearchModel(options: ResearchOptions): Promise<Model<any>>;
+  runResearch(options: ResearchOptions, signal?: AbortSignal): Promise<string>;
+  cleanupResearchServices(sessionId?: string, researchId?: string, ctx?: any, config?: Config, opts?: { skipStoreMaintenance?: boolean }): Promise<void>;
+  distributeSearchResults(plan: ResearchPlan, results: QueryResultWithError[], ctx?: any): Promise<Map<string, string[]>>;
+  runResearchers(options: RunResearchersOptions, researcherLinks?: Map<string, string[]>, storeLinks?: Map<string, StoreUrlEntry[]>, ctx?: any): Promise<void>;
+  runSearchBurst(queries: string[], config: Config, signal?: AbortSignal, onProgress?: (links: number) => void, ctx?: any): Promise<QueryResultWithError[]>;
+  storeLinkDescriptions(sessionId: string, round: number, researchId: string, config: Config, ctx?: any): Promise<void>;
+  // Advisory only — logs infrastructure health; research never aborts on the result.
+  checkHealth(round: number, researchId?: string, ctx?: any): Promise<void>;
+}

package/src/core/interfaces/planning-interfaces.ts

@@ -0,0 +1,100 @@
+/**
+ * Planning Service Interfaces
+ */
+
+import type { IService } from '../service-registry.ts';
+import type { Model } from '@earendil-works/pi-ai';
+import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
+import type { ResearchObserver } from './observer-interfaces.ts';
+import type { ResearchPlan, ResearcherConfig } from './research-plan-types.ts';
+import type { Config } from '../../config.ts';
+
+export type { ResearchPlan, ResearcherConfig };
+export { ResearcherConfigSchema, ResearchPlanSchema } from './research-plan-types.ts';
+
+/**
+ * Session context for planning operations
+ */
+export interface SessionContext {
+  sessionId: string;
+  researchId: string;
+}
+
+/**
+ * Options for generating a research plan
+ */
+export interface GeneratePlanOptions {
+  sessionId: string;
+  query: string;
+  complexity: 1 | 2 | 3;
+  model: Model<any>;
+  modelRegistry: ModelRegistry;
+  cwd: string;
+  signal?: AbortSignal;
+  observer?: ResearchObserver;
+  excludeTools?: string[];
+  steeringMessages?: string[];
+  /** Resolved config from the caller (SDK/orchestrator). Preferred over getConfig(cwd)
+   *  so SDK code-config and ignoreGlobalConfig hermeticity reach the coordinator call. */
+  config?: Config;
+}
+
+/**
+ * Options for generating queries for a researcher
+ */
+export interface GenerateQueriesOptions {
+  researcher: ResearcherConfig;
+  query: string;
+  complexity: 1 | 2 | 3;
+  model: Model<any>;
+  signal?: AbortSignal;
+}
+
+/**
+ * Options for updating plan for next round
+ */
+export interface UpdatePlanOptions {
+  sessionId: string;
+  reports: Map<string, string>;
+  round: number;
+  query: string;
+  complexity: 1 | 2 | 3;
+  model: Model<any>;
+  modelRegistry: ModelRegistry;
+  cwd: string;
+  signal?: AbortSignal;
+  previousPlan: ResearchPlan | null;
+  totalResearchersPlanned: number;
+  mustSynthesize?: boolean;
+  observer?: ResearchObserver;
+  excludeTools?: string[];
+  steeringMessages?: string[];
+  /** Resolved config from the caller (SDK/orchestrator). Preferred over getConfig(cwd)
+   *  so SDK code-config and ignoreGlobalConfig hermeticity reach the evaluator/synthesis call. */
+  config?: Config;
+}
+
+/**
+ * Planning service interface
+ */
+export interface IPlanningService extends IService {
+  generatePlan(options: GeneratePlanOptions): Promise<ResearchPlan>;
+  generateResearchers(plan: ResearchPlan, query: string, complexity: 1 | 2 | 3): ResearcherConfig[];
+  generateQueries(options: GenerateQueriesOptions): Promise<string[]>;
+  updatePlanForRound(options: UpdatePlanOptions): Promise<ResearchPlan>;
+  getQueryHistory(sessionId: string): string[];
+  addToQueryHistory(sessionId: string, queries: string[]): void;
+  getCurrentPlan(sessionId: string): ResearchPlan | null;
+  getTotalResearchersPlanned(sessionId: string): number;
+  incrementTotalResearchersPlanned(sessionId: string, count: number): void;
+  getTeamSize(complexity: 1 | 2 | 3): number;
+  getQueryBudget(complexity: 1 | 2 | 3): number;
+  getComplexityGuidance(complexity: 1 | 2 | 3, maxTeamSize: number, queryBudget: number): string;
+  getEvaluatorComplexityGuidance(complexity: 1 | 2 | 3): string;
+  getRoundPhaseGuidance(currentRound: number, maxRounds: number, complexity: 1 | 2 | 3, maxTeamSize: number): string;
+  capResearcherQueries(plan: ResearchPlan, complexity: 1 | 2 | 3, serviceName: string): ResearchPlan;
+  parseJsonPlan(text: string): ResearchPlan;
+  buildFallbackCoordinatorPlan(rawText: string, query: string): ResearchPlan;
+  clearPlanningState(sessionId?: string): void;
+  isReady(): boolean;
+}

package/src/core/interfaces/process-interfaces.ts

@@ -0,0 +1,37 @@
+/**
+ * Process Service Interfaces
+ */
+
+import type { IService } from '../service-registry.ts';
+
+/**
+ * Process Lifecycle Service Interface
+ */
+export interface IProcessLifecycle extends IService {
+  isProcessAlive(pid: number, expectedStartTime?: number | null): Promise<boolean>;
+  isProcessAliveSync(pid: number): boolean;
+  isPidAlive<TState>(
+    pid: number,
+    expectedSchedulerId?: string,
+    options?: {
+      getState?: (skipLock?: boolean) => Promise<TState>;
+      skipLock?: boolean;
+      getSchedulerIdFromState?: (state: TState) => string | undefined;
+      expectedStartTime?: number | null;
+    }
+  ): Promise<boolean>;
+  getCurrentPid(): number;
+  getProcessStartTime(pid: number): Promise<number | null>;
+  getCurrentProcessStartTime(): Promise<number | null>;
+  waitForProcessTermination(pid: number, timeoutMs?: number, checkIntervalMs?: number, expectedStartTime?: number | null): Promise<boolean>;
+  isCurrentProcess(pid: number): boolean;
+  getProcessInfo(pid: number): Promise<{ pid: number; alive: boolean; startTime?: number | null } | null>;
+}
+
+/**
+ * GPU Resource Service Interface
+ */
+export interface IGPUResourceService extends IService {
+  acquireGpuLock(sessionId?: string, timeoutMs?: number, ctx?: any): Promise<boolean>;
+  releaseGpuLock(pid?: number, ctx?: any): Promise<void>;
+}

package/src/core/interfaces/research-plan-types.ts

@@ -0,0 +1,52 @@
+/**
+ * Research Plan Types
+ *
+ * Core data types for research plans and researcher configuration.
+ * Lives in a separate file so both planning-interfaces.ts and
+ * observer-interfaces.ts can import without creating a circular dependency.
+ */
+
+import { Type, type Static } from 'typebox';
+
+// ============================================================================
+// TypeBox Schemas for Validation
+// ============================================================================
+
+/**
+ * Individual researcher configuration schema
+ */
+export const ResearcherConfigSchema = Type.Object({
+  id: Type.Union([Type.String(), Type.Number()]),
+  name: Type.String(),
+  goal: Type.String(),
+  queries: Type.Array(Type.String()),
+});
+
+/**
+ * Individual researcher configuration type
+ */
+export type ResearcherConfig = Static<typeof ResearcherConfigSchema>;
+
+/**
+ * Research plan structure schema
+ */
+export const ResearchPlanSchema = Type.Object({
+  action: Type.Optional(Type.Union([
+    Type.Literal('synthesize'),
+    Type.Literal('delegate'),
+    Type.Literal('wait')
+  ])),
+  // Optional at the schema level because a 'synthesize' response legitimately omits
+  // researchers (its contract is { action, content }). The delegate-requires-researchers
+  // invariant is enforced explicitly in parseJsonPlan() so that a valid synthesis is not
+  // misrouted into the agentic-repair path. See research-plan-types history / planning-utils.
+  researchers: Type.Optional(Type.Array(ResearcherConfigSchema)),
+  allQueries: Type.Optional(Type.Array(Type.String())),
+  content: Type.Optional(Type.String()),
+  title: Type.Optional(Type.String()),
+});
+
+/**
+ * Research plan structure type
+ */
+export type ResearchPlan = Static<typeof ResearchPlanSchema>;

package/src/core/interfaces/scheduler-interfaces.ts

@@ -0,0 +1,91 @@
+/**
+ * Scheduler Service Interfaces
+ */
+
+import type { IService } from '../service-registry.ts';
+import type { Config } from '../../config.ts';
+
+/**
+ * Minimal scheduler instance interface — the raw scheduler object returned
+ * by the factory and stored inside SchedulerService.
+ */
+export interface ISchedulerInstance {
+  shutdown(): Promise<void>;
+  schedulerId?: string;
+}
+
+/**
+ * Internal state management methods exposed by SchedulerService.
+ * Used by browser-lifecycle.ts and the infrastructure scheduler factory to manage
+ * scheduler instance state without creating a circular import on the SchedulerService class.
+ * Extends IService so it satisfies the tryGetService<T extends IService> constraint.
+ */
+export interface ISchedulerInternals extends IService {
+  getSchedulerInstance(): ISchedulerInstance | null;
+  setSchedulerInstance(instance: ISchedulerInstance | null): void;
+  getSchedulerVersion(): string | null;
+  setSchedulerVersion(version: string | null): void;
+  getSchedulerInitializationPromise(): Promise<ISchedulerInstance> | null;
+  setSchedulerInitializationPromise(promise: Promise<ISchedulerInstance> | null): void;
+  getPendingShutdownPromise(): Promise<void> | null;
+  setPendingShutdownPromise(promise: Promise<void> | null): void;
+  isSchedulerRestartInProgress(): boolean;
+  setSchedulerRestartInProgress(inProgress: boolean): void;
+}
+
+/**
+ * Scheduler service interface
+ */
+export interface ISchedulerService extends IService {
+  isReady(): boolean;
+  getScheduler(): IScheduler | null;
+}
+
+/**
+ * Scheduler search result — matches the shape returned by the browser
+ * infrastructure layer (BrowserTaskScheduler / BrowserClient).
+ */
+export interface SearchResult {
+  title: string;
+  url: string;
+  content: string;
+  engine?: string;
+  score?: number;
+}
+
+/**
+ * Scheduler scrape result — matches the shape returned by the browser
+ * infrastructure layer (BrowserTaskScheduler / BrowserClient).
+ */
+export interface ScrapeResult {
+  url: string;
+  success: boolean;
+  markdown: string;
+  error?: string;
+  source?: string;
+  layer?: string;
+  duration?: number;
+}
+
+/**
+ * Base scheduler interface
+ */
+export interface IScheduler {
+  runSearch(query: string, config?: Config, signal?: AbortSignal): Promise<SearchResult[]>;
+  runScrape(url: string, config?: Config, signal?: AbortSignal): Promise<ScrapeResult>;
+  runHealthCheck(config?: Config, signal?: AbortSignal): Promise<{ success: boolean }>;
+  shutdown(): Promise<void>;
+  resetIdleTimerOnActivity?(): void;
+  schedulerId?: string;
+}
+
+/**
+ * Scheduler service metadata
+ */
+export interface SchedulerMetadata {
+  schedulerId: string;
+  schedulerVersion: string;
+  port?: number;
+  pid: number;
+  isLeader: boolean;
+}

package/src/core/interfaces/service-names.ts

@@ -0,0 +1,39 @@
+/**
+ * Service Names (Constants)
+ */
+
+/**
+ * Standard service names used throughout the application
+ */
+export const ServiceNames = {
+  SCHEDULER: 'scheduler',
+  SCHEDULER_FACTORY: 'scheduler-factory',
+  HEALTH_CHECK_CACHE: 'health-check-cache',
+  STATE_MANAGER: 'state-manager',
+  KNOWLEDGE_STORE: 'knowledge-store',
+  WRITER_QUEUE: 'writer-queue',
+  METRICS: 'metrics',
+  PLANNING: 'planning',
+  PROCESS_LIFECYCLE: 'process-lifecycle',
+  RESEARCH_ORCHESTRATION: 'research-orchestration',
+  STATE_PATH_CONFIGURATION: 'state-path-configuration',
+  // Helper services for state management
+  FILE_LOCK_SERVICE: 'file-lock-service',
+  GPU_RESOURCE_SERVICE: 'gpu-resource-service',
+  STATE_SESSION_MANAGER: 'state-session-manager',
+  STATE_BROWSER_MANAGER: 'state-browser-manager',
+  STATE_BACKUP_MANAGER: 'state-backup-manager',
+  STATE_METRICS_COLLECTOR: 'state-metrics-collector',
+  STATE_VALIDATOR: 'state-validator',
+  HEALTH_REGISTRY: 'health-registry',
+  // Browser infrastructure services
+  WORKER_POOL_MANAGER: 'worker-pool-manager',
+  // Research session services
+  RESEARCH_SESSION_SERVICE: 'research-session-service',
+  RESEARCH_SYNTHESIS_SERVICE: 'research-synthesis-service',
+} as const;
+
+/**
+ * Type of service names
+ */
+export type ServiceName = typeof ServiceNames[keyof typeof ServiceNames];

package/src/core/interfaces/state-manager-interfaces.ts

@@ -0,0 +1,29 @@
+/**
+ * State Manager Service Interface
+ */
+
+import type { IService } from '../service-registry.ts';
+
+/**
+ * State manager service interface
+ */
+export interface IStateManager extends IService {
+  readState(): Promise<any>;
+  writeState(state: any): Promise<void>;
+  updateState(updater: (state: any) => any | Promise<any>): Promise<void>;
+  addSession(sessionId: string, param: number | string): Promise<void>;
+  removeSession(sessionId: string): Promise<void>;
+  updateHeartbeat(sessionId: string): Promise<void>;
+  cleanupStaleSessions(timeoutMs: number): Promise<number>;
+  getBrowserServer(): Promise<{ port: number; pid: number; schedulerId?: string; authSecret?: string } | null>;
+  setBrowserServer(port: number, pid: number, schedulerId?: string, authSecret?: string): Promise<void>;
+  clearBrowserServer(): Promise<void>;
+  getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string } | null>;
+  clearEmbeddingServer(): Promise<void>;
+  isPidAlive(pid: number, expectedSchedulerId?: string, skipLock?: boolean): Promise<boolean>;
+  acquireGpuLock(sessionId?: string, timeoutMs?: number): Promise<boolean>;
+  releaseGpuLock(pid?: number): Promise<void>;
+  getGpuOwner(): Promise<any | null>;
+  getMetrics(): Promise<any>;
+  cleanup(): Promise<void>;
+}