@axonity-ai/mcp 0.5.0 → 0.7.0

package/README.md

@@ -40,10 +40,16 @@ tenant + scope on every call, so the connector is not a trust boundary.
 
 ## Tools
 
-200+ tools total. `axonity_conventions` (read this first) covers the authoring
+220+ 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.
 
+What the connector does **not** state is as deliberate as what it does: the
+mutation commands, the step types, the trigger types, the schedule-rule shapes
+and the three value vocabularies are all read live from
+`get_workflow_authoring_spec`, because every one of those lists drifted while it
+was kept here. A conformance test asserts their absence.
+
 ### The generic entity family
 
 Ten entities — **workflow, agent, tool, skill, policy, reference_doc, persona,
@@ -65,12 +71,45 @@ entity gets every verb (see the per-entity notes below for the exceptions):
 Exceptions: `persona` has no `create_persona` (create only via
 `create_agent_persona`).
 
+Some list routes narrow in the query, which is where narrowing belongs — the
+backend applies it before the rows come back:
+`list_workflows({ stageId?, capabilityId? })`,
+`list_agents({ includeSystem? })`,
+`list_policies({ scope?, ownerId? })`,
+`list_reference_docs({ scope?, ownerId? })`,
+`list_prompt_snippets({ deleted? })`.
+
+That table is **generated** from the pinned schema's own query parameters
+(`npm run generate:filters` → `src/generated/listFilters.ts`), not hand-listed.
+A filter the backend adds is exposed as soon as the snapshot is refreshed, and
+a test fails if the two have parted. The argument names are camelCase; the wire
+keeps whatever spelling each route declares, which is not consistent between
+them and is not something a caller should have to know.
+
 Plus:
+- `get_workflow_authoring_spec` — everything **this deploy** can be built from,
+  read live from the server (`GET /workflows/operations`): the mutation
+  `operations`, the `triggerTypes`, the `stepTypes` (including the ones you may
+  not author, each with the reason and what to write instead), the
+  `scheduleRuleKinds` (each with an example the backend round-trips through its
+  own parser as it serves it), and **three vocabularies for a value's type that
+  are not interchangeable** — `parameterTypes` (a trigger parameter's or
+  workflow constant's `type`), `outputKinds` (a step output's or input's
+  `kind` — narrower, *different key*) and `schemaFieldKinds` (inside a field's
+  `schema`, which wins where present). Getting that last group wrong is silent:
+  a `kind` written on a trigger parameter is not a 422, it is a key nothing
+  reads, so the value falls back to text. Every list is generated from the
+  registry that *enforces* it, so the connector states none of them and a new
+  value is discoverable without a release here. `operations` is an index by
+  default; pass `types` for a command's live payload schema. `rulesVersion` is
+  a content hash over all seven — same hash, nothing to re-fetch.
 - `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.
+- `read_workflow_trigger_parameters` — how to start the workflow:
+  `{ triggers, constants }`, every start with its own parameters and a `pinned`
+  flag marking the values the author owns.
 - `bulk_delete_workflows` — soft-delete several at once (each with its own
   `expectedVersion`).
 
@@ -87,7 +126,9 @@ For the ten versioned entities (including `flow`):
 | `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). |
+| `create_<entity>_major_version` | Cut a new **named** major version — "Save As" on the current draft. |
+| `ensure_<entity>_major_version` | Make sure a working draft major version exists. Idempotent. |
+| `name_<entity>_major_version` | Rename an existing major version (label a release). |
 
 `{version}` (an int) and `{versionId}` (a UUID) are two different identifiers
 across these routes — the tool parameter names say which.
@@ -107,7 +148,16 @@ across these routes — the tool parameter names say which.
   `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`.
+  `list_agent_reference_docs` and `list_workflow_skills`. The three agent
+  read-backs take an optional `workflowId` for the **composed runtime view** —
+  what the agent's prompt actually assembles inside that workflow, with a
+  `linkSource` per row saying why each item is there.
+- **What uses this?**: `list_workflows_using({ entityKind, entityId })` names
+  the workflows that reference a tool, agent, flow, output schema or workflow,
+  **and the steps they reference it in**, with `draft`/`published` per hit.
+  `list_dependent_agents({ entityKind, entityId })` is the same question for a
+  skill, policy or reference doc. Ask before editing anything shared — the
+  alternative is validating every workflow in the tenant.
 - **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
