@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/order-templates.d.ts

@@ -0,0 +1,50 @@
+export type TemplateParamType = "address" | "string" | "number" | "string[]" | "object";
+export interface OrderTemplateParam {
+    name: string;
+    type: TemplateParamType;
+    description: string;
+    required: boolean;
+    default?: string | number | string[] | object;
+}
+export interface OrderTemplate {
+    id: string;
+    name: string;
+    description: string;
+    applicable_scenes: string[];
+    industry_tags: string[];
+    params: OrderTemplateParam[];
+    body: (params: Record<string, string | number | string[] | object>) => object;
+    notes?: string[];
+    permission_layer: "L1_owner_only" | "L2_owner_or_agent" | "L3_package_only" | "via_service_buy";
+    irreversible: boolean;
+}
+export declare const ORDER_TEMPLATES: OrderTemplate[];
+export declare const ORDER_TEMPLATES_VERSION = "1.0.0";
+export declare const ORDER_TEMPLATES_COUNT: number;
+export declare function getAllOrderTemplates(): OrderTemplate[];
+export declare function getTemplateById(id: string): OrderTemplate | undefined;
+export declare function getTemplatesByScene(sceneId: string): OrderTemplate[];
+export declare function getTemplatesByIndustry(industry: string): OrderTemplate[];
+export declare function getTemplatesByPermissionLayer(layer: OrderTemplate["permission_layer"]): OrderTemplate[];
+export declare function getIrreversibleTemplates(): OrderTemplate[];
+export declare function suggestTemplateForScene(sceneId: string): OrderTemplate | undefined;
+export declare function listOrderTemplates(): {
+    id: string;
+    name: string;
+    description: string;
+    scenes: string[];
+    irreversible: boolean;
+}[];
+export type FillTemplateResult = {
+    ok: true;
+    body: object;
+    template: OrderTemplate;
+} | {
+    ok: false;
+    error: string;
+    template?: OrderTemplate;
+};
+export declare function fillTemplate(templateId: string, params: Record<string, string | number | string[] | object>): FillTemplateResult;
+export declare function suggestTemplateFromIntent(intent: string): OrderTemplate | undefined;
+export declare function getTemplateParameters(templateId: string): OrderTemplateParam[] | undefined;
+export declare function validateTemplateParams(templateId: string, params: Record<string, string | number | string[] | object>): string[];

package/dist/knowledge/order-templates.js

