@metabob/minibob 0.1.2

package/src/vessel-registry.ts

@@ -0,0 +1,621 @@
+/**
+ * Vessel Registry
+ *
+ * Tracks codebases that have been burrowed into and converted to vessels.
+ * Each vessel has:
+ * - Unique identity
+ * - Learned activities (from execution traces)
+ * - Defined impulses (context data)
+ * - Registered hooks (lifecycle events)
+ * - Provided tools (capabilities)
+ * - Composition graph (how activities relate)
+ *
+ * The registry enables:
+ * - Discovery: Find vessels available for use
+ * - Selection: Choose which vessel's activities to use
+ * - Learning: Track activity performance per vessel
+ * - Development: Debug and evolve vessel capabilities
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join, resolve } from 'path'
+
+// Backend API endpoint for vessel registry sync
+const BACKEND_ENDPOINT = process.env.MINIBOB_MCP_ENDPOINT || 'http://api.minibob.local'
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface VesselIdentity {
+  /** Unique vessel ID */
+  id: string
+  /** Human-readable name */
+  name: string
+  /** Path to the codebase */
+  path: string
+  /** When the vessel was created (burrowed into) */
+  createdAt: number
+  /** Last time the vessel was active */
+  lastActiveAt: number
+  /** Version (from package.json or inferred) */
+  version?: string
+  /** Description */
+  description?: string
+}
+
+export interface VesselActivity {
+  /** Activity ID */
+  id: string
+  /** Activity name */
+  name: string
+  /** How the activity was created */
+  origin: 'extracted' | 'defined' | 'improvised'
+  /** Source location in code (if known) */
+  sourceLocation?: {
+    file: string
+    line: number
+    function?: string
+  }
+  /** Execution count */
+  executions: number
+  /** Success rate */
+  successRate: number
+  /** Average duration (ms) */
+  avgDuration: number
+  /** Thompson Sampling parameters */
+  thompson: {
+    alpha: number
+    beta: number
+  }
+}
+
+export interface VesselImpulse {
+  /** Impulse ID */
+  id: string
+  /** Impulse type */
+  type: 'config' | 'context' | 'feature-flag' | 'mock' | 'override'
+  /** Description */
+  description?: string
+  /** Default value */
+  defaultValue?: unknown
+  /** Current value (if set) */
+  currentValue?: unknown
+}
+
+export interface VesselHook {
+  /** Hook ID */
+  id: string
+  /** Hook type */
+  type: 'startup' | 'shutdown' | 'error' | 'activity.before' | 'activity.after' | 'custom'
+  /** Handler location */
+  handler: string
+  /** Whether the hook is enabled */
+  enabled: boolean
+}
+
+export interface VesselTool {
+  /** Tool name */
+  name: string
+  /** Tool description */
+  description: string
+  /** Input schema */
+  inputSchema?: Record<string, unknown>
+  /** How to invoke the tool */
+  invocation: {
+    type: 'function' | 'command' | 'http' | 'mcp'
+    target: string
+  }
+}
+
+export interface VesselComposition {
+  /** Activity compositions recorded */
+  compositions: Array<{
+    parent: string
+    child: string
+    count: number
+    successRate: number
+  }>
+  /** Inferred activity sequences */
+  sequences: Array<{
+    activities: string[]
+    count: number
+    avgDuration: number
+  }>
+}
+
+export interface Vessel extends VesselIdentity {
+  /** Activities available in this vessel */
+  activities: VesselActivity[]
+  /** Impulses defined for this vessel */
+  impulses: VesselImpulse[]
+  /** Hooks registered for this vessel */
+  hooks: VesselHook[]
+  /** Tools provided by this vessel */
+  tools: VesselTool[]
+  /** Activity composition data */
+  composition: VesselComposition
+  /** Runtime mapping data */
+  mapping: RuntimeMapping
+}
+
+// =============================================================================
+// RUNTIME MAPPING
+// =============================================================================
+
+/**
+ * Maps runtime behavior to source code and intent
+ */
+export interface RuntimeMapping {
+  /** Function call → source location */
+  functionMap: Map<string, SourceLocation>
+  /** Source location → inferred intent */
+  intentMap: Map<string, InferredIntent>
+  /** Execution patterns → activities */
+  patternMap: Map<string, string>
+}
+
+export interface SourceLocation {
+  file: string
+  line: number
+  column?: number
+  functionName?: string
+  className?: string
+  moduleName?: string
+}
+
+export interface InferredIntent {
+  /** What the code does */
+  purpose: string
+  /** Why it exists */
+  rationale?: string
+  /** Expected inputs */
+  inputs?: string[]
+  /** Expected outputs */
+  outputs?: string[]
+  /** Constraints */
+  constraints?: string[]
+  /** Success criteria */
+  successCriteria?: string[]
+  /** Confidence in this inference */
+  confidence: number
+  /** How the intent was inferred */
+  source: 'function-name' | 'comment' | 'docstring' | 'variable-names' | 'data-flow' | 'llm-analysis'
+}
+
+// =============================================================================
+// REGISTRY STORAGE
+// =============================================================================
+
+const REGISTRY_DIR = '.minibob/registry'
+const VESSELS_FILE = 'vessels.json'
+
+interface RegistryData {
+  version: string
+  vessels: Record<string, Omit<Vessel, 'mapping'> & { mapping?: any }>
+  lastUpdated: number
+}
+
+function getRegistryPath(): string {
+  // Use home directory for global registry
+  const home = process.env.HOME || process.env.USERPROFILE || '.'
+  return join(home, REGISTRY_DIR)
+}
+
+function ensureRegistryDir(): void {
+  const dir = getRegistryPath()
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+}
+
+function loadRegistry(): RegistryData {
+  ensureRegistryDir()
+  const filePath = join(getRegistryPath(), VESSELS_FILE)
+
+  if (!existsSync(filePath)) {
+    return {
+      version: '1.0.0',
+      vessels: {},
+      lastUpdated: Date.now(),
+    }
+  }
+
+  try {
+    const data = readFileSync(filePath, 'utf-8')
+    return JSON.parse(data)
+  } catch (error) {
+    console.warn('[VesselRegistry] Failed to load registry, starting fresh')
+    return {
+      version: '1.0.0',
+      vessels: {},
+      lastUpdated: Date.now(),
+    }
+  }
+}
+
+function saveRegistry(data: RegistryData): void {
+  ensureRegistryDir()
+  const filePath = join(getRegistryPath(), VESSELS_FILE)
+  data.lastUpdated = Date.now()
+  writeFileSync(filePath, JSON.stringify(data, null, 2))
+}
+
+// =============================================================================
+// BACKEND SYNC
+// =============================================================================
+
+/**
+ * Sync vessel registration with backend
+ */
+async function syncVesselToBackend(vessel: Vessel, functionMappings?: Array<{
+  functionName: string
+  file: string
+  line: number
+  className?: string
+  intent?: InferredIntent
+}>): Promise<boolean> {
+  try {
+    const payload = {
+      vessel_id: vessel.id,
+      name: vessel.name,
+      path: vessel.path,
+      description: vessel.description,
+      version: vessel.version,
+      framework: (vessel as any).framework,
+      activities: vessel.activities,
+      impulses: vessel.impulses,
+      hooks: vessel.hooks,
+      tools: vessel.tools,
+      composition: vessel.composition,
+      functionMappings: functionMappings || [],
+      created_at: new Date(vessel.createdAt).toISOString(),
+    }
+
+    const response = await fetch(`${BACKEND_ENDPOINT}/v2/vessels/codebase/register`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      console.warn(`[VesselRegistry] Backend sync failed: ${response.status} ${text}`)
+      return false
+    }
+
+    const result = await response.json()
+    console.log(`[VesselRegistry] Synced to backend: ${vessel.name} (${result.stored?.functionMappings || 0} mappings)`)
+    return true
+
+  } catch (error) {
+    console.warn(`[VesselRegistry] Backend sync failed:`, error instanceof Error ? error.message : error)
+    return false
+  }
+}
+
+/**
+ * Record activity execution to backend (for Thompson Sampling)
+ */
+export async function recordActivityExecution(
+  vesselId: string,
+  activityId: string,
+  success: boolean,
+  durationMs: number
+): Promise<boolean> {
+  try {
+    const response = await fetch(
+      `${BACKEND_ENDPOINT}/v2/vessels/registry/${vesselId}/activities/${activityId}/execution`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ success, duration_ms: durationMs }),
+      }
+    )
+
+    if (!response.ok) {
+      console.warn(`[VesselRegistry] Failed to record execution: ${response.status}`)
+      return false
+    }
+
+    return true
+  } catch (error) {
+    console.warn(`[VesselRegistry] Failed to record execution:`, error instanceof Error ? error.message : error)
+    return false
+  }
+}
+
+// =============================================================================
+// REGISTRY OPERATIONS
+// =============================================================================
+
+/**
+ * Register a new vessel (after burrowing into a codebase)
+ */
+export function registerVessel(vessel: Omit<Vessel, 'id' | 'createdAt' | 'lastActiveAt' | 'mapping'>): Vessel {
+  const registry = loadRegistry()
+
+  // Generate ID from path
+  const normalizedPath = resolve(vessel.path)
+  const id = `vessel_${Buffer.from(normalizedPath).toString('base64url').slice(0, 16)}`
+
+  // Check if already registered
+  if (registry.vessels[id]) {
+    console.log(`[VesselRegistry] Vessel already registered: ${id}`)
+    return registry.vessels[id] as any
+  }
+
+  const now = Date.now()
+  const fullVessel: Vessel = {
+    ...vessel,
+    id,
+    createdAt: now,
+    lastActiveAt: now,
+    mapping: {
+      functionMap: new Map(),
+      intentMap: new Map(),
+      patternMap: new Map(),
+    },
+  }
+
+  // Store without Map objects (they don't serialize)
+  registry.vessels[id] = {
+    ...fullVessel,
+    mapping: {
+      functionMap: {},
+      intentMap: {},
+      patternMap: {},
+    },
+  }
+
+  saveRegistry(registry)
+  console.log(`[VesselRegistry] Registered vessel: ${vessel.name} (${id})`)
+
+  return fullVessel
+}
+
+/**
+ * Get a vessel by ID
+ */
+export function getVessel(id: string): Vessel | null {
+  const registry = loadRegistry()
+  const vessel = registry.vessels[id]
+
+  if (!vessel) return null
+
+  // Reconstitute Map objects
+  return {
+    ...vessel,
+    mapping: {
+      functionMap: new Map(Object.entries(vessel.mapping?.functionMap || {})),
+      intentMap: new Map(Object.entries(vessel.mapping?.intentMap || {})),
+      patternMap: new Map(Object.entries(vessel.mapping?.patternMap || {})),
+    },
+  } as Vessel
+}
+
+/**
+ * Get vessel by path
+ */
+export function getVesselByPath(path: string): Vessel | null {
+  const normalizedPath = resolve(path)
+  const registry = loadRegistry()
+
+  for (const vessel of Object.values(registry.vessels)) {
+    if (resolve(vessel.path) === normalizedPath) {
+      return getVessel(vessel.id)
+    }
+  }
+
+  return null
+}
+
+/**
+ * List all registered vessels
+ */
+export function listVessels(): VesselIdentity[] {
+  const registry = loadRegistry()
+  return Object.values(registry.vessels).map(v => ({
+    id: v.id,
+    name: v.name,
+    path: v.path,
+    createdAt: v.createdAt,
+    lastActiveAt: v.lastActiveAt,
+    version: v.version,
+    description: v.description,
+  }))
+}
+
+/**
+ * Update vessel activity data
+ */
+export function updateVesselActivities(vesselId: string, activities: VesselActivity[]): void {
+  const registry = loadRegistry()
+
+  if (!registry.vessels[vesselId]) {
+    throw new Error(`Vessel not found: ${vesselId}`)
+  }
+
+  registry.vessels[vesselId].activities = activities
+  registry.vessels[vesselId].lastActiveAt = Date.now()
+  saveRegistry(registry)
+}
+
+/**
+ * Add an activity to a vessel
+ */
+export function addVesselActivity(vesselId: string, activity: VesselActivity): void {
+  const registry = loadRegistry()
+
+  if (!registry.vessels[vesselId]) {
+    throw new Error(`Vessel not found: ${vesselId}`)
+  }
+
+  const existing = registry.vessels[vesselId].activities.findIndex(a => a.id === activity.id)
+  if (existing >= 0) {
+    registry.vessels[vesselId].activities[existing] = activity
+  } else {
+    registry.vessels[vesselId].activities.push(activity)
+  }
+
+  registry.vessels[vesselId].lastActiveAt = Date.now()
+  saveRegistry(registry)
+}
+
+/**
+ * Update runtime mapping for a vessel
+ */
+export function updateVesselMapping(
+  vesselId: string,
+  type: 'function' | 'intent' | 'pattern',
+  key: string,
+  value: SourceLocation | InferredIntent | string
+): void {
+  const registry = loadRegistry()
+
+  if (!registry.vessels[vesselId]) {
+    throw new Error(`Vessel not found: ${vesselId}`)
+  }
+
+  if (!registry.vessels[vesselId].mapping) {
+    registry.vessels[vesselId].mapping = {
+      functionMap: {},
+      intentMap: {},
+      patternMap: {},
+    }
+  }
+
+  switch (type) {
+    case 'function':
+      registry.vessels[vesselId].mapping.functionMap[key] = value as SourceLocation
+      break
+    case 'intent':
+      registry.vessels[vesselId].mapping.intentMap[key] = value as InferredIntent
+      break
+    case 'pattern':
+      registry.vessels[vesselId].mapping.patternMap[key] = value as string
+      break
+  }
+
+  saveRegistry(registry)
+}
+
+/**
+ * Record activity composition for a vessel
+ */
+export function recordVesselComposition(
+  vesselId: string,
+  parent: string,
+  child: string,
+  success: boolean
+): void {
+  const registry = loadRegistry()
+
+  if (!registry.vessels[vesselId]) {
+    throw new Error(`Vessel not found: ${vesselId}`)
+  }
+
+  const compositions = registry.vessels[vesselId].composition?.compositions || []
+  const existing = compositions.find(c => c.parent === parent && c.child === child)
+
+  if (existing) {
+    existing.count++
+    // Update success rate
+    const successCount = Math.round(existing.successRate * (existing.count - 1) / 100)
+    existing.successRate = ((successCount + (success ? 1 : 0)) / existing.count) * 100
+  } else {
+    compositions.push({
+      parent,
+      child,
+      count: 1,
+      successRate: success ? 100 : 0,
+    })
+  }
+
+  registry.vessels[vesselId].composition = {
+    ...registry.vessels[vesselId].composition,
+    compositions,
+  }
+
+  saveRegistry(registry)
+}
+
+/**
+ * Deregister a vessel
+ */
+export function deregisterVessel(id: string): boolean {
+  const registry = loadRegistry()
+
+  if (!registry.vessels[id]) {
+    return false
+  }
+
+  delete registry.vessels[id]
+  saveRegistry(registry)
+  console.log(`[VesselRegistry] Deregistered vessel: ${id}`)
+
+  return true
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+/**
+ * Register a vessel and sync to backend (async version)
+ */
+export async function registerVesselWithSync(
+  vessel: Omit<Vessel, 'id' | 'createdAt' | 'lastActiveAt' | 'mapping'>,
+  functionMappings?: Array<{
+    functionName: string
+    file: string
+    line: number
+    className?: string
+    intent?: InferredIntent
+  }>
+): Promise<Vessel> {
+  // Register locally first
+  const registeredVessel = registerVessel(vessel)
+
+  // Then sync to backend (non-blocking, but we await for reporting)
+  await syncVesselToBackend(registeredVessel, functionMappings)
+
+  return registeredVessel
+}
+
+/**
+ * Fetch vessel from backend (if local not found)
+ */
+export async function fetchVesselFromBackend(vesselId: string): Promise<Vessel | null> {
+  try {
+    const response = await fetch(`${BACKEND_ENDPOINT}/v2/vessels/registry/${vesselId}`)
+    if (!response.ok) return null
+
+    const data = await response.json()
+    return {
+      ...data,
+      mapping: {
+        functionMap: new Map(),
+        intentMap: new Map(),
+        patternMap: new Map(),
+      },
+    }
+  } catch {
+    return null
+  }
+}
+
+export const vesselRegistry = {
+  register: registerVessel,
+  registerWithSync: registerVesselWithSync,
+  get: getVessel,
+  getByPath: getVesselByPath,
+  list: listVessels,
+  updateActivities: updateVesselActivities,
+  addActivity: addVesselActivity,
+  updateMapping: updateVesselMapping,
+  recordComposition: recordVesselComposition,
+  recordExecution: recordActivityExecution,
+  deregister: deregisterVessel,
+  fetchFromBackend: fetchVesselFromBackend,
+}

package/templates/core/edit-file.json

@@ -0,0 +1,85 @@
+{
+  "activity_id": "core-edit-file",
+  "variant_id": "core-edit-file-v1",
+  "variant_name": "Edit File with Specific Changes",
+  "category": "feature",
+  "description": "Modify an existing file by making specific changes to its content. Use when goal mentions: change, modify, edit, update, replace values in a file.",
+  "scope": "global",
+  "task_steps": [
+    {
+      "id": "read-file",
+      "description": "Read the target file to understand current content",
+      "dependencies": [],
+      "subagent": "general",
+      "prompt": {
+        "template": "Read the file {{filePath}} to see its current content:\n\nread({ filePath: \"{{filePath}}\" })\n\nTake note of the current values that need to be changed.",
+        "maxTokens": 4096,
+        "compressionStrategy": "filter",
+        "variables": [
+          {
+            "name": "filePath",
+            "type": "string",
+            "required": true,
+            "description": "Path to file to edit"
+          }
+        ]
+      },
+      "retry": {
+        "maxAttempts": 2,
+        "strategy": "simple"
+      }
+    },
+    {
+      "id": "apply-changes",
+      "description": "Apply the specified changes using edit tool",
+      "dependencies": ["read-file"],
+      "subagent": "general",
+      "prompt": {
+        "template": "Now modify the file {{filePath}} to apply these changes:\n\n{{changes}}\n\nUse the edit tool to make ONLY the specified changes. Be precise with the oldString parameter - it must match the exact content being replaced.\n\nedit({\n  filePath: \"{{filePath}}\",\n  oldString: \"<exact string to replace>\",\n  newString: \"<new string>\"\n})\n\nIf multiple changes are needed, make multiple edit calls.",
+        "maxTokens": 4096,
+        "compressionStrategy": "filter",
+        "variables": [
+          {
+            "name": "filePath",
+            "type": "string",
+            "required": true,
+            "description": "Path to file to edit"
+          },
+          {
+            "name": "changes",
+            "type": "string",
+            "required": true,
+            "description": "Description of what changes to make"
+          }
+        ]
+      },
+      "retry": {
+        "maxAttempts": 2,
+        "strategy": "simple"
+      }
+    },
+    {
+      "id": "verify-changes",
+      "description": "Read the file again to verify changes were applied",
+      "dependencies": ["apply-changes"],
+      "subagent": "general",
+      "prompt": {
+        "template": "Verify the changes by reading the file again:\n\nread({ filePath: \"{{filePath}}\" })\n\nConfirm that the requested changes have been applied correctly.",
+        "maxTokens": 4096,
+        "compressionStrategy": "filter",
+        "variables": [
+          {
+            "name": "filePath",
+            "type": "string",
+            "required": true,
+            "description": "Path to file to edit"
+          }
+        ]
+      },
+      "retry": {
+        "maxAttempts": 2,
+        "strategy": "simple"
+      }
+    }
+  ]
+}