23 Commits

Author	SHA1	Message	Date
Kacper Kapuściak	e1d7654af5	docs: add a Limits section to the physical iOS devices page (#1050) ... ## Summary - Adds a `## Limits` section to `packages/docs/docs/features/physical-ios-devices.mdx`, matching the shape of the other feature pages. - Moves the unsupported-capability bullets out of "What works" into the new section. - Adds limits that were undocumented: iPhone only, USB cable only, home/volume/action buttons only, Enter and Backspace only. ## Docs This PR is a docs-only change. `npx docusaurus build` and `npm run format` pass. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Clarified limitations when using physical iOS devices. * Documented supported hardware: iPhones are available, while iPads are not currently shown. * Added details about USB-cable-only control, supported home, volume, and action buttons, and available text, Enter, and Backspace keys. * Moved simulator-specific limitations into a dedicated “Limits” section, including unavailable rotation, shake, permission changes, debugging, profiling, inspection, recording, and paste capabilities. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-11 11:33:33 +02:00
Hubert Gancarczyk	e09e200eb5	feat(flows): let a flow run select a booted remote iOS simulator (#1060) ... ## What A booted remote iOS simulator is now a device a flow run can be pointed at - both by auto-detection and by `--platform ios-remote`. ## Why It was invisible to flow device resolution. With a remote simulator booted alongside local ones: ``` $ argent flow run checkout 7 booted devices matched - pass --device or --platform to disambiguate. Available devices: 79EE0744 (ios, Booted), A1E0DF35 (ios, Booted), emulator-5554 (android, device), ... ``` Three local iPhones and four Android emulators, and the remote simulator absent entirely. Narrowing to it did not work either - `--platform ios-remote` was rejected by the parameter's enum. The only way onto a remote simulator was typing the full `remote:<uuid>` id. The cause is one type. `RawDevice.platform` was typed from the tuple of platforms an author can *write* in a flow file, which has no `ios-remote`, so nothing forced the case to be handled and two functions quietly fell through: - `isBooted` hit its `default: return false`, so a remote row never counted as booted. - `deviceEntryId` fell through to `serial`, a field a remote row does not carry (it uses `udid`, prefixed `remote:`). Even once counted, it had no id - and a resolution error printed it as `? (ios-remote, Booted)`, hiding the very id the caller needed. ## How The tuple served two different jobs at once - what an author may write, and what a run may be pointed at - so it is now two: - `LAUNCH_PLATFORMS` - launch-map keys and `when:` guards. Unchanged. - `SELECTABLE_PLATFORMS` - device selection. Adds `ios-remote`. `ios-remote` is selectable but deliberately not writable. A flow says what it drives, not which machine hosts the simulator, so `when: { platform: ios-remote }` stays a parse error. For the same reason `ios` and `ios-remote` do not overlap: `ios` selects local simulators only. The flow file is identical either way, so which host runs it is an explicit choice rather than something that changes with whatever happens to be booted. ## Scope Selection only. A remote flow run is still coordinate-only - selector steps, `await: { idle: true }` and `snapshot: { cropOn }` need a UI tree source that `ios-remote` does not have yet, and `launch:` maps still have no `ios-remote` key. Those are separate changes. ## Verification End-to-end against a booted cloud simulator (`remote:73A22194-…`, iPhone 17 Pro / iOS 26.5) driven through the branch tool-server, with three local simulators and four Android emulators also up: | Run | Result | | --- | --- | | `platform: "ios-remote"` | resolves `remote:73A22194-…`, flow passes | | no platform | 8 booted devices listed, including `remote:73A22194-… (ios-remote, Booted)` - named by its id, not `?` | | `platform: "ios"` | 3 local simulators only, the remote one absent | `npm run build` and the tool-server suite pass. ## Docs `flow-yaml.mdx` and the `argent flow run --help` text both list `ios-remote` and note that `ios` never picks a remote simulator. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added support for selecting remote iOS simulators with `--platform ios-remote`. * Remote simulators are automatically detected when booted and identified by their device ID. * Local `ios` selection continues to target only local simulators. * **Documentation** * Updated command-line help and flow documentation to describe remote iOS simulator support and platform selection behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Hubert Gancarczyk <claude-hubert.gancarczyk@swmansion.com>	2026-09-10 14:31:02 +02:00
Ignacy Łątka	46d968abbf	style(docs): reflow the tool-server env-var table (#1153) ... `prettier --check .` fails on `main`, so every push since #1151 has a red **Format** job. #1151 shortened the `ARGENT_SCREENSHOT_SCALE` description. That cell was the widest in the column, so the whole table was left padded to a width nothing occupies any more. Reflowed it with Prettier; whitespace only. | Before | After | | --- | --- | | `Format` ❌ on `main` (4 consecutive pushes) | `npx prettier --check .` → exit 0 | <details> <summary>Verification</summary> ``` $ npx prettier --check . # the exact CI step Checking formatting... All matched files use Prettier code style! EXIT=0 ``` Re-running `prettier --write` produces no further change (idempotent). `git diff -w` reduces to the separator row alone; no cell content changed. Docs still build and the table still renders: ``` $ npx docusaurus build # packages/docs [SUCCESS] Generated static files in "build". BUILD_EXIT=0 $ # parsed build/docs/reference/configuration/index.html rows=8 (header + 7), 3 cells each, all values intact ``` </details>	2026-09-09 23:02:51 +02:00
Ignacy Łątka	59daf7c67d	fix(screenshot): give ARGENT_SCREENSHOT_SCALE the 0.01 floor its parameter enforces (#1151) ... Fixes #816 **Cause** - `getScreenshotScale()` guarded on `n > 0 && n <= 1`, while the `scale` parameter of the same tool is `min(0.01).max(1.0)`; a value in `(0, 0.01)` was accepted and shrank a capture towards zero pixels, so `screenshot-diff` refused the pair and reported `dimension_mismatch` rather than a configuration problem. An out-of-range value was also swallowed with no warning, so `ARGENT_SCREENSHOT_SCALE=30` silently read as the default. **Fix** - the guard is now `n >= 0.01 && n <= 1`, and a rejected value is reported once per distinct value on stderr, naming the value and the accepted range. **Verified** - the three new floor cases and the warning assertion fail on the unfixed function and pass with it; full `@argent/tool-server` suite green. Docs: `packages/docs/docs/reference/configuration.mdx` - the `ARGENT_SCREENSHOT_SCALE` row said `0` to `1` and a `0.3` default; it now says `0.01` to `1`, default `0.25`, and that an out-of-range value is ignored with a warning. No other reference or feature page mentions the variable. Class check: `getScreenshotScale()` is the only env-to-scale parser in the tool-server (iOS, Android, tvOS and Vega all read it), so there is no sibling site to fix. <details> <summary>Discriminating-test proof and checks</summary> Source fix reverted, test file kept: ``` FAIL test/screenshot-default-scale.test.ts > falls back to 0.25 below the floor for "0.009" expected 0.009 to be 0.25 FAIL test/screenshot-default-scale.test.ts > falls back to 0.25 below the floor for "1e-3" expected 0.001 to be 0.25 FAIL test/screenshot-default-scale.test.ts > falls back to 0.25 below the floor for "0.0001" expected 0.0001 to be 0.25 FAIL test/screenshot-default-scale.test.ts > names the ignored value and the accepted range, once per value expected "warn" to be called 1 times, but got 0 times Test Files 1 failed (1) Tests 4 failed | 9 passed (13) ``` Fix restored: 13 passed. Checks run from the worktree root: - `npx tsc --build` - clean - `npm run typecheck:tests -w @argent/tool-server` - clean - `npm test -w @argent/tool-server` - 368 files, 4837 passed, 1 skipped - `npx prettier --check` on the three changed files - clean `npx eslint` on the changed files could not run locally: the root install skips `packages/docs`, so its `tsconfig.json` fails to resolve `@docusaurus/tsconfig` and the shared project parse errors out. Same reason `npx docusaurus build` was not run for the one-cell docs table edit. </details> 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-09-09 21:42:01 +02:00
Hubert Gancarczyk	0f90d182b2	feat(flows): record a script step by running it (#940) ... #864 (the executor) and #865 (the `script:` step) are merged. This branch now sits directly on `main` as a single commit, so the diff and the commit list are this change alone. A `script:` step could only enter a flow by being typed into the YAML after the recording ended. The authoring skill said so in as many words, and listed it among the legal unrecorded insertions. That made it the one directive exempt from every rule the recorder exists to enforce, and it cost two things: - **The script never ran while the flow was authored.** It first executed during the closing replay, where a failure reads as a flow that was never right rather than a script that needs one more attempt. Worse, the device steps recorded after it were walked against backend state the author had established by hand — so the recording proved nothing about whether the script establishes that same state. - **The author never saw what the script returned.** A later release reads `{{output:user.id}}`; the only way to know that path exists is to have seen the document. This adds one MCP tool, `flow-add-script`, that runs a local `.mjs` and records the step it ran. **No new flow syntax** — the `script:` step is unchanged, and this is a second way for one to enter a flow file. ```text flow-add-script { name: "checkout", project_root: "/Users/dev/shop", path: "../../scripts/seed-order.mjs", timeout: 60000 } ``` ## What it adds - **One shared execution path.** Path resolution, the on-disk casing guard, the executor call and the verdict were private to `flow-run.ts`. They are now `runFlowScriptStep` in `flow-script-step.ts`, with the file-ref helpers in `flow-file-refs.ts`, and `runScriptStep` is that call plus its `ExecState` plumbing. This is the load-bearing change: "the recording runs the script exactly as replay will" is one function, not two code paths that agree today. - **A failure records nothing.** The opposite of `flow-add-step`, deliberately. A failed script did not establish the state the rest of the walkthrough would then be recorded against, so an appended red step costs every step after it, not just itself. The `message` also says whether a child actually *ran* — a path that resolved to no file forked nothing, while a script that threw halfway did not roll back — because the author's next move is a retry or a cleanup and they cannot pick without knowing. - **The returned document, as JSON text.** Text rather than an object because this is the first tool result carrying bytes the server did not author: every result is deep-walked for `__argentClientFile` and `__argentArtifact` directives, which match on shape alone and write or fetch files on the agent's machine. As a string it inherits none of that. Bounded at 64 KiB with `outputTruncated`, for the reason `log` is bounded. - **`{{output:` refused by `parseFlow`.** Surfacing the document invites an author to write a reference that has no meaning yet — it would be printed literally by a step that passes, green and wrong. The scan runs over exactly the field list the output release declares supported, so it is a seam that release converts from reject to resolve rather than scaffolding it deletes. Patterns are excluded: a `{{` in a regular expression is a quantifier the author meant. - **Two boundaries.** A `client`-mode recording is refused — its `.mjs` never left the agent's machine, the same anchor reason `run:`, `snapshot` and uploaded flows are refused. And the tool is `longRunning`, so the MCP adapter's 30s fetch abort cannot retry a call whose whole purpose is a side effect; the comment records what that flag does *not* close, and where the rest belongs. - **`flow-add-step` says when the call already ran.** The `{{output:` refusal is the one refusal this release adds on a path where the tool call has already fired, and its message asks for an edit-and-retry — which repeats the device action. Verified: a `keyboard` step recorded twice left `{{output:code}}{{output:code}}` in the field. That one refusal now carries what already happened. ## Documentation Rule 5 of `argent-create-flow` no longer lists `script:` as a legal unrecorded insertion — leaving it there would tell agents to keep doing the thing this PR removes. `live-authoring.md` gains the recorder contract, the return fields that are not self-evident, and the ordering rule: a setup script is recorded *before* the `restart-app` it prepares state for, because that is where it runs at replay. A leading script does not make the flow a fragment. `qa-flows` and `reliability-and-recovery` follow the count and the wording. ## Verification `npm run build`, `npx eslint . --max-warnings 0`, `npx prettier --check` over tracked files, and `npm run typecheck:tests -w @argent/tool-server` are green. `npm test -w @argent/tool-server`: 358 files, 4657 passed, 1 skipped. Exercised end to end against a live tool server built from this branch, not only in tests — recorded a flow, then replayed the saved YAML through `argent flow run` with no hand editing: ``` flow-add-script → status "pass", durationMs 124 log: "seeding order for the flow\nwarn: using the fake backend\n" outputJson: {"order":{"id":"ord_4417","total":39.5}, "user":{"id":"usr_9","email":"buyer@example.com"}} recorded: 1. script: ../../scripts/seed-order.mjs (timeout 30000ms) ``` ```yaml steps: - script: path: ../../scripts/seed-order.mjs timeout: 30000 - echo: order seeded; expect Home ``` ``` Flow "checkout" ✓ 1 script ../../scripts/seed-order.mjs │ seeding order for the flow │ warn: using the fake backend › order seeded; expect Home PASS — 1 passed, 0 failed, 0 errored, 0 skipped ``` The three refusals, live on the same recording: - A script that threw after creating records: `status "fail"`, `stepCount` unchanged at 1, and the message naming the side effects that were not rolled back. - A path resolving to no file: refused before any fork, no `durationMs`, and "Nothing ran, so there is nothing to clean up". - `flow-add-echo` holding `{{output:user.id}}`: refused with the author-facing message naming the step, the field and the later release. No device is involved at any point — a recording may open with a seeding script before it boots anything. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added the `flow-add-script` tool to run local `.mjs` scripts and record successful executions in flows. * Added script status, output, duration, logs, and failure details to recording results. * Added clearer handling for script cancellation, timeouts, missing files, and path casing. * **Documentation** * Updated flow guidance to clarify end-to-end classification and script setup or cleanup usage. * Documented script path requirements, failure conditions, and recording workflows. * **Bug Fixes** * Flows now reject unsupported output-reference templates with more precise diagnostics. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-07 12:59:29 +02:00
Hubert Gancarczyk	9c4bc9ef5b	feat(flows): run an external script as a flow step (#865) ... Stacked on #864, which adds the executor. This branch adds the `script:` step itself: the YAML directive, the runner integration, the CLI and MCP rendering, and the authoring reference. ```yaml - script: { path: ../../scripts/seed-order.mjs } - script: { path: ../../scripts/seed-order.mjs, timeout: 60000 } ``` A `script:` step runs an external `.mjs` file from the project, in a fresh Node process. What the script does is its own business — seeding an order, creating a test account, cleaning up what a run left behind are the reasons flows have wanted one. It drives no device, so a flow of nothing but scripts runs with nothing booted. ## What it adds - **The directive.** The value is always a map; `path` is required and obeys the same name rules a `run:` target does, spelled for `.mjs`. It resolves against the directory of the flow file containing the step, so a fragment reaches the same script whichever flow composed it. A mis-cased path is refused rather than run, because macOS and Windows would open it and Linux CI would not. - **The report.** The script's stdout and stderr come back on the step and print under the step line, on a pass as well as a failure — it is the only record of what the step did to the backend. Both renderers (CLI, MCP) carry it, live and buffered. - **The fail/error split.** A `fail` is the script's own answer; an `error` is the host's. That is what lets CI tell a regression from the machine it ran on. - **Two boundaries.** An uploaded flow carrying a `script:` step is refused before anything runs — its `.mjs` never left the client. A flow whose script step sits beside a `run:` step still resolves a device. ## Review follow-ups The last three commits answer a review of the three above them. - A launch behind a leading `script:` was not read as the flow's leading launch, so a Chromium flow that seeded a backend first hoisted no boot, bound to whatever browser happened to be up, and passed a launch it never performed. The same lead-in walked a fragment past the `executionPrerequisite` refusal its `echo:`-led twin is given. Both readers now share one exhaustively-switched predicate. - Coverage: the whole failure-kind table, the mis-cased arm CI never ran, the two unreached `scriptFileProblem` arms, symlink resolution for a script path, and the CLI live-progress closure that no test had executed. - Docs: the reference claimed the log was secret-redacted (it is not), never mentioned the environment allowlist, the working directory, the time-limit ceiling or the log caps, stated a fail/error rule that was not the code's, and was missing from its own table of contents. The skills stated a closed list of legal unrecorded insertions that excluded the only way this step can ever be written. ## Verification `npm run build`, `npx eslint . --max-warnings 0`, `npx prettier --check .`, `npm run knip`, `npm run typecheck:scripts` and `npm run test:scripts` are green, as are the three `tsconfig.test.json` typechecks. Suites: tool-server 357 files / 4552 passed, `@argent/cli` 469, `@argent/mcp` 83, `@argent/registry` 90. Reproduced end to end against a real tool server and a real Electron app, not only in tests: a flow of `script:` then `launch:` now boots its own Chromium instance and reports it, where before it attached to a stray browser and reported a green launch for an app path that did not exist. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Added support for local `.mjs` scripts as flow steps, including configurable timeouts, validation, cancellation, and device-free execution. - Script output is displayed in CLI runs and included in MCP flow results, with indentation and truncation notices. - Script failures now provide clearer diagnostics and verdicts. - Flow authoring tools recognize and guide creation of script steps. - **Documentation** - Added guidance for script syntax, execution limits, output handling, classification, and remote-run restrictions. - Updated flow creation and QA guidance to include script steps. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Hubert Gancarczyk <claude-hubert.gancarczyk@swmansion.com>	2026-09-07 12:08:13 +02:00
Hubert Gancarczyk	1a7e97fb14	feat(flows): run a local script in a bounded child process (#864) ... Adds the executor a flow `script:` step runs on: a fresh Node child per step, a protocol over its IPC channel, and the two watchdogs that make a hung or runaway script the runner's problem rather than the host's. The step itself is not here. This branch stops at the executor and its unit tests; `feat/flow-script-step` stacks the YAML directive, the runner integration, and the reference docs on top. ## What it does - **One child per step.** Spawned with an old-space heap limit, an explicit working directory, and an environment built from an allowlist rather than copied from the tool server. - **A deadline and a lifeline.** A separate watchdog holds the deadline, so a script that wedges the event loop still dies on time; a second one reaps the whole process tree when the parent goes away, so a grandchild cannot outlive the run. - **A concurrency queue.** Slots are bounded per server. A step that never gets one is refused with a message that says so, and an aborted run frees its slot immediately. - **Log budgets.** 64 KiB per step and 256 KiB per run, counted on the bytes the report keeps: redaction and V8 frame collapsing both run before anything is counted, so what the limits bound is the size of the report rather than the size of the script's writes. - **Secret hold-back.** The scrub walks a chunk and stops where a value could still begin, so neither half of a value split across two chunks is released on its own, and a shorter value is never taken where the longer one containing it has not arrived yet. - **A failure taxonomy.** Twelve kinds, split into what the script did (it threw, it did not load, it exited non-zero, it wrote an unusable `output`) and what the host did to it (a limit, a signal, a spawn that failed, a queue slot it never got). ## Docs `packages/docs/docs/reference/configuration.mdx` lists the two configuration keys this branch adds, `scripts.maxTimeoutMs` and `scripts.heapLimitMb`. The `script:` step itself is documented with the step, on `feat/flow-script-step`. ## Verification `npm run build`, `npx eslint . --max-warnings 0`, `npx prettier --check .`, `npm run knip`, `npm run typecheck:scripts`, the test typecheck across every workspace, the tool-server suite (4719 passed, 1 skipped) and `npm run test:scripts` (92 tests) are green, as is `npx docusaurus build`. The executor's own behaviour is covered by the eight `test/flows/script/` files added here, against real child processes, and the compiled `dist/` executor was driven against its copied runner assets over every path the review reached. Each review fix carries the run that reproduced it before the change and the mutation that proves the new test fails without it: the prefix-secret leak and all three npm `node-options` routes were reproduced end to end through the executor against real child processes, and the five coverage findings were confirmed by re-applying the exact mutation each thread named. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added reliable execution of trusted flow scripts with concurrency control, cancellation, timeouts, memory limits, logging, and detailed failure reporting. * Added safeguards for process cleanup, watchdog termination, output validation, and secret redaction. * Added global configuration for maximum script runtime and memory usage. * **Bug Fixes** * Improved handling of script failures, stalled processes, malformed output, and child-process termination. * **Documentation** * Documented script resource limits and global configuration behavior. * **Chores** * Updated builds and packaging to include required flow-script runtime assets. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Hubert Gancarczyk <claude-hubert.gancarczyk@swmansion.com>	2026-09-07 11:34:30 +02:00
Mateusz Aliyev	6e9e45c9f0	feat: attach to devices offered by external providers (#735) ... This pull request lets Argent drive a simulator or emulator another process is already running, attaching to its simulator-server rather than spawning a second one. A provider writes a JSON descriptor to `~/.argent/providers/` listing the devices it offers and the mechanisms Argent may use on each. They appear in `list-devices` with an `ext:` id and work with the existing tools. The file is re-read on every call, so a withdrawal or a narrowed grant applies immediately. `ios.additionalDeviceSets` (#600) already makes such a simulator reachable by UDID. What changes is ownership. `boot-device` and `stop-simulator-server` refuse these devices, anything the provider did not grant is refused with a message naming it and Argent uses only the endpoints its own simulator-server build serves. A grant binds to the device rather than to one of its names, so the real udid or serial is gated exactly like the `ext:` id. Android emulators are covered too and a device visible to both a provider and `adb`/`simctl` is listed once. The contract ships as `schemas/device-provider-v1.json`, validated by `argent providers check`, and is documented in `docs/reference/device-providers.mdx`. Includes unit tests and an e2e phase where the harness acts as its own provider. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added support for discovering and connecting to externally managed devices. * Added `argent providers` commands for listing, validating, publishing, withdrawing, and pruning providers. * Added provider-aware simulator, debugger, profiler, native tools, and device listings. * Added capability controls, endpoint validation, revocation handling, and provider-specific diagnostics. * Added automatic CLI discovery for provider integrations. * **Bug Fixes** * Improved service recovery and paused-runtime error reporting. * Improved simulator keyboard and paste command reliability. * **Documentation** * Documented provider descriptors, capabilities, lifecycle rules, and CLI usage. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-04 22:02:57 +02:00
Ignacy Łątka	e895dd0a5d	fix(flow): give every flow in a directory run a verdict on stdout (#739) ... ## Every flow run says how it ended, on stdout `argent flow run` wrote some outcomes only to stderr. A CI job that archives stdout — the common case — got a log with a hole in it. **A directory run**, three flows, one with a `run:` the parser rejects: ``` $ argent flow run <dir> > out.txt 2> err.txt ; echo $? 1 ── out.txt ── ← the log that gets archived [1/3] a-ok.yaml PASS — 0 passed, 0 failed, 0 errored, 0 skipped (no test steps) [2/3] b-broken.yaml [3/3] c-ok.yaml PASS — 0 passed, 0 failed, 0 errored, 0 skipped (no test steps) FAIL — 3 flows: 2 passed, 1 failed, 0 skipped ``` `[2/3]` has a header and no outcome. The tally says one flow failed and stdout names none; the reader's inference that `b-broken` was the one is available only because it is the sole entry missing a line. **A single-flow run** had the same gap, and worse — with live step lines the last thing the log holds is a `✓`, so a run that died reads as one that passed and got truncated: ``` $ argent flow run checkout.yaml > out.txt 2> err.txt ; echo $? 1 ── out.txt ── Flow "checkout" ✓ 1 tap ✓ 2 assert ← ends here ``` ## The fix An indented verdict on stdout for every branch that had none, on both runners: ``` ✗ not run (invalid flow) ← rejected by validation; a batch continues ✗ not run (no device resolved) ← nothing matched the run, or several did and none was singled out ✗ not run (rejected) ← rejected for a reason neither of the above names ✗ did not finish (run error) ← in a batch, this flow is the one that stopped it ✗ did not finish (no run report) ``` stderr is untouched, so anything reading that stream sees exactly what it did before, and the detail is not duplicated onto the merged stream. Both runners print the verdict directly under the header and the stderr detail after it, so a `2>&1` log of a batch reads like a `2>&1` log of a single run. No verdict reaches `--json` — every one is behind `!args.json` — so neither runner ever mixes prose into that stream. What each emits is unchanged: a batch still prints its one aggregate document on every path, and a single run still prints the report alone, which means nothing at all when the run produced no report. ### What a batch's `--json` carries The aggregate is the mode a CI job consumes for a directory, so the classification the verdict is chosen from travels with it: a failed entry carries `error_code` and `error_kind` beside `error`, under the names `--json-stream` already publishes. Without them an invalid flow file and an unresolvable device are the same `{"status": "fail", "error": "<prose>"}` entry with the same key set, told apart only by a message the server assembles from device lists and remedies. ### Picking the wording from the failure code, not the kind `error_kind: "validation"` marks any rejection the server scopes to one call; it says nothing about the flow file. Device resolution rejects that way too (`FLOW_DEVICE_RESOLUTION`), so keying the wording off the kind made a batch run with nothing booted report every one of a directory of good YAML files as `not run (invalid flow)` — sending the reader to the wrong file. `rejectionVerdict` switches on `error_code` instead: only a code whose subject is the file (`FLOW_FILE_INVALID`, `FLOW_ENTRY_UNRECOGNIZED`, `FLOW_E2E_HAS_PREREQUISITE`) licenses "invalid flow"; anything unrecognized stays neutral and leaves the reason to the stderr line beside it. `FLOW_NAME_INVALID` is deliberately absent. `argent flow run` only ever sends `flow_path`, and both of its paths screen the stem against `SAFE_FLOW_NAME` first — which *is* `FLOW_NAME_PATTERN`, the pattern `assertSafeFlowName` applies on the server — so the code cannot come back from a flow run. `FLOW_PROJECT_ROOT_INVALID` is out for the same reason: `project_root` is `process.cwd()`, always absolute and never `..`-bearing. Which rejections let the batch continue is unchanged — still `errorKind === "validation"`. ### Also on the single-flow path `!report || !("steps" in report)` took a primitive wire value straight into `in`, which throws on one — `TypeError: Cannot use 'in' operator to search for 'steps' in a-string`, surfacing through the CLI's top-level catch as a raw stack trace. The batch path guards this deliberately ("must classify as no report, not as an infra throw"); this one now does too. ### Docs The help text said a directory run prints "only failing steps plus a final summary" and named an invalid file as the only rejection it survives. It now describes what it prints and what it continues past. `packages/docs/docs/reference/flow-yaml.mdx` still described the batch as printing "only the failing steps and a summary" and named an invalid file as the only rejection it survives. It now describes what a directory run prints, tables the six outcome lines with their meanings, states what the `--json` aggregate holds down to `error_code`, notes that a single-flow `--json` failure writes nothing at all to stdout, and adds `--json-stream` to the option table — the mode that carries the failure as a record. Two claims that survived into the first pass of that page were wrong and are corrected here: a flow that fails its *steps* also leaves the batch running (only a transport failure, a rejection of another kind, or a reply that is not a report stops it), and the aggregate entry for such a flow carries a report and no `error`. The `flow run --help` blurb carried the first of those two as well. `argent-create-flow` carried the same stale sentence when this branch opened, and an earlier commit here fixed it too. #730 has since split that skill into `references/` and dropped the standalone-runner paragraph from the tree, so there is nothing left to correct there and the merge resolution takes the hunk out. ## Checks - E2E through the built CLI (`packages/argent/dist/cli.js`) for every transcript above, plus the `--json` shapes piped through `python3 -m json.tool` to prove one document. - `packages/argent-cli`: 512 passed across 24 files (`flow.test.ts` 148). - Mutation matrix over the new behaviour, 24 mutations applied and reverted individually: deleting each of the five verdicts, dropping either `!args.json` guard, weakening `isFlowReport` in six ways (each conjunct dropped in turn, `every`→`some`, and reverts to both earlier readings), deleting each `rejectionVerdict` arm, swapping two wordings, dropping either `liveSteps === 0` header guard, dropping `stopped = true`, restricting the batch verdict to the first flow, and emitting a verdict on the success path. Every one reddens a test; no gaps. - Reverting only the source hunks fails exactly the tests added here; no pre-existing test changes state. - E2E against a real tool-server for the review follow-ups: a directory of one unparseable YAML plus one flow needing a device, run with the verdict and the stderr detail merged (`2>&1`) to show the order, and again under `--json` — `FLOW_FILE_INVALID` / `validation` arrive in the aggregate entry and stdout parses as one document. A `--platform vega` run with no VVD gives the real `not run (no device resolved)` line. - Mutations for the follow-ups, each applied and reverted: dropping the failure signal from the aggregate, relaxing the batch guard to `!args.json || rejectedThisFlowOnly`, dropping `&& !args.jsonStream` from the single-flow guards, restoring the old detail-before-verdict order, and deleting the batch verdict. Every one reddens a test. - prettier, eslint (`--max-warnings 0`), `tsc --build`, `tsc -p tsconfig.test.json`, knip and `npx docusaurus build` in `packages/docs` all clean. Two findings from reviewing this branch are out of scope and filed instead: #1025 (`--json` prints the usage text on stdout for a flag error, where `--json-stream` keeps stdout machine-readable) and #1026 (a directory run's artifact export sits outside the loop's `try`, so an export throw loses the batch summary, the skip entries and the aggregate). Directory runs arrived in #576, so the batch half is a defect in a new feature rather than a regression; the single-flow half predates it. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added clear outcome lines for flow runs, including validation rejections, execution errors, missing reports, and skipped flows. * Batch runs continue after flow-specific validation rejections and stop when other errors occur. * Added machine-readable failure classifications to JSON output, including batch aggregates. * Added `--json-stream` for one JSON record per line during single-flow runs. * JSON modes now emit only machine-readable output, with aggregate details for directory runs. * **Documentation** * Expanded flow command documentation with batch behavior, outcome statuses, and JSON output details. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-04 14:28:52 +02:00
Sebastian Flajszer	1068430b91	feat(ios-device): small fixes related with ios-device support (#1031) ... Follow-up to #944: the fixes made after the review that did not make the squash. ## What changes - **Signing note**: delivered only to a call whose device argument resolves to a physical iPhone, including `flow-execute`'s `device`, and held (not dropped) across other calls. The label is now `Apple Development (KEYID)`; the certificate CN's Apple ID no longer reaches agent context or logs. - **Flow device resolution**: the no-device-matched refusal names the cabled phone and the exact `device <udid>` / `--device` spelling. A physical iPhone is never picked automatically. - **`gesture-swipe`**: the description states the hardware semantics (edge gesture needs `fromX` 0, `durationMs` sets drag speed, `momentum:false` does not damp). - **Skills**: `argent-ios-simulator-setup` skips `kind: "device"` entries; `argent-ios-device-setup` and `-interact` state the runner build timing, the full list of tools that do not exist on hardware, the backgrounded-target behaviour of each read tool, `actionButton` only on models that have one, and the swipe and `open-url` rules; the flow, Metro and profiler skills each carry one line on physical-iPhone limits. - **Docs**: `physical-ios-devices`, `flows`, `flow-yaml` and `tools` corrected to match the behaviour above; README platform row; runner `PROTOCOL.md`. ## Verification - tool-server suite 400 files / 5173 tests, `tsc`, lint, prettier and the docs build clean. - Live re-check against 0.23.0 on three simulators and a physical iPhone 15: no regression; the note lands once on the first phone call with no e-mail address, and flow auto-detection is byte-identical to 0.23.0 with 0, 1 and 3 simulators booted.	2026-09-03 14:53:25 +02:00
Sebastian Flajszer	1e69c90981	feat(ios-device): add physical iOS support (#944) ... # 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 -->	2026-09-03 14:33:11 +02:00
filip131311	397dce87f6	feat(installer): allowlist.enabled config — opt out of allowlist refresh on update (#986) ... A minimal opt-out for the allowlist refresh in `argent update`: a new config key **`allowlist.enabled`** (project + global scopes, restrictive merge — `false` in either scope wins, so a committed project opt-out holds for the team). **Nothing changes by default.** The key has no default value; while it is unset, `argent init` and `argent update` behave exactly as today. Only an explicit ``` argent config set allowlist.enabled false ``` changes anything: `argent update` then skips re-applying editor auto-approve allowlist rules entirely (rules already written stay) and prints a dim one-liner saying why. `argent init` is untouched — it still asks its auto-approve question and applies the answer as before. ### Docs `reference/configuration.mdx` gains the key's row and a short behavior note. `docusaurus build` and `npm run format` are clean. ### Tests - `allowlist.enabled` merge semantics (restrictive, no default) in configuration-core. - Suites: installer 555, configuration-core 125; tsc, eslint --max-warnings 0, prettier, both knip gates clean. - Live-tested from a packed tgz in an isolated HOME: `init -y` and `update` with the key unset are byte-identical to main's behavior; with `allowlist.enabled false`, `update` re-imposes nothing and prints the skip note. Supersedes #787. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_014b5AyEqWd16k1s8xvve3dS <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Added an `allowlist.enabled` setting to control editor auto-approve allowlist updates. - Allowlist updates now run when enabled or unset, while an explicit disabled setting prevents changes. - **Documentation** - Added configuration reference details, including scope precedence and unset behavior. - **Bug Fixes** - Preserved non-blocking handling when individual editor allowlist updates fail. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-08-31 19:29:37 +02:00
filip131311	23b9a07760	feat(mcp): auto-describe — element tree after interaction tools + relaxed tapping rule (#958) ... ## Why The rule's `<tapping_rule>` ("Before **every** tap, you MUST call a discovery tool") makes agents loop `tap → describe → tap → describe`: over 35 baseline runs, `describe` was called 90 times against 86 taps — one round-trip per tap, each a full model turn. The screen after an action is already captured by the auto-screenshot; the element tree is the only thing the agent still had to fetch. ## What - **MCP** (`packages/argent-mcp`): after the action settles, call `describe` and append `--- Elements after action (describe) ---` + the tree to the tool result. Follows the same tool allow-list as the auto-screenshot, skips `describe` itself, and sits inside the non-secret branch so a `{{secret:…}}` value never re-enters context as text. Spy-logged as `auto_describe` (duration, chars). MCP `instructions` reworded. - **Flag** `disable-auto-describe` (opt-out, mirrors `disable-auto-screenshot`). Auto-describe has its own tool list (`AUTO_DESCRIBE_TOOLS`) and its own branch, so the two features are independent; the secret-placeholder skip and the screen-idle wait cover both. - **Rule + skill**: `tapping_rule` now says take coordinates from the returned tree, call a discovery tool only when there is no fresh tree for the screen (first action on a screen, after a wait, target not listed); the two-failed-taps rule and the "never from pixels" prohibition stay. `argent-device-interact` best-practice #6 and the general-rules line updated to match. - **Docs**: `reference/configuration.mdx` flag row, `features/interacting-with-apps.mdx` discovery section. - **Tests**: `autoDescribeEnabled` (global / project scope) and `shouldAutoDescribe`. ## Evidence A/B with `claude -p --model sonnet`, one build (variant env-gated during the experiment), two sandbox projects differing only in rule/skill text and the toggle; 7 tasks × 2 arms × 5 reps = 70 runs on the iPhone 17 Pro simulator (iOS Settings ×3, Expo `my-app` ×2, Contacts create verified in sqlite) and the Electron testbed. | | main | this PR | Δ | |---|---|---|---| | Task success | 35/35 | 35/35 | = | | Turns / run | 10.4 | 8.2 | −21% | | Wall / run | 36.5 s | 28.0 s | −23% (new won 28/34 pairs) | | Cost / run | $0.28 | $0.23 | −17% (27/34) | | `describe` calls / run | 2.2 | 0.24 | −89% | | Cache-read tokens / run | 622k | 421k | −32% | (34 clean pairs; one pair excluded for external interference on the simulator — with it included: wall −5%, cost −10%, turns −16%.) Every iOS task moved 15–30% in favour of the new arm; Electron was neutral (both arms describe once after `boot-device`, then a single `run-sequence`). The appended tree costs ≈2.4k chars (~700 tokens) and a median 73 ms per action; per-turn latency was unchanged, the saving is the removed model round-trip. Full report: https://claude.ai/code/artifact/279528cf-ea92-4f52-9276-4f0475ba3e3c ## Caveats - Sonnet only, short tasks, small screens. On feed-heavy apps with 10–20k-char trees the per-action overhead grows; a follow-up could cap or filter the appended tree. - Flags are read once at MCP start (same as `disable-auto-screenshot`), so toggling needs an MCP restart. ## Checks `vitest` argent-mcp (85) + configuration-core (122) green; `eslint --max-warnings 0` on changed packages; `prettier --check .`; `npx docusaurus build` green. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Interaction tools now return an accessibility element tree alongside the latest screenshot. - Agents can use fresh element data for follow-up actions without an additional discovery step. - **Configuration** - Added the `disable-auto-describe` feature flag to turn off automatic element trees. - **Documentation** - Updated interaction guidance and configuration references to explain the new behavior and flag. - **Bug Fixes** - Secret-placeholder handling now correctly accounts for both screenshots and element trees. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-08-28 17:20:51 +02:00
Jakub Piasecki	d4a712c401	refactor(gesture): rename the momentum-free flag to momentum (#732) ... `settle: true` collided with the runner's other `settle` — waiting for the tree to quiesce — which is the very thing a swipe step does after every dispatch, whichever way the flag is set. One sentence of the flow skill used both senses at once. This names the physics instead: `momentum: false` is the momentum-free gesture, and the natural fling is the default the prose already described. ### Renamed | surface | before | after | | --- | --- | --- | | `swipe` flow directive | `settle: true` | `momentum: false` | | `gesture-swipe` param | `settle` | `momentum` | | `gesture-drag` param | `settle` | `momentum` | The directive passes the flag straight through to the tools, so all three move together. `momentum: true` is the default and normalizes to absent, mirroring what `settle: false` did — parse/serialize stay exact inverses. ### Also - Recording summary label `(settle)` → `(momentum-free)` - Internal constants → `MOMENTUM_FREE_EASE_EXPONENT`, `MOMENTUM_FREE_MIN_STEPS` - `flow-run` tool description and `argent-create-flow` skill updated ### Testing `tsc -b`, eslint (`--max-warnings 0`) and prettier clean; `test/flows` + `test/tools` pass 671/671, including a new case covering the legacy-spelling rejection.	2026-08-28 09:55:47 +02:00
Jakub Piasecki	e314b3ef4a	feat(flow): swipe directive (#520) ... Add one semantic finger flick for dismissing cards, paging carousels, opening drawers, and other gesture-driven actions distinct from goal-seeking scroll-to. Support bare directions plus from with exactly one of direction, to, or by, optional settle, and positive finite duration. Resolve selector or normalized-point anchors through the shared target path. Direction uses the Maestro geometry presets and now rejects anchored gestures that would collapse or travel opposite to the requested direction. Relative by deltas saturate supplied axes to [0, 1] and reject any effective zero or sign reversal. Resolved starts must remain on-screen, while explicit endpoints stay author-controlled. Keep parse and serialization invariants aligned for programmatic steps, improve unknown-key hints and selector diagnostics, surface swipe targets in run reports and recording summaries, share positive-millisecond validation, and reuse the common flow test harness. Dispatch gesture-swipe on touch platforms and gesture-drag on Chromium, reject touch directives on Vega, and document when to prefer scroll-to or a raw system-edge gesture.	2026-08-28 09:55:47 +02:00
filip131311	c2324f052d	feat(telemetry): project-scope opt-out (restrictive merge) + init --local --no-telemetry (#952) ... ## Why Teams that must not send usage data to a third party (a strict-compliance customer asked) had no way to turn telemetry off for a repository. `telemetry.enabled` was global-only (`~/.argent/config.json`), so a committed local install (`init --local`) still defaulted every teammate to **on** — `--no-telemetry` only opted out the machine that ran `init`. ## What - **`telemetry.enabled` accepts the project scope.** `consent.ts` now reads both `~/.argent/config.json` and `<project-root>/.argent/config.json` (root resolved from `cwd`, per-file cache keyed by path) and merges **restrictively**: `false` in either document wins. A committed project opt-out holds on every clone, and a project file can never re-enable a global opt-out. Env overrides (`DO_NOT_TRACK`, `ARGENT_TELEMETRY`) still outrank both. - **`argent telemetry enable|disable --scope global|project`** (default `global`). `status` names the document that decided (`config.json (project)`, `(global)`, `(project and global)`). `enable` at one scope while the other still opts out reports that telemetry stays disabled instead of claiming success. Unknown scope / argument → exit 2, nothing written. - **`argent init --local --no-telemetry`** also writes `telemetry.enabled: false` to `.argent/config.json`, and the "commit these files" checklist lists it. Global mode is unchanged. - `argent config set/unset telemetry.enabled` stays delegated to `argent telemetry` (`manageCommand`), so the lifecycle work (draining the live client) is still done by the dedicated command. ## Tests Unit: `telemetry` (+8 project-scope cases: single-scope opt-out, both restrictive directions, both-off, env precedence, live re-read of the project file, malformed project file), `configuration-core` (schema scopes), new `argent-cli/test/telemetry-command.test.ts` (real-fs, 6 cases), `argent-installer` — all green; eslint, prettier, knip, `docusaurus build` green. Live, from a real `npm pack` tarball of this branch (sandboxed `HOME`): 1. Fresh project → `init --local --yes --no-telemetry --from <tgz>`: writes `.argent/config.json` `{telemetry:{enabled:false}}` + global opt-out; summary lists `.argent/config.json` to commit. 2. `telemetry status` → `disabled`, source `config.json (project and global)`. `telemetry enable` (global) → "stays disabled: config.json (project) still opts out"; from `~` (no project) → `enabled`. `enable --scope project` → enabled; `disable --scope project` → disabled. `--scope team` → exit 2. 3. **Teammate simulation**: copied only the committed files to a fresh clone with a fresh `HOME` (no global opt-out), bundle built with a dummy OTLP token, `ARGENT_TELEMETRY_DEBUG=1`, drove `argent mcp` (initialize → tools/list → `list-devices` call). Control clone without `.argent/config.json`: tool-server emitted `toolserver:start`, `tool:invoke`, `tool:complete`, `toolserver:stop`. Clone with the committed opt-out: **0 events**, and the first-run telemetry notice is not printed. ## Caveat (documented) The project file is resolved from the working directory of the process. Editors start the MCP server in the workspace root, so it and the tool-server it launches read it. The tool-server is shared by every editor on the machine and reads the project file of the workspace that started it; the global opt-out or `DO_NOT_TRACK` still covers the machine-wide case. ## Docs Updated in this PR: `reference/configuration.mdx` (scopes + merge wording), `reference/telemetry.mdx` (new "Opt out for a whole repository" section), `reference/cli.mdx` (`init`, `telemetry` rows), `fundamentals/installation.mdx` (`--no-telemetry` in local mode). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01BkkAihA8Kp26hHS4uhkNGu	2026-08-25 11:24:02 +02:00
filip131311	efae6a8fb6	feat(tools): opt-in emulator sound on boot-device + boot-sound default flag (#813) ... Field report ([Slack thread](https://swmansion.slack.com)): when a session needs to test audio, it is very non-obvious that argent boots the Android emulator muted — the agent (and the user) burned significant time discovering it. The mute default is intentional (several agent-driven emulators all playing sound on the host would be worse), so this PR keeps it and instead makes it **discoverable and overridable**: ## 1. `sound` argument on `boot-device` (default `false`) - `sound: true` boots the emulator with audio output (drops the mute launch flag). - Applied consistently to the snapshot-loadability probe, hot boot, and cold boot — the qemu-device-topology parity invariant is preserved. A `default_boot` snapshot saved in the other audio mode fails the probe and falls through to a cold boot that re-saves it, so toggling costs one slower boot and nothing else. - iOS/Vega/Electron are unaffected (argent never mutes them); the argument documents itself as Android-only. ## 2. Agent-facing information: argument description only Per the thread, the info lives in the tool argument's description (no skill changes): it states the muted default, *why* (multiple agent-driven devices sharing the host's speakers), the `force: true` hint for an already-running muted emulator, the cold-boot cost of toggling, and the `boot-sound` flag. The underlying emulator flag is described behaviorally ("muted"), not by name, per our agent-docs convention. **Validated that the description alone is sufficient** by driving three models through the Cursor `agent` CLI with the schema excerpt and the exact scenario from the field report ("testing notification sound, hear nothing, emulator already booted with defaults"). All three — composer-2.5, gemini-3.7-flash, gpt-5.2 — correctly diagnosed the muted default and produced the exact fix `boot-device({avdName, sound: true, force: true})`, including the weakest model. Transcript excerpts in the PR discussion below if wanted. ## 3. `boot-sound` feature flag `argent enable boot-sound` defaults the `sound` **argument** to `true`. It only moves the argument's default, read live per call: an explicit `sound: false` on a call still boots muted, and without the flag the default remains muted. Registered in `FLAG_REGISTRY` so `argent enable`/`argent flags` pick it up with no further wiring. ## Tests - New `boot-device-sound.test.ts`: mute-by-default, `sound: true` dropping the mute flag from **both** probe and hot-boot spawn (parity), cold-boot spawn, flag-driven default, and explicit-`sound:false`-beats-flag. - The three existing Android boot test files now pin `isFlagEnabled` to `false` so a developer's real `flags.json` can't flip the args they assert on. - `tool-server` boot suites 62/62 green, `argent-cli` flags 33/33, `configuration-core` 122/122; lint, `typecheck:tests`, and knip all pass. 🤖 Generated with [Claude Code](https://claude.com/claude-code)	2026-08-24 14:51:16 +02:00
filip131311	8dda6aa1f9	docs: cover the paste tool on the interacting features page (#941) ... The `paste` tool was the only capability in the **Interacting** tool group with no mention on the `features/interacting-with-apps` page — typing, gestures, shake, buttons and permissions are all covered there. It already has its row in the tools reference. This adds the minimal parity: - one sentence in **Gestures and text**: for long text, the agent puts the text on the clipboard and pastes it in one step; - the **Limits** bullet for the sim/emu-only restriction, merged into the existing shake bullet, which has the same restriction. No reference changes needed — `reference/tools.mdx` already lists `paste`. Checks: `npx docusaurus build` in `packages/docs` passes; `npm run format` from the repo root leaves the file unchanged. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YPSUSz8gDxGm7tb9tA3b4D	2026-08-24 12:47:44 +02:00
filip131311	b232114422	docs: audit every comment in src against the code it describes (#931) ... Audits every comment in `src/` and `scripts/` against the code it describes. **462 files, 57 commits, net −8,194 lines.** Comment text only — the whole branch is code-identical to `main`. ## Method One subagent per file, strictly sequential. Scope was `src/` + `scripts/` (459 files); three more files were added at the end because they carried dead references of the same kind — two test headers citing design docs that do not exist, and `publish-npm.yml` citing a retired workflow. Each agent verified every comment — line, block, JSDoc, file header, trailing — against the surrounding code and the rest of the repo, following identifiers, paths, tool ids, config keys, env vars and issue links to see whether they still exist and still behave as described. Rules: - **A false or misleading comment is deleted, not reworded.** If a claim could not be confirmed by reading the source, it went. That is why the deletion count is so much larger than the rewrite count. - Survivors are cut to the shortest form carrying something the code does not already say. Restatement, preamble, hedging, changelog prose and ASCII banners are gone; the non-obvious *why* stays. - Preserved byte-identical: license headers, pragmas and directives (`@ts-*`, `eslint-disable`, shebangs, `/// <reference>`), JSDoc tag tokens, everything inside a string or template literal, and the sole comment inside an otherwise empty block (ESLint `no-empty` counts a comment-bearing block as non-empty). ## Verification Every file passed two independent gates before being recorded as done: 1. `comments-only` — the required check. 2. A second comment-stripping comparator with a proper mode stack, written for this pass because `comments-only`'s flat scanner desyncs on nested template literals and quote-bearing regex literals and then reports comment lines as code changes. Two files hit that false FAIL (`utils/android-profiler/pipeline/index.ts`, `scripts/extract-tools.mjs`); in both the "changed code" it printed was literally `//` lines, and the second checker confirmed the code was byte-identical. After the last file, all 462 changed files were re-checked against `main` with the same comparator, rather than trusting any agent's self-report. **459 code-identical; 2 are non-code (`.svg`, `.md`); 1 intentional.** The intentional one is `packages/argent/scripts/bundle-tools.cjs`: the changed template literal *is* the comment header of the file it generates, `packages/native-devtools-android/src/bundled-meta.ts`. Fixing only the generated file would have been reverted by the next build, so the generator changed too — and it has been verified to reproduce the committed generated file byte-for-byte. ## Representative false claims removed Not wording nits — statements a reader would have acted on: - **Reversed directions.** `proxyStart`'s JSDoc had the tunnel backwards (it is a reverse tunnel: the host binds first and the simulator dials in). A `paste()` doc had the pasteboard copy direction reversed. - **Contradicted by the code below it.** A timeout budget multiplied by three where the probes run concurrently — the same comment said so six lines later. A "warn once" that warns on every call. A "binary search" that is a linear scan. - **Named things that do not exist.** A `vega-fast-cli` binary, a `finish-recording.ts`, a `publish-next.yml` workflow, two `profiler-react19-*.md` design docs, a `DebuggerTarget.ts`, a commit hash git does not know, two tool ids, an `ensureEnv` cycle. - **Wrong by construction.** "Welford accumulators" across four files where the code keeps naive `n`/`sum`/`sumSq`; `sum`/`sumSq` documented over `actualDuration` when reduce sums `selfDuration`; a strict-mode halving written `n/2` where the code ceils; field docs listing enum values the producers never emit. - **Guarantees the code does not make.** A validation matrix claiming to cover "EVERY tool" that skips flagless ones; a Pareto cutoff that `slice(0, 20)` makes inert; an idempotence claim where the real rule is at-or-ahead; a capability note describing a clean 400 the shape-based device resolver can never produce. - **Unverifiable assertions** about prebuilt binaries, external CLIs and the cloud SDK — deleted rather than kept as folklore, since nothing in the repo can confirm them. - **Stale numbers**: invented Android tool versions, hard-coded tool counts and description lengths that had drifted. ## Review A Fable agent reviewed both halves adversarially for over-deletion, misread code, `no-empty` hazards and byte-identity violations. Second-half verdict: **SHIP**, with two one-line restores, both applied in the final commit — the `npm view ""` rationale behind a blank-token guard, and the note that `argent-mcp` keeps a copy of `SECRET_PLACEHOLDER_MARKER` it cannot import. ## Code issues surfaced but deliberately not fixed This pass changes comments only. Eight genuine findings are logged for a follow-up: 1. `telemetry/src/consent.ts` — a non-ENOENT read error returns null and falls through to the default-on path, so file errors *can* silently flip telemetry on. 2. `chromium-server/navigation.ts` — `navigate()` is reachable from `POST /api/navigate` with only a `typeof === "string"` check; open-url's schema is a bare `z.string()`, so the "already validated by zod" premise never held. 3. `http.ts` — `constantTimeEqual` returns early on a length mismatch, so the auth token's length is observable. 4. `describe/index.ts:~114` — the ios-remote branch passes `{ isTvOs: false }` unconditionally, so a remote tvOS simulator takes the iOS ax-service path, though `isRemoteTvOsSimulator` exists and shake/paste do use it. 5. `devices/boot-device.ts` — `-crash-report-mode never` is passed unconditionally *and* appended again by the feature-detecting path, so every emulator spawn passes it twice. 6. `react-profiler/pipeline/04-rank.ts` — `PARETO_THRESHOLD_PCT` is dead: `slice(0, 20)` always wins. 7. `reaped-sessions.ts` — a user-facing hint string tells the agent that `react-profiler-start { force: true }` disposes the debugger and profiler session; it does not. Left byte-identical because it is a string literal, not a comment. 8. `utils/simctl-backend.ts` — `localSimctl` is exported with no importers anywhere. ## Docs No documentation change is needed: this pass touches only source comments, and no user-facing capability, tool, CLI flag, config key or flow-file behaviour changed. --------- Co-authored-by: filip131311 <f.kaminski2000@gmail.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-24 12:16:20 +02:00
Kacper Kapuściak	e0fcf6c995	chore(docs): add Google Search Console verification meta tag (#939) ... Adds the `google-site-verification` meta tag to the docs site via Docusaurus `headTags`, so docs.swmansion.com/argent can be verified as a property in Google Search Console. ## Test plan - `npx docusaurus build` in `packages/docs/`, confirm the meta tag renders in the built HTML `<head>`. - After deploy, hit Verify in Google Search Console. No further docs update needed: this is a site config change with no user facing capability change.	2026-08-24 10:36:46 +02:00
filip131311	d0b3356ebf	feat(tool-server): paste tool (device clipboard + paste shortcut) (#879) ... ## Summary Registers a real `paste` tool. The `tools/paste/index.ts` from #506 was never registered and sent a `{cmd:"paste"}` WebSocket command simulator-server doesn't implement — dead on every platform. - **iOS simulator**: simulator-server `POST /api/clipboard/text` fills a private pasteboard and pushes it into the sim synchronously (host clipboard untouched); the tool then sends the ⌘V chord over the existing `key` command (the same `simulatorSendKeyEvent` path the keyboard tool uses). - **Android emulator**: same route over the emulator gRPC bridge, then `KEYCODE_PASTE` via `adb shell input`. - **ios-remote**: the MoQ transport's existing paste primitive, awaited. - Clean 400 for tvOS / Android TV (runtime probe), physical devices, Chromium (a renderer paste would clobber the *host* clipboard), Vega. - `{{secret:<NAME>}}` placeholders as in `keyboard`; allowed inside `run-sequence`; device-interact SKILL updated. - Description/skill tell the agent `paste` is **not** a `keyboard` substitute — only where a real user would paste (OTP/2FA code, long link/token, testing paste handling). ## Blocked on a simulator-server built with the `clipboard` feature: software-mansion/radon#185 adds it to the `argent` alias (no sim-server API change). Until a release + bin bump, the tool reports `PASTE_CLIPBOARD_UNSUPPORTED` (with an update hint) against the shipped binary. ## Test plan - 13 new unit tests (`test/paste.test.ts`) + secret-placeholder tests; full tool-server suite, lint, knip green (the 4 telemetry/bind test files that fail locally fail identically on `main`). - Live against a locally built simulator-server: iOS 26.5 Settings search (12 back-to-back pastes in order), Messages composer (multi-line/tab/emoji/diacritics preserved), `{{secret:EMAIL}}` never echoed or logged; Pixel_9 Settings search (ASCII + `Zażółć🔑`), Expensify RN login field; `run-sequence` paste steps; live 400s for tvOS sim / phone serial / chromium id.	2026-08-21 16:51:51 +02:00
Kacper Kapuściak	5e81136096	docs: generate an Open Graph card for every page at build time (#889) ... ## What Every docs page now gets its own Open Graph card, rendered during the build. The card is `static/img/og-background.png` with a frosted glass panel in the middle: a 920x400 rounded rectangle with a 32px radius, the background blurred behind it (`backdrop-filter: blur(60px)`, an SVG `feGaussianBlur` of stdDeviation 30) and tinted with `#C3D3E033`. The white Argent logo sits centred on the panel, with the page title centred underneath in DM Sans Medium at `#FFFFFF`. Before, every page shared one static `img/logo-icon.png`. ## How `plugins/og-image/index.js` is a Docusaurus plugin with a `postBuild` hook. It: 1. Renders the background and the frosted panel once. That part is the same on every card, so it is reused as a bitmap and only the logo and the title are rendered per page. 2. Reads each built page's `<title>`, strips the ` | Argent` suffix, and lays out the logo and the title with satori. Long titles wrap and stay centred. 3. Rasterises the result with resvg into `build/img/og/<route>.png`. 4. Rewrites the `og:image` and `twitter:image` tags of that page to the new absolute URL, and adds `og:image:width` / `og:image:height`. Satori embeds every glyph as a path, so resvg needs no font lookup. DM Sans Medium is vendored in `scripts/og-assets/` (with its OFL license), so CI renders the cards exactly as a local build does. Layout, colours and blur are constants at the top of the plugin. Pages with no title of their own get a card with the logo alone. That covers the home page, whose title is the site title the logo already shows, and the search page, whose title the Algolia search theme renders as `[object Object]`. The shared `@swmansion/t-rex-ui` theme points doc pages at `img/og/<title>.png` and hardcodes a "React Native Reanimated" fallback. The plugin overwrites those tags after the build, so the naming is route based and consistent across doc pages, the home page, search and 404. ## Verification Against a clean `npx docusaurus build`, checked for all 20 built pages: the tag is an absolute site URL, the target exists in `build/`, it is a valid PNG at 1200x630, `twitter:image` matches `og:image`, the width/height tags are 1200/630, and `twitter:card` is `summary_large_image`. No unreferenced cards. Serving the production build over HTTP, every card URL returns `HTTP 200` with `content-type: image/png`. `npm run typecheck`, `npm run build`, and the root `npm run format` and `npm run lint` all pass. ## Notes - The cards add ~16MB to a 65MB build, about 845KB each. The background is a photograph and resvg only emits PNG. Re-encoding as JPEG would bring that down to roughly 2MB at the cost of a `sharp` dependency, if the deploy size becomes a concern. - New `packages/docs` dependencies: `satori` and `@resvg/resvg-js`. Both record all platform binaries in the lockfile, including `linux-x64-gnu` for the CI runner. - The branch also carries a `docs: update favicon` commit, which replaces `static/img/favicon.png`. ## Docs No user facing docs change: this is build internals. The build step is documented for contributors in `packages/docs/CLAUDE.md`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01JovgRQBFngBsHnUYSoRF56	2026-08-21 16:31:57 +02:00
Kacper Kapuściak	36aa14a5fc	docs: add Argent documentation (#814) ... Adds the Argent documentation site, published to [docs.swmansion.com/argent](https://docs.swmansion.com/argent): a branded Docusaurus project under `packages/docs/`, the full first set of pages, and the CI that checks and deploys it. <img width="1512" height="945" alt="Screenshot 2026-08-21 at 13 05 04" src="https://github.com/user-attachments/assets/4607e143-4359-49a8-93a2-aaa3af4c9534" /> ## Site A standalone Docusaurus 3.9 project, built on the shared Software Mansion docs theme ([`@swmansion/t-rex-ui`](https://www.npmjs.com/package/@swmansion/t-rex-ui)) and restyled for Argent: - **Palette** from [argent.swmansion.com](https://argent.swmansion.com): dark `#0D0F26`, blue `#99DAFF`, lavender `#E4E1FF`, light `#FEFEFE`, mist `#F1F1F1`. The `--swm-*` token names stay, since the shared theme resolves against them. - **Typography**: DM Sans and DM Mono, matching the landing page. - **Sidebar** with lucide icons on every page entry (`sidebar_custom_props.icon` in the front matter, registered in `src/theme/SidebarIcon`), the logo kept on the page background and the panel inset from the edge. - **Video component** for embedded screen recordings, with `scripts/encode-video.sh` producing a web-sized MP4 and a poster frame for each clip in `static/video/`. - **Copy page button** and a few theme fixes: inline code badges in tables, paginator hover. - **No landing page.** That stays at argent.swmansion.com. The root route redirects to Getting started. ## Content Three sections in `docs/`: - **Fundamentals**: getting started, installation, supported platforms. - **Features**: interacting with apps, flows, network, screen recording, lens, visual regression, profiling, debugging. Conceptual overviews with recordings, each linking to the tools reference. - **Reference**: tools, CLI, configuration, flow YAML, editors, telemetry. Prose follows Simplified Technical English. The conventions (style, front matter, icons, checks) are written down in `packages/docs/CLAUDE.md`, and a root `CLAUDE.md` adds a checklist so that code changes to tools, CLI, configuration or flows update the matching docs page in the same pull request. ## CI and deploy - `Docs build` runs `format:check`, `lint`, `typecheck` and `build` on every pull request that touches `packages/docs/`. The build has `onBrokenLinks: "throw"`, so it catches links left dangling by a moved page. - `Docs publish` deploys `packages/docs/build` through the GitHub Actions Pages source on every push to `main` that touches the docs. The repository Pages source needs to be set to **GitHub Actions** for the first run. ## Notes for review - The site is excluded from the root `packages/*` workspaces (`!packages/docs`) and keeps its own `package.json` and `package-lock.json`, so its dependency tree stays out of the toolkit's lockfile. Root Prettier, ESLint and knip ignore it; it formats and lints itself with the repo `.prettierrc` and its own `eslint.config.mjs`. `check-workspace-versions.mjs` skips it so its `0.0.0` version is not read as drift. - `webpack` is pinned to `5.105.4` and `@docusaurus/plugin-content-docs` / `theme-common` to `3.9.2` via `overrides`. Newer webpack fails Docusaurus 3.9's ProgressPlugin option validation, and a hoisted `plugin-content-docs@3.10.2` produced a duplicate React context that crashed SSR. - **Search is not wired up yet.** The shared theme always mounts a DocSearch bar, so an `algolia` block has to be present. It reads `ALGOLIA_APP_ID` / `ALGOLIA_API_KEY` / `ALGOLIA_INDEX_NAME` from the environment and the bar stays hidden until Argent has its own DocSearch application. Follow-up PR. ## Testing - `npm run format:check`, `npm run lint`, `npm run typecheck` and `npm run build` pass in `packages/docs/`. - Root `prettier --check`, `eslint` and `npm run knip` pass. - Walked the served production build in the browser in light and dark themes while iterating: root redirect, docs pages, sidebar icons, videos, TOC, footer. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-21 16:03:35 +02:00