@tanstack/ai-code-mode-skills 0.1.0

package/src/skills-to-bindings.ts

@@ -0,0 +1,134 @@
+import type { ToolExecutionContext } from '@tanstack/ai'
+import type { ToolBinding } from '@tanstack/ai-code-mode'
+import type { Skill, SkillStorage } from './types'
+
+interface SkillsToBindingsOptions {
+  /**
+   * Skills to convert to bindings
+   */
+  skills: Array<Skill>
+
+  /**
+   * Tool execution context for emitting custom events
+   */
+  context?: ToolExecutionContext
+
+  /**
+   * Function to execute skill code in the sandbox
+   * The skill code receives `input` as a variable
+   */
+  executeInSandbox: (code: string, input: unknown) => Promise<unknown>
+
+  /**
+   * Storage for updating execution stats
+   */
+  storage: SkillStorage
+}
+
+/**
+ * Convert skills to sandbox bindings with the skill_ prefix.
+ * Skills become callable functions inside the sandbox.
+ */
+export function skillsToBindings({
+  skills,
+  context,
+  executeInSandbox,
+  storage,
+}: SkillsToBindingsOptions): Record<string, ToolBinding> {
+  const bindings: Record<string, ToolBinding> = {}
+
+  for (const skill of skills) {
+    const bindingName = `skill_${skill.name}`
+
+    bindings[bindingName] = {
+      name: bindingName,
+      description: skill.description,
+      inputSchema: skill.inputSchema,
+      outputSchema: skill.outputSchema,
+      execute: async (input: unknown) => {
+        const startTime = Date.now()
+
+        // Emit skill call event
+        context?.emitCustomEvent('code_mode:skill_call', {
+          skill: skill.name,
+          input,
+          timestamp: startTime,
+        })
+
+        try {
+          // Wrap the skill code to receive input as a variable
+          const wrappedCode = `
+            const input = ${JSON.stringify(input)};
+            ${skill.code}
+          `
+
+          const result = await executeInSandbox(wrappedCode, input)
+          const duration = Date.now() - startTime
+
+          // Emit success event
+          context?.emitCustomEvent('code_mode:skill_result', {
+            skill: skill.name,
+            result,
+            duration,
+            timestamp: Date.now(),
+          })
+
+          // Update stats (async, don't await to not block)
+          storage.updateStats(skill.name, true).catch(() => {
+            // Silently ignore stats update failures
+          })
+
+          return result
+        } catch (error) {
+          const duration = Date.now() - startTime
+
+          // Emit error event
+          context?.emitCustomEvent('code_mode:skill_error', {
+            skill: skill.name,
+            error: error instanceof Error ? error.message : String(error),
+            duration,
+            timestamp: Date.now(),
+          })
+
+          // Update stats (async, don't await)
+          storage.updateStats(skill.name, false).catch(() => {
+            // Silently ignore stats update failures
+          })
+
+          throw error
+        }
+      },
+    }
+  }
+
+  return bindings
+}
+
+/**
+ * Create a simple binding record for skills without full sandbox execution.
+ * This is used when skills are being documented in the system prompt
+ * but not yet being executed.
+ */
+export function skillsToSimpleBindings(
+  skills: Array<Skill>,
+): Record<string, ToolBinding> {
+  const bindings: Record<string, ToolBinding> = {}
+
+  for (const skill of skills) {
+    const bindingName = `skill_${skill.name}`
+
+    bindings[bindingName] = {
+      name: bindingName,
+      description: skill.description,
+      inputSchema: skill.inputSchema,
+      outputSchema: skill.outputSchema,
+      execute: async () => {
+        throw new Error(
+          `Skill ${skill.name} is not available for execution in this context`,
+        )
+      },
+    }
+  }
+
+  return bindings
+}

package/src/skills-to-tools.ts

