@od-oneapp/ai-platform 0.1.0

package/src/governance/policies/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview AI Agent Policies Module.
+ *
+ * Exports policy definitions for guardrails, loop controls, and telemetry settings
+ * that govern agent behavior and safety.
+ *
+ * @module @od-oneapp/ai-platform/policies
+ * @example
+ * ```ts
+ * import { applyDefaultGuardrails, resolveLoopPolicy } from "@od-oneapp/ai-platform/policies";
+ *
+ * const model = applyDefaultGuardrails(anthropic("claude-3-haiku"));
+ * const loopPolicy = resolveLoopPolicy({ riskLevel: "medium" });
+ * ```
+ */
+
+/**
+ * Guardrail policies for models (content filters, PII redaction).
+ * @example
+ * ```ts
+ * const guarded = applyDefaultGuardrails(model);
+ * ```
+ */
+export * from './guardrails';
+
+/**
+ * Loop control policies that enforce step budgets and tool availability.
+ * @example
+ * ```ts
+ * const loop = resolveLoopPolicy({ riskLevel: 'high', activeTools: ['auditLog'] });
+ * ```
+ */
+export * from './loop-controls';
+
+/**
+ * Telemetry defaults for AI SDK integrations.
+ * @example
+ * const telemetry = defaultTelemetry;
+ */
+export * from './telemetry';
+
+export type { ComplianceSignal, RiskLevel } from '../compliance/schemas';

package/src/governance/policies/loop-controls.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Loop control policies
+ *
+ * Provides risk-tiered loop policies that control agent execution behavior:
+ * - Low risk: 6 steps, auto tool selection
+ * - Medium risk: 4 steps, auto tool selection
+ * - High risk: 2 steps, escalation required
+ *
+ * @module @od-oneapp/ai-platform/policies/loop-controls
+ */
+
+import { stepCountIs } from '../../shared';
+
+import type { SDKStopCondition, SDKToolChoice, SDKToolSet } from '../../shared';
+import type { RiskLevel } from '../compliance/schemas';
+
+/**
+ * Loop policy configuration.
+ * Controls agent execution limits and tool selection behavior.
+ */
+export type LoopPolicy = {
+  /** Risk level this policy applies to. */
+  riskLevel: RiskLevel;
+  /** Stop condition for the agent loop. */
+
+  stopCondition: SDKStopCondition<SDKToolSet>;
+  /** Maximum number of steps allowed. */
+  maxSteps: number;
+  /** Tool choice strategy ('auto', 'required', or 'none'). */
+
+  toolChoice: SDKToolChoice<SDKToolSet> | undefined;
+  /** Optional list of active tool names to enable. */
+  activeTools?: string[];
+};
+
+/**
+ * Base loop policies for each risk level.
+ * Defines default step limits and tool selection strategies.
+ * @internal
+ */
+const BASE_LOOP_POLICIES: Record<RiskLevel, LoopPolicy> = {
+  low: {
+    riskLevel: 'low',
+    maxSteps: 6,
+    stopCondition: stepCountIs(6),
+    toolChoice: 'auto',
+    activeTools: undefined,
+  },
+  medium: {
+    riskLevel: 'medium',
+    maxSteps: 4,
+    stopCondition: stepCountIs(4),
+    toolChoice: 'auto',
+    activeTools: undefined,
+  },
+  high: {
+    riskLevel: 'high',
+    maxSteps: 2,
+    stopCondition: stepCountIs(2),
+    toolChoice: 'required',
+    activeTools: ['escalate'],
+  },
+};
+
+/**
+ * Resolves a loop policy for the given risk level.
+ * Merges base policy with optional overrides for tool choice and active tools.
+ *
+ * @param options - Policy resolution options.
+ * @param options.riskLevel - Risk level to resolve policy for.
+ * @param options.toolChoice - Optional tool choice override.
+ * @param options.activeTools - Optional active tools override.
+ * @returns Resolved loop policy with step limits, stop condition, and tool configuration.
+ * @remarks Base policies:
+ * - Low: 6 steps, auto tool choice
+ * - Medium: 4 steps, auto tool choice
+ * - High: 2 steps, required tool choice, only 'escalate' tool active
+ * Overrides take precedence over base policy values.
+ * @example
+ * ```ts
+ * const policy = resolveLoopPolicy({
+ *   riskLevel: 'medium',
+ *   activeTools: ['knowledgeBase', 'escalate']
+ * });
+ * ```
+ */
+export const resolveLoopPolicy = ({
+  riskLevel,
+  toolChoice,
+  activeTools,
+}: {
+  riskLevel: RiskLevel;
+
+  toolChoice?: SDKToolChoice<SDKToolSet>;
+  activeTools?: string[];
+}): LoopPolicy => {
+  const base = BASE_LOOP_POLICIES[riskLevel];
+  return {
+    ...base,
+    toolChoice: toolChoice ?? base.toolChoice,
+    activeTools: activeTools ?? base.activeTools,
+  };
+};
+
+/**
+ * Merges active tools from policy and requested tools.
+ * Combines policy-defined active tools with user-requested tools.
+ *
+ * @param policy - Loop policy containing active tools.
+ * @param requestedTools - Optional list of requested tool names.
+ * @returns Merged array of active tool names, or undefined if neither provided.
+ * @example
+ * ```ts
+ * const tools = mergeActiveTools(policy, ['customTool']);
+ * // Returns ['escalate', 'customTool'] if policy has 'escalate' in activeTools
+ * ```
+ */
+export const mergeActiveTools = (
+  policy: LoopPolicy,
+  requestedTools?: string[],
+): string[] | undefined => {
+  if (!policy.activeTools && !requestedTools) {
+    return undefined;
+  }
+
+  const merged = new Set<string>();
+  for (const tool of requestedTools ?? []) {
+    merged.add(tool);
+  }
+
+  for (const tool of policy.activeTools ?? []) {
+    merged.add(tool);
+  }
+
+  return Array.from(merged);
+};

