@wowok/agent-mcp 2.3.12 → 2.3.14

package/dist/schemas/onchain_operations.output.json

@@ -16,7 +16,7 @@
                 "type": {
                   "type": "string",
                   "const": "submission",
-                  "description": "Type of call response: submission"
+                  "description": "Discriminator for this result variant. Constraint: always 'submission'. Example: 'submission'"
                 },
                 "guard": {
                   "type": "array",
@@ -25,11 +25,11 @@
                     "properties": {
                       "object": {
                         "type": "string",
-                        "description": "Guard object name or ID."
+                        "description": "Guard object name or ID to verify against. Example: 'my-delivery-guard' or '0x123...'"
                       },
                       "impack": {
                         "type": "boolean",
-                        "description": "Whether the verification result of this Guard participates in the final verification logic. If true, the verification result of this Guard will be included in the final verification result; if false, the verification result of this Guard will not be included."
+                        "description": "Whether this Guard's verification result participates in the final logic. Constraint: if false, the Guard is checked but does not block the operation. Example: true"
                       }
                     },
                     "required": [
@@ -37,7 +37,8 @@
                       "impack"
                     ],
                     "additionalProperties": false
-                  }
+                  },
+                  "description": "Array of Guard objects to verify. Relation: each entry corresponds to a Guard bound to the operation."
                 },
                 "submission": {
                   "type": "array",
@@ -46,7 +47,7 @@
                     "properties": {
                       "guard": {
                         "$ref": "#/definitions/onchain_operations/properties/result/anyOf/0/properties/guard/items/properties/object",
-                        "description": "Guard object name or ID."
+                        "description": "Guard object name or ID that requires submission data. Example: 'my-delivery-guard'"
                       },
                       "submission": {
                         "type": "array",
@@ -498,7 +499,7 @@
                           "additionalProperties": false,
                           "description": "Guard table item"
                         },
-                        "description": "User-submitted data required for Guard verification."
+                        "description": "User-submitted data matching the Guard's required fields. Relation: structure must match the Guard table's column definitions. Example: [{field:'delivery_proof', value:'Qm...'}]"
                       }
                     },
                     "required": [
@@ -506,8 +507,9 @@
                       "submission"
                     ],
                     "additionalProperties": false,
-                    "description": "Permission guard submission data."
-                  }
+                    "description": "One Guard's submission data: the Guard to verify plus the user-provided data that satisfies its requirements."
+                  },
+                  "description": "User-submitted data for each Guard. Relation: one entry per Guard in the guard array; fill submission fields and resubmit via call_with_submission."
                 }
               },
               "required": [
@@ -516,7 +518,7 @@
                 "submission"
               ],
               "additionalProperties": false,
