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

package/lib/session/preferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preferences.d.ts","sourceRoot":"","sources":["../../src/session/preferences.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD,4BAA4B;AAC5B,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAA;CAC5C;AAED,qBAAa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,MAAM,CAA4B;IAE1C,OAAO;IAKP;;;;;;;;OAQG;WACU,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAMzF,0DAA0D;IAC1D,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS;IAI/C;;;;;OAKG;IACG,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3D,uEAAuE;IACjE,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9C,0EAA0E;YAC5D,OAAO;CAQtB"}

package/lib/session/preferences.js

@@ -0,0 +1,102 @@
+/**
+ * One durable string a conversation chose for itself.
+ *
+ * Two things need this and they are the same shape: the directory a chat works
+ * in, and the model it talks to. Both are per conversation, both must outlive
+ * `/new` — a preference discarded with the session would silently snap back to
+ * the deployment default on the next message — and both must outlive a
+ * restart.
+ *
+ * Kept apart from the session binding for exactly that reason: a binding is
+ * one conversation with the agent and dies with `/new`, while a preference
+ * belongs to the CHAT.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export class ChatPreferences {
+    file;
+    accept;
+    values = new Map();
+    constructor(file, accept) {
+        this.file = file;
+        this.accept = accept;
+    }
+    /**
+     * Load the store, or start empty when there is nothing readable yet.
+     *
+     * A corrupt file costs the conversation its preference, which one command
+     * restores; refusing to start would cost the whole bot.
+     *
+     * @param file - absolute path to the JSON document.
+     * @param options - how to tell a usable value from one to drop.
+     */
+    static async open(file, options) {
+        const store = new ChatPreferences(file, options.accept);
+        store.values = await read(file, options.accept);
+        return store;
+    }
+    /** What this conversation chose, if it chose anything. */
+    forChat(target) {
+        return this.values.get(keyOf(target));
+    }
+    /**
+     * Remember a conversation's choice.
+     *
+     * @param target - the conversation.
+     * @param value - the value, already checked by the caller.
+     */
+    async set(target, value) {
+        if (!this.accept(value))
+            return;
+        const next = new Map(this.values);
+        next.set(keyOf(target), value);
+        this.values = next;
+        await this.persist();
+    }
+    /** Forget it, returning the conversation to the deployment default. */
+    async clear(target) {
+        const next = new Map(this.values);
+        if (!next.delete(keyOf(target)))
+            return;
+        this.values = next;
+        await this.persist();
+    }
+    /** Write the document atomically, so a crash cannot leave a half file. */
+    async persist() {
+        const document = Object.fromEntries(this.values);
+        const temporary = `${this.file}.${process.pid}.tmp`;
+        await mkdir(dirname(this.file), { recursive: true });
+        await writeFile(temporary, `${JSON.stringify(document, undefined, 2)}\n`, 'utf8');
+        await rename(temporary, this.file);
+    }
+}
+/** The durable key for one conversation; a forum topic is its own conversation. */
+function keyOf(target) {
+    return target.threadId === undefined ? target.chatId : `${target.chatId}#${target.threadId}`;
+}
+/** Read the document, keeping only entries the caller still accepts. */
+async function read(file, accept) {
+    const values = new Map();
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch {
+        return values;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return values;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return values;
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value === 'string' && value !== '' && accept(value))
+            values.set(key, value);
+    }
+    return values;
+}
+//# sourceMappingURL=preferences.js.map

package/lib/session/preferences.js.map

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

