@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/order-context.js

@@ -0,0 +1,390 @@
+import { MAX_AGENT_COUNT, MAX_DISPUTE_COUNT, } from "@wowok/wowok";
+import { ORDER_LIFECYCLE_EVENTS, inferSceneFromIntent, getScenesByOperationField, getScenesByPermissionLayer, getEmittedEvents, } from "./order-ledger.js";
+import { getTemplatesByScene, suggestTemplateFromIntent, } from "./order-templates.js";
+import { matchSemanticPattern, } from "./order-translation.js";
+import { getAllOrderRiskRules, assessOrderRisks, } from "./order-risk.js";
+import { initPuzzleFromIntent, checkPuzzleCompleteness, verifySnapshotMechanism, } from "./order-puzzle.js";
+import { ORDER_PUBLISH_CHECKLIST, ORDER_CONFIRMATION_QUESTIONS, } from "./order-confirm.js";
+export const ORDER_CONTEXT_VERSION = "1.0.0";
+export function buildOrderContext(input) {
+    const max_length = input.max_length ?? 4000;
+    let matched_scene;
+    if (input.intent) {
+        matched_scene = inferSceneFromIntent(input.intent);
+    }
+    if (!matched_scene && input.target_operation_field) {
+        const scenes = getScenesByOperationField(input.target_operation_field);
+        if (scenes.length > 0)
+            matched_scene = scenes[0];
+    }
+    if (!matched_scene && input.target_permission_layer) {
+        const scenes = getScenesByPermissionLayer(input.target_permission_layer);
+        if (scenes.length > 0)
+            matched_scene = scenes[0];
+    }
+    let matched_template;
+    if (matched_scene) {
+        const templates = getTemplatesByScene(matched_scene.id);
+        if (templates.length > 0)
+            matched_template = templates[0];
+    }
+    if (!matched_template && input.intent) {
+        matched_template = suggestTemplateFromIntent(input.intent);
+    }
+    let matched_pattern;
+    if (input.intent) {
+        const patterns = matchSemanticPattern(input.intent);
+        if (patterns.length > 0)
+            matched_pattern = patterns[0];
+    }
+    let puzzle_state;
+    let puzzle_completeness;
+    if (input.mode === "initial_design" && input.intent) {
+        puzzle_state = initPuzzleFromIntent({ rule_sentence: input.intent });
+        puzzle_completeness = checkPuzzleCompleteness(puzzle_state);
+    }
+    const relevant_risks = filterRiskRules(input.mode, input.stakeholder, matched_scene);
+    let risk_assessment;
+    if (input.mode === "pre_execute" && input.order_json && input.current_state) {
+        risk_assessment = assessOrderRisks(input.current_state);
+    }
+    const relevant_checklist = filterChecklist(input.mode);
+    const relevant_questions = filterQuestions(input.mode);
+    let snapshot_verification;
+    if (puzzle_state && (input.mode === "initial_design" || input.mode === "mid_design_review")) {
+        snapshot_verification = verifySnapshotMechanism(puzzle_state);
+    }
+    const emitted = getEmittedEvents();
+    const inferred = ORDER_LIFECYCLE_EVENTS.filter(e => !e.actually_emitted);
+    const event_audit = { emitted, inferred };
+    const cross_object_refs = buildCrossObjectRefs(matched_scene);
+    const onchain_constraints = buildOnchainConstraints();
+    const rendering_hints = buildRenderingHints(input.mode, max_length, !!input.order_json?.transfer_to, !!input.order_json?.arb_claim_compensation, !!snapshot_verification?.snapshot_understood);
+    return {
+        version: ORDER_CONTEXT_VERSION,
+        mode: input.mode,
+        stakeholder_perspective: input.stakeholder,
+        matched_scene,
+        matched_template,
+        matched_pattern,
+        puzzle_state,
+        puzzle_completeness,
+        relevant_risks,
+        risk_assessment,
+        relevant_checklist,
+        relevant_questions,
+        cross_object_refs,
+        onchain_constraints,
+        rendering_hints,
+        snapshot_verification,
+        event_audit,
+    };
+}
+function filterRiskRules(mode, stakeholder, scene) {
+    const rules = getAllOrderRiskRules();
+    if (mode === "initial_design") {
+        return rules.filter(r => r.category === "structural" || r.category === "semantic");
+    }
+    if (mode === "pre_execute") {
+        return rules;
+    }
+    if (mode === "stakeholder_review" && stakeholder) {
+        if (stakeholder === "owner") {
+            return rules.filter(r => r.category === "authority" || r.category === "lifecycle");
+        }
+        if (stakeholder === "agent") {
+            return rules.filter(r => r.id === "R-O-3-01" || r.id === "R-O-3-02" || r.id === "R-O-1-04" || r.id === "R-O-2-02");
+        }
+        if (stakeholder === "arbitrator") {
+            return rules.filter(r => r.category === "lifecycle" || r.id === "R-O-3-03");
+        }
+        if (stakeholder === "service_provider") {
+            return rules.filter(r => r.category === "cross_object" || r.id === "R-O-2-01");
+        }
+    }
+    if (mode === "dispute_resolution") {
+        return rules.filter(r => r.category === "lifecycle" || r.id === "R-O-3-03" || r.id === "R-O-1-03" || r.id === "R-O-5-04");
+    }
+    return rules;
+}
+function filterChecklist(mode) {
+    if (mode === "initial_design") {
+        return ORDER_PUBLISH_CHECKLIST.filter(i => ["C-O-02", "C-O-03", "C-O-04", "C-O-12", "C-O-15"].includes(i.id));
+    }
+    if (mode === "dispute_resolution") {
+        return ORDER_PUBLISH_CHECKLIST.filter(i => ["C-O-04", "C-O-05", "C-O-07", "C-O-10", "C-O-14"].includes(i.id));
+    }
+    return ORDER_PUBLISH_CHECKLIST;
+}
+function filterQuestions(mode) {
+    if (mode === "pre_execute") {
+        return ORDER_CONFIRMATION_QUESTIONS;
+    }
+    if (mode === "dispute_resolution") {
+        return ORDER_CONFIRMATION_QUESTIONS.filter(q => ["QO3", "QO4", "QO8"].includes(q.id));
+    }
+    return [];
+}
+function buildCrossObjectRefs(scene) {
+    const refs = [
+        {
+            object: "Service",
+            field: "service",
+            scene_id: "order_create",
+            description: "Order references Service at creation (service::buy). Service.machine is SNAPSHOTTED to order.machine. After creation, Service changes do NOT affect Order.",
+        },
+        {
+            object: "Machine",
+            field: "machine",
+            scene_id: "order_create",
+            description: "order.machine is a snapshot copied from service.machine at buy time. Not a reference — Order's Machine is decoupled from Service's Machine after creation.",
+        },
+        {
+            object: "Progress",
+            field: "progress",
+            scene_id: "order_advance",
+            description: "Progress is 1:1 bound to Order at creation via on_progress. Binding is one-time (E_PROGRESS_ALREADY_SPECIFIED). Progress binding FREEZES owner and agent.",
+        },
+        {
+            object: "Allocation",
+            field: "allocation",
+            scene_id: "order_create",
+            description: "Allocation is 1:1 bound to Order at creation via on_allocation. Binding is one-time (E_ALLOCATION_ALREADY_SPECIFIED). Required when order.amount > 0.",
+        },
+        {
+            object: "Arbitration",
+            field: "dispute",
+            scene_id: "order_arb_confirm",
+            description: "Arb objects are appended to order.dispute via dispute() (package-only). Max 10 disputes. Frozen when claimed_by is set (E_ORDER_ALREADY_CLAIMED).",
+        },
+        {
+            object: "Discount",
+            field: "discount",
+            scene_id: "order_create",
+            description: "Discount object address (created-immutable). Applied at service::buy — affects order.amount calculation.",
+        },
+        {
+            object: "Contact",
+            field: "required_info",
+            scene_id: "order_required_info",
+            description: "Contact object can be set as required_info (recipient info). L2 operation — both owner and agent can update.",
+        },
+        {
+            object: "WTS_Proof",
+            field: "required_info",
+            scene_id: "order_required_info",
+            description: "WTS Proof object (generated via Wowok Messenger) can be set as required_info (delivery proof). L2 operation.",
+        },
+    ];
+    if (scene) {
+        refs.sort((a, b) => {
+            const aMatch = a.scene_id === scene.id ? -1 : 0;
+            const bMatch = b.scene_id === scene.id ? -1 : 0;
+            return aMatch - bMatch;
+        });
+    }
+    return refs;
+}
+function buildOnchainConstraints() {
+    return [
+        { name: "MAX_AGENT_COUNT", value: MAX_AGENT_COUNT, description: "Maximum agents per Order (doc limit; ⚠️ actual allows 11 due to <= bug in agent_set_imp)" },
+        { name: "MAX_DISPUTE_COUNT", value: MAX_DISPUTE_COUNT, description: "Maximum concurrent disputes per Order (frozen when claimed_by.is_some())" },
+        { name: "Order field count", value: 14, description: "Order has 14 fields (no Permission field — only business object without Permission in 22 objects)" },
+        { name: "Permission layers", value: "L1/L2/L3", description: "L1=owner-only (assert_owner), L2=owner-or-agent (has_op_permission), L3=package-only" },
+        { name: "Emitted events", value: 1, description: "Only NewOrderEvent is emitted; 10 other lifecycle events must be inferred from field changes" },
+        { name: "SDK builder ↔ Move owner", value: "naming deviation", description: "Only naming deviation in 22 objects — SDK uses 'builder' for Move's 'owner' field" },
+    ];
+}
+function buildRenderingHints(mode, max_length, hasTransfer, hasClaimCompensation, hasSnapshot) {
+    return {
+        include_puzzle_template: mode === "initial_design",
+        include_risk_details: mode === "pre_execute" || mode === "stakeholder_review" || mode === "dispute_resolution",
+        include_questions: mode === "pre_execute",
+        include_immutability_warning: mode === "post_create_monitor",
+        include_irreversible_warning: hasTransfer || hasClaimCompensation,
+        include_snapshot_warning: hasSnapshot && mode === "initial_design",
+        include_claimed_by_warning: mode === "dispute_resolution" || hasClaimCompensation,
+        max_length,
+    };
+}
+export function buildPromptFromOrderContext(bundle) {
+    const lines = [];
+    const h = bundle.rendering_hints;
+    lines.push(`═══ Order Context (mode: ${bundle.mode}) ═══`);
+    lines.push("");
+    if (bundle.stakeholder_perspective) {
+        lines.push(`Stakeholder perspective: ${bundle.stakeholder_perspective}`);
+        lines.push("");
+    }
+    if (bundle.matched_scene) {
+        lines.push(`Scene: ${bundle.matched_scene.name}`);
+        lines.push(`Operation field: ${bundle.matched_scene.operation_field}`);
+        lines.push(`Permission layer: ${bundle.matched_scene.permission_layer}`);
+        lines.push(`Reversibility: ${bundle.matched_scene.reversibility}`);
+        lines.push("");
+    }
+    if (bundle.matched_template) {
+        lines.push(`Suggested template: ${bundle.matched_template.id} — ${bundle.matched_template.name}`);
+        if (bundle.matched_template.irreversible) {
+            lines.push(`⚠️ IRREVERSIBLE operation`);
+        }
+        lines.push("");
+    }
+    if (h.include_puzzle_template && bundle.puzzle_completeness) {
+        const c = bundle.puzzle_completeness;
+        lines.push("─ Puzzle Completeness ──────────────");
+        lines.push(`Complete: ${c.complete ? "YES" : "NO"}`);
+        if (c.missing.length > 0) {
+            lines.push(`Missing: ${c.missing.join(", ")}`);
+        }
+        lines.push(`Next: ${c.next_step}`);
+        lines.push("");
+    }
+    if (h.include_snapshot_warning && bundle.snapshot_verification) {
+        const sv = bundle.snapshot_verification;
+        lines.push("─ Snapshot Verification ──────────────");
+        lines.push(`Snapshot understood: ${sv.snapshot_understood ? "YES" : "NO"}`);
+        lines.push(`Message: ${sv.message}`);
+        lines.push("");
+    }
+    if (h.include_risk_details && bundle.relevant_risks.length > 0) {
+        lines.push(`─ Relevant Risk Rules (${bundle.relevant_risks.length}) ──────────────`);
+        for (const r of bundle.relevant_risks.slice(0, 5)) {
+            lines.push(`  ${r.id} [${r.category}] — ${r.trigger}`);
+        }
+        if (bundle.relevant_risks.length > 5) {
+            lines.push(`  ... and ${bundle.relevant_risks.length - 5} more`);
+        }
+        lines.push("");
+    }
+    if (bundle.risk_assessment) {
+        lines.push("─ Risk Assessment ──────────────");
+        lines.push(`Overall: ${bundle.risk_assessment.overall_risk}`);
+        lines.push(`Detected: ${bundle.risk_assessment.risks.length} risk(s)`);
+        if (bundle.risk_assessment.needs_human_review) {
+            lines.push(`⚠️ Needs human review (HIGH or CRITICAL risks detected)`);
+        }
+        lines.push("");
+    }
+    if (bundle.event_audit) {
+        lines.push("─ Event Audit ──────────────");
+        lines.push(`Emitted: ${bundle.event_audit.emitted.length} event(s)`);
+        for (const e of bundle.event_audit.emitted) {
+            lines.push(`  ✓ ${e.name} — ${e.trigger}`);
+        }
+        lines.push(`Inferred (NOT emitted): ${bundle.event_audit.inferred.length} event(s)`);
+        for (const e of bundle.event_audit.inferred.slice(0, 3)) {
+            lines.push(`  ✗ ${e.name} — ${e.trigger}`);
+        }
+        if (bundle.event_audit.inferred.length > 3) {
+            lines.push(`  ... and ${bundle.event_audit.inferred.length - 3} more`);
+        }
+        lines.push("");
+    }
+    if (h.include_irreversible_warning) {
+        lines.push("⚠️⚠️ IRREVERSIBLE OPERATION DETECTED — claimed_by/transfer_to cannot be undone");
+        lines.push("");
+    }
+    if (h.include_claimed_by_warning) {
+        lines.push("⚠️ claimed_by state — once set, NO new disputes can be filed (E_ORDER_ALREADY_CLAIMED)");
+        lines.push("");
+    }
+    if (bundle.onchain_constraints.length > 0) {
+        lines.push("─ On-chain Constraints ──────────────");
+        for (const c of bundle.onchain_constraints) {
+            lines.push(`  ${c.name} = ${c.value} — ${c.description}`);
+        }
+        lines.push("");
+    }
+    if (bundle.cross_object_refs.length > 0) {
+        lines.push(`─ Cross-Object References (${bundle.cross_object_refs.length}) ──────────────`);
+        for (const r of bundle.cross_object_refs.slice(0, 4)) {
+            lines.push(`  ${r.object}.${r.field} (${r.scene_id}): ${r.description}`);
+        }
+        if (bundle.cross_object_refs.length > 4) {
+            lines.push(`  ... and ${bundle.cross_object_refs.length - 4} more`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export function getOrderContextSummary(bundle) {
+    const parts = [
+        `mode=${bundle.mode}`,
+        `scene=${bundle.matched_scene?.id ?? "none"}`,
+        `template=${bundle.matched_template?.id ?? "none"}`,
+        `risks=${bundle.relevant_risks.length}`,
+    ];
+    if (bundle.stakeholder_perspective)
+        parts.push(`stakeholder=${bundle.stakeholder_perspective}`);
+    if (bundle.risk_assessment)
+        parts.push(`overall_risk=${bundle.risk_assessment.overall_risk}`);
+    if (bundle.snapshot_verification)
+        parts.push(`snapshot=${bundle.snapshot_verification.snapshot_understood ? "yes" : "no"}`);
+    if (bundle.event_audit)
+        parts.push(`events_emitted=${bundle.event_audit.emitted.length}/inferred=${bundle.event_audit.inferred.length}`);
+    return parts.join(", ");
+}
+export function getStakeholderAdvice(stakeholder, scene) {
+    const advice = {
+        owner: [
+            "You are the Order owner — you can perform ALL operations (L1 + L2)",
+            "Only you can call receive (collect payments) — agents CANNOT",
+            "Only you can call transfer_to (irreversible ownership transfer)",
+            "Only you can call agent_set (frozen after Progress binding)",
+            "⚠️ Verify new owner address TWICE before transfer_to — IRREVERSIBLE",
+            "Set agents BEFORE service::buy if Machine is configured (frozen after)",
+        ],
+        agent: [
+            "You are an Order agent — you can perform L2 operations only",
+            "You CAN: advance Progress, update required_info, file arb_confirm/objection/claim_compensation",
+            "You CANNOT: receive payments, transfer ownership, set agent list (L1 owner-only)",
+            "Your permissions are FROZEN after Progress binding (cannot be modified)",
+            "To collect payments, ask the owner to do it for you",
+        ],
+        arbitrator: [
+            "You are the Arbitrator — you interact with the Arb object, not Order directly",
+            "Your Arb is appended to order.dispute via dispute() (package-only)",
+            "Once you set claimed_by via compensate(), NO new disputes can be filed",
+            "claimed_by is IRREVERSIBLE — verify ruling before calling compensate()",
+            "Max 10 disputes per Order (MAX_DISPUTE_COUNT)",
+        ],
+        service_provider: [
+            "You are the Service Provider — you published the Service the Order was bought from",
+            "Service.machine is SNAPSHOTTED to order.machine at buy time — your later changes do NOT propagate",
+            "Order is DECOUPLED from Service after creation — you cannot modify the Order",
+            "To influence Order flow, modify Progress (if you have operator permission)",
+            "Use Service.pause to block new orders (does NOT affect existing Orders)",
+        ],
+        system: [
+            "Order is the ONLY business object among 22 WoWok objects without a Permission field",
+            "Order uses owner/agent dual-layer (assert_owner + has_op_permission inline functions)",
+            "Order creation is COMPOSITE via service::buy (Order + Allocation + Progress atomic)",
+            "Only NewOrderEvent is emitted — 10 other lifecycle events must be inferred from field changes",
+            "SDK uses 'builder' for Move's 'owner' — only naming deviation in 22 objects",
+            "⚠️ agent_set_imp boundary bug: actual max 11 agents (not 10) due to <= instead of <",
+        ],
+    };
+    const base = advice[stakeholder];
+    if (!scene)
+        return base;
+    const sceneAdvice = {
+        order_create: [
+            "Creation goes via service::buy — not CallOrder_Data",
+            "wip_hash must NOT be empty string — use actual hash",
+        ],
+        order_advance: [
+            "Node transitions are IRREVERSIBLE — no backward movement",
+            "Guard (if any) must pass for forward to succeed",
+        ],
+        order_arb_claim_compensation: [
+            "⚠️⚠️ IRREVERSIBLE — claimed_by cannot be reset",
+            "After claim: NO new disputes can be filed (E_ORDER_ALREADY_CLAIMED)",
+        ],
+        order_transfer: [
+            "⚠️⚠️ IRREVERSIBLE — new owner takes over ALL permissions",
+            "Can be called even after Progress binding (unlike agent_set)",
+        ],
+    };
+    return [...base, ...(sceneAdvice[scene.id] ?? [])];
+}

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

@@ -0,0 +1,69 @@
+export interface OrderScene {
+    id: string;
+    name: string;
+    operation_field: "object" | "agent" | "required_info" | "progress" | "arb_confirm" | "arb_objection" | "arb_claim_compensation" | "receive" | "transfer_to" | "lifecycle";
+    move_entry: string;
+    permission_layer: OrderPermissionLayer;
+    reversibility: OrderReversibility;
+    governed_operations: string[];
+    common_patterns: string[];
+    related_risks: string[];
+    recommended_templates: string[];
+}
+export type OrderPermissionLayer = "L1_owner_only" | "L2_owner_or_agent" | "L3_package_only";
+export type OrderReversibility = "reversible" | "one_time_set" | "frozen_after_progress" | "irreversible" | "append_only" | "immutable";
+export interface OrderFieldDef {
+    move_name: string;
+    sdk_name: string;
+    move_type: string;
+    mutability_layer: 1 | 2 | 3 | 4;
+    description: string;
+}
+export declare const ORDER_FIELDS: OrderFieldDef[];
+export type OrderState = "CREATED" | "IN_PROGRESS" | "DISPUTED" | "CLAIMED" | "COMPLETED" | "CANCELLED";
+export declare const ORDER_STATES: OrderState[];
+export declare const ORDER_STATE_TRANSITIONS: {
+    from: OrderState;
+    to: OrderState;
+    trigger: string;
+}[];
+export interface OrderLifecycleEvent {
+    name: string;
+    trigger: string;
+    emit_source: string;
+    actually_emitted: boolean;
+    fields: string[];
+}
+export declare const ORDER_LIFECYCLE_EVENTS: OrderLifecycleEvent[];
+export declare const ORDER_PERMISSION_MATRIX: {
+    operation: string;
+    move_function: string;
+    layer: OrderPermissionLayer;
+    aborts_with?: string;
+    notes: string;
+}[];
+export declare const ORDER_SCENES: OrderScene[];
+export declare const ORDER_AUDIT_FORMULAS: {
+    status_inference: string;
+    amount_check: string;
+    fund_balance: string;
+    dispute_constraint: string;
+    agent_constraint: string;
+};
+export declare const ORDER_LEDGER_VERSION = "1.0.0";
+export declare function getScenesByOperationField(field: OrderScene["operation_field"]): OrderScene[];
+export declare function findSceneById(id: string): OrderScene | undefined;
+export declare function findSceneByMoveEntry(moveEntry: string): OrderScene | undefined;
+export declare function getScenesByPermissionLayer(layer: OrderPermissionLayer): OrderScene[];
+export declare function getScenesByReversibility(rev: OrderReversibility): OrderScene[];
+export declare function getFieldDef(moveName: string): OrderFieldDef | undefined;
+export declare function getMutableFields(): OrderFieldDef[];
+export declare function getImmutableFields(): OrderFieldDef[];
+export declare function getFrozenAfterProgressFields(): OrderFieldDef[];
+export declare function getOneTimeSetFields(): OrderFieldDef[];
+export declare function inferSceneFromIntent(intent: string): OrderScene | undefined;
+export declare function getEmittedEvents(): OrderLifecycleEvent[];
+export declare function getInferredEvents(): OrderLifecycleEvent[];
+export declare function getOrderScenesCount(): number;
+export declare function sdkToMoveField(sdkName: string): string | undefined;
+export declare function moveToSdkField(moveName: string): string | undefined;