@metabob/minibob 0.1.2

package/index.ts

@@ -0,0 +1,1329 @@
+#!/usr/bin/env bun
+/**
+ * minibob - Minimal Vessel for the Process-of-Becoming
+ *
+ * Just describe what you want. MiniBob figures out how to do it.
+ *
+ * Primary usage:
+ *   minibob goal "Fix the login bug"
+ *   minibob goal "Add a logout button"
+ *   minibob goal "Optimize slow queries"
+ *
+ * MiniBob automatically:
+ *   1. Searches for proven solutions (existing templates)
+ *   2. Adapts to your context (impulse interpolation)
+ *   3. Recovers from failures (adaptive retry & trailblazing)
+ *   4. Improvises when needed (creative exploration)
+ *   5. Learns which approaches work (Thompson Sampling)
+ *
+ * Advanced usage:
+ *   minibob run <template>              # Execute specific template
+ *   minibob improvise <goal>            # Pure improvisation
+ *   minibob understand <path>           # Codebase exploration
+ *   minibob diagnose <problem>          # Problem diagnosis
+ *
+ * For local development:
+ *   bun run index.ts [command]          # Run from source
+ */
+
+import { loadConfig, generateManifest, configSummary, type RuntimeContext } from "./src/config"
+import { ActivityExecutor, loadTemplate, loadTemplateFromMCPOrLocal, type ExecutorConfig } from "./src/activity"
+import { handleACPRequest, type ACPServerConfig } from "./src/acp"
+import { initializeMCP, type MCPClient } from "./src/mcp"
+import { initializeBoredom, startBoredom, markBoredomActivity } from "./src/boredom"
+import { validateRunActivityRequest, validateRequestSize, ValidationException } from "./src/validation"
+import { MCPActivityBridge } from "./src/mcp-activity-bridge"
+import { ActivityCompositionService } from "./activity_composition_service"
+import { GoalProcessor } from "./src/goal-processor"
+import { SearchFirstExecutor } from "./src/search-first-executor"
+import { CodeExplorer, ApplicationAnalyzer } from "./src/understanding"
+
+// CLI command imports
+import { burrow } from "./src/cli/burrow"
+import { observe } from "./src/cli/observe"
+import { goal } from "./src/cli/goal"
+import { doctor } from "./src/cli/doctor"
+import { launchACPServer } from "./src/cli/acp-server"
+// Idealization is handled within vessel-bootstrap, not as a separate CLI command
+import { registerInstance, deregisterInstance, updateInstanceStatus, generateInstanceId } from "./src/cli/instance-registry"
+import { vessel as vesselCommand } from "./src/cli/vessel"
+
+// Vessel registry and runtime mapping
+import {
+  registerVessel,
+  registerVesselWithSync,
+  recordActivityExecution,
+  fetchVesselFromBackend,
+  getVessel,
+  getVesselByPath,
+  listVessels,
+  updateVesselActivities,
+  addVesselActivity,
+  updateVesselMapping,
+  recordVesselComposition,
+  deregisterVessel,
+  vesselRegistry,
+  type Vessel,
+  type VesselIdentity,
+  type VesselActivity,
+  type VesselImpulse,
+  type VesselHook,
+  type VesselTool,
+  type VesselComposition,
+  type RuntimeMapping,
+  type SourceLocation,
+  type InferredIntent,
+} from "./src/vessel-registry"
+
+import {
+  analyzeCodebase as analyzeCodebaseMapping,
+  mapTraceToSource,
+  inferIntent,
+  runtimeMapping,
+  type TraceToSourceMapping,
+  type CodebaseAnalysis,
+  type FunctionInfo,
+  type ClassInfo,
+  type ModuleInfo,
+  type DocumentationInfo,
+} from "./src/runtime-mapping"
+
+// Re-export for library usage
+export {
+  // Vessel registry
+  registerVessel,
+  getVessel,
+  getVesselByPath,
+  listVessels,
+  updateVesselActivities,
+  addVesselActivity,
+  updateVesselMapping,
+  recordVesselComposition,
+  deregisterVessel,
+  vesselRegistry,
+  // Runtime mapping
+  analyzeCodebaseMapping,
+  mapTraceToSource,
+  inferIntent,
+  runtimeMapping,
+  // CLI commands
+  burrow,
+  observe,
+  goal,
+  doctor,
+  launchACPServer,
+  vesselCommand,
+}
+
+// Re-export AgentRuntime for library usage
+export { AgentRuntime } from "./src/agent-runtime"
+
+// Re-export types
+export type {
+  Vessel,
+  VesselIdentity,
+  VesselActivity,
+  VesselImpulse,
+  VesselHook,
+  VesselTool,
+  VesselComposition,
+  RuntimeMapping,
+  SourceLocation,
+  InferredIntent,
+  TraceToSourceMapping,
+  CodebaseAnalysis,
+  FunctionInfo,
+  ClassInfo,
+  ModuleInfo,
+  DocumentationInfo,
+}
+
+// =============================================================================
+// CLI ARGUMENT PARSING
+// =============================================================================
+
+const args = process.argv.slice(2)
+const command = args[0]
+
+// =============================================================================
+// HELP COMMAND
+// =============================================================================
+
+if (command === "--help" || command === "-h") {
+  console.log(`
+minibob - Minimal Vessel for the Process-of-Becoming
+
+Just describe what you want. MiniBob figures out how to do it.
+
+USAGE:
+  minibob goal "<description>"    # Recommended: Describe what you want
+  minibob [command] [options]     # Advanced: Direct command access
+
+PRIMARY COMMAND:
+  goal <description>        Achieve a goal (recommended approach)
+                           MiniBob will:
+                           1. Try routine activities (learned patterns)
+                           2. Recover from issues (adaptive retry)
+                           3. Improvise solutions (creative exploration)
+
+                           Example: minibob goal "Fix the login bug"
+                           Example: minibob goal "Add a logout button"
+
+UTILITY COMMANDS:
+  doctor                    Health check and configuration
+  observe                   View running minibob instances
+  vessel <subcommand>       Manage vessel registry (list, info, remove)
+  burrow [path]             Inject minibob into a codebase
+  (no command)              Start the HTTP/ACP server
+  acp                       Launch standalone ACP server
+
+ADVANCED COMMANDS (Direct Execution):
+  run <template>            Execute a specific activity template
+                           Example: minibob run templates/fix-bug.json
+
+  improvise <goal>          Pure improvisation (no template search)
+                           Example: minibob improvise "Create HTTP server"
+
+  understand [path]         Explore and analyze codebase structure
+                           Example: minibob understand ./my-app
+
+  diagnose <problem>        Diagnose application problems
+                           Example: minibob diagnose "API returns 500"
+
+  --help                    Show this help message
+
+HOW MINIBOB WORKS:
+  When you use 'goal', MiniBob automatically:
+  • Searches for proven solutions (existing templates)
+  • Adapts to your specific context (impulse interpolation)
+  • Recovers from failures (trailblazing new variants)
+  • Creates new templates from successful improvisations
+  • Learns which approaches work best (Thompson Sampling)
+
+  You don't choose the method - MiniBob does. Just describe the goal.
+
+ENVIRONMENT VARIABLES:
+  ANTHROPIC_API_KEY     API key for Claude (required)
+  OPENAI_API_KEY        API key for OpenAI (if using OpenAI provider)
+  MINIBOB_MCP_ENDPOINT  Backend API endpoint (default: http://localhost:8080)
+  MINIBOB_PORT          Server port (default: 8080)
+  MINIBOB_HOST          Server host (default: 0.0.0.0)
+  MINIBOB_PROVIDER      LLM provider: anthropic or openai (default: anthropic)
+  MINIBOB_MODEL         Model to use (default: claude-sonnet-4-20250514)
+  MINIBOB_WORKDIR       Working directory (default: current directory)
+  MINIBOB_TEMPLATES     Templates directory (default: ./templates)
+  MINIBOB_AUTO_COMMIT   Auto-commit changes: true or false (default: false)
+
+QUICK START:
+  # Install
+  npm install -g @metabob/minibob
+
+  # Set API key
+  export ANTHROPIC_API_KEY="sk-ant-..."
+
+  # Achieve a goal
+  minibob goal "Add error handling to the API"
+
+  # That's it! MiniBob handles the rest.
+
+EXAMPLES:
+  # Goal-first (recommended)
+  minibob goal "Fix the broken test suite"
+  minibob goal "Add dark mode to the dashboard"
+  minibob goal "Optimize database queries"
+  minibob goal "Debug why the API is slow"
+
+  # Configuration
+  minibob doctor                    # Check setup
+  minibob observe --scan            # View running instances
+
+  # Advanced (direct execution)
+  minibob run templates/fix-bug.json --var bug="login timeout"
+  minibob improvise "Create a countdown timer"
+  minibob understand ./my-project components
+  minibob diagnose "dashboard crashes on load"
+
+DEVELOPMENT:
+  # Run from source (contributors)
+  bun run index.ts goal "your goal here"
+`)
+  process.exit(0)
+}
+
+// =============================================================================
+// RUN ACTIVITY COMMAND
+// =============================================================================
+
+if (command === "run") {
+  const templatePath = args[1]
+  if (!templatePath) {
+    console.error("Error: Template path required")
+    console.error("Usage: minibob run <template.json> [--var key=value...]")
+    process.exit(1)
+  }
+
+  // Parse variables from command line
+  const variables: Record<string, unknown> = {}
+  for (let i = 2; i < args.length; i++) {
+    const arg = args[i]
+    if (arg?.startsWith("--var")) {
+      const [, varArg] = arg.split("=", 1)
+      if (varArg) {
+        const eqIndex = varArg.indexOf("=")
+        if (eqIndex > 0) {
+          const key = varArg.slice(0, eqIndex)
+          const value = varArg.slice(eqIndex + 1)
+          variables[key] = value
+        }
+      }
+    } else if (arg && args[i - 1] === "--var") {
+      const eqIndex = arg.indexOf("=")
+      if (eqIndex > 0) {
+        const key = arg.slice(0, eqIndex)
+        const value = arg.slice(eqIndex + 1)
+        variables[key] = value
+      }
+    }
+  }
+
+  // Find reason argument
+  const reasonIndex = args.indexOf("--reason")
+  const reason = reasonIndex > -1 ? args[reasonIndex + 1] : undefined
+
+  // Run the activity
+  runActivity(templatePath, variables, reason)
+    .then((result) => {
+      console.log("\n=== Activity Result ===")
+      console.log(`Status: ${result.status}`)
+      console.log(`Duration: ${result.metrics?.duration}ms`)
+      console.log(`Tokens: ${result.metrics?.totalTokens.input} in / ${result.metrics?.totalTokens.output} out`)
+      console.log(`Cost: $${result.metrics?.cost.toFixed(4)}`)
+      
+      if (result.status === "failed") {
+        const failedTask = result.taskResults.find((t) => t.status === "failed")
+        console.error(`\nFailed task: ${failedTask?.taskId}`)
+        console.error(`Error: ${failedTask?.error}`)
+        process.exit(1)
+      }
+    })
+    .catch((error) => {
+      console.error("Error running activity:", error)
+      process.exit(1)
+    })
+}
+
+// =============================================================================
+// IMPROVISE COMMAND
+// =============================================================================
+
+else if (command === "improvise") {
+  const goal = args.slice(1).join(" ")
+  if (!goal) {
+    console.error("Error: Goal description required")
+    console.error('Usage: minibob improvise "your goal here"')
+    process.exit(1)
+  }
+
+  runImprovise(goal)
+    .then(() => {
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("Error during improvisation:", error)
+      process.exit(1)
+    })
+}
+
+// =============================================================================
+// UNDERSTAND COMMAND
+// =============================================================================
+
+else if (command === "understand") {
+  const rootPath = args[1] || process.cwd()
+  const focus = args[2] || "architecture"
+
+  runUnderstand(rootPath, focus)
+    .then(() => {
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("Error understanding codebase:", error)
+      process.exit(1)
+    })
+}
+
+// =============================================================================
+// DIAGNOSE COMMAND
+// =============================================================================
+
+else if (command === "diagnose") {
+  if (args.length < 2) {
+    console.error("Error: Problem description required")
+    console.error('Usage: minibob diagnose "description of problem"')
+    process.exit(1)
+  }
+
+  const problem = args.slice(1).join(" ")
+
+  runDiagnose(problem)
+    .then(() => {
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("Error diagnosing problem:", error)
+      process.exit(1)
+    })
+}
+
+// =============================================================================
+// GOAL COMMAND (NEW)
+// =============================================================================
+
+else if (command === "goal") {
+  goal(args.slice(1))
+    .then(() => {
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("Error executing goal:", error)
+      process.exit(1)
+    })
+}
+
+// =============================================================================
+// BURROW COMMAND (NEW)
+// =============================================================================
+
+else if (command === "burrow") {
+  burrow(args.slice(1))
+    .then(() => {
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("Error during burrow:", error)
+      process.exit(1)
+    })
+}
+
+// =============================================================================
+// OBSERVE COMMAND (NEW)
+// =============================================================================
+
+else if (command === "observe") {
+  observe(args.slice(1))
+    .then(() => {
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("Error observing:", error)
+      process.exit(1)
+    })
+}
+
+// =============================================================================
+// DOCTOR COMMAND (NEW)
+// =============================================================================
+
+else if (command === "doctor") {
+  doctor(args.slice(1))
+    .then(() => {
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("Error running doctor:", error)
+      process.exit(1)
+    })
+}
+
+// =============================================================================
+// ACP SERVER COMMAND (NEW)
+// =============================================================================
+
+else if (command === "acp") {
+  launchACPServer(args.slice(1))
+    .then(() => {
+      // ACP server runs until terminated
+    })
+    .catch((error) => {
+      console.error("Error starting ACP server:", error)
+      process.exit(1)
+    })
+}
+
+// =============================================================================
+// VESSEL COMMAND (NEW)
+// =============================================================================
+
+else if (command === "vessel") {
+  vesselCommand(args.slice(1))
+    .then(() => {
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("Error with vessel command:", error)
+      process.exit(1)
+    })
+}
+
+else {
+  // =============================================================================
+  // START SERVER (default)
+  // =============================================================================
+  startServer()
+}
+
+// =============================================================================
+// ACTIVITY RUNNER
+// =============================================================================
+
+async function runActivity(
+  templatePath: string,
+  variables: Record<string, unknown>,
+  reason?: string
+) {
+  const config = await loadConfig()
+  console.log(configSummary(config))
+
+  // Initialize agent runtime with backend integration
+  const { AgentRuntime } = await import("./src/agent-runtime")
+  const runtime = await AgentRuntime.initialize({
+    config,
+    mode: "cli",
+    enableHeartbeat: false, // No heartbeat for one-shot CLI commands
+  })
+
+  console.log(`\nRunning activity: ${templatePath}`)
+  console.log(`Variables: ${JSON.stringify(variables)}`)
+  if (reason) console.log(`Reason: ${reason}`)
+
+  try {
+    // Load template from MCP or local
+    const template = await loadTemplateFromMCPOrLocal(templatePath)
+    const executorConfig: ExecutorConfig = {
+      provider: config.provider,
+      apiKey: config.apiKey,
+      model: config.model,
+      workingDirectory: config.workingDirectory,
+      // Wire MCP activity callbacks for autonomous trailblazing
+      onSearchActivities: MCPActivityBridge.isAvailable() ? MCPActivityBridge.searchActivities : undefined,
+      onCreateActivity: MCPActivityBridge.isAvailable() ? MCPActivityBridge.createActivity : undefined,
+    }
+
+    const executor = new ActivityExecutor(executorConfig)
+
+    // Track activity
+    runtime.setCurrentActivity({
+      id: template.id,
+      name: template.name,
+      startedAt: Date.now()
+    })
+
+    const result = await executor.execute({
+      template,
+      variables,
+      reason,
+      onTaskStart: (taskId) => {
+        console.log(`\n>>> Starting task: ${taskId}`)
+        runtime.setCurrentActivity({
+          id: template.id,
+          name: template.name,
+          task: taskId,
+          startedAt: Date.now()
+        })
+      },
+      onTaskComplete: (taskId, taskResult) => {
+        const status = taskResult.status === "completed" ? "✓" : "✗"
+        console.log(`${status} Completed task: ${taskId}`)
+      },
+    })
+
+    // Report execution to backend
+    await runtime.reportExecution(result)
+    runtime.clearCurrentActivity()
+
+    return result
+  } finally {
+    // Clean shutdown
+    await runtime.shutdown()
+  }
+}
+
+// =============================================================================
+// UNDERSTAND COMMAND RUNNER
+// =============================================================================
+
+async function runUnderstand(rootPath: string, focus: string) {
+  const config = await loadConfig()
+  console.log(configSummary(config))
+
+  // Initialize MCP if configured (for potential backend features)
+  if (config.vessels.metabob) {
+    const mcpEndpoint = config.vessels.metabob.endpoint
+    console.log(`\nInitializing MCP client: ${mcpEndpoint}`)
+    await initializeMCP({ endpoint: mcpEndpoint, apiKey: config.apiKey }, true)
+  }
+
+  console.log(`\n=== Understanding Codebase ===`)
+  console.log(`Path: ${rootPath}`)
+  console.log(`Focus: ${focus}\n`)
+
+  // 1. Fast static exploration
+  const explorer = new CodeExplorer(config.workingDirectory)
+  console.log('Exploring codebase structure...')
+  const structure = await explorer.explore(rootPath)
+
+  console.log(`\n📊 Codebase Overview:`)
+  console.log(`  Total Files: ${structure.totalFiles}`)
+  console.log(`  Total Lines of Code: ${structure.totalLoc.toLocaleString()}`)
+  console.log(`  Total Size: ${(structure.totalSize / 1024).toFixed(2)} KB`)
+  console.log(`\n📁 File Types:`)
+  for (const [ext, count] of Object.entries(structure.filesByType).sort((a, b) => b[1] - a[1]).slice(0, 10)) {
+    console.log(`  .${ext}: ${count} files`)
+  }
+  console.log(`\n🔧 Frameworks:`)
+  if (structure.dependencies.frameworks.length > 0) {
+    for (const framework of structure.dependencies.frameworks) {
+      console.log(`  - ${framework}`)
+    }
+  } else {
+    console.log(`  (none detected)`)
+  }
+  console.log(`\n🚀 Entry Points:`)
+  for (const entry of structure.entryPoints) {
+    console.log(`  - ${entry}`)
+  }
+
+  // 2. LLM-powered semantic analysis
+  console.log(`\n🤖 Performing semantic analysis with LLM...`)
+
+  // Use the target path as working directory for file reads
+  const analyzePath = rootPath.startsWith('/') ? rootPath : `${config.workingDirectory}/${rootPath}`
+
+  const executorConfig: ExecutorConfig = {
+    provider: config.provider,
+    apiKey: config.apiKey,
+    model: config.model,
+    workingDirectory: analyzePath,
+  }
+
+  const executor = new ActivityExecutor(executorConfig)
+  const analyzer = new ApplicationAnalyzer(executor, explorer)
+
+  const analysis = await analyzer.analyze({ rootPath, focus: focus as any, depth: 'medium' })
+
+  console.log(`\n📝 Analysis Results:\n`)
+  console.log(`Architecture Pattern: ${analysis.architecture.pattern}`)
+  console.log(`Description: ${analysis.architecture.description}`)
+
+  if (analysis.architecture.layers.length > 0) {
+    console.log(`\nArchitectural Layers:`)
+    for (const layer of analysis.architecture.layers) {
+      console.log(`  - ${layer}`)
+    }
+  }
+
+  if (analysis.components.keyModules.length > 0) {
+    console.log(`\nKey Modules:`)
+    for (const module of analysis.components.keyModules) {
+      console.log(`  - ${module.name}: ${module.purpose}`)
+    }
+  }
+
+  console.log(`\n✅ Understanding complete!\n`)
+}
+
+// =============================================================================
+// DIAGNOSE COMMAND RUNNER
+// =============================================================================
+
+async function runDiagnose(problem: string) {
+  const config = await loadConfig()
+  console.log(configSummary(config))
+
+  // Initialize MCP if configured
+  if (config.vessels.metabob) {
+    const mcpEndpoint = config.vessels.metabob.endpoint
+    console.log(`\nInitializing MCP client: ${mcpEndpoint}`)
+    await initializeMCP({ endpoint: mcpEndpoint, apiKey: config.apiKey }, true)
+  }
+
+  console.log(`\n=== Diagnosing Problem ===`)
+  console.log(`Problem: ${problem}\n`)
+
+  const executorConfig: ExecutorConfig = {
+    provider: config.provider,
+    apiKey: config.apiKey,
+    model: config.model,
+    workingDirectory: config.workingDirectory,
+  }
+
+  const executor = new ActivityExecutor(executorConfig)
+  const explorer = new CodeExplorer(config.workingDirectory)
+  const analyzer = new ApplicationAnalyzer(executor, explorer)
+
+  console.log('🔍 Analyzing problem...')
+  const diagnosis = await analyzer.diagnose(problem)
+
+  console.log(`\n📊 Diagnosis Results:\n`)
+  console.log(`Confidence: ${diagnosis.confidence.toUpperCase()}`)
+  console.log(`\nRoot Cause:`)
+  console.log(`  ${diagnosis.rootCause}`)
+
+  if (diagnosis.symptoms.length > 0) {
+    console.log(`\nSymptoms:`)
+    for (const symptom of diagnosis.symptoms) {
+      console.log(`  - ${symptom}`)
+    }
+  }
+
+  if (diagnosis.affectedFiles.length > 0) {
+    console.log(`\nAffected Files:`)
+    for (const file of diagnosis.affectedFiles) {
+      console.log(`  - ${file}`)
+    }
+  }
+
+  console.log(`\nRecommended Fix:`)
+  console.log(`  ${diagnosis.recommendedFix}`)
+
+  if (diagnosis.validationSteps.length > 0) {
+    console.log(`\nValidation Steps:`)
+    for (const step of diagnosis.validationSteps) {
+      console.log(`  - ${step}`)
+    }
+  }
+
+  console.log(`\n✅ Diagnosis complete!\n`)
+}
+
+// =============================================================================
+// IMPROVISE COMMAND RUNNER
+// =============================================================================
+
+async function runImprovise(goal: string) {
+  const config = await loadConfig()
+  console.log(configSummary(config))
+
+  // Initialize agent runtime with backend integration
+  const { AgentRuntime } = await import("./src/agent-runtime")
+  const runtime = await AgentRuntime.initialize({
+    config,
+    mode: "cli",
+    enableHeartbeat: false,
+  })
+
+  console.log(`\n🎭 Improvising toward goal: ${goal}`)
+  console.log('Recording all steps...\n')
+
+  try {
+    const { GoalImproviser } = await import('./src/improviser')
+    const improviser = new GoalImproviser({
+      provider: config.provider,
+      apiKey: config.apiKey,
+      model: config.model,
+      workingDirectory: config.workingDirectory
+    })
+
+    // Track activity
+    runtime.setCurrentActivity({
+      id: `improvise-${Date.now()}`,
+      name: 'Pure Improvisation',
+      task: goal,
+      startedAt: Date.now()
+    })
+
+    const trace = await improviser.improvise(goal)
+    runtime.clearCurrentActivity()
+
+    // Display results
+    console.log(`\n${'='.repeat(60)}`)
+    console.log(`Goal: ${goal}`)
+    console.log(`Status: ${trace.outcome.goal_achieved ? '✅ Achieved' : '❌ Not achieved'}`)
+    console.log(`Steps: ${trace.steps.length}`)
+    console.log(`Duration: ${trace.outcome.total_duration_ms}ms`)
+    console.log(`Cost: $${trace.outcome.total_cost.toFixed(4)}`)
+    console.log(`${'='.repeat(60)}\n`)
+
+    // Show steps summary
+    console.log('Steps taken:')
+    trace.steps.forEach(step => {
+      const paramsPreview = JSON.stringify(step.params).substring(0, 50)
+      console.log(`  ${step.step}. ${step.thought}`)
+      console.log(`     → ${step.action}(${paramsPreview}${paramsPreview.length >= 50 ? '...' : ''})`)
+      console.log(`     ${step.result.success ? '✓' : '✗'} ${step.result.success ? 'Success' : 'Failed'} (${step.duration_ms}ms)`)
+    })
+
+    // Extract template if successful
+    if (trace.outcome.goal_achieved) {
+      console.log('\n🧬 Extracting template from successful improvisation...')
+
+      const { extractTemplateFromImprovisation } = await import('./src/template-extractor')
+      const template = await extractTemplateFromImprovisation(trace)
+
+      console.log(`✅ Template created: ${template.id}`)
+      console.log(`   Name: ${template.name}`)
+      console.log(`   Tasks: ${template.tasks.length}`)
+
+      // Register with backend if available
+      const { getMCPClient, isMCPEnabled } = await import('./src/mcp')
+      if (isMCPEnabled()) {
+        try {
+          const mcp = getMCPClient()
+          // Store the template - assuming there's a method for this
+          // For now, just log that we would register it
+          console.log(`   Would register with backend (not yet implemented)`)
+        } catch (error) {
+          console.log(`   Backend registration skipped: ${error}`)
+        }
+      }
+
+      // TODO: Review and create variants
+      // This requires the template-reviewer module which we'll implement next
+      console.log('\n💡 Template extraction complete!')
+      console.log('   Next: Create variants through review (not yet implemented)')
+    } else {
+      console.log('\n❌ Goal not achieved - no template extracted')
+      if (trace.outcome.error) {
+        console.log(`   Error: ${trace.outcome.error}`)
+      }
+    }
+
+    console.log(`\n✅ Improvisation complete!\n`)
+  } finally {
+    // Clean shutdown
+    await runtime.shutdown()
+  }
+}
+
+// =============================================================================
+// HTTP SERVER
+// =============================================================================
+
+async function startServer() {
+  const config = await loadConfig()
+  console.log(configSummary(config))
+
+  // =============================================================================
+  // ENVIRONMENT AUTO-DETECTION
+  // =============================================================================
+  
+  console.log("\n=== Environment Detection ===")
+  const { detectCompleteEnvironment } = await import("./src/environment")
+  
+  const mcpEndpoint = config.vessels.metabob?.endpoint
+  const envInfo = await detectCompleteEnvironment(mcpEndpoint)
+  
+  console.log(`Environment: ${envInfo.environment}`)
+  console.log(`Cluster Mode: ${envInfo.clusterMode} (${envInfo.peerCount} peer(s))`)
+  console.log(`Backend Available: ${envInfo.backendAvailable}`)
+  console.log("=============================\n")
+
+  // Build runtime context for dynamic manifest
+  const runtime: RuntimeContext = {
+    environment: envInfo.environment,
+    clusterMode: envInfo.clusterMode,
+    peerCount: envInfo.peerCount,
+    boredomEnabled: false,
+    acpGossipEnabled: false,
+    backendAvailable: envInfo.backendAvailable,
+  }
+
+  // =============================================================================
+  // CONDITIONAL MCP INITIALIZATION
+  // =============================================================================
+  
+  let mcp: MCPClient | null = null
+  if (config.vessels.metabob && envInfo.backendAvailable) {
+    console.log(`Initializing MCP client: ${mcpEndpoint}`)
+    mcp = await initializeMCP({ endpoint: mcpEndpoint!, apiKey: config.apiKey }, false)
+    
+    if (mcp) {
+      // Register this vessel with the backend
+      const tempManifest = generateManifest(config, runtime)
+      await mcp.registerVessel({
+        id: tempManifest.id,
+        name: tempManifest.name,
+        version: tempManifest.version,
+        capabilities: tempManifest.capabilities,
+        endpoint: tempManifest.acpEndpoint,
+      })
+      console.log("✓ Registered with backend")
+    }
+  } else if (config.vessels.metabob && !envInfo.backendAvailable) {
+    console.log("Backend unavailable, running in local mode")
+  }
+
+  // =============================================================================
+  // CONDITIONAL BOREDOM INITIALIZATION (Cluster Mode Only)
+  // =============================================================================
+  
+  if (envInfo.clusterMode && mcp) {
+    console.log("\nInitializing boredom task executor (cluster mode)...")
+    const executorConfig: ExecutorConfig = {
+      provider: config.provider,
+      apiKey: config.apiKey,
+      model: config.model,
+      workingDirectory: config.workingDirectory,
+    }
+    
+    initializeBoredom({
+      pollInterval: 30000, // Poll every 30 seconds
+      idleThreshold: 60000, // Consider idle after 60 seconds
+      // LLM config for goal-based execution via SearchFirstExecutor
+      llmConfig: {
+        provider: config.provider,
+        apiKey: config.apiKey,
+        model: config.model,
+        workingDirectory: config.workingDirectory,
+      },
+      // Template-based execution callback (legacy mode)
+      onExecuteTask: async (template, variables, reason) => {
+        // Create executor with MCP activity callbacks for boredom tasks
+        const boredomExecutorConfig = {
+          ...executorConfig,
+          onSearchActivities: MCPActivityBridge.isAvailable() ? MCPActivityBridge.searchActivities : undefined,
+          onCreateActivity: MCPActivityBridge.isAvailable() ? MCPActivityBridge.createActivity : undefined,
+        }
+        const executor = new ActivityExecutor(boredomExecutorConfig)
+        return executor.execute({ template, variables, reason })
+      },
+    })
+    
+    // Start boredom executor with cluster mode flag
+    startBoredom(envInfo.clusterMode)
+    runtime.boredomEnabled = true
+    console.log("✓ Boredom task executor started")
+  } else if (!envInfo.clusterMode) {
+    console.log("Boredom disabled: Not in cluster mode")
+  } else if (!mcp) {
+    console.log("Boredom disabled: Backend unavailable")
+  }
+
+  // =============================================================================
+  // TODO: ACP GOSSIP (Cluster Mode Only)
+  // =============================================================================
+  
+  if (envInfo.clusterMode) {
+    console.log("\n[TODO] ACP Gossip protocol would be initialized here")
+    console.log("  - DNS peer discovery")
+    console.log("  - Periodic health broadcasts")
+    runtime.acpGossipEnabled = true
+  }
+
+  // Generate final manifest with runtime capabilities
+  const manifest = generateManifest(config, runtime)
+  const acpConfig: ACPServerConfig = {
+    provider: config.provider,
+    apiKey: config.apiKey,
+    model: config.model,
+    workingDirectory: config.workingDirectory,
+  }
+
+  // =============================================================================
+  // INSTANCE STATE TRACKING (for observe command)
+  // =============================================================================
+  const instanceId = generateInstanceId()
+  const startTime = Date.now()
+  let activitiesExecuted = 0
+  let totalCost = 0
+  let currentActivity: {
+    id: string
+    name?: string
+    task?: string
+    startedAt: number
+  } | null = null
+
+  // Register instance
+  await registerInstance({
+    id: instanceId,
+    pid: process.pid,
+    port: config.port,
+    host: config.host,
+    startTime,
+    workingDirectory: config.workingDirectory,
+    status: 'idle',
+    capabilities: manifest.capabilities,
+  })
+  console.log(`✓ Registered instance: ${instanceId}`)
+
+  const server = Bun.serve({
+    port: config.port,
+    hostname: config.host,
+
+    fetch(request) {
+      const url = new URL(request.url)
+      const path = url.pathname
+
+      // Health check
+      if (path === "/health") {
+        return new Response(JSON.stringify({ status: "ok", vessel: "minibob" }), {
+          headers: { "Content-Type": "application/json" },
+        })
+      }
+
+      // Status endpoint (for observe command)
+      if (path === "/status") {
+        const status = currentActivity ? 'executing' : (runtime.boredomEnabled ? 'boredom' : 'idle')
+        return new Response(JSON.stringify({
+          id: instanceId,
+          status,
+          currentActivity: currentActivity ? {
+            id: currentActivity.id,
+            name: currentActivity.name,
+            task: currentActivity.task,
+            progress: 0.5, // TODO: Track actual progress
+          } : undefined,
+          metrics: {
+            activitiesExecuted,
+            uptime: Date.now() - startTime,
+            totalCost,
+          },
+          config: {
+            workingDirectory: config.workingDirectory,
+            model: config.model,
+            port: config.port,
+          },
+        }), {
+          headers: { "Content-Type": "application/json" },
+        })
+      }
+
+      // Vessel manifest/config
+      if (path === "/config" || path === "/manifest") {
+        return new Response(JSON.stringify(manifest), {
+          headers: { "Content-Type": "application/json" },
+        })
+      }
+
+      // ACP endpoint
+      if (path === "/acp" || path === "/acp/stream") {
+        if (request.method === "POST") {
+          return handleACPRequest(acpConfig, request)
+        }
+        // WebSocket upgrade would happen here
+        return new Response("ACP endpoint - use POST or WebSocket", {
+          status: 400,
+        })
+      }
+
+      // Run activity endpoint
+      if (path === "/run" && request.method === "POST") {
+        markBoredomActivity() // Mark activity to prevent boredom tasks during user requests
+        return handleRunActivity(request, config)
+      }
+
+      // List templates
+      if (path === "/templates" && request.method === "GET") {
+        return handleListTemplates(config.templatesDir)
+      }
+
+      // Goal-seeking endpoint
+      if (path === "/goal" && request.method === "POST") {
+        markBoredomActivity() // Mark activity to prevent boredom tasks during user requests
+        return handleGoal(request, config)
+      }
+
+      // Search-first goal endpoint (experimental)
+      if (path === "/goal/search-first" && request.method === "POST") {
+        markBoredomActivity()
+        return handleSearchFirstGoal(request, config)
+      }
+
+      // 404
+      return new Response(JSON.stringify({
+        error: "Not found",
+        endpoints: [
+          "GET  /health",
+          "GET  /status",
+          "GET  /config",
+          "POST /acp",
+          "POST /run",
+          "POST /goal",
+          "POST /goal/search-first",
+          "GET  /templates",
+        ],
+      }), {
+        status: 404,
+        headers: { "Content-Type": "application/json" },
+      })
+    },
+  })
+
+  console.log(`\nminibob server running at http://${config.host}:${config.port}`)
+  console.log(`\nEndpoints:`)
+  console.log(`  GET  /health      - Health check`)
+  console.log(`  GET  /status      - Instance status (for observe)`)
+  console.log(`  GET  /config      - Vessel manifest`)
+  console.log(`  POST /acp         - ACP protocol handler`)
+  console.log(`  POST /run         - Run activity template`)
+  console.log(`  POST /goal        - Goal-seeking execution`)
+  console.log(`  GET  /templates   - List available templates`)
+
+  // =============================================================================
+  // HEARTBEAT TO BACKEND (for centralized observation)
+  // =============================================================================
+  let heartbeatInterval: ReturnType<typeof setInterval> | null = null
+
+  const sendHeartbeat = async () => {
+    if (!envInfo.backendAvailable) return
+
+    try {
+      const heartbeatUrl = `${mcpEndpoint}/v2/vessels/heartbeat`
+      const status = currentActivity ? 'executing' : (runtime.boredomEnabled ? 'bored' : 'idle')
+
+      await fetch(heartbeatUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          pod_name: instanceId,
+          namespace: 'local', // Use 'local' for non-k8s environments
+          status,
+          current_activity: currentActivity ? {
+            variant_id: currentActivity.id,
+            activity_id: currentActivity.id,
+            variant_name: currentActivity.name || currentActivity.id,
+            started_at: new Date(currentActivity.startedAt).toISOString(),
+            current_task: currentActivity.task,
+          } : null,
+          metrics: {
+            executions_completed: activitiesExecuted,
+            total_cost_usd: totalCost,
+            uptime_seconds: Math.floor((Date.now() - startTime) / 1000),
+          },
+        }),
+        signal: AbortSignal.timeout(5000),
+      })
+    } catch (error) {
+      // Silently ignore heartbeat failures - backend might be temporarily unavailable
+    }
+  }
+
+  // Send initial heartbeat and start interval
+  if (envInfo.backendAvailable) {
+    sendHeartbeat()
+    heartbeatInterval = setInterval(sendHeartbeat, 30000) // Every 30 seconds
+    console.log("✓ Heartbeat reporting started (30s interval)")
+  }
+
+  // RELIABILITY: Graceful shutdown on SIGTERM/SIGINT
+  let isShuttingDown = false
+  const gracefulShutdown = async (signal: string) => {
+    if (isShuttingDown) return
+    isShuttingDown = true
+
+    console.log(`\n\nReceived ${signal}, starting graceful shutdown...`)
+
+    // Stop heartbeat
+    if (heartbeatInterval) {
+      clearInterval(heartbeatInterval)
+    }
+
+    // Deregister instance
+    try {
+      await deregisterInstance(instanceId)
+      console.log("✓ Deregistered instance")
+    } catch (error) {
+      console.error("Error deregistering instance:", error)
+    }
+
+    // Stop accepting new requests
+    try {
+      server.stop()
+      console.log("✓ Stopped accepting new requests")
+    } catch (error) {
+      console.error("Error stopping server:", error)
+    }
+
+    // Give in-flight requests time to complete (5 seconds)
+    await new Promise((resolve) => setTimeout(resolve, 5000))
+
+    console.log("✓ Graceful shutdown complete")
+    process.exit(0)
+  }
+
+  process.on("SIGTERM", () => gracefulShutdown("SIGTERM"))
+  process.on("SIGINT", () => gracefulShutdown("SIGINT"))
+}
+
+// =============================================================================
+// REQUEST HANDLERS
+// =============================================================================
+
+async function handleRunActivity(request: Request, config: Awaited<ReturnType<typeof loadConfig>>) {
+  try {
+    // SECURITY: Validate request size to prevent DoS
+    const contentLength = request.headers.get("Content-Length")
+    validateRequestSize(contentLength, 10 * 1024 * 1024) // 10MB limit
+
+    const body = await request.json()
+    
+    // SECURITY: Validate input schema
+    const { template: templatePath, variables, reason } = validateRunActivityRequest(body)
+
+    const template = await loadTemplateFromMCPOrLocal(templatePath)
+    const executorConfig: ExecutorConfig = {
+      provider: config.provider,
+      apiKey: config.apiKey,
+      model: config.model,
+      workingDirectory: config.workingDirectory,
+      // Wire MCP activity callbacks for autonomous trailblazing
+      onSearchActivities: MCPActivityBridge.isAvailable() ? MCPActivityBridge.searchActivities : undefined,
+      onCreateActivity: MCPActivityBridge.isAvailable() ? MCPActivityBridge.createActivity : undefined,
+    }
+
+    const executor = new ActivityExecutor(executorConfig)
+    const result = await executor.execute({
+      template,
+      variables,
+      reason,
+    })
+
+    return new Response(JSON.stringify(result), {
+      headers: { "Content-Type": "application/json" },
+    })
+  } catch (error) {
+    // Return appropriate status code for validation errors
+    const isValidationError = error instanceof ValidationException
+    return new Response(JSON.stringify({ 
+      error: error instanceof Error ? error.message : String(error),
+      ...(isValidationError && { validationErrors: (error as ValidationException).errors }),
+    }), {
+      status: isValidationError ? 400 : 500,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+}
+
+async function handleGoal(request: Request, config: Awaited<ReturnType<typeof loadConfig>>) {
+  try {
+    // SECURITY: Validate request size to prevent DoS
+    const contentLength = request.headers.get("Content-Length")
+    validateRequestSize(contentLength, 10 * 1024 * 1024) // 10MB limit
+
+    const body = await request.json() as Record<string, unknown>
+    
+    // Parse goal request
+    const goal = body.goal as string
+    const context = (body.context as Record<string, unknown>) || {}
+    const impulseRefs = (body.impulseRefs as string[]) || []
+    const maxActivities = (body.maxActivities as number) || 5
+    const maxCost = (body.maxCost as number) || 10.0
+    
+    if (!goal || typeof goal !== 'string') {
+      throw new ValidationException([
+        { field: 'goal', message: 'Must be a non-empty string' }
+      ])
+    }
+
+    console.log(`[Goal] Received: ${goal}`)
+    console.log(`[Goal] Context:`, context)
+    console.log(`[Goal] Impulse refs:`, impulseRefs)
+    console.log(`[Goal] Max activities: ${maxActivities}, Max cost: $${maxCost}`)
+
+    // Create executor with MCP activity callbacks
+    const executorConfig: ExecutorConfig = {
+      provider: config.provider,
+      apiKey: config.apiKey,
+      model: config.model,
+      workingDirectory: config.workingDirectory,
+      onSearchActivities: MCPActivityBridge.isAvailable() ? MCPActivityBridge.searchActivities : undefined,
+      onCreateActivity: MCPActivityBridge.isAvailable() ? MCPActivityBridge.createActivity : undefined,
+    }
+
+    const executor = new ActivityExecutor(executorConfig)
+    const goalProcessor = new GoalProcessor({
+      workingDirectory: config.workingDirectory,
+      executor,
+    })
+
+    // Execute goal-seeking (GoalProcessor signature is just: message, context, options)
+    const result = await goalProcessor.executeGoal(goal, context, {
+      maxActivities,
+      maxCost,
+    })
+
+    return new Response(JSON.stringify(result), {
+      headers: { "Content-Type": "application/json" },
+    })
+  } catch (error) {
+    // Return appropriate status code for validation errors
+    const isValidationError = error instanceof ValidationException
+    return new Response(JSON.stringify({ 
+      error: error instanceof Error ? error.message : String(error),
+      ...(isValidationError && { validationErrors: (error as ValidationException).errors }),
+    }), {
+      status: isValidationError ? 400 : 500,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+}
+
+/**
+ * Handle search-first goal execution
+ * Uses step-by-step decomposition with activity reuse
+ */
+async function handleSearchFirstGoal(request: Request, config: Awaited<ReturnType<typeof loadConfig>>) {
+  try {
+    const contentLength = request.headers.get("Content-Length")
+    validateRequestSize(contentLength, 10 * 1024 * 1024)
+
+    const body = await request.json() as Record<string, unknown>
+
+    const goal = body.goal as string
+    const context = (body.context as Record<string, unknown>) || {}
+
+    if (!goal || typeof goal !== 'string') {
+      throw new ValidationException([
+        { field: 'goal', message: 'Must be a non-empty string' }
+      ])
+    }
+
+    console.log(`[SearchFirst] Received goal: ${goal}`)
+
+    const executor = new SearchFirstExecutor({
+      provider: config.provider,
+      apiKey: config.apiKey,
+      model: config.model,
+      workingDirectory: config.workingDirectory,
+      maxSteps: 5,
+      maxTokensPerStep: 4096,
+    })
+
+    const result = await executor.execute(goal, context)
+
+    return new Response(JSON.stringify(result), {
+      headers: { "Content-Type": "application/json" },
+    })
+  } catch (error) {
+    const isValidationError = error instanceof ValidationException
+    return new Response(JSON.stringify({
+      error: error instanceof Error ? error.message : String(error),
+      ...(isValidationError && { validationErrors: (error as ValidationException).errors }),
+    }), {
+      status: isValidationError ? 400 : 500,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+}
+
+async function handleListTemplates(templatesDir: string) {
+  try {
+    const glob = new Bun.Glob("**/*.json")
+    const templates: string[] = []
+    
+    for await (const file of glob.scan({ cwd: templatesDir })) {
+      templates.push(file)
+    }
+
+    return new Response(JSON.stringify({ templates }), {
+      headers: { "Content-Type": "application/json" },
+    })
+  } catch (error) {
+    return new Response(JSON.stringify({ 
+      templates: [],
+      error: error instanceof Error ? error.message : String(error),
+    }), {
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+}