@smithers-orchestrator/devtools 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@smithers-orchestrator/devtools",
+  "version": "0.16.0",
+  "description": "Devtools and debugging utilities for Smithers workflow inspection",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "tsup --dts-only",
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/DevToolsDelta.ts

@@ -0,0 +1,8 @@
+import type { DevToolsDeltaOp } from "./DevToolsDeltaOp.ts";
+
+export type DevToolsDelta = {
+  version: 1;
+  baseSeq: number;
+  seq: number;
+  ops: DevToolsDeltaOp[];
+};

package/src/DevToolsDeltaOp.ts

@@ -0,0 +1,8 @@
+import type { DevToolsNode } from "./DevToolsNode.ts";
+
+export type DevToolsDeltaOp =
+  | { op: "addNode"; parentId: number; index: number; node: DevToolsNode }
+  | { op: "removeNode"; id: number }
+  | { op: "updateProps"; id: number; props: Record<string, unknown> }
+  | { op: "updateTask"; id: number; task: DevToolsNode["task"] }
+  | { op: "replaceRoot"; node: DevToolsNode };

package/src/DevToolsEngineEvent.ts

@@ -0,0 +1,98 @@
+/**
+ * Discriminated union of Smithers engine events that {@link DevToolsRunStore}
+ * understands when reducing engine state. Any other `type` value flows through
+ * the open-ended tail so future event kinds can be added without changes to
+ * consumers.
+ */
+export type DevToolsEngineEvent =
+  | RunStartedEvent
+  | RunFinishedEvent
+  | RunFailedEvent
+  | RunCancelledEvent
+  | FrameCommittedEvent
+  | NodePendingEvent
+  | NodeStartedEvent
+  | NodeFinishedEvent
+  | NodeFailedEvent
+  | NodeCancelledEvent
+  | NodeSkippedEvent
+  | NodeRetryingEvent
+  | NodeWaitingApprovalEvent
+  | NodeWaitingEventEvent
+  | NodeWaitingTimerEvent
+  | ToolCallStartedEvent
+  | ToolCallFinishedEvent
+  | UnknownEngineEvent;
+
+type RunEventBase = {
+  runId: string;
+  timestampMs: number;
+};
+
+type NodeEventBase = RunEventBase & {
+  nodeId: string;
+  iteration: number;
+};
+
+export type RunStartedEvent = RunEventBase & { type: "RunStarted" };
+export type RunFinishedEvent = RunEventBase & { type: "RunFinished" };
+export type RunFailedEvent = RunEventBase & { type: "RunFailed"; error?: unknown };
+export type RunCancelledEvent = RunEventBase & { type: "RunCancelled" };
+
+export type FrameCommittedEvent = RunEventBase & {
+  type: "FrameCommitted";
+  frameNo: number;
+};
+
+export type NodePendingEvent = NodeEventBase & { type: "NodePending" };
+export type NodeStartedEvent = NodeEventBase & {
+  type: "NodeStarted";
+  attempt: number;
+};
+export type NodeFinishedEvent = NodeEventBase & {
+  type: "NodeFinished";
+  attempt: number;
+};
+export type NodeFailedEvent = NodeEventBase & {
+  type: "NodeFailed";
+  attempt: number;
+  error?: unknown;
+};
+export type NodeCancelledEvent = NodeEventBase & { type: "NodeCancelled" };
+export type NodeSkippedEvent = NodeEventBase & { type: "NodeSkipped" };
+export type NodeRetryingEvent = NodeEventBase & {
+  type: "NodeRetrying";
+  attempt: number;
+};
+export type NodeWaitingApprovalEvent = NodeEventBase & {
+  type: "NodeWaitingApproval";
+};
+export type NodeWaitingEventEvent = NodeEventBase & {
+  type: "NodeWaitingEvent";
+};
+export type NodeWaitingTimerEvent = NodeEventBase & {
+  type: "NodeWaitingTimer";
+};
+
+export type ToolCallStartedEvent = NodeEventBase & {
+  type: "ToolCallStarted";
+  toolName: string;
+  seq: number;
+};
+export type ToolCallFinishedEvent = NodeEventBase & {
+  type: "ToolCallFinished";
+  toolName: string;
+  seq: number;
+  status?: string;
+};
+
+/**
+ * Open tail: any future engine event with the minimal shape we require
+ * (`type` + `runId` + `timestampMs`). The store ignores unknown `type`s but
+ * still records them in `run.events`.
+ */
+export type UnknownEngineEvent = {
+  type: string;
+  runId: string;
+  timestampMs: number;
+} & Record<string, unknown>;

