@axonity-ai/mcp 0.17.1 → 0.20.0

package/dist/tools/conventions.js

@@ -241,6 +241,16 @@ has run cleanly once, at its current version.
 
 ## Per entity — what to create, and what "complete" means
 
+**The platform's live create contract wins.** \`get_entity_authoring_contract\`
+reads this deploy's own contract per entity — required fields, allowed values,
+and the rules a publication checks — generated from the code that enforces
+them, with a \`rulesVersion\`. The notes below are kept by hand in this
+connector: guidance on order and on what "complete" means, SUBORDINATE to that
+contract. Where they disagree, the contract is right and this text is behind.
+On a deploy that does not serve it yet the tool says so; then the platform's
+refusal on save or publish (and \`get_publish_release\`'s readiness) is the
+authority, not these notes.
+
 Build in dependency order: a thing you will REFERENCE must exist before the
 thing that references it. So: tools and output-schemas first, then agents (which
 list tool ids), then workflows (whose steps name agents and tools), then
@@ -251,7 +261,7 @@ made any time before you attach them.
 - Required: \`name\`. Also: \`description\`, \`type\`, \`inputSchema\`,
   \`outputSchema\`, \`implementation\`, \`authConfig\`, \`surfacing\`.
 - \`type\`: \`"function"\` (default) | \`"connector"\` | \`"validator"\` |
-  \`"evaluator"\`. \`surfacing\`: \`"always"\` (in the agent's tool list) |
+  \`"evaluator"\` | \`"executor"\`. \`surfacing\`: \`"always"\` (in the agent's tool list) |
   \`"on_demand"\`.
 - \`inputSchema\` / \`outputSchema\` are JSON-Schema objects describing the tool's
   params and result. Set them — an agent binds to a tool by its declared I/O; a
@@ -270,6 +280,23 @@ made any time before you attach them.
     or ""); a human fills the secret in Axonity. Test with
     \`execute_stored_connector\` (uses the real, server-side-decrypted secret;
     you see only the result).
+    - **\`implementation.effect\` is required to PUBLISH**: \`"reads"\` (fetches,
+      looks something up) or \`"acts"\` (sends, writes, starts something). A
+      draft saves without it; the publish approval refuses it ("Set the
+      connector's side effects … before publishing"). Set it at create time,
+      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
+      (\`execute_stored_connector\`) nothing is stored: you see name and size.
+  - **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
+    \`list_executor_commands\` say what exists.
   - **validator / evaluator** — a constrained kind, and \`implementation\` takes
     ONE OF TWO shapes. Either \`{"builtin": "validators.<name>"}\`, naming a
     house predicate — look at the tenant's existing validator/evaluator tools
@@ -311,6 +338,15 @@ made any time before you attach them.
   - \`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\`.
+- A step's GOAL is read from a different place per step type: an \`agent\`
+  step's \`contract.goal\`, a \`manual\` or \`automation\` step's
+  \`config.goal\`. Written in the other place it is stored and read by nobody,
+  and the validator keeps reporting \`step_no_goal\`.
+- After every \`apply_workflow_mutations\` / \`replace_workflow_document\` the
+  connector runs \`validate_workflow\` on the stored workflow and returns its
+  verdict as \`validation\`. Report those issues as they are. Green there means
+  every PLATFORM check passed — none of them asks whether the editor can draw
+  the document, so open it in the editor before you call it done.
 - 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
@@ -345,8 +381,9 @@ made any time before you attach them.
   then wire with the \`attach_*\` tools — see Wiring.
 - A reference doc has NO kind any more. What used to be a semantic note lives
   in the model itself: a word is a concept (\`create_concept\`), a table card
-  is the table's description and grain, a source query is the table's
-  \`provenance\`, an example question is a measure's \`questions\`. The
+  is the table's description and grain, a source query is a query of its
+  own (\`create_query\`, the table's \`fillingQueryId\`), an example question
+  is a measure's \`questions\`. The
   platform refuses \`semanticKind\`, \`semanticDetails\`, \`subjectTableId\`
   and \`subjectSourceId\` on a reference doc, and says where each one went.
   Building the SEMANTIC MODEL? Read \`axonity_semantic_conventions\` first —
@@ -383,8 +420,10 @@ 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; what follows
-is the part you cannot author without.
+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.
 
 - 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
@@ -727,14 +766,15 @@ a document to find out what the platform did.
 ## Triggers
 - 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.
+- **A schedule and a conditional start are reconciled for you.** Draw them in
+  the document, publish, and the firing row is brought into line: created,
+  updated, and removed when the element is gone. A deploy does the same and
+  brings new ones in switched off.
+- **A webhook is NOT.** Its row must be created separately —
+  \`create_webhook_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.
@@ -751,26 +791,44 @@ a document to find out what the platform did.
 - \`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.
-- **A conditional trigger without a CHECK starts the workflow every beat.** It
-  wakes on its interval and, with nothing set, runs regardless of whether there
-  was anything to do — a mailbox on fifteen minutes then makes ninety-six empty
-  runs a day. Set \`checkKind\` on \`create_conditional_trigger\`, or on an
-  existing one with \`update_conditional_trigger\`; every trigger authored
-  before checks existed has none, so read \`checkKind\` in
-  \`list_conditional_triggers\` before assuming otherwise.
-- \`checkKind: "automatic"\` is ONE tool call and one rule on its answer — no
-  model, so it is the cheap way to ask "is there anything there?". Its
-  \`checkConfig\` is \`{ toolId, inputs?, rule: { field, op, value } }\`, where
-  \`field\` names a key OF THE TOOL'S ANSWER. A rule pointing at a field the
-  tool never returns is reported as a broken setup, not as "condition not met".
-  \`"agent"\` is reserved for a model judging the condition and is refused
-  today. Do not pre-validate a check here — the backend judges it with the same
-  function the dispatcher runs when the trigger fires, and its refusal says
-  what to change.
-- **To take a check off again, send \`checkKind: ""\`** — the empty string. It
-  clears the kind and its config together and returns the trigger to starting
-  every beat. Omitting the field leaves the check standing, which is why the
-  empty string exists at all.
+- **A conditional start is authored in the workflow, on the trigger element.**
+  Its \`typeId\` is \`"conditional-poll"\`, its \`id\` MUST be a UUID (the
+  platform cannot make a row for any other id), and everything it does lives
+  on its \`config\`: \`conditionText\`, \`repeatIntervalMinutes\`, and the
+  CHECK — \`checkKind\` with that kind's settings. Write it with
+  \`apply_workflow_mutations\` (\`add_trigger\`, or \`update_trigger\`, which
+  REPLACES \`config\` whole — read it, change it, send all of it). Publishing
+  copies it onto the row \`list_conditional_triggers\` shows.
+  \`create_conditional_trigger\` is not the normal path, and the platform
+  refuses a check sent to it or to \`update_conditional_trigger\`: "A
+  conditional start's check is set on the start in the workflow, and takes
+  effect when the workflow is published."
+- **A conditional start without a CHECK starts the workflow every beat.** It
+  wakes on its interval and, with no \`checkKind\`, runs regardless of whether
+  there was anything to do — a mailbox on fifteen minutes then makes
+  ninety-six empty runs a day. Read \`checkKind\` in
+  \`list_conditional_triggers\` before assuming a start has one.
+- \`checkKind: "automatic"\` decides with no model, before a run exists. Its
+  settings on \`config\` are \`plan\` (the steps of an automation step, each
+  with a \`toolId\`), \`outputs\` (what the plan produces — not worked out by
+  an agent) and \`startsWhen\` (rules \`{ field, op, value }\` of a decision's
+  rule table, where \`field\` names one of those outputs). A look that cannot
+  be made — a broken tool, a rule on an output nothing produces — is a fault,
+  never a start.
+- \`checkKind: "agent"\` is for a condition that needs judgement: the beat
+  becomes a run whose first step asks the agent named by \`config.agentId\`
+  (else the workflow's owner); it stays out of the Runs list until the answer
+  is yes. Settings: \`agentId\`, \`toolIds\`, \`inputs\`, \`reasoningLevel\`.
+- Do not pre-validate a check here. \`validate_workflow\` judges it
+  (\`conditional_check_invalid\`) with the same function the dispatcher runs
+  when the start fires, and the refusal says what to change.
+- **Removing \`checkKind\` does NOT take a check off.** A \`config\` without it
+  is read as a start written before checks existed, and the row keeps the
+  check it has. There is no way to return a start to "every beat" today; say
+  so to your human rather than looking for a route to the row.
+- Publishing also switches every start of the workflow back ON. An
+  \`update_conditional_trigger({ enabled: false })\` lasts until the next
+  publish of that workflow.
 
 ## Evaluating what you built
 - There is no findings endpoint and no evaluator entity. To judge a run, read it:
@@ -970,6 +1028,15 @@ the rows; the rows come from \`read_data_table\`.
   the box, call \`list_toolbox_dependent_tools\` — it names the tools that would
   start failing at run time with a bare 401.
 
+## Who may read what
+Every policy, skill, reference doc and table carries a label: \`level\`
+(public, internal, confidential) and \`audienceIds\`, whom it is meant for. An
+agent and a workflow carry a \`clearance\`; so does your token, and you read
+with it. Look audience ids up with \`list_audiences\` — never guess one, and
+compare on id, never on name. \`level: null\` makes a thing readable by nobody.
+Narrowing a label is always allowed; widening it is a colleague's act, never
+yours.
+
 ## Tenant
 - Your token fixes the tenant. You cannot act across tenants; never send a
   tenant id in a body.
@@ -1013,7 +1080,7 @@ const SEMANTIC_KNOWLEDGE_UNAVAILABLE = "## Semantic knowledge — NOT AVAILABLE\
     "The rules for writing the semantic layer could not be read from this deploy " +
     `(\`GET ${SEMANTIC_KNOWLEDGE_ROUTE}\`). This connector does not carry a copy ` +
     "of them. Do not build the semantic model — no concept, no measure, no " +
-    "table provenance — until they can be read: call " +
+    "query — until they can be read: call " +
     "`axonity_semantic_conventions` again, and if it still fails, report it " +
     "rather than deciding what the knowledge should say yourself.";
 /**
@@ -1077,9 +1144,9 @@ is the window ending at the end of the period asked for; a running total per
 month is the standing at the end of each month, never their sum. A fact kept
 per month is not asked per week (\`grain_too_fine\`).
 
-**Row logic belongs in the table's source query, not in a measure.** A value
-per row (net = gross − discount) is a column, added to the table's
-\`provenance.sql\` and described like any other column. A measure is computed
+**Row logic belongs in the query that fills the table, not in a measure.** A
+value per row (net = gross − discount) is a column, added to that query's
+\`sql\` and described like any other column. A measure is computed
 per question — period, grain, split, filters — and is never stored.
 
 **How a number is computed.** Each leaf is aggregated on its own table, over
@@ -1129,7 +1196,7 @@ export function registerConventions(server, client) {
         ],
     }));
     server.tool("axonity_semantic_conventions", "Read BEFORE building a workspace's semantic model: the tables with " +
-        "their provenance and grain, the measures, and the concepts that say " +
+        "the queries that fill them and their grain, the measures, and the concepts that say " +
         "what a word or a number means. Returns this deploy's rules for writing " +
         "it: what a concept owes, what a measure's description and questions " +
         "must say, and what a table's grain must say about one row. Read live " +

package/dist/tools/conventions.js.map

@@ -1 +1 @@
-{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/tools/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAMH,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAi7B1B,CAAC;AAEF,mEAAmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,oCAAoC,CAAC;AAEpE,yEAAyE;AACzE,MAAM,CAAC,MAAM,wBAAwB,GAAG,sCAAsC,CAAC;AAQ/E;;;;GAIG;AACH,MAAM,qBAAqB,GACzB,iDAAiD;IACjD,wEAAwE;IACxE,UAAU,eAAe,iDAAiD;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,yEAAyE;IACzE,WAAW,CAAC;AAEd,qFAAqF;AACrF,MAAM,8BAA8B,GAClC,2CAA2C;IAC3C,8EAA8E;IAC9E,UAAU,wBAAwB,4CAA4C;IAC9E,wEAAwE;IACxE,kDAAkD;IAClD,yEAAyE;IACzE,8DAA8D,CAAC;AAEjE;;;;;GAKG;AACH,KAAK,UAAU,eAAe,CAC5B,MAAqB,EACrB,KAAa,EACb,IAAY,EACZ,WAAmB;IAEnB,IAAI,QAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAkB,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,EAAE,QAAQ,CAAC;IACpC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3D,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,MAAM,OAAO,GACX,OAAO,QAAQ,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;IAChF,OAAO,CACL,OAAO,IAAI,wCAAwC;QACnD,mBAAmB,OAAO,UAAU;QACpC,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAqB;IAC5D,OAAO,eAAe,CACpB,MAAM,EACN,eAAe,EACf,gCAAgC,EAChC,qBAAqB,CACtB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoDtC,CAAC;AAEF,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,MAAqB;IACpE,MAAM,KAAK,GAAG,MAAM,eAAe,CACjC,MAAM,EACN,wBAAwB,EACxB,sCAAsC,EACtC,8BAA8B,CAC/B,CAAC;IACF,0EAA0E;IAC1E,yDAAyD;IACzD,IAAI,KAAK,KAAK,8BAA8B;QAAE,OAAO,KAAK,CAAC;IAC3D,OAAO,GAAG,KAAK,OAAO,uBAAuB,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAiB,EAAE,MAAqB;IAC1E,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,2EAA2E;QACzE,2EAA2E;QAC3E,2EAA2E;QAC3E,4EAA4E;QAC5E,uEAAuE;QACvE,uEAAuE;QACvE,uEAAuE;QACvE,+DAA+D,EACjE,EAAE,EACF,KAAK,IAAI,EAAE,CAAC,CAAC;QACX,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,GAAG,WAAW,KAAK,MAAM,kBAAkB,CAAC,MAAM,CAAC,EAAE;aAC5D;SACF;KACF,CAAC,CACH,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,8BAA8B,EAC9B,qEAAqE;QACnE,sEAAsE;QACtE,yEAAyE;QACzE,sEAAsE;QACtE,uEAAuE;QACvE,wEAAwE;QACxE,sEAAsE;QACtE,qEAAqE;QACrE,2BAA2B,EAC7B,EAAE,EACF,KAAK,IAAI,EAAE,CAAC,CAAC;QACX,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC,MAAM,CAAC,EAAE,CAAC;KACrF,CAAC,CACH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/tools/conventions.ts"],"names":[],"mappings":"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"}

package/dist/tools/dataSources.d.ts

@@ -10,11 +10,11 @@
  * shows, and duplicating a dashboard.
  *
  * **There are no sync tools any more.** A sync was a separate object beside
- * the table it filled; the semantic model made it the table's own
- * `provenance` (source, query, grain, key, mode, schedule), so a changed query
- * goes through the same approval as a changed column. Filling a table is now
- * `create_data_table` / `update_data_table` with `provenance`, and running it
- * early is `refresh_data_table` (tools/dataTables.ts). A measure is no longer
+ * the table it filled. The semantic model first made it the table's own
+ * `provenance`; axonity-flow#2013 then moved the source, SQL and grain into a
+ * named query (tools/queries.ts), leaving the table its `filledBy`,
+ * `fillingQueryId` and `rhythm`. Running a fill early is `refresh_data_table`
+ * (tools/dataTables.ts). A measure is no longer
  * a field on a table either: it is its own versioned entity (`create_measure`
  * and the rest of the generic family).
  *

package/dist/tools/dataSources.js

@@ -10,11 +10,11 @@
  * shows, and duplicating a dashboard.
  *
  * **There are no sync tools any more.** A sync was a separate object beside
- * the table it filled; the semantic model made it the table's own
- * `provenance` (source, query, grain, key, mode, schedule), so a changed query
- * goes through the same approval as a changed column. Filling a table is now
- * `create_data_table` / `update_data_table` with `provenance`, and running it
- * early is `refresh_data_table` (tools/dataTables.ts). A measure is no longer
+ * the table it filled. The semantic model first made it the table's own
+ * `provenance`; axonity-flow#2013 then moved the source, SQL and grain into a
+ * named query (tools/queries.ts), leaving the table its `filledBy`,
+ * `fillingQueryId` and `rhythm`. Running a fill early is `refresh_data_table`
+ * (tools/dataTables.ts). A measure is no longer
  * a field on a table either: it is its own versioned entity (`create_measure`
  * and the rest of the generic family).
  *
@@ -57,14 +57,15 @@ export function registerDataSourceTools(server, client) {
         "query. `containerWord` is what this warehouse calls the container " +
         "(\"dataset\" on BigQuery, \"schema\" on PostgreSQL). Column types are " +
         "the warehouse's own names, passed through. Read this before writing a " +
-        "query or a table's provenance, rather than guessing table names. " +
+        "query, rather than guessing table names. " +
         "On a source restricted to `policy.allowedDatasets` it reads those " +
         "datasets one by one, so it answers even when the key may not list " +
         "the whole project.", { id: SOURCE_ID }, async ({ id }) => guard(async () => jsonResult(await client.get(`${SOURCES}/${id}/schema`))));
     server.tool("query_data_source", "Run a READ-ONLY SQL query against the warehouse and get the rows back. " +
         "For looking — checking what a warehouse table holds, trying the " +
-        "query a table's provenance will run. To fill a table regularly, give " +
-        "it a `provenance` (create_data_table / update_data_table). " +
+        "statement before it becomes a query. To fill a table regularly, make " +
+        "it a query (create_query, try it with test_query) and point the table " +
+        "at it: `filledBy: \"query\"`, `fillingQueryId`, `rhythm`. " +
         "\n\nTHE ROWS ARE CAPPED. `truncated: true` means rows were left out: " +
         "`rowCount` is what came back, `totalRows` is what matched. Never report " +
         "a count or a total off a truncated answer — aggregate in the SQL " +
@@ -86,7 +87,7 @@ export function registerDataSourceTools(server, client) {
             .int()
             .optional()
             .describe("How many rows you want back. Clamped by the platform — a bigger " +
-            "answer belongs in a table with provenance, not in a response."),
+            "answer belongs in a table filled by a query, not in a response."),
     }, async ({ id, sql, maxRows }) => guard(async () => jsonResult(await client.post(`${SOURCES}/${id}/query`, {
         sql,
         ...(maxRows !== undefined ? { maxRows } : {}),

package/dist/tools/dataSources.js.map

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

package/dist/tools/dataTables.js

@@ -159,17 +159,19 @@ export function registerDataTableTools(server, client) {
     // The page envelope is forwarded WHOLE — unwrapping to `items` would
     // rebuild the silent truncation this tool exists to avoid.
     jsonResult(await client.get(`${BASE}/${tableId}/rows`, { q, limit, cursor }))));
-    server.tool("refresh_data_table", "Fill a table from its source NOW instead of at its next scheduled time. " +
-        "Replaces run_data_source_sync: a table's fill is its own `provenance` " +
-        "now, not a separate sync. " +
+    server.tool("refresh_data_table", "Fill a table from its query NOW instead of at its next scheduled time " +
+        "— or at all, for a table with no `rhythm`, which fills only when " +
+        "asked. Replaces run_data_source_sync: what fills a table is the query " +
+        "its `fillingQueryId` names, not a separate sync. " +
         "\n\nTHIS DOES NOT WAIT FOR THE RESULT. The query can take tens of " +
         "seconds, so the platform brings the table's next fill forward and its " +
         "scheduler runs it. The response is the table, with `fill.nextAt` set " +
         "to now. To see how it went, read_data_table again after a moment: " +
         "`fill.lastAt`, `fill.lastRowCount` and `fill.lastError` describe the " +
         "run. " +
-        "\n\nRefused with a 422 when the table has no `provenance` — 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`))));
+        "\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`))));
     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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,IAAI,GAAG,qBAAqB,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,KAAK,GAAG;IACZ,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,CACP,qEAAqE;QACnE,wEAAwE;QACxE,wEAAwE;QACxE,oDAAoD,CACvD;IACH,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,QAAQ,CACP,wEAAwE;QACtE,8DAA8D;QAC9D,6CAA6C,CAChD;CACJ,CAAC;AAEF,MAAM,UAAU,sBAAsB,CACpC,MAAiB,EACjB,MAAqB;IAErB,MAAM,CAAC,IAAI,CACT,oBAAoB,EACpB,uEAAuE;QACrE,qEAAqE;QACrE,uEAAuE;QACvE,0EAA0E;QAC1E,cAAc;QACd,uEAAuE;QACvE,2EAA2E;QAC3E,gDAAgD;QAChD,mEAAmE;QACnE,2DAA2D;QAC3D,yEAAyE;QACzE,wEAAwE,EAC1E;QACE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAC1C,MAAM,EAAE,CAAC;aACN,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;aACnB,QAAQ,CACP,mEAAmE;YACjE,+CAA+C,CAClD;KACJ,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CACvB,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CACrF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,uBAAuB,EACvB,4EAA4E;QAC1E,2EAA2E;QAC3E,qBAAqB;QACrB,0EAA0E;QAC1E,8BAA8B;QAC9B,yEAAyE;QACzE,uEAAuE;QACvE,2DAA2D;QAC3D,6DAA6D,EAC/D;QACE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAC1C,GAAG,KAAK;QACR,OAAO,EAAE,CAAC;aACP,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;aACnB,QAAQ,CACP,oEAAoE;YAClE,oEAAoE,CACvE;KACJ,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,EAAE,CACjD,KAAK,CAAC,KAAK,IAAI,EAAE,CACf,UAAU,CACR,MAAM,MAAM,CAAC,KAAK,CAChB,GAAG,IAAI,IAAI,EAAE,OAAO,EACpB,EAAE,OAAO,EAAE,EACX,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,CACvD,CACF,CACF,CACJ,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,uBAAuB,EACvB,wCAAwC;QACtC,yEAAyE;QACzE,0EAA0E;QAC1E,oDAAoD;QACpD,wEAAwE;QACxE,2EAA2E;QAC3E,iEAAiE;QACjE,sEAAsE,EACxE;QACE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAC1C,GAAG,KAAK;QACR,OAAO,EAAE,CAAC;aACP,OAAO,CAAC,IAAI,CAAC;aACb,QAAQ,CACP,oEAAoE;YAClE,6DAA6D,CAChE;KACJ,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE,EAAE,CACxC,KAAK,CAAC,KAAK,IAAI,EAAE,CACf,UAAU,CACR,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,EAAE,OAAO,EAAE;QACrC,YAAY,EAAE,WAAW;QACzB,WAAW,EAAE,UAAU;KACxB,CAAC,CACH,CACF,CACJ,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,sBAAsB,EACtB,0EAA0E;QACxE,kEAAkE;QAClE,uEAAuE;QACvE,0EAA0E;QAC1E,0EAA0E;QAC1E,0EAA0E;QAC1E,sEAAsE;QACtE,0EAA0E;QAC1E,2EAA2E;QAC3E,8CAA8C;QAC9C,yEAAyE;QACzE,0EAA0E;QAC1E,6BAA6B;QAC7B,sEAAsE;QACtE,oEAAoE;QACpE,qEAAqE;QACrE,0EAA0E;QAC1E,uDAAuD,EACzD;QACE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAC/C,CAAC,EAAE,CAAC;aACD,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,kEAAkE;YAChE,gDAAgD,CACnD;QACH,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,GAAG,EAAE;aACL,QAAQ,EAAE;aACV,QAAQ,CACP,qEAAqE;YACnE,qCAAqC,CACxC;QACH,MAAM,EAAE,CAAC;aACN,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,0DAA0D;YACxD,iEAAiE;YACjE,0DAA0D,CAC7D;KACJ,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CACtC,KAAK,CAAC,KAAK,IAAI,EAAE;IACf,qEAAqE;IACrE,2DAA2D;IAC3D,UAAU,CACR,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,OAAO,OAAO,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAClE,CACF,CACJ,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,oBAAoB,EACpB,0EAA0E;QACxE,wEAAwE;QACxE,4BAA4B;QAC5B,oEAAoE;QACpE,wEAAwE;QACxE,uEAAuE;QACvE,oEAAoE;QACpE,uEAAuE;QACvE,OAAO;QACP,uEAAuE;QACvE,iEAAiE,EACnE,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,EAC9C,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CACf,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAC5E,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,uBAAuB,EACvB,sEAAsE;QACpE,oBAAoB;QACpB,qEAAqE;QACrE,yEAAyE;QACzE,oEAAoE;QACpE,qEAAqE;QACrE,0EAA0E;QAC1E,2DAA2D;QAC3D,mEAAmE;QACnE,sEAAsE;QACtE,wEAAwE;QACxE,wEAAwE;QACxE,4DAA4D;QAC5D,mEAAmE;QACnE,qCAAqC,EACvC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,EAC9C,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CACf,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CACzE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"dataTables.js","sourceRoot":"","sources":["../../src/tools/dataTables.ts"],"names":[],"mappings":"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"}

package/dist/tools/entityContract.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The platform's create contract per entity kind, read live (axonity-mcp#95,
+ * axonity-flow#2103, merged as axonity-flow#2104).
+ *
+ * The rules for creating a tool, a connector, an agent, a table — required
+ * fields, allowed values, what a publication checks — were kept as prose in
+ * this connector (`conventions.ts`, the tool descriptions). A rule added on the
+ * platform then stayed missing here: since axonity-flow#1997 a connector must
+ * declare `implementation.effect` before it can be published, and nothing in
+ * this connector said so. An agent built a connector by the guide and the
+ * human's approval refused it.
+ *
+ * For workflows that problem is already solved: `get_workflow_authoring_spec`
+ * reads `GET /workflows/operations`, generated from the registry that enforces
+ * it. This is the same move for every other kind:
+ *
+ *   GET /api/v1/authoring/entity-contracts?kinds=tool,agent
+ *   → { kinds: string[], contracts: { <kind>: {...} }, rulesVersion: string }
+ *
+ * `kinds` is ONE comma-separated query parameter, filtered by the platform; an
+ * unknown kind is the platform's 422, which names the known ones — passed on as
+ * the error it is, not re-judged here. `rulesVersion` covers the whole
+ * catalogue whatever `kinds` was. Authenticated like every route; a read-only
+ * service token is enough. The answer is passed through unchanged.
+ *
+ * FEATURE-DETECTED, NEVER SUBSTITUTED. A backend older than the route answers
+ * 404 (or 405). Then the tool says so in words — it does not fall back to the
+ * hand-kept notes in `axonity_conventions`, because those notes are exactly
+ * what drifted. Any other failure is reported as the error it is.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AxonityClient } from "../client.js";
+/** Where this deploy serves its per-kind create contracts (axonity-flow#2103). */
+export declare const ENTITY_CONTRACT_ROUTE = "/api/v1/authoring/entity-contracts";
+/** Said when the deploy does not serve the route. Not a fallback. */
+export declare const ENTITY_CONTRACT_UNAVAILABLE: string;
+/** What the tool answers: the live contract, the not-served notice, or the error. */
+export declare function readEntityContract(client: AxonityClient, kinds?: string[]): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function registerEntityContractTools(server: McpServer, client: AxonityClient): void;

package/dist/tools/entityContract.js

@@ -0,0 +1,90 @@
+/**
+ * The platform's create contract per entity kind, read live (axonity-mcp#95,
+ * axonity-flow#2103, merged as axonity-flow#2104).
+ *
+ * The rules for creating a tool, a connector, an agent, a table — required
+ * fields, allowed values, what a publication checks — were kept as prose in
+ * this connector (`conventions.ts`, the tool descriptions). A rule added on the
+ * platform then stayed missing here: since axonity-flow#1997 a connector must
+ * declare `implementation.effect` before it can be published, and nothing in
+ * this connector said so. An agent built a connector by the guide and the
+ * human's approval refused it.
+ *
+ * For workflows that problem is already solved: `get_workflow_authoring_spec`
+ * reads `GET /workflows/operations`, generated from the registry that enforces
+ * it. This is the same move for every other kind:
+ *
+ *   GET /api/v1/authoring/entity-contracts?kinds=tool,agent
+ *   → { kinds: string[], contracts: { <kind>: {...} }, rulesVersion: string }
+ *
+ * `kinds` is ONE comma-separated query parameter, filtered by the platform; an
+ * unknown kind is the platform's 422, which names the known ones — passed on as
+ * the error it is, not re-judged here. `rulesVersion` covers the whole
+ * catalogue whatever `kinds` was. Authenticated like every route; a read-only
+ * service token is enough. The answer is passed through unchanged.
+ *
+ * FEATURE-DETECTED, NEVER SUBSTITUTED. A backend older than the route answers
+ * 404 (or 405). Then the tool says so in words — it does not fall back to the
+ * hand-kept notes in `axonity_conventions`, because those notes are exactly
+ * what drifted. Any other failure is reported as the error it is.
+ */
+import { z } from "zod";
+import { AxonityApiError } from "../errors.js";
+import { errorResult, jsonResult } from "./result.js";
+/** Where this deploy serves its per-kind create contracts (axonity-flow#2103). */
+export const ENTITY_CONTRACT_ROUTE = "/api/v1/authoring/entity-contracts";
+/** Said when the deploy does not serve the route. Not a fallback. */
+export const ENTITY_CONTRACT_UNAVAILABLE = "## Entity create contracts — NOT AVAILABLE on this deploy\n\n" +
+    `This backend does not serve \`GET ${ENTITY_CONTRACT_ROUTE}\` ` +
+    "(axonity-flow#2103): it is older than the live contract. This connector " +
+    "carries no copy of it. The per-entity notes in `axonity_conventions` are " +
+    "kept by hand and may be behind the platform — they are guidance, not the " +
+    "contract. Until this deploy serves it, the authority is the platform's own " +
+    "answer: the refusal on save, `validate_workflow`, and the readiness of " +
+    "`request_publish_*` / `get_publish_release`. Tell your human which " +
+    "environment this token points at if you need the contract.";
+/** What the tool answers: the live contract, the not-served notice, or the error. */
+export async function readEntityContract(client, kinds) {
+    const wanted = (kinds ?? []).map((k) => k.trim()).filter((k) => k !== "");
+    try {
+        return jsonResult(wanted.length === 0
+            ? await client.get(ENTITY_CONTRACT_ROUTE)
+            : await client.get(ENTITY_CONTRACT_ROUTE, { kinds: wanted.join(",") }));
+    }
+    catch (err) {
+        if (err instanceof AxonityApiError && (err.status === 404 || err.status === 405)) {
+            return {
+                content: [{ type: "text", text: ENTITY_CONTRACT_UNAVAILABLE }],
+            };
+        }
+        return errorResult(err);
+    }
+}
+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 " +
+        "`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` " +
+        "and the platform's own message (e.g. a connector without " +
+        "`implementation.effect`). Generated from the schemas and checks that " +
+        "enforce it. `rulesVersion` covers the whole catalogue: while it is " +
+        "unchanged there is nothing to re-read. " +
+        "\n\nREAD IT BEFORE YOU CREATE an entity whose rules you have not checked " +
+        "this session. Where it disagrees with `axonity_conventions` or a tool " +
+        "description, it is right and they are behind. The workflow document's " +
+        "own vocabulary is in `get_workflow_authoring_spec`. " +
+        "\n\nThe whole catalogue is large; pass `kinds` for the ones you need. " +
+        "`kinds` in the answer lists every kind this deploy serves. On a backend " +
+        "that does not serve the route yet, the tool SAYS SO instead of " +
+        "returning a copy.", {
+        kinds: z
+            .array(z.string())
+            .optional()
+            .describe('Kinds to return, e.g. ["tool", "agent"]. Omit for every kind. An ' +
+            "unknown kind is refused by the platform with the list of known ones."),
+    }, async ({ kinds }) => readEntityContract(client, kinds));
+}
+//# sourceMappingURL=entityContract.js.map

