macos-computer-use-kit 0.2.0__py3-none-any.whl

macos_computer_use/overlay.py

@@ -0,0 +1,148 @@
+"""Transient visual overlay: a ring (+ optional label) at a screen point.
+
+Absorbed from Grok Bot's cursor/drag overlays: the user should be able to see
+where the agent is acting. The overlay is click-through, floats above normal
+windows, and fades out after ``--duration`` seconds.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+from . import darwin
+
+COLORS = {
+    "cyan": (0.20, 0.80, 1.00),
+    "green": (0.20, 0.85, 0.40),
+    "orange": (1.00, 0.65, 0.10),
+    "red": (1.00, 0.30, 0.30),
+}
+
+
+def _appkit():
+    darwin.require_macos()
+    import objc
+    from AppKit import (
+        NSApplication,
+        NSBackingStoreBuffered,
+        NSBezierPath,
+        NSColor,
+        NSFont,
+        NSInsetRect,
+        NSMakeRect,
+        NSScreen,
+        NSScreenSaverWindowLevel,
+        NSString,
+        NSView,
+        NSWindow,
+        NSWindowStyleMaskBorderless,
+    )
+    from Foundation import NSDate, NSRunLoop
+
+    return objc, dict(
+        NSApplication=NSApplication,
+        NSBackingStoreBuffered=NSBackingStoreBuffered,
+        NSBezierPath=NSBezierPath,
+        NSColor=NSColor,
+        NSFont=NSFont,
+        NSInsetRect=NSInsetRect,
+        NSMakeRect=NSMakeRect,
+        NSScreen=NSScreen,
+        NSScreenSaverWindowLevel=NSScreenSaverWindowLevel,
+        NSString=NSString,
+        NSView=NSView,
+        NSWindow=NSWindow,
+        NSWindowStyleMaskBorderless=NSWindowStyleMaskBorderless,
+        NSDate=NSDate,
+        NSRunLoop=NSRunLoop,
+    )
+
+
+def _ring_view_class():
+    objc, K = _appkit()
+
+    class RingView(K["NSView"]):
+        def initWithFrame_(self, frame):
+            self = objc.super(RingView, self).initWithFrame_(frame)
+            if self is None:
+                return None
+            self._label = ""
+            self._rgb = COLORS["cyan"]
+            return self
+
+        def setLabel_(self, label):
+            self._label = label
+
+        def setRGB_(self, rgb):
+            self._rgb = rgb
+
+        def drawRect_(self, rect):
+            r, g, b = self._rgb
+            K["NSColor"].colorWithCalibratedRed_green_blue_alpha_(r, g, b, 0.95).set()
+            ring = K["NSBezierPath"].bezierPathWithOvalInRect_(K["NSInsetRect"](self.bounds(), 8, 8))
+            ring.setLineWidth_(5.0)
+            ring.stroke()
+            K["NSColor"].colorWithCalibratedRed_green_blue_alpha_(r, g, b, 0.9).set()
+            dot = K["NSBezierPath"].bezierPathWithOvalInRect_(K["NSInsetRect"](self.bounds(), 30, 30))
+            dot.fill()
+            if self._label:
+                K["NSColor"].whiteColor().set()
+                attrs = {
+                    "NSFont": K["NSFont"].boldSystemFontOfSize_(13),
+                    "NSForegroundColor": K["NSColor"].whiteColor(),
+                    "NSBackgroundColor": K["NSColor"].colorWithCalibratedWhite_alpha_(0.0, 0.65),
+                }
+                K["NSString"].stringWithString_(self._label).drawAtPoint_withAttributes_((4, -6), attrs)
+
+    return RingView
+
+
+def cocoa_point(ax_x: float, ax_y: float) -> tuple[float, float]:
+    """Convert an AX top-left screen point to a Cocoa bottom-left window origin.
+
+    The AX space is anchored at the primary display's top-left, so the primary
+    display's height is the correct mirror axis even on multi-display setups.
+    """
+    _w, height = darwin.primary_screen_point_size()
+    return float(ax_x), float(height - ax_y)
+
+
+def show(x: float, y: float, label: str = "", duration: float = 1.5, color: str = "cyan") -> int:
+    RingView = _ring_view_class()  # noqa: N806
+    _objc, K = _appkit()
+
+    app = K["NSApplication"].sharedApplication()
+    app.setActivationPolicy_(1)  # accessory: no dock icon
+    size = 96
+    cx, cy = cocoa_point(x, y)
+    frame = K["NSMakeRect"](cx - size / 2, cy - size / 2, size, size)
+    win = K["NSWindow"].alloc().initWithContentRect_styleMask_backing_defer_(
+        frame, K["NSWindowStyleMaskBorderless"], K["NSBackingStoreBuffered"], False
+    )
+    win.setOpaque_(False)
+    win.setBackgroundColor_(K["NSColor"].clearColor())
+    win.setLevel_(K["NSScreenSaverWindowLevel"])
+    win.setIgnoresMouseEvents_(True)
+    win.setHasShadow_(False)
+    view = RingView.alloc().initWithFrame_(K["NSMakeRect"](0, 0, size, size))
+    view.setLabel_(label or "")
+    view.setRGB_(COLORS.get(color, COLORS["cyan"]))
+    win.setContentView_(view)
+    win.orderFrontRegardless()
+
+    deadline = time.time() + duration
+    while time.time() < deadline:
+        K["NSRunLoop"].currentRunLoop().runUntilDate_(K["NSDate"].dateWithTimeIntervalSinceNow_(0.05))
+    win.orderOut_(None)
+    return 0
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.cmd == "clear":
+        return 0
+    if args.x is None or args.y is None:
+        print("--x/--y required", file=sys.stderr)
+        return 2
+    return show(args.x, args.y, args.label, args.duration, args.color)

macos_computer_use/paste.py

@@ -0,0 +1,111 @@
+"""Clipboard-safe paste with takeover detection and clipboard restore.
+
+Absorbed from ZCode's ``providedPaste`` pipeline (begin -> markDispatched ->
+awaitRead -> finish) and its error taxonomy:
+
+- ``pasteboard_write_failed``           nothing was sent
+- ``pasteboard_changed_during_paste``   someone else took over the clipboard;
+                                        verify the app did not paste the user's content
+- ``pasteboard_read_timed_out``         the app never consumed the paste
+
+The user's clipboard is saved before writing and restored afterwards, so an
+agent pasting Chinese/CJK text never destroys what the user had copied.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+
+from . import darwin
+
+
+def _pb():
+    _AS, _NSWorkspace, Quartz = darwin._pyobjc()  # noqa: N806
+    from AppKit import NSPasteboard
+
+    try:
+        from AppKit import NSPasteboardTypeString as string_type
+    except ImportError:  # pragma: no cover - legacy pyobjc
+        from AppKit import NSStringPboardType as string_type
+    return Quartz, NSPasteboard.generalPasteboard(), string_type
+
+
+def read_text() -> str:
+    _Quartz, board, string_type = _pb()  # noqa: N806
+    return board.stringForType_(string_type) or ""
+
+
+def write_text(text: str) -> bool:
+    _Quartz, board, string_type = _pb()  # noqa: N806
+    board.clearContents()
+    return bool(board.setString_forType_(text, string_type))
+
+
+def post_paste(pid: int | None, mode: str) -> None:
+    Quartz, _board, _string_type = _pb()  # noqa: N806
+    for is_down in (True, False):
+        ev = Quartz.CGEventCreateKeyboardEvent(None, 9, is_down)  # 9 = V
+        Quartz.CGEventSetFlags(ev, Quartz.kCGEventFlagMaskCommand)
+        if mode == "pid" and pid is not None:
+            Quartz.CGEventPostToPid(pid, ev)
+        else:
+            Quartz.CGEventPost(Quartz.kCGHIDEventTap, ev)
+        time.sleep(0.02)
+
+
+def run(args: argparse.Namespace) -> int:
+    Quartz, board, _string_type = _pb()  # noqa: N806
+    result = {"steps": []}
+
+    previous = read_text()
+    before_count = board.changeCount()
+    result["previous_len"] = len(previous)
+    result["steps"].append("begin")
+
+    if not write_text(args.text):
+        result.update(ok=False, reason="pasteboard_write_failed", action_sent=False)
+        print(json.dumps(result, ensure_ascii=False))
+        return 3
+    after_count = board.changeCount()
+    result["steps"].append("written")
+
+    pid = args.pid
+    if pid is None and args.app:
+        pid = darwin.resolve_pid(args.app)
+    if args.mode == "pid" and pid is None:
+        result.update(ok=False, reason="target_app_not_found", action_sent=False)
+        print(json.dumps(result, ensure_ascii=False))
+        return 4
+    post_paste(pid, args.mode)
+    result["steps"].append(f"dispatched({args.mode})")
+
+    time.sleep(args.wait)
+    taken_over = board.changeCount() != after_count
+    result["clipboard_taken_over"] = taken_over
+    result["action_sent"] = True
+
+    if taken_over:
+        result.update(
+            ok=False,
+            reason="pasteboard_changed_during_paste",
+            hint="someone else wrote the clipboard during the paste; check the app to make sure "
+            "the user's content was not pasted instead",
+            restored=False,
+        )
+    elif args.keep:
+        result.update(ok=True, restored=False)
+    else:
+        if previous:
+            write_text(previous)
+            result["restored"] = True
+        else:
+            board.clearContents()
+            result["restored"] = False
+        result.update(ok=True)
+
+    result["steps"].append("finished")
+    print(json.dumps(result, ensure_ascii=False))
+    return 0 if result.get("ok") else 2

