@capekai/core 1.0.0

package/src/core/model-utils.ts

@@ -0,0 +1,149 @@
+import { type LanguageModel } from 'ai';
+import { createOpenAI } from '@ai-sdk/openai';
+import { findProviderFromModel, parseModelSpecifier } from './provider-utils';
+import { findModel, getApiKeyForProvider, getLLMBaseUrl, getModelsConfig } from '../configuration/runtime';
+import { createModelForProvider, getProvider } from '../providers/registry';
+import { isSandboxActive } from '../runtime/host-dependencies';
+
+export interface ModelWithMetadata {
+  model: LanguageModel;
+  useProviderInstructions?: boolean;
+  omitMaxOutputTokens?: boolean;
+  providerOptions?: Record<string, Record<string, unknown>>;
+}
+
+export interface ModelResolutionOptions {
+  modelId?: string;
+  providerId?: string;
+  systemPrompt?: string;
+  sessionId?: string;
+}
+
+export async function getModelWithMetadata(options: ModelResolutionOptions): Promise<ModelWithMetadata>;
+export async function getModelWithMetadata(modelId?: string, providerId?: string, systemPrompt?: string): Promise<ModelWithMetadata>;
+export async function getModelWithMetadata(
+  modelIdOrOptions?: string | ModelResolutionOptions,
+  providerId?: string,
+  systemPrompt?: string,
+): Promise<ModelWithMetadata> {
+  const options: ModelResolutionOptions = typeof modelIdOrOptions === 'string'
+    ? { modelId: modelIdOrOptions, providerId, systemPrompt }
+    : (modelIdOrOptions ?? {});
+  const requestedModelId = options.modelId || getModelsConfig().defaultModel;
+  const parsedSpecifier = parseModelSpecifier(requestedModelId);
+  const resolvedModelId = parsedSpecifier.modelId;
+  const sandboxProvider = getProvider('sandbox');
+
+  // When sandbox mode is active, route all LLM calls through the sandbox provider
+  if (sandboxProvider && isSandboxActive()) {
+    const result = await createModelForProvider({
+      modelId: resolvedModelId,
+      providerId: 'sandbox',
+      systemPrompt: options.systemPrompt || '',
+      sessionId: options.sessionId,
+    });
+    return {
+      model: result.model,
+      useProviderInstructions: result.useProviderInstructions,
+      omitMaxOutputTokens: result.omitMaxOutputTokens,
+      providerOptions: result.providerOptions,
+    };
+  }
+
+  let provider = options.providerId ?? parsedSpecifier.providerId;
+  let model = resolvedModelId;
+
+  if (!provider) {
+    provider = findProviderFromModel(resolvedModelId);
+    const modelInfo = findModel(resolvedModelId);
+    if (modelInfo) {
+      model = modelInfo.id;
+    }
+  }
+
+  if (!provider) {
+    throw new Error('No provider resolved for model "' + model + '". Configure runtime configuration (getModelsConfig) with a default provider, register the provider, or pass providerId explicitly.');
+  }
+
+  const registeredProvider = getProvider(provider);
+  if (registeredProvider) {
+    const result = await createModelForProvider({
+      modelId: model,
+      providerId: provider,
+      systemPrompt: options.systemPrompt || '',
+      sessionId: options.sessionId,
+    });
+    return {
+      model: result.model,
+      useProviderInstructions: result.useProviderInstructions,
+      omitMaxOutputTokens: result.omitMaxOutputTokens,
+      providerOptions: result.providerOptions,
+    };
+  }
+
+  const apiKey = getApiKeyForProvider(provider);
+
+  if (!apiKey) {
+    throw new Error(`No API key configured for provider: ${provider}. Register the provider with registerProvider or configure getApiKey in runtime configuration.`);
+  }
+
+  switch (provider) {
+    case 'openrouter': {
+      const { createOpenRouter } = await import('@openrouter/ai-sdk-provider');
+      const openrouter = createOpenRouter({ apiKey });
+      return { model: openrouter.chat(model) as unknown as LanguageModel };
+    }
+
+    case 'minimax': {
+      const { createMinimax } = await import('vercel-minimax-ai-provider');
+      const minimax = createMinimax({ apiKey });
+      return { model: minimax.chat(model) as unknown as LanguageModel };
+    }
+
+    case 'zhipu': {
+      const { createZhipu } = await import('zhipu-ai-provider');
+      const zhipu = createZhipu({
+        apiKey,
+        baseURL: 'https://open.bigmodel.cn/api/paas/v4',
+      });
+      return { model: zhipu.chat(model) as unknown as LanguageModel };
+    }
+
+    case 'zhipu-coding': {
+      const { createZhipu } = await import('zhipu-ai-provider');
+      const zhipu = createZhipu({
+        apiKey,
+        baseURL: 'https://api.z.ai/api/coding/paas/v4',
+      });
+      return { model: zhipu.chat(model) as unknown as LanguageModel };
+    }
+
+    case 'deepseek': {
+      const { createDeepSeek } = await import('@ai-sdk/deepseek');
+      const deepseek = createDeepSeek({ apiKey });
+      return { model: deepseek.chat(model) as unknown as LanguageModel };
+    }
+
+    case 'openai':
+    default: {
+      const openai = createOpenAI({
+        apiKey,
+        baseURL: getLLMBaseUrl() || undefined,
+      });
+      return {
+        model: openai.responses(model) as unknown as LanguageModel,
+        providerOptions: {
+          openai: {
+            promptCacheKey: options.sessionId,
+            store: false,
+          },
+        },
+      };
+    }
+  }
+}
+
+export async function getModel(modelId?: string, providerId?: string): Promise<LanguageModel> {
+  const { model } = await getModelWithMetadata({ modelId, providerId });
+  return model;
+}

