@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/progress-templates.js

@@ -0,0 +1,228 @@
+export const PROGRESS_TEMPLATES = [
+    {
+        id: "T-PR-01",
+        name: "Single named_operator workflow",
+        description: "Bind a single named_operator role (e.g. 'seller' or 'logistics') to a Progress. " +
+            "Suitable for linear flows with one external operator besides OrderHolder.",
+        applicable_scenes: ["progress_named_operator", "progress_task_submit"],
+        industry_tags: ["universal", "ecommerce"],
+        params: [
+            { name: "progress_address", type: "address", description: "Progress object address", required: true },
+            { name: "operator_name", type: "name", description: "named_operator name (e.g. 'seller', 'logistics')", required: true },
+            { name: "operator_address", type: "address", description: "Single operator address", required: true },
+        ],
+        body: (p) => ({
+            object: p.progress_address,
+            progress_namedOperator: {
+                op: "set",
+                name: p.operator_name,
+                operators: [p.operator_address],
+            },
+        }),
+        notes: [
+            "Use 'set' for initial assignment (REPLACE list); use 'add' for extending existing list",
+            "Operator name must be a valid NAME (common::NAME) — non-empty, length-bounded",
+            "Empty name '' is reserved for OrderHolder — do not use here",
+        ],
+    },
+    {
+        id: "T-PR-02",
+        name: "Multi named_operator collaborative workflow",
+        description: "Bind multiple named_operator roles in one transaction (e.g. seller + logistics + reviewer). " +
+            "Suitable for collaborative workflows where different roles advance different forwards.",
+        applicable_scenes: ["progress_named_operator"],
+        industry_tags: ["logistics", "arbitration", "freelance"],
+        params: [
+            { name: "progress_address", type: "address", description: "Progress object address", required: true },
+            { name: "roles", type: "string[]", description: "named_operator names (e.g. ['seller','logistics','reviewer'])", required: true },
+            { name: "addresses_per_role", type: "string", description: "Comma-separated addresses per role, semicolon-separated roles (e.g. '0xA,0xB;0xC;0xD,0xE')", required: true },
+        ],
+        body: (p) => {
+            const roles = p.roles;
+            const roleAddrStrings = p.addresses_per_role.split(";");
+            const operations = [];
+            for (let i = 0; i < roles.length; i++) {
+                const roleName = roles[i];
+                const addrs = (roleAddrStrings[i] ?? "").split(",").map(s => s.trim()).filter(s => s.length > 0);
+                operations.push({
+                    object: p.progress_address,
+                    progress_namedOperator: {
+                        op: "set",
+                        name: roleName,
+                        operators: addrs,
+                    },
+                });
+            }
+            return {
+                _batch: operations,
+                _note: "Each entry is a separate CallProgress_Data; submit all in one transaction",
+            };
+        },
+        notes: [
+            "Each role must satisfy common::NAME — non-empty, length-bounded",
+            "Total roles ≤ MAX_NAMED_OPERATOR_COUNT (60); each role's addresses ≤ MAX_NAMED_OPERATOR_ADDRESS_COUNT (80)",
+            "Submit all operations in a single transaction for atomicity",
+        ],
+    },
+    {
+        id: "T-PR-03",
+        name: "Context_repository binding workflow",
+        description: "Bind context Repository objects to a Progress for query-time context " +
+            "(learning progress, inspection records, bridge state). Up to 30 repositories.",
+        applicable_scenes: ["progress_context_repository"],
+        industry_tags: ["education", "content", "rental", "cross_chain"],
+        params: [
+            { name: "progress_address", type: "address", description: "Progress object address", required: true },
+            { name: "repository_addresses", type: "string[]", description: "Repository object addresses to bind", required: true },
+            { name: "op", type: "string", description: "Operation: 'add' (extend) | 'set' (replace) | 'remove' | 'clear'", required: false, default: "add" },
+        ],
+        body: (p) => ({
+            object: p.progress_address,
+            repository: {
+                op: p.op || "add",
+                objects: p.repository_addresses,
+            },
+        }),
+        notes: [
+            "op='add' is idempotent (vector::contains check); op='set' clears then adds",
+            "Total count ≤ MAX_CONTEXT_REPOSITORY_COUNT (30); E_MAX_CONTEXT_REPOSITORY_COUNT on overflow",
+            "Binding creates Registrar affiliation — remove before deleting Repository to avoid dangling refs",
+            "Bind BEFORE forward advance so on-chain guards can read context data",
+        ],
+    },
+    {
+        id: "T-PR-04",
+        name: "Forward advancement workflow",
+        description: "Advance a Progress forward (next or hold). Forwards are defined in the bound Machine; " +
+            "this template emits the operate payload for a single forward step.",
+        applicable_scenes: ["progress_completed", "progress_unhold"],
+        industry_tags: ["universal"],
+        params: [
+            { name: "progress_address", type: "address", description: "Progress object address", required: true },
+            { name: "next_node_name", type: "name", description: "Target node name (must exist in Machine)", required: true },
+            { name: "forward", type: "name", description: "Forward name (from current → next_node_name)", required: true },
+            { name: "op", type: "string", description: "'next' to advance the forward, 'hold' to lock the forward", required: false, default: "next" },
+            { name: "message", type: "string", description: "Deliverable message (≤ MAX_LONG_NAME_LENGTH)", required: false, default: "" },
+        ],
+        body: (p) => ({
+            object: p.progress_address,
+            operate: {
+                operation: {
+                    next_node_name: p.next_node_name,
+                    forward: p.forward,
+                },
+                op: p.op || "next",
+                message: p.message || "",
+            },
+        }),
+        notes: [
+            "Forward must exist in Machine: query machine::info_borrow(machine, current, next_node, forward)",
+            "If Forward.guard is Some, use *_with_passport variant (SDK auto-selects based on submission)",
+            "If Forward.namedOperator is set, caller must be in that operator list (IsNamedOperator short-circuit)",
+            "op='hold' blocks the forward; op='next' advances it; op='unhold' self-releases; op='adminUnhold' force-releases via 224",
+        ],
+    },
+    {
+        id: "T-PR-05",
+        name: "Unhold / adminUnhold workflow",
+        description: "Release a previously-held forward. Two modes: (a) self-unhold by original holder (op='unhold'); " +
+            "(b) adminUnhold via 224 permission to bypass holder check (op='adminUnhold', deadlock recovery).",
+        applicable_scenes: ["progress_unhold"],
+        industry_tags: ["content", "rental", "arbitration", "subscription"],
+        params: [
+            { name: "progress_address", type: "address", description: "Progress object address", required: true },
+            { name: "next_node_name", type: "name", description: "Target node name (matches the held forward)", required: true },
+            { name: "forward", type: "name", description: "Forward name (matches the held forward)", required: true },
+            { name: "admin_unhold", type: "string", description: "'true' to force-release via 224 permission (op='adminUnhold'); 'false' for self-unhold (op='unhold')", required: false, default: "false" },
+            { name: "message", type: "string", description: "Release message (≤ MAX_LONG_NAME_LENGTH)", required: false, default: "" },
+        ],
+        body: (p) => ({
+            object: p.progress_address,
+            operate: {
+                operation: {
+                    next_node_name: p.next_node_name,
+                    forward: p.forward,
+                },
+                op: p.admin_unhold === "true" ? "adminUnhold" : "unhold",
+                message: p.message || "",
+            },
+        }),
+        notes: [
+            "op='unhold': sender must == Holder.who; else E_NOT_THE_HOLDER",
+            "op='adminUnhold': requires 224 permission (PROGRESS_UNHOLD); bypasses holder check",
+            "Re-hold on already-accomplished forward → E_FORWARD_ALREADY_ACCOMPLISHED",
+            "Use adminUnhold sparingly — log every invocation for audit",
+        ],
+    },
+    {
+        id: "T-PR-06",
+        name: "Owner receive workflow",
+        description: "Owner receives Receiving<K> objects or CoinWrapper<T> coins at a terminal node. " +
+            "Unwraps via Payment.unwrap_with_check; forwards to Permission owner. " +
+            "Note: NOT exposed in CallProgress_Data — direct Move call required.",
+        applicable_scenes: ["progress_owner_receive"],
+        industry_tags: ["finance", "treasury", "rental", "freelance"],
+        params: [
+            { name: "progress_address", type: "address", description: "Progress object address", required: true },
+            { name: "machine_address", type: "address", description: "Bound Machine object address", required: true },
+            { name: "permission_address", type: "address", description: "Machine's Permission object address", required: true },
+            { name: "asset_type", type: "string", description: "'coin' or 'object'", required: true },
+            { name: "received_object", type: "address", description: "Receiving<K> object address (the received 'envelope')", required: true },
+            { name: "payment_object", type: "address", description: "Payment<T> object address (only for asset_type='coin')", required: false },
+        ],
+        body: (p) => ({
+            _note: "This operation is NOT exposed via CallProgress_Data; must be called via direct Move call.",
+            _move_target: p.asset_type === "coin"
+                ? "progress::owner_receive<T>"
+                : "progress::owner_receive_object<K>",
+            _arguments: p.asset_type === "coin"
+                ? [p.progress_address, p.machine_address, p.permission_address, p.received_object, p.payment_object]
+                : [p.progress_address, p.machine_address, p.permission_address, p.received_object],
+            _permission_required: 225,
+            _permission_label: "PROGRESS_OWNER_RECEIVE",
+        }),
+        notes: [
+            "Permission 225 (PROGRESS_OWNER_RECEIVE) is required; SDK CallProgress_Data does NOT expose this op",
+            "Recipient is Permission owner (Machine.permission's owner), NOT Progress creator",
+            "Triggered at terminal nodes: 'deposit_refunded', 'completed', 'enforced', 'paid'",
+            "For coins: Payment.unwrap_with_check validates amount before forwarding to owner",
+            "For objects: generic K:key+store — forwarded directly via permission::owner_receive_inner",
+        ],
+    },
+];
+export const PROGRESS_TEMPLATES_VERSION = "1.0.0";
+export function getAllProgressTemplates() {
+    return [...PROGRESS_TEMPLATES];
+}
+export function getProgressTemplateById(id) {
+    return PROGRESS_TEMPLATES.find(t => t.id === id);
+}
+export function getProgressTemplatesByScene(sceneId) {
+    return PROGRESS_TEMPLATES.filter(t => t.applicable_scenes.includes(sceneId));
+}
+export function getProgressTemplatesByIndustry(industry) {
+    return PROGRESS_TEMPLATES.filter(t => t.industry_tags.includes(industry) || t.industry_tags.includes("universal"));
+}
+export function suggestProgressTemplateForScene(sceneId) {
+    const matches = getProgressTemplatesByScene(sceneId);
+    return matches.length > 0 ? matches[0] : undefined;
+}
+export function listProgressTemplates() {
+    return PROGRESS_TEMPLATES.map(t => ({
+        id: t.id,
+        name: t.name,
+        description: t.description,
+        scenes: t.applicable_scenes,
+    }));
+}
+export function fillProgressTemplate(templateId, params) {
+    const tpl = getProgressTemplateById(templateId);
+    if (!tpl)
+        return { ok: false, error: `Template ${templateId} not found` };
+    for (const p of tpl.params) {
+        if (p.required && !(p.name in params)) {
+            return { ok: false, error: `Missing required param: ${p.name}` };
+        }
+    }
+    return { ok: true, body: tpl.body(params) };
+}

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

