@wowok/agent-mcp 3.3.9 → 3.4.1

package/dist/schemas/onchain_operations_reward.schema.json

@@ -95,7 +95,7 @@
           "description": "Two ways to specify an object: (1) STRING - Reference an EXISTING object by name or ID; (2) OBJECT - CREATE a NEW object with full configuration including name, tags, description, token type for payments, and Permission-based access control. The object format is used when you need both token specification AND permission management."
         },
         "claim": {
-          "description": "GUARD object name/address whose verification starts the reward distribution — this is the GUARD, NEVER the order (KLM-FIND-08, klook-mn 261019: passing the order here aborts). The ORDER reference rides submission slot 0 — pass it via the call's 'submission', not in this field.",
+          "description": "GUARD object name/address whose verification starts the reward distribution — this is the GUARD, NEVER the order (KLM-FIND-08, klook-mn 261019: passing the order here aborts). The ORDER reference rides submission slot 0 — pass it via the call's 'submission', not in this field. WINDOW LIFECYCLE (rqd3-tn-261030 F-02): the guard's pass condition must cover EVERY terminal state that may legitimately hold at claim time. A completed-only window (root = query order status == completed) is CLOSED FOREVER the moment the Machine settles — settlement overwrites the order status, the guard can never pass again, and the bounty is stranded (claim path aborts with E_GUARD_NOT_FOUND — the payout lookup finds no payable row, abort 7). Design the claim guard against the full terminal set (e.g. completed OR settled OR refunded, per the payout rail), and if a bound window is already closed, migration = new guard with the corrected root + reward.guard_remove + reward.guard_add (guards are immutable — there is no in-place edit).",
           "type": "string"
         },
         "description": {
@@ -243,7 +243,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)."
                       }
                     },
                     "required": [
@@ -256,26 +256,34 @@
                     "type": "object",
                     "properties": {
                       "Entity": {
-                        "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."
+                        ],
+                        "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 }."
                       }
                     },
                     "required": [
                       "Entity"
                     ],
                     "additionalProperties": false,
-                    "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
+                    "description": "Static address resolved via LocalMark. Format: {Entity: 'mark_name'} (string shorthand) or {Entity: {name_or_address: 'mark_name'}} (full object).F-RQ-11 (rq2 promotion): string shorthand accepted — the FIX-005 transform resolves local marks first."
                   },
                   {
                     "type": "object",
@@ -307,7 +315,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)."
                       }
                     },
                     "required": [
@@ -357,7 +365,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)."
                   },
                   {
                     "type": "null"
@@ -643,6 +651,13 @@
       "additionalProperties": false,
       "description": "On-chain Reward operations. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, type_parameter, permission, ...} to create a Reward. 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. NAME RESOLUTION SCOPE (T8 az3-mn-261013): a LocalMark name resolves ONLY within the SIGNING account's own local mark store — when the Reward was named by a DIFFERENT account (e.g. the merchant's mark) and you operate it from another account, the name lookup fails with 'not found locally'; pass the on-chain 0x object ID instead (resolve it once via workspace/onchain_objects and reuse the id)."
     },
+    "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": {
@@ -663,7 +678,7 @@
           "type": "boolean"
         },
         "network": {
-          "description": "Omit in client/chat contexts — the runtime stamps the user's CURRENT network (the client's UI selection). Standalone MCP/CLI: omit to use the current network; set ONLY when the user explicitly names a different network (a mismatch pauses for user confirmation). Never guess or hardcode a network.",
+          "description": "Omit in chat-client contexts — the runtime stamps the user's CURRENT network (the client's UI selection). Standalone MCP/CLI: omit to use the current network; set ONLY when the user explicitly names a different network (a mismatch pauses for user confirmation). Never guess or hardcode a network.",
           "type": "string",
           "enum": [
             "localnet",
@@ -781,7 +796,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",
@@ -1098,7 +1113,7 @@
                                 }
                               },
                               "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."
+                              "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."
                             },
                             {
                               "type": "string"
@@ -1123,6 +1138,7 @@
                               "type": "object",
                               "properties": {
                                 "entities": {
+                                  "minItems": 1,
                                   "type": "array",
                                   "items": {
                                     "type": "object",
@@ -1137,7 +1153,7 @@
                                       }
                                     },
                                     "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."
+                                    "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": {