@sixb/core 0.1.6 → 0.1.8

package/src/agents/reference.ts

@@ -0,0 +1,7 @@
+import type { AgentReference } from "./types"
+
+/** Project Agent capability used in security grants such as `can.run(agent)`. */
+export const agent: AgentReference = Object.freeze({
+  kind: "agent",
+  usage: Object.freeze({ kind: "aiUsage" }),
+})

package/src/agents/request.ts

@@ -4,30 +4,41 @@ import { SYSTEM_PRINCIPAL } from "../auth"
 import { snapshotRequesterGroupIds } from "../auth/attribution"
 import { assertAuthorized } from "../authorization"
 import type { FileRef } from "../blob-storage"
-import { createAgentExecutionRecord } from "../execution/agent"
+import {
+  canInheritAgentRequestAuthorization,
+  createInheritedAgentExecutionRecord,
+} from "../execution/agent"
+import { resolveExecutionScopeAuthorization } from "../execution/authorization"
 import { ensureExecutionRecord, executionRecordInputFromRuntime } from "../execution/durable"
 import type { ExecutionContext } from "../execution/types"
+import type { LanguageModelCatalog, LanguageModelRef } from "../models"
+import { isModelReasoning } from "../models/language-model"
 import type { SixbRuntimeContext } from "../runtime/types"
-import type { SecurityDefinitionCatalog } from "../security"
 import {
-  type AgentRunRecord,
   type AgentStorage,
   AgentStorageError,
   type AgentThreadRecord,
+  type ConversationAgentRunRecord,
+  type ConversationAgentRunSpec,
 } from "../storage/agents"
+import {
+  aiLimitSubjectsFromAttribution,
+  aiUsageLimitExceededError,
+  aiUsageLimitUnavailableError,
+  applicableAiLimitPolicyStatuses,
+} from "../storage/ai-limits/enforcement"
+import type { AiLimitPolicyStatus } from "../storage/ai-limits/types"
 import type { CreateExecutionInput } from "../storage/executions"
-import { ensureAgentExecutionIdentity, resolveAgentExecutionAuthorization } from "./authority"
 import type { AgentContextEntryInput } from "./context"
 import { resolveAgentContextParts } from "./context-resolution"
 import { dispatchQueuedAgentRuns } from "./dispatch"
 import { AgentRequestError } from "./errors"
 import { createAgentMessageId, createAgentRunId, createAgentThreadId } from "./ids"
+import { assertNoAgentSelector } from "./retired-config"
 import { publishAgentRunActivity } from "./streams"
