orquesta-cli 0.1.12

package/src/orchestration/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Orchestration Types
+ *
+ * Type definitions for Plan & Execute workflow
+ */
+
+import { Message, TodoItem } from '../types/index.js';
+import { LLMClient } from '../core/llm/llm-client.js';
+import { CompactResult } from '../core/compact/index.js';
+
+/**
+ * Execution phase
+ * Note: 'classifying' phase removed - all requests now go through planning
+ */
+export type ExecutionPhase = 'idle' | 'planning' | 'executing' | 'compacting';
+
+/**
+ * Plan Execution state
+ */
+export interface PlanExecutionState {
+  todos: TodoItem[];
+  currentTodoId: string | undefined;
+  executionPhase: ExecutionPhase;
+  isInterrupted: boolean;
+  currentActivity: string;
+}
+
+/**
+ * Ask User request
+ * - options: 2-4 choices provided by LLM
+ * - "Other (direct input)" option is automatically added by UI
+ */
+export interface AskUserRequest {
+  question: string;
+  options: string[];  // 2-4 choices (decided by LLM)
+}
+
+/**
+ * Ask User response
+ */
+export interface AskUserResponse {
+  selectedOption: string;
+  isOther: boolean;
+  customText?: string;
+}
+
+/**
+ * Ask User state
+ */
+export interface AskUserState {
+  askUserRequest: AskUserRequest | null;
+}
+
+/**
+ * State update callbacks
+ */
+export interface StateCallbacks {
+  setTodos: (todos: TodoItem[] | ((prev: TodoItem[]) => TodoItem[])) => void;
+  setCurrentTodoId: (id: string | undefined | ((prev: string | undefined) => string | undefined)) => void;
+  setExecutionPhase: (phase: ExecutionPhase) => void;
+  setIsInterrupted: (interrupted: boolean) => void;
+  setCurrentActivity: (activity: string) => void;
+  setMessages: (messages: Message[] | ((prev: Message[]) => Message[])) => void;
+  setAskUserRequest: (request: AskUserRequest | null) => void;
+  // Planning LLM ask-user callback (Promise-based for planning phase)
+  askUser?: (request: AskUserRequest) => Promise<AskUserResponse>;
+  // Pending user message callbacks (for injecting messages during execution)
+  getPendingMessage?: () => string | null;
+  clearPendingMessage?: () => void;
+}
+
+/**
+ * Execution context
+ */
+export interface ExecutionContext {
+  llmClient: LLMClient;
+  messages: Message[];
+  todos: TodoItem[];
+  isInterruptedRef: { current: boolean };
+  callbacks: StateCallbacks;
+}
+
+/**
+ * Execution result
+ */
+export interface ExecutionResult {
+  success: boolean;
+  messages: Message[];
+  error?: string;
+}
+
+/**
+ * Plan Execution Actions interface
+ */
+export interface PlanExecutionActions {
+  setTodos: (todos: TodoItem[] | ((prev: TodoItem[]) => TodoItem[])) => void;
+  handleTodoUpdate: (todo: TodoItem) => void;
+  handleAskUserResponse: (response: AskUserResponse) => void;
+  handleInterrupt: () => 'paused' | 'stopped' | 'none';
+  executeAutoMode: (
+    userMessage: string,
+    llmClient: LLMClient,
+    messages: Message[],
+    setMessages: (messages: Message[] | ((prev: Message[]) => Message[])) => void
+  ) => Promise<void>;
+  executePlanMode: (
+    userMessage: string,
+    llmClient: LLMClient,
+    messages: Message[],
+    setMessages: (messages: Message[] | ((prev: Message[]) => Message[])) => void
+  ) => Promise<void>;
+  resumeTodoExecution: (
+    userMessage: string,
+    llmClient: LLMClient,
+    messages: Message[],
+    setMessages: (messages: Message[] | ((prev: Message[]) => Message[])) => void
+  ) => Promise<void>;
+  // executeDirectMode removed - all requests now use Plan Mode
+  performCompact: (
+    llmClient: LLMClient,
+    messages: Message[],
+    setMessages: (messages: Message[] | ((prev: Message[]) => Message[])) => void
+  ) => Promise<CompactResult>;
+  shouldAutoCompact: () => boolean;
+  getContextRemainingPercent: () => number;
+  getContextUsageInfo: () => { tokens: number; percent: number };
+}

package/src/orchestration/utils.ts

