@microfox/ai-worker 1.0.3 → 1.0.5

package/dist/client.d.ts

@@ -1,2 +1,148 @@
-import 'zod';
-export { D as DispatchOptions, b as DispatchQueueResult, a as DispatchResult, S as SerializedContext, W as WorkerQueueRegistry, d as dispatch, f as dispatchLocal, h as dispatchQueue, e as dispatchWorker, c as getQueueStartUrl, g as getWorkersTriggerUrl } from './client-BqSJQ9mZ.js';
+import { ZodType, z } from 'zod';
+import { d as WorkerQueueConfig, b as ChainContext, H as HitlResumeContext, L as LoopContext } from './queue-B5n6YVQV.js';
+import './hitlConfig.js';
+
+/**
+ * Client for dispatching background worker jobs.
+ *
+ * In production, dispatching happens via the workers HTTP API:
+ *   POST /workers/trigger  -> enqueues message to SQS on the workers service side
+ *
+ * This avoids requiring AWS credentials in your Next.js app.
+ */
+
+interface WorkerQueueRegistry {
+    getQueueById(queueId: string): WorkerQueueConfig | undefined;
+    getStepAt?(queueId: string, stepIndex: number): {
+        workerId?: string;
+        requiresApproval?: boolean;
+        hasChain?: boolean;
+        hasResume?: boolean;
+        hasLoop?: boolean;
+        hitl?: unknown;
+    } | undefined;
+    /** Build next-step input during normal chain advancement (no HITL). */
+    invokeChain?: (queueId: string, stepIndex: number, ctx: ChainContext) => Promise<unknown> | unknown;
+    /** Build domain input when a HITL step resumes after human approval. */
+    invokeResume?: (queueId: string, stepIndex: number, ctx: HitlResumeContext<any>) => Promise<unknown> | unknown;
+    /** Evaluate whether a looping step should run again after its output. */
+    invokeLoop?: (queueId: string, stepIndex: number, ctx: LoopContext) => Promise<boolean> | boolean;
+}
+interface DispatchOptions {
+    /**
+     * Optional webhook callback URL to notify when the job finishes.
+     * Only called when provided. Default: no webhook (use job store / MongoDB only).
+     */
+    webhookUrl?: string;
+    /**
+     * Controls how dispatch executes.
+     * - "auto" (default): local inline execution in development unless WORKERS_LOCAL_MODE=false.
+     * - "local": force inline execution (no SQS).
+     * - "remote": force SQS/Lambda dispatch even in development.
+     */
+    mode?: 'auto' | 'local' | 'remote';
+    jobId?: string;
+    /**
+     * The ID of the user who triggered this job.
+     * Call getClientId() in your API route and pass the result here.
+     * If omitted, userId is not stored and not logged.
+     */
+    userId?: string;
+    metadata?: Record<string, any>;
+    /**
+     * In-memory queue registry for dispatchQueue. Required when using dispatchQueue.
+     * Pass a registry that imports from your .queue.ts definitions (works on Vercel/serverless).
+     */
+    registry?: WorkerQueueRegistry;
+    /**
+     * Optional callback to create a queue job record before dispatching.
+     * Called with queueJobId (= first worker's jobId), queueId, and firstStep.
+     */
+    onCreateQueueJob?: (params: {
+        queueJobId: string;
+        queueId: string;
+        firstStep: {
+            workerId: string;
+            workerJobId: string;
+        };
+        metadata?: Record<string, unknown>;
+    }) => Promise<void>;
+    /**
+     * Maximum total tokens (input + output) allowed for this job.
+     * The worker must call ctx.reportTokenUsage() after each LLM call.
+     * Throws TokenBudgetExceededError when the limit is reached.
+     * For queues, applies per-step unless overridden on the queue step config.
+     */
+    maxTokens?: number;
+}
+interface DispatchResult {
+    messageId: string;
+    status: 'queued';
+    jobId: string;
+}
+interface DispatchQueueResult extends DispatchResult {
+    queueId: string;
+}
+interface SerializedContext {
+    requestId?: string;
+    userId?: string;
+    traceId?: string;
+    [key: string]: any;
+}
+/**
+ * Derives the full /workers/trigger URL from env.
+ * Exported for use by local dispatchWorker (worker-to-worker in dev).
+ * Server-side only; clients should use useWorkflowJob with your app's /api/workflows routes.
+ *
+ * Env vars:
+ * - WORKER_BASE_URL: base URL of the workers service (e.g. https://.../prod)
+ * - WORKERS_TRIGGER_API_URL / WORKERS_CONFIG_API_URL: legacy, still supported
+ */
+declare function getWorkersTriggerUrl(): string;
+/**
+ * URL for the queue start endpoint (dispatch proxy). Use this so queue starts
+ * go through the queue handler Lambda for easier debugging (one log stream per queue).
+ */
+declare function getQueueStartUrl(queueId: string): string;
+/**
+ * Dispatches a background worker job to SQS.
+ *
+ * @param workerId - The ID of the worker to dispatch
+ * @param input - The input data for the worker (will be validated against inputSchema)
+ * @param inputSchema - Zod schema for input validation
+ * @param options - Dispatch options including webhook URL
+ * @param ctx - Optional context object (only serializable parts will be sent)
+ * @returns Promise resolving to dispatch result with messageId and jobId
+ */
+declare function dispatch<INPUT_SCHEMA extends ZodType<any>>(workerId: string, input: z.input<INPUT_SCHEMA>, inputSchema: INPUT_SCHEMA, options: DispatchOptions, ctx?: any): Promise<DispatchResult>;
+/**
+ * Dispatch a worker by ID without importing the worker module.
+ * Sends to the workers trigger API (WORKER_BASE_URL). No input schema validation at call site.
+ *
+ * @param workerId - The worker ID (e.g. 'echo', 'data-processor')
+ * @param input - Input payload (object or undefined)
+ * @param options - Optional jobId, webhookUrl, metadata
+ * @param ctx - Optional context (serializable parts sent in the request)
+ * @returns Promise resolving to { messageId, status: 'queued', jobId }
+ */
+declare function dispatchWorker(workerId: string, input?: Record<string, unknown>, options?: DispatchOptions, ctx?: any): Promise<DispatchResult>;
+/**
+ * Local development mode: runs the handler immediately in the same process.
+ * This bypasses SQS and Lambda for faster iteration during development.
+ *
+ * @param handler - The worker handler function
+ * @param input - The input data
+ * @param ctx - The context object
+ * @returns The handler result
+ */
+declare function dispatchLocal<INPUT, OUTPUT>(handler: (params: {
+    input: INPUT;
+    ctx: any;
+}) => Promise<OUTPUT>, input: INPUT, ctx?: any): Promise<OUTPUT>;
+/**
+ * Dispatches a queue by ID. POSTs to the queue-start API; the queue-start handler creates the queue job.
+ * Pass the first worker's input directly (no registry required).
+ */
+declare function dispatchQueue<InitialInput = any>(queueId: string, initialInput?: InitialInput, options?: DispatchOptions, _ctx?: any): Promise<DispatchQueueResult>;
+
+export { type DispatchOptions, type DispatchQueueResult, type DispatchResult, type SerializedContext, type WorkerQueueRegistry, dispatch, dispatchLocal, dispatchQueue, dispatchWorker, getQueueStartUrl, getWorkersTriggerUrl };

