@wowok/agent-mcp 2.6.0 → 2.6.3

package/dist/extensions/modes.d.ts

@@ -0,0 +1,2 @@
+import type { IndustryMode } from "./types.js";
+export declare const BUILTIN_MODES: IndustryMode[];

package/dist/extensions/modes.js

@@ -0,0 +1,493 @@
+import { getScenarioMode } from "../knowledge/scenario-modes.js";
+import { getIndustryTraits } from "../knowledge/industry-registry.js";
+import { getIndustryRiskChecks, getIndustryNeeds } from "../customer/index.js";
+import { getFlywheelForIndustry } from "../knowledge/acquisition-flywheel.js";
+const GENERAL_TRAITS = {
+    has_logistics: false,
+    communication_heavy: false,
+    pure_digital: false,
+    long_cycle: false,
+    deposit_required: false,
+    multi_tier_allocation: false,
+    regulatory_intensity: "low",
+    trust_sensitivity: "medium",
+    consumption_frequency: "occasional",
+    avg_ticket_size: "medium",
+};
+const GENERAL_FLYWHEEL = {
+    industry: "general",
+    trustSellingPoints: [],
+    keyActions: [],
+    rewardStrategy: "User-defined",
+    discountStrategy: "User-defined",
+    trustDescription: "User-defined trust mechanism",
+};
+const GENERAL_MACHINE_SHAPE = [
+    { name: "paid", role: "Entry: order created and paid" },
+    { name: "delivering", role: "Service delivery in progress" },
+    { name: "completed", role: "Service completed, funds released" },
+    { name: "refunded", role: "Customer refund path" },
+    { name: "cancelled", role: "Pre-delivery cancellation" },
+];
+const GENERAL_ALLOCATOR = {
+    recipient: "signer",
+    count: 1,
+    mode: "surplus",
+    description: "Default: surplus to service owner (general fallback)",
+};
+const RETAIL_MACHINE_SHAPE = [
+    { name: "paid", role: "Entry: order paid via Service.buy(); Machine starts here" },
+    { name: "shipped", role: "Merchant ships goods, records shipping WIP (tracking number)" },
+    { name: "delivered", role: "Goods delivered to buyer" },
+    { name: "confirmed", role: "Buyer confirms receipt" },
+    { name: "completed", role: "Funds released to merchant" },
+    { name: "refunded", role: "Return & refund path" },
+    { name: "cancelled", role: "Pre-ship cancellation" },
+];
+const RETAIL_GUARDS = [
+    { template_id: "buy_guard_inventory", host: "service", purpose: "Verify inventory and buyer address on purchase" },
+    { template_id: "ship_guard_wip", host: "machine", purpose: "Shipping evidence WIP (logistics tracking number)" },
+    { template_id: "confirm_guard_signer", host: "machine", purpose: "Only buyer can confirm receipt" },
+    { template_id: "refund_guard_permission", host: "machine", purpose: "Return & refund requires merchant permission OR arbiter" },
+    { template_id: "tpl_payment_exception_compensation", host: "machine", purpose: "Logistics delay exception compensation (§2.13)" },
+];
+const RETAIL_ALLOCATOR = {
+    recipient: "entity",
+    count: 2,
+    mode: "rate",
+    description: "Platform 10% + Merchant 90% (rate-based split)",
+};
+const RETAIL_KEY_RISK = "Products don't match description — no refund path for returns";
+const RETAIL_BUILD_NOTES = [
+    "Logistics WIP (tracking number) is essential — shipping evidence protects both parties in return disputes",
+    "confirm_gate prevents merchant from self-confirming receipt",
+    "Refund path must support return-and-exchange flow",
+    "Compensation fund covers return/exchange disputes",
+];
+const RETAIL_D2C_MACHINE_SHAPE = [
+    { name: "ordered", role: "Entry: order created (funds escrowed in Allocation)" },
+    { name: "shipped", role: "Merchant ships goods" },
+    { name: "delivered", role: "Goods delivered to buyer" },
+    { name: "completed", role: "Buyer confirms receipt — withdraw_guard releases funds" },
+    { name: "cancelled", role: "Pre-ship cancellation — refund_guard refunds buyer" },
+];
+const RETAIL_D2C_GUARDS = [
+    { template_id: "withdraw_guard_delivery", host: "service", purpose: "Release funds to merchant + processor on order completion (delivery confirmation)" },
+    { template_id: "refund_guard_cancellation", host: "service", purpose: "Refund 100% to buyer on order cancellation" },
+];
+const RETAIL_D2C_ALLOCATOR = {
+    recipient: "entity",
+    count: 2,
+    mode: "rate",
+    description: "Merchant 97% + Processor 3% (rate-based split, no platform commission)",
+};
+const RETAIL_D2C_KEY_RISK = "No platform arbitration — disputes rely on optional Arbitration or off-chain chargeback";
+const RETAIL_D2C_BUILD_NOTES = [
+    "Allocation escrow replaces platform custody — funds locked in contract until Guard releases",
+    "withdraw_guard enforces delivery gate — merchant must reach 'completed' state to receive payment",
+    "refund_guard ensures 100% refund on cancellation — no merchant approval needed",
+    "No buy_guard needed — D2C doesn't gate purchases (open storefront)",
+    "Arbitration is optional — add when dispute volume justifies the cost",
+    "Service ↔ Guard circular dependency: create Service (unpublished) → create Guards → update Service (publish)",
+];
+const SUPPORTED_INDUSTRY_SET = new Set([
+    "freelance", "rental", "education", "travel", "subscription", "retail", "retail_d2c",
+]);
+function fetchTemplate(name) {
+    const traitsLookupName = name === "retail_d2c" ? "retail" : name;
+    const traits = getIndustryTraits(traitsLookupName) ?? GENERAL_TRAITS;
+    const isSupported = SUPPORTED_INDUSTRY_SET.has(name);
+    const industryLookupName = name === "retail_d2c" ? "retail" : name;
+    const risk_checks = isSupported
+        ? getIndustryRiskChecks(industryLookupName)
+        : [];
+    const needs = isSupported
+        ? getIndustryNeeds(industryLookupName)
+        : [];
+    const flywheel = getFlywheelForIndustry(traitsLookupName) ?? GENERAL_FLYWHEEL;
+    let machine_shape;
+    let guards;
+    let allocator;
+    let key_risk;
+    let build_notes;
+    if (name === "retail") {
+        machine_shape = RETAIL_MACHINE_SHAPE;
+        guards = RETAIL_GUARDS;
+        allocator = RETAIL_ALLOCATOR;
+        key_risk = RETAIL_KEY_RISK;
+        build_notes = RETAIL_BUILD_NOTES;
+    }
+    else if (name === "retail_d2c") {
+        machine_shape = RETAIL_D2C_MACHINE_SHAPE;
+        guards = RETAIL_D2C_GUARDS;
+        allocator = RETAIL_D2C_ALLOCATOR;
+        key_risk = RETAIL_D2C_KEY_RISK;
+        build_notes = RETAIL_D2C_BUILD_NOTES;
+    }
+    else if (name === "general") {
+        const sm = getScenarioMode("general");
+        machine_shape = GENERAL_MACHINE_SHAPE;
+        guards = [];
+        allocator = GENERAL_ALLOCATOR;
+        key_risk = sm?.key_risk ?? "No safety net — user must design all trust mechanisms manually";
+        build_notes = sm?.build_notes;
+    }
+    else {
+        const sm = getScenarioMode(name);
+        if (!sm) {
+            throw new Error(`[modes.ts] No scenario mode found for industry: ${name}`);
+        }
+        machine_shape = sm.machine_shape;
+        guards = sm.guards;
+        allocator = sm.allocator;
+        key_risk = sm.key_risk;
+        build_notes = sm.build_notes;
+    }
+    return { traits, risk_checks, needs, flywheel, machine_shape, guards, allocator, key_risk, build_notes };
+}
+export const BUILTIN_MODES = [
+    {
+        name: "freelance",
+        display_name: "Freelance",
+        version: "v1",
+        source: "builtin",
+        ...fetchTemplate("freelance"),
+        capabilities_used: [
+            "permission.index_create", "permission.role_assign",
+            "guard.validate_buy", "guard.validate_wip_hash",
+            "machine.node_topology",
+            "treasury.owner_receive",
+            "allocation.distribute", "allocation.distribute_milestone",
+            "service.publish", "progress.advance",
+            "arb.vote_weighted", "contact.im_create",
+        ],
+        config_overrides: {
+            service: { setting_locked_time: "30d", engagement_type: "milestone" },
+            machine: { wip_required: true, wip_hash_algorithm: "sha256", acceptance_gate: true },
+        },
+        expected_benefits: [
+            { metric: "Dispute rate reduction", expected_value: "40%", evidence: "WIP hash + milestone allocation enforces delivery evidence" },
+            { metric: "Delivery confirmation efficiency", expected_value: "+50%", evidence: "acceptance gate automates acceptance workflow" },
+            { metric: "Provider payment assurance", expected_value: "100%", evidence: "Funds auto-release to provider after accepted node" },
+        ],
+        risk_appetite: "balanced",
+        risk_constraints: {
+            require_arbitration: true,
+            require_compensation_fund: false,
+            require_wip_evidence: true,
+            other_constraints: [
+                "setting_locked_time >= 7d to lock engagement-period rules",
+                "ISSUE-P1-4: 48h auto-accept requires off-chain keeper (WoWok Guard does not support time-based triggers). Deploy a keeper service that polls Progress objects in 'delivered' state and calls adminUnhold (permission 224) after 48h timeout. See keeper template in docs.",
+            ],
+        },
+        applicable_conditions: {
+            business_scale: "small",
+            min_daily_orders: 1,
+            other_conditions: ["Suitable for mid-to-long-term project delivery", "Requires milestone-based phased acceptance"],
+        },
+        similar_industries: ["rental", "education"],
+        novel_capabilities: ["allocation.distribute_milestone"],
+    },
+    {
+        name: "rental",
+        display_name: "Rental",
+        version: "v1",
+        source: "builtin",
+        ...fetchTemplate("rental"),
+        capabilities_used: [
+            "permission.index_create", "permission.role_assign",
+            "guard.validate_buy", "guard.validate_wip_hash",
+            "machine.node_topology",
+            "treasury.owner_receive",
+            "allocation.distribute",
+            "service.publish", "progress.advance",
+            "arb.vote_weighted", "contact.im_create",
+        ],
+        config_overrides: {
+            treasury: { deposit_escrow: true, deposit_deductible: true },
+            machine: { wip_required: true, wip_stages: ["handover_out", "returned"], inspection_gate: true },
+        },
+        expected_benefits: [
+            { metric: "Deposit dispute rate", expected_value: "-60%", evidence: "pre-rental WIP mandatorily records item's original state" },
+            { metric: "Damage liability accuracy", expected_value: "+70%", evidence: "pre/post WIP hash comparison eliminates unfounded deductions" },
+            { metric: "Trust score", expected_value: "+25%", evidence: "compensation_fund covers damage risk" },
+        ],
+        risk_appetite: "conservative",
+        risk_constraints: {
+            require_arbitration: true,
+            require_compensation_fund: true,
+            require_wip_evidence: true,
+            max_single_transaction: 10000,
+            compensation_fund_coverage_ratio: 10,
+            other_constraints: ["Deposit must be escrowed (no direct transfer)", "lock_duration >= 7d to prevent arbitrary merchant withdrawal"],
+        },
+        applicable_conditions: {
+            business_scale: "small",
+            min_daily_orders: 1,
+            other_conditions: ["Requires physical item handover", "Has logistics or offline delivery leg"],
+        },
+        similar_industries: ["retail", "travel"],
+        novel_capabilities: [],
+    },
+    {
+        name: "education",
+        display_name: "Education",
+        version: "v1",
+        source: "builtin",
+        ...fetchTemplate("education"),
+        capabilities_used: [
+            "permission.index_create", "permission.role_assign",
+            "guard.validate_buy", "guard.validate_wip_hash",
+            "machine.node_topology",
+            "treasury.owner_receive",
+            "allocation.distribute", "allocation.distribute_milestone",
+            "service.publish", "progress.advance",
+            "arb.vote_weighted", "contact.im_create",
+        ],
+        config_overrides: {
+            allocation: {
+                strategy: {
+                    recipient: "entity",
+                    count: 1,
+                    mode: "amount",
+                    description: "1/N of tuition released per session attendance",
+                },
+                session_threshold: true,
+            },
+            service: { setting_locked_time: "120d", anti_runaway: true },
+        },
+        expected_benefits: [
+            { metric: "Refund dispute rate", expected_value: "-50%", evidence: "per-session release distributes tuition by class" },
+            { metric: "Institution runaway risk", expected_value: "eliminated", evidence: "Funds release per session; undelivered portion is refundable" },
+            { metric: "Attendance traceability", expected_value: "100%", evidence: "attendance_guard signs each session" },
+        ],
+        risk_appetite: "conservative",
+        risk_constraints: {
+            require_arbitration: true,
+            require_compensation_fund: true,
+            require_wip_evidence: false,
+            other_constraints: ["setting_locked_time covers the entire term (>=90d)", "Long-cycle projects must monitor >90d progress"],
+        },
+        applicable_conditions: {
+            business_scale: "medium",
+            min_daily_orders: 1,
+            other_conditions: ["Long-cycle delivery", "Requires per-session acceptance", "Regulatory intensity: medium"],
+        },
+        similar_industries: ["freelance", "subscription"],
+        novel_capabilities: ["allocation.distribute_milestone"],
+    },
+    {
+        name: "travel",
+        display_name: "Travel",
+        version: "v1",
+        source: "builtin",
+        ...fetchTemplate("travel"),
+        capabilities_used: [
+            "permission.index_create", "permission.role_assign",
+            "guard.validate_buy", "guard.validate_wip_hash",
+            "machine.node_topology",
+            "treasury.owner_receive",
+            "allocation.distribute",
+            "service.publish", "progress.advance",
+            "arb.vote_weighted", "contact.im_create",
+        ],
+        config_overrides: {
+            allocation: {
+                strategy: {
+                    recipient: "entity",
+                    count: 3,
+                    mode: "amount",
+                    description: "Deposit 20% to agency, final 80% to agency, then agency-side Allocation splits to hotel/guide/driver per segment",
+                },
+                multi_tier_waterfall: true,
+                guard_chaining: true,
+            },
+            service: { supply_chain_suborders: true, segment_guard_required: true },
+        },
+        expected_benefits: [
+            { metric: "Fund transparency", expected_value: "100%", evidence: "multi-tier allocation splits per segment to hotel/guide/driver" },
+            { metric: "Itinerary change disputes", expected_value: "-45%", evidence: "segment WIP accepts each leg" },
+            { metric: "Breach compensation assurance", expected_value: "+60%", evidence: "compensation_fund covers itinerary breach" },
+        ],
+        risk_appetite: "balanced",
+        risk_constraints: {
+            require_arbitration: true,
+            require_compensation_fund: true,
+            require_wip_evidence: true,
+            other_constraints: ["Multi-tier allocation requires guard chaining validation", "deposit 20% + final 80% two-stage payment"],
+        },
+        applicable_conditions: {
+            business_scale: "medium",
+            min_daily_orders: 1,
+            other_conditions: ["Multi-segment itinerary combination", "Requires hotel/guide/driver multi-party allocation"],
+        },
+        similar_industries: ["rental", "education"],
+        novel_capabilities: [],
+    },
+    {
+        name: "subscription",
+        display_name: "Subscription",
+        version: "v1",
+        source: "builtin",
+        ...fetchTemplate("subscription"),
+        capabilities_used: [
+            "permission.index_create", "permission.role_assign",
+            "guard.validate_buy",
+            "machine.node_topology",
+            "treasury.owner_receive",
+            "allocation.distribute",
+            "service.publish", "progress.advance",
+            "arb.vote_weighted", "reward.claim_guard", "contact.im_create",
+        ],
+        config_overrides: {
+            machine: {
+                no_auto_renew_trap: true,
+                user_confirmed_charge: true,
+                cancel_anytime: true,
+                next_period_effective: true,
+            },
+            service: { creator_data_subscription: true, periodic_billing: true },
+        },
+        expected_benefits: [
+            { metric: "Renewal rate", expected_value: "+25%", evidence: "loyalty reward + transparent subscription mechanism" },
+            { metric: "Cancellation disputes", expected_value: "eliminated", evidence: "cancel anytime + no auto-renew trap" },
+            { metric: "Creator retention", expected_value: "+30%", evidence: "deliver_guard_wip prevents content dropout" },
+        ],
+        risk_appetite: "aggressive",
+        risk_constraints: {
+            require_arbitration: false,
+            require_compensation_fund: false,
+            require_wip_evidence: false,
+            compensation_fund_coverage_ratio: 3,
+            other_constraints: ["Forbid dead-end nodes (prevent lock-in)", "charge_guard requires user confirmation each period"],
+        },
+        applicable_conditions: {
+            business_scale: "small",
+            min_daily_orders: 5,
+            other_conditions: ["Pure-digital delivery", "Periodic content or SaaS service"],
+        },
+        similar_industries: ["freelance", "education"],
+        novel_capabilities: [],
+    },
+    {
+        name: "retail",
+        display_name: "Retail",
+        version: "v1",
+        source: "builtin",
+        ...fetchTemplate("retail"),
+        capabilities_used: [
+            "permission.index_create", "permission.role_assign",
+            "guard.validate_buy", "guard.validate_wip_hash",
+            "machine.node_topology",
+            "treasury.owner_receive",
+            "allocation.distribute",
+            "service.publish", "progress.advance",
+            "arb.vote_weighted", "reward.claim_guard", "contact.im_create",
+        ],
+        config_overrides: {
+            machine: {
+                wip_required: true,
+                wip_field: "tracking_number",
+                confirm_gate: true,
+                refund_requires_approval: true,
+            },
+            service: { logistics_mode: "standard", first_order_discount: true },
+        },
+        expected_benefits: [
+            { metric: "Return dispute rate", expected_value: "-35%", evidence: "logistics WIP + refund path assurance" },
+            { metric: "Repurchase rate", expected_value: "+20%", evidence: "spend cashback reward" },
+            { metric: "Product authenticity traceability", expected_value: "100%", evidence: "WIP verifies product/logistics info" },
+        ],
+        risk_appetite: "conservative",
+        risk_constraints: {
+            require_arbitration: true,
+            require_compensation_fund: true,
+            require_wip_evidence: false,
+            compensation_fund_coverage_ratio: 5,
+            other_constraints: ["refund_window >= 7d", "confirm_gate: only buyer can confirm receipt"],
+        },
+        applicable_conditions: {
+            business_scale: "medium",
+            min_daily_orders: 10,
+            other_conditions: ["Has logistics shipping leg", "High-frequency small-ticket transactions"],
+        },
+        similar_industries: ["rental", "subscription"],
+        novel_capabilities: [],
+    },
+    {
+        name: "retail_d2c",
+        display_name: "Retail D2C (Direct-to-Consumer)",
+        version: "v1",
+        source: "builtin",
+        ...fetchTemplate("retail_d2c"),
+        capabilities_used: [
+            "permission.index_create", "permission.role_assign",
+            "guard.validate_withdraw", "guard.validate_refund",
+            "machine.node_topology",
+            "allocation.distribute",
+            "service.publish", "progress.advance",
+            "contact.im_create",
+        ],
+        config_overrides: {
+            machine: {
+                wip_required: false,
+                confirm_gate: true,
+                refund_requires_approval: false,
+            },
+            service: { logistics_mode: "merchant_managed", multi_recipient_allocation: true },
+        },
+        expected_benefits: [
+            { metric: "Merchant revenue share", expected_value: "97%", evidence: "No platform commission — only 3% processing fee" },
+            { metric: "Fund safety", expected_value: "contract-grade", evidence: "Allocation escrow + Guard verification replaces platform custody" },
+            { metric: "Delivery reliability", expected_value: "high", evidence: "withdraw_guard enforces delivery confirmation before payment" },
+        ],
+        risk_appetite: "balanced",
+        risk_constraints: {
+            require_arbitration: false,
+            require_compensation_fund: false,
+            require_wip_evidence: false,
+            other_constraints: [
+                "Allocation escrow required (withdraw_guard + refund_guard)",
+                "Service ↔ Guard circular dependency requires 3-step creation pattern",
+            ],
+        },
+        applicable_conditions: {
+            business_scale: "small",
+            min_daily_orders: 1,
+            other_conditions: ["Independent storefront (no marketplace)", "Merchant-managed logistics", "Allocation escrow model"],
+        },
+        similar_industries: ["retail", "subscription"],
+        novel_capabilities: ["Allocation escrow as platform-custody alternative", "Multi-recipient allocation (merchant + processor)"],
+    },
+    {
+        name: "general",
+        display_name: "General",
+        version: "v1",
+        source: "builtin",
+        ...fetchTemplate("general"),
+        capabilities_used: [
+            "permission.index_create",
+            "machine.node_topology",
+            "treasury.owner_receive",
+            "allocation.distribute",
+            "service.publish",
+            "progress.advance",
+        ],
+        expected_benefits: [
+            { metric: "Flexibility", expected_value: "100%", evidence: "User customizes all trust mechanism parameters" },
+            { metric: "Degraded safety", expected_value: "usable", evidence: "Can fall back to general at any time" },
+        ],
+        risk_appetite: "balanced",
+        risk_constraints: {
+            require_arbitration: false,
+            require_compensation_fund: false,
+            require_wip_evidence: false,
+        },
+        applicable_conditions: {
+            business_scale: "small",
+            other_conditions: ["Fallback degraded mode", "Hybrid scenarios not covered by other industries"],
+        },
+        similar_industries: [],
+        novel_capabilities: [],
+    },
+];

