@tanstack/ai-code-mode-snippets 0.3.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# @tanstack/ai-code-mode-snippets
+
+Persistent snippet library for TanStack AI Code Mode - LLM-created reusable code snippets.
+
+## Overview
+
+The Snippets System extends Code Mode with persistent, LLM-creatable reusable code snippets. Snippets are TypeScript functions that the LLM can create, catalog, and invoke across sessions—enabling compounding capability over time.
+
+## Installation
+
+```bash
+pnpm add @tanstack/ai-code-mode-snippets
+```
+
+## Usage
+
+```typescript
+import {
+  codeModeWithSnippets,
+  createAlwaysTrustedStrategy,
+} from '@tanstack/ai-code-mode-snippets'
+// Node-only file storage lives behind the `/storage` subpath so the root
+// export stays safe for Worker/browser bundlers.
+import { createFileSnippetStorage } from '@tanstack/ai-code-mode-snippets/storage'
+import { createNodeIsolateDriver } from '@tanstack/ai-isolate-node'
+
+// Create snippet storage
+const snippetStorage = createFileSnippetStorage({
+  directory: './.snippets',
+  trustStrategy: createAlwaysTrustedStrategy(),
+})
+
+// Create code mode config
+const codeModeConfig = {
+  driver: createNodeIsolateDriver(),
+  tools: allTools, // Your external tools
+  timeout: 60000,
+  memoryLimit: 128,
+}
+
+// Build a dynamic registry and system prompt with snippets
+const { toolsRegistry, systemPrompt, selectedSnippets } =
+  await codeModeWithSnippets({
+    config: codeModeConfig,
+    adapter: anthropic('claude-3-haiku'), // Cheap model for snippet selection
+    snippets: {
+      storage: snippetStorage,
+      maxSnippetsInContext: 5,
+    },
+    messages,
+  })
+
+// Use in chat
+const stream = chat({
+  adapter: anthropic('claude-sonnet-4-20250514'), // Main model
+  toolRegistry: toolsRegistry,
+  messages,
+  systemPrompts: [basePrompt, systemPrompt],
+})
+```
+
+## Testing
+
+This package includes a CLI for testing the snippets system. The tests verify the complete snippets lifecycle:
+
+1. **First run (Snippet Creation)**: LLM uses `execute_typescript` to solve a problem and registers a reusable snippet
+2. **Second run (Snippet Reuse)**: LLM calls the saved snippet directly without needing `execute_typescript`
+
+### Running the Simulated Test
+
+The simulated test uses a mock adapter with predetermined responses for fully deterministic testing. No API key required.
+
+```bash
+# From the package directory
+cd packages/ai-code-mode-snippets
+
+# Run the simulated test
+pnpm test:cli:simulated
+```
+
+### Running the Live Test
+
+The live test uses a real LLM (OpenAI or Anthropic) to verify the snippets flow with actual LLM responses.
+
+#### Setup
+
+1. Copy the environment example file:
+
+   ```bash
+   cp test-cli/env.example test-cli/.env.local
+   ```
+
+2. Edit `test-cli/.env.local` and add your API key:
+   ```
+   OPENAI_API_KEY=sk-...
+   # or
+   ANTHROPIC_API_KEY=sk-ant-...
+   ```
+
+#### Run the test
+
+```bash
+# Run with OpenAI (default)
+pnpm test:cli:live
+
+# Run with Anthropic
+pnpm test:cli:live --provider anthropic
+
+# Run with a specific model
+pnpm test:cli:live --model gpt-4o-mini
+
+# Run with verbose output
+pnpm test:cli:live -v
+```
+
+### CLI Commands
+
+```bash
+# Show help
+pnpm test:cli --help
+
+# Run simulated test (deterministic, no API key)
+pnpm test:cli simulated
+
+# Run live test (requires API key)
+pnpm test:cli live [options]
+
+Options:
+  --provider <provider>  LLM provider: openai or anthropic (default: openai)
+  --model <model>        Model to use (default depends on provider)
+  -v, --verbose          Enable verbose output
+```
+
+## API Reference
+
+### `codeModeWithSnippets(options)`
+
+Creates Code Mode tools and system prompt with snippets integration.
+
+**Options:**
+
+- `config` - Code Mode tool configuration (driver, tools, timeout, memoryLimit)
+- `adapter` - Text adapter for snippet selection (should be a cheap/fast model)
+- `snippets.storage` - Snippet storage implementation
+- `snippets.maxSnippetsInContext` - Maximum snippets to load into context (default: 5)
+- `messages` - Current conversation messages
+- `snippetsAsTools` - Whether to include snippets as direct tools (default: true)
+
+**Returns:**
+
+- `toolsRegistry` - Mutable `ToolRegistry` containing `execute_typescript`, snippet management tools, and selected snippet tools
+- `systemPrompt` - System prompt documenting available snippets and external functions
+- `selectedSnippets` - Snippets that were selected for this request
+
+### Storage
+
+The worker/browser-safe in-memory storage (`createMemorySnippetStorage`) is
+re-exported from the root entry. The Node-only file storage
+(`createFileSnippetStorage`) imports `node:fs` / `node:path`, so it is only
+available from the `/storage` subpath — keeping the root export safe to import
+from Cloudflare Workers and browser bundlers:
+
+```typescript
+// Worker/browser-safe — root export
+import { createMemorySnippetStorage } from '@tanstack/ai-code-mode-snippets'
+
+// Node-only — `/storage` subpath
+import { createFileSnippetStorage } from '@tanstack/ai-code-mode-snippets/storage'
+```
+
+#### `createFileSnippetStorage(options)`
+
+Git-friendly file-based storage:
+
+```text
+.snippets/
+├── compare_react_state_libraries/
+│   ├── meta.json      # Metadata, schemas, stats
+│   └── code.ts        # TypeScript implementation
+└── fetch_github_stats/
+    ├── meta.json
+    └── code.ts
+```
+
+#### `createMemorySnippetStorage(options)`
+
+In-memory storage for testing.
+
+### Trust Strategies
+
+Snippets track execution success and promote trust levels over time:
+
+| Trust Level   | Description                       |
+| ------------- | --------------------------------- |
+| `untrusted`   | Newly created, not yet proven     |
+| `provisional` | 10+ executions with ≥90% success  |
+| `trusted`     | 100+ executions with ≥95% success |
+
+Available strategies:
+
+- `createDefaultTrustStrategy()` - Earn trust through successful executions
+- `createAlwaysTrustedStrategy()` - Trust immediately (dev/testing)
+- `createRelaxedTrustStrategy()` - Faster promotion
+- `createCustomTrustStrategy(options)` - Custom thresholds
+
+## License
+
+MIT

