@sympoies/dsh-telegram 0.0.0-bootstrap.0 → 0.6.0

package/lib/media/screenshot.js

@@ -0,0 +1,101 @@
+/**
+ * Taking a picture of the screen the harness is running on.
+ *
+ * Useful for the same reason the bot exists at all: the machine is at a desk
+ * and you are not. Checking what a long build is showing, or what that dialog
+ * says, is otherwise a trip back to the keyboard.
+ *
+ * It is also the one thing this plugin does that sends the machine's own
+ * contents outward without the agent being involved, and a screen holds
+ * whatever happens to be on it — an open password manager, someone else's
+ * messages, an unrelated customer's data. So it is off unless switched on, and
+ * the switch is deliberately a deployment setting rather than a chat command:
+ * turning it on should take the same access as configuring the bot.
+ *
+ * macOS also requires Screen Recording permission for the process that runs
+ * the harness. Without it `screencapture` succeeds and returns the desktop
+ * picture with no windows, which looks like a broken feature rather than a
+ * missing permission — so that case is named rather than shrugged at.
+ */
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SILENT_LOGGER } from '../harness/types.js';
+/** How long to wait for the capture before giving up. */
+const DEFAULT_TIMEOUT_MS = 20_000;
+/** Telegram refuses a photo above this; a document goes up to 50 MB. */
+export const PHOTO_LIMIT_BYTES = 10 * 1024 * 1024;
+export class Screenshotter {
+    options;
+    logger;
+    constructor(options = {}) {
+        this.options = options;
+        this.logger = options.logger ?? SILENT_LOGGER;
+    }
+    /** Whether this platform has a capture tool this knows how to drive. */
+    get available() {
+        return (this.options.platform ?? process.platform) === 'darwin' || this.options.run !== undefined;
+    }
+    /**
+     * Capture the screen.
+     *
+     * @returns the image, or why there is none.
+     */
+    async take() {
+        const platform = this.options.platform ?? process.platform;
+        if (!this.available)
+            return { kind: 'unsupported', platform };
+        // Written to a directory of its own so the file cannot collide with
+        // another capture, and so one removal cleans up whatever was produced.
+        const directory = await mkdtemp(join(tmpdir(), 'dsh-telegram-shot-'));
+        const output = join(directory, 'screen.png');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        try {
+            await (this.options.run ?? captureWithScreencapture)(output, controller.signal);
+            const data = await readFile(output);
+            if (data.length === 0)
+                return { kind: 'failed', reason: 'the capture came back empty' };
+            return { kind: 'image', data, filename: 'screen.png' };
+        }
+        catch (error) {
+            return { kind: 'failed', reason: describe(error, controller.signal.aborted) };
+        }
+        finally {
+            clearTimeout(timer);
+            await rm(directory, { recursive: true, force: true }).catch((error) => {
+                this.logger.warn('[dsh-telegram] could not remove a screenshot', error);
+            });
+        }
+    }
+}
+/** Drive macOS's own `screencapture`. */
+function captureWithScreencapture(output, signal) {
+    return new Promise((resolve, reject) => {
+        // -x is silent: a bot taking a picture should not play the camera sound at
+        // whoever is sitting there. -C includes the cursor, which is often the
+        // point when someone asks what is on screen.
+        execFile('/usr/sbin/screencapture', ['-x', '-C', output], { signal }, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+/** Turn whatever went wrong into something a person can act on. */
+function describe(error, timedOut) {
+    if (timedOut)
+        return 'the capture took too long';
+    const message = error instanceof Error ? error.message : String(error);
+    if (/ENOENT/.test(message))
+        return 'no screen capture tool was found';
+    // The permission case does not fail loudly on macOS — it quietly returns the
+    // desktop picture — so this covers the version that does.
+    if (/not permitted|denied/i.test(message)) {
+        return 'the harness has no Screen Recording permission';
+    }
+    return message;
+}
+//# sourceMappingURL=screenshot.js.map

package/lib/media/screenshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../../src/media/screenshot.ts"],"names":[],"mappings":"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"}

package/lib/media/vision.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Asking whether the model can look at a picture before sending it one.
+ *
+ * A model that takes no image input rejects the whole request, so an
+ * unchecked screenshot does not degrade — it fails the turn, and the user is
+ * told their model "does not accept image input" by a layer that knows nothing
+ * about Telegram or about what they were trying to do.
+ *
+ * The harness already publishes the answer: every model carries
+ * `inputModalities`, defaulting to text alone. Reading it first turns a failed
+ * turn into a sentence naming the models that would have worked.
+ *
+ * The check is best-effort in one direction only. A definite "no" refuses the
+ * image; anything else — the catalog is unreachable, the model is unknown —
+ * sends it and lets the provider be the authority, because a check that cannot
+ * answer must not remove a capability the model may well have.
+ */
+/** What the harness knows about one model. */
+export interface ModelInfo {
+    readonly id: string;
+    readonly name?: string;
+    readonly inputModalities?: readonly string[];
+}
+/** The `ctx.llm` surface this needs. */
+export interface ModelCatalog {
+    resolveModelInfo(provider: string, model: string): Promise<ModelInfo>;
+    listModels(provider: string): Promise<readonly ModelInfo[]>;
+}
+/** The route a conversation's agent is running on. */
+export interface ModelRoute {
+    readonly provider: string;
+    readonly model: string;
+}
+/** Whether a model declares image input. */
+export declare function acceptsImages(info: ModelInfo | undefined): boolean;
+export declare class VisionCheck {
+    private readonly catalog;
+    /** The route in force right now, read late so a model change is picked up. */
+    private readonly route;
+    constructor(catalog: ModelCatalog, 
+    /** The route in force right now, read late so a model change is picked up. */
+    route: () => ModelRoute | undefined);
+    /**
+     * Whether an image may be sent on the current route.
+     *
+     * @returns `'yes'` when the model declares image input, `'no'` when it
+     *   definitely does not, and `'unknown'` when the catalog could not say —
+     *   in which case the caller should send and let the provider decide.
+     */
+    verdict(): Promise<'yes' | 'no' | 'unknown'>;
+    /**
+     * Models on the current provider that would accept the image.
+     *
+     * @returns their display names, or an empty list when none or unknown.
+     */
+    alternatives(): Promise<string[]>;
+    /** The model an image would have been sent to, for naming it in a message. */
+    currentModel(): string | undefined;
+}
+//# sourceMappingURL=vision.d.ts.map

package/lib/media/vision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../../src/media/vision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7C;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IACrE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAA;CAC5D;AAED,sDAAsD;AACtD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,4CAA4C;AAC5C,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAElE;AAED,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAFL,OAAO,EAAE,YAAY;IACtC,8EAA8E;IAC7D,KAAK,EAAE,MAAM,UAAU,GAAG,SAAS;IAGtD;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;IAalD;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAYvC,8EAA8E;IAC9E,YAAY,IAAI,MAAM,GAAG,SAAS;CAGnC"}

package/lib/media/vision.js

@@ -0,0 +1,74 @@
+/**
+ * Asking whether the model can look at a picture before sending it one.
+ *
+ * A model that takes no image input rejects the whole request, so an
+ * unchecked screenshot does not degrade — it fails the turn, and the user is
+ * told their model "does not accept image input" by a layer that knows nothing
+ * about Telegram or about what they were trying to do.
+ *
+ * The harness already publishes the answer: every model carries
+ * `inputModalities`, defaulting to text alone. Reading it first turns a failed
+ * turn into a sentence naming the models that would have worked.
+ *
+ * The check is best-effort in one direction only. A definite "no" refuses the
+ * image; anything else — the catalog is unreachable, the model is unknown —
+ * sends it and lets the provider be the authority, because a check that cannot
+ * answer must not remove a capability the model may well have.
+ */
+/** Whether a model declares image input. */
+export function acceptsImages(info) {
+    return info?.inputModalities?.includes('image') === true;
+}
+export class VisionCheck {
+    catalog;
+    route;
+    constructor(catalog, 
+    /** The route in force right now, read late so a model change is picked up. */
+    route) {
+        this.catalog = catalog;
+        this.route = route;
+    }
+    /**
+     * Whether an image may be sent on the current route.
+     *
+     * @returns `'yes'` when the model declares image input, `'no'` when it
+     *   definitely does not, and `'unknown'` when the catalog could not say —
+     *   in which case the caller should send and let the provider decide.
+     */
+    async verdict() {
+        const route = this.route();
+        if (!route)
+            return 'unknown';
+        try {
+            const info = await this.catalog.resolveModelInfo(route.provider, route.model);
+            if (info.inputModalities === undefined)
+                return 'unknown';
+            return acceptsImages(info) ? 'yes' : 'no';
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    /**
+     * Models on the current provider that would accept the image.
+     *
+     * @returns their display names, or an empty list when none or unknown.
+     */
+    async alternatives() {
+        const route = this.route();
+        if (!route)
+            return [];
+        try {
+            const models = await this.catalog.listModels(route.provider);
+            return models.filter(acceptsImages).map((model) => model.name ?? model.id);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** The model an image would have been sent to, for naming it in a message. */
+    currentModel() {
+        return this.route()?.model;
+    }
+}
+//# sourceMappingURL=vision.js.map

package/lib/media/vision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.js","sourceRoot":"","sources":["../../src/media/vision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAqBH,4CAA4C;AAC5C,MAAM,UAAU,aAAa,CAAC,IAA2B;IACvD,OAAO,IAAI,EAAE,eAAe,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;AAC1D,CAAC;AAED,MAAM,OAAO,WAAW;IAEH;IAEA;IAHnB,YACmB,OAAqB;IACtC,8EAA8E;IAC7D,KAAmC;QAFnC,YAAO,GAAP,OAAO,CAAc;QAErB,UAAK,GAAL,KAAK,CAA8B;IACnD,CAAC;IAEJ;;;;;;OAMG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAA;QAC1B,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAA;QAE5B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;YAC7E,IAAI,IAAI,CAAC,eAAe,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAA;YACxD,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAA;QAC1B,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAA;QAErB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;YAC5D,OAAO,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC,CAAA;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAA;QACX,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,YAAY;QACV,OAAO,IAAI,CAAC,KAAK,EAAE,EAAE,KAAK,CAAA;IAC5B,CAAC;CACF"}

package/lib/render/clamp.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Keeping the plugin's own prompts inside Telegram's message limit.
+ *
+ * Agent replies go out as rich messages and get 32768 characters. The prompts
+ * this plugin assembles — an approval, a question, a status line — stay on
+ * plain HTML and get 4096, and they embed model-authored text of no fixed
+ * length: a tool's stated reason, a question's option descriptions.
+ *
+ * Left unbounded, a verbose reason pushes the message past the limit, the send
+ * fails, and the approval fails closed — the agent is refused permission it
+ * was never actually asked about, and nobody sees a button. Bounding the
+ * inputs is what keeps that from being possible.
+ *
+ * Escaping is the subtlety: `&` becomes `&`, so escaped text can be five
+ * times longer than its source. Cutting after escaping risks splitting an
+ * entity, so the text is cut first and escaped afterwards, shrinking until the
+ * escaped form fits.
+ */
+/**
+ * Escape text, cutting it down until the escaped form fits.
+ *
+ * @param text - raw, possibly model-authored text.
+ * @param maxEscaped - the budget in characters of the escaped result.
+ * @returns escaped html no longer than `maxEscaped`.
+ */
+export declare function escapeWithin(text: string, maxEscaped: number): string;
+/**
+ * Cut raw text to a length, on a word boundary where one is close by.
+ *
+ * @param text - the raw text.
+ * @param max - maximum characters.
+ */
+export declare function clamp(text: string, max: number): string;
+//# sourceMappingURL=clamp.d.ts.map

package/lib/render/clamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clamp.d.ts","sourceRoot":"","sources":["../../src/render/clamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAkBrE;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGvD"}

package/lib/render/clamp.js

@@ -0,0 +1,65 @@
+/**
+ * Keeping the plugin's own prompts inside Telegram's message limit.
+ *
+ * Agent replies go out as rich messages and get 32768 characters. The prompts
+ * this plugin assembles — an approval, a question, a status line — stay on
+ * plain HTML and get 4096, and they embed model-authored text of no fixed
+ * length: a tool's stated reason, a question's option descriptions.
+ *
+ * Left unbounded, a verbose reason pushes the message past the limit, the send
+ * fails, and the approval fails closed — the agent is refused permission it
+ * was never actually asked about, and nobody sees a button. Bounding the
+ * inputs is what keeps that from being possible.
+ *
+ * Escaping is the subtlety: `&` becomes `&`, so escaped text can be five
+ * times longer than its source. Cutting after escaping risks splitting an
+ * entity, so the text is cut first and escaped afterwards, shrinking until the
+ * escaped form fits.
+ */
+import { escapeHtml } from './escape.js';
+/** Marker showing the reader that text was cut. */
+const ELLIPSIS = '…';
+/**
+ * Escape text, cutting it down until the escaped form fits.
+ *
+ * @param text - raw, possibly model-authored text.
+ * @param maxEscaped - the budget in characters of the escaped result.
+ * @returns escaped html no longer than `maxEscaped`.
+ */
+export function escapeWithin(text, maxEscaped) {
+    if (maxEscaped <= 0)
+        return '';
+    const escaped = escapeHtml(text);
+    if (escaped.length <= maxEscaped)
+        return escaped;
+    // Shrink proportionally rather than character by character: escaping expands
+    // by a factor, so one or two passes converge where a linear walk would take
+    // thousands.
+    let cut = text;
+    for (let attempt = 0; attempt < 8 && cut.length > 1; attempt += 1) {
+        const current = escapeHtml(cut);
+        if (current.length <= maxEscaped - ELLIPSIS.length)
+            break;
+        const ratio = (maxEscaped - ELLIPSIS.length) / current.length;
+        cut = cut.slice(0, Math.max(1, Math.floor(cut.length * ratio) - 1));
+    }
+    return `${escapeHtml(trimTail(cut))}${ELLIPSIS}`;
+}
+/**
+ * Cut raw text to a length, on a word boundary where one is close by.
+ *
+ * @param text - the raw text.
+ * @param max - maximum characters.
+ */
+export function clamp(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${trimTail(text.slice(0, Math.max(1, max - ELLIPSIS.length)))}${ELLIPSIS}`;
+}
+/** Drop a partial trailing word and any whitespace before the marker. */
+function trimTail(text) {
+    const lastSpace = text.lastIndexOf(' ');
+    const trimmed = lastSpace > text.length * 0.6 ? text.slice(0, lastSpace) : text;
+    return trimmed.trimEnd();
+}
+//# sourceMappingURL=clamp.js.map

package/lib/render/clamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clamp.js","sourceRoot":"","sources":["../../src/render/clamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,mDAAmD;AACnD,MAAM,QAAQ,GAAG,GAAG,CAAA;AAEpB;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,UAAkB;IAC3D,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,EAAE,CAAA;IAE9B,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,CAAA;IAChC,IAAI,OAAO,CAAC,MAAM,IAAI,UAAU;QAAE,OAAO,OAAO,CAAA;IAEhD,6EAA6E;IAC7E,4EAA4E;IAC5E,aAAa;IACb,IAAI,GAAG,GAAG,IAAI,CAAA;IACd,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QAClE,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;QAC/B,IAAI,OAAO,CAAC,MAAM,IAAI,UAAU,GAAG,QAAQ,CAAC,MAAM;YAAE,MAAK;QACzD,MAAM,KAAK,GAAG,CAAC,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAA;QAC7D,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACrE,CAAC;IAED,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAA;AAClD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,GAAW;IAC7C,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,IAAI,CAAA;IACnC,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAA;AACpF,CAAC;AAED,yEAAyE;AACzE,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;IACvC,MAAM,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC/E,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;AAC1B,CAAC"}

package/lib/render/escape.d.ts

@@ -0,0 +1,15 @@
+/**
+ * HTML escaping for the plugin's own messages.
+ *
+ * Agent replies are sent as rich markdown for Telegram to render, but the
+ * prompts this plugin writes itself — questions, approvals, command answers —
+ * stay on HTML: they are short, they carry inline keyboards, and they embed
+ * model-authored text that must not be able to introduce markup.
+ *
+ * Telegram's HTML mode is not a browser: it recognises a fixed tag whitelist
+ * and treats everything else as text. Only `&`, `<` and `>` can start markup,
+ * so those are the only three characters that must be escaped.
+ */
+/** Escape text content so Telegram reads it as text, never as markup. */
+export declare function escapeHtml(text: string): string;
+//# sourceMappingURL=escape.d.ts.map

package/lib/render/escape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.d.ts","sourceRoot":"","sources":["../../src/render/escape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/lib/render/escape.js

@@ -0,0 +1,17 @@
+/**
+ * HTML escaping for the plugin's own messages.
+ *
+ * Agent replies are sent as rich markdown for Telegram to render, but the
+ * prompts this plugin writes itself — questions, approvals, command answers —
+ * stay on HTML: they are short, they carry inline keyboards, and they embed
+ * model-authored text that must not be able to introduce markup.
+ *
+ * Telegram's HTML mode is not a browser: it recognises a fixed tag whitelist
+ * and treats everything else as text. Only `&`, `<` and `>` can start markup,
+ * so those are the only three characters that must be escaped.
+ */
+/** Escape text content so Telegram reads it as text, never as markup. */
+export function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+//# sourceMappingURL=escape.js.map

package/lib/render/escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.js","sourceRoot":"","sources":["../../src/render/escape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AAChF,CAAC"}

package/lib/reply/activity.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Saying what the agent is doing right now.
+ *
+ * A turn that spends two minutes running tests emits no text, so the reply
+ * shows a placeholder and nothing else — from the outside that is
+ * indistinguishable from a bot that has died. The tool calls are already in
+ * the session feed; they were simply being dropped.
+ *
+ * What is shown is deliberately one short line. A tool call's arguments can be
+ * an entire file, and the point is reassurance, not a transcript: the finished
+ * reply carries the substance, and this disappears when the turn ends.
+ */
+/**
+ * Describe one tool call in a line.
+ *
+ * @param name - the tool the model invoked.
+ * @param argumentsJson - the raw arguments string, exactly as the model wrote
+ *   it, which means it may be incomplete or not be JSON at all.
+ * @returns a short line, already escaped for the markup it is placed in.
+ */
+export declare function describeToolCall(name: string, argumentsJson: string | undefined): string;
+/**
+ * Wrap an activity line in the block Telegram shows as "thinking".
+ *
+ * The tag is valid in rich markdown and rich HTML alike, and is accepted only
+ * in a draft — which is exactly its lifetime here.
+ *
+ * @param activity - the escaped line, or undefined to show nothing.
+ */
+export declare function thinkingBlock(activity: string | undefined): string;
+//# sourceMappingURL=activity.d.ts.map

package/lib/reply/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../src/reply/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIxF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGlE"}

package/lib/reply/activity.js

@@ -0,0 +1,88 @@
+/**
+ * Saying what the agent is doing right now.
+ *
+ * A turn that spends two minutes running tests emits no text, so the reply
+ * shows a placeholder and nothing else — from the outside that is
+ * indistinguishable from a bot that has died. The tool calls are already in
+ * the session feed; they were simply being dropped.
+ *
+ * What is shown is deliberately one short line. A tool call's arguments can be
+ * an entire file, and the point is reassurance, not a transcript: the finished
+ * reply carries the substance, and this disappears when the turn ends.
+ */
+import { escapeHtml } from '../render/escape.js';
+/** Longest activity line shown; a command can be arbitrarily long. */
+const MAX_DETAIL = 80;
+/**
+ * Argument fields worth showing, in the order they are looked for.
+ *
+ * A tool's most identifying argument is almost always one of these, and
+ * guessing from the first key present beats rendering the whole JSON.
+ */
+const DETAIL_KEYS = [
+    'command',
+    'cmd',
+    'file_path',
+    'path',
+    'filePath',
+    'pattern',
+    'query',
+    'url',
+    'description',
+    'name',
+];
+/**
+ * Describe one tool call in a line.
+ *
+ * @param name - the tool the model invoked.
+ * @param argumentsJson - the raw arguments string, exactly as the model wrote
+ *   it, which means it may be incomplete or not be JSON at all.
+ * @returns a short line, already escaped for the markup it is placed in.
+ */
+export function describeToolCall(name, argumentsJson) {
+    const detail = firstDetail(argumentsJson);
+    const label = detail === undefined ? name : `${name}: ${detail}`;
+    return escapeHtml(clip(label, MAX_DETAIL));
+}
+/**
+ * Wrap an activity line in the block Telegram shows as "thinking".
+ *
+ * The tag is valid in rich markdown and rich HTML alike, and is accepted only
+ * in a draft — which is exactly its lifetime here.
+ *
+ * @param activity - the escaped line, or undefined to show nothing.
+ */
+export function thinkingBlock(activity) {
+    if (activity === undefined || activity === '')
+        return '';
+    return `<tg-thinking>${activity}</tg-thinking>`;
+}
+/** The first recognisable argument, or undefined when none can be read. */
+function firstDetail(argumentsJson) {
+    if (!argumentsJson)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(argumentsJson);
+    }
+    catch {
+        // Arguments stream in, so mid-call they are routinely incomplete JSON.
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    for (const key of DETAIL_KEYS) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim() !== '')
+            return value.trim().split('\n')[0];
+    }
+    return undefined;
+}
+/** Cut a line to length, marking that it was cut. */
+function clip(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1)}…`;
+}
+//# sourceMappingURL=activity.js.map

package/lib/reply/activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.js","sourceRoot":"","sources":["../../src/reply/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEhD,sEAAsE;AACtE,MAAM,UAAU,GAAG,EAAE,CAAA;AAErB;;;;;GAKG;AACH,MAAM,WAAW,GAAG;IAClB,SAAS;IACT,KAAK;IACL,WAAW;IACX,MAAM;IACN,UAAU;IACV,SAAS;IACT,OAAO;IACP,KAAK;IACL,aAAa;IACb,MAAM;CACE,CAAA;AAEV;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,aAAiC;IAC9E,MAAM,MAAM,GAAG,WAAW,CAAC,aAAa,CAAC,CAAA;IACzC,MAAM,KAAK,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,MAAM,EAAE,CAAA;IAChE,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAA;AAC5C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,QAA4B;IACxD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,EAAE,CAAA;IACxD,OAAO,gBAAgB,QAAQ,gBAAgB,CAAA;AACjD,CAAC;AAED,2EAA2E;AAC3E,SAAS,WAAW,CAAC,aAAiC;IACpD,IAAI,CAAC,aAAa;QAAE,OAAO,SAAS,CAAA;IAEpC,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,CAAA;IACnE,MAAM,MAAM,GAAG,MAAiC,CAAA;IAEhD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;QACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1F,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,qDAAqD;AACrD,SAAS,IAAI,CAAC,IAAY,EAAE,GAAW;IACrC,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,IAAI,CAAA;IACnC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAA;AACrC,CAAC"}