openclaw-overlay-plugin 0.7.22

package/src/scripts/messaging/poll.ts

@@ -0,0 +1,59 @@
+/**
+ * Poll command: fetch and process all pending messages.
+ */
+
+import { OVERLAY_URL } from '../config.js';
+import { ok, fail } from '../output.js';
+import { loadIdentity } from '../wallet/identity.js';
+import { processMessage } from './handlers.js';
+
+/**
+ * Poll command: fetch all pending messages and process them.
+ */
+export async function cmdPoll(): Promise<never> {
+  const { identityKey, privKey } = await loadIdentity();
+
+  // Fetch inbox
+  const inboxResp = await fetch(`${OVERLAY_URL}/relay/inbox?identity=${identityKey}`);
+  if (!inboxResp.ok) {
+    const body = await inboxResp.text();
+    return fail(`Relay inbox failed (${inboxResp.status}): ${body}`);
+  }
+  const inbox = await inboxResp.json();
+
+  if (inbox.count === 0) {
+    return ok({ processed: 0, messages: [], summary: 'No pending messages.' });
+  }
+
+  const processed: any[] = [];
+  const ackedIds: string[] = [];
+  const unhandled: any[] = [];
+
+  for (const msg of inbox.messages) {
+    const result = await processMessage(msg, identityKey, privKey);
+    if (result.ack) {
+      ackedIds.push(result.id);
+      processed.push(result);
+    } else {
+      unhandled.push(result);
+    }
+  }
+
+  // ACK processed messages
+  if (ackedIds.length > 0) {
+    await fetch(`${OVERLAY_URL}/relay/ack`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ identity: identityKey, messageIds: ackedIds }),
+    });
+  }
+
+  return ok({
+    processed: processed.length,
+    unhandled: unhandled.length,
+    total: inbox.count,
+    messages: processed,
+    unhandledMessages: unhandled,
+    ackedIds,
+  });
+}

package/src/scripts/messaging/send.ts

@@ -0,0 +1,54 @@
+/**
+ * Send relay message command.
+ */
+
+import { OVERLAY_URL } from '../config.js';
+import { ok, fail } from '../output.js';
+import { loadIdentity, signRelayMessage } from '../wallet/identity.js';
+
+/**
+ * Send command: send a typed message to another agent.
+ */
+export async function cmdSend(
+  targetKey: string | undefined,
+  type: string | undefined,
+  payloadStr: string | undefined
+): Promise<never> {
+  if (!targetKey || !type || !payloadStr) {
+    return fail('Usage: send <identityKey> <type> <json_payload>');
+  }
+
+  if (!/^0[23][0-9a-fA-F]{64}$/.test(targetKey)) {
+    return fail('Target must be a compressed public key (66 hex chars, 02/03 prefix)');
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(payloadStr);
+  } catch {
+    return fail('payload must be valid JSON');
+  }
+
+  const { identityKey, privKey } = await loadIdentity();
+  const signature = await signRelayMessage(privKey, targetKey, type, payload);
+
+  const resp = await fetch(`${OVERLAY_URL}/relay/send`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      from: identityKey,
+      to: targetKey,
+      type,
+      payload,
+      signature,
+    }),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    return fail(`Relay send failed (${resp.status}): ${body}`);
+  }
+
+  const result = await resp.json();
+  return ok({ sent: true, messageId: result.id, to: targetKey, type, signed: true });
+}

package/src/scripts/output.ts

@@ -0,0 +1,21 @@
+/**
+ * JSON output helpers for CLI commands.
+ * All CLI output follows the { success, data/error } wrapper format.
+ */
+
+/**
+ * Output a successful result and exit.
+ */
+export function ok<T>(data: T): never {
+  console.log(JSON.stringify({ success: true, data }));
+  process.exit(0);
+}
+
+/**
+ * Output an error and exit.
+ */
+export function fail(error: string | Error): never {
+  const message = error instanceof Error ? error.message : String(error);
+  console.log(JSON.stringify({ success: false, error: message }));
+  process.exit(1);
+}