package/src/governance/policies/telemetry.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Telemetry settings utilities
+ *
+ * Provides utilities for creating telemetry settings with risk level metadata
+ * and default telemetry configuration for agents.
+ *
+ * @module @od-oneapp/ai-platform/policies/telemetry
+ */
+
+import type { SDKTelemetrySettings } from '../../shared';
+import type { RiskLevel } from '../compliance/schemas';
+
+/**
+ * Creates telemetry settings with risk level metadata.
+ * Enables telemetry and includes risk level and optional metadata.
+ *
+ * @param options - Telemetry configuration options.
+ * @param options.functionId - Function identifier for telemetry tracking.
+ * @param options.riskLevel - Risk level to include in metadata.
+ * @param options.metadata - Optional additional metadata (merged with riskLevel).
+ * @returns Telemetry settings object with isEnabled: true and metadata containing riskLevel.
+ * @remarks Telemetry is always enabled. Metadata always includes riskLevel.
+ * Additional metadata is merged into the metadata object.
+ * @example
+ * ```ts
+ * const telemetry = createTelemetrySettings({
+ *   functionId: 'agent-execution',
+ *   riskLevel: 'medium',
+ *   metadata: { userId: 'user-123' }
+ * });
+ * ```
+ */
+export const createTelemetrySettings = ({
+  functionId,
+  riskLevel,
+  metadata,
+}: {
+  functionId: string;
+  riskLevel: RiskLevel;
+  metadata?: Record<string, string | number | boolean>;
+}): SDKTelemetrySettings => ({
+  isEnabled: true,
+  functionId,
+  metadata: {
+    riskLevel,
+    ...metadata,
+  },
+});
+
+/**
+ * Default telemetry settings for agents.
+ * Enables telemetry with basic run type metadata.
+ * @example
+ * ```ts
+ * const telemetry = { ...defaultTelemetry, functionId: 'agent-run' };
+ * ```
+ */
+export const defaultTelemetry: SDKTelemetrySettings = {
+  isEnabled: true,
+  metadata: {
+    runType: 'agent',
+  },
+};

