@metabob/minibob 0.1.2

package/src/validation.ts

@@ -0,0 +1,125 @@
+/**
+ * Input validation utilities
+ * 
+ * Lightweight validation without external dependencies.
+ * Prevents crashes from malformed input and provides clear error messages.
+ */
+
+export interface ValidationError {
+  field: string
+  message: string
+}
+
+export class ValidationException extends Error {
+  constructor(public errors: ValidationError[]) {
+    super(`Validation failed: ${errors.map((e) => `${e.field}: ${e.message}`).join(", ")}`)
+    this.name = "ValidationException"
+  }
+}
+
+/**
+ * Validate /run activity request body
+ */
+export function validateRunActivityRequest(body: unknown): {
+  template: string
+  variables: Record<string, unknown>
+  reason?: string
+} {
+  const errors: ValidationError[] = []
+
+  if (!body || typeof body !== "object") {
+    throw new ValidationException([
+      { field: "body", message: "Request body must be a JSON object" },
+    ])
+  }
+
+  const data = body as Record<string, unknown>
+
+  // Validate template (required)
+  const template = data.template ?? data.templatePath
+  if (!template || typeof template !== "string") {
+    errors.push({
+      field: "template",
+      message: "Missing required field (string expected)",
+    })
+  }
+
+  if (template && typeof template === "string" && template.length > 1000) {
+    errors.push({
+      field: "template",
+      message: "Template path too long (max 1000 characters)",
+    })
+  }
+
+  // Validate variables (optional, default to empty object)
+  let variables: Record<string, unknown> = {}
+  if (data.variables !== undefined) {
+    if (typeof data.variables !== "object" || data.variables === null) {
+      errors.push({
+        field: "variables",
+        message: "Must be an object",
+      })
+    } else {
+      variables = data.variables as Record<string, unknown>
+    }
+  }
+
+  // Validate reason (optional)
+  let reason: string | undefined
+  if (data.reason !== undefined) {
+    if (typeof data.reason !== "string") {
+      errors.push({
+        field: "reason",
+        message: "Must be a string",
+      })
+    } else if (data.reason.length > 5000) {
+      errors.push({
+        field: "reason",
+        message: "Reason too long (max 5000 characters)",
+      })
+    } else {
+      reason = data.reason
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new ValidationException(errors)
+  }
+
+  return {
+    template: template as string,
+    variables,
+    reason,
+  }
+}
+
+/**
+ * Validate request body size (prevent DoS)
+ * @param contentLength Content-Length header value
+ * @param maxSizeBytes Maximum allowed size in bytes (default: 10MB)
+ */
+export function validateRequestSize(
+  contentLength: string | null,
+  maxSizeBytes: number = 10 * 1024 * 1024
+): void {
+  if (!contentLength) {
+    // No Content-Length header - will be checked during parsing
+    return
+  }
+
+  const size = parseInt(contentLength, 10)
+  if (isNaN(size)) {
+    throw new ValidationException([
+      { field: "Content-Length", message: "Invalid header value" },
+    ])
+  }
+
+  if (size > maxSizeBytes) {
+    throw new ValidationException([
+      {
+        field: "Content-Length",
+        message: `Request too large: ${size} bytes (max ${maxSizeBytes} bytes)`,
+      },
+    ])
+  }
+}

package/src/vessel-bootstrap.ts

@@ -0,0 +1,440 @@
+/**
+ * Vessel Bootstrap
+ *
+ * Universal vessel conversion module.
+ * Import this into any application to make it self-aware and activity-controlled.
+ *
+ * Core Concept: Continuous Learning
+ * ---------------------------------
+ * The vessel doesn't have a separate "observation mode" - it continuously learns
+ * during normal operation. When activities execute:
+ *
+ *   Intent → Code       (instructional → functional, choosing what to execute)
+ *   Code → Outcome      (instructional → functional, execution results)
+ *
+ * Both transformations are mediated by activities. The existing infrastructure
+ * handles this automatically:
+ *
+ * 1. ActivityExecutor captures execution traces
+ * 2. Backend stores traces and applies Thompson Sampling
+ * 3. runtime-mapping maps traces to source and infers intent
+ *
+ * The burrow command lays the groundwork (injects bootstrap, creates config).
+ * Normal operation continuously builds understanding through execution traces.
+ *
+ * Usage:
+ * ```typescript
+ * import { initializeVessel } from '@metabob/minibob/vessel-bootstrap'
+ *
+ * const vessel = await initializeVessel({
+ *   workingDirectory: __dirname,
+ *   provider: 'anthropic',
+ *   apiKey: process.env.ANTHROPIC_API_KEY!,
+ *   model: 'claude-sonnet-4-20250514',
+ *   vesselType: 'my-app',
+ * })
+ *
+ * // Register components for runtime access
+ * vessel.state.register('myComponent', myComponentInstance)
+ *
+ * // Run activities - learning happens automatically via execution traces
+ * await vessel.runGoal('Optimize database query performance')
+ * ```
+ */
+
+import { ActivityExecutor, type ExecutorConfig } from './activity'
+import { GoalProcessor } from './goal-processor'
+import type { ActivityTemplate } from './types'
+import { initializeMCP } from './mcp'
+
+const log = {
+  info: (...args: any[]) => console.log('[Vessel]', ...args),
+  warn: (...args: any[]) => console.warn('[Vessel]', ...args),
+  error: (...args: any[]) => console.error('[Vessel]', ...args),
+  debug: (...args: any[]) => console.debug('[Vessel]', ...args),
+}
+
+export interface VesselConfig extends ExecutorConfig {
+  /**
+   * Vessel type identifier (for telemetry)
+   */
+  vesselType?: string
+
+  /**
+   * Enable self-improvement loop
+   * Vessel will periodically run optimization activities on itself
+   */
+  enableSelfImprovement?: boolean
+
+  /**
+   * Self-improvement interval (ms)
+   * Default: 5 minutes
+   */
+  selfImprovementInterval?: number
+}
+
+export interface VesselState {
+  /**
+   * Components registered for runtime access
+   */
+  registry: Map<string, any>
+
+  /**
+   * Vessel metadata
+   */
+  metadata: {
+    type: string
+    startTime: number
+    workingDirectory: string
+  }
+
+  /**
+   * Performance metrics
+   */
+  metrics: {
+    activitiesExecuted: number
+    goalsExecuted: number
+    totalCost: number
+    avgDuration: number
+    uptime: number
+  }
+}
+
+/**
+ * Vessel Bootstrap
+ *
+ * Converts any application into a self-aware, activity-controlled vessel.
+ * Continuous learning happens automatically through execution traces.
+ */
+export class VesselBootstrap {
+  private executor: ActivityExecutor
+  private goalProcessor: GoalProcessor
+  public state: VesselStateManager
+  private selfImprovementInterval?: NodeJS.Timeout
+  private config: VesselConfig
+
+  constructor(config: VesselConfig) {
+    this.config = {
+      vesselType: 'generic',
+      enableSelfImprovement: false,
+      selfImprovementInterval: 5 * 60 * 1000, // 5 minutes
+      ...config
+    }
+
+    log.info('Initializing vessel', {
+      type: this.config.vesselType,
+      workingDirectory: this.config.workingDirectory
+    })
+
+    // Initialize executor
+    this.executor = new ActivityExecutor({
+      provider: this.config.provider,
+      apiKey: this.config.apiKey,
+      model: this.config.model,
+      workingDirectory: this.config.workingDirectory,
+      systemPrompt: this.config.systemPrompt,
+      customTools: this.config.customTools,
+      maxNestingDepth: this.config.maxNestingDepth,
+    })
+
+    // Initialize goal processor
+    this.goalProcessor = new GoalProcessor({
+      workingDirectory: this.config.workingDirectory,
+      executor: this.executor
+    })
+
+    // Initialize state manager
+    this.state = new VesselStateManager({
+      type: this.config.vesselType!,
+      workingDirectory: this.config.workingDirectory
+    })
+
+    // Register vessel internals
+    this.state.register('vessel', {
+      executor: this.executor,
+      goalProcessor: this.goalProcessor,
+      runActivity: this.runActivity.bind(this),
+      runGoal: this.runGoal.bind(this),
+      getState: () => this.state.snapshot(),
+      shutdown: this.shutdown.bind(this)
+    })
+
+    // Start self-improvement loop if enabled
+    if (this.config.enableSelfImprovement) {
+      this.startSelfImprovementLoop()
+    }
+
+    log.info('Vessel initialized successfully', {
+      type: this.config.vesselType,
+      selfImprovement: this.config.enableSelfImprovement
+    })
+  }
+
+  /**
+   * Run activity on this vessel
+   *
+   * @param template Activity template or template ID
+   * @param variables Variables for the activity
+   * @returns Activity execution result
+   */
+  async runActivity(template: ActivityTemplate | string, variables: any = {}) {
+    log.info('Running activity on vessel', {
+      template: typeof template === 'string' ? template : template.id
+    })
+
+    this.state.incrementMetric('activitiesExecuted')
+    const startTime = Date.now()
+
+    try {
+      // If template is string, need to fetch it (not implemented here)
+      if (typeof template === 'string') {
+        throw new Error('Template fetching not implemented. Pass ActivityTemplate object directly.')
+      }
+
+      const result = await this.executor.execute({
+        template,
+        variables: {
+          ...variables,
+          // Inject vessel context
+          vesselType: this.config.vesselType,
+          vesselWorkingDirectory: this.config.workingDirectory
+        }
+      })
+
+      // Update metrics
+      const duration = Date.now() - startTime
+      this.state.updateMetrics({
+        avgDuration: duration,
+        totalCost: result.metrics?.cost || 0
+      })
+
+      return result
+    } catch (error) {
+      log.error('Activity failed', { error: error instanceof Error ? error.message : String(error) })
+      throw error
+    }
+  }
+
+  /**
+   * Run goal on this vessel
+   *
+   * Execution traces are automatically captured and sent to the backend
+   * where Thompson Sampling learns which activities work best.
+   *
+   * @param goal Natural language goal description
+   * @param context Additional context for the goal
+   * @param options Goal execution options
+   * @returns Goal execution result
+   */
+  async runGoal(goal: string, context: any = {}, options: any = {}) {
+    log.info('Running goal on vessel', { goal: goal.slice(0, 100) })
+
+    this.state.incrementMetric('goalsExecuted')
+
+    try {
+      const result = await this.goalProcessor.executeGoal(goal, {
+        ...context,
+        // Inject vessel context
+        vesselType: this.config.vesselType,
+        vesselWorkingDirectory: this.config.workingDirectory
+      }, options)
+
+      return result
+    } catch (error) {
+      log.error('Goal failed', { error: error instanceof Error ? error.message : String(error) })
+      throw error
+    }
+  }
+
+  /**
+   * Start self-improvement loop
+   * Vessel periodically analyzes and optimizes itself
+   */
+  private startSelfImprovementLoop() {
+    log.info('Starting self-improvement loop', {
+      interval: this.config.selfImprovementInterval
+    })
+
+    this.selfImprovementInterval = setInterval(async () => {
+      try {
+        log.info('Running self-improvement cycle')
+
+        await this.runGoal(
+          'Analyze vessel performance and apply optimizations if beneficial. Focus on reducing cost and duration while maintaining quality.',
+          {
+            files: [this.config.workingDirectory + '/**/*.ts'],
+            currentMetrics: this.state.snapshot().metrics
+          },
+          {
+            maxActivities: 3,
+            maxCost: 2.0
+          }
+        )
+      } catch (error) {
+        log.error('Self-improvement cycle failed', {
+          error: error instanceof Error ? error.message : String(error)
+        })
+      }
+    }, this.config.selfImprovementInterval)
+  }
+
+  /**
+   * Shutdown vessel
+   */
+  shutdown() {
+    log.info('Shutting down vessel')
+
+    if (this.selfImprovementInterval) {
+      clearInterval(this.selfImprovementInterval)
+    }
+
+    log.info('Vessel shutdown complete')
+  }
+}
+
+/**
+ * Vessel State Manager
+ *
+ * Manages observable state for the vessel
+ * Components register themselves for runtime access
+ */
+export class VesselStateManager {
+  private registry: Map<string, any> = new Map()
+  private metadata: VesselState['metadata']
+  private metrics: VesselState['metrics']
+
+  constructor(config: { type: string, workingDirectory: string }) {
+    this.metadata = {
+      type: config.type,
+      startTime: Date.now(),
+      workingDirectory: config.workingDirectory
+    }
+
+    this.metrics = {
+      activitiesExecuted: 0,
+      goalsExecuted: 0,
+      totalCost: 0,
+      avgDuration: 0,
+      uptime: 0
+    }
+  }
+
+  /**
+   * Register component for runtime access
+   *
+   * @param name Component identifier
+   * @param component Any object to make accessible
+   */
+  register(name: string, component: any) {
+    this.registry.set(name, component)
+    log.debug('Component registered', { name })
+  }
+
+  /**
+   * Get registered component
+   */
+  get(name: string): any {
+    return this.registry.get(name)
+  }
+
+  /**
+   * List all registered components
+   */
+  list(): string[] {
+    return Array.from(this.registry.keys())
+  }
+
+  /**
+   * Get full state snapshot
+   */
+  snapshot(): VesselState {
+    this.metrics.uptime = Date.now() - this.metadata.startTime
+
+    return {
+      registry: this.registry,
+      metadata: this.metadata,
+      metrics: { ...this.metrics }
+    }
+  }
+
+  /**
+   * Increment metric
+   */
+  incrementMetric(metric: keyof VesselState['metrics']) {
+    if (typeof this.metrics[metric] === 'number') {
+      (this.metrics[metric] as number)++
+    }
+  }
+
+  /**
+   * Update metrics
+   */
+  updateMetrics(updates: Partial<VesselState['metrics']>) {
+    if (updates.totalCost !== undefined) {
+      this.metrics.totalCost += updates.totalCost
+    }
+
+    if (updates.avgDuration !== undefined) {
+      // Running average
+      const count = this.metrics.activitiesExecuted || 1
+      this.metrics.avgDuration =
+        (this.metrics.avgDuration * (count - 1) + updates.avgDuration) / count
+    }
+  }
+}
+
+/**
+ * Global vessel instance
+ * Applications can access via globalThis.__vessel
+ */
+declare global {
+  var __vessel: VesselBootstrap | undefined
+}
+
+/**
+ * Initialize vessel globally
+ * Convenience function for applications
+ *
+ * @param config Vessel configuration
+ * @returns Vessel instance
+ */
+export async function initializeVessel(config: VesselConfig): Promise<VesselBootstrap> {
+  if (globalThis.__vessel) {
+    log.warn('Vessel already initialized, returning existing instance')
+    return globalThis.__vessel
+  }
+
+  // Initialize MCP first if endpoint configured
+  const mcpEndpoint = process.env.MINIBOB_MCP_ENDPOINT
+  if (mcpEndpoint) {
+    log.info('Initializing MCP client', { endpoint: mcpEndpoint })
+    try {
+      const client = await initializeMCP({ endpoint: mcpEndpoint })
+      if (client) {
+        log.info('MCP client initialized successfully')
+      } else {
+        log.warn('MCP client initialization failed - backend may be unavailable')
+      }
+    } catch (err) {
+      log.error('MCP initialization error:', err instanceof Error ? err.message : String(err))
+    }
+  } else {
+    log.warn('MINIBOB_MCP_ENDPOINT not set, MCP features unavailable')
+  }
+
+  const vessel = new VesselBootstrap(config)
+  globalThis.__vessel = vessel
+
+  // Register shutdown handlers
+  process.on('SIGTERM', () => vessel.shutdown())
+  process.on('SIGINT', () => vessel.shutdown())
+
+  return vessel
+}
+
+/**
+ * Get global vessel instance
+ */
+export function getVessel(): VesselBootstrap | undefined {
+  return globalThis.__vessel
+}