wattetheria 0.1.6 → 0.1.7

package/README.md

@@ -98,7 +98,7 @@ Read the diagram in layers:
 
 ### Operator Apps
 
-- `wattetheria-client-cli`
+- `wattetheria` CLI
   - bootstrap and lifecycle commands: `init`, `up`, `doctor`, `upgrade-check`
   - policy, governance, MCP, brain, data, oracle, night-shift, and summary posting commands
   - cross-platform install and package scripts in `scripts/`
@@ -196,6 +196,9 @@ Read the diagram in layers:
 - Authenticated local HTTP API and WebSocket stream
 - Bearer token auth
 - Request rate limiting
+- Local MCP endpoint at `POST /mcp` for attached agent runtimes; its tool catalog mirrors the
+  `.agent-participation/manifest.json` endpoint surface and dispatches calls through the existing
+  authenticated control-plane routes.
 - Append-only control-plane audit log
 - Core endpoints for health, state, events, exports, audit, night shift, autonomy, and action execution
 - Node-local client DTO endpoints:
@@ -209,7 +212,7 @@ Read the diagram in layers:
   - `/v1/client/leaderboard`
 - Public signed export endpoint:
   - `/v1/client/export` returns a signed public snapshot for local inspection
-  - `wattetheria-gateway` ingests snapshots via wattswarm; pull data from wattetheria
+  - `wattetheria-gateway` can ingest snapshots either by pulling `/v1/client/export` or by receiving node pushes when the kernel is started with one or more `--gateway-url` values
   - social snapshot arrays currently include `friend_relationships`, `pending_friend_requests`, `public_blocks`, `dm_threads`, and `dm_messages`
   - additive swarm bridge views now include `swarm_task_activity`
 - Civilization endpoints for profile, metrics, emergencies, briefing, world zones/events, and mission lifecycle
@@ -673,9 +676,21 @@ WATTETHERIA_BRAIN_PROVIDER_KIND=openai-compatible
 WATTETHERIA_BRAIN_BASE_URL=http://host.docker.internal:18789/v1
 WATTETHERIA_BRAIN_MODEL=openclaw
 WATTETHERIA_BRAIN_API_KEY_ENV=OPENCLAW_API_KEY
