@yeaft/webchat-agent 1.0.590 → 1.0.592

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.590",
+  "version": "1.0.592",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/attachments.js

@@ -9,16 +9,17 @@
  *     user message into that query's `inputStream`.
  *   - Yeaft mode has many VPs taking turns inside a group, no per-VP
  *     workDir, and the Engine accepts the user message via `query()`
- *     args. So we (a) save attachments to a shared per-group folder
- *     under the agent's CWD (so file-tools using `ctx.cwd` can read
- *     them with relative paths) and (b) hand back the persisted-form
+ *     args. Session uploads belong to the instance's
+ *     `sessions/<sessionId>/attachments` directory, independent of workDir.
+ *     Non-Session callers retain the legacy CWD-relative folder.
+ *     We hand back the persisted-form
  *     metadata AND a `promptParts` content array (image blocks +
  *     synthesized [Uploaded files] suffix) for the LLM call.
  *
  * Inputs (`files`) come from the server-side resolver in
  * `client-conversation.js`: each entry is
  * `{ name, mimeType, data: <base64>, isImage }` — the `pendingFiles`
- * `fileId` was already consumed by the server before `forwardToAgent`.
+ * `fileId` is consumed only after the server successfully forwards the message.
  *
  * Output (single bundle, all named for the role each piece plays in
  * the LLM call):
@@ -40,8 +41,8 @@
  *     than swallowing it in a console.warn.
  */
 
-import { existsSync, mkdirSync, writeFileSync, readFileSync, statSync } from 'node:fs';
-import { basename, extname, join, resolve, relative, isAbsolute } from 'node:path';
+import { mkdirSync, writeFileSync, lstatSync, openSync, closeSync, fstatSync, readSync, constants } from 'node:fs';
+import { basename, extname, join, resolve, relative, isAbsolute, sep } from 'node:path';
 import { randomBytes } from 'node:crypto';
 
 // Same dir name Chat mode uses, so ".gitignore" rules and tool-side
