@arcforge/err 2.0.149 → 2.0.151

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arcforge/err",
-    "version": "2.0.149",
+    "version": "2.0.151",
     "description": "Structured Axon errors — the code map every user-facing failure is rendered from.",
     "type": "module",
     "private": false,
@@ -15,7 +15,7 @@
         "deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
     },
     "dependencies": {
-        "@arcforge/types": "2.0.149"
+        "@arcforge/types": "2.0.151"
     },
     "devDependencies": {
         "@types/bun": "latest",

package/src/map.ts

@@ -838,6 +838,84 @@ export const errorMap = {
         source: "kernel",
         severity: "fatal",
     },
+    /**
+     * ── Engine failures the USER can act on ─────────────────────────────────
+     *
+     * Every one of these was previously a single `ENGINE_STREAM_FAILED`, which
+     * put an internal code and a stack trace in front of someone whose real
+     * problem was an expired key or a spent subscription. The drivers already
+     * classify the fault precisely (AxonEngineFaultCode) and already write a
+     * provider-specific sentence about it — that work was being thrown away one
+     * layer up.
+     *
+     * These are `expected: true`, so they render as headline + description with
+     * no frames: the user did not write the code that failed, and eighty lines
+     * of our stack tells them to debug software they do not own. The driver's
+     * own message rides in as `detail` and is the most specific thing on
+     * screen ("Codex: usage limit reached. Check your ChatGPT subscription.").
+     *
+     * The split is one question: CAN THE USER FIX IT? If yes it belongs here.
+     * If the model or the driver misbehaved, it stays ENGINE_STREAM_FAILED and
+     * keeps the full report, because that one is ours to debug.
+     */
+    ENGINE_NOT_CONNECTED: {
+        code: "AX-KERNEL-015",
+        title: "Provider Not Connected",
+        description: "This model's route is not connected to your account yet — run `:provider <name> connect` for the provider named below, or pick a model on a route you are already signed in to.",
+        source: "kernel",
+        severity: "fatal",
+        expected: true,
+    },
+    ENGINE_AUTH_FAILED: {
+        code: "AX-KERNEL-016",
+        title: "Provider Rejected Your Credentials",
+        description: "The provider refused the credential this agent is using — it has expired, been revoked, or is for a different account. Reconnect the provider, or pick a model on a route you are signed in to.",
+        source: "kernel",
+        severity: "fatal",
+        expected: true,
+    },
+    ENGINE_RATE_LIMITED: {
+        code: "AX-KERNEL-017",
+        title: "Provider Rate Limit Reached",
+        description: "The provider is refusing further calls right now — either too many requests in a short window, or a subscription whose allowance is spent. Waiting usually clears the first; the second needs a plan change or a different model.",
+        source: "kernel",
+        severity: "fatal",
+        expected: true,
+    },
+    ENGINE_QUOTA_EXHAUSTED: {
+        code: "AX-KERNEL-018",
+        title: "Provider Credits Exhausted",
+        description: "This route has no credit left to spend. Top it up, or switch to a model on a route that does — the conversation is intact either way.",
+        source: "kernel",
+        severity: "fatal",
+        expected: true,
+    },
+    ENGINE_REQUEST_REJECTED: {
+        code: "AX-KERNEL-019",
+        title: "Provider Rejected The Request",
+        description: "The provider refused this call as malformed or unsupported — commonly a model id it does not serve, a context window this conversation has outgrown, or a parameter that route does not accept.",
+        source: "kernel",
+        severity: "fatal",
+        expected: true,
+    },
+    ENGINE_UNREACHABLE: {
+        code: "AX-KERNEL-020",
+        title: "Could Not Reach The Provider",
+        description: "The provider could not be reached, or kept failing, across every retry — usually a network problem on this machine or an outage on their side. Nothing about this agent needs changing; try again.",
+        source: "kernel",
+        severity: "fatal",
+        expected: true,
+    },
+
+    /**
+     * The engine failure that is OURS.
+     *
+     * Deliberately NOT `expected`: what is left here after the classified
+     * failures above is a model that returned nothing, a driver that broke the
+     * wire protocol, or a fault nothing recognised. The user cannot act on any
+     * of those, and the full report — frames, snippets, cause chain — is what
+     * makes it debuggable from a pasted log.
+     */
     ENGINE_STREAM_FAILED: {
         code: "AX-KERNEL-008",
         title: "Engine Stream Failed",
@@ -845,6 +923,20 @@ export const errorMap = {
         source: "kernel",
         severity: "fatal",
     },
+    /**
+     * RETIRED — superseded by ENGINE_NOT_CONNECTED (AX-KERNEL-015).
+     *
+     * This was the one hand-written special case in the kernel's failure path:
+     * `AUTH_NOT_CONNECTED` AND `provider === "codex"`. Every other provider hit
+     * the generic internal error for the identical condition, and each new
+     * route would have needed its own branch and its own code.
+     *
+     * ENGINE_NOT_CONNECTED says the same thing for any provider, with the
+     * driver's own message naming which one. Kept as a definition rather than
+     * deleted so AX-KERNEL-012 is never handed to a different failure — a code
+     * that appears in an old session log, a support thread or a screenshot must
+     * keep meaning what it meant when it was written.
+     */
     CODEX_NOT_CONNECTED: {
         code: "AX-KERNEL-012",
         title: "Codex Subscription Not Connected",
@@ -1289,6 +1381,14 @@ export const errorMap = {
         severity: "fatal",
         expected: true,
     },
+    MODEL_UNAVAILABLE: {
+        code: "AX-TUI-051",
+        title: "Model Not Available From Any Declared Provider",
+        description: "The picked model was saved to the agent's config, but no provider this profile declares can supply it — so the running agent still uses its previous model. Connect the provider that serves it, or pick a model from the offered list.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
     MODEL_IMMUTABLE_DEPLOYED: {
         code: "AX-TUI-006",
         title: "Cannot Change A Deployment's Model",