@axonity-ai/mcp 0.6.0 → 0.7.0

package/dist/tools/company.js

@@ -3,8 +3,11 @@
  * streams, org structure). Unlike the other authored entities it is a
  * SINGLETON: one per tenant, addressed at `/api/v1/company` with no id, so it
  * has no list / create / delete / restore / discard routes. It is
- * version-controlled like the memory entities, and edited as a whole document
- * (a full-document PUT under optimistic locking), not field-by-field.
+ * version-controlled like the memory entities, and editable two ways: command
+ * mutations (`apply_company_mutation`, preferred — the backend validates each
+ * and threads the version) or a whole-document PUT (`update_company`). Workflow
+ * has had both for a long time; company was whole-document-only here even
+ * though `POST /api/v1/company/mutations` existed.
  *
  * Publishing: company is currently NOT a publish-approval entity type on the
  * backend, so there is no request_publish_company — a company change is
@@ -52,6 +55,57 @@ export function registerCompanyTools(server, client) {
     }, async ({ versionId, expectedVersion }) => guard(async () => jsonResult(await client.post(`/api/v1/company/versions/${versionId}/restore`, {
         expectedVersion,
     }))));
+    server.tool("create_company_major_version", "Cut a new NAMED major version of the company document — \"Save As\" for " +
+        "the current draft, so a milestone is findable by name instead of by " +
+        "hunting through checkpoints. Takes no id (singleton). This does NOT " +
+        "publish: what is live stays live until a human approves a " +
+        "request_publish_company.", {
+        name: z
+            .string()
+            .min(1)
+            .max(255)
+            .describe('What to call this release, e.g. "Q3 operating model".'),
+        description: z
+            .string()
+            .optional()
+            .describe("A longer note on what this version represents."),
+    }, async ({ name, description }) => guard(async () => jsonResult(await client.post("/api/v1/company/versions", {
+        name,
+        ...(description ? { description } : {}),
+    }))));
+    server.tool("ensure_company_major_version", "Make sure the company document has a working draft major version, " +
+        "creating an unnamed one if it has none. IDEMPOTENT — safe to call before " +
+        "a run of edits; when one already exists nothing changes. Returns the " +
+        "draft's major version number and name.", {}, async () => guard(async () => jsonResult(await client.post("/api/v1/company/versions/ensure"))));
+    server.tool("apply_company_mutation", "Apply ONE structural command to the company document — the validated, " +
+        "version-safe way to change its layers, value streams, stages and " +
+        "capabilities, and to link workflows to them. Prefer this over " +
+        "update_company: that route is a whole-document PUT, which is the same " +
+        "reason apply_workflow_mutations is preferred for a workflow. Read the " +
+        "company first for its version. " +
+        "\n\nOne command per call — this route has no batch form, unlike the " +
+        "workflow one. Apply a sequence yourself, using the version each response " +
+        "returns as the next call's expectedVersion. " +
+        "\n\nWHICH COMMANDS EXIST is not listed here and this connector keeps no " +
+        "copy: unlike workflows, company has no catalogue route to read, so a " +
+        "wrong `type` is a 422 that names every value the route accepts. Read " +
+        "that error rather than guessing twice.", {
+        type: z
+            .string()
+            .describe("The command name. A value this deploy does not accept comes back as " +
+            "a 422 listing the ones it does."),
+        payload: z
+            .record(z.unknown())
+            .describe("The command's arguments (camelCase keys)."),
+        expectedVersion: z
+            .number()
+            .int()
+            .describe("The version you last read — rejected with 409 if stale."),
+    }, async ({ type, payload, expectedVersion }) => guard(async () => jsonResult(await client.post("/api/v1/company/mutations", {
+        type,
+        payload,
+        expectedVersion,
+    }))));
     server.tool("name_company_major_version", "Give one of the company document's major versions a name — label a release " +
         "so it is easy to find in history. Targets a MAJOR version by its integer " +
         "number (from list_company_versions), not a checkpoint or a versionId. Like " +

package/dist/tools/company.js.map

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

package/dist/tools/conventions.d.ts

@@ -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.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function registerConventions(server: McpServer): void;

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
@@ -230,8 +263,8 @@ made any time before you attach them.
   - \`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 +282,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 +359,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 +450,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 +507,41 @@ 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.
 
+## 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,11 +566,24 @@ 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.
@@ -474,11 +595,62 @@ a document to find out what the platform did.
 - 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**, give it a trigger with
+  \`typeId: "subprocess-invocation"\` (\`add_trigger\`) whose \`parameters\` are
+  what a caller must pass. That list IS the signature — there is no other place
+  to declare it. \`parameters\` goes in the \`add_trigger\` call itself; you do
+  not need a follow-up \`update_trigger\`. For what a parameter may contain, ask
+  \`get_workflow_authoring_spec\` for \`add_trigger\`'s payload schema 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.
 
 ## Tenant
 - Your token fixes the tenant. You cannot act across tenants; never send a

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAknBnB,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