Bumps every workspace package, `package-lock.json`, and both version
fields in `server.json` from 0.24.0 to 0.25.0.
- `npm version 0.25.0 --workspaces --no-git-tag-version
--workspaces-update=false`
- lockfile regenerated with `npm install --package-lock-only
--ignore-scripts` on Node 24 / npm 11 (version-only diff)
- `npm run check:versions` passes
No docs update needed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01XdSDvFDvuU1iyz7HPjcHMV
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
# Physical iOS device support
Try it now (cabled iPhone, unlocked, Developer Mode on):
```bash
argent run list-devices # copy the 25-char UDID
argent run launch-app --udid <UDID> --bundleId com.apple.Preferences
```
First launch builds and signs the on-device runner: 3 to 5 minutes, keep
the phone unlocked. Every later start: seconds, from cache. No signing
setup needed if an Apple ID is signed into Xcode; the team is detected
from the keychain.
## What this adds
- Physical iPhone support, on by default: a cabled iPhone simply appears
in `list-devices`. iPhone-only: physical iPads are skipped at discovery.
- 15 tools ported to hardware. Flows replay on device.
- Zero-config signing from the keychain; `ARGENT_IOS_TEAM_ID` is an
override, nothing is persisted.
- Self-contained npm install: the runner's Swift sources ship in the
package. New package `@argent/ios-device-runner` (an XCUITest bundle
hosting an HTTP command server on the device), new tool-server backend
under `src/utils/ios-device/`.
- The one always-on cost: `list-devices` on macOS now runs physical
discovery in parallel with the other platform probes, under the existing
8s devicectl timeout; off-macOS it early-returns.
## Suggested review order
Rough estimate: half a day for the full pass.
1. `packages/ios-device-runner/PROTOCOL.md`, then `README.md` (wire
contract and reliability model, ~15 min)
2. `packages/tool-server/src/utils/ios-device/` (devicectl, usbmux,
team-detect, runner-build, runner-commands: the core)
3. `packages/tool-server/src/blueprints/ios-device-runner.ts` (service
lifecycle, crash recovery)
4. Per-tool device arms and the capability gates
(`ios-physical-device-classification.test.ts` is the ratchet)
5. Docs page, the two new skills, the Swift runner sources
## Requirements
1. macOS host with full Xcode (iOS platform installed); uses `xcrun
devicectl` and `xcodebuild`.
2. An Apple ID signed into Xcode; automatic signing mints the runner's
provisioning profile.
3. USB cable only. Wi-Fi is deliberately unsupported: the transport is
usbmux, and a Wi-Fi-only device lists as `paired`, not `connected`.
4. iPhone paired with and trusting the Mac, Developer Mode on, A12/2018
or newer (modern 8+16-hex UDID, the CoreDevice floor). Legacy 40-hex
UDIDs are not classified as iOS.
5. Signing resolves as: `ARGENT_IOS_TEAM_ID` in the tool-server's
environment (explicit override, CI) -> keychain detection (newest
identity first, memoized per server run, never persisted). One
certificate: nothing to do. Several teams: newest wins; the first tool
result names the pick, the runner-ups, and the override. No certificate:
the error walks through Xcode > Settings > Accounts and Manage
Certificates > + > Apple Development, then retry; it never names the env
var, since a team id alone cannot sign. Bundle ids derive per team
(`com.argent.runner.t<teamid>`). `ARGENT_IOS_RUNNER_PROJECT` overrides
the project path for unusual layouts.
Build artifacts cache under `~/.argent/ios-device-runner`, keyed by
runner sources, Xcode/SDK version, and signing. A team with no
registered devices self-heals: the failed generic build retries against
the connected phone, which registers it.
## How it works
1. `xcrun devicectl` (CoreDevice) is the control plane: discovery,
readiness, app lifecycle. Readiness gates on the wired transport, so an
unplugged phone is refused before any build starts.
2. A signed XCUITest runner is built lazily with the resolved team,
started via `xcodebuild test-without-building`, and parks as an HTTP
command server for 24h. On an npm install the Xcode project is the copy
shipped inside the package.
3. The listener binds to the device's loopback interface; the host
reaches it over usbmuxd with a dependency-free `node:net` client.
4. Mutating commands are journaled by `commandId`; a lost reply is
resolved by asking `status` for the journaled fate, never by replay
(at-most-once delivery).
5. Routing hangs off `resolveDevice` UDID-shape classification plus a
per-tool capability allowlist. CLI and MCP layers are untouched; outside
tool-server, docs, and the runner package the diff is failure-code
constants (registry), two agent skills plus rule updates (skills), the
pack step (packages/argent), and the e2e smoke script.
## Supported tools
| Tool | Status | Notes |
| ----------------- | --------- |
------------------------------------------------------------------------------------------------------------------------------------------------------------
|
| launch-app | Supported | Plain `devicectl` launch. System UI
(SpringBoard/Spotlight) registers a session only; no launch attempt.
Carries a note when signing is not resolvable yet. |
| restart-app | Supported | System UI bundle ids rejected before any
device contact. |
| reinstall-app | Supported | Same system UI pre-flight. |
| screenshot | Supported | Served through the runner; device-wide, needs
no registered app. (No host-side devicectl screenshot exists on any
toolchain; that dead route was removed.) |
| describe | Supported | AX tree snapshot via the runner. Snapshots the
session app's process, so another process's dialogs are not in the tree.
A backgrounded session app fails with an actionable error instead of
being silently re-fronted. Focus polling is off for this source; typing
uses a fixed settle. |
| keyboard | Supported | Types into the focused element; typing with
nothing focused is refused with "tap the text field first". `enter` and
`backspace` are the named keys (both exist as software-keyboard
characters; there is no per-keycode HID surface on hardware).
Whitespace-only keys rejected, not silently "typed". |
| gesture-tap | Supported | `clickCount > 1` dispatches as one native
multi-tap gesture, not separate taps. |
| gesture-swipe | Supported | Single-finger drag between two points. |
| gesture-custom | Supported | Two shapes only: press-hold and straight
single-finger drag. Second finger or `Move` waypoints rejected with
authoring guidance, before any runner starts. |
| button | Supported | `home`, `volumeUp`, `volumeDown`, `actionButton`
(volume buttons are simulator-unavailable in the SDK, not
device-unavailable). `power`/`appSwitch` have no public XCUIDevice API
and reject before device contact; a button the model lacks gets a typed
refusal via `hasHardwareButton`. |
| await-ui-element | Supported | Polls the same runner snapshot describe
returns; waits and taps see identical frames. Degrades to `cause:
"unreadable"` with a note on a backgrounded app, never a raw throw. |
| await-screen-idle | Supported | Same describe path; resolves
not-settled instead of throwing, so a follow-up screenshot still runs. |
| run-sequence | Supported | Outer gate only; each step pre-flights its
own capability. |
| open-url | Supported | devicectl launches the receiving app with the
URL as its launch payload. http(s) defaults to Safari; any other scheme
needs the new optional `bundleId` param (hardware cannot resolve a
scheme's handler system-wide). |
| screenshot-diff | Supported | Live captures through the runner
(full-resolution, device-wide, no registered app needed); the diff
itself runs on the host. Baselines are per device model/resolution;
`rotation` is ignored on hardware. |
Flows run through these tools; the device flow tree gets the same
`subtreeText` hoisting as every other platform, so container-scoped
`text` asserts work.
## Not supported (400 at the capability gate)
1. gesture-pinch, gesture-rotate: no two-finger coordinate API on
hardware. Pinch/rotate flow directives also fail upfront with a clear
error.
2. screen-recording-start/stop (video): simulator-only capture pipeline.
3. rotate, paste, shake, settings-permissions: simulator-only backends,
not ported (paste also hits the iOS 16+ cross-app paste permission
prompt).
4. native-devtools, debugger, profiler families: simulator-side
instrumentation (DYLD injection does not exist on hardware).
5. Physical iPads: filtered at discovery for now.
A test ratchet (`ios-physical-device-classification.test.ts`) keeps
`apple.device` declarations in sync with the ported list.
## Core contracts
1. Observation never mutates the screen: a backgrounded session app
makes `describe`/`await-*` fail with an error naming the three ways out
(screenshot, launch-app, or launch-app com.apple.springboard). Mutating
commands do re-front, and their result carries `reactivated: true`.
2. The runner listener is unauthenticated; mitigation is the
loopback-only bind.
3. `list-devices` states: `connected` (cabled now, usable) vs `paired`
(unreachable, never auto-bound). Wired transport alone decides; a
Wi-Fi-migrated CoreDevice tunnel does not count.
4. The multi-team signing pick rides the first affected tool result as a
one-shot note (the pre-existing notes channel). The `list-devices`
result shape is unchanged from main: devices and avds, nothing else.
5. Rejections are typed 400 validation errors end to end, so a batch
flow run skips one failing flow instead of aborting.
Also: the runner is a first-class device-owned service
(`stop-simulator-server` and `stop-all-simulator-servers` reap it,
detached xcodebuild child included; a crashed runner respawns on the
next call). A passcode-locked phone refuses launches; the devicectl
10002 hint also covers a pending system prompt on an unlocked phone.
Build failures surface xcodebuild's own `error:` lines with signing
hints (no registered devices, free-team app-id cap, missing
provisioning, the `errSecInternalComponent` partition-list fix). An app
XCTest reports as `.unknown` (a swipe-killed foreign app) is refused
with launch-app guidance. Status-bar pinning is skipped on hardware;
pixel-settle masks the top band.
## Testing
- Unit coverage, hardware-independent: UDID classification and
capability routing; usbmux framing and transport; devicectl list/hints
parsing incl. the silent iPhone-only filter; keychain detection against
real certificate fixtures; runner build/cache self-heals (poisoned
cache, concurrent checkout, fresh-team retry); crash/journal recovery;
the backgrounded-observation and reactivated contracts; keyboard guards
incl. the not-focused refusal; system-UI pre-flight; per-tool device
arms.
- Manual smoke on a real device: `scripts/e2e-ios-physical-device.mjs`.
## Docs and skills
1. `features/physical-ios-devices.mdx`: the user-facing walkthrough
(zero-config signing with the sign-in fallback, prerequisites,
app-scoped model, troubleshooting).
2. `fundamentals/supported-platforms.mdx`: physical iPhones in the
platform matrix (iPads not supported yet).
3. `reference/tools.mdx` and `reference/configuration.mdx`: list-devices
states and the `ARGENT_IOS_TEAM_ID` override.
4. Two skills ship with the package via `argent init`:
`argent-ios-device-setup` (setup ladder plus a troubleshooting table
keyed to real error texts) and `argent-ios-device-interact` (the
app-scoped hardware contract, supported subset with alternatives,
gesture recipes, pitfalls). The agent rule and sibling skills route to
them.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added experimental USB-connected physical iPhone support.
* Physical iPhones now support discovery, app lifecycle actions, URL
opening, accessibility snapshots, screenshots, taps, swipes, custom
gestures, keyboard input, waits, flows, and screenshot comparisons.
* Added automatic signing-team detection with optional
`ARGENT_IOS_TEAM_ID` configuration.
* Added clear handling for paired or unavailable devices and unsupported
hardware actions.
* **Documentation**
* Added setup, troubleshooting, capability, and physical-device usage
guidance.
* Clarified that physical iPads and several simulator-only tools and
gestures remain unsupported.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Bumps all workspace packages from 0.22.1 to 0.23.0.
- All 16 `packages/*/package.json` bumped via `npm version 0.23.0
--workspaces`
- `package-lock.json` regenerated on Node 24 / npm 11 (`npm install
--package-lock-only --ignore-scripts`); diff is version-only
- `server.json` updated in both places (top-level `version` and
`packages[0].version`)
- `npm run check:versions` passes
No docs update needed — version-only change.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01VGjTuE8XKfrmmhJEjchBFq
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Chores**
- Updated the release version across all packages and the server
manifest from 0.22.1 to 0.23.0.
- Ensures package metadata and server configuration consistently reflect
the new release.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Bumps every workspace package, `package-lock.json`, and both version
fields in `server.json` from 0.22.0 to 0.22.1.
- `npm version 0.22.1 --workspaces --no-git-tag-version
--workspaces-update=false`
- lockfile regenerated on Node 24 / npm 11 (version-only diff, 16 lines
each way)
- `npm run check:versions` passes
No docs update needed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01EjrDqoeJa5X8Ry2ND1P714
Bumps every workspace package, `package-lock.json`, and both
`server.json` version fields from 0.21.0 to 0.22.0 (18 files). Lockfile
regenerated on Node 24 / npm 11 so the diff is version-only; `npm run
check:versions` passes.
Covers everything on main since `v0.21.0`: `paste` tool (#879),
rotation-aware Android capture (#693), 0.25 default screenshot scale
(#878), no-reboot describe on externally booted sims (#583/#877), NDJSON
flow progress (#855), OTLP telemetry (#570), native-devtools
restart_required derivation (#560), Android profiler empty-CPU
explanation (#669), plus test/CI fixes.
Full-surface live QA of this main (tgz vs npm 0.21.0) on iOS, Android,
tvOS, Electron, CLI and Linux/remote found zero regressions. Two release
notes: the published artifact must be built with
`ARGENT_OTEL_INGEST_TOKEN` set (a local tgz without it compiles
`readIngestToken()` to an empty string, making telemetry a silent
no-op), and remember to push the `v0.22.0` git tag so online `init`
skills installs resolve.
No docs update needed: version-only change.
Bumps the monorepo from 0.20.0 to 0.21.0 across the full 18-file set:
- all 16 `packages/*/package.json` (via `npm version --workspaces`)
- `package-lock.json` regenerated with `npm install --package-lock-only
--ignore-scripts` on Node 24 / npm 11 (version-only diff, matching the
lockfile CI job)
- `server.json` — both the top-level `version` and `packages[0].version`
`npm run check:versions` passes: all workspace packages and server.json
are at 0.21.0.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Version-only bump of the workspace to 0.20.0, same shape as #741 (the
0.19.0 bump).
## What changed
- All 16 packages under `packages/*` → `0.20.0`
- `package-lock.json` — regenerated with `npm install
--package-lock-only --ignore-scripts` on Node 24, matching what the
Lockfile job runs. Version-only: 16 insertions, 16 deletions, nothing
else.
- `server.json` — the MCP registry manifest, in **both** places it
carries a version: the top-level `version` and `packages[0].version`. It
lives outside `packages/*`, so a workspace sweep leaves it behind and
the registry then rejects the publish because `packages[].version` names
a version npm has never seen.
## Verification
- `npm run check:versions` → "All workspace packages and server.json are
at 0.20.0."
- `npx prettier --check` clean on every touched file
- No `"0.19.0"` string left anywhere in the repo
No code changes.
Version-only bump of the workspace to 0.19.0, same shape as #603 (the
0.18.1 bump).
## What changed
- All 16 packages under `packages/*` → `0.19.0`
- `package-lock.json` — regenerated with `npm install
--package-lock-only --ignore-scripts` on Node 24, matching what the
Lockfile job runs. Version-only: 16 insertions, 16 deletions, nothing
else.
- `server.json` — the MCP registry manifest, in **both** places it
carries a version: the top-level `version` and `packages[0].version`. It
lives outside `packages/*`, so a workspace sweep leaves it behind and
the registry then rejects the publish because `packages[].version` names
a version npm has never seen.
## Verification
- `npm run check:versions` → "All workspace packages and server.json are
at 0.19.0."
- `npx prettier --check` clean on every touched file
- No `"0.18.1"` string left anywhere in the repo
No code changes.
Patch bump. First release whose npm tarball carries `mcpName` (added in
#598), which unblocks the MCP registry publish (`mcp-publisher publish`
rejects `0.18.0` because its manifest predates the field).
`server.json` is bumped alongside `packages/*` for the first time —
`scripts/check-workspace-versions.mjs` now enforces it (`All workspace
packages and server.json are at 0.18.1` locally).
| Commit | Change |
| --- | --- |
| `eea6c27c` | `style`: fix prettier formatting on main (#604) |
| `7e4ece69` | `chore`: server.json for the official MCP registry (#598)
|
| `fc09612f` | `feat(config)`: `recordings.directory` — configurable
save location for screen recordings (#601) |
| `cccda92d` | `feat(config)`: `ios.additionalDeviceSets` — additive
array of extra CoreSimulator device sets (#542) |
Version-only diff, rebased on main as of #604.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## What
Lockstep-bump all 16 `packages/*` workspace packages (and the matching
`package-lock.json` entries) from `0.16.1` → **0.17.0**.
Diff is exactly 32 version-field swaps across 17 files — no formatting
or
dependency churn.
## Verification
- **Lockfile CI gate reproduced locally on the exact CI toolchain**
(Node
24.14.1 / npm 11.11.0, matching `lockfile.yml`'s `node-version: "24"`):
`npm install --package-lock-only --ignore-scripts` on top of the commit,
then `git diff --exit-code -- package-lock.json` → **clean**. npm's own
regeneration reproduced the hand-edit byte-for-byte, so none of the
`"peer": true` churn that #513/#539 had to keep out reappears here.
- `node scripts/check-workspace-versions.mjs` → `All workspace packages
are
at 0.17.0.`
- Remaining `repo-hygiene.yml` checks pass: no conflict markers, no
focused
tests.
- `prettier --check` on all 17 changed files → `All matched files use
Prettier code style!`
- **Runtime version actually reports 0.17.0**: `getInstalledVersion()`
(`argent-installer/src/utils.ts:384`) and
`getGloballyInstalledVersion()`
(`topology.ts:94`) both read `version` straight out of the resolved
package
root's `package.json` at runtime, so the bump is the whole mechanism —
no
generated constant or second version file to keep in sync. Exercised
that
resolution against the bumped tree: `PACKAGE_ROOT` → `packages/argent`
(`@swmansion/argent`) → `0.17.0`.
- Verified all 16 lockfile hits belong to workspace packages (parsed the
lockfile's `packages{}` and matched every `0.16.1` entry to a
`packages/*` path) — no unrelated dependency happened to sit at 0.16.1.
- No test asserts a release version string; the only `0.1x.x` matches
under
`*.test.ts` are historical references inside comments.
## Note
`packages/argent-private` needs no pin change here. Its release version
is
carried purely as a git tag — the repo has no version field on the
release
line (its only `package.json` is a `private: true` research CLI on an
independent `0.1.0` line) — and `v0.17.0` is now tagged at `2d6c292`,
which
is **already** the commit this superproject pins. `v0.16.0` and
`v0.16.1`
sit on that same commit, so the submodule entry is correct as-is and
stays
out of this diff.
## What
Lockstep-bump all 16 `packages/*` workspace packages (and the matching
`package-lock.json` entries) from `0.16.0` → **0.16.1**.
## Verification
- `node scripts/check-workspace-versions.mjs` → `All workspace packages
are at 0.16.1.`
- Lockfile diff is exactly 16 version-field swaps — no unrelated churn
(the `"peer": true` regeneration noise from a newer npm was again kept
out, same as #513). The one remaining `0.16.0` in the lockfile is the
unrelated `@humanfs/types` dev dependency.
- `packages/argent-private` submodule left pinned at `v0.16.0` — no
`v0.16.1` tag exists there yet.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## What
Lockstep-bump all 16 `packages/*` workspace packages (and the matching
`package-lock.json` entries) from `0.15.0` → **0.16.0**.
## Why
The `packages/argent-private` submodule is already pinned at
**v0.16.0**, while the workspace packages sat at 0.15.0. This aligns the
whole repo on the single 0.16.0 version.
## Verification
- `node scripts/check-workspace-versions.mjs` → `All workspace packages
are at 0.16.0.`
- `git submodule status` → clean (no `+`), pinned at `v0.16.0`.
- Lockfile diff is exactly 17 version-field swaps (no unrelated churn —
a full `npm install --package-lock-only` regeneration was rejected
because it introduced unrelated `"peer": true` churn from a newer npm).
## What
Adds three privacy-safe telemetry events for the Argent Lens
design-review flow, capturing the human-decision funnel that the generic
`tool:*` path can't see (submission is an HTTP POST, and the
`await_user_selection` tool is hidden in `argent lens` CLI sessions):
- **`lens:preview_opened`** — a human loaded the preview UI (`GET
/preview/`), deduped per round.
- **`lens:round_completed`** — the human submitted their picks (once per
round, never on a resubmit).
- **`lens:round_abandoned`** — a staged round was discarded before
submit (window closed, `argent lens` exited mid-review, or the round
superseded).
## Privacy
Payloads carry only aggregate counts, booleans, durations, and the
device `platform` enum — never element names, comment text, variant
code, file paths, or raw device ids. The store emits privacy-safe
aggregate structs that are decoupled from the telemetry package;
structural assignability to the event props is enforced at the `track()`
call site (drift is a compile error).
## Event fields
- **`preview_opened`**: `round, element_count, variant_count,
is_cli_session, platform`
- **`round_completed`**: `round, element_count, variant_count,
annotation_count, element_comment_count, skipped_comment_count,
has_global_comment, is_cli_session, had_parked_await, round_duration_ms,
platform`
- **`round_abandoned`**: `round, element_count, variant_count,
had_parked_await, is_cli_session, platform`
## Testing
- Unit tests for all three events: per-round dedup, exactly-once
completion (no resubmit re-emit), abandoned vs happy-path roll, CLI
up-front open, and content-agnostic privacy assertions.
- Verified end-to-end against a live tool-server: all three events fire
with correct aggregate values and zero content leakage through the real
sanitize pipeline.
---------
Co-authored-by: Ignacy Łątka <latkaignacy@gmail.com>
## What
- Bump the `packages/argent-private` submodule pointer from
`v0.11.0-8-g2953e89` to **v0.15.0** (`41484e4`). The superproject pin
had drifted ~4 releases behind the checked-out submodule.
- Lockstep-bump all `packages/*` workspace packages from `0.14.0` →
**0.15.0** (and the matching `package-lock.json` entries) to line up
with the submodule.
## Why
The submodule and the workspace were out of sync: the working tree had
`argent-private` checked out at v0.15.0 while the superproject still
pinned the v0.11 era, and the JS packages sat at 0.14.0. This adopts
v0.15.0 as the single, consistent version across the repo.
## Verification
- `node scripts/check-workspace-versions.mjs` → `All workspace packages
are at 0.15.0.`
- `git submodule status` → clean (no `+`), pinned at `v0.15.0`.
- Lockfile diff is exactly 15 version-field swaps (no unrelated churn).
Bumps every package under `packages/*` from 0.13.0 → 0.14.0 in lockstep.
- All 14 workspace packages bumped to `0.14.0`.
- `package-lock.json` regenerated to match (also picks up npm's `"peer":
true` normalization).
- `npm run check:versions` passes: *All workspace packages are at
0.14.0.*
Internal deps use `file:../` references, so no dependency version
specifiers needed changing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## What
Adds `argent lens` — open Argent Lens bound to a fresh `claude` session.
## Why
The Lens preview window and the agent communicate through a shared,
process-wide tool-server that carries **no per-agent identity** (only a
coarse telemetry header). So when the user requests changes in the
window, there's no reliable way to route them to the *specific* agent
that opened it.
`argent lens` sidesteps the problem by inverting ownership: the human
launches Lens, and Lens spawns (and therefore owns) exactly one `claude`
terminal. The binding is 1:1 by construction — no identity plumbing
required.
## How it works
1. `argent lens` ensures a tool-server and **begins a CLI Lens
session**, which opens the preview window up front (no
`await_user_selection` needed) and keeps it open across rounds.
2. It spawns a tracked `claude` terminal in the current directory — a
TypeScript port of the macOS applet's `osascript` spawn/track mechanism
— seeded to propose variants without blocking.
3. A watcher polls `GET /preview/outcome`; on each submitted round it
types a one-line feedback summary into that terminal, queuing it to the
agent as its next prompt. Requesting changes therefore "talks back" to
the bound agent instead of closing the window.
macOS only (drives Terminal/iTerm via `osascript`); off-darwin it exits
with a clear message.
## Changes
- **CLI** `lens-terminal.ts` — `osascript` spawn/track + a new
write-into-running-session path (the "outputting" channel; injects input
into the running TUI, which a tty write cannot do).
- **CLI** `lens.ts` — the command + feedback formatter.
- **tool-server** — a `cliSession` flag in the variant store (opens the
window, suppresses auto-close on submit); `POST /preview/cli-session`
and `GET /preview/outcome` routes.
- **UI** — relabels the submit action to "Request changes" while a CLI
session is active.
Behind the existing `argent-lens` feature flag.
## Verification
- Build + typecheck across the workspace; ESLint (`--max-warnings 0`) +
Prettier clean.
- 34 new unit tests; full `@argent/cli` suite **118 passing**,
tool-server variant/preview suites **46 passing**.
- **E2E (observed on this machine):**
- **tool-server HTTP** — `cli-session` toggles `cliSession` true/false;
submitted feedback round-trips through `/preview/outcome`.
- **terminal injection** — spawned a window running `cat`, confirmed
`writeToSession` lands text in the running program's **stdin** (both
iTerm and Terminal), with embedded newlines flattened.
- **full relay** — the real `watchAndRelay` loop against a real
tool-server typed two distinct submission rounds' feedback into a
stand-in agent terminal (dedup on `completedAt` verified).
- `argent lens --help` and the feature-flag gate (exit 1 with guidance,
no spawn).
Note: a real end-to-end with a live `claude` agent was not run (it would
drive a paid interactive session); the agent-facing channel is proven by
injecting into a stand-in process's stdin via the exact same code path.
---------
Co-authored-by: Filip131311 <contact@filipkaminski.com>
Part 1 out of N reworks for Argent Lens
Polish pass on the Argent Lens preview window.
## Changes
- **Native window controls.** `titleBarStyle: "hidden"` (+
`setWindowButtonVisibility`) shows the real macOS traffic lights on the
transparent window instead of the handcrafted close button.
`trafficLightPosition` insets them to share the corner panels' 14px
padding.
- **Comment-mode cursor.** Entering comment mode swaps the crosshair for
a Figma-style speech-bubble cursor over the stream, so "you are placing
a comment" is unmistakable. Defined as a `--cursor-comment` data-URI
token in `theme.css`.
- **Bottom toolbelt.** The "Add comment" button moved out of the
top-right cluster into a new bottom-centre floating toolbelt — the seed
of a Figma-style bottom tool tab. Same button look, placement only.
- **Cards show all variants.** Two fixes so short cards no longer clip a
variant: the left column is no longer height-limited by the bottom-right
footbar (per-column bound), and tighter variant-row padding lets a
2-variant card fit its column.
- **Cards repel / never overlap.** A deterministic per-poll de-overlap
of the spring **home** targets (a stable top-down sweep), not a
per-frame force. The damped springs glide to non-overlapping rests: no
micro-jitter, no rubber-banding, and a card wedged between two settles
instead of wiggling forever.
- **App named "Argent Lens".** The window title was already set, but the
macOS menu bar / Cmd-Tab / Dock showed "Electron" (the unpackaged
`Electron.app` bundle's `CFBundleName`, which `app.setName` can't
override). On macOS the tool-server now launches the window through a
thin **wrapper `.app`** whose `Info.plist` `CFBundleName` is "Argent
Lens" — it symlinks Electron's Frameworks/Resources (no ~270MB copy) and
is launched with `--no-sandbox` (the modified/symlinked bundle no longer
matches the signed Helper apps). Acceptable for this window: it only
loads the tool-server's localhost UI, and the renderer keeps
`contextIsolation` + `sandbox:true`. Falls back to plain Electron on
non-macOS or any failure.
## Verification
Driven live against the iOS simulator via a dev tool-server + the
Electron window over CDP:
- Native traffic lights render on the transparent window; handcrafted
close button removed.
- Comment-mode `.stage img` computed cursor is the speech-bubble
data-URI.
- "Add comment" is in `#float-toolbelt`, horizontally centred at the
window mid-line, 14px above the bottom.
- All demo cards report `bodyScrollHeight === clientHeight` (zero clip);
both variants visible.
- 5- and 9-card layouts: zero overlaps, positions identical across 2s
(no jitter), and pinning a card between two settles with no overlap and
no wiggle.
- Menu bar / Cmd-Tab read "Argent Lens"; `ps` confirms the window
launches via `…/argent-lens-app/Argent Lens.app/Contents/MacOS/Electron
--no-sandbox`.
- `tsc --build`, `eslint`, `prettier --check`, and the preview/variant
test files all pass.
## The bug
A variant proposed for the Favourites header (matched by text
**"Export"**) was marked **off-screen / hidden** in Argent Lens even
though the "Export" button was clearly visible. Found during E2E testing
of the Pokémon app.
Repro proposal:
- `match: {by:"text", value:"Export"}`
- `variant.frame: {x:0, y:0, width:1, height:0.205}`
## Root cause
`vpMatchNode` (the on-screen matcher) seeds the match **anchor** from
the proposal's `variant.frame`, then a **size gate** (`MAX_SIZE_RATIO =
2.5`) rejects candidates whose size differs too much from that seed.
But `variant.frame` is a thumbnail **crop region** — frequently a whole
component — while `match` can anchor on a small **sub-element** inside
it. Here the agent cropped the full-width header band (`{w:1, h:0.205}`)
but anchored on the tiny "Export" button (live frame `{x:0.743, y:0.109,
w:0.181, h:0.037}` from `describe`). The ~5.5× width gap tripped the
gate, which eliminated the **only** on-screen candidate → `vpMatchNode`
returned `null` → reported off-screen.
## Fix
Make the size gate a **preference**, not an eliminator
(`packages/ui/index.html`, `vpMatchNode`): keep the nearest candidate
even when the gate rejects it and fall back to it, so a clearly
on-screen element is never dropped. The gate still disambiguates among
multiple same-text candidates (size-matched wins), and the
locked-identity re-match path is unchanged.
## Verification
Headless-Chrome repro against the real UI, injecting the live Favourites
AX tree + the exact proposal:
- **before:** `onScreen: false` (bug reproduced)
- **after:** `onScreen: true`, matched "Export"
Full UI regression sweep (theme seed, stream-reconnect, off-screen pill,
comment-Escape, reduced-motion) still green.
Follow-up to #271 (Argent Lens).
Three independent reliability fixes for **Argent Lens** (the
`propose_variant` / `await_user_selection` variant-review flow and its
preview window). They touch disjoint files and were validated
separately; combined here into one PR.
---
### 1. Preview window 404s on dot-path installs (nvm/fnm/volta/asdf)
The Lens window showed a raw `NotFoundError` instead of the variant UI
whenever argent was installed under a path containing a dot-segment
(most commonly nvm, `~/.nvm/...`). `GET /preview/` and
`/preview/theme.css` returned 404 while JSON routes worked.
Cause: the express 4 → 5 bump (#354, shipped in v0.12.1). Express 5's
`send@1` defaults to `dotfiles: "ignore"`, which 404s any file path
containing a dot-segment, and the preview routes pass the absolute
install path to `res.sendFile`. Proven in isolation: express 5.2.1
`sendFile` of the file → 404; express 4.22.1 → 200; `sendFile(basename,
{ root: dir })` → 200.
Fix: serve the preview UI via `sendFile(basename, { root: dir })` (a
`serveUiFile` helper) so the request path carries no dot-segment.
Regression test serves the UI from a temp dir whose name starts with
`.`.
> Note: the underlying `send@1` dot-path behaviour is a property of the
express-5 migration, not of Lens — these two routes are simply the only
`sendFile` calls in the tool-server today.
### 2. Variant fails to anchor right after navigation
A `propose_variant` made immediately after navigating to a screen
(exactly the navigate → screenshot → propose workflow) often failed to
anchor: the card floated/hid ("didn't register"), or latched onto a
same-text distractor (e.g. a bottom-bar tab instead of a header).
Cause: `captureElementFrame` describes the device **once** at propose
time, but iOS' accessibility tree is empty for ~1.25 s after a screen
appears and then fills incrementally (nav chrome before screen content)
— measured on a real device.
Fix: `captureElementFrame` now retries across the warm-up window and
**holds out for an exact label/identifier hit** (the intended element),
falling back to a substring match only after the budget.
`findElementMatch` / `matchFrameInTree` rank exact matches above
substring ones. Adds `match-element-frame-cold-describe.test.ts`; two
existing tests updated for the new retry signature.
### 3. Off-screen choices were unreachable
In the preview window, the off-screen reveal prompt (the "Show them"
card and the "N hidden — show" pill) was hidden unless **every on-screen
choice was already staged** (`onScreenStaged`). So a proposal whose
element was off-screen showed a hidden-choice count with no affordance
to surface it.
Fix: show the prompt whenever any element is off-screen (`offScreenCount
> 0 && !revealOffscreen && !submitting`), dropping the `onScreenStaged`
gate.
---
Supersedes #390, #392, #393 (same commits, combined).
Bumps every workspace package under `packages/*` from `0.12.0` →
`0.12.1`, keeping the monorepo's lockstep versioning intact.
## Changes
- `version` bumped to `0.12.1` in all 15 workspace `package.json` files
- `package-lock.json` workspace entries synced to match
## Verification
- `npm run check:versions` → `All workspace packages are at 0.12.1.`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Why
We hit a mismatch between a locally-generated `package-lock.json` and
the one on `main`. `npm ci` validates the lockfile loosely and accepts a
stale lock that a fresh `npm install` would rewrite, so the drift
slipped through. This adds CI to catch that, plus a few related
common-mistake guards.
## What
**`Lockfile` workflow** (Node 20) — runs `npm install
--package-lock-only --ignore-scripts` and fails if `package-lock.json`
changes. This is the gap `npm ci` leaves: it asserts the lock is exactly
what npm produces, not merely "consistent enough".
**`Repo Hygiene` workflow** — three fast static guards:
- **Merge-conflict markers** — fail on any `<<<<<<<` / `=======` /
`>>>>>>>` left in a tracked file.
- **Focused tests** — fail on `describe/it/test/bench.only` in
`*.test.ts(x)` / `*.spec.ts(x)`. Uses a POSIX-ERE word-boundary pattern
so it actually fires under `git grep -E` (a `\b` pattern silently
matches nothing there).
- **Workspace version sync** — fail when `packages/*` versions drift,
via `scripts/check-workspace-versions.mjs` (also `npm run
check:versions`).
To make versions consistent, `@argent/ui` is bumped `0.0.1 → 0.12.0` (it
is `private`, so no publish impact).
## Verification (Node 20 / npm 10.8.2, matching CI)
- Lockfile check: no false positive on `main`; idempotent; catches a
tampered lock.
- Merge-marker & `.only` greps: proven to catch real violations and
reject lookalikes (`await.only`, `audit.only`, `foo.it.only`); clean
across the repo.
- `check-workspace-versions.mjs`: reports all packages at `0.12.0`;
passes `eslint` and `typecheck:scripts`.
- All new/changed files pass `prettier --check`; both workflow YAMLs
parse.
## Note: npm version coupling
The check runs on Node 20 (npm 10.8.2), matching the committed lock's
format. npm 11 (Node 24) regenerates the same lock minus cosmetic
`"peer": true` markers — no resolution change, but a contributor who
regenerates on npm 11 would trip the strict diff. The repo pins no
toolchain today (CI mixes Node 20 and 24). Pinning npm/Node repo-wide
would fully close this; left out of scope here — happy to add it as a
follow-up.
Adds a UI for proposing and choosing between multiple agent-generated
variants on a running app.
**MCP tools** (`packages/tool-server/src/tools/variants/`)
- `propose_variant` — non-blocking; agent stages a variant for an
on-screen element (text/label/identifier/role matcher).
- `await_user_selection` — one blocking call; parks until the human
submits, then returns the picks + free-form annotations + a global
comment.
**Preview UI** (`packages/ui`)
- Floating cards anchored to live element frames via the existing
`describe` tree, with connector lines.
- Comment-mode inspector: hover spotlight (blur+dim everything else),
right-click any element to pin a comment.
- Sticky padded hitbox + trajectory-aware dismissal so focus doesn't
drop on cursor jitter.
- Footbar [Complete] [Clear], confirm modal for destructive actions,
green toast on submit.
- Single source of feel constants in `theme.css`.
**Electron host** (`packages/preview-window`)
- New workspace package. Frameless transparent BrowserWindow at fixed
size; the squeeze open/close is a CSS `transform: scaleY` on `<html>`,
GPU-composited — no OS-level resize.
- Tool-server spawns it on `await_user_selection` park, reuses it across
re-awaits, and asks it to animate-close on submit (1s grace so the toast
is visible).
- Stdio-line IPC (no extra ports). Ephemeral throughout — the renderer
hits the tool-server's already-ephemeral `/preview/*` HTTP.
---------
Co-authored-by: Filip131311 <contact@filipkaminski.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* chore: update .gitignore and remove deprecated scripts, remove artifacts from MCP
* chore: remove unused files and scripts, including .DS_Store and benchmark scripts
* feat: include skiplists
* feat: allow for verbose logging in component tree and element-inspect
* feat: trim the skills related to PR from unneeded information
Move server code to packages/server/, add placeholder packages for
packages/ui and packages/vscode. Add tsconfig.base.json with shared
compiler options and root tsconfig.json with project references.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
filip131311