pikiclaw 0.2.49 → 0.2.51

package/README.md

@@ -2,13 +2,11 @@
 
 # pikiclaw
 
-**Run Claude Code / Codex / Gemini on your own computer from Telegram or Feishu.**
+**Put the world's smartest AI agents in your pocket. Command local Claude & Gemini via best IM.**
 
-*把 IM 变成你电脑上的远程 Agent 控制台。*
+*让最好用的 IM 变成你电脑上的顶级 Agent 控制台*
 
-```bash
-npx pikiclaw@latest
-```
+> npx pikiclaw@latest
 
 <p align="center">
 <a href="https://www.npmjs.com/package/pikiclaw"><img src="https://img.shields.io/npm/v/pikiclaw" alt="npm"></a>
@@ -92,48 +90,48 @@ npx pikiclaw@latest --doctor
 
 ---
 
-## What Exists Today
-
-### Channels
+## Current Capabilities
 
-- Telegram 已可用
-- 飞书已可用
-- 两个渠道可以同时启动
+### Channels And Agents
 
-### Agents
-
-- Claude Code
-- Codex CLI
-- Gemini CLI
-
-Agent 通过 driver registry 接入，模型列表、会话列表、usage 展示都走统一接口。
+- Telegram、飞书都可用，也可以同时启动
+- Claude Code、Codex CLI、Gemini CLI 都已接入
+- agent 通过统一 driver registry 管理，模型列表、session 列表、usage 展示走同一套接口
 
 ### Runtime
 
 - 流式预览和持续消息更新
 - 会话切换、恢复和多轮续聊
 - 工作目录浏览与切换
-- 长任务防休眠
-- watchdog 守护和自动重启
-- 长文本自动拆分，文件和图片自动回传
+- 文件附件自动进入 session workspace
+- 长任务防休眠、watchdog 守护和自动重启
+- 长文本自动拆分，图片和文件可直接回传到 IM
+- Dashboard 可查看运行状态、sessions、usage、主机状态和 macOS 权限状态
 
 ### Skills
 
-- 支持项目级 `.pikiclaw/skills/*/SKILL.md`
+- 项目级 skills 以 `.pikiclaw/skills/*/SKILL.md` 为 canonical 入口
 - 兼容 `.claude/commands/*.md`
+- 兼容 legacy `.claude/skills` / `.agents/skills`，并可合并回 `.pikiclaw/skills`
 - IM 内可通过 `/skills` 和 `/sk_<name>` 触发
 
-### MCP Session Bridge
+### Codex Human Loop
+
+当 Codex 在运行过程中请求额外用户输入时，pikiclaw 会把问题转成 Telegram / 飞书里的交互提示，用户回复后再继续当前任务。
+
+### MCP And GUI Automation
 
-每次 Agent stream 会启动一个会话级 MCP server，把 IM 能力暴露给 Agent。
+每次 Agent stream 都会启动一个会话级 MCP bridge，把本地工具按本次任务注入给 Agent。
 
-当前已接入的工具：
+当前内置工具：
 
 - `im_list_files`：列出 session workspace 文件
 - `im_send_file`：把文件实时发回 IM
-- `take_screenshot`：跨平台截图并返回路径
 
-当前 `guiTools` 模块已经预留，但点击、输入、窗口控制等顶级 GUI 工具还没接上。
+可选 GUI 能力：
+
+- 浏览器自动化：通过 `@playwright/mcp` 补充接入，默认支持 Chrome extension mode，也可切到 headless / isolated 模式
+- macOS 桌面自动化：通过 Appium Mac2 提供 `desktop_open_app`、`desktop_snapshot`、`desktop_click`、`desktop_type`、`desktop_screenshot` 等工具
 
 ---
 
@@ -156,42 +154,37 @@ Agent 通过 driver registry 接入，模型列表、会话列表、usage 展示
 
 ---
 
-## Skills And MCP
+## Config And Setup Notes
 
