@wowok/agent-mcp 3.4.0 → 3.4.1

package/dist/schemas/onchain_operations_machine.schema.json

@@ -197,39 +197,47 @@
                   "minLength": 1
                 },
                 "operators": {
-                  "type": "object",
-                  "properties": {
-                    "entities": {
-                      "minItems": 1,
-                      "type": "array",
-                      "items": {
-                        "type": "object",
-                        "properties": {
-                          "name_or_address": {
-                            "type": "string",
-                            "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
-                          },
-                          "local_mark_first": {
-                            "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-                            "type": "boolean"
+                  "anyOf": [
+                    {
+                      "description": "Array of account names, addresses, or mark names. Local marks are searched first for each entry. EXAMPLE: ['alice', '0x2...', 'bob']"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "entities": {
+                          "minItems": 1,
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "name_or_address": {
+                                "type": "string",
+                                "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                              },
+                              "local_mark_first": {
+                                "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                                "type": "boolean"
+                              }
+                            },
+                            "additionalProperties": false,
+                            "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
                           }
                         },
-                        "additionalProperties": false,
-                        "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
-                      }
-                    },
-                    "check_all_founded": {
-                      "default": true,
-                      "description": "Whether to check all entities are found. Defaults to true: abort and throw if ANY entity cannot be resolved. Set false only when partial resolution is explicitly intended (only found IDs are returned)",
-                      "type": "boolean"
+                        "check_all_founded": {
+                          "default": true,
+                          "description": "Whether to check all entities are found. Defaults to true: abort and throw if ANY entity cannot be resolved. Set false only when partial resolution is explicitly intended (only found IDs are returned)",
+                          "type": "boolean"
+                        }
+                      },
+                      "required": [
+                        "entities",
+                        "check_all_founded"
+                      ],
+                      "additionalProperties": false,
+                      "description": "Used to batch find account or object IDs by name"
                     }
-                  },
-                  "required": [
-                    "entities",
-                    "check_all_founded"
                   ],
-                  "additionalProperties": false,
-                  "description": "Used to batch find account or object IDs by name"
+                  "description": "Batch account or address lookup. Can be an array of strings (recommended for AI) or full object with explicit control. Array form auto-converts to { entities: [...], check_all_founded: true }. Empty arrays and {} elements are REJECTED (no-op transaction guard)."
                 }
               },
               "required": [
@@ -524,10 +532,10 @@
                         "additionalProperties": false,
                         "description": "Node in Machine object"
                       },
-                      "description": "List of nodes to add or set."
+                      "description": "List of nodes to add (or replace in place when bReplace=true)."
                     },
                     "bReplace": {
-                      "description": "Whether to replace existing nodes. If true, existing nodes will be replaced; if false, nodes will be added by merging.",
+                      "description": "Whether to replace existing nodes. If true, existing nodes will be replaced; if false, nodes will be added by merging. This is the ONLY supported way to rewrite nodes on an EXISTING Machine.",
                       "type": "boolean"
                     }
                   },
@@ -715,7 +723,7 @@
                         "additionalProperties": false,
                         "description": "Node in Machine object"
                       },
-                      "description": "List of nodes to add or set."
+                      "description": "List of nodes for a freshly CREATED Machine. xk9 F-02: REFUSED on an existing Machine — op set implies a clear-and-rewrite of the on-chain node table that permanently corrupts it (E_EMPTY_MACHINE on every later publish, no repair). To rewrite an existing Machine use op:add with bReplace:true."
                     },
                     "bReplace": {
                       "description": "Whether to replace existing nodes. If true, existing nodes will be replaced; if false, nodes will be added by merging.",
@@ -727,7 +735,7 @@
                     "nodes"
                   ],
                   "additionalProperties": false,
-                  "description": "Set nodes."
+                  "description": "Set nodes (CREATE-ONLY — refused on an existing Machine; use add+bReplace there)."
                 },
                 {
                   "type": "object",
@@ -1231,6 +1239,13 @@
       "additionalProperties": false,
       "description": "On-chain Machine operations. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, permission, ...} to create a Machine. NOTE: 'name' goes INSIDE 'object', NOT at the data root level. 'permission' can be a new Permission object or reference an existing one - check 'object' field description for details. (2) OPERATE EXISTING: Set 'object' field with STRING format (object ID or name). The 'object' field is CRITICAL and REQUIRED in both cases. STRING for existing, OBJECT for new creation."
     },
