@wowok/agent-mcp 2.6.1 → 2.6.3

package/dist/schema/project/index.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 const IndustryEnum = z.enum([
     "general",
     "retail",
+    "retail_d2c",
     "service",
     "rental",
     "freelance",
@@ -70,11 +71,17 @@ export const ProjectOperationInputSchema = z
         "delete_project",
         "assemble_context",
         "get_machine_graph",
+        "get_guard_graph",
         "generate_deployment_doc",
         "pre_evaluate_check",
         "verify_deployment",
         "clone_project_to_network",
         "migrate_network",
+        "migrate_to_mainnet",
+        "plan_object_edit",
+        "apply_object_edit",
+        "patch_machine_nodes",
+        "patch_guard_tree",
     ])
         .describe("Action to perform. Two categories:\n" +
         "1. Project Entity + Evaluation (15, GLM6): list_projects, create_project, create_project_from_onchain, update_project, get_project_detail, add_object, remove_object, create_version, build_graph, get_graph, evaluate_project, save_evaluation, compare_projects, refresh_objects, get_object_diff. Projects are first-class entities with SQLite persistence, rigid project-object relationships, three-pathway graph construction, and a dual rule-based + LLM-assisted evaluation engine.\n" +
@@ -83,7 +90,10 @@ export const ProjectOperationInputSchema = z
     project: z
         .string()
         .optional()
-        .describe("Project prefix (human-readable unique identifier). Used by create_version, build_graph, evaluate_project, etc. Takes precedence resolution: project_id > project (prefix)."),
+        .describe("Project prefix (human-readable unique identifier). " +
+        "For create_project: OPTIONAL — if omitted, auto-derived from project_name (e.g. 'Twitch Service' → 'twitch_service'). " +
+        "For other actions (build_graph, evaluate_project, etc.): used to identify the project. " +
+        "Takes precedence resolution: project_id > project (prefix)."),
     version: z
         .string()
         .regex(/^v\d+$/)
@@ -128,7 +138,8 @@ export const ProjectOperationInputSchema = z
         "(and not 'general'), the system auto-applies an industry blueprint " +
         "with ~10 draft objects (Permission, Service, Machine, Guard, Treasury, " +
         "Allocation, etc.) + graph edges, ready for deployment. " +
-        "Supported industries: 'general' (no template), 'retail', 'service', " +
+        "Supported industries: 'general' (no template), 'retail', 'retail_d2c' " +
+        "(Direct-to-Consumer, e.g., Shopify — Allocation escrow + 2 Guards), 'service', " +
         "'rental', 'freelance', 'education', 'travel', 'subscription', 'custom'. " +
         "Each industry preset embeds risk constraints (e.g., 'freelance' does " +
         "NOT require compensation_fund, while 'rental'/'travel' do). " +
@@ -269,7 +280,11 @@ export const ProjectOperationInputSchema = z
     refresh_before_eval: z
         .boolean()
         .optional()
-        .describe("When true, evaluate_project refreshes object cache from chain before evaluating. Default false."),
+        .describe("When true (DEFAULT), evaluate_project refreshes object cache from chain before evaluating. " +
+        "Set to false ONLY for read-only checks where staleness is acceptable (e.g., quick comparisons). " +
+        "BUG-P0-2 fix: previously defaulted to false, causing stale Machine node_count and other " +
+        "dynamic-field-derived fields to produce false findings (e.g., 'Machine has no nodes'). " +
+        "Now defaults to true — set refresh_before_eval=false explicitly to skip refresh."),
     eval_score: z
         .number()
         .min(0)
@@ -320,6 +335,56 @@ export const ProjectOperationInputSchema = z
         "'detailed': adds sale list, arbitration list, reward list. " +
         "'full': complete fields including stock, price, wip_hash, all config. " +
         "Use 'summary' for quick review; request 'detailed' or 'full' only when deeper inspection is needed."),
