@codemation/eventbus-redis 0.0.1

package/README.md

@@ -0,0 +1,84 @@
+# `@codemation/eventbus-redis`
+
+**Redis-backed run event bus** implementation for Codemation, bridging engine events to infrastructure using **ioredis**. It implements host/runtime expectations for publishing and subscribing to run lifecycle traffic.
+
+## At a glance
+
+**End-to-end (why Redis):** run lifecycle signals must cross processes (API process vs worker, or multiple hosts). The engine publishes **`RunEvent`**; this package serializes them to Redis so every subscriber sees the same stream.
+
+```
+  Run starts
+  ──────────
+  · User clicks Run / HTTP command  ─┐
+  · Webhook / trigger / schedule     ├──►  @codemation/host  ──►  Engine  ──►  RunEvent
+                                       │         (StartWorkflowRun, etc.)      │  (publish)
+                                       │                                      │
+                                       │         ┌────────────────────────────┘
+                                       │         ▼
+                                       │   ┌──────────────────┐
+                                       │   │ eventbus-redis   │  Redis PUBLISH to:
+                                       └──►│ RedisRunEventBus │  · codemation.run-events.all
+                                           │ (this package)   │  · codemation.run-events.workflow.<id>
+                                           └────────┬─────────┘
+                                                    │
+                    any process with a subscriber   │ SUBSCRIBE (same channels)
+                                                    ▼
+                                           ┌──────────────────┐
+                                           │ @codemation/host │
+                                           │ WorkflowRunEvent │
+                                           │ WebsocketRelay   │──► workflow WebSocket room
+                                           └────────┬─────────┘      (clients subscribed by
+                                                    │               workflowId)
+                                                    ▼
+                                           Browser / live UI updates
+                                           (nodeQueued, nodeStarted, …)
+```
+
+**Compact view**
+
+```
+  Engine (main or worker)     Redis pub/sub              @codemation/host
+  ┌────────────────────┐     ┌──────────────┐          ┌────────────────────────┐
+  │ RunEvent publishers│────►│ RedisRunEvent│◄────────│ WorkflowRunEvent     │
+  │ (engine + run store)│ pub │ Bus channels │ sub     │ WebsocketRelay → room  │
+  └────────────────────┘     └──────────────┘          └────────────────────────┘
+```
+
+Workers and the HTTP server can live on different machines; all subscribe to the same Redis channels. **In-memory** `RunEventBus` only works inside one process.
+
+## Typical events on this bus
+
+These mirror `@codemation/core` **`RunEvent`** kinds (serialized over Redis):
+
+| Kind            | Meaning (high level)                    |
+| --------------- | --------------------------------------- |
+| `runCreated`    | A workflow run was started (or resumed) |
+| `runSaved`      | Persisted run state was written         |
+| `nodeQueued`    | A node is scheduled / entered the queue |
+| `nodeStarted`   | Execution of a node began               |
+| `nodeCompleted` | A node finished successfully            |
+| `nodeFailed`    | A node failed with an error snapshot    |
+
+Use **in-memory** bus for single-process dev; switch to **Redis** when multiple processes or machines must observe the same run lifecycle.
+
+## Install
+
+```bash
+pnpm add @codemation/eventbus-redis@^0.0.0
+# or
+npm install @codemation/eventbus-redis@^0.0.0
+```
+
+Requires a reachable Redis deployment compatible with your host configuration.
+
+## When to use
+
+Wire this package when you run Codemation in multi-process or scaled setups and want run events (progress, completion, errors) to flow through Redis instead of an in-memory bus.
+
+## Usage
+
+```ts
+import { RedisRunEventBus } from "@codemation/eventbus-redis";
+```
+
+Register the implementation through your host DI/bootstrap where `EventBus`-style services are bound (exact wiring depends on your `CodemationApplication` configuration).

package/dist/chunk-fLflgnQm.js

@@ -0,0 +1,25 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+//#endregion
+export {  };

package/dist/index.d.ts