package/src/governance/tenancy/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Multi-tenancy module
+ *
+ * Provides tenant isolation, quota management, and
+ * per-tenant configuration for AI applications.
+ *
+ * @module @od-oneapp/ai-platform/tenancy
+ */
+
+// Types
+export type { TenantConfig, TenantTier, TenantQuotas, TenantContext } from './types';
+export { TenantQuotaExceededError } from './types';
+
+// Isolation
+export {
+  setTenantContext,
+  getTenantContext,
+  getTenantContextOrNull,
+  clearTenantContext,
+  withTenantContext,
+  createTenantContext,
+} from './isolation/context';
+
+// Quotas
+export {
+  createQuotaMiddleware,
+  InMemoryQuotaTracker,
+  type QuotaTracker,
+  type QuotaUsage,
+} from './quotas/quota-manager';

package/src/governance/tenancy/isolation/context.ts

@@ -0,0 +1,92 @@
+/**
+ * Tenant context isolation
+ */
+
+import type { TenantContext, TenantConfig } from '../types';
+
+/**
+ * Tenant context storage (AsyncLocalStorage would be better in production)
+ */
+let currentTenant: TenantContext | null = null;
+
+/**
+ * Set the current tenant context
+ *
+ * @example
+ * ```ts
+ * setTenantContext({
+ *   tenantId: "tenant-123",
+ *   tier: "pro",
+ *   quotas: { requestsPerMinute: 100, ... }
+ * });
+ * ```
+ */
+export function setTenantContext(context: TenantContext): void {
+  // Clone to prevent external mutation of stored context
+  currentTenant = structuredClone(context);
+}
+
+/**
+ * Get the current tenant context
+ * @throws Error if no tenant context is set
+ */
+export function getTenantContext(): TenantContext {
+  if (!currentTenant) {
+    throw new Error('No tenant context set. Call setTenantContext first.');
+  }
+  // Return a clone to prevent external mutation
+  return structuredClone(currentTenant);
+}
+
+/**
+ * Get tenant context if available, or null
+ */
+export function getTenantContextOrNull(): TenantContext | null {
+  // Return a clone to prevent external mutation
+  return currentTenant ? structuredClone(currentTenant) : null;
+}
+
+/**
+ * Clear the current tenant context
+ */
+export function clearTenantContext(): void {
+  currentTenant = null;
+}
+
+/**
+ * Run a function with tenant context
+ *
+ * @example
+ * ```ts
+ * const result = await withTenantContext(
+ *   { tenantId: "tenant-123", tier: "pro", quotas: {...} },
+ *   async () => {
+ *     return generateText({ model, prompt });
+ *   }
+ * );
+ * ```
+ */
+export async function withTenantContext<T>(
+  context: TenantContext,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const previous = currentTenant;
+  try {
+    // Clone to prevent external mutation during execution
+    currentTenant = structuredClone(context);
+    return await fn();
+  } finally {
+    currentTenant = previous;
+  }
+}
+
+/**
+ * Create tenant context from config
+ */
+export function createTenantContext(config: TenantConfig): TenantContext {
+  return {
+    tenantId: config.tenantId,
+    tier: config.tier,
+    quotas: config.quotas,
+  };
+}

package/src/governance/tenancy/isolation/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Tenant isolation
+ * @module @od-oneapp/ai-platform/tenancy/isolation
+ */
+
+export {
+  setTenantContext,
+  getTenantContext,
+  getTenantContextOrNull,
+  clearTenantContext,
+  withTenantContext,
+  createTenantContext,
+} from './context';

package/src/governance/tenancy/quotas/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Tenant quota management
+ * @module @od-oneapp/ai-platform/tenancy/quotas
+ */
+
+export {
+  createQuotaMiddleware,
+  InMemoryQuotaTracker,
+  type QuotaTracker,
+  type QuotaUsage,
+} from './quota-manager';

