omnius 1.0.591 → 1.0.592

package/docs/proposals/opencode-modules/orchestrator.ts

@@ -0,0 +1,387 @@
+/**
+ * orchestrator.ts — High-level session management, state transitions, and
+ * multi-turn coordination.  This module owns the *what* and *when* of the
+ * agentic loop:
+ *   1. Manage session lifecycle (create, resume, terminate)
+ *   2. Decide when to compact context
+ *   3. Coordinate between multiple agents
+ *   4. Handle task decomposition and sub-task routing
+ *   5. Track overall progress and completion criteria
+ *
+ * The runner owns the *how*: turn-by-turn execution, tool dispatch, and
+ * event emission.
+ */
+
+import type { LLMBackend } from './backendAdapter.js';
+import { AgenticRunner, type RunResult, type RunnerEvent, type RunnerConfig, type ToolHandler } from './runner.js';
+
+// ─── Session state ────────────────────────────────────────────────────────
+
+export enum SessionState {
+  /** Session has been created but not yet started */
+  Created = 'created',
+  /** Session is actively running */
+  Running = 'running',
+  /** Session is paused (waiting for user input or external event) */
+  Paused = 'paused',
+  /** Session has completed successfully */
+  Completed = 'completed',
+  /** Session has failed */
+  Failed = 'failed',
+  /** Session has been terminated */
+  Terminated = 'terminated',
+}
+
+/** A single session in the orchestrator */
+export interface Session {
+  /** Unique session identifier */
+  id: string;
+  /** Current session state */
+  state: SessionState;
+  /** Session name / description */
+  name: string;
+  /** Task description */
+  task: string;
+  /** System prompt for the session */
+  systemPrompt: string;
+  /** Registered tools for this session */
+  tools: Map<string, ToolHandler>;
+  /** LLM backend for this session */
+  backend: LLMBackend;
+  /** Messages in the conversation history */
+  messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>;
+  /** Current turn number */
+  turnCount: number;
+  /** Maximum turns before forced stop */
+  maxTurns: number;
+  /** Compaction strategy for this session */
+  compactionStrategy: CompactionStrategy;
+  /** Completion criteria for the session */
+  completionCriteria?: string;
+  /** Progress tracking */
+  progress: SessionProgress;
+  /** Created timestamp */
+  createdAt: number;
+  /** Last updated timestamp */
+  updatedAt: number;
+}
+
+/** Progress tracking for a session */
+export interface SessionProgress {
+  /** Steps completed */
+  completedSteps: string[];
+  /** Steps pending */
+  pendingSteps: string[];
+  /** Current step being worked on */
+  currentStep: string;
+  /** Failed approaches to avoid */
+  failedApproaches: string[];
+  /** Next action to take */
+  nextAction: string;
+  /** Modified files tracking */
+  modifiedFiles: Map<string, string>;
+  /** Total tool calls made */
+  toolCallCount: number;
+}
+
+/** Compaction strategy for managing context window */
+export interface CompactionStrategy {
+  /** Type of compaction */
+  type: 'summarize' | 'prune' | 'compress' | 'none';
+  /** Threshold for triggering compaction (in turns) */
+  threshold: number;
+  /** Token budget after compaction */
+  tokenBudget: number;
+  /** Custom compaction function */
+  custom?: (messages: Array<{ role: string; content: string }>) => Promise<Array<{ role: string; content: string }>>;
+}
+
+// ─── Orchestrator ────────────────────────────────────────────────────────
+
+export class SessionOrchestrator {
+  private sessions: Map<string, Session> = new Map();
+  private onSessionEvent?: (event: SessionEvent) => void;
+
+  constructor(onSessionEvent?: (event: SessionEvent) => void) {
+    this.onSessionEvent = onSessionEvent;
+  }
+
+  /**
+   * Create a new session with the given configuration.
+   */
+  createSession(options: {
+    id?: string;
+    name: string;
+    task: string;
+    systemPrompt?: string;
+    backend: LLMBackend;
+    tools?: Map<string, ToolHandler>;
+    maxTurns?: number;
+    compactionStrategy?: CompactionStrategy;
+    completionCriteria?: string;
+  }): Session {
+    const id = options.id ?? `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const session: Session = {
+      id,
+      state: SessionState.Created,
+      name: options.name,
+      task: options.task,
+      systemPrompt: options.systemPrompt ?? '',
+      backend: options.backend,
+      tools: options.tools ?? new Map(),
+      messages: [],
+      turnCount: 0,
+      maxTurns: options.maxTurns ?? 50,
+      compactionStrategy: options.compactionStrategy ?? { type: 'none', threshold: 10, tokenBudget: 4096 },
+      completionCriteria: options.completionCriteria,
+      progress: {
+        completedSteps: [],
+        pendingSteps: [options.task],
+        currentStep: options.task,
+        failedApproaches: [],
+        nextAction: 'start',
+        modifiedFiles: new Map(),
+        toolCallCount: 0,
+      },
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+
+    this.sessions.set(id, session);
+    this.emit({ type: 'session-created', sessionId: id, session });
+    return session;
+  }
+
+  /**
+   * Start a session — transitions it from Created to Running and begins
+   * the agentic loop.
+   */
+  async startSession(sessionId: string): Promise<Session> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session "${sessionId}" not found`);
+    }
+    if (session.state !== SessionState.Created && session.state !== SessionState.Paused) {
+      throw new Error(`Cannot start session in state "${session.state}"`);
+    }
+
+    session.state = SessionState.Running;
+    session.updatedAt = Date.now();
+
+    // Add system prompt as first message
+    if (session.systemPrompt) {
+      session.messages.push({ role: 'system', content: session.systemPrompt });
+    }
+
+    this.emit({ type: 'session-started', sessionId, session });
+
+    // Begin the agentic loop
+    await this.runLoop(session);
+
+    return session;
+  }
+
+  /**
+   * Run the agentic loop for a session: repeatedly call the runner until
+   * completion criteria are met or max turns reached.
+   */
+  private async runLoop(session: Session): Promise<void> {
+    while (session.state === SessionState.Running && session.turnCount < session.maxTurns) {
+      session.turnCount++;
+
+      // Check compaction threshold
+      if (session.compactionStrategy.type !== 'none' && session.turnCount % session.compactionStrategy.threshold === 0) {
+        await this.compactSession(session);
+      }
+
+      // Check completion criteria
+      if (session.completionCriteria && this.checkCompletion(session)) {
+        session.state = SessionState.Completed;
+        session.updatedAt = Date.now();
+        this.emit({ type: 'session-completed', sessionId: session.id, session });
+        return;
+      }
+
+      // Run one turn
+      const result = await this.runTurn(session);
+
+      // Check for errors
+      if (result.error) {
+        session.state = SessionState.Failed;
+        session.updatedAt = Date.now();
+        this.emit({ type: 'session-failed', sessionId: session.id, session, error: result.error });
+        return;
+      }
+
+      // Update progress
+      session.progress.toolCallCount += result.toolCalls.length;
+      session.updatedAt = Date.now();
+    }
+
+    // Max turns reached
+    if (session.turnCount >= session.maxTurns) {
+      session.state = SessionState.Completed;
+      session.updatedAt = Date.now();
+      this.emit({ type: 'session-completed', sessionId: session.id, session });
+    }
+  }
+
+  /**
+   * Run a single turn: delegate to the runner and process the result.
+   */
+  private async runTurn(session: Session): Promise<RunResult> {
+    const runner = new AgenticRunner(
+      {
+        backend: session.backend,
+        tools: session.tools,
+        maxTurns: 1,
+        streamEvents: true,
+      },
+      (event: RunnerEvent) => {
+        this.emit({ type: 'runner-event', sessionId: session.id, event });
+      },
+    );
+
+    const result = await runner.run(session.messages);
+
+    // Add assistant message to history
+    session.messages.push({ role: 'assistant', content: result.text });
+
+    // Add tool results to history
+    for (const tr of result.toolResults) {
+      session.messages.push({
+        role: 'system',
+        content: `<tool_result id="${tr.id}">${tr.content}</tool_result>`,
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * Compact the session's message history according to the compaction strategy.
+   */
+  private async compactSession(session: Session): Promise<void> {
+    if (session.compactionStrategy.type === 'none') return;
+
+    const messages = session.messages;
+
+    if (session.compactionStrategy.custom) {
+      session.messages = (await session.compactionStrategy.custom(messages)) as typeof session.messages;
+    } else if (session.compactionStrategy.type === 'summarize') {
+      // Simple summarize: keep system prompt + last N messages
+      const keep = Math.min(session.compactionStrategy.tokenBudget, messages.length);
+      session.messages = messages.slice(-keep);
+    } else if (session.compactionStrategy.type === 'prune') {
+      // Simple prune: keep system prompt + every other message
+      session.messages = messages.filter((_, i) => i % 2 === 0);
+    }
+  }
+
+  /**
+   * Check if the session has met its completion criteria.
+   */
+  private checkCompletion(session: Session): boolean {
+    if (!session.completionCriteria) return false;
+
+    // Simple keyword matching for now
+    const criteria = session.completionCriteria.toLowerCase();
+    const lastMessage = session.messages[session.messages.length - 1];
+    if (!lastMessage) return false;
+
+    return lastMessage.content.toLowerCase().includes(criteria);
+  }
+
+  /**
+   * Pause a running session.
+   */
+  pauseSession(sessionId: string): Session {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session "${sessionId}" not found`);
+    }
+    if (session.state !== SessionState.Running) {
+      throw new Error(`Cannot pause session in state "${session.state}"`);
+    }
+
+    session.state = SessionState.Paused;
+    session.updatedAt = Date.now();
+    this.emit({ type: 'session-paused', sessionId, session });
+    return session;
+  }
+
+  /**
+   * Resume a paused session.
+   */
+  async resumeSession(sessionId: string): Promise<Session> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session "${sessionId}" not found`);
+    }
+    if (session.state !== SessionState.Paused) {
+      throw new Error(`Cannot resume session in state "${session.state}"`);
+    }
+
+    session.state = SessionState.Running;
+    session.updatedAt = Date.now();
+    this.emit({ type: 'session-resumed', sessionId, session });
+
+    await this.runLoop(session);
+    return session;
+  }
+
+  /**
+   * Terminate a session.
+   */
+  terminateSession(sessionId: string): Session {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session "${sessionId}" not found`);
+    }
+
+    session.state = SessionState.Terminated;
+    session.updatedAt = Date.now();
+    this.emit({ type: 'session-terminated', sessionId, session });
+    return session;
+  }
+
+  /**
+   * Get a session by ID.
+   */
+  getSession(sessionId: string): Session | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  /**
+   * List all sessions.
+   */
+  listSessions(): Session[] {
+    return Array.from(this.sessions.values());
+  }
+
+  /**
+   * Delete a session.
+   */
+  deleteSession(sessionId: string): void {
+    this.sessions.delete(sessionId);
+  }
+
+  /**
+   * Emit a session event.
+   */
+  private emit(event: SessionEvent): void {
+    if (this.onSessionEvent) {
+      this.onSessionEvent(event);
+    }
+  }
+}
+
+// ─── Session events ────────────────────────────────────────────────────────
+
+export interface SessionEvent {
+  type: 'session-created' | 'session-started' | 'session-paused' | 'session-resumed' | 'session-completed' | 'session-failed' | 'session-terminated' | 'runner-event';
+  sessionId: string;
+  session?: Session;
+  event?: RunnerEvent;
+  error?: string;
+}

package/docs/proposals/opencode-modules/runner.ts

@@ -0,0 +1,258 @@
+/**
+ * runner.ts — Core agentic loop: turn-by-turn execution, tool dispatch,
+ * and event emission.  This module owns the *how* of a single agent turn:
+ *   1. Receive messages from the orchestrator
+ *   2. Call the LLM backend (via backendAdapter)
+ *   3. Parse tool calls from the response
+ *   4. Dispatch each tool and collect results
+ *   5. Emit events back to the orchestrator
+ *
+ * The orchestrator owns the *what* and *when*: session lifecycle, state
+ * transitions, compaction decisions, and multi-agent coordination.
+ */
+
+import type { LLMBackend, LLMEvent } from './backendAdapter.js';
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+/** Result returned by a single run cycle */
+export interface RunResult {
+  /** Final assistant text (concatenated chunks) */
+  text: string;
+  /** Tool calls that were made during this turn */
+  toolCalls: Array<{ id: string; name: string; args: string }>;
+  /** Tool results that were collected */
+  toolResults: Array<{ id: string; content: string; error?: string }>;
+  /** Whether the run completed normally */
+  finished: boolean;
+  /** Error message if the run failed */
+  error?: string;
+}
+
+/** Configuration for a single run cycle */
+export interface RunnerConfig {
+  /** LLM backend to use for completions */
+  backend: LLMBackend;
+  /** Registered tools keyed by name */
+  tools: Map<string, ToolHandler>;
+  /** Maximum turns before forced stop */
+  maxTurns: number;
+  /** Whether to stream events to the orchestrator */
+  streamEvents: boolean;
+}
+
+/** A tool handler that can be invoked by the runner */
+export interface ToolHandler {
+  /** Unique tool name */
+  name: string;
+  /** Description of what the tool does */
+  description: string;
+  /** Schema describing the tool's parameters */
+  parameters: Record<string, unknown>;
+  /** Execute the tool with the given arguments */
+  execute(args: string): Promise<string>;
+}
+
+/** Event emitted by the runner during execution */
+export interface RunnerEvent {
+  type: 'chunk' | 'tool-call' | 'tool-result' | 'finish' | 'error' | 'turn-start' | 'turn-end';
+  content?: string;
+  toolCall?: { id: string; name: string; args: string };
+  toolResult?: { id: string; content: string; error?: string };
+  turnNumber?: number;
+  error?: string;
+}
+
+// ─── Core runner ─────────────────────────────────────────────────────────────
+
+export class AgenticRunner {
+  private config: RunnerConfig;
+  private turnCount = 0;
+  private currentText = '';
+  private currentToolCalls: Array<{ id: string; name: string; args: string }> = [];
+  private currentToolResults: Array<{ id: string; content: string; error?: string }> = [];
+  private onEvent?: (event: RunnerEvent) => void;
+
+  constructor(config: RunnerConfig, onEvent?: (event: RunnerEvent) => void) {
+    this.config = config;
+    this.onEvent = onEvent;
+  }
+
+  /**
+   * Run one complete agentic cycle: prompt LLM → parse response → execute tools → return result.
+   * This is the core turn loop that the orchestrator calls repeatedly.
+   */
+  async run(messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>): Promise<RunResult> {
+    this.turnCount++;
+    this.currentText = '';
+    this.currentToolCalls = [];
+    this.currentToolResults = [];
+
+    // Emit turn-start event
+    this.emit({ type: 'turn-start', turnNumber: this.turnCount });
+
+    // Call the LLM backend
+    const response = await this.callLLM(messages);
+
+    // Parse the response into tool calls and text
+    const { text, toolCalls } = this.parseResponse(response);
+    this.currentText = text;
+    this.currentToolCalls = toolCalls;
+
+    // Execute any tool calls
+    if (toolCalls.length > 0) {
+      const results = await this.executeTools(toolCalls);
+      this.currentToolResults = results;
+
+      // Build follow-up messages with tool results
+      const toolResultMessages = this.buildToolResultMessages(results);
+      const finalResponse = await this.callLLM([...messages, ...toolResultMessages]);
+      const { text: finalText } = this.parseResponse(finalResponse);
+      this.currentText = finalText;
+    }
+
+    // Emit finish event
+    this.emit({
+      type: 'finish',
+      content: this.currentText,
+      turnNumber: this.turnCount,
+    });
+
+    return {
+      text: this.currentText,
+      toolCalls: this.currentToolCalls,
+      toolResults: this.currentToolResults,
+      finished: true,
+    };
+  }
+
+  /** Call the LLM backend and collect the full response */
+  private async callLLM(messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>): Promise<string> {
+    const stream = this.config.backend.complete(messages, this.buildToolDefinitions());
+    let fullResponse = '';
+
+    for await (const event of stream) {
+      if (event.type === 'chunk' && event.content) {
+        this.emit({ type: 'chunk', content: event.content });
+        fullResponse += event.content;
+      } else if (event.type === 'error') {
+        this.emit({ type: 'error', error: event.error });
+        throw new Error(event.error ?? 'Unknown backend error');
+      }
+    }
+
+    return fullResponse;
+  }
+
+  /** Build tool definitions for the LLM backend */
+  private buildToolDefinitions(): Array<{ name: string; description?: string; parameters: Record<string, unknown> }> {
+    const definitions: Array<{ name: string; description?: string; parameters: Record<string, unknown> }> = [];
+
+    for (const tool of this.config.tools.values()) {
+      definitions.push({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+      });
+    }
+
+    return definitions;
+  }
+
+  /** Parse the LLM response into text and tool calls */
+  private parseResponse(response: string): { text: string; toolCalls: Array<{ id: string; name: string; args: string }> } {
+    const toolCalls: Array<{ id: string; name: string; args: string }> = [];
+    let text = response;
+
+    // Extract tool calls using regex pattern matching
+    const toolCallRegex = /<tool_call>\s*({[\s\S]*?})\s*<\/tool_call>/g;
+    let match;
+
+    while ((match = toolCallRegex.exec(response)) !== null) {
+      try {
+        const args = JSON.parse(match[1]);
+        const id = `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+        const name = args.name || args.function?.name || 'unknown';
+        const toolArgs = args.arguments || args.args || args.function?.arguments || '{}';
+        const parsedArgs = typeof toolArgs === 'string' ? toolArgs : JSON.stringify(toolArgs);
+
+        toolCalls.push({ id, name, args: parsedArgs });
+
+        // Remove the tool call from the text
+        text = text.replace(match[0], '').trim();
+      } catch {
+        // Invalid JSON — skip this match
+      }
+    }
+
+    // Emit tool-call events
+    for (const tc of toolCalls) {
+      this.emit({ type: 'tool-call', toolCall: tc });
+    }
+
+    return { text, toolCalls };
+  }
+
+  /** Execute all tool calls and collect results */
+  private async executeTools(toolCalls: Array<{ id: string; name: string; args: string }>): Promise<Array<{ id: string; content: string; error?: string }>> {
+    const results: Array<{ id: string; content: string; error?: string }> = [];
+
+    for (const tc of toolCalls) {
+      const tool = this.config.tools.get(tc.name);
+      if (!tool) {
+        results.push({ id: tc.id, content: `Error: Tool "${tc.name}" not found`, error: 'tool_not_found' });
+        this.emit({
+          type: 'tool-result',
+          toolResult: { id: tc.id, content: `Tool "${tc.name}" not found`, error: 'tool_not_found' },
+        });
+        continue;
+      }
+
+      try {
+        const result = await tool.execute(tc.args);
+        results.push({ id: tc.id, content: result });
+        this.emit({
+          type: 'tool-result',
+          toolResult: { id: tc.id, content: result },
+        });
+      } catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        results.push({ id: tc.id, content: `Error: ${errorMsg}`, error: 'execution_error' });
+        this.emit({
+          type: 'tool-result',
+          toolResult: { id: tc.id, content: `Error: ${errorMsg}`, error: 'execution_error' },
+        });
+      }
+    }
+
+    return results;
+  }
+
+  /** Build messages from tool results for the follow-up LLM call */
+  private buildToolResultMessages(results: Array<{ id: string; content: string; error?: string }>): Array<{ role: 'system' | 'user' | 'assistant'; content: string }> {
+    return results.map((r) => ({
+      role: 'system',
+      content: `<tool_result>\n<tool_id>${r.id}</tool_id>\n<content>${r.content}</content>\n</tool_result>`,
+    }));
+  }
+
+  /** Emit an event if a handler is registered */
+  private emit(event: RunnerEvent): void {
+    if (this.onEvent) {
+      this.onEvent(event);
+    }
+  }
+
+  /** Get the current turn count */
+  getTurnCount(): number {
+    return this.turnCount;
+  }
+
+  /** Reset the runner state */
+  reset(): void {
+    this.turnCount = 0;
+    this.currentText = '';
+    this.currentToolCalls = [];
+    this.currentToolResults = [];
+  }
+}