@sixb/core 0.1.20 → 0.1.22

package/src/models/catalog.ts

@@ -13,6 +13,8 @@ import {
   type ModelDefinition,
 } from "./definitions"
 import { assertEmbeddingModel, type EmbeddingModel } from "./embedding-model"
+import { createImageCatalog, type ImageModelCatalog } from "./image/catalog"
+import type { ImageModel } from "./image/types"
 import {
   type LanguageModel,
   MODEL_REASONING_LEVELS,
@@ -46,11 +48,42 @@ export interface RerankingModelCatalog {
   getByRef(ref: ModelRef): RerankingModelEntry | null
 }
 
+/** The cost and strength classes a project can configure language models in. */
+export const LANGUAGE_MODEL_TIERS = ["light", "standard", "heavy"] as const
+
+export type LanguageModelTier = (typeof LANGUAGE_MODEL_TIERS)[number]
+
+/** How likely a decision model judged each tier, each from 0 to 1. */
+export type LanguageModelTierProbabilities = Readonly<Record<LanguageModelTier, number>>
+
+export function isLanguageModelTier(value: unknown): value is LanguageModelTier {
+  return (LANGUAGE_MODEL_TIERS as readonly unknown[]).includes(value)
+}
+
+/** The tiers as errors list them: "light, standard or heavy". */
+export function formatLanguageModelTiers(): string {
+  const last = LANGUAGE_MODEL_TIERS.at(-1)
+  return `${LANGUAGE_MODEL_TIERS.slice(0, -1).join(", ")} or ${last}`
+}
+
+/** Language models by tier; each takes a model or an ordered list, whose first is the tier's. */
+export interface LanguageModelTiers {
+  readonly light?: LanguageModel | readonly LanguageModel[]
+  /** Its first model is the project default, and stands in for a tier left out. */
+  readonly standard: LanguageModel | readonly LanguageModel[]
+  readonly heavy?: LanguageModel | readonly LanguageModel[]
+}
+
 /** The configured language models, with the project default. */
 export interface LanguageModelCatalog {
   readonly default: LanguageModelEntry
+  /** The tiers the project configures, in tier order; empty when `models.language` is a list. */
+  readonly tiers: readonly LanguageModelTier[]
+  /** Configured order; with tiers, light, standard then heavy, each tier in its own order. */
   list(): readonly LanguageModelEntry[]
   getByRef(ref: LanguageModelRef): LanguageModelEntry | null
+  /** The tier's first model; a tier left out, or any tier of a list, gives the default. */
+  getByTier(tier: LanguageModelTier): LanguageModelEntry
 }
 
 /**
@@ -62,6 +95,8 @@ export interface LanguageModelCatalog {
  */
 export interface LanguageModelEntry extends LanguageModelRef {
   readonly model: LanguageModel
+  /** The tier the model is configured in; absent when `models.language` is a list. */
+  readonly tier?: LanguageModelTier
 }
 
 /** Models a project allows Sixb to use, organized by technical model kind. */
@@ -70,23 +105,33 @@ export interface ModelCatalog {
   readonly language?: LanguageModelCatalog
   readonly decision?: DecisionModelCatalog
   readonly embedding: EmbeddingModelCatalog
+  readonly image?: ImageModelCatalog
   readonly reranking?: RerankingModelCatalog
 }
 
 export interface ModelCatalogInput {
   readonly audio?: AudioModelCatalogInput
-  /** Ordered; the first entry is the project default. */
-  readonly language?: readonly LanguageModel[]
+  /**
+   * Ordered, the first entry being the project default; or tiers, whose first `standard` model is
+   * the default.
+   */
+  readonly language?: readonly LanguageModel[] | LanguageModelTiers
   /** Ordered; the first entry is the project default decision model. */
   readonly decision?: readonly DecisionModel[]
   readonly embedding?: readonly EmbeddingModel[]
+  /** Ordered; the first entry is the default image model. */
+  readonly image?: readonly ImageModel[]
   /** Available rerankers; no default model and no automatic activation. */
   readonly reranking?: readonly RerankingModel[]
 }
 
 // Only statically required inputs make their corresponding catalogs required.
 type ConfiguredModelKinds<TInput> = {
-  [Kind in keyof ModelCatalog]-?: [TInput] extends [Record<Kind, readonly unknown[]>] ? Kind : never
+  [Kind in keyof ModelCatalog]-?: [TInput] extends [
+    Record<Kind, readonly unknown[] | LanguageModelTiers>,
+  ]
+    ? Kind
+    : never
 }[keyof ModelCatalog]
 
 export type ModelCatalogFor<TInput extends ModelCatalogInput> = ModelCatalog &
@@ -97,6 +142,13 @@ export type ModelCatalogFor<TInput extends ModelCatalogInput> = ModelCatalog &
           readonly transcription: NonNullable<AudioModelCatalog["transcription"]>
         }
       }
