@wowok/agent-mcp 2.6.0 → 2.6.1

package/dist/tools/index.js

@@ -24,6 +24,7 @@ import { handleBridgeOperations } from "./handlers/bridge.js";
 import { handleProjectOperation } from "./handlers/project.js";
 import { handleConfigOperation } from "./handlers/config.js";
 import { handleTrustScore } from "./handlers/trust.js";
+import { handleQueryTaskStatus, QueryTaskStatusInputSchema, QueryTaskStatusOutputSchema } from "./handlers/task-status.js";
 import { applyOnchainRules } from "./rules-hook.js";
 import { createToolMeta, OnchainOperationsSchema, AccountOperationSchema, LocalMarkOperationSchema, LocalInfoOperationSchema, WipOperationsSchema, MessengerOperationInputSchema, Guard2File_InputSchema, MachineNode2File_InputSchema, WatchQueryOperationsSchema, WatchQueryOperationsResultSchema, OnchainTableDataSchema, OnchainEventsInputSchema, ProtocolInfoQuerySchema, SchemaQueryInputSchema, BridgeOperationsSchema, ProjectOperationInputSchema, ConfigOperationInputSchema, TrustScoreInputSchema, CallOutputSchema, AccountOperationOutputWrappedSchema, LocalMarkOperationOutputWrappedSchema, LocalInfoOperationOutputWrappedSchema, WipOperationOutputSchema, MessengerOperationOutputSchema, Guard2File_OutputWrappedSchema, MachineNode2File_OutputWrappedSchema, OnchainTableDataResultSchema, OnchainEventsResultSchema, ProtocolInfoResultSchema, SchemaQueryOutputSchema, BridgeCallOutputSchema, ProjectOperationOutputSchema, ConfigOperationOutputSchema, TrustScoreOutputSchema, } from "../schema/index.js";
 export const TOOL_REGISTRY = [
@@ -84,7 +85,7 @@ export const TOOL_REGISTRY = [
         handler: handleWipOperations,
         config: {
             title: "🤝 Witness Immutable Promise File Operations",
-            description: "generate (create WIP files from markdown and images), verify (integrity check), sign (add signatures), or wip2html (convert to HTML).\n\n💡 Schema hint: Use schema_query with action='get' and name='wip_file' to retrieve the exact parameter schema before calling.",
+            description: "generate (create WIP files from markdown and images), verify (integrity check), sign (add signatures), or wip2html (convert to HTML).\n\n⚠️ IMPORTANT — On-chain WIP URL requirement: When using a WIP file URL in `service.sales[].wip` (stored on-chain), the URL MUST be publicly reachable. Local file paths (e.g., 'C:\\\\path\\\\file.wip' or '/home/user/file.wip') are NOT acceptable on-chain — they only work locally and will fail verification for buyers.\n\nDeployment options for the .wip file:\n  • GitHub Pages: https://raw.githubusercontent.com/<user>/<repo>/<branch>/<file>.wip\n  • IPFS: https://ipfs.io/ipfs/<CID> or https://cloudflare-ipfs.com/ipfs/<CID> (upload via pinata.cloud)\n  • User's own static website URL\n\nUse type='generate' to create the WIP file first, upload it to any of the above, then use the resulting URL in service.sales[].wip.\n\n💡 Schema hint: Use schema_query with action='get' and name='wip_file' to retrieve the exact parameter schema before calling.",
             inputSchema: WipOperationsSchema,
             outputSchema: z.object({
                 result: WipOperationOutputSchema,
@@ -360,6 +361,28 @@ export const TOOL_REGISTRY = [
             _meta: createToolMeta("trust", ["trust", "score", "risk", "service", "merchant", "reputation", "safety", "evaluate"]),
         },
     },
+    {
+        name: "query_task_status",
+        handler: handleQueryTaskStatus,
+        config: {
+            title: "📊 Task Status - Async Operation Tracking",
+            description: "Query the status of a long-running async task (created by build_graph or evaluate_project " +
+                "with async_mode=true). Returns progress percentage, current status, and the final result " +
+                "when completed.\n\n" +
+                "Tasks are ephemeral (retained 5 minutes after completion, in-memory only).\n\n" +
+                "Usage:\n" +
+                "  • Pass task_id to query a single task's status.\n" +
+                "  • Omit task_id to list all recent tasks (max 50, most recent first).\n" +
+                "  • Pass project_id (with task_id omitted) to filter by project.\n\n" +
+                "This tool is read-only and always safe to call. Use it to check if a long-running " +
+                "operation (e.g. build_graph with enablePotential=true) has completed.\n\n" +
+                "💡 Schema hint: Use schema_query with action='get' and name='query_task_status' to retrieve the exact parameter schema.",
+            inputSchema: QueryTaskStatusInputSchema,
+            outputSchema: QueryTaskStatusOutputSchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            _meta: createToolMeta("task", ["task", "status", "async", "progress", "background", "tracker"]),
+        },
+    },
 ];
 export const TOOL_REGISTRY_MAP = new Map(TOOL_REGISTRY.map(t => [t.name, t]));
 const SUB_TOOL_NAMES = TOOL_REGISTRY.map(t => t.name);
@@ -478,12 +501,71 @@ const WOWOK_TOOL_DESCRIPTION = [
     "  general → fallback for unclear industry",
     "═══════════════════════════════════════════════════════════════",
 ].join("\n");
-function formatZodErrors(error) {
+function formatZodErrors(error, input) {
     return error.issues.map(issue => {
-        const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-        return `${path}: ${issue.message}`;
+        const path = issue.path.length > 0
+            ? issue.path.map(p => typeof p === "number" ? `[${p}]` : p).join(".").replace(".[", "[")
+            : "(root)";
+        const code = issue.code;
+        const message = issue.message;
+        let extras = "";
+        const issueAny = issue;
+        if (code === "invalid_type") {
+            const expected = issueAny.expected;
+            const received = issueAny.received;
+            if (typeof expected === "string" && typeof received === "string") {
+                extras = ` (expected: ${expected}; received: ${received})`;
+            }
+        }
+        else if (code === "invalid_literal" || code === "invalid_enum_value") {
+            const expected = issueAny.expected;
+            if (expected !== undefined) {
+                const expStr = typeof expected === "string" ? expected : JSON.stringify(expected);
+                extras = ` (expected: ${expStr.slice(0, 60)})`;
+            }
+        }
+        else if (code === "too_big" || code === "too_small") {
+            const maximum = issueAny.maximum ?? issueAny.minimum;
+            const origin = issueAny.origin;
+            if (maximum !== undefined && origin !== undefined) {
+                extras = ` (${origin}: ${maximum})`;
+            }
+        }
+        const receivedVal = extractValueAtPath(input, issue.path);
+        if (receivedVal !== undefined) {
+            const valStr = typeof receivedVal === "string"
+                ? `"${receivedVal.slice(0, 60)}"`
+                : typeof receivedVal === "object"
+                    ? JSON.stringify(receivedVal).slice(0, 60)
+                    : String(receivedVal);
+            if (!extras.includes("received:")) {
+                extras += ` (received value: ${valStr})`;
+            }
+        }
+        return `${path} [${code}]: ${message}${extras}`;
     });
 }
+function extractValueAtPath(input, path) {
+    if (input === undefined || input === null || path.length === 0) {
+        return undefined;
+    }
+    let current = input;
+    for (const key of path) {
+        if (current === undefined || current === null)
+            return undefined;
+        if (typeof key === "number") {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[key];
+        }
+        else {
+            if (typeof current !== "object")
+                return undefined;
+            current = current[key];
+        }
+    }
+    return current;
+}
 function checkUnknownFields(schema, input) {
     let innerSchema = schema;
     while (true) {
@@ -518,6 +600,109 @@ function isSchemaValidationError(message) {
         message.includes("Invalid input") ||
         message.includes("Required"));
 }
+function buildSchemaPreview(schema, toolName, data) {
+    try {
+        const lines = [`Schema preview for ${toolName}:`];
+        let topProps;
+        let topRequired = [];
+        let topDescription = "";
+        if (schema.properties && typeof schema.properties === "object") {
+            topProps = schema.properties;
+            topRequired = Array.isArray(schema.required) ? schema.required : [];
+            topDescription = typeof schema.description === "string" ? schema.description : "";
+        }
+        else if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf)) {
+            const variants = (schema.oneOf ?? schema.anyOf);
+            for (const v of variants) {
+                if (v && typeof v === "object") {
+                    const vo = v;
+                    if (vo.properties && typeof vo.properties === "object") {
+                        topProps = vo.properties;
+                        topRequired = Array.isArray(vo.required) ? vo.required : [];
+                        topDescription = typeof vo.description === "string" ? vo.description : "";
+                        break;
+                    }
+                }
+            }
+            if (!topProps) {
+                lines.push(`  (discriminated union with ${variants.length} variants — see structuredContent for full schema)`);
+                return lines.join("\n");
+            }
+        }
+        if (topDescription && topDescription.length > 0 && topDescription.length < 200) {
+            lines.push(`  ${topDescription}`);
+        }
+        if (!topProps) {
+            lines.push("  (no properties available — see structuredContent for full schema)");
+            return lines.join("\n");
+        }
+        const requiredSet = new Set(topRequired);
+        const requiredList = topRequired.length > 0 ? topRequired.join(", ") : "(none)";
+        const optionalList = Object.keys(topProps).filter(k => !requiredSet.has(k)).join(", ");
+        lines.push(`Required: ${requiredList}`);
+        if (optionalList) {
+            lines.push(`Optional: ${optionalList}`);
+        }
+        lines.push("Fields:");
+        for (const [fieldName, fieldSchema] of Object.entries(topProps)) {
+            if (fieldSchema && typeof fieldSchema === "object") {
+                const f = fieldSchema;
+                const type = describeSchemaType(f);
+                const required = requiredSet.has(fieldName) ? "required" : "optional";
+                let desc = typeof f.description === "string" ? f.description : "";
+                if (desc.length > 120)
+                    desc = desc.slice(0, 117) + "...";
+                let subFields = "";
+                if (f.properties && typeof f.properties === "object") {
+                    const subProps = Object.keys(f.properties);
+                    if (subProps.length > 0) {
+                        subFields = ` { ${subProps.slice(0, 8).join(", ")}${subProps.length > 8 ? ", ..." : ""} }`;
+                    }
+                }
+                if (f.items && typeof f.items === "object") {
+                    const items = f.items;
+                    const itemType = describeSchemaType(items);
+                    subFields = ` (array of ${itemType})`;
+                }
+                if (Array.isArray(f.enum)) {
+                    subFields = ` (enum: ${f.enum.slice(0, 6).map(v => JSON.stringify(v)).join(", ")}${f.enum.length > 6 ? ", ..." : ""})`;
+                }
+                lines.push(`  - ${fieldName} (${type}, ${required})${subFields}${desc ? ` — ${desc}` : ""}`);
+            }
+        }
+        if (toolName === "onchain_operations" && typeof data === "object" && data !== null) {
+            const opType = data.operation_type;
+            if (typeof opType === "string") {
+                lines.push(``);
+                lines.push(`operation_type-specific schema: onchain_operations_${opType}`);
+                lines.push(`(Use schema_query with action='get' and name='onchain_operations_${opType}' for the full sub-schema.)`);
+            }
+        }
+        return lines.join("\n");
+    }
+    catch {
+        return `Schema preview for ${toolName}: (unable to build preview — see structuredContent for full schema)`;
+    }
+}
+function describeSchemaType(schema) {
+    if (typeof schema.type === "string")
+        return schema.type;
+    if (Array.isArray(schema.type))
+        return schema.type.join("|");
+    if (schema.$ref)
+        return "$ref";
+    if (Array.isArray(schema.oneOf))
+        return "oneOf";
+    if (Array.isArray(schema.anyOf))
+        return "anyOf";
+    if (Array.isArray(schema.allOf))
+        return "allOf";
+    if (schema.enum)
+        return "enum";
+    if (schema.const)
+        return `const(${JSON.stringify(schema.const)})`;
+    return "object";
+}
 export async function dispatchToolCall(name, args, options) {
     if (name === "wowok") {
         return handleWowok(args);
@@ -647,17 +832,28 @@ async function handleWowok(args) {
     if (!validationResult.success || unknownFields.length > 0) {
         const allErrors = [];
         if (!validationResult.success) {
-            allErrors.push(...formatZodErrors(validationResult.error));
+            allErrors.push(...formatZodErrors(validationResult.error, normalizedData));
         }
         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);
+        const errorPreview = allErrors.slice(0, 5).map((e, i) => `  ${i + 1}. ${e}`).join("\n");
+        const schemaPreview = buildSchemaPreview(relevantSchema, normalizedToolName, normalizedData);
+        const textContent = [
+            `Schema mismatch for ${normalizedToolName}. ${allErrors.length} error(s):`,
+            errorPreview,
+            "",
+            schemaPreview,
+            "",
+            "Fix the parameters based on the errors above and the schema summary, then retry.",
+            `Full JSON Schema is in the structuredContent.schema.input field (cache it for future ${normalizedToolName} calls).`,
+        ].filter(Boolean).join("\n");
         return {
             content: [{
                     type: "text",
-                    text: `Schema mismatch for ${normalizedToolName}. ${allErrors.length} error(s). Read the schema below, fix your params, and retry.`,
+                    text: textContent,
                 }],
             structuredContent: {
                 result: {
@@ -706,10 +902,18 @@ async function handleWowok(args) {
         if (isSchemaValidationError(errorMessage)) {
             const fullSchema = loadPreGeneratedSchema(normalizedToolName) ?? zodToJsonSchemaSafe(entry.config.inputSchema, normalizedToolName);
             const relevantSchema = extractRelevantSchema(fullSchema, normalizedToolName, normalizedData);
+            const schemaPreview = buildSchemaPreview(relevantSchema, normalizedToolName, normalizedData);
+            const textContent = [
+                `Schema mismatch for ${normalizedToolName}: ${errorMessage}`,
+                "",
+                schemaPreview,
+                "",
+                "Fix the parameters and retry. Full JSON Schema is in structuredContent.schema.input.",
+            ].join("\n");
             return {
                 content: [{
                         type: "text",
-                        text: `Schema mismatch for ${normalizedToolName}: ${errorMessage}`,
+                        text: textContent,
                     }],
                 structuredContent: {
                     result: {

package/dist/tools/retry.d.ts

@@ -0,0 +1,8 @@
+export interface RetryConfig {
+    maxRetries: number;
+    intervalMs: number;
+}
+export declare const DEFAULT_FAUCET_RETRY_CONFIG: RetryConfig;
+export declare function loadFaucetRetryConfig(): RetryConfig;
+export declare function isFaucetRateLimitError(error: unknown): boolean;
+export declare function withFaucetRetry<T, R>(fn: (input: T) => Promise<R>, config?: RetryConfig): (input: T) => Promise<R>;

package/dist/tools/retry.js

@@ -0,0 +1,85 @@
+export const DEFAULT_FAUCET_RETRY_CONFIG = {
+    maxRetries: 5,
+    intervalMs: 3000,
+};
+export function loadFaucetRetryConfig() {
+    const maxRetries = Number(process.env.WOWOK_FAUCET_RETRY_COUNT);
+    const intervalMs = Number(process.env.WOWOK_FAUCET_RETRY_INTERVAL_MS);
+    return {
+        maxRetries: Number.isFinite(maxRetries) && maxRetries > 0
+            ? Math.floor(maxRetries)
+            : DEFAULT_FAUCET_RETRY_CONFIG.maxRetries,
+        intervalMs: Number.isFinite(intervalMs) && intervalMs > 0
+            ? Math.floor(intervalMs)
+            : DEFAULT_FAUCET_RETRY_CONFIG.intervalMs,
+    };
+}
+export function isFaucetRateLimitError(error) {
+    if (!error)
+        return false;
+    const msg = error instanceof Error ? error.message : String(error);
+    const lower = msg.toLowerCase();
+    if (lower.includes("429"))
+        return true;
+    if (lower.includes("rate limit"))
+        return true;
+    if (lower.includes("rate-limit"))
+        return true;
+    if (lower.includes("too many requests"))
+        return true;
+    if (lower.includes("try again in"))
+        return true;
+    if (lower.includes("throttle"))
+        return true;
+    return false;
+}
+function isFaucetOperation(input) {
+    if (typeof input !== "object" || input === null)
+        return false;
+    const obj = input;
+    return obj.faucet !== undefined && obj.faucet !== null;
+}
+export function withFaucetRetry(fn, config = loadFaucetRetryConfig()) {
+    return async (input) => {
+        if (!isFaucetOperation(input)) {
+            return fn(input);
+        }
+        let lastError;
+        for (let attempt = 1; attempt <= config.maxRetries; attempt++) {
+            try {
+                const result = await fn(input);
+                if (result && typeof result === "object" && !Array.isArray(result)) {
+                    const obj = result;
+                    if (obj.faucet_retry_count === undefined && attempt > 1) {
+                        obj.faucet_retry_count = attempt;
+                    }
+                }
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                if (!isFaucetRateLimitError(error)) {
+                    throw error;
+                }
+                if (attempt === config.maxRetries) {
+                    break;
+                }
+                await new Promise((resolve) => setTimeout(resolve, config.intervalMs));
+            }
+        }
+        const lastMsg = lastError instanceof Error ? lastError.message : String(lastError);
+        const err = new Error(`Faucet request failed after ${config.maxRetries} attempts ` +
+            `(interval ${config.intervalMs}ms). Last error: ${lastMsg}. ` +
+            `The faucet endpoint is currently rate-limiting this account. ` +
+            `Suggestions:\n` +
+            `  1. Wait a few minutes and try again.\n` +
+            `  2. Use a different faucet network if available.\n` +
+            `  3. Override retry config via env vars: ` +
+            `WOWOK_FAUCET_RETRY_COUNT (default 5), ` +
+            `WOWOK_FAUCET_RETRY_INTERVAL_MS (default 3000).`);
+        if (lastError instanceof Error && lastError.code) {
+            err.code = lastError.code;
+        }
+        throw err;
+    };
+}

package/dist/tools/wip-deploy-assist.d.ts

@@ -0,0 +1,28 @@
+export type WipPathType = "local_unix" | "local_windows" | "local_relative" | "http_url" | "ipfs" | "data_url" | "unknown";
+export interface WipPathClassification {
+    type: WipPathType;
+    is_local: boolean;
+    is_network: boolean;
+    description: string;
+}
+export declare function classifyWipPath(path: string): WipPathClassification;
+export interface WipDeployOption {
+    name: string;
+    description: string;
+    difficulty: "easy" | "medium" | "hard";
+    free: boolean;
+    result_url_pattern: string;
+    steps: string[];
+    notes?: string[];
+}
+export declare function getDeployOptions(localFilePath: string): WipDeployOption[];
+export interface WipDeploySuggestion {
+    path: string;
+    classification: WipPathClassification;
+    needs_deployment: boolean;
+    reason: string;
+    options: WipDeployOption[];
+    remind_update_hash: boolean;
+}
+export declare function analyzeWipDeployment(path: string): WipDeploySuggestion;
+export declare function formatDeployHints(suggestion: WipDeploySuggestion): string;