@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/service-templates.js

@@ -0,0 +1,418 @@
+export const SERVICE_TEMPLATES = [
+    {
+        id: "T-S-01",
+        name: "Retail e-commerce Service",
+        description: "Standard retail shop with multiple SKUs, WIP-verified products, owner-only allocation",
+        applicable_scenes: ["service_retail", "service_buy_guard"],
+        industry_tags: ["retail", "ecommerce", "digital_goods"],
+        params: [
+            { name: "owner_address", type: "address", description: "Service owner address (receives payments)", required: true },
+            { name: "permission_address", type: "address", description: "Permission object address (must be owned by owner)", required: true },
+            { name: "description", type: "string", description: "Shop description", required: true },
+            { name: "location", type: "string", description: "Shop URL (HTTPS or IPFS)", required: false, default: "" },
+            { name: "sales_items", type: "object", description: "Array of {name, price, stock, wip, wip_hash}", required: true },
+            { name: "buy_guard_address", type: "address", description: "Buyer eligibility Guard (null for public sale)", required: false, default: "" },
+        ],
+        body: (p) => {
+            const result = {
+                object: null,
+                description: p.description,
+                permission: p.permission_address,
+                location: p.location || undefined,
+                sales: { op: "add", sales: p.sales_items },
+                order_allocators: [
+                    {
+                        threshold: "0",
+                        sharing: [{ who: { Object: p.owner_address }, weight: 100 }],
+                    },
+                ],
+            };
+            if (p.buy_guard_address)
+                result.buy_guard = p.buy_guard_address;
+            return result;
+        },
+        notes: [
+            "WIP hash is MANDATORY for tamper protection — never leave empty if wip URL is set",
+            "Use buy_guard for pre-sale whitelist phase, then clear for public sale",
+            "Single-recipient allocation (owner 100%) — use T-S-08 for multi-party split",
+        ],
+        post_publish_considerations: [
+            "machine/arbitrations/order_allocators become immutable — verify before publish",
+            "Sales can still be added/removed/updated post-publish",
+            "buy_guard can be changed post-publish (unusual exception)",
+        ],
+    },
+    {
+        id: "T-S-02",
+        name: "Rental Service (deposit + use + return)",
+        description: "Equipment/asset rental with deposit guarantee, Machine workflow, and arbitration",
+        applicable_scenes: ["service_rental"],
+        industry_tags: ["rental", "equipment", "real_estate"],
+        params: [
+            { name: "owner_address", type: "address", description: "Service owner (rental company)", required: true },
+            { name: "permission_address", type: "address", description: "Permission object address", required: true },
+            { name: "description", type: "string", description: "Rental service description", required: true },
+            { name: "machine_address", type: "address", description: "Published Machine with Reserve→Pay→Pickup→Return→Refund nodes", required: true },
+            { name: "arbitration_address", type: "address", description: "Arbitration for deposit disputes", required: true },
+            { name: "rental_items", type: "object", description: "Array of {name, price, stock=1, wip, wip_hash}", required: true },
+            { name: "compensation_fund_balance", type: "string", description: "Initial deposit to compensation_fund (in base units)", required: false, default: "0" },
+        ],
+        body: (p) => ({
+            object: null,
+            description: p.description,
+            permission: p.permission_address,
+            machine: p.machine_address,
+            arbitrations: { op: "add", objects: [p.arbitration_address] },
+            sales: { op: "add", sales: p.rental_items },
+            order_allocators: [
+                {
+                    threshold: "0",
+                    sharing: [{ who: { Object: p.owner_address }, weight: 100 }],
+                },
+            ],
+            compensation_fund_add: p.compensation_fund_balance && p.compensation_fund_balance !== "0"
+                ? { balance: p.compensation_fund_balance }
+                : undefined,
+        }),
+        notes: [
+            "stock=1 per rental item (unique items) — once rented, stock becomes 0",
+            "Machine must define deposit/return/refund nodes for proper rental flow",
+            "compensation_fund holds deposit guarantees — separate from rental fee",
+            "Arbitration required if compensation_fund > 0 (F-S-19)",
+        ],
+        post_publish_considerations: [
+            "Machine binding is permanent — verify workflow before publish",
+            "Arbitration binding is permanent — choose reputable arbiters",
+            "Sales can be updated (add new rental items, remove deprecated ones)",
+        ],
+    },
+    {
+        id: "T-S-03",
+        name: "Subscription Service (tiered plans)",
+        description: "Recurring-access service with tiered plans (Free/Pro/Enterprise), discount coupons, loyalty rewards",
+        applicable_scenes: ["service_subscription"],
+        industry_tags: ["subscription", "saas", "membership"],
+        params: [
+            { name: "owner_address", type: "address", description: "Service owner", required: true },
+            { name: "permission_address", type: "address", description: "Permission object address", required: true },
+            { name: "description", type: "string", description: "Subscription service description", required: true },
+            { name: "tier_plans", type: "object", description: "Array of {name, price, stock=999999, wip, wip_hash} for each tier", required: true },
+            { name: "trial_discount_count", type: "number", description: "Number of trial discount coupons to issue", required: false, default: 0 },
+            { name: "reward_address", type: "address", description: "Loyalty Reward object address (optional)", required: false, default: "" },
+        ],
+        body: (p) => {
+            const result = {
+                object: null,
+                description: p.description,
+                permission: p.permission_address,
+                sales: { op: "add", sales: p.tier_plans },
+                order_allocators: [
+                    {
+                        threshold: "0",
+                        sharing: [{ who: { Object: p.owner_address }, weight: 100 }],
+                    },
+                ],
+            };
+            if (p.reward_address) {
+                result.rewards = { op: "add", objects: [p.reward_address] };
+            }
+            return result;
+        },
+        notes: [
+            "Subscription renewals are handled by repeat orders (no native recurring billing)",
+            "Use large stock values (e.g. 999999) since subscriptions are not inventory-limited",
+            "Trial discounts: issue via service::discount (312) post-publish",
+            "Loyalty rewards: bind via service::reward_add (318) — locked by setting_lock_duration",
+        ],
+        post_publish_considerations: [
+            "Tier prices can be updated via sales_set (existing subscribers unaffected)",
+            "Discount coupons can be issued/destroyed post-publish",
+            "Rewards can be added but removal locked by duration",
+        ],
+    },
+    {
+        id: "T-S-04",
+        name: "Workflow-bound Service (machine-driven delivery)",
+        description: "Service with multi-step delivery workflow (e.g. freelance, custom manufacturing, course)",
+        applicable_scenes: ["service_workflow", "service_rental"],
+        industry_tags: ["workflow", "freelance", "manufacturing", "education"],
+        params: [
+            { name: "owner_address", type: "address", description: "Service owner (provider)", required: true },
+            { name: "permission_address", type: "address", description: "Permission object address", required: true },
+            { name: "description", type: "string", description: "Service description", required: true },
+            { name: "machine_address", type: "address", description: "Published Machine with Pay→Confirm→Deliver→Sign-off nodes", required: true },
+            { name: "service_items", type: "object", description: "Array of {name, price, stock, wip, wip_hash}", required: true },
+            { name: "customer_required", type: "string[]", description: "Required info fields (e.g. ['name','project_brief'])", required: false, default: [] },
+        ],
+        body: (p) => ({
+            object: null,
+            description: p.description,
+            permission: p.permission_address,
+            machine: p.machine_address,
+            sales: { op: "add", sales: p.service_items },
+            customer_required: p.customer_required,
+            order_allocators: [
+                {
+                    threshold: "0",
+                    sharing: [{ who: { Object: p.owner_address }, weight: 100 }],
+                },
+            ],
+        }),
+        notes: [
+            "Machine MUST be published before binding (machine::publish)",
+            "Each order creates a Progress object tracking the workflow",
+            "Named operators can be assigned per Forward in the Machine",
+            "Service.bPaused does NOT affect already-created Progress (existing orders continue)",
+        ],
+        post_publish_considerations: [
+            "Machine binding is PERMANENT — cannot upgrade workflow post-publish",
+            "To change workflow: clone Service with new Machine, migrate customers via discounts",
+            "customer_required fields can be updated post-publish",
+        ],
+    },
+    {
+        id: "T-S-05",
+        name: "Arbitration-bound Service (dispute-ready)",
+        description: "Service with multiple Arbitration objects for different dispute scopes + compensation_fund",
+        applicable_scenes: ["service_arbitration", "service_arbitration_binding"],
+        industry_tags: ["arbitration", "dispute_resolution", "high_value"],
+        params: [
+            { name: "owner_address", type: "address", description: "Service owner", required: true },
+            { name: "permission_address", type: "address", description: "Permission object address", required: true },
+            { name: "description", type: "string", description: "Service description", required: true },
+            { name: "arbitration_addresses", type: "string[]", description: "1-3 Arbitration object addresses (different scopes)", required: true },
+            { name: "compensation_fund_balance", type: "string", description: "Initial compensation_fund deposit (base units)", required: true },
+            { name: "setting_lock_duration_ms", type: "number", description: "Initial setting_lock_duration in ms (default 30 days)", required: false, default: 2592000000 },
+            { name: "service_items", type: "object", description: "Array of {name, price, stock, wip, wip_hash}", required: true },
+        ],
+        body: (p) => ({
+            object: null,
+            description: p.description,
+            permission: p.permission_address,
+            arbitrations: { op: "add", objects: p.arbitration_addresses },
+            compensation_fund_add: { balance: p.compensation_fund_balance },
+            setting_locked_time_add: p.setting_lock_duration_ms,
+            sales: { op: "add", sales: p.service_items },
+            order_allocators: [
+                {
+                    threshold: "0",
+                    sharing: [{ who: { Object: p.owner_address }, weight: 100 }],
+                },
+            ],
+        }),
+        notes: [
+            "Use 2-3 Arbitration objects: e.g. one for quality disputes, one for delivery disputes",
+            "compensation_fund > 0 REQUIRES arbitrations non-empty (F-S-19, E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND)",
+            "compensation_fund coin type MUST match Service<T> type parameter",
+            "setting_lock_duration protects customers — only-increase mechanism",
+        ],
+        post_publish_considerations: [
+            "Arbitration bindings are PERMANENT — verify arb reputation before publish",
+            "compensation_fund_add (deposit) is always mutable post-publish",
+            "compensation_fund_withdraw requires bPaused=true + lock_duration expired",
+            "Cannot add new Arbitration post-publish — only pre-publish",
+        ],
+    },
+    {
+        id: "T-S-06",
+        name: "Compensation fund Service (embedded Balance<T>)",
+        description: "Service focused on compensation_fund management — emphasizes distinction from Treasury",
+        applicable_scenes: ["service_compensation_fund", "service_arbitration"],
+        industry_tags: ["finance", "escrow", "guarantee"],
+        params: [
+            { name: "owner_address", type: "address", description: "Service owner", required: true },
+            { name: "permission_address", type: "address", description: "Permission object address", required: true },
+            { name: "description", type: "string", description: "Service description", required: true },
+            { name: "arbitration_addresses", type: "string[]", description: "Arbitration objects (required when fund > 0)", required: true },
+            { name: "initial_deposit", type: "string", description: "Initial compensation_fund deposit (base units)", required: true },
+            { name: "lock_duration_ms", type: "number", description: "setting_lock_duration (ms)", required: false, default: 2592000000 },
+            { name: "service_items", type: "object", description: "Sales items", required: true },
+        ],
+        body: (p) => ({
+            object: null,
+            description: p.description,
+            permission: p.permission_address,
+            arbitrations: { op: "add", objects: p.arbitration_addresses },
+            compensation_fund_add: { balance: p.initial_deposit },
+            setting_locked_time_add: p.lock_duration_ms,
+            sales: { op: "add", sales: p.service_items },
+            order_allocators: [
+                {
+                    threshold: "0",
+                    sharing: [{ who: { Object: p.owner_address }, weight: 100 }],
+                },
+            ],
+        }),
+        notes: [
+            "⚠️ compensation_fund is INTERNAL Balance<T> — distinct from Treasury (external)",
+            "Treasury is referenced via order_allocators.sharing.who=Entity (Treasury address)",
+            "compensation_fund is consumed by arbitration::compensation_claim (driven by arb result)",
+            "Owner can only withdraw via compensation_fund_withdraw (requires paused + lock expired)",
+        ],
+        post_publish_considerations: [
+            "Deposits (compensation_fund_add) always allowed",
+            "Withdrawals (compensation_fund_withdraw) require bPaused=true + lock_duration expired",
+            "Receive (compensation_fund_receive) locked by duration",
+            "setting_lock_duration only-increase — plan withdrawal timeline carefully",
+        ],
+    },
+    {
+        id: "T-S-07",
+        name: "Dynamic pricing Service (discount-driven)",
+        description: "Service with promotional discount coupons — supports rates (basis points, per 10000) and minus (direct deduction) types",
+        applicable_scenes: ["service_dynamic_pricing"],
+        industry_tags: ["retail", "marketing", "promotion"],
+        params: [
+            { name: "owner_address", type: "address", description: "Service owner", required: true },
+            { name: "permission_address", type: "address", description: "Permission object address", required: true },
+            { name: "description", type: "string", description: "Service description", required: true },
+            { name: "service_items", type: "object", description: "Array of {name, price, stock, wip, wip_hash}", required: true },
+            { name: "discount_specs", type: "object", description: "Array of {name, type, data, count, expire_at} for initial discounts", required: false, default: [] },
+        ],
+        body: (p) => ({
+            object: null,
+            description: p.description,
+            permission: p.permission_address,
+            sales: { op: "add", sales: p.service_items },
+            order_allocators: [
+                {
+                    threshold: "0",
+                    sharing: [{ who: { Object: p.owner_address }, weight: 100 }],
+                },
+            ],
+        }),
+        notes: [
+            "Discounts are issued POST-PUBLISH via service::discount (312) — not in create body",
+            "discount_type=0 rates (basis points, e.g. 1000=10%); 1=minus (direct deduction, base units)",
+            "MAX_DISCOUNT_COUNT_ONCE = 1000 per issue call",
+            "MAX_DISCOUNT_RECEIVER_ONCE = 1000 receivers per call",
+            "MAX_DISCOUNT_TOTAL_COUNT = 20000 total coupons per Service",
+            "discount_destroy is holder-only (no SERVICE_DISCOUNT permission needed)",
+        ],
+        post_publish_considerations: [
+            "Discount coupons can be issued/destroyed freely",
+            "Sales prices can be updated via sales_set (existing orders unaffected)",
+            "Track discount usage to avoid stockout of promotional items",
+        ],
+    },
+    {
+        id: "T-S-08",
+        name: "Multi-allocator Service (tiered fund distribution)",
+        description: "Service with multiple allocator tiers — first-match-wins distribution based on order value",
+        applicable_scenes: ["service_multi_allocator", "service_order_allocator", "service_reward"],
+        industry_tags: ["marketplace", "platform", "logistics"],
+        params: [
+            { name: "owner_address", type: "address", description: "Service owner (merchant)", required: true },
+            { name: "permission_address", type: "address", description: "Permission object address", required: true },
+            { name: "description", type: "string", description: "Service description", required: true },
+            { name: "platform_address", type: "address", description: "Platform fee recipient", required: true },
+            { name: "logistics_address", type: "address", description: "Logistics fee recipient (optional)", required: false, default: "" },
+            { name: "service_items", type: "object", description: "Array of {name, price, stock, wip, wip_hash}", required: true },
+            { name: "tier1_threshold", type: "string", description: "Small order threshold (base units, e.g. '0')", required: false, default: "0" },
+            { name: "tier2_threshold", type: "string", description: "Medium order threshold (base units)", required: false, default: "10000000000" },
+            { name: "tier3_threshold", type: "string", description: "Large order threshold (base units)", required: false, default: "100000000000" },
+        ],
+        body: (p) => {
+            const allocators = [
+                {
+                    threshold: p.tier1_threshold,
+                    sharing: [
+                        { who: { Object: p.owner_address }, weight: 90 },
+                        { who: { Object: p.platform_address }, weight: 10 },
+                    ],
+                },
+                {
+                    threshold: p.tier2_threshold,
+                    sharing: p.logistics_address
+                        ? [
+                            { who: { Object: p.owner_address }, weight: 80 },
+                            { who: { Object: p.platform_address }, weight: 10 },
+                            { who: { Object: p.logistics_address }, weight: 10 },
+                        ]
+                        : [
+                            { who: { Object: p.owner_address }, weight: 85 },
+                            { who: { Object: p.platform_address }, weight: 15 },
+                        ],
+                },
+                {
+                    threshold: p.tier3_threshold,
+                    sharing: p.logistics_address
+                        ? [
+                            { who: { Object: p.owner_address }, weight: 70 },
+                            { who: { Object: p.platform_address }, weight: 10 },
+                            { who: { Object: p.logistics_address }, weight: 20 },
+                        ]
+                        : [
+                            { who: { Object: p.owner_address }, weight: 80 },
+                            { who: { Object: p.platform_address }, weight: 20 },
+                        ],
+                },
+            ];
+            return {
+                object: null,
+                description: p.description,
+                permission: p.permission_address,
+                sales: { op: "add", sales: p.service_items },
+                order_allocators: allocators,
+            };
+        },
+        notes: [
+            "First-match-wins: first allocator whose threshold <= order value handles distribution",
+            "Each tier can have its own Guard for execution authorization (optional)",
+            "Thresholds must be ascending (tier1 < tier2 < tier3)",
+            "MAX_SHARING_COUNT = 100 per allocator (sum of sharing entries)",
+            "Treasury addresses can be referenced via sharing.who=Entity (Treasury object)",
+        ],
+        post_publish_considerations: [
+            "⚠️ order_allocators is IMMUTABLE post-publish (F-S-22) — verify tiers before publish",
+            "To change fee split: clone Service with new allocators (cannot migrate existing Orders)",
+            "Sales can still be updated post-publish (only allocator is locked)",
+        ],
+    },
+];
+export const SERVICE_TEMPLATES_VERSION = "1.0.0";
+export function getAllServiceTemplates() {
+    return [...SERVICE_TEMPLATES];
+}
+export function getServiceTemplateById(id) {
+    return SERVICE_TEMPLATES.find(t => t.id === id);
+}
+export function getServiceTemplatesByScene(sceneId) {
+    return SERVICE_TEMPLATES.filter(t => t.applicable_scenes.includes(sceneId));
+}
+export function getServiceTemplatesByIndustry(industry) {
+    return SERVICE_TEMPLATES.filter(t => t.industry_tags.includes(industry) || t.industry_tags.includes("universal"));
+}
+export function suggestServiceTemplateForScene(sceneId) {
+    const matches = getServiceTemplatesByScene(sceneId);
+    return matches.length > 0 ? matches[0] : undefined;
+}
+export function listServiceTemplates() {
+    return SERVICE_TEMPLATES.map(t => ({
+        id: t.id,
+        name: t.name,
+        description: t.description,
+        scenes: t.applicable_scenes,
+    }));
+}
+export function fillServiceTemplate(templateId, params) {
+    const tpl = getServiceTemplateById(templateId);
+    if (!tpl)
+        return { ok: false, error: `Template ${templateId} not found` };
+    const missing = [];
+    for (const p of tpl.params) {
+        if (p.required && !(p.name in params)) {
+            missing.push(p.name);
+        }
+    }
+    if (missing.length > 0) {
+        return { ok: false, error: `Missing required params: ${missing.join(", ")}`, missing_required: missing };
+    }
+    const filled = { ...params };
+    for (const p of tpl.params) {
+        if (!(p.name in filled) && p.default !== undefined) {
+            filled[p.name] = p.default;
+        }
+    }
+    return { ok: true, body: tpl.body(filled) };
+}

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

