@tormentalabs/opencode-telegram-plugin 0.2.0 → 0.3.0

package/README.md

@@ -7,9 +7,12 @@ Telegram bot plugin for [OpenCode](https://opencode.ai) — remote control and i
 - **Remote Control** — attach to your active TUI session, see streaming responses in real-time, send prompts, and approve/deny permission requests via inline buttons
 - **Independent Sessions** — create standalone sessions for async work from your phone
 - **Live Streaming** — AI responses stream into Telegram with throttled in-place message edits
-- **Permission Handling** — tool permission prompts appear as inline keyboards (Approve / Deny)
+- **Permission Handling** — tool permission prompts with inline keyboards (Approve / Always / Deny), plus text replies (YES/NO/ALWAYS)
+- **Shell Access** — run shell commands directly from Telegram (`!git status` or `/shell`)
 - **Tool Status** — see which tools are executing in real-time
 - **Multi-session** — switch between sessions, list active sessions, create new ones
+- **Session Control** — undo/redo file changes, compact/summarize, share sessions, view diffs
+- **Bot Menu** — all commands auto-registered in Telegram's command menu, including auto-discovered OpenCode commands
 - **Config Management** — built-in `/telegram` slash command for setup without leaving OpenCode
 
 ## Quick Start
@@ -142,19 +145,30 @@ Once the bot is running, these commands are available in Telegram:
 | Command | Description |
 |---------|-------------|
 | `/start` | Initialize bot, auto-attach to active session |
-| `/attach` | Attach to an active TUI session (shows picker) |
+| `/help` | Show help |
+| `/attach [id]` | Attach to a session (shows picker if no ID) |
 | `/detach` | Detach from the current session |
-| `/new` | Create an independent session |
+| `/new [title]` | Create an independent session |
 | `/sessions` | List all sessions |
-| `/switch` | Switch to a different session |
-| `/model` | List available models with favorites marked |
+| `/switch [id]` | Switch to a different session |
+| `!command` | Run a shell command (e.g. `!git status`) |
+| `/shell <cmd>` | Run a shell command |
+| `/diff` | Show changed files in current session |
+| `/messages [n]` | Show last N messages (default: 5, max: 20) |
+| `/pending` | List pending permission requests |
+| `/model` | List available models with favorites |
 | `/model <provider/model-id>` | Set a specific model for this chat |
 | `/model reset` | Reset to the default model |
-| `/effort` | Show current effort level |
-| `/effort <low\|medium\|high>` | Set reasoning effort level |
+| `/effort [low\|medium\|high]` | Set/show reasoning effort level |
 | `/status` | Show current connection status |
-| `/abort` | Abort the current session |
-| `/help` | Show help |
+| `/abort` | Abort the current operation |
+| `/oc_undo` | Undo last message and file changes |
+| `/oc_redo` | Redo undone changes |
+| `/oc_compact` | Summarize/compact the session |
+| `/oc_share` | Share the session (get URL) |
+| `/commands` | List all available OpenCode commands |
+
+Text replies to permission messages: `YES`, `NO`, or `ALWAYS` (reply to a specific permission message, or send bare to apply to the most recent).
 
 ## How It Works
 
@@ -184,10 +198,15 @@ When OpenCode requests tool permissions, an inline keyboard appears in Telegram:
 ```
 🔐 Permission requested: bash
 Command: git status
-[✅ Approve] [❌ Deny]
+[✅ Approve] [✅ Always] [❌ Deny]
 ```
 
-Tapping a button responds to the permission request in OpenCode.
+You can respond by:
+- Tapping an inline button
+- Replying with `YES`, `ALWAYS`, or `NO` to the permission message
+- Sending bare `YES`/`ALWAYS`/`NO` to apply to the most recent pending request
+
+Use `/pending` to see all pending permission requests.
 
 ## Project Structure
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tormentalabs/opencode-telegram-plugin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Telegram bot plugin for OpenCode — remote control and independent sessions from your phone",
   "type": "module",
   "main": "./src/index.ts",

package/src/bot.ts

@@ -13,6 +13,17 @@ import {
   effortCommand,
   statusCommand,
   abortCommand,
+  shellCommand,
+  diffCommand,
+  pendingCommand,
+  messagesCommand,
+  ocUndoCommand,
+  ocRedoCommand,
+  ocCompactCommand,
+  ocShareCommand,
+  commandsCommand,
+  ocGenericCommand,
+  discoverCommands,
   setClient as setCommandsClient,
 } from "./handlers/commands.js";
 import {
@@ -91,6 +102,26 @@ export function createBot(opts: CreateBotOptions): Bot {
   bot.command("effort", effortCommand);
   bot.command("status", statusCommand);
   bot.command("abort", abortCommand);
+  bot.command("shell", shellCommand);
+  bot.command("diff", diffCommand);
+  bot.command("pending", pendingCommand);
+  bot.command("messages", messagesCommand);
+  bot.command("oc_undo", ocUndoCommand);
+  bot.command("oc_redo", ocRedoCommand);
+  bot.command("oc_compact", ocCompactCommand);
+  bot.command("oc_share", ocShareCommand);
+  bot.command("commands", commandsCommand);
+
+  // ── Dynamic /oc_* catch-all for custom OpenCode commands ──────────────
+  bot.hears(/^\/oc_(\w+)(?:\s+(.*))?$/, async (ctx) => {
+    const match = ctx.match;
+    const commandName = match[1]!;
+    // Skip commands we handle explicitly
+    if (["undo", "redo", "compact", "share"].includes(commandName)) return;
+    // Inject the arguments as ctx.match for ocGenericCommand
+    (ctx as any).match = match[2] ?? "";
+    await ocGenericCommand(commandName, ctx);
+  });
 
   // ── Callback queries ──────────────────────────────────────────────────
   bot.on("callback_query:data", handleCallback);
@@ -123,6 +154,63 @@ export function injectClient(client: unknown): void {
   setCallbacksClient(client);
 }
 
+// ---------------------------------------------------------------------------
+// Bot menu registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register all bot commands in Telegram's command menu.
+ * Also auto-discovers custom OpenCode commands and registers them as /oc_*.
+ */
+export async function registerBotMenu(bot: Bot): Promise<void> {
+  const builtinCommands = [
+    { command: "start", description: "Start the bot" },
+    { command: "help", description: "Show help" },
+    { command: "attach", description: "Attach to a session" },
+    { command: "detach", description: "Detach from session" },
+    { command: "new", description: "Create new session" },
+    { command: "sessions", description: "List sessions" },
+    { command: "switch", description: "Switch session" },
+    { command: "model", description: "List/set model" },
+    { command: "effort", description: "Set reasoning effort" },
+    { command: "status", description: "Show bot status" },
+    { command: "abort", description: "Abort current operation" },
+    { command: "shell", description: "Run shell command" },
+    { command: "diff", description: "Show changed files" },
+    { command: "pending", description: "List pending permissions" },
+    { command: "messages", description: "Show recent messages" },
+    { command: "oc_undo", description: "Undo last changes" },
+    { command: "oc_redo", description: "Redo undone changes" },
+    { command: "oc_compact", description: "Compact/summarize session" },
+    { command: "oc_share", description: "Share session URL" },
+    { command: "commands", description: "List OpenCode commands" },
+  ];
+
+  // Auto-discover custom OpenCode commands
+  try {
+    const ocCommands = await discoverCommands();
+    const builtinNames = new Set(["undo", "redo", "compact", "share"]);
+    for (const cmd of ocCommands) {
+      if (builtinNames.has(cmd.name)) continue; // already registered explicitly
+      builtinCommands.push({
+        command: `oc_${cmd.name}`,
+        description: cmd.description?.slice(0, 256) ?? `OpenCode: ${cmd.name}`,
+      });
+    }
+  } catch {
+    // Non-fatal — proceed with builtin commands only
+  }
+
+  // Telegram limits to 100 commands
+  const commands = builtinCommands.slice(0, 100);
+
+  try {
+    await bot.api.setMyCommands(commands);
+  } catch {
+    // Non-fatal — menu registration failure shouldn't block startup
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------

package/src/handlers/callbacks.ts

@@ -9,9 +9,9 @@ import { escapeHtml } from "../utils/format.js";
 // ---------------------------------------------------------------------------
 
 interface OpenCodeClient {
-  postSessionByIdPermissionsByPermissionId(params: {
-    path: { id: string; permissionId: string };
-    body: unknown;
+  postSessionIdPermissionsPermissionId(params: {
+    path: { id: string; permissionID: string };
+    body: { response: "once" | "always" | "reject" };
   }): Promise<unknown>;
 }
 
@@ -91,7 +91,7 @@ export async function handleCallback(ctx: Context): Promise<void> {
   try {
     switch (entry.action) {
       // ----------------------------------------------------------------
-      // Permission approval
+      // Permission approval (once)
       // ----------------------------------------------------------------
       case "perm_approve": {
         const { sessionId, permissionId } = entry.data;
@@ -102,9 +102,9 @@ export async function handleCallback(ctx: Context): Promise<void> {
           return;
         }
 
-        await getClient().postSessionByIdPermissionsByPermissionId({
-          path: { id: sessionId, permissionId },
-          body: {},
+        await getClient().postSessionIdPermissionsPermissionId({
+          path: { id: sessionId, permissionID: permissionId },
+          body: { response: "once" },
         });
 
         getChatState(chatId).pendingPermissions.delete(permissionId);
@@ -117,7 +117,33 @@ export async function handleCallback(ctx: Context): Promise<void> {
       }
 
       // ----------------------------------------------------------------
-      // Permission denial — notify SDK so the session doesn't hang
+      // Permission approval (always) — permanently whitelist
+      // ----------------------------------------------------------------
+      case "perm_always": {
+        const { sessionId, permissionId } = entry.data;
+        if (!sessionId || !permissionId) {
+          await safeSend(() =>
+            ctx.answerCallbackQuery({ text: "Invalid callback data." }),
+          );
+          return;
+        }
+
+        await getClient().postSessionIdPermissionsPermissionId({
+          path: { id: sessionId, permissionID: permissionId },
+          body: { response: "always" },
+        });
+
+        getChatState(chatId).pendingPermissions.delete(permissionId);
+        await safeSend(() => ctx.answerCallbackQuery({ text: "✅ Always Allowed" }));
+        await safeEditText(
+          ctx,
+          `${escapeHtml(originalMessageText(ctx))}\n\n✅ <b>Always Allowed</b>`,
+        );
+        break;
+      }
+
+      // ----------------------------------------------------------------
+      // Permission denial
       // ----------------------------------------------------------------
       case "perm_deny": {
         const { sessionId, permissionId } = entry.data;
@@ -128,13 +154,10 @@ export async function handleCallback(ctx: Context): Promise<void> {
           return;
         }
 
-        // Best-effort: call the permission endpoint to unblock the session.
-        // If the SDK has no explicit deny mechanism, this call may fail —
-        // the session will eventually time out on its own.
         try {
-          await getClient().postSessionByIdPermissionsByPermissionId({
-            path: { id: sessionId, permissionId },
-            body: { deny: true },
+          await getClient().postSessionIdPermissionsPermissionId({
+            path: { id: sessionId, permissionID: permissionId },
+            body: { response: "reject" },
           });
         } catch {
           // SDK may not support explicit deny — fall through silently

package/src/handlers/commands.ts

@@ -22,11 +22,55 @@ interface SessionSummary {
   createdAt: string;
 }
 
+interface FileDiff {
+  file: string;
+  additions: number;
+  deletions: number;
+  status?: "added" | "deleted" | "modified";
+}
+
+interface MessageInfo {
+  id: string;
+  role: string;
+  createdAt?: string;
+}
+
+interface MessagePart {
+  type: string;
+  text?: string;
+  [key: string]: unknown;
+}
+
+interface SessionData {
+  id: string;
+  title?: string;
+  share?: { url: string };
+}
+
+interface AssistantMessage {
+  parts?: MessagePart[];
+}
+
+interface OpenCodeCommand {
+  name: string;
+  description?: string;
+  source?: string;
+}
+
 interface OpenCodeClient {
   session: {
     list(): Promise<{ data: SessionSummary[] }>;
     create(params: { body: { title: string } }): Promise<{ data: { id: string } }>;
     abort(params: { path: { id: string } }): Promise<boolean>;
+    shell(params: { path: { id: string }; body: { agent: string; command: string } }): Promise<{ data: AssistantMessage }>;
+    diff(params: { path: { id: string }; query?: { messageID?: string } }): Promise<{ data: FileDiff[] }>;
+    share(params: { path: { id: string } }): Promise<{ data: SessionData }>;
+    unshare(params: { path: { id: string } }): Promise<{ data: SessionData }>;
+    revert(params: { path: { id: string }; body?: { messageID: string } }): Promise<{ data: SessionData }>;
+    unrevert(params: { path: { id: string } }): Promise<{ data: SessionData }>;
+    summarize(params: { path: { id: string }; body?: { providerID: string; modelID: string } }): Promise<{ data: boolean }>;
+    messages(params: { path: { id: string }; query?: { limit?: number } }): Promise<{ data: Array<{ info: MessageInfo; parts: MessagePart[] }> }>;
+    command(params: { path: { id: string }; body: { command: string; arguments: string } }): Promise<{ data: unknown }>;
   };
   config: {
     providers(): Promise<{
@@ -39,6 +83,9 @@ interface OpenCodeClient {
       };
     }>;
   };
+  command: {
+    list(): Promise<{ data: OpenCodeCommand[] }>;
+  };
 }
 
 let _client: OpenCodeClient | null = null;
@@ -68,7 +115,11 @@ const HELP_TEXT = `
 
 <b>While in a Session</b>
 Just send a message to prompt OpenCode
+<code>!command</code>     — Run a shell command (e.g. <code>!git status</code>)
+/shell &lt;cmd&gt; — Run a shell command
 /abort       — Abort the current running operation
+/diff        — Show changed files in current session
+/messages    — Show last 5 messages from session
 
 <b>Model &amp; Config</b>
 /model              — List available models
@@ -77,6 +128,17 @@ Just send a message to prompt OpenCode
 /effort [low|medium|high] — Set reasoning effort (default: high)
 /status      — Show current bot status
 /help        — Show this help message
+
+<b>Permissions</b>
+Reply <code>YES</code>, <code>NO</code>, or <code>ALWAYS</code> to a permission message
+/pending     — List pending permission requests
+
+<b>OpenCode Commands</b>
+/oc_undo     — Undo last message + file changes
+/oc_redo     — Redo undone changes
+/oc_compact  — Summarize/compact the session
+/oc_share    — Share the session (get URL)
+/commands    — List all available OpenCode commands
 `.trim();
 
 /**
@@ -560,3 +622,412 @@ export async function abortCommand(ctx: Context): Promise<void> {
     );
   }
 }
+
+// ---------------------------------------------------------------------------
+// Shell command — /shell <cmd> or !<cmd>
+// ---------------------------------------------------------------------------
+
+export async function shellCommand(ctx: Context): Promise<void> {
+  const chatId = ctx.chat?.id;
+  if (!chatId) return;
+
+  const command = typeof ctx.match === "string" ? ctx.match.trim() : "";
+  if (!command) {
+    await safeSend(() =>
+      ctx.reply("Usage: <code>/shell command</code>\nExample: <code>/shell git status</code>\n\nOr use the <code>!</code> prefix: <code>!git status</code>", { parse_mode: "HTML" }),
+    );
+    return;
+  }
+
+  await executeShell(ctx, chatId, command);
+}
+
+/**
+ * Execute a shell command in the current session and send the result.
+ * Shared between /shell and !<cmd>.
+ */
+export async function executeShell(ctx: Context, chatId: number, command: string): Promise<void> {
+  const sessionId = getActiveSessionId(chatId);
+  if (!sessionId) {
+    await safeSend(() =>
+      ctx.reply("No active session. Use /attach or /new first."),
+    );
+    return;
+  }
+
+  try {
+    await ctx.api.sendChatAction(chatId, "typing");
+  } catch { /* non-fatal */ }
+
+  try {
+    const { data } = await getClient().session.shell({
+      path: { id: sessionId },
+      body: { agent: "", command },
+    });
+
+    const parts = data?.parts ?? [];
+    const textParts = parts
+      .filter((p) => p.type === "text" && p.text)
+      .map((p) => p.text!);
+
+    const output = textParts.join("\n").trim();
+
+    if (!output) {
+      await safeSend(() =>
+        ctx.reply(`<code>$ ${escapeHtml(command)}</code>\n<i>(no output)</i>`, { parse_mode: "HTML" }),
+      );
+      return;
+    }
+
+    // Chunk output if needed (4000 char limit for safety)
+    const header = `<code>$ ${escapeHtml(command)}</code>\n`;
+    const MAX_LEN = 4000 - header.length;
+
+    if (output.length <= MAX_LEN) {
+      await safeSend(() =>
+        ctx.reply(`${header}<pre>${escapeHtml(output)}</pre>`, { parse_mode: "HTML" }),
+      );
+    } else {
+      // Send header first, then chunks
+      await safeSend(() =>
+        ctx.reply(header, { parse_mode: "HTML" }),
+      );
+
+      let remaining = output;
+      while (remaining.length > 0) {
+        const chunk = remaining.slice(0, 4000);
+        remaining = remaining.slice(4000);
+        await safeSend(() =>
+          ctx.reply(`<pre>${escapeHtml(chunk)}</pre>`, { parse_mode: "HTML" }),
+        );
+      }
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await safeSend(() =>
+      ctx.reply(`❌ Shell error: ${escapeHtml(msg)}`, { parse_mode: "HTML" }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// /diff — Show changed files
+// ---------------------------------------------------------------------------
+
+export async function diffCommand(ctx: Context): Promise<void> {
+  const chatId = ctx.chat?.id;
+  if (!chatId) return;
+
+  const sessionId = getActiveSessionId(chatId);
+  if (!sessionId) {
+    await safeSend(() => ctx.reply("No active session. Use /attach or /new first."));
+    return;
+  }
+
+  try {
+    const { data: diffs } = await getClient().session.diff({
+      path: { id: sessionId },
+    });
+
+    if (!diffs || diffs.length === 0) {
+      await safeSend(() => ctx.reply("No file changes in this session."));
+      return;
+    }
+
+    const statusIcon: Record<string, string> = {
+      added: "🟢",
+      deleted: "🔴",
+      modified: "🟡",
+    };
+
+    const lines = diffs.map((d) => {
+      const icon = statusIcon[d.status ?? "modified"] ?? "🟡";
+      const stats = `<code>+${d.additions} -${d.deletions}</code>`;
+      return `${icon} ${stats} ${escapeHtml(d.file)}`;
+    });
+
+    const totalAdd = diffs.reduce((s, d) => s + d.additions, 0);
+    const totalDel = diffs.reduce((s, d) => s + d.deletions, 0);
+    const summary = `\n<b>${diffs.length} file${diffs.length === 1 ? "" : "s"}</b> changed: <code>+${totalAdd} -${totalDel}</code>`;
+
+    await safeSend(() =>
+      ctx.reply(`<b>Changed Files:</b>\n\n${lines.join("\n")}${summary}`, { parse_mode: "HTML" }),
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await safeSend(() =>
+      ctx.reply(`❌ Failed to get diff: ${escapeHtml(msg)}`, { parse_mode: "HTML" }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// /pending — List pending permission requests
+// ---------------------------------------------------------------------------
+
+export async function pendingCommand(ctx: Context): Promise<void> {
+  const chatId = ctx.chat?.id;
+  if (!chatId) return;
+
+  const state = getChatState(chatId);
+  const pending = Array.from(state.pendingPermissions.values());
+
+  if (pending.length === 0) {
+    await safeSend(() => ctx.reply("No pending permission requests."));
+    return;
+  }
+
+  const lines = pending.map((p, i) => {
+    const age = Math.round((Date.now() - p.timestamp) / 1000);
+    const ageStr = age < 60 ? `${age}s ago` : `${Math.round(age / 60)}m ago`;
+    return `${i + 1}. <b>${escapeHtml(p.tool)}</b> (${ageStr})\n   ${escapeHtml(p.description.slice(0, 100))}`;
+  });
+
+  await safeSend(() =>
+    ctx.reply(
+      `<b>Pending Permissions (${pending.length}):</b>\n\n${lines.join("\n\n")}\n\nReply <code>YES</code>, <code>NO</code>, or <code>ALWAYS</code> to the most recent, or tap the inline buttons.`,
+      { parse_mode: "HTML" },
+    ),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// /messages — Show last N messages from the session
+// ---------------------------------------------------------------------------
+
+export async function messagesCommand(ctx: Context): Promise<void> {
+  const chatId = ctx.chat?.id;
+  if (!chatId) return;
+
+  const sessionId = getActiveSessionId(chatId);
+  if (!sessionId) {
+    await safeSend(() => ctx.reply("No active session. Use /attach or /new first."));
+    return;
+  }
+
+  const limitArg = typeof ctx.match === "string" ? parseInt(ctx.match.trim(), 10) : NaN;
+  const limit = Number.isFinite(limitArg) && limitArg > 0 ? Math.min(limitArg, 20) : 5;
+
+  try {
+    const { data: messages } = await getClient().session.messages({
+      path: { id: sessionId },
+      query: { limit },
+    });
+
+    if (!messages || messages.length === 0) {
+      await safeSend(() => ctx.reply("No messages in this session."));
+      return;
+    }
+
+    const lines = messages.map((m) => {
+      const role = m.info.role === "user" ? "👤" : "🤖";
+      const textParts = m.parts
+        .filter((p) => p.type === "text" && p.text)
+        .map((p) => p.text!);
+      const preview = textParts.join(" ").slice(0, 200);
+      return `${role} <b>${escapeHtml(m.info.role)}</b>\n${escapeHtml(preview)}${preview.length >= 200 ? "…" : ""}`;
+    });
+
+    await safeSend(() =>
+      ctx.reply(
+        `<b>Last ${messages.length} message${messages.length === 1 ? "" : "s"}:</b>\n\n${lines.join("\n\n")}`,
+        { parse_mode: "HTML" },
+      ),
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await safeSend(() =>
+      ctx.reply(`❌ Failed to fetch messages: ${escapeHtml(msg)}`, { parse_mode: "HTML" }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// /oc_undo — Revert last message + file changes
+// ---------------------------------------------------------------------------
+
+export async function ocUndoCommand(ctx: Context): Promise<void> {
+  const chatId = ctx.chat?.id;
+  if (!chatId) return;
+
+  const sessionId = getActiveSessionId(chatId);
+  if (!sessionId) {
+    await safeSend(() => ctx.reply("No active session."));
+    return;
+  }
+
+  try {
+    await getClient().session.revert({
+      path: { id: sessionId },
+    });
+    await safeSend(() => ctx.reply("↩️ Undone. File changes reverted."));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await safeSend(() =>
+      ctx.reply(`❌ Undo failed: ${escapeHtml(msg)}`, { parse_mode: "HTML" }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// /oc_redo — Restore undone changes
+// ---------------------------------------------------------------------------
+
+export async function ocRedoCommand(ctx: Context): Promise<void> {
+  const chatId = ctx.chat?.id;
+  if (!chatId) return;
+
+  const sessionId = getActiveSessionId(chatId);
+  if (!sessionId) {
+    await safeSend(() => ctx.reply("No active session."));
+    return;
+  }
+
+  try {
+    await getClient().session.unrevert({
+      path: { id: sessionId },
+    });
+    await safeSend(() => ctx.reply("↪️ Redone. Changes restored."));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await safeSend(() =>
+      ctx.reply(`❌ Redo failed: ${escapeHtml(msg)}`, { parse_mode: "HTML" }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// /oc_compact — Summarize/compact session
+// ---------------------------------------------------------------------------
+
+export async function ocCompactCommand(ctx: Context): Promise<void> {
+  const chatId = ctx.chat?.id;
+  if (!chatId) return;
+
+  const sessionId = getActiveSessionId(chatId);
+  if (!sessionId) {
+    await safeSend(() => ctx.reply("No active session."));
+    return;
+  }
+
+  try {
+    await getClient().session.summarize({
+      path: { id: sessionId },
+    });
+    await safeSend(() => ctx.reply("📦 Session compacted."));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await safeSend(() =>
+      ctx.reply(`❌ Compact failed: ${escapeHtml(msg)}`, { parse_mode: "HTML" }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// /oc_share — Share session and get URL
+// ---------------------------------------------------------------------------
+
+export async function ocShareCommand(ctx: Context): Promise<void> {
+  const chatId = ctx.chat?.id;
+  if (!chatId) return;
+
+  const sessionId = getActiveSessionId(chatId);
+  if (!sessionId) {
+    await safeSend(() => ctx.reply("No active session."));
+    return;
+  }
+
+  try {
+    const { data } = await getClient().session.share({
+      path: { id: sessionId },
+    });
+
+    const url = data?.share?.url;
+    if (url) {
+      await safeSend(() =>
+        ctx.reply(`🔗 Session shared:\n${url}`),
+      );
+    } else {
+      await safeSend(() => ctx.reply("✅ Session shared (no URL returned)."));
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await safeSend(() =>
+      ctx.reply(`❌ Share failed: ${escapeHtml(msg)}`, { parse_mode: "HTML" }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// /commands — List all available OpenCode commands
+// ---------------------------------------------------------------------------
+
+export async function commandsCommand(ctx: Context): Promise<void> {
+  try {
+    const { data: commands } = await getClient().command.list();
+
+    if (!commands || commands.length === 0) {
+      await safeSend(() => ctx.reply("No OpenCode commands available."));
+      return;
+    }
+
+    const lines = commands.map((cmd) => {
+      const desc = cmd.description ? ` — ${escapeHtml(cmd.description)}` : "";
+      const source = cmd.source ? ` <i>[${escapeHtml(cmd.source)}]</i>` : "";
+      return `• <code>/oc_${escapeHtml(cmd.name)}</code>${desc}${source}`;
+    });
+
+    await safeSend(() =>
+      ctx.reply(`<b>OpenCode Commands:</b>\n\n${lines.join("\n")}`, { parse_mode: "HTML" }),
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await safeSend(() =>
+      ctx.reply(`❌ Failed to list commands: ${escapeHtml(msg)}`, { parse_mode: "HTML" }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Generic /oc_* handler — dispatch to session.command()
+// ---------------------------------------------------------------------------
+
+export async function ocGenericCommand(commandName: string, ctx: Context): Promise<void> {
+  const chatId = ctx.chat?.id;
+  if (!chatId) return;
+
+  const sessionId = getActiveSessionId(chatId);
+  if (!sessionId) {
+    await safeSend(() => ctx.reply("No active session."));
+    return;
+  }
+
+  const args = typeof ctx.match === "string" ? ctx.match.trim() : "";
+
+  try {
+    await getClient().session.command({
+      path: { id: sessionId },
+      body: { command: commandName, arguments: args || "" },
+    });
+    await safeSend(() =>
+      ctx.reply(`✅ Command <code>/${escapeHtml(commandName)}</code> sent.`, { parse_mode: "HTML" }),
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await safeSend(() =>
+      ctx.reply(`❌ Command failed: ${escapeHtml(msg)}`, { parse_mode: "HTML" }),
+    );
+  }
+}
+
+/**
+ * Discover OpenCode commands and return them for bot menu registration.
+ */
+export async function discoverCommands(): Promise<OpenCodeCommand[]> {
+  try {
+    const { data } = await getClient().command.list();
+    return data ?? [];
+  } catch {
+    return [];
+  }
+}

package/src/handlers/messages.ts

@@ -3,6 +3,7 @@ import { getActiveSessionId, attachSession } from "../state/mode.js";
 import { getChatState } from "../state/store.js";
 import { safeSend } from "../utils/safeSend.js";
 import { escapeHtml } from "../utils/format.js";
+import { executeShell } from "./commands.js";
 
 // ---------------------------------------------------------------------------
 // Client interface — only the methods used in this file
@@ -26,6 +27,10 @@ interface OpenCodeClient {
       };
     }): Promise<{ data: { info: unknown; parts: unknown[] } }>;
   };
+  postSessionIdPermissionsPermissionId(params: {
+    path: { id: string; permissionID: string };
+    body: { response: "once" | "always" | "reject" };
+  }): Promise<unknown>;
 }
 
 let _client: OpenCodeClient | null = null;
@@ -63,6 +68,85 @@ async function tryAutoAttach(chatId: number): Promise<string | null> {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Permission text-reply helper
+// ---------------------------------------------------------------------------
+
+type PermissionReply = "once" | "always" | "reject";
+
+function parsePermissionReply(text: string): PermissionReply | null {
+  const lower = text.trim().toLowerCase();
+  if (lower === "yes" || lower === "y" || lower === "approve") return "once";
+  if (lower === "always" || lower === "yes always") return "always";
+  if (lower === "no" || lower === "n" || lower === "deny" || lower === "reject") return "reject";
+  return null;
+}
+
+const REPLY_LABELS: Record<PermissionReply, string> = {
+  once: "✅ Approved",
+  always: "✅ Always Allowed",
+  reject: "❌ Denied",
+};
+
+/**
+ * Try to resolve a text-based permission reply.
+ * Returns true if the message was handled as a permission reply.
+ */
+async function tryPermissionReply(ctx: Context, chatId: number, text: string): Promise<boolean> {
+  const reply = parsePermissionReply(text);
+  if (!reply) return false;
+
+  const state = getChatState(chatId);
+  if (state.pendingPermissions.size === 0) return false;
+
+  // If replying to a specific permission message, match by telegramMessageId
+  const replyToId = ctx.message?.reply_to_message?.message_id;
+  let targetPerm: { permissionId: string; sessionId: string } | null = null;
+
+  if (replyToId) {
+    for (const perm of state.pendingPermissions.values()) {
+      if (perm.telegramMessageId === replyToId) {
+        targetPerm = { permissionId: perm.permissionId, sessionId: perm.sessionId };
+        break;
+      }
+    }
+  }
+
+  // Fallback: apply to most recent pending permission
+  if (!targetPerm) {
+    let latest: { permissionId: string; sessionId: string; timestamp: number } | null = null;
+    for (const perm of state.pendingPermissions.values()) {
+      if (!latest || perm.timestamp > latest.timestamp) {
+        latest = { permissionId: perm.permissionId, sessionId: perm.sessionId, timestamp: perm.timestamp };
+      }
+    }
+    if (latest) {
+      targetPerm = { permissionId: latest.permissionId, sessionId: latest.sessionId };
+    }
+  }
+
+  if (!targetPerm) return false;
+
+  try {
+    await getClient().postSessionIdPermissionsPermissionId({
+      path: { id: targetPerm.sessionId, permissionID: targetPerm.permissionId },
+      body: { response: reply },
+    });
+
+    state.pendingPermissions.delete(targetPerm.permissionId);
+    await safeSend(() =>
+      ctx.reply(REPLY_LABELS[reply], { parse_mode: "HTML" }),
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await safeSend(() =>
+      ctx.reply(`❌ Permission reply failed: ${escapeHtml(msg)}`, { parse_mode: "HTML" }),
+    );
+  }
+
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // Handler
 // ---------------------------------------------------------------------------
@@ -71,11 +155,10 @@ async function tryAutoAttach(chatId: number): Promise<string | null> {
  * Handles every plain-text message sent to the bot.
  *
  * Flow:
- *  1. Resolve (or auto-attach to) an active session.
- *  2. Fire the prompt against the OpenCode SDK — without awaiting the full
- *     response, because the streaming reply arrives through event hooks
- *     (message.updated) and is handled by a separate event listener.
- *  3. Propagate any errors back to the user.
+ *  1. Check for !<cmd> shell prefix.
+ *  2. Check for permission text replies (YES/NO/ALWAYS).
+ *  3. Resolve (or auto-attach to) an active session.
+ *  4. Fire the prompt against the OpenCode SDK.
  */
 export async function handleTextMessage(ctx: Context): Promise<void> {
   const chatId = ctx.chat?.id;
@@ -89,7 +172,24 @@ export async function handleTextMessage(ctx: Context): Promise<void> {
   if (text.startsWith("/")) return;
 
   // ------------------------------------------------------------------
-  // 1. Resolve active session
+  // 1. Shell prefix: !<command>
+  // ------------------------------------------------------------------
+  if (text.startsWith("!")) {
+    const command = text.slice(1).trim();
+    if (command) {
+      await executeShell(ctx, chatId, command);
+      return;
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // 2. Text-based permission replies (YES/NO/ALWAYS)
+  // ------------------------------------------------------------------
+  const handled = await tryPermissionReply(ctx, chatId, text);
+  if (handled) return;
+
+  // ------------------------------------------------------------------
+  // 3. Resolve active session
   // ------------------------------------------------------------------
   let sessionId = getActiveSessionId(chatId);
 
@@ -111,7 +211,7 @@ export async function handleTextMessage(ctx: Context): Promise<void> {
   }
 
   // ------------------------------------------------------------------
-  // 2. Show typing indicator (best-effort)
+  // 4. Show typing indicator (best-effort)
   // ------------------------------------------------------------------
   try {
     await ctx.api.sendChatAction(chatId, "typing");
@@ -120,7 +220,7 @@ export async function handleTextMessage(ctx: Context): Promise<void> {
   }
 
   // ------------------------------------------------------------------
-  // 3. Fire the prompt — response streams via event hooks, not here
+  // 5. Fire the prompt — response streams via event hooks, not here
   // ------------------------------------------------------------------
   const capturedSessionId = sessionId; // capture before any async gap
 

package/src/hooks/permission.ts

@@ -41,6 +41,10 @@ export function handlePermissionAsked(
       permissionId,
       sessionId: sessionID,
     });
+    const alwaysKey = registerCallback("perm_always", {
+      permissionId,
+      sessionId: sessionID,
+    });
     const denyKey = registerCallback("perm_deny", {
       permissionId,
       sessionId: sessionID,
@@ -48,12 +52,14 @@ export function handlePermissionAsked(
 
     const keyboard = new InlineKeyboard()
       .text("✅ Approve", approveKey)
+      .text("✅ Always", alwaysKey)
       .text("❌ Deny", denyKey);
 
     const messageText =
       `🔐 <b>Permission requested</b>\n\n` +
       `<b>Tool:</b> <code>${escapeHtml(tool)}</code>\n` +
-      escapeHtml(description);
+      escapeHtml(description) +
+      `\n\n<i>Reply YES, ALWAYS, or NO</i>`;
 
     void (async () => {
       const result = await safeSend(() =>

package/src/index.ts

@@ -1,6 +1,6 @@
 import type { Plugin } from "@opencode-ai/plugin";
 
-import { createBot, injectClient } from "./bot.js";
+import { createBot, injectClient, registerBotMenu } from "./bot.js";
 import { initMapping } from "./state/mapping.js";
 import {
   resolveConfig,
@@ -269,6 +269,9 @@ export const TelegramPlugin: Plugin = async (ctx) => {
           message: "Telegram bot started (token from " + config.tokenSource + ").",
         },
       });
+
+      // Register bot commands in Telegram's menu (non-blocking)
+      void registerBotMenu(bot).catch(() => undefined);
     },
     allowed_updates: [
       "message",