package/src/scripts/overlay/discover.ts

@@ -0,0 +1,81 @@
+/**
+ * Overlay discovery commands.
+ */
+
+import { OVERLAY_URL, LOOKUP_SERVICES } from '../config.js';
+import { ok } from '../output.js';
+import { lookupOverlay, parseOverlayOutput } from './transaction.js';
+
+/**
+ * Discover command: query the overlay for agents and services.
+ */
+export async function cmdDiscover(args: string[]): Promise<never> {
+
+  // Parse flags
+  let serviceFilter: string | null = null;
+  let agentFilter: string | null = null;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--service' && args[i + 1]) serviceFilter = args[++i];
+    else if (args[i] === '--agent' && args[i + 1]) agentFilter = args[++i];
+  }
+
+  const results: {
+    agents: any[];
+    services: any[];
+    agentError?: string;
+    serviceError?: string;
+  } = { agents: [], services: [] };
+
+  // Query agents
+  if (!serviceFilter) {
+    try {
+      const agentQuery = agentFilter ? { name: agentFilter } : { type: 'list' };
+      const agentResult = await lookupOverlay(LOOKUP_SERVICES.AGENTS, agentQuery);
+
+      if (agentResult.outputs) {
+        for (const output of agentResult.outputs) {
+          try {
+            const { data, txid } = await parseOverlayOutput(output.beef, output.outputIndex);
+            if (data?.type === 'identity') {
+              results.agents.push({ ...data, txid });
+            }
+          } catch { /* ignore */ }
+        }
+      }
+    } catch (err: any) {
+      results.agentError = String(err);
+    }
+  }
+
+  // Query services
+  if (!agentFilter) {
+    try {
+      const serviceQuery = serviceFilter ? { serviceType: serviceFilter } : {};
+      const serviceResult = await lookupOverlay(LOOKUP_SERVICES.SERVICES, serviceQuery);
+
+      if (serviceResult.outputs) {
+        for (const output of serviceResult.outputs) {
+          try {
+            const { data, txid } = await parseOverlayOutput(output.beef, output.outputIndex);
+            if (data?.type === 'service') {
+              results.services.push({ ...data, txid });
+            }
+          } catch { /* ignore */ }
+        }
+      }
+    } catch (err: any) {
+      results.serviceError = String(err);
+    }
+  }
+
+  return ok({
+    overlayUrl: OVERLAY_URL,
+    agentCount: results.agents.length,
+    serviceCount: results.services.length,
+    agents: results.agents,
+    services: results.services,
+    ...(results.agentError && { agentError: results.agentError }),
+    ...(results.serviceError && { serviceError: results.serviceError }),
+  });
+}

package/src/scripts/overlay/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Overlay module exports.
+ */
+
+export * from './transaction.js';
+export * from './registration.js';
+export * from './services.js';
+export * from './discover.js';

package/src/scripts/overlay/registration.ts