@@ -0,0 +1,103 @@
+export interface SemanticToSchemaRule {
+    id: string;
+    pattern_name: string;
+    semantic_intent: string;
+    match_keywords: string[];
+    schema_fields: string[];
+    example_json: object;
+    reverse_explanation: string;
+}
+export interface SchemaToSemanticRule {
+    element_type: "field" | "op" | "index";
+    type_name: string;
+    semantic_explanation: string;
+    constraints?: string[];
+}
+export interface ServiceConstraintRule {
+    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 SERVICE_CONSTRAINT_RULES: ServiceConstraintRule[];
+export declare const SERVICE_TRANSLATION_VERSION = "1.0.0";
+export declare function matchSemanticPattern(userIntent: string): SemanticToSchemaRule[];
+export interface ServiceCallDataForExplain {
+    object?: string | null;
+    description?: string;
+    location?: string;
+    customer_required?: string[];
+    sales?: {
+        op: "add" | "set";
+        sales: Array<{
+            name: string;
+            price?: string;
+            stock?: number;
+            wip?: string;
+            wip_hash?: string;
+        }>;
+    } | {
+        op: "remove";
+        sales_name: string[];
+    } | {
+        op: "clear";
+    };
+    machine?: string | null;
+    buy_guard?: string | null;
+    arbitrations?: {
+        op: "add" | "set" | "remove";
+        objects: string[];
+    } | {
+        op: "clear";
+    };
+    repositories?: {
+        op: "add" | "set" | "remove";
+        objects: string[];
+    } | {
+        op: "clear";
+    };
+    rewards?: {
+        op: "add" | "set" | "remove";
+        objects: string[];
+    } | {
+        op: "clear";
+    };
+    order_allocators?: unknown;
+    discount?: {
+        name: string;
+        discount_type: number;
+        data: number;
+        count: number;
+        receivers?: string[];
+        expire_at?: number;
+    };
+    pause?: boolean;
+    publish?: boolean;
+    compensation_fund_add?: {
+        balance: string | number;
+    };
+    compensation_fund_withdraw?: unknown;
+    compensation_fund_receive?: unknown;
+    setting_locked_time_add?: number;
+    order_new?: {
+        buy: {
+            items: Array<{
+                name: string;
+                wip_hash: string;
+                count: number;
+            }>;
+            discount?: string;
+            total_pay: string;
+        };
+    };
+    builder?: string;
+    um?: string | null;
+    owner_receive?: unknown;
+}
+export declare function explainServiceCallData(data: ServiceCallDataForExplain): string;
+export declare function explainField(fieldName: string): SchemaToSemanticRule | undefined;
+export declare function explainOp(opName: string): SchemaToSemanticRule | undefined;
+export declare function getConstraintsByCategory(category: ServiceConstraintRule["category"]): ServiceConstraintRule[];
+export declare function explainServicePermissionIndex(index: number): string;