@crewhaus/errors 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export declare class CompilerError extends CrewhausError {
     constructor(message: string, cause?: unknown);
 }
 export declare class RuntimeError extends CrewhausError {
-    readonly name = "RuntimeError";
+    readonly name: string;
     constructor(message: string, cause?: unknown);
 }
 export declare class ConfigError extends CrewhausError {
@@ -69,3 +69,95 @@ export declare class ProviderAuthError extends AdapterError {
     readonly name = "ProviderAuthError";
     constructor(providerId: string, message: string, cause?: unknown);
 }
+/**
+ * Terminal failure classes a run can die with. Broader than `ErrorCode`
+ * (which tags where an error was raised): a `FailureClass` tags *why the run
+ * stopped*, in end-user vocabulary, and maps 1:1 onto an exit code.
+ */
+export type FailureClass = "billing" | "auth" | "rate_limit" | "crewhaus_budget" | "mcp_boot" | "context_overflow" | "spec" | "config" | "tool" | "unknown";
+/**
+ * The single structured description of a terminal run failure. `detail`
+ * carries the raw provider text (with attribution, e.g. `Anthropic said:
+ * "…"`); `remediation` is the one actionable next step; `exitCode` comes
+ * from `EXIT_CODES` so fleet / the UI host can dispatch without parsing.
+ */
+export type FailureReport = {
+    readonly class: FailureClass;
+    readonly title: string;
+    readonly detail: string;
+    readonly remediation?: string;
+    readonly exitCode: number;
+    readonly docsUrl?: string;
+};
+/**
+ * Process exit-code table (documented in CLI-REFERENCE). Everything fatal
+ * used to be exit 1; these codes let `fleet run` and the UI host tell
+ * "account out of funding" from "bad spec" from "tool crash".
+ */
+export declare const EXIT_CODES: {
+    /** Clean run. */
+    readonly ok: 0;
+    /** Unclassified fatal error (the pre-0.3.0 catch-all). */
+    readonly generic: 1;
+    /** Spec parse / validation failure. */
+    readonly spec: 20;
+    /** Config / missing-env failure. */
+    readonly config: 21;
+    /** Provider rejected the credentials at runtime (401/403). */
+    readonly auth: 30;
+    /** Provider account out of funding (credit balance, insufficient_quota, 402). */
+    readonly billing: 31;
+    /** Provider quota / rate limit exhausted after retries. */
+    readonly rate_limit: 32;
+    /** CrewHaus's own configured budget cap ended the run. */
+    readonly crewhaus_budget: 33;
+    /** Tool or MCP failure (including MCP boot). */
+    readonly tool: 40;
+};
+/**
+ * Terminal error carrying a `FailureReport`. Thrown by runtime-core when the
+ * recovery engine returns a `halt` action. Extends `RuntimeError` so every
+ * existing `instanceof CrewhausError` catch (e.g. `crewhaus run`'s die()
+ * routing) keeps working unchanged; PR 3 upgrades those catch sites to
+ * render the report and exit with `report.exitCode`.
+ */
+export declare class RunFailedError extends RuntimeError {
+    readonly name = "RunFailedError";
+    readonly report: FailureReport;
+    constructor(report: FailureReport, cause?: unknown);
+}
+/**
+ * Render a `FailureReport` as the canonical multi-line failure message:
+ *
+ *     ✗ run stopped — provider account out of funding
+ *       Anthropic said: "Your credit balance is too low to access the Anthropic API."
+ *       Fix: add credits at https://console.anthropic.com/settings/billing, then rerun.
+ *       (exit 31)
+ *
+ * `opts.prefix` replaces the leading `✗` (e.g. `crewhaus:` for the CLI).
+ * `opts.notes` are surface-specific trailing lines rendered after Fix/Docs
+ * and before the exit line (e.g. `crewhaus run`'s "Your session is saved —
+ * …" resume hint). Dependency-free by design — emitted bundles inline-import
+ * this.
+ */
+export declare function formatRunFailure(report: FailureReport, opts?: {
+    prefix?: string;
+    notes?: readonly string[];
+}): string;
+/**
+ * Is `err` a RunFailedError (or a structurally identical wire twin)? The
+ * duck-typed fallback matters for compiled bundles: a bundle and the runtime
+ * it embeds can end up with two copies of this package (duplicated install,
+ * bundler realm split), in which case `instanceof` lies but the shape —
+ * `name === "RunFailedError"` plus a report with a numeric `exitCode` —
+ * does not.
+ */
+export declare function isRunFailedError(err: unknown): err is RunFailedError;
+/**
+ * Coerce any thrown value into a `FailureReport`: a RunFailedError yields
+ * its own classified report; everything else synthesizes a best-effort
+ * generic report (class `"unknown"`, exit {@link EXIT_CODES.generic}) so
+ * every terminal surface — compiled bundles' catch wrappers, daemon mains,
+ * `crewhaus run` — renders ONE shape regardless of what escaped.
+ */
+export declare function toFailureReport(err: unknown): FailureReport;

package/dist/index.js

@@ -44,6 +44,7 @@ export class CompilerError extends CrewhausError {
     }
 }
 export class RuntimeError extends CrewhausError {
+    // `: string` (not the literal) so subclasses (RunFailedError) can narrow.
     name = "RuntimeError";
     constructor(message, cause) {
         super("runtime", message, cause);
@@ -100,3 +101,128 @@ export class ProviderAuthError extends AdapterError {
         super(providerId, message, cause);
     }
 }
+/**
+ * Process exit-code table (documented in CLI-REFERENCE). Everything fatal
+ * used to be exit 1; these codes let `fleet run` and the UI host tell
+ * "account out of funding" from "bad spec" from "tool crash".
+ */
+export const EXIT_CODES = {
+    /** Clean run. */
+    ok: 0,
+    /** Unclassified fatal error (the pre-0.3.0 catch-all). */
+    generic: 1,
+    /** Spec parse / validation failure. */
+    spec: 20,
+    /** Config / missing-env failure. */
+    config: 21,
+    /** Provider rejected the credentials at runtime (401/403). */
+    auth: 30,
+    /** Provider account out of funding (credit balance, insufficient_quota, 402). */
+    billing: 31,
+    /** Provider quota / rate limit exhausted after retries. */
+    rate_limit: 32,
+    /** CrewHaus's own configured budget cap ended the run. */
+    crewhaus_budget: 33,
+    /** Tool or MCP failure (including MCP boot). */
+    tool: 40,
+};
+/**
+ * Terminal error carrying a `FailureReport`. Thrown by runtime-core when the
+ * recovery engine returns a `halt` action. Extends `RuntimeError` so every
+ * existing `instanceof CrewhausError` catch (e.g. `crewhaus run`'s die()
+ * routing) keeps working unchanged; PR 3 upgrades those catch sites to
+ * render the report and exit with `report.exitCode`.
+ */
+export class RunFailedError extends RuntimeError {
+    name = "RunFailedError";
+    report;
+    constructor(report, cause) {
+        super(`run stopped — ${report.title}: ${report.detail}`, cause);
+        this.report = report;
+    }
+}
+/**
+ * Render a `FailureReport` as the canonical multi-line failure message:
+ *
+ *     ✗ run stopped — provider account out of funding
+ *       Anthropic said: "Your credit balance is too low to access the Anthropic API."
+ *       Fix: add credits at https://console.anthropic.com/settings/billing, then rerun.
+ *       (exit 31)
+ *
+ * `opts.prefix` replaces the leading `✗` (e.g. `crewhaus:` for the CLI).
+ * `opts.notes` are surface-specific trailing lines rendered after Fix/Docs
+ * and before the exit line (e.g. `crewhaus run`'s "Your session is saved —
+ * …" resume hint). Dependency-free by design — emitted bundles inline-import
+ * this.
+ */
+export function formatRunFailure(report, opts) {
+    const prefix = opts?.prefix ?? "✗";
+    const lines = [`${prefix} run stopped — ${report.title}`];
+    if (report.detail.length > 0) {
+        for (const detailLine of report.detail.split("\n")) {
+            lines.push(`  ${detailLine}`);
+        }
+    }
+    if (report.remediation !== undefined && report.remediation.length > 0) {
+        lines.push(`  Fix: ${report.remediation}`);
+    }
+    if (report.docsUrl !== undefined && report.docsUrl.length > 0) {
+        lines.push(`  Docs: ${report.docsUrl}`);
+    }
+    for (const note of opts?.notes ?? []) {
+        lines.push(`  ${note}`);
+    }
+    lines.push(`  (exit ${report.exitCode})`);
+    return lines.join("\n");
+}
+/**
+ * Is `err` a RunFailedError (or a structurally identical wire twin)? The
+ * duck-typed fallback matters for compiled bundles: a bundle and the runtime
+ * it embeds can end up with two copies of this package (duplicated install,
+ * bundler realm split), in which case `instanceof` lies but the shape —
+ * `name === "RunFailedError"` plus a report with a numeric `exitCode` —
+ * does not.
+ */
+export function isRunFailedError(err) {
+    if (err instanceof RunFailedError)
+        return true;
+    const duck = err;
+    return (duck !== null &&
+        typeof duck === "object" &&
+        duck.name === "RunFailedError" &&
+        typeof duck.report === "object" &&
+        duck.report !== null &&
+        typeof duck.report.exitCode === "number");
+}
+/**
+ * Coerce any thrown value into a `FailureReport`: a RunFailedError yields
+ * its own classified report; everything else synthesizes a best-effort
+ * generic report (class `"unknown"`, exit {@link EXIT_CODES.generic}) so
+ * every terminal surface — compiled bundles' catch wrappers, daemon mains,
+ * `crewhaus run` — renders ONE shape regardless of what escaped.
+ */
+export function toFailureReport(err) {
+    if (isRunFailedError(err))
+        return err.report;
+    const detail = err instanceof Error ? err.message : String(err);
+    // A `ConfigError` (missing env var, unresolvable secret ref — e.g. the
+    // thredz boot's THREDZ_API_KEY resolution, §4.4) is a classified failure
+    // with its own exit code (21), not the generic catch-all. Duck-typed on
+    // the stable `code` field so a realm-split copy of this package still
+    // classifies.
+    const code = err?.code;
+    if (err instanceof Error && code === "config") {
+        return {
+            class: "config",
+            title: "configuration error",
+            detail,
+            exitCode: EXIT_CODES.config,
+        };
+    }
+    return {
+        class: "unknown",
+        title: "unexpected error",
+        detail,
+        exitCode: EXIT_CODES.generic,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/errors",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "description": "Typed error hierarchy shared across factory layers",
   "main": "dist/index.js",