@@ -0,0 +1,319 @@
+import { toolDefinition } from '@tanstack/ai'
+import {
+  createEventAwareBindings,
+  stripTypeScript,
+  toolsToBindings,
+} from '@tanstack/ai-code-mode'
+import { z } from 'zod'
+import type { ServerTool, ToolExecutionContext } from '@tanstack/ai'
+import type {
+  CodeModeTool,
+  IsolateDriver,
+  ToolBinding,
+} from '@tanstack/ai-code-mode'
+import type { Skill, SkillStorage } from './types'
+
+/**
+ * Options for converting a single skill to a tool
+ */
+export interface SkillToToolOptions {
+  /**
+   * The skill to convert
+   */
+  skill: Skill
+
+  /**
+   * Isolate driver for executing skill code
+   */
+  driver: IsolateDriver
+
+  /**
+   * Pre-computed bindings for external_* functions
+   */
+  bindings: Record<string, ToolBinding>
+
+  /**
+   * Storage for updating execution stats
+   */
+  storage: SkillStorage
+
+  /**
+   * Timeout for skill execution in ms
+   * @default 30000
+   */
+  timeout?: number
+
+  /**
+   * Memory limit in bytes
+   * @default 128
+   */
+  memoryLimit?: number
+}
+
+interface SkillsToToolsOptions {
+  /**
+   * Skills to convert to tools
+   */
+  skills: Array<Skill>
+
+  /**
+   * Isolate driver for executing skill code
+   */
+  driver: IsolateDriver
+
+  /**
+   * Original tools that become external_* bindings
+   * (so skills can call external_* functions)
+   */
+  tools: Array<CodeModeTool>
+
+  /**
+   * Storage for updating execution stats
+   */
+  storage: SkillStorage
+
+  /**
+   * Timeout for skill execution in ms
+   * @default 30000
+   */
+  timeout?: number
+
+  /**
+   * Memory limit in bytes
+   * @default 128
+   */
+  memoryLimit?: number
+}
+
+/**
+ * Convert JSON Schema to Zod schema.
+ * This is a simplified converter that handles common cases.
+ */
+function jsonSchemaToZod(schema: Record<string, unknown>): z.ZodType {
+  const type = schema.type as string
+
+  if (type === 'string') {
+    let zodString = z.string()
+    if (schema.description) {
+      zodString = zodString.describe(schema.description as string)
+    }
+    return zodString
+  }
+  if (type === 'number' || type === 'integer') {
+    let zodNum = z.number()
+    if (schema.description) {
+      zodNum = zodNum.describe(schema.description as string)
+    }
+    return zodNum
+  }
+  if (type === 'boolean') {
+    let zodBool = z.boolean()
+    if (schema.description) {
+      zodBool = zodBool.describe(schema.description as string)
+    }
+    return zodBool
+  }
+  if (type === 'array') {
+    const items = schema.items as Record<string, unknown> | undefined
+    if (items) {
+      return z.array(jsonSchemaToZod(items))
+    }
+    return z.array(z.unknown())
+  }
+  if (type === 'object') {
+    const properties = schema.properties as
+      | Record<string, Record<string, unknown>>
+      | undefined
+    const required = (schema.required as Array<string> | undefined) ?? []
+
+    if (properties) {
+      const shape: Record<string, z.ZodType> = {}
+      for (const [key, propSchema] of Object.entries(properties)) {
+        let zodProp = jsonSchemaToZod(propSchema)
+        if (!required.includes(key)) {
+          zodProp = zodProp.optional()
+        }
+        shape[key] = zodProp
+      }
+      return z.object(shape)
+    }
+    return z.record(z.string(), z.unknown())
+  }
+
+  // Fallback
+  return z.unknown()
+}
+
+/**
+ * Convert a single skill to a ServerTool that the LLM can call directly.
+ * The skill executes its code in the sandbox with access to external_* bindings.
+ */
+export function skillToTool({
+  skill,
+  driver,
+  bindings,
+  storage,
+  timeout = 30000,
+  memoryLimit = 128,
+}: SkillToToolOptions): ServerTool<any, any, any> {
+  // Generate input and output schemas from JSON Schema
+  const inputSchema = jsonSchemaToZod(skill.inputSchema)
+  const outputSchema = jsonSchemaToZod(skill.outputSchema)
+
+  return toolDefinition({
+    name: skill.name,
+    description: `[SKILL] ${skill.description}`,
+    inputSchema,
+    outputSchema,
+  }).server(async (input: unknown, context?: ToolExecutionContext) => {
+    const startTime = Date.now()
+    const emitCustomEvent = context?.emitCustomEvent || (() => {})
+
+    // Emit skill call event
+    emitCustomEvent('code_mode:skill_call', {
+      skill: skill.name,
+      input,
+      timestamp: startTime,
+    })
+
+    let isolateContext = null
+
+    try {
+      console.log(
+        `[Skill:${skill.name}] Starting execution with input:`,
+        JSON.stringify(input).substring(0, 200),
+      )
+
+      // Wrap the skill code to receive input as a variable
+      const wrappedCode = `
+          const input = ${JSON.stringify(input)};
+          ${skill.code}
+        `
+      console.log(
+        `[Skill:${skill.name}] Wrapped code (first 500 chars):`,
+        wrappedCode.substring(0, 500),
+      )
+
+      // Strip TypeScript to JavaScript
+      const strippedCode = await stripTypeScript(wrappedCode)
+      console.log(
+        `[Skill:${skill.name}] Stripped code (first 500 chars):`,
+        strippedCode.substring(0, 500),
+      )
+
+      // Create event-aware bindings
+      const eventAwareBindings = createEventAwareBindings(
+        bindings,
+        emitCustomEvent,
+      )
+      console.log(
+        `[Skill:${skill.name}] Event-aware bindings:`,
+        Object.keys(eventAwareBindings),
+      )
+
+      // Create sandbox context
+      console.log(`[Skill:${skill.name}] Creating sandbox context...`)
+      isolateContext = await driver.createContext({
+        bindings: eventAwareBindings,
+        timeout,
+        memoryLimit,
+      })
+      console.log(`[Skill:${skill.name}] Sandbox context created`)
+
+      // Execute the code
+      console.log(`[Skill:${skill.name}] Executing code...`)
+      const executionResult = await isolateContext.execute(strippedCode)
+      console.log(`[Skill:${skill.name}] Execution result:`, {
+        success: executionResult.success,
+        hasValue: 'value' in executionResult,
+        error: executionResult.error,
+        logs: executionResult.logs,
+      })
+
+      const duration = Date.now() - startTime
+
+      if (!executionResult.success) {
+        console.error(
+          `[Skill:${skill.name}] Execution failed:`,
+          executionResult.error,
+        )
+        throw new Error(
+          executionResult.error?.message || 'Skill execution failed',
+        )
+      }
+
+      // Emit success event
+      emitCustomEvent('code_mode:skill_result', {
+        skill: skill.name,
+        result: executionResult.value,
+        duration,
+        timestamp: Date.now(),
+      })
+
+      // Update stats (async, don't await to not block)
+      storage.updateStats(skill.name, true).catch(() => {
+        // Silently ignore stats update failures
+      })
+
+      return executionResult.value
+    } catch (error) {
+      const duration = Date.now() - startTime
+      console.error(`[Skill:${skill.name}] CAUGHT ERROR:`, {
+        message: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        duration,
+      })
+
+      // Emit error event
+      emitCustomEvent('code_mode:skill_error', {
+        skill: skill.name,
+        error: error instanceof Error ? error.message : String(error),
+        duration,
+        timestamp: Date.now(),
+      })
+
+      // Update stats (async, don't await)
+      storage.updateStats(skill.name, false).catch(() => {
+        // Silently ignore stats update failures
+      })
+
+      throw error
+    } finally {
+      if (isolateContext) {
+        await isolateContext.dispose()
+      }
+    }
+  })
+}
+
+/**
+ * Convert multiple skills to ServerTools that the LLM can call directly.
+ * Skills become real tools that execute their code in the sandbox.
+ */
+export function skillsToTools({
+  skills,
+  driver,
+  tools,
+  storage,
+  timeout = 30000,
+  memoryLimit = 128,
+}: SkillsToToolsOptions): Array<ServerTool<any, any, any>> {
+  // Pre-compute bindings from tools (these are shared across all skill executions)
+  console.log(
+    '[SkillsToTools] Creating bindings from tools:',
+    tools.map((t) => t.name),
+  )
+  const bindings = toolsToBindings(tools, 'external_')
+  console.log('[SkillsToTools] Created bindings:', Object.keys(bindings))
+
+  return skills.map((skill) =>
+    skillToTool({
+      skill,
+      driver,
+      bindings,
+      storage,
+      timeout,
+      memoryLimit,
+    }),
+  )
+}

