@yeaft/webchat-agent 0.1.720 → 0.1.722

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.720",
+  "version": "0.1.722",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/attachments.js

@@ -0,0 +1,224 @@
+/**
+ * attachments.js — Unify (group/feature) attachment handling.
+ *
+ * Mirrors the Chat-mode pipeline implemented in `agent/workbench/transfer.js`,
+ * adapted to the Unify architecture:
+ *
+ *   - Chat mode has a per-conversation `state.workDir` and a single
+ *     in-flight Claude SDK query — `transfer.js` enqueues a constructed
+ *     user message into that query's `inputStream`.
+ *   - Unify 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
+ *     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` / `client-crew.js`: each entry is
+ * `{ name, mimeType, data: <base64>, isImage }` — the `pendingFiles`
+ * `fileId` was already consumed by the server before `forwardToAgent`.
+ *
+ * Output (single bundle, all named for the role each piece plays in
+ * the LLM call):
+ *   - `promptAttachments`: persisted metadata `{ name, path, mimeType,
+ *     isImage }` suitable for the group jsonl-log (NO base64 — must
+ *     stay small).
+ *   - `promptSuffix`: text to append to the user's prompt so the model
+ *     sees the file list in the same form Chat mode uses.
+ *   - `promptParts`: an array of `{ type:'image', source:{ data, mediaType } }`
+ *     blocks for images, ready to be combined with a text block for
+ *     `engine.query({ promptParts })`. Empty when no images are present.
+ *   - `failed`: list of `{ name, error }` for entries that could not
+ *     be persisted (disk full, bad base64, ...). The caller surfaces
+ *     this so the UI can tell the user *which* file blew up rather
+ *     than swallowing it in a console.warn.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+// Same dir name Chat mode uses, so ".gitignore" rules and tool-side
+// expectations stay identical.
+const TEMP_UPLOAD_DIR = '.claude-tmp-attachments';
+
+// Caps. Any ingestion path without caps is a denial-of-service waiting
+// to be discovered. Cheap insurance.
+//   - MAX_FILES_PER_TURN: matches the UI's per-message attachment cap.
+//   - MAX_TOTAL_BYTES:    50 MiB across all files in one turn.
+export const MAX_FILES_PER_TURN = 16;
+export const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+
+/**
+ * Sanitize a user-supplied filename's basename for use as an on-disk
+ * path component. We KEEP Unicode (CJK, emoji, accented letters) —
+ * the disk path is opaque, the UI uses `promptAttachments[].name` for
+ * display, and tool consumers (file-read, bash) handle UTF-8 paths
+ * fine on Linux/macOS. We only strip what is structurally dangerous:
+ *   - path separators (`/`, `\`)
+ *   - NUL bytes
+ *   - leading dots (so a user can't write `.bashrc` into the temp dir)
+ *   - leading `-` (so the path can't be mistaken for a CLI flag)
+ *   - control characters
+ */
+function sanitizeBaseName(base) {
+  let s = String(base ?? '')
+    .replace(/[\/\\\0]/g, '_')
+    // Strip C0 controls (\u0000–\u001F) and DEL (\u007F).
+    .replace(/[\u0000-\u001f\u007f]/g, '_')
+    // Trim runs of leading dots/dashes that would create dotfiles or
+    // CLI-flag-looking paths.
+    .replace(/^[.\-]+/, '');
+  if (!s) s = 'file';
+  // Hard cap on length — most filesystems are fine with 255 bytes per
+  // name, and the random suffix + extension still need to fit.
+  if (s.length > 80) s = s.slice(0, 80);
+  return s;
+}
+
+/**
+ * Persist resolved files to disk and build the LLM-side payload pieces.
+ *
+ * @param {Array<{name:string, mimeType:string, data:string, isImage?:boolean}>} files
+ *        Resolved files from server (pendingFiles → base64).
+ * @param {Object} [opts]
+ * @param {string} [opts.subdir]   Sub-folder under TEMP_UPLOAD_DIR
+ *        (e.g. groupId). Lets multiple groups co-exist without clobbering.
+ * @param {string} [opts.cwd]      Override base dir; defaults to process.cwd()
+ *        which is what unify tools (file-read, bash, ...) resolve relative
+ *        paths against.
+ * @returns {{
+ *   promptAttachments: Array<{name:string, path:string, mimeType:string, isImage:boolean}>,
+ *   promptSuffix: string,
+ *   promptParts: Array<{type:'image', source:{type:'base64', mediaType:string, data:string}}>,
+ *   failed: Array<{name:string, error:string}>
+ * }}
+ */
+export function persistUnifyAttachments(files, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  // Subdir is OURS — it must remain ASCII-safe because we generate it
+  // from groupId. 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);
+
+  if (!Array.isArray(files) || files.length === 0) {
+    return { promptAttachments: [], promptSuffix: '', promptParts: [], failed: [] };
+  }
+
+  // Enforce per-turn file count cap. Excess entries are surfaced as
+  // failures so the UI can tell the user what got dropped.
+  const accepted = files.slice(0, MAX_FILES_PER_TURN);
+  const rejectedByCount = files.slice(MAX_FILES_PER_TURN);
+
+  if (!existsSync(uploadDir)) {
+    mkdirSync(uploadDir, { recursive: true });
+  }
+
+  const promptAttachments = [];
+  const promptParts = [];
+  const failed = rejectedByCount.map((f) => ({
+    name: f?.name || '<unknown>',
+    error: `too many files (cap=${MAX_FILES_PER_TURN})`,
+  }));
+
+  let totalBytes = 0;
+
+  for (const file of accepted) {
+    if (!file || !file.name || !file.data) {
+      // Silently skip null/empty entries — these are caller bugs, not
+      // user errors, and the existing test suite asserts they don't
+      // appear in `failed`. (Backwards compatible.)
+      continue;
+    }
+    try {
+      const ext = extname(file.name);
+      const base = basename(file.name, ext);
+      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);
+
+      const buffer = Buffer.from(file.data, 'base64');
+
+      // Total-bytes cap. Check BEFORE write so we don't half-fill the
+      // disk and then bail.
+      if (totalBytes + buffer.length > MAX_TOTAL_BYTES) {
+        failed.push({
+          name: file.name,
+          error: `total upload exceeds ${MAX_TOTAL_BYTES} bytes`,
+        });
+        continue;
+      }
+      totalBytes += buffer.length;
+
+      writeFileSync(absPath, buffer);
+
+      const isImage = !!file.isImage || (file.mimeType || '').startsWith('image/');
+      promptAttachments.push({
+        name: file.name,
+        path: relPath,
+        mimeType: file.mimeType || 'application/octet-stream',
+        isImage,
+      });
+
+      if (isImage) {
+        promptParts.push({
+          type: 'image',
+          source: {
+            type: 'base64',
+            // Both adapters accept either `mediaType` or `media_type`
+            // (see openai-responses.js:#translateUserContent and the
+            // Anthropic upstream contract). Use the camelCase form to
+            // match `openai-responses.js` exactly.
+            mediaType: file.mimeType || 'image/png',
+            data: file.data,
+          },
+        });
+      }
+    } catch (err) {
+      failed.push({
+        name: file?.name || '<unknown>',
+        error: err?.message || String(err),
+      });
+    }
+  }
+
+  let promptSuffix = '';
+  if (promptAttachments.length > 0) {
+    const lines = promptAttachments.map((f) =>
+      `- ${f.path} (${f.isImage ? 'image' : f.mimeType})`
+    );
+    promptSuffix = `\n\n[Uploaded files]\n${lines.join('\n')}`;
+  }
+
+  return { promptAttachments, promptSuffix, promptParts, failed };
+}
+
+/**
+ * Strip base64 data from a resolved-files array so it can be safely
+ * persisted (e.g. into a group jsonl-log or memory entry). Keeps name,
+ * mimeType, isImage, and the on-disk path returned by
+ * `persistUnifyAttachments`.
+ *
+ * @param {Array<{name:string, path:string, mimeType:string, isImage:boolean}>} promptAttachments
+ * @returns {Array<{name:string, path:string, mimeType:string, isImage:boolean}>}
+ */
+export function attachmentsForPersistence(promptAttachments) {
+  if (!Array.isArray(promptAttachments)) return [];
+  return promptAttachments.map((f) => ({
+    name: f.name,
+    path: f.path,
+    mimeType: f.mimeType,
+    isImage: !!f.isImage,
+  }));
+}

