@holoscript/framework 6.0.3

package/src/ai/AIOutputValidator.ts

@@ -0,0 +1,203 @@
+/**
+ * AI Output Validator
+ *
+ * Validates AI-generated HoloScript code before execution.
+ * Catches structural errors, dangerous patterns, and excessive complexity.
+ *
+ * @module ai
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface ValidationIssue {
+  severity: 'error' | 'warning' | 'info';
+  message: string;
+  line?: number;
+  rule: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  issues: ValidationIssue[];
+  confidence: number; // 0-1: higher = more confident code is safe/correct
+  stats: {
+    lineCount: number;
+    traitCount: number;
+    dangerousPatternCount: number;
+    maxNesting: number;
+  };
+}
+
+export interface ValidatorConfig {
+  maxLines: number;
+  maxNesting: number;
+  maxTraits: number;
+  allowedTraits?: string[];
+  blockDangerousPatterns: boolean;
+}
+
+// =============================================================================
+// DANGEROUS PATTERNS
+// =============================================================================
+
+const DANGEROUS_PATTERNS: Array<{ pattern: RegExp; rule: string; message: string }> = [
+  { pattern: /\beval\s*\(/, rule: 'no-eval', message: 'eval() is forbidden in generated code' },
+  {
+    pattern: /\bFunction\s*\(/,
+    rule: 'no-function-constructor',
+    message: 'Function constructor is forbidden',
+  },
+  {
+    pattern: /\brequire\s*\(/,
+    rule: 'no-require',
+    message: 'require() is forbidden — use imports',
+  },
+  { pattern: /\b__proto__\b/, rule: 'no-proto', message: '__proto__ access is forbidden' },
+  {
+    pattern: /\bconstructor\s*\[/,
+    rule: 'no-constructor-bracket',
+    message: 'Constructor bracket access is forbidden',
+  },
+  {
+    pattern: /\bprocess\s*\./,
+    rule: 'no-process',
+    message: 'process.* is forbidden in sandboxed code',
+  },
+  { pattern: /\bchild_process\b/, rule: 'no-child-process', message: 'child_process is forbidden' },
+  { pattern: /\bfs\s*\./, rule: 'no-fs', message: 'Direct fs access is forbidden' },
+  { pattern: /import\s*\(/, rule: 'no-dynamic-import', message: 'Dynamic import() is forbidden' },
+  { pattern: /\bglobalThis\b/, rule: 'no-globalThis', message: 'globalThis access is forbidden' },
+];
+
+// =============================================================================
+// VALIDATOR
+// =============================================================================
+
+const DEFAULT_CONFIG: ValidatorConfig = {
+  maxLines: 2000,
+  maxNesting: 15,
+  maxTraits: 100,
+  blockDangerousPatterns: true,
+};
+
+/**
+ * Validate AI-generated code for safety and correctness.
+ */
+export function validateAIOutput(
+  code: string,
+  config: Partial<ValidatorConfig> = {}
+): ValidationResult {
+  const cfg: ValidatorConfig = { ...DEFAULT_CONFIG, ...config };
+  const issues: ValidationIssue[] = [];
+  const lines = code.split('\n');
+  const lineCount = lines.length;
+
+  // --- Line count check ---
+  if (lineCount > cfg.maxLines) {
+    issues.push({
+      severity: 'error',
+      message: `Code exceeds maximum line count (${lineCount} > ${cfg.maxLines})`,
+      rule: 'max-lines',
+    });
+  }
+
+  // --- Dangerous pattern scan ---
+  let dangerousPatternCount = 0;
+  if (cfg.blockDangerousPatterns) {
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      for (const dp of DANGEROUS_PATTERNS) {
+        if (dp.pattern.test(line)) {
+          dangerousPatternCount++;
+          issues.push({
+            severity: 'error',
+            message: dp.message,
+            line: i + 1,
+            rule: dp.rule,
+          });
+        }
+      }
+    }
+  }
+
+  // --- Nesting depth check ---
+  let maxNesting = 0;
+  let currentNesting = 0;
+  for (const line of lines) {
+    for (const ch of line) {
+      if (ch === '{') {
+        currentNesting++;
+        maxNesting = Math.max(maxNesting, currentNesting);
+      } else if (ch === '}') {
+        currentNesting = Math.max(0, currentNesting - 1);
+      }
+    }
+  }
+
+  if (maxNesting > cfg.maxNesting) {
+    issues.push({
+      severity: 'warning',
+      message: `Excessive nesting depth (${maxNesting} > ${cfg.maxNesting})`,
+      rule: 'max-nesting',
+    });
+  }
+
+  // --- Unbalanced braces ---
+  if (currentNesting !== 0) {
+    issues.push({
+      severity: 'error',
+      message: `Unbalanced braces: ${currentNesting} unclosed '{'`,
+      rule: 'balanced-braces',
+    });
+  }
+
+  // --- Trait count extraction ---
+  const traitMatches = code.match(/@\w+/g) || [];
+  const traitCount = traitMatches.length;
+
+  if (traitCount > cfg.maxTraits) {
+    issues.push({
+      severity: 'warning',
+      message: `Too many traits (${traitCount} > ${cfg.maxTraits})`,
+      rule: 'max-traits',
+    });
+  }
+
+  // --- Allowed traits check ---
+  if (cfg.allowedTraits && cfg.allowedTraits.length > 0) {
+    const allowed = new Set(cfg.allowedTraits.map((t) => (t.startsWith('@') ? t : `@${t}`)));
+    for (const trait of traitMatches) {
+      if (!allowed.has(trait)) {
+        issues.push({
+          severity: 'warning',
+          message: `Unknown trait "${trait}" — not in allowed list`,
+          rule: 'allowed-traits',
+        });
+      }
+    }
+  }
+
+  // --- Confidence scoring ---
+  const errorCount = issues.filter((i) => i.severity === 'error').length;
+  const warningCount = issues.filter((i) => i.severity === 'warning').length;
+  const confidence = Math.max(
+    0,
+    1.0 - errorCount * 0.3 - warningCount * 0.1 - dangerousPatternCount * 0.2
+  );
+
+  return {
+    valid: errorCount === 0,
+    issues,
+    confidence: Math.round(confidence * 100) / 100,
+    stats: { lineCount, traitCount, dangerousPatternCount, maxNesting },
+  };
+}
+
+/**
+ * Quick check — returns true if code passes all error-level checks.
+ */
+export function isAISafe(code: string, config?: Partial<ValidatorConfig>): boolean {
+  return validateAIOutput(code, config).valid;
+}

