@sixb/core 0.1.6 → 0.1.8

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"

package/src/models/language-model.ts

@@ -0,0 +1,143 @@
+import type { JsonObject, ReadonlyJsonObject } from "../json"
+import type { LanguageModelDefinitionCatalog, ModelDefinitionCatalog } from "./catalog"
+import type { LanguageModelDefinition } from "./definitions"
+import type { LanguageModelStreamEvent } from "./events"
+import type { ModelMessage } from "./messages"
+import type { ModelCostEstimator } from "./pricing"
+
+export const MODEL_REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const
+
+export type ModelReasoningEffort = (typeof MODEL_REASONING_EFFORTS)[number]
+
+export const MODEL_REASONING_LEVELS = [
+  "provider-default",
+  "none",
+  ...MODEL_REASONING_EFFORTS,
+] as const
+
+export type ModelReasoningLevel = (typeof MODEL_REASONING_LEVELS)[number]
+
+/** Exact provider-native reasoning budget, expressed in tokens. */
+export interface ModelReasoningBudget extends ReadonlyJsonObject {
+  readonly budgetTokens: number
+}
+
+/** Provider-neutral reasoning preference accepted by every language-model runtime. */
+export type ModelReasoning = ModelReasoningLevel | ModelReasoningBudget
+
+export interface ModelReasoningBudgetCapabilities {
+  readonly min?: number
+  readonly max?: number
+}
+
+/** Controls exposed by one concrete model offering through one provider. */
+export interface ModelReasoningCapabilities {
+  readonly canDisable?: boolean
+  readonly efforts?: readonly ModelReasoningEffort[]
+  readonly budgetTokens?: ModelReasoningBudgetCapabilities
+}
+
+export interface ModelCapabilities {
+  readonly inputMediaTypes?: readonly string[] | "any"
+  /** `undefined` is unknown, `false` is unsupported, and an object describes supported controls. */
+  readonly reasoning?: false | ModelReasoningCapabilities
+  readonly localTools?: boolean
+  readonly parallelToolCalls?: boolean
+  readonly nativeStructuredOutput?: boolean
+  readonly providerExecutedTools?: boolean
+}
+
+export interface ModelToolSpecification {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: JsonObject
+}
+
+export interface ModelResponseFormat {
+  readonly type: "json"
+  readonly name: string
+  readonly description?: string
+  readonly schema: JsonObject
+}
+
+export interface LanguageModelRequest {
+  readonly callId: string
+  readonly messages: readonly ModelMessage[]
+  readonly tools: readonly ModelToolSpecification[]
+  readonly reasoning?: ModelReasoning
+  /** Per-call output ceiling; providers must not exceed a stricter configured model limit. */
+  readonly maxOutputTokens?: number
+  /** Disable automatic prompt caching without overriding explicit provider configuration. */
+  readonly caching?: "auto" | "off"
+  readonly responseFormat?: ModelResponseFormat
+  readonly signal: AbortSignal
+}
+
+export interface LanguageModelStream {
+  readonly events: AsyncIterable<LanguageModelStreamEvent>
+}
+
+export interface LanguageModel {
+  readonly providerId: string
+  readonly modelId: string
+  readonly definition: LanguageModelDefinition
+  readonly costEstimator?: ModelCostEstimator
+  /**
+   * Return an executable model pinned to operational metadata, preserving model identity.
+   * `offline` requires a local snapshot without catalog I/O. Workers retain this model
+   * for generation and compaction; later catalog refreshes must not change its capabilities/limits.
+   * Throw ModelCatalogUnavailableError for catalog transport/access failures to allow workers to
+   * retry with an offline snapshot. Invalid definitions and other resolver errors remain fatal.
+   */
+  resolve?(options?: { readonly offline?: boolean }): Promise<LanguageModel>
+  stream(request: LanguageModelRequest): Promise<LanguageModelStream>
+}
+
+/** The common callable provider shape. Provider packages may accept additional model options. */
+export interface ModelProvider<TCatalog extends ModelDefinitionCatalog = ModelDefinitionCatalog> {
+  readonly providerId: string
+  readonly catalog: TCatalog
+}
+
+export interface LanguageModelProvider extends ModelProvider<LanguageModelDefinitionCatalog> {
+  (modelId: string): LanguageModel
+}
+
+export function isModelReasoning(value: unknown): value is ModelReasoning {
+  if (typeof value === "string") {
+    return (MODEL_REASONING_LEVELS as readonly string[]).includes(value)
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false
+  if (Object.keys(value).length !== 1) return false
+  const budgetTokens = (value as { readonly budgetTokens?: unknown }).budgetTokens
+  return typeof budgetTokens === "number" && Number.isSafeInteger(budgetTokens) && budgetTokens >= 0
+}
+
+/** Explain why a request cannot be represented by known model capabilities. Unknown is allowed. */
+export function modelReasoningSupportIssue(
+  capabilities: ModelCapabilities["reasoning"],
+  reasoning: unknown
+): string | undefined {
+  if (reasoning === undefined) return undefined
+  if (!isModelReasoning(reasoning)) return "the reasoning preference is invalid"
+  if (reasoning === "provider-default") return undefined
+  if (capabilities === undefined) return undefined
+  if (capabilities === false) return "reasoning is not supported"
+  if (reasoning === "none") {
+    return capabilities.canDisable === true ? undefined : "reasoning cannot be disabled"
+  }
+  if (typeof reasoning === "string") {
+    return capabilities.efforts?.includes(reasoning) === true
+      ? undefined
+      : `reasoning effort '${reasoning}' is not supported`
+  }
+  const budget = capabilities.budgetTokens
+  if (budget === undefined) return "reasoning token budgets are not supported"
+  if (budget.min !== undefined && reasoning.budgetTokens < budget.min) {
+    return `reasoning token budget must be at least ${budget.min}`
+  }
+  if (budget.max !== undefined && reasoning.budgetTokens > budget.max) {
+    return `reasoning token budget must not exceed ${budget.max}`
+  }
+  return undefined
+}

package/src/models/messages.ts

@@ -0,0 +1,78 @@
+import type { JsonValue } from "../json"
+
+/** Opaque, JSON-safe provider state. Each provider reads only its own key. */
+export type ProviderData = Readonly<Record<string, JsonValue>>
+
+interface ModelPartBase {
+  readonly providerData?: ProviderData
+}
+
+export interface ModelTextPart extends ModelPartBase {
+  readonly type: "text"
+  readonly text: string
+}
+
+export interface ModelReasoningPart extends ModelPartBase {
+  readonly type: "reasoning"
+  readonly text: string
+}
+
+export interface ModelFilePart extends ModelPartBase {
+  readonly type: "file"
+  readonly data: URL
+  readonly filename?: string
+  readonly mediaType: string
+}
+
+export interface ModelToolCallPart extends ModelPartBase {
+  readonly type: "tool-call"
+  readonly toolCallId: string
+  readonly toolName: string
+  readonly input: JsonValue
+  readonly providerExecuted?: boolean
+  readonly dynamic?: boolean
+}
+
+export type ModelToolOutput =
+  | { readonly type: "text"; readonly value: string }
+  | { readonly type: "json"; readonly value: JsonValue }
+  | { readonly type: "error-text"; readonly value: string }
+  | { readonly type: "error-json"; readonly value: JsonValue }
+
+export interface ModelToolResultPart extends ModelPartBase {
+  readonly type: "tool-result"
+  readonly toolCallId: string
+  readonly toolName: string
+  readonly output: ModelToolOutput
+  /** Original durable tool output when the model-facing output is a projection. */
+  readonly originalOutput?: JsonValue
+  readonly providerExecuted?: boolean
+  readonly dynamic?: boolean
+}
+
+/** Ordered replay state with no honest portable content representation. */
+export interface ModelProviderStatePart {
+  readonly type: "provider-state"
+  readonly providerId: string
+  readonly data: JsonValue
+}
+
+export type ModelAssistantPart =
+  | ModelTextPart
+  | ModelReasoningPart
+  | ModelToolCallPart
+  | ModelToolResultPart
+  | ModelProviderStatePart
+
+export type ModelMessage =
+  | {
+      readonly role: "system"
+      readonly content: string
+      readonly providerData?: ProviderData
+    }
+  | {
+      readonly role: "user"
+      readonly content: readonly (ModelTextPart | ModelFilePart)[]
+    }
+  | { readonly role: "assistant"; readonly content: readonly ModelAssistantPart[] }
+  | { readonly role: "tool"; readonly content: readonly ModelToolResultPart[] }