@silicaclaw/cli 2026.3.19-9 → 2026.3.20-10

package/packages/core/src/types.ts

@@ -5,12 +5,19 @@ export type AgentIdentity = {
   created_at: number;
 };
 
+export type PrivateEncryptionKeyPair = {
+  public_key: string;
+  private_key: string;
+  created_at: number;
+};
+
 export type PublicProfile = {
   agent_id: string;
   display_name: string;
   bio: string;
   tags: string[];
   avatar_url?: string;
+  private_encryption_public_key?: string;
   public_enabled: boolean;
   updated_at: number;
   signature: string;
@@ -58,6 +65,43 @@ export type SocialMessageObservationRecord = {
   signature: string;
 };
 
+export type PrivateMessageRecord = {
+  type: "private.message";
+  message_id: string;
+  conversation_id: string;
+  from_agent_id: string;
+  to_agent_id: string;
+  sender_public_key: string;
+  sender_encryption_public_key: string;
+  recipient_encryption_public_key: string;
+  cipher_scheme: "nacl-box-v1";
+  ciphertext: string;
+  nonce: string;
+  created_at: number;
+  signature: string;
+};
+
+export type PrivateMessageReceiptRecord = {
+  type: "private.message.receipt";
+  receipt_id: string;
+  message_id: string;
+  conversation_id: string;
+  from_agent_id: string;
+  to_agent_id: string;
+  sender_public_key: string;
+  status: "received" | "read";
+  created_at: number;
+  signature: string;
+};
+
+export type PrivateConversationSummary = {
+  conversation_id: string;
+  peer_agent_id: string;
+  last_message_at: number | null;
+  last_message_preview: string;
+  unread_count: number;
+};
+
 export type DirectoryState = {
   profiles: Record<string, PublicProfile>;
   presence: Record<string, number>;

package/packages/network/dist/config/silicaclaw-defaults.json

@@ -0,0 +1,19 @@
+{
+    "ports": {
+        "local_console": 4310,
+        "public_explorer": 4311,
+        "openclaw_gateway": 18789,
+        "network_default": 44123
+    },
+    "network": {
+        "default_mode": "global-preview",
+        "default_namespace": "silicaclaw.preview",
+        "global_preview": {
+            "relay_url": "https://relay.silicaclaw.com",
+            "room": "silicaclaw-global-preview"
+        }
+    },
+    "bridge": {
+        "api_base": "http://localhost:4310"
+    }
+}

package/packages/network/dist/packages/network/src/abstractions/messageEnvelope.d.ts

@@ -0,0 +1,28 @@
+export type NetworkMessageEnvelope<TPayload = unknown> = {
+    version: 1;
+    message_id: string;
+    topic: string;
+    source_peer_id: string;
+    timestamp: number;
+    payload: TPayload;
+};
+export type DecodedNetworkMessage = {
+    envelope: NetworkMessageEnvelope;
+    raw: Buffer;
+};
+export interface MessageEnvelopeCodec {
+    encode(envelope: NetworkMessageEnvelope): Buffer;
+    decode(raw: Buffer): DecodedNetworkMessage | null;
+}
+export type EnvelopeValidationOptions = {
+    now?: number;
+    max_future_drift_ms: number;
+    max_past_drift_ms: number;
+};
+export type EnvelopeValidationResult = {
+    ok: boolean;
+    reason?: "not_object" | "invalid_version" | "invalid_message_id" | "invalid_topic" | "invalid_source_peer_id" | "invalid_timestamp" | "missing_payload" | "timestamp_future_drift" | "timestamp_past_drift";
+    envelope?: NetworkMessageEnvelope;
+    drift_ms?: number;
+};
+export declare function validateNetworkMessageEnvelope(value: unknown, options: EnvelopeValidationOptions): EnvelopeValidationResult;

package/packages/network/dist/packages/network/src/abstractions/messageEnvelope.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateNetworkMessageEnvelope = validateNetworkMessageEnvelope;
+function validateNetworkMessageEnvelope(value, options) {
+    if (typeof value !== "object" || value === null) {
+        return { ok: false, reason: "not_object" };
+    }
+    const envelope = value;
+    if (envelope.version !== 1) {
+        return { ok: false, reason: "invalid_version" };
+    }
+    if (typeof envelope.message_id !== "string" || envelope.message_id.trim().length === 0) {
+        return { ok: false, reason: "invalid_message_id" };
+    }
+    if (typeof envelope.topic !== "string" || envelope.topic.trim().length === 0) {
+        return { ok: false, reason: "invalid_topic" };
+    }
+    if (typeof envelope.source_peer_id !== "string" || envelope.source_peer_id.trim().length === 0) {
+        return { ok: false, reason: "invalid_source_peer_id" };
+    }
+    if (!Number.isFinite(envelope.timestamp)) {
+        return { ok: false, reason: "invalid_timestamp" };
+    }
+    if (!("payload" in envelope)) {
+        return { ok: false, reason: "missing_payload" };
+    }
+    const now = options.now ?? Date.now();
+    const drift = Number(envelope.timestamp) - now;
+    if (drift > options.max_future_drift_ms) {
+        return { ok: false, reason: "timestamp_future_drift", drift_ms: drift };
+    }
+    if (drift < -options.max_past_drift_ms) {
+        return { ok: false, reason: "timestamp_past_drift", drift_ms: drift };
+    }
+    return { ok: true, envelope: envelope, drift_ms: drift };
+}

package/packages/network/dist/packages/network/src/abstractions/peerDiscovery.d.ts

@@ -0,0 +1,43 @@
+import { NetworkMessageEnvelope } from "./messageEnvelope";
+export type PeerStatus = "online" | "stale";
+export type PeerSnapshot = {
+    peer_id: string;
+    first_seen_at: number;
+    last_seen_at: number;
+    status: PeerStatus;
+    stale_since_at?: number;
+    messages_seen: number;
+    meta?: Record<string, unknown>;
+};
+export type PeerDiscoveryContext = {
+    self_peer_id: string;
+    publishControl: (topic: string, payload: unknown) => Promise<void>;
+};
+export type PeerDiscoveryStats = {
+    observe_calls: number;
+    peers_added: number;
+    peers_removed: number;
+    peers_marked_stale: number;
+    heartbeat_sent: number;
+    heartbeat_send_errors: number;
+    reconcile_runs: number;
+    last_observed_at: number;
+    last_heartbeat_at: number;
+    last_reconcile_at: number;
+    last_error_at: number;
+};
+export type PeerDiscoveryConfigSnapshot = {
+    discovery: string;
+    heartbeat_topic?: string;
+    heartbeat_interval_ms?: number;
+    stale_after_ms?: number;
+    remove_after_ms?: number;
+};
+export interface PeerDiscovery {
+    start(context: PeerDiscoveryContext): Promise<void>;
+    stop(): Promise<void>;
+    observeEnvelope(envelope: NetworkMessageEnvelope): void;
+    listPeers(): PeerSnapshot[];
+    getStats?(): PeerDiscoveryStats;
+    getConfig?(): PeerDiscoveryConfigSnapshot;
+}

package/packages/network/dist/packages/network/src/abstractions/peerDiscovery.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/packages/network/dist/packages/network/src/abstractions/topicCodec.d.ts

@@ -0,0 +1,4 @@
+export interface TopicCodec {
+    encode(topic: string, payload: unknown): unknown;
+    decode(topic: string, payload: unknown): unknown;
+}

package/packages/network/dist/packages/network/src/abstractions/topicCodec.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/packages/network/dist/packages/network/src/abstractions/transport.d.ts

@@ -0,0 +1,36 @@
+export type TransportMessageMeta = {
+    remote_address: string;
+    remote_port: number;
+    transport: string;
+};
+export type TransportLifecycleState = "stopped" | "starting" | "running" | "stopping" | "error";
+export type TransportStats = {
+    starts: number;
+    stops: number;
+    start_errors: number;
+    stop_errors: number;
+    sent_messages: number;
+    sent_bytes: number;
+    send_errors: number;
+    received_messages: number;
+    received_bytes: number;
+    receive_errors: number;
+    last_sent_at: number;
+    last_received_at: number;
+    last_error_at: number;
+};
+export type TransportConfigSnapshot = {
+    transport: string;
+    state: TransportLifecycleState;
+    bind_address?: string;
+    broadcast_address?: string;
+    port?: number;
+};
+export interface NetworkTransport {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(data: Buffer): Promise<void>;
+    onMessage(handler: (data: Buffer, meta: TransportMessageMeta) => void): () => void;
+    getStats?(): TransportStats;
+    getConfig?(): TransportConfigSnapshot;
+}

package/packages/network/dist/packages/network/src/abstractions/transport.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/packages/network/dist/packages/network/src/codec/jsonMessageEnvelopeCodec.d.ts

@@ -0,0 +1,5 @@
+import { DecodedNetworkMessage, MessageEnvelopeCodec, NetworkMessageEnvelope } from "../abstractions/messageEnvelope";
+export declare class JsonMessageEnvelopeCodec implements MessageEnvelopeCodec {
+    encode(envelope: NetworkMessageEnvelope): Buffer;
+    decode(raw: Buffer): DecodedNetworkMessage | null;
+}

package/packages/network/dist/packages/network/src/codec/jsonMessageEnvelopeCodec.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonMessageEnvelopeCodec = void 0;
+class JsonMessageEnvelopeCodec {
+    encode(envelope) {
+        return Buffer.from(JSON.stringify(envelope), "utf8");
+    }
+    decode(raw) {
+        try {
+            const parsed = JSON.parse(raw.toString("utf8"));
+            if (typeof parsed !== "object" || parsed === null) {
+                return null;
+            }
+            return {
+                envelope: parsed,
+                raw,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.JsonMessageEnvelopeCodec = JsonMessageEnvelopeCodec;

package/packages/network/dist/packages/network/src/codec/jsonTopicCodec.d.ts

@@ -0,0 +1,5 @@
+import { TopicCodec } from "../abstractions/topicCodec";
+export declare class JsonTopicCodec implements TopicCodec {
+    encode(_topic: string, payload: unknown): unknown;
+    decode(_topic: string, payload: unknown): unknown;
+}

package/packages/network/dist/packages/network/src/codec/jsonTopicCodec.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonTopicCodec = void 0;
+class JsonTopicCodec {
+    encode(_topic, payload) {
+        return payload;
+    }
+    decode(_topic, payload) {
+        return payload;
+    }
+}
+exports.JsonTopicCodec = JsonTopicCodec;

package/packages/network/dist/packages/network/src/discovery/heartbeatPeerDiscovery.d.ts

@@ -0,0 +1,28 @@
+import { PeerDiscovery, PeerDiscoveryConfigSnapshot, PeerDiscoveryContext, PeerDiscoveryStats, PeerSnapshot } from "../abstractions/peerDiscovery";
+import { NetworkMessageEnvelope } from "../abstractions/messageEnvelope";
+type HeartbeatPeerDiscoveryOptions = {
+    heartbeatIntervalMs?: number;
+    staleAfterMs?: number;
+    removeAfterMs?: number;
+    topic?: string;
+};
+export declare class HeartbeatPeerDiscovery implements PeerDiscovery {
+    private peers;
+    private timer;
+    private context;
+    private heartbeatIntervalMs;
+    private staleAfterMs;
+    private removeAfterMs;
+    private topic;
+    private stats;
+    constructor(options?: HeartbeatPeerDiscoveryOptions);
+    start(context: PeerDiscoveryContext): Promise<void>;
+    stop(): Promise<void>;
+    observeEnvelope(envelope: NetworkMessageEnvelope): void;
+    listPeers(): PeerSnapshot[];
+    getStats(): PeerDiscoveryStats;
+    getConfig(): PeerDiscoveryConfigSnapshot;
+    private sendHeartbeat;
+    private reconcilePeerHealth;
+}
+export {};

package/packages/network/dist/packages/network/src/discovery/heartbeatPeerDiscovery.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeartbeatPeerDiscovery = void 0;
+class HeartbeatPeerDiscovery {
+    peers = new Map();
+    timer = null;
+    context = null;
+    heartbeatIntervalMs;
+    staleAfterMs;
+    removeAfterMs;
+    topic;
+    stats = {
+        observe_calls: 0,
+        peers_added: 0,
+        peers_removed: 0,
+        peers_marked_stale: 0,
+        heartbeat_sent: 0,
+        heartbeat_send_errors: 0,
+        reconcile_runs: 0,
+        last_observed_at: 0,
+        last_heartbeat_at: 0,
+        last_reconcile_at: 0,
+        last_error_at: 0,
+    };
+    constructor(options = {}) {
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? 12_000;
+        this.staleAfterMs = options.staleAfterMs ?? 45_000;
+        this.removeAfterMs = options.removeAfterMs ?? 180_000;
+        this.topic = options.topic ?? "__discovery/heartbeat";
+    }
+    async start(context) {
+        this.context = context;
+        this.reconcilePeerHealth();
+        await this.sendHeartbeat();
+        this.timer = setInterval(async () => {
+            await this.sendHeartbeat();
+            this.reconcilePeerHealth();
+        }, this.heartbeatIntervalMs);
+    }
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    observeEnvelope(envelope) {
+        this.stats.observe_calls += 1;
+        this.stats.last_observed_at = Date.now();
+        if (!this.context) {
+            return;
+        }
+        if (envelope.source_peer_id === this.context.self_peer_id) {
+            return;
+        }
+        const now = Date.now();
+        const existing = this.peers.get(envelope.source_peer_id);
+        if (!existing) {
+            this.stats.peers_added += 1;
+        }
+        this.peers.set(envelope.source_peer_id, {
+            peer_id: envelope.source_peer_id,
+            first_seen_at: existing?.first_seen_at ?? now,
+            last_seen_at: now,
+            status: "online",
+            stale_since_at: undefined,
+            messages_seen: (existing?.messages_seen ?? 0) + 1,
+            meta: envelope.topic === this.topic && typeof envelope.payload === "object" && envelope.payload !== null
+                ? envelope.payload
+                : existing?.meta,
+        });
+    }
+    listPeers() {
+        this.reconcilePeerHealth();
+        return Array.from(this.peers.values()).sort((a, b) => {
+            const score = (p) => (p.status === "online" ? 1 : 0);
+            const byStatus = score(b) - score(a);
+            if (byStatus !== 0) {
+                return byStatus;
+            }
+            return b.last_seen_at - a.last_seen_at;
+        });
+    }
+    getStats() {
+        return { ...this.stats };
+    }
+    getConfig() {
+        return {
+            discovery: "heartbeat-peer-discovery",
+            heartbeat_topic: this.topic,
+            heartbeat_interval_ms: this.heartbeatIntervalMs,
+            stale_after_ms: this.staleAfterMs,
+            remove_after_ms: this.removeAfterMs,
+        };
+    }
+    async sendHeartbeat() {
+        if (!this.context) {
+            return;
+        }
+        try {
+            await this.context.publishControl(this.topic, {
+                kind: "heartbeat",
+                at: Date.now(),
+            });
+            this.stats.heartbeat_sent += 1;
+            this.stats.last_heartbeat_at = Date.now();
+        }
+        catch {
+            this.stats.heartbeat_send_errors += 1;
+            this.stats.last_error_at = Date.now();
+        }
+    }
+    reconcilePeerHealth() {
+        const now = Date.now();
+        this.stats.reconcile_runs += 1;
+        this.stats.last_reconcile_at = now;
+        for (const [peerId, peer] of this.peers.entries()) {
+            const age = now - peer.last_seen_at;
+            if (age > this.removeAfterMs) {
+                this.peers.delete(peerId);
+                this.stats.peers_removed += 1;
+                continue;
+            }
+            if (age > this.staleAfterMs) {
+                if (peer.status !== "stale") {
+                    this.stats.peers_marked_stale += 1;
+                }
+                this.peers.set(peerId, {
+                    ...peer,
+                    status: "stale",
+                    stale_since_at: peer.stale_since_at ?? now,
+                });
+                continue;
+            }
+            if (peer.status !== "online") {
+                this.peers.set(peerId, {
+                    ...peer,
+                    status: "online",
+                    stale_since_at: undefined,
+                });
+            }
+        }
+    }
+}
+exports.HeartbeatPeerDiscovery = HeartbeatPeerDiscovery;

package/packages/network/dist/packages/network/src/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./types";
+export * from "./mock";
+export * from "./localEventBus";
+export * from "./realPreview";
+export * from "./webrtcPreview";
+export * from "./relayPreview";
+export * from "./abstractions/messageEnvelope";
+export * from "./abstractions/topicCodec";
+export * from "./abstractions/transport";
+export * from "./abstractions/peerDiscovery";
+export * from "./codec/jsonMessageEnvelopeCodec";
+export * from "./codec/jsonTopicCodec";
+export * from "./discovery/heartbeatPeerDiscovery";
+export * from "./transport/udpLanBroadcastTransport";

package/packages/network/dist/packages/network/src/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./mock"), exports);
+__exportStar(require("./localEventBus"), exports);
+__exportStar(require("./realPreview"), exports);
+__exportStar(require("./webrtcPreview"), exports);
+__exportStar(require("./relayPreview"), exports);
+__exportStar(require("./abstractions/messageEnvelope"), exports);
+__exportStar(require("./abstractions/topicCodec"), exports);
+__exportStar(require("./abstractions/transport"), exports);
+__exportStar(require("./abstractions/peerDiscovery"), exports);
+__exportStar(require("./codec/jsonMessageEnvelopeCodec"), exports);
+__exportStar(require("./codec/jsonTopicCodec"), exports);
+__exportStar(require("./discovery/heartbeatPeerDiscovery"), exports);
+__exportStar(require("./transport/udpLanBroadcastTransport"), exports);

package/packages/network/dist/packages/network/src/localEventBus.d.ts

@@ -0,0 +1,9 @@
+import { NetworkAdapter } from "./types";
+export declare class LocalEventBusAdapter implements NetworkAdapter {
+    private started;
+    private emitter;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    publish(topic: string, data: any): Promise<void>;
+    subscribe(topic: string, handler: (data: any) => void): void;
+}

package/packages/network/dist/packages/network/src/localEventBus.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalEventBusAdapter = void 0;
+const events_1 = require("events");
+const CHANNEL_NAME = "silicaclaw-local-event-bus";
+function getNodeBus() {
+    const g = globalThis;
+    if (!g.__silicaclaw_bus) {
+        g.__silicaclaw_bus = new events_1.EventEmitter();
+    }
+    return g.__silicaclaw_bus;
+}
+class LocalEventBusAdapter {
+    started = false;
+    emitter = getNodeBus();
+    async start() {
+        this.started = true;
+    }
+    async stop() {
+        this.started = false;
+    }
+    async publish(topic, data) {
+        if (!this.started) {
+            return;
+        }
+        if (typeof BroadcastChannel !== "undefined") {
+            const channel = new BroadcastChannel(CHANNEL_NAME);
+            channel.postMessage({ topic, data });
+            channel.close();
+            return;
+        }
+        setImmediate(() => this.emitter.emit(topic, data));
+    }
+    subscribe(topic, handler) {
+        if (typeof BroadcastChannel !== "undefined") {
+            const channel = new BroadcastChannel(CHANNEL_NAME);
+            channel.onmessage = (event) => {
+                if (event.data?.topic === topic) {
+                    handler(event.data.data);
+                }
+            };
+            return;
+        }
+        this.emitter.on(topic, handler);
+    }
+}
+exports.LocalEventBusAdapter = LocalEventBusAdapter;

package/packages/network/dist/packages/network/src/mock.d.ts

@@ -0,0 +1,8 @@
+import { NetworkAdapter } from "./types";
+export declare class MockNetworkAdapter implements NetworkAdapter {
+    private started;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    publish(topic: string, data: any): Promise<void>;
+    subscribe(topic: string, handler: (data: any) => void): void;
+}

package/packages/network/dist/packages/network/src/mock.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockNetworkAdapter = void 0;
+const events_1 = require("events");
+const bus = new events_1.EventEmitter();
+class MockNetworkAdapter {
+    started = false;
+    async start() {
+        this.started = true;
+    }
+    async stop() {
+        this.started = false;
+    }
+    async publish(topic, data) {
+        if (!this.started) {
+            return;
+        }
+        setImmediate(() => bus.emit(topic, data));
+    }
+    subscribe(topic, handler) {
+        bus.on(topic, handler);
+    }
+}
+exports.MockNetworkAdapter = MockNetworkAdapter;