[auberginewly]

Summary

Add waitForRecording to the in-app MCP server so a client can wait while the user records and stops a take from the HUD. The call binds to the current recording ID, includes finalization and project saving, and returns the same recording result fields as stopRecording.

timeoutSec accepts 1–3600 seconds (default 300). Idle calls fail immediately. Timeout, request cancellation and HTTP disconnect release only the wait; they never stop the recording. Concurrent waits are independent. Cancelled, failed and superseded takes cannot be mistaken for a later take or an imported project.

The recorder reports terminal failures/discards, and the editor acknowledges the take after its duration and automatic-zoom saves. The main process reads the persisted project and checks its measured clip and nonempty media before completing waits. Completed client takes release their recorder claim so another startRecording works without an extra stop call.

Observation works with MCP edits off, behind the existing HTTP authentication and origin checks. No MCP notifications or command hooks are introduced. The stdio server registers an explanatory unsupported-tool response; clients observing the GUI must connect to the in-app HTTP server.

Related issue

Fixes #1188

Type of change

• Bug fix
• Feature
• Enhancement
• Documentation
• Refactor / maintenance
• Performance
• Security

Release impact

• Patch
• Minor
• Major / breaking change
• No release note needed

Desktop impact

• Windows
• macOS
• Linux
• Installer / packaging
• Not platform-specific

Screenshots / video

No visual UI changes. The scoped real-desktop attempt and its capture blocker are recorded in technical-documentation/testing/manual-e2e-checklist.md.

Testing

Tested locally on macOS 15.8 arm64, Node 22.22.1 / npm 10.9.4, based on upstream main d8bf2d81.

• Targeted Vitest run: 191 tests passed across nine recorder, MCP, HTTP, import and native-stop suites.
• npm run test: 4955 passed, 7 skipped; 354 suites passed, one skipped.
• npx tsc --noEmit and npx tsc -p tsconfig.test.json --noEmit: passed.
• Related-file npx biome check: passed without diagnostics. Full npm run lint and npm run lint:fix: exit 0, 26 existing warnings; no automatic changes.
• npm run docs:check: passed (37 files). git diff --check: passed.
• Regression coverage includes immediate completion after subscription, target isolation, concurrent waits, retry after timeout, already-aborted requests, MCP cancellation, HTTP disconnect cleanup, save/import failure, discard, persisted project/media readiness and reuse of the recording slot. Removing the recording ID guard makes the isolation regression fail; restoring it passes all 17 completion tests.
• Real Electron 41.2.1 + authenticated HTTP MCP, isolated userData and ports (Vite 5188, MCP 47888, CDP 9388): idle waitForRecording returned HTTP 200 with isError: true in 679 ms.
• Real recording remains unverified: computer-use selected Screen 1 and pressed Record on the HUD, which reported “Native macOS capture helper is not available.” The borrowed native directory has the compositor/ffmpeg but no capture helper, and npm run build:native:mac is blocked by the absence of full Xcode. Consequently, HUD recording → wait → manual stop → result and timeout during a real ongoing recording were skipped. Fixture/SDK/HTTP tests are not claimed as real capture validation. Windows/Linux desktop capture, webcam, transcription and export were not exercised.

The initial full run encountered an optional peer dependency missing after installation with the host's npm 11. Reinstalling with the repository's pinned Node/npm and including optional/peer dependencies restored @noble/hashes; the AppImage suite then passed all 14 tests, followed by the passing full run above. Package manifests and lockfile are unchanged.

Summary by CodeRabbit

• New Features
  • Added an MCP tool to wait for an active recording to finish and become available in the editor, without starting or stopping capture.
  • Waits can time out or be cancelled without interrupting the recording.
• Bug Fixes
  • Recording waits now report failures or discarded takes instead of leaving them unresolved.
• Documentation
  • Updated MCP guidance and manual checks for recording waits, including timeout and cancellation behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: bd28da57-b69d-4ae6-b965-ca8fb852fc1e

📥 Commits

Reviewing files that changed from the base of the PR and between d8bf2d8 and e06e69b.

📒 Files selected for processing: 19

