@cellaflow/sdk 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to the CellaFlow TypeScript SDK.
+
+## 0.7.1
+
+### Added
+
+- **The high-level API.** `0.7.0` shipped the transport only: `CellaflowClient` and
+  the generated types. Everything above it now exists, matching the Python SDK's
+  surface.
+
+  - `tool` / `step` — 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 receives what the first returned, even if
+    that process has since died.
+  - `durableTools` — opens the session a leased tool belongs to, from a LangGraph
+    config or a bare thread id. Callback-based rather than a context manager.
+  - `executionLease` / `taskLease` — a distributed lock with liveness
+    heartbeating, so a holder that dies stops renewing and another worker takes
+    over once the TTL elapses.
+  - `currentLease`, `LeaseHandle`, `LeaseNotAcquired`, `LeaseLostError`.
+  - `deriveIdempotencyKey`, `hashInputs`, `IdempotencyScope`, `toolSessionId`,
+    `WorkflowContext`, `DivergentStepError`.
+
+- **Cross-language coordination.** `IdempotencyScope.SHARED` now works between
+  runtimes. Key derivation is byte-identical to the Python SDK: RFC 8785 canonical
+  JSON, SHA-256, first 16 bytes. Verified against Python reference hashes covering
+  unicode, escapes, nested objects, key reordering and exponent-form numbers, and
+  end to end against a running engine, where a Python agent and a TypeScript
+  agent proposing different amounts for the same refund converge on one.
+
+  This was not possible on `0.7.0`: without exported key derivation, a TypeScript
+  caller could not reach the same key without reimplementing the canonicalisation
+  by hand and getting it exactly right.
+
+### Notes
+
+- Purely additive. Nothing was removed or changed, so `^0.7.0` picks this up and
+  existing code continues to work untouched.
+
+- **Two places this cannot match the Python SDK**, documented in the API rather
+  than silently approximated:
+
+  - Python's `async_execution_lease` cancels the calling task when the lease is
+    lost. Node has no task cancellation, so `LeaseHandle` exposes `check()` and
+    an `AbortSignal` and losing a lease is cooperative. Anything irreversible
+    inside a long block should check first.
+  - Python binds `*args`/`**kwargs` against the function signature so `shared_on`
+    can select named parameters. JavaScript has no named arguments, so `sharedOn`
+    selects keys from a single object argument, and a tool using it must take one.
+
+- **Not included:** the LangGraph checkpointer. It needs `@langchain/langgraph`
+  as a peer dependency, and the Python implementation has a known defect under
+  concurrent read-modify-write that should be fixed before it is copied into a
+  second language.
+
+- The Python and TypeScript SDKs will be aligned at `0.8.0` on the next release.
+  Until then, matching version numbers do not imply matching feature sets:
+  Python `0.7.0` had the high-level API and TypeScript `0.7.0` did not.
+
+## 0.7.0
+
+### Added
+
+- Initial TypeScript/Node.js SDK. `CellaflowClient` over Connect RPC, covering
+  `startSession`, `commitStep`, `getGraph`, `checkIdempotencyCache`, `renewLease`
+  and `releaseLease`, with MessagePack serialization for state payloads.

package/README.md

