@smithers-orchestrator/errors 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,33 @@
+{
+  "name": "@smithers-orchestrator/errors",
+  "version": "0.16.0",
+  "description": "Error types, tagged errors, and error utilities for Smithers",
+  "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/"
+  ],
+  "dependencies": {
+    "effect": "^3.21.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsup --dts-only"
+  }
+}

package/src/AgentCliError.js

@@ -0,0 +1,9 @@
+import { Data } from "effect";
+
+/** @typedef {import("./TaggedErrorDetails.ts").GenericTaggedErrorArgs} GenericTaggedErrorArgs */
+
+const AgentCliErrorBase = /** @type {new (args: GenericTaggedErrorArgs) => import("effect/Cause").YieldableError & { readonly _tag: "AgentCliError" } & Readonly<GenericTaggedErrorArgs>} */ (
+  Data.TaggedError("AgentCliError")
+);
+
+export class AgentCliError extends AgentCliErrorBase {}

package/src/DbWriteFailed.js

@@ -0,0 +1,9 @@
+import { Data } from "effect";
+
+/** @typedef {import("./TaggedErrorDetails.ts").GenericTaggedErrorArgs} GenericTaggedErrorArgs */
+
+const DbWriteFailedBase = /** @type {new (args: GenericTaggedErrorArgs) => import("effect/Cause").YieldableError & { readonly _tag: "DbWriteFailed" } & Readonly<GenericTaggedErrorArgs>} */ (
+  Data.TaggedError("DbWriteFailed")
+);
+
+export class DbWriteFailed extends DbWriteFailedBase {}

package/src/ERROR_REFERENCE_URL.js

@@ -0,0 +1 @@
+export const ERROR_REFERENCE_URL = "https://smithers.sh/reference/errors";

package/src/EngineError.js

@@ -0,0 +1,17 @@
+import { Data } from "effect";
+
+/** @typedef {import("./EngineErrorCode.ts").EngineErrorCode} EngineErrorCode */
+
+/**
+ * @typedef {{
+ *   readonly code: EngineErrorCode;
+ *   readonly message: string;
+ *   readonly context?: Record<string, unknown>;
+ * }} EngineErrorArgs
+ */
+
+const EngineErrorBase = /** @type {new (args: EngineErrorArgs) => import("effect/Cause").YieldableError & { readonly _tag: "EngineError" } & Readonly<EngineErrorArgs>} */ (
+  Data.TaggedError("EngineError")
+);
+
+export class EngineError extends EngineErrorBase {}

package/src/EngineErrorCode.ts

@@ -0,0 +1,21 @@
+export type EngineErrorCode =
+  | "TASK_HEARTBEAT_TIMEOUT"
+  | "DUPLICATE_ID"
+  | "NESTED_LOOP"
+  | "INVALID_CONTINUATION_STATE"
+  | "TASK_ID_REQUIRED"
+  | "TASK_MISSING_OUTPUT"
+  | "WORKTREE_EMPTY_PATH"
+  | "INVALID_INPUT"
+  | "WORKFLOW_EXECUTION_FAILED"
+  | "TASK_TIMEOUT"
+  | "TASK_ABORTED"
+  | "MISSING_OUTPUT"
+  | "DEP_NOT_SATISFIED"
+  | "RUN_CANCELLED"
+  | "RUN_NOT_FOUND"
+  | "NODE_NOT_FOUND"
+  | "STORAGE_ERROR"
+  | "SCHEDULER_ERROR"
+  | "SESSION_ERROR"
+  | "INTERNAL_ERROR";

package/src/ErrorWrapOptions.ts

@@ -0,0 +1,6 @@
+import type { SmithersErrorCode } from "./SmithersErrorCode.ts";
+
+export type ErrorWrapOptions = {
+  readonly code?: SmithersErrorCode;
+  readonly details?: Record<string, unknown>;
+};

package/src/InvalidInput.js

@@ -0,0 +1,9 @@
+import { Data } from "effect";
+
+/** @typedef {import("./TaggedErrorDetails.ts").GenericTaggedErrorArgs} GenericTaggedErrorArgs */
+
+const InvalidInputBase = /** @type {new (args: GenericTaggedErrorArgs) => import("effect/Cause").YieldableError & { readonly _tag: "InvalidInput" } & Readonly<GenericTaggedErrorArgs>} */ (
+  Data.TaggedError("InvalidInput")
+);
+
+export class InvalidInput extends InvalidInputBase {}

package/src/KnownSmithersErrorCode.ts

