@cellaflow/sdk 0.7.0 → 0.7.1

package/dist/execution.js

@@ -0,0 +1,172 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { CellaflowClient } from "./client.js";
+import { CacheStatus } from "./cellaflow/v1/idempotency_pb.js";
+import { LeaseHeartbeat } from "./lease.js";
+const DEFAULT_TTL_MS = 30_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
+/** Raised when the requested execution lease cannot be acquired. */
+export class LeaseNotAcquired extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LeaseNotAcquired";
+    }
+}
+/** Raised by `LeaseHandle.check()` once the lease has been lost. */
+export class LeaseLostError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LeaseLostError";
+    }
+}
+/**
+ * Handle to an active execution lease.
+ *
+ * Node cannot interrupt a running task the way Python's asyncio can cancel one,
+ * so losing a lease here is **cooperative**: the work keeps running until it
+ * checks. Two ways to check, and long or irreversible work should use one:
+ *
+ * - `check()` throws {@link LeaseLostError} once the lease is gone.
+ * - `signal` aborts, so it can be handed to `fetch` or any AbortSignal-aware API.
+ */
+export class LeaseHandle {
+    fencingToken;
+    controller = new AbortController();
+    lostDetail;
+    constructor(fencingToken) {
+        this.fencingToken = fencingToken;
+    }
+    /** Aborts when the lease is lost. Pass to `fetch`, streams, or your own loops. */
+    get signal() {
+        return this.controller.signal;
+    }
+    get isLost() {
+        return this.controller.signal.aborted;
+    }
+    /** @internal */
+    markLost(detail) {
+        if (this.controller.signal.aborted)
+            return;
+        this.lostDetail = detail;
+        this.controller.abort(new LeaseLostError(`Execution lease was lost: ${detail}`));
+    }
+    /**
+     * Throws if the lease has been lost.
+     *
+     * Call this before anything irreversible inside a long block. Nothing else
+     * stops the work: losing a lease cannot preempt a running function in Node.
+     */
+    check() {
+        if (this.isLost) {
+            throw new LeaseLostError(`Execution lease was lost: ${this.lostDetail}`);
+        }
+    }
+}
+const currentLeaseStore = new AsyncLocalStorage();
+/**
+ * Returns the lease held by the enclosing block.
+ *
+ * Lets code inside an {@link executionLease} block, or inside a
+ * {@link taskLease} function which has no handle to receive, reach the fencing
+ * token to pass downstream.
+ */
+export function currentLease() {
+    const handle = currentLeaseStore.getStore();
+    if (!handle) {
+        throw new Error("No execution lease is active. currentLease() is only valid inside an " +
+            "executionLease(...) block or a taskLease(...) function.");
+    }
+    return handle;
+}
+/**
+ * Runs `fn` holding a distributed lock on `key`, renewed by a heartbeat.
+ *
+ * Only one worker runs the block at a time. If this process dies, the lease
+ * stops being renewed and another worker takes it once the TTL elapses, which is
+ * the property a plain database lock cannot offer for a holder that hangs
+ * without dying.
+ *
+ * ```ts
+ * await executionLease("task:abc-123", { workerId: "worker-1" }, async (lease) => {
+ *   lease.check();
+ *   await doTheWork({ signal: lease.signal });
+ * });
+ * ```
+ *
+ * Unlike the Python `async_execution_lease`, losing the lease does **not**
+ * interrupt `fn`: Node has no task cancellation. The handle exposes `check()`
+ * and `signal` so the work can abort itself, and anything irreversible should
+ * check first.
+ */
+export async function executionLease(key, options, fn) {
+    const { workerId, target = "localhost:50051", secure = false, ttlMs = DEFAULT_TTL_MS, heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS, onLeaseLost, waitMs = 0, } = options;
+    const client = new CellaflowClient({ target, secure });
+    let hb;
+    let fencingToken = 0;
+    try {
+        const resp = await client.checkIdempotencyCache(workerId, key, waitMs, ttlMs);
+        if (resp.status === CacheStatus.HIT) {
+            throw new LeaseNotAcquired(`'${key}' is already committed: the operation it names has completed. An ` +
+                "execution lease locks work still to be done, so a committed key means " +
+                "this work is finished, not that the lock is busy.");
+        }
+        if (resp.status !== CacheStatus.ACQUIRED) {
+            const holder = resp.currentHolderId ? ` (held by ${resp.currentHolderId})` : "";
+            throw new LeaseNotAcquired(`Could not acquire execution lease '${key}'${holder}. Another worker is ` +
+                "running it. Raise waitMs to wait for them, or treat this as the " +
+                "signal that the work is already in hand.");
+        }
+        fencingToken = Number(resp.fencingToken ?? 0n);
+        const handle = new LeaseHandle(fencingToken);
+        hb = new LeaseHeartbeat({
+            client,
+            agentId: workerId,
+            idempotencyKey: key,
+            fencingToken,
+            heartbeatIntervalMs: Number(resp.heartbeatIntervalMs ?? BigInt(heartbeatIntervalMs)),
+            leaseTtlMs: ttlMs,
+            onLeaseLost: (detail) => {
+                handle.markLost(detail);
+                try {
+                    onLeaseLost?.(detail);
+                }
+                catch {
+                    // A caller's callback must not mask the loss itself.
+                }
+            },
+        });
+        hb.start();
+        return await currentLeaseStore.run(handle, () => fn(handle));
+    }
+    finally {
+        await hb?.stop();
+        if (fencingToken > 0) {
+            await client
+                .releaseLease(workerId, key, fencingToken, "BLOCK_EXIT")
+                .catch(() => {
+                // The lease expires on its own; a failed release is not worth masking
+                // whatever the block was doing.
+            });
+        }
+        client.close();
+    }
+}
+/**
+ * Wraps a function so every call runs under an execution lease.
+ *
+ * The key is derived per call, so a task id argument becomes the lock:
+ *
+ * ```ts
+ * const processOrder = taskLease(
+ *   async (orderId: string) => { currentLease().check(); await ship(orderId); },
+ *   { workerId: "worker-1", key: (orderId) => `order:${orderId}` },
+ * );
+ * ```
+ */
+export function taskLease(fn, options) {
+    const { key, ...leaseOptions } = options;
+    return async function leasedTask(...args) {
+        const resolved = typeof key === "function" ? key(...args) : key;
+        return executionLease(resolved, leaseOptions, () => fn(...args));
+    };
+}
+//# sourceMappingURL=execution.js.map

