@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/scenario-modes.js

@@ -0,0 +1,302 @@
+export const SCENARIO_MODES = [
+    {
+        name: "freelance",
+        phase: 1,
+        industry: "Design / dev / consulting / writing",
+        trust_pattern: "Milestone allocation, acceptance gate",
+        traits: {
+            has_logistics: false,
+            communication_heavy: true,
+            pure_digital: true,
+            long_cycle: true,
+            deposit_required: false,
+            multi_tier_allocation: false,
+        },
+        machine_shape: [
+            { name: "ordered", role: "Customer places order, payment escrowed" },
+            { name: "delivering", role: "Provider submits deliverable (WIP hash)" },
+            { name: "delivered", role: "Deliverable available for review" },
+            { name: "accepted", role: "Customer signs acceptance" },
+            { name: "completed", role: "Funds released to provider" },
+            { name: "refunded", role: "Customer-initiated refund path" },
+            { name: "cancelled", role: "Pre-delivery cancellation" },
+        ],
+        guards: [
+            { template_id: "buy_guard_identity", host: "service", purpose: "Customer identity check on purchase" },
+            { template_id: "deliver_guard_wip", host: "machine", purpose: "Provider must submit WIP hash for deliverable" },
+            { template_id: "accept_guard_signer", host: "machine", purpose: "Only customer can sign acceptance" },
+            { template_id: "withdraw_guard_permission", host: "machine", purpose: "Only provider can withdraw after acceptance" },
+            { template_id: "refund_guard_signer", host: "machine", purpose: "Only customer can initiate refund" },
+        ],
+        allocator: {
+            recipient: "signer",
+            count: 2,
+            mode: "amount",
+            description: "100% to provider on accepted; 100% refund to customer on refunded",
+        },
+        key_risk: "Customer never accepts delivery — provider cannot get paid",
+        build_notes: [
+            "Use Service `setting_locked_time` to lock rules for the engagement duration",
+            "WIP hash on deliverable is mandatory — protects provider in disputes",
+            "Acceptance gate is the trust pivot — both parties must agree on criteria",
+        ],
+    },
+    {
+        name: "rental",
+        phase: 1,
+        industry: "Equipment / vehicle / property rental",
+        trust_pattern: "Deposit escrow, return inspection",
+        traits: {
+            has_logistics: true,
+            communication_heavy: true,
+            pure_digital: false,
+            long_cycle: false,
+            deposit_required: true,
+            multi_tier_allocation: false,
+        },
+        machine_shape: [
+            { name: "reserved", role: "Customer reserves item, pays deposit + rent" },
+            { name: "handover_out", role: "Owner hands over item, records pre-rental WIP" },
+            { name: "in_use", role: "Rental period active" },
+            { name: "returned", role: "Customer returns item" },
+            { name: "inspected", role: "Owner inspects returned item" },
+            { name: "deposit_refunded", role: "No damage — full deposit returned" },
+            { name: "deposit_deducted", role: "Damage found — deposit partially deducted" },
+        ],
+        guards: [
+            { template_id: "deposit_guard_amount", host: "service", purpose: "Verify deposit amount matches listing" },
+            { template_id: "return_guard_wip", host: "machine", purpose: "Return must include post-rental WIP" },
+            { template_id: "inspect_guard_signer", host: "machine", purpose: "Only owner can submit inspection result" },
+            { template_id: "refund_guard_permission", host: "machine", purpose: "Refund requires owner permission" },
+            { template_id: "damage_guard_wip", host: "machine", purpose: "Damage claim requires pre+post WIP comparison" },
+        ],
+        allocator: {
+            recipient: "entity",
+            count: 3,
+            mode: "amount",
+            description: "Rent to owner; refund to customer; deduction to owner (damage case)",
+        },
+        key_risk: "Owner claims damage without pre-rental WIP — customer loses deposit unfairly",
+        build_notes: [
+            "Pre-rental WIP is non-negotiable — without it, damage claims fail",
+            "Deposit must be escrowed, not direct-transferred — enables fair deduction",
+            "Inspection gate prevents customer from denying damage",
+        ],
+    },
+    {
+        name: "education",
+        phase: 2,
+        industry: "Courses / training / tutoring",
+        trust_pattern: "Periodic release per session, attendance Guard",
+        traits: {
+            has_logistics: false,
+            communication_heavy: true,
+            pure_digital: false,
+            long_cycle: true,
+            deposit_required: true,
+            multi_tier_allocation: false,
+        },
+        machine_shape: [
+            { name: "enrolled", role: "Student enrolls, pays tuition" },
+            { name: "session_N", role: "Per-session attendance (1..N)" },
+            { name: "completed", role: "All sessions delivered" },
+            { name: "refunded", role: "Institution-approved refund" },
+        ],
+        guards: [
+            { template_id: "attendance_guard_signer", host: "machine", purpose: "Per-session student attendance signature" },
+            { template_id: "refund_guard_permission", host: "machine", purpose: "Institution approval OR arbiter for refund" },
+        ],
+        allocator: {
+            recipient: "entity",
+            count: 1,
+            mode: "amount",
+            description: "1/N of tuition released per session attendance; unearned portion refundable",
+        },
+        key_risk: "Tutoring institutions run away with prepaid tuition",
+        build_notes: [
+            "Use Service `setting_locked_time` to lock rules mid-semester (regulatory compliance)",
+            "Attendance Guard needs WIP hash for session content commitment",
+            "Per-session release requires threshold-based trigger",
+        ],
+    },
+    {
+        name: "travel",
+        phase: 2,
+        industry: "Custom tours / multi-segment trips",
+        trust_pattern: "Multi-tier allocation per segment",
+        traits: {
+            has_logistics: false,
+            communication_heavy: true,
+            pure_digital: false,
+            long_cycle: true,
+            deposit_required: true,
+            multi_tier_allocation: true,
+        },
+        machine_shape: [
+            { name: "ordered", role: "Customer books tour, pays deposit + final" },
+            { name: "segment_D1", role: "Segment 1 (e.g., hotel check-in)" },
+            { name: "segment_D2", role: "Segment 2 (e.g., guided tour)" },
+            { name: "returned", role: "Trip completed, customer returns" },
+            { name: "completed", role: "All segments delivered, funds released" },
+            { name: "refunded", role: "Trip interruption refund" },
+        ],
+        guards: [
+            { template_id: "segment_guard_wip", host: "machine", purpose: "Per-segment arrival WIP (hotel check-in, etc.)" },
+            { template_id: "refund_guard_permission", host: "machine", purpose: "Agency approval OR arbiter for trip interruption" },
+        ],
+        allocator: {
+            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",
+        },
+        key_risk: "Paid in full then service shrinks — multi-tier transparency prevents this",
+        build_notes: [
+            "Multi-tier Allocation is WoWok's unique advantage over traditional travel platforms",
+            "segment_guard needs standardized WIP templates per segment type (hotel, transport, activity)",
+            "Multi-tier waterfall needs guard chaining validation",
+        ],
+    },
+    {
+        name: "subscription",
+        phase: 3,
+        industry: "SaaS / content membership / periodic service",
+        trust_pattern: "Periodic charge, cancel Guard",
+        traits: {
+            has_logistics: false,
+            communication_heavy: false,
+            pure_digital: true,
+            long_cycle: true,
+            deposit_required: false,
+            multi_tier_allocation: false,
+        },
+        machine_shape: [
+            { name: "subscribed", role: "Subscriber signs up" },
+            { name: "charge_period_N", role: "Periodic charge (1..N)" },
+            { name: "deliver_period_N", role: "Per-period delivery" },
+            { name: "cancelled", role: "Subscriber cancels — takes effect next period" },
+            { name: "expired", role: "Subscription term ends" },
+        ],
+        guards: [
+            { template_id: "charge_guard_signer", host: "machine", purpose: "User confirms each charge — no auto-renew trap" },
+            { template_id: "cancel_guard_signer", host: "machine", purpose: "User cancels anytime, next-period effective" },
+            { template_id: "deliver_guard_wip", host: "machine", purpose: "Creator WIP hash per period — prevents content abandonment" },
+        ],
+        allocator: {
+            recipient: "entity",
+            count: 1,
+            mode: "amount",
+            description: "Each charge → 100% to creator; unearned periods → refund to subscriber",
+        },
+        key_risk: "Auto-renew trap and platform-takes-30% — WoWok native solution",
+        build_notes: [
+            "Pure digital — native WoWok soil",
+            "charge_guard needs periodic trigger (off-chain scheduler + on-chain Guard)",
+            "Targets indie creators, niche SaaS, paid newsletters",
+        ],
+    },
+    {
+        name: "general",
+        phase: 1,
+        industry: "Anything not covered / hybrid",
+        trust_pattern: "User-defined from scratch",
+        traits: {
+            has_logistics: false,
+            communication_heavy: false,
+            pure_digital: false,
+            long_cycle: false,
+            deposit_required: false,
+            multi_tier_allocation: false,
+        },
+        machine_shape: [],
+        guards: [],
+        allocator: {
+            recipient: "signer",
+            count: 0,
+            mode: "amount",
+            description: "User-defined — no defaults",
+        },
+        key_risk: "No safety net — user must design all trust mechanisms manually",
+        build_notes: [
+            "Escape hatch: any user can switch to general mode at any time",
+            "Already-created objects under a previous mode remain on-chain (REUSE pattern)",
+            "wowok-machine / wowok-guard / wowok-provider become primary references",
+        ],
+    },
+];
+export function matchScenarioMode(description) {
+    const d = description.toLowerCase();
+    const traits = inferScenarioTraits(description);
+    const scores = SCENARIO_MODES.map((mode) => {
+        let score = 0;
+        let total = 0;
+        for (const key of Object.keys(traits)) {
+            total += 1;
+            if (mode.traits[key] === traits[key])
+                score += 1;
+        }
+        if (mode.name !== "general") {
+            const keywords = MODE_KEYWORDS[mode.name] ?? [];
+            for (const kw of keywords) {
+                if (d.includes(kw))
+                    score += 0.5;
+            }
+        }
+        return { mode, score, total };
+    });
+    let best = scores[0];
+    for (const s of scores) {
+        if (s.score > best.score)
+            best = s;
+    }
+    const confidence = best.total > 0 ? Math.min(1, best.score / best.total) : 0;
+    return { mode: best.mode, confidence };
+}
+const MODE_KEYWORDS = {
+    freelance: ["freelance", "design", "develop", "consult", "write", "consulting"],
+    rental: ["rent", "rental", "lease", "borrow", "equipment", "vehicle", "property"],
+    education: ["course", "training", "tutor", "teach", "education", "class"],
+    travel: ["tour", "travel", "trip", "itinerary", "vacation"],
+    subscription: ["subscribe", "subscription", "membership", "saas", "newsletter", "recurring"],
+};
+export function inferScenarioTraits(description) {
+    const d = description.toLowerCase();
+    return {
+        has_logistics: /ship|delivery|equipment|vehicle|physical|goods/.test(d),
+        communication_heavy: /consult|discuss|back-and-forth|custom|bespoke|negotiate/.test(d),
+        pure_digital: /digital|file|download|online|software|code|design|content/.test(d),
+        long_cycle: /month|long-term|engagement|project|semester|period/.test(d),
+        deposit_required: /deposit|escrow|prepay|tuition|reserve/.test(d),
+        multi_tier_allocation: /tier|segment|multi-|agency|hotel|guide|driver/.test(d),
+    };
+}
+export const MODE_COMPOSITIONS = [
+    {
+        modes: ["freelance", "subscription"],
+        use_case: "Retainer consulting (monthly + milestone)",
+        conflict_resolution: "Allocator: split into retainer (subscription) + milestone (freelance)",
+    },
+    {
+        modes: ["rental", "education"],
+        use_case: "Equipment training rental",
+        conflict_resolution: "Machine: extend rental nodes with attendance gates",
+    },
+    {
+        modes: ["travel", "rental"],
+        use_case: "Tour with equipment",
+        conflict_resolution: "Allocator: segment allocation + deposit escrow side-by-side",
+    },
+];
+export function getScenarioMode(name) {
+    return SCENARIO_MODES.find((m) => m.name === name);
+}
+export function listScenarioModes() {
+    return SCENARIO_MODES;
+}
+export function getShippedModes() {
+    return SCENARIO_MODES.filter((m) => m.phase === 1);
+}
+export function getModeCompositions(name) {
+    return MODE_COMPOSITIONS.filter((c) => c.modes.includes(name));
+}
+export const SCENARIO_MODES_VERSION = 1;

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