@@ -119,13 +169,33 @@ across these routes — the tool parameter names say which.
 - **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
+  `name_company_major_version`, `create_company_major_version`,
+  `ensure_company_major_version`, `read_company_published`,
+  `apply_company_mutation` (one validated, version-safe command — preferred
+  over the whole-document `update_company`, the same way
+  `apply_workflow_mutations` is preferred for a workflow), and
   `request_publish_company` (takes no id — the
   server resolves your tenant's one company; direct company publish is closed to
   service tokens).
+- **Subworkflows**: `list_callable_workflows` — which workflows a `subprocess`
+  step may call, each with its `parameters` and `outcomes`, and a
+  `blockedReason` for the ones that cannot (never published, or no
+  `subprocess-invocation` trigger). Authoring both halves is ordinary
+  `apply_workflow_mutations` work — a callable workflow's signature goes into
+  the `add_trigger` call itself. `validate_workflow` **does** check a subprocess
+  target now (missing, self-call, deleted, unpublished, not callable), but
+  `list_callable_workflows` is still what you run first: it is how you pick a
+  target and read the interface you are binding to.
+- **Secrets** (read-only): `list_secrets`, `read_secret` — the catalogue a
+  connector's `authConfig.secretId` points at. Values are never returned by any
+  Axonity route; `valueKeys` says which keys a human has filled in, so you can
+  tell an unfinished secret from a finished one before wiring to it. Creating or
+  changing a secret is a human act in Axonity (#39).
 - **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`.
+  `clone_flow`, `clone_prompt_snippet`, `list_tool_packages` (the import
+  allowlist `validate_tool_code` judges against), `list_templates` /
+  `read_template`.
 - `list_deleted_prompt_snippets` calls `/api/v1/prompt-snippets/deleted`; the
   backend returns it as `{ items: [... ] }`, and the tool forwards that response
   unchanged.
@@ -157,6 +227,42 @@ workflow and really executes), `cancel_run`, `delete_run`, `list_runs`,
 `bulk_delete_runs`. There is no findings endpoint — evaluation means reading a
 run's validator verdicts and its trace.
 
+**Which start, and what it wants.** `read_workflow_trigger_parameters` answers
+`{ triggers, constants }` — every way the workflow can be started, each with its
+own parameters. Pass the one you mean to `start_workflow_run` as `triggerId`;
+omitting it fires the first, which on a workflow with a button *and* a schedule
+is an arbitrary choice. A parameter marked `pinned` is one the **author** owns:
+it is overwritten on every run, so a caller must not send it.
+
+**`read_run` omits the workflow snapshot by default.** It is immutable, it is
+never the answer to a question about the run, and it measured 81% of one real
+response — an oversized response turns a call that succeeded into an error.
+Pass `includeSnapshot: true` when you actually want to see what executed.
+
+**A run can park rather than finish.** `read_run_waiting_on` says what it is
+waiting for; `answer_run_question` answers an `ask_user` step and
+`send_run_message` sends a turn to a conversation run. Both record the input as
+a person's, so use them on runs you started. Deciding a **plan approval** and
+restarting a stuck run are deliberately absent — the first is the human review
+the step exists to get, the second is `require_admin` and a service token is
+always `role="member"`. Both are recorded in `test/exclusions.test.ts`.
+
+**Inside a launch**: `read_run_items_summary` is the roll-up ("4,415 processed ·
+12 failed"), `list_run_items({ outcome })` the paged rows — filter in the query,
+because the failures are scattered and sifting page one finds none of them.
+`list_run_tasks` and `read_run_for_each_progress` cover the children a run set
+in motion.
+
+`list_workflow_runs({ workflowId, status?, archivedOnly?, limit?, cursor? })` returns one
+**page** — `{ items, nextCursor, pageSize, hasMore }`, 20 by default and 200 at
+most — so follow `nextCursor` while `hasMore` is true rather than treating the
+first page as the answer. It also lists **launches**, not runs: the per-item runs
+a FOR EACH creates stay inside their launch, so a launch over 4,415 people is one
+entry carrying `forEachProgress`. `list_runs` is the tenant-wide list and is now
+paged the same way — `{ items, nextCursor, pageSize, hasMore }`, walked with
+`cursor`. It stopped answering with a bare array when the backend converted the
+route; the `offset` it used to take is no longer read.
+
 ### Approvals
 
 `list_publish_approvals({ status?, limit?, offset? })` and
@@ -164,6 +270,23 @@ run's validator verdicts and its trace.
 `request_publish_*` was approved or rejected. Approving and rejecting are
 human-only actions in Axonity.
 
+`request_publish_release({ workflowId, changeSummary? })` proposes a **release**:
+a workflow *and everything its run needs* — the agents it runs, their tools and
+personas, the flows it pins, the memory scoped to those agents — as ONE approval.
+Prefer it over a request per entity. Taking a tenant live entity-by-entity means
+a hundred-odd approvals, none of which means anything on its own, and a human
+asked that many times is not reviewing. `list_publish_releases` and
+`get_publish_release` read one back — the release's members, and its readiness
+recomputed as of now.
+
+Unlike `request_publish_bulk`, a release is **all-or-nothing and in dependency
+order**: approving it publishes every member or none, so a workflow can never go
+live calling a tool that did not. The response carries the bundle's verdict —
+`ready`, `changedCount` of `totalCount` (unchanged members are already live and
+ride along), `members` with why each is there, and `blockers` that name the
+member in the way. Requesting is ours; deciding stays human, like everywhere
+else here.
+
 ## What this is for — and what it is not
 
 **Authoring.** An agent composing an entity from intent: drafting a workflow,
@@ -193,15 +316,22 @@ These are enforced by the backend, not merely by convention:
 - **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.
+  (`/api/v1/secrets`) are **readable and unwritable**: `list_secrets` /
+  `read_secret` give the catalogue and `valueKeys` (which keys are filled, never
+  their values) so an agent can point `authConfig.secretId` at the right entry,
+  and no tool can create, change or delete one — the backend refuses a service
+  token there too. A secret's `metadata` is stored unencrypted and readable
+  tenant-wide (axonity-flow#908), so credential-shaped entries in it are
+  withheld on read and listed under `metadataRedacted`.
 - **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`).
