wrangle 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c71a3ad462a532ec7f6ddea4621ff5620bfde1085cbdbcb5ec0f04995b2707e3
-  data.tar.gz: de242cf8fa5fb7b3c21c03af57d8f8287db282c487fabc20b61f52459756d113
+  metadata.gz: b938bca1479790bd7cd763b621d7075e12f7b0021f4552b8a5c78a3567fbb55a
+  data.tar.gz: 34f213f2393cec5fc75443e65ff1e2eb7bef998998a193cce2fbeb809b7e5ea1
 SHA512:
-  metadata.gz: f295f56bb4e7553dcac794b08ef3d63295f57a2f18922a6fc1d7142dfde7ece183f0971340db080d7a87ce55fb671ef8c431a8e57cd0fd930d0c710a0c051c5f
-  data.tar.gz: e4d1eaffa60d2360f513aaf20f2a4a97255bc387e24ff3e1e563a1d2c189912c37eba1fb022e25dd4931540a37b8f6f9a74c5fdd6d96361f1d8ce9700b5b145c
+  metadata.gz: 6963739192d1de1c1efc3b7399ceaab2b5072a7c24f08d045c6c8c0e9c0a17219aede195d266f787cd4e1202075b21a78b123cd7bfeab4ca9795c48a0a3f6c6d
+  data.tar.gz: a9f666405cd6db619f8f0c3126b441c70de381e71356ddf8a21b97aace0bb58115f57b70027daf4716aa3ea6b3a0196940320701e98a2db902d1ee9c558ab15d

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.2.0] - 2026-09-30
+
+- Native macOS desktop engine: `wrangle task --app APP --goal GOAL` runs a bounded
+  observe → decide → preview → execute → verify loop in one exact application window (Jev by
+  default, at most 8 actions), and `attach`/`observe`/`drill`/`preview`/`execute`/`continue`
+  drive the same loop interactively through a persistent session server.
+- One exact window, never more: the CoreGraphics window and process birth-time identity are
+  re-verified before every snapshot and dispatch. A replaced process, moved window, or ambiguous
+  target fails closed instead of acting. Policy denies credential handoffs and window-control
+  actions outright; consequential actions need a separate `--approve` approval.
+- At-most-once dispatch: a durable marker crosses the dispatch gap, so an interrupted action is
+  reported `delivery_unknown` and never retried. Target-specific effect verification reports
+  `verified`, `unchanged`, or `unverified` instead of trusting that the screen changed.
+- `wrangle qualify --provider NAME` runs the recorded conformance suite and emits an owner-only
+  receipt; only a qualified provider may dispatch, and replay providers are bound to their trace
+  digest. Qualification expires after 7 days.
+- Read-only Tart guest driver: `windows --vm VM --app APP` and `tart-observe` inspect one guest
+  application window, bound to the VM's boot generation, with no mutation path.
+- Project-local Pi tool (`.pi/extensions/computer.ts`): a single-call `computer` tool that owns
+  the whole loop and releases the window automatically.
+- Fixed a dispatch-marker leak where a pre-delivery driver refusal bricked the scope with a
+  phantom unresolved dispatch; it now finishes the marker and reports `not_delivered` without
+  poisoning the session.
+
 ## [0.1.0] - 2026-09-18
 
 - `wrangle run --goal "..." --execute`: a decision loop driven by Jev, a typed-choice model that

data/README.md

