@sixb/core 0.1.5 → 0.1.7

package/src/agents/authority.ts

@@ -1,15 +1,32 @@
-import { SYSTEM_PRINCIPAL } from "../auth"
+import { principalsEqual, SYSTEM_PRINCIPAL } from "../auth"
 import type { AuthorizationContext } from "../authorization"
 import { resolveAuthorizationContext } from "../authorization"
+import { createSixbError } from "../errors/internal"
 import type { AuthorizablePrincipal, AuthorizationRef } from "../execution"
 import type { SecurityDefinitionCatalog } from "../security"
 import type {
+  AccessTokenRecord,
   AuthStorage,
   ServiceAccountGroupMembershipRecord,
   ServiceAccountRecord,
+  SessionRecord,
+  UserRecord,
 } from "../storage/auth"
 import { AuthStorageError } from "../storage/auth"
-import type { AgentDefinition } from "./types"
+
+export type AgentExecutionAuthorization =
+  | { readonly type: "principal"; readonly context: AuthorizationContext }
+  | { readonly type: "disabled" }
+
+type UserCredentialRef = NonNullable<
+  Extract<AuthorizationRef, { readonly type: "principal" }>["credential"]
+>
+
+interface CredentialedUserAuthorizationRef {
+  readonly type: "principal"
+  readonly principal: Extract<AuthorizablePrincipal, { readonly type: "user" }>
+  readonly credential: UserCredentialRef
+}
 
 export interface AgentExecutionIdentity {
   readonly serviceAccount: ServiceAccountRecord
@@ -17,44 +34,49 @@ export interface AgentExecutionIdentity {
   readonly groupMemberships: readonly ServiceAccountGroupMembershipRecord[]
 }
 
-export function agentServiceAccountId(agentId: string): string {
-  return `svc_agent_${agentId}`
+export function agentServiceAccountId(actorId: string): string {
+  return `svc_agent_${actorId}`
 }
 
-/** Ensure the definition-owned service account exists before an Agent execution is admitted. */
-export async function ensureAgentExecutionIdentity(input: {
+/** Ensure a framework-managed Agent actor exists with exactly its declared group memberships. */
+export async function ensureManagedAgentExecutionIdentity(input: {
   readonly auth: AuthStorage | undefined
   readonly projectId: string
-  readonly agent: AgentDefinition
+  readonly actorId: string
+  readonly name: string
+  readonly description: string
+  readonly groupIds: readonly string[]
 }): Promise<AgentExecutionIdentity> {
   const auth = requireAuthStorage(input.auth)
-  const id = agentServiceAccountId(input.agent.id)
-  const name = input.agent.name
-  const description = `Managed service account for agent '${input.agent.id}'.`
+  const id = agentServiceAccountId(input.actorId)
   const now = new Date()
   const loaded = await loadOrCreateAgentServiceAccount(auth, {
     id,
     projectId: input.projectId,
-    name,
-    description,
+    name: input.name,
+    description: input.description,
     updatedAt: now,
   })
-  assertActiveAgentServiceAccount(input.agent.id, loaded)
+  assertFrameworkManagedAgentServiceAccount(input.actorId, loaded)
+  assertActiveAgentServiceAccount(input.actorId, loaded)
   const serviceAccount = await updateAgentServiceAccountMetadata(auth, {
     existing: loaded,
-    name,
-    description,
+    name: input.name,
+    description: input.description,
     updatedAt: now,
   })
-  assertActiveAgentServiceAccount(input.agent.id, serviceAccount)
+  assertActiveAgentServiceAccount(input.actorId, serviceAccount)
 
-  const groupMemberships = await auth.serviceAccountGroupMemberships.reconcileForServiceAccount({
-    projectId: input.projectId,
-    serviceAccountId: id,
-    groupIds: input.agent.groupIds,
-    source: "agent",
-    updatedAt: now,
-  })
+  const groupMemberships = requireDefinitionOwnedGroupMemberships(
+    input.actorId,
+    await auth.serviceAccountGroupMemberships.reconcileForServiceAccount({
+      projectId: input.projectId,
+      serviceAccountId: id,
+      groupIds: input.groupIds,
+      source: "agent",
+      updatedAt: now,
+    })
+  )
 
   return {
     serviceAccount,
@@ -105,31 +127,64 @@ async function loadOrCreateAgentServiceAccount(
 }
 
 function assertActiveAgentServiceAccount(
-  agentId: string,
+  actorId: string,
   serviceAccount: ServiceAccountRecord
 ): void {
   if (serviceAccount.status === "suspended") {
     throw new Error(
-      `[Sixb] Agent '${agentId}' service account '${serviceAccount.id}' is suspended.`
+      `[Sixb] Agent '${actorId}' service account '${serviceAccount.id}' is suspended.`
+    )
+  }
+}
+
+function assertFrameworkManagedAgentServiceAccount(
+  actorId: string,
+  serviceAccount: ServiceAccountRecord
+): void {
+  if (
+    serviceAccount.createdByPrincipal === undefined ||
+    !principalsEqual(serviceAccount.createdByPrincipal, SYSTEM_PRINCIPAL)
+  ) {
+    throw createSixbError(
+      "agent.execution_failed",
+      `[Sixb] Agent '${actorId}' cannot use service account '${serviceAccount.id}' because it is not managed by Sixb.`,
+      { details: { actorId, serviceAccountId: serviceAccount.id } }
     )
   }
 }
 
+function requireDefinitionOwnedGroupMemberships(
+  actorId: string,
+  memberships: readonly ServiceAccountGroupMembershipRecord[]
+): readonly ServiceAccountGroupMembershipRecord[] {
+  const externalGroupIds = memberships
+    .filter((membership) => membership.source !== "agent")
+    .map((membership) => membership.groupId)
+  if (externalGroupIds.length > 0) {
+    throw createSixbError(
+      "agent.execution_failed",
+      `[Sixb] Agent '${actorId}' service account has group memberships not managed by its definition: ${externalGroupIds.join(", ")}.`,
+      { details: { actorId, externalGroupIds } }
+    )
+  }
+  return memberships
+}
+
 /** Resolve current grants for the service account referenced by a durable Agent execution. */
 export async function resolveAgentExecutionAuthorization(input: {
   readonly auth: AuthStorage | undefined
   readonly projectId: string
-  readonly agentId: string
+  readonly actorId: string
   readonly authorizationRef: AuthorizationRef
   readonly security: SecurityDefinitionCatalog
 }): Promise<{ readonly identity: AgentExecutionIdentity; readonly context: AuthorizationContext }> {
   const auth = requireAuthStorage(input.auth)
-  const expectedId = agentServiceAccountId(input.agentId)
+  const expectedId = agentServiceAccountId(input.actorId)
   const principal =
     input.authorizationRef.type === "principal" ? input.authorizationRef.principal : null
   if (principal?.type !== "serviceAccount" || principal.id !== expectedId) {
     throw new Error(
-      `[Sixb] Agent '${input.agentId}' execution authority must reference service account '${expectedId}'.`
+      `[Sixb] Agent '${input.actorId}' execution authority must reference service account '${expectedId}'.`
     )
   }
 
@@ -140,11 +195,15 @@ export async function resolveAgentExecutionAuthorization(input: {
   if (!serviceAccount || serviceAccount.status !== "active") {
     throw new Error(`[Sixb] Agent service account '${principal.id}' is not active.`)
   }
+  assertFrameworkManagedAgentServiceAccount(input.actorId, serviceAccount)
 
-  const groupMemberships = await auth.serviceAccountGroupMemberships.listForServiceAccount({
-    projectId: input.projectId,
-    serviceAccountId: principal.id,
-  })
+  const groupMemberships = requireDefinitionOwnedGroupMemberships(
+    input.actorId,
+    await auth.serviceAccountGroupMemberships.listForServiceAccount({
+      projectId: input.projectId,
+      serviceAccountId: principal.id,
+    })
+  )
   const identity: AgentExecutionIdentity = {
     serviceAccount,
     principal: { type: "serviceAccount", id: principal.id },
@@ -160,6 +219,129 @@ export async function resolveAgentExecutionAuthorization(input: {
   }
 }
 
+/** Revalidate the durable user authority inherited by a conversational or child Agent. */
+export async function resolveInheritedAgentExecutionAuthorization(input: {
+  readonly auth: AuthStorage | undefined
+  readonly projectId: string
+  readonly authorizationRef: AuthorizationRef
+  readonly security: SecurityDefinitionCatalog
+  readonly now?: Date
+}): Promise<AgentExecutionAuthorization> {
+  if (input.authorizationRef.type === "disabled") return { type: "disabled" }
+
+  const ref = requireCredentialedUserAuthority(input.authorizationRef)
+  const auth = requireAuthStorage(input.auth)
+  const now = input.now ?? new Date()
+  const user = await requireActiveUser(auth, input.projectId, ref.principal.id)
+  const memberships = await auth.groupMemberships.listForUser({
+    projectId: input.projectId,
+    userId: user.id,
+  })
+  const credential = await revalidateUserCredential({
+    auth,
+    projectId: input.projectId,
+    userId: user.id,
+    credential: ref.credential,
+    currentGroupIds: memberships.map((membership) => membership.groupId),
+    now,
+  })
+
+  return {
+    type: "principal",
+    context: resolveAuthorizationContext({
+      principal: ref.principal,
+      groupIds: credential.groupIds,
+      roles: input.security.listResolvedRoles(),
+      ...(credential.sessionId === undefined ? {} : { sessionId: credential.sessionId }),
+    }),
+  }
+}
+
+function requireCredentialedUserAuthority(ref: AuthorizationRef): CredentialedUserAuthorizationRef {
+  if (ref.type !== "principal" || ref.principal.type !== "user" || ref.credential === undefined) {
+    throw invalidInheritedAuthority("the durable reference is not a credentialed user")
+  }
+  return {
+    type: "principal",
+    principal: { type: "user", id: ref.principal.id },
+    credential: { type: ref.credential.type, id: ref.credential.id },
+  }
+}
+
+async function requireActiveUser(
+  auth: AuthStorage,
+  projectId: string,
+  userId: string
+): Promise<UserRecord> {
+  const user = await auth.users.getById({ projectId, id: userId })
+  if (!user || user.status !== "active") {
+    throw invalidInheritedAuthority(`user '${userId}' is not active`)
+  }
+  return user
+}
+
+async function revalidateUserCredential(input: {
+  readonly auth: AuthStorage
+  readonly projectId: string
+  readonly userId: string
+  readonly credential: UserCredentialRef
+  readonly currentGroupIds: readonly string[]
+  readonly now: Date
+}): Promise<{ readonly groupIds: readonly string[]; readonly sessionId?: string }> {
+  if (input.credential.type === "session") {
+    const session = await input.auth.sessions.getById({
+      projectId: input.projectId,
+      id: input.credential.id,
+    })
+    if (!isUsableUserSession(session, input.userId, input.now)) {
+      throw invalidInheritedAuthority("the inherited session is no longer valid")
+    }
+    return { groupIds: input.currentGroupIds, sessionId: session.id }
+  }
+
+  const accessToken = await input.auth.accessTokens.getById({
+    projectId: input.projectId,
+    id: input.credential.id,
+  })
+  if (!isUsableUserAccessToken(accessToken, input.userId, input.now)) {
+    throw invalidInheritedAuthority("the inherited access token is no longer valid")
+  }
+  if (accessToken.groupIds === undefined) return { groupIds: input.currentGroupIds }
+
+  const allowedGroupIds = new Set(accessToken.groupIds)
+  return {
+    groupIds: input.currentGroupIds.filter((groupId) => allowedGroupIds.has(groupId)),
+  }
+}
+
+function isUsableUserSession(
+  session: SessionRecord | null,
+  userId: string,
+  now: Date
+): session is SessionRecord {
+  if (!session || session.userId !== userId || session.revokedAt !== undefined) return false
+  if (session.expiresAt.getTime() <= now.getTime()) return false
+  return (
+    session.absoluteExpiresAt === undefined || session.absoluteExpiresAt.getTime() > now.getTime()
+  )
+}
+
+function isUsableUserAccessToken(
+  token: AccessTokenRecord | null,
+  userId: string,
+  now: Date
+): token is AccessTokenRecord {
+  if (!token || token.subjectType !== "user" || token.subjectId !== userId) return false
+  return token.revokedAt === undefined && token.expiresAt.getTime() > now.getTime()
+}
+
+function invalidInheritedAuthority(reason: string): Error {
+  return createSixbError(
+    "agent.execution_failed",
+    `[Sixb] The Agent execution cannot restore its inherited authority: ${reason}.`
+  )
+}
+
 function requireAuthStorage(auth: AuthStorage | undefined): AuthStorage {
   if (!auth) {
     throw new Error("[Sixb] Agent executions require auth storage.")

package/src/agents/builders.ts

@@ -1,32 +1,24 @@
-import { AgentDefinitionError } from "./errors"
-import { createAgentToolDefinition, toolsFromDefinitions } from "./tool-definition"
+import { createAgentToolDefinition } from "./tool-definition"
 import type {
-  AgentDefinition,
   AgentToolDefinition,
   AgentToolDescriptionBuilder,
   AgentToolHandler,
   AgentToolInputBuilder,
   AgentToolInputSchema,
   AgentToolRunBuilder,
-  DefineAgentConfig,
   InferAgentToolInputSchema,
 } from "./types"
 import {
-  assertNonEmpty,
   assertValidAgentToolDescription,
   assertValidAgentToolInput,
   assertValidAgentToolName,
-  assertValidProviderOptions,
-  assertValidReasoningLevel,
-  groupIdsFromDefinitions,
-  resolveAgentLoopConfig,
 } from "./validation"
 
 /**
- * Define a reusable tool that can be selected explicitly by one or more agents.
+ * Define a reusable tool registered through `createSixb({ tools })`.
  *
  * The returned definition is inert. The agent worker supplies its run-scoped
- * context and executes the handler only when a selected agent calls the tool.
+ * context and executes the handler only when a run calls the tool.
  */
 export function defineAgentTool<const TName extends string>(
   name: TName
@@ -55,42 +47,3 @@ export function defineAgentTool<const TName extends string>(
     },
   }
 }
-
-/**
- * Define an agent: a conversational, looping actor auto-discovered from `agents/`.
- *
- * The returned definition is declarative and can be exported from a project-level
- * `agents/` module. The runtime loads and registers it (`sixb.agents`); the agent
- * worker executes it as a running, streaming agent.
- */
-export function defineAgent<const TId extends string>(
-  id: TId,
-  config: DefineAgentConfig
-): AgentDefinition<TId> {
-  assertNonEmpty(id, "id")
-  assertNonEmpty(config.name, "name")
-  assertNonEmpty(config.instructions, "instructions")
-
-  if (config.model === undefined || config.model === null) {
-    throw new AgentDefinitionError("[Sixb] Agent model is required.")
-  }
-  assertValidReasoningLevel(config.reasoning)
-  assertValidProviderOptions(config.providerOptions)
-  const loop = resolveAgentLoopConfig(config.loop)
-  const groupIds = groupIdsFromDefinitions(id, config.groups)
-  const tools = toolsFromDefinitions(id, config.tools)
-
-  return Object.freeze({
-    kind: "agent",
-    id,
-    name: config.name,
-    model: config.model,
-    ...(config.reasoning !== undefined ? { reasoning: config.reasoning } : {}),
-    ...(config.providerOptions !== undefined ? { providerOptions: config.providerOptions } : {}),
-    instructions: config.instructions,
-    groupIds,
-    tools,
-    ...(config.description !== undefined ? { description: config.description } : {}),
-    ...(loop !== undefined ? { loop } : {}),
-  })
-}

package/src/agents/context-compaction.ts

@@ -147,6 +147,9 @@ function estimateMessageTokens(
       case "context":
         tokens += textTokens(stableJsonStringify(part.context))
         break
+      case "provider-state":
+        tokens += textTokens(stableJsonStringify(part.data))
+        break
       case "tool-call":
         tokens +=
           TOOL_OVERHEAD_TOKENS +
@@ -193,6 +196,7 @@ function serializeSummaryPart(
     case "text":
       return [`${indent}<text>${escapeXml(part.text)}</text>`]
     case "reasoning":
+    case "provider-state":
     case "step-start":
       return []
     case "context":

package/src/agents/dispatch.ts

@@ -1,4 +1,4 @@
-import type { AgentQueueJob, Queue } from "../queues"
+import type { AgentQueueJob, Queue, SubagentQueueJob } from "../queues"
 import type { AgentStorage } from "../storage/agents"
 
 export interface DispatchQueuedAgentRunsInput {
@@ -31,6 +31,10 @@ export function agentRunQueueJobId(runId: string): string {
   return `agt_job_${runId}`
 }
 
+export function subagentRunQueueJobId(runId: string): string {
+  return `agt_child_job_${runId}`
+}
+
 /** Stable queue identity shared by workflow dispatch and agent reconciliation. */
 export function workflowAgentNodeQueueJobId(nodeRunId: string): string {
   return `wfa_job_${nodeRunId}`
@@ -55,13 +59,14 @@ export async function dispatchQueuedAgentRuns(
     : (
         await input.storage.runs.list({
           projectId: input.projectId,
+          kinds: ["conversation"],
           statuses: ["queued"],
           order: "asc",
           limit,
         })
       ).runs
 
-  const queued = runs.filter((run) => run.status === "queued")
+  const queued = runs.filter((run) => run.kind === "conversation" && run.status === "queued")
   if (queued.length === 0) {
     return { scanned: 0, dispatched: [], failures: [] }
   }
@@ -93,6 +98,58 @@ export async function dispatchQueuedAgentRuns(
   }
 }
 
+export async function dispatchQueuedSubagentRuns(input: {
+  readonly projectId: string
+  readonly storage: AgentStorage
+  readonly queue: Queue<SubagentQueueJob>
+  readonly runIds?: readonly string[]
+  readonly limit?: number
+}): Promise<DispatchQueuedAgentRunsResult> {
+  const limit = normalizeLimit(input.limit)
+  const runs = input.runIds
+    ? await input.storage.runs.getByIds({
+        projectId: input.projectId,
+        ids: [...new Set(input.runIds)].slice(0, limit),
+      })
+    : (
+        await input.storage.runs.list({
+          projectId: input.projectId,
+          kinds: ["subagent"],
+          statuses: ["queued"],
+          order: "asc",
+          limit,
+        })
+      ).runs
+  const queued = runs.filter((run) => run.kind === "subagent" && run.status === "queued")
+  if (queued.length === 0) return { scanned: 0, dispatched: [], failures: [] }
+
+  try {
+    const jobs = await input.queue.enqueue({
+      projectId: input.projectId,
+      jobs: queued.map((run) => ({
+        id: subagentRunQueueJobId(run.id),
+        type: "agent.subagent-run.requested" as const,
+        payload: { runId: run.id },
+      })),
+    })
+    const jobsById = new Set(jobs.map((job) => job.id))
+    const dispatched = queued.map((run) => {
+      const jobId = subagentRunQueueJobId(run.id)
+      if (!jobsById.has(jobId)) {
+        throw new Error(`[Sixb] Subagent queue did not return job '${jobId}'.`)
+      }
+      return { runId: run.id, jobId }
+    })
+    return { scanned: queued.length, dispatched, failures: [] }
+  } catch (error) {
+    return {
+      scanned: queued.length,
+      dispatched: [],
+      failures: queued.map((run) => ({ runId: run.id, error })),
+    }
+  }
+}
+
 function normalizeLimit(value: number | undefined): number {
   if (value === undefined) return 100
   if (!Number.isFinite(value) || value < 1) {

package/src/agents/errors.ts

@@ -7,7 +7,7 @@ export class AgentDefinitionError extends Error {
 }
 
 /**
- * Raised by the message adapters. `fromAiSdk` is **total**: rather than silently dropping a part it
+ * Raised by the message adapters. `fromUiMessage` is **total**: rather than silently dropping a part it
  * cannot model, it throws this — which both prevents data loss and pinpoints exactly when the
  * {@link AgentMessage} part union must be extended. It also fires on transient/streaming parts that
  * must never be persisted, and on out-of-contract (non-JSON) payloads.
@@ -39,12 +39,15 @@ export class AgentToolResultValidationError extends Error {
 }
 
 export type AgentRequestErrorCode =
+  | "agent_selector_removed"
   | "agent_not_found"
+  | "model_not_found"
+  | "invalid_model_selection"
   | "run_not_found"
   | "run_not_retryable"
   | "thread_not_found"
-  | "thread_agent_mismatch"
   | "active_run_exists"
+  | "authority_not_inheritable"
   | "invalid_context"
   | "storage_unavailable"