Skip to content

feat(macos): warn when Automation is missing, and toast key presses macOS blocks - #205

Merged
jonocodes merged 2 commits into
mainfrom
implement-196
Nov 19, 2026
Merged

jonocodes merged 2 commits into
mainfrom
implement-196

Conversation

@jonocodes

Copy link
Copy Markdown
Owner

On macOS, key buttons (Firefox New window sends ⌘N, for example) go through osascript → System Events. That needs two grants: Automation for System Events, and Accessibility. When either was missing, the press did nothing and only the daemon log said why. A missing Automation grant also left the deck stuck on the wrong app. #195 added a banner for Accessibility only.

Now the phone tells you about both, before you press anything and again when a press is refused.

Banner before any press. The daemon asks TCC with AEDeterminePermissionToAutomateTarget, which doesn't show the system prompt, whether it may control System Events. If not, it raises automation_system_events_missing through the #195 health channel. The fix steps name Privacy & Security → Automation → System Events. Automation can't be added with +, so for the packaged app they also give tccutil reset AppleEvents com.deckd.daemon.

Failures caught as they happen. osascript stderr is classified by its trailing error number: (-1743) is Automation, (1002) is Accessibility, and anything else is ignored. This covers the focus query, key presses and the startup check, so the banner still appears when the direct check can't tell or is wrong. A held refusal is re-checked with an empty keystroke on each health poll, so it clears without a restart. A healthy Mac never runs that extra check.

Toast within a second. A refused key press sends an action_error frame to the phone that pressed it ("Key press blocked: deckd.app needs Accessibility permission.") and re-polls health straight away, so the toast and the banner arrive together. This covers key: and text: buttons, macro key steps, and manual-control keys and typing. A macro stops at the refused step. If a refused paste's Ctrl+V fails, the user's clipboard is put back. Refusals are recorded as outcome="permission_denied" in /actions/recent and /metrics.

Other changes:

  • Health probes now run off the event loop.
  • conftest stubs the permission checks, so test results no longer depend on the developer's own Mac grants.
  • README, GUIDE, REFERENCE, CONTEXT and PLATFORM-PARITY are updated.

Worth a look:

  • A refused widget press is recorded as ok (dispatched) and then permission_denied, the same pairing a failed macro already gets.
  • With --no-focus there is no platform backend, so the toast appears but no banner does.

Tests:

  • pytest: 869 passed. New: stderr classification with false-positive cases, ledger transitions, the TCC status mapping, the wire shape, and server tests for the toast, ring buffer, metrics and immediate banner.
  • vitest: 436 passed.
  • The direct Automation check returns "granted" on a Mac where it is granted.

Still needs a human on a Mac (human-verification-required):

  1. Deny Automation for System Events and confirm the banner appears at launch.
  2. Press a key button with each grant missing and confirm a toast appears within ~1 s.
  3. Grant the permission and confirm the banner clears.

Closes #196.

Created with Claude Opus 5.5 in Claude Code.

🤖 Generated with Claude Code

jonocodes and others added 2 commits November 18, 2026 17:26
…presses (#196)

Key buttons on macOS go through osascript -> System Events, which needs
Automation (System Events) and Accessibility. Either missing made the
press fail silently; only the daemon log knew.

- Proactive: AEDeterminePermissionToAutomateTarget (ctypes, no prompt)
  raises `automation_system_events_missing` through the #195 health
  channel, with fix steps naming Privacy & Security → Automation and,
  for the packaged app, `tccutil reset AppleEvents com.deckd.daemon`.
- Reactive: osascript stderr is classified by its trailing error number
  ((-1743) Automation, (1002) Accessibility). A shared PermissionLedger
  holds refusals from the focus query, the keysink's startup probe and
  key presses; health_issues() re-checks a held refusal with an empty
  keystroke each poll, so it clears without a restart.
- MacKeySink raises PermissionDenied; the server sends the requesting
  session an `action_error` frame, records outcome="permission_denied"
  in /actions/recent and /metrics, and re-polls health at once so the
  banner arrives with the toast. Macros stop at the refused step.
- Health probes now run off the event loop (asyncio.to_thread).
- Client: ActionErrorToast; banner labels the new `focus` primitive.
- conftest stubs the Automation probe and ledger so tests never depend
  on the host's TCC state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- text paste: when the OS refuses ctrl+v, put the user's clipboard back
  immediately before the refusal propagates (it was left holding the
  widget text).
- PermissionLedger: record_failure / record_success instead of faking
  return codes on the focus path; the keysink's startup probe reuses
  _probe_keystroke and is renamed _check_system_events (it checks both
  grants).
- Docs: CONTEXT gains "Action error"; PLATFORM-PARITY's System Events
  row and ActionRecord's outcome list are current; REFERENCE notes the
  ok + permission_denied pairing and that --no-focus gets no banner.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jonocodes
jonocodes merged commit bfde356 into main Nov 19, 2026
7 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.

macOS: detect missing Automation (System Events) permission + toast on permission-blocked actions

1 participant