[earakely-scale]

Two more computer-use drivers for macOS computers, agent-desktop and macos-harness, beside cua-driver. They need macOS permissions granted to a program that isn't an app bundle, and computer/v1 without cua-driver, so this PR adds both of those.

What's in it

Permissions for an executable (env/envs/computer/utils/install.py, computers/vm_bundle/macos/lib.sh, macos_vm_bundle.py)

• A macOS layer's grants can name an executable under its prefix as well as an app bundle. grant_executable writes TCC rows for that path (client type 1), bound to the file's code signature. It also records the screen-capture approval under the path, which is how macOS keys it for a bare executable.
• Each macOS layer's venv is now a --copies venv made from the pinned Python's own folder, so the layer has an interpreter of its own. Its services start agentenv-service on that interpreter, and macOS charges what a process starts to the program launchd started. So a grant to venv/bin/python covers the layer's driver and every program it runs, and no other layer.

MacOSDriver (agentenv_protocol.computer._macos, with the protocol's new macos extra)

• computer/v1 on macOS, including the pointer and keyboard groups. ScreenCaptureKit captures the display, and Quartz events send input from the driver's own process.
• Typing uses a US keyboard's key codes, so apps see real key events. Characters off that layout are sent as the characters themselves.
• Modifiers go down and up around whatever they modify, Shift with any shifted character, and keys held with key_down ride on every later event.
• Events are paced so apps see them all: a click is held and settles, wheel notches are spaced, and a pointer move waits until macOS reports the pointer there before anything presses at it.
• computer-ready reports any of Accessibility, Post Event and Screen Recording that macOS hasn't granted.

Driver settings (computer/driver.py, _declare.py, env/envs/computer/utils/params.py)

• A driver can declare a Settings subclass of ComputerSettings. Its declaration carries the schema, and core checks a deploy's driver_settings against it. This mirrors what apps already have.

The drivers (drivers/envs/agent-desktop/, drivers/envs/macos-harness/)

• agent-desktop 1.2.0: agents get what its own MCP server, agent-desktop mcp, serves, pinned in mcp.json the way cua-driver's tools are pinned. That's its instructions and its 67 desktop_* tools, each forwarded to a server of its own. Its headed setting starts the server with --headed. computer-ready checks both executables' sha256, the tools the server lists, and the permissions.
• macos-harness 0.2.1: it ships only a command line, so agents get one tool, macos_harness. It runs the harness on a list of command lines in order and stops at the first that fails, with no shell. A line that doesn't start with one of the harness's commands runs nothing. Its skill, pinned in skill.md, is the instructions. A read's screenshot comes back as an image. The harness gets none of the driver's environment, and its telemetry is off.

Lume: a builder whose shutdown hangs (providers/sandbox_providers/lume/provider.py)

• When a builder hasn't stopped within SHUTDOWN_WAIT_S (two minutes), it's synced again, and its guest's log is saved and warned of: the shutdown lines of the last 15 minutes and the last 2 minutes in full. Then it's stopped from outside and kept, and the compose's probe judges it as usual. Before, the compose failed after ten minutes and the evidence was lost.

Also

• A recording test that assumed 30 fake frames are made within half a second now waits for the source. It was flaky under load.

Why this shape

• Grants by executable path. These two tools are a plain binary and a Python package, not app bundles. A copied interpreter per layer gives each driver its own identity without an app wrapper per arm.
• Each arm reaches the agent as its vendor ships it. agent-desktop has had its own MCP server since this release, so it's forwarded the way cua-driver's is. macos-harness is a command line whose skill chains actions in one call, so it's one tool that takes a list of command lines.
• One shared computer/v1. Both drivers serve the probe, recordings and readiness from the same module, so the arms differ only in their own tools.

Tested

• Unit: the touched protocol, core, driver and bundle suites pass on an EC2 Mac.
• TCC on a macOS 26.5.2 VM, in a clone of a composed computer:
  • a granted --copies interpreter gets all three permissions as a LaunchAgent;
  • an ungranted program it starts inherits them;
  • the pinned Python and other copies are denied;
  • a granted copy started by an ungranted one is denied;
  • the grant holds after a reboot;
  • exec'ing on the same copy keeps the grant.
• ScreenCaptureKit capture: 15–50 ms a frame from the granted copy.
• Composed and fully probed on EC2 Macs (gate 3): both computers pass all 55 checks.
  • macos-harness passed on its first compose.
  • agent-desktop's probes found three timing problems in MacOSDriver, each fixed and re-probed: wheel notches posted back to back reached the app as fewer (P7), a right click was sometimes lost (P4), and a press right after a move landed where the pointer had been. It now passes all 55.
• Bench trials: both drivers run the macOS Cua Driver Bench's trials end to end with only their own tools (the bench hides the computer_* tools from the agent).
• Two cua_driver_test.py tests fail when the unit suite runs on a Mac host instead of Linux. They fail on main too, so they're not from this PR.

Linear: FD-5213 (the other arms on macOS), FD-5257 (the builder that didn't shut down).

🤖 Generated with Claude Code

Confidence Score: 4/5

The PR still needs the remaining child-process cleanup from the previous finding before merging.

Findings

1.  Cancelled commands keep running ▶

Fix with agent prompt

### Issue 1
src/agent_env/drivers/envs/macos-harness/driver.py:112-116
`_run` kills the harness on `TimeoutError`, but not when the tool call is cancelled. A cancelled command can keep clicking or typing after the caller has stopped waiting. Stop and wait for the child in a cancellation-safe cleanup path.

The same cleanup gap exists in `_agent_desktop`: its skill timeout raises without killing the child.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds agent-desktop and macos-harness drivers for macOS.

• Each macOS layer can grant permissions to its own executable.
• MacOSDriver captures screens and sends computer input on macOS.
• Drivers can declare settings that deploys can check.
• Agents can use agent-desktop’s pinned macOS tools through a computer driver.
• Agents can run macos-harness commands through one computer tool.
• Lume keeps builders whose shutdown takes longer than two minutes.
• The recording test waits for its frames before checking the stream.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Agent --> Desktop["agent-desktop tools"]
    Agent --> Harness["macos_harness tool"]
    Desktop --> MCP["Vendor MCP server"]
    Harness --> CLI["Pinned harness"]
    Computer["computer_* tools"] --> MacOSDriver
    MacOSDriver --> Capture["ScreenCaptureKit"]
    MacOSDriver --> Input["Quartz input"]

Loading

_{Reviews (7) · Last reviewed commit: "fix(drivers): macos-harness's instructio..." · Reviewed by Greptile}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/​macos-harness@​0.2.1
	pypi/​pyobjc-framework-quartz@​13.0
	pypi/​pyobjc-framework-screencapturekit@​13.0

View full report

[greptile-apps]

Cancelled commands keep running

_run kills the harness on TimeoutError, but not when the tool call is cancelled. A cancelled command can keep clicking or typing after the caller has stopped waiting. Stop and wait for the child in a cancellation-safe cleanup path.

The same cleanup gap exists in _agent_desktop: its skill timeout raises without killing the child.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agent_env/drivers/envs/macos-harness/driver.py
Line: 110-115

Comment:
**Cancelled commands keep running**

`_run` kills the harness on `TimeoutError`, but not when the tool call is cancelled. A cancelled command can keep clicking or typing after the caller has stopped waiting. Stop and wait for the child in a cancellation-safe cleanup path.

The same cleanup gap exists in `_agent_desktop`: its skill timeout raises without killing the child.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[earakely-scale]

Fixed in e17a809: _run now stops the harness process (_stopped) when its call times out or is cancelled, so a cancelled macos_harness call doesn't leave the command running. test_a_cancelled_call_stops_the_command_it_was_running checks the child is gone after the cancel.