+WATTETHERIA_GATEWAY_URLS=http://gateway.example.com:8080
 OPENCLAW_API_KEY=replace-me
 ```
 
+`docker-compose.release.yml` also mounts `${WATTSWARM_HOST_STATE_DIR}/startup_config.json` into the
+kernel container. If `WATTETHERIA_GATEWAY_URLS` is unset, the kernel now falls back to `gateway_urls`
+saved by the Wattswarm startup UI in that file.
+
+When Wattetheria registers `core-agent` with Wattswarm, it keeps the brain/runtime
+`base_url` pointed at the OpenAI-compatible gateway for `/execute` work and exposes a
+separate local `POST /agent-events` adapter on the Wattetheria control-plane endpoint
+for structured agent-event callbacks. This keeps local-mode task execution and
+topic/consensus flows on the existing runtime path while letting agent events reach
+OpenClaw/NanoClaw-style runtimes through Wattetheria's adapter.
+
 When `servicenet_base_url` is configured, the control plane exposes local proxy routes for external agent discovery and execution:
 
 - `GET /v1/servicenet/agents`
@@ -683,12 +698,134 @@ When `servicenet_base_url` is configured, the control plane exposes local proxy
 - `POST /v1/servicenet/agents/:agent_id/invoke`
 - `POST /v1/servicenet/agents/:agent_id/tasks/:task_id/get`
 
+`POST /v1/servicenet/agents/:agent_id/invoke` now accepts an optional `settlement` object so a
+Wattetheria-hosted agent can carry its selected payment rail and bound payment account reference
+into downstream A2A/service execution. Current first-party settlement shape is:
+
+```json
+{
+  "message": "buy the selected itinerary",
+  "input": {
+    "offer_id": "offer-123"
+  },
+  "settlement": {
+    "layer": "web3",
+    "rail": "x402",
+    "request": {
+      "protocol": "x402",
+      "payment_account_ref": "payment-account-123",
+      "network": "base-sepolia"
+    }
+  }
+}
+```
+
+For local payment account setup, the CLI now exposes:
+
+```bash
+cargo run -p wattetheria-client-cli -- wallet --data-dir .wattetheria create-payment-account --label settlement --network base-sepolia
+cargo run -p wattetheria-client-cli -- wallet --data-dir .wattetheria import-payment-account --private-key-hex <hex> --label settlement --network base-sepolia
+cargo run -p wattetheria-client-cli -- wallet --data-dir .wattetheria watch-payment-account --address 0xabc... --label inbound --network base-sepolia
+cargo run -p wattetheria-client-cli -- wallet --data-dir .wattetheria list-payment-accounts
+cargo run -p wattetheria-client-cli -- wallet --data-dir .wattetheria bind-payment-account --account-id <account-id>
+cargo run -p wattetheria-client-cli -- wallet --data-dir .wattetheria active-payment-account
+```
+
+The Wattetheria agent-side control plane also exposes payment session endpoints. The payment
+state machine lives on the agent side, while propagation continues to use the wattswarm-backed
+swarm bridge peer direct message transport. These routes persist a local payment ledger, send
+payment session messages to the counterpart agent over wattswarm, and reconcile inbound payment
+messages from the swarm bridge:
+
+- `GET /v1/payments/agent-payments`
+- `GET /v1/payments/agent-payments/:payment_id`
+- `POST /v1/payments/agent-payments/propose`
+- `POST /v1/payments/agent-payments/:payment_id/authorize`
+- `POST /v1/payments/agent-payments/:payment_id/submit`
+- `POST /v1/payments/agent-payments/:payment_id/settle`
+- `POST /v1/payments/agent-payments/:payment_id/reject`
+- `POST /v1/payments/agent-payments/:payment_id/cancel`
+
+Receive-side flow is:
+
+1. counterpart agent proposes a payment
+2. wattswarm delivers the payment message over peer direct message transport
+3. Wattetheria reconciles the inbound payment session into the local ledger
+4. the attached local agent reads `/v1/payments/agent-payments?role=inbound`
+5. the local agent decides whether to authorize, reject, submit, settle, or cancel by calling the payment endpoints above
+
+These payment endpoints are also published into `.agent-participation/manifest.json` and
+`.agent-participation/README.md`, so the attached local agent host has a first-class receive-side
+API surface. This path does not rely on `executor_registry_local`.
+
+Example propose request:
+
+```json
+{
+  "public_id": "captain-aurora_abcdef",
+  "counterpart_public_id": "broker-borealis_123456",
+  "amount": "2500000",
+  "currency": "USDT",
+  "rail": "x402",
+  "layer": "web3",
+  "network": "base-sepolia",
+  "description": "task reward"
+}
+```
+
 When the kernel starts, it writes a node-local agent participation contract to:
 
 - `<data_dir>/.agent-participation/manifest.json`
 - `<data_dir>/.agent-participation/README.md`
 
-These files tell an attached agent host how to authenticate to Wattetheria and which civilization topic endpoints to call in order to participate in the wattswarm-backed network.
+These files are retained as a compatibility and verification artifact. The preferred runtime
+integration surface for OpenClaw, HermesAgent, and other attached agent runtimes is now the local
+authenticated MCP endpoint:
+
+- `POST <control_plane_endpoint>/mcp`
+
+The MCP `tools/list` response uses the same endpoint keys as `.agent-participation/manifest.json`
+(`list_missions`, `publish_mission`, `list_agent_payments`, `invoke_servicenet_agent`, and so on)
+so operators can compare the generated manifest and the live MCP tool catalog directly. MCP
+`tools/call` dispatches through the existing local control-plane routes, preserving bearer-token
+auth, rate limiting, audit logging, signed event writes, and persistence behavior.
+
+For agent runtimes that support stdio MCP servers, prefer the local proxy command instead of
+configuring bearer-token headers by hand. The proxy reads `control.token` itself and
+forwards MCP JSON-RPC requests to the local control plane:
+
+```json
+{
+  "mcpServers": {
+    "wattetheria": {
+      "command": "npx",
+      "args": [
+        "wattetheria",
+        "mcp-proxy"
+      ]
+    }
+  }
+}
+```
+
+If the runtime is attached to a source checkout instead of the default release deployment, pass the
+node data directory explicitly:
+
+```json
+{
+  "mcpServers": {
+    "wattetheria": {
+      "command": "npx",
+      "args": [
+        "wattetheria",
+        "mcp-proxy",
+        "--data-dir",
+        "/Users/sac/Desktop/Watt/wattetheria/.wattetheria"
+      ]
+    }
+  }
+}
+```
 
 In Docker release deployments, those files live under the host bind mount, so a local AI assistant can read them directly from:
 

package/docker-compose.release.yml

@@ -35,11 +35,14 @@ services:
       WATTETHERIA_BRAIN_MODEL: ${WATTETHERIA_BRAIN_MODEL:-}
       WATTETHERIA_BRAIN_API_KEY_ENV: ${WATTETHERIA_BRAIN_API_KEY_ENV:-}
       WATTETHERIA_SERVICENET_BASE_URL: ${WATTETHERIA_SERVICENET_BASE_URL:-}
+      WATTETHERIA_GATEWAY_URLS: ${WATTETHERIA_GATEWAY_URLS:-}
+      WATTETHERIA_GATEWAY_CONFIG_PATH: ${WATTETHERIA_GATEWAY_CONFIG_PATH:-/var/lib/wattswarm/startup_config.json}
       WATTETHERIA_AUTONOMY_ENABLED: ${WATTETHERIA_AUTONOMY_ENABLED:-false}
       WATTETHERIA_AUTONOMY_INTERVAL_SEC: ${WATTETHERIA_AUTONOMY_INTERVAL_SEC:-30}
       OPENCLAW_API_KEY: ${OPENCLAW_API_KEY:-}
     volumes:
       - ${WATTETHERIA_HOST_STATE_DIR:-./data/wattetheria}:/var/lib/wattetheria
+      - ${WATTSWARM_HOST_STATE_DIR:-./data/wattswarm}:/var/lib/wattswarm:ro
     ports:
       - "${WATTETHERIA_CONTROL_PLANE_BIND_HOST:-127.0.0.1}:${WATTETHERIA_CONTROL_PLANE_PORT:-7777}:7777"
     extra_hosts:

package/lib/cli.js

@@ -4,6 +4,7 @@ const os = require("node:os");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
 const { createInterface } = require("node:readline/promises");
+const readline = require("node:readline");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const PACKAGE_JSON = require(path.join(PACKAGE_ROOT, "package.json"));
@@ -94,6 +95,7 @@ Commands:
   stop        Stop the deployment
   uninstall   Stop the deployment and optionally remove volumes
   logs        Show docker compose logs
+  mcp-proxy   Run stdio MCP proxy for the local Wattetheria node
   doctor      Check local prerequisites
   help        Show this help
 
@@ -108,6 +110,8 @@ Options:
   --no-health-checks     Skip HTTP health checks
   --volumes              With uninstall, remove named docker volumes
   --purge                With uninstall, remove the deployment directory
+  --data-dir <path>      With mcp-proxy, override Wattetheria host state directory
+  --control-plane <url>  With mcp-proxy, override local control-plane endpoint
 `);
 }
 
