pi-braid-telegram 0.1.5 → 0.1.6

package/build-info.json

@@ -1,9 +1,9 @@
 {
   "name": "pi-braid-telegram",
-  "version": "0.1.5",
-  "sha": "752d2e6e9b45037a8ebcc17f3d6f90c905b2c71c",
-  "shaShort": "752d2e6",
-  "branch": "detached",
+  "version": "0.1.6",
+  "sha": "dc847759a4c99339571e7583ae848d8ec99e694c",
+  "shaShort": "dc84775",
+  "branch": "main",
   "dirty": false,
-  "packedAt": "2026-10-19T11:29:41.109Z"
+  "packedAt": "2026-10-23T21:27:14.009Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-braid-telegram",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Bidirectional Telegram channel for pi-braid: telegram_send tool (outbound) + inbound long-poll injector (backward channel)",
   "type": "module",
   "files": [

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/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 =