@@ -0,0 +1,3 @@
+import type { smithersErrorDefinitions } from "./smithersErrorDefinitions.ts";
+
+export type KnownSmithersErrorCode = keyof typeof smithersErrorDefinitions;

package/src/RunNotFound.js

@@ -0,0 +1,14 @@
+import { Data } from "effect";
+
+/**
+ * @typedef {{
+ *   readonly message: string;
+ *   readonly runId: string;
+ * }} RunNotFoundArgs
+ */
+
+const RunNotFoundBase = /** @type {new (args: RunNotFoundArgs) => import("effect/Cause").YieldableError & { readonly _tag: "RunNotFound" } & Readonly<RunNotFoundArgs>} */ (
+  Data.TaggedError("RunNotFound")
+);
+
+export class RunNotFound extends RunNotFoundBase {}

package/src/SmithersError.js

@@ -0,0 +1,55 @@
+import { getSmithersErrorDocsUrl } from "./getSmithersErrorDocsUrl.js";
+/** @typedef {import("./SmithersErrorCode.ts").SmithersErrorCode} SmithersErrorCode */
+/** @typedef {import("./SmithersErrorOptions.ts").SmithersErrorOptions} SmithersErrorOptions */
+
+/**
+ * @param {string} message
+ * @param {string} docsUrl
+ * @returns {string}
+ */
+function formatSmithersErrorMessage(message, docsUrl) {
+    if (message.includes(docsUrl))
+        return message;
+    return `${message} See ${docsUrl}`;
+}
+export class SmithersError extends Error {
+    /** @type {SmithersErrorCode} */
+    code;
+    /** @type {string} */
+    summary;
+    /** @type {string} */
+    docsUrl;
+    /** @type {Record<string, unknown> | undefined} */
+    details;
+    /** @type {unknown} */
+    cause;
+    /** @type {string} */
+    name;
+    /**
+   * @param {SmithersErrorCode} code
+   * @param {string} summary
+   * @param {Record<string, unknown>} [details]
+   * @param {unknown | SmithersErrorOptions} [causeOrOptions]
+   */
+    constructor(code, summary, details, causeOrOptions) {
+        const docsUrl = getSmithersErrorDocsUrl(code);
+        const isOptionsObject = causeOrOptions &&
+            typeof causeOrOptions === "object" &&
+            (Object.prototype.hasOwnProperty.call(causeOrOptions, "cause") ||
+                Object.prototype.hasOwnProperty.call(causeOrOptions, "includeDocsUrl") ||
+                Object.prototype.hasOwnProperty.call(causeOrOptions, "name"));
+        const options = /** @type {SmithersErrorOptions} */ (isOptionsObject
+            ? causeOrOptions
+            : { cause: causeOrOptions });
+        super(options.includeDocsUrl === false
+            ? summary
+            : formatSmithersErrorMessage(summary, docsUrl), { cause: options.cause });
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = options.name ?? "SmithersError";
+        this.code = code;
+        this.summary = summary;
+        this.docsUrl = docsUrl;
+        this.details = details;
+        this.cause = options.cause;
+    }
+}

package/src/SmithersErrorCategory.ts

@@ -0,0 +1,11 @@
+export type SmithersErrorCategory =
+  | "engine"
+  | "components"
+  | "tools"
+  | "agents"
+  | "database"
+  | "effect"
+  | "hot"
+  | "scorers"
+  | "cli"
+  | "integrations";

package/src/SmithersErrorCode.ts

@@ -0,0 +1,3 @@
+import type { KnownSmithersErrorCode } from "./KnownSmithersErrorCode.ts";
+
+export type SmithersErrorCode = KnownSmithersErrorCode | (string & {});

package/src/SmithersErrorDefinition.ts

@@ -0,0 +1,7 @@
+import type { SmithersErrorCategory } from "./SmithersErrorCategory.ts";
+
+export type SmithersErrorDefinition = {
+  readonly category: SmithersErrorCategory;
+  readonly when: string;
+  readonly details?: string;
+};

package/src/SmithersErrorOptions.ts

@@ -0,0 +1,5 @@
+export type SmithersErrorOptions = {
+  readonly cause?: unknown;
+  readonly includeDocsUrl?: boolean;
+  readonly name?: string;
+};

package/src/SmithersTaggedError.ts