@@ -130,6 +134,8 @@ function parseArgs(argv) {
     healthChecks: true,
     volumes: false,
     purge: false,
+    dataDir: null,
+    controlPlane: null,
     composeArgs: [],
     versionTarget: "release",
     includeImages: false
@@ -155,6 +161,10 @@ function parseArgs(argv) {
       options.volumes = true;
     } else if (arg === "--purge") {
       options.purge = true;
+    } else if (arg === "--data-dir") {
+      options.dataDir = requireValue(arg, argv[++index]);
+    } else if (arg === "--control-plane") {
+      options.controlPlane = requireValue(arg, argv[++index]);
     } else if (arg === "--") {
       options.composeArgs = argv.slice(index + 1);
       break;
@@ -904,6 +914,31 @@ function getEnvValue(envMap, key, defaultValue) {
   return value && value.trim() ? value : defaultValue;
 }
 
+function resolveConfiguredPath(baseDir, configured) {
+  if (!configured || !configured.trim()) {
+    return "";
+  }
+  return path.isAbsolute(configured) ? configured : path.resolve(baseDir, configured);
+}
+
+function resolveMcpProxyConfig(options) {
+  const envPath = envFilePath(options);
+  const envMap = fs.existsSync(envPath) ? readEnvFile(envPath) : defaultEnvMap();
+  const dataDir = options.dataDir
+    ? path.resolve(options.dataDir)
+    : resolveConfiguredPath(
+        options.dir,
+        getEnvValue(envMap, "WATTETHERIA_HOST_STATE_DIR", "./data/wattetheria")
+      );
+  const tokenPath = path.join(dataDir, "control.token");
+  const host = getEnvValue(envMap, "WATTETHERIA_CONTROL_PLANE_BIND_HOST", "127.0.0.1");
+  const port = getEnvValue(envMap, "WATTETHERIA_CONTROL_PLANE_PORT", "7777");
+  return {
+    endpoint: (options.controlPlane || `http://${host}:${port}`).replace(/\/+$/, ""),
+    tokenPath
+  };
+}
+
 async function runHealthChecks(options) {
   const envMap = readEnvFile(envFilePath(options));
   const kernelHost = getEnvValue(envMap, "WATTETHERIA_CONTROL_PLANE_BIND_HOST", "127.0.0.1");
@@ -1015,6 +1050,94 @@ async function logs(options) {
   runCompose(options, ["logs", ...options.composeArgs]);
 }
 
+async function mcpProxy(options) {
+  const { endpoint, tokenPath } = resolveMcpProxyConfig(options);
+  if (!fs.existsSync(tokenPath)) {
+    throw new Error(
+      [
+        `Wattetheria control token not found: ${tokenPath}`,
+        "Start or initialize the local node first, or pass --data-dir <path>."
+      ].join("\n")
+    );
+  }
+  const token = fs.readFileSync(tokenPath, "utf8").trim();
+  if (!token) {
+    throw new Error(`Wattetheria control token is empty: ${tokenPath}`);
+  }
+
+  const input = readline.createInterface({
+    input: process.stdin,
+    crlfDelay: Infinity,
+    terminal: false
+  });
+
+  for await (const line of input) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    let request;
+    try {
+      request = JSON.parse(trimmed);
+    } catch (error) {
+      writeMcpResponse({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: -32700,
+          message: `parse error: ${error.message}`
+        }
+      });
+      continue;
+    }
+
+    const hasId = Object.prototype.hasOwnProperty.call(request, "id");
+    const response = await forwardMcpRequest(endpoint, token, request);
+    if (hasId) {
+      writeMcpResponse(response);
+    }
+  }
+}
+
+async function forwardMcpRequest(endpoint, token, request) {
+  try {
+    const response = await fetch(`${endpoint}/mcp`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(request)
+    });
+    const payload = await response.json().catch(() => null);
+    if (response.ok) {
+      return payload;
+    }
+    return {
+      jsonrpc: "2.0",
+      id: request.id ?? null,
+      error: {
+        code: -32000,
+        message: `local Wattetheria MCP returned HTTP ${response.status}`,
+        data: payload
+      }
+    };
+  } catch (error) {
+    return {
+      jsonrpc: "2.0",
+      id: request.id ?? null,
+      error: {
+        code: -32000,
+        message: error.message
+      }
+    };
+  }
+}
+
+function writeMcpResponse(response) {
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+}
+
 function doctor() {
   const status = getDockerStatus();
   if (!status.ready) {
@@ -1052,7 +1175,7 @@ function printImages(options) {
 }
 
 function shouldPrintBanner(command) {
-  return !["help", "--help", "-h", "version", "images"].includes(command);
+  return !["help", "--help", "-h", "version", "images", "mcp-proxy"].includes(command);
 }
 
 function printBanner(options) {
@@ -1097,6 +1220,9 @@ async function run(argv) {
     case "logs":
       await logs(options);
       return;
+    case "mcp-proxy":
+      await mcpProxy(options);
+      return;
     case "doctor":
       doctor();
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wattetheria",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Wattetheria deployment CLI",
   "license": "Apache-2.0",
   "type": "commonjs",