@smithers-orchestrator/protocol 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,35 @@
+{
+  "name": "@smithers-orchestrator/protocol",
+  "version": "0.16.0",
+  "description": "Shared Smithers contracts, errors, and small value types",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts"
+    },
+    "./errors": {
+      "types": "./src/index.d.ts"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "effect": "^3.21.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "tsup --dts-only",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/devtools/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/devtools/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/devtools/DevToolsEvent.ts

@@ -0,0 +1,14 @@
+import type { DevToolsSnapshot } from "./DevToolsSnapshot.ts";
+import type { DevToolsDelta } from "./DevToolsDelta.ts";
+
+export type DevToolsEvent =
+  | {
+      version: 1;
+      kind: "snapshot";
+      snapshot: DevToolsSnapshot;
+    }
+  | {
+      version: 1;
+      kind: "delta";
+      delta: DevToolsDelta;
+    };

package/src/devtools/DevToolsNode.ts

@@ -0,0 +1,18 @@
+import type { DevToolsNodeType } from "./DevToolsNodeType.ts";
+
+export type DevToolsNode = {
+  id: number;
+  type: DevToolsNodeType;
+  name: string;
+  props: Record<string, unknown>;
+  task?: {
+    nodeId: string;
+    kind: "agent" | "compute" | "static";
+    agent?: string;
+    label?: string;
+    outputTableName?: string;
+    iteration?: number;
+  };
+  children: DevToolsNode[];
+  depth: number;
+};

package/src/devtools/DevToolsNodeType.ts

@@ -0,0 +1,17 @@
+export type DevToolsNodeType =
+  | "workflow"
+  | "task"
+  | "sequence"
+  | "parallel"
+  | "merge-queue"
+  | "branch"
+  | "loop"
+  | "worktree"
+  | "approval"
+  | "timer"
+  | "subflow"
+  | "wait-for-event"
+  | "saga"
+  | "try-catch"
+  | "fragment"
+  | "unknown";

package/src/devtools/DevToolsSnapshot.ts

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

package/src/devtools.js

@@ -0,0 +1,10 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./devtools/DevToolsDelta.ts").DevToolsDelta} DevToolsDelta */
+/** @typedef {import("./devtools/DevToolsDeltaOp.ts").DevToolsDeltaOp} DevToolsDeltaOp */
+/** @typedef {import("./devtools/DevToolsEvent.ts").DevToolsEvent} DevToolsEvent */
+/** @typedef {import("./devtools/DevToolsNode.ts").DevToolsNode} DevToolsNode */
+/** @typedef {import("./devtools/DevToolsNodeType.ts").DevToolsNodeType} DevToolsNodeType */
+/** @typedef {import("./devtools/DevToolsSnapshot.ts").DevToolsSnapshot} DevToolsSnapshot */
+// @smithers-type-exports-end
+
+export const DEVTOOLS_PROTOCOL_VERSION = /** @type {1} */ (1);

package/src/errors/DevToolsErrorCode.ts

@@ -0,0 +1,8 @@
+export type DevToolsErrorCode =
+  | "RunNotFound"
+  | "InvalidRunId"
+  | "FrameOutOfRange"
+  | "SeqOutOfRange"
+  | "BackpressureDisconnect"
+  | "Unauthorized"
+  | "InvalidDelta";

package/src/errors/JumpToFrameErrorCode.ts

@@ -0,0 +1,12 @@
+export type JumpToFrameErrorCode =
+  | "InvalidRunId"
+  | "InvalidFrameNo"
+  | "RunNotFound"
+  | "FrameOutOfRange"
+  | "ConfirmationRequired"
+  | "Busy"
+  | "UnsupportedSandbox"
+  | "VcsError"
+  | "RewindFailed"
+  | "RateLimited"
+  | "Unauthorized";

package/src/errors/NodeDiffErrorCode.ts

@@ -0,0 +1,11 @@
+export type NodeDiffErrorCode =
+  | "InvalidRunId"
+  | "InvalidNodeId"
+  | "InvalidIteration"
+  | "RunNotFound"
+  | "NodeNotFound"
+  | "AttemptNotFound"
+  | "AttemptNotFinished"
+  | "VcsError"
+  | "WorkingTreeDirty"
+  | "DiffTooLarge";

package/src/errors/NodeOutputErrorCode.ts

@@ -0,0 +1,11 @@
+export type NodeOutputErrorCode =
+  | "InvalidRunId"
+  | "InvalidNodeId"
+  | "InvalidIteration"
+  | "RunNotFound"
+  | "NodeNotFound"
+  | "IterationNotFound"
+  | "NodeHasNoOutput"
+  | "SchemaConversionError"
+  | "MalformedOutputRow"
+  | "PayloadTooLarge";

package/src/errors/ProtocolError.ts

@@ -0,0 +1,10 @@
+import type { DevToolsErrorCode } from "./DevToolsErrorCode.ts";
+import type { NodeOutputErrorCode } from "./NodeOutputErrorCode.ts";
+import type { NodeDiffErrorCode } from "./NodeDiffErrorCode.ts";
+import type { JumpToFrameErrorCode } from "./JumpToFrameErrorCode.ts";
+
+export type ProtocolError = {
+  code: DevToolsErrorCode | NodeOutputErrorCode | NodeDiffErrorCode | JumpToFrameErrorCode | string;
+  message: string;
+  hint?: string;
+};

package/src/errors/index.js

@@ -0,0 +1,54 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./DevToolsErrorCode.ts").DevToolsErrorCode} DevToolsErrorCode */
+/** @typedef {import("./JumpToFrameErrorCode.ts").JumpToFrameErrorCode} JumpToFrameErrorCode */
+/** @typedef {import("./NodeDiffErrorCode.ts").NodeDiffErrorCode} NodeDiffErrorCode */
+/** @typedef {import("./NodeOutputErrorCode.ts").NodeOutputErrorCode} NodeOutputErrorCode */
+/** @typedef {import("./ProtocolError.ts").ProtocolError} ProtocolError */
+// @smithers-type-exports-end
+
+export const DEVTOOLS_ERROR_CODES = [
+    "RunNotFound",
+    "InvalidRunId",
+    "FrameOutOfRange",
+    "SeqOutOfRange",
+    "BackpressureDisconnect",
+    "Unauthorized",
+    "InvalidDelta",
+];
+export const NODE_OUTPUT_ERROR_CODES = [
+    "InvalidRunId",
+    "InvalidNodeId",
+    "InvalidIteration",
+    "RunNotFound",
+    "NodeNotFound",
+    "IterationNotFound",
+    "NodeHasNoOutput",
+    "SchemaConversionError",
+    "MalformedOutputRow",
+    "PayloadTooLarge",
+];
+export const NODE_DIFF_ERROR_CODES = [
+    "InvalidRunId",
+    "InvalidNodeId",
+    "InvalidIteration",
+    "RunNotFound",
+    "NodeNotFound",
+    "AttemptNotFound",
+    "AttemptNotFinished",
+    "VcsError",
+    "WorkingTreeDirty",
+    "DiffTooLarge",
+];
+export const JUMP_TO_FRAME_ERROR_CODES = [
+    "InvalidRunId",
+    "InvalidFrameNo",
+    "RunNotFound",
+    "FrameOutOfRange",
+    "ConfirmationRequired",
+    "Busy",
+    "UnsupportedSandbox",
+    "VcsError",
+    "RewindFailed",
+    "RateLimited",
+    "Unauthorized",
+];

package/src/errors.ts

@@ -0,0 +1,55 @@
+export const DEVTOOLS_ERROR_CODES = [
+    "RunNotFound",
+    "InvalidRunId",
+    "FrameOutOfRange",
+    "SeqOutOfRange",
+    "BackpressureDisconnect",
+    "Unauthorized",
+    "InvalidDelta",
+] as const;
+export type DevToolsErrorCode = (typeof DEVTOOLS_ERROR_CODES)[number];
+export const NODE_OUTPUT_ERROR_CODES = [
+    "InvalidRunId",
+    "InvalidNodeId",
+    "InvalidIteration",
+    "RunNotFound",
+    "NodeNotFound",
+    "IterationNotFound",
+    "NodeHasNoOutput",
+    "SchemaConversionError",
+    "MalformedOutputRow",
+    "PayloadTooLarge",
+] as const;
+export type NodeOutputErrorCode = (typeof NODE_OUTPUT_ERROR_CODES)[number];
+export const NODE_DIFF_ERROR_CODES = [
+    "InvalidRunId",
+    "InvalidNodeId",
+    "InvalidIteration",
+    "RunNotFound",
+    "NodeNotFound",
+    "AttemptNotFound",
+    "AttemptNotFinished",
+    "VcsError",
+    "WorkingTreeDirty",
+    "DiffTooLarge",
+] as const;
+export type NodeDiffErrorCode = (typeof NODE_DIFF_ERROR_CODES)[number];
+export const JUMP_TO_FRAME_ERROR_CODES = [
+    "InvalidRunId",
+    "InvalidFrameNo",
+    "RunNotFound",
+    "FrameOutOfRange",
+    "ConfirmationRequired",
+    "Busy",
+    "UnsupportedSandbox",
+    "VcsError",
+    "RewindFailed",
+    "RateLimited",
+    "Unauthorized",
+] as const;
+export type JumpToFrameErrorCode = (typeof JUMP_TO_FRAME_ERROR_CODES)[number];
+export type ProtocolError = {
+    code: DevToolsErrorCode | NodeOutputErrorCode | NodeDiffErrorCode | JumpToFrameErrorCode | string;
+    message: string;
+    hint?: string;
+};

package/src/index.d.ts

@@ -0,0 +1,106 @@
+type DevToolsNodeType = "workflow" | "task" | "sequence" | "parallel" | "merge-queue" | "branch" | "loop" | "worktree" | "approval" | "timer" | "subflow" | "wait-for-event" | "saga" | "try-catch" | "fragment" | "unknown";
+
+type DevToolsNode = {
+    id: number;
+    type: DevToolsNodeType;
+    name: string;
+    props: Record<string, unknown>;
+    task?: {
+        nodeId: string;
+        kind: "agent" | "compute" | "static";
+        agent?: string;
+        label?: string;
+        outputTableName?: string;
+        iteration?: number;
+    };
+    children: DevToolsNode[];
+    depth: number;
+};
+
+type DevToolsSnapshot = {
+    version: 1;
+    runId: string;
+    frameNo: number;
+    seq: number;
+    root: DevToolsNode;
+};
+
+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;
+};
+
+type DevToolsDelta = {
+    version: 1;
+    baseSeq: number;
+    seq: number;
+    ops: DevToolsDeltaOp[];
+};
+
+type DevToolsEvent = {
+    version: 1;
+    kind: "snapshot";
+    snapshot: DevToolsSnapshot;
+} | {
+    version: 1;
+    kind: "delta";
+    delta: DevToolsDelta;
+};
+
+/** @typedef {import("./devtools/DevToolsDelta.ts").DevToolsDelta} DevToolsDelta */
+/** @typedef {import("./devtools/DevToolsDeltaOp.ts").DevToolsDeltaOp} DevToolsDeltaOp */
+/** @typedef {import("./devtools/DevToolsEvent.ts").DevToolsEvent} DevToolsEvent */
+/** @typedef {import("./devtools/DevToolsNode.ts").DevToolsNode} DevToolsNode */
+/** @typedef {import("./devtools/DevToolsNodeType.ts").DevToolsNodeType} DevToolsNodeType */
+/** @typedef {import("./devtools/DevToolsSnapshot.ts").DevToolsSnapshot} DevToolsSnapshot */
+declare const DEVTOOLS_PROTOCOL_VERSION: 1;
+
+type OutputSchemaFieldType = "string" | "number" | "boolean" | "object" | "array" | "null" | "unknown";
+type OutputSchemaDescriptor = {
+    fields: Array<{
+        name: string;
+        type: OutputSchemaFieldType;
+        optional: boolean;
+        nullable: boolean;
+        description?: string;
+        enum?: readonly unknown[];
+    }>;
+};
+type NodeOutputResponse = {
+    status: "produced" | "pending" | "failed";
+    row: Record<string, unknown> | null;
+    schema: OutputSchemaDescriptor | null;
+    partial?: Record<string, unknown> | null;
+};
+
+declare const DEVTOOLS_ERROR_CODES: readonly ["RunNotFound", "InvalidRunId", "FrameOutOfRange", "SeqOutOfRange", "BackpressureDisconnect", "Unauthorized", "InvalidDelta"];
+type DevToolsErrorCode = (typeof DEVTOOLS_ERROR_CODES)[number];
+declare const NODE_OUTPUT_ERROR_CODES: readonly ["InvalidRunId", "InvalidNodeId", "InvalidIteration", "RunNotFound", "NodeNotFound", "IterationNotFound", "NodeHasNoOutput", "SchemaConversionError", "MalformedOutputRow", "PayloadTooLarge"];
+type NodeOutputErrorCode = (typeof NODE_OUTPUT_ERROR_CODES)[number];
+declare const NODE_DIFF_ERROR_CODES: readonly ["InvalidRunId", "InvalidNodeId", "InvalidIteration", "RunNotFound", "NodeNotFound", "AttemptNotFound", "AttemptNotFinished", "VcsError", "WorkingTreeDirty", "DiffTooLarge"];
+type NodeDiffErrorCode = (typeof NODE_DIFF_ERROR_CODES)[number];
+declare const JUMP_TO_FRAME_ERROR_CODES: readonly ["InvalidRunId", "InvalidFrameNo", "RunNotFound", "FrameOutOfRange", "ConfirmationRequired", "Busy", "UnsupportedSandbox", "VcsError", "RewindFailed", "RateLimited", "Unauthorized"];
+type JumpToFrameErrorCode = (typeof JUMP_TO_FRAME_ERROR_CODES)[number];
+type ProtocolError = {
+    code: DevToolsErrorCode | NodeOutputErrorCode | NodeDiffErrorCode | JumpToFrameErrorCode | string;
+    message: string;
+    hint?: string;
+};
+
+export { DEVTOOLS_ERROR_CODES, DEVTOOLS_PROTOCOL_VERSION, type DevToolsDelta, type DevToolsDeltaOp, type DevToolsErrorCode, type DevToolsEvent, type DevToolsNode, type DevToolsNodeType, type DevToolsSnapshot, JUMP_TO_FRAME_ERROR_CODES, type JumpToFrameErrorCode, NODE_DIFF_ERROR_CODES, NODE_OUTPUT_ERROR_CODES, type NodeDiffErrorCode, type NodeOutputErrorCode, type NodeOutputResponse, type OutputSchemaDescriptor, type OutputSchemaFieldType, type ProtocolError };