+    object_kind: z
+        .enum(["machine", "guard"])
+        .optional()
+        .describe("Object kind for plan_object_edit. 'machine' = Machine workflow directed graph (cycles allowed), 'guard' = Guard computation tree. " +
+        "Required when action='plan_object_edit'. Inferred from action for patch_machine_nodes (always 'machine') " +
+        "and patch_guard_tree (always 'guard')."),
+    edit_format: z
+        .enum(["tree_outline", "json"])
+        .optional()
+        .describe("Format of the edited content for plan_object_edit. " +
+        "'tree_outline' (default): the indented Markdown outline produced by get_machine_graph / get_guard_graph (human-editable). " +
+        "'json': raw JSON (machine-readable, for programmatic edits). " +
+        "Both formats are bidirectional with the parse functions in knowledge/machine-render.ts / guard-render.ts."),
+    edited_content: z
+        .string()
+        .optional()
+        .describe("Edited content for plan_object_edit. Must be in the format specified by edit_format. " +
+        "For 'tree_outline': the full tree_outline string from get_machine_graph/get_guard_graph with user edits. " +
+        "For 'json': a JSON string matching the Machine/Guard schema. " +
+        "The content is parsed + validated + diffed against the current on-chain state."),
+    plan_id: z
+        .string()
+        .optional()
+        .describe("Plan ID returned by plan_object_edit. Required for apply_object_edit. " +
+        "The plan is short-lived (10-minute TTL) and stored in-memory."),
+    expected_hash: z
+        .string()
+        .optional()
+        .describe("Expected hash returned by plan_object_edit. Required for apply_object_edit. " +
+        "Used for optimistic concurrency control: if the on-chain state changed between plan and apply, " +
+        "the hash will mismatch and apply will refuse to proceed (stale edit protection)."),
+    patch_operations: z
+        .array(z.string())
+        .optional()
+        .describe("Patch operations for patch_machine_nodes / patch_guard_tree. Each string is a single patch operation.\n" +
+        "Machine operations (13 total):\n" +
+        "  'add node <name>' | 'remove node <name>' | 'set description <node_name> <text...>'\n" +
+        "  'add edge <from> <to>' | 'remove edge <from> <to>' | 'set threshold <edge_from> <edge_to> <value>'\n" +
+        "  'add forward <edge_from> <edge_to> <forward_name>' | 'remove forward <edge_from> <edge_to> <forward_name>'\n" +
+        "  'set guard <edge_from> <edge_to> <forward_name> <guard_addr_or_name|none>'\n" +
+        "  'set permission <edge_from> <edge_to> <forward_name> <perm_index>'\n" +
+        "  'set operator <edge_from> <edge_to> <forward_name> <named_operator|none>'\n" +
+        "  'set weight <edge_from> <edge_to> <forward_name> <weight>'\n" +
+        "  'set retained_submission <edge_from> <edge_to> <forward_name> <comma_separated_indices|none>'\n" +
+        "Guard operations (8 total — see patch_guard_tree):\n" +
+        "  'add table <identifier> <name|none> <value_type> <b_submission> [json_value]'\n" +
+        "  'remove table <identifier>' | 'set table_value <identifier> [json_value|none]'\n" +
+        "  'set table_name <identifier> <name|none>' | 'set table_submission <identifier> <true|false>'\n" +
+        "  'set root <json_node>' | 'set rely <comma_separated_guard_addresses|none>'\n" +
+        "Operations are applied in order. Both patches are validated (validateMachine/validateGuard) before execution."),
 })
     .strict();
 const AssembleContextResultSchema = z
@@ -695,7 +760,7 @@ const GenerateDeploymentDocResultSchema = z
             status: z.enum(["PASS", "WARN", "FAIL"]).describe("Check result status."),
             message: z.string().describe("Human-readable check result message."),
         }).strict()).describe("Per-dimension check results."),