@@ -0,0 +1,62 @@
+# @cellaflow/sdk
+
+The official TypeScript/Node.js SDK for the Cellaflow workflow engine.
+
+Cellaflow is the concurrency and durability layer for AI agent execution. It makes concurrent AI agent state transitions and external actions safe despite crashes, retries, and stale state.
+
+## Installation
+
+```bash
+npm install @cellaflow/sdk
+```
+
+## Quick Start
+
+```typescript
+import { CellaflowClient, StepStatus } from "@cellaflow/sdk";
+
+// 1. Initialize the client
+const client = new CellaflowClient({
+  target: "localhost:50051",
+  secure: false, // Set to true if your engine is behind HTTPS/TLS
+});
+
+async function main() {
+  // 2. Start a workflow session
+  const session = await client.startSession("my-agent-workflow", "1.0");
+  const sessionId = session.sessionId;
+
+  console.log("Started session:", sessionId);
+
+  // 3. Commit a step to the session
+  const result = await client.commitStep(
+    sessionId,
+    1,                       // Step sequence
+    "fetch_data",            // Step name
+    StepStatus.COMPLETED,    // Outcome
+    { data: "example" }      // Payload (auto-serialized via MessagePack)
+  );
+
+  console.log("Step committed.");
+
+  // 4. Retrieve the session graph
+  const [graph, nextCursor] = await client.getGraph(sessionId);
+  console.log("Graph:", graph);
+}
+
+main().catch(console.error);
+```
+
+## Features
+
+- **Built on Connect-ES**: Uses HTTP/2 for high performance and strict gRPC semantics.
+- **Safe Serialization**: Strictly uses MessagePack for state payloads to mitigate Remote Code Execution (RCE) risks associated with unvalidated JSON parsing.
+- **Idempotency Locks**: Built-in methods for leasing and fencing distributed locks (`checkIdempotencyCache`, `renewLease`, `releaseLease`).
+
+## Requirements
+
+- Node.js 18.0.0 or higher.
+
+## License
+
+Apache 2.0

package/dist/context.d.ts

@@ -0,0 +1,71 @@
+import type { CellaflowClient } from "./client.js";
+/**
+ * The session a tool call belongs to, plus the bookkeeping that keeps the local
+ * sequence counter aligned with the engine's.
+ */
+export declare class WorkflowContext {
+    readonly client: CellaflowClient;
+    readonly sessionId: string;
+    readonly workflowVersion: string;
+    sequence: number;
+    /**
+     * Names the work several agents are collaborating on: a ticket, a task, a
+     * tenant. Only {@link IdempotencyScope.SHARED} reads it, and that scope
+     * requires it.
+     */
+    readonly coordinationId?: string;
+    /**
+     * The session position the engine last reported, held from a cache hit until
+     * the next step consumes it. See {@link reconcileSequence}.
+     */
+    private reportedSequence?;
+    constructor(init: {
+        client: CellaflowClient;
+        sessionId: string;
+        workflowVersion: string;
+        sequence?: number;
+        coordinationId?: string;
+    });
+    /**
+     * Notes the session position the engine reported alongside a cache hit.
+     *
+     * Held rather than applied immediately: a run whose last act is a shared tool,
+     * which is the common shape, should not pay for bookkeeping it will never use.
+     * {@link reconcileSequence} consumes it at the start of the next step.
+     */
+    recordEngineSequence(sequence: number): void;
+    /**
+     * Adopts the position the engine reported on the last cache hit.
+     *
+     * Every tool call increments this counter, but a cache hit returns *without
+     * committing*. The engine's sequence therefore did not advance while the local
+     * one did, and the next commit fails the ordering check one step after the
+     * real cause.
+     *
+     * The same-session case survives on a coincidence rather than an invariant: a
+     * peer's commit advances the engine by exactly the amount this caller advanced
+     * locally, so the two happen to stay equal. Any asymmetry breaks it, such as a
+     * hit satisfied from a *different* session, or replicas that reached a shared
+     * tool after different numbers of steps.
+     *
+     * A no-op when the engine reported nothing, which is an older engine predating
+     * the field. Behaviour then degrades to the original defect rather than to
+     * something new.
+     */
+    reconcileSequence(): void;
+}
+export declare function registerSession(ctx: WorkflowContext): void;
+export declare function deregisterSession(ctx: WorkflowContext): void;
+/** Runs `fn` with `ctx` as the active context. */
+export declare function runWithContext<T>(ctx: WorkflowContext, fn: () => T): T;
+/**
+ * Returns the context a tool call belongs to.
+ *
+ * Falls back to the open-session registry when the async context was lost, but
+ * only when a single session is open. Two open sessions and a lost context is
+ * ambiguous, and guessing would attribute a side effect to the wrong run.
+ */
+export declare function getContext(): WorkflowContext;
+/** Whether a context is currently reachable, without throwing. */
+export declare function hasContext(): boolean;
+//# 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":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;GAGG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAElC,YAAY,IAAI,EAAE;QAChB,MAAM,EAAE,eAAe,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,EAMA;IAED;;;;;;OAMG;IACH,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE3C;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB,IAAI,IAAI,CAKxB;CACF;AAgBD,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAE5D;AAED,kDAAkD;AAClD,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,eAAe,CAqB5C;AAED,kEAAkE;AAClE,wBAAgB,UAAU,IAAI,OAAO,CAEpC"}

