@sixb/core 0.1.6 → 0.1.8

package/src/agents/model-loop.ts

@@ -0,0 +1,1071 @@
+import { randomUUID } from "node:crypto"
+import {
+  assertJsonObject,
+  assertJsonValue,
+  isJsonValue,
+  isPlainRecord,
+  type JsonValue,
+} from "../json"
+import { ModelProviderError, ModelStreamError, StructuredOutputError } from "../models/errors"
+import type {
+  LanguageModelStreamEvent,
+  ModelCallEndEvent,
+  ModelFinishReason,
+  ModelStep,
+  ModelUiChunk,
+  ModelUsage,
+} from "../models/events"
+import type {
+  LanguageModel,
+  ModelReasoning,
+  ModelToolSpecification,
+} from "../models/language-model"
+import type {
+  ModelAssistantPart,
+  ModelMessage,
+  ModelProviderStatePart,
+  ModelTextPart,
+  ModelToolCallPart,
+  ModelToolOutput,
+  ModelToolResultPart,
+  ProviderData,
+} from "../models/messages"
+import {
+  estimateModelCall,
+  type ModelCallCost,
+  type ModelReportedCost,
+  rateModelCall,
+} from "../models/pricing"
+import type { ModelOutput, ModelTool } from "../models/tools"
+
+const MAX_PROVIDER_DATA_BYTES = 256 * 1024
+
+interface ModelLoopOptions {
+  readonly model: LanguageModel
+  readonly messages: readonly ModelMessage[]
+  readonly tools?: readonly ModelTool[]
+  readonly reasoning?: ModelReasoning
+  readonly maxOutputTokens?: number
+  readonly caching?: "auto" | "off"
+  readonly maxSteps: number
+  readonly signal: AbortSignal
+  /** Reserve the final provider call for a tool-free synthesis response. */
+  readonly finalStepInstruction?: string
+  readonly prepareStep?: (
+    input: PrepareModelStepInput
+  ) => PrepareModelStepResult | undefined | Promise<PrepareModelStepResult | undefined>
+  readonly onEvent?: (event: ModelUiChunk) => void | Promise<void>
+  readonly onModelCallEnd?: (event: ModelCallEndEvent) => void | Promise<void>
+  readonly onStepEnd?: (step: ModelStep) => void | Promise<void>
+  readonly generateCallId?: () => string
+}
+
+/** Non-text output requires a validator; unvalidated text can only inhabit types accepting string. */
+export type RunModelLoopInput<TOutput = string> = ModelLoopOptions &
+  (
+    | { readonly output: ModelOutput<TOutput> }
+    | (string extends TOutput ? { readonly output?: undefined } : never)
+  )
+
+export interface PrepareModelStepInput {
+  readonly stepIndex: number
+  readonly messages: readonly ModelMessage[]
+  readonly model: LanguageModel
+  readonly signal: AbortSignal
+}
+
+export interface PrepareModelStepResult {
+  /** Replacement history retained for this request and subsequent steps. */
+  readonly messages?: readonly ModelMessage[]
+}
+
+export type ModelLoopResult<TOutput = string> =
+  | {
+      readonly status: "completed"
+      readonly output: TOutput
+      readonly steps: readonly ModelStep[]
+      readonly finishReason: ModelFinishReason
+    }
+  | {
+      readonly status: "aborted"
+      readonly steps: readonly ModelStep[]
+      readonly partialContent: readonly ModelAssistantPart[]
+    }
+
+interface CompletedResponse {
+  readonly providerIds?: import("../models/events").ModelProviderIds
+  readonly content: readonly ModelAssistantPart[]
+  readonly toolCalls: readonly ParsedToolCall[]
+  readonly finishReason: ModelFinishReason
+  readonly rawFinishReason?: string
+  readonly usage: ModelUsage
+  readonly responseId?: string
+  readonly responseModelId?: string
+  readonly projectionError?: Error
+  readonly reportedCost?: ModelReportedCost
+  readonly route?: import("../models/events").ModelRoute
+}
+
+interface ParsedToolCall {
+  readonly part: ModelToolCallPart
+  readonly inputError?: Error
+}
+
+/**
+ * Run a provider-neutral, streaming model/tool loop.
+ *
+ * One step is exactly one provider call. Lifecycle and stream callbacks are awaited so the caller
+ * controls backpressure and can fail closed before another billable call starts.
+ * Completed steps and partial content contain validated JSON payloads and normalized provider
+ * metadata. Trace adapters may project these results directly; storage owns write validation.
+ */
+export function runModelLoop<TOutput = string>(
+  input: RunModelLoopInput<TOutput>
+): Promise<ModelLoopResult<TOutput>>
+export async function runModelLoop(
+  input: RunModelLoopInput<unknown>
+): Promise<ModelLoopResult<unknown>> {
+  assertLoopInput(input)
+  const tools = indexTools(input.tools ?? [])
+  const toolSpecifications = [...tools.values()].map<ModelToolSpecification>((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  }))
+  let messages: readonly ModelMessage[] = [...input.messages]
+  const steps: ModelStep[] = []
+  const generateCallId = input.generateCallId ?? (() => `model_call_${randomUUID()}`)
+  const callIds = new Set<string>()
+
+  for (let stepIndex = 0; stepIndex < input.maxSteps; stepIndex += 1) {
+    if (input.signal.aborted) {
+      return { status: "aborted", steps, partialContent: [] }
+    }
+    await input.onEvent?.({ type: "start-step" })
+
+    let requestMessages: readonly ModelMessage[]
+    try {
+      const prepared = await input.prepareStep?.({
+        stepIndex,
+        messages,
+        model: input.model,
+        signal: input.signal,
+      })
+      requestMessages = prepared?.messages ?? messages
+    } catch (error) {
+      if (!input.signal.aborted && !isAbortError(error)) throw error
+      return { status: "aborted", steps, partialContent: [] }
+    }
+    if (input.signal.aborted) {
+      return { status: "aborted", steps, partialContent: [] }
+    }
+    let requestTools: readonly ModelToolSpecification[] = toolSpecifications
+    if (input.finalStepInstruction !== undefined && stepIndex === input.maxSteps - 1) {
+      requestMessages = [
+        ...requestMessages,
+        { role: "user", content: [{ type: "text", text: input.finalStepInstruction }] },
+      ]
+      requestTools = []
+    }
+
+    const callId = generateCallId()
+    if (!callId || callIds.has(callId)) {
+      throw new ModelStreamError(`[SixbModels] Model call IDs must be nonempty and unique.`)
+    }
+    callIds.add(callId)
+    const accumulator = new StreamAccumulator(input.onEvent)
+    let accepted = false
+    let cost: ModelCallCost = { status: "unpriceable", reason: "missing-usage" }
+    let terminalStreamError: { readonly error: unknown } | undefined
+    try {
+      const stream = await input.model.stream({
+        callId,
+        messages: requestMessages,
+        tools: requestTools,
+        ...(input.reasoning === undefined ? {} : { reasoning: input.reasoning }),
+        ...(input.maxOutputTokens === undefined ? {} : { maxOutputTokens: input.maxOutputTokens }),
+        ...(input.caching === undefined ? {} : { caching: input.caching }),
+        ...(input.output === undefined
+          ? {}
+          : {
+              responseFormat: {
+                type: "json" as const,
+                name: input.output.name,
+                ...(input.output.description === undefined
+                  ? {}
+                  : { description: input.output.description }),
+                schema: input.output.schema,
+              },
+            }),
+        signal: input.signal,
+      })
+      accepted = true
+      for await (const event of stream.events) {
+        await accumulator.accept(event)
+      }
+    } catch (error) {
+      const aborted = input.signal.aborted || isAbortError(error)
+      if (accumulator.isFinished()) {
+        if (!aborted) terminalStreamError = { error }
+      } else if (!aborted) {
+        throw error
+      } else {
+        return {
+          status: "aborted",
+          steps,
+          partialContent: accumulator.partialContent(),
+        }
+      }
+    } finally {
+      // Once a stream is accepted, cancellation or protocol failure cannot erase the call.
+      // Only a finish event establishes final meters; interrupted calls remain explicitly unknown.
+      if (accepted) {
+        const facts = accumulator.accounting()
+        const estimate = accumulator.isFinished() ? estimateModelCall(input.model, facts) : cost
+        cost = facts.reportedCost
+          ? rateModelCall({ usage: facts.usage, reported: facts.reportedCost })
+          : estimate
+        await input.onModelCallEnd?.({
+          callId,
+          providerId: input.model.providerId,
+          modelId: input.model.modelId,
+          responseId: facts.responseId ?? `${callId}:response`,
+          providerIds: facts.providerIds,
+          responseModelId: facts.responseModelId,
+          usage: facts.usage,
+          cost,
+          ...(facts.reportedCost === undefined ? {} : { estimate }),
+          ...(input.reasoning === undefined ? {} : { requestedReasoning: input.reasoning }),
+          ...(facts.route === undefined ? {} : { route: facts.route }),
+        })
+      }
+    }
+
+    if (input.signal.aborted && !accumulator.isFinished()) {
+      return { status: "aborted", steps, partialContent: accumulator.partialContent() }
+    }
+    const response = accumulator.complete()
+    const responseId = response.responseId ?? `${callId}:response`
+    if (terminalStreamError) throw terminalStreamError.error
+    if (response.projectionError) throw response.projectionError
+    if (input.signal.aborted) {
+      return { status: "aborted", steps, partialContent: response.content }
+    }
+
+    const localCalls = response.toolCalls.filter((call) => call.part.providerExecuted !== true)
+    if (response.finishReason === "pause" && localCalls.length === 0) {
+      const step = modelStep(response, responseId, response.content, cost)
+      steps.push(step)
+      await input.onStepEnd?.(step)
+      messages = [...requestMessages, { role: "assistant", content: response.content }]
+      if (stepIndex + 1 === input.maxSteps) {
+        throw new ModelStreamError(
+          "[SixbModels] Model reached the step limit while a provider continuation was pending."
+        )
+      }
+      continue
+    }
+    if (localCalls.length === 0) {
+      const step = modelStep(response, responseId, response.content, cost)
+      steps.push(step)
+      await input.onStepEnd?.(step)
+      if (input.output) {
+        const text = responseText(response)
+        if (response.finishReason !== "stop") {
+          throw new StructuredOutputError(
+            `[SixbModels] Structured output did not complete successfully (${response.finishReason}).`,
+            structuredOutputErrorContext(input, response, responseId, cost, text)
+          )
+        }
+        let raw: unknown
+        try {
+          raw = JSON.parse(text)
+        } catch (error) {
+          throw new StructuredOutputError("[SixbModels] Model did not produce valid JSON output.", {
+            cause: error,
+            ...structuredOutputErrorContext(input, response, responseId, cost, text),
+          })
+        }
+        try {
+          return {
+            status: "completed",
+            output: input.output.validate(raw),
+            steps,
+            finishReason: response.finishReason,
+          }
+        } catch (error) {
+          throw new StructuredOutputError("[SixbModels] Structured output validation failed.", {
+            cause: error,
+            ...structuredOutputErrorContext(input, response, responseId, cost, text),
+          })
+        }
+      }
+      const output = responseText(response)
+      return { status: "completed", output, steps, finishReason: response.finishReason }
+    }
+
+    const toolResults = await Promise.all(
+      localCalls.map((call) => executeToolCall(call, tools, callId, input.signal, input.onEvent))
+    )
+    const step = modelStep(response, responseId, [...response.content, ...toolResults], cost)
+    steps.push(step)
+    await input.onStepEnd?.(step)
+
+    if (input.signal.aborted) {
+      return {
+        status: "aborted",
+        steps,
+        partialContent: [],
+      }
+    }
+
+    const assistantContent = response.content.filter(
+      (part) => part.type !== "tool-result" || part.providerExecuted === true
+    )
+    messages = [
+      ...requestMessages,
+      { role: "assistant", content: assistantContent },
+      { role: "tool", content: toolResults },
+    ]
+
+    if (stepIndex + 1 === input.maxSteps) {
+      if (input.output) {
+        throw new StructuredOutputError(
+          "[SixbModels] Model reached the step limit without structured output.",
+          structuredOutputErrorContext(input, response, responseId, cost, responseText(response))
+        )
+      }
+      const output = responseText(response)
+      return { status: "completed", output, steps, finishReason: response.finishReason }
+    }
+  }
+
+  throw new ModelStreamError("[SixbModels] Model loop exited without a terminal result.")
+}
+
+function assertLoopInput(input: RunModelLoopInput<unknown>): void {
+  if (
+    input.maxOutputTokens !== undefined &&
+    (!Number.isSafeInteger(input.maxOutputTokens) || input.maxOutputTokens <= 0)
+  ) {
+    throw new TypeError("[SixbModels] maxOutputTokens must be a positive safe integer.")
+  }
+  if (!Number.isInteger(input.maxSteps) || input.maxSteps <= 0) {
+    throw new TypeError("[SixbModels] maxSteps must be a positive integer.")
+  }
+  if (!input.model.providerId.trim() || !input.model.modelId.trim()) {
+    throw new TypeError("[SixbModels] Model providerId and modelId must not be empty.")
+  }
+  if (
+    input.model.definition.providerId !== input.model.providerId ||
+    input.model.definition.modelId !== input.model.modelId
+  ) {
+    throw new TypeError(
+      `[SixbModels] Model definition for '${input.model.providerId}/${input.model.modelId}' has a different identity.`
+    )
+  }
+  if (input.output) {
+    if (!input.output.name.trim()) {
+      throw new TypeError("[SixbModels] Structured output names must not be empty.")
+    }
+    assertJsonObject(input.output.schema, "structured output schema")
+  }
+}
+
+function indexTools(tools: readonly ModelTool[]): ReadonlyMap<string, ModelTool> {
+  const result = new Map<string, ModelTool>()
+  for (const tool of tools) {
+    if (!tool.name.trim()) throw new TypeError("[SixbModels] Tool names must not be empty.")
+    if (result.has(tool.name)) {
+      throw new TypeError(`[SixbModels] Duplicate tool name '${tool.name}'.`)
+    }
+    assertJsonObject(tool.inputSchema, `tool '${tool.name}' input schema`)
+    result.set(tool.name, tool)
+  }
+  return result
+}
+
+function responseText(response: CompletedResponse): string {
+  return response.content
+    .filter((part): part is ModelTextPart => part.type === "text")
+    .map((part) => part.text)
+    .join("")
+}
+
+function structuredOutputErrorContext(
+  input: RunModelLoopInput<unknown>,
+  response: CompletedResponse,
+  responseId: string,
+  cost: ModelCallCost,
+  text: string
+) {
+  return {
+    text,
+    providerId: input.model.providerId,
+    modelId: input.model.modelId,
+    responseId,
+    ...(response.responseModelId === undefined
+      ? {}
+      : { responseModelId: response.responseModelId }),
+    finishReason: response.finishReason,
+    usage: response.usage,
+    cost,
+  }
+}
+
+function modelStep(
+  response: CompletedResponse,
+  responseId: string,
+  content: readonly ModelAssistantPart[],
+  cost: import("../models/pricing").ModelCallCost
+): ModelStep {
+  return {
+    content,
+    finishReason: response.finishReason,
+    ...(response.rawFinishReason === undefined
+      ? {}
+      : { rawFinishReason: response.rawFinishReason }),
+    usage: response.usage,
+    responseId,
+    ...(response.responseModelId === undefined
+      ? {}
+      : { responseModelId: response.responseModelId }),
+    cost,
+    ...(response.route === undefined ? {} : { route: response.route }),
+  }
+}
+
+async function executeToolCall(
+  call: ParsedToolCall,
+  tools: ReadonlyMap<string, ModelTool>,
+  callId: string,
+  signal: AbortSignal,
+  onEvent: RunModelLoopInput["onEvent"]
+): Promise<ModelToolResultPart> {
+  const { part } = call
+  if (call.inputError) {
+    const errorText = `Tool input is not valid JSON: ${call.inputError.message}`
+    await onEvent?.({
+      type: "tool-input-error",
+      toolCallId: part.toolCallId,
+      toolName: part.toolName,
+      input: part.input,
+      errorText,
+    })
+    return toolErrorResult(part, errorText)
+  }
+
+  const tool = tools.get(part.toolName)
+  if (!tool) {
+    const errorText = `Tool '${part.toolName}' is not available.`
+    await onEvent?.({
+      type: "tool-output-error",
+      toolCallId: part.toolCallId,
+      toolName: part.toolName,
+      errorText,
+    })
+    return toolErrorResult(part, errorText)
+  }
+
+  let parsed: unknown
+  try {
+    parsed = tool.parseInput(part.input)
+  } catch (error) {
+    const errorText = error instanceof Error ? error.message : "Tool input validation failed."
+    await onEvent?.({
+      type: "tool-input-error",
+      toolCallId: part.toolCallId,
+      toolName: part.toolName,
+      input: part.input,
+      errorText,
+    })
+    return toolErrorResult(part, errorText)
+  }
+
+  await onEvent?.({
+    type: "tool-input-available",
+    toolCallId: part.toolCallId,
+    toolName: part.toolName,
+    input: part.input,
+  })
+  let output: JsonValue
+  let modelOutput: ModelToolOutput
+  try {
+    const context = { signal, callId, toolCallId: part.toolCallId }
+    output = await tool.execute(parsed, context)
+    assertJsonValue(output, `tool '${part.toolName}' output`)
+    modelOutput = tool.toModelOutput
+      ? await tool.toModelOutput(output, context)
+      : modelToolOutput(output)
+    validateModelToolOutput(modelOutput, part.toolName)
+  } catch (error) {
+    const errorText = tool.errorText(error)
+    await onEvent?.({
+      type: "tool-output-error",
+      toolCallId: part.toolCallId,
+      toolName: part.toolName,
+      errorText,
+    })
+    return toolErrorResult(part, errorText)
+  }
+  // Publication failures belong to the caller, not the tool's recoverable error channel.
+  await onEvent?.({
+    type: "tool-output-available",
+    toolCallId: part.toolCallId,
+    toolName: part.toolName,
+    output,
+  })
+  return {
+    type: "tool-result",
+    toolCallId: part.toolCallId,
+    toolName: part.toolName,
+    output: modelOutput,
+    ...(modelOutputMatchesOriginal(modelOutput, output) ? {} : { originalOutput: output }),
+  }
+}
+
+function validateModelToolOutput(output: ModelToolOutput, toolName: string): void {
+  if (output.type === "text" || output.type === "error-text") {
+    if (typeof output.value !== "string") {
+      throw new TypeError(`[SixbModels] Tool '${toolName}' model output must contain text.`)
+    }
+    return
+  }
+  if (output.type !== "json" && output.type !== "error-json") {
+    throw new TypeError(
+      `[SixbModels] Tool '${toolName}' returned an unsupported model output type.`
+    )
+  }
+  assertJsonValue(output.value, `tool '${toolName}' model output`)
+}
+
+function modelOutputMatchesOriginal(output: ModelToolOutput, original: JsonValue): boolean {
+  if (output.type === "text") return typeof original === "string" && output.value === original
+  if (output.type === "json") return output.value === original
+  return false
+}
+
+function modelToolOutput(value: JsonValue): ModelToolOutput {
+  return typeof value === "string" ? { type: "text", value } : { type: "json", value }
+}
+
+function toolErrorResult(part: ModelToolCallPart, errorText: string): ModelToolResultPart {
+  if (typeof errorText !== "string") {
+    throw new TypeError(`[SixbModels] Tool '${part.toolName}' error text must be a string.`)
+  }
+  return {
+    type: "tool-result",
+    toolCallId: part.toolCallId,
+    toolName: part.toolName,
+    output: { type: "error-text", value: errorText },
+  }
+}
+
+type MutableTextPart = {
+  type: "text"
+  text: string
+  providerData?: ProviderData
+  complete: boolean
+}
+type MutableReasoningPart = {
+  type: "reasoning"
+  text: string
+  providerData?: ProviderData
+  complete: boolean
+}
+type MutableToolCall = {
+  type: "tool-call"
+  toolCallId: string
+  toolName: string
+  inputText: string
+  providerData?: ProviderData
+  providerExecuted?: boolean
+  dynamic?: boolean
+  complete: boolean
+}
+type MutablePart =
+  | MutableTextPart
+  | MutableReasoningPart
+  | MutableToolCall
+  | ModelToolResultPart
+  | ModelProviderStatePart
+
+class StreamAccumulator {
+  private readonly parts: MutablePart[] = []
+  private readonly spans = new Map<string, MutableTextPart | MutableReasoningPart>()
+  private readonly toolCalls = new Map<string, MutableToolCall>()
+  private started = false
+  private finished = false
+  private finishReason: ModelFinishReason | undefined
+  private rawFinishReason: string | undefined
+  private usage: ModelUsage = {}
+  private responseId: string | undefined
+  private providerIds: import("../models/events").ModelProviderIds | undefined
+  private responseModelId: string | undefined
+  private projectionError: Error | undefined
+  private reportedCost: ModelReportedCost | undefined
+  private route: import("../models/events").ModelRoute | undefined
+
+  constructor(private readonly onEvent: RunModelLoopInput["onEvent"]) {}
+
+  isFinished(): boolean {
+    return this.finished
+  }
+
+  async accept(event: LanguageModelStreamEvent): Promise<void> {
+    if (this.finished) {
+      throw new ModelStreamError(`[SixbModels] Received '${event.type}' after stream finish.`)
+    }
+    switch (event.type) {
+      case "stream-start":
+        if (this.started) throw new ModelStreamError("[SixbModels] Duplicate stream-start event.")
+        this.started = true
+        return
+      case "response-metadata":
+        this.requireStarted(event.type)
+        this.responseId = event.id ?? this.responseId
+        if (event.providerIds) this.providerIds = { ...this.providerIds, ...event.providerIds }
+        this.responseModelId = event.modelId ?? this.responseModelId
+        return
+      case "text-start":
+        await this.startText(event)
+        return
+      case "text-delta":
+        await this.appendText(event, "text")
+        return
+      case "text-end":
+        await this.endText(event, "text")
+        return
+      case "reasoning-start":
+        await this.startReasoning(event)
+        return
+      case "reasoning-delta":
+        await this.appendText(event, "reasoning")
+        return
+      case "reasoning-end":
+        await this.endText(event, "reasoning")
+        return
+      case "tool-input-start":
+        await this.startTool(event)
+        return
+      case "tool-input-delta":
+        await this.appendTool(event)
+        return
+      case "tool-input-end":
+        this.endTool(event)
+        return
+      case "tool-call":
+        await this.completeTool(event)
+        return
+      case "tool-result":
+        this.addProviderToolResult(event)
+        return
+      case "provider-state":
+        if (typeof event.providerId !== "string" || event.providerId.length === 0) {
+          this.captureProjectionError(
+            new ModelStreamError("[SixbModels] Provider state requires a nonempty provider ID.")
+          )
+          return
+        }
+        if (this.captureProviderState(event.data)) {
+          this.parts.push({
+            type: "provider-state",
+            providerId: event.providerId,
+            data: event.data,
+          })
+        }
+        return
+      case "finish":
+        this.requireStarted(event.type)
+        validateUsage(event.usage)
+        this.captureProviderData(event.providerData)
+        this.finished = true
+        this.finishReason = event.finishReason
+        this.rawFinishReason = event.rawFinishReason
+        this.usage = event.usage
+        this.reportedCost = event.reportedCost
+        this.route = event.route
+        return
+      case "error":
+        throw event.error instanceof Error
+          ? event.error
+          : new ModelProviderError("[SixbModels] Provider stream failed.", "unknown", "unknown", {
+              cause: event.error,
+            })
+    }
+  }
+
+  complete(): CompletedResponse {
+    if (!this.started) throw new ModelStreamError("[SixbModels] Stream did not start.")
+    if (!this.finished || !this.finishReason) {
+      throw new ModelStreamError("[SixbModels] Stream ended without a finish event.")
+    }
+    for (const part of this.parts) {
+      if ("complete" in part && !part.complete) {
+        throw new ModelStreamError(
+          `[SixbModels] Stream finished with incomplete ${part.type} content.`
+        )
+      }
+    }
+    const parsed = this.parseParts(false)
+    return {
+      content: parsed.content,
+      toolCalls: parsed.toolCalls,
+      finishReason: this.finishReason,
+      ...(this.rawFinishReason === undefined ? {} : { rawFinishReason: this.rawFinishReason }),
+      ...this.accounting(),
+      ...(this.projectionError === undefined ? {} : { projectionError: this.projectionError }),
+    }
+  }
+
+  accounting() {
+    return {
+      usage: this.usage,
+      ...(this.responseId === undefined ? {} : { responseId: this.responseId }),
+      ...(this.providerIds === undefined ? {} : { providerIds: this.providerIds }),
+      ...(this.responseModelId === undefined ? {} : { responseModelId: this.responseModelId }),
+      ...(this.reportedCost === undefined ? {} : { reportedCost: this.reportedCost }),
+      ...(this.route === undefined ? {} : { route: this.route }),
+    }
+  }
+
+  partialContent(): readonly ModelAssistantPart[] {
+    return this.parseParts(true).content
+  }
+
+  private parseParts(partial: boolean): {
+    readonly content: ModelAssistantPart[]
+    readonly toolCalls: ParsedToolCall[]
+  } {
+    const content: ModelAssistantPart[] = []
+    const toolCalls: ParsedToolCall[] = []
+    for (const part of this.parts) {
+      if (part.type === "text") {
+        if ((!partial || part.text.length > 0) && (part.complete || partial)) {
+          content.push({
+            type: "text",
+            text: part.text,
+            ...(part.providerData === undefined ? {} : { providerData: part.providerData }),
+          })
+        }
+      } else if (part.type === "reasoning") {
+        if (part.complete) {
+          content.push({
+            type: "reasoning",
+            text: part.text,
+            ...(part.providerData === undefined ? {} : { providerData: part.providerData }),
+          })
+        }
+      } else if (part.type === "tool-call") {
+        if (!part.complete) continue
+        let value: JsonValue = null
+        let inputError: Error | undefined
+        try {
+          const parsed: unknown = JSON.parse(part.inputText)
+          if (!isJsonValue(parsed)) throw new TypeError("input is not a JSON value")
+          value = parsed
+        } catch (error) {
+          inputError = error instanceof Error ? error : new Error(String(error))
+        }
+        const call: ModelToolCallPart = {
+          type: "tool-call",
+          toolCallId: part.toolCallId,
+          toolName: part.toolName,
+          input: value,
+          ...(part.providerData === undefined ? {} : { providerData: part.providerData }),
+          ...(part.providerExecuted === undefined
+            ? {}
+            : { providerExecuted: part.providerExecuted }),
+          ...(part.dynamic === undefined ? {} : { dynamic: part.dynamic }),
+        }
+        content.push(call)
+        toolCalls.push({ part: call, ...(inputError === undefined ? {} : { inputError }) })
+      } else {
+        content.push(part)
+      }
+    }
+    return { content, toolCalls }
+  }
+
+  private async startText(
+    event: Extract<LanguageModelStreamEvent, { type: "text-start" }>
+  ): Promise<void> {
+    this.requireStarted(event.type)
+    this.assertNewSpan(event.id)
+    const providerData = this.captureProviderData(event.providerData)
+    const part: MutableTextPart = {
+      type: "text",
+      text: "",
+      complete: false,
+      ...(providerData === undefined ? {} : { providerData }),
+    }
+    this.spans.set(event.id, part)
+    this.parts.push(part)
+    await this.onEvent?.({ type: "text-start", id: event.id })
+  }
+
+  private async startReasoning(
+    event: Extract<LanguageModelStreamEvent, { type: "reasoning-start" }>
+  ): Promise<void> {
+    this.requireStarted(event.type)
+    this.assertNewSpan(event.id)
+    const providerData = this.captureProviderData(event.providerData)
+    const part: MutableReasoningPart = {
+      type: "reasoning",
+      text: "",
+      complete: false,
+      ...(providerData === undefined ? {} : { providerData }),
+    }
+    this.spans.set(event.id, part)
+    this.parts.push(part)
+    await this.onEvent?.({ type: "reasoning-start", id: event.id })
+  }
+
+  private async appendText(
+    event: Extract<LanguageModelStreamEvent, { type: "text-delta" | "reasoning-delta" }>,
+    expected: "text" | "reasoning"
+  ): Promise<void> {
+    const part = this.spans.get(event.id)
+    if (!part || part.type !== expected || part.complete) {
+      throw new ModelStreamError(
+        `[SixbModels] ${event.type} references unopened ${expected} span '${event.id}'.`
+      )
+    }
+    part.text += event.delta
+    await this.onEvent?.({ type: event.type, id: event.id, delta: event.delta })
+  }
+
+  private async endText(
+    event: Extract<LanguageModelStreamEvent, { type: "text-end" | "reasoning-end" }>,
+    expected: "text" | "reasoning"
+  ): Promise<void> {
+    const part = this.spans.get(event.id)
+    if (!part || part.type !== expected || part.complete) {
+      throw new ModelStreamError(
+        `[SixbModels] ${event.type} references unopened ${expected} span '${event.id}'.`
+      )
+    }
+    part.providerData = mergeProviderData(
+      part.providerData,
+      this.captureProviderData(event.providerData)
+    )
+    part.complete = true
+    this.spans.delete(event.id)
+    await this.onEvent?.({ type: event.type, id: event.id })
+  }
+
+  private async startTool(
+    event: Extract<LanguageModelStreamEvent, { type: "tool-input-start" }>
+  ): Promise<void> {
+    this.requireStarted(event.type)
+    if (
+      typeof event.id !== "string" ||
+      !event.id ||
+      typeof event.toolName !== "string" ||
+      !event.toolName
+    ) {
+      throw new ModelStreamError("[SixbModels] Tool calls require nonempty IDs and names.")
+    }
+    if (this.toolCalls.has(event.id)) {
+      throw new ModelStreamError(`[SixbModels] Duplicate tool call ID '${event.id}'.`)
+    }
+    const providerData = this.captureProviderData(event.providerData)
+    const part: MutableToolCall = {
+      type: "tool-call",
+      toolCallId: event.id,
+      toolName: event.toolName,
+      inputText: "",
+      complete: false,
+      ...(providerData === undefined ? {} : { providerData }),
+      ...(event.providerExecuted === undefined ? {} : { providerExecuted: event.providerExecuted }),
+      ...(event.dynamic === undefined ? {} : { dynamic: event.dynamic }),
+    }
+    this.toolCalls.set(event.id, part)
+    this.parts.push(part)
+    await this.onEvent?.({
+      type: "tool-input-start",
+      toolCallId: event.id,
+      toolName: event.toolName,
+    })
+  }
+
+  private async appendTool(
+    event: Extract<LanguageModelStreamEvent, { type: "tool-input-delta" }>
+  ): Promise<void> {
+    const part = this.toolCalls.get(event.id)
+    if (!part || part.complete) {
+      throw new ModelStreamError(
+        `[SixbModels] tool-input-delta references unopened tool call '${event.id}'.`
+      )
+    }
+    part.inputText += event.delta
+    await this.onEvent?.({
+      type: "tool-input-delta",
+      toolCallId: event.id,
+      toolName: part.toolName,
+      inputTextDelta: event.delta,
+    })
+  }
+
+  private endTool(event: Extract<LanguageModelStreamEvent, { type: "tool-input-end" }>): void {
+    const part = this.toolCalls.get(event.id)
+    if (!part || part.complete) {
+      throw new ModelStreamError(
+        `[SixbModels] tool-input-end references unopened tool call '${event.id}'.`
+      )
+    }
+    part.providerData = mergeProviderData(
+      part.providerData,
+      this.captureProviderData(event.providerData)
+    )
+    part.complete = true
+  }
+
+  private async completeTool(
+    event: Extract<LanguageModelStreamEvent, { type: "tool-call" }>
+  ): Promise<void> {
+    await this.startTool({
+      type: "tool-input-start",
+      id: event.toolCallId,
+      toolName: event.toolName,
+      ...(event.providerData === undefined ? {} : { providerData: event.providerData }),
+      ...(event.providerExecuted === undefined ? {} : { providerExecuted: event.providerExecuted }),
+      ...(event.dynamic === undefined ? {} : { dynamic: event.dynamic }),
+    })
+    const part = this.toolCalls.get(event.toolCallId)
+    if (!part) throw new ModelStreamError("[SixbModels] Failed to index completed tool call.")
+    part.inputText = event.input
+    part.complete = true
+  }
+
+  private addProviderToolResult(
+    event: Extract<LanguageModelStreamEvent, { type: "tool-result" }>
+  ): void {
+    if (!this.captureJsonValue(event.output, "provider tool result")) return
+    const providerData = this.captureProviderData(event.providerData)
+    this.parts.push({
+      type: "tool-result",
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      output: event.isError
+        ? { type: "error-json", value: event.output }
+        : modelToolOutput(event.output),
+      providerExecuted: event.providerExecuted ?? true,
+      ...(event.dynamic === undefined ? {} : { dynamic: event.dynamic }),
+      ...(providerData === undefined ? {} : { providerData }),
+    })
+  }
+
+  private captureProviderData(data: ProviderData | undefined): ProviderData | undefined {
+    if (data === undefined) return undefined
+    try {
+      return normalizeProviderData(data)
+    } catch (error) {
+      this.captureProjectionError(error)
+      return undefined
+    }
+  }
+
+  private captureProviderState(value: unknown): value is JsonValue {
+    if (!this.captureJsonValue(value, "provider state")) return false
+    if (JSON.stringify(value).length > MAX_PROVIDER_DATA_BYTES) {
+      this.captureProjectionError(
+        new ModelStreamError(
+          `[SixbModels] Provider state exceeds the ${MAX_PROVIDER_DATA_BYTES}-byte response limit.`
+        )
+      )
+      return false
+    }
+    return true
+  }
+
+  private captureJsonValue(value: unknown, label: string): value is JsonValue {
+    try {
+      assertJsonValue(value, label)
+      return true
+    } catch (error) {
+      this.captureProjectionError(error)
+      return false
+    }
+  }
+
+  private captureProjectionError(error: unknown): void {
+    this.projectionError ??= error instanceof Error ? error : new Error(String(error))
+  }
+
+  private requireStarted(type: string): void {
+    if (!this.started) {
+      throw new ModelStreamError(`[SixbModels] Received '${type}' before stream-start.`)
+    }
+  }
+
+  private assertNewSpan(id: string): void {
+    if (!id) throw new ModelStreamError("[SixbModels] Content span IDs must not be empty.")
+    if (this.spans.has(id)) {
+      throw new ModelStreamError(`[SixbModels] Duplicate open content span '${id}'.`)
+    }
+  }
+}
+
+function validateUsage(usage: ModelUsage): void {
+  for (const [key, value] of Object.entries(usage)) {
+    if (key === "raw") {
+      if (value !== undefined) assertJsonValue(value, "raw model usage")
+      continue
+    }
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+      throw new ModelStreamError(`[SixbModels] Usage field '${key}' must be a nonnegative integer.`)
+    }
+  }
+}
+
+function normalizeProviderData(value: ProviderData): ProviderData {
+  const data = omitUndefinedObjectProperties(value)
+  assertJsonValue(data, "provider data")
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new TypeError("[SixbModels] provider data must be a JSON object.")
+  }
+  if (JSON.stringify(data).length > MAX_PROVIDER_DATA_BYTES) {
+    throw new ModelStreamError(
+      `[SixbModels] Provider data exceeds the ${MAX_PROVIDER_DATA_BYTES}-byte response limit.`
+    )
+  }
+  return data
+}
+
+/** Normalize absent metadata fields at ingestion, leaving non-JSON values for validation. */
+function omitUndefinedObjectProperties(value: unknown, seen = new Set<object>()): unknown {
+  if (typeof value !== "object" || value === null || seen.has(value)) return value
+  seen.add(value)
+  try {
+    if (Array.isArray(value)) {
+      return value.map((entry) => omitUndefinedObjectProperties(entry, seen))
+    }
+    if (!isPlainRecord(value)) return value
+    return Object.fromEntries(
+      Reflect.ownKeys(value)
+        .filter((key) => Object.prototype.propertyIsEnumerable.call(value, key))
+        .map((key) => [key, Reflect.get(value, key)] as const)
+        .filter(([, entry]) => entry !== undefined)
+        .map(([key, entry]) => [key, omitUndefinedObjectProperties(entry, seen)])
+    )
+  } finally {
+    seen.delete(value)
+  }
+}
+
+function mergeProviderData(
+  first: ProviderData | undefined,
+  second: ProviderData | undefined
+): ProviderData | undefined {
+  if (first === undefined) return second
+  if (second === undefined) return first
+  return { ...first, ...second }
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    (error instanceof DOMException && error.name === "AbortError") ||
+    (error instanceof Error && error.name === "AbortError")
+  )
+}