@cellaflow/sdk 0.7.0

package/dist/client.js

@@ -0,0 +1,187 @@
+import { createPromiseClient, } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import { WorkflowEngineService } from "./cellaflow/v1/service_connect.js";
+import { serialize, deserialize } from "./serialization.js";
+export class CellaflowClient {
+    /**
+     * gRPC Client for the Cellaflow Engine (Connect-ES transport).
+     * Handles communication with the engine and strictly uses MessagePack
+     * for state payloads.
+     */
+    client;
+    constructor(options = {}) {
+        const { target = "localhost:50051", secure = false } = options;
+        // Use http/https based on the secure flag
+        const baseUrl = secure ? `https://${target}` : `http://${target}`;
+        const transport = createGrpcTransport({
+            baseUrl,
+            httpVersion: "2",
+        });
+        this.client = createPromiseClient(WorkflowEngineService, transport);
+    }
+    /**
+     * Starts a new workflow execution session.
+     *
+     * @param workflowId - The workflow definition ID.
+     * @param version - The workflow version string.
+     * @param sessionId - Optional client-proposed session ID. When provided, the
+     *   engine performs a transactional check-and-insert to prevent concurrent
+     *   race conditions. Omit to let the engine assign one.
+     */
+    async startSession(workflowId, version, sessionId) {
+        const req = { workflowId, version };
+        // Only set sessionId when truthy — matches Python's `if session_id:` guard.
+        // Sending an empty string may trigger the engine's custom-ID validation path.
+        if (sessionId) {
+            req.sessionId = sessionId;
+        }
+        return await this.client.startSession(req);
+    }
+    /**
+     * Commits a completed step result to the session graph.
+     *
+     * @param sessionId - The session to commit to.
+     * @param sequence - The step sequence number (1-based).
+     * @param name - Human-readable step name.
+     * @param status - The step outcome status.
+     * @param outputPayload - Arbitrary step output. Serialized as MessagePack.
+     * @param idempotencyKey - Optional idempotency lease key.
+     * @param idempotencyFencingToken - Required when `idempotencyKey` is set.
+     */
+    async commitStep(sessionId, sequence, name, status, outputPayload, idempotencyKey, idempotencyFencingToken) {
+        // Strictly serialize object to MessagePack
+        const serializedState = serialize(outputPayload);
+        const req = {
+            sessionId,
+            stepResult: {
+                sequence: BigInt(sequence),
+                name,
+                status,
+                outputPayload: Buffer.from(serializedState),
+            },
+        };
+        if (idempotencyKey !== undefined) {
+            req.idempotencyKey = idempotencyKey;
+            if (idempotencyFencingToken === undefined) {
+                throw new Error("idempotencyFencingToken required if idempotencyKey is set");
+            }
+            req.idempotencyFencingToken = BigInt(idempotencyFencingToken);
+        }
+        return await this.client.commitStep(req);
+    }
+    /**
+     * Returns a paginated list of committed step results for a session.
+     *
+     * @returns A tuple of (step results, next_cursor). `next_cursor` is
+     *   `undefined` when there are no more pages. Each step result's
+     *   `outputPayload` is fully deserialized from MessagePack.
+     */
+    async getGraph(sessionId, limit, cursor) {
+        const req = { sessionId };
+        if (limit !== undefined) {
+            req.limit = limit;
+        }
+        if (cursor !== undefined) {
+            req.cursor = cursor;
+        }
+        const resp = await this.client.getGraph(req);
+        const results = resp.steps.map((step) => ({
+            sequence: step.sequence,
+            name: step.name,
+            status: step.status,
+            // Guard against empty payload (default Uint8Array(0)) to prevent
+            // msgpack from throwing on an empty buffer.
+            outputPayload: step.outputPayload.length > 0 ? deserialize(step.outputPayload) : {},
+            idempotencyKey: step.idempotencyKey,
+        }));
+        const nextCursor = resp.nextCursor ? resp.nextCursor : undefined;
+        return [results, nextCursor];
+    }
+    /**
+     * Arbitrates the idempotency lease for `idempotencyKey`.
+     *
+     * Supplying `sessionId` also asks the engine for the session's committed
+     * position, returned as `currentSequence` on every status. The idempotency
+     * key is opaque to the engine, so the session cannot be inferred from it —
+     * without this the engine has nothing to answer from.
+     *
+     * Supplying `sequence` — the position this caller intends to write to —
+     * additionally lets the engine refuse a lease that would authorise a side
+     * effect at an already-committed position, instead of rejecting the commit
+     * afterwards once the side effect has happened. The engine raises
+     * `FAILED_PRECONDITION` when refused. Both fields are optional on the wire;
+     * omitting `sequence` keeps the position unguarded.
+     */
+    async checkIdempotencyCache(agentId, idempotencyKey, waitTimeoutMs, leaseTtlMs, sessionId, sequence) {
+        const req = { agentId, idempotencyKey };
+        // These proto fields are uint64 → bigint; convert from the JS number API.
+        if (waitTimeoutMs !== undefined) {
+            req.waitTimeoutMs = BigInt(waitTimeoutMs);
+        }
+        if (leaseTtlMs !== undefined) {
+            req.leaseTtlMs = BigInt(leaseTtlMs);
+        }
+        if (sessionId !== undefined) {
+            req.sessionId = sessionId;
+        }
+        if (sequence !== undefined) {
+            req.sequence = BigInt(sequence);
+        }
+        return await this.client.checkIdempotencyCache(req);
+    }
+    /**
+     * Renews a held idempotency lease.
+     *
+     * @param timeoutSecs - Bounds the RPC in **seconds**. Heartbeat callers
+     *   MUST supply a positive value: without a deadline a black-holed
+     *   connection parks the calling thread indefinitely, and the shutdown
+     *   path that joins that thread parks with it.
+     */
+    async renewLease(agentId, idempotencyKey, fencingToken, extendMs, timeoutSecs) {
+        const req = {
+            agentId,
+            idempotencyKey,
+            fencingToken: BigInt(fencingToken),
+            extendMs: BigInt(extendMs),
+        };
+        return await this.client.renewLease(req, {
+            // Guard against timeout=0 which would cause an instant timeout.
+            timeoutMs: timeoutSecs !== undefined && timeoutSecs > 0
+                ? timeoutSecs * 1000
+                : undefined,
+        });
+    }
+    /**
+     * Releases a held idempotency lease.
+     *
+     * @param timeoutSecs - Bounds the RPC in **seconds**.
+     */
+    async releaseLease(agentId, idempotencyKey, fencingToken, reason, timeoutSecs) {
+        const req = {
+            agentId,
+            idempotencyKey,
+            fencingToken: BigInt(fencingToken),
+        };
+        if (reason !== undefined) {
+            req.reason = reason;
+        }
+        return await this.client.releaseLease(req, {
+            timeoutMs: timeoutSecs !== undefined && timeoutSecs > 0
+                ? timeoutSecs * 1000
+                : undefined,
+        });
+    }
+    /**
+     * Provided for API compatibility with the Python client.
+     *
+     * Connect-ES v1 with `createGrpcTransport` does not expose an explicit
+     * close/shutdown method — HTTP/2 sessions are managed by Node.js and are
+     * cleaned up on process exit or when the client is garbage-collected.
+     * Long-lived server processes with many short-lived clients should let the
+     * garbage collector handle cleanup.
+     */
+    close() {
+        // No-op: Connect-ES v1 does not provide a transport.close() API.
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./serialization.js";
+export * from "./cellaflow/v1/common_pb.js";
+export * from "./cellaflow/v1/idempotency_pb.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./client.js";
+export * from "./serialization.js";
+export * from "./cellaflow/v1/common_pb.js";
+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.
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/serialization.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Serializes a JavaScript object to a MessagePack byte array.
+ * This ensures we never use JSON for state payloads, mitigating RCE risks.
+ *
+ * @throws {TypeError} If `data` is not a plain, non-null object.
+ */
+export declare function serialize(data: Record<string, any>): Uint8Array;
+/**
+ * Deserializes a MessagePack byte array back into a JavaScript object.
+ *
+ * Uses `ArrayBuffer.isView()` instead of `instanceof Uint8Array` to work
+ * correctly across JS realms (worker threads, vm contexts, etc.).
+ *
+ * @throws {TypeError} If `data` is not a Uint8Array / ArrayBufferView.
+ * @throws {TypeError} If the deserialized value is not a plain object.
+ */
+export declare function deserialize(data: Uint8Array): Record<string, any>;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,UAAU,CAY/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqBjE"}

package/dist/serialization.js

@@ -0,0 +1,41 @@
+import { encode, decode } from "@msgpack/msgpack";
+/**
+ * Serializes a JavaScript object to a MessagePack byte array.
+ * This ensures we never use JSON for state payloads, mitigating RCE risks.
+ *
+ * @throws {TypeError} If `data` is not a plain, non-null object.
+ */
+export function serialize(data) {
+    // Explicit null check first — `typeof null === "object"` would otherwise
+    // produce a misleading error message reporting "got object" instead of "got null".
+    if (data === null) {
+        throw new TypeError("Expected an object for serialization, got null");
+    }
+    if (typeof data !== "object" || Array.isArray(data)) {
+        throw new TypeError(`Expected an object for serialization, got ${Array.isArray(data) ? "array" : typeof data}`);
+    }
+    return encode(data);
+}
+/**
+ * Deserializes a MessagePack byte array back into a JavaScript object.
+ *
+ * Uses `ArrayBuffer.isView()` instead of `instanceof Uint8Array` to work
+ * correctly across JS realms (worker threads, vm contexts, etc.).
+ *
+ * @throws {TypeError} If `data` is not a Uint8Array / ArrayBufferView.
+ * @throws {TypeError} If the deserialized value is not a plain object.
+ */
+export function deserialize(data) {
+    // ArrayBuffer.isView is cross-realm safe; instanceof Uint8Array is not.
+    if (!ArrayBuffer.isView(data)) {
+        throw new TypeError(`Expected Uint8Array for deserialization, got ${data === null ? "null" : typeof data}`);
+    }
+    const unpacked = decode(data);
+    if (typeof unpacked !== "object" ||
+        unpacked === null ||
+        Array.isArray(unpacked)) {
+        throw new TypeError(`Deserialized data is not an object, got ${unpacked === null ? "null" : typeof unpacked}`);
+    }
+    return unpacked;
+}
+//# sourceMappingURL=serialization.js.map

package/dist/serialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.js","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAyB;IACjD,yEAAyE;IACzE,mFAAmF;IACnF,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,SAAS,CACjB,6CAA6C,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAC3F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,wEAAwE;IACxE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,SAAS,CACjB,gDAAgD,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CACvF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAE9B,IACE,OAAO,QAAQ,KAAK,QAAQ;QAC5B,QAAQ,KAAK,IAAI;QACjB,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EACvB,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,2CAA2C,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,QAAQ,EAAE,CAC1F,CAAC;IACJ,CAAC;IAED,OAAO,QAA+B,CAAC;AACzC,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@cellaflow/sdk",
+  "version": "0.7.0",
+  "description": "TypeScript/Node.js SDK for the Cellaflow workflow engine",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "cellaflow",
+    "workflow",
+    "grpc",
+    "connect-rpc",
+    "sdk"
+  ],
+  "author": "Cellaflow <hello@cellaflow.com>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cellaflow/cellaflow-sdks.git",
+    "directory": "typescript"
+  },
+  "homepage": "https://github.com/cellaflow/cellaflow-sdks/tree/main/typescript#readme",
+  "bugs": {
+    "url": "https://github.com/cellaflow/cellaflow-sdks/issues"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^1.10.1",
+    "@connectrpc/connect": "^1.7.0",
+    "@connectrpc/connect-node": "^1.7.0",
+    "@msgpack/msgpack": "^3.1.3"
+  },
+  "devDependencies": {
+    "@bufbuild/buf": "^1.73.0",
+    "@bufbuild/protoc-gen-es": "^1.10.1",
+    "@connectrpc/protoc-gen-connect-es": "^1.7.0",
+    "@types/node": "^26.6.2",
+    "typescript": "^7.0.2"
+  }
+}