+    : unknown) &
+  ([TInput] extends [{ readonly audio: { readonly speech: readonly unknown[] } }]
+    ? {
+        readonly audio: AudioModelCatalog & {
+          readonly speech: NonNullable<AudioModelCatalog["speech"]>
+        }
+      }
     : unknown)
 
 /** Build an immutable catalog while preserving each family's default and empty-list rules. */
@@ -112,21 +164,23 @@ export function createModelCatalog(input: ModelCatalogInput): ModelCatalog {
   const embedding = createEmbeddingCatalog(input.embedding)
   const decision = createDecisionCatalog(input.decision)
   const audio = createAudioCatalog(input.audio)
+  const image = createImageCatalog(input.image)
   const reranking = createRerankingCatalog(input.reranking)
 
   if (
     !language &&
     !decision &&
     !audio &&
+    !image &&
     embedding.list().length === 0 &&
     !reranking?.list().length
   ) {
     throw new RuntimeError(
-      "[Sixb] Configure at least one language, embedding, decision, audio or reranking model."
+      "[Sixb] Configure at least one language, embedding, decision, audio, image or reranking model."
     )
   }
 
-  return Object.freeze({ language, embedding, decision, audio, reranking })
+  return Object.freeze({ language, embedding, decision, audio, image, reranking })
 }
 
 function createRerankingCatalog(
@@ -140,25 +194,112 @@ function createRerankingCatalog(
 }
 
 function createLanguageCatalog(
-  models: readonly LanguageModel[] | undefined
+  input: ModelCatalogInput["language"]
 ): LanguageModelCatalog | undefined {
-  if (models === undefined) return undefined
-  if (!Array.isArray(models)) {
-    throw new RuntimeError("[Sixb] 'models.language' must be an array of Sixb language models.")
-  }
+  if (input === undefined) return undefined
 
-  const index = indexModelBindings(models, "language", (model, position) => {
-    assertLanguageModel(model, position)
-    assertDefaultReasoning(model, position)
-  })
-  const [defaultEntry] = index.list()
+  const configured = configuredLanguageModels(input)
+  const index = indexModelBindings(
+    configured.map(({ model }) => model),
+    "language",
+    (model, position) => {
+      const { path } = configured[position]
+      assertValidLanguageModel(model, (detail) => invalidLanguageModel(path, detail))
+    },
+    (position): Pick<LanguageModelEntry, "tier"> => {
+      const { tier } = configured[position]
+      return tier === undefined ? {} : { tier }
+    }
+  )
+  const entries = index.list()
+
+  const defaultEntry = entries.find((entry) => entry.tier === "standard") ?? entries[0]
   if (!defaultEntry) {
     throw new RuntimeError(
       "[Sixb] 'models.language' needs at least one model. Configure one or omit 'models.language'."
     )
   }
 
-  return Object.freeze({ ...index, default: defaultEntry })
+  const tiers = LANGUAGE_MODEL_TIERS.filter((tier) => entries.some((entry) => entry.tier === tier))
+
+  return Object.freeze({
+    ...index,
+    default: defaultEntry,
+    tiers: Object.freeze(tiers),
+    getByTier: (tier: LanguageModelTier) =>
+      entries.find((entry) => entry.tier === tier) ?? defaultEntry,
+  })
+}
+
+/**
+ * The model code runs: its own as given, a tier's model from the catalog, or the default. A string
+ * that is not a tier throws, since a caller's types may not have checked it.
+ */
+export function selectLanguageModel(
+  catalog: LanguageModelCatalog | undefined,
+  model: LanguageModel | LanguageModelTier | undefined
+): LanguageModel | undefined {
+  if (model === undefined) return catalog?.default.model
+  if (typeof model !== "string") return model
+
+  if (!isLanguageModelTier(model)) {
+    throw new TypeError(
+      `[Sixb] Unknown model tier '${model}'. Use ${formatLanguageModelTiers()}, or pass a model.`
+    )
+  }
+
+  return catalog?.getByTier(model).model
+}
+
+interface ConfiguredLanguageModel {
+  readonly model: LanguageModel
+  readonly tier?: LanguageModelTier
+  /** Where the model was configured, for its errors. */
+  readonly path: string
+}
+
+/** Flatten a list, or tiers in tier order, without validating the models themselves. */
+function configuredLanguageModels(
+  input: readonly LanguageModel[] | LanguageModelTiers
+): readonly ConfiguredLanguageModel[] {
+  if (Array.isArray(input)) {
+    return input.map((model, index) => ({ model, path: `models.language[${index}]` }))
+  }
+  if (typeof input !== "object" || input === null) {
+    throw new RuntimeError(
+      "[Sixb] 'models.language' must be an array of Sixb language models, or tiers: { light, standard, heavy }."
+    )
+  }
+
+  const unknown = Object.keys(input).find((key) => !isLanguageModelTier(key))
+  if (unknown !== undefined) {
+    throw new RuntimeError(
+      `[Sixb] Unknown model tier '${unknown}' in 'models.language'. Use ${formatLanguageModelTiers()}, or pass an array of models.`
+    )
+  }
+  // Array.isArray does not narrow a readonly array out of the union.
+  const tiers = input as LanguageModelTiers
+  if (tiers.standard === undefined) {
+    throw new RuntimeError(
+      "[Sixb] 'models.language' tiers need 'standard': its first model is the project default."
+    )
+  }
+
+  return LANGUAGE_MODEL_TIERS.flatMap((tier) => {
+    const models = tiers[tier]
+    if (models === undefined) return []
+    if (!Array.isArray(models)) {
+      return [{ model: models, tier, path: `models.language.${tier}` }]
+    }
+    if (models.length === 0) {
+      throw new RuntimeError(`[Sixb] 'models.language.${tier}' needs at least one model.`)
+    }
+    return models.map((model, index) => ({
+      model,
+      tier,
+      path: `models.language.${tier}[${index}]`,
+    }))
+  })
 }
 
 function createEmbeddingCatalog(
@@ -171,33 +312,66 @@ function createEmbeddingCatalog(
   return indexModelBindings(models ?? [], "embedding", assertEmbeddingModel)
 }
 
+/** Builds the error for an invalid language model, naming where it was configured. */
+type InvalidLanguageModel = (detail: string) => Error
+
+/**
+ * Check a language model the project configures, in the catalog or on an agent step: its shape
+ * and identity, its default reasoning and its output limit.
+ */
+export function assertValidLanguageModel(
+  model: unknown,
+  fail: InvalidLanguageModel
+): asserts model is LanguageModel {
+  assertLanguageModel(model, fail)
+  assertDefaultReasoning(model, fail)
+  assertMaxOutputTokens(model, fail)
+}
+
 // Capabilities known without catalog I/O. Unknown support is accepted: providers fall back to their
 // default when a resolved model turns out not to support the level.
-function assertDefaultReasoning(model: LanguageModel, index: number): void {
+function assertDefaultReasoning(model: LanguageModel, fail: InvalidLanguageModel): void {
   const reasoning: unknown = model.defaultReasoning
   if (reasoning === undefined) return
   if (!(MODEL_REASONING_LEVELS as readonly unknown[]).includes(reasoning)) {
-    throw invalidLanguageModel(
-      index,
-      `expected 'defaultReasoning' to be one of: ${MODEL_REASONING_LEVELS.join(", ")}`
-    )
+    throw fail(`expected 'defaultReasoning' to be one of: ${MODEL_REASONING_LEVELS.join(", ")}`)
   }
   const issue = modelReasoningSupportIssue(model.definition.capabilities.reasoning, reasoning)
   if (issue !== undefined) {
-    throw invalidLanguageModel(index, `default reasoning '${reasoning}' cannot be used: ${issue}`)
+    throw fail(`default reasoning '${reasoning}' cannot be used: ${issue}`)
   }
 }
 
-function assertLanguageModel(model: unknown, index: number): asserts model is LanguageModel {
+// Providers validate their own options; this holds the same rule for providers written elsewhere.
+function assertMaxOutputTokens(model: LanguageModel, fail: InvalidLanguageModel): void {
+  const maxOutputTokens: unknown = model.maxOutputTokens
+  if (maxOutputTokens === undefined) return
+  if (
+    typeof maxOutputTokens !== "number" ||
+    !Number.isSafeInteger(maxOutputTokens) ||
+    maxOutputTokens <= 0
+  ) {
+    throw fail("expected 'maxOutputTokens' to be a positive safe integer")
+  }
+  const modelMaximum = model.definition.maxOutputTokens
+  if (modelMaximum !== undefined && maxOutputTokens > modelMaximum) {
+    throw fail(`'maxOutputTokens' (${maxOutputTokens}) exceeds the model maximum (${modelMaximum})`)
+  }
+}
+
+function assertLanguageModel(
+  model: unknown,
+  fail: InvalidLanguageModel
+): asserts model is LanguageModel {
   if ((typeof model !== "object" && typeof model !== "function") || model === null) {
-    throw invalidLanguageModel(index, "expected a Sixb LanguageModel instance")
+    throw fail("expected a Sixb LanguageModel instance")
   }
 
   const candidate = model as Record<string, unknown>
-  assertModelIdentifier(candidate.providerId, "provider", index)
-  assertModelIdentifier(candidate.modelId, "modelId", index)
+  assertModelIdentifier(candidate.providerId, "provider", fail)
+  assertModelIdentifier(candidate.modelId, "modelId", fail)
   if (typeof candidate.stream !== "function") {
-    throw invalidLanguageModel(index, "expected 'stream' to be a function")
+    throw fail("expected 'stream' to be a function")
   }
   try {
     const definition = defineLanguageModel(candidate.definition as LanguageModelDefinition)
@@ -208,23 +382,25 @@ function assertLanguageModel(model: unknown, index: number): asserts model is La
       throw new Error("definition identity does not match the binding")
     }
   } catch (error) {
-    throw invalidLanguageModel(index, error instanceof Error ? error.message : "invalid definition")
+    throw fail(error instanceof Error ? error.message : "invalid definition")
   }
 }
 
-function assertModelIdentifier(value: unknown, field: "provider" | "modelId", index: number): void {
+function assertModelIdentifier(
+  value: unknown,
+  field: "provider" | "modelId",
+  fail: InvalidLanguageModel
+): void {
   if (typeof value !== "string" || value.length === 0) {
-    throw invalidLanguageModel(index, `expected '${field}' to be a non-empty string`)
+    throw fail(`expected '${field}' to be a non-empty string`)
   }
   if (value.trim() !== value) {
-    throw invalidLanguageModel(index, `expected '${field}' not to have surrounding whitespace`)
+    throw fail(`expected '${field}' not to have surrounding whitespace`)
   }
 }
 
-function invalidLanguageModel(index: number, detail: string): RuntimeError {
-  return new RuntimeError(
-    `[Sixb] Invalid language model at 'models.language[${index}]': ${detail}.`
-  )
+function invalidLanguageModel(path: string, detail: string): RuntimeError {
+  return new RuntimeError(`[Sixb] Invalid language model at '${path}': ${detail}.`)
 }
 
 /** Provider-owned metadata lookup, independent from the project's configured bindings. */

package/src/models/decision/runtime.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto"
-import { assertProviderAccess } from "../../authorization"
+import { assertAuthorized, assertModelAccess } from "../../authorization"
 import type { ExecutionContext } from "../../execution"
 import { cloneJsonValue } from "../../json"
 import type { SixbRuntimeContext } from "../../runtime/types"
@@ -25,15 +25,27 @@ import {
   validateDecisionAnswers,
 } from "./validation"
 
+/**
+ * Who may ask: code and the API need `can.run(project.models)`; the Agent asks on a turn's behalf,
+ * which running the Agent authorizes.
+ */
+export type DecisionAccess = "models" | "agent.run"
+
 export function createDecisionRuntime(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext,
   catalog: ModelCatalog | undefined,
-  session: ModelExecutionSession
+  session: ModelExecutionSession,
+  access: DecisionAccess
 ): DecisionModelsRuntime {
+  function assertAccess(): void {
+    if (access === "agent.run") assertAuthorized(runtime, { kind: "agent.run" })
+    else assertModelAccess(runtime, execution, "models.decision.evaluate")
+  }
+
   return {
     async evaluate(input) {
-      assertProviderAccess(runtime, execution, "models.decision.evaluate")
+      assertAccess()
       assertDecisionContent(input.input, "input")
       assertDecisionQuestions(input.questions)
 
@@ -109,27 +121,13 @@ function resolveDecisionModel(
   catalog: ModelCatalog | undefined,
   requested: DecisionModel | undefined
 ): DecisionModel {
-  if (!requested) {
-    const model = catalog?.decision?.default.model
-    if (!model) {
-      throw new Error("[SixbModels] Configure models.decision or supply a model to evaluate().")
-    }
-    return model
+  // A model the caller passes runs as given, listed or not; the catalog supplies the default.
+  const selected = requested ?? catalog?.decision?.default.model
+  if (!selected) {
+    throw new Error("[SixbModels] Configure models.decision or supply a model to evaluate().")
   }
 
-  if (!catalog) return requested
-
-  // The catalog owns the binding, even when a caller supplies another object with the same ID.
-  const entry = catalog.decision?.getByRef({
-    provider: requested.providerId,
-    modelId: requested.modelId,
-  })
-  if (!entry) {
-    throw new Error(
-      `[SixbModels] Model '${requested.providerId}/${requested.modelId}' is not configured in models.decision.`
-    )
-  }
-  return entry.model
+  return selected
 }
 
 async function admitDecisionCall(
@@ -170,6 +168,7 @@ async function recordDecision(
   })
   const event = {
     callId,
+    modelKind: "decision" as const,
     providerId: model.providerId,
     modelId: model.modelId,
     responseId: metadata.providerIds?.responseId ?? callId,

package/src/models/decision/validation.ts

@@ -144,7 +144,10 @@ export function assertDecisionSupport(model: DecisionModel, questions: DecisionQ
   }
 }
 
-function supportsQuestion(capabilities: DecisionCapabilities, question: DecisionQuestion): boolean {
+export function supportsQuestion(
+  capabilities: DecisionCapabilities,
+  question: DecisionQuestion
+): boolean {
   if (!capabilities.questions.includes(question.type)) return false
 
   switch (question.type) {

package/src/models/definitions.ts

@@ -5,14 +5,30 @@ import {
   type ModelReasoningCapabilities,
 } from "./language-model"
 
-export type ModelKind =
-  | "language"
-  | "image"
-  | "video"
-  | "embedding"
-  | "decision"
-  | "transcription"
-  | "reranking"
+/** @internal Every model kind, for validating stored values. */
+export const MODEL_KINDS = [
+  "language",
+  "image",
+  "video",
+  "embedding",
+  "decision",
+  "transcription",
+  "speech",
+  "reranking",
+] as const
+
+export type ModelKind = (typeof MODEL_KINDS)[number]
+
+/**
+ * @internal Kinds billed per audio second, search, image or character, whose providers mostly
+ * report no tokens. Token limits skip them, and a missing token count from one is not a gap.
+ */
+export const TOKENLESS_MODEL_KINDS: readonly ModelKind[] = [
+  "transcription",
+  "reranking",
+  "image",
+  "speech",
+]
 
 /** Common catalog identity shared by every present and future model runtime. */
 export interface ModelDefinition {
@@ -41,6 +57,39 @@ export interface LanguageModelDefinition extends ModelDefinition {
   readonly capabilities: ModelCapabilities
 }
 
+/** The name and description a project gives a language model, in place of the provider's. */
+export interface LanguageModelLabel {
+  /** Shown in the chat's model picker and to the Agent. */
+  readonly name?: string
+  /** When the model is useful, for the people choosing it and for the Agent delegating to it. */
+  readonly description?: string
+}
+
+/**
+ * The label a model binding sets, checked and reported with the provider's error prefix. A provider
+ * spreads it over every definition it builds for the binding, its resolved ones included.
+ *
+ * Stricter than `defineLanguageModel`, which takes a provider's catalog text as it comes: the
+ * project types a label by hand, so an empty or padded value is a mistake to report.
+ */
+export function defineLanguageModelLabel(
+  label: LanguageModelLabel,
+  prefix: string
+): LanguageModelLabel {
+  for (const field of ["name", "description"] as const) {
+    const value: unknown = label[field]
+
+    if (value !== undefined && (typeof value !== "string" || !value || value !== value.trim())) {
+      throw new TypeError(`${prefix} ${field} must be a nonempty trimmed string.`)
+    }
+  }
+
+  return {
+    ...(label.name === undefined ? {} : { name: label.name }),
+    ...(label.description === undefined ? {} : { description: label.description }),
+  }
+}
+
 export function defineLanguageModel(definition: LanguageModelDefinition): LanguageModelDefinition {
   if (definition.kind !== "language") {
     throw new TypeError("[Sixb] Language model definitions must use kind 'language'.")

package/src/models/events.ts

@@ -1,4 +1,4 @@
-import type { JsonObject, JsonValue } from "../json"
+import { isJsonValue, isPlainRecord, type JsonObject, type JsonValue } from "../json"
 import type { ModelReasoning } from "./language-model"
 import type {
   ModelAssistantPart,
@@ -57,6 +57,14 @@ export interface ModelUsage {
   readonly cacheWrite1hInputTokens?: number
   readonly textOutputTokens?: number
   readonly reasoningOutputTokens?: number
+  /** Output tokens that encode generated images, within outputTokens. */
+  readonly imageOutputTokens?: number
+  /** Output tokens that encode generated audio, within outputTokens. */
+  readonly audioOutputTokens?: number
+  /** Images the call returned. */
+  readonly outputImages?: number
+  /** Input characters, counted by the provider's own billing rule. */
+  readonly inputCharacters?: number
   readonly raw?: JsonObject
 }
 
@@ -169,6 +177,69 @@ export type ModelUiChunk =
     }
   | { readonly type: "error"; readonly errorText: string }
 
+export const MODEL_UI_CHUNK_TYPES = [
+  "start-step",
+  "text-start",
+  "text-delta",
+  "text-end",
+  "reasoning-start",
+  "reasoning-delta",
+  "reasoning-end",
+  "tool-input-start",
+  "tool-input-delta",
+  "tool-input-available",
+  "tool-input-error",
+  "tool-output-available",
+  "tool-output-error",
+  "error",
+] as const satisfies readonly ModelUiChunk["type"][]
+
+type ChunkFields = Readonly<Record<string, unknown>>
+
+// Keyed by the union itself, so a chunk variant added without its check does not compile.
+const MODEL_UI_CHUNK_FIELDS_ARE_VALID: {
+  readonly [TType in ModelUiChunk["type"]]: (chunk: ChunkFields) => boolean
+} = {
+  "start-step": () => true,
+  "text-start": hasSpanId,
+  "text-delta": (chunk) => hasSpanId(chunk) && typeof chunk.delta === "string",
+  "text-end": hasSpanId,
+  "reasoning-start": hasSpanId,
+  "reasoning-delta": (chunk) => hasSpanId(chunk) && typeof chunk.delta === "string",
+  "reasoning-end": hasSpanId,
+  "tool-input-start": hasToolCall,
+  "tool-input-delta": (chunk) => hasToolCall(chunk) && typeof chunk.inputTextDelta === "string",
+  "tool-input-available": (chunk) => hasToolCall(chunk) && hasJson(chunk, "input"),
+  "tool-input-error": (chunk) =>
+    hasToolCall(chunk) && hasJson(chunk, "input") && typeof chunk.errorText === "string",
+  "tool-output-available": (chunk) => hasToolCall(chunk) && hasJson(chunk, "output"),
+  "tool-output-error": (chunk) => hasToolCall(chunk) && typeof chunk.errorText === "string",
+  error: (chunk) => typeof chunk.errorText === "string",
+}
+
+/** A known chunk type with every field it requires. Fields a newer producer adds are allowed. */
+export function isModelUiChunk(value: unknown): value is ModelUiChunk {
+  if (!isPlainRecord(value) || !isModelUiChunkType(value.type)) return false
+
+  return MODEL_UI_CHUNK_FIELDS_ARE_VALID[value.type](value)
+}
+
+function isModelUiChunkType(value: unknown): value is ModelUiChunk["type"] {
+  return typeof value === "string" && (MODEL_UI_CHUNK_TYPES as readonly string[]).includes(value)
+}
+
+function hasSpanId(chunk: ChunkFields): boolean {
+  return typeof chunk.id === "string"
+}
+
+function hasToolCall(chunk: ChunkFields): boolean {
+  return typeof chunk.toolCallId === "string" && typeof chunk.toolName === "string"
+}
+
+function hasJson(chunk: ChunkFields, field: string): boolean {
+  return Object.hasOwn(chunk, field) && isJsonValue(chunk[field])
+}
+
 export interface ModelCallEndEvent {
   readonly modelKind?: import("./definitions").ModelKind
   readonly providerIds?: ModelProviderIds