safehands-pharos 1.4.0 → 1.5.0

package/dist/demo.js

@@ -1,172 +1,172 @@
-// ─── SafeHands Deterministic Hackathon Demo ────────────────────────────
-// Non-destructive demo for judges and reviewers. It uses offline/sample-safe
-// paths and a local HTTP server only when explicitly allowed in-process.
-// No real transaction is broadcast.
-// ────────────────────────────────────────────────────────────────────────
-import express from "express";
-import { handleSafeHandsWalletHealth } from "./tools/safehandsWalletHealth.js";
-import { handleSafeHandsPreflightCheck } from "./tools/safehandsPreflightCheck.js";
-import { handleTokenRegistryStatus } from "./tools/tokenRegistryStatus.js";
-import { handleSafeHandsX402Preflight } from "./tools/safehandsX402Preflight.js";
-import { handleX402PayAndFetch } from "./tools/x402PayAndFetch.js";
-import { handleSendPayment } from "./tools/sendPayment.js";
-import { handleExplainRisk } from "./tools/explainRisk.js";
-import { CHAIN_ID, PHAROS_ENVIRONMENT, USDC_ADDRESS } from "./lib/constants.js";
-const RECIPIENT = "0x0000000000000000000000000000000000000001";
-function section(title) {
-    console.log(`\n${"═".repeat(78)}`);
-    console.log(`  ${title}`);
-    console.log("═".repeat(78));
-}
-function print(label, value) {
-    console.log(`\n${label}`);
-    console.log(JSON.stringify(value, null, 2));
-}
-function setEnv(key, value) {
-    const previous = process.env[key];
-    if (value === undefined)
-        delete process.env[key];
-    else
-        process.env[key] = value;
-    return () => {
-        if (previous === undefined)
-            delete process.env[key];
-        else
-            process.env[key] = previous;
-    };
-}
-async function withLocalX402DemoServer(handler) {
-    const app = express();
-    app.get("/supported", (_req, res) => {
-        res.json({
-            ok: true,
-            demo: true,
-            paymentRequired: false,
-            endpoints: ["/supported", "/paid"],
-            network: `eip155:${CHAIN_ID}`,
-        });
-    });
-    app.get("/paid", (_req, res) => {
-        res.status(402).json({
-            error: "Payment Required",
-            demo: true,
-            price: "0.001",
-            asset: USDC_ADDRESS,
-            network: `eip155:${CHAIN_ID}`,
-        });
-    });
-    const server = await new Promise((resolve) => {
-        const instance = app.listen(0, "127.0.0.1", () => resolve(instance));
-    });
-    try {
-        const address = server.address();
-        if (!address || typeof address === "string")
-            throw new Error("Failed to open local demo server");
-        return await handler(`http://127.0.0.1:${address.port}`);
-    }
-    finally {
-        if ("closeAllConnections" in server)
-            server.closeAllConnections();
-        await new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
-    }
-}
-export async function runDemo() {
-    const restoreWalletMode = setEnv("WALLET_MODE", process.env.WALLET_MODE || "none");
-    const restoreWrite = setEnv("WRITE_TOOLS_ENABLED", "false");
-    const restorePrivateKey = setEnv("PRIVATE_KEY", undefined);
-    const restoreX402Signer = setEnv("X402_SIGNER_PRIVATE_KEY", undefined);
-    try {
-        console.log("\n🛡️  SafeHands-Pharos Deterministic Demo");
-        console.log(`   Environment: ${PHAROS_ENVIRONMENT}`);
-        console.log(`   Chain ID: ${CHAIN_ID}`);
-        console.log("   Mode: non-destructive demo, no real transactions broadcast");
-        section("1. Wallet Health");
-        print("safehands_wallet_health", await handleSafeHandsWalletHealth({}));
-        section("2. Safe Payment Preflight: ALLOW");
-        print("safehands_preflight_check", await handleSafeHandsPreflightCheck({
-            actionType: "send_payment",
-            chainId: CHAIN_ID,
-            isMainnet: false,
-            amount: "0.001",
-            amountUnit: "PHRS",
-            recipient: RECIPIENT,
-        }));
-        section("3. Unlimited Approval Preflight: BLOCK");
-        const blockedApproval = await handleSafeHandsPreflightCheck({
-            actionType: "approve_token",
-            chainId: CHAIN_ID,
-            isMainnet: false,
-            approvalAmount: "max",
-            spender: RECIPIENT,
-        });
-        print("safehands_preflight_check", blockedApproval);
-        section("4. Token Registry Status");
-        print("token_registry_status", await handleTokenRegistryStatus({ tokenAddress: USDC_ADDRESS }));
-        section("5. x402 Preflight Without Private Key");
-        await withLocalX402DemoServer(async (baseUrl) => {
-            const restoreLocal = setEnv("ALLOW_LOCAL_X402_FETCH", "true");
-            try {
-                print("safehands_x402_preflight", await handleSafeHandsX402Preflight({
-                    url: `${baseUrl}/paid`,
-                    paymentAmountUsdc: "0.001",
-                    probeEndpoint: false,
-                }));
-            }
-            finally {
-                restoreLocal();
-            }
-        });
-        section("6. x402 /supported Free Endpoint Without Private Key");
-        await withLocalX402DemoServer(async (baseUrl) => {
-            const restoreLocal = setEnv("ALLOW_LOCAL_X402_FETCH", "true");
-            try {
-                print("x402_pay_and_fetch free endpoint", await handleX402PayAndFetch({ url: `${baseUrl}/supported` }));
-            }
-            finally {
-                restoreLocal();
-            }
-        });
-        section("7. x402 Paid Endpoint Without Signer");
-        await withLocalX402DemoServer(async (baseUrl) => {
-            const restoreLocal = setEnv("ALLOW_LOCAL_X402_FETCH", "true");
-            try {
-                print("x402_pay_and_fetch paid endpoint", await handleX402PayAndFetch({ url: `${baseUrl}/paid`, maxPaymentUsdc: "0.001" }));
-            }
-            finally {
-                restoreLocal();
-            }
-        });
-        section("8. SSRF_BLOCKED");
-        const restoreLocalBlocked = setEnv("ALLOW_LOCAL_X402_FETCH", undefined);
-        try {
-            print("safehands_x402_preflight localhost blocked", await handleSafeHandsX402Preflight({ url: "http://127.0.0.1:4021/supported" }));
-        }
-        finally {
-            restoreLocalBlocked();
-        }
-        section("9. WRITE_TOOLS_DISABLED");
-        print("send_payment guarded", await handleSendPayment({ toAddress: RECIPIENT, amount: "0.001" }));
-        section("10. Human-Readable Risk Explanation");
-        print("explain_risk", await handleExplainRisk({
-            decision: "BLOCK",
-            riskLevel: "HIGH",
-            reasons: ["Unlimited approval requested"],
-            requiredActions: ["Use a limited approval amount before approving a spender"],
-        }));
-        section("Demo Complete");
-        console.log("SafeHands demonstrated wallet health, ALLOW/BLOCK policy, token registry, x402 safety, SSRF blocking, write-tool guardrails, and explainable risk output.");
-    }
-    finally {
-        restoreWalletMode();
-        restoreWrite();
-        restorePrivateKey();
-        restoreX402Signer();
-    }
-}
-if (import.meta.url === `file://${process.argv[1]}`) {
-    runDemo().catch((err) => {
-        console.error("Demo error:", err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    });
-}
+// ─── SafeHands Deterministic Hackathon Demo ────────────────────────────
+// Non-destructive demo for judges and reviewers. It uses offline/sample-safe
+// paths and a local HTTP server only when explicitly allowed in-process.
+// No real transaction is broadcast.
+// ────────────────────────────────────────────────────────────────────────
+import express from "express";
+import { handleSafeHandsWalletHealth } from "./tools/safehandsWalletHealth.js";
+import { handleSafeHandsPreflightCheck } from "./tools/safehandsPreflightCheck.js";
+import { handleTokenRegistryStatus } from "./tools/tokenRegistryStatus.js";
+import { handleSafeHandsX402Preflight } from "./tools/safehandsX402Preflight.js";
+import { handleX402PayAndFetch } from "./tools/x402PayAndFetch.js";
+import { handleSendPayment } from "./tools/sendPayment.js";
+import { handleExplainRisk } from "./tools/explainRisk.js";
+import { CHAIN_ID, PHAROS_ENVIRONMENT, USDC_ADDRESS } from "./lib/constants.js";
+const RECIPIENT = "0x0000000000000000000000000000000000000001";
+function section(title) {
+    console.log(`\n${"═".repeat(78)}`);
+    console.log(`  ${title}`);
+    console.log("═".repeat(78));
+}
+function print(label, value) {
+    console.log(`\n${label}`);
+    console.log(JSON.stringify(value, null, 2));
+}
+function setEnv(key, value) {
+    const previous = process.env[key];
+    if (value === undefined)
+        delete process.env[key];
+    else
+        process.env[key] = value;
+    return () => {
+        if (previous === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = previous;
+    };
+}
+async function withLocalX402DemoServer(handler) {
+    const app = express();
+    app.get("/supported", (_req, res) => {
+        res.json({
+            ok: true,
+            demo: true,
+            paymentRequired: false,
+            endpoints: ["/supported", "/paid"],
+            network: `eip155:${CHAIN_ID}`,
+        });
+    });
+    app.get("/paid", (_req, res) => {
+        res.status(402).json({
+            error: "Payment Required",
+            demo: true,
+            price: "0.001",
+            asset: USDC_ADDRESS,
+            network: `eip155:${CHAIN_ID}`,
+        });
+    });
+    const server = await new Promise((resolve) => {
+        const instance = app.listen(0, "127.0.0.1", () => resolve(instance));
+    });
+    try {
+        const address = server.address();
+        if (!address || typeof address === "string")
+            throw new Error("Failed to open local demo server");
+        return await handler(`http://127.0.0.1:${address.port}`);
+    }
+    finally {
+        if ("closeAllConnections" in server)
+            server.closeAllConnections();
+        await new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
+    }
+}
+export async function runDemo() {
+    const restoreWalletMode = setEnv("WALLET_MODE", process.env.WALLET_MODE || "none");
+    const restoreWrite = setEnv("WRITE_TOOLS_ENABLED", "false");
+    const restorePrivateKey = setEnv("PRIVATE_KEY", undefined);
+    const restoreX402Signer = setEnv("X402_SIGNER_PRIVATE_KEY", undefined);
+    try {
+        console.log("\n🛡️  SafeHands-Pharos Deterministic Demo");
+        console.log(`   Environment: ${PHAROS_ENVIRONMENT}`);
+        console.log(`   Chain ID: ${CHAIN_ID}`);
+        console.log("   Mode: non-destructive demo, no real transactions broadcast");
+        section("1. Wallet Health");
+        print("safehands_wallet_health", await handleSafeHandsWalletHealth({}));
+        section("2. Safe Payment Preflight: ALLOW");
+        print("safehands_preflight_check", await handleSafeHandsPreflightCheck({
+            actionType: "send_payment",
+            chainId: CHAIN_ID,
+            isMainnet: false,
+            amount: "0.001",
+            amountUnit: "PHRS",
+            recipient: RECIPIENT,
+        }));
+        section("3. Unlimited Approval Preflight: BLOCK");
+        const blockedApproval = await handleSafeHandsPreflightCheck({
+            actionType: "approve_token",
+            chainId: CHAIN_ID,
+            isMainnet: false,
+            approvalAmount: "max",
+            spender: RECIPIENT,
+        });
+        print("safehands_preflight_check", blockedApproval);
+        section("4. Token Registry Status");
+        print("token_registry_status", await handleTokenRegistryStatus({ tokenAddress: USDC_ADDRESS }));
+        section("5. x402 Preflight Without Private Key");
+        await withLocalX402DemoServer(async (baseUrl) => {
+            const restoreLocal = setEnv("ALLOW_LOCAL_X402_FETCH", "true");
+            try {
+                print("safehands_x402_preflight", await handleSafeHandsX402Preflight({
+                    url: `${baseUrl}/paid`,
+                    paymentAmountUsdc: "0.001",
+                    probeEndpoint: false,
+                }));
+            }
+            finally {
+                restoreLocal();
+            }
+        });
+        section("6. x402 /supported Free Endpoint Without Private Key");
+        await withLocalX402DemoServer(async (baseUrl) => {
+            const restoreLocal = setEnv("ALLOW_LOCAL_X402_FETCH", "true");
+            try {
+                print("x402_pay_and_fetch free endpoint", await handleX402PayAndFetch({ url: `${baseUrl}/supported` }));
+            }
+            finally {
+                restoreLocal();
+            }
+        });
+        section("7. x402 Paid Endpoint Without Signer");
+        await withLocalX402DemoServer(async (baseUrl) => {
+            const restoreLocal = setEnv("ALLOW_LOCAL_X402_FETCH", "true");
+            try {
+                print("x402_pay_and_fetch paid endpoint", await handleX402PayAndFetch({ url: `${baseUrl}/paid`, maxPaymentUsdc: "0.001" }));
+            }
+            finally {
+                restoreLocal();
+            }
+        });
+        section("8. SSRF_BLOCKED");
+        const restoreLocalBlocked = setEnv("ALLOW_LOCAL_X402_FETCH", undefined);
+        try {
+            print("safehands_x402_preflight localhost blocked", await handleSafeHandsX402Preflight({ url: "http://127.0.0.1:4021/supported" }));
+        }
+        finally {
+            restoreLocalBlocked();
+        }
+        section("9. WRITE_TOOLS_DISABLED");
+        print("send_payment guarded", await handleSendPayment({ toAddress: RECIPIENT, amount: "0.001" }));
+        section("10. Human-Readable Risk Explanation");
+        print("explain_risk", await handleExplainRisk({
+            decision: "BLOCK",
+            riskLevel: "HIGH",
+            reasons: ["Unlimited approval requested"],
+            requiredActions: ["Use a limited approval amount before approving a spender"],
+        }));
+        section("Demo Complete");
+        console.log("SafeHands demonstrated wallet health, ALLOW/BLOCK policy, token registry, x402 safety, SSRF blocking, write-tool guardrails, and explainable risk output.");
+    }
+    finally {
+        restoreWalletMode();
+        restoreWrite();
+        restorePrivateKey();
+        restoreX402Signer();
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runDemo().catch((err) => {
+        console.error("Demo error:", err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}
 //# sourceMappingURL=demo.js.map

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
-export {};
+#!/usr/bin/env node
+import "./lib/envLoader.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAMA,OAAO,oBAAoB,CAAC"}

package/dist/index.js

@@ -2,6 +2,11 @@
 // ─── SafeHands MCP Server ──────────────────────────────────────────────
 // Entry point — registers 27 tools (17 legacy/core + 3 managed wallet + 7 SafeHands guardrail tools) and starts the MCP server.
 // ────────────────────────────────────────────────────────────────────────
+// Must be first import — loads .env before any module reads process.env at init time
+import "./lib/envLoader.js";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const PKG_VERSION = require("../package.json").version;
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { assessRiskSchema, handleAssessRisk } from "./tools/assessRisk.js";
@@ -129,18 +134,19 @@ if (process.argv[2] === "init") {
     process.exit(0);
 }
 // ─── Deterministic Demo CLI ───────────────────────────────────────────
-if (process.argv.includes("--demo")) {
+const isDemoMode = process.argv.includes("--demo");
+if (isDemoMode) {
     await runDemo();
-    // Brief delay allows libuv handles (express sockets) to close cleanly on Windows
-    setTimeout(() => process.exit(0), 100);
-    // Wait indefinitely so the script doesn't continue down to start the MCP server
-    await new Promise(() => { });
+    // Set exit code and let the event loop drain naturally.
+    // Avoids Windows libuv UV_HANDLE_CLOSING assertion that occurs with process.exit() while
+    // async handles (express close, viem HTTP keep-alive) are still winding down.
+    process.exitCode = 0;
 }
 // ─── CLI Help ──────────────────────────────────────────────────────────
 if (process.argv.includes("--help") || process.argv.includes("-h")) {
     process.stdout.write(`
 🛡️  SafeHands-Pharos — Transaction Safety Firewall for AI Agents
-   v1.3.0 | Pharos Atlantic Testnet | Chain ID 688689
+   v${PKG_VERSION} | Pharos Atlantic Testnet | Chain ID 688689
 
 USAGE
   npx safehands-pharos
@@ -221,63 +227,65 @@ DOCS
 `);
     process.exit(0);
 }
-// ─── Startup Validation ────────────────────────────────────────────────
-const walletMode = process.env.WALLET_MODE || "none";
-const hasManagedWalletMode = walletMode === "managed-testnet";
-const hasExplicitSignerMode = walletMode === "managed-testnet" || walletMode === "env";
-if (process.env.WRITE_TOOLS_ENABLED !== "true") {
-    console.error("⚠️  SafeHands — write tools are disabled by default.");
-    console.error("   Preflight, risk report, token registry, read-only, and x402 free endpoint checks remain available.");
-    console.error("   To execute trusted testnet actions, set WRITE_TOOLS_ENABLED=true and configure a signer via WALLET_MODE=managed-testnet or WALLET_MODE=env.");
-    console.error("");
-}
-else if (!hasExplicitSignerMode) {
-    console.error("⚠️  SafeHands — write tools enabled but no signer mode detected.");
-    console.error("   Use WALLET_MODE=managed-testnet with create_agent_wallet, or WALLET_MODE=env for testnet developer mode.");
-    console.error("");
-}
-// ─── Server Setup ──────────────────────────────────────────────────────
-const server = new McpServer({
-    name: "safehands",
-    version: "1.3.0",
-});
-// ─── Tool Registration ─────────────────────────────────────────────────
-server.tool("safehands_preflight_check", "Run a SafeHands policy preflight before an AI agent sends payment, approves tokens, swaps, publishes risk data, or pays x402.", safehandsPreflightCheckSchema.shape, async (params) => mcpText(await invokeTool(handleSafeHandsPreflightCheck, params, "safehands_preflight_check")));
-server.tool("safehands_safe_execute", "Guarded execution wrapper: preflight first, then execute only allowed and explicitly confirmed testnet actions.", safehandsSafeExecuteSchema.shape, async (params) => mcpText(await invokeTool(handleSafeHandsSafeExecute, params, "safehands_safe_execute")));
-server.tool("safehands_wallet_health", "Check whether an AI agent wallet is funded, signer-ready, and safe to use on Pharos Atlantic Testnet.", safehandsWalletHealthSchema.shape, async (params) => mcpText(await invokeTool(handleSafeHandsWalletHealth, params, "safehands_wallet_health")));
-server.tool("safehands_x402_preflight", "Check an x402 paid resource for URL safety, payment amount, token, signer, and testnet policy before signing.", safehandsX402PreflightSchema.shape, async (params) => mcpText(await invokeTool(handleSafeHandsX402Preflight, params, "safehands_x402_preflight")));
-server.tool("safehands_risk_report", "Generate an audit-friendly human-readable SafeHands risk report for an AI agent action.", safehandsRiskReportSchema.shape, async (params) => mcpText(await invokeTool(handleSafeHandsRiskReport, params, "safehands_risk_report")));
-server.tool("explain_risk", "Explain a SafeHands risk/policy decision in human-readable language.", explainRiskSchema.shape, async (params) => mcpText(await invokeTool(handleExplainRisk, params, "explain_risk")));
-server.tool("token_registry_status", "Classify exact token input as canonical testnet token, test liquidity token, custom, unknown, or invalid.", tokenRegistryStatusSchema.shape, async (params) => mcpText(await invokeTool(handleTokenRegistryStatus, params, "token_registry_status")));
-server.tool("assess_risk", "Evaluate the risk of a planned on-chain action (swap or transfer). Returns 0-100 risk score with 5-dimension breakdown.", assessRiskSchema.shape, async (params) => mcpText(await invokeTool(handleAssessRisk, params, "assess_risk")));
-server.tool("execute_swap", "Swap tokens via FaroSwap with built-in risk gate. Runs risk assessment first, blocks if score > 80.", executeSwapSchema.shape, async (params) => mcpText(await invokeTool(handleExecuteSwap, params, "execute_swap")));
-server.tool("send_payment", "Send native PHRS with pre-flight validation. Checks address, balance, and warns on high exposure.", sendPaymentSchema.shape, async (params) => mcpText(await invokeTool(handleSendPayment, params, "send_payment")));
-server.tool("simulate_transaction", "Dry run a swap or transfer via eth_call — no gas spent. Returns expected output and revert reasons.", simulateTransactionSchema.shape, async (params) => mcpText(await invokeTool(handleSimulateTransaction, params, "simulate_transaction")));
-server.tool("get_execution_history", "Pull on-chain transaction history for a wallet. Filters by swap, transfer, or all.", getExecutionHistorySchema.shape, async (params) => mcpText(await invokeTool(handleGetExecutionHistory, params, "get_execution_history")));
-server.tool("get_token_price", "Fetch real-time price of PHRS, USDC, or USDT on Pharos using DODO liquidity quotes.", getTokenPriceSchema.shape, async (params) => mcpText(await invokeTool(handleGetTokenPrice, params, "get_token_price")));
-server.tool("get_wallet_balance", "Return PHRS, USDC, USDT balances for a wallet with total USD estimate.", getWalletBalanceSchema.shape, async (params) => mcpText(await invokeTool(handleGetWalletBalance, params, "get_wallet_balance")));
-server.tool("check_allowance", "Check ERC-20 token allowance for DODO swap approval. Returns whether approval is needed.", checkAllowanceSchema.shape, async (params) => mcpText(await invokeTool(handleCheckAllowance, params, "check_allowance")));
-server.tool("get_transaction_status", "Check on-chain transaction status by hash. Returns status, block, gas, and explorer link.", getTransactionStatusSchema.shape, async (params) => mcpText(await invokeTool(handleGetTransactionStatus, params, "get_transaction_status")));
-server.tool("estimate_gas", "Estimate gas cost for a swap or transfer before executing. Returns cost in PHRS and USD.", estimateGasSchema.shape, async (params) => mcpText(await invokeTool(handleEstimateGas, params, "estimate_gas")));
-server.tool("publish_risk_score", "Run risk assessment and publish result to the on-chain RiskRegistry. Other agents can query it.", publishRiskScoreSchema.shape, async (params) => mcpText(await invokeTool(handlePublishRiskScore, params, "publish_risk_score")));
-server.tool("query_risk_registry", "Query the on-chain RiskRegistry for a wallet's published risk score. Read-only, no private key needed.", queryRiskRegistrySchema.shape, async (params) => mcpText(await invokeTool(handleQueryRiskRegistry, params, "query_risk_registry")));
-server.tool("approve_token", "Approve ERC-20 token spending for FaroSwap (DODO) router. Required before swapping non-native tokens.", approveTokenSchema.shape, async (params) => mcpText(await invokeTool(handleApproveToken, params, "approve_token")));
-server.tool("get_gas_price", "Get current gas price on Pharos with trend classification and cost estimates.", getGasPriceSchema.shape, async (params) => mcpText(await invokeTool(handleGetGasPrice, params, "get_gas_price")));
-server.tool("get_pool_info", "Fetch DODO liquidity pool info for a token pair on Pharos. Returns price ratio, impact, and fees.", getPoolInfoSchema.shape, async (params) => mcpText(await invokeTool(handleGetPoolInfo, params, "get_pool_info")));
-server.tool("check_token_security", "Check token contract security (honeypot, mintable, ownership privileges, tax) via GoPlus Security API.", checkTokenSecuritySchema.shape, async (params) => mcpText(await invokeTool(handleCheckTokenSecurity, params, "check_token_security")));
-server.tool("x402_pay_and_fetch", "Fetch resources from an HTTP x402 payment-gated server. Automatically handles HTTP 402 payment challenge.", x402PayAndFetchSchema.shape, async (params) => mcpText(await invokeTool(handleX402PayAndFetch, params, "x402_pay_and_fetch")));
-// ─── Managed Wallet Tools ──────────────────────────────────────────────
-server.tool("create_agent_wallet", "Create a new managed testnet agent wallet. Private key is encrypted and never returned. Fund the wallet with testnet PHRS before using write tools.", createAgentWalletSchema.shape, async (params) => mcpText(await invokeTool(handleCreateAgentWallet, params, "create_agent_wallet")));
-server.tool("get_agent_wallet", "Get public info (address, environment, chainId) for a managed agent wallet. Never returns private key.", getAgentWalletSchema.shape, async (params) => mcpText(await invokeTool(handleGetAgentWallet, params, "get_agent_wallet")));
-server.tool("get_agent_wallet_balance", "Get PHRS, USDC, and USDT balances for a managed agent wallet on Pharos testnet.", getAgentWalletBalanceSchema.shape, async (params) => mcpText(await invokeTool(handleGetAgentWalletBalance, params, "get_agent_wallet_balance")));
-// ─── Start Server ──────────────────────────────────────────────────────
-async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error("SafeHands-Pharos MCP Server v1.3.0 running on stdio");
-}
-main().catch((error) => {
-    console.error("Fatal error:", error);
-    process.exit(1);
-});
+if (!isDemoMode) {
+    // ─── Startup Validation ────────────────────────────────────────────────
+    const walletMode = process.env.WALLET_MODE || "none";
+    const hasManagedWalletMode = walletMode === "managed-testnet";
+    const hasExplicitSignerMode = walletMode === "managed-testnet" || walletMode === "env";
+    if (process.env.WRITE_TOOLS_ENABLED !== "true") {
+        console.error("⚠️  SafeHands — write tools are disabled by default.");
+        console.error("   Preflight, risk report, token registry, read-only, and x402 free endpoint checks remain available.");
+        console.error("   To execute trusted testnet actions, set WRITE_TOOLS_ENABLED=true and configure a signer via WALLET_MODE=managed-testnet or WALLET_MODE=env.");
+        console.error("");
+    }
+    else if (!hasExplicitSignerMode) {
+        console.error("⚠️  SafeHands — write tools enabled but no signer mode detected.");
+        console.error("   Use WALLET_MODE=managed-testnet with create_agent_wallet, or WALLET_MODE=env for testnet developer mode.");
+        console.error("");
+    }
+    // ─── Server Setup ──────────────────────────────────────────────────────
+    const server = new McpServer({
+        name: "safehands",
+        version: PKG_VERSION,
+    });
+    // ─── Tool Registration ─────────────────────────────────────────────────
+    server.tool("safehands_preflight_check", "Run a SafeHands policy preflight before an AI agent sends payment, approves tokens, swaps, publishes risk data, or pays x402.", safehandsPreflightCheckSchema.shape, async (params) => mcpText(await invokeTool(handleSafeHandsPreflightCheck, params, "safehands_preflight_check")));
+    server.tool("safehands_safe_execute", "Guarded execution wrapper: preflight first, then execute only allowed and explicitly confirmed testnet actions.", safehandsSafeExecuteSchema.shape, async (params) => mcpText(await invokeTool(handleSafeHandsSafeExecute, params, "safehands_safe_execute")));
+    server.tool("safehands_wallet_health", "Check whether an AI agent wallet is funded, signer-ready, and safe to use on Pharos Atlantic Testnet.", safehandsWalletHealthSchema.shape, async (params) => mcpText(await invokeTool(handleSafeHandsWalletHealth, params, "safehands_wallet_health")));
+    server.tool("safehands_x402_preflight", "Check an x402 paid resource for URL safety, payment amount, token, signer, and testnet policy before signing.", safehandsX402PreflightSchema.shape, async (params) => mcpText(await invokeTool(handleSafeHandsX402Preflight, params, "safehands_x402_preflight")));
+    server.tool("safehands_risk_report", "Generate an audit-friendly human-readable SafeHands risk report for an AI agent action.", safehandsRiskReportSchema.shape, async (params) => mcpText(await invokeTool(handleSafeHandsRiskReport, params, "safehands_risk_report")));
+    server.tool("explain_risk", "Explain a SafeHands risk/policy decision in human-readable language.", explainRiskSchema.shape, async (params) => mcpText(await invokeTool(handleExplainRisk, params, "explain_risk")));
+    server.tool("token_registry_status", "Classify exact token input as canonical testnet token, test liquidity token, custom, unknown, or invalid.", tokenRegistryStatusSchema.shape, async (params) => mcpText(await invokeTool(handleTokenRegistryStatus, params, "token_registry_status")));
+    server.tool("assess_risk", "Evaluate the risk of a planned on-chain action (swap or transfer). Returns 0-100 risk score with 5-dimension breakdown.", assessRiskSchema.shape, async (params) => mcpText(await invokeTool(handleAssessRisk, params, "assess_risk")));
+    server.tool("execute_swap", "Swap tokens via FaroSwap with built-in risk gate. Runs risk assessment first, blocks if score > 80.", executeSwapSchema.shape, async (params) => mcpText(await invokeTool(handleExecuteSwap, params, "execute_swap")));
+    server.tool("send_payment", "Send native PHRS with pre-flight validation. Checks address, balance, and warns on high exposure.", sendPaymentSchema.shape, async (params) => mcpText(await invokeTool(handleSendPayment, params, "send_payment")));
+    server.tool("simulate_transaction", "Dry run a swap or transfer via eth_call — no gas spent. Returns expected output and revert reasons.", simulateTransactionSchema.shape, async (params) => mcpText(await invokeTool(handleSimulateTransaction, params, "simulate_transaction")));
+    server.tool("get_execution_history", "Pull on-chain transaction history for a wallet. Filters by swap, transfer, or all.", getExecutionHistorySchema.shape, async (params) => mcpText(await invokeTool(handleGetExecutionHistory, params, "get_execution_history")));
+    server.tool("get_token_price", "Fetch real-time price of PHRS, USDC, or USDT on Pharos using DODO liquidity quotes.", getTokenPriceSchema.shape, async (params) => mcpText(await invokeTool(handleGetTokenPrice, params, "get_token_price")));
+    server.tool("get_wallet_balance", "Return PHRS, USDC, USDT balances for a wallet with total USD estimate.", getWalletBalanceSchema.shape, async (params) => mcpText(await invokeTool(handleGetWalletBalance, params, "get_wallet_balance")));
+    server.tool("check_allowance", "Check ERC-20 token allowance for DODO swap approval. Returns whether approval is needed.", checkAllowanceSchema.shape, async (params) => mcpText(await invokeTool(handleCheckAllowance, params, "check_allowance")));
+    server.tool("get_transaction_status", "Check on-chain transaction status by hash. Returns status, block, gas, and explorer link.", getTransactionStatusSchema.shape, async (params) => mcpText(await invokeTool(handleGetTransactionStatus, params, "get_transaction_status")));
+    server.tool("estimate_gas", "Estimate gas cost for a swap or transfer before executing. Returns cost in PHRS and USD.", estimateGasSchema.shape, async (params) => mcpText(await invokeTool(handleEstimateGas, params, "estimate_gas")));
+    server.tool("publish_risk_score", "Run risk assessment and publish result to the on-chain RiskRegistry. Other agents can query it.", publishRiskScoreSchema.shape, async (params) => mcpText(await invokeTool(handlePublishRiskScore, params, "publish_risk_score")));
+    server.tool("query_risk_registry", "Query the on-chain RiskRegistry for a wallet's published risk score. Read-only, no private key needed.", queryRiskRegistrySchema.shape, async (params) => mcpText(await invokeTool(handleQueryRiskRegistry, params, "query_risk_registry")));
+    server.tool("approve_token", "Approve ERC-20 token spending for FaroSwap (DODO) router. Required before swapping non-native tokens.", approveTokenSchema.shape, async (params) => mcpText(await invokeTool(handleApproveToken, params, "approve_token")));
+    server.tool("get_gas_price", "Get current gas price on Pharos with trend classification and cost estimates.", getGasPriceSchema.shape, async (params) => mcpText(await invokeTool(handleGetGasPrice, params, "get_gas_price")));
+    server.tool("get_pool_info", "Fetch DODO liquidity pool info for a token pair on Pharos. Returns price ratio, impact, and fees.", getPoolInfoSchema.shape, async (params) => mcpText(await invokeTool(handleGetPoolInfo, params, "get_pool_info")));
+    server.tool("check_token_security", "Check token contract security (honeypot, mintable, ownership privileges, tax) via GoPlus Security API.", checkTokenSecuritySchema.shape, async (params) => mcpText(await invokeTool(handleCheckTokenSecurity, params, "check_token_security")));
+    server.tool("x402_pay_and_fetch", "Fetch resources from an HTTP x402 payment-gated server. Automatically handles HTTP 402 payment challenge.", x402PayAndFetchSchema.shape, async (params) => mcpText(await invokeTool(handleX402PayAndFetch, params, "x402_pay_and_fetch")));
+    // ─── Managed Wallet Tools ──────────────────────────────────────────────
+    server.tool("create_agent_wallet", "Create a new managed testnet agent wallet. Private key is encrypted and never returned. Fund the wallet with testnet PHRS before using write tools.", createAgentWalletSchema.shape, async (params) => mcpText(await invokeTool(handleCreateAgentWallet, params, "create_agent_wallet")));
+    server.tool("get_agent_wallet", "Get public info (address, environment, chainId) for a managed agent wallet. Never returns private key.", getAgentWalletSchema.shape, async (params) => mcpText(await invokeTool(handleGetAgentWallet, params, "get_agent_wallet")));
+    server.tool("get_agent_wallet_balance", "Get PHRS, USDC, and USDT balances for a managed agent wallet on Pharos testnet.", getAgentWalletBalanceSchema.shape, async (params) => mcpText(await invokeTool(handleGetAgentWalletBalance, params, "get_agent_wallet_balance")));
+    // ─── Start Server ──────────────────────────────────────────────────────
+    async function main() {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error(`SafeHands-Pharos MCP Server v${PKG_VERSION} running on stdio`);
+    }
+    main().catch((error) => {
+        console.error("Fatal error:", error);
+        process.exit(1);
+    });
+} // end: !isDemoMode
 //# sourceMappingURL=index.js.map