@hatchet-dev/typescript-sdk 1.23.0 → 1.24.0

package/clients/hatchet-client/client-config.d.ts

@@ -16,6 +16,7 @@ declare const ClientTLSConfigSchema: z.ZodObject<{
 export declare const OpenTelemetryConfigSchema: z.ZodObject<{
     excludedAttributes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
     includeTaskNameInSpanName: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    individualRunSpansForBulkRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 export type OpenTelemetryConfig = z.infer<typeof OpenTelemetryConfigSchema>;
 export declare const ClientConfigSchema: z.ZodObject<{
@@ -49,6 +50,7 @@ export declare const ClientConfigSchema: z.ZodObject<{
     otel: z.ZodOptional<z.ZodObject<{
         excludedAttributes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
         includeTaskNameInSpanName: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        individualRunSpansForBulkRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     }, z.core.$strip>>;
     middleware: z.ZodOptional<z.ZodObject<{
         before: z.ZodOptional<z.ZodAny>;

package/clients/hatchet-client/client-config.js

@@ -24,6 +24,14 @@ exports.OpenTelemetryConfigSchema = v4_1.z.object({
      * e.g., "hatchet.start_step_run.my_task" instead of "hatchet.start_step_run"
      */
     includeTaskNameInSpanName: v4_1.z.boolean().optional().default(false),
+    /**
+     * If true, a child `hatchet.run_workflow` span is created for each item in a
+     * bulk run (`runWorkflows`), nested under the parent `hatchet.run_workflows`
+     * span, and each item's traceparent points at its own span. Defaults to false
+     * to preserve the existing span structure for downstream OpenTelemetry
+     * collectors.
+     */
+    individualRunSpansForBulkRun: v4_1.z.boolean().optional().default(false),
 });
 const TaskMiddlewareSchema = v4_1.z
     .object({

package/opentelemetry/instrumentor.js

@@ -35,7 +35,7 @@ catch (_a) {
 const otelApi = require('@opentelemetry/api');
 const otelInstrumentation = require('@opentelemetry/instrumentation');
 /* eslint-enable @typescript-eslint/no-require-imports */
-const { context, propagation, SpanKind, SpanStatusCode, diag } = otelApi;
+const { context, propagation, SpanKind, SpanStatusCode, diag, trace } = otelApi;
 const { InstrumentationBase, InstrumentationNodeModuleDefinition, InstrumentationNodeModuleFile, isWrapped, } = otelInstrumentation;
 const INSTRUMENTOR_NAME = '@hatchet-dev/typescript-sdk';
 // FIXME: refactor version check to use the new pattern introduced in #2954
@@ -354,23 +354,84 @@ class HatchetInstrumentor extends InstrumentationBase {
                     return tracer.startActiveSpan('hatchet.run_workflows', {
                         kind: SpanKind.PRODUCER,
                         attributes,
-                    }, (span) => {
-                        const enhancedWorkflowRuns = workflowRuns.map((run) => {
-                            var _a, _b;
-                            const enhancedMetadata = Object.assign({}, ((_b = (_a = run.options) === null || _a === void 0 ? void 0 : _a.additionalMetadata) !== null && _b !== void 0 ? _b : {}));
-                            injectContext(enhancedMetadata);
-                            return Object.assign(Object.assign({}, run), { options: Object.assign(Object.assign({}, run.options), { additionalMetadata: enhancedMetadata }) });
-                        });
-                        return original
-                            .call(this, enhancedWorkflowRuns, batchSize)
-                            .catch((error) => {
-                            span.recordException(error);
-                            span.setStatus({ code: SpanStatusCode.ERROR, message: error === null || error === void 0 ? void 0 : error.message });
+                    }, (batchSpan) => {
+                        const individualSpans = getConfig().individualRunSpansForBulkRun;
+                        const itemSpans = [];
+                        let enhancedWorkflowRuns;
+                        try {
+                            enhancedWorkflowRuns = workflowRuns.map((run) => {
+                                var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+                                const enhancedMetadata = Object.assign({}, ((_b = (_a = run.options) === null || _a === void 0 ? void 0 : _a.additionalMetadata) !== null && _b !== void 0 ? _b : {}));
+                                if (individualSpans) {
+                                    const itemAttributes = filterAttributes({
+                                        [opentelemetry_1.OTelAttribute.WORKFLOW_NAME]: run.workflowName,
+                                        [opentelemetry_1.OTelAttribute.ACTION_PAYLOAD]: JSON.stringify(run.input),
+                                        [opentelemetry_1.OTelAttribute.PARENT_ID]: (_c = run.options) === null || _c === void 0 ? void 0 : _c.parentId,
+                                        [opentelemetry_1.OTelAttribute.PARENT_STEP_RUN_ID]: (_d = run.options) === null || _d === void 0 ? void 0 : _d.parentStepRunId,
+                                        [opentelemetry_1.OTelAttribute.CHILD_INDEX]: (_e = run.options) === null || _e === void 0 ? void 0 : _e.childIndex,
+                                        [opentelemetry_1.OTelAttribute.CHILD_KEY]: (_f = run.options) === null || _f === void 0 ? void 0 : _f.childKey,
+                                        [opentelemetry_1.OTelAttribute.ADDITIONAL_METADATA]: ((_g = run.options) === null || _g === void 0 ? void 0 : _g.additionalMetadata)
+                                            ? JSON.stringify(run.options.additionalMetadata)
+                                            : undefined,
+                                        [opentelemetry_1.OTelAttribute.PRIORITY]: (_h = run.options) === null || _h === void 0 ? void 0 : _h.priority,
+                                        [opentelemetry_1.OTelAttribute.DESIRED_WORKER_ID]: (_j = run.options) === null || _j === void 0 ? void 0 : _j.desiredWorkerId,
+                                    }, getConfig().excludedAttributes);
+                                    const itemSpan = tracer.startSpan('hatchet.run_workflow', {
+                                        kind: SpanKind.PRODUCER,
+                                        attributes: itemAttributes,
+                                    });
+                                    itemSpans.push(itemSpan);
+                                    propagation.inject(trace.setSpan(context.active(), itemSpan), enhancedMetadata);
+                                }
+                                else {
+                                    // Legacy behaviour: inject the active (batch) span context so the
+                                    // span structure seen by downstream collectors is unchanged.
+                                    injectContext(enhancedMetadata);
+                                }
+                                return Object.assign(Object.assign({}, run), { options: Object.assign(Object.assign({}, run.options), { additionalMetadata: enhancedMetadata }) });
+                            });
+                        }
+                        catch (error) {
+                            const err = error;
+                            batchSpan.recordException(err);
+                            batchSpan.setStatus({ code: SpanStatusCode.ERROR, message: err === null || err === void 0 ? void 0 : err.message });
+                            itemSpans.forEach((s) => {
+                                s.recordException(err);
+                                s.setStatus({ code: SpanStatusCode.ERROR, message: err === null || err === void 0 ? void 0 : err.message });
+                                s.end();
+                            });
+                            batchSpan.end();
                             throw error;
-                        })
-                            .finally(() => {
-                            span.end();
-                        });
+                        }
+                        try {
+                            return original
+                                .call(this, enhancedWorkflowRuns, batchSize)
+                                .catch((error) => {
+                                batchSpan.recordException(error);
+                                batchSpan.setStatus({ code: SpanStatusCode.ERROR, message: error === null || error === void 0 ? void 0 : error.message });
+                                itemSpans.forEach((s) => {
+                                    s.recordException(error);
+                                    s.setStatus({ code: SpanStatusCode.ERROR, message: error === null || error === void 0 ? void 0 : error.message });
+                                });
+                                throw error;
+                            })
+                                .finally(() => {
+                                itemSpans.forEach((s) => s.end());
+                                batchSpan.end();
+                            });
+                        }
+                        catch (error) {
+                            const err = error;
+                            batchSpan.recordException(err);
+                            batchSpan.setStatus({ code: SpanStatusCode.ERROR, message: err === null || err === void 0 ? void 0 : err.message });
+                            itemSpans.forEach((s) => {
+                                s.recordException(err);
+                                s.setStatus({ code: SpanStatusCode.ERROR, message: err === null || err === void 0 ? void 0 : err.message });
+                                s.end();
+                            });
+                            batchSpan.end();
+                            throw error;
+                        }
                     });
                 });
             };

package/opentelemetry/types.d.ts

@@ -2,5 +2,6 @@ export type { OpenTelemetryConfig } from '../clients/hatchet-client/client-confi
 export declare const DEFAULT_CONFIG: {
     excludedAttributes: string[];
     includeTaskNameInSpanName: boolean;
+    individualRunSpansForBulkRun: boolean;
     enableHatchetCollector: boolean;
 };

package/opentelemetry/types.js

@@ -4,5 +4,6 @@ exports.DEFAULT_CONFIG = void 0;
 exports.DEFAULT_CONFIG = {
     excludedAttributes: [],
     includeTaskNameInSpanName: false,
+    individualRunSpansForBulkRun: false,
     enableHatchetCollector: true,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatchet-dev/typescript-sdk",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Background task orchestration & visibility for developers",
   "types": "dist/index.d.ts",
   "files": [
@@ -19,6 +19,7 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1042.0",
     "@eslint/js": "^10.0.1",
     "@types/jest": "^29.5.14",
     "@types/node": "^22.13.14",
@@ -43,7 +44,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.148",
     "@grpc/grpc-js": "^1.14.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openai/agents": "0.11.4",
+    "@openai/agents": "0.11.6",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^2.0.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.218.0",
@@ -75,7 +76,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.148",
     "@grpc/grpc-js": "^1.14.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openai/agents": "0.11.4",
+    "@openai/agents": "0.11.6",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^2.0.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.218.0",

package/util/config-loader/config-loader.js

@@ -86,6 +86,7 @@ class ConfigLoader {
         const otelConfig = (_5 = (_4 = override === null || override === void 0 ? void 0 : override.otel) !== null && _4 !== void 0 ? _4 : yaml === null || yaml === void 0 ? void 0 : yaml.otel) !== null && _5 !== void 0 ? _5 : {
             excludedAttributes: this.parseJsonArray(this.env('HATCHET_CLIENT_OPENTELEMETRY_EXCLUDED_ATTRIBUTES') || '[]'),
             includeTaskNameInSpanName: this.env('HATCHET_CLIENT_OPENTELEMETRY_INCLUDE_TASK_NAME_IN_SPAN_NAME') === 'true',
+            individualRunSpansForBulkRun: this.env('HATCHET_CLIENT_OPENTELEMETRY_INDIVIDUAL_RUN_SPANS_FOR_BULK_RUN') === 'true',
         };
         const grpcMaxRecvMessageLength = (_8 = (_7 = (_6 = override === null || override === void 0 ? void 0 : override.grpc_max_recv_message_length) !== null && _6 !== void 0 ? _6 : yaml === null || yaml === void 0 ? void 0 : yaml.grpc_max_recv_message_length) !== null && _7 !== void 0 ? _7 : this.parseIntEnv('HATCHET_CLIENT_GRPC_MAX_RECV_MESSAGE_LENGTH')) !== null && _8 !== void 0 ? _8 : 4 * 1024 * 1024;
         const grpcMaxSendMessageLength = (_11 = (_10 = (_9 = override === null || override === void 0 ? void 0 : override.grpc_max_send_message_length) !== null && _9 !== void 0 ? _9 : yaml === null || yaml === void 0 ? void 0 : yaml.grpc_max_send_message_length) !== null && _10 !== void 0 ? _10 : this.parseIntEnv('HATCHET_CLIENT_GRPC_MAX_SEND_MESSAGE_LENGTH')) !== null && _11 !== void 0 ? _11 : 4 * 1024 * 1024;

package/v1/client/features/runs.d.ts

@@ -3,6 +3,24 @@ import { V1TaskStatus } from '../../../clients/rest/generated/data-contracts';
 import { RunListenerClient } from '../../../clients/listeners/run-listener/child-listener-client';
 import { WorkflowsClient } from './workflows';
 import { HatchetClient } from '../client';
+import { runStatusToJSON } from '../../../protoc/v1/workflows';
+export type RunDetail = {
+    status: V1TaskStatus;
+    done: boolean;
+    input: unknown;
+    additionalMetadata: unknown;
+    isEvicted: boolean;
+    taskRuns: Record<string, TaskRunDetail>;
+};
+export type TaskRunDetail = {
+    externalId: string;
+    readableId: string;
+    status: V1TaskStatus;
+    output: unknown;
+    error?: string;
+    isEvicted: boolean;
+};
+export { runStatusToJSON };
 export type RunFilter = {
     since?: Date;
     until?: Date;
@@ -72,7 +90,10 @@ export declare class RunsClient {
     tenantId: string;
     workflows: WorkflowsClient;
     listener: RunListenerClient;
+    private _config;
+    private _adminGrpc;
     constructor(client: HatchetClient);
+    private get adminGrpc();
     /**
      * Gets a task or workflow run by its ID.
      * @param run - The ID of the run to get.
@@ -85,6 +106,12 @@ export declare class RunsClient {
      * @returns A promise that resolves to the status of the run.
      */
     get_status<T = any>(run: string | WorkflowRunRef<T>): Promise<V1TaskStatus>;
+    /**
+     * Gets run details
+     * @param run - The workflow run ID (string) or a WorkflowRunRef.
+     * @returns A promise resolving to GetRunDetailsResponse with task run statuses and outputs.
+     */
+    getDetails<T = any>(run: string | WorkflowRunRef<T>): Promise<RunDetail>;
     /**
      * Lists all task and workflow runs for the current tenant.
      * @param opts - The options for the list operation.

package/v1/client/features/runs.js

@@ -32,9 +32,57 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RunsClient = void 0;
+exports.RunsClient = exports.runStatusToJSON = void 0;
 const workflow_run_ref_1 = __importDefault(require("../../../util/workflow-run-ref"));
+const data_contracts_1 = require("../../../clients/rest/generated/data-contracts");
 const child_listener_client_1 = require("../../../clients/listeners/run-listener/child-listener-client");
+const workflows_1 = require("../../../protoc/v1/workflows");
+Object.defineProperty(exports, "runStatusToJSON", { enumerable: true, get: function () { return workflows_1.runStatusToJSON; } });
+const grpc_helpers_1 = require("../../../util/grpc-helpers");
+// EVICTED is not in V1TaskStatus; treat as RUNNING per the proto comment.
+const PROTO_STATUS_MAP = {
+    [workflows_1.RunStatus.QUEUED]: data_contracts_1.V1TaskStatus.QUEUED,
+    [workflows_1.RunStatus.RUNNING]: data_contracts_1.V1TaskStatus.RUNNING,
+    [workflows_1.RunStatus.COMPLETED]: data_contracts_1.V1TaskStatus.COMPLETED,
+    [workflows_1.RunStatus.FAILED]: data_contracts_1.V1TaskStatus.FAILED,
+    [workflows_1.RunStatus.CANCELLED]: data_contracts_1.V1TaskStatus.CANCELLED,
+    [workflows_1.RunStatus.EVICTED]: data_contracts_1.V1TaskStatus.RUNNING,
+    [workflows_1.RunStatus.UNRECOGNIZED]: data_contracts_1.V1TaskStatus.RUNNING,
+};
+function decodeBytes(b) {
+    if (!(b === null || b === void 0 ? void 0 : b.length))
+        return null;
+    try {
+        return JSON.parse(new TextDecoder().decode(b));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function toRunDetail(raw) {
+    var _a;
+    return {
+        status: (_a = PROTO_STATUS_MAP[raw.status]) !== null && _a !== void 0 ? _a : data_contracts_1.V1TaskStatus.RUNNING,
+        done: raw.done,
+        input: decodeBytes(raw.input),
+        additionalMetadata: decodeBytes(raw.additionalMetadata),
+        isEvicted: raw.isEvicted,
+        taskRuns: Object.fromEntries(Object.entries(raw.taskRuns).map(([id, tr]) => {
+            var _a;
+            return [
+                id,
+                {
+                    externalId: tr.externalId,
+                    readableId: tr.readableId,
+                    status: (_a = PROTO_STATUS_MAP[tr.status]) !== null && _a !== void 0 ? _a : data_contracts_1.V1TaskStatus.RUNNING,
+                    output: decodeBytes(tr.output),
+                    error: tr.error,
+                    isEvicted: tr.isEvicted,
+                },
+            ];
+        })),
+    };
+}
 /**
  * The runs client is a client for interacting with task and workflow runs within Hatchet.
  */
@@ -44,6 +92,14 @@ class RunsClient {
         this.tenantId = client.tenantId;
         this.workflows = client.workflows;
         this.listener = client._listener;
+        this._config = client.config;
+    }
+    get adminGrpc() {
+        if (!this._adminGrpc) {
+            const { client } = (0, grpc_helpers_1.createGrpcClient)(this._config, workflows_1.AdminServiceDefinition);
+            this._adminGrpc = client;
+        }
+        return this._adminGrpc;
     }
     /**
      * Gets a task or workflow run by its ID.
@@ -69,6 +125,17 @@ class RunsClient {
             return data;
         });
     }
+    /**
+     * Gets run details
+     * @param run - The workflow run ID (string) or a WorkflowRunRef.
+     * @returns A promise resolving to GetRunDetailsResponse with task run statuses and outputs.
+     */
+    getDetails(run) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const runId = typeof run === 'string' ? run : yield run.getWorkflowRunId();
+            return toRunDetail(yield this.adminGrpc.getRunDetails({ externalId: runId }));
+        });
+    }
     /**
      * Lists all task and workflow runs for the current tenant.
      * @param opts - The options for the list operation.

package/v1/client/features/workflows.js

@@ -79,6 +79,7 @@ class WorkflowsClient {
      */
     get(workflow) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             // Get workflow name string
             const name = (0, exports.workflowNameString)(workflow);
             // Check cache first
@@ -94,8 +95,7 @@ class WorkflowsClient {
                     name,
                 });
                 if (data && data.rows && data.rows.length > 0) {
-                    const [wf] = data.rows;
-                    // Cache the result
+                    const wf = (_a = data.rows.find((row) => row.name === name)) !== null && _a !== void 0 ? _a : data.rows[0];
                     this.workflowCache.set(name, {
                         workflow: wf,
                         expiry: Date.now() + this.cacheTTL,

package/v1/examples/aws/s3/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/v1/examples/aws/s3/worker.js

@@ -0,0 +1,177 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var _a, _b, _c, _d;
+Object.defineProperty(exports, "__esModule", { value: true });
+const client_s3_1 = require("@aws-sdk/client-s3");
+const v1_1 = require("../../..");
+const hatchet_client_1 = require("../../hatchet-client");
+const BUCKET_PREFIX = (_a = process.env.S3_WORKER_BUCKET_PREFIX) !== null && _a !== void 0 ? _a : 'bucket-';
+const MAX_CONCURRENT_BUCKET_POLLERS = parseInt((_b = process.env.S3_WORKER_MAX_CONCURRENT_BUCKET_POLLERS) !== null && _b !== void 0 ? _b : '10');
+const MAX_RUNS_PER_BUCKET = parseInt((_c = process.env.S3_WORKER_MAX_RUNS_PER_BUCKET) !== null && _c !== void 0 ? _c : '20');
+const SLOTS = parseInt((_d = process.env.S3_WORKER_SLOTS) !== null && _d !== void 0 ? _d : '40');
+// > Client Setup
+const s3 = new client_s3_1.S3Client({ forcePathStyle: true });
+// !!
+// > Fetch S3 Buckets
+const fetchBucketsWorkflow = hatchet_client_1.hatchet.workflow({
+    name: 'fetch_s3_buckets',
+    on: {
+        cron: '* * * * *',
+    },
+    concurrency: {
+        expression: "'singleton'",
+        maxRuns: 1,
+        limitStrategy: v1_1.ConcurrencyLimitStrategy.CANCEL_NEWEST,
+    },
+});
+// !!
+// > Fetch S3 Objects
+const fetchObjectsWorkflow = hatchet_client_1.hatchet.workflow({
+    name: 'fetch_s3_objects',
+    concurrency: [
+        {
+            expression: 'input.bucket',
+            maxRuns: 1,
+            limitStrategy: v1_1.ConcurrencyLimitStrategy.CANCEL_NEWEST,
+        },
+        {
+            expression: "'constant'",
+            maxRuns: MAX_CONCURRENT_BUCKET_POLLERS,
+            limitStrategy: v1_1.ConcurrencyLimitStrategy.GROUP_ROUND_ROBIN,
+        },
+    ],
+});
+// !!
+// > Process S3 Objects
+const processObjectWorkflow = hatchet_client_1.hatchet.workflow({
+    name: 'process_object',
+    concurrency: {
+        expression: 'input.bucket',
+        maxRuns: MAX_RUNS_PER_BUCKET,
+        limitStrategy: v1_1.ConcurrencyLimitStrategy.GROUP_ROUND_ROBIN,
+    },
+});
+// !!
+// > Fetch S3 Buckets Task
+fetchBucketsWorkflow.task({
+    name: 'fetch_buckets',
+    fn: () => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, e_1, _b, _c;
+        var _d;
+        try {
+            for (var _e = true, _f = __asyncValues((0, client_s3_1.paginateListBuckets)({ client: s3, pageSize: 10 }, { Prefix: BUCKET_PREFIX })), _g; _g = yield _f.next(), _a = _g.done, !_a; _e = true) {
+                _c = _g.value;
+                _e = false;
+                const page = _c;
+                const items = ((_d = page.Buckets) !== null && _d !== void 0 ? _d : [])
+                    .filter((bucket) => bucket.Name !== undefined)
+                    .map((bucket) => ({
+                    input: { bucket: bucket.Name },
+                    opts: {
+                        childKey: bucket.Name,
+                        additionalMetadata: { 'bucket-name': bucket.Name },
+                    },
+                }));
+                if (items.length > 0) {
+                    yield fetchObjectsWorkflow.runManyNoWait(items);
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_e && !_a && (_b = _f.return)) yield _b.call(_f);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        return {};
+    }),
+});
+// !!
+// > Fetch S3 Objects Task
+fetchObjectsWorkflow.task({
+    name: 'fetch_objects',
+    fn: (input) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, e_2, _b, _c;
+        var _d;
+        try {
+            for (var _e = true, _f = __asyncValues((0, client_s3_1.paginateListObjectsV2)({ client: s3, pageSize: 100 }, { Bucket: input.bucket })), _g; _g = yield _f.next(), _a = _g.done, !_a; _e = true) {
+                _c = _g.value;
+                _e = false;
+                const page = _c;
+                const items = ((_d = page.Contents) !== null && _d !== void 0 ? _d : [])
+                    .filter((obj) => obj.Key !== undefined)
+                    .map((obj) => ({
+                    input: { bucket: input.bucket, key: obj.Key },
+                    opts: {
+                        childKey: `${input.bucket}/${obj.Key}`,
+                    },
+                }));
+                if (items.length > 0) {
+                    yield processObjectWorkflow.runManyNoWait(items);
+                }
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (!_e && !_a && (_b = _f.return)) yield _b.call(_f);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        return {};
+    }),
+});
+// !!
+// > Download and Process S3 Objects Task
+processObjectWorkflow.task({
+    name: 'process_object',
+    fn: (input, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+        let body;
+        try {
+            const response = yield s3.send(new client_s3_1.GetObjectCommand({ Bucket: input.bucket, Key: input.key }));
+            if (!response.Body) {
+                return {};
+            }
+            body = Buffer.from(yield response.Body.transformToByteArray());
+        }
+        catch (err) {
+            if (err instanceof client_s3_1.NoSuchKey || err instanceof client_s3_1.NoSuchBucket) {
+                yield ctx.log(`skipping ${input.bucket}/${input.key}: not found`);
+                return {};
+            }
+            throw err;
+        }
+        // TODO: actual image processing here
+        yield s3.send(new client_s3_1.DeleteObjectCommand({ Bucket: input.bucket, Key: input.key }));
+        return {};
+    }),
+});
+// !!
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const worker = yield hatchet_client_1.hatchet.worker('s3-worker', {
+            workflows: [fetchBucketsWorkflow, fetchObjectsWorkflow, processObjectWorkflow],
+            slots: SLOTS,
+        });
+        yield worker.start();
+    });
+}
+if (require.main === module) {
+    main();
+}

package/v1/examples/support_agent_tools/agent-claude.d.ts

@@ -0,0 +1 @@
+export {};

package/v1/examples/support_agent_tools/agent-claude.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const tools_1 = require("./tools");
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, e_1, _b, _c;
+        const lookupCustomerTool = (0, tools_1.createLookupCustomerToolClaude)();
+        const checkOrderStatusTool = (0, tools_1.createCheckOrderStatusToolClaude)();
+        const ticketTool = (0, tools_1.createTicketToolClaude)();
+        // The Claude Agent SDK is ESM-only, so avoid loading it at module import time.
+        // Run this example with an ESM-compatible TypeScript runner.
+        const { query, createSdkMcpServer } = yield Promise.resolve().then(() => __importStar(require('@anthropic-ai/claude-agent-sdk')));
+        // Wrap the tools in an in-process MCP server
+        const supportServer = createSdkMcpServer({
+            name: 'support',
+            version: '1.0.0',
+            tools: [lookupCustomerTool, checkOrderStatusTool, ticketTool],
+        });
+        try {
+            for (var _d = true, _e = __asyncValues(query({
+                prompt: 'Customer C-100 says order ORD-9987 has not arrived. ' +
+                    'Look up the customer, check the order status, and create a ' +
+                    'support ticket if the order has a known issue or delayed delivery. ' +
+                    'If you create a ticket, use priority "high", subject ' +
+                    '"Delayed order ORD-9987", and a body that summarizes the known ' +
+                    'carrier delay. Then summarize what happened.',
+                options: {
+                    mcpServers: { support: supportServer },
+                    allowedTools: [
+                        `mcp__${supportServer.name}__${lookupCustomerTool.name}`,
+                        `mcp__${supportServer.name}__${checkOrderStatusTool.name}`,
+                        `mcp__${supportServer.name}__${ticketTool.name}`,
+                    ],
+                },
+            })), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                _c = _f.value;
+                _d = false;
+                const message = _c;
+                // "result" is the final message after all tool calls complete
+                if (message.type === 'result' && message.subtype === 'success') {
+                    console.log(message.result);
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    });
+}
+if (require.main === module) {
+    main()
+        .catch(console.error)
+        .finally(() => {
+        process.exit(0);
+    });
+}

package/v1/examples/support_agent_tools/agent-openai.d.ts

@@ -0,0 +1 @@
+export {};

package/v1/examples/support_agent_tools/agent-openai.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const tools_1 = require("./tools");
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const lookupCustomerTool = (0, tools_1.createLookupCustomerToolOpenai)();
+        const checkOrderStatusTool = (0, tools_1.createCheckOrderStatusToolOpenai)();
+        const ticketTool = (0, tools_1.createTicketToolOpenai)();
+        // Dynamic import — @openai/agents crashes at load time with Zod v3, so we delay
+        // the import until after mcpTool has already verified Zod v4 is available.
+        const { Agent, run } = yield Promise.resolve().then(() => __importStar(require('@openai/agents')));
+        const agent = new Agent({
+            name: 'support-agent',
+            tools: [lookupCustomerTool, checkOrderStatusTool, ticketTool],
+        });
+        const result = yield run(agent, 'Customer C-100 says order ORD-9987 has not arrived. ' +
+            'Look up the customer, check the order status, and create a ' +
+            'support ticket if the order has a known issue or delayed delivery. ' +
+            'If you create a ticket, use priority "high", subject ' +
+            '"Delayed order ORD-9987", and a body that summarizes the known ' +
+            'carrier delay. Then summarize what happened.');
+        console.log(result.finalOutput);
+    });
+}
+if (require.main === module) {
+    main()
+        .catch(console.error)
+        .finally(() => {
+        process.exit(0);
+    });
+}

package/v1/examples/support_agent_tools/tools.d.ts

@@ -0,0 +1,45 @@
+type CustomerInfo = {
+    customerId: string;
+    name: string;
+    email: string;
+    plan: string;
+    accountStatus: string;
+    defaultOrderId: string;
+    supportTier: string;
+};
+type OrderStatus = {
+    orderId: string;
+    status: string;
+    lastUpdated: string;
+    estimatedDelivery: string;
+    knownIssue: string | null;
+    carrier: string;
+    trackingNumber: string;
+};
+type TicketResult = {
+    ticketId: string;
+    status: string;
+    priority: string;
+    routingTeam: string;
+    summary: string;
+};
+export declare const lookupCustomer: import("../..").TaskWorkflowDeclaration<{
+    customerId: string;
+}, CustomerInfo, {}, {}, {}, {}>;
+export declare const checkOrderStatus: import("../..").TaskWorkflowDeclaration<{
+    orderId: string;
+}, OrderStatus, {}, {}, {}, {}>;
+export declare const createTicket: import("../..").TaskWorkflowDeclaration<{
+    customerId: string;
+    orderId: string;
+    subject: string;
+    body: string;
+    priority: string;
+}, TicketResult, {}, {}, {}, {}>;
+export declare function createLookupCustomerToolClaude(): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition;
+export declare function createCheckOrderStatusToolClaude(): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition;
+export declare function createTicketToolClaude(): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition;
+export declare function createLookupCustomerToolOpenai(): import("@openai/agents").FunctionTool;
+export declare function createCheckOrderStatusToolOpenai(): import("@openai/agents").FunctionTool;
+export declare function createTicketToolOpenai(): import("@openai/agents").FunctionTool;
+export {};

package/v1/examples/support_agent_tools/tools.js

@@ -0,0 +1,144 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTicket = exports.checkOrderStatus = exports.lookupCustomer = void 0;
+exports.createLookupCustomerToolClaude = createLookupCustomerToolClaude;
+exports.createCheckOrderStatusToolClaude = createCheckOrderStatusToolClaude;
+exports.createTicketToolClaude = createTicketToolClaude;
+exports.createLookupCustomerToolOpenai = createLookupCustomerToolOpenai;
+exports.createCheckOrderStatusToolOpenai = createCheckOrderStatusToolOpenai;
+exports.createTicketToolOpenai = createTicketToolOpenai;
+// > Setup
+const v4_1 = require("zod/v4");
+const hatchet_client_1 = require("../hatchet-client");
+// !!
+// > Models
+const CustomerLookupInput = v4_1.z.object({
+    customerId: v4_1.z.string(),
+});
+const OrderStatusInput = v4_1.z.object({
+    orderId: v4_1.z.string(),
+});
+const CreateTicketInput = v4_1.z.object({
+    customerId: v4_1.z.string(),
+    orderId: v4_1.z.string(),
+    subject: v4_1.z.string(),
+    body: v4_1.z.string(),
+    priority: v4_1.z.string(),
+});
+// !!
+// > Fixture data
+const CUSTOMERS = {
+    'C-100': {
+        customerId: 'C-100',
+        name: 'Alice Martin',
+        email: 'alice@example.com',
+        plan: 'business',
+        accountStatus: 'active',
+        defaultOrderId: 'ORD-9987',
+        supportTier: 'priority',
+    },
+};
+const ORDERS = {
+    'ORD-9987': {
+        orderId: 'ORD-9987',
+        status: 'delayed',
+        lastUpdated: '2026-05-20T14:30:00Z',
+        estimatedDelivery: '2026-05-28',
+        knownIssue: 'Carrier reported weather delay at regional hub',
+        carrier: 'FastShip',
+        trackingNumber: 'FS-482910',
+    },
+};
+// !!
+// > Lookup customer
+exports.lookupCustomer = hatchet_client_1.hatchet.task({
+    name: 'lookup-customer',
+    inputValidator: CustomerLookupInput,
+    description: 'Look up a customer by ID and return their profile, plan, and support tier.',
+    fn: (input) => __awaiter(void 0, void 0, void 0, function* () {
+        const customer = CUSTOMERS[input.customerId];
+        if (!customer) {
+            return {
+                customerId: input.customerId,
+                name: 'Unknown',
+                email: 'unknown@example.com',
+                plan: 'none',
+                accountStatus: 'not_found',
+                defaultOrderId: '',
+                supportTier: 'standard',
+            };
+        }
+        return customer;
+    }),
+});
+// !!
+// > Check order status
+exports.checkOrderStatus = hatchet_client_1.hatchet.task({
+    name: 'check-order-status',
+    inputValidator: OrderStatusInput,
+    description: 'Check the current status, carrier, and any known issues for an order.',
+    fn: (input) => __awaiter(void 0, void 0, void 0, function* () {
+        const order = ORDERS[input.orderId];
+        if (!order) {
+            return {
+                orderId: input.orderId,
+                status: 'not_found',
+                lastUpdated: '',
+                estimatedDelivery: '',
+                knownIssue: null,
+                carrier: 'unknown',
+                trackingNumber: '',
+            };
+        }
+        return order;
+    }),
+});
+// !!
+// > Create ticket
+exports.createTicket = hatchet_client_1.hatchet.task({
+    name: 'create-ticket',
+    inputValidator: CreateTicketInput,
+    description: 'Create a support ticket for a customer issue and return the ticket ID and routing.',
+    fn: (input) => __awaiter(void 0, void 0, void 0, function* () {
+        const ticketId = `TICKET-${input.customerId}-001`;
+        return {
+            ticketId,
+            status: 'open',
+            priority: input.priority,
+            routingTeam: 'shipping-support',
+            summary: `Ticket ${ticketId} created for ${input.customerId} regarding order ${input.orderId}: ${input.subject}`,
+        };
+    }),
+});
+// !!
+// > Create Claude tools
+function createLookupCustomerToolClaude() {
+    return exports.lookupCustomer.mcpTool('claude');
+}
+function createCheckOrderStatusToolClaude() {
+    return exports.checkOrderStatus.mcpTool('claude');
+}
+function createTicketToolClaude() {
+    return exports.createTicket.mcpTool('claude');
+}
+// !!
+// > Create openai tools
+function createLookupCustomerToolOpenai() {
+    return exports.lookupCustomer.mcpTool('openai');
+}
+function createCheckOrderStatusToolOpenai() {
+    return exports.checkOrderStatus.mcpTool('openai');
+}
+function createTicketToolOpenai() {
+    return exports.createTicket.mcpTool('openai');
+}
+// !!

package/v1/examples/support_agent_tools/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/v1/examples/support_agent_tools/worker.js

@@ -0,0 +1,24 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const hatchet_client_1 = require("../hatchet-client");
+const tools_1 = require("./tools");
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const worker = yield hatchet_client_1.hatchet.worker('support-tools-worker', {
+            workflows: [tools_1.lookupCustomer, tools_1.checkOrderStatus, tools_1.createTicket],
+        });
+        yield worker.start();
+    });
+}
+if (require.main === module) {
+    main();
+}

package/v1/index.d.ts

@@ -1,5 +1,6 @@
 export * from './client/client';
 export * from './client/features';
+export type { RunDetail, TaskRunDetail } from './client/features/runs';
 export * from './client/worker/worker';
 export * from './declaration';
 export * from './conditions';

package/version.d.ts

@@ -1 +1 @@
-export declare const HATCHET_VERSION = "1.23.0";
+export declare const HATCHET_VERSION = "1.24.0";

package/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HATCHET_VERSION = void 0;
-exports.HATCHET_VERSION = '1.23.0';
+exports.HATCHET_VERSION = '1.24.0';