@od-oneapp/ai-platform 0.1.0

package/src/server/helpers.ts

@@ -0,0 +1,944 @@
+/**
+ * @fileoverview api-helpers.ts
+ */
+/**
+ * API Route Helpers
+ * DRY utilities for Next.js API routes with database persistence
+ */
+
+import {
+  createAIConversationOrm,
+  createAIMessageOrm,
+  findAIConversationOrm,
+  updateAIConversationOrm,
+} from '@od-oneapp/db-prisma/orm';
+import { AIMessageRole, AISessionType } from '@od-oneapp/db-prisma/types';
+import { type Logger, logError, logInfo, logWarn } from '@repo/shared/logs';
+
+import { createResumableStream } from '../integrations/stream';
+import { UI_MESSAGE_STREAM_HEADERS , generateId } from '../shared';
+
+import { generateSignature, verifySignature } from './cache/crypto';
+
+import type {
+  SDKLanguageModelUsage,
+  SDKStreamTextResult,
+  SDKUIMessage,
+} from '../shared';
+
+
+/**
+ * Type for AI SDK stream finish event
+ * Matches the onFinish callback shape from streamText/generateText
+ */
+interface StreamFinishEvent {
+  usage?: SDKLanguageModelUsage;
+  totalUsage?: SDKLanguageModelUsage;
+  finishReason?: string;
+  text?: string;
+}
+
+type WaitUntil = (promise: Promise<unknown>) => void;
+
+const defaultWaitUntil: WaitUntil = promise => {
+  void promise;
+};
+
+export interface StreamResumptionAuth {
+  getUserContext: (req: Request) => Promise<{ userId: string } | null>;
+  verifyOwnership?: (userId: string, chatId: string) => Promise<boolean>;
+}
+
+type StreamResumptionOptions = {
+  waitUntil?: WaitUntil;
+  auth?: StreamResumptionAuth;
+  tokenTtlSeconds?: number;
+};
+
+type SetupResumableStreamOptions = {
+  waitUntil?: WaitUntil;
+  userId?: string;
+  tokenTtlSeconds?: number;
+};
+
+type ResumptionTokenPayload = {
+  streamId: string;
+  chatId: string;
+  userId: string;
+  issuedAt: number;
+  expiresAt: number;
+};
+
+const defaultTokenTtlSeconds = () => {
+  const raw = process.env.STREAM_RESUME_TOKEN_TTL_SEC ?? '3600';
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 3600;
+};
+
+const getResumptionSigningKey = (): string | undefined =>
+  process.env.STREAM_RESUME_SIGNING_KEY ?? process.env.AUDIT_SIGNING_KEY;
+
+const encodeBase64Url = (value: string): string => {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(value, 'utf8').toString('base64url');
+  }
+
+  if (typeof btoa !== 'undefined') {
+    const encoded = btoa(value);
+    return encoded.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+  }
+
+  throw new Error('Base64 encoding unavailable');
+};
+
+const decodeBase64Url = (value: string): string => {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(value, 'base64url').toString('utf8');
+  }
+
+  if (typeof atob !== 'undefined') {
+    const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=');
+    return atob(padded);
+  }
+
+  throw new Error('Base64 decoding unavailable');
+};
+
+const createResumptionToken = async (payload: ResumptionTokenPayload): Promise<string> => {
+  const signingKey = getResumptionSigningKey();
+  if (!signingKey) {
+    throw new Error('STREAM_RESUME_SIGNING_KEY or AUDIT_SIGNING_KEY is required for resumption');
+  }
+  const encodedPayload = encodeBase64Url(JSON.stringify(payload));
+  const signature = await generateSignature({ payload: encodedPayload }, signingKey);
+  return `${encodedPayload}.${signature}`;
+};
+
+const verifyResumptionToken = async (token: string): Promise<ResumptionTokenPayload | null> => {
+  const signingKey = getResumptionSigningKey();
+  if (!signingKey) {
+    throw new Error('STREAM_RESUME_SIGNING_KEY or AUDIT_SIGNING_KEY is required for resumption');
+  }
+
+  const parts = token.split('.');
+  if (parts.length !== 2) {
+    return null;
+  }
+
+  const encodedPayload = parts[0];
+  const signature = parts[1];
+  if (!encodedPayload || !signature) {
+    return null;
+  }
+
+  const valid = await verifySignature({ payload: encodedPayload }, signature, signingKey);
+  if (!valid) {
+    return null;
+  }
+
+  const payload = JSON.parse(decodeBase64Url(encodedPayload)) as ResumptionTokenPayload;
+  if (!payload || typeof payload !== 'object') {
+    return null;
+  }
+
+  if (Date.now() > payload.expiresAt) {
+    return null;
+  }
+
+  return payload;
+};
+
+const resolveStreamResumptionOptions = (
+  options?: StreamResumptionOptions | WaitUntil,
+): StreamResumptionOptions => {
+  if (typeof options === 'function') {
+    return { waitUntil: options };
+  }
+  return options ?? {};
+};
+
+const resolveSetupResumableStreamOptions = (
+  options?: SetupResumableStreamOptions | WaitUntil,
+): SetupResumableStreamOptions => {
+  if (typeof options === 'function') {
+    return { waitUntil: options };
+  }
+  return options ?? {};
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null;
+};
+
+const normalizeError = (error: unknown): { message: string } => {
+  if (error instanceof Error) {
+    return { message: error.message };
+  }
+
+  if (typeof error === 'string') {
+    return { message: error };
+  }
+
+  if (isRecord(error) && typeof error.message === 'string') {
+    return { message: error.message };
+  }
+
+  return { message: 'Unknown error' };
+};
+
+const toByteStream = (stream: ReadableStream<Uint8Array | string>): ReadableStream<Uint8Array> => {
+  const encoder = new TextEncoder();
+  return stream.pipeThrough(
+    new TransformStream({
+      transform(chunk, controller) {
+        if (typeof chunk === 'string') {
+          controller.enqueue(encoder.encode(chunk));
+          return;
+        }
+        if (chunk instanceof Uint8Array) {
+          controller.enqueue(chunk);
+          return;
+        }
+        controller.enqueue(encoder.encode(String(chunk)));
+      },
+    }),
+  );
+};
+
+/**
+ * Extracts error message from unknown error type.
+ * Provides consistent error message extraction across all routes.
+ *
+ * @param {unknown} error - The error to extract message from
+ * @returns {string} The error message
+ *
+ * @example
+ * ```ts
+ * // Extract error message
+ * const message = getErrorMessage(error);
+ * return jsonError(message, 500);
+ * ```
+ */
+export const getErrorMessage = (error: unknown): string => {
+  return normalizeError(error).message;
+};
+
+/**
+ * Creates a JSON error response with consistent format.
+ *
+ * @param {string | Error} error - The error message or Error object
+ * @param {number} [status] - HTTP status code
+ * @returns {Response} JSON error response
+ *
+ * @example
+ * ```ts
+ * // Create error response
+ * return jsonError('Invalid request', 400);
+ * // or
+ * return jsonError(error, 500);
+ * ```
+ */
+export const jsonError = (error: string | Error, status: number = 500): Response => {
+  const message = typeof error === 'string' ? error : error.message;
+
+  return new Response(JSON.stringify({ error: message }), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+};
+
+/**
+ * Creates a JSON success response.
+ *
+ * @template T
+ * @param {T} data - The data to return
+ * @param {number} [status] - HTTP status code
+ * @returns {Response} JSON success response
+ *
+ * @example
+ * ```ts
+ * // Create success response
+ * return jsonSuccess({ userId: '123', name: 'John' }, 200);
+ * ```
+ */
+export const jsonSuccess = <T>(data: T, status: number = 200): Response => {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+};
+
+/**
+ * Parses and validates request body.
+ * Returns typed data or error response.
+ *
+ * @template T
+ * @param {Request} req - The request object
+ * @returns {Promise<{ data: T } | { error: Response }>} Parsed data or error response
+ *
+ * @example
+ * ```ts
+ * // Parse request body
+ * const result = await parseRequestBody<{ message: string }>(req);
+ * if ('error' in result) {
+ *   return result.error;
+ * }
+ * const { message } = result.data;
+ * ```
+ */
+export const parseRequestBody = async <T = unknown>(
+  req: Request,
+): Promise<{ data: T } | { error: Response }> => {
+  try {
+    const data = (await req.json()) as T;
+    return { data };
+  } catch {
+    return {
+      error: jsonError('Invalid JSON in request body', 400),
+    };
+  }
+};
+
+/**
+ * Validates that messages is a non-empty array of UIMessage.
+ *
+ * @param {unknown} messages - The value to validate
+ * @returns {messages is UIMessage[]} True if messages is a valid array
+ *
+ * @example
+ * ```ts
+ * // Validate messages
+ * if (!validateMessages(messages)) {
+ *   return jsonError('Invalid messages format', 400);
+ * }
+ * ```
+ */
+export const validateMessages = (messages: unknown): messages is SDKUIMessage[] => {
+  return Array.isArray(messages) && messages.length > 0;
+};
+
+/**
+ * Common response options for streaming
+ */
+export const STREAM_RESPONSE_OPTIONS = {
+  /** Standard options: sources + reasoning */
+  standard: {
+    sendSources: true,
+    sendReasoning: true,
+  },
+  /** Sources only */
+  sources: {
+    sendSources: true,
+  },
+  /** Minimal (no extras) */
+  minimal: {},
+} as const;
+
+/**
+ * Creates experimental_telemetry config for AI SDK v6.
+ * Provides observability for AI operations.
+ *
+ * @param {object} options - Telemetry configuration options
+ * @param {string} options.functionId - Unique identifier for the function
+ * @param {string} options.component - Component name
+ * @param {string} [options.version] - Version string
+ * @param {Record<string, unknown>} [options.metadata] - Additional metadata
+ * @returns {object} Telemetry configuration object
+ *
+ * @example
+ * ```ts
+ * // Create telemetry config
+ * const telemetry = createTelemetryConfig({
+ *   functionId: 'chat-handler',
+ *   component: 'chat-api',
+ *   version: '1.0.0',
+ *   metadata: { userId: '123' }
+ * });
+ * ```
+ */
+export const createTelemetryConfig = (options: {
+  functionId: string;
+  component: string;
+  version?: string;
+  metadata?: Record<string, unknown>;
+}) => {
+  return {
+    isEnabled: true,
+    functionId: options.functionId,
+    metadata: {
+      component: options.component,
+      version: options.version || '1.0.0',
+      ...options.metadata,
+    },
+  };
+};
+
+/**
+ * Handle stream resumption for GET /stream routes
+ * Queries the database for activeStreamId and resumes if found.
+ *
+ * Note: Requires Redis to be configured for resumable streams.
+ */
+export async function handleStreamResumption(
+  req: Request,
+  options?: StreamResumptionOptions | WaitUntil,
+): Promise<Response> {
+  const { waitUntil, auth } = resolveStreamResumptionOptions(options);
+  const effectiveWaitUntil = waitUntil ?? defaultWaitUntil;
+  const chatId = req.headers.get('X-Chat-ID');
+
+  if (!chatId) {
+    return jsonError('Missing X-Chat-ID header', 400);
+  }
+
+  if (!auth) {
+    return jsonError('Unauthorized', 401);
+  }
+
+  const userContext = await auth.getUserContext(req);
+  if (!userContext) {
+    return jsonError('Unauthorized', 401);
+  }
+
+  if (auth.verifyOwnership) {
+    const allowed = await auth.verifyOwnership(userContext.userId, chatId);
+    if (!allowed) {
+      return jsonError('Forbidden', 403);
+    }
+  }
+
+  // Query database for active stream ID
+  const conversation = await findAIConversationOrm({ id: chatId });
+  const resumptionToken = conversation?.activeStreamId;
+
+  if (!resumptionToken) {
+    return new Response(null, { status: 204 });
+  }
+
+  try {
+    const payload = await verifyResumptionToken(resumptionToken);
+    if (payload?.chatId !== chatId || payload.userId !== userContext.userId) {
+      await updateAIConversationOrm({ id: chatId }, { activeStreamId: null }).catch(() => {});
+      return new Response(null, { status: 204 });
+    }
+
+    const streamContext = createResumableStream({ waitUntil: effectiveWaitUntil });
+    const stream = await streamContext.resumeExistingStream(payload.streamId);
+
+    if (!stream) {
+      // Stream expired or not found - clear the reference
+      await updateAIConversationOrm({ id: chatId }, { activeStreamId: null }).catch(() => {});
+      return new Response(null, { status: 204 });
+    }
+
+    const responseStream = toByteStream(stream as ReadableStream<Uint8Array | string>);
+
+    return new Response(responseStream, {
+      headers: { ...UI_MESSAGE_STREAM_HEADERS, 'X-Stream-Resumed': 'true' },
+    });
+  } catch (error) {
+    logWarn('[handleStreamResumption] Failed to resume stream:', { error, chatId });
+    return new Response(null, { status: 204 });
+  }
+}
+
+/**
+ * Sets up resumable stream for agent responses.
+ * Wraps a response stream with resumption capabilities and stores
+ * the stream ID in the database for client-side resume.
+ *
+ * Note: Fails gracefully if Redis is not available - stream will still work,
+ * just without resumption support across page refreshes.
+ *
+ * @param {Response} response - The response stream to wrap
+ * @param {string} chatId - The chat/conversation ID for stream tracking
+ * @returns {Promise<void>}
+ *
+ * @example
+ * ```ts
+ * // Setup resumable stream
+ * const response = streamText(...);
+ * await setupResumableStream(response, chatId);
+ * return response;
+ * ```
+ */
+export const setupResumableStream = async (
+  response: Response,
+  chatId: string,
+  options?: SetupResumableStreamOptions | WaitUntil,
+): Promise<void> => {
+  const { waitUntil, userId, tokenTtlSeconds } = resolveSetupResumableStreamOptions(options);
+  const effectiveWaitUntil = waitUntil ?? defaultWaitUntil;
+  try {
+    const streamId = generateId();
+    const streamContext = createResumableStream({ waitUntil: effectiveWaitUntil });
+
+    if (response.body) {
+      await streamContext.createNewResumableStream(streamId, () => response.body as ReadableStream);
+      if (!userId) {
+        logWarn('[setupResumableStream] Missing userId, resumption disabled', { chatId });
+        return;
+      }
+
+      const ttlSeconds = tokenTtlSeconds ?? defaultTokenTtlSeconds();
+      const resumptionToken = await createResumptionToken({
+        streamId,
+        chatId,
+        userId,
+        issuedAt: Date.now(),
+        expiresAt: Date.now() + ttlSeconds * 1000,
+      });
+
+      // Store signed resumption token for client resume
+      await updateAIConversationOrm({ id: chatId }, { activeStreamId: resumptionToken });
+    }
+  } catch (error) {
+    // Fail gracefully - stream will work without resumption support
+    // This typically happens when Redis is not configured/available
+    const isRedisError =
+      error instanceof Error &&
+      'code' in error &&
+      (error as NodeJS.ErrnoException).code === 'ECONNREFUSED';
+
+    if (isRedisError) {
+      // Silent fail for Redis connection issues - already warned in createResumableStream
+      return;
+    }
+
+    // Log unexpected errors but don't throw
+    logWarn('[setupResumableStream] Failed to setup resumable stream:', { error });
+  }
+};
+
+/**
+ * Gets or generates a chat ID for non-persistent sessions.
+ *
+ * Note: For persistent sessions with database storage, use initializePersistentSession instead.
+ *
+ * @param {string} [id] - Optional existing chat ID
+ * @returns {string} The chat ID
+ *
+ * @example
+ * ```ts
+ * // Initialize chat session
+ * const chatId = initializeChatSession();
+ * // or with existing ID
+ * const chatId = initializeChatSession('existing-id');
+ * ```
+ */
+export const initializeChatSession = (id?: string): string => {
+  return id ?? generateId();
+};
+
+/**
+ * Initializes a persistent chat session with database storage.
+ * Use this instead of initializeChatSession for demos that need persistence.
+ *
+ * @param {object} [options] - Session initialization options
+ * @param {string} [options.sessionId] - Existing session ID
+ * @param {string} [options.userId] - User ID for the session
+ * @param {string} [options.model] - Model name for the session
+ * @param {string} [options.demo] - Demo identifier
+ * @returns {Promise<{ sessionId: string; isNew: boolean }>} Session ID and whether it's new
+ *
+ * @example
+ * ```ts
+ * // Initialize persistent session
+ * const { sessionId, isNew } = await initializePersistentSession({
+ *   userId: 'user-123',
+ *   model: 'gpt-4'
+ * });
+ * ```
+ */
+export const initializePersistentSession = async (options?: {
+  sessionId?: string;
+  userId?: string;
+  model?: string;
+  demo?: string;
+}): Promise<{ sessionId: string; isNew: boolean }> => {
+  let session;
+  let isNew = false;
+
+  // Try to get existing session if ID provided
+  if (options?.sessionId) {
+    session = await findAIConversationOrm({ id: options.sessionId });
+  }
+
+  // Create new session if not found
+  if (!session) {
+    session = await createAIConversationOrm({
+      ...(options?.userId ? { user: { connect: { id: options.userId } } } : {}),
+      primaryModel: options?.model,
+      sessionType: AISessionType.CONVERSATION,
+    });
+    isNew = true;
+  } else if (session.activeStreamId) {
+    // Clear any stale active stream from previous session
+    await updateAIConversationOrm({ id: session.id }, { activeStreamId: null }).catch(() => {});
+  }
+
+  return {
+    sessionId: session.id,
+    isNew,
+  };
+};
+
+/**
+ * Wrapper for initializePersistentSession that matches InitializeSessionFn signature
+ * Use this with createAgentRouteHandler for consistent session initialization
+ */
+export const initializePersistentSessionFn: (
+  sessionId?: string,
+) => Promise<{ sessionId: string; isNew: boolean }> = async sessionId => {
+  logInfo('[initializePersistentSessionFn] Starting with sessionId:', { sessionId });
+  try {
+    const result = await initializePersistentSession({ sessionId });
+    logInfo('[initializePersistentSessionFn] Success:', { result });
+    return result;
+  } catch (error) {
+    logError(error instanceof Error ? error : new Error(String(error)), {
+      message: '[initializePersistentSessionFn] Error:',
+    });
+    throw error;
+  }
+};
+
+/**
+ * Save a user message to the database
+ */
+export async function persistUserMessage(
+  sessionId: string,
+  content: string,
+  options?: { autoTitle?: boolean },
+): Promise<void> {
+  await createAIMessageOrm({
+    conversation: { connect: { id: sessionId } },
+    role: AIMessageRole.USER,
+    content,
+  });
+
+  // Auto-generate title from first message if requested
+  if (options?.autoTitle) {
+    const title = content.slice(0, 50) + (content.length > 50 ? '...' : '');
+    await updateAIConversationOrm({ id: sessionId }, { title }).catch(() => {});
+  }
+}
+
+/**
+ * Saves an assistant message to the database.
+ *
+ * @param {string} sessionId - The session ID
+ * @param {string} content - The message content
+ * @returns {Promise<void>}
+ *
+ * @example
+ * ```ts
+ * // Persist assistant message
+ * await persistAssistantMessage(sessionId, 'Hello! How can I help you?');
+ * ```
+ */
+export const persistAssistantMessage = async (
+  sessionId: string,
+  content: string,
+): Promise<void> => {
+  await createAIMessageOrm({
+    conversation: { connect: { id: sessionId } },
+    role: AIMessageRole.ASSISTANT,
+    content,
+  });
+};
+
+/**
+ * Creates a standard onFinish callback for AI SDK streams.
+ * Combines stream cleanup with optional usage logging and persistence.
+ *
+ * AI SDK v6 native feature - leverages built-in onFinish callback
+ * instead of manually handling result.usage Promise.
+ *
+ * @param {string} chatId - The chat ID for stream tracking
+ * @param {object} [options] - Callback options
+ * @param {boolean} [options.logUsage] - Whether to log usage statistics
+ * @param {string} [options.demo] - Demo identifier for logging
+ * @param {Logger} [options.logger] - Logger instance for usage logging
+ * @param {string} [options.persistSessionId] - Session ID for database persistence
+ * @returns {(event: StreamFinishEvent) => Promise<void>} onFinish callback function
+ *
+ * @example
+ * ```ts
+ * // Create onFinish callback
+ * const onFinish = createOnFinishCallback(chatId, {
+ *   logUsage: true,
+ *   demo: 'chat-demo',
+ *   persistSessionId: sessionId
+ * });
+ * ```
+ */
+export const createOnFinishCallback = (
+  chatId: string,
+  options?: {
+    logUsage?: boolean;
+    demo?: string;
+    logger?: Logger;
+    /** Session ID for database persistence */
+    persistSessionId?: string;
+  },
+) => {
+  return async (event: StreamFinishEvent) => {
+    // Clear active stream in database
+    await updateAIConversationOrm({ id: chatId }, { activeStreamId: null }).catch(() => {});
+
+    // Persist assistant response if session ID provided
+    if (options?.persistSessionId && event?.text) {
+      await persistAssistantMessage(options.persistSessionId, event.text).catch(err => {
+        options?.logger?.info?.('Failed to persist assistant message', { error: String(err) });
+      });
+    }
+
+    // Optional usage logging using AI SDK's native onFinish instead of manual Promise handling
+    if (options?.logUsage && options?.logger && event?.usage) {
+      options.logger.info(`${options.demo || 'stream'} usage`, {
+        ...event.usage,
+        totalUsage: event.totalUsage,
+        demo: options.demo,
+      });
+    }
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Cost & telemetry utilities (migrated from @repo/ai)
+// ---------------------------------------------------------------------------
+
+/**
+ * Calculate model cost with extended pricing data including Vercel AI Gateway models.
+ *
+ * Supports provider-prefixed model IDs (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4-5')
+ * and includes pricing for newer models and gateway-specific models.
+ *
+ * @param modelId - Model identifier (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4-5')
+ * @param usage - Token usage object
+ * @returns Estimated cost in USD
+ *
+ * @example
+ * ```typescript
+ * const cost = calculateModelCost('openai/gpt-4o', {
+ *   inputTokens: 1000,
+ *   outputTokens: 500
+ * });
+ * // Returns: 0.005 (estimated cost in USD)
+ * ```
+ */
+export const calculateModelCost = (
+  modelId: string,
+  usage: { inputTokens?: number; outputTokens?: number },
+): number => {
+  const MODEL_COSTS: Record<string, { input: number; output: number }> = {
+    'openai/gpt-4o': { input: 0.0025, output: 0.01 },
+    'openai/gpt-4o-mini': { input: 0.00015, output: 0.0006 },
+    'openai/gpt-5.1-instant': { input: 0.0001, output: 0.0004 },
+    'anthropic/claude-sonnet-4-20250514': { input: 0.003, output: 0.015 },
+    'anthropic/claude-opus-4-5-20251101': { input: 0.015, output: 0.075 },
+    'perplexity/sonar': { input: 0.001, output: 0.001 },
+    // Legacy model names (without provider prefix)
+    'gpt-4o': { input: 0.0025, output: 0.01 },
+    'gpt-4o-mini': { input: 0.00015, output: 0.0006 },
+    'gpt-5.1-instant': { input: 0.0001, output: 0.0004 },
+    'claude-sonnet-4': { input: 0.003, output: 0.015 },
+    'claude-opus-4': { input: 0.015, output: 0.075 },
+    // Default fallback
+    default: { input: 0.001, output: 0.002 },
+  };
+
+  const pricing = MODEL_COSTS[modelId] ?? MODEL_COSTS.default ?? { input: 0.001, output: 0.002 };
+  const inputTokens = usage.inputTokens ?? 0;
+  const outputTokens = usage.outputTokens ?? 0;
+
+  return (inputTokens / 1000) * pricing.input + (outputTokens / 1000) * pricing.output;
+};
+
+/**
+ * Estimate input tokens from text.
+ *
+ * Uses rough approximation: ~4 characters per token for English text.
+ * This is a simple heuristic and may vary by language and content type.
+ *
+ * @param text - Text to estimate tokens for
+ * @returns Estimated number of input tokens
+ *
+ * @example
+ * ```typescript
+ * estimateInputTokens('Hello world'); // Returns: 3 (12 chars / 4)
+ * ```
+ */
+export const estimateInputTokens = (text: string): number => Math.ceil(text.length / 4);
+
+/**
+ * Extract model name from provider-prefixed model ID.
+ *
+ * Removes provider prefix from model IDs like "openai/gpt-4o" or "anthropic/claude-3-5-sonnet".
+ * Handles both "provider/model" and "provider:model" formats.
+ *
+ * @param modelId - Model identifier (e.g., "openai/gpt-4o", "openai:gpt-4o", "gpt-4o")
+ * @returns Model name without provider prefix
+ *
+ * @example
+ * ```typescript
+ * extractModelName('openai/gpt-4o'); // Returns: 'gpt-4o'
+ * extractModelName('openai:gpt-4o'); // Returns: 'gpt-4o'
+ * extractModelName('gpt-4o'); // Returns: 'gpt-4o'
+ * ```
+ */
+export const extractModelName = (modelId: string): string => {
+  if (modelId.includes('/')) {
+    const parts = modelId.split('/');
+    return parts[parts.length - 1] ?? modelId;
+  }
+  if (modelId.includes(':')) {
+    const parts = modelId.split(':');
+    return parts[parts.length - 1] ?? modelId;
+  }
+  return modelId;
+};
+
+/**
+ * Round cost to specified decimal places.
+ *
+ * @param cost - Cost value to round
+ * @param decimals - Number of decimal places (default: 6)
+ * @returns Rounded cost value
+ *
+ * @example
+ * ```typescript
+ * roundCost(0.123456789); // Returns: 0.123457
+ * roundCost(0.123456789, 2); // Returns: 0.12
+ * ```
+ */
+export const roundCost = (cost: number, decimals: number = 6): number =>
+  Math.round(cost * Math.pow(10, decimals)) / Math.pow(10, decimals);
+
+/**
+ * Truncate text to specified length with ellipsis.
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length before truncation
+ * @param ellipsis - Ellipsis string (default: '...')
+ * @returns Truncated text
+ *
+ * @example
+ * ```typescript
+ * truncateText('Hello world', 8); // Returns: 'Hello...'
+ * truncateText('Short', 10); // Returns: 'Short'
+ * ```
+ */
+export const truncateText = (text: string, maxLength: number, ellipsis: string = '...'): string => {
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - ellipsis.length)}${ellipsis}`;
+};
+
+/**
+ * Calculate elapsed duration in milliseconds from a start timestamp.
+ *
+ * @param startTime - Epoch milliseconds captured at the start of an operation
+ * @returns Milliseconds elapsed since `startTime`
+ *
+ * @example
+ * ```typescript
+ * const startedAt = Date.now();
+ * // ... work ...
+ * const durationMs = calculateDuration(startedAt);
+ * ```
+ */
+export const calculateDuration = (startTime: number): number => Date.now() - startTime;
+
+/**
+ * Extract telemetry data from an AI SDK stream result.
+ * Awaits text, usage, and reasoningText in parallel for efficiency.
+ *
+ * @param result - AI SDK stream result to extract from
+ * @returns Parsed text, usage, and optional reasoning text
+ *
+ * @example
+ * ```typescript
+ * const telemetry = await extractTelemetry(streamResult);
+ * console.log(telemetry.usage.totalTokens);
+ * ```
+ */
+export const extractTelemetry = async <TUsage extends SDKLanguageModelUsage>(
+   
+  result: SDKStreamTextResult<any, any>,
+): Promise<{ text: string; usage: TUsage; reasoningText: string | undefined }> => {
+  const [text, usage, reasoningText] = await Promise.all([
+    result.text,
+    result.usage,
+    result.reasoningText,
+  ]);
+
+  return { text, usage: usage as TUsage, reasoningText };
+};
+
+/**
+ * Aggregate token usage from multiple messages or operations.
+ *
+ * Combines usage statistics from multiple sources, handling undefined/null values safely.
+ * Useful for tracking cumulative usage across a conversation or session.
+ *
+ * @param current - Current usage statistics
+ * @param addition - Usage to add to current
+ * @returns Aggregated usage statistics
+ *
+ * @example
+ * ```typescript
+ * const totalUsage = aggregateUsage(
+ *   { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+ *   { inputTokens: 200, outputTokens: 100, totalTokens: 300 }
+ * );
+ * // Returns: { inputTokens: 300, outputTokens: 150, totalTokens: 450, ... }
+ * ```
+ */
+export const aggregateUsage = (
+  current: Partial<SDKLanguageModelUsage>,
+  addition: Partial<SDKLanguageModelUsage>,
+): SDKLanguageModelUsage => {
+  // Aggregate reasoning tokens (prefer outputTokenDetails, fallback to deprecated field)
+  const reasoningTokens =
+    (current.outputTokenDetails?.reasoningTokens ?? current.reasoningTokens ?? 0) +
+    (addition.outputTokenDetails?.reasoningTokens ?? addition.reasoningTokens ?? 0);
+
+  // Aggregate cache read tokens (prefer inputTokenDetails, fallback to deprecated field)
+  const cacheReadTokens =
+    (current.inputTokenDetails?.cacheReadTokens ?? current.cachedInputTokens ?? 0) +
+    (addition.inputTokenDetails?.cacheReadTokens ?? addition.cachedInputTokens ?? 0);
+
+  // Aggregate other input token details
+  const noCacheTokens =
+    (current.inputTokenDetails?.noCacheTokens ?? 0) +
+    (addition.inputTokenDetails?.noCacheTokens ?? 0);
+
+  const cacheWriteTokens =
+    (current.inputTokenDetails?.cacheWriteTokens ?? 0) +
+    (addition.inputTokenDetails?.cacheWriteTokens ?? 0);
+
+  // Aggregate text tokens from output details
+  const textTokens =
+    (current.outputTokenDetails?.textTokens ?? 0) + (addition.outputTokenDetails?.textTokens ?? 0);
+
+  return {
+    inputTokens: (current.inputTokens ?? 0) + (addition.inputTokens ?? 0),
+    outputTokens: (current.outputTokens ?? 0) + (addition.outputTokens ?? 0),
+    totalTokens: (current.totalTokens ?? 0) + (addition.totalTokens ?? 0),
+    // Deprecated fields for backwards compatibility
+    reasoningTokens,
+    cachedInputTokens: cacheReadTokens,
+    // AI SDK v6 detailed token info
+    inputTokenDetails: {
+      noCacheTokens: noCacheTokens || undefined,
+      cacheReadTokens: cacheReadTokens || undefined,
+      cacheWriteTokens: cacheWriteTokens || undefined,
+    },
+    outputTokenDetails: {
+      textTokens: textTokens || undefined,
+      reasoningTokens: reasoningTokens || undefined,
+    },
+  };
+};