package/dist/execution.js.map

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

package/dist/idempotency.d.ts

@@ -0,0 +1,62 @@
+/**
+ * How widely a derived idempotency key deduplicates.
+ *
+ * The numeric values match the Python SDK and the engine's enum. They are part
+ * of the wire contract, not an implementation detail.
+ */
+export declare enum IdempotencyScope {
+    UNSPECIFIED = 0,
+    /** Shared across all agents in the session. The default. */
+    SESSION_WIDE = 1,
+    /** Isolated to the executing agent. */
+    AGENT_PRIVATE = 2,
+    /** Isolated to the specific superstep / node. */
+    STEP_LOCAL = 3,
+    /**
+     * Shared across *sessions* within a declared coordination domain.
+     *
+     * The only scope whose key omits `sessionId`, so agents running different
+     * workflows in different sessions deduplicate one shared side effect.
+     */
+    SHARED = 4
+}
+/**
+ * Hashes inputs with RFC 8785 Canonical JSON and SHA-256, returning the first
+ * 16 bytes hex-encoded.
+ *
+ * Byte-identical to the Python SDK's `_hash_inputs`, which is what allows a
+ * TypeScript agent and a Python agent to converge on one key under
+ * {@link IdempotencyScope.SHARED}. Verified against Python reference hashes
+ * covering unicode, escapes, nested objects, key reordering and exponent-form
+ * numbers. Changing the canonicalisation or the digest length silently stops
+ * cross-language deduplication, which fails by repeating the side effect rather
+ * than by raising.
+ */
+export declare function hashInputs(args: unknown[], kwargs: Record<string, unknown>): string;
+export interface DeriveKeyOptions {
+    sessionId: string;
+    workflowVersion: string;
+    stepSequence: number;
+    agentId: string;
+    toolName: string;
+    scope: IdempotencyScope;
+    coordinationId?: string;
+    /** Positional arguments the tool was called with. */
+    args?: unknown[];
+    /** Named arguments, when the tool takes a single options object. */
+    kwargs?: Record<string, unknown>;
+    /**
+     * Restricts the hash to the named keys of `kwargs`.
+     *
+     * Heterogeneous agents converge on one side effect precisely when they
+     * disagree about everything else, so hashing everything they pass is the one
+     * thing guaranteed to keep them apart.
+     *
+     * JavaScript has no named arguments, so a tool using `sharedOn` must take a
+     * single options object; the names are read from it.
+     */
+    sharedOn?: readonly string[];
+}
+/** Derives the canonical idempotency key for a step or tool execution. */
+export declare function deriveIdempotencyKey(opts: DeriveKeyOptions): string;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,oBAAY,gBAAgB;IAC1B,WAAW,IAAI;IACf,4DAA4D;IAC5D,YAAY,IAAI;IAChB,uCAAuC;IACvC,aAAa,IAAI;IACjB,iDAAiD;IACjD,UAAU,IAAI;IACd;;;;;OAKG;IACH,MAAM,IAAI;CACX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAUnF;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,gBAAgB,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAyDnE"}