• electron/electron-env.d.ts
• electron/ipc/handlers.ts
• electron/ipc/recordingStateRouting.test.ts
• electron/mcp/app-recorder.test.ts
• electron/mcp/app-recorder.ts
• electron/mcp/media-tools.test.ts
• electron/mcp/media-tools.ts
• electron/mcp/openscreen-mcp-server.test.ts
• electron/mcp/recording-completion.test.ts
• electron/mcp/recording-completion.ts
• electron/preload.ts
• src/components/ai-edition/recordingImport.test.ts
• src/components/ai-edition/recordingImport.ts
• src/hooks/useScreenRecorder.nativeStopFailure.test.tsx
• src/hooks/useScreenRecorder.ts
• src/lib/recordingSession.ts
• technical-documentation/architecture/mcp-server.md
• technical-documentation/architecture/recording.md
• technical-documentation/testing/manual-e2e-checklist.md

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

📝 Walkthrough

The change adds an MCP tool that observes user-controlled recordings and returns their project and media details after editor saves complete. Recording outcomes are associated with recording IDs. Timeout and cancellation end the wait without stopping the recording.

Changes: Recording lifecycle and MCP observation

Layer / File(s)	Summary
Report recording handoff outcomes src/lib/recordingSession.ts, electron/preload.ts, electron/electron-env.d.ts, src/hooks/useScreenRecorder.ts, src/components/ai-edition/recordingImport.ts, related tests	The renderer reports failed or cancelled recordings and reports ready after the imported project meets save, duration, and auto-zoom conditions. The Electron API carries these outcomes.
Track take lifecycle and verify completion electron/mcp/recording-completion.ts, electron/ipc/handlers.ts, electron/mcp/app-recorder.ts, related tests	The main process tracks recording IDs and saved media, verifies the persisted project and media before completion, and releases an app-recorder take only for the matching ID.
Expose the MCP recording wait electron/mcp/media-tools.ts, electron/ipc/handlers.ts, electron/mcp/openscreen-mcp-server.test.ts, electron/mcp/media-tools.test.ts, technical-documentation/architecture/*, technical-documentation/testing/manual-e2e-checklist.md	The MCP server adds waitForRecording, which returns the shared recording result or an error. Tests and documentation cover idle waits, timeout, cancellation, and request disconnects.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant MCPClient
  participant WaitForRecording
  participant RecordingCompletion
  participant RecordingImport
  participant ElectronIPC
  MCPClient->>WaitForRecording: Request waitForRecording
  WaitForRecording->>RecordingCompletion: Wait with timeout and abort signal
  RecordingImport->>ElectronIPC: Report ready after project saves
  ElectronIPC->>RecordingCompletion: Verify project readiness for recording ID
  RecordingCompletion-->>WaitForRecording: Return completed recording
  WaitForRecording-->>MCPClient: Return project and take details

Loading

Merge Risk: ⚪ Minimal · up to e06e6

The recording-wait change is ready to merge after normal checks. Real HUD capture remains unverified, but no current failure has been established.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 20 functions across 16 files. (3 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely identifies the main change: adding the waitForRecording MCP tool for user-controlled recordings.
Description check		The description follows the repository template and provides a detailed summary, linked issue, change classification, release and desktop impact, screenshot information, and comprehensive testing resu…
Linked Issues check		Issue #1188 requests a way for an MCP client or script to detect that a user-controlled take ended and was saved. The PR adds the in-app HTTP waitForRecording tool. The tool observes the current rec…
Out of Scope Changes check		The changes stay connected to #1188. Recorder outcome reporting, recording-ID tracking, project/media readiness checks, and editor acknowledgements support reliable completion detection. Tests and arc…

Full details: Description check

Explanation

The description follows the repository template and provides a detailed summary, linked issue, change classification, release and desktop impact, screenshot information, and comprehensive testing results, including known real-recording limitations.

Full details: Linked Issues check

Explanation

Issue #1188 requests a way for an MCP client or script to detect that a user-controlled take ended and was saved. The PR adds the in-app HTTP waitForRecording tool. The tool observes the current recording, waits for finalization and project readiness, and returns the recording result. Recording IDs, failure states, cancellation, timeout, disconnect handling, and MCP-edits-off operation address the issue's stated use case. The reported automated tests cover completion, isolation, persistence, failure, cancellation, and reuse of the recording slot.

Full details: Out of Scope Changes check

Explanation

The changes stay connected to #1188. Recorder outcome reporting, recording-ID tracking, project/media readiness checks, and editor acknowledgements support reliable completion detection. Tests and architecture/testing documentation cover the new tool and its failure modes. The reported real-capture limitation does not show an unrelated code change.

Full details: Docstring Coverage

Explanation

Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 20 functions across 16 files. (3 skipped: 3 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · 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.}