pi-ui-extend 1.0.41 → 1.0.45

package/dist/bundled-extensions/telegram-connector/coordinator.d.ts

@@ -0,0 +1,66 @@
+import type { NormalizedQuestion, QuestionSelection } from "../question/types.js";
+import { TelegramBotClient, type TelegramIncomingMessage } from "./bot.js";
+import type { TelegramConnectorConfig } from "./config.js";
+export type TelegramCompletionKind = "complete" | "error";
+export type TelegramSessionEndpoint = {
+    sessionId: string;
+    cwd: string;
+    getTitle(): string;
+    isIdle(): boolean;
+    sendUserMessage(text: string): void;
+    dispatchNewSession(requestId: string): void;
+};
+type BotLike = Pick<TelegramBotClient, "start" | "stop" | "sendMessage">;
+type BotFactory = (botToken: string, chatId: string) => BotLike;
+export declare class TelegramConnectorCoordinator {
+    private readonly createBot;
+    private readonly reportError;
+    private readonly sessions;
+    private readonly completionRoutes;
+    private readonly pendingQuestions;
+    private readonly newSessionRequests;
+    private readonly newSessionSources;
+    private bot;
+    private botKey;
+    private focusSessionId;
+    private stopTimer;
+    constructor(createBot?: BotFactory, reportError?: (message: string) => void);
+    attachSession(endpoint: TelegramSessionEndpoint, config: TelegramConnectorConfig): void;
+    detachSession(sessionId: string, endpoint?: TelegramSessionEndpoint): void;
+    notifyCompletion(sessionId: string, kind: TelegramCompletionKind, summary?: string): Promise<void>;
+    askQuestions(sessionId: string, questions: NormalizedQuestion[], signal?: AbortSignal): Promise<QuestionSelection[] | null | undefined>;
+    createNewSessionRequest(sourceSessionId: string, task: string): string | undefined;
+    consumeNewSessionRequest(requestId: string, sourceSessionId: string): string | undefined;
+    finishNewSessionRequest(sourceSessionId: string): void;
+    announceNewSession(sessionId: string): Promise<void>;
+    sendStatus(): Promise<void>;
+    sendHelp(): Promise<void>;
+    sendNotice(text: string): Promise<void>;
+    handleIncoming(message: TelegramIncomingMessage): Promise<void>;
+    stop(): void;
+    private ensureBot;
+    private waitForQuestionReply;
+    private resolvePendingQuestion;
+    private cancelPendingQuestion;
+    private rememberCompletionRoute;
+    private hasPendingQuestionFor;
+    private pruneExpiredNewSessionRequests;
+    private scheduleStop;
+    private clearStopTimer;
+}
+type ParsedTelegramCommand = {
+    kind: "new";
+    task: string;
+} | {
+    kind: "help";
+} | {
+    kind: "status";
+} | {
+    kind: "message";
+    text: string;
+};
+export declare function parseTelegramCommand(text: string): ParsedTelegramCommand;
+export declare function parseQuestionAnswer(question: NormalizedQuestion, answer: string): QuestionSelection | undefined;
+export declare function getTelegramConnectorCoordinator(): TelegramConnectorCoordinator;
+export declare function resetTelegramConnectorCoordinatorForTests(): void;
+export {};

package/dist/bundled-extensions/telegram-connector/coordinator.js

