@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/runtime/subagent.ts

@@ -0,0 +1,154 @@
+/**
+ * Sub-Agent Lifecycle Manager
+ *
+ * Handles spawning child agents with their own sessions.
+ * Sub-agents inherit the parent's org context and can optionally
+ * get their own email accounts.
+ */
+
+import { nanoid } from 'nanoid';
+import type { ModelConfig, SessionState } from './types.js';
+
+// ─── Types ───────────────────────────────────────────────
+
+export interface SubAgentInfo {
+  id: string;
+  parentSessionId: string;
+  childSessionId: string;
+  agentId: string;
+  task: string;
+  status: 'active' | 'completed' | 'failed' | 'cancelled';
+  email?: string;
+  createdAt: number;
+  completedAt?: number;
+}
+
+export interface SpawnSubAgentOptions {
+  parentSessionId: string;
+  task: string;
+  agentId?: string;
+  name?: string;
+  model?: ModelConfig;
+}
+
+export interface SpawnSubAgentResult {
+  id: string;
+  childSessionId: string;
+  agentId: string;
+  status: 'accepted' | 'error';
+  error?: string;
+}
+
+// ─── Sub-Agent Manager ───────────────────────────────────
+
+export class SubAgentManager {
+  /** Active sub-agent records keyed by parent session ID */
+  private subAgents = new Map<string, SubAgentInfo[]>();
+  /** Max children per parent session */
+  private maxChildrenPerParent: number;
+  /** Max spawn depth */
+  private maxSpawnDepth: number;
+
+  constructor(opts?: { maxChildrenPerParent?: number; maxSpawnDepth?: number }) {
+    this.maxChildrenPerParent = opts?.maxChildrenPerParent ?? 5;
+    this.maxSpawnDepth = opts?.maxSpawnDepth ?? 2;
+  }
+
+  /**
+   * Register a new sub-agent spawn.
+   */
+  register(info: SubAgentInfo): void {
+    var existing = this.subAgents.get(info.parentSessionId) || [];
+    existing.push(info);
+    this.subAgents.set(info.parentSessionId, existing);
+  }
+
+  /**
+   * Check if spawning is allowed for this parent session.
+   */
+  canSpawn(parentSessionId: string): { allowed: boolean; reason?: string } {
+    var children = this.subAgents.get(parentSessionId) || [];
+    var activeCount = children.filter(function(c) { return c.status === 'active'; }).length;
+
+    if (activeCount >= this.maxChildrenPerParent) {
+      return {
+        allowed: false,
+        reason: `Max active sub-agents reached (${activeCount}/${this.maxChildrenPerParent})`,
+      };
+    }
+
+    return { allowed: true };
+  }
+
+  /**
+   * Get depth of a session in the sub-agent tree.
+   */
+  getDepth(sessionId: string): number {
+    var depth = 0;
+    // Walk up the tree
+    for (var [parentId, children] of this.subAgents) {
+      for (var child of children) {
+        if (child.childSessionId === sessionId) {
+          return 1 + this.getDepth(parentId);
+        }
+      }
+    }
+    return depth;
+  }
+
+  /**
+   * Mark a sub-agent as completed.
+   */
+  complete(childSessionId: string, status: 'completed' | 'failed'): void {
+    for (var [, children] of this.subAgents) {
+      for (var child of children) {
+        if (child.childSessionId === childSessionId) {
+          child.status = status;
+          child.completedAt = Date.now();
+          return;
+        }
+      }
+    }
+  }
+
+  /**
+   * List sub-agents for a parent session.
+   */
+  listForParent(parentSessionId: string): SubAgentInfo[] {
+    return this.subAgents.get(parentSessionId) || [];
+  }
+
+  /**
+   * Cancel all active sub-agents for a parent.
+   */
+  cancelAll(parentSessionId: string): string[] {
+    var children = this.subAgents.get(parentSessionId) || [];
+    var cancelled: string[] = [];
+    for (var child of children) {
+      if (child.status === 'active') {
+        child.status = 'cancelled';
+        child.completedAt = Date.now();
+        cancelled.push(child.childSessionId);
+      }
+    }
+    return cancelled;
+  }
+
+  /**
+   * Clean up all records for a parent session.
+   */
+  cleanup(parentSessionId: string): void {
+    this.subAgents.delete(parentSessionId);
+  }
+
+  /**
+   * Get total active sub-agent count across all parents.
+   */
+  getActiveCount(): number {
+    var count = 0;
+    for (var [, children] of this.subAgents) {
+      count += children.filter(function(c) { return c.status === 'active'; }).length;
+    }
+    return count;
+  }
+}

package/src/runtime/tool-executor.ts

