@radishbot/sdk 0.4.0 → 0.5.0

package/README.md

@@ -139,6 +139,34 @@ action.info("continuing from service B");
 await action.finish();
 ```
 
+## Run ID
+
+Every `RL()` call auto-generates a **run ID** — a short random string that groups flows across processes. Pass it to subprocesses via env vars, CLI args, or message queues so all flows from one logical execution link together.
+
+```ts
+const root = await RL(key);
+
+// Pass to subprocess
+spawn("worker.ts", { env: { ...process.env, RADISH_RUN_ID: root.runId } });
+
+// In the subprocess — same run ID groups them together
+const worker = await RL(key, { runId: process.env.RADISH_RUN_ID });
+worker.info("processing");
+await worker.finishAndDisconnect();
+```
+
+You can also generate a run ID upfront:
+
+```ts
+import { generateRunId } from "@radishbot/sdk";
+const runId = generateRunId();
+// pass to multiple services
+const a = await RL(key, { runId });
+const b = await RL(key, { runId });
+```
+
+In the dashboard, click a run ID badge to filter all flows from that run.
+
 ## Release Tracking
 
 Tag every flow with a version or commit SHA. Errors are tracked per-release, and regressions (errors reappearing after being resolved) are detected automatically.
@@ -181,6 +209,7 @@ const root = await RL(key, {
   defaultTimeout: 100, // seconds, default 100
   release: "v1.0.0", // version or commit SHA
   retention: "30d", // data retention period
+  runId: "abc123", // optional, auto-generated if omitted
 });
 ```
 
@@ -204,12 +233,16 @@ Actions that exceed their timeout are automatically marked as timed out.
 
 ### `RL(secretKey, options?) → Promise<Flow>`
 
-Connect and create a root action. Options: `host`, `dbName`, `defaultTimeout`, `release`, `retention`.
+Connect and create a root action. Options: `host`, `dbName`, `defaultTimeout`, `release`, `retention`, `runId`.
 
 ### `generateKey() → string`
 
 Generate a random secret key (prefix `rl_`).
 
+### `generateRunId() → string`
+
+Generate a random run ID. Useful when you want to create the ID before calling `RL()`.
+
 ### `restoreFlow(secretKey, handle, options?) → Promise<Flow>`
 
 Restore an action from an exported handle string.
@@ -228,4 +261,5 @@ Restore an action from an exported handle string.
 | `.debug(msg, data?)`       | Log at debug level.                                                |
 | `.log(msg, data?, level?)` | Log at any level.                                                  |
 | `.exportID()`              | Export handle for cross-context restore.                           |
