@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/treasury-context.js

@@ -0,0 +1,363 @@
+import { USER_DEFINED_PERM_INDEX_START, MAX_ADMIN_COUNT, MAX_PERM_FOR_ENTITY, MAX_ENTITY_COUNT, } from "@wowok/wowok";
+import { findSceneById, findSceneByPermissionIndex, inferSceneFromIntent, getActiveBuiltinPermissions, getReservedBuiltinPermissions, } from "./treasury-ledger.js";
+import { getTemplatesByScene, } from "./treasury-templates.js";
+import { matchSemanticPattern, } from "./treasury-translation.js";
+import { getAllTreasuryRiskRules, assessTreasuryRisks, } from "./treasury-risk.js";
+import { initPuzzleFromIntent, checkPuzzleCompleteness, MAX_EXTERNAL_DEPOSIT_GUARD_COUNT, MAX_EXTERNAL_WITHDRAW_GUARD_COUNT, MAX_DESCRIPTION_LENGTH, } from "./treasury-puzzle.js";
+import { TREASURY_PUBLISH_CHECKLIST, TREASURY_CONFIRMATION_QUESTIONS, } from "./treasury-confirm.js";
+export const TREASURY_CONTEXT_VERSION = "1.0.0";
+export function buildTreasuryContext(input) {
+    const max_length = input.max_length ?? 4000;
+    let matched_scene;
+    if (input.intent) {
+        matched_scene = inferSceneFromIntent(input.intent);
+    }
+    else if (input.target_permission_index !== undefined) {
+        matched_scene = findSceneByPermissionIndex(input.target_permission_index);
+    }
+    if (!matched_scene && input.intent) {
+        matched_scene = findSceneById("treasury_fund_collection");
+    }
+    let matched_template;
+    if (matched_scene) {
+        const templates = getTemplatesByScene(matched_scene.id);
+        if (templates.length > 0)
+            matched_template = templates[0];
+    }
+    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_publish" || input.mode === "mid_design_review") && input.treasury_json) {
+        const ctx = {
+            object: typeof input.treasury_json.object === "string" ? input.treasury_json.object : null,
+            description: input.treasury_json.description,
+            deposit: input.treasury_json.deposit ? {
+                coin_balance: input.treasury_json.deposit.coin?.balance,
+                coin_object: input.treasury_json.deposit.coin?.coin_object,
+                by_external_deposit_guard: input.treasury_json.deposit.by_external_deposit_guard,
+            } : undefined,
+            withdraw: input.treasury_json.withdraw ? {
+                amount_fixed: input.treasury_json.withdraw.amount?.fixed,
+                amount_by_external_withdraw_guard: input.treasury_json.withdraw.amount?.by_external_withdraw_guard,
+                recipient: input.treasury_json.withdraw.recipient,
+            } : undefined,
+            external_deposit_guard: input.treasury_json.external_deposit_guard,
+            external_withdraw_guard: input.treasury_json.external_withdraw_guard,
+            owner_receive: input.treasury_json.owner_receive,
+            um: input.treasury_json.um,
+            type_parameter: input.type_parameter,
+            shared_with_service: input.shared_with_service,
+            shared_with_allocator: input.shared_with_allocator,
+            shared_with_arbitration: input.shared_with_arbitration,
+            current_permission_indexes_granted: input.current_permission_indexes_granted,
+        };
+        risk_assessment = assessTreasuryRisks(ctx);
+    }
+    const relevant_checklist = filterChecklist(input.mode);
+    const relevant_questions = filterQuestions(input.mode);
+    const relevant_builtin_permissions = matched_scene
+        ? matched_scene.builtin_indexes.filter(p => p.active)
+        : getActiveBuiltinPermissions();
+    const reserved_builtin_permissions = getReservedBuiltinPermissions();
+    const cross_object_refs = buildCrossObjectRefs(input.mode, matched_scene);
+    const onchain_constraints = buildOnchainConstraints();
+    const rendering_hints = buildRenderingHints(input.mode, max_length, !!input.treasury_json?.withdraw, !!input.treasury_json?.external_deposit_guard || !!input.treasury_json?.external_withdraw_guard, !!input.shared_with_service || !!input.shared_with_allocator || !!input.shared_with_arbitration);
+    return {
+        version: TREASURY_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,
+        relevant_builtin_permissions,
+        reserved_builtin_permissions,
+        cross_object_refs,
+        onchain_constraints,
+        rendering_hints,
+    };
+}
+function filterRiskRules(mode, stakeholder, scene) {
+    let rules = getAllTreasuryRiskRules();
+    if (mode === "initial_design") {
+        return rules.filter(r => r.category === "structural" || r.category === "authority");
+    }
+    if (mode === "pre_publish") {
+        return rules;
+    }
+    if (mode === "stakeholder_review" && stakeholder) {
+        if (stakeholder === "owner") {
+            return rules.filter(r => r.category === "authority" || r.category === "lifecycle");
+        }
+        if (stakeholder === "admin") {
+            return rules.filter(r => r.category === "structural" || r.category === "semantic");
+        }
+        if (stakeholder === "depositor") {
+            return rules.filter(r => r.id === "R-T-2-02" || r.id === "R-T-2-03" || r.category === "structural");
+        }
+        if (stakeholder === "withdrawer") {
+            return rules.filter(r => r.id === "R-T-4-01" || r.id === "R-T-4-02" || r.id === "R-T-3-01");
+        }
+        if (stakeholder === "external_operator") {
+            return rules.filter(r => r.id === "R-T-2-01" || r.id === "R-T-2-03" || r.id === "R-T-4-02");
+        }
+        if (stakeholder === "system") {
+            return rules.filter(r => r.category === "cross_object" || r.id === "R-T-0-01");
+        }
+    }
+    if (mode === "cross_object_check") {
+        return rules.filter(r => r.category === "cross_object");
+    }
+    return rules;
+}
+function filterChecklist(mode) {
+    if (mode === "initial_design") {
+        return TREASURY_PUBLISH_CHECKLIST.filter(i => ["C-T-01", "C-T-02", "C-T-03", "C-T-10"].includes(i.id));
+    }
+    return TREASURY_PUBLISH_CHECKLIST;
+}
+function filterQuestions(mode) {
+    if (mode === "pre_publish") {
+        return TREASURY_CONFIRMATION_QUESTIONS;
+    }
+    if (mode === "post_publish_modify") {
+        return TREASURY_CONFIRMATION_QUESTIONS.filter(q => q.id !== "QT1");
+    }
+    return [];
+}
+function buildCrossObjectRefs(mode, scene) {
+    const refs = [];
+    refs.push({
+        object: "Permission",
+        field: "permission",
+        description: "All Treasury write operations (except external_deposit/withdraw) require Permission authorization via indexes 250-258",
+        collaboration_type: "dependency",
+    });
+    refs.push({
+        object: "Registrar",
+        field: "registrar",
+        description: "Tracks affiliation between Treasury, Permission, and UM (Contact) objects",
+        collaboration_type: "dependency",
+    });
+    refs.push({
+        object: "Clock",
+        field: "clock",
+        description: "Provides timestamp for Record entries in history ParentTable",
+        collaboration_type: "dependency",
+    });
+    if (scene?.id === "treasury_external_ops" || scene?.id === "treasury_guard_protection" || mode === "cross_object_check") {
+        refs.push({
+            object: "Guard",
+            field: "external_deposit_guard / external_withdraw_guard",
+            description: "Guard objects referenced by external_*_guard lists; provide programmable access rules for external deposit/withdraw",
+            collaboration_type: "dependency",
+        });
+        refs.push({
+            object: "Passport",
+            field: "passport",
+            description: "Required for every external_deposit / external_withdraw call; carries submission values verified by Guard",
+            collaboration_type: "dependency",
+        });
+    }
+    refs.push({
+        object: "Allocator",
+        field: "sharing.who=Entity",
+        description: "Allocator can reference Treasury address as fund split target; Treasury.receive (253) converts CoinWrapper to balance",
+        collaboration_type: "referenced_by",
+    });
+    refs.push({
+        object: "Arbitration",
+        field: "fees_transfer",
+        description: "Arbitration.fees_transfer sends Payment to Treasury address; Treasury.receive (253) required to intake",
+        collaboration_type: "referenced_by",
+    });
+    refs.push({
+        object: "Service",
+        field: "compensation_fund (parallel design)",
+        description: "Service.compensation_fund is a parallel design (NOT a Treasury object); both are Balance<T> containers but implementation-independent",
+        collaboration_type: "parallel_design",
+    });
+    refs.push({
+        object: "Contact",
+        field: "um",
+        description: "Optional UM (User Manager) Contact object; manages user-tier information via Registrar affiliation",
+        collaboration_type: "dependency",
+    });
+    refs.push({
+        object: "Payment",
+        field: "history ParentTable",
+        description: "Every deposit/withdraw/receive creates a Payment object; Payment address is the key in history ParentTable",
+        collaboration_type: "dependency",
+    });
+    refs.push({
+        object: "CoinWrapper",
+        field: "receive",
+        description: "CoinWrapper is the received form of coins; Treasury.receive (253) unwraps CoinWrapper to balance",
+        collaboration_type: "dependency",
+    });
+    return refs;
+}
+function buildOnchainConstraints() {
+    return [
+        { name: "MAX_EXTERNAL_DEPOSIT_GUARD_COUNT", value: MAX_EXTERNAL_DEPOSIT_GUARD_COUNT, description: "Maximum external_deposit_guard entries (Treasury-specific, not yet in onchain-constants.ts)" },
+        { name: "MAX_EXTERNAL_WITHDRAW_GUARD_COUNT", value: MAX_EXTERNAL_WITHDRAW_GUARD_COUNT, description: "Maximum external_withdraw_guard entries (Treasury-specific, not yet in onchain-constants.ts)" },
+        { name: "MAX_DESCRIPTION_LENGTH", value: MAX_DESCRIPTION_LENGTH, description: "Maximum description length (shared across all objects)" },
+        { name: "USER_DEFINED_PERM_INDEX_START", value: USER_DEFINED_PERM_INDEX_START, description: "Custom permission indexes must be >= this value" },
+        { name: "MAX_ENTITY_COUNT", value: MAX_ENTITY_COUNT, description: "Maximum entities per Permission (shared)" },
+        { name: "MAX_PERM_FOR_ENTITY", value: MAX_PERM_FOR_ENTITY, description: "Maximum permission indexes per entity (shared)" },
+        { name: "MAX_ADMIN_COUNT", value: MAX_ADMIN_COUNT, description: "Maximum admins per Permission (shared)" },
+    ];
+}
+function buildRenderingHints(mode, max_length, hasWithdraw, hasExternalGuard, hasCrossObject) {
+    return {
+        include_puzzle_template: mode === "initial_design",
+        include_risk_details: mode === "pre_publish" || mode === "stakeholder_review" || mode === "mid_design_review",
+        include_questions: mode === "pre_publish",
+        include_irreversibility_warning: hasWithdraw,
+        include_external_guard_warning: hasExternalGuard,
+        include_cross_object_warning: hasCrossObject || mode === "cross_object_check",
+        max_length,
+    };
+}
+export function buildPromptFromTreasuryContext(bundle) {
+    const lines = [];
+    const h = bundle.rendering_hints;
+    lines.push(`═══ Treasury 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(`Scene ID: ${bundle.matched_scene.id}`);
+        lines.push(`Permission range: ${bundle.matched_scene.permission_index_range}`);
+        lines.push("");
+    }
+    if (bundle.matched_template) {
+        lines.push(`Suggested template: ${bundle.matched_template.id} — ${bundle.matched_template.name}`);
+        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_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, 8)) {
+            lines.push(`  ${r.id} — ${r.trigger}`);
+        }
+        if (bundle.relevant_risks.length > 8) {
+            lines.push(`  ... and ${bundle.relevant_risks.length - 8} 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)`);
+        for (const r of bundle.risk_assessment.risks.slice(0, 5)) {
+            lines.push(`  [${r.level}] ${r.id}: ${r.title}`);
+        }
+        lines.push("");
+    }
+    if (bundle.relevant_builtin_permissions.length > 0) {
+        lines.push(`─ Builtin Treasury Permissions (active: ${bundle.relevant_builtin_permissions.length}) ──────────────`);
+        for (const p of bundle.relevant_builtin_permissions) {
+            lines.push(`  [${p.index}] ${p.name}: ${p.description}`);
+        }
+        lines.push("");
+    }
+    if (bundle.reserved_builtin_permissions.length > 0) {
+        lines.push(`─ Reserved (no Permission index) ──────────────`);
+        for (const p of bundle.reserved_builtin_permissions) {
+            lines.push(`  ${p.name}: ${p.description}`);
+        }
+        lines.push("");
+    }
+    if (h.include_irreversibility_warning) {
+        lines.push("⚠️ WITHDRAW OPERATION DETECTED — IRREVERSIBLE");
+        lines.push("  - withdraw (fixed) and external_withdraw cannot be undone");
+        lines.push("  - verify recipient address twice");
+        lines.push("  - ensure balance sufficiency");
+        lines.push("");
+    }
+    if (h.include_external_guard_warning) {
+        lines.push("⚠️ EXTERNAL GUARD MANAGEMENT — Verify Guard table fields");
+        lines.push("  - identifier must be number-type (u8/u16/u32/u64/u128/u256)");
+        lines.push("  - store_from_id must be address-compatible");
+        lines.push("  - external_withdraw_guard.identifier is REQUIRED (u8, not Option)");
+        lines.push("  - external_deposit_guard.identifier is Option<u8> (None = no amount limit)");
+        lines.push("");
+    }
+    if (h.include_cross_object_warning) {
+        lines.push("⚠️ CROSS-OBJECT COLLABORATION — Verify consistency");
+        lines.push("  - If shared with Service: verify Permission indexes 250-258 (Treasury) and 300-320 (Service) align");
+        lines.push("  - If referenced by Allocator/Arbitration: TREASURY_RECEIVE (253) must be granted for CoinWrapper intake");
+        lines.push("");
+    }
+    if (bundle.cross_object_refs.length > 0) {
+        lines.push(`─ Cross-Object References (${bundle.cross_object_refs.length}) ──────────────`);
+        for (const ref of bundle.cross_object_refs.slice(0, 6)) {
+            lines.push(`  [${ref.collaboration_type}] ${ref.object}.${ref.field}`);
+            lines.push(`    ${ref.description}`);
+        }
+        if (bundle.cross_object_refs.length > 6) {
+            lines.push(`  ... and ${bundle.cross_object_refs.length - 6} more`);
+        }
+        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 (h.include_questions && bundle.relevant_questions.length > 0) {
+        lines.push("─ Confirmation Questions ──────────────");
+        for (const q of bundle.relevant_questions) {
+            const marker = q.requires_explicit_yes ? " ⚠️" : "";
+            lines.push(`  ${q.id}${marker}: ${q.question}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export function getTreasuryContextSummary(bundle) {
+    const parts = [
+        `mode=${bundle.mode}`,
+        `scene=${bundle.matched_scene?.id ?? "none"}`,
+        `risks=${bundle.relevant_risks.length}`,
+        `permissions=${bundle.relevant_builtin_permissions.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.matched_template)
+        parts.push(`template=${bundle.matched_template.id}`);
+    return parts.join(", ");
+}

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

@@ -0,0 +1,42 @@
+export interface TreasuryScene {
+    id: string;
+    name: string;
+    coin_type_category: "generic" | "native_sui" | "wrapped" | "stablecoin";
+    permission_index_range: string;
+    builtin_indexes: BuiltinTreasuryPermissionEntry[];
+    owner_operations: string[];
+    admin_operations: string[];
+    permission_index_operations: string[];
+    external_operations: string[];
+    guard_list_mutable_after_publish: boolean;
+    common_patterns: string[];
+    irreversibility: {
+        deposit: "reversible" | "irreversible";
+        withdraw: "reversible" | "irreversible";
+        external_deposit: "reversible" | "irreversible";
+        external_withdraw: "reversible" | "irreversible";
+        owner_receive: "reversible" | "irreversible";
+    };
+    cross_object_collaboration: string[];
+    recommended_templates: string[];
+}
+export interface BuiltinTreasuryPermissionEntry {
+    index: number;
+    name: string;
+    description: string;
+    governed_operation: string;
+    active: boolean;
+}
+export declare const TREASURY_PERMISSIONS: BuiltinTreasuryPermissionEntry[];
+export declare const TREASURY_SCENES: TreasuryScene[];
+export declare const TREASURY_LEDGER_VERSION = "1.0.0";
+export declare function getScenesByHostObject(_host: "Treasury"): TreasuryScene[];
+export declare function findSceneById(id: string): TreasuryScene | undefined;
+export declare function findSceneByPermissionIndex(index: number): TreasuryScene | undefined;
+export declare function getBuiltinPermissionByIndex(index: number): BuiltinTreasuryPermissionEntry | undefined;
+export declare function isBuiltinTreasuryPermission(index: number): boolean;
+export declare function getActiveBuiltinPermissions(): BuiltinTreasuryPermissionEntry[];
+export declare function getReservedBuiltinPermissions(): BuiltinTreasuryPermissionEntry[];
+export declare function inferSceneFromIntent(intent: string): TreasuryScene | undefined;
+export declare function getTreasuryScenesCount(): number;
+export declare function getMoveFunctionsForPermissionIndex(index: number): string[];