openclaw-overlay-plugin 0.8.4 → 0.8.7

package/src/scripts/messaging/connect.ts

@@ -11,9 +11,9 @@ import { ensureStateDir } from '../utils/storage.js';
 
 /**
  * Connect command: establish WebSocket connection for real-time messaging.
- * Note: This function never returns normally - it runs until SIGINT/SIGTERM.
+ * Supports being used as a library with onMessage callback and AbortSignal.
  */
-export async function cmdConnect(): Promise<void> {
+export async function cmdConnect(onMessage?: (data: any) => void, signal?: AbortSignal): Promise<void> {
   let WebSocketClient: any;
   try {
     const ws = await import('ws');
@@ -34,19 +34,36 @@ export async function cmdConnect(): Promise<void> {
     if (currentWs) {
       try { currentWs.close(); } catch {}
     }
-    process.exit(0);
+    // Only exit if we're not running as a library
+    if (!onMessage) {
+      process.exit(0);
+    }
   }
 
-  process.on('SIGINT', shutdown);
-  process.on('SIGTERM', shutdown);
+  if (!onMessage) {
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  }
+
+  if (signal) {
+    signal.addEventListener('abort', () => {
+      shouldReconnect = false;
+      if (currentWs) {
+        try { currentWs.close(); } catch {}
+      }
+    });
+  }
 
   function connect() {
+    if (signal?.aborted) return;
     const ws = new WebSocketClient(wsUrl);
     currentWs = ws;
 
     ws.on('open', () => {
       reconnectDelay = 1000; // reset on successful connect
-      console.error(JSON.stringify({ event: 'connected', identity: identityKey, overlay: OVERLAY_URL }));
+      const log = { event: 'connected', identity: identityKey, overlay: OVERLAY_URL };
+      if (onMessage) onMessage(log);
+      else console.error(JSON.stringify(log));
     });
 
     ws.on('message', async (data: any) => {
@@ -54,8 +71,9 @@ export async function cmdConnect(): Promise<void> {
         const envelope = JSON.parse(data.toString());
         if (envelope.type === 'message') {
           const result = await processMessage(envelope.message, identityKey, privKey);
-          // Output the result as a JSON line to stdout
-          console.log(JSON.stringify(result));
+          
+          if (onMessage) onMessage(result);
+          else console.log(JSON.stringify(result));
 
           // Also append to notification log
           ensureStateDir();
@@ -72,7 +90,9 @@ export async function cmdConnect(): Promise<void> {
                 body: JSON.stringify({ identity: identityKey, messageIds: [result.id] }),
               });
             } catch (ackErr: any) {
-              console.error(JSON.stringify({ event: 'ack-error', id: result.id, message: String(ackErr) }));
+              const log = { event: 'ack-error', id: result.id, message: String(ackErr) };
+              if (onMessage) onMessage(log);
+              else console.error(JSON.stringify(log));
             }
           }
         }
@@ -90,32 +110,45 @@ export async function cmdConnect(): Promise<void> {
             txid: envelope.txid,
             _ts: Date.now(),
           };
-          console.log(JSON.stringify(announcement));
+          if (onMessage) onMessage(announcement);
+          else console.log(JSON.stringify(announcement));
+          
           ensureStateDir();
           try {
             fs.appendFileSync(PATHS.notifications, JSON.stringify(announcement) + '\n');
           } catch {}
         }
       } catch (err: any) {
-        console.error(JSON.stringify({ event: 'process-error', message: String(err) }));
+        const log = { event: 'process-error', message: String(err) };
+        if (onMessage) onMessage(log);
+        else console.error(JSON.stringify(log));
       }
     });
 
     ws.on('close', () => {
       currentWs = null;
-      if (shouldReconnect) {
-        console.error(JSON.stringify({ event: 'disconnected', reconnectMs: reconnectDelay }));
+      if (shouldReconnect && !signal?.aborted) {
+        const log = { event: 'disconnected', reconnectMs: reconnectDelay };
+        if (onMessage) onMessage(log);
+        else console.error(JSON.stringify(log));
+        
         setTimeout(connect, reconnectDelay);
         reconnectDelay = Math.min(reconnectDelay * 2, 30000);
       }
     });
 
     ws.on('error', (err: any) => {
-      console.error(JSON.stringify({ event: 'error', message: err.message }));
+      const log = { event: 'error', message: err.message };
+      if (onMessage) onMessage(log);
+      else console.error(JSON.stringify(log));
     });
   }
 
   connect();
