pi-harness-runtime 1.1.146 → 1.1.148

package/packages/notification/dist/telegram-webhook-handler.js

@@ -0,0 +1,149 @@
+/**
+ * Telegram Webhook Handler — RFC-0022
+ *
+ * Handles incoming webhook updates from Telegram (callback queries, messages).
+ * This enables 2-way communication with inline keyboard buttons.
+ */
+/**
+ * Predefined action prefixes for callback data
+ */
+export const CallbackActions = {
+    /** Approve/resume action */
+    APPROVE: "approve",
+    /** Reject/cancel action */
+    REJECT: "reject",
+    /** View details action */
+    VIEW: "view",
+    /** Custom action prefix */
+    CUSTOM: "custom",
+};
+/**
+ * Parse callback data string into structured object
+ * Format: "action_targetId" or "action_targetId_key1=val1,key2=val2"
+ */
+export function parseCallbackData(data) {
+    const parts = data.split("_");
+    const action = parts[0] || "";
+    const targetId = parts[1] || "";
+    let payload;
+    // Check for additional payload
+    const payloadPart = parts.slice(2).join("_");
+    if (payloadPart && payloadPart.includes("=")) {
+        payload = {};
+        for (const pair of payloadPart.split(",")) {
+            const [key, value] = pair.split("=");
+            if (key && value) {
+                payload[key] = value;
+            }
+        }
+    }
+    return { action, targetId, payload };
+}
+/**
+ * Build callback data string from components
+ */
+export function buildCallbackData(action, targetId, payload) {
+    let data = `${action}_${targetId}`;
+    if (payload && Object.keys(payload).length > 0) {
+        const pairs = Object.entries(payload)
+            .map(([k, v]) => `${k}=${v}`)
+            .join(",");
+        data += `_${pairs}`;
+    }
+    return data;
+}
+/**
+ * Create a standard Yes/No callback handler
+ */
+export function createYesNoHandler(options) {
+    return async (data, query) => {
+        const parsed = parseCallbackData(data);
+        const { action, targetId } = parsed;
+        console.log(`[TelegramWebhook] Callback: action=${action}, target=${targetId}, from=${query.from.username || query.from.first_name}`);
+        switch (action) {
+            case CallbackActions.APPROVE:
+                if (options.onApprove) {
+                    await options.onApprove(targetId, query);
+                }
+                else if (options.jobManager) {
+                    await options.jobManager.resume(targetId);
+                    console.log(`[TelegramWebhook] Job resumed: ${targetId}`);
+                }
+                break;
+            case CallbackActions.REJECT:
+                if (options.onReject) {
+                    await options.onReject(targetId, query);
+                }
+                else if (options.jobManager) {
+                    await options.jobManager.cancel(targetId);
+                    console.log(`[TelegramWebhook] Job cancelled: ${targetId}`);
+                }
+                break;
+            case CallbackActions.VIEW:
+                if (options.onCustom) {
+                    await options.onCustom(action, targetId, query);
+                }
+                break;
+            default:
+                if (options.onCustom) {
+                    await options.onCustom(action, targetId, query);
+                }
+                else {
+                    console.warn(`[TelegramWebhook] Unknown action: ${action}`);
+                }
+        }
+    };
+}
+/**
+ * Telegram webhook route handler for Express/Fastify/etc.
+ */
+export function createTelegramWebhookHandler(adapter, secretToken) {
+    return async (req, res) => {
+        // Verify secret token
+        if (secretToken) {
+            const receivedToken = req.headers["x-telegram-bot-api-secret-token"];
+            if (receivedToken !== secretToken) {
+                console.error("[TelegramWebhook] Unauthorized webhook request");
+                res.sendStatus(403);
+                return;
+            }
+        }
+        try {
+            await adapter.handleWebhookUpdate(req.body);
+            res.sendStatus(200);
+        }
+        catch (error) {
+            console.error("[TelegramWebhook] Error processing update:", error);
+            res.sendStatus(500);
+        }
+    };
+}
+/**
+ * Notification payload helper with inline keyboard support
+ */
+export function createInteractivePayload(event, jobId, title, message, buttons, details) {
+    return {
+        event,
+        jobId,
+        timestamp: new Date().toISOString(),
+        title,
+        message,
+        details: {
+            ...details,
+            _callbackButtons: buttons.map((b) => ({
+                text: b.text,
+                callbackData: buildCallbackData(b.action, b.targetId),
+            })),
+        },
+    };
+}
+/**
+ * Update TelegramConfig to include action buttons from payload details
+ */
+export function extractButtonsFromPayload(details) {
+    if (!details)
+        return undefined;
+    const cb = details._callbackButtons;
+    return cb?.length ? cb : undefined;
+}
+//# sourceMappingURL=telegram-webhook-handler.js.map