-项目里现在有两条能力扩展线：
+- 持久化配置在 `~/.pikiclaw/setting.json`
+- Dashboard 是主配置入口，环境变量仍然可用
+- 浏览器 GUI 相关常用变量：
+  - `PIKICLAW_BROWSER_GUI`
+  - `PIKICLAW_BROWSER_USE_EXTENSION`
+  - `PIKICLAW_BROWSER_HEADLESS`
+  - `PIKICLAW_BROWSER_ISOLATED`
+  - `PLAYWRIGHT_MCP_EXTENSION_TOKEN`
+- 桌面 GUI 相关常用变量：
+  - `PIKICLAW_DESKTOP_GUI`
+  - `PIKICLAW_DESKTOP_APPIUM_URL`
 
-- Skills：偏“高层工作流提示词”，来源于 `.pikiclaw/skills` 和 `.claude/commands`
-- MCP tools：偏“可执行工具能力”，目前是会话级 bridge，由 pikiclaw 在每次 stream 时注入
+如果要启用 macOS 桌面自动化，需要先准备 Appium Mac2：
 
-这两条线已经能工作，但都还是偏“session / project 内部接入”，还不是仓库级统一入口。
+```bash
+npm install -g appium
+appium driver install mac2
+appium
+```
 
----
+然后给运行 `pikiclaw` 的终端应用授予 macOS 的辅助功能权限。
 
-## Status
+---
 
-### 已完成
+## Roadmap
 
-| 项目 | 状态 |
-|---|---|
-| Telegram 渠道 | ✅ |
-| 飞书渠道 | ✅ |
-| Claude Code driver | ✅ |
-| Codex CLI driver | ✅ |
-| Gemini CLI driver | ✅ |
-| Web Dashboard | ✅ |
-| 项目级 Skills | ✅ |
-| 会话级 MCP bridge | ✅ |
-| 文件回传 / 截图回传 | ✅ |
-| 守护重启 / 防休眠 | ✅ |
-
-### 待办
-
-| 项目 | 说明 |
-|---|---|
-| 顶级 Skills 接入 | 把 skills 从当前项目级入口提升为更统一的顶级接入能力 |
-| 顶级 MCP 工具接入 | 把当前会话级 MCP bridge 扩展成更完整的顶级工具接入层 |
-| GUI 自动化工具补全 | 在 `src/tools/gui.ts` 上接入点击、输入、聚焦、窗口控制等工具 |
-| 更多渠道 | WhatsApp 仍在规划中 |
+- 把当前会话级 MCP bridge 继续扩展成更完整的顶级工具接入层
+- 继续完善 GUI 自动化能力，尤其是浏览器与桌面工具的协同链路
+- 增加更多 IM 渠道，WhatsApp 仍在规划中
 
 ---
 
