@wowok/agent-mcp 2.6.0 → 2.6.3

package/dist/tools/handlers/onchain.js

@@ -1,10 +1,247 @@
 import { readFileSync } from "fs";
 import { resolve } from "path";
-import { CallService, CallMachine, CallProgress, CallGuard, CallArbitration, CallRepository, CallContact, CallTreasury, CallReward, CallAllocation, CallPersonal, CallPayment, CallDemand, CallOrder, gen_passport, CallProof, gen_proof, ResponseData, LocalProject, parseGuardFile, formatGuardParseErrors, transformRewardInput, transformPersonalInput, } from "@wowok/wowok";
+import { CallService, CallMachine, CallProgress, CallGuard, CallArbitration, CallRepository, CallContact, CallTreasury, CallReward, CallAllocation, CallPersonal, CallPayment, CallDemand, CallOrder, gen_passport, CallProof, gen_proof, ResponseData, LocalProject, LocalMark, query_objects, parseGuardFile, formatGuardParseErrors, transformRewardInput, transformPersonalInput, } from "@wowok/wowok";
 import { OnchainOperationsSchema, strictParse, getEnvConfig, handleCallResult, checkClientSchemaCompatibility, parseMachineNodesFromText, formatNodeErrors as formatMachineNodeErrors, transformSubmission, } from "../../schema/index.js";
 import { handlePermissionOperations } from "../../schema/call/permission-handler.js";
+import { collectPermissionIndexes, checkPermissionAuthorization, formatPermissionWarning, } from "../../schema/utils/permission-machine-check.js";
 import { isProjectServiceEnabled, normalize as projectNormalize, } from "../../project/index.js";
+import { getSkillsHintForOnchain } from "../../schema/utils/skills-recommendation.js";
+import { processFundOperation, generateSkillsHint as generateFundSkillsHint } from "../../knowledge/fund-layer.js";
+import { generateGuardSubmissionPrompt, formatSubmissionPrompt } from "../../knowledge/guard-submission-prompt.js";
 import { withHarness } from "../shared.js";
