@sixb/core 0.1.5 → 0.1.7

package/src/models/definitions.ts

@@ -0,0 +1,202 @@
+import {
+  MODEL_REASONING_EFFORTS,
+  type ModelCapabilities,
+  type ModelReasoningBudgetCapabilities,
+  type ModelReasoningCapabilities,
+} from "./language-model"
+
+export type ModelKind = "language" | "image" | "video" | "embedding"
+
+/** Common catalog identity shared by every present and future model runtime. */
+export interface ModelDefinition {
+  readonly kind: ModelKind
+  readonly providerId: string
+  readonly modelId: string
+  readonly name?: string
+  readonly description?: string
+  readonly family?: string
+  readonly tags?: readonly string[]
+  readonly releaseDate?: string
+}
+
+/** Serializable facts about one concrete model offering from one provider. */
+export interface LanguageModelDefinition extends ModelDefinition {
+  readonly kind: "language"
+  readonly knowledgeCutoff?: string
+  readonly contextWindow?: number
+  /** Maximum input tokens, distinct from a shared input/output context window. */
+  readonly maxInputTokens?: number
+  readonly maxOutputTokens?: number
+  readonly capabilities: ModelCapabilities
+}
+
+export function defineLanguageModel(definition: LanguageModelDefinition): LanguageModelDefinition {
+  if (definition.kind !== "language") {
+    throw new TypeError("[Sixb] Language model definitions must use kind 'language'.")
+  }
+  assertModelId(definition.providerId, "providerId")
+  assertModelId(definition.modelId, "modelId")
+  assertOptionalString(definition.name, "name")
+  assertOptionalString(definition.description, "description")
+  assertOptionalString(definition.family, "family")
+  assertOptionalString(definition.releaseDate, "releaseDate")
+  assertOptionalString(definition.knowledgeCutoff, "knowledgeCutoff")
+  const tags = freezeStrings(definition.tags, "tags")
+  const capabilities = defineModelCapabilities(definition.capabilities)
+  assertOptionalPositiveInteger(definition.contextWindow, "contextWindow")
+  assertOptionalPositiveInteger(definition.maxInputTokens, "maxInputTokens")
+  assertOptionalPositiveInteger(definition.maxOutputTokens, "maxOutputTokens")
+  return Object.freeze({
+    kind: "language",
+    providerId: definition.providerId,
+    modelId: definition.modelId,
+    ...(definition.name === undefined ? {} : { name: definition.name }),
+    ...(definition.description === undefined ? {} : { description: definition.description }),
+    ...(definition.family === undefined ? {} : { family: definition.family }),
+    ...(tags === undefined ? {} : { tags }),
+    ...(definition.releaseDate === undefined ? {} : { releaseDate: definition.releaseDate }),
+    ...(definition.knowledgeCutoff === undefined
+      ? {}
+      : { knowledgeCutoff: definition.knowledgeCutoff }),
+    ...(definition.contextWindow === undefined ? {} : { contextWindow: definition.contextWindow }),
+    ...(definition.maxInputTokens === undefined
+      ? {}
+      : { maxInputTokens: definition.maxInputTokens }),
+    ...(definition.maxOutputTokens === undefined
+      ? {}
+      : { maxOutputTokens: definition.maxOutputTokens }),
+    capabilities,
+  })
+}
+
+function defineModelCapabilities(capabilities: unknown): ModelCapabilities {
+  assertRecord(capabilities, "capabilities")
+  const inputMediaTypes =
+    capabilities.inputMediaTypes === "any"
+      ? "any"
+      : freezeStrings(capabilities.inputMediaTypes, "capabilities.inputMediaTypes")
+  for (const [field, value] of Object.entries(capabilities)) {
+    if (field === "inputMediaTypes" || field === "reasoning") continue
+    if (value !== undefined && typeof value !== "boolean") {
+      throw new TypeError(`[Sixb] Model capability '${field}' must be boolean.`)
+    }
+  }
+  const reasoning = freezeReasoningCapabilities(capabilities.reasoning)
+  const flags: {
+    localTools?: boolean
+    parallelToolCalls?: boolean
+    nativeStructuredOutput?: boolean
+    providerExecutedTools?: boolean
+  } = {}
+  for (const key of [
+    "localTools",
+    "parallelToolCalls",
+    "nativeStructuredOutput",
+    "providerExecutedTools",
+  ] as const) {
+    const value = capabilities[key]
+    if (typeof value === "boolean") flags[key] = value
+  }
+  return Object.freeze({
+    ...(inputMediaTypes === undefined ? {} : { inputMediaTypes }),
+    ...(reasoning === undefined ? {} : { reasoning }),
+    ...flags,
+  })
+}
+
+function freezeReasoningCapabilities(reasoning: unknown): ModelCapabilities["reasoning"] {
+  if (reasoning === undefined || reasoning === false) return reasoning
+  assertRecord(reasoning, "reasoning")
+  if (reasoning.canDisable !== undefined && typeof reasoning.canDisable !== "boolean") {
+    throw new TypeError("[Sixb] Model reasoning capability 'canDisable' must be boolean.")
+  }
+  const efforts = freezeReasoningEfforts(reasoning.efforts)
+  const budgetTokens = freezeReasoningBudgetCapabilities(reasoning.budgetTokens)
+  return Object.freeze({
+    ...(reasoning.canDisable === undefined ? {} : { canDisable: reasoning.canDisable }),
+    ...(efforts === undefined ? {} : { efforts }),
+    ...(budgetTokens === undefined ? {} : { budgetTokens }),
+  } satisfies ModelReasoningCapabilities)
+}
+
+function freezeReasoningEfforts(
+  efforts: unknown
+): readonly (typeof MODEL_REASONING_EFFORTS)[number][] | undefined {
+  if (efforts === undefined) return undefined
+  if (!Array.isArray(efforts)) {
+    throw new TypeError("[Sixb] Model reasoning capability 'efforts' must be an array.")
+  }
+  const seen = new Set<string>()
+  return Object.freeze(
+    efforts.map((value: unknown) => {
+      const effort = MODEL_REASONING_EFFORTS.find((allowed) => allowed === value)
+      if (effort === undefined) {
+        throw new TypeError(`[Sixb] Model reasoning effort '${String(value)}' is invalid.`)
+      }
+      if (seen.has(effort)) {
+        throw new TypeError(`[Sixb] Model reasoning effort '${effort}' is duplicated.`)
+      }
+      seen.add(effort)
+      return effort
+    })
+  )
+}
+
+function freezeReasoningBudgetCapabilities(
+  budget: unknown
+): ModelReasoningBudgetCapabilities | undefined {
+  if (budget === undefined) return undefined
+  assertRecord(budget, "reasoning budgetTokens")
+  assertOptionalNonnegativeInteger(budget.min, "capabilities.reasoning.budgetTokens.min")
+  assertOptionalNonnegativeInteger(budget.max, "capabilities.reasoning.budgetTokens.max")
+  if (budget.min !== undefined && budget.max !== undefined && budget.max < budget.min) {
+    throw new TypeError(
+      "[Sixb] Model reasoning token budget maximum must not be below its minimum."
+    )
+  }
+  return Object.freeze({
+    ...(budget.min === undefined ? {} : { min: budget.min }),
+    ...(budget.max === undefined ? {} : { max: budget.max }),
+  })
+}
+
+function assertModelId(value: string, field: string): void {
+  if (!value.trim()) throw new TypeError(`[Sixb] Model ${field} must not be empty.`)
+}
+
+function assertOptionalPositiveInteger(value: number | undefined, field: string): void {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
+    throw new TypeError(`[Sixb] Model ${field} must be a positive safe integer.`)
+  }
+}
+
+function assertOptionalNonnegativeInteger(
+  value: unknown,
+  field: string
+): asserts value is number | undefined {
+  if (
+    value !== undefined &&
+    (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+  ) {
+    throw new TypeError(`[Sixb] Model ${field} must be a nonnegative safe integer.`)
+  }
+}
+
+function assertOptionalString(value: string | undefined, field: string): void {
+  if (value !== undefined && typeof value !== "string") {
+    throw new TypeError(`[Sixb] Model ${field} must be a string.`)
+  }
+}
+
+function freezeStrings(value: unknown, field: string): readonly string[] | undefined {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || !entry.trim())) {
+    throw new TypeError(`[Sixb] Model ${field} must contain nonempty strings.`)
+  }
+  return Object.freeze([...value])
+}
+
+function assertRecord(value: unknown, field: string): asserts value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError(`[Sixb] Model ${field} must be an object.`)
+}

