@agenticmail/enterprise 0.5.327 → 0.5.328

package/src/engine/activity.ts

@@ -1,568 +0,0 @@
-/**
- * Real-Time Activity & Observability
- *
- * See what every agent is doing RIGHT NOW:
- * - Live tool call stream
- * - Conversation logs
- * - Error tracking
- * - Cost tracking per call
- * - Session timeline
- *
- * This powers the "live view" in the dashboard where admins
- * can watch their agent employee work in real-time.
- */
-
-// ─── Types ──────────────────────────────────────────────
-
-export interface ActivityEvent {
-  id: string;
-  agentId: string;
-  orgId: string;
-  sessionId?: string;
-  timestamp: string;
-  type: ActivityType;
-  data: Record<string, any>;
-}
-
-export type ActivityType =
-  | 'session_start'
-  | 'session_end'
-  | 'message_received'      // Agent received a message from user/channel
-  | 'message_sent'          // Agent sent a reply
-  | 'tool_call_start'       // Agent is calling a tool
-  | 'tool_call_end'         // Tool returned result
-  | 'tool_call_error'       // Tool call failed
-  | 'tool_blocked'          // Permission engine blocked a tool
-  | 'approval_requested'    // Waiting for human approval
-  | 'approval_decided'      // Human approved/denied
-  | 'email_received'
-  | 'email_sent'
-  | 'task_assigned'         // Agent assigned to another agent
-  | 'task_completed'
-  | 'error'                 // General error
-  | 'warning'               // Non-fatal issue
-  | 'heartbeat'             // Periodic check-in
-  | 'memory_write'          // Agent wrote to memory
-  | 'budget_alert'          // Approaching or exceeding budget
-  | 'llm_call';             // LLM API call
-
-export interface ToolCallRecord {
-  id: string;
-  agentId: string;
-  orgId: string;
-  sessionId: string;
-  toolId: string;
-  toolName: string;
-  parameters: Record<string, any>;  // Sanitized (no secrets)
-  result?: {
-    success: boolean;
-    truncatedOutput?: string;        // First 500 chars
-    error?: string;
-  };
-  timing: {
-    startedAt: string;
-    completedAt?: string;
-    durationMs?: number;
-  };
-  cost?: {
-    inputTokens: number;
-    outputTokens: number;
-    estimatedCostUsd: number;
-  };
-  permission: {
-    allowed: boolean;
-    reason: string;
-    requiredApproval: boolean;
-    approvalId?: string;
-  };
-}
-
-export interface ConversationEntry {
-  id: string;
-  agentId: string;
-  sessionId: string;
-  timestamp: string;
-  role: 'user' | 'assistant' | 'system';
-  content: string;                   // Truncated for storage
-  channel?: string;                  // Which channel (email, whatsapp, slack, etc.)
-  tokenCount: number;
-  toolCalls?: string[];              // Tool call IDs referenced in this turn
-}
-
-export interface AgentTimeline {
-  agentId: string;
-  date: string;                      // YYYY-MM-DD
-  events: TimelineEntry[];
-  summary: {
-    totalSessions: number;
-    totalMessages: number;
-    totalToolCalls: number;
-    totalErrors: number;
-    totalTokens: number;
-    totalCostUsd: number;
-    topTools: { toolId: string; count: number }[];
-    activeHours: number[];           // Which hours the agent was active (0-23)
-  };
-}
-
-export interface TimelineEntry {
-  timestamp: string;
-  type: ActivityType;
-  summary: string;                   // Human-readable one-liner
-  details?: Record<string, any>;
-  durationMs?: number;
-}
-
-// ─── Activity Tracker ───────────────────────────────────
-
-import type { EngineDatabase } from './db-adapter.js';
-
-export class ActivityTracker {
-  private events: ActivityEvent[] = [];
-  private toolCalls = new Map<string, ToolCallRecord>();
-  private conversations: ConversationEntry[] = [];
-  private listeners: ((event: ActivityEvent) => void)[] = [];
-  private sseClients = new Set<(event: ActivityEvent) => void>();
-  private engineDb?: EngineDatabase;
-
-  // Buffer settings
-  private maxEvents = 10_000;        // Keep last N events in memory
-  private maxToolCalls = 5_000;
-  private maxConversations = 5_000;
-
-  /**
-   * Set the database adapter for persistent activity storage
-   */
-  async setDb(db: EngineDatabase): Promise<void> {
-    this.engineDb = db;
-    await this.loadFromDb();
-  }
-
-  private async loadFromDb(): Promise<void> {
-    if (!this.engineDb) return;
-    try {
-      // Load recent events (last 24h) to warm the cache
-      const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
-      const events = await this.engineDb.getActivityEvents({ since, limit: this.maxEvents });
-      this.events = events.reverse(); // DB returns DESC, we want ASC for our buffer
-
-      // Load recent tool calls (last 24h)
-      const toolCalls = await this.engineDb.getToolCalls({ since, limit: this.maxToolCalls });
-      for (const tc of toolCalls) {
-        this.toolCalls.set(tc.id, tc);
-      }
-    } catch {
-      // Table may not exist yet if migrations haven't run
-    }
-  }
-
-  // ─── Record Events ───────────────────────────────────
-
-  /**
-   * Record a generic activity event
-   */
-  record(event: Omit<ActivityEvent, 'id' | 'timestamp'>): ActivityEvent {
-    const full: ActivityEvent = {
-      ...event,
-      id: crypto.randomUUID(),
-      timestamp: new Date().toISOString(),
-    };
-
-    this.events.push(full);
-    if (this.events.length > this.maxEvents) {
-      this.events = this.events.slice(-this.maxEvents);
-    }
-
-    // Persist to DB (fire-and-forget — high-volume telemetry)
-    this.engineDb?.insertActivityEvent(full).catch((err) => {
-      console.error('[activity] Failed to persist event:', err);
-    });
-
-    // Notify listeners
-    for (const listener of this.listeners) {
-      try { listener(full); } catch { /* ignore */ }
-    }
-    for (const client of this.sseClients) {
-      try { client(full); } catch { this.sseClients.delete(client); }
-    }
-
-    return full;
-  }
-
-  /**
-   * Record a tool call starting
-   */
-  startToolCall(opts: {
-    agentId: string;
-    orgId: string;
-    sessionId: string;
-    toolId: string;
-    toolName: string;
-    parameters: Record<string, any>;
-    permission: ToolCallRecord['permission'];
-  }): ToolCallRecord {
-    const record: ToolCallRecord = {
-      id: crypto.randomUUID(),
-      agentId: opts.agentId,
-      orgId: opts.orgId,
-      sessionId: opts.sessionId,
-      toolId: opts.toolId,
-      toolName: opts.toolName,
-      parameters: this.sanitizeParams(opts.parameters),
-      timing: { startedAt: new Date().toISOString() },
-      permission: opts.permission,
-    };
-
-    this.toolCalls.set(record.id, record);
-    if (this.toolCalls.size > this.maxToolCalls) {
-      // Remove oldest entries
-      const keys = Array.from(this.toolCalls.keys());
-      for (let i = 0; i < 1000; i++) this.toolCalls.delete(keys[i]);
-    }
-
-    // Persist to DB (fire-and-forget — high-volume telemetry)
-    this.engineDb?.insertToolCall(record).catch((err) => {
-      console.error('[activity] Failed to persist tool call:', err);
-    });
-
-    this.record({
-      agentId: opts.agentId,
-      orgId: opts.orgId,
-      sessionId: opts.sessionId,
-      type: opts.permission.allowed ? 'tool_call_start' : 'tool_blocked',
-      data: { toolCallId: record.id, toolId: opts.toolId, toolName: opts.toolName },
-    });
-
-    return record;
-  }
-
-  /**
-   * Lightweight tool call recording — single in-memory record + single DB insert.
-   * Used by agent-loop to avoid 4x DB writes per tool call.
-   */
-  recordToolCallCompact(opts: {
-    agentId: string; orgId: string; sessionId: string;
-    tool: string; success: boolean; durationMs?: number; error?: string;
-  }): void {
-    const record: ToolCallRecord = {
-      id: crypto.randomUUID(),
-      agentId: opts.agentId,
-      orgId: opts.orgId,
-      sessionId: opts.sessionId,
-      toolId: opts.tool,
-      toolName: opts.tool,
-      parameters: {},
-      timing: {
-        startedAt: new Date().toISOString(),
-        completedAt: new Date().toISOString(),
-        durationMs: opts.durationMs,
-      },
-      result: { success: opts.success, error: opts.error },
-      permission: { allowed: true, reason: '', requiredApproval: false },
-    };
-    this.toolCalls.set(record.id, record);
-    if (this.toolCalls.size > this.maxToolCalls) {
-      const keys = Array.from(this.toolCalls.keys());
-      for (let i = 0; i < 1000; i++) this.toolCalls.delete(keys[i]);
-    }
-    // Single DB write (fire-and-forget)
-    this.engineDb?.insertToolCall(record).catch(() => {});
-  }
-
-  /**
-   * Record a tool call completing
-   */
-  endToolCall(toolCallId: string, result: {
-    success: boolean;
-    output?: string;
-    error?: string;
-    inputTokens?: number;
-    outputTokens?: number;
-    costUsd?: number;
-  }) {
-    const record = this.toolCalls.get(toolCallId);
-    if (!record) return;
-
-    record.timing.completedAt = new Date().toISOString();
-    record.timing.durationMs = new Date(record.timing.completedAt).getTime() -
-      new Date(record.timing.startedAt).getTime();
-
-    record.result = {
-      success: result.success,
-      truncatedOutput: result.output?.slice(0, 500),
-      error: result.error,
-    };
-
-    if (result.inputTokens || result.outputTokens || result.costUsd) {
-      record.cost = {
-        inputTokens: result.inputTokens || 0,
-        outputTokens: result.outputTokens || 0,
-        estimatedCostUsd: result.costUsd || 0,
-      };
-    }
-
-    // Persist to DB (fire-and-forget — high-volume telemetry)
-    this.engineDb?.updateToolCallResult(record.id, record.result, record.timing, record.cost).catch((err) => {
-      console.error('[activity] Failed to update tool call result:', err);
-    });
-
-    this.record({
-      agentId: record.agentId,
-      orgId: record.orgId,
-      sessionId: record.sessionId,
-      type: result.success ? 'tool_call_end' : 'tool_call_error',
-      data: {
-        toolCallId, toolId: record.toolId,
-        durationMs: record.timing.durationMs,
-        success: result.success,
-        error: result.error,
-      },
-    });
-  }
-
-  /**
-   * Record a conversation message
-   */
-  recordMessage(entry: Omit<ConversationEntry, 'id' | 'timestamp'>): ConversationEntry {
-    const full: ConversationEntry = {
-      ...entry,
-      id: crypto.randomUUID(),
-      timestamp: new Date().toISOString(),
-      content: entry.content.slice(0, 2000), // Truncate
-    };
-
-    this.conversations.push(full);
-    if (this.conversations.length > this.maxConversations) {
-      this.conversations = this.conversations.slice(-this.maxConversations);
-    }
-
-    // Persist to DB (fire-and-forget — high-volume telemetry)
-    this.engineDb?.insertConversation(full).catch((err) => {
-      console.error('[activity] Failed to persist conversation:', err);
-    });
-
-    this.record({
-      agentId: entry.agentId,
-      orgId: '',
-      sessionId: entry.sessionId,
-      type: entry.role === 'user' ? 'message_received' : 'message_sent',
-      data: { messageId: full.id, role: entry.role, channel: entry.channel, tokenCount: entry.tokenCount },
-    });
-
-    return full;
-  }
-
-  // ─── Query ──────────────────────────────────────────
-
-  /**
-   * Get recent events for an agent
-   */
-  getEvents(opts: {
-    agentId?: string;
-    orgId?: string;
-    types?: ActivityType[];
-    since?: string;
-    limit?: number;
-  }): ActivityEvent[] {
-    let events = [...this.events];
-
-    if (opts.agentId) events = events.filter(e => e.agentId === opts.agentId);
-    if (opts.orgId) events = events.filter(e => e.orgId === opts.orgId);
-    if (opts.types?.length) events = events.filter(e => opts.types!.includes(e.type));
-    if (opts.since) {
-      const sinceTs = new Date(opts.since).getTime();
-      events = events.filter(e => new Date(e.timestamp).getTime() >= sinceTs);
-    }
-
-    events.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
-    return events.slice(0, opts.limit || 50);
-  }
-
-  /**
-   * Get tool call history for an agent
-   */
-  getToolCalls(opts: {
-    agentId?: string;
-    orgId?: string;
-    toolId?: string;
-    limit?: number;
-  }): ToolCallRecord[] {
-    let calls = Array.from(this.toolCalls.values());
-    if (opts.agentId) calls = calls.filter(c => c.agentId === opts.agentId);
-    if (opts.orgId) calls = calls.filter(c => c.orgId === opts.orgId);
-    if (opts.toolId) calls = calls.filter(c => c.toolId === opts.toolId);
-    calls.sort((a, b) => new Date(b.timing.startedAt).getTime() - new Date(a.timing.startedAt).getTime());
-    return calls.slice(0, opts.limit || 50);
-  }
-
-  /**
-   * Get conversation history for a session
-   */
-  async getConversation(sessionId: string, limit: number = 50): Promise<ConversationEntry[]> {
-    // Check memory first
-    const memResults = this.conversations
-      .filter(c => c.sessionId === sessionId)
-      .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime())
-      .slice(-limit);
-
-    if (memResults.length > 0) return memResults;
-
-    // Fall back to DB for sessions not in memory buffer
-    if (this.engineDb) {
-      try {
-        return await this.engineDb.getConversation(sessionId, limit);
-      } catch { /* fall through */ }
-    }
-    return [];
-  }
-
-  /**
-   * Generate a daily timeline for an agent
-   */
-  getTimeline(agentId: string, date: string): AgentTimeline {
-    const dayStart = new Date(date + 'T00:00:00Z');
-    const dayEnd = new Date(date + 'T23:59:59Z');
-
-    const dayEvents = this.events.filter(e => {
-      if (e.agentId !== agentId) return false;
-      const ts = new Date(e.timestamp).getTime();
-      return ts >= dayStart.getTime() && ts <= dayEnd.getTime();
-    });
-
-    const dayToolCalls = Array.from(this.toolCalls.values()).filter(tc => {
-      if (tc.agentId !== agentId) return false;
-      const ts = new Date(tc.timing.startedAt).getTime();
-      return ts >= dayStart.getTime() && ts <= dayEnd.getTime();
-    });
-
-    // Compute tool usage stats
-    const toolCounts = new Map<string, number>();
-    let totalTokens = 0, totalCost = 0, totalErrors = 0;
-    const activeHours = new Set<number>();
-
-    for (const tc of dayToolCalls) {
-      toolCounts.set(tc.toolId, (toolCounts.get(tc.toolId) || 0) + 1);
-      if (tc.cost) {
-        totalTokens += tc.cost.inputTokens + tc.cost.outputTokens;
-        totalCost += tc.cost.estimatedCostUsd;
-      }
-      if (tc.result && !tc.result.success) totalErrors++;
-      activeHours.add(new Date(tc.timing.startedAt).getUTCHours());
-    }
-
-    const topTools = Array.from(toolCounts.entries())
-      .map(([toolId, count]) => ({ toolId, count }))
-      .sort((a, b) => b.count - a.count)
-      .slice(0, 10);
-
-    const totalMessages = dayEvents.filter(e =>
-      e.type === 'message_received' || e.type === 'message_sent'
-    ).length;
-
-    const totalSessions = new Set(dayEvents.filter(e => e.sessionId).map(e => e.sessionId)).size;
-
-    return {
-      agentId,
-      date,
-      events: dayEvents.map(e => ({
-        timestamp: e.timestamp,
-        type: e.type,
-        summary: this.summarizeEvent(e),
-        details: e.data,
-      })),
-      summary: {
-        totalSessions,
-        totalMessages,
-        totalToolCalls: dayToolCalls.length,
-        totalErrors,
-        totalTokens,
-        totalCostUsd: totalCost,
-        topTools,
-        activeHours: Array.from(activeHours).sort((a, b) => a - b),
-      },
-    };
-  }
-
-  // ─── Real-time Streaming (SSE) ────────────────────────
-
-  /**
-   * Subscribe to real-time events (for SSE endpoint)
-   */
-  subscribe(callback: (event: ActivityEvent) => void): () => void {
-    this.sseClients.add(callback);
-    return () => this.sseClients.delete(callback);
-  }
-
-  /**
-   * Subscribe to events (general listener)
-   */
-  onEvent(listener: (event: ActivityEvent) => void): () => void {
-    this.listeners.push(listener);
-    return () => { this.listeners = this.listeners.filter(l => l !== listener); };
-  }
-
-  // ─── Stats ──────────────────────────────────────────
-
-  /**
-   * Get real-time stats for dashboard
-   */
-  getStats(orgId?: string): {
-    eventsLast5min: number;
-    toolCallsLast5min: number;
-    errorsLast5min: number;
-    activeAgents: string[];
-    activeSessions: number;
-  } {
-    const fiveMinAgo = new Date(Date.now() - 5 * 60_000).toISOString();
-    let recent = this.events.filter(e => e.timestamp >= fiveMinAgo);
-    if (orgId) recent = recent.filter(e => e.orgId === orgId);
-
-    const toolCalls = recent.filter(e => e.type === 'tool_call_start' || e.type === 'tool_call_end');
-    const errors = recent.filter(e => e.type === 'tool_call_error' || e.type === 'error');
-    const activeAgents = [...new Set(recent.map(e => e.agentId))];
-    const activeSessions = new Set(recent.filter(e => e.sessionId).map(e => e.sessionId)).size;
-
-    return {
-      eventsLast5min: recent.length,
-      toolCallsLast5min: toolCalls.length,
-      errorsLast5min: errors.length,
-      activeAgents,
-      activeSessions,
-    };
-  }
-
-  // ─── Private ──────────────────────────────────────────
-
-  private sanitizeParams(params: Record<string, any>): Record<string, any> {
-    const sanitized = { ...params };
-    const sensitiveKeys = ['password', 'token', 'secret', 'key', 'apiKey', 'credential', 'authorization'];
-    for (const key of Object.keys(sanitized)) {
-      if (sensitiveKeys.some(sk => key.toLowerCase().includes(sk))) {
-        sanitized[key] = '***';
-      }
-      // Truncate large values
-      if (typeof sanitized[key] === 'string' && sanitized[key].length > 200) {
-        sanitized[key] = sanitized[key].slice(0, 200) + '...';
-      }
-    }
-    return sanitized;
-  }
-
-  private summarizeEvent(event: ActivityEvent): string {
-    switch (event.type) {
-      case 'session_start': return 'Session started';
-      case 'session_end': return 'Session ended';
-      case 'message_received': return `Received message via ${event.data.channel || 'unknown'}`;
-      case 'message_sent': return `Sent reply via ${event.data.channel || 'unknown'}`;
-      case 'tool_call_start': return `Called ${event.data.toolName || event.data.toolId}`;
-      case 'tool_call_end': return `${event.data.toolName || event.data.toolId} completed (${event.data.durationMs}ms)`;
-      case 'tool_call_error': return `${event.data.toolName || event.data.toolId} failed: ${event.data.error}`;
-      case 'tool_blocked': return `Blocked: ${event.data.toolName || event.data.toolId}`;
-      case 'email_received': return 'Received email';
-      case 'email_sent': return 'Sent email';
-      case 'error': return `Error: ${event.data.message || 'Unknown'}`;
-      case 'heartbeat': return 'Heartbeat check';
-      default: return event.type;
-    }
-  }
-}