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

package/lib/commands.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Slash commands.
+ *
+ * Telegram delivers a command as ordinary message text, and in a group it
+ * arrives addressed — `/new@my_bot` — because several bots may share the chat.
+ * Parsing is therefore a real step rather than a `startsWith`, and a command
+ * addressed to a different bot must be ignored rather than executed.
+ */
+/** A recognised command and the text that followed it. */
+export interface ParsedCommand {
+    /** Command name, lowercased, without the slash or the bot suffix. */
+    readonly name: string;
+    /** Everything after the command, trimmed; empty when there was nothing. */
+    readonly args: string;
+}
+/** Commands the plugin answers, with the one-line help shown by `/help`. */
+export declare const COMMANDS: Readonly<Record<string, string>>;
+/**
+ * Parse a message as a command.
+ *
+ * @param text - the raw message text.
+ * @param botUsername - this bot's username, so `/cmd@other_bot` is ignored.
+ * @returns the command, or undefined when the text is not one for us.
+ */
+export declare function parseCommand(text: string, botUsername?: string): ParsedCommand | undefined;
+/**
+ * The command menu to publish, for the list Telegram shows on `/`.
+ *
+ * `/claim` is left out once the bot has an owner: it is the one command that
+ * stops working the moment it succeeds, and offering it forever invites
+ * everyone who opens the chat to try a code that can no longer be right.
+ *
+ * @param claimable - whether the bot is still waiting to be claimed.
+ * @returns entries in menu order, descriptions clipped to Telegram's limit.
+ */
+export declare function commandMenu(claimable: boolean): {
+    command: string;
+    description: string;
+}[];
+/**
+ * The `/help` body, rendered as Telegram HTML.
+ *
+ * The descriptions are prose, not markup, so they are escaped on the way in.
+ * `/claim <code>` is the reason: sent raw with `parse_mode: HTML`, Telegram
+ * read `<code>` as an unclosed tag and rejected the WHOLE message with a 400 —
+ * so `/help` answered with silence, which reads as a dead bot rather than as a
+ * malformed message. Escaping here means a description added later cannot do
+ * it again.
+ */
+export declare function helpText(): string;
+//# sourceMappingURL=commands.d.ts.map

package/lib/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAKD,4EAA4E;AAC5E,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBrD,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAa1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,CAO1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAKjC"}

package/lib/commands.js

