@sixb/core 0.1.6 → 0.1.8

package/src/storage/agents/provider.ts

@@ -1,5 +1,8 @@
-import { agentServiceAccountId } from "../../agents/authority"
-import type { ExecutionStorage } from "../executions"
+import { isDeepStrictEqual } from "node:util"
+import { AGENT_REASONING_LEVELS } from "../../agents/types"
+import { isFileRef } from "../../blob-storage"
+import { isModelReasoning } from "../../models/language-model"
+import type { ExecutionRecord, ExecutionStorage } from "../executions"
 import { findAgentRunExecution } from "../executions/run-link"
 import { AgentStorageError } from "./errors"
 import type {
@@ -7,23 +10,60 @@ import type {
   AgentMessageRecord,
   AgentRunRecord,
   AgentThreadRecord,
+  ConversationAgentRunSpec,
   CreateAgentContextCheckpointInput,
+  CreateSubagentRunInput,
+  SubagentRunRecord,
+  SubagentRunResult,
 } from "./types"
 
+/** Validate the provider-neutral model selection captured for a conversational turn. */
+export function assertConversationAgentRunSpec(
+  spec: ConversationAgentRunSpec,
+  prefix = "Sixb"
+): void {
+  if (!isRecord(spec) || !isRecord(spec.model)) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Conversational Agent run spec must contain a model reference.`
+    )
+  }
+  for (const [name, value] of [
+    ["model.provider", spec.model.provider],
+    ["model.modelId", spec.model.modelId],
+  ] as const) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[${prefix}] Conversational Agent run '${name}' must not be empty.`
+      )
+    }
+  }
+  if (spec.reasoning !== undefined && !isModelReasoning(spec.reasoning)) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Conversational Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
+    )
+  }
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
 /** Validate the semantic link between a conversational Agent run and its immutable execution. */
 export async function assertAgentRunExecution(input: {
   readonly executions: ExecutionStorage
   readonly projectId: string
   readonly executionId: string
   readonly runId: string
-  readonly agentId: string
-}): Promise<void> {
+}): Promise<ExecutionRecord> {
   const execution = await findAgentRunExecution({
     executions: input.executions,
     projectId: input.projectId,
     executionId: input.executionId,
     runId: input.runId,
-    serviceAccountId: agentServiceAccountId(input.agentId),
+    authority: { type: "inherited" },
   })
   if (!execution) {
     throw new AgentStorageError(
@@ -31,6 +71,110 @@ export async function assertAgentRunExecution(input: {
       `[Sixb] Execution '${input.executionId}' does not authorize Agent run '${input.runId}'.`
     )
   }
+  return execution
+}
+
+/** Validate the provider-neutral payload of an idempotent child admission. */
+export function assertCreateSubagentRunInput(input: CreateSubagentRunInput, prefix = "Sixb"): void {
+  for (const [name, value] of [
+    ["id", input.id],
+    ["projectId", input.projectId],
+    ["executionId", input.executionId],
+    ["parentRunId", input.parentRunId],
+    ["parentExecutionToken", input.parentExecutionToken],
+    ["spawnKey", input.spawnKey],
+    ["model.provider", input.spec.model.provider],
+    ["model.modelId", input.spec.model.modelId],
+    ["task", input.spec.task],
+  ] as const) {
+    if (value.trim().length === 0) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[${prefix}] Subagent run '${name}' must not be empty.`
+      )
+    }
+  }
+  if (input.spawnKey.length > 128) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Subagent spawn key must not exceed 128 characters.`
+    )
+  }
+  for (const [name, value] of [
+    ["maxActiveChildren", input.maxActiveChildren],
+    ["spec.maxSteps", input.spec.maxSteps],
+  ] as const) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[${prefix}] Subagent run '${name}' must be a positive safe integer.`
+      )
+    }
+  }
+  if (new Set(input.spec.toolNames).size !== input.spec.toolNames.length) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Subagent run tool names must be unique.`
+    )
+  }
+  if (input.spec.reasoning !== undefined && !isModelReasoning(input.spec.reasoning)) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Subagent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
+    )
+  }
+  if (input.spec.toolNames.some((name) => !name.trim())) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Subagent run tool names must not be empty.`
+    )
+  }
+  if (input.createdAt && !Number.isFinite(input.createdAt.getTime())) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Subagent run createdAt must be a valid date.`
+    )
+  }
+}
+
+/** Exact semantic match required when a durable spawn key is replayed. */
+export function subagentRunMatchesCreateInput(
+  run: AgentRunRecord,
+  input: CreateSubagentRunInput
+): run is SubagentRunRecord {
+  return (
+    run.kind === "subagent" &&
+    run.id === input.id &&
+    run.projectId === input.projectId &&
+    run.executionId === input.executionId &&
+    run.parentRunId === input.parentRunId &&
+    run.spawnKey === input.spawnKey &&
+    isDeepStrictEqual(run.spec, input.spec)
+  )
+}
+
+/** Validate the small durable result returned by a successful child. */
+export function assertSubagentRunResult(
+  result: SubagentRunResult | undefined,
+  runId: string,
+  prefix = "Sixb"
+): asserts result is SubagentRunResult {
+  const text = result?.text
+  const files = result?.files
+  const hasText = typeof text === "string" && text.trim().length > 0
+  const hasFiles = Array.isArray(files) && files.length > 0 && files.every(isFileRef)
+  if (!result || (!hasText && !hasFiles)) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Succeeded subagent run '${runId}' requires text or files.`
+    )
+  }
+  if ((text !== undefined && !hasText) || (files !== undefined && !hasFiles)) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Subagent run '${runId}' has an invalid result.`
+    )
+  }
 }
 
 /** Validate provider-independent checkpoint fields before entering a storage critical section. */
