@wowok/agent-mcp 2.4.1 → 2.4.3

package/dist/tools/index.js

@@ -0,0 +1,479 @@
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SCHEMA_DIR_CANDIDATES = [
+    join(__dirname, "..", "schemas"),
+    join(__dirname, "..", "..", "dist", "schemas"),
+];
+const preGeneratedSchemaCache = new Map();
+import { wrapHandlerWithErrorShape, statusErrorShape, operationErrorShape, strictStatusErrorShape, } from "./wrap.js";
+import { withTelemetry } from "../telemetry/index.js";
+import { handleOnchainOperations } from "./handlers/onchain.js";
+import { handleAccountOperation, handleMarkOperation, handleInfoOperation } from "./handlers/local.js";
+import { handleWipOperations } from "./handlers/wip.js";
+import { handleMessengerOperation } from "./handlers/messenger.js";
+import { handleGuard2File, handleMachineNode2File } from "./handlers/file-export.js";
+import { handleWatchQueryOperations, handleOnchainTableData, handleOnchainEvents, handleWowokInfo, } from "./handlers/query.js";
+import { handleSchemaQuery } from "./handlers/schema-query.js";
+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 { applyOnchainRules } from "./rules-hook.js";
+import { createToolMeta, OnchainOperationsSchema, AccountOperationSchema, LocalMarkOperationSchema, LocalInfoOperationSchema, WipOperationsSchema, MessengerOperationInputSchema, Guard2File_InputSchema, MachineNode2File_InputSchema, WatchQueryOperationsSchema, 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 = [
+    {
+        name: "onchain_operations",
+        handler: handleOnchainOperations,
+        config: {
+            title: "⛓️ On-chain Operations",
+            description: "On-chain operations for WoWok object: service (marketplace listings), machine (workflow templates), progress (order tracking), repository (on-chain database), arbitration (dispute resolution), contact (IM management), treasury (team funds), reward (incentive pools), allocation (auto-distribution), permission (access control), guard (programmable trust rules), personal (public profile), payment (direct coin transfers), demand (service requests), order (order management), gen_passport (verified credentials), proof (on-chain proof objects), gen_proof (generate proof shortcut).\n\n💡 Schema hint: Use schema_query with action='get' and name='onchain_operations' to retrieve the complete parameter schema. For individual operation schemas (e.g., 'onchain_operations_permission'), use schema_query with action='list_operations' to see all available operation schemas.",
+            inputSchema: OnchainOperationsSchema,
+            outputSchema: CallOutputSchema,
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+            _meta: createToolMeta("operation", ["service", "machine", "progress", "repository", "arbitration", "contact", "treasury", "reward", "allocation", "permission", "guard", "personal", "payment", "demand", "order", "gen_passport", "proof", "gen_proof", "on-chain", "blockchain"]),
+        },
+        applyRules: applyOnchainRules,
+    },
+    {
+        name: "account_operation",
+        handler: handleAccountOperation,
+        config: {
+            title: "🔒 LOCAL ONLY: Account - Wallet Management",
+            description: "🔒 100% LOCAL, NEVER ON-CHAIN 🔒 Manage WoWok accounts locally on device: generate, suspend, resume, faucet-test, operate assets, sign data, etc.\n\n💡 Schema hint: Use schema_query with action='get' and name='account_operation' to retrieve the exact parameter schema before calling.",
+            inputSchema: AccountOperationSchema,
+            outputSchema: AccountOperationOutputWrappedSchema,
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+            _meta: createToolMeta("operation", ["account", "local", "private", "wallet", "off-chain"]),
+        },
+        errorShapeBuilder: statusErrorShape,
+    },
+    {
+        name: "local_mark_operation",
+        handler: handleMarkOperation,
+        config: {
+            title: "🔒 LOCAL ONLY: LocalMark - Address Book Management",
+            description: "100% LOCAL, NEVER ON-CHAIN 🔒 Manage ID names and tags stored ONLY on your local device for easy identification of user address or object IDs by name.\n\n💡 Schema hint: Use schema_query with action='get' and name='local_mark_operation' to retrieve the exact parameter schema before calling.",
+            inputSchema: LocalMarkOperationSchema,
+            outputSchema: LocalMarkOperationOutputWrappedSchema,
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+            _meta: createToolMeta("operation", ["mark", "local", "private", "address-book", "off-chain"]),
+        },
+        errorShapeBuilder: statusErrorShape,
+    },
+    {
+        name: "local_info_operation",
+        handler: handleInfoOperation,
+        config: {
+            title: "🔒 LOCAL ONLY: LocalInfo - Private Data Management",
+            description: "100% LOCAL, NEVER ON-CHAIN 🔒 Manage sensitive personal information stored ONLY on your device: delivery addresses, phone numbers, contacts.\n\n💡 Schema hint: Use schema_query with action='get' and name='local_info_operation' to retrieve the exact parameter schema before calling.",
+            inputSchema: LocalInfoOperationSchema,
+            outputSchema: LocalInfoOperationOutputWrappedSchema,
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+            _meta: createToolMeta("operation", ["info", "local", "private", "data-management", "off-chain"]),
+        },
+        errorShapeBuilder: statusErrorShape,
+    },
+    {
+        name: "wip_file",
+        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.",
+            inputSchema: WipOperationsSchema,
+            outputSchema: z.object({
+                result: WipOperationOutputSchema,
+            }),
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+            _meta: createToolMeta("operation", ["wip", "promise", "file-generation", "verification", "signature", "local"]),
+        },
+    },
+    {
+        name: "messenger_operation",
+        handler: handleMessengerOperation,
+        config: {
+            title: "💬 Messenger Operations",
+            description: "WoWok encrypted messenger operations: watch conversations (with unread filtering, preview messages), send message, send file, watch messages (with viewed status filtering), extract zip messages, generate WTS, verify WTS, sign WTS, WTS to HTML, proof message on-chain, manage blacklist, friendslist, guardlist, settings, mark messages as viewed, mark conversation as viewed, and pull messages from server.\n\n💡 Schema hint: Use schema_query with action='get' and name='messenger_operation' to retrieve the exact parameter schema before calling.",
+            inputSchema: MessengerOperationInputSchema,
+            outputSchema: MessengerOperationOutputSchema,
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+            _meta: createToolMeta("operation", ["messenger", "message", "file", "wts", "blacklist", "friendslist", "guardlist", "settings", "proof", "communication"]),
+        },
+        errorShapeBuilder: operationErrorShape,
+        timeoutMs: 30000,
+    },
+    {
+        name: "guard2file",
+        handler: handleGuard2File,
+        config: {
+            title: "📄 Guard to File - Export Guard Definition",
+            description: "Export a Guard object's definition from the blockchain to a local JSON or Markdown file for editing and creating new Guard objects. Note: To query on-chain object information, use the 'query_toolkit' tool instead.\n\n💡 Schema hint: Use schema_query with action='get' and name='guard2file' to retrieve the exact parameter schema before calling.",
+            inputSchema: Guard2File_InputSchema,
+            outputSchema: Guard2File_OutputWrappedSchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            _meta: createToolMeta("generate file", ["guard", "export", "file", "json", "markdown", "on-chain"]),
+        },
+        errorShapeBuilder: strictStatusErrorShape,
+    },
+    {
+        name: "machineNode2file",
+        handler: handleMachineNode2File,
+        config: {
+            title: "⚙️ Machine Node to File - Export Machine Node Definition",
+            description: "Export a Machine object's node definition from the blockchain to a local JSON or Markdown file for editing and creating new Machine objects. Note: To query on-chain object information, use the 'query_toolkit' tool instead.\n\n💡 Schema hint: Use schema_query with action='get' and name='machineNode2file' to retrieve the exact parameter schema before calling.",
+            inputSchema: MachineNode2File_InputSchema,
+            outputSchema: MachineNode2File_OutputWrappedSchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            _meta: createToolMeta("generate file", ["machine", "export", "file", "json", "markdown", "on-chain", "workflow"]),
+        },
+        errorShapeBuilder: strictStatusErrorShape,
+    },
+    {
+        name: "query_toolkit",
+        handler: handleWatchQueryOperations,
+        config: {
+            title: "🔍 Data Query Toolkit",
+            description: "WOWOK data query toolkit — 9 query types covering local device data and on-chain blockchain data:\n\n"
+                + "LOCAL (device-only, never on-chain):\n"
+                + "1. local_mark_list — Query your LOCAL address book: maps human-readable names to blockchain addresses with optional tags. Use to resolve names→addresses or find addresses by tag.\n"
+                + "2. account_list — Query your LOCAL accounts (addresses, messenger status, suspension state). Use filter.includePubkey=true to also include public keys. Use to discover available accounts before operations.\n"
+                + "3. local_info_list — Query your LOCAL private info: sensitive data like delivery addresses, phone numbers, contacts stored ONLY on this device.\n"
+                + "4. token_list — Query cached token metadata: symbol, decimals, icon URL, description for tokens previously fetched from chain. Use to look up token precision/decimals before performing token operations. Returns: TokenTypeInfo[] (type, alias, name, symbol, decimals, iconUrl).\n"
+                + "5. account_balance — Query an account's coin balance OR Paginated coin objects. Use balance=true for total amount, or coin={cursor,limit} to list individual coin objects. Supports multi-token via token_type parameter.\n"
+                + "6. local_names — Query local names by a list of addresses. For each address, returns the resolved account name (if exists) and local mark name (if exists). Returns: { account?, local_mark?, address }[].\n\n"
+                + "ONCHAIN (blockchain):\n"
+                + "7. onchain_personal_profile — Query any user's PUBLIC on-chain profile: social links, reputation (likes/dislikes), personal info records, voting history, referrer.\n"
+                + "8. onchain_objects — Batch query on-chain WOWOK objects by ID or name: supports Service, Machine, Order, Treasury, Reward, Arb, Personal, Contact, and more.\n"
+                + "9. onchain_received — Query objects (Payments, Tokens, NFTs) received by a specific object. Supports pagination and type filter.\n\n"
+                + "For dynamic table data queries (pagination, table items), use the 'onchain_table_data' tool.\n\n"
+                + "💡 Schema hint: Use schema_query with action='get' and name='query_toolkit' to retrieve the exact parameter schema with all query types and field definitions.",
+            inputSchema: WatchQueryOperationsSchema,
+            outputSchema: z.object({
+                result: z.unknown().describe("Query result — type depends on query_type. Local queries return arrays (MarkData[], AccountData[], InfoData[], TokenTypeInfo[]). account_balance returns { address, balance? | coin? }. Onchain queries return typed objects or undefined. onchain_received returns ReceivedBalance | ReceivedNormal[]."),
+                semantic: z.unknown().optional().describe("Business semantic summary for the query operation"),
+            }),
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            _meta: createToolMeta("query", ["watch", "query", "on-chain", "local", "events", "objects", "tokens", "balance", "profile"]),
+        },
+    },
+    {
+        name: "onchain_table_data",
+        handler: handleOnchainTableData,
+        config: {
+            title: "📊 Watch WoWok On-chain Table Data Query",
+            description: "Query dynamic table data of on-chain objects — supports paginated table queries and specific table item lookups. Each table item belongs to a parent object type and has a specific meaning:\n\n"
+                + "1. onchain_table — Paginated query of ANY object's dynamic fields table (Parent: any object). Returns all entries with keys, types, and object IDs. Use to explore all sub-items of an object.\n"
+                + "2. onchain_table_item_repository_data — Query a record from a Repository's on-chain key-value database (Parent: Repository). Key: name + entity (address or number). Returns the stored data record with typed value.\n"
+                + "3. onchain_table_item_permission_perm — Query a permission entry from a Permission object's access control table (Parent: Permission). Key: user address or Guard ID. Returns the permission list (perm[]) granted to that user/guard.\n"
+                + "4. onchain_table_item_entity_registrar — Query an entity's registration record from the GLOBAL EntityRegistrar (Parent: system EntityRegistrar). Key: user address. Returns registration info: description, referrer, records, mark_object.\n"
+                + "5. onchain_table_item_entity_linker — Query community votes/endorsements for an entity from the GLOBAL EntityLinker (Parent: system EntityLinker). Key: entity address. Returns vote records (likes/dislikes) showing community trust.\n"
+                + "6. onchain_table_item_reward_record — Query a reward claim record from a Reward object's distribution table (Parent: Reward). Key: recipient address. Returns claim history: guard used, total claimed, per-claim details.\n"
+                + "7. onchain_table_item_demand_presenter — Query a demand submission from a Demand object's presenter table (Parent: Demand). Key: presenter address. Returns submission details: recommendation, service, feedback, acceptance score.\n"
+                + "8. onchain_table_item_treasury_history — Query a payment record from a Treasury's history table (Parent: Treasury). Key: payment ID (address). Returns payment details: operation type, signer, amount, external guard.\n"
+                + "9. onchain_table_item_machine_node — Query a workflow node definition from a Machine object's node table (Parent: Machine). Key: node name (string). Returns node configuration: pairs, forwards, guards, thresholds.\n"
+                + "10. onchain_table_item_progress_history — Query a progress step record from a Progress object's history table (Parent: Progress). Key: sequence number (u64). Returns step details: node, next_node, session state, time.\n"
+                + "11. onchain_table_item_address_mark — Query a PUBLIC on-chain name/tag mark from an AddressMark object's table (Parent: AddressMark). Key: address. Returns public labels: entity, name, tags[]. Unlike local marks, these are published on-chain.\n"
+                + "12. onchain_table_item_generic — Query a generic table item from ANY object's dynamic fields (Parent: any object). Supports arbitrary key types (address, u64, string, object ID, etc.). Use for custom objects and general-purpose table lookups. Returns: ObjectBase | undefined.\n\n"
+                + "💡 Schema hint: Use schema_query with action='get' and name='onchain_table_data' to retrieve the exact parameter schema with all table item types and field definitions.",
+            inputSchema: OnchainTableDataSchema,
+            outputSchema: OnchainTableDataResultSchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            _meta: createToolMeta("table query", ["on-chain", "table", "dynamic fields", "pagination", "repository", "permission", "reward", "demand", "treasury", "machine", "progress"]),
+        },
+    },
+    {
+        name: "onchain_events",
+        handler: handleOnchainEvents,
+        config: {
+            title: "📅 Watch WoWok On-chain Events",
+            description: "Watch on-chain WoWok events by type. Supports arbitration events, new order events, progress events, demand presentation events, demand feedback events, and new entity registration events. Use pagination cursor for fetching large result sets.\n\n💡 Schema hint: Use schema_query with action='get' and name='onchain_events' to retrieve the exact parameter schema with all event types and field definitions.",
+            inputSchema: OnchainEventsInputSchema,
+            outputSchema: OnchainEventsResultSchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            _meta: createToolMeta("watch wowook events", ["events", "on-chain", "arbitration", "order", "progress", "demand", "entity"]),
+        },
+    },
+    {
+        name: "wowok_buildin_info",
+        handler: handleWowokInfo,
+        config: {
+            title: "ℹ️ WoWok Build-in Information",
+            description: "Query WoWok protocol information: 'constants', 'built-in permissions', 'guard instructions', 'current network', 'value types', or 'mainnet bridge tokens'. For 'mainnet bridge tokens': returns cross-chain bridge tokens (ETH, WETH, WBTC, USDC, USDT) with each token's symbol, WOW-side type tag (wowTypeTag), EVM address, decimals, and description. The wowTypeTag (format {address}::{module}::{struct}) can be used directly as the `type_parameter` of Service / Treasury / Reward / Allocation objects to set their payment token — e.g. use USDT's wowTypeTag to create a Service that accepts USDT payments.",
+            inputSchema: ProtocolInfoQuerySchema,
+            outputSchema: ProtocolInfoResultSchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            _meta: createToolMeta("WoWok info", ["build-in", "constants", "permissions", "guard", "network", "value-types", "bridge-tokens"]),
+        },
+    },
+    {
+        name: "schema_query",
+        handler: handleSchemaQuery,
+        config: {
+            title: "📋 Schema Query",
+            description: "Look up JSON Schemas for WoWok MCP tools and on-chain operations. " +
+                "This is the authoritative reference for exact parameter structures, types, and required fields. " +
+                "Always check the schema before calling an unfamiliar tool.\n\n" +
+                "Actions:\n" +
+                "  'list' - Show all available schemas (tools + on-chain operations). Start here to discover what exists.\n" +
+                "  'get' - Fetch the full input JSON Schema by name (e.g. 'onchain_operations'). Use with the 'name' param.\n" +
+                "  'get_output' - Fetch the output JSON Schema of a tool by name (e.g. 'onchain_operations'). Use with the 'name' param. Use this to understand a tool's return value structure.\n" +
+                "  'search' - Find schemas by keyword, matching name/title/description. Use with the 'query' param.\n" +
+                "  'list_operations' - Show only on-chain operation schemas (prefixed 'onchain_operations_'). Narrower than 'list'.",
+            inputSchema: SchemaQueryInputSchema,
+            outputSchema: SchemaQueryOutputSchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            _meta: createToolMeta("schema", ["schema", "json-schema", "types", "structure", "validation", "reference"]),
+        },
+    },
+    {
+        name: "bridge_operation",
+        handler: handleBridgeOperations,
+        config: {
+            title: "🌉 Bridge - Cross-Chain Operations",
+            description: "🌉 Simplified cross-chain bridge between WOW and EVM (Ethereum mainnet). Only WOW mainnet provides cross-chain functionality.\n\n" +
+                "Key concepts (transparent to user):\n" +
+                "  • Global single activeEvmAccount - auto-generated on first use, holds cross-chain assets.\n" +
+                "  • WOW→EVM: assets auto-claim to activeEvmAccount; optional withdrawTo transfers to a final EVM address.\n" +
+                "  • EVM→WOW: deposit from activeEvmAccount (balance checked first), assets arrive at the WOW account.\n\n" +
+                "Operations (operation_type):\n" +
+                "  • cross_chain_wow_to_evm - WOW→EVM cross-chain (asset to activeEvmAccount or withdrawTo). [Requires WOW mainnet env]\n" +
+                "  • cross_chain_evm_to_wow - EVM→WOW cross-chain (from activeEvmAccount to WOW account). [Requires WOW mainnet env]\n" +
+                "  • withdraw - Withdraw from activeEvmAccount to another EVM address (non-cross-chain). [No env needed]\n" +
+                "  • query_active_evm_account - Query activeEvmAccount address + balances (per chain or all). [No env needed]\n" +
+                "  • query_supported_evm_chains - List supported EVM chains (enum/description/chainId/RPC health). [No env needed]\n" +
+                "  • query_supported_tokens - List supported Bridge tokens per chain (WOW/EVM contract addresses, decimals, description). [No env needed]\n" +
+                "  • query_transfer_list - Query transfer history list with optional filters (status/direction/token/limit). [No env needed]\n" +
+                "  • query_transfer_status - Query single transfer detail by transferId. [No env needed]\n" +
+                "  • manage_evm_rpc - Manage EVM RPC endpoints (list/add/remove/set/ping) to handle 429 rate limits. [No env needed]\n\n" +
+                "Token support follows SDK config (ETH/WETH/WBTC/USDC/USDT). WOW account names are supported (resolved via LocalMark).\n" +
+                "NOTE: Use schema_query (name='bridge_operation') to retrieve the exact JSON Schema with all field definitions before calling.",
+            inputSchema: BridgeOperationsSchema,
+            outputSchema: BridgeCallOutputSchema,
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+            _meta: createToolMeta("operation", ["bridge", "cross-chain", "evm", "ethereum", "wow", "transfer", "rpc"]),
+        },
+    },
+    {
+        name: "project_operation",
+        handler: handleProjectOperation,
+        config: {
+            title: "🗂️ Project - Namespace & Object Graph",
+            description: "Phase 2 project namespace service — manage and query the local object dependency graph (DAG) " +
+                "built on top of local_mark tags. No on-chain writes; all data comes from local marks tagged " +
+                "`project:<prefix>` (auto-injected by the ProjectService when enabled, default ON).\n\n" +
+                "Actions:\n" +
+                "  • list_projects — List all discovered projects (grouped by `project:<prefix>` tag) with object counts.\n" +
+                "  • list_objects — List objects in a project (requires `project` param).\n" +
+                "  • shareable — List objects tagged `shareable:true` (cross-project reusable: common Permission, 3rd-party Arb).\n" +
+                "  • dependencies — Trace forward dependencies of an object (BFS transitive closure + dangling refs).\n" +
+                "  • referenced_by — Reverse query: who references this object?\n" +
+                "  • pre_publish_check — Pre-publish sanity check for a service (dangling deps + cycles).\n" +
+                "  • cross_project_refs — Find edges that cross project boundaries.\n" +
+                "  • graph_stats — Graph statistics (node/edge counts, cycles, dangling deps).\n" +
+                "  • save_graph — Save the in-memory graph to ~/.wowok/project-graph.json (persist across sessions).\n" +
+                "  • load_graph — Load the graph from file (restore after restart).\n\n" +
+                "NOTE: The graph is in-memory by default. Use save_graph/load_graph for cross-session persistence " +
+                "(or toggle graph_persist via config_operation for auto-save). " +
+                "list_projects/shareable always query local_mark (persistent).\n\n" +
+                "💡 Schema hint: Use schema_query with action='get' and name='project_operation' to retrieve the exact parameter schema with all actions and field definitions.",
+            inputSchema: ProjectOperationInputSchema,
+            outputSchema: ProjectOperationOutputSchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            _meta: createToolMeta("project", ["project", "namespace", "graph", "dag", "dependency", "reference", "organization"]),
+        },
+    },
+    {
+        name: "config_operation",
+        handler: handleConfigOperation,
+        config: {
+            title: "⚙️ Config - Runtime Service Toggles",
+            description: "Phase 2 runtime configuration — toggle Phase 2 services on/off at runtime WITHOUT restarting the MCP server. " +
+                "This is the session-level switch mechanism: AI can toggle based on user conversation context, or users can " +
+                "directly control which Phase 2 features are active.\n\n" +
+                "Actions:\n" +
+                "  • list — List all services with current state + reminders.\n" +
+                "  • toggle — Toggle a service on/off (requires `service` param). Returns reminder text.\n" +
+                "  • enable — Enable a service (requires `service` param).\n" +
+                "  • disable — Disable a service (requires `service` param).\n" +
+                "  • reset — Reset a service to its default (requires `service` param).\n" +
+                "  • info — Get detailed info about a service (requires `service` param).\n\n" +
+                "Services:\n" +
+                "  • confirm_gate — Safety Confirmation Gate (default ON)\n" +
+                "  • project_service — Project Namespace + Dependency Graph (default ON)\n" +
+                "  • harness — L4 Verify/Recover Loop (default OFF)\n" +
+                "  • graph_persist — Graph Persistence to File (default OFF)\n" +
+                "  • semantic_rich — Semantic Layer Enrichment Reminder (default ON)\n" +
+                "  • experience_layer — Real-time Experience Layer (Phase 2 Topic 2, default ON)\n" +
+                "  • customer_intelligence — Buyer Intelligence / Risk & Preference Alerts (Phase 3 C-3, default ON)\n" +
+                "  • order_monitor — In-progress Order Monitoring (Phase 3 C-3.2, default OFF)\n" +
+                "  • industry_evolution — Industry Specialization Evolution Flywheel (Phase 4, default ON)\n\n" +
+                "NOTE: Toggles persist for the MCP process lifetime. Set WOWOK_RUNTIME_CONFIG_PERSIST=1 " +
+                "to persist across sessions to ~/.wowok/runtime-config.json.\n\n" +
+                "💡 Schema hint: Use schema_query with action='get' and name='config_operation' to retrieve the exact parameter schema with all actions and field definitions.",
+            inputSchema: ConfigOperationInputSchema,
+            outputSchema: ConfigOperationOutputSchema,
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            _meta: createToolMeta("config", ["config", "toggle", "service", "runtime", "switch", "enable", "disable"]),
+        },
+    },
+    {
+        name: "trust_score",
+        handler: handleTrustScore,
+        config: {
+            title: "🛡️ Trust Score - Service Risk & Trust Assessment",
+            description: "Proactively query the trust score and risk assessment of a Service object. " +
+                "This is the standalone query form of the trust_score field that is otherwise only " +
+                "passively injected into onchain_operations semantic output.\n\n" +
+                "Returns:\n" +
+                "  • trust_score (0-100, 5 dimensions: arbitration/reviews/fulfillment/fund_safety/transparency)\n" +
+                "  • risk_score (4 dimensions: workflow/fund/trust/behavior, 100-point) when depth >= 'evaluate'\n" +
+                "  • info_puzzle completeness + gaps summary\n" +
+                "  • service_basics snapshot (published/paused/sales/guards/arbitrations)\n\n" +
+                "Use this tool when the user asks 'is this service trustworthy?', 'should I buy from this merchant?', " +
+                "'what's the risk of ordering this service?', or any explicit trust/risk inquiry about a Service.\n\n" +
+                "Parameters:\n" +
+                "  • service (required) — Service object ID or local_mark name.\n" +
+                "  • order_amount (optional) — Order amount in smallest token unit (e.g. 2000000000 for 2 WOW). " +
+                "Defaults to the service's first active sale price.\n" +
+                "  • depth (optional, default 'evaluate') — 'browse' (trust score only), 'evaluate' (+ risk assessment), " +
+                "'preorder' (most thorough, includes market context dimension).\n\n" +
+                "💡 Schema hint: Use schema_query with action='get' and name='trust_score' to retrieve the exact parameter schema.",
+            inputSchema: TrustScoreInputSchema,
+            outputSchema: TrustScoreOutputSchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            _meta: createToolMeta("trust", ["trust", "score", "risk", "service", "merchant", "reputation", "safety", "evaluate"]),
+        },
+    },
+];
+export const TOOL_REGISTRY_MAP = new Map(TOOL_REGISTRY.map(t => [t.name, t]));
+export async function dispatchToolCall(name, args, options) {
+    const entry = TOOL_REGISTRY_MAP.get(name);
+    if (!entry) {
+        throw new Error(`Unknown tool: ${name}. Available: ${TOOL_REGISTRY.map(t => t.name).join(", ")}`);
+    }
+    if (entry.applyRules && !options?.skipRules) {
+        const ruleResult = entry.applyRules(args);
+        if (ruleResult)
+            return ruleResult;
+    }
+    const timeoutMs = entry.timeoutMs ?? 60000;
+    const wrapped = wrapHandlerWithErrorShape(entry.handler, timeoutMs, name, entry.errorShapeBuilder);
+    return wrapped(args);
+}
+function zodToJsonSchemaSafe(schema, name) {
+    try {
+        const jsonSchema = zodToJsonSchema(schema, {
+            name,
+            $refStrategy: "root",
+            basePath: ["#"],
+            effectStrategy: "input",
+        });
+        if (jsonSchema && typeof jsonSchema === "object" && !Array.isArray(jsonSchema)) {
+            const { $schema: _omit, ...rest } = jsonSchema;
+            return rest;
+        }
+        return { type: "object" };
+    }
+    catch {
+        return { type: "object", additionalProperties: true };
+    }
+}
+function resolveSchemaRefs(schema) {
+    const STRIP_KEYS = new Set(["definitions", "$schema", "$id"]);
+    function navigatePointer(path) {
+        if (!path.startsWith("#/"))
+            return null;
+        const parts = path.slice(2).split("/");
+        let target = schema;
+        for (const part of parts) {
+            if (target == null || typeof target !== "object" || Array.isArray(target)) {
+                return null;
+            }
+            target = target[part];
+        }
+        return target;
+    }
+    function resolveNode(node, visiting) {
+        if (!node || typeof node !== "object") {
+            return node;
+        }
+        if (Array.isArray(node)) {
+            return node.map((item) => resolveNode(item, visiting));
+        }
+        const obj = node;
+        if (typeof obj.$ref === "string") {
+            const ref = obj.$ref;
+            if (visiting.has(ref)) {
+                return { type: "object", additionalProperties: true };
+            }
+            const target = navigatePointer(ref);
+            if (target && typeof target === "object" && !Array.isArray(target)) {
+                const newVisiting = new Set(visiting);
+                newVisiting.add(ref);
+                const resolved = resolveNode(target, newVisiting);
+                const siblings = {};
+                for (const [k, v] of Object.entries(obj)) {
+                    if (k !== "$ref" && !STRIP_KEYS.has(k))
+                        siblings[k] = v;
+                }
+                return {
+                    ...resolved,
+                    ...siblings,
+                };
+            }
+            return { type: "object", additionalProperties: true };
+        }
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) {
+            if (STRIP_KEYS.has(k))
+                continue;
+            result[k] = resolveNode(v, visiting);
+        }
+        return result;
+    }
+    return resolveNode(schema, new Set());
+}
+function loadPreGeneratedSchema(toolName) {
+    const cached = preGeneratedSchemaCache.get(toolName);
+    if (cached)
+        return cached;
+    for (const dir of SCHEMA_DIR_CANDIDATES) {
+        try {
+            const schemaPath = join(dir, `${toolName}.schema.json`);
+            const raw = readFileSync(schemaPath, "utf-8");
+            const schema = JSON.parse(raw);
+            const resolved = resolveSchemaRefs(schema);
+            preGeneratedSchemaCache.set(toolName, resolved);
+            return resolved;
+        }
+        catch {
+        }
+    }
+    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,
+        };
+    });
+}
+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));
+    }
+}