@@ -0,0 +1,18 @@
+import type { TaskAborted } from "./TaskAborted.ts";
+import type { TaskTimeout } from "./TaskTimeout.ts";
+import type { TaskHeartbeatTimeout } from "./TaskHeartbeatTimeout.ts";
+import type { RunNotFound } from "./RunNotFound.ts";
+import type { InvalidInput } from "./InvalidInput.ts";
+import type { DbWriteFailed } from "./DbWriteFailed.ts";
+import type { AgentCliError } from "./AgentCliError.ts";
+import type { WorkflowFailed } from "./WorkflowFailed.ts";
+
+export type SmithersTaggedError =
+  | TaskAborted
+  | TaskTimeout
+  | TaskHeartbeatTimeout
+  | RunNotFound
+  | InvalidInput
+  | DbWriteFailed
+  | AgentCliError
+  | WorkflowFailed;

package/src/SmithersTaggedErrorPayload.ts

@@ -0,0 +1,52 @@
+import type { TaggedErrorDetails } from "./TaggedErrorDetails.ts";
+
+export type SmithersTaggedErrorPayload =
+  | {
+      readonly _tag: "TaskAborted";
+      readonly message: string;
+      readonly details?: TaggedErrorDetails;
+      readonly name?: string;
+    }
+  | {
+      readonly _tag: "TaskTimeout";
+      readonly message: string;
+      readonly nodeId: string;
+      readonly attempt: number;
+      readonly timeoutMs: number;
+    }
+  | {
+      readonly _tag: "TaskHeartbeatTimeout";
+      readonly message: string;
+      readonly nodeId: string;
+      readonly iteration: number;
+      readonly attempt: number;
+      readonly timeoutMs: number;
+      readonly staleForMs: number;
+      readonly lastHeartbeatAtMs: number;
+    }
+  | {
+      readonly _tag: "RunNotFound";
+      readonly message: string;
+      readonly runId: string;
+    }
+  | {
+      readonly _tag: "InvalidInput";
+      readonly message: string;
+      readonly details?: TaggedErrorDetails;
+    }
+  | {
+      readonly _tag: "DbWriteFailed";
+      readonly message: string;
+      readonly details?: TaggedErrorDetails;
+    }
+  | {
+      readonly _tag: "AgentCliError";
+      readonly message: string;
+      readonly details?: TaggedErrorDetails;
+    }
+  | {
+      readonly _tag: "WorkflowFailed";
+      readonly message: string;
+      readonly details?: TaggedErrorDetails;
+      readonly status?: number;
+    };

package/src/SmithersTaggedErrorTag.ts

@@ -0,0 +1,3 @@
+import type { smithersTaggedErrorCodes } from "./smithersTaggedErrorCodes.ts";
+
+export type SmithersTaggedErrorTag = keyof typeof smithersTaggedErrorCodes;

package/src/TaggedErrorDetails.ts

@@ -0,0 +1,6 @@
+export type TaggedErrorDetails = Record<string, unknown>;
+
+export type GenericTaggedErrorArgs = {
+  readonly message: string;
+  readonly details?: TaggedErrorDetails;
+};

package/src/TaskAborted.js

@@ -0,0 +1,17 @@
+import { Data } from "effect";
+
+/** @typedef {import("./TaggedErrorDetails.ts").TaggedErrorDetails} TaggedErrorDetails */
+
+/**
+ * @typedef {{
+ *   readonly message: string;
+ *   readonly details?: TaggedErrorDetails;
+ *   readonly name?: string;
+ * }} TaskAbortedArgs
+ */
+
+const TaskAbortedBase = /** @type {new (args: TaskAbortedArgs) => import("effect/Cause").YieldableError & { readonly _tag: "TaskAborted" } & Readonly<TaskAbortedArgs>} */ (
+  Data.TaggedError("TaskAborted")
+);
+
+export class TaskAborted extends TaskAbortedBase {}

package/src/TaskHeartbeatTimeout.js

@@ -0,0 +1,19 @@
+import { Data } from "effect";
+
+/**
+ * @typedef {{
+ *   readonly message: string;
+ *   readonly nodeId: string;
+ *   readonly iteration: number;
+ *   readonly attempt: number;
+ *   readonly timeoutMs: number;
+ *   readonly staleForMs: number;
+ *   readonly lastHeartbeatAtMs: number;
+ * }} TaskHeartbeatTimeoutArgs
+ */
+
+const TaskHeartbeatTimeoutBase = /** @type {new (args: TaskHeartbeatTimeoutArgs) => import("effect/Cause").YieldableError & { readonly _tag: "TaskHeartbeatTimeout" } & Readonly<TaskHeartbeatTimeoutArgs>} */ (
+  Data.TaggedError("TaskHeartbeatTimeout")
+);
+
+export class TaskHeartbeatTimeout extends TaskHeartbeatTimeoutBase {}