package/packages/notification/dist/telegram-webhook-handler.js.map

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

package/packages/notification/dist/types.d.ts

@@ -29,7 +29,44 @@ export interface TelegramConfig {
     botToken: string;
     chatId: string;
     parseMode?: "MarkdownV2" | "HTML" | "Markdown";
+    enableInlineKeyboard?: boolean;
+    actionButtons?: InlineKeyboardButton[];
 }
+/**
+ * Inline keyboard button for Telegram interactive messages
+ */
+export interface InlineKeyboardButton {
+    /** Button text displayed to user */
+    text: string;
+    /** Callback data sent when button is clicked */
+    callbackData: string;
+    /** Optional URL to open when button is clicked (mutually exclusive with callbackData) */
+    url?: string;
+}
+/**
+ * Callback query received from Telegram inline keyboard
+ */
+export interface TelegramCallbackQuery {
+    id: string;
+    from: {
+        id: number;
+        is_bot: boolean;
+        first_name: string;
+        username?: string;
+    };
+    chat_instance: string;
+    data: string;
+    message?: {
+        chat: {
+            id: number;
+        };
+        message_id: number;
+    };
+}
+/**
+ * Callback handler function type
+ */
+export type TelegramCallbackHandler = (callbackData: string, query: TelegramCallbackQuery) => Promise<void> | void;
 export interface NtfyConfig {
     server: string;
     topic: string;

package/packages/notification/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,iBAAiB,GAC1B,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,aAAa,GACb,iBAAiB,GACjB,kBAAkB,GAClB,sBAAsB,GACtB,WAAW,GACX,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,GACd,qBAAqB,GACrB,qBAAqB,GACrB,mBAAmB,GACnB,OAAO,CAAC;AAEX,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IAEtC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,uBAAuB,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,cAAc,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;CAC/E;AAED,MAAM,MAAM,uBAAuB,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzF,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,YAAY,GAAG,MAAM,GAAG,UAAU,CAAC;CAC/C;AAED,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/packages/notification/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/notification",
-  "version": "1.1.146",
+  "version": "1.1.148",
   "description": "pi-harness-runtime — notification",
   "type": "module",
   "main": "./dist/index.js",

package/packages/notification/src/adapters/telegram-adapter.ts

@@ -7,8 +7,11 @@
 /// <reference types="node" />
 
 import type {
+	InlineKeyboardButton,
 	NotificationPayload,
 	NotificationResult,
+	TelegramCallbackHandler,
+	TelegramCallbackQuery,
 	TelegramConfig,
 } from "../types.js";
 import { BaseChannelAdapter } from "../base-adapter.js";
@@ -17,11 +20,27 @@ export class TelegramAdapter extends BaseChannelAdapter {
 readonly id = "telegram";
 readonly type = "telegram";
 private _botUsername: string | undefined;
+private _callbackHandler: TelegramCallbackHandler | undefined;
+private _webhookSecret: string | undefined;
 
 constructor(config: TelegramConfig) {
 super({ id: "telegram", type: "telegram", enabled: true, config });
 }
 
+/**
+ * Register a callback handler for inline keyboard button clicks
+ */
+setCallbackHandler(handler: TelegramCallbackHandler): void {
+	this._callbackHandler = handler;
+}
+
+/**
+ * Set webhook secret for verification
+ */
+setWebhookSecret(secret: string): void {
+	this._webhookSecret = secret;
+}
+
 get botUsername(): string | undefined {
 return this._botUsername;
 }
@@ -43,21 +62,32 @@ return this._botUsername;
 		}
 	}
 
