@od-oneapp/ai-platform 0.1.0

package/src/agents/tools/index.ts

@@ -0,0 +1,291 @@
+/**
+ * @fileoverview Default agent tools
+ *
+ * Provides default tools for AI agents including knowledge base search,
+ * escalation, and audit logging. Also includes utilities for creating
+ * execution signals.
+ *
+ * @module @od-oneapp/ai-platform/agents/tools
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import { z } from 'zod/v4';
+
+import { complianceSignalSchema } from '../../governance/compliance/schemas';
+import { rerank, tool } from '../../shared';
+
+import type { ComplianceSignal } from '../../governance/compliance/schemas';
+import type { SDKTool as Tool } from '../../shared';
+
+
+
+/**
+ * Tool call information for execution signals.
+ */
+interface ToolCall {
+  /** Tool call ID */
+  id: string;
+  /** Name of the tool being called */
+  toolName: string;
+  /** Input arguments for the tool */
+  input: unknown;
+}
+
+/**
+ * Knowledge base entry structure.
+ */
+interface KnowledgeBaseEntry {
+  readonly id: string;
+  readonly title: string;
+  readonly snippet: string;
+}
+
+/**
+ * Knowledge base search result.
+ */
+interface KnowledgeBaseResult {
+  readonly query: string;
+  readonly results: Array<{
+    id: string;
+    score: number;
+    text: string;
+  }>;
+  readonly warning?: string;
+}
+
+/**
+ * Internal knowledge base for compliance and best practices.
+ * Used by the knowledgeBaseTool for searching compliance guidelines.
+ * @internal
+ */
+const KNOWLEDGE_BASE = [
+  {
+    id: 'kb-guardrails',
+    title: 'Guardrail Playbook',
+    snippet: 'All high risk guardrail violations must be escalated to compliance within 1 hour.',
+  },
+  {
+    id: 'kb-telemetry',
+    title: 'Telemetry Standards',
+    snippet: 'Every AI call must include telemetry metadata including risk levels and tool names.',
+  },
+  {
+    id: 'kb-rag',
+    title: 'RAG Quality Checks',
+    snippet: 'Use rerank() with topN <= 5 to keep prompts small and latency predictable.',
+  },
+];
+
+/**
+ * Schema for knowledge base search input.
+ */
+const knowledgeBaseInputSchema = z.object({
+  /** Search query (minimum 2 characters). */
+  query: z.string().min(2),
+  /** Number of results to return (1-5, default 3). */
+  topN: z.number().min(1).max(5).default(3),
+});
+
+/** Knowledge base search input type. */
+export type KnowledgeBaseInput = z.infer<typeof knowledgeBaseInputSchema>;
+
+/**
+ * Knowledge base search tool.
+ * Searches the internal compliance knowledge base using reranking.
+ * Falls back to simple text matching if reranking fails.
+ * @example
+ * ```ts
+ * const result = await knowledgeBaseTool.execute({ query: 'guardrail', topN: 2 });
+ * console.log(result.results[0].text);
+ * ```
+ */
+export const knowledgeBaseTool = tool({
+  description: 'Searches the internal compliance knowledge base and returns ranked snippets.',
+  inputSchema: knowledgeBaseInputSchema,
+  execute: async ({ query, topN }: KnowledgeBaseInput): Promise<KnowledgeBaseResult> => {
+    try {
+      // Type assertion needed for experimental rerank API model parameter
+      type RerankModel = Parameters<typeof rerank>[0]['model'];
+      const rerankModel = 'openai:rerank-v1' as unknown as RerankModel;
+
+      const result = await rerank({
+        model: rerankModel,
+        documents: KNOWLEDGE_BASE.map((document: KnowledgeBaseEntry) => ({
+          id: document.id,
+          text: `${document.title}: ${document.snippet}`,
+        })),
+        query,
+        topN,
+        experimental_telemetry: {
+          isEnabled: true,
+          functionId: 'knowledge-base-rerank',
+          metadata: { queryLength: query.length },
+        },
+      });
+
+      return {
+        query,
+        results: result.rerankedDocuments.slice(0, topN).map((entry: any, index) => ({
+          id: entry.id ?? `kb-${index}`,
+          score: typeof entry.score === 'number' ? entry.score : 0,
+          text: entry.text,
+        })),
+      };
+    } catch (error) {
+      const fallback = KNOWLEDGE_BASE.filter((document: KnowledgeBaseEntry) =>
+        document.snippet.toLowerCase().includes(query.toLowerCase()),
+      ).slice(0, topN);
+
+      return {
+        query,
+        results: fallback.map((document: KnowledgeBaseEntry, index: number) => ({
+          id: document.id ?? `fallback-${index}`,
+          score: 0,
+          text: `${document.title}: ${document.snippet}`,
+        })),
+        warning: error instanceof Error ? error.message : String(error),
+      };
+    }
+  },
+});
+
+/**
+ * Schema for escalation ticket input.
+ */
+const escalateInputSchema = z.object({
+  /** Ticket summary (minimum 10 characters). */
+  summary: z.string().min(10),
+  /** Ticket system to use. */
+  ticketSystem: z.enum(['jira', 'pagerduty', 'service-now']).default('jira'),
+  /** Severity level. */
+  severity: z.enum(['low', 'medium', 'high']).default('medium'),
+});
+
+/** Escalation input type. */
+export type EscalateInput = z.infer<typeof escalateInputSchema>;
+
+/**
+ * Escalation tool for creating compliance tickets.
+ * Requires human approval for medium and high severity tickets.
+ * @example
+ * ```ts
+ * const ticket = await escalateTool.execute({
+ *   summary: 'User requested PII export',
+ *   ticketSystem: 'jira',
+ *   severity: 'high',
+ * });
+ * ```
+ */
+export const escalateTool = tool({
+  description: 'Creates a compliance escalation ticket that requires human approval.',
+  inputSchema: escalateInputSchema,
+  needsApproval: (input: EscalateInput) => input.severity !== 'low',
+  execute: async (input: EscalateInput) => ({
+    // Node.js 22+: Use randomUUID() for secure ticket IDs
+    ticketId: `${input.ticketSystem}-${randomUUID().slice(0, 8)}`,
+    ...input,
+    createdAt: new Date().toISOString(),
+  }),
+});
+
+/**
+ * Schema for audit log input.
+ */
+const auditLogInputSchema = z.object({
+  runId: z.string(),
+  toolCalls: z.array(
+    z.object({
+      id: z.string(),
+      toolName: z.string(),
+      approved: z.boolean().optional(),
+      payload: z.record(z.string(), z.unknown()).optional(),
+    }),
+  ),
+});
+
+/**
+ * Audit logging tool for compliance tracking.
+ * Writes structured audit log entries and returns compliance receipts.
+ * @example
+ * ```ts
+ * const receipt = await auditLogTool.execute({
+ *   runId: 'run-1',
+ *   toolCalls: [{ id: 'call-1', toolName: 'knowledgeBase' }],
+ * });
+ * ```
+ */
+export const auditLogTool = tool({
+  description: 'Writes a structured audit log entry and returns a compliance receipt.',
+  inputSchema: auditLogInputSchema,
+  execute: async ({
+    runId,
+    toolCalls,
+  }: {
+    runId: string;
+    toolCalls: Array<{
+      id: string;
+      toolName: string;
+      approved?: boolean;
+      payload?: Record<string, unknown>;
+    }>;
+  }) => ({
+    receiptId: randomUUID(),
+    runId,
+    totalTools: toolCalls.length,
+    createdAt: new Date().toISOString(),
+  }),
+});
+
+/**
+ * Default tools available to all agents.
+ * Includes knowledge base search, escalation, and audit logging.
+ * @example
+ * ```ts
+ * const tools = Object.keys(defaultTools);
+ * // ['knowledgeBase', 'escalate', 'auditLog']
+ * ```
+ */
+export const defaultTools: Record<string, Tool> = {
+  knowledgeBase: knowledgeBaseTool,
+  escalate: escalateTool,
+  auditLog: auditLogTool,
+};
+
+/** Type for default toolset. */
+export type DefaultToolset = typeof defaultTools;
+
+export * from './mcp';
+
+/**
+ * Creates a compliance signal for tool execution events.
+ * Used to track tool calls throughout agent execution for audit purposes.
+ *
+ * @param toolCall - Tool call information.
+ * @param type - Signal type (tool.executed, tool.awaiting-approval, or tool.denied).
+ * @param runId - Agent run identifier.
+ * @returns Compliance signal object.
+ * @example
+ * ```ts
+ * const signal = createExecutionSignal(
+ *   { id: 'call-123', toolName: 'escalate', input: { summary: 'Issue' } },
+ *   'tool.executed',
+ *   'run-456'
+ * );
+ * ```
+ */
+export const createExecutionSignal = (
+  toolCall: ToolCall,
+  type: ComplianceSignal['type'],
+  runId: string,
+): ComplianceSignal =>
+  complianceSignalSchema.parse({
+    id: randomUUID(),
+    type,
+    message: `${toolCall.toolName} (${toolCall.id}) ${type.replace('tool.', '')}`,
+    runId,
+    timestamp: new Date().toISOString(),
+  });
+
+/** Tool execution signal type. */
+export type ToolExecutionSignal = ReturnType<typeof createExecutionSignal>;

