cairnq 0.1.0

package/dist/_protocol/sql/sqlite/retry.sql

@@ -0,0 +1,16 @@
+-- Manually re-enqueue a failed/canceled task. :reset_attempt (0/1) controls
+-- whether the attempt counter resets to 0.
+-- params: id, now_ms, reset_attempt
+update cairnq_tasks
+set
+    status = 'queued',
+    error = null,
+    worker_id = null,
+    lease_until_ms = null,
+    run_at_ms = :now_ms,
+    cancel_requested_at_ms = null,
+    completed_at_ms = null,
+    attempt = case when :reset_attempt = 1 then 0 else attempt end,
+    updated_at_ms = :now_ms
+where id = :id and status in ('failed', 'canceled')
+returning *;

package/dist/_protocol/sql/sqlite/succeed.sql

@@ -0,0 +1,15 @@
+-- Mark succeeded. Ownership-checked. worker_id kept for audit.
+-- params: id, worker_id, now_ms, result (JSON text), message
+update cairnq_tasks
+set
+    status = 'succeeded',
+    result = :result,
+    progress = 1.0,
+    message = coalesce(:message, message),
+    completed_at_ms = :now_ms,
+    updated_at_ms = :now_ms
+where id = :id
+  and status = 'running'
+  and worker_id = :worker_id
+  and lease_until_ms > :now_ms
+returning *;

package/dist/_protocol/sql/sqlite/upsert_key.sql

@@ -0,0 +1,7 @@
+-- Point a key at a task (initial pointer, or repoint on replace).
+-- params: key, task_id, now_ms
+insert into cairnq_task_keys (key, task_id, created_at_ms, updated_at_ms)
+values (:key, :task_id, :now_ms, :now_ms)
+on conflict(key) do update set
+    task_id = excluded.task_id,
+    updated_at_ms = excluded.updated_at_ms;

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+import { type Task } from "./models.js";
+import type { ListInput, SubmitInput, TaskStore } from "./store/base.js";
+import { type TaskDef } from "./task.js";
+export type SubmitOptions = Omit<SubmitInput, "name" | "payload">;
+export interface CallOptions extends SubmitOptions {
+    waitTimeoutMs?: number;
+    pollMs?: number;
+}
+/** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
+export declare class CairnQ {
+    private readonly _store;
+    constructor(_store: TaskStore);
+    static sqlite(path: string, opts?: {
+        busyTimeoutMs?: number;
+    }): CairnQ;
+    /** Multi-host backend. `dsn` is a libpq connection string; requires the
+     * optional `pg` package. */
+    static postgres(dsn: string, opts?: {
+        max?: number;
+    }): CairnQ;
+    get store(): TaskStore;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    submit(name: string, payload?: unknown, opts?: SubmitOptions): Promise<Task>;
+    submit<P, R>(task: TaskDef<P, R>, payload?: P, opts?: SubmitOptions): Promise<Task>;
+    get(taskId: string): Promise<Task | null>;
+    getByKey(key: string): Promise<Task | null>;
+    list(input?: ListInput): Promise<Task[]>;
+    cancel(taskId: string): Promise<Task | null>;
+    cancelByKey(key: string): Promise<Task | null>;
+    retry(taskId: string, opts?: {
+        resetAttempt?: boolean;
+    }): Promise<Task | null>;
+    retryByKey(key: string, opts?: {
+        resetAttempt?: boolean;
+    }): Promise<Task | null>;
+    wait(taskId: string, opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<Task>;
+    /** submit + wait. Resolves with the result on success; rejects with
+     * TaskFailed / TaskCanceled / TaskTimeout otherwise. Pass a TaskDef and the
+     * resolved value is typed as its Result. */
+    call(name: string, payload?: unknown, opts?: CallOptions): Promise<unknown>;
+    call<P, R>(task: TaskDef<P, R>, payload?: P, opts?: CallOptions): Promise<R>;
+}

package/dist/client.js

