@tanstack/ai-code-mode 0.1.0

package/src/strip-typescript.ts

@@ -0,0 +1,94 @@
+import { transform } from 'esbuild'
+
+// Unique markers for wrapping/unwrapping code
+const WRAPPER_START = '___TANSTACK_WRAPPER_START___'
+const WRAPPER_END = '___TANSTACK_WRAPPER_END___'
+
+/**
+ * Strip TypeScript syntax from code, converting it to plain JavaScript.
+ *
+ * This is a safety net to ensure that even if an LLM generates TypeScript
+ * code with type annotations, it will be converted to valid JavaScript
+ * before being sent to the sandbox for execution.
+ *
+ * Uses esbuild's transform API which is extremely fast and handles all
+ * TypeScript syntax including:
+ * - Type annotations (: string, : number, etc.)
+ * - Generic types (Array<T>, Record<K, V>, etc.)
+ * - Interface and type declarations
+ * - Type assertions
+ * - Enums (converted to JavaScript objects)
+ *
+ * The code is wrapped in an async function before transformation to allow
+ * top-level `return` and `await` statements, then unwrapped after.
+ *
+ * @param code - TypeScript or JavaScript code
+ * @returns Plain JavaScript code with all type syntax removed
+ * @throws Error if esbuild fails (e.g., syntax error) or wrapper extraction fails
+ */
+export async function stripTypeScript(code: string): Promise<string> {
+  // Wrap the code in an async function to allow top-level return/await
+  // This is necessary because esbuild's ESM format doesn't allow top-level returns
+  const wrappedCode = `async function ${WRAPPER_START}() {\n${code}\n}; ${WRAPPER_END}`
+
+  const result = await transform(wrappedCode, {
+    loader: 'ts',
+    // Don't minify - keep the code readable for debugging
+    minify: false,
+    // Don't use keepNames as it adds __name() helper calls that aren't available in the sandbox
+    keepNames: false,
+    // Target modern JavaScript (ES2022 has top-level await)
+    target: 'es2022',
+  })
+
+  // Extract the code from inside the wrapper function
+  const transformed = result.code
+
+  // Find the function declaration start
+  const functionStart = transformed.indexOf(`async function ${WRAPPER_START}()`)
+  if (functionStart === -1) {
+    throw new Error(
+      '[stripTypeScript] Could not find wrapper function start in transformed output',
+    )
+  }
+
+  // Find the opening brace of the function
+  const openBrace = transformed.indexOf('{', functionStart)
+  if (openBrace === -1) {
+    throw new Error(
+      '[stripTypeScript] Could not find opening brace in transformed output',
+    )
+  }
+
+  // Find the end marker (regardless of formatting)
+  const endMarkerIndex = transformed.indexOf(WRAPPER_END)
+  if (endMarkerIndex === -1) {
+    throw new Error(
+      '[stripTypeScript] Could not find end marker in transformed output',
+    )
+  }
+
+  // Find the closing brace of the function (last } before the end marker)
+  // We need to find the } that matches the function opening
+  const codeBeforeEndMarker = transformed.substring(
+    openBrace + 1,
+    endMarkerIndex,
+  )
+
+  // Find the last } before the end marker, accounting for the semicolon
+  // The code will be: ...function body...}; WRAPPER_END or ...};\nWRAPPER_END
+  const closingBraceIndex = codeBeforeEndMarker.lastIndexOf('}')
+
+  if (closingBraceIndex === -1) {
+    throw new Error(
+      '[stripTypeScript] Could not find closing brace in transformed output',
+    )
+  }
+
+  // Extract the function body (between { and })
+  const functionBody = codeBeforeEndMarker
+    .substring(0, closingBraceIndex)
+    .trim()
+
+  return functionBody
+}

package/src/type-generator/json-schema-to-ts.ts

