@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/tools/shared.js

@@ -0,0 +1,130 @@
+import { confirmGate } from "../safety/confirm-gate.js";
+import { renderPreview } from "../safety/preview.js";
+import { validateOperation, hasBlockingViolations, getWarningViolations, } from "../knowledge/index.js";
+import { getHarness } from "../harness/index.js";
+import { isEnabled as isRuntimeEnabled } from "../config/index.js";
+import { classifyError, buildDataSemantic, } from "../schema/call/semantic.js";
+import { strictParse } from "../schema/index.js";
+export function withHarness(base, operation, intent) {
+    if (!isRuntimeEnabled("harness"))
+        return base;
+    try {
+        const harness = getHarness();
+        const expected = harness.expect(operation, intent, base.operation_type, base.data);
+        return {
+            ...base,
+            harness,
+            expected,
+            operation_id: `${base.operation_type}_${Date.now()}`,
+        };
+    }
+    catch {
+        return base;
+    }
+}
+export function wrapLocalHandler(config) {
+    const { schema, operationFn, parseLabel, buildContext } = config;
+    return async (args) => {
+        let validated;
+        try {
+            validated = strictParse(schema, args, parseLabel);
+            const result = await operationFn(validated);
+            const ctx = buildContext(validated);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+                structuredContent: {
+                    result: {
+                        status: "success",
+                        data: result,
+                    },
+                    semantic: buildDataSemantic(result, ctx),
+                },
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const ctx = validated ? buildContext(validated) : undefined;
+            const classified = classifyError(errorMessage);
+            const errorResult = {
+                status: "error",
+                error: errorMessage,
+            };
+            if (classified.error_code !== undefined)
+                errorResult.error_code = classified.error_code;
+            if (classified.retryable !== undefined)
+                errorResult.retryable = classified.retryable;
+            if (classified.recovery_hint !== undefined)
+                errorResult.recovery_hint = classified.recovery_hint;
+            return {
+                content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                structuredContent: {
+                    result: errorResult,
+                    semantic: buildDataSemantic(undefined, ctx, true, errorMessage),
+                },
+            };
+        }
+    };
+}
+export function buildPendingConfirmation(operation_type, data, env) {
+    const gate = confirmGate(operation_type, data, env, env?.user_intent_phrases);
+    if (gate.pass)
+        return { content: [], structuredContent: null };
+    const preview = gate.preview;
+    const rendered = renderPreview(preview);
+    const output = {
+        message: rendered,
+        result: {
+            type: "pending_confirmation",
+            preview,
+            rule_id: gate.rule_id,
+        },
+        semantic: {
+            intent: `${operation_type}_awaiting_confirmation`,
+            status: "pending_input",
+            summary: `Operation blocked by ConfirmGate (${gate.level}). Review the preview and re-call with env.confirmed=true to proceed.`,
+            next_actions: [
+                {
+                    action: "confirm: re-call the SAME operation with env.confirmed=true",
+                    reason: `ConfirmGate rule '${gate.rule_id}' matched. The operation was NOT executed.`,
+                    tool: "onchain_operations",
+                    priority: "required",
+                },
+            ],
+            warnings: preview.warnings ?? [],
+        },
+    };
+    return {
+        content: [{ type: "text", text: rendered }],
+        structuredContent: output,
+    };
+}
+export function buildConstraintError(operation_type, violations) {
+    const errors = violations.filter((v) => v.severity === "error");
+    const errorList = errors.map((v) => `  • [${v.field}] ${v.message}`).join("\n");
+    const message = `Pre-call constraint violations for '${operation_type}':\n${errorList}\n\nFix the listed field(s) and retry.`;
+    const output = {
+        message,
+        result: {
+            type: "error",
+            error: message,
+            error_code: "invalid_parameter",
+            retryable: false,
+            recovery_hint: "Review the constraint violations above and correct the corresponding fields.",
+        },
+    };
+    return {
+        content: [{ type: "text", text: message }],
+        structuredContent: output,
+    };
+}
+export function buildClassifiedErrorResult(base, error, classified) {
+    const result = { ...base, error };
+    if (classified.error_code !== undefined)
+        result.error_code = classified.error_code;
+    if (classified.retryable !== undefined)
+        result.retryable = classified.retryable;
+    if (classified.recovery_hint !== undefined)
+        result.recovery_hint = classified.recovery_hint;
+    return result;
+}
+export { validateOperation, hasBlockingViolations, getWarningViolations, };

