@metabob/minibob 0.1.2

package/src/types.ts

@@ -0,0 +1,497 @@
+/**
+ * minibob Type Definitions
+ * 
+ * Minimal type system for activity execution, impulses, and vessel communication.
+ * Designed to be compatible with OpenCode schemas but much simpler.
+ */
+
+// =============================================================================
+// IMPULSE SYSTEM
+// =============================================================================
+
+/**
+ * Impulse pointer types - what the impulse references
+ * 
+ * Architecture principle: MiniBob handles LOCAL types (memo, file).
+ * Backend (metabob-activity-api) handles ALL OTHER types via MCP.
+ * 
+ * This keeps minibob flexible - backend can introduce new pointer types
+ * without requiring minibob code changes.
+ */
+
+/**
+ * Local pointer types (minibob resolves these directly)
+ */
+export type LocalImpulsePointer =
+  | { type: "memo"; content: string }
+  | { type: "file"; path: string; offset?: number; limit?: number }
+
+/**
+ * Backend pointer types (resolved via MCP - examples, not exhaustive)
+ * Backend can introduce new types without minibob changes.
+ */
+export type BackendImpulsePointer =
+  | { type: "activityOutput"; activityId: string; taskId?: string }
+  | { type: "activityExecutionTrace"; executionId: string; [key: string]: unknown }
+  | { type: "activityTemplate"; templateId: string; [key: string]: unknown }
+  | { type: "activityMetrics"; templateId: string; [key: string]: unknown }
+  | { type: string; [key: string]: unknown }  // Catch-all for backend-defined types
+
+/**
+ * All impulse pointer types (local + backend)
+ */
+export type ImpulsePointer = LocalImpulsePointer | BackendImpulsePointer
+
+/**
+ * Impulse - lazy-loaded context with token budget
+ */
+export interface Impulse {
+  id: string
+  pointer: ImpulsePointer
+  budget: number
+  priority: "critical" | "high" | "medium" | "low"
+  // State
+  loaded: boolean
+  content?: string
+  tokenCount?: number
+  // Metadata
+  createdAt: number
+  tags?: string[]
+}
+
+// =============================================================================
+// ACTIVITY SYSTEM
+// =============================================================================
+
+/**
+ * Variable definition for activity templates
+ */
+export interface VariableDefinition {
+  name: string
+  type: "string" | "number" | "boolean" | "array" | "object"
+  required: boolean
+  description?: string
+  default?: unknown
+}
+
+/**
+ * Task prompt configuration
+ */
+export interface TaskPrompt {
+  template: string
+  variables: VariableDefinition[]
+  maxTokens?: number
+}
+
+/**
+ * Validation rules for task completion
+ */
+export interface TaskValidation {
+  requiredFiles?: string[]
+  /** Check patterns in task output (string array) or in specific files (object array) */
+  requiredPatterns?: string[] | Array<{ file: string; pattern: string }>
+  forbiddenPatterns?: Array<{ file: string; pattern: string }>
+  commands?: Array<{ command: string; expectedOutput?: string }>
+  /** Require task to produce non-empty output */
+  requireOutput?: boolean
+}
+
+/**
+ * Activity task - single unit of work
+ */
+export interface ActivityTask {
+  id: string
+  description: string
+  prompt: TaskPrompt
+  dependencies?: string[]
+  validation?: TaskValidation
+  impulseReferences?: string[]
+  retry?: {
+    maxAttempts: number
+    strategy: "simple" | "progressive-context"
+  }
+  /** Impulse IDs to create from task output (optional) */
+  outputImpulses?: string[]
+}
+
+/**
+ * Activity template - blueprint for execution
+ */
+export interface ActivityTemplate {
+  id: string
+  name: string
+  description: string
+  category: "feature" | "bugfix" | "refactor" | "tool" | "infrastructure"
+  tasks: ActivityTask[]
+  contextRequirements?: Array<{
+    id: string
+    type: "file" | "glob" | "memo" | "custom"
+    source: string
+    budget: number
+    priority: "critical" | "high" | "medium" | "low"
+  }>
+  variables: VariableDefinition[]
+  
+  /**
+   * Optional metadata for provenance tracking
+   * Used by ribosome to track template generation history
+   */
+  metadata?: {
+    generatedFrom?: "execution" | "goal-seeking" | "manual"
+    sourceExecutionId?: string
+    sourceTemplateId?: string
+    firstExecutionMetrics?: {
+      duration: number
+      cost: number
+      tokens: { input: number; output: number }
+      status: string
+    }
+    createdAt?: number
+    author?: string
+  }
+}
+
+/**
+ * Activity execution state
+ */
+export type ActivityStatus = "pending" | "executing" | "completed" | "failed" | "cancelled"
+
+export interface TaskResult {
+  taskId: string
+  status: "pending" | "executing" | "completed" | "failed"
+  output?: string
+  error?: string
+  startedAt?: number
+  completedAt?: number
+  tokens?: { input: number; output: number }
+  
+  // Phase 1.8+: State tracking for ribosome (template generation from traces)
+  metadata?: {
+    inputState?: ExecutedTask["inputState"]
+    outputState?: ExecutedTask["outputState"]
+    stateTransition?: ExecutedTask["stateTransition"]
+    toolCalls?: ToolCall[]
+    actualPrompt?: string
+  }
+}
+
+export interface ActivityExecution {
+  id: string
+  templateId: string
+  status: ActivityStatus
+  variables: Record<string, unknown>
+  impulses: Impulse[]
+  taskResults: TaskResult[]
+  startedAt: number
+  completedAt?: number
+  /** Error message if execution failed */
+  error?: string
+  /** Execution trace (if recording enabled) */
+  executionTrace?: ExecutionTrace
+  metrics?: {
+    duration: number
+    cost: number
+    totalTokens: { input: number; output: number }
+  }
+}
+
+/**
+ * Record of what happened during activity execution
+ * Used to generate activity templates from successful goal executions
+ */
+export interface ExecutionTrace {
+  /** Tasks executed with full context */
+  tasks: ExecutedTask[]
+  /** Impulses created during execution */
+  impulsesCreated: string[]
+  /** Files modified */
+  filesModified: string[]
+  /** Goal that triggered this execution (if any) */
+  goalContext?: {
+    goal: string
+    intent: string
+    context: Record<string, unknown>
+  }
+}
+
+/**
+ * Record of a single task execution
+ */
+export interface ExecutedTask {
+  /** Task ID from template */
+  id: string
+  /** Task description */
+  description: string
+  /** Actual prompt sent to LLM (after variable substitution) */
+  actualPrompt: string
+  /** Tools called during task */
+  toolCalls: ToolCall[]
+  /** LLM response */
+  response: string
+  /** Validation results */
+  validationResults?: {
+    requiredFiles: Array<{ path: string; exists: boolean }>
+    requiredPatterns: Array<{ pattern: string; found: boolean }>
+    forbiddenPatterns: Array<{ pattern: string; found: boolean }>
+  }
+  /** Task result (mapped to backend schema: success/failure/partial) */
+  result: {
+    status: "success" | "failure" | "partial"
+    error?: string
+    metadata?: Record<string, unknown>
+  }
+  
+  // ============================================================================
+  // PHASE 1.8: Enhanced State Tracking for Debugging-as-Activity
+  // ============================================================================
+  
+  /**
+   * Input state captured before task execution
+   * Enables debugging activities to analyze what the task had access to
+   */
+  inputState?: {
+    /** Files available in working directory before execution */
+    filesAvailable: string[]
+    /** Environment variables at task start */
+    environment: Record<string, string>
+    /** Impulse IDs referenced by this task */
+    impulses: string[]
+    /** Variables passed to task (after interpolation) */
+    variables: Record<string, unknown>
+  }
+  
+  /**
+   * Output state captured after task execution
+   * Enables debugging activities to analyze what changed
+   */
+  outputState?: {
+    /** Files modified during execution */
+    filesModified: string[]
+    /** Files created during execution */
+    filesCreated: string[]
+    /** Files deleted during execution */
+    filesDeleted: string[]
+    /** Exit code from bash commands (if any) */
+    exitCode?: number
+    /** Standard error output (if any) */
+    stderr?: string
+  }
+  
+  /**
+   * State transition snapshot (lightweight before/after)
+   * Enables debugging activities to perform differential analysis
+   */
+  stateTransition?: {
+    /** Filesystem snapshot before execution (file → hash) */
+    before: Record<string, string>
+    /** Filesystem snapshot after execution (file → hash) */
+    after: Record<string, string>
+    /** Working directory at execution time */
+    workingDirectory: string
+  }
+}
+
+/**
+ * Record of a tool call (matches backend ExecutionTrace schema)
+ * Tool calls are impulse-like data pointers - they reference data
+ * that influenced LLM decisions during execution
+ */
+export interface ToolCall {
+  /** Unique identifier for this tool call (impulse-like ID) */
+  id: string
+  /** Tool name */
+  name: string
+  /** Arguments passed to tool */
+  arguments: Record<string, unknown>
+  /** Tool result */
+  result: {
+    success: boolean
+    output?: string
+    error?: string
+    metadata?: Record<string, unknown>
+  }
+}
+
+// =============================================================================
+// TOOL SYSTEM
+// =============================================================================
+
+/**
+ * Tool definition for LLM function calling
+ */
+export interface ToolDefinition {
+  name: string
+  description: string
+  parameters: {
+    type: "object"
+    properties: Record<string, {
+      type: string
+      description: string
+      enum?: string[]
+    }>
+    required: string[]
+  }
+}
+
+/**
+ * Tool execution result
+ */
+export interface ToolResult {
+  success: boolean
+  output?: string
+  error?: string
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Tool handler function type
+ */
+export type ToolHandler = (params: Record<string, unknown>) => Promise<ToolResult>
+
+// =============================================================================
+// LLM SYSTEM
+// =============================================================================
+
+/**
+ * Message role in conversation
+ */
+export type MessageRole = "system" | "user" | "assistant" | "tool"
+
+/**
+ * Chat message
+ */
+export interface Message {
+  role: MessageRole
+  content: string
+  toolCalls?: Array<{
+    id: string
+    name: string
+    arguments: Record<string, unknown>
+  }>
+  toolCallId?: string
+}
+
+/**
+ * LLM completion options
+ */
+export interface CompletionOptions {
+  model: string
+  messages: Message[]
+  tools?: ToolDefinition[]
+  maxTokens?: number
+  temperature?: number
+  stream?: boolean
+}
+
+/**
+ * LLM completion result
+ */
+export interface CompletionResult {
+  content: string
+  toolCalls?: Array<{
+    id: string
+    name: string
+    arguments: Record<string, unknown>
+  }>
+  finishReason: "stop" | "tool_calls" | "length" | "error"
+  usage: {
+    inputTokens: number
+    outputTokens: number
+  }
+}
+
+// =============================================================================
+// ACP PROTOCOL
+// =============================================================================
+
+/**
+ * ACP delegate request
+ */
+export interface ACPDelegateRequest {
+  target: string  // "docker://container" or "tcp://host:port" or "http://url"
+  taskDescription: string
+  prompt: string
+  shareImpulses?: string[]
+  timeout?: number
+}
+
+/**
+ * ACP delegate response
+ */
+export interface ACPDelegateResponse {
+  success: boolean
+  sessionId: string
+  response?: string
+  toolsUsed?: string[]
+  error?: string
+  metrics?: {
+    duration: number
+    tokens: { input: number; output: number }
+  }
+}
+
+/**
+ * ACP session message
+ */
+export type ACPMessage =
+  | { type: "hello"; version: string; capabilities: string[] }
+  | { type: "prompt"; sessionId: string; messages: Message[]; tools?: ToolDefinition[] }
+  | { type: "response"; sessionId: string; content: string; finishReason: string }
+  | { type: "tool_call"; sessionId: string; toolCallId: string; name: string; arguments: Record<string, unknown> }
+  | { type: "tool_result"; sessionId: string; toolCallId: string; result: ToolResult }
+  | { type: "error"; sessionId: string; error: string }
+  | { type: "complete"; sessionId: string; metrics: { duration: number; tokens: { input: number; output: number } } }
+
+// =============================================================================
+// CONFIGURATION
+// =============================================================================
+
+/**
+ * minibob configuration
+ */
+export interface MinibobConfig {
+  // Server
+  port: number
+  host: string
+  
+  // LLM
+  provider: "anthropic" | "openai"
+  model: string
+  apiKey: string
+  
+  // Vessels (MCP connections)
+  vessels: Record<string, {
+    type: "mcp" | "http"
+    endpoint: string
+    capabilities: string[]
+  }>
+  
+  // Activity
+  templatesDir: string
+  
+  // Git
+  workingDirectory: string
+  autoCommit: boolean
+}
+
+// =============================================================================
+// VESSEL MANIFEST
+// =============================================================================
+
+/**
+ * Vessel manifest - describes this vessel's capabilities
+ */
+export interface VesselManifest {
+  id: string
+  name: string
+  version: string
+  capabilities: string[]
+  tools: string[]
+  acpEndpoint: string
+  metadata?: {
+    environment?: string
+    clusterMode?: boolean
+    peerCount?: number
+    backendAvailable?: boolean
+  }
+}