@sixb/core 0.1.5 → 0.1.7

package/src/models/rate-card.ts

@@ -0,0 +1,101 @@
+/** Decimal USD per million tokens. Strings keep provider prices exact. */
+export type ModelUnitPrice = string
+
+export interface ModelPricingTier {
+  readonly minTokens: number
+  readonly maxTokens?: number
+  readonly price: ModelUnitPrice
+}
+
+export type ModelTokenPrice =
+  | ModelUnitPrice
+  | { readonly default: ModelUnitPrice; readonly tiers: readonly ModelPricingTier[] }
+
+export interface LanguageModelRateCard {
+  readonly currency: "USD"
+  readonly unit: "million-tokens"
+  readonly input: ModelTokenPrice
+  readonly output: ModelTokenPrice
+  readonly cacheReadInput?: ModelTokenPrice
+  readonly cacheWriteInput?: ModelTokenPrice
+  readonly cacheWriteInput5m?: ModelTokenPrice
+  readonly cacheWriteInput1h?: ModelTokenPrice
+}
+
+/** Validate and snapshot provider-owned pricing independently of operational metadata. */
+export function defineModelRateCard(rateCard: LanguageModelRateCard): LanguageModelRateCard {
+  assertRecord(rateCard, "rate card")
+  if (rateCard.currency !== "USD" || rateCard.unit !== "million-tokens") {
+    throw new TypeError("[Sixb] Model rate cards must use USD per million tokens.")
+  }
+  return Object.freeze({
+    currency: "USD",
+    unit: "million-tokens",
+    input: tokenPrice(rateCard.input),
+    output: tokenPrice(rateCard.output),
+    ...(rateCard.cacheReadInput === undefined
+      ? {}
+      : { cacheReadInput: tokenPrice(rateCard.cacheReadInput) }),
+    ...(rateCard.cacheWriteInput === undefined
+      ? {}
+      : { cacheWriteInput: tokenPrice(rateCard.cacheWriteInput) }),
+    ...(rateCard.cacheWriteInput5m === undefined
+      ? {}
+      : { cacheWriteInput5m: tokenPrice(rateCard.cacheWriteInput5m) }),
+    ...(rateCard.cacheWriteInput1h === undefined
+      ? {}
+      : { cacheWriteInput1h: tokenPrice(rateCard.cacheWriteInput1h) }),
+  })
+}
+
+function tokenPrice(value: ModelTokenPrice): ModelTokenPrice {
+  if (typeof value === "string") return price(value)
+  assertRecord(value, "token price")
+  if (!Array.isArray(value.tiers)) throw new TypeError("[Sixb] Model price tiers must be an array.")
+  let previousMax = 0
+  return Object.freeze({
+    default: price(value.default),
+    tiers: Object.freeze(
+      value.tiers.map((tier, index) => {
+        assertRecord(tier, "price tier")
+        if (
+          typeof tier.minTokens !== "number" ||
+          !Number.isSafeInteger(tier.minTokens) ||
+          tier.minTokens < 0
+        ) {
+          throw new TypeError("[Sixb] Model price tier has an invalid minimum.")
+        }
+        if (index > 0 && tier.minTokens < previousMax) {
+          throw new TypeError("[Sixb] Model price tiers must be ordered and nonoverlapping.")
+        }
+        if (
+          tier.maxTokens !== undefined &&
+          (typeof tier.maxTokens !== "number" ||
+            !Number.isSafeInteger(tier.maxTokens) ||
+            tier.maxTokens <= tier.minTokens)
+        ) {
+          throw new TypeError("[Sixb] Model price tier has an invalid maximum.")
+        }
+        previousMax = tier.maxTokens ?? Number.POSITIVE_INFINITY
+        return Object.freeze({
+          minTokens: tier.minTokens,
+          ...(tier.maxTokens === undefined ? {} : { maxTokens: tier.maxTokens }),
+          price: price(tier.price),
+        })
+      })
+    ),
+  })
+}
+
+function price(value: unknown): string {
+  if (typeof value !== "string" || !/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value)) {
+    throw new TypeError("[Sixb] Model price must be a nonnegative decimal string.")
+  }
+  return value
+}
+
+function assertRecord(value: unknown, field: string): asserts value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`[Sixb] Model ${field} must be an object.`)
+  }
+}

