@ihazz/bitrix24 1.1.12 → 1.1.14

package/src/media-service.ts

@@ -1,14 +1,15 @@
 import { randomUUID } from 'node:crypto';
 import { isIP } from 'node:net';
 import { createReadStream, createWriteStream } from 'node:fs';
-import { writeFile, mkdir, stat, unlink, rename, realpath } from 'node:fs/promises';
-import { join, basename, relative, sep } from 'node:path';
+import { copyFile, writeFile, mkdir, stat, unlink, rename, realpath } from 'node:fs/promises';
+import { isAbsolute, join, basename, relative, resolve as resolvePath, sep } from 'node:path';
 import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
+import { fileURLToPath } from 'node:url';
 import { Bitrix24Api } from './api.js';
 import type { BotContext } from './api.js';
 import type { Logger } from './types.js';
-import { resolveManagedMediaDir } from './state-paths.js';
+import { resolveManagedMediaDir, resolveTrustedWorkspaceDirs } from './state-paths.js';
 import { defaultLogger, maskUrlForLog, serializeError } from './utils.js';
 
 export interface DownloadedMedia {
@@ -22,6 +23,11 @@ export interface UploadedMedia {
   messageId?: number;
 }
 
+type ResolvedUploadPath = {
+  path: string;
+  cleanup: boolean;
+};
+
 const MIME_MAP: Record<string, string> = {
   jpg: 'image/jpeg',
   jpeg: 'image/jpeg',
@@ -66,6 +72,11 @@ function mimeFromExtension(ext: string): string {
   return MIME_MAP[ext.toLowerCase()] ?? 'application/octet-stream';
 }
 
+function isPathInside(rootPath: string, filePath: string): boolean {
+  const rel = relative(rootPath, filePath);
+  return !rel.startsWith('..') && !rel.startsWith(sep);
+}
+
 function normalizeResponseContentType(contentType: string | null): string | undefined {
   if (!contentType) {
     return undefined;
@@ -75,6 +86,23 @@ function normalizeResponseContentType(contentType: string | null): string | unde
   return normalized ? normalized : undefined;
 }
 
+function normalizeLocalUploadPath(localPath: string): string | null {
+  const trimmed = localPath.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  if (trimmed.startsWith('file://')) {
+    try {
+      return fileURLToPath(trimmed);
+    } catch {
+      return null;
+    }
+  }
+
+  return trimmed;
+}
+
 function isPrivateHost(hostname: string): boolean {
   if (hostname === 'localhost' || hostname === '::1') return true;
 
@@ -138,8 +166,10 @@ const MAX_FILE_SIZE = 100 * 1024 * 1024;
 
 /** Timeout for media download requests (30 seconds). */
 const DOWNLOAD_TIMEOUT_MS = 30_000;
+const DOWNLOADED_MEDIA_CLEANUP_DELAY_MS = 30 * 60 * 1000;
 
 const EMPTY_BUFFER = Buffer.alloc(0);
+const MANAGED_FILE_NAME_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}_(.+)$/i;
 
 class MaxFileSizeExceededError extends Error {
   readonly size: number;
@@ -157,6 +187,7 @@ export class MediaService {
   private api: Bitrix24Api;
   private logger: Logger;
   private dirReady = false;
+  private pendingDownloadedMediaCleanupTimers = new Map<string, ReturnType<typeof setTimeout>>();
 
   constructor(api: Bitrix24Api, logger?: Logger) {
     this.api = api;
@@ -241,19 +272,112 @@ export class MediaService {
     return encoded;
   }
 
-  private async resolveManagedUploadPath(localPath: string): Promise<string | null> {
-    await this.ensureDir();
+  private async stageWorkspaceUploadPath(localPath: string): Promise<string> {
+    const { savePath, tempPath } = this.buildManagedMediaPath(basename(localPath), 'file');
 
     try {
-      const [mediaDir, filePath] = await Promise.all([
-        realpath(resolveManagedMediaDir()),
-        realpath(localPath),
-      ]);
-      const rel = relative(mediaDir, filePath);
-      return !rel.startsWith('..') && !rel.startsWith(sep) ? filePath : null;
-    } catch {
+      const fileStat = await stat(localPath);
+      if (fileStat.size > MAX_FILE_SIZE) {
+        throw new MaxFileSizeExceededError(fileStat.size, MAX_FILE_SIZE);
+      }
+
+      await copyFile(localPath, tempPath);
+      await rename(tempPath, savePath);
+      return savePath;
+    } catch (error) {
+      await unlink(tempPath).catch(() => undefined);
+      await unlink(savePath).catch(() => undefined);
+      throw error;
+    }
+  }
+
+  private async resolveManagedUploadPath(localPath: string): Promise<ResolvedUploadPath | null> {
+    await this.ensureDir();
+
+    const normalizedInputPath = normalizeLocalUploadPath(localPath);
+    if (!normalizedInputPath) {
       return null;
     }
+
+    const resolvedMediaDir = await realpath(resolveManagedMediaDir()).catch(() => null);
+    if (!resolvedMediaDir) {
+      return null;
+    }
+
+    const configuredWorkspaceRoots = resolveTrustedWorkspaceDirs();
+    const resolvedWorkspaceRoots = (await Promise.all(
+      configuredWorkspaceRoots.map(async (workspaceRoot) => {
+        try {
+          return await realpath(workspaceRoot);
+        } catch {
+          return null;
+        }
+      }),
+    )).filter((workspaceRoot): workspaceRoot is string => Boolean(workspaceRoot));
+
+    const candidatePaths = new Set<string>();
+    candidatePaths.add(normalizedInputPath);
+
+    if (!isAbsolute(normalizedInputPath)) {
+      candidatePaths.add(join(resolveManagedMediaDir(), normalizedInputPath));
+      for (const workspaceRoot of configuredWorkspaceRoots) {
+        candidatePaths.add(resolvePath(workspaceRoot, normalizedInputPath));
+      }
+    }
+
+    if (isAbsolute(normalizedInputPath)) {
+      const looksLikeWorkspacePath = configuredWorkspaceRoots.some((workspaceRoot) =>
+        isPathInside(workspaceRoot, normalizedInputPath),
+      );
+
+      if (looksLikeWorkspacePath) {
+        candidatePaths.add(join(resolveManagedMediaDir(), basename(normalizedInputPath)));
+      }
+    }
+
+    for (const candidatePath of candidatePaths) {
+      let filePath: string;
+
+      try {
+        filePath = await realpath(candidatePath);
+      } catch {
+        continue;
+      }
+
+      if (isPathInside(resolvedMediaDir, filePath)) {
+        return { path: filePath, cleanup: false };
+      }
+
+      for (const resolvedWorkspaceRoot of resolvedWorkspaceRoots) {
+        if (!isPathInside(resolvedWorkspaceRoot, filePath)) {
+          continue;
+        }
+
+        return {
+          path: await this.stageWorkspaceUploadPath(filePath),
+          cleanup: true,
+        };
+      }
+    }
+
+    return null;
+  }
+
+  private resolveOutboundFileName(fileName: string, managedPath: string): string {
+    const requestedBaseName = basename(fileName).trim();
+    const managedBaseName = basename(managedPath).trim();
+    const managedMatch = MANAGED_FILE_NAME_RE.exec(managedBaseName);
+    const logicalManagedName = managedMatch?.[1]?.trim() || managedBaseName;
+
+    if (requestedBaseName && requestedBaseName !== managedBaseName) {
+      return requestedBaseName;
+    }
+
+    if (requestedBaseName === managedBaseName && managedMatch?.[1]?.trim()) {
+      return managedMatch[1].trim();
+    }
+
+    return requestedBaseName || logicalManagedName;
   }
 
   private async fetchDownloadResponse(params: {
@@ -425,6 +549,7 @@ export class MediaService {
     message?: string;
   }): Promise<UploadedMedia> {
     const { localPath, fileName, webhookUrl, bot, dialogId, message } = params;
+    let stagedUploadPath: string | null = null;
 
     try {
       const managedPath = await this.resolveManagedUploadPath(localPath);
@@ -435,9 +560,12 @@ export class MediaService {
         });
         return { ok: false };
       }
+      if (managedPath.cleanup) {
+        stagedUploadPath = managedPath.path;
+      }
 
       // Check file size before reading
-      const fileStat = await stat(managedPath);
+      const fileStat = await stat(managedPath.path);
       if (fileStat.size > MAX_FILE_SIZE) {
         this.logger.warn('File too large to upload', {
           fileName,
@@ -448,10 +576,11 @@ export class MediaService {
       }
 
       // Encode incrementally to avoid holding both the raw file and base64 string in memory.
-      const base64Content = await this.encodeFileToBase64(managedPath);
+      const base64Content = await this.encodeFileToBase64(managedPath.path);
+      const outboundFileName = this.resolveOutboundFileName(fileName, managedPath.path);
 
       const result = await this.api.uploadFile(webhookUrl, bot, dialogId, {
-        name: basename(fileName).trim() || basename(managedPath),
+        name: outboundFileName,
         content: base64Content,
         message,
       });
@@ -469,6 +598,10 @@ export class MediaService {
         error: serializeError(err),
       });
       return { ok: false };
+    } finally {
+      if (stagedUploadPath) {
+        await unlink(stagedUploadPath).catch(() => undefined);
+      }
     }
   }
 
@@ -476,6 +609,12 @@ export class MediaService {
     const uniquePaths = [...new Set(paths)];
 
     for (const filePath of uniquePaths) {
+      const scheduledCleanup = this.pendingDownloadedMediaCleanupTimers.get(filePath);
+      if (scheduledCleanup) {
+        clearTimeout(scheduledCleanup);
+        this.pendingDownloadedMediaCleanupTimers.delete(filePath);
+      }
+
       if (!(await this.isManagedMediaPath(filePath))) {
         this.logger.debug('Skipping cleanup for unmanaged media path', { path: filePath });
         continue;
@@ -499,6 +638,37 @@ export class MediaService {
     }
   }
 
+  scheduleDownloadedMediaCleanup(
+    paths: string[],
+    delayMs = DOWNLOADED_MEDIA_CLEANUP_DELAY_MS,
+  ): void {
+    const normalizedDelayMs = Math.max(0, Number(delayMs) || 0);
+    const uniquePaths = [...new Set(paths.map((path) => path.trim()).filter(Boolean))];
+
+    for (const filePath of uniquePaths) {
+      const scheduledCleanup = this.pendingDownloadedMediaCleanupTimers.get(filePath);
+      if (scheduledCleanup) {
+        clearTimeout(scheduledCleanup);
+      }
+
+      const timer = setTimeout(() => {
+        this.pendingDownloadedMediaCleanupTimers.delete(filePath);
+        this.cleanupDownloadedMedia([filePath]).catch((error) => {
+          this.logger.warn('Failed to cleanup downloaded media after delay', {
+            path: filePath,
+            error: serializeError(error),
+          });
+        });
+      }, normalizedDelayMs);
+
+      if (timer && typeof timer === 'object' && 'unref' in timer) {
+        timer.unref();
+      }
+
+      this.pendingDownloadedMediaCleanupTimers.set(filePath, timer);
+    }
+  }
+
   private async isManagedMediaPath(filePath: string): Promise<boolean> {
     try {
       const resolvedPath = await realpath(filePath);

package/src/message-utils.ts

@@ -4,6 +4,7 @@ import type { KeyboardButton, B24Keyboard } from './types.js';
 
 const PH_ESC = '\x00ESC';    // escape sequences
 const PH_BBCODE = '\x00BB';  // existing BBCode blocks
+const PH_ENTITY = '\x00BE';  // existing Bitrix entity mentions
 const PH_FCODE = '\x00FC';   // fenced code blocks
 const PH_ICODE = '\x00IC';   // inline code
 const PH_HR = '\x00HR';      // horizontal rules
@@ -62,6 +63,7 @@ export function markdownToBbCode(md: string): string {
     return `${PH_ICODE}${inlineCodes.length - 1}\x00`;
   });
   const tableSeparators: string[] = [];
+  const bitrixEntityBlocks: string[] = [];
 
   // ── Phase 2: Block rules (line-level, order matters) ──────────────────────
 
@@ -149,6 +151,7 @@ export function markdownToBbCode(md: string): string {
   text = text.replace(/~~(.+?)~~/g, '[S]$1[/S]');
 
   // 3f. HTML inline formatting tags
+  text = text.replace(/<br\s*\/?>/gi, '[BR]');
   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]');
@@ -158,15 +161,27 @@ export function markdownToBbCode(md: string): string {
   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]');
+  // 3g. Links: [text](url) → Bitrix BB-code links and action links
+  text = text.replace(/\[([^\]]+)\]\(([\s\S]*?)\)/g, (_match, label: string, rawTarget: string) => {
+    return convertMarkdownLink(label, rawTarget);
+  });
 
   // 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]
+  // 3i. Autolink tel URI: <tel:+79991234567> → [CALL]+79991234567[/CALL]
+  text = text.replace(/<tel:([^>]+)>/gi, '[CALL]$1[/CALL]');
+
+  // 3j. 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]');
 
+  text = text.replace(/\[(CHAT|USER)=[^\]]+\][\s\S]*?\[\/\1\]/giu, (block: string) => {
+    bitrixEntityBlocks.push(block);
+    return `${PH_ENTITY}${bitrixEntityBlocks.length - 1}\x00`;
+  });
+
+  text = repairMalformedBitrixEntityMentions(text);
+
   // ── Phase 4: Restore placeholders ─────────────────────────────────────────
 
   // 4a. Horizontal rules → visual separator
@@ -199,7 +214,13 @@ export function markdownToBbCode(md: string): string {
     return value != null ? restoreBbCodeCodeBlock(value) : _m;
   });
 
-  // 4d. Escape sequences → literal characters
+  // 4d. Existing Bitrix entity mentions → original source, untouched
+  text = text.replace(new RegExp(`${PH_ENTITY.replace(/\x00/g, '\\x00')}(\\d+)\\x00`, 'g'), (_m, idx: string) => {
+    const value = bitrixEntityBlocks[Number(idx)];
+    return value != null ? value : _m;
+  });
+
+  // 4e. Escape sequences → literal characters
   text = text.replace(new RegExp(`${PH_ESC.replace(/\x00/g, '\\x00')}(\\d+)\\x00`, 'g'), (_m, idx: string) => {
     const value = escapes[Number(idx)];
     return value != null ? value : _m;
@@ -208,6 +229,44 @@ export function markdownToBbCode(md: string): string {
   return text;
 }
 
+function repairMalformedBitrixEntityMentions(text: string): string {
+  let repaired = text;
+
+  const quotedPatterns: RegExp[] = [
+    /\[(CHAT|USER)=([^\]]+)\]\s*«([^»\r\n]{1,80})»(?!\s*\[\/\1\])/giu,
+    /\[(CHAT|USER)=([^\]]+)\]\s*“([^”\r\n]{1,80})”(?!\s*\[\/\1\])/giu,
+    /\[(CHAT|USER)=([^\]]+)\]\s*"([^"\r\n]{1,80})"(?!\s*\[\/\1\])/giu,
+    /\[(CHAT|USER)=([^\]]+)\]\s*'([^'\r\n]{1,80})'(?!\s*\[\/\1\])/giu,
+  ];
+
+  for (const pattern of quotedPatterns) {
+    repaired = repaired.replace(pattern, (_match, rawTag: string, rawId: string, rawLabel: string) => {
+      return buildBitrixEntityMention(rawTag, rawId, rawLabel);
+    });
+  }
+
+  repaired = repaired.replace(
+    /\[(CHAT|USER)=([^\]]+)\]\s*([\p{Lu}\d][\p{L}\p{N}._+-]*(?:\s+[\p{Lu}\d][\p{L}\p{N}._+-]*){0,5})(?=$|[\s.,!?;:)\]]|\[)(?!\s*\[\/\1\])/gu,
+    (_match, rawTag: string, rawId: string, rawLabel: string) => {
+      return buildBitrixEntityMention(rawTag, rawId, rawLabel);
+    },
+  );
+
+  return repaired;
+}
+
+function buildBitrixEntityMention(rawTag: string, rawId: string, rawLabel: string): string {
+  const tag = rawTag.toUpperCase();
+  const id = rawId.trim();
+  const label = rawLabel.trim();
+
+  if (!id || !label) {
+    return `[${tag}=${rawId}]${rawLabel}`;
+  }
+
+  return `[${tag}=${id}]${label}[/${tag}]`;
+}
+
 function isInlineAccentToken(value: string): boolean {
   const trimmed = value.trim();
   if (!trimmed || /[\r\n\t]/.test(trimmed) || trimmed.length > 64) {
@@ -645,6 +704,87 @@ function extractMarkdownTarget(rawTarget: string): string {
   return trimmed;
 }
 
+function convertMarkdownLink(label: string, rawTarget: string): string {
+  const target = extractMarkdownTarget(rawTarget);
+  const normalizedTarget = target.trim();
+
+  if (!normalizedTarget) {
+    return label;
+  }
+
+  const sendMatch = normalizedTarget.match(/^send:(.+)$/i);
+  if (sendMatch) {
+    const payload = normalizeActionLinkPayload(sendMatch[1]);
+    return payload ? `[SEND=${payload}]${label}[/SEND]` : `[SEND]${label}[/SEND]`;
+  }
+
+  const putMatch = normalizedTarget.match(/^put:(.+)$/i);
+  if (putMatch) {
+    const payload = normalizeActionLinkPayload(putMatch[1]);
+    return payload ? `[PUT=${payload}]${label}[/PUT]` : `[PUT]${label}[/PUT]`;
+  }
+
+  const callMatch = normalizedTarget.match(/^(?:call|tel):(.+)$/i);
+  if (callMatch) {
+    const phone = callMatch[1].trim();
+    return phone ? `[CALL=${phone}]${label}[/CALL]` : `[CALL]${label}[/CALL]`;
+  }
+
+  const userMatch = normalizedTarget.match(/^user:(.+)$/i);
+  if (userMatch) {
+    return `[USER=${userMatch[1].trim()}]${label}[/USER]`;
+  }
+
+  const chatMatch = normalizedTarget.match(/^chat:(.+)$/i);
+  if (chatMatch) {
+    return `[CHAT=${chatMatch[1].trim()}]${label}[/CHAT]`;
+  }
+
+  const contextMatch = normalizedTarget.match(/^context:(.+)$/i);
+  if (contextMatch) {
+    return `[context=${contextMatch[1].trim()}]${label}[/context]`;
+  }
+
+  const diskMatch = normalizedTarget.match(/^disk:(.+)$/i);
+  if (diskMatch) {
+    return `[disk=${diskMatch[1].trim()}]`;
+  }
+
+  const timestampMatch = normalizedTarget.match(/^timestamp:(.+)$/i);
+  if (timestampMatch) {
+    const timestampMarkup = buildTimestampBbCode(timestampMatch[1].trim());
+    if (timestampMarkup) {
+      return timestampMarkup;
+    }
+  }
+
+  return `[URL=${normalizedTarget}]${label}[/URL]`;
+}
+
+function normalizeActionLinkPayload(value: string): string {
+  return value.trim().replace(/^\/\//, '/');
+}
+
+function buildTimestampBbCode(value: string): string {
+  if (!value) {
+    return '';
+  }
+
+  const [timestamp, rawQuery = ''] = value.split('?', 2);
+  const normalizedTimestamp = timestamp.trim();
+  if (!normalizedTimestamp) {
+    return '';
+  }
+
+  const params = new URLSearchParams(rawQuery);
+  const format = params.get('format')?.trim();
+  if (format) {
+    return `[timestamp=${normalizedTimestamp} format=${format}]`;
+  }
+
+  return `[timestamp=${normalizedTimestamp}]`;
+}
+
 function normalizeBitrixImageUrl(rawUrl: string): string {
   const trimmed = rawUrl.trim();
   if (!trimmed) return trimmed;

package/src/runtime.ts

@@ -2,6 +2,7 @@ interface ReplyPayload {
   text?: string;
   mediaUrl?: string;
   mediaUrls?: string[];
+  replyToId?: string;
   isError?: boolean;
   channelData?: Record<string, unknown>;
 }

package/src/send-service.ts

@@ -41,6 +41,7 @@ export class SendService {
     options?: {
       keyboard?: B24Keyboard;
       convertMarkdown?: boolean;
+      replyToMessageId?: number;
       forwardMessages?: number[];
       system?: boolean;
     },
@@ -49,8 +50,41 @@ export class SendService {
       ? markdownToBbCode(text)
       : text;
 
-    const chunks = splitMessage(convertedText);
-    if (chunks.length === 0) return { ok: true };
+    const chunks = convertedText.length > 0 ? splitMessage(convertedText) : [];
+    if (chunks.length === 0) {
+      if (!options?.forwardMessages?.length) {
+        return { ok: true };
+      }
+
+      const msgOptions: {
+        forwardMessages?: number[];
+        replyToMessageId?: number;
+        system?: boolean;
+      } = {
+        forwardMessages: options.forwardMessages,
+      };
+
+      if (options?.replyToMessageId) {
+        msgOptions.replyToMessageId = options.replyToMessageId;
+      }
+      if (options?.system !== undefined) {
+        msgOptions.system = options.system;
+      }
+
+      try {
+        const messageId = await this.api.sendMessage(
+          ctx.webhookUrl,
+          ctx.bot,
+          ctx.dialogId,
+          null,
+          msgOptions,
+        );
+        return { ok: true, messageId };
+      } catch (error) {
+        this.logger.error('Failed to send forwarded message without text', { error: serializeError(error) });
+        throw error;
+      }
+    }
     let lastMessageId: number | undefined;
 
     for (let i = 0; i < chunks.length; i++) {
@@ -58,6 +92,7 @@ export class SendService {
       const isLast = i === chunks.length - 1;
       const msgOptions: {
         keyboard?: B24Keyboard;
+        replyToMessageId?: number;
         forwardMessages?: number[];
         system?: boolean;
       } = {};
@@ -65,6 +100,9 @@ export class SendService {
       if (isLast && options?.keyboard) {
         msgOptions.keyboard = options.keyboard;
       }
+      if (isFirst && options?.replyToMessageId) {
+        msgOptions.replyToMessageId = options.replyToMessageId;
+      }
       if (isFirst && options?.forwardMessages?.length) {
         msgOptions.forwardMessages = options.forwardMessages;
       }
@@ -171,12 +209,22 @@ export class SendService {
   /**
    * Send the default generic typing indicator.
    */
-  async sendTyping(ctx: SendContext): Promise<void> {
+  async sendTyping(ctx: SendContext, duration?: number): Promise<void> {
     try {
-      await this.api.notifyInputAction(ctx.webhookUrl, ctx.bot, ctx.dialogId);
+      if (duration === undefined) {
+        await this.api.notifyInputAction(ctx.webhookUrl, ctx.bot, ctx.dialogId);
+      } else {
+        await this.api.notifyInputAction(
+          ctx.webhookUrl,
+          ctx.bot,
+          ctx.dialogId,
+          { duration },
+        );
+      }
     } catch (error) {
       this.logger.debug('Failed to send typing indicator', {
         dialogId: ctx.dialogId,
+        duration,
         error: serializeError(error),
       });
     }

package/src/state-paths.ts

@@ -23,6 +23,17 @@ export function resolveManagedMediaDir(env: NodeJS.ProcessEnv = process.env): st
   return join(resolveOpenClawStateDir(env), 'media', 'bitrix24');
 }
 
+export function resolveTrustedWorkspaceDirs(env: NodeJS.ProcessEnv = process.env): string[] {
+  const roots = [
+    env.OPENCLAW_WORKSPACE_DIR?.trim(),
+    env.CLAWDBOT_WORKSPACE_DIR?.trim(),
+    join(resolveOpenClawStateDir(env), 'workspace'),
+    join(resolveHomeDir(env), 'workspace'),
+  ].filter((value): value is string => Boolean(value));
+
+  return [...new Set(roots.map((root) => resolvePath(root)))];
+}
+
 export function resolvePollingStateDir(env: NodeJS.ProcessEnv = process.env): string {
   return join(resolveOpenClawStateDir(env), 'state', 'bitrix24');
 }