package/src/core/part-utils.ts

@@ -0,0 +1,88 @@
+import type { TextPart, ToolPart, StepPart, Part, ImagePart, FilePart } from '@capekai/types';
+import { randomUUID } from 'crypto';
+
+export function isTextPart(part: Part): part is TextPart {
+  return part.type === 'text';
+}
+
+export function isToolPart(part: Part): part is ToolPart {
+  return part.type === 'tool';
+}
+
+export function isImagePart(part: Part): part is ImagePart {
+  return part.type === 'image';
+}
+
+export function isFilePart(part: Part): part is FilePart {
+  return part.type === 'file';
+}
+
+const NULL_BYTE = '\u0000';
+
+function stripNullBytes(value: string): string {
+  if (!value.includes(NULL_BYTE)) {
+    return value;
+  }
+  return value.split(NULL_BYTE).join('');
+}
+
+function sanitizeInput(input: unknown): unknown {
+  if (typeof input === 'string') {
+    return stripNullBytes(input);
+  }
+  if (Array.isArray(input)) {
+    return input.map(sanitizeInput);
+  }
+  if (input !== null && typeof input === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(input)) {
+      result[stripNullBytes(key)] = sanitizeInput((input as Record<string, unknown>)[key]);
+    }
+    return result;
+  }
+  return input;
+}
+
+export function parseToolInput(input: unknown): Record<string, unknown> {
+  if (input === null || input === undefined) {
+    return {};
+  }
+  if (typeof input === 'string') {
+    try {
+      const parsed = JSON.parse(input);
+      if (typeof parsed === 'object' && parsed !== null) {
+        return sanitizeInput(parsed) as Record<string, unknown>;
+      }
+      return {};
+    } catch {
+      return {};
+    }
+  }
+  return typeof input === 'object'
+    ? sanitizeInput(input) as Record<string, unknown>
+    : {};
+}
+
+export function createStepPart(options: {
+  messageId: string;
+  sessionId: string;
+  number: number;
+  status: 'started' | 'finished';
+  finishReason?: 'stop' | 'tool-calls' | 'error' | 'length';
+  tokens?: { prompt: number; completion: number };
+  cost?: number;
+  snapshot?: string;
+}): StepPart {
+  return {
+    id: randomUUID(),
+    messageId: options.messageId,
+    createdAt: Date.now(),
+    type: 'step',
+    number: options.number,
+    status: options.status,
+    ...(options.finishReason && { finishReason: options.finishReason }),
+    ...(options.tokens && { tokens: options.tokens }),
+    ...(options.cost !== undefined && { cost: options.cost }),
+    ...(options.snapshot && { snapshot: options.snapshot }),
+  };
+}