package/unify/engine.js

@@ -991,9 +991,19 @@ export class Engine {
    * @param {string} [params.scenario='chat'] - task-327b: scenario tag
    *   forwarded to the effort decision tree. See effort.js
    *   SCENARIO_EFFORT. Unknown values fall through to 'high'.
+   * @param {Array<{type:string, source?:object, text?:string}>} [params.promptParts] -
+   *   PR #721: optional content-array form of the user message used
+   *   when attachments are present. Each entry is either an
+   *   `{type:'image', source:{type:'base64', mediaType, data}}` block
+   *   (one per uploaded image) or a `{type:'text', text}` block (the
+   *   text prompt body, including any [Uploaded files] suffix). When
+   *   supplied and non-empty, the LLM call uses this array as the
+   *   user-message content; the string `prompt` is then only used for
+   *   logging / history. When omitted the engine falls back to the
+   *   string-prompt shape (no regression for existing callers).
    * @yields {EngineEvent}
    */
-  async *query({ prompt, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement } = {}) {
+  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement } = {}) {
     if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
       yield {
         type: 'error',
@@ -1002,6 +1012,14 @@ export class Engine {
       };
       return;
     }
+    // promptParts (optional): a content-array form of the user message
+    // (e.g. [{type:'image',source:{...}}, {type:'text',text:'@vp-x ...'}]).
+    // When supplied, it REPLACES the trailing `{role:'user',content:prompt}`
+    // entry built into conversationMessages — the string `prompt` is still
+    // used for memory recall, system prompt rendering, and turn previews
+    // because those layers all need plain text. Adapter side already
+    // accepts content arrays for user messages (anthropic.js:72,
+    // openai-responses.js:#translateUserContent).
 
     // task-327b: `/max` / `/high` / `/medium` / `/low` prefix override.
     // Explicit caller-supplied userEffort wins over the prefix.
@@ -1044,7 +1062,7 @@ export class Engine {
     const runSignal = abortCtrl.signal;
 
     try {
-      yield* this.#runQuery({ prompt: effectivePrompt, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement });
+      yield* this.#runQuery({ prompt: effectivePrompt, promptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement });
     } finally {
       if (signal) {
         try { signal.removeEventListener('abort', onExternalAbort); } catch { /* ignore */ }
@@ -1062,7 +1080,7 @@ export class Engine {
    * in a try/finally without indenting the whole loop.
    * @private
    */
-  async *#runQuery({ prompt, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement }) {
+  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement }) {
 
     // ─── Pre-query: FTS5 Memory Recall + AMS snapshot ─────
     // Memory has a SINGLE render outlet now (DESIGN-PROMPT §3 ③):
@@ -1189,11 +1207,17 @@ export class Engine {
         ]
       : [];
 
-    // Build conversation: optional compact head + existing messages + new user message
+    // Build conversation: optional compact head + existing messages + new user message.
+    // If `promptParts` was supplied (image/file attachments), use the array form
+    // so the adapter sees image content blocks alongside the text. Otherwise the
+    // legacy string form keeps prompt-cache behavior identical.
+    const finalUserContent = (Array.isArray(promptParts) && promptParts.length > 0)
+      ? promptParts
+      : prompt;
     const conversationMessages = [
       ...compactMessages,
       ...messages,
-      { role: 'user', content: prompt },
+      { role: 'user', content: finalUserContent },
     ];
 
     // PR-L: T2 carry-forward. If a previous query()'s end-of-turn

package/unify/groups/coordinator.js

@@ -68,8 +68,37 @@ export function createCoordinator(group, options = {}) {
     const mentions = parseMentions(input.text);
 
     // Persist first — audit log / replay works even if dispatch has bugs.
+    //
+    // Convention: any field on `input` that starts with `_` is treated
+    // as ephemeral and is forwarded to the envelope (so per-turn driver
+    // payloads — image base64 blocks, prompt suffixes — reach the LLM
+    // call) but is NEVER passed to appendMessage. The jsonl-log must
+    // stay lean: base64 in audit history would blow up replay.
+    //
+    // The split is enforced structurally — see the assertion below the
+    // partition loop. Don't loosen it. If a new ephemeral key is added,
+    // it gets the `_` prefix at its source and inherits the protection
+    // for free; no allowlist to maintain.
+    const persistInput = {};
+    const ephemeral = {};
+    for (const [k, v] of Object.entries(input)) {
+      if (typeof k === 'string' && k.startsWith('_')) {
+        ephemeral[k] = v;
+      } else {
+        persistInput[k] = v;
+      }
+    }
+    // Structural guarantee: nothing with a `_` prefix may reach the
+    // jsonl-log via `persistInput`. If this ever throws, the `_` rule
+    // got bypassed — fix the caller, not this assertion.
+    {
+      const leaked = Object.keys(persistInput).filter((k) => typeof k === 'string' && k.startsWith('_'));
+      if (leaked.length > 0) {
+        throw new Error(`coordinator.ingest: ephemeral fields leaked into persisted record: ${leaked.join(', ')}`);
+      }
+    }
     const stored = group.appendMessage({
-      ...input,
+      ...persistInput,
       mentions,
       role: input.role || (fromUser ? 'user' : 'assistant'),
     });
@@ -96,7 +125,7 @@ export function createCoordinator(group, options = {}) {
     }
 
     if (selection.reason === 'broadcast') {
-      const envelope = makeEnvelope(stored, meta, 'broadcast');
+      const envelope = makeEnvelope(stored, meta, 'broadcast', ephemeral);
       for (const vpId of selection.dispatched) deliver(vpId, envelope);
       return {
         message: stored,
@@ -110,7 +139,7 @@ export function createCoordinator(group, options = {}) {
 
     if (selection.reason === 'mention') {
       for (const vpId of selection.dispatched) {
-        deliver(vpId, makeEnvelope(stored, meta, 'mention'));
+        deliver(vpId, makeEnvelope(stored, meta, 'mention', ephemeral));
       }
       return {
         message: stored,
@@ -121,7 +150,7 @@ export function createCoordinator(group, options = {}) {
     }
 
     if (selection.reason === 'fallback' && selection.fallback) {
-      deliver(selection.fallback, makeEnvelope(stored, meta, 'fallback'));
+      deliver(selection.fallback, makeEnvelope(stored, meta, 'fallback', ephemeral));
       return {
         message: stored,
         dispatched: selection.dispatched,
@@ -146,12 +175,16 @@ export function createCoordinator(group, options = {}) {
   };
 }
 
-function makeEnvelope(msg, meta, trigger) {
+function makeEnvelope(msg, meta, trigger, ephemeral = {}) {
   return {
     groupId: meta.id,
     taskId: msg.taskId || null,
     msg,
     trigger, // 'broadcast' | 'mention' | 'fallback'
+    // Ephemeral fields (any `_`-prefixed key on coord.ingest input).
+    // Used to ferry per-turn payloads (e.g. image base64 blocks) that
+    // must reach the driver but must NOT be persisted to the group log.
+    ...ephemeral,
   };
 }
 

package/unify/groups/group-store.js

@@ -69,11 +69,23 @@ export function openGroup(groupsRoot, groupId) {
     /**
      * Append a message to the group log. Assigns an id if absent.
      * Returns the stored record (with id + ts).
+     *
+     * Structural invariant: NO field on `record` may start with `_`.
+     * The `_` prefix is reserved for ephemeral per-turn payloads (image
+     * base64, prompt suffixes) that must reach the driver but must
+     * never hit the persisted jsonl-log. If this throws, the caller
+     * forgot to partition ephemeral fields off — fix the caller.
      */
     appendMessage(record) {
       if (!record || typeof record !== 'object') {
         throw new Error('appendMessage: record required');
       }
+      {
+        const leaked = Object.keys(record).filter((k) => typeof k === 'string' && k.startsWith('_'));
+        if (leaked.length > 0) {
+          throw new Error(`appendMessage: ephemeral fields leaked into log: ${leaked.join(', ')}`);
+        }
+      }
       const stored = {
         id: record.id || nextMsgId(),
         ts: record.ts || new Date().toISOString(),

package/unify/llm/router.js

@@ -17,6 +17,7 @@
 
 import { LLMAdapter } from './adapter.js';
 import { getThinkingCapability, normalizeEffort } from '../models.js';
+import { pairSanitize } from '../pair-sanitize.js';
 
 /**
  * task-327a: feature-flag accessor. Read lazily so tests can flip.
@@ -58,6 +59,66 @@ export function filterEffortForModel(params) {
   return { ...params, effort: norm };
 }
 
+/**
+ * task-715: last-line-of-defense pair sanitize at the wire.
+ *
+ * `pairSanitize` already runs in two upstream paths
+ * (`conversation/persist.js#loadRecentByGroup` and
+ * `history-compact.js#compactHistory`), but the engine's main loop
+ * mutates `conversationMessages` AFTER those — appending tool results
+ * mid-loop, archiving bulky tool results into stubs, and (in failure
+ * paths) potentially leaving an assistant `tool_use` whose matching
+ * `role:'tool'` was dropped or never produced. Anthropic's Messages
+ * API rejects either shape with HTTP 400 ("Each tool_use block must
+ * have a corresponding tool_result block in the next message").
+ *
+ * The router is the SINGLE choke point through which every
+ * adapter.stream() / adapter.call() flows. Sanitizing here means no
+ * caller can accidentally bypass the guard — including the per-VP
+ * group-mode path that surfaced the bug.
+ *
+ * Implementation: call `pairSanitize` exactly once and compare the
+ * result to the input. If nothing changed (length matches AND each
+ * assistant kept its toolCalls count), return the original `params`
+ * reference so the happy path is one O(n) walk + one comparison
+ * walk, no allocation downstream. If something WAS dropped, return
+ * `{ ...params, messages: cleaned }` and log a diagnostic so a
+ * recurrence stays traceable in agent logs.
+ *
+ * @param {object} params
+ * @returns {object}
+ */
+export function sanitizeMessagesForWire(params) {
+  if (!params || !Array.isArray(params.messages)) return params;
+  const cleaned = pairSanitize(params.messages);
+  if (sliceUnchanged(params.messages, cleaned)) return params;
+  console.warn(
+    `[router] dropped tool_use/tool_result orphans before wire send: ` +
+    `${params.messages.length} → ${cleaned.length} messages`
+  );
+  return { ...params, messages: cleaned };
+}
+
+/**
+ * Cheap structural equality between the original messages array and
+ * the post-sanitize result. Same length AND every assistant kept its
+ * toolCalls count = no orphans were dropped. We do NOT compare full
+ * deep equality — `pairSanitize` only ever shrinks, never reorders or
+ * mutates payloads.
+ */
+function sliceUnchanged(original, cleaned) {
+  if (original.length !== cleaned.length) return false;
+  for (let i = 0; i < original.length; i += 1) {
+    const a = original[i];
+    const b = cleaned[i];
+    if (!a || !b) continue;
+    const aCalls = Array.isArray(a.toolCalls) ? a.toolCalls.length : 0;
+    const bCalls = Array.isArray(b.toolCalls) ? b.toolCalls.length : 0;
+    if (aCalls !== bCalls) return false;
+  }
+  return true;
+}
+
 /**
  * AdapterRouter — Implements LLMAdapter, routes by model → provider.
  */
@@ -178,8 +239,9 @@ export class AdapterRouter extends LLMAdapter {
    */
   async *stream(params) {
     const filtered = filterEffortForModel(params);
-    const adapter = await this.#resolveAdapter(filtered.model);
-    yield* adapter.stream(filtered);
+    const sanitized = sanitizeMessagesForWire(filtered);
+    const adapter = await this.#resolveAdapter(sanitized.model);
+    yield* adapter.stream(sanitized);
   }
 
   /**
@@ -190,8 +252,9 @@ export class AdapterRouter extends LLMAdapter {
    */
   async call(params) {
     const filtered = filterEffortForModel(params);
-    const adapter = await this.#resolveAdapter(filtered.model);
-    return adapter.call(filtered);
+    const sanitized = sanitizeMessagesForWire(filtered);
+    const adapter = await this.#resolveAdapter(sanitized.model);
+    return adapter.call(sanitized);
   }
 
   /**

package/unify/web-bridge.js

@@ -53,6 +53,7 @@ import {
 } from './history-compact.js';
 import { createFeatureArc } from './feature-arc.js';
 import { getFeatureStore } from './tools/feature-tools.js';
+import { persistUnifyAttachments, attachmentsForPersistence } from './attachments.js';
 
 /** @type {import('./session.js').Session | null} */
 let session = null;
@@ -384,10 +385,24 @@ function ensureDriverRunning(groupId, vpId) {
       // the legacy fan-out path so the model sees the same surface form
       // it always has.
       const text = envelope?.msg?.text || '';
-      const prompt = `@vp-${vpId} ${text}`;
+      // Attachments ride on the envelope's ephemeral fields (set by
+      // handleUnifyGroupChat → coord.ingest). When images are present
+      // we append the file list to the text prompt (same surface as
+      // Chat mode) AND build a content-array form so the LLM sees the
+      // image bytes alongside the text. Pure file-only uploads only
+      // need the suffix; engine.query falls back to string mode.
+      const inboundSuffix = envelope?._promptSuffix || '';
+      const inboundParts = Array.isArray(envelope?._promptParts)
+        ? envelope._promptParts
+        : [];
+      const prompt = `@vp-${vpId} ${text}${inboundSuffix}`;
+      const promptParts = inboundParts.length > 0
+        ? [...inboundParts, { type: 'text', text: prompt }]
+        : null;
       try {
         await runVpTurn({
           prompt,
+          promptParts,
           groupId,
           vpId,
           turnId,
@@ -1170,7 +1185,13 @@ function handleEngineEvent(event, hctx) {
 export async function handleUnifyGroupChat(msg) {
   if (!msg || typeof msg !== 'object') return;
   const { text } = msg;
-  if (!text?.trim()) return;
+  // PR #721: image-only send is allowed — text may be empty when the
+  // user attached files only. The frontend synthesizes a placeholder
+  // string in `sendUnifyGroupChat`, so by the time we get here `text`
+  // should always be non-empty; but defend anyway in case an API
+  // caller sends a bare attachment payload.
+  const hasFiles = Array.isArray(msg.files) && msg.files.length > 0;
+  if (!text?.trim() && !hasFiles) return;
   const mentions = Array.isArray(msg.mentions) ? msg.mentions : [];
   const groupId = (typeof msg.groupId === 'string' && msg.groupId.trim())
     ? msg.groupId.trim()
@@ -1328,6 +1349,38 @@ export async function handleUnifyGroupChat(msg) {
     console.warn('[Unify] unify_group_chat: selective abort pre-pass failed', err?.message || err);
   }
 
+  // ── Attachments (images + files) ───────────────────────────────
+  // Server has already resolved fileId → { name, mimeType, data:base64,
+  // isImage } via the same path crew uses (client-conversation.js relay
+  // for `unify_*`). 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
+  // 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.
+  const inboundFiles = Array.isArray(msg.files) ? msg.files : [];
+  let attachmentBundle = { promptAttachments: [], promptSuffix: '', promptParts: [], failed: [] };
+  if (inboundFiles.length > 0) {
+    try {
+      attachmentBundle = persistUnifyAttachments(inboundFiles, { subdir: groupId });
+    } catch (err) {
+      console.warn('[Unify] unify_group_chat: attachment persist failed', err?.message || err);
+    }
+  }
+  // Surface partial / total upload failures to the user. We don't abort
+  // the turn — the LLM can still answer the text-only portion — but the
+  // user must know which files didn't make it.
+  if (Array.isArray(attachmentBundle.failed) && attachmentBundle.failed.length > 0) {
+    const detail = attachmentBundle.failed
+      .map((f) => `  - ${f.name}: ${f.error}`)
+      .join('\n');
+    sendUnifyOutput({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: `⚠️ ${attachmentBundle.failed.length} file(s) could not be attached:\n${detail}` }] },
+    }, { groupId });
+  }
+  const persistedAttachments = attachmentsForPersistence(attachmentBundle.promptAttachments);
+
   // Ingest user text. The coordinator persists, applies mention/fanout
   // rules, and calls deliver() (== enqueueForVp) for each chosen VP —
   // which both (a) emits vp_typing_start and (b) ensures a driver runs.
@@ -1337,7 +1390,16 @@ export async function handleUnifyGroupChat(msg) {
       from: 'user',
       role: 'user',
       text,
-      meta: { mentions },
+      meta: {
+        mentions,
+        // Persisted form (no base64) — safe for jsonl-log.
+        attachments: persistedAttachments,
+      },
+      // Live form — adapters need the base64 image blocks; runVpTurn
+      // reads `_promptParts` off the envelope rather than going
+      // back to disk on every fan-out target. NOT persisted.
+      _promptParts: attachmentBundle.promptParts,
+      _promptSuffix: attachmentBundle.promptSuffix,
     });
   } catch (err) {
     console.warn('[Unify] unify_group_chat: coord.ingest failed', err?.message || err);
@@ -1581,7 +1643,7 @@ async function ensureSessionLoaded() {
  *
  * @param {{ prompt: string, groupId: string, vpId: string, turnId: string, envelope: object, vpAbort: AbortController, baseSnapshot: Array }} args
  */
-async function runVpTurn({ prompt, groupId, vpId, turnId, envelope: inboundEnvelope, vpAbort, baseSnapshot }) {
+async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, envelope: inboundEnvelope, vpAbort, baseSnapshot }) {
   if (!prompt?.trim()) return;
 
   const envelope = { groupId, vpId, turnId };
@@ -1727,6 +1789,7 @@ async function runVpTurn({ prompt, groupId, vpId, turnId, envelope: inboundEnvel
       });
       for await (const event of vpEngine.query({
         prompt,
+        promptParts,
         messages: trimmedMessages,
         signal: vpAbort.signal,
         ...queryOpts,