package/dist/tools/types.d.ts

@@ -0,0 +1,35 @@
+import type { z } from "zod";
+import type { classifyError } from "../schema/call/semantic.js";
+import type { SemanticContext } from "../schema/call/semantic.js";
+export interface ToolConfig {
+    title: string;
+    description: string;
+    inputSchema: z.ZodTypeAny;
+    outputSchema?: z.ZodTypeAny;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    _meta?: Record<string, unknown>;
+}
+export type ErrorShapeBuilder = (error: string, classified: ReturnType<typeof classifyError>, ctx: SemanticContext) => Record<string, unknown>;
+export interface ToolDispatchResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown> | undefined;
+}
+export interface ToolEntry {
+    name: string;
+    handler: (args: unknown) => Promise<ToolDispatchResult>;
+    config: ToolConfig;
+    errorShapeBuilder?: ErrorShapeBuilder;
+    timeoutMs?: number;
+    applyRules?: (args: unknown) => ToolDispatchResult | null;
+}
+export interface DispatchOptions {
+    skipRules?: boolean;
+}

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/wrap.d.ts

@@ -0,0 +1,14 @@
+import type { ErrorShapeBuilder, ToolDispatchResult } from "./types.js";
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs?: number, operationName?: string): Promise<T>;
+export declare function wrapHandlerWithErrorShape(handler: (args: unknown) => Promise<ToolDispatchResult>, timeoutMs: number, toolName: string, errorShapeBuilder?: ErrorShapeBuilder): (args: unknown) => Promise<ToolDispatchResult>;
+export declare const statusErrorShape: ErrorShapeBuilder;
+export declare const operationErrorShape: ErrorShapeBuilder;
+export declare const strictStatusErrorShape: ErrorShapeBuilder;
+export type HarnessHookPhase = "pre_call" | "post_call" | "pre_publish" | "pre_sign";
+export interface HarnessHookContext {
+    toolName: string;
+    args: unknown;
+    result?: ToolDispatchResult;
+    error?: unknown;
+}
+export declare function dispatchWithHarness(handler: (args: unknown) => Promise<ToolDispatchResult>, toolName: string): (args: unknown) => Promise<ToolDispatchResult>;

package/dist/tools/wrap.js

