pulseed 0.6.5 → 0.6.6

package/dist/runtime/gateway/telegram-gateway-adapter.js

@@ -1,13 +1,33 @@
-import * as fs from "node:fs";
 import * as path from "node:path";
-import { dispatchGatewayChatInput } from "./chat-session-dispatch.js";
+import { loadGatewayConfigJson } from "./config-json.js";
+import { GATEWAY_CHAT_DISPATCH_FAILURE_MESSAGE, dispatchGatewayChatInputResult, formatGatewayChatDispatchFailure, } from "./chat-session-dispatch.js";
 import { formatTelegramNotification, supportsCoreGatewayNotification } from "./core-channel-notification.js";
-import { writeJsonFileAtomic } from "../../base/utils/json-io.js";
-import { evaluateChannelAccess, resolveChannelRoute } from "./channel-policy.js";
-import { createRefreshingTypingIndicator, withTypingIndicator } from "./typing-indicator.js";
+import { buildChannelPolicyMetadata, buildExternalSurfaceDecision, evaluateChannelAccess, resolveChannelRoute } from "./channel-policy.js";
+import { createRefreshingTypingIndicator } from "./typing-indicator.js";
 import { TELEGRAM_GATEWAY_DISPLAY_CONTRACT, createGatewayDisplayPolicy } from "./channel-display-policy.js";
+import { TELEGRAM_SEEDY_PRESENCE_CONTRACT, resolveGatewayChannelPresenceContract } from "./channel-presence-policy.js";
 import { NonTuiDisplayProjector } from "./non-tui-display-projector.js";
+import { SeedyPresenceProjector, createSeedyPresenceTransportFromNonTuiDisplay } from "./seedy-presence-projector.js";
+import { PluginChannelRuntimeStateStore } from "../store/plugin-channel-runtime-state-store.js";
+import { createUserVisibleSeedyTurnPresence } from "../../interface/chat/seedy-turn-presence.js";
 const BACKOFF_STEPS_MS = [5_000, 10_000, 20_000, 40_000, 60_000];
