From 77f84a7ef0f0bec9b169b1e9fb2c165c88a1faa7 Mon Sep 17 00:00:00 2001 From: Ian Gulliver Date: Wed, 21 Oct 2026 07:21:49 -0700 Subject: [PATCH] Audit of 4f88f8a --- docs/agent-corrections.md | 12 ++++++++++++ docs/macos.md | 2 +- docs/operations.md | 4 +--- 3 files changed, 14 insertions(+), 4 deletions(-) create mode 100644 docs/agent-corrections.md diff --git a/docs/agent-corrections.md b/docs/agent-corrections.md new file mode 100644 index 0000000..7cbf036 --- /dev/null +++ b/docs/agent-corrections.md @@ -0,0 +1,12 @@ +# Corrections given to agents + +Keep this file minimal. Include a correction only when both apply: + +- It was given to an agent after the agent took an incorrect path. +- Another agent is likely to take that path again unless the correction is documented. + +Write rules only; omit incident histories and anecdotes. + +## Terminology + +- Use “snapshot” for a point-in-time capture of code and conversation context; “revision” implies source control and changes the meaning. diff --git a/docs/macos.md b/docs/macos.md index 22dd2ba..8ba143c 100644 --- a/docs/macos.md +++ b/docs/macos.md @@ -1,6 +1,6 @@ # byre for macOS -The macOS app under `mac/` is byre's client, a native SwiftUI client of byre's API. This document covers what reading its code won't tell you. +Platform constraints, build requirements and SwiftUI behavior observed live. ## Decision diff --git a/docs/operations.md b/docs/operations.md index 3e85f9d..fa2778a 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -116,14 +116,12 @@ Task agents use the Macs the human has byre's app open on. - **Busy apps.** An app in a menu-tracking loop or otherwise busy answers neither Apple events nor accessibility requests; scripts time out after 10s and accessibility requests after 3s, and the first timeout fails the whole call rather than waiting on every element. - **Display sleep.** While the display sleeps, ScreenCaptureKit lists no displays. Every call holds a `PreventUserIdleDisplaySleep` assertion and, when the display is asleep, declares user activity and waits for ScreenCaptureKit to list it again. A declared activity doesn't reset the keyboard and mouse idle time, so the display sleeps again after powerd's grace period (`com.apple.powermanagement.delayDisplayOff` in `pmset -g assertions`), not after the full display-sleep delay. `pmset -g log` shows each wake as `Display is turned on` beside `byre-hands` assertions. - **Orion.** Orion ignores key events that carry only a Unicode string, so typing posts each ASCII character as its key code. Some apps list `confirm` but ignore it, Orion's address bar among them; send Return instead. `do JavaScript` needs Orion's Develop → "Allow JavaScript from Apple Events". -- **Chrome.** Chrome refuses remote debugging on its default profile, so byre's Chrome is its own profile (`~/Library/Application Support/byre/chrome`), a separate Chrome beside any the human runs, and it keeps its logins: the human signs in there once. Chrome comes from `brew install --cask google-chrome`; macOS's "downloaded from the Internet" prompt on its first launch must be answered Open (or `osascript -e 'tell application "System Events" to tell process "CoreServicesUIAgent" to click button "Open" of window 1'`), and until it is, Chrome runs without opening its debugging port. +- **Chrome.** Chrome refuses remote debugging on its default profile, so byre's Chrome is its own profile (`~/Library/Application Support/byre/chrome`), a separate Chrome beside any the human runs, and it keeps its logins: the human signs in there once. Chrome comes from `brew install --cask google-chrome`; macOS's "downloaded from the Internet" prompt on its first launch must be answered Open (or `osascript -e 'tell application "System Events" to tell process "CoreServicesUIAgent" to click button "Open" of window 1'`), and until it is, Chrome cannot accept debugging commands. - **Chrome's trust boundary.** Other OS accounts on the same Mac are not trusted with byre's logged-in browser. Chrome uses inherited debugging pipes, shared by agents through an owner-only Unix socket; never enable a debugging TCP port or fall back to one. After upgrading from the TCP transport, quit the old byre-profile Chrome once before using the tool; an already-running browser cannot acquire the new pipes. The saved profile and logins stay in place. - **Permissions.** Agents' processes run as byre's descendants, so macOS privacy controls (TCC) hold byre responsible for them: the Screen Recording, Accessibility and Automation grants in System Settings → Privacy & Security are byre's, made by clicking at the Mac's screen, and each app scripted for the first time asks for its own Automation grant. Without Accessibility an untrusted process just sees no windows and no menu bar. Accessibility can list byre switched off; only its switch being on counts. TCC keys grants on the signing identifier and team, and every build is signed with Developer ID, so grants carry over from build to build. On a client Mac the grants belong to byre's app; `NSAppleEventsUsageDescription` in `mac/Info.plist` is what lets macOS ask for the Automation grant. `byre-hands check` prints the grants of the process that runs it; the Server and Settings tabs run it. ## Terminals -Each task has one login shell on a PTY, shared by the Terminal tab and the agents' `terminal_read` and `terminal_type` tools. - - `terminal_type` takes named keys because Claude Code passes tool arguments through as the text the model wrote, so an escape like `\u0003` in `text` reaches the shell as six characters. - In a new shell it waits for the prompt first: typing earlier would reach the PTY while it still echoes in cooked mode, before zsh's line editor takes over, so the text would show twice. - It types one byte per write: a program in raw mode that stops reading blocks a PTY write, and the PTY's file doesn't support deadlines, so this keeps the call within its limits while leaving at most one byte to arrive late.