@wowok/agent-mcp 2.3.16 → 2.4.1

package/dist/schema/call/base.js

@@ -67,6 +67,8 @@ export const CallEnvSchema = z.object({
     confirmed: z.boolean().optional().describe("Phase 2 ConfirmGate: set to true to proceed after a 'pending_confirmation' result. The operation is NOT executed until you re-call with confirmed=true after user consent."),
     user_intent_phrases: z.array(z.string()).optional().describe("Phase 2 ConfirmGate: explicit user intent phrases collected from conversation context (e.g. 'use default account', 'force publish'). Used to bypass confirmation rules whose bypass_on_explicit_intent matches."),
     project: z.string().optional().describe("Phase 2 ProjectService: explicit project prefix to assign this object to (e.g. 'myshop'). When set, the object is tagged with 'project:<prefix>' automatically. Overrides the prefix parsed from the object name."),
+    client_schema_version: z.string().optional().describe("Client-side schema version (semver, e.g. '1.0.0'). When provided, the server checks compatibility and attaches warnings if mismatched."),
+    schema_strict_mode: z.boolean().optional().describe("When true, schema incompatibility returns an error instead of a warning. Default: false (warn mode)."),
 }).strict().describe(`IMPORTANT: Execution environment includes: account for signing operations, network selection (${ENTRYPOINT}), additional Guard permissions, and more. Used to specify context information during the call. If account is not specified, the default account ("") will be used.`);
 export const ObjectsOpSchema = z.union([
     z.object({
@@ -120,7 +122,7 @@ export const ExperienceSchema = z.object({
     avoid: z.array(z.string()).optional().describe("Pitfalls to avoid based on history. Example: ['Guard rejection on delivery_proof']"),
     relevance: z.number().min(0).max(1).optional().describe("Relevance score 0-1 of the matched experience. Example: 0.85"),
     matched_scenario: z.string().optional().describe("Matched historical scenario. Example: 'publish_service_freelance'"),
-}).strict().describe("Experience layer feedback from past operations (Phase 2 议题 2). Provides advice and pitfalls based on historical patterns.");
+}).strict().describe("Experience layer feedback from past operations (Phase 2 Topic 2). Provides advice and pitfalls based on historical patterns.");
 export const ServiceStatusSchema = z.object({
     active: z.array(z.string()).describe("Phase 2 services currently active (enabled). Example: ['confirm_gate','project_service','experience_layer']"),
     inactive: z.array(z.string()).optional().describe("Phase 2 services currently inactive (can be toggled via config_operation). Example: ['harness','graph_persist']"),
@@ -129,31 +131,82 @@ export const CustomerReminderSchema = z.object({
     id: z.string().describe("Reminder rule id. Example: 'high_risk_score'"),
     stage: z.enum(["browse", "evaluate", "preorder", "in_progress", "complete", "after_sale"]).describe("Order lifecycle stage when this reminder fires. Example: 'evaluate'"),
     priority: z.enum(["required", "recommended", "info", "reminder"]).describe("Priority. 'required' = blocks purchase; 'recommended' = strong caution. Example: 'required'"),
-    message: z.string().describe("Human-readable reminder message. Example: '🔴 综合风险分 25/100，强烈建议不购买'"),
+    message: z.string().describe("Human-readable reminder message. Example: 'Composite risk score 25/100, strongly discourage purchase'"),
     action: z.string().optional().describe("Suggested next action. Example: 'require merchant to bind Arbitration before ordering'"),
 }).strict().describe("A buyer-side reminder triggered at a specific order lifecycle stage (Phase 3 C-3).");
 export const PreferenceMatchSchema = z.object({
     score: z.number().min(0).max(100).describe("Match score 0-100 (higher = better fit). Example: 75"),
-    matches: z.array(z.string()).describe("Aspects that match user preferences. Example: ['价格低于均价 10%','有仲裁']"),
-    mismatches: z.array(z.string()).describe("Aspects that mismatch user preferences. Example: ['交付周期超出期望']"),
+    matches: z.array(z.string()).describe("Aspects that match user preferences. Example: ['Price 10% below average','Has arbitration']"),
+    mismatches: z.array(z.string()).describe("Aspects that mismatch user preferences. Example: ['Delivery cycle exceeds expectation']"),
 }).strict().describe("Service-to-preference match result (Phase 3 C-2). 7-dimension scoring: price/time/region/brand/bargain/emotion/risk.");
 export const CustomerAdviceSchema = z.object({
     risk_score: z.number().min(0).max(100).optional().describe("Composite risk score 0-100 (higher = safer). Relation: from risk-assessment.ts 4-dimension scoring. Example: 75"),
     risk_level: z.enum(["low", "medium_low", "medium_high", "high"]).optional().describe("Risk level bucket. 'high' = strongly discourage purchase. Example: 'medium_high'"),
-    recommendations: z.array(z.string()).describe("Actionable recommendations for the buyer. Example: ['要求商家配置仲裁','通过 Messenger 协商退款条款']"),
-    reminders: z.array(CustomerReminderSchema).describe("Stage-specific reminders (deduped, sorted by priority, capped to 3 high-risk). Example: [{priority:'required', message:'🔴 模糊 Guard 必须人工审查'}]"),
+    recommendations: z.array(z.string()).describe("Actionable recommendations for the buyer. Example: ['Require merchant to configure arbitration','Negotiate refund terms via Messenger']"),
+    reminders: z.array(CustomerReminderSchema).describe("Stage-specific reminders (deduped, sorted by priority, capped to 3 high-risk). Example: [{priority:'required', message:'Ambiguous Guard must be human-reviewed'}]"),
     preference_match: PreferenceMatchSchema.optional().describe("Service-to-preference match (populated when user preferences exist). Example: {score:75, matches:[...], mismatches:[...]}"),
 }).strict().describe("Buyer-side advice (Phase 3 C-3.3). Populated in semantic.customer_advice for order/query operations when customer_intelligence service is enabled.");
 export const EvolutionContextSchema = z.object({
-    industry_signal: z.string().optional().describe("Industry evolution signal summary. Example: '行业健康度 82/100（healthy）；累积 25 个行业信号'"),
-    evolution_advice: z.string().optional().describe("Evolution advice for the current operation. Example: '建议强制配置仲裁 + 赔偿金 + 交付 Guard'"),
+    industry_signal: z.string().optional().describe("Industry evolution signal summary. Example: 'Industry health 82/100 (healthy); 25 cumulative industry signals'"),
+    evolution_advice: z.string().optional().describe("Evolution advice for the current operation. Example: 'Recommend mandatory arbitration + compensation fund + delivery Guard'"),
     confidence: z.number().min(0).max(1).describe("Confidence of the evolution context 0-1. <0.5 means no data yet. Example: 0.75"),
     health_score: z.number().min(0).max(100).optional().describe("Industry health score 0-100 if available. Example: 82"),
     pending_suggestions: z.number().int().min(0).optional().describe("Count of pending industry update suggestions (filtered by role if role is set). Example: 3"),
     intent: z.enum(["default", "growth", "retention", "compliance", "efficiency", "trust_building", "custom"]).optional().describe("Phase 4 P4-6.C: Current business intent driving the scoring model. Absent = 'default'. Example: 'growth'"),
-    role_advice: z.array(z.string()).optional().describe("Phase 4 P4-6.C: Role-targeted advice strings (user/merchant/arbitrator). Example: ['强化忠诚度飞轮','优化首单转化']"),
+    role_advice: z.array(z.string()).optional().describe("Phase 4 P4-6.C: Role-targeted advice strings (user/merchant/arbitrator). Example: ['Strengthen loyalty flywheel','Optimize first-order conversion']"),
     role: z.enum(["user", "merchant", "arbitrator"]).optional().describe("Phase 4 P4-6.C: Role used for advice routing. Example: 'merchant'"),
 }).strict().describe("Phase 4 industry evolution context (populated when industry_evolution service is enabled). Provides AI with industry-level health signals, evolution advice, and role-targeted recommendations.");
+export const GuardPuzzleStatusSchema = z.object({
+    intent: z.boolean().describe("Intent dimension complete (action + rule + failure conditions)"),
+    binding: z.boolean().describe("Binding dimension complete (host object + field + circular ref)"),
+    data: z.boolean().describe("Data dimension complete (table entries + witnesses)"),
+    query: z.boolean().describe("Query dimension complete (query instructions if needed)"),
+    logic: z.boolean().describe("Logic dimension complete (root node returns Bool)"),
+    constraints: z.boolean().describe("Constraints dimension complete (10 Pitfalls checked)"),
+}).strict().describe("Guard information puzzle completeness status. 6 dimensions (A-F). false = missing, needs user input.");
+export const GuardAvailableQuerySchema = z.object({
+    id: z.number().int().describe("Query instruction ID. Example: 1253"),
+    name: z.string().describe("Query instruction name. Example: 'progress.current_node_name'"),
+    objectType: z.string().describe("Target object type. Example: 'Progress'"),
+    returnType: z.string().describe("Return value type. Example: 'String'"),
+    description: z.string().optional().describe("Query description"),
+}).strict().describe("A Guard query instruction available for the current context (subset of GUARDQUERY 375 entries).");
+export const GuardAdviceSchema = z.object({
+    current_round: z.enum(["R1", "R2", "R3", "R4", "R5", "R6", "R7", "R8", "R9", "R10"]).optional()
+        .describe("Current R1-R10 dialogue round. R1=intent, R2=table, R3=tree, R4=rely, R5=binding, R6=review, R7=CREATE, R8=test, R9=bind, R10=verify. Example: 'R3'"),
+    puzzle_status: GuardPuzzleStatusSchema.optional()
+        .describe("Information puzzle completeness (6 dimensions). Missing dimensions need user input before CREATE."),
+    matched_scene: z.string().optional()
+        .describe("Matched Guard scene id from the 8 binding scenarios ledger. Example: 'machine_forward_guard'"),
+    scene_description: z.string().optional()
+        .describe("Human-readable scene description. Example: 'Workflow node forward validation (Forward.guard)'"),
+    scene_constraints: z.array(z.string()).optional()
+        .describe("Special constraints for the matched scene. Example: ['Forward.guard cannot be modified after Machine is published']"),
+    suggested_patterns: z.array(z.string()).optional()
+        .describe("Suggested Guard patterns based on user intent. Example: ['time lock','progress status check']"),
+    available_queries: z.array(GuardAvailableQuerySchema).optional()
+        .describe("Available query instructions for the current context (subset of 375 GUARDQUERY entries)"),
+    risk_warnings: z.array(z.string()).optional()
+        .describe("Risk warnings for the current Guard design. Example: ['Guard cannot be modified after creation','Time lock test uses 1000ms']"),
+    pending_questions: z.array(z.string()).optional()
+        .describe("Questions for the user to complete the puzzle. Example: ['Which Host Object will the Guard bind to?']"),
+    confirmation_text: z.string().optional()
+        .describe("Structured semantic confirmation text for user review (generated when puzzle is complete). User must explicitly confirm before CREATE."),
+    test_result: z.object({
+        status: z.enum(["pass", "fail", "not_tested"]),
+        failure_node: z.string().optional().describe("Node that caused failure (if fail)"),
+        passport_id: z.string().optional().describe("Generated Passport ID (if pass)"),
+    }).optional().describe("gen_passport static test result. Must pass before CREATE."),
+    risk_assessment: z.object({
+        overall_risk: z.enum(["critical", "high", "medium", "low", "info"]).describe("Overall risk level (highest from all risks)"),
+        risk_count: z.number().int().describe("Total number of detected risks"),
+        critical_count: z.number().int().describe("Number of critical risks"),
+        high_count: z.number().int().describe("Number of high risks"),
+        needs_human_review: z.boolean().describe("Whether human review is required (critical or 2+ high risks)"),
+        top_risks: z.array(z.string()).describe("Top risk titles (critical and high, max 3)"),
+        stakeholder_advice: z.record(z.string(), z.array(z.string())).optional().describe("Per-stakeholder advice. Key=stakeholder (customer/provider/arbitrator/claimant), value=advice list"),
+    }).optional().describe("Business-layer risk assessment (game theory, data source trust, logic gaps). Populated during Guard design to warn about business risks beyond syntax."),
+}).strict().describe("Guard advice (Phase 5 Guard capability system). Injected when user intent involves Guard. Provides context for Guard design, generation, confirmation, and execution.");
 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'"),
@@ -164,16 +217,17 @@ export const SemanticSummarySchema = z.object({
     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'"),
-    experience: ExperienceSchema.optional().describe("Experience layer feedback from past operations (Phase 2 议题 2)"),
+    experience: ExperienceSchema.optional().describe("Experience layer feedback from past operations (Phase 2 Topic 2)"),
     service_status: ServiceStatusSchema.optional().describe("Phase 2 runtime service status (populated when semantic_rich is enabled). Lets AI see active services in each response."),
     customer_advice: CustomerAdviceSchema.optional().describe("Buyer-side advice (Phase 3 C-3.3). Populated when customer_intelligence service is enabled AND operation is order/query on a Service. Contains risk_score, recommendations, reminders, and preference_match."),
     evolution_context: EvolutionContextSchema.optional().describe("Phase 4 industry evolution context (populated when industry_evolution service is enabled). Provides AI with industry health signals and evolution advice."),
+    guard_advice: GuardAdviceSchema.optional().describe("Phase 5 Guard capability advice (populated when user intent involves Guard). Provides puzzle status, scene matching, suggested patterns, available queries, risk warnings, and confirmation text. AI uses this to guide Guard design dialogue (R1-R10)."),
 }).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("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"),
+    error_code: z.enum(["invalid_parameter", "guard_rejected", "state_conflict", "insufficient_balance", "object_not_found", "permission_denied", "immutable_violation", "network_error", "rate_limit", "gas_exceeded", "bcs_error", "signature_error", "config_error", "unknown"]).optional().describe("Error classification for programmatic recovery. Constraint: enum of 14 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 for network_error, rate_limit, gas_exceeded, 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.");
@@ -192,7 +246,7 @@ export const OperationPreviewSchema = z.object({
     immutable_after: z.array(z.string()).optional().describe("Fields that become immutable after this op (for publish). Example: ['machine','order_allocators']"),
     warnings: z.array(z.string()).optional().describe("Default-value warnings. Example: ['Using default account (env.account=\"\")']"),
     irreversible: z.boolean().optional().describe("True when the operation cannot be reverted. Example: true"),
-}).strict().describe("Preview of an operation awaiting user confirmation (Phase 2 议题 4 ConfirmGate).");
+}).strict().describe("Preview of an operation awaiting user confirmation (Phase 2 Topic 4 ConfirmGate).");
 export const CallPendingConfirmationSchema = z.object({
     type: z.literal("pending_confirmation").describe("Discriminator. The operation was NOT executed; it is blocked pending user confirmation. Re-call with env.confirmed=true to proceed, or modify/cancel."),
     preview: OperationPreviewSchema.describe("Preview of the operation awaiting confirmation."),
@@ -276,9 +330,19 @@ 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 SchemaWarningSchema = z.object({
+    compatible: z.boolean().describe("Whether the client schema version is compatible with the server."),
+    warnings: z.array(z.string()).describe("Schema compatibility warnings or errors."),
+    client_version: z.string().optional().describe("The client schema version that was checked."),
+    server_versions: z.object({
+        sdk: z.string().describe("Server-side SDK schema version."),
+        mcp: z.string().describe("Server-side MCP tool schema version."),
+    }).describe("Server-side schema versions."),
+}).strict().describe("Schema compatibility warning attached to tool output when client_schema_version is provided and a mismatch is detected.");
 export const CallOutputSchema = z.object({
     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'}}"),
+    schema_warning: SchemaWarningSchema.optional().describe("Schema compatibility warning. Present only when client_schema_version is provided in env and a mismatch is detected."),
 }).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

@@ -116,8 +116,11 @@ export async function handleBridgeOperations(args) {
                     amount: BigInt(data.amount),
                     withdrawTo: data.withdrawTo,
                     waitForFinalization: false,
+                    idempotencyKey: data.idempotencyKey,
+                    idempotentByParams: data.idempotentByParams,
                 });
-                return ok(`WOW→EVM cross-chain step 1 (deposit) submitted. transferId=${result.transferId}, activeEvmAccount=${result.activeEvmAccount}. ` +
+                const idemMsg = result.idempotentHit ? " [IDEMPOTENT HIT — no new deposit]" : "";
+                return ok(`WOW→EVM cross-chain step 1 (deposit) submitted. transferId=${result.transferId}, activeEvmAccount=${result.activeEvmAccount}.${idemMsg} ` +
                     `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": {
@@ -130,8 +133,11 @@ export async function handleBridgeOperations(args) {
                     amount: BigInt(data.amount),
                     recipientWowAddress,
                     waitForFinalization: false,
+                    idempotencyKey: data.idempotencyKey,
+                    idempotentByParams: data.idempotentByParams,
                 });
-                return ok(`EVM→WOW cross-chain submitted. transferId=${result.transferId}, activeEvmAccount=${result.activeEvmAccount}. ` +
+                const idemMsg = result.idempotentHit ? " [IDEMPOTENT HIT — no new deposit]" : "";
+                return ok(`EVM→WOW cross-chain submitted. transferId=${result.transferId}, activeEvmAccount=${result.activeEvmAccount}.${idemMsg} ` +
                     `Bridge will auto-claim on WOW (~10-20 min). Poll query_transfer_status to monitor progress.`, result, ctx);
             }
             case "claim_wow_to_evm": {
@@ -141,6 +147,13 @@ export async function handleBridgeOperations(args) {
                 const result = await client.claimWowToEvm(data.transferId);
                 return ok(`WOW→EVM claim (step 2) completed. transferId=${result.transferId}, claimTxHash=${result.claimTxHash}`, result, ctx);
             }
+            case "resume_transfer": {
+                validateMainnet(env);
+                const data = validated.data;
+                const client = getBridgeClient(env);
+                const result = await client.resumeTransfer(data.transferId);
+                return ok(`Transfer ${data.transferId} resumed. Current step: ${result.step}, status: ${result.status}.`, result, ctx);
+            }
             case "withdraw": {
                 const data = validated.data;
                 const client = getBridgeClientForQuery();