opencode-tbot 0.1.27 → 0.1.30

package/dist/plugin.js

@@ -3,10 +3,10 @@ import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
 import { parse, printParseErrorCode } from "jsonc-parser";
 import { z } from "zod";
-import { createOpencodeClient } from "@opencode-ai/sdk/v2/client";
+import { createOpencodeClient } from "@opencode-ai/sdk";
 import { randomUUID } from "node:crypto";
 import { run } from "@grammyjs/runner";
-import { Bot, InlineKeyboard } from "grammy";
+import { Bot, GrammyError, HttpError, InlineKeyboard } from "grammy";
 //#region src/infra/utils/redact.ts
 var REDACTED = "[REDACTED]";
 var DEFAULT_PREVIEW_LENGTH = 160;
@@ -46,7 +46,18 @@ function createOpenCodeAppLogger(client, options = {}) {
 		};
 		queue = queue.catch(() => void 0).then(async () => {
 			try {
-				await client.app.log(payload);
+				if (client.app.log.length >= 2) {
+					await client.app.log(payload, {
+						responseStyle: "data",
+						throwOnError: true
+					});
+					return;
+				}
+				await client.app.log({
+					body: payload,
+					responseStyle: "data",
+					throwOnError: true
+				});
 			} catch {}
 		});
 	};
@@ -292,31 +303,57 @@ var OpenCodeClient = class {
 			...SDK_OPTIONS,
 			...input.signal ? { signal: input.signal } : {}
 		};