package/dist/esm/code-mode-with-snippets.d.ts

@@ -0,0 +1,65 @@
+import { CodeModeWithSnippetsOptions, CodeModeWithSnippetsResult, Snippet } from './types.js';
+import { 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 declare function codeModeWithSnippets({ config, adapter, snippets, messages, snippetsAsTools, }: CodeModeWithSnippetsOptions): Promise<CodeModeWithSnippetsResult>;
+/**
+ * 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 declare function createCodeModeWithSnippetsConfig({ config, selectedSnippets, storage, }: {
+    config: CodeModeWithSnippetsOptions['config'];
+    selectedSnippets: Array<Snippet>;
+    storage: CodeModeWithSnippetsOptions['snippets']['storage'];
+}): {
+    snippetTools: import('@tanstack/ai').ServerTool<import('@tanstack/ai').SchemaInput, import('@tanstack/ai').SchemaInput, string, unknown, false, undefined>[];
+    selectedSnippets: Snippet[];
+    driver: import('@tanstack/ai-code-mode').IsolateDriver;
+    tools: Array<import('@tanstack/ai-code-mode').CodeModeTool>;
+    timeout?: number;
+    memoryLimit?: number;
+    getSnippetBindings?: () => Promise<Record<string, ToolBinding>>;
+    onSecretParameter?: import('@tanstack/ai-code-mode').SecretParameterHandler;
+    lazyToolsConfig?: import('@tanstack/ai').LazyToolsConfig;
+    transpile?: (code: string) => string | Promise<string>;
+};

package/dist/esm/code-mode-with-snippets.js

@@ -0,0 +1,145 @@
+import { selectRelevantSnippets } from "./select-relevant-snippets.js";
+import { snippetsToTools } from "./snippets-to-tools.js";
+import { createSnippetManagementTools } from "./create-snippet-management-tools.js";
+import { createSnippetsSystemPrompt } from "./create-snippets-system-prompt.js";
+import { createCodeModeSystemPrompt, createCodeModeTool, toolsToBindings } from "@tanstack/ai-code-mode";
+import { createToolRegistry } from "@tanstack/ai";
+//#region src/code-mode-with-snippets.ts
+/**
+* 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],
+* });
+* ```
+*/
+async function codeModeWithSnippets({ config, adapter, snippets, messages, snippetsAsTools = true }) {
+	const { storage, maxSnippetsInContext = 5 } = snippets;
+	const snippetIndex = await storage.loadIndex();
+	const selectedSnippets = await selectRelevantSnippets({
+		adapter,
+		messages,
+		snippetIndex,
+		maxSnippets: maxSnippetsInContext,
+		storage
+	});
+	const baseBindings = toolsToBindings(config.tools, "external_");
+	const codeModeTool = createCodeModeTool({
+		...config,
+		getSnippetBindings: async () => {
+			const allSnippets = await storage.loadAll();
+			const snippetBindings = {};
+			for (const snippet of allSnippets) snippetBindings[`snippet_${snippet.name}`] = {
+				name: `snippet_${snippet.name}`,
+				description: snippet.description,
+				inputSchema: snippet.inputSchema,
+				outputSchema: snippet.outputSchema,
+				execute: async (input) => {
+					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 !== void 0 && { 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;
+		}
+	});
+	const registry = createToolRegistry();
+	registry.add(codeModeTool);
+	const snippetManagementTools = createSnippetManagementTools({
+		storage,
+		registry,
+		config,
+		baseBindings
+	});
+	for (const tool of snippetManagementTools) registry.add(tool);
+	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);
+	}
+	const basePrompt = createCodeModeSystemPrompt(config);
+	const snippetsPrompt = createSnippetsSystemPrompt({
+		selectedSnippets,
+		totalSnippetCount: snippetIndex.length,
+		snippetsAsTools
+	});
+	return {
+		toolsRegistry: registry,
+		systemPrompt: basePrompt + "\n\n" + snippetsPrompt,
+		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.
+*/
+function createCodeModeWithSnippetsConfig({ config, selectedSnippets, storage }) {
+	const snippetToolsList = snippetsToTools({
+		snippets: selectedSnippets,
+		driver: config.driver,
+		tools: config.tools,
+		storage,
+		timeout: config.timeout,
+		memoryLimit: config.memoryLimit
+	});
+	return {
+		...config,
+		snippetTools: snippetToolsList,
+		selectedSnippets
+	};
+}
+//#endregion
+export { codeModeWithSnippets, createCodeModeWithSnippetsConfig };
+
+//# sourceMappingURL=code-mode-with-snippets.js.map

package/dist/esm/code-mode-with-snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-mode-with-snippets.js","names":[],"sources":["../../src/code-mode-with-snippets.ts"],"sourcesContent":["import {\n  createCodeModeSystemPrompt,\n  createCodeModeTool,\n  toolsToBindings,\n} from '@tanstack/ai-code-mode'\nimport { createToolRegistry } from '@tanstack/ai'\nimport { selectRelevantSnippets } from './select-relevant-snippets'\nimport { createSnippetManagementTools } from './create-snippet-management-tools'\nimport { createSnippetsSystemPrompt } from './create-snippets-system-prompt'\nimport { snippetsToTools } from './snippets-to-tools'\nimport type {\n  CodeModeWithSnippetsOptions,\n  CodeModeWithSnippetsResult,\n  Snippet,\n} from './types'\nimport type { ToolBinding } from '@tanstack/ai-code-mode'\n\nexport type { CodeModeWithSnippetsOptions, CodeModeWithSnippetsResult }\n\n/**\n * Create Code Mode tools and system prompt with snippets integration.\n *\n * This function:\n * 1. Loads the snippet index from storage\n * 2. Uses a cheap/fast LLM to select relevant snippets based on conversation context\n * 3. Creates the execute_typescript tool with dynamic snippet bindings\n * 4. Creates snippet management tools (search, get, register)\n * 5. Generates system prompts documenting available snippets\n * 6. Returns a ToolRegistry that allows dynamic snippet additions mid-stream\n *\n * @example\n * ```typescript\n * // Node-only file storage lives behind the `/storage` subpath:\n * import { createFileSnippetStorage } from '@tanstack/ai-code-mode-snippets/storage'\n *\n * const { toolsRegistry, systemPrompt, selectedSnippets } = await codeModeWithSnippets({\n *   config: {\n *     driver: createNodeIsolateDriver(),\n *     tools: allTools,\n *     timeout: 60000,\n *   },\n *   adapter: openaiText('gpt-4o-mini'),  // Cheap model for selection\n *   snippets: {\n *     storage: createFileSnippetStorage('./.snippets'),\n *     maxSnippetsInContext: 5,\n *   },\n *   messages,\n * });\n *\n * const stream = chat({\n *   adapter: openaiText('gpt-4o'),  // Main model\n *   toolRegistry: toolsRegistry,  // Dynamic tool registry\n *   messages,\n *   systemPrompts: [BASE_PROMPT, systemPrompt],\n * });\n * ```\n */\nexport async function codeModeWithSnippets({\n  config,\n  adapter,\n  snippets,\n  messages,\n  snippetsAsTools = true,\n}: CodeModeWithSnippetsOptions): Promise<CodeModeWithSnippetsResult> {\n  const { storage, maxSnippetsInContext = 5 } = snippets\n\n  // 1. Load the snippet index (lightweight metadata only)\n  const snippetIndex = await storage.loadIndex()\n\n  // 2. Use adapter to select relevant snippets based on transcript\n  const selectedSnippets = await selectRelevantSnippets({\n    adapter,\n    messages,\n    snippetIndex,\n    maxSnippets: maxSnippetsInContext,\n    storage,\n  })\n\n  // Pre-compute bindings from base tools (shared across snippet executions)\n  const baseBindings = toolsToBindings(config.tools, 'external_')\n\n  // 3. Create the execute_typescript tool with dynamic snippet bindings\n  const codeModeTool = createCodeModeTool({\n    ...config,\n    // Dynamic snippet bindings - fetched at execution time\n    getSnippetBindings: async () => {\n      // Get all snippets from storage (includes newly registered ones)\n      const allSnippets = await storage.loadAll()\n      // Convert to bindings with snippet_ prefix\n      const snippetBindings: Record<string, ToolBinding> = {}\n      for (const snippet of allSnippets) {\n        // Create a simple binding that executes the snippet code\n        snippetBindings[`snippet_${snippet.name}`] = {\n          name: `snippet_${snippet.name}`,\n          description: snippet.description,\n          inputSchema: snippet.inputSchema,\n          outputSchema: snippet.outputSchema,\n          execute: async (input: unknown) => {\n            // This is a simplified execution - the full snippetToTool handles events\n            const wrappedCode = `const input = ${JSON.stringify(input)};\\n${snippet.code}`\n            const { stripTypeScript, createEventAwareBindings } =\n              await import('@tanstack/ai-code-mode')\n            const strippedCode = await stripTypeScript(wrappedCode)\n            const context = await config.driver.createContext({\n              bindings: createEventAwareBindings(baseBindings, () => {}),\n              timeout: config.timeout,\n              ...(config.memoryLimit !== undefined && {\n                memoryLimit: config.memoryLimit,\n              }),\n            })\n            try {\n              const result = await context.execute(strippedCode)\n              if (!result.success) {\n                throw new Error(\n                  result.error?.message || 'Snippet execution failed',\n                )\n              }\n              return result.value\n            } finally {\n              await context.dispose()\n            }\n          },\n        }\n      }\n      return snippetBindings\n    },\n  })\n\n  // 4. Create a mutable tool registry\n  const registry = createToolRegistry()\n\n  // 5. Add the execute_typescript tool to the registry\n  registry.add(codeModeTool)\n\n  // 6. Create snippet management tools (they need access to the registry)\n  const snippetManagementTools = createSnippetManagementTools({\n    storage,\n    registry,\n    config,\n    baseBindings,\n  })\n\n  for (const tool of snippetManagementTools) {\n    registry.add(tool)\n  }\n\n  // 7. Convert selected snippets to direct tools and add to registry (if enabled)\n  if (snippetsAsTools && selectedSnippets.length > 0) {\n    const snippetToolsList = snippetsToTools({\n      snippets: selectedSnippets,\n      driver: config.driver,\n      tools: config.tools,\n      storage,\n      timeout: config.timeout,\n      memoryLimit: config.memoryLimit,\n    })\n\n    for (const snippetTool of snippetToolsList) {\n      registry.add(snippetTool)\n    }\n  }\n\n  // 8. Generate combined system prompt\n  const basePrompt = createCodeModeSystemPrompt(config)\n  const snippetsPrompt = createSnippetsSystemPrompt({\n    selectedSnippets,\n    totalSnippetCount: snippetIndex.length,\n    snippetsAsTools,\n  })\n  const systemPrompt = basePrompt + '\\n\\n' + snippetsPrompt\n\n  return {\n    toolsRegistry: registry,\n    systemPrompt,\n    selectedSnippets,\n  }\n}\n\n/**\n * Create a Code Mode tool configuration extended with snippets.\n * This is an alternative to codeModeWithSnippets that returns\n * a config object instead of directly creating tools.\n *\n * Useful when you want more control over the tool creation process.\n */\nexport function createCodeModeWithSnippetsConfig({\n  config,\n  selectedSnippets,\n  storage,\n}: {\n  config: CodeModeWithSnippetsOptions['config']\n  selectedSnippets: Array<Snippet>\n  storage: CodeModeWithSnippetsOptions['snippets']['storage']\n}) {\n  // Create snippet tools for direct calling\n  const snippetToolsList = snippetsToTools({\n    snippets: selectedSnippets,\n    driver: config.driver,\n    tools: config.tools,\n    storage,\n    timeout: config.timeout,\n    memoryLimit: config.memoryLimit,\n  })\n\n  return {\n    ...config,\n    snippetTools: snippetToolsList,\n    selectedSnippets,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,eAAsB,qBAAqB,EACzC,QACA,SACA,UACA,UACA,kBAAkB,QACiD;CACnE,MAAM,EAAE,SAAS,uBAAuB,MAAM;CAG9C,MAAM,eAAe,MAAM,QAAQ,UAAU;CAG7C,MAAM,mBAAmB,MAAM,uBAAuB;EACpD;EACA;EACA;EACA,aAAa;EACb;CACF,CAAC;CAGD,MAAM,eAAe,gBAAgB,OAAO,OAAO,WAAW;CAG9D,MAAM,eAAe,mBAAmB;EACtC,GAAG;EAEH,oBAAoB,YAAY;GAE9B,MAAM,cAAc,MAAM,QAAQ,QAAQ;GAE1C,MAAM,kBAA+C,CAAC;GACtD,KAAK,MAAM,WAAW,aAEpB,gBAAgB,WAAW,QAAQ,UAAU;IAC3C,MAAM,WAAW,QAAQ;IACzB,aAAa,QAAQ;IACrB,aAAa,QAAQ;IACrB,cAAc,QAAQ;IACtB,SAAS,OAAO,UAAmB;KAEjC,MAAM,cAAc,iBAAiB,KAAK,UAAU,KAAK,EAAE,KAAK,QAAQ;KACxE,MAAM,EAAE,iBAAiB,6BACvB,MAAM,OAAO;KACf,MAAM,eAAe,MAAM,gBAAgB,WAAW;KACtD,MAAM,UAAU,MAAM,OAAO,OAAO,cAAc;MAChD,UAAU,yBAAyB,oBAAoB,CAAC,CAAC;MACzD,SAAS,OAAO;MAChB,GAAI,OAAO,gBAAgB,KAAA,KAAa,EACtC,aAAa,OAAO,YACtB;KACF,CAAC;KACD,IAAI;MACF,MAAM,SAAS,MAAM,QAAQ,QAAQ,YAAY;MACjD,IAAI,CAAC,OAAO,SACV,MAAM,IAAI,MACR,OAAO,OAAO,WAAW,0BAC3B;MAEF,OAAO,OAAO;KAChB,UAAU;MACR,MAAM,QAAQ,QAAQ;KACxB;IACF;GACF;GAEF,OAAO;EACT;CACF,CAAC;CAGD,MAAM,WAAW,mBAAmB;CAGpC,SAAS,IAAI,YAAY;CAGzB,MAAM,yBAAyB,6BAA6B;EAC1D;EACA;EACA;EACA;CACF,CAAC;CAED,KAAK,MAAM,QAAQ,wBACjB,SAAS,IAAI,IAAI;CAInB,IAAI,mBAAmB,iBAAiB,SAAS,GAAG;EAClD,MAAM,mBAAmB,gBAAgB;GACvC,UAAU;GACV,QAAQ,OAAO;GACf,OAAO,OAAO;GACd;GACA,SAAS,OAAO;GAChB,aAAa,OAAO;EACtB,CAAC;EAED,KAAK,MAAM,eAAe,kBACxB,SAAS,IAAI,WAAW;CAE5B;CAGA,MAAM,aAAa,2BAA2B,MAAM;CACpD,MAAM,iBAAiB,2BAA2B;EAChD;EACA,mBAAmB,aAAa;EAChC;CACF,CAAC;CAGD,OAAO;EACL,eAAe;EACf,cAJmB,aAAa,SAAS;EAKzC;CACF;AACF;;;;;;;;AASA,SAAgB,iCAAiC,EAC/C,QACA,kBACA,WAKC;CAED,MAAM,mBAAmB,gBAAgB;EACvC,UAAU;EACV,QAAQ,OAAO;EACf,OAAO,OAAO;EACd;EACA,SAAS,OAAO;EAChB,aAAa,OAAO;CACtB,CAAC;CAED,OAAO;EACL,GAAG;EACH,cAAc;EACd;CACF;AACF"}

package/dist/esm/create-snippet-management-tools.d.ts

@@ -0,0 +1,40 @@
+import { SchemaInput, ServerTool, ToolRegistry } from '@tanstack/ai';
+import { CodeModeToolConfig, ToolBinding } from '@tanstack/ai-code-mode';
+import { SnippetStorage } from './types.js';
+import { TrustStrategy } from './trust-strategies.js';
+interface CreateSnippetManagementToolsOptions {
+    /**
+     * Storage implementation for snippets
+     */
+    storage: SnippetStorage;
+    /**
+     * Trust strategy for determining initial trust level.
+     * If not provided, uses the storage's trustStrategy or falls back to default.
+     */
+    trustStrategy?: TrustStrategy;
+    /**
+     * Tool registry for adding newly registered snippets immediately.
+     * When provided, register_snippet will add the new snippet to this registry
+     * so it's available as a direct tool in the current chat session.
+     */
+    registry?: ToolRegistry;
+    /**
+     * Code mode config for creating snippet tools.
+     * Required when registry is provided.
+     */
+    config?: CodeModeToolConfig;
+    /**
+     * Pre-computed bindings for external_* functions.
+     * Required when registry is provided.
+     */
+    baseBindings?: Record<string, ToolBinding>;
+}
+/**
+ * Create tools for searching, retrieving, and registering snippets.
+ * These tools allow the LLM to interact with the snippet library at runtime.
+ *
+ * When registry, config, and baseBindings are provided, newly registered snippets
+ * will be immediately added to the registry and available as direct tools.
+ */
+export declare function createSnippetManagementTools({ storage, trustStrategy, registry, config, baseBindings, }: CreateSnippetManagementToolsOptions): Array<ServerTool<SchemaInput, SchemaInput, string>>;
+export {};

package/dist/esm/create-snippet-management-tools.js

@@ -0,0 +1,173 @@
+import { createDefaultTrustStrategy } from "./trust-strategies.js";
+import { snippetToTool } from "./snippets-to-tools.js";
+import { toolsToBindings } from "@tanstack/ai-code-mode";
+import { toolDefinition } from "@tanstack/ai";
+import { z } from "zod";
+//#region src/create-snippet-management-tools.ts
+/**
+* Create tools for searching, retrieving, and registering snippets.
+* These tools allow the LLM to interact with the snippet library at runtime.
+*
+* When registry, config, and baseBindings are provided, newly registered snippets
+* will be immediately added to the registry and available as direct tools.
+*/
+function createSnippetManagementTools({ storage, trustStrategy, registry, config, baseBindings }) {
+	const strategy = trustStrategy ?? storage.trustStrategy ?? createDefaultTrustStrategy();
+	const bindings = baseBindings ?? (config ? toolsToBindings(config.tools, "external_") : {});
+	return [
+		toolDefinition({
+			name: "search_snippets",
+			description: "Search the snippet library for reusable snippets. Use this to find snippets that can help accomplish a task. Returns matching snippets with their descriptions.",
+			inputSchema: z.object({
+				query: z.string().describe("Search query describing what you want to accomplish"),
+				limit: z.number().optional().default(5).describe("Maximum number of results (default: 5)")
+			}),
+			outputSchema: z.array(z.object({
+				name: z.string(),
+				description: z.string(),
+				usageHints: z.array(z.string()),
+				trustLevel: z.enum([
+					"untrusted",
+					"provisional",
+					"trusted"
+				])
+			}))
+		}).server(async ({ query, limit }) => {
+			return (await storage.search(query, { limit: limit ?? 5 })).map((s) => ({
+				name: s.name,
+				description: s.description,
+				usageHints: s.usageHints,
+				trustLevel: s.trustLevel
+			}));
+		}),
+		toolDefinition({
+			name: "get_snippet",
+			description: "Get the full implementation details of a snippet, including its code. Use this after search_snippets to see how a snippet works before using it.",
+			inputSchema: z.object({ name: z.string().describe("The snippet name (without snippet_ prefix)") }),
+			outputSchema: z.object({
+				name: z.string().optional(),
+				description: z.string().optional(),
+				code: z.string().optional(),
+				inputSchema: z.string().optional().describe("JSON Schema as string"),
+				outputSchema: z.string().optional().describe("JSON Schema as string"),
+				usageHints: z.array(z.string()).optional(),
+				dependsOn: z.array(z.string()).optional(),
+				trustLevel: z.enum([
+					"untrusted",
+					"provisional",
+					"trusted"
+				]).optional(),
+				stats: z.object({
+					executions: z.number(),
+					successRate: z.number()
+				}).optional(),
+				error: z.string().optional()
+			})
+		}).server(async ({ name }) => {
+			const snippet = await storage.get(name);
+			if (!snippet) return { error: `Snippet '${name}' not found` };
+			return {
+				name: snippet.name,
+				description: snippet.description,
+				code: snippet.code,
+				inputSchema: JSON.stringify(snippet.inputSchema),
+				outputSchema: JSON.stringify(snippet.outputSchema),
+				usageHints: snippet.usageHints,
+				dependsOn: snippet.dependsOn,
+				trustLevel: snippet.trustLevel,
+				stats: snippet.stats
+			};
+		}),
+		toolDefinition({
+			name: "register_snippet",
+			description: "Save working TypeScript code as a reusable snippet for future use. Only register code that has been tested and works correctly. The snippet becomes available as a callable tool immediately.",
+			inputSchema: z.object({
+				name: z.string().regex(/^[a-z][a-z0-9_]*$/, "Must be snake_case starting with a letter").describe("Unique snippet name in snake_case (e.g., fetch_github_stats)"),
+				description: z.string().describe("Clear description of what the snippet does"),
+				code: z.string().describe("The TypeScript code. Receives `input` variable, can call external_* and snippet_* functions, should return a value."),
+				inputSchema: z.string().describe("JSON Schema as a JSON string describing the input parameter, e.g. {\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"number\"}},\"required\":[\"a\"]}"),
+				outputSchema: z.string().describe("JSON Schema as a JSON string describing the return value, e.g. {\"type\":\"object\",\"properties\":{\"result\":{\"type\":\"number\"}}}"),
+				usageHints: z.array(z.string()).describe("Hints about when to use this snippet, e.g. \"Use when user asks about...\""),
+				dependsOn: z.array(z.string()).optional().default([]).describe("Names of other snippets this snippet calls")
+			}),
+			outputSchema: z.object({
+				success: z.boolean().optional(),
+				snippetId: z.string().optional(),
+				name: z.string().optional(),
+				message: z.string().optional(),
+				error: z.string().optional()
+			})
+		}).server(async (rawSnippetDef, context) => {
+			let inputSchema;
+			let outputSchema;
+			try {
+				inputSchema = JSON.parse(rawSnippetDef.inputSchema);
+			} catch {
+				return { error: "inputSchema must be a valid JSON string" };
+			}
+			try {
+				outputSchema = JSON.parse(rawSnippetDef.outputSchema);
+			} catch {
+				return { error: "outputSchema must be a valid JSON string" };
+			}
+			const snippetDef = {
+				...rawSnippetDef,
+				inputSchema,
+				outputSchema
+			};
+			try {
+				if (snippetDef.name.startsWith("external_")) return { error: "Snippet names cannot start with 'external_'" };
+				if (snippetDef.name.startsWith("snippet_")) return { error: "Snippet names should not include the 'snippet_' prefix - it will be added automatically" };
+				if (await storage.get(snippetDef.name)) return { error: `Snippet '${snippetDef.name}' already exists. Use a different name or update the existing snippet.` };
+				const id = crypto.randomUUID();
+				const initialTrustLevel = strategy.getInitialTrustLevel();
+				const snippet = await storage.save({
+					id,
+					name: snippetDef.name,
+					description: snippetDef.description,
+					code: snippetDef.code,
+					inputSchema: snippetDef.inputSchema,
+					outputSchema: snippetDef.outputSchema,
+					usageHints: snippetDef.usageHints,
+					dependsOn: snippetDef.dependsOn ?? [],
+					trustLevel: initialTrustLevel,
+					stats: {
+						executions: 0,
+						successRate: 0
+					}
+				});
+				if (registry && config) {
+					const snippetTool = snippetToTool({
+						snippet,
+						driver: config.driver,
+						bindings,
+						storage,
+						timeout: config.timeout,
+						memoryLimit: config.memoryLimit
+					});
+					registry.add(snippetTool);
+					console.log(`[register_snippet] Added snippet '${snippet.name}' to registry immediately`);
+				}
+				context?.emitCustomEvent("snippet:registered", {
+					id: snippet.id,
+					name: snippet.name,
+					description: snippet.description,
+					timestamp: Date.now()
+				});
+				return {
+					success: true,
+					snippetId: snippet.id,
+					name: snippet.name,
+					message: `Snippet '${snippet.name}' registered successfully and is now available as the '${snippet.name}' tool.`
+				};
+			} catch (error) {
+				console.error("[register_snippet] Error:", error);
+				return { error: `Failed to register snippet: ${error instanceof Error ? error.message : String(error)}` };
+			}
+		})
+	];
+}
+//#endregion
+export { createSnippetManagementTools };
+
+//# sourceMappingURL=create-snippet-management-tools.js.map