@@ -0,0 +1,152 @@
+import { type ServiceRiskAssessment } from "./service-risk.js";
+export type ServiceConfirmGateStatus = "approved" | "blocked_checklist" | "blocked_risk" | "blocked_user" | "blocked_environment";
+export interface ServiceConfirmGateResult {
+    status: ServiceConfirmGateStatus;
+    checklist_result: ServiceChecklistResult;
+    risk_result?: ServiceRiskAssessment;
+    user_confirmation?: ServiceUserConfirmation;
+    environment_result?: ServiceEnvironmentResult;
+    confirmation_text?: string;
+    block_reason?: string;
+    decision_record: ServiceDecisionRecord;
+}
+export interface ServiceChecklistResult {
+    all_passed: boolean;
+    items: ServiceChecklistItem[];
+}
+export interface ServiceChecklistItem {
+    id: string;
+    description: string;
+    passed: boolean;
+    message: string;
+}
+export interface ServiceUserConfirmation {
+    questions_asked: ServiceConfirmationQuestion[];
+    responses: ServiceConfirmationResponse[];
+    all_confirmed: boolean;
+}
+export interface ServiceConfirmationQuestion {
+    id: string;
+    question: string;
+    requires_explicit_yes: boolean;
+    related_risk_ids?: string[];
+}
+export interface ServiceConfirmationResponse {
+    question_id: string;
+    response: "yes" | "no" | "skip";
+}
+export interface ServiceEnvironmentResult {
+    passed: boolean;
+    checks: {
+        name: string;
+        passed: boolean;
+        message: string;
+    }[];
+}
+export interface ServiceDecisionRecord {
+    timestamp: string;
+    gate_version: string;
+    final_status: ServiceConfirmGateStatus;
+    layers_passed: string[];
+    layers_failed: string[];
+}
+export interface ServiceJsonForConfirm {
+    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 interface ServiceConfirmGateInput {
+    service_json: ServiceJsonForConfirm;
+    intent?: string;
+    target_objects_types?: string[];
+    current_bPublished?: boolean;
+    current_bPaused?: boolean;
+    current_compensation_fund_balance?: string;
+    current_setting_lock_duration?: string;
+    current_arbitrations_count?: number;
+    current_rewards_count?: number;
+    current_repositories_count?: number;
+    current_sales_count?: number;
+    current_machine_bound?: boolean;
+    current_order_allocators_set?: boolean;
+    skip_user_confirmation?: boolean;
+    skip_environment_check?: boolean;
+}
+export declare const SERVICE_PUBLISH_CHECKLIST: ServiceChecklistItem[];
+export declare const SERVICE_CONFIRMATION_QUESTIONS: ServiceConfirmationQuestion[];
+export declare const SERVICE_CONFIRM_VERSION = "1.0.0";
+export declare function runServiceConfirmGate(input: ServiceConfirmGateInput): ServiceConfirmGateResult;
+export interface ServiceProgressiveCheckResult {
+    stage: "checklist" | "risk" | "confirmation" | "environment" | "complete";
+    status: "pass" | "fail" | "pending";
+    message: string;
+    next_action?: string;
+}
+export declare function progressiveServiceCheck(input: ServiceConfirmGateInput): ServiceProgressiveCheckResult;