@wowok/agent-mcp 2.6.0 → 2.6.3

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);
@@ -439,10 +462,10 @@ const WOWOK_TOOL_DESCRIPTION = [
     "Projects are the core organizing unit for all WoWok workflows. The policy is context-aware:",
     "",
     "CASE 1 — COMPLEX REQUIREMENT (user wants to build/deploy a full service):",
-    "  Examples: '搭建旅行地陪服务', '开一个玩具店', '创建租赁服务'",
+    "  Examples: 'build a travel guide service', 'open a toy store', 'create a rental service'",
     "  → You MUST auto-create a project FIRST, then create objects.",
     "  → Check for similar existing projects first: project_operation action='list_projects'",
-    "    If similar projects exist (same industry), remind the user: '发现类似项目 X, 是否复用或新建?'",
+    "    If similar projects exist (same industry), remind the user: 'Found similar project X. Reuse or create new?'",
     "  → Workflow:",
     "    1. project_operation action='create_project' (perspective='producer', project_industry=<best match>)",
     "    2. Create on-chain objects via onchain_operations with env.project='<prefix>' (auto-tags + auto-associates to SQLite project)",
@@ -452,11 +475,11 @@ const WOWOK_TOOL_DESCRIPTION = [
     "    6. Report results, fix critical findings, then publish Service",
     "",
     "CASE 2 — SINGLE OBJECT CREATION (user wants one specific object):",
-    "  Examples: '创建一个Permission', '添加一个Contact', '建一个Guard'",
+    "  Examples: 'create a Permission', 'add a Contact', 'build a Guard'",
     "  → Do NOT auto-create a project. If the user has an existing project, create with env.project='<prefix>' to auto-associate.",
     "  → If no existing project, after creation, REMIND the user:",
-    "    '此对象已创建。建议将其加入一个项目以便管理: project_operation action=\"add_object\"",
-    "    如还没有项目, 可用 action=\"create_project\" 新建。现有项目: [list projects if any]'",
+    "    'This object has been created. Consider adding it to a project for management: project_operation action=\"add_object\"",
+    "    If no project exists yet, use action=\"create_project\" to create one. Existing projects: [list projects if any]'",
     "  → If the user then says 'yes, create a project' or 'add to project X', proceed accordingly.",
     "",
     "CASE 3 — CONSUMER FLOW (user wants to buy/evaluate a service):",
@@ -478,12 +501,215 @@ 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.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 generateSuggestion(code, issue, receivedValue) {
+    const issueAny = issue;
+    switch (code) {
+        case "invalid_type": {
+            const expected = issueAny.expected;
+            const received = issueAny.received;
+            if (expected === "number" && typeof receivedValue === "string") {
+                return `Convert to number: ${Number(receivedValue)}`;
+            }
+            if (expected === "string") {
+                return `Wrap in quotes or call String(...)`;
+            }
+            if (expected === "array") {
+                return `Wrap in array: [${JSON.stringify(receivedValue)}]`;
+            }
+            if (expected === "object") {
+                return `Provide an object, not a primitive`;
+            }
+            return `Convert value to ${expected ?? "the expected type"}`;
+        }
+        case "invalid_enum_value": {
+            const options = issueAny.options;
+            const optionsStr = Array.isArray(options)
+                ? options.map((v) => JSON.stringify(v)).join(" | ")
+                : String(options);
+            return `Use one of: ${optionsStr}`;
+        }
+        case "invalid_literal": {
+            const expected = issueAny.expected;
+            return `Use the exact value: ${JSON.stringify(expected)}`;
+        }
+        case "too_small": {
+            const minimum = issueAny.minimum;
+            const type = issueAny.type;
+            if (type === "array") {
+                return `Add at least ${minimum} element(s) to the array`;
+            }
+            if (type === "string") {
+                return `String must be at least ${minimum} character(s) long`;
+            }
+            if (type === "number") {
+                return `Use a value >= ${minimum}`;
+            }
+            return `Value must be >= ${minimum}`;
+        }
+        case "too_big": {
+            const maximum = issueAny.maximum;
+            const type = issueAny.type;
+            if (type === "array") {
+                return `Reduce array to at most ${maximum} element(s)`;
+            }
+            if (type === "string") {
+                return `Shorten string to at most ${maximum} character(s)`;
+            }
+            if (type === "number") {
+                return `Use a value <= ${maximum}`;
+            }
+            return `Value must be <= ${maximum}`;
+        }
+        case "unrecognized_keys": {
+            const keys = issueAny.keys;
+            return `Remove unknown field(s): ${(keys ?? []).join(", ")}. Check the schema for valid field names.`;
+        }
+        case "invalid_union": {
+            return `Value does not match any of the union variants. Check the schema for valid shapes.`;
+        }
+        case "invalid_string": {
+            const validation = issueAny.validation;
+            if (validation === "url")
+                return `Provide a valid URL string`;
+            if (validation === "email")
+                return `Provide a valid email string`;
+            if (validation === "uuid")
+                return `Provide a valid UUID string`;
+            if (validation === "regex")
+                return `String does not match the required pattern`;
+            return `Provide a valid string matching the validation: ${validation ?? "unknown"}`;
+        }
+        case "invalid_date": {
+            return `Provide a valid Date object or ISO date string`;
+        }
+        case "not_finite": {
+            return `Use a finite number (not Infinity or NaN)`;
+        }
+        case "invalid_arguments": {
+            return `Arguments do not match the expected schema`;
+        }
+        case "invalid_return_type": {
+            return `Return type does not match the expected schema`;
+        }
+        case "custom": {
+            return `Custom validation failed — see the field's description in the schema`;
+        }
+        default: {
+            return `Fix the value at '${issue.path.join(".")}' based on the schema`;
+        }
+    }
+}
+function formatZodErrorsStructured(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;
+        const issueAny = issue;
+        let expected;
+        if (code === "invalid_type") {
+            const exp = issueAny.expected;
+            const rec = issueAny.received;
+            if (typeof exp === "string" && typeof rec === "string") {
+                expected = exp;
+            }
+        }
+        else if (code === "invalid_literal") {
+            const exp = issueAny.expected;
+            if (exp !== undefined) {
+                expected = typeof exp === "string" ? exp : JSON.stringify(exp);
+            }
+        }
+        else if (code === "invalid_enum_value") {
+            const options = issueAny.options;
+            if (Array.isArray(options)) {
+                expected = options.map((v) => JSON.stringify(v)).join(" | ");
+            }
+        }
+        else if (code === "too_big" || code === "too_small") {
+            const threshold = issueAny.maximum ?? issueAny.minimum;
+            if (threshold !== undefined) {
+                expected = String(threshold);
+            }
+        }
+        const receivedVal = extractValueAtPath(input, issue.path);
+        const suggestion = generateSuggestion(code, issue, receivedVal);
+        return {
+            path,
+            code,
+            message,
+            expected,
+            received_value: receivedVal,
+            suggestion,
+        };
     });
 }
