@wowok/agent-mcp 2.3.12 → 2.3.14

package/dist/schemas/onchain_operations_service.schema.json

@@ -909,7 +909,7 @@
         "type": {
           "type": "string",
           "const": "submission",
-          "description": "Type of call response: submission"
+          "description": "Discriminator for this result variant. Constraint: always 'submission'. Example: 'submission'"
         },
         "guard": {
           "type": "array",
@@ -918,11 +918,11 @@
             "properties": {
               "object": {
                 "type": "string",
-                "description": "Guard object name or ID."
+                "description": "Guard object name or ID to verify against. Example: 'my-delivery-guard' or '0x123...'"
               },
               "impack": {
                 "type": "boolean",
-                "description": "Whether the verification result of this Guard participates in the final verification logic. If true, the verification result of this Guard will be included in the final verification result; if false, the verification result of this Guard will not be included."
+                "description": "Whether this Guard's verification result participates in the final logic. Constraint: if false, the Guard is checked but does not block the operation. Example: true"
               }
             },
             "required": [
@@ -930,7 +930,8 @@
               "impack"
             ],
             "additionalProperties": false
-          }
+          },
+          "description": "Array of Guard objects to verify. Relation: each entry corresponds to a Guard bound to the operation."
         },
         "submission": {
           "type": "array",
@@ -939,7 +940,7 @@
             "properties": {
               "guard": {
                 "$ref": "#/definitions/submission/properties/guard/items/properties/object",
-                "description": "Guard object name or ID."
+                "description": "Guard object name or ID that requires submission data. Example: 'my-delivery-guard'"
               },
               "submission": {
                 "type": "array",
@@ -1391,7 +1392,7 @@
                   "additionalProperties": false,
                   "description": "Guard table item"
                 },
-                "description": "User-submitted data required for Guard verification."
+                "description": "User-submitted data matching the Guard's required fields. Relation: structure must match the Guard table's column definitions. Example: [{field:'delivery_proof', value:'Qm...'}]"
               }
             },
             "required": [
@@ -1399,8 +1400,9 @@
               "submission"
             ],
             "additionalProperties": false,
-            "description": "Permission guard submission data."
-          }
+            "description": "One Guard's submission data: the Guard to verify plus the user-provided data that satisfies its requirements."
+          },
+          "description": "User-submitted data for each Guard. Relation: one entry per Guard in the guard array; fill submission fields and resubmit via call_with_submission."
         }
       },
       "required": [
@@ -1409,7 +1411,7 @@
         "submission"
       ],
       "additionalProperties": false,
-      "description": "Guard verification submission data required to complete an operation. Contains: (1) 'guard' - array of Guard objects to verify, each with an object ID and an 'impack' flag indicating if its result affects the final outcome; (2) 'submission' - array of user data submissions matching the Guard's requirements. The operation proceeds only after all Guards with impack=true are successfully verified."
+      "description": "Guard verification required. The operation was blocked because one or more Guards require user-submitted data. Fill the submission array and resubmit. Semantic status is 'pending_input'."
     }
   }
 }

package/dist/schemas/onchain_operations_treasury.schema.json

@@ -650,7 +650,7 @@
         "type": {
           "type": "string",
           "const": "submission",
-          "description": "Type of call response: submission"
+          "description": "Discriminator for this result variant. Constraint: always 'submission'. Example: 'submission'"
         },
         "guard": {
           "type": "array",
@@ -659,11 +659,11 @@
             "properties": {
               "object": {
                 "type": "string",
-                "description": "Guard object name or ID."
+                "description": "Guard object name or ID to verify against. Example: 'my-delivery-guard' or '0x123...'"
               },
               "impack": {
                 "type": "boolean",
-                "description": "Whether the verification result of this Guard participates in the final verification logic. If true, the verification result of this Guard will be included in the final verification result; if false, the verification result of this Guard will not be included."
+                "description": "Whether this Guard's verification result participates in the final logic. Constraint: if false, the Guard is checked but does not block the operation. Example: true"
               }
             },
             "required": [
@@ -671,7 +671,8 @@
               "impack"
             ],
             "additionalProperties": false
-          }
+          },
+          "description": "Array of Guard objects to verify. Relation: each entry corresponds to a Guard bound to the operation."
         },
         "submission": {
           "type": "array",
@@ -680,7 +681,7 @@
             "properties": {
               "guard": {
                 "$ref": "#/definitions/submission/properties/guard/items/properties/object",
-                "description": "Guard object name or ID."
+                "description": "Guard object name or ID that requires submission data. Example: 'my-delivery-guard'"
               },
               "submission": {
                 "type": "array",
@@ -1132,7 +1133,7 @@
                   "additionalProperties": false,
                   "description": "Guard table item"
                 },
-                "description": "User-submitted data required for Guard verification."
+                "description": "User-submitted data matching the Guard's required fields. Relation: structure must match the Guard table's column definitions. Example: [{field:'delivery_proof', value:'Qm...'}]"
               }
             },
             "required": [
@@ -1140,8 +1141,9 @@
               "submission"
             ],
             "additionalProperties": false,