-import type { AgentDefinition } from "./types"
+import { AGENT_REASONING_LEVELS, type AgentReasoningLevel } from "./types"
 
 export interface RequestAgentRunInput {
-  /** The agent to run. */
-  readonly agentId: string
   /** The user's message that triggers the turn. */
   readonly text: string
   /** Blob-backed files attached to the trigger message. */
@@ -36,6 +47,10 @@ export interface RequestAgentRunInput {
   readonly context?: readonly AgentContextEntryInput[]
   /** Continue an existing thread. Omitted → a fresh thread is created for this agent. */
   readonly threadId?: string
+  /** Configured language model selected for this turn. Omitted uses the agent default. */
+  readonly model?: LanguageModelRef
+  /** Provider-neutral reasoning effort selected for this turn. */
+  readonly reasoning?: AgentReasoningLevel
   /** Title to stamp on the thread when one is created. */
   readonly title?: string
   /** Explicit id for the trigger (user) message. Defaults to a generated id. */
@@ -46,7 +61,7 @@ export interface RequestAgentRunInput {
 
 export interface RequestAgentRunResult {
   /** The durable queued run exactly as it was created (`status: "queued"`, attempt 0). */
-  readonly run: AgentRunRecord
+  readonly run: ConversationAgentRunRecord
   /** The enqueued job id, when the queue returns one. */
   readonly jobId?: string
   /** Whether this call created the thread. */
@@ -64,11 +79,17 @@ export interface RequestAgentRunResult {
 export async function requestAgentRun(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext,
-  security: SecurityDefinitionCatalog,
-  agent: AgentDefinition,
+  models: LanguageModelCatalog | undefined,
   input: RequestAgentRunInput
 ): Promise<RequestAgentRunResult> {
-  assertAuthorized(runtime, { kind: "agent.run", agentId: agent.id })
+  const authority = resolveExecutionScopeAuthorization(runtime.projectId, {
+    execution,
+    authorization: runtime.runtimeAuthorization,
+  })
+  assertNoAgentSelector(input)
+  assertAuthorized(runtime, { kind: "agent.run" })
+  assertRequestAuthorityCanRunAgent(runtime)
+  const spec = resolveConversationRunSpec({ models, input })
 
   // Resolve context before creating a thread: invalid or inaccessible references must not leave an
   // empty conversation behind. The resulting parts are the exact snapshot persisted below.
@@ -76,12 +97,26 @@ export async function requestAgentRun(
 
   const agents = requireAgentStorage(runtime)
   const projectId = runtime.projectId
-  // A scoped runtime is authoritative for caller identity. `input.principal` remains available to
-  // privileged server integrations that have already authenticated their request.
-  const principal = runtime.authorization?.principal ?? input.principal ?? SYSTEM_PRINCIPAL
+  // Attribution comes from the exact capability/execution pair, never the optional context cache
+  // on the runtime. `input.principal` remains available to unrestricted server integrations that
+  // have already authenticated their request.
+  const principal =
+    authority.type === "principal"
+      ? authority.context.principal
+      : (input.principal ?? SYSTEM_PRINCIPAL)
+  const runId = createAgentRunId()
+  const durableExecution = await prepareDurableAgentExecution(runtime, execution, runId)
+  const requesterGroupIds = durableExecution.requestedBy
+    ? await snapshotRequesterGroupIds({
+        auth: runtime.storage.auth,
+        projectId,
+        principal: durableExecution.requestedBy,
+      })
+    : []
+  await assertAiLimitPreflight(runtime, durableExecution, requesterGroupIds)
+
   const { thread, createdThread } = await resolveThread(agents, {
     projectId,
-    agentId: agent.id,
     threadId: input.threadId,
     title: input.title,
     principal,
@@ -94,24 +129,8 @@ export async function requestAgentRun(
       `[Sixb] Agent thread '${thread.id}' already has an active run '${thread.activeRunId}'.`
     )
   }
-
-  const runId = createAgentRunId()
-  const durableExecution = await prepareDurableAgentExecution(
-    runtime,
-    execution,
-    security,
-    agent,
-    runId
-  )
-  const requesterGroupIds = durableExecution.requestedBy
-    ? await snapshotRequesterGroupIds({
-        auth: runtime.storage.auth,
-        projectId,
-        principal: durableExecution.requestedBy,
-      })
-    : []
   const triggerMessageId = input.messageId ?? createAgentMessageId()
-  let run: AgentRunRecord
+  let run: ConversationAgentRunRecord
   try {
     run = await runtime.storage.transaction(async (tx) => {
       const agents = tx.agents
@@ -140,8 +159,8 @@ export async function requestAgentRun(
         projectId,
         executionId: durableExecution.id,
         threadId: thread.id,
-        agentId: agent.id,
         triggerMessageId,
+        spec,
         requesterGroupIds,
       })
     })
@@ -166,17 +185,15 @@ export async function requestAgentRun(
 export async function retryAgentRun(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext,
-  security: SecurityDefinitionCatalog,
-  agent: AgentDefinition,
-  failedRun: AgentRunRecord
+  models: LanguageModelCatalog | undefined,
+  failedRun: ConversationAgentRunRecord
 ): Promise<RequestAgentRunResult> {
-  assertAuthorized(runtime, { kind: "agent.run", agentId: agent.id })
-  if (failedRun.agentId !== agent.id) {
-    throw new AgentRequestError(
-      "agent_not_found",
-      `[Sixb] Agent run '${failedRun.id}' does not belong to agent '${agent.id}'.`
-    )
-  }
+  resolveExecutionScopeAuthorization(runtime.projectId, {
+    execution,
+    authorization: runtime.runtimeAuthorization,
+  })
+  assertAuthorized(runtime, { kind: "agent.run" })
+  assertRequestAuthorityCanRunAgent(runtime)
   if (failedRun.status !== "failed") {
     throw new AgentRequestError(
       "run_not_retryable",
@@ -185,14 +202,18 @@ export async function retryAgentRun(
   }
 
   const agents = requireAgentStorage(runtime)
+  const thread = await agents.threads.getById({
+    projectId: runtime.projectId,
+    id: failedRun.threadId,
+  })
+  if (!thread) {
+    throw new AgentRequestError(
+      "thread_not_found",
+      `[Sixb] Agent thread '${failedRun.threadId}' was not found.`
+    )
+  }
   const runId = createAgentRunId()
-  const durableExecution = await prepareDurableAgentExecution(
-    runtime,
-    execution,
-    security,
-    agent,
-    runId
-  )
+  const durableExecution = await prepareDurableAgentExecution(runtime, execution, runId)
   const requesterGroupIds = durableExecution.requestedBy
     ? await snapshotRequesterGroupIds({
         auth: runtime.storage.auth,
@@ -200,6 +221,7 @@ export async function retryAgentRun(
         principal: durableExecution.requestedBy,
       })
     : []
+  await assertAiLimitPreflight(runtime, durableExecution, requesterGroupIds)
   const run = await runtime.storage.transaction(async (tx) => {
     const agents = tx.agents
     if (!agents) {
@@ -216,8 +238,13 @@ export async function retryAgentRun(
       projectId: runtime.projectId,
       executionId: durableExecution.id,
       threadId: failedRun.threadId,
-      agentId: agent.id,
       triggerMessageId: failedRun.triggerMessageId,
+      spec:
+        failedRun.spec ??
+        resolveConversationRunSpec({
+          models,
+          input: {},
+        }),
       requesterGroupIds,
     })
   })
@@ -226,25 +253,76 @@ export async function retryAgentRun(
   return { run, ...(jobId ? { jobId } : {}), createdThread: false }
 }
 
+async function assertAiLimitPreflight(
+  runtime: SixbRuntimeContext,
+  execution: CreateExecutionInput,
+  requesterGroupIds: readonly string[]
+): Promise<void> {
+  const limits = runtime.storage.aiLimits
+  if (!limits) throw aiUsageLimitUnavailableError(["limitStorageUnavailable"])
+
+  const subjects = aiLimitSubjectsFromAttribution(execution.requestedBy, requesterGroupIds)
+  let applicable: readonly AiLimitPolicyStatus[]
+  try {
+    applicable = applicableAiLimitPolicyStatuses(
+      await limits.listPolicyStatuses({ projectId: runtime.projectId }),
+      subjects
+    )
+  } catch {
+    throw aiUsageLimitUnavailableError(["limitStorageUnavailable"])
+  }
+
+  const unavailable = applicable.filter((status) => status.accountingStatus === "unavailable")
+  if (unavailable.length > 0) {
+    throw aiUsageLimitUnavailableError(["incompleteAccounting"])
+  }
+  const exhausted = applicable.filter((status) => status.exhausted)
+  if (exhausted.length > 0) {
+    const resetAt = new Date(
+      Math.min(...exhausted.map((status) => status.period.resetAt.getTime()))
+    )
+    throw aiUsageLimitExceededError(resetAt)
+  }
+}
+
+function resolveConversationRunSpec(input: {
+  readonly models?: LanguageModelCatalog
+  readonly input: Pick<RequestAgentRunInput, "model" | "reasoning">
+}): ConversationAgentRunSpec {
+  if (!input.models) {
+    throw new AgentRequestError(
+      "model_not_found",
+      "[Sixb] Configure models.language before starting the Agent."
+    )
+  }
+  const selected = input.input.model ?? input.models.default
+  const model = input.models.getByRef(selected)
+  if (model === null) {
+    throw new AgentRequestError(
+      "model_not_found",
+      `[Sixb] Language model '${selected.provider}/${selected.modelId}' is not in the project model catalog.`
+    )
+  }
+
+  const reasoning = input.input.reasoning
+  if (reasoning !== undefined && !isModelReasoning(reasoning)) {
+    throw new AgentRequestError(
+      "invalid_model_selection",
+      `[Sixb] Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
+    )
+  }
+
+  return Object.freeze({
+    model: Object.freeze({ provider: selected.provider, modelId: selected.modelId }),
+    ...(reasoning === undefined ? {} : { reasoning }),
+  })
+}
+
 async function prepareDurableAgentExecution(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext,
-  security: SecurityDefinitionCatalog,
-  agent: AgentDefinition,
   runId: string
 ): Promise<CreateExecutionInput> {
-  const identity = await ensureAgentExecutionIdentity({
-    auth: runtime.storage.auth,
-    projectId: runtime.projectId,
-    agent,
-  })
-  const resolved = await resolveAgentExecutionAuthorization({
-    auth: runtime.storage.auth,
-    projectId: runtime.projectId,
-    agentId: agent.id,
-    authorizationRef: { type: "principal", principal: identity.principal },
-    security,
-  })
   const parent = await ensureExecutionRecord(
     runtime.storage.executions,
     executionRecordInputFromRuntime({
@@ -252,15 +330,22 @@ async function prepareDurableAgentExecution(
       runtimeAuthorization: runtime.runtimeAuthorization,
     })
   )
-  return createAgentExecutionRecord({
+  return createInheritedAgentExecutionRecord({
     id: `exec_${randomUUID()}`,
     parent,
-    agentId: agent.id,
     runId,
-    principal: resolved.identity.principal,
   })
 }
 
+function assertRequestAuthorityCanRunAgent(runtime: SixbRuntimeContext): void {
+  if (!canInheritAgentRequestAuthorization(runtime.runtimeAuthorization)) {
+    throw new AgentRequestError(
+      "authority_not_inheritable",
+      "[Sixb] The Agent requires an authenticated user request or disabled authorization."
+    )
+  }
+}
+
 async function dispatchAgentRun(
   runtime: SixbRuntimeContext,
   agents: AgentStorage,
@@ -290,7 +375,10 @@ async function dispatchAgentRun(
 }
 
 /** Activity delivery is observational: durable run admission remains successful if the feed is down. */
-async function publishRunActivity(runtime: SixbRuntimeContext, run: AgentRunRecord): Promise<void> {
+async function publishRunActivity(
+  runtime: SixbRuntimeContext,
+  run: ConversationAgentRunRecord
+): Promise<void> {
   try {
     await publishAgentRunActivity(runtime.broker, run)
   } catch (error) {
@@ -302,7 +390,6 @@ async function resolveThread(
   agents: AgentStorage,
   params: {
     readonly projectId: string
-    readonly agentId: string
     readonly threadId?: string
     readonly title?: string
     readonly principal: Principal
@@ -314,12 +401,6 @@ async function resolveThread(
       id: params.threadId,
     })
     if (existing) {
-      if (existing.agentId !== params.agentId) {
-        throw new AgentRequestError(
-          "thread_agent_mismatch",
-          `[Sixb] Agent thread '${existing.id}' belongs to agent '${existing.agentId}', not '${params.agentId}'.`
-        )
-      }
       return { thread: existing, createdThread: false }
     }
   }
@@ -327,7 +408,6 @@ async function resolveThread(
   const thread = await agents.threads.create({
     id: params.threadId ?? createAgentThreadId(),
     projectId: params.projectId,
-    agentId: params.agentId,
     ownerPrincipal: params.principal,
     ...(params.title === undefined ? {} : { title: params.title }),
   })

package/src/agents/retired-config.ts

@@ -0,0 +1,20 @@
+import { RuntimeError } from "../runtime/errors"
+import { AgentRequestError } from "./errors"
+
+/** Reject JavaScript callers too: old configuration must not silently change authority. */
+export function assertNoAgentDefinitions(input: object): void {
+  if ("agents" in input) {
+    throw new RuntimeError(
+      "[Sixb] Agent definitions are no longer supported. Configure 'models' and 'tools' on createSixb() instead."
+    )
+  }
+}
+
+export function assertNoAgentSelector(input: object): void {
+  if ("agentId" in input || "agentIds" in input) {
+    throw new AgentRequestError(
+      "agent_selector_removed",
+      "[Sixb] There is one project Agent. Remove the agentId selector and use sixb.agent."
+    )
+  }
+}

package/src/agents/streams.ts

@@ -7,6 +7,7 @@ import {
   type AgentContextCheckpointReason,
   type AgentRunFailureCode,
   type AgentRunRecord,
+  type ConversationAgentRunRecord,
 } from "../storage/agents/types"
 
 export const AGENT_RUN_STREAM_SCHEMA_VERSION = 1 as const
@@ -28,7 +29,6 @@ export interface AgentRunActivityEvent {
   readonly projectId: string
   readonly runId: string
   readonly threadId: string
-  readonly agentId: string
   readonly status: AgentRunRecord["status"]
   readonly attempt: number
   readonly occurredAt: string
@@ -42,7 +42,7 @@ export function agentActivityStreamDefinition(): BrokerStreamDefinition {
 }
 
 export function agentRunActivityEvent(
-  run: AgentRunRecord,
+  run: ConversationAgentRunRecord,
   occurredAt: Date = new Date()
 ): AgentRunActivityEvent {
   return {
@@ -51,7 +51,6 @@ export function agentRunActivityEvent(
     projectId: run.projectId,
     runId: run.id,
     threadId: run.threadId,
-    agentId: run.agentId,
     status: run.status,
     attempt: run.attempt,
     occurredAt: occurredAt.toISOString(),
@@ -66,7 +65,6 @@ export function isAgentRunActivityEvent(value: unknown): value is AgentRunActivi
     typeof value.projectId === "string" &&
     typeof value.runId === "string" &&
     typeof value.threadId === "string" &&
-    typeof value.agentId === "string" &&
     isAgentRunStatus(value.status) &&
     typeof value.attempt === "number" &&
     Number.isFinite(value.attempt) &&
@@ -74,7 +72,10 @@ export function isAgentRunActivityEvent(value: unknown): value is AgentRunActivi
   )
 }
 
-export async function publishAgentRunActivity(broker: Broker, run: AgentRunRecord): Promise<void> {
+export async function publishAgentRunActivity(
+  broker: Broker,
+  run: ConversationAgentRunRecord
+): Promise<void> {
   const event = agentRunActivityEvent(run)
   await broker.ensureStream({
     projectId: run.projectId,
@@ -108,15 +109,22 @@ export function agentRunStreamDefinition(runId: string): BrokerStreamDefinition
   }
 }
 
-interface AgentRunStreamEventBase {
+type AgentRunStreamEventBase = {
   readonly schemaVersion: typeof AGENT_RUN_STREAM_SCHEMA_VERSION
   readonly projectId: string
   readonly runId: string
-  readonly threadId: string
-  readonly agentId: string
   readonly attempt: number
   readonly occurredAt: string
-}
+} & (
+  | {
+      readonly threadId: string
+      readonly parentRunId?: never
+    }
+  | {
+      readonly parentRunId: string
+      readonly threadId?: never
+    }
+)
 
 // ── Control stream (worker-inbound) ─────────────────────────────────────────────────────────────
 //
@@ -157,7 +165,12 @@ export async function publishAgentRunCancel(
     projectId: params.projectId,
     streamId: agentRunControlStreamId(params.runId),
     records: [
-      { name: AGENT_RUN_CANCEL_RECORD, key: params.runId, payload: { runId: params.runId } },
+      {
+        name: AGENT_RUN_CANCEL_RECORD,
+        key: params.runId,
+        payload: { runId: params.runId },
+        idempotencyKey: `${params.runId}:cancel`,
+      },
     ],
   })
 }
@@ -254,18 +267,29 @@ export function agentRunFinishedEvent(
     )
   }
   return {
-    schemaVersion: AGENT_RUN_STREAM_SCHEMA_VERSION,
+    ...agentRunStreamEventBase(run, occurredAt),
     type: "agent.run.finished",
-    projectId: run.projectId,
-    runId: run.id,
-    threadId: run.threadId,
-    agentId: run.agentId,
-    attempt: run.attempt,
     status: run.status,
     ...(run.finishReason === undefined ? {} : { finishReason: run.finishReason }),
     ...(run.error === undefined ? {} : { error: run.error }),
+  }
+}
+
+/** Shared lineage for stream records emitted by conversational and headless runs. */
+export function agentRunStreamEventBase(
+  run: AgentRunRecord,
+  occurredAt: Date = new Date()
+): AgentRunStreamEventBase {
+  const common = {
+    schemaVersion: AGENT_RUN_STREAM_SCHEMA_VERSION,
+    projectId: run.projectId,
+    runId: run.id,
+    attempt: run.attempt,
     occurredAt: occurredAt.toISOString(),
   }
+  return run.kind === "conversation"
+    ? { ...common, threadId: run.threadId }
+    : { ...common, parentRunId: run.parentRunId }
 }
 
 /** Validate an Agent stream payload using the same contract its producers use. */
@@ -275,8 +299,6 @@ export function isAgentRunStreamEvent(value: unknown): value is AgentRunStreamEv
     value.schemaVersion !== AGENT_RUN_STREAM_SCHEMA_VERSION ||
     typeof value.projectId !== "string" ||
     typeof value.runId !== "string" ||
-    typeof value.threadId !== "string" ||
-    typeof value.agentId !== "string" ||
     typeof value.attempt !== "number" ||
     !Number.isFinite(value.attempt) ||
     typeof value.occurredAt !== "string" ||
@@ -284,6 +306,10 @@ export function isAgentRunStreamEvent(value: unknown): value is AgentRunStreamEv
   ) {
     return false
   }
+  const hasConversationLineage =
+    typeof value.threadId === "string" && value.parentRunId === undefined
+  const hasSubagentLineage = typeof value.parentRunId === "string" && value.threadId === undefined
+  if (!hasConversationLineage && !hasSubagentLineage) return false
 
   switch (value.type) {
     case "agent.run.started":
@@ -393,5 +419,5 @@ export async function publishAgentRunFinished(broker: Broker, run: AgentRunRecor
       },
     ],
   })
-  await publishAgentRunActivity(broker, run)
+  if (run.kind === "conversation") await publishAgentRunActivity(broker, run)
 }

package/src/agents/tool-catalog.ts

@@ -0,0 +1,21 @@
+import { toolsFromProjectConfig } from "./tool-definition"
+import type { AgentToolDefinition } from "./types"
+
+/** Immutable catalog of project tools registered with a Sixb host. */
+export interface AgentToolCatalog {
+  list(): readonly AgentToolDefinition[]
+  getByName(name: string): AgentToolDefinition | null
+}
+
+/** Validate, normalize, and index the tools supplied through `createSixb({ tools })`. */
+export function createAgentToolCatalog(
+  definitions: readonly AgentToolDefinition[] | undefined
+): AgentToolCatalog {
+  const tools = toolsFromProjectConfig(definitions)
+  const toolsByName = new Map(tools.map((tool) => [tool.name, tool]))
+
+  return Object.freeze({
+    list: () => tools,
+    getByName: (name: string) => toolsByName.get(name) ?? null,
+  })
+}

package/src/agents/tool-definition.ts

@@ -13,9 +13,9 @@ import type {
   InferAgentToolInputSchema,
 } from "./types"
 import {
-  assertValidAgentToolDefinitions,
   assertValidAgentToolDescription,
   assertValidAgentToolName,
+  assertValidProjectAgentToolDefinitions,
   validateAndSnapshotAgentToolInput,
 } from "./validation"
 
@@ -72,8 +72,7 @@ export function createAgentToolDefinition<
   return Object.freeze(tool)
 }
 
-export function toolsFromDefinitions(
-  agentId: string,
+export function toolsFromProjectConfig(
   tools: readonly AgentToolDefinition[] | undefined
 ): readonly AgentToolDefinition[] {
   if (tools === undefined) {
@@ -81,12 +80,17 @@ export function toolsFromDefinitions(
   }
   if (!Array.isArray(tools)) {
     throw new AgentDefinitionError(
-      `[Sixb] Agent '${agentId}' tools must be an array of agent tool definitions.`
+      "[Sixb] Project tools must be an array of agent tool definitions."
     )
   }
 
-  assertValidAgentToolDefinitions(agentId, tools)
+  assertValidProjectAgentToolDefinitions(tools)
+  return normalizeAgentToolDefinitions(tools)
+}
 
+function normalizeAgentToolDefinitions(
+  tools: readonly AgentToolDefinition[]
+): readonly AgentToolDefinition[] {
   const normalized: AgentToolDefinition[] = []
   for (const tool of tools) {
     normalized.push(normalizeAgentToolDefinition(tool))