@tanstack/ai-code-mode-skills 0.1.0

package/src/storage/memory-storage.ts

@@ -0,0 +1,163 @@
+import { createDefaultTrustStrategy } from '../trust-strategies'
+import type {
+  Skill,
+  SkillIndexEntry,
+  SkillSearchOptions,
+  SkillStorage,
+} from '../types'
+import type { TrustStrategy } from '../trust-strategies'
+
+export interface MemorySkillStorageOptions {
+  /**
+   * Initial skills to populate the storage with
+   */
+  initialSkills?: Array<Skill>
+
+  /**
+   * Trust strategy for determining skill trust levels
+   * @default createDefaultTrustStrategy()
+   */
+  trustStrategy?: TrustStrategy
+}
+
+/**
+ * In-memory skill storage for testing and demos
+ */
+export function createMemorySkillStorage(
+  optionsOrSkills: MemorySkillStorageOptions | Array<Skill> = [],
+): SkillStorage {
+  const options = Array.isArray(optionsOrSkills)
+    ? { initialSkills: optionsOrSkills }
+    : optionsOrSkills
+
+  const { initialSkills = [], trustStrategy = createDefaultTrustStrategy() } =
+    options
+
+  // Store skills in a Map for O(1) lookup
+  const skills = new Map<string, Skill>()
+
+  // Initialize with any provided skills
+  for (const skill of initialSkills) {
+    skills.set(skill.name, skill)
+  }
+
+  async function loadIndex(): Promise<Array<SkillIndexEntry>> {
+    return Array.from(skills.values()).map((skill) => ({
+      id: skill.id,
+      name: skill.name,
+      description: skill.description,
+      usageHints: skill.usageHints,
+      trustLevel: skill.trustLevel,
+    }))
+  }
+
+  async function loadAll(): Promise<Array<Skill>> {
+    return Array.from(skills.values())
+  }
+
+  async function get(name: string): Promise<Skill | null> {
+    return skills.get(name) ?? null
+  }
+
+  async function save(
+    skill: Omit<Skill, 'createdAt' | 'updatedAt'>,
+  ): Promise<Skill> {
+    const now = new Date().toISOString()
+    const existing = skills.get(skill.name)
+
+    const fullSkill: Skill = {
+      ...skill,
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    }
+
+    skills.set(skill.name, fullSkill)
+    return fullSkill
+  }
+
+  async function deleteSkill(name: string): Promise<boolean> {
+    if (!skills.has(name)) {
+      return false
+    }
+    skills.delete(name)
+    return true
+  }
+
+  async function search(
+    query: string,
+    options: SkillSearchOptions = {},
+  ): Promise<Array<SkillIndexEntry>> {
+    const { limit = 5 } = options
+
+    // Simple text matching
+    const queryLower = query.toLowerCase()
+    const terms = queryLower.split(/\s+/)
+
+    const scored = Array.from(skills.values()).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) => ({
+        id: s.skill.id,
+        name: s.skill.name,
+        description: s.skill.description,
+        usageHints: s.skill.usageHints,
+        trustLevel: s.skill.trustLevel,
+      }))
+  }
+
+  async function updateStats(name: string, success: boolean): Promise<void> {
+    const skill = skills.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,
+    )
+
+    skills.set(name, {
+      ...skill,
+      stats: newStats,
+      trustLevel: newTrustLevel,
+      updatedAt: new Date().toISOString(),
+    })
+  }
+
+  return {
+    loadIndex,
+    loadAll,
+    get,
+    save,
+    delete: deleteSkill,
+    search,
+    updateStats,
+    trustStrategy,
+  }
+}

package/src/trust-strategies.ts