+  surface and fails the build if any tool targets a publish / approve /
+  secret-write / service-token / deploy route (`test/exclusions.test.ts`). The
+  rules are method-aware: `GET /api/v1/secrets` is allowed, every write verb on
+  it is not.
 - **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
@@ -227,6 +357,18 @@ Publishing runs from a maintainer's machine, not from CI. npm restricts tokens
 that bypass 2FA for direct publishing, so a stored `NPM_TOKEN` cannot ship this
 package; `npm login` is the supported path.
 
+**Check the contract first.** Shipping with a stale snapshot is how the
+connector fell nine operations behind the backend without any test noticing:
+
+```bash
+npm run check:contract          # expects ../axonity-flow; override with AXONITY_FLOW_PATH
+```
+
+It dumps the schema from a local `axonity-flow` checkout and diffs it against
+`test/fixtures/openapi.snapshot.json`, naming every operation that moved. It
+runs here rather than in the release workflow because the publish itself runs
+here — a gate in CI cannot stop a local `npm publish`.
+
 Run `npm login` in a real terminal — it prints a URL and waits for you to finish
 in the browser, so it needs a session that stays attached (an editor's 2-minute
 command timeout will kill it mid-flow).
@@ -248,3 +390,32 @@ was cut from a state CI cannot install.
 
 Keep npm 11 locally: Node 20 bundles npm 10, whose resolver writes an
 incompatible lockfile tree. CI pins npm 11 for the same reason.