-              "description": "Guard verification submission data required to complete an operation. Contains: (1) 'guard' - array of Guard objects to verify, each with an object ID and an 'impack' flag indicating if its result affects the final outcome; (2) 'submission' - array of user data submissions matching the Guard's requirements. The operation proceeds only after all Guards with impack=true are successfully verified."
+              "description": "Guard verification required. The operation was blocked because one or more Guards require user-submitted data. Fill the submission array and resubmit. Semantic status is 'pending_input'."
             },
             {
               "type": "object",
@@ -1590,7 +1592,8 @@
                 },
                 "type": {
                   "type": "string",
-                  "const": "transaction"
+                  "const": "transaction",
+                  "description": "Discriminator for this result variant. Constraint: always 'transaction'. Example: 'transaction'"
                 }
               },
               "required": [
@@ -1606,10 +1609,38 @@
                 "type": {
                   "type": "string",
                   "const": "error",
-                  "description": "Type of call response: error"
+                  "description": "Discriminator for this result variant. Constraint: always 'error'. Example: 'error'"
                 },
                 "error": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "Human-readable error message from the chain or SDK. Relation: enriched via enrichMoveError before classification. Example: 'Insufficient balance for gas'"
+                },
+                "error_code": {
+                  "type": "string",
+                  "enum": [
+                    "invalid_parameter",
+                    "guard_rejected",
+                    "state_conflict",
+                    "insufficient_balance",
+                    "object_not_found",
+                    "permission_denied",
+                    "immutable_violation",
+                    "network_error",
+                    "unknown"
+                  ],
+                  "description": "Error classification for programmatic recovery. Constraint: enum of 9 values. Relation: drives Recover Loop strategy selection. Example: 'insufficient_balance'"
+                },
+                "retryable": {
+                  "type": "boolean",
+                  "description": "Whether the same call can be retried as-is. Constraint: true only for network_error and insufficient_balance. Example: true"
+                },
+                "recovery_hint": {
+                  "type": "string",
+                  "description": "Recovery suggestion for AI or user. Relation: paired with error_code to guide Recover Loop. Example: 'Claim faucet tokens then retry'"
+                },
+                "related_object": {
+                  "type": "string",
+                  "description": "Object ID related to the error, if any. Example: '0x123...'"
                 }
               },
               "required": [
@@ -1617,14 +1648,15 @@
                 "error"
               ],
               "additionalProperties": false,
-              "description": "Call error data. Contains error information."
+              "description": "Error result. Contains the raw error message plus structured classification (error_code/retryable/recovery_hint) so AI can choose a recovery strategy without parsing the error string."
             },
             {
               "type": "object",
               "properties": {
                 "type": {
                   "type": "string",
-                  "const": "data"
+                  "const": "data",
+                  "description": "Discriminator for this result variant. Constraint: always 'data'. Example: 'data'"
                 },
                 "data": {
                   "type": "array",
@@ -1717,7 +1749,8 @@
                           {
                             "type": "string"
                           }
-                        ]
+                        ],
+                        "description": "What happened to this object in the operation. Constraint: 'created' | 'mutated' | custom string. Example: 'created'"
                       }
                     },
                     "required": [
@@ -1725,8 +1758,9 @@
                       "change"
                     ],
                     "additionalProperties": true,
-                    "description": "Call result data. Contains basic object information and change type."
-                  }
+                    "description": "One object record in a query result. Contains the object's basic info plus how it changed in this operation."
+                  },
+                  "description": "Array of object records returned by a query operation. Example: [{id:'0x...', change:'created'}]"
                 }
               },
               "required": [
@@ -1740,7 +1774,8 @@
               "properties": {
                 "type": {
                   "type": "string",
-                  "const": "null"
+                  "const": "null",
+                  "description": "Discriminator for this result variant. Constraint: always 'null'. Example: 'null'"
                 }
               },
               "required": [
@@ -1749,18 +1784,426 @@
               "additionalProperties": false
             }
           ],
