@wowok/agent-mcp 2.5.0 → 2.5.2

package/dist/tools/index.js

@@ -259,29 +259,57 @@ export const TOOL_REGISTRY = [
         name: "project_operation",
         handler: handleProjectOperation,
         config: {
-            title: "🗂️ Project - Namespace & Object Graph",
-            description: "Phase 2 project namespace service — manage and query the local object dependency graph (DAG) " +
-                "built on top of local_mark tags. No on-chain writes; all data comes from local marks tagged " +
+            title: "🗂️ Project - 5-Stage Deployment & Object Graph",
+            description: "Project-based deployment service — manage the local object dependency graph (DAG) AND guide users " +
+                "through the 5-stage project deployment workflow. All data comes from local marks tagged " +
                 "`project:<prefix>` (auto-injected by the ProjectService when enabled, default ON).\n\n" +
-                "Actions:\n" +
-                "  • list_projects — List all discovered projects (grouped by `project:<prefix>` tag) with object counts.\n" +
+                "═══════════════════════════════════════════════════════════════\n" +
+                "  PROJECT-BASED DEPLOYMENT — 5-STAGE WORKFLOW (C1-C4)\n" +
+                "═══════════════════════════════════════════════════════════════\n" +
+                "When a user wants to build/deploy a service, follow these 5 stages IN ORDER. " +
+                "Each stage's output tells you the next action to call:\n\n" +
+                "  Stage 1: Project Naming\n" +
+                "    → Use `project` + `version` params to name the project (e.g. myshop_v1).\n" +
+                "  Stage 2: Business Puzzle (action='analyze_intent')\n" +
+                "    → Input: user_intent (natural language), industry hint.\n" +
+                "    → Output: ODG (object dependency graph), puzzles, missing fields, next_step.\n" +
+                "    → Guide user to fill missing fields, then proceed to Stage 3.\n" +
+                "  Stage 3: Risk Calibration (action='aggregate_risks')\n" +
+                "    → Input: puzzles from Stage 2.\n" +
+                "    → Output: risk findings, can_proceed flag.\n" +
+                "    → CRITICAL risks block; HIGH/MEDIUM/LOW only warn. Fix CRITICAL before proceeding.\n" +
+                "  Stage 4: Deployment Doc (action='generate_deployment_doc')\n" +
+                "    → Input: objects, edges, steps (topological plan from Stage 2-3).\n" +
+                "    → Output: markdown deployment doc, D-01..D-18 scanner checks, can_proceed.\n" +
+                "    → 0 D-errors required before Stage 5.\n" +
+                "  Stage 5: Substep Trace (action='trace_substeps')\n" +
+                "    → Input: substeps (from deployment doc), network (testnet/mainnet).\n" +
+                "    → Output: coherence check, D-10 substep linkage, can_proceed.\n" +
+                "    → Execute each substep via onchain_operations, record outcomes.\n\n" +
+                "  Status Query (action='get_project_status')\n" +
+                "    → Input: project, version.\n" +
+                "    → Output: current stage (1-5), stage_name, next_action, can_proceed.\n" +
+                "    → Call anytime to check which stage the project is in and what to do next.\n\n" +
+                "Correct object creation order (topological): Permission → Allocation → Guard → Machine → Service.\n" +
+                "All objects created as draft (publish=false) first; publish Machine before Service (last).\n\n" +
+                "═══════════════════════════════════════════════════════════════\n" +
+                "  GRAPH QUERY ACTIONS (10)\n" +
+                "═══════════════════════════════════════════════════════════════\n" +
+                "  • list_projects — List all discovered projects with object counts.\n" +
                 "  • list_objects — List objects in a project (requires `project` param).\n" +
-                "  • shareable — List objects tagged `shareable:true` (cross-project reusable: common Permission, 3rd-party Arb).\n" +
-                "  • dependencies — Trace forward dependencies of an object (BFS transitive closure + dangling refs).\n" +
+                "  • shareable — List cross-project reusable objects (common Permission, 3rd-party Arb).\n" +
+                "  • dependencies — Trace forward dependencies of an object (BFS + dangling refs).\n" +
                 "  • referenced_by — Reverse query: who references this object?\n" +
-                "  • pre_publish_check — Pre-publish sanity check for a service (dangling deps + cycles).\n" +
-                "  • cross_project_refs — Find edges that cross project boundaries.\n" +
+                "  • pre_publish_check — Pre-publish sanity check (dangling deps + cycles).\n" +
+                "  • cross_project_refs — Find edges crossing project boundaries.\n" +
                 "  • graph_stats — Graph statistics (node/edge counts, cycles, dangling deps).\n" +
-                "  • save_graph — Save the in-memory graph to ~/.wowok/project-graph.json (persist across sessions).\n" +
-                "  • load_graph — Load the graph from file (restore after restart).\n\n" +
-                "NOTE: The graph is in-memory by default. Use save_graph/load_graph for cross-session persistence " +
-                "(or toggle graph_persist via config_operation for auto-save). " +
-                "list_projects/shareable always query local_mark (persistent).\n\n" +
-                "💡 Schema hint: Use schema_query with action='get' and name='project_operation' to retrieve the exact parameter schema with all actions and field definitions.",
+                "  • save_graph — Save graph to ~/.wowok/project-graph.json.\n" +
+                "  • load_graph — Load graph from file (restore after restart).\n\n" +
+                "💡 Schema hint: Use schema_query with action='get' and name='project_operation' for exact field definitions.",
             inputSchema: ProjectOperationInputSchema,
             outputSchema: ProjectOperationOutputSchema,
-            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-            _meta: createToolMeta("project", ["project", "namespace", "graph", "dag", "dependency", "reference", "organization"]),
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+            _meta: createToolMeta("project", ["project", "namespace", "graph", "dag", "dependency", "reference", "organization", "deployment", "5-stage", "analyze_intent", "aggregate_risks", "deployment_doc", "trace_substeps", "puzzle", "risk", "odg"]),
         },
     },
     {
@@ -348,7 +376,123 @@ export const TOOL_REGISTRY = [
     },
 ];
 export const TOOL_REGISTRY_MAP = new Map(TOOL_REGISTRY.map(t => [t.name, t]));