@@ -136,7 +280,7 @@ export function assertAgentContextCheckpointAuthority(input: {
       `[${prefix}] Agent thread '${create.threadId}' not found for project '${create.projectId}'.`
     )
   }
-  if (run.threadId !== create.threadId) {
+  if (run.kind !== "conversation" || run.threadId !== create.threadId) {
     throw new AgentStorageError(
       "invalid_input",
       `[${prefix}] Agent run '${run.id}' does not belong to thread '${create.threadId}'.`

package/src/storage/agents/types.ts

@@ -1,7 +1,10 @@
 import type { AgentMessage, AgentMessagePart, AgentMessageRole } from "../../agents/message"
+import type { AgentReasoningLevel } from "../../agents/types"
 import type { Principal } from "../../auth"
+import type { FileRef } from "../../blob-storage"
 import type { SixbErrorCode, SixbFailure } from "../../errors/types"
 import type { JsonValue } from "../../json"
+import type { LanguageModelRef } from "../../models"
 
 // ── agent_threads — one conversation with an agent ──────────────────────────────────────────────
 
@@ -10,7 +13,6 @@ export type AgentThreadStatus = "active" | "archived"
 export interface AgentThreadRecord {
   readonly id: string
   readonly projectId: string
-  readonly agentId: string
   /** Who owns/opened the thread. Reuses the canonical auth principal (gains `agent` later for free). */
   readonly ownerPrincipal: Principal
   readonly title?: string
@@ -26,7 +28,6 @@ export interface AgentThreadRecord {
 export interface CreateAgentThreadInput {
   readonly id: string
   readonly projectId: string
-  readonly agentId: string
   readonly ownerPrincipal: Principal
   readonly title?: string
   readonly status?: AgentThreadStatus
@@ -36,9 +37,6 @@ export interface CreateAgentThreadInput {
 
 export interface ListAgentThreadsInput {
   readonly projectId: string
-  readonly agentId?: string
-  /** Optional allowlist intersected with `agentId` when both are provided. Empty means no rows. */
-  readonly agentIds?: readonly string[]
   readonly statuses?: readonly AgentThreadStatus[]
   readonly ownerPrincipal?: Principal
   readonly limit?: number
@@ -58,21 +56,23 @@ export interface ListAgentThreadsResult {
 export type AgentExecutionStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled"
 
 export type AgentRunStatus = AgentExecutionStatus
+export type AgentRunKind = "conversation" | "subagent"
 
 /** Error codes an agent execution can persist and expose through its public contract. */
 export const AGENT_RUN_FAILURE_CODES = [
   "internal.unexpected",
   "runtime.cancelled",
   "agent.execution_failed",
+  "ai.usage_limit_exceeded",
+  "ai.usage_limit_unavailable",
 ] as const satisfies readonly [SixbErrorCode, ...SixbErrorCode[]]
 
 export type AgentRunFailureCode = (typeof AGENT_RUN_FAILURE_CODES)[number]
 
 /**
- * Why a run ended — our own SDK-independent vocabulary. It includes the AI SDK's unified finish
- * reasons plus platform-level endings such as `timeout`, so reads are typed and exhaustive without
- * core depending on `ai`. `other`/`unknown` are catch-alls: an unrecognised provider value still
- * records *that* the run ended.
+ * Why a run ended — Sixb's provider-independent vocabulary. It includes model-loop reasons plus
+ * platform-level endings such as `timeout`, so reads remain typed and exhaustive. `other` and
+ * `unknown` preserve terminal state when a provider adds a new reason.
  */
 export const AGENT_RUN_FINISH_REASONS = [
   "stop",
@@ -144,13 +144,10 @@ export interface AgentRunExecution {
   readonly queueLeaseExpiresAt: Date
 }
 
-export interface AgentRunRecord {
+interface AgentRunRecordBase {
   readonly id: string
   readonly projectId: string
   readonly executionId: string
-  readonly threadId: string
-  readonly agentId: string
-  readonly triggerMessageId: string
   /** Durable group memberships snapshotted when the run was admitted. */
   readonly requesterGroupIds: readonly string[]
   readonly status: AgentRunStatus
@@ -169,17 +166,73 @@ export interface AgentRunRecord {
   readonly completedAt?: Date
 }
 
+export interface ConversationAgentRunRecord extends AgentRunRecordBase {
+  readonly kind: "conversation"
+  readonly threadId: string
+  readonly triggerMessageId: string
+  /** Immutable model selection captured at admission. Absent only on runs predating this field. */
+  readonly spec?: ConversationAgentRunSpec
+}
+
+/** Immutable, serialisable model selection for one conversational turn. */
+export interface ConversationAgentRunSpec {
+  readonly model: LanguageModelRef
+  readonly reasoning?: AgentReasoningLevel
+}
+
+/** Immutable, serialisable child configuration captured before dispatch. */
+export interface SubagentRunSpec {
+  readonly model: LanguageModelRef
+  readonly reasoning?: AgentReasoningLevel
+  /** Focused task supplied by the parent Agent. */
+  readonly task: string
+  /** Project tools available when the child was admitted. Runtime tools are injected separately. */
+  readonly toolNames: readonly string[]
+  readonly maxSteps: number
+}
+
+/** Durable child output returned to its parent by `wait_agent`. */
+export interface SubagentRunResult {
+  readonly text?: string
+  readonly files?: readonly FileRef[]
+}
+
+export interface SubagentRunRecord extends AgentRunRecordBase {
+  readonly kind: "subagent"
+  readonly parentRunId: string
+  /** Stable parent-selected key that makes repeated tool execution idempotent. */
+  readonly spawnKey: string
+  readonly spec: SubagentRunSpec
+  readonly result?: SubagentRunResult
+}
+
+export type AgentRunRecord = ConversationAgentRunRecord | SubagentRunRecord
+
 export interface CreateAgentRunInput {
   readonly id: string
   readonly projectId: string
   readonly executionId: string
   readonly threadId: string
-  readonly agentId: string
   readonly triggerMessageId: string
+  readonly spec: ConversationAgentRunSpec
   readonly requesterGroupIds: readonly string[]
   readonly createdAt?: Date
 }
 
+export interface CreateSubagentRunInput {
+  readonly id: string
+  readonly projectId: string
+  readonly executionId: string
+  readonly parentRunId: string
+  /** Current parent delivery token. New children are admitted only while that delivery owns it. */
+  readonly parentExecutionToken: string
+  readonly spawnKey: string
+  readonly spec: SubagentRunSpec
+  /** Internal safety bound enforced atomically across worker processes. */
+  readonly maxActiveChildren: number
+  readonly createdAt?: Date
+}
+
 export interface StartAgentRunInput {
   readonly id: string
   readonly projectId: string
@@ -219,6 +272,7 @@ export type FinishAgentRunInput =
       readonly modelId?: string
       readonly finishReason?: AgentRunFinishReason
       readonly diagnostics?: readonly AgentRunDiagnostic[]
+      readonly result?: SubagentRunResult
       readonly completedAt?: Date
     }
   | {
@@ -235,8 +289,9 @@ export type FinishAgentRunInput =
 
 export interface ListAgentRunsInput {
   readonly projectId: string
+  readonly kinds?: readonly AgentRunKind[]
   readonly threadId?: string
-  readonly agentId?: string
+  readonly parentRunId?: string
   readonly statuses?: readonly AgentRunStatus[]
   /** Effective start time; runs that never started use `createdAt`. */
   readonly startedAfter?: Date
@@ -371,7 +426,9 @@ export interface AgentThreadStore {
 
 export interface AgentRunStore {
   /** Persist a queued run and atomically claim the thread's single-flight slot. */
-  create(input: CreateAgentRunInput): Promise<AgentRunRecord>
+  create(input: CreateAgentRunInput): Promise<ConversationAgentRunRecord>
+  /** Persist or replay one idempotent child run while atomically enforcing parent fan-out. */
+  createSubagent(input: CreateSubagentRunInput): Promise<SubagentRunRecord>
   /** Transition a queued run to running and install the first delivery's execution token. */
   start(input: StartAgentRunInput): Promise<AgentRunRecord>
   /** Finish a queued run before execution and release the thread's single-flight slot. */

package/src/storage/ai-cost/analytics.ts

@@ -59,7 +59,8 @@ export interface AiAccountingAggregateFragment {
   readonly start?: Date
   readonly providerId?: string
   readonly modelId?: string
-  readonly agentId?: string
+  readonly agentKind?: "agent" | "workflowAgent"
+  readonly agentStepId?: string
   readonly workflowId?: string
   readonly modelCallCount: string
   readonly usage: {
@@ -154,7 +155,19 @@ export function buildAiAccountingOverview(
       JSON.stringify([item.usage.providerId, item.usage.requestedModelId]),
       item
     )
-    if (item.attribution) appendGrouped(agentItems, item.attribution.agentId, item)
+    if (item.attribution?.kind === "agent") {
+      appendGrouped(agentItems, JSON.stringify(["agent"]), item)
+    } else if (item.attribution?.kind === "workflowAgent") {
+      appendGrouped(
+        agentItems,
+        JSON.stringify([
+          "workflowAgent",
+          item.attribution.workflowId,
+          item.attribution.agentStepId,
+        ]),
+        item
+      )
+    }
     if (item.attribution?.kind === "workflowAgent") {
       appendGrouped(workflowItems, item.attribution.workflowId, item)
     }
@@ -171,7 +184,21 @@ export function buildAiAccountingOverview(
     })
     .sort(compareModelBreakdowns)
   const agents: AiAccountingAgentBreakdown[] = [...agentItems]
-    .map(([agentId, grouped]) => ({ agentId, ...aggregateAccountingItems(grouped) }))
+    .map(([key, grouped]) => {
+      const [kind, workflowId, agentStepId] = JSON.parse(key) as [
+        "agent" | "workflowAgent",
+        string?,
+        string?,
+      ]
+      return kind === "agent"
+        ? { kind, ...aggregateAccountingItems(grouped) }
+        : {
+            kind,
+            workflowId: requiredFragmentString(workflowId, "workflowId"),
+            agentStepId: requiredFragmentString(agentStepId, "agentStepId"),
+            ...aggregateAccountingItems(grouped),
+          }
+    })
     .sort(compareAgentBreakdowns)
   const workflows: AiAccountingWorkflowBreakdown[] = [...workflowItems]
     .map(([workflowId, grouped]) => ({ workflowId, ...aggregateAccountingItems(grouped) }))
@@ -227,7 +254,14 @@ export function buildAiAccountingOverviewFromFragments(
         )
         break
       case "agent":
-        target = getFragmentAccumulator(agents, requiredFragmentString(fragment.agentId, "agentId"))
+        target = getFragmentAccumulator(
+          agents,
+          JSON.stringify([
+            requiredFragmentString(fragment.agentKind, "agentKind"),
+            fragment.workflowId,
+            fragment.agentStepId,
+          ])
+        )
         break
       case "workflow":
         target = getFragmentAccumulator(
@@ -254,7 +288,21 @@ export function buildAiAccountingOverviewFromFragments(
       })
       .sort(compareModelBreakdowns),
     agents: [...agents]
-      .map(([agentId, value]) => ({ agentId, ...finishAggregateFragment(value) }))
+      .map(([key, value]) => {
+        const [kind, workflowId, agentStepId] = JSON.parse(key) as [
+          "agent" | "workflowAgent",
+          string?,
+          string?,
+        ]
+        return kind === "agent"
+          ? { kind, ...finishAggregateFragment(value) }
+          : {
+              kind,
+              workflowId: requiredFragmentString(workflowId, "workflowId"),
+              agentStepId: requiredFragmentString(agentStepId, "agentStepId"),
+              ...finishAggregateFragment(value),
+            }
+      })
       .sort(compareAgentBreakdowns),
     workflows: [...workflows]
       .map(([workflowId, value]) => ({ workflowId, ...finishAggregateFragment(value) }))
@@ -560,7 +608,16 @@ function compareAgentBreakdowns(
   left: AiAccountingAgentBreakdown,
   right: AiAccountingAgentBreakdown
 ): number {
-  return right.modelCallCount - left.modelCallCount || left.agentId.localeCompare(right.agentId)
+  return (
+    right.modelCallCount - left.modelCallCount ||
+    agentBreakdownKey(left).localeCompare(agentBreakdownKey(right))
+  )
+}
+
+function agentBreakdownKey(value: AiAccountingAgentBreakdown): string {
+  return value.kind === "agent"
+    ? "agent"
+    : JSON.stringify(["workflowAgent", value.workflowId, value.agentStepId])
 }
 
 function compareWorkflowBreakdowns(

package/src/storage/ai-cost/codec.ts

@@ -1,9 +1,16 @@
-import type { AiBillableMeter, AiModelCallCostRecord, AiPricingContext } from "./types"
-import { normalizeAiPricingContext } from "./validation"
+import type {
+  AiBillableMeter,
+  AiCostEstimate,
+  AiModelCallCostRecord,
+  AiPriceSource,
+  AiPricingContext,
+} from "./types"
+import { normalizeAiCostEstimate, normalizeAiPricingContext } from "./validation"
 
 export interface AiModelCallCostDetails {
+  readonly estimate?: AiCostEstimate
   readonly pricingContext: AiPricingContext
-  readonly priceSource: Omit<AiModelCallCostRecord["priceSource"], "observedAt"> & {
+  readonly priceSource?: Omit<AiPriceSource, "observedAt"> & {
     readonly observedAt: string
   }
   readonly components?: Extract<AiModelCallCostRecord, { status: "rated" }>["components"]
@@ -12,8 +19,16 @@ export interface AiModelCallCostDetails {
 
 export function aiModelCallCostDetails(record: AiModelCallCostRecord): AiModelCallCostDetails {
   return {
+    ...(record.estimate === undefined ? {} : { estimate: record.estimate }),
     pricingContext: record.pricingContext,
-    priceSource: { ...record.priceSource, observedAt: record.priceSource.observedAt.toISOString() },
+    ...(record.priceSource === undefined
+      ? {}
+      : {
+          priceSource: {
+            ...record.priceSource,
+            observedAt: record.priceSource.observedAt.toISOString(),
+          },
+        }),
     ...(record.status === "rated" ? { components: record.components } : {}),
     ...(record.status === "unpriceable" && record.missingMeters
       ? { missingMeters: record.missingMeters }
@@ -25,18 +40,25 @@ export function parseAiModelCallCostDetails(value: unknown): AiModelCallCostDeta
   const parsed: unknown = typeof value === "string" ? JSON.parse(value) : value
   if (!isRecord(parsed)) throw invalidDetails()
   const priceSource = parsed.priceSource
-  if (!isRecord(priceSource)) throw invalidDetails()
+  if (priceSource !== undefined && !isRecord(priceSource)) throw invalidDetails()
   const components = parsed.components
   const missingMeters = parsed.missingMeters
   return {
+    ...(parsed.estimate === undefined
+      ? {}
+      : { estimate: normalizeAiCostEstimate(parsed.estimate) }),
     pricingContext: pricingContextFromUnknown(parsed.pricingContext),
-    priceSource: {
-      sourceId: requiredString(priceSource.sourceId),
-      sourceEntryId: requiredString(priceSource.sourceEntryId),
-      sourceVersion: requiredString(priceSource.sourceVersion),
-      sourceUrl: requiredString(priceSource.sourceUrl),
-      observedAt: requiredString(priceSource.observedAt),
-    },
+    ...(priceSource === undefined
+      ? {}
+      : {
+          priceSource: {
+            sourceId: requiredString(priceSource.sourceId),
+            sourceEntryId: requiredString(priceSource.sourceEntryId),
+            sourceVersion: requiredString(priceSource.sourceVersion),
+            ...optionalStringProperty(priceSource, "sourceUrl"),
+            observedAt: requiredString(priceSource.observedAt),
+          },
+        }),
     ...(components === undefined ? {} : { components: costComponentsFromUnknown(components) }),
     ...(missingMeters === undefined ? {} : { missingMeters: metersFromUnknown(missingMeters) }),
   }
@@ -50,6 +72,7 @@ function pricingContextFromUnknown(value: unknown): AiPricingContext {
     ...optionalStringProperty(value, "region"),
     ...optionalStringProperty(value, "inferenceGeo"),
     ...optionalStringProperty(value, "routedProviderId"),
+    ...optionalStringProperty(value, "routedModelId"),
     ...optionalStringProperty(value, "deploymentId"),
     ...optionalStringProperty(value, "inferenceProfileId"),
     ...optionalNumberProperty(value, "cacheWriteTtlSeconds"),
@@ -83,6 +106,8 @@ function billableMeter(value: unknown): AiBillableMeter {
     value !== "tokens.input.uncached" &&
     value !== "tokens.input.cacheRead" &&
     value !== "tokens.input.cacheWrite" &&
+    value !== "tokens.input.cacheWrite5m" &&
+    value !== "tokens.input.cacheWrite1h" &&
     value !== "tokens.output.total" &&
     value !== "tokens.output.text" &&
     value !== "tokens.output.reasoning"