@wowok/agent-mcp 2.6.0 → 2.6.3

package/dist/tools/handlers/project.js

@@ -1,9 +1,14 @@
 import { assembleContext } from "../../project/context-assembly.js";
 import { generateDeploymentDocFromProject } from "../../project/deployment-bridge.js";
 import { LocalProject } from "@wowok/wowok";
-import { handleListProjects, handleCreateProject, handleCreateProjectFromOnchain, handleUpdateProject, handleGetProjectDetail, handleAddObject, handleRemoveObject, handleUpdateObject, handleCreateVersion, handleBuildGraph, handleGetGraph, handleEvaluateProject, handleSaveEvaluation, handleCompareProjects, handleRefreshObjects, handleGetObjectDiff, handleDeleteProject, } from "../../project/handlers.js";
+import { validateStageGate } from "../../project/stage-gate.js";
+import { scanDeployment } from "../../knowledge/deployment-scanner.js";
+import { handleListProjects, handleCreateProject, handleCreateProjectFromOnchain, handleUpdateProject, handleGetProjectDetail, handleAddObject, handleRemoveObject, handleUpdateObject, handleCreateVersion, handleBuildGraph, handleGetGraph, handleEvaluateProject, handleSaveEvaluation, handleCompareProjects, handleRefreshObjects, handleGetObjectDiff, handleDeleteProject, handleGetMachineGraph, handleGetGuardGraph, handlePreEvaluateCheck, handleVerifyDeployment, handleCloneProjectToNetwork, handleMigrateToMainnet, } from "../../project/handlers.js";
+import { handlePlanObjectEdit, handleApplyObjectEdit, handlePatchMachineNodes, handlePatchGuardTree, } from "../../project/edit-planner.js";
 import { strictParse } from "../../schema/index.js";
 import { ProjectOperationInputSchema } from "../../schema/project/index.js";
+import { getStageCache } from "../../project/index.js";
+import { getSkillsHintForProject } from "../../schema/utils/skills-recommendation.js";
 export async function handleProjectOperation(args) {
     const validated = strictParse(ProjectOperationInputSchema, args, "project_operation input");
     const { action } = validated;
@@ -60,34 +65,101 @@ export async function handleProjectOperation(args) {
         case "delete_project":
             result = await handleDeleteProject(validated);
             break;
+        case "get_machine_graph":
+            result = await handleGetMachineGraph(validated);
+            break;
+        case "get_guard_graph":
+            result = await handleGetGuardGraph(validated);
+            break;
         case "assemble_context":
             result = await assembleContext(validated);
             break;
         case "generate_deployment_doc": {
-            const { project_id, network, save = true } = validated;
+            const { project_id, network, save = true, detail_level } = validated;
             if (!project_id) {
                 throw new Error("'project_id' is required for generate_deployment_doc");
             }
             if (!network) {
                 throw new Error("'network' is required for generate_deployment_doc");
             }
-            const genResult = await generateDeploymentDocFromProject(project_id, network);
+            const genResult = await generateDeploymentDocFromProject(project_id, network, detail_level);
             if (save) {
                 await LocalProject.Instance().saveDocument(project_id, network, genResult.markdown);
             }
+            const project = await LocalProject.Instance().getProject(project_id);
+            const stageEntry = getStageCache(project?.prefix ?? project_id, project?.currentVersion ?? "v1");
+            const stageGateResult = validateStageGate({
+                stage: 4,
+                prefix: project?.prefix ?? project_id,
+                version: project?.currentVersion ?? "v1",
+                objects: [],
+                risk_status: stageEntry?.risk_status,
+                risk_can_proceed: stageEntry?.risk_can_proceed,
+                has_published_object: false,
+                deployment_doc_generated: true,
+            });
+            const scanResult = scanDeployment({
+                project_name: project?.prefix ?? project_id,
+            });
             result = {
                 action: "generate_deployment_doc",
                 markdown: genResult.markdown,
                 validation: genResult.validation,
                 saved: save,
+                detail_level: detail_level ?? "summary",
+                stage_gate: {
+                    stage: stageGateResult.stage,
+                    passed: stageGateResult.passed,
+                    can_proceed: stageGateResult.can_proceed,
+                    blocking_issues: stageGateResult.blocking_issues,
+                    warnings: stageGateResult.warnings,
+                    checks: stageGateResult.checks,
+                },
+                deployment_scan: {
+                    overall_readiness: scanResult.overall_readiness,
+                    critical_count: scanResult.findings.filter(f => f.severity === "critical").length,
+                    warning_count: scanResult.findings.filter(f => f.severity === "warning").length,
+                    findings: scanResult.findings,
+                    checks: scanResult.checks,
+                },
             };
             break;
         }
+        case "pre_evaluate_check":
+            result = await handlePreEvaluateCheck(validated);
+            break;
+        case "verify_deployment":
+            result = await handleVerifyDeployment(validated);
+            break;
+        case "clone_project_to_network":
+            result = await handleCloneProjectToNetwork(validated);
+            break;
+        case "migrate_network":
+            result = await handleCloneProjectToNetwork(validated);
+            break;
+        case "migrate_to_mainnet":
+            result = await handleMigrateToMainnet(validated);
+            break;
+        case "plan_object_edit":
+            result = await handlePlanObjectEdit(validated);
+            break;
+        case "apply_object_edit":
+            result = await handleApplyObjectEdit(validated);
+            break;
+        case "patch_machine_nodes":
+            result = await handlePatchMachineNodes(validated);
+            break;
+        case "patch_guard_tree":
+            result = await handlePatchGuardTree(validated);
+            break;
         default:
             throw new Error(`Unknown project_operation action: ${String(action)}`);
     }
+    const skillsHint = getSkillsHintForProject(action);
     return {
         content: [{ type: "text", text: JSON.stringify({ result }) }],
-        structuredContent: { result },
+        structuredContent: skillsHint
+            ? { result, skills_recommended: skillsHint }
+            : { result },
     };
 }