-          "description": "Call result. Can be Guard verification information (type: 'submission') that needs to be submitted by the user, result response, error information (type: 'error'), or null."
+          "description": "Discriminated result. Check result.type first: 'transaction'|'submission'|'error'|'data'|'null'. Each variant has different fields."
         },
         "message": {
           "type": "string",
-          "description": "Message or hint information"
+          "description": "Human-readable summary or hint. Constraint: always present for error/transaction results; may be omitted for data/null. Example: 'Transaction completed successfully'"
+        },
+        "semantic": {
+          "type": "object",
+          "properties": {
+            "intent": {
+              "type": "string",
+              "description": "Inferred user intent / operation goal. Constraint: snake_case string. Relation: derived from operation_type + data signals. Example: 'publish_service'"
+            },
+            "status": {
+              "type": "string",
+              "enum": [
+                "success",
+                "partial",
+                "failed",
+                "pending_input"
+              ],
+              "description": "Business-level status (not raw tx status). 'pending_input' = needs Guard submission. Example: 'success'"
+            },
+            "summary": {
+              "type": "string",
+              "description": "One-sentence human-readable summary of what happened. AI should read this first. Example: 'Successfully published Service my-shop with Machine bound'"
+            },
+            "created": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "Object ID (64-hex with 0x prefix). Identifies the on-chain object. Example: '0xa1d4...'"
+                  },
+                  "name": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "description": "Local mark name if assigned, else null. Relation: resolved via local_mark_operation. Example: 'my-shop' or null"
+                  },
+                  "role": {
+                    "type": "string",
+                    "enum": [
+                      "Permission",
+                      "Guard",
+                      "Machine",
+                      "Progress",
+                      "Service",
+                      "Order",
+                      "Allocation",
+                      "Arbitration",
+                      "ArbCase",
+                      "Messenger",
+                      "Contact",
+                      "Demand",
+                      "Reward",
+                      "Personal",
+                      "Repository",
+                      "Treasury",
+                      "Discount",
+                      "Other"
+                    ],
+                    "description": "Business role of the object in the dependency graph. Constraint: enum of 18 values. Relation: derived from objectType last segment; drives Plan/Verify Loop positioning. Example: 'Service'"
+                  },
+                  "relation": {
+                    "type": "object",
+                    "properties": {
+                      "parent": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "description": "Parent object ID, if this object belongs to another (e.g. Machine belongs to Service). Example: '0x123...' or null"
+                      },
+                      "relation_type": {
+                        "type": "string",
+                        "enum": [
+                          "machine_of",
+                          "guard_of",
+                          "allocator_of",
+                          "permission_of",
+                          "progress_of",
+                          "allocation_of",
+                          "arb_of",
+                          "other"
+                        ],
+                        "description": "How this object relates to its parent. Example: 'machine_of'"
+                      }
+                    },
+                    "additionalProperties": false,
+                    "description": "Relationship to another object in the dependency graph"
+                  },
+                  "immutable": {
+                    "type": "boolean",
+                    "description": "Whether the object has entered an immutable state (e.g. Service published). Constraint: true after publish. Example: true"
+                  }
+                },
+                "required": [
+                  "id",
+                  "role"
+                ],
+                "additionalProperties": false,
+                "description": "An object tagged with its business role and relationship within the object dependency graph"
+              },
+              "description": "Objects newly created in this operation, tagged with roles"
+            },
+            "modified": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/onchain_operations/properties/semantic/properties/created/items"
+              },
+              "description": "Objects mutated in this operation, tagged with roles"
+            },
+            "released": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "amount": {
+                    "type": "string",
+                    "description": "Amount change as stringified integer (smallest unit). Negative=spend, positive=receive. Example: '-10000000000'"
+                  },
+                  "coinType": {
+                    "type": "string",
+                    "description": "Coin type tag (format: {address}::{module}::{struct}). Example: '0x2::wow::WOW'"
+                  },
+                  "role": {
+                    "type": "string",
+                    "enum": [
+                      "payment",
+                      "refund",
+                      "change",
+                      "compensation",
+                      "reward",
+                      "gas",
+                      "deposit",
+                      "release",
+                      "other"
+                    ],
+                    "description": "Business role of this fund movement. Constraint: enum of 9 values. Relation: derived from operation context. Example: 'payment'"
+                  },
+                  "from": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "description": "Sender address if known. Example: '0xabc...' or null"
+                  },
+                  "to": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "description": "Recipient address if known. Example: '0xdef...' or null"
+                  }
+                },
+                "required": [
+                  "amount",
+                  "coinType",
+                  "role"
+                ],
+                "additionalProperties": false,
+                "description": "A fund movement tagged with its business role"
+              },
+              "description": "Fund movements in this operation, tagged with roles"
+            },
+            "events": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "event_type": {
+                    "type": "string",
+                    "description": "Raw on-chain event type tag. Example: '0x2::service::ServicePublishedEvent'"
+                  },
+                  "business_meaning": {
+                    "type": "string",
+                    "description": "Human-readable business meaning. Example: 'Service has been published and is now immutable'"
+                  },
+                  "category": {
+                    "type": "string",
+                    "enum": [
+                      "lifecycle",
+                      "state_change",
+                      "fund_flow",
+                      "permission",
+                      "guard",
+                      "other"
+                    ],
+                    "description": "Business category. Constraint: enum of 6 values. Example: 'lifecycle'"
+                  },
+                  "related_object": {
+                    "type": "string",
+                    "description": "Object ID the event relates to, if extractable. Example: '0x123...'"
+                  },
+                  "side_effect": {
+                    "type": "string",
+                    "description": "Side effect description for AI. Example: 'Customers can now place orders against this Service'"
+                  }
+                },
+                "required": [
+                  "event_type",
+                  "business_meaning",
+                  "category"
+                ],
+                "additionalProperties": false,
+                "description": "An on-chain event annotated with business semantics"
+              },
+              "description": "On-chain events annotated with business semantics (S-8)"
+            },
+            "next_actions": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "action": {
+                    "type": "string",
+                    "description": "Recommended next action. Example: 'add sales products'"
+                  },
+                  "reason": {
+                    "type": "string",
+                    "description": "Why this action is recommended. Example: 'Service has no products; customers cannot order'"
+                  },
+                  "tool": {
+                    "type": "string",
+                    "description": "MCP tool to use, if applicable. Example: 'onchain_operations'"
+                  },
+                  "prerequisite": {
+                    "type": "string",
+                    "description": "Condition that must hold before this action. Example: 'Service must be created first'"
+                  },
+                  "priority": {
+                    "type": "string",
+                    "enum": [
+                      "required",
+                      "recommended",
+                      "optional"
+                    ],
+                    "description": "Priority. Constraint: enum. Example: 'required'"
+                  }
+                },
+                "required": [
+                  "action",
+                  "reason",
+                  "priority"
+                ],
+                "additionalProperties": false,
+                "description": "A recommended next action with priority and rationale"
+              },
+              "description": "Recommended next actions to drive the workflow forward"
+            },
+            "warnings": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Business-level warnings. Example: 'order_allocators not configured; order funds cannot be distributed'"
+            }
+          },
+          "required": [
+            "intent",
+            "status",
+            "summary"
+          ],
+          "additionalProperties": false,
+          "description": "Business semantic summary. AI should read semantic first; fall back to parsing result only when semantic is absent. Relation: populated by MCP server from operation context; undefined when intent cannot be confidently inferred or for non-transaction tools. Example: {intent:'publish_service', status:'success', summary:'...'}"
+        },
+        "harness_report": {
+          "type": "object",
+          "properties": {
+            "verify": {
+              "type": "object",
+              "properties": {
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "pass",
+                    "warn",
+                    "fail"
+                  ],
+                  "description": "Overall verify status. Constraint: 'fail' if any mismatch has severity 'fail'; 'warn' if only warns; 'pass' if no mismatches. Example: 'fail'"
+                },
+                "mismatches": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "dimension": {
+                        "type": "string",
+                        "enum": [
+                          "created",
+                          "modified",
+                          "released",
+                          "state",
+                          "event"
+                        ],
+                        "description": "Verify dimension that mismatched. Example: 'created'"
+                      },
+                      "expected": {
+                        "type": "string",
+                        "description": "What the Expect Loop declared. Example: 'Service object created'"
+                      },
+                      "actual": {
+                        "type": "string",
+                        "description": "What actually happened. Example: 'No object created'"
+                      },
+                      "severity": {
+                        "type": "string",
+                        "enum": [
+                          "pass",
+                          "warn",
+                          "fail"
+                        ],
+                        "description": "Severity: 'fail' blocks progress, 'warn' is advisory, 'pass' never appears here. Example: 'fail'"
+                      },
+                      "detail": {
+                        "type": "string",
+                        "description": "Human-readable explanation of the mismatch. Example: 'Expected Service creation but transaction succeeded without object change'"
+                      }
+                    },
+                    "required": [
+                      "dimension",
+                      "expected",
+                      "actual",
+                      "severity",
+                      "detail"
+                    ],
+                    "additionalProperties": false,
+                    "description": "One mismatch between expected and actual result. AI should read severity first to decide whether to halt."
+                  },
+                  "description": "List of mismatches found. Empty array when status is 'pass'. Example: [{dimension:'created', expected:'...', actual:'...', severity:'fail', detail:'...'}]"
+                },
+                "summary": {
+                  "type": "string",
+                  "description": "Human-readable summary of the verify result. Example: '2 mismatches found: created dimension failed, event dimension warned'"
+                },
+                "timestamp": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp when verify ran. Example: '2026-07-14T10:30:00.000Z'"
+                }
+              },
+              "required": [
+                "status",
+                "mismatches",
+                "summary",
+                "timestamp"
+              ],
+              "additionalProperties": false,
+              "description": "Verify Loop report comparing expected vs actual."
+            },
+            "recovery": {
+              "type": "object",
+              "properties": {
+                "strategy": {
+                  "type": "string",
+                  "enum": [
+                    "retry",
+                    "claim_faucet",
+                    "fill_submission",
+                    "recreate",
+                    "switch_account",
+                    "query_and_retry",
+                    "adjust_params",
+                    "escalate_human",
+                    "stop"
+                  ],
+                  "description": "Recovery strategy chosen by the Recover Loop. Constraint: 9 strategies matching error_code table. Example: 'claim_faucet'"
+                },
+                "should_retry": {
+                  "type": "boolean",
+                  "description": "Whether AI should retry the original operation after applying the strategy. Constraint: false for 'stop' and 'escalate_human'. Example: true"
+                },
+                "adjusted_params": {
+                  "type": "object",
+                  "additionalProperties": {},
+                  "description": "Suggested parameter adjustments for 'adjust_params' strategy. Example: {amount: '100000000'}"
+                },
+                "user_prompt": {
+                  "type": "string",
+                  "description": "Prompt to show the user when recovery is semi-automatic or manual. Example: 'Please switch to an account with provider permission'"
+                },
+                "max_attempts": {
+                  "type": "integer",
+                  "description": "Maximum attempts for this error_code type. Example: 3"
+                },
+                "current_attempt": {
+                  "type": "integer",
+                  "description": "Current attempt count (1-indexed). Example: 1"
+                },
+                "detail": {
+                  "type": "string",
+                  "description": "Human-readable explanation of the recovery decision. Example: 'Insufficient balance detected; claim faucet tokens then retry'"
+                }
+              },
+              "required": [
+                "strategy",
+                "should_retry",
+                "max_attempts",
+                "current_attempt",
+                "detail"
+              ],
+              "additionalProperties": false,
+              "description": "Recover Loop action. Present only when verify.status is 'fail' or 'warn', or when an error occurred."
+            }
+          },
+          "required": [
+            "verify"
+          ],
+          "additionalProperties": false,
+          "description": "L4 Harness report (Verify + Recover). Present only when the Harness is injected and an Expected Result was declared for this operation. Relation: produced by handler.ts calling harness.verify() and harness.recover(). Example: {verify:{status:'fail', mismatches:[...]}, recovery:{strategy:'recreate'}}"
         }
       },
       "required": [
         "result"
       ],
       "additionalProperties": false,
-      "description": "On-chain Operation Result"
+      "description": "Unified MCP tool output. result.type discriminates 5 outcomes: 'transaction' (raw Sui response), 'submission' (needs Guard data), 'error' (failed with error_code), 'data' (query result), 'null' (no-op). When semantic is present, prefer it over raw result parsing. When harness_report is present, check verify.status first and follow recovery.strategy if status is 'fail'."
     }
   }
 }