@silicaclaw/cli 1.0.0-beta.0

package/packages/core/src/socialTemplate.ts

@@ -0,0 +1,97 @@
+import { SocialRuntimeConfig } from "./socialConfig";
+
+function asBool(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function asString(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function asStringArray(value: unknown, fallback: string[]): string[] {
+  if (!Array.isArray(value)) return fallback;
+  return value.map((item) => String(item).trim()).filter(Boolean);
+}
+
+function yamlString(input: string): string {
+  return JSON.stringify(input ?? "");
+}
+
+function yamlStringList(values: string[], indent = "  "): string {
+  if (!values.length) {
+    return `${indent}[]`;
+  }
+  return values.map((value) => `${indent}- ${yamlString(value)}`).join("\n");
+}
+
+export function generateSocialMdTemplate(runtimeConfig: SocialRuntimeConfig | null | undefined): string {
+  const enabled = asBool(runtimeConfig?.enabled, true);
+  const publicEnabled = asBool(runtimeConfig?.public_enabled, false);
+  const profile = runtimeConfig?.resolved_profile ?? null;
+  const network = runtimeConfig?.resolved_network ?? null;
+  const discovery = runtimeConfig?.resolved_discovery ?? null;
+  const visibility = runtimeConfig?.visibility ?? null;
+  const openclaw = runtimeConfig?.openclaw ?? null;
+
+  const displayName = asString(profile?.display_name, "");
+  const bio = asString(profile?.bio, "");
+  const tags = asStringArray(profile?.tags, ["openclaw", "local-first"]);
+  const mode =
+    network?.mode === "local" || network?.mode === "lan" || network?.mode === "global-preview"
+      ? network.mode
+      : "lan";
+
+  const discoverable = asBool(discovery?.discoverable, true);
+  const allowProfileBroadcast = asBool(discovery?.allow_profile_broadcast, true);
+  const allowPresenceBroadcast = asBool(discovery?.allow_presence_broadcast, true);
+
+  const showDisplayName = asBool(visibility?.show_display_name, true);
+  const showBio = asBool(visibility?.show_bio, true);
+  const showTags = asBool(visibility?.show_tags, true);
+  const showAgentId = asBool(visibility?.show_agent_id, true);
+  const showLastSeen = asBool(visibility?.show_last_seen, true);
+  const showCapabilitiesSummary = asBool(visibility?.show_capabilities_summary, true);
+
+  const bindExistingIdentity = asBool(openclaw?.bind_existing_identity, true);
+  const useOpenClawProfile = asBool(openclaw?.use_openclaw_profile_if_available, true);
+
+  return `---
+enabled: ${enabled}
+public_enabled: ${publicEnabled}
+
+identity:
+  display_name: ${yamlString(displayName)}
+  bio: ${yamlString(bio)}
+  tags:
+${yamlStringList(tags.map((tag) => asString(tag, "")), "    ")}
+
+network:
+  mode: ${yamlString(mode)}
+
+discovery:
+  discoverable: ${discoverable}
+  allow_profile_broadcast: ${allowProfileBroadcast}
+  allow_presence_broadcast: ${allowPresenceBroadcast}
+
+visibility:
+  show_display_name: ${showDisplayName}
+  show_bio: ${showBio}
+  show_tags: ${showTags}
+  show_agent_id: ${showAgentId}
+  show_last_seen: ${showLastSeen}
+  show_capabilities_summary: ${showCapabilitiesSummary}
+
+openclaw:
+  bind_existing_identity: ${bindExistingIdentity}
+  use_openclaw_profile_if_available: ${useOpenClawProfile}
+---
+
+# Social
+
+Generated from current SilicaClaw runtime state.
+
+- Save as \`social.md\` in your OpenClaw workspace.
+- This export does not auto-overwrite any existing file.
+- Advanced network fields are intentionally hidden in template and resolved in runtime.
+`;
+}

package/packages/core/src/types.ts

@@ -0,0 +1,43 @@
+export type AgentIdentity = {
+  agent_id: string;
+  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;
+  public_enabled: boolean;
+  updated_at: number;
+  signature: string;
+};
+
+export type SignedProfileRecord = {
+  type: "profile";
+  profile: PublicProfile;
+};
+
+export type PresenceRecord = {
+  type: "presence";
+  agent_id: string;
+  timestamp: number;
+  signature: string;
+};
+
+export type IndexRefRecord = {
+  type: "index";
+  key: string;
+  agent_id: string;
+};
+
+export type DirectoryState = {
+  profiles: Record<string, PublicProfile>;
+  presence: Record<string, number>;
+  index: Record<string, string[]>;
+};
+
+export type ProfileInput = Omit<PublicProfile, "signature" | "updated_at">;

package/packages/core/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src"]
+}

package/packages/network/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@silicaclaw/network",
+  "version": "0.1.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}

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

@@ -0,0 +1,80 @@
+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 function validateNetworkMessageEnvelope(
+  value: unknown,
+  options: EnvelopeValidationOptions
+): EnvelopeValidationResult {
+  if (typeof value !== "object" || value === null) {
+    return { ok: false, reason: "not_object" };
+  }
+
+  const envelope = value as Partial<NetworkMessageEnvelope>;
+  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 as NetworkMessageEnvelope, drift_ms: drift };
+}

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

@@ -0,0 +1,49 @@
+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/src/abstractions/topicCodec.ts

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

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

@@ -0,0 +1,40 @@
+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/src/codec/jsonMessageEnvelopeCodec.ts