@@ -0,0 +1,267 @@
+import { classifyError, buildDataSemantic, } from "../schema/call/semantic.js";
+import { buildClassifiedErrorResult } from "./shared.js";
+import { shouldRunLightHooks, shouldRunHeavyHooks, recordOperationFailure, } from "../harness/auto-escalation.js";
+import { getHarness } from "../harness/index.js";
+import { recordOperationOutcome } from "../experience/index.js";
+import { recordIndustrySignal } from "../knowledge/flywheel-loop.js";
+export function withTimeout(promise, timeoutMs = 30000, operationName = "operation") {
+    let timer;
+    return Promise.race([
+        promise.finally(() => {
+            if (timer)
+                clearTimeout(timer);
+        }),
+        new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                let hint = "";
+                if (operationName.includes("messenger")) {
+                    hint = " This is a messenger network operation. Possible causes: " +
+                        "(1) messenger server (https://messenger.wowok.net) unreachable, " +
+                        "(2) no messenger-enabled account configured (use account_operation to set messenger name), " +
+                        "(3) network connectivity issue. " +
+                        "Ensure you have a messenger-enabled account and the server is reachable.";
+                }
+                reject(new Error(`Operation '${operationName}' timed out after ${timeoutMs}ms.${hint}`));
+            }, timeoutMs);
+        }),
+    ]);
+}
+export function wrapHandlerWithErrorShape(handler, timeoutMs, toolName, errorShapeBuilder) {
+    return async (args) => {
+        try {
+            return await withTimeout(handler(args), timeoutMs, toolName);
+        }
+        catch (error) {
+            if (errorShapeBuilder) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                const classified = classifyError(errorMessage);
+                const ctx = { operation_type: toolName, data: args };
+                const structuredContent = errorShapeBuilder(errorMessage, classified, ctx);
+                return {
+                    content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                    structuredContent,
+                };
+            }
+            throw error;
+        }
+    };
+}
+export const statusErrorShape = (error, classified, ctx) => ({
+    result: buildClassifiedErrorResult({ status: "error" }, error, classified),
+    semantic: buildDataSemantic(undefined, ctx, true, error),
+});
+export const operationErrorShape = (error, classified, ctx) => ({
+    result: buildClassifiedErrorResult({ operation: "error" }, error, classified),
+    semantic: buildDataSemantic(undefined, ctx, true, error),
+});
+export const strictStatusErrorShape = (error, _classified, _ctx) => ({
+    result: { status: "error", error },
+});
+export function dispatchWithHarness(handler, toolName) {
+    return async (args) => {
+        const harnessWarnings = [];
+        const harness = getHarness();
+        const runLight = shouldRunLightHooks();
+        const runHeavy = shouldRunHeavyHooks();
+        const isPublishOp = runHeavy && isPublishOperation(toolName, args);
+        const isSignOp = runHeavy && isSignOperation(toolName, args);
+        let expectedResult;
+        if (runLight) {
+            try {
+                const operationType = extractOperationType(toolName, args);
+                const intent = extractIntent(toolName, args);
+                if (operationType && intent) {
+                    expectedResult = harness.expect(toolName, intent, operationType, extractData(args));
+                }
+            }
+            catch (e) {
+                harnessWarnings.push(`pre_call hook failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        if (isPublishOp) {
+            try {
+                harnessWarnings.push("pre_publish: full-tier check engaged");
+            }
+            catch (e) {
+                harnessWarnings.push(`pre_publish hook failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        if (isSignOp) {
+            try {
+                harnessWarnings.push("pre_sign: full-tier check engaged");
+            }
+            catch (e) {
+                harnessWarnings.push(`pre_sign hook failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        let result;
+        try {
+            result = await handler(args);
+        }
+        catch (e) {
+            const errorCode = e instanceof Error ? e.message : String(e);
+            const escalation = recordOperationFailure(toolName, errorCode);
+            if (escalation) {
+                harnessWarnings.push(`Harness escalated to full tier: ${escalation.reason}`);
+            }
+            throw e;
+        }
+        if (runLight && expectedResult) {
+            try {
+                if (result?.structuredContent) {
+                    const verifyInput = buildVerifyInput(expectedResult, result);
+                    const report = harness.verify(verifyInput);
+                    if (report.status === "fail") {
+                        harnessWarnings.push(`Harness verify FAIL: ${report.summary}`);
+                    }
+                    else if (report.status === "warn") {
+                        harnessWarnings.push(`Harness verify WARN: ${report.summary}`);
+                    }
+                }
+            }
+            catch (e) {
+                harnessWarnings.push(`post_call hook failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        if (isWriteClassTool(toolName)) {
+            try {
+                const operationType = extractOperationType(toolName, args) ?? toolName;
+                const intent = extractIntent(toolName, args) ?? toolName;
+                const data = extractData(args) ?? args;
+                const outcome = classifyOutcome(result);
+                const errorCode = extractErrorCode(result);
+                const industry = extractIndustry(args) ?? "general";
+                recordOperationOutcome(operationType, data, intent, outcome, errorCode);
+                recordIndustrySignal(industry, { type: operationType }, {
+                    success: outcome === "success",
+                    error_code: errorCode,
+                });
+            }
+            catch (e) {
+                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];
+            }
+            else {
+                sc.harness_warnings = harnessWarnings;
+            }
+        }
+        return result;
+    };
+}
+function isPublishOperation(toolName, args) {
+    if (toolName !== "onchain_operations")
+        return false;
+    const opType = extractOperationType(toolName, args);
+    return opType === "service" || opType === "machine";
+}
+function isSignOperation(toolName, args) {
+    if (toolName === "wip_file") {
+        const data = args?.operation_type;
+        return data === "sign";
+    }
+    return toolName === "onchain_operations";
+}
+function extractOperationType(toolName, args) {
+    if (!args || typeof args !== "object")
+        return undefined;
+    const obj = args;
+    if (toolName === "onchain_operations") {
+        return typeof obj.operation_type === "string" ? obj.operation_type : undefined;
+    }
+    if (toolName === "project_operation") {
+        return typeof obj.action === "string" ? obj.action : undefined;
+    }
+    return typeof obj.operation_type === "string" ? obj.operation_type : undefined;
+}
+function extractIntent(toolName, args) {
+    if (!args || typeof args !== "object")
+        return undefined;
+    const obj = args;
+    if (toolName === "project_operation" && typeof obj.action === "string") {
+        return `project:${obj.action}`;
+    }
+    const opType = obj.operation_type;
+    if (typeof opType === "string")
+        return `${toolName}:${opType}`;
+    return toolName;
+}
+function extractData(args) {
+    if (!args || typeof args !== "object")
+        return undefined;
+    const obj = args;
+    const data = obj.data;
+    return data && typeof data === "object" ? data : undefined;
+}
+function buildVerifyInput(expected, result) {
+    const sc = (result.structuredContent ?? {});
+    const semantic = sc.semantic;
+    return {
+        expected,
+        actual: {
+            result_type: typeof sc.result_type === "string" ? sc.result_type : undefined,
+            semantic,
+            error_code: typeof sc.error_code === "string" ? sc.error_code : undefined,
+            error: typeof sc.error === "string" ? sc.error : undefined,
+        },
+    };
+}
+const WRITE_CLASS_TOOLS = new Set([
+    "onchain_operations",
+    "project_operation",
+    "wip_file",
+    "messenger_operation",
+    "bridge_operation",
+]);
+function isWriteClassTool(toolName) {
+    return WRITE_CLASS_TOOLS.has(toolName);
+}
+function classifyOutcome(result) {
+    if (!result?.structuredContent)
+        return "failed";
+    const sc = result.structuredContent;
+    const status = typeof sc.status === "string" ? sc.status
+        : typeof sc.result_type === "string" ? sc.result_type
+            : "";
+    if (status === "error" || status === "failed")
+        return "failed";
+    if (status === "partial")
+        return "partial";
+    return "success";
+}
+function extractErrorCode(result) {
+    if (!result?.structuredContent)
+        return undefined;
+    const sc = result.structuredContent;
+    if (typeof sc.error_code === "string")
+        return sc.error_code;
+    const err = sc.error;
+    if (typeof err === "string")
+        return err;
+    if (err && typeof err === "object") {
+        const code = err.code;
+        if (typeof code === "string")
+            return code;
+    }
+    return undefined;
+}
+function extractIndustry(args) {
+    if (!args || typeof args !== "object")
+        return undefined;
+    const obj = args;
+    if (typeof obj.industry === "string")
+        return obj.industry;
+    const data = obj.data;
+    if (data && typeof data === "object") {
+        const d = data;
+        if (typeof d.industry === "string")
+            return d.industry;
+    }
+    return undefined;
+}

package/package.json

@@ -1,11 +1,25 @@
 {
   "name": "@wowok/agent-mcp",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Making It Easy for AI Agents to Communicate, Collaborate, Trade, and Trust.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "node",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./rules": {
+      "types": "./dist/rules.d.ts",
+      "import": "./dist/rules.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.js"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/wowok-ai/agent.git"
@@ -36,23 +50,23 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@wowok/wowok": "2.4.1",
+    "@wowok/wowok": "2.5.0",
     "lodash": "^4.18.1",
-    "zod": "^3.25.76"
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
     "tsx": "^4.21.0",
     "typescript": "^5.8.2",
-    "vitest": "^2.1.0",
-    "zod-to-json-schema": "^3.25.2"
+    "vitest": "^2.1.0"
   },
   "scripts": {
     "clean": "rm -rf dist",
     "build": "tsc && pnpm generate:schemas",
     "watch": "tsc --watch",
     "start": "tsx src/index.ts",
-    "generate:schemas": "tsx scripts/generate-json-schemas.ts",
+    "generate:schemas": "node --max-old-space-size=4096 --import tsx/esm scripts/generate-json-schemas.ts",
     "test": "vitest run",
     "test:watch": "vitest"
   }