@od-oneapp/ai-platform 0.1.0

package/src/shared/__tests__/schemas.test.ts

@@ -0,0 +1,317 @@
+/**
+ * @fileoverview schemas.test.ts — tests for domain schemas split across modules.
+ */
+
+import { describe, expect } from 'vitest';
+
+import {
+  agentCitationSchema,
+  agentStructuredOutputSchema,
+  agentToolCallSchema,
+  type AgentCitation,
+  type AgentStructuredOutput,
+  type AgentToolCall,
+  type RiskLevel,
+} from '../../agents/base/schemas';
+import {
+  riskLevels,
+  complianceSignalSchema,
+  type ComplianceSignal,
+} from '../../governance/compliance/schemas';
+
+describe('schemas', () => {
+  describe('riskLevels', () => {
+    it('contains expected risk levels', () => {
+      expect(riskLevels).toStrictEqual(['low', 'medium', 'high']);
+    });
+  });
+
+  describe('agentToolCallSchema', () => {
+    it('validates complete tool call', () => {
+      const validToolCall = {
+        id: 'tool_123',
+        toolName: 'searchDatabase',
+        input: { query: 'test' },
+        approved: true,
+        durationMs: 150,
+        resultSummary: 'Found 10 results',
+      };
+
+      const result = agentToolCallSchema.safeParse(validToolCall);
+      expect(result.success).toBe(true);
+    });
+
+    it('validates minimal tool call', () => {
+      const minimalToolCall = {
+        id: 'tool_456',
+        toolName: 'calculateSum',
+        input: [1, 2, 3],
+      };
+
+      const result = agentToolCallSchema.safeParse(minimalToolCall);
+      expect(result.success).toBe(true);
+    });
+
+    it('rejects missing required fields', () => {
+      expect(agentToolCallSchema.safeParse({ toolName: 'test', input: {} }).success).toBe(false);
+      expect(agentToolCallSchema.safeParse({ id: '123', input: {} }).success).toBe(false);
+      expect(agentToolCallSchema.safeParse({ id: '123', toolName: 'test' }).success).toBe(false);
+    });
+
+    it('accepts any input type', () => {
+      const inputs = ['string', 123, { obj: true }, ['array'], null];
+      for (const input of inputs) {
+        const result = agentToolCallSchema.safeParse({ id: '1', toolName: 'test', input });
+        expect(result.success).toBe(true);
+      }
+    });
+
+    it('validates durationMs constraints', () => {
+      expect(
+        agentToolCallSchema.safeParse({ id: '1', toolName: 'test', input: {}, durationMs: 0 })
+          .success,
+      ).toBe(true);
+      expect(
+        agentToolCallSchema.safeParse({ id: '1', toolName: 'test', input: {}, durationMs: 100 })
+          .success,
+      ).toBe(true);
+      expect(
+        agentToolCallSchema.safeParse({ id: '1', toolName: 'test', input: {}, durationMs: -1 })
+          .success,
+      ).toBe(false);
+    });
+  });
+
+  describe('agentCitationSchema', () => {
+    it('validates complete citation', () => {
+      const citation = {
+        id: 'cite_1',
+        title: 'Research Paper',
+        url: 'https://example.com/paper',
+        snippet: 'Paper content',
+        score: 0.95,
+      };
+
+      expect(agentCitationSchema.safeParse(citation).success).toBe(true);
+    });
+
+    it('validates minimal citation', () => {
+      const citation = {
+        id: 'cite_2',
+        title: 'Article',
+        snippet: 'Article content',
+      };
+
+      expect(agentCitationSchema.safeParse(citation).success).toBe(true);
+    });
+
+    it('validates URL format', () => {
+      const validUrls = [
+        'https://example.com',
+        'http://example.com/path',
+        'https://sub.example.com/path?query=1',
+      ];
+
+      for (const url of validUrls) {
+        const citation = { id: 'cite', title: 'Title', url, snippet: 'Content' };
+        expect(agentCitationSchema.safeParse(citation).success).toBe(true);
+      }
+
+      const invalidCitation = { id: 'cite', title: 'Title', url: 'not-a-url', snippet: 'Content' };
+      expect(agentCitationSchema.safeParse(invalidCitation).success).toBe(false);
+    });
+
+    it('validates score range', () => {
+      expect(
+        agentCitationSchema.safeParse({ id: '1', title: 'T', snippet: 'S', score: 0 }).success,
+      ).toBe(true);
+      expect(
+        agentCitationSchema.safeParse({ id: '1', title: 'T', snippet: 'S', score: 0.5 }).success,
+      ).toBe(true);
+      expect(
+        agentCitationSchema.safeParse({ id: '1', title: 'T', snippet: 'S', score: 1 }).success,
+      ).toBe(true);
+      expect(
+        agentCitationSchema.safeParse({ id: '1', title: 'T', snippet: 'S', score: -0.1 }).success,
+      ).toBe(false);
+      expect(
+        agentCitationSchema.safeParse({ id: '1', title: 'T', snippet: 'S', score: 1.1 }).success,
+      ).toBe(false);
+    });
+  });
+
+  describe('agentStructuredOutputSchema', () => {
+    it('validates complete structured output', () => {
+      const output: AgentStructuredOutput = {
+        runId: 'run_123',
+        summary: 'Task completed',
+        decision: 'Approve',
+        riskLevel: 'low',
+        toolCalls: [{ id: 'tool_1', toolName: 'check', input: {}, approved: true }],
+        citations: [{ id: 'cite_1', title: 'Doc', snippet: 'Text' }],
+        notes: ['Note 1'],
+        tags: ['tag1'],
+      };
+
+      expect(agentStructuredOutputSchema.safeParse(output).success).toBe(true);
+    });
+
+    it('validates minimal output', () => {
+      const minimal = {
+        runId: 'run_456',
+        summary: 'Done',
+        decision: 'Accept',
+        riskLevel: 'medium',
+        toolCalls: [],
+        citations: [],
+      };
+
+      expect(agentStructuredOutputSchema.safeParse(minimal).success).toBe(true);
+    });
+
+    it('validates all risk levels', () => {
+      for (const riskLevel of riskLevels) {
+        const output = {
+          runId: 'run_test',
+          summary: 'Test',
+          decision: 'Test',
+          riskLevel,
+          toolCalls: [],
+          citations: [],
+        };
+        expect(agentStructuredOutputSchema.safeParse(output).success).toBe(true);
+      }
+    });
+
+    it('rejects invalid risk level', () => {
+      const invalid = {
+        runId: 'run_789',
+        summary: 'Test',
+        decision: 'Test',
+        riskLevel: 'critical',
+        toolCalls: [],
+        citations: [],
+      };
+
+      expect(agentStructuredOutputSchema.safeParse(invalid).success).toBe(false);
+    });
+
+    it('requires all mandatory fields', () => {
+      const base = {
+        runId: 'r',
+        summary: 's',
+        decision: 'd',
+        riskLevel: 'low',
+        toolCalls: [],
+        citations: [],
+      };
+
+      expect(agentStructuredOutputSchema.safeParse({ ...base, runId: undefined }).success).toBe(
+        false,
+      );
+      expect(agentStructuredOutputSchema.safeParse({ ...base, summary: undefined }).success).toBe(
+        false,
+      );
+      expect(agentStructuredOutputSchema.safeParse({ ...base, decision: undefined }).success).toBe(
+        false,
+      );
+      expect(agentStructuredOutputSchema.safeParse({ ...base, toolCalls: undefined }).success).toBe(
+        false,
+      );
+      expect(agentStructuredOutputSchema.safeParse({ ...base, citations: undefined }).success).toBe(
+        false,
+      );
+    });
+
+    it('validates nested toolCalls and citations', () => {
+      const output = {
+        runId: 'run_nested',
+        summary: 'Multiple items',
+        decision: 'Proceed',
+        riskLevel: 'medium',
+        toolCalls: [
+          { id: 'tool_1', toolName: 'search', input: {} },
+          { id: 'tool_2', toolName: 'analyze', input: {} },
+        ],
+        citations: [
+          { id: 'cite_1', title: 'Source 1', snippet: 'Text 1' },
+          { id: 'cite_2', title: 'Source 2', snippet: 'Text 2' },
+        ],
+      };
+
+      expect(agentStructuredOutputSchema.safeParse(output).success).toBe(true);
+    });
+
+    it('validates optional fields', () => {
+      const withOptional = {
+        runId: 'run_opt',
+        summary: 'With optional',
+        decision: 'Approved',
+        riskLevel: 'low',
+        toolCalls: [],
+        citations: [],
+        notes: ['Note 1', 'Note 2'],
+        tags: ['tag1', 'tag2'],
+      };
+
+      expect(agentStructuredOutputSchema.safeParse(withOptional).success).toBe(true);
+    });
+  });
+
+  describe('complianceSignalSchema', () => {
+    it('validates a complete compliance signal', () => {
+      const signal: ComplianceSignal = {
+        id: 'sig-1',
+        type: 'tool.executed',
+        message: 'auditLog executed',
+        runId: 'run-123',
+        timestamp: new Date().toISOString(),
+      };
+
+      expect(complianceSignalSchema.safeParse(signal).success).toBe(true);
+    });
+  });
+
+  describe('typeScript types', () => {
+    it('riskLevel type matches schema', () => {
+      const low: RiskLevel = 'low';
+      const medium: RiskLevel = 'medium';
+      const high: RiskLevel = 'high';
+
+      expect([low, medium, high]).toStrictEqual(['low', 'medium', 'high']);
+    });
+
+    it('agentToolCall type matches schema', () => {
+      const toolCall: AgentToolCall = {
+        id: 'tool_123',
+        toolName: 'test',
+        input: {},
+      };
+
+      expect(agentToolCallSchema.safeParse(toolCall).success).toBe(true);
+    });
+
+    it('agentCitation type matches schema', () => {
+      const citation: AgentCitation = {
+        id: 'cite_123',
+        title: 'Title',
+        snippet: 'Snippet',
+      };
+
+      expect(agentCitationSchema.safeParse(citation).success).toBe(true);
+    });
+
+    it('agentStructuredOutput type matches schema', () => {
+      const output: AgentStructuredOutput = {
+        runId: 'run_123',
+        summary: 'Summary',
+        decision: 'Decision',
+        riskLevel: 'low',
+        toolCalls: [],
+        citations: [],
+      };
+
+      expect(agentStructuredOutputSchema.safeParse(output).success).toBe(true);
+    });
+  });
+});