@@ -0,0 +1,199 @@
+/**
+ * Overlay registration commands: register, unregister.
+ * 
+ * Registration creates an identity record on the overlay network with:
+ * - identityKey: compressed public key (66 hex chars)
+ * - name: agent display name
+ * - description: what the agent does
+ * - channels: contact methods (e.g., { overlay: "https://..." })
+ * - capabilities: what the agent can do (e.g., ["services", "jokes"])
+ * - timestamp: ISO 8601 registration time
+ */
+
+import fs from 'node:fs';
+import { NETWORK, WALLET_DIR, OVERLAY_URL, PROTOCOL_ID, TOPICS, PATHS, AGENT_NAME, AGENT_DESCRIPTION } from '../config.js';
+import { ok, fail } from '../output.js';
+import { loadRegistration, saveRegistration, deleteRegistration, loadServices } from '../utils/storage.js';
+import { buildRealOverlayTransaction } from './transaction.js';
+import { Transaction, Beef, Script, PushDrop, WalletOutput } from '@bsv/sdk'
+
+import { BSVAgentWallet } from '../../core/index.js';
+
+async function getBSVAgentWallet(): Promise<typeof BSVAgentWallet> {
+  return BSVAgentWallet;
+}
+
+/**
+ * Register command: register this agent on the overlay network.
+ */
+export async function cmdRegister(): Promise<never> {
+  if (!fs.existsSync(PATHS.walletIdentity)) {
+    return fail('Wallet not initialized. Run: setup');
+  }
+
+  const BSVAgentWallet = await getBSVAgentWallet();
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+  const identityKey = await wallet.getIdentityKey();
+  await wallet.destroy();
+
+  const existingReg = loadRegistration();
+  if (existingReg && existingReg.identityKey === identityKey) {
+    return ok({
+      alreadyRegistered: true,
+      identityKey,
+      identityTxid: existingReg.identityTxid,
+      overlayUrl: OVERLAY_URL,
+    });
+  }
+
+  // Agent metadata from environment/config
+  const agentName = AGENT_NAME;
+  const agentDescription = AGENT_DESCRIPTION;
+
+  // Build capabilities list based on what services we might offer
+  const capabilities: string[] = ['services'];
+  const services = loadServices();
+  if (services.some(s => s.serviceId === 'tell-joke')) {
+    capabilities.push('jokes');
+  }
+
+  // Create identity record on-chain
+  // This payload format matches the clawdbot-overlay server's expected schema
+  const identityPayload = {
+    protocol: PROTOCOL_ID,
+    type: 'identity' as const,
+    identityKey,
+    name: agentName,
+    description: agentDescription,
+    channels: {
+      overlay: OVERLAY_URL,
+    },
+    capabilities,
+    timestamp: new Date().toISOString(),
+  };
+
+  let identityResult: { txid: string; funded: string };
+  try {
+    identityResult = await buildRealOverlayTransaction(identityPayload, TOPICS.IDENTITY);
+  } catch (err: any) {
+    return fail(`Registration failed: ${err.message}`);
+  }
+
+  // Optionally register services if pre-configured
+  let serviceTxid: string | null = null;
+
+  if (services.length > 0) {
+    // Register each service individually (server expects 'service' type, not 'service-bundle')
+    for (const service of services) {
+      const servicePayload = {
+        protocol: PROTOCOL_ID,
+        type: 'service' as const,
+        identityKey,
+        serviceId: service.serviceId,
+        name: service.name,
+        description: service.description,
+        pricing: {
+          model: 'per-task',
+          amountSats: service.priceSats,
+        },
+        timestamp: new Date().toISOString(),
+      };
+
+      try {
+        const serviceResult = await buildRealOverlayTransaction(servicePayload, TOPICS.SERVICES);
+        serviceTxid = serviceResult.txid; // Keep last one for backward compat
+      } catch {
+        // Non-fatal — identity registered but this service failed
+      }
+    }
+  }
+
+  // Save registration
+  const registration = {
+    identityKey,
+    agentName,
+    agentDescription,
+    overlayUrl: OVERLAY_URL,
+    identityTxid: identityResult.txid,
+    serviceTxid,
+    funded: identityResult.funded,
+    registeredAt: new Date().toISOString(),
+  };
+  saveRegistration(registration);
+
+  return ok({
+    registered: true,
+    identityKey,
+    identityTxid: identityResult.txid,
+    serviceTxid,
+    overlayUrl: OVERLAY_URL,
+    funded: identityResult.funded,
+    stateFile: PATHS.registration,
+  });
+}
+
+/**
+ * Unregister command: submit revocation tx to remove agent from overlay network.
+ */
+export async function cmdUnregister(): Promise<never> {
+  
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+  const { outputs, BEEF } = await wallet._setup.wallet.listOutputs({ basket: TOPICS.IDENTITY, include: 'entire transactions' });
+
+  const token = new PushDrop(wallet._setup.wallet);
+  const unlockingScriptTemplate = await token.unlock([0, PROTOCOL_ID], '1', 'self', 'none', true)
+  const tempTx = new Transaction()
+  const beef = Beef.fromBinary(BEEF as number[])
+  outputs.forEach((o: WalletOutput) => {
+    const [txid, v] = o.outpoint.split('.')
+    const sourceOutputIndex = Number(v)
+    const sourceTransaction = beef.findTransactionForSigning(txid)
+    tempTx.addInput({
+      unlockingScriptTemplate,
+      sourceOutputIndex,
+      sourceTransaction
+    })
+  })
+  tempTx.addOutput({
+    lockingScript: Script.fromASM('OP_FALSE OP_RETURN 330123'),
+    satoshis: 0
+  })
+
+  await tempTx.sign()
+
+  const response = await wallet._setup.wallet.createAction({
+    inputBEEF: BEEF,
+    description: 'revoke registration token',
+    inputs: tempTx.inputs.map(o => ({
+      inputDescription: 'previous registration',
+      outpoint: o.sourceTXID + '.' + String(o.sourceOutputIndex),
+      unlockingScript: o.unlockingScript?.toHex() as string
+    }))
+  })
+
+  const txid = response.txid as string;
+
+  // --- Submit to overlay ---
+  // Use binary BEEF with X-Topics header (matches clawdbot-overlay server API)
+  const submitResp = await fetch(`${OVERLAY_URL}/submit`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/octet-stream',
+      'X-Topics': JSON.stringify([TOPICS.IDENTITY]),
+    },
+    body: new Uint8Array(response.tx as number[]),
+  });
+
+  if (!submitResp.ok) {
+    const errText = await submitResp.text();
+    throw new Error(`Overlay submission failed: ${submitResp.status} — ${errText}`);
+  }
+  
+  // Delete local registration
+  deleteRegistration();
+
+  return ok({
+    unregistered: true,
+    txid
+  });
+}

