[brennanb2025]

	Files	Added	Deleted	Net
Test	16	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1629	$\color{#cf222e}{\Huge{\mathbf{−}}}$​6	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1623
Prod	34	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​2146	$\color{#cf222e}{\Huge{\mathbf{−}}}$​45	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​2101

ELI5

When an agent in Orca's native chat wants to show you a chart, a table or a small mockup, today it can only describe it in text. This PR lets the agent write one HTML page into a folder Orca keeps for that chat and put a single line in its reply; Orca then shows that page right inside the reply, as a live, interactive picture that matches your theme, and you can open it larger in the right sidebar.

What Changed

Problem. A structured native chat (the Claude/Codex chat view, not the terminal) can only show prose, Markdown tables and Mermaid. Agents that want to show data visually have no way to do it inside the conversation, and there was no safe place to keep what they produce or safe way to run it.

Before → after, as a user sees it.

• Before: a reply containing ::orca-visual{file="usage-chart.html" title="Usage by day"} shows that line as plain text.
• After: in a structured chat, that line (alone on its own line in the agent's reply) becomes the chart itself, inline in the reply. It is interactive, wears the app/chat theme (and follows a theme switch without reloading, so clicks and state inside it survive), and its height fits its content. Hovering it (or focusing it with the keyboard, or on touch) shows an Open in sidebar button that opens the same page in the right sidebar, widened while it is open and back to your width afterwards. A visual that can't be shown becomes one muted line, "Visualization unavailable". The same line inside a code block, a quote, a list or inline code stays plain text. While a reply is still streaming, a half-written visual line is held back instead of flashing raw syntax.
• The left sidebar's agent row, notifications, phone agent rows and Agent Session History previews never show the raw line, and Copy message copies the reply without it; they show the reply's prose.

How it works (mechanism).

1. One grammar (src/shared/native-chat-visual-directive.ts) for the reply line, shared with mobile: a single bare file name ending in .html (no folders, .., drive/UNC/device/stream forms), optional title, length caps, at most 8 visuals per reply. A helper removes these lines from text that becomes plain text (withoutNativeChatVisualDirectiveLines), applied at the one producer of the "last reply" summary and at AI Vault previews.
2. Markdown integration, not a second renderer. A small micromark block extension recognizes the line inside the existing native-chat Markdown pipeline, so fences, indented code, quotes and lists keep their meaning. Only top-level lines in assistant replies of a structured chat become visuals; a per-message random nonce stops raw HTML in a reply from forging one.
3. Storage and reading on the host that owns the chat. Each chat gets an Orca-owned folder <userData>/native-chat-visuals/<sha256(session id)>/ on the execution host, outside the user's workspace (creating it and teaching agents to use it is the follow-up PR). A new runtime method agentSession.readVisual {sessionId, file, knownRevision?} reads one file there: lexical and canonical containment, O_NOFOLLOW, folder/parent must be real directories (re-checked after open), regular files only, a 512 KiB bounded read, UTF-8 only. Errors are returned as values (not_found, outside_folder, too_large, not_text, …). An older host answers "method not found" and the client shows "unavailable"; loss of contact is never treated as "deleted". The client keeps a small revision cache (bounded, de-duplicated, revalidated on every mount, bounded retries, no permanent failure).
4. An isolated frame. The page runs in an <iframe sandbox="allow-scripts"> (opaque origin; no same-origin, forms, popups or top navigation) built from a shell (src/shared/native-chat-visual-shell.ts, shared with mobile) whose Content-Security-Policy is the first thing parsed: scripts/styles/fonts/images only inline, data:/blob:, or from six pinned public CDNs; no fetch/XHR/WebSocket, frames, workers, objects, media, forms or <base>. The main process's frame navigation guard (generalized from the plugin-panel guard into a host-frame registry with a separate "chat visual" kind — it grants nothing) refuses any navigation of the frame. Theme tokens are injected before first paint and updated by message. The page reports its height; the host clamps it (80–2000 px), rate-limits it and stops a page that only grows because the frame grew. Links: the page asks; Orca opens http(s) links in the viewing client's browser only while the frame has focus and the user has just acted, at most one per 5 s.
5. Sidebar route. "Open in sidebar" is an in-memory route (identity only, never the HTML; never persisted or sent to other clients) that the right sidebar renders with the same frame component. Picking any sidebar tab, closing the sidebar, or leaving the chat/workspace closes it.

Why

• One reply line + an Orca-owned per-chat folder follows the common pattern for agent-written visuals (the app keeps generated pages in its own per-chat storage and the reply carries a reference), keeps the user's repository clean, and needs no extra tool server.
• Markdown-tree integration instead of splitting the text: splitting breaks reference links, nested lists/quotes and code blocks, and would be a second Markdown path to keep in sync.
• Host-side containment is the security boundary; the renderer's checks are only an early refusal. The reader is narrower than Orca's general file access on purpose: a visual may only come from its own chat's folder.
• srcdoc + CSP-first shell + the existing main-process navigation guard reuses Orca's plugin-panel isolation instead of inventing a new one; the guard was generalized so both kinds share one registry without sharing any authority.
• Live theme by message instead of rebuilding the frame keeps the page's state; fitted height avoids a scrollbox inside the thread.

Differences from the common pattern

• Skill + reply line instead of a host tool — intended (product choice): no tool server; the trade-off is no visuals in read-only/plan turns (the agent falls back to Markdown).
• App-owned per-chat folder — matches the common pattern's storage ownership. Its creation, the agent's write access and its removal are temporary gaps closed by the follow-up PR (PR 2 of this stack: skill + delivery + folder lifecycle); the host never deletes a chat today (closing only hides it), so PR 2 derives the folder's lifetime from the chat record.
• Fitted height + live theme updates — matches the common pattern.
• Network: CDN allowlist for assets, no connect — intended, a disclosed residual risk: a page can still encode data in a request to an allowed CDN, and CSP cannot stop WebRTC or DNS prefetch (the same residual Orca's plugin panels already have). Orca does not claim "no data leaves".
• Web client: there is no main process, so its navigation fence is the shell's script-level lock plus "a second load retires the frame" — intended, with the limits stated here.
• Local images by path are not inlined; pages use data: images, inline SVG or CDN assets — intended v1.
• No headless preview/screenshot tool for the agent — intended v1.
• Mobile rendering — temporary, PR 3 of this stack (native isolated WebView frame using the same grammar and shell).
• Old viewers show the reply line as text — intended while native chat has no real users.

Linked Issue

N/A — maintainer change, part of the inline chat visuals stack (PR 1 of 3: rendering).

Visual Proof

Live QA on macOS (Electron dev build of 4cd8bd2bda1; later commits are review/CI fixes covered by unit tests, hidden window over CDP, isolated profile; the chat runs a stand-in Claude CLI so no real agent was involved; driven by a separate QA agent). Before this PR, the same reply line shows as plain text, as in the code-block/quote example below.

A reply with a visual (dark)	Same chart after a theme switch — the click count inside it survived (no reload)

Open in sidebar (widened; stored width unchanged)	Unavailable visual — one muted line

The line inside code, a quote and inline code stays text	Two visuals in one reply (table fitted to 930 px)	Sidebar agent row shows prose, never the line

QA results (run 3). Inline render (A), interaction + live theme without reload (B), fitted height after a width change (C, no inner overflow), Open in sidebar incl. keyboard focus, width restore and tab supersede (D), unavailable line (E), literal forms (F), plain-text sidebar row (I), Copy message without the line (K), containment — location.href assignment, window.open → null, fetch blocked by CSP (L), console (X): pass.

• H (two visuals + runaway height): the QA agent reported FAIL ("only one new frame"). I re-classified it as pass from a direct DOM read of that reply: it holds both frames, Usage by day (307 px) and Usage table (930 px). The agent counted new frames across the whole transcript; the likely reason the count came out short is that the transcript is windowed and unmounts rows scrolled far away — I did not confirm that cause. The runaway page held at 512 px over 24 samples (below the 2000 px cap).
• G (streaming): only partly verified live — the frame kept its identity while the rest of the reply streamed in, but hiding a half-written line mid-stream was not sampled live (the agent's sampling loop hit its time cap). Covered by NativeChatMarkdown.visual.test.tsx (tail held while the turn works, shown once it ends, an earlier row of the same turn not held) and native-chat-visual-directive.test.ts (streaming tail).
• Not verified live: G's mid-stream hiding (above); the web client and a paired remote runtime (same renderer code; unit-tested message/frame logic); Windows and Linux; clicking a link through to the system browser (deliberately not done; the gate is unit-tested).
• Real agent configs (~/.codex/config.toml, ~/.codex/hooks.json, ~/.claude/settings.json) were hashed before and after each run: unchanged in run 3.

Testing

• Automated (explicit files, all green locally): grammar and streaming tail (native-chat-visual-directive.test.ts), shell CSP/message schema (native-chat-visual-shell.test.ts), height governor, host read containment incl. symlinks to a sibling chat / another workspace, a symlinked folder or root, FIFO, directory, size cap, binary/invalid UTF-8, swapped files (native-chat-visual-file-read.test.ts), the RPC method (params, refusals, capability gate, registration), the main-process frame guard for both kinds, Markdown contexts (fences, indented/inline code, quotes, lists, raw HTML forgery, per-reply cap, reference links), read-client cache/revalidation/de-dup/eviction, the frame (sandbox, name, CSP first, height from the right window/channel only, live theme without reload, link gating, second-load retire), the sidebar route (open/close/restore, supersede by a tab, width), the plain-text producers (status summary, AI Vault previews) and the copy button.

• Typecheck: config/tsconfig.node.json and config/tsconfig.tc.web.json clean on the final head; full CI green on ff394428854.

• Lint/gates: oxlint on changed files, audit:anti-slop, audit:code-quality:native, check:code-quality:changed, RPC params catalog, localization coverage/extraction.

• Manual: macOS, Electron dev build, hidden window over CDP, isolated profile with a stand-in Claude CLI (no real agent) — see Visual Proof and the review comment.

• I manually tested these changes locally

• Automated tests added/updated, or explained why not below

Review

Review summary posted as a PR comment.

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Security: see mechanism 3–4 and the residual risks above; two dedicated security review passes.
• Cross-platform: file names refuse Windows device names, drive/UNC/stream forms; containment uses Node path APIs and a case-insensitive basename compare; no shortcuts added.
• SSH / remote: the read runs on the host that owns the chat (local desktop or a paired remote runtime); structured chats on direct SSH/WSL return unsupported_location. Links open on the viewing client, never on a paired host.
• Mobile: phones are not allowed to call the new method yet (PR 3 adds it to the mobile allowlist); the grammar and shell are in src/shared for it.
• Backwards compatibility: additive RPC method behind the existing structured-session capability; old hosts → "unavailable".
• Performance: frames mount lazily when scrolled near and stay mounted; at most 8 per reply; a bounded client cache (24 entries / 6 MB).

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

[brennanb2025]

Review summary

What this PR does: native-chat replies can show an agent-written HTML visual inline (and in the right sidebar), read from an Orca-owned per-chat folder on the host that owns the chat, inside an opaque sandboxed frame. Details are in the PR body.

Review rounds (self-review with separate reviewer agents; findings fixed before this comment)

1. Security pass (whole diff) — no P0/P1. Fixed: the visuals folder is re-checked after the open so a symlink swapped in and out around the first check cannot redirect a read (P3); unexpected filesystem faults reach clients as visual_read_failed:<code> without host paths (P3); one click in a visual opens at most one link (5 s, matching Chromium's activation window) (P3). Disclosed, not fixable by CSP: WebRTC and DNS prefetch (same residual as plugin panels); the web client's navigation fence is script-level plus "a second load retires the frame".
2. Correctness pass (whole diff) — no P0/P1. Fixed: a page pinned to 100% height was stuck at the reserved height (P2); a finished visual line stayed hidden for the rest of a working turn (P2) — now only the live turn's last row, still ending in prose, holds a half-written line; the runaway-height stop could freeze an animated expansion (P3) — it now needs the same small step repeated; a refused re-read could briefly show the old cached copy (P3) — any refusal evicts it.
3. Re-review of the fix commits — no P0/P1. Fixed: Agent Session History previews still showed the line because providers fold lines before the strip ran (P2) — now stripped per text part first; the overflow measurement could grow a padded full-height page (P2) — now adds a body's overflow only when it really overflows; fence tracking followed CommonMark loosely (P3) — closers take no info string, backtick openers no backtick.
4. Re-review of the last fix commits — no P0/P1/P2. Fixed two P3s: removing visual lines for a copy collapsed blank lines inside code blocks and trimmed a leading indent (now only the gap each removal leaves is closed); the folder check could answer either of two errors for one broken path (now parent first). Disclosed P3s: a page pinned to 100% height with content-box body padding or margin can lose its bottom few pixels (such a page has no stable height; counting that overflow brings back self-growth); if a new revision and a theme change land in the same render, the first paint uses the previous theme until load (corrected then).

• From the stacked PRs' live QA: the raw line leaked into the sidebar agent row → one shared helper (withoutNativeChatVisualDirectiveLines) applied at the single "last reply" producer (sidebar row, dashboard, notifications, phone rows, handoffs) and AI Vault previews; Copy message copies the reply without the line.
• CI caught two of mine: React Doctor flagged a ref written during render in the frame (moved into a layout effect), and the cross-version wire suite's agentSession.* manifest lacked agentSession.readVisual (entry added; the stub host answers the typed session_not_found).

Live QA (macOS, Electron dev build, hidden window over CDP, isolated profile, stand-in Claude CLI; driven by a separate QA agent)

• Pass: A inline render · B interaction + live theme without reload (clicks: 1 survived light↔dark) · C fitted height after a width change (no inner overflow) · D Open in sidebar (keyboard reachable; stored width 350 unchanged; close restores; picking a tab supersedes) · E "Visualization unavailable" line, no toast · F literal forms in code/quote/inline code · I sidebar agent row shows prose only · K Copy message omits the line · L containment (location.href assignment kept the chart; window.open → null; fetch blocked by connect-src 'none') · X no visual/frame/CSP console errors beyond L's expected CSP refusals.
• H (two visuals + runaway): the QA agent reported FAIL ("only one new frame"). Re-classified as pass from a direct DOM read of that reply: both frames are in it — Usage by day (307 px) and Usage table (930 px). The agent counted new frames across the whole transcript; the likely cause of the short count is transcript windowing unmounting far-away rows, which I did not confirm. Runaway page held at 512 px over 24 samples.
• G (streaming): partly verified. The frame kept its identity while the rest of the reply streamed; hiding a half-written line mid-stream was not sampled live. Covered by NativeChatMarkdown.visual.test.tsx and native-chat-visual-directive.test.ts.
• Real ~/.codex/config.toml, ~/.codex/hooks.json, ~/.claude/settings.json hashed before/after: unchanged in the final run. (During an earlier run ~/.codex/config.toml changed; it coincides with a codex app-server started by the installed Orca app, not the QA rig, and contains no rig paths; left as is.)

Not verified

• Live: G's mid-stream hiding; the web client; a paired remote runtime; Windows and Linux; a link click through to the system browser (deliberately not done; gating is unit-tested).
• Mobile is PR 3 of this stack; folder creation, agent write access and folder removal are PR 2.

CI (head ff3944288540d2a62bfe877b28c9bd77b680abf1)

• All checks finished green on the first attempt: static analysis and typecheck, test shards 1–5, relay integration, cross-version wire compatibility, package (macOS/Linux and Windows), Mobile Checks, verify. 15 pass, 17 skipped by path filters, 0 failing.
• Earlier heads, classified: e1b383363b7 — React Doctor error (mine: ref written during render) → fixed. 7b9f21eda36 — cross-version wire (mine: manifest missing agentSession.readVisual) → fixed. 7a1977c762e — src/shared/repo-ref-maintenance.test.ts "runs one repository at a time" timed out waiting 10 s for a second repository: not touched by this PR, passes locally, passed on re-run → timing flake, no change.
• Main-owned reds seen along the way (not carried here; fixed on main and merged in): src/main/acp/acp-structured-host-restore-failed.test.ts:227 (tc:node, spied on a removed method) and src/renderer/src/components/native-chat/native-chat-composer-field-resume.test.tsx:100 (tc:web, fixed by fix(native-chat): repair main's web typecheck after the @-mention prop rename #26097).
• The two round-4 P3 fixes in ff394428854 are covered by new unit tests; they were not re-reviewed by a separate reviewer.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: b2a94032-3fb8-49ad-be0d-91b5ca02f668

📥 Commits

Reviewing files that changed from the base of the PR and between c8dcffc and ff39442.

⛔ Files ignored due to path filters (1)

• src/shared/rpc-contract/rpc-params-catalog.generated.ts is excluded by !**/*.generated.*

📒 Files selected for processing (49)

• src/main/ai-vault/session-scanner-accumulator.ts
• src/main/ai-vault/session-scanner-text-normalization.ts
• src/main/ai-vault/session-scanner-values.test.ts
• src/main/native-chat/native-chat-visual-file-read.test.ts
• src/main/native-chat/native-chat-visual-file-read.ts
• src/main/native-chat/native-chat-visuals-folder.ts
• src/main/runtime/rpc/methods/index.ts
• src/main/runtime/rpc/methods/structured-agent-session-rpc.test-fixture.ts
• src/main/runtime/rpc/methods/structured-agent-session-visual.test.ts
• src/main/runtime/rpc/methods/structured-agent-session-visual.ts
• src/main/window/host-frame-navigation-guard.test.ts
• src/main/window/host-frame-navigation-guard.ts
• src/main/window/main-window-webview-security.test.ts
• src/main/window/main-window-webview-security.ts
• src/renderer/src/components/native-chat/NativeChatInlineVisual.tsx
• src/renderer/src/components/native-chat/NativeChatMarkdown.tsx
• src/renderer/src/components/native-chat/NativeChatMarkdown.visual.test.tsx
• src/renderer/src/components/native-chat/NativeChatMessageRow.test.tsx
• src/renderer/src/components/native-chat/NativeChatMessageRow.tsx
• src/renderer/src/components/native-chat/NativeChatTranscriptChrome.tsx
• src/renderer/src/components/native-chat/NativeChatView.tsx
• src/renderer/src/components/native-chat/NativeChatVisualFrame.test.tsx
• src/renderer/src/components/native-chat/NativeChatVisualFrame.tsx
• src/renderer/src/components/native-chat/NativeChatVisualPanel.tsx
• src/renderer/src/components/native-chat/native-chat-visual-markdown-extension.tsx
• src/renderer/src/components/native-chat/native-chat-visual-markdown-syntax.test.tsx
• src/renderer/src/components/native-chat/native-chat-visual-markdown-syntax.ts
• src/renderer/src/components/native-chat/native-chat-visual-owner.tsx
• src/renderer/src/components/native-chat/native-chat-visual-read-client.test.ts
• src/renderer/src/components/native-chat/native-chat-visual-read-client.ts
• src/renderer/src/components/native-chat/use-native-chat-visual-document.ts
• src/renderer/src/components/native-chat/use-native-chat-visual-theme.ts
• src/renderer/src/components/right-sidebar/index.tsx
• src/renderer/src/components/right-sidebar/right-sidebar-panel-content.tsx
• src/renderer/src/components/right-sidebar/right-sidebar-width.ts
• src/renderer/src/components/sidebar/CommentMarkdown.tsx
• src/renderer/src/i18n/locales/en.json
• src/renderer/src/store/slices/editor/actions/right-sidebar-state.ts
• src/renderer/src/store/slices/editor/actions/right-sidebar-visual-state.test.ts
• src/shared/native-chat-visual-directive.test.ts
• src/shared/native-chat-visual-directive.ts
• src/shared/native-chat-visual-height-governor.test.ts
• src/shared/native-chat-visual-height-governor.ts
• src/shared/native-chat-visual-shell.test.ts
• src/shared/native-chat-visual-shell.ts
• src/shared/rpc-contract/agent-session-visual-params.ts
• src/shared/structured-agent-session-latest-request.test.ts
• src/shared/structured-agent-session-latest-request.ts
• tests/e2e/cross-version-wire/structured-agent-session-surface-manifest.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds native-chat visual directives and renders supported visuals inline or in the right sidebar. It adds shared directive parsing, a runtime RPC for reading session visual files, revision-aware renderer loading, and sandboxed iframe documents with theme and size messaging. Assistant previews, message summaries, and copy actions filter directive lines. Tests cover parsing, file access, RPC behavior, renderer state, frame handling, and sidebar state.

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to ff394

This change shows agent-written HTML visuals inline in structured chats. Each visual is read from that chat's own folder on the host and runs in a sandboxed frame with a strict security policy. Review found no concrete defects. The web client and remote runtimes were not tested live, but the change looks ready to merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 34.31% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 102 functions across 48 files. (1 skipped…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: rendering agent-written visuals inline in structured native chats.
Description check	✅ Passed	The description covers the required sections, including the user-facing change, rationale, linked-issue exception for a maintainer, visual proof, testing, review, agent-skill boundary, notes, and chec…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 34.31% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 102 functions across 48 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}