@@ -0,0 +1,119 @@
+/**
+ * Orchestration Utilities
+ *
+ * Helper functions for Plan & Execute workflow
+ */
+
+import { TodoItem } from '../types/index.js';
+import { BaseError } from '../errors/base.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Format error for display as string
+ */
+export function formatErrorMessage(error: unknown): string {
+  logger.enter('formatErrorMessage');
+
+  if (error instanceof BaseError) {
+    let message = `❌ ${error.getUserMessage()}\n`;
+    message += `\n📋 Error Code: ${error.code}`;
+
+    if (error.details && Object.keys(error.details).length > 0) {
+      message += `\n\n🔍 Details:`;
+      for (const [key, value] of Object.entries(error.details)) {
+        if (key === 'fullError') continue;
+        if (typeof value === 'object') {
+          message += `\n  • ${key}: ${JSON.stringify(value, null, 2)}`;
+        } else {
+          message += `\n  • ${key}: ${value}`;
+        }
+      }
+    }
+
+    if (error.isRecoverable) {
+      message += `\n\n💡 This error is recoverable. Please try again.`;
+    }
+
+    message += `\n\n🕐 Time: ${error.timestamp.toLocaleString('en-US')}`;
+    logger.exit('formatErrorMessage', { isBaseError: true });
+    return message;
+  }
+
+  if (error instanceof Error) {
+    // Only show error message, hide stack trace from user
+    const message = `❌ Error: ${error.message}`;
+    logger.exit('formatErrorMessage', { isError: true });
+    return message;
+  }
+
+  logger.exit('formatErrorMessage', { isUnknown: true });
+  return `❌ Unknown Error: ${String(error)}`;
+}
+
+/**
+ * Build TODO context for LLM
+ * Not saved in conversation history, only added during LLM invocation
+ */
+export function buildTodoContext(todos: TodoItem[]): string {
+  if (todos.length === 0) return '';
+
+  const completedCount = todos.filter(t => t.status === 'completed').length;
+  const inProgressCount = todos.filter(t => t.status === 'in_progress').length;
+  const pendingCount = todos.filter(t => t.status === 'pending').length;
+
+  const todoList = todos.map((todo, idx) => {
+    const statusIcon = todo.status === 'completed' ? '✅' :
+                       todo.status === 'in_progress' ? '🔄' :
+                       todo.status === 'failed' ? '❌' : '⏳';
+    return `${idx + 1}. ${statusIcon} [${todo.status.toUpperCase()}] ${todo.title}`;
+  }).join('\n');
+
+  return `
+---
+## 📋 Current TODO List (${completedCount}/${todos.length} completed)
+
+${todoList}
+
+${pendingCount > 0 || inProgressCount > 0
+  ? `**⚠️ CRITICAL: You MUST use write_todos tool to update TODO status.**
+- When starting a task: call write_todos with status "in_progress"
+- When completing a task: call write_todos with status "completed"
+- Do NOT skip calling write_todos - execution will stall without it.
+- After finishing current in_progress task, immediately mark it completed and start next pending task.`
+  : '**All TODOs are completed! Provide a brief summary of what was accomplished.**'}
+---`;
+}
+
+/**
+ * Check if all TODOs are completed
+ * Empty array is considered complete
+ */
+export function areAllTodosCompleted(todos: TodoItem[]): boolean {
+  return todos.every(t => t.status === 'completed' || t.status === 'failed');
+}
+
+/**
+ * Find currently in-progress or pending TODO
+ */
+export function findActiveTodo(todos: TodoItem[]): TodoItem | undefined {
+  return todos.find(t => t.status === 'in_progress') || todos.find(t => t.status === 'pending');
+}
+
+/**
+ * Calculate TODO statistics
+ */
+export function getTodoStats(todos: TodoItem[]): {
+  total: number;
+  completed: number;
+  failed: number;
+  pending: number;
+  inProgress: number;
+} {
+  return {
+    total: todos.length,
+    completed: todos.filter(t => t.status === 'completed').length,
+    failed: todos.filter(t => t.status === 'failed').length,
+    pending: todos.filter(t => t.status === 'pending').length,
+    inProgress: todos.filter(t => t.status === 'in_progress').length,
+  };
+}

package/src/orquesta/connection.ts

