@axonity-ai/mcp 0.6.0 → 0.8.0

package/dist/tools/conventions.js

@@ -12,6 +12,22 @@
  * and the enums quoted below to a vendored snapshot of that schema, so a drift
  * between this prose and the backend fails CI rather than misleading an agent.
  * Keep enum lists in this doc in step with what that test asserts.
+ *
+ * BETTER STILL, DO NOT QUOTE A LIST AT ALL. Four vocabularies used to live here
+ * and every one of them drifted: the mutation commands (#32/#44), and then the
+ * step types, trigger types and schedule-rule shapes — this guide named nine
+ * step types where seven validate. All four are now read from
+ * `get_workflow_authoring_spec`, generated by the backend from the registries
+ * that ENFORCE them, and this document states none of those LISTS. A pinned
+ * list fails CI when it drifts; a list you never wrote cannot. When you are
+ * about to write out a set of accepted values here, point at the spec instead —
+ * `test/conformance.test.ts` asserts the absence.
+ *
+ * Naming ONE value to state behaviour is a different thing and stays: that
+ * `typeId: "subprocess-invocation"` is what makes a workflow callable is not
+ * something the catalogue can say — it can only say the id exists. The line is
+ * the one #44 drew: a mention is guidance, an enumeration is a claim about what
+ * exists, and it is the claim that goes stale.
  */
 const CONVENTIONS = `# Authoring conventions for Axonity entities
 
@@ -138,10 +154,14 @@ has run cleanly once, at its current version.
   undeclared OR MISSPELLED key is a 422 that names it, not a silent drop. So
   spelling matters and you get told when it is wrong — good. Other entities are
   more lenient and may drop an unknown key silently; never rely on that.
-- \`agent.tags\` is not cosmetic: it drives which policies apply to the agent at
-  runtime. An untagged agent looks correct everywhere in the UI and silently
-  skips policies scoped to those tags. If you create or update an agent that
-  should be governed by a policy, check its tags match what the policy expects.
+- \`agent.tags\` is a free label for grouping and reporting. It GATES NOTHING —
+  what reaches an agent's prompt is a LINK (\`attach_policy_to_agent\`), visible
+  in a table a human can read and edit. A role-tag gate on a policy used to
+  decide that invisibly and is refused outright now: sending
+  \`activation.tags\` to \`create_policy\`/\`update_policy\` is a 422. The two
+  surviving gates, \`activation.tools\` and \`activation.delegation\`, each say
+  something a link cannot — "only on turns where this agent holds this tool",
+  and "only when (not) delegated".
 
 ## After you write, verify
 - A 200 means the request was accepted, NOT that it did what you meant. Re-read
@@ -162,6 +182,19 @@ has run cleanly once, at its current version.
   (\`read_run\` / \`read_run_trace\` / \`read_run_cost\`). Note it runs the PUBLISHED
   workflow and really executes (cost, connector side effects), so publish first,
   and only test-run when a human is expecting it.
+  - Read \`read_workflow_trigger_parameters\` first and pass \`triggerId\`: a
+    workflow can have several starts, each with different fields, and omitting
+    it fires whichever comes first. Never send a parameter marked \`pinned\` —
+    the author owns that value and it is overwritten anyway.
+  - **A run can park instead of finishing.** A step that asks a question waits
+    for an answer, so "it never came back" usually means "it is waiting on you".
+    \`read_run_waiting_on\` says what for; \`answer_run_question\` (or
+    \`send_run_message\` on a conversation run) resumes it. Answer your own test
+    runs; on a run a human is depending on, the answer is theirs to give.
+  - A FOR EACH launch is not one result. \`read_run_items_summary\` is the
+    roll-up ("4,415 processed · 12 failed") and \`list_run_items\` the rows —
+    with \`outcome: "failed"\`, because the failures are scattered and filtering
+    page one finds none of them.
 - A LIST is not the whole list. \`list_workflow_runs\` returns a page —
   \`{ items, nextCursor, pageSize, hasMore }\`, 20 by default — so counting or
   concluding from page one while \`hasMore\` is true is how you answer confidently
@@ -224,14 +257,17 @@ made any time before you attach them.
     use rather than inventing one.
 - Complete check: the tool has the I/O schemas its callers need AND a non-empty
   implementation of the right shape for its type.
+- \`toolboxId\` files the tool in a toolbox on creation. Read \`list_toolboxes\`
+  BEFORE you create: a tool made without one is ungrouped, which is valid and
+  is also how nobody finds it. See Toolboxes below.
 
 ### agent  (\`create_agent\`, strict body)
 - Required: \`name\`. Enumerated fields, with their ONLY valid values:
   - \`capabilityTier\`: \`economy\` | \`standard\` (default) | \`smart\` | \`reasoning\`
   - \`creativityTier\`: \`low\` | \`medium\` (default) | \`high\`
   - \`learningMode\`: \`none\` (default) | \`adaptive\` | \`strict\`
-- \`avatar\`, \`tags\` (role tags — see Field shape; set them or policies silently
-  skip the agent), \`canOwnProcess\` (bool; must be true for an agent to own a
+- \`avatar\`, \`tags\` (free labels for grouping — they gate nothing; see Field
+  shape), \`canOwnProcess\` (bool; must be true for an agent to own a
   workflow step's flow), \`episodicMemoryEnabled\` (bool).
 - \`permissions\` (object): \`planning\`, \`delegation\`, \`verboseOutput\` (bools);
   \`outputValidators\` / \`exposedValidatorTools\` (snake_case specs, see Field
@@ -249,9 +285,14 @@ made any time before you attach them.
     (preferred: the backend validates each and threads the version), or
   - \`replace_workflow_document\` — a full-document atomic PUT.
 - The document is a graph: \`steps.all[]\` (each \`{ id, type, name, ... }\`) and
-  \`steps.edges[]\` (each \`{ id, from, to, type? }\`) plus \`triggers\`. Step
-  \`type\` is one of: \`manual\`, \`agent\`, \`automation\`, \`subprocess\`,
-  \`connector\`, \`decision\`, \`loop\`, \`for_each\`, \`end\`.
+  \`steps.edges[]\` (each \`{ id, from, to, type? }\`) plus \`triggers\`.
+- WHICH VALUES a step's \`type\` and a trigger's \`typeId\` may hold is answered
+  by \`get_workflow_authoring_spec\`, read live from this deploy. This guide
+  does not list them, on purpose: it used to name nine step types where seven
+  validate, and a list nobody could read is a list that goes wrong. The spec
+  also lists the types you may NOT author, each with the reason and how to
+  express that intention instead — so reaching for one gets you an answer
+  rather than a \`step_invalid_type\`.
 - Referential integrity is enforced: step and trigger ids must be unique, and
   every edge \`from\`/\`to\` must reference an id that exists in the document
   (\`from\` may be a trigger or step; \`to\` must be a step). A dangling edge is a
@@ -321,13 +362,18 @@ DELETE a link and do NOT touch the entity body:
 - reference_doc → agent: \`attach_reference_to_agent\` (agents only — there is no
   workflow-scoped reference-doc route).
 - VERIFY every one of these with the read-back before \`request_publish_*\`:
-  \`list_agent_skills\`, \`list_agent_policies\`, \`list_agent_reference_docs\`.
-  This is not optional politeness — because a link lives OUTSIDE the entity body,
-  \`read_agent\` will not show it, so the read-back is the only way to tell an
-  attach that landed from one that silently did nothing. (Mechanism A is
-  different: those ids ARE in the body, so re-reading the agent proves them.
-  \`attach_skill_to_workflow\` has no read-back — the backend has no list route
-  for it.)
+  \`list_agent_skills\`, \`list_agent_policies\`, \`list_agent_reference_docs\`,
+  and \`list_workflow_skills\` for the workflow-scoped variant. This is not
+  optional politeness — because a link lives OUTSIDE the entity body,
+  \`read_agent\` / \`read_workflow\` will not show it, so the read-back is the
+  only way to tell an attach that landed from one that silently did nothing.
+  (Mechanism A is different: those ids ARE in the body, so re-reading the agent
+  proves them.)
+- The three agent read-backs also take \`workflowId\`. With it you get the
+  COMPOSED runtime view — what this agent's prompt actually assembles inside
+  that workflow, with a \`linkSource\` per row saying WHY each item is there (an
+  explicit link, tenant-wide, or scoped to the workflow). Without it you see the
+  agent on its own, which is not what a run assembles.
 
 **C) Reference an id INSIDE the workflow document** (this is how agents and tools
 get "into" a workflow — there is no attach route for it):
@@ -407,6 +453,41 @@ The connector never carries a secret across: \`authConfig\` stays placeholders i
 the new tenant too, and a human fills the real value there.
 
 ## Structural workflow edits
+- **Start by reading the spec.** \`get_workflow_authoring_spec\` returns FOUR
+  lists this deploy generates from its own registries: the mutation commands,
+  the trigger types, the step types (including the ones you may not author, with
+  the reason), and the schedule-rule shapes with a working example each. Neither
+  this guide nor the tool descriptions restate any of those lists: a list kept
+  in the connector is right only by maintenance, and it has been wrong twice
+  already, both times in the direction that costs an agent a 422 on something it
+  was told to use. Pass \`types\` for the live payload schema of a command you
+  are about to write.
+- **The payload schemas describe themselves.** What may go inside
+  \`parameters\`, \`inputs\`, \`outputs\` and \`contract\` is IN those schemas —
+  including the fact that a bound input DERIVES its contract from the output it
+  reads. Ask the spec for the command's \`types\` rather than looking for prose
+  about the shape here; there deliberately is none.
+- **One thing the schemas do not make obvious: which KEY carries the value's
+  type, because it is not the same key everywhere.**
+  - A TRIGGER PARAMETER and a WORKFLOW CONSTANT use \`type\`.
+  - A step INPUT or OUTPUT uses \`kind\`.
+  - Where a field carries a nested \`schema\` object, \`schema.kind\` is what
+    wins.
+
+  This asymmetry is real, not a typo to normalise: the shapes came from
+  different surfaces, and normalising them would make one reader wrong. The
+  VALUES differ too — \`get_workflow_authoring_spec\` returns one list per key
+  (\`parameterTypes\`, \`outputKinds\`, \`schemaFieldKinds\`), and they are not
+  interchangeable: only one knows \`constant\`, and they disagree on how to
+  spell a yes/no. Read the list that matches the shape you are writing; this
+  guide does not restate them, for the same reason it restates no other list.
+
+  Writing \`kind\` on a trigger parameter is not a 422; it is a key nothing
+  reads, so the value silently falls back to text and the workflow runs with
+  the wrong thing. Check which of the three you are writing before you write it.
+- \`rulesVersion\` in that response is a content hash over all four lists. While
+  it is unchanged there is nothing to re-fetch; re-read the spec when it changes,
+  or when a mutation fails with a 422 suggesting your idea of a command is stale.
 - \`apply_workflow_mutations\` takes a LIST of commands and applies them in order,
   threading the version for you — pass the version you read, not one per command.
 - It is NOT transactional. If command N fails, the ones before it stay applied;
@@ -429,11 +510,53 @@ the new tenant too, and a human fills the real value there.
     required, and \`id\`, \`type\`, \`config\`, \`contract\`, \`inputs\` and
     \`outputs\` are accepted next to them. No follow-up \`update_step\` is needed
     just to fill the step in.
+  - \`add_trigger\` does the same for a trigger: \`parameters\` and \`outputs\`
+    go in that call. This is what makes a callable workflow declarable in one
+    mutation, since a trigger's parameter list IS its signature.
   - \`add_edge\` takes the document's own \`from\`/\`to\` as well as
     \`fromStepId\`/\`toStepId\`, and keeps an \`id\` you supply.
   - An unknown or misspelled key is a 422 naming it, not a silent drop — so
     spelling matters and you are told when it is wrong.
 
+## Inputs and constants — the two lists that belong to the PROCESS
+A workflow declares two whole-list things of its own, both edited the same way
+(read the list, change it, write it back — there is no per-entry command,
+because the identity is the \`name\` and renaming is the common edit):
+- \`set_workflow_inputs\` — what the process NEEDS to start. Carried by every
+  start, and the list a caller fills in whichever trigger fired. A start's own
+  \`parameters\` are what that start declares on top; where a name is in both,
+  the process-level one wins.
+- \`set_workflow_constants\` — what the AUTHOR pins, described below.
+Read both back with \`read_workflow_trigger_parameters\`, which answers
+\`{ inputs, triggers, constants }\`.
+
+## Constants — values the AUTHOR owns
+A constant is applied on EVERY run whichever trigger fired, and it OVERWRITES
+whatever a caller sent. That is deliberate: a field the operator's form does not
+show must not become an injection point for anyone who learns its name.
+- Set them with the \`set_workflow_constants\` command. It replaces the WHOLE
+  list, the way \`advanced_edit\` replaces steps and edges — read the list, edit
+  it, write it back. There is no per-constant command, because a constant's
+  identity is its name and renaming is the common edit.
+- Every entry needs a \`name\`: it is what a step binds to and how the run
+  payload keys it. A nameless entry is refused rather than stored, because at
+  run time it would simply be skipped.
+- **A constant with no value blocks publishing.** \`constant_without_value\` is
+  an error, not a warning, and it names the constant. It has to be: an entry
+  with no value was never written into the run at all, so the workflow validated
+  clean, published, and ran without it.
+- ABSENCE, not falsiness. \`0\`, \`""\`, \`false\` and \`[]\` are values and pass.
+- The value lives in \`defaultValue\`. On a constant that is not a fallback —
+  it IS the value, written on every run. A constant carries no \`required\`
+  (nobody is being asked to fill it in) and needs no flag saying it is one.
+- **A trigger parameter can be pinned the same way**, and the platform reads
+  TWO spellings: \`constant: true\`, or the older \`type: "constant"\`. Both
+  mean the author owns it and the caller must not send it, so treat a parameter
+  carrying either as off-limits when you build \`triggerInput\`.
+  \`read_workflow_trigger_parameters\` collapses both into \`pinned\`, on the
+  workflow's constants and on each start's parameters — read that rather than
+  checking the two spellings yourself.
+
 ## Two platform invariants that look like bugs
 Both are deliberate, both run after EVERY edit, and both now report themselves in
 the mutation response under \`systemAdjustments\` — so you no longer have to diff
@@ -458,31 +581,188 @@ a document to find out what the platform did.
 - Pass exactly one. Before telling a human a workflow is ready, check
   \`catalogChecked\` — a green structural verdict is the easiest thing to
   over-read.
+- Read the \`issues\` rather than only \`launchable\`: the validator now reports
+  a sub-process call with no target, one pointing at itself, one whose target
+  is deleted or was never published or has no invocation trigger, a constant
+  with no value, and a trigger drawn on the canvas that nothing is wired to.
+  Some of those are warnings and still let a workflow publish — read the
+  \`severity\`, and read the \`code\`, which is stable where the message is not.
 
 ## Triggers
-- A published workflow still does nothing until it has a trigger. Add one with
-  \`create_cron_schedule\`, \`create_webhook_trigger\`, or
-  \`create_conditional_trigger\`.
+- A published workflow still does nothing until it has a trigger. A trigger has
+  TWO halves, and drawing one on the canvas is only the first.
+- **A schedule is reconciled for you.** Draw it in the document, publish, and
+  the firing row is brought into line. That is the exception.
+- **A webhook or conditional trigger is NOT.** Its row must be created
+  separately — \`create_webhook_trigger\` / \`create_conditional_trigger\` —
+  and publishing will not create one. A webhook drawn and published with no row
+  is an endpoint that does not exist; the validator says so with
+  \`trigger_not_wired\`, a WARNING, so the publish still goes through. Take the
+  warning seriously: nothing else will tell you.
 - Trigger deletes are HARD deletes — no restore. Webhook tokens are shown once
   at create/rotate and are never retrievable; hand them straight to your human
   and never store one in an entity field.
+- **A schedule is a claim — check it.** \`run_cron_schedule_now\` fires one
+  immediately without moving \`nextFireAt\`, so you can prove a schedule starts
+  something instead of waiting until tomorrow to find out it does not. It runs
+  for real, with real cost and side effects.
+- **To PAUSE a schedule, disarm it** (\`set_cron_schedule_enabled\`), never
+  delete it. Deleting throws away the rules the author wrote and makes "stop
+  this for a week" indistinguishable from "we do not do this any more".
+- \`create_cron_schedule\` takes EITHER \`cronExpr\` OR \`rules\`, and the
+  trigger must exist in the PUBLISHED document. For the rule shapes, read
+  \`scheduleRuleKinds\` from \`get_workflow_authoring_spec\` — do not invent one.
+- \`list_all_cron_schedules\` answers "what runs tonight?" across the tenant;
+  \`reconcile_cron_schedules\` answers "is that actually what runs?". The second
+  reports rather than tidying silently and never arms something switched off.
 
 ## Evaluating what you built
 - There is no findings endpoint and no evaluator entity. To judge a run, read it:
   \`read_run\` (its \`validatorVerdicts\` and \`agentInvocations\`) and
   \`read_run_trace\` (the step-by-step tool calls).
+- **Start with \`read_run_outline\`, not \`read_run\`.** The outline is the run's
+  table of contents and carries no bodies, so it costs what the run's SHAPE
+  costs rather than its content — a fan-out over four thousand items reads about
+  as cheaply as one over four. Then open only what you need:
+  \`read_run_value\` for one large step value (by the digest in \`stepStates\`),
+  \`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
+  this replaces.
+- \`itemCap\` on the outline bounds items listed per fan-out step; the remainder
+  is counted in \`counts.truncated\`, never dropped in silence.
+- **What an agent wrote to itself is readable.** \`list_run_session_memory\`
+  lists the files an agent left during a run (metadata only) and
+  \`read_run_session_memory_file\` opens one. When the trace shows a decision but
+  not what it was reading, this is usually where the reason is. Workflow-bound
+  reference material is NOT here — that lives in \`reference_docs\`.
+- **\`list_todo_steps\`** is every step in the tenant waiting on a human, across
+  all runs; \`read_run_waiting_on\` is the same question for one run you already
+  have. It is PAGED over the waiting RUNS, so \`items\` can be longer than
+  \`pageSize\` — one run may park several steps. Follow \`nextCursor\` until it
+  is null before concluding anything about how much is waiting.
 - Runs are the only thing with a real archive state — \`archive_run\` is
   reversible, \`bulk_delete_runs\` is not.
 
+## Subworkflows — one workflow calling another
+Both halves live in the workflow DOCUMENT, so both are ordinary
+\`apply_workflow_mutations\` work. There is no separate "link" route.
+- **To make a workflow callable**, it needs TWO things: a trigger with
+  \`typeId: "subprocess-invocation"\` (\`add_trigger\`), which is what makes it
+  callable at all, and a declared SIGNATURE.
+- **The signature belongs to the PROCESS, not to the trigger.** Declare it with
+  \`set_workflow_inputs\` — one list, carried by every start, and the same list
+  a caller of any kind fills in. A trigger's own \`parameters\` are what THAT
+  start declares on top; \`parameters\` goes in the \`add_trigger\` call itself,
+  so a start that does add fields needs no follow-up \`update_trigger\`.
+- Older documents declared everything on the invocation trigger instead, and
+  that still works: both are read, and where a name appears in both the
+  PROCESS-level one wins. When you are editing a workflow you did not author,
+  read \`read_workflow_trigger_parameters\` and see which list actually holds
+  its fields before adding to either.
+- \`set_workflow_inputs\` REPLACES the whole list, like
+  \`set_workflow_constants\`: read, edit, write back. An entry with no \`name\`
+  is refused rather than stored — the name is how a caller passes the value and
+  how the run payload keys it, so a nameless one would be skipped silently at
+  run time.
+- For what an input or a parameter may contain, ask
+  \`get_workflow_authoring_spec\` for the payload schema of the command you are
+  about to write, rather than a shape written down here.
+- **It must also be PUBLISHED.** The catalogue reads the published document, so
+  a draft-only workflow comes back \`callable: false\` with "Never published".
+  Authoring the caller first and publishing the callee later is a run-time
+  failure waiting to happen.
+- **To call it**, add a step with \`type: "subprocess"\` and
+  \`config: { targetWorkflowId, ownerAgentId }\` — both required, both workflow/
+  agent ids. Bind the step's \`inputs\` by NAME to the callee's \`parameters\`;
+  that is the whole mapping, there is no separate argument block.
+- \`config.waitForCompletion\` is **IGNORED** if you write it. Drawing a step
+  after this one already means "after", so waiting is implied. The one thing the
+  graph cannot say is fire-and-forget: \`config.fireAndForget: true\`, and then
+  nothing downstream may depend on the result.
+- \`config.errorStrategy\` ("fail" | "skip") is only honoured when the step
+  ITERATES (\`config.iteration.enabled\`). On a single call "skip" would report
+  a failed child as success, so it is forced to fail-fast.
+- **A workflow cannot call itself** — every run would spawn a child that reaches
+  the same step again. Pass \`exclude: <the workflow you are editing>\` to
+  \`list_callable_workflows\` and it is kept out of the list.
+- **What comes back** is the callee's \`outcomes\`: its end steps, each with the
+  fields bound into it. WHICH end was reached is itself part of the answer.
+- **\`validate_workflow\` checks this now.** A missing target, a workflow
+  calling itself, a target that is deleted, never published, or has no
+  invocation trigger — each has its own issue code, and the ones that resolve to
+  nothing are errors that block publishing. Still run
+  \`list_callable_workflows\` BEFORE you author the step: it is how you pick a
+  target and see the interface you are binding to, where the validator only
+  tells you afterwards that the one you picked was wrong.
+
 ## Secrets
 - Never handle a real credential. A connector's \`authConfig\` takes placeholders
   only ("{{ MY_SECRET }}" or ""); a human fills the real value in Axonity. This
   is enforced — a write carrying something that looks like a real secret is
   rejected before it leaves this connector.
+- You CAN read the catalogue: \`list_secrets\` (id, name, authType) and
+  \`read_secret\`. That is how you get the id for a connector's
+  \`authConfig.secretId\` — do not ask a human to copy one out of the UI.
+- Before you wire a connector to a secret, check \`valueKeys\` on
+  \`read_secret\`. An empty list means nobody has filled the secret in yet: the
+  connector will author fine and fail at RUN time. Say so to your human, with the
+  secret's name, rather than reporting the wiring as done.
+- You cannot create, change or delete a secret. That is a human act in Axonity →
+  Settings → Secrets, and the backend refuses it from this connector's token.
+- A secret's \`metadata\` (connection config, e.g. a session_cookie handshake)
+  comes back with credential-shaped entries withheld, listed under
+  \`metadataRedacted\`. If you need one of those values, a human reads it in
+  Axonity — do not try another route to it.
+
+## Toolboxes — where a tool is filed
+- A toolbox is a per-tenant grouping label over tools. Read \`list_toolboxes\`
+  before \`create_tool\` and pass the box's id as \`toolboxId\`; a tool created
+  without one is ungrouped. Move an existing tool with
+  \`assign_tool_toolbox\` (\`toolboxId: null\` takes it out of its box).
+- \`set_toolbox_tools\` DECLARES the membership — it does not add to it. A tool
+  in the box and absent from your list is evicted. To add one tool, read the
+  box's contents first, or use \`assign_tool_toolbox\`, which cannot evict
+  anything by accident. A tool is in at most one box.
+- A toolbox NEVER changes what an agent may call. An agent is linked to
+  individual tools (\`agent.toolIds\`), never to a box; there is no route that
+  grants a whole box, and "give this agent the Carerix toolbox" is a bulk write
+  of individual links. What the box decides is how a tool is ADVERTISED: a boxed
+  tool with \`surfacing: "inherit"\` is found via discover_tools instead of
+  riding in every prompt. Read \`effectiveSurfacing\` on the tool to answer "is
+  it in the prompt?"; \`surfacing\` is the raw stored choice.
+- Deleting a toolbox does NOT delete its tools — they survive, ungrouped. The
+  box itself has no restore.
+- Platform-shipped tools cannot be moved. The \`Axonity\`, \`Checks\` and
+  \`Branching\` boxes hold locked tools; the API refuses and NAMES the tool it
+  refused. Read that name to your human instead of bisecting the selection.
+- \`set_toolbox_auth\` sets the credential a box's tools SHARE — ten Microsoft
+  Mail tools, one mailbox, said once. A tool with its own auth keeps it; only a
+  tool with none inherits. Same rule as anywhere else: point \`secretId\` at a
+  stored secret, never a real value. Before you clear or replace it, or delete
+  the box, call \`list_toolbox_dependent_tools\` — it names the tools that would
+  start failing at run time with a bare 401.
 
 ## Tenant
 - Your token fixes the tenant. You cannot act across tenants; never send a
   tenant id in a body.
+- \`read_model_tier_map\` says what \`capabilityTier\` actually RESOLVES TO on
+  this tenant. The tier is the field you write; the model is what you are
+  choosing. Read it before you pick one.
+- When a run does not start, look outward before blaming the workflow:
+  \`read_concurrency_status\` (is the tenant at its cap?),
+  \`read_queue_overview\` (is dispatch alive?), \`list_task_queue\` (did
+  something fail in the layer beneath the run?). \`read_for_each_rate\` explains
+  a fan-out that is pacing itself rather than stalling.
+- You can READ those and not change them. Caps, rate ceilings and the tier map
+  are operator decisions — report what you found, and to whom, rather than
+  looking for another route to it.
+- \`read_deploy_contract\` says what THIS deploy speaks: build, environment and
+  the routes it mounts. Read it when a call fails in a way that suggests the
+  backend is older or newer than you expect.
+- \`list_users\` is where an \`ownerId\` comes from. Look one up instead of
+  asking a human to copy it out of the UI.
+- \`list_audit_events({ actorKind: "service_token" })\` reads back what external
+  agents — including you — actually changed.
 `;
 export function registerConventions(server) {
     server.tool("axonity_conventions", "Read the authoring conventions BEFORE creating or updating anything: the " +

package/dist/tools/conventions.js.map

@@ -1 +1 @@
-{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/tools/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsdnB,CAAC;AAEF,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,2EAA2E;QACzE,2EAA2E;QAC3E,2EAA2E;QAC3E,4EAA4E;QAC5E,uEAAuE;QACvE,kBAAkB,EACpB,EAAE,EACF,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAC1E,CAAC;AACJ,CAAC"}
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/tools/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8tBnB,CAAC;AAEF,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,2EAA2E;QACzE,2EAA2E;QAC3E,2EAA2E;QAC3E,4EAA4E;QAC5E,uEAAuE;QACvE,kBAAkB,EACpB,EAAE,EACF,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAC1E,CAAC;AACJ,CAAC"}

package/dist/tools/credentials.d.ts

@@ -25,6 +25,26 @@ export declare function isPlaceholder(value: unknown): boolean;
  * Exported for testing; `assertPlaceholderCredentials` is the enforcement point.
  */
 export declare function findCredentialViolations(value: unknown, path?: string): string[];
+/** What a redacted leaf is replaced with. Names where the real value lives. */
+export declare const REDACTION = "[redacted by the connector \u2014 read it in Axonity]";
+export interface Redaction {
+    /** The input with every credential-ish leaf replaced by `REDACTION`. */
+    value: unknown;
+    /** Where a replacement happened, e.g. `metadata.handshakeHeaders.Authorization`. */
+    redactedPaths: string[];
+}
+/**
+ * The mirror image of `findCredentialViolations`: same walk, same rules, but it
+ * rewrites what it finds instead of throwing. For data coming BACK from Axonity.
+ *
+ * A secret's `metadata` is stored unencrypted and returned verbatim by a route
+ * every user in the tenant can call (axonity-flow#908), and the handshake form
+ * invites an `Authorization` header straight into it. Returning that to an agent
+ * would put a real credential in its context through the one surface built on
+ * the promise that values never leave the server — so the structure comes back
+ * (an agent needs to see WHICH fields a handshake has) and the credential does not.
+ */
+export declare function redactCredentials(value: unknown, path?: string): Redaction;
 /**
  * Throw if a connector's fields carry anything that looks like a real
  * credential. Safe to call with any tool's fields — it is a no-op when there is

package/dist/tools/credentials.js

@@ -84,6 +84,47 @@ export function findCredentialViolations(value, path = "authConfig") {
     walk(value, path, false);
     return findings;
 }
+/** What a redacted leaf is replaced with. Names where the real value lives. */
+export const REDACTION = "[redacted by the connector — read it in Axonity]";
+/**
+ * The mirror image of `findCredentialViolations`: same walk, same rules, but it
+ * rewrites what it finds instead of throwing. For data coming BACK from Axonity.
+ *
+ * A secret's `metadata` is stored unencrypted and returned verbatim by a route
+ * every user in the tenant can call (axonity-flow#908), and the handshake form
+ * invites an `Authorization` header straight into it. Returning that to an agent
+ * would put a real credential in its context through the one surface built on
+ * the promise that values never leave the server — so the structure comes back
+ * (an agent needs to see WHICH fields a handshake has) and the credential does not.
+ */
+export function redactCredentials(value, path = "metadata") {
+    const redactedPaths = [];
+    const walk = (node, at, keyIsCredential) => {
+        if (Array.isArray(node)) {
+            return node.map((item, i) => walk(item, `${at}[${i}]`, keyIsCredential));
+        }
+        if (node !== null && typeof node === "object") {
+            const out = {};
+            for (const [key, child] of Object.entries(node)) {
+                out[key] = walk(child, `${at}.${key}`, isCredentialKey(key));
+            }
+            return out;
+        }
+        if (typeof node === "string" && SECRET_PATTERNS.some(([, re]) => re.test(node))) {
+            redactedPaths.push(at);
+            return REDACTION;
+        }
+        // A credential-named leaf goes whatever its type — but a placeholder or an
+        // empty string is not a credential, and blanking it would hide that the
+        // field is unfilled, which is exactly what a reader is checking for.
+        if (keyIsCredential && !isPlaceholder(node)) {
+            redactedPaths.push(at);
+            return REDACTION;
+        }
+        return node;
+    };
+    return { value: walk(value, path, false), redactedPaths };
+}
 /**
  * Throw if a connector's fields carry anything that looks like a real
  * credential. Safe to call with any tool's fields — it is a no-op when there is

package/dist/tools/credentials.js.map

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

package/dist/tools/extras.d.ts

@@ -16,6 +16,23 @@ export declare function registerConnectorTools(server: McpServer, client: Axonit
 /** Keep the envelope, project the rows down to identity. */
 export declare function projectLinkRows(response: Record<string, unknown>, rowsKey: string): Record<string, unknown>;
 export declare function registerAttachTools(server: McpServer, client: AxonityClient): void;
+/**
+ * "What breaks if I change this" — the reverse look-up, for both halves of the
+ * catalogue (axonity-flow#845 S5 and #961 S8).
+ *
+ * A shared library item is edited on the assumption that someone knows what
+ * uses it. Three items could answer that agent-first; the rest of the catalogue
+ * could not answer it at all, and there a broken reference stops a RUN rather
+ * than merely thinning a prompt. The only way to find out was to validate every
+ * workflow in the tenant and see where it went wrong.
+ *
+ * It was never queryable because these are not rows in a join table: they are
+ * keys inside a JSON document, and per entity in more than one place — an agent
+ * is a step OWNER and the `ownerAgentId` of a subprocess step; a tool appears in
+ * a step contract, in a plan activity, and on an automation step's config. The
+ * backend answers through one reader for exactly that reason.
+ */
+export declare function registerDependencyTools(server: McpServer, client: AxonityClient): void;
 /**
  * Small standalone tools that don't fit any of the other groupings: the
  * system-tools catalog (read-only — there is no grant/revoke route; enabling