+	/**
+	 * Send a message with optional inline keyboard buttons
+	 */
 	async send(payload: NotificationPayload): Promise<NotificationResult> {
 		try {
 			const cfg = this.config.config as TelegramConfig;
 			const message = this.formatMessage(payload);
 
+			// Build request body
+			const body: Record<string, unknown> = {
+				chat_id: cfg.chatId,
+				text: message,
+				parse_mode: cfg.parseMode ?? "MarkdownV2",
+			};
+
+			// Add inline keyboard if enabled and buttons are configured
+			if (cfg.enableInlineKeyboard && (cfg.actionButtons?.length ?? 0) > 0) {
+				body.reply_markup = this.buildInlineKeyboard(cfg.actionButtons!);
+			}
+
 			const response = await fetch(
 				`https://api.telegram.org/bot${cfg.botToken}/sendMessage`,
 				{
 					method: "POST",
 					headers: { "Content-Type": "application/json" },
-					body: JSON.stringify({
-						chat_id: cfg.chatId,
-						text: message,
-						parse_mode: cfg.parseMode ?? "MarkdownV2",
-					}),
+					body: JSON.stringify(body),
 				},
 			);
 
@@ -80,6 +110,158 @@ return this._botUsername;
 		}
 	}
 
+	/**
+	 * Build inline keyboard markup from button configuration
+	 */
+	private buildInlineKeyboard(
+		buttons: InlineKeyboardButton[],
+	): { inline_keyboard: Array<Array<{ text: string; callback_data?: string; url?: string }>> } {
+		// Group buttons into rows of up to 3 buttons each (Telegram limit)
+		const ROW_SIZE = 3;
+		const rows: Array<Array<{ text: string; callback_data?: string; url?: string }>> = [];
+
+		for (let i = 0; i < buttons.length; i += ROW_SIZE) {
+			const row = buttons.slice(i, i + ROW_SIZE).map((btn) => ({
+				text: btn.text,
+				...(btn.url ? { url: btn.url } : { callback_data: btn.callbackData }),
+			}));
+			rows.push(row);
+		}
+
+		return { inline_keyboard: rows };
+	}
+
+	/**
+	 * Process incoming webhook update from Telegram
+	 */
+	async handleWebhookUpdate(update: Record<string, unknown>): Promise<void> {
+		// Verify secret token if set
+		if (this._webhookSecret) {
+			const secretToken = (update as { secret_token?: string }).secret_token;
+			if (secretToken !== this._webhookSecret) {
+				console.error("[TelegramAdapter] Invalid webhook secret");
+				return;
+			}
+		}
+
+		// Handle callback query (button click)
+		const callbackQuery = update.callback_query as Record<string, unknown> | undefined;
+		if (callbackQuery && this._callbackHandler) {
+			const query = this.parseCallbackQuery(callbackQuery);
+			if (query) {
+				await this._callbackHandler(query.data, query);
+				await this.answerCallbackQuery(query.id);
+			}
+		}
+
+		// Handle regular messages (future: user can type commands)
+		const message = update.message as Record<string, unknown> | undefined;
+		if (message) {
+			console.log("[TelegramAdapter] Received message:", message.text);
+		}
+	}
+
+	/**
+	 * Parse callback query from webhook update
+	 */
+	private parseCallbackQuery(
+		raw: Record<string, unknown>,
+	): TelegramCallbackQuery | null {
+		try {
+			const from = raw.from as Record<string, unknown>;
+			const message = raw.message as Record<string, unknown> | undefined;
+			const chat = message?.chat as Record<string, unknown> | undefined;
+
+			return {
+				id: String(raw.id),
+				from: {
+					id: Number(from?.id),
+					is_bot: Boolean(from?.is_bot),
+					first_name: String(from?.first_name ?? ""),
+					username: from?.username ? String(from.username) : undefined,
+				},
+				chat_instance: String(raw.chat_instance ?? ""),
+				data: String(raw.data ?? ""),
+				message: message
+					? {
+							chat: { id: Number(chat?.id) },
+							message_id: Number(message?.message_id),
+						}
+					: undefined,
+			};
+		} catch {
+			console.error("[TelegramAdapter] Failed to parse callback query");
+			return null;
+		}
+	}
+
+	/**
+	 * Answer a callback query to remove loading state
+	 */
+	private async answerCallbackQuery(callbackQueryId: string): Promise<void> {
+		try {
+			const cfg = this.config.config as TelegramConfig;
+			await fetch(
+				`https://api.telegram.org/bot${cfg.botToken}/answerCallbackQuery`,
+				{
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({ callback_query_id: callbackQueryId }),
+				},
+			);
+		} catch (error) {
+			console.error("[TelegramAdapter] Failed to answer callback query:", error);
+		}
+	}
+
+	/**
+	 * Setup webhook for receiving updates
+	 */
+	async setupWebhook(webhookUrl: string): Promise<boolean> {
+		try {
+			const cfg = this.config.config as TelegramConfig;
+			const response = await fetch(
+				`https://api.telegram.org/bot${cfg.botToken}/setWebhook`,
+				{
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({
+						url: webhookUrl,
+						secret_token: this._webhookSecret,
+					}),
+				},
+			);
+
+			if (!response.ok) {
+				console.error("[TelegramAdapter] Webhook setup failed:", await response.text());
+				return false;
+			}
+
+			console.log(`[TelegramAdapter] Webhook set to: ${webhookUrl}`);
+			return true;
+		} catch (error) {
+			console.error("[TelegramAdapter] Webhook setup error:", error);
+			return false;
+		}
+	}
+
+	/**
+	 * Get current webhook info
+	 */
+	async getWebhookInfo(): Promise<Record<string, unknown> | null> {
+		try {
+			const cfg = this.config.config as TelegramConfig;
+			const response = await fetch(
+				`https://api.telegram.org/bot${cfg.botToken}/getWebhookInfo`,
+			);
+
+			if (!response.ok) return null;
+			return (await response.json()) as Record<string, unknown>;
+		} catch {
+			return null;
+		}
+	}
+
 	private formatMessage(payload: NotificationPayload): string {
 		const emoji = this.getEmoji(payload.event);
 		const title = `${emoji} ${payload.title}`;

package/packages/notification/src/index.ts

@@ -7,4 +7,6 @@
 export * from "./notification-center.js";
 export * from "./base-adapter.js";
 export * from "./types.js";
+export * from "./telegram-webhook-handler.js";
 export { LineAdapter } from "./adapters/line-adapter.js";
+export { TelegramAdapter } from "./adapters/telegram-adapter.js";

package/packages/notification/src/notification-center.ts

@@ -10,15 +10,19 @@
  */
 
 import type {
+	InlineKeyboardButton,
 	NotificationEvent,
 	NotificationPayload,
 	NotificationConfig,
 	NotificationChannelConfig,
 	NotificationResult,
 	NotificationContext,
+	TelegramCallbackHandler,
+	TelegramCallbackQuery,
 } from "./types.js";
 import type { ChannelAdapter } from "./base-adapter.js";
 import { TelegramAdapter } from "./adapters/telegram-adapter.js";
+import { buildCallbackData, parseCallbackData, CallbackActions } from "./telegram-webhook-handler.js";
 import { LineAdapter } from "./adapters/line-adapter.js";
 import { NtfyAdapter } from "./adapters/ntfy-adapter.js";
 import { EmailAdapter } from "./adapters/email-adapter.js";
@@ -158,6 +162,132 @@ export class NotificationCenter {
 		return undefined;
 	}
 
+	/**
+	 * Get Telegram adapter for advanced operations (webhook setup, etc.)
+	 */
+	getTelegramAdapter(): TelegramAdapter | undefined {
+		const adapter = this.adapters.get("telegram");
+		if (adapter instanceof TelegramAdapter) {
+			return adapter;
+		}
+		return undefined;
+	}
+
+	/**
+	 * Set callback handler for Telegram inline keyboard button clicks
+	 */
+	setTelegramCallbackHandler(handler: TelegramCallbackHandler): void {
+		const adapter = this.adapters.get("telegram");
+		if (adapter instanceof TelegramAdapter) {
+			adapter.setCallbackHandler(handler);
+		}
+	}
+
+	/**
+	 * Set webhook secret for Telegram updates verification
+	 */
+	setTelegramWebhookSecret(secret: string): void {
+		const adapter = this.adapters.get("telegram");
+		if (adapter instanceof TelegramAdapter) {
+			adapter.setWebhookSecret(secret);
+		}
+	}
+
+	/**
+	 * Setup Telegram webhook for receiving updates
+	 */
+	async setupTelegramWebhook(webhookUrl: string): Promise<boolean> {
+		const adapter = this.adapters.get("telegram");
+		if (adapter instanceof TelegramAdapter) {
+			return await adapter.setupWebhook(webhookUrl);
+		}
+		return false;
+	}
+
+	/**
+	 * Send notification with interactive Yes/No buttons
+	 */
+	async notifyWithApproval(
+		event: NotificationEvent,
+		context: NotificationContext,
+		options?: {
+			/** Custom button labels */
+			approveLabel?: string;
+			rejectLabel?: string;
+			/** Additional details for the message */
+			additionalDetails?: Record<string, unknown>;
+		},
+	): Promise<NotificationResult[]> {
+		const approveLabel = options?.approveLabel ?? "Yes";
+		const rejectLabel = options?.rejectLabel ?? "No";
+
+		// Build buttons
+		const buttons: InlineKeyboardButton[] = [
+			{ text: `\u2705 ${approveLabel}`, callbackData: buildCallbackData(CallbackActions.APPROVE, context.jobId) },
+			{ text: `\u274C ${rejectLabel}`, callbackData: buildCallbackData(CallbackActions.REJECT, context.jobId) },
+		];
+
+		// Send to each channel with buttons (Telegram only)
+		const results: NotificationResult[] = [];
+
+		for (const [id, adapter] of this.adapters.entries()) {
+			if (adapter instanceof TelegramAdapter) {
+				try {
+					const payload = this.buildPayload(event, context, {
+						enableInlineKeyboard: true,
+						actionButtons: buttons,
+						...(options?.additionalDetails && { additionalDetails: options.additionalDetails }),
+					});
+					const result = await adapter.send(payload);
+					results.push(result);
+				} catch (error) {
+					results.push({ success: false, channel: id, error: String(error) });
+				}
+			}
+		}
+
+		return results;
+	}
+
+	/**
+	 * Send interactive notification with custom buttons
+	 */
+	async notifyWithButtons(
+		event: NotificationEvent,
+		context: NotificationContext,
+		buttons: Array<{ text: string; action: string; targetId: string; url?: string }>,
+		options?: {
+			/** Additional details for the message */
+			additionalDetails?: Record<string, unknown>;
+		},
+	): Promise<NotificationResult[]> {
+		const results: NotificationResult[] = [];
+
+		for (const [id, adapter] of this.adapters.entries()) {
+			if (adapter instanceof TelegramAdapter) {
+				try {
+					const formattedButtons: InlineKeyboardButton[] = buttons.map((b) => ({
+						text: b.text,
+						callbackData: buildCallbackData(b.action, b.targetId),
+						url: b.url,
+					}));
+
+					const payload = this.buildPayload(event, context, {
+						enableInlineKeyboard: true,
+						actionButtons: formattedButtons,
+						...(options?.additionalDetails && { additionalDetails: options.additionalDetails }),
+					});
+					const result = await adapter.send(payload);
+					results.push(result);
+				} catch (error) {
+					results.push({ success: false, channel: id, error: String(error) });
+				}
+			}
+		}
+
+		return results;
+	}
+
 	// --- Private Methods ------------------------------------------------
 
 	private createAdapter(
@@ -192,6 +322,11 @@ export class NotificationCenter {
 	private buildPayload(
 		event: NotificationEvent,
 		context: NotificationContext,
+		options?: {
+			enableInlineKeyboard?: boolean;
+			actionButtons?: InlineKeyboardButton[];
+			additionalDetails?: Record<string, unknown>;
+		},
 	): NotificationPayload {
 		const { title, message } = this.getEventContent(event, context);
 
@@ -207,6 +342,10 @@ export class NotificationCenter {
 				...(context.taskId && { taskId: context.taskId }),
 				...(context.taskTitle && { taskTitle: context.taskTitle }),
 				...(context.error && { error: context.error }),
+				// Pass inline keyboard options to Telegram adapter
+				...(options?.enableInlineKeyboard && { _enableInlineKeyboard: true }),
+				...(options?.actionButtons && { _actionButtons: options.actionButtons }),
+				...(options?.additionalDetails && options.additionalDetails),
 			},
 		};
 	}