@defai.digital/agent-domain 13.0.3

package/src/stub-checkpoint.ts

@@ -0,0 +1,187 @@
+/**
+ * Stub Checkpoint Implementation
+ *
+ * Provides minimal checkpoint storage and manager for when no real
+ * implementation is provided via AgentDomainConfig factories.
+ *
+ * Uses in-memory storage (data lost between invocations).
+ * For production use, provide real implementations via config.
+ */
+
+import type { CheckpointConfig } from '@defai.digital/contracts';
+import type {
+  CheckpointStoragePort,
+  CheckpointManagerPort,
+  Checkpoint,
+  CheckpointStorageFactory,
+  CheckpointManagerFactory,
+} from './types.js';
+
+let _warnedOnce = false;
+
+/**
+ * In-memory checkpoint storage (stub)
+ */
+function createInMemoryCheckpointStorage(): CheckpointStoragePort {
+  const checkpoints = new Map<string, Checkpoint>();
+
+  return {
+    async save(checkpoint: Checkpoint): Promise<void> {
+      checkpoints.set(checkpoint.checkpointId, { ...checkpoint });
+    },
+
+    async load(checkpointId: string): Promise<Checkpoint | null> {
+      return checkpoints.get(checkpointId) ?? null;
+    },
+
+    async loadLatest(agentId: string, sessionId?: string): Promise<Checkpoint | null> {
+      let latest: Checkpoint | null = null;
+      let latestTime = 0;
+
+      for (const cp of checkpoints.values()) {
+        if (cp.agentId !== agentId) continue;
+        if (sessionId !== undefined && cp.sessionId !== sessionId) continue;
+
+        const time = new Date(cp.createdAt).getTime();
+        if (time > latestTime) {
+          latestTime = time;
+          latest = cp;
+        }
+      }
+
+      return latest;
+    },
+
+    async list(agentId: string, sessionId?: string): Promise<Checkpoint[]> {
+      const results: Checkpoint[] = [];
+
+      for (const cp of checkpoints.values()) {
+        if (cp.agentId !== agentId) continue;
+        if (sessionId !== undefined && cp.sessionId !== sessionId) continue;
+        results.push({ ...cp });
+      }
+
+      return results.sort(
+        (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
+      );
+    },
+
+    async delete(checkpointId: string): Promise<boolean> {
+      return checkpoints.delete(checkpointId);
+    },
+
+    async deleteExpired(): Promise<number> {
+      const now = Date.now();
+      let count = 0;
+
+      for (const [id, cp] of checkpoints.entries()) {
+        if (cp.expiresAt && new Date(cp.expiresAt).getTime() < now) {
+          checkpoints.delete(id);
+          count++;
+        }
+      }
+
+      return count;
+    },
+  };
+}
+
+/**
+ * Creates a stub checkpoint manager
+ */
+function createStubCheckpointManager(
+  agentId: string,
+  sessionId: string | undefined,
+  storage: CheckpointStoragePort,
+  config: CheckpointConfig
+): CheckpointManagerPort {
+  return {
+    getConfig(): CheckpointConfig {
+      return { ...config };
+    },
+
+    shouldCheckpoint(stepIndex: number): boolean {
+      if (!config.enabled) return false;
+      return (stepIndex + 1) % config.intervalSteps === 0;
+    },
+
+    async createCheckpoint(
+      stepIndex: number,
+      stepId: string,
+      previousOutputs: Record<string, unknown>,
+      metadata?: Record<string, unknown>
+    ): Promise<Checkpoint> {
+      const now = new Date();
+      const checkpoint: Checkpoint = {
+        checkpointId: crypto.randomUUID(),
+        agentId,
+        sessionId,
+        stepIndex,
+        stepId,
+        previousOutputs: { ...previousOutputs },
+        metadata,
+        createdAt: now.toISOString(),
+        expiresAt: config.retentionHours
+          ? new Date(now.getTime() + config.retentionHours * 3600 * 1000).toISOString()
+          : undefined,
+      };
+
+      await storage.save(checkpoint);
+      return checkpoint;
+    },
+
+    async getLatestCheckpoint(): Promise<Checkpoint | null> {
+      return storage.loadLatest(agentId, sessionId);
+    },
+
+    async getResumeContext(checkpointId: string): Promise<{
+      startFromStep: number;
+      previousOutputs: Record<string, unknown>;
+    } | null> {
+      const checkpoint = await storage.load(checkpointId);
+      if (!checkpoint) return null;
+
+      return {
+        startFromStep: checkpoint.stepIndex + 1,
+        previousOutputs: { ...checkpoint.previousOutputs },
+      };
+    },
+
+    async cleanup(): Promise<number> {
+      return storage.deleteExpired();
+    },
+  };
+}
+
+/**
+ * Stub checkpoint storage factory
+ */
+export const stubCheckpointStorageFactory: CheckpointStorageFactory = () => {
+  if (!_warnedOnce) {
+    console.warn(
+      '[agent-domain] Using stub checkpoint storage. ' +
+      'For persistent checkpoints, provide checkpointStorageFactory in config.'
+    );
+    _warnedOnce = true;
+  }
+  return createInMemoryCheckpointStorage();
+};
+
+/**
+ * Stub checkpoint manager factory
+ */
+export const stubCheckpointManagerFactory: CheckpointManagerFactory = (
+  agentId: string,
+  sessionId: string | undefined,
+  storage: CheckpointStoragePort,
+  config: CheckpointConfig
+) => {
+  return createStubCheckpointManager(agentId, sessionId, storage, config);
+};
+
+/**
+ * Reset the warning flag (for testing)
+ */
+export function resetCheckpointStubWarning(): void {
+  _warnedOnce = false;
+}

package/src/stub-delegation-tracker.ts

@@ -0,0 +1,161 @@
+/**
+ * Stub Delegation Tracker Implementation
+ *
+ * Provides a minimal delegation tracker for when no real implementation
+ * is provided via AgentDomainConfig.delegationTrackerFactory.
+ *
+ * This stub:
+ * - Logs a warning on first use
+ * - Allows delegations within depth limits
+ * - Tracks basic context and history
+ *
+ * For production use, provide a real implementation via config.
+ */
+
+import type {
+  DelegationContext,
+  DelegationCheckResult,
+  DelegationResult,
+  DelegationRequest as ContractDelegationRequest,
+} from '@defai.digital/contracts';
+import {
+  createRootDelegationContext,
+  DelegationErrorCodes,
+} from '@defai.digital/contracts';
+import type { DelegationTrackerPort, DelegationTrackerFactory } from './types.js';
+
+let _warnedOnce = false;
+
+/**
+ * Creates a stub delegation tracker
+ *
+ * This is used when no delegationTrackerFactory is provided in config.
+ * It provides basic functionality but logs a warning.
+ */
+function createStubDelegationTracker(
+  agentId: string,
+  parentContext: DelegationContext | undefined,
+  maxDepth: number
+): DelegationTrackerPort {
+  // Warn once about stub usage
+  if (!_warnedOnce) {
+    console.warn(
+      '[agent-domain] Using stub delegation tracker. ' +
+      'For full delegation support, provide delegationTrackerFactory in AgentDomainConfig.'
+    );
+    _warnedOnce = true;
+  }
+
+  // Initialize context
+  let context: DelegationContext;
+
+  if (parentContext) {
+    // Create child context
+    context = {
+      ...parentContext,
+      currentDepth: parentContext.currentDepth + 1,
+      delegationChain: [...parentContext.delegationChain, agentId],
+    };
+  } else {
+    // Create root context
+    context = createRootDelegationContext(
+      agentId,
+      crypto.randomUUID(),
+      maxDepth
+    );
+  }
+
+  const delegationHistory: DelegationResult[] = [];
+
+  return {
+    getContext(): DelegationContext {
+      return { ...context };
+    },
+
+    canDelegate(toAgentId: string): DelegationCheckResult {
+      // INV-DT-001: Check depth limit
+      if (context.currentDepth >= context.maxDepth) {
+        return {
+          allowed: false,
+          reason: DelegationErrorCodes.MAX_DEPTH_EXCEEDED,
+          message: `Maximum delegation depth ${context.maxDepth} reached`,
+        };
+      }
+
+      // INV-DT-002: Check for circular delegation
+      if (context.delegationChain.includes(toAgentId)) {
+        return {
+          allowed: false,
+          reason: DelegationErrorCodes.CIRCULAR_DELEGATION,
+          message: `Cannot delegate to ${toAgentId} - already in delegation chain`,
+        };
+      }
+
+      return {
+        allowed: true,
+        reason: 'ALLOWED',
+        message: `Delegation to ${toAgentId} is allowed`,
+      };
+    },
+
+    createDelegationRequest(
+      toAgentId: string,
+      task: string,
+      input?: unknown,
+      timeout?: number
+    ): ContractDelegationRequest | null {
+      const checkResult = this.canDelegate(toAgentId);
+      if (!checkResult.allowed) {
+        return null;
+      }
+
+      return {
+        fromAgentId: agentId,
+        toAgentId,
+        task,
+        input,
+        timeout,
+        context,
+      };
+    },
+
+    createChildContext(toAgentId: string): DelegationContext {
+      return {
+        ...context,
+        currentDepth: context.currentDepth + 1,
+        delegationChain: [...context.delegationChain, toAgentId],
+      };
+    },
+
+    recordResult(result: DelegationResult): void {
+      delegationHistory.push(result);
+    },
+
+    getHistory(): DelegationResult[] {
+      return [...delegationHistory];
+    },
+
+    isRoot(): boolean {
+      return context.currentDepth === 0;
+    },
+
+    getRemainingDepth(): number {
+      return context.maxDepth - context.currentDepth;
+    },
+  };
+}
+
+/**
+ * Stub delegation tracker factory
+ *
+ * Use this as a fallback when no factory is provided in config.
+ */
+export const stubDelegationTrackerFactory: DelegationTrackerFactory =
+  createStubDelegationTracker;
+
+/**
+ * Reset the warning flag (for testing)
+ */
+export function resetStubWarning(): void {
+  _warnedOnce = false;
+}

package/src/stub-parallel-executor.ts

@@ -0,0 +1,224 @@
+/**
+ * Stub Parallel Executor Implementation
+ *
+ * Provides minimal parallel execution for when no real implementation
+ * is provided via AgentDomainConfig factories.
+ *
+ * This stub executes steps sequentially (not actually in parallel).
+ * For real parallel execution, provide parallelExecutorFactory in config.
+ */
+
+import {
+  type ParallelExecutionConfig,
+  createDefaultParallelExecutionConfig,
+  type AgentWorkflowStep,
+  TIMEOUT_ORCHESTRATION_EXECUTION,
+} from '@defai.digital/contracts';
+import type {
+  ParallelExecutorPort,
+  ParallelStepExecutor,
+  ParallelGroupResult,
+  ParallelStepResult,
+  ParallelExecutorFactory,
+} from './types.js';
+
+let _warnedOnce = false;
+
+/**
+ * Creates a stub parallel executor that executes steps sequentially
+ */
+function createStubParallelExecutor(
+  config: Partial<ParallelExecutionConfig> = {}
+): ParallelExecutorPort {
+  if (!_warnedOnce) {
+    console.warn(
+      '[agent-domain] Using stub parallel executor (sequential execution). ' +
+      'For real parallel execution, provide parallelExecutorFactory in config.'
+    );
+    _warnedOnce = true;
+  }
+
+  const cfg = { ...createDefaultParallelExecutionConfig(), ...config };
+  let cancelled = false;
+
+  return {
+    getConfig(): ParallelExecutionConfig {
+      return { ...cfg };
+    },
+
+    async executeGroup(
+      steps: AgentWorkflowStep[],
+      executor: ParallelStepExecutor,
+      previousOutputs: Record<string, unknown> = {}
+    ): Promise<ParallelGroupResult> {
+      const startTime = Date.now();
+      const stepResults: ParallelStepResult[] = [];
+      const outputs = { ...previousOutputs };
+      let failedCount = 0;
+      let cancelledCount = 0;
+
+      // Build execution layers (respecting dependencies)
+      const layers = this.buildExecutionLayers(steps);
+
+      // Execute layers sequentially (stub doesn't do real parallelism)
+      for (const layer of layers) {
+        if (cancelled) {
+          // Mark remaining steps as cancelled
+          for (const step of layer) {
+            stepResults.push({
+              stepId: step.stepId,
+              success: false,
+              cancelled: true,
+              durationMs: 0,
+            });
+            cancelledCount++;
+          }
+          continue;
+        }
+
+        // Execute steps in layer sequentially
+        for (const step of layer) {
+          if (cancelled) {
+            stepResults.push({
+              stepId: step.stepId,
+              success: false,
+              cancelled: true,
+              durationMs: 0,
+            });
+            cancelledCount++;
+            continue;
+          }
+
+          const stepStart = Date.now();
+          // Create cancellable timeout to prevent timer leaks
+          let timeoutId: ReturnType<typeof setTimeout> | undefined;
+          const stepTimeoutMs = cfg.groupTimeoutMs ?? TIMEOUT_ORCHESTRATION_EXECUTION;
+          const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => { reject(new Error('Step timed out')); }, stepTimeoutMs);
+          });
+
+          try {
+            const output = await Promise.race([
+              executor(step, outputs),
+              timeoutPromise,
+            ]);
+
+            // Clean up timeout
+            if (timeoutId !== undefined) {
+              clearTimeout(timeoutId);
+            }
+
+            outputs[step.stepId] = output;
+            stepResults.push({
+              stepId: step.stepId,
+              success: true,
+              output,
+              durationMs: Date.now() - stepStart,
+            });
+          } catch (error) {
+            // Clean up timeout on error too
+            if (timeoutId !== undefined) {
+              clearTimeout(timeoutId);
+            }
+            const result: ParallelStepResult = {
+              stepId: step.stepId,
+              success: false,
+              error: error instanceof Error ? error.message : 'Unknown error',
+              durationMs: Date.now() - stepStart,
+            };
+            stepResults.push(result);
+            failedCount++;
+
+            // If step is critical (not parallel) and failFast strategy, stop execution
+            if (!step.parallel && cfg.failureStrategy === 'failFast') {
+              cancelled = true;
+            }
+          }
+        }
+      }
+
+      return {
+        stepResults,
+        totalDurationMs: Date.now() - startTime,
+        allSucceeded: failedCount === 0 && cancelledCount === 0,
+        failedCount,
+        cancelledCount,
+      };
+    },
+
+    buildExecutionLayers(steps: AgentWorkflowStep[]): AgentWorkflowStep[][] {
+      // Simple topological sort based on dependencies
+      const layers: AgentWorkflowStep[][] = [];
+      const completed = new Set<string>();
+      const remaining = [...steps];
+
+      // Guard against infinite loops with max iteration limit
+      const maxIterations = steps.length + 1;
+      let iterations = 0;
+
+      while (remaining.length > 0 && iterations < maxIterations) {
+        iterations++;
+        // Find steps with all dependencies satisfied
+        const ready: AgentWorkflowStep[] = [];
+        const stillWaiting: AgentWorkflowStep[] = [];
+
+        for (const step of remaining) {
+          const deps = step.dependencies ?? [];
+          if (deps.every((dep) => completed.has(dep))) {
+            ready.push(step);
+          } else {
+            stillWaiting.push(step);
+          }
+        }
+
+        if (ready.length === 0 && stillWaiting.length > 0) {
+          // Circular dependency or missing dependency - execute remaining steps
+          const unresolvableSteps = stillWaiting.map((s) => s.stepId).join(', ');
+          console.warn(
+            `[buildExecutionLayers] Circular or unresolvable dependencies detected. ` +
+            `Unresolvable steps: ${unresolvableSteps}`
+          );
+          layers.push(stillWaiting);
+          break;
+        }
+
+        if (ready.length > 0) {
+          layers.push(ready);
+          for (const step of ready) {
+            completed.add(step.stepId);
+          }
+        }
+
+        remaining.length = 0;
+        remaining.push(...stillWaiting);
+      }
+
+      if (iterations >= maxIterations) {
+        console.error(
+          `[buildExecutionLayers] Max iterations (${maxIterations}) reached. ` +
+          `This indicates a bug in the algorithm or malformed input.`
+        );
+      }
+
+      return layers;
+    },
+
+    cancel(): void {
+      cancelled = true;
+    },
+  };
+}
+
+/**
+ * Stub parallel executor factory
+ */
+export const stubParallelExecutorFactory: ParallelExecutorFactory = (config) => {
+  return createStubParallelExecutor(config);
+};
+
+/**
+ * Reset the warning flag (for testing)
+ */
+export function resetParallelStubWarning(): void {
+  _warnedOnce = false;
+}