@@ -216,6 +209,9 @@ npx vitest run test/channel-feishu.unit.test.ts
 npx pikiclaw@latest --doctor
 ```
 
+`npm run dev` 只跑本地源码链路，会固定使用 `--no-daemon`，避免跳转到生产/自举用的 `npx pikiclaw@latest`。
+同时会把本次启动的全部日志写到 `~/.pikiclaw/dev/dev.log`，并在每次启动时先清空旧日志。
+
 更多实现细节见：
 
 - [ARCHITECTURE.md](ARCHITECTURE.md)

package/dist/bot-feishu-render.js

@@ -9,6 +9,7 @@ import { fmtUptime, fmtTokens, fmtBytes, formatThinkingForDisplay, thinkLabel }
 import { summarizePromptForStatus } from './bot-commands.js';
 import { formatProviderUsageLines } from './bot-telegram-render.js';
 import { formatActivityCommandSummary, parseActivitySummary, renderPlanForPreview, summarizeActivityForPreview } from './bot-streaming.js';
+import { currentHumanLoopQuestion, humanLoopAnsweredCount, isHumanLoopAwaitingText, isHumanLoopQuestionAnswered, summarizeHumanLoopAnswer, } from './human-loop.js';
 import path from 'node:path';
 import { listSubdirs } from './bot.js';
 // ---------------------------------------------------------------------------
@@ -163,6 +164,38 @@ export function renderSessionTurnMarkdown(userText, assistantText) {
         parts.push('**Assistant**', assistant);
     return parts.join('\n\n');
 }
+export function buildHumanLoopPromptMarkdown(prompt) {
+    const question = currentHumanLoopQuestion(prompt);
+    const lines = [`**${prompt.title}**`];
+    if (prompt.detail)
+        lines.push(`\`${prompt.detail}\``);
+    lines.push(`*${humanLoopAnsweredCount(prompt)}/${prompt.questions.length} answered*`);
+    if (!question)
+        return lines.join('\n\n');
+    if (question.header.trim())
+        lines.push(`**${question.header}**`);
+    lines.push(question.prompt);
+    const options = question.options || [];
+    if (options.length) {
+        lines.push(options.map((option, index) => {
+            const detail = option.description ? `\n   ${option.description}` : '';
+            return `${index + 1}. ${option.label}${detail}`;
+        }).join('\n'));
+    }
+    if (isHumanLoopAwaitingText(prompt)) {
+        lines.push(`*${question.secret ? 'Reply in chat with the secret value.' : 'Reply in chat with text to answer.'}*`);
+    }
+    if (prompt.hint)
+        lines.push(`*${prompt.hint}*`);
+    if (prompt.questions.length > 1) {
+        lines.push(prompt.questions.map((item, index) => {
+            const summary = summarizeHumanLoopAnswer(prompt, item);
+            const answered = isHumanLoopQuestionAnswered(prompt, index);
+            return `${answered ? '●' : '○'} ${item.header || item.prompt}: ${summary.display}`;
+        }).join('\n'));
+    }
+    return lines.join('\n\n');
+}
 // ---------------------------------------------------------------------------
 // LivePreview renderer — produces Markdown for Feishu card elements
 // ---------------------------------------------------------------------------

package/dist/bot-feishu.js

