[ogulcancelik]

Summary

herdr terminal session control has no way to send mouse input, so bridge clients can't click buttons in TUIs that enabled mouse reporting (for example an agent's "scroll to bottom" button).

This adds a terminal.mouse command to the control stream:

{"type":"terminal.mouse","action":"down","button":"left","column":12,"row":5}

• action is down, up, drag, or move; button is left (default), right, or middle; modifiers is optional (Shift = 1, Ctrl = 2, Alt = 4). Cells are zero-based in the controller's viewport, like terminal.scroll. A click is down then up.
• It maps onto the existing ClientMessage::AttachMouse that herdr agent attach already uses, so there is no new wire message and no server change. The server encodes the event for the pane's mouse mode and drops it when the application hasn't enabled mouse reporting, so a plain shell never receives stray escape bytes.

Why not let clients write mouse bytes through terminal.input: control frames are re-rendered output, so a client can't see whether the application enabled mouse reporting or which encoding it wants. Guessing would type [<0;12;5M into apps that didn't ask for mouse input.

Docs: CLI reference and persistence/remote pages (en, ja, zh-cn).

Testing

• Parser tests for every action and button, modifiers, and rejection of unknown actions or missing cells.
• Server test: down, drag, up, and move to a runtime without mouse reporting send no bytes. The neighboring existing test shows the same click with 1000h/1006h encodes \x1b[<0;11;6M.
• Manual, real CLI: a pane running printf '\e[?1000h\e[?1006h'; cat -v received ^[[<0;13;6M ^[[<0;13;6m from a control-session click; a plain cat -v pane received nothing.
• just check on macOS and Linux, including Windows lint.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

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: aa4d69d8-ffbe-46ff-8e4c-242c772a9ca1

📥 Commits

Reviewing files that changed from the base of the PR and between 316d176 and bc47fd2.

📒 Files selected for processing (9)

• docs/next/website/src/content/docs/cli-reference.mdx
• docs/next/website/src/content/docs/ja/cli-reference.mdx
• docs/next/website/src/content/docs/ja/persistence-remote.mdx
• docs/next/website/src/content/docs/persistence-remote.mdx
• docs/next/website/src/content/docs/zh-cn/cli-reference.mdx
• docs/next/website/src/content/docs/zh-cn/persistence-remote.mdx
• src/client/terminal_sessions.rs
• src/client/tests/mod.rs
• src/server/headless/tests/mod.rs

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

---

📝 Walkthrough

Walkthrough

The control parser now accepts terminal.mouse commands and maps their actions, buttons, cell coordinates, and modifiers to mouse messages. Tests cover defaults, action mappings, invalid commands, and behavior when mouse reporting is disabled. Documentation in English, Japanese, and Chinese describes the command format and its delivery rules.

Suggested reviewers: jjliebig, minatoaquamk2

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to bc47f

The new mouse command has no established issue requiring a fix before merge.

Security Architecture Review

Security architecture risk: 🔵 Low · up to bc47f

A controller gains a mouse command for applications that request mouse input. The command uses the existing writable-session path, and the reviewed server checks still limit where events can go. No PR-introduced security finding was established, though interruption behavior and broader deployment context remain uncertain.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — A command's immediate input destination is the terminal attached to that writable connection, not a target named in the mouse payload. The inspected path does not establish a separate tenant-identity boundary.

Security Findings and Attack Paths

• inferred — A writable controller can now request mouse actions in a mouse-aware terminal application, potentially activating its UI. This is not an established authorization expansion: the same controller already had raw input, and direct-attach clients already used AttachMouse.

Trust Boundaries and Controls

• observed — Control acquisition uses the existing pending-connection and writable-owner checks. Takeover removes the prior owner; later mouse events from a removed client fail the server's client lookup.
• observed — Invalid cell positions are rejected before pane input, and the added test observes no delivered bytes for down, drag, up, or move when mouse reporting is disabled.

Resilience and Maintainability Implications

• inferred — Ownership is cleaned up on disconnect or takeover, but recovery of an application-level pressed-button state after an interrupted down/drag sequence is not established. The inspected path sends events individually and has no synthetic release on teardown.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: accepting mouse events through terminal session control.
Description check	✅ Passed	The description directly explains the new terminal.mouse command, supported inputs, behavior, documentation changes, and testing.
Docstring Coverage	✅ Passed	Docstring coverage is 88.89% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 3 files. (6 skipped: 6 u…
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.

---

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.}

[kangal-bot]

@coderabbitai review
@greptileai

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[greptile-apps]

Confidence Score: 5/5

[Critical risk] Adds mouse event support to terminal control protocol.

The PR appears safe to merge; no actionable regression was identified.

Summary

The PR adds terminal.mouse to the terminal-session control JSON stream, maps it to the existing attach-mouse message, and documents the command in English, Japanese, and Chinese. Parser and server tests cover command mapping and suppression when mouse reporting is disabled.

Diagram

sequenceDiagram
    participant C as Control client
    participant H as Herdr client
    participant S as Headless server
    participant T as Terminal runtime
    C->>H: terminal.mouse JSON
    H->>S: AttachMouse
    S->>S: Check writable attachment and cell
    S->>T: Mouse event
    T->>T: Check application mouse mode
    T-->>C: Mouse report through PTY, if enabled

Loading

_{Reviews (1) · Last reviewed commit: "feat: accept mouse events on terminal se..."}