codeep 3.0.0 → 3.1.1

package/dist/utils/telegramInbox.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Starting work from the phone.
+ *
+ * Approval lets the phone answer a question the agent asked. This lets the
+ * phone ask one — which is a different thing, and a larger one. A chat that can
+ * only say Run, Skip or Cancel is bounded by what the agent already decided to
+ * do; a chat that can send a prompt is a keyboard attached to this machine.
+ * That is why it is off by default and has its own switch rather than riding on
+ * the approval one.
+ */
+import { type TelegramCredentials } from './telegramUpdates';
+/** Longest prompt accepted. Past this it is a paste, not an instruction. */
+export declare const MAX_PROMPT_LENGTH = 2000;
+/**
+ * How old a message may be and still run.
+ *
+ * Telegram keeps undelivered updates for 24 hours. Without this, a message
+ * typed at midnight to a machine that was switched off would be handed to the
+ * agent the moment the CLI next started — hours later, in a repository that has
+ * moved on, with nobody watching. A prompt is an instruction for now.
+ */
+export declare const MAX_MESSAGE_AGE_MS: number;
+export type PromptRejection = 'not-from-owner' | 'not-text' | 'empty' | 'too-long' | 'stale' | 'command';
+export type PromptResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: PromptRejection;
+};
+/**
+ * Whether a message update came from the one chat allowed to drive this agent.
+ *
+ * A bot's username is discoverable, so without this anyone who found it could
+ * type into somebody else's terminal. Mirrors the approval check deliberately:
+ * both gate the same machine, and they should not be able to disagree.
+ */
+export declare function messageFromOwner(message: unknown, chatID: string): boolean;
+/**
+ * Turn a Telegram message into a prompt, or say why it is not one.
+ *
+ * Returns a reason rather than null throughout: every rejection here has a
+ * different thing to tell the sender, and a bot that goes quiet is
+ * indistinguishable from one that is switched off.
+ */
+export declare function extractPrompt(message: unknown, chatID: string, now?: number): PromptResult;
+/** What to say back, so silence never has to be interpreted. */
+export declare function describeRejection(reason: PromptRejection): string | null;
+/**
+ * The one instruction waiting for the agent to be free.
+ *
+ * One slot, and a newer message replaces an older one. A queue that grows is a
+ * queue that runs things you have forgotten asking for: send two corrections
+ * while a run is busy and you meant the second, not both in order. Replacing
+ * says so out loud rather than quietly dropping either.
+ */
+export declare class InboxQueue {
+    private pending;
+    /** @returns whether this displaced an instruction that had not run yet. */
+    offer(text: string): {
+        replaced: boolean;
+    };
+    /** Hand over what is waiting, and empty the slot. */
+    take(): string | null;
+    get waiting(): boolean;
+    clear(): void;
+}
+/** Confirmation for a prompt that will run later, so the sender can stop wondering. */
+export declare function describeQueued(replaced: boolean): string;
+/** Confirmation for a prompt that starts immediately. */
+export declare function describeStarted(text: string): string;
+export declare function markRunFromPhone(): void;
+/** True once per run that came from the phone, then false again. */
+export declare function takeRunFromPhone(): boolean;
+export interface InboxHost {
+    /** True while a run owns the agent, so a prompt has to wait its turn. */
+    isBusy: () => boolean;
+    /** Run a prompt as though it had been typed into the input. */
+    submit: (text: string) => void;
+    /** Say something back on the phone. Failures here are not worth surfacing. */
+    reply: (text: string) => void;
+}
+/**
+ * Listen for instructions from the phone until the returned function is called.
+ *
+ * The queue is drained by `drain`, which the host calls when a run ends —
+ * rather than polled from here — so that "the agent is free" is decided in one
+ * place instead of two that can disagree.
+ */
+export declare function attachTelegramInbox(credentials: TelegramCredentials, host: InboxHost): {
+    stop: () => void;
+    drain: () => void;
+};

package/dist/utils/telegramInbox.js