@@ -0,0 +1,142 @@
+import type { SkillStats, TrustLevel } from './types'
+
+/**
+ * Strategy for determining skill trust levels
+ */
+export interface TrustStrategy {
+  /**
+   * Get the initial trust level for a newly created skill
+   */
+  getInitialTrustLevel: () => TrustLevel
+
+  /**
+   * Calculate the new trust level based on execution stats
+   */
+  calculateTrustLevel: (
+    currentLevel: TrustLevel,
+    stats: SkillStats,
+  ) => TrustLevel
+}
+
+/**
+ * Default trust strategy - skills must earn trust through successful executions
+ *
+ * - untrusted: New skill (0 executions)
+ * - provisional: 10+ executions with ≥90% success rate
+ * - trusted: 100+ executions with ≥95% success rate
+ */
+export function createDefaultTrustStrategy(): TrustStrategy {
+  return {
+    getInitialTrustLevel: () => 'untrusted',
+
+    calculateTrustLevel: (currentLevel, stats) => {
+      const { executions, successRate } = stats
+
+      if (
+        currentLevel === 'untrusted' &&
+        executions >= 10 &&
+        successRate >= 0.9
+      ) {
+        return 'provisional'
+      }
+
+      if (
+        currentLevel === 'provisional' &&
+        executions >= 100 &&
+        successRate >= 0.95
+      ) {
+        return 'trusted'
+      }
+
+      return currentLevel
+    },
+  }
+}
+
+/**
+ * Always trusted strategy - skills are immediately trusted upon creation
+ *
+ * Use this for development/testing or when you trust the LLM's code generation
+ */
+export function createAlwaysTrustedStrategy(): TrustStrategy {
+  return {
+    getInitialTrustLevel: () => 'trusted',
+    calculateTrustLevel: () => 'trusted',
+  }
+}
+
+/**
+ * Relaxed trust strategy - faster trust promotion for development
+ *
+ * - untrusted: New skill (0 executions)
+ * - provisional: 3+ executions with ≥80% success rate
+ * - trusted: 10+ executions with ≥90% success rate
+ */
+export function createRelaxedTrustStrategy(): TrustStrategy {
+  return {
+    getInitialTrustLevel: () => 'untrusted',
+
+    calculateTrustLevel: (currentLevel, stats) => {
+      const { executions, successRate } = stats
+
+      if (
+        currentLevel === 'untrusted' &&
+        executions >= 3 &&
+        successRate >= 0.8
+      ) {
+        return 'provisional'
+      }
+
+      if (
+        currentLevel === 'provisional' &&
+        executions >= 10 &&
+        successRate >= 0.9
+      ) {
+        return 'trusted'
+      }
+
+      return currentLevel
+    },
+  }
+}
+
+/**
+ * Custom trust strategy with configurable thresholds
+ */
+export function createCustomTrustStrategy(config: {
+  initialLevel?: TrustLevel
+  provisionalThreshold?: { executions: number; successRate: number }
+  trustedThreshold?: { executions: number; successRate: number }
+}): TrustStrategy {
+  const {
+    initialLevel = 'untrusted',
+    provisionalThreshold = { executions: 10, successRate: 0.9 },
+    trustedThreshold = { executions: 100, successRate: 0.95 },
+  } = config
+
+  return {
+    getInitialTrustLevel: () => initialLevel,
+
+    calculateTrustLevel: (currentLevel, stats) => {
+      const { executions, successRate } = stats
+
+      if (
+        currentLevel === 'untrusted' &&
+        executions >= provisionalThreshold.executions &&
+        successRate >= provisionalThreshold.successRate
+      ) {
+        return 'provisional'
+      }
+
+      if (
+        currentLevel === 'provisional' &&
+        executions >= trustedThreshold.executions &&
+        successRate >= trustedThreshold.successRate
+      ) {
+        return 'trusted'
+      }
+
+      return currentLevel
+    },
+  }
+}

package/src/types.ts