macos_computer_use/shot.py

@@ -0,0 +1,87 @@
+"""Screenshot capture with blank-frame detection.
+
+Absorbed from ZCode's ``screenshot_blank`` / ``screenshot_bounds``: never reason
+on a blank or permission-starved frame; detect it and say so. Agents that skip
+this step hallucinate UI state from black pixels.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+from . import darwin
+
+
+def analyze(path: str) -> dict:
+    from PIL import Image, ImageStat
+
+    img = Image.open(path).convert("L")
+    stat = ImageStat.Stat(img)
+    mean = float(stat.mean[0])
+    std = float(stat.stddev[0])
+    verdict = "ok"
+    hint = ""
+    blank = std < 2.0
+    if blank and mean < 5:
+        verdict = "all_black"
+        hint = "screen recording permission may be missing, or the window is fully occluded"
+    elif blank and mean > 250:
+        verdict = "all_white"
+        hint = "the window may be blank or still loading"
+    elif blank:
+        verdict = "uniform"
+        hint = "no visual detail; check the target window state"
+    return {
+        "path": path,
+        "width": img.width,
+        "height": img.height,
+        "blank": blank,
+        "mean": round(mean, 2),
+        "std": round(std, 2),
+        "verdict": verdict,
+        "hint": hint,
+    }
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.cmd == "check":
+        if not args.file:
+            print(json.dumps({"error": "--file required"}), file=sys.stderr)
+            return 2
+        print(json.dumps(analyze(args.file), ensure_ascii=False))
+        return 0
+
+    if args.cmd == "windows":
+        print(json.dumps({"windows": darwin.all_windows(args.app)}, ensure_ascii=False))
+        return 0
+
+    if not darwin.permissions()["screen_recording"]:
+        print(json.dumps({"error": "screen_recording_not_granted", "hint": darwin.permission_hint("screen_recording")}), file=sys.stderr)
+        return 2
+
+    out = args.out or os.path.join(tempfile.gettempdir(), "macos-cu-shot.png")
+    cmd = ["screencapture", "-x"]
+    if args.window_id:
+        cmd += ["-l", str(args.window_id), "-o"]
+    elif args.region:
+        cmd += ["-R", args.region]
+    elif args.app:
+        wins = [w for w in darwin.all_windows(args.app) if w["layer"] == 0 and w["bounds"][2] > 100]
+        if not wins:
+            print(json.dumps({"error": "no_window_for_app", "app": args.app}, ensure_ascii=False))
+            return 3
+        wins.sort(key=lambda w: w["bounds"][2] * w["bounds"][3], reverse=True)
+        cmd += ["-l", str(wins[0]["id"]), "-o"]
+    cmd.append(out)
+
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0 or not os.path.exists(out):
+        print(json.dumps({"error": "capture_failed", "stderr": proc.stderr[-200:]}, ensure_ascii=False))
+        return 4
+    print(json.dumps(analyze(out), ensure_ascii=False))
+    return 0

macos_computer_use_kit-0.2.0.dist-info/METADATA

@@ -0,0 +1,308 @@
+Metadata-Version: 2.5
+Name: macos-computer-use-kit
+Version: 0.2.0
+Summary: AX-first computer-use toolkit for AI agents on macOS: accessibility-tree targeting, process-scoped input, clipboard-safe paste, action read-back verification, visual feedback, and optional Jev semantic guards.
+Project-URL: Homepage, https://github.com/Sur-Cai/macos-computer-use-kit
+Project-URL: Repository, https://github.com/Sur-Cai/macos-computer-use-kit
+Project-URL: Issues, https://github.com/Sur-Cai/macos-computer-use-kit/issues
+License: MIT License
+        
+        Copyright (c) 2026 Sur-Cai
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: accessibility,agent-tools,ai-agent,automation,computer-use,dsh-plugin,macos,opencode,pi-package
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: MacOS X :: Cocoa
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Requires-Dist: pillow>=10.0
+Requires-Dist: pyobjc-framework-applicationservices>=10.0; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-cocoa>=10.0; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-quartz>=10.0; sys_platform == 'darwin'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# macos-computer-use-kit
+
+**AX-first computer use for AI agents on macOS.** Instead of screenshot → eyeball
+coordinates → click and hope, read the accessibility tree, get each element's
+semantics and exact geometry, act on it, then verify the action actually changed
+the UI.
+
+A small, composable toolkit: accessibility-tree targeting, process- and
+window-scoped input, clipboard-safe pasting, action read-back verification,
+blank-frame detection, visual feedback, and optional Jev (TypeSafe System One)
+semantic guards.
+
+Works with any agent that can run a shell command, and ships first-class
+packages for [pi](#pi) and [DeepSeek Harness](#deepseek-harness-dsh).
+
+## Why
+
+These mechanisms were distilled from three mature implementations rather than
+invented from scratch:
+
+| Source | Mechanism absorbed |
+| --- | --- |
+| Codex CUA (`@oai/cua` / Sky service) | AX state + element index, `setValue`, batch actions, event delivery via `CGEventPostToPid` |
+| ZCode Computer Use | `*_to_window` window-scoped input, `target_changed` validation, clipboard-safe paste pipeline, `screenshot_blank` |
+| Grok Bot (`CUGrokBotService`) | snapshots with stable element ids + text budget + drill-down, action read-back, coordinate fallback on failure |
+
+## Install
+
+macOS 12+, Python 3.10+.
+
+```bash
+pip install macos-computer-use-kit        # or: pipx install macos-computer-use-kit
+macos-cu doctor                           # check permissions, displays, dependencies
+
+# from a checkout (editable install + agent skill)
+git clone https://github.com/Sur-Cai/macos-computer-use-kit && cd macos-computer-use-kit
+./install.sh
+```
+
+Grant both permissions to the process that runs the agent (your terminal, or the
+agent app). `macos-cu doctor` reports what is missing and where to enable it:
+
+- **Accessibility** — AX reads, `AXPress`, `setValue`, posted events
+- **Screen Recording** — `shot` (without it every capture is black)
+
+## Quickstart
+
+```bash
+# semantic targeting: exact geometry, zero visual reasoning
+macos-cu ax find --app com.apple.finder --role AXButton --title Size
+macos-cu ax tree --app com.apple.finder --depth 16 --max 200
+
+# token-efficient snapshot with stable ids, trimmed to a budget
+macos-cu ax snapshot --app com.apple.finder --budget 1200 --file /tmp/ax.json
+macos-cu ax resolve  --file /tmp/ax.json --id 0.1.0.6.0.0.0.0.5.8
+
+# native AX action + read-back verification
+macos-cu ax press --app com.apple.finder --role AXButton --title Size
+# {"verified":true,"state_changed":true,...}
+
+# window-scoped input: the user's cursor never moves, target is validated
+macos-cu input windows --app "Google Chrome"
+macos-cu input click --window-id 12345 --x 171 --y 28 --show
+macos-cu input click --window-id 12345 --x 171 --y 28 --expect "37040:12345:642:244:824:640"
+# mismatch -> {"ok":false,"reason":"target_changed"} and exit code 5
+
+# clipboard-safe paste (saves and restores the user's clipboard)
+macos-cu paste --app com.google.Chrome --text "你好" --mode pid
+
+# screenshot with blank-frame detection
+macos-cu shot capture --app "Google Chrome" --out /tmp/shot.png
+macos-cu shot check --file /tmp/shot.png
+```
+
+## CLI
+
+One binary, JSON output, stable exit codes (`0` ok, `2` usage/permission,
+`3` not found, `4` capture failed, `5` target changed).
+
+| Group | Commands |
+| --- | --- |
+| `macos-cu ax` | `tree`, `find`, `click-info`, `snapshot`, `resolve`, `press`, `setvalue` |
+| `macos-cu input` | `windows`, `cursor`, `pid`, `click`, `key`, `scroll`, `move` |
+| `macos-cu paste` | clipboard-safe paste (`--mode pid\|hid`, `--keep`) |
+| `macos-cu shot` | `capture`, `check`, `windows` |
+| `macos-cu overlay` | `show`, `clear` |
+| `macos-cu jev` | `guard`, `select` (optional, JSON on stdin) |
+| `macos-cu doctor` | permissions, displays, dependencies, Jev setup |
+
+### Coordinate spaces
+
+| Space | Source | Used by |
+| --- | --- | --- |
+| `screen[x, y]` | AX/CoreGraphics points, origin at the primary display's top-left | `input --x --y`, `overlay` |
+| window-relative | element point − window origin | `input click --window-id N --x --y` |
+| `shot[x, y]` | `center_screen × --shot-scale` | only for harnesses whose screenshots are scaled differently from screen points; there is deliberately no default |
+
+Secondary displays placed left of or above the primary produce **negative**
+coordinates. That is normal. `macos-cu doctor` prints the layout.
+
+## Agent integrations
+
+| Harness | What you get | Install |
+| --- | --- | --- |
+| any agent with a shell | the full CLI | `pip install macos-computer-use-kit` |
+| [opencode](https://opencode.ai) | skill `macos-computer-use` (auto-discovered) | `./install.sh` |
+| [pi](https://pi.dev) | skill + 9 native tools | `pi install npm:pi-macos-computer-use` |
+| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | plugin bundle, 5 tools | `dsh plugin --profile <name> add dsh-macos-computer-use` |
+
+<a name="pi"></a>
+### pi package
+
+`packages/pi` — `pi-macos-computer-use` (npm, `pi-package` keyword). Registers
+`macos_cu_doctor`, `macos_ax_find`, `macos_ax_press`, `macos_input_windows`,
+`macos_input_click`, `macos_input_key`, `macos_paste`, `macos_shot`,
+`macos_jev_guard`. Every tool shells out with an argv array (`shell: false`), so
+model-supplied text can never reach a shell.
+
+```bash
+pi install npm:pi-macos-computer-use
+pi -e ./packages/pi        # try it for one run without installing
+```
+
+App launchers do not inherit your interactive shell's `PATH`. If the CLI is
+installed but pi cannot find it, set `MACOS_CU_BIN=/abs/path/to/macos-cu` and
+restart pi (the dsh plugin honours the same variable).
+
+<a name="deepseek-harness-dsh"></a>
+### DeepSeek Harness plugin
+
+`packages/dsh` — `dsh-macos-computer-use`, a Cordis bundle
+(`dsh.bundle.patch` → `cordis.patch.yml`). Registers `macos_cu_doctor`,
+`macos_ax_find`, `macos_ax_press`, `macos_input_click`, `macos_shot`.
+
+```bash
+dsh plugin --profile demo add dsh-macos-computer-use
+dsh --profile demo --dump-config    # verify the layer before booting
+```
+
+It deliberately does **not** claim the exclusive `ctx.computerUse` provider slot:
+it adds tools rather than owning desktop operations, so it cannot block the
+in-box Cua Driver provider. See `packages/dsh/README.md`.
+
+### opencode skill
+
+`./install.sh` installs `skill/SKILL.md` to
+`~/.config/opencode/skills/macos-computer-use/`, where opencode discovers it
+automatically.
+
+## The four capabilities that matter
+
+**1. Window-scoped input with target validation.** Events are posted straight to
+the target process (`CGEventPostToPid`), so the physical cursor never moves and
+the user can keep working. `--expect pid:wid:x:y:w:h` refuses to act when the
+window moved or lost focus since you looked at it.
+
+**2. Native AX actions with read-back verification.** `press`/`setvalue` compare
+the window's visible-text fingerprint and focused element before and after, and
+report `verified` separately from `action_sent`. When AX cannot act (custom-drawn
+UI), the result carries a `hint` telling you to fall back to a coordinate click
+or a clipboard paste — you find out from evidence, not from guessing.
+
+**3. Clipboard safety.** The user's clipboard is saved before and restored after.
+Takeover and non-consumption are reported explicitly, so pasting CJK text never
+silently destroys what the user had copied.
+
+**4. Never reason on a blank frame.** `shot` classifies captures as
+`ok` / `all_black` / `all_white` / `uniform` with a hint, so a missing permission
+or an occluded window is reported instead of hallucinated UI state.
+
+## Design principles
+
+1. **AX-first.** Semantic + exact geometry beats visual inference. Screenshots
+   verify; they do not target.
+2. **`action_sent` ≠ `verified`.** Keep "we emitted the event" and "the UI
+   changed" as separate facts.
+3. **The clipboard is a shared resource.** Save, detect interference, restore.
+4. **Targets must be explicit and checkable.** Window input carries a signature;
+   a mismatch is `target_changed`, not a misclick.
+5. **Small models judge, code decides.** Jev returns calibrated probabilities;
+   thresholds and side effects stay in code. Cost ladder: deterministic code
+   (µs) < Jev (~1 s) < visual reasoning (seconds to tens of seconds).
+6. **Make it visible.** Action points draw a ring, so the user is never watching
+   a black box.
+
+## Jev semantic guards (optional)
+
+The only part that needs a key. Everything else works without it.
+
+```bash
+echo '{"task":"send the report to Alice",
+       "expected":{"recipient":"Alice","message":"Q3 numbers"},
+       "observed":{"chat_title":"Bob","input_text":"Q3 numbers"}}' | macos-cu jev guard
+# {"answers":{"right_target":0.02,"input_ok":0.98,"blocker":"wrong_target"},
+#  "decision":"switch_target"}
+```
+
+One request fans out independent judgments and **code** applies the policy:
+proceed only when `blocker=none` and both probabilities clear the threshold; the
+model may only suggest the two safe recoveries (`switch_target`, `retype_input`);
+anything else asks the user. `macos-cu jev select` picks one candidate element
+with a `none` escape hatch and a confidence gate.
+
+Key: `TYPESAFE_API_KEY` or `~/.config/typesafe/api_key`
+(<https://console.typesafe.ai/keys>). Pin `TYPESAFE_MODEL` for automation;
+`jev-latest` is the friendly default. Question-design guidance lives in
+[`skill/reference/jev-best-practices.md`](skill/reference/jev-best-practices.md).
+
+## Known limitations
+
+- macOS only (AX, CGEvent, ScreenCaptureKit are macOS APIs).
+- Custom-drawn UIs (some Electron apps, games, chat apps) expose shallow or
+  uncooperative AX trees. Fall back to screenshots **after** read-back fails,
+  not before.
+- Process-targeted key events are accepted by most apps but not all: browsers
+  usually accept background keystrokes; some chat apps require the app to be
+  frontmost for typing and pasting.
+- AX coordinate scale is display-dependent. `center_shot` is opt-in via
+  `--shot-scale` for exactly this reason.
+- The user may be using the machine at the same time. Concurrent automation is
+  risky; one extra verification before an irreversible action is cheap.
+
+## Repository layout
+
+```
+src/macos_computer_use/   the CLI implementation (pip-installable)
+tools/*.py                compatibility shims -> the same modules
+skill/                    agent skill (SKILL.md + Jev reference)
+packages/pi/              pi package (skill + native tools)
+packages/dsh/             DeepSeek Harness plugin bundle
+install.sh                local installer (venv + CLI + skill + Jev key)
+tests/                    unit tests for the safety-relevant logic
+```
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the
+conventions (JSON on stdout, stable exit codes, no machine-specific defaults).
+Release steps and catalog-listing criteria live in
+[PUBLISHING.md](PUBLISHING.md); notable changes are in
+[CHANGELOG.md](CHANGELOG.md).
+
+## 中文说明
+
+给 AI agent 用的 macOS 电脑控制工具箱：**AX 语义定位**（不靠截图目测坐标）、
+进程/窗口级输入（物理光标不动）、剪贴板安全粘贴、动作回读校验、空白帧检测、
+可视反馈，以及可选的 Jev 语义护栏。
+
+```bash
+pip install macos-computer-use-kit
+macos-cu doctor          # 检查辅助功能 / 屏幕录制权限、显示器、依赖、Jev
+```
+
+Agent 集成：`./install.sh`（opencode skill）、`pi install npm:pi-macos-computer-use`（pi）、
+`dsh plugin --profile <名> add dsh-macos-computer-use`（DeepSeek Harness）。
+完整流程与避坑见 [`skill/SKILL.md`](skill/SKILL.md)。
+
+## License
+
+MIT

macos_computer_use_kit-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+macos_computer_use/__init__.py,sha256=pnsVo5RePGCNIf-Bmem94LbdCu8Tyck06Eej8GtBAjQ,271
+macos_computer_use/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+macos_computer_use/ax.py,sha256=2VVlCP4huDEGS6N3TNS_zNwK4ihtEO24mHC0jKPgK1s,12505
+macos_computer_use/cli.py,sha256=1j8Bx2MGb9ATlYJyMJXtZs-gFcIcTef1nelhW-NagH8,8529
+macos_computer_use/darwin.py,sha256=wtJJ8cTocszMn8npCA-5kmx1F6VsLhAkarBuDe39Pko,8657
+macos_computer_use/input_events.py,sha256=le2e3mQ61VKrCkZbEu58EqpS7Q9gD_IDRjczWxT7j_c,6313
+macos_computer_use/jev.py,sha256=KN5KcHpgG0Nmy-SqwLiRZ-3i8TDICvbuqxeqDabEvO0,8477
+macos_computer_use/overlay.py,sha256=YE80fSwHKUc0PGpzmmP9-y7MyWDPaJ5K0g_trU5yFXc,4868
+macos_computer_use/paste.py,sha256=U-KIZ4YCWOcnFsVWXLtUec9j1zdYjww40lnqSu4zZuE,3713
+macos_computer_use/shot.py,sha256=PNFv0ZqEOUIjXWZ7SBRbhbkPzwGV3TdVTzBHs85Og8A,2868
+macos_computer_use_kit-0.2.0.dist-info/METADATA,sha256=MuhWftOqyW7hHHqwErPqoiZwHNf9u6h9PRLMjEuFKWo,14349
+macos_computer_use_kit-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+macos_computer_use_kit-0.2.0.dist-info/entry_points.txt,sha256=t1fChWY0jYxD-O3-VeYHFfoSrliWBiBM-0iIGzdb5jY,57
+macos_computer_use_kit-0.2.0.dist-info/licenses/LICENSE,sha256=8iFQQD9uGhSSaaKuof5c1QiBoaktQ2r8llKpesYrwag,1064
+macos_computer_use_kit-0.2.0.dist-info/RECORD,,

macos_computer_use_kit-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

macos_computer_use_kit-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+macos-cu = macos_computer_use.cli:main