package/src/DevToolsEventBus.ts

@@ -0,0 +1,9 @@
+import type { DevToolsEngineEvent } from "./DevToolsEngineEvent.ts";
+
+export type DevToolsEventBus = {
+  on: (event: "event", handler: (e: DevToolsEngineEvent) => void) => void;
+  removeListener: (
+    event: "event",
+    handler: (e: DevToolsEngineEvent) => void,
+  ) => void;
+};

package/src/DevToolsEventHandler.ts

@@ -0,0 +1,6 @@
+import type { DevToolsSnapshot } from "./DevToolsSnapshot.ts";
+
+export type DevToolsEventHandler = (
+  event: "commit" | "unmount",
+  snapshot: DevToolsSnapshot,
+) => void;

package/src/DevToolsNode.ts

@@ -0,0 +1,23 @@
+import type { SmithersNodeType } from "./SmithersNodeType.ts";
+
+export type DevToolsNode = {
+  id: number;
+  /** Smithers-level type: "workflow" | "task" | "sequence" | etc. */
+  type: SmithersNodeType;
+  /** Display name (component function name or host tag) */
+  name: string;
+  /** Props snapshot (serializable subset) */
+  props: Record<string, unknown>;
+  /** Task-specific fields extracted from renderer raw props */
+  task?: {
+    nodeId: string;
+    kind: "agent" | "compute" | "static";
+    agent?: string;
+    label?: string;
+    outputTableName?: string;
+    iteration?: number;
+  };
+  children: DevToolsNode[];
+  /** Depth in the Smithers tree (not renderer tree depth) */
+  depth: number;
+};

package/src/DevToolsRunStore.js