package/src/agents/tools/mcp.ts

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview Model Context Protocol (MCP) tool integration
+ *
+ * Provides utilities for connecting to MCP servers and integrating their tools
+ * into AI agents. Supports SSE, HTTP, and stdio transport types.
+ *
+ * @module @od-oneapp/ai-platform/agents/tools/mcp
+ */
+
+import {
+  createMCPClient,
+  Experimental_StdioMCPTransport,
+  type SDKOAuthClientProvider,
+  type SDKToolSet,
+} from '../../shared';
+
+import type { IOType } from 'node:child_process';
+import type { Stream } from 'node:stream';
+
+/**
+ * SSE (Server-Sent Events) transport configuration for MCP.
+ */
+export type McpSseTransport = {
+  /** Transport type. Must be 'sse'. */
+  type: 'sse';
+  /** SSE endpoint URL. */
+  url: string;
+  /** Optional HTTP headers for the SSE connection. */
+  headers?: Record<string, string>;
+  /** Optional OAuth provider for protected MCP servers. */
+  authProvider?: SDKOAuthClientProvider;
+};
+
+/**
+ * HTTP transport configuration for MCP.
+ */
+export type McpHttpTransport = {
+  /** Transport type. Must be 'http'. */
+  type: 'http';
+  /** HTTP endpoint URL. */
+  url: string;
+  /** Optional HTTP headers for the connection. */
+  headers?: Record<string, string>;
+  /** Optional session identifier for server-side routing. */
+  sessionId?: string;
+  /** Optional OAuth provider for protected MCP servers. */
+  authProvider?: SDKOAuthClientProvider;
+};
+
+/**
+ * Stdio transport configuration for MCP.
+ */
+export type McpStdioTransport = {
+  /** Transport type. Must be 'stdio'. */
+  type: 'stdio';
+  /** Command to execute for stdio transport. */
+  command?: string;
+  /** Command arguments. */
+  args?: string[];
+  /** Environment variables for the process. */
+  env?: Record<string, string>;
+  /** Working directory for the MCP server process. */
+  cwd?: string;
+  /** stderr destination for the MCP server. */
+  stderr?: IOType | Stream | number;
+};
+
+/** MCP transport type (SSE, HTTP, or stdio). */
+export type McpTransport = McpSseTransport | McpHttpTransport | McpStdioTransport;
+
+/**
+ * Options for connecting to an MCP toolset.
+ */
+export interface McpToolsetOptions {
+  /** Transport configuration (SSE, HTTP, or stdio). */
+  transport: McpTransport;
+  /** Whether tools require approval before execution. */
+  approval?: boolean;
+}
+
+/**
+ * Connected MCP toolset with tools and cleanup function.
+ */
+export interface ConnectedMcpToolset {
+  /** Tools available from the MCP server. */
+  tools: SDKToolSet;
+  /** Function to close the MCP connection and cleanup resources. */
+  close: () => Promise<void>;
+}
+
+/**
+ * Connects to an MCP server and returns its tools.
+ * Uses createMCPClient from the AI SDK MCP package.
+ *
+ * @param options - MCP connection options.
+ * @returns Connected toolset with tools and close function.
+ * @example
+ * ```ts
+ * const toolset = await connectMcpToolset({
+ *   transport: { type: 'sse', url: 'https://mcp.example.com/sse' },
+ *   approval: true
+ * });
+ *
+ * // Use tools
+ * const result = await toolset.tools.myTool.execute({ input: 'data' });
+ *
+ * // Cleanup
+ * await toolset.close();
+ * ```
+ * @example
+ * ```ts
+ * const stdioToolset = await connectMcpToolset({
+ *   transport: { type: 'stdio', command: 'mcp-server', args: ['--profile', 'prod'] },
+ * });
+ * ```
+ */
+export const connectMcpToolset = async (
+  options: McpToolsetOptions,
+): Promise<ConnectedMcpToolset> => {
+  const baseEnv = Object.entries(process.env).reduce<Record<string, string>>(
+    (acc, [key, value]) => {
+      if (typeof value === 'string') {
+        acc[key] = value;
+      }
+      return acc;
+    },
+    {},
+  );
+
+  const transport =
+    options.transport.type === 'stdio'
+      ? new Experimental_StdioMCPTransport({
+          command: options.transport.command ?? 'node',
+          args: options.transport.args ?? [],
+          env: options.transport.env ? { ...baseEnv, ...options.transport.env } : baseEnv,
+          cwd: options.transport.cwd,
+          stderr: options.transport.stderr,
+        })
+      : {
+          type: options.transport.type,
+          url: options.transport.url,
+          headers:
+            options.transport.type === 'http' && options.transport.sessionId
+              ? {
+                  ...options.transport.headers,
+                  'x-mcp-session-id': options.transport.sessionId,
+                }
+              : options.transport.headers,
+          authProvider: options.transport.authProvider,
+        };
+
+  const client = await createMCPClient({ transport });
+
+  let tools: SDKToolSet;
+  try {
+    tools = await client.tools();
+  } catch (error) {
+    await client.close();
+    throw new Error(
+      `Failed to retrieve tools from MCP server: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  // Apply approval flag to tools if needed
+  const processedTools: SDKToolSet = {};
+  try {
+    for (const name of Object.keys(tools)) {
+      const toolDefinition = tools[name];
+      if (!toolDefinition) {
+        continue;
+      }
+      processedTools[name] = {
+        ...toolDefinition,
+        needsApproval: options.approval ?? toolDefinition.needsApproval,
+      };
+    }
+  } catch (error) {
+    await client.close();
+    throw error;
+  }
+
+  return {
+    tools: processedTools,
+    close: async () => {
+      await client.close();
+    },
+  };
+};

package/src/agents/triage/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Triage agent for routing requests.
+ * @module @od-oneapp/ai-platform/agents/triage
+ */
+
+export * from './triage-agent';