@metabob/minibob 0.1.2

package/src/composition-observer.ts

@@ -0,0 +1,449 @@
+/**
+ * Composition Observer - Track and visualize activity composition
+ *
+ * Provides real-time observation of which activities call which,
+ * detects cycles, tracks performance, and generates reports.
+ */
+
+import type { ExecutorConfig } from './activity'
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface CompositionEvent {
+  timestamp: number
+  parent: string
+  child: string
+  depth: number
+  reason?: string
+  status?: 'started' | 'completed' | 'failed' | 'blocked'
+  duration?: number
+  error?: string
+}
+
+export interface ActivityMetrics {
+  activityId: string
+  calls: number
+  successes: number
+  failures: number
+  blocked: number
+  totalDuration: number
+  avgDuration: number
+  successRate: number
+}
+
+export interface CompositionGraph {
+  nodes: Map<string, { calls: number; depths: Set<number> }>
+  edges: Map<string, { count: number; successes: number }>
+}
+
+// ============================================================================
+// COMPOSITION OBSERVER
+// ============================================================================
+
+export class CompositionObserver {
+  private events: CompositionEvent[] = []
+  private callStack: string[] = []
+  private activityMetrics = new Map<string, {
+    calls: number
+    successes: number
+    failures: number
+    blocked: number
+    totalDuration: number
+  }>()
+  private startTimes = new Map<string, number>()
+  private onEventCallback?: (event: CompositionEvent) => void
+
+  /**
+   * Create enhanced executor config with composition tracking
+   */
+  wrapConfig(config: ExecutorConfig): ExecutorConfig {
+    const originalOnActivityExecute = config.onActivityExecute
+
+    return {
+      ...config,
+      onActivityExecute: async (templateId, variables, reason) => {
+        const parent = this.callStack[this.callStack.length - 1] || 'ROOT'
+        const depth = this.callStack.length
+        const eventId = `${templateId}_${Date.now()}`
+
+        // Record start event
+        const startEvent: CompositionEvent = {
+          timestamp: Date.now(),
+          parent,
+          child: templateId,
+          depth,
+          reason,
+          status: 'started'
+        }
+        this.recordEvent(startEvent)
+
+        // Initialize metrics
+        if (!this.activityMetrics.has(templateId)) {
+          this.activityMetrics.set(templateId, {
+            calls: 0,
+            successes: 0,
+            failures: 0,
+            blocked: 0,
+            totalDuration: 0
+          })
+        }
+
+        const metrics = this.activityMetrics.get(templateId)!
+        metrics.calls++
+
+        // Track start time
+        this.startTimes.set(eventId, Date.now())
+
+        // Check for cycle (before calling original handler)
+        const callStack = (config.activityCallStack ?? [])
+        if (callStack.includes(templateId)) {
+          const cycleChain = [...callStack, templateId].join(' → ')
+
+          const blockedEvent: CompositionEvent = {
+            timestamp: Date.now(),
+            parent,
+            child: templateId,
+            depth,
+            reason,
+            status: 'blocked',
+            error: `Cycle detected: ${cycleChain}`
+          }
+          this.recordEvent(blockedEvent)
+          metrics.blocked++
+
+          // Return blocked response
+          return {
+            id: `blocked_cycle_${Date.now()}`,
+            templateId,
+            status: "failed" as const,
+            error: `Cycle detected: ${cycleChain}`,
+          }
+        }
+
+        // Update call stack
+        this.callStack.push(templateId)
+
+        try {
+          // Call original handler or default implementation
+          const result = originalOnActivityExecute
+            ? await originalOnActivityExecute(templateId, variables, reason)
+            : { id: `result_${Date.now()}`, templateId, status: 'completed' as const }
+
+          // Calculate duration
+          const startTime = this.startTimes.get(eventId)
+          const duration = startTime ? Date.now() - startTime : 0
+          this.startTimes.delete(eventId)
+
+          // Update metrics
+          metrics.totalDuration += duration
+          if (result.status === 'completed') {
+            metrics.successes++
+          } else {
+            metrics.failures++
+          }
+
+          // Record completion event
+          const completeEvent: CompositionEvent = {
+            timestamp: Date.now(),
+            parent,
+            child: templateId,
+            depth,
+            reason,
+            status: result.status === 'completed' ? 'completed' : 'failed',
+            duration,
+            error: result.status === 'failed' ? result.error : undefined
+          }
+          this.recordEvent(completeEvent)
+
+          return result
+        } catch (error) {
+          // Calculate duration
+          const startTime = this.startTimes.get(eventId)
+          const duration = startTime ? Date.now() - startTime : 0
+          this.startTimes.delete(eventId)
+
+          // Update metrics
+          metrics.totalDuration += duration
+          metrics.failures++
+
+          // Record failure event
+          const failureEvent: CompositionEvent = {
+            timestamp: Date.now(),
+            parent,
+            child: templateId,
+            depth,
+            reason,
+            status: 'failed',
+            duration,
+            error: error instanceof Error ? error.message : String(error)
+          }
+          this.recordEvent(failureEvent)
+
+          throw error
+        } finally {
+          // Pop call stack
+          this.callStack.pop()
+        }
+      }
+    }
+  }
+
+  /**
+   * Register callback for real-time event notifications
+   */
+  onEvent(callback: (event: CompositionEvent) => void): void {
+    this.onEventCallback = callback
+  }
+
+  /**
+   * Record composition event
+   */
+  private recordEvent(event: CompositionEvent): void {
+    this.events.push(event)
+    if (this.onEventCallback) {
+      this.onEventCallback(event)
+    }
+  }
+
+  /**
+   * Get all recorded events
+   */
+  getEvents(): CompositionEvent[] {
+    return [...this.events]
+  }
+
+  /**
+   * Get current call stack
+   */
+  getCurrentCallStack(): string[] {
+    return [...this.callStack]
+  }
+
+  /**
+   * Get activity metrics
+   */
+  getActivityMetrics(): ActivityMetrics[] {
+    return Array.from(this.activityMetrics.entries()).map(([activityId, metrics]) => ({
+      activityId,
+      calls: metrics.calls,
+      successes: metrics.successes,
+      failures: metrics.failures,
+      blocked: metrics.blocked,
+      totalDuration: metrics.totalDuration,
+      avgDuration: metrics.calls > 0 ? Math.round(metrics.totalDuration / metrics.calls) : 0,
+      successRate: metrics.calls > 0 ? metrics.successes / metrics.calls : 0
+    })).sort((a, b) => b.calls - a.calls)
+  }
+
+  /**
+   * Build composition graph
+   */
+  getCompositionGraph(): CompositionGraph {
+    const nodes = new Map<string, { calls: number; depths: Set<number> }>()
+    const edges = new Map<string, { count: number; successes: number }>()
+
+    for (const event of this.events) {
+      if (event.status !== 'started') continue
+
+      // Track nodes
+      if (!nodes.has(event.child)) {
+        nodes.set(event.child, { calls: 0, depths: new Set() })
+      }
+      const node = nodes.get(event.child)!
+      node.calls++
+      node.depths.add(event.depth)
+
+      // Track edges
+      const edgeKey = `${event.parent} → ${event.child}`
+      if (!edges.has(edgeKey)) {
+        edges.set(edgeKey, { count: 0, successes: 0 })
+      }
+      const edge = edges.get(edgeKey)!
+      edge.count++
+
+      // Find corresponding completion event
+      const completionEvent = this.events.find(e =>
+        e.child === event.child &&
+        e.timestamp > event.timestamp &&
+        e.status === 'completed'
+      )
+      if (completionEvent) {
+        edge.successes++
+      }
+    }
+
+    return { nodes, edges }
+  }
+
+  /**
+   * Detect cycles in recorded events
+   */
+  detectCycles(): Array<{ cycle: string[]; occurrences: number }> {
+    const cycles = new Map<string, number>()
+
+    for (const event of this.events) {
+      if (event.status === 'blocked' && event.error?.includes('Cycle detected:')) {
+        const match = event.error.match(/Cycle detected: (.+)/)
+        if (match) {
+          const cycle = match[1].split(' → ')
+          const key = cycle.join('→')
+          cycles.set(key, (cycles.get(key) ?? 0) + 1)
+        }
+      }
+    }
+
+    return Array.from(cycles.entries())
+      .map(([cycle, occurrences]) => ({
+        cycle: cycle.split('→'),
+        occurrences
+      }))
+      .sort((a, b) => b.occurrences - a.occurrences)
+  }
+
+  /**
+   * Generate text report
+   */
+  generateReport(): string {
+    const lines: string[] = []
+
+    lines.push('═'.repeat(80))
+    lines.push('📊 COMPOSITION REPORT')
+    lines.push('═'.repeat(80))
+
+    // Summary
+    lines.push('')
+    lines.push('SUMMARY:')
+    lines.push(`  Total Events: ${this.events.length}`)
+    lines.push(`  Total Activities: ${this.activityMetrics.size}`)
+
+    const totalCalls = Array.from(this.activityMetrics.values()).reduce((sum, m) => sum + m.calls, 0)
+    const totalSuccesses = Array.from(this.activityMetrics.values()).reduce((sum, m) => sum + m.successes, 0)
+    const totalFailures = Array.from(this.activityMetrics.values()).reduce((sum, m) => sum + m.failures, 0)
+    const totalBlocked = Array.from(this.activityMetrics.values()).reduce((sum, m) => sum + m.blocked, 0)
+
+    lines.push(`  Total Calls: ${totalCalls}`)
+    lines.push(`  Successes: ${totalSuccesses} (${((totalSuccesses / totalCalls) * 100).toFixed(0)}%)`)
+    lines.push(`  Failures: ${totalFailures} (${((totalFailures / totalCalls) * 100).toFixed(0)}%)`)
+    lines.push(`  Blocked: ${totalBlocked} (${((totalBlocked / totalCalls) * 100).toFixed(0)}%)`)
+
+    // Activity Metrics
+    lines.push('')
+    lines.push('─'.repeat(80))
+    lines.push('ACTIVITY METRICS:')
+    lines.push('─'.repeat(80))
+
+    for (const metrics of this.getActivityMetrics()) {
+      lines.push('')
+      lines.push(`${metrics.activityId}:`)
+      lines.push(`  Calls: ${metrics.calls}`)
+      lines.push(`  Successes: ${metrics.successes} (${(metrics.successRate * 100).toFixed(0)}%)`)
+      lines.push(`  Failures: ${metrics.failures}`)
+      if (metrics.blocked > 0) {
+        lines.push(`  Blocked: ${metrics.blocked}`)
+      }
+      lines.push(`  Avg Duration: ${metrics.avgDuration}ms`)
+      lines.push(`  Total Duration: ${metrics.totalDuration}ms`)
+    }
+
+    // Composition Graph
+    lines.push('')
+    lines.push('─'.repeat(80))
+    lines.push('COMPOSITION GRAPH:')
+    lines.push('─'.repeat(80))
+
+    const graph = this.getCompositionGraph()
+
+    lines.push('')
+    lines.push('Nodes (Activities):')
+    for (const [activity, data] of graph.nodes.entries()) {
+      lines.push(`  ${activity}`)
+      lines.push(`    Calls: ${data.calls}`)
+      lines.push(`    Depths: ${Array.from(data.depths).sort((a, b) => a - b).join(', ')}`)
+    }
+
+    lines.push('')
+    lines.push('Edges (Compositions):')
+    for (const [edge, data] of graph.edges.entries()) {
+      const successRate = data.count > 0 ? (data.successes / data.count * 100).toFixed(0) : '0'
+      lines.push(`  ${edge}`)
+      lines.push(`    Count: ${data.count}`)
+      lines.push(`    Success Rate: ${successRate}%`)
+    }
+
+    // Cycles
+    const cycles = this.detectCycles()
+    if (cycles.length > 0) {
+      lines.push('')
+      lines.push('─'.repeat(80))
+      lines.push('⚠️  CYCLES DETECTED:')
+      lines.push('─'.repeat(80))
+
+      for (const { cycle, occurrences } of cycles) {
+        lines.push(`  ${cycle.join(' → ')} (${occurrences}x)`)
+      }
+    }
+
+    lines.push('')
+    lines.push('═'.repeat(80))
+
+    return lines.join('\n')
+  }
+
+  /**
+   * Generate ASCII tree visualization
+   */
+  generateTree(): string {
+    const lines: string[] = []
+
+    // Group events by parent
+    const tree = new Map<string, string[]>()
+    for (const event of this.events) {
+      if (event.status === 'started') {
+        if (!tree.has(event.parent)) {
+          tree.set(event.parent, [])
+        }
+        tree.get(event.parent)!.push(event.child)
+      }
+    }
+
+    // Build tree starting from ROOT
+    const buildBranch = (node: string, prefix: string, isLast: boolean): void => {
+      const marker = isLast ? '└─' : '├─'
+      lines.push(`${prefix}${marker} ${node}`)
+
+      const children = tree.get(node) ?? []
+      const newPrefix = prefix + (isLast ? '  ' : '│ ')
+
+      children.forEach((child, index) => {
+        buildBranch(child, newPrefix, index === children.length - 1)
+      })
+    }
+
+    lines.push('ROOT')
+    const rootChildren = tree.get('ROOT') ?? []
+    rootChildren.forEach((child, index) => {
+      buildBranch(child, '', index === rootChildren.length - 1)
+    })
+
+    return lines.join('\n')
+  }
+
+  /**
+   * Clear all recorded data
+   */
+  clear(): void {
+    this.events = []
+    this.callStack = []
+    this.activityMetrics.clear()
+    this.startTimes.clear()
+  }
+}
+
+/**
+ * Create a new composition observer
+ */
+export function createCompositionObserver(): CompositionObserver {
+  return new CompositionObserver()
+}

