@sixb/core 0.1.20 → 0.1.22

package/src/models/execution/README.md

@@ -1,6 +1,6 @@
 # Model execution accounting
 
-Internal execution and accounting shared by language, embedding, decision and reranking calls. Application usage is
+Internal execution and accounting shared by language, embedding, decision, reranking, image and speech calls. Application usage is
 documented in [Usage and limits](../../../../../docs/models/usage-and-limits.md).
 
 ## Execution boundary
@@ -44,7 +44,9 @@ replays accounting only, never inference; see the
 [worker recovery contract](../../../../agent-worker/docs/usage-accounting.md).
 
 An Agent run binds its own recorder to its SDK, so calls from its tools share the run's admission,
-failure state and cancellation. Direct provider calls bypass this session. Webhook handlers have no
+failure state and cancellation. A request through the agent API gateway is served by the server,
+not by the run's worker: it gets its own recorder on the run's execution and current attempt, and
+only its own request cancels it. Direct provider calls bypass this session. Webhook handlers have no
 bound model execution attempt; they must dispatch an action for accounted calls. A process crash
 before accounting is captured can still leave provider billing outside the ledger.
 
@@ -62,15 +64,15 @@ and ranking validation. A complete permutation with finite scores is required; t
 candidate order. `RerankingModelResponseError` carries metadata from malformed billable responses.
 
 Provider charges remain distinct from token usage: absent tokens stay unknown. Token limits
-neither admit nor count reranking or transcription calls (`aiLimitMeterApplies` in the limit
-storage helpers), so their unmetered records cannot make a token meter unavailable. Reported
+neither admit nor count reranking, transcription, image or speech calls (`aiLimitMeterApplies` in
+the limit storage helpers), so their unmetered records cannot make a token meter unavailable. Reported
 costs reconcile monetary reservations; missing tariffs fail admission under cost limits. Recovery
 remains the existing accounting-only replay.
 
 ## Decision flow
 
 Decision evaluation in `../decision/runtime.ts` uses the same session and recorder. It snapshots JSON input/questions
-before yielding, resolves only a permitted catalog binding, checks primitive capabilities,
+before yielding, runs the binding the caller passes or the catalog default, checks primitive capabilities,
 admits one call, invokes the provider, and records usage before validating or returning answers.
 The original question snapshot defines valid answer keys, labels and score levels.
 
@@ -81,3 +83,30 @@ must preserve their actual output-token meters even when their output price is z
 `DecisionModelResponseError` carries accounting metadata when protocol translation fails after
 a billable response. Other errors retain unknown usage. Recovery replays accounting, never
 inference. Decision-only projects use the existing recovery worker without an agent sandbox.
+
+## Image flow
+
+Image generation in `../image/runtime.ts` snapshots the request, runs the binding the caller passes
+or the catalog default, and checks it against the definition's sizes, counts and reference-image
+limits before reading any file. Reference images are read with the same size and digest checks as transcription
+audio (`../input-file.ts`).
+
+Admission reserves the binding's `estimateReservation`, keyed by the request's size, quality and
+style; without one, cost limits refuse the call. The call is recorded before its images are
+validated or written: `outputImages` is the number the provider actually returned, whatever its
+own usage says, and the same dimensions select the rate-card variant. Generated images are written
+to blob storage only after accounting, so a cancelled call is billed but stores nothing. Once
+written, they are recorded against the call ID (`aiUsage.recordModelCallFiles`), which is how a
+caller outside the process reads them back; the execution that made the call decides who may.
+
+## Speech flow
+
+Speech generation in `../audio/speech.ts` follows the image flow. A request without a voice takes
+the binding's `defaultVoice`, and voice, format, length and instructions are checked against the
+definition before admission. Sixb never transcodes: a reply in a format other than the one requested
+is an invalid response, recorded but not stored.
+
+Characters and voice tiers are provider rules, so the binding owns both: `estimateReservation`
+receives the text and voice and counts characters itself, providers report `inputCharacters` in
+usage, and `pricingDimensions` in the reply names the tier the provider billed, which selects the
+rate-card variant.

package/src/models/execution/binding.ts

@@ -8,7 +8,9 @@ export interface ModelExecutionAttempt {
   readonly embeddingAdmission?: (admit: () => Promise<void>) => Promise<void>
   /**
    * Accounting the execution attempt already owns, such as an Agent run's. Calls then share its
-   * admission and failure state instead of opening a second recorder for the same attempt.
+   * admission and failure state instead of opening a second recorder for the same attempt. Without
+   * it, the binding opens its own recorder — as an agent API gateway request does on the run's
+   * attempt, outside the run's in-memory failure state and cancellation.
    */
   readonly accounting?: AiModelCallRecorder
 }

