@metabob/minibob 0.1.2

package/src/agent-runtime.ts

@@ -0,0 +1,365 @@
+/**
+ * Agent Runtime - Reusable backend integration for CLI and server modes
+ *
+ * Provides:
+ * - Backend registration/deregistration
+ * - Heartbeat reporting
+ * - Execution metrics tracking
+ * - Graceful shutdown
+ *
+ * Usage:
+ *   const runtime = await AgentRuntime.initialize(config)
+ *   // ... do work ...
+ *   await runtime.reportExecution(execution)
+ *   await runtime.shutdown()
+ */
+
+import type { MinibobConfig, ActivityExecution, VesselManifest } from "./types"
+import type { MCPClient } from "./mcp"
+import { initializeMCP, getMCPClient, isMCPEnabled } from "./mcp"
+import { generateManifest, type RuntimeContext } from "./config"
+import { detectCompleteEnvironment } from "./environment"
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface AgentRuntimeConfig {
+  config: MinibobConfig
+  mode: "cli" | "server"
+  instanceId?: string
+  enableHeartbeat?: boolean
+  heartbeatInterval?: number
+}
+
+export interface AgentMetrics {
+  executionsCompleted: number
+  executionsFailed: number
+  totalCost: number
+  totalTokens: {
+    input: number
+    output: number
+  }
+  uptime: number
+}
+
+export interface CurrentActivity {
+  id: string
+  name?: string
+  task?: string
+  startedAt: number
+}
+
+// =============================================================================
+// AGENT RUNTIME
+// =============================================================================
+
+export class AgentRuntime {
+  private config: MinibobConfig
+  private mode: "cli" | "server"
+  private instanceId: string
+  private startTime: number
+  private mcp: MCPClient | null = null
+  private manifest: VesselManifest | null = null
+
+  private heartbeatInterval: NodeJS.Timeout | null = null
+  private heartbeatIntervalMs: number
+  private enableHeartbeat: boolean
+
+  private metrics: AgentMetrics = {
+    executionsCompleted: 0,
+    executionsFailed: 0,
+    totalCost: 0,
+    totalTokens: { input: 0, output: 0 },
+    uptime: 0
+  }
+
+  private currentActivity: CurrentActivity | null = null
+  private shuttingDown = false
+
+  private constructor(options: AgentRuntimeConfig) {
+    this.config = options.config
+    this.mode = options.mode
+    this.instanceId = options.instanceId || this.generateInstanceId()
+    this.startTime = Date.now()
+    this.enableHeartbeat = options.enableHeartbeat ?? (options.mode === "server")
+    this.heartbeatIntervalMs = options.heartbeatInterval ?? 30000
+  }
+
+  /**
+   * Initialize agent runtime with backend connection
+   */
+  static async initialize(options: AgentRuntimeConfig): Promise<AgentRuntime> {
+    const runtime = new AgentRuntime(options)
+
+    console.log(`[AgentRuntime] Initializing in ${options.mode} mode (instance: ${runtime.instanceId})`)
+
+    // Detect environment
+    const mcpEndpoint = runtime.config.vessels.metabob?.endpoint
+    const envInfo = await detectCompleteEnvironment(mcpEndpoint)
+
+    console.log(`[AgentRuntime] Environment: ${envInfo.environment}`)
+    console.log(`[AgentRuntime] Backend Available: ${envInfo.backendAvailable}`)
+
+    // Initialize MCP if backend available
+    if (runtime.config.vessels.metabob && envInfo.backendAvailable) {
+      console.log(`[AgentRuntime] Connecting to backend: ${mcpEndpoint}`)
+
+      try {
+        runtime.mcp = await initializeMCP(
+          {
+            endpoint: mcpEndpoint!,
+            apiKey: runtime.config.apiKey
+          },
+          options.mode === "cli" // Skip health check in CLI mode for faster startup
+        )
+
+        // Generate manifest
+        const runtimeContext: RuntimeContext = {
+          environment: envInfo.environment,
+          clusterMode: envInfo.clusterMode,
+          peerCount: envInfo.peerCount,
+          boredomEnabled: false, // CLI mode doesn't do boredom
+          acpGossipEnabled: false,
+          backendAvailable: true,
+        }
+
+        runtime.manifest = generateManifest(runtime.config, runtimeContext)
+
+        // Register with backend
+        if (runtime.mcp) {
+          await runtime.mcp.registerVessel({
+            id: runtime.manifest.id,
+            name: runtime.manifest.name,
+            version: runtime.manifest.version,
+            capabilities: runtime.manifest.capabilities,
+            endpoint: runtime.manifest.acpEndpoint,
+          })
+          console.log("[AgentRuntime] ✓ Registered with backend")
+
+          // Start heartbeat if enabled
+          if (runtime.enableHeartbeat) {
+            runtime.startHeartbeat()
+          }
+        }
+      } catch (error) {
+        console.warn("[AgentRuntime] Failed to connect to backend:", error instanceof Error ? error.message : String(error))
+        console.warn("[AgentRuntime] Continuing in standalone mode")
+      }
+    } else {
+      console.log("[AgentRuntime] Running in standalone mode (no backend)")
+    }
+
+    // Setup graceful shutdown handlers
+    runtime.setupShutdownHandlers()
+
+    return runtime
+  }
+
+  /**
+   * Start heartbeat reporting
+   */
+  private startHeartbeat(): void {
+    if (!this.mcp || !this.manifest) return
+
+    const sendHeartbeat = async () => {
+      if (!this.mcp || this.shuttingDown) return
+
+      try {
+        const endpoint = this.config.vessels.metabob?.endpoint
+        if (!endpoint) return
+
+        const status = this.currentActivity ? 'executing' : 'idle'
+        const heartbeatUrl = `${endpoint}/v2/vessels/heartbeat`
+
+        await fetch(heartbeatUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            pod_name: this.instanceId,
+            namespace: this.mode === 'cli' ? 'cli' : 'local',
+            status,
+            current_activity: this.currentActivity ? {
+              variant_id: this.currentActivity.id,
+              activity_id: this.currentActivity.id,
+              variant_name: this.currentActivity.name || this.currentActivity.id,
+              started_at: new Date(this.currentActivity.startedAt).toISOString(),
+              current_task: this.currentActivity.task,
+            } : null,
+            metrics: {
+              executions_completed: this.metrics.executionsCompleted,
+              total_cost_usd: this.metrics.totalCost,
+              uptime_seconds: Math.floor((Date.now() - this.startTime) / 1000),
+            },
+          }),
+          signal: AbortSignal.timeout(5000),
+        })
+      } catch (error) {
+        // Silently ignore heartbeat failures
+      }
+    }
+
+    // Send initial heartbeat
+    sendHeartbeat()
+
+    // Start interval
+    this.heartbeatInterval = setInterval(sendHeartbeat, this.heartbeatIntervalMs)
+    console.log(`[AgentRuntime] ✓ Heartbeat started (${this.heartbeatIntervalMs}ms interval)`)
+  }
+
+  /**
+   * Mark start of activity execution
+   */
+  setCurrentActivity(activity: CurrentActivity): void {
+    this.currentActivity = activity
+  }
+
+  /**
+   * Clear current activity
+   */
+  clearCurrentActivity(): void {
+    this.currentActivity = null
+  }
+
+  /**
+   * Report execution to backend
+   */
+  async reportExecution(execution: ActivityExecution): Promise<void> {
+    // Update metrics
+    if (execution.status === "completed") {
+      this.metrics.executionsCompleted++
+    } else if (execution.status === "failed") {
+      this.metrics.executionsFailed++
+    }
+
+    if (execution.metrics) {
+      this.metrics.totalCost += execution.metrics.cost
+      this.metrics.totalTokens.input += execution.metrics.totalTokens.input
+      this.metrics.totalTokens.output += execution.metrics.totalTokens.output
+    }
+
+    // Store execution trace in backend if available
+    if (this.mcp) {
+      try {
+        await this.mcp.storeExecutionTrace(execution)
+        console.log(`[AgentRuntime] ✓ Execution trace stored: ${execution.id}`)
+      } catch (error) {
+        console.warn("[AgentRuntime] Failed to store execution trace:", error instanceof Error ? error.message : String(error))
+      }
+    }
+  }
+
+  /**
+   * Get current metrics
+   */
+  getMetrics(): AgentMetrics {
+    return {
+      ...this.metrics,
+      uptime: Date.now() - this.startTime
+    }
+  }
+
+  /**
+   * Get instance ID
+   */
+  getInstanceId(): string {
+    return this.instanceId
+  }
+
+  /**
+   * Check if backend is available
+   */
+  hasBackend(): boolean {
+    return this.mcp !== null
+  }
+
+  /**
+   * Get MCP client (if available)
+   */
+  getMCP(): MCPClient | null {
+    return this.mcp
+  }
+
+  /**
+   * Setup graceful shutdown handlers
+   */
+  private setupShutdownHandlers(): void {
+    const gracefulShutdown = async (signal: string) => {
+      if (this.shuttingDown) return
+      this.shuttingDown = true
+
+      console.log(`\n[AgentRuntime] Received ${signal}, shutting down gracefully...`)
+      await this.shutdown()
+      process.exit(0)
+    }
+
+    process.on("SIGTERM", () => gracefulShutdown("SIGTERM"))
+    process.on("SIGINT", () => gracefulShutdown("SIGINT"))
+  }
+
+  /**
+   * Shutdown runtime and cleanup
+   */
+  async shutdown(): Promise<void> {
+    if (this.shuttingDown && !this.heartbeatInterval) {
+      return // Already shut down
+    }
+
+    console.log("[AgentRuntime] Shutting down...")
+
+    // Stop heartbeat
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval)
+      this.heartbeatInterval = null
+      console.log("[AgentRuntime] ✓ Heartbeat stopped")
+    }
+
+    // Deregister from backend
+    if (this.mcp && this.manifest) {
+      try {
+        // Send final heartbeat with shutdown status
+        const endpoint = this.config.vessels.metabob?.endpoint
+        if (endpoint) {
+          await fetch(`${endpoint}/v2/vessels/heartbeat`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              pod_name: this.instanceId,
+              namespace: this.mode === 'cli' ? 'cli' : 'local',
+              status: 'shutdown',
+              metrics: {
+                executions_completed: this.metrics.executionsCompleted,
+                total_cost_usd: this.metrics.totalCost,
+                uptime_seconds: Math.floor((Date.now() - this.startTime) / 1000),
+              },
+            }),
+            signal: AbortSignal.timeout(2000),
+          })
+        }
+        console.log("[AgentRuntime] ✓ Deregistered from backend")
+      } catch (error) {
+        // Ignore errors during shutdown
+      }
+    }
+
+    // Print final metrics
+    const metrics = this.getMetrics()
+    console.log("\n[AgentRuntime] Final Metrics:")
+    console.log(`  Executions: ${metrics.executionsCompleted} completed, ${metrics.executionsFailed} failed`)
+    console.log(`  Cost: $${metrics.totalCost.toFixed(4)}`)
+    console.log(`  Tokens: ${metrics.totalTokens.input} in / ${metrics.totalTokens.output} out`)
+    console.log(`  Uptime: ${Math.floor(metrics.uptime / 1000)}s`)
+
+    console.log("[AgentRuntime] ✓ Shutdown complete")
+  }
+
+  /**
+   * Generate unique instance ID
+   */
+  private generateInstanceId(): string {
+    const hostname = process.env.HOSTNAME || "local"
+    const timestamp = Date.now()
+    const random = Math.random().toString(36).substring(7)
+    return `minibob-${hostname}-${timestamp}-${random}`
+  }
+}