orquesta-cli 0.1.2

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/orquesta/prompt-reporter.ts

@@ -0,0 +1,147 @@
+/**
+ * Prompt Reporter
+ *
+ * Reports prompt execution to Orquesta dashboard
+ * Non-blocking - failures don't affect CLI operation
+ */
+
+import { configManager } from '../core/config/config-manager.js';
+import { submitPromptToOrquesta, updatePromptStatus } from './config-sync.js';
+import { logger } from '../utils/logger.js';
+
+interface ActivePrompt {
+  promptId: string;
+  startTime: number;
+  content: string;
+}
+
+// Track active prompts for status updates
+const activePrompts = new Map<string, ActivePrompt>();
+
+/**
+ * Report a new prompt to Orquesta
+ * Returns a tracking ID for subsequent updates
+ */
+export async function reportPromptStart(
+  content: string,
+  context?: {
+    cwd?: string;
+    model?: string;
+    endpoint?: string;
+  }
+): Promise<string | null> {
+  // Check if connected to Orquesta
+  if (!configManager.hasOrquestaConnection()) {
+    return null;
+  }
+
+  try {
+    const result = await submitPromptToOrquesta({
+      content,
+      context: {
+        cwd: context?.cwd || process.cwd(),
+        timestamp: Date.now(),
+      },
+      llmConfig: context?.model && context?.endpoint
+        ? { endpoint: context.endpoint, model: context.model }
+        : undefined,
+    });
+
+    if (result.success && result.promptId) {
+      // Track for status updates
+      activePrompts.set(result.promptId, {
+        promptId: result.promptId,
+        startTime: Date.now(),
+        content,
+      });
+
+      // Update to running status
+      await updatePromptStatus(result.promptId, { status: 'running' });
+
+      return result.promptId;
+    }
+
+    return null;
+  } catch (error) {
+    // Don't let reporting errors affect CLI operation
+    logger.warn('Failed to report prompt start', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}
+
+/**
+ * Report prompt completion
+ */
+export async function reportPromptComplete(
+  trackingId: string,
+  result: {
+    success: boolean;
+    output?: string;
+    error?: string;
+    tokensUsed?: number;
+    costCents?: number;
+  }
+): Promise<void> {
+  if (!trackingId || !configManager.hasOrquestaConnection()) {
+    return;
+  }
+
+  try {
+    await updatePromptStatus(trackingId, {
+      status: result.success ? 'completed' : 'failed',
+      result: result.output,
+      error: result.error,
+      tokensUsed: result.tokensUsed,
+      costCents: result.costCents,
+    });
+
+    // Remove from active tracking
+    activePrompts.delete(trackingId);
+  } catch (error) {
+    logger.warn('Failed to report prompt completion', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+/**
+ * Report prompt cancellation
+ */
+export async function reportPromptCancelled(trackingId: string): Promise<void> {
+  if (!trackingId || !configManager.hasOrquestaConnection()) {
+    return;
+  }
+
+  try {
+    await updatePromptStatus(trackingId, {
+      status: 'cancelled',
+    });
+
+    activePrompts.delete(trackingId);
+  } catch (error) {
+    logger.warn('Failed to report prompt cancellation', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+/**
+ * Get number of active prompts being tracked
+ */
+export function getActivePromptCount(): number {
+  return activePrompts.size;
+}
+
+/**
+ * Clean up old tracking entries (call periodically)
+ */
+export function cleanupOldPrompts(maxAgeMs: number = 3600000): void {
+  const now = Date.now();
+  for (const [id, prompt] of activePrompts) {
+    if (now - prompt.startTime > maxAgeMs) {
+      activePrompts.delete(id);
+    }
+  }
+}

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;