@tanstack/ai-code-mode-snippets 0.3.14

package/src/storage/memory-storage.ts

@@ -0,0 +1,172 @@
+import { createDefaultTrustStrategy } from '../trust-strategies'
+import type {
+  Snippet,
+  SnippetIndexEntry,
+  SnippetSearchOptions,
+  SnippetStorage,
+} from '../types'
+import type { TrustStrategy } from '../trust-strategies'
+
+export interface MemorySnippetStorageOptions {
+  /**
+   * Initial snippets to populate the storage with
+   */
+  initialSnippets?: Array<Snippet>
+
+  /**
+   * Trust strategy for determining snippet trust levels
+   * @default createDefaultTrustStrategy()
+   */
+  trustStrategy?: TrustStrategy
+}
+
+/**
+ * In-memory snippet storage for testing and demos
+ */
+export function createMemorySnippetStorage(
+  optionsOrSnippets: MemorySnippetStorageOptions | Array<Snippet> = [],
+): SnippetStorage {
+  const options = Array.isArray(optionsOrSnippets)
+    ? { initialSnippets: optionsOrSnippets }
+    : optionsOrSnippets
+
+  const { initialSnippets = [], trustStrategy = createDefaultTrustStrategy() } =
+    options
+
+  // Store snippets in a Map for O(1) lookup
+  const snippets = new Map<string, Snippet>()
+
+  // Initialize with any provided snippets
+  for (const snippet of initialSnippets) {
+    snippets.set(snippet.name, snippet)
+  }
+
+  function loadIndex(): Promise<Array<SnippetIndexEntry>> {
+    return Promise.resolve(
+      Array.from(snippets.values()).map((snippet) => ({
+        id: snippet.id,
+        name: snippet.name,
+        description: snippet.description,
+        usageHints: snippet.usageHints,
+        trustLevel: snippet.trustLevel,
+      })),
+    )
+  }
+
+  function loadAll(): Promise<Array<Snippet>> {
+    return Promise.resolve(Array.from(snippets.values()))
+  }
+
+  function get(name: string): Promise<Snippet | null> {
+    return Promise.resolve(snippets.get(name) ?? null)
+  }
+
+  function save(
+    snippet: Omit<Snippet, 'createdAt' | 'updatedAt'>,
+  ): Promise<Snippet> {
+    const now = new Date().toISOString()
+    const existing = snippets.get(snippet.name)
+
+    const fullSnippet: Snippet = {
+      ...snippet,
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    }
+
+    snippets.set(snippet.name, fullSnippet)
+    return Promise.resolve(fullSnippet)
+  }
+
+  function deleteSnippet(name: string): Promise<boolean> {
+    if (!snippets.has(name)) {
+      return Promise.resolve(false)
+    }
+    snippets.delete(name)
+    return Promise.resolve(true)
+  }
+
+  function search(
+    query: string,
+    searchOptions: SnippetSearchOptions = {},
+  ): Promise<Array<SnippetIndexEntry>> {
+    const { limit = 5 } = searchOptions
+
+    // Simple text matching
+    const queryLower = query.toLowerCase()
+    const terms = queryLower.split(/\s+/)
+
+    const scored = Array.from(snippets.values()).map((snippet) => {
+      let score = 0
+      const searchText = [
+        snippet.name,
+        snippet.description,
+        ...snippet.usageHints,
+      ]
+        .join(' ')
+        .toLowerCase()
+
+      for (const term of terms) {
+        if (searchText.includes(term)) {
+          score += 1
+        }
+        // Boost exact name matches
+        if (snippet.name.toLowerCase().includes(term)) {
+          score += 2
+        }
+      }
+
+      return { snippet, score }
+    })
+
+    return Promise.resolve(
+      scored
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map((s) => ({
+          id: s.snippet.id,
+          name: s.snippet.name,
+          description: s.snippet.description,
+          usageHints: s.snippet.usageHints,
+          trustLevel: s.snippet.trustLevel,
+        })),
+    )
+  }
+
+  function updateStats(name: string, success: boolean): Promise<void> {
+    const snippet = snippets.get(name)
+    if (!snippet) return Promise.resolve()
+
+    const { executions, successRate } = snippet.stats
+    const newExecutions = executions + 1
+    const newSuccessRate =
+      (successRate * executions + (success ? 1 : 0)) / newExecutions
+
+    const newStats = { executions: newExecutions, successRate: newSuccessRate }
+
+    // Use trust strategy to calculate new trust level
+    const newTrustLevel = trustStrategy.calculateTrustLevel(
+      snippet.trustLevel,
+      newStats,
+    )
+
+    snippets.set(name, {
+      ...snippet,
+      stats: newStats,
+      trustLevel: newTrustLevel,
+      updatedAt: new Date().toISOString(),
+    })
+    return Promise.resolve()
+  }
+
+  return {
+    loadIndex,
+    loadAll,
+    get,
+    save,
+    delete: deleteSnippet,
+    search,
+    updateStats,
+    trustStrategy,
+  }
+}

