swarm-mail 0.1.0 → 0.1.3

package/src/streams/debug.ts

@@ -1,727 +0,0 @@
-/**
- * Swarm Mail Debug Tools - Event inspection and state debugging
- *
- * Tools for inspecting the event store, agent state, and system health.
- * Useful for debugging issues and understanding system behavior.
- */
-import { getDatabase, getDatabaseStats } from "./index";
-import { readEvents, getLatestSequence, replayEventsBatched } from "./store";
-import { getAgent, getActiveReservations, getMessage } from "./projections";
-import type { AgentEvent } from "./events";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface DebugEventsOptions {
-  projectPath: string;
-  types?: AgentEvent["type"][];
-  agentName?: string;
-  limit?: number;
-  since?: number;
-  until?: number;
-}
-
-export interface DebugEventResult {
-  id: number;
-  sequence: number;
-  type: AgentEvent["type"];
-  timestamp: number;
-  timestamp_human: string;
-  agent_name?: string;
-  from_agent?: string;
-  to_agents?: string[];
-  [key: string]: unknown;
-}
-
-export interface DebugEventsResult {
-  events: DebugEventResult[];
-  total: number;
-}
-
-export interface DebugAgentOptions {
-  projectPath: string;
-  agentName: string;
-  includeEvents?: boolean;
-}
-
-export interface DebugAgentResult {
-  agent: {
-    name: string;
-    program: string;
-    model: string;
-    task_description: string | null;
-    registered_at: number;
-    last_active_at: number;
-  } | null;
-  stats: {
-    messagesSent: number;
-    messagesReceived: number;
-  };
-  reservations: Array<{
-    id: number;
-    path: string;
-    reason: string | null;
-    expires_at: number;
-  }>;
-  recentEvents?: DebugEventResult[];
-}
-
-export interface DebugMessageOptions {
-  projectPath: string;
-  messageId: number;
-  includeEvents?: boolean;
-}
-
-export interface DebugMessageResult {
-  message: {
-    id: number;
-    from_agent: string;
-    subject: string;
-    body: string;
-    thread_id: string | null;
-    importance: string;
-    created_at: number;
-  } | null;
-  recipients: Array<{
-    agent_name: string;
-    read_at: number | null;
-    acked_at: number | null;
-  }>;
-  events?: DebugEventResult[];
-}
-
-export interface DebugReservationsOptions {
-  projectPath: string;
-  checkConflicts?: boolean;
-}
-
-export interface DebugReservationsResult {
-  reservations: Array<{
-    id: number;
-    agent_name: string;
-    path_pattern: string;
-    reason: string | null;
-    expires_at: number;
-    expires_in_human: string;
-  }>;
-  byAgent: Record<string, Array<{ path: string; expires_at: number }>>;
-  conflicts?: Array<{
-    path1: string;
-    agent1: string;
-    path2: string;
-    agent2: string;
-  }>;
-}
-
-export interface TimelineEntry {
-  time: string;
-  type: AgentEvent["type"];
-  summary: string;
-  agent: string;
-  sequence: number;
-}
-
-export interface TimelineResult {
-  timeline: TimelineEntry[];
-}
-
-export interface InspectStateOptions {
-  projectPath: string;
-  format?: "object" | "json";
-}
-
-export interface InspectStateResult {
-  agents: Array<{
-    name: string;
-    program: string;
-    model: string;
-    task_description: string | null;
-  }>;
-  messages: Array<{
-    id: number;
-    from_agent: string;
-    subject: string;
-    thread_id: string | null;
-  }>;
-  reservations: Array<{
-    id: number;
-    agent_name: string;
-    path_pattern: string;
-  }>;
-  eventCount: number;
-  latestSequence: number;
-  stats: {
-    events: number;
-    agents: number;
-    messages: number;
-    reservations: number;
-  };
-  json?: string;
-}
-
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-/**
- * Format timestamp as human-readable ISO string
- */
-function formatTimestamp(timestamp: number): string {
-  return new Date(timestamp).toISOString();
-}
-
-/**
- * Format duration as human-readable string
- */
-function formatDuration(ms: number): string {
-  if (ms < 0) return "expired";
-  if (ms < 60000) return `${Math.round(ms / 1000)}s`;
-  if (ms < 3600000) return `${Math.round(ms / 60000)}m`;
-  if (ms < 86400000) return `${Math.round(ms / 3600000)}h`;
-  return `${Math.round(ms / 86400000)}d`;
-}
-
-/**
- * Generate event summary for timeline
- */
-function summarizeEvent(
-  event: AgentEvent & { id: number; sequence: number },
-): string {
-  switch (event.type) {
-    case "agent_registered":
-      return `Agent ${event.agent_name} registered (${event.program}/${event.model})`;
-    case "agent_active":
-      return `Agent ${event.agent_name} active`;
-    case "message_sent":
-      return `${event.from_agent} → ${event.to_agents.join(", ")}: "${event.subject}"`;
-    case "message_read":
-      return `${event.agent_name} read message #${event.message_id}`;
-    case "message_acked":
-      return `${event.agent_name} acked message #${event.message_id}`;
-    case "file_reserved":
-      return `${event.agent_name} reserved ${event.paths.length} file(s)`;
-    case "file_released":
-      return `${event.agent_name} released files`;
-    case "task_started":
-      return `${event.agent_name} started task: ${event.bead_id}`;
-    case "task_progress":
-      return `${event.agent_name} progress on ${event.bead_id}: ${event.progress_percent}%`;
-    case "task_completed":
-      return `${event.agent_name} completed ${event.bead_id}`;
-    case "task_blocked":
-      return `${event.agent_name} blocked on ${event.bead_id}: ${event.reason}`;
-    default:
-      return `Unknown event type`;
-  }
-}
-
-/**
- * Get agent name from event (handles different event types)
- */
-function getAgentFromEvent(event: AgentEvent): string {
-  if ("agent_name" in event && event.agent_name) return event.agent_name;
-  if ("from_agent" in event && event.from_agent) return event.from_agent;
-  return "unknown";
-}
-
-// ============================================================================
-// Debug Functions
-// ============================================================================
-
-/**
- * Get recent events with filtering
- *
- * For large event logs (>100k events), consider using batchSize option
- * to paginate through results instead of loading all events.
- */
-export async function debugEvents(
-  options: DebugEventsOptions & { batchSize?: number },
-): Promise<DebugEventsResult> {
-  const {
-    projectPath,
-    types,
-    agentName,
-    limit = 50,
-    since,
-    until,
-    batchSize,
-  } = options;
-
-  // If batchSize is specified, use pagination to avoid OOM
-  if (batchSize && batchSize > 0) {
-    return await debugEventsPaginated({ ...options, batchSize });
-  }
-
-  // Get all events first (we'll filter in memory for agent name)
-  const allEvents = await readEvents(
-    {
-      projectKey: projectPath,
-      types,
-      since,
-      until,
-    },
-    projectPath,
-  );
-
-  // Filter by agent name if specified
-  let filteredEvents = allEvents;
-  if (agentName) {
-    filteredEvents = allEvents.filter((e) => {
-      if ("agent_name" in e && e.agent_name === agentName) return true;
-      if ("from_agent" in e && e.from_agent === agentName) return true;
-      if ("to_agents" in e && e.to_agents?.includes(agentName)) return true;
-      return false;
-    });
-  }
-
-  // Sort by sequence descending (most recent first)
-  filteredEvents.sort((a, b) => b.sequence - a.sequence);
-
-  // Apply limit
-  const limitedEvents = filteredEvents.slice(0, limit);
-
-  // Format for output - extract known fields, spread rest
-  const events: DebugEventResult[] = limitedEvents.map((e) => {
-    const { id, sequence, type, timestamp, project_key, ...rest } = e;
-    return {
-      id,
-      sequence,
-      type,
-      timestamp,
-      timestamp_human: formatTimestamp(timestamp),
-      ...rest,
-    };
-  });
-
-  return {
-    events,
-    total: filteredEvents.length,
-  };
-}
-
-/**
- * Get events using pagination to avoid OOM on large logs
- */
-async function debugEventsPaginated(
-  options: DebugEventsOptions & { batchSize: number },
-): Promise<DebugEventsResult> {
-  const {
-    projectPath,
-    types,
-    agentName,
-    limit = 50,
-    since,
-    until,
-    batchSize,
-  } = options;
-
-  const allEvents: Array<AgentEvent & { id: number; sequence: number }> = [];
-  let offset = 0;
-  let hasMore = true;
-
-  // Fetch in batches until we have enough events or run out
-  while (hasMore && allEvents.length < limit) {
-    const batch = await readEvents(
-      {
-        projectKey: projectPath,
-        types,
-        since,
-        until,
-        limit: batchSize,
-        offset,
-      },
-      projectPath,
-    );
-
-    if (batch.length === 0) {
-      hasMore = false;
-      break;
-    }
-
-    // Filter by agent name if specified
-    const filtered = agentName
-      ? batch.filter((e) => {
-          if ("agent_name" in e && e.agent_name === agentName) return true;
-          if ("from_agent" in e && e.from_agent === agentName) return true;
-          if ("to_agents" in e && e.to_agents?.includes(agentName)) return true;
-          return false;
-        })
-      : batch;
-
-    allEvents.push(...filtered);
-    offset += batchSize;
-
-    console.log(
-      `[SwarmMail] Fetched ${allEvents.length} events (batch size: ${batchSize})`,
-    );
-  }
-
-  // Sort by sequence descending (most recent first)
-  allEvents.sort((a, b) => b.sequence - a.sequence);
-
-  // Apply limit
-  const limitedEvents = allEvents.slice(0, limit);
-
-  // Format for output
-  const events: DebugEventResult[] = limitedEvents.map((e) => {
-    const { id, sequence, type, timestamp, project_key, ...rest } = e;
-    return {
-      id,
-      sequence,
-      type,
-      timestamp,
-      timestamp_human: formatTimestamp(timestamp),
-      ...rest,
-    };
-  });
-
-  return {
-    events,
-    total: allEvents.length,
-  };
-}
-
-/**
- * Get detailed agent information
- */
-export async function debugAgent(
-  options: DebugAgentOptions,
-): Promise<DebugAgentResult> {
-  const { projectPath, agentName, includeEvents = false } = options;
-
-  // Get agent from projections
-  const agent = await getAgent(projectPath, agentName, projectPath);
-
-  if (!agent) {
-    return {
-      agent: null,
-      stats: { messagesSent: 0, messagesReceived: 0 },
-      reservations: [],
-    };
-  }
-
-  // Get message counts
-  const db = await getDatabase(projectPath);
-  const sentResult = await db.query<{ count: string }>(
-    `SELECT COUNT(*) as count FROM messages WHERE project_key = $1 AND from_agent = $2`,
-    [projectPath, agentName],
-  );
-  const receivedResult = await db.query<{ count: string }>(
-    `SELECT COUNT(*) as count FROM message_recipients mr
-     JOIN messages m ON mr.message_id = m.id
-     WHERE m.project_key = $1 AND mr.agent_name = $2`,
-    [projectPath, agentName],
-  );
-
-  // Get active reservations
-  const reservations = await getActiveReservations(
-    projectPath,
-    projectPath,
-    agentName,
-  );
-
-  const result: DebugAgentResult = {
-    agent: {
-      name: agent.name,
-      program: agent.program,
-      model: agent.model,
-      task_description: agent.task_description,
-      registered_at: agent.registered_at,
-      last_active_at: agent.last_active_at,
-    },
-    stats: {
-      messagesSent: parseInt(sentResult.rows[0]?.count || "0"),
-      messagesReceived: parseInt(receivedResult.rows[0]?.count || "0"),
-    },
-    reservations: reservations.map((r) => ({
-      id: r.id,
-      path: r.path_pattern,
-      reason: r.reason,
-      expires_at: r.expires_at,
-    })),
-  };
-
-  // Include recent events if requested
-  if (includeEvents) {
-    const eventsResult = await debugEvents({
-      projectPath,
-      agentName,
-      limit: 20,
-    });
-    result.recentEvents = eventsResult.events;
-  }
-
-  return result;
-}
-
-/**
- * Get detailed message information with audit trail
- */
-export async function debugMessage(
-  options: DebugMessageOptions,
-): Promise<DebugMessageResult> {
-  const { projectPath, messageId, includeEvents = false } = options;
-
-  // Get message from projections
-  const message = await getMessage(projectPath, messageId, projectPath);
-
-  if (!message) {
-    return {
-      message: null,
-      recipients: [],
-    };
-  }
-
-  // Get recipients
-  const db = await getDatabase(projectPath);
-  const recipientsResult = await db.query<{
-    agent_name: string;
-    read_at: string | null;
-    acked_at: string | null;
-  }>(
-    `SELECT agent_name, read_at, acked_at FROM message_recipients WHERE message_id = $1`,
-    [messageId],
-  );
-
-  const result: DebugMessageResult = {
-    message: {
-      id: message.id,
-      from_agent: message.from_agent,
-      subject: message.subject,
-      body: message.body ?? "",
-      thread_id: message.thread_id,
-      importance: message.importance,
-      created_at: message.created_at,
-    },
-    recipients: recipientsResult.rows.map((r) => ({
-      agent_name: r.agent_name,
-      read_at: r.read_at ? parseInt(r.read_at) : null,
-      acked_at: r.acked_at ? parseInt(r.acked_at) : null,
-    })),
-  };
-
-  // Include related events if requested
-  if (includeEvents) {
-    const allEvents = await readEvents(
-      { projectKey: projectPath },
-      projectPath,
-    );
-    const relatedEvents = allEvents.filter((e) => {
-      if (e.type === "message_sent" && e.subject === message.subject)
-        return true;
-      if (
-        (e.type === "message_read" || e.type === "message_acked") &&
-        e.message_id === messageId
-      )
-        return true;
-      return false;
-    });
-
-    result.events = relatedEvents.map((e) => {
-      const { id, sequence, type, timestamp, project_key, ...rest } = e;
-      return {
-        id,
-        sequence,
-        type,
-        timestamp,
-        timestamp_human: formatTimestamp(timestamp),
-        ...rest,
-      };
-    });
-  }
-
-  return result;
-}
-
-/**
- * Get current reservation state
- */
-export async function debugReservations(
-  options: DebugReservationsOptions,
-): Promise<DebugReservationsResult> {
-  const { projectPath, checkConflicts = false } = options;
-
-  const reservations = await getActiveReservations(projectPath, projectPath);
-  const now = Date.now();
-
-  // Format reservations
-  const formattedReservations = reservations.map((r) => ({
-    id: r.id,
-    agent_name: r.agent_name,
-    path_pattern: r.path_pattern,
-    reason: r.reason,
-    expires_at: r.expires_at,
-    expires_in_human: formatDuration(r.expires_at - now),
-  }));
-
-  // Group by agent
-  const byAgent: Record<
-    string,
-    Array<{ path: string; expires_at: number }>
-  > = {};
-  for (const r of reservations) {
-    if (!byAgent[r.agent_name]) {
-      byAgent[r.agent_name] = [];
-    }
-    byAgent[r.agent_name].push({
-      path: r.path_pattern,
-      expires_at: r.expires_at,
-    });
-  }
-
-  const result: DebugReservationsResult = {
-    reservations: formattedReservations,
-    byAgent,
-  };
-
-  // Check for conflicts if requested
-  if (checkConflicts) {
-    const conflicts: Array<{
-      path1: string;
-      agent1: string;
-      path2: string;
-      agent2: string;
-    }> = [];
-
-    // Simple overlap detection - check if any patterns might conflict
-    for (let i = 0; i < reservations.length; i++) {
-      for (let j = i + 1; j < reservations.length; j++) {
-        const r1 = reservations[i];
-        const r2 = reservations[j];
-
-        // Skip same agent
-        if (r1.agent_name === r2.agent_name) continue;
-
-        // Check for potential overlap (simple heuristic)
-        const p1 = r1.path_pattern;
-        const p2 = r2.path_pattern;
-
-        // Glob pattern might overlap with specific file
-        if (
-          p1.includes("**") &&
-          p2.startsWith(p1.replace("/**", "").replace("**", ""))
-        ) {
-          conflicts.push({
-            path1: p1,
-            agent1: r1.agent_name,
-            path2: p2,
-            agent2: r2.agent_name,
-          });
-        } else if (
-          p2.includes("**") &&
-          p1.startsWith(p2.replace("/**", "").replace("**", ""))
-        ) {
-          conflicts.push({
-            path1: p2,
-            agent1: r2.agent_name,
-            path2: p1,
-            agent2: r1.agent_name,
-          });
-        }
-      }
-    }
-
-    result.conflicts = conflicts;
-  }
-
-  return result;
-}
-
-/**
- * Get event timeline for visualization
- */
-export async function getEventTimeline(options: {
-  projectPath: string;
-  since?: number;
-  until?: number;
-  limit?: number;
-}): Promise<TimelineResult> {
-  const { projectPath, since, until, limit = 100 } = options;
-
-  const events = await readEvents(
-    {
-      projectKey: projectPath,
-      since,
-      until,
-      limit,
-    },
-    projectPath,
-  );
-
-  // Sort by sequence ascending for timeline
-  events.sort((a, b) => a.sequence - b.sequence);
-
-  const timeline: TimelineEntry[] = events.map((e) => ({
-    time: formatTimestamp(e.timestamp),
-    type: e.type,
-    summary: summarizeEvent(e),
-    agent: getAgentFromEvent(e),
-    sequence: e.sequence,
-  }));
-
-  return { timeline };
-}
-
-/**
- * Get complete state snapshot for debugging
- */
-export async function inspectState(
-  options: InspectStateOptions,
-): Promise<InspectStateResult> {
-  const { projectPath, format = "object" } = options;
-
-  const db = await getDatabase(projectPath);
-
-  // Get all agents
-  const agentsResult = await db.query<{
-    name: string;
-    program: string;
-    model: string;
-    task_description: string | null;
-  }>(
-    `SELECT name, program, model, task_description FROM agents WHERE project_key = $1`,
-    [projectPath],
-  );
-
-  // Get all messages
-  const messagesResult = await db.query<{
-    id: number;
-    from_agent: string;
-    subject: string;
-    thread_id: string | null;
-  }>(
-    `SELECT id, from_agent, subject, thread_id FROM messages WHERE project_key = $1`,
-    [projectPath],
-  );
-
-  // Get active reservations
-  const reservationsResult = await db.query<{
-    id: number;
-    agent_name: string;
-    path_pattern: string;
-  }>(
-    `SELECT id, agent_name, path_pattern FROM reservations 
-     WHERE project_key = $1 AND released_at IS NULL AND expires_at > $2`,
-    [projectPath, Date.now()],
-  );
-
-  // Get stats
-  const stats = await getDatabaseStats(projectPath);
-  const latestSequence = await getLatestSequence(projectPath, projectPath);
-
-  const result: InspectStateResult = {
-    agents: agentsResult.rows,
-    messages: messagesResult.rows,
-    reservations: reservationsResult.rows,
-    eventCount: stats.events,
-    latestSequence,
-    stats,
-  };
-
-  if (format === "json") {
-    result.json = JSON.stringify(result, null, 2);
-  }
-
-  return result;
-}