chainlesschain 0.162.158 → 0.162.160

package/src/lib/channels/channel-manager.js

@@ -0,0 +1,126 @@
+/**
+ * Inbound channels — external events entering a running agent session
+ * (gap-2026-07-11 P0#5; Claude-Code "channels" parity, self-hosted).
+ *
+ * `cc agent --channels webhook,telegram` starts channel listeners whose
+ * events become user turns in the interactive session (queued behind any
+ * in-flight turn by the REPL's pending-line queue). Every channel enforces a
+ * trust boundary: webhook = bearer token + loopback-only by default;
+ * telegram = explicit chat-id allowlist (deny-all when unset).
+ *
+ * Outbound replies reuse the existing notifier stack (`notify` agent tool /
+ * NotificationManager) — the inbound event's metadata tells the model which
+ * channel and sender to address.
+ */
+
+import { logger } from "../logger.js";
+
+export const CHANNEL_KINDS = ["webhook", "telegram"];
+
+/**
+ * Parse `--channels` input: "webhook,telegram", "webhook:18901", or an array.
+ * @returns {Array<{kind:string, arg:string|null}>}
+ */
+export function parseChannelSpecs(input) {
+  const items = Array.isArray(input)
+    ? input
+    : String(input || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+  return items.map((item) => {
+    const idx = item.indexOf(":");
+    const kind = (idx === -1 ? item : item.slice(0, idx)).toLowerCase();
+    const arg = idx === -1 ? null : item.slice(idx + 1);
+    if (!CHANNEL_KINDS.includes(kind)) {
+      throw new Error(
+        `Unknown channel "${kind}" — supported: ${CHANNEL_KINDS.join(", ")}`,
+      );
+    }
+    return { kind, arg };
+  });
+}
+
+/**
+ * Render a channel event as the user-turn text. The channel/sender prefix
+ * keeps provenance visible to the model AND guarantees the line can never be
+ * mistaken for a REPL slash command or `!` shell escape, no matter what the
+ * external sender wrote.
+ */
+export function formatChannelEvent(event) {
+  const channel = event?.channel || "channel";
+  const sender = event?.sender ? ` from ${event.sender}` : "";
+  const text = String(event?.text ?? "").trim();
+  return `[channel:${channel}${sender}] ${text}`;
+}
+
+/**
+ * Start every requested channel. Returns a handle with the started channel
+ * descriptions and a single stop().
+ *
+ * @param {string|string[]} specsInput --channels value
+ * @param {object} opts
+ * @param {(event) => void} opts.onEvent   called for each inbound event
+ * @param {object} [opts.config]           loadConfig().channels subtree
+ * @param {object} [opts.deps]             channel starters (tests inject)
+ */
+export async function startChannels(specsInput, opts = {}) {
+  const specs = parseChannelSpecs(specsInput);
+  if (specs.length === 0) {
+    throw new Error("--channels given but no channel names parsed");
+  }
+  const config = opts.config || {};
+  const log = opts.log || ((msg) => logger.info(msg));
+  const deps = opts.deps || {};
+
+  const started = [];
+  const stopAll = () => {
+    for (const c of started) {
+      try {
+        c.stop?.();
+      } catch {
+        /* best-effort */
+      }
+    }
+  };
+
+  try {
+    for (const spec of specs) {
+      if (spec.kind === "webhook") {
+        const { startWebhookChannel } =
+          deps.webhook || (await import("./webhook-channel.js"));
+        const cfg = config.webhook || {};
+        const handle = await (
+          deps.webhook?.startWebhookChannel || startWebhookChannel
+        )({
+          ...cfg,
+          port: spec.arg ? Number(spec.arg) : cfg.port,
+          onEvent: opts.onEvent,
+          log,
+        });
+        started.push({ kind: "webhook", describe: handle.describe, ...handle });
+      } else if (spec.kind === "telegram") {
+        const { startTelegramChannel } =
+          deps.telegram || (await import("./telegram-channel.js"));
+        const cfg = config.telegram || {};
+        const handle = await (
+          deps.telegram?.startTelegramChannel || startTelegramChannel
+        )({
+          ...cfg,
+          onEvent: opts.onEvent,
+          log,
+        });
+        started.push({
+          kind: "telegram",
+          describe: handle.describe,
+          ...handle,
+        });
+      }
+    }
+  } catch (err) {
+    stopAll(); // never leave half the channels listening after a failure
+    throw err;
+  }
+
+  return { channels: started, stop: stopAll };
+}

package/src/lib/channels/telegram-channel.js

@@ -0,0 +1,112 @@
+/**
+ * Telegram inbound channel — long-polls the Bot API (`getUpdates`) so no
+ * public endpoint is needed, and turns allowed chats' messages into session
+ * events.
+ *
+ * Trust boundary: `allowFrom` (array of chat ids) is REQUIRED — an inbound
+ * channel with no allowlist would let anyone who finds the bot drive the
+ * agent, so an empty/missing allowlist denies every update (fail closed).
+ *
+ * Replies: `handle.reply(event, text)` posts a sendMessage back to the
+ * event's chat. fetch is injectable for tests.
+ */
+
+const POLL_TIMEOUT_S = 25;
+const ERROR_BACKOFF_MS = 5000;
+
+export async function startTelegramChannel(options = {}) {
+  const {
+    botToken = process.env.TELEGRAM_BOT_TOKEN,
+    allowFrom,
+    onEvent,
+    log = () => {},
+    fetchImpl = globalThis.fetch,
+    pollTimeoutS = POLL_TIMEOUT_S,
+    // Real macrotask pause between polls. The server-side long-poll dominates
+    // in production; this exists so a fast-resolving fetch (tests, HTTP-level
+    // failures) can never turn the loop into a microtask chain that starves
+    // the event loop (timers, stop()) entirely.
+    pollPauseMs = 50,
+  } = options;
+
+  if (!botToken) {
+    throw new Error(
+      "telegram channel needs a bot token (channels.telegram.botToken or TELEGRAM_BOT_TOKEN)",
+    );
+  }
+  const allowed = new Set((allowFrom || []).map((id) => String(id)));
+  if (allowed.size === 0) {
+    throw new Error(
+      "telegram channel needs channels.telegram.allowFrom (chat-id allowlist) — refusing to listen to everyone",
+    );
+  }
+
+  const api = (method) => `https://api.telegram.org/bot${botToken}/${method}`;
+  let stopped = false;
+  let offset = 0;
+
+  async function poll() {
+    while (!stopped) {
+      try {
+        const res = await fetchImpl(api("getUpdates"), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ timeout: pollTimeoutS, offset }),
+        });
+        const data = await res.json();
+        if (!data?.ok || !Array.isArray(data.result)) {
+          throw new Error(data?.description || `getUpdates HTTP ${res.status}`);
+        }
+        for (const update of data.result) {
+          offset = Math.max(offset, Number(update.update_id) + 1);
+          const msg = update.message || update.edited_message;
+          const chatId = msg?.chat?.id;
+          const text = typeof msg?.text === "string" ? msg.text.trim() : "";
+          if (!chatId || !text) continue;
+          if (!allowed.has(String(chatId))) continue; // fail closed
+          try {
+            onEvent?.({
+              channel: "telegram",
+              sender: String(chatId),
+              text,
+              meta: { updateId: update.update_id },
+            });
+          } catch {
+            /* downstream owns its failures */
+          }
+        }
+      } catch (err) {
+        if (stopped) return;
+        log(`channel telegram poll error: ${err.message} — backing off`);
+        await new Promise((r) => setTimeout(r, ERROR_BACKOFF_MS));
+      }
+      if (!stopped) {
+        await new Promise((r) => setTimeout(r, pollPauseMs));
+      }
+    }
+  }
+  const pollPromise = poll();
+
+  log(`channel telegram polling (allowlist: ${[...allowed].join(", ")})`);
+
+  return {
+    kind: "telegram",
+    describe: `telegram (${allowed.size} allowed chat${allowed.size === 1 ? "" : "s"})`,
+    async reply(event, text) {
+      const res = await fetchImpl(api("sendMessage"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ chat_id: event.sender, text }),
+      });
+      const data = await res.json();
+      if (!data?.ok) {
+        throw new Error(data?.description || `sendMessage HTTP ${res.status}`);
+      }
+      return true;
+    },
+    stop: () => {
+      stopped = true;
+      return pollPromise.catch(() => {});
+    },
+  };
+}