package/src/core/provider-utils.ts

@@ -0,0 +1,67 @@
+import { findModel, getModelsConfig } from '../configuration/runtime';
+import { getProvider } from '../providers/registry';
+import type { Session, Preconfig } from '@capekai/types';
+
+export type Provider = 'openai' | 'openrouter' | 'minimax' | 'zhipu' | 'zhipu-coding' | 'deepseek';
+
+const EXPLICIT_PROVIDERS = new Set<Provider>([
+  'openai',
+  'openrouter',
+  'minimax',
+  'zhipu',
+  'zhipu-coding',
+  'deepseek',
+]);
+
+const PROVIDER_PREFIXES: Array<{ test: (m: string) => boolean; provider: string }> = [
+  { test: (m) => m.includes('/'), provider: 'openrouter' },
+  { test: (m) => m.startsWith('MiniMax-') || m.toLowerCase().includes('minimax'), provider: 'minimax' },
+  { test: (m) => m.startsWith('deepseek-'), provider: 'deepseek' },
+];
+
+export interface ParsedModelSpecifier {
+  modelId: string;
+  providerId?: string;
+}
+
+export function parseModelSpecifier(modelId: string): ParsedModelSpecifier {
+  const separator = modelId.indexOf('/');
+  if (separator <= 0 || separator === modelId.length - 1) return { modelId };
+  const providerId = modelId.slice(0, separator) as Provider;
+  if (!EXPLICIT_PROVIDERS.has(providerId) && !getProvider(providerId)) return { modelId };
+  return {
+    providerId,
+    modelId: modelId.slice(separator + 1),
+  };
+}
+
+export function findProviderFromModel(modelId: string): string {
+  const modelInfo = findModel(modelId);
+  if (modelInfo) return modelInfo.providerId;
+
+  const parsed = parseModelSpecifier(modelId);
+  if (parsed.providerId) return parsed.providerId;
+
+  for (const { test, provider } of PROVIDER_PREFIXES) {
+    if (test(modelId)) return provider;
+  }
+  return getModelsConfig().defaultProvider;
+}
+
+export function resolveModelId(
+  session: Pick<Session, 'selectedModel'> | null,
+  preconfig: Pick<Preconfig, 'model'> | null | undefined,
+): string {
+  return session?.selectedModel || preconfig?.model || getModelsConfig().defaultModel;
+}
+
+export function resolveProviderId(
+  session: Pick<Session, 'selectedProvider'> | null,
+  preconfig: Pick<Preconfig, 'model'> | null | undefined,
+): string {
+  return (
+    session?.selectedProvider ||
+    (preconfig?.model ? findProviderFromModel(preconfig.model) : null) ||
+    getModelsConfig().defaultProvider
+  );
+}

package/src/core/revert.ts

@@ -0,0 +1,46 @@
+import { deleteMessage, listMessagesWithParts, updateMessage } from '../storage/runtime';
+
+interface RevertResult {
+  revertedTo: { messageId: string | null; messageCount: number };
+  removed: { messageIds: string[]; partCount: number };
+}
+
+interface RevertOptions {
+  sessionId: string;
+  targetMessageId: string;
+  keepTarget?: boolean;
+}
+
+export async function revertToStep(options: RevertOptions): Promise<RevertResult> {
+  const { sessionId, targetMessageId, keepTarget = false } = options;
+  const allMessages = await listMessagesWithParts(sessionId);
+  const targetIndex = allMessages.findIndex((entry) => entry.message.id === targetMessageId);
+  if (targetIndex === -1) throw new Error('Target message not found');
+
+  const messagesToDelete = targetIndex === 0 && !keepTarget
+    ? allMessages
+    : allMessages.slice(targetIndex + 1);
+  const removedMessageIds: string[] = [];
+  let partCountRemoved = 0;
+
+  for (const { message, parts } of messagesToDelete) {
+    partCountRemoved += parts.length;
+    removedMessageIds.push(message.id);
+    await deleteMessage(message.id);
+  }
+
+  for (const { message } of await listMessagesWithParts(sessionId)) {
+    if (message.role === 'assistant' && message.status === 'streaming') {
+      await updateMessage(message.id, { status: 'error', error: 'Reverted before completion' });
+    }
+  }
+
+  const clearedAll = targetIndex === 0 && !keepTarget;
+  return {
+    revertedTo: {
+      messageId: clearedAll ? null : targetMessageId,
+      messageCount: clearedAll ? 0 : targetIndex,
+    },
+    removed: { messageIds: removedMessageIds, partCount: partCountRemoved },
+  };
+}