package/src/index.ts

@@ -0,0 +1,23 @@
+export { DEVTOOLS_PROTOCOL_VERSION } from "./devtools.js";
+export type { DevToolsNodeType } from "./devtools/DevToolsNodeType.ts";
+export type { DevToolsNode } from "./devtools/DevToolsNode.ts";
+export type { DevToolsSnapshot } from "./devtools/DevToolsSnapshot.ts";
+export type { DevToolsDeltaOp } from "./devtools/DevToolsDeltaOp.ts";
+export type { DevToolsDelta } from "./devtools/DevToolsDelta.ts";
+export type { DevToolsEvent } from "./devtools/DevToolsEvent.ts";
+export {
+  type OutputSchemaFieldType,
+  type OutputSchemaDescriptor,
+  type NodeOutputResponse,
+} from "./outputs.ts";
+export {
+  DEVTOOLS_ERROR_CODES,
+  type DevToolsErrorCode,
+  NODE_OUTPUT_ERROR_CODES,
+  type NodeOutputErrorCode,
+  NODE_DIFF_ERROR_CODES,
+  type NodeDiffErrorCode,
+  JUMP_TO_FRAME_ERROR_CODES,
+  type JumpToFrameErrorCode,
+  type ProtocolError,
+} from "./errors.ts";

package/src/outputs.ts

@@ -0,0 +1,19 @@
+export type OutputSchemaFieldType = "string" | "number" | "boolean" | "object" | "array" | "null" | "unknown";
+
+export type OutputSchemaDescriptor = {
+    fields: Array<{
+        name: string;
+        type: OutputSchemaFieldType;
+        optional: boolean;
+        nullable: boolean;
+        description?: string;
+        enum?: readonly unknown[];
+    }>;
+};
+
+export type NodeOutputResponse = {
+    status: "produced" | "pending" | "failed";
+    row: Record<string, unknown> | null;
+    schema: OutputSchemaDescriptor | null;
+    partial?: Record<string, unknown> | null;
+};