package/lib/session/recovery.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Getting a conversation out of a state it cannot leave on its own.
+ *
+ * Some failures are transient and worth retrying. One is not: a provider
+ * inspects the whole request history for images, so once a session's log holds
+ * one, every later turn fails on a model that cannot read it — however plain
+ * that turn's own text. Retrying is futile, and the user has no way of knowing
+ * that from the error, which talks about image input on a message they may
+ * have sent an hour ago.
+ *
+ * The only exit is a new session, and asking the user to remember a command
+ * for it is asking them to diagnose the plugin. So the plugin recognises the
+ * failure and offers the exit as a button.
+ */
+import type { ChatTarget } from '../interact/surface.js';
+import type { ChatSurface } from '../interact/surface.js';
+import type { PendingRegistry } from '../interact/pending.js';
+import type { Logger } from '../harness/types.js';
+/** How a turn failed, as the session log reports it. */
+export interface TurnFailure {
+    readonly message: string;
+    readonly code?: string;
+}
+/**
+ * Whether only a new conversation can clear this failure.
+ *
+ * `UNSUPPORTED_CONTENT` is the provider saying the request carries something
+ * it will not take. Since the request carries the whole history, that is not
+ * about the message just sent, and nothing the user types next will help.
+ */
+export declare function needsFreshConversation(failure: TurnFailure): boolean;
+/** Everything the offer needs from the rest of the plugin. */
+export interface RecoveryOfferOptions {
+    readonly surface: ChatSurface;
+    readonly pending: PendingRegistry<unknown>;
+    /** Resolve a session id to its chat, or undefined when it is not a Telegram one. */
+    readonly targetOf: (sessionId: string) => ChatTarget | undefined;
+    /** Forget the conversation's session, exactly as `/new` does. */
+    readonly reset: (target: ChatTarget) => Promise<void>;
+}
+export declare class RecoveryOffer {
+    private readonly options;
+    private readonly logger;
+    /** Conversations already offered a way out, so a retry loop cannot spam. */
+    private readonly offered;
+    constructor(options: RecoveryOfferOptions, logger?: Logger);
+    /**
+     * Tell the user a turn failed, and offer the exit when there is one.
+     *
+     * @param sessionId - the session whose turn failed.
+     * @param failure - the structured failure from the session log.
+     */
+    offer(sessionId: string, failure: TurnFailure): Promise<void>;
+    /**
+     * Route one button press.
+     *
+     * @param data - raw `callback_data` from the update.
+     * @returns whether the press belonged to an open offer.
+     */
+    handleCallback(data: string | undefined): boolean;
+    /** Forget every outstanding offer — the plugin is unloading. */
+    dispose(): void;
+    /** Post one notice, swallowing delivery failures. */
+    private say;
+}
+//# sourceMappingURL=recovery.d.ts.map

package/lib/session/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/session/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAMjD,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAGpE;AAED,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,CAAA;IAC1C,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAA;IAChE,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtD;AAED,qBAAa,aAAa;IAMtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAGzB,OAAO,EAAE,oBAAoB,EAC9C,MAAM,CAAC,EAAE,MAAM;IAKjB;;;;;OAKG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA0CnE;;;;;OAKG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO;IAYjD,gEAAgE;IAChE,OAAO,IAAI,IAAI;IAIf,qDAAqD;YACvC,GAAG;CAWlB"}

package/lib/session/recovery.js

