@openacp/cli 0.4.6 → 0.4.9

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

@@ -830,6 +830,7 @@ var SessionManager = class {
         createdAt: session.createdAt.toISOString(),
         lastActiveAt: (/* @__PURE__ */ new Date()).toISOString(),
         name: session.name,
+        dangerousMode: false,
         platform: {}
       });
     }
@@ -2016,7 +2017,7 @@ var ApiServer = class {
       return;
     }
     target[lastKey] = value;
-    const { ConfigSchema } = await import("./config-J5YQOMDU.js");
+    const { ConfigSchema } = await import("./config-H2DSEHNW.js");
     const result = ConfigSchema.safeParse(cloned);
     if (!result.success) {
       this.sendJson(res, 400, {
@@ -2418,7 +2419,7 @@ function formatUsage(usage) {
   return `${emoji} ${formatTokens(tokensUsed)} / ${formatTokens(contextSize)} tokens
 ${bar} ${pct}%`;
 }
-function splitMessage(text, maxLength = 4096) {
+function splitMessage(text, maxLength = 3800) {
   if (text.length <= maxLength) return [text];
   const chunks = [];
   let remaining = text;
@@ -2428,14 +2429,23 @@ function splitMessage(text, maxLength = 4096) {
       break;
     }
     let splitAt = remaining.lastIndexOf("\n\n", maxLength);
-    if (splitAt === -1 || splitAt < maxLength * 0.5) {
+    if (splitAt === -1 || splitAt < maxLength * 0.2) {
       splitAt = remaining.lastIndexOf("\n", maxLength);
     }
-    if (splitAt === -1 || splitAt < maxLength * 0.5) {
+    if (splitAt === -1 || splitAt < maxLength * 0.2) {
       splitAt = maxLength;
     }
+    const candidate = remaining.slice(0, splitAt);
+    const fences = candidate.match(/```/g);
+    if (fences && fences.length % 2 !== 0) {
+      const closingFence = remaining.indexOf("```", splitAt);
+      if (closingFence !== -1) {
+        const afterFence = remaining.indexOf("\n", closingFence + 3);
+        splitAt = afterFence !== -1 ? afterFence + 1 : closingFence + 3;
+      }
+    }
     chunks.push(remaining.slice(0, splitAt));
-    remaining = remaining.slice(splitAt).trimStart();
+    remaining = remaining.slice(splitAt).replace(/^\n+/, "");
   }
   return chunks;
 }
@@ -2472,14 +2482,22 @@ var MessageDraft = class {
   async flush() {
     if (!this.buffer) return;
     if (this.firstFlushPending) return;
-    const html = markdownToTelegramHtml(this.buffer);
-    const truncated = html.length > 4096 ? html.slice(0, 4090) + "\n..." : html;
-    if (!truncated) return;
+    let displayBuffer = this.buffer;
+    if (displayBuffer.length > 3800) {
+      let cutAt = displayBuffer.lastIndexOf("\n", 3800);
+      if (cutAt < 800) cutAt = 3800;
+      displayBuffer = displayBuffer.slice(0, cutAt) + "\n\u2026";
+    }
+    let html = markdownToTelegramHtml(displayBuffer);
+    if (!html) return;
+    if (html.length > 4096) {
+      html = html.slice(0, 4090) + "\n\u2026";
+    }
     if (!this.messageId) {
       this.firstFlushPending = true;
       try {
         const result = await this.sendQueue.enqueue(
-          () => this.bot.api.sendMessage(this.chatId, truncated, {
+          () => this.bot.api.sendMessage(this.chatId, html, {
             message_thread_id: this.threadId,
             parse_mode: "HTML",
             disable_notification: true
@@ -2497,7 +2515,7 @@ var MessageDraft = class {
     } else {
       try {
         await this.sendQueue.enqueue(
-          () => this.bot.api.editMessageText(this.chatId, this.messageId, truncated, {
+          () => this.bot.api.editMessageText(this.chatId, this.messageId, html, {
             parse_mode: "HTML"
           }),
           { type: "text", key: this.sessionId }
@@ -2517,21 +2535,20 @@ var MessageDraft = class {
     if (this.messageId && this.buffer === this.lastSentBuffer) {
       return this.messageId;
     }
-    const html = markdownToTelegramHtml(this.buffer);
-    const chunks = splitMessage(html);
-    try {
-      for (let i = 0; i < chunks.length; i++) {
-        const chunk = chunks[i];
+    const mdChunks = splitMessage(this.buffer);
+    for (let i = 0; i < mdChunks.length; i++) {
+      const html = markdownToTelegramHtml(mdChunks[i]);
+      try {
         if (i === 0 && this.messageId) {
           await this.sendQueue.enqueue(
-            () => this.bot.api.editMessageText(this.chatId, this.messageId, chunk, {
+            () => this.bot.api.editMessageText(this.chatId, this.messageId, html, {
               parse_mode: "HTML"
             }),
             { type: "other" }
           );
         } else {
           const msg = await this.sendQueue.enqueue(
-            () => this.bot.api.sendMessage(this.chatId, chunk, {
+            () => this.bot.api.sendMessage(this.chatId, html, {
               message_thread_id: this.threadId,
               parse_mode: "HTML",
               disable_notification: true
@@ -2542,17 +2559,25 @@ var MessageDraft = class {
             this.messageId = msg.message_id;
           }
         }
-      }
-    } catch {
-      if (this.buffer !== this.lastSentBuffer) {
+      } catch {
         try {
-          await this.sendQueue.enqueue(
-            () => this.bot.api.sendMessage(this.chatId, this.buffer.slice(0, 4096), {
-              message_thread_id: this.threadId,
-              disable_notification: true
-            }),
-            { type: "other" }
-          );
+          if (i === 0 && this.messageId) {
+            await this.sendQueue.enqueue(
+              () => this.bot.api.editMessageText(this.chatId, this.messageId, mdChunks[i].slice(0, 4096)),
+              { type: "other" }
+            );
+          } else {
+            const msg = await this.sendQueue.enqueue(
+              () => this.bot.api.sendMessage(this.chatId, mdChunks[i].slice(0, 4096), {
+                message_thread_id: this.threadId,
+                disable_notification: true
+              }),
+              { type: "other" }
+            );
+            if (msg) {
+              this.messageId = msg.message_id;
+            }
+          }
         } catch {
         }
       }
@@ -2598,11 +2623,21 @@ 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));
   bot.command("cancel", (ctx) => handleCancel(ctx, core, assistant));
   bot.command("status", (ctx) => handleStatus(ctx, core));
+  bot.command("sessions", (ctx) => handleTopics(ctx, core));
   bot.command("agents", (ctx) => handleAgents(ctx, core));
   bot.command("help", (ctx) => handleHelp(ctx));
   bot.command("menu", (ctx) => handleMenu(ctx));
@@ -2610,27 +2645,96 @@ function setupCommands(bot, core, chatId, assistant) {
   bot.command("disable_dangerous", (ctx) => handleDisableDangerous(ctx, core));
   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{1F916} Agents", "m:agents").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) {
+function setupMenuCallbacks(bot, core, chatId, systemTopicIds) {
   bot.callbackQuery(/^m:/, async (ctx) => {
     const data = ctx.callbackQuery.data;
     try {
       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;
@@ -2646,6 +2750,27 @@ function setupMenuCallbacks(bot, core, chatId) {
       case "m:update":
         await handleUpdate(ctx, core);
         break;
+      case "m:integrate":
+        await handleIntegrate(ctx, core);
+        break;
+      case "m:topics":
+        await handleTopics(ctx, core);
+        break;
+      case "m:cleanup:finished":
+        await handleCleanup(ctx, core, chatId, ["finished"]);
+        break;
+      case "m:cleanup:errors":
+        await handleCleanup(ctx, core, chatId, ["error", "cancelled"]);
+        break;
+      case "m:cleanup:all":
+        await handleCleanup(ctx, core, chatId, ["finished", "error", "cancelled"]);
+        break;
+      case "m:cleanup:everything":
+        await handleCleanupEverything(ctx, core, chatId, systemTopicIds);
+        break;
+      case "m:cleanup:everything:confirm":
+        await handleCleanupEverythingConfirmed(ctx, core, chatId, systemTopicIds);
+        break;
     }
   });
 }
@@ -2662,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`;
@@ -2680,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 });
@@ -2696,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",
@@ -2706,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) {
@@ -2716,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) {
@@ -2870,6 +3088,188 @@ Total sessions: ${sessions.length}`,
     );
   }
 }
+async function handleTopics(ctx, core) {
+  try {
+    const allRecords = core.sessionManager.listRecords();
+    const records = allRecords.filter((r) => {
+      const platform = r.platform;
+      return !!platform?.topicId;
+    });
+    const headlessCount = allRecords.length - records.length;
+    if (records.length === 0) {
+      const extra = headlessCount > 0 ? ` (${headlessCount} headless hidden)` : "";
+      await ctx.reply(`No sessions with topics found.${extra}`, { parse_mode: "HTML" });
+      return;
+    }
+    const statusEmoji = {
+      active: "\u{1F7E2}",
+      initializing: "\u{1F7E1}",
+      finished: "\u2705",
+      error: "\u274C",
+      cancelled: "\u26D4"
+    };
+    const statusOrder = { active: 0, initializing: 1, error: 2, finished: 3, cancelled: 4 };
+    records.sort((a, b) => (statusOrder[a.status] ?? 5) - (statusOrder[b.status] ?? 5));
+    const MAX_DISPLAY = 30;
+    const displayed = records.slice(0, MAX_DISPLAY);
+    const lines = displayed.map((r) => {
+      const emoji = statusEmoji[r.status] || "\u26AA";
+      const name = r.name?.trim();
+      const label = name ? escapeHtml(name) : `<i>${escapeHtml(r.agentName)} session</i>`;
+      return `${emoji} ${label}  <code>[${r.status}]</code>`;
+    });
+    const header = `<b>Sessions: ${records.length}</b>` + (headlessCount > 0 ? ` (${headlessCount} headless hidden)` : "");
+    const truncated = records.length > MAX_DISPLAY ? `
+
+<i>...and ${records.length - MAX_DISPLAY} more</i>` : "";
+    const finishedCount = records.filter((r) => r.status === "finished").length;
+    const errorCount = records.filter((r) => r.status === "error" || r.status === "cancelled").length;
+    const activeCount = records.filter((r) => r.status === "active" || r.status === "initializing").length;
+    const keyboard = new InlineKeyboard();
+    if (finishedCount > 0) {
+      keyboard.text(`Cleanup finished (${finishedCount})`, "m:cleanup:finished").row();
+    }
+    if (errorCount > 0) {
+      keyboard.text(`Cleanup errors (${errorCount})`, "m:cleanup:errors").row();
+    }
+    if (finishedCount + errorCount > 0) {
+      keyboard.text(`Cleanup all non-active (${finishedCount + errorCount})`, "m:cleanup:all").row();
+    }
+    keyboard.text(`\u26A0\uFE0F Cleanup ALL (${records.length})`, "m:cleanup:everything").row();
+    keyboard.text("Refresh", "m:topics");
+    await ctx.reply(
+      `${header}
+
+${lines.join("\n")}${truncated}`,
+      { parse_mode: "HTML", reply_markup: keyboard }
+    );
+  } catch (err) {
+    log8.error({ err }, "handleTopics error");
+    await ctx.reply("\u274C Failed to list sessions.", { parse_mode: "HTML" }).catch(() => {
+    });
+  }
+}
+async function handleCleanup(ctx, core, chatId, statuses) {
+  const allRecords = core.sessionManager.listRecords();
+  const cleanable = allRecords.filter((r) => {
+    const platform = r.platform;
+    return !!platform?.topicId && statuses.includes(r.status);
+  });
+  if (cleanable.length === 0) {
+    await ctx.reply("Nothing to clean up.", { parse_mode: "HTML" });
+    return;
+  }
+  let deleted = 0;
+  let failed = 0;
+  for (const record of cleanable) {
+    try {
+      const topicId = record.platform?.topicId;
+      if (topicId) {
+        try {
+          await ctx.api.deleteForumTopic(chatId, topicId);
+        } catch (err) {
+          log8.warn({ err, sessionId: record.sessionId, topicId }, "Failed to delete forum topic during cleanup");
+        }
+      }
+      await core.sessionManager.removeRecord(record.sessionId);
+      deleted++;
+    } catch (err) {
+      log8.error({ err, sessionId: record.sessionId }, "Failed to cleanup session");
+      failed++;
+    }
+  }
+  await ctx.reply(
+    `\u{1F5D1} Cleaned up <b>${deleted}</b> sessions${failed > 0 ? ` (${failed} failed)` : ""}.`,
+    { parse_mode: "HTML" }
+  );
+}
+async function handleCleanupEverything(ctx, core, chatId, systemTopicIds) {
+  const allRecords = core.sessionManager.listRecords();
+  const cleanable = allRecords.filter((r) => {
+    const platform = r.platform;
+    if (!platform?.topicId) return false;
+    if (systemTopicIds && (platform.topicId === systemTopicIds.notificationTopicId || platform.topicId === systemTopicIds.assistantTopicId)) return false;
+    return true;
+  });
+  if (cleanable.length === 0) {
+    await ctx.reply("Nothing to clean up.", { parse_mode: "HTML" });
+    return;
+  }
+  const statusCounts = /* @__PURE__ */ new Map();
+  for (const r of cleanable) {
+    statusCounts.set(r.status, (statusCounts.get(r.status) ?? 0) + 1);
+  }
+  const statusEmoji = {
+    active: "\u{1F7E2}",
+    initializing: "\u{1F7E1}",
+    finished: "\u2705",
+    error: "\u274C",
+    cancelled: "\u26D4"
+  };
+  const breakdown = Array.from(statusCounts.entries()).map(([status, count]) => `${statusEmoji[status] ?? "\u26AA"} ${status}: ${count}`).join("\n");
+  const activeCount = (statusCounts.get("active") ?? 0) + (statusCounts.get("initializing") ?? 0);
+  const activeWarning = activeCount > 0 ? `
+
+\u26A0\uFE0F <b>${activeCount} active session(s) will be cancelled and their agents stopped!</b>` : "";
+  const keyboard = new InlineKeyboard().text("Yes, delete all", "m:cleanup:everything:confirm").text("Cancel", "m:topics");
+  await ctx.reply(
+    `<b>Delete ${cleanable.length} topics?</b>
+
+This will:
+\u2022 Delete all session topics from this group
+\u2022 Cancel any running agent sessions
+\u2022 Remove all session records
+
+<b>Breakdown:</b>
+${breakdown}${activeWarning}
+
+<i>Notifications and Assistant topics will NOT be deleted.</i>`,
+    { parse_mode: "HTML", reply_markup: keyboard }
+  );
+}
+async function handleCleanupEverythingConfirmed(ctx, core, chatId, systemTopicIds) {
+  const allRecords = core.sessionManager.listRecords();
+  const cleanable = allRecords.filter((r) => {
+    const platform = r.platform;
+    if (!platform?.topicId) return false;
+    if (systemTopicIds && (platform.topicId === systemTopicIds.notificationTopicId || platform.topicId === systemTopicIds.assistantTopicId)) return false;
+    return true;
+  });
+  if (cleanable.length === 0) {
+    await ctx.reply("Nothing to clean up.", { parse_mode: "HTML" });
+    return;
+  }
+  let deleted = 0;
+  let failed = 0;
+  for (const record of cleanable) {
+    try {
+      if (record.status === "active" || record.status === "initializing") {
+        try {
+          await core.sessionManager.cancelSession(record.sessionId);
+        } catch (err) {
+          log8.warn({ err, sessionId: record.sessionId }, "Failed to cancel session during cleanup");
+        }
+      }
+      const topicId = record.platform?.topicId;
+      if (topicId) {
+        try {
+          await ctx.api.deleteForumTopic(chatId, topicId);
+        } catch (err) {
+          log8.warn({ err, sessionId: record.sessionId, topicId }, "Failed to delete forum topic during cleanup");
+        }
+      }
+      await core.sessionManager.removeRecord(record.sessionId);
+      deleted++;
+    } catch (err) {
+      log8.error({ err, sessionId: record.sessionId }, "Failed to cleanup session");
+      failed++;
+    }
+  }
+  await ctx.reply(
+    `\u{1F5D1} Cleaned up <b>${deleted}</b> sessions${failed > 0 ? ` (${failed} failed)` : ""}.`,
+    { parse_mode: "HTML" }
+  );
+}
 async function handleAgents(ctx, core) {
   const agents = core.agentManager.getAvailableAgents();
   const defaultAgent = core.configManager.get().defaultAgent;
@@ -2886,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",
@@ -3126,16 +3558,182 @@ async function executeCancelSession(core, excludeSessionId) {
   await session.cancel();
   return session;
 }
+async function handleIntegrate(ctx, _core) {
+  const { listIntegrations } = await import("./integrate-WUPLRJD3.js");
+  const agents = listIntegrations();
+  const keyboard = new InlineKeyboard();
+  for (const agent of agents) {
+    keyboard.text(`\u{1F916} ${agent}`, `i:agent:${agent}`).row();
+  }
+  await ctx.reply(
+    `<b>\u{1F517} Integrations</b>
+
+Select an agent to manage its integrations.`,
+    { parse_mode: "HTML", reply_markup: keyboard }
+  );
+}
+function buildAgentItemsKeyboard(agentName, items) {
+  const keyboard = new InlineKeyboard();
+  for (const item of items) {
+    const installed = item.isInstalled();
+    keyboard.text(
+      installed ? `\u2705 ${item.name} \u2014 Uninstall` : `\u{1F4E6} ${item.name} \u2014 Install`,
+      installed ? `i:uninstall:${agentName}:${item.id}` : `i:install:${agentName}:${item.id}`
+    ).row();
+  }
+  keyboard.text("\u2190 Back", "i:back").row();
+  return keyboard;
+}
+function setupIntegrateCallbacks(bot, core) {
+  bot.callbackQuery(/^i:/, async (ctx) => {
+    const data = ctx.callbackQuery.data;
+    try {
+      await ctx.answerCallbackQuery();
+    } catch {
+    }
+    if (data === "i:back") {
+      const { listIntegrations } = await import("./integrate-WUPLRJD3.js");
+      const agents = listIntegrations();
+      const keyboard2 = new InlineKeyboard();
+      for (const agent of agents) {
+        keyboard2.text(`\u{1F916} ${agent}`, `i:agent:${agent}`).row();
+      }
+      try {
+        await ctx.editMessageText(
+          `<b>\u{1F517} Integrations</b>
+
+Select an agent to manage its integrations.`,
+          { parse_mode: "HTML", reply_markup: keyboard2 }
+        );
+      } catch {
+      }
+      return;
+    }
+    const agentMatch = data.match(/^i:agent:(.+)$/);
+    if (agentMatch) {
+      const agentName2 = agentMatch[1];
+      const { getIntegration: getIntegration2 } = await import("./integrate-WUPLRJD3.js");
+      const integration2 = getIntegration2(agentName2);
+      if (!integration2) {
+        await ctx.reply(`\u274C No integration available for '${escapeHtml(agentName2)}'.`, { parse_mode: "HTML" });
+        return;
+      }
+      const keyboard2 = buildAgentItemsKeyboard(agentName2, integration2.items);
+      try {
+        await ctx.editMessageText(
+          `<b>\u{1F517} ${escapeHtml(agentName2)} Integrations</b>
+
+${integration2.items.map((i) => `\u2022 <b>${escapeHtml(i.name)}</b> \u2014 ${escapeHtml(i.description)}`).join("\n")}`,
+          { parse_mode: "HTML", reply_markup: keyboard2 }
+        );
+      } catch {
+        await ctx.reply(
+          `<b>\u{1F517} ${escapeHtml(agentName2)} Integrations</b>`,
+          { parse_mode: "HTML", reply_markup: keyboard2 }
+        );
+      }
+      return;
+    }
+    const actionMatch = data.match(/^i:(install|uninstall):([^:]+):(.+)$/);
+    if (!actionMatch) return;
+    const action = actionMatch[1];
+    const agentName = actionMatch[2];
+    const itemId = actionMatch[3];
+    const { getIntegration } = await import("./integrate-WUPLRJD3.js");
+    const integration = getIntegration(agentName);
+    if (!integration) return;
+    const item = integration.items.find((i) => i.id === itemId);
+    if (!item) return;
+    const result = action === "install" ? await item.install() : await item.uninstall();
+    const installed = action === "install" && result.success;
+    await core.configManager.save({
+      integrations: {
+        [agentName]: {
+          installed,
+          installedAt: installed ? (/* @__PURE__ */ new Date()).toISOString() : void 0
+        }
+      }
+    });
+    const statusEmoji = result.success ? "\u2705" : "\u274C";
+    const actionLabel = action === "install" ? "installed" : "uninstalled";
+    const logsText = result.logs.map((l) => `<code>${escapeHtml(l)}</code>`).join("\n");
+    const resultText = `${statusEmoji} <b>${escapeHtml(item.name)}</b> ${actionLabel}.
+
+${logsText}`;
+    const keyboard = buildAgentItemsKeyboard(agentName, integration.items);
+    try {
+      await ctx.editMessageText(
+        `<b>\u{1F517} ${escapeHtml(agentName)} Integrations</b>
+
+${resultText}`,
+        { parse_mode: "HTML", reply_markup: keyboard }
+      );
+    } catch {
+      await ctx.reply(resultText, { parse_mode: "HTML" });
+    }
+  });
+}
+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" },
   { command: "cancel", description: "Cancel current session" },
   { command: "status", description: "Show status" },
+  { command: "sessions", description: "List all sessions" },
   { command: "agents", description: "List available agents" },
   { command: "help", description: "Help" },
   { command: "menu", description: "Show menu" },
   { command: "enable_dangerous", description: "Auto-approve all permission requests (session only)" },
   { 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" }
 ];
@@ -3220,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) {
@@ -3256,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>\`
+
+### 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
+
+### 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 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
+### 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
 
-## Management Commands (via CLI)
-You have access to bash. Use these commands to manage OpenACP:
+### 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>\`
 
-### Session management
+### 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
@@ -3313,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;
@@ -3761,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();
@@ -3942,10 +4968,12 @@ var TelegramAdapter = class extends ChannelAdapter {
       this.telegramConfig.chatId,
       () => this.assistantSession?.id
     );
+    setupIntegrateCallbacks(this.bot, this.core);
     setupMenuCallbacks(
       this.bot,
       this.core,
-      this.telegramConfig.chatId
+      this.telegramConfig.chatId,
+      { notificationTopicId: this.notificationTopicId, assistantTopicId: this.assistantTopicId }
     );
     setupCommands(
       this.bot,
@@ -3953,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();
@@ -3967,24 +5011,26 @@ var TelegramAdapter = class extends ChannelAdapter {
         return;
       }
       const session = this.core.sessionManager.getSessionByThread("telegram", String(threadId));
-      if (!session) {
-        await ctx.reply("No active session in this topic.", {
+      const record = session ? void 0 : this.core.sessionManager.getRecordByThread("telegram", String(threadId));
+      const agentName = session?.agentName ?? record?.agentName;
+      const agentSessionId = session?.agentSessionId ?? record?.agentSessionId;
+      if (!agentName || !agentSessionId) {
+        await ctx.reply("No session found for this topic.", {
           message_thread_id: threadId
         });
         return;
       }
       const { getAgentCapabilities: getAgentCapabilities2 } = await import("./agent-registry-7HC6D4CH.js");
-      const caps = getAgentCapabilities2(session.agentName);
+      const caps = getAgentCapabilities2(agentName);
       if (!caps.supportsResume || !caps.resumeCommand) {
-        await ctx.reply("This agent does not support CLI handoff.", {
+        await ctx.reply("This agent does not support session transfer.", {
           message_thread_id: threadId
         });
         return;
       }
-      const agentSessionId = session.agentSessionId;
       const command = caps.resumeCommand(agentSessionId);
       await ctx.reply(
-        `Resume this session on CLI:
+        `Run this in your terminal to continue the session:
 
 <code>${command}</code>`,
         {
@@ -4004,14 +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 welcomeText = `\u{1F44B} <b>OpenACP Assistant</b> is online.
-
-Available agents: ${agentList}
-Workspace: <code>${workspace}</code>
-
-<b>Select an action:</b>`;
+      const allRecords = this.core.sessionManager.listRecords();
+      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",
@@ -4056,6 +5102,9 @@ Workspace: <code>${workspace}</code>
   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,
@@ -4102,6 +5151,10 @@ Workspace: <code>${workspace}</code>
     );
     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);
@@ -4533,4 +5586,4 @@ export {
   TopicManager,
   TelegramAdapter
 };
-//# sourceMappingURL=chunk-2M4O7AFI.js.map
+//# sourceMappingURL=chunk-45DFYWJT.js.map