+| `.runId`                   | The run ID (read-only). Pass to subprocesses.                      |
 | `.getId()`                 | Get server-assigned action ID.                                     |

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export type LogLevel = "info" | "warn" | "error" | "debug";
 
 export declare class Flow {
+  readonly runId: string;
   log(message: string, data?: unknown, level?: LogLevel): this;
   info(message: string, data?: unknown): this;
   warn(message: string, data?: unknown): this;
@@ -24,8 +25,10 @@ export interface RLOptions {
   defaultTimeout?: number;
   release?: string;
   retention?: string;
+  runId?: string;
 }
 
 export declare function RL(secretKey: string, options?: RLOptions): Promise<Flow>;
 export declare function restoreFlow(secretKey: string, exportedId: string, options?: RLOptions): Promise<Flow>;
 export declare function generateKey(): string;
+export declare function generateRunId(): string;

package/dist/index.js

@@ -48,6 +48,7 @@ import {
 } from "spacetimedb";
 var create_root_flow_reducer_default = {
   keyHash: __t4.string(),
+  runId: __t4.string(),
   timeoutSeconds: __t4.u64(),
   exportToken: __t4.string(),
   release: __t4.string()
@@ -165,6 +166,7 @@ import {
 var flow_table_default = __t14.row({
   id: __t14.u64().primaryKey(),
   keyHash: __t14.string().name("key_hash"),
+  runId: __t14.string().name("run_id"),
   parentFlowId: __t14.u64().name("parent_flow_id"),
   name: __t14.string(),
   path: __t14.string(),
@@ -454,13 +456,15 @@ class Flow {
   _name;
   _timeoutSeconds;
   _release;
-  constructor(sdk, keyHash, parentId, name, timeoutSeconds, release = "") {
+  _runId;
+  constructor(sdk, keyHash, parentId, name, timeoutSeconds, release = "", runId = "") {
     this._sdk = sdk;
     this._keyHash = keyHash;
     this._parentId = parentId;
     this._name = name;
     this._timeoutSeconds = !timeoutSeconds || timeoutSeconds === Infinity ? 0n : BigInt(timeoutSeconds);
     this._release = release;
+    this._runId = runId;
     this._exportToken = generateToken();
     this._ready = new Promise((resolve) => {
       this._resolveReady = resolve;
@@ -472,7 +476,13 @@ class Flow {
     const keyHash = this._keyHash;
     const timeoutSeconds = this._timeoutSeconds;
     if (this._parentId === 0n) {
-      const id = await this._sdk.createFlowAndResolveId(() => conn.reducers.createRootFlow({ keyHash, timeoutSeconds, exportToken, release: this._release }), exportToken);
+      const id = await this._sdk.createFlowAndResolveId(() => conn.reducers.createRootFlow({
+        keyHash,
+        runId: this._runId,
+        timeoutSeconds,
+        exportToken,
+        release: this._release
+      }), exportToken);
       this._id = id;
     } else {
       const parentFlowId = this._parentId;
@@ -521,7 +531,7 @@ class Flow {
     return this.log(message, data, "debug");
   }
   action(name, timeoutSeconds = 100) {
-    const child = new Flow(this._sdk, this._keyHash, 0n, name, timeoutSeconds, this._release);
+    const child = new Flow(this._sdk, this._keyHash, 0n, name, timeoutSeconds, this._release, this._runId);
     this._ready.then(() => {
       child._parentId = this._id;
       child._create();
@@ -574,12 +584,16 @@ class Flow {
       errorMessage
     });
   }
+  get runId() {
+    return this._runId;
+  }
   async exportID() {
     await this._ready;
     return JSON.stringify({
       flowId: this._id.toString(),
       exportToken: this._exportToken,
-      keyHash: this._keyHash
+      keyHash: this._keyHash,
+      runId: this._runId
     });
   }
   async getId() {
@@ -639,7 +653,8 @@ async function RL(secretKey, options = {}) {
     label = "",
     defaultTimeout = 100,
     release = "",
-    retention = "30d"
+    retention = "30d",
+    runId = generateRunId()
   } = options;
   const retentionDays = parseRetention(retention);
   const keyHash = await hashKey(secretKey);
@@ -656,7 +671,7 @@ async function RL(secretKey, options = {}) {
   try {
     sdk.conn.reducers.checkTimeouts({ keyHash });
   } catch {}
-  const root = new Flow(sdk, keyHash, 0n, "/", 0, release);
+  const root = new Flow(sdk, keyHash, 0n, "/", 0, release, runId);
   root._create();
   return root;
 }
@@ -669,7 +684,7 @@ async function restoreFlow(secretKey, exportedId, options = {}) {
   }
   const sdk = new SdkConnection(host, dbName);
   await sdk.connect();
-  const flow = new Flow(sdk, keyHash, 0n, "restored", 100);
+  const flow = new Flow(sdk, keyHash, 0n, "restored", 100, "", parsed.runId || "");
   flow._id = BigInt(parsed.flowId);
   flow._exportToken = parsed.exportToken;
   flow._resolveReady();
@@ -680,8 +695,14 @@ function generateKey() {
   crypto.getRandomValues(bytes);
   return "rl_" + Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+function generateRunId() {
+  const bytes = new Uint8Array(8);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
 export {
   restoreFlow,
+  generateRunId,
   generateKey,
   RL,
   Flow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radishbot/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli.ts

@@ -185,19 +185,27 @@ function cmdList(flows: any[]) {
   }
 
   const hasRelease = roots.some((f) => f.release && f.release !== "");
+  const hasRunId = roots.some((f) => f.runId && f.runId !== "");
 
   console.log(`${c.bold}Flows${c.reset} ${c.dim}(${roots.length} total)${c.reset}\n`);
-  if (hasRelease) {
-    console.log(
-      `${c.dim}  ${"ID".padEnd(8)} ${"STATUS".padEnd(10)} ${"RELEASE".padEnd(10)} ${"DURATION".padEnd(10)} CREATED${c.reset}`,
-    );
-    console.log(
-      `${c.dim}  ${"─".repeat(8)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(24)}${c.reset}`,
-    );
-  } else {
-    console.log(`${c.dim}  ${"ID".padEnd(8)} ${"STATUS".padEnd(10)} ${"DURATION".padEnd(10)} CREATED${c.reset}`);
-    console.log(`${c.dim}  ${"─".repeat(8)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(24)}${c.reset}`);
-  }
+  const cols = [
+    "ID".padEnd(8),
+    "STATUS".padEnd(10),
+    ...(hasRunId ? ["RUN".padEnd(18)] : []),
+    ...(hasRelease ? ["RELEASE".padEnd(10)] : []),
+    "DURATION".padEnd(10),
+    "CREATED",
+  ];
+  const divs = [
+    "─".repeat(8),
+    "─".repeat(10),
+    ...(hasRunId ? ["─".repeat(18)] : []),
+    ...(hasRelease ? ["─".repeat(10)] : []),
+    "─".repeat(10),
+    "─".repeat(24),
+  ];
+  console.log(`${c.dim}  ${cols.join(" ")}${c.reset}`);
+  console.log(`${c.dim}  ${divs.join(" ")}${c.reset}`);
 
   for (const f of roots.slice(0, 30)) {
     const id = f.id.toString().padEnd(8);
@@ -205,8 +213,11 @@ function cmdList(flows: any[]) {
     const status = padRight(f.status, 10);
     const dur = f.finishedAt !== 0n ? padRight(fmtDuration(f.createdAt, f.finishedAt), 10) : padRight("—", 10);
     const time = fmtDateTime(f.createdAt);
+    const runIdCol = hasRunId ? padRight(f.runId ? f.runId.slice(0, 16) : "—", 18) : "";
     const release = hasRelease ? padRight(f.release || "—", 10) + " " : "";
-    console.log(`  ${c.dim}${id}${c.reset} ${sc}${status}${c.reset} ${release}${dur} ${c.dim}${time}${c.reset}`);
+    console.log(
+      `  ${c.dim}${id}${c.reset} ${sc}${status}${c.reset} ${hasRunId ? runIdCol + " " : ""}${release}${dur} ${c.dim}${time}${c.reset}`,
+    );
   }
 
   if (roots.length > 30) {
@@ -225,6 +236,9 @@ function cmdShow(flowId: bigint, allFlows: any[], allLogs: any[]) {
   const sc = statusColor(flow.status);
   const releaseTag = flow.release ? `  ${c.dim}(${flow.release})${c.reset}` : "";
   console.log(`${c.bold}Flow #${flow.id}${c.reset}  ${sc}${flow.status}${c.reset}${releaseTag}`);
+  if (flow.runId) {
+    console.log(`${c.dim}Run: ${flow.runId}${c.reset}`);
+  }
   console.log(`${c.dim}Created: ${fmtDateTime(flow.createdAt)}${c.reset}`);
   if (flow.finishedAt !== 0n) {
     console.log(`${c.dim}Duration: ${fmtDuration(flow.createdAt, flow.finishedAt)}${c.reset}`);

package/src/index.ts

@@ -97,6 +97,7 @@ export class Flow {
   private _name: string;
   private _timeoutSeconds: bigint;
   private _release: string;
+  private _runId: string;
 
   /** @internal */
   constructor(
@@ -106,6 +107,7 @@ export class Flow {
     name: string,
     timeoutSeconds: number,
     release: string = "",
+    runId: string = "",
   ) {
     this._sdk = sdk;
     this._keyHash = keyHash;
@@ -113,6 +115,7 @@ export class Flow {
     this._name = name;
     this._timeoutSeconds = !timeoutSeconds || timeoutSeconds === Infinity ? 0n : BigInt(timeoutSeconds);
     this._release = release;
+    this._runId = runId;
     this._exportToken = generateToken();
     this._ready = new Promise<void>((resolve) => {
       this._resolveReady = resolve;
@@ -128,7 +131,14 @@ export class Flow {
 
     if (this._parentId === 0n) {
       const id = await this._sdk.createFlowAndResolveId(
-        () => conn.reducers.createRootFlow({ keyHash, timeoutSeconds, exportToken, release: this._release }),
+        () =>
+          conn.reducers.createRootFlow({
+            keyHash,
+            runId: this._runId,
+            timeoutSeconds,
+            exportToken,
+            release: this._release,
+          }),
         exportToken,
       );
       this._id = id;
@@ -191,7 +201,7 @@ export class Flow {
 
   /** Create a sub-action. Returns immediately — creation runs in background. */
   action(name: string, timeoutSeconds = 100): Flow {
-    const child = new Flow(this._sdk, this._keyHash, 0n, name, timeoutSeconds, this._release);
+    const child = new Flow(this._sdk, this._keyHash, 0n, name, timeoutSeconds, this._release, this._runId);
     this._ready.then(() => {
       (child as any)._parentId = this._id!;
       child._create();
@@ -252,6 +262,11 @@ export class Flow {
     });
   }
 
+  /** Get the run ID for this flow (pass to subprocesses via env, args, etc.) */
+  get runId(): string {
+    return this._runId;
+  }
+
   /** Export this flow's handle for restoration in another context */
   async exportID(): Promise<string> {
     await this._ready;
@@ -259,6 +274,7 @@ export class Flow {
       flowId: this._id!.toString(),
       exportToken: this._exportToken,
       keyHash: this._keyHash,
+      runId: this._runId,
     });
   }
 
@@ -323,6 +339,8 @@ export interface RLOptions {
   defaultTimeout?: number;
   release?: string;
   retention?: string;
+  /** Run ID — groups flows across processes. Auto-generated if not provided. */
+  runId?: string;
 }
 
 function parseRetention(retention: string): number {
@@ -360,6 +378,7 @@ export async function RL(secretKey: string, options: RLOptions = {}): Promise<Fl
     defaultTimeout = 100,
     release = "",
     retention = "30d",
+    runId = generateRunId(),
   } = options;
 
   const retentionDays = parseRetention(retention);
@@ -387,7 +406,7 @@ export async function RL(secretKey: string, options: RLOptions = {}): Promise<Fl
   }
 
   // Root flow — creation runs in background, logs queue until ready
-  const root = new Flow(sdk, keyHash, 0n, "/", 0, release);
+  const root = new Flow(sdk, keyHash, 0n, "/", 0, release, runId);
   root._create(); // fire-and-forget — resolves _ready when server assigns ID
   return root;
 }
@@ -405,7 +424,7 @@ export async function restoreFlow(secretKey: string, exportedId: string, options
   const sdk = new SdkConnection(host, dbName);
   await sdk.connect();
 
-  const flow = new Flow(sdk, keyHash, 0n, "restored", 100);
+  const flow = new Flow(sdk, keyHash, 0n, "restored", 100, "", parsed.runId || "");
   (flow as any)._id = BigInt(parsed.flowId);
   (flow as any)._exportToken = parsed.exportToken;
   (flow as any)._resolveReady();
@@ -423,3 +442,12 @@ export function generateKey(): string {
       .join("")
   );
 }
+
+/** Generate a random run ID (pass to subprocesses to link flows) */
+export function generateRunId(): string {
+  const bytes = new Uint8Array(8);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}

package/src/module_bindings/create_root_flow_reducer.ts

@@ -12,6 +12,7 @@ import {
 
 export default {
   keyHash: __t.string(),
+  runId: __t.string(),
   timeoutSeconds: __t.u64(),
   exportToken: __t.string(),
   release: __t.string(),

package/src/module_bindings/flow_table.ts

@@ -13,6 +13,7 @@ import {
 export default __t.row({
   id: __t.u64().primaryKey(),
   keyHash: __t.string().name("key_hash"),
+  runId: __t.string().name("run_id"),
   parentFlowId: __t.u64().name("parent_flow_id"),
   name: __t.string(),
   path: __t.string(),

package/src/module_bindings/types.ts

@@ -46,6 +46,7 @@ export type ErrorGroup = __Infer<typeof ErrorGroup>;
 export const Flow = __t.object("Flow", {
   id: __t.u64(),
   keyHash: __t.string(),
+  runId: __t.string(),
   parentFlowId: __t.u64(),
   name: __t.string(),
   path: __t.string(),