@sixb/core 0.1.1 → 0.1.2

package/src/workers/queue-worker.ts

@@ -1,4 +1,6 @@
-import type { ClaimedQueueJob, Queue, QueueJob, QueueJobError } from "../queues"
+import { captureSixbFailure } from "../errors/internal"
+import type { SixbErrorCode, SixbFailure } from "../errors/types"
+import type { ClaimedQueueJob, Queue, QueueJob } from "../queues"
 import { WorkerAbortError } from "./errors"
 import {
   createQueueDelivery,
@@ -7,34 +9,61 @@ import {
 } from "./queue-delivery"
 import { Worker } from "./worker"
 
-export interface QueueWorkerConfig<TJob extends QueueJob> {
+type QueueWorkerFailureCodes = readonly [
+  "internal.unexpected",
+  "runtime.cancelled",
+  ...SixbErrorCode[],
+]
+
+export interface QueueWorkerConfig<
+  TJob extends QueueJob,
+  TFailureCodes extends QueueWorkerFailureCodes,
+> {
   readonly projectId: string
-  readonly queue: Queue<TJob>
+  readonly queue: Queue<TJob, TFailureCodes[number]>
+  /** Runtime counterpart of this lane's precise terminal-failure union. */
+  readonly failureCodes: TFailureCodes
   readonly workerId: string
   readonly leaseMs?: number
   readonly claimLimit?: number
   readonly idlePollMs?: number
 }
 
-export interface QueueWorkerFailureDecision {
-  readonly kind: "retry" | "fail"
-  readonly availableAt?: string
-}
+/**
+ * Queue settlement selected after execution stops.
+ *
+ * A worker must name its allowed failure-code union before it can supply an already-persisted
+ * failure. Workers that only choose retry vs fail need no generic annotation.
+ */
+export type QueueWorkerFailureDecision<TFailureCode extends SixbErrorCode = never> =
+  | {
+      readonly kind: "retry"
+      readonly availableAt?: string
+    }
+  | {
+      readonly kind: "fail"
+      /** Exact durable run failure, when execution already persisted one. */
+      readonly failure?: SixbFailure<TFailureCode>
+    }
 
 const DEFAULT_LEASE_MS = 15 * 60_000
 const DEFAULT_CLAIM_LIMIT = 1
 const DEFAULT_IDLE_POLL_MS = 1_000
 const MAX_CONSECUTIVE_CLAIM_FAILURES = 5
 
-export abstract class QueueWorker<TJob extends QueueJob> extends Worker {
-  protected readonly config: Required<QueueWorkerConfig<TJob>>
+export abstract class QueueWorker<
+  TJob extends QueueJob,
+  TFailureCodes extends QueueWorkerFailureCodes,
+> extends Worker {
+  protected readonly config: Required<QueueWorkerConfig<TJob, TFailureCodes>>
   private consecutiveClaimFailures = 0
 
-  constructor(config: QueueWorkerConfig<TJob>) {
+  constructor(config: QueueWorkerConfig<TJob, TFailureCodes>) {
     super()
     this.config = {
       projectId: config.projectId,
       queue: config.queue,
+      failureCodes: config.failureCodes,
       workerId: config.workerId,
       leaseMs: config.leaseMs ?? DEFAULT_LEASE_MS,
       claimLimit: config.claimLimit ?? DEFAULT_CLAIM_LIMIT,
@@ -80,20 +109,24 @@ export abstract class QueueWorker<TJob extends QueueJob> extends Worker {
   protected abstract execute(
     claimed: ClaimedQueueJob<TJob>,
     signal: AbortSignal,
-    delivery: QueueDelivery<TJob>
+    delivery: QueueDelivery<TJob, TFailureCodes[number]>
   ): Promise<void>
 
   protected onExecutionError(
     _claimed: ClaimedQueueJob<TJob>,
     _error: unknown
-  ): Promise<QueueWorkerFailureDecision> | QueueWorkerFailureDecision {
+  ):
+    | Promise<QueueWorkerFailureDecision<TFailureCodes[number]>>
+    | QueueWorkerFailureDecision<TFailureCodes[number]> {
     return { kind: "fail" }
   }
 
   protected onAbortError(
     _claimed: ClaimedQueueJob<TJob>,
     _error: unknown
-  ): Promise<QueueWorkerFailureDecision> | QueueWorkerFailureDecision {
+  ):
+    | Promise<QueueWorkerFailureDecision<TFailureCodes[number]>>
+    | QueueWorkerFailureDecision<TFailureCodes[number]> {
     // Shutdown should normally release work for another process. Workers with non-idempotent
     // partial commits can override this and fail the job instead.
     return { kind: "retry" }
@@ -171,7 +204,7 @@ export abstract class QueueWorker<TJob extends QueueJob> extends Worker {
       if (signal.aborted || isAbortError(error)) {
         try {
           const decision = await this.onAbortError(claimed, error)
-          await this.applyFailureDecision(delivery, decision, error)
+          await this.applyFailureDecision(delivery, decision, error, "runtime.cancelled")
         } catch {
           // Shutdown is already in progress. The unacknowledged job becomes visible after its lease.
         }
@@ -180,7 +213,7 @@ export abstract class QueueWorker<TJob extends QueueJob> extends Worker {
 
       try {
         const decision = await this.onExecutionError(claimed, error)
-        await this.applyFailureDecision(delivery, decision, error)
+        await this.applyFailureDecision(delivery, decision, error, "internal.unexpected")
       } catch (settlementError) {
         logQueueOperationError("apply failure decision to", claimed, settlementError)
       }
@@ -190,24 +223,28 @@ export abstract class QueueWorker<TJob extends QueueJob> extends Worker {
   }
 
   private async applyFailureDecision(
-    delivery: QueueDelivery<TJob>,
-    decision: QueueWorkerFailureDecision,
-    error: unknown
+    delivery: QueueDelivery<TJob, TFailureCodes[number]>,
+    decision: QueueWorkerFailureDecision<TFailureCodes[number]>,
+    error: unknown,
+    defaultCode: "internal.unexpected" | "runtime.cancelled"
   ): Promise<void> {
     if (decision.kind === "retry") {
-      await delivery.retry({
-        availableAt: decision.availableAt,
-        error: toQueueJobError(error),
-      })
+      await delivery.retry({ availableAt: decision.availableAt })
       return
     }
 
-    await delivery.fail(toQueueJobError(error))
+    const failure =
+      decision.failure ??
+      captureSixbFailure(error, {
+        allowedCodes: this.config.failureCodes,
+        defaultCode,
+      })
+    await delivery.fail(failure)
   }
 }
 
-async function settleOrLog<TJob extends QueueJob>(
-  delivery: QueueDelivery<TJob>,
+async function settleOrLog<TJob extends QueueJob, TFailureCode extends SixbErrorCode>(
+  delivery: QueueDelivery<TJob, TFailureCode>,
   operation: string,
   settle: () => Promise<QueueSettlementResult>
 ): Promise<void> {
@@ -226,13 +263,6 @@ function logQueueOperationError(operation: string, claimed: ClaimedQueueJob, err
   )
 }
 
-function toQueueJobError(error: unknown): QueueJobError {
-  if (error instanceof Error) {
-    return { name: error.name, message: error.message }
-  }
-  return { message: String(error) }
-}
-
 /** True for a standard abort (`AbortController`/`AbortSignal.timeout`) error. */
 export function isAbortError(error: unknown): boolean {
   return error instanceof Error && error.name === "AbortError"

package/src/workflows/execution.ts

@@ -0,0 +1,292 @@
+import { canViewWorkflowIntervention, canViewWorkflowRun, isAllowed } from "../authorization"
+import type { AuthorizablePrincipal, ExecutionContext } from "../execution"
+import { resolveExecutionUsage } from "../runtime/ai-usage"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { AiModelCallUsage } from "../storage/ai-usage"
+import type {
+  ListWorkflowInterventionsInput,
+  ListWorkflowInterventionsResult,
+  WorkflowInterventionRecord,
+} from "../storage/workflow-interventions"
+import type {
+  ListLatestWorkflowRunsResult,
+  ListWorkflowNodeRunsInput,
+  ListWorkflowNodeRunsResult,
+  ListWorkflowRunsInput,
+  ListWorkflowRunsResult,
+  WorkflowAgentNodeRunRecord,
+  WorkflowNodeRunRecord,
+  WorkflowRunRecord,
+  WorkflowRunStorage,
+} from "../storage/workflow-runs"
+import { WorkflowValidationError } from "./errors"
+import {
+  type RequestWorkflowRunInput,
+  requestWorkflowRun,
+  type WorkflowRunRequestOptions,
+  type WorkflowRunRequestResult,
+} from "./request"
+import type { WorkflowDefinition } from "./types"
+
+export interface WorkflowRunsRuntime {
+  getById(runId: string): Promise<WorkflowRunView | null>
+  list(
+    input?: Omit<ListWorkflowRunsInput, "projectId" | "workflowIds">
+  ): Promise<WorkflowRunListResult>
+  listLatest(workflowIds: readonly string[]): Promise<LatestWorkflowRunListResult>
+  listNodes(
+    runId: string,
+    input?: ListWorkflowRunNodesInput
+  ): Promise<WorkflowNodeRunListResult | null>
+}
+
+/** Execution-facing run view with provenance resolved from the immutable execution ledger. */
+export interface WorkflowRunView extends WorkflowRunRecord {
+  readonly requestedBy?: AuthorizablePrincipal
+}
+
+export interface WorkflowRunListResult extends Omit<ListWorkflowRunsResult, "runs"> {
+  readonly runs: readonly WorkflowRunView[]
+}
+
+export interface LatestWorkflowRunListResult extends Omit<ListLatestWorkflowRunsResult, "runs"> {
+  readonly runs: readonly WorkflowRunView[]
+}
+
+export type ListWorkflowRunNodesInput = Omit<
+  ListWorkflowNodeRunsInput,
+  "projectId" | "workflowRunId" | "workflowId"
+>
+
+/** Execution-facing Agent node view derived from its run row and model-call ledger. */
+export interface WorkflowAgentNodeRunView extends Omit<WorkflowAgentNodeRunRecord, "execution"> {
+  readonly usage?: AiModelCallUsage
+}
+
+/** Execution-facing workflow node view with optional Agent execution details. */
+export interface WorkflowNodeRunView extends WorkflowNodeRunRecord {
+  readonly agentExecution?: WorkflowAgentNodeRunView
+}
+
+export interface WorkflowNodeRunListResult extends Omit<ListWorkflowNodeRunsResult, "nodes"> {
+  readonly nodes: readonly WorkflowNodeRunView[]
+}
+
+export interface WorkflowInterventionsRuntime {
+  getById(interventionId: string): Promise<WorkflowInterventionRecord | null>
+  list(
+    input?: Omit<ListWorkflowInterventionsInput, "projectId" | "workflowIds">
+  ): Promise<ListWorkflowInterventionsResult>
+}
+
+export interface WorkflowsRuntime {
+  list(): readonly WorkflowDefinition[]
+  getById(workflowId: string): WorkflowDefinition | null
+  request(
+    workflow: WorkflowDefinition,
+    options?: WorkflowRunRequestOptions
+  ): Promise<WorkflowRunRequestResult>
+  requestById(input: RequestWorkflowRunInput): Promise<WorkflowRunRequestResult>
+  readonly runs: WorkflowRunsRuntime
+  readonly interventions: WorkflowInterventionsRuntime
+}
+
+export function createWorkflowsRuntime(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  source: Pick<WorkflowsRuntime, "list" | "getById">
+): WorkflowsRuntime {
+  const allowed = (workflowId: string) =>
+    isAllowed(runtime.authorization, { kind: "workflow.run", workflowId })
+  const canAccessHistory = (workflowId: string) =>
+    allowed(workflowId) && (!runtime.authorization || source.getById(workflowId) !== null)
+  const visibleIds = () =>
+    source
+      .list()
+      .filter((workflow) => allowed(workflow.id))
+      .map((workflow) => workflow.id)
+  const getVisibleRunRecord = async (runId: string): Promise<WorkflowRunRecord | null> => {
+    const run =
+      (await runtime.storage.workflowRuns?.getById({
+        projectId: runtime.projectId,
+        id: runId,
+      })) ?? null
+    return run && canViewWorkflowRun(runtime.authorization, run) && canAccessHistory(run.workflowId)
+      ? run
+      : null
+  }
+  const getRun = async (runId: string): Promise<WorkflowRunView | null> => {
+    const run = await getVisibleRunRecord(runId)
+    return run ? attachRequestedBy(runtime, run) : null
+  }
+  const listNodes = async (
+    runId: string,
+    input: ListWorkflowRunNodesInput = {}
+  ): Promise<WorkflowNodeRunListResult | null> => {
+    const storage = runtime.storage.workflowRuns
+    if (!storage || !(await getVisibleRunRecord(runId))) return null
+    const result = await storage.nodes.list({
+      projectId: runtime.projectId,
+      ...input,
+      workflowRunId: runId,
+    })
+    return {
+      ...result,
+      nodes: await attachWorkflowNodeViews(runtime, storage, result.nodes),
+    }
+  }
+
+  return {
+    list: () => source.list().filter((workflow) => allowed(workflow.id)),
+    getById: (workflowId) => {
+      const workflow = source.getById(workflowId)
+      return workflow && allowed(workflowId) ? workflow : null
+    },
+    request: (workflow, options) => requestWorkflowRun(runtime, execution, workflow, options),
+    requestById: async (input) => {
+      const workflow = source.getById(input.workflowId)
+      if (!workflow) {
+        throw new WorkflowValidationError(`[Sixb] Unknown workflow '${input.workflowId}'`)
+      }
+      return requestWorkflowRun(runtime, execution, workflow, input)
+    },
+    runs: {
+      getById: getRun,
+      list: async (input = {}) => {
+        const storage = runtime.storage.workflowRuns
+        if (!storage) return { runs: [], hasMore: false, total: 0 }
+        const result = await storage.list({
+          projectId: runtime.projectId,
+          ...input,
+          workflowIds: runtime.authorization ? visibleIds() : undefined,
+        })
+        return {
+          ...result,
+          runs: await Promise.all(result.runs.map((run) => attachRequestedBy(runtime, run))),
+        }
+      },
+      listLatest: async (workflowIds) => {
+        const storage = runtime.storage.workflowRuns
+        if (!storage || workflowIds.length === 0) return { runs: [] }
+        const allowedIds = workflowIds.filter(canAccessHistory)
+        if (allowedIds.length === 0) return { runs: [] }
+        const result = await storage.listLatestByWorkflowIds({
+          projectId: runtime.projectId,
+          workflowIds: allowedIds,
+        })
+        return {
+          runs: await Promise.all(result.runs.map((run) => attachRequestedBy(runtime, run))),
+        }
+      },
+      listNodes,
+    },
+    interventions: {
+      getById: async (interventionId) => {
+        const intervention =
+          (await runtime.storage.workflowInterventions?.getById({
+            projectId: runtime.projectId,
+            id: interventionId,
+          })) ?? null
+        return intervention &&
+          canViewWorkflowIntervention(runtime.authorization, intervention) &&
+          canAccessHistory(intervention.workflowId)
+          ? intervention
+          : null
+      },
+      list: (input = {}) => {
+        const storage = runtime.storage.workflowInterventions
+        if (!storage) return Promise.resolve({ interventions: [], hasMore: false, total: 0 })
+        return storage.list({
+          projectId: runtime.projectId,
+          ...input,
+          workflowIds: runtime.authorization ? visibleIds() : undefined,
+        })
+      },
+    },
+  }
+}
+
+async function attachWorkflowNodeViews(
+  runtime: SixbRuntimeContext,
+  storage: WorkflowRunStorage,
+  nodes: readonly WorkflowNodeRunRecord[]
+): Promise<readonly WorkflowNodeRunView[]> {
+  const executions = await Promise.all(
+    nodes.map((node) =>
+      node.nodeType === "agent"
+        ? storage.agentNodes.getByNodeRunId({
+            projectId: runtime.projectId,
+            nodeRunId: node.id,
+          })
+        : null
+    )
+  )
+  const agentExecutions = executions.filter(
+    (execution): execution is WorkflowAgentNodeRunRecord => execution !== null
+  )
+  if (agentExecutions.length === 0) return nodes
+
+  const usages = await resolveExecutionUsage({
+    storage: runtime.storage.aiUsage,
+    projectId: runtime.projectId,
+    executionIds: agentExecutions.map((execution) => execution.executionId),
+  })
+  const usageByExecutionId = new Map(
+    agentExecutions.map((execution, index) => [execution.executionId, usages[index]] as const)
+  )
+
+  return nodes.map((node, index) => {
+    const execution = executions[index]
+    if (!execution) return node
+    const usage = usageByExecutionId.get(execution.executionId)
+    return {
+      ...node,
+      agentExecution: toWorkflowAgentNodeRunView(execution, usage),
+    }
+  })
+}
+
+function toWorkflowAgentNodeRunView(
+  execution: WorkflowAgentNodeRunRecord,
+  usage: AiModelCallUsage | undefined
+): WorkflowAgentNodeRunView {
+  return {
+    projectId: execution.projectId,
+    nodeRunId: execution.nodeRunId,
+    executionId: execution.executionId,
+    agentId: execution.agentId,
+    status: execution.status,
+    prompt: execution.prompt,
+    modelId: execution.modelId,
+    finishReason: execution.finishReason,
+    trace: execution.trace,
+    diagnostics: execution.diagnostics,
+    error: execution.error,
+    attempt: execution.attempt,
+    createdAt: execution.createdAt,
+    startedAt: execution.startedAt,
+    completedAt: execution.completedAt,
+    ...(usage === undefined ? {} : { usage }),
+  }
+}
+
+async function attachRequestedBy(
+  runtime: SixbRuntimeContext,
+  run: WorkflowRunRecord
+): Promise<WorkflowRunView> {
+  const execution = await runtime.storage.executions.getById({
+    projectId: runtime.projectId,
+    id: run.executionId,
+  })
+  if (!execution) {
+    throw new Error(
+      `[Sixb] Workflow run '${run.id}' references missing execution '${run.executionId}'.`
+    )
+  }
+  return {
+    ...run,
+    ...(execution.requestedBy === undefined
+      ? {}
+      : { requestedBy: structuredClone(execution.requestedBy) }),
+  }
+}

package/src/workflows/failure.ts

@@ -0,0 +1,63 @@
+import { createSixbError, isSixbError, summarizeErrorMessage } from "../errors/internal"
+
+interface WorkflowNodeFailureIdentityBase {
+  readonly workflowId: string
+  readonly workflowRunId: string
+  readonly nodeId: string
+  readonly nodeRunId?: string
+}
+
+export interface WorkflowNodeFailureIdentity extends WorkflowNodeFailureIdentityBase {
+  readonly child:
+    | { readonly type: "step"; readonly stepId: string }
+    | {
+        readonly type: "action"
+        readonly actionId: string
+        readonly actionRunId?: string
+      }
+    | { readonly type: "agent"; readonly agentId: string }
+    | { readonly type: "intervention"; readonly interventionId: string }
+}
+
+/** Translate a node-local failure into the workflow primitive's durable vocabulary. */
+export function createWorkflowNodeFailure(error: unknown, identity: WorkflowNodeFailureIdentity) {
+  return createSixbError(
+    "workflow.node_failed",
+    summarizeErrorMessage(error, "Workflow node execution failed."),
+    {
+      cause: error,
+      details: workflowNodeFailureDetails(identity),
+    }
+  )
+}
+
+/** Recover the native child error for direct callers and error-monitoring integrations. */
+export function unwrapWorkflowNodeFailure(error: unknown): unknown {
+  return isSixbError(error) && error.code === "workflow.node_failed" && error.cause !== undefined
+    ? error.cause
+    : error
+}
+
+function workflowNodeFailureDetails(identity: WorkflowNodeFailureIdentity) {
+  const base = {
+    workflowId: identity.workflowId,
+    workflowRunId: identity.workflowRunId,
+    nodeId: identity.nodeId,
+    ...(identity.nodeRunId ? { nodeRunId: identity.nodeRunId } : {}),
+  }
+
+  switch (identity.child.type) {
+    case "step":
+      return { ...base, stepId: identity.child.stepId }
+    case "action":
+      return {
+        ...base,
+        actionId: identity.child.actionId,
+        ...(identity.child.actionRunId ? { actionRunId: identity.child.actionRunId } : {}),
+      }
+    case "agent":
+      return { ...base, agentId: identity.child.agentId }
+    case "intervention":
+      return { ...base, interventionId: identity.child.interventionId }
+  }
+}

package/src/workflows/index.ts

@@ -6,13 +6,21 @@ export {
   interventionField,
 } from "./builders"
 export { WorkflowDefinitionError, WorkflowValidationError } from "./errors"
+export type { WorkflowNodeFailureIdentity } from "./failure"
+export { createWorkflowNodeFailure, unwrapWorkflowNodeFailure } from "./failure"
 export type {
   RequestWorkflowRunInput,
   WorkflowRunRequestOptions,
   WorkflowRunRequestResult,
 } from "./request"
 export { requestWorkflowRun } from "./request"
-export { WorkflowsRuntime } from "./runtime"
+export {
+  type AutomaticWorkflowExecutionSource,
+  type AutomaticWorkflowRunDispatchInput,
+  WorkflowRunDispatcher,
+  type WorkflowRunDispatcherDependencies,
+  type WorkflowRunDispatchPort,
+} from "./run-dispatch"
 export {
   snapshotWorkflowActionInput,
   snapshotWorkflowAgentStepInput,
@@ -69,6 +77,7 @@ export type {
   WorkflowMapperContext,
   WorkflowNodeDefinition,
   WorkflowRunSource,
+  WorkflowRuntimeFacade,
   WorkflowScheduleMapper,
   WorkflowScheduleTriggerDefinition,
   WorkflowStepMapper,