+const SUB_TOOL_NAMES = TOOL_REGISTRY.map(t => t.name);
+const WowokToolRuntimeSchema = z.unknown().describe("WoWok unified tool input. Expected: { tool: \"<sub-tool>\", data: {<params>} }. " +
+    "Aliases accepted: tool_name→tool, args→data, name→tool, params→data. " +
+    "If parameters don't match the sub-tool's schema, the response includes the correct schema for self-correction.");
+const WowokToolDisplaySchema = z.object({
+    tool: z.enum(SUB_TOOL_NAMES).optional().describe("The sub-tool to execute. Each sub-tool has its own parameter schema."),
+    data: z.record(z.unknown()).optional().describe("Sub-tool specific parameters. If validation fails, the response includes the correct schema for this sub-tool — read it, fix your params, and retry."),
+    tool_name: z.enum(SUB_TOOL_NAMES).optional().describe("DEPRECATED alias for 'tool'. Use 'tool' instead."),
+    args: z.record(z.unknown()).optional().describe("DEPRECATED alias for 'data'. Use 'data' instead."),
+    name: z.enum(SUB_TOOL_NAMES).optional().describe("DEPRECATED alias for 'tool'. Use 'tool' instead."),
+    params: z.record(z.unknown()).optional().describe("DEPRECATED alias for 'data'. Use 'data' instead."),
+}).describe("WoWok unified tool input. Call with { tool: \"<sub-tool>\", data: {<params>} }. " +
+    "Aliases: tool_name/name→tool, args/params→data.");
+const WOWOK_TOOL_DESCRIPTION = [
+    "WoWok MCP unified interface. Call with { tool: \"<sub-tool>\", data: {<params>} }.",
+    "",
+    "  tool: name of the sub-tool (string)",
+    "  data: sub-tool parameters (object)",
+    "",
+    "  Aliases accepted (deprecated): tool_name/name for tool, args/params for data.",
+    "  Inline params also accepted: { tool: \"<sub-tool>\", <param1>: ..., <param2>: ... }",
+    "",
+    "  EXAMPLE: wowok({ tool: \"schema_query\", data: { action: \"get\", name: \"onchain_operations\" } })",
+    "  EXAMPLE: wowok({ tool: \"wowok_buildin_info\", data: { info: \"mainnet bridge tokens\" } })",
+    "  EXAMPLE (inline params): wowok({ tool: \"schema_query\", action: \"get\", name: \"onchain_operations\" })",
+    "",
+    "Available sub-tools:",
+    "  onchain_operations — On-chain ops: service, machine, progress, repository, arbitration, etc.",
+    "  account_operation — LOCAL wallet management (generate, suspend, faucet, sign).",
+    "  local_mark_operation — LOCAL address book (name/tag for addresses and object IDs).",
+    "  local_info_operation — LOCAL private data (delivery addresses, phone numbers).",
+    "  wip_file — Work-in-progress file management.",
+    "  messenger_operation — End-to-end encrypted messaging.",
+    "  guard2file — Export guard rules to file.",
+    "  machineNode2file — Export machine nodes to file.",
+    "  query_toolkit — Query on-chain objects by ID/type/owner.",
+    "  onchain_table_data — Query on-chain dynamic field tables with pagination.",
+    "  onchain_events — Watch on-chain events (arbitration, order, progress, demand).",
+    "  wowok_buildin_info — Protocol constants, built-in permissions, bridge tokens.",
+    "  schema_query — Query JSON schemas for any sub-tool (action: list/get/get_output/search).",
+    "  bridge_operation — Cross-chain bridge between WOW and EVM (mainnet only).",
+    "  project_operation — 5-stage project deployment workflow (C1-C4 + graph queries).",
+    "  config_operation — Runtime service toggles (confirm_gate, harness, etc.).",
+    "  trust_score — Service trust/risk assessment (0-100 score, 5 dimensions).",
+    "",
+    "SCHEMA-GATED EXECUTION:",
+    "  If your parameters don't match the sub-tool's schema, the response will include:",
+    "    result.status = \"schema_mismatch\"",
+    "    result.errors = specific validation errors (field path + expected type)",
+    "    result.hint = instructions to fix and retry",
+    "    schema.input = the correct JSON schema for the sub-tool",
+    "    schema.tool = which sub-tool this schema belongs to",
+    "  Read the schema, fix your params, and retry. This is normal — no need to call schema_query separately.",
+    "",
+    "SCHEMA CACHING:",
+    "  Each sub-tool has a DIFFERENT schema. When you receive a schema in a mismatch response:",
+    "    1. Read the schema carefully",
+    "    2. Fix your parameters",
+    "    3. Retry the call",
+    "    4. CACHE the schema in your context for future calls to the SAME sub-tool",
+    "  You should only need to see each sub-tool's schema once per conversation.",
+    "",
+    "PROJECT-BASED DEPLOYMENT (5 stages):",
+    "  Stage 1: Project naming (provide project + version params)",
+    "  Stage 2: project_operation action='analyze_intent' → ODG + puzzles",
+    "  Stage 3: project_operation action='aggregate_risks' → risk findings",
+    "  Stage 4: project_operation action='generate_deployment_doc' → deployment doc",
+    "  Stage 5: project_operation action='trace_substeps' → substep verification",
+    "  Status: project_operation action='get_project_status' → current stage + next action",
+    "",
+    "Correct object creation order: Permission → Allocation → Guard → Machine → Service.",
+    "All objects created as draft (publish=false) first; publish Machine before Service (last).",
+].join("\n");
+function formatZodErrors(error) {
+    return error.issues.map(issue => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+        return `${path}: ${issue.message}`;
+    });
+}
+function checkUnknownFields(schema, input) {
+    let innerSchema = schema;
+    while (true) {
+        const def = innerSchema._def;
+        if (!def || def.typeName !== "ZodEffects")
+            break;
+        innerSchema = def.schema ?? innerSchema;
+    }
+    const def = innerSchema._def;
+    const shape = def?.shape?.();
+    if (!shape || typeof input !== "object" || input === null)
+        return [];
+    const allowedFields = Object.keys(shape);
+    const inputFields = Object.keys(input);
+    return inputFields.filter(f => !allowedFields.includes(f));
+}
+function extractRelevantSchema(fullSchema, toolName, data) {
+    if (toolName === "onchain_operations" && typeof data === "object" && data !== null) {
+        const opType = data.operation_type;
+        if (typeof opType === "string") {
+            const subSchemaName = `onchain_operations_${opType}`;
+            const subSchema = loadPreGeneratedSchema(subSchemaName);
+            if (subSchema)
+                return subSchema;
+        }
+    }
+    return fullSchema;
+}
+function isSchemaValidationError(message) {
+    return (message.startsWith("Unknown ") && message.includes("field") ||
+        message.includes("expected") && message.includes("received") ||
+        message.includes("Invalid input") ||
+        message.includes("Required"));
+}
 export async function dispatchToolCall(name, args, options) {
+    if (name === "wowok") {
+        return handleWowok(args);
+    }
     const entry = TOOL_REGISTRY_MAP.get(name);
     if (!entry) {
         throw new Error(`Unknown tool: ${name}. Available: ${TOOL_REGISTRY.map(t => t.name).join(", ")}`);
@@ -363,6 +507,206 @@ export async function dispatchToolCall(name, args, options) {
     const wrapped = wrapHandlerWithErrorShape(harnessWrapped, timeoutMs, name, entry.errorShapeBuilder);
     return wrapped(args);
 }
+const TOOL_FIELD_ALIASES = ["tool", "tool_name", "name"];
+const DATA_FIELD_ALIASES = ["data", "args", "params", "parameters"];
+const RESERVED_FIELD_NAMES = new Set([
+    ...TOOL_FIELD_ALIASES,
+    ...DATA_FIELD_ALIASES,
+]);
+function normalizeInput(args) {
+    const notes = [];
+    if (!args || typeof args !== "object" || Array.isArray(args)) {
+        return { tool: undefined, data: {}, normalizationNotes: ["input is not an object"] };
+    }
+    const obj = args;
+    let tool;
+    for (const alias of TOOL_FIELD_ALIASES) {
+        if (typeof obj[alias] === "string" && obj[alias]) {
+            tool = obj[alias];
+            if (alias !== "tool") {
+                notes.push(`normalized '${alias}' → 'tool'`);
+            }
+            break;
+        }
+    }
+    let data;
+    for (const alias of DATA_FIELD_ALIASES) {
+        const v = obj[alias];
+        if (v !== undefined && v !== null && typeof v === "object" && !Array.isArray(v)) {
+            data = v;
+            if (alias !== "data") {
+                notes.push(`normalized '${alias}' → 'data'`);
+            }
+            break;
+        }
+    }
+    if (!data) {
+        const inlineParams = {};
+        let hasInline = false;
+        for (const key of Object.keys(obj)) {
+            if (!RESERVED_FIELD_NAMES.has(key)) {
+                inlineParams[key] = obj[key];
+                hasInline = true;
+            }
+        }
+        if (hasInline) {
+            data = inlineParams;
+            notes.push("extracted inline params → 'data' (no data wrapper was provided)");
+        }
+        else {
+            data = {};
+        }
+    }
+    return { tool, data, normalizationNotes: notes };
+}
+async function handleWowok(args) {
+    const { tool: normalizedToolName, data: normalizedData, normalizationNotes } = normalizeInput(args);
+    if (!normalizedToolName) {
+        const receivedKeys = (args && typeof args === "object" && !Array.isArray(args))
+            ? Object.keys(args).join(", ") || "(none)"
+            : `(non-object input: ${typeof args})`;
+        const errors = [
+            `Missing 'tool' field. Received keys: ${receivedKeys}`,
+            `Expected one of: ${SUB_TOOL_NAMES.join(", ")}`,
+        ];
+        return {
+            content: [{
+                    type: "text",
+                    text: `Missing 'tool' field. Call format: wowok({ tool: "<sub-tool>", data: {<params>} }). Received keys: ${receivedKeys}. Available sub-tools: ${SUB_TOOL_NAMES.join(", ")}`,
+                }],
+            structuredContent: {
+                result: {
+                    status: "schema_mismatch",
+                    errors,
+                    hint: `Provide 'tool' (one of: ${SUB_TOOL_NAMES.join(", ")}) and 'data' (sub-tool parameters). Aliases accepted: tool_name/name→tool, args/params→data.`,
+                    received: args,
+                },
+                schema: {
+                    input: zodToJsonSchemaSafe(WowokToolDisplaySchema, "wowok"),
+                    tool: "wowok",
+                },
+            },
+        };
+    }
+    const entry = TOOL_REGISTRY_MAP.get(normalizedToolName);
+    if (!entry) {
+        const suggestions = TOOL_REGISTRY
+            .map(t => t.name)
+            .filter(name => name.includes(normalizedToolName) || normalizedToolName.includes(name))
+            .slice(0, 5);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Unknown sub-tool: '${normalizedToolName}'. Available: ${TOOL_REGISTRY.map(t => t.name).join(", ")}${suggestions.length > 0 ? `. Did you mean: ${suggestions.join(", ")}?` : ""}`,
+                }],
+            structuredContent: {
+                result: {
+                    status: "error",
+                    errors: [`Unknown sub-tool: ${normalizedToolName}`],
+                    hint: `Available sub-tools: ${TOOL_REGISTRY.map(t => t.name).join(", ")}${suggestions.length > 0 ? `. Did you mean: ${suggestions.join(", ")}?` : ""}`,
+                    suggestions,
+                },
+                schema: null,
+            },
+        };
+    }
+    if (normalizationNotes.length > 0) {
+        console.warn(`[wowok] input normalization for '${normalizedToolName}': ${normalizationNotes.join("; ")}`);
+    }
+    const validationResult = entry.config.inputSchema.safeParse(normalizedData);
+    const unknownFields = checkUnknownFields(entry.config.inputSchema, normalizedData);
+    if (!validationResult.success || unknownFields.length > 0) {
+        const allErrors = [];
+        if (!validationResult.success) {
+            allErrors.push(...formatZodErrors(validationResult.error));
+        }
+        if (unknownFields.length > 0) {
+            allErrors.push(`Unknown field(s): ${unknownFields.join(", ")}`);
+        }
+        const fullSchema = loadPreGeneratedSchema(normalizedToolName) ?? zodToJsonSchemaSafe(entry.config.inputSchema, normalizedToolName);
+        const relevantSchema = extractRelevantSchema(fullSchema, normalizedToolName, normalizedData);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Schema mismatch for ${normalizedToolName}. ${allErrors.length} error(s). Read the schema below, fix your params, and retry.`,
+                }],
+            structuredContent: {
+                result: {
+                    status: "schema_mismatch",
+                    errors: allErrors,
+                    hint: `Fix your parameters based on the schema below and retry. CACHE THIS SCHEMA for future ${normalizedToolName} calls — you don't need to query it again.`,
+                },
+                schema: {
+                    input: relevantSchema,
+                    tool: normalizedToolName,
+                },
+            },
+        };
+    }
+    try {
+        const subResult = await dispatchToolCall(normalizedToolName, normalizedData);
+        const sc = subResult.structuredContent;
+        const resultField = sc?.result;
+        const isErrorResponse = resultField?.status === "error" || resultField?.operation === "error";
+        if (isErrorResponse) {
+            return {
+                content: subResult.content,
+                structuredContent: {
+                    result: {
+                        status: "error",
+                        data: subResult.structuredContent,
+                        errors: [subResult.content[0]?.text ?? "Sub-tool returned an error"],
+                    },
+                    schema: null,
+                },
+            };
+        }
+        return {
+            content: subResult.content,
+            structuredContent: {
+                result: {
+                    status: "success",
+                    data: subResult.structuredContent,
+                },
+                schema: null,
+            },
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (isSchemaValidationError(errorMessage)) {
+            const fullSchema = loadPreGeneratedSchema(normalizedToolName) ?? zodToJsonSchemaSafe(entry.config.inputSchema, normalizedToolName);
+            const relevantSchema = extractRelevantSchema(fullSchema, normalizedToolName, normalizedData);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Schema mismatch for ${normalizedToolName}: ${errorMessage}`,
+                    }],
+                structuredContent: {
+                    result: {
+                        status: "schema_mismatch",
+                        errors: [errorMessage],
+                        hint: `Fix your parameters based on the schema below and retry. CACHE THIS SCHEMA for future ${normalizedToolName} calls.`,
+                    },
+                    schema: {
+                        input: relevantSchema,
+                        tool: normalizedToolName,
+                    },
+                },
+            };
+        }
+        return {
+            content: [{ type: "text", text: `Error: ${errorMessage}` }],
+            structuredContent: {
+                result: {
+                    status: "error",
+                    errors: [errorMessage],
+                },
+                schema: null,
+            },
+        };
+    }
+}
 function zodToJsonSchemaSafe(schema, name) {
     try {
         const jsonSchema = zodToJsonSchema(schema, {
@@ -474,49 +818,38 @@ function loadPreGeneratedOutputSchema(toolName) {
     return null;
 }
 export function listTools() {
-    return TOOL_REGISTRY.map(entry => {
-        const preGenerated = loadPreGeneratedSchema(entry.name);
-        const inputSchema = preGenerated ?? zodToJsonSchemaSafe(entry.config.inputSchema, entry.name);
-        return {
-            name: entry.name,
-            title: entry.config.title,
-            description: entry.config.description,
-            inputSchema,
-        };
-    });
+    return [{
+            name: "wowok",
+            title: "WoWok MCP",
+            description: WOWOK_TOOL_DESCRIPTION,
+            inputSchema: zodToJsonSchemaSafe(WowokToolDisplaySchema, "wowok"),
+        }];
 }
 export function registerAllTools(server) {
-    for (const entry of TOOL_REGISTRY) {
-        const timeoutMs = entry.timeoutMs ?? 60000;
-        const handlerWithRules = async (args) => {
-            return dispatchToolCall(entry.name, args);
-        };
-        const wrapped = wrapHandlerWithErrorShape(handlerWithRules, timeoutMs, entry.name, entry.errorShapeBuilder);
-        server.registerTool(entry.name, entry.config, withTelemetry(entry.name, wrapped));
-    }
+    const timeoutMs = 120000;
+    const wrapped = wrapHandlerWithErrorShape(handleWowok, timeoutMs, "wowok", undefined);
+    server.registerTool("wowok", {
+        title: "WoWok MCP",
+        description: WOWOK_TOOL_DESCRIPTION,
+        inputSchema: WowokToolRuntimeSchema,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, withTelemetry("wowok", wrapped));
     overrideToolsListHandler(server);
 }
 function overrideToolsListHandler(server) {
     server.server.setRequestHandler(ListToolsRequestSchema, () => ({
-        tools: TOOL_REGISTRY.map(entry => {
-            const rawSchema = loadPreGeneratedSchema(entry.name) ??
-                zodToJsonSchemaSafe(entry.config.inputSchema, entry.name);
-            const inputSchema = ensureObjectType(rawSchema);
-            const toolDef = {
-                name: entry.name,
-                title: entry.config.title,
-                description: entry.config.description,
-                inputSchema,
-                annotations: entry.config.annotations,
-                _meta: entry.config._meta,
-            };
-            if (entry.config.outputSchema) {
-                const outputSchema = loadPreGeneratedOutputSchema(entry.name) ??
-                    zodToJsonSchemaSafe(entry.config.outputSchema, `${entry.name}_output`);
-                toolDef.outputSchema = outputSchema;
-            }
-            return toolDef;
-        }),
+        tools: [{
+                name: "wowok",
+                title: "WoWok MCP",
+                description: WOWOK_TOOL_DESCRIPTION,
+                inputSchema: ensureObjectType(zodToJsonSchemaSafe(WowokToolDisplaySchema, "wowok")),
+                annotations: {
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
+            }],
     }));
 }
 function ensureObjectType(schema) {

package/dist/tools/wrap.js

@@ -4,6 +4,7 @@ import { shouldRunLightHooks, shouldRunHeavyHooks, recordOperationFailure, } fro
 import { getHarness } from "../harness/index.js";
 import { recordOperationOutcome } from "../experience/index.js";
 import { recordIndustrySignal } from "../knowledge/flywheel-loop.js";
+import { getStageCache } from "../project/index.js";
 export function withTimeout(promise, timeoutMs = 30000, operationName = "operation") {
     let timer;
     return Promise.race([
@@ -57,6 +58,34 @@ export const operationErrorShape = (error, classified, ctx) => ({
 export const strictStatusErrorShape = (error, _classified, _ctx) => ({
     result: { status: "error", error },
 });
+function checkProjectStage(action, project, version) {
+    const entry = getStageCache(project, version);
+    if (!entry) {
+        if (action === "analyze_intent" || action === "get_project_status") {
+            return null;
+        }
+        return `project_stage: calling '${action}' before 'analyze_intent' — recommend calling analyze_intent first for project '${project}:${version}'`;
+    }
+    const stageOrder = {
+        analyze_intent: 2,
+        aggregate_risks: 3,
+        generate_deployment_doc: 4,
+        trace_substeps: 5,
+    };
+    const requiredStage = stageOrder[action];
+    if (!requiredStage)
+        return null;
+    if (entry.stage < requiredStage - 1) {
+        return `project_stage: calling '${action}' (stage ${requiredStage}) but project is at stage ${entry.stage} — recommend completing prior stages first for '${project}:${version}'`;
+    }
+    if (action === "generate_deployment_doc" && entry.risk_can_proceed === false) {
+        return `project_stage: calling 'generate_deployment_doc' but CRITICAL risks are unresolved — recommend fixing risks first for '${project}:${version}'`;
+    }
+    if (action === "trace_substeps" && entry.doc_error_count && entry.doc_error_count > 0) {
+        return `project_stage: calling 'trace_substeps' but deployment doc has ${entry.doc_error_count} D-error(s) — recommend fixing doc errors first for '${project}:${version}'`;
+    }
+    return null;
+}
 export function dispatchWithHarness(handler, toolName) {
     return async (args) => {
         const harnessWarnings = [];
@@ -78,6 +107,22 @@ export function dispatchWithHarness(handler, toolName) {
                 harnessWarnings.push(`pre_call hook failed: ${e instanceof Error ? e.message : String(e)}`);
             }
         }
+        if (toolName === "project_operation" && runLight) {
+            try {
+                const projArgs = args;
+                const action = projArgs?.action;
+                const project = projArgs?.project;
+                const version = projArgs?.version;
+                if (action && project && version) {
+                    const stageCheck = checkProjectStage(action, project, version);
+                    if (stageCheck) {
+                        harnessWarnings.push(stageCheck);
+                    }
+                }
+            }
+            catch {
+            }
+        }
         if (isPublishOp) {
             try {
                 harnessWarnings.push("pre_publish: full-tier check engaged");
@@ -141,15 +186,24 @@ export function dispatchWithHarness(handler, toolName) {
                 harnessWarnings.push(`signal collection failed: ${e instanceof Error ? e.message : String(e)}`);
             }
         }
-        if (harnessWarnings.length > 0 && result?.structuredContent) {
-            const sc = result.structuredContent;
-            const semantic = sc.semantic;
-            if (semantic) {
-                const existing = Array.isArray(semantic.harness_warnings) ? semantic.harness_warnings : [];
-                semantic.harness_warnings = [...existing, ...harnessWarnings];
+        if (harnessWarnings.length > 0) {
+            if (result?.structuredContent) {
+                const sc = result.structuredContent;
+                const semantic = sc.semantic;
+                if (semantic) {
+                    const existing = Array.isArray(semantic.warnings) ? semantic.warnings : [];
+                    semantic.warnings = [...existing, ...harnessWarnings];
+                }
+                else {
+                    for (const w of harnessWarnings) {
+                        console.warn(`[harness] ${w}`);
+                    }
+                }
             }
             else {
-                sc.harness_warnings = harnessWarnings;
+                for (const w of harnessWarnings) {
+                    console.warn(`[harness] ${w}`);
+                }
             }
         }
         return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/agent-mcp",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "Making It Easy for AI Agents to Communicate, Collaborate, Trade, and Trust.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",