@@ -0,0 +1,368 @@
+export const ORDER_TEMPLATES = [
+    {
+        id: "T-O-01",
+        name: "Standard retail order (single item, no machine)",
+        description: "Template for buying a single retail item from a Service without a Machine workflow. Order created via service::buy.",
+        applicable_scenes: ["order_create", "order_required_info"],
+        industry_tags: ["retail", "universal"],
+        params: [
+            { name: "service_address", type: "address", description: "Service object address (target of service::buy)", required: true },
+            { name: "item_name", type: "string", description: "Item name (must match Service's sale item name)", required: true },
+            { name: "item_price", type: "string", description: "Item price in MIST (string for u64 precision)", required: true },
+            { name: "item_quantity", type: "number", description: "Quantity to purchase", required: true, default: 1 },
+            { name: "wip_hash", type: "string", description: "WIP hash (NOT empty string — use '0x' + actual hash)", required: true },
+            { name: "discount_address", type: "address", description: "Discount object address (optional)", required: false },
+            { name: "named_order", type: "string", description: "Order alias name (optional, for SDK lookup)", required: false },
+            { name: "contact_address", type: "address", description: "Contact object address for required_info (recipient)", required: false },
+        ],
+        body: (p) => {
+            const result = {
+                _note: "Order creation goes via service::buy, not CallOrder_Data. Use this template to populate CallService_Data.buy.",
+                _call_target: "service",
+                object: p.service_address,
+                buy: {
+                    items: [
+                        {
+                            name: p.item_name,
+                            price: p.item_price,
+                            quantity: p.item_quantity,
+                            wip_hash: p.wip_hash,
+                        },
+                    ],
+                    discount: p.discount_address ?? null,
+                    named_order: p.named_order ?? null,
+                    machine_forward: null,
+                },
+            };
+            if (p.contact_address) {
+                result._post_buy_required_info = p.contact_address;
+            }
+            return result;
+        },
+        notes: [
+            "Order is NOT created directly — service::buy atomically builds Order + Allocation + Progress",
+            "wip_hash must NOT be empty string — use actual hash to avoid 'WIP hash not match' error",
+            "Item name + price must match a sale item configured on the Service",
+        ],
+        permission_layer: "via_service_buy",
+        irreversible: true,
+    },
+    {
+        id: "T-O-02",
+        name: "Workflow order advance (machine + progress forward)",
+        description: "Template for advancing an Order's Progress via named forward. Both owner and agent can advance.",
+        applicable_scenes: ["order_advance"],
+        industry_tags: ["workflow", "logistics", "service"],
+        params: [
+            { name: "order_address", type: "address", description: "Order object address", required: true },
+            { name: "next_node_name", type: "string", description: "Target node name to advance to", required: true },
+            { name: "forward_name", type: "string", description: "Forward name (must exist on current node)", required: true },
+            { name: "operator", type: "address", description: "Named operator address (optional, null for anyone)", required: false },
+            { name: "guard_submission", type: "object", description: "Guard submission object (optional, required if forward has guard)", required: false },
+            { name: "message", type: "string", description: "Optional message attached to this advance", required: false },
+        ],
+        body: (p) => {
+            const result = {
+                object: p.order_address,
+                progress: {
+                    next_node_name: p.next_node_name,
+                    forward: {
+                        name: p.forward_name,
+                        operator: p.operator ?? null,
+                        guard: p.guard_submission ?? null,
+                    },
+                    op: "next",
+                },
+            };
+            if (p.message)
+                result.progress.message = p.message;
+            return result;
+        },
+        notes: [
+            "L2 operation — both owner and agent can advance",
+            "Node transition is IRREVERSIBLE (no backward movement)",
+            "If forward has a Guard, guard_submission is required",
+            "Service.machine is snapshotted at buy time — Order.machine will NOT update if Service.machine changes later",
+        ],
+        permission_layer: "L2_owner_or_agent",
+        irreversible: true,
+    },
+    {
+        id: "T-O-03",
+        name: "Set agent list (multi-agent logistics delegation)",
+        description: "Template for setting up multiple agents to operate the Order (advance Progress, update required_info). Agents CANNOT receive payments.",
+        applicable_scenes: ["order_set_agent"],
+        industry_tags: ["logistics", "team", "service"],
+        params: [
+            { name: "order_address", type: "address", description: "Order object address", required: true },
+            { name: "agent_addresses", type: "string[]", description: "Agent addresses (overwrites entire list)", required: true },
+        ],
+        body: (p) => ({
+            object: p.order_address,
+            agent: p.agent_addresses,
+        }),
+        notes: [
+            "L1 operation — OWNER-ONLY (assert_owner)",
+            "⚠️ Boundary bug: actual max 11 agents (not 10) due to <= in agent_set_imp",
+            "FROZEN after Progress binding — call BEFORE service::buy if machine is configured",
+            "Agents can advance Progress, update required_info, file arbitration — but CANNOT receive payments",
+            "Overwrites entire agent list (not additive)",
+        ],
+        permission_layer: "L1_owner_only",
+        irreversible: false,
+    },
+    {
+        id: "T-O-04",
+        name: "File arbitration (arb_confirm with proposition)",
+        description: "Template for filing an arbitration case with description + proposition list. Triggers order::dispute(arb) appending Arb to dispute vector.",
+        applicable_scenes: ["order_arb_confirm"],
+        industry_tags: ["dispute", "arbitration", "universal"],
+        params: [
+            { name: "order_address", type: "address", description: "Order object address", required: true },
+            { name: "arb_address", type: "address", description: "Arbitration object address (must exist)", required: true },
+            { name: "confirm", type: "string", description: "Confirm materials valid? 'true' or 'false'", required: true, default: "true" },
+            { name: "description", type: "string", description: "Compensation application description (required for arb::description_change)", required: true },
+            { name: "propositions", type: "string[]", description: "Compensation claims list (e.g. ['Refund full amount', 'Compensation for delay'])", required: true },
+        ],
+        body: (p) => ({
+            object: p.order_address,
+            arb_confirm: {
+                arb: p.arb_address,
+                confirm: p.confirm === "true",
+                description: p.description,
+                proposition: p.propositions,
+            },
+        }),
+        notes: [
+            "L2 operation — both owner and agent can file",
+            "IRREVERSIBLE — once filed, Arb process cannot be cancelled",
+            "Triggers order::dispute(arb) — appends Arb to order.dispute vector (max 10)",
+            "If claimed_by is already set, aborts E_ORDER_ALREADY_CLAIMED",
+            "Use T-O-08 (arb_objection) to object to Arb ruling after this step",
+        ],
+        permission_layer: "L2_owner_or_agent",
+        irreversible: true,
+    },
+    {
+        id: "T-O-05",
+        name: "Receive payment (owner-only collect)",
+        description: "Template for collecting CoinWrapper or arbitrary Receiving<K> from Progress. Funds forwarded to owner. Owner-only.",
+        applicable_scenes: ["order_receive"],
+        industry_tags: ["finance", "universal"],
+        params: [
+            { name: "order_address", type: "address", description: "Order object address", required: true },
+            { name: "received_object_id", type: "string", description: "Receiving object ID (CoinWrapper or Receiving<K>)", required: true },
+        ],
+        body: (p) => ({
+            object: p.order_address,
+            receive: {
+                received: p.received_object_id,
+            },
+        }),
+        notes: [
+            "L1 operation — OWNER-ONLY (assert_owner). Agent CANNOT receive.",
+            "Aborts E_ORDER_DELIVERING if Progress not at terminal node",
+            "Can be called multiple times (e.g. partial refunds)",
+            "Funds are unwrapped (CoinWrapper → Coin) and transferred to owner address",
+            "For ownership transfer, use T-O-06 variant (transfer_to) instead",
+        ],
+        permission_layer: "L1_owner_only",
+        irreversible: false,
+    },
+    {
+        id: "T-O-06",
+        name: "Claim compensation (arb_claim_compensation — IRREVERSIBLE)",
+        description: "Template for claiming compensation from a ruled Arb. Sets claimed_by — ONE-TIME, IRREVERSIBLE, blocks all future disputes.",
+        applicable_scenes: ["order_arb_claim_compensation"],
+        industry_tags: ["dispute", "arbitration"],
+        params: [
+            { name: "order_address", type: "address", description: "Order object address", required: true },
+            { name: "arb_address", type: "address", description: "RULED Arb object address (must be in Arbitrated state)", required: true },
+        ],
+        body: (p) => ({
+            object: p.order_address,
+            arb_claim_compensation: {
+                arb: p.arb_address,
+            },
+        }),
+        notes: [
+            "⚠️⚠️ IRREVERSIBLE — claimed_by cannot be reset",
+            "After claim: NO new disputes can be filed (E_ORDER_ALREADY_CLAIMED)",
+            "Arb must be in Arbitrated state (ruled, not pending)",
+            "L2 operation — both owner and agent can claim",
+            "Triggers service::compensation_claim → order::compensate(arb)",
+            "Verify arb_address TWICE before submitting — there is no undo",
+        ],
+        permission_layer: "L2_owner_or_agent",
+        irreversible: true,
+    },
+    {
+        id: "T-O-07",
+        name: "Update required_info (Contact recipient or WTS Proof)",
+        description: "Template for setting required_info — either a Contact object (recipient info) or WTS Proof object (delivery proof). Both owner and agent can update.",
+        applicable_scenes: ["order_required_info"],
+        industry_tags: ["logistics", "universal"],
+        params: [
+            { name: "order_address", type: "address", description: "Order object address", required: true },
+            { name: "info_type", type: "string", description: "'contact' (recipient) or 'wts_proof' (delivery proof) or 'clear' (set to null)", required: true },
+            { name: "info_address", type: "address", description: "Contact or WTS Proof object address (not needed if info_type='clear')", required: false },
+        ],
+        body: (p) => {
+            if (p.info_type === "clear") {
+                return {
+                    object: p.order_address,
+                    required_info: null,
+                };
+            }
+            if (!p.info_address) {
+                throw new Error(`info_address required when info_type='${p.info_type}'`);
+            }
+            return {
+                object: p.order_address,
+                required_info: p.info_address,
+            };
+        },
+        notes: [
+            "L2 operation — both owner and agent can update",
+            "REVERSIBLE — can be called multiple times",
+            "Contact object = recipient info (shipping address, contact details)",
+            "WTS Proof object = delivery proof (generated via Wowok Messenger)",
+            "null clears the field",
+        ],
+        permission_layer: "L2_owner_or_agent",
+        irreversible: false,
+    },
+    {
+        id: "T-O-08",
+        name: "Object to Arb ruling (arb_objection — request re-arbitration)",
+        description: "Template for objecting to an Arb ruling and requesting re-arbitration. Requires Arb status = Arbitrated.",
+        applicable_scenes: ["order_arb_objection"],
+        industry_tags: ["dispute", "arbitration"],
+        params: [
+            { name: "order_address", type: "address", description: "Order object address", required: true },
+            { name: "arb_address", type: "address", description: "RULED Arb object address (must be in Arbitrated state)", required: true },
+            { name: "objection_reason", type: "string", description: "Reason for objection (required by arb::objection)", required: true },
+        ],
+        body: (p) => ({
+            object: p.order_address,
+            arb_objection: {
+                arb: p.arb_address,
+                objection: p.objection_reason,
+            },
+        }),
+        notes: [
+            "L2 operation — both owner and agent can object",
+            "IRREVERSIBLE — triggers re-arbitration flow",
+            "Arb must be in Arbitrated state (after initial ruling)",
+            "Cannot object if claimed_by is already set (E_ORDER_ALREADY_CLAIMED)",
+        ],
+        permission_layer: "L2_owner_or_agent",
+        irreversible: true,
+    },
+];
+export const ORDER_TEMPLATES_VERSION = "1.0.0";
+export const ORDER_TEMPLATES_COUNT = ORDER_TEMPLATES.length;
+export function getAllOrderTemplates() {
+    return [...ORDER_TEMPLATES];
+}
+export function getTemplateById(id) {
+    return ORDER_TEMPLATES.find(t => t.id === id);
+}
+export function getTemplatesByScene(sceneId) {
+    return ORDER_TEMPLATES.filter(t => t.applicable_scenes.includes(sceneId));
+}
+export function getTemplatesByIndustry(industry) {
+    return ORDER_TEMPLATES.filter(t => t.industry_tags.includes(industry) || t.industry_tags.includes("universal"));
+}
+export function getTemplatesByPermissionLayer(layer) {
+    return ORDER_TEMPLATES.filter(t => t.permission_layer === layer);
+}
+export function getIrreversibleTemplates() {
+    return ORDER_TEMPLATES.filter(t => t.irreversible);
+}
+export function suggestTemplateForScene(sceneId) {
+    const matches = getTemplatesByScene(sceneId);
+    return matches.length > 0 ? matches[0] : undefined;
+}
+export function listOrderTemplates() {
+    return ORDER_TEMPLATES.map(t => ({
+        id: t.id,
+        name: t.name,
+        description: t.description,
+        scenes: t.applicable_scenes,
+        irreversible: t.irreversible,
+    }));
+}
+export function fillTemplate(templateId, params) {
+    const tpl = getTemplateById(templateId);
+    if (!tpl)
+        return { ok: false, error: `Template ${templateId} not found` };
+    for (const p of tpl.params) {
+        if (p.required && !(p.name in params)) {
+            return { ok: false, error: `Missing required param: ${p.name}`, template: tpl };
+        }
+    }
+    try {
+        const body = tpl.body(params);
+        return { ok: true, body, template: tpl };
+    }
+    catch (e) {
+        return { ok: false, error: `Template body generation failed: ${e.message}`, template: tpl };
+    }
+}
+export function suggestTemplateFromIntent(intent) {
+    const lower = intent.toLowerCase();
+    const keywordMap = [
+        ["buy", "T-O-01"], ["purchase", "T-O-01"],
+        ["advance", "T-O-02"], ["forward", "T-O-02"],
+        ["set agent", "T-O-03"], ["agent", "T-O-03"],
+        ["arb_confirm", "T-O-04"], ["file dispute", "T-O-04"], ["apply arbitration", "T-O-04"],
+        ["receive", "T-O-05"], ["collect", "T-O-05"],
+        ["claim compensation", "T-O-06"],
+        ["required_info", "T-O-07"], ["contact", "T-O-07"], ["recipient", "T-O-07"],
+        ["arb_objection", "T-O-08"], ["objection", "T-O-08"],
+    ];
+    for (const [kw, tplId] of keywordMap) {
+        if (lower.includes(kw.toLowerCase())) {
+            return getTemplateById(tplId);
+        }
+    }
+    return undefined;
+}
+export function getTemplateParameters(templateId) {
+    return getTemplateById(templateId)?.params;
+}
+export function validateTemplateParams(templateId, params) {
+    const tpl = getTemplateById(templateId);
+    if (!tpl)
+        return [`Template ${templateId} not found`];
+    const issues = [];
+    for (const p of tpl.params) {
+        if (p.required && !(p.name in params)) {
+            issues.push(`Missing required param: ${p.name}`);
+            continue;
+        }
+        if (!(p.name in params))
+            continue;
+        const val = params[p.name];
+        if (p.type === "address") {
+            if (typeof val !== "string" || !val.startsWith("0x") || val.length < 40) {
+                issues.push(`Param ${p.name} must be a valid Wow address (got: ${val})`);
+            }
+        }
+        else if (p.type === "string") {
+            if (typeof val !== "string")
+                issues.push(`Param ${p.name} must be a string`);
+        }
+        else if (p.type === "number") {
+            if (typeof val !== "number" || !Number.isFinite(val))
+                issues.push(`Param ${p.name} must be a number`);
+        }
+        else if (p.type === "string[]") {
+            if (!Array.isArray(val) || !val.every(v => typeof v === "string")) {
+                issues.push(`Param ${p.name} must be a string[]`);
+            }
+        }
+    }
+    return issues;
+}

