@smithers-orchestrator/errors 0.24.2 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/errors",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "Error types, tagged errors, and error utilities for Smithers",
   "type": "module",
   "sideEffects": false,

package/src/assertZodV4.js

@@ -0,0 +1,45 @@
+import { SmithersError } from "./SmithersError.js";
+
+/**
+ * Assert that a user-supplied schema is a Zod v4 schema, failing fast and clearly
+ * when it is a Zod v3 (or otherwise pre-v4) schema.
+ *
+ * smithers introspects schemas through Zod v4 runtime internals (`schema._zod`)
+ * and the v4-only static `z.toJSONSchema()`. A Zod v3 schema has no `_zod`, so
+ * without this guard it would (a) silently degrade every output column to a JSON
+ * text column in `zodToTable` (optional chaining swallows the missing `_zod`),
+ * then (b) detonate later, deep inside `z.toJSONSchema`, with the cryptic
+ * `undefined is not an object (evaluating 'schema._zod.def')`. This converts both
+ * failure modes into one actionable error at the earliest boundary — workflow
+ * construction.
+ *
+ * Detection signal: every Zod v4 schema instance carries
+ * `schema._zod.version.major === 4`; Zod v3 schemas have no `_zod` at all.
+ *
+ * @param {unknown} schema - the candidate schema
+ * @param {string} [where] - name of the schema (e.g. an output key) for the message
+ * @returns {void}
+ */
+export function assertZodV4(schema, where) {
+    if (!schema || typeof schema !== "object")
+        return;
+    const internal = /** @type {{ _zod?: { version?: { major?: number } } }} */ (schema);
+    // Zod v4 fast-path: accept and return. Verified robust across object/string/
+    // array/union/enum/optional plus refine/transform/pipe/lazy/brand/coerce —
+    // every v4 schema instance carries _zod.version.major === 4.
+    if (internal._zod?.version?.major === 4)
+        return;
+    // Only error on things that are recognizably a Zod schema, so a plain config
+    // object that happens to flow through here is never rejected. NOTE: this is
+    // purely an "is this Zod-shaped at all" gate — Zod v4 schemas ALSO carry
+    // `_def`/`parse`, so this clause does NOT discriminate the version; the
+    // `_zod.version` check above is the version discriminator.
+    const candidate = /** @type {{ parse?: unknown }} */ (schema);
+    const looksLikeZod = typeof candidate.parse === "function" || "_def" in schema || "shape" in schema;
+    if (!looksLikeZod)
+        return;
+    const target = where ? ` for "${where}"` : "";
+    throw new SmithersError("INVALID_INPUT", `smithers requires Zod v4 schemas${target}, but received what looks like a Zod v3 (or pre-v4) schema. ` +
+        `Upgrade your project to "zod": "^4" and import schemas from "zod". ` +
+        `smithers reads Zod v4 internals (schema._zod) and uses z.toJSONSchema(), neither of which exists on a Zod v3 schema.`, where ? { schema: where } : undefined);
+}

package/src/errorToJson.js

@@ -1,13 +1,100 @@
+import { EngineError } from "./EngineError.js";
 import { SmithersError } from "./SmithersError.js";
 import { fromTaggedError } from "./fromTaggedError.js";
