@nuetzliches/croniq-runner 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+Initial release. Implements the Croniq runner protocol:
+
+- Poll / ack / renew / events / register endpoints (`/v1/work/*`, `/v1/jobs/register`).
+- ESM-first, Node 18+, native `fetch` and `AbortController`.
+- Streaming `LogWriter` with batch-by-count, batch-by-time, drain-before-ack semantics.
+- Per-execution `AbortSignal` honouring `PollResponse.cancel`.
+- Self-registration of schedule-bearing handlers at startup.
+- `Authorization: ApiKey {key}` and `Bearer {token}` precedence.
+- Persistent runner-id resolution (env → state file → generated).
+- Conformance against all 12 cases in [`sdks/conformance/cases/`](../conformance/cases).

package/README.md

@@ -0,0 +1,172 @@
+# Croniq Runner SDK for Node.js
+
+[![npm](https://img.shields.io/npm/v/%40nuetzliches%2Fcroniq-runner.svg)](https://www.npmjs.com/package/@nuetzliches/croniq-runner)
+[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)
+
+Build job execution runners for [Croniq](https://github.com/nuetzliches/croniq) in Node.js / TypeScript. The SDK polls a Croniq server for work, dispatches handlers, streams structured logs back, and reports completion — using native `fetch` and `AbortController`, no extra HTTP dependency.
+
+Aimed at workloads that are Node-native: headless-browser automation (Playwright / Puppeteer), web scraping, npm-ecosystem builds, anything that lives most naturally in a JS toolchain.
+
+## Install
+
+```sh
+npm install @nuetzliches/croniq-runner
+```
+
+(The package name is org-scoped under `@nuetzliches` to align with the project's other npm artefacts. Import path: `import { createRunner } from '@nuetzliches/croniq-runner';`.)
+
+Requires Node.js ≥ 18 (ESM, native `fetch`, `AbortController`).
+
+## Quick start
+
+```ts
+import { createRunner } from '@nuetzliches/croniq-runner';
+
+const runner = createRunner({
+  serverUrl: 'http://localhost:4000',
+  apiKey: process.env.CRONIQ_API_KEY,
+  capabilities: ['demo'],
+  tags: ['env=dev', 'lang=typescript'],
+  maxInflight: 5,
+});
+
+runner.handle('hello:world', async (ctx) => {
+  ctx.logger.info(`Hello from ${ctx.jobKey} (attempt ${ctx.attempt})`);
+  await new Promise((r) => setTimeout(r, 1_000));
+});
+
+// Wire SIGTERM/SIGINT to graceful shutdown.
+const controller = new AbortController();
+for (const sig of ['SIGTERM', 'SIGINT'] as const) {
+  process.on(sig, () => controller.abort());
+}
+
+await runner.run(controller.signal);
+```
+
+## Features
+
+- **ESM-first**, native `fetch` + `AbortController` — no `axios`, no `node-fetch` shim.
+- **Two handler styles**: delegate (`runner.handle('key', fn)`) and a default catch-all (`runner.setDefaultHandler(fn)`).
+- **Server-side cancellation** — `PollResponse.cancel` aborts the handler's `ctx.signal`.
+- **Streaming `LogWriter`** — bounded queue with backpressure, batch by count (32) / by time (200 ms) / max 100 events per POST, **drain-before-ack**.
+- **Self-registration** — `runner.handle('key', fn, { schedule: '5m' })` calls `POST /v1/jobs/register` once at startup (DSL precedence applies server-side).
+- **Auth precedence** — `Authorization: ApiKey {key}` if set, else `Bearer {token}`.
+- **Persistent runner-id** — env var → state file → generated `{prefix}-{hex8}`, persisted under `$XDG_STATE_HOME/croniq-runner` (Linux/macOS) or `%LOCALAPPDATA%\croniq-runner` (Windows).
+- **OpenTelemetry-ready** — bring your own `@opentelemetry/sdk-node` setup; the SDK plays nicely with the standard `@opentelemetry/api` no-op fallback.
+
+## Capabilities vs Tags
+
+Same rule as the .NET / Rust SDKs — **don't put implementation details into capabilities**. Capabilities drive routing (`require` / `prefer` in the Croniqfile); tags are filter-only.
+
+| Good capability                              | Bad capability                |
+| -------------------------------------------- | ----------------------------- |
+| `billing`, `reporting`, `gpu`, `sandboxed`   | `nodejs`, `typescript`, `linux-x64` |
+
+If your runner is Node-based, put that into **tags** (`lang=typescript`, `platform=linux-x64`) so a future Go or Python runner with the same business capabilities can take over without rewriting Croniqfile entries.
+
+## Handler API
+
+The handler receives an `ExecutionContext`:
+
+```ts
+import type { ExecutionContext } from '@nuetzliches/croniq-runner';
+
+runner.handle('billing:invoice', async (ctx: ExecutionContext) => {
+  const meta = ctx.metadata as { customer_id: string };
+
+  // Structured logger pre-scoped with execution_id, job_key, runner_id, attempt.
+  ctx.logger.info('generating invoice', { customer_id: meta.customer_id });
+
+  // Streaming events visible in the Croniq UI execution log:
+  for await (const line of generateInvoice(meta.customer_id, ctx.signal)) {
+    await ctx.logWriter.write('info', line);
+  }
+
+  // ctx.signal aborts when the server cancels OR the runner drain-timeout fires.
+  if (ctx.signal.aborted) return;
+});
+```
+
+`ctx.metadata` is the raw server-provided JSON — cast to your expected shape. Field names are the original snake_case sent by the server.
+
+## Streaming logs
+
+```ts
+runner.handle('export:report', async (ctx) => {
+  const writer = ctx.logWriter;
+  for (let i = 0; i < 100; i++) {
+    await writer.write('info', `processing row ${i}`, { row: String(i) });
+  }
+  // No explicit flush() needed — the runner drains the writer before ack.
+  // Call writer.flush() if you need a synchronization barrier mid-handler.
+});
+```
+
+The writer batches by count and time and survives transient POST failures (drops the batch, logs a warning, keeps going). On per-execution shutdown the runner drains queued events with a configurable timeout (`logWriter.shutdownTimeoutMs`, default 5 s) — late events never arrive after the ack.
+
+## Self-register a schedule
+
+```ts
+runner.handle(
+  'reports:daily',
+  async (ctx) => { /* … */ },
+  { schedule: '1h', timeout: '10m', description: 'rolling 24-hour digest' },
+);
+```
+
+On startup the SDK calls `POST /v1/jobs/register`. If a Croniqfile (DSL) entry with the same `job_key` exists, the server returns `status=skipped_dsl_precedence` and the SDK logs an info message — your runner still polls and executes the job normally, just driven by the DSL schedule rather than the runner-registered one.
+
+## Configuration
+
+| Option                | Default                                              | Description                                                              |
+| --------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------ |
+| `serverUrl`           | _(required)_                                         | Croniq server base URL.                                                  |
+| `runnerId`            | resolved                                             | Stable id. Falls back to `RUNNER_ID` env var → state file → generated.   |
+| `runnerIdPrefix`      | `"runner"`                                           | Used when generating an id.                                              |
+| `runnerDataDir`       | platform default                                     | Where the persistent `runner-id` file lives.                             |
+| `apiKey`              | —                                                    | `Authorization: ApiKey {…}`. Takes precedence over `bearerToken`.        |
+| `bearerToken`         | —                                                    | `Authorization: Bearer {…}`.                                             |
+| `capabilities`        | `[]`                                                 | Routing capabilities.                                                    |
+| `tags`                | `[]`                                                 | Free-form `key=value` tags. Filter-only.                                 |
+| `maxInflight`         | `5`                                                  | Max concurrent in-flight executions.                                     |
+| `pollTimeoutMs`       | `35_000`                                             | Per-request timeout on the long-poll.                                    |
+| `renewIntervalMs`     | `15_000`                                             | Heartbeat cadence for in-flight executions.                              |
+| `drainTimeoutMs`      | `30_000`                                             | Graceful shutdown budget before hard-cancel.                             |
+| `pollRetryDelayMs`    | `5_000`                                              | Back-off after a failed poll.                                            |
+| `capacityBackoffMs`   | `500`                                                | Idle wait when at `maxInflight`.                                         |
+| `logWriter`           | see below                                            | Streaming log-writer tunables.                                           |
+
+LogWriter sub-options: `channelCapacity` (256), `batchSizeThreshold` (32), `batchTimeThresholdMs` (200), `maxBatchPerPost` (100), `shutdownTimeoutMs` (5_000).
+
+## Wire-protocol conformance
+
+Validated against the shared, language-neutral suite at [`sdks/conformance/`](../conformance/) — the same 12 YAML cases the .NET SDK passes. The TypeScript binding lives at [`sdks/conformance/bindings/typescript/`](../conformance/bindings/typescript).
+
+```sh
+cd sdks/conformance/bindings/typescript
+npm install
+npm test
+```
+
+## Releasing
+
+Publishing is fully automated by [`typescript-sdk-release.yml`](../../.github/workflows/typescript-sdk-release.yml). To ship a new version:
+
+1. Bump `version` in [`package.json`](package.json) and update the [CHANGELOG](CHANGELOG.md).
+2. Merge to `main`.
+3. Tag the commit: `git tag ts-sdk-v0.2.0 && git push --tags`.
+
+The workflow re-runs typecheck, lint, unit tests, build, and the full conformance suite against the freshly built artefact, then `npm publish --provenance --access public`. Pre-release tags (anything with a `-`, e.g. `ts-sdk-v0.2.0-rc.1`) publish under the `next` npm dist-tag so `npm install @nuetzliches/croniq-runner` keeps pointing at the latest stable.
+
+Prerequisite: a repo admin must set the `NPM_TOKEN` secret (an npm automation or granular token with publish rights to the `@croniq` scope) once.
+
+## Compatibility matrix
+
+| SDK Version | Node.js     | Croniq Server (min) | Croniq Server (max tested) |
+| ----------- | ----------- | ------------------- | -------------------------- |
+| 0.1.x       | ≥ 18.0.0    | 0.14.0              | 0.14.0                     |
+
+## License
+
+Dual-licensed under MIT OR Apache-2.0. See [LICENSE-MIT](../../LICENSE-MIT) and [LICENSE-APACHE](../../LICENSE-APACHE).

package/dist/abort.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compose multiple AbortSignals into one that aborts as soon as any of the
+ * inputs aborts. A polyfill for `AbortSignal.any()` (Node 20.3+) so this
+ * SDK works on Node 18.
+ */
+export declare function anySignal(...signals: AbortSignal[]): AbortSignal;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,CAuBhE"}

package/dist/abort.js

@@ -0,0 +1,31 @@
+/**
+ * Compose multiple AbortSignals into one that aborts as soon as any of the
+ * inputs aborts. A polyfill for `AbortSignal.any()` (Node 20.3+) so this
+ * SDK works on Node 18.
+ */
+export function anySignal(...signals) {
+    // Fast path: native AbortSignal.any when available.
+    const anyFn = AbortSignal.any;
+    if (typeof anyFn === 'function')
+        return anyFn(signals);
+    const controller = new AbortController();
+    const abort = (reason) => {
+        if (controller.signal.aborted)
+            return;
+        controller.abort(reason);
+        for (const s of signals)
+            s.removeEventListener('abort', listeners.get(s));
+    };
+    const listeners = new Map();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            return controller.signal;
+        }
+        const fn = () => abort(signal.reason);
+        listeners.set(signal, fn);
+        signal.addEventListener('abort', fn, { once: true });
+    }
+    return controller.signal;
+}
+//# sourceMappingURL=abort.js.map

package/dist/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAAG,OAAsB;IACjD,oDAAoD;IACpD,MAAM,KAAK,GAAI,WAAsE,CAAC,GAAG,CAAC;IAC1F,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC;IAEvD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,CAAC,MAAe,EAAQ,EAAE;QACtC,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO;QACtC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACzB,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,CAAC,CAAC,mBAAmB,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC;IAC7E,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;IACrD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAChC,OAAO,UAAU,CAAC,MAAM,CAAC;QAC3B,CAAC;QACD,MAAM,EAAE,GAAG,GAAS,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5C,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC1B,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,UAAU,CAAC,MAAM,CAAC;AAC3B,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+import type { AckRequest, PollRequest, PollResponse, RegisterJobRequest, RegisterJobResponse, RenewRequest, WorkEvent } from './protocol.js';
+import type { Logger } from './logger.js';
+export interface CroniqClientOptions {
+    baseUrl: string;
+    apiKey?: string | undefined;
+    bearerToken?: string | undefined;
+    /** Custom `fetch` implementation. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    logger?: Logger | undefined;
+}
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly path: string;
+    readonly body: string;
+    constructor(status: number, statusText: string, path: string, body: string);
+}
+/**
+ * HTTP client for the Croniq runner API. Adds `Authorization` per request
+ * (ApiKey takes precedence over Bearer when both are set) and serialises
+ * snake_case JSON in/out.
+ */
+export declare class CroniqClient {
+    #private;
+    constructor(opts: CroniqClientOptions);
+    poll(req: PollRequest, timeoutMs: number, signal: AbortSignal): Promise<PollResponse>;
+    ack(req: AckRequest, signal: AbortSignal): Promise<void>;
+    renew(req: RenewRequest, signal: AbortSignal): Promise<void>;
+    pushEvents(executionId: string, events: WorkEvent[], signal: AbortSignal): Promise<void>;
+    registerJob(req: RegisterJobRequest, signal: AbortSignal): Promise<RegisterJobResponse | undefined>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACV,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,qBAAa,SAAU,SAAQ,KAAK;aAEhB,MAAM,EAAE,MAAM;aACd,UAAU,EAAE,MAAM;aAClB,IAAI,EAAE,MAAM;aACZ,IAAI,EAAE,MAAM;gBAHZ,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM;CAK/B;AAED;;;;GAIG;AACH,qBAAa,YAAY;;gBAOX,IAAI,EAAE,mBAAmB;IAQ/B,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAKrF,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxF,WAAW,CAAC,GAAG,EAAE,kBAAkB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;CAgE1G"}

package/dist/client.js

@@ -0,0 +1,147 @@
+import { AbortError } from './deferred.js';
+import { trimTrailingSlashes } from './url.js';
+export class HttpError extends Error {
+    status;
+    statusText;
+    path;
+    body;
+    constructor(status, statusText, path, body) {
+        super(`${status} ${statusText} on ${path}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.path = path;
+        this.body = body;
+        this.name = 'HttpError';
+    }
+}
+/**
+ * HTTP client for the Croniq runner API. Adds `Authorization` per request
+ * (ApiKey takes precedence over Bearer when both are set) and serialises
+ * snake_case JSON in/out.
+ */
+export class CroniqClient {
+    #baseUrl;
+    #apiKey;
+    #bearerToken;
+    #fetch;
+    #logger;
+    constructor(opts) {
+        this.#baseUrl = trimTrailingSlashes(opts.baseUrl);
+        this.#apiKey = opts.apiKey;
+        this.#bearerToken = opts.bearerToken;
+        this.#fetch = opts.fetchImpl ?? fetch;
+        this.#logger = opts.logger;
+    }
+    async poll(req, timeoutMs, signal) {
+        const body = await this.#send('POST', '/v1/work/poll', req, signal, timeoutMs);
+        return body ?? { work: [], cancel: [] };
+    }
+    async ack(req, signal) {
+        await this.#send('POST', '/v1/work/ack', req, signal);
+    }
+    async renew(req, signal) {
+        await this.#send('POST', '/v1/work/renew', req, signal);
+    }
+    async pushEvents(executionId, events, signal) {
+        if (events.length === 0)
+            return;
+        const path = `/v1/work/${encodeURIComponent(executionId)}/events`;
+        await this.#send('POST', path, events, signal);
+    }
+    async registerJob(req, signal) {
+        const body = await this.#send('POST', '/v1/jobs/register', req, signal);
+        if (body?.status === 'skipped_dsl_precedence') {
+            this.#logger?.info(`job ${body.job_key} is managed by the Croniqfile (DSL precedence) — schedule registration skipped`, { job_key: body.job_key });
+        }
+        return body;
+    }
+    async #send(method, path, body, outerSignal, timeoutMs) {
+        const url = `${this.#baseUrl}${path}`;
+        const headers = {
+            'content-type': 'application/json',
+            accept: 'application/json',
+        };
+        if (this.#apiKey) {
+            headers.authorization = `ApiKey ${this.#apiKey}`;
+        }
+        else if (this.#bearerToken) {
+            headers.authorization = `Bearer ${this.#bearerToken}`;
+        }
+        const { signal, dispose } = composeSignals(outerSignal, timeoutMs);
+        let response;
+        try {
+            response = await this.#fetch(url, {
+                method,
+                headers,
+                body: JSON.stringify(body),
+                signal,
+            });
+        }
+        catch (err) {
+            if (isAbortLikeError(err)) {
+                throw new AbortError(`request to ${path} aborted`);
+            }
+            throw err;
+        }
+        finally {
+            dispose();
+        }
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new HttpError(response.status, response.statusText, path, text);
+        }
+        // 204 No Content / empty body — return undefined so callers see `null`-ish.
+        if (response.status === 204)
+            return undefined;
+        const text = await response.text();
+        if (text.length === 0)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            // Some endpoints respond 200 with a non-JSON body — treat as void.
+            return undefined;
+        }
+    }
+}
+function composeSignals(outer, timeoutMs) {
+    if (timeoutMs == null) {
+        return { signal: outer, dispose: () => { } };
+    }
+    // Node 18 doesn't have AbortSignal.any; build one by hand. The caller MUST
+    // invoke dispose() in a finally — otherwise long-lived outer signals
+    // (e.g. the runner's loop signal) accumulate one listener per poll.
+    const ac = new AbortController();
+    let timer;
+    const onOuterAbort = () => {
+        if (timer)
+            clearTimeout(timer);
+        ac.abort(outer.reason);
+    };
+    const dispose = () => {
+        if (timer)
+            clearTimeout(timer);
+        outer.removeEventListener('abort', onOuterAbort);
+    };
+    if (outer.aborted) {
+        ac.abort(outer.reason);
+        return { signal: ac.signal, dispose };
+    }
+    timer = setTimeout(() => {
+        outer.removeEventListener('abort', onOuterAbort);
+        ac.abort(new AbortError('timeout'));
+    }, timeoutMs);
+    outer.addEventListener('abort', onOuterAbort, { once: true });
+    return { signal: ac.signal, dispose };
+}
+function isAbortLikeError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.name === 'AbortError')
+        return true;
+    // undici exposes the original cause for fetch aborts in some Node versions.
+    const cause = err.cause;
+    return cause instanceof Error && cause.name === 'AbortError';
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,82 @@
+import type { CroniqClient } from './client.js';
+import type { LogEnrichment } from './enrichment.js';
+import type { Logger } from './logger.js';
+import { StreamingLogWriter, type LogWriter } from './log-writer.js';
+import type { ResolvedLogWriterOptions } from './options.js';
+import type { WorkEvent, WorkEventLevel } from './protocol.js';
+export interface ExecutionContext {
+    /** Server-assigned execution identifier. */
+    readonly executionId: string;
+    /** Job key, e.g. `billing:invoice`. */
+    readonly jobKey: string;
+    /** 1-based attempt counter, incremented on each retry. */
+    readonly attempt: number;
+    /**
+     * Raw metadata payload from the server. The shape is job-specific — cast
+     * to your expected type. Field names are the original snake_case sent by
+     * the server (no transformation).
+     */
+    readonly metadata: unknown;
+    /** Server-declared timeout for this execution, in milliseconds. */
+    readonly timeoutMs: number;
+    /** The runner's stable identifier. */
+    readonly runnerId: string;
+    /** Free-form tags this runner self-declared. */
+    readonly runnerTags: readonly string[];
+    /**
+     * Combined abort signal: aborts when the server cancels the execution via
+     * `PollResponse.cancel`, OR when the runner's drain timeout elapses while
+     * still in-flight. Handlers should propagate this to downstream awaits.
+     */
+    readonly signal: AbortSignal;
+    /** Logger pre-scoped with `execution_id`, `job_key`, `runner_id`, `attempt`. */
+    readonly logger: Logger;
+    /**
+     * Streaming log writer that POSTs events to the Croniq server's execution
+     * log (visible in the UI). Lazily initialised on first access; the runner
+     * drains the writer (bounded by `logWriter.shutdownTimeoutMs`) before
+     * sending the ack.
+     */
+    readonly logWriter: LogWriter;
+    /**
+     * Push a single event inline (awaits the HTTP POST). For high-volume
+     * scenarios, prefer {@link logWriter}.
+     */
+    pushEvent(level: WorkEventLevel, message: string, fields?: Record<string, string>): Promise<void>;
+    /** Push pre-built events inline. */
+    pushEvents(events: WorkEvent[]): Promise<void>;
+}
+export interface ExecutionContextInput {
+    executionId: string;
+    jobKey: string;
+    attempt: number;
+    metadata: unknown;
+    timeoutMs: number;
+    runnerId: string;
+    runnerTags: readonly string[];
+    signal: AbortSignal;
+    logger: Logger;
+    client: CroniqClient;
+    enrichment: LogEnrichment;
+    logWriterOptions: ResolvedLogWriterOptions;
+    sdkLogger: Logger;
+}
+export declare class ExecutionContextImpl implements ExecutionContext {
+    #private;
+    readonly executionId: string;
+    readonly jobKey: string;
+    readonly attempt: number;
+    readonly metadata: unknown;
+    readonly timeoutMs: number;
+    readonly runnerId: string;
+    readonly runnerTags: readonly string[];
+    readonly signal: AbortSignal;
+    readonly logger: Logger;
+    constructor(input: ExecutionContextInput);
+    get logWriter(): LogWriter;
+    /** Internal accessor — returns the writer only if a handler actually used it. */
+    get logWriterIfCreated(): StreamingLogWriter | null;
+    pushEvent(level: WorkEventLevel, message: string, fields?: Record<string, string>): Promise<void>;
+    pushEvents(events: WorkEvent[]): Promise<void>;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/context.js

@@ -0,0 +1,52 @@
+import { StreamingLogWriter } from './log-writer.js';
+export class ExecutionContextImpl {
+    executionId;
+    jobKey;
+    attempt;
+    metadata;
+    timeoutMs;
+    runnerId;
+    runnerTags;
+    signal;
+    logger;
+    #client;
+    #enrichment;
+    #logWriterOptions;
+    #sdkLogger;
+    #logWriter = null;
+    constructor(input) {
+        this.executionId = input.executionId;
+        this.jobKey = input.jobKey;
+        this.attempt = input.attempt;
+        this.metadata = input.metadata;
+        this.timeoutMs = input.timeoutMs;
+        this.runnerId = input.runnerId;
+        this.runnerTags = input.runnerTags;
+        this.signal = input.signal;
+        this.logger = input.logger;
+        this.#client = input.client;
+        this.#enrichment = input.enrichment;
+        this.#logWriterOptions = input.logWriterOptions;
+        this.#sdkLogger = input.sdkLogger;
+    }
+    get logWriter() {
+        this.#logWriter ??= new StreamingLogWriter(this.#client, this.executionId, this.#enrichment, this.#logWriterOptions, this.#sdkLogger);
+        return this.#logWriter;
+    }
+    /** Internal accessor — returns the writer only if a handler actually used it. */
+    get logWriterIfCreated() {
+        return this.#logWriter;
+    }
+    pushEvent(level, message, fields) {
+        const event = fields ? { level, message, fields } : { level, message };
+        return this.pushEvents([event]);
+    }
+    async pushEvents(events) {
+        if (events.length === 0)
+            return;
+        const enriched = events.map((e) => this.#enrichment.enrich(e));
+        const ac = new AbortController();
+        await this.#client.pushEvents(this.executionId, enriched, ac.signal);
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAkB,MAAM,iBAAiB,CAAC;AAgErE,MAAM,OAAO,oBAAoB;IACtB,WAAW,CAAS;IACpB,MAAM,CAAS;IACf,OAAO,CAAS;IAChB,QAAQ,CAAU;IAClB,SAAS,CAAS;IAClB,QAAQ,CAAS;IACjB,UAAU,CAAoB;IAC9B,MAAM,CAAc;IACpB,MAAM,CAAS;IAEf,OAAO,CAAe;IACtB,WAAW,CAAgB;IAC3B,iBAAiB,CAA2B;IAC5C,UAAU,CAAS;IAC5B,UAAU,GAA8B,IAAI,CAAC;IAE7C,YAAY,KAA4B;QACtC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC,gBAAgB,CAAC;QAChD,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC;IACpC,CAAC;IAED,IAAI,SAAS;QACX,IAAI,CAAC,UAAU,KAAK,IAAI,kBAAkB,CACxC,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,iBAAiB,EACtB,IAAI,CAAC,UAAU,CAChB,CAAC;QACF,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,iFAAiF;IACjF,IAAI,kBAAkB;QACpB,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,SAAS,CAAC,KAAqB,EAAE,OAAe,EAAE,MAA+B;QAC/E,MAAM,KAAK,GAAc,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAClF,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,MAAmB;QAClC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/D,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;QACjC,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IACvE,CAAC;CACF"}

package/dist/deferred.d.ts

@@ -0,0 +1,18 @@
+export interface Deferred<T> {
+    readonly promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+}
+export declare function deferred<T = void>(): Deferred<T>;
+/**
+ * Promise-based sleep that resolves after `ms` milliseconds, or rejects with
+ * an `AbortError` if `signal` aborts first. A resolved AbortSignal at call
+ * time short-circuits to an immediate rejection.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+export declare class AbortError extends Error {
+    readonly name = "AbortError";
+    constructor(message?: string);
+}
+export declare function isAbortError(err: unknown): boolean;
+//# sourceMappingURL=deferred.d.ts.map

package/dist/deferred.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred.d.ts","sourceRoot":"","sources":["../src/deferred.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7B,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC7C,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED,wBAAgB,QAAQ,CAAC,CAAC,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAQhD;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE;AAED,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,gBAAgB;gBAC1B,OAAO,SAA8B;CAGlD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAElD"}

package/dist/deferred.js

@@ -0,0 +1,40 @@
+export function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+/**
+ * Promise-based sleep that resolves after `ms` milliseconds, or rejects with
+ * an `AbortError` if `signal` aborts first. A resolved AbortSignal at call
+ * time short-circuits to an immediate rejection.
+ */
+export function sleep(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.reject(new AbortError());
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new AbortError());
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+export class AbortError extends Error {
+    name = 'AbortError';
+    constructor(message = 'The operation was aborted') {
+        super(message);
+    }
+}
+export function isAbortError(err) {
+    return err instanceof Error && (err.name === 'AbortError' || err.name === 'AbortError');
+}
+//# sourceMappingURL=deferred.js.map

package/dist/deferred.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred.js","sourceRoot":"","sources":["../src/deferred.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,QAAQ;IACtB,IAAI,OAA6C,CAAC;IAClD,IAAI,MAAmC,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC1C,OAAO,GAAG,GAAG,CAAC;QACd,MAAM,GAAG,GAAG,CAAC;IACf,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QACpB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC;QAC3B,CAAC,CAAC;QACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,OAAO,UAAW,SAAQ,KAAK;IACjB,IAAI,GAAG,YAAY,CAAC;IACtC,YAAY,OAAO,GAAG,2BAA2B;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAG,YAAY,KAAK,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC;AAC1F,CAAC"}