pi-braid-telegram 0.1.4 → 0.1.6

package/README.md

@@ -4,6 +4,12 @@
 
 Bidirectional Telegram channel for pi-braid.
 
+```bash
+pi install npm:pi-braid-telegram
+```
+
+One command, no clone, no build: `pi install` registers the package with pi and installs it under pi's npm directory.
+
 - **Outbound**: `telegram_send` tool - the agent sends text messages to the
   owner (or voice notes once a TTS source is configured). Messages are LONG by
   default: plain text sends verbatim up to the cap (`braid.telegram.sendMaxChars`
@@ -96,6 +102,17 @@ Or register the workspace in `~/.pi/agent/settings.json`:
 - A bot token from @BotFather; optionally `BRAID_TG_CHAT_ID` / `BRAID_TG_ALLOWED_USERS` for the
   allow-list.
 
+## Settings cadence
+
+Settings live in `~/.pi/agent/settings.json`. `braid.telegram.pauseStateFile`
+is captured as the callback write target when the extension loads. `getPauseState()`
+resolves its read path per call, so restart after changing the setting to keep
+reads and writes aligned. `braid.telegram.tts` is loaded into the voice hook at
+extension load; restart after changing its source, rate, or voices.
+The send and notification caps (`braid.telegram.sendMaxChars` and
+`braid.telegram.notifyMaxChars`) are re-read per operation and change without
+a restart.
+
 ## Environment variables
 
 | Var                                | Purpose                                                                | Required                                                        |

package/build-info.json

@@ -0,0 +1,9 @@
+{
+  "name": "pi-braid-telegram",
+  "version": "0.1.6",
+  "sha": "dc847759a4c99339571e7583ae848d8ec99e694c",
+  "shaShort": "dc84775",
+  "branch": "main",
+  "dirty": false,
+  "packedAt": "2026-10-23T21:27:14.009Z"
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "pi-braid-telegram",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Bidirectional Telegram channel for pi-braid: telegram_send tool (outbound) + inbound long-poll injector (backward channel)",
   "type": "module",
   "files": [
     "src/",
     "docs/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "build-info.json"
   ],
   "exports": {
     ".": "./src/index.ts"
@@ -34,16 +35,17 @@
     "test": "node test/run-tests.mjs",
     "check:doc-index": "node ../../packages/core/scripts/check-doc-index.mjs",
     "publish:local": "node ../../packages/core/scripts/publish-local.mjs telegram",
-    "prepack": "npm run build"
+    "prepack": "npm run build && node ../../packages/core/scripts/pack-provenance.mjs write",
+    "postpack": "node ../../packages/core/scripts/pack-provenance.mjs remove"
   },
   "devDependencies": {
     "typescript": "6.0.2",
     "typebox": "1.1.38"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "typebox": "*"
+    "@earendil-works/pi-ai": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "typebox": "^1.1.38"
   },
   "author": "kifirkin",
   "license": "MIT",

package/src/index.ts

@@ -67,6 +67,7 @@ import {
 import {
   createInboundPoller,
   type IncomingOwnerMessage,
+  type IncomingReplyContext,
   type InboundPoller,
   type PauseStateReader,
 } from "./lib/inbound-poller.js";
@@ -374,6 +375,24 @@ export function log(
 
 // Inbound formatting (agent-zero prompts/fw.telegram.user_message.md template)
 
+/**
+ * The reply reference line, rendered into the envelope header so the owner's
+ * "yes, that one" arrives attached to what it answers. An absent reference
+ * renders NOTHING: a message that is not a reply keeps exactly the envelope it
+ * had, so a missing or malformed reply field can only ever cost the reference.
+ */
+export function formatReplyLine(reply?: IncomingReplyContext): string {
+  if (!reply) return "";
+  const target =
+    reply.author === "agent"
+      ? "your message"
+      : reply.author === "owner"
+        ? "the owner's message"
+        : "an unidentified message";
+  const quoted = reply.excerpt ? ` — "${reply.excerpt}"` : "";
+  return `\nreplying to ${target} ${reply.messageId}${quoted}`;
+}
+
 export function formatInboundMessage(message: IncomingOwnerMessage): string {
   const sender = message.username
     ? `@${message.username}`
@@ -387,7 +406,7 @@ export function formatInboundMessage(message: IncomingOwnerMessage): string {
     : "";
   // The opening tag line carries nothing after `]`: the provenance line
   // starts on its own line so the envelope header is readable at a glance.
-  const header = `[braid-whisper - telegram${sentClock}]\nfrom ${sender}${name} in chat ${message.chatId}/${message.chatType}`;
+  const header = `[braid-whisper - telegram${sentClock}]\nfrom ${sender}${name} in chat ${message.chatId}/${message.chatType}${formatReplyLine(message.replyTo)}`;
   return `${header}\n\n${message.text.trim()}\n[braid-whisper-end]`;
 }
 
@@ -410,7 +429,7 @@ export function formatInboundBatch(messages: IncomingOwnerMessage[]): string {
     const sentClock = Number.isFinite(message.receivedAt)
       ? ` @ ${formatWhisperClock(message.receivedAt)}`
       : "";
-    const partHeader = `[${index + 1}/${messages.length}${sentClock}] from ${sender}${name} in chat ${message.chatId}/${message.chatType}`;
+    const partHeader = `[${index + 1}/${messages.length}${sentClock}] from ${sender}${name} in chat ${message.chatId}/${message.chatType}${formatReplyLine(message.replyTo)}`;
     return `${partHeader}\n\n${message.text.trim()}`;
   });
   return `${header}\n\n${parts.join("\n\n")}\n[braid-whisper-end]`;

package/src/lib/format.ts

@@ -27,7 +27,11 @@ import type {
   TelegramSendResult,
   ParseMode,
 } from "./telegram-client.js";
-import { checkTelegramHtml, parseTelegramTagAt } from "./html-check.js";
+import {
+  TELEGRAM_HTML_TAGS,
+  checkTelegramHtml,
+  parseTelegramTagAt,
+} from "./html-check.js";
 
 /** Telegram hard cap for a single text message (https://core.telegram.org/bots/api#sendmessage). */
 export const TELEGRAM_MAX_TEXT_LENGTH = 4096;
@@ -145,17 +149,26 @@ export function isBalancedMarkdown(text: string): boolean {
 // attribute value is part of the tag, so `<a href="a>b">` is one token and is
 // removed whole rather than truncated at the first `>`.
 
-/** True when the text contains raw HTML tags — a signal it was authored as HTML. */
+/** True when the text contains a tag Telegram's HTML parser accepts.
+ *
+ * Tag-shaped is not enough: auto-selecting HTML for a body carrying `<n>` or
+ * `<b/>` makes Telegram reject the whole message ("Unsupported start tag"),
+ * while as a plain body the same characters reach the reader literally. Only
+ * a token whose name is in Telegram's tag set and whose syntax the parser
+ * accepts is a signal the body was authored as HTML.
+ */
 export function hasHtmlTags(text: string): boolean {
   return findTagToken(text) !== null;
 }
 
-/** First tag-shaped token in `text`, or null. */
+/** First tag-shaped token Telegram would accept, or null. */
 function findTagToken(text: string): { start: number; end: number } | null {
   let i = text.indexOf("<");
   while (i !== -1) {
     const tag = parseTelegramTagAt(text, i);
-    if (tag) return { start: i, end: tag.end };
+    if (tag && tag.error === undefined && TELEGRAM_HTML_TAGS.has(tag.name)) {
+      return { start: i, end: tag.end };
+    }
     i = text.indexOf("<", i + 1);
   }
   return null;

package/src/lib/inbound-poller.ts

@@ -69,6 +69,40 @@ import {
   type SttConfig,
 } from "./transcribe.js";
 
+/**
+ * One-line cap for the quoted excerpt. The excerpt is untrusted text copied
+ * into the prompt header, so it is hard-capped: a multi-KB replied message
+ * would ride into every reply for no gain.
+ */
+export const REPLY_EXCERPT_MAX_CHARS = 120;
+
+/**
+ * The message the owner replied to.
+ *
+ * Carried on the received message rather than resolved on demand: a lookup
+ * would put a getMessage round trip inside the receive path, where a failure
+ * costs the owner a delivered message, and the update already holds the
+ * reference.
+ */
+export interface IncomingReplyContext {
+  /** `message_id` of the replied message — the name the owner can point at. */
+  messageId: number;
+  /**
+   * Who sent the replied message. "agent" and "owner" mean different things,
+   * and conflating them misleads worse than silence: "yes, that one" answering
+   * our own message is a confirmation, answering the owner's is a correction.
+   * "unknown" is a sender Telegram omitted, or a bot that is not provably ours
+   * (a message forwarded from another bot).
+   */
+  author: "agent" | "owner" | "unknown";
+  /**
+   * Sanitised one-line excerpt of the replied message's text (or its caption
+   * when it carried no text), capped at REPLY_EXCERPT_MAX_CHARS. Absent when
+   * the replied message carried neither.
+   */
+  excerpt?: string;
+}
+
 export interface IncomingOwnerMessage {
   updateId: number;
   messageId: number;
@@ -78,6 +112,8 @@ export interface IncomingOwnerMessage {
   chatId: number;
   chatType: string;
   text: string;
+  /** Present when the owner replied to a specific message (absent otherwise). */
+  replyTo?: IncomingReplyContext;
   /** Present for photo messages (absent for plain-text). */
   photo?: {
     fileId: string;
@@ -144,6 +180,12 @@ export interface WatchdogTunnelStatusEvent {
 /** Media-extraction context threaded into extractIncomingMessage (photo/voice/document inbound). */
 export interface IncomingMediaContext {
   token?: string;
+  /**
+   * Our own bot id when the caller knows it (a cached getMe result). It only
+   * sharpens the reply-reference author verdict; absent, `is_bot` alone
+   * decides.
+   */
+  botId?: number;
   fetchFn?: TelegramFetch;
   baseUrl?: string;
   mediaDir?: string;
@@ -413,6 +455,89 @@ export function isAllowed(
   return false;
 }
 
+/**
+ * Read the reply reference from the update the poller already holds.
+ *
+ * Never throws and never fetches: an absent, malformed, or partly readable
+ * `reply_to_message` degrades the REFERENCE (the id alone, or nothing) and
+ * leaves the delivery untouched — this channel's contract is that an owner
+ * message is never dropped, and a richer envelope must not weaken it.
+ */
+export function extractReplyContext(
+  message: unknown,
+  botId?: number,
+): IncomingReplyContext | undefined {
+  if (message === null || typeof message !== "object") return undefined;
+  const raw = (message as { reply_to_message?: unknown }).reply_to_message;
+  if (raw === null || typeof raw !== "object") return undefined;
+  const reply = raw as {
+    message_id?: unknown;
+    from?: unknown;
+    text?: unknown;
+    caption?: unknown;
+  };
+  if (
+    typeof reply.message_id !== "number" ||
+    !Number.isFinite(reply.message_id)
+  ) {
+    return undefined;
+  }
+  const from = reply.from;
+  const sender =
+    from !== null && typeof from === "object"
+      ? (from as { id?: unknown; is_bot?: unknown })
+      : undefined;
+  const excerptText =
+    typeof reply.text === "string" && reply.text.trim()
+      ? reply.text
+      : typeof reply.caption === "string" && reply.caption.trim()
+        ? reply.caption
+        : undefined;
+  const excerpt = excerptText ? oneLineExcerpt(excerptText) : undefined;
+  return {
+    messageId: reply.message_id,
+    author: classifyReplyAuthor(sender, botId),
+    ...(excerpt ? { excerpt } : {}),
+  };
+}
+
+/**
+ * Whose message was replied to. Telegram marks bot senders with `is_bot`; our
+ * own id, when the caller knows it, is the only positive proof that a bot
+ * message was OURS, so a bot that cannot be proven ours reads as "unknown"
+ * rather than claiming authorship we cannot verify.
+ */
+function classifyReplyAuthor(
+  sender: { id?: unknown; is_bot?: unknown } | undefined,
+  botId: number | undefined,
+): IncomingReplyContext["author"] {
+  if (!sender || typeof sender.id !== "number") return "unknown";
+  if (typeof botId === "number") {
+    if (sender.id === botId) return "agent";
+    return sender.is_bot === true ? "unknown" : "owner";
+  }
+  return sender.is_bot === true ? "agent" : "owner";
+}
+
+/**
+ * Flatten the replied text to ONE line and defuse it before it reaches the
+ * envelope header: control and format characters (newlines, line separators,
+ * zero-width joiners) would let the quoted text forge extra header lines, and
+ * a bracketed `[braid-whisper ...]` marker would let it open or close an
+ * envelope inside the one it is quoted into. Then cut to the cap, with a
+ * visible ellipsis.
+ */
+function oneLineExcerpt(raw: string): string | undefined {
+  const flat = raw
+    .replace(/[\p{Cc}\p{Cf}]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/\[\s*braid-whisper([^\]]*)\]/gi, "braid-whisper$1");
+  if (!flat) return undefined;
+  if (flat.length <= REPLY_EXCERPT_MAX_CHARS) return flat;
+  return flat.slice(0, REPLY_EXCERPT_MAX_CHARS - 1).trimEnd() + "…";
+}
+
 /**
  * Extract an accepted message into the shape handed to consumers (shared by
  * the background poller and telegram-inbox). Plain-text messages map 1:1.
@@ -438,6 +563,10 @@ export async function extractIncomingMessage(
   media: IncomingMediaContext = {},
 ): Promise<IncomingOwnerMessage> {
   const message = update.message!;
+  // Read the reference ONCE and let every variant below inherit it through
+  // `base`: the plain-text, photo, voice, document, and text+document returns
+  // all spread `base`, so no delivery path can lose it by omission.
+  const replyTo = extractReplyContext(message, media.botId);
   const base = {
     updateId: update.update_id,
     messageId: message.message_id,
@@ -447,6 +576,7 @@ export async function extractIncomingMessage(
     chatId: message.chat.id,
     chatType: message.chat.type,
     receivedAt: message.date * 1000,
+    ...(replyTo ? { replyTo } : {}),
   };
   const text = typeof message.text === "string" ? message.text.trim() : "";
   const caption =