@@ -0,0 +1,308 @@
+import IORedis from "ioredis";
+
+//#region ../core/src/contracts/runTypes.d.ts
+interface RunExecutionOptions {
+  /** Run-intent override: force the inline scheduler and bypass node-level offload decisions. */
+  localOnly?: boolean;
+  /** Marks runs started from webhook handling so orchestration can apply webhook-specific continuation rules. */
+  webhook?: boolean;
+  mode?: "manual" | "debug";
+  sourceWorkflowId?: WorkflowId;
+  sourceRunId?: RunId;
+  derivedFromRunId?: RunId;
+  isMutable?: boolean;
+  /** Set by the engine for this run: 0 = root, 1 = first child subworkflow, … */
+  subworkflowDepth?: number;
+  /** Effective cap after engine policy merge (successful node completions per run). */
+  maxNodeActivations?: number;
+  /** Effective cap after engine policy merge (subworkflow nesting). */
+  maxSubworkflowDepth?: number;
+}
+/** Engine-owned counters persisted with the run (worker-safe). */
+interface EngineRunCounters {
+  completedNodeActivations: number;
+}
+type RunStopCondition = Readonly<{
+  kind: "workflowCompleted";
+}> | Readonly<{
+  kind: "nodeCompleted";
+  nodeId: NodeId;
+}>;
+interface PersistedRunControlState {
+  stopCondition?: RunStopCondition;
+}
+interface PersistedWorkflowSnapshotNode {
+  id: NodeId;
+  kind: NodeKind;
+  name?: string;
+  nodeTokenId: PersistedTokenId;
+  configTokenId: PersistedTokenId;
+  tokenName?: string;
+  configTokenName?: string;
+  config: unknown;
+}
+interface PersistedWorkflowSnapshot {
+  id: WorkflowId;
+  name: string;
+  nodes: ReadonlyArray<PersistedWorkflowSnapshotNode>;
+  edges: ReadonlyArray<Edge>;
+  /** When the snapshot was built from a live workflow definition that configured a workflow error handler. */
+  workflowErrorHandlerConfigured?: boolean;
+  /** Connection metadata for child nodes not in the execution graph (e.g. AI agent attachments). */
+  connections?: ReadonlyArray<WorkflowNodeConnection>;
+}
+type PinnedNodeOutputsByPort = Readonly<Record<OutputPortKey, Items>>;
+interface PersistedMutableNodeState {
+  pinnedOutputsByPort?: PinnedNodeOutputsByPort;
+  lastDebugInput?: Items;
+}
+interface PersistedMutableRunState {
+  nodesById: Readonly<Record<NodeId, PersistedMutableNodeState>>;
+}
+type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
+interface RunQueueEntry {
+  nodeId: NodeId;
+  input: Items;
+  toInput?: InputPortKey;
+  batchId?: string;
+  from?: Readonly<{
+    nodeId: NodeId;
+    output: OutputPortKey;
+  }>;
+  collect?: Readonly<{
+    expectedInputs: ReadonlyArray<InputPortKey>;
+    received: Readonly<Record<InputPortKey, Items>>;
+  }>;
+}
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+interface NodeExecutionError {
+  message: string;
+  name?: string;
+  stack?: string;
+}
+interface NodeExecutionSnapshot {
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId?: NodeActivationId;
+  parent?: ParentExecutionRef;
+  status: NodeExecutionStatus;
+  usedPinnedOutput?: boolean;
+  queuedAt?: string;
+  startedAt?: string;
+  finishedAt?: string;
+  updatedAt: string;
+  inputsByPort?: NodeInputsByPort;
+  outputs?: NodeOutputs;
+  error?: NodeExecutionError;
+}
+/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
+type ConnectionInvocationId = string;
+/**
+ * One logical LLM or tool call under an owning workflow node (e.g. AI agent).
+ * The owning node defines what {@link managedInput} and {@link managedOutput} contain.
+ */
+interface ConnectionInvocationRecord {
+  readonly invocationId: ConnectionInvocationId;
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly connectionNodeId: NodeId;
+  readonly parentAgentNodeId: NodeId;
+  readonly parentAgentActivationId: NodeActivationId;
+  readonly status: NodeExecutionStatus;
+  readonly managedInput?: JsonValue;
+  readonly managedOutput?: JsonValue;
+  readonly error?: NodeExecutionError;
+  readonly queuedAt?: string;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly updatedAt: string;
+}
+type RunStatus = "running" | "pending" | "completed" | "failed";
+interface PendingNodeExecution {
+  runId: RunId;
+  activationId: NodeActivationId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  itemsIn: number;
+  inputsByPort: NodeInputsByPort;
+  receiptId: string;
+  queue?: string;
+  batchId?: string;
+  enqueuedAt: string;
+}
+interface PersistedRunState {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  parent?: ParentExecutionRef;
+  executionOptions?: RunExecutionOptions;
+  control?: PersistedRunControlState;
+  workflowSnapshot?: PersistedWorkflowSnapshot;
+  mutableState?: PersistedMutableRunState;
+  /** Frozen at createRun from workflow + runtime defaults for prune/storage decisions. */
+  policySnapshot?: PersistedRunPolicySnapshot;
+  /** Successful node completions so far (for activation budget). */
+  engineCounters?: EngineRunCounters;
+  status: RunStatus;
+  pending?: PendingNodeExecution;
+  queue: RunQueueEntry[];
+  outputsByNode: Record<NodeId, NodeOutputs>;
+  nodeSnapshotsByNodeId: Record<NodeId, NodeExecutionSnapshot>;
+  /** Append-only history of connection invocations (LLM/tool) nested under owning nodes. */
+  connectionInvocations?: ReadonlyArray<ConnectionInvocationRecord>;
+}
+//#endregion
+//#region ../core/src/contracts/workflowTypes.d.ts
+type WorkflowId = string;
+type NodeId = string;
+type OutputPortKey = string;
+type InputPortKey = string;
+type PersistedTokenId = string;
+type NodeKind = "trigger" | "node";
+type JsonPrimitive = string | number | boolean | null;
+interface JsonObject {
+  readonly [key: string]: JsonValue;
+}
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+type JsonArray = ReadonlyArray<JsonValue>;
+interface Edge {
+  from: {
+    nodeId: NodeId;
+    output: OutputPortKey;
+  };
+  to: {
+    nodeId: NodeId;
+    input: InputPortKey;
+  };
+}
+type NodeConnectionName = string;
+/**
+ * Named connection from an executable parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
+ * but are not traversed by the main execution graph.
+ */
+interface WorkflowNodeConnection {
+  readonly parentNodeId: NodeId;
+  readonly connectionName: NodeConnectionName;
+  readonly childNodeIds: ReadonlyArray<NodeId>;
+}
+type PairedItemRef = Readonly<{
+  nodeId: NodeId;
+  output: OutputPortKey;
+  itemIndex: number;
+}>;
+type BinaryPreviewKind = "image" | "audio" | "video" | "download";
+type BinaryAttachment = Readonly<{
+  id: string;
+  storageKey: string;
+  mimeType: string;
+  size: number;
+  storageDriver: string;
+  previewKind: BinaryPreviewKind;
+  createdAt: string;
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  filename?: string;
+  sha256?: string;
+}>;
+type ItemBinary = Readonly<Record<string, BinaryAttachment>>;
+type Item<TJson = unknown> = Readonly<{
+  json: TJson;
+  binary?: ItemBinary;
+  meta?: Readonly<Record<string, unknown>>;
+  paired?: ReadonlyArray<PairedItemRef>;
+}>;
+type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
+type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
+type RunId = string;
+type NodeActivationId = string;
+interface ParentExecutionRef {
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  /** Subworkflow depth of the **spawning** run (0 = root). Passed when starting a child run. */
+  subworkflowDepth?: number;
+  /** Effective max node activations from the parent run (propagated to child policy merge). */
+  engineMaxNodeActivations?: number;
+  /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
+  engineMaxSubworkflowDepth?: number;
+}
+/** Whether to persist run execution data after the workflow finishes. */
+type WorkflowStoragePolicyMode = "ALL" | "SUCCESS" | "ERROR" | "NEVER";
+interface PersistedRunPolicySnapshot {
+  readonly retentionSeconds?: number;
+  readonly binaryRetentionSeconds?: number;
+  readonly storagePolicy: WorkflowStoragePolicyMode;
+}
+//#endregion
+//#region ../core/src/events/runEvents.d.ts
+type RunEvent = Readonly<{
+  kind: "runCreated";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+}> | Readonly<{
+  kind: "runSaved";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+  state: PersistedRunState;
+}> | Readonly<{
+  kind: "nodeQueued";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+  snapshot: NodeExecutionSnapshot;
+}> | Readonly<{
+  kind: "nodeStarted";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+  snapshot: NodeExecutionSnapshot;
+}> | Readonly<{
+  kind: "nodeCompleted";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+  snapshot: NodeExecutionSnapshot;
+}> | Readonly<{
+  kind: "nodeFailed";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+  snapshot: NodeExecutionSnapshot;
+}>;
+interface RunEventSubscription {
+  close(): Promise<void>;
+}
+interface RunEventBus {
+  publish(event: RunEvent): Promise<void>;
+  subscribe(onEvent: (event: RunEvent) => void): Promise<RunEventSubscription>;
+  subscribeToWorkflow(workflowId: WorkflowId, onEvent: (event: RunEvent) => void): Promise<RunEventSubscription>;
+}
+//#endregion
+//#region src/RedisRunEventBusRegistry.d.ts
+declare class RedisRunEventBus implements RunEventBus {
+  private readonly redisUrl;
+  private readonly globalChannel;
+  private publisher;
+  constructor(redisUrl: string, channelPrefix?: string);
+  private readonly channelPrefix;
+  publish(event: RunEvent): Promise<void>;
+  subscribe(onEvent: (event: RunEvent) => void): Promise<RunEventSubscription>;
+  subscribeToWorkflow(workflowId: WorkflowId, onEvent: (event: RunEvent) => void): Promise<RunEventSubscription>;
+  private ensurePublisher;
+  private createSubscription;
+  private getWorkflowChannel;
+  private parseEvent;
+}
+//#endregion
+export { RedisRunEventBus };

