@metabob/minibob 0.1.2

package/src/cli/observe.ts

@@ -0,0 +1,682 @@
+/**
+ * Observe Command
+ *
+ * Observe running instances OR codebases to extract/validate activities.
+ *
+ * Two modes:
+ * 1. Instance mode (default): View execution state of running minibob instances
+ * 2. Codebase mode (--codebase): Observe a codebase to extract activities
+ *
+ * The codebase mode extracts the instructional→functional mappings:
+ * - Developer Intent → Written Code (activities inferred from functions)
+ * - Written Code → Runtime (traced via execution)
+ *
+ * Discovery mechanisms for instance mode:
+ * 1. Explicit targets (--target flag)
+ * 2. Local registry (~/.minibob/instances.json)
+ * 3. Port scanning (--scan flag)
+ * 4. Backend query (--backend flag) - centralized view from metabob-activity-api
+ */
+
+import { parseArgs, formatHelp, printInfo, printWarning, printSuccess } from './index'
+import {
+  listInstances,
+  scanForInstances,
+  fetchInstanceStatus,
+  cleanupStaleInstances,
+  type MinibobInstance,
+  type InstanceStatus,
+} from './instance-registry'
+import {
+  analyzeCodebase,
+  mapTraceToSource,
+  inferIntent,
+  type CodebaseAnalysis,
+} from '../runtime-mapping'
+
+export interface ObserveOptions {
+  target?: string
+  codebase?: string
+  list?: boolean
+  follow?: boolean
+  scan?: boolean
+  backend?: boolean
+  json?: boolean
+  interval?: number
+  validate?: boolean
+}
+
+/**
+ * Run observe command
+ */
+export async function observe(args: string[]): Promise<void> {
+  const { flags, values, positional } = parseArgs(args)
+
+  // Show help
+  if (flags.help || flags.h) {
+    console.log(formatHelp('observe', 'Observe instances or codebases', [
+      { flag: '--codebase <path>', description: 'Observe a codebase to extract activities' },
+      { flag: '--validate', description: 'Validate observed activities against execution traces' },
+      { flag: '--target <url>', description: 'Connect to specific instance (e.g., http://localhost:8080)' },
+      { flag: '--list', description: 'List instances from registry (default)' },
+      { flag: '--follow', description: 'Continuously monitor (refresh every 2s)' },
+      { flag: '--scan', description: 'Scan localhost ports 8080-8090 for instances' },
+      { flag: '--backend', description: 'Query backend for all registered vessels' },
+      { flag: '--json', description: 'Output as JSON' },
+      { flag: '--help, -h', description: 'Show this help message' },
+    ]))
+    return
+  }
+
+  const options: ObserveOptions = {
+    target: values.target,
+    codebase: values.codebase || positional[0], // Allow positional arg for codebase
+    list: flags.list,
+    follow: flags.follow || flags.f,
+    scan: flags.scan,
+    backend: flags.backend || flags.b,
+    json: flags.json,
+    interval: values.interval ? parseInt(values.interval) : 2000,
+    validate: flags.validate,
+  }
+
+  // If codebase specified, observe the codebase
+  if (options.codebase) {
+    await observeCodebase(options.codebase, options)
+    return
+  }
+
+  // If target specified, observe that instance
+  if (options.target) {
+    await observeTarget(options.target, options)
+    return
+  }
+
+  // If backend query requested
+  if (options.backend) {
+    await queryBackend(options)
+    return
+  }
+
+  // If scan requested, scan for instances
+  if (options.scan) {
+    await scanAndObserve(options)
+    return
+  }
+
+  // Default: list from registry
+  await listAndObserve(options)
+}
+
+/**
+ * Observe a codebase to extract activities (instructional→functional mappings)
+ *
+ * Activities ARE the mappings:
+ * - Developer Intent → Written Code (what functions do)
+ * - Written Code → Runtime (execution behavior)
+ */
+async function observeCodebase(path: string, options: ObserveOptions): Promise<void> {
+  const { existsSync } = await import('fs')
+  const { resolve } = await import('path')
+
+  const fullPath = resolve(path)
+
+  if (!existsSync(fullPath)) {
+    printWarning(`Path not found: ${fullPath}`)
+    return
+  }
+
+  printInfo(`Observing codebase: ${fullPath}`)
+  console.log('')
+
+  // Use existing analyzeCodebase from runtime-mapping.ts
+  const analysis = await analyzeCodebase(fullPath)
+
+  if (options.json) {
+    console.log(JSON.stringify(analysis, null, 2))
+    return
+  }
+
+  // Display as activities (the instructional→functional mappings)
+  console.log('┌─ Observed Activities (Intent → Code Mappings) ──────────────┐\n')
+
+  console.log(`  Entry Points: ${analysis.entryPoints.length}`)
+  for (const entry of analysis.entryPoints) {
+    console.log(`    • ${entry}`)
+  }
+  console.log('')
+
+  console.log(`  Functions: ${analysis.functions.length}`)
+  console.log(`  Classes: ${analysis.classes.length}`)
+  console.log(`  Modules: ${analysis.modules.length}`)
+  console.log('')
+
+  // Show functions as activities (each function is an intent→code mapping)
+  const activitiesFound: Array<{ name: string; intent: string; confidence: number; file: string }> = []
+
+  for (const func of analysis.functions) {
+    const intent = inferIntent(func, analysis.classes, analysis.documentation)
+    activitiesFound.push({
+      name: func.name,
+      intent: intent.purpose,
+      confidence: intent.confidence,
+      file: func.file,
+    })
+  }
+
+  // Sort by confidence
+  activitiesFound.sort((a, b) => b.confidence - a.confidence)
+
+  // Show top activities
+  const topActivities = activitiesFound.slice(0, 20)
+  console.log(`  Top Activities by Confidence:\n`)
+
+  for (const activity of topActivities) {
+    const confidenceBar = '█'.repeat(Math.round(activity.confidence * 10))
+    const spaces = ' '.repeat(10 - Math.round(activity.confidence * 10))
+    console.log(`    ${activity.name}`)
+    console.log(`      Intent: "${activity.intent}"`)
+    console.log(`      Confidence: [${confidenceBar}${spaces}] ${(activity.confidence * 100).toFixed(0)}%`)
+    console.log(`      File: ${activity.file}`)
+    console.log('')
+  }
+
+  if (activitiesFound.length > 20) {
+    console.log(`    ... and ${activitiesFound.length - 20} more activities`)
+    console.log('')
+  }
+
+  console.log('└─────────────────────────────────────────────────────────────┘\n')
+
+  // If validate flag, compare with execution traces
+  if (options.validate) {
+    await validateObservation(analysis, options)
+  }
+
+  printSuccess(`Observed ${activitiesFound.length} activities in codebase`)
+  printInfo('Use --validate to compare against execution traces')
+  printInfo('Use --json for machine-readable output')
+}
+
+/**
+ * Validate observed activities against actual execution traces
+ */
+async function validateObservation(analysis: CodebaseAnalysis, options: ObserveOptions): Promise<void> {
+  const backendUrl = process.env.MINIBOB_MCP_ENDPOINT || 'http://api.minibob.local'
+
+  printInfo(`\nValidating against execution traces from: ${backendUrl}`)
+
+  try {
+    // Fetch recent execution traces
+    const response = await fetch(`${backendUrl}/v2/activities/execution-traces?limit=100`, {
+      signal: AbortSignal.timeout(10000),
+    })
+
+    if (!response.ok) {
+      printWarning(`Could not fetch execution traces: ${response.status}`)
+      return
+    }
+
+    const data = await response.json() as { executions?: Array<{ tool_calls?: string[] }> }
+    const traces = data.executions || []
+
+    console.log(`\n┌─ Validation: Observed vs Executed ─────────────────────────┐\n`)
+    console.log(`  Execution traces found: ${traces.length}`)
+
+    // Extract function names from traces
+    const executedFunctions = new Set<string>()
+    for (const trace of traces) {
+      // Tool calls contain function names
+      if (trace.tool_calls) {
+        for (const call of trace.tool_calls) {
+          executedFunctions.add(call)
+        }
+      }
+    }
+
+    // Compare observed functions to executed
+    const observedNames = new Set(analysis.functions.map(f => f.name))
+
+    const matched = [...observedNames].filter(n => executedFunctions.has(n))
+    const observedOnly = [...observedNames].filter(n => !executedFunctions.has(n))
+    const executedOnly = [...executedFunctions].filter(n => !observedNames.has(n))
+
+    console.log(`\n  Matched (observed AND executed): ${matched.length}`)
+    for (const name of matched.slice(0, 10)) {
+      console.log(`    ✓ ${name}`)
+    }
+    if (matched.length > 10) {
+      console.log(`    ... and ${matched.length - 10} more`)
+    }
+
+    console.log(`\n  Observed only (not yet executed): ${observedOnly.length}`)
+    for (const name of observedOnly.slice(0, 5)) {
+      console.log(`    ○ ${name}`)
+    }
+    if (observedOnly.length > 5) {
+      console.log(`    ... and ${observedOnly.length - 5} more`)
+    }
+
+    console.log(`\n  Executed only (not in observation): ${executedOnly.length}`)
+    for (const name of executedOnly.slice(0, 5)) {
+      console.log(`    ? ${name}`)
+    }
+    if (executedOnly.length > 5) {
+      console.log(`    ... and ${executedOnly.length - 5} more`)
+    }
+
+    // Calculate coverage
+    const coverage = matched.length / (observedNames.size || 1)
+    console.log(`\n  Coverage: ${(coverage * 100).toFixed(1)}% of observed activities have been executed`)
+
+    console.log('\n└─────────────────────────────────────────────────────────────┘\n')
+
+  } catch (error) {
+    printWarning(`Validation failed: ${error instanceof Error ? error.message : String(error)}`)
+    printInfo('Is the backend running? Start minibob and execute some activities first.')
+  }
+}
+
+/**
+ * Observe a specific target instance
+ */
+async function observeTarget(target: string, options: ObserveOptions): Promise<void> {
+  // Normalize target URL
+  let url = target
+  if (!url.startsWith('http://') && !url.startsWith('https://')) {
+    url = `http://${url}`
+  }
+
+  // Extract host and port
+  const urlObj = new URL(url)
+  const instance: MinibobInstance = {
+    id: `target-${urlObj.port}`,
+    host: urlObj.hostname,
+    port: parseInt(urlObj.port) || 8080,
+    startTime: Date.now(),
+    workingDirectory: '(unknown)',
+    status: 'unknown',
+  }
+
+  if (options.follow) {
+    await followInstance(instance, options)
+  } else {
+    await displayInstanceStatus(instance, options)
+  }
+}
+
+/**
+ * Scan for instances and observe
+ */
+async function scanAndObserve(options: ObserveOptions): Promise<void> {
+  printInfo('Scanning localhost ports 8080-8090 for minibob instances...')
+
+  const instances = await scanForInstances()
+
+  if (instances.length === 0) {
+    printWarning('No minibob instances found')
+    return
+  }
+
+  printInfo(`Found ${instances.length} instance(s)`)
+
+  if (options.follow) {
+    await followInstances(instances, options)
+  } else {
+    await displayInstances(instances, options)
+  }
+}
+
+/**
+ * List instances from registry and observe
+ */
+async function listAndObserve(options: ObserveOptions): Promise<void> {
+  // Clean up stale instances first
+  const cleaned = await cleanupStaleInstances()
+  if (cleaned > 0) {
+    printInfo(`Cleaned up ${cleaned} stale instance(s)`)
+  }
+
+  const instances = await listInstances()
+
+  if (instances.length === 0) {
+    printWarning('No instances registered')
+    printInfo('Use --scan to search for running instances')
+    printInfo('Use --backend to query the centralized backend')
+    printInfo('Or start a minibob server: minibob')
+    return
+  }
+
+  if (options.follow) {
+    await followInstances(instances, options)
+  } else {
+    await displayInstances(instances, options)
+  }
+}
+
+/**
+ * Backend vessel status from metabob-activity-api
+ */
+interface BackendVesselStatus {
+  pod_name: string
+  namespace: string
+  status: 'idle' | 'executing' | 'bored' | 'error' | 'unknown'
+  current_activity?: {
+    variant_id: string
+    activity_id: string
+    variant_name: string
+    started_at: string
+    current_task?: string
+    progress?: number
+  }
+  metrics?: {
+    executions_completed: number
+    total_cost_usd: number
+    uptime_seconds: number
+  }
+  last_heartbeat: string
+  ready: boolean
+  phase: string
+}
+
+/**
+ * Query backend for all registered vessels
+ */
+async function queryBackend(options: ObserveOptions): Promise<void> {
+  const backendUrl = process.env.MINIBOB_MCP_ENDPOINT || 'http://api.minibob.local'
+
+  printInfo(`Querying backend: ${backendUrl}/v2/vessels/status`)
+
+  try {
+    const response = await fetch(`${backendUrl}/v2/vessels/status`, {
+      signal: AbortSignal.timeout(10000),
+    })
+
+    if (!response.ok) {
+      printWarning(`Backend returned ${response.status}`)
+      return
+    }
+
+    const data = (await response.json()) as { vessels: BackendVesselStatus[]; total: number }
+
+    if (options.json) {
+      console.log(JSON.stringify(data, null, 2))
+      return
+    }
+
+    if (!data.vessels || data.vessels.length === 0) {
+      printWarning('No vessels reporting to backend')
+      printInfo('Vessels send heartbeats every 30 seconds')
+      printInfo('Start a minibob server and wait for heartbeat')
+      return
+    }
+
+    console.log(`\n┌─ Backend Vessel Status (${data.total} vessel(s)) ─────────────────┐\n`)
+
+    for (const vessel of data.vessels) {
+      printBackendVesselInfo(vessel)
+      console.log('')
+    }
+
+    console.log('└─────────────────────────────────────────────────────────────┘\n')
+
+    // Follow mode for backend
+    if (options.follow) {
+      await followBackend(backendUrl, options)
+    }
+  } catch (error) {
+    printWarning(`Could not reach backend: ${error instanceof Error ? error.message : String(error)}`)
+    printInfo('Is the backend running? Check: curl http://api.minibob.local/health')
+  }
+}
+
+/**
+ * Follow backend status
+ */
+async function followBackend(backendUrl: string, options: ObserveOptions): Promise<void> {
+  console.log('Watching backend (Ctrl+C to stop)...\n')
+
+  const updateDisplay = async () => {
+    console.clear()
+    console.log('┌─ Backend Vessel Status (live) ─────────────────────────────┐\n')
+
+    try {
+      const response = await fetch(`${backendUrl}/v2/vessels/status`, {
+        signal: AbortSignal.timeout(5000),
+      })
+
+      if (response.ok) {
+        const data = (await response.json()) as { vessels: BackendVesselStatus[] }
+
+        if (data.vessels && data.vessels.length > 0) {
+          for (const vessel of data.vessels) {
+            printBackendVesselInfo(vessel)
+            console.log('')
+          }
+        } else {
+          console.log('  No vessels reporting')
+        }
+      } else {
+        console.log(`  Backend error: ${response.status}`)
+      }
+    } catch {
+      console.log('  Backend unreachable')
+    }
+
+    console.log(`Last updated: ${new Date().toLocaleTimeString()}`)
+    console.log('└─────────────────────────────────────────────────────────────┘')
+  }
+
+  await updateDisplay()
+  const interval = setInterval(updateDisplay, options.interval)
+
+  process.on('SIGINT', () => {
+    clearInterval(interval)
+    console.log('\n\nStopped watching.')
+    process.exit(0)
+  })
+
+  await new Promise(() => {})
+}
+
+/**
+ * Print backend vessel info
+ */
+function printBackendVesselInfo(vessel: BackendVesselStatus): void {
+  const statusIcon = getStatusIcon(vessel.status)
+  const readyIcon = vessel.ready ? '●' : '○'
+
+  console.log(`${statusIcon} ${vessel.pod_name} ${readyIcon}`)
+  console.log(`  Namespace: ${vessel.namespace}`)
+  console.log(`  Status: ${vessel.status}`)
+  console.log(`  Last Heartbeat: ${new Date(vessel.last_heartbeat).toLocaleTimeString()}`)
+
+  if (vessel.current_activity) {
+    console.log(`  Current Activity: ${vessel.current_activity.variant_name}`)
+    if (vessel.current_activity.current_task) {
+      console.log(`    Task: ${vessel.current_activity.current_task}`)
+    }
+    if (vessel.current_activity.progress !== undefined) {
+      console.log(`    Progress: ${vessel.current_activity.progress}%`)
+    }
+  }
+
+  if (vessel.metrics) {
+    console.log(`  Executions: ${vessel.metrics.executions_completed}`)
+    console.log(`  Cost: $${vessel.metrics.total_cost_usd.toFixed(4)}`)
+    console.log(`  Uptime: ${formatUptime(vessel.metrics.uptime_seconds * 1000)}`)
+  }
+}
+
+/**
+ * Display status for multiple instances
+ */
+async function displayInstances(instances: MinibobInstance[], options: ObserveOptions): Promise<void> {
+  const statuses: Array<{ instance: MinibobInstance; status: InstanceStatus | null }> = []
+
+  for (const instance of instances) {
+    const status = await fetchInstanceStatus(instance)
+    statuses.push({ instance, status })
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(statuses, null, 2))
+    return
+  }
+
+  console.log('\n┌─ minibob instances ─────────────────────────────────────────┐\n')
+
+  for (const { instance, status } of statuses) {
+    printInstanceInfo(instance, status)
+    console.log('')
+  }
+
+  console.log('└─────────────────────────────────────────────────────────────┘\n')
+}
+
+/**
+ * Display status for a single instance
+ */
+async function displayInstanceStatus(instance: MinibobInstance, options: ObserveOptions): Promise<void> {
+  const status = await fetchInstanceStatus(instance)
+
+  if (options.json) {
+    console.log(JSON.stringify({ instance, status }, null, 2))
+    return
+  }
+
+  console.log('')
+  printInstanceInfo(instance, status)
+  console.log('')
+}
+
+/**
+ * Follow instances continuously
+ */
+async function followInstances(instances: MinibobInstance[], options: ObserveOptions): Promise<void> {
+  console.log('Watching instances (Ctrl+C to stop)...\n')
+
+  // Clear screen and show header
+  const clearScreen = () => {
+    console.clear()
+    console.log('┌─ minibob instances (live) ─────────────────────────────────┐\n')
+  }
+
+  const updateDisplay = async () => {
+    clearScreen()
+
+    for (const instance of instances) {
+      const status = await fetchInstanceStatus(instance)
+      printInstanceInfo(instance, status)
+      console.log('')
+    }
+
+    console.log(`Last updated: ${new Date().toLocaleTimeString()}`)
+    console.log('└─────────────────────────────────────────────────────────────┘')
+  }
+
+  // Initial display
+  await updateDisplay()
+
+  // Update periodically
+  const interval = setInterval(updateDisplay, options.interval)
+
+  // Handle Ctrl+C
+  process.on('SIGINT', () => {
+    clearInterval(interval)
+    console.log('\n\nStopped watching.')
+    process.exit(0)
+  })
+
+  // Keep process alive
+  await new Promise(() => {})
+}
+
+/**
+ * Follow a single instance
+ */
+async function followInstance(instance: MinibobInstance, options: ObserveOptions): Promise<void> {
+  await followInstances([instance], options)
+}
+
+/**
+ * Print instance info
+ */
+function printInstanceInfo(instance: MinibobInstance, status: InstanceStatus | null): void {
+  const statusIcon = status ? getStatusIcon(status.status) : '?'
+  const statusText = status?.status || 'unreachable'
+
+  console.log(`${statusIcon} ${instance.id}`)
+  console.log(`  URL: http://${instance.host}:${instance.port}`)
+  console.log(`  Status: ${statusText}`)
+
+  if (status) {
+    console.log(`  Working Dir: ${status.config.workingDirectory}`)
+    console.log(`  Model: ${status.config.model}`)
+    console.log(`  Uptime: ${formatUptime(status.metrics.uptime)}`)
+    console.log(`  Activities: ${status.metrics.activitiesExecuted}`)
+
+    if (status.currentActivity) {
+      console.log(`  Current: ${status.currentActivity.name || status.currentActivity.id}`)
+      if (status.currentActivity.task) {
+        console.log(`    Task: ${status.currentActivity.task}`)
+      }
+      if (status.currentActivity.progress !== undefined) {
+        console.log(`    Progress: ${Math.round(status.currentActivity.progress * 100)}%`)
+      }
+    }
+
+    if (status.metrics.totalCost !== undefined) {
+      console.log(`  Total Cost: $${status.metrics.totalCost.toFixed(4)}`)
+    }
+  } else {
+    console.log(`  PID: ${instance.pid || 'unknown'}`)
+    console.log(`  Started: ${new Date(instance.startTime).toLocaleTimeString()}`)
+  }
+}
+
+/**
+ * Get status icon
+ */
+function getStatusIcon(status: string): string {
+  switch (status) {
+    case 'idle':
+      return '💤'
+    case 'executing':
+      return '🔄'
+    case 'boredom':
+      return '🤖'
+    default:
+      return '❓'
+  }
+}
+
+/**
+ * Format uptime
+ */
+function formatUptime(ms: number): string {
+  const seconds = Math.floor(ms / 1000)
+  const minutes = Math.floor(seconds / 60)
+  const hours = Math.floor(minutes / 60)
+  const days = Math.floor(hours / 24)
+
+  if (days > 0) {
+    return `${days}d ${hours % 24}h`
+  }
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m`
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`
+  }
+  return `${seconds}s`
+}
+
+// CLI entry point
+if (import.meta.main) {
+  const args = process.argv.slice(2)
+  observe(args).catch((error) => {
+    console.error('Observe failed:', error)
+    process.exit(1)
+  })
+}