@od-oneapp/ai-platform 0.1.0

package/src/agents/coordinator/coordinator-agent.ts

@@ -0,0 +1,381 @@
+/**
+ * @fileoverview Coordinator agent for multi-agent orchestration.
+ * @module @od-oneapp/ai-platform/agents/coordinator
+ */
+
+import { withTimeout } from '@repo/core-utils/shared/timeout';
+import { z } from 'zod';
+
+import { generateObject } from '../../shared';
+import { createInitialState } from '../base/factory';
+
+import type { SDKLanguageModel } from '../../shared';
+import type { Agent, AgentConfig, BaseAgentState, AgentExecutionOptions } from '../base/types';
+
+
+/**
+ * Task definition for coordinator.
+ */
+export interface Task {
+  /** Task ID */
+  id: string;
+  /** Task description */
+  description: string;
+  /** Agent ID to execute task */
+  agentId: string;
+  /** Dependencies (task IDs that must complete first) */
+  dependencies?: string[];
+  /** Priority (higher = more urgent) */
+  priority?: number;
+  /** Input data for the task */
+  input?: unknown;
+}
+
+/**
+ * Task result.
+ */
+export interface TaskResult {
+  /** Task ID */
+  taskId: string;
+  /** Task status */
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  /** Result data */
+  result?: unknown;
+  /** Error if failed */
+  error?: string;
+  /** Execution time in ms */
+  executionTimeMs?: number;
+}
+
+/**
+ * Execution plan schema.
+ */
+export const ExecutionPlanSchema = z.object({
+  /** Plan description */
+  description: z.string(),
+  /** Tasks to execute */
+  tasks: z.array(
+    z.object({
+      id: z.string(),
+      description: z.string(),
+      agentId: z.string(),
+      dependencies: z.array(z.string()).optional(),
+      priority: z.number().optional(),
+    }),
+  ),
+  /** Estimated total time */
+  estimatedTimeMs: z.number().optional(),
+});
+
+export type ExecutionPlan = z.infer<typeof ExecutionPlanSchema>;
+
+/**
+ * Coordinator agent configuration.
+ */
+export interface CoordinatorConfig extends Omit<AgentConfig, 'systemPrompt'> {
+  /** Available agents */
+  agents: Map<string, Agent>;
+  /** Maximum parallel tasks */
+  maxParallel?: number;
+  /** Task timeout in ms */
+  taskTimeoutMs?: number;
+  /** Custom planning prompt */
+  planningPrompt?: string;
+}
+
+/**
+ * Creates a coordinator agent that orchestrates multiple agents.
+ *
+ * @param config - Coordinator configuration
+ * @returns Coordinator agent
+ *
+ * @example
+ * ```ts
+ * const coordinator = createCoordinatorAgent({
+ *   id: 'coordinator',
+ *   name: 'Task Coordinator',
+ *   description: 'Coordinates multi-agent workflows',
+ *   agents: new Map([
+ *     ['research', researchAgent],
+ *     ['code', codeAgent],
+ *     ['review', reviewAgent],
+ *   ]),
+ *   maxParallel: 3,
+ * });
+ *
+ * const result = await coordinator.execute('Build a todo app with tests', {
+ *   model: openai('gpt-4o'),
+ * });
+ * ```
+ */
+export function createCoordinatorAgent(config: CoordinatorConfig) {
+  const { agents, maxParallel = 3, taskTimeoutMs = 60000, planningPrompt } = config;
+
+  // Validate maxParallel to avoid misleading failures
+  if (maxParallel < 1) {
+    throw new Error(`maxParallel must be at least 1, got ${maxParallel}`);
+  }
+
+  const systemPrompt = planningPrompt ?? buildPlanningPrompt(agents);
+
+  return {
+    config: { ...config, systemPrompt } as AgentConfig,
+    agents,
+
+    /**
+     * Creates an execution plan for a goal.
+     */
+    async plan(
+      goal: string,
+      options: { model: SDKLanguageModel; context?: AgentExecutionOptions['context'] },
+    ): Promise<ExecutionPlan> {
+      const { object } = await generateObject({
+        model: options.model,
+        system: systemPrompt,
+        prompt: `Create an execution plan for this goal:\n\n"${goal}"`,
+        schema: ExecutionPlanSchema,
+        abortSignal: options.context?.abortSignal,
+      });
+
+      return object;
+    },
+
+    /**
+     * Executes a plan with dependency management.
+     */
+    async executePlan(
+      plan: ExecutionPlan,
+      options: AgentExecutionOptions,
+    ): Promise<Map<string, TaskResult>> {
+      // Validate unique task IDs to prevent silent task skipping
+      const taskIds = plan.tasks.map(t => t.id);
+      const uniqueIds = new Set(taskIds);
+      if (uniqueIds.size !== taskIds.length) {
+        const duplicates = taskIds.filter((id, idx) => taskIds.indexOf(id) !== idx);
+        throw new Error(`Duplicate task IDs detected: ${[...new Set(duplicates)].join(', ')}`);
+      }
+
+      const results = new Map<string, TaskResult>();
+      const pending = new Set(plan.tasks.map(t => t.id));
+      const running = new Set<string>();
+      const runningPromises = new Map<string, Promise<void>>();
+
+      // Initialize all tasks as pending
+      for (const task of plan.tasks) {
+        results.set(task.id, { taskId: task.id, status: 'pending' });
+      }
+
+      while (pending.size > 0 || running.size > 0) {
+        // Find ready tasks (dependencies completed), sorted by priority descending
+        const availableSlots = maxParallel - running.size;
+        const readyTasks = plan.tasks
+          .filter(task => {
+            if (!pending.has(task.id)) return false;
+
+            const deps = task.dependencies ?? [];
+            return deps.every(depId => {
+              const depResult = results.get(depId);
+              return depResult?.status === 'completed';
+            });
+          })
+          .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+          .slice(0, Math.max(0, availableSlots));
+
+        if (readyTasks.length === 0 && running.size === 0) {
+          // Check for missing dependencies first
+          const missingDeps = plan.tasks
+            .filter(task => pending.has(task.id))
+            .flatMap(task => {
+              const deps = task.dependencies ?? [];
+              return deps
+                .filter(depId => !results.has(depId))
+                .map(depId => ({ taskId: task.id, depId }));
+            });
+
+          if (missingDeps.length > 0) {
+            const missingDep = missingDeps[0];
+            if (missingDep) {
+              throw new Error(
+                `Task "${missingDep.taskId}" references non-existent dependency "${missingDep.depId}"`,
+              );
+            }
+          }
+
+          // Check for failed dependencies
+          const hasFailedDeps = plan.tasks.some(task => {
+            if (!pending.has(task.id)) return false;
+            const deps = task.dependencies ?? [];
+            return deps.some(depId => results.get(depId)?.status === 'failed');
+          });
+
+          if (hasFailedDeps) {
+            // Mark remaining tasks as failed due to dependency failure
+            for (const taskId of pending) {
+              results.set(taskId, {
+                taskId,
+                status: 'failed',
+                error: 'Dependency failed',
+              });
+            }
+            break;
+          }
+
+          // Circular dependency
+          throw new Error('Circular dependency detected in task plan');
+        }
+
+        // Start ready tasks
+        for (const task of readyTasks) {
+          pending.delete(task.id);
+          running.add(task.id);
+          results.set(task.id, { taskId: task.id, status: 'running' });
+
+          const taskPromise = (async () => {
+            const startTime = Date.now();
+            const agent = agents.get(task.agentId);
+
+            if (!agent) {
+              results.set(task.id, {
+                taskId: task.id,
+                status: 'failed',
+                error: `Agent not found: ${task.agentId}`,
+              });
+              running.delete(task.id);
+              runningPromises.delete(task.id);
+              return;
+            }
+
+            try {
+              // Build context with dependency results
+              const depResults: Record<string, unknown> = {};
+              for (const depId of task.dependencies ?? []) {
+                depResults[depId] = results.get(depId)?.result;
+              }
+
+              const prompt = buildTaskPrompt(task, depResults);
+              const agentResult = await withTimeout(agent.execute(prompt, options), taskTimeoutMs, {
+                name: `Task ${task.id}`,
+              });
+
+              results.set(task.id, {
+                taskId: task.id,
+                status: 'completed',
+                result: agentResult.result,
+                executionTimeMs: Date.now() - startTime,
+              });
+            } catch (error) {
+              results.set(task.id, {
+                taskId: task.id,
+                status: 'failed',
+                error: error instanceof Error ? error.message : String(error),
+                executionTimeMs: Date.now() - startTime,
+              });
+            } finally {
+              running.delete(task.id);
+              runningPromises.delete(task.id);
+            }
+          })();
+
+          runningPromises.set(task.id, taskPromise);
+        }
+
+        // Wait for at least one task to complete if there are any running
+        if (runningPromises.size > 0) {
+          await Promise.race(runningPromises.values());
+        }
+      }
+
+      return results;
+    },
+
+    /**
+     * Full execution: plan + execute.
+     */
+    async execute(
+      prompt: string,
+      options: AgentExecutionOptions,
+    ): Promise<BaseAgentState & { plan: ExecutionPlan; taskResults: Map<string, TaskResult> }> {
+      const state = createInitialState(options.messages);
+
+      try {
+        // Create plan
+        const plan = await this.plan(prompt, {
+          model: options.model,
+          context: options.context,
+        });
+
+        state.metadata.plan = plan;
+
+        // Execute plan
+        const taskResults = await this.executePlan(plan, options);
+
+        // Aggregate results
+        const completedTasks = Array.from(taskResults.values()).filter(
+          r => r.status === 'completed',
+        );
+
+        state.isComplete = true;
+        state.result = {
+          plan,
+          taskResults: Object.fromEntries(taskResults),
+          completedCount: completedTasks.length,
+          totalCount: plan.tasks.length,
+        };
+
+        return { ...state, plan, taskResults };
+      } catch (error) {
+        state.error = error instanceof Error ? error : new Error(String(error));
+        state.isComplete = true;
+        return {
+          ...state,
+          plan: { description: '', tasks: [] },
+          taskResults: new Map(),
+        };
+      }
+    },
+  };
+}
+
+/**
+ * Builds the planning system prompt.
+ */
+function buildPlanningPrompt(agents: Map<string, Agent>): string {
+  const agentList = Array.from(agents.entries())
+    .map(([id, agent]) => `- ${id}: ${agent.config.description}`)
+    .join('\n');
+
+  return `You are a task planning coordinator. Your job is to break down complex goals into tasks that can be executed by specialized agents.
+
+Available Agents:
+${agentList}
+
+Instructions:
+1. Analyze the goal to identify required sub-tasks
+2. Assign each task to the most appropriate agent
+3. Define dependencies between tasks (which must complete before others can start)
+4. Prioritize tasks when possible (higher priority = execute first when ready)
+5. Keep tasks focused and atomic
+
+Output your plan in the specified JSON format.`;
+}
+
+/**
+ * Builds a task prompt including dependency results.
+ */
+function buildTaskPrompt(task: Task, depResults: Record<string, unknown>): string {
+  let prompt = task.description;
+
+  if (task.input) {
+    prompt += `\n\nInput: ${JSON.stringify(task.input)}`;
+  }
+
+  const deps = Object.entries(depResults);
+  if (deps.length > 0) {
+    prompt += '\n\nResults from previous tasks:';
+    for (const [depId, result] of deps) {
+      prompt += `\n- ${depId}: ${JSON.stringify(result)}`;
+    }
+  }
+
+  return prompt;
+}