@@ -0,0 +1,413 @@
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
+import { TelegramBotClient } from "./bot.js";
+const COMPLETION_ROUTE_LIMIT = 200;
+const NEW_SESSION_REQUEST_TTL_MS = 10 * 60_000;
+const STOP_GRACE_MS = 750;
+export class TelegramConnectorCoordinator {
+    createBot;
+    reportError;
+    sessions = new Map();
+    completionRoutes = new Map();
+    pendingQuestions = new Map();
+    newSessionRequests = new Map();
+    newSessionSources = new Map();
+    bot;
+    botKey;
+    focusSessionId;
+    stopTimer;
+    constructor(createBot = (botToken, chatId) => new TelegramBotClient(botToken, chatId), reportError = (message) => process.stderr.write(`[telegram-connector] ${message}\n`)) {
+        this.createBot = createBot;
+        this.reportError = reportError;
+    }
+    attachSession(endpoint, config) {
+        this.sessions.set(endpoint.sessionId, endpoint);
+        this.clearStopTimer();
+        if (!config.enabled || !config.botToken || !config.chatId)
+            return;
+        this.ensureBot(config.botToken, config.chatId);
+    }
+    detachSession(sessionId, endpoint) {
+        if (endpoint && this.sessions.get(sessionId) !== endpoint)
+            return;
+        this.sessions.delete(sessionId);
+        if (this.focusSessionId === sessionId)
+            this.focusSessionId = undefined;
+        for (const [messageId, pending] of this.pendingQuestions) {
+            if (pending.sessionId !== sessionId)
+                continue;
+            this.pendingQuestions.delete(messageId);
+            pending.resolve(null);
+        }
+        if (this.sessions.size === 0)
+            this.scheduleStop();
+    }
+    async notifyCompletion(sessionId, kind, summary) {
+        const endpoint = this.sessions.get(sessionId);
+        const bot = this.bot;
+        if (!endpoint || !bot)
+            return;
+        const messageId = await bot.sendMessage(formatCompletionMessage(endpoint, kind, summary));
+        if (this.bot !== bot || this.sessions.get(sessionId) !== endpoint)
+            return;
+        this.focusSessionId = sessionId;
+        this.rememberCompletionRoute(messageId, sessionId);
+    }
+    async askQuestions(sessionId, questions, signal) {
+        const endpoint = this.sessions.get(sessionId);
+        const bot = this.bot;
+        if (!endpoint || !bot)
+            return undefined;
+        if (signal?.aborted)
+            return null;
+        this.focusSessionId = sessionId;
+        const selections = [];
+        for (let index = 0; index < questions.length; index++) {
+            const question = questions[index];
+            const messageId = await bot.sendMessage(formatQuestionMessage(endpoint, question, index, questions.length), signal);
+            if (signal?.aborted || this.bot !== bot || this.sessions.get(sessionId) !== endpoint)
+                return null;
+            let answer = await this.waitForQuestionReply(messageId, sessionId, signal);
+            while (true) {
+                if (answer === null || isCancelCommand(answer))
+                    return null;
+                const parsed = parseQuestionAnswer(question, answer);
+                if (parsed) {
+                    selections.push(parsed);
+                    break;
+                }
+                // Re-arm the route before awaiting Telegram feedback. Otherwise a quick
+                // corrected reply can arrive after the invalid reply removed the old
+                // pending entry but before the feedback send completes.
+                const nextAnswer = this.waitForQuestionReply(messageId, sessionId, signal);
+                try {
+                    await bot.sendMessage("Не понял выбор. Ответьте на исходный вопрос номером варианта, несколькими номерами через запятую или своим текстом.", signal);
+                }
+                catch (error) {
+                    this.cancelPendingQuestion(messageId, sessionId);
+                    throw error;
+                }
+                if (signal?.aborted || this.bot !== bot || this.sessions.get(sessionId) !== endpoint) {
+                    this.cancelPendingQuestion(messageId, sessionId);
+                    return null;
+                }
+                answer = await nextAnswer;
+            }
+        }
+        return selections;
+    }
+    createNewSessionRequest(sourceSessionId, task) {
+        const endpoint = this.sessions.get(sourceSessionId);
+        const normalizedTask = task.trim();
+        if (!endpoint || !normalizedTask)
+            return undefined;
+        this.pruneExpiredNewSessionRequests();
+        if ((this.newSessionSources.get(sourceSessionId) ?? 0) > Date.now())
+            return undefined;
+        const requestId = randomUUID();
+        const expiresAt = Date.now() + NEW_SESSION_REQUEST_TTL_MS;
+        this.newSessionRequests.set(requestId, {
+            sourceSessionId,
+            task: normalizedTask,
+            expiresAt,
+        });
+        this.newSessionSources.set(sourceSessionId, expiresAt);
+        try {
+            endpoint.dispatchNewSession(requestId);
+            this.focusSessionId = sourceSessionId;
+            return requestId;
+        }
+        catch (error) {
+            this.newSessionRequests.delete(requestId);
+            this.newSessionSources.delete(sourceSessionId);
+            this.reportError(errorMessage(error));
+            return undefined;
+        }
+    }
+    consumeNewSessionRequest(requestId, sourceSessionId) {
+        this.pruneExpiredNewSessionRequests();
+        const request = this.newSessionRequests.get(requestId);
+        if (!request || request.sourceSessionId !== sourceSessionId)
+            return undefined;
+        this.newSessionRequests.delete(requestId);
+        return request.task;
+    }
+    finishNewSessionRequest(sourceSessionId) {
+        this.newSessionSources.delete(sourceSessionId);
+    }
+    async announceNewSession(sessionId) {
+        const endpoint = this.sessions.get(sessionId);
+        const bot = this.bot;
+        if (!endpoint || !bot)
+            return;
+        const messageId = await bot.sendMessage(`🆕 Новая сессия · ${sessionLabel(endpoint)}\nСессия создана. Задача запускается.`);
+        if (this.bot !== bot || this.sessions.get(sessionId) !== endpoint)
+            return;
+        this.focusSessionId = sessionId;
+        this.rememberCompletionRoute(messageId, sessionId);
+    }
+    async sendStatus() {
+        if (!this.bot)
+            return;
+        const endpoint = this.focusSessionId ? this.sessions.get(this.focusSessionId) : undefined;
+        if (!endpoint) {
+            await this.bot.sendMessage("Нет активной Telegram-сессии. Дождитесь уведомления от Pix или запустите задачу локально.");
+            return;
+        }
+        await this.bot.sendMessage(`${endpoint.isIdle() ? "🟢 idle" : "🟡 busy"} · ${sessionLabel(endpoint)}`);
+    }
+    async sendHelp() {
+        if (!this.bot)
+            return;
+        await this.bot.sendMessage([
+            "Telegram connector",
+            "",
+            "↩️ Ответьте на уведомление — продолжить в той же сессии.",
+            "🆕 /new <задача> — новая сессия (можно ответом на конкретное уведомление).",
+            "📍 /status — текущая сессия.",
+            "❌ /cancel — отменить ожидающий Telegram-вопрос.",
+        ].join("\n"));
+    }
+    async sendNotice(text) {
+        await this.bot?.sendMessage(text);
+    }
+    async handleIncoming(message) {
+        const explicitQuestion = message.replyToMessageId === undefined ? undefined : this.pendingQuestions.get(message.replyToMessageId);
+        if (explicitQuestion) {
+            this.resolvePendingQuestion(message.replyToMessageId, explicitQuestion, message.text);
+            return;
+        }
+        const command = parseTelegramCommand(message.text);
+        if (message.replyToMessageId === undefined
+            && this.pendingQuestions.size === 1
+            && (command.kind === "message" || isCancelCommand(message.text))) {
+            const [messageId, pending] = this.pendingQuestions.entries().next().value;
+            this.resolvePendingQuestion(messageId, pending, message.text);
+            return;
+        }
+        if (message.replyToMessageId === undefined
+            && this.pendingQuestions.size > 1
+            && (command.kind === "message" || isCancelCommand(message.text))) {
+            await this.bot?.sendMessage("Есть несколько ожидающих вопросов. Ответьте reply на конкретное сообщение с вопросом.");
+            return;
+        }
+        if (command.kind === "help") {
+            await this.sendHelp();
+            return;
+        }
+        if (command.kind === "status") {
+            await this.sendStatus();
+            return;
+        }
+        if (message.replyToMessageId === undefined && this.sessions.size > 1) {
+            await this.bot?.sendMessage("Есть несколько живых сессий. Ответьте reply на уведомление нужной сессии, чтобы не отправить задачу не туда.");
+            return;
+        }
+        const routedSessionId = message.replyToMessageId === undefined
+            ? this.focusSessionId
+            : this.completionRoutes.get(message.replyToMessageId);
+        const endpoint = routedSessionId ? this.sessions.get(routedSessionId) : undefined;
+        if (!endpoint) {
+            await this.bot?.sendMessage("Не могу определить живую сессию для этого сообщения. Ответьте на свежее уведомление от Pix.");
+            return;
+        }
+        this.focusSessionId = endpoint.sessionId;
+        if (command.kind === "new") {
+            if (!command.task) {
+                await this.bot?.sendMessage("Использование: /new <задача>");
+                return;
+            }
+            if (this.hasPendingQuestionFor(endpoint.sessionId)) {
+                await this.bot?.sendMessage("Эта сессия ждёт ответа на вопрос. Сначала ответьте на вопрос или отправьте /cancel reply на него.");
+                return;
+            }
+            const requestId = this.createNewSessionRequest(endpoint.sessionId, command.task);
+            await this.bot?.sendMessage(requestId ? "🆕 Создаю новую сессию и передаю задачу." : "Не удалось запустить новую сессию.");
+            return;
+        }
+        try {
+            endpoint.sendUserMessage(command.text);
+            await this.bot?.sendMessage(`➡️ Отправлено · ${sessionLabel(endpoint)}`);
+        }
+        catch (error) {
+            this.reportError(errorMessage(error));
+            await this.bot?.sendMessage("Не удалось отправить сообщение: сессия уже заменена или недоступна.");
+        }
+    }
+    stop() {
+        this.clearStopTimer();
+        this.bot?.stop();
+        this.bot = undefined;
+        this.botKey = undefined;
+        for (const pending of this.pendingQuestions.values())
+            pending.resolve(null);
+        this.pendingQuestions.clear();
+        this.completionRoutes.clear();
+        this.newSessionRequests.clear();
+        this.newSessionSources.clear();
+        this.focusSessionId = undefined;
+    }
+    ensureBot(botToken, chatId) {
+        const key = `${botToken}\u0000${chatId}`;
+        if (this.bot && this.botKey === key)
+            return;
+        this.stop();
+        this.botKey = key;
+        this.bot = this.createBot(botToken, chatId);
+        this.bot.start((message) => this.handleIncoming(message), (error) => this.reportError(error.message));
+    }
+    waitForQuestionReply(messageId, sessionId, signal) {
+        return new Promise((resolve) => {
+            let settled = false;
+            const onAbort = () => settle(null);
+            const settle = (text) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal?.removeEventListener("abort", onAbort);
+                if (this.pendingQuestions.get(messageId)?.resolve === settle)
+                    this.pendingQuestions.delete(messageId);
+                resolve(text);
+            };
+            this.pendingQuestions.set(messageId, { sessionId, resolve: settle });
+            signal?.addEventListener("abort", onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
+        });
+    }
+    resolvePendingQuestion(messageId, pending, text) {
+        this.pendingQuestions.delete(messageId);
+        this.focusSessionId = pending.sessionId;
+        pending.resolve(text);
+    }
+    cancelPendingQuestion(messageId, sessionId) {
+        const pending = this.pendingQuestions.get(messageId);
+        if (!pending || pending.sessionId !== sessionId)
+            return;
+        this.pendingQuestions.delete(messageId);
+        pending.resolve(null);
+    }
+    rememberCompletionRoute(messageId, sessionId) {
+        this.completionRoutes.set(messageId, sessionId);
+        while (this.completionRoutes.size > COMPLETION_ROUTE_LIMIT) {
+            const oldest = this.completionRoutes.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.completionRoutes.delete(oldest);
+        }
+    }
+    hasPendingQuestionFor(sessionId) {
+        return [...this.pendingQuestions.values()].some((pending) => pending.sessionId === sessionId);
+    }
+    pruneExpiredNewSessionRequests() {
+        const now = Date.now();
+        for (const [requestId, request] of this.newSessionRequests) {
+            if (request.expiresAt <= now)
+                this.newSessionRequests.delete(requestId);
+        }
+        for (const [sessionId, expiresAt] of this.newSessionSources) {
+            if (expiresAt <= now)
+                this.newSessionSources.delete(sessionId);
+        }
+    }
+    scheduleStop() {
+        this.clearStopTimer();
+        this.stopTimer = setTimeout(() => {
+            this.stopTimer = undefined;
+            if (this.sessions.size === 0)
+                this.stop();
+        }, STOP_GRACE_MS);
+        this.stopTimer.unref?.();
+    }
+    clearStopTimer() {
+        if (!this.stopTimer)
+            return;
+        clearTimeout(this.stopTimer);
+        this.stopTimer = undefined;
+    }
+}
+export function parseTelegramCommand(text) {
+    const trimmed = text.trim();
+    const commandMatch = /^\/(new|help|status)(?:@[A-Za-z0-9_]+)?(?:\s+([\s\S]*))?$/i.exec(trimmed);
+    if (!commandMatch)
+        return { kind: "message", text: trimmed };
+    const command = commandMatch[1].toLowerCase();
+    if (command === "help")
+        return { kind: "help" };
+    if (command === "status")
+        return { kind: "status" };
+    return { kind: "new", task: commandMatch[2]?.trim() ?? "" };
+}
+export function parseQuestionAnswer(question, answer) {
+    const trimmed = answer.trim();
+    if (!trimmed || isCancelCommand(trimmed))
+        return undefined;
+    const numeric = trimmed.match(/^\d+(?:\s*[, ]\s*\d+)*$/)?.[0];
+    if (!numeric) {
+        if (!question.multiple)
+            return { id: question.id, customText: trimmed };
+        if ((question.minSelections ?? 1) > 1 || (question.maxSelections ?? question.choices.length + 1) < 1)
+            return undefined;
+        return { id: question.id, choiceValues: [], customText: trimmed };
+    }
+    const indexes = numeric.split(/\s*[, ]\s*/).filter(Boolean).map((value) => Number(value));
+    if (indexes.some((index) => !Number.isInteger(index) || index < 1 || index > question.choices.length))
+        return undefined;
+    const unique = [...new Set(indexes)];
+    if (question.multiple) {
+        if (unique.length < (question.minSelections ?? 1) || unique.length > (question.maxSelections ?? question.choices.length + 1))
+            return undefined;
+        return { id: question.id, choiceValues: unique.map((index) => question.choices[index - 1].value) };
+    }
+    if (unique.length !== 1)
+        return undefined;
+    return { id: question.id, choiceValue: question.choices[unique[0] - 1].value };
+}
+function formatCompletionMessage(endpoint, kind, summary) {
+    const heading = kind === "error" ? "🔴 Ошибка" : "✅ Готово";
+    const body = summary?.trim();
+    return [
+        `${heading} · ${sessionLabel(endpoint)}`,
+        ...(body ? ["", body.slice(0, 2500)] : []),
+        "",
+        "↩️ Ответьте на это сообщение — продолжить в этой сессии.",
+        "🆕 /new <задача> — начать новую сессию.",
+    ].join("\n");
+}
+function formatQuestionMessage(endpoint, question, index, total) {
+    const choices = question.choices.map((choice, choiceIndex) => {
+        const description = choice.description ? ` — ${choice.description}` : "";
+        return `${choiceIndex + 1}. ${choice.label}${description}`;
+    });
+    const multipleHint = question.multiple ? "Можно несколько номеров через запятую." : "Можно номер варианта или свой текст.";
+    const lines = [`❓ Вопрос ${total > 1 ? `${index + 1}/${total} · ` : ""}${sessionLabel(endpoint)}`];
+    if (question.label)
+        lines.push(question.label);
+    lines.push(question.prompt);
+    if (choices.length > 0)
+        lines.push("", ...choices);
+    lines.push("", `${multipleHint} /cancel — отменить.`);
+    return lines.join("\n");
+}
+function sessionLabel(endpoint) {
+    const title = endpoint.getTitle().trim() || endpoint.sessionId.slice(0, 8);
+    const project = basename(endpoint.cwd) || endpoint.cwd;
+    return title === project ? title : `${title} · ${project}`;
+}
+function isCancelCommand(text) {
+    return /^\/cancel(?:@[A-Za-z0-9_]+)?$/i.test(text.trim());
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+const COORDINATOR_KEY = Symbol.for("pix.telegram.connector.coordinator.v1");
+export function getTelegramConnectorCoordinator() {
+    const root = globalThis;
+    root[COORDINATOR_KEY] ??= new TelegramConnectorCoordinator();
+    return root[COORDINATOR_KEY];
+}
+export function resetTelegramConnectorCoordinatorForTests() {
+    const root = globalThis;
+    root[COORDINATOR_KEY]?.stop();
+    delete root[COORDINATOR_KEY];
+}

package/dist/bundled-extensions/telegram-connector/index.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function telegramConnector(pi: ExtensionAPI): void;
+export declare function assistantVisibleText(message: unknown): string | undefined;

package/dist/bundled-extensions/telegram-connector/index.js

@@ -0,0 +1,195 @@
+import { registerRemoteQuestionHandler } from "../question/remote.js";
+import { resolveTelegramConnectorConfig } from "./config.js";
+import { getTelegramConnectorCoordinator } from "./coordinator.js";
+const INTERNAL_NEW_SESSION_COMMAND = "telegram-new-session";
+const SESSION_ABORTED_EVENT = "pix:session-aborted";
+export default function telegramConnector(pi) {
+    const config = resolveTelegramConnectorConfig();
+    const coordinator = getTelegramConnectorCoordinator();
+    let currentCtx;
+    let attachedSessionId;
+    let attachedEndpoint;
+    let unregisterRemoteQuestion;
+    let lastAssistantText;
+    let lastFailureReason;
+    let userAborted = false;
+    function attach(ctx) {
+        currentCtx = ctx;
+        const sessionId = ctx.sessionManager.getSessionId();
+        if (attachedSessionId === sessionId)
+            return;
+        if (attachedSessionId)
+            coordinator.detachSession(attachedSessionId, attachedEndpoint);
+        unregisterRemoteQuestion?.();
+        attachedSessionId = sessionId;
+        const endpoint = {
+            sessionId,
+            cwd: ctx.cwd,
+            getTitle: () => safeSessionTitle(pi, currentCtx, sessionId),
+            isIdle: () => safeIsIdle(currentCtx),
+            sendUserMessage: (text) => {
+                const options = safeIsIdle(currentCtx) ? undefined : { deliverAs: "followUp" };
+                pi.sendUserMessage(text, options);
+            },
+            dispatchNewSession: (requestId) => {
+                const options = {
+                    ...(safeIsIdle(currentCtx) ? {} : { deliverAs: "followUp" }),
+                    expandPromptTemplates: true,
+                };
+                pi.sendUserMessage(`/${INTERNAL_NEW_SESSION_COMMAND} ${requestId}`, options);
+            },
+        };
+        attachedEndpoint = endpoint;
+        coordinator.attachSession(endpoint, config);
+        unregisterRemoteQuestion = registerRemoteQuestionHandler(sessionId, (questions, signal) => coordinator.askQuestions(sessionId, questions, signal));
+    }
+    function detach() {
+        unregisterRemoteQuestion?.();
+        unregisterRemoteQuestion = undefined;
+        if (attachedSessionId)
+            coordinator.detachSession(attachedSessionId, attachedEndpoint);
+        attachedSessionId = undefined;
+        attachedEndpoint = undefined;
+        currentCtx = undefined;
+    }
+    pi.registerCommand("tg", {
+        description: "Show Telegram connector status",
+        handler: async (_args, ctx) => {
+            attach(ctx);
+            if (!config.enabled || !config.botToken || !config.chatId) {
+                ctx.ui.notify("Telegram connector is not configured. Set telegramConnector.botToken/chatId or PIX_TELEGRAM_* env vars.", "warning");
+                return;
+            }
+            ctx.ui.notify("Telegram connector is active for this Pix process.", "info");
+            void coordinator.sendStatus().catch(() => { });
+        },
+    });
+    // Internal command dispatched through sendUserMessage(expandPromptTemplates=true).
+    // This intentionally obtains a fresh ExtensionCommandContext at execution time,
+    // instead of keeping command contexts alive across async Telegram callbacks.
+    pi.registerCommand(INTERNAL_NEW_SESSION_COMMAND, {
+        description: "Internal Telegram connector session handoff",
+        handler: async (args, ctx) => {
+            const sourceSessionId = ctx.sessionManager.getSessionId();
+            const requestId = args.trim();
+            const task = coordinator.consumeNewSessionRequest(requestId, sourceSessionId);
+            if (!task)
+                return;
+            try {
+                await ctx.waitForIdle();
+                const result = await ctx.newSession({
+                    withSession: async (nextCtx) => {
+                        const nextSessionId = nextCtx.sessionManager.getSessionId();
+                        // Start both operations from the fresh replacement context, but do not
+                        // make the agent turn wait for Telegram delivery (or vice versa).
+                        // The Bot API call is started first so the normal case shows the new-
+                        // session card before that session eventually reports completion.
+                        void coordinator.announceNewSession(nextSessionId).catch(() => { });
+                        void nextCtx.sendUserMessage(task, { expandPromptTemplates: false }).catch(() => {
+                            void coordinator.sendNotice("Новая сессия создана, но задачу запустить не удалось.").catch(() => { });
+                        });
+                    },
+                });
+                if (result.cancelled) {
+                    void coordinator.sendNotice("Новая сессия не была создана.").catch(() => { });
+                }
+            }
+            catch {
+                void coordinator.sendNotice("Не удалось создать новую сессию.").catch(() => { });
+            }
+            finally {
+                coordinator.finishNewSessionRequest(sourceSessionId);
+            }
+        },
+    });
+    pi.on("session_start", async (_event, ctx) => {
+        attach(ctx);
+    });
+    pi.on("agent_start", async (_event, ctx) => {
+        attach(ctx);
+        lastAssistantText = undefined;
+        lastFailureReason = undefined;
+        userAborted = false;
+    });
+    pi.on("message_end", async (event, ctx) => {
+        attach(ctx);
+        const text = assistantVisibleText(event.message);
+        if (text)
+            lastAssistantText = text;
+    });
+    pi.on("message_update", async (event, ctx) => {
+        attach(ctx);
+        const update = event.assistantMessageEvent;
+        if (update.type === "error" && update.reason === "aborted") {
+            userAborted = true;
+            lastFailureReason = undefined;
+            return;
+        }
+        if (update.type === "error") {
+            const reason = typeof update.error?.errorMessage === "string" ? update.error.errorMessage.trim() : "";
+            if (reason)
+                lastFailureReason = reason;
+            return;
+        }
+        if (typeof update.type === "string")
+            lastFailureReason = undefined;
+    });
+    pi.events.on(SESSION_ABORTED_EVENT, (data) => {
+        if (isRecord(data) && data.aborted === true) {
+            userAborted = true;
+            lastFailureReason = undefined;
+        }
+    });
+    pi.on("agent_settled", (_event, ctx) => {
+        attach(ctx);
+        if (userAborted || !attachedSessionId)
+            return;
+        const sessionId = attachedSessionId;
+        const summary = lastFailureReason ?? lastAssistantText;
+        void coordinator.notifyCompletion(sessionId, lastFailureReason ? "error" : "complete", summary).catch(() => {
+            // Telegram is an optional notification channel and must never delay or fail the run.
+        });
+    });
+    pi.on("session_shutdown", async () => {
+        detach();
+    });
+}
+export function assistantVisibleText(message) {
+    if (!isRecord(message) || message.role !== "assistant")
+        return undefined;
+    const content = message.content;
+    if (typeof content === "string")
+        return normalizedText(content);
+    if (!Array.isArray(content))
+        return undefined;
+    const text = content.flatMap((part) => {
+        if (!isRecord(part) || part.type !== "text" || typeof part.text !== "string")
+            return [];
+        return [part.text];
+    }).join("\n");
+    return normalizedText(text);
+}
+function safeSessionTitle(pi, ctx, sessionId) {
+    try {
+        const title = pi.getSessionName()?.trim() || ctx?.sessionManager.getSessionName?.()?.trim();
+        return title || sessionId.slice(0, 8);
+    }
+    catch {
+        return sessionId.slice(0, 8);
+    }
+}
+function safeIsIdle(ctx) {
+    try {
+        return ctx?.isIdle() ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizedText(text) {
+    const normalized = text.trim();
+    return normalized || undefined;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}