@arcforge/err 2.0.162 → 2.0.164

package/README.md

@@ -0,0 +1,25 @@
+# @arcforge/err
+
+Structured errors for the [Axon](https://axon.arclabs.it) agent runtime.
+
+Every user-facing failure in Axon is rendered from a single code map. An error is a
+structured code with a known cause and a known remedy — never a bare string thrown
+from wherever it happened to occur.
+
+```bash
+npm install @arcforge/err
+```
+
+Most people never install this directly. It arrives as a dependency of the Axon
+framework when you scaffold an agent with `axon init`.
+
+## Documentation
+
+Full documentation is at **[axon.arclabs.it/docs/v2](https://axon.arclabs.it/docs/v2)**.
+
+- [What is Axon?](https://axon.arclabs.it/docs/v2)
+- [The axon API](https://axon.arclabs.it/docs/v2/api)
+
+## License
+
+Proprietary. © ArcLabs

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arcforge/err",
-    "version": "2.0.162",
+    "version": "2.0.164",
     "description": "Structured Axon errors — the code map every user-facing failure is rendered from.",
     "type": "module",
     "private": false,
@@ -15,10 +15,29 @@
         "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.162"
+        "@arcforge/types": "2.0.164"
     },
     "devDependencies": {
         "@types/bun": "latest",
         "typescript": "^5"
-    }
+    },
+    "homepage": "https://axon.arclabs.it/docs/v2",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/artificial-cognition-laboratories/axon.git",
+        "directory": "libs/axon/packages/err"
+    },
+    "bugs": {
+        "url": "https://github.com/artificial-cognition-laboratories/axon/issues"
+    },
+    "keywords": [
+        "axon",
+        "ai",
+        "agent",
+        "agents",
+        "llm",
+        "ai-agent",
+        "agent-runtime",
+        "typescript"
+    ]
 }

package/src/map.ts

@@ -508,6 +508,80 @@ export const errorMap = {
         severity: "fatal",
     },
 