package/dist/idempotency.js

@@ -0,0 +1,91 @@
+import canonicalize from "canonicalize";
+import { createHash } from "node:crypto";
+/**
+ * How widely a derived idempotency key deduplicates.
+ *
+ * The numeric values match the Python SDK and the engine's enum. They are part
+ * of the wire contract, not an implementation detail.
+ */
+export var IdempotencyScope;
+(function (IdempotencyScope) {
+    IdempotencyScope[IdempotencyScope["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    /** Shared across all agents in the session. The default. */
+    IdempotencyScope[IdempotencyScope["SESSION_WIDE"] = 1] = "SESSION_WIDE";
+    /** Isolated to the executing agent. */
+    IdempotencyScope[IdempotencyScope["AGENT_PRIVATE"] = 2] = "AGENT_PRIVATE";
+    /** Isolated to the specific superstep / node. */
+    IdempotencyScope[IdempotencyScope["STEP_LOCAL"] = 3] = "STEP_LOCAL";
+    /**
+     * Shared across *sessions* within a declared coordination domain.
+     *
+     * The only scope whose key omits `sessionId`, so agents running different
+     * workflows in different sessions deduplicate one shared side effect.
+     */
+    IdempotencyScope[IdempotencyScope["SHARED"] = 4] = "SHARED";
+})(IdempotencyScope || (IdempotencyScope = {}));
+/**
+ * Hashes inputs with RFC 8785 Canonical JSON and SHA-256, returning the first
+ * 16 bytes hex-encoded.
+ *
+ * Byte-identical to the Python SDK's `_hash_inputs`, which is what allows a
+ * TypeScript agent and a Python agent to converge on one key under
+ * {@link IdempotencyScope.SHARED}. Verified against Python reference hashes
+ * covering unicode, escapes, nested objects, key reordering and exponent-form
+ * numbers. Changing the canonicalisation or the digest length silently stops
+ * cross-language deduplication, which fails by repeating the side effect rather
+ * than by raising.
+ */
+export function hashInputs(args, kwargs) {
+    const canon = canonicalize({ args, kwargs });
+    if (canon === undefined) {
+        throw new TypeError("Tool arguments could not be canonicalised. Arguments contributing to an " +
+            "idempotency key must be JSON-representable: no functions, symbols, " +
+            "BigInt, undefined, or circular references.");
+    }
+    return createHash("sha256").update(canon, "utf8").digest("hex").slice(0, 32);
+}
+/** Derives the canonical idempotency key for a step or tool execution. */
+export function deriveIdempotencyKey(opts) {
+    const { sessionId, workflowVersion, stepSequence, agentId, toolName, scope, coordinationId, args = [], kwargs = {}, sharedOn, } = opts;
+    let inputsHash;
+    if (sharedOn !== undefined) {
+        const selected = {};
+        for (const k of sharedOn) {
+            if (Object.prototype.hasOwnProperty.call(kwargs, k))
+                selected[k] = kwargs[k];
+        }
+        inputsHash = hashInputs([], selected);
+    }
+    else {
+        inputsHash = hashInputs(args, kwargs);
+    }
+    if (scope === IdempotencyScope.SHARED) {
+        // The only scope that omits sessionId, so agents in different sessions
+        // converge on one key. It also omits workflowVersion, because the whole
+        // point is that *different* workflows share the operation and they will
+        // not be on the same version.
+        //
+        // coordinationId is what keeps this from being too wide. Without it two
+        // unrelated callers of sendEmail({to: X}) would deduplicate, suppressing
+        // one of them silently. It is required, and the caller must choose it.
+        if (!coordinationId) {
+            throw new Error("IdempotencyScope.SHARED requires a coordinationId naming the work being " +
+                "shared: a ticket, task, or tenant id. Pass it when opening the session, " +
+                'e.g. durableTools(config, { coordinationId: "ticket-4417" }, fn). It has ' +
+                "no default: a shared one would deduplicate unrelated callers that happen " +
+                "to make the same call.");
+        }
+        return `shared:${coordinationId}:${toolName}:${inputsHash}`;
+    }
+    let seqPart = "session_wide";
+    let agentPart = "session_wide";
+    if (scope === IdempotencyScope.AGENT_PRIVATE) {
+        agentPart = agentId;
+    }
+    else if (scope === IdempotencyScope.STEP_LOCAL) {
+        seqPart = String(stepSequence);
+        agentPart = agentId;
+    }
+    return `${sessionId}:${workflowVersion}:${seqPart}:${agentPart}:${toolName}:${inputsHash}`;
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/idempotency.js.map

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

package/dist/index.d.ts

@@ -2,4 +2,13 @@ export * from "./client.js";
 export * from "./serialization.js";
 export * from "./cellaflow/v1/common_pb.js";
 export * from "./cellaflow/v1/idempotency_pb.js";
+export { IdempotencyScope, deriveIdempotencyKey, hashInputs } from "./idempotency.js";
+export type { DeriveKeyOptions } from "./idempotency.js";
+export { tool, step, DivergentStepError } from "./tool.js";
+export type { ToolOptions } from "./tool.js";
+export { durableTools, toolSessionId } from "./durable.js";
+export type { DurableToolsOptions, DurableSession, ThreadRef } from "./durable.js";
+export { executionLease, taskLease, currentLease, LeaseHandle, LeaseNotAcquired, LeaseLostError, } from "./execution.js";
+export type { ExecutionLeaseOptions } from "./execution.js";
+export { WorkflowContext } from "./context.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AAMjD,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACtF,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC3D,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EACL,cAAc,EACd,SAAS,EACT,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -5,4 +5,10 @@ export * from "./cellaflow/v1/idempotency_pb.js";
 // Note: internal_pb is intentionally NOT re-exported here. It contains
 // engine-internal types (CacheRecord, LeaseRecord, etc.) that are not part
 // of the public SDK surface.
+// High-level API
+export { IdempotencyScope, deriveIdempotencyKey, hashInputs } from "./idempotency.js";
+export { tool, step, DivergentStepError } from "./tool.js";
+export { durableTools, toolSessionId } from "./durable.js";
+export { executionLease, taskLease, currentLease, LeaseHandle, LeaseNotAcquired, LeaseLostError, } from "./execution.js";
+export { WorkflowContext } from "./context.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,uEAAuE;AACvE,2EAA2E;AAC3E,6BAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,uEAAuE;AACvE,2EAA2E;AAC3E,6BAA6B;AAE7B,iBAAiB;AACjB,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEtF,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EACL,cAAc,EACd,SAAS,EACT,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/dist/lease.d.ts

@@ -0,0 +1,50 @@
+import type { CellaflowClient } from "./client.js";
+export interface LeaseHeartbeatOptions {
+    client: CellaflowClient;
+    agentId: string;
+    idempotencyKey: string;
+    fencingToken: number;
+    /** How often to renew. The engine suggests this on acquisition. */
+    heartbeatIntervalMs: number;
+    /** How long each renewal extends the lease. Defaults to 3x the interval. */
+    extendMs?: number;
+    /**
+     * How long the lease survives without a confirmed renewal. Loss is declared
+     * against this, not against an error count.
+     */
+    leaseTtlMs?: number;
+    /** Called once when the lease is determined to be lost. */
+    onLeaseLost?: (detail: string) => void;
+}
+/**
+ * Renews a held lease on an interval until stopped.
+ *
+ * The engine requires a caller holding a lease to renew it, so this starts as
+ * soon as one is acquired and stops in a `finally`.
+ */
+export declare class LeaseHeartbeat {
+    private readonly opts;
+    private timer?;
+    private stopped;
+    private lastConfirmed;
+    private inFlight?;
+    /** Set once the lease is known to be lost. Read by `LeaseHandle.check()`. */
+    lost: boolean;
+    lostDetail?: string;
+    constructor(options: LeaseHeartbeatOptions);
+    start(): void;
+    stop(): Promise<void>;
+    private notifyLost;
+    /**
+     * True once the lease can no longer be assumed held.
+     *
+     * A failed renewal is not itself proof of loss: the RPC failing means we could
+     * not confirm the lease, while the engine may still hold it until the TTL runs
+     * out. Declaring loss on an error count would abort work that still holds a
+     * perfectly valid lease, so loss is declared on elapsed time since the last
+     * *confirmed* renewal.
+     */
+    private ttlExhausted;
+    private beat;
+}
+//# sourceMappingURL=lease.d.ts.map

package/dist/lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../src/lease.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAqBnD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CACwB;IAC7C,OAAO,CAAC,KAAK,CAAC,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,CAAgB;IAEjC,6EAA6E;IAC7E,IAAI,UAAS;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,YAAY,OAAO,EAAE,qBAAqB,EAQzC;IAED,KAAK,IAAI,IAAI,CAYZ;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAS1B;IAED,OAAO,CAAC,UAAU;IAYlB;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;YAIN,IAAI;CA2BnB"}

package/dist/lease.js

@@ -0,0 +1,117 @@
+import { RenewFailureReason } from "./cellaflow/v1/idempotency_pb.js";
+/** Why the engine refused to renew, in words a caller can act on. */
+function renewFailureDetail(reason) {
+    switch (reason) {
+        case RenewFailureReason.EXPIRED:
+            return "the lease had already expired";
+        case RenewFailureReason.SUPERSEDED:
+            return "another worker took the lease";
+        case RenewFailureReason.NOT_FOUND:
+            return "the engine has no record of the lease";
+        case RenewFailureReason.COMPLETED:
+            return "the operation was already committed";
+        case RenewFailureReason.MAX_LIFETIME_EXCEEDED:
+            return "the lease hit its maximum lifetime and was reclaimed";
+        default:
+            return "the engine refused renewal";
+    }
+}
+/**
+ * Renews a held lease on an interval until stopped.
+ *
+ * The engine requires a caller holding a lease to renew it, so this starts as
+ * soon as one is acquired and stops in a `finally`.
+ */
+export class LeaseHeartbeat {
+    opts;
+    timer;
+    stopped = false;
+    lastConfirmed = Date.now();
+    inFlight;
+    /** Set once the lease is known to be lost. Read by `LeaseHandle.check()`. */
+    lost = false;
+    lostDetail;
+    constructor(options) {
+        const intervalMs = options.heartbeatIntervalMs;
+        this.opts = {
+            ...options,
+            heartbeatIntervalMs: intervalMs,
+            extendMs: options.extendMs ?? intervalMs * 3,
+            leaseTtlMs: options.leaseTtlMs ?? intervalMs * 3,
+        };
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            // Never overlap renewals: a slow RPC would otherwise queue them and each
+            // would extend from a stale view of the lease.
+            if (this.inFlight)
+                return;
+            this.inFlight = this.beat().finally(() => {
+                this.inFlight = undefined;
+            });
+        }, this.opts.heartbeatIntervalMs);
+        // Do not hold the event loop open on the heartbeat alone.
+        this.timer.unref?.();
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        // Let an in-flight renewal settle so it cannot outlive the block that owns
+        // the lease and renew something the caller has already released.
+        if (this.inFlight)
+            await this.inFlight.catch(() => { });
+    }
+    notifyLost(detail) {
+        if (this.lost)
+            return;
+        this.lost = true;
+        this.lostDetail = detail;
+        void this.stop();
+        try {
+            this.opts.onLeaseLost?.(detail);
+        }
+        catch {
+            // A caller's callback must not take down the heartbeat.
+        }
+    }
+    /**
+     * True once the lease can no longer be assumed held.
+     *
+     * A failed renewal is not itself proof of loss: the RPC failing means we could
+     * not confirm the lease, while the engine may still hold it until the TTL runs
+     * out. Declaring loss on an error count would abort work that still holds a
+     * perfectly valid lease, so loss is declared on elapsed time since the last
+     * *confirmed* renewal.
+     */
+    ttlExhausted() {
+        return Date.now() - this.lastConfirmed >= this.opts.leaseTtlMs;
+    }
+    async beat() {
+        if (this.stopped || this.lost)
+            return;
+        try {
+            const resp = await this.opts.client.renewLease(this.opts.agentId, this.opts.idempotencyKey, this.opts.fencingToken, this.opts.extendMs, 
+            // Bound the RPC. Without a deadline a black-holed connection parks the
+            // renewal forever and the lease silently ages out while we wait on it.
+            Math.max(1, Math.ceil(this.opts.heartbeatIntervalMs / 1000)));
+            if (!resp.renewed) {
+                this.notifyLost(renewFailureDetail(resp.failureReason));
+                return;
+            }
+            this.lastConfirmed = Date.now();
+        }
+        catch (err) {
+            if (this.ttlExhausted()) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.notifyLost(`could not be renewed for ${this.opts.leaseTtlMs}ms (last error: ${msg})`);
+            }
+            // Otherwise: transient. The engine may still be holding it for us.
+        }
+    }
+}
+//# sourceMappingURL=lease.js.map

