@skein-js/bullmq 0.0.0-stage → 0.23.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @skein-js/bullmq
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional BullMQ access to Skein's native client. External command/outcome queues share the runtime's
+authorization, atomic admission, retained results and outbox. Skein's internal execution and delivery
+queues remain in charge.
+
+```ts
+import { createBullMqTransport } from "@skein-js/bullmq";
+
+const access = createBullMqTransport({
+  commandQueue: "commands",
+  outcomeQueue, // borrowed BullMQ Queue
+  connection,
+  authenticate: async (job) => ({ authContext: await verifyCaller(job) }),
+});
+// Compose access.wrapDispatcher(existingDispatcher) into ProtocolDeps.webhookDispatcher.
+// Bind access.outcomeTarget on runtime.createNativeClient({sourceId, allowedAssistants, ...}).
+await access.start(nativeClient);
+// ... shutdown:
+await access.stop(); // closes owned workers, preserves borrowed connections/queues
+```
+
+BullMQ 5/6 and ioredis 5/6 are supported. Producers send version-1 `BullMqCommand` values and configure
+bounded BullMQ attempts/backoff. Job return values acknowledge admission; durable outcomes carry
+`eventId` equal to the outbox delivery ID. Persist receiver deduplication independently of broker job
+retention. `result.get` and `state.get` support bounded digest-checked chunks; native results stay whole.
+
+`projectResult` projects outcomes and `result.get`, not full `run.get` metadata or `state.get` snapshots.
+Reject unwanted raw queries in the host's `authenticate`/`route` callbacks. Redis readers can inspect
+job inputs and return values outside native authorization; configure credentials, ACLs, TLS and job
+retention. Skein deletion does not purge external broker copies.
+
+The [runnable approval example](https://github.com/skein-js/skein-js/tree/main/examples/native-transports)
+shows explicit lifecycle, a host-bound principal, projected results, chunk verification and durable
+receiver deduplication. See [security and operations](https://github.com/skein-js/skein-js/blob/main/docs/native-access-security.md).
+
+Read [native access and BullMQ](https://github.com/skein-js/skein-js/blob/main/docs/native-access.md)
+for setup, message formats, ownership, errors and reconciliation. Run the external packed consumers
+with `pnpm exec nx run test-support:test-native-consumer`.
+
+The package supplies its runtime ioredis dependency, including when BullMQ 6 resolves ioredis through
+its optional peer. The adapter accepts connection options or a borrowed supported ioredis `Redis` or
+`Cluster` client.
+For mixed BullMQ 5/ioredis 6 installs, give upstream BullMQ queues and workers connection options so
+they use BullMQ's own client; the maintained example demonstrates this without application casts.
+The adapter keeps borrowed clients and the outcome queue usable after `stop()`.
+Borrowed outcome queues can come from a different supported BullMQ major than the adapter's worker.
+Use `BullMqTransportOptions<typeof outcomeQueue>` when explicitly annotating options for that queue;
+existing annotations retain the full upstream Queue type by default.

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import { NativeStartInput, NativeResumeInput, WebhookDispatcher, NativeClient, NativeCallOptions } from '@skein-js/agent-protocol';
+import { Run, RunResult } from '@skein-js/core';
+import { Queue, ConnectionOptions, Job } from 'bullmq';
+import { Redis, Cluster } from 'ioredis';
+
+/** The BullMQ adapter's wire format. Authority, destinations and deadlines belong to the host. */
+type BullMqCommand = {
+    version: 1;
+    commandId: string;
+    correlationId?: string;
+} & ({
+    operation: "start";
+    input: NativeStartInput;
+} | {
+    operation: "resume";
+    input: NativeResumeInput;
+} | {
+    operation: "cancel";
+    runId: string;
+    action?: "interrupt" | "rollback";
+    wait?: boolean;
+} | {
+    operation: "run.get";
+    runId: string;
+    offset?: number;
+    digest?: string;
+} | {
+    operation: "state.get";
+    threadId: string;
+    offset?: number;
+    digest?: string;
+} | {
+    operation: "result.get";
+    runId: string;
+    offset?: number;
+    digest?: string;
+} | {
+    operation: "receipt.get";
+    idempotencyKey: string;
+});
+/** Durable receiver deduplication uses eventId, including after BullMQ jobs have been removed. */
+interface BullMqOutcome {
+    version: 1;
+    operation: "run.settled";
+    eventId: string;
+    commandId: string;
+    correlationId?: string;
+    runId: string;
+    threadId: string;
+    status: Run["status"];
+    resultRef: {
+        runId: string;
+    };
+    truncated: boolean;
+    outcome?: unknown;
+}
+/** Byte offsets address a base64 encoded slice of the serialized whole value. */
+interface BullMqChunk {
+    encoding: "base64";
+    digest: string;
+    offset: number;
+    nextOffset: number | null;
+    totalBytes: number;
+    content: string;
+}
+
+/** The adapter publishes outcomes; the host owns every other queue operation and its lifetime. */
+interface OutcomeQueueTarget {
+    readonly name: string;
+    readonly opts: {
+        readonly prefix?: string;
+    };
+    add(name: string, outcome: unknown, options: {
+        jobId: string;
+    }): Promise<unknown>;
+}
+interface BullMqTransportOptions<OutcomeQueue extends OutcomeQueueTarget = Queue> {
+    commandQueue: string;
+    /** Borrowed queue. The adapter never closes it or its connection. */
+    outcomeQueue: OutcomeQueue;
+    /** A borrowed supported ioredis connection or BullMQ connection options. */
+    connection: ConnectionOptions | Redis | Cluster;
+    prefix?: string;
+    concurrency?: number;
+    maxMessageBytes?: number;
+    /** Verify broker credentials/claims here. No authority is accepted from the message itself. */
+    authenticate(job: Job): Promise<Omit<NativeCallOptions, "idempotencyKey" | "idempotencyInput" | "correlationId">>;
+    /** Host-controlled mapping; the original validated command remains its idempotency identity. */
+    route?(command: BullMqCommand): BullMqCommand | Promise<BullMqCommand>;
+    projectResult?(result: RunResult, runId: string): unknown | Promise<unknown>;
+    logger?: {
+        warn(message: string, error?: unknown): void;
+    };
+}
+interface BullMqTransport {
+    /** Bind this stable address to the native source's outcomeTarget. */
+    readonly outcomeTarget: string;
+    wrapDispatcher(inner: WebhookDispatcher): WebhookDispatcher;
+    start(client: NativeClient): Promise<void>;
+    stop(): Promise<void>;
+}
+/** Optional access transport. Skein's own execution and delivery queues remain in charge. */
+declare function createBullMqTransport<OutcomeQueue extends OutcomeQueueTarget>(options: BullMqTransportOptions<OutcomeQueue>): BullMqTransport;
+declare function createBullMqTransport(options: BullMqTransportOptions): BullMqTransport;
+
+export { type BullMqChunk, type BullMqCommand, type BullMqOutcome, type BullMqTransport, type BullMqTransportOptions, createBullMqTransport };

package/dist/index.js

@@ -0,0 +1,253 @@
+// src/bullmq-transport.ts
+import { createHash } from "crypto";
+import {
+  DEFAULT_MAX_PAYLOAD_BYTES
+} from "@skein-js/agent-protocol";
+import {
+  isSkeinHttpError,
+  serializeWireJson,
+  SkeinHttpError
+} from "@skein-js/core";
+import { Worker, UnrecoverableError } from "bullmq";
+import { z } from "zod";
+var key = z.string().min(1).max(255).regex(/^[\x20-\x7e]+$/);
+var chunkFields = {
+  offset: z.number().int().nonnegative().optional(),
+  digest: z.string().regex(/^[a-f0-9]{64}$/).optional()
+};
+var base = {
+  version: z.literal(1),
+  commandId: key,
+  correlationId: z.string().max(255).optional()
+};
+var commandSchema = z.discriminatedUnion("operation", [
+  z.object({ ...base, operation: z.literal("start"), input: z.record(z.unknown()) }).strict(),
+  z.object({ ...base, operation: z.literal("resume"), input: z.record(z.unknown()) }).strict(),
+  z.object({
+    ...base,
+    operation: z.literal("cancel"),
+    runId: z.string().min(1),
+    action: z.enum(["interrupt", "rollback"]).optional(),
+    wait: z.boolean().optional()
+  }).strict(),
+  z.object({ ...base, operation: z.literal("run.get"), runId: z.string().min(1), ...chunkFields }).strict(),
+  z.object({
+    ...base,
+    operation: z.literal("state.get"),
+    threadId: z.string().min(1),
+    ...chunkFields
+  }).strict(),
+  z.object({
+    ...base,
+    operation: z.literal("result.get"),
+    runId: z.string().min(1),
+    ...chunkFields
+  }).strict(),
+  z.object({ ...base, operation: z.literal("receipt.get"), idempotencyKey: key }).strict()
+]);
+function parseCommand(input, cap) {
+  if (Buffer.byteLength(serializeWireJson(input)) > cap)
+    throw SkeinHttpError.unprocessable("Broker command exceeds the message limit.", {
+      code: "message_too_large"
+    });
+  const parsed = commandSchema.safeParse(input);
+  if (!parsed.success)
+    throw SkeinHttpError.badRequest("Invalid BullMQ command.", {
+      code: "invalid_bullmq_command",
+      details: parsed.error.issues
+    });
+  return parsed.data;
+}
+function chunk(value, request, cap) {
+  const bytes = Buffer.from(serializeWireJson(value));
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (request.digest && request.digest !== digest)
+    throw SkeinHttpError.conflict("The requested value changed; restart retrieval.", {
+      code: "result_digest_mismatch"
+    });
+  const offset = request.offset ?? 0;
+  if (offset > 0 && !request.digest)
+    throw SkeinHttpError.badRequest("Continuation requires its digest.", {
+      code: "result_digest_required"
+    });
+  if (offset > bytes.length)
+    throw SkeinHttpError.badRequest("Chunk offset is outside the result.", {
+      code: "invalid_chunk_offset"
+    });
+  const end = Math.min(bytes.length, offset + Math.floor((cap - 512) * 3 / 4));
+  const result = {
+    encoding: "base64",
+    digest,
+    offset,
+    nextOffset: end < bytes.length ? end : null,
+    totalBytes: bytes.length,
+    content: bytes.subarray(offset, end).toString("base64")
+  };
+  if (Buffer.byteLength(serializeWireJson(result)) > cap)
+    throw new Error("BullMQ chunk framing exceeded its bound.");
+  return result;
+}
+var transientCodes = /* @__PURE__ */ new Set([
+  "native_state_changed",
+  "execution_lease_lost",
+  "thread_busy",
+  "thread_status_mismatch",
+  "idempotency_key_in_flight",
+  "run_result_pending"
+]);
+function classify(error) {
+  if (isSkeinHttpError(error) && !transientCodes.has(error.code ?? "") && (error.status < 500 || error.status === 501))
+    throw new UnrecoverableError(
+      JSON.stringify({
+        code: error.code ?? "command_rejected",
+        message: error.message,
+        status: error.status
+      })
+    );
+  throw error;
+}
+function createBullMqTransport(options) {
+  const cap = options.maxMessageBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
+  if (!Number.isSafeInteger(cap) || cap < 1024 || cap > DEFAULT_MAX_PAYLOAD_BYTES)
+    throw new Error("maxMessageBytes must be between 1024 and the existing payload limit.");
+  if (!options.commandQueue) throw new Error("commandQueue is required.");
+  const logger = options.logger ?? console;
+  const outcomeTarget = `skein-bullmq://outcomes/${encodeURIComponent(options.outcomeQueue.opts.prefix ?? "bull")}/${encodeURIComponent(options.outcomeQueue.name)}`;
+  let worker;
+  let starting;
+  let stopping;
+  let running;
+  const processCommand = async (client, job) => {
+    try {
+      const original = parseCommand(job.data, cap);
+      const { correlationId: _diagnostic, ...meaning } = JSON.parse(
+        serializeWireJson(original)
+      );
+      const authenticated = await options.authenticate(job);
+      const command = options.route ? parseCommand(await options.route(structuredClone(original)), cap) : original;
+      const call = {
+        ...authenticated,
+        idempotencyKey: original.commandId,
+        idempotencyInput: meaning,
+        ...original.correlationId ? { correlationId: original.correlationId } : {}
+      };
+      switch (command.operation) {
+        case "start":
+          return await client.start(command.input, call);
+        case "resume":
+          return await client.resume(command.input, call);
+        case "cancel":
+          return await client.cancel(command.runId, {
+            ...call,
+            action: command.action,
+            wait: command.wait
+          });
+        case "run.get": {
+          const run = await client.getRun(command.runId, call);
+          return chunk(run, command, cap);
+        }
+        case "receipt.get":
+          return await client.getReceipt(command.idempotencyKey, call);
+        case "state.get":
+          return chunk(await client.getState(command.threadId, call), command, cap);
+        case "result.get": {
+          const result = await client.getResult(command.runId, call);
+          return chunk(
+            options.projectResult ? await options.projectResult(result, command.runId) : result,
+            command,
+            cap
+          );
+        }
+      }
+    } catch (error) {
+      classify(error);
+    }
+  };
+  return {
+    outcomeTarget,
+    wrapDispatcher: (inner) => async (url, payload, attempt) => {
+      if (url !== outcomeTarget) return inner(url, payload, attempt);
+      if (!attempt?.deliveryId)
+        throw new Error("BullMQ outcomes require an outbox delivery identity.");
+      const body = payload;
+      if (typeof body["run_id"] !== "string" || typeof body["thread_id"] !== "string" || typeof body["command_id"] !== "string")
+        throw new Error("Invalid native outcome.");
+      const event = {
+        version: 1,
+        operation: "run.settled",
+        eventId: attempt.deliveryId,
+        commandId: body["command_id"],
+        ...typeof body["correlation_id"] === "string" ? { correlationId: body["correlation_id"] } : {},
+        runId: body["run_id"],
+        threadId: body["thread_id"],
+        status: body["status"],
+        resultRef: { runId: body["run_id"] },
+        truncated: body["payload_truncated"] === true,
+        outcome: options.projectResult ? body["payload_truncated"] === true || body["result_unavailable"] === true ? void 0 : await options.projectResult(
+          {
+            values: body["values"],
+            ...body["interrupts"] ? { interrupts: body["interrupts"] } : {},
+            ...body["reply"] !== void 0 ? { reply: body["reply"] } : {}
+          },
+          body["run_id"]
+        ) : payload
+      };
+      if (Buffer.byteLength(serializeWireJson(event)) > cap) {
+        delete event.outcome;
+        event.truncated = true;
+      }
+      if (Buffer.byteLength(serializeWireJson(event)) > cap)
+        throw new Error("BullMQ outcome identity exceeds the message bound.");
+      await options.outcomeQueue.add("skein.run.settled.v1", event, { jobId: event.eventId });
+    },
+    start: async (client) => {
+      if (stopping) await stopping;
+      if (starting) return starting;
+      if (worker) return;
+      starting = (async () => {
+        const owned = new Worker(options.commandQueue, (job) => processCommand(client, job), {
+          // BullMQ 5's type names its own ioredis 5 connector class. Keep borrowed client support
+          // across the tested ioredis majors without requiring casts at the application's boundary.
+          connection: options.connection,
+          ...options.prefix ? { prefix: options.prefix } : {},
+          concurrency: options.concurrency ?? 1,
+          autorun: false
+        });
+        worker = owned;
+        owned.on("error", (error) => logger.warn("BullMQ command worker error", error));
+        try {
+          await owned.waitUntilReady();
+          running = owned.run().catch((error) => logger.warn("BullMQ command worker stopped", error));
+        } catch (error) {
+          worker = void 0;
+          await owned.close();
+          throw error;
+        }
+      })();
+      try {
+        await starting;
+      } finally {
+        starting = void 0;
+      }
+    },
+    stop: async () => {
+      if (stopping) return stopping;
+      stopping = (async () => {
+        await starting;
+        const owned = worker;
+        worker = void 0;
+        await owned?.close();
+        await running;
+        running = void 0;
+      })();
+      try {
+        await stopping;
+      } finally {
+        stopping = void 0;
+      }
+    }
+  };
+}
+export {
+  createBullMqTransport
+};

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@skein-js/bullmq",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.23.0",
+  "description": "Optional BullMQ command and outcome transport for Skein agents.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/skein-js/skein-js/tree/main/packages/bullmq#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skein-js/skein-js.git",
+    "directory": "packages/bullmq"
+  },
+  "bugs": {
+    "url": "https://github.com/skein-js/skein-js/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "bullmq": "^5.0.0 || ^6.0.0",
+    "zod": "^3.25.76",
+    "ioredis": "^5.4.0 || ^6.0.0",
+    "@skein-js/agent-protocol": "0.23.0",
+    "@skein-js/core": "0.23.0"
+  },
+  "devDependencies": {
+    "@skein-js/test-support": "0.23.0",
+    "@skein-js/storage-memory": "0.23.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }