viber-channel 0.5.3 → 0.7.0

package/lib/control_stream.ts

@@ -0,0 +1,351 @@
+/**
+ * control_stream — subscribe to an instance-scoped server→agent control stream
+ * (#280 step-01/03).
+ *
+ * The control stream (`GET /api/instances/<id>/events`, authenticated by the
+ * instance_token) is how the server pushes commands to an agent BEFORE it is in
+ * any conversation. Today it carries:
+ *   - `connected` — open marker
+ *   - `ping`      — keepalive
+ *   - `stop`      — the instance was revoked; the agent should exit
+ *   - `join`      — admit this agent to a conversation; the payload IS a
+ *                   ConversationMintResponse (conversation_id, conversation_token,
+ *                   ws_url, expires_at), so it feeds the conversation SSE loop
+ *                   directly with no copy-pasted ids or tokens (the step-03 payoff).
+ *
+ * This module is intentionally side-effect-free and runtime-agnostic (no Codex /
+ * Claude specifics) so both bridges can consume it and it can be unit-tested with
+ * a mock fetch.
+ */
+import { cfAccessHeaders } from "./cfAccess.js";
+import type { ConversationMintResponse } from "./conversation.js";
+
+/** One parsed Server-Sent Event from the control stream. */
+export interface ControlEvent {
+  event: string;
+  data: string;
+}
+
+/** Build the instance control-stream SSE URL. */
+export function buildControlStreamUrl(baseUrl: string, instanceId: string): string {
+  return `${baseUrl}/api/instances/${instanceId}/events`;
+}
+
+/**
+ * POST /api/instances/:id/heartbeat — instance control-stream liveness (#311).
+ *
+ * The agent beats on a fixed interval so the server's #311 sweeper never purges a
+ * live-but-idle agent: a server→client SSE keepalive can't prove this process is
+ * still alive behind the Cloudflare tunnel, but this beat can. Best-effort —
+ * `true` on 2xx, `false` on any non-2xx / network error. Bounded by a per-POST
+ * timeout so a hung tunnel socket can't stack beats (mirrors #298).
+ */
+export async function sendInstanceHeartbeat(
+  baseUrl: string,
+  instanceId: string,
+  instanceToken: string,
+  timeoutMs = 20_000,
+  fetchImpl: typeof fetch = fetch,
+): Promise<boolean> {
+  try {
+    const resp = await fetchImpl(`${baseUrl}/api/instances/${instanceId}/heartbeat`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${instanceToken}`,
+        "Content-Type": "application/json",
+        ...cfAccessHeaders(),
+      },
+      body: "{}",
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
+export interface ControlStreamOptions {
+  baseUrl: string;
+  instanceId: string;
+  instanceToken: string;
+  signal?: AbortSignal;
+  /** Injectable for tests; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Thrown when the control stream is rejected with 401 — the instance_token is
+ * revoked or invalid, so the agent must re-register (a fresh instance_id).
+ */
+export class ControlStreamAuthError extends Error {
+  constructor() {
+    super("control stream unauthorized (instance token revoked or invalid)");
+    this.name = "ControlStreamAuthError";
+  }
+}
+
+/**
+ * Async generator that connects to the instance control stream and yields each
+ * parsed `{ event, data }`. One connection attempt — the caller decides whether
+ * to reconnect (the server keeps the stream open with `ping` keepalives). Throws
+ * `ControlStreamAuthError` on 401; the AbortSignal ends it cleanly.
+ */
+export async function* subscribeControlStream(
+  opts: ControlStreamOptions,
+): AsyncGenerator<ControlEvent> {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const url = buildControlStreamUrl(opts.baseUrl, opts.instanceId);
+
+  const resp = await doFetch(url, {
+    headers: {
+      Authorization: `Bearer ${opts.instanceToken}`,
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache",
+      ...cfAccessHeaders(),
+    },
+    signal: opts.signal,
+  });
+  if (resp.status === 401) throw new ControlStreamAuthError();
+  if (!resp.ok || !resp.body) {
+    throw new Error(`control stream connection failed: HTTP ${resp.status}`);
+  }
+
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      // Normalise CRLF → LF: the SSE spec allows \r\n line/record separators and
+      // some servers (incl. Cloudflare) emit them; without this the `\n\n` split
+      // never matches and a trailing `\r` corrupts every field value.
+      buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+      while (true) {
+        const eventEnd = buffer.indexOf("\n\n");
+        if (eventEnd === -1) break;
+        const block = buffer.slice(0, eventEnd);
+        buffer = buffer.slice(eventEnd + 2);
+
+        let event = "";
+        let data = "";
+        for (const line of block.split("\n")) {
+          if (line.startsWith(":")) continue; // comment line (keepalive)
+          if (line.startsWith("event: ")) event = line.slice(7);
+          else if (line.startsWith("data: ")) data = line.slice(6);
+        }
+        if (event) yield { event, data };
+      }
+    }
+  } finally {
+    // Release the reader (and cancel the body) so an early `break`/`return` by
+    // the consumer — e.g. waitForJoin resolving on the first join — or an abort
+    // doesn't leak the underlying connection until GC.
+    try {
+      await reader.cancel();
+    } catch {
+      /* already closed / aborted */
+    }
+  }
+}
+
+/** Raised when the control stream is signalled `stop` (instance revoked). */
+export class ControlStreamStopped extends Error {
+  constructor() {
+    super("control stream received stop (instance revoked)");
+    this.name = "ControlStreamStopped";
+  }
+}
+
+/**
+ * Parse a `join` event's data into a validated `ConversationMintResponse`, or
+ * null if it is malformed / missing fields (the caller skips it and waits for
+ * the next). Shared by waitForJoin and runPersistentControlStream.
+ */
+function parseJoinPayload(
+  data: string,
+  log: (msg: string) => void,
+): ConversationMintResponse | null {
+  let payload: Partial<ConversationMintResponse>;
+  try {
+    payload = JSON.parse(data) as Partial<ConversationMintResponse>;
+  } catch {
+    log("[control-stream] ignored malformed join payload\n");
+    return null;
+  }
+  if (
+    typeof payload.conversation_id === "string" &&
+    typeof payload.conversation_token === "string" &&
+    typeof payload.ws_url === "string" &&
+    typeof payload.expires_at === "number"
+  ) {
+    return payload as ConversationMintResponse;
+  }
+  log("[control-stream] ignored join payload with missing fields\n");
+  return null;
+}
+
+/**
+ * Consume the control stream until the first `join` event and return its payload
+ * as a `ConversationMintResponse` — ready to feed the conversation SSE loop. A
+ * `stop` event before any join throws `ControlStreamStopped`. `connected`/`ping`
+ * are ignored (keepalive). Malformed `join` data is skipped (waits for the next).
+ *
+ * NOTE: this CLOSES the stream on the first join (the generator returns). For the
+ * control-plane DM model — where presence must survive after joining — use
+ * runPersistentControlStream instead, which keeps the stream open for life.
+ */
+export async function waitForJoin(
+  opts: ControlStreamOptions,
+  log: (msg: string) => void = () => {},
+): Promise<ConversationMintResponse> {
+  for await (const ev of subscribeControlStream(opts)) {
+    if (ev.event === "stop") throw new ControlStreamStopped();
+    if (ev.event !== "join") continue; // connected / ping / unknown → ignore
+    const minted = parseJoinPayload(ev.data, log);
+    if (minted) return minted;
+  }
+  // Stream ended without a join — the caller reconnects.
+  throw new Error("control stream ended before a join event");
+}
+
+/** Resolve after `ms`, or early when `signal` aborts. */
+function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export interface PersistentControlStreamHandlers {
+  /** Called for EACH pushed join (the conversation to admit this agent into). */
+  onJoin?: (minted: ConversationMintResponse) => void;
+  /**
+   * Called once when the stream terminates for a NON-transient reason:
+   *   "stopped"      — a `stop` event arrived (the instance was revoked)
+   *   "unauthorized" — the control stream returned 401 (token revoked/invalid)
+   * The agent should shut down. NOT called on transient drops (those reconnect).
+   */
+  onStop?: (reason: "stopped" | "unauthorized") => void;
+  /**
+   * Called on a `beat_now` event (#311): the server is actively probing this
+   * agent's liveness — respond with an IMMEDIATE instance heartbeat so a live
+   * agent is confirmed within seconds (and a dead one, which never gets here, is
+   * force-offlined at the probe deadline).
+   */
+  onBeatNow?: () => void;
+  log?: (msg: string) => void;
+  /** Backoff before reconnecting after a drop / clean end. Default 2000ms. */
+  reconnectDelayMs?: number;
+}
+
+export interface PersistentControlStream {
+  /**
+   * Resolves with the FIRST pushed join — the caller starts the conversation
+   * from it. Rejects with ControlStreamStopped / ControlStreamAuthError if the
+   * stream ends (revoke / 401) before any join, or a generic Error on abort.
+   */
+  firstJoin: Promise<ConversationMintResponse>;
+  /** Resolves when the run loop exits (abort, stop, or auth error). */
+  done: Promise<void>;
+}
+
+/**
+ * Run the instance control stream for the agent's WHOLE lifetime (hub-and-spoke:
+ * ONE persistent server→agent link). Unlike waitForJoin — which returns on the
+ * first join and CLOSES the stream — this keeps the stream open AFTER the first
+ * join so server-side presence (#280 step-02) keeps seeing the agent online and
+ * re-invitable (step-20, Codex P1-3). Reconnects with backoff on transient drops;
+ * a `stop` (revoke) or 401 ends the loop via onStop. The AbortSignal ends it.
+ */
+export function runPersistentControlStream(
+  opts: ControlStreamOptions,
+  handlers: PersistentControlStreamHandlers = {},
+): PersistentControlStream {
+  const log = handlers.log ?? (() => {});
+  const delayMs = handlers.reconnectDelayMs ?? 2000;
+  const signal = opts.signal;
+
+  let firstSettled = false;
+  let resolveFirst!: (m: ConversationMintResponse) => void;
+  let rejectFirst!: (err: unknown) => void;
+  const firstJoin = new Promise<ConversationMintResponse>((res, rej) => {
+    resolveFirst = res;
+    rejectFirst = rej;
+  });
+  // Mark settled synchronously so the rejection on abort never fires after a
+  // resolve (and vice-versa) — and so an unobserved firstJoin still rejects once.
+  const settleFirstResolve = (m: ConversationMintResponse) => {
+    if (firstSettled) return;
+    firstSettled = true;
+    resolveFirst(m);
+  };
+  const settleFirstReject = (err: unknown) => {
+    if (firstSettled) return;
+    firstSettled = true;
+    rejectFirst(err);
+  };
+
+  const done = (async () => {
+    try {
+      while (true) {
+        if (signal?.aborted) {
+          settleFirstReject(new Error("control stream aborted before join"));
+          return;
+        }
+        try {
+          for await (const ev of subscribeControlStream(opts)) {
+            if (ev.event === "stop") {
+              settleFirstReject(new ControlStreamStopped());
+              handlers.onStop?.("stopped");
+              return;
+            }
+            if (ev.event === "beat_now") {
+              handlers.onBeatNow?.();
+              continue;
+            }
+            if (ev.event !== "join") continue; // connected / ping / unknown
+            const minted = parseJoinPayload(ev.data, log);
+            if (!minted) continue;
+            handlers.onJoin?.(minted);
+            settleFirstResolve(minted);
+          }
+          // Clean end (server closed the SSE) → reconnect after backoff.
+        } catch (err) {
+          if (err instanceof ControlStreamAuthError) {
+            settleFirstReject(err);
+            handlers.onStop?.("unauthorized");
+            return;
+          }
+          if (signal?.aborted) {
+            settleFirstReject(new Error("control stream aborted before join"));
+            return;
+          }
+          log(
+            `[control-stream] ${err instanceof Error ? err.message : String(err)}, reconnecting...\n`,
+          );
+        }
+        if (signal?.aborted) {
+          settleFirstReject(new Error("control stream aborted before join"));
+          return;
+        }
+        await abortableDelay(delayMs, signal);
+      }
+    } finally {
+      // Defensive: never leave an awaiter of firstJoin hanging if the loop exits.
+      settleFirstReject(new Error("control stream ended before a join event"));
+    }
+  })();
+
+  return { firstJoin, done };
+}

package/lib/conversation.ts

@@ -26,10 +26,24 @@ export class ReattachFailedError extends Error {
   }
 }
 
+/**
+ * Non-2xx from the conversation mint/join endpoint. `.status` lets the caller
+ * react to a 401 (the instance_token was revoked → re-acquire a new instance
+ * and retry, #269) distinctly from other failures.
+ */
+export class ConversationMintError extends Error {
+  status: number;
+  constructor(status: number, detail: string) {
+    super(`Failed to mint conversation token (HTTP ${status}): ${detail}`);
+    this.name = "ConversationMintError";
+    this.status = status;
+  }
+}
+
 export async function mintConversation(
   baseUrl: string,
   projectId: number,
-  projectToken: string,
+  instanceToken: string,
   fingerprint: string,
   label: string,
   /**
@@ -55,7 +69,7 @@ export async function mintConversation(
   const resp = await fetch(`${baseUrl}/api/projects/${projectId}/conversations`, {
     method: "POST",
     headers: {
-      Authorization: `Bearer ${projectToken}`,
+      Authorization: `Bearer ${instanceToken}`,
       "X-Client-Fingerprint": fingerprint,
       "Content-Type": "application/json",
       ...cfAccessHeaders(),
@@ -64,7 +78,7 @@ export async function mintConversation(
   });
   if (!resp.ok) {
     const detail = await resp.text();
-    throw new Error(`Failed to mint conversation token (HTTP ${resp.status}): ${detail}`);
+    throw new ConversationMintError(resp.status, detail);
   }
   return (await resp.json()) as ConversationMintResponse;
 }
@@ -81,14 +95,14 @@ export async function mintConversation(
 export async function reattachConversation(
   baseUrl: string,
   projectId: number,
-  projectToken: string,
+  instanceToken: string,
   fingerprint: string,
   conversationId: string,
 ): Promise<ConversationMintResponse> {
   const resp = await fetch(`${baseUrl}/api/projects/${projectId}/conversations`, {
     method: "POST",
     headers: {
-      Authorization: `Bearer ${projectToken}`,
+      Authorization: `Bearer ${instanceToken}`,
       "X-Client-Fingerprint": fingerprint,
       "Content-Type": "application/json",
       ...cfAccessHeaders(),
@@ -237,7 +251,7 @@ export const DEFAULT_REATTACH_WINDOW_SECONDS = 3600;
  * @param sessionPath   Path returned by `sessionFilePath(baseUrl, fingerprint, sessionId, dir)`
  * @param baseUrl       Backend base URL
  * @param projectId     Project ID from auth.json
- * @param projectToken  Bearer token from auth.json
+ * @param instanceToken  Bearer token from auth.json
  * @param fingerprint   Client fingerprint from auth.json
  * @param label         Conversation label (used only when minting)
  * @param targetConversationId  Optional target for the attach-to-project flow (passed to mint)
@@ -248,7 +262,7 @@ export async function acquireConversation(
   sessionPath: string,
   baseUrl: string,
   projectId: number,
-  projectToken: string,
+  instanceToken: string,
   fingerprint: string,
   label: string,
   targetConversationId?: string | null,
@@ -265,7 +279,7 @@ export async function acquireConversation(
     if (handleAge < reattachWindowSeconds) {
       log(`[viber-channel] startup: session handle found (conv_id=${handle.conversation_id}, age=${handleAge}s < ${reattachWindowSeconds}s window), attempting reattach\n`);
       try {
-        const result = await reattachConversation(baseUrl, projectId, projectToken, fingerprint, handle.conversation_id);
+        const result = await reattachConversation(baseUrl, projectId, instanceToken, fingerprint, handle.conversation_id);
         log(`[viber-channel] startup: reattach OK, conv_id=${result.conversation_id}\n`);
         try {
           writeHandle(sessionPath, result.conversation_id);
@@ -291,7 +305,7 @@ export async function acquireConversation(
   }
 
   // Mint a new conversation
-  const result = await mintConversation(baseUrl, projectId, projectToken, fingerprint, label, targetConversationId ?? null);
+  const result = await mintConversation(baseUrl, projectId, instanceToken, fingerprint, label, targetConversationId ?? null);
   log(`[viber-channel] startup: mint OK, conv_id=${result.conversation_id}\n`);
   try {
     writeHandle(sessionPath, result.conversation_id);