package/src/models/execution/embedding.ts

@@ -124,6 +124,7 @@ async function recordEmbedding(
   })
   await accounting.onModelCallEnd({
     callId,
+    modelKind: "embedding",
     providerId: model.providerId,
     modelId: model.modelId,
     responseId: metadata.providerIds?.responseId ?? callId,

package/src/models/execution/index.ts

@@ -1,3 +1,8 @@
+export {
+  formatLanguageModelTiers,
+  isLanguageModelTier,
+  selectLanguageModel,
+} from "../catalog"
 export { resolveLanguageModel } from "../resolve"
 export { ModelUsageRecordingError } from "./errors"
 export type {

package/src/models/execution/model-call-accounting.ts

@@ -152,7 +152,9 @@ function modelCostRecord(
       ? "missingRateCard"
       : input.cost.reason === "missing-usage"
         ? "missingUsageMeter"
-        : "invalidUsageForFormula"
+        : input.cost.reason === "unsupported-pricing-dimension"
+          ? "unsupportedPricingDimension"
+          : "invalidUsageForFormula"
   const missingMeters =
     reason === "missingUsageMeter" ? normalizeMissingMeters(input.cost.missingMeters) : undefined
   return {

package/src/models/execution/model-call-recorder.ts

@@ -1,5 +1,10 @@
 import { randomUUID } from "node:crypto"
-import type { ReadonlyJsonObject, RecordAiModelCallInput } from "../../storage"
+import type { FileRef } from "../../blob-storage/types"
+import {
+  AiUsageStorageError,
+  type ReadonlyJsonObject,
+  type RecordAiModelCallInput,
+} from "../../storage"
 import type { ModelCallEndEvent, ModelUsage } from "../events"
 import type { LanguageModel } from "../language-model"
 import { ModelUsageRecordingError } from "./errors"
@@ -225,6 +230,29 @@ export class AiModelCallRecorder {
     }
   }
 
+  /** Record the files a completed call produced; the call's readers download them through it. */
+  async recordFiles(callId: string, files: readonly FileRef[]): Promise<void> {
+    try {
+      await retryOperation(
+        () =>
+          this.input.storage.aiUsage.recordModelCallFiles({
+            projectId: this.input.projectId,
+            executionId: this.input.executionId,
+            callId,
+            files,
+          }),
+        this.retryDelaysMs,
+        this.sleep,
+        (error) => !(error instanceof TypeError || error instanceof AiUsageStorageError)
+      )
+    } catch (error) {
+      throw new Error(
+        `[SixbModels] Model call '${callId}' completed, but its files could not be recorded.`,
+        { cause: error }
+      )
+    }
+  }
+
   assertHealthy(): void {
     if (this.admissionError !== undefined) throw this.admissionError
     if (this.recordingError) throw this.recordingError

package/src/models/execution/usage.ts

@@ -20,5 +20,13 @@ export function aiModelCallUsageFromModel(usage: ModelUsage): AiModelCallUsageIn
     ...(usage.reasoningOutputTokens === undefined
       ? {}
       : { reasoningOutputTokens: usage.reasoningOutputTokens }),
+    ...(usage.imageOutputTokens === undefined
+      ? {}
+      : { imageOutputTokens: usage.imageOutputTokens }),
+    ...(usage.audioOutputTokens === undefined
+      ? {}
+      : { audioOutputTokens: usage.audioOutputTokens }),
+    ...(usage.outputImages === undefined ? {} : { outputImages: usage.outputImages }),
+    ...(usage.inputCharacters === undefined ? {} : { inputCharacters: usage.inputCharacters }),
   }
 }

package/src/models/execution.ts

@@ -1,16 +1,17 @@
 import { runModelLoop } from "../agents/model-loop"
-import { assertProviderAccess } from "../authorization"
+import { assertModelAccess } from "../authorization"
 import type { BlobStorage } from "../blob-storage/types"
 import type { ExecutionContext } from "../execution"
 import type { SixbRuntimeContext } from "../runtime/types"
 import { createAudioRuntime } from "./audio/runtime"
-import type { ModelCatalog } from "./catalog"
+import { createModelCallsRuntime, type ModelCallRunVisibility } from "./calls"
+import { type ModelCatalog, selectLanguageModel } from "./catalog"
 import { createDecisionRuntime } from "./decision/runtime"
 import { ModelProviderError, ModelStreamError, UnsupportedModelFeatureError } from "./errors"
 import type { ModelCallEndEvent } from "./events"
 import { registerModelExecutionBinding } from "./execution/binding"
 import { aiModelCallOutputTokenAllowance } from "./execution/model-call-admission"
-import { ModelExecutionSession } from "./execution/session"
+import type { ModelExecutionSession } from "./execution/session"
 import type {
   InferLanguageModelOutput,
   LanguageModelGenerateInput,
@@ -18,6 +19,7 @@ import type {
   LanguageModelOutputShape,
   ModelsRuntime,
 } from "./generation-types"
+import { createImageRuntime } from "./image/runtime"
 import { modelReasoningSupportIssue } from "./language-model"
 import type { ModelMessage } from "./messages"
 import { languageModelOutput } from "./output"
@@ -27,10 +29,10 @@ export function createModelsRuntime(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext,
   catalog: ModelCatalog | undefined,
+  session: ModelExecutionSession,
+  runs: ModelCallRunVisibility,
   blobs?: BlobStorage
 ): ModelsRuntime {
-  const session = runtime.modelExecution ?? new ModelExecutionSession(runtime, execution)
-
   function generate<const TShape extends LanguageModelOutputShape | undefined = undefined>(
     input: LanguageModelGenerateInput<TShape>
   ): Promise<
@@ -41,24 +43,15 @@ export function createModelsRuntime(
   async function generate(
     input: LanguageModelGenerateInput<LanguageModelOutputShape | undefined>
   ): Promise<LanguageModelGenerateResult<unknown>> {
-    assertProviderAccess(runtime, execution, "models.language.generate")
+    assertModelAccess(runtime, execution, "models.language.generate")
     const messages = generationMessages(input)
     const signal = session.signal(input.signal)
     signal.throwIfAborted()
-    // The catalog's binding is the configured one, default reasoning included.
-    const selected = input.model
-      ? catalog
-        ? catalog.language?.getByRef({
-            provider: input.model.providerId,
-            modelId: input.model.modelId,
-          })?.model
-        : input.model
-      : catalog?.language?.default.model
+    // An explicit model runs as given, listed or not; the catalog supplies a tier's or the default.
+    const selected = selectLanguageModel(catalog?.language, input.model)
     if (!selected) {
       throw new Error(
-        input.model
-          ? `[SixbModels] Model '${input.model.providerId}/${input.model.modelId}' is not configured in models.language.`
-          : "[SixbModels] Configure models.language in createSixb() or supply a model to generate()."
+        "[SixbModels] Configure models.language in createSixb() or supply a model to generate()."
       )
     }
     const output =
@@ -71,16 +64,19 @@ export function createModelsRuntime(
       input.reasoning
     )
     if (reasoningIssue) throw new UnsupportedModelFeatureError(`[SixbModels] ${reasoningIssue}.`)
-    // The default was checked against the capabilities known at startup; like any request, a level
-    // the resolved model turns out not to support falls back to the provider default.
+    // A catalog model's default was checked against the capabilities known at startup; like any
+    // request, a level the resolved model turns out not to support falls back to the provider default.
     const reasoning = input.reasoning ?? selected.defaultReasoning
     if (output && model.definition.capabilities.nativeStructuredOutput === false) {
       throw new UnsupportedModelFeatureError(
         "[SixbModels] Model does not support native structured output."
       )
     }
+    // Like its reasoning, the binding's output limit applies unless the call sets its own.
     const maxOutputTokens = Math.min(
-      aiModelCallOutputTokenAllowance(input.maxOutputTokens ?? model.definition.maxOutputTokens),
+      aiModelCallOutputTokenAllowance(
+        input.maxOutputTokens ?? selected.maxOutputTokens ?? model.definition.maxOutputTokens
+      ),
       model.definition.maxOutputTokens ?? Infinity
     )
     if (typeof reasoning === "object" && reasoning.budgetTokens >= maxOutputTokens) {
@@ -129,8 +125,10 @@ export function createModelsRuntime(
 
   const models: ModelsRuntime = {
     language: { generate },
-    decision: createDecisionRuntime(runtime, execution, catalog, session),
+    decision: createDecisionRuntime(runtime, execution, catalog, session, "models"),
     audio: createAudioRuntime(runtime, execution, catalog, session, blobs),
+    image: createImageRuntime(runtime, execution, catalog, session, blobs),
+    calls: createModelCallsRuntime(runtime, runs, execution.id),
   }
   registerModelExecutionBinding(models, (input) => {
     session.bind(input)

package/src/models/generation-types.ts

@@ -1,7 +1,10 @@
 import type { InferSchemaOrRef, SchemaOrRef } from "../ontology"
 import type { AudioModelsRuntime } from "./audio/types"
+import type { ModelCallsRuntime } from "./calls"
+import type { LanguageModelTier } from "./catalog"
 import type { DecisionModelsRuntime } from "./decision/types"
 import type { ModelFinishReason, ModelUsage } from "./events"
+import type { ImageModelsRuntime } from "./image/types"
 import type { LanguageModel, ModelReasoning } from "./language-model"
 import type { ModelMessage } from "./messages"
 import type { ModelCallCost } from "./pricing"
@@ -17,7 +20,8 @@ export type LanguageModelGenerateInput<
   TShape extends LanguageModelOutputShape | undefined = undefined,
 > = {
   readonly instructions?: string
-  readonly model?: LanguageModel
+  /** A model runs as given; a tier runs that tier's model from `models.language`. */
+  readonly model?: LanguageModel | LanguageModelTier
   readonly output?: TShape
   readonly maxOutputTokens?: number
   readonly reasoning?: ModelReasoning
@@ -51,4 +55,7 @@ export interface ModelsRuntime {
   readonly audio: AudioModelsRuntime
   readonly language: LanguageModelsRuntime
   readonly decision: DecisionModelsRuntime
+  readonly image: ImageModelsRuntime
+  /** What past calls produced, as visible as the runs that made them. */
+  readonly calls: ModelCallsRuntime
 }

package/src/models/image/catalog.ts

@@ -0,0 +1,89 @@
+import type { ModelRef } from "../catalog"
+import { indexModelBindings } from "../catalog-index"
+import type { ImageModel } from "./types"
+
+export interface ImageModelEntry extends ModelRef {
+  readonly model: ImageModel
+}
+
+export interface ImageModelCatalog {
+  readonly default: ImageModelEntry
+  list(): readonly ImageModelEntry[]
+  getByRef(ref: ModelRef): ImageModelEntry | null
+}
+
+export function createImageCatalog(
+  models: readonly ImageModel[] | undefined
+): ImageModelCatalog | undefined {
+  if (models === undefined) return undefined
+  if (!Array.isArray(models)) {
+    throw new TypeError("[Sixb] models.image must be a nonempty array of image models.")
+  }
+
+  const index = indexModelBindings(models, "image", assertImageModel)
+  const [defaultEntry] = index.list()
+  if (!defaultEntry) {
+    throw new TypeError("[Sixb] models.image must contain at least one model.")
+  }
+
+  return Object.freeze({ ...index, default: defaultEntry })
+}
+
+export function assertImageModel(model: unknown): asserts model is ImageModel {
+  const candidate = model as Partial<ImageModel> | null
+  const definition = candidate?.definition
+  if (
+    !candidate ||
+    !isValidId(candidate.providerId) ||
+    !isValidId(candidate.modelId) ||
+    typeof candidate.generate !== "function" ||
+    definition?.kind !== "image" ||
+    definition.providerId !== candidate.providerId ||
+    definition.modelId !== candidate.modelId
+  ) {
+    throw invalidModel("identity")
+  }
+
+  if (
+    definition.maxImagesPerCall !== undefined &&
+    !isPositiveInteger(definition.maxImagesPerCall)
+  ) {
+    throw invalidModel("maxImagesPerCall")
+  }
+  for (const field of ["sizes", "aspectRatios", "qualities", "styles"] as const) {
+    if (!isOptionalList(definition[field])) throw invalidModel(field)
+  }
+
+  const inputImages = definition.inputImages
+  if (
+    inputImages !== undefined &&
+    (!inputImages ||
+      !isPositiveInteger(inputImages.maxCount) ||
+      !isPositiveInteger(inputImages.maxBytes) ||
+      !isOptionalList(inputImages.mediaTypes) ||
+      inputImages.mediaTypes?.some((type) => !/^image\/[a-z0-9.+-]+$/.test(type)))
+  ) {
+    throw invalidModel("inputImages")
+  }
+}
+
+function isOptionalList(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (Array.isArray(value) &&
+      value.length > 0 &&
+      value.every((entry) => typeof entry === "string" && entry.trim() === entry && entry))
+  )
+}
+
+function isPositiveInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+}
+
+function isValidId(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.trim() === value
+}
+
+function invalidModel(field: string): TypeError {
+  return new TypeError(`[SixbModels] Invalid image model ${field}.`)
+}

package/src/models/image/errors.ts

@@ -0,0 +1,19 @@
+import { ModelProviderError } from "../errors"
+import type { ImageModelResponseMetadata } from "./types"
+
+/** Retains billing metadata even when the provider returns invalid images. */
+export class ImageModelResponseError extends ModelProviderError {
+  constructor(
+    message: string,
+    providerId: string,
+    modelId: string,
+    readonly metadata: ImageModelResponseMetadata,
+    options?: ErrorOptions
+  ) {
+    super(message, providerId, modelId, {
+      ...options,
+      code: "invalid_image_response",
+      retryable: false,
+    })
+  }
+}