@sixb/core 0.1.6 → 0.1.7

package/src/authorization/decision.ts

@@ -31,8 +31,10 @@ export type AuthzRequest =
   | { readonly kind: "workflow.run"; readonly workflowId: string }
   | { readonly kind: "sync.run"; readonly syncId: string }
   | { readonly kind: "pipeline.run"; readonly pipelineId: string }
-  | { readonly kind: "agent.run"; readonly agentId: string }
+  | { readonly kind: "agent.run" }
   | { readonly kind: "logs.observe" }
+  | { readonly kind: "aiUsage.observe" }
+  | { readonly kind: "aiUsage.manage" }
   | { readonly kind: "connector.manage"; readonly connectorId: string }
   | { readonly kind: "object.query"; readonly touchedObjectTypeIds: readonly string[] }
 
@@ -53,10 +55,9 @@ interface AuthorizedRuntime {
 // the single unit that both names a requirement and tests the grant index, so
 // the two can never drift. `kind` is the resolved-index key, so enforcement is
 // a direct lookup with no per-target dispatch.
-interface Atom {
-  readonly kind: GrantKind
-  readonly id: string
-}
+type Atom =
+  | { readonly kind: "run:agent" }
+  | { readonly kind: Exclude<GrantKind, "run:agent">; readonly id: string }
 
 function atomsFor(request: AuthzRequest): readonly Atom[] {
   switch (request.kind) {
@@ -79,9 +80,13 @@ function atomsFor(request: AuthzRequest): readonly Atom[] {
     case "pipeline.run":
       return [{ kind: "run:pipeline", id: request.pipelineId }]
     case "agent.run":
-      return [{ kind: "run:agent", id: request.agentId }]
+      return [{ kind: "run:agent" }]
     case "logs.observe":
       return [{ kind: "observe:logs", id: "logs" }]
+    case "aiUsage.observe":
+      return [{ kind: "observe:aiUsage", id: "aiUsage" }]
+    case "aiUsage.manage":
+      return [{ kind: "manage:aiUsage", id: "aiUsage" }]
     case "connector.manage":
       return [{ kind: "manage:connector", id: request.connectorId }]
     case "object.query":
@@ -90,11 +95,19 @@ function atomsFor(request: AuthzRequest): readonly Atom[] {
 }
 
 function atomKey(atom: Atom): string {
-  if (atom.kind === "observe:logs") return atom.kind
+  if (atom.kind === "run:agent") return atom.kind
+  if (
+    atom.kind === "observe:logs" ||
+    atom.kind === "observe:aiUsage" ||
+    atom.kind === "manage:aiUsage"
+  ) {
+    return atom.kind
+  }
   return `${atom.kind}:${atom.id}`
 }
 
 function holds(grants: GrantIndex, atom: Atom): boolean {
+  if (atom.kind === "run:agent") return grants[atom.kind]
   return grants[atom.kind].has(atom.id)
 }
 
@@ -205,7 +218,7 @@ export function assertPrivileged(runtime: AuthorizedRuntime, operation: string):
  * Assert access to process providers that trusted executions and genuine agent runs may use.
  *
  * Agent provenance alone is not authority: the registered capability must be bound to the exact
- * same agent and run before this check succeeds.
+ * same execution identity and run before this check succeeds.
  */
 export function assertProviderAccess(
   runtime: AuthorizedRuntime,
@@ -223,7 +236,7 @@ export function assertProviderAccess(
     binding?.type === "agent" &&
     executor.type === "agent" &&
     binding.executionId === execution.id &&
-    binding.agentId === executor.agentId &&
+    binding.actorId === executor.actorId &&
     binding.runId === executor.runId
   ) {
     return
@@ -260,9 +273,13 @@ function deniedMessage(
     case "pipeline.run":
       return `[Sixb] Principal '${principalId}' is not allowed to run pipeline '${request.pipelineId}'.`
     case "agent.run":
-      return `[Sixb] Principal '${principalId}' is not allowed to run agent '${request.agentId}'.`
+      return `[Sixb] Principal '${principalId}' is not allowed to run the project Agent.`
     case "logs.observe":
       return `[Sixb] Principal '${principalId}' is not allowed to observe project logs.`
+    case "aiUsage.observe":
+      return `[Sixb] Principal '${principalId}' is not allowed to observe project AI usage.`
+    case "aiUsage.manage":
+      return `[Sixb] Principal '${principalId}' is not allowed to manage project AI usage limits.`
     case "connector.manage":
       return `[Sixb] Principal '${principalId}' is not allowed to manage connector '${request.connectorId}'.`
     case "object.query": {

package/src/authorization/grant-kinds.ts

@@ -8,7 +8,7 @@
  * entry in `GRANT_KINDS` plus the compile errors that forces at every consumer.
  */
 
-import type { GrantDefinition } from "../security/types"
+import type { AgentRunGrant, GrantDefinition } from "../security/types"
 
 export type GrantKind =
   | "access:application"
@@ -22,7 +22,12 @@ export type GrantKind =
   | "run:pipeline"
   | "run:agent"
   | "observe:logs"
+  | "observe:aiUsage"
   | "manage:connector"
+  | "manage:aiUsage"
+
+export type SingletonGrantKind = "run:agent"
+export type TargetedGrantKind = Exclude<GrantKind, SingletonGrantKind>
 
 /** Registered id universes a grant kind ranges over, plus subtype expansion. */
 export interface GrantUniverse {
@@ -33,16 +38,16 @@ export interface GrantUniverse {
   readonly workflowIds: ReadonlySet<string>
   readonly syncIds: ReadonlySet<string>
   readonly pipelineIds: ReadonlySet<string>
-  readonly agentIds: ReadonlySet<string>
   readonly observableIds: ReadonlySet<string>
   readonly connectorIds: ReadonlySet<string>
+  readonly manageableIds: ReadonlySet<string>
   readonly getSubTypes: (objectTypeId: string) => readonly string[]
 }
 
 /** The registered-id sets a grant kind validates against (no subtype hook). */
 export type GrantUniverseKey = Exclude<keyof GrantUniverse, "getSubTypes">
 
-interface GrantKindSpec {
+interface TargetedGrantKindSpec {
   /** Registered universe the grant's ids must belong to. */
   readonly universeKey: GrantUniverseKey
   /** Subject noun used in validation errors ("unknown <subject> '<id>'"). */
@@ -53,11 +58,22 @@ interface GrantKindSpec {
   readonly expandsSubtypes?: true
 }
 
+interface SingletonGrantKindSpec {
+  /** Project-wide capability with no resource selection; resolves to a boolean. */
+  readonly singleton: true
+  readonly subject: string
+  readonly fix: string
+}
+
 /**
  * The exhaustive grant-kind table. A new grant family is one entry here; the
- * `Record<GrantKind, …>` makes every omission a compile error.
+ * mapped type makes every omission a compile error.
  */
-export const GRANT_KINDS: Record<GrantKind, GrantKindSpec> = {
+export const GRANT_KINDS: {
+  readonly [TKind in GrantKind]: TKind extends SingletonGrantKind
+    ? SingletonGrantKindSpec
+    : TargetedGrantKindSpec
+} = {
   "access:application": {
     universeKey: "applicationIds",
     subject: "application",
@@ -108,25 +124,41 @@ export const GRANT_KINDS: Record<GrantKind, GrantKindSpec> = {
     fix: "Add it to 'pipelines/' or pass it to createSixb({ pipelines }).",
   },
   "run:agent": {
-    universeKey: "agentIds",
+    singleton: true,
     subject: "agent",
-    fix: "Add it to 'agents/' or pass it to createSixb({ agents }).",
+    fix: "Configure models.language and use the exported agent reference in can.run(agent).",
   },
   "observe:logs": {
     universeKey: "observableIds",
     subject: "observability surface",
     fix: 'Use can.observe("logs").',
   },
+  "observe:aiUsage": {
+    universeKey: "observableIds",
+    subject: "observability surface",
+    fix: "Use can.observe(agent.usage).",
+  },
   "manage:connector": {
     universeKey: "connectorIds",
     subject: "connector",
     fix: "Add it to 'connectors/' or pass it to createSixb({ connectors }).",
   },
+  "manage:aiUsage": {
+    universeKey: "manageableIds",
+    subject: "management surface",
+    fix: "Use can.manage(agent.usage).",
+  },
 }
 
 export const GRANT_KIND_KEYS = Object.keys(GRANT_KINDS) as readonly GrantKind[]
+export const TARGETED_GRANT_KIND_KEYS = GRANT_KIND_KEYS.filter(
+  (kind): kind is TargetedGrantKind => kind !== "run:agent"
+)
 
 /** The grant kind a stored grant resolves to. */
+export function grantKindOf(grant: AgentRunGrant): SingletonGrantKind
+export function grantKindOf(grant: Exclude<GrantDefinition, AgentRunGrant>): TargetedGrantKind
+export function grantKindOf(grant: GrantDefinition): GrantKind
 export function grantKindOf(grant: GrantDefinition): GrantKind {
   switch (grant.capability) {
     case "access":
@@ -142,17 +174,32 @@ export function grantKindOf(grant: GrantDefinition): GrantKind {
     case "run":
       return `run:${grant.target}`
     case "observe":
-      return "observe:logs"
+      return `observe:${grant.target}`
     case "manage":
-      return "manage:connector"
+      return `manage:${grant.target}`
   }
 }
 
-/** A fresh, mutable grant index with one empty id set per kind. */
-export function emptyGrantSets(): Record<GrantKind, Set<string>> {
-  const sets = {} as Record<GrantKind, Set<string>>
-  for (const kind of GRANT_KIND_KEYS) {
-    sets[kind] = new Set<string>()
+/** Mutable grant index: booleans for singleton capabilities, id sets for selected resources. */
+export type MutableGrantIndex = {
+  [TKind in GrantKind]: TKind extends SingletonGrantKind ? boolean : Set<string>
+}
+
+export function emptyGrantSets(): MutableGrantIndex {
+  return {
+    "access:application": new Set(),
+    "view:object": new Set(),
+    "view:dataset": new Set(),
+    "edit:object": new Set(),
+    "append:telemetry": new Set(),
+    "apply:action": new Set(),
+    "run:workflow": new Set(),
+    "run:sync": new Set(),
+    "run:pipeline": new Set(),
+    "run:agent": false,
+    "observe:logs": new Set(),
+    "observe:aiUsage": new Set(),
+    "manage:connector": new Set(),
+    "manage:aiUsage": new Set(),
   }
-  return sets
 }

package/src/authorization/index.ts

@@ -7,6 +7,7 @@ export {
   assertCanManageConnector,
   assertPrivileged,
   assertProviderAccess,
+  assertRuntimeAuthorizationBound,
   evaluate,
   isAllowed,
 } from "./decision"

package/src/authorization/resolve.ts

@@ -2,19 +2,19 @@ import type { Principal } from "../auth/types"
 import type { RoleDefinition, Selection } from "../security"
 import {
   emptyGrantSets,
-  GRANT_KIND_KEYS,
   GRANT_KINDS,
   type GrantUniverse,
   grantKindOf,
+  TARGETED_GRANT_KIND_KEYS,
 } from "./grant-kinds"
 import type { AuthorizationContext, GrantIndex, ResolvedRole } from "./types"
 
 /**
- * Expand a role's grants into concrete id sets once at startup.
+ * Resolve a role's grants once at startup.
  *
  * Broad grants (`every.object().except([...])`) expand against the registered
- * universe; object-type grants also expand to subtypes. The result holds only
- * `Set`s, so per-request resolution and runtime checks stay simple `set.has`.
+ * universe; object-type grants also expand to subtypes. Resource grants become
+ * id sets; the project Agent grant becomes a boolean.
  * The per-kind universe and subtype rules come from the `GRANT_KINDS` table, so
  * this loop never enumerates targets by hand.
  */
@@ -22,6 +22,10 @@ export function resolveRoleGrants(role: RoleDefinition, universe: GrantUniverse)
   const grants = emptyGrantSets()
 
   for (const grant of role.grants) {
+    if (grant.capability === "run" && grant.target === "agent") {
+      grants["run:agent"] = true
+      continue
+    }
     const kind = grantKindOf(grant)
     const spec = GRANT_KINDS[kind]
     expandSelection(
@@ -84,7 +88,10 @@ export function resolveAuthorizationContext(input: {
     }
 
     roleIds.push(role.id)
-    for (const kind of GRANT_KIND_KEYS) {
+    if (role.grants["run:agent"]) {
+      grants["run:agent"] = true
+    }
+    for (const kind of TARGETED_GRANT_KIND_KEYS) {
       for (const id of role.grants[kind]) {
         grants[kind].add(id)
       }

package/src/authorization/types.ts

@@ -8,16 +8,18 @@
  */
 
 import type { Principal } from "../auth/types"
-import { emptyGrantSets, type GrantKind } from "./grant-kinds"
+import { emptyGrantSets, type GrantKind, type SingletonGrantKind } from "./grant-kinds"
 
 /**
- * Grants resolved to concrete id sets, keyed by grant kind (`view:object`,
- * `run:sync`, …). Broad grants and object subtypes are already expanded, so
- * enforcement is a single `grants[kind].has(id)` lookup. Keyed by `GrantKind`
+ * Grants keyed by kind (`view:object`, `run:sync`, …). Resource selections resolve
+ * to id sets; project-wide singleton capabilities resolve to booleans.
+ * Broad grants and object subtypes are already expanded. Keyed by `GrantKind`
  * so a new grant family adds one key, not a new bucket every consumer must
  * learn.
  */
-export type GrantIndex = Readonly<Record<GrantKind, ReadonlySet<string>>>
+export type GrantIndex = Readonly<{
+  [TKind in GrantKind]: TKind extends SingletonGrantKind ? boolean : ReadonlySet<string>
+}>
 
 /**
  * A grant index that grants nothing, as the base for a hand-built context — typically in tests.

package/src/bootstrap/discovery.ts

@@ -10,7 +10,6 @@ import { readdir } from "node:fs/promises"
 import { join, relative } from "node:path"
 import { pathToFileURL } from "node:url"
 import { isActionDefinition } from "../actions"
-import { isAgentDefinition } from "../agents"
 import { isConnectorDefinition } from "../connectors"
 import { isDatasetDefinition } from "../datasets"
 import type { OntologyDocumentInput, OntologySource } from "../ontology/registry"
@@ -73,7 +72,6 @@ export async function discoverOntologySources(
 
 type DiscoveryModuleKind =
   | "action"
-  | "agent"
   | "connector"
   | "dataset"
   | "group"
@@ -138,7 +136,6 @@ const definitionDiscoveryRegistry = {
     kind: "membershipPolicy",
     isDefinition: isMembershipPolicyDefinition,
   },
-  agents: { directory: ["agents"], kind: "agent", isDefinition: isAgentDefinition },
 } as const satisfies Record<string, DefinitionDiscoveryFamily<unknown>>
 
 type DefinitionFromFamily<TFamily> =

package/src/error-reporting/types.ts

@@ -15,8 +15,10 @@ export interface SixbRunIdentityByKind {
   }
   readonly agent: {
     readonly runId: string
-    readonly agentId: string
-  }
+  } & (
+    | { readonly threadId: string; readonly parentRunId?: never }
+    | { readonly parentRunId: string; readonly threadId?: never }
+  )
   readonly pipeline: {
     readonly runId: string
     readonly pipelineId: string

package/src/errors/catalog.ts

@@ -18,6 +18,14 @@ export const SIXB_ERROR_DEFINITIONS = {
     publicMessage: "Agent execution failed.",
     retryable: false,
   },
+  "ai.usage_limit_exceeded": {
+    publicMessage: "AI usage limit exceeded.",
+    retryable: false,
+  },
+  "ai.usage_limit_unavailable": {
+    publicMessage: "AI usage limit could not be evaluated.",
+    retryable: true,
+  },
   "connector.adapter_invalid": {
     publicMessage: "Connector adapter returned an invalid result.",
     retryable: false,

package/src/execution/agent.ts

@@ -1,11 +1,18 @@
-import { agentServiceAccountId } from "../agents/authority"
-import type { AuthorizationContext } from "../authorization"
+import { type AgentExecutionAuthorization, agentServiceAccountId } from "../agents/authority"
 import type { OntologySource } from "../ontology"
 import { isBoundSixb, type Sixb } from "../runtime/sixb"
 import type { CreateExecutionInput, ExecutionRecord } from "../storage/executions"
 import { ExecutionStorageError } from "../storage/executions"
-import { createAgentRuntimeAuthorization } from "./authorization"
-import type { AuthorizablePrincipal, ExecutionContext, ExecutionScope } from "./types"
+
+export { ensureExecutionRecord } from "./durable"
+
+import { createAgentRuntimeAuthorization, getAuthorizationRef } from "./authorization"
+import type {
+  AuthorizablePrincipal,
+  ExecutionContext,
+  ExecutionScope,
+  RuntimeAuthorization,
+} from "./types"
 
 /** Minimal host boundary required by agent workers. */
 export interface AgentExecutionHost {
@@ -13,15 +20,24 @@ export interface AgentExecutionHost {
   withScope(scope: ExecutionScope): object
 }
 
+/** Whether a conversational Agent run can durably restore this request authority without widening it. */
+export function canInheritAgentRequestAuthorization(authorization: RuntimeAuthorization): boolean {
+  const ref = getAuthorizationRef(authorization)
+  return (
+    ref.type === "disabled" ||
+    (ref.type === "principal" && ref.principal.type === "user" && ref.credential !== undefined)
+  )
+}
+
 /** Build the immutable child execution owned by one direct or Workflow Agent run. */
 export function createAgentExecutionRecord(input: {
   readonly id: string
   readonly parent: ExecutionRecord
-  readonly agentId: string
+  readonly actorId: string
   readonly runId: string
   readonly principal: Extract<AuthorizablePrincipal, { readonly type: "serviceAccount" }>
 }): CreateExecutionInput {
-  assertAgentPrincipal(input.agentId, input.principal)
+  assertAgentPrincipal(input.actorId, input.principal)
   return {
     id: input.id,
     projectId: input.parent.projectId,
@@ -38,14 +54,48 @@ export function createAgentExecutionRecord(input: {
   }
 }
 
+/** Build an Agent execution that carries its parent's exact durable authority reference. */
+export function createInheritedAgentExecutionRecord(input: {
+  readonly id: string
+  readonly parent: ExecutionRecord
+  readonly runId: string
+}): CreateExecutionInput {
+  const authority = input.parent.authorizationRef
+  if (
+    authority.type !== "disabled" &&
+    !(
+      authority.type === "principal" &&
+      authority.principal.type === "user" &&
+      authority.credential !== undefined
+    )
+  ) {
+    throw new ExecutionStorageError(
+      "invalid_input",
+      `[Sixb] Agent run '${input.runId}' requires inheritable user or auth-disabled authority.`
+    )
+  }
+
+  return {
+    id: input.id,
+    projectId: input.parent.projectId,
+    ...(input.parent.requestedBy === undefined
+      ? {}
+      : { requestedBy: structuredClone(input.parent.requestedBy) }),
+    executor: { type: "agent", runId: input.runId },
+    source: { type: "execution", executionId: input.parent.id },
+    correlationId: input.parent.correlationId,
+    authorizationRef: structuredClone(authority),
+  }
+}
+
 /** Bind a worker to the immutable execution already owned by its durable Agent run. */
 export function bindDurableAgentExecution(
   host: AgentExecutionHost,
   input: {
     readonly execution: ExecutionRecord
-    readonly agentId: string
+    readonly actorId?: string
     readonly runId: string
-    readonly authorization: AuthorizationContext
+    readonly authorization: AgentExecutionAuthorization
   }
 ): Sixb<readonly OntologySource[]> {
   const scope = restoreAgentExecutionScope(input)
@@ -59,9 +109,9 @@ export function bindDurableAgentExecution(
 /** Restore one provider-validated Agent execution with its currently resolved grants. */
 export function restoreAgentExecutionScope(input: {
   readonly execution: ExecutionRecord
-  readonly agentId: string
+  readonly actorId?: string
   readonly runId: string
-  readonly authorization: AuthorizationContext
+  readonly authorization: AgentExecutionAuthorization
 }): ExecutionScope {
   assertAgentExecutionRecord(input)
   const context: ExecutionContext = Object.freeze({
@@ -70,7 +120,11 @@ export function restoreAgentExecutionScope(input: {
     ...(input.execution.requestedBy === undefined
       ? {}
       : { requestedBy: Object.freeze(structuredClone(input.execution.requestedBy)) }),
-    executor: Object.freeze({ type: "agent", agentId: input.agentId, runId: input.runId }),
+    executor: Object.freeze({
+      type: "agent",
+      ...(input.actorId === undefined ? {} : { actorId: input.actorId }),
+      runId: input.runId,
+    }),
     source: Object.freeze(structuredClone(input.execution.source)),
     correlationId: input.execution.correlationId,
   })
@@ -78,10 +132,20 @@ export function restoreAgentExecutionScope(input: {
     execution: context,
     authorization: createAgentRuntimeAuthorization({
       projectId: input.execution.projectId,
-      context: input.authorization,
       executionId: input.execution.id,
-      agentId: input.agentId,
+      ...(input.actorId === undefined ? {} : { actorId: input.actorId }),
       runId: input.runId,
+      authority:
+        input.authorization.type === "principal"
+          ? {
+              type: "principal",
+              context: input.authorization.context,
+              ...(input.execution.authorizationRef.type === "principal" &&
+              input.execution.authorizationRef.credential !== undefined
+                ? { credential: input.execution.authorizationRef.credential }
+                : {}),
+            }
+          : { type: "disabled" },
     }),
   })
 }
@@ -89,35 +153,78 @@ export function restoreAgentExecutionScope(input: {
 /** Validate that a durable record belongs to the exact resolved Agent execution. */
 export function assertAgentExecutionRecord(input: {
   readonly execution: ExecutionRecord
-  readonly agentId: string
+  readonly actorId?: string
   readonly runId: string
-  readonly authorization: AuthorizationContext
+  readonly authorization: AgentExecutionAuthorization
 }): void {
   const authority = input.execution.authorizationRef
   if (
     input.execution.executor.type !== "agent" ||
     input.execution.executor.runId !== input.runId ||
-    input.execution.source.type !== "execution" ||
+    input.execution.source.type !== "execution"
+  ) {
+    invalidAgentExecution(input.execution.id, input.runId)
+  }
+
+  if (
+    input.authorization.type === "disabled" ||
+    input.authorization.context.principal.type === "user"
+  ) {
+    assertInheritedAgentAuthority(input.execution, input.runId, input.authorization)
+    return
+  }
+
+  if (
+    input.authorization.type !== "principal" ||
     authority.type !== "principal" ||
     authority.principal.type !== "serviceAccount" ||
-    input.authorization.principal.type !== "serviceAccount" ||
-    authority.principal.id !== input.authorization.principal.id ||
+    input.authorization.context.principal.type !== "serviceAccount" ||
+    authority.principal.id !== input.authorization.context.principal.id ||
     authority.credential !== undefined
   ) {
     invalidAgentExecution(input.execution.id, input.runId)
   }
-  assertAgentPrincipal(input.agentId, authority.principal)
+  if (input.actorId === undefined) {
+    invalidAgentExecution(input.execution.id, input.runId)
+  }
+  assertAgentPrincipal(input.actorId, authority.principal)
+}
+
+function assertInheritedAgentAuthority(
+  execution: ExecutionRecord,
+  runId: string,
+  authorization: AgentExecutionAuthorization
+): void {
+  const authority = execution.authorizationRef
+  if (authorization.type === "disabled") {
+    if (authority.type !== "disabled") invalidAgentExecution(execution.id, runId)
+    return
+  }
+
+  const principal = authorization.context.principal
+  if (
+    authority.type !== "principal" ||
+    authority.principal.type !== "user" ||
+    principal.type !== "user" ||
+    authority.principal.id !== principal.id ||
+    authority.credential === undefined ||
+    (authority.credential.type === "session"
+      ? authorization.context.sessionId !== authority.credential.id
+      : authorization.context.sessionId !== undefined)
+  ) {
+    invalidAgentExecution(execution.id, runId)
+  }
 }
 
 function assertAgentPrincipal(
-  agentId: string,
+  actorId: string,
   principal: Extract<AuthorizablePrincipal, { readonly type: "serviceAccount" }>
 ): void {
-  const expectedId = agentServiceAccountId(agentId)
+  const expectedId = agentServiceAccountId(actorId)
   if (principal.id !== expectedId) {
     throw new ExecutionStorageError(
       "invalid_input",
-      `[Sixb] Agent '${agentId}' execution authority must reference service account '${expectedId}'.`
+      `[Sixb] Agent '${actorId}' execution authority must reference service account '${expectedId}'.`
     )
   }
 }