@@ -89,6 +90,8 @@ function sanitizeBaseName(base) {
  * @param {Array<{name:string, mimeType:string, data:string, isImage?:boolean}>} files
  *        Resolved files from server (pendingFiles → base64).
  * @param {Object} [opts]
+ * @param {string} [opts.yeaftDir] Instance data root for Session uploads.
+ * @param {string} [opts.sessionId] Session owner (required with yeaftDir).
  * @param {string} [opts.subdir]   Sub-folder under TEMP_UPLOAD_DIR
  *        (e.g. sessionId). Lets multiple groups co-exist without clobbering.
  * @param {string} [opts.cwd]      Override base dir; defaults to process.cwd()
@@ -107,9 +110,11 @@ export function persistYeaftAttachments(files, opts = {}) {
   // from sessionId. Keep the existing strict policy here; this is NOT
   // user-visible.
   const subdir = opts.subdir ? String(opts.subdir).replace(/[^a-zA-Z0-9._-]/g, '_') : '';
-  const uploadDir = subdir
-    ? join(cwd, TEMP_UPLOAD_DIR, subdir)
-    : join(cwd, TEMP_UPLOAD_DIR);
+  const sessionUpload = opts.yeaftDir != null || opts.sessionId != null;
+  const uploadDir = sessionUpload
+    ? sessionAttachmentRoot(opts)
+    : (subdir && subdir !== '.' && subdir !== '..'
+      ? resolve(cwd, TEMP_UPLOAD_DIR, subdir) : resolve(cwd, TEMP_UPLOAD_DIR));
 
   if (!Array.isArray(files) || files.length === 0) {
     return { promptAttachments: [], promptSuffix: '', promptParts: [], failed: [] };
@@ -120,8 +125,17 @@ export function persistYeaftAttachments(files, opts = {}) {
   const accepted = files.slice(0, MAX_FILES_PER_TURN);
   const rejectedByCount = files.slice(MAX_FILES_PER_TURN);
 
-  if (!existsSync(uploadDir)) {
+  try {
+    if (!uploadDir) throw new Error('invalid Session attachment owner');
+    const root = sessionUpload ? resolve(opts.yeaftDir) : resolve(cwd);
+    assertNoSymlinks(root, uploadDir, true);
     mkdirSync(uploadDir, { recursive: true });
+    assertNoSymlinks(root, uploadDir);
+  } catch (error) {
+    return {
+      promptAttachments: [], promptSuffix: '', promptParts: [],
+      failed: files.map(file => ({ name: file?.name || '<unknown>', error: error.message })),
+    };
   }
 
   const promptAttachments = [];
@@ -141,17 +155,18 @@ export function persistYeaftAttachments(files, opts = {}) {
       continue;
     }
     try {
-      const ext = extname(file.name);
-      const base = basename(file.name, ext);
+      const rawExt = extname(file.name);
+      const ext = rawExt.replace(/[\\\/\0-\x1f\x7f]/g, '_');
+      const base = basename(file.name, rawExt);
       const safeBase = sanitizeBaseName(base);
       // Identity comes from random bytes — a clock is not an identity.
       // 4 bytes (2^32) is plenty for a 16-file cap.
       const suffix = randomBytes(4).toString('hex');
       const uniqueName = `${safeBase}_${suffix}${ext || ''}`;
       const absPath = join(uploadDir, uniqueName);
-      const relPath = subdir
-        ? join(TEMP_UPLOAD_DIR, subdir, uniqueName)
-        : join(TEMP_UPLOAD_DIR, uniqueName);
+      // Absolute Session references keep file tools independent of workDir;
+      // readers still require this instance and Session's exact asset root.
+      const persistedPath = sessionUpload ? absPath : relative(resolve(cwd), absPath);
 
       const buffer = Buffer.from(file.data, 'base64');
 
@@ -166,12 +181,12 @@ export function persistYeaftAttachments(files, opts = {}) {
       }
       totalBytes += buffer.length;
 
-      writeFileSync(absPath, buffer);
+      writeFileSync(absPath, buffer, { flag: 'wx', mode: 0o600 });
 
       const isImage = !!file.isImage || (file.mimeType || '').startsWith('image/');
       promptAttachments.push({
         name: file.name,
-        path: relPath,
+        path: persistedPath,
         mimeType: file.mimeType || 'application/octet-stream',
         isImage,
       });
@@ -230,48 +245,177 @@ export function attachmentsForPersistence(promptAttachments) {
   }));
 }
 
+/** Session IDs are identities, never sanitized into another Session's directory. */
+function validSessionId(value) {
+  return typeof value === 'string' && /^[a-zA-Z0-9_-][a-zA-Z0-9._-]*$/.test(value);
+}
+
+function sessionAttachmentRoot({ yeaftDir, sessionId }) {
+  return typeof yeaftDir === 'string' && yeaftDir && validSessionId(sessionId)
+    ? resolve(yeaftDir, 'sessions', sessionId, 'attachments') : null;
+}
+
+function isWithin(root, path) {
+  const rel = relative(root, path);
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+// Check the trusted base itself and every descendant, including intermediate
+// directories. O_NOFOLLOW below also guards replacement of the final file.
+// This is not a sandbox against concurrently replaced ancestor directories.
+function assertNoSymlinks(root, path, allowMissing = false) {
+  if (path !== root && !isWithin(root, path)) throw new Error('attachment path outside owner root');
+  let current = root;
+  for (const part of ['', ...relative(root, path).split(sep).filter(Boolean)]) {
+    if (part) current = join(current, part);
+    try {
+      if (lstatSync(current).isSymbolicLink()) throw new Error('attachment symlink is not allowed');
+    } catch (error) {
+      if (allowMissing && error.code === 'ENOENT') continue;
+      throw error;
+    }
+  }
+}
+
 /**
- * Resolve a persisted Yeaft attachment path to an on-disk file. The persisted
- * path is intentionally relative (for tool use), so preview hydration must
- * keep it inside the upload root instead of serving arbitrary files.
- *
+ * Resolve only this Session's assets, or its CWD-relative legacy uploads.
+ * Absolute paths are allowed ONLY in <yeaftDir>/sessions/<sessionId>/attachments.
+ * No workDir search/fallback: legacy Web uploads were written under Agent CWD.
+ * Non-Session callers retain their original CWD-relative upload root.
  * @param {string} attachmentPath
- * @param {{ cwd?: string }} [opts]
+ * @param {{cwd?:string, legacyRoot?:string, yeaftDir?:string, sessionId?:string}} [opts]
+ *        legacyRoot is the original Agent CWD (not workDir or the upload subdir).
  * @returns {string|null}
  */
 export function resolvePersistedAttachmentPath(attachmentPath, opts = {}) {
-  if (!attachmentPath || typeof attachmentPath !== 'string') return null;
-  if (isAbsolute(attachmentPath)) return null;
-  const cwd = resolve(opts.cwd || process.cwd());
-  const uploadRoot = resolve(cwd, TEMP_UPLOAD_DIR);
+  if (!attachmentPath || typeof attachmentPath !== 'string' || attachmentPath.includes('\0')) return null;
+  const cwd = resolve(opts.legacyRoot || opts.cwd || process.cwd());
+  const scoped = opts.sessionId != null || opts.yeaftDir != null;
+  const sessionRoot = sessionAttachmentRoot(opts);
+  if (scoped && !sessionRoot) return null;
   const absPath = resolve(cwd, attachmentPath);
-  const rel = relative(uploadRoot, absPath);
-  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return null;
-  return absPath;
+  let root;
+  if (isAbsolute(attachmentPath)) {
+    if (!sessionRoot || !isWithin(sessionRoot, absPath)) return null;
+    root = resolve(opts.yeaftDir);
+  } else {
+    const legacyRoot = scoped
+      ? resolve(cwd, TEMP_UPLOAD_DIR, opts.sessionId) : resolve(cwd, TEMP_UPLOAD_DIR);
+    if (!isWithin(legacyRoot, absPath)) return null;
+    root = cwd;
+  }
+  try {
+    assertNoSymlinks(root, absPath);
+    return absPath;
+  } catch {
+    return null;
+  }
 }
 
-/**
- * Read a persisted image attachment into a short-lived preview payload for the
- * web server. Returns null for non-images, bad paths, missing files, or files
- * too large to cache as previews.
- *
- * @param {{name?:string, path?:string, mimeType?:string, isImage?:boolean}} att
- * @param {{ cwd?: string }} [opts]
- * @returns {{data:string,mimeType:string,filename:string}|null}
- */
-export function persistedAttachmentPreviewPayload(att, opts = {}) {
-  if (!att || !att.isImage || !att.path) return null;
-  const absPath = resolvePersistedAttachmentPath(att.path, opts);
-  if (!absPath) return null;
+/** Shared bounded read for model history and browser preview. Never follows symlinks. */
+function readPersistedAttachment(att, opts, maxBytes) {
+  const absPath = resolvePersistedAttachmentPath(att?.path, opts);
+  if (!absPath) throw new Error('file missing or outside this Session / 文件缺失或不属于本会话');
+  const fd = openSync(absPath, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
   try {
-    const st = statSync(absPath);
-    if (!st.isFile() || st.size > MAX_PREVIEW_BYTES) return null;
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) throw new Error('not a regular file');
+    if (stat.size > maxBytes) throw new Error('image exceeds attachment size limit');
+    const buffer = Buffer.alloc(stat.size);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const read = readSync(fd, buffer, offset, buffer.length - offset, null);
+      if (!read) throw new Error('image changed while reading');
+      offset += read;
+    }
     return {
-      data: readFileSync(absPath).toString('base64'),
-      mimeType: att.mimeType || 'application/octet-stream',
+      data: buffer.toString('base64'),
+      mimeType: att.mimeType || 'image/png',
       filename: att.name || basename(absPath),
+      bytes: buffer.length,
     };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Short-lived web preview; missing/denied/oversized images have no preview. */
+export function persistedAttachmentPreviewPayload(att, opts = {}) {
+  if (!att?.isImage || !att.path) return null;
+  try {
+    const { bytes, ...payload } = readPersistedAttachment(att, opts, MAX_PREVIEW_BYTES);
+    return payload;
   } catch {
     return null;
   }
 }
+
+/**
+ * Build provider content from one canonical user row, without a Web runtime.
+ * Call once on raw transcript rows, before history-window budgeting (including
+ * recalled turns). Never persist the returned base64 or unavailable notices.
+ * Ownership comes from the requested Session, not an attachment's metadata.
+ *
+ * @param {{role:string, sessionId?:string, content?:string|Array, attachments?:Array}} row
+ * @param {{yeaftDir:string, sessionId:string, legacyRoot?:string, cwd?:string}} opts
+ *        legacyRoot is the original Agent CWD; cwd is its compatibility alias.
+ * @returns {Array} Standard provider content parts; the input row is unchanged.
+ */
+export function hydratePersistedUserAttachmentContent(row, opts = {}) {
+  const content = Array.isArray(row?.content) ? [...row.content]
+    : (row?.content ? [{ type: 'text', text: String(row.content) }] : []);
+  if (row?.role !== 'user' || row.sessionId !== opts.sessionId || !validSessionId(opts.sessionId)) return content;
+  const images = Array.isArray(row.attachments) ? row.attachments.filter(att => att?.isImage) : [];
+  let totalBytes = 0;
+  for (const att of images.slice(0, MAX_FILES_PER_TURN)) {
+    try {
+      const payload = readPersistedAttachment(att, opts, MAX_TOTAL_BYTES - totalBytes);
+      totalBytes += payload.bytes;
+      content.push({ type: 'image', source: { type: 'base64', media_type: payload.mimeType, data: payload.data } });
+    } catch (error) {
+      content.push({ type: 'text', text: `[Uploaded image unavailable / 上传图片不可用: ${att.name || 'image'} — ${error.message}. Ask the user to upload it again / 请用户重新上传。]` });
+    }
+  }
+  if (images.length > MAX_FILES_PER_TURN) content.push({ type: 'text', text: '[Uploaded image unavailable: attachment count limit exceeded.]' });
+  return content;
+}
+
+/** Provider-only projection for a canonical history array; no store decoration. */
+export function hydratePersistedAttachmentHistory(messages, opts = {}) {
+  return messages.map(row => {
+    if (row?.role !== 'user' || row.sessionId !== opts.sessionId || !validSessionId(opts.sessionId)
+      || !Array.isArray(row.attachments) || !row.attachments.some(att => att?.isImage)) return row;
+    return { ...row, content: hydratePersistedUserAttachmentContent(row, opts) };
+  });
+}
+
+/**
+ * Clone selected transcript attachments into the target Session's owned root.
+ * Missing/denied legacy references remain unavailable (never broaden access).
+ * Copy errors for available files fail the fork so CRUD can roll it back.
+ * @param {Array} rows Selected canonical source rows, including cold history.
+ * @param {{yeaftDir:string, sourceSessionId:string, targetSessionId:string}} opts
+ * @returns {Array} New rows; callers remap message and Session identities.
+ */
+export function copyPersistedSessionAttachments(rows, { yeaftDir, sourceSessionId, targetSessionId }) {
+  const sourceOptions = { yeaftDir, sessionId: sourceSessionId };
+  const copiedPaths = new Map();
+  return rows.map(row => {
+    if (row.sessionId !== sourceSessionId || !Array.isArray(row.attachments)) return row;
+    return { ...row, attachments: row.attachments.map(att => {
+      if (!att?.path) return att;
+      if (copiedPaths.has(att.path)) return { ...att, path: copiedPaths.get(att.path) };
+      if (!resolvePersistedAttachmentPath(att.path, sourceOptions)) return att;
+      const payload = readPersistedAttachment(att, sourceOptions, MAX_TOTAL_BYTES);
+      const bundle = persistYeaftAttachments([{ ...att, name: payload.filename, data: payload.data }], {
+        yeaftDir, sessionId: targetSessionId,
+      });
+      if (bundle.failed.length || bundle.promptAttachments.length !== 1) {
+        throw new Error(`Session attachment copy failed: ${bundle.failed[0]?.error || 'missing output'}`);
+      }
+      const path = bundle.promptAttachments[0].path;
+      copiedPaths.set(att.path, path);
+      return { ...att, path };
+    }) };
+  });
+}

package/yeaft/conversation/persist.js

@@ -31,6 +31,7 @@ import {
   iterateCanonicalVisibleEntriesNewestFirst,
   normalizeLiteralSearch,
 } from './visible-entry.js';
+import { copyPersistedSessionAttachments } from '../attachments.js';
 import { markConversationDirty } from './history-index-state.js';
 
 /**
@@ -2035,7 +2036,8 @@ export class ConversationStore {
       `m${String(firstSeq + index).padStart(4, '0')}`,
     ]));
     const remapId = id => idMap.get(id) || id;
-    const copies = rows.map(row => {
+    const assetRows = copyPersistedSessionAttachments(rows, { yeaftDir: this.#dir, sourceSessionId, targetSessionId });
+    const copies = assetRows.map(row => {
       const copy = {
         ...row,
         id: idMap.get(row.id),

package/yeaft/engine.js

@@ -42,6 +42,7 @@ import {
 } from './history-window.js';
 import { recallConversationTurns } from './conversation/history-index.js';
 import { parseSeqFromId } from './conversation/persist.js';
+import { hydratePersistedAttachmentHistory } from './attachments.js';
 import { isVpForeign, readContent as readScopeContent } from './memory/store.js';
 import { ActiveMemorySet } from './memory/ams.js';
 import { cleanMemoryPromptText } from './memory/prompt-cleanup.js';
@@ -2180,7 +2181,13 @@ export class Engine {
       if (Number.isFinite(beforeSeq)) {
         const loadHistory = this.#conversationStore.loadProviderHistoryBySession
           || this.#conversationStore.loadRecentBySession;
-        const tail = await loadHistory.call(this.#conversationStore, runtimeSessionId, recentTurnCap, { beforeSeq });
+        // Materialize only provider copies from this Session's controlled assets.
+        // Hydrate before budgeting; never mutate/persist base64 into canonical rows.
+        const attachmentOptions = { yeaftDir: this.#yeaftDir, sessionId: runtimeSessionId, legacyRoot: process.cwd() };
+        const tail = hydratePersistedAttachmentHistory(
+          await loadHistory.call(this.#conversationStore, runtimeSessionId, recentTurnCap, { beforeSeq }),
+          attachmentOptions,
+        );
         messages = tail.filter(m => parseSeqFromId(m.id) < beforeSeq
           && (m.role !== 'tool' || !queryVpId || m.speakerVpId === queryVpId))
           .map(m => {
@@ -2193,7 +2200,19 @@ export class Engine {
             const recalled = await recallConversationTurns(this.#yeaftDir, runtimeSessionId, prompt, {
               beforeSeq, limit: relatedTurnCap,
             });
-            relatedHistoryTurns = recalled.turns || [];
+            relatedHistoryTurns = (recalled.turns || []).map(turn => ({
+              ...turn,
+              // Recall indexes intentionally contain text/identities, not assets.
+              // Reload only the exact same-Session user anchor's references.
+              messages: hydratePersistedAttachmentHistory((turn.messages || []).map(row => {
+                if (row.role !== 'user' || row.sessionId !== runtimeSessionId
+                  || !Number.isFinite(row.seq) || row.seq >= beforeSeq) return row;
+                const anchor = this.#conversationStore.loadRecentBySession(runtimeSessionId, 1, { beforeSeq: row.seq + 1 })
+                  .find(candidate => candidate.role === 'user' && candidate.sessionId === runtimeSessionId
+                    && candidate.id === row.messageId && parseSeqFromId(candidate.id) === row.seq);
+                return anchor?.attachments ? { ...row, attachments: anchor.attachments } : row;
+              }), attachmentOptions),
+            }));
             historyRecallMeta = { source: 'messages', status: 'ready', ...recalled.meta };
           } catch (error) {
             // Cold/stale index degrades to recent history, never a full scan.
@@ -4279,6 +4298,7 @@ export class Engine {
       // break out of the outer while-loop cleanly once the current
       // tool batch finishes reporting.
       let abortedDuringTools = false;
+      let batchHasUnseenImages = false;
       /** @type {string[]} */
       const pendingDupReminders = [];
       let terminateAfterDuplicateBatch = false;
@@ -4439,6 +4459,7 @@ export class Engine {
 
         let output;
         let displayImages = [];
+        let modelImages = [];
         let isError = false;
         let reusedReadOnlyResult = false;
         let reusedReadOnlyCallId = null;
@@ -4575,6 +4596,7 @@ export class Engine {
           const cachedReadOnly = readOnlyToolResults.get(duplicateKey);
           if (!readOnlyToolReuseDisabled && cachedReadOnly && cacheableTool) {
             output = cachedReadOnly.output;
+            modelImages = cachedReadOnly.modelImages || [];
             isError = Boolean(cachedReadOnly.isError);
             reusedReadOnlyResult = true;
             reusedReadOnlyCallId = cachedReadOnly.callId || null;
@@ -4619,6 +4641,13 @@ export class Engine {
             }
             displayImages = extractDisplayImages(tc.name, output);
             if (displayImages.length > 0) {
+              // UI asset delivery and model vision are independent consumers.
+              // Capture provider parts before yielding to the UI bridge; never
+              // persist base64 in transcript/exec-log or textual tool output.
+              modelImages = displayImages.map(image => ({
+                type: 'image',
+                source: { type: 'base64', media_type: image.mimeType, data: image.previewData.data },
+              }));
               output = stripDisplayImageData(output, displayImages);
             }
             isError = toolErrorOutput === 'json-error-envelope' && isToolErrorOutput(output);
@@ -4752,6 +4781,7 @@ export class Engine {
             && !readOnlyToolReuseDisabled && cacheableTool) {
           readOnlyToolResults.set(duplicateKey, {
             output,
+            modelImages,
             isError,
             callId: tc.id,
           });
@@ -4764,10 +4794,13 @@ export class Engine {
           toolName: tc.name,
           language: this.#config?.language,
         });
+        if (modelImages.length > 0) batchHasUnseenImages = true;
         const toolMessage = {
           role: 'tool',
           toolCallId: tc.id,
-          content: contextOutput,
+          content: modelImages.length > 0
+            ? [{ type: 'text', text: contextOutput }, ...modelImages]
+            : contextOutput,
           isError,
         };
         conversationMessages.push(toolMessage);
@@ -4896,7 +4929,9 @@ export class Engine {
       const completedToolLoops = toolLoopTurns + 1;
       const t1BatchDue = completedToolLoops - lastT1AtLoopCount
         >= TOOL_LOOP_REFLECTION_INTERVAL;
-      if (t1BatchDue && !toolBatchBarrier
+      // Text-only reflection cannot consume visual input. Defer folding until
+      // the primary provider has received this image batch at least once.
+      if (t1BatchDue && !batchHasUnseenImages && !toolBatchBarrier
           && !abortedDuringTools && !signal?.aborted) {
         const t1DedupKey = `${queryNumber}:t1-loop:${completedToolLoops}`;
         if (this.#reflectedTurns.has(t1DedupKey)) {

package/yeaft/llm/adapter.js

@@ -59,9 +59,9 @@ import { utf8PrefixWithinBytes } from '../utf8.js';
  * @typedef {{ thinking: string, signature: string }} ThinkingBlock
  *
  * @typedef {{ role: 'system', content: string }} SystemMessage
- * @typedef {{ role: 'user', content: string }} UserMessage
+ * @typedef {{ role: 'user', content: string|Array<object> }} UserMessage
  * @typedef {{ role: 'assistant', content: string, toolCalls?: UnifiedToolCall[], thinkingBlocks?: ThinkingBlock[] }} AssistantMessage
- * @typedef {{ role: 'tool', toolCallId: string, content: string, isError?: boolean }} ToolMessage
+ * @typedef {{ role: 'tool', toolCallId: string, content: string|Array<object>, isError?: boolean }} ToolMessage
  *
  * @typedef {SystemMessage | UserMessage | AssistantMessage | ToolMessage} UnifiedMessage
  */

package/yeaft/llm/openai-responses.js

@@ -205,7 +205,10 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
         input.push({
           type: 'function_call_output',
           call_id: msg.toolCallId,
-          output: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+          output: Array.isArray(msg.content) && msg.content.length > 0
+              && msg.content.every(part => part && ['text', 'image', 'document'].includes(part.type))
+            ? this.#translateUserContent(msg.content)
+            : (typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)),
         });
       }
     }

package/yeaft/tool-folding/index.js

@@ -125,6 +125,16 @@ export function buildDuplicateReminder({ toolName, count, lastResultBrief }) {
     + `Consider whether re-running this tool is necessary or if you should try a different approach.`;
 }
 
+function toolOutputForReflection(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content) && content.every(part => part && ['text', 'image', 'document'].includes(part.type))) {
+    // Reflection consumes text, not a base64 dump of visual context. The image
+    // has already been delivered to the primary model in the paired result.
+    return content.map(part => part.type === 'text' ? part.text : `[${part.type} content omitted from reflection]`).join('\n');
+  }
+  return JSON.stringify(content);
+}
+
 /**
  * Convert assistant.toolCalls + matching tool results into the
  * { name, input, output, isError } pairs the reflector prompt expects.
@@ -159,14 +169,14 @@ export function extractToolPairsFromRange(messages, startIdx, endIdx) {
     } else if (m.role === 'tool') {
       const ent = m.toolCallId ? byId.get(m.toolCallId) : null;
       if (ent) {
-        ent.output = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+        ent.output = toolOutputForReflection(m.content);
         ent.isError = !!m.isError;
       } else {
         // Orphan tool result — still include for completeness.
         pairs.push({
           name: '(orphan)',
           input: {},
-          output: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+          output: toolOutputForReflection(m.content),
           isError: !!m.isError,
         });
       }

package/yeaft/tools/registry.js

@@ -238,6 +238,17 @@ function truncateUtf8(text, maxBytes) {
 }
 
 export function truncateToolResultIfNeeded(output, { toolName, language } = {}) {
+  // Provider content parts are not JSON text. Bound their text together while
+  // preserving binary blocks; history-window budgets/omits attachments whole.
+  // Arbitrary structured tool output still follows the legacy JSON path.
+  if (Array.isArray(output) && output.length > 0
+      && output.every(part => part && ['text', 'image', 'document'].includes(part.type))) {
+    const text = output.filter(part => part.type === 'text').map(part => part.text || '').join('\n');
+    return [
+      ...(text ? [{ type: 'text', text: truncateToolResultIfNeeded(text, { toolName, language }) }] : []),
+      ...output.filter(part => part.type !== 'text'),
+    ];
+  }
   const text = normalizeToolOutput(output);
   const originalBytes = Buffer.byteLength(text, 'utf8');
   if (originalBytes <= TOOL_RESULT_MAX_BYTES) return text;

package/yeaft/tools/view-image.js

@@ -123,8 +123,9 @@ export default defineTool({
     en: `Load a local image file and attach it to the conversation so the LLM can see it.
 
 Returns a base64 data URI (\`image\` field) plus metadata (format, dimensions,
-size). The caller/bridge is responsible for turning the data URI into the
-provider-specific image content block.
+size). The engine delivers the image as a native multimodal tool result.
+Inspect the whole image first. Crop/zoom only details that are unreadable; OCR
+is optional for text extraction, not a prerequisite for seeing the image.
 
 When to call:
   - User references a local image path (screenshot, design, log/chart) and
@@ -151,8 +152,8 @@ Max size: 20 MiB by default (configurable via ctx.maxImageBytes).
 Path must live under the project directory or an explicit host allowlist.`,
     zh: `加载本地图片文件并附加到对话中，使 LLM 可以查看。
 
-返回 base64 data URI（image 字段）及元数据（格式、尺寸、大小）。调用方/桥接层负责将 data URI 转换为
-provider 特定的图片内容块。
+返回 base64 data URI（image 字段）及元数据（格式、尺寸、大小）。引擎将图片作为原生多模态工具结果交给模型。
+先直接查看整图；仅对确实看不清的细节裁剪/放大。OCR 用于需要时提取文字，不是看图的前置步骤。
 
 何时调用：
   - 用户引用本地图片路径（截图、设计稿、日志/图表）并要求你读取、分析或描述它。

package/yeaft/web-bridge.js

@@ -1454,12 +1454,15 @@ function projectPersistedToVisibleHistoryEntry(m) {
   return entry && (entry.role === 'user' || entry.role === 'assistant') ? entry : null;
 }
 
-function hydrateHistoryAttachmentPreviews(attachments) {
+function hydrateHistoryAttachmentPreviews(attachments, sessionId) {
   if (!Array.isArray(attachments) || attachments.length === 0) return [];
   return attachments.map((att) => {
     if (!att || typeof att !== 'object') return att;
     if (!att.isImage || att.preview || att.previewData) return att;
-    const payload = persistedAttachmentPreviewPayload(att);
+    const payload = sessionId ? persistedAttachmentPreviewPayload(att, {
+      yeaftDir: session?.yeaftDir || ctx.CONFIG?.yeaftDir || DEFAULT_YEAFT_DIR,
+      sessionId,
+    }) : null;
     return payload ? { ...att, previewData: payload } : att;
   });
 }
@@ -1538,7 +1541,7 @@ function projectVisibleHistoryChunkMessages(messages = []) {
       threadId: m.threadId || m.turnId || 'main',
       ...(m.turnId ? { turnId: m.turnId } : {}),
       ...(m.imageAssetAnchor === true ? { imageAssetAnchor: true } : {}),
-      ...(Array.isArray(m.attachments) && m.attachments.length > 0 ? { attachments: hydrateHistoryAttachmentPreviews(m.attachments) } : {}),
+      ...(Array.isArray(m.attachments) && m.attachments.length > 0 ? { attachments: hydrateHistoryAttachmentPreviews(m.attachments, m.sessionId) } : {}),
       ...(m.quote ? { quote: m.quote } : {}),
       ...(Array.isArray(m.images) && m.images.length > 0 ? { images: m.images } : {}),
       ...(m.speakerVpId ? { speakerVpId: m.speakerVpId } : {}),
@@ -1596,7 +1599,7 @@ function emitLegacyHistoryOutputFrames(replayEntries) {
         message: {
           content: entry.content,
           id: entry.id || null,
-          ...(Array.isArray(entry.attachments) && entry.attachments.length > 0 ? { attachments: hydrateHistoryAttachmentPreviews(entry.attachments) } : {}),
+          ...(Array.isArray(entry.attachments) && entry.attachments.length > 0 ? { attachments: hydrateHistoryAttachmentPreviews(entry.attachments, entry.sessionId) } : {}),
           ...(entry.quote ? { quote: entry.quote } : {}),
         },
         ts: entry.ts || null,
@@ -4920,9 +4923,9 @@ async function runYeaftSessionSend(msg) {
   // ── Attachments (images + files) ───────────────────────────────
   // Server has already resolved fileId → { name, mimeType, data:base64,
   // isImage } via the client-conversation.js relay
-  // for `yeaft_*`). We persist files to disk under the agent's CWD so
-  // file-tools (file-read / bash) can pick them up with relative paths,
-  // and we build per-image content blocks for the LLM call. The
+  // for `yeaft_*`). Session files belong to the instance data root, not
+  // the agent CWD or project workDir. Absolute controlled references work
+  // with file-tools; per-image content blocks go directly to the model. The
   // resolved metadata WITHOUT base64 rides on coord.ingest meta so it
   // shows up in the persisted group log and on the envelope every VP
   // driver receives.
@@ -4931,9 +4934,10 @@ async function runYeaftSessionSend(msg) {
   const attachmentsStart = perfNowMs();
   if (inboundFiles.length > 0) {
     try {
-      attachmentBundle = persistYeaftAttachments(inboundFiles, { subdir: sessionId });
+      attachmentBundle = persistYeaftAttachments(inboundFiles, { yeaftDir, sessionId });
     } catch (err) {
       console.warn('[Yeaft] yeaft_session_chat: attachment persist failed', err?.message || err);
+      attachmentBundle.failed = inboundFiles.map(file => ({ name: file?.name || '<unknown>', error: err?.message || String(err) }));
     }
   }
   // Surface partial / total upload failures to the user. We don't abort