pi-braid-telegram 0.0.0-stage → 0.1.4

package/src/lib/pause-control.ts

@@ -0,0 +1,425 @@
+/**
+ * Telegram inline-keyboard pause/resume control.
+ *
+ * The for a button to control the agent through Telegram
+ * ("Seems need a button for pause or whatever control this through tg").
+ * This module adds:
+ *  - an inline keyboard (reply_markup) with ⏸ Pause / ▶ Resume / 📊 Status
+ *    buttons (callback_data: "pause" | "resume" | "status");
+ *  - callback_query handling: pause → paused=true, resume → paused=false,
+ *    status → reply the current state; every tap is answered via
+ *    answerCallbackQuery and the keyboard is updated in place via
+ *    editMessageText (paused shows ▶ Resume, running shows ⏸ Pause);
+ *  - a persisted pause state file (default
+ *    `<braidDir>/telegram/pause-state.json`, atomic write-temp-rename) that
+ *    survives restarts; the pre-move `~/.pi/agent/telegram-pause-state.json`
+ *    stays readable until the first post-move write replaces it (reads prefer
+ *    the braid-root file, writes only ever land there);
+ *  - `getPauseState()` — the exported read seam for the CONSUMER (the
+ *    orchestrator decides how to honor the flag; this module never blocks the
+ *    poller or the core loop).
+ *
+ * Design: the pause flag is a signal for the consumer, not a gate here. The
+ * poller keeps polling and delivering; pause/resume/status callbacks are
+ * handled entirely within this module (answer + edit) and never a turn.
+ *
+ * Config follows the pi "settings" philosophy (packages/core braid-settings):
+ * the state-file path defaults to the fixed path above and can be overridden
+ * via `braid.telegram.pauseStateFile` in `~/.pi/agent/settings.json` — no
+ * process.env keys are introduced.
+ */
+
+import { readFile, writeFile, rename, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+import {
+  defaultPauseStateFile,
+  legacyPauseStateFile,
+  warnUnderivableRoot,
+} from "./state-paths.js";
+import type { TelegramClient, TelegramReplyMarkup } from "./telegram-client.js";
+
+export { defaultPauseStateFile, legacyPauseStateFile };
+
+// Callback actions (button callback_data)
+
+export const CALLBACK_PAUSE = "pause";
+export const CALLBACK_RESUME = "resume";
+export const CALLBACK_STATUS = "status";
+
+/** Control-message body shown while the agent is running. */
+export const CONTROL_RUNNING_TEXT =
+  "▶ Agent is running — inbound flows normally.";
+/** Control-message body shown while the agent is paused. */
+export const CONTROL_PAUSED_TEXT = "⏸ Agent is paused — inbound will be held.";
+
+export interface PauseState {
+  paused: boolean;
+  /** Epoch ms of the last pause/resume transition (0 when never changed). */
+  updatedAt: number;
+}
+
+/** settings.json (pi-native) — braid.telegram block, mirrors braid-settings.ts. */
+const SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
+
+interface BraidSettings {
+  braid?: {
+    telegram?: {
+      /** Override for the pause-state file path (default: defaultPauseStateFile()). */
+      pauseStateFile?: string;
+    };
+  };
+}
+
+/** The `braid.telegram.pauseStateFile` override, or undefined. Never throws. */
+function configuredPauseStateFile(): string | undefined {
+  try {
+    if (existsSync(SETTINGS_PATH)) {
+      const parsed = JSON.parse(
+        readFileSync(SETTINGS_PATH, "utf8"),
+      ) as BraidSettings;
+      const override = parsed?.braid?.telegram?.pauseStateFile;
+      if (typeof override === "string" && override.trim())
+        return override.trim();
+    }
+  } catch {
+    // non-fatal — fall through to the default
+  }
+  return undefined;
+}
+
+/**
+ * Write resolution: `braid.telegram.pauseStateFile` when configured, else the
+ * braid-root default. Every write goes here — the pre-move agent-dir file is
+ * read-only history. Null when no absolute root resolves: the caller refuses
+ * to persist instead of writing beside the cwd.
+ */
+export function resolvePauseStateFile(): string | null {
+  return configuredPauseStateFile() ?? defaultPauseStateFile();
+}
+
+/**
+ * Read resolution: the configured override, else the braid-root file when it
+ * exists, else the pre-move agent-dir file when that exists (so a pause set
+ * before the relocation keeps holding), else the braid-root path (a miss the
+ * caller treats as "not paused"). Null when no absolute root resolves.
+ */
+export function resolvePauseStateReadFile(): string | null {
+  const configured = configuredPauseStateFile();
+  if (configured) return configured;
+  const current = defaultPauseStateFile();
+  if (current !== null && existsSync(current)) return current;
+  const legacy = legacyPauseStateFile();
+  if (legacy !== null && existsSync(legacy)) return legacy;
+  return current;
+}
+
+/** Read the pause state; a missing/corrupt file means "not paused" (never throws). */
+export async function loadPauseState(
+  stateFile: string | null,
+): Promise<PauseState> {
+  if (stateFile === null) return { paused: false, updatedAt: 0 };
+  try {
+    const raw = await readFile(stateFile, "utf8");
+    const parsed = JSON.parse(raw) as Partial<PauseState>;
+    return {
+      paused: parsed?.paused === true,
+      updatedAt: Number(parsed?.updatedAt) || 0,
+    };
+  } catch {
+    return { paused: false, updatedAt: 0 };
+  }
+}
+
+/**
+ * Persist the pause state ATOMICALLY (write-temp-rename): the JSON is written
+ * to `<stateFile>.tmp` first, then renamed over the target, so a crash
+ * mid-write can never leave a truncated state file behind.
+ */
+export async function savePauseState(
+  stateFile: string,
+  state: PauseState,
+): Promise<void> {
+  const dir = dirname(stateFile);
+  try {
+    await mkdir(dir, { recursive: true });
+  } catch {
+    // parent may already exist; write will surface real errors
+  }
+  const tmp = `${stateFile}.tmp`;
+  await writeFile(tmp, JSON.stringify(state, null, 2) + "\n", "utf8");
+  await rename(tmp, stateFile);
+}
+
+/**
+ * Exported read seam for the CONSUMER (orchestrator): check the persisted
+ * pause flag before processing inbound. `stateFile` defaults to the resolved
+ * settings/default path. Never throws.
+ */
+export async function getPauseState(
+  stateFile: string | null = resolvePauseStateReadFile(),
+): Promise<PauseState> {
+  return loadPauseState(stateFile);
+}
+
+/**
+ * Build the control keyboard for the given state: running shows ⏸ Pause +
+ * 📊 Status; paused shows ▶ Resume + 📊 Status (the action that changes the
+ * current state is always the primary button).
+ */
+export function buildControlKeyboard(paused: boolean): TelegramReplyMarkup {
+  return {
+    inline_keyboard: [
+      [
+        paused
+          ? { text: "▶ Resume", callback_data: CALLBACK_RESUME }
+          : { text: "⏸ Pause", callback_data: CALLBACK_PAUSE },
+        { text: "📊 Status", callback_data: CALLBACK_STATUS },
+      ],
+    ],
+  };
+}
+
+export interface SendControlKeyboardResult {
+  ok: boolean;
+  messageId?: number;
+  error?: string;
+}
+
+/**
+ * Send the control message (status line + inline keyboard) to a chat. The
+ * orchestrator/agent can call this to place the control in a chat; the
+ * keyboard is then kept in sync by handlePauseCallbackQuery's edit.
+ */
+export async function sendControlKeyboard(
+  client: Pick<TelegramClient, "sendMessage">,
+  token: string,
+  chatId: number | string,
+  paused: boolean,
+): Promise<SendControlKeyboardResult> {
+  const text = paused ? CONTROL_PAUSED_TEXT : CONTROL_RUNNING_TEXT;
+  const res = await client.sendMessage(token, chatId, text, {
+    replyMarkup: buildControlKeyboard(paused),
+  });
+  return res.ok
+    ? { ok: true, messageId: res.messageId }
+    : { ok: false, error: res.error };
+}
+
+/** Comparable pause-state reader for the placement helper (see PauseControlDeps.getPauseState). */
+export type PauseStateReaderLike = () => Promise<PauseState>;
+
+export interface PlaceControlKeyboardDeps {
+  client: Pick<TelegramClient, "sendMessage">;
+  token: string;
+  /**
+   * Pause-state reader — defaults to the (unpersisted-default) getPauseState().
+   * Injectable so the consumer can reuse its gate's reader (index.ts passes the
+   * same readPauseState the poller gate uses: placement and gate always agree).
+   */
+  getPauseState?: PauseStateReaderLike;
+  log?: (
+    level: "debug" | "info" | "warn" | "error",
+    message: string,
+    ...rest: unknown[]
+  ) => void;
+}
+
+export interface PlaceControlKeyboardResult {
+  ok: boolean;
+  /**
+   * True when no usable chat id was given (owner chat not known yet — pure
+   * first-message bootstrap). NOTHING is sent; the caller retries once the
+   * first owner message captures the real chat id. Never true alongside ok:true.
+   */
+  deferred: boolean;
+  messageId?: number;
+  error?: string;
+}
+
+/**
+ * Consumer-side placement helper: ONE call sends the
+ * control keyboard to `chatId`, reflecting the CURRENT persisted pause flag —
+ * running shows ⏸ Pause, paused shows ▶ Resume. This stays delivery-neutral:
+ * NOTHING self-sends on import — the CONSUMER (index.ts) calls this at the
+ * poller-start seam. Best-effort: failures are returned in the result, never
+ * thrown. When `chatId` is empty/0 the call returns `deferred: true` without
+ * sending, so a poller that started before the owner chat was discovered
+ * (bootstrap) can place once the first owner message provides a chat id.
+ */
+export async function placeControlKeyboard(
+  chatId: number | string | undefined,
+  deps: PlaceControlKeyboardDeps,
+): Promise<PlaceControlKeyboardResult> {
+  const log = deps.log ?? (() => {});
+  if (chatId == null || chatId === "" || chatId === 0) {
+    log(
+      "debug",
+      "telegram: control keyboard deferred — owner chat not known yet",
+    );
+    return { ok: false, deferred: true };
+  }
+  const state = deps.getPauseState
+    ? await deps.getPauseState()
+    : await getPauseState();
+  const res = await sendControlKeyboard(
+    deps.client,
+    deps.token,
+    chatId,
+    state.paused,
+  );
+  if (res.ok) {
+    log(
+      "info",
+      `telegram: control keyboard placed in chat ${chatId} (${state.paused ? "paused — ▶ Resume" : "running — ⏸ Pause"}${res.messageId != null ? `, msg ${res.messageId}` : ""})`,
+    );
+  } else {
+    log(
+      "warn",
+      `telegram: control keyboard placement failed for chat ${chatId}: ${res.error ?? "unknown"}`,
+    );
+  }
+  return { ...res, deferred: false };
+}
+
+/** The callback_query shape this handler consumes (subset of Telegram's). */
+export interface PauseCallbackQuery {
+  id: string;
+  from?: { id: number; username?: string; first_name?: string };
+  /** The message the button is attached to (absent in inline mode). */
+  message?: { message_id: number; chat: { id: number; type?: string } };
+  data?: string;
+}
+
+export interface PauseControlDeps {
+  client: Pick<TelegramClient, "answerCallbackQuery" | "editMessageText">;
+  token: string;
+  /** Path to the pause-state file (persistence). Null when no absolute braid
+   *  root resolves: reads degrade to "not paused", writes are refused. */
+  stateFile: string | null;
+  log?: (
+    level: "debug" | "info" | "warn" | "error",
+    message: string,
+    ...rest: unknown[]
+  ) => void;
+}
+
+export interface PauseCallbackOutcome {
+  ok: boolean;
+  action: "pause" | "resume" | "status" | "unknown";
+  /** State AFTER the tap (persisted truth). */
+  paused: boolean;
+  /** answerCallbackQuery succeeded. */
+  answered: boolean;
+  /** editMessageText (keyboard refresh) succeeded. */
+  edited: boolean;
+  error?: string;
+}
+
+async function answerCallback(
+  deps: PauseControlDeps,
+  callbackQueryId: string,
+  text: string,
+): Promise<boolean> {
+  const res = await deps.client.answerCallbackQuery(
+    deps.token,
+    callbackQueryId,
+    { text },
+  );
+  return res.ok;
+}
+
+/**
+ * Handle one inline-keyboard tap: pause → persist paused=true, resume →
+ * persist paused=false, status → no change. Every tap is answered via
+ * answerCallbackQuery (toast with the current state) and — when the tap
+ * carries a message — the keyboard is updated in place via editMessageText so
+ * paused shows ▶ Resume and running shows ⏸ Pause. Idempotent: re-tapping the
+ * same action is a no-op on state (still answered + keyboard refreshed).
+ * Never throws; API failures are reported in the outcome.
+ */
+export async function handlePauseCallbackQuery(
+  deps: PauseControlDeps,
+  callbackQuery: PauseCallbackQuery,
+): Promise<PauseCallbackOutcome> {
+  const log = deps.log ?? (() => {});
+  const data =
+    typeof callbackQuery.data === "string" ? callbackQuery.data.trim() : "";
+  const stateFile = deps.stateFile;
+  // Reads prefer the braid-root file but fall back to the pre-move agent-dir
+  // copy while the braid-root file does not exist yet; the writes below always
+  // target `stateFile` (the braid-root default or the configured override).
+  const readFile =
+    stateFile === resolvePauseStateFile()
+      ? resolvePauseStateReadFile()
+      : stateFile;
+  const state = await loadPauseState(readFile);
+
+  // Unknown action: answer with a hint, no state change, no keyboard edit.
+  if (
+    data !== CALLBACK_PAUSE &&
+    data !== CALLBACK_RESUME &&
+    data !== CALLBACK_STATUS
+  ) {
+    const answered = await answerCallback(
+      deps,
+      callbackQuery.id,
+      `Unknown action: ${data || "(empty)"}`,
+    );
+    return {
+      ok: true,
+      action: "unknown",
+      paused: state.paused,
+      answered,
+      edited: false,
+    };
+  }
+
+  if (data === CALLBACK_PAUSE && !state.paused) {
+    if (stateFile === null) {
+      warnUnderivableRoot("pause-state write refused");
+    } else {
+      await savePauseState(stateFile, { paused: true, updatedAt: Date.now() });
+      log(
+        "info",
+        `telegram pause: agent paused via callback (${callbackQuery.id})`,
+      );
+    }
+  } else if (data === CALLBACK_RESUME && state.paused) {
+    if (stateFile === null) {
+      warnUnderivableRoot("pause-state write refused");
+    } else {
+      await savePauseState(stateFile, { paused: false, updatedAt: Date.now() });
+      log(
+        "info",
+        `telegram pause: agent resumed via callback (${callbackQuery.id})`,
+      );
+    }
+  }
+  // Re-read so `paused` reflects the persisted truth (idempotent re-taps).
+  const current = await loadPauseState(readFile);
+
+  const statusText = current.paused ? "⏸ Agent paused" : "▶ Agent running";
+  const answered = await answerCallback(deps, callbackQuery.id, statusText);
+
+  let edited = false;
+  const msg = callbackQuery.message;
+  if (msg?.message_id && msg?.chat?.id != null) {
+    const res = await deps.client.editMessageText(
+      deps.token,
+      msg.chat.id,
+      msg.message_id,
+      current.paused ? CONTROL_PAUSED_TEXT : CONTROL_RUNNING_TEXT,
+      { replyMarkup: buildControlKeyboard(current.paused) },
+    );
+    edited = res.ok;
+    if (!res.ok)
+      log(
+        "warn",
+        `telegram pause: keyboard edit failed (${res.error ?? "unknown"})`,
+      );
+  }
+
+  return { ok: true, action: data, paused: current.paused, answered, edited };
+}

package/src/lib/photo.ts

@@ -0,0 +1,182 @@
+/**
+ * photo.ts — shared inbound photo extraction (owner photo attachments).
+ *
+ * Both inbound consumers (background poller in inbound-poller.ts and the
+ * agentic pull in telegram-inbox.ts) route accepted photo messages through
+ * these helpers: pick the largest photo variant, resolve it to a download
+ * path via getFile, fetch the bytes, save them under the media dir, and
+ * produce the agent-facing delivery text carrying the absolute path (or, on
+ * failure, the file_id + an error note — never drop the message).
+ *
+ * Pure + injectable-fetch driven, mirroring the client's test conventions:
+ * `fetchFn` defaults to globalThis.fetch, so tests substitute a recorded
+ * fixture fake with NO network.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { defaultMediaDir, warnUnderivableRoot } from "./state-paths.js";
+import {
+  getFile,
+  downloadFile,
+  type TelegramFetch,
+} from "./telegram-client.js";
+
+/** One element of a Telegram `photo` array (PhotoSize). */
+export interface TelegramPhotoSize {
+  file_id: string;
+  file_unique_id?: string;
+  width?: number;
+  height?: number;
+  file_size?: number;
+}
+
+/** True when a message carries a non-empty `photo` array (photo inbound). */
+export function hasPhoto(message: unknown): boolean {
+  if (message == null || typeof message !== "object") return false;
+  const photo = (message as { photo?: unknown }).photo;
+  return Array.isArray(photo) && photo.length > 0;
+}
+
+/**
+ * Pick the largest photo variant: the one with the greatest `file_size`, or
+ * (when no sizes are present) the LAST array element — Telegram orders the
+ * `photo` array by size ascending, so the last is the largest. Returns
+ * undefined when no usable variant (with a file_id) exists.
+ */
+export function pickPhotoVariant(
+  photo: unknown,
+): TelegramPhotoSize | undefined {
+  if (!Array.isArray(photo) || photo.length === 0) return undefined;
+  const variants = photo.filter(
+    (v): v is TelegramPhotoSize =>
+      v != null &&
+      typeof v === "object" &&
+      typeof (v as { file_id?: unknown }).file_id === "string",
+  );
+  if (variants.length === 0) return undefined;
+  let largest = variants[variants.length - 1];
+  for (const v of variants) {
+    if (
+      typeof v.file_size === "number" &&
+      v.file_size > (largest.file_size ?? 0)
+    ) {
+      largest = v;
+    }
+  }
+  return largest;
+}
+
+/** Derive a safe short file extension from the Telegram file_path (fallback jpg). */
+function extFromFilePath(filePath?: string): string {
+  if (!filePath) return "jpg";
+  const last = filePath.split("/").pop() ?? "";
+  const dot = last.lastIndexOf(".");
+  if (dot >= 0 && dot < last.length - 1) {
+    const ext = last.slice(dot + 1).toLowerCase();
+    if (/^[a-z0-9]{1,8}$/.test(ext)) return ext;
+  }
+  return "jpg"; // Telegram photos are JPEG
+}
+
+/** Outcome of materializePhoto: saved path, or a degraded file_id + error. */
+export type MaterializePhotoResult =
+  | { ok: true; fileId: string; filePath: string; filePathOnTelegram: string }
+  | { ok: false; fileId: string; error: string };
+
+/**
+ * Download one photo variant and save it to `<mediaDir>/<updateId>.<ext>`.
+ * Never throws: a getFile / download / write failure returns
+ * `{ ok: false, fileId, error }` so the caller can degrade instead of drop.
+ */
+export async function materializePhoto(opts: {
+  token: string;
+  updateId: number;
+  photo: TelegramPhotoSize;
+  fetchFn?: TelegramFetch;
+  baseUrl?: string;
+  mediaDir?: string;
+}): Promise<MaterializePhotoResult> {
+  const { token, updateId, photo, fetchFn, baseUrl } = opts;
+  const fileId = photo.file_id;
+  const mediaDir = opts.mediaDir ?? defaultMediaDir();
+  if (mediaDir === null) {
+    warnUnderivableRoot("photo download refused");
+    return {
+      ok: false,
+      fileId,
+      error:
+        "braid media directory is underivable (BRAID_HOME unset and no absolute home); photo not saved",
+    };
+  }
+
+  const fileInfo = await getFile(token, fileId, { fetch: fetchFn, baseUrl });
+  const filePathOnTelegram = fileInfo.ok ? fileInfo.file?.file_path : undefined;
+  if (!fileInfo.ok || !filePathOnTelegram) {
+    return {
+      ok: false,
+      fileId,
+      error: fileInfo.error ?? "getFile returned no file_path",
+    };
+  }
+
+  const fileDownload = await downloadFile(token, filePathOnTelegram, {
+    fetch: fetchFn,
+    baseUrl,
+  });
+  if (!fileDownload.ok || !fileDownload.bytes) {
+    return {
+      ok: false,
+      fileId,
+      error: fileDownload.error ?? "file download failed",
+    };
+  }
+
+  const dest = join(
+    mediaDir,
+    `${updateId}.${extFromFilePath(filePathOnTelegram)}`,
+  );
+  try {
+    await mkdir(mediaDir, { recursive: true });
+    await writeFile(dest, fileDownload.bytes);
+  } catch (error) {
+    return {
+      ok: false,
+      fileId,
+      error: `failed to save ${dest}: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  return { ok: true, fileId, filePath: dest, filePathOnTelegram };
+}
+
+/** Options for formatPhotoText — the agent-facing delivery string. */
+export interface PhotoDeliveryTextOptions {
+  /** Sender label, e.g. "@owner" or "id 123" (matches the whisper header). */
+  senderLabel: string;
+  /** Absolute path of the saved file (when the download succeeded). */
+  filePath?: string;
+  /** Telegram file_id (always present for a photo message). */
+  fileId?: string;
+  /** Message caption (trimmed), if any. */
+  caption?: string;
+  /** Download/save failure note (degraded delivery). */
+  error?: string;
+}
+
+/**
+ * Build the delivered text the receiving agent can act on. Downloaded form:
+ *   📷 Photo from @owner: /abs/path.jpg (caption: <caption or none>)
+ * Degraded (download failed) form — never dropped:
+ *   📷 Photo from @owner: file_id <id> (caption: <caption or none>) (download failed: <error>)
+ */
+export function formatPhotoText(opts: PhotoDeliveryTextOptions): string {
+  const captionPart = opts.caption
+    ? ` (caption: ${opts.caption})`
+    : " (caption: none)";
+  if (opts.filePath) {
+    return `📷 Photo from ${opts.senderLabel}: ${opts.filePath}${captionPart}`;
+  }
+  const filePart = opts.fileId ? `file_id ${opts.fileId}` : "file_id unknown";
+  const errorPart = opts.error ? ` (download failed: ${opts.error})` : "";
+  return `📷 Photo from ${opts.senderLabel}: ${filePart}${errorPart}${captionPart}`;
+}