package/src/TaskTimeout.js

@@ -0,0 +1,16 @@
+import { Data } from "effect";
+
+/**
+ * @typedef {{
+ *   readonly message: string;
+ *   readonly nodeId: string;
+ *   readonly attempt: number;
+ *   readonly timeoutMs: number;
+ * }} TaskTimeoutArgs
+ */
+
+const TaskTimeoutBase = /** @type {new (args: TaskTimeoutArgs) => import("effect/Cause").YieldableError & { readonly _tag: "TaskTimeout" } & Readonly<TaskTimeoutArgs>} */ (
+  Data.TaggedError("TaskTimeout")
+);
+
+export class TaskTimeout extends TaskTimeoutBase {}

package/src/WorkflowFailed.js

@@ -0,0 +1,15 @@
+import { Data } from "effect";
+
+/** @typedef {import("./TaggedErrorDetails.ts").GenericTaggedErrorArgs} GenericTaggedErrorArgs */
+
+/**
+ * @typedef {GenericTaggedErrorArgs & {
+ *   readonly status?: number;
+ * }} WorkflowFailedArgs
+ */
+
+const WorkflowFailedBase = /** @type {new (args: WorkflowFailedArgs) => import("effect/Cause").YieldableError & { readonly _tag: "WorkflowFailed" } & Readonly<WorkflowFailedArgs>} */ (
+  Data.TaggedError("WorkflowFailed")
+);
+
+export class WorkflowFailed extends WorkflowFailedBase {}

package/src/errorToJson.js