package/src/shared/ai-runtime.ts

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview Custom OneApp runtime functions.
+ *
+ * SDK runtime re-exports live in ./sdk-runtime.ts.
+ * This file contains ONLY custom OneApp functions that operate on SDK types.
+ *
+ * To add a new helper: add the function here with JSDoc + explicit return type.
+ */
+
+import type { SDKLanguageModelUsage, SDKLanguageModel } from './sdk-types';
+
+// ---------------------------------------------------------------------------
+// CUSTOM TYPES — co-located with the functions that use them
+// ---------------------------------------------------------------------------
+
+/**
+ * TokenUsage type for tracking token consumption.
+ * Uses familiar promptTokens/completionTokens naming for backwards compatibility.
+ *
+ * Note: SDK uses inputTokens/outputTokens. Use convertFromSDKUsage() to convert.
+ */
+export interface TokenUsage {
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly totalTokens: number;
+}
+
+/** Reference to a language model — ID string or model instance. */
+export type ModelRef = string | SDKLanguageModel;
+
+// ---------------------------------------------------------------------------
+// TOKEN USAGE HELPERS
+// ---------------------------------------------------------------------------
+
+/** Convert SDK LanguageModelUsage to OneApp TokenUsage. */
+export function convertFromSDKUsage(usage: SDKLanguageModelUsage): TokenUsage {
+  const promptTokens = usage.inputTokens ?? 0;
+  const completionTokens = usage.outputTokens ?? 0;
+  return {
+    promptTokens,
+    completionTokens,
+    totalTokens: promptTokens + completionTokens,
+  };
+}
+
+/** Create an empty TokenUsage object. */
+export function createEmptyUsage(): TokenUsage {
+  return {
+    promptTokens: 0,
+    completionTokens: 0,
+    totalTokens: 0,
+  };
+}
+
+/** Add two TokenUsage objects together. */
+export function addUsage(a: TokenUsage, b: TokenUsage | undefined): TokenUsage {
+  if (!b) return a;
+  return {
+    promptTokens: a.promptTokens + b.promptTokens,
+    completionTokens: a.completionTokens + b.completionTokens,
+    totalTokens: a.totalTokens + b.totalTokens,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// MODEL REFERENCE HELPERS
+// ---------------------------------------------------------------------------
+
+/** Resolves a ModelRef to a model ID string. */
+export function resolveModelId(model: ModelRef): string {
+  if (typeof model === 'string') {
+    return model;
+  }
+  return model.modelId;
+}
+
+/** Runtime guard for ModelRef values. */
+export function isModelRef(value: unknown): value is ModelRef {
+  if (typeof value === 'string') {
+    return value.trim().length > 0;
+  }
+
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const candidate = value as { modelId?: unknown };
+  return typeof candidate.modelId === 'string' && candidate.modelId.trim().length > 0;
+}
+
+// generateId is re-exported from the Vercel AI SDK via sdk-runtime.ts.
+// Use generateUniqueId() from this file when you need the full options API.
+
+// ---------------------------------------------------------------------------
+// ID GENERATION
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates a unique identifier.
+ * Uses crypto.randomUUID() when available (Node.js 14.17+, modern browsers),
+ * otherwise falls back to timestamp + random for local correlation IDs.
+ * Note: Fallback is not suitable for security-sensitive contexts or high-frequency distributed scenarios.
+ */
+export function generateUniqueId(options: { requireSecure?: boolean } = {}): string {
+  const requireSecure = options.requireSecure ?? true;
+
+  if (typeof crypto !== 'undefined') {
+    if (crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+
+    if (crypto.getRandomValues) {
+      const bytes = new Uint8Array(16);
+      crypto.getRandomValues(bytes);
+      const byte6 = bytes[6] ?? 0;
+      const byte8 = bytes[8] ?? 0;
+      bytes[6] = (byte6 & 0x0f) | 0x40;
+      bytes[8] = (byte8 & 0x3f) | 0x80;
+
+      const toHex = (value: number): string => value.toString(16).padStart(2, '0');
+      const byte = (index: number): number => bytes[index] ?? 0;
+      return [
+        `${toHex(byte(0))}${toHex(byte(1))}${toHex(byte(2))}${toHex(byte(3))}`,
+        `${toHex(byte(4))}${toHex(byte(5))}`,
+        `${toHex(byte(6))}${toHex(byte(7))}`,
+        `${toHex(byte(8))}${toHex(byte(9))}`,
+        `${toHex(byte(10))}${toHex(byte(11))}${toHex(byte(12))}${toHex(byte(13))}${toHex(byte(14))}${toHex(byte(15))}`,
+      ].join('-');
+    }
+  }
+
+  if (requireSecure) {
+    throw new Error('Secure random generator unavailable for generateId');
+  }
+
+  const timestamp = Date.now().toString(36);
+  const entropy = `${timestamp}-${timestamp.slice(-4)}`;
+  return entropy;
+}

package/src/shared/ai-types.ts

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Custom types and derived SDK types for ai-platform.
+ *
+ * This file contains ONLY:
+ * - Derived SDK types (computed from SDK types, can't be one-liner re-exports)
+ * - Custom OneApp types (message roles, finish reasons, tool states, etc.)
+ *
+ * Sibling files:
+ * sdk-types.ts   — SDK type re-exports (one line per type, SDK prefix)
+ * sdk-runtime.ts — SDK runtime re-exports (functions, classes, constants)
+ * ai-runtime.ts  — Custom runtime functions + co-located types (TokenUsage, ModelRef)
+ */
+
+// ---------------------------------------------------------------------------
+// DERIVED SDK TYPES (computed from SDK types, can't be direct re-exports)
+// ---------------------------------------------------------------------------
+
+import type {
+  SDKLanguageModelV3Middleware,
+  SDKTextPart,
+  SDKFilePart,
+  SDKImagePart,
+  SDKToolCallPart,
+  SDKToolResultPart,
+  SDKToolApprovalResponse,
+} from './sdk-types';
+
+/** Extracted output type from a tool result part. */
+export type SDKToolResultOutput = SDKToolResultPart['output'];
+
+/** Middleware wrapGenerate parameter type. */
+export type SDKWrapGenerateArgs = Parameters<
+  NonNullable<SDKLanguageModelV3Middleware['wrapGenerate']>
+>[0];
+
+/** Middleware wrapStream parameter type. */
+export type SDKWrapStreamArgs = Parameters<
+  NonNullable<SDKLanguageModelV3Middleware['wrapStream']>
+>[0];
+
+/** Middleware transformParams parameter type. */
+export type SDKTransformParamsArgs = Parameters<
+  NonNullable<SDKLanguageModelV3Middleware['transformParams']>
+>[0];
+
+/** Union of all SDK message part types. */
+export type SDKMessagePart =
+  | SDKTextPart
+  | SDKFilePart
+  | SDKImagePart
+  | SDKToolCallPart
+  | SDKToolResultPart
+  | SDKToolApprovalResponse;
+
+// ---------------------------------------------------------------------------
+// TOOL INVOCATION STATES (SDK-Aligned)
+// ---------------------------------------------------------------------------
+
+/** SDK-aligned tool invocation states for UI rendering. */
+export type SDKToolInvocationState = 'partial-call' | 'call' | 'result';
+
+/** Tool shimmer states for UI loading indicators (OneApp-specific). */
+export type ToolShimmerState = 'pending' | 'loading' | 'success' | 'error';
+
+// ---------------------------------------------------------------------------
+// MESSAGE ROLE TYPES (SDK-Aligned)
+// ---------------------------------------------------------------------------
+
+/** SDK-aligned message role types. */
+export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+
+/** Core message roles (without 'tool'). */
+export type CoreMessageRole = 'user' | 'assistant' | 'system';
+
+/** Basic message interface aligned with SDK patterns. */
+export interface BaseMessage {
+  readonly role: MessageRole;
+  readonly content: string;
+}
+
+/** Core message interface (without tool role). */
+export interface CoreMessage {
+  readonly role: CoreMessageRole;
+  readonly content: string;
+}
+
+// ---------------------------------------------------------------------------
+// FINISH REASON TYPES (SDK-Aligned)
+// ---------------------------------------------------------------------------
+
+/** Finish reason for a single generation step. */
+export type StepFinishReason = 'stop' | 'tool-calls' | 'length' | 'content-filter';
+
+/** Finish reason for complete agent execution. */
+export type AgentFinishReason = 'stop' | 'max-steps' | 'abort';
+
+// ---------------------------------------------------------------------------
+// COMPLIANCE & RISK (Cross-cutting lightweight types)
+// ---------------------------------------------------------------------------
+// Full Zod-validated schemas live in governance/compliance/schemas.ts.
+// These lightweight types are for cross-cutting use across agents, tools, etc.
+
+/**
+ * Risk level for compliance-aware agent orchestration.
+ * Determines loop budgets, tool access, and guardrail strictness.
+ */
+export type RiskLevel = 'low' | 'medium' | 'high';
+
+/**
+ * Compliance signal types emitted during agent execution.
+ */
+export type ComplianceSignalType =
+  | 'guardrail.blocked'
+  | 'guardrail.sanitized'
+  | 'tool.awaiting-approval'
+  | 'tool.executed'
+  | 'tool.denied'
+  | 'loop.started'
+  | 'loop.completed'
+  | 'loop.exhausted'
+  | 'loop.error'
+  | 'loop.timeout'
+  | 'loop.budget_exceeded'
+  | 'loop.approval_required';
+
+/**
+ * Signal emitted during agent execution for compliance tracking.
+ */
+export interface ComplianceSignal {
+  type: ComplianceSignalType;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}

package/src/shared/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Shared SDK barrel — canonical import point for all consumers.
+ *
+ * All consumer files import SDK types and functions from '../../shared' (this file).
+ * Never import from individual sub-files directly.
+ *
+ * File layout:
+ * sdk-types.ts   — SDK type re-exports (one line per type, SDK prefix)
+ * sdk-runtime.ts — SDK runtime re-exports (functions, classes, constants)
+ * ai-types.ts    — Derived SDK types + custom OneApp types
+ * ai-runtime.ts  — Custom runtime functions (TokenUsage, ModelRef, helpers)
+ *
+ * Domain schemas live with their domains:
+ * agents/base/schemas.ts          — Agent output schemas
+ * governance/compliance/schemas.ts — Compliance signals + RiskLevel
+ *
+ * @module @od-oneapp/ai-platform/shared
+ */
+
+/** SDK type aliases (SDKLanguageModel, SDKTool, etc.). */
+export * from './sdk-types';
+
+/** SDK runtime functions (generateText, streamText, tool, etc.). */
+export * from './sdk-runtime';
+
+/** Derived SDK types + custom OneApp types (MessageRole, BaseMessage, etc.). */
+export * from './ai-types';
+
+/** Custom runtime functions (convertFromSDKUsage, resolveModelId, etc.). */
+export * from './ai-runtime';