privateer-agent 0.3.6 → 0.4.0

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);
+  }
+}