package/src/models/errors.ts

@@ -0,0 +1,83 @@
+import type { ModelFinishReason, ModelUsage } from "./events"
+import type { ModelCallCost } from "./pricing"
+
+/** Catalog transport/access failed; callers may use local metadata without masking invalid definitions. */
+export class ModelCatalogUnavailableError extends Error {
+  readonly name = "ModelCatalogUnavailableError"
+}
+
+/** A provider or provider protocol rejected a model request. */
+export class ModelProviderError extends Error {
+  readonly name = "ModelProviderError"
+
+  constructor(
+    message: string,
+    readonly providerId: string,
+    readonly modelId: string,
+    options?: ErrorOptions & {
+      readonly status?: number
+      readonly code?: string
+      readonly requestId?: string
+      readonly retryAfterMs?: number
+      readonly retryable?: boolean
+    }
+  ) {
+    super(message, options)
+    this.status = options?.status
+    this.code = options?.code
+    this.requestId = options?.requestId
+    this.retryAfterMs = options?.retryAfterMs
+    this.retryable = options?.retryable ?? false
+  }
+
+  readonly status?: number
+  readonly code?: string
+  readonly requestId?: string
+  readonly retryAfterMs?: number
+  readonly retryable: boolean
+}
+
+export class ModelStreamError extends Error {
+  readonly name = "ModelStreamError"
+}
+
+export class UnsupportedModelFeatureError extends Error {
+  readonly name = "UnsupportedModelFeatureError"
+}
+
+export class StructuredOutputError extends Error {
+  readonly name = "StructuredOutputError"
+
+  constructor(
+    message: string,
+    options?: ErrorOptions & {
+      readonly text?: string
+      readonly providerId?: string
+      readonly modelId?: string
+      readonly responseId?: string
+      readonly responseModelId?: string
+      readonly finishReason?: ModelFinishReason
+      readonly usage?: ModelUsage
+      readonly cost?: ModelCallCost
+    }
+  ) {
+    super(message, options)
+    this.text = options?.text
+    this.providerId = options?.providerId
+    this.modelId = options?.modelId
+    this.responseId = options?.responseId
+    this.responseModelId = options?.responseModelId
+    this.finishReason = options?.finishReason
+    this.usage = options?.usage
+    this.cost = options?.cost
+  }
+
+  readonly text?: string
+  readonly providerId?: string
+  readonly modelId?: string
+  readonly responseId?: string
+  readonly responseModelId?: string
+  readonly finishReason?: ModelFinishReason
+  readonly usage?: ModelUsage
+  readonly cost?: ModelCallCost
+}