-    }).strict().describe("Stage gate validation (GLM6 5-stage lifecycle 衔接). Validates Stage 3 risk score threshold (>=80 PASS, >=50 WARN, <50 FAIL) and Stage 4 deployment doc generation prerequisite."),
+    }).strict().describe("Stage gate validation (GLM6 5-stage lifecycle handoff). Validates Stage 3 risk score threshold (>=80 PASS, >=50 WARN, <50 FAIL) and Stage 4 deployment doc generation prerequisite."),
     deployment_scan: z.object({
         overall_readiness: z.enum(["ready", "blocked", "warnings"]).describe("'ready' = all 20 checks pass; 'blocked' = any critical fail; 'warnings' = only warning fails."),
         critical_count: z.number().describe("Number of critical findings (blocks deployment)."),
@@ -817,6 +882,158 @@ const GetMachineGraphResultSchema = z
     edges: z.array(MachineGraphEdgeSchema).describe("Directed edges (pairs) connecting nodes. Each edge has a threshold and forwards."),
     published: z.boolean().nullable().describe("Whether the Machine is published (locked for production). null = unknown."),
     paused: z.boolean().nullable().describe("Whether the Machine is paused (not generating new Progress). null = unknown."),
+    mermaid: z.string().describe("Mermaid stateDiagram-v2 string visualizing the directed graph. Entry nodes start from [*]. Edge labels include forward name + threshold + guard info. Cycles (revision loops) are rendered as normal edges. Includes a color legend comment block + BehaviorTree.CPP-style color annotations (entry=green, terminal=red, revision=amber, normal=blue). Renderable in markdown viewers."),
+    tree_outline: z.string().describe("Indented Markdown outline of the directed graph (human-editable format). Lists edges as outline entries with forwards nested under each edge. Includes a Backrefs section consolidating incoming edges per node (editing aid — answers 'who transitions INTO node X?'). Bidirectional with parseMachineTreeIndented(). Includes JSON code block for round-trip safety. Use this for the download -> edit -> republish workflow."),
+    ascii_art: z.string().describe("ASCII art directed graph visualization using arrow notation (A -forward-> B). Cycle (revision loop) and terminal annotations included. Terminal-friendly, avoids JSON escaping issues that affect multi-line Mermaid strings. Use when rendering in plain-text contexts."),
+    markmap: z.string().describe("Markmap-compatible Markdown string (heading levels represent hierarchy). Edge-centric layout with forwards nested under edges. Renderable by VS Code Markmap extension or markmap.js. Provides an interactive mind-map view of the workflow."),
+})
+    .strict();
+const GuardGraphNodeSchema = z.lazy(() => z.object({
+    type: z.string().describe("Guard node type (logic_and, query, identifier, context, calc_*, convert_*, vec_*, etc.)."),
+    nodes: z.array(GuardGraphNodeSchema).optional().describe("Child nodes (for logic_and/or, calc_*, vec_contains_*, etc.)."),
+    node: GuardGraphNodeSchema.optional().describe("Single child (for logic_not, convert_*, value_type)."),
+    nodeLeft: GuardGraphNodeSchema.optional().describe("Left child (for vec_indexof_*)."),
+    nodeRight: GuardGraphNodeSchema.optional().describe("Right child (for vec_indexof_*)."),
+    query: z.union([z.number(), z.string()]).optional().describe("Query instruction ID or name (for query nodes)."),
+    object: z.object({
+        identifier: z.number().optional(),
+        convert_witness: z.number().optional(),
+    }).optional().describe("Query target object reference."),
+    parameters: z.array(GuardGraphNodeSchema).optional().describe("Query parameters."),
+    identifier: z.number().optional().describe("Table entry index (for identifier nodes)."),
+    context: z.string().optional().describe("Context type: Signer, Clock, or Guard."),
+}).strict());
+const GuardTableEntrySchema = z.object({
+    identifier: z.number().describe("Table entry index (0-255)."),
+    b_submission: z.boolean().describe("Whether this entry is submitted at runtime."),
+    value_type: z.union([z.number(), z.string()]).describe("Value type (numeric code or name)."),
+    value: z.unknown().optional().describe("Constant value (if b_submission=false)."),
+    name: z.string().optional().describe("Human-readable name/description."),
+}).strict();
+const GetGuardGraphResultSchema = z
+    .object({
+    action: z.literal("get_guard_graph"),
+    guardAddress: z.string().describe("The Guard object address."),
+    guardName: z.string().nullable().describe("The Guard's local name (from LocalMark) if available."),
+    root: GuardGraphNodeSchema.describe("Root computation node (returns Bool). The tree is recursive — each node may have children."),
+    table: z.array(GuardTableEntrySchema).describe("Guard data table entries (constants + submission slots)."),
+    rely: z.object({
+        guards: z.array(z.string()),
+        logic_or: z.boolean().optional(),
+    }).nullable().describe("Rely dependencies (other Guards this Guard depends on). null = no rely."),
+    immutable: z.boolean().nullable().describe("Whether the Guard is immutable (frozen for verification). null = unknown."),
+    mermaid: z.string().describe("Mermaid flowchart TD string visualizing the tree. Node shapes: {}=decision (logic_*), []=computation/query, ([])=leaf (identifier), {{}}=context. Includes a color legend comment block + BehaviorTree.CPP-style color annotations (control=blue, decision=amber, computation=purple, query=cyan, leaf=gray, context=green)."),
+    tree_outline: z.string().describe("Indented Markdown outline of the tree (human-editable format). Bidirectional with parseGuardTreeIndented(). Includes JSON code block for round-trip safety."),
+    ascii_art: z.string().describe("ASCII art tree visualization using box-drawing characters (+-- --, |). Table summary appended. Terminal-friendly, avoids JSON escaping issues that affect multi-line Mermaid strings."),
+    markmap: z.string().describe("Markmap-compatible Markdown string (heading levels represent tree depth). Root -> branches -> leaves hierarchy. Renderable by VS Code Markmap extension or markmap.js. Provides an interactive mind-map view of the Guard tree."),
+})
+    .strict();
+const PlanObjectEditResultSchema = z
+    .object({
+    action: z.literal("plan_object_edit"),
+    plan_id: z.string().describe("Unique plan ID (UUID). Pass to apply_object_edit within 10 minutes to execute."),
+    object_kind: z.enum(["machine", "guard"]).describe("The object kind that was edited."),
+    object_address: z.string().describe("The on-chain object address being edited."),
+    object_name: z.string().nullable().describe("The object's local name (from LocalMark) if available."),
+    expected_hash: z.string().describe("SHA-256 hash of (current_onchain_state + edited_content). Pass to apply_object_edit as expected_hash for stale-edit detection."),
+    diff: z.object({
+        added: z.array(z.string()).describe("List of added items (node names, edge 'from->to', table identifiers, etc.)."),
+        removed: z.array(z.string()).describe("List of removed items."),
+        modified: z.array(z.string()).describe("List of modified items with a brief description of the change."),
+        summary: z.string().describe("Human-readable one-line diff summary (e.g. '2 nodes added, 1 edge removed, 3 forwards modified')."),
+    }).describe("Structured diff between current on-chain state and edited content."),
+    warnings: z.array(z.object({
+        id: z.string().describe("Warning identifier (e.g. 'W-01')."),
+        description: z.string().describe("What the warning is about."),
+        impact: z.string().describe("Potential impact if ignored."),
+    })).describe("Non-blocking warnings (the edit can still proceed, but review is recommended)."),
+    blocking_errors: z.array(z.object({
+        id: z.string().describe("Error identifier (e.g. 'E-01')."),
+        description: z.string().describe("What the error is."),
+        impact: z.string().describe("Why this blocks execution."),
+    })).describe("Blocking errors (the edit CANNOT proceed until these are fixed)."),
+    can_apply: z.boolean().describe("Whether apply_object_edit can proceed. false if blocking_errors is non-empty."),
+    prepared_call: z.unknown().nullable().describe("The prepared onchain_operations call data (operation_type + data). null if can_apply=false. Pass this to onchain_operations to execute the edit."),
+    expires_at: z.string().describe("ISO timestamp when the plan expires (10 minutes from creation). After expiry, apply_object_edit will refuse to proceed."),
+    summary: z.string().describe("Human-readable one-line plan summary."),
+})
+    .strict();
+const ApplyObjectEditResultSchema = z
+    .object({
+    action: z.literal("apply_object_edit"),
+    plan_id: z.string().describe("The plan ID that was applied."),
+    applied: z.boolean().describe("Whether the plan was successfully applied (hash matched and plan was fresh)."),
+    hash_match: z.boolean().describe("Whether the expected_hash matched the stored plan hash. false = stale edit detected."),
+    prepared_call: z.unknown().nullable().describe("The prepared onchain_operations call data. Pass this to onchain_operations to execute the edit on-chain. null if applied=false."),
+    error: z.string().nullable().describe("Error message if applied=false (e.g. 'Plan not found', 'Hash mismatch — on-chain state changed', 'Plan expired'). null on success."),
+    next_step: z.string().describe("Instructions for the next step (typically 'Pass prepared_call to onchain_operations to execute the edit on-chain')."),
+})
+    .strict();
+const PatchMachineNodesResultSchema = z
+    .object({
+    action: z.literal("patch_machine_nodes"),
+    machine_address: z.string().describe("The Machine object address being patched."),
+    machine_name: z.string().nullable().describe("The Machine's local name (from LocalMark) if available."),
+    operations_applied: z.number().describe("Number of patch operations successfully applied."),
+    operations_failed: z.array(z.object({
+        operation: z.string().describe("The original operation string."),
+        error: z.string().describe("Why the operation failed."),
+    })).describe("Operations that failed parse/apply (not applied). Also surfaced as E-OP entries in blocking_errors for schema symmetry with plan_object_edit."),
+    patched_nodes: z.array(z.unknown()).describe("The patched Machine nodes (after applying all successful operations)."),
+    patched_edges: z.array(z.unknown()).describe("The patched Machine edges (after applying all successful operations)."),
+    diff: z.object({
+        added: z.array(z.string()).describe("List of added items."),
+        removed: z.array(z.string()).describe("List of removed items."),
+        modified: z.array(z.string()).describe("List of modified items."),
+        summary: z.string().describe("Human-readable one-line diff summary."),
+    }).describe("Diff between original and patched Machine."),
+    warnings: z.array(z.object({
+        id: z.string().describe("Warning identifier (e.g. 'W-01' unreachable node, 'W-02' self-loop)."),
+        description: z.string().describe("What the warning is about."),
+        impact: z.string().describe("Potential impact if ignored."),
+    })).describe("Non-blocking warnings from validateMachine (W-01 unreachable, W-02 self-loop)."),
+    blocking_errors: z.array(z.object({
+        id: z.string().describe("Error identifier (e.g. 'E-01' no entry forward, 'E-02' orphan endpoint, 'E-03' too many nodes, 'E-OP' operation failed)."),
+        description: z.string().describe("What the error is."),
+        impact: z.string().describe("Why this blocks execution."),
+    })).describe("Blocking errors (operation failures + structural validation). The patch CANNOT proceed until these are fixed. Empty array when can_apply=true."),
+    can_apply: z.boolean().describe("Whether the patch can be applied on-chain. false if any blocking_errors exist (operation failures or validateMachine blocking errors)."),
+    prepared_call: z.unknown().nullable().describe("The prepared onchain_operations call data. null if can_apply=false."),
+    summary: z.string().describe("Human-readable one-line patch summary."),
+})
+    .strict();
+const PatchGuardTreeResultSchema = z
+    .object({
+    action: z.literal("patch_guard_tree"),
+    guard_address: z.string().describe("The Guard object address being patched."),
+    guard_name: z.string().nullable().describe("The Guard's local name (from LocalMark) if available."),
+    operations_applied: z.number().describe("Number of Guard patch operations successfully applied."),
+    operations_failed: z.array(z.object({
+        operation: z.string().describe("The original operation string."),
+        error: z.string().describe("Why the operation failed."),
+    })).describe("Operations that failed parse/apply (not applied). Also surfaced as E-OP entries in blocking_errors."),
+    patched_root: z.unknown().describe("The patched Guard root node (after applying all successful operations). For set_root, this is the new root; otherwise the original root unchanged."),
+    patched_table: z.array(z.unknown()).describe("The patched Guard table entries (after applying all successful table operations)."),
+    patched_rely: z.unknown().nullable().describe("The patched rely field (cross-guard composition). null if rely was cleared or never set. Shape: { guards: string[], logic_or?: boolean }."),
+    diff: z.object({
+        added: z.array(z.string()).describe("List of added items (table entries, tree nodes)."),
+        removed: z.array(z.string()).describe("List of removed items."),
+        modified: z.array(z.string()).describe("List of modified items with a brief description of the change."),
+        summary: z.string().describe("Human-readable one-line diff summary."),
+    }).describe("Diff between original and patched Guard (root tree + table)."),
+    warnings: z.array(z.object({
+        id: z.string().describe("Warning identifier (e.g. 'W-01' dead submission slot, 'W-02' orphan table entry, 'W-03' deep nesting)."),
+        description: z.string().describe("What the warning is about."),
+        impact: z.string().describe("Potential impact if ignored."),
+    })).describe("Non-blocking warnings from validateGuard (W-01 dead submission slot, W-02 orphan table entry, W-03 deep nesting > 16)."),
+    blocking_errors: z.array(z.object({
+        id: z.string().describe("Error identifier (e.g. 'E-01' no root, 'E-02' identifier not in table, 'E-03' table too large, 'E-OP' operation failed)."),
+        description: z.string().describe("What the error is."),
+        impact: z.string().describe("Why this blocks execution."),
+    })).describe("Blocking errors (operation failures + structural validation). The patch CANNOT proceed until these are fixed. Empty array when can_apply=true."),
+    can_apply: z.boolean().describe("Whether the patch can be applied on-chain. false if any blocking_errors exist."),
+    prepared_call: z.unknown().nullable().describe("The prepared onchain_operations call data (operation_type='guard'). null if can_apply=false."),
+    summary: z.string().describe("Human-readable one-line patch summary."),
 })
     .strict();
 const CloneProjectToNetworkResultSchema = z