@@ -0,0 +1,22 @@
+import { DecodedNetworkMessage, MessageEnvelopeCodec, NetworkMessageEnvelope } from "../abstractions/messageEnvelope";
+
+export class JsonMessageEnvelopeCodec implements MessageEnvelopeCodec {
+  encode(envelope: NetworkMessageEnvelope): Buffer {
+    return Buffer.from(JSON.stringify(envelope), "utf8");
+  }
+
+  decode(raw: Buffer): DecodedNetworkMessage | null {
+    try {
+      const parsed = JSON.parse(raw.toString("utf8")) as unknown;
+      if (typeof parsed !== "object" || parsed === null) {
+        return null;
+      }
+      return {
+        envelope: parsed as NetworkMessageEnvelope,
+        raw,
+      };
+    } catch {
+      return null;
+    }
+  }
+}

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

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

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

@@ -0,0 +1,173 @@
+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 class HeartbeatPeerDiscovery implements PeerDiscovery {
+  private peers = new Map<string, PeerSnapshot>();
+  private timer: NodeJS.Timeout | null = null;
+  private context: PeerDiscoveryContext | null = null;
+
+  private heartbeatIntervalMs: number;
+  private staleAfterMs: number;
+  private removeAfterMs: number;
+  private topic: string;
+  private stats: PeerDiscoveryStats = {
+    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: HeartbeatPeerDiscoveryOptions = {}) {
+    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: PeerDiscoveryContext): Promise<void> {
+    this.context = context;
+    this.reconcilePeerHealth();
+    await this.sendHeartbeat();
+
+    this.timer = setInterval(async () => {
+      await this.sendHeartbeat();
+      this.reconcilePeerHealth();
+    }, this.heartbeatIntervalMs);
+  }
+
+  async stop(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  observeEnvelope(envelope: NetworkMessageEnvelope): void {
+    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 as Record<string, unknown>)
+          : existing?.meta,
+    });
+  }
+
+  listPeers(): PeerSnapshot[] {
+    this.reconcilePeerHealth();
+    return Array.from(this.peers.values()).sort((a, b) => {
+      const score = (p: PeerSnapshot) => (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(): PeerDiscoveryStats {
+    return { ...this.stats };
+  }
+
+  getConfig(): PeerDiscoveryConfigSnapshot {
+    return {
+      discovery: "heartbeat-peer-discovery",
+      heartbeat_topic: this.topic,
+      heartbeat_interval_ms: this.heartbeatIntervalMs,
+      stale_after_ms: this.staleAfterMs,
+      remove_after_ms: this.removeAfterMs,
+    };
+  }
+
+  private async sendHeartbeat(): Promise<void> {
+    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();
+    }
+  }
+
+  private reconcilePeerHealth(): void {
+    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,
+        });
+      }
+    }
+  }
+}

package/packages/network/src/index.ts

@@ -0,0 +1,16 @@
+export * from "./types";
+export * from "./mock";
+export * from "./localEventBus";
+export * from "./realPreview";
+export * from "./webrtcPreview";
+
+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/src/localEventBus.ts

@@ -0,0 +1,61 @@
+import { EventEmitter } from "events";
+import { NetworkAdapter } from "./types";
+
+type EventBusPayload = {
+  topic: string;
+  data: any;
+};
+
+const CHANNEL_NAME = "silicaclaw-local-event-bus";
+
+function getNodeBus(): EventEmitter {
+  const g = globalThis as typeof globalThis & {
+    __silicaclaw_bus?: EventEmitter;
+  };
+  if (!g.__silicaclaw_bus) {
+    g.__silicaclaw_bus = new EventEmitter();
+  }
+  return g.__silicaclaw_bus;
+}
+
+export class LocalEventBusAdapter implements NetworkAdapter {
+  private started = false;
+  private emitter = getNodeBus();
+
+  async start(): Promise<void> {
+    this.started = true;
+  }
+
+  async stop(): Promise<void> {
+    this.started = false;
+  }
+
+  async publish(topic: string, data: any): Promise<void> {
+    if (!this.started) {
+      return;
+    }
+
+    if (typeof BroadcastChannel !== "undefined") {
+      const channel = new BroadcastChannel(CHANNEL_NAME);
+      channel.postMessage({ topic, data } satisfies EventBusPayload);
+      channel.close();
+      return;
+    }
+
+    setImmediate(() => this.emitter.emit(topic, data));
+  }
+
+  subscribe(topic: string, handler: (data: any) => void): void {
+    if (typeof BroadcastChannel !== "undefined") {
+      const channel = new BroadcastChannel(CHANNEL_NAME);
+      channel.onmessage = (event: MessageEvent<EventBusPayload>) => {
+        if (event.data?.topic === topic) {
+          handler(event.data.data);
+        }
+      };
+      return;
+    }
+
+    this.emitter.on(topic, handler);
+  }
+}

package/packages/network/src/mock.ts

@@ -0,0 +1,27 @@
+import { EventEmitter } from "events";
+import { NetworkAdapter } from "./types";
+
+const bus = new EventEmitter();
+
+export class MockNetworkAdapter implements NetworkAdapter {
+  private started = false;
+
+  async start(): Promise<void> {
+    this.started = true;
+  }
+
+  async stop(): Promise<void> {
+    this.started = false;
+  }
+
+  async publish(topic: string, data: any): Promise<void> {
+    if (!this.started) {
+      return;
+    }
+    setImmediate(() => bus.emit(topic, data));
+  }
+
+  subscribe(topic: string, handler: (data: any) => void): void {
+    bus.on(topic, handler);
+  }
+}