package/dist/tools/handlers/query.js

@@ -73,6 +73,33 @@ export async function handleWatchQueryOperations(args) {
                     }
                     return obj;
                 });
+                queryResult.objects = queryResult.objects.map((obj) => {
+                    if (obj && obj.data && obj.data.type === "Progress" && obj.data.current === "") {
+                        const machineId = obj.data.machine;
+                        const taskId = obj.data.task;
+                        return {
+                            ...obj,
+                            _diagnostic: {
+                                issue: "Progress.current is empty — order workflow is stuck at the initial state",
+                                cause: "The Machine's entry node (prev_node='') likely has no forwards defined. " +
+                                    "When Progress starts, it looks up the entry node's forwards to determine " +
+                                    "the next node. Without forwards, Progress cannot advance and the order " +
+                                    "is permanently stuck.",
+                                machine_object_id: machineId ?? null,
+                                bound_order_id: taskId ?? null,
+                                fix: [
+                                    "1. Query the Machine object (use query_toolkit with query_type='onchain_objects' and objects=[" + JSON.stringify(machineId) + "]).",
+                                    "2. Inspect node.pairs for the entry node (prev_node='').",
+                                    "3. If forwards is empty: this is the root cause. The Machine must be republished with at least one forward on the entry node.",
+                                    "4. To republish: clone the Machine nodes, add a forward to the entry node's pairs, then create a new Machine (Machine nodes are immutable after publish — see P0-2 schema validation that now blocks this).",
+                                    "5. Rebind the new Machine to the Service (service.machine field) and create a new Order to test.",
+                                ],
+                                reference: "P0-2 schema refinement in MachineNodePairSchema ensures new Machines cannot be published with empty entry-node forwards. This diagnostic catches legacy Machines that predate the fix.",
+                            },
+                        };
+                    }
+                    return obj;
+                });
             }
             result = { query_type: "onchain_objects", result: queryResult };
             break;

package/dist/tools/handlers/schema-query.js

