Skip to content

fix(mcp): report a failed recording start's reason instead of a 30s timeout - #1641

Merged
EtienneLescot merged 3 commits into
getopenscreen:mainfrom
IdrisGit:fix/mcp-start-failure-reason
Nov 21, 2026
Merged

EtienneLescot merged 3 commits into
getopenscreen:mainfrom
IdrisGit:fix/mcp-start-failure-reason

Conversation

@IdrisGit

@IdrisGit IdrisGit commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Summary

startRecording (stdio MCP) and openscreen record now fail immediately when the recorder already knows its start failed, returning the recorder's reason instead of "Recording did not start within 30s — see stderr".

  • startRecording answers with an outcome — started, cancelled, or failed with the message its toast already showed. GUI behavior unchanged; countdown and restart ignore it.
  • The hidden runner fails fast on a failed or cancelled start (picker dismissed), appending Retry with "cursor": "system" … only to the cursor-metadata failure, matched on the helper's typed wording so it cannot misfire.
  • The 30-second deadline remains only as a backstop for a start that reports success but the recording state never confirms; the camera-open failure (MCP recording with camera: true has no webcam on Linux while the app is running #1303) still wins their race.

Related issue

Fixes #1640

Type of change

  • Bug fix

Release impact

  • Patch

Desktop impact

  • Windows
  • macOS
  • Linux

Screenshots / video

None — no UI change.

Summary by CodeRabbit

  • Bug Fixes
    • Recording start failures now report the recorder’s specific error instead of a generic timeout.
    • Cancelling the screen-share picker is reported as a cancellation, not a recording error.
    • Cursor-related recording failures include a retry hint when available.
    • A camera-open failure is preserved if it occurs before a delayed recording-start failure.
    • If recording start is not confirmed within 30 seconds, the error explains that confirmation timed out.

The start funnel caught every failure, showed its toast and resolved
normally, so a caller could only learn of a failed start from recording
state that never flips. startRecording now answers with an outcome:
started, cancelled, or failed with the message the toast showed. The
countdown and restart paths ignore it as before.
A start the recorder had already failed left the hidden runner guessing:
its deadline answered MCP startRecording and `openscreen record` with
"Recording did not start within 30s — see stderr". The runner now fails
at once with the outcome's reason, says when the picker was dismissed,
and appends the system-cursor retry advice only to the cursor-metadata
failure. The deadline remains only as a backstop for a start that
reports success but never confirms; in a race with the camera effect
(getopenscreen#1303) the first error still wins.
FakeRunners can now name a record start's failure. Assert the
startRecording tool error carries that reason, so the forwarding above
the runner stays honest.
@coderabbitai

coderabbitai Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The recorder now returns an explicit outcome for successful, cancelled, and failed starts. The CLI reports start failures and picker dismissal, preserves earlier errors, and distinguishes an unconfirmed recording from a known start failure. Tests cover these outcomes and MCP error reporting.

Changes: Recording start failure reporting

Layer / File(s) Summary
Recorder start outcomes
src/hooks/useScreenRecorder.ts, src/hooks/useScreenRecorder.startCancel.test.tsx
startRecording returns a started, cancelled, or failed outcome. Failed outcomes include a message. Native and browser start paths return these outcomes, and tests cover success, cancellation, and failure.
Client failure reporting
src/cli/CliRecordRunner.tsx, src/cli/CliRecordRunner.test.tsx, electron/mcp/media-tools.test.ts
The CLI reports start failures, adds cursor retry advice for matching errors, preserves an earlier camera-open error, and reports when recording state is not confirmed within 30 seconds. Tests cover these cases and MCP reporting of a recorder-specific failure.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Possibly related PRs

  • getopenscreen/openscreen#1371: Updates CliRecordRunner camera-open failure handling during recording startup. The current change preserves that failure when a delayed start error follows.
Merge Risk: Minimal · up to 9447c

Known recording-start failures now return their reason immediately, while unconfirmed successful starts retain the timeout. No concrete merge-blocking issue is established; normal checks should pass before merging.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: a failed recording start now reports the recorder's reason instead of the generic 30-second timeout. It matches the linked issue #1640 and the changeset, which adds a …
Description check Passed The description follows the repository template. It has a Summary that explains the fail-fast behavior and the retained 30-second backstop. It links the issue with 'Fixes #1640' and marks Bug fix, Pat…
Linked Issues check Passed Issue #1640 requires that a start already known to have failed returns the recorder reason immediately. The timeout must apply only to unknown outcomes. The PR meets this requirement as follows:
- `us…
Out of Scope Changes check Passed All changed areas support the #1640 objective:
- useScreenRecorder.ts: the outcome type and return values are needed to report the start result to the runner and the MCP tool. The public `startRecor…
Full details: Title check

Explanation

The title names the main change: a failed recording start now reports the recorder's reason instead of the generic 30-second timeout. It matches the linked issue #1640 and the changeset, which adds a RecordingStartOutcome and fail-fast handling in the hidden runner and the startRecording MCP tool. The fix(mcp) prefix is a conventional commit style and the title is 75 characters, within normal limits.

Full details: Description check

Explanation

The description follows the repository template. It has a Summary that explains the fail-fast behavior and the retained 30-second backstop. It links the issue with 'Fixes #1640' and marks Bug fix, Patch, and all three desktop platforms. The Testing section is missing. The template asks for how the change was tested, and the description does not include commands, steps, or environment details. The Screenshots section says 'None — no UI change', which is acceptable.

Resolution

Consider adding a Testing section that lists the commands or steps used to verify the change, such as the new tests in CliRecordRunner.test.tsx, useScreenRecorder.startCancel.test.tsx, and media-tools.test.ts.

Full details: Linked Issues check

Explanation

Issue #1640 requires that a start already known to have failed returns the recorder reason immediately. The timeout must apply only to unknown outcomes. The PR meets this requirement as follows:

  • useScreenRecorder.ts adds RecordingStartOutcome (started, cancelled, failed with message). startRecording returns this outcome. Caught start errors and missing sources return failed with a message.
  • CliRecordRunner.tsx checks the outcome from startRecordingImmediately(). A failed outcome ends the run with the recorder message. A cancelled outcome ends the run with a picker-dismissal error.
  • The cursor-metadata retry hint (Retry with "cursor": "system") is added only when the failure text contains advertise METADATA cursor mode. This matches the reported Hyprland failure.
  • The 30-second timeout remains only when a start reports success but recording state never confirms.
  • media-tools.test.ts adds a test that a recorder-specific failure reaches the MCP client. CliRecordRunner.test.tsx and useScreenRecorder.startCancel.test.tsx cover failed, cancelled, started, camera-precedence, and backstop cases.

I did not inspect the full diff. This verdict relies on the PR summary and the test descriptions. The code path from the MCP startRecording tool to the runner error was not traced line by line.

Full details: Out of Scope Changes check

Explanation

All changed areas support the #1640 objective:

  • useScreenRecorder.ts: the outcome type and return values are needed to report the start result to the runner and the MCP tool. The public startRecordingImmediately signature changes to return the outcome, which is required for that reporting.
  • CliRecordRunner.tsx: fail-fast handling, cursor retry advice, and the reworded backstop timeout message implement the requested behavior.
  • Test files: these cover the new behavior. They contain no unrelated changes.

The PR description states that GUI behavior is unchanged. The summaries show that countdown and restart code ignore the outcome, so no unrelated UI behavior change is evident.

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

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: 94cfcb65-63c4-4f58-9363-5b73970c426d
Commits

Reviewing files that changed from the base of the PR and between c1a2c97 and 9447c0c.

Files selected for processing: 5

  • electron/mcp/media-tools.test.ts
  • src/cli/CliRecordRunner.test.tsx
  • src/cli/CliRecordRunner.tsx
  • src/hooks/useScreenRecorder.startCancel.test.tsx
  • src/hooks/useScreenRecorder.ts

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

@EtienneLescot
EtienneLescot merged commit 00a0d96 into getopenscreen:main Nov 21, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: MCP startRecording over stdio reports a 30s timeout instead of the capture failure

2 participants