-		return unwrapSdkData(input.parameters === void 0 ? await handler.call(target, options) : await handler.call(target, input.parameters, options));
+		return unwrapSdkData(handler.length >= 2 ? await handler.call(target, input.legacyParameters, options) : await handler.call(target, input.parameters === void 0 ? options : {
+			...input.parameters,
+			...options
+		}));
 	}
 	async getHealth() {
-		return this.callScopedSdkMethod("global", "health", {});
+		try {
+			return await this.callScopedSdkMethod("global", "health", {});
+		} catch (error) {
+			if (!isMissingScopedSdkMethodError(error, "global", "health")) throw error;
+			return this.callRawSdkGet("/global/health");
+		}
 	}
 	async abortSession(sessionId) {
-		return this.callScopedSdkMethod("session", "abort", { parameters: { sessionID: sessionId } });
+		return this.callScopedSdkMethod("session", "abort", {
+			legacyParameters: { sessionID: sessionId },
+			parameters: { path: { id: sessionId } }
+		});
 	}
 	async deleteSession(sessionId) {
-		return this.callScopedSdkMethod("session", "delete", { parameters: { sessionID: sessionId } });
+		return this.callScopedSdkMethod("session", "delete", {
+			legacyParameters: { sessionID: sessionId },
+			parameters: { path: { id: sessionId } }
+		});
 	}
 	async forkSession(sessionId, messageId) {
-		return this.callScopedSdkMethod("session", "fork", { parameters: {
-			sessionID: sessionId,
-			...messageId?.trim() ? { messageID: messageId.trim() } : {}
-		} });
+		return this.callScopedSdkMethod("session", "fork", {
+			legacyParameters: {
+				sessionID: sessionId,
+				...messageId?.trim() ? { messageID: messageId.trim() } : {}
+			},
+			parameters: {
+				path: { id: sessionId },
+				...messageId?.trim() ? { body: { messageID: messageId.trim() } } : {}
+			}
+		});
 	}
 	async getPath() {
 		return this.callScopedSdkMethod("path", "get", {});
 	}
 	async listLspStatuses(directory) {
-		return this.callScopedSdkMethod("lsp", "status", { parameters: directory ? { directory } : void 0 });
+		return this.callScopedSdkMethod("lsp", "status", {
+			legacyParameters: directory ? { directory } : void 0,
+			parameters: directory ? { query: { directory } } : void 0
+		});
 	}
 	async listMcpStatuses(directory) {
-		return this.callScopedSdkMethod("mcp", "status", { parameters: directory ? { directory } : void 0 });
+		return this.callScopedSdkMethod("mcp", "status", {
+			legacyParameters: directory ? { directory } : void 0,
+			parameters: directory ? { query: { directory } } : void 0
+		});
 	}
 	async getSessionStatuses() {
 		return this.loadSessionStatuses();
@@ -331,29 +368,69 @@ var OpenCodeClient = class {
 		return this.callScopedSdkMethod("project", "current", {});
 	}
 	async createSessionForDirectory(directory, title) {
-		return this.callScopedSdkMethod("session", "create", { parameters: title ? {
-			directory,
-			title
-		} : { directory } });
+		return this.callScopedSdkMethod("session", "create", {
+			legacyParameters: title ? {
+				directory,
+				title
+			} : { directory },
+			parameters: {
+				query: { directory },
+				...title ? { body: { title } } : {}
+			}
+		});
 	}
 	async renameSession(sessionId, title) {
-		return this.callScopedSdkMethod("session", "update", { parameters: {
-			sessionID: sessionId,
-			title
-		} });
+		return this.callScopedSdkMethod("session", "update", {
+			legacyParameters: {
+				sessionID: sessionId,
+				title
+			},
+			parameters: {
+				path: { id: sessionId },
+				body: { title }
+			}
+		});
 	}
 	async listAgents() {
 		return this.callScopedSdkMethod("app", "agents", {});
 	}
 	async listPendingPermissions(directory) {
-		return this.callScopedSdkMethod("permission", "list", { parameters: directory ? { directory } : void 0 });
-	}
-	async replyToPermission(requestId, reply, message, _sessionId) {
-		return this.callScopedSdkMethod("permission", "reply", { parameters: {
-			requestID: requestId,
-			reply,
-			...message?.trim() ? { message: message.trim() } : {}
-		} });
+		return (await this.callScopedSdkMethod("permission", "list", {
+			legacyParameters: directory ? { directory } : void 0,
+			parameters: directory ? { query: { directory } } : void 0
+		})).map(normalizePermissionRequest).filter((permission) => !!permission);
+	}
+	async replyToPermission(requestId, reply, message, sessionId) {
+		const normalizedMessage = message?.trim();
+		const rootPermissionHandler = this.client.postSessionIdPermissionsPermissionId;
+		if (sessionId && typeof rootPermissionHandler === "function") return unwrapSdkData(await rootPermissionHandler.call(this.client, {
+			...SDK_OPTIONS,
+			body: {
+				response: reply,
+				...normalizedMessage ? { message: normalizedMessage } : {}
+			},
+			path: {
+				id: sessionId,
+				permissionID: requestId
+			}
+		}));
+		return this.callScopedSdkMethod("permission", "reply", {
+			legacyParameters: {
+				requestID: requestId,
+				reply,
+				...normalizedMessage ? { message: normalizedMessage } : {}
+			},
+			parameters: sessionId ? {
+				body: {
+					response: reply,
+					...normalizedMessage ? { message: normalizedMessage } : {}
+				},
+				path: {
+					id: sessionId,
+					permissionID: requestId
+				}
+			} : void 0
+		});
 	}
 	async listModels() {
 		const now = Date.now();
@@ -489,10 +566,14 @@ var OpenCodeClient = class {
 				messageId
 			}, async (requestSignal) => {
 				return normalizePromptResponse(await this.callScopedSdkMethod("session", "message", {
-					parameters: {
+					legacyParameters: {
 						sessionID: sessionId,
 						messageID: messageId
 					},
+					parameters: { path: {
+						id: sessionId,
+						messageID: messageId
+					} },
 					signal: requestSignal
 				}));
 			}, signal);
@@ -520,10 +601,14 @@ var OpenCodeClient = class {
 				timeoutMs: this.promptTimeoutPolicy.pollRequestTimeoutMs
 			}, async (requestSignal) => {
 				return normalizePromptResponses(await this.callScopedSdkMethod("session", "messages", {
-					parameters: {
+					legacyParameters: {
 						sessionID: sessionId,
 						limit: PROMPT_MESSAGE_POLL_LIMIT
 					},
+					parameters: {
+						path: { id: sessionId },
+						query: { limit: PROMPT_MESSAGE_POLL_LIMIT }
+					},
 					signal: requestSignal
 				}));
 			}, signal);
@@ -584,10 +669,14 @@ var OpenCodeClient = class {
 			...input.variant ? { variant: input.variant } : {},
 			parts
 		};
-		const requestParameters = {
+		const legacyRequestParameters = {
 			sessionID: input.sessionId,
 			...requestBody
 		};
+		const requestParameters = {
+			body: requestBody,
+			path: { id: input.sessionId }
+		};
 		try {
 			if (typeof this.client.session?.promptAsync === "function") {
 				await this.runPromptRequestWithTimeout({
@@ -596,6 +685,7 @@ var OpenCodeClient = class {
 					timeoutMs: this.promptTimeoutPolicy.waitTimeoutMs
 				}, async (signal) => {
 					await this.callScopedSdkMethod("session", "promptAsync", {
+						legacyParameters: legacyRequestParameters,
 						parameters: requestParameters,
 						signal
 					});
@@ -613,10 +703,16 @@ var OpenCodeClient = class {
 		throw new Error("OpenCode SDK client does not expose session.promptAsync().");
 	}
 	async loadSessionStatuses(signal) {
-		return this.callScopedSdkMethod("session", "status", {
-			signal,
-			parameters: void 0
-		});
+		return this.callScopedSdkMethod("session", "status", { signal });
+	}
+	async callRawSdkGet(url, signal) {
+		const rawClient = getRawSdkRequestClient(this.client);
+		if (typeof rawClient?.get !== "function") throw new Error(`OpenCode SDK client does not expose a compatible raw GET endpoint for ${url}.`);
+		return unwrapSdkData(await rawClient.get({
+			...SDK_OPTIONS,
+			...signal ? { signal } : {},
+			url
+		}));
 	}
 	async runPromptRequestWithTimeout(input, operation, signal) {
 		const startedAt = Date.now();
@@ -684,12 +780,16 @@ var OpenCodeClient = class {
 	logPromptRequest(level, extra, message) {
 		const log = this.client.app?.log;
 		if (typeof log !== "function") return;
-		log.call(this.client.app, {
+		const payload = {
 			service: PROMPT_LOG_SERVICE,
 			level,
 			message,
 			extra
-		}).catch(() => void 0);
+		};
+		(log.length >= 2 ? log.call(this.client.app, payload, SDK_OPTIONS) : log.call(this.client.app, {
+			body: payload,
+			...SDK_OPTIONS
+		})).catch(() => void 0);
 	}
 };
 function createOpenCodeClientFromSdkClient(client, fetchFn = fetch, promptTimeoutPolicy = {}) {
@@ -811,7 +911,7 @@ function isPromptResponseUsable(data, structured) {
 }
 function normalizePromptResponse(response) {
 	return {
-		info: isPlainRecord(response?.info) ? response.info : null,
+		info: isPlainRecord$1(response?.info) ? response.info : null,
 		parts: normalizePromptParts(response?.parts)
 	};
 }
@@ -835,7 +935,7 @@ function toAssistantMessage(message) {
 	if ("mode" in message && typeof message.mode === "string" && message.mode.trim().length > 0) normalized.mode = message.mode;
 	if ("modelID" in message && typeof message.modelID === "string" && message.modelID.trim().length > 0) normalized.modelID = message.modelID;
 	if ("parentID" in message && typeof message.parentID === "string" && message.parentID.trim().length > 0) normalized.parentID = message.parentID;
-	if ("path" in message && isPlainRecord(message.path)) normalized.path = {
+	if ("path" in message && isPlainRecord$1(message.path)) normalized.path = {
 		...typeof message.path.cwd === "string" && message.path.cwd.trim().length > 0 ? { cwd: message.path.cwd } : {},
 		...typeof message.path.root === "string" && message.path.root.trim().length > 0 ? { root: message.path.root } : {}
 	};
@@ -845,16 +945,16 @@ function toAssistantMessage(message) {
 	const structuredPayload = extractStructuredPayload(message);
 	if (structuredPayload !== null) normalized.structured = structuredPayload;
 	if ("summary" in message && typeof message.summary === "boolean") normalized.summary = message.summary;
-	if ("time" in message && isPlainRecord(message.time)) normalized.time = {
+	if ("time" in message && isPlainRecord$1(message.time)) normalized.time = {
 		...typeof message.time.created === "number" && Number.isFinite(message.time.created) ? { created: message.time.created } : {},
 		...typeof message.time.completed === "number" && Number.isFinite(message.time.completed) ? { completed: message.time.completed } : {}
 	};
-	if ("tokens" in message && isPlainRecord(message.tokens)) normalized.tokens = {
+	if ("tokens" in message && isPlainRecord$1(message.tokens)) normalized.tokens = {
 		...typeof message.tokens.input === "number" && Number.isFinite(message.tokens.input) ? { input: message.tokens.input } : {},
 		...typeof message.tokens.output === "number" && Number.isFinite(message.tokens.output) ? { output: message.tokens.output } : {},
 		...typeof message.tokens.reasoning === "number" && Number.isFinite(message.tokens.reasoning) ? { reasoning: message.tokens.reasoning } : {},
 		...typeof message.tokens.total === "number" && Number.isFinite(message.tokens.total) ? { total: message.tokens.total } : {},
-		...isPlainRecord(message.tokens.cache) ? { cache: {
+		...isPlainRecord$1(message.tokens.cache) ? { cache: {
 			...typeof message.tokens.cache.read === "number" && Number.isFinite(message.tokens.cache.read) ? { read: message.tokens.cache.read } : {},
 			...typeof message.tokens.cache.write === "number" && Number.isFinite(message.tokens.cache.write) ? { write: message.tokens.cache.write } : {}
 		} } : {}
@@ -863,7 +963,7 @@ function toAssistantMessage(message) {
 	return normalized;
 }
 function extractMessageId(message) {
-	if (!isPlainRecord(message)) return null;
+	if (!isPlainRecord$1(message)) return null;
 	return typeof message.id === "string" && message.id.trim().length > 0 ? message.id : null;
 }
 function delay(ms, signal) {
@@ -959,6 +1059,34 @@ function unwrapSdkData(response) {
 	if (response && typeof response === "object" && "data" in response) return response.data;
 	return response;
 }
+function normalizePermissionRequest(permission) {
+	if (!isPlainRecord$1(permission)) return null;
+	const id = typeof permission.id === "string" && permission.id.trim().length > 0 ? permission.id : null;
+	const sessionID = typeof permission.sessionID === "string" && permission.sessionID.trim().length > 0 ? permission.sessionID : null;
+	const permissionName = typeof permission.permission === "string" && permission.permission.trim().length > 0 ? permission.permission : typeof permission.type === "string" && permission.type.trim().length > 0 ? permission.type : null;
+	if (!id || !sessionID || !permissionName) return null;
+	return {
+		always: Array.isArray(permission.always) ? permission.always.filter((value) => typeof value === "string") : [],
+		id,
+		metadata: isPlainRecord$1(permission.metadata) ? permission.metadata : {},
+		patterns: normalizePermissionPatterns$1(permission),
+		permission: permissionName,
+		sessionID
+	};
+}
+function normalizePermissionPatterns$1(permission) {
+	if (Array.isArray(permission.patterns)) return permission.patterns.filter((value) => typeof value === "string");
+	if (typeof permission.pattern === "string" && permission.pattern.trim().length > 0) return [permission.pattern];
+	if (Array.isArray(permission.pattern)) return permission.pattern.filter((value) => typeof value === "string");
+	return [];
+}
+function getRawSdkRequestClient(client) {
+	const compatibleClient = client;
+	return compatibleClient.client ?? compatibleClient._client ?? null;
+}
+function isMissingScopedSdkMethodError(error, scope, method) {
+	return error instanceof Error && error.message === `OpenCode SDK client does not expose a compatible ${scope}.${method} method.`;
+}
 function resolvePromptTimeoutPolicy(input) {
 	return {
 		pollRequestTimeoutMs: input.pollRequestTimeoutMs ?? DEFAULT_OPENCODE_PROMPT_TIMEOUT_POLICY.pollRequestTimeoutMs,
@@ -967,11 +1095,11 @@ function resolvePromptTimeoutPolicy(input) {
 	};
 }
 function normalizeAssistantError(value) {
-	if (!isPlainRecord(value) || typeof value.name !== "string" || value.name.trim().length === 0) return;
+	if (!isPlainRecord$1(value) || typeof value.name !== "string" || value.name.trim().length === 0) return;
 	return {
 		...value,
 		name: value.name,
-		...isPlainRecord(value.data) ? { data: value.data } : {}
+		...isPlainRecord$1(value.data) ? { data: value.data } : {}
 	};
 }
 function isAssistantMessageCompleted(message) {
@@ -984,7 +1112,7 @@ function isCompletedEmptyPromptResponse(data, structured) {
 	return isAssistantMessageCompleted(assistantInfo) && !assistantInfo?.error && !hasText && !bodyMd;
 }
 function extractStructuredPayload(message) {
-	if (!isPlainRecord(message)) return null;
+	if (!isPlainRecord$1(message)) return null;
 	if ("structured" in message && message.structured !== void 0) return message.structured;
 	if ("structured_output" in message && message.structured_output !== void 0) return message.structured_output;
 	return null;
@@ -1058,7 +1186,7 @@ function throwIfAborted(signal) {
 	if (!signal?.aborted) return;
 	throw normalizeAbortReason(signal.reason);
 }
-function isPlainRecord(value) {
+function isPlainRecord$1(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 async function resolveProviderAvailability(config, fetchFn) {
@@ -2274,25 +2402,35 @@ function escapeMarkdownV2(value) {
 async function handleTelegramBotPluginEvent(runtime, event) {
 	switch (event.type) {
 		case "permission.asked":
-			await handlePermissionAsked(runtime, event);
+		case "permission.updated": {
+			const request = normalizePermissionRequestEvent(event.properties);
+			if (request) await handlePermissionAsked(runtime, request);
 			return;
-		case "permission.replied":
-			await handlePermissionReplied(runtime, event);
+		}
+		case "permission.replied": {
+			const replyEvent = normalizePermissionReplyEvent(event.properties);
+			if (replyEvent) await handlePermissionReplied(runtime, replyEvent);
 			return;
-		case "session.error":
-			await handleSessionError(runtime, event);
+		}
+		case "session.error": {
+			const sessionError = normalizeSessionErrorEvent(event.properties);
+			if (sessionError) await handleSessionError(runtime, sessionError);
 			return;
-		case "session.idle":
-			await handleSessionIdle(runtime, event);
+		}
+		case "session.idle": {
+			const sessionIdle = normalizeSessionIdleEvent(event.properties);
+			if (sessionIdle) await handleSessionIdle(runtime, sessionIdle);
 			return;
-		case "session.status":
-			await handleSessionStatus(runtime, event);
+		}
+		case "session.status": {
+			const sessionStatus = normalizeSessionStatusEvent(event.properties);
+			if (sessionStatus) await handleSessionStatus(runtime, sessionStatus);
 			return;
+		}
 		default: return;
 	}
 }
-async function handlePermissionAsked(runtime, event) {
-	const request = event.properties;
+async function handlePermissionAsked(runtime, request) {
 	const bindings = await runtime.container.sessionRepo.listBySessionId(request.sessionID);
 	const chatIds = new Set([...bindings.map((binding) => binding.chatId), ...runtime.container.foregroundSessionTracker.listChatIds(request.sessionID)]);
 	const approvals = await runtime.container.permissionApprovalRepo.listByRequestId(request.id);
@@ -2322,52 +2460,42 @@ async function handlePermissionAsked(runtime, event) {
 	}
 }
 async function handlePermissionReplied(runtime, event) {
-	const requestId = event.properties.requestID;
-	const reply = event.properties.reply;
-	const approvals = await runtime.container.permissionApprovalRepo.listByRequestId(requestId);
+	const approvals = await runtime.container.permissionApprovalRepo.listByRequestId(event.requestId);
 	await Promise.all(approvals.map(async (approval) => {
 		try {
-			await runtime.bot.api.editMessageText(approval.chatId, approval.messageId, buildPermissionApprovalResolvedMessage(requestId, reply));
+			await runtime.bot.api.editMessageText(approval.chatId, approval.messageId, buildPermissionApprovalResolvedMessage(event.requestId, event.reply));
 		} catch (error) {
 			runtime.container.logger.warn({
 				error,
 				chatId: approval.chatId,
-				requestId
+				requestId: event.requestId,
+				sessionId: event.sessionId
 			}, "failed to update Telegram permission message");
 		}
-		await runtime.container.permissionApprovalRepo.set(toResolvedApproval(approval, reply));
+		await runtime.container.permissionApprovalRepo.set(toResolvedApproval(approval, event.reply));
 	}));
 }
 async function handleSessionError(runtime, event) {
-	const sessionId = event.properties.sessionID;
-	const error = event.properties.error;
-	if (!sessionId) {
-		runtime.container.logger.error({ error }, "session error received without a session id");
-		return;
-	}
-	if (runtime.container.foregroundSessionTracker.fail(sessionId, error ?? /* @__PURE__ */ new Error("Unknown session error."))) {
+	if (runtime.container.foregroundSessionTracker.fail(event.sessionId, event.error instanceof Error ? event.error : /* @__PURE__ */ new Error("Unknown session error."))) {
 		runtime.container.logger.warn({
-			error,
-			sessionId
+			error: event.error,
+			sessionId: event.sessionId
 		}, "session error suppressed for foreground Telegram session");
 		return;
 	}
-	await notifyBoundChats(runtime, sessionId, `Session failed.\n\nSession: ${sessionId}\nError: ${(typeof error?.data?.message === "string" ? error.data.message.trim() : "") || error?.name?.trim() || "Unknown session error."}`);
+	const message = extractSessionErrorMessage(event.error) ?? "Unknown session error.";
+	await notifyBoundChats(runtime, event.sessionId, `Session failed.\n\nSession: ${event.sessionId}\nError: ${message}`);
 }
 async function handleSessionIdle(runtime, event) {
-	const sessionId = event.properties.sessionID;
-	if (runtime.container.foregroundSessionTracker.clear(sessionId)) {
-		runtime.container.logger.info({ sessionId }, "session idle notification suppressed for foreground Telegram session");
+	if (runtime.container.foregroundSessionTracker.clear(event.sessionId)) {
+		runtime.container.logger.info({ sessionId: event.sessionId }, "session idle notification suppressed for foreground Telegram session");
 		return;
 	}
-	await notifyBoundChats(runtime, sessionId, `Session finished.\n\nSession: ${sessionId}`);
+	await notifyBoundChats(runtime, event.sessionId, `Session finished.\n\nSession: ${event.sessionId}`);
 }
 async function handleSessionStatus(runtime, event) {
-	if (event.properties.status.type !== "idle") return;
-	await handleSessionIdle(runtime, {
-		type: "session.idle",
-		properties: { sessionID: event.properties.sessionID }
-	});
+	if (event.statusType !== "idle") return;
+	await handleSessionIdle(runtime, event);
 }
 async function notifyBoundChats(runtime, sessionId, text) {
 	const bindings = await runtime.container.sessionRepo.listBySessionId(sessionId);
@@ -2391,6 +2519,79 @@ function toResolvedApproval(approval, reply) {
 		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 	};
 }
+function normalizePermissionRequestEvent(properties) {
+	if (!isPlainRecord(properties)) return null;
+	const id = asNonEmptyString(properties.id);
+	const sessionID = asNonEmptyString(properties.sessionID);
+	const permission = asNonEmptyString(properties.permission) ?? asNonEmptyString(properties.type);
+	if (!id || !sessionID || !permission) return null;
+	return {
+		always: Array.isArray(properties.always) ? properties.always.filter((value) => typeof value === "string") : [],
+		id,
+		metadata: isPlainRecord(properties.metadata) ? properties.metadata : {},
+		patterns: normalizePermissionPatterns(properties),
+		permission,
+		sessionID
+	};
+}
+function normalizePermissionReplyEvent(properties) {
+	if (!isPlainRecord(properties)) return null;
+	const requestId = asNonEmptyString(properties.requestID) ?? asNonEmptyString(properties.permissionID);
+	const reply = normalizePermissionReply(asNonEmptyString(properties.reply) ?? asNonEmptyString(properties.response));
+	const sessionId = asNonEmptyString(properties.sessionID);
+	if (!requestId || !reply || !sessionId) return null;
+	return {
+		reply,
+		requestId,
+		sessionId
+	};
+}
+function normalizeSessionErrorEvent(properties) {
+	if (!isPlainRecord(properties)) return null;
+	const sessionId = asNonEmptyString(properties.sessionID);
+	if (!sessionId) return null;
+	return {
+		error: properties.error,
+		sessionId
+	};
+}
+function normalizeSessionIdleEvent(properties) {
+	if (!isPlainRecord(properties)) return null;
+	const sessionId = asNonEmptyString(properties.sessionID);
+	return sessionId ? { sessionId } : null;
+}
+function normalizeSessionStatusEvent(properties) {
+	if (!isPlainRecord(properties) || !isPlainRecord(properties.status)) return null;
+	const sessionId = asNonEmptyString(properties.sessionID);
+	const statusType = asNonEmptyString(properties.status.type);
+	if (!sessionId || !statusType) return null;
+	return {
+		sessionId,
+		statusType
+	};
+}
+function normalizePermissionPatterns(properties) {
+	if (Array.isArray(properties.patterns)) return properties.patterns.filter((value) => typeof value === "string");
+	if (typeof properties.pattern === "string" && properties.pattern.trim().length > 0) return [properties.pattern];
+	if (Array.isArray(properties.pattern)) return properties.pattern.filter((value) => typeof value === "string");
+	return [];
+}
+function normalizePermissionReply(value) {
+	if (value === "once" || value === "always" || value === "reject") return value;
+	return null;
+}
+function extractSessionErrorMessage(error) {
+	if (error instanceof Error && error.message.trim().length > 0) return error.message.trim();
+	if (!isPlainRecord(error)) return null;
+	if (isPlainRecord(error.data) && typeof error.data.message === "string" && error.data.message.trim().length > 0) return error.data.message.trim();
+	return asNonEmptyString(error.name);
+}
+function asNonEmptyString(value) {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function isPlainRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 var SUPPORTED_BOT_LANGUAGES = [
 	"en",
 	"zh-CN",
@@ -3094,111 +3295,6 @@ async function syncTelegramCommandsForChat(api, chatId, language) {
 	} });
 }
 //#endregion
-//#region src/bot/i18n.ts
-async function getChatLanguage(sessionRepo, chatId) {
-	if (!chatId) return "en";
-	return normalizeBotLanguage((await sessionRepo.getByChatId(chatId))?.language);
-}
-async function getChatCopy(sessionRepo, chatId) {
-	return getBotCopy(await getChatLanguage(sessionRepo, chatId));
-}
-async function setChatLanguage(sessionRepo, chatId, language) {
-	const binding = await sessionRepo.getByChatId(chatId);
-	await sessionRepo.setCurrent({
-		chatId,
-		sessionId: binding?.sessionId ?? null,
-		projectId: binding?.projectId ?? null,
-		directory: binding?.directory ?? null,
-		agentName: binding?.agentName ?? null,
-		modelProviderId: binding?.modelProviderId ?? null,
-		modelId: binding?.modelId ?? null,
-		modelVariant: binding?.modelVariant ?? null,
-		language,
-		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-	});
-}
-var NUMBERED_BUTTONS_PER_ROW = 5;
-function buildModelsKeyboard(models, requestedPage, copy = BOT_COPY) {
-	const page = getModelsPage(models, requestedPage);
-	const keyboard = buildNumberedKeyboard(page.items, page.startIndex, (_, index) => `model:pick:${page.startIndex + index + 1}`);
-	appendPaginationButtons(keyboard, page.page, page.totalPages, "model:page", copy);
-	return {
-		keyboard,
-		page
-	};
-}
-function buildAgentsKeyboard(agents, requestedPage, copy = BOT_COPY) {
-	const page = getAgentsPage(agents, requestedPage);
-	const keyboard = buildNumberedKeyboard(page.items, page.startIndex, (_, index) => `agents:select:${page.startIndex + index + 1}`);
-	appendPaginationButtons(keyboard, page.page, page.totalPages, "agents:page", copy);
-	return {
-		keyboard,
-		page
-	};
-}
-function buildSessionsKeyboard(sessions, requestedPage, copy = BOT_COPY) {
-	const page = getSessionsPage(sessions, requestedPage);
-	const keyboard = buildNumberedKeyboard(page.items, page.startIndex, (session) => `sessions:pick:${page.page}:${session.id}`);
-	appendPaginationButtons(keyboard, page.page, page.totalPages, "sessions:page", copy);
-	return {
-		keyboard,
-		page
-	};
-}
-function buildSessionActionKeyboard(sessionId, page, copy = BOT_COPY) {
-	return new InlineKeyboard().text(copy.sessions.switchAction, `sessions:switch:${page}:${sessionId}`).text(copy.sessions.renameAction, `sessions:rename:${page}:${sessionId}`).row().text(copy.sessions.backToList, `sessions:back:${page}`);
-}
-function buildModelVariantsKeyboard(variants, modelIndex) {
-	return buildNumberedKeyboard(variants, 0, (_, index) => `model:variant:${modelIndex}:${index + 1}`);
-}
-function buildLanguageKeyboard(currentLanguage, copy = BOT_COPY) {
-	const keyboard = new InlineKeyboard();
-	SUPPORTED_BOT_LANGUAGES.forEach((language, index) => {
-		const label = currentLanguage === language ? `[${getLanguageLabel(language, copy)}]` : getLanguageLabel(language, copy);
-		keyboard.text(label, `language:select:${language}`);
-		if (index !== SUPPORTED_BOT_LANGUAGES.length - 1) keyboard.row();
-	});
-	return keyboard;
-}
-function getModelsPage(models, requestedPage) {
-	return getPagedItems(models, requestedPage, 10);
-}
-function getAgentsPage(agents, requestedPage) {
-	return getPagedItems(agents, requestedPage, 10);
-}
-function getSessionsPage(sessions, requestedPage) {
-	return getPagedItems(sessions, requestedPage, 10);
-}
-function buildNumberedKeyboard(items, startIndex, buildCallbackData) {
-	const keyboard = new InlineKeyboard();
-	items.forEach((item, index) => {
-		const displayIndex = startIndex + index + 1;
-		keyboard.text(`${displayIndex}`, buildCallbackData(item, index));
-		if (index !== items.length - 1 && (index + 1) % NUMBERED_BUTTONS_PER_ROW === 0) keyboard.row();
-	});
-	return keyboard;
-}
-function appendPaginationButtons(keyboard, page, totalPages, prefix, copy) {
-	if (totalPages <= 1) return;
-	if (page > 0) keyboard.text(copy.common.previousPage, `${prefix}:${page - 1}`);
-	if (page < totalPages - 1) keyboard.text(copy.common.nextPage, `${prefix}:${page + 1}`);
-}
-function getPagedItems(items, requestedPage, pageSize) {
-	const totalPages = Math.max(1, Math.ceil(items.length / pageSize));
-	const page = clampPage(requestedPage, totalPages);
-	const startIndex = page * pageSize;
-	return {
-		items: items.slice(startIndex, startIndex + pageSize),
-		page,
-		startIndex,
-		totalPages
-	};
-}
-function clampPage(page, totalPages) {
-	if (!Number.isInteger(page) || page < 0) return 0;
-	return Math.min(page, totalPages - 1);
-}
-//#endregion
 //#region src/bot/presenters/error.presenter.ts
 function presentError(error, copy = BOT_COPY) {
 	const presented = normalizeError(error, copy);
@@ -3313,6 +3409,183 @@ function stringifyUnknown(value) {
 	}
 }
 //#endregion
+//#region src/bot/error-boundary.ts
+function extractTelegramUpdateContext(ctx) {
+	const updateId = getNestedNumber(ctx, ["update", "update_id"]);
+	const chatId = getNestedNumber(ctx, ["chat", "id"]);
+	const messageText = getNestedString(ctx, ["message", "text"]);
+	const callbackData = getNestedString(ctx, ["callbackQuery", "data"]);
+	return {
+		...typeof updateId === "number" ? { updateId } : {},
+		...typeof chatId === "number" ? { chatId } : {},
+		...typeof messageText === "string" && messageText.trim().length > 0 ? { messageText } : {},
+		...typeof callbackData === "string" && callbackData.trim().length > 0 ? { callbackData } : {}
+	};
+}
+async function replyWithDefaultTelegramError(ctx, logger, error) {
+	const text = presentError(error, BOT_COPY);
+	const editMessageText = getFunction(ctx, "editMessageText");
+	const reply = getFunction(ctx, "reply");
+	const callbackData = getNestedString(ctx, ["callbackQuery", "data"]);
+	try {
+		if (typeof callbackData === "string" && editMessageText) {
+			await editMessageText.call(ctx, text);
+			return;
+		}
+		if (reply) await reply.call(ctx, text);
+	} catch (replyError) {
+		logger.warn?.({
+			...extractTelegramUpdateContext(ctx),
+			error: replyError
+		}, "failed to deliver fallback Telegram error message");
+	}
+}
+function getFunction(value, key) {
+	if (!(key in value)) return null;
+	const candidate = value[key];
+	return typeof candidate === "function" ? candidate : null;
+}
+function getNestedNumber(value, path) {
+	const candidate = getNestedValue(value, path);
+	return typeof candidate === "number" ? candidate : null;
+}
+function getNestedString(value, path) {
+	const candidate = getNestedValue(value, path);
+	return typeof candidate === "string" ? candidate : null;
+}
+function getNestedValue(value, path) {
+	let current = value;
+	for (const segment of path) {
+		if (!current || typeof current !== "object" || !(segment in current)) return null;
+		current = current[segment];
+	}
+	return current;
+}
+//#endregion
+//#region src/bot/i18n.ts
+async function getChatLanguage(sessionRepo, chatId) {
+	if (!chatId) return "en";
+	return normalizeBotLanguage((await sessionRepo.getByChatId(chatId))?.language);
+}
+async function getSafeChatLanguage(sessionRepo, chatId, logger) {
+	try {
+		return await getChatLanguage(sessionRepo, chatId);
+	} catch (error) {
+		logger?.warn?.({
+			error,
+			chatId: chatId ?? void 0
+		}, "failed to resolve Telegram chat language; falling back to the default locale");
+		return "en";
+	}
+}
+async function getSafeChatCopy(sessionRepo, chatId, logger) {
+	try {
+		return getBotCopy(await getSafeChatLanguage(sessionRepo, chatId, logger));
+	} catch (error) {
+		logger?.warn?.({
+			error,
+			chatId: chatId ?? void 0
+		}, "failed to resolve Telegram copy; falling back to the default locale");
+		return BOT_COPY;
+	}
+}
+async function setChatLanguage(sessionRepo, chatId, language) {
+	const binding = await sessionRepo.getByChatId(chatId);
+	await sessionRepo.setCurrent({
+		chatId,
+		sessionId: binding?.sessionId ?? null,
+		projectId: binding?.projectId ?? null,
+		directory: binding?.directory ?? null,
+		agentName: binding?.agentName ?? null,
+		modelProviderId: binding?.modelProviderId ?? null,
+		modelId: binding?.modelId ?? null,
+		modelVariant: binding?.modelVariant ?? null,
+		language,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+var NUMBERED_BUTTONS_PER_ROW = 5;
+function buildModelsKeyboard(models, requestedPage, copy = BOT_COPY) {
+	const page = getModelsPage(models, requestedPage);
+	const keyboard = buildNumberedKeyboard(page.items, page.startIndex, (_, index) => `model:pick:${page.startIndex + index + 1}`);
+	appendPaginationButtons(keyboard, page.page, page.totalPages, "model:page", copy);
+	return {
+		keyboard,
+		page
+	};
+}
+function buildAgentsKeyboard(agents, requestedPage, copy = BOT_COPY) {
+	const page = getAgentsPage(agents, requestedPage);
+	const keyboard = buildNumberedKeyboard(page.items, page.startIndex, (_, index) => `agents:select:${page.startIndex + index + 1}`);
+	appendPaginationButtons(keyboard, page.page, page.totalPages, "agents:page", copy);
+	return {
+		keyboard,
+		page
+	};
+}
+function buildSessionsKeyboard(sessions, requestedPage, copy = BOT_COPY) {
+	const page = getSessionsPage(sessions, requestedPage);
+	const keyboard = buildNumberedKeyboard(page.items, page.startIndex, (session) => `sessions:pick:${page.page}:${session.id}`);
+	appendPaginationButtons(keyboard, page.page, page.totalPages, "sessions:page", copy);
+	return {
+		keyboard,
+		page
+	};
+}
+function buildSessionActionKeyboard(sessionId, page, copy = BOT_COPY) {
+	return new InlineKeyboard().text(copy.sessions.switchAction, `sessions:switch:${page}:${sessionId}`).text(copy.sessions.renameAction, `sessions:rename:${page}:${sessionId}`).row().text(copy.sessions.backToList, `sessions:back:${page}`);
+}
+function buildModelVariantsKeyboard(variants, modelIndex) {
+	return buildNumberedKeyboard(variants, 0, (_, index) => `model:variant:${modelIndex}:${index + 1}`);
+}
+function buildLanguageKeyboard(currentLanguage, copy = BOT_COPY) {
+	const keyboard = new InlineKeyboard();
+	SUPPORTED_BOT_LANGUAGES.forEach((language, index) => {
+		const label = currentLanguage === language ? `[${getLanguageLabel(language, copy)}]` : getLanguageLabel(language, copy);
+		keyboard.text(label, `language:select:${language}`);
+		if (index !== SUPPORTED_BOT_LANGUAGES.length - 1) keyboard.row();
+	});
+	return keyboard;
+}
+function getModelsPage(models, requestedPage) {
+	return getPagedItems(models, requestedPage, 10);
+}
+function getAgentsPage(agents, requestedPage) {
+	return getPagedItems(agents, requestedPage, 10);
+}
+function getSessionsPage(sessions, requestedPage) {
+	return getPagedItems(sessions, requestedPage, 10);
+}
+function buildNumberedKeyboard(items, startIndex, buildCallbackData) {
+	const keyboard = new InlineKeyboard();
+	items.forEach((item, index) => {
+		const displayIndex = startIndex + index + 1;
+		keyboard.text(`${displayIndex}`, buildCallbackData(item, index));
+		if (index !== items.length - 1 && (index + 1) % NUMBERED_BUTTONS_PER_ROW === 0) keyboard.row();
+	});
+	return keyboard;
+}
+function appendPaginationButtons(keyboard, page, totalPages, prefix, copy) {
+	if (totalPages <= 1) return;
+	if (page > 0) keyboard.text(copy.common.previousPage, `${prefix}:${page - 1}`);
+	if (page < totalPages - 1) keyboard.text(copy.common.nextPage, `${prefix}:${page + 1}`);
+}
+function getPagedItems(items, requestedPage, pageSize) {
+	const totalPages = Math.max(1, Math.ceil(items.length / pageSize));
+	const page = clampPage(requestedPage, totalPages);
+	const startIndex = page * pageSize;
+	return {
+		items: items.slice(startIndex, startIndex + pageSize),
+		page,
+		startIndex,
+		totalPages
+	};
+}
+function clampPage(page, totalPages) {
+	if (!Number.isInteger(page) || page < 0) return 0;
+	return Math.min(page, totalPages - 1);
+}
+//#endregion
 //#region src/bot/presenters/message.presenter.ts
 var VARIANT_ORDER = [
 	"minimal",
@@ -3692,7 +3965,7 @@ function formatSessionLabel(session) {
 //#endregion
 //#region src/bot/commands/agents.ts
 async function handleAgentsCommand(ctx, dependencies) {
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	try {
 		const result = await dependencies.listAgentsUseCase.execute({ chatId: ctx.chat.id });
 		if (result.agents.length === 0) {
@@ -3718,7 +3991,7 @@ function registerAgentsCommand(bot, dependencies) {
 //#endregion
 //#region src/bot/sessions-menu.ts
 async function buildSessionsListView(chatId, requestedPage, dependencies) {
-	const copy = await getChatCopy(dependencies.sessionRepo, chatId);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, chatId, dependencies.logger);
 	const result = await dependencies.listSessionsUseCase.execute({ chatId });
 	if (result.sessions.length === 0) return {
 		copy,
@@ -3777,14 +4050,14 @@ async function getPendingSessionRenameAction(dependencies, chatId) {
 }
 async function replyIfSessionRenamePending(ctx, dependencies) {
 	if (!await getPendingSessionRenameAction(dependencies, ctx.chat.id)) return false;
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	await ctx.reply(copy.sessions.renamePendingInput);
 	return true;
 }
 async function handlePendingSessionRenameText(ctx, dependencies) {
 	const pendingAction = await getPendingSessionRenameAction(dependencies, ctx.chat.id);
 	if (!pendingAction) return false;
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	const title = ctx.message.text?.trim() ?? "";
 	if (title.startsWith("/")) {
 		await ctx.reply(copy.sessions.renamePendingInput);
@@ -3816,7 +4089,7 @@ async function handlePendingSessionRenameText(ctx, dependencies) {
 async function cancelPendingSessionRename(ctx, dependencies) {
 	const pendingAction = await getPendingSessionRenameAction(dependencies, ctx.chat.id);
 	if (!pendingAction) return false;
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	await dependencies.pendingActionRepo.clear(ctx.chat.id);
 	await bestEffortRestoreSessionsList(ctx.api, pendingAction, dependencies);
 	await ctx.reply(copy.sessions.renameCancelled);
@@ -3835,7 +4108,7 @@ function isSessionRenamePendingAction(action) {
 //#endregion
 //#region src/bot/commands/cancel.ts
 async function handleCancelCommand(ctx, dependencies) {
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	try {
 		if (await cancelPendingSessionRename(ctx, dependencies)) return;
 		const result = await dependencies.abortPromptUseCase.execute({ chatId: ctx.chat.id });
@@ -3861,8 +4134,8 @@ function registerCancelCommand(bot, dependencies) {
 //#endregion
 //#region src/bot/commands/language.ts
 async function handleLanguageCommand(ctx, dependencies) {
-	const language = await getChatLanguage(dependencies.sessionRepo, ctx.chat.id);
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const language = await getSafeChatLanguage(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	try {
 		await syncTelegramCommandsForChat(ctx.api, ctx.chat.id, language);
 		await ctx.reply(presentLanguageMessage(language, copy), { reply_markup: buildLanguageKeyboard(language, copy) });
@@ -3872,7 +4145,7 @@ async function handleLanguageCommand(ctx, dependencies) {
 	}
 }
 async function switchLanguageForChat(api, chatId, language, dependencies) {
-	const currentCopy = await getChatCopy(dependencies.sessionRepo, chatId);
+	const currentCopy = await getSafeChatCopy(dependencies.sessionRepo, chatId, dependencies.logger);
 	if (!isBotLanguage(language)) return {
 		found: false,
 		copy: currentCopy
@@ -3881,7 +4154,7 @@ async function switchLanguageForChat(api, chatId, language, dependencies) {
 	await syncTelegramCommandsForChat(api, chatId, language);
 	return {
 		found: true,
-		copy: await getChatCopy(dependencies.sessionRepo, chatId),
+		copy: await getSafeChatCopy(dependencies.sessionRepo, chatId, dependencies.logger),
 		language
 	};
 }
@@ -3891,7 +4164,7 @@ async function presentLanguageSwitchForChat(chatId, api, language, dependencies)
 		found: false,
 		copy: result.copy,
 		text: result.copy.language.expired,
-		keyboard: buildLanguageKeyboard(await getChatLanguage(dependencies.sessionRepo, chatId), result.copy)
+		keyboard: buildLanguageKeyboard(await getSafeChatLanguage(dependencies.sessionRepo, chatId, dependencies.logger), result.copy)
 	};
 	return {
 		found: true,
@@ -3908,7 +4181,7 @@ function registerLanguageCommand(bot, dependencies) {
 //#endregion
 //#region src/bot/commands/models.ts
 async function handleModelsCommand(ctx, dependencies) {
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	try {
 		const result = await dependencies.listModelsUseCase.execute({ chatId: ctx.chat.id });
 		if (result.models.length === 0) {
@@ -3936,7 +4209,7 @@ function registerModelsCommand(bot, dependencies) {
 //#endregion
 //#region src/bot/commands/new.ts
 async function handleNewCommand(ctx, dependencies) {
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	try {
 		const title = extractSessionTitle(ctx);
 		const result = await dependencies.createSessionUseCase.execute({
@@ -4300,7 +4573,7 @@ function escapeLinkDestination(url) {
 //#endregion
 //#region src/bot/commands/status.ts
 async function handleStatusCommand(ctx, dependencies) {
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat?.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat?.id, dependencies.logger);
 	try {
 		const result = await dependencies.getStatusUseCase.execute({ chatId: ctx.chat?.id ?? 0 });
 		const renderedMarkdown = renderMarkdownToTelegramMarkdownV2(presentStatusMarkdownMessage(result, copy));
@@ -4322,7 +4595,7 @@ function registerStatusCommand(bot, dependencies) {
 //#endregion
 //#region src/bot/commands/sessions.ts
 async function handleSessionsCommand(ctx, dependencies) {
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	try {
 		await dependencies.pendingActionRepo.clear(ctx.chat.id);
 		const view = await buildSessionsListView(ctx.chat.id, 0, dependencies);
@@ -4345,7 +4618,7 @@ function presentStartMarkdownMessage(copy = BOT_COPY) {
 //#endregion
 //#region src/bot/commands/start.ts
 async function handleStartCommand(ctx, dependencies) {
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat?.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat?.id, dependencies.logger);
 	const reply = buildTelegramStaticReply(presentStartMarkdownMessage(copy));
 	try {
 		await ctx.reply(reply.preferred.text, reply.preferred.options);
@@ -4383,7 +4656,7 @@ async function handleAgentsCallback(ctx, dependencies) {
 	if (!data.startsWith("agents:")) return;
 	await ctx.answerCallbackQuery();
 	if (!ctx.chat) return;
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	try {
 		if (data.startsWith(AGENTS_PAGE_PREFIX)) {
 			const requestedPage = Number(data.slice(12));
@@ -4427,7 +4700,7 @@ async function handleModelsCallback(ctx, dependencies) {
 	if (!data.startsWith("model:")) return;
 	await ctx.answerCallbackQuery();
 	if (!ctx.chat) return;
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	try {
 		if (data.startsWith(MODEL_PAGE_PREFIX)) {
 			const requestedPage = Number(data.slice(11));
@@ -4506,7 +4779,7 @@ async function handleSessionsCallback(ctx, dependencies) {
 	if (!data.startsWith("sessions:")) return;
 	await ctx.answerCallbackQuery();
 	if (!ctx.chat) return;
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	try {
 		if (data.startsWith(SESSIONS_PAGE_PREFIX)) {
 			const requestedPage = Number(data.slice(14));
@@ -4587,10 +4860,10 @@ async function handleLanguageCallback(ctx, dependencies) {
 	if (!data.startsWith("language:")) return;
 	await ctx.answerCallbackQuery();
 	if (!ctx.chat || !ctx.api) return;
-	const currentCopy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const currentCopy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	try {
 		if (!data.startsWith(LANGUAGE_SELECT_PREFIX)) {
-			await ctx.editMessageText(presentLanguageMessage(await getChatLanguage(dependencies.sessionRepo, ctx.chat.id), currentCopy), { reply_markup: buildLanguageKeyboard(await getChatLanguage(dependencies.sessionRepo, ctx.chat.id), currentCopy) });
+			await ctx.editMessageText(presentLanguageMessage(await getSafeChatLanguage(dependencies.sessionRepo, ctx.chat.id, dependencies.logger), currentCopy), { reply_markup: buildLanguageKeyboard(await getSafeChatLanguage(dependencies.sessionRepo, ctx.chat.id, dependencies.logger), currentCopy) });
 			return;
 		}
 		const selectedLanguage = data.slice(16);
@@ -4657,7 +4930,7 @@ function parseSessionActionTarget(data, prefix) {
 //#endregion
 //#region src/bot/handlers/prompt.handler.ts
 async function executePromptRequest(ctx, dependencies, resolvePrompt) {
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	const foregroundRequest = dependencies.foregroundSessionTracker.acquire(ctx.chat.id);
 	if (!foregroundRequest) {
 		await ctx.reply(copy.status.alreadyProcessing);
@@ -4794,7 +5067,7 @@ function registerMessageHandler(bot, dependencies) {
 async function handleVoiceMessage(ctx, dependencies) {
 	if (!ctx.message.voice) return;
 	if (await replyIfSessionRenamePending(ctx, dependencies)) return;
-	const copy = await getChatCopy(dependencies.sessionRepo, ctx.chat.id);
+	const copy = await getSafeChatCopy(dependencies.sessionRepo, ctx.chat.id, dependencies.logger);
 	await ctx.reply(copy.errors.voiceUnsupported);
 }
 function registerVoiceHandler(bot, dependencies) {
@@ -4839,45 +5112,119 @@ function createLoggingMiddleware(logger) {
 function registerBot(bot, container, options) {
 	bot.use(createLoggingMiddleware(container.logger));
 	bot.use(createAuthMiddleware(options.telegramAllowedChatIds));
-	registerStartCommand(bot, container);
-	registerStatusCommand(bot, container);
-	registerNewCommand(bot, container);
-	registerAgentsCommand(bot, container);
-	registerSessionsCommand(bot, container);
-	registerCancelCommand(bot, container);
-	registerModelsCommand(bot, container);
-	registerLanguageCommand(bot, container);
-	registerCallbackHandler(bot, container);
-	registerFileHandler(bot, container);
-	registerMessageHandler(bot, container);
-	registerVoiceHandler(bot, container);
+	const safeBot = bot.errorBoundary(async (error) => {
+		container.logger.error({
+			...extractTelegramUpdateContext(error.ctx),
+			error: error.error
+		}, "telegram middleware failed");
+		await replyWithDefaultTelegramError(error.ctx, container.logger, error.error);
+	});
+	registerStartCommand(safeBot, container);
+	registerStatusCommand(safeBot, container);
+	registerNewCommand(safeBot, container);
+	registerAgentsCommand(safeBot, container);
+	registerSessionsCommand(safeBot, container);
+	registerCancelCommand(safeBot, container);
+	registerModelsCommand(safeBot, container);
+	registerLanguageCommand(safeBot, container);
+	registerCallbackHandler(safeBot, container);
+	registerFileHandler(safeBot, container);
+	registerMessageHandler(safeBot, container);
+	registerVoiceHandler(safeBot, container);
 }
 //#endregion
 //#region src/app/runtime.ts
+var TELEGRAM_RUNNER_OPTIONS = { runner: {
+	fetch: { timeout: 30 },
+	maxRetryTime: 900 * 1e3,
+	retryInterval: "exponential",
+	silent: true
+} };
 async function startTelegramBotRuntime(input) {
-	const bot = new Bot(input.config.telegramBotToken, { client: { apiRoot: input.config.telegramApiRoot } });
-	registerBot(bot, input.container, { telegramAllowedChatIds: input.config.telegramAllowedChatIds });
+	const runtimeKey = buildTelegramRuntimeKey(input.config);
+	const registry = getTelegramBotRuntimeRegistry();
+	const existingRuntime = registry.activeByKey.get(runtimeKey);
+	if (existingRuntime) {
+		input.container.logger.warn({
+			runtimeKey,
+			telegramApiRoot: input.config.telegramApiRoot
+		}, "telegram runtime already active in this process; reusing the existing runner");
+		await input.container.dispose();
+		return existingRuntime;
+	}
+	const runtimePromise = startTelegramBotRuntimeInternal(input, runtimeKey, () => {
+		if (registry.activeByKey.get(runtimeKey) === runtimePromise) registry.activeByKey.delete(runtimeKey);
+	}).catch((error) => {
+		if (registry.activeByKey.get(runtimeKey) === runtimePromise) registry.activeByKey.delete(runtimeKey);
+		throw error;
+	});
+	registry.activeByKey.set(runtimeKey, runtimePromise);
+	return runtimePromise;
+}
+async function startTelegramBotRuntimeInternal(input, runtimeKey, releaseRuntime) {
+	const bot = (input.botFactory ?? ((token, options) => new Bot(token, options)))(input.config.telegramBotToken, { client: { apiRoot: input.config.telegramApiRoot } });
+	wrapTelegramGetUpdates(bot, input.container);
+	(input.registerBotHandlers ?? registerBot)(bot, input.container, { telegramAllowedChatIds: input.config.telegramAllowedChatIds });
 	bot.catch((error) => {
+		const metadata = extractTelegramUpdateContext(error.ctx);
+		if (error.error instanceof GrammyError) {
+			input.container.logger.error({
+				...metadata,
+				errorCode: error.error.error_code,
+				description: error.error.description,
+				method: error.error.method,
+				parameters: error.error.parameters,
+				payload: error.error.payload
+			}, "telegram bot api request failed");
+			return;
+		}
+		if (error.error instanceof HttpError) {
+			input.container.logger.error({
+				...metadata,
+				error: error.error.error,
+				message: error.error.message
+			}, "telegram bot network request failed");
+			return;
+		}
 		input.container.logger.error({
-			error: error.error,
-			update: error.ctx.update
+			...metadata,
+			error: error.error
 		}, "telegram bot update failed");
 	});
-	input.container.logger.info("bot starting...");
-	if (input.syncCommands ?? true) await syncTelegramCommands(bot, input.container.logger);
-	const runner = run(bot);
+	input.container.logger.info({ runtimeKey }, "telegram bot polling starting");
+	const runner = (input.runBot ?? run)(bot, TELEGRAM_RUNNER_OPTIONS);
 	let stopped = false;
 	let disposed = false;
-	const stop = () => {
+	if (input.syncCommands ?? true) (input.syncCommandsHandler ?? syncTelegramCommands)(bot, input.container.logger).catch((error) => {
+		input.container.logger.warn({
+			error,
+			runtimeKey
+		}, "failed to sync telegram commands; polling continues without command registration updates");
+	});
+	let stopPromise = null;
+	const requestStop = async () => {
 		if (stopped) return;
 		stopped = true;
-		runner.stop();
+		stopPromise = runner.stop().catch((error) => {
+			input.container.logger.warn({
+				error,
+				runtimeKey
+			}, "failed to stop telegram runner cleanly");
+		});
+		await stopPromise;
+	};
+	const stop = () => {
+		requestStop();
 	};
 	const dispose = async () => {
 		if (disposed) return;
 		disposed = true;
-		stop();
-		await input.container.dispose();
+		try {
+			await requestStop();
+			await input.container.dispose();
+		} finally {
+			releaseRuntime();
+		}
 	};
 	return {
 		bot,
@@ -4886,39 +5233,69 @@ async function startTelegramBotRuntime(input) {
 		dispose
 	};
 }
+function wrapTelegramGetUpdates(bot, container) {
+	const originalGetUpdates = bot.api.getUpdates.bind(bot.api);
+	bot.api.getUpdates = async (options, signal) => {
+		const requestOptions = options ?? {
+			limit: 100,
+			offset: 0,
+			timeout: 30
+		};
+		try {
+			return await originalGetUpdates(requestOptions, signal);
+		} catch (error) {
+			container.logger.warn({
+				error,
+				limit: requestOptions.limit,
+				offset: requestOptions.offset,
+				timeout: requestOptions.timeout
+			}, "telegram getUpdates failed");
+			throw error;
+		}
+	};
+}
+function buildTelegramRuntimeKey(config) {
+	return `${config.telegramApiRoot}::${config.telegramBotToken}`;
+}
+function getTelegramBotRuntimeRegistry() {
+	const globalScope = globalThis;
+	globalScope.__opencodeTbotTelegramRuntimeRegistry__ ??= { activeByKey: /* @__PURE__ */ new Map() };
+	return globalScope.__opencodeTbotTelegramRuntimeRegistry__;
+}
 //#endregion
 //#region src/plugin.ts
-var runtimeState = null;
 async function ensureTelegramBotPluginRuntime(options) {
+	const runtimeStateHolder = getTelegramBotPluginRuntimeStateHolder();
 	const cwd = resolvePluginRuntimeCwd(options.context);
-	if (runtimeState && runtimeState.cwd !== cwd) {
-		const activeState = runtimeState;
-		runtimeState = null;
+	if (runtimeStateHolder.state && runtimeStateHolder.state.cwd !== cwd) {
+		const activeState = runtimeStateHolder.state;
+		runtimeStateHolder.state = null;
 		await disposeTelegramBotPluginRuntimeState(activeState);
 	}
-	if (!runtimeState) {
+	if (!runtimeStateHolder.state) {
 		const runtimePromise = startPluginRuntime(options, cwd).then((runtime) => {
-			if (runtimeState?.runtimePromise === runtimePromise) runtimeState.runtime = runtime;
+			if (runtimeStateHolder.state?.runtimePromise === runtimePromise) runtimeStateHolder.state.runtime = runtime;
 			return runtime;
 		}).catch((error) => {
-			if (runtimeState?.runtimePromise === runtimePromise) runtimeState = null;
+			if (runtimeStateHolder.state?.runtimePromise === runtimePromise) runtimeStateHolder.state = null;
 			throw error;
 		});
-		runtimeState = {
+		runtimeStateHolder.state = {
 			cwd,
 			runtime: null,
 			runtimePromise
 		};
 	}
-	return runtimeState.runtimePromise;
+	return runtimeStateHolder.state.runtimePromise;
 }
 var TelegramBotPlugin = async (context) => {
 	return createHooks(await ensureTelegramBotPluginRuntime({ context }));
 };
 async function resetTelegramBotPluginRuntimeForTests() {
-	if (!runtimeState) return;
-	const activeState = runtimeState;
-	runtimeState = null;
+	const runtimeStateHolder = getTelegramBotPluginRuntimeStateHolder();
+	if (!runtimeStateHolder.state) return;
+	const activeState = runtimeStateHolder.state;
+	runtimeStateHolder.state = null;
 	await disposeTelegramBotPluginRuntimeState(activeState);
 }
 async function startPluginRuntime(options, cwd) {
@@ -4971,6 +5348,11 @@ function createHooks(runtime) {
 		}
 	};
 }
+function getTelegramBotPluginRuntimeStateHolder() {
+	const globalScope = globalThis;
+	globalScope.__opencodeTbotPluginRuntimeState__ ??= { state: null };
+	return globalScope.__opencodeTbotPluginRuntimeState__;
+}
 //#endregion
 export { TelegramBotPlugin, TelegramBotPlugin as default, ensureTelegramBotPluginRuntime, resetTelegramBotPluginRuntimeForTests };