@@ -0,0 +1,232 @@
+/** @typedef {import("./DevToolsEngineEvent.ts").DevToolsEngineEvent} DevToolsEngineEvent */
+/** @typedef {import("./DevToolsEventBus.ts").DevToolsEventBus} DevToolsEventBus */
+/** @typedef {import("./DevToolsRunStoreOptions.ts").DevToolsRunStoreOptions} DevToolsRunStoreOptions */
+/** @typedef {import("./RunExecutionState.ts").RunExecutionState} RunExecutionState */
+/** @typedef {import("./TaskExecutionState.ts").TaskExecutionState} TaskExecutionState */
+
+export class DevToolsRunStore {
+    /** @type {DevToolsRunStoreOptions} */
+    options;
+    /** @type {Map<string, RunExecutionState>} */
+    _runs = new Map();
+    /** @type {Array<{ bus: DevToolsEventBus; handler: (event: DevToolsEngineEvent) => void }>} */
+    _eventBusListeners = [];
+    /**
+     * @param {DevToolsRunStoreOptions} [options]
+     */
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Attach to a Smithers EventBus-like source.
+     * @param {DevToolsEventBus} bus
+     * @returns {this}
+     */
+    attachEventBus(bus) {
+        /**
+         * @param {DevToolsEngineEvent} event
+         */
+        const handler = (event) => this.processEngineEvent(event);
+        bus.on("event", handler);
+        this._eventBusListeners.push({ bus, handler });
+        return this;
+    }
+    /**
+     * Detach all EventBus listeners registered by this store.
+     * @returns {void}
+     */
+    detachEventBuses() {
+        for (const { bus, handler } of this._eventBusListeners) {
+            bus.removeListener("event", handler);
+        }
+        this._eventBusListeners = [];
+    }
+    /**
+     * Get execution state for a specific run.
+     * @param {string} runId
+     * @returns {RunExecutionState | undefined}
+     */
+    getRun(runId) {
+        return this._runs.get(runId);
+    }
+    /**
+     * Get all tracked runs.
+     * @returns {Map<string, RunExecutionState>}
+     */
+    get runs() {
+        return this._runs;
+    }
+    /**
+     * Get task execution state by nodeId within a run. Searches all iterations.
+     * @param {string} runId
+     * @param {string} nodeId
+     * @param {number} [iteration]
+     * @returns {TaskExecutionState | undefined}
+     */
+    getTaskState(runId, nodeId, iteration) {
+        const run = this._runs.get(runId);
+        if (!run)
+            return undefined;
+        if (typeof iteration === "number") {
+            return run.tasks.get(`${nodeId}::${iteration}`);
+        }
+        for (const task of run.tasks.values()) {
+            if (task.nodeId === nodeId)
+                return task;
+        }
+        return undefined;
+    }
+    /**
+     * @param {DevToolsEngineEvent} event
+     * @returns {void}
+     */
+    processEngineEvent(event) {
+        if (!event || !event.type || !event.runId)
+            return;
+        const run = this.ensureRun(event.runId);
+        run.events.push(event);
+        const verbose = this.options.verbose ?? false;
+        switch (event.type) {
+            case "RunStarted":
+                run.status = "running";
+                run.startedAt = event.timestampMs;
+                break;
+            case "RunFinished":
+                run.status = "finished";
+                run.finishedAt = event.timestampMs;
+                break;
+            case "RunFailed":
+                run.status = "failed";
+                run.finishedAt = event.timestampMs;
+                break;
+            case "RunCancelled":
+                run.status = "cancelled";
+                run.finishedAt = event.timestampMs;
+                break;
+            case "FrameCommitted":
+                run.frameNo = event.frameNo;
+                break;
+            case "NodePending": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.status = "pending";
+                break;
+            }
+            case "NodeStarted": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.status = "started";
+                task.attempt = event.attempt;
+                task.startedAt = event.timestampMs;
+                if (verbose) {
+                    console.log(`▶️  [smithers-devtools] Task started: ${event.nodeId} (attempt ${event.attempt})`);
+                }
+                break;
+            }
+            case "NodeFinished": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.status = "finished";
+                task.attempt = event.attempt;
+                task.finishedAt = event.timestampMs;
+                if (verbose) {
+                    console.log(`✅ [smithers-devtools] Task finished: ${event.nodeId}`);
+                }
+                break;
+            }
+            case "NodeFailed": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.status = "failed";
+                task.attempt = event.attempt;
+                task.finishedAt = event.timestampMs;
+                task.error = event.error;
+                if (verbose) {
+                    console.log(`❌ [smithers-devtools] Task failed: ${event.nodeId}`);
+                }
+                break;
+            }
+            case "NodeCancelled": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.status = "cancelled";
+                break;
+            }
+            case "NodeSkipped": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.status = "skipped";
+                break;
+            }
+            case "NodeRetrying": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.status = "retrying";
+                task.attempt = event.attempt;
+                break;
+            }
+            case "NodeWaitingApproval": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.status = "waiting-approval";
+                run.status = "waiting-approval";
+                break;
+            }
+            case "NodeWaitingEvent": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.status = "waiting-event";
+                break;
+            }
+            case "NodeWaitingTimer": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.status = "waiting-timer";
+                run.status = "waiting-timer";
+                break;
+            }
+            case "ToolCallStarted": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                task.toolCalls.push({ name: event.toolName, seq: event.seq });
+                break;
+            }
+            case "ToolCallFinished": {
+                const task = this.ensureTask(run, event.nodeId, event.iteration);
+                const tc = task.toolCalls.find((t) => t.name === event.toolName && t.seq === event.seq);
+                if (tc)
+                    tc.status = event.status;
+                break;
+            }
+        }
+        this.options.onEngineEvent?.(event);
+    }
+    /**
+     * @param {string} runId
+     * @returns {RunExecutionState}
+     */
+    ensureRun(runId) {
+        let run = this._runs.get(runId);
+        if (!run) {
+            run = {
+                runId,
+                status: "running",
+                frameNo: 0,
+                tasks: new Map(),
+                events: [],
+            };
+            this._runs.set(runId, run);
+        }
+        return run;
+    }
+    /**
+     * @param {RunExecutionState} run
+     * @param {string} nodeId
+     * @param {number} iteration
+     * @returns {TaskExecutionState}
+     */
+    ensureTask(run, nodeId, iteration) {
+        const key = `${nodeId}::${iteration}`;
+        let task = run.tasks.get(key);
+        if (!task) {
+            task = {
+                nodeId,
+                iteration,
+                status: "pending",
+                attempt: 0,
+                toolCalls: [],
+            };
+            run.tasks.set(key, task);
+        }
+        return task;
+    }
+}

package/src/DevToolsRunStoreOptions.ts

