@wowok/agent-mcp 2.4.3 → 2.5.0

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

@@ -0,0 +1,74 @@
+import { type ProgressScene } from "./progress-ledger.js";
+export type ProgressRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+export type ProgressRiskCategory = "structural" | "semantic" | "permission" | "lifecycle" | "cross_object";
+export interface ProgressRisk {
+    id: string;
+    level: ProgressRiskLevel;
+    category: ProgressRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: ProgressStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+}
+export type ProgressStakeholder = "owner" | "named_operator" | "submitter" | "system";
+export interface ProgressRiskRule {
+    id: string;
+    category: ProgressRiskCategory;
+    trigger: string;
+    check: (ctx: ProgressRiskCheckContext) => ProgressRisk | null;
+}
+export interface ProgressRiskCheckContext {
+    object?: string | null;
+    task?: string;
+    repository?: {
+        op: "add" | "set";
+        objects: string[];
+    } | {
+        op: "remove";
+        objects: string[];
+    } | {
+        op: "clear";
+    };
+    progress_namedOperator?: {
+        op: "add" | "set" | "remove";
+        name: string;
+        operators: string[];
+    };
+    operate?: {
+        operation: {
+            next_node_name: string;
+            forward: string;
+        };
+        op: "next" | "hold" | "unhold" | "adminUnhold";
+        message?: string;
+    };
+    current_machine?: string;
+    machine_published?: boolean;
+    current_task?: string | null;
+    current_named_operator_count?: number;
+    current_context_repository_count?: number;
+    current_node?: string;
+    forward_already_accomplished?: boolean;
+    holder_address?: string | null;
+    signer?: string;
+    forward_named_operator?: string;
+    forward_permission_index?: number | null;
+    forward_has_guard?: boolean;
+    target_objects_types?: string[];
+}
+export declare const PROGRESS_RISK_VERSION = "1.0.0";
+export declare function getAllProgressRiskRules(): ProgressRiskRule[];
+export declare function getProgressRiskRulesCount(): number;
+export declare function getProgressRiskRulesByCategory(category: ProgressRiskCategory): ProgressRiskRule[];
+export interface ProgressRiskAssessment {
+    summary: string;
+    scene?: ProgressScene;
+    risks: ProgressRisk[];
+    overall_risk: ProgressRiskLevel;
+    risks_by_category: Partial<Record<ProgressRiskCategory, number>>;
+    stakeholder_advice: Partial<Record<ProgressStakeholder, string[]>>;
+    needs_human_review: boolean;
+}
+export declare function assessProgressRisks(ctx: ProgressRiskCheckContext): ProgressRiskAssessment;

package/dist/knowledge/progress-risk.js

