@sixb/core 0.1.6 → 0.1.7

package/src/security/types.ts

@@ -86,7 +86,7 @@ export interface ApplyGrant {
   readonly selection: Selection
 }
 
-export type RunGrantTarget = "workflow" | "sync" | "pipeline" | "agent"
+export type RunGrantTarget = "workflow" | "sync" | "pipeline"
 
 export interface RunGrant<TTarget extends RunGrantTarget = RunGrantTarget> {
   readonly kind: "grant"
@@ -95,7 +95,14 @@ export interface RunGrant<TTarget extends RunGrantTarget = RunGrantTarget> {
   readonly selection: Selection
 }
 
-export type ObserveGrantTarget = "logs"
+/** Run the project's single conversational Agent. */
+export interface AgentRunGrant {
+  readonly kind: "grant"
+  readonly capability: "run"
+  readonly target: "agent"
+}
+
+export type ObserveGrantTarget = "logs" | "aiUsage"
 
 export interface ObserveGrant {
   readonly kind: "grant"
@@ -104,10 +111,13 @@ export interface ObserveGrant {
   readonly selection: Selection
 }
 
-/** Manage the OAuth connection lifecycle for selected connector definitions. */
-export interface ManageGrant {
+export type ManageGrantTarget = "connector" | "aiUsage"
+
+/** Manage a selected connector or the project's AI usage-limit policies. */
+export interface ManageGrant<TTarget extends ManageGrantTarget = ManageGrantTarget> {
   readonly kind: "grant"
   readonly capability: "manage"
+  readonly target: TTarget
   readonly selection: Selection
 }
 
@@ -118,6 +128,7 @@ export type GrantDefinition =
   | AppendGrant
   | ApplyGrant
   | RunGrant
+  | AgentRunGrant
   | ObserveGrant
   | ManageGrant
 

package/src/security/validation.ts

@@ -8,10 +8,13 @@ import type {
   MembershipPolicyDefinition,
   RegisteredSecurityDefinitions,
   RoleDefinition,
+  Selection,
 } from "./types"
 
-/** Registered id universes keyed as the grant-kind table expects them. */
-type RegisteredUniverses = Partial<Record<GrantUniverseKey, ReadonlySet<string>>>
+/** Registered id universes and singleton capabilities available to role grants. */
+type RegisteredUniverses = Partial<Record<GrantUniverseKey, ReadonlySet<string>>> & {
+  readonly agentAvailable?: boolean
+}
 
 /**
  * Every grant capability, for validating grants that arrive from untyped code.
@@ -220,12 +223,19 @@ export function assertGrantDefinition(
     )
   }
 
-  if (value.capability === "observe" && value.target !== "logs") {
-    throw createError(`[Sixb] ${field} observe grant target must be 'logs'.`)
+  if (value.capability === "observe" && value.target !== "logs" && value.target !== "aiUsage") {
+    throw createError(`[Sixb] ${field} observe grant target must be 'logs' or 'aiUsage'.`)
+  }
+
+  if (value.capability === "manage" && value.target !== "connector" && value.target !== "aiUsage") {
+    throw createError(`[Sixb] ${field} manage grant target must be 'connector' or 'aiUsage'.`)
   }
 
-  if (value.capability === "manage" && value.target !== undefined) {
-    throw createError(`[Sixb] ${field} manage grant must not declare a target.`)
+  if (value.capability === "run" && value.target === "agent") {
+    if (value.selection !== undefined) {
+      throw createError(`[Sixb] ${field} agent run grant must not declare a selection.`)
+    }
+    return
   }
 
   assertSelection(value.selection, field, createError)
@@ -235,7 +245,7 @@ function assertSelection(
   value: unknown,
   field: string,
   createError: CreateSecurityError
-): asserts value is GrantDefinition["selection"] {
+): asserts value is Selection {
   if (!isRecord(value) || typeof value.all !== "boolean") {
     throw createError(`[Sixb] ${field} grant must carry a selection from 'can' or a scope.`)
   }
@@ -303,10 +313,12 @@ export function validateSecurityDefinitionsAtStartup(input: {
   readonly syncIds?: ReadonlySet<string>
   /** Registered pipeline ids — when provided, pipeline run grants must reference them. */
   readonly pipelineIds?: ReadonlySet<string>
-  /** Registered agent ids — when provided, agent run grants must reference them. */
-  readonly agentIds?: ReadonlySet<string>
+  /** Whether the project's single conversational Agent is configured. */
+  readonly agentAvailable?: boolean
   /** Registered observability surfaces. */
   readonly observableIds?: ReadonlySet<string>
+  /** Registered singleton management surfaces. */
+  readonly manageableIds?: ReadonlySet<string>
   /** Registered connector ids — when provided, manage grants must reference them. */
   readonly connectorIds?: ReadonlySet<string>
 }): RegisteredSecurityDefinitions {
@@ -415,6 +427,15 @@ function assertGrantReferences(
   grant: GrantDefinition,
   registered: RegisteredUniverses
 ): void {
+  if (grant.capability === "run" && grant.target === "agent") {
+    const spec = GRANT_KINDS[grantKindOf(grant)]
+    if (!registered.agentAvailable) {
+      throw new SecurityValidationError(
+        `[Sixb] Role '${roleId}' grants ${grant.capability} on the project Agent, but it is unavailable. ${spec.fix}`
+      )
+    }
+    return
+  }
   const spec = GRANT_KINDS[grantKindOf(grant)]
   const universe = registered[spec.universeKey]
 

package/src/storage/agents/errors.ts

@@ -1,6 +1,7 @@
 export type AgentStorageErrorCode =
   | "thread_not_found"
   | "active_run_exists"
+  | "active_child_limit"
   | "run_not_found"
   | "invalid_input"
   | "invalid_state"

package/src/storage/agents/in-memory.ts

@@ -11,7 +11,11 @@ import {
   assertAgentContextCheckpointAuthority,
   assertAgentContextCheckpointReplayState,
   assertAgentRunExecution,
+  assertConversationAgentRunSpec,
   assertCreateAgentContextCheckpointInput,
+  assertCreateSubagentRunInput,
+  assertSubagentRunResult,
+  subagentRunMatchesCreateInput,
 } from "./provider"
 import type {
   AgentContextCheckpointRecord,
@@ -26,9 +30,11 @@ import type {
   AgentThreadStore,
   AppendAgentMessageInput,
   ConfirmAgentRunExecutionOwnershipInput,
+  ConversationAgentRunRecord,
   CreateAgentContextCheckpointInput,
   CreateAgentRunInput,
   CreateAgentThreadInput,
+  CreateSubagentRunInput,
   DeleteAgentMessagesByRunInput,
   FinishAgentRunInput,
   FinishQueuedAgentRunInput,
@@ -40,6 +46,7 @@ import type {
   ListAgentThreadsResult,
   ReclaimAgentRunInput,
   StartAgentRunInput,
+  SubagentRunRecord,
 } from "./types"
 import { AGENT_RUN_FAILURE_CODES } from "./types"
 
@@ -125,7 +132,6 @@ class InMemoryAgentThreadStore implements AgentThreadStore {
     const record: AgentThreadRecord = {
       id: input.id,
       projectId: input.projectId,
-      agentId: input.agentId,
       ownerPrincipal: clone(input.ownerPrincipal),
       ...(input.title === undefined ? {} : { title: input.title }),
       status: input.status ?? "active",
@@ -147,12 +153,8 @@ class InMemoryAgentThreadStore implements AgentThreadStore {
   async list(input: ListAgentThreadsInput): Promise<ListAgentThreadsResult> {
     const order = input.order ?? "desc"
     const statuses = input.statuses ? new Set(input.statuses) : null
-    const agentIds = input.agentIds ? new Set(input.agentIds) : null
-
     const filtered = [...this.state.threads.values()]
       .filter((thread) => thread.projectId === input.projectId)
-      .filter((thread) => (input.agentId ? thread.agentId === input.agentId : true))
-      .filter((thread) => (agentIds ? agentIds.has(thread.agentId) : true))
       .filter((thread) => (statuses ? statuses.has(thread.status) : true))
       .filter((thread) =>
         input.ownerPrincipal ? principalsEqual(thread.ownerPrincipal, input.ownerPrincipal) : true
@@ -180,13 +182,13 @@ class InMemoryAgentRunStore implements AgentRunStore {
     private readonly executions: ExecutionStorage
   ) {}
 
-  async create(input: CreateAgentRunInput): Promise<AgentRunRecord> {
+  async create(input: CreateAgentRunInput): Promise<ConversationAgentRunRecord> {
+    assertConversationAgentRunSpec(input.spec)
     await assertAgentRunExecution({
       executions: this.executions,
       projectId: input.projectId,
       executionId: input.executionId,
       runId: input.id,
-      agentId: input.agentId,
     })
     // No `await` between read and write: the in-memory critical section is atomic, so two concurrent
     // queued runs on the same thread cannot both win — the second observes `activeRunId` set.
@@ -224,13 +226,14 @@ class InMemoryAgentRunStore implements AgentRunStore {
     }
 
     const createdAt = new Date(input.createdAt ?? new Date())
-    const run: AgentRunRecord = {
+    const run: ConversationAgentRunRecord = {
+      kind: "conversation",
       id: input.id,
       projectId: input.projectId,
       executionId: input.executionId,
       threadId: input.threadId,
-      agentId: input.agentId,
       triggerMessageId: input.triggerMessageId,
+      spec: clone(input.spec),
       requesterGroupIds: normalizeRequesterGroupIds(input.requesterGroupIds),
       status: "queued",
       attempt: 0,
@@ -248,6 +251,94 @@ class InMemoryAgentRunStore implements AgentRunStore {
     return clone(run)
   }
 
+  async createSubagent(input: CreateSubagentRunInput): Promise<SubagentRunRecord> {
+    assertCreateSubagentRunInput(input)
+    const execution = await assertAgentRunExecution({
+      executions: this.executions,
+      projectId: input.projectId,
+      executionId: input.executionId,
+      runId: input.id,
+    })
+
+    const runKey = key(input.projectId, input.id)
+    const existing = this.state.runs.get(runKey)
+    if (existing) {
+      if (subagentRunMatchesCreateInput(existing, input)) return clone(existing)
+      throw new AgentStorageError(
+        "duplicate_id",
+        `[Sixb] Subagent run '${input.id}' already exists with different immutable inputs.`
+      )
+    }
+
+    const parent = this.state.runs.get(key(input.projectId, input.parentRunId))
+    if (!parent || parent.kind !== "conversation") {
+      throw new AgentStorageError(
+        "run_not_found",
+        `[Sixb] Parent Agent run '${input.parentRunId}' was not found.`
+      )
+    }
+    if (parent.status !== "running") {
+      throw new AgentStorageError(
+        "invalid_state",
+        `[Sixb] Parent Agent run '${parent.id}' is not running (status '${parent.status}').`
+      )
+    }
+    if (
+      execution.source.type !== "execution" ||
+      execution.source.executionId !== parent.executionId
+    ) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[Sixb] Subagent execution '${execution.id}' is not a child of parent execution '${parent.executionId}'.`
+      )
+    }
+    if (parent.execution?.token !== input.parentExecutionToken) {
+      throw new AgentStorageError(
+        "execution_lost",
+        `[Sixb] Parent Agent run '${parent.id}' is no longer owned by this execution.`
+      )
+    }
+    const activeChildren = [...this.state.runs.values()].filter(
+      (run) =>
+        run.kind === "subagent" &&
+        run.projectId === input.projectId &&
+        run.parentRunId === parent.id &&
+        (run.status === "queued" || run.status === "running")
+    ).length
+    if (activeChildren >= input.maxActiveChildren) {
+      throw new AgentStorageError(
+        "active_child_limit",
+        `[Sixb] Agent run '${parent.id}' already has ${activeChildren} active subagents.`
+      )
+    }
+    if (
+      [...this.state.runs.values()].some(
+        (run) => run.projectId === input.projectId && run.executionId === input.executionId
+      )
+    ) {
+      throw new AgentStorageError(
+        "duplicate_id",
+        `[Sixb] Execution '${input.executionId}' already belongs to another Agent run.`
+      )
+    }
+
+    const run: SubagentRunRecord = {
+      kind: "subagent",
+      id: input.id,
+      projectId: input.projectId,
+      executionId: input.executionId,
+      parentRunId: input.parentRunId,
+      spawnKey: input.spawnKey,
+      spec: clone(input.spec),
+      requesterGroupIds: clone(parent.requesterGroupIds),
+      status: "queued",
+      attempt: 0,
+      createdAt: new Date(input.createdAt ?? new Date()),
+    }
+    this.state.runs.set(runKey, clone(run))
+    return clone(run)
+  }
+
   async start(input: StartAgentRunInput): Promise<AgentRunRecord> {
     const run = this.requireStatus(input.projectId, input.id, "queued")
     const startedAt = new Date(input.startedAt ?? new Date())
@@ -320,6 +411,15 @@ class InMemoryAgentRunStore implements AgentRunStore {
         `[Sixb] Execution token is no longer current on agent run '${input.id}'.`
       )
     }
+    if (input.status === "succeeded" && run.kind === "subagent") {
+      assertSubagentRunResult(input.result, run.id)
+    }
+    if (input.status === "succeeded" && run.kind === "conversation" && input.result !== undefined) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[Sixb] Conversational Agent run '${run.id}' cannot persist a subagent result.`
+      )
+    }
 
     const completedAt = new Date(input.completedAt ?? new Date())
     const next: AgentRunRecord = {
@@ -328,6 +428,9 @@ class InMemoryAgentRunStore implements AgentRunStore {
       ...(input.modelId === undefined ? {} : { modelId: input.modelId }),
       ...(input.finishReason === undefined ? {} : { finishReason: input.finishReason }),
       ...(input.diagnostics === undefined ? {} : { diagnostics: clone(input.diagnostics) }),
+      ...(input.status === "succeeded" && input.result !== undefined
+        ? { result: clone(input.result) }
+        : {}),
       ...(input.status === "succeeded" || input.error === undefined
         ? {}
         : { error: normalizeFailure(input.error) }),
@@ -359,11 +462,17 @@ class InMemoryAgentRunStore implements AgentRunStore {
   async list(input: ListAgentRunsInput): Promise<ListAgentRunsResult> {
     const order = input.order ?? "desc"
     const statuses = input.statuses ? new Set(input.statuses) : null
+    const kinds = input.kinds ? new Set(input.kinds) : null
 
     const filtered = [...this.state.runs.values()]
       .filter((run) => run.projectId === input.projectId)
-      .filter((run) => (input.threadId ? run.threadId === input.threadId : true))
-      .filter((run) => (input.agentId ? run.agentId === input.agentId : true))
+      .filter((run) => (kinds ? kinds.has(run.kind) : true))
+      .filter((run) =>
+        input.threadId ? run.kind === "conversation" && run.threadId === input.threadId : true
+      )
+      .filter((run) =>
+        input.parentRunId ? run.kind === "subagent" && run.parentRunId === input.parentRunId : true
+      )
       .filter((run) => (statuses ? statuses.has(run.status) : true))
       .filter((run) =>
         input.startedAfter ? (run.startedAt ?? run.createdAt) >= input.startedAfter : true
@@ -405,6 +514,7 @@ class InMemoryAgentRunStore implements AgentRunStore {
   }
 
   private releaseThread(run: AgentRunRecord, completedAt: Date): void {
+    if (run.kind !== "conversation") return
     const threadKey = key(run.projectId, run.threadId)
     const thread = this.state.threads.get(threadKey)
     if (thread && thread.activeRunId === run.id) {

package/src/storage/agents/index.ts

@@ -16,6 +16,7 @@ export type {
   AgentRunExecution,
   AgentRunFailureCode,
   AgentRunFinishReason,
+  AgentRunKind,
   AgentRunRecord,
   AgentRunStatus,
   AgentRunStore,
@@ -25,9 +26,12 @@ export type {
   AgentThreadStore,
   AppendAgentMessageInput,
   ConfirmAgentRunExecutionOwnershipInput,
+  ConversationAgentRunRecord,
+  ConversationAgentRunSpec,
   CreateAgentContextCheckpointInput,
   CreateAgentRunInput,
   CreateAgentThreadInput,
+  CreateSubagentRunInput,
   DeleteAgentMessagesByRunInput,
   FinishAgentRunInput,
   FinishQueuedAgentRunInput,
@@ -39,6 +43,9 @@ export type {
   ListAgentThreadsResult,
   ReclaimAgentRunInput,
   StartAgentRunInput,
+  SubagentRunRecord,
+  SubagentRunResult,
+  SubagentRunSpec,
 } from "./types"
 export {
   AGENT_RUN_DIAGNOSTIC_CODES,

package/src/storage/agents/provider.ts

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