package/dist/lease.js.map

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

package/dist/tool.d.ts

@@ -0,0 +1,58 @@
+import { IdempotencyScope } from "./idempotency.js";
+/**
+ * Raised when the engine refuses a lease because another agent already owns the
+ * graph position this call intends to write to.
+ *
+ * This is the refusal arriving *before* the side effect, which is the point: the
+ * alternative is discovering the divergence at commit time, after the money has
+ * moved.
+ */
+export declare class DivergentStepError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export interface ToolOptions {
+    /**
+     * Overrides key derivation entirely. Supply this when the operation's identity
+     * is a business fact you already have, such as `charge:${orderId}`.
+     */
+    idempotencyKey?: string;
+    /** Identifies the calling agent. Read by AGENT_PRIVATE and STEP_LOCAL scopes. */
+    agentId?: string;
+    /** Defaults to the function's name. Required for anonymous functions. */
+    toolName?: string;
+    scope?: IdempotencyScope;
+    /**
+     * Restricts key derivation to these keys of the tool's single object argument.
+     *
+     * Use when several agents must converge on one side effect while disagreeing
+     * about everything else they pass. A tool using this must take one options
+     * object, because JavaScript has no named arguments to select from.
+     */
+    sharedOn?: readonly string[];
+}
+/**
+ * Wraps a function so the engine runs it at most once per idempotency key, and
+ * so its result survives the process that produced it.
+ *
+ * A second caller deriving the same key does not run the body. It receives what
+ * the first call returned, even if that process has since died.
+ *
+ * ```ts
+ * const chargeCard = tool(
+ *   async ({ orderId, cents }: { orderId: string; cents: number }) =>
+ *     gateway.charge(orderId, cents),
+ *   { toolName: "chargeCard" },
+ * );
+ *
+ * await durableTools({ configurable: { thread_id: "ticket-4417" } }, async () => {
+ *   await chargeCard({ orderId: "ORD-1", cents: 1999 });
+ * });
+ * ```
+ *
+ * Must be called inside {@link durableTools}, which supplies the session.
+ */
+export declare function tool<A extends unknown[], R>(fn: (...args: A) => R | Promise<R>, options?: ToolOptions): (...args: A) => Promise<R>;
+/** `step` and `tool` are the same mechanism, kept distinct for readability. */
+export declare const step: typeof tool;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAwB,MAAM,kBAAkB,CAAC;AAI1E;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IACd,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;IAArD,YAAY,OAAO,EAAE,MAAM,EAAW,KAAK,CAAC,EAAE,OAAO,EAGpD;CACF;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EACzC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAClC,OAAO,GAAE,WAAgB,GACxB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAiK5B;AAED,+EAA+E;AAC/E,eAAO,MAAM,IAAI,aAAO,CAAC"}