package/dist/client.js

@@ -66,6 +66,9 @@ function serializeContext(ctx) {
   if (ctx.requestId) {
     serialized.requestId = ctx.requestId;
   }
+  if (ctx.userId) {
+    serialized.userId = ctx.userId;
+  }
   if (ctx.metadata && typeof ctx.metadata === "object") {
     Object.assign(serialized, ctx.metadata);
   }
@@ -80,6 +83,8 @@ async function dispatch(workerId, input, inputSchema, options, ctx) {
   const jobId = options.jobId || `job-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
   const triggerUrl = getWorkersTriggerUrl();
   const serializedContext = ctx ? serializeContext(ctx) : {};
+  const userId = options.userId ?? ctx?.userId;
+  if (userId) serializedContext.userId = userId;
   const messageBody = {
     workerId,
     jobId,
@@ -87,7 +92,8 @@ async function dispatch(workerId, input, inputSchema, options, ctx) {
     context: serializedContext,
     webhookUrl: options.webhookUrl,
     metadata: options.metadata || {},
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    ...options.maxTokens !== void 0 ? { maxTokens: options.maxTokens } : {}
   };
   const headers = {
     "Content-Type": "application/json"
@@ -122,6 +128,8 @@ async function dispatchWorker(workerId, input, options = {}, ctx) {
   const jobId = options.jobId || `job-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
   const triggerUrl = getWorkersTriggerUrl();
   const serializedContext = ctx ? serializeContext(ctx) : {};
+  const userId = options.userId ?? ctx?.userId;
+  if (userId) serializedContext.userId = userId;
   const messageBody = {
     workerId,
     jobId,
@@ -129,7 +137,8 @@ async function dispatchWorker(workerId, input, options = {}, ctx) {
     context: serializedContext,
     webhookUrl: options.webhookUrl,
     metadata: options.metadata || {},
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    ...options.maxTokens !== void 0 ? { maxTokens: options.maxTokens } : {}
   };
   const headers = { "Content-Type": "application/json" };
   const triggerKey = process.env.WORKERS_TRIGGER_API_KEY;
@@ -159,6 +168,7 @@ async function dispatchQueue(queueId, initialInput, options = {}, _ctx) {
   const headers = { "Content-Type": "application/json" };
   const triggerKey = process.env.WORKERS_TRIGGER_API_KEY;
   if (triggerKey) headers["x-workers-trigger-key"] = triggerKey;
+  const userId = options.userId ?? _ctx?.userId;
   const response = await fetch(queueStartUrl, {
     method: "POST",
     headers,
@@ -167,6 +177,7 @@ async function dispatchQueue(queueId, initialInput, options = {}, _ctx) {
       initialInput: normalizedInput,
       metadata: options.metadata ?? {},
       jobId,
+      ...userId ? { userId } : {},
       ...options.webhookUrl ? { webhookUrl: options.webhookUrl } : {}
     })
   });

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"sourcesContent":["/**\n * Client for dispatching background worker jobs.\n *\n * In production, dispatching happens via the workers HTTP API:\n *   POST /workers/trigger  -> enqueues message to SQS on the workers service side\n *\n * This avoids requiring AWS credentials in your Next.js app.\n */\n\nimport type { ZodType, z } from 'zod';\nimport type { WorkerQueueConfig } from './queue.js';\n\nexport interface WorkerQueueRegistry {\n  getQueueById(queueId: string): WorkerQueueConfig | undefined;\n  /** (initialInput, previousOutputs) for best DX: derive next input from original request and all prior step outputs. */\n  invokeMapInput?: (\n    queueId: string,\n    stepIndex: number,\n    initialInput: unknown,\n    previousOutputs: Array<{ stepIndex: number; workerId: string; output: unknown }>\n  ) => Promise<unknown> | unknown;\n}\n\nexport interface DispatchOptions {\n  /**\n   * Optional webhook callback URL to notify when the job finishes.\n   * Only called when provided. Default: no webhook (use job store / MongoDB only).\n   */\n  webhookUrl?: string;\n  /**\n   * Controls how dispatch executes.\n   * - \"auto\" (default): local inline execution in development unless WORKERS_LOCAL_MODE=false.\n   * - \"local\": force inline execution (no SQS).\n   * - \"remote\": force SQS/Lambda dispatch even in development.\n   */\n  mode?: 'auto' | 'local' | 'remote';\n  jobId?: string;\n  metadata?: Record<string, any>;\n  /**\n   * In-memory queue registry for dispatchQueue. Required when using dispatchQueue.\n   * Pass a registry that imports from your .queue.ts definitions (works on Vercel/serverless).\n   */\n  registry?: WorkerQueueRegistry;\n  /**\n   * Optional callback to create a queue job record before dispatching.\n   * Called with queueJobId (= first worker's jobId), queueId, and firstStep.\n   */\n  onCreateQueueJob?: (params: {\n    queueJobId: string;\n    queueId: string;\n    firstStep: { workerId: string; workerJobId: string };\n    metadata?: Record<string, unknown>;\n  }) => Promise<void>;\n}\n\nexport interface DispatchResult {\n  messageId: string;\n  status: 'queued';\n  jobId: string;\n}\n\nexport interface DispatchQueueResult extends DispatchResult {\n  queueId: string;\n}\n\nexport interface SerializedContext {\n  requestId?: string;\n  userId?: string;\n  traceId?: string;\n  [key: string]: any;\n}\n\n/**\n * Derives the full /workers/trigger URL from env.\n * Exported for use by local dispatchWorker (worker-to-worker in dev).\n * Server-side only; clients should use useWorkflowJob with your app's /api/workflows routes.\n *\n * Env vars:\n * - WORKER_BASE_URL: base URL of the workers service (e.g. https://.../prod)\n * - WORKERS_TRIGGER_API_URL / WORKERS_CONFIG_API_URL: legacy, still supported\n */\nexport function getWorkersTriggerUrl(): string {\n  const raw =\n    process.env.WORKER_BASE_URL ||\n    process.env.WORKERS_TRIGGER_API_URL ||\n    process.env.WORKERS_CONFIG_API_URL;\n\n  if (!raw) {\n    throw new Error(\n      'WORKER_BASE_URL is required for background workers. Set it server-side only.'\n    );\n  }\n\n  const url = new URL(raw);\n  url.search = '';\n  url.hash = '';\n\n  const path = url.pathname || '';\n\n  // If the user pointed at a specific endpoint, normalize back to the service root.\n  url.pathname = path.replace(/\\/?workers\\/(trigger|config)\\/?$/, '');\n\n  const basePath = url.pathname.replace(/\\/+$/, '');\n  url.pathname = `${basePath}/workers/trigger`.replace(/\\/+$/, '');\n\n  return url.toString();\n}\n\n/**\n * URL for the queue start endpoint (dispatch proxy). Use this so queue starts\n * go through the queue handler Lambda for easier debugging (one log stream per queue).\n */\nexport function getQueueStartUrl(queueId: string): string {\n  const raw =\n    process.env.WORKER_BASE_URL ||\n    process.env.WORKERS_TRIGGER_API_URL ||\n    process.env.WORKERS_CONFIG_API_URL;\n\n  if (!raw) {\n    throw new Error(\n      'WORKER_BASE_URL is required for background workers. Set it server-side only.'\n    );\n  }\n\n  const url = new URL(raw);\n  url.search = '';\n  url.hash = '';\n\n  const path = url.pathname || '';\n  url.pathname = path.replace(/\\/?workers\\/(trigger|config)\\/?$/, '');\n  const basePath = url.pathname.replace(/\\/+$/, '');\n  const safeSegment = encodeURIComponent(queueId);\n  url.pathname = `${basePath}/queues/${safeSegment}/start`.replace(/\\/+$/, '');\n\n  return url.toString();\n}\n\n/**\n * Serializes context data for transmission to Lambda.\n * Only serializes safe, JSON-compatible properties.\n */\nfunction serializeContext(ctx: any): SerializedContext {\n  const serialized: SerializedContext = {};\n\n  if (ctx.requestId) {\n    serialized.requestId = ctx.requestId;\n  }\n\n  // Extract any additional serializable metadata\n  if (ctx.metadata && typeof ctx.metadata === 'object') {\n    Object.assign(serialized, ctx.metadata);\n  }\n\n  // Allow custom context serialization via a helper property\n  if (ctx._serializeContext && typeof ctx._serializeContext === 'function') {\n    const custom = ctx._serializeContext();\n    Object.assign(serialized, custom);\n  }\n\n  return serialized;\n}\n\n\n/**\n * Dispatches a background worker job to SQS.\n *\n * @param workerId - The ID of the worker to dispatch\n * @param input - The input data for the worker (will be validated against inputSchema)\n * @param inputSchema - Zod schema for input validation\n * @param options - Dispatch options including webhook URL\n * @param ctx - Optional context object (only serializable parts will be sent)\n * @returns Promise resolving to dispatch result with messageId and jobId\n */\nexport async function dispatch<INPUT_SCHEMA extends ZodType<any>>(\n  workerId: string,\n  input: z.input<INPUT_SCHEMA>,\n  inputSchema: INPUT_SCHEMA,\n  options: DispatchOptions,\n  ctx?: any\n): Promise<DispatchResult> {\n  // Validate input against schema\n  const validatedInput = inputSchema.parse(input);\n\n  // Generate job ID if not provided\n  const jobId =\n    options.jobId || `job-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;\n\n  // Resolve /workers/trigger endpoint URL\n  const triggerUrl = getWorkersTriggerUrl();\n\n  // Serialize context (only safe, JSON-compatible parts)\n  const serializedContext = ctx ? serializeContext(ctx) : {};\n\n  // Job updates use MongoDB only; never pass jobStoreUrl/origin URL.\n  const messageBody = {\n    workerId,\n    jobId,\n    input: validatedInput,\n    context: serializedContext,\n    webhookUrl: options.webhookUrl,\n    metadata: options.metadata || {},\n    timestamp: new Date().toISOString(),\n  };\n\n  const headers: Record<string, string> = {\n    'Content-Type': 'application/json',\n  };\n  const triggerKey = process.env.WORKERS_TRIGGER_API_KEY;\n  if (triggerKey) {\n    headers['x-workers-trigger-key'] = triggerKey;\n  }\n\n  const response = await fetch(triggerUrl, {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({\n      workerId,\n      body: messageBody,\n    }),\n  });\n\n  if (!response.ok) {\n    const text = await response.text().catch(() => '');\n    throw new Error(\n      `Failed to trigger worker \"${workerId}\": ${response.status} ${response.statusText}${text ? ` - ${text}` : ''}`\n    );\n  }\n\n  const data = (await response.json().catch(() => ({}))) as any;\n  const messageId = data?.messageId ? String(data.messageId) : `trigger-${jobId}`;\n\n  return {\n    messageId,\n    status: 'queued',\n    jobId,\n  };\n}\n\n/**\n * Dispatch a worker by ID without importing the worker module.\n * Sends to the workers trigger API (WORKER_BASE_URL). No input schema validation at call site.\n *\n * @param workerId - The worker ID (e.g. 'echo', 'data-processor')\n * @param input - Input payload (object or undefined)\n * @param options - Optional jobId, webhookUrl, metadata\n * @param ctx - Optional context (serializable parts sent in the request)\n * @returns Promise resolving to { messageId, status: 'queued', jobId }\n */\nexport async function dispatchWorker(\n  workerId: string,\n  input?: Record<string, unknown>,\n  options: DispatchOptions = {},\n  ctx?: any\n): Promise<DispatchResult> {\n  const jobId =\n    options.jobId || `job-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;\n  const triggerUrl = getWorkersTriggerUrl();\n  const serializedContext = ctx ? serializeContext(ctx) : {};\n  const messageBody = {\n    workerId,\n    jobId,\n    input: input ?? {},\n    context: serializedContext,\n    webhookUrl: options.webhookUrl,\n    metadata: options.metadata || {},\n    timestamp: new Date().toISOString(),\n  };\n  const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n  const triggerKey = process.env.WORKERS_TRIGGER_API_KEY;\n  if (triggerKey) headers['x-workers-trigger-key'] = triggerKey;\n  const response = await fetch(triggerUrl, {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({ workerId, body: messageBody }),\n  });\n  if (!response.ok) {\n    const text = await response.text().catch(() => '');\n    throw new Error(\n      `Failed to trigger worker \"${workerId}\": ${response.status} ${response.statusText}${text ? ` - ${text}` : ''}`\n    );\n  }\n  const data = (await response.json().catch(() => ({}))) as any;\n  const messageId = data?.messageId ? String(data.messageId) : `trigger-${jobId}`;\n  return { messageId, status: 'queued', jobId };\n}\n\n/**\n * Local development mode: runs the handler immediately in the same process.\n * This bypasses SQS and Lambda for faster iteration during development.\n *\n * @param handler - The worker handler function\n * @param input - The input data\n * @param ctx - The context object\n * @returns The handler result\n */\nexport async function dispatchLocal<INPUT, OUTPUT>(\n  handler: (params: { input: INPUT; ctx: any }) => Promise<OUTPUT>,\n  input: INPUT,\n  ctx?: any\n): Promise<OUTPUT> {\n  return handler({ input, ctx: ctx || {} });\n}\n\n/**\n * Dispatches a queue by ID. POSTs to the queue-start API; the queue-start handler creates the queue job.\n * Pass the first worker's input directly (no registry required).\n */\nexport async function dispatchQueue<InitialInput = any>(\n  queueId: string,\n  initialInput?: InitialInput,\n  options: DispatchOptions = {},\n  _ctx?: any\n): Promise<DispatchQueueResult> {\n  const jobId =\n    options.jobId || `job-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;\n  const queueStartUrl = getQueueStartUrl(queueId);\n  const normalizedInput =\n    initialInput !== null && typeof initialInput === 'object'\n      ? (initialInput as Record<string, unknown>)\n      : { value: initialInput };\n  const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n  const triggerKey = process.env.WORKERS_TRIGGER_API_KEY;\n  if (triggerKey) headers['x-workers-trigger-key'] = triggerKey;\n  const response = await fetch(queueStartUrl, {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({\n      input: normalizedInput,\n      initialInput: normalizedInput,\n      metadata: options.metadata ?? {},\n      jobId,\n      ...(options.webhookUrl ? { webhookUrl: options.webhookUrl } : {}),\n    }),\n  });\n  if (!response.ok) {\n    const text = await response.text().catch(() => '');\n    throw new Error(\n      `Failed to start queue \"${queueId}\": ${response.status} ${response.statusText}${text ? ` - ${text}` : ''}`\n    );\n  }\n  const data = (await response.json().catch(() => ({}))) as any;\n  const messageId = data?.messageId ?? data?.jobId ?? `queue-${jobId}`;\n  return { queueId, messageId, status: 'queued', jobId };\n}\n\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["/**\n * Client for dispatching background worker jobs.\n *\n * In production, dispatching happens via the workers HTTP API:\n *   POST /workers/trigger  -> enqueues message to SQS on the workers service side\n *\n * This avoids requiring AWS credentials in your Next.js app.\n */\n\nimport type { ZodType, z } from 'zod';\nimport type { WorkerQueueConfig } from './queue.js';\n\nimport type { ChainContext, HitlResumeContext, LoopContext } from './queue.js';\n\nexport interface WorkerQueueRegistry {\n  getQueueById(queueId: string): WorkerQueueConfig | undefined;\n  getStepAt?(queueId: string, stepIndex: number): {\n    workerId?: string;\n    requiresApproval?: boolean;\n    hasChain?: boolean;\n    hasResume?: boolean;\n    hasLoop?: boolean;\n    hitl?: unknown;\n  } | undefined;\n  /** Build next-step input during normal chain advancement (no HITL). */\n  invokeChain?: (\n    queueId: string,\n    stepIndex: number,\n    ctx: ChainContext\n  ) => Promise<unknown> | unknown;\n  /** Build domain input when a HITL step resumes after human approval. */\n  invokeResume?: (\n    queueId: string,\n    stepIndex: number,\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    ctx: HitlResumeContext<any>\n  ) => Promise<unknown> | unknown;\n  /** Evaluate whether a looping step should run again after its output. */\n  invokeLoop?: (\n    queueId: string,\n    stepIndex: number,\n    ctx: LoopContext\n  ) => Promise<boolean> | boolean;\n}\n\nexport interface DispatchOptions {\n  /**\n   * Optional webhook callback URL to notify when the job finishes.\n   * Only called when provided. Default: no webhook (use job store / MongoDB only).\n   */\n  webhookUrl?: string;\n  /**\n   * Controls how dispatch executes.\n   * - \"auto\" (default): local inline execution in development unless WORKERS_LOCAL_MODE=false.\n   * - \"local\": force inline execution (no SQS).\n   * - \"remote\": force SQS/Lambda dispatch even in development.\n   */\n  mode?: 'auto' | 'local' | 'remote';\n  jobId?: string;\n  /**\n   * The ID of the user who triggered this job.\n   * Call getClientId() in your API route and pass the result here.\n   * If omitted, userId is not stored and not logged.\n   */\n  userId?: string;\n  metadata?: Record<string, any>;\n  /**\n   * In-memory queue registry for dispatchQueue. Required when using dispatchQueue.\n   * Pass a registry that imports from your .queue.ts definitions (works on Vercel/serverless).\n   */\n  registry?: WorkerQueueRegistry;\n  /**\n   * Optional callback to create a queue job record before dispatching.\n   * Called with queueJobId (= first worker's jobId), queueId, and firstStep.\n   */\n  onCreateQueueJob?: (params: {\n    queueJobId: string;\n    queueId: string;\n    firstStep: { workerId: string; workerJobId: string };\n    metadata?: Record<string, unknown>;\n  }) => Promise<void>;\n  /**\n   * Maximum total tokens (input + output) allowed for this job.\n   * The worker must call ctx.reportTokenUsage() after each LLM call.\n   * Throws TokenBudgetExceededError when the limit is reached.\n   * For queues, applies per-step unless overridden on the queue step config.\n   */\n  maxTokens?: number;\n}\n\nexport interface DispatchResult {\n  messageId: string;\n  status: 'queued';\n  jobId: string;\n}\n\nexport interface DispatchQueueResult extends DispatchResult {\n  queueId: string;\n}\n\nexport interface SerializedContext {\n  requestId?: string;\n  userId?: string;\n  traceId?: string;\n  [key: string]: any;\n}\n\n\n/**\n * Derives the full /workers/trigger URL from env.\n * Exported for use by local dispatchWorker (worker-to-worker in dev).\n * Server-side only; clients should use useWorkflowJob with your app's /api/workflows routes.\n *\n * Env vars:\n * - WORKER_BASE_URL: base URL of the workers service (e.g. https://.../prod)\n * - WORKERS_TRIGGER_API_URL / WORKERS_CONFIG_API_URL: legacy, still supported\n */\nexport function getWorkersTriggerUrl(): string {\n  const raw =\n    process.env.WORKER_BASE_URL ||\n    process.env.WORKERS_TRIGGER_API_URL ||\n    process.env.WORKERS_CONFIG_API_URL;\n\n  if (!raw) {\n    throw new Error(\n      'WORKER_BASE_URL is required for background workers. Set it server-side only.'\n    );\n  }\n\n  const url = new URL(raw);\n  url.search = '';\n  url.hash = '';\n\n  const path = url.pathname || '';\n\n  // If the user pointed at a specific endpoint, normalize back to the service root.\n  url.pathname = path.replace(/\\/?workers\\/(trigger|config)\\/?$/, '');\n\n  const basePath = url.pathname.replace(/\\/+$/, '');\n  url.pathname = `${basePath}/workers/trigger`.replace(/\\/+$/, '');\n\n  return url.toString();\n}\n\n/**\n * URL for the queue start endpoint (dispatch proxy). Use this so queue starts\n * go through the queue handler Lambda for easier debugging (one log stream per queue).\n */\nexport function getQueueStartUrl(queueId: string): string {\n  const raw =\n    process.env.WORKER_BASE_URL ||\n    process.env.WORKERS_TRIGGER_API_URL ||\n    process.env.WORKERS_CONFIG_API_URL;\n\n  if (!raw) {\n    throw new Error(\n      'WORKER_BASE_URL is required for background workers. Set it server-side only.'\n    );\n  }\n\n  const url = new URL(raw);\n  url.search = '';\n  url.hash = '';\n\n  const path = url.pathname || '';\n  url.pathname = path.replace(/\\/?workers\\/(trigger|config)\\/?$/, '');\n  const basePath = url.pathname.replace(/\\/+$/, '');\n  const safeSegment = encodeURIComponent(queueId);\n  url.pathname = `${basePath}/queues/${safeSegment}/start`.replace(/\\/+$/, '');\n\n  return url.toString();\n}\n\n/**\n * Serializes context data for transmission to Lambda.\n * Only serializes safe, JSON-compatible properties.\n */\nfunction serializeContext(ctx: any): SerializedContext {\n  const serialized: SerializedContext = {};\n\n  if (ctx.requestId) {\n    serialized.requestId = ctx.requestId;\n  }\n\n  if (ctx.userId) {\n    serialized.userId = ctx.userId;\n  }\n\n  // Extract any additional serializable metadata\n  if (ctx.metadata && typeof ctx.metadata === 'object') {\n    Object.assign(serialized, ctx.metadata);\n  }\n\n  // Allow custom context serialization via a helper property\n  if (ctx._serializeContext && typeof ctx._serializeContext === 'function') {\n    const custom = ctx._serializeContext();\n    Object.assign(serialized, custom);\n  }\n\n  return serialized;\n}\n\n\n/**\n * Dispatches a background worker job to SQS.\n *\n * @param workerId - The ID of the worker to dispatch\n * @param input - The input data for the worker (will be validated against inputSchema)\n * @param inputSchema - Zod schema for input validation\n * @param options - Dispatch options including webhook URL\n * @param ctx - Optional context object (only serializable parts will be sent)\n * @returns Promise resolving to dispatch result with messageId and jobId\n */\nexport async function dispatch<INPUT_SCHEMA extends ZodType<any>>(\n  workerId: string,\n  input: z.input<INPUT_SCHEMA>,\n  inputSchema: INPUT_SCHEMA,\n  options: DispatchOptions,\n  ctx?: any\n): Promise<DispatchResult> {\n  // Validate input against schema\n  const validatedInput = inputSchema.parse(input);\n\n  // Generate job ID if not provided\n  const jobId =\n    options.jobId || `job-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;\n\n  // Resolve /workers/trigger endpoint URL\n  const triggerUrl = getWorkersTriggerUrl();\n\n  // Serialize context (only safe, JSON-compatible parts)\n  const serializedContext = ctx ? serializeContext(ctx) : {};\n\n  // Attach userId if explicitly provided in options or context.\n  const userId = options.userId ?? (ctx?.userId as string | undefined);\n  if (userId) serializedContext.userId = userId;\n\n  // Job updates use MongoDB only; never pass jobStoreUrl/origin URL.\n  const messageBody = {\n    workerId,\n    jobId,\n    input: validatedInput,\n    context: serializedContext,\n    webhookUrl: options.webhookUrl,\n    metadata: options.metadata || {},\n    timestamp: new Date().toISOString(),\n    ...(options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),\n  };\n\n  const headers: Record<string, string> = {\n    'Content-Type': 'application/json',\n  };\n  const triggerKey = process.env.WORKERS_TRIGGER_API_KEY;\n  if (triggerKey) {\n    headers['x-workers-trigger-key'] = triggerKey;\n  }\n\n  const response = await fetch(triggerUrl, {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({\n      workerId,\n      body: messageBody,\n    }),\n  });\n\n  if (!response.ok) {\n    const text = await response.text().catch(() => '');\n    throw new Error(\n      `Failed to trigger worker \"${workerId}\": ${response.status} ${response.statusText}${text ? ` - ${text}` : ''}`\n    );\n  }\n\n  const data = (await response.json().catch(() => ({}))) as any;\n  const messageId = data?.messageId ? String(data.messageId) : `trigger-${jobId}`;\n\n  return {\n    messageId,\n    status: 'queued',\n    jobId,\n  };\n}\n\n/**\n * Dispatch a worker by ID without importing the worker module.\n * Sends to the workers trigger API (WORKER_BASE_URL). No input schema validation at call site.\n *\n * @param workerId - The worker ID (e.g. 'echo', 'data-processor')\n * @param input - Input payload (object or undefined)\n * @param options - Optional jobId, webhookUrl, metadata\n * @param ctx - Optional context (serializable parts sent in the request)\n * @returns Promise resolving to { messageId, status: 'queued', jobId }\n */\nexport async function dispatchWorker(\n  workerId: string,\n  input?: Record<string, unknown>,\n  options: DispatchOptions = {},\n  ctx?: any\n): Promise<DispatchResult> {\n  const jobId =\n    options.jobId || `job-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;\n  const triggerUrl = getWorkersTriggerUrl();\n  const serializedContext = ctx ? serializeContext(ctx) : {};\n  const userId = options.userId ?? (ctx?.userId as string | undefined);\n  if (userId) serializedContext.userId = userId;\n  const messageBody = {\n    workerId,\n    jobId,\n    input: input ?? {},\n    context: serializedContext,\n    webhookUrl: options.webhookUrl,\n    metadata: options.metadata || {},\n    timestamp: new Date().toISOString(),\n    ...(options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),\n  };\n  const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n  const triggerKey = process.env.WORKERS_TRIGGER_API_KEY;\n  if (triggerKey) headers['x-workers-trigger-key'] = triggerKey;\n  const response = await fetch(triggerUrl, {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({ workerId, body: messageBody }),\n  });\n  if (!response.ok) {\n    const text = await response.text().catch(() => '');\n    throw new Error(\n      `Failed to trigger worker \"${workerId}\": ${response.status} ${response.statusText}${text ? ` - ${text}` : ''}`\n    );\n  }\n  const data = (await response.json().catch(() => ({}))) as any;\n  const messageId = data?.messageId ? String(data.messageId) : `trigger-${jobId}`;\n  return { messageId, status: 'queued', jobId };\n}\n\n/**\n * Local development mode: runs the handler immediately in the same process.\n * This bypasses SQS and Lambda for faster iteration during development.\n *\n * @param handler - The worker handler function\n * @param input - The input data\n * @param ctx - The context object\n * @returns The handler result\n */\nexport async function dispatchLocal<INPUT, OUTPUT>(\n  handler: (params: { input: INPUT; ctx: any }) => Promise<OUTPUT>,\n  input: INPUT,\n  ctx?: any\n): Promise<OUTPUT> {\n  return handler({ input, ctx: ctx || {} });\n}\n\n/**\n * Dispatches a queue by ID. POSTs to the queue-start API; the queue-start handler creates the queue job.\n * Pass the first worker's input directly (no registry required).\n */\nexport async function dispatchQueue<InitialInput = any>(\n  queueId: string,\n  initialInput?: InitialInput,\n  options: DispatchOptions = {},\n  _ctx?: any\n): Promise<DispatchQueueResult> {\n  const jobId =\n    options.jobId || `job-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;\n  const queueStartUrl = getQueueStartUrl(queueId);\n  const normalizedInput =\n    initialInput !== null && typeof initialInput === 'object'\n      ? (initialInput as Record<string, unknown>)\n      : { value: initialInput };\n  const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n  const triggerKey = process.env.WORKERS_TRIGGER_API_KEY;\n  if (triggerKey) headers['x-workers-trigger-key'] = triggerKey;\n  const userId = options.userId ?? (_ctx?.userId as string | undefined);\n  const response = await fetch(queueStartUrl, {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({\n      input: normalizedInput,\n      initialInput: normalizedInput,\n      metadata: options.metadata ?? {},\n      jobId,\n      ...(userId ? { userId } : {}),\n      ...(options.webhookUrl ? { webhookUrl: options.webhookUrl } : {}),\n    }),\n  });\n  if (!response.ok) {\n    const text = await response.text().catch(() => '');\n    throw new Error(\n      `Failed to start queue \"${queueId}\": ${response.status} ${response.statusText}${text ? ` - ${text}` : ''}`\n    );\n  }\n  const data = (await response.json().catch(() => ({}))) as any;\n  const messageId = data?.messageId ?? data?.jobId ?? `queue-${jobId}`;\n  return { queueId, messageId, status: 'queued', jobId };\n}\n\n"],"mappings":"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","names":[]}

package/dist/client.mjs

@@ -5,7 +5,7 @@ import {
   dispatchWorker,
   getQueueStartUrl,
   getWorkersTriggerUrl
-} from "./chunk-72XGFZCE.mjs";
+} from "./chunk-CILTGUUQ.mjs";
 import "./chunk-BJTO5JO5.mjs";
 export {
   dispatch,

package/dist/handler.d.mts

@@ -1,5 +1,29 @@
 import { SQSEvent, Context } from 'aws-lambda';
 import { ZodType } from 'zod';
+import { R as RetryContext, S as SmartRetryConfig, Q as QueueStepOutput, b as ChainContext, H as HitlResumeContext, L as LoopContext } from './queue-DaR2UuZi.mjs';
+export { B as BuiltInRetryPattern, C as CustomRetryPattern, a as RetryPattern } from './queue-DaR2UuZi.mjs';
+import './hitlConfig.mjs';
+
+/**
+ * Token budget tracking for workers.
+ * Workers report usage via ctx.reportTokenUsage(); the runtime accumulates
+ * and throws TokenBudgetExceededError when the limit is reached.
+ */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+interface TokenBudgetState {
+    inputTokens: number;
+    outputTokens: number;
+    /** null = no budget configured */
+    budget: number | null;
+}
+declare class TokenBudgetExceededError extends Error {
+    readonly used: number;
+    readonly budget: number;
+    constructor(used: number, budget: number);
+}
 
 /**
  * Generic Lambda handler wrapper for worker agents.
@@ -34,6 +58,7 @@ interface JobRecord {
         jobId: string;
         workerId: string;
     }>;
+    userId?: string;
     createdAt: string;
     updatedAt: string;
     completedAt?: string;
@@ -98,6 +123,8 @@ interface WorkerHandlerParams<INPUT, OUTPUT> {
         jobId: string;
         workerId: string;
         requestId?: string;
+        /** ID of the user who triggered this job. Pass via DispatchOptions.userId from your API route. */
+        userId?: string;
         /**
          * Job store interface for updating and retrieving job state.
          * Uses MongoDB directly when configured; never HTTP/origin URL.
@@ -116,49 +143,114 @@ interface WorkerHandlerParams<INPUT, OUTPUT> {
             messageId?: string;
             output?: unknown;
         }>;
+        /**
+         * Report token usage after an LLM call. Accumulates across all calls in this job.
+         * Throws TokenBudgetExceededError if the configured maxTokens budget is exceeded.
+         * Also persists usage to the job store for observability.
+         *
+         * @example
+         * ```ts
+         * const result = await anthropic.messages.create({ ... });
+         * await ctx.reportTokenUsage({
+         *   inputTokens: result.usage.input_tokens,
+         *   outputTokens: result.usage.output_tokens,
+         * });
+         * ```
+         */
+        reportTokenUsage: (usage: TokenUsage) => Promise<void>;
+        /**
+         * Get the current token usage and remaining budget for this job.
+         * Returns `{ used, budget: null, remaining: null }` when no maxTokens was set.
+         */
+        getTokenBudget: () => {
+            used: number;
+            budget: number | null;
+            remaining: number | null;
+        };
+        /**
+         * Populated on retry attempts (attempt >= 2). Contains info about the previous failure
+         * so the handler can self-correct (e.g. inject the error message into the next prompt).
+         * `undefined` on the first attempt — use `if (ctx.retryContext)` to detect retries.
+         */
+        retryContext?: RetryContext;
         [key: string]: any;
     };
 }
+
 type WorkerHandler<INPUT, OUTPUT> = (params: WorkerHandlerParams<INPUT, OUTPUT>) => Promise<OUTPUT>;
 /** Result of getNextStep for queue chaining. */
 interface QueueNextStep {
     workerId: string;
     delaySeconds?: number;
-    mapInputFromPrev?: string;
+    requiresApproval?: boolean;
+    /** Whether this step has a `chain` function (or built-in string) defined. */
+    hasChain?: boolean;
+    /** Whether this step has a `resume` function defined. */
+    hasResume?: boolean;
+    /** Optional HITL metadata from queue step config (UI/tooling only). */
+    hitl?: {
+        ui?: unknown;
+    } | unknown;
+    /** Smart retry config for this step. Overrides worker-level retry for this step only. */
+    retry?: SmartRetryConfig;
 }
-/** One previous step's output (for mapInputFromPrev context). */
-interface QueueStepOutput {
-    stepIndex: number;
-    workerId: string;
-    output: unknown;
+/**
+ * @deprecated Use {@link ChainContext} for the normal chain path and
+ * {@link HitlResumeContext} for the HITL resume path instead.
+ * Kept for backwards compatibility with queue files written against the old API.
+ */
+interface MapStepInputContext {
+    initialInput: unknown;
+    previousOutputs: QueueStepOutput[];
+    /** @deprecated Use HitlResumeContext.reviewerInput instead. */
+    hitlInput?: unknown;
+    /** @deprecated Use HitlResumeContext.pendingInput instead. */
+    pendingStepInput?: Record<string, unknown>;
 }
+
 /** Runtime helpers for queue-aware wrappers (provided by generated registry). */
 interface QueueRuntime {
     getNextStep(queueId: string, stepIndex: number): QueueNextStep | undefined;
-    /** Optional: when provided, mapping can use outputs from any previous step. */
+    /** Step config at `stepIndex`. */
+    getStepAt?(queueId: string, stepIndex: number): QueueNextStep | undefined;
+    /** Optional: when provided, mappers can use outputs from any previous step. */
     getQueueJob?(queueJobId: string): Promise<{
         steps: Array<{
             workerId: string;
             output?: unknown;
         }>;
     } | null>;
-    /** (initialInput, previousOutputs) – previousOutputs includes outputs for steps 0..stepIndex-1 and current step. */
-    invokeMapInput?(queueId: string, stepIndex: number, initialInput: unknown, previousOutputs: QueueStepOutput[]): Promise<unknown> | unknown;
+    /**
+     * Build the input for a step when the queue advances normally (no HITL resume).
+     * Calls the step's `chain` function, or the built-in passthrough/continueFromPrevious.
+     */
+    invokeChain?(queueId: string, stepIndex: number, ctx: ChainContext): Promise<unknown> | unknown;
+    /**
+     * Build the domain input for a step when it resumes after HITL approval.
+     * Calls the step's `resume` function, or merges pendingInput + reviewerInput by default.
+     */
+    invokeResume?(queueId: string, stepIndex: number, ctx: HitlResumeContext): Promise<unknown> | unknown;
+    /**
+     * Evaluate whether a looping step should run again.
+     * Calls the step's `loop.shouldContinue` function. Returns false if none defined.
+     */
+    invokeLoop?(queueId: string, stepIndex: number, ctx: LoopContext): Promise<boolean> | boolean;
 }
 /**
- * Wraps a user handler so that when the job has __workerQueue context (from
- * dispatchQueue or queue cron), it dispatches the next worker in the sequence
- * after the handler completes. Uses literal worker IDs so the CLI env injection
- * picks up WORKER_QUEUE_URL_* for next-step workers.
+ * Wraps a user handler so that when the job has `__workerQueue` context (from
+ * `dispatchQueue` or queue cron), it dispatches the next worker in the sequence
+ * **after** the handler completes.
+ *
+ * All queue/HITL envelope keys (`__workerQueue`, `__hitlInput`, `__hitlDecision`,
+ * `__hitlPending`, `hitl`) are **stripped from `params.input` before the user handler
+ * runs** — workers receive clean domain input and do not need to accept these keys
+ * in their Zod schemas.
+ *
+ * **HITL resume:** When `__hitlInput` is present, `invokeResume` is called first to
+ * produce the merged domain input. **Chain advancement:** After a step completes,
+ * `invokeChain` is called to compute the next step's input.
  */
-declare function wrapHandlerForQueue<INPUT, OUTPUT>(handler: WorkerHandler<INPUT, OUTPUT>, queueRuntime: QueueRuntime): WorkerHandler<INPUT & {
-    __workerQueue?: {
-        id: string;
-        stepIndex: number;
-        initialInput: unknown;
-        queueJobId?: string;
-    };
-}, OUTPUT>;
+declare function wrapHandlerForQueue<INPUT, OUTPUT>(handler: WorkerHandler<INPUT, OUTPUT>, queueRuntime: QueueRuntime): WorkerHandler<INPUT, OUTPUT>;
 interface SQSMessageBody {
     workerId: string;
     jobId: string;
@@ -169,6 +261,10 @@ interface SQSMessageBody {
     jobStoreUrl?: string;
     metadata?: Record<string, any>;
     timestamp: string;
+    /** ID of the user who triggered this job. Forwarded from dispatch options. */
+    userId?: string;
+    /** Maximum total tokens (input + output) for this job. Forwarded from DispatchOptions.maxTokens. */
+    maxTokens?: number;
 }
 interface WebhookPayload {
     jobId: string;
@@ -190,6 +286,8 @@ interface WebhookPayload {
  * @param outputSchema - Optional Zod schema for output validation
  * @returns A Lambda handler function
  */
-declare function createLambdaHandler<INPUT, OUTPUT>(handler: WorkerHandler<INPUT, OUTPUT>, outputSchema?: ZodType<OUTPUT>): (event: SQSEvent, context: Context) => Promise<void>;
+declare function createLambdaHandler<INPUT, OUTPUT>(handler: WorkerHandler<INPUT, OUTPUT>, outputSchema?: ZodType<OUTPUT>, options?: {
+    retry?: SmartRetryConfig;
+}): (event: SQSEvent, context: Context) => Promise<void>;
 
-export { type DispatchWorkerOptions, type JobRecord, type JobStore, type JobStoreUpdate, type QueueNextStep, type QueueRuntime, type QueueStepOutput, type SQSMessageBody, SQS_MAX_DELAY_SECONDS, type WebhookPayload, type WorkerHandler, type WorkerHandlerParams, type WorkerLogger, createLambdaHandler, createWorkerLogger, wrapHandlerForQueue };
+export { ChainContext, type DispatchWorkerOptions, HitlResumeContext, type JobRecord, type JobStore, type JobStoreUpdate, LoopContext, type MapStepInputContext, type QueueNextStep, type QueueRuntime, QueueStepOutput, RetryContext, type SQSMessageBody, SQS_MAX_DELAY_SECONDS, SmartRetryConfig, TokenBudgetExceededError, type TokenBudgetState, type TokenUsage, type WebhookPayload, type WorkerHandler, type WorkerHandlerParams, type WorkerLogger, createLambdaHandler, createWorkerLogger, wrapHandlerForQueue };