-            "description": "Permission guard submission data."
-          }
+            "description": "One Guard's submission data: the Guard to verify plus the user-provided data that satisfies its requirements."
+          },
+          "description": "User-submitted data for each Guard. Relation: one entry per Guard in the guard array; fill submission fields and resubmit via call_with_submission."
         }
       },
       "required": [
@@ -1150,7 +1152,7 @@
         "submission"
       ],
       "additionalProperties": false,
-      "description": "Guard verification submission data required to complete an operation. Contains: (1) 'guard' - array of Guard objects to verify, each with an object ID and an 'impack' flag indicating if its result affects the final outcome; (2) 'submission' - array of user data submissions matching the Guard's requirements. The operation proceeds only after all Guards with impack=true are successfully verified."
+      "description": "Guard verification required. The operation was blocked because one or more Guards require user-submitted data. Fill the submission array and resubmit. Semantic status is 'pending_input'."
     }
   }
 }

package/dist/schemas/onchain_table_data.output.json

@@ -1925,6 +1925,9 @@
               "additionalProperties": false
             }
           ]
+        },
+        "semantic": {
+          "description": "Business semantic summary for the table data query"
         }
       },
       "required": [

package/dist/schemas/query_toolkit.schema.json

@@ -134,6 +134,10 @@
                       },
                       "additionalProperties": false,
                       "description": "Filter by update time range"
+                    },
+                    "includePubkey": {
+                      "type": "boolean",
+                      "description": "Include pubkey in results (default: false). Pubkey is large (~900 bytes), omit unless needed"
                     }
                   },
                   "additionalProperties": false,
@@ -144,7 +148,7 @@
                 "query_type"
               ],
               "additionalProperties": false,