@@ -0,0 +1,52 @@
+export interface ProgressSemanticToSchemaRule {
+    id: string;
+    pattern_name: string;
+    semantic_intent: string;
+    match_keywords: string[];
+    schema_fields: string[];
+    example_json: object;
+    reverse_explanation: string;
+}
+export interface ProgressSchemaToSemanticRule {
+    element_type: "field" | "op" | "phase";
+    type_name: string;
+    semantic_explanation: string;
+    constraints?: string[];
+}
+export interface ProgressConstraintRule {
+    id: string;
+    category: "structural" | "semantic" | "permission" | "lifecycle" | "cross_object";
+    rule: string;
+    applies_to: string[];
+}
+export declare const PROGRESS_SEMANTIC_TO_SCHEMA_RULES: ProgressSemanticToSchemaRule[];
+export declare const PROGRESS_SCHEMA_TO_SEMANTIC_RULES: ProgressSchemaToSemanticRule[];
+export declare const PROGRESS_CONSTRAINT_RULES: ProgressConstraintRule[];
+export declare const PROGRESS_TRANSLATION_VERSION = "1.0.0";
+export declare function matchSemanticPattern(userIntent: string): ProgressSemanticToSchemaRule[];
+export interface ProgressCallDataForExplanation {
+    object?: string | null;
+    task?: string;
+    repository?: {
+        op: string;
+        objects?: string[];
+    };
+    progress_namedOperator?: {
+        op: string;
+        name: string;
+        operators?: string[];
+    };
+    operate?: {
+        operation: {
+            next_node_name: string;
+            forward: string;
+        };
+        op?: "next" | "hold" | "unhold" | "adminUnhold";
+        message?: string;
+    };
+}
+export declare function explainProgressCallData(data: ProgressCallDataForExplanation): string;
+export declare function explainField(fieldName: string): ProgressSchemaToSemanticRule | undefined;
+export declare function explainOp(opName: string): ProgressSchemaToSemanticRule | undefined;
+export declare function getConstraintsByCategory(category: ProgressConstraintRule["category"]): ProgressConstraintRule[];
+export declare function explainPermissionIndex(index: number): string;