@ihazz/bitrix24 0.1.6 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ihazz/bitrix24",
-  "version": "0.1.6",
+  "version": "0.2.2",
   "description": "Bitrix24 Messenger channel for OpenClaw",
   "type": "module",
   "main": "./dist/index.js",

package/src/api.ts

@@ -307,6 +307,18 @@ export class Bitrix24Api {
     return result.result;
   }
 
+  async getFileInfoViaWebhook(
+    webhookUrl: string,
+    fileId: number,
+  ): Promise<{ DOWNLOAD_URL: string; [key: string]: unknown }> {
+    const result = await this.callWebhook<{ DOWNLOAD_URL: string; [key: string]: unknown }>(
+      webhookUrl,
+      'disk.file.get',
+      { id: fileId },
+    );
+    return result.result;
+  }
+
   /**
    * Get the disk folder ID for a chat (needed for file uploads).
    */

package/src/channel.ts

@@ -38,6 +38,40 @@ interface GatewayState {
 
 let gatewayState: GatewayState | null = null;
 
+// ─── i18n helpers ────────────────────────────────────────────────────────────
+
+const I18N_MEDIA_DOWNLOAD_FAILED: Record<string, (files: string) => string> = {
+  en: (f) => `⚠️ Could not download file(s): ${f}.\n\nFile processing is currently only available for the primary user (webhook owner). This limitation will be removed in a future release.`,
+  ru: (f) => `⚠️ Не удалось загрузить файл(ы): ${f}.\n\nОбработка файлов пока доступна только для основного пользователя (автора вебхука). В будущих версиях это ограничение будет снято.`,
+  de: (f) => `⚠️ Datei(en) konnten nicht heruntergeladen werden: ${f}.\n\nDateiverarbeitung ist derzeit nur für den Hauptbenutzer (Webhook-Besitzer) verfügbar. Diese Einschränkung wird in einer zukünftigen Version behoben.`,
+  es: (f) => `⚠️ No se pudo descargar el/los archivo(s): ${f}.\n\nEl procesamiento de archivos actualmente solo está disponible para el usuario principal (propietario del webhook). Esta limitación se eliminará en una versión futura.`,
+  fr: (f) => `⚠️ Impossible de télécharger le(s) fichier(s) : ${f}.\n\nLe traitement des fichiers est actuellement réservé à l'utilisateur principal (propriétaire du webhook). Cette limitation sera levée dans une prochaine version.`,
+  pt: (f) => `⚠️ Não foi possível baixar o(s) arquivo(s): ${f}.\n\nO processamento de arquivos está disponível apenas para o usuário principal (dono do webhook). Essa limitação será removida em uma versão futura.`,
+};
+
+function mediaDownloadFailedMsg(lang: string | undefined, fileNames: string): string {
+  const code = (lang ?? 'en').toLowerCase().slice(0, 2);
+  const fn = I18N_MEDIA_DOWNLOAD_FAILED[code] ?? I18N_MEDIA_DOWNLOAD_FAILED.en;
+  return fn(fileNames);
+}
+
+// ─── Default bot avatar (64×64 red circle with white "C") ───────────────────
+
+const DEFAULT_AVATAR_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAABp0lEQVR42u1bsa3DIBBNmVlcZgbKNF7BK6TIHG4yi2fwAjS/8AIs4IZAdC5RAtxh+LyTniJFlq33gLsD7i4XGOxU+7vduiA5OEwOs8PioB2Mw+5g6dfQ/ws9558fWiatHF4OG5FMxUbvUS2Qvjo8aCStADS9/1oj+SdNY1sA/jvPWoiPgiP+y4wYT/PetDZtBXgVjSbk1ddKyB9Yi0QN8u5sa90bs29QkuTvOURjLUOIu9TIi5NmFENxr3lzBvEMIQyLTyBvv9ZAPkGENTs6xIS6khYTInOTnKqIJwoxpgqgayYfIYJOze3tPxHARu0daFdnWiAfIYL5eRdJW85myEeI8GBZ+9LTVfD9miXjK5XWCn1HZcX9wjm9yNb5mwAbpwCVkf+cMX7L+dmmZYXkDwwhAaYOyHtMIQHmTgSYQwIsHAJUTt5jEY3/DQigQwKYTgQwIQH2TgTYQyc/PTjAA5gB8AGIAsgDkAliL4DdIM4DcCKEM0GcCuNeADdDuBvE7TDqA1AhghohVImhThCVoqgVRrU4+gXQMYKeIXSNoW8QnaPoHe7F3lyXWKOZrIuJAAAAAElFTkSuQmCC';
+
+// ─── Default command keyboard ────────────────────────────────────────────────
+
+/** Default keyboard shown with command responses and welcome messages. */
+export const DEFAULT_COMMAND_KEYBOARD: B24Keyboard = [
+  { TEXT: 'Help', COMMAND: 'help', BG_COLOR_TOKEN: 'primary', DISPLAY: 'LINE' },
+  { TEXT: 'Status', COMMAND: 'status', DISPLAY: 'LINE' },
+  { TEXT: 'Commands', COMMAND: 'commands', DISPLAY: 'LINE' },
+  { TYPE: 'NEWLINE' },
+  { TEXT: 'New session', COMMAND: 'new', DISPLAY: 'LINE' },
+  { TEXT: 'Models', COMMAND: 'models', DISPLAY: 'LINE' },
+];
+
 // ─── Keyboard / Button conversion ────────────────────────────────────────────
 
 /** Generic button format used by OpenClaw channelData. */
@@ -143,9 +177,16 @@ async function ensureBotRegistered(
 
     if (existing) {
       logger.info(`Bot "${code}" already registered (ID=${existing.ID}), updating EVENT_HANDLER`);
+      const updateProps: Record<string, unknown> = {
+        NAME: name,
+        WORK_POSITION: 'AI Assistant',
+        COLOR: 'RED',
+      };
+      updateProps.PERSONAL_PHOTO = config.botAvatar || DEFAULT_AVATAR_BASE64;
+
       await api.updateBot(webhookUrl, existing.ID, {
         EVENT_HANDLER: callbackUrl,
-        PROPERTIES: { NAME: name },
+        PROPERTIES: updateProps,
       });
       return existing.ID;
     }
@@ -162,7 +203,8 @@ async function ensureBotRegistered(
       PROPERTIES: {
         NAME: name,
         WORK_POSITION: 'AI Assistant',
-        COLOR: 'AZURE',
+        COLOR: 'RED',
+        PERSONAL_PHOTO: config.botAvatar || DEFAULT_AVATAR_BASE64,
       },
     });
     logger.info(`Bot "${code}" registered (ID=${botId})`);
@@ -280,6 +322,7 @@ export const bitrix24Plugin = {
     reactions: false,
     threads: false,
     nativeCommands: true,
+    inlineButtons: 'all',
   },
 
   config: {
@@ -498,6 +541,7 @@ export const bitrix24Plugin = {
                   extension: m.extension,
                   clientEndpoint: msgCtx.clientEndpoint,
                   userToken: msgCtx.userToken,
+                  webhookUrl: config.webhookUrl,
                 }),
               ),
             )).filter(Boolean) as DownloadedMedia[];
