@sixb/core 0.1.0 → 0.1.2

package/src/actions/run-dispatch.ts

@@ -0,0 +1,276 @@
+import { randomUUID } from "node:crypto"
+import { reportRunFailure } from "../error-reporting/capability"
+import { createSixbError, toSixbFailure } from "../errors/internal"
+import type { DomainEventLog } from "../events"
+import type { Queues } from "../queues"
+import type {
+  ActionRunFailure,
+  ActionRunParams,
+  ActionRunRecord,
+  CreateExecutionInput,
+  Storage,
+} from "../storage"
+import {
+  ACTION_RUN_FAILURE_CODES,
+  ActionRunError,
+  actionRunParamsEqual,
+  actionSubjectsEqual,
+} from "../storage"
+import { parseActionRunFailure } from "../storage/action-runs/failure"
+import type { RequestActionResult } from "./request"
+import { createActionRunId, createActionRunIdempotencyKey } from "./run-id"
+import type { ActionSubject } from "./types"
+
+interface DispatchActionRunInput {
+  readonly errorReporterHost: object
+  readonly projectId: string
+  readonly storage: Storage
+  readonly queue: Queues["actions"]
+  readonly events: DomainEventLog
+  readonly actionId: string
+  readonly subject: ActionSubject
+  readonly params: ActionRunParams
+  readonly runId?: string
+  readonly createExecution: (executionId: string, runId: string) => Promise<CreateExecutionInput>
+}
+
+interface PreparedActionRun {
+  readonly runId: string
+  readonly idempotencyKey: string
+}
+
+type PersistedActionRun =
+  | { readonly publish: false; readonly run: ActionRunRecord }
+  | {
+      readonly publish: true
+      readonly run: ActionRunRecord
+      readonly execution: CreateExecutionInput
+      readonly queuedAt: Date
+      readonly created: boolean
+    }
+
+/** Persist an Action execution and run before publishing its queue job. */
+export async function dispatchActionRun(
+  input: DispatchActionRunInput
+): Promise<RequestActionResult> {
+  const request = prepareActionRun(input)
+  const persisted = await persistActionRun(input, request)
+  if (!persisted.publish) return existingActionRunResult(persisted.run)
+  return publishActionRun(input, persisted)
+}
+
+function prepareActionRun(input: DispatchActionRunInput): PreparedActionRun {
+  const runId = createActionRunId(input.runId)
+  return {
+    runId,
+    idempotencyKey: createActionRunIdempotencyKey(input.projectId, runId),
+  }
+}
+
+async function persistActionRun(
+  input: DispatchActionRunInput,
+  request: PreparedActionRun
+): Promise<PersistedActionRun> {
+  const actionRuns = requireActionRunStorage(input.storage)
+  const existing = await actionRuns.getById({ projectId: input.projectId, id: request.runId })
+  if (existing) return reuseActionRun(input, existing)
+
+  const execution = await input.createExecution(`exec_${randomUUID()}`, request.runId)
+  const queuedAt = new Date()
+  try {
+    return await input.storage.transaction(
+      async (tx): Promise<PersistedActionRun> => {
+        const transactionalRuns = requireActionRunStorage(tx)
+        const raced = await transactionalRuns.getById({
+          projectId: input.projectId,
+          id: request.runId,
+        })
+        if (raced) {
+          assertExistingRunMatchesRequest(raced, input)
+          return { publish: false, run: raced }
+        }
+
+        await tx.executions.create(execution)
+        const run = await transactionalRuns.queue({
+          projectId: input.projectId,
+          id: request.runId,
+          executionId: execution.id,
+          actionId: input.actionId,
+          subject: input.subject,
+          params: input.params,
+          idempotencyKey: request.idempotencyKey,
+          queuedAt,
+        })
+        return { publish: true, run, execution, queuedAt, created: true }
+      },
+      { isolation: "serializable" }
+    )
+  } catch (error) {
+    if (!(error instanceof ActionRunError)) throw error
+    const raced = await actionRuns.getById({ projectId: input.projectId, id: request.runId })
+    if (!raced) throw error
+    assertExistingRunMatchesRequest(raced, input)
+    return { publish: false, run: raced }
+  }
+}
+
+async function reuseActionRun(
+  input: DispatchActionRunInput,
+  existing: ActionRunRecord
+): Promise<PersistedActionRun> {
+  assertExistingRunMatchesRequest(existing, input)
+  if (!isRetryableEnqueueFailure(existing)) return { publish: false, run: existing }
+
+  const execution = await input.storage.executions.getById({
+    projectId: input.projectId,
+    id: existing.executionId,
+  })
+  if (!execution) {
+    throw new ActionRunError(
+      `[Sixb] Execution '${existing.executionId}' for Action run '${existing.id}' was not found.`
+    )
+  }
+
+  const queuedAt = new Date()
+  const run = await requireActionRunStorage(input.storage).queue({
+    projectId: input.projectId,
+    id: existing.id,
+    executionId: existing.executionId,
+    actionId: existing.actionId,
+    subject: existing.subject,
+    params: existing.params,
+    idempotencyKey: existing.idempotencyKey,
+    queuedAt,
+  })
+  return { publish: true, run, execution, queuedAt, created: false }
+}
+
+async function publishActionRun(
+  input: DispatchActionRunInput,
+  persisted: Extract<PersistedActionRun, { readonly publish: true }>
+): Promise<RequestActionResult> {
+  let job: Awaited<ReturnType<Queues["actions"]["enqueue"]>>[number] | undefined
+  try {
+    const jobs = await input.queue.enqueue({
+      projectId: input.projectId,
+      jobs: [
+        {
+          id: persisted.run.id,
+          type: "action.run.requested",
+          payload: {
+            runId: persisted.run.id,
+          },
+        },
+      ],
+    })
+    job = jobs[0]
+  } catch (error) {
+    await failActionRunPublication(input, persisted.run, error)
+    throw error
+  }
+
+  await input.events.emit(
+    {
+      events: [
+        {
+          type: "action.requested",
+          payload: {
+            actionId: persisted.run.actionId,
+            subject: persisted.run.subject,
+            params: persisted.run.params,
+            runId: persisted.run.id,
+          },
+        },
+      ],
+      correlationId: persisted.execution.correlationId,
+    },
+    { source: "Sixb" }
+  )
+
+  return {
+    runId: persisted.run.id,
+    queuedAt: persisted.queuedAt.toISOString(),
+    ...(job?.id ? { jobId: job.id } : {}),
+    created: persisted.created,
+  }
+}
+
+async function failActionRunPublication(
+  input: DispatchActionRunInput,
+  run: ActionRunRecord,
+  error: unknown
+): Promise<void> {
+  const failedAt = new Date()
+  const failure = toActionRunFailure(error, run, failedAt)
+  await requireActionRunStorage(input.storage).finish({
+    projectId: input.projectId,
+    id: run.id,
+    status: "failed",
+    finishedAt: failedAt,
+    error: failure,
+  })
+  reportRunFailure(input.errorReporterHost, error, {
+    projectId: input.projectId,
+    runKind: "action",
+    run: { runId: run.id, actionId: run.actionId },
+    failure,
+  })
+}
+
+function requireActionRunStorage(storage: Storage): NonNullable<Storage["actionRuns"]> {
+  if (!storage.actionRuns) {
+    throw new ActionRunError("[Sixb] Action run storage is not configured.")
+  }
+  return storage.actionRuns
+}
+
+function assertExistingRunMatchesRequest(
+  existing: ActionRunRecord,
+  request: Pick<DispatchActionRunInput, "actionId" | "subject" | "params">
+): void {
+  if (
+    existing.actionId !== request.actionId ||
+    !actionSubjectsEqual(existing.subject, request.subject) ||
+    !actionRunParamsEqual(existing.params, request.params)
+  ) {
+    throw new ActionRunError(
+      `[Sixb] Action run '${existing.id}' already exists with a different request payload.`
+    )
+  }
+}
+
+function isRetryableEnqueueFailure(record: ActionRunRecord): boolean {
+  return (
+    record.status === "failed" && record.phase === "enqueue" && record.error?.retryable === true
+  )
+}
+
+function existingActionRunResult(existing: ActionRunRecord): RequestActionResult {
+  return {
+    runId: existing.id,
+    queuedAt: existing.queuedAt.toISOString(),
+    created: false,
+  }
+}
+
+function toActionRunFailure(
+  error: unknown,
+  run: ActionRunRecord,
+  at: Date
+): ActionRunFailure<"enqueue"> {
+  const enqueueError = createSixbError(
+    "queue.enqueue_failed",
+    `[Sixb] Could not enqueue Action run '${run.id}'.`,
+    {
+      cause: error,
+      details: { actionId: run.actionId, runId: run.id, phase: "enqueue" },
+    }
+  )
+  return parseActionRunFailure(
+    toSixbFailure(enqueueError, {
+      allowedCodes: ACTION_RUN_FAILURE_CODES,
+      at,
+    }),
+    "enqueue"
+  )
+}