@@ -3,10 +3,11 @@
 [![CI](https://github.com/ericboehs/wrangle/actions/workflows/ci.yml/badge.svg)](https://github.com/ericboehs/wrangle/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/wrangle.svg)](https://rubygems.org/gems/wrangle)
 
-**Hand one Safari window to a program, and no more than that.**
+**Scoped computer use for macOS — hand one Safari window or one app window to a program, and no more than that.**
 
-Wrangle drives an ordinary Safari window through Apple Events. There is no automation session, no
-extension, and no native helper — so the window stays a real one you can see, keep, and take back at
+Wrangle drives an ordinary Safari window through Apple Events, or one exact macOS application window
+through a shipped native helper over the accessibility stack. Either way there is no session beyond
+the window you hand over — so the window stays a real one you can see, keep, and take back at
 any moment. It is pure Ruby with **no runtime dependencies**: everything it needs ships with Ruby and
 macOS.
 
@@ -15,6 +16,13 @@ with a banner across the top, none of your cookies, and none of your sessions. T
 for testing a site. It is the wrong tool for doing something *in* a browser you are already logged
 into. Wrangle is for the second case.
 
+> **Release status:** 0.1 is the stable Safari engine described below. `main` now also carries the
+> macOS desktop engine: scoped AX computer use (`wrangle task`, `attach`, `preview`, `execute`),
+> provider qualification (`wrangle qualify`), and a project-local Pi tool
+> (`.pi/extensions/computer.ts`). Its controlled Finder/Settings/Slack gate passes on the alpha host
+> through the exact-window native driver; see
+> [`docs/evaluations/macos-alpha-acceptance-2026-09-19.md`](docs/evaluations/macos-alpha-acceptance-2026-09-19.md).
+
 ```ruby
 require "wrangle"
 
@@ -163,6 +171,83 @@ one evaluation) and a mutation costs four. The page scripts are shipped once at
 ~12 KB per call, unresolved specifiers are addressed rather than resolved, and nothing reads window
 bounds on the hot path.
 
+## Scoped macOS alpha
+
+The alpha keeps the same observe → propose → execute boundary for one exact application window. A
+shipped Swift helper owns window/process/display discovery, Electron accessibility setup, bounded AX
+observation, and native dispatch. There is no `agent-desktop` runtime prerequisite. Native refs remain
+bound to one snapshot and scope, actions revalidate the exact process/window/AX target, and delivery
+is still verified independently afterward. A locked login session is reported as unavailable rather
+than treated as an empty or broken AX tree.
+
+The primary interface is one natural task. Wrangle selects the only or uniquely focused app window,
+runs at most eight typed decision/action cycles internally, verifies every delivered action, releases
+its lease automatically, and leaves the application window open:
+
+```bash
+wrangle doctor
+wrangle task --app Finder --goal "Open Search in the disposable Finder window"
+```
+
+`windows`, `attach`, `observe`, `drill`, `preview`, `execute`, and `close` remain debug and conformance
+interfaces; an outer agent does not orchestrate them during a normal task.
+
+Desktop tasks use Jev when neither `--provider` nor `WRANGLE_DESKTOP_PROVIDER` is set. An explicitly
+configured provider overrides that default, and Wrangle never falls back between providers. No provider is
+mutation-qualified merely because its API is compatible. Qualification receipts are bound to the canonical
+suite and provider/model, to the exact configured endpoint for Jev, and to the exact trace digest for replay;
+they expire after seven days:
+
+```bash
+wrangle qualify --provider replay --provider-trace trace.jsonl --output qualification.json
+wrangle task --app Finder --goal "Open the fixture" --provider replay \
+  --provider-trace trace.jsonl --provider-qualification qualification.json
+```
+
+A task invocation authorizes only its necessary reversible actions. Internally each action still uses
+a revision-bound one-shot proposal. Consequential actions stop before delivery, and uncertain delivery
+terminates the task without retry. Text must be an exact quoted goal span or named literal;
+credentials are always a handoff. If multiple AX targets expose the same visible role, label, value,
+states, and operation, Wrangle omits that operation from every match rather than resolving the tie
+with an opaque ref, path, or list position.
+
+In a source checkout, the stdlib-only
+[macOS acceptance harness](docs/evaluations/macos-app-compatibility.md) probes exact windows without
+retaining UI content. `script/macos_accept finder --runs 5` checks one profile;
+`script/macos_matrix --tier core --runs 5` checks a compatibility wave. App preparation and bounded
+provider tasks are separate opt-in flags, and the checked-in task profiles permit zero delivered
+actions. `script/tart_vm` creates, preflights, snapshots, starts, stops, and explicitly resets
+disposable Tart acceptance VMs; clone/snapshot refuse replacement and reset requires `--replace`.
+Clone and reset default to the validated `wrangle-provisioned-base-v2`; it, the original
+`wrangle-provisioned-base`, and the Pi-enabled `wrangle-pi-base` are protected from reset replacement.
+The guest preflight rejects a
+running or login-restored Setup Assistant. `start` must pass that check
+before returning a fixture as ready, and `snapshot` preflights and stops its running source before
+preserving it. The experimental read-only guest backend requires both scopes explicitly:
+
+```bash
+wrangle tart-observe --vm wrangle-acceptance --app Finder
+wrangle attach --vm wrangle-acceptance --app Finder --session guest
+```
+
+It verifies the VM boot generation around every guest-helper request and has no mutation or host-pixel
+fallback. Guest sessions expose observe/drill/inspect, identify themselves as read-only, and return a
+`not_delivered/read_only` receipt for every execution attempt. See
+[ADR 0004](docs/adr/0004-tart-guest-driver.md).
+
+Pi discovers [`.pi/extensions/computer.ts`](.pi/extensions/computer.ts) in this checkout. Users can
+ask naturally:
+
+> Check the #notifications channel in Boehs Slack.
+
+The agent calls `computer` once with only the natural goal and application name. Wrangle performs
+window selection, progressive observation, typed decisions, proposals, dispatch, verification, and
+cleanup internally; users and the outer agent never handle window IDs, refs, proposal IDs, revisions,
+or receipt vocabulary. Consequential actions stop before delivery; this first protocol reports the
+pending action but cannot yet resume its bound approval. Every result releases Wrangle's exclusive
+lease and deliberately leaves the user-owned app window open. Policy remains in Wrangle rather than
+the extension.
+
 ## CLI
 
 ```
@@ -459,6 +544,12 @@ property of the transport, not of a stub.
 ```
 COVERAGE=1 rake test                      # per-file lines and branches
 COVERAGE=1 COVERAGE_DETAIL=1 rake test    # and which ones are missing
+script/macos_accept --list                # macOS compatibility profiles, no app access
+script/macos_accept finder --runs 5       # read-only exact-window probes
+script/tart_vm status                     # sanitized disposable-VM lifecycle state
+script/tart_vm preflight                  # reject active/persisted Setup Assistant state
+wrangle tart-observe --vm VM --app APP    # exact read-only guest application observation
+wrangle attach --vm VM --app APP          # read-only guest observe/drill/inspect session
 ```
 
 Coverage is measured with Ruby's own `Coverage` module rather than a gem: adding a dependency to