aibroker 0.2.6 → 0.5.1

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "aibroker",
-  "version": "0.2.6",
+  "version": "0.5.1",
   "description": "Platform-agnostic AI message broker — routes between user channels and AI backends",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
+    "templates",
     "README.md",
     "LICENSE"
   ],
+  "bin": {
+    "aibroker": "dist/daemon/cli.js"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "start": "node dist/daemon/cli.js start",
     "prepublishOnly": "npm run build"
   },
   "repository": {
@@ -37,10 +42,12 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.1.0",
-    "kokoro-js": "^1.2.1"
+    "kokoro-js": "^1.2.1",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
     "typescript": "^5.0.0"
   }
 }

package/templates/adapter/ONBOARDING_PROMPT.md

@@ -0,0 +1,287 @@
+# AIBroker Adapter Onboarding — AI-Guided Creation
+
+You are helping a developer create a new AIBroker messaging adapter. Your job is to ask up to 5 targeted questions, then generate a complete, working adapter from the scaffold templates.
+
+Work through the following phases in order.
+
+---
+
+## Phase 1: Interview (5 questions max)
+
+Ask only what you need. If the answer is obvious from context (e.g. the user says "Discord"), skip the question. Combine questions where sensible. Never ask more than 5.
+
+**The 5 questions:**
+
+1. **Service name** — What service are you connecting? (e.g. Signal, Discord, Slack, IRC, Matrix)
+2. **Package name** — What npm package should be used? (If you don't know, say "search for me" — you will search npm.)
+3. **Auth method** — How does the SDK authenticate? (QR code scan, phone number + OTP, API key, OAuth, bot token, username/password)
+4. **Message model** — Does the service have the concept of channels/rooms/groups, or is it always a 1:1 direct chat? Who is the default recipient?
+5. **Voice support** — Does the service support sending voice/audio messages? If yes, what format does it accept? (Most accept OGG Opus or MP3.)
+
+If the user already answered any of these in their initial message, skip those questions.
+
+---
+
+## Phase 2: npm Research
+
+Before generating code, search npm for the best library for this service:
+
+```bash
+# Search npm for available packages
+npm search <service-name> --json | head -20
+
+# Read the top candidate's README
+npm show <package-name> readme
+```
+
+Pick the most maintained package (high weekly downloads, recent publish date, active repo). If the user specified a package, verify it exists and read its docs anyway.
+
+Read the package README for:
+- Connection/auth pattern (how to establish a session)
+- How to receive incoming messages (event name, callback signature)
+- How to send a text message (method name, arguments)
+- How to send a file/audio (if applicable)
+- Session persistence (does it save credentials to disk?)
+
+---
+
+## Phase 3: Generate the Adapter
+
+Generate all files listed below. Use the scaffold templates in `templates/adapter/` as the starting point and replace all `{{ADAPTER_NAME}}` and `{{DISPLAY_NAME}}` placeholders.
+
+**Variable substitution:**
+- `{{ADAPTER_NAME}}` — lowercase hyphenated package name (e.g. `signal-bridge`, `discord-adapter`)
+- `{{DISPLAY_NAME}}` — human-readable service name (e.g. `Signal`, `Discord`)
+
+### Files to generate
+
+**`package.json`** — from `templates/adapter/package.json.tmpl`
+- Fill in name, description
+- Add the chosen npm library to `dependencies`
+
+**`tsconfig.json`** — from `templates/adapter/tsconfig.json.tmpl`
+- No changes needed
+
+**`src/watcher/state.ts`** — from `templates/adapter/src/watcher/state.ts.tmpl`
+- Replace placeholders only
+- The socket path must be `/tmp/{{ADAPTER_NAME}}-watcher.sock`
+
+**`src/watcher/connection.ts`** — from `templates/adapter/src/watcher/connection.ts.tmpl`
+- THIS IS THE CORE IMPLEMENTATION FILE — replace the stub with real SDK code
+- Implement `connectWatcher()` using the library you researched
+- The function must:
+  1. Load credentials from `appDir` (use `getAppDir()` from aibroker if available, or `os.homedir()` + `.{{ADAPTER_NAME}}/auth/`)
+  2. Establish connection to the service
+  3. Subscribe to incoming messages, calling `onMessage(text, timestamp)` for each
+  4. Return `cleanup()` to disconnect gracefully
+  5. Return `triggerLogin()` to start a fresh auth flow (QR, OTP, etc.)
+- Include all necessary imports from the chosen npm package
+- Handle reconnection if the SDK supports it
+- Log connection events with `log()` from aibroker
+
+**`src/watcher/send.ts`** — from `templates/adapter/src/watcher/send.ts.tmpl`
+- Replace stubs with real SDK delivery calls
+- `sendText(text, recipient?)` — send plain text
+- `sendVoice(audioPath, recipient?)` — send OGG Opus audio file (skip with a clear comment if service does not support voice)
+- `sendFile(filePath, caption?, mimetype?, recipient?)` — send document attachment
+
+**`src/watcher/commands.ts`** — from `templates/adapter/src/watcher/commands.ts.tmpl`
+- Replace placeholders only
+- Add any service-specific slash commands if the service warrants them (e.g. `/channel #general` to switch rooms)
+
+**`src/watcher/ipc-server.ts`** — from `templates/adapter/src/watcher/ipc-server.ts.tmpl`
+- Replace placeholders only
+- The four required IPC handlers must be present: `deliver`, `health`, `connection_status`, `login`
+
+**`src/watcher/index.ts`** — from `templates/adapter/src/watcher/index.ts.tmpl`
+- Replace placeholders only
+- The hub detection pattern must remain intact
+
+**`src/watcher/cli.ts`** — from `templates/adapter/src/watcher/cli.ts.tmpl`
+- Replace placeholders only
+
+**`src/index.ts`** — MCP server entry point
+- Model this on Whazaa's `src/index.ts` (the reference implementation)
+- Expose MCP tools named `<service>_send`, `<service>_status`, `<service>_tts` (voice, if supported), `<service>_send_file`
+- Wire each tool to the corresponding IPC handler via `WatcherClient`
+- Socket path: `/tmp/{{ADAPTER_NAME}}-watcher.sock`
+
+**`README.md`** — from `templates/adapter/README.md.tmpl`
+- Fill in service name, auth instructions, and any service-specific setup steps
+
+---
+
+## Phase 4: Wire into AIBroker Config
+
+After generating the adapter files, register the adapter with the AIBroker hub:
+
+1. **Check if `~/.aibroker/config.json` exists.** If yes, add an entry to the `adapters` array:
+```json
+{
+  "name": "{{ADAPTER_NAME}}",
+  "socketPath": "/tmp/{{ADAPTER_NAME}}-watcher.sock",
+  "autoStart": false
+}
+```
+
+2. **Register as an MCP server** in `~/.claude.json` under `mcpServers`:
+```json
+"{{ADAPTER_NAME}}": {
+  "type": "stdio",
+  "command": "node",
+  "args": ["/path/to/{{ADAPTER_NAME}}/dist/index.js"],
+  "description": "{{DISPLAY_NAME}} MCP adapter"
+}
+```
+
+3. **Add permission** in `~/.claude/settings.json` under `permissions.allow`:
+```json
+"mcp__{{ADAPTER_NAME}}"
+```
+
+---
+
+## Phase 5: Test the Connection
+
+After generating all files:
+
+```bash
+# Build
+cd /path/to/{{ADAPTER_NAME}}
+npm install
+npm run build
+
+# Start the watcher (runs the upstream connection)
+node dist/watcher/cli.js watch
+
+# In a separate terminal, verify the IPC server is responding
+node -e "
+import { WatcherClient } from 'aibroker';
+const c = new WatcherClient('/tmp/{{ADAPTER_NAME}}-watcher.sock');
+c.call_raw('health', {}).then(r => console.log(JSON.stringify(r, null, 2)));
+"
+```
+
+Expected health response:
+```json
+{
+  "ok": true,
+  "result": {
+    "status": "ok",
+    "connectionStatus": "connected",
+    "stats": { "messagesReceived": 0, "messagesSent": 0, "errors": 0 },
+    "lastMessageAgo": null
+  }
+}
+```
+
+If `status` is `"down"` or `connectionStatus` is not `"connected"`, check the watcher logs for auth/connection errors and run `triggerLogin()` via the `login` IPC handler.
+
+---
+
+## Interface Contracts (Reference)
+
+### MessengerAdapter interface
+
+Every adapter fulfills this interface structurally via IPC handlers:
+
+```typescript
+interface MessengerAdapter {
+  // Lifecycle
+  start(config: AdapterConfig): Promise<void>;
+  stop(): Promise<void>;
+  health(): Promise<AdapterHealth>;       // IPC: "health"
+
+  // Auth
+  login(): Promise<string>;               // IPC: "login"
+  connectionStatus(): Promise<AdapterConnectionStatus>; // IPC: "connection_status"
+
+  // Outbound
+  sendText(text, recipient?): Promise<void>;                          // IPC: "send"
+  sendVoice(audioPath, recipient?): Promise<void>;                    // IPC: "send_voice"
+  sendFile(filePath, caption?, mimetype?, recipient?): Promise<void>; // IPC: "send_file"
+  sendImage(imagePath, caption?, recipient?): Promise<void>;          // IPC: "send_image"
+}
+```
+
+### BrokerMessage (hub envelope)
+
+```typescript
+interface BrokerMessage {
+  id: string;          // UUID
+  timestamp: number;   // epoch ms
+  source: string;      // adapter name that sent it
+  target?: string;     // target adapter name (omit for default routing)
+  type: "text" | "voice" | "file" | "command" | "status";
+  payload: {
+    text?: string;
+    filePath?: string;
+    audioPath?: string;
+    mimetype?: string;
+    caption?: string;
+    recipient?: string;
+    channel?: string;
+    metadata?: Record<string, unknown>;
+  };
+}
+```
+
+### Required IPC handlers
+
+| Handler | Called by | Must return |
+|---------|-----------|-------------|
+| `deliver` | Hub, when routing a BrokerMessage to this adapter | `{ ok: true, result: { delivered: true } }` or `{ ok: false, error: string }` |
+| `health` | Hub health polling | `{ ok: true, result: AdapterHealth }` |
+| `connection_status` | Hub, MCP tools | `{ ok: true, result: { status: AdapterConnectionStatus } }` |
+| `login` | User, via MCP tool | `{ ok: true, result: { message: string } }` |
+| `send` | MCP tool | `{ ok: true, result: { sent: true } }` |
+| `send_voice` | MCP tool | `{ ok: true, result: { sent: true } }` |
+| `send_file` | MCP tool | `{ ok: true, result: { sent: true } }` |
+| `status` | MCP tool | Human-readable status object |
+
+### Hub detection pattern
+
+The watcher probes the AIBroker daemon socket at startup:
+
+```typescript
+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;
+  }
+}
+```
+
+If `detectHubMode()` returns `true`, the adapter:
+- Forwards incoming messages to the hub via `route_message`
+- Registers itself via `register_adapter` so the hub can push outbound messages back
+
+If `false`, the adapter handles everything locally (embedded mode).
+
+---
+
+## Reference Implementation
+
+**Whazaa** is the canonical reference adapter. When in doubt, model behaviour on Whazaa:
+
+- Repo: `~/dev/ai/Whazaa/`
+- Key file — connection: `src/watcher/baileys.ts` (WhatsApp-specific connection)
+- Key file — send: `src/watcher/send.ts`
+- Key file — IPC: `src/watcher/ipc-server.ts`
+- Key file — MCP tools: `src/index.ts`
+- Key pattern — Baileys saves auth state to `~/.whazaa/auth/` via `useMultiFileAuthState()`
+
+The Whazaa pattern for `connectWatcher()` is:
+1. Call `useMultiFileAuthState(authDir)` (or equivalent for your SDK)
+2. Create the client instance with the auth state
+3. Set up message event listener calling `onMessage(text, timestamp)`
+4. Call `client.connect()` or equivalent
+5. Return `cleanup` (calls `client.logout()` or `client.disconnect()`) and `triggerLogin` (generates new QR/pairing)
+
+Follow this pattern exactly. The template scaffold maps cleanly onto it.

package/templates/adapter/README.md.tmpl

@@ -0,0 +1,98 @@
+# {{ADAPTER_NAME}}
+
+AIBroker adapter for {{DISPLAY_NAME}}.
+
+## Overview
+
+This adapter bridges {{DISPLAY_NAME}} and the [AIBroker](https://github.com/mnott/AIBroker) hub, enabling bidirectional message routing between {{DISPLAY_NAME}} and AI backends (Claude Code, Anthropic API, etc.).
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+npm install
+```
+
+### 2. Implement the connection
+
+Open `src/watcher/connection.ts` and implement `connectWatcher()` with your {{DISPLAY_NAME}} SDK.
+
+The function must:
+- Connect to {{DISPLAY_NAME}} using your credentials
+- Call `onMessage(text, timestamp)` for each incoming message
+- Return `cleanup()` (disconnect) and `triggerLogin()` (fresh auth flow)
+
+### 3. Implement outbound delivery
+
+Open `src/watcher/send.ts` and implement `sendText()`, `sendVoice()`, and `sendFile()`.
+
+### 4. Build
+
+```bash
+npm run build
+```
+
+### 5. Run
+
+```bash
+# Standalone (embedded) mode — no hub required
+npm run watch
+
+# Or: with AIBroker hub running
+aibroker start   # in another terminal
+npm run watch    # adapter auto-detects and registers with hub
+```
+
+## Architecture
+
+```
+{{DISPLAY_NAME}} <── connectWatcher() ──> watcher/index.ts
+                                              │
+                          createMessageHandler()  startIpcServer()
+                                              │         │
+                                        commands.ts  ipc-server.ts
+                                              │
+                                    AIBroker hub / embedded
+```
+
+## Configuration
+
+Set these environment variables before running:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AIBROKER_MODEL` | `sonnet` | AI model for API sessions |
+| `AIBROKER_CWD` | `~` | Working directory for AI sessions |
+| `AIBROKER_MAX_TURNS` | `30` | Max turns per API session |
+| `AIBROKER_MAX_BUDGET` | `1.0` | Max USD budget per API session |
+| `AIBROKER_PERMISSION_MODE` | `acceptEdits` | Claude permission mode |
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/h`, `/help` | Show help |
+| `/s`, `/sessions` | List all sessions |
+| `/ss`, `/status` | Show active session status |
+| `/n [name]` | Create a new API session |
+| `/1`, `/2`, ... | Switch to session by index |
+
+## IPC Methods
+
+The adapter exposes these methods on its Unix socket (`/tmp/{{ADAPTER_NAME}}-watcher.sock`):
+
+| Method | Description |
+|--------|-------------|
+| `deliver` | Hub pushes a BrokerMessage for outbound delivery |
+| `health` | Returns adapter health (status, stats, lastMessageAgo) |
+| `connection_status` | Returns upstream connection status string |
+| `send` | Send a text message |
+| `send_voice` | Send a voice note (OGG Opus path) |
+| `send_file` | Send a file attachment |
+| `login` | Trigger a fresh login / QR pairing flow |
+| `status` | Human-readable adapter status summary |
+
+## License
+
+MIT

package/templates/adapter/package.json.tmpl

@@ -0,0 +1,23 @@
+{
+  "name": "{{ADAPTER_NAME}}",
+  "version": "0.1.0",
+  "description": "AIBroker adapter for {{DISPLAY_NAME}}",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "{{ADAPTER_NAME}}": "dist/watcher/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "watch": "node dist/watcher/cli.js watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "aibroker": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { watch } from "./index.js";
+
+const command = process.argv[2];
+if (command === "watch" || !command) {
+  watch().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+  });
+} else {
+  console.log(`Usage: {{ADAPTER_NAME}} watch`);
+}

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

@@ -0,0 +1,146 @@
+/**
+ * commands.ts — Slash command handler for {{DISPLAY_NAME}}
+ *
+ * Parses incoming message text. If the text starts with "/" it is treated as
+ * a slash command; otherwise it is delivered as a plain message to the active
+ * AI session via the HybridSessionManager.
+ *
+ * Extend this file with adapter-specific slash commands as needed.
+ */
+
+import {
+  hybridManager,
+  deliverViaApi,
+  log,
+} from "aibroker";
+import { sendText } from "./send.js";
+
+// ── Command handler factory ───────────────────────────────────────────────────
+
+/**
+ * Build and return the message handler closure used by the watcher.
+ *
+ * The closure captures mutable state via getter/setter callbacks so the
+ * watcher's `watch()` function can keep its own local variables authoritative
+ * while sharing them with the handler.
+ */
+export function createMessageHandler(): (text: string, timestamp: number) => void {
+  return function handleMessage(text: string, _timestamp: number): void {
+    const trimmed = text.trim();
+
+    if (!trimmed.startsWith("/")) {
+      // Plain text — deliver to the active AI session
+      void deliverMessage(trimmed);
+      return;
+    }
+
+    // Slash command dispatch
+    void handleSlashCommand(trimmed);
+  };
+}
+
+// ── Slash command dispatcher ─────────────────────────────────────────────────
+
+async function handleSlashCommand(cmd: string): Promise<void> {
+  const [base, ...args] = cmd.split(/\s+/);
+
+  switch (base) {
+    case "/h":
+    case "/help":
+      await sendText(buildHelp());
+      return;
+
+    case "/s":
+    case "/sessions": {
+      const mgr = hybridManager;
+      if (!mgr) { await sendText("No session manager active."); return; }
+      await sendText(mgr.formatSessionList());
+      return;
+    }
+
+    case "/ss":
+    case "/status": {
+      const mgr = hybridManager;
+      if (!mgr) { await sendText("No session manager active."); return; }
+      const status = mgr.formatActiveStatus();
+      await sendText(status ?? "Active session is a visual terminal — no text status available.");
+      return;
+    }
+
+    case "/n":
+    case "/new": {
+      const mgr = hybridManager;
+      if (!mgr) { await sendText("No session manager active."); return; }
+      const cwd = process.env.AIBROKER_CWD ?? process.env.HOME ?? "/";
+      const name = args[0] ?? `Session ${Date.now()}`;
+      const session = mgr.createApiSession(name, cwd);
+      await sendText(`Created new API session: "${session.name}" (${session.id})`);
+      return;
+    }
+
+    default:
+      // Numeric shortcut: /1, /2, /3 — switch to session by index
+      if (/^\/\d+$/.test(base)) {
+        const idx = parseInt(base.slice(1), 10);
+        const mgr = hybridManager;
+        if (!mgr) { await sendText("No session manager active."); return; }
+        const session = mgr.switchToIndex(idx);
+        if (session) {
+          await sendText(`Switched to: "${session.name}" (${session.kind})`);
+        } else {
+          await sendText(`No session at index ${idx}.`);
+        }
+        return;
+      }
+
+      log(`[{{ADAPTER_NAME}}] Unknown command: ${cmd}`);
+      await sendText(`Unknown command: ${cmd}\nType /h for help.`);
+  }
+}
+
+// ── Message delivery ─────────────────────────────────────────────────────────
+
+async function deliverMessage(text: string): Promise<void> {
+  const mgr = hybridManager;
+  if (!mgr) {
+    log("[{{ADAPTER_NAME}}] No hybrid manager — dropping message");
+    return;
+  }
+
+  const active = mgr.activeSession;
+  if (!active) {
+    await sendText("No active session. Use /n to create one.");
+    return;
+  }
+
+  if (active.kind === "api") {
+    // Deliver via APIBackend — response comes back asynchronously via deliverViaApi
+    const response = await deliverViaApi(text, async (responseText: string) => {
+      await sendText(responseText);
+    });
+    if (response) {
+      // Synchronous response (some backends return inline)
+      await sendText(response);
+    }
+  } else {
+    // Visual (iTerm2) session — TODO: type into terminal if iTerm2 adapter is available
+    log(`[{{ADAPTER_NAME}}] Visual session delivery not yet implemented`);
+    await sendText("Visual session delivery not yet implemented for this adapter.");
+  }
+}
+
+// ── Help text ────────────────────────────────────────────────────────────────
+
+function buildHelp(): string {
+  return [
+    "*{{DISPLAY_NAME}} Adapter — Commands*",
+    "",
+    "/h, /help       — This help message",
+    "/s, /sessions   — List all sessions",
+    "/ss, /status    — Show active session status",
+    "/n [name]       — Create a new API session",
+    "/1, /2, ...     — Switch to session by index",
+    "",
+    "Any other text is delivered to the active AI session.",
+  ].join("\n");
+}

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

@@ -0,0 +1,59 @@
+/**
+ * connection.ts — Connect to {{DISPLAY_NAME}}
+ *
+ * TODO: Implement the upstream service connection here.
+ * This is the adapter-specific part — use the SDK/library for your service.
+ *
+ * Replace this stub with a real connection using the appropriate SDK, e.g.:
+ *   - @whiskeysockets/baileys  for WhatsApp
+ *   - gramjs / telegram        for Telegram
+ *   - discord.js               for Discord
+ *   - signal-cli               for Signal
+ *
+ * The onMessage callback receives every incoming message text so the watcher
+ * can route it through the command handler / hub forwarding.
+ */
+
+export interface ConnectionResult {
+  /** Call to cleanly disconnect from the upstream service. */
+  cleanup: () => void;
+  /**
+   * Trigger a new login flow (QR code, pairing, etc.) and return a
+   * human-readable status string to send back to the user.
+   */
+  triggerLogin: () => Promise<string>;
+}
+
+/**
+ * Establish the upstream connection.
+ *
+ * @param onMessage - Called for each incoming message the adapter should process.
+ *                    Receives the message text and the message timestamp (epoch ms).
+ */
+export async function connectWatcher(
+  onMessage: (text: string, timestamp: number) => void,
+): Promise<ConnectionResult> {
+  // TODO: Replace this stub with your actual connection logic.
+  //
+  // Typical pattern:
+  //   1. Load credentials from appDir (set by setAppDir() in index.ts)
+  //   2. Connect to the upstream service
+  //   3. Subscribe to incoming messages, calling onMessage() for each
+  //   4. Return cleanup() and triggerLogin() implementations
+  //
+  console.log("[{{ADAPTER_NAME}}] Connection stub — implement connectWatcher()");
+
+  // Suppress unused-parameter warning in stub
+  void onMessage;
+
+  return {
+    cleanup: () => {
+      // TODO: close WebSocket, stop polling, revoke auth, etc.
+      console.log("[{{ADAPTER_NAME}}] cleanup() called");
+    },
+    triggerLogin: async () => {
+      // TODO: start QR code / pairing flow, return status string
+      return "Login not yet implemented for {{DISPLAY_NAME}}";
+    },
+  };
+}