package/src/core/step-handlers.ts

@@ -0,0 +1,157 @@
+import type { MessageEvent, StepPart } from '@capekai/types';
+import { createPart, updatePart } from '../storage/runtime';
+import { createStepPart } from './part-utils';
+import { randomUUID } from 'crypto';
+import { getModelsConfig } from '../configuration/runtime';
+
+interface StepUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  inputTokenDetails?: {
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    noCacheTokens?: number;
+  };
+}
+
+export interface UsageEventData {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  noCacheTokens: number;
+}
+
+export interface StepCallbacksContext {
+  messageId: string;
+  sessionId: string;
+  stepParts: StepPart[];
+  yieldFn: ((event: CallbackEvent) => void) | null;
+  isMainSession: boolean | null;
+  contextWindow: number | undefined;
+  autoThreshold: number;
+  resolvedModelId: string | undefined;
+  variant: string | undefined;
+  needsCompaction: boolean;
+  latestUsage: UsageEventData;
+}
+
+export type CallbackEvent = MessageEvent | {
+  type: 'usage';
+  usage: UsageEventData;
+  model: string;
+  variant: string | null;
+};
+
+export function createStepCallbacks(ctx: StepCallbacksContext) {
+  return {
+    experimental_onStepStart: async (stepStartEvent: { stepNumber: number }) => {
+      const stepNumber = stepStartEvent.stepNumber + 1;
+
+      const startedStepPart = createStepPart({
+        messageId: ctx.messageId,
+        sessionId: ctx.sessionId,
+        number: stepNumber,
+        status: 'started',
+      });
+      ctx.stepParts.push(startedStepPart);
+
+      if (ctx.yieldFn) {
+        ctx.yieldFn({ type: 'part.created', sessionId: ctx.sessionId, part: startedStepPart });
+      }
+      await createPart(startedStepPart, ctx.sessionId);
+    },
+    onStepFinish: async (stepFinishEvent: { stepNumber: number; finishReason: string | null; usage?: StepUsage; totalUsage?: StepUsage }) => {
+      const stepNumber = stepFinishEvent.stepNumber + 1;
+
+      const stepUsage = stepFinishEvent.usage;
+      const stepPromptTokens = stepUsage?.inputTokens ?? 0;
+      const stepCompletionTokens = stepUsage?.outputTokens ?? 0;
+      const stepCacheReadTokens = stepUsage?.inputTokenDetails?.cacheReadTokens ?? 0;
+      const stepCacheWriteTokens = stepUsage?.inputTokenDetails?.cacheWriteTokens ?? 0;
+      const stepNoCacheTokens = stepUsage?.inputTokenDetails?.noCacheTokens ?? 0;
+
+      if (ctx.isMainSession && ctx.contextWindow) {
+        const latestStepInputTokens = stepUsage?.inputTokens ?? 0;
+        if (latestStepInputTokens >= ctx.autoThreshold) {
+          ctx.needsCompaction = true;
+        }
+      }
+
+      let finishReason: 'stop' | 'tool-calls' | 'error' | 'length' | undefined;
+      if (stepFinishEvent.finishReason) {
+        if (stepFinishEvent.finishReason === 'stop') {
+          finishReason = 'stop';
+        } else if (stepFinishEvent.finishReason === 'tool-calls') {
+          finishReason = 'tool-calls';
+        } else if (stepFinishEvent.finishReason === 'length') {
+          finishReason = 'length';
+        } else if (stepFinishEvent.finishReason === 'error' || stepFinishEvent.finishReason === 'other') {
+          finishReason = 'error';
+        }
+      }
+
+      const existingStepPart = ctx.stepParts.find(sp => sp.number === stepNumber);
+
+      const finishedStepPart: StepPart = {
+        id: existingStepPart?.id || randomUUID(),
+        messageId: ctx.messageId,
+        createdAt: existingStepPart?.createdAt || Date.now(),
+        type: 'step',
+        number: stepNumber,
+        status: 'finished',
+        finishReason,
+        tokens: {
+          prompt: stepPromptTokens,
+          completion: stepCompletionTokens,
+          cacheRead: stepCacheReadTokens,
+          cacheWrite: stepCacheWriteTokens,
+          noCache: stepNoCacheTokens,
+        },
+      };
+
+      if (existingStepPart) {
+        const index = ctx.stepParts.indexOf(existingStepPart);
+        ctx.stepParts[index] = finishedStepPart;
+      } else {
+        ctx.stepParts.push(finishedStepPart);
+      }
+
+      if (ctx.yieldFn) {
+        ctx.yieldFn({ type: 'part.updated', sessionId: ctx.sessionId, part: finishedStepPart });
+      }
+      await updatePart(finishedStepPart.id, {
+        status: finishedStepPart.status,
+        finishReason: finishedStepPart.finishReason,
+        tokens: finishedStepPart.tokens,
+      });
+
+      if (stepUsage) {
+        ctx.latestUsage.promptTokens = stepUsage.inputTokens ?? 0;
+        ctx.latestUsage.completionTokens = stepUsage.outputTokens ?? 0;
+        ctx.latestUsage.totalTokens = stepUsage.totalTokens ?? 0;
+        ctx.latestUsage.cacheReadTokens = stepUsage.inputTokenDetails?.cacheReadTokens ?? 0;
+        ctx.latestUsage.cacheWriteTokens = stepUsage.inputTokenDetails?.cacheWriteTokens ?? 0;
+        ctx.latestUsage.noCacheTokens = stepUsage.inputTokenDetails?.noCacheTokens ?? 0;
+
+        if (ctx.yieldFn) {
+          ctx.yieldFn({
+            type: 'usage',
+            usage: {
+              promptTokens: ctx.latestUsage.promptTokens,
+              completionTokens: ctx.latestUsage.completionTokens,
+              totalTokens: ctx.latestUsage.totalTokens,
+              cacheReadTokens: ctx.latestUsage.cacheReadTokens,
+              cacheWriteTokens: ctx.latestUsage.cacheWriteTokens,
+              noCacheTokens: ctx.latestUsage.noCacheTokens,
+            },
+            model: ctx.resolvedModelId ?? getModelsConfig().defaultModel,
+            variant: ctx.variant ?? null,
+          });
+        }
+      }
+    },
+  };
+}