package/src/models/tools.ts

@@ -0,0 +1,29 @@
+import type { JsonObject, JsonValue } from "../json"
+import type { ModelToolOutput } from "./messages"
+
+export interface ModelToolExecutionContext {
+  readonly signal: AbortSignal
+  readonly callId: string
+  readonly toolCallId: string
+}
+
+export interface ModelTool<TInput = unknown, TOutput extends JsonValue = JsonValue> {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: JsonObject
+  parseInput(value: unknown): TInput
+  execute(input: TInput, context: ModelToolExecutionContext): Promise<TOutput>
+  /** Project a durable output into provider-safe model content without changing the stored result. */
+  toModelOutput?(
+    output: TOutput,
+    context: ModelToolExecutionContext
+  ): ModelToolOutput | Promise<ModelToolOutput>
+  errorText(error: unknown): string
+}
+
+export interface ModelOutput<TOutput> {
+  readonly name: string
+  readonly description?: string
+  readonly schema: JsonObject
+  validate(value: unknown): TOutput
+}

package/src/queues/in-memory.ts

@@ -16,6 +16,7 @@ import type {
   QueueJob,
   QueueJobFailure,
   Queues,
+  SubagentQueueJob,
   SyncQueueJobFailureCode,
   SyncRunRequestedQueueJob,
   WorkflowQueueJob,
@@ -382,6 +383,10 @@ export class InMemoryQueues implements Queues {
     this.store,
     "agent.runs"
   )
+  readonly agentChildren = new InMemoryQueue<SubagentQueueJob, AgentQueueJobFailureCode>(
+    this.store,
+    "agent.children"
+  )
 
   /** Nothing to reach: the store is a field of this object. */
   health(): Promise<void> {

package/src/queues/index.ts

@@ -1,3 +1,12 @@
+export type {
+  ModelCallCost,
+  ModelCostComponent,
+  ModelCostEstimate,
+  ModelCostMeter,
+  ModelMoney,
+  ModelRoute,
+} from "../models"
+export type { ModelProviderIds } from "../models/events"
 export type { ProviderScope } from "../provider-scope"
 export { QueueError } from "./errors"
 export { InMemoryQueues } from "./in-memory"
@@ -22,6 +31,8 @@ export type {
   QueueJobEnvelope,
   QueueJobFailure,
   Queues,
+  SubagentQueueJob,
+  SubagentRunRequestedQueueJob,
   SyncQueueJobFailureCode,
   SyncRunRequestedQueueJob,
   WorkflowQueueJob,

package/src/queues/types.ts

@@ -1,10 +1,10 @@
 import type { SixbErrorCode, SixbFailure } from "../errors/types"
 import type { JsonValue } from "../json"
+import type { ModelCallCost, ModelCostEstimate, ModelRoute } from "../models"
 import type { ProjectionRunFailureCode } from "../projections/types"
 import type { ProviderScope } from "../provider-scope"
 import type { ActionRunFailureCode } from "../storage/action-runs/types"
 import type { AgentRunFailureCode } from "../storage/agents/types"
-import type { AiPricingContext } from "../storage/ai-cost/types"
 import type { RecordAiModelCallInput } from "../storage/ai-usage"
 import type { PipelineRunFailureCode } from "../storage/pipeline-runs/types"
 import type { SyncRunFailureCode } from "../storage/sync-runs/types"
@@ -191,6 +191,17 @@ export interface AgentRunRequestedQueueJob
     }
   > {}
 
+/** A headless child run uses a reserved lane so waiting parents cannot consume its capacity. */
+export interface SubagentRunRequestedQueueJob
+  extends QueueJob<
+    "agent.subagent-run.requested",
+    {
+      readonly runId: string
+    }
+  > {}
+
+export type SubagentQueueJob = SubagentRunRequestedQueueJob
+
 export interface AgentWorkflowNodeRequestedQueueJob
   extends QueueJob<
     "agent.workflow-node.requested",
@@ -211,8 +222,12 @@ export type AgentAiUsageRecordPayload = Omit<
 }
 
 export interface AgentAiUsageAccountingPayload {
-  readonly pricingContext: AiPricingContext
+  readonly estimate?: ModelCostEstimate
+  readonly cost: ModelCallCost
+  readonly route?: ModelRoute
   readonly ratedAt: string
+  /** Absent on pre-limit jobs; those model calls did not create a reservation. */
+  readonly reconcileLimitReservation?: boolean
 }
 
 export interface AgentAiUsageRecordRequestedQueueJob
@@ -220,7 +235,7 @@ export interface AgentAiUsageRecordRequestedQueueJob
     "agent.ai-usage.record.requested",
     {
       readonly record: AgentAiUsageRecordPayload
-      /** Absent on Phase 1 jobs; recovery then uses an empty pricing context. */
+      /** Absent only on legacy jobs that predate atomic valuation recovery. */
       readonly accounting?: AgentAiUsageAccountingPayload
     }
   > {}
@@ -237,6 +252,8 @@ export interface Queues {
   readonly workflows: Queue<WorkflowQueueJob, WorkflowQueueJobFailureCode>
   readonly actions: Queue<ActionRunRequestedQueueJob, ActionQueueJobFailureCode>
   readonly agents: Queue<AgentQueueJob, AgentQueueJobFailureCode>
+  /** Internal capacity reserved for headless child runs. */
+  readonly agentChildren: Queue<SubagentQueueJob, AgentQueueJobFailureCode>
 
   /**
    * Whether these queues can be shared across processes.

package/src/runtime/create.ts

@@ -1,6 +1,7 @@
 import { resolve } from "node:path"
 import type { ActionDefinition } from "../actions"
-import type { AgentDefinition } from "../agents"
+import type { AgentToolDefinition } from "../agents"
+import { assertNoAgentDefinitions } from "../agents/retired-config"
 import type { SixbAuthConfig } from "../auth"
 import type { BlobStorage } from "../blob-storage"
 import { discoverOntologySources, discoverProjectDefinitions } from "../bootstrap"
@@ -44,10 +45,10 @@ export interface CreateSixbOptions {
   ontologyMaintenance?: OntologyMaintenanceOptions
   ontologies?: readonly OntologySource[]
   actions?: readonly ActionDefinition[]
-  /** Agent definitions to register in addition to auto-discovered `agents/` exports. */
-  agents?: readonly AgentDefinition[]
   /** Models this project allows Sixb to use. The first of each kind is the default. */
   models?: ModelCatalogInput
+  /** Project tools available to Agent runtimes. */
+  tools?: readonly AgentToolDefinition[]
   datasets?: readonly DatasetDefinition[]
   /** Connector definitions to register in addition to auto-discovered `connectors/` exports. */
   connectors?: readonly ConnectorDefinition[]
@@ -71,12 +72,13 @@ export interface CreateSixbOptions {
  *
  * The host auto-discovers exported definitions from `ontology/`, `actions/`, `datasets/`,
  * `connectors/`, `syncs/`, `schedules/`, `pipelines/`, `projections/`,
- * `rules/`, `workflows/`, `agents/`, and `security/{groups,roles,policies}/`
+ * `rules/`, `workflows/`, and `security/{groups,roles,policies}/`
  * relative to `projectRoot`.
  */
 export async function createSixb(
   options: CreateSixbOptions
 ): Promise<SixbHost<readonly OntologySource[]>> {
+  assertNoAgentDefinitions(options)
   const projectRoot = resolve(options.projectRoot ?? process.cwd())
 
   const discoveredOntology = await discoverOntologySources(projectRoot)
@@ -120,8 +122,8 @@ export async function createSixb(
     groups: [...(options.groups ?? []), ...definitions.groups],
     roles: [...(options.roles ?? []), ...definitions.roles],
     membershipPolicies: [...(options.membershipPolicies ?? []), ...definitions.membershipPolicies],
-    agents: [...(options.agents ?? []), ...definitions.agents],
     models: options.models,
+    tools: options.tools,
     auth: options.auth,
   })
 }

package/src/runtime/definitions.ts

@@ -1,5 +1,5 @@
 import type { ActionDefinitionCatalog } from "../actions"
-import type { AgentDefinition } from "../agents"
+import type { AgentToolCatalog } from "../agents"
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets"
 import type { ModelCatalog } from "../models"
@@ -22,7 +22,7 @@ export interface DefinitionCatalog<TDefinition> {
 export interface SixbDefinitions {
   readonly ontology: OntologyDefinitionCatalog
   readonly actions: ActionDefinitionCatalog
-  readonly agents: DefinitionCatalog<AgentDefinition>
+  readonly tools: AgentToolCatalog
   readonly connectors: DefinitionCatalog<ConnectorDefinition>
   readonly datasets: DefinitionCatalog<DatasetDefinition>
   /** Absent until a project configures `models` in createSixb(). */

package/src/runtime/host.ts

@@ -7,7 +7,7 @@
 
 import { resolve } from "node:path"
 import type { ActionDefinition } from "../actions/types"
-import type { AgentDefinition } from "../agents"
+import type { AgentToolDefinition } from "../agents"
 import {
   AuthRuntime,
   AuthRuntimeError,
@@ -108,8 +108,9 @@ export interface SixbHostOptions<TOntologySources extends readonly OntologySourc
   projections?: readonly ProjectionDefinition[]
   rules?: readonly RuleDefinition[]
   workflows?: readonly WorkflowDefinition[]
-  agents?: readonly AgentDefinition[]
   models?: ModelCatalogInput
+  /** Project tools available to Agent runtimes. */
+  tools?: readonly AgentToolDefinition[]
   groups?: readonly GroupDefinition[]
   roles?: readonly RoleDefinition[]
   membershipPolicies?: readonly MembershipPolicyDefinition[]

package/src/runtime/resolve-definitions.ts

@@ -1,11 +1,12 @@
 import { ActionRegistry } from "../actions"
 import type { ActionDefinition } from "../actions/types"
-import type { AgentDefinition } from "../agents"
-import { validateAgentGroupReferences, validateAgentToolsAtStartup } from "../agents"
+import type { AgentToolDefinition } from "../agents"
+import { assertNoAgentDefinitions } from "../agents/retired-config"
+import { createAgentToolCatalog } from "../agents/tool-catalog"
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets/types"
 import { assertDatasetDefinition } from "../datasets/validation"
-import { createModelCatalog, type ModelCatalog, type ModelCatalogInput, modelRef } from "../models"
+import { createModelCatalog, type ModelCatalogInput } from "../models"
 import { OntologyRegistry } from "../ontology"
 import type { PipelineDefinition } from "../pipelines/types"
 import { ProjectionRegistry } from "../projections"
@@ -24,7 +25,7 @@ import {
   validateMergeSyncProjectionSafety,
 } from "../syncs/validation"
 import type { WorkflowDefinition } from "../workflows"
-import { validateWorkflowsAtStartup } from "../workflows"
+import { validateWorkflowAgentStepGroupReferences, validateWorkflowsAtStartup } from "../workflows"
 import { createDefinitionCatalog, type SixbDefinitions } from "./definitions"
 import { RuntimeError } from "./errors"
 import type { OntologySource } from "./types"
@@ -40,7 +41,7 @@ interface DefinitionOptions {
   readonly projections?: readonly ProjectionDefinition[]
   readonly rules?: readonly RuleDefinition[]
   readonly workflows?: readonly WorkflowDefinition[]
-  readonly agents?: readonly AgentDefinition[]
+  readonly tools?: readonly AgentToolDefinition[]
   readonly models?: ModelCatalogInput
   readonly groups?: readonly GroupDefinition[]
   readonly roles?: readonly RoleDefinition[]
@@ -56,15 +57,13 @@ interface ResolvedDefinitions extends SixbDefinitions {
 
 /** Resolve and cross-validate every registered definition before runtime services are composed. */
 export function resolveDefinitions(options: DefinitionOptions): ResolvedDefinitions {
+  assertNoAgentDefinitions(options)
   const ontology = new OntologyRegistry({ sources: options.ontology })
   const actionRegistry = new ActionRegistry({ actions: options.actions ?? [], ontology })
   const registeredActionIds = new Set(actionRegistry.list().map((action) => action.id))
 
-  const agents = options.agents ?? []
-  validateAgentToolsAtStartup(agents)
   const models = options.models === undefined ? undefined : createModelCatalog(options.models)
-  validateAgentModelReferences(agents, models)
-  const agentsById = indexUniqueDefinitions("agent", agents)
+  const tools = createAgentToolCatalog(options.tools)
   const connectorsById = indexUniqueDefinitions("connector", options.connectors ?? [])
 
   // Datasets resolve first because syncs, pipelines, projections, and security depend on them.
@@ -126,7 +125,8 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
     workflows: options.workflows ?? [],
     registeredSchedules: schedulesById,
     registeredActionIds,
-    registeredAgentIds: new Set(agentsById.keys()),
+    ...(models === undefined ? {} : { models }),
+    tools,
   })
   const workflowsById = indexUniqueDefinitions("workflow", workflows)
 
@@ -140,11 +140,11 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
     workflowIds: new Set(workflowsById.keys()),
     syncIds: new Set(syncsById.keys()),
     pipelineIds: new Set(pipelinesById.keys()),
-    agentIds: new Set(agentsById.keys()),
+    agentAvailable: models !== undefined,
     connectorIds: new Set(connectorsById.keys()),
     getSubTypes: (objectTypeId) => ontology.listSubTypes(objectTypeId),
   })
-  validateAgentGroupReferences(agents, security)
+  validateWorkflowAgentStepGroupReferences(workflows, security)
 
   const projectionRegistry = new ProjectionRegistry({
     projections: options.projections ?? [],
@@ -159,7 +159,7 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
   return Object.freeze({
     ontology,
     actions: actionRegistry,
-    agents: createDefinitionCatalog(agentsById),
+    tools,
     connectors: createDefinitionCatalog(connectorsById),
     datasets: createDefinitionCatalog(datasetsById),
     ...(models === undefined ? {} : { models }),
@@ -241,26 +241,3 @@ function validateScheduleReferences(
     }
   }
 }
-
-/**
- * Keep every agent on a model the project actually allows.
- *
- * Only enforced once a project configures `models`; without a catalog an agent's model is its own
- * declaration, which is the pre-catalog behavior.
- */
-function validateAgentModelReferences(
-  agents: readonly AgentDefinition[],
-  models: ModelCatalog | undefined
-): void {
-  if (models === undefined) {
-    return
-  }
-  for (const agent of agents) {
-    const ref = modelRef(agent.model)
-    if (models.language.getById(ref) === null) {
-      throw new RuntimeError(
-        `[Sixb] Agent '${agent.id}' uses unknown language model '${ref}'. Add it to 'models.language' in createSixb().`
-      )
-    }
-  }
-}

package/src/runtime/sixb.ts

@@ -1,5 +1,6 @@
 import { type ActionsRuntime, createActionsRuntime } from "../actions/execution"
-import { type AgentsRuntime, createAgentsRuntime } from "../agents/execution"
+import { type AgentRuntime, createAgentRuntime } from "../agents/execution"
+import { type AiUsageRuntime, createAiUsageRuntime } from "../ai-usage"
 import { type BlobsRuntime, createBlobsRuntime } from "../blob-storage/execution"
 import type { BlobStorage } from "../blob-storage/types"
 import { registerConnectorConnectionsRuntime } from "../connectors/connections/capability"
@@ -36,7 +37,8 @@ export interface Sixb<
   readonly pipelines: PipelinesRuntime
   readonly projections: ProjectionsRuntime
   readonly rules: RulesRuntime
-  readonly agents: AgentsRuntime
+  readonly agent: AgentRuntime
+  readonly aiUsage: AiUsageRuntime
   readonly events: EventsRuntime
   readonly logs: LogsRuntime
   readonly schedules: SchedulesRuntime
@@ -95,12 +97,8 @@ function createExecutionFacades<TOntologySources extends readonly OntologySource
     pipelines: createPipelinesRuntime(runtime, execution, dependencies.definitions.pipelines),
     projections: createProjectionsRuntime(runtime, dependencies.definitions.projections),
     rules: createRulesRuntime(runtime, dependencies.definitions.rules),
-    agents: createAgentsRuntime(
-      runtime,
-      execution,
-      dependencies.definitions.agents,
-      dependencies.definitions.security
-    ),
+    agent: createAgentRuntime(runtime, execution, dependencies.definitions.models),
+    aiUsage: createAiUsageRuntime(runtime, dependencies.definitions.security),
     events: createEventsRuntime(runtime),
     logs: createLogsRuntime(runtime, dependencies.logging),
     schedules: createSchedulesRuntime(dependencies.definitions.schedules),

package/src/security/every.ts

@@ -12,7 +12,6 @@
  */
 
 import type { ActionDefinition } from "../actions/types"
-import type { AgentDefinition } from "../agents/types"
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets"
 import type { ObjectType } from "../ontology"
@@ -30,7 +29,6 @@ export const BREADTH_TARGETS = [
   "workflow",
   "sync",
   "pipeline",
-  "agent",
   "application",
   "connector",
 ] as const
@@ -44,7 +42,6 @@ interface BreadthTargetInput {
   workflow: WorkflowDefinition
   sync: SyncDefinition
   pipeline: PipelineDefinition
-  agent: AgentDefinition
   application: ApplicationDefinition
   connector: ConnectorDefinition
 }
@@ -106,7 +103,6 @@ export const every = {
   workflow: (): BreadthSelector<"workflow"> => all("workflow"),
   sync: (): BreadthSelector<"sync"> => all("sync"),
   pipeline: (): BreadthSelector<"pipeline"> => all("pipeline"),
-  agent: (): BreadthSelector<"agent"> => all("agent"),
   application: (): BreadthSelector<"application"> => all("application"),
   connector: (): BreadthSelector<"connector"> => all("connector"),
 }

package/src/security/grants.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ActionDefinition } from "../actions/types"
-import type { AgentDefinition } from "../agents/types"
+import type { AgentReference, AgentUsageReference } from "../agents/types"
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets"
 import type { ObjectType } from "../ontology"
@@ -24,6 +24,7 @@ import {
 } from "./every"
 import type {
   AccessGrant,
+  AgentRunGrant,
   AppendGrant,
   ApplicationDefinition,
   ApplyGrant,
@@ -41,7 +42,7 @@ type GrantInput<TDefinition, TTarget extends BreadthTarget> =
   | BreadthSelector<TTarget>
 
 const VIEW_TARGETS = ["object", "dataset"] as const
-const RUN_TARGETS = ["workflow", "sync", "pipeline", "agent"] as const
+const RUN_TARGETS = ["workflow", "sync", "pipeline"] as const
 
 /**
  * Seven of the nine targets carry a `kind` discriminant naming themselves. The other two — an
@@ -52,7 +53,6 @@ const TARGET_BY_DEFINITION_KIND: Readonly<Partial<Record<string, BreadthTarget>>
   dataset: "dataset",
   sync: "sync",
   pipeline: "pipeline",
-  agent: "agent",
   workflow: "workflow",
   application: "application",
   connector: "connector",
@@ -187,18 +187,49 @@ function apply(input: GrantInput<ActionDefinition, "action">): ApplyGrant {
 function run(input: GrantInput<WorkflowDefinition, "workflow">): RunGrant<"workflow">
 function run(input: GrantInput<SyncDefinition, "sync">): RunGrant<"sync">
 function run(input: GrantInput<PipelineDefinition, "pipeline">): RunGrant<"pipeline">
-function run(input: GrantInput<AgentDefinition, "agent">): RunGrant<"agent">
+function run(input: AgentReference): AgentRunGrant
 function run(
-  input: GrantInput<
-    WorkflowDefinition | SyncDefinition | PipelineDefinition | AgentDefinition,
-    "workflow" | "sync" | "pipeline" | "agent"
-  >
-): RunGrant {
+  input:
+    | AgentReference
+    | GrantInput<
+        WorkflowDefinition | SyncDefinition | PipelineDefinition,
+        "workflow" | "sync" | "pipeline"
+      >
+): RunGrant | AgentRunGrant {
+  if (isAgentReference(input)) {
+    return { kind: "grant", capability: "run", target: "agent" }
+  }
   const { target, selection } = resolveGrant(input, "can.run", RUN_TARGETS)
   return { kind: "grant", capability: "run", target, selection }
 }
 
-function observe(target: "logs"): ObserveGrant {
+function isAgentReference(input: unknown): input is AgentReference {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    !Array.isArray(input) &&
+    !isBreadthSelector(input) &&
+    "kind" in input &&
+    input.kind === "agent"
+  )
+}
+
+function isAgentUsageReference(input: unknown): input is AgentUsageReference {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    !Array.isArray(input) &&
+    !isBreadthSelector(input) &&
+    "kind" in input &&
+    input.kind === "aiUsage"
+  )
+}
+
+function observe(input: "logs" | AgentUsageReference): ObserveGrant {
+  if (input !== "logs" && !isAgentUsageReference(input)) {
+    throw new SecurityValidationError('[Sixb] can.observe accepts "logs" or agent.usage.')
+  }
+  const target = input === "logs" ? "logs" : "aiUsage"
   return {
     kind: "grant",
     capability: "observe",
@@ -207,10 +238,23 @@ function observe(target: "logs"): ObserveGrant {
   }
 }
 
-function manage(input: GrantInput<ConnectorDefinition, "connector">): ManageGrant {
+function manage(input: GrantInput<ConnectorDefinition, "connector">): ManageGrant<"connector">
+function manage(input: AgentUsageReference): ManageGrant<"aiUsage">
+function manage(
+  input: GrantInput<ConnectorDefinition, "connector"> | AgentUsageReference
+): ManageGrant {
+  if (isAgentUsageReference(input)) {
+    return {
+      kind: "grant",
+      capability: "manage",
+      target: "aiUsage",
+      selection: { all: false, ids: ["aiUsage"] },
+    }
+  }
   return {
     kind: "grant",
     capability: "manage",
+    target: "connector",
     selection: resolveGrant(input, "can.manage", ["connector"]).selection,
   }
 }

package/src/security/index.ts

@@ -20,6 +20,7 @@ export type { SecurityDefinitionCatalog, SecurityRegistryOptions } from "./regis
 export { SecurityRegistry } from "./registry"
 export type {
   AccessGrant,
+  AgentRunGrant,
   AppendGrant,
   ApplicationDefinition,
   ApplyGrant,
@@ -29,6 +30,7 @@ export type {
   GroupDefinition,
   GroupReference,
   ManageGrant,
+  ManageGrantTarget,
   MembershipOperation,
   MembershipPolicyDefinition,
   ObserveGrant,

package/src/security/registry.ts

@@ -25,7 +25,7 @@ export interface SecurityRegistryOptions {
   readonly workflowIds?: ReadonlySet<string>
   readonly syncIds?: ReadonlySet<string>
   readonly pipelineIds?: ReadonlySet<string>
-  readonly agentIds?: ReadonlySet<string>
+  readonly agentAvailable?: boolean
   readonly connectorIds?: ReadonlySet<string>
   readonly getSubTypes?: (objectTypeId: string) => readonly string[]
 }
@@ -48,9 +48,10 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       workflowIds: input.workflowIds,
       syncIds: input.syncIds,
       pipelineIds: input.pipelineIds,
-      agentIds: input.agentIds,
+      agentAvailable: input.agentAvailable,
       connectorIds: input.connectorIds,
-      observableIds: new Set(["logs"]),
+      observableIds: new Set(["logs", "aiUsage"]),
+      manageableIds: new Set(["aiUsage"]),
     })
 
     const universe = {
@@ -61,9 +62,9 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       workflowIds: input.workflowIds ?? new Set<string>(),
       syncIds: input.syncIds ?? new Set<string>(),
       pipelineIds: input.pipelineIds ?? new Set<string>(),
-      agentIds: input.agentIds ?? new Set<string>(),
       connectorIds: input.connectorIds ?? new Set<string>(),
-      observableIds: new Set(["logs"]),
+      observableIds: new Set(["logs", "aiUsage"]),
+      manageableIds: new Set(["aiUsage"]),
       getSubTypes: input.getSubTypes ?? (() => []),
     }