@cellaflow/sdk 0.7.0 → 0.7.1

package/dist/tool.js

@@ -0,0 +1,183 @@
+import { CacheStatus } from "./cellaflow/v1/idempotency_pb.js";
+import { StepStatus } from "./cellaflow/v1/common_pb.js";
+import { getContext } from "./context.js";
+import { IdempotencyScope, deriveIdempotencyKey } from "./idempotency.js";
+import { LeaseHeartbeat } from "./lease.js";
+import { deserialize } from "./serialization.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 class DivergentStepError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "DivergentStepError";
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * 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 function tool(fn, options = {}) {
+    const { idempotencyKey, agentId = "default", scope = IdempotencyScope.SESSION_WIDE, sharedOn, } = options;
+    const toolName = options.toolName ?? fn.name;
+    if (!toolName) {
+        throw new Error("tool() needs a name: it is part of the idempotency key, so two anonymous " +
+            "tools would otherwise derive the same key for different work. Pass " +
+            "{ toolName: '...' } or use a named function.");
+    }
+    if (sharedOn !== undefined && scope !== IdempotencyScope.SHARED) {
+        throw new Error("sharedOn only applies to IdempotencyScope.SHARED. Under any other scope " +
+            "the key already includes the session, so restricting the hash changes " +
+            "what deduplicates without making anything converge.");
+    }
+    if (sharedOn !== undefined && idempotencyKey) {
+        throw new Error("sharedOn and idempotencyKey both decide the key. Supply one: an explicit " +
+            "key is already the identity of the work.");
+    }
+    return async function leasedTool(...args) {
+        const ctx = getContext();
+        // A cache hit may have left this counter ahead of the engine's. Adopt the
+        // position it reported before claiming the next sequence, or this commit
+        // fails the ordering check and names the wrong step. Deferred to here rather
+        // than done on the hit itself so a run that ends on a hit does no extra work.
+        ctx.reconcileSequence();
+        ctx.sequence += 1;
+        const seq = ctx.sequence;
+        let ikey = idempotencyKey;
+        if (!ikey) {
+            const kwargs = sharedOn !== undefined && args.length === 1 && isPlainObject(args[0])
+                ? args[0]
+                : {};
+            if (sharedOn !== undefined && Object.keys(kwargs).length === 0) {
+                throw new Error(`Tool '${toolName}' uses sharedOn but was not called with a single ` +
+                    "object argument. The names in sharedOn are read from that object, " +
+                    "so there is nothing to select from.");
+            }
+            ikey = deriveIdempotencyKey({
+                sessionId: ctx.sessionId,
+                workflowVersion: ctx.workflowVersion,
+                stepSequence: seq,
+                agentId,
+                toolName,
+                scope,
+                coordinationId: ctx.coordinationId,
+                args: sharedOn !== undefined ? [] : args,
+                kwargs,
+                sharedOn,
+            });
+        }
+        let fencingToken = 0;
+        let hb;
+        // Arbitrate. Loop because IN_PROGRESS means another worker holds it and the
+        // right move is to wait for their result rather than to act.
+        for (;;) {
+            let resp;
+            try {
+                resp = await ctx.client.checkIdempotencyCache(agentId, ikey, 0, undefined, ctx.sessionId, 
+                // Tell the engine where this call intends to write, so a lease at an
+                // already-committed position is refused before the body runs rather
+                // than after.
+                seq);
+            }
+            catch (err) {
+                if (isFailedPrecondition(err)) {
+                    throw new DivergentStepError(`Step '${toolName}' at sequence ${seq} was refused: another agent ` +
+                        "already owns this graph position with different inputs.", err);
+                }
+                throw err;
+            }
+            if (resp.status === CacheStatus.HIT) {
+                // Returns without committing, so record where the engine says the
+                // session sits. The next step adopts it.
+                if (resp.currentSequence !== undefined) {
+                    ctx.recordEngineSequence(Number(resp.currentSequence));
+                }
+                const payload = resp.cachedResult?.outputPayload;
+                if (payload && payload.length > 0) {
+                    const envelope = deserialize(payload);
+                    return envelope?.result;
+                }
+                return undefined;
+            }
+            if (resp.status === CacheStatus.IN_PROGRESS) {
+                await sleep(Number(resp.retryAfterMs ?? 1000n));
+                continue;
+            }
+            if (resp.status === CacheStatus.ACQUIRED) {
+                fencingToken = Number(resp.fencingToken ?? 0n);
+                const intervalMs = Number(resp.heartbeatIntervalMs ?? 5000n);
+                hb = new LeaseHeartbeat({
+                    client: ctx.client,
+                    agentId,
+                    idempotencyKey: ikey,
+                    fencingToken,
+                    heartbeatIntervalMs: intervalMs,
+                });
+                hb.start();
+            }
+            break;
+        }
+        try {
+            const result = await fn(...args);
+            await ctx.client.commitStep(ctx.sessionId, seq, toolName, StepStatus.SUCCESS, 
+            // The envelope is part of the cross-language contract: the Python SDK
+            // commits {result} and reads .result back. A bare value here would not
+            // interoperate on a shared key.
+            { result }, ikey, fencingToken);
+            return result;
+        }
+        catch (err) {
+            if (fencingToken > 0) {
+                await ctx.client
+                    .releaseLease(agentId, ikey, fencingToken, "TOOL_ERROR")
+                    .catch(() => {
+                    // The lease expires on its own. Losing the release is not worth
+                    // masking the error that caused it.
+                });
+            }
+            throw err;
+        }
+        finally {
+            await hb?.stop();
+        }
+    };
+}
+/** `step` and `tool` are the same mechanism, kept distinct for readability. */
+export const step = tool;
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Connect and gRPC surface `FAILED_PRECONDITION` differently depending on
+ * transport, so match on the code rather than the class.
+ */
+function isFailedPrecondition(err) {
+    const code = err?.code;
+    return code === 9 || code === "failed_precondition";
+}
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cellaflow/sdk",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "TypeScript/Node.js SDK for the Cellaflow workflow engine",
   "type": "module",
   "main": "dist/index.js",