package/src/cellaflow/v1/common_pb.ts

@@ -0,0 +1,195 @@
+// @generated by protoc-gen-es v1.10.1 with parameter "target=ts,import_extension=.js"
+// @generated from file cellaflow/v1/common.proto (package cellaflow.v1, syntax proto3)
+/* eslint-disable */
+// @ts-nocheck
+
+import type { BinaryReadOptions, FieldList, JsonReadOptions, JsonValue, PartialMessage, PlainMessage } from "@bufbuild/protobuf";
+import { Message, proto3 } from "@bufbuild/protobuf";
+
+/**
+ * StepStatus defines compile-time type-safe execution states for a step.
+ *
+ * @generated from enum cellaflow.v1.StepStatus
+ */
+export enum StepStatus {
+  /**
+   * @generated from enum value: STEP_STATUS_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * @generated from enum value: STEP_STATUS_RUNNING = 1;
+   */
+  RUNNING = 1,
+
+  /**
+   * @generated from enum value: STEP_STATUS_SUCCESS = 2;
+   */
+  SUCCESS = 2,
+
+  /**
+   * @generated from enum value: STEP_STATUS_FAILED = 3;
+   */
+  FAILED = 3,
+
+  /**
+   * @generated from enum value: STEP_STATUS_TIMER_SCHEDULED = 4;
+   */
+  TIMER_SCHEDULED = 4,
+
+  /**
+   * @generated from enum value: STEP_STATUS_TIMER_FIRED = 5;
+   */
+  TIMER_FIRED = 5,
+}
+// Retrieve enum metadata with: proto3.getEnumType(StepStatus)
+proto3.util.setEnumType(StepStatus, "cellaflow.v1.StepStatus", [
+  { no: 0, name: "STEP_STATUS_UNSPECIFIED" },
+  { no: 1, name: "STEP_STATUS_RUNNING" },
+  { no: 2, name: "STEP_STATUS_SUCCESS" },
+  { no: 3, name: "STEP_STATUS_FAILED" },
+  { no: 4, name: "STEP_STATUS_TIMER_SCHEDULED" },
+  { no: 5, name: "STEP_STATUS_TIMER_FIRED" },
+]);
+
+/**
+ * StepResult represents the outcome of a single step in a workflow execution session.
+ *
+ * @generated from message cellaflow.v1.StepResult
+ */
+export class StepResult extends Message<StepResult> {
+  /**
+   * Optional to distinguish between explicit sequence 0 and unset/omitted values.
+   * Validation: Must be greater than 0 during normal execution.
+   *
+   * @generated from field: optional uint64 sequence = 1;
+   */
+  sequence?: bigint;
+
+  /**
+   * @generated from field: string name = 2;
+   */
+  name = "";
+
+  /**
+   * Safe enum-typed status to prevent raw string errors (e.g. typos).
+   *
+   * @generated from field: cellaflow.v1.StepStatus status = 3;
+   */
+  status = StepStatus.UNSPECIFIED;
+
+  /**
+   * Output payload generated by this execution step.
+   * Validation: Size must not exceed 4MB (4,194,304 bytes).
+   *
+   * @generated from field: bytes output_payload = 4;
+   */
+  outputPayload = new Uint8Array(0);
+
+  /**
+   * Unique idempotency key to prevent duplicate tool execution.
+   * Validation: If specified, must not be empty.
+   *
+   * @generated from field: optional string idempotency_key = 5;
+   */
+  idempotencyKey?: string;
+
+  /**
+   * Deadline for the sleep operation, represented as a Unix timestamp in milliseconds.
+   * Used when status is STEP_STATUS_TIMER_SCHEDULED.
+   *
+   * @generated from field: optional uint64 deadline_ms = 6;
+   */
+  deadlineMs?: bigint;
+
+  /**
+   * The sequence number of the originating TimerScheduled event.
+   * Used when status is STEP_STATUS_TIMER_FIRED to explicitly pair events.
+   *
+   * @generated from field: optional uint64 source_sequence = 7;
+   */
+  sourceSequence?: bigint;
+
+  constructor(data?: PartialMessage<StepResult>) {
+    super();
+    proto3.util.initPartial(data, this);
+  }
+
+  static readonly runtime: typeof proto3 = proto3;
+  static readonly typeName = "cellaflow.v1.StepResult";
+  static readonly fields: FieldList = proto3.util.newFieldList(() => [
+    { no: 1, name: "sequence", kind: "scalar", T: 4 /* ScalarType.UINT64 */, opt: true },
+    { no: 2, name: "name", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 3, name: "status", kind: "enum", T: proto3.getEnumType(StepStatus) },
+    { no: 4, name: "output_payload", kind: "scalar", T: 12 /* ScalarType.BYTES */ },
+    { no: 5, name: "idempotency_key", kind: "scalar", T: 9 /* ScalarType.STRING */, opt: true },
+    { no: 6, name: "deadline_ms", kind: "scalar", T: 4 /* ScalarType.UINT64 */, opt: true },
+    { no: 7, name: "source_sequence", kind: "scalar", T: 4 /* ScalarType.UINT64 */, opt: true },
+  ]);
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): StepResult {
+    return new StepResult().fromBinary(bytes, options);
+  }
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): StepResult {
+    return new StepResult().fromJson(jsonValue, options);
+  }
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): StepResult {
+    return new StepResult().fromJsonString(jsonString, options);
+  }
+
+  static equals(a: StepResult | PlainMessage<StepResult> | undefined, b: StepResult | PlainMessage<StepResult> | undefined): boolean {
+    return proto3.util.equals(StepResult, a, b);
+  }
+}
+
+/**
+ * @generated from message cellaflow.v1.WorkflowDefinition
+ */
+export class WorkflowDefinition extends Message<WorkflowDefinition> {
+  /**
+   * @generated from field: string id = 1;
+   */
+  id = "";
+
+  /**
+   * @generated from field: string version = 2;
+   */
+  version = "";
+
+  /**
+   * @generated from field: string description = 3;
+   */
+  description = "";
+
+  constructor(data?: PartialMessage<WorkflowDefinition>) {
+    super();
+    proto3.util.initPartial(data, this);
+  }
+
+  static readonly runtime: typeof proto3 = proto3;
+  static readonly typeName = "cellaflow.v1.WorkflowDefinition";
+  static readonly fields: FieldList = proto3.util.newFieldList(() => [
+    { no: 1, name: "id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 2, name: "version", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 3, name: "description", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+  ]);
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): WorkflowDefinition {
+    return new WorkflowDefinition().fromBinary(bytes, options);
+  }
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): WorkflowDefinition {
+    return new WorkflowDefinition().fromJson(jsonValue, options);
+  }
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): WorkflowDefinition {
+    return new WorkflowDefinition().fromJsonString(jsonString, options);
+  }
+
+  static equals(a: WorkflowDefinition | PlainMessage<WorkflowDefinition> | undefined, b: WorkflowDefinition | PlainMessage<WorkflowDefinition> | undefined): boolean {
+    return proto3.util.equals(WorkflowDefinition, a, b);
+  }
+}
+