@wowok/agent-mcp 2.3.13 → 2.3.14

package/dist/schema/call/base.js

@@ -75,24 +75,74 @@ export const ObjectsOpSchema = z.union([
     }).describe("Remove all objects."),
 ]).describe("Operate object list. Used to set, add, or remove objects.");
 export const ResponseDataSchema = ObjectBaseSchema.extend({
-    change: z.union([z.literal("created"), z.literal("mutated"), z.string()]),
-}).describe("Call result data. Contains basic object information and change type.");
+    change: z.union([z.literal("created"), z.literal("mutated"), z.string()]).describe("What happened to this object in the operation. Constraint: 'created' | 'mutated' | custom string. Example: 'created'"),
+}).describe("One object record in a query result. Contains the object's basic info plus how it changed in this operation.");
+export const ObjectRoleSchema = z.object({
+    id: z.string().describe("Object ID (64-hex with 0x prefix). Identifies the on-chain object. Example: '0xa1d4...'"),
+    name: z.union([z.string(), z.null()]).optional().describe("Local mark name if assigned, else null. Relation: resolved via local_mark_operation. Example: 'my-shop' or null"),
+    role: z.enum([
+        "Permission", "Guard", "Machine", "Progress", "Service", "Order", "Allocation",
+        "Arbitration", "ArbCase", "Messenger", "Contact", "Demand", "Reward", "Personal",
+        "Repository", "Treasury", "Discount", "Other"
+    ]).describe("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: z.object({
+        parent: z.union([z.string(), z.null()]).optional().describe("Parent object ID, if this object belongs to another (e.g. Machine belongs to Service). Example: '0x123...' or null"),
+        relation_type: z.enum(["machine_of", "guard_of", "allocator_of", "permission_of", "progress_of", "allocation_of", "arb_of", "other"]).optional().describe("How this object relates to its parent. Example: 'machine_of'"),
+    }).optional().describe("Relationship to another object in the dependency graph"),
+    immutable: z.boolean().optional().describe("Whether the object has entered an immutable state (e.g. Service published). Constraint: true after publish. Example: true"),
+}).strict().describe("An object tagged with its business role and relationship within the object dependency graph");
+export const FundRoleSchema = z.object({
+    amount: z.string().describe("Amount change as stringified integer (smallest unit). Negative=spend, positive=receive. Example: '-10000000000'"),
+    coinType: z.string().describe("Coin type tag (format: {address}::{module}::{struct}). Example: '0x2::wow::WOW'"),
+    role: z.enum(["payment", "refund", "change", "compensation", "reward", "gas", "deposit", "release", "other"]).describe("Business role of this fund movement. Constraint: enum of 9 values. Relation: derived from operation context. Example: 'payment'"),
+    from: z.string().nullable().optional().describe("Sender address if known. Example: '0xabc...' or null"),
+    to: z.string().nullable().optional().describe("Recipient address if known. Example: '0xdef...' or null"),
+}).strict().describe("A fund movement tagged with its business role");
+export const NextActionSchema = z.object({
+    action: z.string().describe("Recommended next action. Example: 'add sales products'"),
+    reason: z.string().describe("Why this action is recommended. Example: 'Service has no products; customers cannot order'"),
+    tool: z.string().optional().describe("MCP tool to use, if applicable. Example: 'onchain_operations'"),
+    prerequisite: z.string().optional().describe("Condition that must hold before this action. Example: 'Service must be created first'"),
+    priority: z.enum(["required", "recommended", "optional"]).describe("Priority. Constraint: enum. Example: 'required'"),
+}).strict().describe("A recommended next action with priority and rationale");
+export const EventSemanticSchema = z.object({
+    event_type: z.string().describe("Raw on-chain event type tag. Example: '0x2::service::ServicePublishedEvent'"),
+    business_meaning: z.string().describe("Human-readable business meaning. Example: 'Service has been published and is now immutable'"),
+    category: z.enum(["lifecycle", "state_change", "fund_flow", "permission", "guard", "other"]).describe("Business category. Constraint: enum of 6 values. Example: 'lifecycle'"),
+    related_object: z.string().optional().describe("Object ID the event relates to, if extractable. Example: '0x123...'"),
+    side_effect: z.string().optional().describe("Side effect description for AI. Example: 'Customers can now place orders against this Service'"),
+}).strict().describe("An on-chain event annotated with business semantics");
+export const SemanticSummarySchema = z.object({
+    intent: z.string().describe("Inferred user intent / operation goal. Constraint: snake_case string. Relation: derived from operation_type + data signals. Example: 'publish_service'"),
+    status: z.enum(["success", "partial", "failed", "pending_input"]).describe("Business-level status (not raw tx status). 'pending_input' = needs Guard submission. Example: 'success'"),
+    summary: z.string().describe("One-sentence human-readable summary of what happened. AI should read this first. Example: 'Successfully published Service my-shop with Machine bound'"),
+    created: z.array(ObjectRoleSchema).optional().describe("Objects newly created in this operation, tagged with roles"),
+    modified: z.array(ObjectRoleSchema).optional().describe("Objects mutated in this operation, tagged with roles"),
+    released: z.array(FundRoleSchema).optional().describe("Fund movements in this operation, tagged with roles"),
+    events: z.array(EventSemanticSchema).optional().describe("On-chain events annotated with business semantics (S-8)"),
+    next_actions: z.array(NextActionSchema).optional().describe("Recommended next actions to drive the workflow forward"),
+    warnings: z.array(z.string()).optional().describe("Business-level warnings. Example: 'order_allocators not configured; order funds cannot be distributed'"),
+}).strict().describe("Business semantic summary: translates the raw transaction response into AI-directly-understandable business meaning");
 export const CallResponseErrorSchema = z.object({
-    type: z.literal("error").describe("Type of call response: error"),
-    error: z.string(),
-}).describe("Call error data. Contains error information.");
+    type: z.literal("error").describe("Discriminator for this result variant. Constraint: always 'error'. Example: 'error'"),
+    error: z.string().describe("Human-readable error message from the chain or SDK. Relation: enriched via enrichMoveError before classification. Example: 'Insufficient balance for gas'"),
+    error_code: z.enum(["invalid_parameter", "guard_rejected", "state_conflict", "insufficient_balance", "object_not_found", "permission_denied", "immutable_violation", "network_error", "unknown"]).optional().describe("Error classification for programmatic recovery. Constraint: enum of 9 values. Relation: drives Recover Loop strategy selection. Example: 'insufficient_balance'"),
+    retryable: z.boolean().optional().describe("Whether the same call can be retried as-is. Constraint: true only for network_error and insufficient_balance. Example: true"),
+    recovery_hint: z.string().optional().describe("Recovery suggestion for AI or user. Relation: paired with error_code to guide Recover Loop. Example: 'Claim faucet tokens then retry'"),
+    related_object: z.string().optional().describe("Object ID related to the error, if any. Example: '0x123...'"),
+}).describe("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.");
 export const GuardSubmissionToFillSchema = z.object({
-    guard: NameOrAddressSchema.describe("Guard object name or ID."),
-    submission: z.array(GuardTableItemSchema).describe("User-submitted data required for Guard verification."),
-}).strict().describe("Permission guard submission data.");
+    guard: NameOrAddressSchema.describe("Guard object name or ID that requires submission data. Example: 'my-delivery-guard'"),
+    submission: z.array(GuardTableItemSchema).describe("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...'}]"),
+}).strict().describe("One Guard's submission data: the Guard to verify plus the user-provided data that satisfies its requirements.");
 export const SubmissionCallSchema = z.object({
-    type: z.literal("submission").describe("Type of call response: submission"),
+    type: z.literal("submission").describe("Discriminator for this result variant. Constraint: always 'submission'. Example: 'submission'"),
     guard: z.array(z.object({
-        object: NameOrAddressSchema.describe("Guard object name or ID."),
-        impack: z.boolean().describe("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."),
-    }).strict()),
-    submission: z.array(GuardSubmissionToFillSchema),
-}).strict().describe("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.");
+        object: NameOrAddressSchema.describe("Guard object name or ID to verify against. Example: 'my-delivery-guard' or '0x123...'"),
+        impack: z.boolean().describe("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"),
+    }).strict()).describe("Array of Guard objects to verify. Relation: each entry corresponds to a Guard bound to the operation."),
+    submission: z.array(GuardSubmissionToFillSchema).describe("User-submitted data for each Guard. Relation: one entry per Guard in the guard array; fill submission fields and resubmit via call_with_submission."),
+}).strict().describe("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'.");
 export const TypedPermissionObjectSchema = z.union([
     NameOrAddressSchema.describe("String format: Reference an EXISTING object by its name (local mark) or on-chain object ID. Use this when the object already exists and you want to reference it."),
     TypeNamedObjectWithPermissionSchema.describe("Object format: CREATE a NEW object with COMPLETE configuration including: optional name, tags, description, token type for payments (e.g., '0x2::wow::WOW'), AND Permission-based access control. Use this for creating sophisticated objects with both payment token specification and permission management."),
@@ -108,17 +158,17 @@ export const TypedDescriptionObjectSchema = z.union([
 export const CallResultSchema = z.discriminatedUnion("type", [
     SubmissionCallSchema,
     WowTransactionBlockResponseSchema.extend({
-        type: z.literal("transaction"),
+        type: z.literal("transaction").describe("Discriminator for this result variant. Constraint: always 'transaction'. Example: 'transaction'"),
     }),
     CallResponseErrorSchema,
     z.object({
-        type: z.literal("data"),
-        data: z.array(ResponseDataSchema),
+        type: z.literal("data").describe("Discriminator for this result variant. Constraint: always 'data'. Example: 'data'"),
+        data: z.array(ResponseDataSchema).describe("Array of object records returned by a query operation. Example: [{id:'0x...', change:'created'}]"),
     }),
     z.object({
-        type: z.literal("null"),
+        type: z.literal("null").describe("Discriminator for this result variant. Constraint: always 'null'. Example: 'null'"),
     }),
-]).describe("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.");
+]).describe("Discriminated union of 5 result types: 'transaction' (raw Sui response with digest/effects/objectChanges), 'submission' (Guard verification needed), 'error' (failed with error_code), 'data' (query result array), 'null' (no-op completed). AI should check result.type first to determine how to process the response.");
 export const ObjectsSchema = z.union([
     z.object({
         op: z.union([z.literal('add'), z.literal('set')]),
@@ -132,7 +182,35 @@ export const ObjectsSchema = z.union([
         op: z.literal('clear'),
     }).strict(),
 ]);
+export const VerifyMismatchSchema = z.object({
+    dimension: z.enum(["created", "modified", "released", "state", "event"]).describe("Verify dimension that mismatched. Example: 'created'"),
+    expected: z.string().describe("What the Expect Loop declared. Example: 'Service object created'"),
+    actual: z.string().describe("What actually happened. Example: 'No object created'"),
+    severity: z.enum(["pass", "warn", "fail"]).describe("Severity: 'fail' blocks progress, 'warn' is advisory, 'pass' never appears here. Example: 'fail'"),
+    detail: z.string().describe("Human-readable explanation of the mismatch. Example: 'Expected Service creation but transaction succeeded without object change'"),
+}).describe("One mismatch between expected and actual result. AI should read severity first to decide whether to halt.");
+export const VerifyReportSchema = z.object({
+    status: z.enum(["pass", "warn", "fail"]).describe("Overall verify status. Constraint: 'fail' if any mismatch has severity 'fail'; 'warn' if only warns; 'pass' if no mismatches. Example: 'fail'"),
+    mismatches: z.array(VerifyMismatchSchema).describe("List of mismatches found. Empty array when status is 'pass'. Example: [{dimension:'created', expected:'...', actual:'...', severity:'fail', detail:'...'}]"),
+    summary: z.string().describe("Human-readable summary of the verify result. Example: '2 mismatches found: created dimension failed, event dimension warned'"),
+    timestamp: z.string().describe("ISO 8601 timestamp when verify ran. Example: '2026-07-14T10:30:00.000Z'"),
+}).describe("Verify Loop report. Compares expected vs actual semantic fields across 5 dimensions. When status is 'fail', AI should consult the recovery_action in the parent harness_report.");
+export const RecoveryActionSchema = z.object({
+    strategy: z.enum(["retry", "claim_faucet", "fill_submission", "recreate", "switch_account", "query_and_retry", "adjust_params", "escalate_human", "stop"]).describe("Recovery strategy chosen by the Recover Loop. Constraint: 9 strategies matching error_code table. Example: 'claim_faucet'"),
+    should_retry: z.boolean().describe("Whether AI should retry the original operation after applying the strategy. Constraint: false for 'stop' and 'escalate_human'. Example: true"),
+    adjusted_params: z.record(z.string(), z.unknown()).optional().describe("Suggested parameter adjustments for 'adjust_params' strategy. Example: {amount: '100000000'}"),
+    user_prompt: z.string().optional().describe("Prompt to show the user when recovery is semi-automatic or manual. Example: 'Please switch to an account with provider permission'"),
+    max_attempts: z.number().int().describe("Maximum attempts for this error_code type. Example: 3"),
+    current_attempt: z.number().int().describe("Current attempt count (1-indexed). Example: 1"),
+    detail: z.string().describe("Human-readable explanation of the recovery decision. Example: 'Insufficient balance detected; claim faucet tokens then retry'"),
+}).describe("Recover Loop action. Generated when verify fails or an error occurs. AI should follow the strategy and respect max_attempts.");
+export const HarnessReportSchema = z.object({
+    verify: VerifyReportSchema.describe("Verify Loop report comparing expected vs actual."),
+    recovery: RecoveryActionSchema.optional().describe("Recover Loop action. Present only when verify.status is 'fail' or 'warn', or when an error occurred."),
+}).describe("L4 Harness report attached to CallOutput when the Harness is injected. Contains verify result and optional recovery action. AI should check verify.status first; if 'fail', consult recovery.strategy.");
 export const CallOutputSchema = z.object({
-    result: CallResultSchema,
-    message: z.string().optional().describe("Message or hint information"),
-}).strict().describe("On-chain Operation Result");
+    result: CallResultSchema.describe("Discriminated result. Check result.type first: 'transaction'|'submission'|'error'|'data'|'null'. Each variant has different fields."),
+    message: z.string().optional().describe("Human-readable summary or hint. Constraint: always present for error/transaction results; may be omitted for data/null. Example: 'Transaction completed successfully'"),
+    semantic: SemanticSummarySchema.optional().describe("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: HarnessReportSchema.optional().describe("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'}}"),
+}).strict().describe("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'.");

package/dist/schema/call/bridge-handler.js

@@ -1,4 +1,5 @@
 import { BridgeClient, LocalMark, } from "@wowok/wowok";
+import { classifyError, buildSemantic, buildDataSemantic } from "./semantic.js";
 let _bridgeClient = null;
 let _bridgeClientEnv = null;
 function getBridgeClient(env) {
@@ -56,9 +57,10 @@ function convertBigInts(obj) {
     }
     return obj;
 }
-function ok(message, result) {
+function ok(message, result, context) {
     const safeResult = convertBigInts(result);
-    const output = { message, result: { type: "data", data: safeResult } };
+    const semantic = buildSemantic(safeResult, context);
+    const output = { message, result: { type: "data", data: safeResult }, semantic };
     return {
         content: [
             { type: "text", text: message },
@@ -67,8 +69,20 @@ function ok(message, result) {
         structuredContent: output,
     };
 }
-function err(message) {
-    const output = { message, result: { type: "error", error: message } };
+function err(message, context) {
+    const classified = classifyError(message);
+    const semantic = buildDataSemantic(undefined, context, true, message);
+    const output = {
+        message,
+        result: {
+            type: "error",
+            error: message,
+            error_code: classified.error_code,
+            retryable: classified.retryable,
+            recovery_hint: classified.recovery_hint,
+        },
+        semantic,
+    };
     return {
         content: [{ type: "text", text: message }],
         structuredContent: output,
@@ -87,6 +101,10 @@ export async function handleBridgeOperations(args) {
         return err(`Parameter validation failed: ${e?.message ?? String(e)}`);
     }
     const env = validated.env;
+    const ctx = {
+        operation_type: "bridge_" + validated.operation_type,
+        data: validated.data,
+    };
     try {
         switch (validated.operation_type) {
             case "cross_chain_wow_to_evm": {
@@ -100,7 +118,7 @@ export async function handleBridgeOperations(args) {
                     waitForFinalization: false,
                 });
                 return ok(`WOW→EVM cross-chain step 1 (deposit) submitted. transferId=${result.transferId}, activeEvmAccount=${result.activeEvmAccount}. ` +
-                    `Next: poll query_transfer_status until bridge signs (~1-5 min), then call claim_wow_to_evm to complete.`, result);
+                    `Next: poll query_transfer_status until bridge signs (~1-5 min), then call claim_wow_to_evm to complete.`, result, ctx);
             }
             case "cross_chain_evm_to_wow": {
                 validateMainnet(env);
@@ -114,14 +132,14 @@ export async function handleBridgeOperations(args) {
                     waitForFinalization: false,
                 });
                 return ok(`EVM→WOW cross-chain submitted. transferId=${result.transferId}, activeEvmAccount=${result.activeEvmAccount}. ` +
-                    `Bridge will auto-claim on WOW (~10-20 min). Poll query_transfer_status to monitor progress.`, result);
+                    `Bridge will auto-claim on WOW (~10-20 min). Poll query_transfer_status to monitor progress.`, result, ctx);
             }
             case "claim_wow_to_evm": {
                 validateMainnet(env);
                 const data = validated.data;
                 const client = getBridgeClient(env);
                 const result = await client.claimWowToEvm(data.transferId);
-                return ok(`WOW→EVM claim (step 2) completed. transferId=${result.transferId}, claimTxHash=${result.claimTxHash}`, result);
+                return ok(`WOW→EVM claim (step 2) completed. transferId=${result.transferId}, claimTxHash=${result.claimTxHash}`, result, ctx);
             }
             case "withdraw": {
                 const data = validated.data;
@@ -133,7 +151,7 @@ export async function handleBridgeOperations(args) {
                     const tokenMeta = chain?.tokens?.find((t) => t.symbol === data.token);
                     tokenAddress = tokenMeta?.evmAddress;
                     if (!tokenAddress) {
-                        return err(`Cannot resolve ERC20 token address for symbol '${data.token}' on chain '${data.network ?? "mainnet"}'. Please pass tokenAddress explicitly.`);
+                        return err(`Cannot resolve ERC20 token address for symbol '${data.token}' on chain '${data.network ?? "mainnet"}'. Please pass tokenAddress explicitly.`, ctx);
                     }
                 }
                 const result = await client.withdrawFromActiveEvmAccount({
@@ -143,7 +161,7 @@ export async function handleBridgeOperations(args) {
                     token: data.token ? data.token : undefined,
                     network: data.network,
                 });
-                return ok(`Withdrawal submitted. transferId=${result.transferId}, txHash=${result.txHash}`, result);
+                return ok(`Withdrawal submitted. transferId=${result.transferId}, txHash=${result.txHash}`, result, ctx);
             }
             case "query_active_evm_account": {
                 const data = validated.data ?? {};
@@ -152,12 +170,12 @@ export async function handleBridgeOperations(args) {
                     network: data.network,
                     tokens: data.tokens,
                 });
-                return ok(`activeEvmAccount: ${result.address} (${result.chains.length} chain(s))`, result);
+                return ok(`activeEvmAccount: ${result.address} (${result.chains.length} chain(s))`, result, ctx);
             }
             case "query_supported_evm_chains": {
                 const client = getBridgeClientForQuery();
                 const result = await client.querySupportedEvmChains();
-                return ok(`${result.length} EVM chain(s) supported: ${result.map(c => `${c.name}(chainId=${c.chainId})`).join(", ")}`, result);
+                return ok(`${result.length} EVM chain(s) supported: ${result.map(c => `${c.name}(chainId=${c.chainId})`).join(", ")}`, result, ctx);
             }
             case "query_supported_tokens": {
                 const data = validated.data ?? {};
@@ -166,7 +184,7 @@ export async function handleBridgeOperations(args) {
                     network: data.network,
                 });
                 const totalTokens = result.reduce((sum, c) => sum + c.tokens.length, 0);
-                return ok(`${result.length} chain(s), ${totalTokens} token entries: ${result.map((c) => `${c.chainName}(${c.tokens.length} tokens)`).join(", ")}`, result);
+                return ok(`${result.length} chain(s), ${totalTokens} token entries: ${result.map((c) => `${c.chainName}(${c.tokens.length} tokens)`).join(", ")}`, result, ctx);
             }
             case "query_transfer_list": {
                 const data = validated.data ?? {};
@@ -187,7 +205,7 @@ export async function handleBridgeOperations(args) {
                     result = result.slice(0, data.limit);
                 }
                 const active = result.filter(r => r.status !== "success" && r.status !== "failed").length;
-                return ok(`${result.length} transfer record(s) (${active} in progress)${data.status || data.direction || data.token ? " (filtered)" : ""}`, result);
+                return ok(`${result.length} transfer record(s) (${active} in progress)${data.status || data.direction || data.token ? " (filtered)" : ""}`, result, ctx);
             }
             case "query_transfer_status": {
                 const data = validated.data;
@@ -208,9 +226,9 @@ export async function handleBridgeOperations(args) {
                     return err(`transferId '${data.transferId}' not found. ` +
                         `Use query_transfer_list to see all valid transferIds. ` +
                         `Note: transfer history is persisted in cache.db and restored on MCP restart, ` +
-                        `so this transferId may never have been created in this environment.`);
+                        `so this transferId may never have been created in this environment.`, ctx);
                 }
-                return ok(`Transfer ${data.transferId}: ${result.direction} / ${result.step} / ${result.status}`, result);
+                return ok(`Transfer ${data.transferId}: ${result.direction} / ${result.step} / ${result.status}`, result, ctx);
             }
             case "manage_evm_rpc": {
                 const data = validated.data;
@@ -220,15 +238,15 @@ export async function handleBridgeOperations(args) {
                     network: data.network,
                     rpcUrls: data.rpcUrls,
                 });
-                return ok(`RPC '${data.op}' operation ${result.success ? "succeeded" : "failed"}`, result);
+                return ok(`RPC '${data.op}' operation ${result.success ? "succeeded" : "failed"}`, result, ctx);
             }
             default: {
-                return err(`Unsupported operation_type: ${validated.operation_type}`);
+                return err(`Unsupported operation_type: ${validated.operation_type}`, ctx);
             }
         }
     }
     catch (e) {
         const msg = e?.message ?? String(e);
-        return err(`Bridge operation failed: ${msg}`);
+        return err(`Bridge operation failed: ${msg}`, ctx);
     }
 }