@@ -18,7 +18,9 @@ import { getStartData, getSessionsPageData, getModelsListData, getSessionTurnPre
 import { buildAgentsCommandView, buildModelsCommandView, buildSessionsCommandView, buildSkillsCommandView, decodeCommandAction, executeCommandAction, } from './bot-command-ui.js';
 import { LivePreview } from './bot-telegram-live-preview.js';
 import { formatActiveTaskRestartError, getActiveTaskCount, registerProcessRuntime, requestProcessRestart, } from './process-control.js';
-import { feishuPreviewRenderer, feishuStreamingPreviewRenderer, buildInitialPreviewMarkdown, buildFinalReplyRender, renderCommandNotice, renderCommandSelectionCard, renderSessionTurnMarkdown, renderStart, renderStatus, renderHost, buildSwitchWorkdirCard, resolveFeishuRegisteredPath, } from './bot-feishu-render.js';
+import { feishuPreviewRenderer, feishuStreamingPreviewRenderer, buildInitialPreviewMarkdown, buildHumanLoopPromptMarkdown, buildFinalReplyRender, renderCommandNotice, renderCommandSelectionCard, renderSessionTurnMarkdown, renderStart, renderStatus, renderHost, buildSwitchWorkdirCard, resolveFeishuRegisteredPath, } from './bot-feishu-render.js';
+import { buildCodexHumanLoopPrompt } from './human-loop-codex.js';
+import { currentHumanLoopQuestion, humanLoopOptionSelected } from './human-loop.js';
 import { FeishuChannel } from './channel-feishu.js';
 import { splitText, supportsChannelCapability } from './channel-base.js';
 import { getActiveUserConfig } from './user-config.js';
@@ -376,11 +378,110 @@ export class FeishuBot extends Bot {
             parts.push(`cancelled ${cancelledQueued} queued ${cancelledQueued === 1 ? 'task' : 'tasks'}`);
         await ctx.reply(`Stopped current session: ${parts.join(', ')}.`);
     }
+    buildHumanLoopKeyboard(promptId) {
+        const prompt = this.humanLoopPrompt(promptId);
+        const question = prompt ? currentHumanLoopQuestion(prompt) : null;
+        const rows = [];
+        for (let index = 0; index < (question?.options?.length || 0); index++) {
+            const option = question.options[index];
+            rows.push({
+                actions: [{
+                        tag: 'button',
+                        text: { tag: 'plain_text', content: `${humanLoopOptionSelected(prompt, option.value) ? '●' : '○'} ${option.label}`.slice(0, 32) },
+                        value: { action: `hl:o:${promptId}:${index}` },
+                    }],
+            });
+        }
+        if (question?.options?.length && question.allowFreeform) {
+            rows.push({
+                actions: [{
+                        tag: 'button',
+                        text: { tag: 'plain_text', content: 'Other...' },
+                        value: { action: `hl:other:${promptId}` },
+                    }],
+            });
+        }
+        if (question?.allowEmpty) {
+            rows.push({
+                actions: [{
+                        tag: 'button',
+                        text: { tag: 'plain_text', content: 'Skip' },
+                        value: { action: `hl:skip:${promptId}` },
+                    }],
+            });
+        }
+        rows.push({
+            actions: [{
+                    tag: 'button',
+                    text: { tag: 'plain_text', content: 'Cancel' },
+                    value: { action: `hl:cancel:${promptId}` },
+                }],
+        });
+        return { rows };
+    }
+    async refreshHumanLoopPrompt(chatId, promptId, suffix) {
+        const prompt = this.humanLoopPrompt(promptId);
+        if (!prompt)
+            return;
+        const messageId = prompt.messageIds[0];
+        if (!messageId)
+            return;
+        const markdown = `${buildHumanLoopPromptMarkdown(prompt)}${suffix ? `\n\n*${suffix}*` : ''}`;
+        await this.channel.editMessage(chatId, String(messageId), markdown, {
+            keyboard: this.buildHumanLoopKeyboard(promptId),
+        }).catch(() => { });
+    }
+    async finalizeHumanLoopPrompt(prompt, suffix) {
+        if (!prompt)
+            return;
+        const messageId = prompt.messageIds[0];
+        if (!messageId)
+            return;
+        const markdown = `${buildHumanLoopPromptMarkdown(prompt)}\n\n*${suffix}*`;
+        await this.channel.editMessage(prompt.chatId, String(messageId), markdown, {
+            keyboard: { rows: [] },
+        }).catch(() => { });
+    }
+    createCodexHumanLoopHandler(ctx, taskId) {
+        return async (request) => {
+            const blueprint = buildCodexHumanLoopPrompt(request);
+            const active = this.beginHumanLoopPrompt({
+                taskId,
+                chatId: ctx.chatId,
+                ...blueprint,
+            });
+            try {
+                const sent = await ctx.reply(buildHumanLoopPromptMarkdown(active.prompt), {
+                    keyboard: this.buildHumanLoopKeyboard(active.prompt.promptId),
+                });
+                if (sent)
+                    this.registerHumanLoopMessage(active.prompt.promptId, sent);
+            }
+            catch (error) {
+                this.humanLoopCancel(active.prompt.promptId, error?.message || 'Failed to send prompt.');
+                throw error;
+            }
+            return active.result;
+        };
+    }
     // ---- streaming bridge -----------------------------------------------------
     async handleMessage(msg, ctx) {
         const text = msg.text.trim();
         if (!text && !msg.files.length)
             return;
+        const pendingPrompt = this.pendingHumanLoopPrompt(ctx.chatId);
+        if (pendingPrompt && text && !msg.files.length && !text.startsWith('/')) {
+            const result = this.humanLoopSubmitText(ctx.chatId, text);
+            if (!result) {
+                await ctx.reply('Please answer the active prompt using the buttons above.');
+                return;
+            }
+            if (result.completed)
+                await this.finalizeHumanLoopPrompt(result.prompt, 'Answer submitted.');
+            else
+                await this.refreshHumanLoopPrompt(ctx.chatId, result.prompt.promptId);
+            return;
+        }
         const session = this.resolveIncomingSession(ctx, text, msg.files);
         const cs = this.chat(ctx.chatId);
         this.applySessionSelection(cs, session);
@@ -484,7 +585,7 @@ export class FeishuBot extends Bot {
                 const mcpSendFile = this.createMcpSendFileCallback(ctx);
                 const result = await this.runStream(prompt, session, files, (nextText, nextThinking, nextActivity = '', meta, plan) => {
                     livePreview?.update(nextText, nextThinking, nextActivity, meta, plan);
-                }, undefined, mcpSendFile, abortController.signal);
+                }, undefined, mcpSendFile, abortController.signal, this.createCodexHumanLoopHandler(ctx, taskId));
                 await livePreview?.settle();
                 const finalReplyIds = await this.sendFinalReply(ctx, placeholderId, session.agent, result);
                 this.registerSessionMessages(ctx.chatId, finalReplyIds, session);
@@ -680,6 +781,8 @@ export class FeishuBot extends Bot {
     // ---- callback handlers ----------------------------------------------------
     async handleCallback(data, ctx) {
         try {
+            if (await this.handleHumanLoopCallback(data, ctx))
+                return;
             if (await this.handleTaskStopCallback(data, ctx))
                 return;
             if (await this.handleSwitchNavigateCallback(data, ctx))
@@ -698,6 +801,52 @@ export class FeishuBot extends Bot {
             this.log(`callback error: ${e}`);
         }
     }
+    async handleHumanLoopCallback(data, ctx) {
+        if (!data.startsWith('hl:'))
+            return false;
+        const [, action, promptId, rawIndex] = data.split(':');
+        const prompt = this.humanLoopPrompt(promptId);
+        if (!prompt)
+            return true;
+        if (action === 'cancel') {
+            const cancelled = this.humanLoopCancel(promptId, 'Prompt cancelled from Feishu.');
+            await this.finalizeHumanLoopPrompt(cancelled, 'Cancelled.');
+            return true;
+        }
+        if (action === 'skip') {
+            const result = this.humanLoopSkip(promptId);
+            if (!result)
+                return true;
+            if (result.completed)
+                await this.finalizeHumanLoopPrompt(result.prompt, 'Answer submitted.');
+            else
+                await this.refreshHumanLoopPrompt(ctx.chatId, promptId);
+            return true;
+        }
+        if (action === 'other') {
+            const result = this.humanLoopSelectOption(promptId, '__other__', { requestFreeform: true });
+            if (!result)
+                return true;
+            await this.refreshHumanLoopPrompt(ctx.chatId, promptId);
+            return true;
+        }
+        if (action === 'o') {
+            const index = Number.parseInt(rawIndex || '', 10);
+            const question = this.humanLoopCurrentQuestion(promptId);
+            const option = Number.isFinite(index) ? question?.options?.[index] : null;
+            if (!option)
+                return true;
+            const result = this.humanLoopSelectOption(promptId, option.value);
+            if (!result)
+                return true;
+            if (result.completed)
+                await this.finalizeHumanLoopPrompt(result.prompt, 'Answer submitted.');
+            else
+                await this.refreshHumanLoopPrompt(ctx.chatId, promptId);
+            return true;
+        }
+        return true;
+    }
     async handleTaskStopCallback(data, ctx) {
         if (!data.startsWith('tsk:stop:'))
             return false;

package/dist/bot-telegram-render.js

@@ -1,6 +1,7 @@
 import { encodeCommandAction } from './bot-command-ui.js';
 import { fmtUptime, formatThinkingForDisplay, thinkLabel } from './bot.js';
 import { formatActivityCommandSummary, parseActivitySummary, renderPlanForPreview, summarizeActivityForPreview } from './bot-streaming.js';
+import { currentHumanLoopQuestion, humanLoopAnsweredCount, isHumanLoopAwaitingText, isHumanLoopQuestionAnswered, summarizeHumanLoopAnswer, } from './human-loop.js';
 export function escapeHtml(t) {
     return t.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
@@ -91,6 +92,44 @@ export function renderCommandSelectionKeyboard(view) {
         }))),
     };
 }