@@ -0,0 +1,202 @@
+/**
+ * Tool Execution Engine
+ *
+ * Bridges the agent loop with agent-tools/ implementations.
+ * Validates input, executes with timeout, formats results.
+ */
+
+import type { AnyAgentTool, ToolResult } from '../agent-tools/types.js';
+import type { ToolCall, ToolCallResult } from './types.js';
+
+// ─── Constants ───────────────────────────────────────────
+
+const DEFAULT_TOOL_TIMEOUT_MS = 30_000;
+const MAX_RESULT_CHARS = 200_000;
+
+// ─── Tool Registry ───────────────────────────────────────
+
+export class ToolRegistry {
+  private tools = new Map<string, AnyAgentTool>();
+
+  register(tools: AnyAgentTool[]): void {
+    for (var tool of tools) {
+      this.tools.set(tool.name, tool);
+    }
+  }
+
+  get(name: string): AnyAgentTool | undefined {
+    return this.tools.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  list(): AnyAgentTool[] {
+    return Array.from(this.tools.values());
+  }
+
+  clear(): void {
+    this.tools.clear();
+  }
+}
+
+// ─── Execution ───────────────────────────────────────────
+
+/**
+ * Execute a single tool call and return a formatted result.
+ */
+export async function executeTool(
+  tool: AnyAgentTool,
+  toolCall: ToolCall,
+  options?: { timeoutMs?: number; signal?: AbortSignal },
+): Promise<{ result: ToolCallResult; content: string }> {
+  var timeoutMs = options?.timeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+  var started = Date.now();
+
+  try {
+    // Validate required parameters
+    var validationError = validateToolInput(tool, toolCall.input);
+    if (validationError) {
+      return {
+        result: { success: false, error: validationError, durationMs: Date.now() - started },
+        content: `Error: ${validationError}`,
+      };
+    }
+
+    // Execute with timeout
+    var toolResult = await executeWithTimeout(
+      tool.execute(toolCall.id, toolCall.input),
+      timeoutMs,
+      options?.signal,
+    );
+
+    var content = formatToolResult(toolResult);
+    var durationMs = Date.now() - started;
+
+    return {
+      result: { success: true, output: content, durationMs },
+      content: truncateResult(content),
+    };
+  } catch (err: any) {
+    var durationMs = Date.now() - started;
+    var errorMessage = err?.message || String(err);
+
+    if (err?.name === 'AbortError' || err?.name === 'TimeoutError') {
+      errorMessage = `Tool "${tool.name}" timed out after ${timeoutMs}ms`;
+    }
+
+    return {
+      result: { success: false, error: errorMessage, durationMs },
+      content: `Error executing ${tool.name}: ${errorMessage}`,
+    };
+  }
+}
+
+// ─── Validation ──────────────────────────────────────────
+
+function validateToolInput(tool: AnyAgentTool, input: Record<string, any>): string | null {
+  var schema = tool.parameters;
+  if (!schema || !schema.required) return null;
+
+  for (var field of schema.required) {
+    if (input[field] === undefined || input[field] === null) {
+      return `Missing required parameter: "${field}" for tool "${tool.name}"`;
+    }
+  }
+
+  // Basic type checks
+  if (schema.properties) {
+    for (var [key, prop] of Object.entries(schema.properties)) {
+      if (input[key] === undefined) continue;
+
+      var expectedType = prop.type;
+      var actualValue = input[key];
+      var actualType = typeof actualValue;
+
+      if (expectedType === 'string' && actualType !== 'string') {
+        return `Parameter "${key}" must be a string, got ${actualType}`;
+      }
+      if (expectedType === 'number' && actualType !== 'number') {
+        return `Parameter "${key}" must be a number, got ${actualType}`;
+      }
+      if (expectedType === 'boolean' && actualType !== 'boolean') {
+        return `Parameter "${key}" must be a boolean, got ${actualType}`;
+      }
+      if (expectedType === 'array' && !Array.isArray(actualValue)) {
+        return `Parameter "${key}" must be an array`;
+      }
+    }
+  }
+
+  return null;
+}
+
+// ─── Timeout Wrapper ─────────────────────────────────────
+
+async function executeWithTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<T> {
+  if (signal?.aborted) {
+    throw new Error('Aborted');
+  }
+
+  return new Promise<T>(function(resolve, reject) {
+    var timer = setTimeout(function() {
+      var err = new Error('Tool execution timed out');
+      err.name = 'TimeoutError';
+      reject(err);
+    }, timeoutMs);
+
+    var onAbort = function() {
+      clearTimeout(timer);
+      var err = new Error('Tool execution aborted');
+      err.name = 'AbortError';
+      reject(err);
+    };
+
+    if (signal) {
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    promise.then(
+      function(value) {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        resolve(value);
+      },
+      function(err) {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        reject(err);
+      },
+    );
+  });
+}
+
+// ─── Result Formatting ──────────────────────────────────
+
+function formatToolResult(result: ToolResult): string {
+  if (!result.content || result.content.length === 0) {
+    return '(no output)';
+  }
+
+  var parts: string[] = [];
+  for (var block of result.content) {
+    if (block.type === 'text') {
+      parts.push(block.text);
+    } else if (block.type === 'image') {
+      parts.push(`[Image: ${block.mimeType}]`);
+    }
+  }
+
+  return parts.join('\n');
+}
+
+function truncateResult(content: string): string {
+  if (content.length <= MAX_RESULT_CHARS) return content;
+  var truncated = content.slice(0, MAX_RESULT_CHARS);
+  return truncated + `\n\n... [truncated, ${content.length - MAX_RESULT_CHARS} chars omitted]`;
+}

package/src/runtime/types.ts

@@ -0,0 +1,215 @@
+/**
+ * AgenticMail Agent Runtime — Core Types
+ *
+ * All types needed by the standalone agent runtime:
+ * messages, tool calls, sessions, config, streaming events.
+ */
+
+import type { AnyAgentTool } from '../agent-tools/types.js';
+
+// ─── Messages ────────────────────────────────────────────
+
+export type ContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'image'; source: { type: 'base64'; media_type: string; data: string } }
+  | { type: 'tool_use'; id: string; name: string; input: Record<string, any> }
+  | { type: 'tool_result'; tool_use_id: string; content: string | ContentBlock[]; is_error?: boolean }
+  | { type: 'thinking'; thinking: string };
+
+export interface AgentMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string | ContentBlock[];
+  tool_calls?: ToolCall[];
+  tool_results?: ToolResultMsg[];
+}
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  input: Record<string, any>;
+}
+
+export interface ToolResultMsg {
+  tool_use_id: string;
+  content: string;
+  is_error?: boolean;
+}
+
+// ─── Agent Configuration ─────────────────────────────────
+
+export interface ModelConfig {
+  /** Provider name — any registered or custom provider (e.g. 'anthropic', 'deepseek', 'ollama') */
+  provider: string;
+  modelId: string;
+  thinkingLevel?: 'off' | 'low' | 'medium' | 'high';
+  /** Override base URL for custom endpoints */
+  baseUrl?: string;
+  /** Extra headers for custom endpoints */
+  headers?: Record<string, string>;
+}
+
+export interface AgentConfig {
+  agentId: string;
+  orgId: string;
+  model: ModelConfig;
+  systemPrompt: string;
+  tools: AnyAgentTool[];
+  maxTurns?: number;         // 0 = unlimited (default), positive = hard cap
+  maxTokens?: number;        // default 8192
+  temperature?: number;      // default 0.7
+  contextWindowSize?: number; // default 1000000 (1M — most frontier models support this)
+}
+
+// ─── Session State ───────────────────────────────────────
+
+export type SessionStatus = 'active' | 'completed' | 'failed' | 'paused' | 'resuming';
+
+export interface SessionState {
+  id: string;
+  agentId: string;
+  orgId: string;
+  messages: AgentMessage[];
+  status: SessionStatus;
+  tokenCount: number;
+  turnCount: number;
+  createdAt: number;
+  updatedAt: number;
+  lastHeartbeatAt?: number;
+  parentSessionId?: string;
+  /** Total cost in USD tracked across the session */
+  costUsd?: number;
+}
+
+// ─── Streaming Events ────────────────────────────────────
+
+export type StreamEvent =
+  | { type: 'session_start'; sessionId: string }
+  | { type: 'session_resumed'; sessionId: string; turnCount: number }
+  | { type: 'turn_start'; turnNumber: number }
+  | { type: 'text_delta'; text: string }
+  | { type: 'thinking_delta'; text: string }
+  | { type: 'tool_call_start'; toolName: string; toolCallId: string }
+  | { type: 'tool_call_end'; toolName: string; result: any; blocked?: boolean }
+  | { type: 'turn_end'; stopReason: string }
+  | { type: 'checkpoint'; turnNumber: number; tokenCount: number; messageCount: number }
+  | { type: 'heartbeat'; timestamp: number; activeTurns: number }
+  | { type: 'retry'; attempt: number; maxRetries: number; delayMs: number; reason: string }
+  | { type: 'budget_warning'; remainingUsd: number; usedUsd: number }
+  | { type: 'budget_exceeded'; reason: string }
+  | { type: 'session_end'; summary: string }
+  | { type: 'error'; message: string; code?: string; retryable?: boolean };
+
+// ─── Runtime Configuration ───────────────────────────────
+
+export interface RuntimeConfig {
+  /** Engine DB instance for session persistence + hook calls */
+  engineDb: import('../engine/db-adapter.js').EngineDatabase;
+  /** Admin DB adapter (optional, for agent lookups) */
+  adminDb?: import('../db/adapter.js').DatabaseAdapter;
+  /** Default LLM model configuration */
+  defaultModel?: ModelConfig;
+  /** API keys keyed by provider name (e.g. { anthropic: 'sk-...', deepseek: 'sk-...' }) */
+  apiKeys?: Record<string, string>;
+  /** Max concurrent sessions (default: 100) */
+  maxConcurrentSessions?: number;
+  /** Session idle timeout in ms (default: 30 minutes) */
+  sessionIdleTimeoutMs?: number;
+  /** Enable the runtime gateway (HTTP API) */
+  gatewayEnabled?: boolean;
+  /** Resume active sessions on startup (default: true) */
+  resumeOnStartup?: boolean;
+  /** Heartbeat interval in ms (default: 30000 = 30s) */
+  heartbeatIntervalMs?: number;
+  /** Stale session timeout in ms — sessions with no heartbeat for this long are marked failed (default: 5 minutes) */
+  staleSessionTimeoutMs?: number;
+  /** LLM retry configuration */
+  retry?: {
+    /** Max duration to keep retrying in ms (default: 3600000 = 1 hour) */
+    maxRetryDurationMs?: number;
+    /** Max individual retries — secondary safety cap (default: 200) */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    baseDelayMs?: number;
+    /** Max delay in ms per retry (default: 60000 = 1 min) */
+    maxDelayMs?: number;
+  };
+}
+
+// ─── Hook Types ──────────────────────────────────────────
+
+export interface ToolCallContext {
+  toolCallId: string;
+  toolName: string;
+  parameters: Record<string, any>;
+  agentId: string;
+  orgId: string;
+  sessionId: string;
+}
+
+export interface HookResult {
+  allowed: boolean;
+  reason: string;
+  requiresApproval?: boolean;
+  approvalId?: string;
+  modifiedParameters?: Record<string, any>;
+}
+
+export interface ToolCallResult {
+  success: boolean;
+  output?: string;
+  error?: string;
+  durationMs?: number;
+}
+
+export interface BudgetCheckResult {
+  allowed: boolean;
+  reason?: string;
+  /** Remaining budget in USD (if known) */
+  remainingUsd?: number;
+  /** Estimated cost of next LLM call in USD */
+  estimatedCostUsd?: number;
+}
+
+export interface RuntimeHooks {
+  /** Inject KB context, policy context, memory before LLM call */
+  beforeLLMCall(messages: AgentMessage[], agentId: string, sessionId: string): Promise<AgentMessage[]>;
+  /** Check budget before making an LLM call (can block the call) */
+  checkBudget(agentId: string, orgId: string, estimatedTokens: number): Promise<BudgetCheckResult>;
+  /** Record LLM usage after each call */
+  recordLLMUsage(agentId: string, orgId: string, usage: { inputTokens: number; outputTokens: number; costUsd: number }): Promise<void>;
+  /** Look up model pricing from settings */
+  getModelPricing(provider: string, modelId: string): Promise<{ inputCostPerMillion: number; outputCostPerMillion: number } | null>;
+  /** Check permissions, DLP, guardrails before tool execution */
+  beforeToolCall(ctx: ToolCallContext): Promise<HookResult>;
+  /** Journal, activity, communication after tool execution */
+  afterToolCall(ctx: ToolCallContext, result: ToolCallResult): Promise<void>;
+  /** Session lifecycle */
+  onSessionStart(sessionId: string, agentId: string, orgId: string): Promise<void>;
+  onSessionEnd(sessionId: string, agentId: string, orgId: string): Promise<void>;
+  /** Flush learnings to memory on context compaction */
+  onContextCompaction(sessionId: string, agentId: string, summary: string): Promise<void>;
+}
+
+// ─── Spawn Options ───────────────────────────────────────
+
+export interface SpawnOptions {
+  agentId: string;
+  orgId?: string;
+  message: string;
+  model?: ModelConfig;
+  systemPrompt?: string;
+  tools?: AnyAgentTool[];
+  parentSessionId?: string;
+}
+
+// ─── Follow-Up ───────────────────────────────────────────
+
+export interface FollowUp {
+  id: string;
+  agentId: string;
+  sessionId?: string;
+  message: string;
+  executeAt: number;
+  status: 'pending' | 'executed' | 'cancelled';
+  createdAt: number;
+}