@@ -511,6 +555,21 @@ export const bitrix24Plugin = {
                 MediaUrls: downloaded.map((m) => m.path),
                 MediaTypes: downloaded.map((m) => m.contentType),
               };
+            } else {
+              // All file downloads failed — notify the user
+              const fileNames = msgCtx.media.map((m) => m.name).join(', ');
+              logger.warn('All media downloads failed, notifying user', { fileNames });
+              const errSendCtx = {
+                webhookUrl: config.webhookUrl,
+                clientEndpoint: msgCtx.clientEndpoint,
+                botToken: msgCtx.botToken,
+                dialogId: msgCtx.chatId,
+              };
+              await sendService.sendText(
+                errSendCtx,
+                mediaDownloadFailedMsg(msgCtx.language, fileNames),
+              );
+              return;
             }
           }
 
@@ -545,7 +604,7 @@ export const bitrix24Plugin = {
             RawBody: body,
             From: `bitrix24:${msgCtx.chatId}`,
             To: `bitrix24:${msgCtx.chatId}`,
-            SessionKey: route.sessionKey,
+            SessionKey: `${route.sessionKey}:bitrix24:${msgCtx.chatId}`,
             AccountId: route.accountId,
             ChatType: msgCtx.isDm ? 'direct' : 'group',
             ConversationLabel: msgCtx.senderName,
@@ -628,25 +687,40 @@ export const bitrix24Plugin = {
 
           logger.info('Inbound command', { commandName, commandParams, senderId, dialogId });
 
-          const runtime = getBitrix24Runtime();
-          const cfg = runtime.config.loadConfig();
+          let runtime;
+          let cfg;
+          try {
+            runtime = getBitrix24Runtime();
+            cfg = runtime.config.loadConfig();
+          } catch (err) {
+            logger.error('Failed to get runtime/config for command', err);
+            return;
+          }
 
           // Pairing-aware access control (commands don't send pairing replies)
-          const accessResult = await checkAccessWithPairing({
-            senderId,
-            config,
-            runtime,
-            accountId: ctx.accountId,
-            pairingAdapter: bitrix24Plugin.pairing,
-            sendReply: async () => {},
-            logger,
-          });
+          let accessResult;
+          try {
+            accessResult = await checkAccessWithPairing({
+              senderId,
+              config,
+              runtime,
+              accountId: ctx.accountId,
+              pairingAdapter: bitrix24Plugin.pairing,
+              sendReply: async () => {},
+              logger,
+            });
+          } catch (err) {
+            logger.error('Access check failed for command', err);
+            return;
+          }
 
           if (accessResult !== 'allow') {
             logger.debug(`Command blocked (${accessResult})`, { senderId });
             return;
           }
 
+          logger.debug('Command access allowed, resolving route', { commandText });
+
           const route = runtime.channel.routing.resolveAgentRoute({
             cfg,
             channel: 'bitrix24',
@@ -654,8 +728,11 @@ export const bitrix24Plugin = {
             peer: { kind: isDm ? 'direct' : 'group', id: dialogId },
           });
 
-          // Native commands use a separate slash-command session
-          const slashSessionKey = `bitrix24:slash:${senderId}`;
+          logger.debug('Command route resolved', { sessionKey: route.sessionKey });
+
+          // Each command invocation gets a unique ephemeral session
+          // so the gateway doesn't treat it as "already handled".
+          const slashSessionKey = `bitrix24:slash:${senderId}:${Date.now()}`;
 
           const inboundCtx = runtime.channel.reply.finalizeInboundContext({
             Body: commandText,
@@ -664,7 +741,7 @@ export const bitrix24Plugin = {
             CommandBody: commandText,
             CommandAuthorized: true,
             CommandSource: 'native',
-            CommandTargetSessionKey: route.sessionKey,
+            CommandTargetSessionKey: `${route.sessionKey}:bitrix24:${dialogId}`,
             From: `bitrix24:${dialogId}`,
             To: `slash:${senderId}`,
             SessionKey: slashSessionKey,
@@ -689,15 +766,23 @@ export const bitrix24Plugin = {
             dialogId,
           };
 
+          logger.debug('Dispatching command to agent', { commandText, slashSessionKey });
+
           try {
             await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
               ctx: inboundCtx,
               cfg,
               dispatcherOptions: {
                 deliver: async (payload) => {
+                  logger.debug('Command deliver callback', {
+                    hasText: !!payload.text,
+                    textLen: payload.text?.length ?? 0,
+                    hasMedia: !!(payload.mediaUrl || payload.mediaUrls?.length),
+                  });
                   if (payload.text) {
-                    const keyboard = extractKeyboardFromPayload(payload);
-                    await sendService.sendText(sendCtx, payload.text, keyboard ? { keyboard } : undefined);
+                    // Use agent-provided keyboard if any, otherwise re-attach default command keyboard
+                    const keyboard = extractKeyboardFromPayload(payload) ?? DEFAULT_COMMAND_KEYBOARD;
+                    await sendService.sendText(sendCtx, payload.text, { keyboard });
                   }
                 },
                 onReplyStart: async () => {
@@ -710,28 +795,57 @@ export const bitrix24Plugin = {
                 },
               },
             });
+            logger.debug('Command dispatch completed', { commandText });
           } catch (err) {
             logger.error('Error dispatching command to agent', err);
           }
         },
 
         onJoinChat: async (event: B24JoinChatEvent) => {
+          const dialogId = event.data.PARAMS.DIALOG_ID;
+          const botEntry = Object.values(event.data.BOT)[0];
           logger.info('Bot joined chat', {
-            dialogId: event.data.PARAMS.DIALOG_ID,
+            dialogId,
             userId: event.data.PARAMS.USER_ID,
+            hasBotEntry: !!botEntry,
+            botId: botEntry?.BOT_ID,
+            hasEndpoint: !!botEntry?.client_endpoint,
+            hasToken: !!botEntry?.access_token,
           });
-          const dialogId = event.data.PARAMS.DIALOG_ID;
-          const botEntry = Object.values(event.data.BOT)[0];
-          if (botEntry && dialogId) {
-            try {
+          if (!dialogId) return;
+
+          const welcomeText = `${config.botName ?? 'OpenClaw'} ready. Send me a message or pick a command below.`;
+          const welcomeOpts = { KEYBOARD: DEFAULT_COMMAND_KEYBOARD };
+
+          try {
+            // Prefer token-based call; fall back to webhook URL
+            if (botEntry?.client_endpoint && botEntry?.access_token) {
               await api.sendMessageWithToken(
                 botEntry.client_endpoint,
                 botEntry.access_token,
                 dialogId,
-                `${config.botName ?? 'OpenClaw'} ready. Send me a message to get started.`,
+                welcomeText,
+                welcomeOpts,
               );
-            } catch (err) {
-              logger.error('Failed to send welcome message', err);
+            } else if (config.webhookUrl) {
+              await api.sendMessage(config.webhookUrl, dialogId, welcomeText, welcomeOpts);
+            } else {
+              logger.warn('No way to send welcome message — no token and no webhookUrl');
+              return;
+            }
+            logger.info('Welcome message sent', { dialogId });
+          } catch (err: unknown) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            logger.error('Failed to send welcome message', { error: errMsg, dialogId });
+            // Retry via webhook if token-based call failed
+            if (botEntry?.client_endpoint && config.webhookUrl) {
+              try {
+                await api.sendMessage(config.webhookUrl, dialogId, welcomeText, welcomeOpts);
+                logger.info('Welcome message sent via webhook fallback', { dialogId });
+              } catch (err2: unknown) {
+                const errMsg2 = err2 instanceof Error ? err2.message : String(err2);
+                logger.error('Welcome message webhook fallback also failed', { error: errMsg2, dialogId });
+              }
             }
           }
         },

package/src/media-service.ts

@@ -90,16 +90,25 @@ export class MediaService {
     extension: string;
     clientEndpoint: string;
     userToken: string;
+    webhookUrl?: string;
   }): Promise<DownloadedMedia | null> {
-    const { fileId, fileName, extension, clientEndpoint, userToken } = params;
+    const { fileId, fileName, extension, clientEndpoint, userToken, webhookUrl } = params;
 
     try {
       // Get download URL from B24 REST API
-      const fileInfo = await this.api.getFileInfo(
-        clientEndpoint,
-        userToken,
-        Number(fileId),
-      );
+      // Try webhook URL first (more reliable — event tokens often lack disk scope),
+      // fall back to event access token.
+      let fileInfo: { DOWNLOAD_URL: string; [key: string]: unknown };
+      if (webhookUrl) {
+        try {
+          fileInfo = await this.api.getFileInfoViaWebhook(webhookUrl, Number(fileId));
+        } catch {
+          this.logger.debug('Webhook disk.file.get failed, falling back to token', { fileId });
+          fileInfo = await this.api.getFileInfo(clientEndpoint, userToken, Number(fileId));
+        }
+      } else {
+        fileInfo = await this.api.getFileInfo(clientEndpoint, userToken, Number(fileId));
+      }
 
       const downloadUrl = fileInfo.DOWNLOAD_URL;
       if (!downloadUrl) {

package/src/message-utils.ts

@@ -1,44 +1,174 @@
 import type { KeyboardButton, B24Keyboard } from './types.js';
 
+// ─── Placeholder helpers ──────────────────────────────────────────────────────
+
+const PH_ESC = '\x00ESC';    // escape sequences
+const PH_FCODE = '\x00FC';   // fenced code blocks
+const PH_ICODE = '\x00IC';   // inline code
+const PH_HR = '\x00HR';      // horizontal rules
+
 /**
- * Convert Markdown text to Bitrix24 BB-code chat format.
+ * Convert Markdown (CommonMark + GFM subset) to Bitrix24 BB-code chat format.
  *
- * Supported conversions:
- * - **bold** / __bold__ → [B]bold[/B]
- * - *italic* / _italic_ → [I]italic[/I]
- * - ~~strikethrough~~ → [S]strikethrough[/S]
- * - `inline code` → [CODE]inline code[/CODE]
- * - ```code block``` → [CODE]code block[/CODE]
- * - [text](url) → [URL=url]text[/URL]
- * - > blockquote → >>blockquote
+ * 4-phase pipeline:
+ *   1. Protect literals — escape sequences, fenced code, inline code → placeholders
+ *   2. Block rules     — indented code, setext headings, horizontal rules, ATX headings,
+ *                         blockquotes, unordered lists
+ *   3. Inline rules    — images, bold+italic, bold, italic, strikethrough, HTML inline
+ *                         formatting, links, autolinks
+ *   4. Restore         — placeholders → BB-code equivalents
  */
 export function markdownToBbCode(md: string): string {
-  let result = md;
-
-  // Code blocks first (to avoid processing markdown inside them)
-  result = result.replace(/```[\w]*\n?([\s\S]*?)```/g, '[CODE]$1[/CODE]');
-
-  // Inline code
-  result = result.replace(/`([^`]+)`/g, '[CODE]$1[/CODE]');
-
-  // Bold: **text** or __text__
-  result = result.replace(/\*\*(.+?)\*\*/g, '[B]$1[/B]');
-  result = result.replace(/__(.+?)__/g, '[B]$1[/B]');
-
-  // Italic: *text* or _text_ (but not inside words with underscores)
-  result = result.replace(/(?<!\w)\*([^*]+?)\*(?!\w)/g, '[I]$1[/I]');
-  result = result.replace(/(?<!\w)_([^_]+?)_(?!\w)/g, '[I]$1[/I]');
-
-  // Strikethrough: ~~text~~
-  result = result.replace(/~~(.+?)~~/g, '[S]$1[/S]');
-
-  // Links: [text](url)
-  result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '[URL=$2]$1[/URL]');
-
-  // Blockquotes: > text → >>text
-  result = result.replace(/^>\s?(.*)$/gm, '>>$1');
-
-  return result;
+  let text = md;
+
+  // ── Phase 1: Protect literals ─────────────────────────────────────────────
+
+  // 1a. Escape sequences: \* \# \_ etc. → placeholders
+  const escapes: string[] = [];
+  text = text.replace(/\\([\\`*_{}[\]()#+\-.!~|>])/g, (_match, ch: string) => {
+    escapes.push(ch);
+    return `${PH_ESC}${escapes.length - 1}\x00`;
+  });
+
+  // 1b. Fenced code blocks (backticks and tildes)
+  const fencedBlocks: string[] = [];
+  text = text.replace(/^(`{3,})[^\n`]*\n([\s\S]*?)^\1[ \t]*$/gm, (_match, _fence, code: string) => {
+    fencedBlocks.push(code.replace(/\n$/, ''));
+    return `${PH_FCODE}${fencedBlocks.length - 1}\x00`;
+  });
+  text = text.replace(/^(~{3,})[^\n~]*\n([\s\S]*?)^\1[ \t]*$/gm, (_match, _fence, code: string) => {
+    fencedBlocks.push(code.replace(/\n$/, ''));
+    return `${PH_FCODE}${fencedBlocks.length - 1}\x00`;
+  });
+
+  // 1c. Inline code (backticks) — single and double backtick
+  const inlineCodes: string[] = [];
+  text = text.replace(/``([^`]+)``/g, (_match, code: string) => {
+    inlineCodes.push(code);
+    return `${PH_ICODE}${inlineCodes.length - 1}\x00`;
+  });
+  text = text.replace(/`([^`\n]+)`/g, (_match, code: string) => {
+    inlineCodes.push(code);
+    return `${PH_ICODE}${inlineCodes.length - 1}\x00`;
+  });
+
+  // ── Phase 2: Block rules (line-level, order matters) ──────────────────────
+
+  // 2a. Indented code blocks (4 spaces or 1 tab after a blank line)
+  //     Collect consecutive indented lines preceded by a blank line
+  text = text.replace(/(?:^|\n)\n((?:(?:    |\t).+\n?)+)/g, (_match, block: string) => {
+    const code = block.replace(/^(?:    |\t)/gm, '').replace(/\n$/, '');
+    fencedBlocks.push(code);
+    return `\n${PH_FCODE}${fencedBlocks.length - 1}\x00`;
+  });
+
+  // 2b. Setext headings (BEFORE horizontal rules — `---` under text is H2, not HR)
+  text = text.replace(/^([^\n]+)\n={2,}[ \t]*$/gm, '[SIZE=24][B]$1[/B][/SIZE]');
+  text = text.replace(/^([^\n]+)\n-{2,}[ \t]*$/gm, '[SIZE=20][B]$1[/B][/SIZE]');
+
+  // 2c. Horizontal rules: ---, ***, ___, - - -, * * *  (on their own line)
+  //     Use placeholder to prevent underscores from being caught by bold/italic rules
+  text = text.replace(/^[ \t]*([-*_])[ \t]*\1[ \t]*\1(?:[ \t]*\1)*[ \t]*$/gm, `${PH_HR}\x00`);
+  text = text.replace(/^[ \t]*[-*_](?:[ \t]+[-*_]){2,}[ \t]*$/gm, `${PH_HR}\x00`);
+
+  // 2d. ATX headings: # through ######
+  text = text.replace(/^######\s+(.+?)(?:\s+#+)?$/gm, '[SIZE=16][B]$1[/B][/SIZE]');
+  text = text.replace(/^#####\s+(.+?)(?:\s+#+)?$/gm, '[SIZE=16][B]$1[/B][/SIZE]');
+  text = text.replace(/^####\s+(.+?)(?:\s+#+)?$/gm, '[SIZE=16][B]$1[/B][/SIZE]');
+  text = text.replace(/^###\s+(.+?)(?:\s+#+)?$/gm, '[SIZE=18][B]$1[/B][/SIZE]');
+  text = text.replace(/^##\s+(.+?)(?:\s+#+)?$/gm, '[SIZE=20][B]$1[/B][/SIZE]');
+  text = text.replace(/^#\s+(.+?)(?:\s+#+)?$/gm, '[SIZE=24][B]$1[/B][/SIZE]');
+
+  // 2e. Blockquotes: > text → >>text (multi-level: >> text → >>>>text)
+  text = text.replace(/^(>{1,})\s?(.*)$/gm, (_m, arrows: string, content: string) => {
+    return '>'.repeat(arrows.length * 2) + content;
+  });
+
+  // 2f. Task lists (GFM): - [x] done / - [ ] todo → emoji checkboxes
+  //     Must run BEFORE generic list rules to avoid double-processing
+  text = text.replace(/^([ \t]*)[-*+]\s+\[x\]\s+(.*)$/gmi, (_m, indent: string, content: string) => {
+    const depth = Math.floor(indent.replace(/\t/g, '    ').length / 2);
+    return '\t'.repeat(depth) + '✅ ' + content;
+  });
+  text = text.replace(/^([ \t]*)[-*+]\s+\[ \]\s+(.*)$/gm, (_m, indent: string, content: string) => {
+    const depth = Math.floor(indent.replace(/\t/g, '    ').length / 2);
+    return '\t'.repeat(depth) + '☑️ ' + content;
+  });
+
+  // 2g. Ordered lists: 1. item / 2. item → number with dot
+  //     Handle nested lists with tab indentation
+  text = text.replace(/^([ \t]*)(\d+)\.\s+(.*)$/gm, (_m, indent: string, num: string, content: string) => {
+    const depth = Math.floor(indent.replace(/\t/g, '    ').length / 2);
+    return '\t'.repeat(depth) + num + '. ' + content;
+  });
+
+  // 2h. Unordered lists: - item / * item / + item → • item
+  //     Handle nested lists with tab indentation
+  text = text.replace(/^([ \t]*)[-*+]\s+(.*)$/gm, (_m, indent: string, content: string) => {
+    const depth = Math.floor(indent.replace(/\t/g, '    ').length / 2);
+    return '\t'.repeat(depth) + '• ' + content;
+  });
+
+  // ── Phase 3: Inline rules (order matters) ─────────────────────────────────
+
+  // 3a. Images: ![alt](url) → [IMG size=medium]url [/IMG] (note: space before closing tag is required by B24)
+  text = text.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, '[IMG size=medium]$2 [/IMG]');
+
+  // 3b. Bold+Italic combined: ***text*** or ___text___ → [B][I]text[/I][/B]
+  text = text.replace(/\*\*\*(.+?)\*\*\*/g, '[B][I]$1[/I][/B]');
+  text = text.replace(/___(.+?)___/g, '[B][I]$1[/I][/B]');
+
+  // 3c. Bold: **text** or __text__
+  text = text.replace(/\*\*(.+?)\*\*/g, '[B]$1[/B]');
+  text = text.replace(/__(.+?)__/g, '[B]$1[/B]');
+
+  // 3d. Italic: *text* or _text_ (word boundaries to avoid false positives)
+  text = text.replace(/(?<!\w)\*([^*]+?)\*(?!\w)/g, '[I]$1[/I]');
+  text = text.replace(/(?<!\w)_([^_]+?)_(?!\w)/g, '[I]$1[/I]');
+
+  // 3e. Strikethrough: ~~text~~
+  text = text.replace(/~~(.+?)~~/g, '[S]$1[/S]');
+
+  // 3f. HTML inline formatting tags
+  text = text.replace(/<u>([\s\S]*?)<\/u>/gi, '[U]$1[/U]');
+  text = text.replace(/<b>([\s\S]*?)<\/b>/gi, '[B]$1[/B]');
+  text = text.replace(/<strong>([\s\S]*?)<\/strong>/gi, '[B]$1[/B]');
+  text = text.replace(/<i>([\s\S]*?)<\/i>/gi, '[I]$1[/I]');
+  text = text.replace(/<em>([\s\S]*?)<\/em>/gi, '[I]$1[/I]');
+  text = text.replace(/<s>([\s\S]*?)<\/s>/gi, '[S]$1[/S]');
+  text = text.replace(/<del>([\s\S]*?)<\/del>/gi, '[S]$1[/S]');
+  text = text.replace(/<strike>([\s\S]*?)<\/strike>/gi, '[S]$1[/S]');
+
+  // 3g. Links: [text](url) → [URL=url]text[/URL]
+  text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '[URL=$2]$1[/URL]');
+
+  // 3h. Autolink URL: <https://...> → [URL]https://...[/URL]
+  text = text.replace(/<(https?:\/\/[^>]+)>/g, '[URL]$1[/URL]');
+
+  // 3i. Autolink email: <user@example.com> → [URL]mailto:user@example.com[/URL]
+  text = text.replace(/<([a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,})>/g, '[URL]mailto:$1[/URL]');
+
+  // ── Phase 4: Restore placeholders ─────────────────────────────────────────
+
+  // 4a. Horizontal rules → visual separator
+  text = text.replace(new RegExp(`${PH_HR.replace(/\x00/g, '\\x00')}\\x00`, 'g'), '____________');
+
+  // 4b. Inline code → [CODE]...[/CODE]
+  text = text.replace(new RegExp(`${PH_ICODE.replace(/\x00/g, '\\x00')}(\\d+)\\x00`, 'g'), (_m, idx: string) => {
+    return `[CODE]${inlineCodes[Number(idx)]}[/CODE]`;
+  });
+
+  // 4b. Fenced/indented code blocks → [CODE]...[/CODE]
+  text = text.replace(new RegExp(`${PH_FCODE.replace(/\x00/g, '\\x00')}(\\d+)\\x00`, 'g'), (_m, idx: string) => {
+    return `[CODE]${fencedBlocks[Number(idx)]}[/CODE]`;
+  });
+
+  // 4c. Escape sequences → literal characters
+  text = text.replace(new RegExp(`${PH_ESC.replace(/\x00/g, '\\x00')}(\\d+)\\x00`, 'g'), (_m, idx: string) => {
+    return escapes[Number(idx)];
+  });
+
+  return text;
 }
 
 /**