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

package/packages/network/dist/realPreview.d.ts

@@ -0,0 +1,105 @@
+import { NetworkAdapter } from "./types";
+import { MessageEnvelopeCodec } from "./abstractions/messageEnvelope";
+import { TopicCodec } from "./abstractions/topicCodec";
+import { NetworkTransport } from "./abstractions/transport";
+import { PeerDiscovery, PeerSnapshot } from "./abstractions/peerDiscovery";
+type RealNetworkAdapterPreviewOptions = {
+    peerId?: string;
+    namespace?: string;
+    transport?: NetworkTransport;
+    envelopeCodec?: MessageEnvelopeCodec;
+    topicCodec?: TopicCodec;
+    peerDiscovery?: PeerDiscovery;
+    maxMessageBytes?: number;
+    dedupeWindowMs?: number;
+    dedupeMaxEntries?: number;
+    maxFutureDriftMs?: number;
+    maxPastDriftMs?: number;
+};
+type NetworkDiagnostics = {
+    adapter: string;
+    peer_id: string;
+    namespace: string;
+    components: {
+        transport: string;
+        discovery: string;
+        envelope_codec: string;
+        topic_codec: string;
+    };
+    limits: {
+        max_message_bytes: number;
+        dedupe_window_ms: number;
+        dedupe_max_entries: number;
+        max_future_drift_ms: number;
+        max_past_drift_ms: number;
+    };
+    config: {
+        started: boolean;
+        topic_handler_count: number;
+        transport: ReturnType<NonNullable<NetworkTransport["getConfig"]>> | null;
+        discovery: ReturnType<NonNullable<PeerDiscovery["getConfig"]>> | null;
+    };
+    peers: {
+        total: number;
+        online: number;
+        stale: number;
+        items: PeerSnapshot[];
+    };
+    stats: {
+        publish_attempted: number;
+        publish_sent: number;
+        received_total: number;
+        delivered_total: number;
+        dropped_duplicate: number;
+        dropped_self: 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_topic_decode_error: number;
+        dropped_handler_error: number;
+        send_errors: number;
+        discovery_errors: number;
+        start_errors: number;
+        stop_errors: number;
+        received_validated: number;
+    };
+    transport_stats: ReturnType<NonNullable<NetworkTransport["getStats"]>> | null;
+    discovery_stats: ReturnType<NonNullable<PeerDiscovery["getStats"]>> | null;
+};
+export declare class RealNetworkAdapterPreview implements NetworkAdapter {
+    private started;
+    private peerId;
+    private namespace;
+    private transport;
+    private envelopeCodec;
+    private topicCodec;
+    private peerDiscovery;
+    private maxMessageBytes;
+    private dedupeWindowMs;
+    private dedupeMaxEntries;
+    private maxFutureDriftMs;
+    private maxPastDriftMs;
+    private seenMessageIds;
+    private offTransportMessage;
+    private handlers;
+    private stats;
+    constructor(options?: RealNetworkAdapterPreviewOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    publish(topic: string, data: any): Promise<void>;
+    subscribe(topic: string, handler: (data: any) => void): void;
+    listPeers(): PeerSnapshot[];
+    getDiagnostics(): NetworkDiagnostics;
+    private onTransportMessage;
+    private topicKey;
+    private stripNamespace;
+    private isDuplicateMessage;
+    private cleanupSeenMessageIds;
+    private isValidTopic;
+    private normalizeNamespace;
+    private errorMessage;
+}
+export {};

package/packages/network/dist/realPreview.js

@@ -0,0 +1,327 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealNetworkAdapterPreview = void 0;
+const crypto_1 = require("crypto");
+const messageEnvelope_1 = require("./abstractions/messageEnvelope");
+const jsonMessageEnvelopeCodec_1 = require("./codec/jsonMessageEnvelopeCodec");
+const jsonTopicCodec_1 = require("./codec/jsonTopicCodec");
+const udpLanBroadcastTransport_1 = require("./transport/udpLanBroadcastTransport");
+const heartbeatPeerDiscovery_1 = require("./discovery/heartbeatPeerDiscovery");
+class RealNetworkAdapterPreview {
+    started = false;
+    peerId;
+    namespace;
+    transport;
+    envelopeCodec;
+    topicCodec;
+    peerDiscovery;
+    maxMessageBytes;
+    dedupeWindowMs;
+    dedupeMaxEntries;
+    maxFutureDriftMs;
+    maxPastDriftMs;
+    seenMessageIds = new Map();
+    offTransportMessage = null;
+    handlers = new Map();
+    stats = {
+        publish_attempted: 0,
+        publish_sent: 0,
+        received_total: 0,
+        delivered_total: 0,
+        dropped_duplicate: 0,
+        dropped_self: 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_topic_decode_error: 0,
+        dropped_handler_error: 0,
+        send_errors: 0,
+        discovery_errors: 0,
+        start_errors: 0,
+        stop_errors: 0,
+        received_validated: 0,
+    };
+    constructor(options = {}) {
+        this.peerId = options.peerId ?? `peer-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+        this.namespace = this.normalizeNamespace(options.namespace ?? "silicaclaw.preview");
+        this.transport = options.transport ?? new udpLanBroadcastTransport_1.UdpLanBroadcastTransport();
+        this.envelopeCodec = options.envelopeCodec ?? new jsonMessageEnvelopeCodec_1.JsonMessageEnvelopeCodec();
+        this.topicCodec = options.topicCodec ?? new jsonTopicCodec_1.JsonTopicCodec();
+        this.peerDiscovery = options.peerDiscovery ?? new heartbeatPeerDiscovery_1.HeartbeatPeerDiscovery();
+        this.maxMessageBytes = options.maxMessageBytes ?? 64 * 1024;
+        this.dedupeWindowMs = options.dedupeWindowMs ?? 90_000;
+        this.dedupeMaxEntries = options.dedupeMaxEntries ?? 10_000;
+        this.maxFutureDriftMs = options.maxFutureDriftMs ?? 30_000;
+        this.maxPastDriftMs = options.maxPastDriftMs ?? 120_000;
+    }
+    async start() {
+        if (this.started) {
+            return;
+        }
+        try {
+            await this.transport.start();
+        }
+        catch (error) {
+            this.stats.start_errors += 1;
+            throw new Error(`Transport start failed: ${this.errorMessage(error)}`);
+        }
+        this.started = true;
+        this.offTransportMessage = this.transport.onMessage((raw) => {
+            this.onTransportMessage(raw);
+        });
+        try {
+            await this.peerDiscovery.start({
+                self_peer_id: this.peerId,
+                publishControl: async (topic, payload) => {
+                    await this.publish(topic, payload);
+                },
+            });
+        }
+        catch (error) {
+            this.stats.start_errors += 1;
+            this.started = false;
+            if (this.offTransportMessage) {
+                this.offTransportMessage();
+                this.offTransportMessage = null;
+            }
+            try {
+                await this.transport.stop();
+            }
+            catch {
+                this.stats.stop_errors += 1;
+            }
+            throw new Error(`Peer discovery start failed: ${this.errorMessage(error)}`);
+        }
+    }
+    async stop() {
+        if (!this.started) {
+            return;
+        }
+        try {
+            await this.peerDiscovery.stop();
+        }
+        catch {
+            this.stats.discovery_errors += 1;
+            this.stats.stop_errors += 1;
+        }
+        if (this.offTransportMessage) {
+            this.offTransportMessage();
+            this.offTransportMessage = null;
+        }
+        try {
+            await this.transport.stop();
+        }
+        catch {
+            this.stats.stop_errors += 1;
+        }
+        this.started = false;
+    }
+    async publish(topic, data) {
+        if (!this.started) {
+            return;
+        }
+        this.stats.publish_attempted += 1;
+        if (!this.isValidTopic(topic)) {
+            this.stats.dropped_malformed += 1;
+            return;
+        }
+        const envelope = {
+            version: 1,
+            message_id: (0, crypto_1.randomUUID)(),
+            topic: this.topicKey(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;
+        }
+        try {
+            await this.transport.send(raw);
+            this.stats.publish_sent += 1;
+        }
+        catch {
+            this.stats.send_errors += 1;
+            throw new Error("Transport send failed");
+        }
+    }
+    subscribe(topic, handler) {
+        if (!this.isValidTopic(topic)) {
+            return;
+        }
+        const key = this.topicKey(topic);
+        if (!this.handlers.has(key)) {
+            this.handlers.set(key, new Set());
+        }
+        this.handlers.get(key)?.add(handler);
+    }
+    listPeers() {
+        return this.peerDiscovery.listPeers();
+    }
+    getDiagnostics() {
+        const peers = this.listPeers();
+        const online = peers.filter((peer) => peer.status === "online").length;
+        return {
+            adapter: "real-preview",
+            peer_id: this.peerId,
+            namespace: this.namespace,
+            components: {
+                transport: this.transport.constructor.name,
+                discovery: this.peerDiscovery.constructor.name,
+                envelope_codec: this.envelopeCodec.constructor.name,
+                topic_codec: this.topicCodec.constructor.name,
+            },
+            limits: {
+                max_message_bytes: this.maxMessageBytes,
+                dedupe_window_ms: this.dedupeWindowMs,
+                dedupe_max_entries: this.dedupeMaxEntries,
+                max_future_drift_ms: this.maxFutureDriftMs,
+                max_past_drift_ms: this.maxPastDriftMs,
+            },
+            config: {
+                started: this.started,
+                topic_handler_count: this.handlers.size,
+                transport: this.transport.getConfig?.() ?? null,
+                discovery: this.peerDiscovery.getConfig?.() ?? null,
+            },
+            peers: {
+                total: peers.length,
+                online,
+                stale: Math.max(0, peers.length - online),
+                items: peers,
+            },
+            stats: { ...this.stats },
+            transport_stats: this.transport.getStats?.() ?? null,
+            discovery_stats: this.peerDiscovery.getStats?.() ?? null,
+        };
+    }
+    onTransportMessage(raw) {
+        this.stats.received_total += 1;
+        if (raw.length > this.maxMessageBytes) {
+            this.stats.dropped_oversized += 1;
+            return;
+        }
+        const decoded = this.envelopeCodec.decode(raw);
+        if (!decoded) {
+            this.stats.dropped_decode_failed += 1;
+            this.stats.dropped_malformed += 1;
+            return;
+        }
+        const validated = (0, messageEnvelope_1.validateNetworkMessageEnvelope)(decoded.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;
+        }
+        this.stats.received_validated += 1;
+        const envelope = validated.envelope;
+        if (!envelope.topic.startsWith(`${this.namespace}:`)) {
+            this.stats.dropped_namespace_mismatch += 1;
+            return;
+        }
+        if (this.isDuplicateMessage(envelope.message_id, envelope.timestamp)) {
+            this.stats.dropped_duplicate += 1;
+            return;
+        }
+        try {
+            this.peerDiscovery.observeEnvelope(envelope);
+        }
+        catch {
+            this.stats.discovery_errors += 1;
+        }
+        if (envelope.source_peer_id === this.peerId) {
+            this.stats.dropped_self += 1;
+            return;
+        }
+        const topic = this.stripNamespace(envelope.topic);
+        if (!topic) {
+            this.stats.dropped_namespace_mismatch += 1;
+            return;
+        }
+        const handlers = this.handlers.get(envelope.topic);
+        if (!handlers || handlers.size === 0) {
+            return;
+        }
+        try {
+            const payload = this.topicCodec.decode(topic, envelope.payload);
+            for (const handler of handlers) {
+                try {
+                    handler(payload);
+                    this.stats.delivered_total += 1;
+                }
+                catch {
+                    this.stats.dropped_handler_error += 1;
+                }
+            }
+        }
+        catch {
+            this.stats.dropped_topic_decode_error += 1;
+        }
+    }
+    topicKey(topic) {
+        return `${this.namespace}:${topic}`;
+    }
+    stripNamespace(topicKey) {
+        const prefix = `${this.namespace}:`;
+        if (!topicKey.startsWith(prefix)) {
+            return null;
+        }
+        return topicKey.slice(prefix.length);
+    }
+    isDuplicateMessage(messageId, timestamp) {
+        const now = Date.now();
+        this.cleanupSeenMessageIds(now);
+        const existing = this.seenMessageIds.get(messageId);
+        if (existing && now - existing <= this.dedupeWindowMs) {
+            return true;
+        }
+        this.seenMessageIds.set(messageId, Number.isFinite(timestamp) ? timestamp : now);
+        if (this.seenMessageIds.size > this.dedupeMaxEntries) {
+            const oldestKey = this.seenMessageIds.keys().next().value;
+            if (oldestKey) {
+                this.seenMessageIds.delete(oldestKey);
+            }
+        }
+        return false;
+    }
+    cleanupSeenMessageIds(now) {
+        for (const [id, ts] of this.seenMessageIds.entries()) {
+            if (now - ts > this.dedupeWindowMs) {
+                this.seenMessageIds.delete(id);
+            }
+        }
+    }
+    isValidTopic(topic) {
+        if (typeof topic !== "string") {
+            return false;
+        }
+        const normalized = topic.trim();
+        return normalized.length > 0 && !normalized.includes(":");
+    }
+    normalizeNamespace(namespace) {
+        const normalized = namespace.trim();
+        return normalized.length > 0 ? normalized : "silicaclaw.preview";
+    }
+    errorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        return String(error);
+    }
+}
+exports.RealNetworkAdapterPreview = RealNetworkAdapterPreview;

package/packages/network/dist/relayPreview.d.ts

@@ -0,0 +1,133 @@
+import { NetworkAdapter } from "./types";
+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;
+    };
+};
+export declare class RelayPreviewAdapter implements NetworkAdapter {
+    private readonly peerId;
+    private readonly namespace;
+    private readonly signalingEndpoints;
+    private readonly room;
+    private readonly seedPeers;
+    private readonly bootstrapHints;
+    private readonly bootstrapSources;
+    private readonly maxMessageBytes;
+    private readonly pollIntervalMs;
+    private readonly maxFutureDriftMs;
+    private readonly maxPastDriftMs;
+    private readonly envelopeCodec;
+    private readonly topicCodec;
+    private started;
+    private poller;
+    private handlers;
+    private peers;
+    private seenMessageIds;
+    private activeEndpoint;
+    private discoveryEvents;
+    private discoveryEventsTotal;
+    private lastDiscoveryEventAt;
+    private signalingMessagesSentTotal;
+    private signalingMessagesReceivedTotal;
+    private reconnectAttemptsTotal;
+    private stats;
+    constructor(options?: RelayPreviewOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    publish(topic: string, data: any): Promise<void>;
+    subscribe(topic: string, handler: (data: any) => void): void;
+    getDiagnostics(): RelayDiagnostics;
+    private pollOnce;
+    private refreshPeers;
+    private onEnvelope;
+    private recordDiscovery;
+    private get;
+    private post;
+}
+export {};