package/src/trust-strategies.ts

@@ -0,0 +1,142 @@
+import type { SnippetStats, TrustLevel } from './types'
+
+/**
+ * Strategy for determining snippet trust levels
+ */
+export interface TrustStrategy {
+  /**
+   * Get the initial trust level for a newly created snippet
+   */
+  getInitialTrustLevel: () => TrustLevel
+
+  /**
+   * Calculate the new trust level based on execution stats
+   */
+  calculateTrustLevel: (
+    currentLevel: TrustLevel,
+    stats: SnippetStats,
+  ) => TrustLevel
+}
+
+/**
+ * Default trust strategy - snippets must earn trust through successful executions
+ *
+ * - untrusted: New snippet (0 executions)
+ * - provisional: 10+ executions with ≥90% success rate
+ * - trusted: 100+ executions with ≥95% success rate
+ */
+export function createDefaultTrustStrategy(): TrustStrategy {
+  return {
+    getInitialTrustLevel: () => 'untrusted',
+
+    calculateTrustLevel: (currentLevel, stats) => {
+      const { executions, successRate } = stats
+
+      if (
+        currentLevel === 'untrusted' &&
+        executions >= 10 &&
+        successRate >= 0.9
+      ) {
+        return 'provisional'
+      }
+
+      if (
+        currentLevel === 'provisional' &&
+        executions >= 100 &&
+        successRate >= 0.95
+      ) {
+        return 'trusted'
+      }
+
+      return currentLevel
+    },
+  }
+}
+
+/**
+ * Always trusted strategy - snippets are immediately trusted upon creation
+ *
+ * Use this for development/testing or when you trust the LLM's code generation
+ */
+export function createAlwaysTrustedStrategy(): TrustStrategy {
+  return {
+    getInitialTrustLevel: () => 'trusted',
+    calculateTrustLevel: () => 'trusted',
+  }
+}
+
+/**
+ * Relaxed trust strategy - faster trust promotion for development
+ *
+ * - untrusted: New snippet (0 executions)
+ * - provisional: 3+ executions with ≥80% success rate
+ * - trusted: 10+ executions with ≥90% success rate
+ */
+export function createRelaxedTrustStrategy(): TrustStrategy {
+  return {
+    getInitialTrustLevel: () => 'untrusted',
+
+    calculateTrustLevel: (currentLevel, stats) => {
+      const { executions, successRate } = stats
+
+      if (
+        currentLevel === 'untrusted' &&
+        executions >= 3 &&
+        successRate >= 0.8
+      ) {
+        return 'provisional'
+      }
+
+      if (
+        currentLevel === 'provisional' &&
+        executions >= 10 &&
+        successRate >= 0.9
+      ) {
+        return 'trusted'
+      }
+
+      return currentLevel
+    },
+  }
+}
+
+/**
+ * Custom trust strategy with configurable thresholds
+ */
+export function createCustomTrustStrategy(config: {
+  initialLevel?: TrustLevel
+  provisionalThreshold?: { executions: number; successRate: number }
+  trustedThreshold?: { executions: number; successRate: number }
+}): TrustStrategy {
+  const {
+    initialLevel = 'untrusted',
+    provisionalThreshold = { executions: 10, successRate: 0.9 },
+    trustedThreshold = { executions: 100, successRate: 0.95 },
+  } = config
+
+  return {
+    getInitialTrustLevel: () => initialLevel,
+
+    calculateTrustLevel: (currentLevel, stats) => {
+      const { executions, successRate } = stats
+
+      if (
+        currentLevel === 'untrusted' &&
+        executions >= provisionalThreshold.executions &&
+        successRate >= provisionalThreshold.successRate
+      ) {
+        return 'provisional'
+      }
+
+      if (
+        currentLevel === 'provisional' &&
+        executions >= trustedThreshold.executions &&
+        successRate >= trustedThreshold.successRate
+      ) {
+        return 'trusted'
+      }
+
+      return currentLevel
+    },
+  }
+}

