privateer-agent 0.3.5 → 0.4.0

package/src/channels/slack.ts

@@ -0,0 +1,176 @@
+// Slack channel adapter — templated off the Telegram one against the same
+// ChannelAdapter interface. Uses Socket Mode (an outbound WebSocket), so like
+// Telegram long-poll it needs NO public inbound endpoint: it works from a laptop
+// behind NAT. Zero new dependencies — `ws` is already a dep (see relayClient.ts)
+// and the rest is the Slack Web API over fetch.
+//
+// Slack app setup (one-time):
+//   - Enable Socket Mode → generate an app-level token `xapp-…` (scope
+//     connections:write). That's `appToken`.
+//   - Bot token `xoxb-…` with scope `chat:write`. That's `botToken`.
+//   - Event Subscriptions → subscribe the bot to `message.im` (DMs). Then DM the bot.
+//
+// Everything above the adapter (allowlist, serialization, redaction, chunking) is
+// MessagingBridge, reused verbatim.
+
+import WebSocket from "ws";
+import type { ChannelAdapter, InboundMessage } from "./types.ts";
+
+const API = "https://slack.com/api";
+const RECONNECT_MS = 3000;
+const HTTP_TIMEOUT_MS = 15_000;
+
+// The Events-API payload we read (Socket Mode wraps this in an envelope).
+interface SlackEventPayload {
+  event?: {
+    type?: string;
+    subtype?: string;
+    bot_id?: string;
+    user?: string;
+    text?: string;
+    channel?: string;
+  };
+}
+
+// Pure mapping: an Events-API payload → normalized InboundMessage, or null for
+// anything we shouldn't treat as a user prompt. Critically filters out our own
+// bot's messages (`bot_id`) and non-plain events (`subtype`: edits, joins, etc.)
+// so the agent never talks to itself. Extracted so it's unit-testable.
+export function messageFromSlackEvent(payload: SlackEventPayload): InboundMessage | null {
+  const ev = payload.event;
+  if (!ev || ev.type !== "message") return null;
+  if (ev.bot_id || ev.subtype) return null; // bot echoes / edits / system messages
+  if (typeof ev.text !== "string" || !ev.channel || !ev.user) return null;
+  return { chatId: ev.channel, userId: ev.user, text: ev.text };
+}
+
+export interface SlackOptions {
+  appToken: string; // xapp-… (Socket Mode connection)
+  botToken: string; // xoxb-… (chat:write)
+  fetchImpl?: typeof fetch;
+  onLog?: (msg: string) => void;
+}
+
+export class SlackAdapter implements ChannelAdapter {
+  readonly name = "slack";
+  private readonly appToken: string;
+  private readonly botToken: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly onLog?: (msg: string) => void;
+  private ws?: WebSocket;
+  private running = false;
+  private reconnectTimer?: ReturnType<typeof setTimeout>;
+  private onMessage?: (m: InboundMessage) => void;
+
+  constructor(opts: SlackOptions) {
+    this.appToken = opts.appToken;
+    this.botToken = opts.botToken;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.onLog = opts.onLog;
+  }
+
+  async start(onMessage: (m: InboundMessage) => void): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+    this.onMessage = onMessage;
+    await this.connect();
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    try {
+      this.ws?.close();
+    } catch {
+      /* ignore */
+    }
+    this.ws = undefined;
+  }
+
+  async sendText(chatId: string, text: string): Promise<void> {
+    if (!text) return;
+    const res = await this.web("chat.postMessage", { channel: chatId, text });
+    const data = (await res.json().catch(() => ({}))) as { ok?: boolean; error?: string };
+    if (!data.ok) this.log(`chat.postMessage failed: ${data.error ?? "unknown"}`);
+  }
+
+  // Slack has no bot "typing" over the Web API, so sendTyping is intentionally
+  // absent — the bridge guards `sendTyping?.()`.
+
+  private log(msg: string): void {
+    this.onLog?.(`slack: ${msg}`);
+  }
+
+  // Mint a fresh Socket Mode WSS URL and connect. Slack rotates the URL, sending a
+  // `disconnect` frame before it does; we just reconnect (re-minting) each time.
+  private async connect(): Promise<void> {
+    if (!this.running) return;
+    let url: string;
+    try {
+      const res = await this.web("apps.connections.open", {}, this.appToken);
+      const data = (await res.json()) as { ok?: boolean; url?: string; error?: string };
+      if (!data.ok || !data.url) throw new Error(data.error ?? "no url");
+      url = data.url;
+    } catch (e) {
+      this.log(`apps.connections.open failed: ${e instanceof Error ? e.message : String(e)} — retrying`);
+      return this.scheduleReconnect();
+    }
+
+    const ws = new WebSocket(url);
+    this.ws = ws;
+    ws.on("message", (raw) => this.handleFrame(ws, raw));
+    ws.on("close", () => {
+      if (this.ws === ws) this.ws = undefined;
+      if (this.running) this.scheduleReconnect();
+    });
+    ws.on("error", (err: Error) => this.log(`ws error: ${err?.message ?? err}`));
+  }
+
+  private scheduleReconnect(): void {
+    if (!this.running || this.reconnectTimer) return;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      void this.connect();
+    }, RECONNECT_MS);
+  }
+
+  private handleFrame(ws: WebSocket, raw: WebSocket.RawData): void {
+    let frame: { type?: string; envelope_id?: string; payload?: SlackEventPayload };
+    try {
+      frame = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    // Ack EVERY envelope immediately (Slack retries if not acked within 3s), before
+    // doing any work — onMessage only queues an async turn.
+    if (frame.envelope_id) {
+      try {
+        ws.send(JSON.stringify({ envelope_id: frame.envelope_id }));
+      } catch {
+        /* socket dying */
+      }
+    }
+    if (frame.type === "disconnect") {
+      // URL refresh / server drain — drop this socket; `close` reconnects.
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+      return;
+    }
+    if (frame.type === "events_api" && frame.payload) {
+      const m = messageFromSlackEvent(frame.payload);
+      if (m) this.onMessage?.(m);
+    }
+  }
+
+  private async web(method: string, body: Record<string, unknown>, token = this.botToken): Promise<Response> {
+    return this.fetchImpl(`${API}/${method}`, {
+      method: "POST",
+      headers: { "content-type": "application/json; charset=utf-8", authorization: `Bearer ${token}` },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    });
+  }
+}

