@codemation/eventbus-redis 0.0.44 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @codemation/eventbus-redis
 
+## 0.1.0
+
+### Minor Changes
+
+- [#281](https://github.com/MadeRelevant/codemation/pull/281) [`b0b1b5e`](https://github.com/MadeRelevant/codemation/commit/b0b1b5e945e93d43230c9e2bfe935ea59f48e10e) Thanks [@cblokland90](https://github.com/cblokland90)! - feat(relay): publish HMAC-signed run events to redis for the control-plane realtime relay ([#318](https://github.com/MadeRelevant/codemation/issues/318))
+
+  In managed mode (a paired workspace running the redis-backed event bus), the host now relays every `RunEvent` to a workspace+workflow-keyed redis channel `codemation.ws.<workspaceId>.run-events.<workflowId>` as an HMAC-signed envelope (`SignedRunEventRelayPublisher`). The signature is keyed by the workspace pairing secret so the control plane can verify authenticity and which workspace published the event. This lets run events escape the originating HTTP request so externally-triggered (loop/webhook) runs can stream live to the canvas. Part of scale-to-zero ([#261](https://github.com/MadeRelevant/codemation/issues/261)); the control-plane subscribe/verify/SSE side and the canvas subscription land separately.
+
+### Patch Changes
+
+- [#247](https://github.com/MadeRelevant/codemation/pull/247) [`bfdd759`](https://github.com/MadeRelevant/codemation/commit/bfdd7590b4903676b223c2f302b9bcd0f4a4583c) Thanks [@cblokland90](https://github.com/cblokland90)! - Remove all human-written comments from TypeScript source files and add `codemation/no-comments` ESLint rule to enforce self-describing code going forward.
+
+- Updated dependencies [[`60f23a3`](https://github.com/MadeRelevant/codemation/commit/60f23a37660cdda34e3d61acca8b2bf581a9db0e), [`a5457bb`](https://github.com/MadeRelevant/codemation/commit/a5457bb58edafec01e85cdcf6d30f9ca54521e27), [`510e0d8`](https://github.com/MadeRelevant/codemation/commit/510e0d8a5f137a4fe10f43cbf46e40d05fea4977), [`d5f49f7`](https://github.com/MadeRelevant/codemation/commit/d5f49f7f80deafc109dbc29f16ff0d571ee8591a), [`364507a`](https://github.com/MadeRelevant/codemation/commit/364507a9fba45fd66cb208d5a41ee1f3bdc68311), [`0dc8a9d`](https://github.com/MadeRelevant/codemation/commit/0dc8a9def376e4cd1821f3b92b0f887720e0c842), [`3facadf`](https://github.com/MadeRelevant/codemation/commit/3facadf3bc09d21f33e698213a521fb64168d5dd), [`c08cf33`](https://github.com/MadeRelevant/codemation/commit/c08cf33ead44fec64d3d43b9294fccfdf6674156), [`597fa8f`](https://github.com/MadeRelevant/codemation/commit/597fa8f697300d8d861a02c11e9819892f7947fa), [`b15f8c6`](https://github.com/MadeRelevant/codemation/commit/b15f8c68125e3ec3082bab8d79414871f942e409), [`bfdd759`](https://github.com/MadeRelevant/codemation/commit/bfdd7590b4903676b223c2f302b9bcd0f4a4583c), [`0a681b3`](https://github.com/MadeRelevant/codemation/commit/0a681b357afd7b15ba3925788c732fd439d8e6b0), [`ab5185a`](https://github.com/MadeRelevant/codemation/commit/ab5185a839118868eda1aab42b82f7a921037f37), [`fd188a2`](https://github.com/MadeRelevant/codemation/commit/fd188a2bac65c86dd62cf2f540034769c5bc0ac7), [`f2aa0c4`](https://github.com/MadeRelevant/codemation/commit/f2aa0c42b2f9d2e9eb7bc4f3393f74342f7ef460), [`cf2b146`](https://github.com/MadeRelevant/codemation/commit/cf2b146b452317e1ccaa1dfeaaa1a0e153181e30)]:
+  - @codemation/core@0.15.0
+
 ## 0.0.44
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,19 +1,9 @@
 import IORedis from "ioredis";
 
 //#region ../core/src/contracts/testTriggerTypes.d.ts
-
-/**
- * Identifier minted by the host (or in-memory test runner) for one execution of a test suite.
- * One TestSuiteRun produces N child workflow runs, one per item yielded by `generateItems`.
- */
 type TestSuiteRunId = string;
 //#endregion
 //#region ../core/src/contracts/baseTypes.d.ts
-/**
- * Minimal base types that have no dependencies on other contracts.
- * Used by credentialTypes, workflowTypes, and other contract layers
- * to avoid circular dependencies.
- */
 type WorkflowId = string;
 type NodeId = string;
 type OutputPortKey = string;
@@ -22,15 +12,7 @@ type PersistedTokenId = string;
 type NodeConnectionName = string;
 //#endregion
 //#region ../core/src/events/runEvents.d.ts
-/**
- * Outcome of a single test case (one workflow run dispatched by the test-suite orchestrator).
- * - `running`: workflow still in flight
- * - `succeeded`: workflow completed AND all assertions passed (or no assertions)
- * - `failed`: workflow failed OR (workflow completed but ≥1 assertion failed)
- * - `errored` / `cancelled`: workflow itself errored or was cancelled
- */
 type TestCaseRunStatus = "running" | "succeeded" | "failed" | "errored" | "cancelled";
-/** Aggregate outcome of a TestSuiteRun. */
 type TestSuiteRunStatus = "succeeded" | "failed" | "partial" | "errored" | "cancelled";
 type RunEvent = Readonly<{
   kind: "runCreated";
@@ -138,42 +120,24 @@ interface RunEventBus {
 }
 //#endregion
 //#region ../core/src/contracts/runTypes.d.ts
-/**
- * Test-suite linkage for a run. When set, this run was started by a TestSuiteOrchestrator
- * as one test case inside a TestSuiteRun. The `IsTestRun` node and host-side persisters key
- * off the presence of this field. Subworkflow runs inherit it from their parent run.
- */
 interface RunTestContext {
   readonly testSuiteRunId: string;
   readonly testCaseIndex: number;
-  /**
-   * Optional human-friendly label for this test case (e.g. an email subject when fixtures
-   * are loaded from a mailbox). Resolved per item by `TestTrigger.caseLabel(item)` if set,
-   * persisted on `Run.test_case_label` so the Tests-tab tree-table can show "RFQ for batch 14"
-   * instead of "run_1777755971399_bbb86beac1396".
-   */
   readonly testCaseLabel?: string;
 }
 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;
-  /** Present iff started by a TestSuiteOrchestrator; propagates to subworkflow runs via {@link ParentExecutionRef.testContext}. */
   testContext?: RunTestContext;
 }
-/** Engine-owned counters persisted with the run (worker-safe). */
 interface EngineRunCounters {
   completedNodeActivations: number;
 }
@@ -195,7 +159,6 @@ interface PersistedWorkflowSnapshotNode {
   tokenName?: string;
   configTokenName?: string;
   config: unknown;
-  /** Pre-computed static configuration summary; populated by WorkflowSnapshotCodec. */
   inspectorSummary?: ReadonlyArray<Readonly<{
     label: string;
     value: string;
@@ -206,9 +169,7 @@ interface PersistedWorkflowSnapshot {
   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>>;
@@ -256,18 +217,9 @@ interface NodeExecutionSnapshot {
   inputsByPort?: NodeInputsByPort;
   outputs?: NodeOutputs;
   error?: NodeExecutionError;
-  /**
-   * When the node is a SubWorkflow invocation, the run id of the child run it spawned.
-   * Populated after the child run completes so the UI can deep-link to that specific execution.
-   */
   childRunId?: RunId;
 }
-/** 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;
@@ -278,24 +230,18 @@ interface ConnectionInvocationRecord {
   readonly status: NodeExecutionStatus;
   readonly managedInput?: JsonValue;
   readonly managedOutput?: JsonValue;
-  /** Short human-readable description of what this invocation is doing right now (e.g. `"calling search_messages"`). Rendered as a sub-line on the canvas node card. */
   readonly statusLabel?: string;
-  /** Stable identifier for the thing this invocation acts on (e.g. an MCP tool name like `"search_messages"`). Persists across status transitions so the inspector can show it on completed/failed entries too. Connection nodes that ARE the tool (e.g. node-backed agent tools) leave this unset — the parent node id already identifies the subject. */
   readonly subjectName?: string;
   readonly error?: NodeExecutionError;
   readonly queuedAt?: string;
   readonly startedAt?: string;
   readonly finishedAt?: string;
   readonly updatedAt: string;
-  /** Per-item iteration id minted by the engine when this invocation occurred inside a runnable node's per-item loop. */
   readonly iterationId?: NodeIterationId;
-  /** Item index (0-based) of the iteration that produced this invocation. */
   readonly itemIndex?: number;
-  /** When set, this invocation was produced inside a sub-agent triggered by the named parent invocation. */
   readonly parentInvocationId?: ConnectionInvocationId;
 }
 type RunStatus = "running" | "pending" | "completed" | "failed" | "suspended" | "halted";
-/** Reason a run transitioned to {@link RunStatus} `"halted"`. */
 type RunHaltReason = "hitl-rejected" | "hitl-timeout" | "hitl-cancelled";
 interface PendingNodeExecution {
   runId: RunId;
@@ -309,70 +255,42 @@ interface PendingNodeExecution {
   batchId?: string;
   enqueuedAt: string;
 }
-/** One persisted suspension entry per suspended item. */
 interface PersistedSuspensionEntry {
-  /** Opaque task identifier (UUID v4). */
   readonly taskId: string;
   readonly nodeId: NodeId;
   readonly activationId: NodeActivationId;
   readonly itemIndex: number;
-  /** SHA-256 hex digest of the decision schema JSON (for schema-drift detection). */
   readonly decisionSchemaHash: string;
-  /** Serialized return value from `SuspensionRequest.deliver` (stored on the HumanTask row). */
   readonly deliveryRef: JsonValue;
-  /** ISO timestamp when the task expires. */
   readonly timeoutAt: string;
   readonly onTimeout: "halt" | "auto-accept";
 }
-/**
- * When a node is re-activated after suspension, the engine writes the resume context here
- * so `NodeExecutionRequestHandlerService` can splice `resumeContext` into ctx.
- * Cleared once the re-activation is consumed.
- */
 interface PendingResumeEntry {
   readonly activationId: NodeActivationId;
   readonly nodeId: NodeId;
-  /**
-   * Typed as `unknown` here to avoid a circular import between runTypes ↔ runtimeTypes.
-   * `NodeExecutionRequestHandlerService` casts this to `ResumeContext` from runtimeTypes.
-   */
   readonly resumeContext: unknown;
 }
 interface PersistedRunState {
   runId: RunId;
   workflowId: WorkflowId;
   startedAt: string;
-  /** Canonical terminal time for listings and retention when persisted on the run root. */
   finishedAt?: string;
-  /** Optimistic concurrency / CAS on the run aggregate (repository may increment on save). */
   revision?: number;
   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;
-  /** Populated when `status === "halted"` to discriminate why the run was halted. */
   reason?: RunHaltReason;
   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>;
-  /**
-   * One entry per outstanding HITL suspension (per-item).
-   * Present and non-empty iff `status === "suspended"`.
-   */
   suspension?: ReadonlyArray<PersistedSuspensionEntry>;
-  /**
-   * Written by `resumeRun()` so `NodeExecutionRequestHandlerService` can splice `resumeContext`
-   * into the ctx when re-executing the suspended node. Cleared once consumed.
-   */
   pendingResume?: PendingResumeEntry;
 }
 //#endregion
@@ -394,11 +312,6 @@ interface Edge {
     input: InputPortKey;
   };
 }
-/**
- * Named connection from a parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
- * but are not traversed by the main execution graph. Parents are commonly executable nodes, but may
- * also be connection-owned nodes for recursive agent attachments.
- */
 interface WorkflowNodeConnection {
   readonly parentNodeId: NodeId;
   readonly connectionName: NodeConnectionName;
@@ -436,30 +349,16 @@ type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
 type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 type RunId = string;
 type NodeActivationId = string;
-/**
- * One per-item iteration of a runnable node's execute loop. Refines `NodeActivationId` for
- * per-item connection invocations and telemetry. Undefined when the executing node is a batch
- * node or trigger that does not iterate items.
- */
 type NodeIterationId = 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;
-  /**
-   * Test-suite linkage inherited by the child subworkflow run. Set by whichever node
-   * spawns the subworkflow when its own `ctx.testContext` is present, so assertions
-   * emitted inside a subworkflow land under the correct parent test case.
-   */
   testContext?: RunTestContext;
 }
-/** Whether to persist run execution data after the workflow finishes. */
 type WorkflowStoragePolicyMode = "ALL" | "SUCCESS" | "ERROR" | "NEVER";
 interface PersistedRunPolicySnapshot {
   readonly retentionSeconds?: number;
@@ -486,4 +385,32 @@ declare class RedisRunEventBus implements RunEventBus {
   private parseEvent;
 }
 //#endregion
-export { RedisRunEventBus };
+//#region src/signedRelay.types.d.ts
+declare const SIGNED_RUN_EVENT_CHANNEL_PREFIX = "codemation";
+interface SignedRunEventEnvelope {
+  readonly workspaceId: string;
+  readonly ts: number;
+  readonly sig: string;
+  readonly payload: string;
+}
+interface RunEventEnvelopeSigner {
+  readonly workspaceId: string;
+  sign(payload: string): SignedRunEventEnvelope;
+}
+declare function signedRunEventChannel(channelPrefix: string, workspaceId: string, workflowId: string): string;
+//#endregion
+//#region src/SignedRunEventRelayPublisher.d.ts
+declare class SignedRunEventRelayPublisher {
+  private readonly redisUrl;
+  private readonly localBus;
+  private readonly signer;
+  private publisher;
+  private subscription;
+  constructor(redisUrl: string, localBus: RunEventBus, signer: RunEventEnvelopeSigner);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  private relay;
+  private ensurePublisher;
+}
+//#endregion
+export { RedisRunEventBus, type RunEventEnvelopeSigner, SIGNED_RUN_EVENT_CHANNEL_PREFIX, type SignedRunEventEnvelope, SignedRunEventRelayPublisher, signedRunEventChannel };

package/dist/index.js

@@ -61,4 +61,50 @@ var RedisRunEventBus = class {
 };
 
 //#endregion
-export { RedisRunEventBus };
+//#region src/signedRelay.types.ts
+const SIGNED_RUN_EVENT_CHANNEL_PREFIX = "codemation";
+function signedRunEventChannel(channelPrefix, workspaceId, workflowId) {
+	return `${channelPrefix}.ws.${workspaceId}.run-events.${workflowId}`;
+}
+
+//#endregion
+//#region src/SignedRunEventRelayPublisher.ts
+var SignedRunEventRelayPublisher = class {
+	publisher;
+	subscription;
+	constructor(redisUrl, localBus, signer) {
+		this.redisUrl = redisUrl;
+		this.localBus = localBus;
+		this.signer = signer;
+	}
+	async start() {
+		if (this.subscription) return;
+		this.subscription = await this.localBus.subscribe((event) => {
+			this.relay(event);
+		});
+	}
+	async stop() {
+		if (this.subscription) {
+			await this.subscription.close();
+			this.subscription = void 0;
+		}
+		if (this.publisher) {
+			this.publisher.disconnect();
+			this.publisher = void 0;
+		}
+	}
+	async relay(event) {
+		const payload = JSON.stringify(event);
+		const envelope = this.signer.sign(payload);
+		const channel = signedRunEventChannel(SIGNED_RUN_EVENT_CHANNEL_PREFIX, this.signer.workspaceId, event.workflowId);
+		await this.ensurePublisher().publish(channel, JSON.stringify(envelope));
+	}
+	ensurePublisher() {
+		if (this.publisher) return this.publisher;
+		this.publisher = new IORedis(this.redisUrl);
+		return this.publisher;
+	}
+};
+
+//#endregion
+export { RedisRunEventBus, SIGNED_RUN_EVENT_CHANNEL_PREFIX, SignedRunEventRelayPublisher, signedRunEventChannel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/eventbus-redis",
-  "version": "0.0.44",
+  "version": "0.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "ioredis": "^5.7.0",
-    "@codemation/core": "0.14.0"
+    "@codemation/core": "0.15.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",

package/src/SignedRunEventRelayPublisher.ts

@@ -0,0 +1,49 @@
+import type { RunEvent, RunEventBus, RunEventSubscription } from "@codemation/core";
+
+import IORedis from "ioredis";
+
+import type { RunEventEnvelopeSigner } from "./signedRelay.types";
+import { signedRunEventChannel, SIGNED_RUN_EVENT_CHANNEL_PREFIX } from "./signedRelay.types";
+
+export class SignedRunEventRelayPublisher {
+  private publisher: IORedis | undefined;
+  private subscription: RunEventSubscription | undefined;
+
+  constructor(
+    private readonly redisUrl: string,
+    private readonly localBus: RunEventBus,
+    private readonly signer: RunEventEnvelopeSigner,
+  ) {}
+
+  async start(): Promise<void> {
+    if (this.subscription) return;
+    this.subscription = await this.localBus.subscribe((event) => {
+      void this.relay(event);
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (this.subscription) {
+      await this.subscription.close();
+      this.subscription = undefined;
+    }
+    if (this.publisher) {
+      this.publisher.disconnect();
+      this.publisher = undefined;
+    }
+  }
+
+  private async relay(event: RunEvent): Promise<void> {
+    const payload = JSON.stringify(event);
+    const envelope = this.signer.sign(payload);
+    const channel = signedRunEventChannel(SIGNED_RUN_EVENT_CHANNEL_PREFIX, this.signer.workspaceId, event.workflowId);
+    await this.ensurePublisher().publish(channel, JSON.stringify(envelope));
+  }
+
+  private ensurePublisher(): IORedis {
+    if (this.publisher) return this.publisher;
+    // eslint-disable-next-line codemation/no-manual-di-new -- IORedis is an external connection client, not a DI-managed class (same pattern as RedisRunEventBus).
+    this.publisher = new IORedis(this.redisUrl);
+    return this.publisher;
+  }
+}

package/src/index.ts

@@ -1 +1,4 @@
 export { RedisRunEventBus } from "./RedisRunEventBusRegistry";
+export { SignedRunEventRelayPublisher } from "./SignedRunEventRelayPublisher";
+export { signedRunEventChannel, SIGNED_RUN_EVENT_CHANNEL_PREFIX } from "./signedRelay.types";
+export type { RunEventEnvelopeSigner, SignedRunEventEnvelope } from "./signedRelay.types";

package/src/signedRelay.types.ts

@@ -0,0 +1,17 @@
+export const SIGNED_RUN_EVENT_CHANNEL_PREFIX = "codemation";
+
+export interface SignedRunEventEnvelope {
+  readonly workspaceId: string;
+  readonly ts: number;
+  readonly sig: string;
+  readonly payload: string;
+}
+
+export interface RunEventEnvelopeSigner {
+  readonly workspaceId: string;
+  sign(payload: string): SignedRunEventEnvelope;
+}
+
+export function signedRunEventChannel(channelPrefix: string, workspaceId: string, workflowId: string): string {
+  return `${channelPrefix}.ws.${workspaceId}.run-events.${workflowId}`;
+}