@@ -0,0 +1,83 @@
+/**
+ * Slash commands.
+ *
+ * Telegram delivers a command as ordinary message text, and in a group it
+ * arrives addressed — `/new@my_bot` — because several bots may share the chat.
+ * Parsing is therefore a real step rather than a `startsWith`, and a command
+ * addressed to a different bot must be ignored rather than executed.
+ */
+import { escapeHtml } from './render/escape.js';
+/** Telegram refuses a menu description longer than this. */
+const MAX_MENU_DESCRIPTION = 256;
+/** Commands the plugin answers, with the one-line help shown by `/help`. */
+export const COMMANDS = {
+    start: 'Show what this bot is and whether you may use it',
+    help: 'List the commands',
+    claim: 'Take ownership of an unclaimed bot: /claim <code>',
+    new: 'Start a fresh conversation, forgetting the current one',
+    cd: 'Show or change the working directory: /cd ~/projects/app',
+    model: 'Show or change the model: /model list, or /model provider/model',
+    effort: 'Show or change the reasoning effort: /effort high',
+    vision: 'Show or change the model that reads images: /vision off',
+    permission: 'Show or change what the agent may do: /permission read-only',
+    diag: 'Show what the plugin can see about itself, and recent failures',
+    screenshot: "Send a picture of the harness machine's screen",
+    sessions: 'Pick up an earlier conversation from this chat',
+    status: 'Show the session, working directory, and who owns the bot',
+    stop: 'Cancel whatever the agent is doing right now',
+    whoami: 'Show your Telegram user id',
+};
+/**
+ * Parse a message as a command.
+ *
+ * @param text - the raw message text.
+ * @param botUsername - this bot's username, so `/cmd@other_bot` is ignored.
+ * @returns the command, or undefined when the text is not one for us.
+ */
+export function parseCommand(text, botUsername) {
+    const match = /^\/([a-z0-9_]+)(?:@([a-z0-9_]+))?(?:\s+([\s\S]*))?$/i.exec(text.trim());
+    if (!match)
+        return undefined;
+    const addressed = match[2];
+    if (addressed !== undefined && botUsername !== undefined) {
+        if (addressed.toLowerCase() !== botUsername.toLowerCase())
+            return undefined;
+    }
+    const name = match[1].toLowerCase();
+    if (!(name in COMMANDS))
+        return undefined;
+    return { name, args: (match[3] ?? '').trim() };
+}
+/**
+ * The command menu to publish, for the list Telegram shows on `/`.
+ *
+ * `/claim` is left out once the bot has an owner: it is the one command that
+ * stops working the moment it succeeds, and offering it forever invites
+ * everyone who opens the chat to try a code that can no longer be right.
+ *
+ * @param claimable - whether the bot is still waiting to be claimed.
+ * @returns entries in menu order, descriptions clipped to Telegram's limit.
+ */
+export function commandMenu(claimable) {
+    return Object.entries(COMMANDS)
+        .filter(([name]) => claimable || name !== 'claim')
+        .map(([command, description]) => ({
+        command,
+        description: description.slice(0, MAX_MENU_DESCRIPTION),
+    }));
+}
+/**
+ * The `/help` body, rendered as Telegram HTML.
+ *
+ * The descriptions are prose, not markup, so they are escaped on the way in.
+ * `/claim <code>` is the reason: sent raw with `parse_mode: HTML`, Telegram
+ * read `<code>` as an unclosed tag and rejected the WHOLE message with a 400 —
+ * so `/help` answered with silence, which reads as a dead bot rather than as a
+ * malformed message. Escaping here means a description added later cannot do
+ * it again.
+ */
+export function helpText() {
+    const lines = Object.entries(COMMANDS).map(([name, description]) => `/${name} — ${escapeHtml(description)}`);
+    return `<b>Commands</b>\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=commands.js.map

package/lib/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAU/C,4DAA4D;AAC5D,MAAM,oBAAoB,GAAG,GAAG,CAAA;AAEhC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,QAAQ,GAAqC;IACxD,KAAK,EAAE,kDAAkD;IACzD,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,mDAAmD;IAC1D,GAAG,EAAE,wDAAwD;IAC7D,EAAE,EAAE,0DAA0D;IAC9D,KAAK,EAAE,iEAAiE;IACxE,MAAM,EAAE,mDAAmD;IAC3D,MAAM,EAAE,yDAAyD;IACjE,UAAU,EAAE,6DAA6D;IACzE,IAAI,EAAE,gEAAgE;IACtE,UAAU,EAAE,gDAAgD;IAC5D,QAAQ,EAAE,gDAAgD;IAC1D,MAAM,EAAE,2DAA2D;IACnE,IAAI,EAAE,8CAA8C;IACpD,MAAM,EAAE,4BAA4B;CACrC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,WAAoB;IAC7D,MAAM,KAAK,GAAG,sDAAsD,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;IACtF,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAE5B,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;IAC1B,IAAI,SAAS,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QACzD,IAAI,SAAS,CAAC,WAAW,EAAE,KAAK,WAAW,CAAC,WAAW,EAAE;YAAE,OAAO,SAAS,CAAA;IAC7E,CAAC;IAED,MAAM,IAAI,GAAI,KAAK,CAAC,CAAC,CAAY,CAAC,WAAW,EAAE,CAAA;IAC/C,IAAI,CAAC,CAAC,IAAI,IAAI,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAA;IAEzC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAA;AAChD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,SAAkB;IAC5C,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;SAC5B,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,SAAS,IAAI,IAAI,KAAK,OAAO,CAAC;SACjD,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC;QAChC,OAAO;QACP,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC;KACxD,CAAC,CAAC,CAAA;AACP,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CACxC,CAAC,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,MAAM,UAAU,CAAC,WAAW,CAAC,EAAE,CACjE,CAAA;IACD,OAAO,oBAAoB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;AAC/C,CAAC"}

package/lib/config.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Plugin configuration.
+ *
+ * The bot token is deliberately absent. Configuration carries a *reference* to
+ * the credential (`tokenRef`), and the value lives with the harness credential
+ * provider — so a profile config stays safe to read, sync, and show in a UI,
+ * and rotating the token touches no file here.
+ */
+import Schema from '@deepseek-ai/schemastery';
+/** Default credential reference for the bot token. */
+export declare const DEFAULT_TOKEN_REF = "TELEGRAM_BOT_TOKEN";
+export declare const Config: Schema<Schemastery.ObjectS<{
+    enabled: Schema<boolean, boolean>;
+    tokenRef: Schema<string, string>;
+    baseUrl: Schema<string, string>;
+    allowFrom: Schema<number[], number[]>;
+    cwd: Schema<string, string>;
+    timeoutMs: Schema<number, number>;
+    longPollSeconds: Schema<number, number>;
+    streaming: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+        throttleMs: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+        throttleMs: Schema<number, number>;
+    }>>;
+    media: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+        maxBytes: Schema<number, number>;
+        maxTextChars: Schema<number, number>;
+        ocr: Schema<Schemastery.ObjectS<{
+            enabled: Schema<boolean, boolean>;
+            languages: Schema<string, string>;
+        }>, Schemastery.ObjectT<{
+            enabled: Schema<boolean, boolean>;
+            languages: Schema<string, string>;
+        }>>;
+        visionModel: Schema<string, string>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+        maxBytes: Schema<number, number>;
+        maxTextChars: Schema<number, number>;
+        ocr: Schema<Schemastery.ObjectS<{
+            enabled: Schema<boolean, boolean>;
+            languages: Schema<string, string>;
+        }>, Schemastery.ObjectT<{
+            enabled: Schema<boolean, boolean>;
+            languages: Schema<string, string>;
+        }>>;
+        visionModel: Schema<string, string>;
+    }>>;
+    agentPreset: Schema<string, string>;
+    requireMentionInGroups: Schema<boolean, boolean>;
+    permissionPreset: Schema<string, string>;
+    screenshot: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+    }>>;
+    reconnect: Schema<Schemastery.ObjectS<{
+        baseDelayMs: Schema<number, number>;
+        maxDelayMs: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+        baseDelayMs: Schema<number, number>;
+        maxDelayMs: Schema<number, number>;
+    }>>;
+}>, Schemastery.ObjectT<{
+    enabled: Schema<boolean, boolean>;
+    tokenRef: Schema<string, string>;
+    baseUrl: Schema<string, string>;
+    allowFrom: Schema<number[], number[]>;
+    cwd: Schema<string, string>;
+    timeoutMs: Schema<number, number>;
+    longPollSeconds: Schema<number, number>;
+    streaming: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+        throttleMs: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+        throttleMs: Schema<number, number>;
+    }>>;
+    media: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+        maxBytes: Schema<number, number>;
+        maxTextChars: Schema<number, number>;
+        ocr: Schema<Schemastery.ObjectS<{
+            enabled: Schema<boolean, boolean>;
+            languages: Schema<string, string>;
+        }>, Schemastery.ObjectT<{
+            enabled: Schema<boolean, boolean>;
+            languages: Schema<string, string>;
+        }>>;
+        visionModel: Schema<string, string>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+        maxBytes: Schema<number, number>;
+        maxTextChars: Schema<number, number>;
+        ocr: Schema<Schemastery.ObjectS<{
+            enabled: Schema<boolean, boolean>;
+            languages: Schema<string, string>;
+        }>, Schemastery.ObjectT<{
+            enabled: Schema<boolean, boolean>;
+            languages: Schema<string, string>;
+        }>>;
+        visionModel: Schema<string, string>;
+    }>>;
+    agentPreset: Schema<string, string>;
+    requireMentionInGroups: Schema<boolean, boolean>;
+    permissionPreset: Schema<string, string>;
+    screenshot: Schema<Schemastery.ObjectS<{
+        enabled: Schema<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        enabled: Schema<boolean, boolean>;
+    }>>;
+    reconnect: Schema<Schemastery.ObjectS<{
+        baseDelayMs: Schema<number, number>;
+        maxDelayMs: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+        baseDelayMs: Schema<number, number>;
+        maxDelayMs: Schema<number, number>;
+    }>>;
+}>>;
+/** Resolved plugin configuration. */
+export type TelegramConfig = ReturnType<typeof Config>;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAE7C,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,uBAAuB,CAAA;AAErD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoHjB,CAAA;AAEF,qCAAqC;AACrC,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAA"}

package/lib/config.js

@@ -0,0 +1,97 @@
+/**
+ * Plugin configuration.
+ *
+ * The bot token is deliberately absent. Configuration carries a *reference* to
+ * the credential (`tokenRef`), and the value lives with the harness credential
+ * provider — so a profile config stays safe to read, sync, and show in a UI,
+ * and rotating the token touches no file here.
+ */
+import Schema from '@deepseek-ai/schemastery';
+/** Default credential reference for the bot token. */
+export const DEFAULT_TOKEN_REF = 'TELEGRAM_BOT_TOKEN';
+export const Config = Schema.object({
+    enabled: Schema.boolean()
+        .default(true)
+        .description('Whether the Telegram connection starts with the harness.'),
+    tokenRef: Schema.string()
+        .default(DEFAULT_TOKEN_REF)
+        .description('Credential reference holding the bot token — never the token itself.'),
+    baseUrl: Schema.string()
+        .default('https://api.telegram.org')
+        .description('Bot API origin; change it only for a local proxy.'),
+    allowFrom: Schema.array(Schema.number())
+        .default([])
+        .description('Telegram user ids allowed to drive the agent. Leave empty to claim the bot once with /claim.'),
+    cwd: Schema.string().description('Working directory new conversations start in. Defaults to the harness working directory.'),
+    timeoutMs: Schema.natural().default(30_000).description('Per-request Bot API timeout.'),
+    longPollSeconds: Schema.natural()
+        .default(25)
+        .description('How long Telegram holds an empty poll open.'),
+    streaming: Schema.object({
+        enabled: Schema.boolean()
+            .default(true)
+            .description('Edit one message as the answer streams, instead of sending it once at the end.'),
+        throttleMs: Schema.natural()
+            .default(1200)
+            .description('Minimum gap between edits; Telegram rate-limits rapid edits to one chat.'),
+    }),
+    media: Schema.object({
+        enabled: Schema.boolean()
+            .default(true)
+            .description('Read images and text files the user sends.'),
+        maxBytes: Schema.natural()
+            .default(20 * 1024 * 1024)
+            .description('Refuse anything larger. Telegram caps bot downloads at 20 MB.'),
+        maxTextChars: Schema.natural()
+            .default(60_000)
+            .description('Truncate an inlined text file to this many characters.'),
+        ocr: Schema.object({
+            enabled: Schema.boolean()
+                .default(true)
+                .description('Read an image\'s text with tesseract when no vision model is ' +
+                'configured, or when the one configured could not be reached. Does ' +
+                'nothing unless tesseract is installed, which no operating system ' +
+                'does by default. It reads text and does not see: a diagram or a ' +
+                'chart comes back as scattered words.'),
+            languages: Schema.string()
+                .default('eng')
+                .description('Languages to read, as tesseract names them; join several with +, ' +
+                'as in eng+ind. Only languages installed on this machine work — ' +
+                '`tesseract --list-langs` says which.'),
+        }),
+        visionModel: Schema.string()
+            .default('')
+            .description('Model that reads an image, as provider/model. The picture goes to a ' +
+            'session of its own there and only what it says joins the conversation. ' +
+            'Empty sends the image to the conversation itself, which must then accept it.'),
+    }),
+    agentPreset: Schema.string()
+        .default('')
+        .description('Agent preset Telegram conversations are composed from — the roster in ' +
+        'Settings owns the list. Empty takes the deployment default. The preset ' +
+        'is what supplies the tools, so this decides what the agent can do.'),
+    requireMentionInGroups: Schema.boolean()
+        .default(true)
+        .description('In a group, answer only when the bot is @mentioned or replied to. Off ' +
+        'answers every message from an allowed user, which is rarely wanted in ' +
+        'a room where people also talk to each other. Private chats are never ' +
+        'affected.'),
+    permissionPreset: Schema.string()
+        .default('')
+        .description('Permission preset Telegram conversations run under — one of the names ' +
+        'the deployment defines. Empty follows the deployment default. A preset ' +
+        'whose approval policy asks is what makes the approval buttons appear.'),
+    screenshot: Schema.object({
+        enabled: Schema.boolean()
+            .default(false)
+            .description('Allow /screenshot. Off by default: a screen holds whatever happens to ' +
+            'be on it, and this is the one thing here that sends the machine\'s ' +
+            'own contents outward without the agent being involved. macOS also ' +
+            'needs Screen Recording permission for the harness process.'),
+    }),
+    reconnect: Schema.object({
+        baseDelayMs: Schema.natural().default(1000).description('First reconnect delay.'),
+        maxDelayMs: Schema.natural().default(30_000).description('Longest reconnect delay.'),
+    }),
+});
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

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

package/lib/diagnostics.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A status file, because the log is not always readable.
+ *
+ * `ctx.logger` reaches whatever sink the deployment composed — and several
+ * profiles compose none, so a plugin that only logs its failures is silent
+ * about them. That is how a bot ends up not answering with nothing anywhere
+ * to say why: the token was missing, or Telegram refused it, and the one line
+ * that said so went nowhere.
+ *
+ * So the plugin also writes what it is doing to a small JSON file beside its
+ * other state. It is written on every transition, is safe to read while the
+ * plugin runs, and never contains the token.
+ */
+/** What the connection is doing right now. */
+export type ConnectionState = 
+/** Loaded but deliberately not connecting: disabled, or no token yet. */
+'idle'
+/** Opening: verifying the token and clearing any webhook. */
+ | 'connecting'
+/** Long-polling for updates. */
+ | 'connected'
+/** Stopped by an error; `detail` says which. */
+ | 'failed';
+/** One published status. */
+export interface StatusSnapshot {
+    readonly state: ConnectionState;
+    /** The bot's @username, once known. */
+    readonly bot?: string;
+    /** Why, for the states that need a why. Never contains the token. */
+    readonly detail?: string;
+    /** When this was written, ISO-8601. */
+    readonly updatedAt: string;
+}
+/** Publishes the connection's state where a person can read it. */
+export declare class StatusFile {
+    private readonly file;
+    /** Strips the bot token from any text bound for the file. */
+    private readonly redact;
+    constructor(file: string, 
+    /** Strips the bot token from any text bound for the file. */
+    redact?: (text: string) => string);
+    /**
+     * Publish a state.
+     *
+     * Failures are swallowed: a plugin must not fall over because it could not
+     * write its own diagnostics.
+     *
+     * @param state - what the connection is doing.
+     * @param extra - the bot username and reason, where they apply.
+     */
+    publish(state: ConnectionState, extra?: {
+        bot?: string;
+        detail?: string | undefined;
+    }): Promise<void>;
+}
+/** Reduce any thrown value to one readable line. */
+export declare function describeError(error: unknown): string;
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,8CAA8C;AAC9C,MAAM,MAAM,eAAe;AACzB,yEAAyE;AACvE,MAAM;AACR,6DAA6D;GAC3D,YAAY;AACd,gCAAgC;GAC9B,WAAW;AACb,gDAAgD;GAC9C,QAAQ,CAAA;AAEZ,4BAA4B;AAC5B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,mEAAmE;AACnE,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,IAAI,EAAE,MAAM;IAC7B,6DAA6D;IAC5C,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAuB;IAGpE;;;;;;;;OAQG;IACG,OAAO,CACX,KAAK,EAAE,eAAe,EACtB,KAAK,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAO,GACxD,OAAO,CAAC,IAAI,CAAC;CAiBjB;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGpD"}

package/lib/diagnostics.js

@@ -0,0 +1,59 @@
+/**
+ * A status file, because the log is not always readable.
+ *
+ * `ctx.logger` reaches whatever sink the deployment composed — and several
+ * profiles compose none, so a plugin that only logs its failures is silent
+ * about them. That is how a bot ends up not answering with nothing anywhere
+ * to say why: the token was missing, or Telegram refused it, and the one line
+ * that said so went nowhere.
+ *
+ * So the plugin also writes what it is doing to a small JSON file beside its
+ * other state. It is written on every transition, is safe to read while the
+ * plugin runs, and never contains the token.
+ */
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** Publishes the connection's state where a person can read it. */
+export class StatusFile {
+    file;
+    redact;
+    constructor(file, 
+    /** Strips the bot token from any text bound for the file. */
+    redact = (text) => text) {
+        this.file = file;
+        this.redact = redact;
+    }
+    /**
+     * Publish a state.
+     *
+     * Failures are swallowed: a plugin must not fall over because it could not
+     * write its own diagnostics.
+     *
+     * @param state - what the connection is doing.
+     * @param extra - the bot username and reason, where they apply.
+     */
+    async publish(state, extra = {}) {
+        const snapshot = {
+            state,
+            ...(extra.bot !== undefined ? { bot: extra.bot } : {}),
+            ...(extra.detail !== undefined ? { detail: this.redact(extra.detail) } : {}),
+            updatedAt: new Date().toISOString(),
+        };
+        try {
+            const temporary = `${this.file}.${process.pid}.tmp`;
+            await mkdir(dirname(this.file), { recursive: true });
+            await writeFile(temporary, `${JSON.stringify(snapshot, undefined, 2)}\n`, 'utf8');
+            await rename(temporary, this.file);
+        }
+        catch {
+            // Diagnostics must never be the thing that breaks.
+        }
+    }
+}
+/** Reduce any thrown value to one readable line. */
+export function describeError(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+//# sourceMappingURL=diagnostics.js.map

package/lib/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAwBnC,mEAAmE;AACnE,MAAM,OAAO,UAAU;IAEF;IAEA;IAHnB,YACmB,IAAY;IAC7B,6DAA6D;IAC5C,SAAmC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI;QAFjD,SAAI,GAAJ,IAAI,CAAQ;QAEZ,WAAM,GAAN,MAAM,CAA2C;IACjE,CAAC;IAEJ;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,CACX,KAAsB,EACtB,QAAuD,EAAE;QAEzD,MAAM,QAAQ,GAAmB;YAC/B,KAAK;YACL,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtD,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5E,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAA;QAED,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAA;YACnD,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YACpD,MAAM,SAAS,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;YACjF,MAAM,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;QACrD,CAAC;IACH,CAAC;CACF;AAED,oDAAoD;AACpD,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC,OAAO,CAAA;IAChD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;AACtB,CAAC"}

package/lib/failures.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Keeping the last things that went wrong where somebody can see them.
+ *
+ * `ctx.logger` reaches whatever sink the deployment composed, and several
+ * profiles compose none. A plugin that only logs its failures is then silent
+ * about them: the status file says whether the connection is up, and nothing
+ * says that a screenshot failed, an attachment was refused, or a turn threw.
+ *
+ * That is not a hypothetical. Every fault found in this plugin so far was
+ * found by someone noticing odd behaviour in a chat and asking about it, not
+ * by reading a log — because there was no log to read.
+ *
+ * So warnings and errors are also kept here: a small ring in memory for
+ * `/diag`, and the same ring on disk for when the bot itself is too broken to
+ * answer a command.
+ */
+import type { Logger } from './harness/types.js';
+/** One thing that went wrong. */
+export interface Failure {
+    readonly at: string;
+    readonly level: 'warn' | 'error';
+    readonly message: string;
+}
+/** Construction options. */
+export interface FailureLogOptions {
+    /** Where to mirror the ring; absent keeps it in memory only. */
+    readonly file?: string;
+    /** Strips anything secret before it is written down. */
+    readonly redact?: (text: string) => string;
+    readonly keep?: number;
+    readonly flushMs?: number;
+    /** Injected so tests need no clock. */
+    readonly now?: () => Date;
+}
+export declare class FailureLog {
+    private readonly options;
+    private entries;
+    private timer;
+    private writing;
+    constructor(options?: FailureLogOptions);
+    /**
+     * Record one failure.
+     *
+     * @param level - how bad it was.
+     * @param message - what happened, already joined into one line.
+     */
+    record(level: 'warn' | 'error', message: string): void;
+    /** The failures kept, newest first. */
+    recent(): readonly Failure[];
+    /** Write now, whatever the batching timer was waiting for. */
+    flush(): Promise<void>;
+    /** Stop batching — the plugin is unloading. */
+    dispose(): void;
+    /** Arm the batching timer, unless one is already armed. */
+    private schedule;
+    /** Mirror the ring to disk, one write at a time. */
+    private persist;
+}
+/**
+ * A logger that also records what it warns and errors about.
+ *
+ * Wrapping rather than replacing: whatever sink the deployment composed still
+ * gets everything, and this only adds a copy of the parts worth looking back
+ * at. Debug and info are deliberately not kept — a ring of twenty filled with
+ * routine chatter would push out the one line that mattered.
+ *
+ * @param base - the harness logger.
+ * @param log - the ring to tee into.
+ */
+export declare function recordingLogger(base: Logger, log: FailureLog): Logger;
+//# sourceMappingURL=failures.d.ts.map

package/lib/failures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failures.d.ts","sourceRoot":"","sources":["../src/failures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAQhD,iCAAiC;AACjC,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,4BAA4B;AAC5B,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,uCAAuC;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAC1B;AAED,qBAAa,UAAU;IAKT,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,KAAK,CAA2C;IACxD,OAAO,CAAC,OAAO,CAAmC;gBAErB,OAAO,GAAE,iBAAsB;IAE5D;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAatD,uCAAuC;IACvC,MAAM,IAAI,SAAS,OAAO,EAAE;IAI5B,8DAA8D;IACxD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,+CAA+C;IAC/C,OAAO,IAAI,IAAI;IAKf,2DAA2D;IAC3D,OAAO,CAAC,QAAQ;IAYhB,oDAAoD;YACtC,OAAO;CAmBtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAgBrE"}