@@ -0,0 +1,188 @@
+import type { ToolBinding } from '../types'
+
+/**
+ * Options for type stub generation
+ */
+export interface TypeGeneratorOptions {
+  /**
+   * Include JSDoc comments with descriptions
+   * @default true
+   */
+  includeDescriptions?: boolean
+}
+
+/**
+ * Generate TypeScript type stubs for all tool bindings
+ *
+ * These stubs are included in the LLM system prompt so it knows
+ * the exact type signatures of available tools.
+ *
+ * Tool names match the actual function names injected into the sandbox.
+ */
+export function generateTypeStubs(
+  bindings: Record<string, ToolBinding>,
+  options: TypeGeneratorOptions = {},
+): string {
+  const { includeDescriptions = true } = options
+
+  const declarations: Array<string> = []
+
+  for (const [name, binding] of Object.entries(bindings)) {
+    const inputTypeName = `${capitalize(name)}Input`
+    const outputTypeName = `${capitalize(name)}Output`
+
+    // Generate input type
+    const inputType = jsonSchemaToTypeScript(binding.inputSchema, inputTypeName)
+    if (inputType.declaration) {
+      declarations.push(inputType.declaration)
+    }
+
+    // Generate output type if present
+    let outputTypeRef = 'unknown'
+    if (binding.outputSchema) {
+      const outputType = jsonSchemaToTypeScript(
+        binding.outputSchema,
+        outputTypeName,
+      )
+      if (outputType.declaration) {
+        declarations.push(outputType.declaration)
+      }
+      outputTypeRef = outputType.name
+    }
+
+    // Generate function declaration matching the actual sandbox function name
+    const description =
+      includeDescriptions && binding.description
+        ? `/** ${binding.description} */\n`
+        : ''
+
+    declarations.push(
+      `${description}declare function ${name}(input: ${inputType.name}): Promise<${outputTypeRef}>;`,
+    )
+  }
+
+  return declarations.join('\n\n')
+}
+
+interface TypeResult {
+  name: string
+  declaration: string
+}
+
+/**
+ * Convert a JSON Schema to a TypeScript type
+ *
+ * Supports basic types: string, number, boolean, object, array
+ */
+export function jsonSchemaToTypeScript(
+  schema: Record<string, unknown>,
+  typeName: string,
+): TypeResult {
+  const type = schemaToType(schema)
+
+  // For object schemas with properties, create a named interface
+  if (
+    schema.type === 'object' &&
+    schema.properties &&
+    Object.keys(schema.properties as object).length > 0
+  ) {
+    return {
+      name: typeName,
+      declaration: `interface ${typeName} ${type}`,
+    }
+  }
+
+  // For simple types or empty objects, create a type alias
+  return {
+    name: type,
+    declaration: '',
+  }
+}
+
+/**
+ * Convert a JSON Schema to a TypeScript type string
+ */
+function schemaToType(schema: Record<string, unknown>): string {
+  if (typeof schema !== 'object') {
+    return 'unknown'
+  }
+
+  const schemaType = schema.type
+
+  // Handle basic types
+  if (schemaType === 'string') return 'string'
+  if (schemaType === 'number' || schemaType === 'integer') return 'number'
+  if (schemaType === 'boolean') return 'boolean'
+  if (schemaType === 'null') return 'null'
+
+  // Handle arrays
+  if (schemaType === 'array') {
+    const items = schema.items as Record<string, unknown> | undefined
+    const itemType = items ? schemaToType(items) : 'unknown'
+    return `Array<${itemType}>`
+  }
+
+  // Handle objects with properties
+  if (schemaType === 'object' && schema.properties) {
+    const properties = schema.properties as Record<
+      string,
+      Record<string, unknown>
+    >
+    const required = new Set(
+      (schema.required as Array<string> | undefined) ?? [],
+    )
+
+    const props = Object.entries(properties)
+      .map(([key, propSchema]) => {
+        const optional = required.has(key) ? '' : '?'
+        const propType = schemaToType(propSchema)
+        // Handle property names that need quoting
+        const safeName = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)
+          ? key
+          : `"${key}"`
+        return `  ${safeName}${optional}: ${propType};`
+      })
+      .join('\n')
+
+    return `{\n${props}\n}`
+  }
+
+  // Handle enums
+  if (schema.enum) {
+    const enumValues = schema.enum as Array<unknown>
+    return enumValues.map((v) => JSON.stringify(v)).join(' | ')
+  }
+
+  // Handle union types (anyOf, oneOf)
+  if (schema.anyOf || schema.oneOf) {
+    const variants = (schema.anyOf || schema.oneOf) as Array<
+      Record<string, unknown>
+    >
+    return variants.map((v) => schemaToType(v)).join(' | ')
+  }
+
+  // Handle type arrays (e.g., ["string", "null"])
+  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(' | ')
+  }
+
+  // Fallback for unknown schemas
+  return 'unknown'
+}
+
+/**
+ * Capitalize the first letter of a string
+ */
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}

package/src/types.ts