@@ -0,0 +1,461 @@
+import { MAX_NAMED_OPERATOR_COUNT, MAX_NAMED_OPERATOR_ADDRESS_COUNT, MAX_CONTEXT_REPOSITORY_COUNT, } from "@wowok/wowok";
+const R_PR_1_01 = {
+    id: "R-PR-1-01",
+    category: "structural",
+    trigger: "named_operator addresses count > MAX_NAMED_OPERATOR_ADDRESS_COUNT (80)",
+    check: (ctx) => {
+        if (!ctx.progress_namedOperator)
+            return null;
+        const count = ctx.progress_namedOperator.operators.length;
+        if (count > MAX_NAMED_OPERATOR_ADDRESS_COUNT) {
+            return {
+                id: "R-PR-1-01",
+                level: "HIGH",
+                category: "structural",
+                title: "named_operator address count exceeds limit",
+                description: `named_operator "${ctx.progress_namedOperator.name}" has ${count} addresses, ` +
+                    `exceeds MAX_NAMED_OPERATOR_ADDRESS_COUNT ${MAX_NAMED_OPERATOR_ADDRESS_COUNT}. ` +
+                    `Move aborts with E_MAX_NAMED_OPERATOR_ADDRESS_COUNT.`,
+                affected_stakeholders: ["owner", "named_operator"],
+                scenario: "Adding > 80 addresses to a single named operator",
+                mitigation: "Split into multiple named_operator names, or remove inactive addresses first",
+                evidence: `addr_count=${count}`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_1_02 = {
+    id: "R-PR-1-02",
+    category: "structural",
+    trigger: "Adding new named_operator would exceed MAX_NAMED_OPERATOR_COUNT (60)",
+    check: (ctx) => {
+        if (!ctx.progress_namedOperator || ctx.progress_namedOperator.op !== "add")
+            return null;
+        const current = ctx.current_named_operator_count ?? 0;
+        if (current >= MAX_NAMED_OPERATOR_COUNT) {
+            return {
+                id: "R-PR-1-02",
+                level: "HIGH",
+                category: "structural",
+                title: "named_operator namespace count at limit",
+                description: `Progress already has ${current} named operators, ` +
+                    `at MAX_NAMED_OPERATOR_COUNT ${MAX_NAMED_OPERATOR_COUNT}. Adding a new name will abort with E_MAX_NAMED_OPERATOR_COUNT.`,
+                affected_stakeholders: ["owner"],
+                scenario: "Adding a 61st named_operator name to a full Progress",
+                mitigation: "Use 'set' on an existing name (replace address list), or remove an unused name first",
+                evidence: `named_operator_count=${current}`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_1_03 = {
+    id: "R-PR-1-03",
+    category: "structural",
+    trigger: "context_repository add would exceed MAX_CONTEXT_REPOSITORY_COUNT (30)",
+    check: (ctx) => {
+        if (!ctx.repository)
+            return null;
+        if (ctx.repository.op === "clear")
+            return null;
+        const addCount = ctx.repository.op === "remove" ? 0 : ctx.repository.objects.length;
+        if (addCount === 0)
+            return null;
+        const current = ctx.current_context_repository_count ?? 0;
+        if (current + addCount > MAX_CONTEXT_REPOSITORY_COUNT) {
+            return {
+                id: "R-PR-1-03",
+                level: "HIGH",
+                category: "structural",
+                title: "context_repository count exceeds limit",
+                description: `Progress has ${current} repositories, adding ${addCount} would total ${current + addCount}, ` +
+                    `exceeds MAX_CONTEXT_REPOSITORY_COUNT ${MAX_CONTEXT_REPOSITORY_COUNT}. Move aborts with E_MAX_CONTEXT_REPOSITORY_COUNT.`,
+                affected_stakeholders: ["owner"],
+                scenario: "Adding too many context repositories",
+                mitigation: "Remove unused repositories first, or use repository 'set' to replace the list",
+                evidence: `current=${current}, add=${addCount}`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_1_04 = {
+    id: "R-PR-1-04",
+    category: "structural",
+    trigger: "named_operator name is empty string but is_order_holder_namespace=false",
+    check: (ctx) => {
+        if (!ctx.progress_namedOperator)
+            return null;
+        if (ctx.progress_namedOperator.name === "" && ctx.progress_namedOperator.op !== "remove") {
+            return {
+                id: "R-PR-1-04",
+                level: "MEDIUM",
+                category: "structural",
+                title: "named_operator name is empty (OrderHolder namespace)",
+                description: `progress_namedOperator.name="" — empty string maps to the OrderHolder namespace ` +
+                    `(machine::init_node_name()). This is typically set by service::buy, not by direct user op. ` +
+                    `Manual manipulation may overwrite order-payer authorization.`,
+                affected_stakeholders: ["owner", "named_operator"],
+                scenario: "User manually setting the empty-name namespace",
+                mitigation: "If intentional (e.g. order_owner_set internal call), confirm. Otherwise use a non-empty name.",
+                evidence: `name=""`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_2_01 = {
+    id: "R-PR-2-01",
+    category: "semantic",
+    trigger: "task_set on Progress that already has a task (E_TASK_ALREADY_SET)",
+    check: (ctx) => {
+        if (!ctx.task)
+            return null;
+        if (ctx.current_task !== null && ctx.current_task !== undefined) {
+            return {
+                id: "R-PR-2-01",
+                level: "HIGH",
+                category: "semantic",
+                title: "task_set on already-bound Progress (irreversible)",
+                description: `Progress already has task=${ctx.current_task}. task_set is one-time; ` +
+                    `Move aborts with E_TASK_ALREADY_SET. There is no way to change the task after first set.`,
+                affected_stakeholders: ["owner", "submitter"],
+                scenario: "User tries to rebind Progress to a different Order",
+                mitigation: "Create a new Progress via service::buy with the new Order; the old Progress is permanently bound",
+                evidence: `current_task=${ctx.current_task}`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_2_02 = {
+    id: "R-PR-2-02",
+    category: "semantic",
+    trigger: "operate.message exceeds MAX_LONG_NAME_LENGTH (long-name constraint)",
+    check: (ctx) => {
+        if (!ctx.operate?.message)
+            return null;
+        const msg = ctx.operate.message;
+        if (msg.length > 1024) {
+            return {
+                id: "R-PR-2-02",
+                level: "MEDIUM",
+                category: "semantic",
+                title: "operate.message exceeds long-name length",
+                description: `operate.message length ${msg.length} exceeds MAX_LONG_NAME_LENGTH (1024). ` +
+                    `Move aborts in common::LONG_NAME check.`,
+                affected_stakeholders: ["submitter"],
+                scenario: "Long deliverable message",
+                mitigation: "Truncate message to ≤ 1024 chars; store full payload in a context Repository",
+                evidence: `msg_len=${msg.length}`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_2_03 = {
+    id: "R-PR-2-03",
+    category: "semantic",
+    trigger: "operate.op is not a valid enum value (schema-enforced, defense-in-depth)",
+    check: (ctx) => {
+        if (!ctx.operate)
+            return null;
+        const validOps = ["next", "hold", "unhold", "adminUnhold"];
+        if (ctx.operate.op && !validOps.includes(ctx.operate.op)) {
+            return {
+                id: "R-PR-2-03",
+                level: "HIGH",
+                category: "semantic",
+                title: `operate.op must be one of: ${validOps.join(", ")}`,
+                description: `op enum selects the Move function: next=accomplish, hold=hold(bHold=true), ` +
+                    `unhold=hold(bHold=false), adminUnhold=unhold (224 permission).`,
+                affected_stakeholders: ["submitter"],
+                scenario: "Schema validation bypassed or stale client",
+                mitigation: `Use one of: ${validOps.join(", ")}`,
+                evidence: `op=${ctx.operate.op}`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_3_01 = {
+    id: "R-PR-3-01",
+    category: "permission",
+    trigger: "op='adminUnhold' (224 permission) — force release bypassing holder check",
+    check: (ctx) => {
+        if (ctx.operate?.op !== "adminUnhold")
+            return null;
+        return {
+            id: "R-PR-3-01",
+            level: "HIGH",
+            category: "permission",
+            title: "adminUnhold bypasses holder check (broad blast radius)",
+            description: `adminUnhold uses 224 permission to release a held forward WITHOUT verifying sender == holder. ` +
+                `If 224 is granted too broadly, any 224-holder can release ANY held forward in this Progress.`,
+            affected_stakeholders: ["owner", "named_operator", "submitter"],
+            scenario: "Admin force-releases a forward that the original holder still wanted held",
+            mitigation: "1) Grant 224 only to dedicated recovery addresses. 2) Log every adminUnhold for audit. " +
+                "3) Prefer normal unhold (holder self-release) when possible.",
+            evidence: `adminUnhold=true, forward=${ctx.operate.operation.forward}`,
+        };
+    },
+};
+const R_PR_3_02 = {
+    id: "R-PR-3-02",
+    category: "permission",
+    trigger: "namedOperator short-circuit bypasses 220-225 permission check",
+    check: (ctx) => {
+        if (!ctx.operate)
+            return null;
+        if (ctx.forward_named_operator && ctx.forward_named_operator !== "") {
+            return {
+                id: "R-PR-3-02",
+                level: "MEDIUM",
+                category: "permission",
+                title: "Forward advance via named_operator short-circuits 220-225 check",
+                description: `Forward "${ctx.operate.operation.forward}" uses namedOperator="${ctx.forward_named_operator}". ` +
+                    `Move's ASSERT_PERMISSION returns immediately if IsNamedOperator() succeeds, WITHOUT checking ` +
+                    `any permission index. Anyone in the named_operator list can advance this forward.`,
+                affected_stakeholders: ["owner", "named_operator"],
+                scenario: "Operator list too permissive (e.g. includes expired/compromised addresses)",
+                mitigation: "1) Keep named_operator lists minimal. 2) Use namedOperator_remove to revoke access promptly. " +
+                    "3) For sensitive forwards, prefer Forward.permissionIndex (Some) for dual-check.",
+                evidence: `named_operator=${ctx.forward_named_operator}`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_3_03 = {
+    id: "R-PR-3-03",
+    category: "permission",
+    trigger: "Forward has guard (Some) — Passport required but not provided",
+    check: (ctx) => {
+        if (!ctx.operate)
+            return null;
+        if (ctx.forward_has_guard && !ctx.forward_permission_index) {
+            return {
+                id: "R-PR-3-03",
+                level: "HIGH",
+                category: "permission",
+                title: "Forward guard requires Passport",
+                description: `Forward "${ctx.operate.operation.forward}" has a guard (Some). ` +
+                    `Move's next_imp asserts E_NEED_PASSPORT for guarded forwards when called without passport. ` +
+                    `Use next_with_passport / order_next_with_passport instead.`,
+                affected_stakeholders: ["submitter"],
+                scenario: "User calls next() on a guarded forward without passport",
+                mitigation: "Submit via *_with_passport variant; ensure submission data is valid for the Guard",
+                evidence: `forward=${ctx.operate.operation.forward}, has_guard=${ctx.forward_has_guard}`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_4_01 = {
+    id: "R-PR-4-01",
+    category: "lifecycle",
+    trigger: "Machine not published — Progress cannot be created",
+    check: (ctx) => {
+        if (ctx.machine_published === false) {
+            return {
+                id: "R-PR-4-01",
+                level: "CRITICAL",
+                category: "lifecycle",
+                title: "Machine not published — Progress creation blocked",
+                description: `Machine ${ctx.current_machine ?? "(unknown)"} is not published. ` +
+                    `Progress requires a published Machine (machine::on_progress_new asserts published state). ` +
+                    `All Progress ops will fail with E_MACHINE_NOT_MATCH or similar.`,
+                affected_stakeholders: ["owner"],
+                scenario: "User attempts to create Progress before Machine publish",
+                mitigation: "Publish the Machine first (machine::publish, 205 permission), then create Progress",
+                evidence: `machine=${ctx.current_machine}, published=false`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_4_02 = {
+    id: "R-PR-4-02",
+    category: "lifecycle",
+    trigger: "operate on already-accomplished forward (E_FORWARD_ALREADY_ACCOMPLISHED)",
+    check: (ctx) => {
+        if (!ctx.operate)
+            return null;
+        if (ctx.forward_already_accomplished) {
+            return {
+                id: "R-PR-4-02",
+                level: "MEDIUM",
+                category: "lifecycle",
+                title: "Forward already accomplished — re-hold blocked",
+                description: `Forward "${ctx.operate.operation.forward}" to "${ctx.operate.operation.next_node_name}" ` +
+                    `is already accomplished. Move aborts with E_FORWARD_ALREADY_ACCOMPLISHED on any re-hold attempt.`,
+                affected_stakeholders: ["submitter"],
+                scenario: "User retries an already-completed forward (race condition or stale state)",
+                mitigation: "Query Progress.current — if already past target, no action needed; if parallel session, use a different forward",
+                evidence: `forward=${ctx.operate.operation.forward}, accomplished=true`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_4_03 = {
+    id: "R-PR-4-03",
+    category: "lifecycle",
+    trigger: "unhold by non-holder without 224 permission (E_NOT_THE_HOLDER)",
+    check: (ctx) => {
+        if (!ctx.operate || ctx.operate.op !== "unhold")
+            return null;
+        if (ctx.holder_address && ctx.signer && ctx.holder_address !== ctx.signer) {
+            return {
+                id: "R-PR-4-03",
+                level: "HIGH",
+                category: "lifecycle",
+                title: "unhold by non-holder — Move will abort E_NOT_THE_HOLDER",
+                description: `Forward is held by ${ctx.holder_address}, but signer is ${ctx.signer}. ` +
+                    `Move aborts with E_NOT_THE_HOLDER unless signer has 224 permission (adminUnhold path).`,
+                affected_stakeholders: ["submitter"],
+                scenario: "User other than holder tries to release a hold",
+                mitigation: "1) Have the original holder call unhold. 2) If holder is unresponsive, use adminUnhold=true (requires 224).",
+                evidence: `holder=${ctx.holder_address}, signer=${ctx.signer}`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_5_01 = {
+    id: "R-PR-5-01",
+    category: "cross_object",
+    trigger: "operate.order_next called but progress.task != order address (E_ORDER_NOT_MATCH)",
+    check: (ctx) => {
+        if (!ctx.operate)
+            return null;
+        if (ctx.current_task && ctx.signer) {
+            return null;
+        }
+        return null;
+    },
+};
+const R_PR_5_02 = {
+    id: "R-PR-5-02",
+    category: "cross_object",
+    trigger: "context_repository_add without Registrar affiliation check",
+    check: (ctx) => {
+        if (!ctx.repository || ctx.repository.op !== "add")
+            return null;
+        return {
+            id: "R-PR-5-02",
+            level: "LOW",
+            category: "cross_object",
+            title: "context_repository_add creates Registrar affiliation",
+            description: `Adding ${ctx.repository.objects.length} repository(ies) creates Registrar affiliation ` +
+                `entries. If the Repository is later removed (disaffiliation), cross-object queries ` +
+                `that depend on it will return empty results without warning.`,
+            affected_stakeholders: ["owner", "system"],
+            scenario: "Repository deleted while Progress still references it",
+            mitigation: "Use context_repository_remove before deleting a Repository; audit affiliations periodically",
+            evidence: `add_count=${ctx.repository.objects.length}`,
+        };
+    },
+};
+const R_PR_5_03 = {
+    id: "R-PR-5-03",
+    category: "cross_object",
+    trigger: "Permission used by Progress is shared with other host objects",
+    check: (ctx) => {
+        if (!ctx.target_objects_types || ctx.target_objects_types.length < 2)
+            return null;
+        const uniqueTypes = new Set(ctx.target_objects_types);
+        if (uniqueTypes.size > 1) {
+            return {
+                id: "R-PR-5-03",
+                level: "MEDIUM",
+                category: "cross_object",
+                title: "Permission shared across heterogeneous host objects",
+                description: `Single Permission applied to ${[...uniqueTypes].join(", ")}. ` +
+                    `Progress builtin indexes (220-225) have different semantics per host object; ` +
+                    `granting 221 (PROGRESS_NAMED_OPERATOR) to a non-Progress entity is meaningless.`,
+                affected_stakeholders: ["owner"],
+                scenario: "One Permission for both Progress and Machine",
+                mitigation: "Use separate Permission objects per host object type",
+                evidence: `types=${[...uniqueTypes].join(",")}`,
+            };
+        }
+        return null;
+    },
+};
+const R_PR_5_04 = {
+    id: "R-PR-5-04",
+    category: "cross_object",
+    trigger: "Progress without bound Order (order=null) — order_next/order_hold blocked",
+    check: (ctx) => {
+        if (!ctx.operate)
+            return null;
+        if (ctx.current_task === null && ctx.operate.op !== undefined) {
+            return {
+                id: "R-PR-5-04",
+                level: "MEDIUM",
+                category: "cross_object",
+                title: "operate without bound Order — order_next/order_hold unavailable",
+                description: `Progress has no bound task (task=null). order_next and order_hold require ` +
+                    `progress.task == order address (E_ORDER_NOT_MATCH). Use plain next()/hold() instead.`,
+                affected_stakeholders: ["submitter"],
+                scenario: "User tries order variant on a task-less Progress",
+                mitigation: "Use non-order next()/hold() variant, OR call task_set first to bind an Order",
+                evidence: `task=null`,
+            };
+        }
+        return null;
+    },
+};
+const ALL_RULES = [
+    R_PR_1_01, R_PR_1_02, R_PR_1_03, R_PR_1_04,
+    R_PR_2_01, R_PR_2_02, R_PR_2_03,
+    R_PR_3_01, R_PR_3_02, R_PR_3_03,
+    R_PR_4_01, R_PR_4_02, R_PR_4_03,
+    R_PR_5_01, R_PR_5_02, R_PR_5_03, R_PR_5_04,
+];
+export const PROGRESS_RISK_VERSION = "1.0.0";
+export function getAllProgressRiskRules() {
+    return [...ALL_RULES];
+}
+export function getProgressRiskRulesCount() {
+    return ALL_RULES.length;
+}
+export function getProgressRiskRulesByCategory(category) {
+    return ALL_RULES.filter(r => r.category === category);
+}
+export function assessProgressRisks(ctx) {
+    const risks = [];
+    for (const rule of ALL_RULES) {
+        const r = rule.check(ctx);
+        if (r)
+            risks.push(r);
+    }
+    const overall = risks.length === 0
+        ? "LOW"
+        : risks.some(r => r.level === "CRITICAL") ? "CRITICAL"
+            : risks.some(r => r.level === "HIGH") ? "HIGH"
+                : risks.some(r => r.level === "MEDIUM") ? "MEDIUM"
+                    : "LOW";
+    const byCategory = {};
+    for (const r of risks) {
+        byCategory[r.category] = (byCategory[r.category] ?? 0) + 1;
+    }
+    const advice = {};
+    for (const r of risks) {
+        for (const s of r.affected_stakeholders) {
+            if (!advice[s])
+                advice[s] = [];
+            advice[s].push(`${r.id}: ${r.mitigation}`);
+        }
+    }
+    return {
+        summary: `Assessed ${risks.length} risk(s) across ${Object.keys(byCategory).length} categories`,
+        risks,
+        overall_risk: overall,
+        risks_by_category: byCategory,
+        stakeholder_advice: advice,
+        needs_human_review: risks.some(r => r.level === "CRITICAL" || r.level === "HIGH"),
+    };
+}

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

@@ -0,0 +1,38 @@
+export type ProgressTemplateParamType = "address" | "string" | "number" | "string[]" | "name";
+export interface ProgressTemplateParam {
+    name: string;
+    type: ProgressTemplateParamType;
+    description: string;
+    required: boolean;
+    default?: string | number | string[];
+}
+export interface ProgressTemplate {
+    id: string;
+    name: string;
+    description: string;
+    applicable_scenes: string[];
+    industry_tags: string[];
+    params: ProgressTemplateParam[];
+    body: (params: Record<string, string | number | string[]>) => object;
+    notes?: string[];
+}
+export declare const PROGRESS_TEMPLATES: ProgressTemplate[];
+export declare const PROGRESS_TEMPLATES_VERSION = "1.0.0";
+export declare function getAllProgressTemplates(): ProgressTemplate[];
+export declare function getProgressTemplateById(id: string): ProgressTemplate | undefined;
+export declare function getProgressTemplatesByScene(sceneId: string): ProgressTemplate[];
+export declare function getProgressTemplatesByIndustry(industry: string): ProgressTemplate[];
+export declare function suggestProgressTemplateForScene(sceneId: string): ProgressTemplate | undefined;
+export declare function listProgressTemplates(): {
+    id: string;
+    name: string;
+    description: string;
+    scenes: string[];
+}[];
+export declare function fillProgressTemplate(templateId: string, params: Record<string, string | number | string[]>): {
+    ok: true;
+    body: object;
+} | {
+    ok: false;
+    error: string;
+};