@@ -841,6 +1058,43 @@ const MigrateNetworkResultSchema = z
     next_steps: z.string().describe("Instructions for deploying the migrated objects on the target network."),
 })
     .strict();
+const MigrationPlanStepSchema = z.object({
+    step: z.number().describe("Step number (1-5)."),
+    status: z.enum(["completed", "pending_user_action"]).describe("Whether this step is done or awaits user action."),
+    action: z.string().describe("The action to perform (e.g. 'clone_project_to_network', 'onchain_operations', 'local_mark_operation', 'update_project', 'build_graph')."),
+    description: z.string().describe("Human-readable description of what this step does."),
+    result: z.string().optional().describe("Result of this step (only present when status='completed')."),
+    deployment_plan: z.array(z.object({
+        order: z.number(),
+        object_type: z.string(),
+        object_name: z.string(),
+        operation_type: z.string(),
+        localmark_name: z.string(),
+        note: z.string(),
+    })).optional().describe("Deployment plan for step 2 (on-chain deployment). Only present for step 2."),
+    names_to_register: z.array(z.string()).optional().describe("LocalMark names to re-register on mainnet. Only present for step 3."),
+    critical_note: z.string().optional().describe("Critical note for this step."),
+}).strict();
+const MigrateToMainnetResultSchema = z
+    .object({
+    action: z.literal("migrate_to_mainnet"),
+    migration_status: z.string().describe("Overall migration status (e.g. 'step_1_complete_steps_2_5_pending_user_action')."),
+    source_project: z.object({
+        prefix: z.string(),
+        network: z.string(),
+        preserved: z.boolean().describe("Whether the source project is preserved unchanged (always true)."),
+    }).strict(),
+    target_project: z.object({
+        prefix: z.string(),
+        project_id: z.string(),
+        network: z.string(),
+        cloned_objects_count: z.number(),
+    }).strict(),
+    key_principle: z.string().describe("Explains that testnet/mainnet are different projects with different addresses for same names."),
+    migration_plan: z.array(MigrationPlanStepSchema).describe("5-step migration plan. Step 1 is completed; steps 2-5 require user action."),
+    summary: z.string().describe("Human-readable summary of the migration."),
+})
+    .strict();
 export const ProjectOperationOutputSchema = z
     .object({
     result: z.discriminatedUnion("action", [
@@ -866,8 +1120,18 @@ export const ProjectOperationOutputSchema = z
         PreEvaluateCheckResultSchema,
         VerifyDeploymentResultSchema,
         GetMachineGraphResultSchema,
+        GetGuardGraphResultSchema,
+        PlanObjectEditResultSchema,
+        ApplyObjectEditResultSchema,
+        PatchMachineNodesResultSchema,
+        PatchGuardTreeResultSchema,
         CloneProjectToNetworkResultSchema,
         MigrateNetworkResultSchema,
+        MigrateToMainnetResultSchema,
     ]).describe("Query result — shape depends on action"),
+    skills_recommended: z.string().optional().describe("Skills recommendation hint (F-10). Informational only — MCP executes " +
+        "independently of skills. Present when the action benefits from skills' " +
+        "business-semantic guidance (e.g. service/machine/guard/evaluation). " +
+        "Users without skills installed can ignore this field."),
 })
     .strict();