@metabob/minibob 0.1.2

package/src/mcp.ts

@@ -0,0 +1,747 @@
+/**
+ * minibob MCP Client
+ * 
+ * Integrates with Metabob backend for:
+ * - Activity template fetching
+ * - Execution metrics reporting
+ * - Impulse storage/retrieval
+ * - Learning and optimization
+ */
+
+import type { ActivityTemplate, ActivityExecution, Impulse } from "./types"
+
+// Impulse Relevance Metric (Phase 1.8)
+export interface ImpulseRelevanceMetric {
+  impulse_id: string
+  activity_variant_id: string
+  task_id?: string
+  times_loaded: number
+  times_execution_succeeded: number
+  times_execution_failed: number
+  times_not_loaded_succeeded: number
+  times_not_loaded_failed: number
+  relevance_score: number
+  irrelevance_score: number
+  avg_content_size_tokens: number
+  typical_pointer_type?: string
+  created_at: string
+  updated_at: string
+}
+
+// =============================================================================
+// MCP CLIENT CONFIGURATION
+// =============================================================================
+
+export interface MCPConfig {
+  endpoint: string
+  apiKey?: string
+  timeout?: number
+}
+
+// =============================================================================
+// MCP CLIENT
+// =============================================================================
+
+export class MCPClient {
+  private endpoint: string
+  private apiKey?: string
+  private timeout: number
+
+  constructor(config: MCPConfig) {
+    this.endpoint = config.endpoint.replace(/\/$/, "") // Remove trailing slash
+    this.apiKey = config.apiKey
+    this.timeout = config.timeout ?? 30000
+  }
+
+  /**
+   * Fetch activity template by ID
+   */
+  async getActivityTemplate(templateId: string): Promise<ActivityTemplate | null> {
+    try {
+      const response = await this.request("GET", `/v2/activities/templates/${templateId}`)
+      
+      if (!response.ok) {
+        if (response.status === 404) return null
+        throw new Error(`Failed to fetch template: ${response.status} ${response.statusText}`)
+      }
+
+      const data = await response.json() as any
+      const raw = data.template ?? data
+      
+      // Transform API schema to minibob schema
+      return {
+        id: raw.variant_id || raw.id,
+        name: raw.variant_name || raw.name,
+        description: raw.description,
+        category: raw.category,
+        tasks: raw.task_steps || raw.tasks || [],
+        variables: raw.variables || [],
+        contextRequirements: raw.contextRequirements
+      } as ActivityTemplate
+    } catch (error) {
+      console.error(`[MCP] Error fetching template ${templateId}:`, error)
+      return null
+    }
+  }
+
+  /**
+   * Search activity templates
+   */
+  async searchActivityTemplates(query?: {
+    category?: string
+    limit?: number
+  }): Promise<Array<{ id: string; name: string; category: string; successRate?: number }>> {
+    try {
+      const params = new URLSearchParams()
+      if (query?.category) params.set("category", query.category)
+      if (query?.limit) params.set("limit", String(query.limit))
+
+      const url = `/v2/activities/templates?${params.toString()}`
+      const response = await this.request("GET", url)
+
+      if (!response.ok) {
+        throw new Error(`Failed to search templates: ${response.status}`)
+      }
+
+      const data = await response.json() as { templates?: Array<{ id: string; name: string; category: string; successRate?: number }> }
+      return data.templates ?? []
+    } catch (error) {
+      console.error("[MCP] Error searching templates:", error)
+      return []
+    }
+  }
+
+  /**
+   * Recommend activities for a goal using Thompson Sampling
+   * 
+   * This is the key method for goal-driven execution.
+   * The backend uses Thompson Sampling with historical execution data
+   * to recommend the best activities for achieving a goal.
+   * 
+   * @param taskDescription - User's goal description
+   * @param category - Optional category filter
+   * @param loadedImpulses - IDs of currently loaded impulses for context
+   * @param limit - Max number of recommendations
+   * @returns Array of activity recommendations with selection metadata
+   */
+  async recommendActivities(
+    taskDescription: string,
+    category?: string,
+    loadedImpulses?: string[],
+    limit: number = 3
+  ): Promise<Array<{ template_id: string; selection_metadata: any }>> {
+    try {
+      // Call backend recommendation API using Thompson Sampling
+      const payload = {
+        task_description: taskDescription,
+        category,
+        loaded_impulses: loadedImpulses || [],
+        limit,
+      }
+
+      const response = await this.request("POST", "/v2/activities/recommend", payload)
+
+      if (!response.ok) {
+        console.warn(`[MCP] Recommendation failed: ${response.status}`)
+        return []
+      }
+
+      const data = await response.json() as { recommendations?: Array<{ template_id: string; selection_metadata: any }> }
+      return data.recommendations ?? []
+    } catch (error) {
+      console.error("[MCP] Error getting recommendations:", error)
+      return []
+    }
+  }
+
+  /**
+   * Register activity template variant
+   * Called when executing a template loaded from local JSON file
+   */
+  async registerTemplate(template: ActivityTemplate): Promise<boolean> {
+    try {
+      // Transform tasks to match backend schema (add required fields)
+      const task_steps = template.tasks.map(task => ({
+        id: task.id,
+        subagent: "general-purpose", // Default subagent
+        description: task.description,
+        dependencies: [], // No dependencies by default
+        prompt: task.prompt,
+        validation: task.validation,
+        retry: task.retry
+      }))
+
+      const payload: Record<string, any> = {
+        variant_id: template.id,
+        activity_id: template.id, // For now, variant_id === activity_id
+        variant_name: template.name,
+        description: template.description,
+        category: template.category,
+        task_steps,
+        scope: "global",
+      }
+
+      // Omit null/undefined fields (SurrealDB doesn't accept null, needs NONE or omitted)
+      Object.keys(payload).forEach(key => {
+        if (payload[key] === null || payload[key] === undefined) {
+          delete payload[key]
+        }
+      })
+
+      const response = await this.request("POST", "/v2/activities/templates", payload)
+
+      if (!response.ok) {
+        // 409 Conflict means template already exists - that's fine
+        if (response.status === 409) {
+          console.log(`[MCP] Template ${template.id} already registered`)
+          return true
+        }
+        
+        const errorText = await response.text()
+        console.warn(`[MCP] Failed to register template: ${response.status} - ${errorText}`)
+        return false
+      }
+
+      console.log(`[MCP] ✓ Template ${template.id} registered successfully`)
+      return true
+    } catch (error) {
+      console.error("[MCP] Error registering template:", error)
+      return false
+    }
+  }
+
+  /**
+   * Report activity execution results
+   */
+  async reportExecution(execution: ActivityExecution): Promise<boolean> {
+    try {
+      // Determine first failed task if execution failed
+      const failedTask = execution.taskResults.find((t) => t.status === "failed")
+      
+      const payload: Record<string, any> = {
+        variant_id: execution.templateId,
+        success: execution.status === "completed",
+        duration_ms: execution.metrics?.duration || 0,
+        cost: execution.metrics?.cost || 0,
+        tokens: {
+          input: execution.metrics?.totalTokens?.input || 0,
+          output: execution.metrics?.totalTokens?.output || 0,
+          cache: 0, // MiniBob doesn't track cache tokens yet
+        },
+      }
+
+      // Only include optional fields if they have values (SurrealDB doesn't accept null)
+      if (failedTask?.error) {
+        payload.error_message = failedTask.error
+      }
+      if (failedTask) {
+        payload.error_type = "task_execution_error"
+        payload.failed_task_id = failedTask.taskId
+      }
+      // Omit empty arrays - SurrealDB will use default [] if field allows it
+      if (execution.impulses && execution.impulses.length > 0) {
+        payload.impulses_used = execution.impulses.map(imp => imp.id)
+      }
+
+      const response = await this.request("POST", "/v2/activities/executions", payload)
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        console.warn(`[MCP] Failed to report execution: ${response.status} - ${errorText}`)
+        return false
+      }
+
+      return true
+    } catch (error) {
+      console.error("[MCP] Error reporting execution:", error)
+      return false
+    }
+  }
+
+  /**
+   * Record activity composition event (when one activity calls another)
+   * 
+   * This enables learning of composition patterns:
+   * - Which activities typically work together
+   * - Success rates of different compositions
+   * - Optimal activity sequences
+   */
+  async recordComposition(params: {
+    parentActivityId: string
+    childActivityId: string
+    executionId: string
+    goalContext?: string
+    success: boolean
+  }): Promise<boolean> {
+    try {
+      const payload = {
+        parent_activity_id: params.parentActivityId,
+        child_activity_id: params.childActivityId,
+        execution_id: params.executionId,
+        goal_context: params.goalContext,
+        success: params.success,
+      }
+
+      const response = await this.request("POST", "/v2/activities/composition", payload)
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        console.warn(`[MCP] Failed to record composition: ${response.status} - ${errorText}`)
+        return false
+      }
+
+      const data = await response.json() as { success: boolean; edge?: any }
+      if (data.edge) {
+        console.log(`[MCP] Composition recorded: ${params.parentActivityId} → ${params.childActivityId} (weight: ${data.edge.weight})`)
+      }
+
+      return true
+    } catch (error) {
+      console.error("[MCP] Error recording composition:", error)
+      return false
+    }
+  }
+
+  /**
+   * Record tool usage during activity execution
+   * 
+   * This enables learning of tool usage patterns:
+   * - Which tools are required vs optional for each activity
+   * - Success correlation between tool usage and outcomes
+   * - Pre-flight checks (does vessel have required tools?)
+   */
+  async recordToolUsage(params: {
+    toolName: string
+    activityVariantId: string
+    taskId?: string
+    executionId: string
+    toolSucceeded: boolean
+    activitySucceeded: boolean
+    paramsComplexity?: number
+  }): Promise<boolean> {
+    try {
+      const payload = {
+        tool_name: params.toolName,
+        activity_variant_id: params.activityVariantId,
+        task_id: params.taskId,
+        execution_id: params.executionId,
+        tool_succeeded: params.toolSucceeded,
+        activity_succeeded: params.activitySucceeded,
+        params_complexity: params.paramsComplexity,
+      }
+
+      const response = await this.request("POST", "/v2/activities/tool-usage", payload)
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        console.warn(`[MCP] Failed to record tool usage: ${response.status} - ${errorText}`)
+        return false
+      }
+
+      console.log(`[MCP] Tool usage recorded: ${params.toolName} in ${params.activityVariantId}`)
+      return true
+    } catch (error) {
+      console.error("[MCP] Error recording tool usage:", error)
+      return false
+    }
+  }
+
+  /**
+   * Record execution sequence for session-level learning
+   * 
+   * This enables learning:
+   * - Which activities typically run together
+   * - Successful sequences for achieving goals
+   * - Optimal sequence length and patterns
+   */
+  async recordExecutionSequence(params: {
+    sessionId: string
+    goalContext?: string
+    sequence: Array<{
+      activityId: string
+      executionId: string
+      order: number
+      triggerType: 'goal' | 'nested' | 'boredom' | 'manual'
+      parentExecutionId?: string
+      success: boolean
+      durationMs: number
+      costUsd: number
+    }>
+    outcome: 'success' | 'partial' | 'failure'
+  }): Promise<boolean> {
+    try {
+      const payload = {
+        session_id: params.sessionId,
+        goal_context: params.goalContext,
+        sequence: params.sequence.map(item => ({
+          activity_id: item.activityId,
+          execution_id: item.executionId,
+          order: item.order,
+          trigger_type: item.triggerType,
+          parent_execution_id: item.parentExecutionId,
+          success: item.success,
+          duration_ms: item.durationMs,
+          cost_usd: item.costUsd,
+        })),
+        outcome: params.outcome,
+      }
+
+      const response = await this.request("POST", "/v2/activities/execution-sequences", payload)
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        console.warn(`[MCP] Failed to record execution sequence: ${response.status} - ${errorText}`)
+        return false
+      }
+
+      console.log(`[MCP] Execution sequence recorded: ${params.sequence.length} activities (${params.outcome})`)
+      return true
+    } catch (error) {
+      console.error("[MCP] Error recording execution sequence:", error)
+      return false
+    }
+  }
+
+  /**
+   * Store impulse in backend
+   */
+  async storeImpulse(impulse: Impulse): Promise<boolean> {
+    try {
+      // Map MiniBob impulse format to API schema
+      const payload = {
+        impulse_id: impulse.id,
+        project_id: "minibob-default", // Default project for internal impulses
+        impulse_data: {
+          id: impulse.id, // Required by ImpulseDataSchema
+          type: impulse.pointer?.type ?? "memo",
+          pointer: impulse.pointer ?? { type: "memo", content: impulse.content ?? "" },
+          budget: impulse.budget ?? 4000,
+          priority: typeof impulse.priority === "string" ?
+            ({ critical: 1, high: 2, medium: 3, low: 4 }[impulse.priority] ?? 3) :
+            (impulse.priority ?? 3),
+          metadata: {
+            tags: impulse.tags,
+            content: impulse.content,
+          },
+        },
+      }
+
+      const response = await this.request("POST", "/v2/impulses", payload)
+
+      if (!response.ok) {
+        console.warn(`[MCP] Failed to store impulse: ${response.status}`)
+        return false
+      }
+
+      return true
+    } catch (error) {
+      console.error("[MCP] Error storing impulse:", error)
+      return false
+    }
+  }
+
+  /**
+   * Retrieve impulse from backend
+   */
+  async retrieveImpulse(impulseId: string): Promise<Impulse | null> {
+    try {
+      const response = await this.request("GET", `/v2/impulses/${impulseId}`)
+
+      if (!response.ok) {
+        if (response.status === 404) return null
+        throw new Error(`Failed to retrieve impulse: ${response.status}`)
+      }
+
+      const data = await response.json() as { impulse?: Impulse }
+      return data.impulse ?? null
+    } catch (error) {
+      console.error(`[MCP] Error retrieving impulse ${impulseId}:`, error)
+      return null
+    }
+  }
+
+  /**
+   * Track impulse usage for learning
+   */
+  async trackImpulseUsage(impulseId: string, context: {
+    activityId: string
+    taskId: string
+    tokensUsed: number
+  }): Promise<boolean> {
+    try {
+      const response = await this.request("POST", `/v2/impulses/${impulseId}/usage`, context)
+
+      if (!response.ok) {
+        console.warn(`[MCP] Failed to track impulse usage: ${response.status}`)
+        return false
+      }
+
+      return true
+    } catch (error) {
+      console.error("[MCP] Error tracking impulse usage:", error)
+      return false
+    }
+  }
+
+  /**
+   * Query impulse relevance metrics for an activity (Phase 1.8)
+   */
+  async queryImpulseRelevance(params: {
+    activityVariantId: string
+    impulseIds?: string[]
+  }): Promise<ImpulseRelevanceMetric[]> {
+    try {
+      const queryParams = new URLSearchParams({
+        activity_variant_id: params.activityVariantId,
+      })
+      
+      if (params.impulseIds && params.impulseIds.length > 0) {
+        for (const id of params.impulseIds) {
+          queryParams.append('impulse_id', id)
+        }
+      }
+      
+      const response = await this.request(
+        "GET",
+        `/v2/activities/impulse-relevance?${queryParams.toString()}`
+      )
+      
+      if (!response.ok) {
+        if (response.status === 404) return []
+        throw new Error(`Failed to query impulse relevance: ${response.status}`)
+      }
+      
+      const data = await response.json() as any
+      return data.metrics || []
+    } catch (error) {
+      console.error("[MCP] Error querying impulse relevance:", error)
+      return []
+    }
+  }
+
+  /**
+   * Record impulse relevance for learning (Phase 1.8)
+   */
+  async recordImpulseRelevance(params: {
+    impulseId: string
+    activityVariantId: string
+    taskId?: string
+    wasLoaded: boolean
+    executionSucceeded: boolean
+    contentSizeTokens?: number
+    pointerType?: string
+  }): Promise<boolean> {
+    try {
+      const response = await this.request("POST", "/v2/activities/impulse-relevance", {
+        impulse_id: params.impulseId,
+        activity_variant_id: params.activityVariantId,
+        task_id: params.taskId,
+        was_loaded: params.wasLoaded,
+        execution_succeeded: params.executionSucceeded,
+        content_size_tokens: params.contentSizeTokens,
+        pointer_type: params.pointerType,
+      })
+      
+      if (!response.ok) {
+        console.warn(`[MCP] Failed to record impulse relevance: ${response.status}`)
+        return false
+      }
+      
+      return true
+    } catch (error) {
+      console.error("[MCP] Error recording impulse relevance:", error)
+      return false
+    }
+  }
+
+  /**
+   * Resolve an impulse pointer via backend (Phase 1.8+)
+   * 
+   * Architecture: MiniBob delegates all non-local impulse resolution to backend.
+   * This allows backend to introduce new pointer types without minibob changes.
+   */
+  async resolveImpulse(pointer: any): Promise<string> {
+    try {
+      const response = await this.request("POST", "/v2/impulses/resolve", {
+        pointer: pointer,
+      })
+
+      if (!response.ok) {
+        throw new Error(`Failed to resolve impulse: ${response.status} ${response.statusText}`)
+      }
+
+      const data = await response.json() as { content?: string }
+      if (!data.content) {
+        throw new Error("Backend returned no content for impulse resolution")
+      }
+
+      return data.content
+    } catch (error) {
+      throw new Error(
+        `MCP impulse resolution failed: ${error instanceof Error ? error.message : String(error)}`
+      )
+    }
+  }
+
+  /**
+   * Store execution trace in backend (Phase 1.8+)
+   * 
+   * Enables execution traces to be referenced as impulses in future activities.
+   */
+  async storeExecutionTrace(execution: ActivityExecution): Promise<boolean> {
+    try {
+      // Map MiniBob's status to backend's expected values
+      let status: 'success' | 'failure' | 'partial' = 'failure'
+      if (execution.status === 'completed') {
+        status = 'success'
+      } else if (execution.status === 'failed') {
+        status = 'failure'
+      } else if (execution.status === 'executing') {
+        status = 'partial'
+      }
+
+      const response = await this.request("POST", "/v2/activities/execution-traces", {
+        execution_id: execution.id,
+        template_id: execution.templateId,
+        activity_id: execution.templateId, // Backend expects activity_id
+        status: status, // Map to backend's enum values
+        success: execution.status === "completed",
+        duration_ms: execution.metrics?.duration || 0,
+        cost_usd: execution.metrics?.cost || 0,
+        tokens: {
+          input: execution.metrics?.totalTokens?.input || 0,
+          output: execution.metrics?.totalTokens?.output || 0,
+          cache: 0, // MiniBob doesn't track cache tokens yet
+        },
+        // Include execution trace with all collected data
+        execution_trace: execution.executionTrace || {
+          tasks: [],
+          impulsesCreated: [],
+          filesModified: [],
+        },
+        // Include impulse IDs used
+        impulses_used: execution.impulses?.map(i => i.id) || [],
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        console.warn(`[MCP] Failed to store execution trace: ${response.status} - ${errorText}`)
+        return false
+      }
+
+      console.log(`[MCP] ✓ Execution trace stored: ${execution.id}`)
+      return true
+    } catch (error) {
+      console.error("[MCP] Error storing execution trace:", error)
+      return false
+    }
+  }
+
+  /**
+   * Register minibob vessel with backend
+   */
+  async registerVessel(manifest: {
+    id: string
+    name: string
+    version: string
+    capabilities: string[]
+    endpoint: string
+  }): Promise<boolean> {
+    try {
+      const response = await this.request("POST", "/v2/vessels/register", manifest)
+
+      if (!response.ok) {
+        console.warn(`[MCP] Failed to register vessel: ${response.status}`)
+        return false
+      }
+
+      console.log("[MCP] Vessel registered successfully")
+      return true
+    } catch (error) {
+      console.error("[MCP] Error registering vessel:", error)
+      return false
+    }
+  }
+
+  /**
+   * Make HTTP request to MCP backend
+   */
+  private async request(
+    method: "GET" | "POST" | "PUT" | "DELETE",
+    path: string,
+    body?: unknown
+  ): Promise<Response> {
+    const url = `${this.endpoint}${path}`
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    }
+
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`
+      // Also send internal service key for impulse endpoints
+      headers["X-Internal-Api-Key"] = this.apiKey
+    }
+
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout)
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      })
+
+      return response
+    } finally {
+      clearTimeout(timeoutId)
+    }
+  }
+}
+
+// =============================================================================
+// SINGLETON MCP CLIENT
+// =============================================================================
+
+let mcpClient: MCPClient | null = null
+
+/**
+ * Initialize MCP client with backend health check (singleton)
+ * 
+ * Checks backend availability before initialization.
+ * Returns null if backend is unreachable, allowing graceful fallback to local mode.
+ * 
+ * @param config MCP configuration
+ * @param skipHealthCheck Skip health check (for testing)
+ * @returns MCPClient instance or null if backend unavailable
+ */
+export async function initializeMCP(config: MCPConfig, skipHealthCheck = false): Promise<MCPClient | null> {
+  if (!skipHealthCheck) {
+    const { checkBackendHealth } = await import("./environment")
+    const healthy = await checkBackendHealth(config.endpoint)
+    
+    if (!healthy) {
+      console.warn("[MCP] Backend unavailable, using local mode")
+      return null
+    }
+  }
+  
+  mcpClient = new MCPClient(config)
+  console.log("[MCP] ✓ Client initialized")
+  return mcpClient
+}
+
+/**
+ * Get MCP client instance
+ */
+export function getMCPClient(): MCPClient | null {
+  return mcpClient
+}
+
+/**
+ * Check if MCP is enabled
+ */
+export function isMCPEnabled(): boolean {
+  return mcpClient !== null
+}