@wowok/agent-mcp 2.3.12 → 2.3.14

package/dist/schema/call/semantic.js

@@ -0,0 +1,764 @@
+const ERROR_RULES = [
+    {
+        patterns: [/insufficient\s*(gas|balance|coin|fund)/i, /ENOTENOUGH/i, /not\s*enough\s*(coin|gas|balance)/i, /gas\s*budget/i],
+        error_code: "insufficient_balance",
+        retryable: true,
+        recovery_hint: "Claim faucet tokens via account_operation (faucet) then retry the call",
+    },
+    {
+        patterns: [/network/i, /timeout/i, /ECONNRESET/i, /ETIMEDOUT/i, /RPC\s*(error|failed|unreachable)/i, /socket\s*hang\s*up/i, /fetch\s*failed/i],
+        error_code: "network_error",
+        retryable: true,
+        recovery_hint: "Retry the call; if it persists, switch RPC endpoint or check connectivity",
+    },
+    {
+        patterns: [/guard.*(reject|fail|denied)/i, /verification\s*failed/i, /submission.*(invalid|fail|required)/i, /passport.*(invalid|fail)/i, /move[._-]?abort.*guard/i],
+        error_code: "guard_rejected",
+        retryable: false,
+        recovery_hint: "Fill the Guard submission data (see the 'submission' field) and resubmit via call_with_submission",
+    },
+    {
+        patterns: [/already\s*publish/i, /immutable/i, /cannot\s*(modify|change|mutate)/i, /locked/i, /is\s*published/i],
+        error_code: "immutable_violation",
+        retryable: false,
+        recovery_hint: "Object is in an immutable state (e.g. Service already published). Recreate the object if a different config is needed",
+    },
+    {
+        patterns: [/permission/i, /unauthorized/i, /forbidden/i, /not\s*(the\s*)?owner/i, /access\s*denied/i],
+        error_code: "permission_denied",
+        retryable: false,
+        recovery_hint: "Use an account with the required permission, or pass permission_guard IDs via env.permission_guard",
+    },
+    {
+        patterns: [/not\s*found/i, /does\s*not\s*exist/i, /ENOTFOUND/i, /no\s*such\s*object/i, /unknown\s*object/i],
+        error_code: "object_not_found",
+        retryable: false,
+        recovery_hint: "Verify the object ID/name with query_toolkit; local_mark names are case-sensitive",
+    },
+    {
+        patterns: [/state\s*(conflict|mismatch)/i, /already\s*exist/i, /conflict/i, /duplicate/i, /version\s*mismatch/i],
+        error_code: "state_conflict",
+        retryable: false,
+        recovery_hint: "Object state conflicts with the operation. Query the current state with query_toolkit and adjust parameters",
+    },
+    {
+        patterns: [/invalid/i, /missing\s*(field|param|required)/i, /required/i, /expected/i, /malformed/i, /parse\s*error/i, /type\s*mismatch/i],
+        error_code: "invalid_parameter",
+        retryable: false,
+        recovery_hint: "Check parameter format against the tool schema; consult wowok-tools Skill for the operation's requirements",
+    },
+];
+export function classifyError(errorMsg) {
+    if (!errorMsg) {
+        return { error_code: "unknown", retryable: false };
+    }
+    for (const rule of ERROR_RULES) {
+        if (rule.patterns.some((p) => p.test(errorMsg))) {
+            return {
+                error_code: rule.error_code,
+                retryable: rule.retryable,
+                recovery_hint: rule.recovery_hint,
+            };
+        }
+    }
+    return {
+        error_code: "unknown",
+        retryable: false,
+        recovery_hint: "Inspect the full error message; consult wowok-tools Skill for the operation's requirements",
+    };
+}
+const INTENT_RULES = [
+    { operation_type: "service", signals: (d) => d?.publish === true, intent: "publish_service", confidence: 0.95 },
+    { operation_type: "service", signals: (d) => d?.name && d?.publish === undefined, intent: "create_service", confidence: 0.9 },
+    { operation_type: "service", intent: "modify_service", confidence: 0.7 },
+    { operation_type: "machine", intent: "configure_machine", confidence: 0.9 },
+    { operation_type: "progress", intent: "update_progress", confidence: 0.9 },
+    { operation_type: "order", signals: (d) => !!d?.arb, intent: "apply_arbitration", confidence: 0.9 },
+    { operation_type: "order", intent: "manage_order", confidence: 0.85 },
+    { operation_type: "payment", intent: "send_payment", confidence: 0.95 },
+    { operation_type: "reward", intent: "manage_reward", confidence: 0.9 },
+    { operation_type: "demand", intent: "post_demand", confidence: 0.9 },
+    { operation_type: "treasury", intent: "manage_treasury", confidence: 0.9 },
+    { operation_type: "allocation", intent: "allocate_funds", confidence: 0.9 },
+    { operation_type: "permission", intent: "manage_permission", confidence: 0.9 },
+    { operation_type: "guard", intent: "configure_guard", confidence: 0.9 },
+    { operation_type: "arbitration", intent: "manage_arbitration", confidence: 0.9 },
+    { operation_type: "contact", intent: "manage_contact", confidence: 0.9 },
+    { operation_type: "repository", intent: "manage_repository", confidence: 0.9 },
+    { operation_type: "personal", intent: "manage_personal", confidence: 0.9 },
+    { operation_type: "gen_passport", intent: "generate_passport", confidence: 0.95 },
+    { operation_type: "bridge_cross_chain_wow_to_evm", intent: "cross_chain_wow_to_evm_deposit", confidence: 0.95 },
+    { operation_type: "bridge_cross_chain_evm_to_wow", intent: "cross_chain_evm_to_wow_deposit", confidence: 0.95 },
+    { operation_type: "bridge_claim_wow_to_evm", intent: "claim_wow_to_evm", confidence: 0.95 },
+    { operation_type: "bridge_withdraw", intent: "withdraw_from_evm_account", confidence: 0.9 },
+    { operation_type: "bridge_query_active_evm_account", intent: "query_bridge_status", confidence: 0.85 },
+    { operation_type: "bridge_query_supported_evm_chains", intent: "query_bridge_status", confidence: 0.85 },
+    { operation_type: "bridge_query_supported_tokens", intent: "query_bridge_status", confidence: 0.85 },
+    { operation_type: "bridge_query_transfer_list", intent: "query_bridge_status", confidence: 0.85 },
+    { operation_type: "bridge_query_transfer_status", intent: "query_bridge_status", confidence: 0.85 },
+    { operation_type: "bridge_manage_evm_rpc", intent: "manage_evm_rpc", confidence: 0.9 },
+    { operation_type: "account_new", intent: "create_account", confidence: 0.95 },
+    { operation_type: "account_faucet", intent: "claim_faucet", confidence: 0.95 },
+    { operation_type: "account_balance", intent: "query_balance", confidence: 0.9 },
+    { operation_type: "mark_add", intent: "create_local_mark", confidence: 0.9 },
+    { operation_type: "mark_remove", intent: "remove_local_mark", confidence: 0.9 },
+    { operation_type: "mark_query", intent: "query_local_marks", confidence: 0.9 },
+    { operation_type: "local_info", intent: "query_local_info", confidence: 0.9 },
+    { operation_type: "query_toolkit", intent: "query_objects", confidence: 0.85 },
+    { operation_type: "onchain_events", intent: "query_events", confidence: 0.85 },
+    { operation_type: "onchain_table_data", intent: "query_table_data", confidence: 0.85 },
+];
+export function inferIntent(operation_type, data) {
+    const rules = INTENT_RULES.filter((r) => r.operation_type === operation_type);
+    const signaled = rules.find((r) => r.signals && r.signals(data));
+    if (signaled)
+        return signaled.intent;
+    const fallback = rules.find((r) => !r.signals);
+    return fallback?.intent ?? operation_type;
+}
+function inferStatus(safeResult) {
+    if (safeResult && typeof safeResult === "object" && "error" in safeResult)
+        return "failed";
+    if (safeResult && typeof safeResult === "object" && "digest" in safeResult) {
+        return safeResult?.effects?.status?.status === "success" ? "success" : "failed";
+    }
+    return "success";
+}
+const OBJECT_TYPE_TO_ROLE = {
+    service: "Service",
+    machine: "Machine",
+    progress: "Progress",
+    permission: "Permission",
+    guard: "Guard",
+    order: "Order",
+    arb: "Arbitration",
+    arbcase: "ArbCase",
+    messenger: "Messenger",
+    contact: "Contact",
+    demand: "Demand",
+    reward: "Reward",
+    personal: "Personal",
+    repository: "Repository",
+    treasury: "Treasury",
+    discount: "Discount",
+    allocation: "Allocation",
+};
+export function objectTypeToRole(objectType) {
+    if (!objectType)
+        return "Other";
+    const base = objectType.replace(/<.*>/, "").trim();
+    const segments = base.split("::");
+    const last = (segments[segments.length - 1] || "").toLowerCase();
+    return OBJECT_TYPE_TO_ROLE[last] ?? "Other";
+}
+export function tagObjectRoles(objectChanges) {
+    if (!Array.isArray(objectChanges))
+        return [];
+    return objectChanges
+        .filter((c) => c && (c.objectId || c.object?.objectId))
+        .map((c) => {
+        const id = c.objectId || c.object?.objectId;
+        const type = c.objectType || c.object?.objectType || "";
+        const changeType = c.type || "";
+        return {
+            id,
+            role: objectTypeToRole(type),
+            immutable: type.includes("Service") && changeType === "published",
+        };
+    });
+}
+const GAS_COIN_PATTERNS = [/::sui::SUI$/i, /::wow::WOW$/i];
+const SMALL_AMOUNT_THRESHOLD = BigInt(1_000_000);
+function isNegative(amount) {
+    return String(amount ?? "0").startsWith("-");
+}
+function hasEventMatch(events, pattern) {
+    if (!Array.isArray(events))
+        return false;
+    return events.some((e) => pattern.test(String(e?.type ?? e?.event_type ?? "")));
+}
+function isGasCoin(coinType) {
+    if (!coinType)
+        return false;
+    return GAS_COIN_PATTERNS.some((p) => p.test(coinType));
+}
+function absAmount(amount) {
+    try {
+        return BigInt(String(amount).replace("-", "") || "0");
+    }
+    catch {
+        return BigInt(0);
+    }
+}
+const FUND_ROLE_RULES = [
+    {
+        when: (ctx) => hasEventMatch(ctx.events, /order::OrderPaidEvent/i),
+        role: "payment",
+        confidence: 0.95,
+    },
+    {
+        when: (ctx) => hasEventMatch(ctx.events, /order::OrderRefundedEvent|order::RefundEvent/i),
+        role: "refund",
+        confidence: 0.95,
+    },
+    {
+        when: (ctx) => hasEventMatch(ctx.events, /reward::RewardClaimedEvent|reward::ClaimedEvent/i),
+        role: "reward",
+        confidence: 0.95,
+    },
+    {
+        when: (ctx) => hasEventMatch(ctx.events, /arbitration::CompensationEvent|arbitration::RefundEvent/i),
+        role: "compensation",
+        confidence: 0.9,
+    },
+    {
+        when: (ctx) => hasEventMatch(ctx.events, /treasury::DepositEvent/i),
+        role: "deposit",
+        confidence: 0.95,
+    },
+    {
+        when: (ctx) => hasEventMatch(ctx.events, /treasury::WithdrawEvent|treasury::ReleaseEvent/i),
+        role: "release",
+        confidence: 0.9,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "payment" && isNegative(ctx.amount),
+        role: "payment",
+        confidence: 0.95,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "payment" && !isNegative(ctx.amount),
+        role: "refund",
+        confidence: 0.9,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "reward" && isNegative(ctx.amount),
+        role: "reward",
+        confidence: 0.95,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "reward" && !isNegative(ctx.amount),
+        role: "release",
+        confidence: 0.9,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "treasury" && isNegative(ctx.amount),
+        role: "deposit",
+        confidence: 0.95,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "treasury" && !isNegative(ctx.amount),
+        role: "release",
+        confidence: 0.9,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "allocation" && isNegative(ctx.amount),
+        role: "payment",
+        confidence: 0.85,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "allocation" && !isNegative(ctx.amount),
+        role: "release",
+        confidence: 0.85,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "arbitration" && (ctx.data?.compensation !== undefined || ctx.data?.arb === true),
+        role: "compensation",
+        confidence: 0.9,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "order" && isNegative(ctx.amount) && ctx.data?.buy !== undefined,
+        role: "payment",
+        confidence: 0.9,
+    },
+    {
+        when: (ctx) => ctx.operation_type === "order" && !isNegative(ctx.amount) && (ctx.data?.refund !== undefined || ctx.data?.arb !== undefined),
+        role: "refund",
+        confidence: 0.85,
+    },
+    {
+        when: (ctx) => {
+            if (isNegative(ctx.amount))
+                return false;
+            const amt = absAmount(ctx.amount);
+            return isGasCoin(ctx.coinType) && amt > BigInt(0) && amt < SMALL_AMOUNT_THRESHOLD;
+        },
+        role: "gas",
+        confidence: 0.7,
+    },
+    {
+        when: (ctx) => {
+            if (isNegative(ctx.amount))
+                return false;
+            return ctx.sender !== undefined && ctx.recipient !== undefined && ctx.sender === ctx.recipient && ctx.sender !== "";
+        },
+        role: "change",
+        confidence: 0.7,
+    },
+    {
+        when: (ctx) => isNegative(ctx.amount),
+        role: "payment",
+        confidence: 0.7,
+    },
+    {
+        when: (ctx) => !isNegative(ctx.amount) && absAmount(ctx.amount) === BigInt(0),
+        role: "other",
+        confidence: 0.5,
+    },
+    {
+        when: (ctx) => !isNegative(ctx.amount),
+        role: "release",
+        confidence: 0.7,
+    },
+    {
+        when: () => true,
+        role: "other",
+        confidence: 0.3,
+    },
+];
+export function tagFundRoles(balanceChanges, operation_type, data, events) {
+    if (!Array.isArray(balanceChanges))
+        return [];
+    return balanceChanges
+        .filter((c) => c && (c.amount !== undefined || c.coinType))
+        .map((c) => {
+        const ctx = {
+            operation_type,
+            amount: String(c.amount ?? "0"),
+            coinType: c.coinType,
+            data: data ?? {},
+            events,
+            sender: c.sender,
+            recipient: c.recipient,
+        };
+        const rule = FUND_ROLE_RULES.find((r) => r.when(ctx));
+        const role = rule?.role ?? "other";
+        return {
+            amount: ctx.amount,
+            coinType: c.coinType || "",
+            role,
+            from: c.sender ?? null,
+            to: c.recipient ?? null,
+        };
+    });
+}
+const EVENT_SEMANTIC_RULES = [
+    {
+        pattern: /::service::ServiceCreatedEvent/i,
+        business_meaning: "A new Service was created (not yet published)",
+        category: "lifecycle",
+        side_effect: "Service exists in draft state; configure Machine and publish when ready",
+    },
+    {
+        pattern: /::service::ServicePublishedEvent/i,
+        business_meaning: "Service has been published and is now immutable",
+        category: "lifecycle",
+        side_effect: "Customers can now place orders against this Service",
+    },
+    {
+        pattern: /::service::ServiceModifiedEvent/i,
+        business_meaning: "Service configuration was modified",
+        category: "state_change",
+    },
+    {
+        pattern: /::machine::MachineCreatedEvent/i,
+        business_meaning: "A new Machine (workflow template) was created",
+        category: "lifecycle",
+    },
+    {
+        pattern: /::machine::MachineBoundEvent/i,
+        business_meaning: "Machine was bound to a Service",
+        category: "state_change",
+        side_effect: "Orders placed on this Service will follow the Machine's state graph",
+    },
+    {
+        pattern: /::machine::MachinePublishedEvent/i,
+        business_meaning: "Machine was published and is now immutable",
+        category: "lifecycle",
+    },
+    {
+        pattern: /::order::OrderCreatedEvent/i,
+        business_meaning: "A new Order was placed by a customer",
+        category: "lifecycle",
+        side_effect: "Order is pending payment; merchant should await payment before proceeding",
+    },
+    {
+        pattern: /::order::OrderPaidEvent/i,
+        business_meaning: "Order has been paid by the customer",
+        category: "fund_flow",
+        side_effect: "Funds are escrowed; merchant can advance the order to delivery",
+    },
+    {
+        pattern: /::order::OrderAdvancedEvent/i,
+        business_meaning: "Order advanced to the next state in the Machine graph",
+        category: "state_change",
+    },
+    {
+        pattern: /::order::OrderCompletedEvent/i,
+        business_meaning: "Order has been completed",
+        category: "lifecycle",
+        side_effect: "Allocation can be executed to distribute funds to recipients",
+    },
+    {
+        pattern: /::order::OrderRefundedEvent|::order::RefundEvent/i,
+        business_meaning: "Order was refunded",
+        category: "fund_flow",
+        side_effect: "Escrowed funds returned to the customer",
+    },
+    {
+        pattern: /::order::OrderCancelledEvent/i,
+        business_meaning: "Order was cancelled",
+        category: "lifecycle",
+    },
+    {
+        pattern: /::reward::RewardCreatedEvent/i,
+        business_meaning: "A new Reward pool was created",
+        category: "lifecycle",
+    },
+    {
+        pattern: /::reward::RewardClaimedEvent|::reward::ClaimedEvent/i,
+        business_meaning: "Reward was claimed by a claimant",
+        category: "fund_flow",
+        side_effect: "Funds transferred from the reward pool to the claimant",
+    },
+    {
+        pattern: /::treasury::DepositEvent/i,
+        business_meaning: "Funds were deposited into the Treasury",
+        category: "fund_flow",
+    },
+    {
+        pattern: /::treasury::WithdrawEvent|::treasury::ReleaseEvent/i,
+        business_meaning: "Funds were withdrawn from the Treasury",
+        category: "fund_flow",
+    },
+    {
+        pattern: /::demand::DemandCreatedEvent/i,
+        business_meaning: "A new Demand (bounty) was posted",
+        category: "lifecycle",
+    },
+    {
+        pattern: /::demand::PresenterSubmittedEvent|::demand::PresentedEvent/i,
+        business_meaning: "A presenter submitted a solution for the Demand",
+        category: "state_change",
+    },
+    {
+        pattern: /::permission::PermissionGrantedEvent/i,
+        business_meaning: "Permission was granted to an address",
+        category: "permission",
+    },
+    {
+        pattern: /::permission::PermissionRevokedEvent/i,
+        business_meaning: "Permission was revoked from an address",
+        category: "permission",
+    },
+    {
+        pattern: /::guard::GuardRejectedEvent|::guard::RejectedEvent/i,
+        business_meaning: "Guard verification rejected the operation",
+        category: "guard",
+        side_effect: "Operation was blocked; user must satisfy the Guard's submission requirements",
+    },
+    {
+        pattern: /::guard::GuardPassedEvent|::guard::AcceptedEvent/i,
+        business_meaning: "Guard verification passed",
+        category: "guard",
+    },
+    {
+        pattern: /::arbitration::ArbitrationRequestedEvent|::arbitration::RequestedEvent/i,
+        business_meaning: "Arbitration was requested for an Order",
+        category: "state_change",
+        side_effect: "Order is now in dispute; arbiter will rule on the outcome",
+    },
+    {
+        pattern: /::arbitration::ArbitrationResolvedEvent|::arbitration::ResolvedEvent|::arbitration::CompensationEvent/i,
+        business_meaning: "Arbitration was resolved (compensation or refund awarded)",
+        category: "fund_flow",
+        side_effect: "Funds redistributed per arbiter's ruling",
+    },
+    {
+        pattern: /::allocation::AllocatedEvent|::allocation::DistributedEvent/i,
+        business_meaning: "Funds were distributed to allocation recipients",
+        category: "fund_flow",
+    },
+    {
+        pattern: /::progress::ProgressUpdatedEvent|::progress::UpdatedEvent/i,
+        business_meaning: "Order progress was updated",
+        category: "state_change",
+    },
+];
+function extractRelatedObject(event) {
+    if (!event || typeof event !== "object")
+        return undefined;
+    const fields = event.fields ?? event.payload ?? event;
+    if (typeof fields !== "object")
+        return undefined;
+    for (const key of ["object_id", "objectId", "id", "parent", "service", "order", "machine", "reward", "treasury"]) {
+        const v = fields[key];
+        if (typeof v === "string" && v.startsWith("0x") && v.length >= 6)
+            return v;
+    }
+    return undefined;
+}
+export function eventToSemantic(event) {
+    const eventType = String(event?.type ?? event?.event_type ?? "");
+    const rule = EVENT_SEMANTIC_RULES.find((r) => r.pattern.test(eventType));
+    if (!rule) {
+        return {
+            event_type: eventType,
+            business_meaning: "Unknown event",
+            category: "other",
+        };
+    }
+    const related = rule.extractRelatedObject ? rule.extractRelatedObject(event) : extractRelatedObject(event);
+    const result = {
+        event_type: eventType,
+        business_meaning: rule.business_meaning,
+        category: rule.category,
+    };
+    if (related)
+        result.related_object = related;
+    if (rule.side_effect)
+        result.side_effect = rule.side_effect;
+    return result;
+}
+export function annotateEvents(events) {
+    if (!Array.isArray(events))
+        return [];
+    return events.map(eventToSemantic);
+}
+const NEXT_ACTION_RULES = [
+    {
+        when: (ot) => ot === "service",
+        action: "publish the Service when configuration is complete",
+        reason: "Service must be published before customers can order",
+        tool: "onchain_operations (service with publish:true)",
+        priority: "recommended",
+    },
+    {
+        when: (ot) => ot === "service",
+        action: "add Machine nodes to define the service workflow",
+        reason: "Machine drives order state transitions",
+        tool: "onchain_operations (machine)",
+        priority: "recommended",
+    },
+    {
+        when: (ot) => ot === "machine",
+        action: "bind Progress to track order execution",
+        reason: "Progress provides customer-visible status updates",
+        tool: "onchain_operations (progress)",
+        priority: "recommended",
+    },
+    {
+        when: (ot) => ot === "order",
+        action: "wait for customer payment or proceed to allocation",
+        reason: "Order lifecycle: payment → allocation → completion",
+        priority: "optional",
+    },
+    {
+        when: (ot) => ot === "demand",
+        action: "wait for presenter submissions or evaluate existing ones",
+        reason: "Demand lifecycle: presenters submit solutions for reward",
+        priority: "optional",
+    },
+    {
+        when: (ot) => ot === "reward",
+        action: "deposit funds into the reward pool",
+        reason: "Reward pool must be funded before claimants can withdraw",
+        tool: "onchain_operations (treasury)",
+        priority: "recommended",
+    },
+    {
+        when: (ot) => ot === "bridge_cross_chain_wow_to_evm",
+        action: "poll query_transfer_status until bridge signs (~1-5 min), then call claim_wow_to_evm to complete",
+        reason: "Cross-chain WOW→EVM is a 2-step process: deposit first, then claim after bridge confirmation",
+        tool: "bridge_operation (query_transfer_status, then claim_wow_to_evm)",
+        priority: "required",
+    },
+    {
+        when: (ot) => ot === "bridge_cross_chain_evm_to_wow",
+        action: "poll query_transfer_status to monitor auto-claim progress (~10-20 min)",
+        reason: "EVM→WOW cross-chain auto-claims; monitor progress but no manual action needed",
+        tool: "bridge_operation (query_transfer_status)",
+        priority: "recommended",
+    },
+    {
+        when: (ot) => ot === "bridge_claim_wow_to_evm",
+        action: "verify recipient EVM balance updated",
+        reason: "Claim completes the cross-chain transfer; verify funds arrived on EVM side",
+        tool: "bridge_operation (query_active_evm_account)",
+        priority: "recommended",
+    },
+    {
+        when: (ot) => ot === "bridge_withdraw",
+        action: "verify WOW balance updated",
+        reason: "Withdrawal moves funds from active EVM account to WOW; verify balance",
+        tool: "account_operation (balance)",
+        priority: "recommended",
+    },
+    {
+        when: (ot) => ot === "account_new",
+        action: "claim faucet tokens for gas if on testnet, then proceed to create Service",
+        reason: "New account needs gas tokens before on-chain operations",
+        tool: "account_operation (faucet)",
+        priority: "recommended",
+    },
+    {
+        when: (ot) => ot === "account_faucet",
+        action: "proceed to create Permission and Service objects",
+        reason: "Account is now funded; start building your service",
+        tool: "onchain_operations (permission, service)",
+        priority: "recommended",
+    },
+    {
+        when: (ot) => ot === "query_toolkit",
+        action: "use the queried object data to plan next operations",
+        reason: "Query results reveal current object states for decision-making",
+        priority: "optional",
+    },
+];
+function inferNextActions(operation_type, data, status) {
+    return NEXT_ACTION_RULES
+        .filter((r) => r.when(operation_type, data, status))
+        .map((r) => ({
+        action: r.action,
+        reason: r.reason,
+        tool: r.tool,
+        priority: r.priority,
+    }));
+}
+function inferWarnings(operation_type, data, _safeResult) {
+    const warnings = [];
+    if (operation_type === "service" && data?.order_allocators === undefined) {
+        warnings.push("order_allocators not configured; order funds cannot be distributed automatically");
+    }
+    if (operation_type === "reward" && (data?.balance === "0" || data?.balance === 0)) {
+        warnings.push("Reward pool balance is zero; claimants cannot withdraw");
+    }
+    return warnings;
+}
+function composeSummary(intent, status, created, modified, released) {
+    const intentVerb = intent.replace(/_/g, " ");
+    if (status === "failed")
+        return `Failed to ${intentVerb}`;
+    if (status === "pending_input")
+        return `${intentVerb} requires Guard submission to proceed`;
+    const parts = [];
+    if (created.length)
+        parts.push(`created ${created.length} object(s)`);
+    if (modified.length)
+        parts.push(`modified ${modified.length} object(s)`);
+    if (released.length) {
+        if (intent === "allocate_funds") {
+            const details = released.map(f => {
+                const amt = f.amount;
+                const coin = shortCoinType(f.coinType);
+                const recipient = f.to ? shortAddr(f.to) : null;
+                const sender = f.from ? shortAddr(f.from) : null;
+                if (recipient)
+                    return `${amt} ${coin} → ${recipient}`;
+                if (sender)
+                    return `${amt} ${coin} from ${sender}`;
+                return `${amt} ${coin}`;
+            }).join("; ");
+            parts.push(`distributed: ${details}`);
+        }
+        else {
+            parts.push(`${released.length} fund movement(s)`);
+        }
+    }
+    return `Successfully ${intentVerb}${parts.length ? ` (${parts.join(", ")})` : ""}`;
+}
+function shortAddr(addr) {
+    if (addr.length > 14) {
+        return addr.slice(0, 8) + "..." + addr.slice(-4);
+    }
+    return addr;
+}
+function shortCoinType(coinType) {
+    if (!coinType)
+        return "coin";
+    const parts = coinType.split("::");
+    return parts[parts.length - 1] || coinType;
+}
+export function buildSemantic(safeResult, context) {
+    if (!context)
+        return undefined;
+    const intent = inferIntent(context.operation_type, context.data);
+    const status = inferStatus(safeResult);
+    const objectChanges = safeResult?.objectChanges || [];
+    const balanceChanges = safeResult?.balanceChanges || [];
+    const events = safeResult?.events || [];
+    const created = tagObjectRoles(objectChanges.filter((c) => c?.type === "created"));
+    const modified = tagObjectRoles(objectChanges.filter((c) => c?.type === "mutated" || c?.type === "published"));
+    const released = tagFundRoles(balanceChanges, context.operation_type, context.data, events);
+    const annotatedEvents = annotateEvents(events);
+    const next_actions = inferNextActions(context.operation_type, context.data, status);
+    const warnings = inferWarnings(context.operation_type, context.data, safeResult);
+    return {
+        intent,
+        status,
+        summary: composeSummary(intent, status, created, modified, released),
+        created: created.length ? created : undefined,
+        modified: modified.length ? modified : undefined,
+        released: released.length ? released : undefined,
+        events: annotatedEvents.length ? annotatedEvents : undefined,
+        next_actions: next_actions.length ? next_actions : undefined,
+        warnings: warnings.length ? warnings : undefined,
+    };
+}
+export function buildDataSemantic(data, context, isError, errorMsg) {
+    if (!context)
+        return undefined;
+    const intent = inferIntent(context.operation_type, context.data);
+    const warnings = [];
+    let status;
+    if (isError) {
+        status = "failed";
+    }
+    else {
+        status = "success";
+        if (Array.isArray(data) && data.length === 0) {
+            status = "partial";
+            warnings.push("no results found");
+        }
+        else if (data === null || data === undefined) {
+            status = "partial";
+            warnings.push("no results found");
+        }
+        else if (typeof data === "object" && !Array.isArray(data)) {
+            const values = Object.values(data);
+            if (values.length > 0 && values.every((v) => (Array.isArray(v) ? v.length === 0 : v === null || v === undefined))) {
+                status = "partial";
+                warnings.push("no results found");
+            }
+        }
+    }
+    const next_actions = inferNextActions(context.operation_type, context.data, status);
+    let annotatedEvents;
+    if (!isError && context.operation_type === "onchain_events") {
+        const eventsArray = Array.isArray(data) ? data : (data?.data && Array.isArray(data.data) ? data.data : null);
+        if (eventsArray) {
+            annotatedEvents = annotateEvents(eventsArray);
+            if (annotatedEvents.length === 0)
+                annotatedEvents = undefined;
+        }
+    }
+    const intentVerb = intent.replace(/_/g, " ");
+    let summary;
+    if (status === "failed") {
+        summary = `Failed to ${intentVerb}`;
+    }
+    else if (status === "partial") {
+        summary = `${intentVerb} completed with no results`;
+    }
+    else {
+        summary = `Successfully ${intentVerb}`;
+    }
+    return {
+        intent,
+        status,
+        summary,
+        events: annotatedEvents,
+        next_actions: next_actions.length ? next_actions : undefined,
+        warnings: warnings.length ? warnings : undefined,
+    };
+}