@sixb/core 0.1.21 → 0.1.22

package/src/models/audio/speech.ts

@@ -0,0 +1,261 @@
+import { randomUUID } from "node:crypto"
+import { assertModelAccess } from "../../authorization"
+import type { BlobStorage } from "../../blob-storage/types"
+import type { ExecutionContext } from "../../execution"
+import type { SixbRuntimeContext } from "../../runtime/types"
+import type { ModelCatalog } from "../catalog"
+import type { ModelCallEndEvent } from "../events"
+import type { AiModelCallRecorder } from "../execution/model-call-recorder"
+import type { ModelExecutionSession } from "../execution/session"
+import { estimateModelCall, type ModelMoney } from "../pricing"
+import { assertSpeechModel } from "./catalog"
+import { SpeechModelResponseError } from "./errors"
+import type {
+  AudioModelsRuntime,
+  AudioSpeakInput,
+  SpeechModel,
+  SpeechModelRequest,
+  SpeechModelResponseMetadata,
+  SpeechModelResult,
+  SpeechReservationInput,
+} from "./types"
+
+type PreparedRequest = Omit<SpeechModelRequest, "signal">
+
+export function createSpeak(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  catalog: ModelCatalog | undefined,
+  session: ModelExecutionSession,
+  blobs: BlobStorage | undefined
+): AudioModelsRuntime["speak"] {
+  return async (input) => {
+    assertModelAccess(runtime, execution, "models.audio.speak")
+
+    const prepared = prepareRequest(input)
+    if (!blobs) {
+      throw new Error("[SixbModels] Speech generation requires blob storage.")
+    }
+
+    const signal = session.signal(input.signal)
+    signal.throwIfAborted()
+
+    const binding = selectModel(catalog, input.model)
+    assertSpeechModel(binding)
+    assertRequestSupport(binding, withVoice(binding, prepared))
+
+    const accounting = await session.accounting()
+    accounting.assertHealthy()
+
+    const model = binding.resolve ? await binding.resolve() : binding
+    assertSpeechModel(model)
+    if (model.providerId !== binding.providerId || model.modelId !== binding.modelId) {
+      throw new TypeError(
+        "[SixbModels] Resolved speech model identity does not match the selected model."
+      )
+    }
+    const request = withVoice(model, prepared)
+    assertRequestSupport(model, request)
+    signal.throwIfAborted()
+
+    const callId = `call_${randomUUID()}`
+    await accounting.admitCall({
+      callId,
+      providerId: model.providerId,
+      modelId: model.modelId,
+      modelKind: "speech",
+      inputTokens: {
+        status: "estimated",
+        tokens: Math.ceil(new TextEncoder().encode(request.text).byteLength / 4),
+        method: "utf8BytesDividedByFour",
+      },
+      outputTokenAllowance: 0,
+      reservationCost: estimateReservationCost(model, {
+        text: request.text,
+        ...(request.voice === undefined ? {} : { voice: request.voice }),
+        ...(request.instructions === undefined ? {} : { instructions: request.instructions }),
+      }),
+    })
+
+    let result: SpeechModelResult
+    try {
+      signal.throwIfAborted()
+      result = await model.speak({ ...request, signal })
+    } catch (error) {
+      await recordSpeech(
+        accounting,
+        model,
+        callId,
+        error instanceof SpeechModelResponseError ? error.metadata : {}
+      )
+      throw error
+    }
+
+    // A completed, billable reply must survive cancellation and audio validation failures.
+    const event = await recordSpeech(accounting, model, callId, result ?? {})
+    signal.throwIfAborted()
+    const audio = result?.output?.audio
+    if (
+      !(audio?.data instanceof Uint8Array) ||
+      audio.data.byteLength === 0 ||
+      typeof audio.mediaType !== "string" ||
+      !/^audio\/[a-z0-9.+-]+$/.test(audio.mediaType) ||
+      (request.mediaType !== undefined && audio.mediaType !== request.mediaType) ||
+      !isWarnings(result.warnings)
+    ) {
+      throw new SpeechModelResponseError(
+        "[SixbModels] Invalid speech response.",
+        model.providerId,
+        model.modelId,
+        result ?? {}
+      )
+    }
+
+    const file = await blobs.put({
+      body: audio.data,
+      expectedSizeBytes: audio.data.byteLength,
+      mediaType: audio.mediaType,
+      signal,
+    })
+    await accounting.recordFiles(callId, [file])
+    return {
+      file,
+      warnings: [...(result.warnings ?? [])],
+      usage: event.usage,
+      cost: event.cost,
+      callId,
+    }
+  }
+}
+
+/** Validate and snapshot the caller's request before the first await. */
+function prepareRequest(input: AudioSpeakInput): PreparedRequest {
+  if (typeof input?.text !== "string" || !input.text.trim()) {
+    throw new TypeError("[SixbModels] Speech generation requires nonblank text.")
+  }
+  for (const field of ["voice", "instructions", "language"] as const) {
+    const value = input[field]
+    if (value !== undefined && (typeof value !== "string" || !value.trim())) {
+      throw new TypeError(`[SixbModels] Speech ${field} must be a nonblank string.`)
+    }
+  }
+  const mediaType = input.mediaType?.split(";", 1)[0]?.trim().toLowerCase()
+  if (input.mediaType !== undefined && !/^audio\/[a-z0-9.+-]+$/.test(mediaType ?? "")) {
+    throw new TypeError("[SixbModels] Speech mediaType must be an audio media type.")
+  }
+  if (
+    input.speed !== undefined &&
+    (typeof input.speed !== "number" || !Number.isFinite(input.speed) || input.speed <= 0)
+  ) {
+    throw new TypeError("[SixbModels] Speech speed must be a positive number.")
+  }
+
+  return {
+    text: input.text,
+    ...(input.voice === undefined ? {} : { voice: input.voice }),
+    ...(input.instructions === undefined ? {} : { instructions: input.instructions }),
+    ...(mediaType === undefined ? {} : { mediaType }),
+    ...(input.speed === undefined ? {} : { speed: input.speed }),
+    ...(input.language === undefined ? {} : { language: input.language }),
+  }
+}
+
+function withVoice(model: SpeechModel, request: PreparedRequest): PreparedRequest {
+  const voice = request.voice ?? model.defaultVoice
+  return voice === undefined ? request : { ...request, voice }
+}
+
+function selectModel(
+  catalog: ModelCatalog | undefined,
+  requested: SpeechModel | undefined
+): SpeechModel {
+  // A model the caller passes runs as given, listed or not; the catalog supplies the default.
+  const selected = requested ?? catalog?.audio?.speech?.default.model
+  if (!selected) {
+    throw new Error(
+      "[SixbModels] Configure models.audio.speech in createSixb() or supply a model to speak()."
+    )
+  }
+
+  return selected
+}
+
+function assertRequestSupport(model: SpeechModel, request: PreparedRequest): void {
+  const definition = model.definition
+  if (
+    definition.maxInputCharacters !== undefined &&
+    request.text.length > definition.maxInputCharacters
+  ) {
+    throw new RangeError(
+      `[SixbModels] Text exceeds the model's ${definition.maxInputCharacters}-character input limit.`
+    )
+  }
+  if (
+    request.voice !== undefined &&
+    definition.voices &&
+    !definition.voices.includes(request.voice)
+  ) {
+    throw new TypeError(
+      `[SixbModels] Voice '${request.voice}' is not supported by the selected model. Use one of: ${definition.voices.join(", ")}.`
+    )
+  }
+  if (
+    request.mediaType !== undefined &&
+    definition.outputMediaTypes &&
+    !definition.outputMediaTypes.includes(request.mediaType)
+  ) {
+    throw new TypeError(
+      `[SixbModels] Speech media type '${request.mediaType}' is not supported by the selected model. Use one of: ${definition.outputMediaTypes.join(", ")}.`
+    )
+  }
+  if (request.instructions !== undefined && definition.instructions === false) {
+    throw new TypeError("[SixbModels] The selected model does not take speech instructions.")
+  }
+}
+
+function estimateReservationCost(
+  model: SpeechModel,
+  input: SpeechReservationInput
+): ModelMoney | undefined {
+  try {
+    return model.costEstimator?.estimateReservation?.(input)
+  } catch {
+    // Optional pricing cannot bypass an enforced budget: admission fails closed without it.
+    return undefined
+  }
+}
+
+async function recordSpeech(
+  accounting: AiModelCallRecorder,
+  model: SpeechModel,
+  callId: string,
+  metadata: SpeechModelResponseMetadata
+): Promise<ModelCallEndEvent> {
+  const usage = metadata.usage ?? {}
+  const estimate = estimateModelCall(model, {
+    usage,
+    route: metadata.route,
+    responseModelId: metadata.responseModelId,
+    ...(metadata.pricingDimensions === undefined ? {} : { dimensions: metadata.pricingDimensions }),
+  })
+  const event: ModelCallEndEvent = {
+    callId,
+    modelKind: "speech",
+    providerId: model.providerId,
+    modelId: model.modelId,
+    responseId: metadata.providerIds?.responseId ?? callId,
+    providerIds: metadata.providerIds,
+    responseModelId: metadata.responseModelId,
+    usage,
+    cost: metadata.reportedCost ? { status: "reported", ...metadata.reportedCost } : estimate,
+    ...(metadata.reportedCost ? { estimate } : {}),
+    route: metadata.route,
+  }
+
+  await accounting.onModelCallEnd(event)
+  return event
+}
+
+function isWarnings(value: unknown): value is readonly string[] | undefined {
+  return value === undefined || (Array.isArray(value) && value.every((w) => typeof w === "string"))
+}

