@metabob/minibob 0.1.2

package/src/impulse-filter.ts

@@ -0,0 +1,273 @@
+/**
+ * Impulse Filtering Logic (Phase 1.8)
+ * 
+ * Filters impulses based on learned relevance scores to reduce token usage.
+ * 
+ * Key concepts:
+ * - relevance_score: P(success | impulse loaded)
+ * - irrelevance_score: P(success | impulse NOT loaded)
+ * 
+ * Decision rules:
+ * 1. Always load if relevance_score > 0.8 (strong positive signal)
+ * 2. Load if relevance_score > threshold (default: 0.5)
+ * 3. Skip if irrelevance_score > relevance_score (better without it)
+ * 4. Limit to maxImpulses (default: 10)
+ */
+
+import type { ImpulseRelevanceMetric } from "./mcp"
+
+// =============================================================================
+// CONFIGURATION
+// =============================================================================
+
+export interface FilterConfig {
+  // Threshold for loading impulses (default: 0.5)
+  relevanceThreshold: number
+  
+  // Always load impulses with score above this (default: 0.8)
+  alwaysLoadThreshold: number
+  
+  // Maximum impulses to load (default: 10)
+  maxImpulses: number
+  
+  // Fallback behavior when no metrics available
+  fallbackBehavior: 'load-all' | 'load-none' | 'load-top-n'
+}
+
+/**
+ * Get filter configuration from environment variables
+ */
+export function getFilterConfig(): FilterConfig {
+  const relevanceThreshold = parseFloat(process.env.IMPULSE_RELEVANCE_THRESHOLD || '0.5')
+  const alwaysLoadThreshold = parseFloat(process.env.IMPULSE_ALWAYS_LOAD_THRESHOLD || '0.8')
+  const maxImpulses = parseInt(process.env.IMPULSE_MAX_LOAD || '10', 10)
+  const fallbackBehavior = (process.env.IMPULSE_FALLBACK_BEHAVIOR || 'load-all') as FilterConfig['fallbackBehavior']
+
+  return {
+    relevanceThreshold: isNaN(relevanceThreshold) ? 0.5 : relevanceThreshold,
+    alwaysLoadThreshold: isNaN(alwaysLoadThreshold) ? 0.8 : alwaysLoadThreshold,
+    maxImpulses: isNaN(maxImpulses) ? 10 : maxImpulses,
+    fallbackBehavior: ['load-all', 'load-none', 'load-top-n'].includes(fallbackBehavior) 
+      ? fallbackBehavior 
+      : 'load-all',
+  }
+}
+
+export const DEFAULT_FILTER_CONFIG: FilterConfig = {
+  relevanceThreshold: 0.5,
+  alwaysLoadThreshold: 0.8,
+  maxImpulses: 10,
+  fallbackBehavior: 'load-all', // Conservative: load all if no data
+}
+
+// =============================================================================
+// FILTERING LOGIC
+// =============================================================================
+
+export interface FilterResult {
+  toLoad: string[]
+  toSkip: string[]
+  reasoning: Record<string, string>
+}
+
+/**
+ * Filter impulses based on relevance scores
+ */
+export function filterImpulsesByRelevance(
+  impulseIds: string[],
+  metrics: ImpulseRelevanceMetric[],
+  config: Partial<FilterConfig> = {}
+): FilterResult {
+  // Merge environment config with provided config (provided config takes precedence)
+  const envConfig = getFilterConfig()
+  const cfg = { ...envConfig, ...config }
+  
+  // Build metric map for fast lookup
+  const metricMap = new Map<string, ImpulseRelevanceMetric>()
+  for (const metric of metrics) {
+    metricMap.set(metric.impulse_id, metric)
+  }
+  
+  const toLoad: string[] = []
+  const toSkip: string[] = []
+  const reasoning: Record<string, string> = {}
+  
+  for (const impulseId of impulseIds) {
+    const metric = metricMap.get(impulseId)
+    
+    if (!metric) {
+      // No metrics available - use fallback
+      if (cfg.fallbackBehavior === 'load-all') {
+        toLoad.push(impulseId)
+        reasoning[impulseId] = 'No metrics available (fallback: load)'
+      } else if (cfg.fallbackBehavior === 'load-none') {
+        toSkip.push(impulseId)
+        reasoning[impulseId] = 'No metrics available (fallback: skip)'
+      } else {
+        // load-top-n: will be handled after sorting
+        toLoad.push(impulseId)
+        reasoning[impulseId] = 'No metrics available (fallback: top-n)'
+      }
+      continue
+    }
+    
+    // Decision logic based on learned scores
+    if (metric.relevance_score >= cfg.alwaysLoadThreshold) {
+      // Strong positive signal: always load
+      toLoad.push(impulseId)
+      reasoning[impulseId] = `High relevance (${metric.relevance_score.toFixed(2)})`
+    } else if (metric.irrelevance_score > metric.relevance_score) {
+      // Activity succeeds MORE often WITHOUT this impulse: skip (even if above threshold)
+      toSkip.push(impulseId)
+      reasoning[impulseId] = `More successful without it (irrelevance=${metric.irrelevance_score.toFixed(2)} vs relevance=${metric.relevance_score.toFixed(2)})`
+    } else if (metric.relevance_score >= cfg.relevanceThreshold) {
+      // Above threshold and relevance > irrelevance: load
+      toLoad.push(impulseId)
+      reasoning[impulseId] = `Relevant (${metric.relevance_score.toFixed(2)})`
+    } else {
+      // Below threshold: skip
+      toSkip.push(impulseId)
+      reasoning[impulseId] = `Low relevance (${metric.relevance_score.toFixed(2)})`
+    }
+  }
+  
+  // Enforce max impulses limit
+  if (toLoad.length > cfg.maxImpulses) {
+    // Sort by relevance score descending
+    const loadWithScores = toLoad.map(id => ({
+      id,
+      score: metricMap.get(id)?.relevance_score || 0,
+    }))
+    
+    loadWithScores.sort((a, b) => b.score - a.score)
+    
+    const keptIds = loadWithScores.slice(0, cfg.maxImpulses).map(x => x.id)
+    const droppedIds = loadWithScores.slice(cfg.maxImpulses).map(x => x.id)
+    
+    for (const id of droppedIds) {
+      toSkip.push(id)
+      reasoning[id] = `Dropped (exceeded max ${cfg.maxImpulses})`
+    }
+    
+    return {
+      toLoad: keptIds,
+      toSkip,
+      reasoning,
+    }
+  }
+  
+  return { toLoad, toSkip, reasoning }
+}
+
+// =============================================================================
+// SAVINGS CALCULATION
+// =============================================================================
+
+export interface TokenSavings {
+  tokensSaved: number
+  costSaved: number // USD
+  percentSaved: number
+  totalTokens: number
+  loadedTokens: number
+}
+
+/**
+ * Calculate token savings from skipped impulses
+ */
+export function calculateSavings(
+  skippedImpulses: string[],
+  impulseTokenSizes: Map<string, number>
+): TokenSavings {
+  const totalTokens = Array.from(impulseTokenSizes.values()).reduce((sum, t) => sum + t, 0)
+  const skippedTokens = skippedImpulses
+    .map(id => impulseTokenSizes.get(id) || 0)
+    .reduce((sum, t) => sum + t, 0)
+  
+  const loadedTokens = totalTokens - skippedTokens
+  const percentSaved = totalTokens > 0 ? (skippedTokens / totalTokens) * 100 : 0
+  
+  // Approximate cost: $3 per 1M input tokens (Claude pricing)
+  const costSaved = (skippedTokens / 1_000_000) * 3
+  
+  return {
+    tokensSaved: skippedTokens,
+    costSaved,
+    percentSaved,
+    totalTokens,
+    loadedTokens,
+  }
+}
+
+/**
+ * Estimate token size for an impulse based on pointer type
+ */
+export function estimateImpulseTokens(impulse: {
+  id: string
+  pointer: {
+    type: string
+    [key: string]: any
+  }
+}): number {
+  const pointerType = impulse.pointer.type
+  
+  // Rough estimates based on typical sizes
+  switch (pointerType) {
+    case 'file':
+      return 2000 // Average file: ~2k tokens
+    case 'activityOutput':
+      return 1500 // Activity output: ~1.5k tokens
+    case 'memo':
+      return 500 // Memo: ~500 tokens
+    case 'templateDefinition':
+      return 1000 // Template def: ~1k tokens
+    case 'analysisResult':
+      return 1200 // Analysis: ~1.2k tokens
+    default:
+      return 1000 // Unknown: assume 1k tokens
+  }
+}
+
+// =============================================================================
+// REPORTING
+// =============================================================================
+
+export interface FilteringSummary {
+  totalImpulses: number
+  loadedImpulses: number
+  skippedImpulses: number
+  tokensSaved: number
+  costSaved: number
+  percentSaved: number
+  topReasons: Array<{ reason: string; count: number }>
+}
+
+/**
+ * Generate filtering summary for logging/reporting
+ */
+export function generateFilteringSummary(
+  filterResult: FilterResult,
+  savings: TokenSavings
+): FilteringSummary {
+  // Count reasons
+  const reasonCounts = new Map<string, number>()
+  for (const reason of Object.values(filterResult.reasoning)) {
+    const count = reasonCounts.get(reason) || 0
+    reasonCounts.set(reason, count + 1)
+  }
+  
+  // Sort by count descending
+  const topReasons = Array.from(reasonCounts.entries())
+    .map(([reason, count]) => ({ reason, count }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 5)
+  
+  return {
+    totalImpulses: filterResult.toLoad.length + filterResult.toSkip.length,
+    loadedImpulses: filterResult.toLoad.length,
+    skippedImpulses: filterResult.toSkip.length,
+    tokensSaved: savings.tokensSaved,
+    costSaved: savings.costSaved,
+    percentSaved: savings.percentSaved,
+    topReasons,
+  }
+}

package/src/impulse.ts

@@ -0,0 +1,311 @@
+/**
+ * minibob Impulse System
+ * 
+ * Minimal impulse implementation for context management.
+ * Supports: memo, file, activityOutput, custom pointer types.
+ */
+
+import type { Impulse, ImpulsePointer } from "./types"
+import { getMCPClient, isMCPEnabled } from "./mcp"
+
+// =============================================================================
+// IMPULSE STORAGE
+// =============================================================================
+
+/**
+ * In-memory impulse store (can be backed by MCP in production)
+ */
+class ImpulseStore {
+  private impulses = new Map<string, Impulse>()
+  private customResolvers = new Map<string, (data: Record<string, unknown>) => Promise<string>>()
+  private activityOutputs = new Map<string, Map<string, string>>() // activityId -> taskId -> output
+
+  /**
+   * Create a new impulse
+   */
+  create(impulse: Omit<Impulse, "loaded" | "createdAt">): Impulse {
+    const fullImpulse: Impulse = {
+      ...impulse,
+      loaded: false,
+      createdAt: Date.now(),
+    }
+    this.impulses.set(impulse.id, fullImpulse)
+    
+    // Store in backend if MCP enabled
+    // This enables cross-execution impulse tracking and learning
+    // Data flow: impulse.ts:create() → mcp.ts:storeImpulse() → POST /impulses → backend storage
+    if (isMCPEnabled()) {
+      const mcp = getMCPClient()
+      if (mcp) {
+        mcp.storeImpulse(fullImpulse).catch((err: Error) => {
+          console.warn(`[Impulse] Failed to store in backend: ${err.message}`)
+        })
+      }
+    }
+    
+    return fullImpulse
+  }
+
+  /**
+   * Get an impulse by ID
+   */
+  get(id: string): Impulse | undefined {
+    return this.impulses.get(id)
+  }
+
+  /**
+   * Load an impulse (resolve its pointer and populate content)
+   */
+  async load(id: string): Promise<Impulse> {
+    const impulse = this.impulses.get(id)
+    if (!impulse) {
+      throw new Error(`Impulse not found: ${id}`)
+    }
+
+    if (impulse.loaded && impulse.content) {
+      return impulse
+    }
+
+    const content = await this.resolvePointer(impulse.pointer)
+    const tokenCount = this.estimateTokens(content)
+
+    // Truncate if over budget
+    let finalContent = content
+    if (tokenCount > impulse.budget) {
+      const ratio = impulse.budget / tokenCount
+      const targetChars = Math.floor(content.length * ratio * 0.9) // 10% safety margin
+      finalContent = content.substring(0, targetChars) + "\n... (truncated to fit budget)"
+    }
+
+    const loadedImpulse: Impulse = {
+      ...impulse,
+      loaded: true,
+      content: finalContent,
+      tokenCount: Math.min(tokenCount, impulse.budget),
+    }
+
+    this.impulses.set(id, loadedImpulse)
+    return loadedImpulse
+  }
+
+  /**
+   * Unload an impulse (free memory)
+   */
+  unload(id: string): void {
+    const impulse = this.impulses.get(id)
+    if (impulse) {
+      this.impulses.set(id, {
+        ...impulse,
+        loaded: false,
+        content: undefined,
+        tokenCount: undefined,
+      })
+    }
+  }
+
+  /**
+   * Delete an impulse
+   */
+  delete(id: string): boolean {
+    return this.impulses.delete(id)
+  }
+
+  /**
+   * List all impulses
+   */
+  list(): Impulse[] {
+    return Array.from(this.impulses.values())
+  }
+
+  /**
+   * Register a custom resolver
+   */
+  registerResolver(name: string, resolver: (data: Record<string, unknown>) => Promise<string>): void {
+    this.customResolvers.set(name, resolver)
+  }
+
+  /**
+   * Store activity output for activityOutput pointer resolution
+   */
+  storeActivityOutput(activityId: string, taskId: string, output: string): void {
+    if (!this.activityOutputs.has(activityId)) {
+      this.activityOutputs.set(activityId, new Map())
+    }
+    this.activityOutputs.get(activityId)!.set(taskId, output)
+  }
+
+  /**
+   * Get activity output
+   */
+  getActivityOutput(activityId: string, taskId?: string): string | undefined {
+    const outputs = this.activityOutputs.get(activityId)
+    if (!outputs) return undefined
+    
+    if (taskId) {
+      return outputs.get(taskId)
+    }
+    
+    // Return all outputs concatenated
+    return Array.from(outputs.values()).join("\n\n---\n\n")
+  }
+
+  /**
+   * Resolve a pointer to content
+   * 
+   * Architecture: MiniBob handles LOCAL types (memo, file) directly.
+   * All other types are delegated to backend via MCP.
+   */
+  private async resolvePointer(pointer: ImpulsePointer): Promise<string> {
+    // LOCAL TYPE: memo (content embedded in pointer)
+    if (pointer.type === "memo" && "content" in pointer) {
+      return pointer.content as string
+    }
+
+    // LOCAL TYPE: file (read from minibob's filesystem)
+    if (pointer.type === "file" && "path" in pointer) {
+      const filePath = pointer.path
+
+      // Validate path exists and is a string
+      if (!filePath || typeof filePath !== 'string') {
+        throw new Error(`Invalid file path in impulse pointer: expected string, got ${typeof filePath}. Pointer: ${JSON.stringify(pointer)}`)
+      }
+
+      let file
+      try {
+        file = Bun.file(filePath)
+      } catch (bunError) {
+        throw new Error(`Bun.file() failed for impulse path '${filePath}': ${bunError instanceof Error ? bunError.message : String(bunError)}`)
+      }
+
+      if (!(await file.exists())) {
+        throw new Error(`File not found: ${filePath}`)
+      }
+
+      const content = await file.text()
+      const lines = content.split("\n")
+      const offset = (pointer as any).offset ?? 0
+      const limit = (pointer as any).limit ?? lines.length
+      return lines.slice(offset, offset + limit).join("\n")
+    }
+
+    // BACKEND TYPES: Delegate to backend via MCP
+    // This includes: activityOutput, activityExecutionTrace, activityTemplate,
+    // activityMetrics, and ANY future types the backend introduces.
+    if (isMCPEnabled()) {
+      const mcp = getMCPClient()
+      if (mcp && "resolveImpulse" in mcp) {
+        try {
+          const content = await (mcp as any).resolveImpulse(pointer)
+          return content
+        } catch (error) {
+          throw new Error(
+            `Failed to resolve impulse type "${pointer.type}" from backend: ${
+              error instanceof Error ? error.message : String(error)
+            }`
+          )
+        }
+      }
+    }
+
+    // FALLBACK: No backend connection
+    // Try local activityOutput store (in-memory only)
+    if (pointer.type === "activityOutput" && "activityId" in pointer) {
+      const output = this.getActivityOutput(
+        pointer.activityId as string,
+        "taskId" in pointer ? (pointer.taskId as string) : undefined
+      )
+      if (output) {
+        console.warn(
+          `[Impulse] Resolved activityOutput from in-memory cache (no backend). ` +
+          `This will not work across executions.`
+        )
+        return output
+      }
+    }
+
+    // No backend and not a local type - fail
+    throw new Error(
+      `Impulse type "${pointer.type}" requires backend connection. ` +
+      `Only "memo" and "file" types work offline. ` +
+      `Please enable MCP connection to metabob-activity-api.`
+    )
+  }
+
+  /**
+   * Estimate token count (rough approximation: 4 chars per token)
+   */
+  private estimateTokens(content: string): number {
+    return Math.ceil(content.length / 4)
+  }
+}
+
+// =============================================================================
+// IMPULSE MANAGER (Singleton)
+// =============================================================================
+
+let store: ImpulseStore | null = null
+
+/**
+ * Get the impulse store (singleton)
+ */
+export function getImpulseStore(): ImpulseStore {
+  if (!store) {
+    store = new ImpulseStore()
+  }
+  return store
+}
+
+/**
+ * Create a new impulse
+ */
+export function createImpulse(impulse: Omit<Impulse, "loaded" | "createdAt">): Impulse {
+  return getImpulseStore().create(impulse)
+}
+
+/**
+ * Load an impulse
+ */
+export async function loadImpulse(id: string): Promise<Impulse> {
+  return getImpulseStore().load(id)
+}
+
+/**
+ * Load multiple impulses
+ */
+export async function loadImpulses(ids: string[]): Promise<Impulse[]> {
+  return Promise.all(ids.map((id) => loadImpulse(id)))
+}
+
+/**
+ * Format impulses for context injection
+ */
+export function formatImpulsesForContext(impulses: Impulse[]): string {
+  if (impulses.length === 0) return ""
+
+  const formatted = impulses
+    .filter((imp) => imp.loaded && imp.content)
+    .map((imp) => {
+      return `<impulse id="${imp.id}" type="${imp.pointer.type}" tokens="${imp.tokenCount ?? 0}/${imp.budget}">
+${imp.content}
+</impulse>`
+    })
+    .join("\n\n")
+
+  return `<impulse_context>
+${formatted}
+</impulse_context>`
+}
+
+/**
+ * Register a custom resolver
+ */
+export function registerResolver(name: string, resolver: (data: Record<string, unknown>) => Promise<string>): void {
+  getImpulseStore().registerResolver(name, resolver)
+}
+
+/**
+ * Store activity output
+ */
+export function storeActivityOutput(activityId: string, taskId: string, output: string): void {
+  getImpulseStore().storeActivityOutput(activityId, taskId, output)
+}