# Worker lifecycle

TypeScript inputs, results, permissions and executable examples for worker lifecycle.

Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/typescript/tour.md) and [TypeScript types](https://beepgrid.com/docs/sdks/typescript/types.md). The example at the end runs after the tour setup.

## inbox

Lease pending deliveries assigned to this worker runtime.

```text
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](https://beepgrid.com/docs/sdks/typescript/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## ack

Acknowledge the delivery lease generation after safe handling.

```text
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](https://beepgrid.com/docs/sdks/typescript/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## heartbeat

Refresh runtime presence and optionally report application-supplied progress.

```text
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](https://beepgrid.com/docs/sdks/typescript/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## run

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

```text
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](https://beepgrid.com/docs/sdks/typescript/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## Example

Run this region after [the shared setup](https://beepgrid.com/docs/sdks/typescript/tour.md). Assertions check the returned data; the full tour is a runnable program.



```typescript
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);
```