@wabot-dev/framework 0.9.22 → 0.9.24

package/dist/src/addon/chat-bot/anthropic/AnthropicChatAdapter.js

@@ -7,6 +7,7 @@ import '../../../feature/chat-bot/ChatBot.js';
 import '../../../feature/chat-bot/ChatOperator.js';
 import '../../../feature/chat-bot/UnionChatAdapter.js';
 import { extractChatMessageText } from '../../../feature/chat-bot/extractChatMessageText.js';
+import '../../../feature/chat-bot/ImageDescriber.js';
 import { isChatMessageEmpty } from '../../../feature/chat-bot/isChatMessageEmpty.js';
 import { isRetryableError } from '../../../feature/chat-bot/isRetryableError.js';
 import { chatAdapter } from '../../../feature/chat-bot/metadata/@chatAdapter.js';
@@ -14,6 +15,7 @@ import 'uuid';
 import '../../../feature/chat-bot/metadata/ChatBotMetadataStore.js';
 import '../../../feature/chat-bot/metadata/ChatAdapterMetadataStore.js';
 import { safeJsonParse } from '../../../feature/chat-bot/safeJsonParse.js';
+import { unconsumedMediaStartIndex } from '../../../feature/chat-bot/unconsumedMediaStartIndex.js';
 import { Anthropic } from '@anthropic-ai/sdk';
 
 const ANTHROPIC_SUPPORTED_IMAGE_MIME_TYPES = [
@@ -60,10 +62,11 @@ let AnthropicChatAdapter = class AnthropicChatAdapter {
     }
     mapChatItems(chatItems) {
         const messages = [];
-        for (const chatItem of chatItems) {
+        const mediaStart = unconsumedMediaStartIndex(chatItems);
+        chatItems.forEach((chatItem, index) => {
             switch (chatItem.type) {
                 case 'humanMessage':
-                    messages.push(this.mapHumanMessage(chatItem.humanMessage));
+                    messages.push(this.mapHumanMessage(chatItem.humanMessage, index >= mediaStart));
                     break;
                 case 'botMessage':
                     messages.push(this.mapBotMessage(chatItem.botMessage));
@@ -72,10 +75,10 @@ let AnthropicChatAdapter = class AnthropicChatAdapter {
                     messages.push(...this.mapFunctionCall(chatItem.functionCall));
                     break;
             }
-        }
+        });
         return messages;
     }
-    mapHumanMessage(item) {
+    mapHumanMessage(item, includeMedia) {
         if (isChatMessageEmpty(item)) {
             throw new Error('User message content is empty');
         }
@@ -87,14 +90,14 @@ let AnthropicChatAdapter = class AnthropicChatAdapter {
                 supportedDocumentMimeTypes: ANTHROPIC_SUPPORTED_DOCUMENT_MIME_TYPES,
             }),
         });
-        if (item.images) {
+        if (includeMedia && item.images) {
             for (const image of item.images) {
                 if (!ANTHROPIC_SUPPORTED_IMAGE_MIME_TYPES.includes(image.mimeType))
                     continue;
                 blocks.push({ type: 'image', source: this.toAnthropicImageSource(image) });
             }
         }
-        if (item.documents) {
+        if (includeMedia && item.documents) {
             for (const doc of item.documents) {
                 if (!ANTHROPIC_SUPPORTED_DOCUMENT_MIME_TYPES.includes(doc.mimeType))
                     continue;

package/dist/src/addon/chat-bot/deepseek/DeepSeekChatAdapter.js

@@ -6,6 +6,7 @@ import '../../../feature/chat-bot/ChatBot.js';
 import '../../../feature/chat-bot/ChatOperator.js';
 import '../../../feature/chat-bot/UnionChatAdapter.js';
 import { extractChatMessageText } from '../../../feature/chat-bot/extractChatMessageText.js';
+import '../../../feature/chat-bot/ImageDescriber.js';
 import { isChatMessageEmpty } from '../../../feature/chat-bot/isChatMessageEmpty.js';
 import { isRetryableError } from '../../../feature/chat-bot/isRetryableError.js';
 import { chatAdapter } from '../../../feature/chat-bot/metadata/@chatAdapter.js';

package/dist/src/addon/chat-bot/google/GoogleChatAdapter.js

@@ -8,6 +8,7 @@ import '../../../feature/chat-bot/ChatBot.js';
 import '../../../feature/chat-bot/ChatOperator.js';
 import '../../../feature/chat-bot/UnionChatAdapter.js';
 import { extractChatMessageText } from '../../../feature/chat-bot/extractChatMessageText.js';
+import '../../../feature/chat-bot/ImageDescriber.js';
 import { isChatMessageEmpty } from '../../../feature/chat-bot/isChatMessageEmpty.js';
 import { isRetryableError } from '../../../feature/chat-bot/isRetryableError.js';
 import { chatAdapter } from '../../../feature/chat-bot/metadata/@chatAdapter.js';
@@ -15,6 +16,7 @@ import 'uuid';
 import '../../../feature/chat-bot/metadata/ChatBotMetadataStore.js';
 import '../../../feature/chat-bot/metadata/ChatAdapterMetadataStore.js';
 import { safeJsonParse } from '../../../feature/chat-bot/safeJsonParse.js';
+import { unconsumedMediaStartIndex } from '../../../feature/chat-bot/unconsumedMediaStartIndex.js';
 import { GoogleGenAI } from '@google/genai';
 
 const GOOGLE_SUPPORTED_IMAGE_MIME_TYPES = [
@@ -82,10 +84,11 @@ let GoogleChatAdapter = class GoogleChatAdapter {
     }
     async mapChatItems(chatItems) {
         const contents = [];
-        for (const chatItem of chatItems) {
+        const mediaStart = unconsumedMediaStartIndex(chatItems);
+        for (const [index, chatItem] of chatItems.entries()) {
             switch (chatItem.type) {
                 case 'humanMessage':
-                    contents.push(await this.mapHumanMessage(chatItem.humanMessage));
+                    contents.push(await this.mapHumanMessage(chatItem.humanMessage, index >= mediaStart));
                     break;
                 case 'botMessage':
                     contents.push(this.mapBotMessage(chatItem.botMessage));
@@ -97,7 +100,7 @@ let GoogleChatAdapter = class GoogleChatAdapter {
         }
         return contents;
     }
-    async mapHumanMessage(item) {
+    async mapHumanMessage(item, includeMedia) {
         if (isChatMessageEmpty(item)) {
             throw new Error('User message content is empty');
         }
@@ -109,14 +112,14 @@ let GoogleChatAdapter = class GoogleChatAdapter {
             }),
         });
         const filesToSend = [];
-        if (item.images) {
+        if (includeMedia && item.images) {
             for (const image of item.images) {
                 if (!GOOGLE_SUPPORTED_IMAGE_MIME_TYPES.includes(image.mimeType))
                     continue;
                 filesToSend.push(image);
             }
         }
-        if (item.documents) {
+        if (includeMedia && item.documents) {
             for (const doc of item.documents) {
                 if (!GOOGLE_SUPPORTED_DOCUMENT_MIME_TYPES.includes(doc.mimeType))
                     continue;

package/dist/src/addon/chat-bot/in-memory/InMemoryChatMemory.js

@@ -6,6 +6,7 @@ import '../../../feature/chat-bot/ChatBot.js';
 import { ChatItem } from '../../../feature/chat-bot/ChatItem.js';
 import '../../../feature/chat-bot/ChatOperator.js';
 import '../../../feature/chat-bot/UnionChatAdapter.js';
+import '../../../feature/chat-bot/ImageDescriber.js';
 import '../../../core/injection/index.js';
 import '../../../feature/chat-bot/metadata/ChatAdapterMetadataStore.js';
 import 'uuid';

package/dist/src/addon/chat-bot/in-memory/InMemoryChatRepository.js

@@ -10,6 +10,7 @@ import '../../../feature/chat-bot/ChatAdapterRegistry.js';
 import '../../../feature/chat-bot/ChatBot.js';
 import { ChatOperator } from '../../../feature/chat-bot/ChatOperator.js';
 import '../../../feature/chat-bot/UnionChatAdapter.js';
+import '../../../feature/chat-bot/ImageDescriber.js';
 import '../../../feature/chat-bot/metadata/ChatAdapterMetadataStore.js';
 import '../../../feature/chat-bot/metadata/ChatBotMetadataStore.js';
 import '../../../core/error/setupErrorHandlers.js';

package/dist/src/addon/chat-bot/openia/OpenaiChatAdapter.js

@@ -4,6 +4,7 @@ import '../../../feature/chat-bot/ChatBot.js';
 import '../../../feature/chat-bot/ChatOperator.js';
 import '../../../feature/chat-bot/UnionChatAdapter.js';
 import { extractChatMessageText } from '../../../feature/chat-bot/extractChatMessageText.js';
+import '../../../feature/chat-bot/ImageDescriber.js';
 import { isChatMessageEmpty } from '../../../feature/chat-bot/isChatMessageEmpty.js';
 import { isRetryableError } from '../../../feature/chat-bot/isRetryableError.js';
 import { chatAdapter } from '../../../feature/chat-bot/metadata/@chatAdapter.js';
@@ -12,6 +13,7 @@ import 'uuid';
 import '../../../feature/chat-bot/metadata/ChatBotMetadataStore.js';
 import '../../../feature/chat-bot/metadata/ChatAdapterMetadataStore.js';
 import '../../../core/error/setupErrorHandlers.js';
+import { unconsumedMediaStartIndex } from '../../../feature/chat-bot/unconsumedMediaStartIndex.js';
 import { Logger } from '../../../core/logger/Logger.js';
 import { OpenAI } from 'openai';
 
@@ -51,10 +53,11 @@ let OpenaiChatAdapter = class OpenaiChatAdapter {
     }
     mapChatItems(chatItems) {
         const openIaInput = [];
-        for (const chatItem of chatItems) {
+        const mediaStart = unconsumedMediaStartIndex(chatItems);
+        chatItems.forEach((chatItem, index) => {
             switch (chatItem.type) {
                 case 'humanMessage':
-                    openIaInput.push(this.mapConectionMessage(chatItem.humanMessage));
+                    openIaInput.push(this.mapConectionMessage(chatItem.humanMessage, index >= mediaStart));
                     break;
                 case 'botMessage':
                     openIaInput.push(this.mapBotMessage(chatItem.botMessage));
@@ -63,10 +66,10 @@ let OpenaiChatAdapter = class OpenaiChatAdapter {
                     openIaInput.push(...this.mapFunctionCall(chatItem.functionCall));
                     break;
             }
-        }
+        });
         return openIaInput;
     }
-    mapConectionMessage(item) {
+    mapConectionMessage(item, includeMedia) {
         if (isChatMessageEmpty(item)) {
             throw new Error('User message content is empty');
         }
@@ -78,7 +81,7 @@ let OpenaiChatAdapter = class OpenaiChatAdapter {
                 supportedDocumentMimeTypes: OPENAI_SUPPORTED_DOCUMENT_MIME_TYPES,
             }),
         });
-        if (item.images) {
+        if (includeMedia && item.images) {
             for (const image of item.images) {
                 if (!OPENAI_SUPPORTED_IMAGE_MIME_TYPES.includes(image.mimeType))
                     continue;
@@ -89,7 +92,7 @@ let OpenaiChatAdapter = class OpenaiChatAdapter {
                 });
             }
         }
-        if (item.documents) {
+        if (includeMedia && item.documents) {
             for (const doc of item.documents) {
                 if (!OPENAI_SUPPORTED_DOCUMENT_MIME_TYPES.includes(doc.mimeType))
                     continue;

package/dist/src/addon/chat-bot/openrouter/OpenRouterChatAdapter.js

@@ -7,6 +7,7 @@ import '../../../feature/chat-bot/ChatBot.js';
 import '../../../feature/chat-bot/ChatOperator.js';
 import '../../../feature/chat-bot/UnionChatAdapter.js';
 import { extractChatMessageText } from '../../../feature/chat-bot/extractChatMessageText.js';
+import '../../../feature/chat-bot/ImageDescriber.js';
 import { isChatMessageEmpty } from '../../../feature/chat-bot/isChatMessageEmpty.js';
 import { isRetryableError } from '../../../feature/chat-bot/isRetryableError.js';
 import { chatAdapter } from '../../../feature/chat-bot/metadata/@chatAdapter.js';
@@ -14,6 +15,7 @@ import 'uuid';
 import '../../../feature/chat-bot/metadata/ChatBotMetadataStore.js';
 import '../../../feature/chat-bot/metadata/ChatAdapterMetadataStore.js';
 import '../../../core/error/setupErrorHandlers.js';
+import { unconsumedMediaStartIndex } from '../../../feature/chat-bot/unconsumedMediaStartIndex.js';
 import { OpenRouter } from '@openrouter/sdk';
 
 const OPENROUTER_SUPPORTED_IMAGE_MIME_TYPES = [
@@ -66,10 +68,11 @@ let OpenRouterChatAdapter = class OpenRouterChatAdapter {
     }
     mapChatItems(chatItems) {
         const messages = [];
-        for (const chatItem of chatItems) {
+        const mediaStart = unconsumedMediaStartIndex(chatItems);
+        chatItems.forEach((chatItem, index) => {
             switch (chatItem.type) {
                 case 'humanMessage':
-                    messages.push(this.mapHumanMessage(chatItem.humanMessage));
+                    messages.push(this.mapHumanMessage(chatItem.humanMessage, index >= mediaStart));
                     break;
                 case 'botMessage':
                     messages.push(this.mapBotMessage(chatItem.botMessage));
@@ -78,10 +81,10 @@ let OpenRouterChatAdapter = class OpenRouterChatAdapter {
                     messages.push(...this.mapFunctionCall(chatItem.functionCall));
                     break;
             }
-        }
+        });
         return messages;
     }
-    mapHumanMessage(item) {
+    mapHumanMessage(item, includeMedia) {
         if (isChatMessageEmpty(item)) {
             throw new Error('User message content is empty');
         }
@@ -90,7 +93,7 @@ let OpenRouterChatAdapter = class OpenRouterChatAdapter {
             supportedImageMimeTypes: OPENROUTER_SUPPORTED_IMAGE_MIME_TYPES,
             supportedDocumentMimeTypes: OPENROUTER_SUPPORTED_DOCUMENT_MIME_TYPES,
         }));
-        if (item.images) {
+        if (includeMedia && item.images) {
             for (const image of item.images) {
                 if (!OPENROUTER_SUPPORTED_IMAGE_MIME_TYPES.includes(image.mimeType))
                     continue;
@@ -99,7 +102,7 @@ let OpenRouterChatAdapter = class OpenRouterChatAdapter {
                     contentParts.push(imageUrl);
             }
         }
-        if (item.documents) {
+        if (includeMedia && item.documents) {
             for (const doc of item.documents) {
                 if (!OPENROUTER_SUPPORTED_DOCUMENT_MIME_TYPES.includes(doc.mimeType))
                     continue;

package/dist/src/addon/chat-bot/pg/PgChatMemory.js

@@ -13,6 +13,7 @@ import '../../../feature/chat-bot/ChatBot.js';
 import { ChatItem } from '../../../feature/chat-bot/ChatItem.js';
 import '../../../feature/chat-bot/ChatOperator.js';
 import '../../../feature/chat-bot/UnionChatAdapter.js';
+import '../../../feature/chat-bot/ImageDescriber.js';
 import '../../../feature/chat-bot/metadata/ChatAdapterMetadataStore.js';
 import 'uuid';
 import '../../../feature/chat-bot/metadata/ChatBotMetadataStore.js';

package/dist/src/addon/chat-bot/pg/PgChatRepository.js

@@ -16,6 +16,7 @@ import '../../../feature/chat-bot/ChatAdapterRegistry.js';
 import '../../../feature/chat-bot/ChatBot.js';
 import { ChatOperator } from '../../../feature/chat-bot/ChatOperator.js';
 import '../../../feature/chat-bot/UnionChatAdapter.js';
+import '../../../feature/chat-bot/ImageDescriber.js';
 import '../../../feature/chat-bot/metadata/ChatAdapterMetadataStore.js';
 import 'uuid';
 import '../../../feature/chat-bot/metadata/ChatBotMetadataStore.js';

package/dist/src/addon/chat-bot/wabot/WabotChatAdapter.js

@@ -8,6 +8,7 @@ import '../../../feature/chat-bot/ChatAdapterRegistry.js';
 import '../../../feature/chat-bot/ChatBot.js';
 import '../../../feature/chat-bot/ChatOperator.js';
 import '../../../feature/chat-bot/UnionChatAdapter.js';
+import '../../../feature/chat-bot/ImageDescriber.js';
 import { chatAdapter } from '../../../feature/chat-bot/metadata/@chatAdapter.js';
 import 'uuid';
 import '../../../feature/chat-bot/metadata/ChatBotMetadataStore.js';

package/dist/src/addon/chat-controller/cmd/CmdChannel.js

@@ -33,7 +33,7 @@ let CmdChannel = class CmdChannel {
     }
     connect() {
         this.server.register(this.config.route, {
-            onMessage: async (text, reply) => {
+            onMessage: async ({ text, images }, reply) => {
                 if (!this.callBack)
                     return;
                 this.ensureChatId();
@@ -46,7 +46,7 @@ let CmdChannel = class CmdChannel {
                 await this.callBack({
                     channel: cmdChannelName,
                     chatConnection,
-                    message: { text },
+                    message: { text, images: toChatImages(images) },
                     reply: async (message) => {
                         reply({
                             senderName: message.senderName,
@@ -98,6 +98,16 @@ CmdChannel = CmdChannel_1 = __decorate([
         CmdChannelServer,
         CmdChannelConfig])
 ], CmdChannel);
+function toChatImages(images) {
+    if (!images || images.length === 0)
+        return undefined;
+    return images.map((image) => ({
+        id: Random.alphaNumericLowerCase(10),
+        name: image.name,
+        mimeType: image.mimeType,
+        base64Url: image.base64Url,
+    }));
+}
 function extractDisplayText(message) {
     const raw = message.text ?? '';
     const trimmed = raw.trim();

package/dist/src/addon/chat-controller/cmd/CmdChannelServer.js

@@ -146,7 +146,7 @@ let CmdChannelServer = class CmdChannelServer {
                     this.activeRoute = null;
                     return;
                 }
-                await handlers.onMessage(msg.text, (reply) => {
+                await handlers.onMessage({ text: msg.text, images: msg.images }, (reply) => {
                     this.sendToClient({ type: 'reply', ...reply });
                 });
                 return;

package/dist/src/addon/chat-controller/cmd/cmdClientImages.js

@@ -0,0 +1,132 @@
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+const IMAGE_MIME_BY_EXT = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.heic': 'image/heic',
+    '.heif': 'image/heif',
+    '.bmp': 'image/bmp',
+};
+/** Image mime type for a file path based on its extension, or null if not an image. */
+function imageMimeForPath(filePath) {
+    return IMAGE_MIME_BY_EXT[path.extname(filePath).toLowerCase()] ?? null;
+}
+/**
+ * Normalizes a path as a terminal hands it over on drag-and-drop or paste:
+ * strips surrounding single/double quotes and unescapes backslash-escaped
+ * characters (e.g. `\ ` for spaces).
+ */
+function parseDroppedPath(input) {
+    let value = input.trim();
+    if (value.length >= 2 &&
+        ((value.startsWith("'") && value.endsWith("'")) ||
+            (value.startsWith('"') && value.endsWith('"')))) {
+        value = value.slice(1, -1);
+    }
+    else {
+        value = value.replace(/\\(.)/g, '$1');
+    }
+    return value;
+}
+/** Reads an image file into a wire image, or returns null if it is not a readable image file. */
+function imageFromPath(rawPath) {
+    const filePath = parseDroppedPath(rawPath);
+    const mimeType = imageMimeForPath(filePath);
+    if (!mimeType)
+        return null;
+    try {
+        if (!fs.statSync(filePath).isFile())
+            return null;
+        const base64 = fs.readFileSync(filePath).toString('base64');
+        return {
+            name: path.basename(filePath),
+            mimeType,
+            base64Url: `data:${mimeType};base64,${base64}`,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads an image from the system clipboard, cross-platform. Returns null when
+ * the clipboard holds no image or the platform tool is unavailable.
+ *
+ * - macOS: `osascript` (built in)
+ * - Linux: `wl-paste` (Wayland) then `xclip` (X11)
+ * - Windows: PowerShell `System.Windows.Forms.Clipboard`
+ */
+function readClipboardImage() {
+    const tmpFile = path.join(os.tmpdir(), `wabot-clip-${process.pid}-${Date.now()}.png`);
+    try {
+        if (!dumpClipboardImage(tmpFile))
+            return null;
+        const stat = fs.statSync(tmpFile);
+        if (!stat.isFile() || stat.size === 0)
+            return null;
+        const base64 = fs.readFileSync(tmpFile).toString('base64');
+        return {
+            name: 'clipboard.png',
+            mimeType: 'image/png',
+            base64Url: `data:image/png;base64,${base64}`,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch {
+            // ignore: file may not have been created
+        }
+    }
+}
+function dumpClipboardImage(outFile) {
+    switch (process.platform) {
+        case 'darwin': {
+            const script = [
+                `set theFile to (open for access (POSIX file ${JSON.stringify(outFile)}) with write permission)`,
+                'try',
+                '  set eof theFile to 0',
+                '  write (the clipboard as «class PNGf») to theFile',
+                '  close access theFile',
+                'on error',
+                '  close access theFile',
+                '  error "no image on clipboard"',
+                'end try',
+            ].join('\n');
+            return run('osascript', ['-e', script]);
+        }
+        case 'linux': {
+            const quoted = `'${outFile.replace(/'/g, `'\\''`)}'`;
+            return (run('sh', ['-c', `wl-paste --type image/png > ${quoted}`]) ||
+                run('sh', ['-c', `xclip -selection clipboard -t image/png -o > ${quoted}`]));
+        }
+        case 'win32': {
+            const ps = 'Add-Type -AssemblyName System.Windows.Forms;' +
+                '$img=[Windows.Forms.Clipboard]::GetImage();' +
+                `if($img -ne $null){$img.Save(${JSON.stringify(outFile)});exit 0}else{exit 1}`;
+            return run('powershell', ['-NoProfile', '-Command', ps]);
+        }
+        default:
+            return false;
+    }
+}
+function run(command, args) {
+    try {
+        return spawnSync(command, args, { stdio: ['ignore', 'ignore', 'ignore'] }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+
+export { imageFromPath, imageMimeForPath, parseDroppedPath, readClipboardImage };

package/dist/src/addon/chat-controller/cmd/runCmdClient.js

@@ -1,6 +1,7 @@
 import * as net from 'node:net';
 import * as readline from 'node:readline';
 import { cmdChannelSocketPath } from './cmdChannelSocketPath.js';
+import { readClipboardImage, imageFromPath } from './cmdClientImages.js';
 
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
 const ansi = (code) => (text) => useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
@@ -11,11 +12,13 @@ const green = ansi('1;32');
 const greenText = ansi('32');
 const red = ansi('1;31');
 const yellow = ansi('33');
-const COMMANDS = ['/channels', '/clear', '/help', '/exit'];
+const COMMANDS = ['/channels', '/clear', '/help', '/image', '/paste', '/exit'];
 const HELP_LINES = [
     'Commands:',
     '  /channels   list channels and switch',
     '  /clear      start a fresh conversation on the current channel',
+    '  /image <p>  attach an image file (or drag a file into the terminal)',
+    '  /paste      attach an image from the clipboard (or press Ctrl+V)',
     '  /help       show this help',
     '  /exit       quit',
 ];
@@ -31,6 +34,11 @@ function runCmdClient() {
     let waitingNoticeShown = false;
     let exiting = false;
     let restoring = false;
+    let pendingImages = [];
+    const chattingPrompt = (route) => {
+        const tag = pendingImages.length > 0 ? yellow(` [${pendingImages.length} img]`) : '';
+        return cyan(route) + tag + dim(' > ');
+    };
     const completer = (line) => {
         if (line.startsWith('/')) {
             const hits = COMMANDS.filter((c) => c.startsWith(line));
@@ -58,6 +66,41 @@ function runCmdClient() {
         socket.write(JSON.stringify(msg) + '\n');
         return true;
     };
+    const refreshChatPrompt = () => {
+        if (state === 'chatting' && selected)
+            rl.setPrompt(chattingPrompt(selected));
+    };
+    const attachImage = (image, label) => {
+        pendingImages.push(image);
+        process.stdout.write(green(`[attached ${label}]`) + dim(' — press Enter to send, or type a caption first') + '\n');
+        refreshChatPrompt();
+        rl.prompt();
+    };
+    const attachFromClipboard = () => {
+        if (state !== 'chatting') {
+            process.stderr.write(red('select a channel before pasting an image.') + '\n');
+            rl.prompt();
+            return;
+        }
+        const image = readClipboardImage();
+        if (!image) {
+            process.stdout.write(yellow('No image found on the clipboard.') + '\n');
+            rl.prompt();
+            return;
+        }
+        attachImage(image, 'clipboard image');
+    };
+    const sendChatMessage = (text) => {
+        const images = pendingImages.length > 0 ? pendingImages : undefined;
+        if (!text && !images) {
+            rl.prompt();
+            return;
+        }
+        if (send({ type: 'message', text: text || undefined, images })) {
+            pendingImages = [];
+            refreshChatPrompt();
+        }
+    };
     const printChannels = (list) => {
         routes = list;
         if (list.length === 0) {
@@ -90,7 +133,7 @@ function runCmdClient() {
                     process.stdout.write(green(`[connected to ${msg.route}]`) + '\n');
                 }
                 restoring = false;
-                rl.setPrompt(cyan(msg.route) + dim(' > '));
+                rl.setPrompt(chattingPrompt(msg.route));
                 rl.prompt();
                 return;
             case 'reply':
@@ -128,7 +171,7 @@ function runCmdClient() {
                 restoring = true;
                 socket.write(JSON.stringify({ type: 'select', route: selected }) + '\n');
                 state = 'chatting';
-                rl.setPrompt(cyan(selected) + dim(' > '));
+                rl.setPrompt(chattingPrompt(selected));
                 rl.prompt();
             }
             else {
@@ -188,10 +231,15 @@ function runCmdClient() {
             socket.end();
         process.exit(code);
     };
-    rl.on('line', (input) => {
+    rl.on('line', (rawInput) => {
+        // Strip stray control chars (e.g. a ^V left behind by the Ctrl+V shortcut).
+        const input = rawInput.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');
         const trimmed = input.trim();
         if (!trimmed) {
-            rl.prompt();
+            if (state === 'chatting' && pendingImages.length > 0)
+                sendChatMessage('');
+            else
+                rl.prompt();
             return;
         }
         if (trimmed === '/exit' || trimmed.toLowerCase() === 'exit') {
@@ -213,9 +261,36 @@ function runCmdClient() {
                 rl.prompt();
                 return;
             }
+            pendingImages = [];
+            refreshChatPrompt();
             send({ type: 'clear' });
             return;
         }
+        if (trimmed === '/paste') {
+            attachFromClipboard();
+            return;
+        }
+        if (trimmed === '/image' || trimmed.startsWith('/image ')) {
+            if (state !== 'chatting') {
+                process.stderr.write(red('select a channel before attaching an image.') + '\n');
+                rl.prompt();
+                return;
+            }
+            const rawPath = trimmed.slice('/image'.length).trim();
+            if (!rawPath) {
+                process.stderr.write(red('usage: /image <path-to-image>') + '\n');
+                rl.prompt();
+                return;
+            }
+            const image = imageFromPath(rawPath);
+            if (!image) {
+                process.stderr.write(red(`not a readable image file: ${rawPath}`) + '\n');
+                rl.prompt();
+                return;
+            }
+            attachImage(image, image.name ?? 'image');
+            return;
+        }
         if (state === 'disconnected') {
             process.stderr.write(red('not connected to framework — waiting for server...') + '\n');
             rl.prompt();
@@ -231,9 +306,27 @@ function runCmdClient() {
             send({ type: 'select', route: routes[num - 1].route });
             return;
         }
-        send({ type: 'message', text: trimmed });
+        // A bare path to an image file — from drag-and-drop, or a terminal that
+        // pastes a file path on Cmd+V — attaches instead of being sent as text.
+        const dropped = imageFromPath(trimmed);
+        if (dropped) {
+            attachImage(dropped, dropped.name ?? 'image');
+            return;
+        }
+        sendChatMessage(trimmed);
     });
     rl.on('close', () => cleanup(0));
+    // Ctrl+V pastes a clipboard image. (Cmd+V is handled by the terminal itself,
+    // which pastes text/a file path — the latter is picked up as a dropped path.)
+    if (process.stdin.isTTY) {
+        readline.emitKeypressEvents(process.stdin);
+        process.stdin.on('keypress', (_str, key) => {
+            if (key && key.ctrl && key.name === 'v') {
+                process.stdout.write('\n');
+                attachFromClipboard();
+            }
+        });
+    }
     connect();
 }
 

package/dist/src/addon/chat-controller/telegram/TelegramChannel.js

@@ -2,6 +2,7 @@ import { __decorate, __metadata } from 'tslib';
 import { Bot } from 'grammy';
 import { TelegramChannelConfig } from './TelegramChannelConfig.js';
 import { injectable } from '../../../core/injection/index.js';
+import { Logger } from '../../../core/logger/Logger.js';
 import { markdownToTelegramHtml } from './markdownToTelegramHtml.js';
 import { telegramChannelName } from './telegramChannelName.js';
 
@@ -11,6 +12,7 @@ let TelegramChannel = class TelegramChannel {
     config;
     static channelName = telegramChannelName;
     bot;
+    logger = new Logger('wabot:telegram-channel');
     constructor(config) {
         this.config = config;
         this.bot = new Bot(this.config.botToken);
@@ -25,13 +27,16 @@ let TelegramChannel = class TelegramChannel {
                 chatType: ctx.message.chat.type === 'private' ? 'PRIVATE' : 'GROUP',
                 channelName: TelegramChannel_1.channelName,
             };
+            const { images, documents } = await this.extractMedia(ctx.api, ctx.message);
             await callback({
                 channel: telegramChannelName,
                 chatConnection,
                 message: {
                     senderId: ctx.from.id.toString(),
                     senderName: ctx.from.first_name,
-                    text: ctx.message.text,
+                    text: ctx.message.text ?? ctx.message.caption,
+                    images: images.length > 0 ? images : undefined,
+                    documents: documents.length > 0 ? documents : undefined,
                 },
                 reply: async (replyMessage) => {
                     if (!replyMessage.text)
@@ -43,6 +48,43 @@ let TelegramChannel = class TelegramChannel {
             });
         });
     }
+    async extractMedia(api, message) {
+        const images = [];
+        const documents = [];
+        if (message.photo && message.photo.length > 0) {
+            // Photos arrive in multiple sizes; the last entry is the highest resolution.
+            const largest = message.photo[message.photo.length - 1];
+            const file = await this.downloadChatFile(api, largest.file_id, largest.file_unique_id, 'image/jpeg');
+            if (file)
+                images.push(file);
+        }
+        if (message.document) {
+            const doc = message.document;
+            const mimeType = doc.mime_type ?? 'application/octet-stream';
+            const file = await this.downloadChatFile(api, doc.file_id, doc.file_unique_id, mimeType, doc.file_name);
+            // An image sent as an uncompressed file still belongs with the images.
+            if (file)
+                (mimeType.startsWith('image/') ? images : documents).push(file);
+        }
+        return { images, documents };
+    }
+    async downloadChatFile(api, fileId, id, mimeType, name) {
+        try {
+            const file = await api.getFile(fileId);
+            if (!file.file_path)
+                return null;
+            const url = `https://api.telegram.org/file/bot${this.config.botToken}/${file.file_path}`;
+            const res = await fetch(url);
+            if (!res.ok)
+                throw new Error(`${res.status} ${res.statusText}`);
+            const base64 = Buffer.from(await res.arrayBuffer()).toString('base64');
+            return { id, name, mimeType, base64Url: `data:${mimeType};base64,${base64}` };
+        }
+        catch (err) {
+            this.logger.warn(`failed to download telegram file '${id}'`, err instanceof Error ? { message: err.message } : { err });
+            return null;
+        }
+    }
     connect() {
         this.bot.start();
     }

package/dist/src/feature/chat-bot/ChatBot.js

@@ -5,6 +5,8 @@ import { MindsetOperator } from '../mindset/MindsetOperator.js';
 import { ChatAdapter } from './ChatAdapter.js';
 import { ChatItem } from './ChatItem.js';
 import { ChatMemory } from './ChatMemory.js';
+import { ImageDescriber } from './ImageDescriber.js';
+import { pendingMediaStartIndex } from './pendingMediaStartIndex.js';
 import { Logger } from '../../core/logger/Logger.js';
 
 const MAX_CONSECUTIVE_INVALID_ARGS = 2;
@@ -18,13 +20,16 @@ let ChatBot = class ChatBot {
     memory;
     adapter;
     mindset;
+    imageDescriber;
     logger = new Logger('wabot:chat-bot');
-    constructor(memory, adapter, mindset) {
+    constructor(memory, adapter, mindset, imageDescriber) {
         this.memory = memory;
         this.adapter = adapter;
         this.mindset = mindset;
+        this.imageDescriber = imageDescriber;
     }
     async sendMessage(message, callback) {
+        await this.describeImages(message);
         const newChatItem = new ChatItem({
             type: 'humanMessage',
             humanMessage: message,
@@ -32,6 +37,20 @@ let ChatBot = class ChatBot {
         await this.memory.create(newChatItem);
         await this.processLoop(callback, 0);
     }
+    // Caption incoming images once, before persisting, so later turns can recall
+    // them from the stored description instead of re-sending the binary. The
+    // mindset's context/skills/limits focus the description on what matters here.
+    async describeImages(message) {
+        if (!message.images?.some((image) => !image.description))
+            return;
+        const [models, context, skills, limits] = await Promise.all([
+            this.mindset.resolveModels('visionLlm'),
+            this.mindset.context(),
+            this.mindset.skills(),
+            this.mindset.limits(),
+        ]);
+        await this.imageDescriber.describeMessageImages(message, models, { context, skills, limits });
+    }
     async processLoop(callback, invalidArgsCount) {
         const prevItems = await this.memory.findLastItems(16);
         if (prevItems.length === 0) {
@@ -44,10 +63,13 @@ let ChatBot = class ChatBot {
         const systemPrompt = await this.mindset.systemPrompt();
         const tools = this.mindset.tools();
         const identity = await this.mindset.identity();
-        const needsVision = prevItems.some((item) => {
-            const data = item.getData();
-            return data.type === 'humanMessage' && (data.humanMessage.images?.length ?? 0) > 0;
-        });
+        const prevItemsData = prevItems.map((x) => x.getData());
+        // Only media from the pending exchange is actually sent to the model; images
+        // in already-answered messages are not, so they must not force a vision model.
+        const mediaStart = pendingMediaStartIndex(prevItemsData);
+        const needsVision = prevItemsData.some((data, index) => index >= mediaStart &&
+            data.type === 'humanMessage' &&
+            (data.humanMessage.images?.length ?? 0) > 0);
         const kind = needsVision ? 'visionLlm' : 'llm';
         const candidates = await this.mindset.resolveModels(kind);
         if (candidates.length === 0) {
@@ -57,7 +79,7 @@ let ChatBot = class ChatBot {
             models: candidates,
             systemPrompt,
             tools,
-            prevItems: prevItems.map((x) => x.getData()),
+            prevItems: prevItemsData,
         });
         for (const newItemData of newItemsData) {
             if (newItemData.type === 'functionCall') {
@@ -92,7 +114,8 @@ ChatBot = __decorate([
     injectable(),
     __metadata("design:paramtypes", [ChatMemory,
         ChatAdapter,
-        MindsetOperator])
+        MindsetOperator,
+        ImageDescriber])
 ], ChatBot);
 
 export { ChatBot };

package/dist/src/feature/chat-bot/ImageDescriber.js

@@ -0,0 +1,95 @@
+import { __decorate, __metadata } from 'tslib';
+import { injectable } from '../../core/injection/index.js';
+import { Logger } from '../../core/logger/Logger.js';
+import { ChatAdapter } from './ChatAdapter.js';
+
+const DESCRIBE_INSTRUCTIONS = `
+You describe images so an assistant can reference them later in a conversation
+without seeing the image again.
+
+Write a single, factual, self-contained paragraph covering the visible content:
+objects, people, scene, layout, colors, and any readable text. Be thorough but
+concise. Do not add opinions, greetings, or markdown — output only the
+description.
+`.trim();
+function buildSystemPrompt(describeContext) {
+    const sections = [DESCRIBE_INSTRUCTIONS];
+    const mindsetSections = [
+        ['Assistant context', describeContext.context],
+        ['Assistant skills', describeContext.skills],
+        ['Assistant limits', describeContext.limits],
+    ].filter(([, value]) => value && value.trim());
+    if (mindsetSections.length > 0) {
+        sections.push('The assistant you describe images for is outlined below. Use it only to ' +
+            'decide which details deserve emphasis; still describe anything else that ' +
+            'is clearly visible.');
+        for (const [title, value] of mindsetSections) {
+            sections.push(`## ${title}\n${value.trim()}`);
+        }
+    }
+    return sections.join('\n\n');
+}
+/**
+ * Generates a text description for images so the conversation can recall their
+ * content on later turns without re-sending (and re-analyzing) the binary.
+ *
+ * The description is produced once, on arrival, with a single vision-model call
+ * and stored on the image itself; from then on it travels with the message text
+ * via {@link extractChatMessageText}.
+ */
+let ImageDescriber = class ImageDescriber {
+    adapter;
+    logger = new Logger('wabot:image-describer');
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    /**
+     * Fills `description` for every image on the message that does not have one
+     * yet, mutating the images in place. Safe to call with no images or no models:
+     * it simply does nothing. Failures are logged and leave the image undescribed
+     * rather than aborting the message.
+     */
+    async describeMessageImages(message, models, describeContext = {}) {
+        const pending = message.images?.filter((image) => !image.description);
+        if (!pending || pending.length === 0 || models.length === 0)
+            return;
+        await Promise.all(pending.map(async (image) => {
+            const description = await this.describe(image, models, describeContext);
+            if (description)
+                image.description = description;
+        }));
+    }
+    async describe(image, models, describeContext = {}) {
+        if (models.length === 0)
+            return undefined;
+        try {
+            const { nextItems } = await this.adapter.nextItems({
+                models,
+                systemPrompt: buildSystemPrompt(describeContext),
+                tools: [],
+                prevItems: [
+                    {
+                        type: 'humanMessage',
+                        humanMessage: { text: 'Describe this image.', images: [image] },
+                    },
+                ],
+            });
+            const parts = [];
+            for (const item of nextItems) {
+                if (item.type === 'botMessage' && item.botMessage.text)
+                    parts.push(item.botMessage.text);
+            }
+            return parts.join('\n').trim() || undefined;
+        }
+        catch (err) {
+            this.logger.warn(`failed to describe image '${image.id}'`, err instanceof Error ? { message: err.message } : { err });
+            return undefined;
+        }
+    }
+};
+ImageDescriber = __decorate([
+    injectable(),
+    __metadata("design:paramtypes", [ChatAdapter])
+], ImageDescriber);
+
+export { ImageDescriber };

package/dist/src/feature/chat-bot/extractChatMessageText.js

@@ -9,6 +9,7 @@ function extractChatMessageText(message, options = {}) {
             id: x.id,
             name: x.name,
             mimeType: x.mimeType,
+            description: x.description,
             notAnalyzed: isAnalyzed(x.mimeType, options.supportedImageMimeTypes) ? undefined : true,
         })),
         documents: message.documents?.map((x) => ({

package/dist/src/feature/chat-bot/pendingMediaStartIndex.js

@@ -0,0 +1,22 @@
+/**
+ * Index of the first chat item that belongs to the current, not-yet-answered
+ * exchange — i.e. the item right after the last bot message.
+ *
+ * Image and document binaries should only be sent to the model for human
+ * messages at or after this index. Media in earlier human messages has already
+ * been answered by the bot, so its analysis is captured in the bot's replies;
+ * re-sending the binary would make the model analyze the same files again on
+ * every turn (and re-upload them, wasting tokens).
+ *
+ * Returns 0 when the bot has not replied yet, so the whole pending exchange
+ * keeps its media.
+ */
+function pendingMediaStartIndex(items) {
+    for (let i = items.length - 1; i >= 0; i--) {
+        if (items[i].type === 'botMessage')
+            return i + 1;
+    }
+    return 0;
+}
+
+export { pendingMediaStartIndex };

package/dist/src/feature/chat-bot/unconsumedMediaStartIndex.js

@@ -0,0 +1,27 @@
+/**
+ * Index of the first item whose media (images/documents) the model has not been
+ * shown yet — i.e. right after the last model output, be it a bot message or a
+ * function call.
+ *
+ * A file's binary should only be sent on the model's first exposure to it. Once
+ * the model has produced anything in response to a human message (a function
+ * call during a tool loop, or a reply), it has already analyzed that message's
+ * files; re-sending the bytes on the next call would analyze the same file
+ * again. This is the within-turn counterpart of {@link pendingMediaStartIndex}:
+ * that one keeps a turn's media "active" for vision-model selection across the
+ * whole tool loop, while this one stops re-uploading the bytes after the first
+ * call.
+ *
+ * Returns 0 when the model has not produced any output yet, so a brand-new
+ * message keeps its media.
+ */
+function unconsumedMediaStartIndex(items) {
+    for (let i = items.length - 1; i >= 0; i--) {
+        const type = items[i].type;
+        if (type === 'botMessage' || type === 'functionCall')
+            return i + 1;
+    }
+    return 0;
+}
+
+export { unconsumedMediaStartIndex };

package/dist/src/feature/chat-controller/ChatResolver.js

@@ -5,6 +5,7 @@ import '../chat-bot/ChatBot.js';
 import '../chat-bot/ChatOperator.js';
 import { ChatRepository } from '../chat-bot/ChatRepository.js';
 import '../chat-bot/UnionChatAdapter.js';
+import '../chat-bot/ImageDescriber.js';
 import { injectable } from '../../core/injection/index.js';
 import '../chat-bot/metadata/ChatAdapterMetadataStore.js';
 import 'uuid';

package/dist/src/feature/chat-controller/runChatControllers.js

@@ -8,6 +8,7 @@ import { ChatMemory } from '../chat-bot/ChatMemory.js';
 import '../chat-bot/ChatOperator.js';
 import { ChatRepository } from '../chat-bot/ChatRepository.js';
 import '../chat-bot/UnionChatAdapter.js';
+import '../chat-bot/ImageDescriber.js';
 import '../chat-bot/metadata/ChatAdapterMetadataStore.js';
 import 'uuid';
 import { ChatBotMetadataStore } from '../chat-bot/metadata/ChatBotMetadataStore.js';

package/dist/src/feature/project-runner/ProjectRunner.js

@@ -7,6 +7,7 @@ import '../chat-bot/ChatBot.js';
 import '../chat-bot/ChatOperator.js';
 import { ChatRepository } from '../chat-bot/ChatRepository.js';
 import '../chat-bot/UnionChatAdapter.js';
+import '../chat-bot/ImageDescriber.js';
 import '../chat-bot/metadata/ChatAdapterMetadataStore.js';
 import 'uuid';
 import '../chat-bot/metadata/ChatBotMetadataStore.js';

package/dist/src/index.d.ts

@@ -953,6 +953,8 @@ interface IChatMessagesPublicFile {
     base64Url?: undefined;
     mimeType: string;
     id: string;
+    /** Text description of the file content, used to recall it without re-analyzing the binary. */
+    description?: string;
 }
 interface IChatMessagesPrivateFile {
     name?: string;
@@ -960,6 +962,8 @@ interface IChatMessagesPrivateFile {
     base64Url: string;
     mimeType: string;
     id: string;
+    /** Text description of the file content, used to recall it without re-analyzing the binary. */
+    description?: string;
 }
 type IChatMessageFile = IChatMessagesPrivateFile | IChatMessagesPublicFile;
 
@@ -1067,13 +1071,43 @@ interface IChatBot {
     sendMessage(message: IChatMessage, callback: (message: IChatMessage) => Promise<void>): void | Promise<void>;
 }
 
+/** Slice of the mindset used to focus the description on what the assistant cares about. */
+interface IImageDescribeContext {
+    context?: string;
+    skills?: string;
+    limits?: string;
+}
+/**
+ * Generates a text description for images so the conversation can recall their
+ * content on later turns without re-sending (and re-analyzing) the binary.
+ *
+ * The description is produced once, on arrival, with a single vision-model call
+ * and stored on the image itself; from then on it travels with the message text
+ * via {@link extractChatMessageText}.
+ */
+declare class ImageDescriber {
+    private adapter;
+    private logger;
+    constructor(adapter: ChatAdapter);
+    /**
+     * Fills `description` for every image on the message that does not have one
+     * yet, mutating the images in place. Safe to call with no images or no models:
+     * it simply does nothing. Failures are logged and leave the image undescribed
+     * rather than aborting the message.
+     */
+    describeMessageImages(message: IChatMessage, models: IMindsetModelRef[], describeContext?: IImageDescribeContext): Promise<void>;
+    describe(image: IChatMessageImage, models: IMindsetModelRef[], describeContext?: IImageDescribeContext): Promise<string | undefined>;
+}
+
 declare class ChatBot implements IChatBot {
     private memory;
     private adapter;
     private mindset;
+    private imageDescriber;
     private logger;
-    constructor(memory: ChatMemory, adapter: ChatAdapter, mindset: MindsetOperator);
+    constructor(memory: ChatMemory, adapter: ChatAdapter, mindset: MindsetOperator, imageDescriber: ImageDescriber);
     sendMessage(message: IChatMessage, callback: (message: IChatMessage) => Promise<void>): Promise<void>;
+    private describeImages;
     protected processLoop(callback: (message: IChatMessage) => Promise<void>, invalidArgsCount: number): Promise<void>;
 }
 
@@ -1163,10 +1197,44 @@ declare class ChatBotMetadataStore {
     getChatBotsMetadata(): IChatBotMetadata[];
 }
 
+/**
+ * Index of the first chat item that belongs to the current, not-yet-answered
+ * exchange — i.e. the item right after the last bot message.
+ *
+ * Image and document binaries should only be sent to the model for human
+ * messages at or after this index. Media in earlier human messages has already
+ * been answered by the bot, so its analysis is captured in the bot's replies;
+ * re-sending the binary would make the model analyze the same files again on
+ * every turn (and re-upload them, wasting tokens).
+ *
+ * Returns 0 when the bot has not replied yet, so the whole pending exchange
+ * keeps its media.
+ */
+declare function pendingMediaStartIndex(items: IChatItem[]): number;
+
 declare function runChatAdapters(adapters: IConstructor<IChatAdapter>[]): void;
 
 declare function safeJsonParse<T = unknown>(json: string | undefined | null, context?: string): T;
 
+/**
+ * Index of the first item whose media (images/documents) the model has not been
+ * shown yet — i.e. right after the last model output, be it a bot message or a
+ * function call.
+ *
+ * A file's binary should only be sent on the model's first exposure to it. Once
+ * the model has produced anything in response to a human message (a function
+ * call during a tool loop, or a reply), it has already analyzed that message's
+ * files; re-sending the bytes on the next call would analyze the same file
+ * again. This is the within-turn counterpart of {@link pendingMediaStartIndex}:
+ * that one keeps a turn's media "active" for vision-model selection across the
+ * whole tool loop, while this one stops re-uploading the bytes after the first
+ * call.
+ *
+ * Returns 0 when the model has not produced any output yet, so a brand-new
+ * message keeps its media.
+ */
+declare function unconsumedMediaStartIndex(items: IChatItem[]): number;
+
 interface IProjectRunnerConfig {
     directories?: string[];
     exclude?: string[];
@@ -2056,8 +2124,51 @@ declare class CmdChannelConfig {
     constructor(route: string);
 }
 
+interface ICmdChannelEntry {
+    route: string;
+}
+interface ICmdImage {
+    name?: string;
+    mimeType: string;
+    /** Data URL: `data:<mimeType>;base64,<...>`. */
+    base64Url: string;
+}
+type CmdClientMessage = {
+    type: 'hello';
+} | {
+    type: 'select';
+    route: string;
+} | {
+    type: 'message';
+    text?: string;
+    images?: ICmdImage[];
+} | {
+    type: 'clear';
+};
+type CmdServerMessage = {
+    type: 'channels';
+    list: ICmdChannelEntry[];
+} | {
+    type: 'selected';
+    route: string;
+} | {
+    type: 'reply';
+    senderName?: string;
+    text: string;
+} | {
+    type: 'cleared';
+    route: string;
+} | {
+    type: 'error';
+    message: string;
+};
+
+interface ICmdIncomingMessage {
+    text?: string;
+    images?: ICmdImage[];
+}
 interface ICmdChannelHandlers {
-    onMessage: (text: string, reply: (response: {
+    onMessage: (message: ICmdIncomingMessage, reply: (response: {
         senderName?: string;
         text: string;
     }) => void) => Promise<void> | void;
@@ -2113,38 +2224,6 @@ declare function readJsonFromFile<T>(filename: string): T | null;
 
 declare function cmdChannelSocketPath(): string;
 
-interface ICmdChannelEntry {
-    route: string;
-}
-type CmdClientMessage = {
-    type: 'hello';
-} | {
-    type: 'select';
-    route: string;
-} | {
-    type: 'message';
-    text: string;
-} | {
-    type: 'clear';
-};
-type CmdServerMessage = {
-    type: 'channels';
-    list: ICmdChannelEntry[];
-} | {
-    type: 'selected';
-    route: string;
-} | {
-    type: 'reply';
-    senderName?: string;
-    text: string;
-} | {
-    type: 'cleared';
-    route: string;
-} | {
-    type: 'error';
-    message: string;
-};
-
 declare function runCmdClient(): void;
 
 interface ISocketChannelConfig {
@@ -2234,8 +2313,11 @@ declare class TelegramChannel implements IChatChannel {
     private config;
     static channelName: "TelegramChannel";
     private bot;
+    private logger;
     constructor(config: TelegramChannelConfig);
     listen(callback: (message: ITelegramChannelMessage) => Promise<void>): void;
+    private extractMedia;
+    private downloadChatFile;
     connect(): void;
     disconnect(): void;
 }
@@ -2683,4 +2765,4 @@ declare function HtmlModule(options: IHtmlModuleOptions): {
     new (): {};
 };
 
-export { AnthropicChatAdapter, ApiKey, ApiKeyGuardMiddleware, ApiKeyHandshakeGuardMiddleware, ApiKeyRepository, Async, AsyncMetadataStore, Auth, Chat, ChatAdapter, ChatAdapterMetadataStore, ChatAdapterRegistry, ChatBot, ChatBotMetadataStore, ChatItem, ChatMemory, ChatOperator, ChatRepository, ChatResolver, type ClientMap, CmdChannel, CmdChannelConfig, CmdChannelServer, type CmdClientMessage, type CmdServerMessage, type ConfigReference, type ConfigReferenceType, ConfigResolver, Container, ControllerMetadataStore, CronJob, CronJobRepository, CrudRepository, CustomError, DeepSeekChatAdapter, DescriptionMetadataStore, EXPRESS_REQ, EXPRESS_RES, Entity, Env, type ErrorSeverity, ExpressProvider, GoogleChatAdapter, type GoogleChatAdapterV2Options, HtmlModule, HttpServerProvider, type IApiKeyData, type IApiKeyRepository, type IArrayValidationError, type IArrayValidationResult, type IBotMessageItem, type IBuiltQuery, type IChannelMessage, type IChannelMetadata, type IChatAdapter, type IChatAdapterDecoratorConfig, type IChatAdapterMetadata, type IChatAdapterNextItemsReq, type IChatAdapterNextItemsRes, type IChatAssociation, type IChatBot, type IChatBotMetadata, type IChatChannel, type IChatConnection, type IChatControllerMetadata, type IChatData, type IChatItem, type IChatItemData, type IChatItemType, type IChatMemory, type IChatMessage, type IChatMessageDocument, type IChatMessageFile, type IChatMessageImage, type IChatMessagesPrivateFile, type IChatMessagesPublicFile, type IChatRepository, type IChatType, type ICmdChannelEntry, type ICmdChannelHandlers, type ICmdChannelMessage, type ICmdReceivedMessage, type ICommandConfig, type ICommandHandler, type ICommandHandlerConfig, type IConstructor, type ICronConfig, type ICronHandler, type ICronJobData, type ICronJobRepository, type ICrudRepository, type ICustomErrorData, type IDedupConfig, type IDescriptionMetadata, type IEndPointConfig, type IEndPointMetadata, type IEntityData, type IEnvType, type IErrorHandlersConfig, type IErrorMonitor, type IErrorMonitorContext, type IExtractChatMessageTextOptions, type IFunctionCall, type IFunctionCallItem, type IGenerateApiKeyReq, type IGenerateApiKeyRes, type IHandshakeMiddleware, type IHandshakeMiddlewareMetadata, type IHtmlModuleOptions, type IHumanMessageItem, type IJobData, type IJobOptions, type IJobRepository, type IJwtRefreshTokenData, type IJwtRefreshTokenRepository, type IKapsoChannelConfig, type IKapsoChannelMessage, type IKapsoChannelMessageListener, type IKapsoChatMessage, type IKapsoConversation, type IKapsoEvent, type IKapsoIncomingMessage, type IKapsoMessageReceivedEvent, type IKapsoReceivedMessage, type IKapsoUnknownEvent, type ILanguageModelUsage, type ILockKey, type ILocker, type ILockerKey, type IMemoryRepositoryAdapterOptions, type IMessageContext, type IMiddleware, type IMiddlewareMetadata, type IMindset, type IMindsetConfig, type IMindsetIdentity, type IMindsetLlm, type IMindsetMetadata, type IMindsetModelKind, type IMindsetModelRef, type IMindsetModels, type IMindsetModuleConfig, type IMindsetModuleMetadata, type IMindsetParameterSchema, type IMindsetTool, type IMindsetToolParameter, type IModelValidationError, type IModelValidationResult, type IModelValidatorsInfo, type IMoneyData, type IPersistentData, type IPgRepositoryConfig, type IProjectRunnerConfig, type IPropertyValidatorInfo, type IQueryAst, type IQueryCondition, type IQueryMethodMetadata, type IQueryOrderBy, type IReceivedMessage, type IRemoteApiKeyFetcher, type IRepositoryAdapter, type IRepositoryConfig, type IRepositoryRuntime, type IRestControllerConfig, type IRestControllerMetadata, type IScanProjectFilesOptions, type IScheduleAt, type IScheduleDelay, type ISendWhatsAppMessageReq, type ISendWhatsAppTemplateReq, type ISocketChannelConfig, type ISocketChannelMessage, type ISocketChannelReceivedMessage, type ISocketControllerConfig, type ISocketControllerMetadata, type ISocketEventConfig, type ISocketEventMetadata, type ISocketReceivedMessage, type IStorableData, type ITelegramChannelConfig, type ITelegramChannelMessage, type ITelegramReceivedMessage, type ITransactionAdapter, type IValidateArrayOptions, type IValidateArrayOptionsWithItemsValidators, type IValidateInputShape, type IValidateIsInOptions, type IValidateIsRecordOptions, type IValidateMaxOptions, type IValidateMinOptions, type IValidationError, type IValidationResult, type IValidator, type IValidatorMetadata, type IWasenderChannelConfig, type IWasenderChannelMessageListener, type IWasenderDeviceListMetadata, type IWasenderEvent, type IWasenderMessageContent, type IWasenderMessageContextInfo, type IWasenderMessageKey, type IWasenderMessageReceivedData, type IWasenderMessageReceivedEvent, type IWasenderQrUpdatedEvent, type IWasenderReceivedMessage, type IWhatsAppCloudContact, type IWhatsAppCloudMessage, type IWhatsAppCloudMessageMetadata, type IWhatsAppCloudTemplate, type IWhatsAppCloudTemplateComponent, type IWhatsAppCloudTemplateResponse, type IWhatsAppCloudWebhookPayload, type IWhatsAppSender, type IWhatsAppTemplateData, type IWhatsAppTemplateParameter, type IchatControllerConfig, InMemoryChatMemory, InMemoryChatRepository, InMemoryCronJobRepository, InMemoryJobRepository, InMemoryLockKey, InMemoryLocker, Job, JobRepository, JobRunner, Jwt, JwtAccessAndRefreshTokenDto, JwtConfig, JwtGuardMiddleware, JwtHandshakeGuardMiddleware, JwtRefreshToken, JwtRefreshTokenRepository, JwtSigner, JwtTokenDto, KapsoChannel, KapsoChannelConfig, KapsoReceiver, KapsoSender, KapsoWebhookController, Lifecycle, Locker, Logger, MEMORY_ADAPTER_ID, Mapper, MemoryRepositoryAdapter, MemoryRepositoryExtension, Mindset, MindsetMetadataStore, MindsetOperator, Money, MoneyDto, OpenRouterChatAdapter, OpenaiChatAdapter, PG_ADAPTER_ID, Password, type PasswordHashOptions, Persistent, PgApiKeyRepository, PgChatMemory, PgChatRepository, PgCronJobRepository, PgCrudRepository, PgJobRepository, PgJsonRepositoryAdapter, PgJwtRefreshTokenRepository, PgLockKey, PgLocker, PgRepositoryBase, PgRepositoryBase as PgRepositoryExtension, PgTransactionAdapter, ProjectRunner, type QueryConnector, type QueryOperator, type QueryPrefix, Random, RemoteApiKeyRepository, RepositoryAdapterRegistry, RepositoryMetadataStore, type ResolvedConfig, RestControllerMetadataStore, RestRequest, SocketChannel, SocketChannelConfig, SocketChannelMessageFile, SocketChannelReceivedMessage, SocketControllerMetadataStore, SocketServerConfig, SocketServerProvider, Storable, TelegramChannel, TelegramChannelConfig, TransactionMetadataStore, UnionChatAdapter, ValidationMetadataStore, WabotChatAdapter, WasenderChannel, WasenderChannelConfig, WasenderReceiver, WasenderSender, WasenderWebhookController, WhatsAppApiSender, WhatsAppReceiverByCloudApi, WhatsAppSender, apiKeyGuard, apiKeyHandshakeGuard, bool, boolArr, buildQuerySql, chatAdapter, chatBot, chatController, chatItemTypeOptions, cmd, cmdChannelName, cmdChannelSocketPath, command, commandHandler, computeDedupKey, container, cronHandler, description, errorToPlainObject, evaluateQueryAst, extractChatMessageText, extractNumberFromWasenderMessageKey, getClientMap, getPgClient, handshakeMiddlewares, inject, injectable, isArray, isBoolean, isChatMessageEmpty, isDate, isIn, isModel, isNotEmpty, isNumber, isOptional, isPresent, isRecord, isRetryableError, isString, jwtGuard, jwtHandshakeGuard, kapso, kapsoChannelName, markdownToTelegramHtml, max, memExtension, middleware, min, mindset, mindsetModule, modelInfo, num, numArr, obj, onDelete, onGet, onPost, onPut, onSocketEvent, parseQueryMethodName, pgExtension, pgStorage, query, queryExtension, readJsonFromFile, repository, resolveConfigReferences, restController, run, runChatAdapters, runChatControllers, runCmdClient, runCommandHandlers, runCronHandlers, runRestControllers, runSocketControllers, safeJsonParse, scanProjectFiles, scoped, setupErrorHandlers, singleton, socket, socketChannelName, socketController, stopCommandHandlers, stopCronHandlers, str, strArr, telegram, telegramChannelName, transaction, validateAndTransform, validateArray, validateIsBoolean, validateIsDate, validateIsIn, validateIsNotEmpty, validateIsNumber, validateIsPresent, validateIsRecord, validateIsString, validateMax, validateMin, validateModel, wasender, wasenderChannelName, withPgClient, withPgTransaction, writeJsonToFile };
+export { AnthropicChatAdapter, ApiKey, ApiKeyGuardMiddleware, ApiKeyHandshakeGuardMiddleware, ApiKeyRepository, Async, AsyncMetadataStore, Auth, Chat, ChatAdapter, ChatAdapterMetadataStore, ChatAdapterRegistry, ChatBot, ChatBotMetadataStore, ChatItem, ChatMemory, ChatOperator, ChatRepository, ChatResolver, type ClientMap, CmdChannel, CmdChannelConfig, CmdChannelServer, type CmdClientMessage, type CmdServerMessage, type ConfigReference, type ConfigReferenceType, ConfigResolver, Container, ControllerMetadataStore, CronJob, CronJobRepository, CrudRepository, CustomError, DeepSeekChatAdapter, DescriptionMetadataStore, EXPRESS_REQ, EXPRESS_RES, Entity, Env, type ErrorSeverity, ExpressProvider, GoogleChatAdapter, type GoogleChatAdapterV2Options, HtmlModule, HttpServerProvider, type IApiKeyData, type IApiKeyRepository, type IArrayValidationError, type IArrayValidationResult, type IBotMessageItem, type IBuiltQuery, type IChannelMessage, type IChannelMetadata, type IChatAdapter, type IChatAdapterDecoratorConfig, type IChatAdapterMetadata, type IChatAdapterNextItemsReq, type IChatAdapterNextItemsRes, type IChatAssociation, type IChatBot, type IChatBotMetadata, type IChatChannel, type IChatConnection, type IChatControllerMetadata, type IChatData, type IChatItem, type IChatItemData, type IChatItemType, type IChatMemory, type IChatMessage, type IChatMessageDocument, type IChatMessageFile, type IChatMessageImage, type IChatMessagesPrivateFile, type IChatMessagesPublicFile, type IChatRepository, type IChatType, type ICmdChannelEntry, type ICmdChannelHandlers, type ICmdChannelMessage, type ICmdImage, type ICmdIncomingMessage, type ICmdReceivedMessage, type ICommandConfig, type ICommandHandler, type ICommandHandlerConfig, type IConstructor, type ICronConfig, type ICronHandler, type ICronJobData, type ICronJobRepository, type ICrudRepository, type ICustomErrorData, type IDedupConfig, type IDescriptionMetadata, type IEndPointConfig, type IEndPointMetadata, type IEntityData, type IEnvType, type IErrorHandlersConfig, type IErrorMonitor, type IErrorMonitorContext, type IExtractChatMessageTextOptions, type IFunctionCall, type IFunctionCallItem, type IGenerateApiKeyReq, type IGenerateApiKeyRes, type IHandshakeMiddleware, type IHandshakeMiddlewareMetadata, type IHtmlModuleOptions, type IHumanMessageItem, type IImageDescribeContext, type IJobData, type IJobOptions, type IJobRepository, type IJwtRefreshTokenData, type IJwtRefreshTokenRepository, type IKapsoChannelConfig, type IKapsoChannelMessage, type IKapsoChannelMessageListener, type IKapsoChatMessage, type IKapsoConversation, type IKapsoEvent, type IKapsoIncomingMessage, type IKapsoMessageReceivedEvent, type IKapsoReceivedMessage, type IKapsoUnknownEvent, type ILanguageModelUsage, type ILockKey, type ILocker, type ILockerKey, type IMemoryRepositoryAdapterOptions, type IMessageContext, type IMiddleware, type IMiddlewareMetadata, type IMindset, type IMindsetConfig, type IMindsetIdentity, type IMindsetLlm, type IMindsetMetadata, type IMindsetModelKind, type IMindsetModelRef, type IMindsetModels, type IMindsetModuleConfig, type IMindsetModuleMetadata, type IMindsetParameterSchema, type IMindsetTool, type IMindsetToolParameter, type IModelValidationError, type IModelValidationResult, type IModelValidatorsInfo, type IMoneyData, type IPersistentData, type IPgRepositoryConfig, type IProjectRunnerConfig, type IPropertyValidatorInfo, type IQueryAst, type IQueryCondition, type IQueryMethodMetadata, type IQueryOrderBy, type IReceivedMessage, type IRemoteApiKeyFetcher, type IRepositoryAdapter, type IRepositoryConfig, type IRepositoryRuntime, type IRestControllerConfig, type IRestControllerMetadata, type IScanProjectFilesOptions, type IScheduleAt, type IScheduleDelay, type ISendWhatsAppMessageReq, type ISendWhatsAppTemplateReq, type ISocketChannelConfig, type ISocketChannelMessage, type ISocketChannelReceivedMessage, type ISocketControllerConfig, type ISocketControllerMetadata, type ISocketEventConfig, type ISocketEventMetadata, type ISocketReceivedMessage, type IStorableData, type ITelegramChannelConfig, type ITelegramChannelMessage, type ITelegramReceivedMessage, type ITransactionAdapter, type IValidateArrayOptions, type IValidateArrayOptionsWithItemsValidators, type IValidateInputShape, type IValidateIsInOptions, type IValidateIsRecordOptions, type IValidateMaxOptions, type IValidateMinOptions, type IValidationError, type IValidationResult, type IValidator, type IValidatorMetadata, type IWasenderChannelConfig, type IWasenderChannelMessageListener, type IWasenderDeviceListMetadata, type IWasenderEvent, type IWasenderMessageContent, type IWasenderMessageContextInfo, type IWasenderMessageKey, type IWasenderMessageReceivedData, type IWasenderMessageReceivedEvent, type IWasenderQrUpdatedEvent, type IWasenderReceivedMessage, type IWhatsAppCloudContact, type IWhatsAppCloudMessage, type IWhatsAppCloudMessageMetadata, type IWhatsAppCloudTemplate, type IWhatsAppCloudTemplateComponent, type IWhatsAppCloudTemplateResponse, type IWhatsAppCloudWebhookPayload, type IWhatsAppSender, type IWhatsAppTemplateData, type IWhatsAppTemplateParameter, type IchatControllerConfig, ImageDescriber, InMemoryChatMemory, InMemoryChatRepository, InMemoryCronJobRepository, InMemoryJobRepository, InMemoryLockKey, InMemoryLocker, Job, JobRepository, JobRunner, Jwt, JwtAccessAndRefreshTokenDto, JwtConfig, JwtGuardMiddleware, JwtHandshakeGuardMiddleware, JwtRefreshToken, JwtRefreshTokenRepository, JwtSigner, JwtTokenDto, KapsoChannel, KapsoChannelConfig, KapsoReceiver, KapsoSender, KapsoWebhookController, Lifecycle, Locker, Logger, MEMORY_ADAPTER_ID, Mapper, MemoryRepositoryAdapter, MemoryRepositoryExtension, Mindset, MindsetMetadataStore, MindsetOperator, Money, MoneyDto, OpenRouterChatAdapter, OpenaiChatAdapter, PG_ADAPTER_ID, Password, type PasswordHashOptions, Persistent, PgApiKeyRepository, PgChatMemory, PgChatRepository, PgCronJobRepository, PgCrudRepository, PgJobRepository, PgJsonRepositoryAdapter, PgJwtRefreshTokenRepository, PgLockKey, PgLocker, PgRepositoryBase, PgRepositoryBase as PgRepositoryExtension, PgTransactionAdapter, ProjectRunner, type QueryConnector, type QueryOperator, type QueryPrefix, Random, RemoteApiKeyRepository, RepositoryAdapterRegistry, RepositoryMetadataStore, type ResolvedConfig, RestControllerMetadataStore, RestRequest, SocketChannel, SocketChannelConfig, SocketChannelMessageFile, SocketChannelReceivedMessage, SocketControllerMetadataStore, SocketServerConfig, SocketServerProvider, Storable, TelegramChannel, TelegramChannelConfig, TransactionMetadataStore, UnionChatAdapter, ValidationMetadataStore, WabotChatAdapter, WasenderChannel, WasenderChannelConfig, WasenderReceiver, WasenderSender, WasenderWebhookController, WhatsAppApiSender, WhatsAppReceiverByCloudApi, WhatsAppSender, apiKeyGuard, apiKeyHandshakeGuard, bool, boolArr, buildQuerySql, chatAdapter, chatBot, chatController, chatItemTypeOptions, cmd, cmdChannelName, cmdChannelSocketPath, command, commandHandler, computeDedupKey, container, cronHandler, description, errorToPlainObject, evaluateQueryAst, extractChatMessageText, extractNumberFromWasenderMessageKey, getClientMap, getPgClient, handshakeMiddlewares, inject, injectable, isArray, isBoolean, isChatMessageEmpty, isDate, isIn, isModel, isNotEmpty, isNumber, isOptional, isPresent, isRecord, isRetryableError, isString, jwtGuard, jwtHandshakeGuard, kapso, kapsoChannelName, markdownToTelegramHtml, max, memExtension, middleware, min, mindset, mindsetModule, modelInfo, num, numArr, obj, onDelete, onGet, onPost, onPut, onSocketEvent, parseQueryMethodName, pendingMediaStartIndex, pgExtension, pgStorage, query, queryExtension, readJsonFromFile, repository, resolveConfigReferences, restController, run, runChatAdapters, runChatControllers, runCmdClient, runCommandHandlers, runCronHandlers, runRestControllers, runSocketControllers, safeJsonParse, scanProjectFiles, scoped, setupErrorHandlers, singleton, socket, socketChannelName, socketController, stopCommandHandlers, stopCronHandlers, str, strArr, telegram, telegramChannelName, transaction, unconsumedMediaStartIndex, validateAndTransform, validateArray, validateIsBoolean, validateIsDate, validateIsIn, validateIsNotEmpty, validateIsNumber, validateIsPresent, validateIsRecord, validateIsString, validateMax, validateMin, validateModel, wasender, wasenderChannelName, withPgClient, withPgTransaction, writeJsonToFile };

package/dist/src/index.js

@@ -71,14 +71,17 @@ export { ChatRepository } from './feature/chat-bot/ChatRepository.js';
 export { chatItemTypeOptions } from './feature/chat-bot/IChatItem.js';
 export { UnionChatAdapter } from './feature/chat-bot/UnionChatAdapter.js';
 export { extractChatMessageText } from './feature/chat-bot/extractChatMessageText.js';
+export { ImageDescriber } from './feature/chat-bot/ImageDescriber.js';
 export { isChatMessageEmpty } from './feature/chat-bot/isChatMessageEmpty.js';
 export { isRetryableError } from './feature/chat-bot/isRetryableError.js';
 export { chatAdapter } from './feature/chat-bot/metadata/@chatAdapter.js';
 export { chatBot } from './feature/chat-bot/metadata/@chatBot.js';
 export { ChatAdapterMetadataStore } from './feature/chat-bot/metadata/ChatAdapterMetadataStore.js';
 export { ChatBotMetadataStore } from './feature/chat-bot/metadata/ChatBotMetadataStore.js';
+export { pendingMediaStartIndex } from './feature/chat-bot/pendingMediaStartIndex.js';
 export { runChatAdapters } from './feature/chat-bot/runChatAdapters.js';
 export { safeJsonParse } from './feature/chat-bot/safeJsonParse.js';
+export { unconsumedMediaStartIndex } from './feature/chat-bot/unconsumedMediaStartIndex.js';
 export { chatController } from './feature/chat-controller/metadata/controller/@chatController.js';
 export { ControllerMetadataStore } from './feature/chat-controller/metadata/ControllerMetadataStore.js';
 export { ChatResolver } from './feature/chat-controller/ChatResolver.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wabot-dev/framework",
-  "version": "0.9.22",
+  "version": "0.9.24",
   "description": "Framework for IA Chat Bots",
   "type": "module",
   "main": "dist/src/index.js",
@@ -52,7 +52,7 @@
     "types:check": "tsc --noEmit",
     "elia:dev": "node --import @yucacodes/ts --import ./env.mjs  ./test/elia/_run_.ts",
     "elia:watch": "node --watch --import @yucacodes/ts --import ./env.mjs  ./test/elia/_run_.ts",
-    "elia:cmd:channel": "node --import @yucacodes/ts ./test/elia/_cmd_.ts"
+    "elia:cmd": "node --import @yucacodes/ts ./test/elia/_cmd_.ts"
   },
   "devDependencies": {
     "@rollup/plugin-alias": "5.1.1",