@@ -0,0 +1,112 @@
+/**
+ * Getting a conversation out of a state it cannot leave on its own.
+ *
+ * Some failures are transient and worth retrying. One is not: a provider
+ * inspects the whole request history for images, so once a session's log holds
+ * one, every later turn fails on a model that cannot read it — however plain
+ * that turn's own text. Retrying is futile, and the user has no way of knowing
+ * that from the error, which talks about image input on a message they may
+ * have sent an hour ago.
+ *
+ * The only exit is a new session, and asking the user to remember a command
+ * for it is asking them to diagnose the plugin. So the plugin recognises the
+ * failure and offers the exit as a button.
+ */
+import { escapeHtml } from '../render/escape.js';
+import { SILENT_LOGGER } from '../harness/types.js';
+/** Prefix marking callback data as belonging to a recovery offer. */
+const KIND = 'r';
+/**
+ * Whether only a new conversation can clear this failure.
+ *
+ * `UNSUPPORTED_CONTENT` is the provider saying the request carries something
+ * it will not take. Since the request carries the whole history, that is not
+ * about the message just sent, and nothing the user types next will help.
+ */
+export function needsFreshConversation(failure) {
+    if (failure.code === 'UNSUPPORTED_CONTENT')
+        return true;
+    return /does not (?:accept|support) image input/i.test(failure.message);
+}
+export class RecoveryOffer {
+    options;
+    logger;
+    /** Conversations already offered a way out, so a retry loop cannot spam. */
+    offered = new Set();
+    constructor(options, logger) {
+        this.options = options;
+        this.logger = logger ?? SILENT_LOGGER;
+    }
+    /**
+     * Tell the user a turn failed, and offer the exit when there is one.
+     *
+     * @param sessionId - the session whose turn failed.
+     * @param failure - the structured failure from the session log.
+     */
+    async offer(sessionId, failure) {
+        const target = this.options.targetOf(sessionId);
+        if (!target)
+            return;
+        const stuck = needsFreshConversation(failure);
+        if (!stuck) {
+            // A failure that may pass on its own needs no button, only saying so.
+            await this.say(target, `⚠️ ${escapeHtml(failure.message)}`);
+            return;
+        }
+        if (this.offered.has(sessionId))
+            return;
+        this.offered.add(sessionId);
+        const waiter = this.options.pending.open({
+            onCancel: () => this.offered.delete(sessionId),
+        });
+        await this.say(target, [
+            `⚠️ ${escapeHtml(failure.message)}`,
+            '',
+            'This conversation cannot continue on the current model — an earlier ' +
+                'message carries content it will not accept. A new conversation clears it.',
+        ].join('\n'), [[{ text: '🆕 Start a fresh conversation', callbackData: `${KIND}:${waiter.token}:0` }]]);
+        const pressed = await waiter.promise;
+        this.offered.delete(sessionId);
+        if (pressed === undefined)
+            return;
+        try {
+            await this.options.reset(target);
+            await this.say(target, '🆕 Started a fresh conversation. Send your message again.');
+        }
+        catch (error) {
+            this.logger.error('[dsh-telegram] could not start a fresh conversation', error);
+            await this.say(target, '⚠️ Could not start a fresh conversation. Try /new.');
+        }
+    }
+    /**
+     * Route one button press.
+     *
+     * @param data - raw `callback_data` from the update.
+     * @returns whether the press belonged to an open offer.
+     */
+    handleCallback(data) {
+        if (data === undefined)
+            return false;
+        const parts = data.split(':');
+        if (parts.length !== 3 || parts[0] !== KIND)
+            return false;
+        const token = parts[1];
+        if (token === '')
+            return false;
+        return this.options.pending.settle(token, { token });
+    }
+    /** Forget every outstanding offer — the plugin is unloading. */
+    dispose() {
+        this.offered.clear();
+    }
+    /** Post one notice, swallowing delivery failures. */
+    async say(target, html, keyboard) {
+        try {
+            await this.options.surface.send(target, html, keyboard);
+        }
+        catch (error) {
+            this.logger.warn('[dsh-telegram] could not deliver a recovery offer', error);
+        }
+    }
+}
+//# sourceMappingURL=recovery.js.map

package/lib/session/recovery.js.map

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

package/lib/session/runner.d.ts

