@blunking/codexlink 0.1.16 → 0.1.18

package/telegram-plugin/lib/bridge.js

@@ -1,9 +1,9 @@
-import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
 import { listLoadedThreadsOverWs, readThreadOverWs } from "./app-server-client.js";
 import { loadConfig } from "./env.js";
 import { injectIntoThread, isAddressOnlyPing } from "./codex.js";
-import { getUpdates, sendChatAction, sendMessage } from "./telegram.js";
+import { downloadFileBuffer, getFileInfo, getUpdates, sendChatAction, sendMessage } from "./telegram.js";
 import { appendJsonl, appendLog, defaultState, loadJson, nowIso, readTail, saveJson } from "./storage.js";
 
 function loadState(config) {
@@ -384,6 +384,19 @@ function escapeRegExp(value) {
   return String(value || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function startsWithAgentAddress(normalized, mention) {
+  // normalizeTriggerText strips most punctuation, so this covers "Otto?",
+  // "Otto:", "/otto", "!otto", "#otto" and "[otto]" as "otto".
+  return new RegExp(`^@?${mention}\\b(?:\\s|$)`, "u").test(normalized);
+}
+
+function startsWithTeamAddressList(normalized, mention) {
+  // Group chats often address multiple agents in one breath: "Angel, Otto ...".
+  // Keep this conservative: only treat it as direct if Otto is in the first
+  // small address block at the beginning, not if Otto is mentioned later.
+  return new RegExp(`^(?:@?[a-z][a-z0-9_-]{1,24}\\b\\s+){1,3}@?${mention}\\b(?:\\s|$)`, "u").test(normalized);
+}
+
 function looksLikeStatusBroadcast(text) {
   const normalized = foldTriggerText(text);
   if (/^status(?:\s|$|[~:.-])/u.test(normalized)) {
@@ -408,7 +421,7 @@ function isAgentAddressed(config, text) {
 
   for (const name of mentionNames) {
     const mention = escapeRegExp(name);
-    const startsAddressed = new RegExp(`^@?${mention}\\b(?:\\s|\\s*[-:,]|$)`, "u").test(normalized);
+    const startsAddressed = startsWithAgentAddress(normalized, mention) || startsWithTeamAddressList(normalized, mention);
     if (startsAddressed) {
       return true;
     }
@@ -423,10 +436,15 @@ function isAgentAddressed(config, text) {
       return true;
     }
 
-    const imperativeAfterMention = new RegExp(`\\b@?${mention}\\b\\s+(?:bitte|please|pull|abruf|abrufen|zieh|hol|hole|pruef|pruf|teste|debugge|fix|patch|mach|setz|starte|antwort|melde)\\b`, "u").test(normalized);
+    const imperativeAfterMention = new RegExp(`\\b@?${mention}\\b\\s+(?:bitte|please|du|kannst|kann|sollst|soll|bekommst|bekommt|kriegst|erhaeltst|erhaltst|brauchst|brauche|hilf|unterstuetz|unterstuetze|sag|schick|send|pull|abruf|abrufen|zieh|hol|hole|pruef|pruf|teste|test|debugge|fix|patch|mach|setz|starte|aktivier|antwort|melde|bescheid)\\b`, "u").test(normalized);
     if (imperativeAfterMention) {
       return true;
     }
+
+    const workDirective = new RegExp(`\\b@?${mention}\\b[\\s\\S]{0,120}\\b(?:bitte|please|du|kannst|kann|sollst|soll|bekommst|bekommt|kriegst|erhaeltst|erhaltst|brauchst|brauche|hilf|unterstuetz|unterstuetze|sag|schick|send|weiter|continue|mach|pull|abruf|abrufen|zieh|hol|hole|pruef|pruf|teste|test|debugge|fix|patch|setz|starte|aktivier|antwort|melde|bescheid|signal|live|stream|chunk|content)\\b|\\b(?:brauchst|brauche|hilf|unterstuetz|unterstuetze|sag|schick|send|weiter|continue|mach|pull|abruf|abrufen|zieh|hol|hole|pruef|pruf|teste|test|debugge|fix|patch|setz|starte|aktivier|antwort|melde|bescheid|signal|live|stream|chunk|content)\\b[\\s\\S]{0,120}\\b@?${mention}\\b`, "u").test(normalized);
+    if (workDirective) {
+      return true;
+    }
   }
 
   return false;
@@ -445,7 +463,7 @@ function isOtherAgentAddressed(config, text) {
 
   for (const name of mentionNames) {
     const mention = escapeRegExp(name);
-    const startsAddressed = new RegExp(`^@?${mention}\\b(?:\\s|\\s*[-:,]|$)`, "u").test(normalized);
+    const startsAddressed = startsWithAgentAddress(normalized, mention) || startsWithTeamAddressList(normalized, mention);
     if (startsAddressed) {
       return true;
     }
@@ -460,7 +478,7 @@ function isOtherAgentAddressed(config, text) {
       return true;
     }
 
-    const workDirective = new RegExp(`\\b@?${mention}\\b[\\s\\S]{0,80}\\b(?:bitte|please|weiter|continue|mach|pull|abruf|abrufen|zieh|hol|hole|pruef|pruf|teste|debugge|fix|patch|setz|starte|antwort|melde|uebersetz|ubersetz|translate)\\b|\\b(?:weiter|continue|mach|pull|abruf|abrufen|zieh|hol|hole|pruef|pruf|teste|debugge|fix|patch|setz|starte|antwort|melde|uebersetz|ubersetz|translate)\\b[\\s\\S]{0,80}\\b@?${mention}\\b`, "u").test(normalized);
+    const workDirective = new RegExp(`\\b@?${mention}\\b[\\s\\S]{0,120}\\b(?:bitte|please|du|kannst|kann|sollst|soll|bekommst|bekommt|kriegst|erhaeltst|erhaltst|brauchst|brauche|hilf|unterstuetz|unterstuetze|sag|schick|send|weiter|continue|mach|pull|abruf|abrufen|zieh|hol|hole|pruef|pruf|teste|test|debugge|fix|patch|setz|starte|aktivier|antwort|melde|bescheid|signal|live|stream|chunk|content|uebersetz|ubersetz|translate)\\b|\\b(?:brauchst|brauche|hilf|unterstuetz|unterstuetze|sag|schick|send|weiter|continue|mach|pull|abruf|abrufen|zieh|hol|hole|pruef|pruf|teste|test|debugge|fix|patch|setz|starte|aktivier|antwort|melde|bescheid|signal|live|stream|chunk|content|uebersetz|ubersetz|translate)\\b[\\s\\S]{0,120}\\b@?${mention}\\b`, "u").test(normalized);
     if (workDirective) {
       return true;
     }
@@ -1014,6 +1032,135 @@ function mergeStateSnapshots(currentState, incomingState) {
   return merged;
 }
 
+const IMAGE_EXTENSIONS = new Set([".avif", ".bmp", ".gif", ".jpeg", ".jpg", ".png", ".webp"]);
+
+function sanitizeAttachmentName(name) {
+  const raw = basename(String(name || "").replace(/\0/g, "")).replace(/\.\./g, "");
+  const cleaned = raw.replace(/[^0-9A-Za-z._-]+/g, "_").replace(/^_+|_+$/g, "");
+  return cleaned || "telegram-file.bin";
+}
+
+function safePathPart(value) {
+  return String(value || "")
+    .replace(/[^0-9A-Za-z_-]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    || "telegram";
+}
+
+function isImageMimeOrName(mimeType, name) {
+  const mime = String(mimeType || "").toLowerCase();
+  if (mime.startsWith("image/")) {
+    return true;
+  }
+  return IMAGE_EXTENSIONS.has(extname(String(name || "")).toLowerCase());
+}
+
+function pickTelegramAttachment(message) {
+  const messageId = String(message?.message_id || Date.now());
+  const photos = Array.isArray(message?.photo) ? message.photo : [];
+  if (photos.length > 0) {
+    const photo = [...photos].sort((left, right) => Number(left?.file_size || 0) - Number(right?.file_size || 0)).pop();
+    if (photo?.file_id) {
+      return {
+        kind: "photo",
+        fileId: String(photo.file_id),
+        fileUniqueId: String(photo.file_unique_id || ""),
+        originalName: `telegram-photo-${messageId}.jpg`,
+        mimeType: "image/jpeg",
+        sizeBytes: Number(photo.file_size || 0),
+        isImage: true
+      };
+    }
+  }
+
+  const document = message?.document;
+  if (document?.file_id) {
+    const originalName = String(document.file_name || `telegram-document-${messageId}`);
+    const mimeType = String(document.mime_type || "application/octet-stream");
+    return {
+      kind: "document",
+      fileId: String(document.file_id),
+      fileUniqueId: String(document.file_unique_id || ""),
+      originalName,
+      mimeType,
+      sizeBytes: Number(document.file_size || 0),
+      isImage: isImageMimeOrName(mimeType, originalName)
+    };
+  }
+
+  const video = message?.video || message?.animation;
+  if (video?.file_id) {
+    const mimeType = String(video.mime_type || "video/mp4");
+    return {
+      kind: message?.animation ? "animation" : "video",
+      fileId: String(video.file_id),
+      fileUniqueId: String(video.file_unique_id || ""),
+      originalName: String(video.file_name || `telegram-video-${messageId}.mp4`),
+      mimeType,
+      sizeBytes: Number(video.file_size || 0),
+      isImage: false
+    };
+  }
+
+  return null;
+}
+
+async function stageTelegramAttachment(config, inbound) {
+  if (!inbound?.attachment?.fileId) {
+    delete inbound.attachment;
+    return;
+  }
+
+  const attachment = inbound.attachment;
+  const maxBytes = Math.max(Number(config.attachmentMaxBytes || 0), 1);
+  try {
+    const file = await getFileInfo(config, attachment.fileId);
+    if (!file?.file_path) {
+      throw new Error("Telegram returned no file path");
+    }
+
+    const fileSize = Number(file.file_size || attachment.sizeBytes || 0);
+    if (fileSize > maxBytes) {
+      throw new Error(`file too large (${Math.round(fileSize / 1024 / 1024)} MB, max ${Math.round(maxBytes / 1024 / 1024)} MB)`);
+    }
+
+    const buffer = await downloadFileBuffer(config, file.file_path);
+    if (buffer.byteLength > maxBytes) {
+      throw new Error(`file too large (${Math.round(buffer.byteLength / 1024 / 1024)} MB, max ${Math.round(maxBytes / 1024 / 1024)} MB)`);
+    }
+
+    const fallbackName = basename(file.file_path) || attachment.originalName || "telegram-file.bin";
+    const originalName = attachment.originalName || fallbackName;
+    const safeName = sanitizeAttachmentName(originalName.includes(".") ? originalName : fallbackName);
+    const dir = join(
+      config.paths.attachmentsDir,
+      `${safePathPart(inbound.chatId)}_${safePathPart(inbound.messageId)}`
+    );
+    mkdirSync(dir, { recursive: true });
+    const localPath = join(dir, safeName);
+    writeFileSync(localPath, buffer);
+
+    inbound.attachments = [{
+      ...attachment,
+      originalName,
+      safeName,
+      sizeBytes: buffer.byteLength,
+      telegramFilePath: file.file_path,
+      localPath,
+      isImage: Boolean(attachment.isImage || isImageMimeOrName(attachment.mimeType, safeName))
+    }];
+    appendLog(config.paths.activityFile, `ATTACHMENT_SAVED chat=${inbound.chatId} message=${inbound.messageId} file=${safeName} bytes=${buffer.byteLength}`);
+  } catch (error) {
+    inbound.attachments = [{
+      ...attachment,
+      error: String(error?.message || error)
+    }];
+    appendLog(config.paths.activityFile, `ATTACHMENT_ERROR chat=${inbound.chatId} message=${inbound.messageId}: ${String(error?.message || error)}`);
+  } finally {
+    delete inbound.attachment;
+  }
+}
+
 function normalizeInbound(message) {
   const text = message.text ?? message.caption ?? "";
   const chatType = String(message.chat?.type || "unknown");
@@ -1033,6 +1180,7 @@ function normalizeInbound(message) {
     user: message.from?.username || message.from?.first_name || "unknown",
     userId: message.from?.id ? String(message.from.id) : "",
     text,
+    attachment: pickTelegramAttachment(message),
     ts: nowIso(),
     intent: "message",
     relevance: "ambient",
@@ -1321,7 +1469,13 @@ function shouldPublishInboundUiNotice(entry) {
 }
 
 function formatCompactInboundUiNotice(entry) {
-  const text = normalizeWhitespace(repairMojibake(entry?.text || "")).slice(0, 180);
+  let text = normalizeWhitespace(repairMojibake(entry?.text || "")).slice(0, 180);
+  if (!text && Array.isArray(entry?.attachments) && entry.attachments.length > 0) {
+    const first = entry.attachments[0];
+    text = first?.isImage ? "sendete einen Screenshot" : `sendete ${first?.originalName || "eine Datei"}`;
+  } else if (!text && entry?.attachment) {
+    text = entry.attachment.isImage ? "sendete einen Screenshot" : `sendete ${entry.attachment.originalName || "eine Datei"}`;
+  }
   if (!text) {
     return "";
   }
@@ -1592,8 +1746,17 @@ function normalizeThreadTimestampMs(value) {
   return numeric > 100000000000 ? numeric : numeric * 1000;
 }
 
+function parseRuntimeStartedAtMs(runtime) {
+  const parsed = Date.parse(String(runtime?.started_at || ""));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
 function buildHistoryText(message) {
-  const text = String(message.text || "").trim();
+  let text = String(message.text || "").trim();
+  if (!text && Array.isArray(message.attachments) && message.attachments.length > 0) {
+    const first = message.attachments[0];
+    text = first?.isImage ? "[Telegram screenshot]" : `[Telegram file: ${first?.originalName || "attachment"}]`;
+  }
   const chatType = String(message.chatType || "");
   if (chatType === "private" || !chatType) {
     return text;
@@ -1702,6 +1865,7 @@ async function resolveActiveThreadId(config, state, preferredThreadId, options =
 
     const runtimeOwner = getRuntimeOwner(config);
     const runtimeThreadId = String(runtimeOwner?.runtime?.thread_id || "").trim();
+    const runtimeStartedAtMs = parseRuntimeStartedAtMs(runtimeOwner?.runtime);
     const pinnedThreadId = String(preferredThreadId || config.currentThreadId || runtimeThreadId || "").trim();
     if (options.forcePreferred && pinnedThreadId && loadedIds.includes(pinnedThreadId)) {
       if (state.currentThreadId !== pinnedThreadId) {
@@ -1732,11 +1896,14 @@ async function resolveActiveThreadId(config, state, preferredThreadId, options =
         const source = String(thread.source || "").toLowerCase();
         const statusType = String(thread.status?.type || "").toLowerCase();
         if (source === "cli" && statusType === "active") {
-          score += 1000000000000000;
+          score += 4000000000000000;
         } else if (statusType === "active") {
-          score += 900000000000000;
+          score += 3000000000000000;
         } else if (source === "cli") {
-          score += 800000000000000;
+          score += 2000000000000000;
+        }
+        if (runtimeStartedAtMs > 0 && createdAtMs >= runtimeStartedAtMs - 120000) {
+          score += 1000000000000000;
         }
         const sessionPath = String(thread.path || "").trim();
         if (sessionPath && existsSync(sessionPath)) {
@@ -1806,7 +1973,7 @@ export function bridgeStatus() {
     lastPollAt: state.lastPollAt,
     lastInjectAt: state.lastInjectAt,
     stateDir: config.paths.root,
-    note: "Telegram first lands in queue. Automatic delivery waits for an idle session, skips ambient group noise, and still lets escalations through."
+    note: "Telegram first lands in queue. Direct/private/lane messages are delivered immediately in app-server mode; active turns receive them via turn/steer. Ambient group noise stays parked."
   };
 }
 
@@ -1968,7 +2135,7 @@ export async function pollOnce() {
       appendLog(config.paths.activityFile, `IGNORED_IDLE_BRIEF chat=${inbound.chatId} message=${inbound.messageId}`);
       continue;
     }
-    if (!inbound.text.trim()) {
+    if (!inbound.text.trim() && !inbound.attachment) {
       ignored += 1;
       appendLog(config.paths.activityFile, `IGNORED_EMPTY chat=${inbound.chatId} message=${inbound.messageId}`);
       continue;
@@ -1993,6 +2160,7 @@ export async function pollOnce() {
         telegramThreadId: inbound.telegramThreadId
       }).catch(() => {});
     }
+    await stageTelegramAttachment(config, inbound);
     state.queue.push(inbound);
     state.lastInbound = inbound;
     if (shouldPublishInboundUiNotice(inbound)) {
@@ -2091,6 +2259,15 @@ function isFastDispatchEntry(entry) {
   return false;
 }
 
+function isRealtimeAppServerEntry(entry) {
+  if (!entry) {
+    return false;
+  }
+  const relevance = String(entry.relevance || "").trim().toLowerCase();
+  const chatType = String(entry.chatType || "").trim().toLowerCase();
+  return chatType === "private" || relevance === "direct" || relevance === "lane";
+}
+
 export async function injectNext(threadId, options = {}) {
   const config = loadConfig();
   const state = loadState(config);
@@ -2188,10 +2365,17 @@ export async function injectNext(threadId, options = {}) {
     saveStateForConfig(config, state);
   }
 
-  const bypassDeferredGate = auto && (next.relevance === "escalation" || isFastDispatchEntry(next));
+  const bypassDeferredGate = auto && (
+    next.relevance === "escalation"
+    || isFastDispatchEntry(next)
+    || (useAppServer && isRealtimeAppServerEntry(next))
+  );
   if (bypassDeferredGate && auto && isFastDispatchEntry(next)) {
     appendLog(config.paths.activityFile, `FAST_TRIGGER_BYPASS chat=${next.chatId} message=${next.messageId} intent=${next.intent}`);
   }
+  if (bypassDeferredGate && auto && useAppServer && isRealtimeAppServerEntry(next) && !isFastDispatchEntry(next)) {
+    appendLog(config.paths.activityFile, `REALTIME_BYPASS chat=${next.chatId} message=${next.messageId} relevance=${next.relevance || "-"} chat_type=${next.chatType || "-"}`);
+  }
   if (auto && !bypassDeferredGate && String(config.dispatchMode || "deferred").toLowerCase() !== "legacy") {
     const openPendingReplies = countOpenPendingReplies(state, config);
     if (openPendingReplies > 0) {
@@ -2296,6 +2480,10 @@ export async function injectNext(threadId, options = {}) {
   state.lastAutoDispatchAt = auto ? state.lastInjectAt : state.lastAutoDispatchAt;
   const latestState = loadState(config);
   saveStateForConfig(config, mergeStateSnapshots(latestState, state));
+  const injectPreview = normalizeWhitespace(result.responseText || result.stderr || "").slice(0, 220);
+  if (injectPreview) {
+    appendLog(config.paths.activityFile, `INJECT_RESULT thread=${resolvedThreadId} message=${next.messageId}: ${injectPreview}`);
+  }
   appendLog(config.paths.activityFile, `INJECT_${result.ok ? "OK" : "ERROR"} thread=${resolvedThreadId} message=${next.messageId}`);
   return {
     ok: result.ok,

package/telegram-plugin/lib/codex.js

@@ -1,7 +1,11 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { spawn } from "node:child_process";
-import { join } from "node:path";
-import { startTextTurnOverWs } from "./app-server-client.js";
+import { spawn, spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { startOrSteerTextTurnOverWs } from "./app-server-client.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const runtimeRoot = join(here, "..", "..");
 
 function repairMojibake(value) {
   const input = String(value || "");
@@ -86,6 +90,9 @@ function summarizeBrief(text) {
 function compactInboundText(message) {
   const text = String(message.text || "").trim();
   if (!text) {
+    if (Array.isArray(message.attachments) && message.attachments.length > 0) {
+      return "hat eine Datei per Telegram gesendet.";
+    }
     return "";
   }
   if (/^---\s*BRIEF\b/i.test(text)) {
@@ -94,6 +101,55 @@ function compactInboundText(message) {
   return text;
 }
 
+function formatBytes(bytes) {
+  const value = Number(bytes || 0);
+  if (!Number.isFinite(value) || value <= 0) {
+    return "";
+  }
+  if (value < 1024) {
+    return `${Math.round(value)} B`;
+  }
+  if (value < 1024 * 1024) {
+    return `${(value / 1024).toFixed(1)} KB`;
+  }
+  return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatAttachmentInstructions(message) {
+  const attachments = Array.isArray(message.attachments) ? message.attachments : [];
+  if (attachments.length === 0) {
+    return [];
+  }
+
+  const lines = [
+    "",
+    "Telegram-Anhang:"
+  ];
+
+  for (const attachment of attachments) {
+    if (attachment?.error) {
+      lines.push(`- ${attachment.kind || "Datei"} konnte nicht geladen werden: ${attachment.error}`);
+      continue;
+    }
+    const label = attachment.isImage ? "Bild/Screenshot" : (attachment.kind || "Datei");
+    const meta = [
+      attachment.mimeType,
+      formatBytes(attachment.sizeBytes)
+    ].filter(Boolean).join(", ");
+    const name = attachment.originalName || attachment.safeName || "telegram-file";
+    lines.push(`- ${label}: ${name}${meta ? ` (${meta})` : ""}`);
+    lines.push(`  Lokaler Pfad: ${attachment.localPath}`);
+  }
+
+  if (attachments.some((attachment) => attachment?.isImage && attachment?.localPath)) {
+    lines.push("Die Bilddatei wurde als lokaler Bild-Input an diesen Turn angehaengt. Nutze sie direkt fuer Screenshot-/UI-Analyse.");
+  } else {
+    lines.push("Nutze die lokalen Pfade, wenn du den Inhalt der Datei pruefen oder weiterverarbeiten sollst.");
+  }
+
+  return lines;
+}
+
 function normalizeAddressText(value) {
   return repairMojibake(String(value || ""))
     .normalize("NFKC")
@@ -147,6 +203,7 @@ function buildPrompt(config, message) {
     header.push(label);
   }
   header.push(compactText);
+  header.push(...formatAttachmentInstructions(message));
 
   if (message.intent === "continue_nudge") {
     header.push(
@@ -165,12 +222,173 @@ function buildPrompt(config, message) {
   return header.join("\n");
 }
 
+function buildVisibleConsoleText(config, message) {
+  const compactText = compactInboundText(message);
+  const isBriefSummary = compactText.startsWith("Brief von ") || compactText.startsWith("Mnemo Idle");
+  const parts = [];
+  if (!isBriefSummary) {
+    parts.push(compactInboundLabel(message));
+  }
+  parts.push(compactText);
+  parts.push(...formatAttachmentInstructions(message));
+  if (message.intent === "continue_nudge") {
+    parts.push("Weiter-Signal: Bitte den laufenden Arbeitsfluss fortsetzen und nur antworten, wenn es ein konkretes Ergebnis, einen Blocker oder eine Entscheidung gibt.");
+  }
+  return parts
+    .join("\n")
+    .replace(/\s+\n/g, "\n")
+    .replace(/\n\s+/g, "\n")
+    .trim();
+}
+
+function readRuntime(config) {
+  try {
+    if (!config?.paths?.currentRuntimeFile || !existsSync(config.paths.currentRuntimeFile)) {
+      return null;
+    }
+    return JSON.parse(readFileSync(config.paths.currentRuntimeFile, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isPidAlive(pid) {
+  const parsed = Number.parseInt(String(pid || "0"), 10);
+  if (!parsed || parsed <= 0) {
+    return false;
+  }
+  try {
+    process.kill(parsed, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getVisibleConsoleSkipReason(config, message) {
+  if (process.platform !== "win32") {
+    return "not_windows";
+  }
+  if (!config.appServerWsUrl) {
+    return "no_app_server";
+  }
+  const visibleConsoleMode = String(process.env.BLUN_TELEGRAM_VISIBLE_CONSOLE_INJECT || "0").trim().toLowerCase();
+  if (visibleConsoleMode !== "force") {
+    return "env_disabled";
+  }
+  if (Array.isArray(message.attachments) && message.attachments.some((attachment) => attachment?.isImage && attachment?.localPath && !attachment.error)) {
+    return "image_attachment";
+  }
+  return "";
+}
+
+function injectVisibleConsole(config, message) {
+  const skipReason = getVisibleConsoleSkipReason(config, message);
+  if (skipReason) {
+    return { ok: false, skipped: true, reason: skipReason };
+  }
+
+  const runtime = readRuntime(config);
+  const frontendPid = Number.parseInt(String(runtime?.frontend_host_pid || "0"), 10) || 0;
+  if (!isPidAlive(frontendPid)) {
+    return { ok: false, skipped: true, reason: "frontend_offline" };
+  }
+
+  const scriptPath = join(runtimeRoot, "telegram-console-input.ps1");
+  if (!existsSync(scriptPath)) {
+    return { ok: false, skipped: true, reason: "script_missing" };
+  }
+
+  const visibleText = buildVisibleConsoleText(config, message);
+  if (!visibleText) {
+    return { ok: false, skipped: true, reason: "empty" };
+  }
+
+  const result = spawnSync("powershell.exe", [
+    "-NoProfile",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-File",
+    scriptPath,
+    "-TargetPid",
+    String(frontendPid),
+    "-Text",
+    visibleText,
+    "-ClearBefore",
+    "-Submit"
+  ], {
+    cwd: runtimeRoot,
+    encoding: "utf8",
+    windowsHide: true,
+    timeout: 20000
+  });
+
+  if (result.status === 0) {
+    return {
+      ok: true,
+      frontendPid,
+      visibleText
+    };
+  }
+
+  return {
+    ok: false,
+    skipped: false,
+    reason: "script_failed",
+    stderr: String(result.stderr || result.error || "").trim(),
+    stdout: String(result.stdout || "").trim()
+  };
+}
+
+function buildTurnInput(config, message) {
+  const prompt = buildPrompt(config, message);
+  const input = [
+    {
+      type: "text",
+      text: prompt,
+      text_elements: []
+    }
+  ];
+
+  const attachments = Array.isArray(message.attachments) ? message.attachments : [];
+  for (const attachment of attachments) {
+    if (!attachment?.isImage || !attachment.localPath || attachment.error) {
+      continue;
+    }
+    input.push({
+      type: "localImage",
+      path: attachment.localPath
+    });
+  }
+
+  return {
+    prompt,
+    input
+  };
+}
+
 export async function injectIntoThread(config, message, threadId) {
+  const turnInput = buildTurnInput(config, message);
   if (config.appServerWsUrl) {
-    const result = await startTextTurnOverWs({
+    const consoleResult = injectVisibleConsole(config, message);
+    if (consoleResult.ok) {
+      return {
+        ok: true,
+        busy: false,
+        turnId: "",
+        code: 0,
+        signal: null,
+        responseText: `console_injected thread=${threadId} frontend_pid=${consoleResult.frontendPid}`,
+        stdout: "",
+        stderr: ""
+      };
+    }
+
+    const result = await startOrSteerTextTurnOverWs({
       wsUrl: config.appServerWsUrl,
       threadId,
-      text: buildPrompt(config, message),
+      text: turnInput.prompt,
+      input: turnInput.input,
       model: config.model || null,
       effort: config.reasoningEffort || null,
       personality: config.personality || null,
@@ -183,7 +401,9 @@ export async function injectIntoThread(config, message, threadId) {
       turnId: result.turnId || "",
       code: result.ok ? 0 : null,
       signal: null,
-      responseText: result.ok ? `turn_started thread=${threadId}` : "",
+      responseText: result.ok
+        ? `${result.steered ? "turn_steered" : "turn_started"} thread=${threadId} console_${consoleResult.skipped ? "skip" : "fail"}=${consoleResult.reason || "unknown"}`
+        : "",
       stdout: "",
       stderr: result.error ? String(result.error.message || result.error) : ""
     };
@@ -192,7 +412,7 @@ export async function injectIntoThread(config, message, threadId) {
   const safeKey = `${message.chatId}_${message.messageId}`.replace(/[^0-9A-Za-z_-]/g, "_");
   const promptFile = `${config.paths.promptsDir}\\${safeKey}.md`;
   const responseFile = `${config.paths.responsesDir}\\${safeKey}.txt`;
-  writeFileSync(promptFile, buildPrompt(config, message), "utf8");
+  writeFileSync(promptFile, turnInput.prompt, "utf8");
 
   return await new Promise((resolve) => {
     let timedOut = false;

package/telegram-plugin/lib/env.js

@@ -75,6 +75,7 @@ export function loadConfig() {
     idleCooldownMs: Number.parseInt(env.BLUN_TELEGRAM_IDLE_COOLDOWN_MS || "3000", 10) || 3000,
     ambientQueueTtlMs: Number.parseInt(env.BLUN_TELEGRAM_AMBIENT_QUEUE_TTL_MS || "600000", 10) || 600000,
     pendingReplyTimeoutMs: Number.parseInt(env.BLUN_TELEGRAM_PENDING_REPLY_TIMEOUT_MS || "1800000", 10) || 1800000,
+    attachmentMaxBytes: Number.parseInt(env.BLUN_TELEGRAM_ATTACHMENT_MAX_BYTES || "52428800", 10) || 52428800,
     progressFallbackMs: Number.parseInt(env.BLUN_TELEGRAM_PROGRESS_FALLBACK_MS || "20000", 10) || 20000,
     progressRelayMode: env.BLUN_TELEGRAM_PROGRESS_RELAY?.trim().toLowerCase() || "status",
     queueNoticeEnabled: /^(1|true|yes|on)$/i.test(env.BLUN_TELEGRAM_QUEUE_NOTICE || ""),

package/telegram-plugin/lib/paths.js

@@ -25,6 +25,7 @@ export function getPaths() {
     inboxFile: join(root, "inbox.jsonl"),
     outboxFile: join(root, "outbox.jsonl"),
     activityFile: join(root, "activity.log"),
+    attachmentsDir: join(root, "attachments"),
     pollerPidFile: join(root, "poller.pid"),
     dispatcherPidFile: join(root, "dispatcher.pid"),
     responderPidFile: join(root, "responder.pid"),
@@ -42,7 +43,7 @@ export function getPaths() {
 
 export function ensureStateLayout() {
   const paths = getPaths();
-  for (const dir of [paths.root, paths.promptsDir, paths.responsesDir, paths.runtimeDir]) {
+  for (const dir of [paths.root, paths.promptsDir, paths.responsesDir, paths.runtimeDir, paths.attachmentsDir]) {
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });
     }

package/telegram-plugin/lib/telegram.js

@@ -27,6 +27,21 @@ export async function getUpdates(config, offset) {
   });
 }
 
+export async function getFileInfo(config, fileId) {
+  return telegramRequest(config, "getFile", {
+    file_id: fileId
+  });
+}
+
+export async function downloadFileBuffer(config, filePath) {
+  requireToken(config);
+  const response = await fetch(`https://api.telegram.org/file/bot${config.botToken}/${filePath}`);
+  if (!response.ok) {
+    throw new Error(`Telegram file download failed: ${response.status}`);
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+
 export async function sendMessage(config, { chatId, text, replyToMessageId, telegramThreadId }) {
   return telegramRequest(config, "sendMessage", {
     chat_id: chatId,