@link-assistant/hive-mind 1.74.0 → 1.74.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @link-assistant/hive-mind
 
+## 1.74.1
+
+### Patch Changes
+
+- 59eee9a: feat(interactive-mode): display images the AI reads/writes inline in PR comments (#1843)
+
+  When `--interactive-mode` posts Claude/Codex tool activity as PR comments, any
+  images the AI reads or produces (the `Read` tool on a screenshot, Playwright
+  captures, MCP image results) were previously serialized as multi-kilobyte
+  base64 blobs inside the "Raw JSON" section — unreadable and pushing comments
+  toward GitHub's size limit.
+
+  Those base64 payloads are now uploaded to hidden custom Git refs
+  (`refs/hive-mind-media/pr-...`) via the Git Data API and embedded inline in the
+  comment as commit-SHA `![](…?raw=true)` blob URLs, so reviewers see the actual
+  image (GitHub's Camo proxy renders `?raw=true` blob URLs inline for both public
+  and private repos, whereas `data:` URIs are stripped by the comment sanitizer).
+  Uploads are content-hashed (SHA-256) for dedup, and the base64 is redacted from
+  the Raw JSON section with a `<image data: N base64 chars>` placeholder.
+
+  Enabled by default; use `--no-interactive-image-upload` to opt out, in which
+  case each image degrades to a compact metadata note instead of being embedded.
+  All comment bodies continue to pass through the token sanitizer (#1745).
+
 ## 1.74.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.74.0",
+  "version": "1.74.1",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/claude.lib.mjs

@@ -687,6 +687,8 @@ export const executeClaudeCommand = async params => {
         // so the comment-posting path can honor them; flags default to false.
         skipOutputSanitization: argv['dangerously-skip-output-sanitization'] === true,
         skipActiveTokensOutputSanitization: argv['dangerously-skip-active-tokens-output-sanitization'] === true,
+        // Issue #1843: upload & embed images by default; --no-interactive-image-upload opts out.
+        imageUploadEnabled: argv['interactive-image-upload'] !== false,
       });
     } else if (argv.interactiveMode) {
       await log('⚠️ Interactive mode: Disabled - missing PR info (owner/repo/prNumber)', { verbose: true });

package/src/codex.lib.mjs

@@ -805,6 +805,8 @@ export const executeCodexCommand = async params => {
           // comment-posting path can honor them. All default to false.
           skipOutputSanitization: argv['dangerously-skip-output-sanitization'] === true,
           skipActiveTokensOutputSanitization: argv['dangerously-skip-active-tokens-output-sanitization'] === true,
+          // Issue #1843: upload & embed images by default; --no-interactive-image-upload opts out.
+          imageUploadEnabled: argv['interactive-image-upload'] !== false,
         });
       } else if (argv.interactiveMode) {
         await log('⚠️ Interactive mode: Disabled - missing PR info (owner/repo/prNumber)', { verbose: true });

package/src/interactive-image-render.lib.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Interactive Mode Image Rendering (Issue #1843)
+ *
+ * Bridges the raw image uploader (interactive-image-upload.lib.mjs) and the
+ * Markdown formatter (interactive-mode.shared.lib.mjs) so interactive-mode.lib.mjs
+ * can turn the base64 images Claude/Codex read or wrote into an inline
+ * `### 🖼️ Images` section with a single call. Kept in its own module so the main
+ * interactive-mode handler stays under the 1500-line file limit (issue #1730).
+ *
+ * @module interactive-image-render.lib.mjs
+ * @experimental
+ */
+
+import { formatImageEmbeds } from './interactive-mode.shared.lib.mjs';
+import { createImageUploader, extractImagePayload, isImageNode } from './interactive-image-upload.lib.mjs';
+
+// Re-exported so the main handler can import its image helpers from one place.
+export { extractImagePayload, isImageNode };
+
+/**
+ * Collect normalized image payloads from tool-result-like objects, de-duplicated
+ * by base64 content. Scans arrays directly, an array `content` (Claude/MCP), and
+ * the node itself (Claude Read `tool_use_result`). Enriches a missing
+ * `originalSize` from a later sibling payload with the same bytes.
+ *
+ * @param {...*} sources - candidate nodes/containers to scan
+ * @returns {Array<{ base64: string, mediaType?: string, originalSize?: number }>}
+ */
+export const collectImagePayloads = (...sources) => {
+  const payloads = [];
+  const seen = new Set();
+  const add = node => {
+    const payload = extractImagePayload(node);
+    if (!payload) return;
+    const key = payload.base64.slice(0, 64) + ':' + payload.base64.length;
+    if (seen.has(key)) {
+      // Enrich an already-collected payload with size metadata if we now have it.
+      if (payload.originalSize) {
+        const existing = payloads.find(p => p.base64.slice(0, 64) + ':' + p.base64.length === key);
+        if (existing && !existing.originalSize) existing.originalSize = payload.originalSize;
+      }
+      return;
+    }
+    seen.add(key);
+    payloads.push(payload);
+  };
+  const scan = source => {
+    if (!source) return;
+    if (Array.isArray(source)) {
+      source.forEach(add);
+    } else if (typeof source === 'object') {
+      if (Array.isArray(source.content)) source.content.forEach(add);
+      add(source);
+    }
+  };
+  sources.forEach(scan);
+  return payloads;
+};
+
+/**
+ * Create an image renderer bound to a PR. Wraps an image uploader (built here, or
+ * injected via `options.uploader` for tests) and produces the Markdown image
+ * section for a set of tool-result sources. Upload failures / disabled uploads
+ * degrade to a metadata note inside `formatImageEmbeds` rather than dumping base64.
+ *
+ * @param {Object} [options]
+ * @param {Object} [options.uploader] - injected uploader (tests); otherwise built from the remaining options
+ * @param {Object} [options.state] - handler state, used to label images by tool name
+ * @param {Function} [options.log] - async logging function
+ * @param {boolean} [options.verbose=false]
+ * @param {string} [options.owner]
+ * @param {string} [options.repo]
+ * @param {number|string} [options.prNumber]
+ * @param {string} [options.mediaRef]
+ * @param {string} [options.refNamespace]
+ * @param {Function} [options.execFile]
+ * @param {boolean} [options.enabled=true]
+ * @returns {{ uploader: Object, collect: Function, render: Function, toolLabel: Function, section: Function }}
+ */
+export const createImageRenderer = (options = {}) => {
+  const { uploader: injectedUploader, state, log = async () => {}, verbose = false, owner, repo, prNumber, mediaRef, refNamespace, execFile, enabled = true } = options;
+
+  const uploader = injectedUploader !== undefined ? injectedUploader : createImageUploader({ owner, repo, prNumber, mediaRef, refNamespace, log, verbose, execFile, enabled });
+
+  /**
+   * Upload normalized payloads and render the `### 🖼️ Images` Markdown section.
+   * Always returns a string (empty when there are no images).
+   * @param {Array<{ base64: string, mediaType?: string, originalSize?: number }>} payloads
+   * @param {string} [label] - human label prefix for captions / commit messages
+   * @returns {Promise<string>}
+   */
+  const render = async (payloads, label = 'image') => {
+    if (!Array.isArray(payloads) || payloads.length === 0) return '';
+    const rendered = [];
+    for (let i = 0; i < payloads.length; i++) {
+      const payload = payloads[i];
+      const name = payloads.length > 1 ? `${label} ${i + 1}` : label;
+      let url = null;
+      try {
+        if (uploader && typeof uploader.uploadImage === 'function') {
+          url = await uploader.uploadImage({ base64: payload.base64, mediaType: payload.mediaType, name });
+        }
+      } catch (err) {
+        if (verbose) await log(`⚠️ Interactive mode: image upload threw: ${err.message}`, { verbose: true });
+        url = null;
+      }
+      rendered.push({ url, mediaType: payload.mediaType, originalSize: payload.originalSize, name });
+    }
+    return formatImageEmbeds(rendered);
+  };
+
+  /**
+   * A human label for image captions, derived from the tool name in the
+   * pending-call / registry maps (e.g. "Read image"). Falls back to "image".
+   * @param {string} toolUseId
+   * @returns {string}
+   */
+  const toolLabel = toolUseId => {
+    const name = state?.pendingToolCalls?.get(toolUseId)?.toolName || state?.toolUseRegistry?.get(toolUseId)?.toolName;
+    return name ? `${name} image` : 'image';
+  };
+
+  /**
+   * Convenience: collect images from `sources` and render them in one call.
+   * @param {Array<*>} sources - array of candidate nodes/containers
+   * @param {string} [label]
+   * @returns {Promise<string>}
+   */
+  const section = async (sources, label) => render(collectImagePayloads(...(Array.isArray(sources) ? sources : [sources])), label);
+
+  return { uploader, collect: collectImagePayloads, render, toolLabel, section };
+};
+
+export default {
+  collectImagePayloads,
+  createImageRenderer,
+  extractImagePayload,
+  isImageNode,
+};

package/src/interactive-image-upload.lib.mjs

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+/**
+ * Interactive Mode Image Upload (Issue #1843)
+ *
+ * When Claude/Codex read or write images during an --interactive-mode session,
+ * interactive mode should show those images inline in the PR comments it posts.
+ *
+ * GitHub strips `data:` URIs from comment Markdown (its sanitizer only allows
+ * http/https/mailto/relative schemes), so embedding base64 inline does NOT work.
+ * The web "user-attachments" uploader is cookie-gated and rejects Personal Access
+ * Tokens (HTTP 422), so it cannot be driven headlessly either.
+ *
+ * The token-viable approach used here: store image blobs in a hidden custom Git
+ * ref (`refs/hive-mind-media/...`) via the Git Data API and embed a commit-SHA
+ * `?raw=true` blob URL. The custom ref keeps commits reachable without creating
+ * a branch or tag, while GitHub's Camo proxy renders the URL inline for authorized
+ * viewers in public and private repos.
+ *
+ * See docs/case-studies/issue-1843/ for the full analysis and sources.
+ *
+ * @module interactive-image-upload.lib.mjs
+ * @experimental
+ */
+
+import { createHash } from 'node:crypto';
+import { execFileAsync } from './interactive-mode.shared.lib.mjs';
+
+/**
+ * Hidden custom-ref namespace used to keep interactive-mode image commits alive
+ * without adding a branch or tag to the repository UI. Each PR gets its own ref:
+ * `refs/hive-mind-media/pr-<number>`.
+ */
+export const DEFAULT_MEDIA_REF_NAMESPACE = 'refs/hive-mind-media';
+
+const README_CONTENT = `# hive-mind interactive media
+
+This custom Git ref stores images that hive-mind's \`--interactive-mode\` read or
+wrote during a session, so they can be embedded inline in PR comments.
+
+It is created and updated automatically under \`refs/hive-mind-media/...\`. It is
+not a branch or tag and is not meant to be checked out or merged. Files are
+organized as \`media/pr-<number>/<sha256-prefix>.<ext>\` and de-duplicated by
+content hash. See \`docs/case-studies/issue-1843/\` for details.
+`;
+
+const EXT_BY_MEDIA_TYPE = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/svg+xml': 'svg',
+  'image/bmp': 'bmp',
+  'image/avif': 'avif',
+  'image/tiff': 'tiff',
+};
+
+/**
+ * Map an image MIME type to a file extension. Defaults to `png`.
+ * @param {string} mediaType
+ * @returns {string}
+ */
+export const extensionForMediaType = mediaType => {
+  if (typeof mediaType !== 'string') return 'png';
+  const key = mediaType.toLowerCase().split(';')[0].trim();
+  return EXT_BY_MEDIA_TYPE[key] || 'png';
+};
+
+const sanitizeRefSegment = value => {
+  const segment = String(value || 'misc')
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return segment || 'misc';
+};
+
+const normalizeRefNamespace = namespace => {
+  const raw = String(namespace || DEFAULT_MEDIA_REF_NAMESPACE)
+    .replace(/\/+$/g, '')
+    .replace(/^\/+/g, '');
+  return raw.startsWith('refs/') ? raw : `refs/${raw}`;
+};
+
+/**
+ * Build the hidden custom Git ref used for one PR's media.
+ * @param {Object} [options]
+ * @param {number|string} [options.prNumber]
+ * @param {string} [options.namespace]
+ * @returns {string}
+ */
+export const buildMediaRef = ({ prNumber, namespace = DEFAULT_MEDIA_REF_NAMESPACE } = {}) => {
+  const prSeg = prNumber ? `pr-${sanitizeRefSegment(prNumber)}` : 'misc';
+  return `${normalizeRefNamespace(namespace)}/${prSeg}`;
+};
+
+const refPathForApi = fullRef =>
+  String(fullRef)
+    .replace(/^refs\//, '')
+    .split('/')
+    .map(seg => encodeURIComponent(seg))
+    .join('/');
+
+/**
+ * Normalize an image payload from any of the shapes Claude/Codex emit into
+ * `{ base64, mediaType }`, or return null if the node is not an image.
+ *
+ * Verified shapes (see docs/case-studies/issue-1843/external/research-notes.md):
+ *  - Claude tool_result content: { type:'image', source:{ type:'base64', data, media_type } }
+ *  - MCP image content:          { type:'image', data, mimeType }
+ *  - Claude Read tool_use_result: { type:'image', file:{ base64, type, originalSize } }
+ *
+ * @param {*} node
+ * @returns {{ base64: string, mediaType: string, originalSize?: number } | null}
+ */
+export const extractImagePayload = node => {
+  if (!node || typeof node !== 'object') return null;
+
+  // Claude tool_result image block: { type:'image', source:{ data, media_type } }
+  if (node.type === 'image' && node.source && typeof node.source === 'object' && typeof node.source.data === 'string' && node.source.data.length > 0) {
+    return { base64: node.source.data, mediaType: node.source.media_type || node.source.mimeType || 'image/png' };
+  }
+
+  // MCP image content: { type:'image', data, mimeType }
+  if (node.type === 'image' && typeof node.data === 'string' && node.data.length > 0) {
+    return { base64: node.data, mediaType: node.mimeType || node.media_type || 'image/png' };
+  }
+
+  // Claude Read tool_use_result: { type:'image', file:{ base64, type, originalSize } }
+  if (node.file && typeof node.file === 'object' && typeof node.file.base64 === 'string' && node.file.base64.length > 0) {
+    return { base64: node.file.base64, mediaType: node.file.type || node.file.media_type || 'image/png', originalSize: node.file.originalSize };
+  }
+
+  return null;
+};
+
+/**
+ * True when `extractImagePayload` would return a payload for this node.
+ * @param {*} node
+ * @returns {boolean}
+ */
+export const isImageNode = node => extractImagePayload(node) !== null;
+
+/**
+ * Build a Markdown-embeddable raw blob URL for a file committed at a reachable
+ * commit SHA. The custom media ref keeps that commit reachable without exposing a
+ * branch/tag, and the `?raw=true` URL renders inline in GitHub comments.
+ *
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} commitSha
+ * @param {string} path
+ * @returns {string}
+ */
+export const buildRawBlobUrl = (owner, repo, commitSha, path) => {
+  const safePath = String(path)
+    .split('/')
+    .map(seg => encodeURIComponent(seg))
+    .join('/');
+  return `https://github.com/${owner}/${repo}/blob/${encodeURIComponent(commitSha)}/${safePath}?raw=true`;
+};
+
+/**
+ * Create an image uploader bound to a repository/PR.
+ *
+ * @param {Object} options
+ * @param {string} options.owner - Repository owner
+ * @param {string} options.repo - Repository name
+ * @param {number|string} [options.prNumber] - PR number (used to namespace paths/ref)
+ * @param {string} [options.mediaRef] - Full custom media ref (defaults to refs/hive-mind-media/pr-<n>)
+ * @param {string} [options.refNamespace] - Custom media ref namespace
+ * @param {Function} [options.log] - async logging function
+ * @param {boolean} [options.verbose=false]
+ * @param {Function} [options.execFile] - injected gh runner (for testing)
+ * @param {boolean} [options.enabled=true] - master switch
+ * @returns {{ uploadImage: Function, ensureMediaRef: Function, enabled: boolean, mediaRef: string, _state: Object }}
+ */
+export const createImageUploader = (options = {}) => {
+  const { owner, repo, prNumber, mediaRef = buildMediaRef({ prNumber, namespace: options.refNamespace }), log = async () => {}, verbose = false, execFile: execFileFn, enabled = true } = options;
+
+  const runGhApi = execFileFn || execFileAsync;
+  const mediaRefPath = refPathForApi(mediaRef);
+
+  // Memoized ref-readiness promise and a per-session content-hash -> URL cache.
+  let mediaRefReady = null;
+  let currentCommitSha = null;
+  let currentTreeSha = null;
+  let currentTreePaths = new Set();
+  const uploadedByHash = new Map();
+
+  /**
+   * Invoke `gh api` and parse the JSON response. For non-GET methods a JSON body
+   * is supplied on stdin via `--input -` (matches interactive-mode's postComment).
+   * @private
+   */
+  const ghJson = async (apiPath, { method = 'GET', body } = {}) => {
+    const args = ['api', apiPath];
+    if (method && method !== 'GET') args.push('-X', method);
+    const execOpts = { maxBuffer: 16 * 1024 * 1024 };
+    if (body !== undefined) {
+      args.push('--input', '-');
+      execOpts.input = JSON.stringify(body);
+    }
+    const { stdout } = await runGhApi('gh', args, execOpts);
+    if (!stdout) return null;
+    try {
+      return JSON.parse(stdout);
+    } catch {
+      return null;
+    }
+  };
+
+  const rememberTreePaths = async treeSha => {
+    try {
+      const tree = await ghJson(`repos/${owner}/${repo}/git/trees/${treeSha}?recursive=1`);
+      currentTreePaths = new Set((Array.isArray(tree?.tree) ? tree.tree : []).filter(entry => entry?.type === 'blob' && typeof entry.path === 'string').map(entry => entry.path));
+    } catch {
+      currentTreePaths = new Set();
+    }
+  };
+
+  const rememberCommit = async sha => {
+    if (!sha) return false;
+    const commit = await ghJson(`repos/${owner}/${repo}/git/commits/${sha}`);
+    if (!commit?.sha || !commit?.tree?.sha) return false;
+    currentCommitSha = commit.sha;
+    currentTreeSha = commit.tree.sha;
+    await rememberTreePaths(currentTreeSha);
+    return true;
+  };
+
+  const fetchMediaRef = async () => {
+    try {
+      return await ghJson(`repos/${owner}/${repo}/git/ref/${mediaRefPath}`);
+    } catch {
+      return null;
+    }
+  };
+
+  const refreshMediaRef = async () => {
+    const ref = await fetchMediaRef();
+    return !!(ref?.object?.sha && (await rememberCommit(ref.object.sha)));
+  };
+
+  /**
+   * Ensure the custom media ref exists. Creates it once via the Git Data API
+   * (blob -> tree -> parentless commit -> ref). Memoized; resolves to a boolean.
+   * @returns {Promise<boolean>}
+   */
+  const ensureMediaRef = async () => {
+    if (mediaRefReady) return mediaRefReady;
+    mediaRefReady = (async () => {
+      if (await refreshMediaRef()) return true;
+      try {
+        const readmeB64 = Buffer.from(README_CONTENT, 'utf8').toString('base64');
+        const blob = await ghJson(`repos/${owner}/${repo}/git/blobs`, {
+          method: 'POST',
+          body: { content: readmeB64, encoding: 'base64' },
+        });
+        const tree = await ghJson(`repos/${owner}/${repo}/git/trees`, {
+          method: 'POST',
+          body: { tree: [{ path: 'README.md', mode: '100644', type: 'blob', sha: blob.sha }] },
+        });
+        const commit = await ghJson(`repos/${owner}/${repo}/git/commits`, {
+          method: 'POST',
+          body: { message: 'chore: initialize hive-mind interactive media ref', tree: tree.sha, parents: [] },
+        });
+        await ghJson(`repos/${owner}/${repo}/git/refs`, {
+          method: 'POST',
+          body: { ref: mediaRef, sha: commit.sha },
+        });
+        currentCommitSha = commit.sha;
+        currentTreeSha = tree.sha;
+        currentTreePaths = new Set(['README.md']);
+        if (verbose) await log(`🖼️ Interactive mode: created media ref '${mediaRef}'`, { verbose: true });
+        return true;
+      } catch (err) {
+        // A concurrent run may have created it between our check and create.
+        if (await refreshMediaRef()) return true;
+        await log(`⚠️ Interactive mode: could not prepare media ref '${mediaRef}': ${err.message}`);
+        return false;
+      }
+    })();
+    return mediaRefReady;
+  };
+
+  const pathExistsAtCurrentCommit = async path => {
+    return !!(currentCommitSha && currentTreePaths.has(path));
+  };
+
+  const existingUrl = async path => {
+    if (await pathExistsAtCurrentCommit(path)) {
+      return buildRawBlobUrl(owner, repo, currentCommitSha, path);
+    }
+    return null;
+  };
+
+  /**
+   * Upload one image and return a Markdown-embeddable URL, or null on failure /
+   * when disabled. De-duplicates by SHA-256 of the base64 content.
+   *
+   * @param {Object} image
+   * @param {string} image.base64 - base64-encoded image bytes
+   * @param {string} [image.mediaType] - MIME type (e.g. image/png)
+   * @param {string} [image.name] - human label for the commit message
+   * @returns {Promise<string|null>}
+   */
+  const uploadImage = async ({ base64, mediaType, name } = {}) => {
+    if (!enabled) return null;
+    if (!owner || !repo) return null;
+    if (typeof base64 !== 'string' || base64.length === 0) return null;
+
+    const hash = createHash('sha256').update(base64).digest('hex');
+    if (uploadedByHash.has(hash)) return uploadedByHash.get(hash);
+
+    const ready = await ensureMediaRef();
+    if (!ready || !currentCommitSha || !currentTreeSha) return null;
+
+    const ext = extensionForMediaType(mediaType);
+    const short = hash.slice(0, 16);
+    const prSeg = prNumber ? `pr-${sanitizeRefSegment(prNumber)}` : 'misc';
+    const path = `media/${prSeg}/${short}.${ext}`;
+
+    const alreadyUploaded = await existingUrl(path);
+    if (alreadyUploaded) {
+      uploadedByHash.set(hash, alreadyUploaded);
+      return alreadyUploaded;
+    }
+
+    let lastError = null;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const parentSha = currentCommitSha;
+        const blob = await ghJson(`repos/${owner}/${repo}/git/blobs`, {
+          method: 'POST',
+          body: { content: base64, encoding: 'base64' },
+        });
+        const tree = await ghJson(`repos/${owner}/${repo}/git/trees`, {
+          method: 'POST',
+          body: {
+            base_tree: currentTreeSha,
+            tree: [{ path, mode: '100644', type: 'blob', sha: blob.sha }],
+          },
+        });
+        const commit = await ghJson(`repos/${owner}/${repo}/git/commits`, {
+          method: 'POST',
+          body: {
+            message: `chore: add interactive media ${name || short}`,
+            tree: tree.sha,
+            parents: [parentSha],
+          },
+        });
+        await ghJson(`repos/${owner}/${repo}/git/refs/${mediaRefPath}`, {
+          method: 'PATCH',
+          body: { sha: commit.sha, force: false },
+        });
+
+        currentCommitSha = commit.sha;
+        currentTreeSha = tree.sha;
+        currentTreePaths.add(path);
+        const url = buildRawBlobUrl(owner, repo, commit.sha, path);
+        uploadedByHash.set(hash, url);
+        if (verbose) await log(`🖼️ Interactive mode: uploaded image -> ${url}`, { verbose: true });
+        return url;
+      } catch (err) {
+        lastError = err;
+        // Most likely a concurrent non-fast-forward update. Refresh once and retry.
+        if (attempt === 0 && (await refreshMediaRef())) {
+          const existingAfterRefresh = await existingUrl(path);
+          if (existingAfterRefresh) {
+            uploadedByHash.set(hash, existingAfterRefresh);
+            return existingAfterRefresh;
+          }
+          continue;
+        }
+      }
+    }
+
+    const existingAfterFailure = await existingUrl(path);
+    if (existingAfterFailure) {
+      uploadedByHash.set(hash, existingAfterFailure);
+      return existingAfterFailure;
+    }
+
+    await log(`⚠️ Interactive mode: image upload failed (${path}): ${lastError?.message || 'unknown error'}`);
+    return null;
+  };
+
+  return {
+    uploadImage,
+    ensureMediaRef,
+    enabled,
+    mediaRef,
+    _state: {
+      uploadedByHash,
+      get currentCommitSha() {
+        return currentCommitSha;
+      },
+      get currentTreeSha() {
+        return currentTreeSha;
+      },
+      get currentTreePaths() {
+        return currentTreePaths;
+      },
+    },
+  };
+};
+
+export default {
+  DEFAULT_MEDIA_REF_NAMESPACE,
+  buildMediaRef,
+  extensionForMediaType,
+  extractImagePayload,
+  isImageNode,
+  buildRawBlobUrl,
+  createImageUploader,
+};

package/src/interactive-mode.lib.mjs

@@ -32,7 +32,9 @@
  * @experimental
  */
 
-import { CONFIG, createCollapsible, createRawJsonSection, escapeMarkdown, execFileAsync, formatCost, formatDuration, getToolIcon, safeJsonStringify, sanitizeUnicode, truncateMiddle } from './interactive-mode.shared.lib.mjs';
+import { CONFIG, createCollapsible, createRawJsonSection, createRedactedRawJsonSection, escapeMarkdown, execFileAsync, formatCost, formatDuration, getToolIcon, redactImageData, safeJsonStringify, sanitizeUnicode, truncateMiddle } from './interactive-mode.shared.lib.mjs';
+// Issue #1843: turn base64 image tool-results into inline PR-comment images.
+import { createImageRenderer, extractImagePayload, isImageNode } from './interactive-image-render.lib.mjs';
 // Issue #1625: track interactive-mode comment IDs so they're excluded from
 // the "did the AI post anything?" check in checkForAiCreatedComments().
 // Use the session-started marker as the single source of truth for the
@@ -75,6 +77,11 @@ export const createInteractiveHandler = options => {
     // Pre-existing user content carve-out (issue body / non-bot comments /
     // pre-existing code). When provided, sanitizer leaves these tokens untouched.
     excludeTokens = [],
+    // Issue #1843: when true (default), base64 tool-result images are embedded
+    // inline; when false they degrade to a metadata note. See createImageRenderer.
+    imageUploadEnabled = true,
+    mediaRef,
+    imageUploader: injectedImageUploader,
   } = options;
   // Use injected execFile for testability, or the real one by default
   const runGhApi = execFileFn || execFileAsync;
@@ -111,6 +118,8 @@ export const createInteractiveHandler = options => {
     editsFailed: 0,
   };
 
+  const imageRenderer = createImageRenderer({ owner, repo, prNumber, mediaRef, log, verbose, execFile: execFileFn, enabled: imageUploadEnabled, uploader: injectedImageUploader, state }); // Issue #1843
+
   /**
    * Sanitize a comment body and warn the chat owner when a known-local token
    * was about to be published. Issue #1745. The returned string is what we
@@ -632,6 +641,8 @@ ${createRawJsonSection(data)}`;
         .map(c => {
           if (typeof c === 'string') return c;
           if (c.type === 'text') return c.text || '';
+          // Issue #1843: image bytes render in the section below, not the fence.
+          if (isImageNode(c)) return `_[image: ${extractImagePayload(c).mediaType}]_`;
           return safeJsonStringify(c);
         })
         .join('\n');
@@ -644,6 +655,10 @@ ${createRawJsonSection(data)}`;
       keepEnd: 25,
     });
 
+    // Issue #1843: render images this result read/produced (used by both paths).
+    const imagesSection = await imageRenderer.section([toolResult.content, data.tool_use_result], imageRenderer.toolLabel(toolUseId));
+    const imagesBlock = imagesSection ? `${imagesSection}\n\n` : '';
+
     // Check if we have a pending tool call to merge with
     const pendingCall = state.pendingToolCalls.get(toolUseId);
 
@@ -703,9 +718,9 @@ ${inputDisplay}
 
 ${createCollapsible(`📤 Output (${statusIcon} ${statusText.toLowerCase()})`, '```\n' + escapeMarkdown(truncatedContent) + '\n```', true)}
 
----
+${imagesBlock}---
 
-${createRawJsonSection([toolData, data])}`;
+${createRedactedRawJsonSection([toolData, data])}`;
 
         // Edit the existing comment
         const editSuccess = await editComment(commentId, mergedComment);
@@ -742,9 +757,9 @@ ${createRawJsonSection([toolData, data])}`;
 
 ${createCollapsible(`📤 Output (${statusIcon} ${statusText.toLowerCase()})`, '```\n' + escapeMarkdown(truncatedContent) + '\n```', true)}
 
----
+${imagesBlock}---
 
-${createRawJsonSection(data)}`;
+${createRedactedRawJsonSection(data)}`;
 
     await postComment(comment);
 
@@ -1153,17 +1168,20 @@ ${createRawJsonSection(data)}`;
     const item = data.item || {};
     const summary = [`**Server:** \`${item.server || 'unknown'}\``, `**Tool:** \`${item.tool || 'unknown'}\``, `**Status:** \`${item.status || 'unknown'}\``].join('\n');
     const details = item.arguments != null ? createCollapsible('📥 Arguments', '```json\n' + safeJsonStringify(item.arguments, 2) + '\n```', true) : '';
-    const resultSection = item.result != null ? '\n\n' + createCollapsible('📤 Result', '```json\n' + safeJsonStringify(item.result, 2) + '\n```', false) : '';
+    // Issue #1843: render MCP-result images inline; base64 is redacted from JSON below.
+    const imagesSection = await imageRenderer.section([item.result], `${item.tool || 'mcp'} image`);
+    const imagesBlock = imagesSection ? '\n\n' + imagesSection : '';
+    const resultSection = item.result != null ? '\n\n' + createCollapsible('📤 Result', '```json\n' + safeJsonStringify(redactImageData(item.result), 2) + '\n```', false) : '';
     const errorSection = item.error != null ? '\n\n' + createCollapsible('❌ Error', '```json\n' + safeJsonStringify(item.error, 2) + '\n```', true) : '';
 
     await postComment(`## 🔌 Codex MCP tool call
 
 ${summary}
-${details}${resultSection}${errorSection}
+${details}${resultSection}${imagesBlock}${errorSection}
 
 ---
 
-${createRawJsonSection(data)}`);
+${createRedactedRawJsonSection(data)}`);
   };
 
   const handleCodexWebSearch = async data => {
@@ -1388,6 +1406,7 @@ ${createRawJsonSection(data)}`;
     processEvent,
     flush,
     getState,
+    imageUploader: imageRenderer.uploader, // Issue #1843: exposed for callers/tests.
     // Expose individual handlers for testing
     _handlers: {
       handleSystemInit,

package/src/interactive-mode.shared.lib.mjs

@@ -96,6 +96,103 @@ export const createRawJsonSection = data => {
   return createCollapsible('📄 Raw JSON', '```json\n' + jsonContent + '\n```');
 };
 
+/**
+ * Issue #1843: Deep-clone an event object, replacing base64 image payloads with
+ * a short `<image data: N base64 chars>` placeholder. Image base64 (Read tool,
+ * Playwright screenshots, MCP image results) can be many kilobytes on a single
+ * JSON line, which `truncateMiddle` cannot shrink — so without this the "Raw
+ * JSON" sections would bloat every image-bearing comment toward the API limit.
+ *
+ * Redaction is targeted at the three known image carriers and leaves all other
+ * fields intact for debugging:
+ *  - `{ type:'image', source:{ data } }`  → source.data
+ *  - `{ type:'image', data }`              → data (MCP shape)
+ *  - `{ file:{ base64 } }`                 → file.base64 (Read tool_use_result)
+ *
+ * @param {*} data
+ * @returns {*} a redacted clone (primitives returned as-is)
+ */
+export const redactImageData = data => {
+  const seen = new WeakSet();
+  const placeholder = len => `<image data: ${len} base64 chars>`;
+  const walk = node => {
+    if (Array.isArray(node)) return node.map(walk);
+    if (node && typeof node === 'object') {
+      if (seen.has(node)) return '[Circular]';
+      seen.add(node);
+      const out = {};
+      for (const [k, v] of Object.entries(node)) out[k] = walk(v);
+      if (out.type === 'image' && out.source && typeof out.source === 'object' && typeof out.source.data === 'string') {
+        out.source = { ...out.source, data: placeholder(out.source.data.length) };
+      }
+      if (out.type === 'image' && typeof out.data === 'string' && out.data.length > 64) {
+        out.data = placeholder(out.data.length);
+      }
+      if (out.file && typeof out.file === 'object' && typeof out.file.base64 === 'string') {
+        out.file = { ...out.file, base64: placeholder(out.file.base64.length) };
+      }
+      return out;
+    }
+    return node;
+  };
+  return walk(data);
+};
+
+/**
+ * Issue #1843: Like createRawJsonSection, but strips base64 image data first.
+ * @param {*} data
+ * @returns {string}
+ */
+export const createRedactedRawJsonSection = data => createRawJsonSection(redactImageData(data));
+
+/**
+ * Format a byte count as a short human-readable string (e.g. "7.2 MB").
+ * @param {number} bytes
+ * @returns {string}
+ */
+export const formatBytes = bytes => {
+  if (typeof bytes !== 'number' || !isFinite(bytes) || bytes < 0) return '';
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ['KB', 'MB', 'GB'];
+  let value = bytes / 1024;
+  let i = 0;
+  while (value >= 1024 && i < units.length - 1) {
+    value /= 1024;
+    i++;
+  }
+  return `${value.toFixed(value >= 10 || Number.isInteger(value) ? 0 : 1)} ${units[i]}`;
+};
+
+/**
+ * Sanitize Markdown image alt text so it can't break the `![alt](url)` syntax.
+ * @param {string} text
+ * @returns {string}
+ */
+const escapeAltText = text => (!text || typeof text !== 'string' ? 'image' : text.replace(/[[\]\n\r]/g, ' ').trim() || 'image');
+
+/**
+ * Issue #1843: Render an "🖼️ Images" Markdown section for images surfaced in a
+ * tool result. Each entry that has a `url` is embedded inline with `![](url)`;
+ * entries without a `url` (upload disabled or failed) degrade to a compact
+ * metadata note instead of dumping base64.
+ *
+ * @param {Array<{ url?: string, mediaType?: string, originalSize?: number, name?: string }>} images
+ * @returns {string} Markdown (empty string when there are no images)
+ */
+export const formatImageEmbeds = images => {
+  if (!Array.isArray(images) || images.length === 0) return '';
+  const blocks = images.map((img, i) => {
+    const label = img.name || `image ${i + 1}`;
+    const meta = [img.mediaType, formatBytes(img.originalSize)].filter(Boolean).join(', ');
+    const caption = meta ? `${label} (${meta})` : label;
+    if (img.url) {
+      return `**${escapeMarkdown(caption)}**\n\n![${escapeAltText(label)}](${img.url})`;
+    }
+    return `**${escapeMarkdown(caption)}** — _image upload unavailable; not shown inline_`;
+  });
+  return `### 🖼️ Images\n\n${blocks.join('\n\n')}`;
+};
+
 export const formatDuration = ms => {
   if (!ms || ms < 0) return 'unknown';
 

package/src/solve.config.lib.mjs

@@ -405,6 +405,15 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: '[EXPERIMENTAL] Post tool output as PR comments in real-time. Supported for --tool claude and --tool codex.',
     default: false,
   },
+  // Issue #1843: render images that Claude/Codex read/write inline in the PR
+  // comments interactive mode posts. Images are committed to hidden custom Git
+  // refs and embedded via commit-SHA ?raw=true blob URLs (GitHub strips data: URIs).
+  // Disable with --no-interactive-image-upload to fall back to a metadata note.
+  'interactive-image-upload': {
+    type: 'boolean',
+    description: '[EXPERIMENTAL] When --interactive-mode is on, upload images read/written by the AI to hidden custom Git refs (refs/hive-mind-media/...) and embed them inline in PR comments. Enabled by default; use --no-interactive-image-upload to disable.',
+    default: true,
+  },
   // Issue #817: Bidirectional interactive options
   'accept-incomming-comments-as-input': {
     type: 'boolean',