package/dist/tools/entityContract.js.map

@@ -0,0 +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"}

package/dist/tools/extras.js

@@ -42,10 +42,47 @@ const CONNECTOR_SHAPE = "\n\nSHAPE OF `implementation` — `headers` and `queryP
     'string>" }`. Use `{{name}}` in a value to fill it from the tool\'s input. ' +
     "Any other shape cannot run: the connector saves and then fails when " +
     "called, with an error that does not point here.";
+/**
+ * Two rules the platform enforces on a connector that the shape above does not
+ * say (axonity-mcp#95).
+ *
+ * `implementation.effect` (axonity-flow#1997): a draft saves without it, and
+ * the publish approval then refuses it ("Cannot publish connector: Set the
+ * connector's side effects …", `version_service.publish_tool`). An agent that
+ * builds a connector from this description used to make one that failed at the
+ * human's approval, not at its own save.
+ *
+ * `responseMapping.type: "file"` (axonity-flow#2079): the answer is kept as a
+ * file of the run, not parsed. Without this sentence the only mappings an agent
+ * knew were the parsing ones.
+ *
+ * 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.
+ */
+const CONNECTOR_EFFECT_AND_FILE = "\n\nDECLARE WHAT IT DOES — `implementation.effect`: `\"reads\"` (fetches, " +
+    "looks something up) or `\"acts\"` (sends, writes, starts something). A " +
+    "draft saves without it, but a connector WITHOUT `effect` CANNOT BE " +
+    "PUBLISHED: the approval is refused with \"Set the connector's side " +
+    "effects … before publishing\". Set it when you create the connector." +
+    "\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` 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. " +
+    "`execute_stored_connector`) nothing is stored and you see only the name " +
+    "and size. The other mappings (`jmespath` with an `expression`, or `full`) " +
+    "parse the answer as data." +
+    "\n\nThe platform's own create contract, when this deploy serves it, is " +
+    "`get_entity_authoring_contract` — it wins over this description.";
 export function registerConnectorTools(server, client) {
     server.tool("create_connector", "Create a connector draft (a tool of type 'connector'). Do NOT put real " +
         "credentials in authConfig — use placeholders; a human fills secrets in Axonity." +
-        CONNECTOR_SHAPE, {
+        CONNECTOR_SHAPE +
+        CONNECTOR_EFFECT_AND_FILE, {
         fields: z
             .record(z.unknown())
             .describe("Connector fields (name, description, implementation, authConfig)."),
@@ -55,7 +92,8 @@ export function registerConnectorTools(server, client) {
     }));
     server.tool("update_connector", "Update a connector draft (a tool of type 'connector'). Read it first for its " +
         "version; keep authConfig as placeholders only." +
-        CONNECTOR_SHAPE, {
+        CONNECTOR_SHAPE +
+        CONNECTOR_EFFECT_AND_FILE, {
         id: z.string().describe("The connector (tool) id."),
         expectedVersion: z.number().int().describe("Version last read — 409 if stale."),
         fields: z.record(z.unknown()).describe("Fields to change (camelCase)."),