@axonity-ai/mcp 0.6.0 → 0.8.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.
@@ -102,12 +143,32 @@ across these routes — the tool parameter names say which.
   `update_connector` — `authConfig` must be placeholders only; a human fills real
   secrets in Axonity. (`create_tool`/`update_tool` carry the same guard, so a
   connector authored either way is covered.)
+- **Toolboxes** (the group a tool is filed under): `list_toolboxes`,
+  `create_toolbox`, `update_toolbox`, `delete_toolbox`, `set_toolbox_tools`,
+  `assign_tool_toolbox`, `set_toolbox_auth`, `list_toolbox_dependent_tools`.
+  Read `list_toolboxes` before `create_tool` and pass `toolboxId` — a tool made
+  without one is ungrouped. Three things worth knowing before you write:
+  `set_toolbox_tools` **declares** the membership (anything you leave out is
+  evicted — `assign_tool_toolbox` moves a single tool and takes `null` to
+  ungroup); a box never changes what an agent may *call*, only how a tool is
+  *advertised* (agents link to individual tools, never to a box); and deleting a
+  box leaves its tools alive, ungrouped. `set_toolbox_auth` sets the credential a
+  box's tools share and carries the same placeholder guard as a connector.
 - **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`.
+  `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 +180,46 @@ 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.
+- **The deploy, the tenant and its queues** (read-only): `read_deploy_contract`
+  (what this backend actually mounts — read it when a call fails in a way that
+  smells like a version mismatch), `list_users` (where an `ownerId` comes from),
+  `list_audit_events` (pass `actorKind: "service_token"` to read back what
+  external agents — including you — changed), `read_queue_overview`,
+  `list_in_flight_runs`, `read_task_queue_summary`, `list_task_queue`,
+  `read_task_queue_item`, `export_task_queue`, plus `read_model_tier_map` (what
+  `capabilityTier` resolves to), `read_concurrency_status`,
+  `read_concurrent_run_cap` and `read_for_each_rate`. Together these answer *why
+  is my run not moving* without asking a human to look at a screen. Every write
+  in these families — purging or replaying queue work, changing a cap or the
+  tier map, importing a tenant bundle, reading someone's notifications — is
+  deliberately absent and recorded in `test/exclusions.test.ts`.
+- **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.
@@ -148,6 +242,24 @@ across these routes — the tool parameter names say which.
 (plus `update_conditional_trigger`). Trigger deletes are **hard** deletes with
 no restore, and a webhook token is shown **once** at create or rotate.
 
+**A schedule is a claim you can now check.** `run_cron_schedule_now` fires one
+immediately *without* moving `nextFireAt` — testing a schedule must not consume
+the run it was going to make. Before it existed, "every weekday at 07:00" could
+only be tested by coming back tomorrow, and what is usually wrong is not the
+timing but whether it starts anything at all.
+
+**To pause a schedule, disarm it** — `set_cron_schedule_enabled`, not
+`delete_cron_schedule`. Deleting throws away the rules the author wrote and
+makes "stop this for a week" indistinguishable from "we do not do this any
+more". `list_all_cron_schedules` answers *what runs tonight?* across the tenant;
+`reconcile_cron_schedules` answers *is that actually what runs?* — it reports
+rather than tidying silently, and never arms something someone switched off.
+
+`create_cron_schedule` takes either `cronExpr` or the richer `rules`, and the
+trigger must exist in the **published** document. Rule shapes come from
+`get_workflow_authoring_spec` → `scheduleRuleKinds`; this connector names none
+of its own.
+
 ### Runs — evaluating what you built
 
 `start_workflow_run` (test a workflow you built — it runs the **published**
@@ -157,14 +269,66 @@ 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.
 
-`list_workflow_runs({ workflowId, archivedOnly?, limit?, cursor? })` returns one
+**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.
+
+**Start from the outline.** `read_run_outline` is the run's table of contents —
+the run, its steps, and the items a fan-out handed out, flat with parent
+pointers. It carries no bodies, so its size follows the run's *shape* rather
+than its content: a launch over four thousand items costs about what one over
+four costs. `itemCap` bounds the items listed per fan-out step and the remainder
+is counted in `counts.truncated`, never dropped silently. Then open only what
+you want: `read_run_value` for one large step value (by the digest in
+`stepStates`) and `read_run_invocation_messages` for one agent's transcript (by
+the id in `agentInvocations`). Reading a whole run to find one message is the
+habit these replace.
+
+**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`, together
+with stopping runs in bulk (admin), the tenant's storage footprint (admin), an
+inbound channel reply (authenticated by the email/WhatsApp adapter, not by a
+service token) and the retired `workflow-memory` placeholder.
+
+**`list_todo_steps`** is the same question across the whole tenant: every step
+waiting on a human, in any run. It is paged over the waiting **runs**, so
+`items` can be longer than `pageSize` — one run may park several steps. Follow
+`nextCursor` to the end before concluding anything about how much is waiting.
+
+**What an agent wrote to itself.** `list_run_session_memory` lists the files an
+agent left during a run (metadata only, up to 200 per run) and
+`read_run_session_memory_file` opens one. When the trace shows a decision but
+not what it was reading, the reason is usually here. Workflow-bound reference
+material is not — that lives in `reference_docs`.
+
+**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
-*not* paged this way — it answers with a bare array, capped at 200, walked with
-`offset`.
+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
 
@@ -173,6 +337,23 @@ entry carrying `forEachProgress`. `list_runs` is the tenant-wide list and is
 `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,
@@ -202,19 +383,34 @@ 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
   diverges (see `test/fixtures/README.md`).
+- **Every backend route is decided, and the build says so.**
+  `test/completeness.test.ts` partitions all 444 operations in the pinned
+  snapshot into *covered by a tool* or *excluded by a rule that carries a
+  written reason*, and fails on anything in neither. A route nobody has decided
+  about is indistinguishable from one somebody is still working on, which is
+  what made "is this connector finished?" a question you could only answer with
+  an audit. It is now a build status: a new backend route arrives as a red build
+  asking **cover it, or exclude it with a reason?**
 
 **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
@@ -236,6 +432,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).
@@ -257,3 +465,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,109 @@
+/**
+ * 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>;
+/**
+ * Argument overlays the replay runs IN ADDITION to `PROBE_ARGS` alone.
+ *
+ * A blind sweep with one fixed argument set is a LOWER bound on what the tools
+ * reach, and the gap is not evenly spread: a handful of tools pick their route
+ * FROM an argument, so one probe pass sees one of their routes and misses the
+ * rest. `list_templates` chooses between four catalogue paths on `kind`;
+ * `list_dependent_agents` and `list_workflows_using` choose on `entityKind`;
+ * `validate_workflow` takes EXACTLY ONE of `workflowId`/`document`, so the base
+ * set — which supplies both — makes it fire nothing at all.
+ *
+ * That under-reporting is not theoretical. It made a coverage audit name three
+ * template routes as uncovered when `list_templates` had reached them all
+ * along. A measurement that quietly reads low is worse than no measurement,
+ * because it generates work that did not need doing.
+ *
+ * Each overlay is merged over `PROBE_ARGS` and replayed as its own pass. An
+ * `undefined` value REMOVES an argument, which is how the two shapes of
+ * `validate_workflow` are reached.
+ */
+export declare const PROBE_VARIANTS: 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">;