package/src/storage/file-storage.ts

@@ -0,0 +1,243 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { existsSync } from 'node:fs'
+import { createDefaultTrustStrategy } from '../trust-strategies'
+import type {
+  Skill,
+  SkillIndexEntry,
+  SkillSearchOptions,
+  SkillStorage,
+} from '../types'
+import type { TrustStrategy } from '../trust-strategies'
+
+export interface FileSkillStorageOptions {
+  /**
+   * Directory path for storing skills
+   */
+  directory: string
+
+  /**
+   * Trust strategy for determining skill trust levels
+   * @default createDefaultTrustStrategy()
+   */
+  trustStrategy?: TrustStrategy
+}
+
+/**
+ * File-system based skill storage
+ *
+ * Directory structure:
+ *   .skills/
+ *     _index.json          # Fast catalog loading
+ *     fetch_github_stats/
+ *       meta.json          # Metadata (description, schemas, hints, stats)
+ *       code.ts            # The actual TypeScript code
+ *     deploy_to_prod/
+ *       meta.json
+ *       code.ts
+ */
+export function createFileSkillStorage(
+  directoryOrOptions: string | FileSkillStorageOptions,
+): SkillStorage {
+  const options =
+    typeof directoryOrOptions === 'string'
+      ? { directory: directoryOrOptions }
+      : directoryOrOptions
+
+  const { directory, trustStrategy = createDefaultTrustStrategy() } = options
+  const indexPath = join(directory, '_index.json')
+
+  console.log('[FileSkillStorage] Initialized with directory:', directory)
+
+  async function ensureDirectory(): Promise<void> {
+    if (!existsSync(directory)) {
+      console.log('[FileSkillStorage] Creating directory:', directory)
+      await mkdir(directory, { recursive: true })
+    }
+  }
+
+  async function loadIndex(): Promise<Array<SkillIndexEntry>> {
+    await ensureDirectory()
+
+    if (!existsSync(indexPath)) {
+      return []
+    }
+
+    const content = await readFile(indexPath, 'utf-8')
+    return JSON.parse(content) as Array<SkillIndexEntry>
+  }
+
+  async function loadAll(): Promise<Array<Skill>> {
+    const index = await loadIndex()
+    const skills: Array<Skill> = []
+
+    for (const entry of index) {
+      const skill = await get(entry.name)
+      if (skill) {
+        skills.push(skill)
+      }
+    }
+
+    return skills
+  }
+
+  async function saveIndex(index: Array<SkillIndexEntry>): Promise<void> {
+    await writeFile(indexPath, JSON.stringify(index, null, 2))
+  }
+
+  async function get(name: string): Promise<Skill | null> {
+    const skillDir = join(directory, name)
+    const metaPath = join(skillDir, 'meta.json')
+    const codePath = join(skillDir, 'code.ts')
+
+    if (!existsSync(metaPath)) {
+      return null
+    }
+
+    const [metaContent, code] = await Promise.all([
+      readFile(metaPath, 'utf-8'),
+      readFile(codePath, 'utf-8'),
+    ])
+
+    const meta = JSON.parse(metaContent) as Omit<Skill, 'code'>
+    return { ...meta, code }
+  }
+
+  async function save(
+    skill: Omit<Skill, 'createdAt' | 'updatedAt'>,
+  ): Promise<Skill> {
+    await ensureDirectory()
+
+    const skillDir = join(directory, skill.name)
+    const metaPath = join(skillDir, 'meta.json')
+    const codePath = join(skillDir, 'code.ts')
+
+    const now = new Date().toISOString()
+    const existing = await get(skill.name)
+
+    const fullSkill: Skill = {
+      ...skill,
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    }
+
+    // Separate code from metadata
+    const { code, ...meta } = fullSkill
+
+    // Write skill files
+    await mkdir(skillDir, { recursive: true })
+    await Promise.all([
+      writeFile(metaPath, JSON.stringify(meta, null, 2)),
+      writeFile(codePath, code),
+    ])
+
+    // Update index
+    const index = await loadIndex()
+    const indexEntry: SkillIndexEntry = {
+      id: fullSkill.id,
+      name: fullSkill.name,
+      description: fullSkill.description,
+      usageHints: fullSkill.usageHints,
+      trustLevel: fullSkill.trustLevel,
+    }
+
+    const existingIdx = index.findIndex((s) => s.name === skill.name)
+    if (existingIdx >= 0) {
+      index[existingIdx] = indexEntry
+    } else {
+      index.push(indexEntry)
+    }
+    await saveIndex(index)
+
+    return fullSkill
+  }
+
+  async function deleteSkill(name: string): Promise<boolean> {
+    const skillDir = join(directory, name)
+
+    if (!existsSync(skillDir)) {
+      return false
+    }
+
+    await rm(skillDir, { recursive: true })
+
+    // Update index
+    const index = await loadIndex()
+    const filtered = index.filter((s) => s.name !== name)
+    await saveIndex(filtered)
+
+    return true
+  }
+
+  async function search(
+    query: string,
+    options: SkillSearchOptions = {},
+  ): Promise<Array<SkillIndexEntry>> {
+    const { limit = 5 } = options
+    const index = await loadIndex()
+
+    // Simple text matching - can be replaced with embeddings
+    const queryLower = query.toLowerCase()
+    const terms = queryLower.split(/\s+/)
+
+    const scored = index.map((skill) => {
+      let score = 0
+      const searchText = [skill.name, skill.description, ...skill.usageHints]
+        .join(' ')
+        .toLowerCase()
+
+      for (const term of terms) {
+        if (searchText.includes(term)) {
+          score += 1
+        }
+        // Boost exact name matches
+        if (skill.name.toLowerCase().includes(term)) {
+          score += 2
+        }
+      }
+
+      return { skill, score }
+    })
+
+    return scored
+      .filter((s) => s.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit)
+      .map((s) => s.skill)
+  }
+
+  async function updateStats(name: string, success: boolean): Promise<void> {
+    const skill = await get(name)
+    if (!skill) return
+
+    const { executions, successRate } = skill.stats
+    const newExecutions = executions + 1
+    const newSuccessRate =
+      (successRate * executions + (success ? 1 : 0)) / newExecutions
+
+    const newStats = { executions: newExecutions, successRate: newSuccessRate }
+
+    // Use trust strategy to calculate new trust level
+    const newTrustLevel = trustStrategy.calculateTrustLevel(
+      skill.trustLevel,
+      newStats,
+    )
+
+    await save({
+      ...skill,
+      stats: newStats,
+      trustLevel: newTrustLevel,
+    })
+  }
+
+  return {
+    loadIndex,
+    loadAll,
+    get,
+    save,
+    delete: deleteSkill,
+    search,
+    updateStats,
+    trustStrategy,
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,6 @@
+// Storage implementations
+export { createFileSkillStorage } from './file-storage'
+export { createMemorySkillStorage } from './memory-storage'
+
+// Re-export types
+export type { SkillStorage, Skill, SkillIndexEntry } from '../types'