package/src/models/events.ts

@@ -0,0 +1,198 @@
+import type { JsonObject, JsonValue } from "../json"
+import type { ModelReasoning } from "./language-model"
+import type {
+  ModelAssistantPart,
+  ModelToolCallPart,
+  ModelToolResultPart,
+  ProviderData,
+} from "./messages"
+import type { ModelCallCost, ModelCostEstimate, ModelReportedCost } from "./pricing"
+
+export interface ModelRoute {
+  /** Provider selected by a routing gateway, when it differs from the provider being called. */
+  readonly providerId?: string
+  readonly modelId?: string
+}
+
+/** Only identifiers supplied by the provider. Internal call/response fallback IDs never belong here. */
+export type ModelProviderIds = {
+  readonly requestId?: string
+  readonly responseId?: string
+  readonly generationId?: string
+}
+
+export function normalizeModelProviderIds(value: unknown): ModelProviderIds {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new TypeError("[Sixb] Provider identifiers must be an object.")
+  const result: { requestId?: string; responseId?: string; generationId?: string } = {}
+  for (const [key, id] of Object.entries(value)) {
+    if (key !== "requestId" && key !== "responseId" && key !== "generationId") continue
+    if (id === undefined) continue
+    if (typeof id !== "string" || !id.trim())
+      throw new TypeError(`[Sixb] Provider ${key} must be nonblank.`)
+    result[key] = id
+  }
+  return Object.freeze(result)
+}
+
+export type ModelFinishReason =
+  | "stop"
+  | "length"
+  | "content-filter"
+  | "tool-calls"
+  | "pause"
+  | "error"
+  | "other"
+  | "unknown"
+
+export interface ModelUsage {
+  readonly inputTokens?: number
+  readonly outputTokens?: number
+  readonly uncachedInputTokens?: number
+  readonly cacheReadInputTokens?: number
+  readonly cacheWriteInputTokens?: number
+  readonly cacheWrite5mInputTokens?: number
+  readonly cacheWrite1hInputTokens?: number
+  readonly textOutputTokens?: number
+  readonly reasoningOutputTokens?: number
+  readonly raw?: JsonObject
+}
+
+export type LanguageModelStreamEvent =
+  | { readonly type: "stream-start" }
+  | {
+      readonly type: "response-metadata"
+      readonly providerIds?: ModelProviderIds
+      readonly id?: string
+      readonly modelId?: string
+    }
+  | { readonly type: "text-start"; readonly id: string; readonly providerData?: ProviderData }
+  | { readonly type: "text-delta"; readonly id: string; readonly delta: string }
+  | { readonly type: "text-end"; readonly id: string; readonly providerData?: ProviderData }
+  | {
+      readonly type: "reasoning-start"
+      readonly id: string
+      readonly providerData?: ProviderData
+    }
+  | { readonly type: "reasoning-delta"; readonly id: string; readonly delta: string }
+  | { readonly type: "reasoning-end"; readonly id: string; readonly providerData?: ProviderData }
+  | {
+      readonly type: "tool-input-start"
+      readonly id: string
+      readonly toolName: string
+      readonly providerData?: ProviderData
+      readonly providerExecuted?: boolean
+      readonly dynamic?: boolean
+    }
+  | { readonly type: "tool-input-delta"; readonly id: string; readonly delta: string }
+  | { readonly type: "tool-input-end"; readonly id: string; readonly providerData?: ProviderData }
+  | {
+      readonly type: "tool-call"
+      readonly toolCallId: string
+      readonly toolName: string
+      readonly input: string
+      readonly providerData?: ProviderData
+      readonly providerExecuted?: boolean
+      readonly dynamic?: boolean
+    }
+  | {
+      readonly type: "tool-result"
+      readonly toolCallId: string
+      readonly toolName: string
+      readonly output: JsonValue
+      readonly isError?: boolean
+      readonly providerData?: ProviderData
+      readonly providerExecuted?: boolean
+      readonly dynamic?: boolean
+    }
+  | {
+      readonly type: "provider-state"
+      readonly providerId: string
+      readonly data: JsonValue
+    }
+  | {
+      readonly type: "finish"
+      readonly finishReason: ModelFinishReason
+      readonly rawFinishReason?: string
+      readonly usage: ModelUsage
+      readonly providerData?: ProviderData
+      readonly reportedCost?: ModelReportedCost
+      readonly route?: ModelRoute
+    }
+  | { readonly type: "error"; readonly error: unknown }
+
+export type ModelUiChunk =
+  | { readonly type: "start-step" }
+  | { readonly type: "text-start"; readonly id: string }
+  | { readonly type: "text-delta"; readonly id: string; readonly delta: string }
+  | { readonly type: "text-end"; readonly id: string }
+  | { readonly type: "reasoning-start"; readonly id: string }
+  | { readonly type: "reasoning-delta"; readonly id: string; readonly delta: string }
+  | { readonly type: "reasoning-end"; readonly id: string }
+  | {
+      readonly type: "tool-input-start"
+      readonly toolCallId: string
+      readonly toolName: string
+    }
+  | {
+      readonly type: "tool-input-delta"
+      readonly toolCallId: string
+      readonly toolName: string
+      readonly inputTextDelta: string
+    }
+  | {
+      readonly type: "tool-input-available"
+      readonly toolCallId: string
+      readonly toolName: string
+      readonly input: JsonValue
+    }
+  | {
+      readonly type: "tool-input-error"
+      readonly toolCallId: string
+      readonly toolName: string
+      readonly input: JsonValue
+      readonly errorText: string
+    }
+  | {
+      readonly type: "tool-output-available"
+      readonly toolCallId: string
+      readonly toolName: string
+      readonly output: JsonValue
+    }
+  | {
+      readonly type: "tool-output-error"
+      readonly toolCallId: string
+      readonly toolName: string
+      readonly errorText: string
+    }
+  | { readonly type: "error"; readonly errorText: string }
+
+export interface ModelCallEndEvent {
+  readonly providerIds?: ModelProviderIds
+  /** Retained independently when the selected display cost is provider-reported. */
+  readonly estimate?: ModelCostEstimate
+  readonly callId: string
+  readonly providerId: string
+  readonly modelId: string
+  readonly responseId: string
+  readonly responseModelId?: string
+  readonly usage: ModelUsage
+  readonly cost: ModelCallCost
+  readonly requestedReasoning?: ModelReasoning
+  readonly route?: ModelRoute
+}
+
+export interface ModelStep {
+  readonly content: readonly (ModelAssistantPart | ModelToolResultPart)[]
+  readonly finishReason: ModelFinishReason
+  readonly rawFinishReason?: string
+  readonly usage: ModelUsage
+  readonly responseId: string
+  readonly responseModelId?: string
+  readonly cost: ModelCallCost
+  readonly route?: ModelRoute
+}
+
+export interface ModelLoopPartial {
+  readonly content: readonly (ModelAssistantPart | ModelToolCallPart | ModelToolResultPart)[]
+}