+function formatRecipientLabel(recipient) {
+    if (!recipient)
+        return "unknown";
+    if (typeof recipient === "string")
+        return recipient;
+    if ("GuardIdentifier" in recipient) {
+        return `GuardIdentifier(${recipient.GuardIdentifier})`;
+    }
+    if ("Entity" in recipient) {
+        const addr = recipient.Entity;
+        if (typeof addr === "string" && addr.length > 16) {
+            return `Entity(${addr.slice(0, 8)}...${addr.slice(-4)})`;
+        }
+        return `Entity(${addr})`;
+    }
+    if ("Signer" in recipient) {
+        return "Signer (transaction signer)";
+    }
+    return JSON.stringify(recipient);
+}
+function formatMistAmount(amount) {
+    const wowEquivalent = Number(amount) / 1_000_000_000;
+    if (wowEquivalent === 0)
+        return "0 WOW";
+    const wowStr = wowEquivalent.toFixed(9).replace(/\.?0+$/, "");
+    return `${wowStr} WOW (${amount.toString()} MIST)`;
+}
+function extractNodesForCheck(data) {
+    if (!data?.node)
+        return [];
+    if (data.node.nodes && Array.isArray(data.node.nodes)) {
+        return data.node.nodes;
+    }
+    return [];
+}
+function resolvePermissionRef(data) {
+    if (!data?.object)
+        return null;
+    if (typeof data.object === "string")
+        return null;
+    const obj = data.object;
+    if (obj.permission) {
+        if (typeof obj.permission === "string")
+            return obj.permission;
+        return null;
+    }
+    return null;
+}
+async function checkMachinePermissionBeforePublish(data, env) {
+    if (data?.publish !== true)
+        return "";
+    const nodes = extractNodesForCheck(data);
+    if (nodes.length === 0)
+        return "";
+    const collection = collectPermissionIndexes(nodes);
+    if (collection.requiredIndexes.length === 0) {
+        return "";
+    }
+    let warning = "";
+    if (collection.missingRefs.length > 0) {
+        warning += "WARNING: Some forwards have NEITHER permissionIndex nor namedOperator. " +
+            "These forwards cannot be executed. Add one or the other:\n";
+        for (const ref of collection.missingRefs) {
+            warning += `  - Node "${ref.nodeName}", pair prev_node="${ref.prevNode}", forward "${ref.forwardName}"\n`;
+        }
+        warning += "\n";
+    }
+    const permRef = resolvePermissionRef(data);
+    if (!permRef) {
+        if (collection.requiredIndexes.length > 0) {
+            warning += "PRE-PUBLISH REMINDER: This Machine uses " + collection.requiredIndexes.length +
+                " custom permission index(es): [" + collection.requiredIndexes.join(", ") + "]. " +
+                "After creating the Permission object, grant entities for each index via " +
+                'permission.op="add perm by index" BEFORE publishing the Machine. ' +
+                "Otherwise, forwards using these indexes will be un-executable.\n";
+        }
+        return warning;
+    }
+    let permAddress = permRef;
+    if (!permRef.startsWith("0x")) {
+        try {
+            const mark = await LocalMark.Instance().get(permRef);
+            if (mark?.address) {
+                permAddress = mark.address;
+            }
+            else {
+                return warning + "PRE-PUBLISH: Could not resolve Permission name '" + permRef +
+                    "' to an address. Ensure the Permission object exists and is marked. " +
+                    "Required indexes: [" + collection.requiredIndexes.join(", ") + "]\n";
+            }
+        }
+        catch {
+            return warning + "PRE-PUBLISH: Failed to lookup Permission name '" + permRef +
+                "'. Required indexes: [" + collection.requiredIndexes.join(", ") + "]\n";
+        }
+    }
+    const network = env?.network ?? "testnet";
+    let permData = null;
+    try {
+        const queryResult = await query_objects({
+            objects: [permAddress],
+            network: network,
+        });
+        const permObj = queryResult?.objects?.[0];
+        if (permObj) {
+            permData = {
+                address: permAddress,
+                entity_count: permObj.entity_count,
+                perm_remark: permObj.perm_remark,
+                owner: permObj.owner ?? permObj.builder,
+                admin: permObj.admin,
+            };
+        }
+    }
+    catch {
+        return warning + "PRE-PUBLISH: Failed to query Permission object " + permAddress +
+            ". Required indexes: [" + collection.requiredIndexes.join(", ") + "]\n";
+    }
+    if (!permData) {
+        return warning + "PRE-PUBLISH: Permission object " + permAddress +
+            " not found on-chain. Required indexes: [" + collection.requiredIndexes.join(", ") + "]\n";
+    }
+    const report = checkPermissionAuthorization(collection.requiredIndexes, permData);
+    if (!report.allAuthorized) {
+        warning += formatPermissionWarning(report) + "\n";
+    }
+    return warning;
+}
+async function detectServiceGuardCircularDependency(data) {
+    if (!data || typeof data.object !== "object" || data.object === null)
+        return null;
+    const orderAllocators = data.order_allocators;
+    if (!orderAllocators || typeof orderAllocators !== "object")
+        return null;
+    const allocators = Array.isArray(orderAllocators.allocators)
+        ? orderAllocators.allocators
+        : [];
+    if (allocators.length === 0)
+        return null;
+    const unresolvedGuards = [];
+    const seen = new Set();
+    for (const alloc of allocators) {
+        const guardRef = alloc?.guard;
+        if (typeof guardRef === "string" && !guardRef.startsWith("0x")) {
+            if (seen.has(guardRef))
+                continue;
+            seen.add(guardRef);
+            try {
+                const addr = await LocalMark.Instance().get_address(guardRef);
+                if (!addr) {
+                    unresolvedGuards.push(guardRef);
+                }
+            }
+            catch {
+                unresolvedGuards.push(guardRef);
+            }
+        }
+    }
+    if (unresolvedGuards.length === 0)
+        return null;
+    const guardList = unresolvedGuards.map(g => `'${g}'`).join(", ");
+    const serviceObj = data.object;
+    const serviceName = serviceObj.name ?? "<service_name>";
+    const recommended_steps = [
+        {
+            step: 1,
+            action: "onchain_operations",
+            operation_type: "service",
+            params: {
+                ...data,
+                order_allocators: null,
+                publish: false,
+            },
+            purpose: `Create Service '${serviceName}' WITHOUT order_allocators to establish ` +
+                `its LocalMark entry. After this step, the name '${serviceName}' resolves ` +
+                `to an on-chain address.`,
+        },
+        {
+            step: 2,
+            action: "onchain_operations",
+            operation_type: "guard",
+            params: unresolvedGuards.map(name => ({
+                object: { name, type: "Guard" },
+                _hint: `Table items may reference Service '${serviceName}' by name`,
+            })),
+            purpose: `Create Guard(s) ${guardList}. Their table items can now resolve ` +
+                `Service '${serviceName}' by name (LocalMark entry from step 1).`,
+        },
+        {
+            step: 3,
+            action: "onchain_operations",
+            operation_type: "service",
+            params: {
+                object: serviceName,
+                order_allocators: orderAllocators,
+                publish: data.publish ?? true,
+            },
+            purpose: "Update Service with order_allocators (referencing Guards created in " +
+                "step 2) and publish. After publish, order_allocators becomes SDK-LOCKED.",
+        },
+    ];
+    const guideText = `⚠️ Circular dependency detected: Service ↔ Guard\n\n` +
+        `Cannot create Service with order_allocators referencing non-existent Guard(s): ${guardList}.\n\n` +
+        `Explanation: Guard table items may reference the Service by name, creating a circular ` +
+        `dependency: the Service must exist as a LocalMark before the Guard can resolve it, ` +
+        `but the Guard must exist before the Service can reference it in order_allocators. ` +
+        `The SDK would fail with a BCS serialization error: "Expected valid Address for ` +
+        `ValueType.Address, but failed to resolve string: <name>".\n\n` +
+        `Recommended steps:\n` +
+        recommended_steps
+            .map(s => `  Step ${s.step} (${s.operation_type}): ${s.purpose}`)
+            .join("\n") +
+        `\n\nHint: This is the canonical Service↔Guard circular dependency. The 3-step ` +
+        `pattern above is the documented solution (see SCHEMA-03 / P0-01 fix in ` +
+        `schema/call/service.ts publish field description).`;
+    return {
+        content: [{
+                type: "text",
+                text: guideText,
+            }],
+        structuredContent: {
+            result: {
+                type: "error",
+                error: `Cannot create Service with order_allocators referencing non-existent Guard(s): ${guardList}. Circular dependency: Service↔Guard.`,
+                error_code: "circular_dependency_detected",
+                retryable: true,
+                recovery_hint: JSON.stringify(recommended_steps),
+                related_object: serviceName,
+            },
+            message: "Circular dependency detected: Service ↔ Guard. See recovery_hint for the 3-step creation pattern.",
+        },
+    };
+}
 export async function handleOnchainOperations(args) {
     let validated;
     let constraintWarnings = [];
@@ -34,12 +271,19 @@ export async function handleOnchainOperations(args) {
             const rData = ResponseData(result);
             const created = rData.filter((r) => r.change === "created" && r.object);
             for (const obj of created) {
+                const isService = !!(obj.type_raw && obj.type_raw.includes("service::Service"));
                 await lp.addObject(project.id, {
                     objectAddress: obj.object,
                     objectType: obj.type_raw,
-                    role: "reference",
+                    role: isService ? "core" : "reference",
                 });
             }
+            if (operationType === "service") {
+                const svc = created.find((o) => o.type_raw && o.type_raw.includes("service::Service"));
+                if (svc && svc.object) {
+                    await lp.updateProject(project.id, { serviceAddress: svc.object }).catch(() => { });
+                }
+            }
         }
         catch {
         }
@@ -81,19 +325,144 @@ export async function handleOnchainOperations(args) {
             validated.data = pn.data;
             projectWarnings = pn.warnings ?? [];
         }
+        if (!env.account && projectEnvPrefix) {
+            try {
+                const project = await LocalProject.Instance().getProjectByPrefix(projectEnvPrefix);
+                if (project?.defaultAccount) {
+                    env.account = project.defaultAccount;
+                }
+            }
+            catch { }
+        }
         delete env.confirmed;
         delete env.user_intent_phrases;
         delete env.project;
         delete env.client_schema_version;
         delete env.schema_strict_mode;
+        const skillsHint = getSkillsHintForOnchain(validated.operation_type, validated.data);
+        if (skillsHint) {
+            constraintWarnings.push(skillsHint);
+        }
         switch (validated.operation_type) {
             case "service": {
-                const callService = new CallService(validated.data);
-                const result = validated.submission
-                    ? await callService.call_with_submission(env, await transformSubmission(validated.submission))
-                    : await callService.call(env);
                 const data = validated.data;
+                const circularDepGuide = await detectServiceGuardCircularDependency(data);
+                if (circularDepGuide) {
+                    return circularDepGuide;
+                }
+                const fundResult = await processFundOperation(data, "service", env?.network);
+                constraintWarnings.push(...fundResult.warnings);
+                if (fundResult.confirmation) {
+                    constraintWarnings.push(fundResult.confirmation.message);
+                    const fundHint = generateFundSkillsHint(fundResult.confirmation);
+                    if (fundHint)
+                        constraintWarnings.push(fundHint);
+                }
+                const orderAllocators = data?.order_allocators;
+                if (orderAllocators && typeof orderAllocators === "object") {
+                    const allocators = Array.isArray(orderAllocators.allocators)
+                        ? orderAllocators.allocators : [];
+                    for (let i = 0; i < allocators.length; i++) {
+                        const alloc = allocators[i];
+                        const sharing = Array.isArray(alloc?.sharing) ? alloc.sharing : [];
+                        if (sharing.length <= 1)
+                            continue;
+                        const seen = new Map();
+                        for (let j = 0; j < sharing.length; j++) {
+                            const who = sharing[j]?.who;
+                            let key = "";
+                            if (typeof who === "string") {
+                                key = who;
+                            }
+                            else if (who && typeof who === "object") {
+                                if (who.Entity && typeof who.Entity === "object") {
+                                    key = "Entity:" + (who.Entity.name_or_address ?? "");
+                                }
+                                else if (who.Signer) {
+                                    key = "Signer";
+                                }
+                                else if (who.GuardIdentifier !== undefined) {
+                                    key = "Guard:" + who.GuardIdentifier;
+                                }
+                                else {
+                                    key = JSON.stringify(who);
+                                }
+                            }
+                            if (!key)
+                                continue;
+                            const count = seen.get(key) ?? 0;
+                            seen.set(key, count + 1);
+                        }
+                        for (const [key, count] of seen) {
+                            if (count > 1) {
+                                constraintWarnings.push(`DUPLICATE SHARING ENTITY: Allocator[${i}] has entity "${key}" appearing ${count} times ` +
+                                    `in the sharing array. This is likely a configuration error — each entity should appear ` +
+                                    `at most once per allocator. Total sharing: ${count * 100}% to the same entity. ` +
+                                    `If intentional, ignore this warning.`);
+                            }
+                        }
+                    }
+                }
+                const callService = new CallService(validated.data);
+                let result;
+                try {
+                    result = validated.submission
+                        ? await callService.call_with_submission(env, await transformSubmission(validated.submission))
+                        : await callService.call(env);
+                }
+                catch (e) {
+                    const errMsg = e.message ?? String(e);
+                    if (/not found|GetObjectExisted|resolve|LocalMark|failed to resolve/i.test(errMsg)) {
+                        const permRef = (typeof data?.object === 'object' && data?.object !== null)
+                            ? data.object.permission
+                            : undefined;
+                        throw new Error(`DEPENDENCY RESOLUTION FAILED: One or more referenced objects could not be resolved.\n` +
+                            `Original error: ${errMsg}\n` +
+                            `Common causes:\n` +
+                            `  1. Object name typo — check spelling in LocalMark\n` +
+                            `  2. Object not yet created — create dependencies first\n` +
+                            `  3. Object on different network — check env.network\n` +
+                            `Referenced objects in this call: machine=${data?.machine ?? "<none>"}, ` +
+                            `buy_guard=${data?.buy_guard ?? "<none>"}, ` +
+                            `permission=${permRef ?? "<inline/new>"}, ` +
+                            `arbitrations=${Array.isArray(data?.arbitrations) ? data.arbitrations.length + " item(s)" : "<none>"}`);
+                    }
+                    throw e;
+                }
                 const intent = data?.publish ? "publish service" : data?.bPublished !== undefined ? "modify service" : "create service";
+                const isCreatingService = data?.object != null && typeof data.object === "object";
+                const hasCompensationFundAdd = data?.compensation_fund_add != null;
+                if (isCreatingService && !hasCompensationFundAdd) {
+                    constraintWarnings.push("Service.compensation_fund balance is 0 — no refund protection for buyers. " +
+                        "If buyers need refund protection, call service.compensation_fund_add with a Coin<T> " +
+                        "to deposit. Without deposit, arbitration rulings cannot withdraw compensation " +
+                        "from this Service. (Note: some industries like freelance do not require this; " +
+                        "the evaluation engine will check industry-specific requirements.)");
+                }
+                const isPublishing = data?.publish === true;
+                const hasArbitrations = Array.isArray(data?.arbitrations) && data.arbitrations.length > 0;
+                if (isPublishing && !hasArbitrations && hasCompensationFundAdd) {
+                    throw new Error("HARD PRE-CHECK FAILED: Cannot publish Service with compensation_fund > 0 but no Arbitration bound.\n" +
+                        "Contract (service.move:494): assert!(arbitration_count > 0, E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND).\n" +
+                        "The transaction WILL ABORT on-chain if you proceed.\n" +
+                        "Fix: (1) Create an Arbitration object first (onchain_operations with operation_type='arbitration').\n" +
+                        "     (2) Set data.arbitrations=[<arbitration_name_or_id>] in this same call.\n" +
+                        "     (3) Then call publish=true.\n" +
+                        "Note: After publish, arbitrations can still be ADDED (but not removed without pause+lock).");
+                }
+                if (isPublishing && !hasArbitrations && !hasCompensationFundAdd) {
+                    constraintWarnings.push("WARNING: Publishing Service without arbitrations. If compensation_fund was " +
+                        "deposited in a prior call, the contract (service.move:494) WILL ABORT with " +
+                        "E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND. If compensation_fund is 0, " +
+                        "publish will succeed but buyers have no dispute resolution path. " +
+                        "Recommended: bind arbitrations before publish.");
+                }
+                if (!isPublishing && hasCompensationFundAdd && !hasArbitrations) {
+                    constraintWarnings.push("WARNING: Depositing compensation_fund on a Service without arbitrations bound. " +
+                        "If this Service is already published, arbitration rulings will not be able to " +
+                        "withdraw compensation from this Service. Recommended: bind arbitrations first, " +
+                        "then deposit compensation_fund.");
+                }
                 const output = handleCallResult(result, withHarness(buildCtx(data), "service", intent));
                 autoAddToProject(projectEnvPrefix, validated.operation_type, result).catch(() => { });
                 return output;
@@ -123,6 +492,33 @@ export async function handleOnchainOperations(args) {
                         bReplace: true
                     };
                 }
+                const machineData = validated.data;
+                const permWarning = await checkMachinePermissionBeforePublish(machineData, env);
+                if (permWarning) {
+                    constraintWarnings.push(permWarning);
+                }
+                const machineNodes = machineData?.node?.nodes ?? machineData?.node;
+                if (Array.isArray(machineNodes)) {
+                    const arbPatterns = /^(dispute|disputed|arbitration|arb_|arb\.|resolve_dispute|start_arbitration|open_dispute)/i;
+                    for (const node of machineNodes) {
+                        const nodeName = typeof node === 'object' ? node?.name : '';
+                        if (typeof nodeName === 'string' && arbPatterns.test(nodeName)) {
+                            constraintWarnings.push(`ARBITRATION SEPARATION WARNING: Machine node "${nodeName}" appears to be an arbitration-related node.\n` +
+                                `CORE PRINCIPLE: A merchant cannot handle disputes fairly — they would be 'both player and referee'.\n` +
+                                `The WoWok smart contract design makes Arbitration a completely separate object:\n` +
+                                `  - Arbitration has its own Permission, voting_guard, usage_guard, and balance\n` +
+                                `  - Arb instances have a 7-state lifecycle managed by Arbitration, not by Machine\n` +
+                                `  - The Order object is the bridge: it has 'progress' (Machine) and 'dispute' (Arb list) fields\n` +
+                                `  - When Arb rules, it calls order::compensate() — the ONLY connection to the business flow\n\n` +
+                                `CORRECT PATTERN:\n` +
+                                `  - Machine: business states only (ordered -> shipped -> delivered -> refunded -> completed)\n` +
+                                `  - Arbitration: separate object with its own Permission (NOT shared with Service)\n` +
+                                `  - Arb: 7-state lifecycle (Principal_confirming -> Arbitrator_confirming -> Voting -> Arbitrated -> Objectionable -> Finished -> Withdrawn)\n` +
+                                `  - Use 'refunded'/'cancelled' nodes for the BUSINESS OUTCOME of a dispute, not 'disputed'\n\n` +
+                                `If this node name is a legitimate business state (not arbitration), ignore this warning.`);
+                        }
+                    }
+                }
                 const callMachine = new CallMachine(validated.data);
                 const result = validated.submission
                     ? await callMachine.call_with_submission(env, await transformSubmission(validated.submission))
@@ -143,6 +539,65 @@ export async function handleOnchainOperations(args) {
                 const result = validated.submission
                     ? await callProgress.call_with_submission(env, await transformSubmission(validated.submission))
                     : await callProgress.call(env);
+                if (!validated.submission && result && typeof result === 'object' && 'submission' in result) {
+                    const submissionData = result.submission;
+                    if (Array.isArray(submissionData) && submissionData.length > 0) {
+                        const guardRef = submissionData[0]?.guard;
+                        if (guardRef) {
+                            const submissionCtx = {
+                                operation: "progress_next",
+                                network: env?.network,
+                                signer: env?.account,
+                                progress_address: validated.data?.object,
+                                order_address: validated.data?.task,
+                            };
+                            const prompt = await generateGuardSubmissionPrompt(guardRef, submissionCtx);
+                            if (prompt) {
+                                constraintWarnings.push(formatSubmissionPrompt(prompt));
+                            }
+                        }
+                    }
+                }
+                if (result && typeof result === 'object' && 'digest' in result
+                    && result?.effects?.status?.status === 'success') {
+                    try {
+                        const progressRef = validated.data?.object;
+                        let progressAddr;
+                        if (typeof progressRef === 'string') {
+                            if (progressRef.startsWith('0x')) {
+                                progressAddr = progressRef;
+                            }
+                            else {
+                                progressAddr = await LocalMark.Instance().get_address(progressRef) ?? undefined;
+                            }
+                        }
+                        if (progressAddr) {
+                            const progressQuery = await query_objects({
+                                objects: [progressAddr],
+                                no_cache: true,
+                                network: env?.network,
+                            });
+                            const progressObj = progressQuery?.objects?.[0];
+                            if (progressObj?.type === "Progress") {
+                                const currentNode = progressObj.current ?? "<unknown>";
+                                const historyCount = Array.isArray(progressObj.session)
+                                    ? progressObj.session.length : 0;
+                                const machineAddr = progressObj.machine;
+                                const previewLines = [
+                                    `PROGRESS PREVIEW:`,
+                                    `  • current node: "${currentNode}"`,
+                                    `  • history count: ${historyCount} session(s)`,
+                                ];
+                                if (machineAddr) {
+                                    previewLines.push(`  • machine: ${machineAddr}`);
+                                }
+                                constraintWarnings.push(previewLines.join("\n"));
+                            }
+                        }
+                    }
+                    catch {
+                    }
+                }
                 const output = handleCallResult(result, buildCtx(validated.data));
                 autoAddToProject(projectEnvPrefix, validated.operation_type, result).catch(() => { });
                 return output;
@@ -157,6 +612,14 @@ export async function handleOnchainOperations(args) {
                 return output;
             }
             case "arbitration": {
+                const arbFundResult = await processFundOperation(validated.data, "arbitration", env?.network);
+                constraintWarnings.push(...arbFundResult.warnings);
+                if (arbFundResult.confirmation) {
+                    constraintWarnings.push(arbFundResult.confirmation.message);
+                    const fundHint = generateFundSkillsHint(arbFundResult.confirmation);
+                    if (fundHint)
+                        constraintWarnings.push(fundHint);
+                }
                 const callArbitration = new CallArbitration(validated.data);
                 const result = validated.submission
                     ? await callArbitration.call_with_submission(env, await transformSubmission(validated.submission))
@@ -175,6 +638,14 @@ export async function handleOnchainOperations(args) {
                 return output;
             }
             case "treasury": {
+                const trFundResult = await processFundOperation(validated.data, "treasury", env?.network);
+                constraintWarnings.push(...trFundResult.warnings);
+                if (trFundResult.confirmation) {
+                    constraintWarnings.push(trFundResult.confirmation.message);
+                    const fundHint = generateFundSkillsHint(trFundResult.confirmation);
+                    if (fundHint)
+                        constraintWarnings.push(fundHint);
+                }
                 const callTreasury = new CallTreasury(validated.data);
                 const result = validated.submission
                     ? await callTreasury.call_with_submission(env, await transformSubmission(validated.submission))
@@ -184,6 +655,14 @@ export async function handleOnchainOperations(args) {
                 return output;
             }
             case "reward": {
+                const rwFundResult = await processFundOperation(validated.data, "reward", env?.network);
+                constraintWarnings.push(...rwFundResult.warnings);
+                if (rwFundResult.confirmation) {
+                    constraintWarnings.push(rwFundResult.confirmation.message);
+                    const fundHint = generateFundSkillsHint(rwFundResult.confirmation);
+                    if (fundHint)
+                        constraintWarnings.push(fundHint);
+                }
                 const transformedData = transformRewardInput(validated.data);
                 const callReward = new CallReward(transformedData);
                 const result = validated.submission
@@ -198,6 +677,51 @@ export async function handleOnchainOperations(args) {
                 const result = validated.submission
                     ? await callAllocation.call_with_submission(env, await transformSubmission(validated.submission))
                     : await callAllocation.call(env);
+                const allocData = validated.data;
+                if (allocData?.alloc_by_guard) {
+                    const createdPayments = ResponseData(result).filter((e) => e?.type === "Payment" && e?.change === "created");
+                    if (createdPayments.length > 0) {
+                        const paymentAddrs = createdPayments.map((p) => p.object).join(", ");
+                        try {
+                            const paymentResult = await query_objects({
+                                objects: createdPayments.map((p) => p.object),
+                                no_cache: true,
+                                network: env?.network,
+                            });
+                            const distributionLines = [];
+                            let totalDistributed = BigInt(0);
+                            for (const obj of paymentResult?.objects || []) {
+                                if (obj?.type === "Payment" && obj?.record) {
+                                    for (const entry of obj.record) {
+                                        const recipientLabel = formatRecipientLabel(entry.recipient);
+                                        const amountStr = typeof entry.amount === 'string' ? entry.amount : String(entry.amount);
+                                        const amountBig = BigInt(amountStr);
+                                        totalDistributed += amountBig;
+                                        distributionLines.push(`  • ${recipientLabel}: ${formatMistAmount(amountBig)}`);
+                                    }
+                                    if (obj.object) {
+                                        distributionLines.push(`  • Payment object: ${obj.object}`);
+                                    }
+                                }
+                            }
+                            if (distributionLines.length > 0) {
+                                distributionLines.unshift(`DISTRIBUTION DETAILS (alloc_by_guard):`);
+                                distributionLines.push(`  ─────────────────`, `  • Total distributed: ${formatMistAmount(totalDistributed)}`);
+                                const isEscrow = paymentResult?.objects?.some((obj) => obj?.type === "Payment" && obj?.info?.for_object);
+                                if (isEscrow) {
+                                    distributionLines.push(``, `ESCROW MODE: Funds are held in escrow (Payment.for_object points to an Order). ` +
+                                        `The Order owner must call order_claim (or service_order_claim) to actually receive the funds. ` +
+                                        `This happens when the Guard's sharing config uses { GuardIdentifier: 0 }.`);
+                                }
+                                constraintWarnings.push(distributionLines.join("\n"));
+                            }
+                        }
+                        catch {
+                            constraintWarnings.push(`alloc_by_guard created Payment object(s) [${paymentAddrs}]. ` +
+                                `Query these Payment objects to see the distribution details and check for_object for escrow mode.`);
+                        }
+                    }
+                }
                 const output = handleCallResult(result, buildCtx(validated.data));
                 autoAddToProject(projectEnvPrefix, validated.operation_type, result).catch(() => { });
                 return output;
@@ -259,6 +783,34 @@ export async function handleOnchainOperations(args) {
                 }
                 const callGuard = new CallGuard(validatedData);
                 const result = await callGuard.call(env);
+                if (result && typeof result === 'object' && 'digest' in result
+                    && result?.effects?.status?.status === 'success') {
+                    try {
+                        const rootType = validatedData.root?.type ?? "<unknown>";
+                        const tableArr = Array.isArray(validatedData.table) ? validatedData.table : [];
+                        const tableEntries = tableArr.length;
+                        const submissionEntries = tableArr.filter((t) => t?.b_submission === true).length;
+                        const relyGuards = validatedData.rely?.guards;
+                        const relyCount = Array.isArray(relyGuards) ? relyGuards.length : 0;
+                        const relyMode = validatedData.rely?.logic_or === true
+                            ? "OR" : validatedData.rely?.logic_or === false ? "AND" : "none";
+                        const summaryLines = [
+                            `GUARD LOGIC SUMMARY:`,
+                            `  • root type: ${rootType}`,
+                            `  • table entries: ${tableEntries} (${submissionEntries} require runtime submission)`,
+                        ];
+                        if (relyCount > 0) {
+                            summaryLines.push(`  • relies on: ${relyCount} guard(s) (mode: ${relyMode})`);
+                        }
+                        if (validatedData.description) {
+                            const desc = String(validatedData.description).slice(0, 80);
+                            summaryLines.push(`  • description: "${desc}"`);
+                        }
+                        constraintWarnings.push(summaryLines.join("\n"));
+                    }
+                    catch {
+                    }
+                }
                 const output = handleCallResult(result, buildCtx(validated.data));
                 autoAddToProject(projectEnvPrefix, validated.operation_type, result).catch(() => { });
                 return output;
@@ -272,6 +824,37 @@ export async function handleOnchainOperations(args) {
                 return output;
             }
             case "payment": {
+                const payFundResult = await processFundOperation(validated.data, "payment", env?.network);
+                constraintWarnings.push(...payFundResult.warnings);
+                if (payFundResult.confirmation) {
+                    constraintWarnings.push(payFundResult.confirmation.message);
+                    const fundHint = generateFundSkillsHint(payFundResult.confirmation);
+                    if (fundHint)
+                        constraintWarnings.push(fundHint);
+                }
+                const paymentData = validated.data;
+                if (paymentData?.receive === true) {
+                    constraintWarnings.push("RECEIVE MODE (order_claim): You are unwrapping a CoinWrapper to your wallet. " +
+                        "This is the final step of the escrow flow:\n" +
+                        "  1. Allocation's alloc_by_guard created a Payment object with your address as a recipient\n" +
+                        "  2. The Payment's revenue split transferred a CoinWrapper to your wallet (owned but not spendable)\n" +
+                        "  3. THIS operation unwraps the CoinWrapper via payment::unwrap_to_myself, deleting the " +
+                        "CoinWrapper and transferring the underlying coin to tx_context::sender\n" +
+                        "Requirements:\n" +
+                        "  - You MUST be the CoinWrapper's owner (the recipient specified in the Allocation)\n" +
+                        "  - type_parameter MUST match the coin type used when the Allocation created the Payment " +
+                        "(e.g. '0x2::wow::WOW')\n" +
+                        "  - object can be a CoinWrapper ID (0x...) or a local mark name\n" +
+                        "To find received CoinWrappers: call query_toolkit with query_type='onchain_received' " +
+                        "and type='CoinWrapper' for your account.\n" +
+                        "After success: verify your balance increased via account_balance query.");
+                }
+                else if (paymentData?.revenue) {
+                    constraintWarnings.push("CREATE MODE: Creating a new Payment object. Payments are IMMUTABLE after creation — " +
+                        "they cannot be modified. The 'revenue' array defines the recipients and amounts; " +
+                        "ensure correctness before submitting. The 'info.for_guard' field (if set) binds this " +
+                        "Payment to a Guard for conditional release (common in escrow workflows).");
+                }
                 const callPayment = new CallPayment(validated.data);
                 const result = await callPayment.call(env);
                 const output = handleCallResult(result, buildCtx(validated.data));
@@ -293,6 +876,11 @@ export async function handleOnchainOperations(args) {
                         "namedOperator=\"\" (OrderHolder). If the target Forward uses a " +
                         "non-empty namedOperator or permissionIndex-only, use progress.operate " +
                         "on the Progress object directly instead.");
+                    constraintWarnings.push("Allocation hint: if this operation advances the order to a terminal " +
+                        "state (e.g. Completed/Cancelled/Refunded), funds remain in the " +
+                        "Allocation object and are NOT auto-distributed. To release funds, " +
+                        "trigger the corresponding Guard verification via allocation operation " +
+                        "(the Guard bound to the matching Allocator will verify and distribute).");
                 }
                 const callOrder = new CallOrder(validated.data);
                 const result = validated.submission