-  // Keep the process alive — never resolves
-  await new Promise(() => {});
+  // Keep alive
+  return new Promise((resolve) => {
+    if (signal) {
+      signal.addEventListener('abort', () => resolve());
+    }
+  });
 }

package/src/scripts/messaging/inbox.ts

@@ -9,7 +9,7 @@ import { loadIdentity, verifyRelaySignature } from '../wallet/identity.js';
 /**
  * Inbox command: fetch pending messages.
  */
-export async function cmdInbox(args: string[]): Promise<never> {
+export async function cmdInbox(args: string[]): Promise<any> {
   const { identityKey } = await loadIdentity();
 
   let since = '';
@@ -41,7 +41,7 @@ export async function cmdInbox(args: string[]): Promise<never> {
 /**
  * Ack command: acknowledge processed messages.
  */
-export async function cmdAck(messageIds: string[]): Promise<never> {
+export async function cmdAck(messageIds: string[]): Promise<any> {
   if (!messageIds || messageIds.length === 0) {
     return fail('Usage: ack <messageId> [messageId2 ...]');
   }

package/src/scripts/messaging/poll.ts

@@ -10,7 +10,7 @@ import { processMessage } from './handlers.js';
 /**
  * Poll command: fetch all pending messages and process them.
  */
-export async function cmdPoll(): Promise<never> {
+export async function cmdPoll(): Promise<any> {
   const { identityKey, privKey } = await loadIdentity();
 
   // Fetch inbox

package/src/scripts/messaging/send.ts

@@ -13,7 +13,7 @@ export async function cmdSend(
   targetKey: string | undefined,
   type: string | undefined,
   payloadStr: string | undefined
-): Promise<never> {
+): Promise<any> {
   if (!targetKey || !type || !payloadStr) {
     return fail('Usage: send <identityKey> <type> <json_payload>');
   }

package/src/scripts/output.ts

@@ -3,19 +3,28 @@
  * All CLI output follows the { success, data/error } wrapper format.
  */
 
+// Global flag to prevent exit when used as a library
+let noExitFlag = false;
+
+export function setNoExit(value: boolean) {
+  noExitFlag = value;
+}
+
 /**
- * Output a successful result and exit.
+ * Output a successful result and exit (unless noExit is set).
  */
-export function ok<T>(data: T): never {
+export function ok<T>(data: T): any {
+  if (noExitFlag) return { success: true, data };
   console.log(JSON.stringify({ success: true, data }));
   process.exit(0);
 }
 
 /**
- * Output an error and exit.
+ * Output an error and exit (unless noExit is set).
  */
-export function fail(error: string | Error): never {
+export function fail(error: string | Error): any {
   const message = error instanceof Error ? error.message : String(error);
+  if (noExitFlag) return { success: false, error: message };
   console.log(JSON.stringify({ success: false, error: message }));
   process.exit(1);
 }

package/src/scripts/overlay/advertisement.ts

@@ -14,7 +14,7 @@ import { ok, fail } from '../output.js';
  * Advertise a SHIP record.
  * Announce that you host a specific Topic Manager (tm_).
  */
-export async function cmdAdvertiseSHIP(domain?: string, topic?: string): Promise<never> {
+export async function cmdAdvertiseSHIP(domain?: string, topic?: string): Promise<any> {
   if (!domain || !topic) {
     return fail('Usage: advertise-ship <domain> <topic>');
   }
@@ -65,7 +65,7 @@ export async function cmdAdvertiseSHIP(domain?: string, topic?: string): Promise
  * Advertise a SLAP record.
  * Announce that you host a specific Lookup Service (ls_).
  */
-export async function cmdAdvertiseSLAP(domain?: string, service?: string): Promise<never> {
+export async function cmdAdvertiseSLAP(domain?: string, service?: string): Promise<any> {
   if (!domain || !service) {
     return fail('Usage: advertise-slap <domain> <service>');
   }

package/src/scripts/overlay/discover.ts

@@ -9,7 +9,7 @@ import { lookupOverlay, parseOverlayOutput } from './transaction.js';
 /**
  * Discover command: query the overlay for agents and services.
  */
-export async function cmdDiscover(args: string[]): Promise<never> {
+export async function cmdDiscover(args: string[]): Promise<any> {
 
   // Parse flags
   let serviceFilter: string | null = null;

package/src/scripts/overlay/registration.ts

@@ -26,7 +26,7 @@ async function getBSVAgentWallet(): Promise<typeof BSVAgentWallet> {
 /**
  * Register command: register this agent on the overlay network.
  */
-export async function cmdRegister(): Promise<never> {
+export async function cmdRegister(): Promise<any> {
   if (!fs.existsSync(PATHS.walletIdentity)) {
     return fail('Wallet not initialized. Run: setup');
   }
@@ -135,7 +135,7 @@ export async function cmdRegister(): Promise<never> {
 /**
  * Unregister command: submit revocation tx to remove agent from overlay network.
  */
-export async function cmdUnregister(): Promise<never> {
+export async function cmdUnregister(): Promise<any> {
   
   const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
   const { outputs, BEEF } = await wallet._setup.wallet.listOutputs({ basket: TOPICS.IDENTITY, include: 'entire transactions' });

package/src/scripts/overlay/services.ts

@@ -27,7 +27,7 @@ async function getBSVAgentWallet(): Promise<typeof BSVAgentWallet> {
 /**
  * Services command: list currently advertised services.
  */
-export async function cmdServices(): Promise<never> {
+export async function cmdServices(): Promise<any> {
   const services = loadServices();
   return ok({ services, count: services.length });
 }
@@ -40,7 +40,7 @@ export async function cmdAdvertise(
   name: string | undefined,
   priceSatsStr: string | undefined,
   description?: string
-): Promise<never> {
+): Promise<any> {
   if (!serviceId || !name || !priceSatsStr) {
     return fail('Usage: advertise <serviceId> <name> <priceSats> [description]');
   }
@@ -108,7 +108,7 @@ export async function cmdAdvertise(
 /**
  * Remove command: remove a service from local registry.
  */
-export async function cmdRemove(serviceId: string | undefined): Promise<never> {
+export async function cmdRemove(serviceId: string | undefined): Promise<any> {
   if (!serviceId) {
     return fail('Usage: remove <serviceId>');
   }
@@ -137,7 +137,7 @@ export async function cmdReadvertise(
   name?: string,
   priceSatsStr?: string,
   description?: string
-): Promise<never> {
+): Promise<any> {
   if (!serviceId) {
     return fail('Usage: readvertise <serviceId> [name] [priceSats] [description]');
   }

package/src/scripts/payment/commands.ts

@@ -19,7 +19,7 @@ export async function cmdPay(
   pubkey: string | undefined,
   satoshis: string | undefined,
   description?: string
-): Promise<never> {
+): Promise<any> {
   if (!pubkey || !satoshis) {
     return fail('Usage: pay <pubkey> <satoshis> [description]');
   }
@@ -40,7 +40,7 @@ export async function cmdPay(
 /**
  * Verify command: verify an incoming payment BEEF.
  */
-export async function cmdVerify(beefBase64: string | undefined): Promise<never> {
+export async function cmdVerify(beefBase64: string | undefined): Promise<any> {
   if (!beefBase64) {
     return fail('Usage: verify <beef_base64>');
   }
@@ -67,7 +67,7 @@ export async function cmdAccept(
   derivationSuffix: string | undefined,
   senderIdentityKey: string | undefined,
   description?: string
-): Promise<never> {
+): Promise<any> {
   if (!beef || !derivationPrefix || !derivationSuffix || !senderIdentityKey) {
     return fail('Usage: accept <beef> <prefix> <suffix> <senderKey> [description]');
   }

package/src/scripts/services/queue.ts

@@ -10,7 +10,7 @@ import { readJsonl } from '../utils/storage.js';
 /**
  * Service queue command: list pending service requests.
  */
-export async function cmdServiceQueue(): Promise<never> {
+export async function cmdServiceQueue(): Promise<any> {
   if (!fs.existsSync(PATHS.serviceQueue)) {
     return ok({ pending: [], count: 0 });
   }
@@ -24,7 +24,7 @@ export async function cmdServiceQueue(): Promise<never> {
 /**
  * Research queue command: list pending research requests.
  */
-export async function cmdResearchQueue(): Promise<never> {
+export async function cmdResearchQueue(): Promise<any> {
   if (!fs.existsSync(PATHS.researchQueue)) {
     return ok({ pending: [] });
   }

package/src/scripts/services/request.ts

@@ -15,7 +15,7 @@ export async function cmdRequestService(
   serviceId: string | undefined,
   satsStr?: string,
   inputJsonStr?: string
-): Promise<never> {
+): Promise<any> {
   if (!targetKey || !serviceId) {
     return fail('Usage: request-service <identityKey> <serviceId> [sats] [inputJson]');
   }

package/src/scripts/services/respond.ts

@@ -16,7 +16,7 @@ export async function cmdRespondService(
   recipientKey: string | undefined,
   serviceId: string | undefined,
   resultJson: string | undefined
-): Promise<never> {
+): Promise<any> {
   if (!requestId || !recipientKey || !serviceId || !resultJson) {
     return fail('Usage: respond-service <requestId> <recipientKey> <serviceId> <resultJson>');
   }
@@ -93,7 +93,7 @@ export async function cmdRespondService(
 /**
  * Respond to a research request with results.
  */
-export async function cmdResearchRespond(resultJsonPath: string | undefined): Promise<never> {
+export async function cmdResearchRespond(resultJsonPath: string | undefined): Promise<any> {
   if (!resultJsonPath) return fail('Usage: research-respond <resultJsonFile>');
   if (!fs.existsSync(resultJsonPath)) return fail(`File not found: ${resultJsonPath}`);
 

package/src/scripts/wallet/balance.ts

@@ -59,7 +59,7 @@ function sleep(ms: number): Promise<void> {
 /**
  * Balance command: show wallet balance.
  */
-export async function cmdBalance(): Promise<never> {
+export async function cmdBalance(): Promise<any> {
   const BSVAgentWallet = await getBSVAgentWallet();
   const sdk = await getSdk();
 
@@ -80,7 +80,7 @@ export async function cmdBalance(): Promise<never> {
  * If the transaction isn't yet on WoC (just broadcast), it will poll
  * with exponential backoff for up to 60 seconds.
  */
-export async function cmdImport(txidArg: string | undefined, voutStr?: string): Promise<never> {
+export async function cmdImport(txidArg: string | undefined, voutStr?: string): Promise<any> {
   if (!txidArg) {
     return fail('Usage: import <txid> [vout]');
   }

package/src/scripts/wallet/setup.ts

@@ -49,7 +49,7 @@ async function getSdk(): Promise<any> {
 /**
  * Setup command: create wallet and show identity.
  */
-export async function cmdSetup(): Promise<never> {
+export async function cmdSetup(): Promise<any> {
   const BSVAgentWallet = await getBSVAgentWallet();
 
   if (fs.existsSync(PATHS.walletIdentity)) {
@@ -88,7 +88,7 @@ export async function cmdSetup(): Promise<never> {
 /**
  * Identity command: show identity public key.
  */
-export async function cmdIdentity(): Promise<never> {
+export async function cmdIdentity(): Promise<any> {
   const BSVAgentWallet = await getBSVAgentWallet();
   const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
   const identityKey = await wallet.getIdentityKey();
@@ -100,7 +100,7 @@ export async function cmdIdentity(): Promise<never> {
 /**
  * Status command: show identity and balance.
  */
-export async function cmdStatus(): Promise<never> {
+export async function cmdStatus(): Promise<any> {
   const BSVAgentWallet = await getBSVAgentWallet();
   const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
   const identityKey = await wallet.getIdentityKey();
@@ -116,7 +116,7 @@ export async function cmdStatus(): Promise<never> {
 /**
  * Address command: show P2PKH receive address.
  */
-export async function cmdAddress(): Promise<never> {
+export async function cmdAddress(): Promise<any> {
   if (!fs.existsSync(PATHS.walletIdentity)) {
     return fail('Wallet not initialized. Run: setup');
   }

package/src/scripts/x-verification/commands.ts

@@ -47,7 +47,7 @@ async function getSdk(): Promise<any> {
 /**
  * Start X verification: generate a tweet with identity key and signature.
  */
-export async function cmdXVerifyStart(handleArg: string | undefined): Promise<never> {
+export async function cmdXVerifyStart(handleArg: string | undefined): Promise<any> {
   if (!handleArg) {
     return fail('Usage: x-verify-start <@handle>');
   }
@@ -90,7 +90,7 @@ export async function cmdXVerifyStart(handleArg: string | undefined): Promise<ne
 /**
  * Complete X verification by checking the posted tweet.
  */
-export async function cmdXVerifyComplete(tweetUrl: string | undefined): Promise<never> {
+export async function cmdXVerifyComplete(tweetUrl: string | undefined): Promise<any> {
   if (!tweetUrl) return fail('Usage: x-verify-complete <tweet-url>');
 
   // Load pending verification
@@ -187,7 +187,7 @@ export async function cmdXVerifyComplete(tweetUrl: string | undefined): Promise<
 /**
  * List verified X accounts (local cache).
  */
-export async function cmdXVerifications(): Promise<never> {
+export async function cmdXVerifications(): Promise<any> {
   const verifications = loadXVerifications();
   return ok({ verifications, count: verifications.length });
 }
@@ -195,7 +195,7 @@ export async function cmdXVerifications(): Promise<never> {
 /**
  * Lookup X verifications from the overlay network.
  */
-export async function cmdXLookup(query: string | undefined): Promise<never> {
+export async function cmdXLookup(query: string | undefined): Promise<any> {
   try {
     const lookupQuery = query
       ? (query.startsWith('@') ? { xHandle: query } : { identityKey: query })
@@ -211,7 +211,7 @@ export async function cmdXLookup(query: string | undefined): Promise<never> {
 /**
  * List pending X engagement requests.
  */
-export async function cmdXEngagementQueue(): Promise<never> {
+export async function cmdXEngagementQueue(): Promise<any> {
   if (!fs.existsSync(PATHS.xEngagementQueue)) {
     return ok({ queue: [], count: 0 });
   }
@@ -227,7 +227,7 @@ export async function cmdXEngagementQueue(): Promise<never> {
 export async function cmdXEngagementFulfill(
   requestId: string | undefined,
   proofUrl?: string
-): Promise<never> {
+): Promise<any> {
   if (!requestId) return fail('Usage: x-engagement-fulfill <requestId> [proofUrl]');
 
   if (!fs.existsSync(PATHS.xEngagementQueue)) {