@@ -0,0 +1,35 @@
+import { SmithersError } from "./SmithersError.js";
+import { fromTaggedError } from "./fromTaggedError.js";
+/**
+ * @param {unknown} error
+ * @returns {Record<string, unknown>}
+ */
+export function errorToJson(error) {
+    const taggedError = fromTaggedError(error);
+    if (taggedError) {
+        return errorToJson(taggedError);
+    }
+    if (error instanceof SmithersError) {
+        return {
+            name: error.name,
+            code: error.code,
+            message: error.message,
+            stack: error.stack,
+            cause: error.cause,
+            summary: error.summary,
+            docsUrl: error.docsUrl,
+            details: error.details,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+    }
+    if (error && typeof error === "object") {
+        return error;
+    }
+    return { message: String(error) };
+}

package/src/fromTaggedError.js

@@ -0,0 +1,63 @@
+import { SmithersError } from "./SmithersError.js";
+/**
+ * @param {unknown} value
+ * @returns {TaggedErrorPayload | undefined}
+ */
+function objectPayload(value) {
+    return value && typeof value === "object"
+        ? value
+        : undefined;
+}
+/**
+ * @param {unknown} error
+ * @returns {SmithersError | undefined}
+ */
+export function fromTaggedError(error) {
+    const payload = objectPayload(error);
+    if (!payload || typeof payload._tag !== "string")
+        return undefined;
+    const message = typeof payload.message === "string" ? payload.message : String(payload._tag);
+    const cause = error && typeof error === "object" && "cause" in error
+        ? error.cause
+        : undefined;
+    const details = payload.details && typeof payload.details === "object" && !Array.isArray(payload.details)
+        ? payload.details
+        : undefined;
+    switch (payload._tag) {
+        case "TaskAborted":
+            return new SmithersError("TASK_ABORTED", message, details, {
+                cause,
+                name: typeof payload.name === "string" ? payload.name : undefined,
+            });
+        case "TaskTimeout":
+            return new SmithersError("TASK_TIMEOUT", message, {
+                nodeId: payload.nodeId,
+                attempt: payload.attempt,
+                timeoutMs: payload.timeoutMs,
+            }, { cause });
+        case "TaskHeartbeatTimeout":
+            return new SmithersError("TASK_HEARTBEAT_TIMEOUT", message, {
+                nodeId: payload.nodeId,
+                iteration: payload.iteration,
+                attempt: payload.attempt,
+                timeoutMs: payload.timeoutMs,
+                staleForMs: payload.staleForMs,
+                lastHeartbeatAtMs: payload.lastHeartbeatAtMs,
+            }, { cause });
+        case "RunNotFound":
+            return new SmithersError("RUN_NOT_FOUND", message, { runId: payload.runId }, { cause });
+        case "InvalidInput":
+            return new SmithersError("INVALID_INPUT", message, details, { cause });
+        case "DbWriteFailed":
+            return new SmithersError("DB_WRITE_FAILED", message, details, { cause });
+        case "AgentCliError":
+            return new SmithersError("AGENT_CLI_ERROR", message, details, { cause });
+        case "WorkflowFailed":
+            return new SmithersError("WORKFLOW_EXECUTION_FAILED", message, {
+                ...details,
+                ...(payload.status === undefined ? {} : { status: payload.status }),
+            }, { cause });
+        default:
+            return undefined;
+    }
+}

package/src/fromTaggedErrorPayload.js

@@ -0,0 +1,68 @@
+import { TaskAborted } from "./TaskAborted.js";
+import { TaskTimeout } from "./TaskTimeout.js";
+import { TaskHeartbeatTimeout } from "./TaskHeartbeatTimeout.js";
+import { RunNotFound } from "./RunNotFound.js";
+import { InvalidInput } from "./InvalidInput.js";
+import { DbWriteFailed } from "./DbWriteFailed.js";
+import { AgentCliError } from "./AgentCliError.js";
+import { WorkflowFailed } from "./WorkflowFailed.js";
+/** @typedef {import("./SmithersTaggedError.ts").SmithersTaggedError} SmithersTaggedError */
+/** @typedef {import("./SmithersTaggedErrorPayload.ts").SmithersTaggedErrorPayload} SmithersTaggedErrorPayload */
+
+/**
+ * @param {SmithersTaggedErrorPayload} payload
+ * @returns {SmithersTaggedError}
+ */
+export function fromTaggedErrorPayload(payload) {
+    switch (payload._tag) {
+        case "TaskAborted":
+            return new TaskAborted({
+                message: payload.message,
+                details: payload.details,
+                name: payload.name,
+            });
+        case "TaskTimeout":
+            return new TaskTimeout({
+                message: payload.message,
+                nodeId: payload.nodeId,
+                attempt: payload.attempt,
+                timeoutMs: payload.timeoutMs,
+            });
+        case "TaskHeartbeatTimeout":
+            return new TaskHeartbeatTimeout({
+                message: payload.message,
+                nodeId: payload.nodeId,
+                iteration: payload.iteration,
+                attempt: payload.attempt,
+                timeoutMs: payload.timeoutMs,
+                staleForMs: payload.staleForMs,
+                lastHeartbeatAtMs: payload.lastHeartbeatAtMs,
+            });
+        case "RunNotFound":
+            return new RunNotFound({
+                message: payload.message,
+                runId: payload.runId,
+            });
+        case "InvalidInput":
+            return new InvalidInput({
+                message: payload.message,
+                details: payload.details,
+            });
+        case "DbWriteFailed":
+            return new DbWriteFailed({
+                message: payload.message,
+                details: payload.details,
+            });
+        case "AgentCliError":
+            return new AgentCliError({
+                message: payload.message,
+                details: payload.details,
+            });
+        case "WorkflowFailed":
+            return new WorkflowFailed({
+                message: payload.message,
+                details: payload.details,
+                status: payload.status,
+            });
+    }
+}

package/src/getSmithersErrorDefinition.js

@@ -0,0 +1,14 @@
+import { smithersErrorDefinitions } from "./smithersErrorDefinitions.js";
+import { isKnownSmithersErrorCode } from "./isKnownSmithersErrorCode.js";
+/** @typedef {import("./SmithersErrorCode.ts").SmithersErrorCode} SmithersErrorCode */
+/** @typedef {import("./SmithersErrorDefinition.ts").SmithersErrorDefinition} SmithersErrorDefinition */
+
+/**
+ * @param {SmithersErrorCode} code
+ * @returns {SmithersErrorDefinition | undefined}
+ */
+export function getSmithersErrorDefinition(code) {
+    if (!isKnownSmithersErrorCode(code))
+        return undefined;
+    return smithersErrorDefinitions[code];
+}

package/src/getSmithersErrorDocsUrl.js

@@ -0,0 +1,10 @@
+import { ERROR_REFERENCE_URL } from "./ERROR_REFERENCE_URL.js";
+/** @typedef {import("./SmithersErrorCode.ts").SmithersErrorCode} SmithersErrorCode */
+
+/**
+ * @param {SmithersErrorCode} _code
+ * @returns {string}
+ */
+export function getSmithersErrorDocsUrl(_code) {
+    return ERROR_REFERENCE_URL;
+}