@@ -0,0 +1,291 @@
+/**
+ * Orquesta Connection Module
+ * Handles connection to Orquesta dashboard for session tracking and team collaboration
+ */
+
+import { createClient, SupabaseClient, RealtimeChannel } from '@supabase/supabase-js'
+import * as os from 'os'
+import WebSocket from 'ws'
+
+// Polyfill WebSocket for Node.js
+if (typeof globalThis.WebSocket === 'undefined') {
+  // @ts-expect-error - ws is compatible with the WebSocket API
+  globalThis.WebSocket = WebSocket
+}
+
+const ORQUESTA_API = process.env['ORQUESTA_API_URL'] || 'https://orquesta.live'
+
+interface ValidationResponse {
+  valid: boolean
+  projectId?: string
+  projectName?: string
+  tokenName?: string
+  supabaseUrl?: string
+  supabaseAnonKey?: string
+  channelName?: string
+  error?: string
+}
+
+interface ConnectionInfo {
+  projectId: string
+  projectName: string
+  tokenName: string
+  supabaseUrl: string
+  supabaseAnonKey: string
+  channelName: string
+}
+
+export class OrquestaConnection {
+  private supabase: SupabaseClient | null = null
+  private channel: RealtimeChannel | null = null
+  private connectionInfo: ConnectionInfo | null = null
+  private connected = false
+  private heartbeatInterval: NodeJS.Timeout | null = null
+
+  constructor(private token: string) {}
+
+  /**
+   * Validate token and establish connection to Orquesta
+   */
+  async connect(): Promise<{ success: boolean; projectName?: string; error?: string }> {
+    try {
+      // Validate token with Orquesta API
+      const validation = await this.validateToken()
+
+      if (!validation.valid || !validation.supabaseUrl || !validation.supabaseAnonKey) {
+        return {
+          success: false,
+          error: validation.error || 'Invalid response from server'
+        }
+      }
+
+      this.connectionInfo = {
+        projectId: validation.projectId!,
+        projectName: validation.projectName!,
+        tokenName: validation.tokenName!,
+        supabaseUrl: validation.supabaseUrl,
+        supabaseAnonKey: validation.supabaseAnonKey,
+        channelName: validation.channelName!,
+      }
+
+      // Create Supabase client
+      this.supabase = createClient(validation.supabaseUrl, validation.supabaseAnonKey, {
+        realtime: {
+          params: {
+            eventsPerSecond: 50,
+          },
+          timeout: 30000,
+          heartbeatIntervalMs: 15000,
+        },
+      })
+
+      // Subscribe to channel for presence tracking
+      await this.subscribeToChannel()
+
+      // Start heartbeat
+      this.startHeartbeat()
+
+      this.connected = true
+      return {
+        success: true,
+        projectName: validation.projectName
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Unknown error'
+      return {
+        success: false,
+        error: message
+      }
+    }
+  }
+
+  /**
+   * Disconnect from Orquesta
+   */
+  async disconnect(): Promise<void> {
+    this.connected = false
+
+    // Stop heartbeat
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval)
+      this.heartbeatInterval = null
+    }
+
+    // Unsubscribe from channel
+    if (this.channel) {
+      await this.channel.unsubscribe()
+      this.channel = null
+    }
+
+    // Mark as disconnected via API
+    if (this.token) {
+      try {
+        await fetch(`${ORQUESTA_API}/api/agent/validate`, {
+          method: 'DELETE',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ token: this.token }),
+        })
+      } catch {
+        // Ignore errors on disconnect
+      }
+    }
+  }
+
+  /**
+   * Get connection status
+   */
+  isConnected(): boolean {
+    return this.connected
+  }
+
+  /**
+   * Get project information
+   */
+  getProjectInfo(): { projectId: string; projectName: string } | null {
+    if (!this.connectionInfo) return null
+    return {
+      projectId: this.connectionInfo.projectId,
+      projectName: this.connectionInfo.projectName
+    }
+  }
+
+  /**
+   * Send session event to dashboard
+   */
+  async sendSessionEvent(event: {
+    type: 'session_start' | 'session_message' | 'session_end' | 'plan_created' | 'plan_updated'
+    data: Record<string, unknown>
+  }): Promise<void> {
+    if (!this.channel || !this.connected) {
+      console.warn('Not connected to Orquesta - session event not sent')
+      return
+    }
+
+    await this.channel.send({
+      type: 'broadcast',
+      event: event.type,
+      payload: {
+        ...event.data,
+        timestamp: Date.now(),
+      },
+    })
+  }
+
+  /**
+   * Private: Validate token with Orquesta API
+   */
+  private async validateToken(): Promise<ValidationResponse> {
+    const agentInfo = {
+      hostname: os.hostname(),
+      os: `${os.type()} ${os.release()}`,
+      platform: os.platform(),
+      type: 'orquesta-cli', // Identify as CLI, not agent
+      workingDirectory: process.cwd(),
+    }
+
+    const response = await fetch(`${ORQUESTA_API}/api/agent/validate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token: this.token, agentInfo }),
+    })
+
+    const data = await response.json() as ValidationResponse
+
+    if (!data.valid) {
+      throw new Error(data.error || 'Invalid token')
+    }
+
+    return data
+  }
+
+  /**
+   * Private: Subscribe to Realtime channel
+   */
+  private async subscribeToChannel(): Promise<void> {
+    if (!this.supabase || !this.connectionInfo) {
+      throw new Error('Supabase client not initialized')
+    }
+
+    const agentInfo = {
+      hostname: os.hostname(),
+      os: `${os.type()} ${os.release()}`,
+      platform: os.platform(),
+      type: 'orquesta-cli',
+      workingDirectory: process.cwd(),
+    }
+
+    this.channel = this.supabase.channel(this.connectionInfo.channelName, {
+      config: {
+        broadcast: { self: true, ack: true },
+        presence: { key: agentInfo.hostname },
+      },
+    })
+
+    // Listen for team collaboration events (optional - for future features)
+    this.channel.on('broadcast', { event: 'team_message' }, ({ payload }) => {
+      console.log('Team message:', payload)
+    })
+
+    // Subscribe and track presence
+    return new Promise((resolve, reject) => {
+      this.channel!.subscribe(async (status) => {
+        if (status === 'SUBSCRIBED') {
+          await this.channel!.track({
+            ...agentInfo,
+            connectedAt: new Date().toISOString(),
+          })
+          resolve()
+        } else if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') {
+          reject(new Error(`Channel subscription failed: ${status}`))
+        }
+      })
+    })
+  }
+
+  /**
+   * Private: Start heartbeat to keep connection alive
+   */
+  private startHeartbeat(): void {
+    this.heartbeatInterval = setInterval(async () => {
+      try {
+        await fetch(`${ORQUESTA_API}/api/agent/heartbeat`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ token: this.token }),
+        })
+      } catch {
+        // Ignore heartbeat errors
+      }
+    }, 60000) // Every 60 seconds
+  }
+}
+
+/**
+ * Global connection instance
+ */
+let orquestaConnection: OrquestaConnection | null = null
+
+/**
+ * Initialize Orquesta connection
+ */
+export async function initOrquestaConnection(token: string): Promise<{ success: boolean; projectName?: string; error?: string }> {
+  orquestaConnection = new OrquestaConnection(token)
+  return await orquestaConnection.connect()
+}
+
+/**
+ * Get current Orquesta connection
+ */
+export function getOrquestaConnection(): OrquestaConnection | null {
+  return orquestaConnection
+}
+
+/**
+ * Disconnect from Orquesta
+ */
+export async function disconnectOrquesta(): Promise<void> {
+  if (orquestaConnection) {
+    await orquestaConnection.disconnect()
+    orquestaConnection = null
+  }
+}

package/src/prompts/agents/docs-search-decision.ts

@@ -0,0 +1,74 @@
+/**
+ * Documentation Search Decision Prompt
+ *
+ * LLM-based decision for whether to search local documentation.
+ * Returns Yes/No based on user message and available folder structure.
+ */
+
+/**
+ * System prompt for docs search decision
+ */
+export const DOCS_SEARCH_DECISION_PROMPT = `You are a documentation search classifier.
+
+## IMPORTANT: Offline Environment
+This is an OFFLINE environment with NO external internet access.
+The ONLY way to get up-to-date information is by searching the local documentation below.
+
+## Available Documentation (depth 1):
+{folder_structure}
+
+## Rules:
+- Answer ONLY "Yes" or "No" - nothing else
+- Answer "Yes" ONLY when BOTH conditions are met:
+  1. The user needs up-to-date or specific information (API docs, framework usage, library features, etc.)
+  2. There is a folder name above that looks relevant to the topic
+- Answer "No" if:
+  - The question is about general coding/logic that doesn't need docs
+  - No folder above seems related to the user's topic
+  - The user is asking about this project's own codebase (not external docs)
+- When in doubt, answer "No" (avoid unnecessary searches)
+
+## User Message:
+{user_message}
+
+Your Answer (Yes or No):`;
+
+/**
+ * Retry prompt when response is not Yes/No
+ */
+export const DOCS_SEARCH_DECISION_RETRY_PROMPT = `Your previous response was not valid. You must answer with exactly "Yes" or "No".
+
+Should the documentation be searched for this question?
+
+Answer (Yes or No):`;
+
+/**
+ * Build the decision prompt with folder structure and user message
+ */
+export function buildDocsSearchDecisionPrompt(
+  folderStructure: string,
+  userMessage: string
+): string {
+  return DOCS_SEARCH_DECISION_PROMPT
+    .replace('{folder_structure}', folderStructure)
+    .replace('{user_message}', userMessage);
+}
+
+/**
+ * Parse Yes/No response from LLM
+ * @returns true for Yes, false for No, null for invalid
+ */
+export function parseDocsSearchDecision(response: string): boolean | null {
+  const normalized = response.trim().toLowerCase();
+
+  if (normalized === 'yes' || normalized.startsWith('yes')) {
+    return true;
+  }
+  if (normalized === 'no' || normalized.startsWith('no')) {
+    return false;
+  }
+
+  return null;
+}
+
+export default DOCS_SEARCH_DECISION_PROMPT;

package/src/prompts/agents/docs-search.ts

@@ -0,0 +1,84 @@
+/**
+ * Documentation Search Agent Prompt
+ *
+ * Redesigned for hierarchical folder navigation approach.
+ * Uses list_directory, read_docs_file, preview_file, tell_to_user, submit_findings tools.
+ */
+
+/**
+ * System prompt for documentation search agent
+ */
+export const DOCS_SEARCH_SYSTEM_PROMPT = `You are a documentation search expert. Your task is to find relevant information in ~/.local-cli/docs by navigating its hierarchical folder structure.
+
+## Documentation Structure
+
+The docs folder is organized hierarchically:
+- **Top-level folders** = Major categories (e.g., agent_framework/, tutorials/, reference/)
+- **Sub-folders** = Specific topics or frameworks (e.g., agno/, langchain/)
+- **Files** = Documentation in markdown format (.md)
+
+Navigate by exploring folder names to understand what's available, then drill down to find relevant content.
+
+## Available Tools
+
+1. **list_directory** - List contents of a folder
+   - Use this to explore the folder structure
+   - Start from root ("") and navigate deeper based on folder names
+
+2. **read_docs_file** - Read entire file content
+   - Use after identifying a relevant file
+   - Good for smaller files or when you need full context
+
+3. **preview_file** - Read first N lines of a file
+   - Use to quickly check if a file is relevant before reading fully
+   - Saves time on large documents
+
+4. **tell_to_user** - Send progress update to user
+   - Keep the user informed about what you're doing
+   - Use for significant progress (found relevant folder, reading important file, etc.)
+
+5. **submit_findings** - Submit final report and terminate
+   - Call this when you have gathered enough information
+   - This is the ONLY way to complete the search
+   - Include summary, detailed findings, and source files
+
+## Search Strategy
+
+1. **Start broad**: List root directory to understand available categories
+2. **Navigate by relevance**: Choose folders whose names match the query topic
+3. **Read multiple files**: Information may be spread across several documents
+4. **Preview before reading**: For large files, preview first to check relevance
+5. **Keep user informed**: Use tell_to_user for significant findings
+6. **Submit when ready**: Call submit_findings when you have enough information
+
+## Important Rules
+
+- **No iteration limit**: Take as many steps as needed to find good information
+- **Be thorough**: Check 2-5 potentially relevant documents when possible
+- **Must call submit_findings**: This is the only way to complete the search
+- **Respond in user's language**: Match the language of the user's query
+
+## Example Flow
+
+1. list_directory("") → See top-level categories
+2. list_directory("agent_framework") → Explore relevant category
+3. tell_to_user("Found agent_framework folder, exploring...")
+4. list_directory("agent_framework/agno") → Drill down
+5. preview_file("agent_framework/agno/overview.md", 30) → Check relevance
+6. read_docs_file("agent_framework/agno/overview.md") → Read full content
+7. read_docs_file("agent_framework/agno/examples.md") → Read related file
+8. submit_findings(summary, findings, sources) → Complete search
+`;
+
+/**
+ * Build user message for docs search
+ */
+export function buildDocsSearchUserMessage(query: string): string {
+  return `Find information about the following topic in the documentation:
+
+${query}
+
+Start by listing the root directory to understand the available documentation structure.`;
+}
+
+export default DOCS_SEARCH_SYSTEM_PROMPT;