pi-braid-telegram 0.0.0-stage → 0.1.4

package/src/lib/inbound-queue.ts

@@ -0,0 +1,157 @@
+/**
+ * Durable store for owner messages not yet handed to the session.
+ *
+ * Owner messages steer by policy: an arrival is handed over at the coalescing
+ * window's close, busy or idle. An entry stays here only when that handoff
+ * did not happen, either because pi refused the steer (a prompt during
+ * compaction) or because a factory re-run (reload, session replacement)
+ * landed mid-window. The hold outlives the delivery attempt, so it lives in a
+ * FILE, not in an array: the extension factory is re-run on both lifecycle
+ * paths, a reload (resource-loader reload() clears the module cache and calls
+ * the factory again) and a session replacement (new/resume/fork build a new
+ * resource loader whose reload() calls the factory again, so the closure does
+ * not survive into the replacement session), and the delivery handler returns
+ * before the offset confirmation: the hold is written through while the
+ * handler runs, and the poller persists the offset past the update only at
+ * the end of the poll cycle. An in-memory hold would be dropped silently once
+ * the offset moves; the file survives the re-run, and each entry carries the
+ * session it was accepted for, so a hold rehydrated into a different named
+ * session is reported, not delivered — while an entry accepted before any
+ * session could name itself is adopted by the first session that names itself.
+ *
+ * This module only stores and returns entries: which session is current,
+ * whether an entry may be delivered, and what a human is told about an entry
+ * that cannot be, are delivery policy and live in the extension (index.ts).
+ * Every function here is total — a missing, truncated, or hand-edited file
+ * reads as "no entries" rather than throwing into a lifecycle handler; read
+ * failures other than ENOENT and version mismatches are surfaced through the
+ * caller-supplied reporter.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+
+import type { IncomingOwnerMessage } from "./inbound-poller.js";
+
+/** One held owner message plus the session it was accepted for. */
+export interface QueuedInboundMessage {
+  message: IncomingOwnerMessage;
+  /**
+   * Session the message was accepted for. `undefined` when the live context
+   * could not name one (no session manager on a synthetic context); such an
+   * entry is adopted by the first session that names itself (the current id is
+   * stamped on it at delivery/rehydrate). An entry accepted for a different
+   * named session is never delivered across that boundary.
+   */
+  sessionId?: string;
+  /** Acceptance time (ms) — keeps arrival order across process boundaries. */
+  queuedAt: number;
+}
+
+/** Current on-disk shape. Bumped only when the entry shape changes. */
+const QUEUE_VERSION = 1;
+
+/**
+ * Queue file for a given poller state file: a sibling in the same directory,
+ * named after the state file's stem, so the documented `BRAID_TG_STATE_FILE`
+ * knob governs both the offset and the hold, and two state files in one
+ * directory keep two separate holds. The name also says whose hold it was:
+ * moving the state file to another directory strands the old queue beside the
+ * old path — there is no auto-migration, and none is possible from the file
+ * alone.
+ */
+export function inboundQueueFileFor(stateFile: string): string {
+  const stem = basename(stateFile, extname(stateFile));
+  return join(dirname(stateFile), `${stem}-inbound-queue.json`);
+}
+
+/** Entry-shape guard for hand-edited files (the file version is checked separately). */
+function isQueuedEntry(value: unknown): value is QueuedInboundMessage {
+  const entry = value as Partial<QueuedInboundMessage> | undefined;
+  const message = entry?.message as Partial<IncomingOwnerMessage> | undefined;
+  if (!message || typeof message !== "object") return false;
+  if (!Number.isFinite(message.updateId)) return false;
+  if (typeof message.text !== "string") return false;
+  if (entry?.sessionId !== undefined && typeof entry.sessionId !== "string") {
+    return false;
+  }
+  return Number.isFinite(entry?.queuedAt);
+}
+
+/**
+ * Read problems that are not "nothing held": a non-ENOENT read failure or a
+ * file written by another version. The store stays total (the caller still
+ * gets `[]`), but a silent discard is exactly the failure class the durable
+ * hold exists to remove, so the caller is handed a message for its log.
+ * ENOENT and unparsable content are not reported: absent and hand-edited state
+ * is the documented "no entries" reading.
+ */
+export type QueueReadReporter = (message: string) => void;
+
+/**
+ * Read the held entries. Never throws: absent, unreadable, unparsable, or
+ * foreign-version state means "nothing held" (a lost hold is reported by the
+ * delivery path, which knows the session it belonged to; a read failure here
+ * must not take down the lifecycle handler that is rehydrating it). Read
+ * failures other than ENOENT and version mismatches are passed to `report`.
+ */
+export async function loadInboundQueue(
+  queueFile: string,
+  report?: QueueReadReporter,
+): Promise<QueuedInboundMessage[]> {
+  let raw: string;
+  try {
+    raw = await readFile(queueFile, "utf8");
+  } catch (error) {
+    const code = (error as { code?: unknown } | null)?.code;
+    if (code !== "ENOENT") {
+      report?.(
+        `could not read the inbound hold file ${queueFile}: ${String(error)}`,
+      );
+    }
+    return [];
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  const file = parsed as { version?: unknown; entries?: unknown } | null;
+  if (file?.version !== QUEUE_VERSION) {
+    report?.(
+      `ignoring the inbound hold file ${queueFile}: version ${String(file?.version)} is not ${QUEUE_VERSION}`,
+    );
+    return [];
+  }
+  const entries = Array.isArray(file.entries) ? file.entries : [];
+  return entries.filter(isQueuedEntry);
+}
+
+/**
+ * Persist the held entries ATOMICALLY (write-temp-rename, same rationale as
+ * savePauseState): the JSON is written to a temp file first and renamed over
+ * the target, so a crash mid-write can never leave a truncated queue behind —
+ * the truncation would read back as "nothing held" and lose exactly the
+ * messages this file exists to protect. The temp name is unique per write:
+ * a shared temp made concurrent savers fail each other's rename (ENOENT),
+ * while unique temps all land and the last rename wins with a whole snapshot.
+ */
+export async function saveInboundQueue(
+  queueFile: string,
+  entries: QueuedInboundMessage[],
+): Promise<void> {
+  const dir = dirname(queueFile);
+  try {
+    await mkdir(dir, { recursive: true });
+  } catch {
+    // parent may already exist; the write will surface real errors
+  }
+  const tmp = `${queueFile}.${randomUUID()}.tmp`;
+  await writeFile(
+    tmp,
+    JSON.stringify({ version: QUEUE_VERSION, entries }, null, 2) + "\n",
+    "utf8",
+  );
+  await rename(tmp, queueFile);
+}

package/src/lib/local-time.ts

@@ -0,0 +1,181 @@
+/**
+ * Local-time rendering for the telegram package — MIRROR of the core
+ * formatter.
+ *
+ * Telegram cannot import pi-braid core (standalone package, no core dep) —
+ * the established cross-package pattern is a documented literal mirror with
+ * a keep-in-sync test (see watchdog-tunnel.ts: the WATCHDOG_TG_SIGNAL_KEY
+ * mirror). This module mirrors packages/core/src/lib/utils/local-time.ts:
+ *
+ *   formatWhisperClock(ms) -> "17:05 MSK" (whisper header `@ HH:MM TZ`)
+ *   formatLocalTime(ms) -> "17:05 MSK (UTC+3)"
+ *
+ * Owner TZ: `braid.timezone` in ~/.pi/agent/settings.json (same key the
+ * core formatter reads — one setting controls both), default Europe/Moscow.
+ * Keep the two files in sync; test/local-time.test.mjs pins the parity
+ * contract (same inputs → same outputs as the core shapes).
+ *
+ * All Intl-based (Node >= 22 full ICU). No external deps.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export const DEFAULT_TIME_ZONE = "Europe/Moscow";
+
+/** settings.json (pi-native) — same path + braid block as pause-control.ts. */
+const SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
+
+/**
+ * Owner time zone: braid.timezone in ~/.pi/agent/settings.json when set,
+ * else Europe/Moscow. Mirrors core's getOwnerTimeZone() so both packages
+ * render the SAME zone from the SAME setting. Never throws.
+ */
+export function ownerTimeZone(): string {
+  try {
+    if (existsSync(SETTINGS_PATH)) {
+      const parsed = JSON.parse(readFileSync(SETTINGS_PATH, "utf8")) as {
+        braid?: { timezone?: unknown };
+      };
+      const tz = parsed?.braid?.timezone;
+      if (typeof tz === "string" && tz.trim()) return tz.trim();
+    }
+  } catch {
+    // non-fatal — fall through to the default
+  }
+  return DEFAULT_TIME_ZONE;
+}
+
+/** Validate an IANA time zone name cheaply (invalid names fall back). */
+function isValidTimeZone(tz: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-GB", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Abbreviation overrides for well-known FIXED-offset zones — CLDR renders
+ * Europe/Moscow as "GMT+3" but the owner format examples specify "MSK".
+ * MIRROR of packages/core/src/lib/utils/local-time.ts ZONE_ABBREVIATIONS —
+ * keep in sync (parity pinned by test/local-time.test.mjs). Zones not in the
+ * map fall back to the ICU short name ("EDT", "GMT+1", ...). Never invent an
+ * abbreviation for a DST zone.
+ */
+const ZONE_ABBREVIATIONS: Record<string, string> = {
+  "Europe/Moscow": "MSK",
+  "Europe/Kaliningrad": "EET",
+  "Europe/Samara": "SAMT",
+  "Asia/Yekaterinburg": "YEKT",
+  "Asia/Omsk": "OMST",
+  "Asia/Novosibirsk": "NOVT",
+  "Asia/Krasnoyarsk": "KRAT",
+  "Asia/Irkutsk": "IRKT",
+  "Asia/Yakutsk": "YAKT",
+  "Asia/Vladivostok": "VLAT",
+  "Asia/Magadan": "MAGT",
+  "Asia/Kamchatka": "PETT",
+};
+
+/** The zone's short abbreviation (e.g. "MSK"); ICU short fallback otherwise. */
+function zoneAbbreviation(date: Date, timeZone: string): string {
+  const known = ZONE_ABBREVIATIONS[timeZone];
+  if (known) return known;
+  const parts = new Intl.DateTimeFormat("en-GB", {
+    timeZone,
+    timeZoneName: "short",
+  }).formatToParts(date);
+  const name = parts.find((p) => p.type === "timeZoneName")?.value;
+  return name && name.length > 0 ? name : "UTC";
+}
+
+/** Offset from UTC in minutes at the given instant (DST-safe). */
+function zoneOffsetMinutes(date: Date, timeZone: string): number {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  }).formatToParts(date);
+  const map: Record<string, string> = {};
+  for (const p of parts) map[p.type] = p.value;
+  const asUTC = Date.UTC(
+    Number(map.year),
+    Number(map.month) - 1,
+    Number(map.day),
+    Number(map.hour) % 24,
+    Number(map.minute),
+    Number(map.second),
+  );
+  return Math.round((asUTC - date.getTime()) / 60_000);
+}
+
+/** Render a minutes offset as "UTC+3" / "UTC-5" / "UTC+5:30" / "UTC+0". */
+function formatOffset(minutes: number): string {
+  if (minutes === 0) return "UTC+0";
+  const sign = minutes > 0 ? "+" : "-";
+  const abs = Math.abs(minutes);
+  const h = Math.floor(abs / 60);
+  const m = abs % 60;
+  return `UTC${sign}${h}${m > 0 ? `:${String(m).padStart(2, "0")}` : ""}`;
+}
+
+/**
+ * Full local-time form (mirror of core formatLocalTime): "HH:MM TZ (UTC±X)".
+ *
+ * @param ms       epoch milliseconds to render (default: now)
+ * @param withDate prepend "YYYY-MM-DD "
+ */
+export function formatLocalTime(
+  ms: number = Date.now(),
+  withDate = false,
+): string {
+  const tz = ownerTimeZone();
+  const safeTz = isValidTimeZone(tz) ? tz : DEFAULT_TIME_ZONE;
+  const date = new Date(ms);
+  const time = new Intl.DateTimeFormat("en-GB", {
+    timeZone: safeTz,
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).format(date);
+  const abbr = zoneAbbreviation(date, safeTz);
+  const datePart = withDate
+    ? `${new Intl.DateTimeFormat("en-CA", {
+        timeZone: safeTz,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+      }).format(date)} `
+    : "";
+  return `${datePart}${time} ${abbr} (${formatOffset(zoneOffsetMinutes(date, safeTz))})`;
+}
+
+/**
+ * Compact header clock (mirror of core formatWhisperClock): "HH:MM TZ" —
+ * the whisper-header form (`@ HH:MM TZ`), a few tokens short.
+ *
+ * @param ms epoch milliseconds to render (default: now). For inbound TG
+ *           messages pass `update.date * 1000` (unix seconds → ms) so the
+ *           header shows WHEN the owner actually sent the message.
+ */
+export function formatWhisperClock(ms: number = Date.now()): string {
+  const tz = ownerTimeZone();
+  const safeTz = isValidTimeZone(tz) ? tz : DEFAULT_TIME_ZONE;
+  const date = new Date(ms);
+  const time = new Intl.DateTimeFormat("en-GB", {
+    timeZone: safeTz,
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).format(date);
+  const abbr = zoneAbbreviation(date, safeTz);
+  return `${time} ${abbr}`;
+}

package/src/lib/notify/agent-delivery.ts

@@ -0,0 +1,29 @@
+/**
+ * Agent-delivered report flag — the telegram_send ↔ live-update seam.
+ *
+ * Live-update's finish() sends its OWN separate turn-end summary. When the
+ * AGENT already delivered an explicit report via telegram_send during the
+ * turn, that auto summary duplicates it (two similar messages,
+ * one raw/unformatted). This module is the tiny process-local flag the send
+ * path sets and the live-update resolver reads + clears at the turn boundary.
+ *
+ * Process-local only (no persistence, no IPC): both sides run in the same
+ * extension process. The flag is intentionally dumb — no timestamps, no
+ * counting — a successful explicit delivery is all finish() needs to know.
+ */
+let agentDeliveredFlag = false;
+
+/** Record that the agent explicitly delivered a Telegram message this turn. */
+export function markAgentDeliveredMessage(): void {
+  agentDeliveredFlag = true;
+}
+
+/** Clear the flag (fresh turn boundary). Idempotent. */
+export function clearAgentDeliveredMessage(): void {
+  agentDeliveredFlag = false;
+}
+
+/** True when the agent sent an explicit Telegram message this turn. */
+export function wasAgentDeliveredMessage(): boolean {
+  return agentDeliveredFlag;
+}

package/src/lib/notify/craft.ts

@@ -0,0 +1,157 @@
+/**
+ * turn-complete notify — pure crafting logic.
+ *
+ * Pure, unit-testable without pi-core runtime or any LLM:
+ *  - shouldNotifyTurnEnd  — decide whether a turn_end event warrants a notify
+ *  - extractFinalText     — pull the assistant's final text out of the event
+ *  - buildNotifyPrompts   — the distilling prompt (system + user)
+ *  - truncateGuard        — the ≤ notifyMaxChars guard-fallback: the crafting
+ *                           model PRODUCES the message; this stays only as a
+ *                           safety net (default: braid.telegram.notifyMaxChars,
+ *                           1200 when unset).
+ *
+ * Turn-end payload (VERIFIED against pi-core dist/core/extensions/types.d.ts):
+ *   TurnEndEvent { type: "turn_end", turnIndex, message, toolResults }
+ *   — NO separate toolCalls flag. A "trailing tool call" turn is detected by
+ *     message.stopReason === "toolUse" (the model's last action was emitting a
+ *     tool call, so work continues next turn). A completed answer turn has
+ *     stopReason "stop" (or length/error) with text content.
+ *
+ * The notify model call reuses "our systems" (not the bot token): it goes
+ * through ctx.modelRegistry (which pi-braid-providers wires to the key-ring
+ * via auth.apiKey.resolve), mirroring the extension→LLM path that core's
+ * llm-call.ts wraps (completeSimple from @earendil-works/pi-ai/compat).
+ */
+
+import { DEFAULT_NOTIFY_MAX_CHARS } from "../telegram-settings.js";
+
+/** Which turns notify: only completed-answer turns (plain text, no trailing
+ *  tool call). Never notify while the agent is mid-work. */
+export function shouldNotifyTurnEnd(event: unknown): boolean {
+  const message = (
+    event as {
+      message?: { role?: unknown; stopReason?: unknown; content?: unknown };
+    }
+  )?.message;
+  if (!message || typeof message !== "object") return false;
+  if (message.role !== "assistant") return false;
+  // "toolUse" stopReason = the model's last action was a tool call → the turn
+  // did NOT complete with an answer (work continues next turn). Skip notify.
+  if (message.stopReason === "toolUse") return false;
+  return extractFinalTextFromContent(message.content).trim().length > 0;
+}
+
+/** Inspect an assistant message's content for its final text. */
+function extractFinalTextFromContent(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    const b = block as { type?: unknown; text?: unknown } | undefined;
+    if (b?.type === "text" && typeof b.text === "string") parts.push(b.text);
+  }
+  return parts.join("\n").trim();
+}
+
+/**
+ * Is this a terminal turn WITH NO REPORT — i.e. the task is over without an
+ * answer? Canonical terminal-non-completed detection (context-manager
+ * handlers/events.ts: lastAssistant.stopReason is neither "error" nor
+ * "aborted") — do NOT re-derive it here. Concretely:
+ *  - last assistant stopReason "error" or "aborted" → terminal, no report;
+ *  - no assistant message at all → terminal, no report;
+ *  - stopReason "toolUse" (or anything else non-terminal) → work continues
+ *    next turn — the live-update indicator must STAY active.
+ */
+export function isTerminalNoReportTurn(event: unknown): boolean {
+  const message = (
+    event as { message?: { role?: unknown; stopReason?: unknown } }
+  )?.message;
+  if (!message || typeof message !== "object") return true; // no assistant message → no report
+  if (message.role !== "assistant") return true; // turn ended without an assistant report
+  if (message.stopReason === "toolUse") return false; // work continues next turn
+  return message.stopReason === "error" || message.stopReason === "aborted";
+}
+
+/** The final assistant text of a turn ("" when absent). */
+export function extractFinalText(event: unknown): string {
+  const message = (event as { message?: { content?: unknown } })?.message;
+  if (!message || typeof message !== "object") return "";
+  return extractFinalTextFromContent(message.content);
+}
+
+/**
+ * Build the distilling prompt for the crafting model.
+ *
+ * The model receives the agent's final answer and must produce an owner-ready
+ * update, at most `maxLength` chars (the configured notifyMaxChars — default
+ * 1200). No greetings, no filler, no markdown noise.
+ */
+export function buildNotifyPrompts(
+  finalText: string,
+  maxLength: number = DEFAULT_NOTIFY_MAX_CHARS,
+): {
+  system: string;
+  user: string;
+} {
+  const system =
+    "You distill an AI assistant's finished response into ONE concise, " +
+    `plain-text update for its human operator. Rules:\n` +
+    `- At most ${maxLength} characters — complete and readable, never a clipped fragment.\n` +
+    `- State what was done / the key result. No greetings, no sign-off, no filler.\n` +
+    `- Plain text only: no markdown formatting, no bullet lists.\n` +
+    `- If the response has no actionable content, reply with the single word: DONE.`;
+  const user = `Agent's finished response:\n\n${finalText.slice(0, 4000)}`;
+  return { system, user };
+}
+
+/** Delivered-format choice threaded into the rich-summary craft prompt. */
+export type NotifyFormat = "HTML" | "Markdown";
+
+/**
+ * Build the rich summary prompt for the live-update final report.
+ * Unlike the concise notify prompt, this one FLAGS the model to produce
+ * structured formatting (`mode`) and to make the report as long as needed —
+ * split-to-fit handles the 4096-char cap downstream. `mode` is threaded into
+ * the prompt (not just the transport) so the model emits the right markup
+ * from the start instead of the delivery layer guessing. Defaults to
+ * "Markdown".
+ */
+export function buildRichSummaryPrompts(
+  finalText: string,
+  mode: NotifyFormat = "Markdown",
+): { system: string; user: string } {
+  const formatting =
+    mode === "HTML"
+      ? "- Use Telegram HTML: <b>bold</b> headings, <i>italic</i>, <code>code</code>, short sections.\n" +
+        "- Telegram HTML only: NO raw Markdown (no **, _, `, [#](url)) — HTML tags only.\n"
+      : "- Use Telegram Markdown: **bold** headings, bullet lists, short sections.\n" +
+        "- Telegram Markdown only: **bold**, _italic_, `code` — no raw HTML, no fences.\n";
+  const system =
+    "You turn an AI assistant's finished response into a beautiful, structured " +
+    "Telegram report for its human operator. Rules:\n" +
+    formatting +
+    "- Keep it readable on mobile: short paragraphs; lists over prose walls.\n" +
+    "- Lead with what was done, then key results, then any follow-ups.\n" +
+    "- No title banner, no sign-off, no filler — length as needed (split-to-fit handles the 4096 cap).";
+  const user = `Agent's finished response:\n\n${finalText.slice(0, RICH_SUMMARY_INPUT_MAX)}`;
+  return { system, user };
+}
+
+/** Max response chars fed to the rich-summary crafting model. */
+export const RICH_SUMMARY_INPUT_MAX = 12_000;
+
+/**
+ * Guard-fallback: hard-truncate to `maxLen` with an ellipsis. Used when the
+ * crafting model is unavailable or returns something malformed — the cap is a
+ * safety net, never the primary shortening path.
+ */
+export function truncateGuard(
+  text: string,
+  maxLen: number = DEFAULT_NOTIFY_MAX_CHARS,
+): string {
+  const trimmed = text.trim();
+  if (trimmed.length <= maxLen) return trimmed;
+  const head = trimmed.slice(0, Math.max(0, maxLen - 1)).trimEnd();
+  return head + "…";
+}