@openacp/cli 0.4.8 → 0.4.9

package/dist/{chunk-BBPWAWE3.js → chunk-45DFYWJT.js}

@@ -2623,6 +2623,15 @@ function buildDeepLink(chatId, messageId) {
 // src/adapters/telegram/commands.ts
 import { InlineKeyboard } from "grammy";
 var log8 = createChildLogger({ module: "telegram-commands" });
+var pendingNewSessions = /* @__PURE__ */ new Map();
+var PENDING_TIMEOUT_MS = 5 * 60 * 1e3;
+function cleanupPending(userId) {
+  const pending = pendingNewSessions.get(userId);
+  if (pending) {
+    clearTimeout(pending.timer);
+    pendingNewSessions.delete(userId);
+  }
+}
 function setupCommands(bot, core, chatId, assistant) {
   bot.command("new", (ctx) => handleNew(ctx, core, chatId, assistant));
   bot.command("newchat", (ctx) => handleNewChat(ctx, core, chatId));
@@ -2637,9 +2646,10 @@ function setupCommands(bot, core, chatId, assistant) {
   bot.command("restart", (ctx) => handleRestart(ctx, core));
   bot.command("update", (ctx) => handleUpdate(ctx, core));
   bot.command("integrate", (ctx) => handleIntegrate(ctx, core));
+  bot.command("clear", (ctx) => handleClear(ctx, assistant));
 }
 function buildMenuKeyboard() {
-  return new InlineKeyboard().text("\u{1F195} New Session", "m:new").text("\u{1F4AC} New Chat", "m:newchat").row().text("\u26D4 Cancel", "m:cancel").text("\u{1F4CA} Status", "m:status").row().text("\u{1F4CB} Sessions", "m:topics").text("\u{1F916} Agents", "m:agents").row().text("\u{1F517} Integrate", "m:integrate").text("\u2753 Help", "m:help").row().text("\u{1F504} Restart", "m:restart").text("\u2B06\uFE0F Update", "m:update");
+  return new InlineKeyboard().text("\u{1F195} New Session", "m:new").text("\u{1F4CB} Sessions", "m:topics").row().text("\u{1F4CA} Status", "m:status").text("\u{1F916} Agents", "m:agents").row().text("\u{1F517} Integrate", "m:integrate").text("\u2753 Help", "m:help").row().text("\u{1F504} Restart", "m:restart").text("\u2B06\uFE0F Update", "m:update");
 }
 function setupMenuCallbacks(bot, core, chatId, systemTopicIds) {
   bot.callbackQuery(/^m:/, async (ctx) => {
@@ -2648,16 +2658,83 @@ function setupMenuCallbacks(bot, core, chatId, systemTopicIds) {
       await ctx.answerCallbackQuery();
     } catch {
     }
+    if (data.startsWith("m:new:agent:")) {
+      const agentName = data.replace("m:new:agent:", "");
+      const userId = ctx.from?.id;
+      if (userId) await startWorkspaceStep(ctx, core, chatId, userId, agentName);
+      return;
+    }
+    if (data === "m:new:ws:default") {
+      const userId = ctx.from?.id;
+      if (!userId) return;
+      const pending = pendingNewSessions.get(userId);
+      if (!pending?.agentName) return;
+      const workspace = core.configManager.get().workspace.baseDir;
+      await startConfirmStep(ctx, chatId, userId, pending.agentName, workspace);
+      return;
+    }
+    if (data === "m:new:ws:custom") {
+      const userId = ctx.from?.id;
+      if (!userId) return;
+      const pending = pendingNewSessions.get(userId);
+      if (!pending?.agentName) return;
+      try {
+        await ctx.api.editMessageText(
+          chatId,
+          pending.messageId,
+          `\u270F\uFE0F <b>Enter your project path:</b>
+
+Full path like <code>~/code/my-project</code>
+Or just the folder name like <code>my-project</code> (will use ${core.configManager.get().workspace.baseDir}/)`,
+          { parse_mode: "HTML" }
+        );
+      } catch {
+        await ctx.reply(
+          `\u270F\uFE0F <b>Enter your project path:</b>`,
+          { parse_mode: "HTML" }
+        );
+      }
+      clearTimeout(pending.timer);
+      pending.step = "workspace_input";
+      pending.timer = setTimeout(() => pendingNewSessions.delete(userId), PENDING_TIMEOUT_MS);
+      return;
+    }
+    if (data === "m:new:confirm") {
+      const userId = ctx.from?.id;
+      if (!userId) return;
+      const pending = pendingNewSessions.get(userId);
+      if (!pending?.agentName || !pending?.workspace) return;
+      cleanupPending(userId);
+      const confirmMsgId = pending.messageId;
+      try {
+        await ctx.api.editMessageText(chatId, confirmMsgId, `\u23F3 Creating session...`, { parse_mode: "HTML" });
+      } catch {
+      }
+      const resultThreadId = await createSessionDirect(ctx, core, chatId, pending.agentName, pending.workspace);
+      try {
+        if (resultThreadId) {
+          const link = buildDeepLink(chatId, resultThreadId);
+          await ctx.api.editMessageText(chatId, confirmMsgId, `\u2705 Session created \u2192 <a href="${link}">Open topic</a>`, { parse_mode: "HTML" });
+        } else {
+          await ctx.api.editMessageText(chatId, confirmMsgId, `\u274C Session creation failed.`, { parse_mode: "HTML" });
+        }
+      } catch {
+      }
+      return;
+    }
+    if (data === "m:new:cancel") {
+      const userId = ctx.from?.id;
+      if (userId) cleanupPending(userId);
+      try {
+        await ctx.editMessageText("\u274C Session creation cancelled.", { parse_mode: "HTML" });
+      } catch {
+      }
+      return;
+    }
     switch (data) {
       case "m:new":
         await handleNew(ctx, core, chatId);
         break;
-      case "m:newchat":
-        await handleNewChat(ctx, core, chatId);
-        break;
-      case "m:cancel":
-        await handleCancel(ctx, core);
-        break;
       case "m:status":
         await handleStatus(ctx, core);
         break;
@@ -2710,16 +2787,111 @@ async function handleNew(ctx, core, chatId, assistant) {
   const args = matchStr.split(" ").filter(Boolean);
   const agentName = args[0];
   const workspace = args[1];
+  if (agentName && workspace) {
+    await createSessionDirect(ctx, core, chatId, agentName, workspace);
+    return;
+  }
   const currentThreadId = ctx.message?.message_thread_id;
-  if (assistant && currentThreadId === assistant.topicId && (!agentName || !workspace)) {
+  if (assistant && currentThreadId === assistant.topicId) {
     const assistantSession = assistant.getSession();
     if (assistantSession) {
-      const prompt = agentName ? `User wants to create a new session with agent "${agentName}" but didn't specify a workspace. Ask them which workspace to use.` : `User wants to create a new session. Ask them which agent and workspace to use.`;
+      const prompt = agentName ? `User wants to create a new session with agent "${agentName}" but didn't specify a workspace. Ask them which project directory to use as workspace.` : `User wants to create a new session. Guide them through choosing an agent and workspace (project directory).`;
       await assistantSession.enqueuePrompt(prompt);
       return;
     }
   }
-  log8.info({ userId: ctx.from?.id, agentName }, "New session command");
+  const userId = ctx.from?.id;
+  if (!userId) return;
+  const agents = core.agentManager.getAvailableAgents();
+  const config = core.configManager.get();
+  if (agentName || agents.length === 1) {
+    const selectedAgent = agentName || config.defaultAgent;
+    await startWorkspaceStep(ctx, core, chatId, userId, selectedAgent);
+    return;
+  }
+  const keyboard = new InlineKeyboard();
+  for (const agent of agents) {
+    const label = agent.name === config.defaultAgent ? `${agent.name} (default)` : agent.name;
+    keyboard.text(label, `m:new:agent:${agent.name}`).row();
+  }
+  const msg = await ctx.reply(
+    `\u{1F916} <b>Choose an agent:</b>`,
+    { parse_mode: "HTML", reply_markup: keyboard }
+  );
+  cleanupPending(userId);
+  pendingNewSessions.set(userId, {
+    step: "agent",
+    messageId: msg.message_id,
+    threadId: currentThreadId,
+    timer: setTimeout(() => pendingNewSessions.delete(userId), PENDING_TIMEOUT_MS)
+  });
+}
+async function startWorkspaceStep(ctx, core, chatId, userId, agentName) {
+  const config = core.configManager.get();
+  const baseDir = config.workspace.baseDir;
+  const keyboard = new InlineKeyboard().text(`\u{1F4C1} Use ${baseDir}`, "m:new:ws:default").row().text("\u270F\uFE0F Enter project path", "m:new:ws:custom");
+  const text = `\u{1F4C1} <b>Where should ${escapeHtml(agentName)} work?</b>
+
+Enter the path to your project folder \u2014 the agent will read, write, and run code there.
+
+Or use the default directory below:`;
+  let msg;
+  try {
+    const pending = pendingNewSessions.get(userId);
+    if (pending?.messageId) {
+      await ctx.api.editMessageText(chatId, pending.messageId, text, {
+        parse_mode: "HTML",
+        reply_markup: keyboard
+      });
+      msg = { message_id: pending.messageId };
+    } else {
+      msg = await ctx.reply(text, { parse_mode: "HTML", reply_markup: keyboard });
+    }
+  } catch {
+    msg = await ctx.reply(text, { parse_mode: "HTML", reply_markup: keyboard });
+  }
+  cleanupPending(userId);
+  pendingNewSessions.set(userId, {
+    agentName,
+    step: "workspace",
+    messageId: msg.message_id,
+    threadId: ctx.message?.message_thread_id ?? ctx.callbackQuery?.message?.message_thread_id,
+    timer: setTimeout(() => pendingNewSessions.delete(userId), PENDING_TIMEOUT_MS)
+  });
+}
+async function startConfirmStep(ctx, chatId, userId, agentName, workspace) {
+  const keyboard = new InlineKeyboard().text("\u2705 Create", "m:new:confirm").text("\u274C Cancel", "m:new:cancel");
+  const text = `\u2705 <b>Ready to create session?</b>
+
+<b>Agent:</b> ${escapeHtml(agentName)}
+<b>Project:</b> <code>${escapeHtml(workspace)}</code>`;
+  let msg;
+  try {
+    const pending = pendingNewSessions.get(userId);
+    if (pending?.messageId) {
+      await ctx.api.editMessageText(chatId, pending.messageId, text, {
+        parse_mode: "HTML",
+        reply_markup: keyboard
+      });
+      msg = { message_id: pending.messageId };
+    } else {
+      msg = await ctx.reply(text, { parse_mode: "HTML", reply_markup: keyboard });
+    }
+  } catch {
+    msg = await ctx.reply(text, { parse_mode: "HTML", reply_markup: keyboard });
+  }
+  cleanupPending(userId);
+  pendingNewSessions.set(userId, {
+    agentName,
+    workspace,
+    step: "confirm",
+    messageId: msg.message_id,
+    threadId: ctx.message?.message_thread_id ?? ctx.callbackQuery?.message?.message_thread_id,
+    timer: setTimeout(() => pendingNewSessions.delete(userId), PENDING_TIMEOUT_MS)
+  });
+}
+async function createSessionDirect(ctx, core, chatId, agentName, workspace) {
+  log8.info({ userId: ctx.from?.id, agentName, workspace }, "New session command (direct)");
   let threadId;
   try {
     const topicName = `\u{1F504} New Session`;
@@ -2728,15 +2900,9 @@ async function handleNew(ctx, core, chatId, assistant) {
       message_thread_id: threadId,
       parse_mode: "HTML"
     });
-    const session = await core.handleNewSession(
-      "telegram",
-      agentName,
-      workspace
-    );
+    const session = await core.handleNewSession("telegram", agentName, workspace);
     session.threadId = String(threadId);
-    await core.sessionManager.updateSessionPlatform(session.id, {
-      topicId: threadId
-    });
+    await core.sessionManager.updateSessionPlatform(session.id, { topicId: threadId });
     const finalName = `\u{1F504} ${session.agentName} \u2014 New Session`;
     try {
       await ctx.api.editForumTopic(chatId, threadId, { name: finalName });
@@ -2744,9 +2910,11 @@ async function handleNew(ctx, core, chatId, assistant) {
     }
     await ctx.api.sendMessage(
       chatId,
-      `\u2705 Session started
+      `\u2705 <b>Session started</b>
 <b>Agent:</b> ${escapeHtml(session.agentName)}
-<b>Workspace:</b> <code>${escapeHtml(session.workingDirectory)}</code>`,
+<b>Workspace:</b> <code>${escapeHtml(session.workingDirectory)}</code>
+
+This is your coding session \u2014 chat here to work with the agent.`,
       {
         message_thread_id: threadId,
         parse_mode: "HTML",
@@ -2754,6 +2922,7 @@ async function handleNew(ctx, core, chatId, assistant) {
       }
     );
     session.warmup().catch((err) => log8.error({ err }, "Warm-up error"));
+    return threadId ?? null;
   } catch (err) {
     log8.error({ err }, "Session creation failed");
     if (threadId) {
@@ -2764,6 +2933,7 @@ async function handleNew(ctx, core, chatId, assistant) {
     }
     const message = err instanceof Error ? err.message : typeof err === "object" ? JSON.stringify(err) : String(err);
     await ctx.reply(`\u274C ${escapeHtml(message)}`, { parse_mode: "HTML" });
+    return null;
   }
 }
 async function handleNewChat(ctx, core, chatId) {
@@ -3116,22 +3286,54 @@ No agents configured.`;
 }
 async function handleHelp(ctx) {
   await ctx.reply(
-    `<b>OpenACP Commands:</b>
+    `\u{1F4D6} <b>OpenACP Help</b>
+
+\u{1F680} <b>Getting Started</b>
+Tap \u{1F195} New Session to start coding with AI.
+Each session gets its own topic \u2014 chat there to work with the agent.
 
+\u{1F4A1} <b>Common Tasks</b>
 /new [agent] [workspace] \u2014 Create new session
-/newchat \u2014 New chat, same agent &amp; workspace
-/cancel \u2014 Cancel current session
-/status \u2014 Show session/system status
+/cancel \u2014 Cancel session (in session topic)
+/status \u2014 Show session or system status
+/sessions \u2014 List all sessions
 /agents \u2014 List available agents
-/menu \u2014 Show interactive menu
+
+\u2699\uFE0F <b>System</b>
 /restart \u2014 Restart OpenACP
-/update \u2014 Update to latest version and restart
-/help \u2014 Show this help
+/update \u2014 Update to latest version
+/integrate \u2014 Manage agent integrations
+/menu \u2014 Show action menu
+
+\u{1F512} <b>Session Options</b>
+/enable_dangerous \u2014 Auto-approve permissions
+/disable_dangerous \u2014 Restore permission prompts
+/handoff \u2014 Continue session in terminal
+/clear \u2014 Clear assistant history
 
-Or just chat in the \u{1F916} Assistant topic for help!`,
+\u{1F4AC} Need help? Just ask me in this topic!`,
     { parse_mode: "HTML" }
   );
 }
+async function handleClear(ctx, assistant) {
+  if (!assistant) {
+    await ctx.reply("\u26A0\uFE0F Assistant is not available.", { parse_mode: "HTML" });
+    return;
+  }
+  const threadId = ctx.message?.message_thread_id;
+  if (threadId !== assistant.topicId) {
+    await ctx.reply("\u2139\uFE0F /clear only works in the Assistant topic.", { parse_mode: "HTML" });
+    return;
+  }
+  await ctx.reply("\u{1F504} Clearing assistant history...", { parse_mode: "HTML" });
+  try {
+    await assistant.respawn();
+    await ctx.reply("\u2705 Assistant history cleared.", { parse_mode: "HTML" });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    await ctx.reply(`\u274C Failed to clear: <code>${message}</code>`, { parse_mode: "HTML" });
+  }
+}
 function buildDangerousModeKeyboard(sessionId, enabled) {
   return new InlineKeyboard().text(
     enabled ? "\u{1F510} Disable Dangerous Mode" : "\u2620\uFE0F Enable Dangerous Mode",
@@ -3471,6 +3673,53 @@ ${resultText}`,
     }
   });
 }
+async function handlePendingWorkspaceInput(ctx, core, chatId, assistantTopicId) {
+  const userId = ctx.from?.id;
+  if (!userId) return false;
+  const pending = pendingNewSessions.get(userId);
+  if (!pending || !ctx.message?.text) return false;
+  if (pending.step !== "workspace_input" && pending.step !== "workspace") return false;
+  const threadId = ctx.message.message_thread_id;
+  if (threadId && threadId !== assistantTopicId) return false;
+  let workspace = ctx.message.text.trim();
+  if (!workspace || !pending.agentName) {
+    await ctx.reply("\u26A0\uFE0F Please enter a valid directory path.", { parse_mode: "HTML" });
+    return true;
+  }
+  if (!workspace.startsWith("/") && !workspace.startsWith("~")) {
+    const baseDir = core.configManager.get().workspace.baseDir;
+    workspace = `${baseDir.replace(/\/$/, "")}/${workspace}`;
+  }
+  await startConfirmStep(ctx, chatId, userId, pending.agentName, workspace);
+  return true;
+}
+async function startInteractiveNewSession(ctx, core, chatId, agentName) {
+  const userId = ctx.from?.id;
+  if (!userId) return;
+  const agents = core.agentManager.getAvailableAgents();
+  const config = core.configManager.get();
+  if (agentName || agents.length === 1) {
+    const selectedAgent = agentName || config.defaultAgent;
+    await startWorkspaceStep(ctx, core, chatId, userId, selectedAgent);
+    return;
+  }
+  const keyboard = new InlineKeyboard();
+  for (const agent of agents) {
+    const label = agent.name === config.defaultAgent ? `${agent.name} (default)` : agent.name;
+    keyboard.text(label, `m:new:agent:${agent.name}`).row();
+  }
+  const msg = await ctx.reply(
+    `\u{1F916} <b>Choose an agent:</b>`,
+    { parse_mode: "HTML", reply_markup: keyboard }
+  );
+  cleanupPending(userId);
+  pendingNewSessions.set(userId, {
+    step: "agent",
+    messageId: msg.message_id,
+    threadId: ctx.callbackQuery?.message?.message_thread_id,
+    timer: setTimeout(() => pendingNewSessions.delete(userId), PENDING_TIMEOUT_MS)
+  });
+}
 var STATIC_COMMANDS = [
   { command: "new", description: "Create new session" },
   { command: "newchat", description: "New chat, same agent & workspace" },
@@ -3484,6 +3733,7 @@ var STATIC_COMMANDS = [
   { command: "disable_dangerous", description: "Restore normal permission prompts (session only)" },
   { command: "integrate", description: "Manage agent integrations" },
   { command: "handoff", description: "Continue this session in your terminal" },
+  { command: "clear", description: "Clear assistant history" },
   { command: "restart", description: "Restart OpenACP" },
   { command: "update", description: "Update to latest version and restart" }
 ];
@@ -3568,6 +3818,370 @@ ${escapeHtml(request.description)}`,
   }
 };
 
+// src/product-guide.ts
+var PRODUCT_GUIDE = `
+# OpenACP \u2014 Product Guide
+
+OpenACP lets you chat with AI coding agents (like Claude Code) through Telegram.
+You type messages in Telegram, the agent reads/writes/runs code in your project folder, and results stream back in real time.
+
+---
+
+## Quick Start
+
+1. Start OpenACP: \`openacp\` (or \`openacp start\` for background daemon)
+2. Open your Telegram group \u2014 you'll see the Assistant topic
+3. Tap \u{1F195} New Session or type /new
+4. Pick an agent and a project folder
+5. Chat in the session topic \u2014 the agent works on your code
+
+---
+
+## Core Concepts
+
+### Sessions
+A session = one conversation with one AI agent working in one project folder.
+Each session gets its own Telegram topic. Chat there to give instructions to the agent.
+
+### Agents
+An agent is an AI coding tool (e.g., Claude Code). You can configure multiple agents.
+The default agent is used when you don't specify one.
+
+### Project Folder (Workspace)
+The directory where the agent reads, writes, and runs code.
+When creating a session, you choose which folder the agent works in.
+You can type a full path like \`~/code/my-project\` or just a name like \`my-project\` (it becomes \`<base-dir>/my-project\`).
+
+### System Topics
+- **Assistant** \u2014 Always-on helper that can answer questions, create sessions, check status, troubleshoot
+- **Notifications** \u2014 System alerts (permission requests, session errors, completions)
+
+---
+
+## Creating Sessions
+
+### From menu
+Tap \u{1F195} New Session \u2192 choose agent (if multiple) \u2192 choose project folder \u2192 confirm
+
+### From command
+- \`/new\` \u2014 Interactive flow (asks agent + folder)
+- \`/new claude ~/code/my-project\` \u2014 Create directly with specific agent and folder
+
+### From Assistant topic
+Just ask: "Create a session for my-project with claude" \u2014 the assistant handles it
+
+### Quick new chat
+\`/newchat\` in a session topic \u2014 creates new session with same agent and folder as current one
+
+---
+
+## Working with Sessions
+
+### Chat
+Type messages in the session topic. The agent responds with code changes, explanations, tool outputs.
+
+### What you see while the agent works
+- **\u{1F4AD} Thinking indicator** \u2014 Shows when the agent is reasoning, with elapsed time
+- **Text responses** \u2014 Streamed in real time, updated every few seconds
+- **Tool calls** \u2014 When the agent runs commands or edits files, you see tool name, input, status, and output
+- **\u{1F4CB} Plan card** \u2014 Visual task progress with completed/in-progress/pending items and progress bar
+- **"View File" / "View Diff" buttons** \u2014 Opens in browser with Monaco editor (requires tunnel)
+
+### Session lifecycle
+1. **Creating** \u2014 Topic created, agent spawning
+2. **Warming up** \u2014 Agent primes its cache (happens automatically, invisible to you)
+3. **Active** \u2014 Ready for your messages
+4. **Auto-naming** \u2014 After your first message, the session gets a descriptive name (agent summarizes in ~5 words). The topic title updates automatically.
+5. **Finished/Error** \u2014 Session completed or hit an error
+
+### Agent skills
+Some agents provide slash commands (e.g., /compact, /review). Available skills are pinned in the session topic.
+
+### Permission requests
+When the agent wants to run a command, it asks for permission.
+You see buttons: \u2705 Allow, \u274C Reject (and sometimes "Always Allow").
+A notification also appears in the Notifications topic with a link to the request.
+
+### Dangerous mode
+Auto-approves ALL permission requests \u2014 the agent runs any command without asking.
+- Enable: \`/enable_dangerous\` or tap the \u2620\uFE0F button in the session
+- Disable: \`/disable_dangerous\` or tap the \u{1F510} button
+- \u26A0\uFE0F Use with caution \u2014 the agent can execute anything
+
+### Session timeout
+Idle sessions are automatically cancelled after a configurable timeout (default: 60 minutes).
+Configure via \`security.sessionTimeoutMinutes\` in config.
+
+---
+
+## Session Transfer (Handoff)
+
+### Telegram \u2192 Terminal
+1. Type \`/handoff\` in a session topic
+2. You get a command like \`claude --resume <SESSION_ID>\`
+3. Copy and run it in your terminal \u2014 the session continues there with full conversation history
+
+### Terminal \u2192 Telegram
+1. First time: run \`openacp integrate claude\` to install the handoff skill (one-time setup)
+2. In Claude Code, use the /openacp:handoff slash command
+3. The session appears as a new topic in Telegram and you can continue chatting there
+
+### How it works
+- The agent session ID is shared between platforms
+- Conversation history is preserved \u2014 pick up where you left off
+- The agent that supports resume (e.g., Claude with \`--resume\`) handles the actual transfer
+
+---
+
+## Managing Sessions
+
+### Status
+- \`/status\` \u2014 Shows active sessions count and details
+- Ask the Assistant: "What sessions are running?"
+
+### List all sessions
+- \`/sessions\` \u2014 Shows all sessions with status (active, finished, error)
+
+### Cancel
+- \`/cancel\` in a session topic \u2014 cancels that session
+- Ask the Assistant: "Cancel the stuck session"
+
+### Cleanup
+- From \`/sessions\` \u2192 tap cleanup buttons (finished, errors, all)
+- Ask the Assistant: "Clean up old sessions"
+
+---
+
+## Assistant Topic
+
+The Assistant is an always-on AI helper in its own topic. It can:
+- Answer questions about OpenACP
+- Create sessions for you
+- Check status and health
+- Cancel sessions
+- Clean up old sessions
+- Troubleshoot issues
+- Manage configuration
+
+Just chat naturally: "How do I create a session?", "What's the status?", "Something is stuck"
+
+### Clear history
+\`/clear\` in the Assistant topic \u2014 resets the conversation
+
+---
+
+## System Commands
+
+| Command | Where | What it does |
+|---------|-------|-------------|
+| \`/new [agent] [path]\` | Anywhere | Create new session |
+| \`/newchat\` | Session topic | New session, same agent + folder |
+| \`/cancel\` | Session topic | Cancel current session |
+| \`/status\` | Anywhere | Show status |
+| \`/sessions\` | Anywhere | List all sessions |
+| \`/agents\` | Anywhere | List available agents |
+| \`/enable_dangerous\` | Session topic | Auto-approve all permissions |
+| \`/disable_dangerous\` | Session topic | Restore permission prompts |
+| \`/handoff\` | Session topic | Transfer session to terminal |
+| \`/clear\` | Assistant topic | Clear assistant history |
+| \`/menu\` | Anywhere | Show action menu |
+| \`/help\` | Anywhere | Show help |
+| \`/restart\` | Anywhere | Restart OpenACP |
+| \`/update\` | Anywhere | Update to latest version |
+| \`/integrate\` | Anywhere | Manage agent integrations |
+
+---
+
+## Menu Buttons
+
+| Button | Action |
+|--------|--------|
+| \u{1F195} New Session | Create new session (interactive) |
+| \u{1F4CB} Sessions | List all sessions with cleanup options |
+| \u{1F4CA} Status | Show active/total session count |
+| \u{1F916} Agents | List available agents |
+| \u{1F517} Integrate | Manage agent integrations |
+| \u2753 Help | Show help text |
+| \u{1F504} Restart | Restart OpenACP |
+| \u2B06\uFE0F Update | Check and install updates |
+
+---
+
+## CLI Commands
+
+### Server
+- \`openacp\` \u2014 Start (uses configured mode: foreground or daemon)
+- \`openacp start\` \u2014 Start as background daemon
+- \`openacp stop\` \u2014 Stop daemon
+- \`openacp status\` \u2014 Show daemon status
+- \`openacp logs\` \u2014 Tail daemon logs
+- \`openacp --foreground\` \u2014 Force foreground mode (useful for debugging or containers)
+
+### Auto-start (run on boot)
+- macOS: installs a LaunchAgent in \`~/Library/LaunchAgents/\`
+- Linux: installs a systemd user service in \`~/.config/systemd/user/\`
+- Enabled automatically when you start the daemon. Remove with \`openacp stop\`.
+
+### Configuration
+- \`openacp config\` \u2014 Interactive config editor
+- \`openacp reset\` \u2014 Delete all data and start fresh
+
+### Plugins
+- \`openacp install <package>\` \u2014 Install adapter plugin (e.g., \`@openacp/adapter-discord\`)
+- \`openacp uninstall <package>\` \u2014 Remove adapter plugin
+- \`openacp plugins\` \u2014 List installed plugins
+
+### Integration
+- \`openacp integrate <agent>\` \u2014 Install agent integration (e.g., Claude handoff skill)
+- \`openacp integrate <agent> --uninstall\` \u2014 Remove integration
+
+### API (requires running daemon)
+\`openacp api <command>\` \u2014 Interact with running daemon:
+
+| Command | Description |
+|---------|-------------|
+| \`status\` | List active sessions |
+| \`session <id>\` | Session details |
+| \`new <agent> <path>\` | Create session |
+| \`send <id> "text"\` | Send prompt |
+| \`cancel <id>\` | Cancel session |
+| \`dangerous <id> on/off\` | Toggle dangerous mode |
+| \`topics [--status x,y]\` | List topics |
+| \`delete-topic <id> [--force]\` | Delete topic |
+| \`cleanup [--status x,y]\` | Cleanup old topics |
+| \`agents\` | List agents |
+| \`health\` | System health |
+| \`config\` | Show config |
+| \`config set <key> <value>\` | Update config |
+| \`adapters\` | List adapters |
+| \`tunnel\` | Tunnel status |
+| \`notify "message"\` | Send notification |
+| \`version\` | Daemon version |
+| \`restart\` | Restart daemon |
+
+---
+
+## File Viewer (Tunnel)
+
+When tunnel is enabled, file edits and diffs get "View" buttons that open in your browser:
+- **Monaco Editor** \u2014 Full VS Code editor with syntax highlighting
+- **Diff viewer** \u2014 Side-by-side or inline comparison
+- **Line highlighting** \u2014 Click lines to highlight
+- Dark/light theme toggle
+
+### Setup
+Enable in config: set \`tunnel.enabled\` to \`true\`.
+Providers: Cloudflare (default, free), ngrok, bore, Tailscale Funnel.
+
+---
+
+## Configuration
+
+Config file: \`~/.openacp/config.json\`
+
+### Telegram
+- **telegram.botToken** \u2014 Your Telegram bot token
+- **telegram.chatId** \u2014 Your Telegram supergroup ID
+
+### Agents
+- **agents.<name>.command** \u2014 Agent executable path (e.g., \`claude\`, \`codex\`)
+- **agents.<name>.args** \u2014 Arguments to pass to the agent command
+- **agents.<name>.env** \u2014 Custom environment variables for the agent subprocess
+- **defaultAgent** \u2014 Which agent to use by default
+
+### Workspace
+- **workspace.baseDir** \u2014 Base directory for project folders (default: \`~/openacp-workspace\`)
+
+### Security
+- **security.allowedUserIds** \u2014 Restrict who can use the bot (empty = everyone)
+- **security.maxConcurrentSessions** \u2014 Max parallel sessions (default: 5)
+- **security.sessionTimeoutMinutes** \u2014 Auto-cancel idle sessions (default: 60)
+
+### Tunnel / File Viewer
+- **tunnel.enabled** \u2014 Enable file viewer tunnel
+- **tunnel.provider** \u2014 Tunnel provider: cloudflare (default, free), ngrok, bore, tailscale
+- **tunnel.port** \u2014 Local port for tunnel server (default: 3100)
+- **tunnel.auth.enabled** \u2014 Enable authentication for tunnel URLs
+- **tunnel.auth.token** \u2014 Auth token for tunnel access
+- **tunnel.storeTtlMinutes** \u2014 How long viewer links stay cached (default: 60)
+
+### Logging
+- **logging.level** \u2014 Log level: silent, debug, info, warn, error, fatal (default: info)
+- **logging.logDir** \u2014 Log directory (default: \`~/.openacp/logs\`)
+- **logging.maxFileSize** \u2014 Max log file size before rotation
+- **logging.maxFiles** \u2014 Max number of rotated log files
+- **logging.sessionLogRetentionDays** \u2014 Auto-delete old session logs (default: 30)
+
+### Data Retention
+- **sessionStore.ttlDays** \u2014 How long session records persist (default: 30). Old records are cleaned up automatically.
+
+### Environment variables
+Override config with env vars:
+- \`OPENACP_TELEGRAM_BOT_TOKEN\`
+- \`OPENACP_TELEGRAM_CHAT_ID\`
+- \`OPENACP_DEFAULT_AGENT\`
+- \`OPENACP_RUN_MODE\` \u2014 foreground or daemon
+- \`OPENACP_API_PORT\` \u2014 API server port (default: 21420)
+- \`OPENACP_TUNNEL_ENABLED\`
+- \`OPENACP_TUNNEL_PORT\`
+- \`OPENACP_TUNNEL_PROVIDER\`
+- \`OPENACP_LOG_LEVEL\`
+- \`OPENACP_LOG_DIR\`
+- \`OPENACP_DEBUG\` \u2014 Sets log level to debug
+
+---
+
+## Troubleshooting
+
+### Session stuck / not responding
+- Check status: ask Assistant "Is anything stuck?"
+- Cancel and create new: \`/cancel\` then \`/new\`
+- Check system health: Assistant can run health check
+
+### Agent not found
+- Check available agents: \`/agents\`
+- Verify agent command is installed and in PATH
+- Check config: agent command + args must be correct
+
+### Permission request not showing
+- Check Notifications topic for the alert
+- Try \`/enable_dangerous\` to auto-approve (if you trust the agent)
+
+### Session disappeared after restart
+- Sessions persist across restarts
+- Send a message in the old topic \u2014 it auto-resumes
+- If topic was deleted, the session record may still exist in status
+
+### Bot not responding at all
+- Check daemon: \`openacp status\`
+- Check logs: \`openacp logs\`
+- Restart: \`openacp start\` or \`/restart\`
+
+### Messages going to wrong topic
+- Each session is bound to a specific Telegram topic
+- If you see messages appearing in the Assistant topic instead of the session topic, try creating a new session
+
+### Viewing logs
+- Session-specific logs: \`~/.openacp/logs/sessions/\`
+- System logs: \`openacp logs\` to tail live
+- Set \`OPENACP_DEBUG=true\` for verbose output
+
+---
+
+## Data & Storage
+
+All data is stored in \`~/.openacp/\`:
+- \`config.json\` \u2014 Configuration
+- \`sessions/\` \u2014 Session records and state
+- \`topics/\` \u2014 Topic-to-session mappings
+- \`logs/\` \u2014 System and session logs
+- \`plugins/\` \u2014 Installed adapter plugins
+- \`openacp.pid\` \u2014 Daemon PID file
+
+Session records auto-cleanup: 30 days (configurable via \`sessionStore.ttlDays\`).
+Session logs auto-cleanup: 30 days (configurable via \`logging.sessionLogRetentionDays\`).
+`;
+
 // src/adapters/telegram/assistant.ts
 var log10 = createChildLogger({ module: "telegram-assistant" });
 async function spawnAssistant(core, adapter, assistantTopicId) {
@@ -3604,52 +4218,100 @@ async function spawnAssistant(core, adapter, assistantTopicId) {
   });
   return { session, ready };
 }
+function buildWelcomeMessage(ctx) {
+  const { activeCount, errorCount, totalCount, agents, defaultAgent } = ctx;
+  const agentList = agents.map((a) => `${a}${a === defaultAgent ? " (default)" : ""}`).join(", ");
+  if (totalCount === 0) {
+    return `\u{1F44B} <b>OpenACP is ready!</b>
+
+No sessions yet. Tap \u{1F195} New Session to start, or ask me anything!`;
+  }
+  if (errorCount > 0) {
+    return `\u{1F44B} <b>OpenACP is ready!</b>
+
+\u{1F4CA} ${activeCount} active, ${errorCount} errors / ${totalCount} total
+\u26A0\uFE0F ${errorCount} session${errorCount > 1 ? "s have" : " has"} errors \u2014 ask me to check if you'd like.
+
+Agents: ${agentList}`;
+  }
+  return `\u{1F44B} <b>OpenACP is ready!</b>
+
+\u{1F4CA} ${activeCount} active / ${totalCount} total
+Agents: ${agentList}`;
+}
 function buildAssistantSystemPrompt(ctx) {
   const { config, activeSessionCount, totalSessionCount, topicSummary } = ctx;
   const agentNames = Object.keys(config.agents).join(", ");
   const topicBreakdown = topicSummary.map((s) => `${s.status}: ${s.count}`).join(", ") || "none";
-  return `You are the OpenACP Assistant. Help users manage their AI coding sessions and topics.
+  return `You are the OpenACP Assistant \u2014 a helpful guide for managing AI coding sessions.
 
 ## Current State
 - Active sessions: ${activeSessionCount} / ${totalSessionCount} total
 - Topics by status: ${topicBreakdown}
 - Available agents: ${agentNames}
 - Default agent: ${config.defaultAgent}
-- Workspace base: ${config.workspace.baseDir}
+- Workspace base directory: ${config.workspace.baseDir}
+
+## Action Playbook
+
+### Create Session
+- The workspace is the project directory where the agent will work (read, write, execute code). It is NOT the base directory \u2014 it should be a specific project folder like \`~/code/my-project\` or \`${config.workspace.baseDir}/my-app\`.
+- Ask which agent to use (if multiple are configured). Show available: ${agentNames}
+- Ask which project directory to use as workspace. Suggest \`${config.workspace.baseDir}\` as the base, but explain the user can provide any path.
+- Confirm before creating: show agent name + full workspace path.
+- Create via: \`openacp api new <agent> <workspace>\`
 
-## Session Management Commands
-These are Telegram bot commands (type directly in chat):
-- /new [agent] [workspace] \u2014 Create new session
-- /newchat \u2014 New chat with same agent & workspace
-- /cancel \u2014 Cancel current session
-- /status \u2014 Show status
-- /agents \u2014 List agents
-- /help \u2014 Show help
+### Check Status / List Sessions
+- Run \`openacp api status\` for active sessions overview
+- Run \`openacp api topics\` for full list with statuses
+- Format the output nicely for the user
 
-## Management Commands (via CLI)
-You have access to bash. Use these commands to manage OpenACP:
+### Cancel Session
+- Run \`openacp api status\` to see what's active
+- If 1 active session \u2192 ask user to confirm \u2192 \`openacp api cancel <id>\`
+- If multiple \u2192 list them, ask user which one to cancel
 
-### Session management
+### Troubleshoot (Session Stuck, Errors)
+- Run \`openacp api health\` + \`openacp api status\` to diagnose
+- Small issue (stuck session) \u2192 suggest cancel + create new
+- Big issue (system-level) \u2192 suggest restart, ask for confirmation first
+
+### Cleanup Old Sessions
+- Run \`openacp api topics --status finished,error\` to see what can be cleaned
+- Report the count, ask user to confirm
+- Execute: \`openacp api cleanup --status <statuses>\`
+
+### Configuration
+- View: \`openacp api config\`
+- Update: \`openacp api config set <key> <value>\`
+
+### Restart / Update
+- Always ask for confirmation \u2014 these are disruptive actions
+- Guide user: "Tap \u{1F504} Restart button or type /restart"
+
+### Toggle Dangerous Mode
+- Run \`openacp api dangerous <id> on|off\`
+- Explain: dangerous mode auto-approves all permission requests \u2014 the agent can run any command without asking
+
+## CLI Commands Reference
 \`\`\`bash
+# Session management
 openacp api status                       # List active sessions
 openacp api session <id>                 # Session detail
+openacp api new <agent> <workspace>      # Create new session
 openacp api send <id> "prompt text"      # Send prompt to session
 openacp api cancel <id>                  # Cancel session
 openacp api dangerous <id> on|off        # Toggle dangerous mode
-\`\`\`
 
-### Topic management
-\`\`\`bash
-openacp api topics                       # List topics
+# Topic management
+openacp api topics                       # List all topics
 openacp api topics --status finished,error
 openacp api delete-topic <id>            # Delete topic
 openacp api delete-topic <id> --force    # Force delete active
 openacp api cleanup                      # Cleanup finished topics
 openacp api cleanup --status finished,error
-\`\`\`
 
-### System
-\`\`\`bash
+# System
 openacp api health                       # System health
 openacp api config                       # Show config
 openacp api config set <key> <value>     # Update config
@@ -3661,13 +4323,18 @@ openacp api restart                      # Restart daemon
 \`\`\`
 
 ## Guidelines
-- When a user asks about sessions or topics, run \`openacp api topics\` or \`openacp api status\` to get current data.
-- When deleting: if the session is active/initializing, warn the user first. Only use --force if they confirm.
-- Use \`openacp api health\` to check system status.
-- Use \`openacp api config\` to check configuration, \`openacp api config set\` to update values.
-- Format responses nicely for Telegram (use bold, code blocks).
-- Be concise and helpful. Respond in the same language the user uses.
-- When creating sessions, guide through: agent selection \u2192 workspace \u2192 confirm.`;
+- NEVER show \`openacp api ...\` commands to users. These are internal tools for YOU to run silently. Users should only see natural language responses and results.
+- Run \`openacp api ...\` commands yourself for everything you can. Only guide users to Telegram buttons/menu when needed (e.g., "Tap \u{1F195} New Session" or "Go to the session topic to chat with the agent").
+- When creating sessions: guide user through agent + workspace choice conversationally, then run the command yourself.
+- Destructive actions (cancel active session, restart, cleanup) \u2192 always ask user to confirm first in natural language.
+- Small/obvious issues (clearly stuck session with no activity) \u2192 fix it and report back.
+- Respond in the same language the user uses.
+- Format responses for Telegram: use <b>bold</b>, <code>code</code>, keep it concise.
+- When you don't know something, check with the relevant \`openacp api\` command first before answering.
+- Talk to users like a helpful assistant, not a CLI manual. Example: "B\u1EA1n c\xF3 2 session \u0111ang ch\u1EA1y. Mu\u1ED1n xem chi ti\u1EBFt kh\xF4ng?" instead of listing commands.
+
+## Product Reference
+${PRODUCT_GUIDE}`;
 }
 async function handleAssistantMessage(session, text) {
   if (!session) return;
@@ -4109,27 +4776,38 @@ function setupActionCallbacks(bot, core, chatId, getAssistantSessionId) {
     removeAction(actionId);
     try {
       if (action.action === "new_session") {
-        await ctx.answerCallbackQuery({ text: "\u23F3 Creating session..." });
-        const { threadId, firstMsgId } = await executeNewSession(
-          bot,
-          core,
-          chatId,
-          action.agent,
-          action.workspace
-        );
-        const topicLink = `https://t.me/c/${String(chatId).replace("-100", "")}/${firstMsgId ?? threadId}`;
-        const originalText = ctx.callbackQuery.message?.text ?? "";
-        try {
-          await ctx.editMessageText(
-            originalText + `
+        if (action.agent && action.workspace) {
+          await ctx.answerCallbackQuery({ text: "\u23F3 Creating session..." });
+          const { threadId, firstMsgId } = await executeNewSession(
+            bot,
+            core,
+            chatId,
+            action.agent,
+            action.workspace
+          );
+          const topicLink = `https://t.me/c/${String(chatId).replace("-100", "")}/${firstMsgId ?? threadId}`;
+          const originalText = ctx.callbackQuery.message?.text ?? "";
+          try {
+            await ctx.editMessageText(
+              originalText + `
 
 \u2705 Session created \u2192 <a href="${topicLink}">Go to topic</a>`,
-            { parse_mode: "HTML" }
-          );
-        } catch {
-          await ctx.editMessageReplyMarkup({
-            reply_markup: { inline_keyboard: [] }
-          });
+              { parse_mode: "HTML" }
+            );
+          } catch {
+            await ctx.editMessageReplyMarkup({
+              reply_markup: { inline_keyboard: [] }
+            });
+          }
+        } else {
+          await ctx.answerCallbackQuery();
+          try {
+            await ctx.editMessageReplyMarkup({
+              reply_markup: { inline_keyboard: [] }
+            });
+          } catch {
+          }
+          await startInteractiveNewSession(ctx, core, chatId, action.agent);
         }
       } else if (action.action === "cancel_session") {
         const assistantId = getAssistantSessionId();
@@ -4303,7 +4981,23 @@ var TelegramAdapter = class extends ChannelAdapter {
       this.telegramConfig.chatId,
       {
         topicId: this.assistantTopicId,
-        getSession: () => this.assistantSession
+        getSession: () => this.assistantSession,
+        respawn: async () => {
+          if (this.assistantSession) {
+            await this.assistantSession.destroy();
+            this.assistantSession = null;
+          }
+          const { session, ready } = await spawnAssistant(
+            this.core,
+            this,
+            this.assistantTopicId
+          );
+          this.assistantSession = session;
+          this.assistantInitializing = true;
+          ready.then(() => {
+            this.assistantInitializing = false;
+          });
+        }
       }
     );
     this.permissionHandler.setupCallbackHandler();
@@ -4356,17 +5050,14 @@ var TelegramAdapter = class extends ChannelAdapter {
     try {
       const config = this.core.configManager.get();
       const agents = this.core.agentManager.getAvailableAgents();
-      const agentList = agents.map((a) => `${escapeHtml(a.name)}${a.name === config.defaultAgent ? " (default)" : ""}`).join(", ");
-      const workspace = escapeHtml(config.workspace.baseDir);
       const allRecords = this.core.sessionManager.listRecords();
-      const activeCount = allRecords.filter((r) => r.status === "active" || r.status === "initializing").length;
-      const welcomeText = `\u{1F44B} <b>OpenACP Assistant</b> is online.
-
-Available agents: ${agentList}
-Workspace: <code>${workspace}</code>
-Sessions: ${activeCount} active / ${allRecords.length} total
-
-<b>Select an action:</b>`;
+      const welcomeText = buildWelcomeMessage({
+        activeCount: allRecords.filter((r) => r.status === "active" || r.status === "initializing").length,
+        errorCount: allRecords.filter((r) => r.status === "error").length,
+        totalCount: allRecords.length,
+        agents: agents.map((a) => a.name),
+        defaultAgent: config.defaultAgent
+      });
       await this.bot.api.sendMessage(this.telegramConfig.chatId, welcomeText, {
         message_thread_id: this.assistantTopicId,
         parse_mode: "HTML",
@@ -4411,6 +5102,9 @@ Sessions: ${activeCount} active / ${allRecords.length} total
   setupRoutes() {
     this.bot.on("message:text", async (ctx) => {
       const threadId = ctx.message.message_thread_id;
+      if (await handlePendingWorkspaceInput(ctx, this.core, this.telegramConfig.chatId, this.assistantTopicId)) {
+        return;
+      }
       if (!threadId) {
         const html = redirectToAssistant(
           this.telegramConfig.chatId,
@@ -4457,6 +5151,10 @@ Sessions: ${activeCount} active / ${allRecords.length} total
     );
     if (!session) return;
     const threadId = Number(session.threadId);
+    if (!threadId || isNaN(threadId)) {
+      log12.warn({ sessionId, threadId: session.threadId }, "Session has no valid threadId, skipping message");
+      return;
+    }
     switch (content.type) {
       case "thought": {
         const tracker = this.getOrCreateTracker(sessionId, threadId);
@@ -4888,4 +5586,4 @@ export {
   TopicManager,
   TelegramAdapter
 };
-//# sourceMappingURL=chunk-BBPWAWE3.js.map
+//# sourceMappingURL=chunk-45DFYWJT.js.map