package/src/channels/status.ts

@@ -0,0 +1,54 @@
+// Channels daemon heartbeat — the one bit of shared state between the channels
+// daemon (channels/run.ts, the WRITER) and the always-on management relay
+// (daemon/index.ts → channelsControl, the READER).
+//
+// The two run as SEPARATE processes, so the manager can't ask the channels
+// daemon directly whether it's live. Instead the channels daemon writes a small
+// heartbeat file with the platforms it's currently serving; the reader treats a
+// FRESH heartbeat as "running" and a stale/absent one as "not running". This is
+// best-effort presence, never a dependency: a missing file just means the app
+// shows the platform as configured-but-offline.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "../config/paths.ts";
+
+// Heartbeat cadence + freshness window. The channels daemon rewrites the file
+// every HEARTBEAT_MS; a heartbeat older than STALE_MS is treated as dead (the
+// process exited without clearing it, or wedged).
+export const HEARTBEAT_MS = 30_000;
+const STALE_MS = 90_000; // 3 missed beats
+
+interface ChannelsStatus {
+  pid: number;
+  at: string; // ISO timestamp of the last heartbeat
+  platforms: string[]; // platforms with a live bridge this beat
+}
+
+function statusPath(): string {
+  return join(globalDir(), "channels-status.json");
+}
+
+// WRITER: record which platforms have a live bridge right now. Called on start
+// and on each heartbeat tick. Best-effort — a failed write never breaks a turn.
+export function writeChannelsStatus(platforms: string[]): void {
+  try {
+    const status: ChannelsStatus = { pid: process.pid, at: new Date().toISOString(), platforms };
+    writeFileSync(statusPath(), JSON.stringify(status));
+  } catch {
+    /* best effort */
+  }
+}
+
+// READER: the set of platforms the channels daemon is currently serving, or an
+// empty set when the daemon is down / the heartbeat is stale. Never throws.
+export function readRunningPlatforms(): Set<string> {
+  try {
+    const status = JSON.parse(readFileSync(statusPath(), "utf8")) as ChannelsStatus;
+    const age = Date.now() - Date.parse(status.at);
+    if (!Number.isFinite(age) || age > STALE_MS) return new Set();
+    return new Set(Array.isArray(status.platforms) ? status.platforms.map(String) : []);
+  } catch {
+    return new Set();
+  }
+}

package/src/channels/telegram.ts