+
+## Staying level with the backend
+
+The snapshot every drift guard reads is only as fresh as the last time someone
+regenerated it — and once it wasn't: it sat nine operations behind the backend
+while the whole suite stayed green, because a snapshot that has not seen a route
+cannot report it missing.
+
+**Before a release, check it** (see §Releasing): `npm run check:contract` dumps
+the schema from a local `axonity-flow` checkout and names every operation that
+moved. It compares the contract surface — query parameters, request body,
+response shape — and not descriptions, so backend docstring churn does not cry
+wolf. This is the gate that counts, because the publish runs here too.
+
+**At startup, the connector asks the deploy what it mounts.** It calls
+`GET /api/v1/contract` once before accepting its first tool call and, if this
+backend lacks a route this build needs, says which on stderr — instead of
+failing on the twentieth call, mid-task. It is a diagnostic and never a
+dependency: a backend too old to serve `/contract`, an unreachable one, or a
+slow one all degrade to the previous behaviour and the connector starts
+normally. The result is cached on the `contractHash` the route returns, so an
+unchanged deploy costs one request.
+
+**Not here: a scheduled job.** Watching for drift on a timer belongs in
+`axonity-flow`, not in this repository. The schema lives there, its CI already
+has the backend's dependencies installed, and it can read this repository's
+pinned snapshot over plain HTTPS because this repository is public — where the
+reverse needs a credential for a private repo, with an approval policy and an
+expiry behind it. Tracked in axonity-mcp#48.

package/dist/client.d.ts

@@ -8,8 +8,20 @@
  */
 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>;