package/src/ai/BTNodes.ts

@@ -0,0 +1,239 @@
+/**
+ * BTNodes.ts
+ *
+ * Behavior tree node types: composite (sequence, selector, parallel),
+ * decorator (inverter, repeater, guard), leaf (action, condition, wait).
+ *
+ * @module ai
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type BTStatus = 'success' | 'failure' | 'running' | 'ready';
+
+export interface BTContext {
+  blackboard: { get: (key: string) => unknown; set: (key: string, value: unknown) => void };
+  deltaTime: number;
+  entity: string;
+}
+
+// =============================================================================
+// BASE NODE
+// =============================================================================
+
+export abstract class BTNode {
+  name: string;
+  status: BTStatus = 'ready';
+  children: BTNode[] = [];
+
+  constructor(name: string) {
+    this.name = name;
+  }
+  abstract tick(ctx: BTContext): BTStatus;
+  reset(): void {
+    this.status = 'ready';
+    for (const c of this.children) c.reset();
+  }
+}
+
+// =============================================================================
+// COMPOSITE NODES
+// =============================================================================
+
+export class SequenceNode extends BTNode {
+  private currentIndex = 0;
+
+  constructor(name: string, children: BTNode[]) {
+    super(name);
+    this.children = children;
+  }
+
+  tick(ctx: BTContext): BTStatus {
+    while (this.currentIndex < this.children.length) {
+      const status = this.children[this.currentIndex].tick(ctx);
+      if (status === 'running') return (this.status = 'running');
+      if (status === 'failure') {
+        this.currentIndex = 0;
+        return (this.status = 'failure');
+      }
+      this.currentIndex++;
+    }
+    this.currentIndex = 0;
+    return (this.status = 'success');
+  }
+
+  reset(): void {
+    this.currentIndex = 0;
+    super.reset();
+  }
+}
+
+export class SelectorNode extends BTNode {
+  private currentIndex = 0;
+
+  constructor(name: string, children: BTNode[]) {
+    super(name);
+    this.children = children;
+  }
+
+  tick(ctx: BTContext): BTStatus {
+    while (this.currentIndex < this.children.length) {
+      const status = this.children[this.currentIndex].tick(ctx);
+      if (status === 'running') return (this.status = 'running');
+      if (status === 'success') {
+        this.currentIndex = 0;
+        return (this.status = 'success');
+      }
+      this.currentIndex++;
+    }
+    this.currentIndex = 0;
+    return (this.status = 'failure');
+  }
+
+  reset(): void {
+    this.currentIndex = 0;
+    super.reset();
+  }
+}
+
+export class ParallelNode extends BTNode {
+  private requiredSuccesses: number;
+
+  constructor(name: string, children: BTNode[], requiredSuccesses?: number) {
+    super(name);
+    this.children = children;
+    this.requiredSuccesses = requiredSuccesses ?? children.length;
+  }
+
+  tick(ctx: BTContext): BTStatus {
+    let successes = 0;
+    let failures = 0;
+
+    for (const child of this.children) {
+      const status = child.tick(ctx);
+      if (status === 'success') successes++;
+      else if (status === 'failure') failures++;
+    }
+
+    if (successes >= this.requiredSuccesses) return (this.status = 'success');
+    if (failures > this.children.length - this.requiredSuccesses) return (this.status = 'failure');
+    return (this.status = 'running');
+  }
+}
+
+// =============================================================================
+// DECORATOR NODES
+// =============================================================================
+
+export class InverterNode extends BTNode {
+  constructor(name: string, child: BTNode) {
+    super(name);
+    this.children = [child];
+  }
+
+  tick(ctx: BTContext): BTStatus {
+    const status = this.children[0].tick(ctx);
+    if (status === 'success') return (this.status = 'failure');
+    if (status === 'failure') return (this.status = 'success');
+    return (this.status = 'running');
+  }
+}
+
+export class RepeaterNode extends BTNode {
+  private maxRepeats: number;
+  private count = 0;
+
+  constructor(name: string, child: BTNode, repeats = Infinity) {
+    super(name);
+    this.children = [child];
+    this.maxRepeats = repeats;
+  }
+
+  tick(ctx: BTContext): BTStatus {
+    if (this.count >= this.maxRepeats) return (this.status = 'success');
+    const status = this.children[0].tick(ctx);
+    if (status === 'success' || status === 'failure') {
+      this.count++;
+      this.children[0].reset();
+      if (this.count >= this.maxRepeats) return (this.status = 'success');
+      return (this.status = 'running');
+    }
+    return (this.status = 'running');
+  }
+
+  reset(): void {
+    this.count = 0;
+    super.reset();
+  }
+}
+
+export class GuardNode extends BTNode {
+  private condition: (ctx: BTContext) => boolean;
+
+  constructor(name: string, condition: (ctx: BTContext) => boolean, child: BTNode) {
+    super(name);
+    this.condition = condition;
+    this.children = [child];
+  }
+
+  tick(ctx: BTContext): BTStatus {
+    if (!this.condition(ctx)) return (this.status = 'failure');
+    return (this.status = this.children[0].tick(ctx));
+  }
+}
+
+// =============================================================================
+// LEAF NODES
+// =============================================================================
+
+export class ActionNode extends BTNode {
+  private action: (ctx: BTContext) => BTStatus;
+
+  constructor(name: string, action: (ctx: BTContext) => BTStatus) {
+    super(name);
+    this.action = action;
+  }
+
+  tick(ctx: BTContext): BTStatus {
+    return (this.status = this.action(ctx));
+  }
+}
+
+export class ConditionNode extends BTNode {
+  private condition: (ctx: BTContext) => boolean;
+
+  constructor(name: string, condition: (ctx: BTContext) => boolean) {
+    super(name);
+    this.condition = condition;
+  }
+
+  tick(ctx: BTContext): BTStatus {
+    return (this.status = this.condition(ctx) ? 'success' : 'failure');
+  }
+}
+
+export class WaitNode extends BTNode {
+  private duration: number;
+  private elapsed = 0;
+
+  constructor(name: string, seconds: number) {
+    super(name);
+    this.duration = seconds;
+  }
+
+  tick(ctx: BTContext): BTStatus {
+    this.elapsed += ctx.deltaTime;
+    if (this.elapsed >= this.duration) {
+      this.elapsed = 0;
+      return (this.status = 'success');
+    }
+    return (this.status = 'running');
+  }
+
+  reset(): void {
+    this.elapsed = 0;
+    super.reset();
+  }
+}

package/src/ai/BehaviorSelector.ts

@@ -0,0 +1,135 @@
+/**
+ * BehaviorSelector.ts
+ *
+ * Behavior selection: weighted random, priority-based, and
+ * conditional behavior picking with fallbacks and lockout timers.
+ *
+ * @module ai
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface Behavior {
+  id: string;
+  name: string;
+  weight: number;
+  priority: number;
+  condition?: () => boolean;
+  action: () => void;
+  lockoutMs: number; // Minimum time between executions
+  lastExecuted: number;
+}
+
+export type SelectionMode = 'priority' | 'weighted' | 'sequential';
+
+// =============================================================================
+// BEHAVIOR SELECTOR
+// =============================================================================
+
+export class BehaviorSelector {
+  private behaviors: Behavior[] = [];
+  private mode: SelectionMode;
+  private currentIndex = 0;
+  private currentTime = 0;
+  private fallback: Behavior | null = null;
+  private history: Array<{ behaviorId: string; timestamp: number }> = [];
+  private maxHistory = 50;
+
+  constructor(mode: SelectionMode = 'priority') {
+    this.mode = mode;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Behavior Management
+  // ---------------------------------------------------------------------------
+
+  addBehavior(behavior: Behavior): void {
+    this.behaviors.push(behavior);
+  }
+  removeBehavior(id: string): void {
+    this.behaviors = this.behaviors.filter((b) => b.id !== id);
+  }
+  setFallback(behavior: Behavior): void {
+    this.fallback = behavior;
+  }
+  setMode(mode: SelectionMode): void {
+    this.mode = mode;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Selection
+  // ---------------------------------------------------------------------------
+
+  select(): Behavior | null {
+    const available = this.getAvailable();
+    if (available.length === 0) return this.fallback;
+
+    switch (this.mode) {
+      case 'priority':
+        return this.selectByPriority(available);
+      case 'weighted':
+        return this.selectByWeight(available);
+      case 'sequential':
+        return this.selectSequential(available);
+    }
+  }
+
+  private getAvailable(): Behavior[] {
+    return this.behaviors.filter((b) => {
+      if (this.currentTime - b.lastExecuted < b.lockoutMs) return false;
+      if (b.condition && !b.condition()) return false;
+      return true;
+    });
+  }
+
+  private selectByPriority(behaviors: Behavior[]): Behavior {
+    return behaviors.reduce((best, b) => (b.priority > best.priority ? b : best));
+  }
+
+  private selectByWeight(behaviors: Behavior[]): Behavior {
+    const totalWeight = behaviors.reduce((sum, b) => sum + b.weight, 0);
+    let roll = Math.random() * totalWeight;
+    for (const b of behaviors) {
+      roll -= b.weight;
+      if (roll <= 0) return b;
+    }
+    return behaviors[behaviors.length - 1];
+  }
+
+  private selectSequential(behaviors: Behavior[]): Behavior {
+    this.currentIndex = this.currentIndex % behaviors.length;
+    return behaviors[this.currentIndex++];
+  }
+
+  // ---------------------------------------------------------------------------
+  // Execution
+  // ---------------------------------------------------------------------------
+
+  execute(): string | null {
+    const behavior = this.select();
+    if (!behavior) return null;
+
+    behavior.action();
+    behavior.lastExecuted = this.currentTime;
+    this.history.push({ behaviorId: behavior.id, timestamp: this.currentTime });
+    if (this.history.length > this.maxHistory) this.history.shift();
+
+    return behavior.id;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  setTime(time: number): void {
+    this.currentTime = time;
+  }
+  getBehaviorCount(): number {
+    return this.behaviors.length;
+  }
+  getHistory() {
+    return [...this.history];
+  }
+}