+export function buildHumanLoopPromptHtml(prompt) {
+    const question = currentHumanLoopQuestion(prompt);
+    const lines = [`<b>${escapeHtml(prompt.title)}</b>`];
+    if (prompt.detail)
+        lines.push(compactCode(prompt.detail, 40));
+    lines.push(`<i>${humanLoopAnsweredCount(prompt)}/${prompt.questions.length} answered</i>`);
+    if (!question)
+        return lines.join('\n');
+    lines.push('');
+    if (question.header.trim())
+        lines.push(`<b>${escapeHtml(question.header)}</b>`);
+    lines.push(escapeHtml(question.prompt));
+    const options = question.options || [];
+    if (options.length) {
+        lines.push('');
+        for (let i = 0; i < options.length; i++) {
+            const option = options[i];
+            lines.push(`${i + 1}. ${escapeHtml(option.label)}`);
+            if (option.description)
+                lines.push(`<i>${escapeHtml(option.description)}</i>`);
+        }
+    }
+    if (isHumanLoopAwaitingText(prompt)) {
+        lines.push('', `<i>${question.secret ? 'Reply with the secret value in chat.' : 'Reply with text in chat to answer.'}</i>`);
+    }
+    if (prompt.hint)
+        lines.push('', `<i>${escapeHtml(prompt.hint)}</i>`);
+    if (prompt.questions.length > 1) {
+        lines.push('');
+        for (let i = 0; i < prompt.questions.length; i++) {
+            const item = prompt.questions[i];
+            const summary = summarizeHumanLoopAnswer(prompt, item);
+            const answered = isHumanLoopQuestionAnswered(prompt, i);
+            lines.push(`${answered ? '●' : '○'} ${escapeHtml(item.header || item.prompt)}: ${escapeHtml(summary.display)}`);
+        }
+    }
+    return lines.join('\n');
+}
 function mdInline(line) {
     const parts = [];
     let rest = line;

package/dist/bot-telegram.js

@@ -19,7 +19,9 @@ import { buildAgentsCommandView, buildModelsCommandView, buildSessionsCommandVie
 import { buildSwitchWorkdirView, resolveRegisteredPath } from './bot-telegram-directory.js';
 import { LivePreview } from './bot-telegram-live-preview.js';
 import { formatActiveTaskRestartError, getActiveTaskCount, registerProcessRuntime, buildRestartCommand, requestProcessRestart, } from './process-control.js';
-import { buildInitialPreviewHtml, buildStreamPreviewHtml, buildFinalReplyRender, escapeHtml, formatMenuLines, formatProviderUsageLines, renderCommandNoticeHtml, renderCommandSelectionHtml, renderCommandSelectionKeyboard, renderSessionTurnHtml, truncateMiddle, } from './bot-telegram-render.js';
+import { buildInitialPreviewHtml, buildHumanLoopPromptHtml, buildStreamPreviewHtml, buildFinalReplyRender, escapeHtml, formatMenuLines, formatProviderUsageLines, renderCommandNoticeHtml, renderCommandSelectionHtml, renderCommandSelectionKeyboard, renderSessionTurnHtml, truncateMiddle, } from './bot-telegram-render.js';
+import { buildCodexHumanLoopPrompt } from './human-loop-codex.js';
+import { currentHumanLoopQuestion, humanLoopOptionSelected } from './human-loop.js';
 import { TelegramChannel } from './channel-telegram.js';
 import { splitText, supportsChannelCapability } from './channel-base.js';
 import { getActiveUserConfig } from './user-config.js';
@@ -358,11 +360,91 @@ export class TelegramBot extends Bot {
             parts.push(`cancelled ${cancelledQueued} queued ${cancelledQueued === 1 ? 'task' : 'tasks'}`);
         await ctx.reply(`Stopped current session: ${parts.join(', ')}.`);
     }
+    buildHumanLoopKeyboard(promptId) {
+        const prompt = this.humanLoopPrompt(promptId);
+        const question = prompt ? currentHumanLoopQuestion(prompt) : null;
+        const inline_keyboard = [];
+        const optionRows = (question?.options || []).map((option, index) => ([{
+                text: `${humanLoopOptionSelected(prompt, option.value) ? '●' : '○'} ${truncateMiddle(option.label, 28)}`,
+                callback_data: `hl:o:${promptId}:${index}`,
+            }]));
+        inline_keyboard.push(...optionRows);
+        if (question?.options?.length && question.allowFreeform) {
+            inline_keyboard.push([{ text: 'Other...', callback_data: `hl:other:${promptId}` }]);
+        }
+        if (question?.allowEmpty) {
+            inline_keyboard.push([{ text: 'Skip', callback_data: `hl:skip:${promptId}` }]);
+        }
+        inline_keyboard.push([{ text: 'Cancel', callback_data: `hl:cancel:${promptId}` }]);
+        return { inline_keyboard };
+    }
+    async refreshHumanLoopPrompt(chatId, promptId, opts = {}) {
+        const prompt = this.humanLoopPrompt(promptId);
+        if (!prompt)
+            return;
+        const messageId = prompt.messageIds[0];
+        if (typeof messageId !== 'number')
+            return;
+        const html = `${buildHumanLoopPromptHtml(prompt)}${opts.suffix ? `\n\n<i>${escapeHtml(opts.suffix)}</i>` : ''}`;
+        await this.channel.editMessage(chatId, messageId, html, {
+            parseMode: 'HTML',
+            keyboard: opts.submitted ? { inline_keyboard: [] } : this.buildHumanLoopKeyboard(promptId),
+        }).catch(() => { });
+    }
+    async finalizeHumanLoopPrompt(prompt, suffix) {
+        if (!prompt)
+            return;
+        const messageId = prompt.messageIds[0];
+        if (typeof messageId !== 'number')
+            return;
+        const html = `${buildHumanLoopPromptHtml(prompt)}\n\n<i>${escapeHtml(suffix)}</i>`;
+        await this.channel.editMessage(prompt.chatId, messageId, html, {
+            parseMode: 'HTML',
+            keyboard: { inline_keyboard: [] },
+        }).catch(() => { });
+    }
+    createCodexHumanLoopHandler(ctx, taskId, messageThreadId) {
+        return async (request) => {
+            const blueprint = buildCodexHumanLoopPrompt(request);
+            const active = this.beginHumanLoopPrompt({
+                taskId,
+                chatId: ctx.chatId,
+                ...blueprint,
+            });
+            try {
+                const sent = await ctx.reply(buildHumanLoopPromptHtml(active.prompt), {
+                    parseMode: 'HTML',
+                    messageThreadId,
+                    keyboard: this.buildHumanLoopKeyboard(active.prompt.promptId),
+                });
+                if (typeof sent === 'number')
+                    this.registerHumanLoopMessage(active.prompt.promptId, sent);
+            }
+            catch (error) {
+                this.humanLoopCancel(active.prompt.promptId, error?.message || 'Failed to send prompt.');
+                throw error;
+            }
+            return active.result;
+        };
+    }
     // ---- streaming bridge -----------------------------------------------------
     async handleMessage(msg, ctx) {
         const text = msg.text.trim();
         if (!text && !msg.files.length)
             return;
+        const pendingPrompt = this.pendingHumanLoopPrompt(ctx.chatId);
+        if (pendingPrompt && text && !msg.files.length && !text.startsWith('/')) {
+            const result = this.humanLoopSubmitText(ctx.chatId, text);
+            if (!result) {
+                await ctx.reply('Please answer the active prompt using the buttons above.');
+                return;
+            }
+            if (result.completed)
+                await this.finalizeHumanLoopPrompt(result.prompt, 'Answer submitted.');
+            else
+                await this.refreshHumanLoopPrompt(ctx.chatId, result.prompt.promptId);
+            return;
+        }
         const session = this.resolveIncomingSession(ctx, text, msg.files);
         const cs = this.chat(ctx.chatId);
         this.applySessionSelection(cs, session);
@@ -472,7 +554,7 @@ export class TelegramBot extends Bot {
                 const mcpSendFile = this.createMcpSendFileCallback(ctx, messageThreadId);
                 const result = await this.runStream(prompt, session, files, (nextText, nextThinking, nextActivity = '', meta, plan) => {
                     livePreview?.update(nextText, nextThinking, nextActivity, meta, plan);
-                }, undefined, mcpSendFile, abortController.signal);
+                }, undefined, mcpSendFile, abortController.signal, this.createCodexHumanLoopHandler(ctx, taskId, messageThreadId));
                 await livePreview?.settle();
                 this.log(`[handleMessage] done agent=${session.agent} ok=${result.ok} session=${result.sessionId || '?'} elapsed=${result.elapsedS.toFixed(1)}s edits=${livePreview?.getEditCount() || 0} ` +
                     `tokens=in:${fmtTokens(result.inputTokens)}/cached:${fmtTokens(result.cachedInputTokens)}/out:${fmtTokens(result.outputTokens)}`);
@@ -659,7 +741,70 @@ export class TelegramBot extends Bot {
         await ctx.answerCallback('Nothing to stop.');
         return true;
     }
+    async handleHumanLoopCallback(data, ctx) {
+        if (!data.startsWith('hl:'))
+            return false;
+        const [, action, promptId, rawIndex] = data.split(':');
+        const prompt = this.humanLoopPrompt(promptId);
+        if (!prompt) {
+            await ctx.answerCallback('This prompt is no longer active.');
+            return true;
+        }
+        if (action === 'cancel') {
+            const cancelled = this.humanLoopCancel(promptId, 'Prompt cancelled from Telegram.');
+            await this.finalizeHumanLoopPrompt(cancelled, 'Cancelled.');
+            await ctx.answerCallback('Cancelled.');
+            return true;
+        }
+        if (action === 'skip') {
+            const result = this.humanLoopSkip(promptId);
+            if (!result) {
+                await ctx.answerCallback('This prompt is no longer active.');
+                return true;
+            }
+            if (result.completed)
+                await this.finalizeHumanLoopPrompt(result.prompt, 'Answer submitted.');
+            else
+                await this.refreshHumanLoopPrompt(ctx.chatId, promptId);
+            await ctx.answerCallback(result.completed ? 'Submitted.' : 'Skipped.');
+            return true;
+        }
+        if (action === 'other') {
+            const result = this.humanLoopSelectOption(promptId, '__other__', { requestFreeform: true });
+            if (!result) {
+                await ctx.answerCallback('This prompt is no longer active.');
+                return true;
+            }
+            await this.refreshHumanLoopPrompt(ctx.chatId, promptId);
+            await ctx.answerCallback('Reply with text to continue.');
+            return true;
+        }
+        if (action === 'o') {
+            const index = Number.parseInt(rawIndex || '', 10);
+            const question = this.humanLoopCurrentQuestion(promptId);
+            const option = Number.isFinite(index) ? question?.options?.[index] : null;
+            if (!option) {
+                await ctx.answerCallback('Option expired.');
+                return true;
+            }
+            const result = this.humanLoopSelectOption(promptId, option.value);
+            if (!result) {
+                await ctx.answerCallback('This prompt is no longer active.');
+                return true;
+            }
+            if (result.completed)
+                await this.finalizeHumanLoopPrompt(result.prompt, 'Answer submitted.');
+            else
+                await this.refreshHumanLoopPrompt(ctx.chatId, promptId);
+            await ctx.answerCallback(result.completed ? 'Submitted.' : 'Recorded.');
+            return true;
+        }
+        await ctx.answerCallback();
+        return true;
+    }
     async handleCallback(data, ctx) {
+        if (await this.handleHumanLoopCallback(data, ctx))
+            return;
         if (await this.handleTaskStopCallback(data, ctx))
             return;
         if (await this.handleSwitchNavigateCallback(data, ctx))