wu-framework 1.1.6 → 1.1.8

package/src/ai/wu-ai-schema.js

@@ -0,0 +1,225 @@
+/**
+ * WU-AI-SCHEMA: Tool schema generation for function calling
+ *
+ * Converts wu.ai.action() definitions into the canonical tool format
+ * that providers consume. Also handles input sanitization for prompts.
+ *
+ * Canonical tool format:
+ * { name: string, description: string, parameters: JSONSchema }
+ */
+
+// ─── Sanitization ────────────────────────────────────────────────
+
+const SENSITIVE_KEYS = ['password', 'token', 'apiKey', 'secret', 'credential', 'authorization', 'cookie', 'session'];
+
+/**
+ * Sanitize data before injecting into prompts.
+ * Prevents prompt injection and redacts sensitive fields.
+ *
+ * @param {*} data - Any value to sanitize
+ * @param {number} [maxChars=2000] - Max chars per value
+ * @returns {string} Safe string representation
+ */
+export function sanitizeForPrompt(data, maxChars = 2000) {
+  if (data === null || data === undefined) return 'null';
+  if (typeof data === 'function') return '[Function]';
+  if (typeof data === 'symbol') return '[Symbol]';
+
+  if (typeof data === 'string') {
+    const truncated = data.length > maxChars ? data.slice(0, maxChars) + '...[truncated]' : data;
+    return `<user_data>${truncated}</user_data>`;
+  }
+
+  if (typeof data === 'number' || typeof data === 'boolean') {
+    return String(data);
+  }
+
+  if (typeof data === 'object') {
+    const redacted = redactSensitive(data);
+    const json = JSON.stringify(redacted);
+    if (json.length > maxChars) {
+      return `<user_data>${json.slice(0, maxChars)}...[truncated]</user_data>`;
+    }
+    return `<user_data>${json}</user_data>`;
+  }
+
+  return String(data).slice(0, maxChars);
+}
+
+/**
+ * Deep-clone an object, replacing sensitive keys with [REDACTED].
+ *
+ * @param {*} obj
+ * @param {number} [depth=0]
+ * @returns {*}
+ */
+export function redactSensitive(obj, depth = 0) {
+  if (depth > 10) return '[MAX_DEPTH]';
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj !== 'object') return obj;
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => redactSensitive(item, depth + 1));
+  }
+
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const lowerKey = key.toLowerCase();
+    if (SENSITIVE_KEYS.some(sk => lowerKey.includes(sk.toLowerCase()))) {
+      result[key] = '[REDACTED]';
+    } else {
+      result[key] = redactSensitive(value, depth + 1);
+    }
+  }
+  return result;
+}
+
+// ─── Template Interpolation ──────────────────────────────────────
+
+/**
+ * Interpolate {{var}} placeholders in a template string.
+ * Supports dot-notation: {{data.user.name}}
+ *
+ * @param {string} template
+ * @param {object} vars - Variable map { data: ..., context: ... }
+ * @returns {string}
+ */
+export function interpolate(template, vars) {
+  return template.replace(/\{\{(\w+(?:\.\w+)*)\}\}/g, (_match, path) => {
+    const value = path.split('.').reduce((obj, key) => obj?.[key], vars);
+    if (value === undefined || value === null) return '';
+    if (typeof value === 'object') return sanitizeForPrompt(value);
+    return String(value);
+  });
+}
+
+// ─── Tool Schema Builder ─────────────────────────────────────────
+
+/**
+ * Build canonical tool definitions from registered actions.
+ *
+ * @param {Map<string, object>} actions - Map of action name → config
+ * @returns {Array<{ name: string, description: string, parameters: object }>}
+ */
+export function buildToolSchemas(actions) {
+  const tools = [];
+
+  for (const [name, config] of actions) {
+    tools.push({
+      name,
+      description: config.description || `Execute action: ${name}`,
+      parameters: normalizeParameters(config.parameters),
+    });
+  }
+
+  return tools;
+}
+
+/**
+ * Normalize user-provided parameter definitions into JSON Schema.
+ *
+ * Accepts two formats:
+ * 1. Full JSON Schema: { type: 'object', properties: {...}, required: [...] }
+ * 2. Shorthand: { message: { type: 'string', required: true }, count: { type: 'number' } }
+ *
+ * @param {object} params
+ * @returns {object} Valid JSON Schema
+ */
+export function normalizeParameters(params) {
+  if (!params || typeof params !== 'object') {
+    return { type: 'object', properties: {}, required: [] };
+  }
+
+  // Already a JSON Schema
+  if (params.type === 'object' && params.properties) {
+    return params;
+  }
+
+  // Shorthand format — convert
+  const properties = {};
+  const required = [];
+
+  for (const [key, def] of Object.entries(params)) {
+    if (typeof def === 'string') {
+      // Simplest: { message: 'string' }
+      properties[key] = { type: def };
+    } else if (typeof def === 'object') {
+      const { required: isRequired, ...rest } = def;
+      properties[key] = rest.type ? rest : { type: 'string', ...rest };
+      if (isRequired) required.push(key);
+    }
+  }
+
+  return { type: 'object', properties, required };
+}
+
+/**
+ * Validate params against a JSON Schema (lightweight, no external deps).
+ * Only checks type, required, and enum — not full JSON Schema validation.
+ *
+ * @param {object} params - Actual params from LLM
+ * @param {object} schema - JSON Schema from normalizeParameters()
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateParams(params, schema) {
+  const errors = [];
+  if (!schema || !schema.properties) return { valid: true, errors };
+
+  // Check required
+  for (const key of (schema.required || [])) {
+    if (params[key] === undefined || params[key] === null) {
+      errors.push(`'${key}' is required`);
+    }
+  }
+
+  // Check types and enums
+  for (const [key, def] of Object.entries(schema.properties)) {
+    const value = params[key];
+    if (value === undefined || value === null) continue;
+
+    if (def.type && def.type !== 'any') {
+      const actualType = Array.isArray(value) ? 'array' : typeof value;
+      if (def.type === 'integer') {
+        if (typeof value !== 'number' || !Number.isInteger(value)) {
+          errors.push(`'${key}' must be integer, got ${actualType}`);
+        }
+      } else if (def.type !== actualType) {
+        errors.push(`'${key}' must be ${def.type}, got ${actualType}`);
+      }
+    }
+
+    if (def.enum && !def.enum.includes(value)) {
+      errors.push(`'${key}' must be one of [${def.enum.join(', ')}], got '${value}'`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ─── Context Budget ──────────────────────────────────────────────
+
+/**
+ * Estimate token count from character count.
+ * Rough heuristic: 1 token ≈ 4 chars for English, ≈ 2 chars for CJK.
+ *
+ * @param {string} text
+ * @param {number} [charRatio=4]
+ * @returns {number}
+ */
+export function estimateTokens(text, charRatio = 4) {
+  return Math.ceil(text.length / charRatio);
+}
+
+/**
+ * Truncate text to fit within a token budget.
+ *
+ * @param {string} text
+ * @param {number} maxTokens
+ * @param {number} [charRatio=4]
+ * @returns {string}
+ */
+export function truncateToTokenBudget(text, maxTokens, charRatio = 4) {
+  const maxChars = maxTokens * charRatio;
+  if (text.length <= maxChars) return text;
+  return text.slice(0, maxChars) + '\n...[truncated to fit token budget]';
+}