-              "description": "Query your LOCAL accounts — view all accounts stored on this device (addresses, public keys, messenger status, suspension state). Use to discover available accounts before operations. Returns: AccountData[] (name, address, pubkey, suspended, messenger, timestamps)"
+              "description": "Query your LOCAL accounts — view all accounts stored on this device (addresses, messenger status, suspension state). Use filter.includePubkey=true to also include public keys (~900 bytes each, omitted by default). Returns: AccountData[] (name, address, pubkey?, suspended, messenger, timestamps)"
             },
             {
               "type": "object",

package/dist/telemetry/index.d.ts

@@ -0,0 +1,19 @@
+import type { CallOutput } from "../schema/call/base.js";
+export interface TelemetryEvent {
+    timestamp: string;
+    tool_name: string;
+    operation_type: string;
+    intent?: string;
+    status?: "success" | "partial" | "failed" | "pending_input";
+    error_code?: string;
+    duration_ms: number;
+    semantic_hit: boolean;
+    error_message?: string;
+}
+export declare function setTelemetryEnabled(enabled: boolean): void;
+export declare function isTelemetryEnabled(): boolean;
+export declare function captureTelemetry(toolName: string, structuredContent: CallOutput | undefined, durationMs: number, operationTypeHint?: string): Promise<void>;
+export declare function captureTelemetryError(toolName: string, error: any, durationMs: number, operationTypeHint?: string): Promise<void>;
+export declare function withTelemetry<TArgs, TOutput extends {
+    structuredContent?: CallOutput;
+}>(toolName: string, handler: (args: TArgs) => Promise<TOutput>): (args: TArgs) => Promise<TOutput>;

package/dist/telemetry/index.js

@@ -0,0 +1,112 @@
+import { getStorage } from "./storage.js";
+import { redactObject } from "./redact.js";
+let _enabled = true;
+export function setTelemetryEnabled(enabled) {
+    _enabled = enabled;
+}
+export function isTelemetryEnabled() {
+    return _enabled;
+}
+function extractFromOutput(structuredContent, toolName, operationTypeHint) {
+    if (!structuredContent) {
+        return { tool_name: toolName, semantic_hit: false };
+    }
+    const semantic = structuredContent.semantic;
+    const result = structuredContent.result;
+    const event = {
+        tool_name: toolName,
+        semantic_hit: !!semantic,
+    };
+    if (semantic) {
+        event.intent = semantic.intent;
+        event.status = semantic.status;
+    }
+    if (result?.type === "error") {
+        event.status = event.status || "failed";
+        event.error_code = result.error_code;
+        if (result.error) {
+            const truncated = String(result.error).slice(0, 500);
+            event.error_message = redactObject(truncated);
+        }
+    }
+    if (operationTypeHint) {
+        event.operation_type = operationTypeHint;
+    }
+    else if (semantic?.intent) {
+        event.operation_type = "unknown";
+    }
+    return event;
+}
+export async function captureTelemetry(toolName, structuredContent, durationMs, operationTypeHint) {
+    if (!_enabled)
+        return;
+    try {
+        const extracted = extractFromOutput(structuredContent, toolName, operationTypeHint);
+        const event = {
+            timestamp: new Date().toISOString(),
+            tool_name: extracted.tool_name || toolName,
+            operation_type: extracted.operation_type || "unknown",
+            intent: extracted.intent,
+            status: extracted.status,
+            error_code: extracted.error_code,
+            duration_ms: durationMs,
+            semantic_hit: extracted.semantic_hit ?? false,
+            error_message: extracted.error_message,
+        };
+        await getStorage().append(event);
+    }
+    catch {
+    }
+}
+export async function captureTelemetryError(toolName, error, durationMs, operationTypeHint) {
+    if (!_enabled)
+        return;
+    try {
+        const errorMsg = String(error?.message ?? error).slice(0, 500);
+        const event = {
+            timestamp: new Date().toISOString(),
+            tool_name: toolName,
+            operation_type: operationTypeHint || "unknown",
+            status: "failed",
+            duration_ms: durationMs,
+            semantic_hit: false,
+            error_message: redactObject(errorMsg),
+        };
+        await getStorage().append(event);
+    }
+    catch {
+    }
+}
+export function withTelemetry(toolName, handler) {
+    return async (args) => {
+        const start = Date.now();
+        let output;
+        try {
+            output = await handler(args);
+            return output;
+        }
+        catch (error) {
+            await captureTelemetryError(toolName, error, Date.now() - start, extractOperationType(args));
+            throw error;
+        }
+        finally {
+            if (output) {
+                await captureTelemetry(toolName, output?.structuredContent, Date.now() - start, extractOperationType(args));
+            }
+        }
+    };
+}
+function extractOperationType(args) {
+    if (!args || typeof args !== "object")
+        return undefined;
+    if (typeof args.operation_type === "string") {
+        if (args.operation_type.startsWith("cross_chain") || args.operation_type.startsWith("claim") ||
+            args.operation_type.startsWith("withdraw") || args.operation_type.startsWith("query_")) {
+            return "bridge_" + args.operation_type;
+        }
+        return args.operation_type;
+    }
+    if (args.data?.operation_type)
+        return args.data.operation_type;
+    return undefined;
+}

package/dist/telemetry/redact.d.ts

@@ -0,0 +1,2 @@
+export declare function redactAddress(value: string): string;
+export declare function redactObject<T>(obj: T): T;

package/dist/telemetry/redact.js

@@ -0,0 +1,23 @@
+import { createHash } from "crypto";
+const ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40,}$/;
+export function redactAddress(value) {
+    if (typeof value !== "string")
+        return value;
+    if (!ADDRESS_PATTERN.test(value))
+        return value;
+    const hash = createHash("sha256").update(value.toLowerCase()).digest("hex");
+    return "0x" + hash.slice(0, 16);
+}
+export function redactObject(obj) {
+    if (typeof obj === "string")
+        return redactAddress(obj);
+    if (Array.isArray(obj))
+        return obj.map(redactObject);
+    if (obj && typeof obj === "object" && obj.constructor === Object) {
+        const out = {};
+        for (const k of Object.keys(obj))
+            out[k] = redactObject(obj[k]);
+        return out;
+    }
+    return obj;
+}