@@ -0,0 +1,188 @@
+/**
+ * Starting work from the phone.
+ *
+ * Approval lets the phone answer a question the agent asked. This lets the
+ * phone ask one — which is a different thing, and a larger one. A chat that can
+ * only say Run, Skip or Cancel is bounded by what the agent already decided to
+ * do; a chat that can send a prompt is a keyboard attached to this machine.
+ * That is why it is off by default and has its own switch rather than riding on
+ * the approval one.
+ */
+import { sharedUpdates } from './telegramUpdates.js';
+/** Longest prompt accepted. Past this it is a paste, not an instruction. */
+export const MAX_PROMPT_LENGTH = 2000;
+/**
+ * How old a message may be and still run.
+ *
+ * Telegram keeps undelivered updates for 24 hours. Without this, a message
+ * typed at midnight to a machine that was switched off would be handed to the
+ * agent the moment the CLI next started — hours later, in a repository that has
+ * moved on, with nobody watching. A prompt is an instruction for now.
+ */
+export const MAX_MESSAGE_AGE_MS = 5 * 60_000;
+/**
+ * Whether a message update came from the one chat allowed to drive this agent.
+ *
+ * A bot's username is discoverable, so without this anyone who found it could
+ * type into somebody else's terminal. Mirrors the approval check deliberately:
+ * both gate the same machine, and they should not be able to disagree.
+ */
+export function messageFromOwner(message, chatID) {
+    if (!chatID)
+        return false;
+    const chat = message?.chat;
+    const id = chat?.id;
+    if (typeof id === 'number')
+        return String(id) === chatID;
+    if (typeof id === 'string')
+        return id === chatID;
+    return false;
+}
+/**
+ * Turn a Telegram message into a prompt, or say why it is not one.
+ *
+ * Returns a reason rather than null throughout: every rejection here has a
+ * different thing to tell the sender, and a bot that goes quiet is
+ * indistinguishable from one that is switched off.
+ */
+export function extractPrompt(message, chatID, now = Date.now()) {
+    if (!messageFromOwner(message, chatID))
+        return { ok: false, reason: 'not-from-owner' };
+    const text = message?.text;
+    // A photo, sticker or voice note has no `text` at all.
+    if (typeof text !== 'string')
+        return { ok: false, reason: 'not-text' };
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return { ok: false, reason: 'empty' };
+    if (trimmed.length > MAX_PROMPT_LENGTH)
+        return { ok: false, reason: 'too-long' };
+    // `/start` and friends are addressed to the bot, not to the agent.
+    if (trimmed.startsWith('/'))
+        return { ok: false, reason: 'command' };
+    const date = message?.date;
+    if (typeof date === 'number' && now - date * 1000 > MAX_MESSAGE_AGE_MS) {
+        return { ok: false, reason: 'stale' };
+    }
+    return { ok: true, text: trimmed };
+}
+/** What to say back, so silence never has to be interpreted. */
+export function describeRejection(reason) {
+    switch (reason) {
+        // Answering a stranger confirms the bot is live and attached to something
+        // worth probing. They get nothing.
+        case 'not-from-owner': return null;
+        case 'not-text': return 'I can only take text — send the instruction as a message.';
+        case 'empty': return null;
+        case 'too-long': return `That is longer than ${MAX_PROMPT_LENGTH} characters. Send a shorter instruction, or paste the text into the terminal.`;
+        case 'stale': return 'That message is older than five minutes, so I have not run it. Send it again if you still want it.';
+        case 'command': return 'Send an instruction in plain words — I do not take slash commands here.';
+    }
+}
+/**
+ * The one instruction waiting for the agent to be free.
+ *
+ * One slot, and a newer message replaces an older one. A queue that grows is a
+ * queue that runs things you have forgotten asking for: send two corrections
+ * while a run is busy and you meant the second, not both in order. Replacing
+ * says so out loud rather than quietly dropping either.
+ */
+export class InboxQueue {
+    pending = null;
+    /** @returns whether this displaced an instruction that had not run yet. */
+    offer(text) {
+        const replaced = this.pending !== null;
+        this.pending = text;
+        return { replaced };
+    }
+    /** Hand over what is waiting, and empty the slot. */
+    take() {
+        const out = this.pending;
+        this.pending = null;
+        return out;
+    }
+    get waiting() {
+        return this.pending !== null;
+    }
+    clear() {
+        this.pending = null;
+    }
+}
+/** Confirmation for a prompt that will run later, so the sender can stop wondering. */
+export function describeQueued(replaced) {
+    return replaced
+        ? 'Queued — replaces the one you sent before it. It runs when the current task finishes.'
+        : 'Queued — it runs when the current task finishes.';
+}
+/** Confirmation for a prompt that starts immediately. */
+export function describeStarted(text) {
+    const short = text.length > 60 ? `${text.slice(0, 57)}…` : text;
+    return `Started — ${short}`;
+}
+// ─── Whose run is it ──────────────────────────────────────────────────────────
+/**
+ * Whether the run now finishing was started from the phone.
+ *
+ * It decides whether the agent's answer travels. Start a run at the terminal
+ * and the answer is already on the screen you are sitting at; sending it to
+ * Telegram would put a file's contents, a command line, or a secret inside an
+ * error message into a chat that syncs to Telegram's servers, for nothing. Ask
+ * from the phone and the answer is the entire point — you are not at the desk,
+ * and "finished, 33K tokens" answers nothing you asked.
+ *
+ * Module-level because the inbox and the notice sit either side of the run and
+ * share no object: the inbox is wired up once in main.ts, the notice fires deep
+ * inside executeAgentTask.
+ */
+let startedFromPhone = false;
+export function markRunFromPhone() {
+    startedFromPhone = true;
+}
+/** True once per run that came from the phone, then false again. */
+export function takeRunFromPhone() {
+    const was = startedFromPhone;
+    startedFromPhone = false;
+    return was;
+}
+/**
+ * Listen for instructions from the phone until the returned function is called.
+ *
+ * The queue is drained by `drain`, which the host calls when a run ends —
+ * rather than polled from here — so that "the agent is free" is decided in one
+ * place instead of two that can disagree.
+ */
+export function attachTelegramInbox(credentials, host) {
+    const queue = new InboxQueue();
+    const unsubscribe = sharedUpdates(credentials.botToken).subscribe('message', message => {
+        const result = extractPrompt(message, credentials.chatID);
+        if (!result.ok) {
+            const explanation = describeRejection(result.reason);
+            if (explanation)
+                host.reply(explanation);
+            return;
+        }
+        if (host.isBusy()) {
+            host.reply(describeQueued(queue.offer(result.text).replaced));
+            return;
+        }
+        host.reply(describeStarted(result.text));
+        markRunFromPhone();
+        host.submit(result.text);
+    });
+    return {
+        stop: () => { unsubscribe(); queue.clear(); },
+        drain: () => {
+            // Re-check busy: a run can start from the terminal between the last one
+            // ending and this firing, and two agents on one workspace is not a thing
+            // this queue gets to cause.
+            if (host.isBusy())
+                return;
+            const next = queue.take();
+            if (next === null)
+                return;
+            host.reply(describeStarted(next));
+            markRunFromPhone();
+            host.submit(next);
+        },
+    };
+}

