@tanstack/ai-code-mode-snippets 0.3.14

package/dist/esm/storage/memory-storage.js.map

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

package/dist/esm/trust-strategies.d.ts

@@ -0,0 +1,50 @@
+import { SnippetStats, TrustLevel } from './types.js';
+/**
+ * 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 declare function createDefaultTrustStrategy(): TrustStrategy;
+/**
+ * Always trusted strategy - snippets are immediately trusted upon creation
+ *
+ * Use this for development/testing or when you trust the LLM's code generation
+ */
+export declare function createAlwaysTrustedStrategy(): TrustStrategy;
+/**
+ * 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 declare function createRelaxedTrustStrategy(): TrustStrategy;
+/**
+ * Custom trust strategy with configurable thresholds
+ */
+export declare function createCustomTrustStrategy(config: {
+    initialLevel?: TrustLevel;
+    provisionalThreshold?: {
+        executions: number;
+        successRate: number;
+    };
+    trustedThreshold?: {
+        executions: number;
+        successRate: number;
+    };
+}): TrustStrategy;

package/dist/esm/trust-strategies.js

@@ -0,0 +1,73 @@
+//#region src/trust-strategies.ts
+/**
+* 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
+*/
+function createDefaultTrustStrategy() {
+	return {
+		getInitialTrustLevel: () => "untrusted",
+		calculateTrustLevel: (currentLevel, stats) => {
+			const { executions, successRate } = stats;
+			if (currentLevel === "untrusted" && executions >= 10 && successRate >= .9) return "provisional";
+			if (currentLevel === "provisional" && executions >= 100 && successRate >= .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
+*/
+function createAlwaysTrustedStrategy() {
+	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
+*/
+function createRelaxedTrustStrategy() {
+	return {
+		getInitialTrustLevel: () => "untrusted",
+		calculateTrustLevel: (currentLevel, stats) => {
+			const { executions, successRate } = stats;
+			if (currentLevel === "untrusted" && executions >= 3 && successRate >= .8) return "provisional";
+			if (currentLevel === "provisional" && executions >= 10 && successRate >= .9) return "trusted";
+			return currentLevel;
+		}
+	};
+}
+/**
+* Custom trust strategy with configurable thresholds
+*/
+function createCustomTrustStrategy(config) {
+	const { initialLevel = "untrusted", provisionalThreshold = {
+		executions: 10,
+		successRate: .9
+	}, trustedThreshold = {
+		executions: 100,
+		successRate: .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;
+		}
+	};
+}
+//#endregion
+export { createAlwaysTrustedStrategy, createCustomTrustStrategy, createDefaultTrustStrategy, createRelaxedTrustStrategy };
+
+//# sourceMappingURL=trust-strategies.js.map

package/dist/esm/trust-strategies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-strategies.js","names":[],"sources":["../../src/trust-strategies.ts"],"sourcesContent":["import type { SnippetStats, TrustLevel } from './types'\n\n/**\n * Strategy for determining snippet trust levels\n */\nexport interface TrustStrategy {\n  /**\n   * Get the initial trust level for a newly created snippet\n   */\n  getInitialTrustLevel: () => TrustLevel\n\n  /**\n   * Calculate the new trust level based on execution stats\n   */\n  calculateTrustLevel: (\n    currentLevel: TrustLevel,\n    stats: SnippetStats,\n  ) => TrustLevel\n}\n\n/**\n * Default trust strategy - snippets must earn trust through successful executions\n *\n * - untrusted: New snippet (0 executions)\n * - provisional: 10+ executions with ≥90% success rate\n * - trusted: 100+ executions with ≥95% success rate\n */\nexport function createDefaultTrustStrategy(): TrustStrategy {\n  return {\n    getInitialTrustLevel: () => 'untrusted',\n\n    calculateTrustLevel: (currentLevel, stats) => {\n      const { executions, successRate } = stats\n\n      if (\n        currentLevel === 'untrusted' &&\n        executions >= 10 &&\n        successRate >= 0.9\n      ) {\n        return 'provisional'\n      }\n\n      if (\n        currentLevel === 'provisional' &&\n        executions >= 100 &&\n        successRate >= 0.95\n      ) {\n        return 'trusted'\n      }\n\n      return currentLevel\n    },\n  }\n}\n\n/**\n * Always trusted strategy - snippets are immediately trusted upon creation\n *\n * Use this for development/testing or when you trust the LLM's code generation\n */\nexport function createAlwaysTrustedStrategy(): TrustStrategy {\n  return {\n    getInitialTrustLevel: () => 'trusted',\n    calculateTrustLevel: () => 'trusted',\n  }\n}\n\n/**\n * Relaxed trust strategy - faster trust promotion for development\n *\n * - untrusted: New snippet (0 executions)\n * - provisional: 3+ executions with ≥80% success rate\n * - trusted: 10+ executions with ≥90% success rate\n */\nexport function createRelaxedTrustStrategy(): TrustStrategy {\n  return {\n    getInitialTrustLevel: () => 'untrusted',\n\n    calculateTrustLevel: (currentLevel, stats) => {\n      const { executions, successRate } = stats\n\n      if (\n        currentLevel === 'untrusted' &&\n        executions >= 3 &&\n        successRate >= 0.8\n      ) {\n        return 'provisional'\n      }\n\n      if (\n        currentLevel === 'provisional' &&\n        executions >= 10 &&\n        successRate >= 0.9\n      ) {\n        return 'trusted'\n      }\n\n      return currentLevel\n    },\n  }\n}\n\n/**\n * Custom trust strategy with configurable thresholds\n */\nexport function createCustomTrustStrategy(config: {\n  initialLevel?: TrustLevel\n  provisionalThreshold?: { executions: number; successRate: number }\n  trustedThreshold?: { executions: number; successRate: number }\n}): TrustStrategy {\n  const {\n    initialLevel = 'untrusted',\n    provisionalThreshold = { executions: 10, successRate: 0.9 },\n    trustedThreshold = { executions: 100, successRate: 0.95 },\n  } = config\n\n  return {\n    getInitialTrustLevel: () => initialLevel,\n\n    calculateTrustLevel: (currentLevel, stats) => {\n      const { executions, successRate } = stats\n\n      if (\n        currentLevel === 'untrusted' &&\n        executions >= provisionalThreshold.executions &&\n        successRate >= provisionalThreshold.successRate\n      ) {\n        return 'provisional'\n      }\n\n      if (\n        currentLevel === 'provisional' &&\n        executions >= trustedThreshold.executions &&\n        successRate >= trustedThreshold.successRate\n      ) {\n        return 'trusted'\n      }\n\n      return currentLevel\n    },\n  }\n}\n"],"mappings":";;;;;;;;AA2BA,SAAgB,6BAA4C;CAC1D,OAAO;EACL,4BAA4B;EAE5B,sBAAsB,cAAc,UAAU;GAC5C,MAAM,EAAE,YAAY,gBAAgB;GAEpC,IACE,iBAAiB,eACjB,cAAc,MACd,eAAe,IAEf,OAAO;GAGT,IACE,iBAAiB,iBACjB,cAAc,OACd,eAAe,KAEf,OAAO;GAGT,OAAO;EACT;CACF;AACF;;;;;;AAOA,SAAgB,8BAA6C;CAC3D,OAAO;EACL,4BAA4B;EAC5B,2BAA2B;CAC7B;AACF;;;;;;;;AASA,SAAgB,6BAA4C;CAC1D,OAAO;EACL,4BAA4B;EAE5B,sBAAsB,cAAc,UAAU;GAC5C,MAAM,EAAE,YAAY,gBAAgB;GAEpC,IACE,iBAAiB,eACjB,cAAc,KACd,eAAe,IAEf,OAAO;GAGT,IACE,iBAAiB,iBACjB,cAAc,MACd,eAAe,IAEf,OAAO;GAGT,OAAO;EACT;CACF;AACF;;;;AAKA,SAAgB,0BAA0B,QAIxB;CAChB,MAAM,EACJ,eAAe,aACf,uBAAuB;EAAE,YAAY;EAAI,aAAa;CAAI,GAC1D,mBAAmB;EAAE,YAAY;EAAK,aAAa;CAAK,MACtD;CAEJ,OAAO;EACL,4BAA4B;EAE5B,sBAAsB,cAAc,UAAU;GAC5C,MAAM,EAAE,YAAY,gBAAgB;GAEpC,IACE,iBAAiB,eACjB,cAAc,qBAAqB,cACnC,eAAe,qBAAqB,aAEpC,OAAO;GAGT,IACE,iBAAiB,iBACjB,cAAc,iBAAiB,cAC/B,eAAe,iBAAiB,aAEhC,OAAO;GAGT,OAAO;EACT;CACF;AACF"}

package/dist/esm/types.d.ts

@@ -0,0 +1,216 @@
+import { AnyTextAdapter, ModelMessage, ToolRegistry } from '@tanstack/ai';
+import { CodeModeToolConfig } from '@tanstack/ai-code-mode';
+import { TrustStrategy } from './trust-strategies.js';
+/**
+ * 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';
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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'>;
+/**
+ * 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 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>;
+}
+/**
+ * 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>;
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@tanstack/ai-code-mode-snippets",
+  "version": "0.3.14",
+  "description": "Persistent runtime snippet library for TanStack AI Code Mode agents and sandboxed tool orchestration.",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "homepage": "https://tanstack.com/ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-code-mode-snippets"
+  },
+  "bugs": {
+    "url": "https://github.com/TanStack/ai/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./storage": {
+      "types": "./dist/esm/storage/index.d.ts",
+      "import": "./dist/esm/storage/index.js"
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "code-mode",
+    "snippets",
+    "agents",
+    "llm",
+    "sandbox",
+    "tool-calling",
+    "tanstack-intent"
+  ],
+  "dependencies": {
+    "@tanstack/ai": "^0.44.1",
+    "@tanstack/ai-code-mode": "^0.3.11"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0 || ^4.0.0",
+    "@tanstack/ai": "^0.44.1",
+    "@tanstack/ai-code-mode": "^0.3.11"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.1.10",
+    "commander": "^13.1.0",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.23.12",
+    "zod": "^4.2.0",
+    "@tanstack/ai-gemini": "0.23.0",
+    "@tanstack/ai-anthropic": "0.16.5",
+    "@tanstack/ai-openai": "0.19.0",
+    "@tanstack/ai-isolate-node": "0.1.50"
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "test:cli": "tsx test-cli/cli.ts",
+    "test:cli:run": "tsx test-cli/cli.ts run",
+    "test:cli:run:all": "tsx test-cli/cli.ts run --adapters openai,anthropic,gemini",
+    "test:cli:list": "tsx test-cli/cli.ts list",
+    "test:cli:simulated": "tsx test-cli/cli.ts simulated",
+    "test:cli:registry": "tsx test-cli/cli.ts registry",
+    "test:cli:live": "tsx test-cli/cli.ts live",
+    "test:cli:structured": "tsx test-cli/cli.ts structured"
+  }
+}

package/src/code-mode-with-snippets.ts

@@ -0,0 +1,210 @@
+import {
+  createCodeModeSystemPrompt,
+  createCodeModeTool,
+  toolsToBindings,
+} from '@tanstack/ai-code-mode'
+import { createToolRegistry } from '@tanstack/ai'
+import { selectRelevantSnippets } from './select-relevant-snippets'
+import { createSnippetManagementTools } from './create-snippet-management-tools'
+import { createSnippetsSystemPrompt } from './create-snippets-system-prompt'
+import { snippetsToTools } from './snippets-to-tools'
+import type {
+  CodeModeWithSnippetsOptions,
+  CodeModeWithSnippetsResult,
+  Snippet,
+} from './types'
+import type { ToolBinding } from '@tanstack/ai-code-mode'
+
+export type { CodeModeWithSnippetsOptions, CodeModeWithSnippetsResult }
+
+/**
+ * Create Code Mode tools and system prompt with snippets integration.
+ *
+ * This function:
+ * 1. Loads the snippet index from storage
+ * 2. Uses a cheap/fast LLM to select relevant snippets based on conversation context
+ * 3. Creates the execute_typescript tool with dynamic snippet bindings
+ * 4. Creates snippet management tools (search, get, register)
+ * 5. Generates system prompts documenting available snippets
+ * 6. Returns a ToolRegistry that allows dynamic snippet additions mid-stream
+ *
+ * @example
+ * ```typescript
+ * // Node-only file storage lives behind the `/storage` subpath:
+ * import { createFileSnippetStorage } from '@tanstack/ai-code-mode-snippets/storage'
+ *
+ * const { toolsRegistry, systemPrompt, selectedSnippets } = await codeModeWithSnippets({
+ *   config: {
+ *     driver: createNodeIsolateDriver(),
+ *     tools: allTools,
+ *     timeout: 60000,
+ *   },
+ *   adapter: openaiText('gpt-4o-mini'),  // Cheap model for selection
+ *   snippets: {
+ *     storage: createFileSnippetStorage('./.snippets'),
+ *     maxSnippetsInContext: 5,
+ *   },
+ *   messages,
+ * });
+ *
+ * const stream = chat({
+ *   adapter: openaiText('gpt-4o'),  // Main model
+ *   toolRegistry: toolsRegistry,  // Dynamic tool registry
+ *   messages,
+ *   systemPrompts: [BASE_PROMPT, systemPrompt],
+ * });
+ * ```
+ */
+export async function codeModeWithSnippets({
+  config,
+  adapter,
+  snippets,
+  messages,
+  snippetsAsTools = true,
+}: CodeModeWithSnippetsOptions): Promise<CodeModeWithSnippetsResult> {
+  const { storage, maxSnippetsInContext = 5 } = snippets
+
+  // 1. Load the snippet index (lightweight metadata only)
+  const snippetIndex = await storage.loadIndex()
+
+  // 2. Use adapter to select relevant snippets based on transcript
+  const selectedSnippets = await selectRelevantSnippets({
+    adapter,
+    messages,
+    snippetIndex,
+    maxSnippets: maxSnippetsInContext,
+    storage,
+  })
+
+  // Pre-compute bindings from base tools (shared across snippet executions)
+  const baseBindings = toolsToBindings(config.tools, 'external_')
+
+  // 3. Create the execute_typescript tool with dynamic snippet bindings
+  const codeModeTool = createCodeModeTool({
+    ...config,
+    // Dynamic snippet bindings - fetched at execution time
+    getSnippetBindings: async () => {
+      // Get all snippets from storage (includes newly registered ones)
+      const allSnippets = await storage.loadAll()
+      // Convert to bindings with snippet_ prefix
+      const snippetBindings: Record<string, ToolBinding> = {}
+      for (const snippet of allSnippets) {
+        // Create a simple binding that executes the snippet code
+        snippetBindings[`snippet_${snippet.name}`] = {
+          name: `snippet_${snippet.name}`,
+          description: snippet.description,
+          inputSchema: snippet.inputSchema,
+          outputSchema: snippet.outputSchema,
+          execute: async (input: unknown) => {
+            // This is a simplified execution - the full snippetToTool handles events
+            const wrappedCode = `const input = ${JSON.stringify(input)};\n${snippet.code}`
+            const { stripTypeScript, createEventAwareBindings } =
+              await import('@tanstack/ai-code-mode')
+            const strippedCode = await stripTypeScript(wrappedCode)
+            const context = await config.driver.createContext({
+              bindings: createEventAwareBindings(baseBindings, () => {}),
+              timeout: config.timeout,
+              ...(config.memoryLimit !== undefined && {
+                memoryLimit: config.memoryLimit,
+              }),
+            })
+            try {
+              const result = await context.execute(strippedCode)
+              if (!result.success) {
+                throw new Error(
+                  result.error?.message || 'Snippet execution failed',
+                )
+              }
+              return result.value
+            } finally {
+              await context.dispose()
+            }
+          },
+        }
+      }
+      return snippetBindings
+    },
+  })
+
+  // 4. Create a mutable tool registry
+  const registry = createToolRegistry()
+
+  // 5. Add the execute_typescript tool to the registry
+  registry.add(codeModeTool)
+
+  // 6. Create snippet management tools (they need access to the registry)
+  const snippetManagementTools = createSnippetManagementTools({
+    storage,
+    registry,
+    config,
+    baseBindings,
+  })
+
+  for (const tool of snippetManagementTools) {
+    registry.add(tool)
+  }
+
+  // 7. Convert selected snippets to direct tools and add to registry (if enabled)
+  if (snippetsAsTools && selectedSnippets.length > 0) {
+    const snippetToolsList = snippetsToTools({
+      snippets: selectedSnippets,
+      driver: config.driver,
+      tools: config.tools,
+      storage,
+      timeout: config.timeout,
+      memoryLimit: config.memoryLimit,
+    })
+
+    for (const snippetTool of snippetToolsList) {
+      registry.add(snippetTool)
+    }
+  }
+
+  // 8. Generate combined system prompt
+  const basePrompt = createCodeModeSystemPrompt(config)
+  const snippetsPrompt = createSnippetsSystemPrompt({
+    selectedSnippets,
+    totalSnippetCount: snippetIndex.length,
+    snippetsAsTools,
+  })
+  const systemPrompt = basePrompt + '\n\n' + snippetsPrompt
+
+  return {
+    toolsRegistry: registry,
+    systemPrompt,
+    selectedSnippets,
+  }
+}
+
+/**
+ * Create a Code Mode tool configuration extended with snippets.
+ * This is an alternative to codeModeWithSnippets that returns
+ * a config object instead of directly creating tools.
+ *
+ * Useful when you want more control over the tool creation process.
+ */
+export function createCodeModeWithSnippetsConfig({
+  config,
+  selectedSnippets,
+  storage,
+}: {
+  config: CodeModeWithSnippetsOptions['config']
+  selectedSnippets: Array<Snippet>
+  storage: CodeModeWithSnippetsOptions['snippets']['storage']
+}) {
+  // Create snippet tools for direct calling
+  const snippetToolsList = snippetsToTools({
+    snippets: selectedSnippets,
+    driver: config.driver,
+    tools: config.tools,
+    storage,
+    timeout: config.timeout,
+    memoryLimit: config.memoryLimit,
+  })
+
+  return {
+    ...config,
+    snippetTools: snippetToolsList,
+    selectedSnippets,
+  }
+}