+    /**
+     * A flattened tool export would have replaced a host global. Refused at
+     * install rather than silently skipped: skipping made the generated
+     * tool-globals.d.ts assert a binding the runtime never made, so the
+     * editor typechecked a call that threw (or worse, silently read the
+     * builtin) at run time.
+     */
+    TOOL_GLOBAL_COLLISION: {
+        code: "AX-TOOL-409",
+        title: "Tool Global Collides With A Builtin",
+        description: "A flattened tool export has the same name as something that already exists in the agent's global scope, and replacing it would break the code around it. Reach this member through `axon.tools.<namespace>.<member>`, rename the export, or drop `flat` so the module lands under its own namespace instead.",
+        source: "manifest",
+        severity: "fatal",
+        expected: true,
+    },
+
+    /**
+     * A script the agent declares ran and failed. The agent's own error is
+     * carried in `detail` — this code says WHERE it failed, not what went
+     * wrong, which is the script's own business.
+     */
+    SCRIPT_FAILED: {
+        code: "AX-SCRIPT-500",
+        title: "Script Failed",
+        description: "A script declared by this agent was invoked and threw. The agent's own error follows — this is the script's failure, not the runtime's.",
+        source: "runtime",
+        severity: "fatal",
+        expected: true,
+    },
+
+    /**
+     * The agent could not bind an HTTP port. Walking forward from the
+     * requested one is deliberate (a second agent should come up beside the
+     * first), so reaching the end of the range means the whole span is taken
+     * — a real environment problem rather than a retry.
+     */
+    AGENT_SERVE_NO_PORT: {
+        code: "AX-AGENT-503",
+        title: "No Free Port",
+        description: "The agent tried to bind its HTTP surface and every port in the range it walked was already in use. Free one, or pass a different port with --port.",
+        source: "runtime",
+        severity: "fatal",
+        expected: true,
+    },
+
+    // ── Agent resolution (build/runtime/resolve.ts) ─────────────────────────
+    /**
+     * A named reference matched no agent in any local pool. Distinct from
+     * PROJECT_NOT_FOUND, which means "this path is not a project": here the
+     * caller named an agent and the answer is that it is not installed
+     * anywhere, which has a different fix (`axon install`).
+     */
+    AGENT_NOT_FOUND: {
+        code: "AX-AGENT-404",
+        title: "Agent Not Found",
+        description: "No local agent goes by this name. Agent references resolve against your local pools only — watched paths first, then installed agents — and never fetch from the registry. Install it first with `axon install`.",
+        source: "manifest",
+        severity: "fatal",
+        expected: true,
+    },
+    /**
+     * Two pools both hold an agent with this identity. Never resolved by
+     * picking one: running the wrong agent silently is the failure this
+     * exists to prevent.
+     */
+    AGENT_AMBIGUOUS: {
+        code: "AX-AGENT-409",
+        title: "Ambiguous Agent Name",
+        description: "More than one local pool holds an agent with this name, and there is no correct way to guess which was meant — pass an explicit path, or unwatch one of the roots.",
+        source: "manifest",
+        severity: "fatal",
+        expected: true,
+    },
+
     // ── Project (build/project/*.ts) ────────────────────────────────────────
     PROJECT_NOT_FOUND: {
         code: "AX-PROJECT-017",
@@ -1319,6 +1393,30 @@ export const errorMap = {
         source: "capsule",
         severity: "fatal",
     },
+    AGENT_ENV_RESERVED: {
+        code: "AX-CAPSULE-012",
+        title: "Reserved Environment Variable",
+        description: "An agent's .env sets a framework-owned variable the runtime controls (AGENT_ID, AXON_API_BASE and similar). These identify the agent to the platform, so overriding one locally would make the agent report itself as something it is not. The deploy path has always refused this; the local path now refuses it identically.",
+        source: "capsule",
+        severity: "fatal",
+    },
+
+    CAPSULE_NET_UNRESOLVED: {
+        code: "AX-CAPSULE-010",
+        title: "Network Policy Did Not Resolve",
+        description: "A `net.allow` entry names a hostname that did not resolve to any address. Egress rules are installed as addresses, so an unresolvable name becomes no rule at all — a grant you believe you made and did not. The box refuses to boot rather than run with an allowlist quietly smaller than the one you wrote. Check the hostname, or use a literal address if the name is resolvable only from inside the box.",
+        source: "capsule",
+        severity: "fatal",
+    },
+
+    CAPSULE_NET_UNAVAILABLE: {
+        code: "AX-CAPSULE-011",
+        title: "Network Confinement Unavailable",
+        description: "The policy declares a `net` allowlist, which needs a userspace network stack (slirp4netns) and nftables inside the box's namespace. One of them is missing on this host. Install slirp4netns and nftables, or drop the `net` block to run with no network at all — the box will not fall back to unfiltered egress.",
+        source: "capsule",
+        severity: "fatal",
+    },
+
     CAPSULE_CONFINE_UNAVAILABLE: {
         code: "AX-CAPSULE-004",
         title: "OS Confinement Unavailable",
@@ -1619,6 +1717,14 @@ export const errorMap = {
         severity: "fatal",
         expected: true,
     },
+    FLAG_VALUE_REQUIRED: {
+        code: "AX-CLI-007",
+        title: "A Flag Is Missing Its Value",
+        description: "The flag takes a value and none followed it. Quote the value if it contains spaces, and check it was not consumed as another flag.",
+        source: "cli",
+        severity: "fatal",
+        expected: true,
+    },
     RUN_INSTRUCTION_REQUIRED: {
         code: "AX-CLI-006",
         title: "Nothing To Run",
@@ -2201,6 +2307,120 @@ export const errorMap = {
         severity: "degraded",
         expected: true,
     },
+    // ── Daemon (axond) ──────────────────────────────────────────────────────
+    //
+    // The daemon owns machine-wide state, so its failures are about REACHING
+    // it or about it refusing something — never about the work itself, which
+    // reports through the domain's own codes.
+    AGENT_NO_SUPERVISOR: {
+        code: "AX-AGENT-030",
+        title: "No Supervisor to Boot This Agent",
+        description: "Something asked a platform to spawn an agent, but that platform was built without a supervisor. Supervision holds the provider credential and the session log, so it lives in the daemon rather than in whichever process happened to ask — a platform used only to read the store or publish a project does not need one, and this is where the difference surfaces.",
+        source: "runtime",
+        severity: "fatal",
+        expected: true,
+    },
+    MODEL_RUNTIME_MISSING: {
+        code: "AX-MODEL-031",
+        title: "That Runtime Is Not Installed",
+        description: "An adapter recognised the model and the library that executes it is not on this machine. Local inference runtimes are optional because they are large — ONNX Runtime alone is around 300MB of native binaries — so they are installed when first wanted rather than shipped with the CLI.",
+        source: "daemon",
+        severity: "fatal",
+        expected: true,
+    },
+    MODEL_LOAD_FAILED: {
+        code: "AX-MODEL-032",
+        title: "The Model Could Not Be Loaded",
+        description: "A runtime recognised the file and failed to read it. Distinct from an unsupported format: this weight is one this machine can execute in principle, so the file itself is the problem — truncated, corrupt, or not the model its name claims.",
+        source: "daemon",
+        severity: "fatal",
+    },
+    MODEL_WILL_NOT_FIT: {
+        code: "AX-MODEL-033",
+        title: "Not Enough Memory for This Model",
+        description: "The weight loaded and did not fit within this machine's ceiling, so it was unloaded again. The refusal names what is holding the memory — a model already resident, or another process entirely, since the check measures the whole card rather than Axon's share. Nothing is evicted automatically: a silent eviction is another agent mysteriously slowing down.",
+        source: "daemon",
+        severity: "degraded",
+        expected: true,
+    },
+    MODEL_NOT_RESIDENT: {
+        code: "AX-MODEL-034",
+        title: "That Model Is Not Loaded",
+        description: "Inference was asked of a weight that is not in memory. Loading is never implicit: it is a claim on the machine's memory, and taking one a caller did not ask for would make admission invisible at the moment it matters.",
+        source: "daemon",
+        severity: "degraded",
+        expected: true,
+    },
+    MODEL_NOT_CACHED: {
+        code: "AX-MODEL-035",
+        title: "That Model Is Not On This Machine",
+        description: "A weight was asked for that has not been fetched. The daemon caches models content-addressed and machine-wide, so one download serves every agent — but it only serves what has actually been downloaded.",
+        source: "daemon",
+        severity: "degraded",
+        expected: true,
+    },
+    MODEL_NO_SINGLE_WEIGHT: {
+        code: "AX-MODEL-036",
+        title: "That Repository Has No Single Weight",
+        description: "A repository was asked for by name and publishes several weights with no obvious one to take — an encoder-decoder export ships both halves and needs both, and a quantised set is a choice about quality rather than a default. Name the file to fetch. Guessing would download half a model that fails at load with something obscure.",
+        source: "daemon",
+        severity: "degraded",
+        expected: true,
+    },
+    MODEL_NO_RUNTIME: {
+        code: "AX-MODEL-030",
+        title: "No Runtime Can Execute This Model",
+        description: "The weight is on this machine and no adapter claims it. Runtimes are registered per format — ONNX, llama.cpp — and a file none of them recognises can be fetched and cached but not loaded. Either the format needs an adapter, or the file is not the model it appears to be.",
+        source: "daemon",
+        severity: "fatal",
+        expected: true,
+    },
+    DAEMON_NOT_RUNNING: {
+        code: "AX-DAEMON-001",
+        title: "The Axon Daemon Is Not Running",
+        description: "Something asked axond for machine-wide state — what is loaded on the GPU, which agents are running — and no daemon is listening. Start it with `axon daemon up`. Local work that does not need shared state is unaffected.",
+        source: "daemon",
+        severity: "degraded",
+        expected: true,
+    },
+    DAEMON_ALREADY_RUNNING: {
+        code: "AX-DAEMON-002",
+        title: "A Daemon Is Already Running",
+        description: "A second axond was asked to start while one is already listening on this socket. One daemon per user per machine is the whole point — two would each believe they owned the GPU. Nothing was started; the existing one is untouched.",
+        source: "daemon",
+        severity: "degraded",
+        expected: true,
+    },
+    DAEMON_SOCKET_UNAVAILABLE: {
+        code: "AX-DAEMON-003",
+        title: "Could Not Bind the Daemon Socket",
+        description: "axond could not listen on its unix socket. Usually a stale socket file left by a process killed with -9, which the daemon removes on start; if it persists, the path may be unwritable or on a filesystem that does not support unix sockets.",
+        source: "daemon",
+        severity: "fatal",
+    },
+    DAEMON_START_FAILED: {
+        code: "AX-DAEMON-004",
+        title: "The Daemon Failed to Start",
+        description: "axond was spawned but never reported itself ready. Its output is in the daemon log named by the detail; the usual causes are a port or socket conflict and a broken profile config.",
+        source: "daemon",
+        severity: "fatal",
+    },
+    DAEMON_NOT_WIRED: {
+        code: "AX-DAEMON-005",
+        title: "That Part of the Daemon Is Not Built Yet",
+        description: "A domain the daemon declares exists but is not implemented. It throws rather than answering, because a stub returning an empty list is indistinguishable from a real answer and gets built on top of.",
+        source: "daemon",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_LOAD_TIMEOUT: {
+        code: "AX-EXT-034",
+        title: "Extension Took Too Long to Load",
+        description: "A config file did not finish evaluating within the load budget — usually a blocking loop or a synchronous wait at module scope. Loading continued without it, so its commands, keys and palettes are missing; everything else in your config still loaded. The file itself keeps running until it finishes, because there is no safe way to interrupt code mid-execution.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
     PLUGIN_FAILED: {
         code: "AX-EXT-009",
         title: "Plugin Failed to Load",