@@ -0,0 +1,223 @@
+/**
+ * One harness session per Telegram conversation.
+ *
+ * The lifecycle has three states and the transitions between them are the
+ * whole job: a conversation with no session yet, one whose session is loaded
+ * in this process, and one whose session exists only in the durable log
+ * because the harness has restarted since.
+ *
+ * The third case is why `resume` exists and why a failed resume is not fatal.
+ * A session log can be pruned, moved, or written by an incompatible version;
+ * when it can no longer be loaded, the user gets a fresh conversation and a
+ * note, which is far better than a bot that answers every message with the
+ * same load error.
+ *
+ * The agent host is injected rather than reached for directly, so this logic
+ * is exercised without a running harness.
+ */
+import type { ChatTarget } from '../interact/surface.js';
+import type { PromptPart } from '../media/collect.js';
+import type { ModelRoute } from '../harness/model-selection.js';
+import type { AgentRunner } from '../router.js';
+import type { Logger } from '../harness/types.js';
+import type { BindingStore } from './bindings.js';
+/** One line of a conversation's description. */
+export interface StatusRow {
+    readonly label: string;
+    readonly value: string;
+}
+/** A live agent this plugin drives. */
+export interface RunningAgent {
+    readonly sessionId: string;
+    /** Queue a user message and wake the driver. */
+    followup(content: readonly PromptPart[]): void;
+    /**
+     * Route the next step onto another model, or back to the agent's own.
+     *
+     * @param route - the override, or undefined to drop it.
+     * @returns whether the agent accepts an override at all; a borrowed agent,
+     *   or a harness that offers no selection seam, does not.
+     */
+    useModel(route: ModelRoute | undefined): boolean;
+    /** Cancel the in-flight turn and any queued work. */
+    cancel(reason: string): void;
+    /** Stop the agent and release its session. */
+    dispose(): Promise<void>;
+}
+/** Creating and loading agents — the harness surface, narrowed. */
+export interface AgentHost {
+    /** The agent for a session if it is already loaded in this process. */
+    live(sessionId: string): RunningAgent | undefined;
+    /**
+     * Start a new session and agent under `sessionId`.
+     *
+     * @param route - forces the model rather than taking the deployment's
+     *   default. Used by the throwaway session an image is read in, which has to
+     *   run somewhere that can see.
+     */
+    create(sessionId: string, cwd: string, route?: ModelRoute): Promise<RunningAgent>;
+    /** Load a persisted session; undefined when it can no longer be loaded. */
+    resume(sessionId: string): Promise<RunningAgent | undefined>;
+}
+/** Something that can replace an image in a prompt with what it says. */
+export interface PromptResolver {
+    /** Whether reading is possible at all right now. */
+    readonly available: boolean;
+    resolve(content: readonly PromptPart[], route: ModelRoute | undefined): Promise<PromptPart[]>;
+}
+/** Construction options. */
+export interface SessionRunnerOptions {
+    readonly host: AgentHost;
+    readonly bindings: BindingStore;
+    /**
+     * The directory a conversation's next session opens in.
+     *
+     * Per conversation rather than one value, because `/cd` is per chat — and
+     * read late, so a change reaches the next session rather than the next
+     * restart. A session's own cwd never moves: the sandbox derives its writable
+     * root from it and the harness calls that root immutable, which is why
+     * changing directory starts a fresh conversation.
+     */
+    readonly cwdFor: (target: ChatTarget) => string;
+    /** Session id factory; injected so tests can assert on stable ids. */
+    readonly newSessionId?: () => string;
+    /**
+     * Puts a session on the conversation's permission preset.
+     *
+     * Applied to a resumed session as well as a new one: the preset is a
+     * property of the surface the conversation arrives over, and a session that
+     * outlived a restart is still that conversation.
+     */
+    readonly permission?: {
+        apply(target: ChatTarget, sessionId: string): void;
+    };
+    /**
+     * Remembers which conversations this chat has had, so `/sessions` can offer
+     * one back. Absent makes `/new` the one-way door it used to be.
+     */
+    readonly history?: {
+        remember(target: ChatTarget, session: {
+            sessionId: string;
+            startedAt: number;
+            cwd: string;
+            label?: string;
+        }): Promise<void>;
+    };
+    /**
+     * Reads an image with a vision model so the conversation receives text.
+     *
+     * This is what keeps a conversation on its own model: a provider inspects
+     * the whole request history, so an image that reaches the conversation binds
+     * it to a model that can see for as long as it lives.
+     */
+    readonly extractor?: PromptResolver;
+    /**
+     * Whether the model this conversation runs on reads images itself.
+     *
+     * When it does, extraction is not merely unnecessary — it is worse. The
+     * conversation would receive a transcription instead of the picture, so a
+     * diagram, a chart or a misaligned layout becomes scattered words, and the
+     * model never gets to look at the thing it was asked about.
+     *
+     * The indirection exists because a provider inspects the whole request
+     * history: an image left in a conversation binds it to a model that can see.
+     * When that model IS the one the conversation chose, there is nothing to be
+     * stuck on and nothing to work around.
+     */
+    readonly modelSees?: (target: ChatTarget) => Promise<boolean>;
+    /**
+     * The model this conversation reads images with.
+     *
+     * Per conversation because `/vision` is, and read late so a change lands on
+     * the next such turn. It is also what a conversation moves onto when the
+     * picture could not be read and had to go through as it was.
+     */
+    readonly visionRoute?: (target: ChatTarget) => ModelRoute | undefined;
+    /**
+     * The model this conversation chose, if it chose one.
+     *
+     * Read per prompt rather than at session creation, because the harness reads
+     * a mutable selection while assembling each step — which is what lets
+     * `/model` take effect on the very next message rather than the next `/new`.
+     */
+    readonly chosenRoute?: (target: ChatTarget) => ModelRoute | undefined;
+    readonly logger?: Logger;
+}
+export declare class SessionRunner implements AgentRunner {
+    private readonly options;
+    private readonly logger;
+    private readonly newSessionId;
+    /** Serialises work per conversation, so two fast messages cannot both create. */
+    private readonly chains;
+    constructor(options: SessionRunnerOptions);
+    /**
+     * Deliver a prompt, opening or resuming the conversation's session first.
+     *
+     * @param target - the conversation the prompt came from.
+     * @param text - what the user typed.
+     */
+    prompt(target: ChatTarget, content: readonly PromptPart[]): Promise<void>;
+    /**
+     * Turn images into text, where there is anything able to do it.
+     *
+     * A failure here is not the turn's failure: the picture simply goes through
+     * as it is, and the conversation moves to a model that can see it.
+     */
+    private resolve;
+    /**
+     * Which model this conversation's next step must run on.
+     *
+     * Not a per-turn choice, though it looks like one. A provider checks the
+     * WHOLE request history for images, so once a session's log carries one,
+     * every later turn — however plain its own text — fails on a model that
+     * cannot see. The override therefore sticks to the conversation from the
+     * first image until it is reset with `/new`.
+     */
+    private routeFor;
+    /**
+     * Point a conversation at a session it had before.
+     *
+     * The session is not loaded here: the next message resumes it through the
+     * ordinary path, which is also the path that handles a log that can no
+     * longer be read.
+     *
+     * @param target - the conversation.
+     * @param sessionId - a session this chat had earlier.
+     */
+    adopt(target: ChatTarget, sessionId: string): Promise<void>;
+    /**
+     * Forget the conversation's session so the next prompt opens a new one.
+     *
+     * @param target - the conversation to reset.
+     */
+    reset(target: ChatTarget): Promise<void>;
+    /**
+     * Cancel whatever the conversation's agent is doing.
+     *
+     * @returns whether there was a loaded agent to cancel.
+     */
+    stop(target: ChatTarget): Promise<boolean>;
+    /**
+     * Describe the conversation as rows, for the caller to render.
+     *
+     * Rows rather than finished markup, because the caller adds its own — the
+     * model, the effort, what the agent may do — and stitching those onto a
+     * rendered string would mean parsing it back apart.
+     */
+    status(target: ChatTarget): Promise<StatusRow[]>;
+    /**
+     * The agent for a conversation: loaded, resumed, or freshly created.
+     *
+     * A binding whose session cannot be resumed is replaced rather than
+     * reported: the user's next message should work.
+     */
+    private agentFor;
+    /**
+     * Run one conversation's work after its previous work.
+     *
+     * Two messages arriving in the same poll batch would otherwise both see no
+     * binding and both create a session, orphaning the first.
+     */
+    private serialize;
+}
+//# sourceMappingURL=runner.d.ts.map

package/lib/session/runner.d.ts.map

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