package/dist/index.js

@@ -0,0 +1,64 @@
+import IORedis from "ioredis";
+
+//#region src/RedisRunEventSubscription.ts
+var RedisRunEventSubscription = class {
+	constructor(subscriber, channel, handler) {
+		this.subscriber = subscriber;
+		this.channel = channel;
+		this.handler = handler;
+	}
+	async close() {
+		this.subscriber.off("message", this.handler);
+		await this.subscriber.unsubscribe(this.channel);
+		this.subscriber.disconnect();
+	}
+};
+
+//#endregion
+//#region src/RedisRunEventBusRegistry.ts
+var RedisRunEventBus = class {
+	globalChannel;
+	publisher;
+	constructor(redisUrl, channelPrefix = "codemation") {
+		this.redisUrl = redisUrl;
+		this.globalChannel = `${channelPrefix}.run-events.all`;
+		this.channelPrefix = `${channelPrefix}.run-events.workflow`;
+	}
+	channelPrefix;
+	async publish(event) {
+		const pub = this.ensurePublisher();
+		const serialized = JSON.stringify(event);
+		await pub.publish(this.globalChannel, serialized);
+		await pub.publish(this.getWorkflowChannel(event.workflowId), serialized);
+	}
+	async subscribe(onEvent) {
+		return await this.createSubscription(this.globalChannel, onEvent);
+	}
+	async subscribeToWorkflow(workflowId, onEvent) {
+		return await this.createSubscription(this.getWorkflowChannel(workflowId), onEvent);
+	}
+	ensurePublisher() {
+		if (this.publisher) return this.publisher;
+		this.publisher = new IORedis(this.redisUrl);
+		return this.publisher;
+	}
+	async createSubscription(channel, onEvent) {
+		const sub = new IORedis(this.redisUrl);
+		const onMessage = (receivedChannel, message) => {
+			if (receivedChannel !== channel) return;
+			onEvent(this.parseEvent(message));
+		};
+		sub.on("message", onMessage);
+		await sub.subscribe(channel);
+		return new RedisRunEventSubscription(sub, channel, onMessage);
+	}
+	getWorkflowChannel(workflowId) {
+		return `${this.channelPrefix}.${workflowId}`;
+	}
+	parseEvent(raw) {
+		return JSON.parse(raw);
+	}
+};
+
+//#endregion
+export { RedisRunEventBus };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@codemation/eventbus-redis",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Made Relevant B.V.",
+  "homepage": "https://www.maderelevant.com",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": {
+        "import": "./src/index.ts",
+        "require": "./dist/index.cjs"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "ioredis": "^5.7.0",
+    "@codemation/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "eslint": "^10.0.3",
+    "tsdown": "^0.15.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "echo \"(test placeholder)\""
+  }
+}