package/src/lib/channels/webhook-channel.js

@@ -0,0 +1,140 @@
+/**
+ * Webhook inbound channel — a tiny loopback HTTP listener that turns
+ * authenticated POSTs into session events.
+ *
+ *   POST /v1/event
+ *   Authorization: Bearer <token>
+ *   { "text": "deploy finished", "sender": "ci", "meta": {...} }
+ *
+ * Trust boundary:
+ * - bearer token REQUIRED on every request; without a configured token a
+ *   random one is generated and printed once at startup (pairing secret).
+ * - binds 127.0.0.1 unless `allowExternal: true` is explicitly configured
+ *   (same LAN/loopback posture as remote-control direct pairing).
+ * - optional `allowlist` of sender ids — configured ⇒ only those senders.
+ * - body capped at 64 KB; JSON only.
+ */
+
+import { createServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+
+const MAX_BODY_BYTES = 64 * 1024;
+
+function tokenMatches(expected, got) {
+  const a = Buffer.from(String(expected));
+  const b = Buffer.from(String(got || ""));
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export async function startWebhookChannel(options = {}) {
+  const {
+    port = 18901,
+    host = "127.0.0.1",
+    allowExternal = false,
+    allowlist,
+    onEvent,
+    log = () => {},
+  } = options;
+
+  const isLoopback =
+    host === "127.0.0.1" || host === "::1" || host === "localhost";
+  if (!isLoopback && allowExternal !== true) {
+    throw new Error(
+      `webhook channel refuses to bind non-loopback host "${host}" without channels.webhook.allowExternal=true`,
+    );
+  }
+
+  const token = options.token || randomBytes(24).toString("base64url");
+  const generated = !options.token;
+
+  const server = createServer((req, res) => {
+    const respond = (status, body) => {
+      res.writeHead(status, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(body));
+    };
+
+    if (req.method !== "POST" || req.url !== "/v1/event") {
+      return respond(404, { error: "not found" });
+    }
+    const auth = String(req.headers.authorization || "");
+    const got = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+    if (!tokenMatches(token, got)) {
+      return respond(401, { error: "unauthorized" });
+    }
+
+    let size = 0;
+    const chunks = [];
+    let aborted = false;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        aborted = true;
+        respond(413, { error: "body too large" });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (aborted) return;
+      let payload;
+      try {
+        payload = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+      } catch {
+        return respond(400, { error: "invalid JSON" });
+      }
+      const text = typeof payload?.text === "string" ? payload.text.trim() : "";
+      if (!text) return respond(400, { error: "missing text" });
+      const sender =
+        typeof payload.sender === "string" ? payload.sender : "webhook";
+      if (Array.isArray(allowlist) && allowlist.length > 0) {
+        if (!allowlist.includes(sender)) {
+          return respond(403, { error: "sender not in allowlist" });
+        }
+      }
+      try {
+        onEvent?.({
+          channel: "webhook",
+          sender,
+          text,
+          meta:
+            payload.meta && typeof payload.meta === "object"
+              ? payload.meta
+              : undefined,
+        });
+      } catch {
+        /* the session queue owns downstream failures */
+      }
+      respond(202, { ok: true });
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve);
+  });
+  server.unref?.();
+
+  const actualPort = server.address()?.port ?? port;
+  const url = `http://${host}:${actualPort}/v1/event`;
+  log(
+    `channel webhook listening on ${url}` +
+      (generated ? ` (generated token: ${token})` : ""),
+  );
+
+  return {
+    kind: "webhook",
+    url,
+    port: actualPort,
+    token,
+    describe: `webhook ${url}`,
+    stop: () =>
+      new Promise((resolve) => {
+        try {
+          server.close(() => resolve());
+        } catch {
+          resolve();
+        }
+      }),
+  };
+}