@@ -0,0 +1,139 @@
+// Telegram channel adapter — the least-friction platform to prototype: a bot token
+// from @BotFather, plain HTTPS, long-poll `getUpdates` (no public endpoint, no
+// gateway socket, no app review). Zero new dependencies — the Bot API is just JSON
+// over fetch.
+//
+// This file is the ONLY platform-specific code. A Slack/Discord/WhatsApp adapter
+// implements the same ChannelAdapter interface and reuses MessagingBridge verbatim.
+
+import type { ChannelAdapter, InboundMessage } from "./types.ts";
+
+const API = "https://api.telegram.org";
+// Long-poll seconds we ask Telegram to hold the connection; the HTTP timeout below
+// must exceed this or we'd cancel every idle poll.
+const POLL_SECONDS = 50;
+const POLL_HTTP_TIMEOUT_MS = (POLL_SECONDS + 10) * 1000;
+const SEND_TIMEOUT_MS = 15_000;
+const BACKOFF_MS = 3000;
+
+// Shape of the bits of a Telegram Update we read.
+interface TgUpdate {
+  update_id: number;
+  message?: {
+    text?: string;
+    chat?: { id?: number | string };
+    from?: { id?: number | string; username?: string; first_name?: string };
+  };
+}
+
+// Pure mapping Update → normalized InboundMessage (null for non-text / malformed
+// updates). Extracted so it's unit-testable without the polling loop.
+export function messageFromUpdate(upd: TgUpdate): InboundMessage | null {
+  const msg = upd.message;
+  if (!msg || typeof msg.text !== "string") return null;
+  const chatId = msg.chat?.id;
+  if (chatId === undefined || chatId === null) return null;
+  const from = msg.from;
+  return {
+    chatId: String(chatId),
+    userId: String(from?.id ?? chatId),
+    userName: from?.username || from?.first_name,
+    text: msg.text,
+  };
+}
+
+export interface TelegramOptions {
+  botToken: string;
+  fetchImpl?: typeof fetch;
+  onLog?: (msg: string) => void;
+}
+
+export class TelegramAdapter implements ChannelAdapter {
+  readonly name = "telegram";
+  private readonly token: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly onLog?: (msg: string) => void;
+  private offset = 0; // next update_id to fetch from
+  private running = false;
+  private poll?: AbortController;
+
+  constructor(opts: TelegramOptions) {
+    this.token = opts.botToken;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.onLog = opts.onLog;
+  }
+
+  async start(onMessage: (m: InboundMessage) => void): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+    void this.loop(onMessage);
+  }
+
+  stop(): void {
+    this.running = false;
+    this.poll?.abort();
+  }
+
+  async sendText(chatId: string, text: string): Promise<void> {
+    if (!text) return;
+    await this.call("sendMessage", { chat_id: chatId, text }, SEND_TIMEOUT_MS);
+  }
+
+  sendTyping(chatId: string): void {
+    // Best-effort; failures are cosmetic.
+    void this.call("sendChatAction", { chat_id: chatId, action: "typing" }, 10_000).catch(() => {});
+  }
+
+  private log(msg: string): void {
+    this.onLog?.(`telegram: ${msg}`);
+  }
+
+  private async loop(onMessage: (m: InboundMessage) => void): Promise<void> {
+    while (this.running) {
+      this.poll = new AbortController();
+      try {
+        const res = await this.call(
+          "getUpdates",
+          { timeout: POLL_SECONDS, offset: this.offset, allowed_updates: ["message"] },
+          POLL_HTTP_TIMEOUT_MS,
+          this.poll.signal,
+        );
+        const data = (await res.json()) as { ok?: boolean; result?: TgUpdate[]; description?: string };
+        if (!data.ok) {
+          this.log(`getUpdates not ok: ${data.description ?? "unknown"}`);
+          await this.sleep(BACKOFF_MS);
+          continue;
+        }
+        for (const upd of data.result ?? []) {
+          this.offset = Math.max(this.offset, upd.update_id + 1);
+          const m = messageFromUpdate(upd);
+          if (m) onMessage(m);
+        }
+      } catch (e) {
+        if (!this.running) break; // stop() aborted the poll — expected
+        this.log(`poll error: ${e instanceof Error ? e.message : String(e)} — retrying`);
+        await this.sleep(BACKOFF_MS);
+      }
+    }
+  }
+
+  private async call(
+    method: string,
+    body: Record<string, unknown>,
+    timeoutMs: number,
+    extraSignal?: AbortSignal,
+  ): Promise<Response> {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = extraSignal ? AbortSignal.any([extraSignal, timeout]) : timeout;
+    return this.fetchImpl(`${API}/bot${this.token}/${method}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal,
+    });
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((r) => setTimeout(r, ms));
+  }
+}

package/src/channels/types.ts

@@ -0,0 +1,36 @@
+// Messaging-channel plumbing — the inbound/conversational counterpart to the relay.
+//
+// The relay (src/remote/*) lets the Privateer app drive this terminal. A messaging
+// channel (Telegram/Slack/Discord/WhatsApp) is the SAME idea with a different
+// transport: a user's message becomes a prompt, the agent's reply goes back to the
+// channel. `ChannelAdapter` is the one platform-specific seam; everything above it
+// (allowlist, per-chat serialization, redaction, chunking) lives in MessagingBridge
+// and is shared across every platform.
+
+// A normalized inbound message from any platform. `chatId` scopes the conversation
+// (so each thread keeps its own agent session); `userId` is who sent it (allowlist
+// key). Both are strings so platform-native numeric ids don't leak type differences
+// upward.
+export interface InboundMessage {
+  chatId: string;
+  userId: string;
+  userName?: string;
+  text: string;
+}
+
+// The per-platform transport. Implementations own the connection (long-poll,
+// gateway socket, or inbound webhook) and the wire format; they surface normalized
+// messages and accept plain text back. Keep them DUMB: no allowlist, no redaction,
+// no chunking — the bridge does all of that so it's written once and tested once.
+export interface ChannelAdapter {
+  readonly name: string;
+  // Begin receiving. Call `onMessage` for every inbound user message.
+  start(onMessage: (m: InboundMessage) => void): Promise<void>;
+  // Send a reply to a conversation. The bridge guarantees `text` is already
+  // redacted and within the platform's per-message length cap.
+  sendText(chatId: string, text: string): Promise<void>;
+  // Optional "the agent is working" affordance (typing indicator). Best-effort.
+  sendTyping?(chatId: string): void;
+  // Stop receiving and release the connection.
+  stop(): void;
+}

package/src/channels/whatsapp.ts

@@ -0,0 +1,178 @@
+// WhatsApp channel adapter — the official Meta Cloud API. Unlike the socket/
+// long-poll adapters, Cloud API delivers inbound messages by POSTing to a webhook,
+// so this adapter is the INBOUND-WEBHOOK shape: start() runs a small HTTP listener
+// (Node's built-in `http`, zero new deps) and sends via the Graph API over fetch.
+//
+// TRADEOFF: a webhook needs a PUBLIC HTTPS URL for Meta to reach — so unlike the
+// others this can't run purely behind NAT. Expose the port with a tunnel
+// (cloudflared / ngrok) or host it, and register that URL + the verify token in the
+// Meta app's webhook config. This is inherent to the Cloud API, not the adapter.
+//
+// Meta app setup (one-time):
+//   - WhatsApp product → note the phone number id → `phoneNumberId`, and a
+//     (system-user) access token → `accessToken`.
+//   - Webhooks → callback URL = https://<your-tunnel>/webhook, verify token =
+//     whatever you set as `verifyToken`; subscribe to the `messages` field.
+//   - Optional but recommended: set `appSecret` to verify Meta's X-Hub-Signature-256.
+//
+// Everything above the adapter (allowlist, serialization, redaction, chunking) is
+// MessagingBridge, reused verbatim.
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { ChannelAdapter, InboundMessage } from "./types.ts";
+
+const GRAPH = "https://graph.facebook.com/v21.0";
+const SEND_TIMEOUT_MS = 15_000;
+
+interface WaWebhookBody {
+  entry?: Array<{
+    changes?: Array<{
+      value?: {
+        // Inbound user messages. (Delivery/read receipts arrive under `statuses`,
+        // which we deliberately ignore.)
+        messages?: Array<{ from?: string; type?: string; text?: { body?: string } }>;
+      };
+    }>;
+  }>;
+}
+
+// Pure mapping: a webhook POST body → the text messages it carries. A single POST
+// can batch several. Non-text messages and status callbacks yield nothing.
+// Extracted so it's unit-testable without an HTTP server.
+export function messagesFromWebhook(body: WaWebhookBody): InboundMessage[] {
+  const out: InboundMessage[] = [];
+  for (const entry of body.entry ?? []) {
+    for (const change of entry.changes ?? []) {
+      for (const msg of change.value?.messages ?? []) {
+        if (msg.type !== "text") continue;
+        const text = msg.text?.body;
+        if (!msg.from || typeof text !== "string") continue;
+        // The sender's phone number is both the conversation and the user id.
+        out.push({ chatId: msg.from, userId: msg.from, text });
+      }
+    }
+  }
+  return out;
+}
+
+export interface WhatsAppOptions {
+  phoneNumberId: string;
+  accessToken: string;
+  verifyToken: string;
+  appSecret?: string; // enables X-Hub-Signature-256 verification when set
+  port?: number;
+  path?: string;
+  fetchImpl?: typeof fetch;
+  onLog?: (msg: string) => void;
+}
+
+export class WhatsAppAdapter implements ChannelAdapter {
+  readonly name = "whatsapp";
+  private readonly opts: WhatsAppOptions;
+  private readonly fetchImpl: typeof fetch;
+  private readonly onLog?: (msg: string) => void;
+  private readonly port: number;
+  private readonly path: string;
+  private server?: Server;
+  private onMessage?: (m: InboundMessage) => void;
+
+  constructor(opts: WhatsAppOptions) {
+    this.opts = opts;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.onLog = opts.onLog;
+    this.port = opts.port ?? 8787;
+    this.path = opts.path ?? "/webhook";
+  }
+
+  async start(onMessage: (m: InboundMessage) => void): Promise<void> {
+    this.onMessage = onMessage;
+    this.server = createServer((req, res) => this.handle(req, res));
+    await new Promise<void>((resolve) => this.server!.listen(this.port, () => resolve()));
+    this.log(`webhook listening on :${this.port}${this.path} — expose it publicly for Meta to reach.`);
+  }
+
+  stop(): void {
+    this.server?.close();
+    this.server = undefined;
+  }
+
+  async sendText(chatId: string, text: string): Promise<void> {
+    if (!text) return;
+    const res = await this.fetchImpl(`${GRAPH}/${this.opts.phoneNumberId}/messages`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${this.opts.accessToken}`, "content-type": "application/json" },
+      body: JSON.stringify({ messaging_product: "whatsapp", to: chatId, type: "text", text: { body: text } }),
+      signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+    });
+    if (!res.ok) this.log(`send failed: HTTP ${res.status}`);
+  }
+
+  private log(msg: string): void {
+    this.onLog?.(`whatsapp: ${msg}`);
+  }
+
+  private handle(req: IncomingMessage, res: ServerResponse): void {
+    const url = new URL(req.url ?? "/", `http://localhost:${this.port}`);
+    if (url.pathname !== this.path) {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+
+    // GET: Meta's one-time verification challenge.
+    if (req.method === "GET") {
+      const mode = url.searchParams.get("hub.mode");
+      const token = url.searchParams.get("hub.verify_token");
+      const challenge = url.searchParams.get("hub.challenge") ?? "";
+      if (mode === "subscribe" && token === this.opts.verifyToken) {
+        res.writeHead(200, { "content-type": "text/plain" });
+        res.end(challenge);
+      } else {
+        res.writeHead(403);
+        res.end();
+      }
+      return;
+    }
+
+    // POST: an inbound message batch.
+    if (req.method === "POST") {
+      let raw = "";
+      req.on("data", (c) => (raw += c));
+      req.on("end", () => {
+        if (!this.verifySignature(req, raw)) {
+          this.log("rejected webhook: bad or missing X-Hub-Signature-256");
+          res.writeHead(401);
+          res.end();
+          return;
+        }
+        // Ack fast — Meta retries the delivery on any non-200.
+        res.writeHead(200);
+        res.end();
+        let body: WaWebhookBody;
+        try {
+          body = JSON.parse(raw);
+        } catch {
+          return;
+        }
+        for (const m of messagesFromWebhook(body)) this.onMessage?.(m);
+      });
+      return;
+    }
+
+    res.writeHead(405);
+    res.end();
+  }
+
+  // Verify Meta's HMAC signature when an app secret is configured. Absent → skipped
+  // (documented tradeoff); the allowlist still gates who may drive the agent.
+  private verifySignature(req: IncomingMessage, raw: string): boolean {
+    if (!this.opts.appSecret) return true;
+    const header = req.headers["x-hub-signature-256"];
+    if (typeof header !== "string") return false;
+    const expected = "sha256=" + createHmac("sha256", this.opts.appSecret).update(raw).digest("hex");
+    const a = Buffer.from(header);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+  }
+}