wattetheria 0.1.5 → 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/`
@@ -148,18 +148,11 @@ Read the diagram in layers:
 
 ### Tasks, Oracle, And Mailbox
 
-- Legacy task engine with deterministic lifecycle:
-  - publish
-  - claim
-  - execute
-  - submit
-  - verify
-  - settle
-- `market.match` task path with deterministic and witness verification modes
-- `swarm_bridge` adapter that maps current task execution into a `wattswarm`-oriented bridge surface
+- Product-layer galaxy task definitions in `crates/kernel-core/src/tasks/galaxy_task.rs`
+- `swarm_bridge` adapter for `wattswarm` topic, task/run read models, and peer/network surfaces
 - Hybrid `swarm_bridge` path for `wattswarm` topic and network read models
   - optional `--wattswarm-ui-base-url` wiring from CLI config into node runtime
-  - topic subscribe, post, history, cursor, network-status, and peer-list bridge calls
+  - topic subscribe, post, history, cursor, task/run snapshots, network-status, and peer-list bridge calls
 - Oracle registry with signed feed publish, subscribe, pull, and watt-based settlement
 - Cross-subnet mailbox with send, fetch, and ack persistence
 
@@ -203,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:
@@ -216,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
@@ -568,6 +564,8 @@ Version commands:
 - `npx wattetheria --version` shows the current Wattetheria release version
 - `npx wattetheria version --images` prints the configured image refs for the current deployment
 - `npx wattetheria version --cli` shows the deployment CLI package version
+- `npx wattetheria update` resolves the latest shared published image tag across the configured release images and upgrades to it
+- `npx wattetheria update --tag <tag>` pins the deployment to a specific published image tag
 
 Release deployments bind-mount host-visible state by default:
 
@@ -597,7 +595,7 @@ pwsh ./scripts/deploy-release.ps1
 - `docker-compose.yml` is the local `wattetheria`-only development stack
 - `docker-compose.full.yml` is the local joint development stack for `wattetheria` + `wattswarm`
 - `docker-compose.release.yml` is the image-based release deployment asset used by the CLI and fallback scripts
-- `.env.release` is the release deployment environment template used by the CLI and fallback scripts
+- the CLI now generates deployment environment defaults internally and resolves the latest published image release during install and update
 - `scripts/deploy-release.ps1` is a cross-platform fallback deployment entry point
 - this repository does not include `wattetheria-gateway`; gateway is a separate project and deployment unit
 - Entrypoints live in `scripts/docker-kernel-entrypoint.sh` and `scripts/docker-observatory-entrypoint.sh`
@@ -678,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`
@@ -688,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,13 +4,20 @@ 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"));
-const RELEASE_ENV_TEMPLATE = path.join(PACKAGE_ROOT, ".env.release");
 const DEFAULT_DEPLOY_DIR = path.join(os.homedir(), ".wattetheria", "deploy");
 const DEFAULT_PROJECT_NAME = "wattetheria";
 const DEFAULT_COMMAND = "help";