package/dist/knowledge/order-translation.d.ts

@@ -0,0 +1,78 @@
+import { type OrderScene, type OrderPermissionLayer } from "./order-ledger.js";
+export interface SemanticToSchemaRule {
+    id: string;
+    pattern_name: string;
+    semantic_intent: string;
+    match_keywords: string[];
+    schema_fields: string[];
+    example_json: object;
+    reverse_explanation: string;
+    operation_field?: OrderScene["operation_field"];
+    permission_layer?: OrderPermissionLayer;
+}
+export interface SchemaToSemanticRule {
+    element_type: "field" | "op" | "index" | "error";
+    type_name: string;
+    semantic_explanation: string;
+    constraints?: string[];
+}
+export interface OrderConstraintRule {
+    id: string;
+    category: "structural" | "semantic" | "authority" | "lifecycle" | "cross_object";
+    rule: string;
+    applies_to: string[];
+}
+export declare const SEMANTIC_TO_SCHEMA_RULES: SemanticToSchemaRule[];
+export declare const SCHEMA_TO_SEMANTIC_RULES: SchemaToSemanticRule[];
+export declare const ORDER_CONSTRAINT_RULES: OrderConstraintRule[];
+export declare const ORDER_TRANSLATION_VERSION = "1.0.0";
+export declare function matchSemanticPattern(userIntent: string): SemanticToSchemaRule[];
+export interface OrderCallData {
+    object?: string;
+    agent?: string[];
+    required_info?: string | null;
+    progress?: {
+        next_node_name?: string;
+        forward?: {
+            name: string;
+            operator?: string | null;
+            guard?: object | null;
+        };
+        op?: "next" | "hold" | "unhold" | "adminUnhold";
+        message?: string;
+    };
+    arb_confirm?: {
+        arb: string;
+        confirm: boolean;
+        description?: string;
+        proposition?: string[];
+    };
+    arb_objection?: {
+        arb: string;
+        objection: string;
+    };
+    arb_claim_compensation?: {
+        arb: string;
+    };
+    receive?: {
+        received: string;
+    };
+    transfer_to?: string;
+}
+export declare function explainOrderCallData(data: OrderCallData): string;
+export declare function explainField(fieldName: string): SchemaToSemanticRule | undefined;
+export declare function explainOp(opName: string): SchemaToSemanticRule | undefined;
+export declare function explainOrderError(errorNameOrCode: string | number): SchemaToSemanticRule | undefined;
+export declare function getConstraintsByCategory(category: OrderConstraintRule["category"]): OrderConstraintRule[];
+export declare function explainPermissionLayer(layer: OrderPermissionLayer): string;
+export declare function resolveFieldName(sdkOrMoveName: string): {
+    sdk_name: string;
+    move_name: string;
+    is_deviation: boolean;
+};
+export declare function matchSceneFromOperation(operationField: OrderScene["operation_field"]): OrderScene | undefined;
+export declare function explainOrderIntent(intent: string): {
+    matched_scene?: OrderScene;
+    matched_patterns: SemanticToSchemaRule[];
+    relevant_constraints: OrderConstraintRule[];
+};