package/src/models/audio/types.ts

@@ -2,6 +2,7 @@ import type { FileRef } from "../../blob-storage/types"
 import type { ModelDefinition } from "../definitions"
 import type { ModelProviderIds, ModelRoute, ModelUsage } from "../events"
 import type { ModelCallCost, ModelCostEstimator, ModelMoney, ModelReportedCost } from "../pricing"
+import type { ModelPricingDimensions, ModelRateCard } from "../rate-card"
 
 export interface TranscriptionModelDefinition extends ModelDefinition {
   readonly kind: "transcription"
@@ -47,6 +48,11 @@ export interface TranscriptionModel {
   readonly modelId: string
   readonly definition: TranscriptionModelDefinition
   readonly costEstimator?: TranscriptionCostEstimator
+  /**
+   * The prices this binding bills by, for people and agents choosing a model. Pricing itself
+   * goes through costEstimator; absent when the price is unknown.
+   */
+  readonly rateCard?: ModelRateCard
   resolve?(): Promise<TranscriptionModel>
   transcribe(request: TranscriptionModelRequest): Promise<TranscriptionModelResult>
 }
@@ -64,6 +70,97 @@ export interface AudioTranscribeResult {
   readonly callId: string
 }
 
+/** Serializable facts about one speech model. Omitted lists mean the provider publishes none. */
+export interface SpeechModelDefinition extends ModelDefinition {
+  readonly kind: "speech"
+  /** In UTF-16 code units (JavaScript string length). Providers may impose lower limits. */
+  readonly maxInputCharacters?: number
+  readonly voices?: readonly string[]
+  /** Formats the model can return, such as `audio/mpeg`. Sixb never transcodes. */
+  readonly outputMediaTypes?: readonly string[]
+  /** Whether the model takes style instructions. Undefined is unknown. */
+  readonly instructions?: boolean
+}
+
+export interface SpeechModelRequest {
+  readonly text: string
+  readonly voice?: string
+  readonly instructions?: string
+  readonly mediaType?: string
+  readonly speed?: number
+  readonly language?: string
+  readonly signal?: AbortSignal
+}
+
+export interface SpeechModelResponseMetadata {
+  readonly usage?: ModelUsage
+  readonly providerIds?: ModelProviderIds
+  readonly responseModelId?: string
+  readonly reportedCost?: ModelReportedCost
+  readonly route?: ModelRoute
+  /** What the provider billed by, such as the tier of the voice it used. */
+  readonly pricingDimensions?: ModelPricingDimensions
+}
+
+export interface SpeechModelResult extends SpeechModelResponseMetadata {
+  /** A playable file: providers whose API returns raw samples wrap them, for example in WAV. */
+  readonly output: { readonly audio: { readonly data: Uint8Array; readonly mediaType: string } }
+  /** Provider notes about the request, such as a setting it ignored. */
+  readonly warnings?: readonly string[]
+}
+
+export interface SpeechReservationInput {
+  /** The binding counts characters by its provider's own rule. */
+  readonly text: string
+  readonly voice?: string
+  readonly instructions?: string
+}
+
+export interface SpeechCostEstimator extends Pick<ModelCostEstimator, "estimate"> {
+  /** Return undefined if the request cannot be priced safely before inference. */
+  estimateReservation?(input: SpeechReservationInput): ModelMoney | undefined
+}
+
+/** Provider binding. Resolving it may fetch metadata, but must never perform inference. */
+export interface SpeechModel {
+  readonly providerId: string
+  readonly modelId: string
+  readonly definition: SpeechModelDefinition
+  /** Used when a request names no voice, so switching models never requires one. */
+  readonly defaultVoice?: string
+  readonly costEstimator?: SpeechCostEstimator
+  /**
+   * The prices this binding bills by, for people and agents choosing a model. Pricing itself
+   * goes through costEstimator; absent when the price is unknown.
+   */
+  readonly rateCard?: ModelRateCard
+  resolve?(): Promise<SpeechModel>
+  speak(request: SpeechModelRequest): Promise<SpeechModelResult>
+}
+
+export interface AudioSpeakInput {
+  readonly text: string
+  /** Defaults to the binding's default voice. */
+  readonly voice?: string
+  readonly instructions?: string
+  /** The format to return, such as `audio/mpeg`. Defaults to the provider's. */
+  readonly mediaType?: string
+  readonly speed?: number
+  readonly language?: string
+  readonly model?: SpeechModel
+  readonly signal?: AbortSignal
+}
+
+export interface AudioSpeakResult {
+  /** The generated audio, already written to blob storage. */
+  readonly file: FileRef
+  readonly warnings: readonly string[]
+  readonly usage: ModelUsage
+  readonly cost: ModelCallCost
+  readonly callId: string
+}
+
 export interface AudioModelsRuntime {
   transcribe(input: AudioTranscribeInput): Promise<AudioTranscribeResult>
+  speak(input: AudioSpeakInput): Promise<AudioSpeakResult>
 }

package/src/models/calls.ts

@@ -0,0 +1,100 @@
+import { principalsEqual } from "../auth/types"
+import type { FileRef } from "../blob-storage/types"
+import { resolveRuntimeAuthorizationForProject } from "../execution/authorization"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { ExecutionRecord } from "../storage/executions"
+
+/** The files one model call produced. */
+export interface ModelCallFiles {
+  readonly callId: string
+  readonly files: readonly FileRef[]
+  readonly recordedAt: Date
+}
+
+export interface ModelCallsRuntime {
+  /**
+   * The files a call produced, when the caller can see the run that made it: the request's own
+   * principal, the agent thread's readers, or the action or workflow run's viewers. Null when the
+   * call produced none or is hidden; usage observers see a call's cost, not its content.
+   */
+  files(callId: string): Promise<ModelCallFiles | null>
+}
+
+/** Whether the caller sees a run, as the runtime's own run lookups decide it. */
+export interface ModelCallRunVisibility {
+  canViewActionRun(runId: string): Promise<boolean>
+  canViewWorkflowRun(runId: string): Promise<boolean>
+  /** A conversation run: visible to whoever can read its thread. */
+  canViewAgentRun(runId: string): Promise<boolean>
+}
+
+// Subagents nest; a chain longer than this is a storage fault, not a deeper delegation.
+const MAX_SUBAGENT_DEPTH = 32
+
+export function createModelCallsRuntime(
+  runtime: Pick<SixbRuntimeContext, "projectId" | "runtimeAuthorization" | "storage">,
+  runs: ModelCallRunVisibility,
+  /** The execution reading; it reads what it produced, whoever can see its run. */
+  executionId?: string
+): ModelCallsRuntime {
+  const projectId = runtime.projectId
+
+  async function canRead(execution: ExecutionRecord): Promise<boolean> {
+    const authority = resolveRuntimeAuthorizationForProject(runtime)
+    if (authority.type === "unrestricted") return true
+    if (authority.type !== "principal") return false
+
+    const executor = execution.executor
+    if (executor.type === "request") {
+      return (
+        execution.requestedBy !== undefined &&
+        principalsEqual(authority.context.principal, execution.requestedBy)
+      )
+    }
+    if (executor.type === "primitive") {
+      if (executor.kind === "action") return runs.canViewActionRun(executor.runId)
+      if (executor.kind === "workflow") return runs.canViewWorkflowRun(executor.runId)
+      return false
+    }
+    if (executor.type === "agent") return canReadAgentRun(executor.runId)
+    return false
+  }
+
+  async function canReadAgentRun(runId: string): Promise<boolean> {
+    const agents = runtime.storage.agents
+    let id = runId
+    for (let depth = 0; depth < MAX_SUBAGENT_DEPTH; depth += 1) {
+      const run = agents ? await agents.runs.getById({ projectId, id }) : null
+      if (run?.kind === "conversation") return runs.canViewAgentRun(run.id)
+      if (run?.kind === "subagent") {
+        id = run.parentRunId
+        continue
+      }
+      // A workflow's agent step runs as a node of that workflow's run.
+      const node = await runtime.storage.workflowRuns?.nodes.getById({ projectId, id })
+      return node ? runs.canViewWorkflowRun(node.workflowRunId) : false
+    }
+    return false
+  }
+
+  return {
+    async files(callId) {
+      if (typeof callId !== "string" || !callId.trim()) {
+        throw new TypeError("[SixbModels] A model call ID must be a nonblank string.")
+      }
+      const record = await runtime.storage.aiUsage?.getModelCallFiles({ projectId, callId })
+      if (!record) return null
+
+      // A workflow's agent step runs as a service account that cannot view its own workflow run,
+      // yet must read back the image it just made.
+      const visible = { callId: record.callId, files: record.files, recordedAt: record.recordedAt }
+      if (record.executionId === executionId) return visible
+
+      const execution = await runtime.storage.executions.getById({
+        projectId,
+        id: record.executionId,
+      })
+      return execution && (await canRead(execution)) ? visible : null
+    },
+  }
+}

package/src/models/catalog-index.ts

@@ -10,12 +10,30 @@ interface ModelEntry<TModel> extends ModelRef {
   readonly model: TModel
 }
 
+interface ModelIndex<TEntry> {
+  list(): readonly TEntry[]
+  getByRef(ref: ModelRef): TEntry | null
+}
+
 /** Private index shared by model families; default selection belongs to each family. */
 export function indexModelBindings<TModel extends ModelBinding>(
   models: readonly TModel[],
   kind: string,
   validate: (model: TModel, index: number) => void
-) {
+): ModelIndex<ModelEntry<TModel>>
+/** A family that adds its own fields to each entry, such as a language model's tier. */
+export function indexModelBindings<TModel extends ModelBinding, TFields extends object>(
+  models: readonly TModel[],
+  kind: string,
+  validate: (model: TModel, index: number) => void,
+  fields: (index: number) => TFields
+): ModelIndex<ModelEntry<TModel> & TFields>
+export function indexModelBindings<TModel extends ModelBinding>(
+  models: readonly TModel[],
+  kind: string,
+  validate: (model: TModel, index: number) => void,
+  fields?: (index: number) => object
+): ModelIndex<ModelEntry<TModel>> {
   const byRef = new Map<string, ModelEntry<TModel>>()
 
   for (const [index, model] of models.entries()) {
@@ -27,7 +45,8 @@ export function indexModelBindings<TModel extends ModelBinding>(
       )
     }
 
-    byRef.set(key, Object.freeze({ provider: model.providerId, modelId: model.modelId, model }))
+    const entry = { provider: model.providerId, modelId: model.modelId, model }
+    byRef.set(key, Object.freeze(fields ? { ...entry, ...fields(index) } : entry))
   }
 
   const entries = Object.freeze([...byRef.values()])