@silicaclaw/cli 1.0.0-beta.20 → 1.0.0-beta.21

package/packages/network/src/relayPreview.ts

@@ -0,0 +1,425 @@
+import { randomUUID } from "crypto";
+import { NetworkAdapter } from "./types";
+import {
+  MessageEnvelopeCodec,
+  NetworkMessageEnvelope,
+  validateNetworkMessageEnvelope,
+} from "./abstractions/messageEnvelope";
+import { TopicCodec } from "./abstractions/topicCodec";
+import { JsonMessageEnvelopeCodec } from "./codec/jsonMessageEnvelopeCodec";
+import { JsonTopicCodec } from "./codec/jsonTopicCodec";
+
+type RelayPreviewOptions = {
+  peerId?: string;
+  namespace?: string;
+  signalingUrl?: string;
+  signalingUrls?: string[];
+  room?: string;
+  seedPeers?: string[];
+  bootstrapHints?: string[];
+  bootstrapSources?: string[];
+  maxMessageBytes?: number;
+  pollIntervalMs?: number;
+  maxFutureDriftMs?: number;
+  maxPastDriftMs?: number;
+};
+
+type RelayPeer = {
+  peer_id: string;
+  status: "online";
+  first_seen_at: number;
+  last_seen_at: number;
+  messages_seen: number;
+  reconnect_attempts: number;
+};
+
+type RelayDiagnostics = {
+  adapter: "relay-preview";
+  peer_id: string;
+  namespace: string;
+  room: string;
+  signaling_url: string;
+  signaling_endpoints: string[];
+  bootstrap_sources: string[];
+  seed_peers_count: number;
+  bootstrap_hints_count: number;
+  discovery_events_total: number;
+  last_discovery_event_at: number;
+  discovery_events: Array<{
+    id: string;
+    type: string;
+    at: number;
+    peer_id?: string;
+    endpoint?: string;
+    detail?: string;
+  }>;
+  signaling_messages_sent_total: number;
+  signaling_messages_received_total: number;
+  reconnect_attempts_total: number;
+  active_webrtc_peers: number;
+  components: {
+    transport: string;
+    discovery: string;
+    envelope_codec: string;
+    topic_codec: string;
+  };
+  limits: {
+    max_message_bytes: number;
+    max_future_drift_ms: number;
+    max_past_drift_ms: number;
+  };
+  config: {
+    started: boolean;
+    topic_handler_count: number;
+    poll_interval_ms: number;
+  };
+  peers: {
+    total: number;
+    online: number;
+    stale: number;
+    items: RelayPeer[];
+  };
+  stats: {
+    publish_attempted: number;
+    publish_sent: number;
+    received_total: number;
+    delivered_total: number;
+    dropped_malformed: number;
+    dropped_oversized: number;
+    dropped_namespace_mismatch: number;
+    dropped_timestamp_future_drift: number;
+    dropped_timestamp_past_drift: number;
+    dropped_decode_failed: number;
+    dropped_self: number;
+    dropped_topic_decode_error: number;
+    dropped_handler_error: number;
+    signaling_errors: number;
+    invalid_signaling_payload_total: number;
+    duplicate_sdp_total: number;
+    duplicate_ice_total: number;
+    start_errors: number;
+    stop_errors: number;
+    received_validated: number;
+  };
+};
+
+function dedupe(values: string[]): string[] {
+  return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)));
+}
+
+export class RelayPreviewAdapter implements NetworkAdapter {
+  private readonly peerId: string;
+  private readonly namespace: string;
+  private readonly signalingEndpoints: string[];
+  private readonly room: string;
+  private readonly seedPeers: string[];
+  private readonly bootstrapHints: string[];
+  private readonly bootstrapSources: string[];
+  private readonly maxMessageBytes: number;
+  private readonly pollIntervalMs: number;
+  private readonly maxFutureDriftMs: number;
+  private readonly maxPastDriftMs: number;
+  private readonly envelopeCodec: MessageEnvelopeCodec;
+  private readonly topicCodec: TopicCodec;
+
+  private started = false;
+  private poller: NodeJS.Timeout | null = null;
+  private handlers = new Map<string, Set<(data: any) => void>>();
+  private peers = new Map<string, RelayPeer>();
+  private seenMessageIds = new Set<string>();
+  private activeEndpoint = "";
+  private discoveryEvents: RelayDiagnostics["discovery_events"] = [];
+  private discoveryEventsTotal = 0;
+  private lastDiscoveryEventAt = 0;
+  private signalingMessagesSentTotal = 0;
+  private signalingMessagesReceivedTotal = 0;
+  private reconnectAttemptsTotal = 0;
+
+  private stats: RelayDiagnostics["stats"] = {
+    publish_attempted: 0,
+    publish_sent: 0,
+    received_total: 0,
+    delivered_total: 0,
+    dropped_malformed: 0,
+    dropped_oversized: 0,
+    dropped_namespace_mismatch: 0,
+    dropped_timestamp_future_drift: 0,
+    dropped_timestamp_past_drift: 0,
+    dropped_decode_failed: 0,
+    dropped_self: 0,
+    dropped_topic_decode_error: 0,
+    dropped_handler_error: 0,
+    signaling_errors: 0,
+    invalid_signaling_payload_total: 0,
+    duplicate_sdp_total: 0,
+    duplicate_ice_total: 0,
+    start_errors: 0,
+    stop_errors: 0,
+    received_validated: 0,
+  };
+
+  constructor(options: RelayPreviewOptions = {}) {
+    this.peerId = options.peerId ?? `peer-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+    this.namespace = String(options.namespace || "silicaclaw.preview").trim() || "silicaclaw.preview";
+    this.signalingEndpoints = dedupe(
+      (options.signalingUrls && options.signalingUrls.length > 0
+        ? options.signalingUrls
+        : [options.signalingUrl || "http://localhost:4510"])
+    );
+    this.activeEndpoint = this.signalingEndpoints[0] || "http://localhost:4510";
+    this.room = String(options.room || "silicaclaw-global-preview").trim() || "silicaclaw-global-preview";
+    this.seedPeers = dedupe(options.seedPeers || []);
+    this.bootstrapHints = dedupe(options.bootstrapHints || []);
+    this.bootstrapSources = dedupe(options.bootstrapSources || []);
+    this.maxMessageBytes = options.maxMessageBytes ?? 64 * 1024;
+    this.pollIntervalMs = options.pollIntervalMs ?? 2000;
+    this.maxFutureDriftMs = options.maxFutureDriftMs ?? 30_000;
+    this.maxPastDriftMs = options.maxPastDriftMs ?? 120_000;
+    this.envelopeCodec = new JsonMessageEnvelopeCodec();
+    this.topicCodec = new JsonTopicCodec();
+  }
+
+  async start(): Promise<void> {
+    if (this.started) return;
+    try {
+      await this.post("/join", { room: this.room, peer_id: this.peerId });
+      this.started = true;
+      await this.refreshPeers();
+      await this.pollOnce();
+      this.poller = setInterval(() => {
+        this.pollOnce().catch(() => {});
+      }, this.pollIntervalMs);
+      this.recordDiscovery("signaling_connected", { endpoint: this.activeEndpoint });
+    } catch (error) {
+      this.stats.start_errors += 1;
+      throw new Error(`Relay start failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (!this.started) return;
+    if (this.poller) {
+      clearInterval(this.poller);
+      this.poller = null;
+    }
+    try {
+      await this.post("/leave", { room: this.room, peer_id: this.peerId });
+    } catch {
+      this.stats.stop_errors += 1;
+    }
+    this.started = false;
+    this.recordDiscovery("signaling_disconnected", { endpoint: this.activeEndpoint });
+  }
+
+  async publish(topic: string, data: any): Promise<void> {
+    if (!this.started) return;
+    this.stats.publish_attempted += 1;
+    const envelope: NetworkMessageEnvelope = {
+      version: 1,
+      message_id: randomUUID(),
+      topic: `${this.namespace}:${topic}`,
+      source_peer_id: this.peerId,
+      timestamp: Date.now(),
+      payload: this.topicCodec.encode(topic, data),
+    };
+    const raw = this.envelopeCodec.encode(envelope);
+    if (raw.length > this.maxMessageBytes) {
+      this.stats.dropped_oversized += 1;
+      return;
+    }
+    await this.post("/relay/publish", { room: this.room, peer_id: this.peerId, envelope });
+    this.stats.publish_sent += 1;
+    this.signalingMessagesSentTotal += 1;
+  }
+
+  subscribe(topic: string, handler: (data: any) => void): void {
+    const key = `${this.namespace}:${topic}`;
+    if (!this.handlers.has(key)) {
+      this.handlers.set(key, new Set());
+    }
+    this.handlers.get(key)?.add(handler);
+  }
+
+  getDiagnostics(): RelayDiagnostics {
+    const peerItems = Array.from(this.peers.values()).sort((a, b) => b.last_seen_at - a.last_seen_at);
+    return {
+      adapter: "relay-preview",
+      peer_id: this.peerId,
+      namespace: this.namespace,
+      room: this.room,
+      signaling_url: this.activeEndpoint,
+      signaling_endpoints: this.signalingEndpoints,
+      bootstrap_sources: this.bootstrapSources,
+      seed_peers_count: this.seedPeers.length,
+      bootstrap_hints_count: this.bootstrapHints.length,
+      discovery_events_total: this.discoveryEventsTotal,
+      last_discovery_event_at: this.lastDiscoveryEventAt,
+      discovery_events: this.discoveryEvents,
+      signaling_messages_sent_total: this.signalingMessagesSentTotal,
+      signaling_messages_received_total: this.signalingMessagesReceivedTotal,
+      reconnect_attempts_total: this.reconnectAttemptsTotal,
+      active_webrtc_peers: peerItems.length,
+      components: {
+        transport: "HttpRelayTransport",
+        discovery: "RelayRoomPeerList",
+        envelope_codec: this.envelopeCodec.constructor.name,
+        topic_codec: this.topicCodec.constructor.name,
+      },
+      limits: {
+        max_message_bytes: this.maxMessageBytes,
+        max_future_drift_ms: this.maxFutureDriftMs,
+        max_past_drift_ms: this.maxPastDriftMs,
+      },
+      config: {
+        started: this.started,
+        topic_handler_count: this.handlers.size,
+        poll_interval_ms: this.pollIntervalMs,
+      },
+      peers: {
+        total: peerItems.length,
+        online: peerItems.length,
+        stale: 0,
+        items: peerItems,
+      },
+      stats: { ...this.stats },
+    };
+  }
+
+  private async pollOnce(): Promise<void> {
+    const payload = await this.get(`/relay/poll?room=${encodeURIComponent(this.room)}&peer_id=${encodeURIComponent(this.peerId)}`);
+    const messages = Array.isArray(payload?.messages) ? payload.messages : [];
+    for (const message of messages) {
+      this.signalingMessagesReceivedTotal += 1;
+      this.onEnvelope(message?.envelope);
+    }
+    await this.refreshPeers();
+  }
+
+  private async refreshPeers(): Promise<void> {
+    const payload = await this.get(`/peers?room=${encodeURIComponent(this.room)}`);
+    const peerIds = Array.isArray(payload?.peers) ? payload.peers.map((value: unknown) => String(value || "").trim()).filter(Boolean) : [];
+    const now = Date.now();
+    const next = new Map<string, RelayPeer>();
+    for (const peerId of peerIds) {
+      if (peerId === this.peerId) continue;
+      const existing = this.peers.get(peerId);
+      if (!existing) {
+        this.recordDiscovery("peer_joined", { peer_id: peerId });
+      }
+      next.set(peerId, {
+        peer_id: peerId,
+        status: "online",
+        first_seen_at: existing?.first_seen_at ?? now,
+        last_seen_at: now,
+        messages_seen: existing?.messages_seen ?? 0,
+        reconnect_attempts: existing?.reconnect_attempts ?? 0,
+      });
+    }
+    for (const peerId of this.peers.keys()) {
+      if (!next.has(peerId)) {
+        this.recordDiscovery("peer_removed", { peer_id: peerId });
+      }
+    }
+    this.peers = next;
+  }
+
+  private onEnvelope(envelope: unknown): void {
+    this.stats.received_total += 1;
+    const validated = validateNetworkMessageEnvelope(envelope, {
+      max_future_drift_ms: this.maxFutureDriftMs,
+      max_past_drift_ms: this.maxPastDriftMs,
+    });
+    if (!validated.ok || !validated.envelope) {
+      if (validated.reason === "timestamp_future_drift") {
+        this.stats.dropped_timestamp_future_drift += 1;
+      } else if (validated.reason === "timestamp_past_drift") {
+        this.stats.dropped_timestamp_past_drift += 1;
+      } else {
+        this.stats.dropped_malformed += 1;
+      }
+      return;
+    }
+    const message = validated.envelope;
+    if (message.source_peer_id === this.peerId) {
+      this.stats.dropped_self += 1;
+      return;
+    }
+    if (!message.topic.startsWith(`${this.namespace}:`)) {
+      this.stats.dropped_namespace_mismatch += 1;
+      return;
+    }
+    if (this.seenMessageIds.has(message.message_id)) {
+      return;
+    }
+    this.seenMessageIds.add(message.message_id);
+    if (this.seenMessageIds.size > 10000) {
+      const first = this.seenMessageIds.values().next().value;
+      if (first) this.seenMessageIds.delete(first);
+    }
+    this.stats.received_validated += 1;
+
+    const topicKey = message.topic;
+    const topic = topicKey.slice(this.namespace.length + 1);
+    const handlers = this.handlers.get(topicKey);
+    if (!handlers || handlers.size === 0) return;
+
+    const peer = this.peers.get(message.source_peer_id);
+    if (peer) {
+      peer.last_seen_at = Date.now();
+      peer.messages_seen += 1;
+    }
+
+    let payload: unknown;
+    try {
+      payload = this.topicCodec.decode(topic, message.payload);
+    } catch {
+      this.stats.dropped_topic_decode_error += 1;
+      return;
+    }
+    for (const handler of handlers) {
+      try {
+        handler(payload);
+        this.stats.delivered_total += 1;
+      } catch {
+        this.stats.dropped_handler_error += 1;
+      }
+    }
+  }
+
+  private recordDiscovery(type: string, extra: { peer_id?: string; endpoint?: string; detail?: string } = {}): void {
+    const event = {
+      id: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      type,
+      at: Date.now(),
+      ...extra,
+    };
+    this.discoveryEvents.unshift(event);
+    this.discoveryEvents = this.discoveryEvents.slice(0, 200);
+    this.discoveryEventsTotal += 1;
+    this.lastDiscoveryEventAt = event.at;
+  }
+
+  private async get(path: string): Promise<any> {
+    const endpoint = this.activeEndpoint.replace(/\/+$/, "");
+    const response = await fetch(`${endpoint}${path}`);
+    if (!response.ok) {
+      this.stats.signaling_errors += 1;
+      throw new Error(`Relay GET failed (${response.status})`);
+    }
+    return response.json();
+  }
+
+  private async post(path: string, body: any): Promise<any> {
+    const endpoint = this.activeEndpoint.replace(/\/+$/, "");
+    const response = await fetch(`${endpoint}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+      this.stats.signaling_errors += 1;
+      throw new Error(`Relay POST failed (${response.status})`);
+    }
+    return response.json();
+  }
+}

package/packages/storage/dist/socialRuntimeRepo.js

@@ -14,13 +14,13 @@ function emptyRuntime() {
         resolved_identity: null,
         resolved_profile: null,
         resolved_network: {
-            mode: "lan",
-            adapter: "real-preview",
+            mode: "global-preview",
+            adapter: "relay-preview",
             namespace: "silicaclaw.preview",
             port: null,
             signaling_url: "http://localhost:4510",
             signaling_urls: [],
-            room: "silicaclaw-room",
+            room: "silicaclaw-global-preview",
             seed_peers: [],
             bootstrap_hints: [],
             bootstrap_sources: [],

package/packages/storage/src/socialRuntimeRepo.ts

@@ -13,13 +13,13 @@ function emptyRuntime(): SocialRuntimeConfig {
     resolved_identity: null,
     resolved_profile: null,
     resolved_network: {
-      mode: "lan",
-      adapter: "real-preview",
+      mode: "global-preview",
+      adapter: "relay-preview",
       namespace: "silicaclaw.preview",
       port: null,
       signaling_url: "http://localhost:4510",
       signaling_urls: [],
-      room: "silicaclaw-room",
+      room: "silicaclaw-global-preview",
       seed_peers: [],
       bootstrap_hints: [],
       bootstrap_sources: [],

package/scripts/quickstart.sh

@@ -5,7 +5,7 @@ INVOKE_PWD="${INIT_CWD:-$PWD}"
 ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 WORK_DIR="$ROOT_DIR"
 IS_NPX_MODE=0
-DEFAULT_MODE_PICK="${QUICKSTART_DEFAULT_MODE:-1}"
+DEFAULT_MODE_PICK="${QUICKSTART_DEFAULT_MODE:-3}"
 CONNECT_MODE="${QUICKSTART_CONNECT_MODE:-0}"
 
 case "$DEFAULT_MODE_PICK" in
@@ -333,9 +333,9 @@ fi
 title "选择网络模式"
 echo "1) local           单机预览（最快）"
 echo "2) lan             局域网预览（A/B 双机）"
-echo "3) global-preview  非局域网预览（WebRTC）"
-echo "提示: 不确定就直接回车（默认 local）。"
-echo "提示: 只有在你已有可达 signaling 地址时，才选择 3。"
+echo "3) global-preview  互联网预览（Relay，推荐）"
+echo "提示: 不确定就直接回车（默认 global-preview）。"
+echo "提示: 互联网场景需要一个所有节点都可访问的 relay/signaling 地址。"
 if [ "$CONNECT_MODE" = "1" ]; then
   MODE_PICK="3"
   echo "connect 模式：已自动选择 global-preview。"
@@ -347,7 +347,7 @@ fi
 NETWORK_MODE="local"
 NETWORK_ADAPTER="local-event-bus"
 WEBRTC_SIGNALING_URL_VALUE=""
-WEBRTC_ROOM_VALUE="silicaclaw-demo"
+WEBRTC_ROOM_VALUE="silicaclaw-global-preview"
 AUTO_START_SIGNALING=0
 
 case "$MODE_PICK" in
@@ -357,7 +357,7 @@ case "$MODE_PICK" in
     ;;
   3)
     NETWORK_MODE="global-preview"
-    NETWORK_ADAPTER="webrtc-preview"
+    NETWORK_ADAPTER="relay-preview"
     PUBLIC_IP="$(detect_public_ip)"
     SIGNALING_DEFAULT="${WEBRTC_SIGNALING_URL:-http://localhost:4510}"
     if [ -n "$PUBLIC_IP" ]; then
@@ -374,7 +374,7 @@ case "$MODE_PICK" in
     read -r -p "请输入 signaling URL（默认 ${SIGNALING_DEFAULT}）: " WEBRTC_SIGNALING_URL_INPUT || true
     WEBRTC_SIGNALING_URL_VALUE="${WEBRTC_SIGNALING_URL_INPUT:-$SIGNALING_DEFAULT}"
     if [ -z "${WEBRTC_SIGNALING_URL_VALUE:-}" ]; then
-      echo "global-preview 必须提供 signaling URL"
+      echo "global-preview 必须提供公网可达的 signaling URL"
       exit 1
     fi
 
@@ -389,8 +389,8 @@ case "$MODE_PICK" in
       echo "将尝试以 PORT=$SIGNALING_PORT_VALUE 后台启动 signaling server"
     fi
 
-    read -r -p "请输入 room（默认 silicaclaw-demo）: " WEBRTC_ROOM_VALUE_INPUT || true
-    WEBRTC_ROOM_VALUE="${WEBRTC_ROOM_VALUE_INPUT:-silicaclaw-demo}"
+    read -r -p "请输入 room（默认 silicaclaw-global-preview）: " WEBRTC_ROOM_VALUE_INPUT || true
+    WEBRTC_ROOM_VALUE="${WEBRTC_ROOM_VALUE_INPUT:-silicaclaw-global-preview}"
     ;;
   *)
     NETWORK_MODE="local"

package/scripts/silicaclaw-cli.mjs

@@ -101,12 +101,12 @@ function showUpdateGuide(current, latest, beta) {
   }
   console.log("");
   console.log("Quick next commands:");
-  console.log("1) Start local gateway");
-  console.log("   silicaclaw start --mode=local");
+  console.log("1) Start internet gateway");
+  console.log("   silicaclaw start --mode=global-preview --signaling-url=https://your-relay.example");
   console.log("2) Check gateway status");
   console.log("   silicaclaw status");
   console.log("3) npx one-shot (no alias/global install)");
-  console.log("   npx -y @silicaclaw/cli@beta start --mode=local");
+  console.log("   npx -y @silicaclaw/cli@beta start --mode=global-preview --signaling-url=https://your-relay.example");
   console.log("");
 
   const writableGlobal = canWriteGlobalPrefix();

package/scripts/silicaclaw-gateway.mjs

@@ -128,7 +128,7 @@ function parseMode(raw) {
 
 function adapterForMode(mode) {
   if (mode === "lan") return "real-preview";
-  if (mode === "global-preview") return "webrtc-preview";
+  if (mode === "global-preview") return "relay-preview";
   return "local-event-bus";
 }
 
@@ -185,7 +185,8 @@ Usage:
 Notes:
   - Default app dir: current directory; fallback: ~/silicaclaw
   - State dir: .silicaclaw/gateway
-  - global-preview + localhost signaling URL will auto-start signaling server
+  - global-preview is internet-first and expects a publicly reachable relay/signaling URL
+  - global-preview + localhost signaling URL will auto-start signaling server for single-machine testing
 `.trim());
 }
 
@@ -309,7 +310,7 @@ async function stopAll() {
 function startAll() {
   ensureStateDir();
 
-  const mode = parseMode(parseFlag("mode", process.env.NETWORK_MODE || "local"));
+  const mode = parseMode(parseFlag("mode", process.env.NETWORK_MODE || "global-preview"));
   const adapter = adapterForMode(mode);
   const signalingUrl = parseFlag("signaling-url", process.env.WEBRTC_SIGNALING_URL || "http://localhost:4510");
   const room = parseFlag("room", process.env.WEBRTC_ROOM || "silicaclaw-demo");

package/scripts/webrtc-signaling-server.mjs

@@ -6,7 +6,7 @@ const port = Number(process.env.PORT || process.env.WEBRTC_SIGNALING_PORT || 451
 const PEER_STALE_MS = Number(process.env.WEBRTC_SIGNALING_PEER_STALE_MS || 120000);
 const SIGNAL_DEDUPE_WINDOW_MS = Number(process.env.WEBRTC_SIGNALING_DEDUPE_WINDOW_MS || 60000);
 
-/** @type {Map<string, {peers: Map<string, {last_seen_at:number}>, queues: Map<string, any[]>, signal_fingerprints: Map<string, number>}>} */
+/** @type {Map<string, {peers: Map<string, {last_seen_at:number}>, queues: Map<string, any[]>, relay_queues: Map<string, any[]>, signal_fingerprints: Map<string, number>}>} */
 const rooms = new Map();
 
 const counters = {
@@ -24,6 +24,7 @@ function getRoom(roomId) {
     rooms.set(id, {
       peers: new Map(),
       queues: new Map(),
+      relay_queues: new Map(),
       signal_fingerprints: new Map(),
     });
   }
@@ -73,6 +74,7 @@ function cleanupRoom(roomId) {
     if (peer.last_seen_at < threshold) {
       room.peers.delete(peerId);
       room.queues.delete(peerId);
+      room.relay_queues.delete(peerId);
       counters.stale_peers_cleaned_total += 1;
     }
   }
@@ -96,6 +98,9 @@ function touchPeer(room, peerId) {
   if (!room.queues.has(peerId)) {
     room.queues.set(peerId, []);
   }
+  if (!room.relay_queues.has(peerId)) {
+    room.relay_queues.set(peerId, []);
+  }
 }
 
 function isValidSignalPayload(body) {
@@ -168,6 +173,23 @@ const server = http.createServer(async (req, res) => {
     return json(res, 200, { ok: true, messages: queue });
   }
 
+  if (req.method === 'GET' && url.pathname === '/relay/poll') {
+    const roomId = String(url.searchParams.get('room') || 'silicaclaw-room');
+    const peerId = String(url.searchParams.get('peer_id') || '');
+    if (!peerId) {
+      counters.invalid_payload_total += 1;
+      return json(res, 400, { ok: false, error: 'missing_peer_id' });
+    }
+
+    const room = getRoom(roomId);
+    touchPeer(room, peerId);
+    cleanupRoom(roomId);
+
+    const queue = room.relay_queues.get(peerId) || [];
+    room.relay_queues.set(peerId, []);
+    return json(res, 200, { ok: true, messages: queue });
+  }
+
   if (req.method === 'POST' && url.pathname === '/join') {
     const body = await parseBody(req);
     const roomId = String(body.room || 'silicaclaw-room');
@@ -193,6 +215,7 @@ const server = http.createServer(async (req, res) => {
     if (peerId) {
       room.peers.delete(peerId);
       room.queues.delete(peerId);
+      room.relay_queues.delete(peerId);
       counters.leave_total += 1;
     } else {
       counters.invalid_payload_total += 1;
@@ -240,6 +263,34 @@ const server = http.createServer(async (req, res) => {
     return json(res, 200, { ok: true });
   }
 
+  if (req.method === 'POST' && url.pathname === '/relay/publish') {
+    const body = await parseBody(req);
+    const roomId = String(body.room || 'silicaclaw-room');
+    const peerId = String(body.peer_id || '');
+    const envelope = body.envelope;
+    if (!peerId || typeof envelope !== 'object' || envelope === null) {
+      counters.invalid_payload_total += 1;
+      return json(res, 400, { ok: false, error: 'invalid_relay_payload' });
+    }
+
+    const room = getRoom(roomId);
+    touchPeer(room, peerId);
+
+    for (const targetPeerId of room.peers.keys()) {
+      if (targetPeerId === peerId) continue;
+      if (!room.relay_queues.has(targetPeerId)) room.relay_queues.set(targetPeerId, []);
+      room.relay_queues.get(targetPeerId).push({
+        id: String(body.id || randomUUID()),
+        room: roomId,
+        from_peer_id: peerId,
+        envelope,
+        at: now(),
+      });
+    }
+
+    return json(res, 200, { ok: true, delivered_to: Math.max(0, room.peers.size - 1) });
+  }
+
   return json(res, 404, { ok: false, error: 'not_found' });
 });