+const DEFAULT_IMAGE_REFS = new Map([
+  ["WATTETHERIA_KERNEL_IMAGE", "ghcr.io/wattetheria/wattetheria-kernel:latest"],
+  ["WATTETHERIA_OBSERVATORY_IMAGE", "ghcr.io/wattetheria/wattetheria-observatory:latest"],
+  ["WATTSWARM_KERNEL_IMAGE", "ghcr.io/wattetheria/wattswarm-kernel:latest"],
+  ["WATTSWARM_RUNTIME_IMAGE", "ghcr.io/wattetheria/wattswarm-runtime:latest"],
+  ["WATTSWARM_WORKER_IMAGE", "ghcr.io/wattetheria/wattswarm-worker:latest"]
+]);
 const IMAGE_KEYS = [
   "WATTETHERIA_KERNEL_IMAGE",
   "WATTETHERIA_OBSERVATORY_IMAGE",
@@ -19,6 +26,48 @@ const IMAGE_KEYS = [
   "WATTSWARM_WORKER_IMAGE"
 ];
 const HOST_STATE_DIR_KEYS = ["WATTETHERIA_HOST_STATE_DIR", "WATTSWARM_HOST_STATE_DIR"];
+const REGISTRY_TAG_PAGE_SIZE = 1000;
+const DEFAULT_ENV_ENTRIES = [
+  ...DEFAULT_IMAGE_REFS.entries(),
+  ["WATTETHERIA_CONTROL_PLANE_BIND_HOST", "127.0.0.1"],
+  ["WATTETHERIA_CONTROL_PLANE_PORT", "7777"],
+  ["WATTETHERIA_OBSERVATORY_BIND_HOST", "127.0.0.1"],
+  ["WATTETHERIA_OBSERVATORY_PORT", "8780"],
+  ["WATTSWARM_UI_BIND_HOST", "127.0.0.1"],
+  ["WATTSWARM_UI_PORT", "7788"],
+  ["WATTSWARM_SYNC_GRPC_BIND_HOST", "127.0.0.1"],
+  ["WATTSWARM_SYNC_GRPC_PORT", "7791"],
+  ["WATTSWARM_P2P_HOST_PORT", "4001"],
+  ["WATTSWARM_UDP_ANNOUNCE_HOST_PORT", "37931"],
+  ["WATTETHERIA_HOST_STATE_DIR", "./data/wattetheria"],
+  ["WATTSWARM_HOST_STATE_DIR", "./data/wattswarm"],
+  ["WATTETHERIA_RUNTIME_ENV_FILE", ".env.release.local"],
+  ["WATTETHERIA_AGENT_CONTROL_PLANE_ENDPOINT", "http://127.0.0.1:7777"],
+  ["WATTETHERIA_AGENT_WATTSWARM_UI_BASE_URL", "http://127.0.0.1:7788"],
+  ["WATTETHERIA_AGENT_WATTSWARM_SYNC_GRPC_ENDPOINT", "http://127.0.0.1:7791"],
+  ["WATTETHERIA_AGENT_HOST_DATA_DIR", "./data/wattetheria"],
+  ["WATTETHERIA_BRAIN_PROVIDER_KIND", "rules"],
+  ["WATTETHERIA_BRAIN_BASE_URL", ""],
+  ["WATTETHERIA_BRAIN_MODEL", ""],
+  ["WATTETHERIA_BRAIN_API_KEY_ENV", ""],
+  ["WATTETHERIA_SERVICENET_BASE_URL", ""],
+  ["WATTETHERIA_AUTONOMY_ENABLED", "false"],
+  ["WATTETHERIA_AUTONOMY_INTERVAL_SEC", "30"],
+  ["OPENCLAW_API_KEY", ""],
+  ["WATTSWARM_PG_DB", "wattswarm"],
+  ["WATTSWARM_PG_USER", "postgres"],
+  ["WATTSWARM_PG_PASSWORD", "replace-with-strong-password"],
+  ["WATTSWARM_P2P_ENABLED", "true"],
+  ["WATTSWARM_P2P_MDNS", "true"],
+  ["WATTSWARM_P2P_PORT", "4001"],
+  ["WATTSWARM_WORKER_CONCURRENCY", "16"],
+  ["WATTSWARM_WORKER_POLL_MS", "250"],
+  ["WATTSWARM_WORKER_LEASE_MS", "30000"],
+  ["WATTSWARM_UDP_ANNOUNCE_ENABLED", "false"],
+  ["WATTSWARM_UDP_ANNOUNCE_MODE", "multicast"],
+  ["WATTSWARM_UDP_ANNOUNCE_ADDR", "239.255.42.99"],
+  ["WATTSWARM_UDP_ANNOUNCE_PORT", "37931"]
+];
 const DOCKER_INSTALL_URLS = {
   darwin: "https://www.docker.com/products/docker-desktop/",
   win32: "https://www.docker.com/products/docker-desktop/",
@@ -42,10 +91,11 @@ Commands:
   install     Prepare deployment, pull images, and start the stack
   start       Start an existing deployment
   status      Show docker compose status
-  update      Update image tags, pull, and restart
+  update      Resolve latest published release, pull, and restart
   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
 
@@ -56,10 +106,12 @@ Options:
   --dir <path>           Deployment directory (default: ${DEFAULT_DEPLOY_DIR})
   --project-name <name>  Docker compose project name (default: ${DEFAULT_PROJECT_NAME})
   --tag <tag>            Override all release image tags
-  --force                Refresh deployment templates from package assets
+  --force                Refresh deployment defaults and compose assets
   --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
 `);
 }
 
@@ -82,6 +134,8 @@ function parseArgs(argv) {
     healthChecks: true,
     volumes: false,
     purge: false,
+    dataDir: null,
+    controlPlane: null,
     composeArgs: [],
     versionTarget: "release",
     includeImages: false
@@ -107,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;
@@ -179,6 +237,193 @@ function extractImageTag(imageRef) {
   return imageRef.slice(lastColon + 1).trim();
 }
 
+function stripImageTag(imageRef) {
+  if (!imageRef) {
+    return "";
+  }
+  const lastColon = imageRef.lastIndexOf(":");
+  const lastSlash = imageRef.lastIndexOf("/");
+  if (lastColon <= lastSlash) {
+    return imageRef.trim();
+  }
+  return imageRef.slice(0, lastColon).trim();
+}
+
+function parseImageReference(imageRef) {
+  const normalized = stripImageTag(imageRef);
+  if (!normalized) {
+    throw new Error(`Invalid image reference: ${imageRef}`);
+  }
+
+  const segments = normalized.split("/");
+  const first = segments[0];
+  const hasExplicitRegistry = first.includes(".") || first.includes(":") || first === "localhost";
+  const registry = hasExplicitRegistry ? first : "registry-1.docker.io";
+  const repositorySegments = hasExplicitRegistry ? segments.slice(1) : segments;
+  if (repositorySegments.length === 0) {
+    throw new Error(`Invalid image repository: ${imageRef}`);
+  }
+
+  if (!hasExplicitRegistry && repositorySegments.length === 1) {
+    repositorySegments.unshift("library");
+  }
+
+  return {
+    registry,
+    repository: repositorySegments.join("/")
+  };
+}
+
+function parseReleaseTag(tag) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec((tag || "").trim());
+  if (!match) {
+    return null;
+  }
+  return {
+    raw: tag,
+    major: Number.parseInt(match[1], 10),
+    minor: Number.parseInt(match[2], 10),
+    patch: Number.parseInt(match[3], 10),
+    prerelease: match[4] || ""
+  };
+}
+
+function compareReleaseTags(left, right) {
+  const a = parseReleaseTag(left);
+  const b = parseReleaseTag(right);
+  if (!a && !b) {
+    return String(left).localeCompare(String(right));
+  }
+  if (!a) {
+    return -1;
+  }
+  if (!b) {
+    return 1;
+  }
+  for (const key of ["major", "minor", "patch"]) {
+    if (a[key] !== b[key]) {
+      return a[key] - b[key];
+    }
+  }
+  if (!a.prerelease && b.prerelease) {
+    return 1;
+  }
+  if (a.prerelease && !b.prerelease) {
+    return -1;
+  }
+  return a.prerelease.localeCompare(b.prerelease);
+}
+
+function parseAuthChallenge(header) {
+  if (!header) {
+    return null;
+  }
+  const match = /^Bearer\s+(.*)$/i.exec(header.trim());
+  if (!match) {
+    return null;
+  }
+  const params = new Map();
+  for (const [, key, value] of match[1].matchAll(/([a-zA-Z_]+)="([^"]*)"/g)) {
+    params.set(key, value);
+  }
+  const realm = params.get("realm");
+  if (!realm) {
+    return null;
+  }
+  return {
+    realm,
+    service: params.get("service") || "",
+    scope: params.get("scope") || ""
+  };
+}
+
+async function fetchRegistryAccessToken(challenge) {
+  const url = new URL(challenge.realm);
+  if (challenge.service) {
+    url.searchParams.set("service", challenge.service);
+  }
+  if (challenge.scope) {
+    url.searchParams.set("scope", challenge.scope);
+  }
+
+  const response = await fetch(url, { method: "GET" });
+  if (!response.ok) {
+    throw new Error(`Failed to resolve registry token: ${response.status} ${response.statusText}`);
+  }
+  const payload = await response.json();
+  const token = payload.token || payload.access_token;
+  if (!token) {
+    throw new Error("Registry token response did not contain an access token.");
+  }
+  return token;
+}
+
+async function fetchRegistryResponse(url, token = "") {
+  const headers = {
+    Accept: "application/json"
+  };
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  const response = await fetch(url, { method: "GET", headers });
+  if (response.status === 401 && !token) {
+    const challenge = parseAuthChallenge(response.headers.get("www-authenticate"));
+    if (!challenge) {
+      throw new Error(`Registry authentication challenge is missing for ${url}`);
+    }
+    const resolvedToken = await fetchRegistryAccessToken(challenge);
+    return fetchRegistryResponse(url, resolvedToken);
+  }
+  if (!response.ok) {
+    throw new Error(`Registry request failed for ${url}: ${response.status} ${response.statusText}`);
+  }
+  return response;
+}
+
+function resolveRegistryNextPage(linkHeader, currentUrl) {
+  if (!linkHeader) {
+    return "";
+  }
+  const match = /<([^>]+)>;\s*rel="next"/i.exec(linkHeader);
+  if (!match) {
+    return "";
+  }
+  return new URL(match[1], currentUrl).toString();
+}
+
+async function listPublishedImageTags(imageRef) {
+  const { registry, repository } = parseImageReference(imageRef);
+  const collected = new Set();
+  let nextUrl = `https://${registry}/v2/${repository}/tags/list?n=${REGISTRY_TAG_PAGE_SIZE}`;
+  while (nextUrl) {
+    const response = await fetchRegistryResponse(nextUrl);
+    const payload = await response.json();
+    for (const tag of payload.tags || []) {
+      if (tag && tag.trim()) {
+        collected.add(tag.trim());
+      }
+    }
+    nextUrl = resolveRegistryNextPage(response.headers.get("link"), nextUrl);
+  }
+  return [...collected];
+}
+
+function findLatestCommonReleaseTag(tagLists) {
+  if (tagLists.length === 0) {
+    return "";
+  }
+  const [first, ...rest] = tagLists.map((tags) => new Set(tags));
+  const common = [...first].filter((tag) => rest.every((tags) => tags.has(tag)));
+  const releaseCandidates = common
+    .map((tag) => ({ tag, parsed: parseReleaseTag(tag) }))
+    .filter((entry) => entry.parsed);
+  const stableCandidates = releaseCandidates.filter((entry) => !entry.parsed.prerelease);
+  const ranked = (stableCandidates.length > 0 ? stableCandidates : releaseCandidates)
+    .map((entry) => entry.tag)
+    .sort(compareReleaseTags);
+  return ranked.at(-1) || "";
+}
+
 function resolveEnvReference(value, envMap, seen = new Set()) {
   if (!value) {
     return "";
@@ -210,6 +455,22 @@ function getReleaseImageMap(filePath) {
   return images;
 }
 
+function getReleaseImageMapFromEnv(envMap) {
+  const images = new Map();
+  for (const key of IMAGE_KEYS) {
+    const rawValue = envMap.get(key);
+    if (!rawValue) {
+      continue;
+    }
+    images.set(key, resolveEnvReference(rawValue.trim(), envMap));
+  }
+  return images;
+}
+
+function defaultEnvMap() {
+  return new Map(DEFAULT_ENV_ENTRIES);
+}
+
 function getReleaseSource(options) {
   const deployEnvPath = envFilePath(options);
   if (fs.existsSync(deployEnvPath)) {
@@ -219,20 +480,24 @@ function getReleaseSource(options) {
     };
   }
   return {
-    kind: "template",
-    path: RELEASE_ENV_TEMPLATE
+    kind: "uninitialized",
+    path: deployEnvPath
   };
 }
 
 function getReleaseVersionInfo(options) {
   const source = getReleaseSource(options);
-  const images = getReleaseImageMap(source.path);
+  const images = source.kind === "deployment"
+    ? getReleaseImageMap(source.path)
+    : getReleaseImageMapFromEnv(defaultEnvMap());
   const tags = IMAGE_KEYS
     .map((key) => extractImageTag(images.get(key)))
     .filter(Boolean);
-  const version = tags.length === IMAGE_KEYS.length && new Set(tags).size === 1
-    ? tags[0]
-    : "custom";
+  const version = source.kind === "uninitialized"
+    ? "uninitialized"
+    : (tags.length === IMAGE_KEYS.length && new Set(tags).size === 1
+        ? tags[0]
+        : "custom");
   return {
     version,
     images,
@@ -412,15 +677,14 @@ async function ensureDockerAvailable(options = {}) {
 function ensureDeploymentAssets(options) {
   fs.mkdirSync(options.dir, { recursive: true });
 
-  const templateEnvPath = path.join(PACKAGE_ROOT, ".env.release");
   const templateComposePath = path.join(PACKAGE_ROOT, "docker-compose.release.yml");
   const targetEnvPath = envFilePath(options);
   const targetComposePath = composeFilePath(options);
 
   if (options.force || !fs.existsSync(targetEnvPath)) {
-    fs.copyFileSync(templateEnvPath, targetEnvPath);
+    writeEnvFile(targetEnvPath, defaultEnvMap());
   } else {
-    mergeNewTemplateKeys(templateEnvPath, targetEnvPath);
+    mergeNewDefaultKeys(targetEnvPath);
   }
   if (options.force || !fs.existsSync(targetComposePath)) {
     fs.copyFileSync(templateComposePath, targetComposePath);
@@ -471,8 +735,8 @@ function writeEnvFile(filePath, envMap) {
   fs.writeFileSync(filePath, `${lines.join("\n")}\n`);
 }
 
-function mergeNewTemplateKeys(templatePath, targetPath) {
-  const templateMap = readEnvFile(templatePath);
+function mergeNewDefaultKeys(targetPath) {
+  const templateMap = defaultEnvMap();
   const targetMap = readEnvFile(targetPath);
   let added = 0;
   for (const [key, value] of templateMap.entries()) {
@@ -508,32 +772,60 @@ function ensureHostStateDirectories(baseDir, envMap) {
   }
 }
 
-function syncImageTagsFromTemplate(options) {
+async function syncImageTagsToLatestPublishedRelease(options) {
   if (options.tag) {
-    return;
+    return options.tag;
   }
+
   const targetPath = envFilePath(options);
-  const templateMap = readEnvFile(RELEASE_ENV_TEMPLATE);
   const targetMap = readEnvFile(targetPath);
+  const images = getReleaseImageMapFromEnv(targetMap);
+  const missing = IMAGE_KEYS.filter((key) => !images.get(key));
+  if (missing.length > 0) {
+    throw new Error(`Release image refs are missing from deployment env: ${missing.join(", ")}`);
+  }
+
+  const tagLists = [];
+  for (const key of IMAGE_KEYS) {
+    const imageRef = images.get(key);
+    const tags = await listPublishedImageTags(imageRef);
+    if (tags.length === 0) {
+      throw new Error(`No published tags found for ${stripImageTag(imageRef)}`);
+    }
+    tagLists.push(tags);
+  }
+
+  const latestTag = findLatestCommonReleaseTag(tagLists);
+  if (!latestTag) {
+    throw new Error(
+      "Could not find a shared published release tag across all configured images."
+    );
+  }
+
+  const currentTag = targetMap.get("RELEASE_TAG") || "";
+  if (currentTag.trim() !== latestTag) {
+    targetMap.set("RELEASE_TAG", latestTag);
+  }
+
   let changed = false;
-  for (const key of [...IMAGE_KEYS, "RELEASE_TAG"]) {
-    const templateValue = templateMap.get(key);
-    if (!templateValue) {
+  for (const key of IMAGE_KEYS) {
+    const current = targetMap.get(key);
+    if (!current) {
       continue;
     }
-    const resolved = resolveEnvReference(templateValue.trim(), templateMap);
-    const current = targetMap.get(key);
-    const currentResolved = current ? resolveEnvReference(current.trim(), targetMap) : "";
-    if (resolved !== currentResolved) {
-      targetMap.set(key, templateValue);
+    const next = `${stripImageTag(resolveEnvReference(current.trim(), targetMap))}:${latestTag}`;
+    if (resolveEnvReference(current.trim(), targetMap) !== next) {
+      targetMap.set(key, next);
       changed = true;
     }
   }
-  if (changed) {
+  if (changed || currentTag.trim() !== latestTag) {
     writeEnvFile(targetPath, targetMap);
-    const newTag = extractImageTag(resolveEnvReference(templateMap.get(IMAGE_KEYS[0]) || "", templateMap));
-    console.log(`Updated image tags to ${newTag || "latest template values"}.`);
+    console.log(`Resolved latest published release tag ${latestTag}.`);
+  } else {
+    console.log(`Release images are already pinned to latest published tag ${latestTag}.`);
   }
+  return latestTag;
 }
 
 function pinImageTags(envMap, tag) {
@@ -622,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");
@@ -656,6 +973,11 @@ function printSummary(options) {
 async function install(options) {
   await ensureDockerAvailable({ interactive: true });
   ensureDeploymentAssets(options);
+  if (options.tag) {
+    console.log(`Pinning release images to requested tag ${options.tag}.`);
+  } else {
+    await syncImageTagsToLatestPublishedRelease(options);
+  }
   runCompose(options, ["config"], true);
   console.log("Pulling release images...");
   runCompose(options, ["pull"]);
@@ -690,7 +1012,11 @@ async function update(options) {
     throw new Error("Deployment is not initialized. Run install first.");
   }
   ensureDeploymentAssets(options);
-  syncImageTagsFromTemplate(options);
+  if (options.tag) {
+    console.log(`Pinning release images to requested tag ${options.tag}.`);
+  } else {
+    await syncImageTagsToLatestPublishedRelease(options);
+  }
   console.log("Pulling updated images...");
   runCompose(options, ["pull"]);
   console.log("Restarting release stack...");
@@ -724,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) {
@@ -761,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) {
@@ -806,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.5",
+  "version": "0.1.7",
   "description": "Wattetheria deployment CLI",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -9,7 +9,6 @@
     "bin/",
     "lib/",
     "docker-compose.release.yml",
-    ".env.release",
     "README.md",
     "LICENSE"
   ],

package/.env.release

@@ -1,58 +0,0 @@
-# Coordinated release image set
-RELEASE_TAG=1.0.3
-
-WATTETHERIA_KERNEL_IMAGE=ghcr.io/wattetheria/wattetheria-kernel:${RELEASE_TAG}
-WATTETHERIA_OBSERVATORY_IMAGE=ghcr.io/wattetheria/wattetheria-observatory:${RELEASE_TAG}
-WATTSWARM_KERNEL_IMAGE=ghcr.io/wattetheria/wattswarm-kernel:${RELEASE_TAG}
-WATTSWARM_RUNTIME_IMAGE=ghcr.io/wattetheria/wattswarm-runtime:${RELEASE_TAG}
-WATTSWARM_WORKER_IMAGE=ghcr.io/wattetheria/wattswarm-worker:${RELEASE_TAG}
-
-# Host bindings
-WATTETHERIA_CONTROL_PLANE_BIND_HOST=127.0.0.1
-WATTETHERIA_CONTROL_PLANE_PORT=7777
-WATTETHERIA_OBSERVATORY_BIND_HOST=127.0.0.1
-WATTETHERIA_OBSERVATORY_PORT=8780
-WATTSWARM_UI_BIND_HOST=127.0.0.1
-WATTSWARM_UI_PORT=7788
-WATTSWARM_SYNC_GRPC_BIND_HOST=127.0.0.1
-WATTSWARM_SYNC_GRPC_PORT=7791
-WATTSWARM_P2P_HOST_PORT=4001
-WATTSWARM_UDP_ANNOUNCE_HOST_PORT=37931
-
-# Host-mounted state directories for local agent access
-WATTETHERIA_HOST_STATE_DIR=./data/wattetheria
-WATTSWARM_HOST_STATE_DIR=./data/wattswarm
-WATTETHERIA_RUNTIME_ENV_FILE=.env.release.local
-
-# Agent-facing endpoints written into .agent-participation/manifest.json
-WATTETHERIA_AGENT_CONTROL_PLANE_ENDPOINT=http://127.0.0.1:7777
-WATTETHERIA_AGENT_WATTSWARM_UI_BASE_URL=http://127.0.0.1:7788
-WATTETHERIA_AGENT_WATTSWARM_SYNC_GRPC_ENDPOINT=http://127.0.0.1:7791
-WATTETHERIA_AGENT_HOST_DATA_DIR=./data/wattetheria
-
-# Wattetheria runtime
-WATTETHERIA_BRAIN_PROVIDER_KIND=rules
-WATTETHERIA_BRAIN_BASE_URL=
-WATTETHERIA_BRAIN_MODEL=
-WATTETHERIA_BRAIN_API_KEY_ENV=
-WATTETHERIA_SERVICENET_BASE_URL=
-WATTETHERIA_AUTONOMY_ENABLED=false
-WATTETHERIA_AUTONOMY_INTERVAL_SEC=30
-OPENCLAW_API_KEY=
-
-# Wattswarm database
-WATTSWARM_PG_DB=wattswarm
-WATTSWARM_PG_USER=postgres
-WATTSWARM_PG_PASSWORD=replace-with-strong-password
-
-# Wattswarm runtime and network
-WATTSWARM_P2P_ENABLED=true
-WATTSWARM_P2P_MDNS=true
-WATTSWARM_P2P_PORT=4001
-WATTSWARM_WORKER_CONCURRENCY=16
-WATTSWARM_WORKER_POLL_MS=250
-WATTSWARM_WORKER_LEASE_MS=30000
-WATTSWARM_UDP_ANNOUNCE_ENABLED=false
-WATTSWARM_UDP_ANNOUNCE_MODE=multicast
-WATTSWARM_UDP_ANNOUNCE_ADDR=239.255.42.99
-WATTSWARM_UDP_ANNOUNCE_PORT=37931