package/dist/extensions/registry.d.ts

@@ -0,0 +1,50 @@
+import type { IndustryMode, UserDefinedMode, Blueprint, BlueprintObject, BlueprintEdge, ProjectContext, ModeEvaluation, ModeMigrationEvaluation } from "./types.js";
+export declare class IndustryModeRegistry {
+    private static instance;
+    private registrations;
+    private userModes;
+    private aliases;
+    private evaluator;
+    private initialized;
+    static Instance(): IndustryModeRegistry;
+    private constructor();
+    registerMode(mode: IndustryMode, aliases?: string[]): boolean;
+    getMode(name: string): IndustryMode | undefined;
+    listModes(): IndustryMode[];
+    resolveAlias(name: string): string;
+    hasMode(name: string): boolean;
+    evaluateMode(name: string, intent: string, context: ProjectContext): ModeEvaluation;
+    evaluateMigration(sourceName: string, targetName: string): ModeMigrationEvaluation;
+    registerUserMode(mode: UserDefinedMode, userId: string): boolean;
+    deriveMode(sourceMode: string, modifications: Partial<UserDefinedMode>, userId: string, newName: string, newDisplayName?: string): UserDefinedMode | undefined;
+    evolveMode(modeName: string, updates: Partial<UserDefinedMode>, userId: string, changeDescription: string, bumpVersion?: boolean): UserDefinedMode | undefined;
+    listUserModes(userId: string): UserDefinedMode[];
+    getUserMode(modeName: string, userId: string): UserDefinedMode | undefined;
+    unregisterUserMode(modeName: string, userId: string): boolean;
+    private userModeKey;
+    private bumpPatchVersion;
+    applyTemplate(name: string, intent: string, context: ProjectContext): Blueprint;
+    applyUserMode(modeName: string, userId: string, intent: string, context: ProjectContext): Blueprint;
+    private doApplyTemplate;
+    validateBlueprint(objects: BlueprintObject[], edges: BlueprintEdge[], mode: IndustryMode): {
+        errors: string[];
+        warnings: string[];
+    };
+    private buildObjects;
+    private buildPermissionIndexes;
+    private applyConfigOverrides;
+    private applyConfigOverrideRules;
+    private evaluateCondition;
+    private setNestedField;
+    private buildEdges;
+    private makeEdge;
+    private buildSteps;
+    private defaultScenarios;
+    private recordCapabilitiesUsed;
+    private deriveGuardShortName;
+    private getFirstServiceGuardName;
+    private makeObject;
+    private registerBuiltinModes;
+}
+export declare function getIndustryModeRegistry(): IndustryModeRegistry;
+export declare const INDUSTRY_MODE_REGISTRY_VERSION = 2.1;