+const TELEGRAM_INTEGER_ID_TOKEN = /^-?(?:0|[1-9]\d*)$/;
+const MIN_POLLING_TIMEOUT_SECONDS = 1;
+const MAX_POLLING_TIMEOUT_SECONDS = 60;
+function parseTelegramIntegerId(value) {
+    const normalized = value.trim();
+    if (!TELEGRAM_INTEGER_ID_TOKEN.test(normalized))
+        return null;
+    const parsed = Number(normalized);
+    return Number.isSafeInteger(parsed) ? parsed : null;
+}
+function parseTelegramMessageRef(ref) {
+    const messageId = parseTelegramIntegerId(ref.id);
+    if (messageId === null) {
+        throw new Error(`telegram-display: invalid message reference "${ref.id}"`);
+    }
+    return messageId;
+}
 export class TelegramGatewayNotifier {
     api;
     homeChatStore;
@@ -31,35 +51,48 @@ export class TelegramGatewayAdapter {
     name = "telegram";
     typingIndicator;
     displayContract = TELEGRAM_GATEWAY_DISPLAY_CONTRACT;
+    presenceContract = TELEGRAM_SEEDY_PRESENCE_CONTRACT;
     handler = null;
     api;
     config;
-    pluginDir;
+    channelName;
+    runtimeStateStore;
+    timing;
     homeChatStore;
     notifier;
     running = false;
     loopPromise = null;
     handlingUpdate = false;
     offset = 0;
-    constructor(pluginDir, config) {
-        this.pluginDir = pluginDir;
+    constructor(pluginDir, config, options = {}) {
         this.config = config;
+        this.channelName = options.channelName ?? inferGatewayChannelName(pluginDir);
+        this.runtimeStateStore = options.runtimeStateStore ?? new PluginChannelRuntimeStateStore(inferGatewayRuntimeBaseDir(pluginDir));
+        this.timing = new TelegramGatewayTimingRecorder(this.name);
         this.api = new TelegramAPI(config.bot_token);
         this.typingIndicator = createRefreshingTypingIndicator({
             intervalMs: 4_000,
             refresh: async (context) => {
-                const chatId = Number(context.conversation_id);
-                if (!Number.isInteger(chatId))
+                const chatId = parseTelegramIntegerId(context.conversation_id);
+                if (chatId === null)
                     return;
-                await this.api.sendChatAction(chatId, "typing");
+                try {
+                    await this.timing.recordOutbound("typing", () => this.api.sendChatAction(chatId, "typing"));
+                }
+                finally {
+                    await this.recordTiming();
+                }
             },
             onError: (err) => console.warn("TelegramGatewayAdapter: typing indicator failed", err),
         });
-        this.homeChatStore = new TelegramHomeChatStore(pluginDir, config.chat_id);
+        this.homeChatStore = new TelegramHomeChatStore(this.channelName, this.runtimeStateStore, config.chat_id);
         this.notifier = new TelegramGatewayNotifier(this.api, this.homeChatStore);
     }
     static fromConfigDir(configDir) {
-        return new TelegramGatewayAdapter(configDir, loadTelegramGatewayConfig(configDir));
+        return new TelegramGatewayAdapter(configDir, loadTelegramGatewayConfig(configDir), {
+            channelName: inferGatewayChannelName(configDir),
+            runtimeStateStore: new PluginChannelRuntimeStateStore(inferGatewayRuntimeBaseDir(configDir)),
+        });
     }
     getNotifier() {
         return this.notifier;
@@ -70,6 +103,7 @@ export class TelegramGatewayAdapter {
     async start() {
         if (this.running)
             return;
+        await this.homeChatStore.load();
         await this.api.getMe();
         this.running = true;
         this.loopPromise = this.loop().catch(() => undefined);
@@ -85,7 +119,10 @@ export class TelegramGatewayAdapter {
         let backoffIndex = 0;
         while (this.running) {
             try {
+                const poll = this.timing.beginPoll(this.offset, this.config.polling_timeout);
                 const updates = await this.api.getUpdates(this.offset, this.config.polling_timeout);
+                this.timing.completePoll(poll, { updateCount: updates.length, ok: true });
+                await this.recordTiming();
                 backoffIndex = 0;
                 for (const update of updates) {
                     this.offset = update.update_id + 1;
@@ -106,13 +143,13 @@ export class TelegramGatewayAdapter {
                     try {
                         if (this.isFirstHomeBindingCommand(msg.text, fromId)) {
                             await this.recordHealth({ last_inbound_at: new Date().toISOString(), last_error: null });
-                            await this.processMessage(msg.text, fromId, chatId, msg.message_id);
+                            await this.processMessage(msg.text, fromId, chatId, msg.message_id, update.update_id);
                             continue;
                         }
-                        if (!this.config.allow_all && !this.config.allowed_user_ids.includes(fromId))
+                        if (!this.config.allow_all && !this.effectiveAllowedUserIds().includes(fromId))
                             continue;
                         await this.recordHealth({ last_inbound_at: new Date().toISOString(), last_error: null });
-                        await this.processMessage(msg.text, fromId, chatId, msg.message_id);
+                        await this.processMessage(msg.text, fromId, chatId, msg.message_id, update.update_id);
                     }
                     finally {
                         this.handlingUpdate = false;
@@ -120,7 +157,11 @@ export class TelegramGatewayAdapter {
                 }
             }
             catch (err) {
-                await this.recordHealth({ last_error: err instanceof Error ? err.message : String(err) });
+                this.timing.completeOpenPoll({ ok: false, error: err });
+                await this.recordHealth({
+                    last_error: err instanceof Error ? err.message : String(err),
+                    last_timing: this.timing.snapshot(),
+                });
                 if (!this.running)
                     break;
                 const delay = BACKOFF_STEPS_MS[Math.min(backoffIndex, BACKOFF_STEPS_MS.length - 1)];
@@ -129,97 +170,163 @@ export class TelegramGatewayAdapter {
             }
         }
     }
-    async processMessage(text, fromUserId, chatId, messageId) {
+    async processMessage(text, fromUserId, chatId, messageId, updateId) {
+        this.timing.beginTurn({ updateId, messageId });
+        await this.recordTiming();
         const normalized = text.trim().toLowerCase();
         if (normalized === "/sethome" || normalized.startsWith("/sethome@")) {
-            const firstBinding = this.config.allowed_user_ids.length === 0 && this.config.chat_id === undefined && !this.config.allow_all;
+            const firstBinding = this.config.allowed_user_ids.length === 0 && this.homeChatStore.get() === undefined && !this.config.allow_all;
             await this.homeChatStore.set(chatId, firstBinding ? fromUserId : undefined);
-            this.config.chat_id = chatId;
-            if (firstBinding)
-                this.config.allowed_user_ids.push(fromUserId);
-            await this.api.sendPlainMessage(chatId, firstBinding
+            await this.timing.recordOutbound("sethome_send", () => this.api.sendPlainMessage(chatId, firstBinding
                 ? "This chat is now the home channel for PulSeed notifications, and this Telegram user is allowed for normal chat. Runtime control still requires its own allow list."
-                : "This chat is now the home channel for PulSeed notifications.");
+                : "This chat is now the home channel for PulSeed notifications."));
+            this.timing.markLifecycleEnd();
+            await this.recordTiming();
             await this.recordHealth({ last_outbound_at: new Date().toISOString(), last_error: null });
             return;
         }
-        const eventAdapter = new TelegramChatEventAdapter(this.api, chatId);
+        const eventAdapter = new TelegramChatEventAdapter(this.api, chatId, this.timing, () => this.recordTiming());
+        const context = {
+            platform: "telegram",
+            senderId: String(fromUserId),
+            conversationId: String(chatId),
+            channelId: String(chatId),
+        };
         const route = resolveChannelRoute({
             identityKey: this.config.identity_key,
             conversationGoalMap: this.config.chat_goal_map,
             senderGoalMap: this.config.user_goal_map,
             defaultGoalId: this.config.default_goal_id,
-        }, {
-            platform: "telegram",
-            senderId: String(fromUserId),
-            conversationId: String(chatId),
-            channelId: String(chatId),
-        });
+        }, context);
         const access = evaluateChannelAccess({
-            allowedSenderIds: this.config.allow_all ? undefined : this.config.allowed_user_ids.map(String),
+            allowedSenderIds: this.config.allow_all ? undefined : this.effectiveAllowedUserIds().map(String),
             deniedSenderIds: this.config.denied_user_ids.map(String),
             allowedConversationIds: this.config.allowed_chat_ids.map(String),
             deniedConversationIds: this.config.denied_chat_ids.map(String),
             runtimeControlAllowedSenderIds: this.config.runtime_control_allowed_user_ids.map(String),
-        }, {
-            platform: "telegram",
-            senderId: String(fromUserId),
-            conversationId: String(chatId),
-            channelId: String(chatId),
-        });
+        }, context);
         if (!access.allowed) {
             return;
         }
-        const reply = await withTypingIndicator(this.typingIndicator, {
-            platform: "telegram",
-            conversation_id: String(chatId),
-            sender_id: String(fromUserId),
-            message_id: String(messageId),
-        }, () => dispatchGatewayChatInput({
-            text,
-            platform: "telegram",
-            identity_key: route.identityKey ?? this.config.identity_key,
-            conversation_id: String(chatId),
-            sender_id: String(fromUserId),
-            message_id: String(messageId),
-            goal_id: route.goalId,
-            cwd: process.cwd(),
-            onEvent: (event) => eventAdapter.handle(event),
-            metadata: {
-                ...route.metadata,
-                chat_id: chatId,
-                ...(route.goalId ? { goal_id: route.goalId } : {}),
-                ...(access.runtimeControlApproved ? { runtime_control_approved: true } : {}),
-                ...(access.runtimeControlConfigured && !access.runtimeControlApproved ? { runtime_control_denied: true } : {}),
+        const externalSurface = buildExternalSurfaceDecision(context, access, route);
+        const presenceProjector = new SeedyPresenceProjector({
+            presence: resolveGatewayChannelPresenceContract(this.presenceContract),
+            transport: eventAdapter.presenceTransport,
+            typingIndicator: this.typingIndicator,
+            typingContext: {
+                platform: "telegram",
+                conversation_id: String(chatId),
+                sender_id: String(fromUserId),
+                message_id: String(messageId),
             },
-        }));
-        if (!eventAdapter.renderedAssistantOutput) {
-            await eventAdapter.sendFinalFallback(reply ?? "Received.");
+            onError: (error, operation) => console.warn("TelegramGatewayAdapter: presence projector failed", { operation, error }),
+        });
+        let reply = null;
+        let dispatchCompleted = false;
+        let dispatchError = null;
+        try {
+            await presenceProjector.update(createUserVisibleSeedyTurnPresence({
+                turn_id: `telegram:${chatId}:${messageId}`,
+                phase: "received",
+            }));
+            const dispatchResult = await dispatchGatewayChatInputResult({
+                text,
+                platform: "telegram",
+                identity_key: route.identityKey ?? this.config.identity_key,
+                conversation_id: String(chatId),
+                sender_id: String(fromUserId),
+                message_id: String(messageId),
+                goal_id: route.goalId,
+                cwd: process.cwd(),
+                onEvent: async (event) => {
+                    const chatEvent = event;
+                    const shouldRender = eventAdapter.shouldRender(chatEvent);
+                    if (shouldRender) {
+                        await presenceProjector.prepareForEvent(chatEvent);
+                        await eventAdapter.handle(chatEvent);
+                    }
+                    await presenceProjector.handle(chatEvent, {
+                        assistantOutputRendered: eventAdapter.deliveredAssistantOutput,
+                        meaningfulProgressRendered: eventAdapter.deliveredProgressOutput,
+                    });
+                },
+                externalSurface,
+                metadata: {
+                    ...buildChannelPolicyMetadata(context, access, route, externalSurface),
+                    chat_id: chatId,
+                    ...(route.goalId ? { goal_id: route.goalId } : {}),
+                },
+            });
+            if (dispatchResult.status === "ok") {
+                reply = dispatchResult.text;
+            }
+            else {
+                reply = formatGatewayChatDispatchFailure(dispatchResult.error);
+                dispatchError = dispatchResult.error;
+            }
+            dispatchCompleted = true;
         }
-        await this.recordHealth({ last_outbound_at: new Date().toISOString(), last_error: null });
+        catch (error) {
+            dispatchError = error;
+            reply = formatGatewayChatDispatchFailure(error instanceof Error ? error.message : String(error));
+            dispatchCompleted = true;
+        }
+        finally {
+            try {
+                if (dispatchCompleted && !eventAdapter.renderedAssistantOutput) {
+                    const fallbackText = reply ?? GATEWAY_CHAT_DISPATCH_FAILURE_MESSAGE;
+                    await presenceProjector.prepareForEvent({
+                        type: "assistant_final",
+                        runId: "fallback",
+                        turnId: "fallback",
+                        createdAt: new Date().toISOString(),
+                        text: fallbackText,
+                        persisted: false,
+                    });
+                    await eventAdapter.sendFinalFallback(fallbackText);
+                }
+            }
+            finally {
+                await presenceProjector.stop();
+            }
+        }
+        this.timing.markLifecycleEnd();
+        await this.recordTiming();
+        await this.recordHealth({
+            last_outbound_at: new Date().toISOString(),
+            last_error: reply === null
+                ? GATEWAY_CHAT_DISPATCH_FAILURE_MESSAGE
+                : dispatchError instanceof Error
+                    ? dispatchError.message
+                    : dispatchError === null
+                        ? null
+                        : String(dispatchError),
+        });
     }
     isFirstHomeBindingCommand(text, fromUserId) {
         const normalized = text.trim().toLowerCase();
         return (normalized === "/sethome" || normalized.startsWith("/sethome@"))
             && !this.config.allow_all
-            && this.config.chat_id === undefined
+            && this.homeChatStore.get() === undefined
             && this.config.allowed_user_ids.length === 0
             && !this.config.denied_user_ids.includes(fromUserId);
     }
     async recordHealth(update) {
-        const healthPath = path.join(this.pluginDir, "health.json");
-        let current = {};
+        await this.runtimeStateStore.saveChannelHealth(this.channelName, update);
+    }
+    async recordTiming() {
         try {
-            current = JSON.parse(fs.readFileSync(healthPath, "utf-8"));
+            await this.recordHealth({ last_timing: this.timing.snapshot() });
         }
-        catch {
-            current = {};
+        catch (error) {
+            console.warn("TelegramGatewayAdapter: timing instrumentation failed", error);
         }
-        await writeJsonFileAtomic(healthPath, {
-            ...current,
-            ...update,
-            updated_at: new Date().toISOString(),
-        });
+    }
+    effectiveAllowedUserIds() {
+        if (this.config.allowed_user_ids.length > 0)
+            return this.config.allowed_user_ids;
+        const firstBoundUserId = this.homeChatStore.getFirstBoundUserId();
+        return firstBoundUserId !== undefined ? [firstBoundUserId] : [];
     }
 }
 class TelegramAPI {
@@ -304,43 +411,63 @@ class TelegramAPI {
     }
 }
 class TelegramHomeChatStore {
-    configPath;
+    channelName;
+    runtimeStateStore;
+    initialChatId;
     chatId;
-    constructor(pluginDir, initialChatId) {
-        this.configPath = path.join(pluginDir, "config.json");
+    firstBoundUserId;
+    constructor(channelName, runtimeStateStore, initialChatId) {
+        this.channelName = channelName;
+        this.runtimeStateStore = runtimeStateStore;
+        this.initialChatId = initialChatId;
         this.chatId = initialChatId;
     }
+    async load() {
+        const binding = await this.runtimeStateStore.loadChannelBinding(this.channelName);
+        if (binding?.home_target_id !== null && binding?.home_target_id !== undefined) {
+            const parsedChatId = parseTelegramIntegerId(binding.home_target_id);
+            if (parsedChatId !== null)
+                this.chatId = parsedChatId;
+        }
+        else {
+            this.chatId = this.initialChatId;
+        }
+        if (binding?.first_bound_actor_id !== null && binding?.first_bound_actor_id !== undefined) {
+            const parsedUserId = parseTelegramIntegerId(binding.first_bound_actor_id);
+            if (parsedUserId !== null)
+                this.firstBoundUserId = parsedUserId;
+        }
+    }
     get() {
         return this.chatId;
     }
+    getFirstBoundUserId() {
+        return this.firstBoundUserId;
+    }
     async set(chatId, firstAllowedUserId) {
         this.chatId = chatId;
-        let current = {};
-        try {
-            current = JSON.parse(fs.readFileSync(this.configPath, "utf-8"));
-        }
-        catch {
-            current = {};
-        }
-        current["chat_id"] = chatId;
-        if (firstAllowedUserId !== undefined && !Array.isArray(current["allowed_user_ids"])) {
-            current["allowed_user_ids"] = [firstAllowedUserId];
-        }
-        else if (firstAllowedUserId !== undefined) {
-            const ids = current["allowed_user_ids"];
-            if (!ids.includes(firstAllowedUserId))
-                current["allowed_user_ids"] = [...ids, firstAllowedUserId];
-        }
-        await writeJsonFileAtomic(this.configPath, current);
+        if (firstAllowedUserId !== undefined)
+            this.firstBoundUserId = firstAllowedUserId;
+        await this.runtimeStateStore.saveChannelBinding(this.channelName, {
+            home_target_id: String(chatId),
+            first_bound_actor_id: firstAllowedUserId !== undefined ? String(firstAllowedUserId) : undefined,
+        });
     }
 }
 class TelegramChatEventAdapter {
     api;
     chatId;
+    timing;
+    onTimingUpdated;
     projector;
-    constructor(api, chatId) {
+    presenceTransport;
+    constructor(api, chatId, timing, onTimingUpdated) {
         this.api = api;
         this.chatId = chatId;
+        this.timing = timing;
+        this.onTimingUpdated = onTimingUpdated;
+        const transport = new TelegramDisplayTransport(api, chatId, timing, onTimingUpdated);
+        this.presenceTransport = createSeedyPresenceTransportFromNonTuiDisplay(transport);
         this.projector = new NonTuiDisplayProjector({
             display: {
                 capabilities: TELEGRAM_GATEWAY_DISPLAY_CONTRACT.capabilities,
@@ -348,22 +475,35 @@ class TelegramChatEventAdapter {
                     ...createGatewayDisplayPolicy(TELEGRAM_GATEWAY_DISPLAY_CONTRACT.capabilities),
                     progressSurface: "editable",
                     finalSurface: "edit_stream",
-                    cleanupPolicy: "delete",
+                    cleanupPolicy: "collapse",
                 },
             },
-            transport: new TelegramDisplayTransport(api, chatId),
+            transport,
         });
     }
     get renderedAssistantOutput() {
         return this.projector.renderedAssistantOutput;
     }
+    get deliveredAssistantOutput() {
+        return this.projector.deliveredAssistantOutput;
+    }
+    get deliveredProgressOutput() {
+        return this.projector.deliveredProgressOutput;
+    }
     async handle(event) {
-        if (event.type === "operation_progress" && event.item.metadata?.["source"] === "agent_timeline_activity_summary")
-            return;
-        if (event.type === "agent_timeline" && event.item.visibility !== "user")
+        if (!this.shouldRender(event))
             return;
         await this.projector.handle(event);
     }
+    shouldRender(event) {
+        if (event.type === "operation_progress" && event.item.metadata?.["source"] === "agent_timeline_activity_summary")
+            return false;
+        if (event.type === "agent_timeline" && event.item.visibility !== "user")
+            return false;
+        if (this.projector.deliveredAssistantOutput && isNonTerminalProgressEvent(event))
+            return false;
+        return true;
+    }
     async sendFinalFallback(text) {
         if (!text.trim())
             return;
@@ -380,30 +520,185 @@ class TelegramChatEventAdapter {
 class TelegramDisplayTransport {
     api;
     chatId;
-    constructor(api, chatId) {
+    timing;
+    onTimingUpdated;
+    constructor(api, chatId, timing, onTimingUpdated) {
         this.api = api;
         this.chatId = chatId;
+        this.timing = timing;
+        this.onTimingUpdated = onTimingUpdated;
     }
     async sendProgress(text) {
-        const messageId = await this.api.sendPlainMessage(this.chatId, text);
+        const messageId = await this.record("progress_send", () => this.api.sendPlainMessage(this.chatId, text));
         return { id: String(messageId) };
     }
     async editProgress(ref, text) {
-        await this.api.editMessageText(this.chatId, Number(ref.id), text);
+        await this.record("progress_edit", () => this.api.editMessageText(this.chatId, parseTelegramMessageRef(ref), text));
     }
     async deleteProgress(ref) {
-        await this.api.deleteMessage(this.chatId, Number(ref.id));
+        await this.record("progress_delete", () => this.api.deleteMessage(this.chatId, parseTelegramMessageRef(ref)));
     }
     async sendFinal(text) {
-        const messageId = await this.api.sendPlainMessage(this.chatId, text);
+        const messageId = await this.record("final_send", () => this.api.sendPlainMessage(this.chatId, text));
         return { id: String(messageId) };
     }
     async editFinal(ref, text) {
-        await this.api.editMessageText(this.chatId, Number(ref.id), text);
+        await this.record("final_edit", () => this.api.editMessageText(this.chatId, parseTelegramMessageRef(ref), text));
+    }
+    async record(kind, fn) {
+        try {
+            return await this.timing.recordOutbound(kind, fn);
+        }
+        finally {
+            await this.onTimingUpdated();
+        }
+    }
+}
+function isNonTerminalProgressEvent(event) {
+    switch (event.type) {
+        case "operation_progress":
+        case "activity":
+        case "agent_timeline":
+        case "tool_start":
+        case "tool_update":
+        case "tool_end":
+            return true;
+        case "assistant_delta":
+        case "assistant_final":
+        case "lifecycle_error":
+        case "surface_delivery":
+        case "lifecycle_end":
+        case "lifecycle_start":
+        case "presence_update":
+        case "turn_steer":
+        case "user_feedback":
+            return false;
     }
 }
+class TelegramGatewayTimingRecorder {
+    channel;
+    openPoll = null;
+    lastPoll;
+    turn;
+    constructor(channel) {
+        this.channel = channel;
+    }
+    beginPoll(offset, timeoutSeconds) {
+        const token = {
+            startedAtMs: Date.now(),
+            startedAt: new Date().toISOString(),
+            offset,
+            timeoutSeconds,
+        };
+        this.openPoll = token;
+        return token;
+    }
+    completePoll(token, result) {
+        this.lastPoll = {
+            started_at: token.startedAt,
+            completed_at: new Date().toISOString(),
+            duration_ms: elapsedMs(token.startedAtMs),
+            offset: token.offset,
+            timeout_seconds: token.timeoutSeconds,
+            update_count: result.updateCount,
+            ok: result.ok,
+            ...(result.error ? { error_class: errorClass(result.error) } : {}),
+        };
+        if (this.openPoll === token)
+            this.openPoll = null;
+    }
+    completeOpenPoll(result) {
+        if (this.openPoll === null)
+            return;
+        this.completePoll(this.openPoll, {
+            updateCount: 0,
+            ok: result.ok,
+            error: result.error,
+        });
+    }
+    beginTurn(input) {
+        this.turn = {
+            turn_ref: `telegram:message:${input.messageId}`,
+            ...(input.updateId !== undefined ? { update_id: input.updateId } : {}),
+            message_id: input.messageId,
+            inbound_admitted_at: new Date().toISOString(),
+            outbound_calls: [],
+        };
+    }
+    markLifecycleEnd() {
+        if (!this.turn)
+            return;
+        this.turn = {
+            ...this.turn,
+            lifecycle_end_at: new Date().toISOString(),
+        };
+    }
+    async recordOutbound(kind, fn) {
+        const startedAtMs = Date.now();
+        const startedAt = new Date().toISOString();
+        try {
+            const result = await fn();
+            this.appendOutbound({
+                kind,
+                started_at: startedAt,
+                completed_at: new Date().toISOString(),
+                duration_ms: elapsedMs(startedAtMs),
+                ok: true,
+            });
+            return result;
+        }
+        catch (error) {
+            this.appendOutbound({
+                kind,
+                started_at: startedAt,
+                completed_at: new Date().toISOString(),
+                duration_ms: elapsedMs(startedAtMs),
+                ok: false,
+                error_class: errorClass(error),
+            });
+            throw error;
+        }
+    }
+    snapshot() {
+        return {
+            schema_version: "gateway-channel-timing-v1",
+            channel: this.channel,
+            ...(this.lastPoll ? { poll: this.lastPoll } : {}),
+            ...(this.turn ? { turn: this.turn } : {}),
+        };
+    }
+    appendOutbound(call) {
+        if (!this.turn)
+            return;
+        const firstAt = firstOutboundTimestamp(this.turn, call.kind);
+        this.turn = {
+            ...this.turn,
+            ...(call.ok && call.kind === "typing" && firstAt === undefined ? { first_typing_at: call.completed_at } : {}),
+            ...(call.ok && call.kind === "progress_send" && firstAt === undefined ? { first_progress_at: call.completed_at } : {}),
+            ...(call.ok && (call.kind === "final_send" || call.kind === "final_edit") && firstAt === undefined ? { first_final_at: call.completed_at } : {}),
+            outbound_calls: [...this.turn.outbound_calls, call].slice(-32),
+        };
+    }
+}
+function firstOutboundTimestamp(turn, kind) {
+    if (kind === "typing")
+        return turn.first_typing_at;
+    if (kind === "progress_send")
+        return turn.first_progress_at;
+    if (kind === "final_send" || kind === "final_edit")
+        return turn.first_final_at;
+    return undefined;
+}
+function elapsedMs(startedAtMs) {
+    return Math.max(0, Date.now() - startedAtMs);
+}
+function errorClass(error) {
+    if (error instanceof Error && error.name)
+        return error.name;
+    return typeof error;
+}
 function loadTelegramGatewayConfig(pluginDir) {
-    const raw = JSON.parse(fs.readFileSync(path.join(pluginDir, "config.json"), "utf-8"));
+    const raw = loadGatewayConfigJson(pluginDir, "telegram-bot");
     const allowedUserIds = raw["allowed_user_ids"] ?? [];
     const deniedUserIds = raw["denied_user_ids"] ?? raw["deny_from"] ?? [];
     const allowedChatIds = raw["allowed_chat_ids"] ?? [];
@@ -415,17 +710,17 @@ function loadTelegramGatewayConfig(pluginDir) {
     const userGoalMap = raw["user_goal_map"] ?? {};
     assertNonEmptyString(raw["bot_token"], "telegram-bot: bot_token must be a non-empty string");
     if (raw["chat_id"] !== undefined) {
-        assertInteger(raw["chat_id"], "telegram-bot: chat_id must be an integer when set");
+        assertInteger(raw["chat_id"], "telegram-bot: chat_id must be a safe integer when set");
     }
-    assertIntegerArray(allowedUserIds, "telegram-bot: allowed_user_ids must be an array of integers");
-    assertIntegerArray(deniedUserIds, "telegram-bot: denied_user_ids must be an array of integers");
-    assertIntegerArray(allowedChatIds, "telegram-bot: allowed_chat_ids must be an array of integers");
-    assertIntegerArray(deniedChatIds, "telegram-bot: denied_chat_ids must be an array of integers");
-    assertIntegerArray(runtimeControlAllowedUserIds, "telegram-bot: runtime_control_allowed_user_ids must be an array of integers");
+    assertIntegerArray(allowedUserIds, "telegram-bot: allowed_user_ids must be an array of safe integers");
+    assertIntegerArray(deniedUserIds, "telegram-bot: denied_user_ids must be an array of safe integers");
+    assertIntegerArray(allowedChatIds, "telegram-bot: allowed_chat_ids must be an array of safe integers");
+    assertIntegerArray(deniedChatIds, "telegram-bot: denied_chat_ids must be an array of safe integers");
+    assertIntegerArray(runtimeControlAllowedUserIds, "telegram-bot: runtime_control_allowed_user_ids must be an array of safe integers");
     if (typeof allowAll !== "boolean") {
         throw new Error("telegram-bot: allow_all must be a boolean");
     }
-    assertInteger(pollingTimeout, "telegram-bot: polling_timeout must be an integer");
+    assertIntegerInRange(pollingTimeout, MIN_POLLING_TIMEOUT_SECONDS, MAX_POLLING_TIMEOUT_SECONDS, `telegram-bot: polling_timeout must be a safe integer between ${MIN_POLLING_TIMEOUT_SECONDS} and ${MAX_POLLING_TIMEOUT_SECONDS}`);
     if (raw["identity_key"] !== undefined) {
         assertNonEmptyString(raw["identity_key"], "telegram-bot: identity_key must be a non-empty string when set");
     }
@@ -446,10 +741,21 @@ function loadTelegramGatewayConfig(pluginDir) {
         user_goal_map: userGoalMap,
         default_goal_id: raw["default_goal_id"],
         allow_all: allowAll,
-        polling_timeout: Math.min(Math.max(pollingTimeout, 1), 60),
+        polling_timeout: pollingTimeout,
         identity_key: raw["identity_key"],
     };
 }
+function inferGatewayChannelName(configDir) {
+    return path.basename(path.resolve(configDir));
+}
+function inferGatewayRuntimeBaseDir(configDir) {
+    const parts = path.resolve(configDir).split(path.sep);
+    const gatewayIndex = parts.lastIndexOf("gateway");
+    if (gatewayIndex > 0 && parts[gatewayIndex + 1] === "channels") {
+        return parts.slice(0, gatewayIndex).join(path.sep) || path.sep;
+    }
+    return path.resolve(configDir);
+}
 function splitMessage(text, maxLen) {
     if (text.length <= maxLen)
         return [text];
@@ -475,12 +781,17 @@ function assertNonEmptyString(value, message) {
     }
 }
 function assertInteger(value, message) {
-    if (typeof value !== "number" || !Number.isInteger(value)) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new Error(message);
+    }
+}
+function assertIntegerInRange(value, min, max, message) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
         throw new Error(message);
     }
 }
 function assertIntegerArray(value, message) {
-    if (!Array.isArray(value) || !value.every((item) => Number.isInteger(item))) {
+    if (!Array.isArray(value) || !value.every((item) => Number.isSafeInteger(item))) {
         throw new Error(message);
     }
 }