package/src/RedisRunEventBusRegistry.ts

@@ -0,0 +1,63 @@
+import type { RunEvent, RunEventBus, RunEventSubscription, WorkflowId } from "@codemation/core";
+
+import IORedis from "ioredis";
+
+import { RedisRunEventSubscription } from "./RedisRunEventSubscription";
+
+export class RedisRunEventBus implements RunEventBus {
+  private readonly globalChannel: string;
+  private publisher: IORedis | undefined;
+
+  constructor(
+    private readonly redisUrl: string,
+    channelPrefix = "codemation",
+  ) {
+    this.globalChannel = `${channelPrefix}.run-events.all`;
+    this.channelPrefix = `${channelPrefix}.run-events.workflow`;
+  }
+
+  private readonly channelPrefix: string;
+
+  async publish(event: RunEvent): Promise<void> {
+    const pub = this.ensurePublisher();
+    const serialized = JSON.stringify(event);
+    await pub.publish(this.globalChannel, serialized);
+    await pub.publish(this.getWorkflowChannel(event.workflowId), serialized);
+  }
+
+  async subscribe(onEvent: (event: RunEvent) => void): Promise<RunEventSubscription> {
+    return await this.createSubscription(this.globalChannel, onEvent);
+  }
+
+  async subscribeToWorkflow(workflowId: WorkflowId, onEvent: (event: RunEvent) => void): Promise<RunEventSubscription> {
+    return await this.createSubscription(this.getWorkflowChannel(workflowId), onEvent);
+  }
+
+  private ensurePublisher(): IORedis {
+    if (this.publisher) return this.publisher;
+    this.publisher = new IORedis(this.redisUrl);
+    return this.publisher;
+  }
+
+  private async createSubscription(channel: string, onEvent: (event: RunEvent) => void): Promise<RunEventSubscription> {
+    const sub = new IORedis(this.redisUrl);
+    const onMessage = (receivedChannel: string, message: string) => {
+      if (receivedChannel !== channel) return;
+      onEvent(this.parseEvent(message));
+    };
+
+    sub.on("message", onMessage);
+    await sub.subscribe(channel);
+    return new RedisRunEventSubscription(sub, channel, onMessage);
+  }
+
+  private getWorkflowChannel(workflowId: WorkflowId): string {
+    return `${this.channelPrefix}.${workflowId}`;
+  }
+
+  private parseEvent(raw: string): RunEvent {
+    return JSON.parse(raw) as RunEvent;
+  }
+}
+
+export { RedisRunEventSubscription } from "./RedisRunEventSubscription";

package/src/RedisRunEventSubscription.ts

@@ -0,0 +1,17 @@
+import type { RunEventSubscription } from "@codemation/core";
+
+import IORedis from "ioredis";
+
+export class RedisRunEventSubscription implements RunEventSubscription {
+  constructor(
+    private readonly subscriber: IORedis,
+    private readonly channel: string,
+    private readonly handler: (channel: string, message: string) => void,
+  ) {}
+
+  async close(): Promise<void> {
+    this.subscriber.off("message", this.handler);
+    await this.subscriber.unsubscribe(this.channel);
+    this.subscriber.disconnect();
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { RedisRunEventBus } from "./RedisRunEventBusRegistry";

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}