package/dist/utils/telegramNotify.d.ts

@@ -0,0 +1,102 @@
+import type { TelegramCredentials } from './telegramApproval';
+/**
+ * Runs shorter than this are not worth a notification.
+ *
+ * The problem this solves is walking away — starting something substantial,
+ * making coffee, and not knowing it finished. A `git status` that returned in
+ * two seconds was never going to outlast your attention, and a phone that
+ * buzzes for every one of those gets muted within a day, taking the
+ * notifications that mattered with it.
+ */
+export declare const NOTIFY_AFTER_MS = 60000;
+export declare function shouldNotify(elapsedMs: number, enabled: boolean): boolean;
+/** `92s` / `4m 12s` / `1h 03m` — short enough to read on a lock screen. */
+export declare function formatDuration(ms: number): string;
+/**
+ * Telegram refuses a message over 4096 characters outright.
+ *
+ * Kept well under, because the summary head shares the first message.
+ */
+export declare const MAX_ANSWER_LENGTH = 3000;
+/**
+ * How many messages one answer may become.
+ *
+ * A long answer is worth several; an enormous one is not worth a phone buzzing
+ * eleven times, and past a point nobody is reading it there anyway. Three is
+ * enough for an explanation and short of a flood.
+ */
+export declare const MAX_ANSWER_PARTS = 3;
+/**
+ * An answer as the messages to send, in order.
+ *
+ * Cutting at the limit was honest — it said it had cut — but lossy in the place
+ * it hurts: an answer that lists files or walks through a change passes 3000
+ * characters easily, and the conclusion is at the end. So it is split instead,
+ * on a paragraph or line boundary where there is one nearby, and only what
+ * exceeds three messages is cut.
+ *
+ * Mirrors the Mac app's `TelegramAnswerText.partsForPhone` deliberately: two
+ * implementations of "what does the phone get" that can disagree is worse than
+ * either.
+ */
+export declare function splitAnswer(text: string): string[];
+/**
+ * Markdown out, plain words in.
+ *
+ * The agent writes for a terminal that renders markdown, so its answer arrives
+ * on a phone as `**140 datoteka**` — asterisks and backticks read as noise
+ * exactly where the answer should be easiest to read.
+ *
+ * Stripped rather than handed to Telegram as `parse_mode`, which would be the
+ * obvious fix and the wrong one: Telegram rejects a whole message whose markup
+ * is unbalanced, and an agent's answer is arbitrary text. One stray asterisk
+ * and the notice does not arrive at all. Ugly beats missing, and this is
+ * neither.
+ *
+ * Deliberately conservative. Only paired markers are touched, and single
+ * underscores are left alone entirely — `execute_command` and `snake_case`
+ * appear in these answers constantly, and mangling an identifier to italicise
+ * nothing is worse than leaving a marker visible.
+ */
+export declare function stripMarkdown(text: string): string;
+export interface RunSummary {
+    /** What the run was called — the session display name, not the full prompt. */
+    task: string;
+    elapsedMs: number;
+    /** Set when the run ended on an error, so the message can say so. */
+    failure?: string;
+    tokens?: number;
+    /** Pay-per-use dollars. Omitted on a flat-fee plan, where any figure is invented. */
+    costUsd?: number;
+    /**
+     * The agent's own reply, for a run that was started from the phone.
+     *
+     * Omitted for a run started at the terminal, where the answer is already on
+     * the screen the person is sitting at and sending it would put file contents
+     * or a command line into a chat for nothing.
+     */
+    answer?: string;
+}
+/**
+ * The notification, as the messages to send in order.
+ *
+ * One message when the answer fits, which is the common case. A longer answer
+ * continues into further messages rather than being cut at the first limit —
+ * see `splitAnswer`. The head shares the first message, so the reply is not a
+ * bare wall of text with no idea which run it belongs to.
+ *
+ * Carries the agent's answer only when the run was started from the phone. A
+ * finished run can end with anything in it — a file it read, a command it ran,
+ * a secret inside an error — and this goes to a chat that syncs to Telegram's
+ * servers, so it travels only where it was actually asked for. Start a run at
+ * the terminal and this says there is a result to come back to, and no more.
+ */
+export declare function composeRunMessages(summary: RunSummary): string[];
+/**
+ * Send it, and say nothing if it fails.
+ *
+ * A notification that could not be delivered is not worth interrupting the
+ * terminal for — the run already finished and its result is on screen. Returns
+ * whether it went, so a caller that does care can look.
+ */
+export declare function sendTelegramNotice(credentials: TelegramCredentials, text: string): Promise<boolean>;