package/dist/context.js

@@ -0,0 +1,113 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * The session a tool call belongs to, plus the bookkeeping that keeps the local
+ * sequence counter aligned with the engine's.
+ */
+export class WorkflowContext {
+    client;
+    sessionId;
+    workflowVersion;
+    sequence;
+    /**
+     * Names the work several agents are collaborating on: a ticket, a task, a
+     * tenant. Only {@link IdempotencyScope.SHARED} reads it, and that scope
+     * requires it.
+     */
+    coordinationId;
+    /**
+     * The session position the engine last reported, held from a cache hit until
+     * the next step consumes it. See {@link reconcileSequence}.
+     */
+    reportedSequence;
+    constructor(init) {
+        this.client = init.client;
+        this.sessionId = init.sessionId;
+        this.workflowVersion = init.workflowVersion;
+        this.sequence = init.sequence ?? 0;
+        this.coordinationId = init.coordinationId;
+    }
+    /**
+     * Notes the session position the engine reported alongside a cache hit.
+     *
+     * Held rather than applied immediately: a run whose last act is a shared tool,
+     * which is the common shape, should not pay for bookkeeping it will never use.
+     * {@link reconcileSequence} consumes it at the start of the next step.
+     */
+    recordEngineSequence(sequence) {
+        this.reportedSequence = sequence;
+    }
+    /**
+     * Adopts the position the engine reported on the last cache hit.
+     *
+     * Every tool call increments this counter, but a cache hit returns *without
+     * committing*. The engine's sequence therefore did not advance while the local
+     * one did, and the next commit fails the ordering check one step after the
+     * real cause.
+     *
+     * The same-session case survives on a coincidence rather than an invariant: a
+     * peer's commit advances the engine by exactly the amount this caller advanced
+     * locally, so the two happen to stay equal. Any asymmetry breaks it, such as a
+     * hit satisfied from a *different* session, or replicas that reached a shared
+     * tool after different numbers of steps.
+     *
+     * A no-op when the engine reported nothing, which is an older engine predating
+     * the field. Behaviour then degrades to the original defect rather than to
+     * something new.
+     */
+    reconcileSequence() {
+        if (this.reportedSequence !== undefined) {
+            this.sequence = this.reportedSequence;
+            this.reportedSequence = undefined;
+        }
+    }
+}
+const storage = new AsyncLocalStorage();
+/**
+ * Sessions currently open, for frameworks that dispatch a tool off the calling
+ * context.
+ *
+ * `AsyncLocalStorage` follows `await` and `setTimeout`, which covers most
+ * frameworks. It does not follow a hop through a worker thread or a native
+ * callback that loses the async resource. Where exactly one session is open the
+ * context is recoverable from here; where several are, there is nothing to
+ * disambiguate them and the caller must bind explicitly.
+ */
+const openSessions = new Set();
+export function registerSession(ctx) {
+    openSessions.add(ctx);
+}
+export function deregisterSession(ctx) {
+    openSessions.delete(ctx);
+}
+/** Runs `fn` with `ctx` as the active context. */
+export function runWithContext(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+/**
+ * Returns the context a tool call belongs to.
+ *
+ * Falls back to the open-session registry when the async context was lost, but
+ * only when a single session is open. Two open sessions and a lost context is
+ * ambiguous, and guessing would attribute a side effect to the wrong run.
+ */
+export function getContext() {
+    const ctx = storage.getStore();
+    if (ctx)
+        return ctx;
+    if (openSessions.size === 1) {
+        return openSessions.values().next().value;
+    }
+    if (openSessions.size === 0) {
+        throw new Error("No CellaFlow session is active. A leased tool must be called inside " +
+            "durableTools(...), which is what binds it to a session. Without one " +
+            "there is no idempotency key to derive and nothing to lease.");
+    }
+    throw new Error(`The calling context was lost and ${openSessions.size} sessions are open, so ` +
+        "the session this tool belongs to is ambiguous. Bind it explicitly with " +
+        "session.bind(() => ...) inside the tool, or open one session at a time.");
+}
+/** Whether a context is currently reachable, without throwing. */
+export function hasContext() {
+    return storage.getStore() !== undefined || openSessions.size === 1;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;;GAGG;AACH,MAAM,OAAO,eAAe;IACjB,MAAM,CAAkB;IACxB,SAAS,CAAS;IAClB,eAAe,CAAS;IACjC,QAAQ,CAAS;IACjB;;;;OAIG;IACM,cAAc,CAAU;IAEjC;;;OAGG;IACK,gBAAgB,CAAU;IAElC,YAAY,IAMX;QACC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;IAC5C,CAAC;IAED;;;;;;OAMG;IACH,oBAAoB,CAAC,QAAgB;QACnC,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC;IACnC,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB;QACf,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC;YACtC,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;QACpC,CAAC;IACH,CAAC;CACF;AAED,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAmB,CAAC;AAEzD;;;;;;;;;GASG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,EAAmB,CAAC;AAEhD,MAAM,UAAU,eAAe,CAAC,GAAoB;IAClD,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAoB;IACpD,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,cAAc,CAAI,GAAoB,EAAE,EAAW;IACjE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAC/B,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IAEpB,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,YAAY,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAwB,CAAC;IAC/D,CAAC;IAED,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,sEAAsE;YACpE,sEAAsE;YACtE,6DAA6D,CAChE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,KAAK,CACb,oCAAoC,YAAY,CAAC,IAAI,yBAAyB;QAC5E,yEAAyE;QACzE,yEAAyE,CAC5E,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,QAAQ,EAAE,KAAK,SAAS,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC,CAAC;AACrE,CAAC"}

package/dist/durable.d.ts

@@ -0,0 +1,73 @@
+import { WorkflowContext } from "./context.js";
+/**
+ * Returns the session id holding `threadId`'s leased tool calls.
+ *
+ * Deterministic, so a restart derives the same value and the lease taken before
+ * a crash is still recognised afterwards.
+ *
+ * Thread ids are chosen by the application and colons are reserved by the
+ * engine's key layout, so an id containing one is hashed rather than rejected:
+ * `"user:123"` is an ordinary way to namespace a thread, and refusing it would
+ * turn an engine storage detail into a constraint on the caller's naming.
+ * Hashing keeps the one property that matters, that the same thread always
+ * derives the same session, at the cost of a session id that no longer reads
+ * back as the thread's name.
+ */
+export declare function toolSessionId(threadId: string): string;
+/** A LangGraph-style config, or a bare thread id. */
+export type ThreadRef = string | {
+    configurable?: {
+        thread_id?: string;
+    };
+};
+export interface DurableToolsOptions {
+    workflowId?: string;
+    version?: string;
+    target?: string;
+    secure?: boolean;
+    /**
+     * Names the work several agents are collaborating on: a ticket, a task, a
+     * tenant. Required by {@link IdempotencyScope.SHARED} and ignored otherwise.
+     */
+    coordinationId?: string;
+}
+/** The open session, for binding a tool the framework dispatched off-context. */
+export interface DurableSession {
+    readonly sessionId: string;
+    readonly context: WorkflowContext;
+    /**
+     * Re-binds the session around `fn`.
+     *
+     * Needed only when a framework runs a tool somewhere the async context does
+     * not reach, and more than one session is open. With a single open session the
+     * SDK recovers it without this.
+     */
+    bind<T>(fn: () => T): T;
+}
+/**
+ * Leases every {@link tool} call made inside `fn`.
+ *
+ * Not tied to any framework. The contract is a session id, from a LangGraph
+ * config or a bare string, and tools invoked while the callback is running.
+ *
+ * ```ts
+ * await durableTools({ configurable: { thread_id: "ticket-4417" } }, async () => {
+ *   await app.invoke({ ticket: "T-4417" }, config);
+ * });
+ * ```
+ *
+ * which is what makes a node's side effect happen at most once across a crash
+ * and resume. Without it a tool either finds no session at all, or one whose id
+ * is freshly generated per run, which derives a different key each time and so
+ * leases nothing across the restart that matters.
+ *
+ * Positional replay is deliberately not seeded here. Under the default
+ * `SESSION_WIDE` scope the derived key does not encode the position, so a
+ * resumed call derives the same key and the engine answers from the committed
+ * result. Deduplication comes from the idempotency cache, which is
+ * position-independent, rather than from a counter that cannot stay aligned when
+ * a framework resumes into the middle of a run.
+ */
+export declare function durableTools<T>(config: ThreadRef, options: DurableToolsOptions, fn: (session: DurableSession) => Promise<T>): Promise<T>;
+export declare function durableTools<T>(config: ThreadRef, fn: (session: DurableSession) => Promise<T>): Promise<T>;
+//# sourceMappingURL=durable.d.ts.map

package/dist/durable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable.d.ts","sourceRoot":"","sources":["../src/durable.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,EAIhB,MAAM,cAAc,CAAC;AAStB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAatD;AAED,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,YAAY,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAwB3E,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC;;;;;;OAMG;IACH,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,mBAAmB,EAC5B,EAAE,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAC1C,OAAO,CAAC,CAAC,CAAC,CAAC;AACd,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,SAAS,EACjB,EAAE,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAC1C,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist/durable.js

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import { CellaflowClient } from "./client.js";
+import { WorkflowContext, deregisterSession, registerSession, runWithContext, } from "./context.js";
+/**
+ * Appended to a caller's thread id to derive the tool session, keeping it
+ * distinct from whatever session a checkpointer may be using for the same
+ * thread.
+ */
+const TOOL_SESSION_SUFFIX = "-cellaflow-tools";
+/**
+ * Returns the session id holding `threadId`'s leased tool calls.
+ *
+ * Deterministic, so a restart derives the same value and the lease taken before
+ * a crash is still recognised afterwards.
+ *
+ * Thread ids are chosen by the application and colons are reserved by the
+ * engine's key layout, so an id containing one is hashed rather than rejected:
+ * `"user:123"` is an ordinary way to namespace a thread, and refusing it would
+ * turn an engine storage detail into a constraint on the caller's naming.
+ * Hashing keeps the one property that matters, that the same thread always
+ * derives the same session, at the cost of a session id that no longer reads
+ * back as the thread's name.
+ */
+export function toolSessionId(threadId) {
+    if (typeof threadId !== "string" || threadId.length === 0) {
+        throw new Error(`threadId must be a non-empty string, got ${JSON.stringify(threadId)}. ` +
+            "Every thread needs its own id: an empty one would put unrelated runs " +
+            "in a single session, where they would deduplicate against each other.");
+    }
+    if (threadId.includes(":")) {
+        const digest = createHash("sha256").update(threadId, "utf8").digest("hex").slice(0, 32);
+        return `lgthread-${digest}${TOOL_SESSION_SUFFIX}`;
+    }
+    return `${threadId}${TOOL_SESSION_SUFFIX}`;
+}
+function threadIdFrom(config) {
+    if (typeof config === "string")
+        return config;
+    if (typeof config !== "object" || config === null) {
+        throw new TypeError("durableTools() needs the config you pass to invoke(), or a thread id " +
+            `string; got ${typeof config}. Usage: ` +
+            'durableTools({ configurable: { thread_id: "..." } }, fn).');
+    }
+    const threadId = config.configurable?.thread_id;
+    if (typeof threadId !== "string" || threadId.length === 0) {
+        throw new Error("durableTools() needs a config carrying configurable.thread_id, the same " +
+            "one you pass to invoke(). The thread id is what the tool session is " +
+            "derived from, so there is nothing to bind the lease to without it.");
+    }
+    return threadId;
+}
+export async function durableTools(config, optionsOrFn, maybeFn) {
+    const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
+    const fn = (typeof optionsOrFn === "function" ? optionsOrFn : maybeFn);
+    const { workflowId = "durable-tools", version = "1.0.0", target = "localhost:50051", secure = false, coordinationId, } = options;
+    const threadId = threadIdFrom(config);
+    const sessionId = toolSessionId(threadId);
+    const client = new CellaflowClient({ target, secure });
+    const resp = await client.startSession(workflowId, version, sessionId);
+    const ctx = new WorkflowContext({
+        client,
+        sessionId: resp.sessionId,
+        workflowVersion: resp.version,
+        sequence: 0,
+        coordinationId,
+    });
+    const session = {
+        sessionId: ctx.sessionId,
+        context: ctx,
+        bind: (inner) => runWithContext(ctx, inner),
+    };
+    // Registered as well as bound: the async context covers frameworks that
+    // dispatch tools on the calling context, and the registry covers those that
+    // do not.
+    registerSession(ctx);
+    try {
+        return await runWithContext(ctx, () => fn(session));
+    }
+    finally {
+        deregisterSession(ctx);
+        client.close();
+    }
+}
+//# sourceMappingURL=durable.js.map

package/dist/durable.js.map

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

package/dist/execution.d.ts

@@ -0,0 +1,96 @@
+/** Raised when the requested execution lease cannot be acquired. */
+export declare class LeaseNotAcquired extends Error {
+    constructor(message: string);
+}
+/** Raised by `LeaseHandle.check()` once the lease has been lost. */
+export declare class LeaseLostError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare class LeaseHandle {
+    readonly fencingToken: number;
+    private readonly controller;
+    private lostDetail?;
+    constructor(fencingToken: number);
+    /** Aborts when the lease is lost. Pass to `fetch`, streams, or your own loops. */
+    get signal(): AbortSignal;
+    get isLost(): boolean;
+    /** @internal */
+    markLost(detail: string): void;
+    /**
+     * 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(): void;
+}
+/**
+ * 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 declare function currentLease(): LeaseHandle;
+export interface ExecutionLeaseOptions {
+    /** Identifies this worker. Sent as `agentId`. */
+    workerId: string;
+    target?: string;
+    secure?: boolean;
+    ttlMs?: number;
+    heartbeatIntervalMs?: number;
+    /** Notified when the lease is lost. A notification, not a substitute for checking. */
+    onLeaseLost?: (detail: string) => void;
+    /**
+     * How long to wait for a lease another worker is holding. Defaults to 0, which
+     * fails immediately with {@link LeaseNotAcquired}.
+     */
+    waitMs?: number;
+}
+/**
+ * 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 declare function executionLease<T>(key: string, options: ExecutionLeaseOptions, fn: (lease: LeaseHandle) => Promise<T>): Promise<T>;
+/**
+ * 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 declare function taskLease<A extends unknown[], R>(fn: (...args: A) => Promise<R>, options: ExecutionLeaseOptions & {
+    key: string | ((...args: A) => string);
+}): (...args: A) => Promise<R>;
+//# sourceMappingURL=execution.d.ts.map

package/dist/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AAQA,oEAAoE;AACpE,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,oEAAoE;AACpE,qBAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;;;;;;GASG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,UAAU,CAAC,CAAS;IAE5B,YAAY,YAAY,EAAE,MAAM,EAE/B;IAED,kFAAkF;IAClF,IAAI,MAAM,IAAI,WAAW,CAExB;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,gBAAgB;IAChB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAI7B;IAED;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAIZ;CACF;AAID;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,WAAW,CAS1C;AAED,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sFAAsF;IACtF,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,qBAAqB,EAC9B,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,CAAC,CAAC,CAoEZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAC9C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,OAAO,EAAE,qBAAqB,GAAG;IAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,CAAA;CAAE,GAC1E,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAM5B"}