@defai.digital/iterate-domain 13.0.3

package/src/budget.ts

@@ -0,0 +1,165 @@
+/**
+ * Budget Tracker
+ *
+ * Tracks iteration budget consumption (iterations, time, tokens).
+ *
+ * Invariants:
+ * - INV-ITR-001: Budget limits must be enforced
+ */
+
+import {
+  DEFAULT_MAX_ITERATIONS,
+  DEFAULT_MAX_TIME_MS,
+  type IterateBudget,
+  type BudgetConsumed,
+  type IterateBudgetStatus,
+} from '@defai.digital/contracts';
+import type { IBudgetTracker } from './types.js';
+
+// ============================================================================
+// Budget Tracker Implementation
+// ============================================================================
+
+/**
+ * Tracks budget consumption for iterate mode
+ */
+export class BudgetTracker implements IBudgetTracker {
+  private budget: IterateBudget;
+  private consumed: BudgetConsumed;
+  private startTime = 0;
+
+  constructor(budget?: Partial<IterateBudget>) {
+    this.budget = {
+      maxIterations: budget?.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+      maxTimeMs: budget?.maxTimeMs ?? DEFAULT_MAX_TIME_MS,
+      maxTokens: budget?.maxTokens,
+    };
+
+    this.consumed = {
+      iterations: 0,
+      timeMs: 0,
+      tokens: 0,
+    };
+  }
+
+  /**
+   * Start tracking budget
+   */
+  start(): void {
+    this.startTime = Date.now();
+    this.consumed = {
+      iterations: 0,
+      timeMs: 0,
+      tokens: 0,
+    };
+  }
+
+  /**
+   * Record an iteration
+   */
+  recordIteration(tokens?: number): void {
+    this.consumed.iterations++;
+    this.consumed.timeMs = Date.now() - this.startTime;
+    if (tokens !== undefined) {
+      this.consumed.tokens = (this.consumed.tokens ?? 0) + tokens;
+    }
+  }
+
+  /**
+   * Check budget status
+   */
+  check(): IterateBudgetStatus {
+    // Update time consumed
+    this.consumed.timeMs = Date.now() - this.startTime;
+
+    const remainingIterations = this.budget.maxIterations - this.consumed.iterations;
+    const remainingTimeMs = this.budget.maxTimeMs - this.consumed.timeMs;
+    const remainingTokens = this.budget.maxTokens !== undefined
+      ? this.budget.maxTokens - (this.consumed.tokens ?? 0)
+      : undefined;
+
+    // Check what's exceeded
+    if (this.consumed.iterations >= this.budget.maxIterations) {
+      return {
+        exceeded: true,
+        reason: `Max iterations exceeded (${this.consumed.iterations}/${this.budget.maxIterations})`,
+        remaining: {
+          iterations: 0,
+          timeMs: Math.max(0, remainingTimeMs),
+          tokens: remainingTokens !== undefined ? Math.max(0, remainingTokens) : undefined,
+        },
+      };
+    }
+
+    if (this.consumed.timeMs >= this.budget.maxTimeMs) {
+      return {
+        exceeded: true,
+        reason: `Max time exceeded (${Math.round(this.consumed.timeMs / 1000)}s/${Math.round(this.budget.maxTimeMs / 1000)}s)`,
+        remaining: {
+          iterations: Math.max(0, remainingIterations),
+          timeMs: 0,
+          tokens: remainingTokens !== undefined ? Math.max(0, remainingTokens) : undefined,
+        },
+      };
+    }
+
+    if (
+      this.budget.maxTokens !== undefined &&
+      this.consumed.tokens !== undefined &&
+      this.consumed.tokens >= this.budget.maxTokens
+    ) {
+      return {
+        exceeded: true,
+        reason: `Max tokens exceeded (${this.consumed.tokens}/${this.budget.maxTokens})`,
+        remaining: {
+          iterations: Math.max(0, remainingIterations),
+          timeMs: Math.max(0, remainingTimeMs),
+          tokens: 0,
+        },
+      };
+    }
+
+    return {
+      exceeded: false,
+      remaining: {
+        iterations: remainingIterations,
+        timeMs: remainingTimeMs,
+        tokens: remainingTokens,
+      },
+    };
+  }
+
+  /**
+   * Check if budget is exceeded
+   */
+  isExceeded(): boolean {
+    return this.check().exceeded;
+  }
+
+  /**
+   * Get current consumption
+   */
+  getConsumed(): BudgetConsumed {
+    // Update time
+    this.consumed.timeMs = Date.now() - this.startTime;
+    return { ...this.consumed };
+  }
+
+  /**
+   * Get budget limits
+   */
+  getBudget(): IterateBudget {
+    return { ...this.budget };
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Creates a budget tracker with optional limits
+ */
+export function createBudgetTracker(budget?: Partial<IterateBudget>): IBudgetTracker {
+  return new BudgetTracker(budget);
+}

package/src/controller.ts

@@ -0,0 +1,275 @@
+/**
+ * Iterate Controller
+ *
+ * State machine for iterate mode - handles intent classification
+ * and determines actions (CONTINUE, PAUSE, STOP, RETRY).
+ *
+ * Invariants:
+ * - INV-ITR-003: Intent classification drives action decisions
+ */
+
+import { randomUUID } from 'node:crypto';
+import {
+  type IterateIntent,
+  type IterateAction,
+  type IterateState,
+  type IterateStartRequest,
+  type IterateHandleResponse,
+  DEFAULT_MAX_ITERATIONS,
+  DEFAULT_MAX_TIME_MS,
+} from '@defai.digital/contracts';
+import type { IIterateController } from './types.js';
+import { BudgetTracker } from './budget.js';
+import { SafetyGuard } from './safety.js';
+
+// ============================================================================
+// Auto-Response Templates
+// ============================================================================
+
+/**
+ * Auto-responses for CONTINUE action
+ */
+const AUTO_RESPONSES: Record<IterateIntent, string> = {
+  continue: 'Continue.',
+  question: '', // Should not auto-respond
+  blocked: '', // Should not auto-respond
+  complete: '', // Should not auto-respond
+  error: '', // Should not auto-respond
+};
+
+// ============================================================================
+// Iterate Controller Implementation
+// ============================================================================
+
+/**
+ * Main controller for iterate mode
+ */
+export class IterateController implements IIterateController {
+  private budgetTracker: BudgetTracker;
+  private safetyGuard: SafetyGuard;
+
+  constructor() {
+    this.budgetTracker = new BudgetTracker();
+    this.safetyGuard = new SafetyGuard();
+  }
+
+  /**
+   * Start a new iterate session
+   */
+  start(request: IterateStartRequest): IterateState {
+    const sessionId = request.sessionId ?? randomUUID();
+    const now = new Date().toISOString();
+
+    // Initialize budget tracker
+    this.budgetTracker = new BudgetTracker(request.budget);
+    this.budgetTracker.start();
+
+    // Initialize safety guard
+    if (request.safety) {
+      this.safetyGuard = new SafetyGuard(request.safety);
+    }
+
+    return {
+      sessionId,
+      taskId: randomUUID(),
+      budget: {
+        maxIterations: request.budget?.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+        maxTimeMs: request.budget?.maxTimeMs ?? DEFAULT_MAX_TIME_MS,
+        maxTokens: request.budget?.maxTokens,
+      },
+      consumed: {
+        iterations: 0,
+        timeMs: 0,
+        tokens: 0,
+      },
+      iteration: 0,
+      startedAt: now,
+      lastActivityAt: now,
+      status: 'running',
+      consecutiveErrors: 0,
+      history: [],
+    };
+  }
+
+  /**
+   * Handle a response from the LLM
+   */
+  handleResponse(
+    state: IterateState,
+    intent: IterateIntent,
+    content?: string
+  ): IterateHandleResponse {
+    const now = new Date().toISOString();
+
+    // Record iteration in budget tracker
+    this.budgetTracker.recordIteration();
+
+    // Check budget first
+    const budgetStatus = this.budgetTracker.check();
+    if (budgetStatus.exceeded) {
+      return this.createResponse(state, intent, {
+        type: 'STOP',
+        reason: budgetStatus.reason ?? 'Budget exceeded',
+        requiresInput: false,
+      }, 'budget_exceeded', now, content);
+    }
+
+    // Check safety if content provided
+    if (content) {
+      const safetyResult = this.safetyGuard.checkContent(content);
+      if (!safetyResult.safe) {
+        return this.createResponse(state, intent, {
+          type: 'PAUSE',
+          reason: safetyResult.reason ?? 'Safety check failed',
+          requiresInput: true,
+          suggestedInput: 'Review the dangerous pattern and confirm to proceed.',
+        }, 'paused', now, content);
+      }
+    }
+
+    // Check consecutive errors
+    if (intent === 'error') {
+      const newErrorCount = state.consecutiveErrors + 1;
+      const errorResult = this.safetyGuard.checkErrors(newErrorCount);
+      if (!errorResult.safe) {
+        return this.createResponse(state, intent, {
+          type: 'PAUSE',
+          reason: errorResult.reason ?? 'Too many consecutive errors',
+          requiresInput: true,
+          suggestedInput: 'Review the errors and decide how to proceed.',
+        }, 'paused', now, content, newErrorCount);
+      }
+    }
+
+    // Map intent to action
+    const action = this.mapIntentToAction(intent);
+
+    // Determine new status
+    let newStatus: IterateState['status'] = state.status;
+    if (action.type === 'STOP') {
+      newStatus = intent === 'complete' ? 'completed' : 'failed';
+    } else if (action.type === 'PAUSE') {
+      newStatus = 'paused';
+    } else {
+      newStatus = 'running';
+    }
+
+    // Reset error count on non-error intent
+    const consecutiveErrors = intent === 'error' ? state.consecutiveErrors + 1 : 0;
+
+    return this.createResponse(state, intent, action, newStatus, now, content, consecutiveErrors);
+  }
+
+  /**
+   * Get auto-response for CONTINUE action
+   */
+  getAutoResponse(intent: IterateIntent): string {
+    return AUTO_RESPONSES[intent] ?? 'Continue.';
+  }
+
+  /**
+   * Map intent to action
+   */
+  private mapIntentToAction(intent: IterateIntent): IterateAction {
+    switch (intent) {
+      case 'continue':
+        return {
+          type: 'CONTINUE',
+          reason: 'Task in progress',
+          requiresInput: false,
+        };
+
+      case 'question':
+        return {
+          type: 'PAUSE',
+          reason: 'User decision needed',
+          requiresInput: true,
+          suggestedInput: 'Please provide your decision.',
+        };
+
+      case 'blocked':
+        return {
+          type: 'PAUSE',
+          reason: 'External input needed',
+          requiresInput: true,
+          suggestedInput: 'Please provide the required input.',
+        };
+
+      case 'complete':
+        return {
+          type: 'STOP',
+          reason: 'Task completed successfully',
+          requiresInput: false,
+        };
+
+      case 'error':
+        return {
+          type: 'PAUSE',
+          reason: 'Error occurred',
+          requiresInput: true,
+          suggestedInput: 'Please review the error and decide how to proceed.',
+        };
+
+      default:
+        // Unknown intent - pause for safety
+        return {
+          type: 'PAUSE',
+          reason: 'Unknown intent - pausing for safety',
+          requiresInput: true,
+        };
+    }
+  }
+
+  /**
+   * Create response with updated state
+   */
+  private createResponse(
+    state: IterateState,
+    intent: IterateIntent,
+    action: IterateAction,
+    newStatus: IterateState['status'],
+    now: string,
+    content?: string,
+    consecutiveErrors?: number
+  ): IterateHandleResponse {
+    const consumed = this.budgetTracker.getConsumed();
+
+    const newState: IterateState = {
+      ...state,
+      iteration: state.iteration + 1,
+      consumed,
+      lastActivityAt: now,
+      status: newStatus,
+      lastIntent: intent,
+      lastAction: action,
+      consecutiveErrors: consecutiveErrors ?? (intent === 'error' ? state.consecutiveErrors + 1 : 0),
+      history: [
+        ...(state.history ?? []),
+        {
+          iteration: state.iteration + 1,
+          intent,
+          action: action.type,
+          timestamp: now,
+        },
+      ],
+    };
+
+    return {
+      action,
+      newState,
+      content,
+      autoResponse: action.type === 'CONTINUE' ? this.getAutoResponse(intent) : undefined,
+    };
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Creates an iterate controller
+ */
+export function createIterateController(): IIterateController {
+  return new IterateController();
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @defai.digital/iterate-domain
+ *
+ * Iterate mode for AutomatosX - autonomous execution with
+ * structured intent classification and safety controls.
+ *
+ * Key concepts:
+ * - Intent: What the LLM is communicating (continue, question, blocked, complete, error)
+ * - Action: What to do next (CONTINUE, PAUSE, STOP, RETRY)
+ * - Budget: Resource limits (iterations, time, tokens)
+ * - Safety: Pattern detection and error limits
+ */
+
+// Types
+export type {
+  IterateIntent,
+  IterateAction,
+  IterateBudget,
+  BudgetConsumed,
+  IterateBudgetStatus,
+  IterateState,
+  IterateSafetyConfig,
+  SafetyCheckResult,
+  IterateStartRequest,
+  IterateHandleResponse,
+  IBudgetTracker,
+  ISafetyGuard,
+  IIterateController,
+} from './types.js';
+
+// Budget Tracker
+export { BudgetTracker, createBudgetTracker } from './budget.js';
+
+// Safety Guard
+export { SafetyGuard, createSafetyGuard, isContentSafe } from './safety.js';
+
+// Iterate Controller
+export { IterateController, createIterateController } from './controller.js';
+
+// Re-export contract constants
+export {
+  DEFAULT_MAX_ITERATIONS,
+  DEFAULT_MAX_TIME_MS,
+  DEFAULT_MAX_CONSECUTIVE_ERRORS,
+  IterateIntentSchema,
+  IterateActionTypeSchema,
+  IterateBudgetSchema,
+  IterateStateSchema,
+  validateIterateIntent,
+  safeValidateIterateIntent,
+  validateIterateBudget,
+  validateIterateState,
+  IterateErrorCode,
+} from '@defai.digital/contracts';

package/src/safety.ts

@@ -0,0 +1,198 @@
+/**
+ * Safety Guard
+ *
+ * Checks for dangerous patterns and enforces safety limits.
+ *
+ * Invariants:
+ * - INV-ITR-002: Safety guards must pause on dangerous patterns
+ */
+
+import {
+  DEFAULT_MAX_CONSECUTIVE_ERRORS,
+  type IterateSafetyConfig,
+  type SafetyCheckResult,
+} from '@defai.digital/contracts';
+import type { ISafetyGuard } from './types.js';
+
+// ============================================================================
+// Default Dangerous Patterns
+// ============================================================================
+
+/**
+ * Default patterns that trigger safety pause
+ */
+const DEFAULT_DANGEROUS_PATTERNS = [
+  // File system destruction
+  'rm\\s+-rf\\s+[/~]',
+  'rm\\s+-rf\\s+\\*',
+  'rm\\s+-rf\\s+\\.',
+  'rmdir\\s+/\\s',
+  // Database destruction
+  'DROP\\s+TABLE',
+  'DROP\\s+DATABASE',
+  'TRUNCATE\\s+TABLE',
+  'DELETE\\s+FROM\\s+\\w+\\s*;',
+  // Disk format
+  'mkfs\\.',
+  'format\\s+[cC]:',
+  'dd\\s+if=',
+  // Fork bomb
+  ':\\(\\)\\{\\s*:|:&\\s*\\};:',
+  // Git force
+  'git\\s+push\\s+.*--force',
+  'git\\s+reset\\s+--hard\\s+origin',
+  // Shutdown/reboot
+  'shutdown',
+  'reboot',
+  'init\\s+0',
+  // Env/secrets exposure
+  'echo\\s+\\$[A-Z_]*KEY',
+  'echo\\s+\\$[A-Z_]*SECRET',
+  'echo\\s+\\$[A-Z_]*PASSWORD',
+];
+
+// ============================================================================
+// Safety Guard Implementation
+// ============================================================================
+
+/**
+ * Checks content for dangerous patterns
+ */
+export class SafetyGuard implements ISafetyGuard {
+  private config: IterateSafetyConfig;
+  private compiledPatterns: RegExp[];
+
+  constructor(config?: Partial<IterateSafetyConfig>) {
+    this.config = {
+      maxConsecutiveErrors: config?.maxConsecutiveErrors ?? DEFAULT_MAX_CONSECUTIVE_ERRORS,
+      enableDangerousPatternDetection: config?.enableDangerousPatternDetection ?? true,
+      dangerousPatterns: config?.dangerousPatterns ?? DEFAULT_DANGEROUS_PATTERNS,
+      customDangerousPatterns: config?.customDangerousPatterns,
+    };
+
+    // Compile patterns for performance
+    this.compiledPatterns = this.compilePatterns();
+  }
+
+  /**
+   * Compile all patterns into RegExp objects
+   */
+  private compilePatterns(): RegExp[] {
+    const patterns = [
+      ...this.config.dangerousPatterns,
+      ...(this.config.customDangerousPatterns ?? []),
+    ];
+
+    return patterns.map((pattern) => {
+      try {
+        return new RegExp(pattern, 'i');
+      } catch {
+        // Invalid pattern - skip it
+        console.warn(`Invalid dangerous pattern: ${pattern}`);
+        return null;
+      }
+    }).filter((p): p is RegExp => p !== null);
+  }
+
+  /**
+   * Check content for dangerous patterns
+   */
+  checkContent(content: string): SafetyCheckResult {
+    if (!this.config.enableDangerousPatternDetection) {
+      return { safe: true };
+    }
+
+    for (const pattern of this.compiledPatterns) {
+      if (pattern.test(content)) {
+        // Determine severity based on pattern
+        const severity = this.getSeverity(pattern.source);
+
+        return {
+          safe: false,
+          reason: `Dangerous pattern detected: ${pattern.source}`,
+          matchedPattern: pattern.source,
+          severity,
+        };
+      }
+    }
+
+    return { safe: true };
+  }
+
+  /**
+   * Check if too many consecutive errors
+   */
+  checkErrors(consecutiveErrors: number): SafetyCheckResult {
+    if (consecutiveErrors >= this.config.maxConsecutiveErrors) {
+      return {
+        safe: false,
+        reason: `Too many consecutive errors (${consecutiveErrors}/${this.config.maxConsecutiveErrors})`,
+        severity: 'warning',
+      };
+    }
+
+    return { safe: true };
+  }
+
+  /**
+   * Get safety configuration
+   */
+  getConfig(): IterateSafetyConfig {
+    return { ...this.config };
+  }
+
+  /**
+   * Determine severity based on pattern
+   */
+  private getSeverity(pattern: string): 'warning' | 'danger' | 'critical' {
+    // Critical patterns - immediate system damage
+    const criticalPatterns = [
+      'rm\\s+-rf\\s+[/~]',
+      'mkfs\\.',
+      'dd\\s+if=',
+      'DROP\\s+DATABASE',
+      ':\\(\\)\\{',
+    ];
+
+    for (const critical of criticalPatterns) {
+      if (pattern.includes(critical) || pattern === critical) {
+        return 'critical';
+      }
+    }
+
+    // Danger patterns - significant data loss
+    const dangerPatterns = [
+      'DROP\\s+TABLE',
+      'TRUNCATE',
+      'DELETE\\s+FROM',
+      'git\\s+push.*--force',
+    ];
+
+    for (const danger of dangerPatterns) {
+      if (pattern.includes(danger) || pattern === danger) {
+        return 'danger';
+      }
+    }
+
+    return 'warning';
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Creates a safety guard with optional configuration
+ */
+export function createSafetyGuard(config?: Partial<IterateSafetyConfig>): ISafetyGuard {
+  return new SafetyGuard(config);
+}
+
+/**
+ * Quick check if content is safe
+ */
+export function isContentSafe(content: string): boolean {
+  const guard = new SafetyGuard();
+  return guard.checkContent(content).safe;
+}