telegram-approval-buttons 4.0.1

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [4.0.1] - 2026-02-15
+
+### Added
+- Composite banner image showing the full approval workflow
+- `tsconfig.json` for IDE TypeScript support
+- `uiHints` in manifest for better config UI labels
+
+### Changed
+- Rewritten README with simplified 3-step Quick Start for beginners
+- FAQ section with 5 common questions
+- Cleaner troubleshooting table with less jargon
+
+### Fixed
+- `/approvalstatus` command showing raw HTML `<b>` tags instead of plain text
+- Plugin ID mismatch warning on gateway startup (aligned `package.json` name with manifest `id`)
+
+## [4.0.0] - 2026-02-14
+
+### Added
+- Initial public release
+- One-tap inline keyboard buttons: ✅ Allow Once · 🔏 Always · ❌ Deny
+- Auto-resolve: edits message after decision, removes buttons
+- Expiry handling: stale approvals auto-cleaned after configurable timeout
+- `/approvalstatus` diagnostic command with health check
+- Auto-detection of `chatId` and `botToken` from `channels.telegram` config
+- Modular architecture: `index.ts` orchestration + 5 lib modules
+- Full `configSchema` with JSON Schema validation
+- MIT license

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jair Franco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# 🔐 Telegram Approval Buttons for OpenClaw
+
+> One-tap `exec` approvals in Telegram — no more typing `/approve <uuid> allow-once`.
+
+## What does this look like?
+
+<p align="center">
+  <img src="docs/banner.png" alt="Plugin workflow: approval request → allowed → health check" />
+</p>
+
+## What does this do?
+
+OpenClaw's Discord has built-in approval buttons. **Telegram doesn't** — you're stuck typing long `/approve` commands. This plugin fixes that.
+
+**Features:**
+- ✅ **One-tap approvals** — Allow Once · 🔏 Always · ❌ Deny
+- 🔄 **Auto-resolve** — edits the message after decision (removes buttons, shows result)
+- ⏰ **Expiry handling** — stale approvals auto-cleaned and marked as expired
+- 🩺 **Self-diagnostics** — `/approvalstatus` checks health and stats
+- 🛡️ **Graceful fallback** — if buttons fail, the original text goes through
+- 📦 **Zero dependencies** — uses only Node.js built-in `fetch`
+
+## Quick Start
+
+### Step 1: Download the plugin
+
+```bash
+git clone https://github.com/JairFC/openclaw-telegram-approval-buttons.git
+```
+
+### Step 2: Add to your config
+
+Open your `openclaw.json` and add this block. If the `"plugins"` section already exists, just merge the contents:
+
+```jsonc
+{
+  "plugins": {
+    "load": {
+      "paths": ["/path/to/openclaw-telegram-approval-buttons"]
+    },
+    "entries": {
+      "telegram-approval-buttons": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+> 💡 **Replace `/path/to/`** with the actual path where you cloned the repo.  
+> Example: `"/home/jair/Projects/openclaw-telegram-approval-buttons"`
+
+### Step 3: Restart and verify
+
+```bash
+openclaw gateway restart
+```
+
+Then send `/approvalstatus` in your Telegram chat. You should see:
+
+```
+🟢 Approval Buttons Status
+
+Config: chatId=✓ · token=✓
+Telegram: ✓ connected (@your_bot)
+Pending: 0 · Processed: 0
+Uptime: 1m
+```
+
+**That's it!** Next time the AI triggers an `exec` approval, you'll get buttons.
+
+## Prerequisites
+
+- **OpenClaw ≥ 2026.2.9** installed and running
+- **Node.js ≥ 22** (uses built-in `fetch`)
+- **Telegram configured** in your `openclaw.json`
+- **Exec approvals enabled** — `tools.exec.ask` must NOT be `"off"`
+
+## How it works
+
+```
+┌─────────────┐    message_sending     ┌──────────────────┐
+│  OpenClaw    │ ── approval text ──→  │     Plugin        │
+│  Gateway     │                       │                   │
+│              │   cancel original     │  1. Parse text    │
+│              │ ←──────────────────── │  2. Send buttons  │
+└─────────────┘                        │  3. Track pending │
+                                       └────────┬─────────┘
+                                                │
+                                    Telegram Bot API
+                                                │
+                                       ┌────────▼─────────┐
+                                       │   Telegram Chat   │
+                                       │                   │
+                                       │  🔐 Exec Approval │
+                                       │  [✅ Allow] [🔏]  │
+                                       │  [❌ Deny]        │
+                                       └──────────────────┘
+```
+
+When you tap a button, OpenClaw converts the `callback_data` into a synthetic text message — **no webhook needed**.
+
+## Configuration
+
+The plugin **auto-detects** `botToken` and `chatId` from your Telegram channel config. Most setups need zero extra configuration.
+
+### Config resolution order
+
+| Setting    | Priority 1 (explicit)       | Priority 2 (shared config)         | Priority 3 (env)          |
+|------------|-----------------------------|------------------------------------|---------------------------|
+| `botToken` | `pluginConfig.botToken`     | `channels.telegram.token`          | `TELEGRAM_BOT_TOKEN`      |
+| `chatId`   | `pluginConfig.chatId`       | `channels.telegram.allowFrom[0]`   | `TELEGRAM_CHAT_ID`        |
+
+### Advanced options
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "telegram-approval-buttons": {
+        "enabled": true,
+        "config": {
+          "chatId": "123456789",       // Override auto-detected chat ID
+          "botToken": "123:ABC...",     // Override auto-detected bot token
+          "staleMins": 10,             // Minutes before stale cleanup (default: 10)
+          "verbose": false             // Diagnostic logging (default: false)
+        }
+      }
+    }
+  }
+}
+```
+
+## FAQ
+
+**Q: I installed the plugin but no buttons appear.**  
+A: Make sure `tools.exec.ask` is NOT set to `"off"` in your config. If it's `"off"`, there are no approvals to buttonize. Set it to `"on-miss"` or `"always"`.
+
+**Q: How do I find my Telegram Chat ID?**  
+A: Send `/start` to [@userinfobot](https://t.me/userinfobot) on Telegram — it replies with your ID. Alternatively, check `https://api.telegram.org/bot<TOKEN>/getUpdates` after sending a message to your bot.
+
+**Q: Do I need to set up a webhook?**  
+A: No! OpenClaw's Telegram integration automatically converts button taps into synthetic text messages. No extra setup needed.
+
+**Q: What happens if the plugin fails to send buttons?**  
+A: The original plain-text approval message goes through normally. The plugin never blocks approvals.
+
+**Q: Does this work in group chats?**  
+A: Yes, but the bot needs to be an admin or it needs permission to edit its own messages.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| No buttons appear | Check `tools.exec.ask` is not `"off"`. Run `/approvalstatus` to check config. |
+| Buttons show but nothing happens | Bot needs message editing permission. Use a private chat or make bot admin. |
+| `/approvalstatus` says "token=✗" | Set `botToken` in plugin config, or check `channels.telegram.token`. |
+| `/approvalstatus` says "chatId=✗" | Set `chatId` in plugin config, or add your ID to `channels.telegram.allowFrom`. |
+| Buttons say "expired" | Approval timed out before you tapped. Adjust `staleMins` if needed. |
+
+## Architecture
+
+```
+telegram-approval-buttons/
+├── index.ts                  # Entry point — orchestration only
+├── types.ts                  # Shared TypeScript interfaces
+├── lib/
+│   ├── telegram-api.ts       # Telegram Bot API client (isolated)
+│   ├── approval-parser.ts    # Parse OpenClaw approval text format
+│   ├── message-formatter.ts  # HTML formatting for Telegram messages
+│   ├── approval-store.ts     # In-memory pending approval tracker
+│   └── diagnostics.ts        # Config resolution, health checks
+├── openclaw.plugin.json      # Plugin manifest
+└── package.json
+```
+
+## Contributing
+
+Issues and PRs welcome. Each file in `lib/` is self-contained with a single responsibility.
+
+## License
+
+[MIT](LICENSE)

package/index.ts

@@ -0,0 +1,195 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// telegram-approval-buttons · index.ts (v4.0.0)
+// Plugin entry point — orchestration only, all logic lives in lib/
+//
+// Adds inline keyboard buttons to exec approval messages in Telegram.
+// When a user taps a button, OpenClaw processes the /approve command
+// automatically via its callback_query → synthetic text message pipeline.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import type { PluginConfig } from "./types.js";
+
+// ── Modules ─────────────────────────────────────────────────────────────────
+
+import { TelegramApi } from "./lib/telegram-api.js";
+import { ApprovalStore } from "./lib/approval-store.js";
+import { parseApprovalText, detectApprovalResult } from "./lib/approval-parser.js";
+import {
+  formatApprovalRequest,
+  formatApprovalResolved,
+  formatApprovalExpired,
+  buildApprovalKeyboard,
+  formatHealthCheck,
+} from "./lib/message-formatter.js";
+import {
+  resolveConfig,
+  runHealthCheck,
+  logStartupDiagnostics,
+  runStartupChecks,
+} from "./lib/diagnostics.js";
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+const PLUGIN_VERSION = "4.0.1";
+const TAG = "telegram-approval-buttons";
+
+// ── Plugin registration ─────────────────────────────────────────────────────
+
+function register(api: any): void {
+  const log = api.logger;
+  const startedAt = Date.now();
+
+  // ─── 1. Resolve config ────────────────────────────────────────────────
+
+  const pluginCfg: PluginConfig = api.pluginConfig ?? {};
+  const telegramCfg = api.config?.channels?.telegram ?? {};
+
+  const config = resolveConfig(
+    {
+      pluginConfig: pluginCfg,
+      telegramChannelConfig: {
+        token: telegramCfg.token,
+        allowFrom: telegramCfg.allowFrom,
+      },
+      env: {
+        TELEGRAM_BOT_TOKEN: process.env.TELEGRAM_BOT_TOKEN,
+        TELEGRAM_CHAT_ID: process.env.TELEGRAM_CHAT_ID,
+      },
+    },
+    log,
+  );
+
+  if (!config) {
+    log.warn(`[${TAG}] v${PLUGIN_VERSION} loaded (DISABLED — missing config)`);
+    return;
+  }
+
+  logStartupDiagnostics(config, log);
+
+  // ─── 2. Initialize modules ───────────────────────────────────────────
+
+  const tg = new TelegramApi(config.botToken, config.verbose ? log : undefined);
+
+  const store = new ApprovalStore(
+    config.staleMins * 60_000,
+    config.verbose ? log : undefined,
+    // onExpired: edit the Telegram message to show "expired"
+    (entry) => {
+      tg.editMessageText(
+        config.chatId,
+        entry.messageId,
+        formatApprovalExpired(entry.info),
+      ).catch(() => { });
+    },
+  );
+
+  // ─── 3. Register background service (cleanup timer) ──────────────────
+
+  api.registerService({
+    id: `${TAG}-cleanup`,
+    start: () => {
+      store.start();
+      // Non-blocking connectivity check
+      runStartupChecks(tg, log).catch(() => { });
+    },
+    stop: () => store.stop(),
+  });
+
+  // ─── 4. Register /approvalstatus command ─────────────────────────────
+
+  api.registerCommand({
+    name: "approvalstatus",
+    description: "Show approval buttons plugin health and stats",
+    acceptsArgs: false,
+    requireAuth: true,
+    handler: async () => {
+      const health = await runHealthCheck(config, tg, store, startedAt);
+      return { text: formatHealthCheck(health) };
+    },
+  });
+
+  // ─── 5. Register message_sending hook ────────────────────────────────
+
+  api.on(
+    "message_sending",
+    async (
+      event: { to: string; content: string; metadata?: Record<string, unknown> },
+      ctx: { channelId: string; accountId?: string },
+    ) => {
+      // Only intercept Telegram messages
+      if (ctx.channelId !== "telegram") return;
+
+      // ── 5a. Check for approval resolution ───────────────────────────
+      const resolution = detectApprovalResult(event.content, store.entries());
+      if (resolution) {
+        const entry = store.resolve(resolution.id);
+        if (entry) {
+          log.info(
+            `[${TAG}] resolved ${resolution.id.slice(0, 8)}… → ${resolution.action}`,
+          );
+          const edited = await tg.editMessageText(
+            config.chatId,
+            entry.messageId,
+            formatApprovalResolved(entry.info, resolution.action),
+          );
+          if (edited && config.verbose) {
+            log.info(`[${TAG}] edited msg=${entry.messageId}`);
+          }
+        }
+        // Don't cancel — let resolution messages pass through
+        return;
+      }
+
+      // ── 5b. Check for new approval request ─────────────────────────
+      const info = parseApprovalText(event.content);
+      if (!info) return;
+
+      // Duplicate guard
+      if (store.has(info.id)) {
+        if (config.verbose) {
+          log.info(`[${TAG}] skipping duplicate ${info.id.slice(0, 8)}…`);
+        }
+        return { cancel: true };
+      }
+
+      log.info(`[${TAG}] intercepting ${info.id.slice(0, 8)}…`);
+
+      // Send formatted message with inline buttons
+      const messageId = await tg.sendMessage(
+        config.chatId,
+        formatApprovalRequest(info),
+        buildApprovalKeyboard(info.id),
+      );
+
+      if (messageId === null) {
+        log.warn(`[${TAG}] send failed for ${info.id.slice(0, 8)}… — falling back to plain text`);
+        // Don't cancel: let the plain-text message through as fallback
+        return;
+      }
+
+      // Track it
+      store.add(info.id, messageId, info);
+      log.info(`[${TAG}] sent buttons for ${info.id.slice(0, 8)}… (msg=${messageId})`);
+
+      // Cancel the original plain-text message
+      return { cancel: true };
+    },
+  );
+
+  // ─── Done ─────────────────────────────────────────────────────────────
+
+  log.info(`[${TAG}] v${PLUGIN_VERSION} loaded ✓`);
+}
+
+// ─── Plugin export ──────────────────────────────────────────────────────────
+
+export default {
+  id: "telegram-approval-buttons",
+  name: "Telegram Approval Buttons",
+  description:
+    "Adds inline keyboard buttons to exec approval messages in Telegram. " +
+    "Tap to approve/deny without typing commands.",
+  version: PLUGIN_VERSION,
+  kind: "extension" as const,
+  register,
+};

package/lib/approval-parser.ts

@@ -0,0 +1,84 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// telegram-approval-buttons · lib/approval-parser.ts
+// Parse OpenClaw's plain-text exec approval format into structured data
+// ─────────────────────────────────────────────────────────────────────────────
+
+import type { ApprovalAction, ApprovalInfo, ApprovalResolution, SentApproval } from "../types.js";
+
+// ─── Regex patterns (compiled once) ─────────────────────────────────────────
+
+const RE_APPROVAL_MARKER = /Exec approval required/i;
+const RE_ID = /ID:\s*([a-f0-9-]+)/i;
+const RE_COMMAND_BLOCK = /Command:\s*`{0,3}\n?(.+?)\n?`{0,3}(?:\n|$)/is;
+const RE_COMMAND_INLINE = /Command:\s*(.+)/i;
+const RE_CWD = /CWD:\s*(.+)/i;
+const RE_HOST = /Host:\s*(.+)/i;
+const RE_AGENT = /Agent:\s*(.+)/i;
+const RE_SECURITY = /Security:\s*(.+)/i;
+const RE_ASK = /Ask:\s*(.+)/i;
+const RE_EXPIRES = /Expires in:\s*(.+)/i;
+
+/**
+ * Parse OpenClaw's plain-text approval message into an ApprovalInfo object.
+ *
+ * Returns null if the text doesn't match the approval format.
+ * This function is intentionally lenient — it extracts what it can and
+ * falls back to sensible defaults for missing fields.
+ */
+export function parseApprovalText(text: string): ApprovalInfo | null {
+  if (!RE_APPROVAL_MARKER.test(text)) return null;
+
+  const id = text.match(RE_ID)?.[1]?.trim();
+  if (!id) return null;
+
+  // Try block format first (```command```), then inline
+  let command = text.match(RE_COMMAND_BLOCK)?.[1]?.trim();
+  if (!command) command = text.match(RE_COMMAND_INLINE)?.[1]?.trim() ?? "unknown";
+
+  return {
+    id,
+    command,
+    cwd: text.match(RE_CWD)?.[1]?.trim() ?? "unknown",
+    host: text.match(RE_HOST)?.[1]?.trim() ?? "gateway",
+    agent: text.match(RE_AGENT)?.[1]?.trim() ?? "main",
+    security: text.match(RE_SECURITY)?.[1]?.trim() ?? "allowlist",
+    ask: text.match(RE_ASK)?.[1]?.trim() ?? "on-miss",
+    expires: text.match(RE_EXPIRES)?.[1]?.trim() ?? "120s",
+  };
+}
+
+/**
+ * Detect if an outgoing message indicates an approval was resolved.
+ *
+ * Checks whether the message text references any pending approval ID
+ * (full UUID or first 8 chars) and attempts to determine the action.
+ */
+export function detectApprovalResult(
+  text: string,
+  pending: ReadonlyMap<string, SentApproval>,
+): ApprovalResolution | null {
+  for (const [id] of pending) {
+    const shortId = id.slice(0, 8);
+    if (!text.includes(id) && !text.includes(shortId)) continue;
+
+    const action = inferAction(text);
+    return { id, action };
+  }
+  return null;
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────────
+
+/**
+ * Infer the approval action from message text.
+ * Order matters: check most specific patterns first.
+ */
+function inferAction(text: string): ApprovalAction {
+  const lower = text.toLowerCase();
+  if (lower.includes("allow-always") || lower.includes("always allow")) return "allow-always";
+  if (lower.includes("deny") || lower.includes("denied") || lower.includes("rejected")) return "deny";
+  if (lower.includes("allow-once") || lower.includes("allowed")) return "allow-once";
+  if (lower.includes("approved")) return "allow-once";
+  // Default when we see the ID but can't determine action
+  return "allow-once";
+}

package/lib/approval-store.ts

@@ -0,0 +1,143 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// telegram-approval-buttons · lib/approval-store.ts
+// In-memory store for pending approvals with TTL-based cleanup
+// ─────────────────────────────────────────────────────────────────────────────
+
+import type { ApprovalAction, ApprovalInfo, Logger, SentApproval } from "../types.js";
+
+/**
+ * Manages the lifecycle of pending approval requests.
+ *
+ * Responsibilities:
+ * - Track sent approval messages (approval ID → SentApproval)
+ * - Auto-purge stale entries after configurable TTL
+ * - Provide stats for diagnostics
+ *
+ * All state is in-memory — approvals are ephemeral by nature
+ * and don't survive gateway restarts (by design).
+ */
+export class ApprovalStore {
+  private readonly pending = new Map<string, SentApproval>();
+  private totalProcessed = 0;
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    private readonly staleTtlMs: number,
+    private readonly log?: Logger,
+    private readonly onExpired?: (entry: SentApproval) => void,
+  ) { }
+
+  // ── Lifecycle ─────────────────────────────────────────────────────────
+
+  /**
+   * Start periodic stale-entry cleanup (runs every staleTtlMs / 2).
+   */
+  start(): void {
+    if (this.cleanupTimer) return;
+    const interval = Math.max(this.staleTtlMs / 2, 30_000);
+    this.cleanupTimer = setInterval(() => this.cleanStale(), interval);
+    // Prevent the timer from keeping the process alive
+    if (this.cleanupTimer && typeof this.cleanupTimer === "object" && "unref" in this.cleanupTimer) {
+      (this.cleanupTimer as NodeJS.Timeout).unref();
+    }
+  }
+
+  /**
+   * Stop the cleanup timer.
+   */
+  stop(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+
+  // ── Core operations ───────────────────────────────────────────────────
+
+  /**
+   * Track a newly sent approval message.
+   */
+  add(approvalId: string, messageId: number, info: ApprovalInfo): void {
+    this.pending.set(approvalId, {
+      messageId,
+      info,
+      sentAt: Date.now(),
+    });
+  }
+
+  /**
+   * Check if an approval is already being tracked.
+   */
+  has(approvalId: string): boolean {
+    return this.pending.has(approvalId);
+  }
+
+  /**
+   * Get a pending approval entry.
+   */
+  get(approvalId: string): SentApproval | undefined {
+    return this.pending.get(approvalId);
+  }
+
+  /**
+   * Resolve (remove) a pending approval and increment the processed counter.
+   * Returns the entry if it existed.
+   */
+  resolve(approvalId: string): SentApproval | undefined {
+    const entry = this.pending.get(approvalId);
+    if (entry) {
+      this.pending.delete(approvalId);
+      this.totalProcessed++;
+    }
+    return entry;
+  }
+
+  /**
+   * Get a read-only view of all pending approvals.
+   */
+  entries(): ReadonlyMap<string, SentApproval> {
+    return this.pending;
+  }
+
+  // ── Stats ─────────────────────────────────────────────────────────────
+
+  get pendingCount(): number {
+    return this.pending.size;
+  }
+
+  get processedCount(): number {
+    return this.totalProcessed;
+  }
+
+  // ── Cleanup ───────────────────────────────────────────────────────────
+
+  /**
+   * Remove entries older than staleTtlMs.
+   * Calls onExpired callback for each removed entry (e.g., to edit the Telegram message).
+   */
+  cleanStale(): number {
+    const now = Date.now();
+    let removed = 0;
+
+    for (const [id, entry] of this.pending) {
+      if (now - entry.sentAt > this.staleTtlMs) {
+        this.pending.delete(id);
+        removed++;
+        this.log?.debug?.(
+          `[approval-store] purged stale: ${id.slice(0, 8)}… (age=${Math.floor((now - entry.sentAt) / 1000)}s)`,
+        );
+        try {
+          this.onExpired?.(entry);
+        } catch {
+          // Non-critical — just log and continue
+        }
+      }
+    }
+
+    if (removed > 0) {
+      this.log?.info(`[approval-store] cleaned ${removed} stale entries`);
+    }
+
+    return removed;
+  }
+}

package/lib/diagnostics.ts

@@ -0,0 +1,164 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// telegram-approval-buttons · lib/diagnostics.ts
+// Self-diagnostics: config validation, connectivity check, auto-repair
+// ─────────────────────────────────────────────────────────────────────────────
+
+import type { HealthCheck, Logger, PluginConfig, ResolvedConfig } from "../types.js";
+import type { TelegramApi } from "./telegram-api.js";
+import type { ApprovalStore } from "./approval-store.js";
+
+// ─── Config resolution ─────────────────────────────────────────────────────
+
+export interface ConfigSources {
+  pluginConfig: PluginConfig;
+  telegramChannelConfig: { token?: string; allowFrom?: (string | number)[] };
+  env: { TELEGRAM_BOT_TOKEN?: string; TELEGRAM_CHAT_ID?: string };
+}
+
+/**
+ * Resolve plugin configuration from multiple sources with priority:
+ * 1. pluginConfig (explicit config in openclaw.json)
+ * 2. channels.telegram (shared Telegram config)
+ * 3. Environment variables (fallback)
+ *
+ * Returns null with diagnostic messages if critical config is missing.
+ */
+export function resolveConfig(
+  sources: ConfigSources,
+  log: Logger,
+): ResolvedConfig | null {
+  const { pluginConfig, telegramChannelConfig, env } = sources;
+
+  // ── Bot token resolution ────────────────────────────────────────────
+  const botToken =
+    pluginConfig.botToken ||
+    telegramChannelConfig.token ||
+    env.TELEGRAM_BOT_TOKEN ||
+    "";
+
+  if (!botToken) {
+    log.warn(
+      "[diagnostics] No bot token found. Check: " +
+        "pluginConfig.botToken → channels.telegram.token → TELEGRAM_BOT_TOKEN env",
+    );
+  }
+
+  // ── Chat ID resolution ──────────────────────────────────────────────
+  let chatId = pluginConfig.chatId || env.TELEGRAM_CHAT_ID || "";
+
+  // Auto-repair: extract from allowFrom if not explicitly set
+  if (!chatId && Array.isArray(telegramChannelConfig.allowFrom)) {
+    const first = telegramChannelConfig.allowFrom[0];
+    const candidate = String(first ?? "");
+    if (/^-?\d+$/.test(candidate)) {
+      chatId = candidate;
+      log.info(
+        `[diagnostics] Auto-resolved chatId from channels.telegram.allowFrom: ${chatId}`,
+      );
+    }
+  }
+
+  if (!chatId) {
+    log.warn(
+      "[diagnostics] No chatId found. Set pluginConfig.chatId, " +
+        "TELEGRAM_CHAT_ID env, or channels.telegram.allowFrom",
+    );
+  }
+
+  // ── Missing critical config ─────────────────────────────────────────
+  if (!botToken || !chatId) {
+    log.error("[diagnostics] Plugin disabled due to missing configuration");
+    return null;
+  }
+
+  // ── Optional config with defaults ───────────────────────────────────
+  const staleMins =
+    typeof pluginConfig.staleMins === "number" && pluginConfig.staleMins > 0
+      ? pluginConfig.staleMins
+      : 10;
+
+  const verbose = pluginConfig.verbose === true;
+
+  return { chatId, botToken, staleMins, verbose };
+}
+
+// ─── Health check ───────────────────────────────────────────────────────────
+
+/**
+ * Run a full health check: config validation + Telegram connectivity + store stats.
+ */
+export async function runHealthCheck(
+  config: ResolvedConfig | null,
+  tg: TelegramApi | null,
+  store: ApprovalStore,
+  startedAt: number,
+): Promise<HealthCheck> {
+  const health: HealthCheck = {
+    ok: false,
+    config: {
+      chatId: !!config?.chatId,
+      botToken: !!config?.botToken,
+    },
+    telegram: { reachable: false },
+    store: {
+      pending: store.pendingCount,
+      totalProcessed: store.processedCount,
+    },
+    uptime: Date.now() - startedAt,
+  };
+
+  // Config check
+  if (!config || !tg) {
+    health.telegram.error = "not configured";
+    return health;
+  }
+
+  // Telegram connectivity check
+  const me = await tg.getMe();
+  if (me.ok) {
+    health.telegram.reachable = true;
+    health.telegram.botUsername = me.username;
+    health.ok = true;
+  } else {
+    health.telegram.error = me.error;
+  }
+
+  return health;
+}
+
+// ─── Startup diagnostics ────────────────────────────────────────────────────
+
+/**
+ * Log startup diagnostic summary.
+ */
+export function logStartupDiagnostics(
+  config: ResolvedConfig,
+  log: Logger,
+): void {
+  const maskedToken = config.botToken.slice(0, 6) + "…" + config.botToken.slice(-4);
+  const maskedChatId = config.chatId.slice(0, 3) + "…" + config.chatId.slice(-2);
+  log.info(
+    `[diagnostics] Config OK → chatId=${maskedChatId}, ` +
+      `token=${maskedToken}, staleMins=${config.staleMins}, ` +
+      `verbose=${config.verbose}`,
+  );
+}
+
+/**
+ * Run async startup checks (non-blocking).
+ * Verifies Telegram API connectivity and logs the result.
+ */
+export async function runStartupChecks(
+  tg: TelegramApi,
+  log: Logger,
+): Promise<void> {
+  const me = await tg.getMe();
+  if (me.ok) {
+    log.info(`[diagnostics] Telegram connected → @${me.username}`);
+  } else {
+    log.warn(
+      `[diagnostics] Telegram unreachable: ${me.error}. ` +
+        "Plugin will still attempt to send messages.",
+    );
+  }
+}

package/lib/message-formatter.ts

@@ -0,0 +1,152 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// telegram-approval-buttons · lib/message-formatter.ts
+// HTML message formatting for Telegram (approval requests & resolutions)
+// ─────────────────────────────────────────────────────────────────────────────
+
+import type { ApprovalAction, ApprovalInfo } from "../types.js";
+
+// ─── HTML escaping ──────────────────────────────────────────────────────────
+
+/** Escape text for Telegram HTML parse mode. */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+// ─── Approval request format ────────────────────────────────────────────────
+
+/**
+ * Format an approval request as a rich HTML message for Telegram.
+ */
+export function formatApprovalRequest(info: ApprovalInfo): string {
+  const e = escapeHtml;
+  return [
+    `🔐 <b>Exec Approval Request</b>`,
+    ``,
+    `🤖 Agent: <b>${e(info.agent)}</b>`,
+    `🖥️ Host: <b>${e(info.host)}</b>`,
+    `📁 CWD: <code>${e(info.cwd)}</code>`,
+    ``,
+    `<pre>${e(info.command)}</pre>`,
+    ``,
+    `🛡️ Security: ${e(info.security)}`,
+    `❓ Ask: ${e(info.ask)}`,
+    `⏱️ Expires: ${e(info.expires)}`,
+    `🆔 <code>${e(info.id)}</code>`,
+  ].join("\n");
+}
+
+// ─── Resolved approval format ───────────────────────────────────────────────
+
+const ACTION_ICONS: Record<ApprovalAction, string> = {
+  "allow-once": "✅",
+  "allow-always": "🔏",
+  deny: "❌",
+};
+
+const ACTION_LABELS: Record<ApprovalAction, string> = {
+  "allow-once": "Allowed (once)",
+  "allow-always": "Always allowed",
+  deny: "Denied",
+};
+
+/**
+ * Format a resolved approval (post-decision) as an HTML message.
+ * Buttons are removed and the header shows the resolution.
+ */
+export function formatApprovalResolved(
+  info: ApprovalInfo,
+  action: ApprovalAction,
+): string {
+  const e = escapeHtml;
+  const icon = ACTION_ICONS[action] ?? "✅";
+  const label = ACTION_LABELS[action] ?? action;
+
+  return [
+    `${icon} <b>Exec ${label}</b>`,
+    ``,
+    `🤖 Agent: <b>${e(info.agent)}</b>`,
+    `🖥️ Host: <b>${e(info.host)}</b>`,
+    `📁 CWD: <code>${e(info.cwd)}</code>`,
+    ``,
+    `<pre>${e(info.command)}</pre>`,
+    ``,
+    `🆔 <code>${e(info.id)}</code>`,
+  ].join("\n");
+}
+
+// ─── Inline keyboard ────────────────────────────────────────────────────────
+
+/**
+ * Build the inline keyboard markup for an approval request.
+ *
+ * Each button uses `/approve <id> <action>` as callback_data.
+ * OpenClaw's Telegram integration converts unknown callback_data
+ * into synthetic text messages, so these are processed as commands
+ * automatically — no webhook needed.
+ */
+export function buildApprovalKeyboard(approvalId: string): object {
+  return {
+    inline_keyboard: [
+      [
+        { text: "✅ Allow Once", callback_data: `/approve ${approvalId} allow-once` },
+        { text: "🔏 Always", callback_data: `/approve ${approvalId} allow-always` },
+      ],
+      [{ text: "❌ Deny", callback_data: `/approve ${approvalId} deny` }],
+    ],
+  };
+}
+
+// ─── Stale approval format ──────────────────────────────────────────────────
+
+/**
+ * Format a stale/expired approval message.
+ */
+export function formatApprovalExpired(info: ApprovalInfo): string {
+  const e = escapeHtml;
+  return [
+    `⏰ <b>Exec Approval Expired</b>`,
+    ``,
+    `🤖 Agent: <b>${e(info.agent)}</b>`,
+    `🖥️ Host: <b>${e(info.host)}</b>`,
+    ``,
+    `<pre>${e(info.command)}</pre>`,
+    ``,
+    `🆔 <code>${e(info.id)}</code>`,
+  ].join("\n");
+}
+
+// ─── Health / diagnostics format ────────────────────────────────────────────
+
+/**
+ * Format a health check result for display in Telegram.
+ */
+export function formatHealthCheck(health: {
+  ok: boolean;
+  config: { chatId: boolean; botToken: boolean };
+  telegram: { reachable: boolean; botUsername?: string; error?: string };
+  store: { pending: number; totalProcessed: number };
+  uptime: number;
+}): string {
+  const uptimeMin = Math.floor(health.uptime / 60_000);
+  const lines = [
+    `${health.ok ? "🟢" : "🔴"} Approval Buttons Status`,
+    ``,
+    `Config: chatId=${health.config.chatId ? "✓" : "✗"} · token=${health.config.botToken ? "✓" : "✗"}`,
+  ];
+
+  if (health.telegram.reachable) {
+    lines.push(`Telegram: ✓ connected (@${health.telegram.botUsername ?? "?"})`);
+  } else {
+    lines.push(`Telegram: ✗ ${health.telegram.error ?? "unreachable"}`);
+  }
+
+  lines.push(
+    `Pending: ${health.store.pending} · Processed: ${health.store.totalProcessed}`,
+    `Uptime: ${uptimeMin}m`,
+  );
+
+  return lines.join("\n");
+}

package/lib/telegram-api.ts

@@ -0,0 +1,165 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// telegram-approval-buttons · lib/telegram-api.ts
+// Isolated Telegram Bot API wrapper — only depends on fetch (Node built-in)
+// ─────────────────────────────────────────────────────────────────────────────
+
+import type { Logger } from "../types.js";
+
+const API_BASE = "https://api.telegram.org/bot";
+const REQUEST_TIMEOUT_MS = 10_000;
+
+// ─── Internal helpers ───────────────────────────────────────────────────────
+
+interface TgResponse<T = unknown> {
+  ok: boolean;
+  result?: T;
+  description?: string;
+  error_code?: number;
+}
+
+async function tgFetch<T = unknown>(
+  token: string,
+  method: string,
+  body: Record<string, unknown>,
+  log?: Logger,
+): Promise<TgResponse<T>> {
+  const url = `${API_BASE}${token}/${method}`;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timer);
+
+    const data = (await res.json()) as TgResponse<T>;
+    if (!data.ok && log) {
+      log.warn(
+        `[telegram-api] ${method} failed: ${data.error_code} ${data.description}`,
+      );
+    }
+    return data;
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log?.error(`[telegram-api] ${method} network error: ${msg}`);
+    return { ok: false, description: msg };
+  }
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Telegram Bot API client.
+ * Instantiate with a bot token; all methods are self-contained.
+ */
+export class TelegramApi {
+  constructor(
+    private readonly token: string,
+    private readonly log?: Logger,
+  ) {}
+
+  // ── Connectivity ────────────────────────────────────────────────────────
+
+  /**
+   * Call getMe to verify the bot token and get bot info.
+   * Useful for diagnostics.
+   */
+  async getMe(): Promise<{ ok: true; username: string } | { ok: false; error: string }> {
+    const res = await tgFetch<{ username: string }>(
+      this.token,
+      "getMe",
+      {},
+      this.log,
+    );
+    if (res.ok && res.result?.username) {
+      return { ok: true, username: res.result.username };
+    }
+    return { ok: false, error: res.description ?? "unknown error" };
+  }
+
+  // ── Messaging ───────────────────────────────────────────────────────────
+
+  /**
+   * Send an HTML-formatted message, optionally with inline keyboard.
+   * Returns the message_id on success, null on failure.
+   */
+  async sendMessage(
+    chatId: string,
+    text: string,
+    replyMarkup?: object,
+  ): Promise<number | null> {
+    const body: Record<string, unknown> = {
+      chat_id: chatId,
+      text,
+      parse_mode: "HTML",
+    };
+    if (replyMarkup) body.reply_markup = replyMarkup;
+
+    const res = await tgFetch<{ message_id: number }>(
+      this.token,
+      "sendMessage",
+      body,
+      this.log,
+    );
+    return res.ok ? (res.result?.message_id ?? null) : null;
+  }
+
+  /**
+   * Edit an existing message's text and remove inline keyboard.
+   * Returns true on success.
+   */
+  async editMessageText(
+    chatId: string,
+    messageId: number,
+    text: string,
+    replyMarkup?: object,
+  ): Promise<boolean> {
+    const body: Record<string, unknown> = {
+      chat_id: chatId,
+      message_id: messageId,
+      text,
+      parse_mode: "HTML",
+    };
+    // If replyMarkup is explicitly provided, include it; otherwise omit
+    // (omitting reply_markup removes all buttons)
+    if (replyMarkup) body.reply_markup = replyMarkup;
+
+    const res = await tgFetch(this.token, "editMessageText", body, this.log);
+    return res.ok;
+  }
+
+  /**
+   * Answer a callback query (acknowledges button press in Telegram UI).
+   * Optional text shows as a toast notification to the user.
+   */
+  async answerCallbackQuery(
+    callbackQueryId: string,
+    text?: string,
+  ): Promise<boolean> {
+    const body: Record<string, unknown> = {
+      callback_query_id: callbackQueryId,
+    };
+    if (text) body.text = text;
+
+    const res = await tgFetch(this.token, "answerCallbackQuery", body, this.log);
+    return res.ok;
+  }
+
+  /**
+   * Delete a message from a chat.
+   */
+  async deleteMessage(chatId: string, messageId: number): Promise<boolean> {
+    const res = await tgFetch(
+      this.token,
+      "deleteMessage",
+      { chat_id: chatId, message_id: messageId },
+      this.log,
+    );
+    return res.ok;
+  }
+}

package/openclaw.plugin.json

@@ -0,0 +1,52 @@
+{
+  "id": "telegram-approval-buttons",
+  "name": "Telegram Approval Buttons",
+  "description": "Adds inline keyboard buttons to exec approval messages in Telegram. Tap to approve/deny without typing commands.",
+  "version": "4.0.1",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "chatId": {
+        "type": "string",
+        "description": "Telegram chat ID where approval buttons are sent. Falls back to channels.telegram.allowFrom[0]."
+      },
+      "botToken": {
+        "type": "string",
+        "description": "Telegram bot token. Falls back to channels.telegram.token or TELEGRAM_BOT_TOKEN env."
+      },
+      "staleMins": {
+        "type": "number",
+        "description": "Minutes before a pending approval is considered stale and cleaned up.",
+        "default": 10
+      },
+      "verbose": {
+        "type": "boolean",
+        "description": "Enable verbose diagnostic logging.",
+        "default": false
+      }
+    }
+  },
+  "uiHints": {
+    "chatId": {
+      "label": "Telegram Chat ID",
+      "placeholder": "123456789",
+      "help": "Auto-detected from channels.telegram.allowFrom if not set."
+    },
+    "botToken": {
+      "label": "Bot Token",
+      "sensitive": true,
+      "placeholder": "Auto-detected from channels.telegram.token",
+      "help": "Only needed if different from the main Telegram channel token."
+    },
+    "staleMins": {
+      "label": "Stale Timeout (min)",
+      "placeholder": "10",
+      "advanced": true
+    },
+    "verbose": {
+      "label": "Verbose Logging",
+      "advanced": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "telegram-approval-buttons",
+  "version": "4.0.1",
+  "description": "Inline keyboard buttons for exec approval messages in Telegram — tap to approve/deny without typing commands",
+  "type": "module",
+  "main": "index.ts",
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "telegram",
+    "approval",
+    "exec",
+    "inline-keyboard",
+    "buttons"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "author": "Jair Franco (https://github.com/JairFC)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JairFC/openclaw-telegram-approval-buttons"
+  },
+  "files": [
+    "index.ts",
+    "types.ts",
+    "lib/",
+    "openclaw.plugin.json",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/types.ts

@@ -0,0 +1,98 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// telegram-approval-buttons · types.ts
+// Shared TypeScript interfaces for the plugin
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parsed representation of an OpenClaw exec approval request.
+ */
+export interface ApprovalInfo {
+  /** UUID of the approval request */
+  id: string;
+  /** Shell command requiring approval */
+  command: string;
+  /** Working directory where the command would execute */
+  cwd: string;
+  /** Host machine name */
+  host: string;
+  /** Agent that requested the command */
+  agent: string;
+  /** Security policy that triggered the approval */
+  security: string;
+  /** Ask mode (e.g., "on-miss", "always") */
+  ask: string;
+  /** Time until approval expires (e.g., "120s") */
+  expires: string;
+}
+
+/**
+ * A tracked approval that was sent with inline buttons.
+ */
+export interface SentApproval {
+  /** Telegram message_id of our formatted message */
+  messageId: number;
+  /** Parsed approval details */
+  info: ApprovalInfo;
+  /** Unix timestamp (ms) when the message was sent */
+  sentAt: number;
+}
+
+/**
+ * Resolution of an approval (allow-once, allow-always, deny).
+ */
+export type ApprovalAction = "allow-once" | "allow-always" | "deny";
+
+/**
+ * Result of detecting an approval resolution in a message.
+ */
+export interface ApprovalResolution {
+  /** Approval UUID */
+  id: string;
+  /** Action that was taken */
+  action: ApprovalAction;
+}
+
+/**
+ * Plugin configuration (from openclaw.json → plugins.entries.<id>.config).
+ */
+export interface PluginConfig {
+  /** Telegram chat ID to send approval buttons to */
+  chatId?: string;
+  /** Telegram bot token (optional — falls back to channels.telegram.token) */
+  botToken?: string;
+  /** Stale approval timeout in minutes (default: 10) */
+  staleMins?: number;
+  /** Enable verbose diagnostic logging (default: false) */
+  verbose?: boolean;
+}
+
+/**
+ * Resolved (validated) configuration with all defaults applied.
+ */
+export interface ResolvedConfig {
+  chatId: string;
+  botToken: string;
+  staleMins: number;
+  verbose: boolean;
+}
+
+/**
+ * Diagnostic health check result.
+ */
+export interface HealthCheck {
+  ok: boolean;
+  config: { chatId: boolean; botToken: boolean };
+  telegram: { reachable: boolean; botUsername?: string; error?: string };
+  store: { pending: number; totalProcessed: number };
+  uptime: number;
+}
+
+/**
+ * Minimal logger interface matching OpenClaw's plugin logger.
+ */
+export interface Logger {
+  debug?: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+}