+/**
+ * Deeply convert a value into a structure that `JSON.stringify` can never throw
+ * on. `errorToJson` output is fed straight into `JSON.stringify` on the engine's
+ * durable failed-task write path, so a circular `cause`, a `BigInt` detail, or a
+ * throwing getter must not be able to crash the error-recording code.
+ *
+ * @param {unknown} value
+ * @param {WeakSet<object>} seen
+ * @returns {unknown}
+ */
+function toJsonSafe(value, seen) {
+    if (value === null)
+        return null;
+    const type = typeof value;
+    if (type === "string" || type === "boolean")
+        return value;
+    if (type === "number")
+        return Number.isFinite(value) ? value : null;
+    if (type === "bigint")
+        return value.toString();
+    if (type === "undefined" || type === "function" || type === "symbol")
+        return undefined;
+    // value is an object at this point.
+    const obj = /** @type {object} */ (value);
+    if (seen.has(obj))
+        return "[Circular]";
+    seen.add(obj);
+    try {
+        if (obj instanceof Error) {
+            /** @type {Record<string, unknown>} */
+            const out = {
+                name: obj.name,
+                message: obj.message,
+                stack: obj.stack,
+            };
+            if (obj.cause !== undefined)
+                out.cause = toJsonSafe(obj.cause, seen);
+            for (const key of Object.keys(obj)) {
+                if (key in out)
+                    continue;
+                let raw;
+                try {
+                    raw = /** @type {Record<string, unknown>} */ (obj)[key];
+                }
+                catch {
+                    continue;
+                }
+                const safe = toJsonSafe(raw, seen);
+                if (safe !== undefined)
+                    out[key] = safe;
+            }
+            return out;
+        }
+        if (Array.isArray(obj)) {
+            return obj.map((item) => {
+                const safe = toJsonSafe(item, seen);
+                return safe === undefined ? null : safe;
+            });
+        }
+        /** @type {Record<string, unknown>} */
+        const out = {};
+        for (const key of Object.keys(obj)) {
+            let raw;
+            try {
+                raw = /** @type {Record<string, unknown>} */ (obj)[key];
+            }
+            catch {
+                continue;
+            }
+            const safe = toJsonSafe(raw, seen);
+            if (safe !== undefined)
+                out[key] = safe;
+        }
+        return out;
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
 /**
  * @param {unknown} error
  * @returns {Record<string, unknown>}
  */
 export function errorToJson(error) {
+    return /** @type {Record<string, unknown>} */ (toJsonSafe(buildErrorJson(error), new WeakSet()));
+}
+/**
+ * @param {unknown} error
+ * @returns {Record<string, unknown>}
+ */
+function buildErrorJson(error) {
     const taggedError = fromTaggedError(error);
     if (taggedError) {
-        return errorToJson(taggedError);
+        return buildErrorJson(taggedError);
     }
     if (error instanceof SmithersError) {
         return {
@@ -21,6 +108,17 @@ export function errorToJson(error) {
             details: error.details,
         };
     }
+    if (error instanceof EngineError) {
+        return {
+            name: error.name,
+            code: error.code,
+            message: error.message,
+            stack: error.stack,
+            cause: error.cause,
+            summary: error.message,
+            details: error.context,
+        };
+    }
     if (error instanceof Error) {
         return {
             name: error.name,

package/src/index.d.ts

@@ -232,6 +232,31 @@ declare namespace smithersErrorDefinitions {
         let details_4: string;
         export { details_4 as details };
     }
+    namespace TASK_HIJACK_UNSUPPORTED {
+        let category: string;
+        let when: string;
+        let details: string;
+    }
+    namespace TASK_FORK_SOURCE_NOT_FOUND {
+        let category: string;
+        let when: string;
+        let details: string;
+    }
+    namespace TASK_FORK_SOURCE_NOT_COMPLETE {
+        let category: string;
+        let when: string;
+        let details: string;
+    }
+    namespace TASK_FORK_SESSION_UNAVAILABLE {
+        let category: string;
+        let when: string;
+        let details: string;
+    }
+    namespace TASK_FORK_CYCLE {
+        let category: string;
+        let when: string;
+        let details: string;
+    }
     namespace RUN_NOT_FOUND {
         let category_11: string;
         export { category_11 as category };
@@ -570,6 +595,16 @@ declare namespace smithersErrorDefinitions {
         let when_58: string;
         export { when_58 as when };
     }
+    namespace AGENT_CONFIG_INVALID {
+        let category: string;
+        let when: string;
+    }
+    namespace AGENT_QUOTA_EXCEEDED {
+        let category_90: string;
+        export { category_90 as category };
+        let when_90: string;
+        export { when_90 as when };
+    }
     namespace AGENT_RPC_FILE_ARGS {
         let category_59: string;
         export { category_59 as category };
@@ -588,161 +623,193 @@ declare namespace smithersErrorDefinitions {
         let when_61: string;
         export { when_61 as when };
     }
-    namespace DB_MISSING_COLUMNS {
+    namespace ACCOUNT_INVALID {
         let category_62: string;
         export { category_62 as category };
         let when_62: string;
         export { when_62 as when };
     }
-    namespace DB_REQUIRES_BUN_SQLITE {
+    namespace ACCOUNT_NOT_FOUND {
         let category_63: string;
         export { category_63 as category };
         let when_63: string;
         export { when_63 as when };
     }
-    namespace DB_QUERY_FAILED {
+    namespace ACCOUNT_DUPLICATE_LABEL {
         let category_64: string;
         export { category_64 as category };
         let when_64: string;
         export { when_64 as when };
     }
-    namespace DB_WRITE_FAILED {
+    namespace ACCOUNTS_FILE_INVALID {
         let category_65: string;
         export { category_65 as category };
         let when_65: string;
         export { when_65 as when };
     }
-    namespace STORAGE_ERROR {
+    namespace DB_MISSING_COLUMNS {
         let category_66: string;
         export { category_66 as category };
         let when_66: string;
         export { when_66 as when };
     }
-    namespace INTERNAL_ERROR {
+    namespace DB_REQUIRES_BUN_SQLITE {
         let category_67: string;
         export { category_67 as category };
         let when_67: string;
         export { when_67 as when };
     }
-    namespace PROCESS_ABORTED {
+    namespace DB_QUERY_FAILED {
         let category_68: string;
         export { category_68 as category };
         let when_68: string;
         export { when_68 as when };
-        let details_30: string;
-        export { details_30 as details };
     }
-    namespace PROCESS_TIMEOUT {
+    namespace DB_WRITE_FAILED {
         let category_69: string;
         export { category_69 as category };
         let when_69: string;
         export { when_69 as when };
-        let details_31: string;
-        export { details_31 as details };
     }
-    namespace PROCESS_IDLE_TIMEOUT {
+    namespace SMITHERS_MIGRATION_REQUIRED {
+        let category_mig: string;
+        export { category_mig as category };
+        let when_mig: string;
+        export { when_mig as when };
+        let details_mig: string;
+        export { details_mig as details };
+    }
+    namespace STORAGE_ERROR {
         let category_70: string;
         export { category_70 as category };
         let when_70: string;
         export { when_70 as when };
-        let details_32: string;
-        export { details_32 as details };
     }
-    namespace PROCESS_SPAWN_FAILED {
+    namespace INTERNAL_ERROR {
         let category_71: string;
         export { category_71 as category };
         let when_71: string;
         export { when_71 as when };
-        let details_33: string;
-        export { details_33 as details };
     }
-    namespace TASK_RUNTIME_UNAVAILABLE {
+    namespace PROCESS_ABORTED {
         let category_72: string;
         export { category_72 as category };
         let when_72: string;
         export { when_72 as when };
+        let details_30: string;
+        export { details_30 as details };
     }
-    namespace SCHEMA_CHANGE_HOT {
+    namespace PROCESS_TIMEOUT {
         let category_73: string;
         export { category_73 as category };
         let when_73: string;
         export { when_73 as when };
+        let details_31: string;
+        export { details_31 as details };
     }
-    namespace HOT_OVERLAY_FAILED {
+    namespace PROCESS_IDLE_TIMEOUT {
         let category_74: string;
         export { category_74 as category };
         let when_74: string;
         export { when_74 as when };
+        let details_32: string;
+        export { details_32 as details };
     }
-    namespace HOT_RELOAD_INVALID_MODULE {
+    namespace PROCESS_SPAWN_FAILED {
         let category_75: string;
         export { category_75 as category };
         let when_75: string;
         export { when_75 as when };
+        let details_33: string;
+        export { details_33 as details };
     }
-    namespace SCORER_FAILED {
+    namespace TASK_RUNTIME_UNAVAILABLE {
         let category_76: string;
         export { category_76 as category };
         let when_76: string;
         export { when_76 as when };
     }
-    namespace WORKFLOW_EXISTS {
+    namespace SCHEMA_CHANGE_HOT {
         let category_77: string;
         export { category_77 as category };
         let when_77: string;
         export { when_77 as when };
     }
-    namespace CLI_DB_NOT_FOUND {
+    namespace HOT_OVERLAY_FAILED {
         let category_78: string;
         export { category_78 as category };
         let when_78: string;
         export { when_78 as when };
     }
-    namespace CLI_AGENT_UNSUPPORTED {
+    namespace HOT_RELOAD_INVALID_MODULE {
         let category_79: string;
         export { category_79 as category };
         let when_79: string;
         export { when_79 as when };
     }
-    namespace PI_HTTP_ERROR {
+    namespace SCORER_FAILED {
         let category_80: string;
         export { category_80 as category };
         let when_80: string;
         export { when_80 as when };
     }
-    namespace EXTERNAL_BUILD_FAILED {
+    namespace WORKFLOW_EXISTS {
         let category_81: string;
         export { category_81 as category };
         let when_81: string;
         export { when_81 as when };
-        let details_34: string;
-        export { details_34 as details };
     }
-    namespace SCHEMA_DISCOVERY_FAILED {
+    namespace CLI_DB_NOT_FOUND {
         let category_82: string;
         export { category_82 as category };
         let when_82: string;
         export { when_82 as when };
-        let details_35: string;
-        export { details_35 as details };
     }
-    namespace OPENAPI_SPEC_LOAD_FAILED {
+    namespace CLI_AGENT_UNSUPPORTED {
         let category_83: string;
         export { category_83 as category };
         let when_83: string;
         export { when_83 as when };
     }
-    namespace OPENAPI_OPERATION_NOT_FOUND {
+    namespace PI_HTTP_ERROR {
         let category_84: string;
         export { category_84 as category };
         let when_84: string;
         export { when_84 as when };
     }
-    namespace OPENAPI_TOOL_EXECUTION_FAILED {
+    namespace EXTERNAL_BUILD_FAILED {
         let category_85: string;
         export { category_85 as category };
         let when_85: string;
         export { when_85 as when };
+        let details_34: string;
+        export { details_34 as details };
+    }
+    namespace SCHEMA_DISCOVERY_FAILED {
+        let category_86: string;
+        export { category_86 as category };
+        let when_86: string;
+        export { when_86 as when };
+        let details_35: string;
+        export { details_35 as details };
+    }
+    namespace OPENAPI_SPEC_LOAD_FAILED {
+        let category_87: string;
+        export { category_87 as category };
+        let when_87: string;
+        export { when_87 as when };
+    }
+    namespace OPENAPI_OPERATION_NOT_FOUND {
+        let category_88: string;
+        export { category_88 as category };
+        let when_88: string;
+        export { when_88 as when };
+    }
+    namespace OPENAPI_TOOL_EXECUTION_FAILED {
+        let category_89: string;
+        export { category_89 as category };
+        let when_89: string;
+        export { when_89 as when };
     }
 }
 

package/src/index.js

@@ -14,6 +14,7 @@
 // @smithers-type-exports-end
 
 export * from "./AgentCliError.js";
+export * from "./assertZodV4.js";
 export * from "./DbWriteFailed.js";
 export * from "./EngineError.js";
 export * from "./ERROR_REFERENCE_URL.js";

package/src/isSmithersError.js

@@ -1,4 +1,3 @@
-import { isKnownSmithersErrorCode } from "./isKnownSmithersErrorCode.js";
 import { SmithersError } from "./SmithersError.js";
 /** @typedef {import("./SmithersError.js").SmithersError} SmithersError */
 /**
@@ -6,13 +5,5 @@ import { SmithersError } from "./SmithersError.js";
  * @returns {value is SmithersError}
  */
 export function isSmithersError(value) {
-    if (value instanceof SmithersError) {
-        return true;
-    }
-    return Boolean(value &&
-        typeof value === "object" &&
-        "code" in value &&
-        typeof (/** @type {{ code?: unknown }} */ (value).code) === "string" &&
-        isKnownSmithersErrorCode(/** @type {{ code: string }} */ (value).code) &&
-        "message" in value);
+    return value instanceof SmithersError;
 }

package/src/smithersErrorDefinitions.js

@@ -13,7 +13,7 @@ export const smithersErrorDefinitions = {
     },
     RESUME_METADATA_MISMATCH: {
         category: "engine",
-        when: "Stored run metadata no longer matches the workflow being resumed.",
+        when: "Stored run metadata no longer matches the workflow being resumed. Editing the workflow entry file or an imported module between stop and resume triggers this (resume hashes file content, not git); fork/replay onto the edit or start a fresh run instead of resuming.",
     },
     UNKNOWN_OUTPUT_SCHEMA: {
         category: "engine",
@@ -290,6 +290,11 @@ export const smithersErrorDefinitions = {
         category: "agents",
         when: "A CLI-backed agent exits unsuccessfully, streams an explicit error, or its RPC transport fails.",
     },
+    AGENT_QUOTA_EXCEEDED: {
+        category: "agents",
+        when: "An agent provider returns a usage-limit or quota error. The failure is transient; retries are preserved and the run pauses until the reset time.",
+        details: "{ agentId?, agentEngine?, agentModel?, quotaResetAtMs?, resetHint? }",
+    },
     AGENT_CONFIG_INVALID: {
         category: "agents",
         when: "A CLI-backed agent fails with a non-retryable configuration error (e.g. unknown model, missing LLM, unsupported model). Includes agent id, engine and model in details so the offending entry in .smithers/agents.ts can be located.",
@@ -306,6 +311,22 @@ export const smithersErrorDefinitions = {
         category: "agents",
         when: "An internal agent diagnostic check exceeds the per-check timeout budget.",
     },
+    ACCOUNT_INVALID: {
+        category: "integrations",
+        when: "An account entry, label, provider, or provider-specific configuration is invalid.",
+    },
+    ACCOUNT_NOT_FOUND: {
+        category: "integrations",
+        when: "An account operation references a label that is not registered.",
+    },
+    ACCOUNT_DUPLICATE_LABEL: {
+        category: "integrations",
+        when: "An account add operation would create a duplicate label without replace enabled.",
+    },
+    ACCOUNTS_FILE_INVALID: {
+        category: "integrations",
+        when: "The accounts.json file is not valid JSON or does not match the expected account registry schema.",
+    },
     DB_MISSING_COLUMNS: {
         category: "database",
         when: "A table used by Smithers does not expose required columns such as runId or nodeId.",
@@ -322,6 +343,11 @@ export const smithersErrorDefinitions = {
         category: "database",
         when: "A database write or migration fails, including after SQLite retry exhaustion.",
     },
+    SMITHERS_MIGRATION_REQUIRED: {
+        category: "cli",
+        when: "A legacy SQLite store holds run data but the resolved backend is pglite/postgres with no migrated.json, or the store schema version is unsatisfiable in place.",
+        details: "{ dbPath, runCount, schemaVersion, resolvedBackend }",
+    },
     STORAGE_ERROR: {
         category: "database",
         when: "A storage service operation fails before surfacing a more specific database code.",

package/src/toTaggedErrorPayload.js

@@ -10,6 +10,20 @@ import { isSmithersTaggedError } from "./isSmithersTaggedError.js";
 function isRecord(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
+/**
+ * Coerce a value to a finite number. The payload type contract requires these
+ * fields to be `number`, but `Number(undefined)` is `NaN`, which `JSON.stringify`
+ * silently turns into `null` — corrupting the value that retry/backoff logic
+ * reads back after a durable round-trip. Fall back to a defined finite value.
+ *
+ * @param {unknown} value
+ * @param {number} [fallback]
+ * @returns {number}
+ */
+function toFiniteNumber(value, fallback = 0) {
+    const num = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(num) ? num : fallback;
+}
 /**
  * @param {unknown} error
  * @returns {SmithersTaggedErrorPayload | undefined}
@@ -33,19 +47,19 @@ export function toTaggedErrorPayload(error) {
                 _tag: "TaskTimeout",
                 message: String(error.message),
                 nodeId: String(error.nodeId),
-                attempt: Number(error.attempt),
-                timeoutMs: Number(error.timeoutMs),
+                attempt: toFiniteNumber(error.attempt),
+                timeoutMs: toFiniteNumber(error.timeoutMs),
             };
         case "TaskHeartbeatTimeout":
             return {
                 _tag: "TaskHeartbeatTimeout",
                 message: String(error.message),
                 nodeId: String(error.nodeId),
-                iteration: Number(error.iteration),
-                attempt: Number(error.attempt),
-                timeoutMs: Number(error.timeoutMs),
-                staleForMs: Number(error.staleForMs),
-                lastHeartbeatAtMs: Number(error.lastHeartbeatAtMs),
+                iteration: toFiniteNumber(error.iteration),
+                attempt: toFiniteNumber(error.attempt),
+                timeoutMs: toFiniteNumber(error.timeoutMs),
+                staleForMs: toFiniteNumber(error.staleForMs),
+                lastHeartbeatAtMs: toFiniteNumber(error.lastHeartbeatAtMs),
             };
         case "RunNotFound":
             return {

package/src/tagged.js

@@ -1,24 +0,0 @@
-// @smithers-type-exports-begin
-/** @typedef {import("./EngineErrorCode.ts").EngineErrorCode} EngineErrorCode */
-/** @typedef {import("./TaggedErrorDetails.ts").GenericTaggedErrorArgs} GenericTaggedErrorArgs */
-/** @typedef {import("./SmithersTaggedError.ts").SmithersTaggedError} SmithersTaggedError */
-/** @typedef {import("./SmithersTaggedErrorPayload.ts").SmithersTaggedErrorPayload} SmithersTaggedErrorPayload */
-/** @typedef {import("./SmithersTaggedErrorTag.ts").SmithersTaggedErrorTag} SmithersTaggedErrorTag */
-/** @typedef {import("./TaggedErrorDetails.ts").TaggedErrorDetails} TaggedErrorDetails */
-// @smithers-type-exports-end
-
-export * from "./AgentCliError.js";
-export * from "./DbWriteFailed.js";
-export * from "./EngineError.js";
-export * from "./InvalidInput.js";
-export * from "./RunNotFound.js";
-export * from "./TaskAborted.js";
-export * from "./TaskHeartbeatTimeout.js";
-export * from "./TaskTimeout.js";
-export * from "./WorkflowFailed.js";
-export * from "./fromTaggedError.js";
-export * from "./fromTaggedErrorPayload.js";
-export * from "./isSmithersTaggedError.js";
-export * from "./isSmithersTaggedErrorTag.js";
-export * from "./smithersTaggedErrorCodes.js";
-export * from "./toTaggedErrorPayload.js";