@@ -0,0 +1,289 @@
+import type { AnyTextAdapter, ModelMessage, ToolRegistry } from '@tanstack/ai'
+import type { CodeModeToolConfig } from '@tanstack/ai-code-mode'
+import type { TrustStrategy } from './trust-strategies'
+
+// ============================================================================
+// Trust Levels
+// ============================================================================
+
+/**
+ * Trust level for a skill
+ * - untrusted: Newly created, not yet proven
+ * - provisional: Has been successfully executed 10+ times with 90%+ success
+ * - trusted: Has been successfully executed 100+ times with 95%+ success
+ */
+export type TrustLevel = 'untrusted' | 'provisional' | 'trusted'
+
+// ============================================================================
+// Skill Statistics
+// ============================================================================
+
+/**
+ * Execution statistics for a skill
+ */
+export interface SkillStats {
+  /**
+   * Total number of times this skill has been executed
+   */
+  executions: number
+
+  /**
+   * Success rate (0-1) based on execution history
+   */
+  successRate: number
+}
+
+// ============================================================================
+// Skill Types
+// ============================================================================
+
+/**
+ * A reusable skill that can be executed in the Code Mode sandbox
+ */
+export interface Skill {
+  /**
+   * Unique identifier for the skill
+   */
+  id: string
+
+  /**
+   * Unique name in snake_case (e.g., 'fetch_github_stats')
+   * This becomes the function name with skill_ prefix in the sandbox
+   */
+  name: string
+
+  /**
+   * Human-readable description of what the skill does
+   */
+  description: string
+
+  /**
+   * TypeScript code that implements the skill
+   * The code receives `input` as a variable and can call:
+   * - external_* functions (tools)
+   * - other skill_* functions (skills)
+   * Should return a value
+   */
+  code: string
+
+  /**
+   * JSON Schema describing the input parameter
+   */
+  inputSchema: Record<string, unknown>
+
+  /**
+   * JSON Schema describing the return value
+   */
+  outputSchema: Record<string, unknown>
+
+  /**
+   * Hints about when to use this skill
+   * e.g., "Use when comparing NPM package popularity"
+   */
+  usageHints: Array<string>
+
+  /**
+   * Names of other skills this skill depends on/calls
+   */
+  dependsOn: Array<string>
+
+  /**
+   * Trust level based on execution history
+   */
+  trustLevel: TrustLevel
+
+  /**
+   * Execution statistics
+   */
+  stats: SkillStats
+
+  /**
+   * ISO timestamp when the skill was created
+   */
+  createdAt: string
+
+  /**
+   * ISO timestamp when the skill was last updated
+   */
+  updatedAt: string
+}
+
+// ============================================================================
+// Skill Index Types
+// ============================================================================
+
+/**
+ * Lightweight skill entry for the index (metadata only, no code)
+ * Used for fast loading and skill selection
+ */
+export type SkillIndexEntry = Pick<
+  Skill,
+  'id' | 'name' | 'description' | 'usageHints' | 'trustLevel'
+>
+
+// ============================================================================
+// Storage Interface
+// ============================================================================
+
+/**
+ * Options for searching skills
+ */
+export interface SkillSearchOptions {
+  /**
+   * Maximum number of results to return
+   * @default 5
+   */
+  limit?: number
+}
+
+/**
+ * Interface for skill storage implementations
+ */
+export interface SkillStorage {
+  /**
+   * Load the skill index (lightweight metadata for all skills)
+   */
+  loadIndex: () => Promise<Array<SkillIndexEntry>>
+
+  /**
+   * Load all skills with full details (including code)
+   */
+  loadAll: () => Promise<Array<Skill>>
+
+  /**
+   * Get a skill by name
+   */
+  get: (name: string) => Promise<Skill | null>
+
+  /**
+   * Save a skill (create or update)
+   */
+  save: (skill: Omit<Skill, 'createdAt' | 'updatedAt'>) => Promise<Skill>
+
+  /**
+   * Delete a skill by name
+   */
+  delete: (name: string) => Promise<boolean>
+
+  /**
+   * Search for skills by query
+   */
+  search: (
+    query: string,
+    options?: SkillSearchOptions,
+  ) => Promise<Array<SkillIndexEntry>>
+
+  /**
+   * Update execution statistics for a skill
+   */
+  updateStats: (name: string, success: boolean) => Promise<void>
+
+  /**
+   * Trust strategy used by this storage (optional, for creating new skills)
+   */
+  trustStrategy?: TrustStrategy
+}
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+/**
+ * Configuration for the skills system
+ */
+export interface SkillsConfig {
+  /**
+   * Storage implementation for skills
+   */
+  storage: SkillStorage
+
+  /**
+   * Maximum number of skills to load into context per request
+   * @default 5
+   */
+  maxSkillsInContext?: number
+
+  /**
+   * Trust strategy for determining skill trust levels
+   * @default createDefaultTrustStrategy()
+   */
+  trustStrategy?: TrustStrategy
+}
+
+/**
+ * Options for codeModeWithSkills
+ */
+export interface CodeModeWithSkillsOptions {
+  /**
+   * Code Mode tool configuration (driver, tools, timeout, memoryLimit)
+   */
+  config: CodeModeToolConfig
+
+  /**
+   * Text adapter for skill selection (should be a cheap/fast model)
+   */
+  adapter: AnyTextAdapter
+
+  /**
+   * Skills configuration
+   */
+  skills: SkillsConfig
+
+  /**
+   * Current conversation messages (used for context-aware skill selection)
+   */
+  messages: Array<ModelMessage>
+
+  /**
+   * Whether to include skills as direct tools (not just sandbox bindings).
+   * When true, skills become first-class tools the LLM can call directly.
+   * @default true
+   */
+  skillsAsTools?: boolean
+}
+
+/**
+ * Result from codeModeWithSkills
+ */
+export interface CodeModeWithSkillsResult {
+  /**
+   * Tool registry for dynamic tool management.
+   * Pass this to chat() via the toolRegistry option.
+   * Skills registered mid-stream will be added to this registry.
+   */
+  toolsRegistry: ToolRegistry
+
+  /**
+   * System prompt documenting available skills and external functions
+   */
+  systemPrompt: string
+
+  /**
+   * Skills that were selected for this request
+   */
+  selectedSkills: Array<Skill>
+}
+
+// ============================================================================
+// Skill Binding Types (internal)
+// ============================================================================
+
+/**
+ * A skill transformed into a format suitable for sandbox injection
+ */
+export interface SkillBinding {
+  /**
+   * Function name with skill_ prefix
+   */
+  name: string
+
+  /**
+   * The skill this binding wraps
+   */
+  skill: Skill
+
+  /**
+   * Execute function that runs the skill code
+   */
+  execute: (input: unknown) => Promise<unknown>
+}