package/src/actions/types/context.ts

@@ -1,5 +1,5 @@
 import type { BlobStorage } from "../../blob-storage"
-import type { ConnectorAdapter, ConnectorClient, ConnectorDefinition } from "../../connectors"
+import type { ConnectorRuntime } from "../../connectors"
 import type { RecordEditsContext } from "../../edits"
 import type { Logger } from "../../logging"
 import type {
@@ -129,12 +129,10 @@ export interface ActionRuntimeFacade<
   TValueTypes extends readonly ValueType[] = readonly ValueType[],
 > {
   readonly blobs: ActionBlobContext
+  readonly connector: ConnectorRuntime
   objects<const TObjectType extends ObjectTypeWithPropertyTokens>(
     objectType: TObjectType
   ): ActionTelemetryObjectSet<TObjectType, TValueTypes>
-  connector<TAdapter extends ConnectorAdapter>(
-    definition: ConnectorDefinition<string, TAdapter>
-  ): Promise<ConnectorClient<TAdapter>>
 }
 
 /**

package/src/actions/validation.ts

@@ -20,7 +20,7 @@ interface ActionValidationRuntime {
     resolveObjectType(objectTypeId: string): ObjectTypeWithPropertyTokens
   }
   readonly actionRegistry: {
-    getActionsForType(objectType: ObjectTypeWithPropertyTokens): readonly ObjectActionDefinition[]
+    listForType(objectType: ObjectTypeWithPropertyTokens): readonly ObjectActionDefinition[]
   }
 }
 
@@ -164,7 +164,7 @@ function actionAppliesToObjectType(
   objectType: ObjectTypeWithPropertyTokens
 ): boolean {
   return runtime.actionRegistry
-    .getActionsForType(objectType)
+    .listForType(objectType)
     .some((candidate) => candidate.id === action.id)
 }
 

package/src/agents/adapters.ts

@@ -1,5 +1,5 @@
 import { type FileRef, isFileRef } from "../blob-storage"
-import { getInvalidJsonValueReason, type JsonValue } from "../json"
+import { getInvalidJsonValueReason, isPlainRecord, type JsonValue } from "../json"
 import {
   type AgentContextEntryInput,
   type AgentContextInput,
@@ -210,7 +210,11 @@ function optionalJson(value: unknown, label: string): JsonValue | undefined {
  * and every other non-JSON shape are left for `requireJson` to accept or reject. This helper only
  * turns `{ key: undefined }` into `{}` for metadata compatibility with SDK output.
  */
-function omitUndefinedObjectProperties(value: unknown, seen = new Set<object>()): unknown {
+export function omitUndefinedObjectProperties(value: unknown): unknown {
+  return omitUndefinedObjectPropertiesInternal(value, new Set())
+}
+
+function omitUndefinedObjectPropertiesInternal(value: unknown, seen: Set<object>): unknown {
   if (typeof value !== "object" || value === null) return value
 
   // Avoid recursing forever on a malformed/cyclic metadata object. Leaving the cycle in place lets
@@ -220,7 +224,7 @@ function omitUndefinedObjectProperties(value: unknown, seen = new Set<object>())
   seen.add(value)
   try {
     if (Array.isArray(value)) {
-      return value.map((entry) => omitUndefinedObjectProperties(entry, seen))
+      return value.map((entry) => omitUndefinedObjectPropertiesInternal(entry, seen))
     }
 
     if (!isPlainRecord(value)) return value
@@ -228,21 +232,13 @@ function omitUndefinedObjectProperties(value: unknown, seen = new Set<object>())
     return Object.fromEntries(
       Object.entries(value)
         .filter(([, entry]) => entry !== undefined)
-        .map(([key, entry]) => [key, omitUndefinedObjectProperties(entry, seen)])
+        .map(([key, entry]) => [key, omitUndefinedObjectPropertiesInternal(entry, seen)])
     )
   } finally {
     seen.delete(value)
   }
 }
 
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return false
-  }
-  const prototype = Object.getPrototypeOf(value)
-  return prototype === Object.prototype || prototype === null
-}
-
 function isToolType(type: string): boolean {
   return type === "dynamic-tool" || type.startsWith(TOOL_TYPE_PREFIX)
 }