@@ -47,7 +47,8 @@
     "@bufbuild/protobuf": "^1.10.1",
     "@connectrpc/connect": "^1.7.0",
     "@connectrpc/connect-node": "^1.7.0",
-    "@msgpack/msgpack": "^3.1.3"
+    "@msgpack/msgpack": "^3.1.3",
+    "canonicalize": "^4.0.0"
   },
   "devDependencies": {
     "@bufbuild/buf": "^1.73.0",

package/src/context.ts

@@ -0,0 +1,137 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+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 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?: number;
+
+  constructor(init: {
+    client: CellaflowClient;
+    sessionId: string;
+    workflowVersion: string;
+    sequence?: number;
+    coordinationId?: string;
+  }) {
+    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: number): void {
+    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(): void {
+    if (this.reportedSequence !== undefined) {
+      this.sequence = this.reportedSequence;
+      this.reportedSequence = undefined;
+    }
+  }
+}
+
+const storage = new AsyncLocalStorage<WorkflowContext>();
+
+/**
+ * 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<WorkflowContext>();
+
+export function registerSession(ctx: WorkflowContext): void {
+  openSessions.add(ctx);
+}
+
+export function deregisterSession(ctx: WorkflowContext): void {
+  openSessions.delete(ctx);
+}
+
+/** Runs `fn` with `ctx` as the active context. */
+export function runWithContext<T>(ctx: WorkflowContext, fn: () => T): T {
+  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(): WorkflowContext {
+  const ctx = storage.getStore();
+  if (ctx) return ctx;
+
+  if (openSessions.size === 1) {
+    return openSessions.values().next().value as WorkflowContext;
+  }
+
+  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(): boolean {
+  return storage.getStore() !== undefined || openSessions.size === 1;
+}

package/src/durable.ts

@@ -0,0 +1,177 @@
+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: string): string {
+  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}`;
+}
+
+/** A LangGraph-style config, or a bare thread id. */
+export type ThreadRef = string | { configurable?: { thread_id?: string } };
+
+function threadIdFrom(config: ThreadRef): string {
+  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 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 async function durableTools<T>(
+  config: ThreadRef,
+  options: DurableToolsOptions,
+  fn: (session: DurableSession) => Promise<T>,
+): Promise<T>;
+export async function durableTools<T>(
+  config: ThreadRef,
+  fn: (session: DurableSession) => Promise<T>,
+): Promise<T>;
+export async function durableTools<T>(
+  config: ThreadRef,
+  optionsOrFn: DurableToolsOptions | ((session: DurableSession) => Promise<T>),
+  maybeFn?: (session: DurableSession) => Promise<T>,
+): Promise<T> {
+  const options: DurableToolsOptions =
+    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: DurableSession = {
+    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();
+  }
+}