package/src/core/stream/finalization.ts

@@ -0,0 +1,65 @@
+import type { LanguageModelUsage } from 'ai';
+import { extractJsonFromText } from '../structured-output';
+import type { StructuredOutputData, ResponseFormat } from '@capekai/types';
+
+export interface FinalizationData {
+  usageData: LanguageModelUsage | null;
+  structuredOutputData: StructuredOutputData | undefined;
+}
+
+export interface FinalizationOptions {
+  result: {
+    totalUsage: PromiseLike<LanguageModelUsage>;
+    usage: PromiseLike<LanguageModelUsage | undefined>;
+    output: PromiseLike<unknown>;
+  };
+  responseFormat?: ResponseFormat;
+  usePromptBasedStructuredOutput: boolean;
+  accumulatedText: string;
+}
+
+export async function extractFinalizationData(options: FinalizationOptions): Promise<FinalizationData> {
+  const { result, responseFormat, usePromptBasedStructuredOutput, accumulatedText } = options;
+
+  let usageData: LanguageModelUsage | null = null;
+  let structuredOutputData: StructuredOutputData | undefined;
+
+  try {
+    const totalUsagePromise = result.totalUsage;
+    const usagePromise = result.usage;
+    const [totalUsage, usage] = await Promise.all([totalUsagePromise, usagePromise]);
+    usageData = usage ?? totalUsage;
+
+    if (responseFormat) {
+      try {
+        if (usePromptBasedStructuredOutput) {
+          const parsed = extractJsonFromText(accumulatedText);
+          if (parsed) {
+            structuredOutputData = {
+              formatName: responseFormat.name,
+              data: parsed,
+              schema: responseFormat.schema,
+            };
+          } else {
+            console.warn('Failed to parse structured output from text response');
+          }
+        } else {
+          const output = await result.output;
+          if (output && typeof output === 'object') {
+            structuredOutputData = {
+              formatName: responseFormat.name,
+              data: output as Record<string, unknown>,
+              schema: responseFormat.schema,
+            };
+          }
+        }
+      } catch (_outputErr) {
+        console.warn('Failed to get structured output:', _outputErr);
+      }
+    }
+  } catch (_usageErr) {
+    console.warn('Failed to get usage data:', _usageErr);
+  }
+
+  return { usageData, structuredOutputData };
+}