@@ -0,0 +1,6 @@
+import type { SmithersDevToolsOptions } from "./SmithersDevToolsOptions.ts";
+
+export type DevToolsRunStoreOptions = Pick<
+  SmithersDevToolsOptions,
+  "onEngineEvent" | "verbose"
+>;

package/src/DevToolsSnapshot.ts

@@ -0,0 +1,48 @@
+import type { DevToolsNode } from "./DevToolsNode.ts";
+
+type RunState =
+  | "running"
+  | "waiting-approval"
+  | "waiting-event"
+  | "waiting-timer"
+  | "recovering"
+  | "stale"
+  | "orphaned"
+  | "failed"
+  | "cancelled"
+  | "succeeded"
+  | "unknown";
+
+type ReasonBlocked =
+  | { kind: "approval"; nodeId: string; requestedAt: string }
+  | { kind: "event"; nodeId: string; correlationKey: string }
+  | { kind: "timer"; nodeId: string; wakeAt: string }
+  | {
+      kind: "provider";
+      nodeId: string;
+      code: "rate-limit" | "auth" | "timeout";
+    }
+  | { kind: "tool"; nodeId: string; toolName: string; code: string };
+
+type ReasonUnhealthy =
+  | { kind: "engine-heartbeat-stale"; lastHeartbeatAt: string }
+  | { kind: "ui-heartbeat-stale"; lastSeenAt: string }
+  | { kind: "db-lock" }
+  | { kind: "sandbox-unreachable" }
+  | { kind: "supervisor-backoff"; attempt: number; nextAt: string };
+
+export type RunStateView = {
+  runId: string;
+  state: RunState;
+  blocked?: ReasonBlocked;
+  unhealthy?: ReasonUnhealthy;
+  computedAt: string;
+};
+
+export type DevToolsSnapshot = {
+  tree: DevToolsNode | null;
+  nodeCount: number;
+  taskCount: number;
+  timestamp: number;
+  runState?: RunStateView;
+};

package/src/DevToolsSnapshotV1.ts

@@ -0,0 +1,9 @@
+import type { DevToolsNode } from "./DevToolsNode.ts";
+
+export type DevToolsSnapshotV1 = {
+  version: 1;
+  runId: string;
+  frameNo: number;
+  seq: number;
+  root: DevToolsNode;
+};

package/src/InvalidDeltaError.js

@@ -0,0 +1,11 @@
+export class InvalidDeltaError extends Error {
+    /** @type {"InvalidDelta"} */
+    code = "InvalidDelta";
+    /**
+     * @param {string} message
+     */
+    constructor(message) {
+        super(message);
+        this.name = "InvalidDeltaError";
+    }
+}

package/src/RunExecutionState.ts

@@ -0,0 +1,18 @@
+import type { TaskExecutionState } from "./TaskExecutionState.ts";
+
+/** Execution state for a run, aggregated from SmithersEvent stream */
+export type RunExecutionState = {
+  runId: string;
+  status:
+    | "running"
+    | "finished"
+    | "failed"
+    | "cancelled"
+    | "waiting-approval"
+    | "waiting-timer";
+  frameNo: number;
+  tasks: Map<string, TaskExecutionState>;
+  events: Array<{ type: string; timestampMs: number; [key: string]: unknown }>;
+  startedAt?: number;
+  finishedAt?: number;
+};

package/src/SMITHERS_NODE_ICONS.js

@@ -0,0 +1,21 @@
+/** @typedef {import("./SmithersNodeType.ts").SmithersNodeType} SmithersNodeType */
+
+/** @type {Record<SmithersNodeType, string>} */
+export const SMITHERS_NODE_ICONS = {
+    workflow: "📋",
+    task: "⚡",
+    sequence: "➡️",
+    parallel: "⚡",
+    "merge-queue": "🔀",
+    branch: "🌿",
+    loop: "🔁",
+    worktree: "🌳",
+    approval: "✋",
+    timer: "⏱️",
+    subflow: "🔗",
+    "wait-for-event": "📡",
+    saga: "🔄",
+    "try-catch": "🛡️",
+    fragment: "📦",
+    unknown: "❓",
+};

package/src/SNAPSHOT_SERIALIZER_DEFAULT_MAX_DEPTH.js

@@ -0,0 +1,2 @@
+/** @type {number} */
+export const SNAPSHOT_SERIALIZER_DEFAULT_MAX_DEPTH = 100;