@wowok/agent-mcp 2.5.1 → 2.5.3

package/dist/tools/handlers/query.js

@@ -1,5 +1,5 @@
 import { strictParse, WatchQueryOperationsSchema, OnchainTableDataSchema, OnchainEventsInputSchema, ProtocolInfoQuerySchema, } from "../../schema/index.js";
-import { query_local_mark_list, query_account_list, query_local_info_list, query_local_token_list, query_account, GetLocalNamesByAddresses, query_personal, query_objects, query_table, query_tableItem, queryTableItem_RepositoryData, queryTableItem_PermissionPerm, queryTableItem_RewardRecord, queryTableItem_DemandPresenter, queryTableItem_TreasuryHistory, queryTableItem_MachineNode, queryTableItem_ProgressHistory, queryTableItem_AddressMark, queryTableItem_EntityRegistrar, queryTableItem_EntityLinker, query_received, queryProtocolInfo, query_events, generateNodeComments, } from "@wowok/wowok";
+import { query_local_mark_list, query_account_list, query_local_info_list, query_local_token_list, query_account, GetLocalNamesByAddresses, query_personal, query_objects, query_table, query_tableItem, queryTableItem_RepositoryData, queryTableItem_PermissionPerm, queryTableItem_RewardRecord, queryTableItem_DemandPresenter, queryTableItem_TreasuryHistory, queryTableItem_MachineNode, queryTableItem_ProgressHistory, queryTableItem_AddressMark, queryTableItem_EntityRegistrar, queryTableItem_EntityLinker, query_received, queryProtocolInfo, query_events, query_transaction, query_object_history, query_address_activity, generateNodeComments, } from "@wowok/wowok";
 import { buildDataSemantic, } from "../../schema/call/semantic.js";
 import { normalizeAccountOrMark } from "./messenger.js";
 export async function handleWatchQueryOperations(args) {
@@ -89,8 +89,44 @@ export async function handleWatchQueryOperations(args) {
             result = { query_type: "onchain_received", result: queryResult };
             break;
         }
+        case "onchain_transaction": {
+            const queryResult = await query_transaction({
+                digest: validated.digest,
+                no_cache: validated.no_cache,
+                network: validated.network,
+            });
+            result = { query_type: "onchain_transaction", result: queryResult };
+            break;
+        }
+        case "onchain_object_history": {
+            const queryResult = await query_object_history({
+                object: validated.object,
+                cursor: validated.cursor,
+                limit: validated.limit,
+                order: validated.order,
+                no_cache: validated.no_cache,
+                network: validated.network,
+            });
+            result = { query_type: "onchain_object_history", result: queryResult };
+            break;
+        }
+        case "onchain_address_activity": {
+            const addrInput = typeof validated.name_or_address === 'string'
+                ? validated.name_or_address
+                : validated.name_or_address.name_or_address;
+            const queryResult = await query_address_activity({
+                name_or_address: addrInput,
+                cursor: validated.cursor,
+                limit: validated.limit,
+                order: validated.order,
+                no_cache: validated.no_cache,
+                network: validated.network,
+            });
+            result = { query_type: "onchain_address_activity", result: queryResult };
+            break;
+        }
         default:
-            throw new Error(`Unknown query type. Valid query_types are: "local_mark_list", "account_list", "local_info_list", "token_list", "account_balance", "local_names", "onchain_personal_profile", "onchain_objects", "onchain_received". For table queries, use the "onchain_table_data" tool.`);
+            throw new Error(`Unknown query type. Valid query_types are: "local_mark_list", "account_list", "local_info_list", "token_list", "account_balance", "local_names", "onchain_personal_profile", "onchain_objects", "onchain_received", "onchain_transaction", "onchain_object_history", "onchain_address_activity". For table queries, use the "onchain_table_data" tool.`);
     }
     return {
         content: [{ type: "text", text: JSON.stringify({ result }) }],

package/dist/tools/index.js

@@ -286,6 +286,10 @@ export const TOOL_REGISTRY = [
                 "    → 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" +
@@ -372,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(", ")}`);
@@ -387,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, {
@@ -498,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.1",
+  "version": "2.5.3",
   "description": "Making It Easy for AI Agents to Communicate, Collaborate, Trade, and Trust.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -50,7 +50,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@wowok/wowok": "2.5.0",
+    "@wowok/wowok": "2.5.2",
     "lodash": "^4.18.1",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.25.2"