@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/src/mcp/telemetry.js

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { homeDirectory } from './authority.js';
+
+export function getTelemetrySessionPath(options = {}) {
+  const home = homeDirectory(options);
+  return path.join(home, '.agentsam', 'telemetry', 'session-receipts.json');
+}
+
+export function recordToolReceipt(receipt = {}, options = {}) {
+  const filePath = getTelemetrySessionPath(options);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  let existing = [];
+  try {
+    if (fs.existsSync(filePath)) {
+      existing = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      if (!Array.isArray(existing)) existing = [];
+    }
+  } catch {
+    existing = [];
+  }
+
+  const normalized = {
+    id: receipt.id || `tcl_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    agent_run_id: receipt.agent_run_id || null,
+    conversation_id: receipt.conversation_id || null,
+    tool_key: String(receipt.tool_key || receipt.tool || receipt.name || 'unknown'),
+    source_client: receipt.source_client || 'agentsam',
+    status: receipt.status || (receipt.error ? 'failure' : 'success'),
+    duration_ms: Number(receipt.duration_ms ?? receipt.latency_ms ?? 0),
+    error_code: receipt.error_code || (receipt.error ? 'EXECUTION_ERROR' : null),
+    failure_origin: receipt.failure_origin || null,
+    created_at: receipt.created_at || new Date().toISOString(),
+  };
+
+  existing.push(normalized);
+  fs.writeFileSync(filePath, JSON.stringify(existing, null, 2), 'utf8');
+  return normalized;
+}
+
+export function getSessionToolReceipts(options = {}) {
+  const filePath = getTelemetrySessionPath(options);
+  try {
+    if (!fs.existsSync(filePath)) return [];
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return Array.isArray(data) ? data : [];
+  } catch {
+    return [];
+  }
+}
+
+export function clearSessionToolReceipts(options = {}) {
+  const filePath = getTelemetrySessionPath(options);
+  try {
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export function summarizeToolReceipts(receipts = []) {
+  let toolCallCount = 0;
+  let mcpCallCount = 0;
+  let terminalCallCount = 0;
+  let githubCallCount = 0;
+  let d1CallCount = 0;
+  let failureCount = 0;
+
+  for (const r of receipts) {
+    toolCallCount += 1;
+    const key = (r.tool_key || '').toLowerCase();
+    if (key.startsWith('mcp:') || key.includes('mcp') || r.source_client === 'cursor_mcp') {
+      mcpCallCount += 1;
+    }
+    if (key.includes('terminal') || key.includes('bash') || key.includes('shell')) {
+      terminalCallCount += 1;
+    }
+    if (key.includes('github') || key.includes('gh_') || key.includes('git')) {
+      githubCallCount += 1;
+    }
+    if (key.includes('d1') || key.includes('sqlite') || key.includes('database')) {
+      d1CallCount += 1;
+    }
+    if (r.status === 'failure' || r.error_code) {
+      failureCount += 1;
+    }
+  }
+
+  return {
+    tool_call_count: toolCallCount,
+    mcp_call_count: mcpCallCount,
+    terminal_call_count: terminalCallCount,
+    github_call_count: githubCallCount,
+    d1_call_count: d1CallCount,
+    failure_count: failureCount,
+    success_count: toolCallCount - failureCount,
+  };
+}

package/src/models/ai-access-onboarding.js

@@ -0,0 +1,112 @@
+/**
+ * Onboarding guidance when a user has no usable AI path yet.
+ *
+ * Paths (any one unlocks AgentSam model options):
+ *   1. Local Ollama + at least one model
+ *   2. Provider API key (OpenAI / Anthropic / Gemini / …) → their allotted models
+ *   3. Signed-in Local Studio identity + Cloudflare OAuth (Workers AI / account tools)
+ */
+
+export const LOCAL_STUDIO_ORIGIN = 'https://agentsam.inneranimalmedia.com';
+
+/** Identity login (Sign in with Cloudflare) — PKCE public client. */
+export const CF_OAUTH_LOGIN_START = `${LOCAL_STUDIO_ORIGIN}/api/oauth/cloudflare/start?next=/agentsam`;
+
+/** Resource connector (MCP / Workers / D1) — same CF OAuth client, different callback. */
+export const CF_OAUTH_CONNECT_START = `${LOCAL_STUDIO_ORIGIN}/api/connections/cloudflare/start`;
+
+/** Login portal with explicit next (desktop / CLI). */
+export const LOCAL_STUDIO_LOGIN = `${LOCAL_STUDIO_ORIGIN}/auth/login?next=/agentsam`;
+
+/**
+ * Redirect URIs that must be registered on the Cloudflare OAuth client
+ * "AgentSam Local Studio" (PKCE, Token Authentication Method = None).
+ */
+export const CF_OAUTH_REQUIRED_REDIRECTS = Object.freeze([
+  `${LOCAL_STUDIO_ORIGIN}/api/oauth/cloudflare/callback`,
+  `${LOCAL_STUDIO_ORIGIN}/api/connections/cloudflare/callback`,
+  'http://localhost:3000/api/connections/cloudflare/callback',
+  'http://localhost:3000/api/oauth/cloudflare/callback',
+]);
+
+/**
+ * @param {{ inventory?: object, ollama?: object, providers?: object[] }} discovered
+ *   Shape compatible with discoverIngestModelOptions() / collectModelsStatus().
+ */
+export function assessAiAccess(discovered = {}) {
+  const providers = discovered.inventory?.providers
+    || discovered.providers
+    || [];
+  const configuredProviders = providers.filter((p) => p?.configured === true);
+  const ollamaOnline = Boolean(discovered.ollama?.online || discovered.inventory?.local?.online);
+  const ollamaModels = discovered.ollama?.models || discovered.inventory?.local?.models || [];
+  const hasOllamaModels = ollamaOnline && Array.isArray(ollamaModels) && ollamaModels.length > 0;
+  const hasProviderKeys = configuredProviders.length > 0;
+  const embedOptions = Array.isArray(discovered.options)
+    ? discovered.options.filter((o) => o.value && o.value !== 'none')
+    : [];
+
+  const ready = hasOllamaModels || hasProviderKeys || embedOptions.length > 0;
+
+  return {
+    ready,
+    hasOllamaModels,
+    hasProviderKeys,
+    configuredProviders: configuredProviders.map((p) => p.id),
+    ollamaOnline,
+    ollamaModelCount: hasOllamaModels ? ollamaModels.length : 0,
+    embedOptionCount: embedOptions.length,
+  };
+}
+
+/**
+ * Human-readable onboarding block for CLI notes / stderr.
+ * @param {ReturnType<typeof assessAiAccess>} access
+ * @param {{ wantCloudAi?: boolean }} [opts]
+ */
+export function formatAiAccessOnboarding(access, opts = {}) {
+  const lines = [];
+  if (access.ready) {
+    lines.push('AI access: ready');
+    if (access.hasProviderKeys) {
+      lines.push(`  providers  ${access.configuredProviders.join(', ')}`);
+    }
+    if (access.hasOllamaModels) {
+      lines.push(`  ollama     online · ${access.ollamaModelCount} model(s)`);
+    }
+    if (access.embedOptionCount) {
+      lines.push(`  embed menu ${access.embedOptionCount} option(s)`);
+    }
+    return lines.join('\n');
+  }
+
+  lines.push('AI access: not configured yet');
+  lines.push('');
+  lines.push('Pick ONE path to unlock AgentSam model options:');
+  lines.push('');
+  lines.push('  1) Local models (Ollama) — free, offline');
+  lines.push('       https://ollama.com/download');
+  lines.push('       ollama pull mxbai-embed-large');
+  lines.push('       ollama pull qwen2.5-coder');
+  lines.push('       agentsam ollama status');
+  lines.push('');
+  lines.push('  2) Provider API key — use models your key is allotted');
+  lines.push('       agentsam providers');
+  lines.push('       (OpenAI · Anthropic · Gemini · Cursor · xAI · Cloudflare token)');
+  lines.push('');
+  lines.push('  3) Local Studio identity + Cloudflare OAuth');
+  lines.push('       (Workers AI / account tools / MCP connector)');
+  lines.push(`       Login:  ${LOCAL_STUDIO_LOGIN}`);
+  lines.push(`       CF sign-in: ${CF_OAUTH_LOGIN_START}`);
+  lines.push(`       CF connect: ${CF_OAUTH_CONNECT_START}`);
+  if (opts.wantCloudAi) {
+    lines.push('');
+    lines.push('  Cloudflare OAuth client must allow these redirect URIs:');
+    for (const uri of CF_OAUTH_REQUIRED_REDIRECTS) {
+      lines.push(`       • ${uri}`);
+    }
+  }
+  lines.push('');
+  lines.push('AST/text-only indexing still works with embedding: none ($0).');
+  return lines.join('\n');
+}

package/src/models/catalog.js

@@ -1,68 +1,305 @@
 export const MODEL_CATALOG_SCHEMA = 'agentsam-model-catalog-v1';
 
-const ASTRA_SOURCE = 'https://developers.openai.com/api/docs/models/gpt-6-astra';
+const DOCS = Object.freeze({
+  gpt6Astra: 'https://developers.openai.com/api/docs/models/gpt-6-astra',
+  gpt6Sol: 'https://developers.openai.com/api/docs/models/gpt-6-sol',
+  gpt6Luna: 'https://developers.openai.com/api/docs/models/gpt-6-luna',
+  gpt56Sol: 'https://developers.openai.com/api/docs/models/gpt-5.6-sol',
+  gpt56Terra: 'https://developers.openai.com/api/docs/models/gpt-5.6-terra',
+  gpt56Luna: 'https://developers.openai.com/api/docs/models/gpt-5.6-luna',
+  gpt53Codex: 'https://developers.openai.com/api/docs/models/gpt-5.3-codex',
+  embeddingLarge: 'https://developers.openai.com/api/docs/models/text-embedding-3-large',
+  embeddingSmall: 'https://developers.openai.com/api/docs/models/text-embedding-3-small',
+});
 
-const GPT_6_ASTRA = Object.freeze({
-  schema_version: 1,
-  model_key: 'openai:gpt-6-astra',
-  provider: 'openai',
-  provider_model_id: 'gpt-6-astra',
-  label: 'GPT-6 Astra',
-  context_window: 1_050_000,
-  max_output_tokens: 128_000,
-  reasoning_efforts: Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']),
-  service_tiers: Object.freeze(['default', 'fast', 'flex']),
-  capabilities: Object.freeze({
-    responses: true,
-    streaming: true,
-    function_calling: true,
-    structured_outputs: true,
-    prompt_caching: true,
-    compaction: true,
-    tool_search: true,
-    async_tool_calls: true,
-    mid_turn_steering: true,
-    configuration_update: true,
-    batch: true,
-    fast: true,
-    flex: true,
-  }),
-  pricing: Object.freeze({
+const LONG_CONTEXT_POLICY = Object.freeze({
+  target_input_tokens: 120_000,
+  compact_at_tokens: 180_000,
+  intervene_at_tokens: 220_000,
+  max_normal_input_tokens: 250_000,
+  pricing_threshold_tokens: 272_000,
+  max_cumulative_input_tokens: 544_000,
+  safety_margin_tokens: 22_000,
+});
+
+const FULL_RESPONSES_TOOLS = Object.freeze({
+  web_search: true,
+  file_search: true,
+  image_generation: true,
+  code_interpreter: true,
+  hosted_shell: true,
+  apply_patch: true,
+  skills: true,
+  computer_use: true,
+  mcp: true,
+  tool_search: true,
+});
+
+const STANDARD_AGENT_CAPABILITIES = Object.freeze({
+  agent_runtime: true,
+  responses: true,
+  streaming: true,
+  function_calling: true,
+  structured_outputs: true,
+  prompt_caching: true,
+  compaction: true,
+  batch: true,
+  fast: true,
+  flex: true,
+  ...FULL_RESPONSES_TOOLS,
+});
+
+function freezePricing({ input, cachedInput, cacheWrite, output, source, longContext = true, processing = true }) {
+  return Object.freeze({
     currency: 'USD',
     unit: 'per_million_tokens',
-    input: 10,
-    cached_input: 1,
-    cache_write: 12.5,
-    output: 50,
-    thresholds: Object.freeze([
+    input,
+    cached_input: cachedInput,
+    cache_write: cacheWrite,
+    output,
+    thresholds: Object.freeze(longContext ? [
       Object.freeze({
         input_tokens_gt: 272_000,
         applies_to_full_request: true,
         multipliers: Object.freeze({ input: 2, cached_input: 2, cache_write: 2, output: 1.5 }),
       }),
-    ]),
-    service_tier_multipliers: Object.freeze({ default: 1, fast: 2, flex: 0.5, batch: 0.5 }),
-    source: ASTRA_SOURCE,
-    as_of: '2026-09-12',
-  }),
-  context_policy: Object.freeze({
-    target_input_tokens: 120_000,
-    compact_at_tokens: 180_000,
-    intervene_at_tokens: 220_000,
-    max_normal_input_tokens: 250_000,
-    pricing_threshold_tokens: 272_000,
-    safety_margin_tokens: 22_000,
+    ] : []),
+    service_tier_multipliers: Object.freeze(processing
+      ? { default: 1, fast: 2, flex: 0.5, batch: 0.5 }
+      : { default: 1 }),
+    source,
+    as_of: '2026-09-23',
+  });
+}
+
+function openAiAgentModel({
+  id,
+  label,
+  source,
+  reasoning,
+  contextWindow,
+  maxOutputTokens,
+  knowledgeCutoff,
+  description,
+  pricing,
+  capabilities = {},
+  serviceTiers = ['default', 'fast', 'flex'],
+  contextPolicy = LONG_CONTEXT_POLICY,
+}) {
+  return Object.freeze({
+    schema_version: 1,
+    model_key: 'openai:' + id,
+    provider: 'openai',
+    provider_model_id: id,
+    label,
+    kind: 'language',
+    description,
+    context_window: contextWindow,
+    max_output_tokens: maxOutputTokens,
+    knowledge_cutoff: knowledgeCutoff,
+    reasoning_efforts: Object.freeze([...reasoning]),
+    default_reasoning_effort: reasoning.includes('medium') ? 'medium' : reasoning[0],
+    service_tiers: Object.freeze([...serviceTiers]),
+    capabilities: Object.freeze({ ...STANDARD_AGENT_CAPABILITIES, ...capabilities }),
+    pricing,
+    context_policy: contextPolicy,
+    batch: Object.freeze({
+      supported: true,
+      completion_window: '24h',
+      relative_price: 0.5,
+      interactive: false,
+    }),
+    source: Object.freeze({ url: source, as_of: '2026-09-23' }),
+  });
+}
+
+function openAiEmbeddingModel({ id, label, source, dimensions, price }) {
+  return Object.freeze({
+    schema_version: 1,
+    model_key: 'openai:' + id,
+    provider: 'openai',
+    provider_model_id: id,
+    label,
+    kind: 'embedding',
+    description: 'Text embedding model for semantic search and retrieval.',
+    context_window: 8_192,
+    max_output_tokens: null,
+    knowledge_cutoff: null,
+    reasoning_efforts: Object.freeze([]),
+    default_reasoning_effort: null,
+    service_tiers: Object.freeze(['default']),
+    capabilities: Object.freeze({
+      agent_runtime: false,
+      responses: false,
+      function_calling: false,
+      embeddings: true,
+      configurable_dimensions: true,
+    }),
+    pricing: freezePricing({
+      input: price,
+      cachedInput: 0,
+      cacheWrite: 0,
+      output: 0,
+      source,
+      longContext: false,
+      processing: false,
+    }),
+    context_policy: null,
+    batch: Object.freeze({ supported: true, completion_window: '24h', relative_price: 0.5, interactive: false }),
+    source: Object.freeze({ url: source, as_of: '2026-09-23' }),
+    metadata: Object.freeze({ default_dimensions: dimensions, max_input_tokens: 8_192 }),
+  });
+}
+
+const GPT_6_ASTRA = openAiAgentModel({
+  id: 'gpt-6-astra',
+  label: 'GPT-6 Astra',
+  source: DOCS.gpt6Astra,
+  reasoning: ['low', 'medium', 'high', 'xhigh', 'max'],
+  contextWindow: 1_050_000,
+  maxOutputTokens: 128_000,
+  knowledgeCutoff: '2026-04-30',
+  description: 'Highest-capability GPT-6 tier for the hardest end-to-end work.',
+  pricing: freezePricing({ input: 10, cachedInput: 1, cacheWrite: 12.5, output: 50, source: DOCS.gpt6Astra }),
+  capabilities: { async_tool_calls: true, mid_turn_steering: true, configuration_update: true },
+});
+
+const GPT_6_SOL = openAiAgentModel({
+  id: 'gpt-6-sol',
+  label: 'GPT-6 Sol',
+  source: DOCS.gpt6Sol,
+  reasoning: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
+  contextWindow: 1_050_000,
+  maxOutputTokens: 128_000,
+  knowledgeCutoff: '2026-04-20',
+  description: 'GPT-6 tier for complex coding and agentic workflows.',
+  pricing: freezePricing({ input: 2, cachedInput: 0.2, cacheWrite: 2.5, output: 10, source: DOCS.gpt6Sol }),
+  capabilities: { async_tool_calls: true, mid_turn_steering: true, configuration_update: true },
+});
+
+const GPT_6_LUNA = openAiAgentModel({
+  id: 'gpt-6-luna',
+  label: 'GPT-6 Luna',
+  source: DOCS.gpt6Luna,
+  reasoning: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
+  contextWindow: 1_050_000,
+  maxOutputTokens: 128_000,
+  knowledgeCutoff: '2026-05-18',
+  description: 'Most efficient GPT-6 tier for focused, high-volume tasks.',
+  pricing: freezePricing({ input: 0.1, cachedInput: 0.01, cacheWrite: 0.125, output: 0.5, source: DOCS.gpt6Luna }),
+  capabilities: { async_tool_calls: true, mid_turn_steering: true, configuration_update: true },
+});
+
+const GPT_56_SOL = openAiAgentModel({
+  id: 'gpt-5.6-sol',
+  label: 'GPT-5.6 Sol',
+  source: DOCS.gpt56Sol,
+  reasoning: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
+  contextWindow: 1_050_000,
+  maxOutputTokens: 128_000,
+  knowledgeCutoff: '2026-02-16',
+  description: 'Flagship GPT-5.6 model for complex professional work.',
+  pricing: freezePricing({ input: 4, cachedInput: 0.4, cacheWrite: 5, output: 20, source: DOCS.gpt56Sol }),
+});
+
+const GPT_56_TERRA = openAiAgentModel({
+  id: 'gpt-5.6-terra',
+  label: 'GPT-5.6 Terra',
+  source: DOCS.gpt56Terra,
+  reasoning: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
+  contextWindow: 1_050_000,
+  maxOutputTokens: 128_000,
+  knowledgeCutoff: '2026-02-16',
+  description: 'GPT-5.6 tier balancing intelligence and cost.',
+  pricing: freezePricing({ input: 2, cachedInput: 0.2, cacheWrite: 2.5, output: 12, source: DOCS.gpt56Terra }),
+});
+
+const GPT_56_LUNA = openAiAgentModel({
+  id: 'gpt-5.6-luna',
+  label: 'GPT-5.6 Luna',
+  source: DOCS.gpt56Luna,
+  reasoning: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
+  contextWindow: 1_050_000,
+  maxOutputTokens: 128_000,
+  knowledgeCutoff: '2026-02-16',
+  description: 'Cost-sensitive GPT-5.6 tier for high-volume workloads.',
+  pricing: freezePricing({ input: 0.2, cachedInput: 0.02, cacheWrite: 0.25, output: 1.2, source: DOCS.gpt56Luna }),
+});
+
+const GPT_53_CODEX = openAiAgentModel({
+  id: 'gpt-5.3-codex',
+  label: 'GPT-5.3-Codex',
+  source: DOCS.gpt53Codex,
+  reasoning: ['low', 'medium', 'high', 'xhigh'],
+  contextWindow: 400_000,
+  maxOutputTokens: 128_000,
+  knowledgeCutoff: '2025-08-31',
+  description: 'Agentic coding model for Codex-style software workflows.',
+  pricing: freezePricing({
+    input: 1.75,
+    cachedInput: 0.175,
+    cacheWrite: 0,
+    output: 14,
+    source: DOCS.gpt53Codex,
+    longContext: false,
+    processing: false,
   }),
-  batch: Object.freeze({
-    supported: true,
-    completion_window: '24h',
-    relative_price: 0.5,
-    interactive: false,
+  capabilities: {
+    web_search: false,
+    file_search: false,
+    image_generation: false,
+    code_interpreter: false,
+    hosted_shell: false,
+    apply_patch: false,
+    skills: false,
+    computer_use: false,
+    mcp: false,
+    tool_search: false,
+    async_tool_calls: false,
+    mid_turn_steering: false,
+    configuration_update: false,
+    fast: false,
+    flex: false,
+  },
+  serviceTiers: ['default'],
+  contextPolicy: Object.freeze({
+    target_input_tokens: 100_000,
+    compact_at_tokens: 160_000,
+    intervene_at_tokens: 210_000,
+    max_normal_input_tokens: 240_000,
+    pricing_threshold_tokens: null,
+    max_cumulative_input_tokens: 400_000,
+    safety_margin_tokens: 20_000,
   }),
-  source: Object.freeze({ url: ASTRA_SOURCE, as_of: '2026-09-12' }),
 });
 
-export const MODEL_CATALOG = Object.freeze([GPT_6_ASTRA]);
+const TEXT_EMBEDDING_3_LARGE = openAiEmbeddingModel({
+  id: 'text-embedding-3-large',
+  label: 'text-embedding-3-large',
+  source: DOCS.embeddingLarge,
+  dimensions: 3_072,
+  price: 0.13,
+});
+
+const TEXT_EMBEDDING_3_SMALL = openAiEmbeddingModel({
+  id: 'text-embedding-3-small',
+  label: 'text-embedding-3-small',
+  source: DOCS.embeddingSmall,
+  dimensions: 1_536,
+  price: 0.02,
+});
+
+export const MODEL_CATALOG = Object.freeze([
+  GPT_6_LUNA,
+  GPT_6_SOL,
+  GPT_6_ASTRA,
+  GPT_56_LUNA,
+  GPT_56_TERRA,
+  GPT_56_SOL,
+  GPT_53_CODEX,
+  TEXT_EMBEDDING_3_LARGE,
+  TEXT_EMBEDDING_3_SMALL,
+]);
 
 function clean(value) {
   return value == null ? '' : String(value).trim();
@@ -85,6 +322,47 @@ export function getModelRecord(value) {
   return MODEL_CATALOG.find((row) => row.model_key === key || row.provider_model_id === key) || null;
 }
 
+export function mergeModelReference(snapshot) {
+  if (!snapshot || typeof snapshot !== 'object') return null;
+  const reference = getModelRecord(snapshot.model_key || snapshot.provider_model_id);
+  if (!reference) return snapshot;
+
+  const providerContext = snapshot.context_window_source === 'provider_api'
+    && Number.isFinite(Number(snapshot.context_window))
+    && Number(snapshot.context_window) > 0;
+  const providerMaxOutput = snapshot.max_output_tokens_source === 'provider_api'
+    && Number.isFinite(Number(snapshot.max_output_tokens))
+    && Number(snapshot.max_output_tokens) > 0;
+
+  return Object.freeze({
+    ...snapshot,
+    ...reference,
+    model_key: snapshot.model_key || reference.model_key,
+    provider: snapshot.provider || reference.provider,
+    provider_model_id: snapshot.provider_model_id || reference.provider_model_id,
+    availability: snapshot.availability,
+    availability_source: snapshot.availability_source,
+    context_window: providerContext ? Number(snapshot.context_window) : reference.context_window ?? snapshot.context_window ?? null,
+    context_window_source: providerContext
+      ? 'provider_api'
+      : reference.context_window ? 'sdk_reference' : snapshot.context_window_source || 'unknown',
+    max_output_tokens: providerMaxOutput ? Number(snapshot.max_output_tokens) : reference.max_output_tokens ?? snapshot.max_output_tokens ?? null,
+    max_output_tokens_source: providerMaxOutput
+      ? 'provider_api'
+      : reference.max_output_tokens ? 'sdk_reference' : snapshot.max_output_tokens_source || 'unknown',
+    reasoning_efforts: reference.reasoning_efforts?.length
+      ? reference.reasoning_efforts
+      : snapshot.reasoning_efforts || Object.freeze(['auto']),
+    default_reasoning_effort: reference.default_reasoning_effort || snapshot.default_reasoning_effort || null,
+    service_tiers: reference.service_tiers?.length ? reference.service_tiers : snapshot.service_tiers || Object.freeze(['default']),
+    capabilities: Object.freeze({ ...(snapshot.capabilities || {}), ...(reference.capabilities || {}) }),
+    pricing: reference.pricing || snapshot.pricing || null,
+    context_policy: reference.context_policy || snapshot.context_policy || null,
+    source: reference.source || snapshot.source || null,
+    metadata: Object.freeze({ ...(snapshot.metadata || {}), ...(reference.metadata || {}) }),
+  });
+}
+
 export function calculateModelCost(model, usage = {}, options = {}) {
   const record = typeof model === 'string' ? getModelRecord(model) : model;
   if (!record?.pricing) throw new TypeError('model pricing record is required');