package/src/governance/tenancy/quotas/quota-manager.ts

@@ -0,0 +1,180 @@
+/**
+ * Tenant quota management
+ */
+
+import { getTenantContext } from '../isolation/context';
+import { TenantQuotaExceededError } from '../types';
+
+import type { WrapGenerateArgs } from '../../../sdk/middleware/model-middleware';
+import type { SDKLanguageModelV3Middleware } from '../../../shared';
+import type { TenantQuotas } from '../types';
+
+
+/**
+ * Quota usage tracker interface
+ */
+export interface QuotaTracker {
+  /** Get current usage for a tenant */
+  getUsage(tenantId: string): Promise<QuotaUsage>;
+  /** Record usage for a tenant */
+  recordUsage(tenantId: string, usage: Partial<QuotaUsage>): Promise<void>;
+}
+
+/**
+ * Current quota usage
+ */
+export interface QuotaUsage {
+  requestsThisMinute: number;
+  requestsToday: number;
+  tokensToday: number;
+  costThisMonth: number;
+  currentConcurrent: number;
+}
+
+/**
+ * In-memory quota tracker for development
+ */
+export class InMemoryQuotaTracker implements QuotaTracker {
+  private usage = new Map<string, QuotaUsage>();
+
+  async getUsage(tenantId: string): Promise<QuotaUsage> {
+    return (
+      this.usage.get(tenantId) ?? {
+        requestsThisMinute: 0,
+        requestsToday: 0,
+        tokensToday: 0,
+        costThisMonth: 0,
+        currentConcurrent: 0,
+      }
+    );
+  }
+
+  async recordUsage(tenantId: string, usage: Partial<QuotaUsage>): Promise<void> {
+    const current = await this.getUsage(tenantId);
+    this.usage.set(tenantId, {
+      requestsThisMinute: current.requestsThisMinute + (usage.requestsThisMinute ?? 0),
+      requestsToday: current.requestsToday + (usage.requestsToday ?? 0),
+      tokensToday: current.tokensToday + (usage.tokensToday ?? 0),
+      costThisMonth: current.costThisMonth + (usage.costThisMonth ?? 0),
+      currentConcurrent: usage.currentConcurrent ?? current.currentConcurrent,
+    });
+  }
+
+  /** Reset usage for testing */
+  reset(tenantId?: string): void {
+    if (tenantId) {
+      this.usage.delete(tenantId);
+    } else {
+      this.usage.clear();
+    }
+  }
+}
+
+const getUsageTotal = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (value && typeof value === 'object' && 'total' in value) {
+    const { total } = value as { total?: unknown };
+    return typeof total === 'number' ? total : 0;
+  }
+  return 0;
+};
+
+/**
+ * Check quota limits
+ */
+async function checkQuotas(
+  tenantId: string,
+  quotas: TenantQuotas,
+  tracker: QuotaTracker,
+): Promise<void> {
+  const usage = await tracker.getUsage(tenantId);
+
+  if (usage.requestsThisMinute >= quotas.requestsPerMinute) {
+    throw new TenantQuotaExceededError(
+      tenantId,
+      'requestsPerMinute',
+      usage.requestsThisMinute,
+      quotas.requestsPerMinute,
+    );
+  }
+
+  if (usage.requestsToday >= quotas.requestsPerDay) {
+    throw new TenantQuotaExceededError(
+      tenantId,
+      'requestsPerDay',
+      usage.requestsToday,
+      quotas.requestsPerDay,
+    );
+  }
+
+  if (usage.tokensToday >= quotas.tokensPerDay) {
+    throw new TenantQuotaExceededError(
+      tenantId,
+      'tokensPerDay',
+      usage.tokensToday,
+      quotas.tokensPerDay,
+    );
+  }
+
+  if (usage.costThisMonth >= quotas.maxMonthlyCost) {
+    throw new TenantQuotaExceededError(
+      tenantId,
+      'maxMonthlyCost',
+      usage.costThisMonth,
+      quotas.maxMonthlyCost,
+    );
+  }
+
+  if (quotas.maxConcurrent && usage.currentConcurrent >= quotas.maxConcurrent) {
+    throw new TenantQuotaExceededError(
+      tenantId,
+      'maxConcurrent',
+      usage.currentConcurrent,
+      quotas.maxConcurrent,
+    );
+  }
+}
+
+/**
+ * Create tenant quota enforcement middleware
+ *
+ * @example
+ * ```ts
+ * const quotaMiddleware = createQuotaMiddleware(new RedisQuotaTracker(redis));
+ *
+ * const model = wrapLanguageModel({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   middleware: quotaMiddleware,
+ * });
+ * ```
+ */
+export function createQuotaMiddleware(tracker: QuotaTracker): SDKLanguageModelV3Middleware {
+  return {
+    specificationVersion: 'v3',
+    wrapGenerate: async ({ doGenerate }: WrapGenerateArgs) => {
+      const context = getTenantContext();
+
+      // Check quotas before request
+      await checkQuotas(context.tenantId, context.quotas, tracker);
+
+      // Record request start
+      await tracker.recordUsage(context.tenantId, {
+        requestsThisMinute: 1,
+        requestsToday: 1,
+      });
+
+      const result = await doGenerate();
+
+      // Record token usage
+      if (result.usage) {
+        const inputTokens = getUsageTotal(result.usage.inputTokens);
+        const outputTokens = getUsageTotal(result.usage.outputTokens);
+        await tracker.recordUsage(context.tenantId, {
+          tokensToday: inputTokens + outputTokens,
+        });
+      }
+
+      return result;
+    },
+  };
+}

