@timqi/pier 0.1.0 → 0.1.2

package/dist/channels/telegram-api.js

@@ -1,10 +1,6 @@
-// Thin Telegram Bot API client: HTTP and payload shapes only, no policy.
-// The one file in channels/ that talks to api.telegram.org, so the adapter
-// stays testable against this interface. Long polling, not webhooks — Pier is
-// one local process with no inbound HTTP requirement.
-//
-// Behind a proxy, run node with NODE_USE_ENV_PROXY=1 and HTTPS_PROXY set;
-// nothing here needs to know.
+// Thin Telegram Bot API client: HTTP and payload shapes only, no policy; the
+// one file that talks to api.telegram.org. Long polling, so Pier needs no
+// inbound HTTP. Behind a proxy: NODE_USE_ENV_PROXY=1 and HTTPS_PROXY.
 import { readCapped } from "../core/inbox.js";
 const BASE = "https://api.telegram.org";
 export class TelegramApi {
@@ -13,9 +9,7 @@ export class TelegramApi {
         this.token = token;
     }
     async call(method, payload, timeoutMs = 30_000, retry = true) {
-        // An upload is the one call that is not JSON: FormData carries the bytes,
-        // and fetch sets its own multipart boundary. It is re-sendable, so the
-        // flood retry below still works on it.
+        // FormData is re-sendable, so the flood retry below still works on it.
         const multipart = payload instanceof FormData;
         const res = await fetch(`${BASE}/bot${this.token}/${method}`, {
             method: "POST",
@@ -26,9 +20,8 @@ export class TelegramApi {
         const body = (await res.json());
         if (body.ok)
             return body.result;
-        // Telegram answers a flood (a long turn split into chunks hits ~1 msg/s per
-        // chat) with the exact wait. Obeying it once turns a dropped reply into a
-        // late one; a second 429 is a real problem and surfaces as an error.
+        // A long turn split into chunks hits ~1 msg/s per chat; `retry_after` is
+        // the exact wait. Obeyed once; a second 429 throws.
         const after = body.parameters?.retry_after;
         if (retry && after !== undefined && after <= 60) {
             await new Promise((r) => setTimeout(r, (after + 1) * 1000));
@@ -45,19 +38,15 @@ export class TelegramApi {
     sendMessage(payload) {
         return this.call("sendMessage", payload);
     }
-    /** Bytes, not a file_id or a URL: the file is local to this machine, which
-     *  is the whole reason the agent could not just link it. */
     async sendFile({ chat_id, message_thread_id, file }) {
         const form = new FormData();
         form.set("chat_id", String(chat_id));
         if (message_thread_id !== undefined)
             form.set("message_thread_id", String(message_thread_id));
         const field = file.image ? "photo" : "document";
-        // Copied into a fresh view: a Blob part must be backed by an ArrayBuffer,
-        // and a Buffer read off disk carries the wider ArrayBufferLike type.
+        // A Blob part must be backed by an ArrayBuffer, not a Buffer's ArrayBufferLike.
         form.set(field, new Blob([new Uint8Array(file.bytes)]), file.name);
-        // A long upload on a slow link is not a hung request; 30s is the budget
-        // for a JSON call, not for megabytes.
+        // 30s is the budget for a JSON call, not for megabytes on a slow link.
         await this.call(file.image ? "sendPhoto" : "sendDocument", form, 120_000);
     }
     async editMessage(payload) {
@@ -82,7 +71,6 @@ export class TelegramApi {
     async answerCallbackQuery(id, text) {
         await this.call("answerCallbackQuery", { callback_query_id: id, text });
     }
-    /** Bounded mid-stream: metadata size is the platform's word, not a cap. */
     async downloadFile(fileId, maxBytes) {
         const file = await this.call("getFile", { file_id: fileId });
         if (!file.file_path)

package/dist/channels/telegram-panel.js

@@ -1,10 +1,5 @@
-// Telegram's half of the settings panel: HTML markup, an inline keyboard, and
-// a forced reply for the one typed answer. The panel itself lives in
-// `panel.ts`.
-//
-// Asking for a working directory costs a Map here: a forced reply arrives as
-// an ordinary message, so the prompt's message id has to be remembered to
-// recognize the answer. Slack's modal carries that context itself.
+// Telegram's half of the settings panel (panel.ts has the rest). A forced reply
+// arrives as an ordinary message, so the prompt's id is remembered to recognize it.
 import { ChatPanel, CWD_PLACEHOLDER, CWD_TAIL, PANEL_PREFIX, } from "./panel.js";
 import { escapeHtml as esc } from "./telegram-render.js";
 const button = (b) => ({ text: b.label, callback_data: `${PANEL_PREFIX}${b.action}` });
@@ -12,7 +7,6 @@ export class TelegramPanel extends ChatPanel {
     deps;
     platform = "telegram";
     fence = ["<code>", "</code>"];
-    /** Conversations waiting for a typed working directory (ForceReply). */
     cwdPrompts = new Map();
     constructor(deps) {
         super(deps);
@@ -21,7 +15,6 @@ export class TelegramPanel extends ChatPanel {
     esc(text) {
         return esc(text);
     }
-    /** Topics are a Telegram-only gate, and only on a forum. */
     gateExtras(chat, policy) {
         return chat.kind === "forum" ? ` · topics ${policy.topicMode ? "on" : "off"}` : "";
     }
@@ -41,7 +34,6 @@ export class TelegramPanel extends ChatPanel {
             ],
         };
     }
-    /** Open a fresh panel, replacing whichever one this conversation had. */
     async open(key, chatId, topicId) {
         const view = await this.view(key, chatId);
         const sent = await this.deps.api.sendMessage({
@@ -67,10 +59,7 @@ export class TelegramPanel extends ChatPanel {
             .catch((err) => this.deps.log(`panel close failed: ${String(err)}`));
     }
     // --- actions -----------------------------------------------------------------
-    /**
-     * Handle a `cfg:` button. Returns false when the payload is not ours, so the
-     * caller can treat it as one of the agent's next-step labels instead.
-     */
+    /** Returns false when the payload is not ours. */
     async onCallback(query, key) {
         return this.dispatch(key, query.data ?? "", undefined, async () => {
             const message = query.message;
@@ -83,16 +72,12 @@ export class TelegramPanel extends ChatPanel {
         const sent = await this.deps.api.sendMessage({
             chat_id: state.chatId,
             message_thread_id: state.topicId,
-            // Said plainly: this is not an edit, it is a new session.
             text: `Reply with an absolute path. ${CWD_TAIL}`,
             reply_markup: { force_reply: true, input_field_placeholder: CWD_PLACEHOLDER },
         });
         this.cwdPrompts.set(key.conversationId, sent.message_id);
     }
-    /**
-     * Consume a reply to the working-directory prompt. Returns true when this
-     * message was that answer and must not reach the agent.
-     */
+    /** True when this message was the answer and must not reach the agent. */
     async consumeCwdReply(msg, key) {
         const pending = this.cwdPrompts.get(key.conversationId);
         if (!pending || msg.reply_to_message?.message_id !== pending)
@@ -100,8 +85,7 @@ export class TelegramPanel extends ChatPanel {
         this.cwdPrompts.delete(key.conversationId);
         const path = (msg.text ?? "").trim();
         const started = await this.startSessionIn(key, path);
-        // The answer was typed in the chat, so the outcome is said in the chat:
-        // a panel note alone would be easy to miss under one's own message.
+        // The answer was typed in the chat, so the outcome is said there too.
         await this.deps.api.sendMessage({
             chat_id: msg.chat.id,
             message_thread_id: msg.message_thread_id,

package/dist/channels/telegram-render.js

@@ -1,13 +1,8 @@
 import { chunkText } from "./chunk.js";
-// How a reply looks on Telegram: text and buttons.
-//
-// Markdown → Telegram Bot API HTML. Telegram's parser accepts a tiny tag set
-// and rejects the whole message on anything else, so we escape first and
-// reintroduce exactly the tags it documents: b, i, s, code, pre, a.
-// Unsupported markdown (tables, images, nested lists) degrades to plain text
-// rather than losing the message.
+// How a reply looks on Telegram: markdown → Bot API HTML. Telegram's parser
+// rejects the whole message on any tag outside its documented set (b, i, s,
+// code, pre, a), so text is escaped first and only those are reintroduced.
 const MAX_CHARS = 3800; // Telegram's hard limit is 4096; leave room for tags.
-/** Shared: the adapter and the panel escape plain text with this too. */
 export const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 /** Inline emphasis, applied after escaping so `<b>` can only come from us. */
 function inline(text) {
@@ -17,17 +12,11 @@ function inline(text) {
         .replace(/\*\*([^\n*]+)\*\*/g, "<b>$1</b>")
         .replace(/~~([^\n~]+)~~/g, "<s>$1</s>")
         .replace(/(^|[\s(])[*_]([^\n*_]+)[*_](?=[\s).,!?:;]|$)/g, "$1<i>$2</i>")
-        // Headings carry no size in Telegram; bold is the closest honest render.
         .replace(/^#{1,6}[ \t]+(.+)$/gm, "<b>$1</b>");
 }
-/**
- * Render one assistant turn. Code spans and fences are extracted before
- * escaping so emphasis inside them stays literal.
- */
+/** Code is stashed before escaping so emphasis inside it stays literal. */
 export function toTelegramHtml(markdown) {
     const stash = [];
-    // Private-use sentinels: markdown can't contain them, so a stashed block
-    // can't be re-matched by the escaping and emphasis passes that follow.
     const keep = (html) => `\uE000${stash.push(html) - 1}\uE001`;
     let out = markdown.replace(/```([\w.+-]*)\n?([\s\S]*?)```/g, (_m, lang, code) => keep(lang
         ? `<pre><code class="language-${escapeHtml(lang)}">${escapeHtml(code.replace(/\n+$/, ""))}</code></pre>`
@@ -36,31 +25,20 @@ export function toTelegramHtml(markdown) {
     out = inline(escapeHtml(out));
     return out.replace(/\uE000(\d+)\uE001/g, (_m, i) => stash[Number(i)] ?? "");
 }
-/**
- * Split rendered HTML into sendable chunks. A turn long enough to need this can
- * still be cut inside a <pre> block; Telegram closes the tag on its own and the
- * text survives, which beats dropping the turn. (Slack cannot do that, which is
- * why its renderer re-balances fences after the cut.)
- */
+/** A cut inside a <pre> block is fine: Telegram closes the tag on its own. */
 export const chunk = (html) => chunkText(html, MAX_CHARS);
 // --- next-step buttons -------------------------------------------------------
-/**
- * Telegram caps `callback_data` at 64 *bytes* — about 21 CJK characters, far
- * too little to carry a label. Buttons send an index instead, and the label is
- * read back off the message's own keyboard.
- */
+/** `callback_data` caps at 64 bytes (~21 CJK characters), so buttons send an
+ *  index and the label is read back off the message's own keyboard. */
 export const OFFER_PREFIX = "sg:";
-// Buttons in one row share the row's width, so packing is budgeted by display
-// width rather than count: a CJK glyph takes about twice an ASCII one.
+// Buttons in one row split its width evenly, so packing is budgeted by display
+// width, not count.
 const ROW_WIDTH = 26;
 const ROW_BUTTONS = 3;
-/** Rough rendered width: CJK, fullwidth punctuation and emoji take two cells. */
+/** CJK, fullwidth punctuation and emoji take two cells. */
 const displayWidth = (label) => [...label].reduce((n, ch) => n + ((ch.codePointAt(0) ?? 0) > 0x2e7f ? 2 : 1), 0);
-/**
- * Pack short labels onto shared rows, keeping the offered order. A row that is
- * already wide stops accepting: buttons in one Telegram row split the width
- * evenly, so squeezing a long label in truncates everything beside it.
- */
+/** A row that is already wide stops accepting: a long label squeezed in
+ *  truncates everything beside it. */
 export function keyboard(labels) {
     if (!labels.length)
         return undefined;
@@ -80,12 +58,7 @@ export function keyboard(labels) {
     });
     return { inline_keyboard: rows };
 }
-/**
- * The label a next-step payload stands for. Read off the tapped message's own
- * keyboard, which Telegram echoes back — so a button keeps working across a
- * restart or a config reload, where an in-memory offer list would not.
- * A payload we never wrote (an older label-as-payload button) passes through.
- */
+/** A payload we never wrote (an older label-as-payload button) passes through. */
 export function offeredLabel(msg, data) {
     if (!data.startsWith(OFFER_PREFIX))
         return data;