package/src/core/stream/stream-config.ts

@@ -0,0 +1,82 @@
+import { Output, jsonSchema } from 'ai';
+import { findModel, findModelVariant, getLLMTemperature, getLLMMaxSteps, getModelsConfig } from '../../configuration/runtime';
+import { getProvider } from '../../providers/registry';
+import { buildSchemaPromptInstruction } from '../structured-output';
+import type { ResponseFormat } from '@capekai/types';
+
+export interface StreamConfigResult {
+  providerOptions: Record<string, Record<string, unknown>> | undefined;
+  usePromptBasedStructuredOutput: boolean;
+  streamOutput: ReturnType<typeof Output.object> | undefined;
+  temperature: number;
+  maxSteps: number;
+  /** System message with structured output instruction appended (if prompt-based mode) */
+  systemMessage: string;
+}
+
+export interface StreamConfigOptions {
+  modelId: string | undefined;
+  providerId: string | undefined;
+  variant: string | undefined;
+  systemMessage: string;
+  baseProviderOptions: Record<string, Record<string, unknown>> | undefined;
+  responseFormat?: ResponseFormat;
+  temperature?: number;
+  maxSteps?: number;
+}
+
+export function buildStreamConfig(options: StreamConfigOptions): StreamConfigResult {
+  const {
+    modelId,
+    providerId,
+    variant,
+    systemMessage,
+    baseProviderOptions,
+    responseFormat,
+    temperature,
+    maxSteps,
+  } = options;
+
+  // Resolve variant providerOptions
+  const variantOpts = variant ? findModelVariant(modelId || '', variant) : undefined;
+
+  // Determine the provider-specific providerOptions key
+  const resolvedProvider = providerId || getModelsConfig().defaultProvider;
+  const registered = resolvedProvider ? getProvider(resolvedProvider) : undefined;
+  const providerOptionsKey = registered?.descriptor.providerOptionsKey ?? resolvedProvider;
+
+  // Build merged providerOptions
+  let providerOptions: Record<string, Record<string, unknown>> | undefined;
+  if (baseProviderOptions) {
+    providerOptions = {
+      ...baseProviderOptions,
+      ...(variantOpts ? { [providerOptionsKey]: { ...(baseProviderOptions[providerOptionsKey] || {}), ...variantOpts } } : {}),
+    };
+  } else if (variantOpts) {
+    providerOptions = { [providerOptionsKey]: variantOpts };
+  }
+
+  // Structured output handling
+  const modelDef = modelId ? findModel(modelId) : undefined;
+  const structuredOutputMode = modelDef?.capabilities?.structuredOutput?.mode ?? 'native';
+  const usePromptBasedStructuredOutput: boolean =
+    !!(responseFormat && structuredOutputMode === 'prompt');
+
+  let finalSystemMessage = systemMessage;
+  if (usePromptBasedStructuredOutput && responseFormat && systemMessage) {
+    finalSystemMessage = systemMessage + '\n\n' + buildSchemaPromptInstruction(responseFormat);
+  }
+
+  const streamOutput = responseFormat && !usePromptBasedStructuredOutput
+    ? Output.object({ schema: jsonSchema(responseFormat.schema) })
+    : undefined;
+
+  return {
+    providerOptions,
+    usePromptBasedStructuredOutput,
+    streamOutput,
+    temperature: temperature ?? getLLMTemperature(),
+    maxSteps: maxSteps ?? getLLMMaxSteps(),
+    systemMessage: finalSystemMessage,
+  };
+}