@@ -0,0 +1,225 @@
+import type {
+  ServerTool,
+  ToolDefinition,
+  ToolExecutionContext,
+} from '@tanstack/ai'
+
+// ============================================================================
+// Isolate Driver Interfaces
+// ============================================================================
+
+/**
+ * Interface for isolate/sandbox drivers
+ * Each runtime environment implements this to provide sandboxed code execution
+ */
+export interface IsolateDriver {
+  /**
+   * Create a new isolated execution context with tool bindings
+   */
+  createContext: (config: IsolateConfig) => Promise<IsolateContext>
+}
+
+/**
+ * Configuration for creating an isolate context
+ */
+export interface IsolateConfig {
+  /**
+   * Tools transformed into callable bindings for the sandbox
+   */
+  bindings: Record<string, ToolBinding>
+
+  /**
+   * Execution timeout in milliseconds (default: 30000)
+   */
+  timeout?: number
+
+  /**
+   * Memory limit in MB (default: 128)
+   */
+  memoryLimit?: number
+}
+
+/**
+ * Isolated execution context with tool bindings injected
+ */
+export interface IsolateContext {
+  /**
+   * Execute generated code and return results
+   */
+  execute: <T = unknown>(code: string) => Promise<ExecutionResult<T>>
+
+  /**
+   * Clean up sandbox resources
+   */
+  dispose: () => Promise<void>
+}
+
+/**
+ * Result of code execution in the sandbox
+ */
+export interface ExecutionResult<T = unknown> {
+  /**
+   * Whether execution completed without errors
+   */
+  success: boolean
+
+  /**
+   * Return value from the executed code (if successful)
+   */
+  value?: T
+
+  /**
+   * Normalized error information (if failed)
+   */
+  error?: NormalizedError
+
+  /**
+   * Console output captured during execution
+   */
+  logs?: Array<string>
+}
+
+/**
+ * Normalized error format for cross-runtime compatibility
+ */
+export interface NormalizedError {
+  /**
+   * Error name/type
+   */
+  name: string
+
+  /**
+   * Error message
+   */
+  message: string
+
+  /**
+   * Stack trace (if available)
+   */
+  stack?: string
+
+  /**
+   * Error code (if available)
+   */
+  code?: string
+}
+
+// ============================================================================
+// Tool Binding Interfaces
+// ============================================================================
+
+/**
+ * A tool transformed into a format suitable for sandbox injection
+ */
+export interface ToolBinding {
+  /**
+   * Unique tool identifier
+   */
+  name: string
+
+  /**
+   * Human-readable description for the LLM
+   */
+  description: string
+
+  /**
+   * JSON Schema for tool input parameters
+   */
+  inputSchema: Record<string, unknown>
+
+  /**
+   * JSON Schema for tool output (optional)
+   */
+  outputSchema?: Record<string, unknown>
+
+  /**
+   * The execute function that will be injected into the sandbox.
+   * Accepts optional context for emitting custom events.
+   */
+  execute: (args: unknown, context?: ToolExecutionContext) => Promise<unknown>
+}
+
+// Re-export for convenience
+export type { ToolExecutionContext }
+
+// ============================================================================
+// Code Mode Tool Types
+// ============================================================================
+
+/**
+ * Tool types that can be passed to Code Mode
+ */
+export type CodeModeTool =
+  | ServerTool<any, any, any>
+  | ToolDefinition<any, any, any>
+
+/**
+ * Configuration for createCodeModeTool
+ */
+export interface CodeModeToolConfig {
+  /**
+   * Isolate driver for sandboxed code execution
+   */
+  driver: IsolateDriver
+
+  /**
+   * Tools to expose as external_* functions in the sandbox
+   */
+  tools: Array<CodeModeTool>
+
+  /**
+   * Execution timeout in milliseconds (default: 30000)
+   */
+  timeout?: number
+
+  /**
+   * Memory limit for isolate in MB (default: 128)
+   */
+  memoryLimit?: number
+
+  /**
+   * Optional function to get additional bindings dynamically.
+   * Called at execution time (each execute_typescript call) to get current skill bindings.
+   * These are merged with the static external_* bindings.
+   *
+   * @returns Record of skill bindings with skill_ prefix
+   *
+   * @example
+   * ```typescript
+   * getSkillBindings: async () => {
+   *   const skills = await storage.loadAll()
+   *   return skillsToBindings(skills, 'skill_')
+   * }
+   * ```
+   */
+  getSkillBindings?: () => Promise<Record<string, ToolBinding>>
+}
+
+/**
+ * Result returned by the execute_typescript tool
+ */
+export interface CodeModeToolResult {
+  /**
+   * Whether execution completed without errors
+   */
+  success: boolean
+
+  /**
+   * Return value from the executed code (if successful)
+   */
+  result?: unknown
+
+  /**
+   * Console output captured during execution
+   */
+  logs?: Array<string>
+
+  /**
+   * Error details if execution failed
+   */
+  error?: {
+    message: string
+    name?: string
+    line?: number
+  }
+}