@axonity-ai/mcp 0.25.0 → 0.26.0

package/dist/tools/conventions.js

@@ -70,8 +70,9 @@ Read this before creating or updating anything.
 1. \`read_*\` the entity (and \`read_*_published\` if you need to see what is live).
 2. Edit the DRAFT: \`update_*\`, or workflow-edit tools for workflow structure.
 3. Validate before publish: \`validate_workflow\` / \`analyze_workflow_reachable_outputs\` / 
-   \`validate_tool_code\` / \`format_tool_code\`. These four are stateless and work with
-   read-only tokens.
+   \`validate_tool_code\` / \`format_tool_code\`. These four save nothing, and a
+   read-only token may call them — except \`validate_workflow({ workflowId })\`,
+   which needs the \`author\` scope.
 4. Re-read and verify with a saved tool command: \`execute_tool\` /
    \`execute_stored_connector\`.
 5. Fix any issues and re-read again.
@@ -157,11 +158,13 @@ has run cleanly once, at its current version.
 
 ## Field shape
 - All fields are camelCase JSON (e.g. \`capabilityTier\`, not \`capability_tier\`).
-  ONE documented exception: validator specs (\`permissions.outputValidators\`,
-  \`permissions.exposedValidatorTools\`) use snake_case keys (\`function\`,
+  ONE documented exception: validator specs — in an output_schema's
+  \`schemaBody\` (\`validators\`, \`preflight\`), a step's
+  \`contract.output_validators\` and a conversation step's
+  \`answerContract.validators\` — use snake_case keys (\`function\`,
   \`target\`, \`args\`, \`when_present\`, \`inputs\`, \`error_message\`,
-  \`tool_name\`, \`validator_name\`) — they are the same shape at every level and
-  are stored verbatim, so they are NOT camel-aliased. Send them in snake_case.
+  \`tool_name\`, \`validator_name\`) — they are stored verbatim, so they are
+  NOT camel-aliased. Send them in snake_case.
   What those keys MEAN, and how a validator is bound to what it judges, is the
   Validators section.
 - \`update_*\` is a partial change for agents/tools and a partial patch for
@@ -173,10 +176,10 @@ 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 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
+- An agent has no tags: 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",
@@ -217,17 +220,17 @@ has run cleanly once, at its current version.
 - 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
-  and wrongly. Follow \`nextCursor\` until it is null. Two further traps: that
-  route lists LAUNCHES (a 4,415-item FOR EACH is ONE entry carrying
-  \`forEachProgress\`, so rows are not runs), and the offset-style lists
-  (\`list_runs\`, \`list_publish_approvals\`) cap silently — a full page means
-  there may be more, and nothing in the response says so.
+  and wrongly. Follow \`nextCursor\` until it is null. And that route lists
+  LAUNCHES: a 4,415-item FOR EACH is ONE entry carrying \`forEachProgress\`, so
+  rows are not runs. \`list_runs\` pages the same way, by \`nextCursor\` with
+  \`hasMore\`. \`list_publish_approvals\` pages by \`offset\` and answers \`total\`
+  and \`hasMore\`: raise \`offset\` by \`limit\` until \`hasMore\` is false.
 
 ## Delete is recoverable — but not everything is
 - \`delete_*\` soft-deletes: the entity disappears from \`list_*\` but is not gone.
   \`restore_*\` brings it back; \`list_deleted_*\` shows what's waiting. This
-  applies uniformly to workflow, agent, tool, skill, policy, reference_doc,
-  persona, output_schema, prompt_snippet, and flow.
+  applies uniformly to every entity that has a \`delete_*\` and a
+  \`restore_*\` tool.
 - The same applies one level down, to version HISTORY:
   \`delete_*_version\` removes one entry from history (the current draft and
   published version are protected and can't be targeted this way);
@@ -236,8 +239,12 @@ has run cleanly once, at its current version.
   are normal, not a sign of corruption.
 - \`restore_*\` can itself 409 if a live entity now holds the same name/slot —
   the error names the conflicting one.
-- There is no "archive" state for these ten entities — delete + restore IS the
-  lifecycle. Runs are the one exception with a true archive/unarchive (see below).
+- Deleting is not archiving. Some entities also have a \`status\` that can be
+  \`archived\` — kept, not offered — set with \`update_*\`: \`agent\`, \`tool\`,
+  \`skill\`, \`policy\`, \`reference_doc\`, \`output_schema\`, \`data_table\`,
+  \`measure\` and \`application\`. The values each takes are in
+  \`get_entity_authoring_contract\`. Runs have an archive of their own
+  (\`archive_run\` / \`unarchive_run\`, see below).
 
 ## Per entity — what to create, and what "complete" means
 
@@ -287,12 +294,30 @@ made any time before you attach them.
       so the human approving is not the first to find out.
     - **An answer that is a file**: \`responseMapping: { "type": "file",
       "filename": "{{filename}}" }\` keeps the bytes as a file of the run and
-      returns its reference \`{ fileId, filename, contentType, sizeBytes }\` —
-      the shape an upload has, so Digitize documents reads it and a
-      sub-workflow's file parameter takes it. \`filename\` is optional (the
-      far end's \`Content-Disposition\` name, else \`document\`) and may use
-      the inputs. No \`responseTransform\` with a file answer. Outside a run
+      returns its reference
+      \`{ fileId, filename, contentType, sizeBytes, sha256 }\` — the shape an
+      upload has, so Digitize documents reads it and a sub-workflow's file
+      parameter takes it. \`filename\` is optional (the far end's
+      \`Content-Disposition\` name, else \`document\`) and may use the inputs.
+      No \`responseTransform\` with a file answer. Outside a run
       (\`execute_stored_connector\`) nothing is stored: you see name and size.
+    - **\`sha256\` in a file reference** is the hex SHA-256 of the bytes,
+      computed once when the file was stored. The same bytes have the same
+      value under any name, so compare it to recognise a file that was already
+      processed (deciding that is the workflow's logic, not the platform's).
+      Only a reference in a declared file parameter (\`file\`, or a list of
+      \`file\`) is checked against storage. Where one enters a run — a
+      manual, API or MCP start, a sub-workflow call (with its copy under
+      \`item\` in the child) — its \`filename\`, \`contentType\`,
+      \`sizeBytes\` and \`sha256\` are settled from storage, whatever the
+      caller wrote. A reference to a file the run may not read keeps what the
+      caller wrote and carries no \`sha256\`; at a webhook, cron or
+      conditional start that holds for each of them, since such a start links
+      no file. A reference anywhere else (an \`object\` field, an undeclared
+      key) is not checked and keeps any \`sha256\` the caller wrote. Digitize
+      documents always answers the stored \`sha256\` per file it read. So
+      compare only the value on a declared file parameter or on Digitize's
+      entry, never one in another field or one an agent wrote out.
   - **executor** — runs a command on a registered executor (a program on
     the customer's side). The save refuses a tool that names no executor or a
     command that executor does not know; \`list_executors\` and
@@ -316,17 +341,26 @@ made any time before you attach them.
 - 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\` (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
-  shape for the casing, Validators for what they say);
-  \`expectedOutputSchemaId\` (an output_schema id — MANDATORY whenever you
-  attach validators here).
+  - \`reasoningLevel\`: \`default\` (sends nothing, the model decides) | \`none\` | \`low\` | \`medium\` | \`high\` | \`extra_high\`
+  - \`delegation\`: \`off\` (default) | \`on\` (one task to one team member at a time) | \`multi\` (also one task to several at once)
+- \`persona\` (text): who the agent is, in its own words — the character text
+  every prompt of this agent opens with. It is a field of the agent and
+  publishes with it (axonity-flow#2176); there is no separate persona to
+  create, version or publish. To remove it send \`""\`: on an update \`null\`
+  leaves it as it is.
+- \`slug\` (its handle, set once at creation; left out: taken from the name),
+  \`avatar\`, \`conversational\` (bool: may people talk to it),
+  \`delegationBudgetEur\` (what one delegation to it may cost; empty: no
+  budget), \`frameworkToolsOff\` (framework tools taken away; \`submit_output\`
+  cannot be), \`clearance\` (what it may read; set by an administrator).
+- Output: \`outputSchemaIds\` (the output schemas it answers in — library ids
+  or names; a schema outside the list is refused) and \`defaultOutputSchemaId\`
+  (the one used when a caller names none; left out: the first). The GATES on
+  an output live in the output_schema (see Validators), not on the agent.
 - Wiring fields — see the Wiring section: \`toolIds\`, \`systemToolIds\`,
   \`delegationTargetIds\`.
+- Anything else is refused: the body is strict, so a field the platform
+  retired (axonity-flow#2176) is a 422 that names it, not a silent drop.
 - Complete check: an agent with no \`toolIds\`/\`systemToolIds\` has no tools and
   can only reason/talk. If it is meant to DO something, give it the tools.
 
@@ -363,14 +397,16 @@ made any time before you attach them.
   launchable AND has a trigger (see Triggers).
 
 ### persona
-- An agent's character — 1:1 with an agent. Created only through its agent
-  (\`create_agent_persona\`: \`name\`, \`characterText\`); then a normal entity
-  (\`read_persona\`, \`update_persona\`, delete/restore/versions).
+- Not an entity: the agent's \`persona\` field (see agent). Set it with
+  \`create_agent\` / \`update_agent\`, or \`create_agent_persona\` (agentId,
+  expectedVersion, persona); read it with \`read_agent\` or
+  \`read_agent_persona\`. Its history is the agent's versions, and it goes live
+  with \`request_publish_agent\`.
 
 ### output_schema
 - A reusable output contract, versioned and publishable. Referenced BY id from a
-  tool's validators or an agent's \`permissions.expectedOutputSchemaId\` — so
-  create it first, then point things at the id the create call returns.
+  tool's validators or an agent's \`outputSchemaIds\` — so create it first,
+  then point things at the id the create call returns.
 - \`schemaBody\` is a JSON Schema document (\`type\`, \`properties\`,
   \`required\`) PLUS one key that is not JSON Schema: \`validators\`, the gates
   run against a submitted output. This is the place a validator can be STEERED
@@ -417,13 +453,24 @@ made any time before you attach them.
 
 ## Validators — one shape, one call
 A validator is a GATE on a submitted output: it runs after an agent produces a
-result and can refuse it. Specs are written in two places and carry the same
-key names in both — \`permissions.outputValidators\` on an agent, and
-\`validators\` inside an output_schema's \`schemaBody\`. The backend's OpenAPI
-description of \`schemaBody\` is the source for the full contract, and the
-platform's live contract (\`get_entity_authoring_contract\`, output_schema)
-wins over this section where this deploy serves it. What follows is the part
-you cannot author without, checked against the platform and SUBORDINATE to both.
+result and can refuse it. The backend's OpenAPI description of \`schemaBody\`
+is the source for the full contract, and the platform's live contract
+(\`get_entity_authoring_contract\`, output_schema) wins over this section where
+this deploy serves it. What follows is the part you cannot author without,
+checked against the platform and SUBORDINATE to both.
+
+Specs carry the same keys wherever they are written:
+- an output_schema's \`schemaBody\` (\`validators\`, and \`preflight\` for the
+  checks an agent may run itself before it submits) — the gate on one value;
+- a workflow step's \`contract.output_validators\` — run on the step's WHOLE
+  submission, so a rule about how its outputs relate has something to look at;
+  \`validate_workflow\` reports a named validator tool that does not exist;
+- a conversation step's \`answerContract.validators\`, beside its \`schema\` —
+  run on the answer the agent hands in; without a \`schema\` nothing runs, and
+  \`validate_workflow\` does not report it.
+The agent itself no longer carries specs (axonity-flow#2176): it names the
+schemas it answers in with \`outputSchemaIds\`, and a spec sent on the agent's
+strict create/update body is a 422.
 
 - A spec names its check in ONE of two ways, and each brings its own binding:
   - \`function\` — a shipped predicate (e.g. \`validators.min_length\`), bound
@@ -482,11 +529,8 @@ unresolved values and nothing says so. (Rows whose schema declares no shape are
 left alone: there is nothing to check against, and guessing would refuse correct
 configurations.)
 
-WHERE \`field\` AND \`slots\` ARE ACCEPTED: inside an output_schema's
-\`schemaBody\`, which is stored verbatim. An agent's
-\`permissions.outputValidators\` is a STRICT body — an undeclared key is a 422 —
-so a spec written THERE takes neither, and its validator gets the whole output
-and no slots. Steer a validator from the output_schema.
+WHERE \`field\` AND \`slots\` ARE CHECKED: when you save an output_schema, in
+its \`schemaBody\`, which is stored verbatim.
 
 ### The older, explicit binding
 A tool spec MAY declare \`inputs\` instead, and a spec with \`inputs\` does NOT
@@ -513,8 +557,9 @@ lives in the entity body:
   \`update_agent\`. \`toolIds\` and \`systemToolIds\` are DIFFERENT lists; a
   system-tool id does not go in \`toolIds\`.
 - agent → agent (delegation): add the callee agent's id to the caller's
-  \`delegationTargetIds\` (and set \`permissions.delegation: true\`).
-- output_schema → agent: \`permissions.expectedOutputSchemaId\` (a single id).
+  \`delegationTargetIds\` (and set \`delegation\` to \`on\` or \`multi\`).
+- output_schema → agent: \`outputSchemaIds\` (a list), with
+  \`defaultOutputSchemaId\` for the one used when a caller names none.
 - Changing any of these is read-then-write under optimistic locking: read the
   agent, edit the field — an id-array is a FULL replace, so include the ids you
   are keeping — then \`update_agent\` with \`expectedVersion\`.
@@ -588,8 +633,8 @@ doc or a step's activities — and how large each may be, is not decided here: t
 placement rules are served by the platform and appended to this guide, read live
 from this deploy each time you call it.
 
-Long-term recall for an agent is the agent's **\`episodicMemoryEnabled\`** flag
-(Memory V2, opt-in). Session/workflow memory are RUNTIME, not authored: they are
+An agent has no long-term recall of its own runs: episodic memory went with
+axonity-flow#2176. Session/workflow memory are RUNTIME, not authored: they are
 written by a run, never set here. This connector does not expose them — the
 backend serves them per run, but no tool wraps those reads yet, so do not
 promise a user you can show them.
@@ -615,9 +660,8 @@ elsewhere points at nothing. Do this instead:
 2. Create the leaf dependencies first (tools, output_schemas). Keep a map from
    each OLD id to the NEW id the create call returns.
 3. Create agents, translating every referenced id through your map:
-   old toolId → new toolId in \`toolIds\`, etc. Never send an old id. If the
-   source agent has a persona, recreate it with \`create_agent_persona\` on the
-   new agent.
+   old toolId → new toolId in \`toolIds\`, etc. Never send an old id. The
+   persona is a field of the agent: copy its \`persona\` text into the create.
 4. Create workflows; when you add agent/tool references into the document,
    translate through the map the same way.
 5. Attach skills/policies/reference-docs by the new ids, then read them back
@@ -628,10 +672,14 @@ 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
+- **Start by reading the spec.** \`get_workflow_authoring_spec\` returns the
+  lists this deploy generates from its own registries: the mutation commands
+  (\`operations\`), the trigger types (\`triggerTypes\`), the step types
+  (\`stepTypes\`, including the ones you may not author, with the reason), the
+  schedule-rule shapes with a working example each (\`scheduleRuleKinds\`), the
+  value vocabularies (\`parameterTypes\`, \`outputKinds\`, \`schemaFieldKinds\`),
+  the decision evaluators (\`decisionEvaluators\`) and the column kinds of a
+  table (\`tableColumnKinds\`). 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
@@ -660,7 +708,8 @@ the new tenant too, and a human fills the real value there.
   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
+- \`rulesVersion\` in that response is a content hash over the whole
+  answer. 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,
@@ -746,13 +795,18 @@ a document to find out what the platform did.
   \`removedEdges\`. An edge you did not ask for is this, not corruption.
 
 ## Validating: two questions, two calls
-- \`validate_workflow({ workflowId })\` checks the STORED workflow against the
-  tenant catalog — it confirms the agents, tools and flows the steps reference
-  actually exist. This is the "can this run?" answer, and it comes back with
-  \`catalogChecked: true\`.
-- \`validate_workflow({ document })\` is stateless and read-only-token safe, but
-  without a catalog it can only judge STRUCTURE: \`launchable\` there means the
-  graph is sound, not that it will run. It says so with \`catalogChecked: false\`.
+- \`validate_workflow({ workflowId })\` checks the workflow as SAVED against the
+  tenant catalog — whether the agents, tools and flows the steps reference
+  exist and are published — plus its own wiring (its triggers and the knowledge
+  attached to it). This is the "can this run?" answer. It needs a token with
+  the \`author\` scope.
+- \`validate_workflow({ document })\` judges the document against the same
+  catalog, saves nothing, and a read-only token may call it. Without the
+  workflow's id it skips the checks about that workflow's own wiring (its
+  triggers and the knowledge attached to it), so validate by \`workflowId\` once
+  it is saved. Either call answers \`catalogChecked: false\` when the catalog
+  could not be built: then \`launchable\` means the graph is sound, not that it
+  will run.
 - Pass exactly one. Before telling a human a workflow is ready, check
   \`catalogChecked\` — a green structural verdict is the easiest thing to
   over-read.
@@ -854,8 +908,8 @@ a document to find out what the platform did.
   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.
+- A run's archive is reversible (\`archive_run\` / \`unarchive_run\`);
+  \`bulk_delete_runs\` is not.
 
 ## Subworkflows — one workflow calling another
 Both halves live in the workflow DOCUMENT, so both are ordinary
@@ -944,13 +998,18 @@ point and it changes without the process changing.
   editing code, reviewing it and publishing a tool. A business user maintains a
   table; nobody should need you to change a postcode.
 
-**Static or dynamic — who owns the rows.**
-- \`isDynamic: false\` (the default) is reference data the AUTHOR maintains. A
-  workflow reads it and cannot change it. \`allowedOperations\` must be empty:
-  a permission nothing honours is refused, not stored.
-- \`isDynamic: true\` lets a workflow change the rows, limited to
+**Who fills it — \`filledBy\`, one per table** (\`author\`, \`workflow\`,
+\`query\` or \`source\`).
+- \`author\` (the default) is reference data the AUTHOR maintains. A workflow
+  reads it and cannot change it. \`allowedOperations\` must be empty: a
+  permission nothing honours is refused, not stored.
+- \`workflow\` lets a workflow change the rows, limited to
   \`allowedOperations\` — any of \`add\` / \`update\` / \`delete\`. READING IS
   NEVER LISTED there: it is what a table is for and is always allowed.
+- \`query\` fills the rows from a named query (\`fillingQueryId\`, on its
+  \`rhythm\` or with \`refresh_data_table\`).
+- \`source\` holds no rows here: they stay in a data source, and \`external\`
+  says where. \`create_data_table\` describes each filler's fields.
 - You edit rows through \`add_data_table_row\` / \`update_data_table_row\` /
   \`delete_data_table_row\` whatever the table's mode says — those grants are
   about what a RUN may do, not about authoring.
@@ -993,8 +1052,8 @@ value across from one of the others, and do not guess. Every column needs a
 \`description\`: an agent reads it to know what the column is for, and a save
 without one is refused.
 
-**\`list_data_tables\` is PAGED**, alone among the library lists — a tenant's
-reference data has no ceiling. Page one is not the library. Follow
+**\`list_data_tables\` is PAGED**, like \`list_measures\`, \`list_queries\` and
+\`list_applications\` — a tenant's reference data has no ceiling. Page one is not the library. Follow
 \`nextCursor\` while \`hasMore\` is true, or better, narrow in the query:
 \`name\` is exact and unique per workspace, so "does one called X already
 exist" is a single call rather than a walk. The page carries \`rowCount\`, never

package/dist/tools/conventions.js.map

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

package/dist/tools/dataTables.js

@@ -170,8 +170,9 @@ export function registerDataTableTools(server, client) {
         "`fill.lastAt`, `fill.lastRowCount` and `fill.lastError` describe the " +
         "run. " +
         "\n\nRefused with a 422 when the table is not filled by a query " +
-        "(`filledBy` is `author` or `workflow`) — its rows come from a workflow " +
-        "or an author, and there is nothing to run.", { id: z.string().describe("The table's id.") }, async ({ id }) => guard(async () => jsonResult(await client.post(`${BASE}/${id}/refresh`))));
+        "(`filledBy` is `author`, `workflow` or `source`) — its rows come from " +
+        "an author or a workflow, or stay in their data source, and there is " +
+        "nothing to run.", { id: z.string().describe("The table's id.") }, async ({ id }) => guard(async () => jsonResult(await client.post(`${BASE}/${id}/refresh`))));
     server.tool("list_data_table_tools", "Which tools this table yields, and which of them a RUN can actually " +
         "reach. Read-only. " +
         "\n\nA published table mints its own CRUD tools, so giving an agent " +

package/dist/tools/dataTables.js.map

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

package/dist/tools/entityContract.js

@@ -62,9 +62,11 @@ export async function readEntityContract(client, kinds) {
 }
 export function registerEntityContractTools(server, client) {
     server.tool("get_entity_authoring_contract", "Read this deploy's CREATE CONTRACT per entity kind from the platform " +
-        "itself — tools (each type's `implementation`, connectors included), " +
-        "agents, personas, knowledge, schemas, tables, toolboxes, secrets and " +
-        "starts. Answers `{ kinds, contracts, rulesVersion }`: per kind the " +
+        "itself, per kind: `tool` (each type's implementation, connectors " +
+        "included), `agent` (its persona included), `application`, `measure`, " +
+        "`query`, `data_table`, `output_schema`, `policy`, `skill`, " +
+        "`reference_doc`, `prompt_snippet`, `toolbox`, `secret`, " +
+        "`conditional_trigger` and `trigger_element`. Answers `{ kinds, contracts, rulesVersion }`: per kind the " +
         "`create` and `update` fields (name, required, type, allowed values, " +
         "shape, and `refused` with where the value is authored instead), and " +
         "`publish.rules` — what stops it from going live, each with a `code` " +

package/dist/tools/entityContract.js.map

@@ -1 +1 @@
-{"version":3,"file":"entityContract.js","sourceRoot":"","sources":["../../src/tools/entityContract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtD,kFAAkF;AAClF,MAAM,CAAC,MAAM,qBAAqB,GAAG,oCAAoC,CAAC;AAE1E,qEAAqE;AACrE,MAAM,CAAC,MAAM,2BAA2B,GACtC,+DAA+D;IAC/D,qCAAqC,qBAAqB,KAAK;IAC/D,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,yEAAyE;IACzE,qEAAqE;IACrE,4DAA4D,CAAC;AAE/D,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAqB,EAAE,KAAgB;IAC9E,MAAM,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1E,IAAI,CAAC;QACH,OAAO,UAAU,CACf,MAAM,CAAC,MAAM,KAAK,CAAC;YACjB,CAAC,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC;YACzC,CAAC,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CACzE,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,eAAe,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC;YACjF,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,2BAA2B,EAAE,CAAC;aACxE,CAAC;QACJ,CAAC;QACD,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,MAAiB,EAAE,MAAqB;IAClF,MAAM,CAAC,IAAI,CACT,+BAA+B,EAC/B,uEAAuE;QACrE,sEAAsE;QACtE,uEAAuE;QACvE,qEAAqE;QACrE,sEAAsE;QACtE,sEAAsE;QACtE,sEAAsE;QACtE,2DAA2D;QAC3D,uEAAuE;QACvE,qEAAqE;QACrE,yCAAyC;QACzC,2EAA2E;QAC3E,wEAAwE;QACxE,wEAAwE;QACxE,sDAAsD;QACtD,wEAAwE;QACxE,0EAA0E;QAC1E,iEAAiE;QACjE,mBAAmB,EACrB;QACE,KAAK,EAAE,CAAC;aACL,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;aACjB,QAAQ,EAAE;aACV,QAAQ,CACP,mEAAmE;YACjE,sEAAsE,CACzE;KACJ,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CACvD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"entityContract.js","sourceRoot":"","sources":["../../src/tools/entityContract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtD,kFAAkF;AAClF,MAAM,CAAC,MAAM,qBAAqB,GAAG,oCAAoC,CAAC;AAE1E,qEAAqE;AACrE,MAAM,CAAC,MAAM,2BAA2B,GACtC,+DAA+D;IAC/D,qCAAqC,qBAAqB,KAAK;IAC/D,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,yEAAyE;IACzE,qEAAqE;IACrE,4DAA4D,CAAC;AAE/D,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAqB,EAAE,KAAgB;IAC9E,MAAM,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1E,IAAI,CAAC;QACH,OAAO,UAAU,CACf,MAAM,CAAC,MAAM,KAAK,CAAC;YACjB,CAAC,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC;YACzC,CAAC,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CACzE,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,eAAe,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC;YACjF,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,2BAA2B,EAAE,CAAC;aACxE,CAAC;QACJ,CAAC;QACD,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,MAAiB,EAAE,MAAqB;IAClF,MAAM,CAAC,IAAI,CACT,+BAA+B,EAC/B,uEAAuE;QACrE,mEAAmE;QACnE,uEAAuE;QACvE,6DAA6D;QAC7D,0DAA0D;QAC1D,0GAA0G;QAC1G,sEAAsE;QACtE,sEAAsE;QACtE,sEAAsE;QACtE,2DAA2D;QAC3D,uEAAuE;QACvE,qEAAqE;QACrE,yCAAyC;QACzC,2EAA2E;QAC3E,wEAAwE;QACxE,wEAAwE;QACxE,sDAAsD;QACtD,wEAAwE;QACxE,0EAA0E;QAC1E,iEAAiE;QACjE,mBAAmB,EACrB;QACE,KAAK,EAAE,CAAC;aACL,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;aACjB,QAAQ,EAAE;aACV,QAAQ,CACP,mEAAmE;YACjE,sEAAsE,CACzE;KACJ,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CACvD,CAAC;AACJ,CAAC"}

package/dist/tools/extras.d.ts

@@ -1,16 +1,26 @@
 /**
- * Secondary MCP tools: the agent-scoped persona create/read (personas
- * themselves are a full generic entity — see index.ts — but creation and the
- * by-agent read have no equivalent generic route), connectors (a tool
- * subtype), attaching memory to a target, and a few standalone one-offs.
+ * Secondary MCP tools: an agent's persona, connectors (a tool subtype),
+ * attaching memory to a target, and a few standalone one-offs.
  *
  * These use routes with shapes that don't fit the generic entity registrar:
- * a persona is created only through its agent, connectors are a tool with
+ * the persona is a field of its agent, connectors are a tool with
  * `type: "connector"` and MUST NOT carry real credentials, and attach/detach
  * is a path-only link.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { AxonityClient } from "../client.js";
+/**
+ * The persona is the agent's `persona` field (axonity-flow#2176): the
+ * character text every prompt of the agent opens with, published with the
+ * agent. The persona entity, its own id, versions, drafts and approvals are
+ * gone, and so are the persona routes the tools called (21 persona operations
+ * left the API; 19 of them had a tool here).
+ *
+ * These two tools stay as the migration path: an agent that knows them lands
+ * on the field instead of on a 404 it would read as "no such id". Everything
+ * else about a persona is the agent's: its history is the agent's versions,
+ * it goes live with `request_publish_agent`.
+ */
 export declare function registerPersonaTools(server: McpServer, client: AxonityClient): void;
 export declare function registerConnectorTools(server: McpServer, client: AxonityClient): void;
 /** Keep the envelope, project the rows down to identity. */

package/dist/tools/extras.js

@@ -1,31 +1,66 @@
 /**
- * Secondary MCP tools: the agent-scoped persona create/read (personas
- * themselves are a full generic entity — see index.ts — but creation and the
- * by-agent read have no equivalent generic route), connectors (a tool
- * subtype), attaching memory to a target, and a few standalone one-offs.
+ * Secondary MCP tools: an agent's persona, connectors (a tool subtype),
+ * attaching memory to a target, and a few standalone one-offs.
  *
  * These use routes with shapes that don't fit the generic entity registrar:
- * a persona is created only through its agent, connectors are a tool with
+ * the persona is a field of its agent, connectors are a tool with
  * `type: "connector"` and MUST NOT carry real credentials, and attach/detach
  * is a path-only link.
  */
 import { z } from "zod";
 import { assertPlaceholderCredentials } from "./credentials.js";
 import { detachResult, guard, jsonResult } from "./result.js";
+/**
+ * The persona is the agent's `persona` field (axonity-flow#2176): the
+ * character text every prompt of the agent opens with, published with the
+ * agent. The persona entity, its own id, versions, drafts and approvals are
+ * gone, and so are the persona routes the tools called (21 persona operations
+ * left the API; 19 of them had a tool here).
+ *
+ * These two tools stay as the migration path: an agent that knows them lands
+ * on the field instead of on a 404 it would read as "no such id". Everything
+ * else about a persona is the agent's: its history is the agent's versions,
+ * it goes live with `request_publish_agent`.
+ */
 export function registerPersonaTools(server, client) {
-    server.tool("read_agent_persona", "Read an agent's persona (voice/character). A persona is 1:1 with an agent — " +
-        "there is no standalone persona list.", { agentId: z.string().describe("The agent's id.") }, async ({ agentId }) => guard(async () => jsonResult(await client.get(`/api/v1/agents/${agentId}/persona`))));
-    server.tool("create_agent_persona", "Create an agent's persona. Pass name, characterText and optional status.", {
+    server.tool("read_agent_persona", "Read an agent's persona: the character text every prompt of this agent " +
+        "opens with. It is the agent's `persona` field (also in `read_agent`), " +
+        "returned here with the agent's `version`, which `create_agent_persona` " +
+        "and `update_agent` take as `expectedVersion`. `persona` is null or `\"\"` " +
+        "when the agent has none (null: never set; `\"\"`: removed). Replaces " +
+        "`read_persona`, `read_persona_published`, `read_persona_version`, " +
+        "`list_persona_versions`, `list_deleted_persona_versions`, " +
+        "`list_personas` and `list_deleted_personas`: a persona has no id, " +
+        "versions or list of its own any more.", { agentId: z.string().describe("The agent's id.") }, async ({ agentId }) => guard(async () => {
+        const agent = (await client.get(`/api/v1/agents/${agentId}`));
+        return jsonResult({
+            agentId,
+            persona: agent.persona ?? null,
+            version: agent.version,
+        });
+    }));
+    server.tool("create_agent_persona", "Set an agent's persona: who the agent is, in its own words — the " +
+        "character text every prompt of this agent opens with. It writes the " +
+        "agent's `persona` field on its draft (the same as `update_agent` with " +
+        "`{ persona }`) and goes live with the agent (`request_publish_agent`). " +
+        "Setting it again replaces it. Read the agent first (`read_agent` or " +
+        "`read_agent_persona`) for `expectedVersion`; on a 409, re-read and retry. " +
+        "There is no separate name or status: a persona is only its text. To " +
+        "remove it, send `\"\"`; on update_agent `null` changes nothing. Replaces " +
+        "`update_persona`, `delete_persona`, `restore_persona`, " +
+        "`discard_persona_draft`, `create_persona_major_version`, " +
+        "`ensure_persona_major_version`, `name_persona_major_version`, " +
+        "`delete_persona_version`, `restore_persona_version`, " +
+        "`restore_deleted_persona_version` and `request_publish_persona`: the " +
+        "persona's history is the agent's versions, and it goes live with " +
+        "`request_publish_agent`.", {
         agentId: z.string().describe("The agent's id."),
-        fields: z
-            .record(z.unknown())
-            .describe('Persona fields, e.g. { "name": "…", "characterText": "…" }.'),
-    }, async ({ agentId, fields }) => guard(async () => jsonResult(await client.post(`/api/v1/agents/${agentId}/persona`, fields))));
-    // Reading/updating a persona by its OWN id (list_personas, read_persona,
-    // update_persona, delete_persona, restore_persona, …) is generated generically
-    // from the "persona" EntityDef in index.ts — identical PUT semantics to what
-    // used to be hand-written here. Only the agent-scoped create/read above are
-    // bespoke, because personas have no standalone create route.
+        expectedVersion: z
+            .number()
+            .int()
+            .describe("The agent's current `version`, from read_agent or read_agent_persona."),
+        persona: z.string().describe("The character text, as the agent should read it."),
+    }, async ({ agentId, expectedVersion, persona }) => guard(async () => jsonResult(await client.put(`/api/v1/agents/${agentId}`, { expectedVersion, persona }))));
 }
 /**
  * The shape `implementation` must have for a connector to run.
@@ -56,6 +91,11 @@ const CONNECTOR_SHAPE = "\n\nSHAPE OF `implementation` — `headers` and `queryP
  * file of the run, not parsed. Without this sentence the only mappings an agent
  * knew were the parsing ones.
  *
+ * `sha256` in the reference (axonity-flow#2299): the hash stored with the
+ * bytes, settled from storage where a reference enters a run, so a workflow
+ * can recognise a file it already processed. Which value counts is said here
+ * because a caller-written hash would silently skip a new document.
+ *
  * Kept short on purpose: the platform's live contract
  * (`get_entity_authoring_contract`, axonity-flow#2103) is the authority, and
  * this is guidance until every deploy serves it.
@@ -68,8 +108,20 @@ const CONNECTOR_EFFECT_AND_FILE = "\n\nDECLARE WHAT IT DOES — `implementation.
     "\n\nAN ANSWER THAT IS A FILE — `implementation.responseMapping: " +
     '{ "type": "file", "filename": "{{filename}}" }`. The bytes are kept as a ' +
     "file of the run and the connector returns its reference, `{ fileId, " +
-    "filename, contentType, sizeBytes }` — the shape an upload has, so Digitize " +
-    "documents reads it and a sub-workflow's file parameter takes it. " +
+    "filename, contentType, sizeBytes, sha256 }` — the shape an upload has, so " +
+    "Digitize documents reads it and a sub-workflow's file parameter takes it. " +
+    "`sha256` is the hex SHA-256 of the bytes, computed once when the file was " +
+    "stored; the same bytes have the same value under any name, so compare it " +
+    "to recognise a file that was already processed. Only a reference in a " +
+    "declared file parameter (`file`, or a list of `file`) is checked against " +
+    "storage: where one enters a run (a manual, API or MCP start, a " +
+    "sub-workflow call) its fields are settled from storage. A reference to a " +
+    "file the run may not read keeps what the caller wrote and carries no " +
+    "`sha256` — at a webhook, cron or conditional start, each of them. A " +
+    "reference anywhere else (an `object` field, an undeclared key) is not " +
+    "checked and keeps any `sha256` the caller wrote. Digitize documents " +
+    "always answers the stored `sha256` per file it read. So compare only the " +
+    "value on a declared file parameter or on Digitize's entry. " +
     "`filename` is optional and may use the inputs (`{{name}}`); without it the " +
     "far end's `Content-Disposition` name is used, else `document`. A file " +
     "answer takes no `responseTransform`. Outside a run (e.g. " +