@tanstack/ai-code-mode-snippets 0.3.14

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-snippet-management-tools.js","names":[],"sources":["../../src/create-snippet-management-tools.ts"],"sourcesContent":["import { toolDefinition } from '@tanstack/ai'\nimport { toolsToBindings } from '@tanstack/ai-code-mode'\nimport { z } from 'zod'\nimport { createDefaultTrustStrategy } from './trust-strategies'\nimport { snippetToTool } from './snippets-to-tools'\nimport type { SchemaInput, ServerTool, ToolRegistry } from '@tanstack/ai'\nimport type { CodeModeToolConfig, ToolBinding } from '@tanstack/ai-code-mode'\nimport type { SnippetStorage } from './types'\nimport type { TrustStrategy } from './trust-strategies'\n\ninterface CreateSnippetManagementToolsOptions {\n  /**\n   * Storage implementation for snippets\n   */\n  storage: SnippetStorage\n\n  /**\n   * Trust strategy for determining initial trust level.\n   * If not provided, uses the storage's trustStrategy or falls back to default.\n   */\n  trustStrategy?: TrustStrategy\n\n  /**\n   * Tool registry for adding newly registered snippets immediately.\n   * When provided, register_snippet will add the new snippet to this registry\n   * so it's available as a direct tool in the current chat session.\n   */\n  registry?: ToolRegistry\n\n  /**\n   * Code mode config for creating snippet tools.\n   * Required when registry is provided.\n   */\n  config?: CodeModeToolConfig\n\n  /**\n   * Pre-computed bindings for external_* functions.\n   * Required when registry is provided.\n   */\n  baseBindings?: Record<string, ToolBinding>\n}\n\n/**\n * Create tools for searching, retrieving, and registering snippets.\n * These tools allow the LLM to interact with the snippet library at runtime.\n *\n * When registry, config, and baseBindings are provided, newly registered snippets\n * will be immediately added to the registry and available as direct tools.\n */\nexport function createSnippetManagementTools({\n  storage,\n  trustStrategy,\n  registry,\n  config,\n  baseBindings,\n}: CreateSnippetManagementToolsOptions): Array<\n  ServerTool<SchemaInput, SchemaInput, string>\n> {\n  // Use provided strategy, or storage's strategy, or default\n  const strategy =\n    trustStrategy ?? storage.trustStrategy ?? createDefaultTrustStrategy()\n\n  // Compute bindings if not provided but config is available\n  const bindings =\n    baseBindings ?? (config ? toolsToBindings(config.tools, 'external_') : {})\n  return [\n    // Search for snippets\n    toolDefinition({\n      name: 'search_snippets',\n      description:\n        'Search the snippet library for reusable snippets. Use this to find snippets that can help accomplish a task. Returns matching snippets with their descriptions.',\n      inputSchema: z.object({\n        query: z\n          .string()\n          .describe('Search query describing what you want to accomplish'),\n        limit: z\n          .number()\n          .optional()\n          .default(5)\n          .describe('Maximum number of results (default: 5)'),\n      }),\n      outputSchema: z.array(\n        z.object({\n          name: z.string(),\n          description: z.string(),\n          usageHints: z.array(z.string()),\n          trustLevel: z.enum(['untrusted', 'provisional', 'trusted']),\n        }),\n      ),\n    }).server(async ({ query, limit }) => {\n      const results = await storage.search(query, { limit: limit ?? 5 })\n      return results.map((s) => ({\n        name: s.name,\n        description: s.description,\n        usageHints: s.usageHints,\n        trustLevel: s.trustLevel,\n      }))\n    }),\n\n    // Get full snippet details\n    toolDefinition({\n      name: 'get_snippet',\n      description:\n        '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.',\n      inputSchema: z.object({\n        name: z.string().describe('The snippet name (without snippet_ prefix)'),\n      }),\n      outputSchema: z.object({\n        name: z.string().optional(),\n        description: z.string().optional(),\n        code: z.string().optional(),\n        inputSchema: z.string().optional().describe('JSON Schema as string'),\n        outputSchema: z.string().optional().describe('JSON Schema as string'),\n        usageHints: z.array(z.string()).optional(),\n        dependsOn: z.array(z.string()).optional(),\n        trustLevel: z.enum(['untrusted', 'provisional', 'trusted']).optional(),\n        stats: z\n          .object({\n            executions: z.number(),\n            successRate: z.number(),\n          })\n          .optional(),\n        error: z.string().optional(),\n      }),\n    }).server(async ({ name }) => {\n      const snippet = await storage.get(name)\n      if (!snippet) {\n        return { error: `Snippet '${name}' not found` }\n      }\n      return {\n        name: snippet.name,\n        description: snippet.description,\n        code: snippet.code,\n        inputSchema: JSON.stringify(snippet.inputSchema),\n        outputSchema: JSON.stringify(snippet.outputSchema),\n        usageHints: snippet.usageHints,\n        dependsOn: snippet.dependsOn,\n        trustLevel: snippet.trustLevel,\n        stats: snippet.stats,\n      }\n    }),\n\n    // Register a new snippet\n    toolDefinition({\n      name: 'register_snippet',\n      description:\n        '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.',\n      inputSchema: z.object({\n        name: z\n          .string()\n          .regex(\n            /^[a-z][a-z0-9_]*$/,\n            'Must be snake_case starting with a letter',\n          )\n          .describe(\n            'Unique snippet name in snake_case (e.g., fetch_github_stats)',\n          ),\n        description: z\n          .string()\n          .describe('Clear description of what the snippet does'),\n        code: z\n          .string()\n          .describe(\n            'The TypeScript code. Receives `input` variable, can call external_* and snippet_* functions, should return a value.',\n          ),\n        inputSchema: z\n          .string()\n          .describe(\n            'JSON Schema as a JSON string describing the input parameter, e.g. {\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"number\"}},\"required\":[\"a\"]}',\n          ),\n        outputSchema: z\n          .string()\n          .describe(\n            'JSON Schema as a JSON string describing the return value, e.g. {\"type\":\"object\",\"properties\":{\"result\":{\"type\":\"number\"}}}',\n          ),\n        usageHints: z\n          .array(z.string())\n          .describe(\n            'Hints about when to use this snippet, e.g. \"Use when user asks about...\"',\n          ),\n        dependsOn: z\n          .array(z.string())\n          .optional()\n          .default([])\n          .describe('Names of other snippets this snippet calls'),\n      }),\n      outputSchema: z.object({\n        success: z.boolean().optional(),\n        snippetId: z.string().optional(),\n        name: z.string().optional(),\n        message: z.string().optional(),\n        error: z.string().optional(),\n      }),\n    }).server(async (rawSnippetDef, context) => {\n      // Parse the JSON string schemas\n      let inputSchema: Record<string, unknown>\n      let outputSchema: Record<string, unknown>\n      try {\n        inputSchema = JSON.parse(rawSnippetDef.inputSchema) as Record<\n          string,\n          unknown\n        >\n      } catch {\n        return { error: 'inputSchema must be a valid JSON string' }\n      }\n      try {\n        outputSchema = JSON.parse(rawSnippetDef.outputSchema) as Record<\n          string,\n          unknown\n        >\n      } catch {\n        return { error: 'outputSchema must be a valid JSON string' }\n      }\n\n      const snippetDef = {\n        ...rawSnippetDef,\n        inputSchema,\n        outputSchema,\n      }\n      try {\n        // Validate the snippet name isn't reserved\n        if (snippetDef.name.startsWith('external_')) {\n          return { error: \"Snippet names cannot start with 'external_'\" }\n        }\n        if (snippetDef.name.startsWith('snippet_')) {\n          return {\n            error:\n              \"Snippet names should not include the 'snippet_' prefix - it will be added automatically\",\n          }\n        }\n\n        // Check if snippet already exists\n        const existing = await storage.get(snippetDef.name)\n        if (existing) {\n          return {\n            error: `Snippet '${snippetDef.name}' already exists. Use a different name or update the existing snippet.`,\n          }\n        }\n\n        // Generate a unique ID\n        const id = crypto.randomUUID()\n\n        // Get initial trust level from strategy\n        const initialTrustLevel = strategy.getInitialTrustLevel()\n\n        // Save the snippet\n        const snippet = await storage.save({\n          id,\n          name: snippetDef.name,\n          description: snippetDef.description,\n          code: snippetDef.code,\n          inputSchema: snippetDef.inputSchema,\n          outputSchema: snippetDef.outputSchema,\n          usageHints: snippetDef.usageHints,\n          dependsOn: snippetDef.dependsOn ?? [],\n          trustLevel: initialTrustLevel,\n          stats: { executions: 0, successRate: 0 },\n        })\n\n        // If registry and config are available, add the snippet as a tool immediately\n        if (registry && config) {\n          const snippetTool = snippetToTool({\n            snippet,\n            driver: config.driver,\n            bindings,\n            storage,\n            timeout: config.timeout,\n            memoryLimit: config.memoryLimit,\n          })\n          registry.add(snippetTool)\n          console.log(\n            `[register_snippet] Added snippet '${snippet.name}' to registry immediately`,\n          )\n        }\n\n        // Emit event for UI notification\n        context?.emitCustomEvent('snippet:registered', {\n          id: snippet.id,\n          name: snippet.name,\n          description: snippet.description,\n          timestamp: Date.now(),\n        })\n\n        return {\n          success: true,\n          snippetId: snippet.id,\n          name: snippet.name,\n          message: `Snippet '${snippet.name}' registered successfully and is now available as the '${snippet.name}' tool.`,\n        }\n      } catch (error) {\n        console.error('[register_snippet] Error:', error)\n        return {\n          error: `Failed to register snippet: ${error instanceof Error ? error.message : String(error)}`,\n        }\n      }\n    }),\n  ]\n}\n"],"mappings":";;;;;;;;;;;;;AAiDA,SAAgB,6BAA6B,EAC3C,SACA,eACA,UACA,QACA,gBAGA;CAEA,MAAM,WACJ,iBAAiB,QAAQ,iBAAiB,2BAA2B;CAGvE,MAAM,WACJ,iBAAiB,SAAS,gBAAgB,OAAO,OAAO,WAAW,IAAI,CAAC;CAC1E,OAAO;EAEL,eAAe;GACb,MAAM;GACN,aACE;GACF,aAAa,EAAE,OAAO;IACpB,OAAO,EACJ,OAAO,CAAC,CACR,SAAS,qDAAqD;IACjE,OAAO,EACJ,OAAO,CAAC,CACR,SAAS,CAAC,CACV,QAAQ,CAAC,CAAC,CACV,SAAS,wCAAwC;GACtD,CAAC;GACD,cAAc,EAAE,MACd,EAAE,OAAO;IACP,MAAM,EAAE,OAAO;IACf,aAAa,EAAE,OAAO;IACtB,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC;IAC9B,YAAY,EAAE,KAAK;KAAC;KAAa;KAAe;IAAS,CAAC;GAC5D,CAAC,CACH;EACF,CAAC,CAAC,CAAC,OAAO,OAAO,EAAE,OAAO,YAAY;GAEpC,QAAO,MADe,QAAQ,OAAO,OAAO,EAAE,OAAO,SAAS,EAAE,CAAC,EAAA,CAClD,KAAK,OAAO;IACzB,MAAM,EAAE;IACR,aAAa,EAAE;IACf,YAAY,EAAE;IACd,YAAY,EAAE;GAChB,EAAE;EACJ,CAAC;EAGD,eAAe;GACb,MAAM;GACN,aACE;GACF,aAAa,EAAE,OAAO,EACpB,MAAM,EAAE,OAAO,CAAC,CAAC,SAAS,4CAA4C,EACxE,CAAC;GACD,cAAc,EAAE,OAAO;IACrB,MAAM,EAAE,OAAO,CAAC,CAAC,SAAS;IAC1B,aAAa,EAAE,OAAO,CAAC,CAAC,SAAS;IACjC,MAAM,EAAE,OAAO,CAAC,CAAC,SAAS;IAC1B,aAAa,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,uBAAuB;IACnE,cAAc,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,uBAAuB;IACpE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS;IACzC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS;IACxC,YAAY,EAAE,KAAK;KAAC;KAAa;KAAe;IAAS,CAAC,CAAC,CAAC,SAAS;IACrE,OAAO,EACJ,OAAO;KACN,YAAY,EAAE,OAAO;KACrB,aAAa,EAAE,OAAO;IACxB,CAAC,CAAC,CACD,SAAS;IACZ,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS;GAC7B,CAAC;EACH,CAAC,CAAC,CAAC,OAAO,OAAO,EAAE,WAAW;GAC5B,MAAM,UAAU,MAAM,QAAQ,IAAI,IAAI;GACtC,IAAI,CAAC,SACH,OAAO,EAAE,OAAO,YAAY,KAAK,aAAa;GAEhD,OAAO;IACL,MAAM,QAAQ;IACd,aAAa,QAAQ;IACrB,MAAM,QAAQ;IACd,aAAa,KAAK,UAAU,QAAQ,WAAW;IAC/C,cAAc,KAAK,UAAU,QAAQ,YAAY;IACjD,YAAY,QAAQ;IACpB,WAAW,QAAQ;IACnB,YAAY,QAAQ;IACpB,OAAO,QAAQ;GACjB;EACF,CAAC;EAGD,eAAe;GACb,MAAM;GACN,aACE;GACF,aAAa,EAAE,OAAO;IACpB,MAAM,EACH,OAAO,CAAC,CACR,MACC,qBACA,2CACF,CAAC,CACA,SACC,8DACF;IACF,aAAa,EACV,OAAO,CAAC,CACR,SAAS,4CAA4C;IACxD,MAAM,EACH,OAAO,CAAC,CACR,SACC,qHACF;IACF,aAAa,EACV,OAAO,CAAC,CACR,SACC,2JACF;IACF,cAAc,EACX,OAAO,CAAC,CACR,SACC,wIACF;IACF,YAAY,EACT,MAAM,EAAE,OAAO,CAAC,CAAC,CACjB,SACC,4EACF;IACF,WAAW,EACR,MAAM,EAAE,OAAO,CAAC,CAAC,CACjB,SAAS,CAAC,CACV,QAAQ,CAAC,CAAC,CAAC,CACX,SAAS,4CAA4C;GAC1D,CAAC;GACD,cAAc,EAAE,OAAO;IACrB,SAAS,EAAE,QAAQ,CAAC,CAAC,SAAS;IAC9B,WAAW,EAAE,OAAO,CAAC,CAAC,SAAS;IAC/B,MAAM,EAAE,OAAO,CAAC,CAAC,SAAS;IAC1B,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS;IAC7B,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS;GAC7B,CAAC;EACH,CAAC,CAAC,CAAC,OAAO,OAAO,eAAe,YAAY;GAE1C,IAAI;GACJ,IAAI;GACJ,IAAI;IACF,cAAc,KAAK,MAAM,cAAc,WAAW;GAIpD,QAAQ;IACN,OAAO,EAAE,OAAO,0CAA0C;GAC5D;GACA,IAAI;IACF,eAAe,KAAK,MAAM,cAAc,YAAY;GAItD,QAAQ;IACN,OAAO,EAAE,OAAO,2CAA2C;GAC7D;GAEA,MAAM,aAAa;IACjB,GAAG;IACH;IACA;GACF;GACA,IAAI;IAEF,IAAI,WAAW,KAAK,WAAW,WAAW,GACxC,OAAO,EAAE,OAAO,8CAA8C;IAEhE,IAAI,WAAW,KAAK,WAAW,UAAU,GACvC,OAAO,EACL,OACE,0FACJ;IAKF,IAAI,MADmB,QAAQ,IAAI,WAAW,IAAI,GAEhD,OAAO,EACL,OAAO,YAAY,WAAW,KAAK,wEACrC;IAIF,MAAM,KAAK,OAAO,WAAW;IAG7B,MAAM,oBAAoB,SAAS,qBAAqB;IAGxD,MAAM,UAAU,MAAM,QAAQ,KAAK;KACjC;KACA,MAAM,WAAW;KACjB,aAAa,WAAW;KACxB,MAAM,WAAW;KACjB,aAAa,WAAW;KACxB,cAAc,WAAW;KACzB,YAAY,WAAW;KACvB,WAAW,WAAW,aAAa,CAAC;KACpC,YAAY;KACZ,OAAO;MAAE,YAAY;MAAG,aAAa;KAAE;IACzC,CAAC;IAGD,IAAI,YAAY,QAAQ;KACtB,MAAM,cAAc,cAAc;MAChC;MACA,QAAQ,OAAO;MACf;MACA;MACA,SAAS,OAAO;MAChB,aAAa,OAAO;KACtB,CAAC;KACD,SAAS,IAAI,WAAW;KACxB,QAAQ,IACN,qCAAqC,QAAQ,KAAK,0BACpD;IACF;IAGA,SAAS,gBAAgB,sBAAsB;KAC7C,IAAI,QAAQ;KACZ,MAAM,QAAQ;KACd,aAAa,QAAQ;KACrB,WAAW,KAAK,IAAI;IACtB,CAAC;IAED,OAAO;KACL,SAAS;KACT,WAAW,QAAQ;KACnB,MAAM,QAAQ;KACd,SAAS,YAAY,QAAQ,KAAK,yDAAyD,QAAQ,KAAK;IAC1G;GACF,SAAS,OAAO;IACd,QAAQ,MAAM,6BAA6B,KAAK;IAChD,OAAO,EACL,OAAO,+BAA+B,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,IAC7F;GACF;EACF,CAAC;CACH;AACF"}

package/dist/esm/create-snippets-system-prompt.d.ts

@@ -0,0 +1,22 @@
+import { Snippet } from './types.js';
+interface CreateSnippetsSystemPromptOptions {
+    /**
+     * Snippets that were selected for this request
+     */
+    selectedSnippets: Array<Snippet>;
+    /**
+     * Total number of snippets in the library
+     */
+    totalSnippetCount: number;
+    /**
+     * Whether snippets are exposed as direct tools (not just sandbox bindings)
+     * @default true
+     */
+    snippetsAsTools?: boolean;
+}
+/**
+ * Create system prompt documentation for the snippet library.
+ * This is appended to the Code Mode system prompt.
+ */
+export declare function createSnippetsSystemPrompt({ selectedSnippets, totalSnippetCount, snippetsAsTools, }: CreateSnippetsSystemPromptOptions): string;
+export {};

package/dist/esm/create-snippets-system-prompt.js

@@ -0,0 +1,234 @@
+import { generateSnippetTypes } from "./generate-snippet-types.js";
+//#region src/create-snippets-system-prompt.ts
+/**
+* Generate example input from a JSON Schema
+*/
+function generateExampleFromSchema(schema) {
+	if (schema.type === "object" && schema.properties) {
+		const props = schema.properties;
+		const example = {};
+		for (const [key, value] of Object.entries(props)) if (value.type === "string") example[key] = `'example_${key}'`;
+		else if (value.type === "number") example[key] = 0;
+		else if (value.type === "boolean") example[key] = true;
+		else if (value.type === "array") example[key] = [];
+		else example[key] = null;
+		return JSON.stringify(example).replace(/"/g, "");
+	}
+	return "{}";
+}
+/**
+* Create system prompt documentation for the snippet library.
+* This is appended to the Code Mode system prompt.
+*/
+function createSnippetsSystemPrompt({ selectedSnippets, totalSnippetCount, snippetsAsTools = true }) {
+	if (totalSnippetCount === 0) return `## Snippet Library
+
+You have access to a snippet library for storing reusable code. The library is currently empty.
+
+### Snippet Management Tools
+
+- \`search_snippets(query, limit?)\` - Search for snippets (currently empty)
+- \`get_snippet(name)\` - Get full snippet details including code
+- \`register_snippet(...)\` - Save working code as a reusable snippet
+
+When you write useful, reusable code, consider registering it as a snippet for future use.
+
+**Important**: Newly registered snippets become available as tools on the **next message**, not immediately in the current conversation turn.
+`;
+	if (selectedSnippets.length === 0) return `## Snippet Library
+
+You have access to a persistent snippet library with ${totalSnippetCount} snippet${totalSnippetCount === 1 ? "" : "s"}. No snippets were pre-loaded for this conversation based on context.
+
+### Snippet Management Tools
+
+- \`search_snippets(query, limit?)\` - Search for relevant snippets
+- \`get_snippet(name)\` - Get full snippet details including code
+- \`register_snippet(...)\` - Save working code as a reusable snippet
+
+When you write useful, reusable code, consider registering it as a snippet for future use.
+
+**Important**: Newly registered snippets become available as tools on the **next message**, not immediately in the current conversation turn.
+`;
+	if (snippetsAsTools) {
+		const snippetToolDocs = selectedSnippets.map((snippet) => {
+			const inputExample = generateExampleFromSchema(snippet.inputSchema);
+			const trustBadge = snippet.trustLevel === "trusted" ? "✓ trusted" : snippet.trustLevel === "provisional" ? "◐ provisional" : "○ untrusted";
+			return `
+### ${snippet.name} [${trustBadge}]
+
+${snippet.description}
+
+${snippet.usageHints.map((h) => `- ${h}`).join("\n")}
+
+**Input Schema:**
+\`\`\`json
+${JSON.stringify(snippet.inputSchema, null, 2)}
+\`\`\`
+
+**Output Schema:**
+\`\`\`json
+${JSON.stringify(snippet.outputSchema, null, 2)}
+\`\`\`
+
+**Example:**
+Call the \`${snippet.name}\` tool with: ${inputExample}
+`;
+		}).join("\n---\n");
+		return `## Snippet Library
+
+${selectedSnippets.length} snippet${selectedSnippets.length === 1 ? "" : "s"} pre-loaded for this conversation (${totalSnippetCount} total in library).
+
+### Available Snippet Tools
+
+These snippets are available as **direct tools** you can call (marked with [SNIPPET] in description):
+
+${snippetToolDocs}
+
+### Snippet Management Tools
+
+- \`search_snippets(query, limit?)\` - Find additional snippets not pre-loaded
+- \`get_snippet(name)\` - Get full details of any snippet
+- \`register_snippet(...)\` - Save working code as a new snippet
+
+### Using Snippets
+
+Snippets are **regular tools** - call them directly like any other tool. No need to use \`execute_typescript\`.
+
+### Creating New Snippets
+
+When you write useful, reusable code with \`execute_typescript\`, register it:
+
+\`\`\`typescript
+// After verifying code works, call the register_snippet tool
+register_snippet({
+  name: 'compare_npm_packages',
+  description: 'Compare download counts for multiple NPM packages',
+  code: \`
+    const { packages } = input;
+    const results = await Promise.all(
+      packages.map(pkg => external_getNpmDownloads({ package: pkg }))
+    );
+    return packages.map((pkg, i) => ({ package: pkg, downloads: results[i].downloads }))
+      .sort((a, b) => b.downloads - a.downloads);
+  \`,
+  inputSchema: { 
+    type: 'object', 
+    properties: { packages: { type: 'array', items: { type: 'string' } } },
+    required: ['packages']
+  },
+  outputSchema: {
+    type: 'array',
+    items: { type: 'object', properties: { package: { type: 'string' }, downloads: { type: 'number' } } }
+  },
+  usageHints: ['Use when comparing popularity of NPM packages'],
+  dependsOn: [],
+});
+\`\`\`
+
+**Important**: Newly registered snippets become available as tools on the **next message**, not immediately in the current conversation turn.
+`;
+	}
+	const snippetDocs = selectedSnippets.map((snippet) => {
+		const inputExample = generateExampleFromSchema(snippet.inputSchema);
+		const trustBadge = snippet.trustLevel === "trusted" ? "✓ trusted" : snippet.trustLevel === "provisional" ? "◐ provisional" : "○ untrusted";
+		return `
+### snippet_${snippet.name} [${trustBadge}]
+
+${snippet.description}
+
+${snippet.usageHints.map((h) => `- ${h}`).join("\n")}
+
+**Input Schema:**
+\`\`\`json
+${JSON.stringify(snippet.inputSchema, null, 2)}
+\`\`\`
+
+**Output Schema:**
+\`\`\`json
+${JSON.stringify(snippet.outputSchema, null, 2)}
+\`\`\`
+
+**Example:**
+\`\`\`typescript
+const result = await snippet_${snippet.name}(${inputExample});
+\`\`\`
+`;
+	}).join("\n---\n");
+	const typeStubs = generateSnippetTypes(selectedSnippets);
+	return `## Snippet Library
+
+${selectedSnippets.length} snippet${selectedSnippets.length === 1 ? "" : "s"} pre-loaded for this conversation (${totalSnippetCount} total in library).
+
+### Pre-loaded Snippets
+
+These are available as \`snippet_*\` functions in your TypeScript code:
+
+${snippetDocs}
+
+### Type Definitions
+
+\`\`\`typescript
+${typeStubs}
+\`\`\`
+
+### Snippet Management Tools
+
+- \`search_snippets(query, limit?)\` - Find additional snippets not pre-loaded
+- \`get_snippet(name)\` - Get full details of any snippet
+- \`register_snippet(...)\` - Save working code as a new snippet
+
+### Using Snippets
+
+Snippets work just like \`external_*\` functions inside \`execute_typescript\`:
+
+\`\`\`typescript
+// Call a pre-loaded snippet
+const stats = await snippet_fetch_github_stats({ owner: 'tanstack', repo: 'query' });
+
+// Compose snippets with external tools
+const repos = await external_searchRepositories({ query: 'react state' });
+const detailed = await Promise.all(
+  repos.items.slice(0, 5).map(r => 
+    snippet_fetch_github_stats({ owner: r.owner.login, repo: r.name })
+  )
+);
+\`\`\`
+
+### Creating New Snippets
+
+When you write useful, reusable code, register it:
+
+\`\`\`typescript
+// After verifying code works, call the register_snippet tool
+register_snippet({
+  name: 'compare_npm_packages',
+  description: 'Compare download counts for multiple NPM packages',
+  code: \`
+    const { packages } = input;
+    const results = await Promise.all(
+      packages.map(pkg => external_getNpmDownloads({ package: pkg }))
+    );
+    return packages.map((pkg, i) => ({ package: pkg, downloads: results[i].downloads }))
+      .sort((a, b) => b.downloads - a.downloads);
+  \`,
+  inputSchema: { 
+    type: 'object', 
+    properties: { packages: { type: 'array', items: { type: 'string' } } },
+    required: ['packages']
+  },
+  outputSchema: {
+    type: 'array',
+    items: { type: 'object', properties: { package: { type: 'string' }, downloads: { type: 'number' } } }
+  },
+  usageHints: ['Use when comparing popularity of NPM packages'],
+  dependsOn: [],
+});
+\`\`\`
+
+**Important**: Newly registered snippets become available as tools on the **next message**, not immediately in the current conversation turn.
+`;
+}
+//#endregion
+export { createSnippetsSystemPrompt };
+
+//# sourceMappingURL=create-snippets-system-prompt.js.map

package/dist/esm/create-snippets-system-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-snippets-system-prompt.js","names":[],"sources":["../../src/create-snippets-system-prompt.ts"],"sourcesContent":["import { generateSnippetTypes } from './generate-snippet-types'\nimport type { Snippet } from './types'\n\ninterface CreateSnippetsSystemPromptOptions {\n  /**\n   * Snippets that were selected for this request\n   */\n  selectedSnippets: Array<Snippet>\n\n  /**\n   * Total number of snippets in the library\n   */\n  totalSnippetCount: number\n\n  /**\n   * Whether snippets are exposed as direct tools (not just sandbox bindings)\n   * @default true\n   */\n  snippetsAsTools?: boolean\n}\n\n/**\n * Generate example input from a JSON Schema\n */\nfunction generateExampleFromSchema(schema: Record<string, unknown>): string {\n  if (schema.type === 'object' && schema.properties) {\n    const props = schema.properties as Record<string, { type: string }>\n    const example: Record<string, unknown> = {}\n\n    for (const [key, value] of Object.entries(props)) {\n      if (value.type === 'string') example[key] = `'example_${key}'`\n      else if (value.type === 'number') example[key] = 0\n      else if (value.type === 'boolean') example[key] = true\n      else if (value.type === 'array') example[key] = []\n      else example[key] = null\n    }\n\n    return JSON.stringify(example).replace(/\"/g, '')\n  }\n  return '{}'\n}\n\n/**\n * Create system prompt documentation for the snippet library.\n * This is appended to the Code Mode system prompt.\n */\nexport function createSnippetsSystemPrompt({\n  selectedSnippets,\n  totalSnippetCount,\n  snippetsAsTools = true,\n}: CreateSnippetsSystemPromptOptions): string {\n  // No snippets in library\n  if (totalSnippetCount === 0) {\n    return `## Snippet Library\n\nYou have access to a snippet library for storing reusable code. The library is currently empty.\n\n### Snippet Management Tools\n\n- \\`search_snippets(query, limit?)\\` - Search for snippets (currently empty)\n- \\`get_snippet(name)\\` - Get full snippet details including code\n- \\`register_snippet(...)\\` - Save working code as a reusable snippet\n\nWhen you write useful, reusable code, consider registering it as a snippet for future use.\n\n**Important**: Newly registered snippets become available as tools on the **next message**, not immediately in the current conversation turn.\n`\n  }\n\n  // No snippets selected for this conversation\n  if (selectedSnippets.length === 0) {\n    return `## Snippet Library\n\nYou have access to a persistent snippet library with ${totalSnippetCount} snippet${totalSnippetCount === 1 ? '' : 's'}. No snippets were pre-loaded for this conversation based on context.\n\n### Snippet Management Tools\n\n- \\`search_snippets(query, limit?)\\` - Search for relevant snippets\n- \\`get_snippet(name)\\` - Get full snippet details including code\n- \\`register_snippet(...)\\` - Save working code as a reusable snippet\n\nWhen you write useful, reusable code, consider registering it as a snippet for future use.\n\n**Important**: Newly registered snippets become available as tools on the **next message**, not immediately in the current conversation turn.\n`\n  }\n\n  if (snippetsAsTools) {\n    // Snippets are available as direct tools\n    const snippetToolDocs = selectedSnippets\n      .map((snippet) => {\n        const inputExample = generateExampleFromSchema(snippet.inputSchema)\n        const trustBadge =\n          snippet.trustLevel === 'trusted'\n            ? '✓ trusted'\n            : snippet.trustLevel === 'provisional'\n              ? '◐ provisional'\n              : '○ untrusted'\n\n        return `\n### ${snippet.name} [${trustBadge}]\n\n${snippet.description}\n\n${snippet.usageHints.map((h) => `- ${h}`).join('\\n')}\n\n**Input Schema:**\n\\`\\`\\`json\n${JSON.stringify(snippet.inputSchema, null, 2)}\n\\`\\`\\`\n\n**Output Schema:**\n\\`\\`\\`json\n${JSON.stringify(snippet.outputSchema, null, 2)}\n\\`\\`\\`\n\n**Example:**\nCall the \\`${snippet.name}\\` tool with: ${inputExample}\n`\n      })\n      .join('\\n---\\n')\n\n    return `## Snippet Library\n\n${selectedSnippets.length} snippet${selectedSnippets.length === 1 ? '' : 's'} pre-loaded for this conversation (${totalSnippetCount} total in library).\n\n### Available Snippet Tools\n\nThese snippets are available as **direct tools** you can call (marked with [SNIPPET] in description):\n\n${snippetToolDocs}\n\n### Snippet Management Tools\n\n- \\`search_snippets(query, limit?)\\` - Find additional snippets not pre-loaded\n- \\`get_snippet(name)\\` - Get full details of any snippet\n- \\`register_snippet(...)\\` - Save working code as a new snippet\n\n### Using Snippets\n\nSnippets are **regular tools** - call them directly like any other tool. No need to use \\`execute_typescript\\`.\n\n### Creating New Snippets\n\nWhen you write useful, reusable code with \\`execute_typescript\\`, register it:\n\n\\`\\`\\`typescript\n// After verifying code works, call the register_snippet tool\nregister_snippet({\n  name: 'compare_npm_packages',\n  description: 'Compare download counts for multiple NPM packages',\n  code: \\`\n    const { packages } = input;\n    const results = await Promise.all(\n      packages.map(pkg => external_getNpmDownloads({ package: pkg }))\n    );\n    return packages.map((pkg, i) => ({ package: pkg, downloads: results[i].downloads }))\n      .sort((a, b) => b.downloads - a.downloads);\n  \\`,\n  inputSchema: { \n    type: 'object', \n    properties: { packages: { type: 'array', items: { type: 'string' } } },\n    required: ['packages']\n  },\n  outputSchema: {\n    type: 'array',\n    items: { type: 'object', properties: { package: { type: 'string' }, downloads: { type: 'number' } } }\n  },\n  usageHints: ['Use when comparing popularity of NPM packages'],\n  dependsOn: [],\n});\n\\`\\`\\`\n\n**Important**: Newly registered snippets become available as tools on the **next message**, not immediately in the current conversation turn.\n`\n  }\n\n  // Snippets as sandbox bindings (legacy mode)\n  const snippetDocs = selectedSnippets\n    .map((snippet) => {\n      const inputExample = generateExampleFromSchema(snippet.inputSchema)\n      const trustBadge =\n        snippet.trustLevel === 'trusted'\n          ? '✓ trusted'\n          : snippet.trustLevel === 'provisional'\n            ? '◐ provisional'\n            : '○ untrusted'\n\n      return `\n### snippet_${snippet.name} [${trustBadge}]\n\n${snippet.description}\n\n${snippet.usageHints.map((h) => `- ${h}`).join('\\n')}\n\n**Input Schema:**\n\\`\\`\\`json\n${JSON.stringify(snippet.inputSchema, null, 2)}\n\\`\\`\\`\n\n**Output Schema:**\n\\`\\`\\`json\n${JSON.stringify(snippet.outputSchema, null, 2)}\n\\`\\`\\`\n\n**Example:**\n\\`\\`\\`typescript\nconst result = await snippet_${snippet.name}(${inputExample});\n\\`\\`\\`\n`\n    })\n    .join('\\n---\\n')\n\n  // Generate type stubs for selected snippets\n  const typeStubs = generateSnippetTypes(selectedSnippets)\n\n  return `## Snippet Library\n\n${selectedSnippets.length} snippet${selectedSnippets.length === 1 ? '' : 's'} pre-loaded for this conversation (${totalSnippetCount} total in library).\n\n### Pre-loaded Snippets\n\nThese are available as \\`snippet_*\\` functions in your TypeScript code:\n\n${snippetDocs}\n\n### Type Definitions\n\n\\`\\`\\`typescript\n${typeStubs}\n\\`\\`\\`\n\n### Snippet Management Tools\n\n- \\`search_snippets(query, limit?)\\` - Find additional snippets not pre-loaded\n- \\`get_snippet(name)\\` - Get full details of any snippet\n- \\`register_snippet(...)\\` - Save working code as a new snippet\n\n### Using Snippets\n\nSnippets work just like \\`external_*\\` functions inside \\`execute_typescript\\`:\n\n\\`\\`\\`typescript\n// Call a pre-loaded snippet\nconst stats = await snippet_fetch_github_stats({ owner: 'tanstack', repo: 'query' });\n\n// Compose snippets with external tools\nconst repos = await external_searchRepositories({ query: 'react state' });\nconst detailed = await Promise.all(\n  repos.items.slice(0, 5).map(r => \n    snippet_fetch_github_stats({ owner: r.owner.login, repo: r.name })\n  )\n);\n\\`\\`\\`\n\n### Creating New Snippets\n\nWhen you write useful, reusable code, register it:\n\n\\`\\`\\`typescript\n// After verifying code works, call the register_snippet tool\nregister_snippet({\n  name: 'compare_npm_packages',\n  description: 'Compare download counts for multiple NPM packages',\n  code: \\`\n    const { packages } = input;\n    const results = await Promise.all(\n      packages.map(pkg => external_getNpmDownloads({ package: pkg }))\n    );\n    return packages.map((pkg, i) => ({ package: pkg, downloads: results[i].downloads }))\n      .sort((a, b) => b.downloads - a.downloads);\n  \\`,\n  inputSchema: { \n    type: 'object', \n    properties: { packages: { type: 'array', items: { type: 'string' } } },\n    required: ['packages']\n  },\n  outputSchema: {\n    type: 'array',\n    items: { type: 'object', properties: { package: { type: 'string' }, downloads: { type: 'number' } } }\n  },\n  usageHints: ['Use when comparing popularity of NPM packages'],\n  dependsOn: [],\n});\n\\`\\`\\`\n\n**Important**: Newly registered snippets become available as tools on the **next message**, not immediately in the current conversation turn.\n`\n}\n"],"mappings":";;;;;AAwBA,SAAS,0BAA0B,QAAyC;CAC1E,IAAI,OAAO,SAAS,YAAY,OAAO,YAAY;EACjD,MAAM,QAAQ,OAAO;EACrB,MAAM,UAAmC,CAAC;EAE1C,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,GAC7C,IAAI,MAAM,SAAS,UAAU,QAAQ,OAAO,YAAY,IAAI;OACvD,IAAI,MAAM,SAAS,UAAU,QAAQ,OAAO;OAC5C,IAAI,MAAM,SAAS,WAAW,QAAQ,OAAO;OAC7C,IAAI,MAAM,SAAS,SAAS,QAAQ,OAAO,CAAC;OAC5C,QAAQ,OAAO;EAGtB,OAAO,KAAK,UAAU,OAAO,CAAC,CAAC,QAAQ,MAAM,EAAE;CACjD;CACA,OAAO;AACT;;;;;AAMA,SAAgB,2BAA2B,EACzC,kBACA,mBACA,kBAAkB,QAC0B;CAE5C,IAAI,sBAAsB,GACxB,OAAO;;;;;;;;;;;;;;CAiBT,IAAI,iBAAiB,WAAW,GAC9B,OAAO;;uDAE4C,kBAAkB,UAAU,sBAAsB,IAAI,KAAK,IAAI;;;;;;;;;;;;CAcpH,IAAI,iBAAiB;EAEnB,MAAM,kBAAkB,iBACrB,KAAK,YAAY;GAChB,MAAM,eAAe,0BAA0B,QAAQ,WAAW;GAClE,MAAM,aACJ,QAAQ,eAAe,YACnB,cACA,QAAQ,eAAe,gBACrB,kBACA;GAER,OAAO;MACT,QAAQ,KAAK,IAAI,WAAW;;EAEhC,QAAQ,YAAY;;EAEpB,QAAQ,WAAW,KAAK,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE;;;;EAInD,KAAK,UAAU,QAAQ,aAAa,MAAM,CAAC,EAAE;;;;;EAK7C,KAAK,UAAU,QAAQ,cAAc,MAAM,CAAC,EAAE;;;;aAInC,QAAQ,KAAK,gBAAgB,aAAa;;EAEjD,CAAC,CAAC,CACD,KAAK,SAAS;EAEjB,OAAO;;EAET,iBAAiB,OAAO,UAAU,iBAAiB,WAAW,IAAI,KAAK,IAAI,qCAAqC,kBAAkB;;;;;;EAMlI,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6ChB;CAGA,MAAM,cAAc,iBACjB,KAAK,YAAY;EAChB,MAAM,eAAe,0BAA0B,QAAQ,WAAW;EAClE,MAAM,aACJ,QAAQ,eAAe,YACnB,cACA,QAAQ,eAAe,gBACrB,kBACA;EAER,OAAO;cACC,QAAQ,KAAK,IAAI,WAAW;;EAExC,QAAQ,YAAY;;EAEpB,QAAQ,WAAW,KAAK,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE;;;;EAInD,KAAK,UAAU,QAAQ,aAAa,MAAM,CAAC,EAAE;;;;;EAK7C,KAAK,UAAU,QAAQ,cAAc,MAAM,CAAC,EAAE;;;;;+BAKjB,QAAQ,KAAK,GAAG,aAAa;;;CAGxD,CAAC,CAAC,CACD,KAAK,SAAS;CAGjB,MAAM,YAAY,qBAAqB,gBAAgB;CAEvD,OAAO;;EAEP,iBAAiB,OAAO,UAAU,iBAAiB,WAAW,IAAI,KAAK,IAAI,qCAAqC,kBAAkB;;;;;;EAMlI,YAAY;;;;;EAKZ,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DZ"}

package/dist/esm/generate-snippet-types.d.ts

@@ -0,0 +1,7 @@
+import { Snippet } from './types.js';
+/**
+ * Generate TypeScript type stubs for snippets.
+ * These are included in the system prompt so the LLM knows
+ * the exact type signatures of available snippets.
+ */
+export declare function generateSnippetTypes(snippets: Array<Snippet>): string;

package/dist/esm/generate-snippet-types.js

@@ -0,0 +1,79 @@
+//#region src/generate-snippet-types.ts
+/**
+* Convert a JSON Schema to a TypeScript type string
+*/
+function schemaToType(schema) {
+	if (typeof schema !== "object") return "unknown";
+	const schemaType = schema.type;
+	if (schemaType === "string") return "string";
+	if (schemaType === "number" || schemaType === "integer") return "number";
+	if (schemaType === "boolean") return "boolean";
+	if (schemaType === "null") return "null";
+	if (schemaType === "array") {
+		const items = schema.items;
+		return `Array<${items ? schemaToType(items) : "unknown"}>`;
+	}
+	if (schemaType === "object" && schema.properties) {
+		const properties = schema.properties;
+		const required = new Set(schema.required ?? []);
+		return `{\n${Object.entries(properties).map(([key, propSchema]) => {
+			const optional = required.has(key) ? "" : "?";
+			const propType = schemaToType(propSchema);
+			return `  ${/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : `"${key}"`}${optional}: ${propType};`;
+		}).join("\n")}\n}`;
+	}
+	if (schema.enum) return schema.enum.map((v) => JSON.stringify(v)).join(" | ");
+	if (schema.anyOf || schema.oneOf) return (schema.anyOf || schema.oneOf).map((v) => schemaToType(v)).join(" | ");
+	if (Array.isArray(schemaType)) return schemaType.map((t) => {
+		if (t === "string") return "string";
+		if (t === "number" || t === "integer") return "number";
+		if (t === "boolean") return "boolean";
+		if (t === "null") return "null";
+		if (t === "array") return "Array<unknown>";
+		if (t === "object") return "object";
+		return "unknown";
+	}).join(" | ");
+	return "unknown";
+}
+/**
+* Capitalize the first letter of a string
+*/
+function capitalize(str) {
+	return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/**
+* Convert snake_case to PascalCase
+*/
+function toPascalCase(str) {
+	return str.split("_").map((part) => capitalize(part)).join("");
+}
+/**
+* Generate TypeScript type stubs for snippets.
+* These are included in the system prompt so the LLM knows
+* the exact type signatures of available snippets.
+*/
+function generateSnippetTypes(snippets) {
+	const declarations = [];
+	for (const snippet of snippets) {
+		const baseName = toPascalCase(snippet.name);
+		const inputTypeName = `Snippet${baseName}Input`;
+		const outputTypeName = `Snippet${baseName}Output`;
+		const inputType = schemaToType(snippet.inputSchema);
+		if (snippet.inputSchema.type === "object" && snippet.inputSchema.properties && Object.keys(snippet.inputSchema.properties).length > 0) declarations.push(`interface ${inputTypeName} ${inputType}`);
+		const outputType = schemaToType(snippet.outputSchema);
+		if (snippet.outputSchema.type === "object" && snippet.outputSchema.properties && Object.keys(snippet.outputSchema.properties).length > 0) declarations.push(`interface ${outputTypeName} ${outputType}`);
+		const inputRef = snippet.inputSchema.type === "object" && snippet.inputSchema.properties && Object.keys(snippet.inputSchema.properties).length > 0 ? inputTypeName : inputType;
+		const outputRef = snippet.outputSchema.type === "object" && snippet.outputSchema.properties && Object.keys(snippet.outputSchema.properties).length > 0 ? outputTypeName : outputType;
+		const hintsDoc = snippet.usageHints.map((h) => ` * @hint ${h}`).join("\n");
+		declarations.push(`/**
+ * ${snippet.description}
+${hintsDoc}
+ */
+declare function snippet_${snippet.name}(input: ${inputRef}): Promise<${outputRef}>;`);
+	}
+	return declarations.join("\n\n");
+}
+//#endregion
+export { generateSnippetTypes };
+
+//# sourceMappingURL=generate-snippet-types.js.map

package/dist/esm/generate-snippet-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-snippet-types.js","names":[],"sources":["../../src/generate-snippet-types.ts"],"sourcesContent":["import type { Snippet } from './types'\n\n/**\n * Convert a JSON Schema to a TypeScript type string\n */\nfunction schemaToType(schema: Record<string, unknown>): string {\n  if (typeof schema !== 'object') {\n    return 'unknown'\n  }\n\n  const schemaType = schema.type\n\n  // Handle basic types\n  if (schemaType === 'string') return 'string'\n  if (schemaType === 'number' || schemaType === 'integer') return 'number'\n  if (schemaType === 'boolean') return 'boolean'\n  if (schemaType === 'null') return 'null'\n\n  // Handle arrays\n  if (schemaType === 'array') {\n    const items = schema.items as Record<string, unknown> | undefined\n    const itemType = items ? schemaToType(items) : 'unknown'\n    return `Array<${itemType}>`\n  }\n\n  // Handle objects with properties\n  if (schemaType === 'object' && schema.properties) {\n    const properties = schema.properties as Record<\n      string,\n      Record<string, unknown>\n    >\n    const required = new Set(\n      (schema.required as Array<string> | undefined) ?? [],\n    )\n\n    const props = Object.entries(properties)\n      .map(([key, propSchema]) => {\n        const optional = required.has(key) ? '' : '?'\n        const propType = schemaToType(propSchema)\n        // Handle property names that need quoting\n        const safeName = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)\n          ? key\n          : `\"${key}\"`\n        return `  ${safeName}${optional}: ${propType};`\n      })\n      .join('\\n')\n\n    return `{\\n${props}\\n}`\n  }\n\n  // Handle enums\n  if (schema.enum) {\n    const enumValues = schema.enum as Array<unknown>\n    return enumValues.map((v) => JSON.stringify(v)).join(' | ')\n  }\n\n  // Handle union types (anyOf, oneOf)\n  if (schema.anyOf || schema.oneOf) {\n    const variants = (schema.anyOf || schema.oneOf) as Array<\n      Record<string, unknown>\n    >\n    return variants.map((v) => schemaToType(v)).join(' | ')\n  }\n\n  // Handle type arrays (e.g., [\"string\", \"null\"])\n  if (Array.isArray(schemaType)) {\n    return schemaType\n      .map((t) => {\n        if (t === 'string') return 'string'\n        if (t === 'number' || t === 'integer') return 'number'\n        if (t === 'boolean') return 'boolean'\n        if (t === 'null') return 'null'\n        if (t === 'array') return 'Array<unknown>'\n        if (t === 'object') return 'object'\n        return 'unknown'\n      })\n      .join(' | ')\n  }\n\n  // Fallback for unknown schemas\n  return 'unknown'\n}\n\n/**\n * Capitalize the first letter of a string\n */\nfunction capitalize(str: string): string {\n  return str.charAt(0).toUpperCase() + str.slice(1)\n}\n\n/**\n * Convert snake_case to PascalCase\n */\nfunction toPascalCase(str: string): string {\n  return str\n    .split('_')\n    .map((part) => capitalize(part))\n    .join('')\n}\n\n/**\n * Generate TypeScript type stubs for snippets.\n * These are included in the system prompt so the LLM knows\n * the exact type signatures of available snippets.\n */\nexport function generateSnippetTypes(snippets: Array<Snippet>): string {\n  const declarations: Array<string> = []\n\n  for (const snippet of snippets) {\n    const baseName = toPascalCase(snippet.name)\n    const inputTypeName = `Snippet${baseName}Input`\n    const outputTypeName = `Snippet${baseName}Output`\n\n    // Generate input type\n    const inputType = schemaToType(snippet.inputSchema)\n    if (\n      snippet.inputSchema.type === 'object' &&\n      snippet.inputSchema.properties &&\n      Object.keys(snippet.inputSchema.properties).length > 0\n    ) {\n      declarations.push(`interface ${inputTypeName} ${inputType}`)\n    }\n\n    // Generate output type\n    const outputType = schemaToType(snippet.outputSchema)\n    if (\n      snippet.outputSchema.type === 'object' &&\n      snippet.outputSchema.properties &&\n      Object.keys(snippet.outputSchema.properties).length > 0\n    ) {\n      declarations.push(`interface ${outputTypeName} ${outputType}`)\n    }\n\n    // Determine type references\n    const inputRef =\n      snippet.inputSchema.type === 'object' &&\n      snippet.inputSchema.properties &&\n      Object.keys(snippet.inputSchema.properties).length > 0\n        ? inputTypeName\n        : inputType\n\n    const outputRef =\n      snippet.outputSchema.type === 'object' &&\n      snippet.outputSchema.properties &&\n      Object.keys(snippet.outputSchema.properties).length > 0\n        ? outputTypeName\n        : outputType\n\n    // Generate function declaration with JSDoc\n    const hintsDoc = snippet.usageHints.map((h) => ` * @hint ${h}`).join('\\n')\n\n    declarations.push(\n      `/**\n * ${snippet.description}\n${hintsDoc}\n */\ndeclare function snippet_${snippet.name}(input: ${inputRef}): Promise<${outputRef}>;`,\n    )\n  }\n\n  return declarations.join('\\n\\n')\n}\n"],"mappings":";;;;AAKA,SAAS,aAAa,QAAyC;CAC7D,IAAI,OAAO,WAAW,UACpB,OAAO;CAGT,MAAM,aAAa,OAAO;CAG1B,IAAI,eAAe,UAAU,OAAO;CACpC,IAAI,eAAe,YAAY,eAAe,WAAW,OAAO;CAChE,IAAI,eAAe,WAAW,OAAO;CACrC,IAAI,eAAe,QAAQ,OAAO;CAGlC,IAAI,eAAe,SAAS;EAC1B,MAAM,QAAQ,OAAO;EAErB,OAAO,SADU,QAAQ,aAAa,KAAK,IAAI,UACtB;CAC3B;CAGA,IAAI,eAAe,YAAY,OAAO,YAAY;EAChD,MAAM,aAAa,OAAO;EAI1B,MAAM,WAAW,IAAI,IAClB,OAAO,YAA0C,CAAC,CACrD;EAcA,OAAO,MAZO,OAAO,QAAQ,UAAU,CAAC,CACrC,KAAK,CAAC,KAAK,gBAAgB;GAC1B,MAAM,WAAW,SAAS,IAAI,GAAG,IAAI,KAAK;GAC1C,MAAM,WAAW,aAAa,UAAU;GAKxC,OAAO,KAHU,6BAA6B,KAAK,GAAG,IAClD,MACA,IAAI,IAAI,KACW,SAAS,IAAI,SAAS;EAC/C,CAAC,CAAC,CACD,KAAK,IAEK,EAAM;CACrB;CAGA,IAAI,OAAO,MAET,OADmB,OAAO,KACR,KAAK,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK;CAI5D,IAAI,OAAO,SAAS,OAAO,OAIzB,QAHkB,OAAO,SAAS,OAAO,MAAA,CAGzB,KAAK,MAAM,aAAa,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK;CAIxD,IAAI,MAAM,QAAQ,UAAU,GAC1B,OAAO,WACJ,KAAK,MAAM;EACV,IAAI,MAAM,UAAU,OAAO;EAC3B,IAAI,MAAM,YAAY,MAAM,WAAW,OAAO;EAC9C,IAAI,MAAM,WAAW,OAAO;EAC5B,IAAI,MAAM,QAAQ,OAAO;EACzB,IAAI,MAAM,SAAS,OAAO;EAC1B,IAAI,MAAM,UAAU,OAAO;EAC3B,OAAO;CACT,CAAC,CAAC,CACD,KAAK,KAAK;CAIf,OAAO;AACT;;;;AAKA,SAAS,WAAW,KAAqB;CACvC,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,YAAY,IAAI,IAAI,MAAM,CAAC;AAClD;;;;AAKA,SAAS,aAAa,KAAqB;CACzC,OAAO,IACJ,MAAM,GAAG,CAAC,CACV,KAAK,SAAS,WAAW,IAAI,CAAC,CAAC,CAC/B,KAAK,EAAE;AACZ;;;;;;AAOA,SAAgB,qBAAqB,UAAkC;CACrE,MAAM,eAA8B,CAAC;CAErC,KAAK,MAAM,WAAW,UAAU;EAC9B,MAAM,WAAW,aAAa,QAAQ,IAAI;EAC1C,MAAM,gBAAgB,UAAU,SAAS;EACzC,MAAM,iBAAiB,UAAU,SAAS;EAG1C,MAAM,YAAY,aAAa,QAAQ,WAAW;EAClD,IACE,QAAQ,YAAY,SAAS,YAC7B,QAAQ,YAAY,cACpB,OAAO,KAAK,QAAQ,YAAY,UAAU,CAAC,CAAC,SAAS,GAErD,aAAa,KAAK,aAAa,cAAc,GAAG,WAAW;EAI7D,MAAM,aAAa,aAAa,QAAQ,YAAY;EACpD,IACE,QAAQ,aAAa,SAAS,YAC9B,QAAQ,aAAa,cACrB,OAAO,KAAK,QAAQ,aAAa,UAAU,CAAC,CAAC,SAAS,GAEtD,aAAa,KAAK,aAAa,eAAe,GAAG,YAAY;EAI/D,MAAM,WACJ,QAAQ,YAAY,SAAS,YAC7B,QAAQ,YAAY,cACpB,OAAO,KAAK,QAAQ,YAAY,UAAU,CAAC,CAAC,SAAS,IACjD,gBACA;EAEN,MAAM,YACJ,QAAQ,aAAa,SAAS,YAC9B,QAAQ,aAAa,cACrB,OAAO,KAAK,QAAQ,aAAa,UAAU,CAAC,CAAC,SAAS,IAClD,iBACA;EAGN,MAAM,WAAW,QAAQ,WAAW,KAAK,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,IAAI;EAEzE,aAAa,KACX;KACD,QAAQ,YAAY;EACvB,SAAS;;2BAEgB,QAAQ,KAAK,UAAU,SAAS,aAAa,UAAU,GAC9E;CACF;CAEA,OAAO,aAAa,KAAK,MAAM;AACjC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,14 @@
+export { codeModeWithSnippets, createCodeModeWithSnippetsConfig, } from './code-mode-with-snippets.js';
+export type { CodeModeWithSnippetsOptions, CodeModeWithSnippetsResult, } from './code-mode-with-snippets.js';
+export { createDefaultTrustStrategy, createAlwaysTrustedStrategy, createRelaxedTrustStrategy, createCustomTrustStrategy, } from './trust-strategies.js';
+export type { TrustStrategy } from './trust-strategies.js';
+export { selectRelevantSnippets } from './select-relevant-snippets.js';
+export { snippetsToTools, snippetToTool } from './snippets-to-tools.js';
+export type { SnippetToToolOptions } from './snippets-to-tools.js';
+export { snippetsToBindings, snippetsToSimpleBindings, } from './snippets-to-bindings.js';
+export { createSnippetManagementTools } from './create-snippet-management-tools.js';
+export { createSnippetsSystemPrompt } from './create-snippets-system-prompt.js';
+export { generateSnippetTypes } from './generate-snippet-types.js';
+export { createMemorySnippetStorage } from './storage/memory-storage.js';
+export type { MemorySnippetStorageOptions } from './storage/memory-storage.js';
+export type { Snippet, SnippetIndexEntry, SnippetStorage, SnippetsConfig, SnippetStats, TrustLevel, SnippetBinding, } from './types.js';

package/dist/esm/index.js

@@ -0,0 +1,10 @@
+import { selectRelevantSnippets } from "./select-relevant-snippets.js";
+import { createAlwaysTrustedStrategy, createCustomTrustStrategy, createDefaultTrustStrategy, createRelaxedTrustStrategy } from "./trust-strategies.js";
+import { snippetToTool, snippetsToTools } from "./snippets-to-tools.js";
+import { createSnippetManagementTools } from "./create-snippet-management-tools.js";
+import { generateSnippetTypes } from "./generate-snippet-types.js";
+import { createSnippetsSystemPrompt } from "./create-snippets-system-prompt.js";
+import { codeModeWithSnippets, createCodeModeWithSnippetsConfig } from "./code-mode-with-snippets.js";
+import { snippetsToBindings, snippetsToSimpleBindings } from "./snippets-to-bindings.js";
+import { createMemorySnippetStorage } from "./storage/memory-storage.js";
+export { codeModeWithSnippets, createAlwaysTrustedStrategy, createCodeModeWithSnippetsConfig, createCustomTrustStrategy, createDefaultTrustStrategy, createMemorySnippetStorage, createRelaxedTrustStrategy, createSnippetManagementTools, createSnippetsSystemPrompt, generateSnippetTypes, selectRelevantSnippets, snippetToTool, snippetsToBindings, snippetsToSimpleBindings, snippetsToTools };

package/dist/esm/select-relevant-snippets.d.ts

@@ -0,0 +1,29 @@
+import { AnyTextAdapter, ModelMessage } from '@tanstack/ai';
+import { Snippet, SnippetIndexEntry, SnippetStorage } from './types.js';
+interface SelectRelevantSnippetsOptions {
+    /**
+     * Text adapter for snippet selection (should be a cheap/fast model)
+     */
+    adapter: AnyTextAdapter;
+    /**
+     * Current conversation messages
+     */
+    messages: Array<ModelMessage>;
+    /**
+     * Snippet index (lightweight metadata)
+     */
+    snippetIndex: Array<SnippetIndexEntry>;
+    /**
+     * Maximum number of snippets to select
+     */
+    maxSnippets: number;
+    /**
+     * Storage to load full snippet data
+     */
+    storage: SnippetStorage;
+}
+/**
+ * Use a cheap/fast LLM to select which snippets are relevant for the current conversation
+ */
+export declare function selectRelevantSnippets({ adapter, messages, snippetIndex, maxSnippets, storage, }: SelectRelevantSnippetsOptions): Promise<Array<Snippet>>;
+export {};

package/dist/esm/select-relevant-snippets.js

@@ -0,0 +1,56 @@
+import { chat } from "@tanstack/ai";
+//#region src/select-relevant-snippets.ts
+/**
+* Use a cheap/fast LLM to select which snippets are relevant for the current conversation
+*/
+async function selectRelevantSnippets({ adapter, messages, snippetIndex, maxSnippets, storage }) {
+	if (snippetIndex.length === 0) return [];
+	if (messages.length === 0) return [];
+	const selectionPrompt = `Given this conversation context:
+---
+${messages.slice(-5).map((m) => {
+		let content;
+		if (typeof m.content === "string") content = m.content;
+		else if (Array.isArray(m.content)) content = m.content.map((part) => {
+			if (typeof part === "string") return part;
+			if (part && typeof part === "object" && "text" in part) return part.text;
+			return "[non-text content]";
+		}).join(" ");
+		else content = "[complex content]";
+		return `${m.role}: ${content}`;
+	}).join("\n")}
+---
+
+Which of these snippets (if any) would be useful for the next response? Return a JSON array of snippet names, max ${maxSnippets}. Return [] if none are relevant.
+
+Available snippets:
+${snippetIndex.map((s) => {
+		const hints = s.usageHints.length > 0 ? ` (${s.usageHints[0]})` : "";
+		return `- ${s.name}: ${s.description}${hints}`;
+	}).join("\n")}
+
+Respond with only the JSON array, no explanation. Example: ["snippet_name_1", "snippet_name_2"]`;
+	try {
+		const stream = chat({
+			adapter,
+			messages: [{
+				role: "user",
+				content: selectionPrompt
+			}]
+		});
+		let responseText = "";
+		for await (const chunk of stream) if (chunk.type === "TEXT_MESSAGE_CONTENT") responseText += chunk.delta;
+		let jsonText = responseText.trim();
+		if (jsonText.startsWith("```")) jsonText = jsonText.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "");
+		const selectedNames = JSON.parse(jsonText);
+		if (!Array.isArray(selectedNames)) return [];
+		return (await Promise.all(selectedNames.slice(0, maxSnippets).map((name) => storage.get(name)))).filter((s) => s !== null);
+	} catch (error) {
+		console.warn("Snippet selection failed, returning empty selection:", error);
+		return [];
+	}
+}
+//#endregion
+export { selectRelevantSnippets };
+
+//# sourceMappingURL=select-relevant-snippets.js.map

package/dist/esm/select-relevant-snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-relevant-snippets.js","names":[],"sources":["../../src/select-relevant-snippets.ts"],"sourcesContent":["import { chat } from '@tanstack/ai'\nimport type { AnyTextAdapter, ModelMessage, StreamChunk } from '@tanstack/ai'\nimport type { Snippet, SnippetIndexEntry, SnippetStorage } from './types'\n\ninterface SelectRelevantSnippetsOptions {\n  /**\n   * Text adapter for snippet selection (should be a cheap/fast model)\n   */\n  adapter: AnyTextAdapter\n\n  /**\n   * Current conversation messages\n   */\n  messages: Array<ModelMessage>\n\n  /**\n   * Snippet index (lightweight metadata)\n   */\n  snippetIndex: Array<SnippetIndexEntry>\n\n  /**\n   * Maximum number of snippets to select\n   */\n  maxSnippets: number\n\n  /**\n   * Storage to load full snippet data\n   */\n  storage: SnippetStorage\n}\n\n/**\n * Use a cheap/fast LLM to select which snippets are relevant for the current conversation\n */\nexport async function selectRelevantSnippets({\n  adapter,\n  messages,\n  snippetIndex,\n  maxSnippets,\n  storage,\n}: SelectRelevantSnippetsOptions): Promise<Array<Snippet>> {\n  // Early exit conditions\n  if (snippetIndex.length === 0) return []\n  if (messages.length === 0) return []\n\n  // Build context from recent messages (last 5)\n  const recentMessages = messages.slice(-5)\n  const recentContext = recentMessages\n    .map((m) => {\n      let content: string\n      if (typeof m.content === 'string') {\n        content = m.content\n      } else if (Array.isArray(m.content)) {\n        // Handle content parts (text, images, etc.)\n        content = m.content\n          .map((part: unknown) => {\n            if (typeof part === 'string') return part\n            if (part && typeof part === 'object' && 'text' in part)\n              return (part as { text: string }).text\n            return '[non-text content]'\n          })\n          .join(' ')\n      } else {\n        content = '[complex content]'\n      }\n      return `${m.role}: ${content}`\n    })\n    .join('\\n')\n\n  // Build snippet catalog for selection prompt\n  const snippetCatalog = snippetIndex\n    .map((s) => {\n      const hints = s.usageHints.length > 0 ? ` (${s.usageHints[0]})` : ''\n      return `- ${s.name}: ${s.description}${hints}`\n    })\n    .join('\\n')\n\n  // Ask cheap model to select relevant snippets\n  const selectionPrompt = `Given this conversation context:\n---\n${recentContext}\n---\n\nWhich of these snippets (if any) would be useful for the next response? Return a JSON array of snippet names, max ${maxSnippets}. Return [] if none are relevant.\n\nAvailable snippets:\n${snippetCatalog}\n\nRespond with only the JSON array, no explanation. Example: [\"snippet_name_1\", \"snippet_name_2\"]`\n\n  try {\n    // Use chat to get the selection\n    const stream = chat({\n      adapter,\n      messages: [\n        {\n          role: 'user',\n          content: selectionPrompt,\n        },\n      ],\n    })\n\n    // Collect the full response\n    let responseText = ''\n    for await (const chunk of stream as AsyncIterable<StreamChunk>) {\n      if (chunk.type === 'TEXT_MESSAGE_CONTENT') {\n        responseText += chunk.delta\n      }\n    }\n\n    // Parse the JSON response\n    // Handle potential markdown code blocks\n    let jsonText = responseText.trim()\n    if (jsonText.startsWith('```')) {\n      // Remove markdown code block\n      jsonText = jsonText.replace(/^```(?:json)?\\n?/, '').replace(/\\n?```$/, '')\n    }\n\n    const selectedNames: Array<string> = JSON.parse(jsonText)\n\n    if (!Array.isArray(selectedNames)) {\n      return []\n    }\n\n    // Load full snippet data for selected snippets\n    const selectedSnippets = await Promise.all(\n      selectedNames.slice(0, maxSnippets).map((name) => storage.get(name)),\n    )\n\n    return selectedSnippets.filter((s): s is Snippet => s !== null)\n  } catch (error) {\n    // If parsing fails or any error occurs, return empty (safe fallback)\n    console.warn('Snippet selection failed, returning empty selection:', error)\n    return []\n  }\n}\n"],"mappings":";;;;;AAkCA,eAAsB,uBAAuB,EAC3C,SACA,UACA,cACA,aACA,WACyD;CAEzD,IAAI,aAAa,WAAW,GAAG,OAAO,CAAC;CACvC,IAAI,SAAS,WAAW,GAAG,OAAO,CAAC;CAmCnC,MAAM,kBAAkB;;EAhCD,SAAS,MAAM,EAChB,CAAA,CACnB,KAAK,MAAM;EACV,IAAI;EACJ,IAAI,OAAO,EAAE,YAAY,UACvB,UAAU,EAAE;OACP,IAAI,MAAM,QAAQ,EAAE,OAAO,GAEhC,UAAU,EAAE,QACT,KAAK,SAAkB;GACtB,IAAI,OAAO,SAAS,UAAU,OAAO;GACrC,IAAI,QAAQ,OAAO,SAAS,YAAY,UAAU,MAChD,OAAQ,KAA0B;GACpC,OAAO;EACT,CAAC,CAAC,CACD,KAAK,GAAG;OAEX,UAAU;EAEZ,OAAO,GAAG,EAAE,KAAK,IAAI;CACvB,CAAC,CAAC,CACD,KAAK,IAaR,EAAc;;;oHAGoG,YAAY;;;EAbvG,aACpB,KAAK,MAAM;EACV,MAAM,QAAQ,EAAE,WAAW,SAAS,IAAI,KAAK,EAAE,WAAW,GAAG,KAAK;EAClE,OAAO,KAAK,EAAE,KAAK,IAAI,EAAE,cAAc;CACzC,CAAC,CAAC,CACD,KAAK,IAWR,EAAe;;;CAIf,IAAI;EAEF,MAAM,SAAS,KAAK;GAClB;GACA,UAAU,CACR;IACE,MAAM;IACN,SAAS;GACX,CACF;EACF,CAAC;EAGD,IAAI,eAAe;EACnB,WAAW,MAAM,SAAS,QACxB,IAAI,MAAM,SAAS,wBACjB,gBAAgB,MAAM;EAM1B,IAAI,WAAW,aAAa,KAAK;EACjC,IAAI,SAAS,WAAW,KAAK,GAE3B,WAAW,SAAS,QAAQ,oBAAoB,EAAE,CAAC,CAAC,QAAQ,WAAW,EAAE;EAG3E,MAAM,gBAA+B,KAAK,MAAM,QAAQ;EAExD,IAAI,CAAC,MAAM,QAAQ,aAAa,GAC9B,OAAO,CAAC;EAQV,QAAO,MAJwB,QAAQ,IACrC,cAAc,MAAM,GAAG,WAAW,CAAC,CAAC,KAAK,SAAS,QAAQ,IAAI,IAAI,CAAC,CACrE,EAAA,CAEwB,QAAQ,MAAoB,MAAM,IAAI;CAChE,SAAS,OAAO;EAEd,QAAQ,KAAK,wDAAwD,KAAK;EAC1E,OAAO,CAAC;CACV;AACF"}

package/dist/esm/snippets-to-bindings.d.ts

@@ -0,0 +1,34 @@
+import { ToolExecutionContext } from '@tanstack/ai';
+import { ToolBinding } from '@tanstack/ai-code-mode';
+import { Snippet, SnippetStorage } from './types.js';
+interface SnippetsToBindingsOptions {
+    /**
+     * Snippets to convert to bindings
+     */
+    snippets: Array<Snippet>;
+    /**
+     * Tool execution context for emitting custom events
+     */
+    context?: ToolExecutionContext;
+    /**
+     * Function to execute snippet code in the sandbox
+     * The snippet code receives `input` as a variable
+     */
+    executeInSandbox: (code: string, input: unknown) => Promise<unknown>;
+    /**
+     * Storage for updating execution stats
+     */
+    storage: SnippetStorage;
+}
+/**
+ * Convert snippets to sandbox bindings with the snippet_ prefix.
+ * Snippets become callable functions inside the sandbox.
+ */
+export declare function snippetsToBindings({ snippets, context, executeInSandbox, storage, }: SnippetsToBindingsOptions): Record<string, ToolBinding>;
+/**
+ * Create a simple binding record for snippets without full sandbox execution.
+ * This is used when snippets are being documented in the system prompt
+ * but not yet being executed.
+ */
+export declare function snippetsToSimpleBindings(snippets: Array<Snippet>): Record<string, ToolBinding>;
+export {};