@metabob/minibob 0.1.2

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@metabob/minibob",
+  "version": "0.1.2",
+  "description": "Minimal vessel for the process-of-becoming",
+  "type": "module",
+  "main": "./dist/lib.js",
+  "types": "./dist/lib.d.ts",
+  "bin": {
+    "minibob": "./bin/minibob.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js"
+    },
+    "./cli": {
+      "import": "./index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "index.ts",
+    "src",
+    "templates",
+    "README.md",
+    "ARCHITECTURE.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "start": "bun run index.ts",
+    "dev": "bun --watch run index.ts",
+    "build": "bun build src/lib.ts --outdir dist --target node --format esm --sourcemap=external && tsc --project tsconfig.build.json --emitDeclarationOnly",
+    "prepublishOnly": "chmod +x bin/minibob.js && bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "vessel",
+    "activity",
+    "impulse",
+    "acp",
+    "agent"
+  ],
+  "devDependencies": {
+    "@types/bun": "^1.3.10"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}

package/src/acp-gossip.ts

@@ -0,0 +1,193 @@
+/**
+ * ACP Gossip Protocol
+ * 
+ * Implements DNS-based peer discovery and periodic health broadcasts
+ * for minibob vessels running in cluster mode.
+ * 
+ * Architecture:
+ * - DNS lookup discovers peer IPs via K8s headless service
+ * - Periodic health broadcasts to all peers
+ * - Peer state tracking (last seen, health status)
+ * 
+ * This enables vessel-to-vessel coordination and awareness.
+ */
+
+import { exec } from "child_process"
+import { promisify } from "util"
+
+const execAsync = promisify(exec)
+
+export interface PeerInfo {
+  ip: string
+  lastSeen: Date
+  healthy: boolean
+  capabilities?: string[]
+}
+
+export interface GossipConfig {
+  serviceName: string  // e.g., "minibob-cluster.default.svc.cluster.local"
+  broadcastInterval: number  // ms between health broadcasts
+  peerTimeout: number  // ms before marking peer as unhealthy
+  acpPort: number  // Port for ACP communication
+}
+
+export class ACPGossipProtocol {
+  private config: GossipConfig
+  private peers: Map<string, PeerInfo> = new Map()
+  private isRunning = false
+  private intervalId?: Timer
+
+  constructor(config: GossipConfig) {
+    this.config = config
+  }
+
+  /**
+   * Start gossip protocol
+   * 
+   * Begins periodic peer discovery and health broadcasts
+   */
+  async start(): Promise<void> {
+    if (this.isRunning) {
+      console.log("[ACP Gossip] Already running")
+      return
+    }
+
+    console.log("[ACP Gossip] Starting protocol")
+    console.log(`[ACP Gossip] Service: ${this.config.serviceName}`)
+    console.log(`[ACP Gossip] Broadcast interval: ${this.config.broadcastInterval}ms`)
+
+    this.isRunning = true
+
+    // Initial peer discovery
+    await this.discoverPeers()
+
+    // Start periodic health broadcasts
+    this.intervalId = setInterval(async () => {
+      await this.broadcastHealth()
+      await this.discoverPeers()
+      this.cleanupStalePeers()
+    }, this.config.broadcastInterval)
+
+    console.log("[ACP Gossip] Protocol started")
+  }
+
+  /**
+   * Stop gossip protocol
+   */
+  stop(): void {
+    if (!this.isRunning) {
+      return
+    }
+
+    console.log("[ACP Gossip] Stopping protocol")
+    
+    if (this.intervalId) {
+      clearInterval(this.intervalId)
+      this.intervalId = undefined
+    }
+
+    this.isRunning = false
+    console.log("[ACP Gossip] Protocol stopped")
+  }
+
+  /**
+   * Discover peers via DNS lookup
+   * 
+   * Uses getent/nslookup to resolve all IPs for the headless service
+   */
+  private async discoverPeers(): Promise<void> {
+    try {
+      // Try getent first (more reliable in K8s)
+      const { stdout } = await execAsync(`getent hosts ${this.config.serviceName}`)
+      const lines = stdout.trim().split('\n')
+      
+      for (const line of lines) {
+        const match = line.match(/^(\d+\.\d+\.\d+\.\d+)/)
+        if (match && match[1]) {
+          const ip = match[1]
+          
+          if (!this.peers.has(ip)) {
+            console.log(`[ACP Gossip] Discovered new peer: ${ip}`)
+            this.peers.set(ip, {
+              ip,
+              lastSeen: new Date(),
+              healthy: true,
+              capabilities: []
+            })
+          } else {
+            // Update last seen
+            const peer = this.peers.get(ip)
+            if (peer) {
+              peer.lastSeen = new Date()
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.log(`[ACP Gossip] Peer discovery failed: ${error}`)
+    }
+  }
+
+  /**
+   * Broadcast health to all peers
+   * 
+   * TODO: Implement actual health broadcast via HTTP POST to peer ACP endpoints
+   * For now, this is a placeholder that logs the intent
+   */
+  private async broadcastHealth(): Promise<void> {
+    const peerCount = this.peers.size
+    const healthyCount = Array.from(this.peers.values()).filter(p => p.healthy).length
+
+    console.log(`[ACP Gossip] Health broadcast: ${healthyCount}/${peerCount} peers healthy`)
+
+    // TODO: Implement actual HTTP POST to each peer's /acp/gossip endpoint
+    // For now, we just log that we would broadcast
+    for (const [ip, peer] of this.peers.entries()) {
+      // Future: POST http://${ip}:${this.config.acpPort}/acp/gossip
+      // with payload: { from: myIP, timestamp: Date.now(), capabilities: [...] }
+    }
+  }
+
+  /**
+   * Remove peers that haven't been seen recently
+   */
+  private cleanupStalePeers(): void {
+    const now = Date.now()
+    const staleThreshold = now - this.config.peerTimeout
+
+    for (const [ip, peer] of this.peers.entries()) {
+      if (peer.lastSeen.getTime() < staleThreshold) {
+        console.log(`[ACP Gossip] Peer ${ip} is stale, removing`)
+        this.peers.delete(ip)
+      }
+    }
+  }
+
+  /**
+   * Get current peer list
+   */
+  getPeers(): PeerInfo[] {
+    return Array.from(this.peers.values())
+  }
+
+  /**
+   * Get peer count
+   */
+  getPeerCount(): number {
+    return this.peers.size
+  }
+}
+
+/**
+ * Initialize ACP Gossip for minibob cluster
+ */
+export function initializeACPGossip(serviceName: string, acpPort: number): ACPGossipProtocol {
+  const config: GossipConfig = {
+    serviceName,
+    broadcastInterval: 30000,  // 30 seconds
+    peerTimeout: 90000,  // 90 seconds (3 missed broadcasts)
+    acpPort
+  }
+
+  return new ACPGossipProtocol(config)
+}

package/src/acp.ts

@@ -0,0 +1,362 @@
+/**
+ * minibob ACP Protocol Handler
+ * 
+ * Agent Client Protocol support for vessel-to-vessel communication.
+ * Supports both receiving delegated tasks and delegating to other vessels.
+ */
+
+import type {
+  ACPMessage,
+  ACPDelegateRequest,
+  ACPDelegateResponse,
+  Message,
+  ToolResult,
+} from "./types"
+import { createLLMClient, type LLMClient } from "./llm"
+import { createToolHandlers, getAllToolDefinitions } from "./tools"
+
+// =============================================================================
+// ACP SERVER (Receive delegated tasks)
+// =============================================================================
+
+export interface ACPServerConfig {
+  provider: "anthropic" | "openai"
+  apiKey: string
+  model: string
+  workingDirectory: string
+  systemPrompt?: string
+}
+
+/**
+ * ACP session handler for streaming connections
+ */
+export class ACPSession {
+  private llm: LLMClient
+  private toolHandlers: ReturnType<typeof createToolHandlers>
+  private config: ACPServerConfig
+  private sessionId: string
+  private messages: Message[] = []
+  private toolsUsed: string[] = []
+
+  constructor(config: ACPServerConfig, sessionId: string) {
+    this.config = config
+    this.sessionId = sessionId
+    this.llm = createLLMClient(config.provider, config.apiKey)
+    this.toolHandlers = createToolHandlers(config.workingDirectory)
+  }
+
+  /**
+   * Handle an incoming ACP message
+   */
+  async handleMessage(message: ACPMessage): Promise<ACPMessage[]> {
+    const responses: ACPMessage[] = []
+
+    switch (message.type) {
+      case "hello":
+        // Respond with our capabilities
+        responses.push({
+          type: "hello",
+          version: "1.0",
+          capabilities: ["prompt", "tool_call"],
+        })
+        break
+
+      case "prompt":
+        // Execute the prompt with tools
+        try {
+          this.messages = message.messages
+
+          // Add system prompt if not present
+          if (!this.messages.find((m) => m.role === "system")) {
+            this.messages.unshift({
+              role: "system",
+              content: this.config.systemPrompt ?? this.getDefaultSystemPrompt(),
+            })
+          }
+
+          const result = await this.llm.completeWithTools(
+            {
+              model: this.config.model,
+              messages: this.messages,
+              tools: message.tools ?? getAllToolDefinitions(),
+              maxTokens: 4096,
+            },
+            this.toolHandlers
+          )
+
+          this.toolsUsed = result.toolsUsed
+
+          responses.push({
+            type: "response",
+            sessionId: this.sessionId,
+            content: result.content,
+            finishReason: "stop",
+          })
+
+          responses.push({
+            type: "complete",
+            sessionId: this.sessionId,
+            metrics: {
+              duration: 0, // Would need timing
+              tokens: { input: result.usage.inputTokens, output: result.usage.outputTokens },
+            },
+          })
+        } catch (error) {
+          responses.push({
+            type: "error",
+            sessionId: this.sessionId,
+            error: error instanceof Error ? error.message : String(error),
+          })
+        }
+        break
+
+      case "tool_call":
+        // Execute a tool call
+        try {
+          const handler = this.toolHandlers[message.name]
+          let result: ToolResult
+
+          if (!handler) {
+            result = {
+              success: false,
+              error: `Unknown tool: ${message.name}`,
+            }
+          } else {
+            result = await handler(message.arguments)
+            this.toolsUsed.push(message.name)
+          }
+
+          responses.push({
+            type: "tool_result",
+            sessionId: this.sessionId,
+            toolCallId: message.toolCallId,
+            result,
+          })
+        } catch (error) {
+          responses.push({
+            type: "tool_result",
+            sessionId: this.sessionId,
+            toolCallId: message.toolCallId,
+            result: {
+              success: false,
+              error: error instanceof Error ? error.message : String(error),
+            },
+          })
+        }
+        break
+    }
+
+    return responses
+  }
+
+  /**
+   * Get tools used in this session
+   */
+  getToolsUsed(): string[] {
+    return [...new Set(this.toolsUsed)]
+  }
+
+  private getDefaultSystemPrompt(): string {
+    return `You are minibob, a minimal vessel for executing delegated tasks.
+You have access to tools for file operations, shell commands, and git.
+Execute the requested task efficiently and report the results.`
+  }
+}
+
+/**
+ * Handle WebSocket upgrade for ACP streaming
+ */
+export function createACPWebSocketHandler(config: ACPServerConfig) {
+  const sessions = new Map<string, ACPSession>()
+
+  return {
+    upgrade(request: Request): Response | undefined {
+      const url = new URL(request.url)
+      if (url.pathname !== "/acp/stream") {
+        return undefined
+      }
+
+      const sessionId = `acp_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+      const session = new ACPSession(config, sessionId)
+      sessions.set(sessionId, session)
+
+      return undefined // Let Bun handle the upgrade
+    },
+
+    websocket: {
+      async message(ws: WebSocket & { data: { sessionId?: string } }, message: string | Buffer) {
+        try {
+          const data = JSON.parse(typeof message === "string" ? message : message.toString()) as ACPMessage
+
+          // Get or create session
+          let sessionId = ws.data?.sessionId
+          if (!sessionId) {
+            sessionId = `acp_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+            ws.data = { sessionId }
+            sessions.set(sessionId, new ACPSession(config, sessionId))
+          }
+
+          const session = sessions.get(sessionId)
+          if (!session) {
+            ws.send(JSON.stringify({ type: "error", error: "Session not found" }))
+            return
+          }
+
+          const responses = await session.handleMessage(data)
+          for (const response of responses) {
+            ws.send(JSON.stringify(response))
+          }
+        } catch (error) {
+          ws.send(JSON.stringify({
+            type: "error",
+            error: error instanceof Error ? error.message : String(error),
+          }))
+        }
+      },
+
+      close(ws: WebSocket & { data: { sessionId?: string } }) {
+        if (ws.data?.sessionId) {
+          sessions.delete(ws.data.sessionId)
+        }
+      },
+    },
+  }
+}
+
+// =============================================================================
+// ACP CLIENT (Delegate to other vessels)
+// =============================================================================
+
+/**
+ * Delegate a task to another vessel via ACP
+ */
+export async function delegateTask(request: ACPDelegateRequest): Promise<ACPDelegateResponse> {
+  const startTime = Date.now()
+  const sessionId = `delegate_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+
+  try {
+    // Parse target URL
+    const targetUrl = parseTargetUrl(request.target)
+
+    // Connect via HTTP streaming or WebSocket
+    const response = await fetch(targetUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        type: "prompt",
+        sessionId,
+        messages: [
+          {
+            role: "user",
+            content: request.prompt,
+          },
+        ],
+      }),
+    })
+
+    if (!response.ok) {
+      throw new Error(`ACP request failed: ${response.status}`)
+    }
+
+    const result = (await response.json()) as {
+      content?: string
+      toolsUsed?: string[]
+      error?: string
+      metrics?: {
+        duration: number
+        tokens: { input: number; output: number }
+      }
+    }
+
+    return {
+      success: !result.error,
+      sessionId,
+      response: result.content,
+      toolsUsed: result.toolsUsed,
+      error: result.error,
+      metrics: {
+        duration: Date.now() - startTime,
+        tokens: result.metrics?.tokens ?? { input: 0, output: 0 },
+      },
+    }
+  } catch (error) {
+    return {
+      success: false,
+      sessionId,
+      error: error instanceof Error ? error.message : String(error),
+      metrics: {
+        duration: Date.now() - startTime,
+        tokens: { input: 0, output: 0 },
+      },
+    }
+  }
+}
+
+/**
+ * Parse ACP target URL
+ */
+function parseTargetUrl(target: string): string {
+  if (target.startsWith("http://") || target.startsWith("https://")) {
+    return target
+  }
+
+  if (target.startsWith("docker://")) {
+    const container = target.replace("docker://", "")
+    // For Docker, we'd need to resolve the container IP
+    // For now, assume localhost with a port mapping
+    return `http://${container}:8080/acp`
+  }
+
+  if (target.startsWith("tcp://")) {
+    const hostPort = target.replace("tcp://", "")
+    return `http://${hostPort}/acp`
+  }
+
+  throw new Error(`Unsupported ACP target: ${target}`)
+}
+
+// =============================================================================
+// HTTP ENDPOINT HANDLER
+// =============================================================================
+
+/**
+ * Handle ACP HTTP POST requests (non-streaming)
+ */
+export async function handleACPRequest(
+  config: ACPServerConfig,
+  request: Request
+): Promise<Response> {
+  const sessionId = `http_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+  const session = new ACPSession(config, sessionId)
+
+  try {
+    const message = (await request.json()) as ACPMessage
+    const responses = await session.handleMessage(message)
+
+    // For HTTP, we return the last meaningful response
+    const lastResponse = responses.find(
+      (r) => r.type === "response" || r.type === "error"
+    )
+
+    return new Response(JSON.stringify({
+      success: lastResponse?.type === "response",
+      content: lastResponse?.type === "response" ? (lastResponse as { content: string }).content : undefined,
+      error: lastResponse?.type === "error" ? (lastResponse as { error: string }).error : undefined,
+      toolsUsed: session.getToolsUsed(),
+      sessionId,
+    }), {
+      headers: { "Content-Type": "application/json" },
+    })
+  } catch (error) {
+    return new Response(JSON.stringify({
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+      sessionId,
+    }), {
+      status: 500,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+}