@axonity-ai/mcp 0.1.0 → 0.3.2

package/README.md

@@ -1,9 +1,10 @@
 # @axonity-ai/mcp — Axonity Flow MCP connector
 
 A local [Model Context Protocol](https://modelcontextprotocol.io) server that lets
-an external agent (e.g. **Claude Code** on your laptop) read, draft, and update
-**workflows, agents, tools, skills, policies and reference docs** in your Axonity
-tenant — the same verbs the internal Builder team has, minus direct publish.
+an external agent (e.g. **Claude Code** on your laptop) read, draft, update, and
+recoverably delete **workflows, agents, tools, skills, policies, reference docs,
+personas, output schemas, prompt snippets and flows** in your Axonity tenant —
+the same verbs the internal Builder team has, minus direct publish.
 
 It runs on your machine and talks to Axonity **only over the public REST API**,
 authenticated with a per-tenant **service token**. The backend re-enforces
@@ -13,7 +14,11 @@ tenant + scope on every call, so the connector is not a trust boundary.
 
 1. **Mint a service token** in Axonity → **Settings → API tokens**. Copy it once
    (it starts with `axs_`); you won't see it again. Use a **read-only** token if
-   you only want the agent to read.
+   you only want the agent to read — it is genuinely enforced, any write from it
+   is refused with a 403. Every token expires (you choose 7, 15, 30, 60 or 90
+   days at mint time; there is no "never"), and there is no way for the agent to
+   check remaining lifetime in advance — an expired token fails exactly like a
+   revoked one, so mint a fresh one when that happens.
 2. **Add the connector to Claude Code:**
 
    ```bash
@@ -26,43 +31,186 @@ tenant + scope on every call, so the connector is not a trust boundary.
    `AXONITY_API_URL` is optional (defaults to the Axonity SaaS URL); set it if you
    self-host.
 
+   Do **not** pass extra CLI arguments to `axonity-mcp`; startup only reads
+   environment variables. If arguments are supplied, the process exits with a
+   clear usage-style error.
+
 3. Ask Claude Code things like *"list my Axonity workflows"*, *"create a workflow
    called Onboarding"*, or *"add a step to workflow X"*.
 
 ## Tools
 
-| Tool | What it does |
-|------|--------------|
-| `axonity_conventions` | The authoring rules (drafts vs live, optimistic locking, per-entity fields). Read this first. |
-Each entity — **workflow, agent, tool, skill, policy, reference_doc** — gets the
-same five verbs:
+200+ tools total. `axonity_conventions` (read this first) covers the authoring
+rules — drafts vs live, optimistic locking, per-entity fields, delete/restore,
+and how to tell a retryable error from one that will never succeed.
+
+### The generic entity family
+
+Ten entities — **workflow, agent, tool, skill, policy, reference_doc, persona,
+output_schema, prompt_snippet, flow** — share one shape, though not every
+entity gets every verb (see the per-entity notes below for the exceptions):
 
 | Tool (per `<entity>`) | What it does |
 |------|--------------|
-| `list_<entity>s` | List the tenant's entities. |
+| `list_<plural>` | List the tenant's entities. |
 | `read_<entity>` | Read one by id (incl. its version — read before you update). |
 | `create_<entity>` | Create a new **draft**. |
-| `update_<entity>` | Update a draft (carries `expectedVersion`; 409 on a stale write). |
+| `update_<entity>` | Update a draft (`expectedVersion` in the body; 409 on a stale write). |
+| `delete_<entity>` | Soft-delete. **Recoverable** — see `restore_<entity>`. |
+| `restore_<entity>` | Undo a delete. No version check. |
+| `list_deleted_<plural>` | Restore candidates. |
+| `discard_<entity>_draft` | Reset the draft to the last published state. |
 | `request_publish_<entity>` | Ask for a draft to be published — creates a pending approval; never publishes. |
 
-Plus `apply_workflow_mutations` for structural workflow edits (add steps, connect
-edges) via mutation commands.
+Exceptions: `persona` has no `create_persona` (create only via
+`create_agent_persona`).
+
+Plus:
+- `apply_workflow_mutations` for structural workflow edits (add steps, connect
+  edges) via mutation commands, sequenced and version-threaded for you.
+- `replace_workflow_document` for one-shot full-document replacement in a single
+  atomic PUT.
+- `read_workflow_trigger_parameters` — what input a workflow's triggers expect.
+- `bulk_delete_workflows` — soft-delete several at once (each with its own
+  `expectedVersion`).
 
-Also:
+### Version history, rollback, and version-level delete
 
-- **Personas** (agent-scoped, 1:1 with an agent): `read_agent_persona`,
-  `create_agent_persona`, `update_persona`.
+For the ten versioned entities (including `flow`):
+
+| Tool | What it does |
+|------|--------------|
+| `list_<entity>_versions` | List version history (checkpoints + named majors). |
+| `read_<entity>_version` | Read one, by **integer checkpoint number**. |
+| `restore_<entity>_version` | Roll the draft back to an old version (`expectedVersion` in body). |
+| `delete_<entity>_version` | Remove one history entry. Draft and published version are protected. |
+| `list_deleted_<entity>_versions` | Restore candidates for the row above. |
+| `restore_deleted_<entity>_version` | Undo the delete above. No version check. |
+| `read_<entity>_published` | The live snapshot, as opposed to the draft. |
+| `name_<entity>_major_version` | Give a major version a name (label a release). |
+
+`{version}` (an int) and `{versionId}` (a UUID) are two different identifiers
+across these routes — the tool parameter names say which.
+
+### Also
+
+- **Personas**: `read_agent_persona`, `create_agent_persona` — agent-scoped,
+  since a persona can only be created through its agent. Everything else about
+  a persona (list, read, update, delete/restore, versions) is the generic
+  entity family above.
 - **Connectors** (a tool of type `connector`): `create_connector`,
   `update_connector` — `authConfig` must be placeholders only; a human fills real
-  secrets in Axonity.
-- **Attach memory to a target**: `attach_skill_to_agent`,
-  `attach_skill_to_workflow`, `attach_policy_to_agent`, `attach_reference_to_agent`.
+  secrets in Axonity. (`create_tool`/`update_tool` carry the same guard, so a
+  connector authored either way is covered.)
+- **Attach / detach memory**: `attach_skill_to_agent`,
+  `attach_skill_to_workflow`, `attach_policy_to_agent`,
+  `attach_reference_to_agent`, and a `detach_*_from_*` for each. Detaching
+  removes the link only — the skill or policy itself is untouched. Read the
+  links back with `list_agent_skills`, `list_agent_policies`,
+  `list_agent_reference_docs`.
+- **Prompt elements (placement)**: a `prompt_snippet` is a library item; it only
+  takes effect once placed into a flow step's prompt stack.
+  `read_workflow_prompt_stacks` / `read_flow_prompt_stacks` resolve a
+  workflow/flow to its steps and each step's `system`/`user` stacks (this is how
+  you find the `flowStepId`s). Then `attach_prompt_snippet_to_flow_step`
+  (`target` = `system`|`user`, with an order), `update_flow_step_prompt`,
+  `reorder_flow_step_prompts`, `detach_prompt_snippet_from_flow_step`, and
+  `list_flow_step_prompts` / `list_wildcard_prompts`.
+- **Company** (the tenant's single company document — a singleton, no id):
+  `read_company`, `update_company` (whole-document save with `expectedVersion`),
+  `list_company_versions`, `read_company_version`, `restore_company_version`,
+  `name_company_major_version`, `read_company_published`, and
+  `request_publish_company` (takes no id — the
+  server resolves your tenant's one company; direct company publish is closed to
+  service tokens).
+- **Catalog & cloning**: `list_system_tools` (read-only catalog — enabling one
+  for an agent is `update_agent` with the id added to `systemToolIds`),
+  `clone_flow`, `clone_prompt_snippet`.
+- `list_deleted_prompt_snippets` calls `/api/v1/prompt-snippets/deleted`; the
+  backend returns it as `{ items: [... ] }`, and the tool forwards that response
+  unchanged.
+
+### Validate and run before you publish
 
-## Publishing
-
-The connector **never publishes directly**. `request_publish_*` creates a
-**pending approval** in Axonity; an admin approves it there, and only then does
-the draft go live. Rejecting it changes nothing.
+| Tool | What it does |
+|------|--------------|
+| `validate_workflow` | Structural + schema check of a workflow document. Stateless and read-only-token safe; does not verify referenced agents/tools exist. |
+| `analyze_workflow_reachable_outputs` | What a given step can read from upstream — bind inputs to real fields instead of guessing. Stateless and read-only-token safe. |
+| `validate_tool_code` | Syntax and banned-pattern check for Python tool code. Stateless and read-only-token safe. |
+| `format_tool_code` | Format tool code with Black. Stateless and read-only-token safe. |
+| `execute_tool` | Actually RUN tool code (not just validate it) and see the real output. |
+| `execute_stored_connector` | Test-run an already-saved connector. The backend decrypts its real secret server-side — the agent supplies only input parameters and never sees the secret. |
+
+### Triggers — what makes a workflow run
+
+`list_/create_/delete_` for **webhook triggers** (plus
+`rotate_webhook_trigger`), **cron schedules**, and **conditional triggers**
+(plus `update_conditional_trigger`). Trigger deletes are **hard** deletes with
+no restore, and a webhook token is shown **once** at create or rotate.
+
+### Runs — evaluating what you built
+
+`start_workflow_run` (test a workflow you built — it runs the **published**
+workflow and really executes), `cancel_run`, `delete_run`, `list_runs`,
+`list_workflow_runs`, `read_run`, `read_run_trace`, `read_run_cost`,
+`read_runs_summary`, `archive_run` / `unarchive_run`, `bulk_archive_runs` /
+`bulk_delete_runs`. There is no findings endpoint — evaluation means reading a
+run's validator verdicts and its trace.
+
+### Approvals
+
+`list_publish_approvals({ status?, limit?, offset? })` and
+`get_publish_approval({ approvalId })` — how you find out whether a
+`request_publish_*` was approved or rejected. Approving and rejecting are
+human-only actions in Axonity.
+
+## What this is for — and what it is not
+
+**Authoring.** An agent composing an entity from intent: drafting a workflow,
+writing a tool, wiring memory onto an agent, and checking its own work. That is
+what these tools are built for.
+
+**Not bulk migration.** Do not use the connector to move many entities verbatim
+from one place to another. Axonity's config export/import moves bytes with no
+model in the path and fails closed on secrets; content routed through an agent
+can be subtly altered in transit, which is precisely the risk a fidelity
+migration cannot take.
+
+## Guardrails
+
+These are enforced by the backend, not merely by convention:
+
+- **The connector never publishes.** `request_publish_*` creates a **pending
+  approval**; a human approves it in Axonity, and only then does the draft go
+  live. A direct publish from a service token is refused with a 403, so there is
+  no tool for it and no way around it.
+- **A read-only token is genuinely read-only for mutations.** Any write from a token
+  without the `write` scope is refused with a 403.
+- **The four stateless analysis tools are the exception:** `validate_workflow`,
+  `analyze_workflow_reachable_outputs`, `validate_tool_code`, and `format_tool_code`
+  can be called by read-only and write tokens because they never mutate state.
+- **The token is tenant-bound.** An agent cannot reach another tenant.
+- **Secrets never pass through the agent.** A connector's `authConfig` accepts
+  placeholders only; a write carrying something that looks like a real
+  credential is rejected before it leaves the connector. Tenant secrets
+  (`/api/v1/secrets`) aren't wrapped at all — the backend refuses any service
+  token there outright.
+- **Errors carry a machine-readable `code`, not just prose.** A 409 can mean a
+  stale write (retry) or a live reference conflict (don't — see
+  `axonity_conventions`); the connector tells them apart by `code`, never by
+  matching the message text.
+- **No tool crosses the authority boundary.** A test drives the whole registered
+  surface and fails the build if any tool targets a publish / approve / secret /
+  service-token / deploy route (`test/exclusions.test.ts`).
+- **Guidance can't silently drift from the backend.** The field/enum facts the
+  connector states are pinned to a vendored snapshot of the backend OpenAPI
+  schema; `test/conformance.test.ts` fails if a route or documented enum
+  diverges (see `test/fixtures/README.md`).
+
+**One known exception, not enforced:** a framework-provided `flow` is meant to
+be read-only to a tenant, but the backend does not actually block
+`update_flow`/`delete_flow` against one. Prefer `clone_flow` over editing a
+framework flow in place.
 
 ## Development
 

package/dist/client.d.ts

@@ -8,6 +8,8 @@
  */
 import type { AxonityConfig } from "./config.js";
 export type Json = Record<string, unknown>;
+/** Query-string values a route may take. `undefined` entries are omitted. */
+export type Query = Record<string, string | number | boolean | undefined>;
 export declare class AxonityClient {
     private readonly config;
     constructor(config: AxonityConfig);
@@ -16,9 +18,16 @@ export declare class AxonityClient {
      * Issue a request and return the parsed JSON body. Non-2xx responses are
      * thrown as typed errors; a 204/empty body resolves to `undefined`.
      */
-    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
-    get<T = unknown>(path: string): Promise<T>;
+    request<T = unknown>(method: string, path: string, body?: unknown, query?: Query): Promise<T>;
+    get<T = unknown>(path: string, query?: Query): Promise<T>;
     post<T = unknown>(path: string, body?: unknown): Promise<T>;
     put<T = unknown>(path: string, body?: unknown): Promise<T>;
     patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /**
+     * DELETE. The optimistic lock travels as a QUERY parameter on these routes,
+     * not in the body — and its spelling differs by entity family
+     * (`expectedVersion` vs `expected_version`), so the caller passes it in.
+     * A 204 with no body resolves to `undefined`.
+     */
+    del<T = unknown>(path: string, query?: Query): Promise<T>;
 }

package/dist/client.js

@@ -12,17 +12,26 @@ export class AxonityClient {
     constructor(config) {
         this.config = config;
     }
-    url(path) {
-        return `${this.config.apiUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    url(path, query) {
+        const base = `${this.config.apiUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        if (!query)
+            return base;
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined)
+                params.set(key, String(value));
+        }
+        const qs = params.toString();
+        return qs ? `${base}?${qs}` : base;
     }
     /**
      * Issue a request and return the parsed JSON body. Non-2xx responses are
      * thrown as typed errors; a 204/empty body resolves to `undefined`.
      */
-    async request(method, path, body) {
+    async request(method, path, body, query) {
         let resp;
         try {
-            resp = await fetch(this.url(path), {
+            resp = await fetch(this.url(path, query), {
                 method,
                 headers: {
                     Authorization: `Bearer ${this.config.token}`,
@@ -39,15 +48,15 @@ export class AxonityClient {
         const text = await resp.text();
         const parsed = text ? safeJson(text) : undefined;
         if (!resp.ok) {
-            const detail = parsed && typeof parsed === "object" && "detail" in parsed
-                ? parsed.detail
-                : parsed;
-            throw errorForStatus(resp.status, detail);
+            // Pass the FULL body — errorForStatus reads `code`/`retryable`/`message`
+            // off the structured error envelope when present, and falls back
+            // gracefully for a bare `detail` string/array from older routes.
+            throw errorForStatus(resp.status, parsed);
         }
         return parsed;
     }
-    get(path) {
-        return this.request("GET", path);
+    get(path, query) {
+        return this.request("GET", path, undefined, query);
     }
     post(path, body) {
         return this.request("POST", path, body);
@@ -58,6 +67,15 @@ export class AxonityClient {
     patch(path, body) {
         return this.request("PATCH", path, body);
     }
+    /**
+     * DELETE. The optimistic lock travels as a QUERY parameter on these routes,
+     * not in the body — and its spelling differs by entity family
+     * (`expectedVersion` vs `expected_version`), so the caller passes it in.
+     * A 204 with no body resolves to `undefined`.
+     */
+    del(path, query) {
+        return this.request("DELETE", path, undefined, query);
+    }
 }
 function safeJson(text) {
     try {

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAI9D,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAE9C,GAAG,CAAC,IAAY;QACtB,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;IAC5E,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CACX,MAAc,EACd,IAAY,EACZ,IAAc;QAEd,IAAI,IAAc,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;gBACjC,MAAM;gBACN,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;oBAC5C,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACtE;gBACD,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;aAC5D,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,6EAA6E;YAC7E,MAAM,IAAI,eAAe,CACvB,sCAAsC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI;gBAC1D,yCAAyC,EAC3C,CAAC,EACD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEjD,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,MAAM,GACV,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,QAAQ,IAAI,MAAM;gBACxD,CAAC,CAAE,MAA8B,CAAC,MAAM;gBACxC,CAAC,CAAC,MAAM,CAAC;YACb,MAAM,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,MAAW,CAAC;IACrB,CAAC;IAED,GAAG,CAAc,IAAY;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAI,KAAK,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,CAAc,IAAY,EAAE,IAAc;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAI,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED,GAAG,CAAc,IAAY,EAAE,IAAc;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAI,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAc,IAAY,EAAE,IAAc;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAI,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -5,31 +5,74 @@
  * clean, actionable message to the agent — never a raw stack trace or an
  * opaque status code.
  */
+/**
+ * Mirrors the backend's `ErrorCode` enum (`src/error_codes.py`) — the stable,
+ * machine-readable vocabulary every structured error response carries as
+ * `code`. An external agent has no access to the backend repository, so this
+ * is the one field worth branching on; `message` is human-readable prose that
+ * can be reworded without notice.
+ */
+export type ErrorCode = "internal_error" | "bad_request" | "unauthorized" | "forbidden" | "not_found" | "gone" | "payload_too_large" | "service_unavailable" | "upstream_error" | "validation_error" | "config_secret_leak" | "config_import_error" | "conflict" | "version_conflict" | "reference_conflict" | "idempotency_conflict" | "already_terminal" | "concurrency_error" | "admin_session_required" | "rate_limited" | "trigger_concurrency_exceeded" | "config_deploy_disabled" | "git_provider_error";
+/** Codes where re-issuing the SAME request can succeed later. Mirrors `RETRYABLE_CODES`. */
+export declare const RETRYABLE_CODES: ReadonlySet<ErrorCode>;
+/**
+ * Render the server's `detail` as a compact, readable line.
+ *
+ * FastAPI returns a bare string for a raised error and a list of
+ * `{loc, msg, type}` objects for a 422 schema rejection. The list form is what
+ * names the offending field, so it is flattened to `body.fieldName: message`
+ * rather than dumped as JSON — the agent has to act on it, not read it.
+ */
+export declare function describeDetail(detail: unknown): string | undefined;
 export declare class AxonityApiError extends Error {
     /** HTTP status that produced this error. */
     readonly status: number;
-    /** Server-provided detail, when present. */
+    /** The server's response body, when present (may be the structured envelope). */
     readonly detail?: unknown | undefined;
+    /** The envelope's `code`, when the server sent one — branch on this, not on `message`. */
+    readonly code?: string | undefined;
+    /** Whether re-issuing the same request could succeed. `undefined` = unknown. */
+    readonly retryable?: boolean | undefined;
     constructor(message: string, 
     /** HTTP status that produced this error. */
     status: number, 
-    /** Server-provided detail, when present. */
-    detail?: unknown | undefined);
+    /** The server's response body, when present (may be the structured envelope). */
+    detail?: unknown | undefined, 
+    /** The envelope's `code`, when the server sent one — branch on this, not on `message`. */
+    code?: string | undefined, 
+    /** Whether re-issuing the same request could succeed. `undefined` = unknown. */
+    retryable?: boolean | undefined);
 }
 /** 409 — the entity was modified since the agent read it. Re-read and retry. */
 export declare class VersionConflictError extends AxonityApiError {
-    constructor(detail?: unknown);
+    constructor(body?: unknown);
+}
+/**
+ * 409 — the entity is referenced by something published or live. Both this and
+ * `VersionConflictError` are HTTP 409; the `code` is what tells them apart, and
+ * it matters: retrying THIS one can never succeed on its own.
+ */
+export declare class ReferenceConflictError extends AxonityApiError {
+    constructor(body?: unknown);
+}
+/** 404 — no such entity in this tenant (or it was deleted). */
+export declare class NotFoundError extends AxonityApiError {
+    constructor(body?: unknown);
 }
-/** 401 — the service token is missing, unknown, or revoked. */
+/** 401 — the service token is missing, unknown, expired, or revoked. */
 export declare class AuthError extends AxonityApiError {
-    constructor(detail?: unknown);
+    constructor(body?: unknown);
 }
 /** 403 — the token lacks the scope for this action (e.g. read-only on a write). */
 export declare class ForbiddenError extends AxonityApiError {
-    constructor(detail?: unknown);
+    constructor(body?: unknown);
 }
 /**
- * Map an HTTP response to the right error type. `detail` is the parsed body
- * (FastAPI returns `{ detail: … }`), passed through for context.
+ * Map an HTTP response to the right error type. `body` is the parsed response
+ * body — ideally the structured `{error, code, retryable, message, detail?}`
+ * envelope, but may be a bare FastAPI `detail` string/array for routes that
+ * predate it. When a recognised `code` is present it takes priority over the
+ * HTTP status, because the status alone cannot distinguish e.g. a retryable
+ * version conflict from a non-retryable reference conflict — both are 409.
  */
-export declare function errorForStatus(status: number, detail?: unknown): AxonityApiError;
+export declare function errorForStatus(status: number, body?: unknown): AxonityApiError;

package/dist/errors.js

@@ -5,58 +5,202 @@
  * clean, actionable message to the agent — never a raw stack trace or an
  * opaque status code.
  */
+/** Codes where re-issuing the SAME request can succeed later. Mirrors `RETRYABLE_CODES`. */
+export const RETRYABLE_CODES = new Set([
+    "version_conflict",
+    "rate_limited",
+    "trigger_concurrency_exceeded",
+]);
+/** Recognise the structured `{error, code, retryable, message, detail?}` shape. */
+function asEnvelope(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return undefined;
+    const b = body;
+    return {
+        message: typeof b.message === "string" ? b.message : undefined,
+        code: typeof b.code === "string" ? b.code : undefined,
+        retryable: typeof b.retryable === "boolean" ? b.retryable : undefined,
+        detail: "detail" in b ? b.detail : undefined,
+        affectedEntities: "affectedEntities" in b ? b.affectedEntities : undefined,
+    };
+}
+/**
+ * Render the server's `detail` as a compact, readable line.
+ *
+ * FastAPI returns a bare string for a raised error and a list of
+ * `{loc, msg, type}` objects for a 422 schema rejection. The list form is what
+ * names the offending field, so it is flattened to `body.fieldName: message`
+ * rather than dumped as JSON — the agent has to act on it, not read it.
+ */
+export function describeDetail(detail) {
+    if (detail === undefined || detail === null)
+        return undefined;
+    if (typeof detail === "string")
+        return detail.trim() || undefined;
+    if (Array.isArray(detail)) {
+        const lines = detail
+            .map((item) => {
+            if (typeof item === "string")
+                return item;
+            if (typeof item !== "object" || item === null)
+                return String(item);
+            const { loc, msg, message } = item;
+            const where = Array.isArray(loc) ? loc.join(".") : undefined;
+            const what = typeof msg === "string" ? msg : typeof message === "string" ? message : undefined;
+            if (where && what)
+                return `${where}: ${what}`;
+            return what ?? where ?? JSON.stringify(item);
+        })
+            .filter(Boolean);
+        return lines.length ? lines.join("; ") : undefined;
+    }
+    if (typeof detail === "object") {
+        const { detail: nested, message } = detail;
+        if (typeof nested === "string")
+            return nested;
+        if (typeof message === "string")
+            return message;
+        return JSON.stringify(detail);
+    }
+    return String(detail);
+}
+/**
+ * Render a response body for a human, whether it's the new structured
+ * envelope, a bare FastAPI `detail` array/string, or something else entirely.
+ * Falls back to `describeDetail` when the body doesn't look like the envelope,
+ * so older/simpler error bodies still render exactly as before.
+ */
+function describeBody(body) {
+    const env = asEnvelope(body);
+    if (!env)
+        return describeDetail(body);
+    const parts = [];
+    if (env.message)
+        parts.push(env.message);
+    const detailText = describeDetail(env.detail);
+    if (detailText && detailText !== env.message)
+        parts.push(detailText);
+    if (Array.isArray(env.affectedEntities) && env.affectedEntities.length > 0) {
+        parts.push(`Affects: ${env.affectedEntities.map(String).join(", ")}`);
+    }
+    return parts.length ? parts.join(" ") : describeDetail(body);
+}
+/** Append the server's rendered body to a base message, when there is one. */
+function withDetail(base, body) {
+    const described = describeBody(body);
+    return described ? `${base} ${described}` : base;
+}
 export class AxonityApiError extends Error {
     status;
     detail;
+    code;
+    retryable;
     constructor(message, 
     /** HTTP status that produced this error. */
     status, 
-    /** Server-provided detail, when present. */
-    detail) {
+    /** The server's response body, when present (may be the structured envelope). */
+    detail, 
+    /** The envelope's `code`, when the server sent one — branch on this, not on `message`. */
+    code, 
+    /** Whether re-issuing the same request could succeed. `undefined` = unknown. */
+    retryable) {
         super(message);
         this.status = status;
         this.detail = detail;
+        this.code = code;
+        this.retryable = retryable;
         this.name = "AxonityApiError";
     }
 }
 /** 409 — the entity was modified since the agent read it. Re-read and retry. */
 export class VersionConflictError extends AxonityApiError {
-    constructor(detail) {
-        super("Version conflict: the entity changed since you read it. Read it again to " +
-            "get the current version, then re-apply your change.", 409, detail);
+    constructor(body) {
+        const env = asEnvelope(body);
+        super(withDetail("Version conflict: the entity changed since you read it. Read it again to " +
+            "get the current version, then re-apply your change.", body), 409, body, env?.code ?? "version_conflict", env?.retryable ?? true);
         this.name = "VersionConflictError";
     }
 }
-/** 401 — the service token is missing, unknown, or revoked. */
+/**
+ * 409 — the entity is referenced by something published or live. Both this and
+ * `VersionConflictError` are HTTP 409; the `code` is what tells them apart, and
+ * it matters: retrying THIS one can never succeed on its own.
+ */
+export class ReferenceConflictError extends AxonityApiError {
+    constructor(body) {
+        const env = asEnvelope(body);
+        super(withDetail("Reference conflict: this entity is referenced by something published or " +
+            "live. This is NOT a stale-read problem — re-reading and retrying will " +
+            "never succeed. Detach the reference, or unpublish the referencing " +
+            "entity, then try again.", body), 409, body, env?.code ?? "reference_conflict", env?.retryable ?? false);
+        this.name = "ReferenceConflictError";
+    }
+}
+/** 404 — no such entity in this tenant (or it was deleted). */
+export class NotFoundError extends AxonityApiError {
+    constructor(body) {
+        const env = asEnvelope(body);
+        super(withDetail("Not found (404): no such entity in this tenant. Check the id, or list " +
+            "the collection to find it. A deleted entity also reads as not found — " +
+            "list_deleted_* first if you suspect that.", body), 404, body, env?.code ?? "not_found", env?.retryable ?? false);
+        this.name = "NotFoundError";
+    }
+}
+/** 401 — the service token is missing, unknown, expired, or revoked. */
 export class AuthError extends AxonityApiError {
-    constructor(detail) {
-        super("Authentication failed (401): the service token is missing, invalid, or revoked. " +
-            "Check AXONITY_TOKEN, or mint a new token in Axonity → Settings → API tokens.", 401, detail);
+    constructor(body) {
+        const env = asEnvelope(body);
+        super(withDetail("Authentication failed (401): the service token is missing, invalid, expired, " +
+            "or revoked. The backend deliberately returns the same message for all four " +
+            "causes, so do not guess which one it is and do not retry — tell your human " +
+            "the token is dead and a new one must be minted in Axonity → Settings → API tokens.", body), 401, body, env?.code ?? "unauthorized", env?.retryable ?? false);
         this.name = "AuthError";
     }
 }
 /** 403 — the token lacks the scope for this action (e.g. read-only on a write). */
 export class ForbiddenError extends AxonityApiError {
-    constructor(detail) {
-        super("Forbidden (403): this service token is not allowed to perform that action. " +
-            "A read-only token cannot create, update, or request-publish.", 403, detail);
+    constructor(body) {
+        const env = asEnvelope(body);
+        super(withDetail("Forbidden (403): this service token is not allowed to perform that action. " +
+            "A read-only token cannot create, update, delete, or request-publish, and no " +
+            "token may publish directly — use request_publish_* and let a human approve.", body), 403, body, env?.code ?? "forbidden", env?.retryable ?? false);
         this.name = "ForbiddenError";
     }
 }
 /**
- * Map an HTTP response to the right error type. `detail` is the parsed body
- * (FastAPI returns `{ detail: … }`), passed through for context.
+ * Map an HTTP response to the right error type. `body` is the parsed response
+ * body — ideally the structured `{error, code, retryable, message, detail?}`
+ * envelope, but may be a bare FastAPI `detail` string/array for routes that
+ * predate it. When a recognised `code` is present it takes priority over the
+ * HTTP status, because the status alone cannot distinguish e.g. a retryable
+ * version conflict from a non-retryable reference conflict — both are 409.
  */
-export function errorForStatus(status, detail) {
+export function errorForStatus(status, body) {
+    const env = asEnvelope(body);
+    switch (env?.code) {
+        case "version_conflict":
+            return new VersionConflictError(body);
+        case "reference_conflict":
+            return new ReferenceConflictError(body);
+        case "not_found":
+            return new NotFoundError(body);
+        case "unauthorized":
+            return new AuthError(body);
+        case "forbidden":
+        case "admin_session_required":
+            return new ForbiddenError(body);
+    }
     switch (status) {
         case 401:
-            return new AuthError(detail);
+            return new AuthError(body);
         case 403:
-            return new ForbiddenError(detail);
+            return new ForbiddenError(body);
+        case 404:
+            return new NotFoundError(body);
         case 409:
-            return new VersionConflictError(detail);
+            return new VersionConflictError(body);
         default:
-            return new AxonityApiError(`Axonity API request failed (${status}).`, status, detail);
+            return new AxonityApiError(withDetail(`Axonity API request failed (${status}).`, body), status, body, env?.code, env?.retryable);
     }
 }
 //# sourceMappingURL=errors.js.map