+/** One scalar a query parameter may carry. */
+type QueryScalar = string | number | boolean;
+/**
+ * Query-string values a route may take. `undefined` entries are omitted.
+ *
+ * An ARRAY is serialised the way FastAPI reads a `list[…]` query parameter:
+ * the key REPEATED, once per element (`?status=pending&status=running`). Not
+ * every list-shaped filter on the backend is spelled that way — `GET /runs`
+ * takes its statuses as one comma-separated string while
+ * `GET /workflows/{id}/runs` repeats the key — so the caller picks the shape
+ * its route actually declares. An empty array contributes nothing, which is
+ * what "no filter" means.
+ */
+export type Query = Record<string, QueryScalar | QueryScalar[] | undefined>;
 export declare class AxonityClient {
     private readonly config;
     constructor(config: AxonityConfig);
@@ -31,3 +43,4 @@ export declare class AxonityClient {
      */
     del<T = unknown>(path: string, query?: Query): Promise<T>;
 }
+export {};

package/dist/client.js

@@ -18,8 +18,15 @@ export class AxonityClient {
             return base;
         const params = new URLSearchParams();
         for (const [key, value] of Object.entries(query)) {
-            if (value !== undefined)
+            if (value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    params.append(key, String(item));
+            }
+            else {
                 params.set(key, String(value));
+            }
         }
         const qs = params.toString();
         return qs ? `${base}?${qs}` : base;

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/contract.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Asking the deploy what it can do, once, at startup (axonity-mcp#48 M2).
+ *
+ * `src/errors.ts` already turns a 404/405 into a "backend version skew" message
+ * — but only AFTER the call has failed, which means a user is mid-task on the
+ * one call that mattered. And it decides which 404s count from `ROUTES_ADDED_IN`,
+ * a list this repository keeps by hand about routes the server owns. That is the
+ * shape of #32 and #44, and it has the same failure mode: a route added here
+ * without an entry there reports as "no such id" forever.
+ *
+ * `GET /api/v1/contract` (axonity-flow#806) is the proactive replacement. It
+ * returns every mounted route, derived from the running app so it cannot drift,
+ * plus a hash to cache on. It is authenticated but TENANT-AGNOSTIC — a
+ * read-only service token is enough, so this check never needs write scope.
+ *
+ * WHAT THIS DOES NOT DO: fail. A connector that refuses to start because it
+ * could not reach a diagnostic endpoint is worse than the drift it reports —
+ * every path here degrades to today's behaviour, including a backend too old to
+ * serve `/contract` at all. Everything it says goes to STDERR, because stdout is
+ * the MCP channel and a stray byte there breaks the protocol.
+ */
+import type { AxonityClient } from "./client.js";
+/** `GET /api/v1/contract`. `routes` are "METHOD /path/{template}" strings. */
+export interface ContractResponse {
+    buildVersion?: unknown;
+    environment?: unknown;
+    routes?: unknown;
+    contractHash?: unknown;
+}
+/** The minimal `.tool()` surface the registrar needs — same shape as index.ts. */
+export interface ProbeServer {
+    tool: (name: string, description: string, schema: Record<string, unknown>, handler: (args: never) => Promise<unknown>) => void;
+}
+/**
+ * One filled-in value per argument name any tool takes, so a blind replay
+ * reaches as much of the route surface as possible.
+ *
+ * This is how the connector knows which routes it needs WITHOUT keeping a list
+ * of them: it runs its own tools against a recording client and watches. A
+ * hand-written route list would be the very thing #48 M2 exists to delete.
+ *
+ * Shared with `conformance.test.ts` and `exclusions.test.ts` deliberately. They
+ * each carried their own copy, the copies had to be edited in lockstep, and a
+ * probe fixture that has drifted silently narrows what the sweep reaches.
+ */
+export declare const PROBE_ARGS: Record<string, unknown>;
+/** A route a tool actually called, as observed by the recording client. */
+export interface CalledRoute {
+    method: string;
+    path: string;
+}
+/**
+ * Every route this build's tools call, found by replaying them.
+ *
+ * Nothing leaves the process: the client is a recorder. A handler that rejects
+ * the probe arguments is simply skipped — it contributes no route, which makes
+ * this a LOWER bound on what the connector needs and therefore safe: the check
+ * can miss a route, but it cannot invent one.
+ */
+export declare function collectCalledRoutes(register: (server: ProbeServer, client: AxonityClient) => void): Promise<CalledRoute[]>;
+/** Does a concrete path match a "METHOD /a/{b}/c" contract entry? */
+export declare function matchesRoute(call: CalledRoute, entry: string): boolean;
+/**
+ * Routes this build needs that the deploy does not mount, as "METHOD /path".
+ *
+ * Deduplicated by template rather than by concrete path: `read_workflow` and
+ * `update_workflow` both hit `/workflows/{id}`, and reporting one absence twice
+ * makes a short list look like an emergency.
+ */
+export declare function missingFromContract(calls: CalledRoute[], routes: string[]): string[];
+export interface ContractCheckOptions {
+    /** Base URL, used to key the cache so two tenants do not share a verdict. */
+    apiUrl: string;
+    /** Where to write the report. Defaults to stderr — stdout is the MCP channel. */
+    log?: (message: string) => void;
+    /** How long to wait before giving up on the check. Defaults to 5s. */
+    timeoutMs?: number;
+    /** Skip the cache. Used by tests, and by a caller that wants a fresh verdict. */
+    ignoreCache?: boolean;
+}
+/**
+ * Ask the deploy what it mounts, and say — once, at startup — whether this
+ * build needs anything it does not have.
+ *
+ * Returns what it concluded, so a caller (and a test) can tell "checked, all
+ * present" from "could not check". Never throws.
+ */
+export declare function reportContractSkew(client: AxonityClient, register: (server: ProbeServer, client: AxonityClient) => void, options: ContractCheckOptions): Promise<"ok" | "missing" | "unavailable" | "cached" | "timeout">;

package/dist/contract.js

@@ -0,0 +1,227 @@
+/**
+ * Asking the deploy what it can do, once, at startup (axonity-mcp#48 M2).
+ *
+ * `src/errors.ts` already turns a 404/405 into a "backend version skew" message
+ * — but only AFTER the call has failed, which means a user is mid-task on the
+ * one call that mattered. And it decides which 404s count from `ROUTES_ADDED_IN`,
+ * a list this repository keeps by hand about routes the server owns. That is the
+ * shape of #32 and #44, and it has the same failure mode: a route added here
+ * without an entry there reports as "no such id" forever.
+ *
+ * `GET /api/v1/contract` (axonity-flow#806) is the proactive replacement. It
+ * returns every mounted route, derived from the running app so it cannot drift,
+ * plus a hash to cache on. It is authenticated but TENANT-AGNOSTIC — a
+ * read-only service token is enough, so this check never needs write scope.
+ *
+ * WHAT THIS DOES NOT DO: fail. A connector that refuses to start because it
+ * could not reach a diagnostic endpoint is worse than the drift it reports —
+ * every path here degrades to today's behaviour, including a backend too old to
+ * serve `/contract` at all. Everything it says goes to STDERR, because stdout is
+ * the MCP channel and a stray byte there breaks the protocol.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AxonityApiError, ROUTES_ADDED_IN } from "./errors.js";
+/**
+ * One filled-in value per argument name any tool takes, so a blind replay
+ * reaches as much of the route surface as possible.
+ *
+ * This is how the connector knows which routes it needs WITHOUT keeping a list
+ * of them: it runs its own tools against a recording client and watches. A
+ * hand-written route list would be the very thing #48 M2 exists to delete.
+ *
+ * Shared with `conformance.test.ts` and `exclusions.test.ts` deliberately. They
+ * each carried their own copy, the copies had to be edited in lockstep, and a
+ * probe fixture that has drifted silently narrows what the sweep reaches.
+ */
+export const PROBE_ARGS = {
+    id: "x", workflowId: "x", agentId: "x", toolId: "x", runId: "x", approvalId: "x",
+    flowId: "x", snippetId: "x", flowStepId: "x", linkId: "x", webhookId: "x",
+    scheduleId: "x", triggerId: "x", secretId: "x", versionId: "x", version: 1,
+    majorVersion: 1, expectedVersion: 1, displayOrder: 0, name: "x",
+    cronExpr: "0 0 * * *", conditionText: "x", repeatIntervalMinutes: 5,
+    target: "system", confirm: true, document: {}, fields: {},
+    mutations: [{ type: "add_step", payload: {} }], snippetIds: ["a"], runIds: ["a"],
+    workflows: [{ id: "x", expectedVersion: 1 }],
+    functions: [{ name: "f", code: "def f(): pass" }], code: "x",
+    requests: [{ entityType: "tool", entityId: "x" }],
+    entityKind: "skill", entityId: "x", batchId: "x", stepId: "x", answer: "x",
+    message: "x", templateId: "x", releaseId: "x", payload: {},
+};
+/**
+ * Every route this build's tools call, found by replaying them.
+ *
+ * Nothing leaves the process: the client is a recorder. A handler that rejects
+ * the probe arguments is simply skipped — it contributes no route, which makes
+ * this a LOWER bound on what the connector needs and therefore safe: the check
+ * can miss a route, but it cannot invent one.
+ */
+export async function collectCalledRoutes(register) {
+    const calls = [];
+    const record = (method) => async (path) => {
+        calls.push({ method, path });
+        return {};
+    };
+    const recorder = {
+        get: record("GET"),
+        post: record("POST"),
+        put: record("PUT"),
+        patch: record("PATCH"),
+        del: record("DELETE"),
+    };
+    const handlers = [];
+    register({ tool: (_n, _d, _s, handler) => handlers.push(handler) }, recorder);
+    for (const handler of handlers) {
+        try {
+            await handler(PROBE_ARGS);
+        }
+        catch {
+            /* Arg-shape mismatch is fine — only routes that fired are collected. */
+        }
+    }
+    return calls;
+}
+/** Split a path into segments, dropping any query string. */
+function segments(path) {
+    return path.split("?")[0].replace(/^\/+|\/+$/g, "").split("/");
+}
+/** Does a concrete path match a "METHOD /a/{b}/c" contract entry? */
+export function matchesRoute(call, entry) {
+    const space = entry.indexOf(" ");
+    if (space < 0)
+        return false;
+    if (entry.slice(0, space).toUpperCase() !== call.method.toUpperCase())
+        return false;
+    const template = segments(entry.slice(space + 1));
+    const actual = segments(call.path);
+    return (template.length === actual.length &&
+        template.every((part, i) => (part.startsWith("{") && part.endsWith("}")) || part === actual[i]));
+}
+/**
+ * Routes this build needs that the deploy does not mount, as "METHOD /path".
+ *
+ * Deduplicated by template rather than by concrete path: `read_workflow` and
+ * `update_workflow` both hit `/workflows/{id}`, and reporting one absence twice
+ * makes a short list look like an emergency.
+ */
+export function missingFromContract(calls, routes) {
+    const missing = new Set();
+    for (const call of calls) {
+        if (routes.some((entry) => matchesRoute(call, entry)))
+            continue;
+        missing.add(`${call.method} ${call.path}`);
+    }
+    return [...missing].sort();
+}
+/**
+ * What added a route, when this repository happens to know.
+ *
+ * `ROUTES_ADDED_IN` stops being a source of truth here and becomes ANNOTATION:
+ * the contract check has already established that a route is missing, and this
+ * only enriches the sentence. An entry that is absent costs a clause, not a
+ * wrong answer — which is the whole difference from using it to DECIDE whether
+ * a 404 counts.
+ */
+function attribute(route) {
+    const path = route.slice(route.indexOf(" ") + 1);
+    const known = ROUTES_ADDED_IN.find((entry) => entry.pattern.test(path));
+    return known ? `${route}  — added by ${known.addedBy}` : route;
+}
+/** Where the "already checked this contract" marker lives, per API URL. */
+function cachePath(apiUrl) {
+    // Not a security boundary and not precious: a lost cache costs one replay.
+    const key = Buffer.from(apiUrl).toString("base64url").slice(0, 40);
+    return join(tmpdir(), `axonity-mcp-contract-${key}.json`);
+}
+function readCachedHash(apiUrl) {
+    try {
+        const raw = JSON.parse(readFileSync(cachePath(apiUrl), "utf8"));
+        return typeof raw.contractHash === "string" ? raw.contractHash : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCachedHash(apiUrl, contractHash) {
+    try {
+        writeFileSync(cachePath(apiUrl), JSON.stringify({ contractHash }));
+    }
+    catch {
+        /* A cache that cannot be written is a slower startup, not a failure. */
+    }
+}
+/** Resolve `promise`, or `undefined` if it takes longer than `ms`. */
+async function withTimeout(promise, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(undefined), ms);
+                // Do not hold the process open for a check that is already too late.
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Ask the deploy what it mounts, and say — once, at startup — whether this
+ * build needs anything it does not have.
+ *
+ * Returns what it concluded, so a caller (and a test) can tell "checked, all
+ * present" from "could not check". Never throws.
+ */
+export async function reportContractSkew(client, register, options) {
+    const log = options.log ?? ((message) => console.error(message));
+    let contract;
+    try {
+        contract = await withTimeout(client.get("/api/v1/contract"), options.timeoutMs ?? 5_000);
+    }
+    catch (cause) {
+        // A backend too old to serve /contract must degrade to today's behaviour,
+        // not announce a problem it cannot substantiate. 404/405 is exactly that
+        // backend; anything else (401, network) will surface on the first real call
+        // with a better message than this check could write.
+        const status = cause instanceof AxonityApiError ? cause.status : 0;
+        if (status !== 404 && status !== 405 && status !== 0) {
+            log(`Axonity: could not read the backend contract (${status}). ` +
+                "Continuing — this is a diagnostic, not a dependency.");
+        }
+        return "unavailable";
+    }
+    if (contract === undefined)
+        return "timeout";
+    const routes = Array.isArray(contract.routes)
+        ? contract.routes.filter((entry) => typeof entry === "string")
+        : [];
+    if (routes.length === 0)
+        return "unavailable";
+    const hash = typeof contract.contractHash === "string" ? contract.contractHash : "";
+    if (!options.ignoreCache && hash && readCachedHash(options.apiUrl) === hash) {
+        return "cached";
+    }
+    const missing = missingFromContract(await collectCalledRoutes(register), routes);
+    if (missing.length === 0) {
+        // Only a CLEAN result is cached. Caching a problem would report it once and
+        // then go quiet, which is worse than never having checked.
+        if (hash)
+            writeCachedHash(options.apiUrl, hash);
+        return "ok";
+    }
+    const build = typeof contract.buildVersion === "string" ? contract.buildVersion : "unknown";
+    const environment = typeof contract.environment === "string" ? contract.environment : "unknown";
+    log(`Axonity: this backend does not have ${missing.length} route(s) this ` +
+        `connector needs.\n` +
+        `  Backend: ${build} (${environment}) at ${options.apiUrl}\n` +
+        missing.map((route) => `  - ${attribute(route)}`).join("\n") +
+        `\nThe backend is OLDER than this connector. Tools that use those routes ` +
+        `will fail; everything else works. Tell your human which Axonity ` +
+        `environment this token points at, or pin an older connector.`);
+    return "missing";
+}
+//# sourceMappingURL=contract.js.map