package/dist/utils/telegramNotify.js

@@ -0,0 +1,201 @@
+/**
+ * Telling you the run is done, on the phone that already answers its questions.
+ *
+ * Separate from TelegramApproval on purpose: that class exists to ask a
+ * question and wait for one of three answers, and none of its machinery — the
+ * keyboard, the token, the outstanding-message bookkeeping — means anything
+ * for a message nobody replies to.
+ */
+const API = 'https://api.telegram.org/bot';
+const REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * Runs shorter than this are not worth a notification.
+ *
+ * The problem this solves is walking away — starting something substantial,
+ * making coffee, and not knowing it finished. A `git status` that returned in
+ * two seconds was never going to outlast your attention, and a phone that
+ * buzzes for every one of those gets muted within a day, taking the
+ * notifications that mattered with it.
+ */
+export const NOTIFY_AFTER_MS = 60_000;
+export function shouldNotify(elapsedMs, enabled) {
+    return enabled && elapsedMs >= NOTIFY_AFTER_MS;
+}
+/** `92s` / `4m 12s` / `1h 03m` — short enough to read on a lock screen. */
+export function formatDuration(ms) {
+    const seconds = Math.round(ms / 1000);
+    if (seconds < 90)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ${String(seconds % 60).padStart(2, '0')}s`;
+    return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, '0')}m`;
+}
+/**
+ * Telegram refuses a message over 4096 characters outright.
+ *
+ * Kept well under, because the summary head shares the first message.
+ */
+export const MAX_ANSWER_LENGTH = 3000;
+/**
+ * How many messages one answer may become.
+ *
+ * A long answer is worth several; an enormous one is not worth a phone buzzing
+ * eleven times, and past a point nobody is reading it there anyway. Three is
+ * enough for an explanation and short of a flood.
+ */
+export const MAX_ANSWER_PARTS = 3;
+/**
+ * An answer as the messages to send, in order.
+ *
+ * Cutting at the limit was honest — it said it had cut — but lossy in the place
+ * it hurts: an answer that lists files or walks through a change passes 3000
+ * characters easily, and the conclusion is at the end. So it is split instead,
+ * on a paragraph or line boundary where there is one nearby, and only what
+ * exceeds three messages is cut.
+ *
+ * Mirrors the Mac app's `TelegramAnswerText.partsForPhone` deliberately: two
+ * implementations of "what does the phone get" that can disagree is worse than
+ * either.
+ */
+export function splitAnswer(text) {
+    const plain = text.trim();
+    if (!plain)
+        return [];
+    const parts = [];
+    let rest = plain;
+    while (rest.length > 0 && parts.length < MAX_ANSWER_PARTS) {
+        if (rest.length <= MAX_ANSWER_LENGTH) {
+            parts.push(rest);
+            rest = '';
+            break;
+        }
+        const cut = breakPoint(rest);
+        parts.push(rest.slice(0, cut).trim());
+        rest = rest.slice(cut).replace(/^[\n ]+/, '');
+    }
+    // Say it was cut rather than ending mid-sentence and looking finished.
+    if (rest.length > 0 && parts.length > 0) {
+        parts[parts.length - 1] += '\n\n[…cut — the full answer is in the terminal]';
+    }
+    return parts;
+}
+/**
+ * Where to end a part: the last paragraph break in the final third of the
+ * allowance, else the last line break, else the last space.
+ *
+ * Splitting mid-word reads as damage; splitting mid-paragraph reads as a
+ * continuation. Only the tail is searched so a single long paragraph does not
+ * send a 200-character message and push the rest into the next one.
+ */
+function breakPoint(text) {
+    const earliest = Math.floor((MAX_ANSWER_LENGTH * 2) / 3);
+    const window = text.slice(earliest, MAX_ANSWER_LENGTH);
+    const paragraph = window.lastIndexOf('\n\n');
+    if (paragraph >= 0)
+        return earliest + paragraph;
+    const line = window.lastIndexOf('\n');
+    if (line >= 0)
+        return earliest + line;
+    const space = window.lastIndexOf(' ');
+    if (space >= 0)
+        return earliest + space;
+    return MAX_ANSWER_LENGTH;
+}
+/**
+ * Markdown out, plain words in.
+ *
+ * The agent writes for a terminal that renders markdown, so its answer arrives
+ * on a phone as `**140 datoteka**` — asterisks and backticks read as noise
+ * exactly where the answer should be easiest to read.
+ *
+ * Stripped rather than handed to Telegram as `parse_mode`, which would be the
+ * obvious fix and the wrong one: Telegram rejects a whole message whose markup
+ * is unbalanced, and an agent's answer is arbitrary text. One stray asterisk
+ * and the notice does not arrive at all. Ugly beats missing, and this is
+ * neither.
+ *
+ * Deliberately conservative. Only paired markers are touched, and single
+ * underscores are left alone entirely — `execute_command` and `snake_case`
+ * appear in these answers constantly, and mangling an identifier to italicise
+ * nothing is worse than leaving a marker visible.
+ */
+export function stripMarkdown(text) {
+    return text
+        // Fenced blocks: keep the code, drop the fence and any language tag.
+        .replace(/```[a-zA-Z0-9-]*\n?([\s\S]*?)```/g, '$1')
+        // Headings, which a phone shows as literal hashes.
+        .replace(/^#{1,6}[ \t]+/gm, '')
+        .replace(/\*\*([^*]+)\*\*/g, '$1')
+        .replace(/__([^_]+)__/g, '$1')
+        // Single backticks only — a lone one is left alone rather than eating the
+        // rest of the answer looking for a partner.
+        .replace(/`([^`\n]+)`/g, '$1')
+        .trim();
+}
+/** The head: what ran, how long it took, what it cost. Never the answer. */
+function composeHead(summary) {
+    const head = summary.failure ? '⚠️ Codeep stopped' : '✅ Codeep finished';
+    const lines = [`${head} — ${summary.task}`, `took ${formatDuration(summary.elapsedMs)}`];
+    if (summary.failure)
+        lines.push(summary.failure);
+    const cost = [];
+    if (typeof summary.tokens === 'number' && summary.tokens > 0) {
+        cost.push(`${Math.round(summary.tokens / 1000)}K tokens`);
+    }
+    if (typeof summary.costUsd === 'number' && summary.costUsd > 0) {
+        cost.push(`$${summary.costUsd.toFixed(summary.costUsd < 0.01 ? 4 : 2)}`);
+    }
+    if (cost.length > 0)
+        lines.push(cost.join(' · '));
+    return lines.join('\n');
+}
+/**
+ * The notification, as the messages to send in order.
+ *
+ * One message when the answer fits, which is the common case. A longer answer
+ * continues into further messages rather than being cut at the first limit —
+ * see `splitAnswer`. The head shares the first message, so the reply is not a
+ * bare wall of text with no idea which run it belongs to.
+ *
+ * Carries the agent's answer only when the run was started from the phone. A
+ * finished run can end with anything in it — a file it read, a command it ran,
+ * a secret inside an error — and this goes to a chat that syncs to Telegram's
+ * servers, so it travels only where it was actually asked for. Start a run at
+ * the terminal and this says there is a result to come back to, and no more.
+ */
+export function composeRunMessages(summary) {
+    const head = composeHead(summary);
+    const parts = summary.answer ? splitAnswer(stripMarkdown(summary.answer)) : [];
+    if (parts.length === 0)
+        return [head];
+    return [`${head}\n\n${parts[0]}`, ...parts.slice(1)];
+}
+/**
+ * Send it, and say nothing if it fails.
+ *
+ * A notification that could not be delivered is not worth interrupting the
+ * terminal for — the run already finished and its result is on screen. Returns
+ * whether it went, so a caller that does care can look.
+ */
+export async function sendTelegramNotice(credentials, text) {
+    try {
+        const response = await fetch(`${API}${credentials.botToken}/sendMessage`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                chat_id: credentials.chatID,
+                text,
+                // No parse_mode: a task name is arbitrary user text and Telegram
+                // rejects the whole message on unbalanced Markdown, which would turn a
+                // stray underscore in a branch name into a silently dropped notice.
+                disable_notification: false,
+            }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/telegramUpdates.d.ts

@@ -0,0 +1,71 @@
+/**
+ * One long poll, one offset, both kinds of update.
+ *
+ * Telegram's getUpdates has a single cursor per bot. `offset` confirms every
+ * update older than itself **regardless of `allowed_updates`** — that parameter
+ * only filters what comes back in the response, not what the call acknowledges.
+ * So two pollers on one bot do not coexist: each advances the cursor past
+ * updates the other never saw, and both start losing traffic silently. An
+ * approval tapped on the phone would simply not register, with nothing anywhere
+ * to say why.
+ *
+ * Hence this. Everything that wants updates subscribes here, the loop asks for
+ * every type any subscriber could want, and dispatch happens locally where
+ * losing one is impossible.
+ */
+export interface TelegramCredentials {
+    /** From @BotFather. A credential — belongs in the keychain, never in config. */
+    botToken: string;
+    /** The single chat allowed to answer. Anything else is ignored. */
+    chatID: string;
+}
+export type UpdateKind = 'callback_query' | 'message';
+export type UpdateHandler = (payload: unknown) => void | Promise<void>;
+/**
+ * Told when a poll fails, and when one succeeds after failing.
+ *
+ * Without this the loop was completely silent: a webhook left configured on the
+ * bot answers 409 to every getUpdates, a revoked token answers 401, and both
+ * looked exactly like a phone nobody had messaged. Diagnosing it meant reading
+ * the source.
+ */
+export type PollObserver = (event: {
+    ok: boolean;
+    detail: string;
+}) => void;
+/**
+ * Where the cursor goes after a batch.
+ *
+ * Never backwards: a retry that returns an older batch, or a response with ids
+ * this build does not understand, must not re-deliver what was already handled.
+ */
+export declare function nextOffset(current: number, updates: {
+    update_id?: unknown;
+}[]): number;
+/** Every kind this loop asks for, so one cursor can serve every subscriber. */
+export declare const POLLED_KINDS: readonly UpdateKind[];
+export declare class TelegramUpdates {
+    private readonly botToken;
+    private readonly handlers;
+    private offset;
+    private running;
+    private readonly idlePauseMs;
+    private observer;
+    /** Only the first failure of a streak is reported, then the recovery. */
+    private failing;
+    constructor(botToken: string, idlePauseMs?: number);
+    /** Watch the health of the poll itself, separately from its payload. */
+    observe(observer: PollObserver | null): void;
+    private report;
+    /**
+     * Listen for one kind of update. Returns the function that stops listening.
+     *
+     * The loop runs while anyone is listening and stops when the last subscriber
+     * leaves, so a CLI with the inbox switched off never opens a connection.
+     */
+    subscribe(kind: UpdateKind, handler: UpdateHandler): () => void;
+    private subscriberCount;
+    private loop;
+    private getUpdates;
+}
+export declare function sharedUpdates(botToken: string): TelegramUpdates;