package/src/agents/authority.ts

@@ -0,0 +1,189 @@
+import { SYSTEM_PRINCIPAL } from "../auth"
+import type { AuthorizationContext } from "../authorization"
+import { resolveAuthorizationContext } from "../authorization"
+import type { AuthorizablePrincipal, AuthorizationRef } from "../execution"
+import type { SecurityDefinitionCatalog } from "../security"
+import type {
+  AuthStorage,
+  ServiceAccountGroupMembershipRecord,
+  ServiceAccountRecord,
+} from "../storage/auth"
+import { AuthStorageError } from "../storage/auth"
+import type { AgentDefinition } from "./types"
+
+export interface AgentExecutionIdentity {
+  readonly serviceAccount: ServiceAccountRecord
+  readonly principal: Extract<AuthorizablePrincipal, { readonly type: "serviceAccount" }>
+  readonly groupMemberships: readonly ServiceAccountGroupMembershipRecord[]
+}
+
+export function agentServiceAccountId(agentId: string): string {
+  return `svc_agent_${agentId}`
+}
+
+/** Ensure the definition-owned service account exists before an Agent execution is admitted. */
+export async function ensureAgentExecutionIdentity(input: {
+  readonly auth: AuthStorage | undefined
+  readonly projectId: string
+  readonly agent: AgentDefinition
+}): 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 now = new Date()
+  const loaded = await loadOrCreateAgentServiceAccount(auth, {
+    id,
+    projectId: input.projectId,
+    name,
+    description,
+    updatedAt: now,
+  })
+  assertActiveAgentServiceAccount(input.agent.id, loaded)
+  const serviceAccount = await updateAgentServiceAccountMetadata(auth, {
+    existing: loaded,
+    name,
+    description,
+    updatedAt: now,
+  })
+  assertActiveAgentServiceAccount(input.agent.id, serviceAccount)
+
+  const groupMemberships = await auth.serviceAccountGroupMemberships.reconcileForServiceAccount({
+    projectId: input.projectId,
+    serviceAccountId: id,
+    groupIds: input.agent.groupIds,
+    source: "agent",
+    updatedAt: now,
+  })
+
+  return {
+    serviceAccount,
+    principal: { type: "serviceAccount", id },
+    groupMemberships,
+  }
+}
+
+/** Load the managed identity, recovering only the expected concurrent-create race. */
+async function loadOrCreateAgentServiceAccount(
+  auth: AuthStorage,
+  input: {
+    readonly id: string
+    readonly projectId: string
+    readonly name: string
+    readonly description: string
+    readonly updatedAt: Date
+  }
+): Promise<ServiceAccountRecord> {
+  const existing = await auth.serviceAccounts.getById({
+    projectId: input.projectId,
+    id: input.id,
+  })
+  if (existing) return existing
+
+  try {
+    return await auth.serviceAccounts.create({
+      id: input.id,
+      projectId: input.projectId,
+      name: input.name,
+      description: input.description,
+      status: "active",
+      createdByPrincipal: SYSTEM_PRINCIPAL,
+      createdAt: input.updatedAt,
+      updatedAt: input.updatedAt,
+    })
+  } catch (error) {
+    if (!(error instanceof AuthStorageError) || error.code !== "duplicate_service_account") {
+      throw error
+    }
+    const concurrent = await auth.serviceAccounts.getById({
+      projectId: input.projectId,
+      id: input.id,
+    })
+    if (!concurrent) throw error
+    return concurrent
+  }
+}
+
+function assertActiveAgentServiceAccount(
+  agentId: string,
+  serviceAccount: ServiceAccountRecord
+): void {
+  if (serviceAccount.status === "suspended") {
+    throw new Error(
+      `[Sixb] Agent '${agentId}' service account '${serviceAccount.id}' is suspended.`
+    )
+  }
+}
+
+/** 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 authorizationRef: AuthorizationRef
+  readonly security: SecurityDefinitionCatalog
+}): Promise<{ readonly identity: AgentExecutionIdentity; readonly context: AuthorizationContext }> {
+  const auth = requireAuthStorage(input.auth)
+  const expectedId = agentServiceAccountId(input.agentId)
+  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}'.`
+    )
+  }
+
+  const serviceAccount = await auth.serviceAccounts.getById({
+    projectId: input.projectId,
+    id: principal.id,
+  })
+  if (!serviceAccount || serviceAccount.status !== "active") {
+    throw new Error(`[Sixb] Agent service account '${principal.id}' is not active.`)
+  }
+
+  const groupMemberships = await auth.serviceAccountGroupMemberships.listForServiceAccount({
+    projectId: input.projectId,
+    serviceAccountId: principal.id,
+  })
+  const identity: AgentExecutionIdentity = {
+    serviceAccount,
+    principal: { type: "serviceAccount", id: principal.id },
+    groupMemberships,
+  }
+  return {
+    identity,
+    context: resolveAuthorizationContext({
+      principal: identity.principal,
+      groupIds: groupMemberships.map((membership) => membership.groupId),
+      roles: input.security.listResolvedRoles(),
+    }),
+  }
+}
+
+function requireAuthStorage(auth: AuthStorage | undefined): AuthStorage {
+  if (!auth) {
+    throw new Error("[Sixb] Agent executions require auth storage.")
+  }
+  return auth
+}
+
+async function updateAgentServiceAccountMetadata(
+  auth: AuthStorage,
+  input: {
+    readonly existing: ServiceAccountRecord
+    readonly name: string
+    readonly description: string
+    readonly updatedAt: Date
+  }
+): Promise<ServiceAccountRecord> {
+  if (input.existing.name === input.name && input.existing.description === input.description) {
+    return input.existing
+  }
+  return auth.serviceAccounts.update({
+    projectId: input.existing.projectId,
+    id: input.existing.id,
+    name: input.name,
+    description: input.description,
+    updatedAt: input.updatedAt,
+  })
+}

package/src/agents/builders.ts

@@ -1,13 +1,61 @@
 import { AgentDefinitionError } from "./errors"
-import type { AgentDefinition, DefineAgentConfig } from "./types"
+import { createAgentToolDefinition, toolsFromDefinitions } from "./tool-definition"
+import type {
+  AgentDefinition,
+  AgentToolDefinition,
+  AgentToolDescriptionBuilder,
+  AgentToolHandler,
+  AgentToolInputBuilder,
+  AgentToolInputSchema,
+  AgentToolRunBuilder,
+  DefineAgentConfig,
+  InferAgentToolInputSchema,
+} from "./types"
 import {
   assertNonEmpty,
+  assertValidAgentToolDescription,
+  assertValidAgentToolInput,
+  assertValidAgentToolName,
   assertValidLoopConfig,
   assertValidProviderOptions,
   assertValidReasoningLevel,
   groupIdsFromDefinitions,
 } from "./validation"
 
+/**
+ * Define a reusable tool that can be selected explicitly by one or more agents.
+ *
+ * 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.
+ */
+export function defineAgentTool<const TName extends string>(
+  name: TName
+): AgentToolDescriptionBuilder<TName> {
+  assertValidAgentToolName(name)
+
+  return {
+    description(description: string): AgentToolInputBuilder<TName> {
+      assertValidAgentToolDescription(name, description)
+
+      return {
+        input<const TInput extends AgentToolInputSchema>(
+          input: TInput
+        ): AgentToolRunBuilder<TName, TInput> {
+          assertValidAgentToolInput(name, input)
+
+          return {
+            run(
+              handler: AgentToolHandler<InferAgentToolInputSchema<TInput>>
+            ): AgentToolDefinition<TName, TInput> {
+              return createAgentToolDefinition({ name, description, input, handler })
+            },
+          }
+        },
+      }
+    },
+  }
+}
+
 /**
  * Define an agent: a conversational, looping actor auto-discovered from `agents/`.
  *
@@ -30,8 +78,9 @@ export function defineAgent<const TId extends string>(
   assertValidProviderOptions(config.providerOptions)
   assertValidLoopConfig(config.loop)
   const groupIds = groupIdsFromDefinitions(id, config.groups)
+  const tools = toolsFromDefinitions(id, config.tools)
 
-  return {
+  return Object.freeze({
     kind: "agent",
     id,
     name: config.name,
@@ -40,7 +89,8 @@ export function defineAgent<const TId extends string>(
     ...(config.providerOptions !== undefined ? { providerOptions: config.providerOptions } : {}),
     instructions: config.instructions,
     groupIds,
+    tools,
     ...(config.description !== undefined ? { description: config.description } : {}),
     ...(config.loop !== undefined ? { loop: config.loop } : {}),
-  }
+  })
 }

package/src/agents/dispatch.ts

@@ -72,12 +72,7 @@ export async function dispatchQueuedAgentRuns(
       jobs: queued.map((run) => ({
         id: agentRunQueueJobId(run.id),
         type: "agent.run.requested" as const,
-        payload: {
-          agentId: run.agentId,
-          threadId: run.threadId,
-          runId: run.id,
-          triggerMessageId: run.triggerMessageId,
-        },
+        payload: { runId: run.id },
       })),
     })
     const jobsById = new Map(jobs.map((job) => [job.id, job]))

package/src/agents/errors.ts

@@ -16,8 +16,32 @@ export class AgentMessageAdapterError extends Error {
   readonly name = "AgentMessageAdapterError"
 }
 
+/**
+ * An agent-tool failure whose message is intentionally safe to expose to the model and persist in
+ * the durable trace. Tool authors must keep the message free of credentials and internal details;
+ * unknown errors remain masked by the worker.
+ */
+export class AgentToolPublicError extends Error {
+  readonly name: string = "AgentToolPublicError"
+}
+
+/** Raised when an agent tool result cannot cross the durable JSON message boundary. */
+export class AgentToolResultValidationError extends Error {
+  readonly name = "AgentToolResultValidationError"
+
+  constructor(
+    readonly toolName: string,
+    readonly reason: string,
+    options?: ErrorOptions
+  ) {
+    super(`[Sixb] Agent tool '${toolName}' result must be a JSON value; ${reason}.`, options)
+  }
+}
+
 export type AgentRequestErrorCode =
   | "agent_not_found"
+  | "run_not_found"
+  | "run_not_retryable"
   | "thread_not_found"
   | "thread_agent_mismatch"
   | "active_run_exists"