package/dist/tools/rules-hook.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDispatchResult } from "./types.js";
+export declare function applyOnchainRules(args: any): ToolDispatchResult | null;

package/dist/tools/rules-hook.js

@@ -0,0 +1,22 @@
+import { OnchainOperationsSchema, strictParse, getEnvConfig, } from "../schema/index.js";
+import { buildPendingConfirmation, buildConstraintError } from "./shared.js";
+import { validateOperation, hasBlockingViolations, } from "../knowledge/index.js";
+export function applyOnchainRules(args) {
+    let validated;
+    try {
+        validated = strictParse(OnchainOperationsSchema, args, "onchain_operations input");
+    }
+    catch {
+        return null;
+    }
+    const env = getEnvConfig(validated.env);
+    const gateResult = buildPendingConfirmation(validated.operation_type, validated.data, env);
+    if (gateResult.structuredContent) {
+        return gateResult;
+    }
+    const constraintViolations = validateOperation(validated.operation_type, validated.data);
+    if (hasBlockingViolations(constraintViolations)) {
+        return buildConstraintError(validated.operation_type, constraintViolations);
+    }
+    return null;
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,29 @@
+import { validateOperation, hasBlockingViolations, getWarningViolations, type ConstraintViolation } from "../knowledge/index.js";
+import { classifyError, type SemanticContext } from "../schema/call/semantic.js";
+export declare function withHarness(base: SemanticContext, operation: string, intent: string): SemanticContext;
+export interface LocalHandlerConfig {
+    schema: import("zod").ZodTypeAny;
+    operationFn: (input: any) => Promise<any>;
+    parseLabel: string;
+    buildContext: (validated: any) => SemanticContext;
+}
+export declare function wrapLocalHandler(config: LocalHandlerConfig): (args: any) => Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        result: any;
+        semantic: any;
+    };
+}>;
+export declare function buildPendingConfirmation(operation_type: string, data: any, env: any): {
+    content: any[];
+    structuredContent: any;
+};
+export declare function buildConstraintError(operation_type: string, violations: ConstraintViolation[]): {
+    content: any[];
+    structuredContent: any;
+};
+export declare function buildClassifiedErrorResult(base: Record<string, any>, error: string, classified: ReturnType<typeof classifyError>): Record<string, any>;
+export { validateOperation, hasBlockingViolations, getWarningViolations, type ConstraintViolation, };