package/src/governance/tenancy/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Multi-tenancy types
+ */
+
+/**
+ * Tenant configuration
+ */
+export interface TenantConfig {
+  /** Unique tenant identifier */
+  tenantId: string;
+  /** Display name */
+  name: string;
+  /** Tenant tier for feature gating */
+  tier: TenantTier;
+  /** Quota configuration */
+  quotas: TenantQuotas;
+  /** Allowed models for this tenant */
+  allowedModels?: string[];
+  /** Custom settings */
+  settings?: Record<string, unknown>;
+}
+
+/**
+ * Tenant tier for feature gating
+ */
+export type TenantTier = 'free' | 'starter' | 'pro' | 'enterprise';
+
+/**
+ * Tenant quotas
+ */
+export interface TenantQuotas {
+  /** Max requests per minute */
+  requestsPerMinute: number;
+  /** Max requests per day */
+  requestsPerDay: number;
+  /** Max tokens per day */
+  tokensPerDay: number;
+  /** Max cost per month in USD */
+  maxMonthlyCost: number;
+  /** Max concurrent requests */
+  maxConcurrent?: number;
+}
+
+/**
+ * Tenant context for request isolation
+ */
+export interface TenantContext {
+  tenantId: string;
+  tier: TenantTier;
+  quotas: TenantQuotas;
+}
+
+/**
+ * Tenant quota exceeded error
+ */
+export class TenantQuotaExceededError extends Error {
+  constructor(
+    public readonly tenantId: string,
+    public readonly quotaType: keyof TenantQuotas,
+    public readonly current: number,
+    public readonly limit: number,
+  ) {
+    super(`Tenant ${tenantId} exceeded ${quotaType} quota: ${current}/${limit}`);
+    this.name = 'TenantQuotaExceededError';
+  }
+}

package/src/governance/types.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Governance core types
+ * Shared types for audit logging and governance services.
+ */
+
+import type { AuditAction, AuditEntry, AuditQueryFilter } from './audit/audit-schema';
+
+export type { AuditAction, AuditEntry, AuditQueryFilter };
+
+/**
+ * Audit logger interface.
+ */
+export interface AuditLogger {
+  log(entry: Omit<AuditEntry, 'timestamp' | 'signature'>): Promise<void>;
+  query(filter: AuditQueryFilter): Promise<AuditEntry[]>;
+}