@foxden-app/foxclaw 0.5.31 → 0.5.33

package/dist/main.js

@@ -11,6 +11,7 @@ import { APP_HOME, DEFAULT_CODEX_TELEGRAM_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PA
 import { createAuthRefreshNotificationAggregator, } from './auth/notifications.js';
 import { acquireProcessLock, LockHeldError } from './lock.js';
 import { readRuntimeStatus, writeRuntimeStatus } from './runtime.js';
+import { buildFoxclawLaunchdPlistText, extractNodePathFromLaunchdPlist, } from './launchd.js';
 import { buildFoxclawSystemdUnitText, buildSystemdRestartHelperArgs, cgroupContainsSystemdUnit, refreshFoxclawExecStartDropIns, removeFoxclawExecStartDropIns, } from './systemd.js';
 import { createSelfUpdateRuntime, inferPnpmHomeFromEntryPoint, performSelfUpdate, readSelfUpdateStatus, writeSelfUpdateStatus, } from './update.js';
 const rawCommand = process.argv[2];
@@ -113,6 +114,10 @@ async function main() {
         uninstallSystemd();
         return;
     }
+    if (command === 'uninstall-launchd') {
+        uninstallLaunchd();
+        return;
+    }
     if (command === 'install-launchd') {
         requireNode24(command);
         installLaunchd();
@@ -173,7 +178,7 @@ Usage:
   foxclaw start|restart|stop
   foxclaw update
   foxclaw install-systemd|uninstall-systemd
-  foxclaw install-launchd
+  foxclaw install-launchd|uninstall-launchd
   foxclaw weixin-login [account-id]
   foxclaw --version
   foxclaw --help`);
@@ -1344,6 +1349,7 @@ function runDoctorChecks() {
     warnIfProxyEnvMissingFromLoadedEnv();
     warnIfProxyConfigNeedsAttention();
     warnIfInstalledServiceNodeLooksWrong();
+    warnIfInstalledLaunchdNodeLooksWrong();
     warnIfSystemdUserLingerDisabled();
     return passed;
 }
@@ -1373,7 +1379,12 @@ function warnIfProxyConfigNeedsAttention() {
         return;
     }
     console.log('[WARN] Only ALL_PROXY/all_proxy is configured. Node service proxying works best with HTTP_PROXY/HTTPS_PROXY.');
-    console.log('[WARN] For SOCKS-only hosts, set FOXCLAW_PROXYCHAINS_CONF=/absolute/path/to/proxychains.conf and run foxclaw restart.');
+    if (process.platform === 'linux') {
+        console.log('[WARN] For SOCKS-only hosts, set FOXCLAW_PROXYCHAINS_CONF=/absolute/path/to/proxychains.conf and run foxclaw restart.');
+    }
+    else {
+        console.log('[WARN] On macOS launchd, prefer HTTP_PROXY/HTTPS_PROXY; FOXCLAW_PROXYCHAINS_CONF is Linux-only.');
+    }
 }
 function warnIfProxyEnvMissingFromLoadedEnv() {
     const envPath = serviceEnvPath();
@@ -1417,6 +1428,37 @@ function warnIfInstalledServiceNodeLooksWrong() {
     console.log(`[WARN] installed service node is older than 24: ${nodePath}${version ? ` (${version})` : ''}`);
     console.log('[WARN] Run foxclaw start from a Node 24 shell to refresh the service unit.');
 }
+function warnIfInstalledLaunchdNodeLooksWrong() {
+    if (process.platform !== 'darwin') {
+        return;
+    }
+    const plistPath = launchdPlistPath();
+    let text = '';
+    try {
+        text = fs.readFileSync(plistPath, 'utf8');
+    }
+    catch {
+        return;
+    }
+    const nodePath = extractNodePathFromLaunchdPlist(text);
+    if (!nodePath) {
+        return;
+    }
+    if (!fs.existsSync(nodePath)) {
+        console.log(`[WARN] installed launchd node is missing: ${nodePath}`);
+        console.log('[WARN] Run foxclaw start from a Node 24 shell to refresh the launchd plist.');
+        return;
+    }
+    const result = spawnSync(nodePath, ['-p', 'process.versions.node'], { encoding: 'utf8' });
+    const version = result.status === 0 ? result.stdout.trim() : '';
+    const major = Number.parseInt(version.split('.')[0] ?? '', 10);
+    if (Number.isFinite(major) && major >= 24) {
+        console.log(`[OK] launchd node >= 24: ${nodePath}`);
+        return;
+    }
+    console.log(`[WARN] installed launchd node is older than 24: ${nodePath}${version ? ` (${version})` : ''}`);
+    console.log('[WARN] Run foxclaw start from a Node 24 shell to refresh the launchd plist.');
+}
 function warnIfSystemdUserLingerDisabled() {
     if (process.platform !== 'linux' || !hasCommand('loginctl')) {
         return;
@@ -1588,54 +1630,28 @@ function installLaunchd() {
         process.exit(1);
     }
     const home = process.env.HOME || '';
-    const plist = path.join(home, 'Library', 'LaunchAgents', 'app.foxden.foxclaw.plist');
+    const plist = launchdPlistPath();
     const envPath = serviceEnvPath();
     const configDir = path.dirname(envPath);
     const nodeProxyArgs = hasStandardNodeProxyEnv() ? ['--use-env-proxy'] : [];
-    const nodeProxyArgXml = nodeProxyArgs.map((arg) => `    <string>${xmlEscape(arg)}</string>`).join('\n');
-    const proxyEnvXml = buildLaunchdProxyEnvironmentXml();
     fs.mkdirSync(path.dirname(plist), { recursive: true });
     fs.mkdirSync(configDir, { recursive: true });
     fs.mkdirSync(path.join(APP_HOME, 'logs'), { recursive: true });
-    fs.writeFileSync(plist, `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>app.foxden.foxclaw</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>${xmlEscape(process.execPath)}</string>
-${nodeProxyArgXml ? `${nodeProxyArgXml}\n` : ''}    <string>${xmlEscape(entryPoint)}</string>
-    <string>serve</string>
-  </array>
-  <key>WorkingDirectory</key>
-  <string>${xmlEscape(configDir)}</string>
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>PATH</key>
-    <string>${xmlEscape(process.env.PATH || '')}</string>
-    <key>HOME</key>
-    <string>${xmlEscape(home)}</string>
-    <key>USER</key>
-    <string>${xmlEscape(process.env.USER || '')}</string>
-    <key>LOGNAME</key>
-    <string>${xmlEscape(process.env.LOGNAME || process.env.USER || '')}</string>
-    <key>FOXCLAW_ENV</key>
-    <string>${xmlEscape(envPath)}</string>
-${proxyEnvXml}
-  </dict>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <true/>
-  <key>StandardOutPath</key>
-  <string>${xmlEscape(path.join(APP_HOME, 'logs', 'launchd.out.log'))}</string>
-  <key>StandardErrorPath</key>
-  <string>${xmlEscape(path.join(APP_HOME, 'logs', 'launchd.err.log'))}</string>
-</dict>
-</plist>
-`);
+    fs.writeFileSync(plist, buildFoxclawLaunchdPlistText({
+        label: 'app.foxden.foxclaw',
+        nodePath: process.execPath,
+        nodeArgs: nodeProxyArgs,
+        entryPoint,
+        workingDirectory: configDir,
+        pathValue: process.env.PATH || '',
+        home,
+        user: process.env.USER || '',
+        logname: process.env.LOGNAME || process.env.USER || '',
+        envPath,
+        proxyEnv: launchdProxyEnvironment(),
+        stdoutPath: path.join(APP_HOME, 'logs', 'launchd.out.log'),
+        stderrPath: path.join(APP_HOME, 'logs', 'launchd.err.log'),
+    }));
     spawnSync('launchctl', ['unload', plist], { stdio: 'ignore' });
     spawnChecked('launchctl', ['load', plist]);
     console.log(`Installed ${plist}`);
@@ -1648,7 +1664,7 @@ function stopLaunchd() {
         console.error('launchd stop is only available on macOS');
         process.exit(1);
     }
-    const plist = path.join(process.env.HOME || '', 'Library', 'LaunchAgents', 'app.foxden.foxclaw.plist');
+    const plist = launchdPlistPath();
     if (!fs.existsSync(plist)) {
         console.error(`launchd plist not found: ${plist}`);
         process.exit(1);
@@ -1656,6 +1672,19 @@ function stopLaunchd() {
     spawnChecked('launchctl', ['unload', plist]);
     console.log(`Stopped ${plist}`);
 }
+function uninstallLaunchd() {
+    if (process.platform !== 'darwin') {
+        console.error('launchd uninstall is only available on macOS');
+        process.exit(1);
+    }
+    const plist = launchdPlistPath();
+    spawnSync('launchctl', ['unload', plist], { stdio: 'ignore' });
+    fs.rmSync(plist, { force: true });
+    console.log(`Removed ${plist}`);
+}
+function launchdPlistPath() {
+    return path.join(process.env.HOME || '', 'Library', 'LaunchAgents', 'app.foxden.foxclaw.plist');
+}
 function buildServicePath(nodeDir) {
     const pnpmPath = resolveCommand('pnpm');
     const inferredPnpmHome = inferPnpmHomeFromEntryPoint(entryPoint) || '';
@@ -1716,16 +1745,15 @@ function hasStandardNodeProxyEnv() {
 function proxyEnvValue(key) {
     return process.env[key]?.trim() || '';
 }
-function buildLaunchdProxyEnvironmentXml() {
-    const entries = [];
+function launchdProxyEnvironment() {
+    const entries = {};
     for (const key of PROXY_ENV_KEYS) {
         const value = proxyEnvValue(key);
         if (!value)
             continue;
-        entries.push(`    <key>${xmlEscape(key)}</key>`);
-        entries.push(`    <string>${xmlEscape(value)}</string>`);
+        entries[key] = value;
     }
-    return entries.length > 0 ? `${entries.join('\n')}\n` : '';
+    return entries;
 }
 function spawnChecked(commandName, args) {
     const result = spawnSync(commandName, args, { stdio: 'inherit' });
@@ -1739,14 +1767,6 @@ function systemdEscape(value) {
 function systemdUnescape(value) {
     return value.replace(/\\x20/g, ' ').replace(/\\\\/g, '\\');
 }
-function xmlEscape(value) {
-    return value
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&apos;');
-}
 async function runWeixinLoginCli() {
     const [{ attachIlinkRuntimeFromBridgeLogger }, { startWeixinLoginWithQr, waitForWeixinLogin }, { accountFilePath, saveWeixinAccount }, { Logger },] = await Promise.all([
         import('./channels/weixin/ilink/runtime_attach.js'),

package/dist/telegram/gateway.d.ts

@@ -4,6 +4,7 @@ import type { BridgeStore } from '../store/database.js';
 import type { Logger } from '../logger.js';
 import type { TelegramMessageEntity } from './addressing.js';
 import type { TelegramInboundAttachment } from './media.js';
+import type { TelegramInputRichMessage } from './rich.js';
 export interface TelegramTextEvent {
     chatId: string;
     topicId: number | null;
@@ -62,8 +63,13 @@ export declare class TelegramGateway extends EventEmitter {
         text: string;
         callback_data: string;
     }>>, messageThreadId?: number | null): Promise<number>;
+    sendRichMessage(chatId: string, richMessage: TelegramInputRichMessage, inlineKeyboard?: Array<Array<{
+        text: string;
+        callback_data: string;
+    }>>, messageThreadId?: number | null): Promise<number>;
     sendDocument(chatId: string, filename: string, contents: Buffer, caption?: string): Promise<number>;
     sendMessageDraft(chatId: string, draftId: number, text: string, messageThreadId?: number | null): Promise<void>;
+    sendRichMessageDraft(chatId: string, draftId: number, richMessage: TelegramInputRichMessage, messageThreadId?: number | null): Promise<void>;
     editMessage(chatId: string, messageId: number, text: string, inlineKeyboard?: Array<Array<{
         text: string;
         callback_data: string;
@@ -72,6 +78,10 @@ export declare class TelegramGateway extends EventEmitter {
         text: string;
         callback_data: string;
     }>>): Promise<void>;
+    editRichMessage(chatId: string, messageId: number, richMessage: TelegramInputRichMessage, inlineKeyboard?: Array<Array<{
+        text: string;
+        callback_data: string;
+    }>>): Promise<void>;
     clearMessageInlineKeyboard(chatId: string, messageId: number): Promise<void>;
     private sendMessageWithOptions;
     private editMessageWithOptions;

package/dist/telegram/gateway.js

@@ -56,6 +56,18 @@ export class TelegramGateway extends EventEmitter {
     async sendHtmlMessage(chatId, text, inlineKeyboard, messageThreadId) {
         return this.sendMessageWithOptions(chatId, text, inlineKeyboard, 'HTML', messageThreadId);
     }
+    async sendRichMessage(chatId, richMessage, inlineKeyboard, messageThreadId) {
+        const result = await callTelegramApi(this.botToken, 'sendRichMessage', {
+            chat_id: chatId,
+            rich_message: richMessage,
+            ...(messageThreadId !== null && messageThreadId !== undefined ? { message_thread_id: messageThreadId } : {}),
+            ...(inlineKeyboard ? { reply_markup: { inline_keyboard: inlineKeyboard } } : {}),
+        });
+        if (!result.ok || !result.result) {
+            throw new Error(result.description || 'Failed to send Telegram rich message');
+        }
+        return result.result.message_id;
+    }
     async sendDocument(chatId, filename, contents, caption) {
         const result = await callTelegramMultipartApi(this.botToken, 'sendDocument', {
             chat_id: chatId,
@@ -83,12 +95,34 @@ export class TelegramGateway extends EventEmitter {
             throw new Error(result.description || 'Failed to send Telegram draft message');
         }
     }
+    async sendRichMessageDraft(chatId, draftId, richMessage, messageThreadId) {
+        const result = await callTelegramApi(this.botToken, 'sendRichMessageDraft', {
+            chat_id: chatId,
+            draft_id: draftId,
+            rich_message: richMessage,
+            ...(messageThreadId !== null && messageThreadId !== undefined ? { message_thread_id: messageThreadId } : {}),
+        });
+        if (!result.ok) {
+            throw new Error(result.description || 'Failed to send Telegram rich draft message');
+        }
+    }
     async editMessage(chatId, messageId, text, inlineKeyboard) {
         return this.editMessageWithOptions(chatId, messageId, text, inlineKeyboard);
     }
     async editHtmlMessage(chatId, messageId, text, inlineKeyboard) {
         return this.editMessageWithOptions(chatId, messageId, text, inlineKeyboard, 'HTML');
     }
+    async editRichMessage(chatId, messageId, richMessage, inlineKeyboard) {
+        const result = await callTelegramApi(this.botToken, 'editMessageText', {
+            chat_id: chatId,
+            message_id: messageId,
+            rich_message: richMessage,
+            ...(inlineKeyboard ? { reply_markup: { inline_keyboard: inlineKeyboard } } : {}),
+        });
+        if (!result.ok && !String(result.description || '').includes('message is not modified')) {
+            throw new Error(result.description || 'Failed to edit Telegram rich message');
+        }
+    }
     async clearMessageInlineKeyboard(chatId, messageId) {
         const result = await callTelegramApi(this.botToken, 'editMessageReplyMarkup', {
             chat_id: chatId,

package/dist/telegram/html.d.ts

@@ -0,0 +1,8 @@
+export declare function escapeTelegramHtml(value: string): string;
+export declare function telegramBold(value: string): string;
+export declare function telegramCode(value: string): string;
+export declare function telegramPre(value: string): string;
+export declare function telegramPreCode(value: string, language?: string): string;
+export declare function telegramExpandableBlockquote(value: string): string;
+export declare function telegramSpoiler(value: string): string;
+export declare function telegramDetails(summary: string, bodyHtml: string, open?: boolean): string;

package/dist/telegram/html.js

@@ -0,0 +1,31 @@
+export function escapeTelegramHtml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}
+function escapeTelegramHtmlAttribute(value) {
+    return escapeTelegramHtml(value).replaceAll('"', '&quot;');
+}
+export function telegramBold(value) {
+    return `<b>${escapeTelegramHtml(value)}</b>`;
+}
+export function telegramCode(value) {
+    return `<code>${escapeTelegramHtml(value)}</code>`;
+}
+export function telegramPre(value) {
+    return `<pre>${escapeTelegramHtml(value)}</pre>`;
+}
+export function telegramPreCode(value, language) {
+    const classAttr = language ? ` class="language-${escapeTelegramHtmlAttribute(language)}"` : '';
+    return `<pre><code${classAttr}>${escapeTelegramHtml(value)}</code></pre>`;
+}
+export function telegramExpandableBlockquote(value) {
+    return `<blockquote expandable>${escapeTelegramHtml(value)}</blockquote>`;
+}
+export function telegramSpoiler(value) {
+    return `<tg-spoiler>${escapeTelegramHtml(value)}</tg-spoiler>`;
+}
+export function telegramDetails(summary, bodyHtml, open = false) {
+    return `<details${open ? ' open' : ''}><summary>${escapeTelegramHtml(summary)}</summary>${bodyHtml}</details>`;
+}

package/dist/telegram/rich.d.ts

@@ -0,0 +1,13 @@
+export declare const TELEGRAM_RICH_MESSAGE_TEXT_LIMIT = 32768;
+export declare const TELEGRAM_RICH_MESSAGE_BLOCK_LIMIT = 500;
+export interface TelegramInputRichMessage {
+    html?: string;
+    markdown?: string;
+    is_rtl?: true;
+    skip_entity_detection?: true;
+}
+export interface TelegramRichMessageOptions {
+    isRtl?: boolean;
+    skipEntityDetection?: boolean;
+}
+export declare function telegramRichHtml(html: string, options?: TelegramRichMessageOptions): TelegramInputRichMessage;

package/dist/telegram/rich.js

@@ -0,0 +1,12 @@
+export const TELEGRAM_RICH_MESSAGE_TEXT_LIMIT = 32_768;
+export const TELEGRAM_RICH_MESSAGE_BLOCK_LIMIT = 500;
+export function telegramRichHtml(html, options = {}) {
+    const message = { html };
+    if (options.isRtl) {
+        message.is_rtl = true;
+    }
+    if (options.skipEntityDetection) {
+        message.skip_entity_detection = true;
+    }
+    return message;
+}

package/docs/agent-assisted-install.md

@@ -48,6 +48,7 @@ Tasks:
 8. Ask me to send /help, /status, and /auth privately to each configured Telegram bot; confirm /auth names that bot runtime.
 9. Verify the final state:
    - foxclaw.service is active/enabled on Linux
+   - the app.foxden.foxclaw launchd job is loaded on macOS, with no startup errors in ~/.foxclaw/logs/launchd.err.log
    - foxclaw status works
 10. Report the commands used, the final status, and the log command I should use if something stops working. Redact TG_BOT_TOKENS and never print the full token or full .env content.
 11. If multiple bots are enabled, confirm foxclaw status lists independent app-servers; group-chat tests must mention or reply to the intended bot.

package/docs/install-for-beginners.md

@@ -263,7 +263,12 @@ If install reports that linger could not be enabled automatically, run:
 sudo loginctl enable-linger "$USER"
 ```
 
-On macOS, `foxclaw start` manages launchd and starts FoxClaw when you log in.
+On macOS, `foxclaw start` manages launchd and starts FoxClaw when you log in. Check state and startup logs with:
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
 
 For foreground debugging, stop the service first and then run `foxclaw serve`.
 
@@ -275,7 +280,7 @@ Check current status:
 foxclaw status
 ```
 
-Restart Linux service after changing `.env`:
+Restart after changing `.env`:
 
 ```bash
 foxclaw restart
@@ -293,6 +298,12 @@ Uninstall Linux service:
 foxclaw uninstall-systemd
 ```
 
+Uninstall macOS launchd service:
+
+```bash
+foxclaw uninstall-launchd
+```
+
 Update FoxClaw later:
 
 ```bash

package/docs/telegram-rich-messages.md

@@ -0,0 +1,99 @@
+# Telegram Rich Message Adaptation Check
+
+Checked on 2026-06-16 against Telegram Bot API Rich Messages, especially `RichMessage`, `sendRichMessage`, `sendRichMessageDraft`, and Rich Message Formatting Options.
+
+Official references:
+
+- https://core.telegram.org/bots/api#rich-message-formatting-options
+- https://core.telegram.org/bots/api#sendrichmessage
+- https://core.telegram.org/bots/api#sendrichmessagedraft
+
+## Conclusion
+
+FoxClaw can benefit from the new rich message surface, and RichMessage is now wired into Telegram surfaces that are easy to inspect and safe to fall back.
+
+The current strategy is to try `sendRichMessage` first on Telegram, then fall back to the existing Telegram HTML path on failure. Weixin continues to use HTML/plain fallback. Bot API 10.1 Rich Messages start with diagnostics and structured long text, then can expand to status, auth/quota, and AI draft streaming.
+
+Already landed in this pass:
+
+- Added `src/telegram/html.ts` for centralized Telegram HTML escaping and tag helpers.
+- Added `src/telegram/rich.ts` and wired `sendRichMessage` / rich HTML through `TelegramGateway`, `TelegramMessagingPort`, and `BridgeMessagingRouter`.
+- Added `/rich` as a diagnostic command for checking heading, table, details, pre/code, and list rendering in a real Telegram client.
+- Changed `/diff` to prefer RichMessage with a heading plus details/pre/code diff block, falling back to HTML bold title plus expandable quote body.
+- Moved existing CLI observation and archived tool-batch HTML generation onto the shared helper.
+
+## Official Capability
+
+Bot API 10.1 adds Rich Messages:
+
+- `RichText*`: bold, italic, underline, strikethrough, spoiler, code, marked, math, URL, email, phone, mention, hashtag, bot command, anchors, and references.
+- `RichBlock*`: paragraph, heading, preformatted, footer, divider, math block, anchor, list, block quote, pull quote, collage, slideshow, table, details, map, media blocks, and thinking.
+- `sendRichMessage`: sends a complete rich message.
+- `sendRichMessageDraft`: streams an ephemeral partial rich message in private chat; the final answer must still be persisted with `sendRichMessage`.
+- `editMessageText` accepts `rich_message` for editing rich messages.
+
+Rich Message HTML also supports tags such as `<details>`, `<table>`, `<pre><code class="language-...">`, `<ul>/<ol>`, `<hr/>`, `<tg-math-block>`, and `<tg-thinking>`. `RichBlockThinking` is draft-only.
+
+## FoxClaw Inventory
+
+Current Telegram send layer:
+
+- `src/telegram/gateway.ts`: plain/html/rich send and edit are wired; regular HTML uses `parse_mode=HTML`, while rich messages use `rich_message.html`.
+- `src/channels/telegram/telegram_messaging_port.ts`: controller-facing plain/html/rich-html send/edit and text draft operations.
+- `src/telegram/rendering.ts`: `segmented_stream` is the default; `draft_stream` still uses the old text draft path.
+- `src/controller/controller.ts`: central dispatcher for status cards, approvals, tool batches, diffs, auth, MCP, plugins, files, and runtime summaries.
+- `src/controller/presentation.ts`: `/threads`, `/setup`, model, and access panels already use Telegram HTML.
+
+Useful mapping:
+
+| Surface | Current state | Useful rich capabilities | Recommendation |
+| --- | --- | --- | --- |
+| Active turn status | Short plain text, frequent edits | heading, list, thinking draft | Keep stable; use `RichBlockThinking` later only for private draft streaming |
+| Codex streaming replies | Segmented plain text | rich draft, paragraph, pre, details | Feature flag only; needs fallback |
+| Archived tool batches | Expandable HTML quote | details, pre, list | Keep HTML now; later use rich details |
+| `/diff` | RichMessage first, HTML fallback | pre language, details | Landed |
+| Approvals | Plain text plus inline keyboard | code, pre, spoiler, details | Command/path/patch fit code/pre/details; sensitive params should be hidden |
+| `/status` and runtime summaries | Plain text lists | table, heading, footer | Good candidate for rich tables |
+| `/auth` and `/quota` | Compact text plus buttons | table, marked, spoiler | Quota windows fit tables; abnormal candidates fit marked text |
+| `/threads` and `/setup` | HTML panels | heading, list, anchor | Current HTML is enough; medium priority |
+| MCP resources and plugin skills | Long plain text | details, pre, anchor/reference | Good candidate for collapsible schema/resource blocks |
+| Help and setup text | Plain text | heading, list, code | Low priority |
+| Media attachment feedback | Plain summary | collage/slideshow/media captions | Use only if FoxClaw starts returning media previews |
+
+## Rollout Plan
+
+Phase 1: HTML-compatible enhancement.
+
+- Centralize Telegram HTML helpers.
+- Collapse long content by default: diffs, tool logs, MCP resources, plugin skill contents.
+- Render commands, paths, models, and candidate names as code.
+- Use spoilers or omission for secret/token-like diagnostics.
+
+Phase 2: Rich Message builder.
+
+Done:
+
+- Added a minimal typed `src/telegram/rich.ts`.
+- Added `sendRichMessage`, `editRichMessage`, and `sendRichMessageDraft` to `TelegramGateway`.
+- Added rich HTML send/edit to `TelegramMessagingPort` and `BridgeMessagingRouter`; Weixin scopes use fallback HTML.
+- `/rich` and `/diff` use rich sending first and fall back to HTML.
+
+Next:
+
+- Move `/status`, `/auth`, `/quota`, and MCP resources to rich table/details.
+- Decide whether a global config flag is needed after real Telegram client checks.
+
+Phase 3: Rich draft streaming.
+
+- Enable only in Telegram private chats first; keep group/topic rendering on the current segmented stream.
+- Use `RichBlockThinking` while generating and paragraph/pre/details for partial output.
+- Persist the final answer with `sendRichMessage`.
+- Keep the old text draft and segmented stream as fallback paths.
+
+## Risks
+
+- Rich Messages landed in Bot API 10.1 on 2026-06-11, so client compatibility should be checked with `/rich` and `/diff`.
+- `sendRichMessageDraft` targets private users; group, topic, and multi-bot paths must keep existing rendering.
+- Rich media blocks add bot permission and media URL/upload constraints; they are not a Phase 1 target.
+- Automatic entity detection can mis-detect paths, emails, URLs, and commands; rich builders should choose `skip_entity_detection` per message type.
+- All Codex, shell, and file output must pass through centralized escaping before entering HTML/rich markup.

package/docs/troubleshooting.md

@@ -14,6 +14,13 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
+If FoxClaw is installed as a macOS launchd service, check:
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
+
 ## Doctor Failures
 
 | Symptom | Meaning | Fix |
@@ -136,6 +143,13 @@ systemctl --user is-active foxclaw.service
 pgrep -af foxclaw
 ```
 
+On macOS, use:
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+pgrep -af foxclaw
+```
+
 Stop the extra process or service, then restart FoxClaw:
 
 ```bash
@@ -200,12 +214,18 @@ When multiple bots share a group, unaddressed messages intentionally do not trig
 
 If Telegram shows `ChatGPT backend 403 Forbidden`, or the app-server log contains `Unable to load site`, `cf-ray`, or `chatgpt.com/backend-api`, the auth file is not necessarily broken. The service process is usually reaching ChatGPT with the wrong network/proxy/IP.
 
-A common cause is that your shell or project `.env` has proxy variables, while the systemd/launchd service reads a different env file. Check the env file installed into the service:
+A common cause is that your shell or project `.env` has proxy variables, while the systemd/launchd service reads a different env file. On Linux, check the env file installed into the service:
 
 ```bash
 systemctl --user cat foxclaw.service
 ```
 
+On macOS, inspect `FOXCLAW_ENV` in the launchd plist:
+
+```bash
+plutil -p ~/Library/LaunchAgents/app.foxden.foxclaw.plist | grep FOXCLAW_ENV -A1
+```
+
 `foxclaw init` detects proxy environment variables in the current shell and asks whether to save them into the FoxClaw `.env`. If you skipped that step, `foxclaw doctor` warns when it sees proxy variables in the shell but not in the FoxClaw env file.
 
 Make sure the file referenced by `Environment=FOXCLAW_ENV=...` contains your proxy variables, for example:
@@ -243,6 +263,8 @@ FoxClaw writes proxychains into the main service and removes stale FoxClaw `Exec
 
 The systemd installer records the absolute path of the Node process that is currently running FoxClaw. It does not rely on systemd loading `nvm.sh` or any other shell init script. Whether you use nvm, fnm, asdf, mise, Volta, Homebrew, or system Node, run `foxclaw start` from a Node 24+ shell and the service will keep using that Node 24+ path.
 
+macOS launchd follows the same rule: the plist records the absolute Node path that ran `foxclaw start` and does not rely on login-shell initialization.
+
 If you installed the service from a shell using Node 22 or older, reinstall it from a Node 24+ shell. Example for nvm users:
 
 ```bash
@@ -251,7 +273,15 @@ foxclaw start
 systemctl --user status foxclaw.service
 ```
 
-The status output should show a Node 24+ path in `ExecStart`. `foxclaw doctor` also checks the installed service Node path and warns if it is missing or older than 24.
+On macOS:
+
+```bash
+nvm use 24
+foxclaw start
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+```
+
+The status output should show a Node 24+ path. `foxclaw doctor` also checks the installed systemd/launchd service Node path and warns if it is missing or older than 24.
 
 ## Does It Run After Reboot?
 

package/docs/user-manual.md

@@ -145,7 +145,14 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
-On macOS, `foxclaw start` manages launchd. For foreground debugging, stop the background service and run:
+On macOS, `foxclaw start` manages launchd. Check launchd state and startup logs with:
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
+
+For foreground debugging, stop the background service and run:
 
 ```bash
 foxclaw stop
@@ -258,6 +265,10 @@ It controls:
 
 Telegram renders the HTML and buttons. This text block approximates the real panel:
 
+For the Telegram Rich Message inventory and rollout plan, see [Telegram Rich Message Adaptation Check](./telegram-rich-messages.md). The default path still favors Telegram HTML for compatibility.
+
+Send `/rich` to view a RichMessage demo in the current Telegram client. `/diff` also prefers RichMessage details plus a diff code block, with automatic Telegram HTML fallback.
+
 ```text
 Session preferences
 Current: gpt-5.5 · high · fast=off · default · Agent · Steer current turn

package/docs/zh/agent-assisted-install.md

@@ -47,6 +47,7 @@ DEFAULT_CWD=<把绝对工作目录粘贴在这里>
 8. 让我在每个已配置的 Telegram bot 私聊里发送 /help、/status 和 /auth；确认 /auth 显示对应 bot runtime。
 9. 验证最终状态：
    - Linux 上 foxclaw.service 处于 active/enabled
+   - macOS 上 app.foxden.foxclaw launchd job 已加载，并且 ~/.foxclaw/logs/launchd.err.log 没有启动错误
    - foxclaw status 可以正常输出
 10. 汇报执行过的命令、最终状态和后续看日志的命令。请隐藏 TG_BOT_TOKENS，不要打印完整 token 或完整 .env。
 11. 如果启用了多个 bot，确认 foxclaw status 列出独立 app-server；群聊测试必须点名或回复目标 bot。

package/docs/zh/install-for-beginners.md

@@ -261,7 +261,12 @@ journalctl --user -u foxclaw.service -f
 sudo loginctl enable-linger "$USER"
 ```
 
-macOS 上 `foxclaw start` 管理 launchd，并在你登录后启动 FoxClaw。
+macOS 上 `foxclaw start` 管理 launchd，并在你登录后启动 FoxClaw。查看状态和启动日志：
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
 
 前台调试时，先停后台服务，再运行 `foxclaw serve`。
 
@@ -291,6 +296,12 @@ foxclaw stop
 foxclaw uninstall-systemd
 ```
 
+卸载 macOS launchd 服务：
+
+```bash
+foxclaw uninstall-launchd
+```
+
 以后升级 FoxClaw：
 
 ```bash