@@ -0,0 +1,70 @@
+import { TaskCanceled, TaskFailed } from "./errors.js";
+import { isFailed, isSucceeded } from "./models.js";
+import { SQLiteStore } from "./store/sqlite.js";
+import { PostgresStore } from "./store/postgres.js";
+import { taskName } from "./task.js";
+import { pollWait } from "./wait.js";
+/** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
+export class CairnQ {
+    _store;
+    constructor(_store) {
+        this._store = _store;
+    }
+    static sqlite(path, opts) {
+        return new CairnQ(new SQLiteStore(path, opts));
+    }
+    /** Multi-host backend. `dsn` is a libpq connection string; requires the
+     * optional `pg` package. */
+    static postgres(dsn, opts) {
+        return new CairnQ(new PostgresStore(dsn, opts));
+    }
+    get store() {
+        return this._store;
+    }
+    connect() {
+        return this._store.connect();
+    }
+    close() {
+        return this._store.close();
+    }
+    submit(task, payload, opts = {}) {
+        return this._store.submit({ name: taskName(task), payload, ...opts });
+    }
+    get(taskId) {
+        return this._store.get(taskId);
+    }
+    getByKey(key) {
+        return this._store.getByKey(key);
+    }
+    list(input) {
+        return this._store.list(input);
+    }
+    cancel(taskId) {
+        return this._store.cancel(taskId);
+    }
+    cancelByKey(key) {
+        return this._store.cancelByKey(key);
+    }
+    retry(taskId, opts) {
+        return this._store.retry(taskId, opts);
+    }
+    retryByKey(key, opts) {
+        return this._store.retryByKey(key, opts);
+    }
+    wait(taskId, opts = {}) {
+        return pollWait(this._store, taskId, {
+            timeoutMs: opts.timeoutMs ?? 30_000,
+            pollMs: opts.pollMs,
+        });
+    }
+    async call(task, payload, opts = {}) {
+        const { waitTimeoutMs = 30_000, pollMs, ...submit } = opts;
+        const created = await this.submit(taskName(task), payload, submit);
+        const final = await pollWait(this._store, created.id, { timeoutMs: waitTimeoutMs, pollMs });
+        if (isSucceeded(final))
+            return final.result;
+        if (isFailed(final))
+            throw new TaskFailed(final.error);
+        throw new TaskCanceled(final.id);
+    }
+}

package/dist/context.d.ts