package/src/agents/coordinator/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Coordinator agent for multi-agent orchestration.
+ * @module @od-oneapp/ai-platform/agents/coordinator
+ */
+
+export * from './coordinator-agent';

package/src/agents/default-agent.ts

@@ -0,0 +1,211 @@
+/**
+ * @fileoverview Agent creation utilities
+ *
+ * Provides functions for creating AI agents with default configurations including
+ * guardrails, loop policies, telemetry, and structured output support.
+ *
+ * THIS FILE IMPLEMENTS THE STANDARD AGENT TRACK (Experimental_Agent).
+ *
+ * @module @od-oneapp/ai-platform/agents/default-agent
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import {
+  applyDefaultGuardrails,
+  defaultTelemetry,
+  mergeActiveTools,
+  resolveLoopPolicy,
+} from "../governance/policies";
+import { ToolLoopAgent } from '../shared';
+
+import { createExecutionSignal, defaultTools } from "./tools";
+
+import type { SDKLanguageModelV3, SDKTelemetrySettings, SDKToolSet } from '../shared';
+import type { AgentStructuredOutput, RiskLevel } from './base/schemas';
+
+/** Registry of available tools keyed by tool name. */
+type ToolRegistry = SDKToolSet;
+
+/**
+ * Options for creating an AI agent with compliance-first configuration.
+ */
+export interface CreateAgentOptions {
+  /** Language model used for generation; guardrails are applied automatically. */
+  model: SDKLanguageModelV3;
+  /** Risk classification guiding loop controls (`low`, `medium`, `high`). */
+  riskLevel: RiskLevel;
+  /** Optional telemetry settings for observability. Defaults to {@link defaultTelemetry}. */
+  telemetry?: SDKTelemetrySettings;
+  /** Optional custom tools to add or override defaults. */
+  tools?: ToolRegistry;
+  /** Tool names to keep active; merged with risk-based policy choices. */
+  activeTools?: string[];
+  /** Unique identifier for this run. Defaults to a generated UUID. */
+  runId?: string;
+  /**
+   * Callback fired for every execution signal (tool events, loop stops).
+   * Not called when omitted.
+   */
+  onSignal?: (signal: ReturnType<typeof createExecutionSignal>) => void;
+  /**
+   * Callback invoked with validated structured output before finish cleanup.
+   * Errors inside are caught and logged to avoid failing the agent.
+   */
+  onStructuredOutput?: (output: AgentStructuredOutput) => Promise<void> | void;
+  /**
+   * Optional cleanup invoked after finish (even when no structured output).
+   * Use to close spans or release resources.
+   */
+  onCleanup?: () => Promise<void> | void;
+}
+
+/** Default agent output type (structured output schema). */
+export type DefaultAgentOutput = AgentStructuredOutput;
+
+/**
+ * Standard Agent type (Experimental_Agent instance).
+ * Wrapper class to maintain compatibility with legacy DefaultAgent interface
+ * while using Experimental_Agent internally.
+ */
+export class StandardAgent {
+  private agent: ToolLoopAgent<ToolRegistry>;
+  private options: CreateAgentOptions;
+  private runId: string;
+
+  public readonly tools: ToolRegistry;
+
+  constructor(options: CreateAgentOptions) {
+    this.options = options;
+    this.runId = options.runId ?? randomUUID();
+
+    // 1. apply guardrails
+    const wrappedModel = applyDefaultGuardrails(options.model);
+
+    // 2. resolve loop policy
+    const loopPolicy = resolveLoopPolicy({
+      riskLevel: options.riskLevel,
+      activeTools: options.activeTools,
+    });
+
+    // 3. merge tools
+    this.tools = {
+      ...defaultTools,
+      ...options.tools,
+    };
+
+    // 4. filter active tools if policy dictates
+    // Note: Experimental_Agent doesn't have native "activeTools" filtering in config
+    // so we pre-filter the tools object passed to it, or pass all.
+    // Ideally, we pass all tools but use system prompt to steer.
+    // However, loopPolicy.activeTools is strict.
+    const activeToolNames = mergeActiveTools(loopPolicy, options.activeTools);
+
+    // If activeTools is defined, STRICTLY filter the tools object
+    const finalTools: ToolRegistry = activeToolNames
+      ? Object.keys(this.tools)
+          .filter(key => activeToolNames.includes(key))
+          .reduce((obj, key) => {
+            const tool = this.tools[key];
+            if (tool) {
+              obj[key] = tool;
+            }
+            return obj;
+          }, {} as ToolRegistry)
+      : this.tools;
+
+    // 5. create agent
+    this.agent = new ToolLoopAgent({
+      model: wrappedModel,
+      tools: finalTools,
+      instructions:
+        'You are a compliance co-pilot. Obey guardrails, honour human approvals, and document every decision in the structured output.',
+      experimental_telemetry: options.telemetry ?? defaultTelemetry,
+      stopWhen: loopPolicy.stopCondition, // Maps cleanly: stepCountIs(n)
+    });
+  }
+
+  /**
+   * Generates a response using the agent.
+   * Wraps the internal generate call to provide signal emission and structured output handling.
+   */
+  async generate(options: Parameters<ToolLoopAgent<ToolRegistry>['generate']>[0]) {
+    // Execute generation
+    const result = await this.agent.generate(options);
+
+    // Post-processing: Emit signals from steps
+    if (this.options.onSignal && result.steps) {
+      for (const step of result.steps) {
+        if (step.toolCalls) {
+          for (const toolCall of step.toolCalls) {
+            const type = 'tool.executed'; // Agent v6 executes tools automatically by default
+            this.options.onSignal(
+              createExecutionSignal(
+                {
+                  id: toolCall.toolCallId,
+                  toolName: toolCall.toolName,
+                  input: toolCall.input,
+                },
+                type,
+                this.runId,
+              ),
+            );
+          }
+        }
+      }
+    }
+
+    // Post-processing: Check for structured output
+    // Assuming the model outputs json that matches the schema if requested,
+    // or if we forced it via toolChoice.
+    // For StandardAgent, we usually expect text or tool calls.
+    // If we need strict JSON output, we would use agent.generate({ ... }) with strict mode.
+    // ExperimentalAgent doesn't strictly enforce output schema on the top-level `generate`
+    // without `element` or structural forcing.
+
+    // Compatibility: If the last message or content looks like JSON and matches schema, parse it.
+    // OR if we are just returning the text.
+
+    // For this migration, we focus on the AGENT behavior.
+    // Structured Output persistence is best handled by the caller or by a specific "finish" tool.
+
+    // Cleanup
+    await this.options.onCleanup?.();
+
+    return result;
+  }
+
+  async stream(options: Parameters<ToolLoopAgent<ToolRegistry>['stream']>[0]) {
+    return this.agent.stream(options);
+  }
+
+  /**
+   * Access the underlying ToolLoopAgent instance.
+   * Intended for SDK helpers that require the raw agent type.
+   */
+  getToolLoopAgent(): ToolLoopAgent<ToolRegistry> {
+    return this.agent;
+  }
+}
+
+/**
+ * Type alias for the returned agent instance.
+ * Maintains compatibility with code expecting a class instance with generate/stream methods.
+ */
+export type DefaultAgent = StandardAgent;
+
+/**
+ * Creates a default agent (Standard Track).
+ * Uses Experimental_Agent under the hood.
+ */
+export const createDefaultAgent = (options: CreateAgentOptions): StandardAgent => {
+  return new StandardAgent(options);
+};
+
+// Legacy exports for backward compatibility if needed,
+// though we encourage moving to StandardAgent / GovernanceAgent distinction.
+export const createDefaultAgentConfig = (options: CreateAgentOptions) => {
+  void options;
+  // No-op or throw, as config object structure has changed
+  throw new Error('createDefaultAgentConfig is deprecated. Use createDefaultAgent directly.');
+};