package/dist/telemetry/storage.d.ts

@@ -0,0 +1,8 @@
+export interface TelemetryStorage {
+    append(event: Record<string, unknown>): Promise<void>;
+    query(filter: Partial<Record<string, unknown>>): Promise<Record<string, unknown>[]>;
+    rotate(): Promise<void>;
+}
+export declare function getStorage(): TelemetryStorage;
+export declare function setStorage(storage: TelemetryStorage): void;
+export declare function getTelemetryFilePath(): string;

package/dist/telemetry/storage.js

@@ -0,0 +1,80 @@
+import { mkdir, appendFile, stat, rename } from "fs/promises";
+import { dirname, join } from "path";
+import { homedir } from "os";
+const MAX_SIZE_BYTES = 10 * 1024 * 1024;
+const DATA_DIR = join(homedir(), ".wowok", "data");
+const TELEMETRY_FILE = join(DATA_DIR, "telemetry.jsonl");
+const ROTATED_FILE = join(DATA_DIR, "telemetry.jsonl.1");
+class JsonlStorage {
+    filePath;
+    rotatedPath;
+    writeQueue = Promise.resolve();
+    constructor(filePath = TELEMETRY_FILE, rotatedPath = ROTATED_FILE) {
+        this.filePath = filePath;
+        this.rotatedPath = rotatedPath;
+    }
+    async append(event) {
+        this.writeQueue = this.writeQueue.then(async () => {
+            try {
+                await mkdir(dirname(this.filePath), { recursive: true });
+                const line = JSON.stringify(event) + "\n";
+                await appendFile(this.filePath, line, "utf8");
+                await this.maybeRotate();
+            }
+            catch {
+            }
+        });
+        return this.writeQueue;
+    }
+    async query(filter) {
+        try {
+            const { readFile } = await import("fs/promises");
+            const content = await readFile(this.filePath, "utf8");
+            const lines = content.split("\n").filter((l) => l.trim());
+            const events = lines.map((l) => {
+                try {
+                    return JSON.parse(l);
+                }
+                catch {
+                    return null;
+                }
+            }).filter((e) => e !== null);
+            return events.filter((e) => {
+                return Object.entries(filter).every(([k, v]) => e[k] === v);
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    async rotate() {
+        try {
+            await rename(this.filePath, this.rotatedPath).catch(() => { });
+        }
+        catch {
+        }
+    }
+    async maybeRotate() {
+        try {
+            const stats = await stat(this.filePath);
+            if (stats.size >= MAX_SIZE_BYTES) {
+                await this.rotate();
+            }
+        }
+        catch {
+        }
+    }
+}
+let _storage = null;
+export function getStorage() {
+    if (!_storage) {
+        _storage = new JsonlStorage();
+    }
+    return _storage;
+}
+export function setStorage(storage) {
+    _storage = storage;
+}
+export function getTelemetryFilePath() {
+    return TELEMETRY_FILE;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/agent-mcp",
-  "version": "2.3.12",
+  "version": "2.3.14",
   "description": "Making It Easy for AI Agents to Communicate, Collaborate, Trade, and Trust.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,7 +36,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@wowok/wowok": "2.3.12",
+    "@wowok/wowok": "2.3.14",
     "lodash": "^4.18.1",
     "zod": "^3.25.76"
   },
@@ -44,6 +44,7 @@
     "@types/node": "^22.19.19",
     "tsx": "^4.21.0",
     "typescript": "^5.8.2",
+    "vitest": "^2.1.0",
     "zod-to-json-schema": "^3.25.2"
   },
   "scripts": {
@@ -51,6 +52,8 @@
     "build": "tsc && pnpm generate:schemas",
     "watch": "tsc --watch",
     "start": "tsx src/index.ts",
-    "generate:schemas": "tsx scripts/generate-json-schemas.ts"
+    "generate:schemas": "tsx scripts/generate-json-schemas.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }