@od-oneapp/ai-platform 0.1.0

package/src/agents/governance-agent.ts

@@ -0,0 +1,446 @@
+/**
+ * @fileoverview Governance Agent
+ *
+ * Implements the "Governance Track" agent strategy using the Ralph Wiggum autonomous retry loop.
+ * This agent prioritizes RELIABILITY and COMPLIANCE over raw speed.
+ *
+ * Features:
+ * - Autonomous Retry Loop (keeps trying until completion signal)
+ * - "Principal Skinner" Governance (fine-grained token budgets per iteration)
+ * - Audit Signals (loop.approval_required, loop.budget_exceeded)
+ * - Feedback Loops (feeds errors back into context)
+ *
+ * @module @od-oneapp/ai-platform/agents/governance-agent
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import { complianceSignalSchema } from '../governance/compliance/schemas';
+import { generateText } from '../shared';
+
+import type { ComplianceSignal, RiskLevel } from '../governance/compliance/schemas';
+import type { SDKLanguageModelV3, SDKTool } from '../shared';
+
+
+
+/**
+ * Configuration for Governance Agent (Principal Skinner) rules.
+ */
+export interface GovernanceRules {
+  /** Maximum tokens per iteration to limit output length. */
+  maxTokensPerIteration: number;
+  /** Tool names that are blocked from execution. */
+  blockedTools: string[];
+  /**
+   * Tool names that emit an approval signal when executed.
+   * NOTE: This is currently a notification/audit mechanism, NOT a blocking gate.
+   * Tools will execute and a 'loop.approval_required' signal is emitted for audit purposes.
+   */
+  requireApproval: string[];
+  /** Maximum total tokens across all iterations. */
+  maxTotalTokens?: number;
+  /** Timeout in milliseconds for each iteration. */
+  iterationTimeoutMs?: number;
+}
+
+/**
+ * Single iteration result.
+ */
+export interface GovernanceIteration {
+  /** Iteration index (1-based). */
+  index: number;
+  /** Status of the iteration. */
+  status: 'running' | 'success' | 'error' | 'timeout';
+  /** Output text from the iteration. */
+  output?: string;
+  /** Error message if iteration failed. */
+  error?: string;
+  /** Token usage for this iteration. */
+  tokenUsage: { input: number; output: number };
+  /** Duration in milliseconds. */
+  durationMs: number;
+  /** Tool calls made during this iteration. */
+  toolCalls?: Array<{ name: string; args: unknown }>;
+}
+
+/**
+ * Final result of the Governance Agent execution.
+ */
+export interface GovernanceResult {
+  /** Whether the loop completed successfully. */
+  success: boolean;
+  /** Total number of iterations executed. */
+  iterations: number;
+  /** All iteration results. */
+  iterationHistory: GovernanceIteration[];
+  /** Final output if successful. */
+  finalOutput?: string;
+  /** Error message if failed. */
+  error?: string;
+  /** Total token usage. */
+  totalTokens: { input: number; output: number };
+  /** Total duration in milliseconds. */
+  totalDurationMs: number;
+  /** Compliance signals generated. */
+  signals: ComplianceSignal[];
+}
+
+/**
+ * Options for configuring the Governance Agent.
+ */
+export interface GovernanceAgentOptions {
+  /** Task prompt to retry until completion. */
+  task: string;
+  /** Completion signal to detect success (e.g., "DONE", "COMPLETE", "FINISHED"). */
+  completionSignal: string;
+  /** Maximum iterations before force exit. Default: 10. */
+  maxIterations?: number;
+  /** Whether to feed errors back into context. Default: true. */
+  feedbackErrors?: boolean;
+  /** Delay between iterations in milliseconds. Default: 0. */
+  iterationDelay?: number;
+  /** Principal Skinner governance rules. */
+  governance: GovernanceRules;
+  /** Language model to use. */
+  model: SDKLanguageModelV3;
+  /** Tools available to the agent. */
+  tools?: Record<string, SDKTool>;
+  /** Callback for each iteration. */
+  onIteration?: (iteration: GovernanceIteration) => void;
+  /** Callback for compliance signals. */
+  onSignal?: (signal: ComplianceSignal) => void;
+  /** Optional system prompt to prepend. */
+  systemPrompt?: string;
+  /** Run ID for audit logging. */
+  runId?: string;
+}
+
+/**
+ * Creates a delay promise.
+ * @internal
+ */
+const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Filters tools based on blocked list.
+ * @internal
+ */
+const filterTools = (
+  tools: Record<string, SDKTool> | undefined,
+  blockedTools: string[],
+): Record<string, SDKTool> | undefined => {
+  if (!tools) return undefined;
+
+  const filtered: Record<string, SDKTool> = {};
+  for (const [name, tool] of Object.entries(tools)) {
+    if (!blockedTools.includes(name)) {
+      filtered[name] = tool;
+    }
+  }
+  return Object.keys(filtered).length > 0 ? filtered : undefined;
+};
+
+/**
+ * Checks if output contains completion signal.
+ * Uses word boundary matching to avoid false positives.
+ * @internal
+ */
+const detectCompletion = (output: string, signal: string): boolean => {
+  const escapedSignal = signal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const regex = new RegExp(`\\b${escapedSignal}\\b`, 'i');
+  return regex.test(output);
+};
+
+/**
+ * Creates a compliance signal.
+ * @internal
+ */
+const createSignal = (
+  type: ComplianceSignal['type'],
+  message: string,
+  runId: string,
+  riskLevel?: RiskLevel,
+  metadata?: Record<string, unknown>,
+): ComplianceSignal => {
+  return complianceSignalSchema.parse({
+    id: randomUUID(),
+    type,
+    message,
+    runId,
+    riskLevel,
+    timestamp: new Date().toISOString(),
+    metadata,
+  });
+};
+
+/**
+ * Executes the Governance Loop.
+ * @internal
+ */
+async function executeGovernanceLoop(options: GovernanceAgentOptions): Promise<GovernanceResult> {
+  const {
+    task,
+    completionSignal,
+    maxIterations = 10,
+    feedbackErrors = true,
+    iterationDelay = 0,
+    governance,
+    model,
+    tools,
+    onIteration,
+    onSignal,
+    systemPrompt,
+    runId = randomUUID(),
+  } = options;
+
+  const signals: ComplianceSignal[] = [];
+  const iterationHistory: GovernanceIteration[] = [];
+  let iteration = 0;
+  const context = task;
+  let lastError: string | undefined;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  const startTime = Date.now();
+
+  const allowedTools = filterTools(tools, governance.blockedTools);
+
+  const startSignal = createSignal(
+    'loop.started',
+    `Governance Agent started: ${task.slice(0, 50)}...`,
+    runId,
+    'low',
+    { maxIterations, completionSignal },
+  );
+  signals.push(startSignal);
+  onSignal?.(startSignal);
+
+  while (iteration < maxIterations) {
+    iteration++;
+    const iterationStart = Date.now();
+
+    if (
+      governance.maxTotalTokens &&
+      totalInputTokens + totalOutputTokens >= governance.maxTotalTokens
+    ) {
+      const budgetSignal = createSignal(
+        'loop.budget_exceeded',
+        `Total token budget exhausted after ${iteration - 1} iterations`,
+        runId,
+        'medium',
+        { totalInputTokens, totalOutputTokens },
+      );
+      signals.push(budgetSignal);
+      onSignal?.(budgetSignal);
+
+      return {
+        success: false,
+        iterations: iteration - 1,
+        iterationHistory,
+        error: `Token budget exceeded (${totalInputTokens + totalOutputTokens} / ${governance.maxTotalTokens})`,
+        totalTokens: { input: totalInputTokens, output: totalOutputTokens },
+        totalDurationMs: Date.now() - startTime,
+        signals,
+      };
+    }
+
+    const prompt =
+      feedbackErrors && lastError
+        ? `${context}\n\n[Previous attempt failed with error: ${lastError}]\n\nPlease try again and address the error.`
+        : context;
+
+    try {
+      const result = await generateText({
+        model,
+        prompt,
+        system: systemPrompt,
+        tools: allowedTools,
+        maxOutputTokens: governance.maxTokensPerIteration,
+        abortSignal: governance.iterationTimeoutMs
+          ? AbortSignal.timeout(governance.iterationTimeoutMs)
+          : undefined,
+      });
+
+      const iterationDuration = Date.now() - iterationStart;
+      const inputTokens = result.usage?.inputTokens ?? 0;
+      const outputTokens = result.usage?.outputTokens ?? 0;
+      totalInputTokens += inputTokens;
+      totalOutputTokens += outputTokens;
+
+      const toolCalls = result.toolCalls?.map(tc => ({
+        name: tc.toolName,
+        args: (tc as { input?: unknown; args?: unknown }).input ?? (tc as { args?: unknown }).args,
+      }));
+
+      if (toolCalls) {
+        const approvalRequired = toolCalls.filter(tc =>
+          governance.requireApproval.includes(tc.name),
+        );
+        if (approvalRequired.length > 0) {
+          const approvalSignal = createSignal(
+            'loop.approval_required',
+            `Audit: Tools executed that require approval: ${approvalRequired.map(t => t.name).join(', ')}`,
+            runId,
+            'medium',
+            { tools: approvalRequired, note: 'Post-execution audit signal' },
+          );
+          signals.push(approvalSignal);
+          onSignal?.(approvalSignal);
+        }
+      }
+
+      const iterationResult: GovernanceIteration = {
+        index: iteration,
+        status: 'running',
+        output: result.text,
+        tokenUsage: { input: inputTokens, output: outputTokens },
+        durationMs: iterationDuration,
+        toolCalls,
+      };
+
+      if (detectCompletion(result.text, completionSignal)) {
+        iterationResult.status = 'success';
+        iterationHistory.push(iterationResult);
+        onIteration?.(iterationResult);
+
+        const successSignal = createSignal(
+          'loop.completed',
+          `Governance Agent completed successfully after ${iteration} iterations`,
+          runId,
+          'low',
+          { iterations: iteration, totalTokens: totalInputTokens + totalOutputTokens },
+        );
+        signals.push(successSignal);
+        onSignal?.(successSignal);
+
+        return {
+          success: true,
+          iterations: iteration,
+          iterationHistory,
+          finalOutput: result.text,
+          totalTokens: { input: totalInputTokens, output: totalOutputTokens },
+          totalDurationMs: Date.now() - startTime,
+          signals,
+        };
+      }
+
+      iterationHistory.push(iterationResult);
+      onIteration?.(iterationResult);
+      lastError = undefined;
+
+      if (iterationDelay > 0 && iteration < maxIterations) {
+        await sleep(iterationDelay);
+      }
+    } catch (error) {
+      // Error handling consistent with previous implementation
+      const iterationDuration = Date.now() - iterationStart;
+      lastError = error instanceof Error ? error.message : String(error);
+      const isTimeout = error instanceof Error && error.name === 'TimeoutError';
+
+      const iterationResult: GovernanceIteration = {
+        index: iteration,
+        status: isTimeout ? 'timeout' : 'error',
+        error: lastError,
+        tokenUsage: { input: 0, output: 0 },
+        durationMs: iterationDuration,
+      };
+
+      iterationHistory.push(iterationResult);
+      onIteration?.(iterationResult);
+
+      const errorSignal = createSignal(
+        isTimeout ? 'loop.timeout' : 'loop.error',
+        `Iteration ${iteration} ${isTimeout ? 'timed out' : 'failed'}: ${lastError}`,
+        runId,
+        'medium',
+        { iteration, error: lastError },
+      );
+      signals.push(errorSignal);
+      onSignal?.(errorSignal);
+
+      if (!feedbackErrors) {
+        return {
+          success: false,
+          iterations: iteration,
+          iterationHistory,
+          error: `Iteration ${iteration} failed: ${lastError}`,
+          totalTokens: { input: totalInputTokens, output: totalOutputTokens },
+          totalDurationMs: Date.now() - startTime,
+          signals,
+        };
+      }
+    }
+  }
+
+  const exhaustedSignal = createSignal(
+    'loop.exhausted',
+    `Max iterations (${maxIterations}) reached without completion signal`,
+    runId,
+    'high',
+    { iterations: maxIterations, completionSignal },
+  );
+  signals.push(exhaustedSignal);
+  onSignal?.(exhaustedSignal);
+
+  return {
+    success: false,
+    iterations: iteration,
+    iterationHistory,
+    error: `Max iterations (${maxIterations}) reached without completion signal "${completionSignal}"`,
+    totalTokens: { input: totalInputTokens, output: totalOutputTokens },
+    totalDurationMs: Date.now() - startTime,
+    signals,
+  };
+}
+
+/**
+ * Governance Agent class.
+ * Wraps the autonomous retry loop in an interface compatible with StandardAgent.
+ */
+export class GovernanceAgent {
+  private options: GovernanceAgentOptions;
+
+  constructor(options: GovernanceAgentOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Generates a response using the governance retry loop.
+   * Maps the result to a format compatible with StandardAgent results where possible,
+   * or returns the specific GovernanceResult.
+   */
+  async generate(): Promise<GovernanceResult> {
+    return executeGovernanceLoop(this.options);
+  }
+
+  /**
+   * Creates a new instance with merged options.
+   */
+  static create(options: GovernanceAgentOptions): GovernanceAgent {
+    return new GovernanceAgent(options);
+  }
+}
+
+/**
+ * Factory for creating a Governance Agent with defaults.
+ */
+export function createGovernanceAgent(options: GovernanceAgentOptions): GovernanceAgent {
+  return new GovernanceAgent(options);
+}
+
+/**
+ * Default governance rules.
+ */
+export const DEFAULT_GOVERNANCE_RULES: GovernanceRules = {
+  maxTokensPerIteration: 4096,
+  blockedTools: ['deleteFile', 'formatDisk', 'dropTable', 'truncateTable', 'deleteDatabase'],
+  requireApproval: ['executeShell', 'runCommand', 'modifyPermissions', 'deployProduction'],
+  maxTotalTokens: 100_000,
+  iterationTimeoutMs: 60_000,
+};
+
+// Re-export types and legacy function for backward compatibility
+export const ralphLoop = executeGovernanceLoop;
+export type RalphLoopResult = GovernanceResult;
+export type RalphLoopOptions = GovernanceAgentOptions;
+export type RalphGovernance = GovernanceRules;
+export const DEFAULT_RALPH_GOVERNANCE = DEFAULT_GOVERNANCE_RULES;

package/src/agents/index.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview AI Agents Module
+ * @module @od-oneapp/ai-platform/agents
+ *
+ * Submodule overview:
+ * - base — Core agent types (BaseAgentState, AgentConfig, StopConditions)
+ * - triage — Intent-based routing to specialized agents
+ * - coordinator — Multi-step task planning and execution
+ * - experimental — AI SDK v6 agent with prepareStep hook and phased tools
+ * - evaluatorOptimizer — Typed evaluator/optimizer feedback loops
+ * - patterns — Lightweight pattern-based evaluator/optimizer (PatternEvaluatorOptimizer)
+ * - persistence — Checkpoint/restore with versioned state (CheckpointState)
+ * - controlFlow — Execution controllers, stop/continue conditions (ExecutionMetrics)
+ * - multi — Multi-agent swarm coordination (SwarmAgentState)
+ * - fallback — Model fallback and retry strategies
+ * - workflows — Workflow definition and execution
+ * - observability — Agent-level telemetry
+ *
+ * Note: tools/approval/ and tools/compliance/ are now re-exported from tools/index.ts.
+ */
+
+// Convenience exports for primary agent constructors
+export {
+  createTriageAgent,
+  createKeywordTriage,
+  type TriageAgentConfig,
+  type TriageResult,
+} from './triage/triage-agent';
+export {
+  createCoordinatorAgent,
+  type CoordinatorConfig,
+  type ExecutionPlan,
+  type Task,
+  type TaskResult,
+} from './coordinator/coordinator-agent';
+
+// Standard Agent (Experimental_Agent track)
+export {
+  StandardAgent,
+  createDefaultAgent,
+  createDefaultAgentConfig,
+  type CreateAgentOptions,
+  type DefaultAgent,
+  type DefaultAgentOutput,
+} from './default-agent';
+
+// Governance Agent (Ralph Loop track)
+export {
+  GovernanceAgent,
+  createGovernanceAgent,
+  DEFAULT_GOVERNANCE_RULES,
+  ralphLoop,
+  DEFAULT_RALPH_GOVERNANCE,
+  type GovernanceRules,
+  type GovernanceIteration,
+  type GovernanceResult,
+  type GovernanceAgentOptions,
+  type RalphLoopResult,
+  type RalphLoopOptions,
+  type RalphGovernance,
+} from './governance-agent';
+
+// Platform Orchestrator (risk-aware routing)
+export { PlatformOrchestrator, type OrchestratorOptions, type PlatformAgent } from './orchestrator';
+
+// Namespaced exports to avoid conflicts across agent modules
+export * as base from "./base";
+export * as triage from "./triage";
+export * as coordinator from "./coordinator";
+export * as experimental from "./experimental";
+export * as persistence from "./persistence";
+export * as observability from "./observability";
+export * as controlFlow from "./control-flow";
+export * as fallback from "./fallback";
+export * as workflows from "./workflows";
+export * as evaluatorOptimizer from "./evaluator-optimizer";
+export * as multi from "./multi";
+export * as swarm from "./multi/swarm";
+export * as patterns from "./patterns";

package/src/agents/multi/coordination/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Multi-agent coordination
+ * @module @od-oneapp/ai-platform/multi-agent/coordination
+ */
+
+export { InMemoryMessageBus } from './message-bus';

package/src/agents/multi/coordination/message-bus.ts

@@ -0,0 +1,144 @@
+/**
+ * In-memory message bus for agent coordination
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import { logError } from '@repo/shared/logs';
+
+import type { AgentMessage, MessageBus, MessageHandler, Unsubscribe } from '../types';
+
+/**
+ * In-memory message bus implementation
+ *
+ * @example
+ * ```ts
+ * const bus = new InMemoryMessageBus();
+ *
+ * // Subscribe to messages
+ * bus.subscribe("agent-1", async (msg) => {
+ *   console.log("Received:", msg.payload);
+ * });
+ *
+ * // Send a message
+ * await bus.send({
+ *   id: randomUUID(),
+ *   from: "coordinator",
+ *   to: "agent-1",
+ *   type: "command",
+ *   payload: { action: "process" },
+ *   timestamp: new Date().toISOString(),
+ * });
+ *
+ * // Request/response pattern
+ * const result = await bus.request<{ query: string }, { answer: string }>(
+ *   "coordinator", // from
+ *   "agent-1", // to
+ *   { query: "What is 2+2?" },
+ *   5000
+ * );
+ * ```
+ */
+export class InMemoryMessageBus implements MessageBus {
+  private handlers = new Map<string, MessageHandler[]>();
+  private topicHandlers = new Map<string, MessageHandler[]>();
+  private pending = new Map<
+    string,
+    { resolve: (value: unknown) => void; reject: (error: Error) => void }
+  >();
+
+  async send(message: AgentMessage): Promise<void> {
+    const targets = Array.isArray(message.to) ? message.to : [message.to];
+
+    for (const target of targets) {
+      const handlers = this.handlers.get(target) || [];
+      for (const handler of handlers) {
+        try {
+          await handler(message);
+        } catch (error) {
+          logError(`Handler error for target ${target}`, {
+            error: error instanceof Error ? error : new Error(String(error)),
+          });
+          // Continue to next handler
+        }
+      }
+    }
+
+    // Handle responses for pending requests
+    if (message.type === 'response' && message.correlationId) {
+      const pending = this.pending.get(message.correlationId);
+      if (pending) {
+        this.pending.delete(message.correlationId);
+        pending.resolve(message.payload);
+      }
+    }
+  }
+
+  async broadcast(topic: string, message: AgentMessage): Promise<void> {
+    const handlers = this.topicHandlers.get(topic) || [];
+    for (const handler of handlers) {
+      await handler(message);
+    }
+  }
+
+  subscribe(agentId: string, handler: MessageHandler): Unsubscribe {
+    const handlers = this.handlers.get(agentId) || [];
+    handlers.push(handler);
+    this.handlers.set(agentId, handlers);
+
+    return () => {
+      const idx = handlers.indexOf(handler);
+      if (idx >= 0) handlers.splice(idx, 1);
+    };
+  }
+
+  subscribeTopic(topic: string, handler: MessageHandler): Unsubscribe {
+    const handlers = this.topicHandlers.get(topic) || [];
+    handlers.push(handler);
+    this.topicHandlers.set(topic, handlers);
+
+    return () => {
+      const idx = handlers.indexOf(handler);
+      if (idx >= 0) handlers.splice(idx, 1);
+    };
+  }
+
+  async request<T, R>(from: string, to: string, payload: T, timeout = 30000): Promise<R> {
+    const correlationId = randomUUID();
+    const message: AgentMessage<T> = {
+      id: randomUUID(),
+      from,
+      to,
+      type: 'request',
+      payload,
+      correlationId,
+      timestamp: new Date().toISOString(),
+    };
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(correlationId);
+        reject(new Error(`Request timeout: ${to}`));
+      }, timeout);
+
+      this.pending.set(correlationId, {
+        resolve: response => {
+          clearTimeout(timer);
+          resolve(response as R);
+        },
+        reject: error => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+
+      void (async () => {
+        try {
+          await this.send(message);
+        } catch (error) {
+          reject(error as Error);
+        }
+      })();
+    });
+  }
+}

package/src/agents/multi/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Multi-agent coordination, supervision, and state management.
+ * @module @od-oneapp/ai-platform/agents/multi
+ */
+
+export * from "./swarm";