package/src/scripts/overlay/services.ts

@@ -0,0 +1,199 @@
+/**
+ * Overlay service commands: services, advertise, remove, readvertise.
+ * 
+ * Service payloads match the clawdbot-overlay server schema:
+ * - protocol: "clawdbot-overlay-v1"
+ * - type: "service"
+ * - identityKey: provider's compressed public key
+ * - serviceId: unique service identifier
+ * - name: human-readable name
+ * - description: what the service does
+ * - pricing: { model: "per-task", amountSats: number }
+ * - timestamp: ISO 8601 time
+ */
+
+import { NETWORK, WALLET_DIR, PROTOCOL_ID, TOPICS } from '../config.js';
+import { ok, fail } from '../output.js';
+import { loadServices, saveServices } from '../utils/storage.js';
+import { buildRealOverlayTransaction } from './transaction.js';
+import type { ServiceAdvertisement } from '../types.js';
+
+import { BSVAgentWallet } from '../../core/index.js';
+
+async function getBSVAgentWallet(): Promise<typeof BSVAgentWallet> {
+  return BSVAgentWallet;
+}
+
+/**
+ * Services command: list currently advertised services.
+ */
+export async function cmdServices(): Promise<never> {
+  const services = loadServices();
+  return ok({ services, count: services.length });
+}
+
+/**
+ * Advertise command: add a new service advertisement.
+ */
+export async function cmdAdvertise(
+  serviceId: string | undefined,
+  name: string | undefined,
+  priceSatsStr: string | undefined,
+  description?: string
+): Promise<never> {
+  if (!serviceId || !name || !priceSatsStr) {
+    return fail('Usage: advertise <serviceId> <name> <priceSats> [description]');
+  }
+
+  const priceSats = parseInt(priceSatsStr, 10);
+  if (isNaN(priceSats) || priceSats < 0) {
+    return fail('priceSats must be a non-negative integer');
+  }
+
+  const BSVAgentWallet = await getBSVAgentWallet();
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+  const identityKey = await wallet.getIdentityKey();
+  await wallet.destroy();
+
+  // Load existing services
+  const services = loadServices();
+  const existing = services.find(s => s.serviceId === serviceId);
+  if (existing) {
+    return fail(`Service '${serviceId}' already exists. Use 'readvertise' to update.`);
+  }
+
+  // Create service record (local storage format)
+  const newService: ServiceAdvertisement = {
+    serviceId,
+    name,
+    description: description || `${name} service`,
+    priceSats,
+    registeredAt: new Date().toISOString(),
+  };
+
+  // Publish on-chain (matches clawdbot-overlay server schema)
+  const servicePayload = {
+    protocol: PROTOCOL_ID,
+    type: 'service' as const,
+    identityKey,
+    serviceId,
+    name,
+    description: newService.description,
+    pricing: {
+      model: 'per-task',
+      amountSats: priceSats,
+    },
+    timestamp: new Date().toISOString(),
+  };
+
+  try {
+    const result = await buildRealOverlayTransaction(servicePayload, TOPICS.SERVICES);
+    newService.txid = result.txid;
+
+    // Save locally
+    services.push(newService);
+    saveServices(services);
+
+    return ok({
+      advertised: true,
+      service: newService,
+      txid: result.txid,
+      funded: result.funded,
+    });
+  } catch (err: any) {
+    return fail(`Failed to advertise service: ${err.message}`);
+  }
+}
+
+/**
+ * Remove command: remove a service from local registry.
+ */
+export async function cmdRemove(serviceId: string | undefined): Promise<never> {
+  if (!serviceId) {
+    return fail('Usage: remove <serviceId>');
+  }
+
+  const services = loadServices();
+  const idx = services.findIndex(s => s.serviceId === serviceId);
+  if (idx === -1) {
+    return fail(`Service '${serviceId}' not found`);
+  }
+
+  const removed = services.splice(idx, 1)[0];
+  saveServices(services);
+
+  return ok({
+    removed: true,
+    service: removed,
+    note: 'Removed from local registry. On-chain record remains (blockchain is immutable).',
+  });
+}
+
+/**
+ * Readvertise command: update an existing service advertisement.
+ */
+export async function cmdReadvertise(
+  serviceId: string | undefined,
+  name?: string,
+  priceSatsStr?: string,
+  description?: string
+): Promise<never> {
+  if (!serviceId) {
+    return fail('Usage: readvertise <serviceId> [name] [priceSats] [description]');
+  }
+
+  const services = loadServices();
+  const existing = services.find(s => s.serviceId === serviceId);
+  if (!existing) {
+    return fail(`Service '${serviceId}' not found. Use 'advertise' to create.`);
+  }
+
+  const BSVAgentWallet = await getBSVAgentWallet();
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+  const identityKey = await wallet.getIdentityKey();
+  await wallet.destroy();
+
+  // Update fields if provided
+  if (name) existing.name = name;
+  if (priceSatsStr) {
+    const priceSats = parseInt(priceSatsStr, 10);
+    if (isNaN(priceSats) || priceSats < 0) {
+      return fail('priceSats must be a non-negative integer');
+    }
+    existing.priceSats = priceSats;
+  }
+  if (description) existing.description = description;
+  existing.registeredAt = new Date().toISOString();
+
+  // Publish update on-chain (matches clawdbot-overlay server schema)
+  const servicePayload = {
+    protocol: PROTOCOL_ID,
+    type: 'service' as const,
+    identityKey,
+    serviceId,
+    name: existing.name,
+    description: existing.description,
+    pricing: {
+      model: 'per-task',
+      amountSats: existing.priceSats,
+    },
+    timestamp: existing.registeredAt,
+  };
+
+  try {
+    const result = await buildRealOverlayTransaction(servicePayload, TOPICS.SERVICES);
+    existing.txid = result.txid;
+
+    // Save locally
+    saveServices(services);
+
+    return ok({
+      readvertised: true,
+      service: existing,
+      txid: result.txid,
+      funded: result.funded,
+    });
+  } catch (err: any) {
+    return fail(`Failed to readvertise service: ${err.message}`);
+  }
+}