package/src/config.ts

@@ -0,0 +1,172 @@
+/**
+ * minibob Configuration
+ * 
+ * Loads configuration from environment variables and optional config file.
+ */
+
+import type { MinibobConfig, VesselManifest } from "./types"
+import type { RuntimeEnvironment } from "./environment"
+
+// =============================================================================
+// DEFAULT CONFIGURATION
+// =============================================================================
+
+const defaultConfig: MinibobConfig = {
+  port: 8080,
+  host: "0.0.0.0",
+  provider: "anthropic",
+  model: "claude-sonnet-4-20250514",
+  apiKey: "",
+  vessels: {
+    metabob: {
+      type: "http",
+      endpoint: process.env.MINIBOB_MCP_ENDPOINT || "http://api.minibob.local",
+      capabilities: ["activities", "impulses", "executions", "thompson-sampling"],
+    },
+  },
+  templatesDir: "./templates",
+  workingDirectory: process.cwd(),
+  autoCommit: false,
+}
+
+// =============================================================================
+// CONFIGURATION LOADING
+// =============================================================================
+
+/**
+ * Safe wrapper for Bun.file() with better error handling
+ */
+function safeReadFile(path: string): ReturnType<typeof Bun.file> {
+  if (!path || typeof path !== 'string') {
+    throw new Error(`Invalid file path: expected string, got ${typeof path}`)
+  }
+  try {
+    return Bun.file(path)
+  } catch (error) {
+    throw new Error(`Failed to create file handle for '${path}': ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/**
+ * Load configuration from environment and optional file
+ */
+export async function loadConfig(configPath?: string): Promise<MinibobConfig> {
+  let fileConfig: Partial<MinibobConfig> = {}
+
+  // Try to load config file
+  if (configPath) {
+    const file = safeReadFile(configPath)
+    if (await file.exists()) {
+      fileConfig = await file.json()
+    }
+  } else {
+    // Try default locations
+    for (const path of ["minibob.json", ".minibob.json", "opencode.json"]) {
+      const file = safeReadFile(path)
+      if (await file.exists()) {
+        fileConfig = await file.json()
+        break
+      }
+    }
+  }
+
+  // Merge with environment variables
+  const config: MinibobConfig = {
+    ...defaultConfig,
+    ...fileConfig,
+    port: parseInt(process.env.MINIBOB_PORT ?? String(fileConfig.port ?? defaultConfig.port)),
+    host: process.env.MINIBOB_HOST ?? fileConfig.host ?? defaultConfig.host,
+    provider: (process.env.MINIBOB_PROVIDER ?? fileConfig.provider ?? defaultConfig.provider) as "anthropic" | "openai",
+    model: process.env.MINIBOB_MODEL ?? fileConfig.model ?? defaultConfig.model,
+    apiKey: process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? fileConfig.apiKey ?? "",
+    workingDirectory: process.env.MINIBOB_WORKDIR ?? fileConfig.workingDirectory ?? process.cwd(),
+    templatesDir: process.env.MINIBOB_TEMPLATES ?? fileConfig.templatesDir ?? defaultConfig.templatesDir,
+    autoCommit: process.env.MINIBOB_AUTO_COMMIT === "true" || fileConfig.autoCommit || false,
+  }
+
+  // Validate required fields
+  if (!config.apiKey) {
+    console.warn("Warning: No API key configured. Set ANTHROPIC_API_KEY or OPENAI_API_KEY.")
+  }
+
+  return config
+}
+
+// =============================================================================
+// VESSEL MANIFEST
+// =============================================================================
+
+/**
+ * Runtime context for dynamic manifest generation
+ */
+export interface RuntimeContext {
+  environment: RuntimeEnvironment
+  clusterMode: boolean
+  peerCount: number
+  boredomEnabled: boolean
+  acpGossipEnabled: boolean
+  backendAvailable: boolean
+}
+
+/**
+ * Generate vessel manifest with dynamic capabilities based on runtime context
+ * 
+ * Capabilities are determined by detected environment:
+ * - Base: activities, impulses, git (always enabled)
+ * - acp-gossip: Only in cluster mode (3+ pods)
+ * - boredom: Only in cluster mode with backend available
+ */
+export function generateManifest(config: MinibobConfig, runtime?: RuntimeContext): VesselManifest {
+  const capabilities = ["activities", "impulses", "git"]
+  
+  // Add dynamic capabilities based on runtime context
+  if (runtime?.acpGossipEnabled) {
+    capabilities.push("acp-gossip")
+  }
+  if (runtime?.boredomEnabled) {
+    capabilities.push("boredom")
+  }
+  
+  // Always expose basic ACP endpoint for delegation
+  capabilities.push("acp")
+  
+  return {
+    id: "minibob",
+    name: "minibob - Minimal Vessel",
+    version: "0.1.0",
+    capabilities,
+    tools: [
+      "bash",
+      "read",
+      "write",
+      "edit",
+      "glob",
+      "grep",
+      "list",
+      "git",
+    ],
+    acpEndpoint: `http://${config.host}:${config.port}/acp`,
+    metadata: runtime ? {
+      environment: runtime.environment,
+      clusterMode: runtime.clusterMode,
+      peerCount: runtime.peerCount,
+      backendAvailable: runtime.backendAvailable,
+    } : undefined
+  }
+}
+
+/**
+ * Get configuration summary for logging
+ */
+export function configSummary(config: MinibobConfig): string {
+  return `
+minibob Configuration:
+  Port: ${config.port}
+  Provider: ${config.provider}
+  Model: ${config.model}
+  Working Directory: ${config.workingDirectory}
+  Templates: ${config.templatesDir}
+  Auto-Commit: ${config.autoCommit}
+  API Key: ${config.apiKey ? "***" + config.apiKey.slice(-4) : "(not set)"}
+`.trim()
+}