+    "idempotency_key": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9._:-]+$",
+      "description": "F-RQ-13A (prescription ⑨): idempotency key for this business attempt. REPLAY GUARD: if a previous call with the SAME key is still open (dispatched but outcome unresolved, or already committed), this call is HELD — you get a structured state_conflict envelope with the prior attempt's verification data instead of a second on-chain submission (the ghost-order guard: two live mainnet orders, two escrows). Lifecycle: a deterministic failure (nothing submitted / provably reverted) clears the key — fix the cause and retry with the SAME key; an unknown-outcome failure (submission may have landed) keeps the key HELD — verify on-chain state first (result.submission_verification tells you where to look), and only retry with a NEW key once the outcome is resolved. Keep one key per business attempt (e.g. 'ord-20261030-042-buy'); do not reuse across attempts."
+    },
     "env": {
       "type": "object",
       "properties": {
@@ -1369,7 +1384,7 @@
                       "type": "integer",
                       "minimum": 0,
                       "maximum": 255,
-                      "description": "Identifier (0-255) for data lookup in Guard table. Slot consensus (enforced on-chain at guard table construction): 0-220 = user slots (free for business guards); 221-253 = PROTOCOL-RESERVED (rejected on-chain — reserved so future protocol features get fixed slots without colliding with published guards); 255 = ONCE replay-protection slot on Allocation (byte-keyed, the submitted bytes are the once-key — use for per-period keys like period-<N>); 254 = ONCE-FOR-OBJECT slot on Allocation (chain-derived key = bcs(the Allocation's payment_info.for_object); the submitted bytes are ignored and the submission only arms the slot — use for one-shot per-order rails such as full refunds). SLOT 0 SEMANTICS: slot 0 carries the transacted Order address by convention. As a submission slot it is legal on order/allocation/machine rails (the order exists when those verify), but FORBIDDEN on a Service buy_guard — the order does not exist when the buy-time passport is verified, so the mount is refused (service abort 43)."
+                      "description": "Identifier (0-255) for data lookup in Guard table. Slot consensus (enforced on-chain at guard table construction): 0-220 = user slots (free for business guards); 221-253 = PROTOCOL-RESERVED (rejected on-chain — reserved so future protocol features get fixed slots without colliding with published guards); 255 = ONCE replay-protection slot on Allocation (byte-keyed, the submitted bytes are the once-key — use for per-period keys like period-<N>); 254 = ONCE-FOR-OBJECT slot on Allocation (chain-derived key = bcs(the Allocation's payment_info.for_object); the submitted bytes are ignored and the submission only arms the slot — use for one-shot per-order rails whose payee is NOT the order itself, such as settlement releases and incentive/bounty claims). NEVER arm 254 on a refund rail: a refund pays the submitted Order through user slot 0, and a refund leg re-entered in a later renewal period would abort E_ONCE_TRIGGERED (16) forever — refund once-ness comes from the terminal-node topology, never from a once slot. SLOT 0 SEMANTICS: slot 0 carries the transacted Order address by convention. As a submission slot it is legal on order/allocation/machine rails (the order exists when those verify), but FORBIDDEN on a Service buy_guard — the order does not exist when the buy-time passport is verified, so the mount is refused (service abort 43)."
                     },
                     "b_submission": {
                       "type": "boolean",

package/dist/schemas/onchain_operations_order.schema.json

@@ -18,38 +18,46 @@
         },
         "agent": {
           "description": "Order agent. Agents can operate the order, such as canceling the order, modifying the order status, etc.; but cannot receive the funds received by the order.",
-          "type": "object",
-          "properties": {
-            "entities": {
-              "minItems": 1,
-              "type": "array",
-              "items": {
-                "type": "object",
-                "properties": {
-                  "name_or_address": {
-                    "type": "string",
-                    "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
-                  },
-                  "local_mark_first": {
-                    "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-                    "type": "boolean"
+          "anyOf": [
+            {
+              "description": "Array of account names, addresses, or mark names. Local marks are searched first for each entry. EXAMPLE: ['alice', '0x2...', 'bob']"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "entities": {
+                  "minItems": 1,
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "name_or_address": {
+                        "type": "string",
+                        "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                      },
+                      "local_mark_first": {
+                        "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                        "type": "boolean"
+                      }
+                    },
+                    "additionalProperties": false,
+                    "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
                   }
                 },
-                "additionalProperties": false,
-                "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
-              }
-            },
-            "check_all_founded": {
-              "default": true,
-              "description": "Whether to check all entities are found. Defaults to true: abort and throw if ANY entity cannot be resolved. Set false only when partial resolution is explicitly intended (only found IDs are returned)",
-              "type": "boolean"
+                "check_all_founded": {
+                  "default": true,
+                  "description": "Whether to check all entities are found. Defaults to true: abort and throw if ANY entity cannot be resolved. Set false only when partial resolution is explicitly intended (only found IDs are returned)",
+                  "type": "boolean"
+                }
+              },
+              "required": [
+                "entities",
+                "check_all_founded"
+              ],
+              "additionalProperties": false,
+              "description": "Used to batch find account or object IDs by name"
             }
-          },
-          "required": [
-            "entities",
-            "check_all_founded"
-          ],
-          "additionalProperties": false
+          ]
         },
         "required_info": {
           "description": "Credential recorded on the order: the merchant's IM user address resolved from the Service's Contact (zero cost) or a WTS Proof object id (on-chain delivery proof embedding that IM address and timestamp; costs gas). The information itself is delivered via Wowok Messenger. ACCEPTED FORMS (upwc-cat-261017 T10 live probe): a Contact/Proof object ID (0x…), an account ADDRESS, or a REGISTERED mark name — a bare account display name is not an object reference and fails with 'not found'. WRITE PERMISSION: OWNER-ONLY — only the order owner (the buyer) can set or clear this field; any other signer (including the merchant/service owner) aborts on-chain (MoveAbort 1, 'Not the owner'). The merchant's role is to READ it and to receive the info over Messenger. ATTESTATION SEMANTICS: the recorded VALUE is self-attested and has no on-chain readback — never trust the value itself as a gate condition. A PRESENCE gate IS legitimate on-chain (query order.required_info is some — see pattern.required_info_evidence_gate): it proves the buyer recorded a credential before handover, without asserting what the credential says.",
@@ -318,18 +326,26 @@
         },
         "transfer_to": {
           "description": "Set new owner of the order. Requires order owner permission to set.",
-          "type": "object",
-          "properties": {
-            "name_or_address": {
-              "type": "string",
-              "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+          "anyOf": [
+            {
+              "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x2...' (64 hex chars) - uses address directly; EXAMPLE: '' - uses the default local account"
             },
-            "local_mark_first": {
-              "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-              "type": "boolean"
+            {
+              "type": "object",
+              "properties": {
+                "name_or_address": {
+                  "type": "string",
+                  "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                },
+                "local_mark_first": {
+                  "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false,
+              "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
             }
-          },
-          "additionalProperties": false
+          ]
         },
         "order_renew": {
           "description": "Renewal in ONE transaction: pays into the order's allocation and advances the renew forward (fund + record + advance in a single step). Replaces the legacy 3-transaction renewal split. The new Payment's sole recipient is the allocation object itself (enforced on-chain). PRE-STATE CONSTRAINT (esound-mn-261021 B-1): guards on the advanced forward read the COMMITTED pre-transaction balance — this same-PTB payment is INVISIBLE to them; NEVER bind an allocation.balance gate to the forward this call advances (it always aborts; identity/signer guards are fine). If the forward DOES carry a balance gate, do NOT call this tool — execute the TWO-TX RENEW RECIPE (esound2-mn-261022 R2-1): a balance/fund-gated renew or capture forward is satisfiable only when the capture funds were committed in a PRIOR transaction — split the coupled one-PTB call into TWO transactions: TX1 commits the period/capture funds into the order's Allocation (create the escrowed payment record, then have the allocation receive it; a hand-built PTB until the allocation top-up primitive ships on the package face), WAIT for its success, then TX2 advances the forward with the plain order-holder progress call — the gate now reads the committed balance and passes. The ONE-PTB data.order_renew stays the route for GATE-LESS renew forwards only. NEVER retry the same-PTB shape after the abort: the guard verdict is structural (guards read the pre-transaction snapshot, esound-mn-261021 B-1), not a transient balance shortfall. Structural alternatives that avoid the second transaction: prepaid-full at buy (staged-RELEASE semantics) or per-period NEW Orders.",
@@ -470,6 +486,13 @@
       "additionalProperties": false,
       "description": "On-chain, operate on an Order object."
     },
+    "idempotency_key": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9._:-]+$",
+      "description": "F-RQ-13A (prescription ⑨): idempotency key for this business attempt. REPLAY GUARD: if a previous call with the SAME key is still open (dispatched but outcome unresolved, or already committed), this call is HELD — you get a structured state_conflict envelope with the prior attempt's verification data instead of a second on-chain submission (the ghost-order guard: two live mainnet orders, two escrows). Lifecycle: a deterministic failure (nothing submitted / provably reverted) clears the key — fix the cause and retry with the SAME key; an unknown-outcome failure (submission may have landed) keeps the key HELD — verify on-chain state first (result.submission_verification tells you where to look), and only retry with a NEW key once the outcome is resolved. Keep one key per business attempt (e.g. 'ord-20261030-042-buy'); do not reuse across attempts."
+    },
     "env": {
       "type": "object",
       "properties": {
@@ -608,7 +631,7 @@
                       "type": "integer",
                       "minimum": 0,
                       "maximum": 255,
-                      "description": "Identifier (0-255) for data lookup in Guard table. Slot consensus (enforced on-chain at guard table construction): 0-220 = user slots (free for business guards); 221-253 = PROTOCOL-RESERVED (rejected on-chain — reserved so future protocol features get fixed slots without colliding with published guards); 255 = ONCE replay-protection slot on Allocation (byte-keyed, the submitted bytes are the once-key — use for per-period keys like period-<N>); 254 = ONCE-FOR-OBJECT slot on Allocation (chain-derived key = bcs(the Allocation's payment_info.for_object); the submitted bytes are ignored and the submission only arms the slot — use for one-shot per-order rails such as full refunds). SLOT 0 SEMANTICS: slot 0 carries the transacted Order address by convention. As a submission slot it is legal on order/allocation/machine rails (the order exists when those verify), but FORBIDDEN on a Service buy_guard — the order does not exist when the buy-time passport is verified, so the mount is refused (service abort 43)."
+                      "description": "Identifier (0-255) for data lookup in Guard table. Slot consensus (enforced on-chain at guard table construction): 0-220 = user slots (free for business guards); 221-253 = PROTOCOL-RESERVED (rejected on-chain — reserved so future protocol features get fixed slots without colliding with published guards); 255 = ONCE replay-protection slot on Allocation (byte-keyed, the submitted bytes are the once-key — use for per-period keys like period-<N>); 254 = ONCE-FOR-OBJECT slot on Allocation (chain-derived key = bcs(the Allocation's payment_info.for_object); the submitted bytes are ignored and the submission only arms the slot — use for one-shot per-order rails whose payee is NOT the order itself, such as settlement releases and incentive/bounty claims). NEVER arm 254 on a refund rail: a refund pays the submitted Order through user slot 0, and a refund leg re-entered in a later renewal period would abort E_ONCE_TRIGGERED (16) forever — refund once-ness comes from the terminal-node topology, never from a once slot. SLOT 0 SEMANTICS: slot 0 carries the transacted Order address by convention. As a submission slot it is legal on order/allocation/machine rails (the order exists when those verify), but FORBIDDEN on a Service buy_guard — the order does not exist when the buy-time passport is verified, so the mount is refused (service abort 43)."
                     },
                     "b_submission": {
                       "type": "boolean",

package/dist/schemas/onchain_operations_payment.schema.json

@@ -54,19 +54,27 @@
                 "type": "object",
                 "properties": {
                   "recipient": {
-                    "type": "object",
-                    "properties": {
-                      "name_or_address": {
-                        "type": "string",
-                        "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                    "anyOf": [
+                      {
+                        "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x2...' (64 hex chars) - uses address directly; EXAMPLE: '' - uses the default local account"
                       },
-                      "local_mark_first": {
-                        "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-                        "type": "boolean"
+                      {
+                        "type": "object",
+                        "properties": {
+                          "name_or_address": {
+                            "type": "string",
+                            "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                          },
+                          "local_mark_first": {
+                            "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                            "type": "boolean"
+                          }
+                        },
+                        "additionalProperties": false,
+                        "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
                       }
-                    },
-                    "additionalProperties": false,
-                    "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
+                    ],
+                    "description": "Account or address lookup. Can be a simple string (recommended for AI) or full object with explicit local_mark_first control. String form auto-converts to { name_or_address: <string>, local_mark_first: true }."
                   },
                   "amount": {
                     "anyOf": [
@@ -200,6 +208,13 @@
       ],
       "description": "On-chain Payment operations. TWO modes:\n(1) CREATE: Set 'object' with {name, type_parameter, ...}, 'revenue', and 'info' to create a new Payment.\n(2) RECEIVE: Set {receive: true} to unwrap CoinWrappers to your wallet. Provide 'object' (<coinwrapper_id_or_name>) to unwrap a specific one, or OMIT it to auto-unwrap every CoinWrapper owned by the caller. type_parameter optional — auto-derived from the CoinWrapper's type."
     },
+    "idempotency_key": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9._:-]+$",
+      "description": "F-RQ-13A (prescription ⑨): idempotency key for this business attempt. REPLAY GUARD: if a previous call with the SAME key is still open (dispatched but outcome unresolved, or already committed), this call is HELD — you get a structured state_conflict envelope with the prior attempt's verification data instead of a second on-chain submission (the ghost-order guard: two live mainnet orders, two escrows). Lifecycle: a deterministic failure (nothing submitted / provably reverted) clears the key — fix the cause and retry with the SAME key; an unknown-outcome failure (submission may have landed) keeps the key HELD — verify on-chain state first (result.submission_verification tells you where to look), and only retry with a NEW key once the outcome is resolved. Keep one key per business attempt (e.g. 'ord-20261030-042-buy'); do not reuse across attempts."
+    },
     "env": {
       "type": "object",
       "properties": {