package/src/types.ts

@@ -0,0 +1,289 @@
+import type { AnyTextAdapter, ModelMessage, ToolRegistry } from '@tanstack/ai'
+import type { CodeModeToolConfig } from '@tanstack/ai-code-mode'
+import type { TrustStrategy } from './trust-strategies'
+
+// ============================================================================
+// Trust Levels
+// ============================================================================
+
+/**
+ * Trust level for a snippet
+ * - untrusted: Newly created, not yet proven
+ * - provisional: Has been successfully executed 10+ times with 90%+ success
+ * - trusted: Has been successfully executed 100+ times with 95%+ success
+ */
+export type TrustLevel = 'untrusted' | 'provisional' | 'trusted'
+
+// ============================================================================
+// Snippet Statistics
+// ============================================================================
+
+/**
+ * Execution statistics for a snippet
+ */
+export interface SnippetStats {
+  /**
+   * Total number of times this snippet has been executed
+   */
+  executions: number
+
+  /**
+   * Success rate (0-1) based on execution history
+   */
+  successRate: number
+}
+
+// ============================================================================
+// Snippet Types
+// ============================================================================
+
+/**
+ * A reusable snippet that can be executed in the Code Mode sandbox
+ */
+export interface Snippet {
+  /**
+   * Unique identifier for the snippet
+   */
+  id: string
+
+  /**
+   * Unique name in snake_case (e.g., 'fetch_github_stats')
+   * This becomes the function name with snippet_ prefix in the sandbox
+   */
+  name: string
+
+  /**
+   * Human-readable description of what the snippet does
+   */
+  description: string
+
+  /**
+   * TypeScript code that implements the snippet
+   * The code receives `input` as a variable and can call:
+   * - external_* functions (tools)
+   * - other snippet_* functions (snippets)
+   * Should return a value
+   */
+  code: string
+
+  /**
+   * JSON Schema describing the input parameter
+   */
+  inputSchema: Record<string, unknown>
+
+  /**
+   * JSON Schema describing the return value
+   */
+  outputSchema: Record<string, unknown>
+
+  /**
+   * Hints about when to use this snippet
+   * e.g., "Use when comparing NPM package popularity"
+   */
+  usageHints: Array<string>
+
+  /**
+   * Names of other snippets this snippet depends on/calls
+   */
+  dependsOn: Array<string>
+
+  /**
+   * Trust level based on execution history
+   */
+  trustLevel: TrustLevel
+
+  /**
+   * Execution statistics
+   */
+  stats: SnippetStats
+
+  /**
+   * ISO timestamp when the snippet was created
+   */
+  createdAt: string
+
+  /**
+   * ISO timestamp when the snippet was last updated
+   */
+  updatedAt: string
+}
+
+// ============================================================================
+// Snippet Index Types
+// ============================================================================
+
+/**
+ * Lightweight snippet entry for the index (metadata only, no code)
+ * Used for fast loading and snippet selection
+ */
+export type SnippetIndexEntry = Pick<
+  Snippet,
+  'id' | 'name' | 'description' | 'usageHints' | 'trustLevel'
+>
+
+// ============================================================================
+// Storage Interface
+// ============================================================================
+
+/**
+ * Options for searching snippets
+ */
+export interface SnippetSearchOptions {
+  /**
+   * Maximum number of results to return
+   * @default 5
+   */
+  limit?: number
+}
+
+/**
+ * Interface for snippet storage implementations
+ */
+export interface SnippetStorage {
+  /**
+   * Load the snippet index (lightweight metadata for all snippets)
+   */
+  loadIndex: () => Promise<Array<SnippetIndexEntry>>
+
+  /**
+   * Load all snippets with full details (including code)
+   */
+  loadAll: () => Promise<Array<Snippet>>
+
+  /**
+   * Get a snippet by name
+   */
+  get: (name: string) => Promise<Snippet | null>
+
+  /**
+   * Save a snippet (create or update)
+   */
+  save: (snippet: Omit<Snippet, 'createdAt' | 'updatedAt'>) => Promise<Snippet>
+
+  /**
+   * Delete a snippet by name
+   */
+  delete: (name: string) => Promise<boolean>
+
+  /**
+   * Search for snippets by query
+   */
+  search: (
+    query: string,
+    options?: SnippetSearchOptions,
+  ) => Promise<Array<SnippetIndexEntry>>
+
+  /**
+   * Update execution statistics for a snippet
+   */
+  updateStats: (name: string, success: boolean) => Promise<void>
+
+  /**
+   * Trust strategy used by this storage (optional, for creating new snippets)
+   */
+  trustStrategy?: TrustStrategy
+}
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+/**
+ * Configuration for the snippets system
+ */
+export interface SnippetsConfig {
+  /**
+   * Storage implementation for snippets
+   */
+  storage: SnippetStorage
+
+  /**
+   * Maximum number of snippets to load into context per request
+   * @default 5
+   */
+  maxSnippetsInContext?: number
+
+  /**
+   * Trust strategy for determining snippet trust levels
+   * @default createDefaultTrustStrategy()
+   */
+  trustStrategy?: TrustStrategy
+}
+
+/**
+ * Options for codeModeWithSnippets
+ */
+export interface CodeModeWithSnippetsOptions {
+  /**
+   * Code Mode tool configuration (driver, tools, timeout, memoryLimit)
+   */
+  config: CodeModeToolConfig
+
+  /**
+   * Text adapter for snippet selection (should be a cheap/fast model)
+   */
+  adapter: AnyTextAdapter
+
+  /**
+   * Snippets configuration
+   */
+  snippets: SnippetsConfig
+
+  /**
+   * Current conversation messages (used for context-aware snippet selection)
+   */
+  messages: Array<ModelMessage>
+
+  /**
+   * Whether to include snippets as direct tools (not just sandbox bindings).
+   * When true, snippets become first-class tools the LLM can call directly.
+   * @default true
+   */
+  snippetsAsTools?: boolean
+}
+
+/**
+ * Result from codeModeWithSnippets
+ */
+export interface CodeModeWithSnippetsResult {
+  /**
+   * Tool registry for dynamic tool management.
+   * Pass this to chat() via the toolRegistry option.
+   * Snippets registered mid-stream will be added to this registry.
+   */
+  toolsRegistry: ToolRegistry
+
+  /**
+   * System prompt documenting available snippets and external functions
+   */
+  systemPrompt: string
+
+  /**
+   * Snippets that were selected for this request
+   */
+  selectedSnippets: Array<Snippet>
+}
+
+// ============================================================================
+// Snippet Binding Types (internal)
+// ============================================================================
+
+/**
+ * A snippet transformed into a format suitable for sandbox injection
+ */
+export interface SnippetBinding {
+  /**
+   * Function name with snippet_ prefix
+   */
+  name: string
+
+  /**
+   * The snippet this binding wraps
+   */
+  snippet: Snippet
+
+  /**
+   * Execute function that runs the snippet code
+   */
+  execute: (input: unknown) => Promise<unknown>
+}