aibroker 0.2.6 → 0.5.1

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

@@ -0,0 +1,177 @@
+/**
+ * watcher/index.ts — {{DISPLAY_NAME}} adapter entry point
+ *
+ * Wires together:
+ *   1. Hub detection  — probe AIBroker daemon; enter hub or embedded mode
+ *   2. Connection     — connectWatcher() establishes the upstream service link
+ *   3. Command router — createMessageHandler() dispatches text / slash commands
+ *   4. IPC server     — startIpcServer() accepts calls from hub and MCP tools
+ *   5. Hub registration — if hub is running, announce this adapter's socket
+ *
+ * Lifecycle:
+ *   watch() → detectHubMode() → connectWatcher() → startIpcServer()
+ *          → [hub mode] register_adapter on hub
+ *          → await forever (exits on SIGINT / SIGTERM)
+ */
+
+import { unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  WatcherClient,
+  DAEMON_SOCKET_PATH,
+  setAppDir,
+  loadSessionRegistry,
+  APIBackend,
+  HybridSessionManager,
+  setHybridManager,
+  router,
+  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 detection ─────────────────────────────────────────────────────────────
+
+/**
+ * Probe the AIBroker hub daemon.
+ *
+ * Returns true if the hub is reachable on its standard socket within 2 seconds.
+ * On any failure the adapter runs in embedded (standalone) mode.
+ */
+async function detectHubMode(): Promise<boolean> {
+  const client = new WatcherClient(DAEMON_SOCKET_PATH);
+  try {
+    const result = await Promise.race([
+      client.call_raw("status", {}),
+      new Promise<null>((_, reject) => setTimeout(() => reject(new Error("timeout")), 2000)),
+    ]);
+    return result !== null;
+  } catch {
+    return false;
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Start the {{DISPLAY_NAME}} adapter watcher.
+ *
+ * Suspends the event loop indefinitely via `await new Promise(() => {})`.
+ * Exits only on SIGINT or SIGTERM.
+ */
+export async function watch(): Promise<void> {
+  setLogPrefix("{{ADAPTER_NAME}}-watch");
+  setAppDir(join(homedir(), ".{{ADAPTER_NAME}}"));
+
+  // Initialise hybrid session manager
+  const apiBackend = new APIBackend({
+    type: "api",
+    provider: "anthropic",
+    model: process.env.AIBROKER_MODEL ?? "sonnet",
+    cwd: process.env.AIBROKER_CWD,
+    maxTurns: Number(process.env.AIBROKER_MAX_TURNS) || 30,
+    maxBudgetUsd: Number(process.env.AIBROKER_MAX_BUDGET) || 1.0,
+    permissionMode: process.env.AIBROKER_PERMISSION_MODE ?? "acceptEdits",
+    skipDefaultSession: true,
+  });
+  const manager = new HybridSessionManager(apiBackend);
+  setHybridManager(manager);
+  manager.createApiSession("Default", process.env.AIBROKER_CWD ?? homedir());
+  router.setDefaultBackend(apiBackend);
+
+  // Detect whether the AIBroker hub daemon is running
+  const hubMode = await detectHubMode();
+  const hubClient = hubMode ? new WatcherClient(DAEMON_SOCKET_PATH) : null;
+
+  console.log(`{{DISPLAY_NAME}} Adapter Watch`);
+  console.log(`  Socket:  ${ADAPTER_SOCKET_PATH}`);
+  console.log(`  Mode:    ${hubMode ? "hub (daemon detected)" : "embedded (standalone)"}`);
+  console.log();
+
+  // Restore persisted session state
+  loadSessionRegistry();
+
+  // Graceful shutdown
+  let cleanupConnection: (() => void) | null = null;
+
+  const shutdown = (signal: string) => {
+    console.log(`\n[{{ADAPTER_NAME}}-watch] ${signal} received. Stopping.`);
+    setConnectionStatus("disconnected");
+    if (cleanupConnection) cleanupConnection();
+    if (hubClient) {
+      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"));
+
+  // Build the message handler
+  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;
+
+      if (hubMode && hubClient) {
+        // Hub mode: forward non-local messages to the hub for routing
+        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, handling locally: ${err instanceof Error ? err.message : String(err)}`);
+          handleMessage(text, timestamp);
+        });
+      } else {
+        // Embedded mode: handle everything locally
+        handleMessage(text, timestamp);
+      }
+    },
+  );
+
+  cleanupConnection = cleanup;
+  setConnectionStatus("connected");
+
+  // Start the adapter IPC server
+  startIpcServer(triggerLogin);
+
+  // Register with hub if running
+  if (hubMode && hubClient) {
+    log("Hub mode: registering with AIBroker hub daemon");
+    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)}`);
+    });
+  }
+
+  // Keep process alive
+  await new Promise(() => {});
+}

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

@@ -0,0 +1,226 @@
+/**
+ * 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": {
+          const audioPath = typeof payload.audioPath === "string" ? payload.audioPath : null;
+          if (!audioPath) return { ok: false, error: "deliver(voice): 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 "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"]
+}