package/src/models/index.ts

@@ -1,71 +1,89 @@
-import type { LanguageModelV4 } from "@ai-sdk/provider"
-import { createDefinitionCatalog, type DefinitionCatalog } from "../runtime/definitions"
-import { RuntimeError } from "../runtime/errors"
-
-/** The configured language models, with the project default. */
-export interface LanguageModelCatalog extends DefinitionCatalog<LanguageModelEntry> {
-  readonly default: LanguageModelEntry
-}
-
-/**
- * One configured language model.
- *
- * `ref` is derived, never author-supplied, and stays internal to the runtime: it identifies the
- * configured binding, not a vendor model. The AI SDK's `provider` names the binding, so
- * `openai.chat(...)` and `openai.responses(...)` are distinct entries even for one vendor model,
- * and neither matches the canonical id the worker resolves for billing
- * (`SDK_PROVIDER_BINDINGS` in `@sixb/agent-worker`). Anything user-facing should key on
- * `provider` + `modelId` instead.
- */
-export interface LanguageModelEntry {
-  readonly ref: string
-  readonly provider: string
-  readonly modelId: string
-  readonly model: LanguageModelV4
-}
-
-/** Models a project allows Sixb to use, organized by technical model kind. */
-export interface ModelCatalog {
-  readonly language: LanguageModelCatalog
-}
-
-export interface ModelCatalogInput {
-  /** Ordered; the first entry is the project default. */
-  readonly language: readonly LanguageModelV4[]
-}
-
-/**
- * Identify a catalog entry by the binding its model was constructed from.
- *
- * `gateway("openai/gpt-5.4")` and `openai("gpt-5.4")` are different entries on purpose: they route
- * differently and bill differently. See {@link LanguageModelEntry}.
- */
-export function modelRef(model: LanguageModelV4): string {
-  return `${model.provider}/${model.modelId}`
-}
-
-/** Build the immutable project model catalog. Rejects duplicates and an empty catalog. */
-export function createModelCatalog(input: ModelCatalogInput): ModelCatalog {
-  const byRef = new Map<string, LanguageModelEntry>()
-
-  for (const model of input.language) {
-    const ref = modelRef(model)
-    if (byRef.has(ref)) {
-      throw new RuntimeError(
-        `[Sixb] Duplicate language model '${ref}' in 'models'. Each provider and model id pair may be configured once.`
-      )
-    }
-    byRef.set(ref, Object.freeze({ ref, provider: model.provider, modelId: model.modelId, model }))
-  }
-
-  const [defaultEntry] = byRef.values()
-  if (defaultEntry === undefined) {
-    throw new RuntimeError(
-      "[Sixb] 'models.language' needs at least one model. Configure one or omit 'models' from createSixb()."
-    )
-  }
-
-  return Object.freeze({
-    language: Object.freeze({ ...createDefinitionCatalog(byRef), default: defaultEntry }),
-  })
-}
+export type { JsonObject, JsonPrimitive, JsonValue } from "../json"
+export { assertJsonObject, assertJsonValue, isJsonObject, isJsonValue } from "../json"
+export type {
+  LanguageModelCatalog,
+  LanguageModelDefinitionCatalog,
+  LanguageModelEntry,
+  LanguageModelRef,
+  ModelCatalog,
+  ModelCatalogInput,
+  ModelDefinitionCatalog,
+} from "./catalog"
+export { createModelCatalog } from "./catalog"
+export type {
+  LanguageModelDefinition,
+  ModelDefinition,
+  ModelKind,
+} from "./definitions"
+export { defineLanguageModel } from "./definitions"
+export {
+  ModelCatalogUnavailableError,
+  ModelProviderError,
+  ModelStreamError,
+  StructuredOutputError,
+  UnsupportedModelFeatureError,
+} from "./errors"
+export type {
+  LanguageModelStreamEvent,
+  ModelCallEndEvent,
+  ModelFinishReason,
+  ModelLoopPartial,
+  ModelProviderIds,
+  ModelRoute,
+  ModelStep,
+  ModelUiChunk,
+  ModelUsage,
+} from "./events"
+export { normalizeModelProviderIds } from "./events"
+export type {
+  LanguageModel,
+  LanguageModelProvider,
+  LanguageModelRequest,
+  LanguageModelStream,
+  ModelCapabilities,
+  ModelProvider,
+  ModelReasoning,
+  ModelReasoningBudget,
+  ModelReasoningBudgetCapabilities,
+  ModelReasoningCapabilities,
+  ModelReasoningEffort,
+  ModelReasoningLevel,
+  ModelResponseFormat,
+  ModelToolSpecification,
+} from "./language-model"
+export {
+  isModelReasoning,
+  MODEL_REASONING_EFFORTS,
+  MODEL_REASONING_LEVELS,
+  modelReasoningSupportIssue,
+} from "./language-model"
+export type {
+  ModelAssistantPart,
+  ModelFilePart,
+  ModelMessage,
+  ModelProviderStatePart,
+  ModelReasoningPart,
+  ModelTextPart,
+  ModelToolCallPart,
+  ModelToolOutput,
+  ModelToolResultPart,
+  ProviderData,
+} from "./messages"
+export type {
+  ModelCallCost,
+  ModelCostComponent,
+  ModelCostEstimate,
+  ModelCostEstimator,
+  ModelCostMeter,
+  ModelMoney,
+  ModelReportedCost,
+} from "./pricing"
+export { estimateModelReservation, rateModelCall } from "./pricing"
+export type {
+  LanguageModelRateCard,
+  ModelPricingTier,
+  ModelTokenPrice,
+  ModelUnitPrice,
+} from "./rate-card"
+export { defineModelRateCard } from "./rate-card"
+export type { ModelOutput, ModelTool, ModelToolExecutionContext } from "./tools"