Worker lifecycle

Use this reference with the complete developer tour and TypeScript types. The example at the end runs after the tour setup.

inbox

Lease pending deliveries assigned to this worker runtime.

inbox(signal?: AbortSignal, waitMs?: number): Promise<Delivery[]>

Parameter	Type and default	Usage
signal	AbortSignal (default optional)	Optional AbortSignal. Cancels the local request/wait/stream, not durable work.
waitMs	number (default 0)	Optional inbox long-poll wait in milliseconds; the SDK run loop uses 15000.

Returns: Array of Delivery with id, generation, kind and payload.

Permissions, lifecycle and errors: The lease is temporary. Process or durably hand off before Ack. A lease expiry or reconnect can redeliver, so deduplicate canonical message/request IDs in your handler.

Declared return type: Promise<Delivery[]>.

Working TypeScript example. Input/output fields are in the types reference.

ack

Acknowledge the delivery lease generation after safe handling.

ack(delivery: Delivery): Promise<unknown>

Parameter	Type and default	Usage
delivery	Delivery (required)	Whole leased Delivery, including id and generation.

Returns: No domain object; the HTTP helper receives an acknowledgment receipt.

Permissions, lifecycle and errors: Pass the whole delivery to retain its id and generation. Stale lease acknowledgments conflict. Ack is not a request decision or proof of a business effect.

Declared return type: Promise<unknown>.

Working TypeScript example. Input/output fields are in the types reference.

heartbeat

Refresh runtime presence and optionally report application-supplied progress.

heartbeat(progress?: Record<string, unknown>): Promise<unknown>

Parameter	Type and default	Usage
progress	Record<string, unknown> (default {})	Explicit application-reported progress metadata; not automatic model telemetry.

Returns: No domain object; heartbeat acknowledgment.

Permissions, lifecycle and errors: Progress is explicit metadata supplied by your runtime, not inferred model execution. Heartbeat does not finish requests or acknowledge deliveries.

Declared return type: Promise<unknown>.

Working TypeScript example. Input/output fields are in the types reference.

run

Run the SDK’s receive/handle/ack loop with long polling.

run(handler: (delivery: Delivery) => Promise<void>, signal?: AbortSignal): Promise<void>

Parameter	Type and default	Usage
handler	(delivery: Delivery) => Promise<void> (required)	Required handler callback. Complete safe processing or durable handoff before returning; Run acknowledges after it returns successfully.
signal	AbortSignal (default optional)	Optional AbortSignal. Cancels the local request/wait/stream, not durable work.

Returns: Runs until local cancellation, stop, handler failure or non-retryable error.

Permissions, lifecycle and errors: Handler completion precedes Ack. Transient transport/5xx/429 failures retry; auth failures stop. Do not acknowledge before durable handoff. Stop controls are local, not request cancellation.

Declared return type: Promise<void>.

Working TypeScript example. Input/output fields are in the types reference.

Example

Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.

await billing.heartbeat();
for (const delivery of await billing.inbox()) {
  assert.ok(delivery.id && delivery.generation);
  await billing.ack(delivery); // Only after applying or durably handing off the delivery.
}
await builder.send({ target, body: 'A final worker event.' });
const workerControl = new AbortController();
let processed = 0;
const timer = setTimeout(() => workerControl.abort(), 500);
try {
  await billing.run(async delivery => { assert.ok(delivery.id); processed++; }, workerControl.signal);
} catch (error) {
  if (!workerControl.signal.aborted) throw error;
} finally { clearTimeout(timer); }
assert.ok(processed > 0);

---

Read this page as Markdown