veryfront 0.1.49 → 0.1.51

package/src/src/workflow/dsl/map.ts

@@ -7,6 +7,7 @@ import type {
   WorkflowNode,
 } from "../types.js";
 import { validateNodeId } from "./validation.js";
+import { INVALID_ARGUMENT } from "../../errors/index.js";
 
 export interface MapOptions extends Omit<BaseNodeConfig, "checkpoint"> {
   items: unknown[] | ((context: WorkflowContext) => unknown[] | Promise<unknown[]>);
@@ -21,8 +22,14 @@ export interface MapOptions extends Omit<BaseNodeConfig, "checkpoint"> {
 export function map(id: string, options: MapOptions): WorkflowNode {
   validateNodeId(id);
 
-  if (!options.items) throw new Error(`Map node "${id}" must have 'items' configured`);
-  if (!options.processor) throw new Error(`Map node "${id}" must have a 'processor' configured`);
+  if (!options.items) {
+    throw INVALID_ARGUMENT.create({ detail: `Map node "${id}" must have 'items' configured` });
+  }
+  if (!options.processor) {
+    throw INVALID_ARGUMENT.create({
+      detail: `Map node "${id}" must have a 'processor' configured`,
+    });
+  }
 
   const config: MapNodeConfig = {
     type: "map",

package/src/src/workflow/dsl/parallel.ts

@@ -6,6 +6,7 @@ import type {
   WorkflowNode,
 } from "../types.js";
 import { validateNodeId } from "./validation.js";
+import { INVALID_ARGUMENT } from "../../errors/index.js";
 
 export interface ParallelOptions extends Omit<BaseNodeConfig, "checkpoint"> {
   strategy?: "all" | "race" | "allSettled";
@@ -24,15 +25,17 @@ export function parallel(
   validateNodeId(id);
 
   if (nodes.length === 0) {
-    throw new Error(`Parallel node "${id}" must have at least one child node`);
+    throw INVALID_ARGUMENT.create({
+      detail: `Parallel node "${id}" must have at least one child node`,
+    });
   }
 
   const prefix = `${id}/`;
   const prefixedNodes = nodes.map((node, index) => {
     if (typeof node.id !== "string" || node.id.length === 0) {
-      throw new Error(
-        `Child node at index ${index} in parallel "${id}" has invalid ID`,
-      );
+      throw INVALID_ARGUMENT.create({
+        detail: `Child node at index ${index} in parallel "${id}" has invalid ID`,
+      });
     }
 
     const childId = node.id.startsWith(prefix) ? node.id : `${prefix}${node.id}`;

package/src/src/workflow/dsl/step.ts

@@ -8,6 +8,7 @@ import type {
   WorkflowNode,
 } from "../types.js";
 import { validateNodeId } from "./validation.js";
+import { INVALID_ARGUMENT } from "../../errors/index.js";
 
 export interface StepOptions extends Omit<BaseNodeConfig, "checkpoint"> {
   agent?: string | Agent;
@@ -26,11 +27,13 @@ export function step(id: string, options: StepOptions): WorkflowNode {
   const hasTool = options.tool != null;
 
   if (!hasAgent && !hasTool) {
-    throw new Error(`Step "${id}" must specify either 'agent' or 'tool'`);
+    throw INVALID_ARGUMENT.create({ detail: `Step "${id}" must specify either 'agent' or 'tool'` });
   }
 
   if (hasAgent && hasTool) {
-    throw new Error(`Step "${id}" cannot specify both 'agent' and 'tool'`);
+    throw INVALID_ARGUMENT.create({
+      detail: `Step "${id}" cannot specify both 'agent' and 'tool'`,
+    });
   }
 
   const config: StepNodeConfig = {

package/src/src/workflow/dsl/sub-workflow.ts

@@ -6,6 +6,7 @@ import type {
   WorkflowNode,
 } from "../types.js";
 import { validateNodeId } from "./validation.js";
+import { INVALID_ARGUMENT } from "../../errors/index.js";
 
 export interface SubWorkflowOptions extends BaseNodeConfig {
   workflow: WorkflowDefinition;
@@ -18,7 +19,9 @@ export function subWorkflow(id: string, options: SubWorkflowOptions): WorkflowNo
   validateNodeId(id);
 
   if (!options.workflow) {
-    throw new Error(`SubWorkflow node "${id}" must have a 'workflow' configured`);
+    throw INVALID_ARGUMENT.create({
+      detail: `SubWorkflow node "${id}" must have a 'workflow' configured`,
+    });
   }
 
   const config: SubWorkflowNodeConfig = {

package/src/src/workflow/dsl/validation.ts

@@ -1,6 +1,8 @@
+import { INVALID_ARGUMENT } from "../../errors/index.js";
+
 /** Validate that a node ID is a non-empty string */
 export function validateNodeId(id: string): void {
   if (!id.trim()) {
-    throw new Error("Node ID must be a non-empty string");
+    throw INVALID_ARGUMENT.create({ detail: "Node ID must be a non-empty string" });
   }
 }

package/src/src/workflow/dsl/wait.ts

@@ -1,5 +1,6 @@
 import type { BaseNodeConfig, RetryConfig, WorkflowContext, WorkflowNode } from "../types.js";
 import { validateNodeId } from "./validation.js";
+import { INVALID_ARGUMENT } from "../../errors/index.js";
 
 export interface WaitForApprovalOptions extends Omit<BaseNodeConfig, "checkpoint"> {
   message?: string;
@@ -42,7 +43,7 @@ export function waitForEvent(id: string, options: WaitForEventOptions): Workflow
   validateNodeId(id);
 
   if (!options.eventName) {
-    throw new Error(`waitForEvent "${id}" must specify an eventName`);
+    throw INVALID_ARGUMENT.create({ detail: `waitForEvent "${id}" must specify an eventName` });
   }
 
   return {

package/src/src/workflow/dsl/workflow.ts

@@ -14,6 +14,7 @@ import type {
   WorkflowNode,
 } from "../types.js";
 import { workflowRegistry } from "../registry.js";
+import { INVALID_ARGUMENT } from "../../errors/index.js";
 
 export type { Workflow } from "../types.js";
 
@@ -39,8 +40,10 @@ export interface WorkflowOptions<TInput = unknown, TOutput = unknown> {
 export function workflow<TInput = unknown, TOutput = unknown>(
   options: WorkflowOptions<TInput, TOutput>,
 ): Workflow<TInput, TOutput> {
-  if (!options.id) throw new Error("Workflow must have an 'id'");
-  if (!options.steps) throw new Error(`Workflow "${options.id}" must have 'steps'`);
+  if (!options.id) throw INVALID_ARGUMENT.create({ detail: "Workflow must have an 'id'" });
+  if (!options.steps) {
+    throw INVALID_ARGUMENT.create({ detail: `Workflow "${options.id}" must have 'steps'` });
+  }
 
   const definition: WorkflowDefinition<TInput, TOutput> = {
     id: options.id,
@@ -93,7 +96,7 @@ export function dag(nodes: Record<string, DagNodeInput>): WorkflowNode[] {
     const nodeId = baseNode.id || id;
 
     if (seenIds.has(nodeId)) {
-      throw new Error(`Duplicate node ID detected in dag: "${nodeId}"`);
+      throw INVALID_ARGUMENT.create({ detail: `Duplicate node ID detected in dag: "${nodeId}"` });
     }
 
     seenIds.add(nodeId);

package/src/src/workflow/executor/dag/graph.ts

@@ -1,12 +1,13 @@
 import type { NodeState, WorkflowNode } from "../../types.js";
+import { INVALID_ARGUMENT } from "../../../errors/index.js";
 
-export interface DAGGraph {
+interface DAGGraph {
   adjList: Map<string, string[]>;
   inDegree: Map<string, number>;
   nodeMap: Map<string, WorkflowNode>;
 }
 
-export function hasAnyDependents(nodes: WorkflowNode[], nodeId: string): boolean {
+function hasAnyDependents(nodes: WorkflowNode[], nodeId: string): boolean {
   return nodes.some((n) => n.dependsOn?.includes(nodeId));
 }
 
@@ -25,7 +26,9 @@ export function buildGraph(nodes: WorkflowNode[]): DAGGraph {
     for (const dep of node.dependsOn ?? []) {
       const dependents = adjList.get(dep);
       if (!dependents) {
-        throw new Error(`Node "${node.id}" depends on unknown node "${dep}"`);
+        throw INVALID_ARGUMENT.create({
+          detail: `Node "${node.id}" depends on unknown node "${dep}"`,
+        });
       }
       dependents.push(node.id);
       inDegree.set(node.id, (inDegree.get(node.id) ?? 0) + 1);

package/src/src/workflow/executor/dag/index.ts

@@ -23,6 +23,7 @@ import type {
   WorkflowRun,
 } from "../../types.js";
 import { generateId, parseDuration } from "../../types.js";
+import { INVALID_ARGUMENT, NOT_SUPPORTED } from "../../../errors/index.js";
 
 export type { DAGExecutionResult, DAGExecutorConfig, NodeExecutionResult } from "./types.js";
 
@@ -190,10 +191,11 @@ export class DAGExecutor {
       case "loop":
         return this.executeLoopNode(node, config, context, nodeStates);
       default:
-        throw new Error(
-          `Unknown node type "${(config as WorkflowNodeConfig).type}" for node "${node.id}". ` +
+        throw INVALID_ARGUMENT.create({
+          detail:
+            `Unknown node type "${(config as WorkflowNodeConfig).type}" for node "${node.id}". ` +
             "Valid types are: step, parallel, map, branch, wait, subWorkflow, loop",
-        );
+        });
     }
   }
 
@@ -276,7 +278,7 @@ export class DAGExecutor {
     const items = typeof config.items === "function" ? await config.items(context) : config.items;
 
     if (!Array.isArray(items)) {
-      throw new Error(`Map node "${node.id}" items must be an array`);
+      throw INVALID_ARGUMENT.create({ detail: `Map node "${node.id}" items must be an array` });
     }
 
     if (items.length === 0) {
@@ -463,9 +465,10 @@ export class DAGExecutor {
     const startTime = Date.now();
 
     if (typeof config.workflow === "string") {
-      throw new Error(
-        "Resolving workflow by ID is not yet supported in this execution context. Pass the WorkflowDefinition object.",
-      );
+      throw NOT_SUPPORTED.create({
+        detail:
+          "Resolving workflow by ID is not yet supported in this execution context. Pass the WorkflowDefinition object.",
+      });
     }
 
     const workflowDef = config.workflow;

package/src/src/workflow/executor/dag/utils.ts

@@ -12,5 +12,6 @@ export function shouldCheckpoint(node: WorkflowNode): boolean {
 }
 
 export function sleep(ms: number): Promise<void> {
+  // no cleanup needed: one-shot
   return new Promise((resolve) => dntShim.setTimeout(resolve, ms));
 }

package/src/src/workflow/executor/step-executor.ts

@@ -3,6 +3,14 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import type { Agent, AgentResponse } from "../../agent/index.js";
 import type { Tool } from "../../tool/index.js";
 import { ensureError } from "../../errors/veryfront-error.js";
+import {
+  AGENT_NOT_FOUND,
+  INITIALIZATION_ERROR,
+  INVALID_ARGUMENT,
+  ORCHESTRATION_ERROR,
+  RESOURCE_NOT_FOUND,
+  TIMEOUT_ERROR,
+} from "../../errors/index.js";
 import type {
   CapturedTenantContext,
   NodeState,
@@ -44,14 +52,20 @@ export function runWithWorkflowTenant<T>(
   return workflowTenantStorage.run(tenant, fn);
 }
 
+/** Default initial delay before first retry attempt */
+const DEFAULT_RETRY_INITIAL_DELAY_MS = 1_000;
+
+/** Default maximum delay between retry attempts */
+const DEFAULT_RETRY_MAX_DELAY_MS = 30_000;
+
 const DEFAULT_RETRY: RetryConfig = {
   maxAttempts: 1,
   backoff: "exponential",
-  initialDelay: 1000,
-  maxDelay: 30000,
+  initialDelay: DEFAULT_RETRY_INITIAL_DELAY_MS,
+  maxDelay: DEFAULT_RETRY_MAX_DELAY_MS,
 };
 
-const DEFAULT_STEP_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_STEP_TIMEOUT_MS = 5 * 60 * 1_000;
 
 export interface AgentRegistry {
   get(id: string): Agent | undefined;
@@ -92,10 +106,11 @@ export class StepExecutor {
     const config = node.config as StepNodeConfig;
 
     if (config.type !== "step") {
-      throw new Error(
-        `StepExecutor can only execute 'step' nodes, but node "${node.id}" has type '${config.type}'. ` +
+      throw ORCHESTRATION_ERROR.create({
+        detail:
+          `StepExecutor can only execute 'step' nodes, but node "${node.id}" has type '${config.type}'. ` +
           `This is likely a bug in the DAG executor routing.`,
-      );
+      });
     }
 
     const retryConfig = { ...DEFAULT_RETRY, ...config.retry };
@@ -171,8 +186,8 @@ export class StepExecutor {
   }
 
   private calculateRetryDelay(attempt: number, config: RetryConfig): number {
-    const initialDelay = config.initialDelay ?? 1000;
-    const maxDelay = config.maxDelay ?? 30000;
+    const initialDelay = config.initialDelay ?? DEFAULT_RETRY_INITIAL_DELAY_MS;
+    const maxDelay = config.maxDelay ?? DEFAULT_RETRY_MAX_DELAY_MS;
 
     let baseDelay = initialDelay;
     if (config.backoff === "exponential") baseDelay = initialDelay * Math.pow(2, attempt - 1);
@@ -183,6 +198,7 @@ export class StepExecutor {
   }
 
   private sleep(ms: number): Promise<void> {
+    // no cleanup needed: one-shot
     return new Promise((resolve) => dntShim.setTimeout(resolve, ms));
   }
 
@@ -204,7 +220,7 @@ export class StepExecutor {
 
     const timeoutPromise = new Promise<never>((_, reject) => {
       timeoutId = dntShim.setTimeout(() => {
-        reject(new Error(`Step "${nodeId}" timed out after ${timeout}ms`));
+        reject(TIMEOUT_ERROR.create({ detail: `Step "${nodeId}" timed out after ${timeout}ms` }));
       }, timeout);
     });
 
@@ -222,7 +238,7 @@ export class StepExecutor {
   ): Promise<unknown> {
     if (config.agent) return this.executeAgent(config.agent, input, context);
     if (config.tool) return this.executeTool(config.tool, input);
-    throw new Error("Step must have either 'agent' or 'tool' specified");
+    throw INVALID_ARGUMENT.create({ detail: "Step must have either 'agent' or 'tool' specified" });
   }
 
   private async executeAgent(
@@ -266,7 +282,9 @@ export class StepExecutor {
     const label = type.charAt(0).toUpperCase() + type.slice(1);
 
     if (!registry) {
-      throw new Error(`${label} registry not configured. Cannot resolve ${type} "${id}"`);
+      throw INITIALIZATION_ERROR.create({
+        detail: `${label} registry not configured. Cannot resolve ${type} "${id}"`,
+      });
     }
 
     const item = registry.get(id);
@@ -277,7 +295,10 @@ export class StepExecutor {
       ? this.formatAvailableItems(available)
       : ` No ${type}s are registered.`;
 
-    throw new Error(`${label} not found: "${id}".${suggestion}`);
+    const detail = `${label} not found: "${id}".${suggestion}`;
+    throw (type === "agent"
+      ? AGENT_NOT_FOUND.create({ detail })
+      : RESOURCE_NOT_FOUND.create({ detail }));
   }
 
   private getAgent(id: string): Agent {

package/src/src/workflow/executor/workflow-executor.ts

@@ -8,6 +8,12 @@ import * as dntShim from "../../../_dnt.shims.js";
 
 import { logger as baseLogger } from "../../utils/index.js";
 import { ensureError } from "../../errors/veryfront-error.js";
+import {
+  INVALID_ARGUMENT,
+  ORCHESTRATION_ERROR,
+  RESOURCE_NOT_FOUND,
+  TIMEOUT_ERROR,
+} from "../../errors/index.js";
 import type {
   BlobResolver,
   NodeState,
@@ -28,6 +34,9 @@ import type { BlobStorage } from "../blob/types.js";
 
 const logger = baseLogger.component("workflow-executor");
 
+/** Default polling interval for waiting on workflow result */
+const DEFAULT_RESULT_POLL_INTERVAL_MS = 1_000;
+
 /**
  * Workflow executor configuration
  */
@@ -84,13 +93,14 @@ export class WorkflowExecutor {
   private stepExecutor: StepExecutor;
   private checkpointManager: CheckpointManager;
   private dagExecutor: DAGExecutor;
+  // deno-lint-ignore no-explicit-any -- type-erased registry: register() accepts WorkflowDefinition<TInput, TOutput> with arbitrary type params
   private workflows = new Map<string, WorkflowDefinition<any, any>>();
   private blobResolver?: BlobResolver;
 
   /** Default lock duration: 30 seconds */
-  private static readonly DEFAULT_LOCK_DURATION = 30000;
+  private static readonly DEFAULT_LOCK_DURATION = 30_000;
   /** Heartbeat interval for long-running workflow liveness tracking */
-  private static readonly HEARTBEAT_INTERVAL_MS = 10000;
+  private static readonly HEARTBEAT_INTERVAL_MS = 10_000;
 
   constructor(config: WorkflowExecutorConfig) {
     this.config = {
@@ -152,6 +162,7 @@ export class WorkflowExecutor {
   /**
    * Get a registered workflow
    */
+  // deno-lint-ignore no-explicit-any -- type-erased registry lookup
   getWorkflow(id: string): WorkflowDefinition<any, any> | undefined {
     return this.workflows.get(id);
   }
@@ -165,7 +176,9 @@ export class WorkflowExecutor {
     options?: { runId?: string },
   ): Promise<WorkflowHandle<TOutput>> {
     const workflow = this.workflows.get(workflowId);
-    if (!workflow) throw new Error(`Workflow not found: ${workflowId}`);
+    if (!workflow) {
+      throw RESOURCE_NOT_FOUND.create({ detail: `Workflow not found: ${workflowId}` });
+    }
 
     workflow.inputSchema?.parse(input);
 
@@ -213,26 +226,28 @@ export class WorkflowExecutor {
    */
   async resume(runId: string, fromCheckpoint?: string): Promise<void> {
     const run = await this.config.backend.getRun(runId);
-    if (!run) throw new Error(`Run not found: ${runId}`);
+    if (!run) throw RESOURCE_NOT_FOUND.create({ detail: `Run not found: ${runId}` });
 
     if (run.status !== "waiting" && run.status !== "pending") {
-      throw new Error(
-        `Cannot resume workflow run "${runId}": current status is "${run.status}". ` +
+      throw ORCHESTRATION_ERROR.create({
+        detail: `Cannot resume workflow run "${runId}": current status is "${run.status}". ` +
           `Only runs in "waiting" or "pending" status can be resumed.`,
-      );
+      });
     }
 
     const workflow = this.workflows.get(run.workflowId);
-    if (!workflow) throw new Error(`Workflow not found: ${run.workflowId}`);
+    if (!workflow) {
+      throw RESOURCE_NOT_FOUND.create({ detail: `Workflow not found: ${run.workflowId}` });
+    }
 
     const nodes = this.resolveNodes(workflow, run.context);
     const resumeInfo = await this.checkpointManager.prepareResume(runId, nodes, fromCheckpoint);
 
     if (fromCheckpoint && !resumeInfo) {
-      throw new Error(
-        `Checkpoint "${fromCheckpoint}" not found for run "${runId}". ` +
+      throw RESOURCE_NOT_FOUND.create({
+        detail: `Checkpoint "${fromCheckpoint}" not found for run "${runId}". ` +
           `Cannot resume from non-existent checkpoint.`,
-      );
+      });
     }
 
     if (resumeInfo) {
@@ -254,10 +269,12 @@ export class WorkflowExecutor {
    */
   async executeAsync(runId: string, startFromNode?: string): Promise<void> {
     const run = await this.config.backend.getRun(runId);
-    if (!run) throw new Error(`Run not found: ${runId}`);
+    if (!run) throw RESOURCE_NOT_FOUND.create({ detail: `Run not found: ${runId}` });
 
     const workflow = this.workflows.get(run.workflowId);
-    if (!workflow) throw new Error(`Workflow not found: ${run.workflowId}`);
+    if (!workflow) {
+      throw RESOURCE_NOT_FOUND.create({ detail: `Workflow not found: ${run.workflowId}` });
+    }
 
     const useLocking = this.config.enableLocking !== false && hasLockSupport(this.config.backend);
     const lockDuration = this.config.lockDuration ?? WorkflowExecutor.DEFAULT_LOCK_DURATION;
@@ -267,10 +284,11 @@ export class WorkflowExecutor {
     if (useLocking) {
       const acquired = await this.config.backend.acquireLock!(runId, lockDuration);
       if (!acquired) {
-        throw new Error(
-          `Cannot execute workflow run "${runId}": another worker is already executing it. ` +
+        throw ORCHESTRATION_ERROR.create({
+          detail:
+            `Cannot execute workflow run "${runId}": another worker is already executing it. ` +
             `This can happen when multiple workers try to execute the same run concurrently.`,
-        );
+        });
       }
       logger.debug("Acquired lock for run", { runId });
     }
@@ -343,7 +361,7 @@ export class WorkflowExecutor {
         return;
       }
 
-      const error = new Error(result.error || "Unknown error");
+      const error = ORCHESTRATION_ERROR.create({ detail: result.error || "Unknown error" });
       await this.failRun(runId, error, result.context, result.nodeStates);
 
       await workflow.onError?.(error, result.context);
@@ -390,11 +408,15 @@ export class WorkflowExecutor {
    */
   private validateNodes(nodes: WorkflowNode[], workflowId: string): void {
     if (!Array.isArray(nodes)) {
-      throw new Error(`Workflow "${workflowId}" steps must resolve to an array`);
+      throw INVALID_ARGUMENT.create({
+        detail: `Workflow "${workflowId}" steps must resolve to an array`,
+      });
     }
 
     if (nodes.length === 0) {
-      throw new Error(`Workflow "${workflowId}" must have at least one step`);
+      throw INVALID_ARGUMENT.create({
+        detail: `Workflow "${workflowId}" must have at least one step`,
+      });
     }
 
     const seenIds = new Set<string>();
@@ -403,24 +425,34 @@ export class WorkflowExecutor {
       const node = nodes[i];
 
       if (!node) {
-        throw new Error(`Workflow "${workflowId}" has undefined node at index ${i}`);
+        throw INVALID_ARGUMENT.create({
+          detail: `Workflow "${workflowId}" has undefined node at index ${i}`,
+        });
       }
 
       if (!node.id || typeof node.id !== "string") {
-        throw new Error(`Workflow "${workflowId}" node at index ${i} has invalid ID`);
+        throw INVALID_ARGUMENT.create({
+          detail: `Workflow "${workflowId}" node at index ${i} has invalid ID`,
+        });
       }
 
       if (seenIds.has(node.id)) {
-        throw new Error(`Workflow "${workflowId}" has duplicate node ID: "${node.id}"`);
+        throw INVALID_ARGUMENT.create({
+          detail: `Workflow "${workflowId}" has duplicate node ID: "${node.id}"`,
+        });
       }
       seenIds.add(node.id);
 
       if (!node.config || typeof node.config !== "object") {
-        throw new Error(`Workflow "${workflowId}" node "${node.id}" has invalid config`);
+        throw INVALID_ARGUMENT.create({
+          detail: `Workflow "${workflowId}" node "${node.id}" has invalid config`,
+        });
       }
 
       if (!node.config.type) {
-        throw new Error(`Workflow "${workflowId}" node "${node.id}" config missing type`);
+        throw INVALID_ARGUMENT.create({
+          detail: `Workflow "${workflowId}" node "${node.id}" config missing type`,
+        });
       }
     }
   }
@@ -439,7 +471,7 @@ export class WorkflowExecutor {
 
     const timeoutPromise = new Promise<never>((_, reject) => {
       timeoutId = dntShim.setTimeout(() => {
-        reject(new Error(`Workflow timed out after ${timeoutMs}ms`));
+        reject(TIMEOUT_ERROR.create({ detail: `Workflow timed out after ${timeoutMs}ms` }));
       }, timeoutMs);
     });
 
@@ -532,15 +564,23 @@ export class WorkflowExecutor {
   /**
    * Wait for workflow result
    */
-  private async waitForResult<TOutput>(runId: string, pollInterval = 1000): Promise<TOutput> {
+  private async waitForResult<TOutput>(
+    runId: string,
+    pollInterval = DEFAULT_RESULT_POLL_INTERVAL_MS,
+  ): Promise<TOutput> {
     while (true) {
       const run = await this.config.backend.getRun(runId);
-      if (!run) throw new Error(`Run not found: ${runId}`);
+      if (!run) throw RESOURCE_NOT_FOUND.create({ detail: `Run not found: ${runId}` });
 
       if (run.status === "completed") return run.output as TOutput;
-      if (run.status === "failed") throw new Error(run.error?.message || "Workflow failed");
-      if (run.status === "cancelled") throw new Error("Workflow was cancelled");
+      if (run.status === "failed") {
+        throw ORCHESTRATION_ERROR.create({ detail: run.error?.message || "Workflow failed" });
+      }
+      if (run.status === "cancelled") {
+        throw ORCHESTRATION_ERROR.create({ detail: "Workflow was cancelled" });
+      }
 
+      // no cleanup needed: one-shot
       await new Promise((resolve) => dntShim.setTimeout(resolve, pollInterval));
     }
   }
@@ -550,13 +590,13 @@ export class WorkflowExecutor {
    */
   async cancel(runId: string): Promise<void> {
     const run = await this.config.backend.getRun(runId);
-    if (!run) throw new Error(`Run not found: ${runId}`);
+    if (!run) throw RESOURCE_NOT_FOUND.create({ detail: `Run not found: ${runId}` });
 
     if (run.status === "completed" || run.status === "failed") {
-      throw new Error(
-        `Cannot cancel workflow run "${runId}": run has already ${run.status}. ` +
+      throw ORCHESTRATION_ERROR.create({
+        detail: `Cannot cancel workflow run "${runId}": run has already ${run.status}. ` +
           `Only active runs (pending, running, waiting) can be cancelled.`,
-      );
+      });
     }
 
     await this.config.backend.updateRun(runId, {

package/src/src/workflow/react/use-approval.ts

@@ -1,5 +1,6 @@
 import * as dntShim from "../../../_dnt.shims.js";
 import { useCallback, useEffect, useState } from "react";
+import { REQUEST_ERROR } from "../../errors/index.js";
 import type { ApprovalDecision, PendingApproval } from "../types.js";
 
 export interface UseApprovalOptions {
@@ -53,7 +54,10 @@ export function useApproval(options: UseApprovalOptions): UseApprovalResult {
         const response = await dntShim.fetch(`${apiBase}/runs/${runId}/approvals/${approvalId}`);
 
         if (!response.ok) {
-          throw new Error(`Failed to fetch approval: ${response.status}`);
+          throw REQUEST_ERROR.create({
+            detail: `Failed to fetch approval: ${response.status}`,
+            status: response.status,
+          });
         }
 
         const data: PendingApproval = await response.json();
@@ -86,7 +90,10 @@ export function useApproval(options: UseApprovalOptions): UseApprovalResult {
         });
 
         if (!response.ok) {
-          throw new Error(`Failed to submit decision: ${response.status}`);
+          throw REQUEST_ERROR.create({
+            detail: `Failed to submit decision: ${response.status}`,
+            status: response.status,
+          });
         }
 
         setApproval((prev) => {

package/src/src/workflow/react/use-workflow-list.ts

@@ -1,7 +1,11 @@
 import * as dntShim from "../../../_dnt.shims.js";
 import { useCallback, useEffect, useState } from "react";
+import { REQUEST_ERROR } from "../../errors/index.js";
 import type { RunFilter, WorkflowRun, WorkflowStatus } from "../types.js";
 
+/** Default interval for auto-refreshing the workflow list */
+const DEFAULT_REFRESH_INTERVAL_MS = 5_000;
+
 export interface UseWorkflowListOptions {
   workflowId?: string;
   status?: WorkflowStatus | WorkflowStatus[];
@@ -37,7 +41,7 @@ export function useWorkflowList(options: UseWorkflowListOptions = {}): UseWorkfl
     pageSize = 20,
     apiBase = "/api/workflows",
     autoRefresh = false,
-    refreshInterval = 5000,
+    refreshInterval = DEFAULT_REFRESH_INTERVAL_MS,
   } = options;
 
   const [runs, setRuns] = useState<WorkflowRun[]>([]);
@@ -85,7 +89,12 @@ export function useWorkflowList(options: UseWorkflowListOptions = {}): UseWorkfl
         const queryString = buildQueryString(filter, append ? cursor : undefined);
         const response = await dntShim.fetch(`${apiBase}/runs?${queryString}`);
 
-        if (!response.ok) throw new Error(`Failed to fetch runs: ${response.status}`);
+        if (!response.ok) {
+          throw REQUEST_ERROR.create({
+            detail: `Failed to fetch runs: ${response.status}`,
+            status: response.status,
+          });
+        }
 
         const data: { runs?: WorkflowRun[]; cursor?: string; totalCount?: number } = await response
           .json();