feat(cli): cross-flavor inline image and video display via MCP and ACP

[heavygee]

Summary

Cross-flavor inline image and video in HAPI web chat (not Cursor IDE composer):

• CLI MCP: display_image and display_video in startHappyServer; stdio bridge forwards both; buildHapiMcpBridge auto-approves both tools.
• Prompts: Shared displayImagePrompt / display_video exports for Claude, Codex, and HAPI_MCP_BRIDGE_PROMPT (Cursor, Gemini, Kimi, OpenCode first-prompt injection).
• ACP: Image content blocks → generated-image agent messages; generated media stored in CLI memory and served via hub GET /api/sessions/:id/generated-images/:imageId (images and video share this route).
• Web: GeneratedImageCard renders <img> (with tiny-image upscale + stable blob fetch) or <video controls> when mimeType is video/*.
• Tooling: hapi-display-image.mjs routes mp4/webm to display_video (absolute paths); loads hapiMcpUrl from per-session GET.

Test plan

• bun typecheck
• CLI: generatedImages.test.ts, buildHapiMcpBridge.test.ts, codexMcpConfig.test.ts, AcpMessageHandler.test.ts, messageConverter.test.ts
• Web: generatedInlineMedia.test.ts
• Manual: display_image PNG and display_video MP4 on Cursor session with hapiMcpUrl; inline cards in HAPI web

Issues

Closes #956

[github-actions]

Findings

• [Major] ACP inline media can be emitted before preceding assistant text. The new image branch flushes reasoning but leaves bufferedText open, while emitGeneratedImageFromAcpContent() emits asynchronously. For a normal ACP sequence like text chunk -> image block -> turn drain, the generated-image message can reach the web UI before the text that came first in the stream. Evidence: cli/src/agent/backends/acp/AcpMessageHandler.ts:559.

Questions

• None.

Summary

• Review mode: initial
• One ordering regression found in the latest diff. Residual risk: media fetch/cache behavior was reviewed statically only.

Testing

• Not run (automation). Suggested coverage: ACP handler test that sends a text agentMessageChunk, then an image agentMessageChunk, then drains, and asserts text precedes generated_image.

[github-actions]

Findings

• [Major] Generated media cards can keep rendering a stale blob after imageId changes.
• [Major] ACP image registration can let later updates render before the image block that preceded them.

Summary
Review mode: initial
Latest PR diff reviewed in full. The main residual risk is around generated media lifecycle/order because the new tests cover happy-path conversion and MIME helpers, but not component prop changes or ACP image blocks followed by later updates.

Testing
Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Major] Await ACP updates that arrive during the late-drain window before emitting turn_complete. cli/src/agent/backends/acp/AcpSdkBackend.ts:429

Summary
Review mode: follow-up after new commits
The previous stale-blob and initial ACP ordering findings are addressed. One ordering gap remains in the follow-up fix: late ACP image/file-backed updates can still be queued during drainLateBuffers() and emitted after turn_complete.

Testing
Not run (automation). Suggested: ACP prompt lifecycle test where a local-path image update arrives during drainLateBuffers() and must appear before turn_complete.

HAPI Bot

[github-actions]

Findings

• [Minor] AVIF files are now routed to display_video, so the helper rejects a supported image format. scripts/tooling/hapi-display-image.mjs:32
  Suggested fix:

  if (head.length >= 12 && head.subarray(4, 8).toString('ascii') === 'ftyp') {
      const brand = head.subarray(8, 12).toString('ascii')
      return brand === 'avif' || brand === 'avis' ? 'display_image' : 'display_video'
  }

Summary
Review mode: follow-up after new commits
One minor issue found in the helper script. The previous ACP ordering finding is addressed by the added post-drainLateBuffers() queue drain.

Testing
Not run (automation). Suggested: add a script/media sniffing test or shared helper coverage for AVIF vs MP4 ftyp routing.

HAPI Bot

[github-actions]

Findings
No issues found.

Summary
Review mode: follow-up after new commits
The follow-up commit addresses the previous AVIF ftyp routing finding. I reviewed the full current diff across MCP/ACP media registration, generated-image RPC serving, web rendering, and helper tooling; no new high-confidence correctness, security, data-loss, or regression findings found. Residual risk: I did not run the full Bun test suite in this automation environment.

Testing
Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Minor] HAPI_SESSION_ID shorthand drops the optional title — the new usage text advertises HAPI_SESSION_ID=<uuid> hapi-display-image.mjs <media-path> [title], but when a title is present process.argv[3] is treated as imagePath, so the later file check runs against the title string and exits before calling MCP. Evidence: scripts/tooling/hapi-display-image.mjs:27.
  Suggested fix:

  if (envSessionPrefix && sessionArg && existsSync(sessionArg) && lstatSync(sessionArg).isFile()) {
      imagePath = sessionArg
      title = process.argv[3]
      sessionArg = envSessionPrefix
  } else if (!sessionArg && envSessionPrefix) {
      sessionArg = envSessionPrefix
  }

Summary
Review mode: follow-up after new commits
Reviewed the full current PR diff, with prior bot review and the 67ca0b80...e3ab425 compare as follow-up context. One helper-script argument parsing regression found. Residual risk: full Bun test suite not run in this automation pass.

Testing
Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Major] Generated media fetch bypasses the immutable browser cache — cache: 'no-store' prevents the browser from storing or reusing the response, so every remount of an inline image/video goes back through the hub and CLI RPC despite the route explicitly returning Cache-Control: immutable and having a regression test for avoiding that round-trip. Evidence: web/src/api/client.ts:333.
  Suggested fix:

  const res = await fetch(this.buildUrl(`/api/sessions/${encodeURIComponent(sessionId)}/generated-images/${encodeURIComponent(imageId)}`), {
      headers
  })

Summary
Review mode: follow-up after new commits
Reviewed the full current PR diff with the previous bot review and follow-up compare as context. The prior HAPI_SESSION_ID title parsing issue is fixed. One cache regression remains in the generated media client path.

Testing
Not run (automation)

HAPI Bot

[github-actions]

Findings
None.

Summary
Review mode: follow-up after new commits
Reviewed the full current PR diff, using the previous HAPI Bot review and follow-up compare as context. The prior generated-media cache issue is addressed in the latest head. No blocking or high-confidence correctness/security regressions found in the changed lines. Residual risk: I did not execute PR code, so runtime/browser behavior for the new inline video path still depends on the workflow/manual test results.

Testing
Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Major] Avoid restoring stale Cursor MCP config wholesale — installCursorMcpOverlay() snapshots the entire .cursor/mcp.json before adding HAPI, then cleanup writes that old snapshot back. Any user/Cursor edits made while the remote session is running are silently lost on cleanup, which is a user config data-loss regression. Evidence: cli/src/cursor/utils/cursorMcpOverlay.ts:92
  Suggested fix:

  const installedEntry = {
      command: bridge.command,
      args: [...bridge.args],
  };
  config.mcpServers[CURSOR_HAPI_MCP_SERVER_ID] = installedEntry;
  
  // cleanup: re-read current file and only undo this overlay entry.
  const current = readMcpJson(mcpJsonPath);
  const currentEntry = current.mcpServers?.[CURSOR_HAPI_MCP_SERVER_ID];
  if (JSON.stringify(currentEntry) !== JSON.stringify(installedEntry)) {
      return;
  }
  delete current.mcpServers![CURSOR_HAPI_MCP_SERVER_ID];
  
  const previous = previousContent ? parseMcpJson(previousContent) : null;
  const previousEntry = previous?.mcpServers?.[CURSOR_HAPI_MCP_SERVER_ID];
  if (previousEntry) {
      current.mcpServers![CURSOR_HAPI_MCP_SERVER_ID] = previousEntry;
  }
  writeMcpJson(mcpJsonPath, current);

Summary
Review mode: follow-up after new commits
Reviewed the full current PR diff, using the previous HAPI Bot review and compare diff as context. Found one Major issue in the new Cursor MCP overlay cleanup path. Residual risk: runtime browser/media behavior was not executed in this review.

Testing
Not run (automation)

HAPI Bot

[github-actions]

[MAJOR] This cleanup path restores the full previousContent snapshot captured before HAPI was injected. If the user or Cursor updates .cursor/mcp.json while the session is running, those unrelated changes get overwritten when the launcher exits. Re-read the current file during cleanup and remove/restore only the hapi entry that this overlay installed.

Suggested fix:

const installedEntry = {
    command: bridge.command,
    args: [...bridge.args],
};
config.mcpServers[CURSOR_HAPI_MCP_SERVER_ID] = installedEntry;

// cleanup: re-read current file and only undo this overlay entry.
const current = readMcpJson(mcpJsonPath);
const currentEntry = current.mcpServers?.[CURSOR_HAPI_MCP_SERVER_ID];
if (JSON.stringify(currentEntry) !== JSON.stringify(installedEntry)) {
    return;
}
delete current.mcpServers![CURSOR_HAPI_MCP_SERVER_ID];

const previous = previousContent ? parseMcpJson(previousContent) : null;
const previousEntry = previous?.mcpServers?.[CURSOR_HAPI_MCP_SERVER_ID];
if (previousEntry) {
    current.mcpServers![CURSOR_HAPI_MCP_SERVER_ID] = previousEntry;
}
writeMcpJson(mcpJsonPath, current);

[github-actions]

Findings

• [Major] Avoid restoring stale Cursor MCP config wholesale — installCursorMcpOverlay() snapshots the whole .cursor/mcp.json before adding HAPI and cleanup writes that old snapshot back. Any Cursor/user edits made while the session is running are silently lost when the launcher exits, so this is a user config data-loss regression. Evidence: cli/src/cursor/utils/cursorMcpOverlay.ts:92
  Suggested fix:

  const installedEntry = {
      command: bridge.command,
      args: [...bridge.args],
  };
  config.mcpServers[CURSOR_HAPI_MCP_SERVER_ID] = installedEntry;
  
  // cleanup: re-read current file and only undo this overlay entry.
  const current = readMcpJson(mcpJsonPath);
  const currentEntry = current.mcpServers?.[CURSOR_HAPI_MCP_SERVER_ID];
  if (JSON.stringify(currentEntry) !== JSON.stringify(installedEntry)) {
      return;
  }
  delete current.mcpServers![CURSOR_HAPI_MCP_SERVER_ID];
  
  const previous = previousContent ? parseMcpJson(previousContent) : null;
  const previousEntry = previous?.mcpServers?.[CURSOR_HAPI_MCP_SERVER_ID];
  if (previousEntry) {
      current.mcpServers![CURSOR_HAPI_MCP_SERVER_ID] = previousEntry;
  }
  writeMcpJson(mcpJsonPath, current);

Summary
Review mode: follow-up after new commits
Reviewed the full current PR diff, using the previous HAPI Bot review and compare diff as context. The prior Cursor MCP cleanup data-loss issue is still present at the current head. Residual risk: runtime browser/media behavior was not executed in this review.

Testing
Not run (automation)

HAPI Bot

[github-actions]

[MAJOR] This cleanup path restores the full previousContent snapshot captured before HAPI was injected. If the user or Cursor updates .cursor/mcp.json while the session is running, those unrelated changes get overwritten when the launcher exits. Re-read the current file during cleanup and remove/restore only the hapi entry that this overlay installed.

Suggested fix:

const installedEntry = {
    command: bridge.command,
    args: [...bridge.args],
};
config.mcpServers[CURSOR_HAPI_MCP_SERVER_ID] = installedEntry;

// cleanup: re-read current file and only undo this overlay entry.
const current = readMcpJson(mcpJsonPath);
const currentEntry = current.mcpServers?.[CURSOR_HAPI_MCP_SERVER_ID];
if (JSON.stringify(currentEntry) !== JSON.stringify(installedEntry)) {
    return;
}
delete current.mcpServers![CURSOR_HAPI_MCP_SERVER_ID];

const previous = previousContent ? parseMcpJson(previousContent) : null;
const previousEntry = previous?.mcpServers?.[CURSOR_HAPI_MCP_SERVER_ID];
if (previousEntry) {
    current.mcpServers![CURSOR_HAPI_MCP_SERVER_ID] = previousEntry;
}
writeMcpJson(mcpJsonPath, current);