@od-oneapp/ai-platform 0.1.0

package/src/agents/base/factory.ts

@@ -0,0 +1,382 @@
+/**
+ * @fileoverview Core agent factory and agentic loop runner.
+ * @module @od-oneapp/ai-platform/agents/base
+ */
+
+import { generateText } from '../../shared';
+
+import { StopConditions } from './types';
+
+import type {
+  Agent,
+  AgentConfig,
+  BaseAgentState,
+  AgentExecutionOptions,
+  AgentMessage,
+  StopCondition,
+  ToolCallRecord,
+} from './types';
+import type {
+  SDKAssistantModelMessage as AssistantModelMessage,
+  SDKModelMessage as ModelMessage,
+  SDKSystemModelMessage as SystemModelMessage,
+  SDKToolModelMessage as ToolModelMessage,
+  SDKUserModelMessage as UserModelMessage,
+
+  SDKFilePart,
+  SDKMessagePart,
+  SDKTextPart,
+  SDKToolCallPart,
+  SDKToolResultOutput} from '../../shared';
+
+
+type ToolContent = Array<
+  Extract<SDKMessagePart, { type: 'tool-result' | 'tool-approval-response' }>
+>;
+
+type AssistantPart = SDKTextPart | SDKToolCallPart;
+
+function isTextPart(part: SDKMessagePart): part is SDKTextPart {
+  return part.type === 'text';
+}
+
+function isFilePart(part: SDKMessagePart): part is SDKFilePart {
+  return part.type === 'file';
+}
+
+function partsToText(parts: SDKMessagePart[]): string {
+  return parts
+    .filter(isTextPart)
+    .map(part => part.text)
+    .join('\n');
+}
+
+function isToolContent(parts: SDKMessagePart[]): parts is ToolContent {
+  return parts.every(part => part.type === 'tool-result' || part.type === 'tool-approval-response');
+}
+
+function isAssistantPart(part: SDKMessagePart): part is AssistantPart {
+  return part.type === 'text' || part.type === 'tool-call';
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isToolResultOutput(value: unknown): value is SDKToolResultOutput {
+  if (!isRecord(value)) return false;
+  return typeof value.type === 'string';
+}
+
+/**
+ * Creates initial agent state.
+ */
+export function createInitialState(messages: AgentMessage[] = []): BaseAgentState {
+  return {
+    iteration: 0,
+    messages: [...messages],
+    toolCalls: [],
+    isComplete: false,
+    metadata: {},
+  };
+}
+
+/**
+ * Executes a single agent step (shared logic for execute and stream).
+ * Handles model call, message updates, and tool call processing.
+ *
+ * @remarks This function mutates `state` directly for performance.
+ * It sets `state.metadata.lastToolCallCount` before each iteration
+ * to enable the `StopConditions.noToolCalls()` stop condition.
+ *
+ * @internal
+ */
+async function executeAgentStep(
+  state: BaseAgentState,
+  config: AgentConfig,
+  options: AgentExecutionOptions,
+): Promise<BaseAgentState> {
+  // Track tool call count before this iteration for stop condition checks
+  // (required for StopConditions.noToolCalls() to work correctly)
+  state.metadata.lastToolCallCount = state.toolCalls.length;
+  state.iteration++;
+
+  try {
+    const result = await generateText({
+      model: options.model,
+      system: config.systemPrompt,
+      messages: state.messages.map<ModelMessage>(message => {
+        if (message.role === 'tool') {
+          const toolCallId = message.toolCallId ?? 'unknown';
+          if (Array.isArray(message.content)) {
+            if (isToolContent(message.content)) {
+              const toolMessage: ToolModelMessage = { role: 'tool', content: message.content };
+              return toolMessage;
+            }
+
+            const textValue = partsToText(message.content);
+            const toolMessage: ToolModelMessage = {
+              role: 'tool',
+              content: [
+                {
+                  type: 'tool-result' as const,
+                  toolCallId,
+                  toolName: 'unknown',
+                  output: { type: 'text', value: textValue },
+                },
+              ],
+            };
+            return toolMessage;
+          }
+
+          const toolMessage: ToolModelMessage = {
+            role: 'tool',
+            content: [
+              {
+                type: 'tool-result' as const,
+                toolCallId,
+                toolName: 'unknown',
+                output: { type: 'text', value: message.content },
+              },
+            ],
+          };
+          return toolMessage;
+        }
+
+        if (message.role === 'system') {
+          const systemMessage: SystemModelMessage = {
+            role: 'system',
+            content:
+              typeof message.content === 'string' ? message.content : partsToText(message.content),
+          };
+          return systemMessage;
+        }
+
+        if (message.role === 'user') {
+          if (typeof message.content === 'string') {
+            const userMessage: UserModelMessage = { role: 'user', content: message.content };
+            return userMessage;
+          }
+          const userParts = message.content.filter(part => isTextPart(part) || isFilePart(part));
+          if (userParts.length === message.content.length) {
+            const userMessage: UserModelMessage = { role: 'user', content: userParts };
+            return userMessage;
+          }
+          const userMessage: UserModelMessage = {
+            role: 'user',
+            content: partsToText(message.content),
+          };
+          return userMessage;
+        }
+
+        if (typeof message.content === 'string') {
+          const assistantMessage: AssistantModelMessage = {
+            role: 'assistant',
+            content: message.content,
+          };
+          return assistantMessage;
+        }
+
+        const assistantParts = message.content.filter(isAssistantPart);
+        const assistantMessage: AssistantModelMessage = {
+          role: 'assistant',
+          content: assistantParts.length > 0 ? assistantParts : '',
+        };
+        return assistantMessage;
+      }),
+      tools: options.tools,
+      temperature: config.temperature,
+      abortSignal: options.context?.abortSignal,
+    });
+
+    // Add assistant message
+    state.messages.push({
+      role: 'assistant',
+      content: result.text,
+    });
+
+    // Process tool calls
+    if (result.toolCalls && result.toolCalls.length > 0) {
+      for (const toolCall of result.toolCalls) {
+        const toolResult = result.toolResults?.find(r => r.toolCallId === toolCall.toolCallId);
+        const toolInput = isRecord(toolCall.input) ? toolCall.input : {};
+        const toolOutput = isToolResultOutput(toolResult?.output) ? toolResult?.output : undefined;
+        const record: ToolCallRecord = {
+          id: toolCall.toolCallId,
+          name: toolCall.toolName,
+          input: toolInput,
+          result: toolOutput,
+          timestamp: Date.now(),
+        };
+
+        state.toolCalls.push(record);
+
+        // Add tool result message for multi-turn tool-use loops
+        if (toolOutput !== undefined) {
+          state.messages.push({
+            role: 'tool',
+            content: [
+              {
+                type: 'tool-result',
+                toolCallId: toolCall.toolCallId,
+                toolName: toolCall.toolName,
+                output: toolOutput,
+              },
+            ],
+            toolCallId: toolCall.toolCallId,
+          });
+        }
+
+        if (options.onToolCall) {
+          await options.onToolCall(record);
+        }
+      }
+    } else {
+      // No tool calls means agent is done
+      state.isComplete = true;
+      state.result = result.text;
+    }
+  } catch (error) {
+    state.error = error instanceof Error ? error : new Error(String(error));
+    state.isComplete = true;
+  }
+
+  return state;
+}
+
+/**
+ * Creates a basic agent with agentic loop execution.
+ *
+ * @param config - Agent configuration
+ * @param stopCondition - Optional custom stop condition
+ * @returns Agent instance
+ *
+ * @example
+ * ```ts
+ * const agent = createAgent({
+ *   id: 'research-agent',
+ *   name: 'Research Agent',
+ *   description: 'Researches topics using web search',
+ *   systemPrompt: 'You are a research assistant...',
+ *   maxIterations: 5,
+ * });
+ *
+ * const result = await agent.execute('Research AI trends', {
+ *   model: openai('gpt-4o'),
+ *   tools: { webSearch, summarize },
+ * });
+ * ```
+ */
+export function createAgent(config: AgentConfig, stopCondition?: StopCondition): Agent {
+  const defaultStopCondition = StopConditions.any(
+    StopConditions.maxIterations(config.maxIterations),
+    StopConditions.onError(),
+  );
+
+  const stop = stopCondition ?? defaultStopCondition;
+
+  return {
+    config,
+
+    async execute(prompt: string, options: AgentExecutionOptions): Promise<BaseAgentState> {
+      const state = createInitialState(options.messages);
+
+      // Add user message
+      state.messages.push({
+        role: 'user',
+        content: prompt,
+      });
+
+      // Run agentic loop using shared step execution
+      while (!state.isComplete && !stop(state)) {
+        await executeAgentStep(state, config, options);
+
+        if (options.onStep) {
+          await options.onStep(state);
+        }
+      }
+
+      // Mark complete if stopped by condition
+      if (!state.isComplete) {
+        state.isComplete = true;
+        state.result = state.messages[state.messages.length - 1]?.content ?? '';
+      }
+
+      if (options.onComplete) {
+        await options.onComplete(state);
+      }
+
+      return state;
+    },
+
+    async *stream(prompt: string, options: AgentExecutionOptions): AsyncGenerator<BaseAgentState> {
+      const state = createInitialState(options.messages);
+
+      state.messages.push({
+        role: 'user',
+        content: prompt,
+      });
+
+      // Run agentic loop using shared step execution
+      while (!state.isComplete && !stop(state)) {
+        await executeAgentStep(state, config, options);
+        yield state;
+      }
+
+      if (!state.isComplete) {
+        state.isComplete = true;
+        state.result = state.messages[state.messages.length - 1]?.content;
+        yield state;
+      }
+    },
+  };
+}
+
+/**
+ * Runs an agentic loop with custom step function.
+ *
+ * @param options - Loop options
+ * @returns Final state
+ *
+ * @remarks The `step` function MUST increment `state.iteration` to ensure
+ * the `maxIterations` safety bound is respected. Failure to do so may result
+ * in an infinite loop if `shouldStop` never returns true.
+ *
+ * @example
+ * ```ts
+ * const result = await runAgentLoop({
+ *   maxIterations: 5,
+ *   initialState: createInitialState(),
+ *   step: async (state) => {
+ *     // Custom step logic - MUST increment iteration
+ *     return { ...state, iteration: state.iteration + 1 };
+ *   },
+ *   shouldStop: (state) => state.iteration >= 5,
+ * });
+ * ```
+ */
+export async function runAgentLoop(options: {
+  maxIterations: number;
+  initialState: BaseAgentState;
+  step: (state: BaseAgentState) => Promise<BaseAgentState>;
+  shouldStop: StopCondition;
+  onStep?: (state: BaseAgentState) => void | Promise<void>;
+}): Promise<BaseAgentState> {
+  let state = options.initialState;
+
+  // Note: maxIterations provides a safety limit; shouldStop handles custom conditions
+  while (state.iteration < options.maxIterations && !options.shouldStop(state)) {
+    state = await options.step(state);
+
+    if (options.onStep) {
+      await options.onStep(state);
+    }
+
+    if (state.error) {
+      break;
+    }
+  }
+
+  state.isComplete = true;
+  return state;
+}

package/src/agents/base/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Base agent utilities.
+ * @module @od-oneapp/ai-platform/agents/base
+ */
+
+export * from './types';
+export * from './factory';
+export * from './schemas';

package/src/agents/base/schemas.ts

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Agent output schemas — structured output, tool calls, citations.
+ *
+ * Defines the standard output format for agent runs including decisions,
+ * tool call records, and supporting evidence.
+ *
+ * @module @od-oneapp/ai-platform/agents/base/schemas
+ */
+
+import { z } from 'zod';
+
+import { riskLevels } from '../../governance/compliance/schemas';
+export type { RiskLevel } from '../../governance/compliance/schemas';
+
+/**
+ * Schema for agent tool call information.
+ * Captures tool execution details for audit and compliance purposes.
+ * @example
+ * ```ts
+ * const call = agentToolCallSchema.parse({
+ *   id: 'tool-1',
+ *   toolName: 'auditLog',
+ *   input: { runId: '123' },
+ *   approved: true,
+ * });
+ * ```
+ */
+export const agentToolCallSchema = z.object({
+  /** Stable identifier for the tool call. */
+  id: z.string().describe('Stable identifier for the tool call'),
+  /** Name of the tool that executed. */
+  toolName: z.string().describe('Name of the tool that executed'),
+  /** Raw input passed to the tool. */
+  input: z
+    .unknown()
+    .refine(val => val !== undefined, {
+      message: 'input is required',
+    })
+    .describe('Raw input passed to the tool'),
+  /** Whether a human approved execution. */
+  approved: z.boolean().optional().describe('Whether a human approved execution'),
+  /** Execution duration in milliseconds. */
+  durationMs: z.number().nonnegative().optional().describe('Execution duration in milliseconds'),
+  /** Short, human readable summary of the tool output. */
+  resultSummary: z.string().optional().describe('Short, human readable summary of the tool output'),
+});
+
+/**
+ * Schema for agent citation/reference information.
+ * Represents supporting evidence or sources for agent decisions.
+ * @example
+ * ```ts
+ * const citation = agentCitationSchema.parse({
+ *   id: 'c1',
+ *   title: 'Policy',
+ *   url: 'https://example.com',
+ *   snippet: 'Policy snippet',
+ * });
+ * ```
+ */
+export const agentCitationSchema = z.object({
+  /** Citation identifier. */
+  id: z.string(),
+  /** Citation title. */
+  title: z.string(),
+  /** Optional citation URL. */
+  url: z.string().url().optional(),
+  /** Citation snippet/text. */
+  snippet: z.string(),
+  /** Optional relevance score (0-1). */
+  score: z.number().min(0).max(1).optional(),
+});
+
+/**
+ * Schema for agent structured output.
+ * Comprehensive output format capturing all agent decisions, tool calls, and evidence.
+ * @example
+ * ```ts
+ * const output = agentStructuredOutputSchema.parse({
+ *   runId: 'run-1',
+ *   summary: 'Completed review',
+ *   decision: 'approve',
+ *   riskLevel: 'medium',
+ *   toolCalls: [],
+ *   citations: [],
+ *   notes: ['No PII found'],
+ * });
+ * ```
+ */
+export const agentStructuredOutputSchema = z.object({
+  /** Unique identifier for the agent run. */
+  runId: z.string().describe('Unique identifier for the agent run'),
+  /** One sentence describing the outcome. */
+  summary: z.string().describe('One sentence describing the outcome'),
+  /** Final assistant decision or recommendation. */
+  decision: z.string().describe('Final assistant decision or recommendation'),
+  /** Risk classification applied to the run. */
+  riskLevel: z.enum(riskLevels).describe('Risk classification applied to the run'),
+  /** Every tool call executed during the run. */
+  toolCalls: z.array(agentToolCallSchema).describe('Every tool call executed during the run'),
+  /** Supporting evidence for the decision. */
+  citations: z.array(agentCitationSchema).describe('Supporting evidence for the decision'),
+  /** Additional compliance notes captured during the run. */
+  notes: z
+    .array(z.string())
+    .optional()
+    .describe('Additional compliance notes captured during the run'),
+  /** Arbitrary labels for audit filtering. */
+  tags: z.array(z.string()).optional().describe('Arbitrary labels for audit filtering'),
+});
+
+/** Agent structured output type. */
+export type AgentStructuredOutput = z.infer<typeof agentStructuredOutputSchema>;
+/** Agent tool call type. */
+export type AgentToolCall = z.infer<typeof agentToolCallSchema>;
+/** Agent citation type. */
+export type AgentCitation = z.infer<typeof agentCitationSchema>;

package/src/agents/base/types.ts

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview Base agent types and interfaces.
+ * @module @od-oneapp/ai-platform/agents/base
+ *
+ * Types are aligned with AI SDK v6 where applicable.
+ * Uses LanguageModel and Tool types directly from the SDK.
+ */
+
+import { z } from 'zod';
+
+import type { SDKLanguageModel, SDKTool , MessageRole, SDKMessagePart } from '../../shared';
+
+/**
+ * Agent configuration schema.
+ */
+export const AgentConfigSchema = z.object({
+  /** Unique agent identifier */
+  id: z.string(),
+  /** Human-readable agent name */
+  name: z.string(),
+  /** Agent description for routing/triage */
+  description: z.string(),
+  /** System prompt for the agent */
+  systemPrompt: z.string(),
+  /** Maximum iterations for agentic loops */
+  maxIterations: z.number().default(10),
+  /** Maximum tokens for response */
+  maxTokens: z.number().optional(),
+  /** Temperature for generation */
+  temperature: z.number().min(0).max(2).optional(),
+});
+
+export type AgentConfig = z.infer<typeof AgentConfigSchema>;
+
+/**
+ * Simple message type for agent state.
+ * Uses SDK-aligned MessageRole type.
+ */
+export interface AgentMessage {
+  role: MessageRole;
+  content: string | SDKMessagePart[];
+  toolCallId?: string;
+}
+
+/**
+ * Base agent state for tracking execution.
+ */
+export interface BaseAgentState {
+  /** Current iteration count */
+  iteration: number;
+  /** Accumulated messages */
+  messages: AgentMessage[];
+  /** Tool calls made */
+  toolCalls: ToolCallRecord[];
+  /** Whether agent is complete */
+  isComplete: boolean;
+  /** Final result if complete */
+  result?: unknown;
+  /** Error if failed */
+  error?: Error;
+  /** Custom state data */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Record of a tool call.
+ */
+export interface ToolCallRecord {
+  /** Tool call ID */
+  id: string;
+  /** Tool name */
+  name: string;
+  /** Tool input payload */
+  input: Record<string, unknown>;
+  /** Tool result */
+  result?: unknown;
+  /** Error if failed */
+  error?: string;
+  /** Timestamp */
+  timestamp: number;
+}
+
+/**
+ * Agent execution context.
+ */
+export interface AgentContext {
+  /** User ID */
+  userId?: string;
+  /** Session ID */
+  sessionId?: string;
+  /** Request ID for tracing */
+  requestId?: string;
+  /** Abort signal */
+  abortSignal?: AbortSignal;
+  /** Additional context data */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Agent execution options.
+ */
+export interface AgentExecutionOptions {
+  /** Language model to use */
+  model: SDKLanguageModel;
+  /** Tools available to the agent */
+  tools?: Record<string, SDKTool>;
+  /** Initial messages */
+  messages?: AgentMessage[];
+  /** Execution context */
+  context?: AgentContext;
+  /** Callback on each step */
+  onStep?: (state: BaseAgentState) => void | Promise<void>;
+  /** Callback on tool call */
+  onToolCall?: (call: ToolCallRecord) => void | Promise<void>;
+  /** Callback on completion */
+  onComplete?: (state: BaseAgentState) => void | Promise<void>;
+}
+
+/**
+ * Agent interface.
+ */
+export interface Agent {
+  /** Agent configuration */
+  readonly config: AgentConfig;
+  /** Execute the agent */
+  execute(prompt: string, options: AgentExecutionOptions): Promise<BaseAgentState>;
+  /** Stream execution */
+  stream?(prompt: string, options: AgentExecutionOptions): AsyncGenerator<BaseAgentState>;
+}
+
+/**
+ * Agent factory function type.
+ */
+export type AgentFactory<TConfig extends AgentConfig = AgentConfig> = (config: TConfig) => Agent;
+
+/**
+ * Stop condition for agent loops.
+ */
+export type StopCondition = (state: BaseAgentState) => boolean;
+
+/**
+ * Default stop conditions.
+ */
+export const StopConditions = {
+  /** Stop after max iterations */
+  maxIterations:
+    (max: number): StopCondition =>
+    state =>
+      state.iteration >= max,
+
+  /**
+   * Stop when no tool calls were made in the last iteration.
+   * @remarks Requires the agent loop to set `state.metadata.lastToolCallCount`
+   * to `state.toolCalls.length` before each iteration. See `executeAgentStep` in factory.ts.
+   */
+  noToolCalls: (): StopCondition => state => {
+    // Only stop if we've completed at least one iteration and the last iteration had no tool calls
+    // We check this by comparing current tool calls count with the count from before the last iteration
+    // Since we check before each iteration, we need iteration > 0 to have completed at least one iteration
+    if (state.iteration === 0) {
+      return false;
+    }
+    // Check if the last iteration added any tool calls by comparing with previous count
+    // We store the previous tool call count in metadata to track this
+    const previousToolCallCount = (state.metadata.lastToolCallCount as number) ?? 0;
+    return state.toolCalls.length === previousToolCallCount;
+  },
+
+  /** Stop on specific tool call */
+  onToolCall:
+    (toolName: string): StopCondition =>
+    state => {
+      return state.toolCalls.some(call => call.name === toolName);
+    },
+
+  /** Stop on error */
+  onError: (): StopCondition => state => Boolean(state.error),
+
+  /** Combine multiple conditions with OR */
+  any:
+    (...conditions: StopCondition[]): StopCondition =>
+    state => {
+      return conditions.some(cond => cond(state));
+    },
+
+  /** Combine multiple conditions with AND */
+  all:
+    (...conditions: StopCondition[]): StopCondition =>
+    state => {
+      return conditions.every(cond => cond(state));
+    },
+};