aibroker 0.2.6 → 0.6.1

package/templates/adapter/src/watcher/index.ts.tmpl

@@ -0,0 +1,201 @@
+/**
+ * watcher/index.ts — {{DISPLAY_NAME}} adapter entry point
+ *
+ * Thin transport adapter: connects to {{DISPLAY_NAME}}, forwards all messages
+ * to the AIBroker hub daemon for processing, and delivers hub responses back
+ * via the upstream service.
+ *
+ * Requires the AIBroker daemon to be running. Does not function standalone.
+ */
+
+import { unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  WatcherClient,
+  DAEMON_SOCKET_PATH,
+  setAppDir,
+  log,
+  setLogPrefix,
+  createBrokerMessage,
+} from "aibroker";
+
+import { connectWatcher } from "./connection.js";
+import { startIpcServer } from "./ipc-server.js";
+import { createMessageHandler } from "./commands.js";
+import {
+  ADAPTER_SOCKET_PATH,
+  adapterStats,
+  setConnectionStatus,
+} from "./state.js";
+
+// ── Hub connection ──────────────────────────────────────────────────────────
+
+/**
+ * Connect to the AIBroker hub daemon. Retries up to 3 times with 2s delay.
+ * Throws if the hub is not reachable — adapter cannot function without it.
+ */
+async function connectToHub(): Promise<WatcherClient> {
+  const client = new WatcherClient(DAEMON_SOCKET_PATH);
+  const MAX_RETRIES = 3;
+  const RETRY_DELAY = 2000;
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      const result = await Promise.race([
+        client.call_raw("ping", {}),
+        new Promise<null>((_, reject) =>
+          setTimeout(() => reject(new Error("timeout")), 2000),
+        ),
+      ]);
+      if (result !== null) return client;
+    } catch {
+      if (attempt < MAX_RETRIES) {
+        log(`Hub not reachable (attempt ${attempt}/${MAX_RETRIES}), retrying in ${RETRY_DELAY}ms...`);
+        await new Promise((r) => setTimeout(r, RETRY_DELAY));
+      }
+    }
+  }
+
+  throw new Error(
+    `AIBroker daemon not reachable at ${DAEMON_SOCKET_PATH}. ` +
+    `Start it with: aibroker start`
+  );
+}
+
+/**
+ * Slash commands handled locally (require direct upstream service access).
+ * Everything else goes to the hub.
+ */
+const LOCAL_SLASH_COMMANDS = new Set(["/restart", "/login"]);
+
+function isLocalSlashCommand(text: string): boolean {
+  return LOCAL_SLASH_COMMANDS.has(text.trim());
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Start the {{DISPLAY_NAME}} adapter watcher — thin transport adapter.
+ *
+ * All command handling, session management, TTS, and screenshots are owned
+ * by the AIBroker hub daemon. This process only:
+ * 1. Connects to the upstream service
+ * 2. Forwards incoming messages to the hub
+ * 3. Delivers hub-originated messages via the upstream service (through IPC "deliver")
+ * 4. Handles /restart and /login locally
+ */
+export async function watch(): Promise<void> {
+  setLogPrefix("{{ADAPTER_NAME}}-watch");
+  setAppDir(join(homedir(), ".{{ADAPTER_NAME}}"));
+
+  // Connect to AIBroker hub (required — no standalone mode)
+  let hubClient: WatcherClient;
+  try {
+    hubClient = await connectToHub();
+  } catch (err) {
+    console.error(`[{{ADAPTER_NAME}}-watch] FATAL: ${err instanceof Error ? err.message : String(err)}`);
+    console.error("[{{ADAPTER_NAME}}-watch] The AIBroker daemon must be running. Exiting.");
+    process.exit(1);
+  }
+
+  console.log(`{{DISPLAY_NAME}} Adapter Watch`);
+  console.log(`  Socket:  ${ADAPTER_SOCKET_PATH}`);
+  console.log(`  Hub:     ${DAEMON_SOCKET_PATH}`);
+  console.log();
+
+  // Graceful shutdown
+  let cleanupConnection: (() => void) | null = null;
+
+  const shutdown = (signal: string) => {
+    console.log(`\n[{{ADAPTER_NAME}}-watch] ${signal} received. Stopping.`);
+    clearInterval(heartbeatTimer);
+    setConnectionStatus("disconnected");
+    if (cleanupConnection) cleanupConnection();
+    hubClient.call_raw("unregister_adapter", { name: "{{ADAPTER_NAME}}" }).catch(() => {});
+    try { unlinkSync(ADAPTER_SOCKET_PATH); } catch { /* ignore */ }
+    process.exit(0);
+  };
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+  // Local handler for /restart and /login only
+  const handleMessage = createMessageHandler();
+
+  // Connect to the upstream service
+  console.log(`Connecting to {{DISPLAY_NAME}}...\n`);
+  setConnectionStatus("connecting");
+
+  const { cleanup, triggerLogin } = await connectWatcher(
+    (text: string, timestamp: number) => {
+      log(`[{{ADAPTER_NAME}}] incoming: ${text.slice(0, 80)}`);
+      adapterStats.messagesReceived++;
+      adapterStats.lastMessageAt = timestamp;
+
+      // Local commands stay in the adapter
+      if (isLocalSlashCommand(text)) {
+        handleMessage(text, timestamp);
+        return;
+      }
+
+      // Everything else → hub
+      const message = createBrokerMessage(
+        "{{ADAPTER_NAME}}",
+        text.trim().startsWith("/") ? "command" : "text",
+        { text },
+      );
+      message.timestamp = timestamp;
+
+      hubClient.call_raw("route_message", {
+        message: message as unknown as Record<string, unknown>,
+      }).catch((err) => {
+        log(`Hub route_message failed: ${err instanceof Error ? err.message : String(err)}`);
+      });
+    },
+  );
+
+  cleanupConnection = cleanup;
+  setConnectionStatus("connected");
+
+  // Start the adapter IPC server
+  startIpcServer(triggerLogin);
+
+  // Register with hub
+  hubClient.call_raw("register_adapter", {
+    name: "{{ADAPTER_NAME}}",
+    socketPath: ADAPTER_SOCKET_PATH,
+  }).then(() => {
+    log("Registered with AIBroker hub daemon");
+  }).catch((err) => {
+    log(`Hub registration failed: ${err instanceof Error ? err.message : String(err)}`);
+  });
+
+  // Hub heartbeat — re-register if the daemon restarts
+  const HUB_HEARTBEAT_INTERVAL = 30_000; // 30 seconds
+  const heartbeatTimer = setInterval(async () => {
+    try {
+      const result = await Promise.race([
+        hubClient.call_raw("ping", {}),
+        new Promise<null>((_, reject) =>
+          setTimeout(() => reject(new Error("timeout")), 5000),
+        ),
+      ]);
+      if (result === null) throw new Error("null response");
+    } catch {
+      // Hub unreachable — try to re-register
+      log("Hub heartbeat failed — attempting re-registration...");
+      hubClient.call_raw("register_adapter", {
+        name: "{{ADAPTER_NAME}}",
+        socketPath: ADAPTER_SOCKET_PATH,
+      }).then(() => {
+        log("Re-registered with AIBroker hub daemon");
+      }).catch((err) => {
+        log(`Hub re-registration failed: ${err instanceof Error ? err.message : String(err)}`);
+      });
+    }
+  }, HUB_HEARTBEAT_INTERVAL);
+
+  // Keep process alive
+  await new Promise(() => {});
+}

package/templates/adapter/src/watcher/ipc-server.ts.tmpl

@@ -0,0 +1,250 @@
+/**
+ * ipc-server.ts — Adapter-side IPC server for {{DISPLAY_NAME}}
+ *
+ * Registers the handlers that the AIBroker hub (and MCP tools) can call
+ * on this adapter's Unix Domain Socket.
+ *
+ * Required handlers (called by the hub):
+ *   deliver          — hub pushes a BrokerMessage to this adapter for outbound delivery
+ *   health           — hub polls adapter health
+ *   connection_status — returns the upstream connection status string
+ *
+ * Optional handlers (called by MCP tools or the hub):
+ *   send             — send a text message
+ *   send_voice       — send a voice note (OGG Opus path)
+ *   send_file        — send a file attachment
+ *   login            — trigger a new login / QR pairing flow
+ *   status           — human-readable status summary
+ */
+
+import { IpcServer, log } from "aibroker";
+import type { BrokerMessage } from "aibroker";
+
+import { ADAPTER_SOCKET_PATH, adapterStats, connectionStatus, getLastMessageAgo } from "./state.js";
+import { sendText, sendVoice, sendFile } from "./send.js";
+
+let triggerLoginFn: (() => Promise<string>) | null = null;
+
+/**
+ * Create, register handlers on, and start the adapter IPC server.
+ *
+ * @param triggerLogin - Async function that starts a fresh login flow and
+ *                       returns a human-readable status string.
+ * @returns The IpcServer instance (already started).
+ */
+export function startIpcServer(triggerLogin: () => Promise<string>): IpcServer {
+  triggerLoginFn = triggerLogin;
+
+  const server = new IpcServer(ADAPTER_SOCKET_PATH);
+
+  // ── Hub-required handlers ──────────────────────────────────────────────────
+
+  /**
+   * deliver — Hub pushes a BrokerMessage for outbound delivery.
+   *
+   * The hub calls this when it has routed a message to this adapter.
+   * Inspect message.type to decide how to deliver:
+   *   "text"    → sendText
+   *   "voice"   → sendVoice
+   *   "file"    → sendFile
+   *   "command" → run through local command handler
+   */
+  server.on("deliver", async (req) => {
+    const { message } = req.params as { message: BrokerMessage };
+    if (!message || !message.type) {
+      return { ok: false, error: "Invalid BrokerMessage: type is required" };
+    }
+
+    log(`[{{ADAPTER_NAME}}] deliver: type=${message.type} source=${message.source}`);
+
+    try {
+      const payload = message.payload ?? {};
+      const recipient = typeof payload.recipient === "string" ? payload.recipient : undefined;
+
+      switch (message.type) {
+        case "text": {
+          const text = typeof payload.text === "string" ? payload.text : String(payload.text ?? "");
+          await sendText(text, recipient);
+          break;
+        }
+        case "voice": {
+          // Hub sends pre-encoded audio as base64 buffer, or audioPath as fallback
+          const voiceB64 = typeof payload.buffer === "string" ? payload.buffer : "";
+          if (voiceB64) {
+            // Pre-encoded audio from hub — write to temp file and send
+            const { writeFileSync } = await import("node:fs");
+            const { join } = await import("node:path");
+            const { tmpdir } = await import("node:os");
+            const tmpPath = join(tmpdir(), `{{ADAPTER_NAME}}-voice-${Date.now()}.ogg`);
+            writeFileSync(tmpPath, Buffer.from(voiceB64, "base64"));
+            await sendVoice(tmpPath, recipient);
+          } else {
+            const audioPath = typeof payload.audioPath === "string" ? payload.audioPath : null;
+            if (!audioPath) return { ok: false, error: "deliver(voice): buffer or audioPath is required" };
+            await sendVoice(audioPath, recipient);
+          }
+          break;
+        }
+        case "file": {
+          const filePath = typeof payload.filePath === "string" ? payload.filePath : null;
+          if (!filePath) return { ok: false, error: "deliver(file): filePath is required" };
+          const caption = typeof payload.caption === "string" ? payload.caption : undefined;
+          const mimetype = typeof payload.mimetype === "string" ? payload.mimetype : undefined;
+          await sendFile(filePath, caption, mimetype, recipient);
+          break;
+        }
+        case "image": {
+          // Image delivery — payload contains base64-encoded buffer and optional caption
+          const buffer = typeof payload.buffer === "string"
+            ? Buffer.from(payload.buffer, "base64")
+            : null;
+          if (!buffer) return { ok: false, error: "deliver(image): buffer is required" };
+          const imgCaption = typeof payload.text === "string" ? payload.text : undefined;
+          // TODO: implement image sending via your SDK. For now, fall back to caption text.
+          if (imgCaption) await sendText(imgCaption, recipient);
+          log(`[{{ADAPTER_NAME}}] deliver(image): ${buffer.length} bytes — implement image sending`);
+          break;
+        }
+        case "command": {
+          // Commands from the hub (e.g. routed from another adapter) — deliver as text
+          const text = typeof payload.text === "string" ? payload.text : String(payload.text ?? "");
+          await sendText(text, recipient);
+          break;
+        }
+        default:
+          log(`[{{ADAPTER_NAME}}] deliver: unhandled message type "${message.type}"`);
+          return { ok: false, error: `Unhandled message type: ${message.type}` };
+      }
+
+      return { ok: true, result: { delivered: true } };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      log(`[{{ADAPTER_NAME}}] deliver error: ${msg}`);
+      adapterStats.errors++;
+      return { ok: false, error: msg };
+    }
+  });
+
+  /**
+   * health — Hub polls this to determine adapter liveness.
+   *
+   * Returns AdapterHealth-compatible shape.
+   */
+  server.on("health", async (_req) => {
+    const isConnected = connectionStatus === "connected";
+    return {
+      ok: true,
+      result: {
+        status: isConnected ? "ok" : connectionStatus === "connecting" ? "degraded" : "down",
+        connectionStatus,
+        stats: {
+          messagesReceived: adapterStats.messagesReceived,
+          messagesSent: adapterStats.messagesSent,
+          errors: adapterStats.errors,
+        },
+        lastMessageAgo: getLastMessageAgo(),
+      },
+    };
+  });
+
+  /**
+   * connection_status — Returns the upstream connection status as a string.
+   */
+  server.on("connection_status", async (_req) => {
+    return {
+      ok: true,
+      result: { status: connectionStatus },
+    };
+  });
+
+  // ── Optional outbound handlers ─────────────────────────────────────────────
+
+  /**
+   * send — Send a text message.
+   */
+  server.on("send", async (req) => {
+    const { message, recipient } = req.params as { message?: string; recipient?: string };
+    if (!message) return { ok: false, error: "message is required" };
+    try {
+      await sendText(message, recipient);
+      return { ok: true, result: { sent: true } };
+    } catch (err) {
+      adapterStats.errors++;
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  });
+
+  /**
+   * send_voice — Send a voice note from a file path (OGG Opus).
+   */
+  server.on("send_voice", async (req) => {
+    const { audioPath, recipient } = req.params as { audioPath?: string; recipient?: string };
+    if (!audioPath) return { ok: false, error: "audioPath is required" };
+    try {
+      await sendVoice(audioPath, recipient);
+      return { ok: true, result: { sent: true } };
+    } catch (err) {
+      adapterStats.errors++;
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  });
+
+  /**
+   * send_file — Send a file attachment.
+   */
+  server.on("send_file", async (req) => {
+    const { filePath, caption, mimetype, recipient } = req.params as {
+      filePath?: string;
+      caption?: string;
+      mimetype?: string;
+      recipient?: string;
+    };
+    if (!filePath) return { ok: false, error: "filePath is required" };
+    try {
+      await sendFile(filePath, caption, mimetype, recipient);
+      return { ok: true, result: { sent: true } };
+    } catch (err) {
+      adapterStats.errors++;
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  });
+
+  /**
+   * login — Trigger a fresh login / QR pairing flow.
+   */
+  server.on("login", async (_req) => {
+    if (!triggerLoginFn) return { ok: false, error: "Login not available" };
+    try {
+      const result = await triggerLoginFn();
+      return { ok: true, result: { message: result } };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  });
+
+  /**
+   * status — Human-readable adapter status summary.
+   */
+  server.on("status", async (_req) => {
+    const agoMs = getLastMessageAgo();
+    const agoStr = agoMs !== null
+      ? `${Math.round(agoMs / 1000)}s ago`
+      : "never";
+    return {
+      ok: true,
+      result: {
+        adapter: "{{ADAPTER_NAME}}",
+        displayName: "{{DISPLAY_NAME}}",
+        connectionStatus,
+        messagesReceived: adapterStats.messagesReceived,
+        messagesSent: adapterStats.messagesSent,
+        errors: adapterStats.errors,
+        lastMessageAgo: agoStr,
+      },
+    };
+  });
+
+  server.start();
+  log(`[{{ADAPTER_NAME}}] IPC server started on ${ADAPTER_SOCKET_PATH}`);
+  return server;
+}

package/templates/adapter/src/watcher/send.ts.tmpl

@@ -0,0 +1,62 @@
+/**
+ * send.ts — Outbound message delivery for {{DISPLAY_NAME}}
+ *
+ * These functions are called by the IPC server handlers when the hub (or an
+ * MCP tool) wants to send a message to the upstream service.
+ *
+ * TODO: Replace each stub with real delivery logic using your SDK.
+ */
+
+import { adapterStats } from "./state.js";
+
+// ── Text ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Send a plain-text message to the upstream service.
+ *
+ * @param text      The message body.
+ * @param recipient Optional channel/user/room identifier. Defaults to self-chat.
+ */
+export async function sendText(text: string, recipient?: string): Promise<void> {
+  // TODO: deliver text via your SDK
+  console.log(`[{{ADAPTER_NAME}}] sendText stub — text="${text.slice(0, 60)}" recipient=${recipient ?? "(default)"}`);
+  adapterStats.messagesSent++;
+}
+
+// ── Voice ────────────────────────────────────────────────────────────────────
+
+/**
+ * Send an audio file as a voice note.
+ *
+ * The file at audioPath is an OGG/Opus buffer produced by Kokoro TTS.
+ * Most messaging platforms accept OGG Opus for voice notes.
+ *
+ * @param audioPath Path to the OGG Opus audio file on disk.
+ * @param recipient Optional channel/user/room identifier.
+ */
+export async function sendVoice(audioPath: string, recipient?: string): Promise<void> {
+  // TODO: upload and send audio file via your SDK
+  console.log(`[{{ADAPTER_NAME}}] sendVoice stub — path="${audioPath}" recipient=${recipient ?? "(default)"}`);
+  adapterStats.messagesSent++;
+}
+
+// ── File ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Send an arbitrary file as a document attachment.
+ *
+ * @param filePath  Path to the file on disk.
+ * @param caption   Optional caption shown beneath the attachment.
+ * @param mimetype  Optional MIME type override. Detected automatically if omitted.
+ * @param recipient Optional channel/user/room identifier.
+ */
+export async function sendFile(
+  filePath: string,
+  caption?: string,
+  mimetype?: string,
+  recipient?: string,
+): Promise<void> {
+  // TODO: upload and send file via your SDK
+  console.log(`[{{ADAPTER_NAME}}] sendFile stub — path="${filePath}" caption="${caption ?? ""}" mime="${mimetype ?? "auto"}" recipient=${recipient ?? "(default)"}`);
+  adapterStats.messagesSent++;
+}

package/templates/adapter/src/watcher/state.ts.tmpl

@@ -0,0 +1,39 @@
+/**
+ * state.ts — {{DISPLAY_NAME}} adapter local state
+ *
+ * Tracks connection status, per-run statistics, and the socket path
+ * for the adapter's IPC server. All fields are module-level singletons
+ * written by the watcher and read by the IPC server handlers.
+ */
+
+import type { AdapterConnectionStatus } from "aibroker";
+
+// ── Connection tracking ──────────────────────────────────────────────────────
+
+/** Current upstream connection status. */
+export let connectionStatus: AdapterConnectionStatus = "disconnected";
+
+export function setConnectionStatus(s: AdapterConnectionStatus): void {
+  connectionStatus = s;
+}
+
+// ── Per-run statistics ───────────────────────────────────────────────────────
+
+/** Statistics reset on each watcher restart (not persisted). */
+export const adapterStats = {
+  messagesReceived: 0,
+  messagesSent: 0,
+  errors: 0,
+  lastMessageAt: null as number | null,
+};
+
+// ── Socket path ──────────────────────────────────────────────────────────────
+
+/** Unix Domain Socket path for the adapter's IPC server. */
+export const ADAPTER_SOCKET_PATH = "/tmp/{{ADAPTER_NAME}}-watcher.sock";
+
+/** Timestamp of the last incoming message (epoch ms). */
+export function getLastMessageAgo(): number | null {
+  if (adapterStats.lastMessageAt === null) return null;
+  return Date.now() - adapterStats.lastMessageAt;
+}

package/templates/adapter/tsconfig.json.tmpl

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}