dsh-lcx-codex 0.4.0 → 0.4.1

package/lib/route.js

@@ -1,44 +1,134 @@
+// @ts-check
+
 import { createHash, randomUUID } from 'node:crypto'
 import { attributionHeaders, resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 
+/** @typedef {Record<string, string>} HeaderMap */
+/** @typedef {Parameters<typeof resolveRetryPolicy>[0]} RetryPolicyConfig */
+/** @typedef {'none' | 'short' | 'long'} CacheRetention */
+/** @typedef {{ supportsDeveloperRole?: boolean, supportsStrictMode?: boolean, supportsLongCacheRetention?: boolean }} ResponsesCompat */
+/** @typedef {{ provider: string, model: string, baseURL: string, sessionId: string }} RouteIdentity */
+/** @typedef {{ provider?: unknown, model?: unknown, sessionId?: unknown }} RouteOptions */
+/** @typedef {{ id?: unknown, compat?: unknown }} ProviderModelProfile */
+/**
+ * @typedef {object} ProviderProfile
+ * @property {string} [api]
+ * @property {string} [baseURL]
+ * @property {string} [apiKeyEnv]
+ * @property {HeaderMap} [headers]
+ * @property {unknown} [cacheRetention]
+ * @property {number} [timeoutMs]
+ * @property {number} [maxRequestImageBytes]
+ * @property {number} [requestImagePixelBudget]
+ * @property {number} [requestImageMaxBytes]
+ * @property {RetryPolicyConfig} [retryPolicy]
+ * @property {unknown} [compat]
+ * @property {ProviderModelProfile[]} [models]
+ * @property {Record<string, ProviderModelProfile>} [modelOverrides]
+ */
+/** @typedef {{ providers?: Record<string, ProviderProfile> }} LlmSettingsSection */
+/** @typedef {{ get?: (namespace: unknown) => LlmSettingsSection | undefined }} SettingsService */
+/** @typedef {{ resolve?: (name: string) => Promise<{ value?: unknown } | undefined> }} CredentialsService */
+/** @typedef {{ id: string, header?: { parentSession?: string }, requestHeader?: () => RequestHeader | undefined }} RouteSession */
+/** @typedef {{ get?: (id: string) => RouteSession | undefined }} SessionsService */
+/**
+ * @typedef {object} RouteContext
+ * @property {((name: string) => unknown)} [get]
+ * @property {SettingsService} [settings]
+ * @property {CredentialsService} [credentials]
+ * @property {SessionsService} [sessions]
+ */
+/**
+ * Raw fallback values are not a resolved Responses route. cacheRetention is
+ * intentionally unknown until resolveResponsesRouteConfig normalizes it.
+ * @typedef {object} UnresolvedRouteConfig
+ * @property {string} provider
+ * @property {string} model
+ * @property {string} baseURL
+ * @property {string} apiKeyEnv
+ * @property {HeaderMap} [headers]
+ * @property {unknown} [cacheRetention]
+ * @property {unknown} [supportsLongCacheRetention]
+ * @property {unknown} [responsesCompat]
+ * @property {number} [timeoutMs]
+ * @property {number} [maxAttempts]
+ * @property {number} [maxRequestImageBytes]
+ * @property {number} [requestImagePixelBudget]
+ * @property {number} [requestImageMaxBytes]
+ */
+/**
+ * @typedef {UnresolvedRouteConfig & {
+ *   api: 'openai-responses',
+ *   cacheRetention: CacheRetention,
+ *   supportsLongCacheRetention: boolean,
+ *   responsesCompat?: ResponsesCompat
+ * }} ResolvedResponsesRoute
+ */
+/** @typedef {{ provider?: unknown, model?: unknown, reasoningEffort?: unknown, temperature?: unknown, maxTokens?: unknown }} RequestHeaderConfig */
+/** @typedef {{ config?: RequestHeaderConfig }} RequestHeader */
+/** @typedef {{ reasoningEffort?: unknown, temperature?: unknown, maxTokens?: unknown }} GenerationControls */
+/** @typedef {{ version: number, provider: unknown, model: unknown, baseURLFingerprint: unknown, sourceSessionId: unknown }} CheckpointRouteRecord */
+/** @typedef {Error & { code?: string }} LcxError */
+
+/** @param {unknown} value */
 export function normalizeBaseURL(value) {
   return String(value ?? '').trim().replace(/\/+$/u, '')
 }
 
+/** @param {unknown} model */
 export function isGptModel(model) {
   return /(^|[^a-z])gpt(?:[^a-z]|$)/iu.test(String(model ?? ''))
 }
 
+/** @param {unknown} baseURL */
 export function baseURLFingerprint(baseURL) {
   return createHash('sha256').update(normalizeBaseURL(baseURL), 'utf8').digest('hex')
 }
 
+/**
+ * @param {Partial<RouteIdentity> | null | undefined} route
+ * @param {{ includeSession?: boolean }} [options]
+ */
 export function routeFingerprint(route, options = {}) {
   const includeSession = options.includeSession !== false
   const fields = [route?.provider ?? '', route?.model ?? '', normalizeBaseURL(route?.baseURL), includeSession ? route?.sessionId ?? '' : '']
   return createHash('sha256').update(fields.join('\u001f'), 'utf8').digest('hex')
 }
 
+/** @param {unknown} value */
 function clampPromptCacheKey(value) {
   if (value === undefined) return undefined
   const chars = Array.from(String(value))
   return chars.length <= 64 ? String(value) : chars.slice(0, 64).join('')
 }
 
+/**
+ * @param {Partial<RouteIdentity> | null | undefined} route
+ * @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention'>>} [config]
+ */
 export function promptCacheSessionId(route, config = {}) {
   if (config?.cacheRetention === 'none') return undefined
   return route?.sessionId ? String(route.sessionId) : undefined
 }
 
+/**
+ * @param {Partial<RouteIdentity> | null | undefined} route
+ * @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention'>>} [config]
+ */
 export function promptCacheKey(route, config = {}) {
   return clampPromptCacheKey(promptCacheSessionId(route, config))
 }
 
+/** @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention' | 'supportsLongCacheRetention'>>} [config] */
 export function promptCacheRetention(config = {}) {
   return config?.cacheRetention === 'long' && config?.supportsLongCacheRetention !== false ? '24h' : undefined
 }
 
+/**
+ * @param {RetryPolicyConfig | null | undefined} policy
+ * @param {number} [fallback]
+ */
 function retryAttempts(policy, fallback = 3) {
   if (!policy || typeof policy !== 'object') return fallback
   try {
@@ -48,19 +138,34 @@ function retryAttempts(policy, fallback = 3) {
   return fallback
 }
 
+/**
+ * @param {RouteContext | null | undefined} ctx
+ * @param {string} namespace
+ */
 export function settingsValue(ctx, namespace) {
-  const settings = ctx?.get?.('settings') ?? ctx?.settings
+  const settings = /** @type {SettingsService | undefined} */ (ctx?.get?.('settings') ?? ctx?.settings)
   return settings?.get?.(settingsNamespace(namespace))
 }
 
+/** @type {Set<keyof ResponsesCompat>} */
 const RESPONSES_COMPAT_FIELDS = new Set(['supportsDeveloperRole', 'supportsStrictMode', 'supportsLongCacheRetention'])
 
+/**
+ * @param {ResponsesCompat} target
+ * @param {unknown} source
+ */
 function copyResponsesCompat(target, source) {
   if (!source || typeof source !== 'object') return
-  for (const field of RESPONSES_COMPAT_FIELDS) if (typeof source[field] === 'boolean') target[field] = source[field]
+  for (const field of RESPONSES_COMPAT_FIELDS) if (typeof /** @type {Record<keyof ResponsesCompat, unknown>} */ (source)[field] === 'boolean') target[field] = /** @type {boolean} */ (/** @type {Record<keyof ResponsesCompat, unknown>} */ (source)[field])
 }
 
+/**
+ * @param {ProviderProfile | null | undefined} profile
+ * @param {unknown} modelId
+ * @returns {ResponsesCompat | undefined}
+ */
 function configuredResponsesCompat(profile, modelId) {
+  /** @type {ResponsesCompat} */
   const compat = {}
   copyResponsesCompat(compat, profile?.compat)
   const configuredModels = Array.isArray(profile?.models) ? profile.models : []
@@ -71,6 +176,12 @@ function configuredResponsesCompat(profile, modelId) {
   return Object.keys(compat).length > 0 ? compat : undefined
 }
 
+/**
+ * @param {RouteContext | null | undefined} ctx
+ * @param {RouteOptions} options
+ * @param {UnresolvedRouteConfig} fallbackConfig
+ * @returns {ResolvedResponsesRoute | undefined}
+ */
 export function resolveResponsesRouteConfig(ctx, options, fallbackConfig) {
   if (!isGptModel(options?.model)) return undefined
   const provider = String(options?.provider ?? '')
@@ -84,9 +195,9 @@ export function resolveResponsesRouteConfig(ctx, options, fallbackConfig) {
       model: String(options.model),
       api: 'openai-responses',
       baseURL: normalizeBaseURL(fallbackConfig.baseURL),
-      cacheRetention: ['none', 'short', 'long'].includes(fallbackConfig.cacheRetention) ? fallbackConfig.cacheRetention : 'short',
+      cacheRetention: /** @type {CacheRetention} */ (['none', 'short', 'long'].includes(/** @type {string} */ (fallbackConfig.cacheRetention)) ? fallbackConfig.cacheRetention : 'short'),
       supportsLongCacheRetention: fallbackConfig.supportsLongCacheRetention !== false,
-      responsesCompat: fallbackConfig.responsesCompat && typeof fallbackConfig.responsesCompat === 'object' ? { ...fallbackConfig.responsesCompat } : undefined,
+      responsesCompat: fallbackConfig.responsesCompat && typeof fallbackConfig.responsesCompat === 'object' ? /** @type {ResponsesCompat} */ ({ ...fallbackConfig.responsesCompat }) : undefined,
     }
   }
   if (profile.api !== 'openai-responses') return undefined
@@ -102,38 +213,49 @@ export function resolveResponsesRouteConfig(ctx, options, fallbackConfig) {
     baseURL: normalizeBaseURL(baseURL),
     apiKeyEnv,
     headers: profile.headers && typeof profile.headers === 'object' ? { ...profile.headers } : { ...(fallbackConfig.headers ?? {}) },
-    cacheRetention: ['none', 'short', 'long'].includes(profile.cacheRetention) ? profile.cacheRetention : (['none', 'short', 'long'].includes(fallbackConfig.cacheRetention) ? fallbackConfig.cacheRetention : 'short'),
-    supportsLongCacheRetention: responsesCompat?.supportsLongCacheRetention ?? fallbackConfig.supportsLongCacheRetention ?? true,
+    cacheRetention: /** @type {CacheRetention} */ (['none', 'short', 'long'].includes(/** @type {string} */ (profile.cacheRetention)) ? profile.cacheRetention : (['none', 'short', 'long'].includes(/** @type {string} */ (fallbackConfig.cacheRetention)) ? fallbackConfig.cacheRetention : 'short')),
+    supportsLongCacheRetention: responsesCompat?.supportsLongCacheRetention ?? /** @type {boolean | undefined} */ (fallbackConfig.supportsLongCacheRetention) ?? true,
     responsesCompat,
-    timeoutMs: Number.isInteger(profile.timeoutMs) && profile.timeoutMs > 0 ? profile.timeoutMs : fallbackConfig.timeoutMs,
+    timeoutMs: Number.isInteger(profile.timeoutMs) && /** @type {number} */ (profile.timeoutMs) > 0 ? profile.timeoutMs : fallbackConfig.timeoutMs,
     maxAttempts: retryAttempts(profile.retryPolicy, fallbackConfig.maxAttempts),
-    maxRequestImageBytes: Number.isSafeInteger(profile.maxRequestImageBytes) && profile.maxRequestImageBytes > 0
+    maxRequestImageBytes: Number.isSafeInteger(profile.maxRequestImageBytes) && /** @type {number} */ (profile.maxRequestImageBytes) > 0
       ? profile.maxRequestImageBytes
       : fallbackConfig.maxRequestImageBytes,
-    requestImagePixelBudget: Number.isSafeInteger(profile.requestImagePixelBudget) && profile.requestImagePixelBudget > 0
+    requestImagePixelBudget: Number.isSafeInteger(profile.requestImagePixelBudget) && /** @type {number} */ (profile.requestImagePixelBudget) > 0
       ? profile.requestImagePixelBudget
       : fallbackConfig.requestImagePixelBudget,
-    requestImageMaxBytes: Number.isSafeInteger(profile.requestImageMaxBytes) && profile.requestImageMaxBytes > 0
+    requestImageMaxBytes: Number.isSafeInteger(profile.requestImageMaxBytes) && /** @type {number} */ (profile.requestImageMaxBytes) > 0
       ? profile.requestImageMaxBytes
       : fallbackConfig.requestImageMaxBytes,
   }
 }
 
+/**
+ * @param {RouteContext | null | undefined} ctx
+ * @param {Pick<ResolvedResponsesRoute, 'apiKeyEnv'>} config
+ */
 export async function resolveApiKey(ctx, config) {
-  const credentials = ctx?.get?.('credentials') ?? ctx?.credentials
+  const credentials = /** @type {CredentialsService | undefined} */ (ctx?.get?.('credentials') ?? ctx?.credentials)
   if (credentials?.resolve) {
     const resolved = await credentials.resolve(config.apiKeyEnv)
     if (typeof resolved?.value === 'string' && resolved.value.trim()) return resolved.value.trim()
   }
   const ambient = String(process.env[config.apiKeyEnv] ?? '').trim()
   if (ambient) return ambient
+  /** @type {LcxError} */
   const error = new Error(`DSH provider credential is unavailable: ${config.apiKeyEnv}`)
   error.code = 'LCX_CREDENTIAL_UNAVAILABLE'
   throw error
 }
 
+/**
+ * @param {HeaderMap | null | undefined} headers
+ * @param {string} name
+ */
 function hasHeader(headers, name) { return Object.keys(headers ?? {}).some((key) => key.toLowerCase() === name.toLowerCase()) }
+/** @param {HeaderMap | null | undefined} headers */
 function hasExplicitSessionAffinity(headers) { return ['session-id', 'session_id', 'x-session-id'].some((name) => hasHeader(headers, name)) }
+/** @param {Partial<ResolvedResponsesRoute> | null | undefined} config */
 function sessionAffinityFormat(config) {
   if (config?.api && config.api !== 'openai-responses') return 'none'
   const provider = String(config?.provider ?? '').toLowerCase()
@@ -141,8 +263,16 @@ function sessionAffinityFormat(config) {
   return provider === 'openrouter' || baseURL.includes('openrouter.ai') ? 'openrouter' : 'openai'
 }
 
+/**
+ * @param {RouteContext | null | undefined} ctx
+ * @param {ResolvedResponsesRoute} config
+ * @param {unknown} sessionId
+ * @param {string | null | undefined} requestId
+ * @returns {Promise<HeaderMap>}
+ */
 export async function authenticatedHeaders(ctx, config, sessionId, requestId) {
   const explicit = { ...(config.headers ?? {}) }
+  /** @type {HeaderMap} */
   const headers = {
     ...attributionHeaders(),
     authorization: `Bearer ${await resolveApiKey(ctx, config)}`,
@@ -160,6 +290,11 @@ export async function authenticatedHeaders(ctx, config, sessionId, requestId) {
   return { ...headers, ...explicit }
 }
 
+/**
+ * @param {RouteOptions | null | undefined} options
+ * @param {Pick<UnresolvedRouteConfig, 'provider' | 'model' | 'baseURL'>} config
+ * @returns {RouteIdentity}
+ */
 export function currentRoute(options, config) {
   return {
     provider: String(options?.provider ?? config.provider ?? ''),
@@ -169,9 +304,15 @@ export function currentRoute(options, config) {
   }
 }
 
+/**
+ * @param {RequestHeader | null | undefined} header
+ * @param {Partial<RouteIdentity> | null | undefined} route
+ * @returns {GenerationControls}
+ */
 export function generationControlsFromHeader(header, route) {
   const config = header?.config
   if (!config || String(config.provider ?? '') !== String(route?.provider ?? '') || String(config.model ?? '') !== String(route?.model ?? '')) return {}
+  /** @type {GenerationControls} */
   const controls = {}
   if (config.reasoningEffort !== undefined) controls.reasoningEffort = config.reasoningEffort
   if (config.temperature !== undefined) controls.temperature = config.temperature
@@ -179,11 +320,21 @@ export function generationControlsFromHeader(header, route) {
   return controls
 }
 
+/**
+ * @param {RouteSession | null | undefined} session
+ * @param {Partial<RouteIdentity> | null | undefined} route
+ * @returns {GenerationControls}
+ */
 export function generationControlsFromSession(session, route) {
   try { return generationControlsFromHeader(session?.requestHeader?.(), route) }
   catch { return {} }
 }
 
+/**
+ * @param {{ set?: (key: string, value: RequestHeader) => unknown } | null | undefined} cache
+ * @param {RouteSession | null | undefined} session
+ * @param {{ type?: string, data?: { header?: RequestHeader } } | null | undefined} event
+ */
 export function updateRequestHeaderCache(cache, session, event) {
   if (!cache?.set || !session?.id) return false
   let header
@@ -196,10 +347,16 @@ export function updateRequestHeaderCache(cache, session, event) {
   return true
 }
 
+/**
+ * @param {RouteContext | null | undefined} ctx
+ * @param {string | null | undefined} sessionId
+ * @returns {string[]}
+ */
 export function sessionAncestry(ctx, sessionId) {
   if (!sessionId) return []
-  const sessions = ctx?.get?.('sessions') ?? ctx?.sessions
+  const sessions = /** @type {SessionsService | undefined} */ (ctx?.get?.('sessions') ?? ctx?.sessions)
   const result = []
+  /** @type {Set<string>} */
   const seen = new Set()
   let current = sessions?.get?.(sessionId)
   while (current && !seen.has(current.id)) {
@@ -212,6 +369,11 @@ export function sessionAncestry(ctx, sessionId) {
   return result
 }
 
+/**
+ * @param {CheckpointRouteRecord | null | undefined} record
+ * @param {RouteIdentity} route
+ * @param {unknown} ctx
+ */
 export function routeCompatible(record, route, ctx) {
   if (!record || ![4, 5].includes(record.version)) return false
   if (record.provider !== route.provider || record.model !== route.model) return false

package/lib/token-budget.js

@@ -0,0 +1,165 @@
+// @ts-check
+
+/** @typedef {Record<string, unknown>} UnknownRecord */
+
+export const PORTABLE_BUDGET_ERROR_CODE = 'LCX_PORTABLE_BUDGET_EXCEEDED'
+const MAX_BUDGET_INPUT_CHARS = 2_000_000
+const CONSERVATIVE_IMAGE_TOKEN_COST = 2_048
+const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u
+const ASCII_WORD = /[A-Za-z0-9]/u
+const STRUCTURAL = /[\p{P}\p{S}]/u
+const DATA_URI = /^data:[^;,\s]+(?:;[^,\s]*)?;base64,[A-Za-z0-9+/\s]+={0,2}$/u
+const ENCODED_TEXT = /^[A-Za-z0-9+/_-]{512,}={0,2}$/u
+
+/** @param {string} value */
+function looksEncodedText(value) { return DATA_URI.test(value) || ENCODED_TEXT.test(value) }
+
+/**
+ * A small conservative fallback, deliberately not a tokenizer. The baseline
+ * preserves legacy /4 while CJK and structural characters cost more.
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+export function estimateTextTokens(value) {
+  if (typeof value !== 'string') return undefined
+  if (value.length > MAX_BUDGET_INPUT_CHARS || looksEncodedText(value)) return Math.max(1, value.length)
+  let weighted = 0
+  let asciiRun = 0
+  const flushAscii = () => { if (asciiRun > 0) weighted += Math.ceil(asciiRun / 4); asciiRun = 0 }
+  for (const char of value) {
+    if (ASCII_WORD.test(char)) { asciiRun += 1; continue }
+    flushAscii()
+    if (/\s/u.test(char)) continue
+    if (CJK.test(char) || STRUCTURAL.test(char)) weighted += 1
+    else weighted += Math.ceil(char.length / 2)
+  }
+  flushAscii()
+  return Math.max(1, Math.ceil(value.length / 4), weighted)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is UnknownRecord}
+ */
+function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
+/**
+ * @param {unknown} value
+ * @param {Set<object>} [seen]
+ * @returns {boolean}
+ */
+function containsOpaqueValue(value, seen = new Set()) {
+  if (value === null || typeof value !== 'object') return false
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer || seen.has(value)) return true
+  seen.add(value)
+  return Object.values(value).some((entry) => containsOpaqueValue(entry, seen))
+}
+/** @param {unknown} value */
+function safeJson(value) { try { if (containsOpaqueValue(value)) return undefined; const encoded = JSON.stringify(value); return typeof encoded === 'string' ? encoded : undefined } catch { return undefined } }
+/** @param {unknown} value */
+function safeScalar(value) { return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' ? String(value) : undefined }
+
+/**
+ * @param {unknown} content
+ * @returns {unknown[] | undefined}
+ */
+function visibleContent(content) {
+  if (typeof content === 'string') return [{ type: 'text', text: content }]
+  if (!Array.isArray(content)) return undefined
+  const parts = []
+  for (const part of content) {
+    if (!isObject(part) || typeof part.type !== 'string') return undefined
+    if (['text', 'input_text', 'output_text'].includes(part.type)) {
+      if (typeof part.text !== 'string') return undefined
+      parts.push({ type: part.type, text: part.text })
+      continue
+    }
+    if (part.type === 'reasoning') {
+      if (typeof part.text !== 'string') return undefined
+      parts.push({ type: 'reasoning', text: part.text })
+      continue
+    }
+    if (part.type === 'tool-call') {
+      const id = safeScalar(part.id); const name = safeScalar(part.name); const argumentsText = safeJson(part.arguments)
+      if (id === undefined || name === undefined || argumentsText === undefined) return undefined
+      parts.push({ type: 'tool-call', id, name, arguments: argumentsText })
+      continue
+    }
+    if (part.type === 'tool-result') {
+      const toolCallId = safeScalar(part.toolCallId); const toolName = safeScalar(part.toolName ?? part.name ?? 'unknown'); const nested = visibleContent(part.content)
+      if (toolCallId === undefined || toolName === undefined || nested === undefined) return undefined
+      parts.push({ type: 'tool-result', toolCallId, toolName, content: nested })
+      continue
+    }
+    if (['image', 'input_image', 'output_image', 'dsh_image_attachment'].includes(part.type)) {
+      parts.push({ type: part.type, image: true })
+      continue
+    }
+    return undefined
+  }
+  return parts
+}
+
+/**
+ * Project an item to model-visible fields only. Opaque provider state, raw
+ * binary, and replay/session metadata are intentionally excluded.
+ * @param {unknown} item
+ * @returns {unknown | undefined}
+ */
+export function modelVisibleBudgetView(item) {
+  if (!isObject(item)) return undefined
+  if (item.type === 'function_call') {
+    const callId = safeScalar(item.call_id); const name = safeScalar(item.name); const argumentsText = safeJson(item.arguments)
+    return callId === undefined || name === undefined || argumentsText === undefined ? undefined : { type: 'function_call', call_id: callId, name, arguments: argumentsText }
+  }
+  if (item.type === 'function_call_output') {
+    const callId = safeScalar(item.call_id); const output = typeof item.output === 'string' ? item.output : safeJson(item.output)
+    return callId === undefined || output === undefined ? undefined : { type: 'function_call_output', call_id: callId, output }
+  }
+  if (item.type !== undefined && item.type !== 'message') return undefined
+  if (!['developer', 'system', 'user', 'assistant'].includes(String(item.role ?? ''))) return undefined
+  const content = visibleContent(item.content)
+  return content === undefined ? undefined : { role: String(item.role), content }
+}
+
+/**
+ * Images have provider/model-dependent costs. Count each known image block with
+ * a fixed conservative surcharge without inspecting base64 or attachment data.
+ * @param {unknown} value
+ * @returns {number}
+ */
+function imageTokenCost(value) {
+  if (Array.isArray(value)) {
+    let total = 0
+    for (const entry of value) total += imageTokenCost(entry)
+    return total
+  }
+  if (!isObject(value)) return 0
+  let total = value.image === true ? CONSERVATIVE_IMAGE_TOKEN_COST : 0
+  for (const entry of Object.values(value)) total += imageTokenCost(entry)
+  return total
+}
+
+/**
+ * @param {unknown} item
+ * @returns {number | undefined}
+ */
+export function estimateBudgetItem(item) {
+  const view = modelVisibleBudgetView(item)
+  if (view === undefined) return undefined
+  const encoded = safeJson(view)
+  const textCost = estimateTextTokens(encoded)
+  return textCost === undefined ? undefined : textCost + imageTokenCost(view)
+}
+
+/** @param {unknown} maxChars */
+export function portableTokenCeiling(maxChars) {
+  return Number.isSafeInteger(maxChars) && /** @type {number} */ (maxChars) > 0 ? Math.ceil(/** @type {number} */ (maxChars) / 4) : undefined
+}
+
+/** @param {string} message */
+export function portableBudgetError(message) {
+  /** @type {Error & { code?: string }} */
+  const error = new Error(message)
+  error.code = PORTABLE_BUDGET_ERROR_CODE
+  return error
+}