illuma-agents 1.0.45 → 1.0.49

package/src/deepagents/DeepAgentBackend.ts

@@ -0,0 +1,214 @@
+/**
+ * Deep Agent Backend
+ * 
+ * A backend implementation that extends deepagents' FilesystemBackend
+ * with SSE streaming for real-time updates and integration with
+ * external code execution services.
+ */
+
+import { FilesystemBackend } from 'deepagents';
+import type { ExecuteResponse, SandboxBackendProtocol } from 'deepagents';
+import type { DeepAgentTodo, DeepAgentSubagent } from './types';
+
+/** SSE Response interface for streaming */
+export interface SSEResponse {
+  write: (data: string) => void;
+  headersSent?: boolean;
+}
+
+/** Options for Deep Agent Backend */
+export interface DeepAgentBackendOptions {
+  /** Root directory for file operations (default: process.cwd()) */
+  rootDir?: string;
+  /** Whether to use virtual paths (default: true) */
+  virtualMode?: boolean;
+  /** Timeout for command execution in ms (default: 120000) */
+  timeout?: number;
+  /** Max output size in bytes (default: 100000) */
+  maxOutputBytes?: number;
+  /** SSE response for streaming updates */
+  sseResponse?: SSEResponse;
+  /** Conversation ID for event tracking */
+  conversationId?: string;
+  /** Code executor API URL (optional - for sandboxed execution) */
+  codeExecutorUrl?: string;
+  /** Callback for todo changes */
+  onTodoUpdate?: (todos: DeepAgentTodo[]) => void;
+  /** Callback for subagent changes */
+  onSubagentUpdate?: (subagents: DeepAgentSubagent[]) => void;
+}
+
+/**
+ * Deep Agent Backend
+ * 
+ * Extends FilesystemBackend with:
+ * - SSE streaming for real-time updates
+ * - Integration with external code executor services
+ * - Event emission for todos and subagents
+ */
+export class DeepAgentBackend extends FilesystemBackend implements SandboxBackendProtocol {
+  readonly id: string;
+  private readonly timeout: number;
+  private readonly maxOutputBytes: number;
+  private readonly conversationId?: string;
+  private readonly sseResponse?: SSEResponse;
+  private readonly codeExecutorUrl?: string;
+  private readonly onTodoUpdate?: (todos: DeepAgentTodo[]) => void;
+  private readonly onSubagentUpdate?: (subagents: DeepAgentSubagent[]) => void;
+
+  constructor(options: DeepAgentBackendOptions = {}) {
+    super({
+      rootDir: options.rootDir ?? process.cwd(),
+      virtualMode: options.virtualMode ?? true,
+      maxFileSizeMb: 10,
+    });
+
+    this.id = `deep-agent-backend-${Date.now().toString(36)}`;
+    this.timeout = options.timeout ?? 120_000;
+    this.maxOutputBytes = options.maxOutputBytes ?? 100_000;
+    this.conversationId = options.conversationId;
+    this.sseResponse = options.sseResponse;
+    this.codeExecutorUrl = options.codeExecutorUrl;
+    this.onTodoUpdate = options.onTodoUpdate;
+    this.onSubagentUpdate = options.onSubagentUpdate;
+  }
+
+  /**
+   * Execute a command
+   * 
+   * If codeExecutorUrl is configured, uses the external sandboxed executor.
+   * Otherwise, logs a warning (shell execution may not be available).
+   */
+  async execute(command: string): Promise<ExecuteResponse> {
+    if (!command || typeof command !== 'string') {
+      return {
+        output: 'Error: Command must be a non-empty string.',
+        exitCode: 1,
+        truncated: false,
+      };
+    }
+
+    // If we have a code executor URL, use that for sandboxed execution
+    if (this.codeExecutorUrl) {
+      return this.executeViaCodeExecutor(command);
+    }
+
+    // Log warning - direct shell execution may not be available
+    console.warn('[DeepAgentBackend] Shell execution requested but no code executor configured');
+    return {
+      output: 'Shell execution is not available in this environment. Consider using the code executor tool instead.',
+      exitCode: 1,
+      truncated: false,
+    };
+  }
+
+  /**
+   * Execute command via external code executor service
+   */
+  private async executeViaCodeExecutor(command: string): Promise<ExecuteResponse> {
+    try {
+      const response = await fetch(`${this.codeExecutorUrl}/execute`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          code: command,
+          language: 'shell',
+          timeout: this.timeout,
+        }),
+        signal: AbortSignal.timeout(this.timeout + 5000),
+      });
+
+      if (!response.ok) {
+        return {
+          output: `Execution error: ${response.statusText}`,
+          exitCode: 1,
+          truncated: false,
+        };
+      }
+
+      const result = await response.json() as {
+        output?: string;
+        exitCode?: number;
+        error?: string;
+      };
+
+      let output = result.output ?? result.error ?? '';
+      let truncated = false;
+
+      if (output.length > this.maxOutputBytes) {
+        output = output.slice(0, this.maxOutputBytes) + '\n... (output truncated)';
+        truncated = true;
+      }
+
+      return {
+        output,
+        exitCode: result.exitCode ?? (result.error ? 1 : 0),
+        truncated,
+      };
+    } catch (error) {
+      return {
+        output: `Execution failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        exitCode: 1,
+        truncated: false,
+      };
+    }
+  }
+
+  /**
+   * Send an SSE event to the client
+   */
+  sendEvent(event: string, data: unknown): void {
+    if (this.sseResponse && !this.sseResponse.headersSent) {
+      try {
+        this.sseResponse.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+      } catch (e) {
+        console.warn('[DeepAgentBackend] Failed to send SSE event:', e);
+      }
+    }
+  }
+
+  /**
+   * Emit todo update event
+   */
+  emitTodoUpdate(todos: DeepAgentTodo[]): void {
+    // Call callback if provided
+    if (this.onTodoUpdate) {
+      this.onTodoUpdate(todos);
+    }
+
+    // Send SSE event
+    this.sendEvent('deep_research', {
+      type: 'todo_update',
+      conversationId: this.conversationId,
+      todos,
+      progress: this.calculateProgress(todos),
+      isRunning: todos.some(t => t.status === 'in_progress'),
+    });
+  }
+
+  /**
+   * Emit subagent update event
+   */
+  emitSubagentUpdate(subagents: DeepAgentSubagent[]): void {
+    // Call callback if provided
+    if (this.onSubagentUpdate) {
+      this.onSubagentUpdate(subagents);
+    }
+
+    // Send SSE event
+    this.sendEvent('deep_research', {
+      type: 'subagent_update',
+      conversationId: this.conversationId,
+      subagents,
+    });
+  }
+
+  /**
+   * Calculate progress from todos
+   */
+  private calculateProgress(todos: DeepAgentTodo[]): number {
+    if (todos.length === 0) return 0;
+    const completed = todos.filter(t => t.status === 'completed').length;
+    return Math.round((completed / todos.length) * 100);
+  }
+}

package/src/deepagents/DeepAgentRuntime.ts

@@ -0,0 +1,187 @@
+/**
+ * Deep Agent Runtime
+ * 
+ * Factory for creating and managing deep agent instances with
+ * illuma-agents integration.
+ * 
+ * Uses explicit any types to avoid version conflicts between
+ * langchain dependencies in deepagents vs illuma-agents.
+ */
+
+import { createDeepAgent } from 'deepagents';
+import { DeepAgentBackend } from './DeepAgentBackend';
+import type { DeepAgentRuntimeOptions, DeepAgentTodo, DeepAgentSubagent } from './types';
+
+/** Default system prompt for deep research mode */
+const DEFAULT_DEEP_RESEARCH_PROMPT = `You are a deep research agent capable of breaking down complex tasks into manageable steps.
+
+## Todo Management
+
+You have a todo tool to track your progress. Use it to:
+1. Create a plan at the START with all tasks as "pending"
+2. Mark ONE task as "in_progress" before working on it
+3. Mark it "completed" IMMEDIATELY after finishing
+4. Update the FULL list each time (include all todos)
+
+## Best Practices
+
+- Break complex tasks into 3-7 discrete steps
+- Work through tasks sequentially
+- Keep the user informed of progress
+- If a task is blocked, mark it and move to the next
+- Summarize findings after completing all tasks
+`;
+
+/** Return type for createDeepAgentRuntime */
+export interface DeepAgentRuntimeResult {
+  /** The deep agent instance */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  agent: any;
+  /** The backend for execution */
+  backend: DeepAgentBackend;
+  /** Thread ID for checkpointing */
+  threadId: string;
+  /** Conversation ID for tracking */
+  conversationId: string;
+}
+
+/**
+ * Create a deep agent runtime with the provided options
+ * 
+ * @param options - Configuration for the deep agent
+ * @returns The configured deep agent instance
+ */
+export async function createDeepAgentRuntime(
+  options: DeepAgentRuntimeOptions
+): Promise<DeepAgentRuntimeResult> {
+  const {
+    model,
+    threadId,
+    conversationId,
+    workspacePath,
+    systemPrompt,
+    checkpointer,
+    sseResponse,
+    onTodoUpdate,
+    onSubagentUpdate,
+    requireApproval = false,
+    codeExecutorUrl,
+  } = options;
+
+  if (!threadId) {
+    throw new Error('Thread ID is required for deep agent checkpointing');
+  }
+
+  // Create the backend with SSE streaming
+  const backend = new DeepAgentBackend({
+    rootDir: workspacePath,
+    virtualMode: !workspacePath, // Use virtual mode if no workspace path
+    conversationId,
+    sseResponse,
+    codeExecutorUrl,
+    onTodoUpdate,
+    onSubagentUpdate,
+  });
+
+  // Build the full system prompt
+  const fullSystemPrompt = systemPrompt 
+    ? `${systemPrompt}\n\n${DEFAULT_DEEP_RESEARCH_PROMPT}`
+    : DEFAULT_DEEP_RESEARCH_PROMPT;
+
+  // Create the deep agent with explicit any casts to avoid version conflicts
+  // between langchain types in deepagents vs illuma-agents
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const agent = createDeepAgent({
+    model: model as any,
+    checkpointer: checkpointer as any,
+    backend,
+    systemPrompt: fullSystemPrompt,
+    // Require approval for shell commands if configured
+    interruptOn: requireApproval ? { execute: true } : undefined,
+  } as any);
+
+  return {
+    agent,
+    backend,
+    threadId,
+    conversationId,
+  };
+}
+
+/**
+ * Run a deep agent with the given input
+ * 
+ * @param runtime - The deep agent runtime
+ * @param input - User input message
+ * @param config - Optional run configuration
+ */
+export async function runDeepAgent(
+  runtime: DeepAgentRuntimeResult,
+  input: string,
+  config?: {
+    signal?: AbortSignal;
+    onToken?: (token: string) => void;
+    onTodoUpdate?: (todos: DeepAgentTodo[]) => void;
+    onSubagentUpdate?: (subagents: DeepAgentSubagent[]) => void;
+  }
+): Promise<{
+  response: string;
+  todos: DeepAgentTodo[];
+  subagents: DeepAgentSubagent[];
+}> {
+  const { agent, threadId, backend } = runtime;
+
+  // Stream the agent response
+  const stream = await agent.stream(
+    { messages: [{ role: 'human', content: input }] },
+    { 
+      configurable: { thread_id: threadId },
+      signal: config?.signal,
+    }
+  );
+
+  let fullResponse = '';
+  const todos: DeepAgentTodo[] = [];
+  const subagents: DeepAgentSubagent[] = [];
+
+  for await (const event of stream) {
+    // Handle different event types
+    if ('messages' in event && Array.isArray(event.messages)) {
+      // Extract the latest AI message content
+      const lastMessage = event.messages[event.messages.length - 1];
+      if (lastMessage?.role === 'ai' && typeof lastMessage.content === 'string') {
+        const newContent = lastMessage.content.slice(fullResponse.length);
+        if (newContent && config?.onToken) {
+          config.onToken(newContent);
+        }
+        fullResponse = lastMessage.content;
+      }
+    }
+
+    // Handle todo updates
+    if ('todos' in event && Array.isArray(event.todos)) {
+      todos.length = 0;
+      todos.push(...(event.todos as DeepAgentTodo[]));
+      if (config?.onTodoUpdate) {
+        config.onTodoUpdate(todos);
+      }
+      backend.emitTodoUpdate(todos);
+    }
+
+    // Handle subagent updates
+    if ('subagents' in event && Array.isArray(event.subagents)) {
+      subagents.length = 0;
+      subagents.push(...(event.subagents as DeepAgentSubagent[]));
+      if (config?.onSubagentUpdate) {
+        config.onSubagentUpdate(subagents);
+      }
+      backend.emitSubagentUpdate(subagents);
+    }
+  }
+
+  return {
+    response: fullResponse,
+    todos,
+    subagents,
+  };
+}

package/src/deepagents/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Deep Agents Integration
+ * 
+ * This module integrates the deepagentsjs library into illuma-agents,
+ * providing deep research capabilities including:
+ * - Todo planning and tracking
+ * - Subagent delegation
+ * - Filesystem operations
+ * - Shell execution
+ * 
+ * @module deepagents
+ */
+
+// Re-export core deepagents functionality
+export {
+  createDeepAgent,
+  FilesystemBackend,
+  type SandboxBackendProtocol,
+  type ExecuteResponse,
+} from 'deepagents';
+
+// Export our custom integrations
+export * from './types';
+export * from './DeepAgentRuntime';
+export * from './DeepAgentBackend';

package/src/deepagents/types.ts

@@ -0,0 +1,118 @@
+/**
+ * Deep Agents Types
+ * 
+ * Type definitions for deep agent integration
+ * 
+ * Uses generic/unknown types to avoid version conflicts between
+ * langchain dependencies in deepagents vs illuma-agents.
+ */
+
+/** Status of a todo item */
+export type TodoStatus = 'pending' | 'in_progress' | 'completed' | 'cancelled';
+
+/** A todo item tracked by the deep agent */
+export interface DeepAgentTodo {
+  /** Unique identifier */
+  id: string;
+  /** Task description */
+  content: string;
+  /** Current status */
+  status: TodoStatus;
+  /** Order index */
+  order?: number;
+  /** When created */
+  createdAt?: string;
+  /** When last updated */
+  updatedAt?: string;
+}
+
+/** A subagent spawned by the deep agent */
+export interface DeepAgentSubagent {
+  /** Unique identifier */
+  id: string;
+  /** Subagent name/purpose */
+  name: string;
+  /** Description of what it's doing */
+  description?: string;
+  /** Current status */
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  /** When started */
+  startedAt?: string;
+  /** When completed */
+  completedAt?: string;
+}
+
+/** State of a deep agent session */
+export interface DeepAgentState {
+  /** Whether deep research mode is active */
+  enabled: boolean;
+  /** Current todos */
+  todos: DeepAgentTodo[];
+  /** Active subagents */
+  subagents: DeepAgentSubagent[];
+  /** Overall progress (0-100) */
+  progress: number;
+  /** Whether currently executing */
+  isRunning: boolean;
+  /** Workspace path for file operations */
+  workspacePath?: string;
+}
+
+/** Options for creating a deep agent runtime */
+export interface DeepAgentRuntimeOptions {
+  /** The LLM model to use (BaseChatModel or model name string) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  model: any;
+  /** Thread ID for checkpointing */
+  threadId: string;
+  /** Conversation ID for event tracking */
+  conversationId: string;
+  /** Workspace path for file operations (optional) */
+  workspacePath?: string;
+  /** Custom system prompt to prepend */
+  systemPrompt?: string;
+  /** Checkpointer for state persistence (BaseCheckpointSaver) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  checkpointer?: any;
+  /** SSE response object for streaming updates */
+  sseResponse?: {
+    write: (data: string) => void;
+    headersSent?: boolean;
+  };
+  /** Callback for todo updates */
+  onTodoUpdate?: (todos: DeepAgentTodo[]) => void;
+  /** Callback for subagent updates */
+  onSubagentUpdate?: (subagents: DeepAgentSubagent[]) => void;
+  /** Whether to require human approval for shell commands */
+  requireApproval?: boolean;
+  /** Code executor URL for sandboxed execution */
+  codeExecutorUrl?: string;
+}
+
+/** Events emitted by the deep agent */
+export interface DeepAgentEvent {
+  type: 'todo_update' | 'subagent_update' | 'file_change' | 'execution';
+  conversationId: string;
+  data: {
+    todos?: DeepAgentTodo[];
+    subagents?: DeepAgentSubagent[];
+    files?: Array<{ path: string; action: 'read' | 'write' | 'delete' }>;
+    execution?: { command: string; output: string; exitCode: number | null };
+  };
+}
+
+/** Calculate progress from todos */
+export function calculateTodoProgress(todos: DeepAgentTodo[]): number {
+  if (todos.length === 0) return 0;
+  const completed = todos.filter(t => t.status === 'completed').length;
+  return Math.round((completed / todos.length) * 100);
+}
+
+/** Default state for deep agent */
+export const defaultDeepAgentState: DeepAgentState = {
+  enabled: false,
+  todos: [],
+  subagents: [],
+  progress: 0,
+  isRunning: false,
+};

package/src/index.ts

@@ -8,11 +8,13 @@ export * from './messages';
 /* Graphs */
 export * from './graphs';
 
+/* Deep Agents */
+export * from './deepagents';
+
 /* Tools */
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
 export * from './tools/BrowserTools';
-export * from './tools/DesktopTools';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearch';
 export * from './tools/handlers';