package/src/ai/wu-ai-triggers.js

@@ -0,0 +1,396 @@
+/**
+ * WU-AI-TRIGGERS: Event-to-AI bridge
+ *
+ * Listens to wu.eventBus events and automatically triggers LLM interactions.
+ * This is the "reactive AI" — the app becomes intelligent by responding
+ * to events with AI-generated actions.
+ *
+ * Features:
+ * - Pattern-based event matching (wu convention: 'cart:*', 'user:login')
+ * - Debounce per trigger (avoid flooding LLM)
+ * - Conditional execution (only trigger if condition returns true)
+ * - Priority batching (high triggers fire immediately, low ones batch)
+ * - Template interpolation ({{event.data.user}} in prompts)
+ * - Namespace isolation (each trigger uses its own conversation namespace)
+ */
+
+import { logger } from '../core/wu-logger.js';
+import { interpolate, sanitizeForPrompt } from './wu-ai-schema.js';
+
+// ─── Trigger Config ──────────────────────────────────────────────
+
+const DEFAULT_TRIGGER_CONFIG = {
+  enabled: true,
+  maxActiveTriggers: 20,
+  defaultDebounceMs: 1000,
+  batchIntervalMs: 2000,
+};
+
+// ─── Single Trigger ──────────────────────────────────────────────
+
+class Trigger {
+  constructor(name, config) {
+    this.name = name;
+    this.pattern = config.pattern;         // event pattern: 'cart:updated', 'user:*'
+    this.prompt = config.prompt;           // string or function(eventData) → string
+    this.condition = config.condition || null; // function(eventData) → boolean
+    this.debounceMs = config.debounce ?? DEFAULT_TRIGGER_CONFIG.defaultDebounceMs;
+    this.priority = config.priority || 'medium'; // 'high' | 'medium' | 'low'
+    this.namespace = config.namespace || `trigger:${name}`;
+    this.systemPrompt = config.systemPrompt || null;
+    this.onResult = config.onResult || null; // callback(result, eventData) → void
+    this.enabled = config.enabled !== false;
+    this.maxTokens = config.maxTokens || undefined;
+    this.temperature = config.temperature || undefined;
+
+    // Internal state
+    this._debounceTimer = null;
+    this._lastFired = 0;
+    this._fireCount = 0;
+    this._pendingEvent = null;
+  }
+
+  /**
+   * Check if this trigger matches an event name.
+   */
+  matches(eventName) {
+    if (!this.pattern) return false;
+    if (this.pattern === '*') return true;
+    if (!this.pattern.includes('*')) return eventName === this.pattern;
+
+    const regex = new RegExp('^' + this.pattern.replace(/\*/g, '[^:]*') + '$');
+    return regex.test(eventName);
+  }
+
+  /**
+   * Build the prompt for this trigger given event data.
+   */
+  buildPrompt(eventData) {
+    if (typeof this.prompt === 'function') {
+      return this.prompt(eventData);
+    }
+
+    // Template interpolation
+    return interpolate(this.prompt, {
+      event: eventData,
+      data: eventData?.data,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Check condition (if any).
+   */
+  async checkCondition(eventData) {
+    if (!this.condition) return true;
+    try {
+      const result = this.condition(eventData);
+      return result instanceof Promise ? await result : result;
+    } catch (err) {
+      logger.wuDebug(`[wu-ai] Trigger '${this.name}' condition error: ${err.message}`);
+      return false;
+    }
+  }
+}
+
+// ─── Main Triggers Manager ───────────────────────────────────────
+
+export class WuAITriggers {
+  constructor({ eventBus, conversation, permissions }) {
+    this._eventBus = eventBus;
+    this._conversation = conversation;
+    this._permissions = permissions;
+
+    this._config = { ...DEFAULT_TRIGGER_CONFIG };
+    this._triggers = new Map();          // name → Trigger
+    this._listeners = new Map();         // name → unsubscribe function
+    this._batchQueue = [];               // low-priority triggers pending batch
+    this._batchTimer = null;
+    this._stats = {
+      totalFired: 0,
+      totalSkipped: 0,
+      totalErrors: 0,
+    };
+  }
+
+  /**
+   * Configure trigger system.
+   */
+  configure(config) {
+    Object.assign(this._config, config);
+  }
+
+  /**
+   * Register a trigger.
+   *
+   * @param {string} name - Trigger name (unique identifier)
+   * @param {object} config
+   * @param {string} config.pattern - Event pattern to match (e.g., 'cart:*')
+   * @param {string|Function} config.prompt - Prompt template or function
+   * @param {Function} [config.condition] - Optional condition function
+   * @param {number} [config.debounce=1000] - Debounce in ms
+   * @param {string} [config.priority='medium'] - 'high' | 'medium' | 'low'
+   * @param {string} [config.namespace] - Conversation namespace
+   * @param {string} [config.systemPrompt] - Override system prompt
+   * @param {Function} [config.onResult] - Callback for results
+   * @param {boolean} [config.enabled=true] - Whether trigger is active
+   */
+  register(name, config) {
+    if (this._triggers.size >= this._config.maxActiveTriggers) {
+      logger.wuWarn(`[wu-ai] Max triggers (${this._config.maxActiveTriggers}) reached. Cannot register '${name}'.`);
+      return;
+    }
+
+    // Unregister existing trigger with same name
+    if (this._triggers.has(name)) {
+      this.unregister(name);
+    }
+
+    const trigger = new Trigger(name, config);
+    this._triggers.set(name, trigger);
+
+    // Subscribe to matching events
+    const handler = (eventData) => this._handleEvent(name, eventData);
+    const unsub = this._eventBus.on(trigger.pattern, handler);
+    this._listeners.set(name, unsub);
+
+    logger.wuDebug(`[wu-ai] Trigger registered: '${name}' → pattern '${trigger.pattern}' (${trigger.priority})`);
+  }
+
+  /**
+   * Unregister a trigger.
+   */
+  unregister(name) {
+    const trigger = this._triggers.get(name);
+    if (trigger) {
+      // Clear any pending debounce
+      if (trigger._debounceTimer) {
+        clearTimeout(trigger._debounceTimer);
+      }
+    }
+
+    // Remove event listener
+    const unsub = this._listeners.get(name);
+    if (typeof unsub === 'function') {
+      unsub();
+    }
+
+    this._triggers.delete(name);
+    this._listeners.delete(name);
+  }
+
+  /**
+   * Enable/disable a trigger.
+   */
+  setEnabled(name, enabled) {
+    const trigger = this._triggers.get(name);
+    if (trigger) trigger.enabled = enabled;
+  }
+
+  /**
+   * Enable/disable all triggers.
+   */
+  setAllEnabled(enabled) {
+    this._config.enabled = enabled;
+    for (const trigger of this._triggers.values()) {
+      trigger.enabled = enabled;
+    }
+  }
+
+  /**
+   * Fire a trigger manually (bypasses event matching).
+   */
+  async fire(name, eventData = {}) {
+    const trigger = this._triggers.get(name);
+    if (!trigger) {
+      logger.wuWarn(`[wu-ai] Trigger '${name}' not found`);
+      return null;
+    }
+    return this._executeTrigger(trigger, eventData);
+  }
+
+  /**
+   * Get registered trigger names.
+   */
+  getNames() {
+    return [...this._triggers.keys()];
+  }
+
+  /**
+   * Get trigger info.
+   */
+  getTrigger(name) {
+    const t = this._triggers.get(name);
+    if (!t) return null;
+    return {
+      name: t.name,
+      pattern: t.pattern,
+      priority: t.priority,
+      namespace: t.namespace,
+      enabled: t.enabled,
+      fireCount: t._fireCount,
+      lastFired: t._lastFired,
+    };
+  }
+
+  /**
+   * Destroy all triggers and clean up.
+   */
+  destroy() {
+    for (const name of [...this._triggers.keys()]) {
+      this.unregister(name);
+    }
+    if (this._batchTimer) {
+      clearTimeout(this._batchTimer);
+      this._batchTimer = null;
+    }
+    this._batchQueue = [];
+  }
+
+  // ── Private: Event Handling ──
+
+  async _handleEvent(triggerName, eventData) {
+    if (!this._config.enabled) return;
+
+    const trigger = this._triggers.get(triggerName);
+    if (!trigger || !trigger.enabled) return;
+
+    // Check condition
+    const conditionMet = await trigger.checkCondition(eventData);
+    if (!conditionMet) {
+      this._stats.totalSkipped++;
+      return;
+    }
+
+    // Priority routing
+    if (trigger.priority === 'high') {
+      // High priority: fire immediately (with debounce)
+      this._debouncedFire(trigger, eventData);
+    } else if (trigger.priority === 'low') {
+      // Low priority: batch
+      this._batchQueue.push({ trigger, eventData });
+      this._scheduleBatch();
+    } else {
+      // Medium: debounce
+      this._debouncedFire(trigger, eventData);
+    }
+  }
+
+  _debouncedFire(trigger, eventData) {
+    // Store pending event (latest wins for debounce)
+    trigger._pendingEvent = eventData;
+
+    if (trigger._debounceTimer) {
+      clearTimeout(trigger._debounceTimer);
+    }
+
+    if (trigger.debounceMs <= 0) {
+      // No debounce
+      this._executeTrigger(trigger, eventData);
+      return;
+    }
+
+    trigger._debounceTimer = setTimeout(() => {
+      trigger._debounceTimer = null;
+      const pending = trigger._pendingEvent;
+      trigger._pendingEvent = null;
+      if (pending) {
+        this._executeTrigger(trigger, pending);
+      }
+    }, trigger.debounceMs);
+  }
+
+  _scheduleBatch() {
+    if (this._batchTimer) return;
+
+    this._batchTimer = setTimeout(() => {
+      this._batchTimer = null;
+      this._processBatch();
+    }, this._config.batchIntervalMs);
+  }
+
+  async _processBatch() {
+    const batch = [...this._batchQueue];
+    this._batchQueue = [];
+
+    // Deduplicate: keep last event per trigger
+    const byTrigger = new Map();
+    for (const { trigger, eventData } of batch) {
+      byTrigger.set(trigger.name, { trigger, eventData });
+    }
+
+    for (const { trigger, eventData } of byTrigger.values()) {
+      await this._executeTrigger(trigger, eventData);
+    }
+  }
+
+  async _executeTrigger(trigger, eventData) {
+    try {
+      const prompt = trigger.buildPrompt(eventData);
+      if (!prompt) {
+        this._stats.totalSkipped++;
+        return null;
+      }
+
+      logger.wuDebug(`[wu-ai] Trigger '${trigger.name}' firing with prompt: ${prompt.slice(0, 100)}...`);
+
+      const result = await this._conversation.send(prompt, {
+        namespace: trigger.namespace,
+        systemPrompt: trigger.systemPrompt,
+        temperature: trigger.temperature,
+        maxTokens: trigger.maxTokens,
+      });
+
+      trigger._fireCount++;
+      trigger._lastFired = Date.now();
+      this._stats.totalFired++;
+
+      // Emit trigger result event
+      this._eventBus.emit('ai:trigger:result', {
+        trigger: trigger.name,
+        pattern: trigger.pattern,
+        result,
+      }, { appName: 'wu-ai' });
+
+      // Call onResult callback if provided
+      if (trigger.onResult) {
+        try {
+          await trigger.onResult(result, eventData);
+        } catch (err) {
+          logger.wuDebug(`[wu-ai] Trigger '${trigger.name}' onResult error: ${err.message}`);
+        }
+      }
+
+      return result;
+    } catch (err) {
+      this._stats.totalErrors++;
+      logger.wuWarn(`[wu-ai] Trigger '${trigger.name}' error: ${err.message}`);
+
+      this._eventBus.emit('ai:trigger:error', {
+        trigger: trigger.name,
+        error: err.message,
+      }, { appName: 'wu-ai' });
+
+      return null;
+    }
+  }
+
+  getStats() {
+    const triggers = {};
+    for (const [name, t] of this._triggers) {
+      triggers[name] = {
+        pattern: t.pattern,
+        priority: t.priority,
+        enabled: t.enabled,
+        fireCount: t._fireCount,
+        lastFired: t._lastFired,
+      };
+    }
+    return {
+      ...this._stats,
+      triggerCount: this._triggers.size,
+      batchQueueSize: this._batchQueue.length,
+      triggers,
+    };
+  }
+}