@@ -0,0 +1,31 @@
+import { type Task } from "./models.js";
+import type { SubmitOptions } from "./client.js";
+import type { TaskStore } from "./store/base.js";
+import { type TaskDef } from "./task.js";
+/** Handed to a task handler. Worker-side capabilities mirror the Python SDK. */
+export declare class TaskContext {
+    private readonly store;
+    private readonly task;
+    readonly workerId: string;
+    private readonly leaseMs;
+    constructor(store: TaskStore, task: Task, workerId: string, leaseMs: number);
+    get taskId(): string;
+    get name(): string;
+    get queue(): string;
+    get attempt(): number;
+    get metadata(): any;
+    get rootId(): string | null;
+    get correlationId(): string | null;
+    get payload(): any;
+    progress(value: number | null, message?: string | null): Promise<Task>;
+    heartbeat(): Promise<Task>;
+    /** Cooperative cancel check. */
+    canceled(): Promise<boolean>;
+    /** Submit a child task; parent/root/correlation are wired automatically. */
+    submit(name: string, payload?: unknown, opts?: SubmitOptions): Promise<Task>;
+    submit<P, R>(task: TaskDef<P, R>, payload?: P, opts?: SubmitOptions): Promise<Task>;
+    wait(taskId: string, opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<Task>;
+}

package/dist/context.js

@@ -0,0 +1,78 @@
+import { cancelRequested } from "./models.js";
+import { taskName } from "./task.js";
+import { pollWait } from "./wait.js";
+/** Handed to a task handler. Worker-side capabilities mirror the Python SDK. */
+export class TaskContext {
+    store;
+    task;
+    workerId;
+    leaseMs;
+    constructor(store, task, workerId, leaseMs) {
+        this.store = store;
+        this.task = task;
+        this.workerId = workerId;
+        this.leaseMs = leaseMs;
+    }
+    get taskId() {
+        return this.task.id;
+    }
+    get name() {
+        return this.task.name;
+    }
+    get queue() {
+        return this.task.queue;
+    }
+    get attempt() {
+        return this.task.attempt;
+    }
+    get metadata() {
+        return this.task.metadata;
+    }
+    get rootId() {
+        return this.task.root_id;
+    }
+    get correlationId() {
+        return this.task.correlation_id;
+    }
+    get payload() {
+        return this.task.payload;
+    }
+    async progress(value, message = null) {
+        return this.store.progress({
+            taskId: this.task.id,
+            workerId: this.workerId,
+            progress: value,
+            message,
+        });
+    }
+    async heartbeat() {
+        return this.store.heartbeat({
+            taskId: this.task.id,
+            workerId: this.workerId,
+            leaseMs: this.leaseMs,
+        });
+    }
+    /** Cooperative cancel check. */
+    async canceled() {
+        const t = await this.store.get(this.task.id);
+        if (!t)
+            return true;
+        return cancelRequested(t) || t.status === "canceled";
+    }
+    async submit(task, payload, opts = {}) {
+        return this.store.submit({
+            name: taskName(task),
+            payload,
+            parentId: this.task.id,
+            rootId: this.task.root_id,
+            correlationId: this.task.correlation_id,
+            ...opts,
+        });
+    }
+    async wait(taskId, opts = {}) {
+        return pollWait(this.store, taskId, {
+            timeoutMs: opts.timeoutMs ?? 30_000,
+            pollMs: opts.pollMs,
+        });
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,60 @@
+/** The single shape of the JSON error envelope (see PROTOCOL.md). Everything that
+ * records an error — a handler exception, a missing handler, lease expiry, a thrown
+ * TaskError — builds it here, so the contract's fields live in one place. */
+export declare function errorEnvelope(e: {
+    type: string;
+    code: string;
+    message: string;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+}): Record<string, unknown>;
+export declare class CairnQError extends Error {
+}
+export declare class AlreadyExists extends CairnQError {
+    key: string;
+    constructor(key: string);
+}
+/** wait/call did not reach a terminal status in time. The task keeps running. */
+export declare class TaskTimeout extends CairnQError {
+    taskId: string;
+    constructor(taskId: string);
+}
+/** A waited-on task ended in `failed`. The envelope's fields are unpacked onto the
+ * error — read `e.code` / `e.message` / `e.retryable` / `e.details` instead of
+ * digging into `e.error` (the raw envelope stays available on `e.error`). */
+export declare class TaskFailed extends CairnQError {
+    error: unknown;
+    readonly type: string;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly details: Record<string, unknown>;
+    constructor(error: unknown);
+}
+export declare class TaskCanceled extends CairnQError {
+    taskId: string;
+    constructor(taskId: string);
+}
+/** A worker write affected 0 rows: the lease expired and was reclaimed. */
+export declare class LostLease extends CairnQError {
+    taskId: string;
+    constructor(taskId: string);
+}
+export declare class ProtocolVersionMismatch extends CairnQError {
+    constructor(message: string);
+}
+/** Throw inside a handler to control how the failure is recorded. Defaults to
+ * non-retryable so deterministic errors fail fast instead of burning retries.
+ * Any other thrown value is treated as retryable. */
+export declare class TaskError extends CairnQError {
+    code: string;
+    retryable: boolean;
+    type: string;
+    details: Record<string, unknown>;
+    constructor(message: string, opts?: {
+        code?: string;
+        retryable?: boolean;
+        type?: string;
+        details?: Record<string, unknown>;
+    });
+    envelope(): Record<string, unknown>;
+}

package/dist/errors.js

@@ -0,0 +1,100 @@
+/** The single shape of the JSON error envelope (see PROTOCOL.md). Everything that
+ * records an error — a handler exception, a missing handler, lease expiry, a thrown
+ * TaskError — builds it here, so the contract's fields live in one place. */
+export function errorEnvelope(e) {
+    return {
+        type: e.type,
+        code: e.code,
+        message: e.message,
+        retryable: e.retryable,
+        details: e.details ?? {},
+    };
+}
+export class CairnQError extends Error {
+}
+export class AlreadyExists extends CairnQError {
+    key;
+    constructor(key) {
+        super(`task with key ${key} already exists`);
+        this.key = key;
+        this.name = "AlreadyExists";
+    }
+}
+/** wait/call did not reach a terminal status in time. The task keeps running. */
+export class TaskTimeout extends CairnQError {
+    taskId;
+    constructor(taskId) {
+        super(`task ${taskId} did not finish in time`);
+        this.taskId = taskId;
+        this.name = "TaskTimeout";
+    }
+}
+/** A waited-on task ended in `failed`. The envelope's fields are unpacked onto the
+ * error — read `e.code` / `e.message` / `e.retryable` / `e.details` instead of
+ * digging into `e.error` (the raw envelope stays available on `e.error`). */
+export class TaskFailed extends CairnQError {
+    error;
+    type;
+    code;
+    retryable;
+    details;
+    constructor(error) {
+        const env = (error ?? {});
+        super(env.message ?? "task failed");
+        this.error = error;
+        this.name = "TaskFailed";
+        this.type = env.type ?? "TaskError";
+        this.code = env.code ?? "task_error";
+        this.retryable = env.retryable ?? false;
+        this.details = env.details ?? {};
+    }
+}
+export class TaskCanceled extends CairnQError {
+    taskId;
+    constructor(taskId) {
+        super(`task ${taskId} was canceled`);
+        this.taskId = taskId;
+        this.name = "TaskCanceled";
+    }
+}
+/** A worker write affected 0 rows: the lease expired and was reclaimed. */
+export class LostLease extends CairnQError {
+    taskId;
+    constructor(taskId) {
+        super(`lost lease on task ${taskId}`);
+        this.taskId = taskId;
+        this.name = "LostLease";
+    }
+}
+export class ProtocolVersionMismatch extends CairnQError {
+    constructor(message) {
+        super(message);
+        this.name = "ProtocolVersionMismatch";
+    }
+}
+/** Throw inside a handler to control how the failure is recorded. Defaults to
+ * non-retryable so deterministic errors fail fast instead of burning retries.
+ * Any other thrown value is treated as retryable. */
+export class TaskError extends CairnQError {
+    code;
+    retryable;
+    type;
+    details;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "TaskError";
+        this.code = opts.code ?? "task_error";
+        this.retryable = opts.retryable ?? false;
+        this.type = opts.type ?? "TaskError";
+        this.details = opts.details ?? {};
+    }
+    envelope() {
+        return errorEnvelope({
+            type: this.type,
+            code: this.code,
+            message: this.message,
+            retryable: this.retryable,
+            details: this.details,
+        });
+    }
+}

package/dist/ids.d.ts

@@ -0,0 +1,3 @@
+export declare function newUlid(tsMs?: number): string;
+export declare function newId(prefix?: string): string;
+export declare function nowMs(): number;

package/dist/ids.js

@@ -0,0 +1,19 @@
+import { randomBytes } from "node:crypto";
+// ULID-style id. Must match the Python SDK byte-for-byte in format (PROTOCOL.md):
+// <prefix>_ + 26-char Crockford base32 of (48-bit ms timestamp << 80 | 80-bit random).
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export function newUlid(tsMs = Date.now()) {
+    let value = (BigInt(tsMs) << 80n) | BigInt("0x" + randomBytes(10).toString("hex"));
+    const chars = [];
+    for (let i = 0; i < 26; i++) {
+        chars.push(CROCKFORD[Number(value & 31n)]);
+        value >>= 5n;
+    }
+    return chars.reverse().join("");
+}
+export function newId(prefix = "task") {
+    return `${prefix}_${newUlid()}`;
+}
+export function nowMs() {
+    return Date.now();
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { CairnQ } from "./client.js";
+export type { CallOptions, SubmitOptions } from "./client.js";
+export { Worker } from "./worker.js";
+export type { Handler, TypedHandler, WorkerOptions } from "./worker.js";
+export { TaskContext } from "./context.js";
+export { defineTask } from "./task.js";
+export type { TaskDef } from "./task.js";
+export { SQLiteStore } from "./store/sqlite.js";
+export { PostgresStore } from "./store/postgres.js";
+export type { ListInput, SubmitInput, TaskStore, Conflict } from "./store/base.js";
+export type { Task, TaskStatus } from "./models.js";
+export { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
+export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, } from "./errors.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { CairnQ } from "./client.js";
+export { Worker } from "./worker.js";
+export { TaskContext } from "./context.js";
+export { defineTask } from "./task.js";
+export { SQLiteStore } from "./store/sqlite.js";
+export { PostgresStore } from "./store/postgres.js";
+export { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
+export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, } from "./errors.js";

package/dist/models.d.ts

@@ -0,0 +1,36 @@
+export declare const STATUSES: readonly ["queued", "running", "succeeded", "failed", "canceled"];
+export type TaskStatus = (typeof STATUSES)[number];
+export interface Task {
+    id: string;
+    name: string;
+    queue: string;
+    status: TaskStatus;
+    payload: any;
+    metadata: any;
+    result: any | null;
+    error: any | null;
+    progress: number | null;
+    message: string | null;
+    attempt: number;
+    max_attempts: number;
+    priority: number;
+    worker_id: string | null;
+    lease_until_ms: number | null;
+    run_at_ms: number;
+    cancel_requested_at_ms: number | null;
+    parent_id: string | null;
+    root_id: string | null;
+    correlation_id: string | null;
+    created_at_ms: number;
+    updated_at_ms: number;
+    completed_at_ms: number | null;
+}
+export declare const TERMINAL: TaskStatus[];
+export declare function rowToTask(row: Record<string, unknown>): Task;
+export declare function isTerminal(task: Task): boolean;
+export declare function cancelRequested(task: Task): boolean;
+export declare const isQueued: (task: Task) => boolean;
+export declare const isRunning: (task: Task) => boolean;
+export declare const isSucceeded: (task: Task) => boolean;
+export declare const isFailed: (task: Task) => boolean;
+export declare const isCanceled: (task: Task) => boolean;

package/dist/models.js

@@ -0,0 +1,31 @@
+// STATUSES is the canonical declaration within the TS SDK; TaskStatus derives from
+// it so the type and the runtime set can't drift apart. The cross-language source of
+// truth is the status CHECK constraint in cairnq-protocol's migration, which the
+// conformance suite pins this set against.
+export const STATUSES = ["queued", "running", "succeeded", "failed", "canceled"];
+const JSON_COLUMNS = ["payload", "result", "error", "metadata"];
+export const TERMINAL = ["succeeded", "failed", "canceled"];
+export function rowToTask(row) {
+    const t = { ...row };
+    for (const col of JSON_COLUMNS) {
+        const v = row[col];
+        // The driver decides a JSON column's wire form: SQLite (TEXT) hands back a
+        // string to parse; a jsonb-aware driver (Postgres `pg`) hands back an
+        // already-decoded object. Parse only a string — never assume one backend.
+        t[col] = typeof v === "string" ? JSON.parse(v) : (v ?? null);
+    }
+    return t;
+}
+export function isTerminal(task) {
+    return TERMINAL.includes(task.status);
+}
+export function cancelRequested(task) {
+    return task.cancel_requested_at_ms != null;
+}
+// Status predicates — mirror the Python `task.succeeded` properties so callers
+// don't compare status strings by hand.
+export const isQueued = (task) => task.status === "queued";
+export const isRunning = (task) => task.status === "running";
+export const isSucceeded = (task) => task.status === "succeeded";
+export const isFailed = (task) => task.status === "failed";
+export const isCanceled = (task) => task.status === "canceled";

package/dist/sql.d.ts

@@ -0,0 +1,6 @@
+export declare function findProtocolRoot(): string;
+export declare function loadStatements(dialect?: string, root?: string): Record<string, string>;
+export declare function loadMigrations(dialect?: string, root?: string): {
+    name: string;
+    sql: string;
+}[];

package/dist/sql.js

@@ -0,0 +1,44 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// Locate the shared cairnq-protocol dir. Resolution: $CAIRNQ_PROTOCOL_DIR ->
+// vendored `_protocol/` next to this module -> walk up to `cairnq-protocol/`
+// (monorepo dev). Both SDKs load the SAME .sql strings (zero-drift guarantee).
+// The dir is laid out per-dialect (sql/<dialect>/*.sql, migrations/<dialect>/*.sql)
+// so a second backend (Postgres) slots in beside sqlite; `dialect` picks the subtree.
+export function findProtocolRoot() {
+    const env = process.env.CAIRNQ_PROTOCOL_DIR;
+    if (env)
+        return env;
+    let dir = dirname(fileURLToPath(import.meta.url));
+    const vendored = join(dir, "_protocol");
+    if (existsSync(join(vendored, "sql")))
+        return vendored;
+    for (let i = 0; i < 10; i++) {
+        const candidate = join(dir, "cairnq-protocol");
+        if (existsSync(join(candidate, "sql")))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error("cannot locate cairnq-protocol; set CAIRNQ_PROTOCOL_DIR");
+}
+export function loadStatements(dialect = "sqlite", root = findProtocolRoot()) {
+    const dir = join(root, "sql", dialect);
+    const out = {};
+    for (const file of readdirSync(dir).sort()) {
+        if (file.endsWith(".sql")) {
+            out[file.slice(0, -4)] = readFileSync(join(dir, file), "utf-8");
+        }
+    }
+    return out;
+}
+export function loadMigrations(dialect = "sqlite", root = findProtocolRoot()) {
+    const dir = join(root, "migrations", dialect);
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".sql"))
+        .sort()
+        .map((f) => ({ name: f, sql: readFileSync(join(dir, f), "utf-8") }));
+}

package/dist/store/base.d.ts

@@ -0,0 +1,77 @@
+import type { Task } from "../models.js";
+export type Conflict = "reuse" | "reject" | "replace";
+export interface SubmitInput {
+    name: string;
+    payload: unknown;
+    queue?: string;
+    key?: string | null;
+    conflict?: Conflict;
+    maxAttempts?: number;
+    priority?: number;
+    metadata?: unknown;
+    parentId?: string | null;
+    rootId?: string | null;
+    correlationId?: string | null;
+    runAtDelayMs?: number;
+}
+export interface ListInput {
+    status?: string | null;
+    queue?: string | null;
+    name?: string | null;
+    rootId?: string | null;
+    correlationId?: string | null;
+    limit?: number;
+    offset?: number;
+}
+/** The storage seam. SQLiteStore is the only MVP implementation. */
+export interface TaskStore {
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    protocolVersion(): Promise<number>;
+    submit(input: SubmitInput): Promise<Task>;
+    get(taskId: string): Promise<Task | null>;
+    getByKey(key: string): Promise<Task | null>;
+    list(input?: ListInput): Promise<Task[]>;
+    cancel(taskId: string): Promise<Task | null>;
+    cancelByKey(key: string): Promise<Task | null>;
+    retry(taskId: string, opts?: {
+        resetAttempt?: boolean;
+    }): Promise<Task | null>;
+    retryByKey(key: string, opts?: {
+        resetAttempt?: boolean;
+    }): Promise<Task | null>;
+    claim(input: {
+        queues: string[];
+        workerId: string;
+        leaseMs?: number;
+        limit?: number;
+    }): Promise<Task[]>;
+    heartbeat(input: {
+        taskId: string;
+        workerId: string;
+        leaseMs?: number;
+    }): Promise<Task>;
+    progress(input: {
+        taskId: string;
+        workerId: string;
+        progress: number | null;
+        message: string | null;
+    }): Promise<Task>;
+    succeed(input: {
+        taskId: string;
+        workerId: string;
+        result: unknown;
+    }): Promise<Task>;
+    complete(input: {
+        taskId: string;
+        workerId: string;
+        result: unknown;
+    }): Promise<Task>;
+    fail(input: {
+        taskId: string;
+        workerId: string;
+        error: unknown;
+        retryable?: boolean;
+        delayMs?: number;
+    }): Promise<Task>;
+}