@sixb/core 0.1.6 → 0.1.8

package/src/agents/types.ts

@@ -1,11 +1,10 @@
-import type { LanguageModelV4, LanguageModelV4CallOptions } from "@ai-sdk/provider"
 import type { BlobBody, FileRef } from "../blob-storage"
 import type { ConnectorRuntime } from "../connectors"
 import type { JsonPrimitive, JsonValue, ReadonlyJsonValue } from "../json"
 import type { Logger } from "../logging"
+import { type LanguageModelRef, MODEL_REASONING_LEVELS, type ModelReasoning } from "../models"
 import type { InferSchema } from "../ontology/inference"
 import type { Schema } from "../ontology/types"
-import type { GroupDefinition } from "../security"
 
 export type {
   AgentContextEntryInput,
@@ -14,41 +13,30 @@ export type {
   AgentContextPart,
 } from "./context"
 
-export type AgentReasoningLevel = NonNullable<LanguageModelV4CallOptions["reasoning"]>
-
-export const AGENT_REASONING_LEVELS = [
-  "provider-default",
-  "none",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-] as const satisfies readonly AgentReasoningLevel[]
-
-export interface AgentContextConfig {
-  /** Override the provider context-window size inferred by the agent worker. */
-  readonly windowTokens?: number
-  /** Tokens reserved for the next response and compaction work. */
-  readonly reserveTokens?: number
-  /** Approximate recent-message budget retained verbatim after compaction. */
-  readonly keepRecentTokens?: number
+/** Public capability reference used by security grants such as `can.run(agent)`. */
+export interface AgentReference {
+  readonly kind: "agent"
+  readonly usage: AgentUsageReference
 }
 
-/**
- * Loop / stop controls for an agent run.
- *
- * Consumed by the agent worker when it executes a run.
- */
-export interface AgentLoopConfig {
-  readonly stopWhen?: {
-    readonly maxSteps?: number
-  }
-  readonly context?: AgentContextConfig
-  /** Automatic provider prompt caching. Defaults to `auto`; use `off` to opt out. */
-  readonly caching?: "auto" | "off"
+/** Project-wide AI accounting and limit capability, independent of permission to run the Agent. */
+export interface AgentUsageReference {
+  readonly kind: "aiUsage"
+}
+
+/** Public metadata for the project's conversational Agent. */
+export interface AgentDescriptor {
+  readonly name: string
+  readonly model: LanguageModelRef
 }
 
+export type AgentReasoning = ModelReasoning
+
+/** @deprecated Use {@link AgentReasoning}. */
+export type AgentReasoningLevel = AgentReasoning
+
+export const AGENT_REASONING_LEVELS = MODEL_REASONING_LEVELS
+
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
 type JsonifyAgentToolInput<T> = unknown extends T
   ? ReadonlyJsonValue
@@ -73,12 +61,24 @@ export type InferAgentToolInputSchema<TInput extends AgentToolInputSchema> =
         readonly [K in keyof TInput]: JsonifyAgentToolInput<InferSchema<TInput[K]>>
       }>
 
-/** Identifies the agent execution that invoked a tool. */
-export interface AgentToolRunInfo {
-  readonly id: string
-  readonly agentId: string
-  readonly threadId?: string
-}
+/** Identifies the conversational, workflow, or child Agent execution that invoked a tool. */
+export type AgentToolRunInfo =
+  | {
+      readonly kind: "conversation"
+      readonly id: string
+      readonly threadId: string
+    }
+  | {
+      readonly kind: "subagent"
+      readonly id: string
+      readonly parentRunId: string
+    }
+  | {
+      readonly kind: "workflow"
+      readonly id: string
+      readonly workflowId: string
+      readonly stepId: string
+    }
 
 /** Input accepted by the run-scoped artifact publisher exposed to agent tools. */
 export interface AgentToolArtifactPutInput {
@@ -183,45 +183,3 @@ export interface AgentToolInputBuilder<TName extends string> {
 export interface AgentToolDescriptionBuilder<TName extends string> {
   description(description: string): AgentToolInputBuilder<TName>
 }
-
-/**
- * Declarative config accepted by {@link defineAgent}.
- *
- * Every field is a static value. `instructions` is a plain string; widening it to
- * `string | (ctx) => string` later would be backwards-compatible.
- */
-export interface DefineAgentConfig {
-  readonly name: string
-  readonly description?: string
-  readonly model: LanguageModelV4
-  readonly reasoning?: AgentReasoningLevel
-  readonly providerOptions?: LanguageModelV4CallOptions["providerOptions"]
-  readonly instructions: string
-  readonly groups?: readonly GroupDefinition[]
-  /** Reusable tools this agent is explicitly allowed to call. */
-  readonly tools?: readonly AgentToolDefinition[]
-  readonly loop?: AgentLoopConfig
-}
-
-/**
- * Agent definition registered with Sixb.
- *
- * Definitions are safe to export from `agents/` modules; the runtime loads and
- * registers them. The agent worker runs them as streaming turns. The `model` is an
- * AI SDK language model instance and is therefore not serialisable — the worker
- * resolves a definition from its own discovery rather than over the wire.
- */
-export interface AgentDefinition<TId extends string = string> {
-  readonly kind: "agent"
-  readonly id: TId
-  readonly name: string
-  readonly description?: string
-  readonly model: LanguageModelV4
-  readonly reasoning?: AgentReasoningLevel
-  readonly providerOptions?: LanguageModelV4CallOptions["providerOptions"]
-  readonly instructions: string
-  readonly groupIds: readonly string[]
-  /** Selected tool definitions, normalized to an empty array when omitted. */
-  readonly tools: readonly AgentToolDefinition[]
-  readonly loop?: AgentLoopConfig
-}

package/src/agents/validation.ts

@@ -6,18 +6,8 @@ import {
   type ValueType,
   validateSchemaValue,
 } from "../ontology"
-import type { GroupDefinition, SecurityDefinitionCatalog } from "../security"
 import { AgentDefinitionError } from "./errors"
-import {
-  AGENT_REASONING_LEVELS,
-  type AgentContextConfig,
-  type AgentDefinition,
-  type AgentLoopConfig,
-  type AgentReasoningLevel,
-  type AgentToolDefinition,
-  type AgentToolInputSchema,
-  type DefineAgentConfig,
-} from "./types"
+import type { AgentToolDefinition, AgentToolInputSchema } from "./types"
 
 const AGENT_TOOL_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/
 const AGENT_TOOL_PRIMITIVE_SCHEMAS = new Set([
@@ -32,27 +22,13 @@ const AGENT_TOOL_PRIMITIVE_SCHEMAS = new Set([
   "fileRef",
 ])
 
-export const AGENT_RESERVED_TOOL_NAMES = ["bash", "read", "view_file"] as const
-
-export function assertNonEmpty(value: string, field: string): void {
-  if (!value.trim()) {
-    throw new AgentDefinitionError(`[Sixb] Agent ${field} must not be empty.`)
-  }
-}
-
-export function isAgentDefinition(value: unknown): value is AgentDefinition {
-  return (
-    isRecord(value) &&
-    value.kind === "agent" &&
-    typeof value.id === "string" &&
-    typeof value.name === "string" &&
-    typeof value.instructions === "string" &&
-    (value.reasoning === undefined || isAgentReasoningLevel(value.reasoning)) &&
-    (value.providerOptions === undefined || isProviderOptions(value.providerOptions)) &&
-    Array.isArray(value.groupIds) &&
-    isAgentToolDefinitionArray(value.tools)
-  )
-}
+export const AGENT_RESERVED_TOOL_NAMES = [
+  "bash",
+  "read",
+  "view_file",
+  "spawn_agent",
+  "wait_agent",
+] as const
 
 export function isAgentToolDefinition(value: unknown): value is AgentToolDefinition {
   return (
@@ -143,174 +119,6 @@ export function validateAndNormalizeAgentToolInput(
   )
 }
 
-/** Revalidate and lock tool definitions supplied directly to the runtime. */
-export function validateAgentToolsAtStartup(agents: readonly AgentDefinition[]): void {
-  for (const agent of agents) {
-    if (!isAgentDefinition(agent)) {
-      throw new AgentDefinitionError("[Sixb] Agents must contain only valid agent definitions.")
-    }
-
-    assertValidAgentToolDefinitions(agent.id, agent.tools)
-    for (const tool of agent.tools) {
-      deepFreeze(tool.input)
-      Object.freeze(tool)
-    }
-    Object.freeze(agent.tools)
-    Object.freeze(agent)
-  }
-}
-
-export function resolveAgentLoopConfig(
-  loop: AgentLoopConfig | undefined
-): AgentLoopConfig | undefined {
-  if (loop === undefined) return undefined
-
-  const maxSteps = loop?.stopWhen?.maxSteps
-  if (maxSteps !== undefined && (!Number.isSafeInteger(maxSteps) || maxSteps <= 0)) {
-    throw new AgentDefinitionError(
-      "[Sixb] Agent loop.stopWhen.maxSteps must be a positive safe integer."
-    )
-  }
-  if (loop.caching !== undefined && loop.caching !== "auto" && loop.caching !== "off") {
-    throw new AgentDefinitionError("[Sixb] Agent loop.caching must be 'auto' or 'off'.")
-  }
-
-  const context = loop.context ? snapshotAgentContextConfig(loop.context) : undefined
-  return Object.freeze({
-    ...(loop.stopWhen === undefined
-      ? {}
-      : { stopWhen: Object.freeze({ ...(maxSteps === undefined ? {} : { maxSteps }) }) }),
-    ...(context === undefined ? {} : { context }),
-    ...(loop.caching === undefined ? {} : { caching: loop.caching }),
-  })
-}
-
-function snapshotAgentContextConfig(context: AgentContextConfig): AgentContextConfig {
-  const snapshot: Record<string, number> = {}
-  for (const field of ["windowTokens", "reserveTokens", "keepRecentTokens"] as const) {
-    const value = context[field]
-    if (value === undefined) continue
-    assertPositiveSafeInteger(value, field)
-    snapshot[field] = value
-  }
-
-  return Object.freeze(snapshot)
-}
-
-function assertPositiveSafeInteger(value: unknown, field: string): asserts value is number {
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
-    throw new AgentDefinitionError(
-      `[Sixb] Agent loop.context.${field} must be a positive safe integer.`
-    )
-  }
-}
-
-export function assertValidReasoningLevel(reasoning: AgentReasoningLevel | undefined): void {
-  if (reasoning === undefined) {
-    return
-  }
-  if (!isAgentReasoningLevel(reasoning)) {
-    throw new AgentDefinitionError(
-      `[Sixb] Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}.`
-    )
-  }
-}
-
-export function assertValidProviderOptions(
-  providerOptions: DefineAgentConfig["providerOptions"]
-): void {
-  if (providerOptions === undefined) {
-    return
-  }
-
-  const reason = getInvalidJsonValueReason(providerOptions, "providerOptions")
-  if (!isRecord(providerOptions) || reason) {
-    throw new AgentDefinitionError(
-      `[Sixb] Agent providerOptions must be a provider-keyed JSON object${reason ? `; ${reason}` : "."}`
-    )
-  }
-
-  for (const [provider, options] of Object.entries(providerOptions)) {
-    if (!provider.trim()) {
-      throw new AgentDefinitionError(
-        "[Sixb] Agent providerOptions provider names must not be empty."
-      )
-    }
-    const optionsReason = getInvalidJsonValueReason(options, `providerOptions.${provider}`)
-    if (!isRecord(options) || optionsReason) {
-      throw new AgentDefinitionError(
-        `[Sixb] Agent providerOptions.${provider} must be a JSON object${optionsReason ? `; ${optionsReason}` : "."}`
-      )
-    }
-  }
-}
-
-export function groupIdsFromDefinitions(
-  agentId: string,
-  groups: readonly GroupDefinition[] | undefined
-): readonly string[] {
-  const groupIds = (groups ?? []).map((group) => {
-    if (!isRecord(group) || group.kind !== "group") {
-      throw new AgentDefinitionError(
-        `[Sixb] Agent '${agentId}' groups must contain only group definitions.`
-      )
-    }
-
-    assertNonEmpty(group.id, `Agent '${agentId}' group id`)
-    return group.id
-  })
-
-  assertNoDuplicateGroupIds(agentId, groupIds)
-  return Object.freeze(groupIds)
-}
-
-export function validateAgentGroupReferences(
-  agents: readonly AgentDefinition[],
-  security: SecurityDefinitionCatalog
-): void {
-  for (const agent of agents) {
-    assertNoDuplicateGroupIds(agent.id, agent.groupIds)
-    for (const groupId of agent.groupIds) {
-      if (!security.getGroupById(groupId)) {
-        throw new AgentDefinitionError(
-          `[Sixb] Agent '${agent.id}' groups references unknown group '${groupId}'. Add it to 'security/groups/' or pass it to createSixb({ groups }).`
-        )
-      }
-    }
-  }
-}
-
-function assertNoDuplicateGroupIds(agentId: string, groupIds: readonly string[]): void {
-  const seen = new Set<string>()
-  for (const groupId of groupIds) {
-    assertNonEmpty(groupId, `Agent '${agentId}' group id`)
-    if (seen.has(groupId)) {
-      throw new AgentDefinitionError(
-        `[Sixb] Agent '${agentId}' groups contains duplicate group id '${groupId}'.`
-      )
-    }
-    seen.add(groupId)
-  }
-}
-
-function isAgentReasoningLevel(value: unknown): value is AgentReasoningLevel {
-  return typeof value === "string" && (AGENT_REASONING_LEVELS as readonly string[]).includes(value)
-}
-
-function isProviderOptions(
-  value: unknown
-): value is NonNullable<DefineAgentConfig["providerOptions"]> {
-  if (!isRecord(value) || getInvalidJsonValueReason(value) !== undefined) {
-    return false
-  }
-  return Object.entries(value).every(
-    ([provider, options]) =>
-      provider.trim().length > 0 &&
-      isRecord(options) &&
-      getInvalidJsonValueReason(options) === undefined
-  )
-}
-
 function assertValidAgentToolSchema(
   toolName: string,
   schema: unknown,
@@ -391,20 +199,7 @@ function invalidAgentToolSchema(toolName: string, path: string): AgentDefinition
   )
 }
 
-function isAgentToolDefinitionArray(value: unknown): value is readonly AgentToolDefinition[] {
-  if (!Array.isArray(value)) {
-    return false
-  }
-  for (let index = 0; index < value.length; index += 1) {
-    if (!Object.hasOwn(value, index) || !isAgentToolDefinition(value[index])) {
-      return false
-    }
-  }
-  return true
-}
-
-export function assertValidAgentToolDefinitions(
-  agentId: string,
+export function assertValidProjectAgentToolDefinitions(
   tools: readonly AgentToolDefinition[]
 ): void {
   const seen = new Set<string>()
@@ -412,7 +207,7 @@ export function assertValidAgentToolDefinitions(
     const tool = tools[index]
     if (!Object.hasOwn(tools, index) || !isAgentToolDefinition(tool)) {
       throw new AgentDefinitionError(
-        `[Sixb] Agent '${agentId}' tools must contain only agent tool definitions.`
+        "[Sixb] Project tools must contain only agent tool definitions."
       )
     }
 
@@ -421,7 +216,7 @@ export function assertValidAgentToolDefinitions(
     assertValidAgentToolInput(tool.name, tool.input)
     if (seen.has(tool.name)) {
       throw new AgentDefinitionError(
-        `[Sixb] Agent '${agentId}' tools contains duplicate tool name '${tool.name}'.`
+        `[Sixb] Project tools contain duplicate tool name '${tool.name}'.`
       )
     }
     seen.add(tool.name)

package/src/ai-usage/execution.ts

@@ -0,0 +1,189 @@
+import { randomUUID } from "node:crypto"
+import { assertAuthorized, isRuntimeAllowed } from "../authorization"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { SecurityDefinitionCatalog } from "../security"
+import type {
+  AiAccountingOverview,
+  AiLimitPolicy,
+  AiLimitPolicyStatus,
+  CreateAiLimitPolicyInput,
+  ListAiLimitPoliciesInput,
+  ListAiLimitPolicyStatusesInput,
+  ListAiModelCallAccountingInput,
+  ListAiModelCallAccountingResult,
+  ListAiModelCallGroupsInput,
+  ListAiModelCallGroupsResult,
+  QueryAiAccountingOverviewInput,
+  ServiceAccountStatus,
+  UpdateAiLimitPolicyInput,
+  UserStatus,
+} from "../storage"
+
+export type QueryAiUsageOverviewInput = Omit<QueryAiAccountingOverviewInput, "projectId">
+export type ListAiUsageModelCallsInput = Omit<ListAiModelCallAccountingInput, "projectId">
+export type ListAiUsageModelCallGroupsInput = Omit<ListAiModelCallGroupsInput, "projectId">
+export type ListAiUsageLimitPoliciesInput = Omit<ListAiLimitPoliciesInput, "projectId">
+export type ListAiUsageLimitStatusesInput = Omit<
+  ListAiLimitPolicyStatusesInput,
+  "projectId" | "existingGroupIds" | "at"
+>
+export type CreateAiUsageLimitPolicyInput = Omit<
+  CreateAiLimitPolicyInput,
+  "id" | "projectId" | "createdAt"
+> & { readonly id?: string }
+export type UpdateAiUsageLimitPolicyInput = Omit<
+  UpdateAiLimitPolicyInput,
+  "projectId" | "updatedAt"
+>
+
+export interface AiUsageLimitGroupOption {
+  readonly id: string
+  readonly label?: string
+  readonly description?: string
+}
+
+export interface AiUsageLimitUserOption {
+  readonly id: string
+  readonly email: string
+  readonly displayName?: string
+  readonly status: UserStatus
+}
+
+export interface AiUsageLimitServiceAccountOption {
+  readonly id: string
+  readonly name: string
+  readonly description?: string
+  readonly status: ServiceAccountStatus
+}
+
+export interface AiUsageLimitSubjectOptions {
+  readonly groups: readonly AiUsageLimitGroupOption[]
+  readonly users: readonly AiUsageLimitUserOption[]
+  readonly serviceAccounts: readonly AiUsageLimitServiceAccountOption[]
+}
+
+/** Project AI accounting and limit controls bound to one execution's authority. */
+export interface AiUsageRuntime {
+  readonly accountingConfigured: boolean
+  readonly limitsConfigured: boolean
+  assertObservable(): void
+  assertManageable(): void
+  canManageLimits(): boolean
+  queryOverview(input: QueryAiUsageOverviewInput): Promise<AiAccountingOverview>
+  listModelCalls(input: ListAiUsageModelCallsInput): Promise<ListAiModelCallAccountingResult>
+  listModelCallGroups(input: ListAiUsageModelCallGroupsInput): Promise<ListAiModelCallGroupsResult>
+  listLimitPolicies(input?: ListAiUsageLimitPoliciesInput): Promise<readonly AiLimitPolicy[]>
+  listLimitStatuses(input?: ListAiUsageLimitStatusesInput): Promise<readonly AiLimitPolicyStatus[]>
+  listLimitSubjectOptions(): Promise<AiUsageLimitSubjectOptions>
+  createLimitPolicy(input: CreateAiUsageLimitPolicyInput): Promise<AiLimitPolicy>
+  updateLimitPolicy(input: UpdateAiUsageLimitPolicyInput): Promise<AiLimitPolicy>
+  deleteLimitPolicy(id: string): Promise<boolean>
+}
+
+export function createAiUsageRuntime(
+  runtime: SixbRuntimeContext,
+  security: SecurityDefinitionCatalog
+): AiUsageRuntime {
+  const assertObservable = () => assertAuthorized(runtime, { kind: "aiUsage.observe" })
+  const assertManageable = () => assertAuthorized(runtime, { kind: "aiUsage.manage" })
+  const assertPolicyReadable = () => {
+    if (
+      !isRuntimeAllowed(runtime, { kind: "aiUsage.observe" }) &&
+      !isRuntimeAllowed(runtime, { kind: "aiUsage.manage" })
+    ) {
+      assertObservable()
+    }
+  }
+  const requireCosts = () => {
+    if (!runtime.storage.aiCosts) {
+      throw new Error("[Sixb] AI cost storage is not configured.")
+    }
+    return runtime.storage.aiCosts
+  }
+  const requireLimits = () => {
+    if (!runtime.storage.aiLimits) {
+      throw new Error("[Sixb] AI limit storage is not configured.")
+    }
+    return runtime.storage.aiLimits
+  }
+
+  return {
+    accountingConfigured: runtime.storage.aiCosts !== undefined,
+    limitsConfigured: runtime.storage.aiLimits !== undefined,
+    assertObservable,
+    assertManageable,
+    canManageLimits: () => isRuntimeAllowed(runtime, { kind: "aiUsage.manage" }),
+    queryOverview: (input) => {
+      assertObservable()
+      return requireCosts().queryProjectOverview({ ...input, projectId: runtime.projectId })
+    },
+    listModelCalls: (input) => {
+      assertObservable()
+      return requireCosts().listModelCalls({ ...input, projectId: runtime.projectId })
+    },
+    listModelCallGroups: (input) => {
+      assertObservable()
+      return requireCosts().listModelCallGroups({ ...input, projectId: runtime.projectId })
+    },
+    listLimitPolicies: (input = {}) => {
+      assertPolicyReadable()
+      return requireLimits().listPolicies({ ...input, projectId: runtime.projectId })
+    },
+    listLimitStatuses: (input = {}) => {
+      assertObservable()
+      return requireLimits().listPolicyStatuses({
+        ...(input.includeDisabled === undefined ? {} : { includeDisabled: input.includeDisabled }),
+        projectId: runtime.projectId,
+        existingGroupIds: security.listGroups().map((group) => group.id),
+      })
+    },
+    listLimitSubjectOptions: async () => {
+      assertManageable()
+      const groups = security.listGroups().map((group) => ({
+        id: group.id,
+        ...(group.label === undefined ? {} : { label: group.label }),
+        ...(group.description === undefined ? {} : { description: group.description }),
+      }))
+      const auth = runtime.storage.auth
+      if (!auth) return { groups, users: [], serviceAccounts: [] }
+
+      const [users, serviceAccounts] = await Promise.all([
+        auth.users.list({ projectId: runtime.projectId, order: "asc" }),
+        auth.serviceAccounts.list({ projectId: runtime.projectId, order: "asc" }),
+      ])
+      return {
+        groups,
+        users: users.users.map((user) => ({
+          id: user.id,
+          email: user.email,
+          ...(user.displayName === undefined ? {} : { displayName: user.displayName }),
+          status: user.status,
+        })),
+        serviceAccounts: serviceAccounts.serviceAccounts.map((serviceAccount) => ({
+          id: serviceAccount.id,
+          name: serviceAccount.name,
+          ...(serviceAccount.description === undefined
+            ? {}
+            : { description: serviceAccount.description }),
+          status: serviceAccount.status,
+        })),
+      }
+    },
+    createLimitPolicy: (input) => {
+      assertManageable()
+      return requireLimits().createPolicy({
+        ...input,
+        id: input.id ?? `ailim_${randomUUID()}`,
+        projectId: runtime.projectId,
+      })
+    },
+    updateLimitPolicy: (input) => {
+      assertManageable()
+      return requireLimits().updatePolicy({ ...input, projectId: runtime.projectId })
+    },
+    deleteLimitPolicy: (id) => {
+      assertManageable()
+      return requireLimits().deletePolicy({ id, projectId: runtime.projectId })
+    },
+  }
+}

package/src/ai-usage/index.ts

@@ -0,0 +1,15 @@
+export type {
+  AiUsageLimitGroupOption,
+  AiUsageLimitServiceAccountOption,
+  AiUsageLimitSubjectOptions,
+  AiUsageLimitUserOption,
+  AiUsageRuntime,
+  CreateAiUsageLimitPolicyInput,
+  ListAiUsageLimitPoliciesInput,
+  ListAiUsageLimitStatusesInput,
+  ListAiUsageModelCallGroupsInput,
+  ListAiUsageModelCallsInput,
+  QueryAiUsageOverviewInput,
+  UpdateAiUsageLimitPolicyInput,
+} from "./execution"
+export { createAiUsageRuntime } from "./execution"