@@ -1,4 +1,4 @@
-import { processSchemaQuery, } from "../../schema-query/index.js";
+import { processSchemaQuery, EXAMPLES_DIR, } from "../../schema-query/index.js";
 import { strictParse } from "../../schema/index.js";
 import { SchemaQueryInputSchema } from "../../schema/schema-query/index.js";
 export async function handleSchemaQuery(args) {
@@ -7,9 +7,16 @@ export async function handleSchemaQuery(args) {
         action: validated.action,
         name: validated.name,
         query: validated.query,
+        field_path: validated.field_path,
+        template: validated.template,
+        output_file: validated.output_file,
     };
     const response = processSchemaQuery(request);
     let textContent = response.message;
+    if (response.output_file_path) {
+        textContent += `\n\n📄 Full data written to: ${response.output_file_path}`;
+        textContent += `\n   Use the Read tool to access the file content.`;
+    }
     const data = response.data;
     if (response.success && data) {
         switch (request.action) {
@@ -55,6 +62,18 @@ export async function handleSchemaQuery(args) {
                 textContent += JSON.stringify(data, null, 2);
                 textContent += "\n```\n";
                 break;
+            case "get_guard_templates":
+                textContent += "\n\n## Guard Templates\n\n";
+                textContent += "```json\n";
+                textContent += JSON.stringify(data, null, 2);
+                textContent += "\n```\n";
+                break;
+            case "get_field":
+                textContent += "\n\n## Field Schema\n\n";
+                textContent += "```json\n";
+                textContent += JSON.stringify(data, null, 2);
+                textContent += "\n```\n";
+                break;
             case "search":
                 if (Array.isArray(data) && data.length > 0) {
                     textContent += `\n\nFound ${data.length} schemas matching '${request.query ?? ""}':\n`;
@@ -73,6 +92,29 @@ export async function handleSchemaQuery(args) {
                     textContent += "\n\nNo schemas found. Try 'list' to browse all available schemas, or use a broader search term.";
                 }
                 break;
+            case "search_examples": {
+                const items = (Array.isArray(data) ? data : []);
+                if (items.length > 0) {
+                    textContent += `\n\nFound ${items.length} example(s) matching '${request.query ?? ""}':\n`;
+                    for (const item of items) {
+                        textContent += `\n  • [score: ${item.score}] ${item.file}`;
+                        textContent += `\n    Title: ${item.title}`;
+                        textContent += `\n    Industry: ${item.industry} | Operation: ${item.operation_type} | Verified: ${item.verified ? "yes" : "no"}`;
+                        textContent += `\n    Tags: ${item.tags.join(", ")}`;
+                        textContent += `\n    Matched fields: ${item.matched_fields.join(", ")}`;
+                        const descPreview = item.description.length > 120
+                            ? `${item.description.slice(0, 120)}...`
+                            : item.description;
+                        textContent += `\n    Description: ${descPreview}`;
+                        textContent += "\n";
+                    }
+                    textContent += `\n  To view the full example JSON, read files from: ${EXAMPLES_DIR}`;
+                }
+                else {
+                    textContent += "\n\nNo examples found. Try broader terms like 'service', 'machine', 'guard', 'permission', or an industry name like 'rental' or 'retail'.";
+                }
+                break;
+            }
             default:
                 throw new Error(`Unknown schema_query action: ${String(request.action)}`);
         }

package/dist/tools/handlers/task-status.d.ts

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import type { ToolDispatchResult } from "../types.js";
+export declare const QueryTaskStatusInputSchema: z.ZodObject<{
+    task_id: z.ZodOptional<z.ZodString>;
+    project_id: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    project_id?: string | undefined;
+    task_id?: string | undefined;
+}, {
+    project_id?: string | undefined;
+    task_id?: string | undefined;
+}>;
+export declare const TaskStateSchema: z.ZodObject<{
+    task_id: z.ZodString;
+    operation: z.ZodString;
+    status: z.ZodEnum<["pending", "running", "completed", "failed", "cancelled"]>;
+    progress: z.ZodNumber;
+    message: z.ZodString;
+    result: z.ZodNullable<z.ZodUnknown>;
+    error: z.ZodNullable<z.ZodString>;
+    started_at: z.ZodNumber;
+    completed_at: z.ZodNullable<z.ZodNumber>;
+    project_id: z.ZodNullable<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    message: string;
+    status: "failed" | "completed" | "pending" | "cancelled" | "running";
+    error: string | null;
+    operation: string;
+    progress: number;
+    completed_at: number | null;
+    project_id: string | null;
+    task_id: string;
+    started_at: number;
+    result?: unknown;
+}, {
+    message: string;
+    status: "failed" | "completed" | "pending" | "cancelled" | "running";
+    error: string | null;
+    operation: string;
+    progress: number;
+    completed_at: number | null;
+    project_id: string | null;
+    task_id: string;
+    started_at: number;
+    result?: unknown;
+}>;
+export declare const QueryTaskStatusOutputSchema: z.ZodObject<{
+    task_id: z.ZodOptional<z.ZodString>;
+    task: z.ZodNullable<z.ZodObject<{
+        task_id: z.ZodString;
+        operation: z.ZodString;
+        status: z.ZodEnum<["pending", "running", "completed", "failed", "cancelled"]>;
+        progress: z.ZodNumber;
+        message: z.ZodString;
+        result: z.ZodNullable<z.ZodUnknown>;
+        error: z.ZodNullable<z.ZodString>;
+        started_at: z.ZodNumber;
+        completed_at: z.ZodNullable<z.ZodNumber>;
+        project_id: z.ZodNullable<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        message: string;
+        status: "failed" | "completed" | "pending" | "cancelled" | "running";
+        error: string | null;
+        operation: string;
+        progress: number;
+        completed_at: number | null;
+        project_id: string | null;
+        task_id: string;
+        started_at: number;
+        result?: unknown;
+    }, {
+        message: string;
+        status: "failed" | "completed" | "pending" | "cancelled" | "running";
+        error: string | null;
+        operation: string;
+        progress: number;
+        completed_at: number | null;
+        project_id: string | null;
+        task_id: string;
+        started_at: number;
+        result?: unknown;
+    }>>;
+    tasks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        task_id: z.ZodString;
+        operation: z.ZodString;
+        status: z.ZodEnum<["pending", "running", "completed", "failed", "cancelled"]>;
+        progress: z.ZodNumber;
+        message: z.ZodString;
+        result: z.ZodNullable<z.ZodUnknown>;
+        error: z.ZodNullable<z.ZodString>;
+        started_at: z.ZodNumber;
+        completed_at: z.ZodNullable<z.ZodNumber>;
+        project_id: z.ZodNullable<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        message: string;
+        status: "failed" | "completed" | "pending" | "cancelled" | "running";
+        error: string | null;
+        operation: string;
+        progress: number;
+        completed_at: number | null;
+        project_id: string | null;
+        task_id: string;
+        started_at: number;
+        result?: unknown;
+    }, {
+        message: string;
+        status: "failed" | "completed" | "pending" | "cancelled" | "running";
+        error: string | null;
+        operation: string;
+        progress: number;
+        completed_at: number | null;
+        project_id: string | null;
+        task_id: string;
+        started_at: number;
+        result?: unknown;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    task: {
+        message: string;
+        status: "failed" | "completed" | "pending" | "cancelled" | "running";
+        error: string | null;
+        operation: string;
+        progress: number;
+        completed_at: number | null;
+        project_id: string | null;
+        task_id: string;
+        started_at: number;
+        result?: unknown;
+    } | null;
+    task_id?: string | undefined;
+    tasks?: {
+        message: string;
+        status: "failed" | "completed" | "pending" | "cancelled" | "running";
+        error: string | null;
+        operation: string;
+        progress: number;
+        completed_at: number | null;
+        project_id: string | null;
+        task_id: string;
+        started_at: number;
+        result?: unknown;
+    }[] | undefined;
+}, {
+    task: {
+        message: string;
+        status: "failed" | "completed" | "pending" | "cancelled" | "running";
+        error: string | null;
+        operation: string;
+        progress: number;
+        completed_at: number | null;
+        project_id: string | null;
+        task_id: string;
+        started_at: number;
+        result?: unknown;
+    } | null;
+    task_id?: string | undefined;
+    tasks?: {
+        message: string;
+        status: "failed" | "completed" | "pending" | "cancelled" | "running";
+        error: string | null;
+        operation: string;
+        progress: number;
+        completed_at: number | null;
+        project_id: string | null;
+        task_id: string;
+        started_at: number;
+        result?: unknown;
+    }[] | undefined;
+}>;
+export declare function handleQueryTaskStatus(args: unknown): Promise<ToolDispatchResult>;

package/dist/tools/handlers/task-status.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { TaskTracker } from "../../project/task-tracker.js";
+export const QueryTaskStatusInputSchema = z.object({
+    task_id: z
+        .string()
+        .optional()
+        .describe("The task ID to query (returned by a prior async operation). " +
+        "If omitted, lists all recent tasks (most recent first, max 50)."),
+    project_id: z
+        .string()
+        .optional()
+        .describe("Optional filter — when listing tasks (task_id omitted), only return tasks for this project."),
+}).strict().describe("Query the status of an async task, or list all recent tasks when task_id is omitted.");
+export const TaskStateSchema = z.object({
+    task_id: z.string().describe("Unique task identifier."),
+    operation: z.string().describe("Operation type that created this task (e.g. 'build_graph')."),
+    status: z.enum(["pending", "running", "completed", "failed", "cancelled"]).describe("Current task status."),
+    progress: z.number().describe("Progress percentage 0-100."),
+    message: z.string().describe("Human-readable progress message."),
+    result: z.unknown().nullable().describe("Result payload (set when status='completed'). null otherwise."),
+    error: z.string().nullable().describe("Error message (set when status='failed'). null otherwise."),
+    started_at: z.number().describe("Timestamp (ms) when the task was created."),
+    completed_at: z.number().nullable().describe("Timestamp (ms) when the task reached a terminal state. null if still running."),
+    project_id: z.string().nullable().describe("Project ID associated with this task, if any."),
+}).strict();
+export const QueryTaskStatusOutputSchema = z.object({
+    task_id: z.string().optional().describe("The queried task ID (present when a single task was queried)."),
+    task: TaskStateSchema.nullable().describe("The task state. null if task_id not found or when listing."),
+    tasks: z.array(TaskStateSchema).optional().describe("List of tasks (present when task_id was omitted)."),
+}).strict();
+export async function handleQueryTaskStatus(args) {
+    const validated = (args && typeof args === "object" ? args : {});
+    if (validated.task_id) {
+        const task = TaskTracker.get(validated.task_id);
+        const result = {
+            task_id: validated.task_id,
+            task: task ?? null,
+            tasks: undefined,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result) }],
+            structuredContent: result,
+        };
+    }
+    const tasks = TaskTracker.list(validated.project_id).slice(0, 50);
+    const result = {
+        task_id: undefined,
+        task: null,
+        tasks,
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        structuredContent: result,
+    };
+}

package/dist/tools/handlers/wip.js

@@ -1,6 +1,36 @@
 import { strictParse, WipOperationsSchema, } from "../../schema/index.js";
 import { generate_wip, verify_wip, sign_wip, wip2html, } from "@wowok/wowok";
+import { analyzeWipDeployment, formatDeployHints, } from "../wip-deploy-assist.js";
 export async function handleWipOperations(args) {
+    if (typeof args === "object" && args !== null
+        && args.type === "deploy_assist") {
+        const wipPath = args.wipFilePath;
+        if (typeof wipPath !== "string") {
+            return {
+                content: [{
+                        type: "text",
+                        text: "Error: 'wipFilePath' is required for deploy_assist action",
+                    }],
+                structuredContent: {
+                    result: {
+                        type: "error",
+                        error: "'wipFilePath' is required for deploy_assist action",
+                    },
+                },
+            };
+        }
+        const suggestion = analyzeWipDeployment(wipPath);
+        const hints = formatDeployHints(suggestion);
+        return {
+            content: [{ type: "text", text: hints || "No deployment needed." }],
+            structuredContent: {
+                result: {
+                    type: "deploy_assist",
+                    ...suggestion,
+                },
+            },
+        };
+    }
     const validated = strictParse(WipOperationsSchema, args, "wip_file input");
     let structuredContent;
     switch (validated.type) {
@@ -10,8 +40,24 @@ export async function handleWipOperations(args) {
             break;
         }
         case "verify": {
+            const deploySuggestion = analyzeWipDeployment(validated.wipFilePath);
             const result = await verify_wip(validated.wipFilePath, validated.hash_equal, validated.requireSignature);
-            structuredContent = { result: { type: "verify", ...result } };
+            const attachHints = deploySuggestion.needs_deployment
+                || (!result.valid && deploySuggestion.classification.type !== "data_url");
+            if (attachHints) {
+                const hints = formatDeployHints(deploySuggestion);
+                structuredContent = {
+                    result: {
+                        type: "verify",
+                        ...result,
+                        deployment_assistance: deploySuggestion,
+                    },
+                    deployment_hints: hints,
+                };
+            }
+            else {
+                structuredContent = { result: { type: "verify", ...result } };
+            }
             break;
         }
         case "sign": {

package/dist/tools/index.d.ts

@@ -2,6 +2,14 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ToolEntry, ToolDispatchResult, DispatchOptions } from "./types.js";
 export declare const TOOL_REGISTRY: ToolEntry[];
 export declare const TOOL_REGISTRY_MAP: Map<string, ToolEntry>;
+export interface StructuredSchemaError {
+    path: string;
+    code: string;
+    message: string;
+    expected?: string;
+    received_value?: unknown;
+    suggestion: string;
+}
 export declare function dispatchToolCall(name: string, args: unknown, options?: DispatchOptions): Promise<ToolDispatchResult>;
 export interface ToolListEntry {
     name: string;