+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 +744,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,22 +976,52 @@ 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 structuredErrors = [];
+        if (!validationResult.success) {
+            structuredErrors.push(...formatZodErrorsStructured(validationResult.error, normalizedData));
+        }
+        if (unknownFields.length > 0) {
+            for (const f of unknownFields) {
+                structuredErrors.push({
+                    path: f,
+                    code: "unrecognized_keys",
+                    message: `Unknown field '${f}' is not allowed`,
+                    suggestion: `Remove field '${f}' or check the schema for valid field names`,
+                });
+            }
+        }
         const fullSchema = loadPreGeneratedSchema(normalizedToolName) ?? zodToJsonSchemaSafe(entry.config.inputSchema, normalizedToolName);
         const relevantSchema = extractRelevantSchema(fullSchema, normalizedToolName, normalizedData);
+        const firstSuggestion = structuredErrors[0]?.suggestion
+            ? ` FIRST ERROR SUGGESTION: ${structuredErrors[0].suggestion}`
+            : '';
+        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).${firstSuggestion}`,
+            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).`,
+            `Structured errors with fix suggestions are in structuredContent.result.structured_errors (ARCH-02).`,
+        ].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: {
                     status: "schema_mismatch",
                     errors: allErrors,
+                    structured_errors: structuredErrors,
                     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: {
@@ -706,15 +1065,31 @@ 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 structuredErrors = [{
+                    path: "(runtime)",
+                    code: "schema_validation_error",
+                    message: errorMessage,
+                    suggestion: "Check the error message and the schema below for the correct field format",
+                }];
+            const textContent = [
+                `Schema mismatch for ${normalizedToolName}: ${errorMessage}`,
+                "",
+                schemaPreview,
+                "",
+                "Fix the parameters and retry. Full JSON Schema is in structuredContent.schema.input.",
+                "Structured errors with fix suggestions are in structuredContent.result.structured_errors (ARCH-02).",
+            ].join("\n");
             return {
                 content: [{
                         type: "text",
-                        text: `Schema mismatch for ${normalizedToolName}: ${errorMessage}`,
+                        text: textContent,
                     }],
                 structuredContent: {
                     result: {
                         status: "schema_mismatch",
                         errors: [errorMessage],
+                        structured_errors: structuredErrors,
                         hint: `Fix your parameters based on the schema below and retry. CACHE THIS SCHEMA for future ${normalizedToolName} calls.`,
                     },
                     schema: {

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;