32 Commits

Author	SHA1	Message	Date
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
Hubert Gancarczyk	50c9580e30	fix(tools): make a schema failure name the parameter that was sent (#718) ... > Stacked on #717. ## The problem An invalid tool call returned Zod's raw issue array. Someone who wrote `flow_name` instead of `name` got back, depending on the tool: ``` Invalid params for tool "flow-start-recording": [{"expected":"string","code":"invalid_type","path":["name"]}] Invalid params for tool "flow-execute": [{"code":"custom","path":["flow_path"],"message":"Pass exactly one flow source: name or flow_path."}] ``` The first names the parameter the tool **wanted** and never the one the caller **sent**. The second — flow-execute's, whose `name` is optional so `flow_path` can stand in — names neither: it is anchored on the one source field the caller had no reason to send. Either way the mistake is invisible, and working it out costs a whole turn. ## What changes **1. `describeParamIssues` — one sentence per bad parameter.** Missing fields read as `` `name` is required (string) and was not provided`` rather than as a type error about `undefined`. Unknown keys are named and path-qualified, so a key nested in `selector` is not reported as a bare name that contradicts the top-level list printed beside it. The message closes with the caller's own keys — `You sent: \`flow_name\`, \`project_root\`.` — which is what makes the mistake self-evident. Key names only, never values: this string reaches logs, telemetry and the agent transcript, and a params object can carry a secret. Wired into both entry points: the registry's `invokeTool` and the HTTP boundary. **2. `flow-execute` accepts `flow_name` as an alias for `name`.** The tool is called `flow-execute`, so "the flow's name" spells itself that way; this is a mistake worth absorbing rather than rejecting. The name is resolved in code rather than by the schema — a Zod `required` failure would once again name only the field it wanted — and the error text names the spellings that are silently discarded (`flowName`, `flow`, `flow_file`), because by then Zod has already stripped them and the caller has no other way to learn their key was dropped. **3. A flow DIRECTIVE passed as `command` points at the tool that records it.** `command: "echo"` used to come back as a bare "Tool not found". It now names `flow-add-echo` — and says to call it **directly**, since routing it through the recorder would write the echo *and* a `tool: flow-add-echo` step that fails on every replay. The hint distinguishes directives the recorder **rewrites** from those it stores **raw** for the polish pass, because promising a rewrite that does not happen sends the author looking for a directive that is not in the file. `wait` and `long-press` get their own answers: neither has a recording tool at all. Only a genuine not-found is rewritten — a tool that ran and failed still reports its own error. **4. A recorder tool as `command` is refused.** `flow-add-echo`, `flow-add-step`, `flow-start-recording`, `flow-finish-recording` each mutate the recording itself, and nesting one reported success either way. Each is refused for its own reason: `flow-add-echo` would write the echo **and** a replay-breaking `tool:` step, `flow-start-recording` would **erase** this flow at replay, `flow-finish-recording` would end the take it is a step in, and `flow-add-step` cannot record itself. Now nothing is executed and nothing is written. --------- Co-authored-by: Hubert Gancarczyk <claude-hubert.gancarczyk@swmansion.com>	2026-08-25 10:48:49 +02:00
schicaelmott	dd5d823833	feat(flow): stream run progress as NDJSON (#855) ... ## Summary - add `argent flow run --json-stream` - stream flow progress as JSON lines - finish with a JSON result or error ## Why `--json` prints only after a flow finishes. `--json-stream` lets scripts and CI see live progress. ## Why this is a separate PR This is useful without the custom-tools feature in #856. ## Validation - `npm test -w @argent/cli -- flow.test.ts` — 106 tests passed - `npm run typecheck:tests -w @argent/cli` - `npm run build -w @argent/cli` --------- Co-authored-by: Filip131311 <contact@filipkaminski.com>	2026-08-21 12:14:34 +02:00
Ignacy Łątka	5d8fc10799	test: stop tests binding machine-wide resources they do not own (#714) ... ## Why Three flaky or failing tests were diagnosed separately this week, and all three turned out to be one defect wearing different clothes: **a test binding a machine-wide resource it does not own**, so a second concurrent run — another checkout, a CI matrix cell, a developer's own app — perturbs it. Those three are fixed in #707, #709 and #711. Each of those was found by chasing a symptom, and each audit covered only its own resource type. This is the systematic sweep: all **448 test files across 13 packages**, plus the 4 `node --test` scripts. (The sweep itself ran over the 400 files that existed when it started; merging `main` brought the count to 448, and every category below was re-run over the full set — 25 files assign `env.HOME` and none omit `USERPROFILE`, one test file calls `pkill`/`pgrep` (`vega-cli-timeout.test.ts`, scoped out to #711 below), and no `listen()` names a fixed port.) ## Findings | Category | Files checked | Real findings | |---|---|---| | Network endpoints (bind / probe / unix socket) | 448 | 4 | | Filesystem — shared temp namespace (`os.tmpdir()` and literal `/tmp`) | 448 | 8 | | Filesystem — real `$HOME` / `~/.argent` | 448 | 4 (28 files) | | Ambient environment | 448 + all `src` readers | 12 | | Device / emulator / SDK state | 448 | 2 | | Process table (`pgrep` / `pkill` / fixed-pattern sweeps) | 448 | **0** | | In-process globals leaking across files | 13 packages × 13 modes | **0** | Every finding was reproduced with a concrete instrument before being touched, and the instrument re-run after. Representative: - **`stop-tools.test.ts`** ran the real `stop-metro` against port 59999, which `lsof`s and **SIGTERMs whatever it finds**. With a squatter there: `16 passed` → `1 failed`, and the squatter logged `received SIGTERM #1`. Now port 1. - **`bind-failure-telemetry` / `lens-relay-telemetry`** were gated on the real `~/.argent/flags.json`. Enabling the documented `tool-server-event-log` flag: `4 passed` → **`4 failed`**, and records were appended to the developer's real event log. - **LogFileWriter (12 files)** — its constructor `mkdir -p`s `os.homedir()/.argent/tmp`. Instrument: run each of the 16 test files that reference a writer, or a blueprint that builds one, under a scratch `HOME`/`USERPROFILE`, then test `$HOME/.argent/tmp` for existence. 4 created it; the 12 that actually construct a writer now all call `scopeTempHome`, and none creates it. - **`screen-recording.test.ts`** — the device ids are fixtures and `vi.useFakeTimers()` seeds its clock from the real time, so only the millisecond a run starts in separates two runs' `.mp4` paths, and each test deletes the path it derived. Self-concurrent: **2 of 3 rounds failed** → 0 of 4. Scoping `TMPDIR` removes the window rather than narrowing it. - **`DO_NOT_TRACK=1`** → telemetry `282 passed` → **`13 failed`**. **`npm_config_user_agent=pnpm|yarn|bun`** → installer `535 passed` → 4/5/3 failed. **19 tests required a real `adb`** — PATH shadow + empty HOME: `30 passed` → **`19 failed`**. - A fixed `/tmp/argent-nd-<udid8>.sock` **destroyed a concurrent holder's live socket** (proven by inode) in **3** files that run the native-devtools factory. Two of them also fail outright: `native-devtools-app-state` lost **3 of 3** rounds of two concurrent runs on `expected 'unregistered' to be 'connected'`. All three now derive the UDID from `process.pid`. - `flow-visual`, `react-profiler/dump`, `file-inputs`, `http-upload` — shared `/tmp` paths and prefix scans, each reproduced with a squatter. In `http-upload` the collision surfaced *as a timeout*, inside `vi.waitFor`. (`flow-chromium-boot` was fixed on this branch too, but main's #585 rewrote that file afterwards and the merge kept main's copy, so it is byte-identical to `origin/main` here and carries no fix.) ## Clean, with the evidence - **Process table** — an `LD_PRELOAD` exec interposer over a full run (507 execs) plus all 12 other suites. Excluding `vega-cli-timeout.test.ts`, which is #711's and does sweep the table (`pkill -f '^sleep 6910[0-9]$'` at line 134): no `pgrep`/`pkill`/`killall`/fixed-pattern sweep anywhere, and **no test signals a pid it did not spawn**. - **Real device state** — **zero** exec attempts of real `adb` / `simctl` / `emulator` / `avdmanager` / `vega`; no test asserts a device list. That list was too narrow: `workspace-reader-integration` spawned the real `yarn` / `pnpm` / `bun` / `pod` / `eas` / `expo`, which is the second finding in this row. - **Cross-file in-process leakage** — structurally impossible: vitest 4.1.9 resolves `pool: "forks"` / `isolate: true`, confirmed by a scratch experiment (distinct pids, no env leak, module `Map` = 1,1,1). 120 default-mode runs across 12 packages produced 1 failure. - **`scripts/`** — 4 files, 86 tests: `mkdtemp` throughout, no ports, no sweeps, writes nothing. ## Verification Each fix was mutated back and killed by a **named** test under its instrument — e.g. `× reads a plain absolute path`, `× returns null when only the extensionless binary exists`, `× pins both names os.homedir() consults, at the same directory`. Restores verified with `git diff` / `git status`, never a substring grep. **Pinned by an instrument only:** the socket fix for `ios-only-blueprint-gate`, the `~/.argent/tmp` and `~/.argent/flags.json` fixes, the `/tmp` fixture cleanup, the `stop-metro` port change (the test asserts `stopped: false` / `pids: []`, which hold for either port whenever nothing is listening) and the `workspace-reader` `PATH` pin (only `node` is asserted; the other seven probes are not) are not pinned by any suite assertion — reverting them still passes, and only the external squatter / scratch-`HOME` instruments catch them. They are pollution fixes. The `native-devtools-app-state` socket fix is the exception in the other direction: reverting it turns two concurrent runs red. Gates, unpiped and read by exit code: `eslint .` 0, `prettier --check .` 0, `tsc --build` 0, `typecheck:tests` 0. Suite, run as six shards: tool-server **4287 passed, 1 skipped, 0 failed**; argent-cli 462; telemetry 306; argent-tools-client 191; configuration-core 122; argent-mcp 80; argent-installer 555. All other packages and `test:scripts` green, identical to baseline. `lens-tools-platform-gate.test.ts` times out at the 5s default under full-suite load and passes at `--testTimeout=30000` (24.7s, almost all of it transform). It predates this branch and is untouched by it. ## Scope This branch is **test-only** — no `src/` file is touched. Both production defects the sweep turned up are separated out, so each can be reviewed as the user-facing fix it is: `ps` without `-ww` orphaning live tool-servers is #713, and #852 is `ensureToolsServer` respawning on every call when `ARGENT_HOST` is exported — `buildToolsServerEnv` passes the inherited value to the child while the state records the literal `127.0.0.1` the health check then probes. The second surfaced here as eight stranded `fake-tool-server` processes, and pinning the environment in this branch removes that signal, which is why it is filed rather than merely worked around. A third, outside this branch entirely, is #853: ten `tool-server` test servers omit the host on `listen(0)`, binding every interface where twenty-two sibling sites pass `127.0.0.1`. It is hardening, not a live exposure — `createHttpApp`'s Host allow-list answers a LAN-addressed request with 403, and only a raw client forging `Host: 127.0.0.1` reaches the stub registry behind it, inside the ~100 ms one `it()` holds the socket. It is also not a collision risk: ephemeral ports are kernel-assigned and never reissued while in use, which is why the fixed-port audit above is unaffected. All ten predate this branch. Left untouched on purpose: `boot-electron-spawn-error.test.ts`, `chromium-discovery.test.ts` and `vega-cli-timeout.test.ts` — owned by the still-open #709 and #711, and all three still carrying their defects on this base. (#707 has since merged into this base, so `boot-device-hotboot.test.ts` and `vitest.config.ts` carry its fix rather than a defect; `test/setup/clear-argent-env.ts` is its work, and this branch relies on it.) **Not fixed, deliberately** — an adjacent class (test-*order* dependence, not machine-global resources), reproducible if wanted: `link-config.test.ts` (deterministic: `-t "returns null when required field"` → 4 failed), `network/network-integration.test.ts` and `android-perfetto/dispatch.test.ts` (fail under `--sequence.shuffle` seeds). **Also observed, not addressed:** one green tool-server run leaves **56** entries behind in a scratch `TMPDIR` — **30** in the `argent-screenshot-diff*` family, 4 `argent-events-*`, 3 `argent-flow-crop-*`, 3 `argent-tar-upload-*`, 2 `argent-flow-diff-*`, 2 `argent-file-input-*`, and 12 assorted singletons (`ast-index-*`, `component-source-*`, `argent-profiler-cwd`, `argent-chromium-media`, …). Measured per run against a scoped temp dir, so it ranks the contributors rather than counting one machine's accumulated history — screenshot-diff, not flow-crop, is the dominant one. A separate leak. That instrument is blind to a *literal* path, which is how it missed the two `/tmp/native-profiler-*-report.md` writers the fourth pass found. Re-run across all 13 packages, `argent-mcp` is the only one outside `tool-server` that leaves anything — two entries per run, filed as #854. ## Second pass A review of this branch re-ran every category above with its own instrument rather than reading the diff, and found the sweep had pinned four resources in one file while leaving a sibling that does the same thing live. Fixed in `4289e3d8f` and `8164955b4`; the table and bullets above are the corrected totals. - **`tool-server-event-log`** was mocked off in 2 of the 4 files that call the real `start()`. With the flag on, `startup-telemetry` and `tool-fail-invalid-params-emission` failed 3 tests in `attachRegistryEventLogger` and truncated the real `~/.argent/tool-server-events.jsonl` to 0 bytes first. `ARGENT_EVENT_LOG` cannot redirect that: `test/setup/clear-argent-env.ts` strips every `ARGENT_*` var before the module graph loads. - **`scopeTempHome`** reached 8 files; 4 more built a real `LogFileWriter` through the JS-runtime-debugger blueprint. - **`os.homedir()` on Windows** reads `USERPROFILE`, not `HOME`. `android-binary-windows` and `adb-resolve-avd-path` pinned only `HOME`, and both run on a real windows-latest host. Proven by running the resolver under a `node:os` mock that reproduces the Windows lookup: with `HOME` alone the stock Studio SDK under the profile resolves; with both pinned it misses. `update-checker` had the same gap. - **`getConsentState`** honours a falsy `ARGENT_TELEMETRY` at the same precedence as `DO_NOT_TRACK`, ahead of the config override the suite writes. Only `DO_NOT_TRACK` was pinned: `ARGENT_TELEMETRY=0` gave `17 failed | 6 passed`. - **`workspace-reader-integration`** let the version probe spawn the real package managers off `PATH`; their shims self-install, so the file pulled **~44 MB** into `~/.cache/node/corepack` and `~/Library/Caches/eas-cli`. `PATH` is now a directory holding only `node`, the one version the test asserts — 44 MB → 4 KB. - **`argent-mcp`** snapshotted `ARGENT_AUTO_SCREENSHOT_DELAY_MS` without clearing it, and that package has no `ARGENT_*`-stripping setup file, so 3 tests asserted the developer's exported value. Smaller items in the same commits: the `/tmp` socket fixtures now remove the directories they create per run; `http-upload`'s pre-scan snapshot is gone, since scoping `TMPDIR` to a fresh directory made it permanently empty and its filter inert, as its two siblings already did; and two `detectProjectPackageManager` assertions that enumerated the entire return union are pinned to a single value. The confirmation pass also caught a defect the first round of fixes introduced: pinning `HOME`/`USERPROFILE` to the fixture root in `android-binary-windows` let `<home>/Android/Sdk` shadow the `%LOCALAPPDATA%` root the two positive tests are named after, so deleting `roots.push(join(localAppData, …))` from the resolver left all three green. Home has its own directory in `6aee3ee7a`, and that mutation now fails both tests. A third pass, running the nearest-twin move repo-wide, found the `os.homedir()`-on-Windows gap in one more package: eight `argent-tools-client` test files redirect only `HOME`, and four of them recursively delete `STATE_DIR` — two before each test, two after — which on Windows is the developer's real `%USERPROFILE%\.argent`. Fixed in `139447d4a`, together with the same gap in `avd-snapshot`. Nothing runs that package on Windows CI today, so no current run fires it. ## Fourth pass A fourth pass audited the three fix commits and re-ran the sweep with two instruments the earlier ones did not have. Both holes were in the *measurement*, not the diff — which is why three passes missed what they found. Fixed in `a67c43f8d`. - **`os.tmpdir()` does not read the same variable on every platform.** POSIX takes `TMPDIR`, `TMP`, `TEMP` in that order; Windows takes `TEMP`, then `TMP`, and never looks at `TMPDIR`. The five pins this branch added set `TMPDIR` alone, so on Windows production still materialized into the machine-wide `%TEMP%` while the test scanned a scratch directory nothing ever wrote to — and `file-inputs`, `http-upload` and `flow-visual` each end in a leak assertion over that listing, which then passes whatever the code does. Against `origin/main`, which diffed a before/after listing of the real tmpdir, that is a regression rather than a wash. `redirectTmpdir` (`test/helpers/tmpdir-env.ts`) sets all three and returns the restore; the **7** files that scope a tmpdir use it, including the two `android-perfetto` ones that predate this branch. `test/tmpdir-env.test.ts` pins both lookup chains — reverting the helper to `TMPDIR` alone fails two of its three tests. All three leak assertions were re-confirmed live on POSIX by mutating the production cleanup each one covers. - **A hardcoded absolute path is invisible to a `TMPDIR`-scoped instrument.** `session-correctness` and `ios-instruments/analyze-freshness` passed a literal `/tmp/native-profiler-{x,ios}.trace` as the session's trace file, and the renderer writes its report beside it (`deriveReportPath` = `dirname(traceFile)/<base>-report.md`). Every run left `native-profiler-x-report.md` and `native-profiler-ios-report.md` in the shared `/tmp`; nothing removed them, and two concurrent runs write the same names. Reproduced with `TMPDIR` pointed at a scratch dir — the files still landed in `/tmp`, which is exactly why the `os.tmpdir()` row and the leftover census below both read clean here. Both tests now own the directory. - **A prefix-scanned env var is invisible to a grep for variable names.** `secretSources` enumerates `process.env` by the `ARGENT_SECRET_` prefix and ranks it *above* every file the test writes, so `secrets-command.test.ts` — which already pins `HOME`, `USERPROFILE` and cwd — still read the developer's shell. `ARGENT_SECRET_FOO=bar`, argent's own documented way to supply a secret: `6 passed` → **`3 failed | 3 passed`**, deterministic. `argent-cli` has no `ARGENT_*`-stripping setup file, so the prefix is cleared per test. Its sibling `configuration-core/tests/secrets.test.ts` was already immune — it threads an explicit `env: NO_ENV` into every call. - **`android-binary` and `vega-cli-fallback`** were the last two files redirecting `HOME` without `USERPROFILE` — the former the direct twin of `android-binary-windows`, in the same directory, driving the same resolver. Under a `node:os` mock reproducing the Windows lookup with an SDK planted in the profile, it loses **5 of 11** tests. No test file in the repo redirects `HOME` alone any more. (`6fbb66ce1` later skipped both of this file's describes on win32 — its fixtures are extensionless and the win32 resolver only takes `.exe` — so its own `USERPROFILE` pin is now symmetry with the sibling files that do run there, not a live guard.) Two smaller items in the same commit. `native-devtools-socket-bind`'s ENOENT fixture still rooted at `os.tmpdir()` while the comment three screens above explains why the others do not: with a 142-character ambient `$TMPDIR` that path exceeds `sun_path` and `listen` rejects it for *that* reason, which the assertions cannot tell from the missing-directory one they were written for. And `<home>\AppData\Local\Android\Sdk` — the resolver's fallback for a GUI-spawned server that never inherited `%LOCALAPPDATA%` — could be deleted with the whole suite green; it now has a test, and deleting either win32 root fails exactly the tests named for it. ## Fifth pass A fifth pass took the platform-branch shape the fourth pass exposed and ran it as its own move: *for every function that branches on `process.platform`, does the test's guard cover every arm, or only the one the author's machine takes?* Fixed in `e08b466b6`. - **`init-stale-config.test.ts` deletes the developer's real VS Code MCP config on Windows.** The file mocks `os.homedir()` and says it does so "so hidden-scope probes (`~/.claude.json`, VS Code user profile) never touch the real home directory". `vscodeUserDirs()` branches `darwin → homedir()/Library/Application Support`, `win32 → %APPDATA%`, `else → homedir()/.config` — the win32 arm never calls `homedir()`, so the mock is inert there, and the test's own `userMcpJsonPath()` mirrors the same branch. Both user-profile tests then write a one-entry fixture over `%APPDATA%\Code\User\mcp.json` with a whole-file `writeFileSync`, and assert that `remove()` deleted it. Reproduced by forcing `process.platform` to `win32` with a two-server `mcp.json` planted at a probe `%APPDATA%`: **`3 passed`, and the file and its directory were gone.** With `APPDATA` pinned, the whole file passes under the same instrument — 31 tests — and the planted config is byte-identical. - **`argent-tools-client` hands its ambient `ARGENT_*` to a real spawned child.** The launcher spawns an actual tool-server, and `buildToolsServerEnv` overrides only the keys it is given — everything else rides in on `...baseEnv`. `ARGENT_HOST` is the one that bites: the fixture binds the host it names while the launcher records and health-checks `127.0.0.1`, so reuse misses and a second server is spawned. With six overrides exported: **`10 failed | 181 passed`, and eight stray `fake-tool-server` processes still holding TCP listen sockets after the run.** With the prefix stripped: `191 passed`, none surviving. The package now carries the same setup file `tool-server` has, for the same reason — and it is the second of the two packages whose missing `ARGENT_*` strip this review found. ## Later passes A sixth pass audited the fix commits themselves and bounded the SDK probe (`6fbb66ce1`); a seventh ran the moves against the diff one more time and turned up the two below, plus the `listen(0)` defect filed as #853. - **The `PATH` pin made `workspace-reader-integration` POSIX-only without the guard its siblings got.** The shim it puts on `PATH` is an extensionless `node`, and `symlink()` to a file needs an elevated process or Developer Mode on Windows, so `beforeAll` throws `EPERM` there before any assertion runs; a copy in place of the symlink would not rescue it either, since a bare command name resolves through `PATHEXT`. This sweep already skips `android-binary` and `native-devtools-socket-bind` on win32 for exactly this class, and the Windows job runs a curated list of seven `tool-server` files that excludes this one, so nothing was catching it. Fixed in `095d75bd8` — verified POSIX `2 passed`, and under a forced win32 platform `2 skipped` with the top-level `beforeAll` never entered. - **A rationale that rested on a case the file excludes.** `android-binary`'s header justified pinning `USERPROFILE` by what `os.homedir()` reads on Windows, two sentences before noting that both describes skip on win32. Fixed in `f37b3605e`; the variable stays in the snapshot list, the justification no longer claims a platform this file never reaches. A seventh pass also re-ran the sweep against a hostile machine: every feature flag on in a scratch `~/.argent/flags.json`, no `adb` on `PATH`, and a `TMPDIR` long enough to overrun the 104-byte `sun_path` limit. It found one resource this branch had not closed. - **A red `launcher-version-gate` run strands a real tool-server.** `ensureToolsServer` spawns a fixture server, but its pid only reached the reaper after three or four assertions on the state it returned; any of those throwing left the pid unrecorded, and the same `afterEach` then deleted `STATE_DIR`, the only other record of what to kill. **Eight such processes were alive on the development machine**, spread from 14:33 to 18:23, every one from an `argent-version-gate-test-*` fixture and none from any other family — each still holding a TCP listen socket with its fixture directory long gone. Forcing one assertion to fail took the `tool-server.cjs start` count from 10 to 11. The nearest twin, `launcher-duplicate-spawn`, guards this twice: it records the pid straight after the null check and sets `FAKE_TTL_MS` so an escaped server self-exits. Fixed in `26c2c60ec` with both, the TTL also covering the window between the spawn and the state read where no pid exists yet — the same forced failure now leaves **zero** strays. An eighth pass audited the seventh's own fixes, and found the version-gate fix had been applied to one file when the defect was a property of four. - **Three more files strand a real tool-server on a red run.** `launcher-spawn` and `launcher-exit` set `FAKE_TTL_MS` nowhere; `launcher-duplicate-spawn` — the file `26c2c60ec` cites as the model — armed it inside one test's `try/finally`, so eight of its nine spawns ran without it and the `finally` disarmed it for the remainder of that test. Reproduced per file by forcing a failure before the pid is recorded: a detached node process survives, reparented to init, holding a listening socket, with its `TEST_HOME` removed and its state record already cleared. Fixed in `3bb69ded6` by moving the net to a file-wide `beforeEach` in all three. Verified end to end — the child carries `FAKE_TTL_MS=60000`, and a stranded server spawned at 21:28:36 exited by itself at 21:29:36 with nothing signalling it; three consecutive green runs stay at 191 passed. - **A 29th file writes the real `~/.argent`.** `boot-electron-spawn-error`'s success-path test completes a boot, and a completed boot calls `trackChromiumPort`, persisting to `os.homedir()/.argent/chromium-cdp-ports.json`. The real file on the development machine had accumulated **106 dead ephemeral ports**. Its two siblings in the same directory already mock `chromium-discovery` for exactly this reason; this was the third, with no mock. Fixed in `3306b6f40`. - **`scopeTempHome` was itself unpinned.** Deleting its `USERPROFILE` line — the Windows half, the same property the sibling helper's test pins — left all twelve consumers green at 48 passed. `3306b6f40` adds the missing test; it kills that mutation plus dropping the `HOME` pin and replacing the per-test `mkdtemp` with one shared directory. Two findings from that pass were refuted on verification and are recorded rather than acted on: the tool-server tmpdir leftovers (mechanism real, but they are the separate leak this body already scopes out) and a claim that `26c2c60ec`'s message overstated its twin. Four comments were also corrected against their code: `deriveReportPath` joins `<base>-report.md` *inside* the trace's directory rather than appending to the directory's name, which is what makes the `rm(traceDir)` added in `a67c43f8d` cover it; two `android-perfetto` comments still named `TMPDIR` as the mechanism after the switch to `redirectTmpdir`; and `android-binary`'s header claimed the home pin lets its two positive tests resolve "on either platform", though its fixtures are extensionless and the win32 resolver only accepts `.exe`.	2026-08-19 23:06:48 +02:00
Hubert Gancarczyk	96ea94f87a	feat(flow): add an idle condition that waits for the screen to stop moving (#728) ... > Stacked on #574. Replaces the route-fingerprint approach that #727 and #729 carried; both are closed. > > Rebased off the #715-#726 chain so it can merge on #574 alone. That chain owns `DirectiveOutcome.warning` / `StepReport.warning` and the `indeterminate` scoring rule; the small amount of each that this condition needs is carried here, scoped to `idle`, and will conflict textually with #724/#725 for whichever lands second. ## One check a selector cannot express ```yaml - await: { idle: true } ``` Has the screen stopped moving? Flows were substituting fixed `wait:` steps for it, which either wait too long on every run or too little on the run that mattered. ## Why it reads pixels as well as the tree Each signal is blind to what the other sees. The tree cannot see presentation-layer motion. An iOS push or modal dismissal commits its hierarchy up front and then animates a layer for a few hundred milliseconds; a cross-fade or a scrim moves no node at all. Measured on a real Android emulator: a page animating a large element continuously reads as a single static `WebView` node, and the existing `await-screen-idle` tool called it settled in **465 ms, five times out of five**. On a deterministic Chromium page whose DOM is byte-identical across the animation, that tool returned `settled: true` in **407 ms** while this condition failed 8/8. Pixels alone would not do either: they cannot see a tree still churning behind an unchanged surface, and anything animated forever (a video, a shimmer) would make a pixel-only settle unsatisfiable on a screen the tree calls ready. Unlike that tool, this cannot be silently stepped over. Readiness is not an acceptance criterion — the verdict belongs to the identity and outcome checks around it — so a screen that never settles still **passes**, carrying a `warning` that says what the green actually bought. That is what makes it safe to persist in a flow: it reports on every run without ever failing one over a video or a shimmer. The only thing that stops a run is a tree source that cannot be read. ## The rule the design follows The absence of evidence is never evidence. - A capture that did not arrive cannot complete the hold. - Neither can a single agreeing pair. Every animation that reverses has a turning point, and two samples straddling it come back identical while the screen is moving. On a live 3 s cross-fade that passed a default-shaped step on roughly **one run in three**; settling now takes two consecutive still intervals, so `minStableMs: 0` still means three reads. - A round is never started without the budget to observe it with. A round begun with nothing left neither captures nor reads, and both absences were otherwise recorded as facts about the device. - No verdict comes from a latch. A screen that settles and then moves again, or goes blank, has not settled. ## `timeout:` is a real bound No describe path takes an abort signal, so the tree read is raced against what is left of the budget. Without that, a wedged ViewInspector RPC ran 2.25 s past an 8000 ms budget, and a busy Android screen ran 5.4-6.0 s against a 3000 ms one. A read that runs out of step budget is the step ending, not the source failing, and only the latter is reported as an environment problem. ## Failure modes stay apart They call for opposite responses. A screen that never stopped moving is a verdict about the app. A tree that could not be read is not, and it names the foreground check first, because a backgrounded app reads identically to an uninstrumented one and relaunching is the wrong repair. A run whose captures never produced a comparable pair still settles on the tree and says so in a warning, rather than passing off half a proof as the whole one. ## Capture routing and tolerance Captures route exactly as the `screenshot` tool routes them, so tvOS and Vega, which have no simulator-server backend but are perfectly screenshottable through `xcrun` and the emulator console, are covered rather than written off. The pixel comparison owns its tolerance rather than borrowing `screenshot-diff`'s. That one holds a baseline stored across sessions, machines and OS versions against a live capture and must absorb real drift; this one holds two captures one poll apart from a single session, where a static screen reads back byte-identical (measured: zero changed pixels across five consecutive pairs on an idle simulator). The margin is load-bearing, because uniform change is all-or-nothing: at the baseline tolerance any cross-fade slower than ~2 s counted zero changed pixels and read as settled mid-animation. ## Not a screen check A dropped tap leaves the source screen perfectly idle. It belongs after the element check that names the destination, never instead of one. #730 documents the pairing. ## Verification - 3307 tests pass; typecheck, `typecheck:tests`, lint and prettier clean. Eleven mutations applied to the source, all eleven caught by tests. - Driven end to end against a real iOS simulator, a real Android emulator, and a Chromium app through a tool-server built from this branch: static screens pass with no warning (proving captures ran), animating screens pass carrying the warning that names the motion, and the pre-existing tool disagrees exactly where it should. --------- Co-authored-by: Hubert Gancarczyk <claude-hubert.gancarczyk@swmansion.com>	2026-08-10 11:50:16 +02:00
Hubert Gancarczyk	afd722924f	feat(flow): support concurrent flow recordings (#574) ... ## Problem Only one flow could be recorded at a time, anywhere on the machine. Recording state was three module globals in `flow-utils.ts` — harmless in a per-client process, but the tool-server is a **host-wide singleton per install bundle**. Every MCP client, every subagent sharing a parent's connection, every `argent` CLI call and every project on the machine attaches to the same process, the same `Registry`, and those same three globals. HTTP requests are served concurrently with no serialization. Three failures followed, all reproduced against the pre-change code: 1. **A second recording clobbered the first.** `startRecordingSession` just overwrote, so the first agent's next `flow-add-step` silently appended into the *other* agent's flow file — in a different project. 2. **Any agent could finish any agent's recording.** `flow-finish-recording`'s schema was literally `z.object({})`. 3. **Replay stomped recording.** `resolveFlowFilePath` called `setActiveProjectRoot`, so a `flow-execute` in project B rebound the global root mid-recording of project A. Already worked around, locally only, in `flow-add-step`. ## Approach Recording state is now a `Map` keyed by the resolved flow file path, `<project_root>/.argent/flows/<name>.yaml` — the identity of the artifact being built, so "same key" means "same output file" and two sessions on one key are a genuine collision rather than an accident of scoping. `flow-add-step`, `flow-add-echo` and `flow-finish-recording` each take `name` + `project_root`, so every call is self-contained; required rather than optional-with-fallback, since a fallback would succeed while an agent is alone and fail only once a second recording exists. `resolveFlowFilePath` is pure, which fixes defect 3 and retires `FLOW_PROJECT_ROOT_REQUIRED` (the state it guarded can no longer exist). Rejected alternatives — keying by device udid (flows are deliberately device-portable, and `flow-add-echo`/`flow-finish-recording` have no device at all), an opaque `recordingId` (an agent that loses the token cannot recover), and per-caller identity from the transport (`ToolContext` carries no caller identity, and subagents share their parent's MCP connection, so it would fail the exact scenario being fixed). ### Locking, and why readers needed more than a lock Every mutation of one flow file runs under a lock keyed by that path — appends, `flow-start-recording`'s truncate-and-register, and `flow-finish-recording`'s read-summarize-clear. Keyed by file rather than owned by the session, because a restart *replaces* the session: a session-owned lock cannot exclude the operation that supersedes it. Per file, not global, so two recordings never queue behind each other. An append whose session was finished, restarted or evicted meanwhile fails with `FLOW_NO_ACTIVE_RECORDING` rather than writing into a different take. The lock serializes writers only, and no reader of a flow YAML can join it — `flow-execute`'s own load, its `run:` fragment load, `flow-read-prerequisite`, `flow-add-step`'s sibling-fragment check, and the `argent` CLI reading from another process entirely, where an in-process lock cannot reach. Both writers used a plain `fs.writeFile`, which opens `O_TRUNC`, so a reader could land between the truncate and the write. That case is silent: `parseFlow("")` returns `{ steps: [] }` with no error and `summarize` derives `ok` from "no failures", so a `flow-execute` racing an append reports a **top-level PASS having replayed zero steps**. Both writes now go through a sibling temp file and a rename, so a reader sees either the whole old file or the whole new one — and unlike the lock, that also holds cross-process. ### `stop-all-simulator-servers` gets a `devices` scope Every agent is told to call this at session end, and unscoped it walked the whole registry — so agent A wrapping up tore down agent B's devtools mid-recording, degrading B's flow to brittle coordinate taps. It now takes an optional `devices` scope and reports `unmatched` ids, so a mistyped id doesn't read as a clean machine. Which namespaces count as "owned by a device" turned out to be the load-bearing part, because nothing cascades to most of them and `unmatched` turns any omission into an actively wrong diagnosis — a correct device id reported as a typo. The set now covers `AXService` (the in-sim ax daemon, spawned `--timeout 3600`; an iOS session that only ran boot/launch/describe owns this and nothing else), `ScreenRecordingSession` (an ffmpeg child plus the touch-visualizer overlay it enabled on the device), `NativeProfilerSession` (an xctrace child, or an on-device perfetto process and its trace file) and `JsRuntimeDebugger` (a bound loopback server, the CDP socket to Metro, a log handle). The debugger URNs interpose the Metro port — `<ns>:<port>:<deviceId>` — so the matcher understands both shapes, consuming only the first colon so a wireless adb serial after the port still compares whole. `stop-simulator-server` shared none of this and had drifted: it looked URNs up with an exact, case-sensitive `services.get()`, so a lower-cased UDID silently no-op'd there while the scoped stop-all reaped it. Both tools now share one matcher. Their namespace *sets* stay deliberately different, documented where they are defined — `stop-simulator-server` is also the documented recovery for a wedged transport, and widening it to devtools/AX would make a routine retry drop the native-devtools connection another agent's recording depends on, which is the hazard the `devices` scope exists to prevent. ## Verification **End-to-end, three devices, one shared tool-server** (iPhone 16 Pro, iPhone 17 Pro, Pixel 3a): three interleaved recordings, plus an unrelated `flow-execute` in a fourth project while all three were live. Both iOS devices held their own live native-devtools concurrently (two per-UDID sockets, `connected: true`). Each YAML contained exactly its own steps in order, taps captured as selectors rather than coordinates, and neither picked up another's or the third root's path. All three replayed green — also through the **released 0.17.0 CLI** against the modified server, which checks wire compatibility. A device-scoped teardown of sim 1 left sim 2 and the emulator running. Re-run against the final build: - Two interleaved recordings across two project roots on one device, with a **separate process** polling one of the flow files as fast as it could for the duration. Zero empty or truncated observations; each YAML held exactly its own steps; both replayed green (6/6 and 5/5). Against the pre-change in-place write the same reader observes zero-step reads interleaved among the real ones — the silent-PASS input. - A scoped teardown of the iPhone reaped `AXService` and `NativeDevtools` for that UDID only, reported no `unmatched`, and left the second sim and the emulator running. Lower-casing the UDID matched; a genuinely bogus id was still reported. - With a screen recording live on the Pixel 3a, a scoped teardown reaped `ScreenRecordingSession` and the **ffmpeg child actually exited** (1 → 0). Before the fix it survived to the 180 s cap while the tool called the correct serial a typo. The pre-change repros were re-run afterwards to confirm observed behavior changed, not just the tests. `npx vitest run` in `packages/tool-server` (295 files, 3154 tests) and `packages/argent-cli` (280), `tsc --build`, `tsc --noEmit` on both test projects, eslint and prettier — all green. ## Review notes Several rounds of review found real defects in this change; each was reproduced before fixing and re-verified after. Worth knowing when reading the diff, since the tests exist to pin them: - `flow-start-recording` truncated the `.yaml` outside any lock, so a step from the take being discarded landed in the freshly reset file and was reported as success (26-29 of 200 runs). - `flow-finish-recording` never took the lock; its `await fs.readFile` was a yield during which a concurrent append committed, leaving the reported summary disagreeing with disk (11-16 of 200). - A failed finish destroyed the recording. Hand-editing the `.yaml` mid-recording is a documented workflow, so `parseFlow` can legitimately throw — and the error told the agent to call `flow-start-recording`, which truncates the very take it would recover. - `unmatched` reported a device this session had just stopped, because `disposeService` returns a node to IDLE and keeps it. - A bare IP claimed every wireless-adb device at that address, since an adb serial is itself `ip:port`. - The eviction backstop stamped with `Date.now()`; ties at millisecond resolution let it drop the session that was just used. - `requireRecordingSession` ended with "Call flow-start-recording first" — reached for a key that was finished, superseded or evicted as well as one never started, and on those branches the file on disk is fully populated while that call truncates it and reports no `restarted`. - The atomic write regressed twice on its own terms: its scratch name was derived from the flow file's basename, which has no length cap, so a long flow name that appended fine before failed `ENAMETOOLONG`; and the cleanup guard began after the temp file was created, leaking a scratch file into a committed directory on any write that failed after opening. - Two tests passed against implementations they claimed to reject: the `stop-simulator-server` narrowness guard used a udid that classifies as *android*, where the iOS-only services it guards can never appear, so widening the iOS branch kept it green; and the client-mode finish asserted only the *shape* of `savedTo`, never its content, though that directive is the only thing that lands the file in client mode. ## Notes for reviewers - Client/remote persist mode is the least-exercised path, and now has its own concurrency tests (overlapping appends, and a restart superseding an in-flight one) — it previously had none. The `project_root` key is byte-stable across the file boundary (`kind: "probe"` passes it through unchanged), which is what keeps a remote recording addressable from `flow-add-step`, which declares no file input. - Two spellings of one flow file still mint two sessions — and two independent locks — over one file, which bypasses every guarantee here. Two ways in: the root spelled two ways (a symlink, or a case variant on APFS), and the likelier one, the *name* cased two ways on a case-insensitive volume. Neither is normalized away because the correct normalization is the filesystem's: case-folding the key would wrongly merge two distinct flows on ext4, and resolving symlinks is impossible in client mode, where the root does not exist on this host. Documented at `getFlowPath`. - No recording tool can detect that another agent took its key. `flow-add-step`, `flow-add-echo` and `flow-finish-recording` all re-resolve the key on every call, so after a takeover they act on whichever take is now live and report success: an append lands in the other agent's file, and a finish finishes and clears it. The only case that fails loudly is the narrow one the liveness check covers - an append already IN FLIGHT when the restart lands. There is no caller identity to key ownership on (see the rejected alternatives above), so this is spelled out for the agent under "Pick a name unique to your task" in `argent-create-flow` rather than mechanized. - Skew hazard in one direction only: a *new* client against an *older* tool-server. Zod strips the undeclared `name`/`project_root`, and the old server falls back to its module globals — so concurrent recordings silently collapse onto one session. The other direction (released 0.17.0 CLI against this server) was verified end-to-end. - `packages/argent-private/docs/reference.md` still describes `flow-add-step` as appending to "the current recording", and names two tool ids that do not exist (`flow-insert-echo`/`flow-run` are file names; the ids are `flow-add-echo`/`flow-execute`). It is a submodule, so the fix cannot ride on this branch. - A restart reported `discardedSteps` from the superseded session's in-memory flow while it truncates the *file*. Hand-editing the `.yaml` mid-recording is documented, so the two diverge: four steps wiped, one reported. It now counts the file, and reports no number at all when that file cannot be read or parsed - 0 is the answer a genuinely empty take gives. Client mode still counts from memory (this host cannot see the client's file), and the description now says which mode it is promising. - `ChromiumJsRuntimeDebugger` cascades from `ChromiumCdp` and was therefore already being torn down - silently, while `NetworkInspector` and `ReactProfilerSession` cascade the same way and were named. `stopped` is documented as the services that were live and got shut down, so it is listed now too. - The client-mode case named for a superseded in-flight append restarted *between* calls, so the next append re-resolved the key and succeeded - the guard was never reached, and neutering it left the whole file green. It now parks an append in its live sub-tool call across the restart. - `stop-tools.test.ts`' mock handed the tool the live service map where the real `getSnapshot` copies, so a cascade rewrote the state the sweep was still reading and the answer depended on map insertion order. The mock copies and recurses like `_teardown` now, and the cascade case runs under both orders. - Prose the code contradicted, each verified against source before rewriting: Vega owns `JsRuntimeDebugger`/`NetworkInspector` once the debugger has run (and can match anything at all through an ERROR node); "nothing here cascades" was denied twice in its own file; an iOS boot/launch/describe session owns `NativeDevtools` too; `:tcp` is mintable but unreached in production; the tool-server is a singleton *per install bundle*, not per machine; `argent flow list` does enumerate `.argent/flows`; the stop-tools comments narrated a "before" that only existed on this branch. Found while verifying, out of scope, worth their own issues: a `tool: flow-execute` self-reference recurses past both cycle guards (`run:` is guarded, a nested `flow-execute` reseeds the stack); react-profiler artifacts collide host-wide on a second-resolution filename; `stop-metro` is port-scoped and kills another agent's bundler; `debugger-reload-metro`'s HTTP fallback broadcasts to every attached client. A tool's `capability` is enforced only by the HTTP layer, not by `registry.invokeTool`, so a call that reaches the registry another way - `flow-add-step` takes `command` as a bare string - can resolve a service the tool declares it does not support, leaving an ERROR node behind (e.g. `SimulatorServer:<vega serial>`). --------- Co-authored-by: Hubert Gancarczyk <claude-hubert.gancarczyk@swmansion.com>	2026-08-10 10:54:58 +02:00
Jakub Piasecki	6d907cc86b	feat(flow): boot a Chromium instance per launch step (#585) ... A `launch:` on Chromium now starts its own Electron instance, so nested e2e flows and mid-flow relaunches work as they do on iOS/Android. Previously the runner booted one app per run and rejected any second chromium launch. A chromium device id _is_ its CDP port, so a launch that starts an app from scratch has to boot one and move the run onto it: `state.device` became reassignable (steps already read it per call), and `state.owned` tracks what the runner booted, torn down in reverse at run end. An instance the runner did not boot — pinned via `--device`, or auto-detected — is attached to, never killed. Relaunching the same app kills its instance and waits for the process to actually exit, or the replacement loses a race against the app's single-instance lock. The runner needs a device before step 1, so `resolveRunDevice` follows a leading `run:` chain to find the launch the run _begins_ with: a fragment composing a chromium e2e flow now boots instead of failing with "No booted chromium device found". A launch declaring no app id for the run's platform stays an error — the run's platform is fixed start to finish. Also fixes a pre-existing teardown leak: the spawned handle is the npm `electron` node wrapper, not Electron, so signalling it left the app and its helpers running (reparented to launchd, still in the dock). Teardown now sweeps the child's process group. **Behavior change:** a fragment leading with `run:` into a chromium e2e flow now boots a fresh instance where it previously attached to a running one; pass `--device` to keep attaching. ## Tests Cover the boot/attach/settle three-way, teardown ordering and the group sweep, device rebinding after a nested launch, same-app retire ordering, cancellation mid-boot, both "no chromium app declared" guards, and the leading-`run:` chain (multi-hop, cyclic, no-launch). The guard, exit-wait and sweep tests are mutation-checked.	2026-08-06 07:28:27 +02:00
Jakub Piasecki	22033e1418	feat(flow): allow to run every flow in a directory from flow run (#576) ... `argent flow run` now accepts a directory and runs every flow in it sequentially: ``` argent flow run .argent/flows --recursive ``` Discovery uses the same acceptance rules as `flow list` (lowercase `.yaml`, safe stem, readable file), sorted for a deterministic run order. `-r`/`--recursive` walks subdirectories too, skipping dot-directories and `node_modules` and never following directory symlinks. A directory named `foo.yaml` still batches (stat wins over extension). Batch output is failures-only: each flow prints a `[i/n] <path>` header, its failing/errored steps — numbered exactly as a single-mode rerun would number them — and a per-flow summary; the run ends with a `PASS/FAIL — N flows: X passed, Y failed, Z skipped` verdict. `--json` prints one aggregate object with per-flow reports. Exit code reflects the batch (0 pass, 1 any failure, 2 discovery/config errors). `--output` exports keep the single-run `<output>/<flow>/` layout, keyed by subdirectory in recursive runs so same-stem flows in different directories can't clobber each other's snapshots. **Failure semantics:** a flow failing its steps — or one the tool-server rejects as invalid (bad YAML, unparseable step) — fails alone and the batch continues. An infra error (transport death, unclassified failure) stops the batch and counts the remaining flows skipped. To make that distinction possible, tool-error responses now carry the server's failure signal (`error_code`/`error_kind`) on the wire — on the streaming terminal error line and on JSON error bodies — and the tools client surfaces server-answered errors as a typed `ToolInvocationError`. Against a pre-signal server this degrades to stopping on any throw. Not breaking: single-file runs behave exactly as before.	2026-08-05 14:51:42 +02:00
Jakub Piasecki	a644d52d39	feat(flows): run CLI flows from explicit paths (#568) ... `argent flow run` now takes an explicit YAML path instead of a saved-flow name: ``` argent flow run .argent/flows/checkout.yaml --platform ios ``` The path may point anywhere on the local filesystem; the filename stem names the run's report/artifacts, so it must be `[A-Za-z0-9_-]+` with a lowercase `.yaml` extension. A bare name fails with the exact replacement command, and `argent flow list` prints paths instead of names. Because sibling `run:` files and `__baselines__` resolve beside the YAML, the CLI now requires the auto-started local tool server and refuses `ARGENT_TOOLS_URL` / `argent link` routing. The `flow-execute` tool stays remotely callable via `name` + `project_root`, and gains a `flow_path` parameter (exactly one of `name`/`flow_path`) that is only honored when the file-input boundary verified it as a real host path — uploads and boundary bypasses are rejected, so it can't execute arbitrary server YAML. Also: the flow-name pattern is now a single shared export from `@argent/registry`, and the recorder composes a `flow_path` call into a `run:` step when it targets a sibling of the recording.	2026-08-05 14:51:42 +02:00
filip131311	19782f4e1a	feat(secrets): resolve {{secret:…}} from .env files, not just the environment (#734) ... ## Why A credential could only reach a typing tool through an `ARGENT_SECRET_<NAME>` environment variable. That is the right CI contract — and stays the highest-priority source — but interactively it is poor ergonomics: an editor-hosted tool-server inherits the environment its editor was launched with, so changing a credential means restarting the editor, and there is nowhere to write one down that survives a reboot. "Is loading these from a `.env` file on the roadmap?" is the recurring ask. ## What `{{secret:NAME}}` now resolves through an ordered chain, first match wins, re-read on every resolution — so editing a file applies to the next keystroke with **no server restart** (the same runtime-read design `ios.additionalDeviceSets` already uses). | # | Source | Which keys it exposes | | - | ------ | --------------------- | | 1 | `ARGENT_SECRET_<NAME>` in the environment | prefixed variables only — unchanged, still wins | | 2 | `<project>/.argent/secrets.env` | every key (gitignore it) | | 3 | `<project>/.env.local`, then `<project>/.env` | **only `ARGENT_SECRET_`-prefixed keys** | | 4 | `~/.argent/secrets.env` | every key, any project | Covers `keyboard`, `paste`, `run-sequence` keyboard steps, and flow `type:` steps — all four already funnel through the same resolution point, so nothing else changed. Also adds `argent secrets [list] [--json]` so a setup is verifiable without an agent: names only, never values, shadowed names marked, and a warning when a linked remote tool-server means resolution happens on a different machine. ## The one design decision worth reviewing **Row 3 is why this isn't just "read the `.env`".** An agent composes the tool call, so anything reachable through `{{secret:…}}` is exfiltratable by a prompt-injected one — type it into a field, then read the field back. "Which values may argent type" has to stay an allowlist the user wrote deliberately. So: a *dedicated* argent secrets file exists for no other purpose and therefore **is** the allowlist; a file the app *shares* keeps the prefix as the allowlist, exactly as the process environment does. Your `STRIPE_SECRET_KEY` sitting in the same `.env` stays unreachable — verified live, not just asserted. Adding `ARGENT_SECRET_` to one line is the deliberate act that exposes it. Two smaller calls, both reversible: - The chain lives in `@argent/configuration-core`, not the tool-server, so the CLI reads the same code; the tool-server keeps only the placeholder engine. - The project scope is discovered by the **cwd walk-up every other project-scoped configuration uses**. A per-request project root (header → `ToolContext`) was considered and rejected as new protocol surface across two client paths; reusing flows' module-global `setActiveProjectRoot` was rejected as a cross-project leak on a reused server. The cost is that a tool-server whose cwd sits outside the project skips project files — mitigated by the failure now listing every path it consulted, and by `~/.argent/secrets.env` needing no project at all. ## Verification Unit + integration: tool-server 3122, configuration-core 122 (19 new), argent-cli 370 (6 new). Lint and prettier clean. All four publish bundles build. Live, driving this branch's tool-server on :3001 against iPhone 17 Pro / iOS 26.4 and the Electron testbed: - global `~/.argent/secrets.env` → typed correctly; the response echoed only the placeholder - prefixed key in the project `.env` → typed; **unprefixed `STRIPE_SECRET_KEY` in that same file → rejected** - `.argent/secrets.env` beat `.env`; the environment variable beat both - edited a secrets file mid-session → applied on the very next call, same server pid - a chromium flow with `type: { text: "{{secret:APP_PASSWORD}}" }` → 3/3 pass, asserting on the greeting the app rendered, so the *correct value* provably landed - an undefined name inside a flow surfaces the full source list in the step report Sample of the failure output (no value ever appears): ``` Unknown secret "LOGIN_PASSWORD" — no source on the machine running the tool-server defines LOGIN_PASSWORD. Available secrets: APP_USER. Sources consulted, first match wins: 1. environment (ARGENT_SECRET_*) — 0 secrets 2. /path/to/project/.argent/secrets.env — found, 1 secret 3. /path/to/project/.env.local — not found 4. /path/to/project/.env — found, 1 secret 5. /Users/me/.argent/secrets.env — not found To make it available, ask the user to add `LOGIN_PASSWORD=…` to … ``` ## Out of scope No general flow variable/parameter system — a non-secret external value (a test account's email, a staging tenant id) can use the same placeholder, but argent treats every such value as a secret: redacted from errors, never echoed, so it is not for something a report should show. No config key pointing at an arbitrary secrets file. Remote (`argent link`) still resolves on the remote host, which the CLI now says out loud.	2026-08-04 15:23:12 +02:00
filip131311	2278115028	fix(flow): run a device-less flow without a device, and say why its counts are zero (#649) ... Fixes #644. ## Before ``` $ argent flow run echo-only # .argent/flows/echo-only.yaml: two `echo` steps [Tool:flow-execute] No booted device found. Pass a device id or platform explicitly. Available devices: 18BE573F-… (ios, Shutdown), <70 more> ``` and when a device *was* booted: ``` PASS on 18BE573F-… — 0 passed, 0 failed, 0 errored, 0 skipped ``` ## After ``` $ argent flow run echo-only # nothing booted Flow "echo-only" › first step › second step PASS — 0 passed, 0 failed, 0 errored, 0 skipped (no test steps) ``` ## Symptom 1 — the device Whether a device is needed is decided from the flow's own steps, before resolution. Classification is **per step kind and defaults to needing one**, so a kind added later inherits today's behaviour instead of silently running against no device — and the `never` binding makes leaving a new kind unclassified a compile error, backed by a test keyed on the step union so it fails to build rather than to run. Two classifications worth calling out: - **`when` always needs a device**, whatever its body contains, because the guard reads one itself (its platform, or its view tree). A `when: {platform: ios}` block containing only narration still resolves. - **`run` needs one without the fragment being read here.** The named flow is resolved at run time; resolving it a second time would duplicate that lookup and could disagree with it if the file changed in between. A deliberate over-approximation: composing a narration-only fragment still resolves a device. Stated in the code and in the tool description. For `tool:` steps the tool's own schema decides, via a superset of the keys the runner injects — `device` is included because a nested `flow-execute` step drives a device without being handed the run's own. A tool that declares no input at all (`stop-all-simulator-servers`) is device-free, and reading its absent schema must not throw — it previously would have. `ExecState.device` is nullable, which is the safety mechanism rather than just typing: the compiler enumerates every site that acts on a device, each of which now says so via one `deviceEnv()` narrowing. `flow-actions.ts`, `flow-visual.ts` and `ActionEnv` are untouched. The executor also re-checks each step against the **same predicate**, so if the scan and the executor ever disagree the step reports it instead of failing obscurely deeper in. A run that resolved no device reports `device: ""`, and neither renderer claims it ran somewhere. ## Symptom 2 — the counters Reproducing this showed the issue's framing is slightly off: `--json` doesn't only disagree with the text, it disagrees with **itself** — counters all zero while its own `steps[]` marks both steps `"pass"`. So the CLI text was a faithful rendering of the server's counters. **The counters are right and stay as they are.** Narration is deliberately excluded, and it should be: after a hard stop every remaining step *including narration* is reported skipped, so counting it would inflate `skipped` on every real failing run — a worse and far more common lie than the vacuous one being reported here. It would also contradict the JUnit model in #578, where echo is `<system-out>` and not a `<testcase>`. What was missing was saying *why* zero. Both the CLI and the MCP renderer now append `(no test steps)`, and only on a pass — a cancelled run can be a FAIL with all four counters zero, where "no test steps" would read as though the failure had no cause. No wire format changes: `steps[].kind === "echo"` already distinguishes counted from uncounted steps, so the JSON is self-describing without widening the status enum. ## Conflicts, for whoever lands second This is a hot area — seven open PRs touch `flow-run.ts`. - **#578** rewrites the CLI summary line I also change (one hunk, one 7-line function, semantically independent — resolution is keep-both), and its `attachFailureDiagnostics` dereferences `env.device.platform`. **It will need a null-device guard**, or every failure in a device-less flow silently degrades to `read-failed` diagnostics. Happy to rebase onto it rather than the reverse. - **#585** rewrites `resolveRunDevice` at the same seam and edits the same description sentence. - **#538** rewrites `flow-device.ts`. Worth noting it makes `resolveFlowDevice` reject a physical iPhone for flows — skipping resolution means a narration-only flow now passes on a physical-iPhone-only host, which I think is desirable but is a second behaviour change on this seam. All new tests are in new files, since every existing flow test file in the blast radius is rewritten by an open PR. ## Behaviour changes a reviewer should weigh - A device-free flow no longer prints `PASS on <id>` **even when a device is booted**. That is the point: otherwise an identical flow reports differently in CI (no simulator) than on a laptop with one open. An explicit `--device` is still honoured and still named. - `--platform` is ignored for a device-free flow, where it previously errored with nothing booted. - A 0.18.1 CLI against a newer server would print `Flow "x" on ` — cosmetic version skew. ## Verification Live against the built CLI: device-less flow with nothing booted (the reported bug) and with a device booted (identical output, no ambient attribution); `--json` showing `device: ""`; explicit `--device` still naming it; a mixed flow and a composed flow both still demanding a device; a mixed flow with a device booted still reporting `PASS on <id> — 1 passed`. 24 new tests. tool-server 3103 passed, CLI 284 passed, MCP 78 passed — no existing test modified. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- > **#697 is stacked on this branch** — it conflicts with this one in `flow-run.ts`'s import block, so it was rebased on top. Merge this first.	2026-08-03 16:14:30 +02:00
filip131311	81de9f66a6	fix(config): say what a rejected value should have been, and prune the group it left behind (#650) ... Fixes #643. ## Before / after ``` $ argent config set ios.additionalDeviceSets "~/Library/Developer/Radon/Devices" --scope project Error: Invalid value for config key "ios.additionalDeviceSets". # ← the whole message ``` ``` $ argent config set ios.additionalDeviceSets "~/Library/Developer/Radon/Devices" --scope project Error: Invalid value for config key "ios.additionalDeviceSets": expected an array of strings. Did you mean: argent config set ios.additionalDeviceSets '["~/Library/Developer/Radon/Devices"]' --scope project Run `argent config list` to see each key's expected value. ``` ``` $ argent config unset ios.additionalDeviceSets --scope project $ cat .argent/config.json { "ios": {} } → {} ``` ## Symptom 1 — the message The issue names three gaps: no expected type, no example, no pointer to `config list`. All three are closed, plus one the issue didn't ask for and I think is the actual fix. **The suggestion carries the user's own value.** A generic `Example: … '["~/DeviceSets/ci"]'` would hand someone a path they have never heard of and expect them to spot the difference. Where the correction is mechanical — a single item offered to a list-valued key — the error offers back what they typed, wrapped, shell-quoted, and **on the scope they asked for**. Pasting it works; verified live that it lands in project scope, not global. Nothing is coerced. The issue floated accepting a bare string and storing it wrapped; I didn't, because `config set` persists, gets committed, and is read by other machines, so a value silently stored in a shape the user didn't type is expensive to debug and `coerceCliValue` already has one silent fallback. Showing the corrected command costs the user one keystroke and keeps the store honest. If a reviewer prefers coercion, this is the smaller change to build on. **The expected shape comes from the validator, not a per-key string** — `asStringArray` *is* "an array of strings", so swapping a key's `parse` swaps its description with it and the two cannot drift. A bespoke validator can override via a new optional `expected`, and degrades to today's exact message if it says nothing. **`config list` states it too.** The issue notes `list` doesn't close the gap either — its description describes the *elements* but never says the value is a list. It now shows `value: an array of strings, e.g. ["~/DeviceSets/ci"]`, and `list --json` carries both fields. `telemetry.enabled` deliberately gets no example: `setConfigValue` refuses it before validating (it's managed by `argent telemetry`), so a "here's how to set it" hint would point at a command you may not run. A schema guard test keeps that honest as keys are added — and asserts every example **actually round-trips through its own validator**, so an example can never ship that reproduces the error it exists to fix. ## Symptom 2 — the empty group Deleting a key now removes any container the delete emptied, stopping at the first ancestor that still holds something. **This is file hygiene, not a behaviour change.** I traced every raw reader of the document — `readConfigObject`, and telemetry's `consent.ts` and `notice.ts`, which each do their own read — and an empty parent is already indistinguishable from an absent one: `getAtPath` returns `undefined` either way, before `parse`, so the merge layer never sees a container at all. The only observable difference is the bytes on disk, which is exactly the complaint. Guards worth noting: - **The root always survives** — an emptied config is `{}`, never a deleted file. `.argent/` is itself a project-root marker, so removing the file wouldn't restore the prior state anyway, and `updateConfig` is a shared publish path with a lock/rename protocol that has no defined meaning for file removal. - **A no-op unset still doesn't touch the file.** That fast path exists so an unset that removes nothing can't materialise a project config and dirty git status; pruning lives inside the mutate callback, which the fast path returns before reaching. So a group someone deliberately left empty by hand is never tidied away — pinned by a test asserting the file stays byte-identical. - Siblings at any level stop the unwind, including an empty array value, which is preserved. **Two existing tests asserted the old behaviour and now assert the new one** — `config-access.test.ts:47` and `config.test.ts:109` (the latter is `clearRememberedAgent`'s sibling-preservation test, so it doubles as proof siblings survive). ## Known same-class case, not fixed here `resetFirstRunNotice` (`packages/telemetry/src/notice.ts`) does its own inline delete and still leaves `{"notices":{}}`. It doesn't go through `deleteAtPath`, so it doesn't inherit this. It's a one-line change to route it through the same function — happy to do it here or as a follow-up, but it pulls the telemetry package into a config PR so I left it out by default. ## Verification Live against the built CLI: the reported case; pasting the suggestion back and confirming it lands in **project** scope; unset leaving `{}`; a sibling key surviving; a non-array key correctly getting the generic example and *no* bogus "Did you mean"; `config list` output; `telemetry.enabled` still delegating unchanged. configuration-core 103 passed, argent-cli 285 passed. 🤖 Generated with [Claude Code](https://claude.com/claude-code)	2026-08-03 14:56:40 +02:00
filip131311	3fff176a32	fix(cli): let a boolean flag take the value you typed (#699) ... Fixes #586. ## The bug `--includeChildren false` left the flag **true** and silently dropped the word, so the tool ran with the opposite of what was asked. The reporter spent a while chasing a filter bug that did not exist — the output was simply the unfiltered kind. Reproduced on 0.18.1, device-free, with a discriminator that shows the flag's value directly: ``` $ argent run screenshot-diff --udid U --baselinePath A.png --currentPath B.png --captureCurrent=false { "summary": "Screenshot diff summary … pixel_mismatch: 1.79% …" <-- false, diff runs $ argent run screenshot-diff --udid U --baselinePath A.png --currentPath B.png --captureCurrent false [Tool:screenshot-diff] Provide either currentPath or captureCurrent, not both. <-- stayed TRUE ``` That message is the whole problem in one line: the user typed `false`, and the tool refuses on the grounds that they asked to capture. ## Why the old behaviour existed, and why it does not need to The parser deliberately declined to look ahead: > `// Bare boolean flag: true. Don't consume next argv to avoid surprising behavior when a positional follows.` That protects a case which does not exist. `parseFlags` has exactly one caller, and **`positional` is never read anywhere in the repo** — every bare token is collected and dropped, for booleans and for every other type. There is no positional to steal. The module header had documented the space form as legal all along: ``` // --name value (string / number / integer / boolean-with-value) ``` This matters because several tool booleans **default to true**, so `false` is the only way to say what you mean: `screenshot.includeImageInContext`, `network-request.includeBody`, `debugger-component-tree.onScreenOnly`, `debugger-inspect-element.resolveSourceMaps`. ## What changed A boolean flag consumes a following token when it is exactly the word `true`/`false`, case-insensitively. `1`/`0` and everything else are left alone — a bare number after a switch is more likely an unrelated argument than a value, and guessing at an ambiguous token is what caused this bug. `--flag -- false` still keeps the word positional. Three consequences are handled here rather than left to bite later: - **`argent run` now reports arguments it ignored.** This is what stops `--flag 0` and `--flag yes` being the same silent inversion, in a syntax users are now being taught works. stderr, so `--json` stays parseable. - **`--no-flag true` / `--no-flag false` now name the positive form** instead of quietly meaning false. One is a contradiction, the other a double negative. - **`--flag=True` used to throw** while `--flag True` would now work — the inline coercion was case-sensitive and did not trim. Both paths now share one helper, so a single word cannot get two answers one function apart. The **flow** and **lens** parsers take switches that accept no value at all, and would have silently ignored the syntax their users just learned elsewhere. They now refuse it — in the flow parser that also stops `false` being swallowed as the flow name, since its first bare token is the flow to run. `--help` gains **one legend line** for tools with a boolean field, rather than widening the flag column on every field of every tool: ``` Booleans: --flag or --flag true sets true; --flag false, --flag=false, or --no-flag sets false. ``` It deliberately does not begin with `--`. `scripts/e2e-full/lib/discover-tools.sh` reads any such line in the `Flags:` section as a flag row and takes the first `--token` as its name, so a legend starting with a flag would inject a phantom flag into every tool model it builds. **There is a test pinning that shape**, verified live: running the harness's awk over the new help output yields exactly the real flags and no legend row. ## Verified live ``` --captureCurrent false -> diff runs (was: "Provide either currentPath or captureCurrent, not both.") --captureCurrent=false -> unchanged --captureCurrent 0 -> "Note: ignoring unused argument(s): 0. Pass values as --flag <value> or --flag=<value>." screenshot --help -> legend present; harness awk parses only the real flags ``` 25 new tests; 8 confirmed to fail before and pass after. The rest pin what deliberately did *not* change: bare flag still true, a following flag or non-boolean word left alone, `1`/`0` still positional in the space form, `--` escape, string and unknown fields untouched, `--no-flag` semantics, boolean arrays, last-write-wins. The parser had **zero** boolean coverage before — which is why this survived. Full CLI suite 298 passing; lint, prettier and `typecheck:tests` clean. ## Scope and neighbours Only `flag-parser.ts` (the schema-driven parser for `argent run`) changes semantics. The other CLI parsers take fixed, default-off switches where `false` has no coherent meaning; three of them already reject a stray token outright, and the two that did not now do. `flow.ts`'s deliberate rejection of `--flag=value` is untouched. **#648** also edits `flag-parser.ts` (rewrites `renderFlagName`, inserts helpers at the same anchor). Behaviourally compatible — it keeps boolean → bare `--name` — so this is a textual conflict only, and either order works. ## Found while here, not fixed `scripts/e2e-full/lib/discover-tools.sh:60-64` detects flag kinds with `\bboolean\b` in awk, where `\b` is **backspace**, not a word boundary — so it never matches and every non-enum flag is typed `unknown`. That makes the `bad-type` validation case downstream unreachable. Pre-existing and unrelated to this fix; filing separately. --- > **Stacked on #648** (`filip/run-cli-validation-messages`). Both rewrite the same region of `packages/argent-cli/src/flag-parser.ts` — #648 factors out `flagNameFor`/`isJsonField` and rewrites `renderFlagName`, this one adds `booleanWord` beside them and a boolean legend to `formatSchemaUsage`. Merging them independently conflicts; this branch is rebased on #648, so review only the top commit. GitHub retargets it to `main` when #648 merges. --------- Co-authored-by: Filip131311 <f.kaminski2000@gmail.com>	2026-08-03 12:18:11 +02:00
filip131311	a6f1bef632	fix(cli): stop argent mcp --help starting the server, and argent tools --help dumping the catalogue (#656) ... Fixes #638. ## The report understated it The issue says `argent mcp --help` "does not hang and does not start the server — it simply prints nothing". Reproducing it showed the opposite: ``` $ argent mcp --help < /dev/null ; echo $? 0 # 0 bytes ← what the reporter saw $ argent mcp --help # stdin open (a pipe, an editor, a CI step) # HANGS — I hit a 300s timeout ``` `--help` **starts the MCP stdio server**, which blocks reading JSON-RPC from stdin. The "prints nothing, exit 0" is just the server getting an immediate EOF from a closed stdin. So this is the same "`--help` runs the real command" bug that was fixed for the installers — `mcp` was missed. `startMcpServer` takes no argv at all (`mcp-server.ts:96` — its only parameter is `{ paths }`), so a help flag was *structurally* unreachable; there was nowhere downstream that could have handled it. ## Fix `mcp` joins the existing guarded set rather than growing a second help path. That set's defining property is "the handler never inspects its argv", and `mcp` qualifies more strongly than the installers do — it isn't merely ignoring `rest`, it is never handed it. **It cannot fire on a real launch.** The guard tests `rest`, which is `[]` for every generated editor config (all four shapes end at `mcp`, and `isArgentManagedEntry` requires exactly that), and `[].some(...)` evaluates no predicate. This is pinned in both directions, because a guard that *did* fire here would print usage onto the JSON-RPC channel and break every editor at handshake — the highest-cost regression in this file, and it was untested. The top-level table's `mcp` row now reads the same metadata as its own help, so the two cannot drift. **No rename.** An earlier draft renamed the module and six identifiers (`installer-help` → `command-help`, etc.) on the grounds that its comments had become false. They hadn't quite: fixing `mcp` *and* `tools` makes "every other subcommand parses `--help` itself" true again — I checked all ten siblings. Since #530 and #568 both edit `cli.ts`, a rename would have forced them through churn for no behavioural gain. Prose-only. ## Second commit: `argent tools --help` The issue mentions it in passing; it's a different mechanism and a genuinely dead branch. `argv.filter((a) => !a.startsWith("--"))` dropped `--help` before the subcommand was read, so it fell through to listing all 77 tools — **contacting the tool-server, starting one if none was running**, to do it. Only `-h` ever reached the existing help branch. Scoped to the subcommand position on purpose: a global check would have broken `argent tools describe <name> --help`, which today prints *that tool's* flags. It still does — there is a test. Separate commit so it can be reverted alone. ## Verification Live, against the built CLI: | | before | after | |---|---|---| | `mcp --help`, stdin open | hangs indefinitely | usage, returns immediately | | `mcp --help`, stdin closed | 0 bytes, exit 0 | 849 bytes of help, exit 0 | | `mcp` (real launch) | works | works — verified with an actual `initialize` handshake, server replies with its capabilities | | `mcp --metro-port 8082` | starts server | starts server (guard keys on help, not on "any argv") | | `tools --help` | 77-line catalogue | usage | | `tools describe gesture-tap --help` | tool's flags | tool's flags | | `argent --help` `mcp` row | — | byte-identical | argent 80 passed, argent-cli 284 passed. ## Note on the help text Every claim in it is sourced (stdio/JSON-RPC transport, stdout ownership, the `~/.argent/mcp-calls.log` default and `ARGENT_MCP_LOG` override, auto-spawn vs `ARGENT_TOOLS_URL`/`argent link`). It deliberately does **not** suggest running `argent mcp` by hand to check an install — that is the reported hang — and instead says it will look like it has hung and why. 🤖 Generated with [Claude Code](https://claude.com/claude-code)	2026-08-03 12:14:24 +02:00
filip131311	d08c3a3cfc	fix(cli): name the missing flag instead of printing a Zod dump (#648) ... Fixes #645. ## Before ``` $ argent run gesture-tap [ { "expected": "string", "code": "invalid_type", "path": ["udid"], "message": "Invalid input: expected string, received undefined" }, ... two more ] ``` ## After ``` $ argent run gesture-tap Error: missing required flags --udid, --x, --y argent run gesture-tap [flags] ...full per-flag help... ``` ## Scope The issue names the missing-flag case. Reproducing it showed the same raw dump has a second trigger: any constraint the tool itself rejects, which the CLI cannot know in advance. | invocation | before | after | |---|---|---| | `gesture-tap` (no flags) | raw issue array | `missing required flags --udid, --x, --y` | | `screenshot --scale 99` | raw issue array | `--scale Too big: expected number to be <=1` | | `gesture-scroll --udid X --x .5 --y .5` (zero deltas) | raw issue array | `Pass a non-zero deltaX and/or deltaY …` | | `run-sequence --udid X` | raw issue array | `missing required flag --steps-json` | | `gesture-tap --x abc` | already good | unchanged | | runtime failure | plain message, exit 1 | unchanged | Fixing only the first row would have left the CLI's error voice less predictable than before, so both go through the same renderer. ## How it works Two sources, one output. Missing flags are found locally from the tool's published schema — a **presence** check only, never a type or range judgement, which stays exclusively the server's. That is sound because the schema generator excludes defaulted fields from `required` (`debugger-connect` requires `device_id`, not `port`), so it cannot reject a call the server would have accepted. Everything else is read off the rejection the tool-server already returns. Both produce one report rendered by one function and reported through one call site, so the wording, the output channel and the exit code cannot drift between them. Recognition of a rejection is **structural** — the shape of the issue list plus the tool's own schema — never the wording of a message, which is not ours to depend on and changes between Zod releases. Four gates must all hold, and any failure leaves the existing handling untouched. Details worth a reviewer's attention: - **A rule spanning the whole payload reports no field.** `gesture-scroll` and `gesture-rotate` validate at the object level, and `screenshot-diff` is `.strict()`. Treating those as field-scoped would print `Error: --undefined …`; they are stated on their own instead. - **A rule firing on an *optional* field is not called a missing required flag.** `await-ui-element` refines on `expectedText`, which it does not require — reporting that as missing would contradict the help block printed directly underneath, where the field carries no `(required)` marker. - **The check runs after `--args` is merged**, so `argent run gesture-tap --args '{...}'` is not falsely reported as missing everything. Verified live: it reaches the device and taps. - Presence uses own-key semantics, so a required field named e.g. `constructor` is not treated as supplied by the prototype chain. ## Behaviour changes a reviewer should weigh - **A tool-rejected value now exits 2 instead of 1.** `run.ts` already uses 2 for bad input and 1 for a failed run; a Zod 400 means the tool never ran. No in-repo consumer tests for a specific code — `scripts/e2e-full` only checks zero/non-zero. Note this does **not** make 2 universal: an unknown tool name still exits 1, which is untouched here. - **`--json` gains a defined failure shape** (it had none — the blob printed regardless). One object on stderr, nothing on stdout, so `--json | jq` on a failed run reads an empty stream and a non-zero status: ```json { "error": "missing required flags --udid, --x, --y", "missing": ["--udid", "--x", "--y"], "issues": [] } ``` `issues` carries the tool's list verbatim, which is the raw data the issue asked to keep. - **One adjacent fix**, called out because it is not the reported bug: the global-option parse ran *outside* the error handler, so `argent run screenshot --out` printed a raw stack trace. Same bad-input-to-ugly-output defect, one line above the fix. ## Not done - The unknown-flag hole (`argent run gesture-tap --bogusflag 1` is silently accepted and the tool runs). The pass-through is deliberate — see the comment in `flag-parser.ts` — and belongs with #586, the same CLI-argument family. - `argent flow` builds its own payload and has its own required check; it cannot reach this path. - The server still returns the issue list verbatim, so MCP and other clients are unaffected. All prettifying is CLI-side. ## Verification Live against the built CLI for every row of the table above, plus: `debugger-connect` asks only for `--device_id` and never `--port`; `--args '{...}'` reaches the device and taps; a thrown runtime error still prints its bare message with no `Error:` prefix, no help block, exit 1. 43 new tests. `run-telemetry.test.ts` passes **unedited** — it already asserted the non-Zod passthrough, which makes it the regression guard for the untouched path. Full CLI suite 320 passed, registry 87 passed. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- > **#699 is stacked on this branch** — it conflicts with this one in `flag-parser.ts`, so it was rebased on top rather than left to collide at merge time. Merge this first.	2026-08-03 11:42:26 +02:00
filip131311	cccda92d15	feat(config): ios.additionalDeviceSets — additive array of extra CoreSimulator device sets (#542) ... ## Summary **Stacked on #534.** Adds the first *additive* configuration entry on the new schema — `ios.additionalDeviceSets`, a list of extra CoreSimulator device-set directories — delivering the config side of the #401 discussion on the #534 machinery. ### The schema entry One registry entry in `config-schema.ts`: - key `ios.additionalDeviceSets`, scopes `project` + `global`, `parse: asStringArray`, **`merge: "union"`** Unlike `lens.agent` (project *shadows* global), this is additive: the effective value is the **union of both scopes** — the global baseline first, the project's extras appended, deduplicated. A repo can commit the device sets its tooling needs to `.argent/config.json` and they *extend* (never replace) the user's global list. `argent config list/get/set/unset` handle the array key with zero command changes — arrays already round-trip through the JSON value coercion. ### The runtime reader `getAdditionalIosDeviceSets(options): string[]` in `config-access.ts` — the surface iOS tooling should call. It reads each scope separately so paths normalize against the base the author meant: - `~` / `~/…` expands to the home directory (honoring the sandbox `homeDir` override) - relative **project** entries resolve against the **project root**, relative **global** entries against **home** - output order matches the `union` preset (global first), with **post-normalization** duplicates dropped — `~/DeviceSets/ci` in global and its absolute spelling in the project file collapse to one entry - empty array when unset Support refactor: `resolveHomeDir()` extracted in `paths.ts` (the HOME/USERPROFILE + override logic previously inlined in `argentHomeDir`/`configDir`). ### Out of scope (follow-up) Actually pointing simctl at the extra sets. There is no central simctl wrapper today (~25 call sites build `xcrun simctl …` argv inline, and `ax-prefs.ts` hardcodes the default set's `CoreSimulator/Devices` path), so consuming this reader in `list-devices`/boot/etc. is its own change — the runtime-read-off-disk design here means that consumer needs no CLI/env threading, matching how #534's description framed the split. ## Testing - `configuration-core`: 5 new tests (82 total, green) — additive union across scopes + per-scope file isolation, non-array rejection + entry normalization, reader `~`/relative resolution per scope, post-normalization dedup, empty-when-unset - `argent-cli`: new real-filesystem CLI round-trip (274 total, green) — `config set` an array at each scope, effective `get` shows the union while `get --scope` shows only that scope's entries - `tsc` build + `typecheck:tests` + eslint clean on touched packages	2026-07-31 10:27:25 +02:00
Ignacy Łątka	2251c7cf46	feat(screen-recording): screen-recording-start/stop tools with per-call stop reminders (#517) ... ## What Adds a `screen-recording-start` / `screen-recording-stop` tool pair (naming follows `native-profiler-start/stop`) that records the device screen to an mp4 and returns it as a downloadable artifact. Capture runs through **simulator-server** — the same backend `screenshot` and every interaction tool already drive. simulator-server publishes the device screen as an MJPEG stream (`/stream.mjpeg`), so recording needs no platform-specific recorder: the tool-server subscribes to that stream, paces the frames onto a fixed 30 fps timeline, and pipes them into a single ffmpeg process that encodes — and watermarks — straight to the final mp4. The stream is multi-subscriber, so a preview window can stay open on the same device while recording. - **One path for every device simulator-server drives** — iOS simulators, Android emulators, and physical Android devices. - **Native resolution, constant 30 fps** — h264, `+faststart`, no post-processing pass. - Session state lives in a per-device `ScreenRecordingSession` blueprint (mirrors the native-profiler session): time-limit cap with auto-finalize, unexpected-exit recovery (a capture that ended on its own is still retrievable via stop), always-startable state reset on stop, and dispose-on-shutdown cleanup through the registry. ## Why the frames are paced host-side A device only emits a frame when the screen **changes**. Pointing ffmpeg straight at the stream therefore produces a video whose length is the sum of the moments something moved — a still screen collapses to a fraction of a second — and an ffmpeg blocked on a silent socket does not answer a stop signal promptly either (measured: 12 s late). Re-emitting the last frame on a wall-clock schedule fixes both: **video duration always equals real elapsed time**, and stop is a stdin EOF that finalizes in ~60 ms. Duplicate frames cost almost nothing once encoded (a 10 s recording of a static screen is ~1 MB). ## Finishing pass folded into capture The Argent watermark (logo + `By @swmansion`, bottom-left, sized relative to the frame) is stamped by the same ffmpeg invocation that encodes the capture, so there is no second encode and no temp intermediate. Its colour is chosen **per pixel** from the background luma underneath it — the white logo over dark areas, a runtime-derived near-black copy over light areas — so it keeps maximum contrast against whatever is behind it. It sits at 20 % opacity and is opt-out via `argent disable video-watermark` (read when the recording starts). Frame geometry comes from the first JPEG's SOF header, so no `ffprobe` is needed. ffmpeg is now the recorder rather than an optional finisher, so a missing ffmpeg fails `screen-recording-start` up front with an install hint instead of silently degrading the output at stop time. ## Reminder plumbing While a recording is running — or ended on its own but was never retrieved — **every** tool result carries a `note` telling the agent the recording is still going and how to stop it. It rides the same `note` field as the update reminder but is per-call and unsuppressed; both notes compose when they coincide. The note text switches to "already ended, retrieve the file" once the cap fires or the capture dies. ## Skill New `argent-screen-recording` skill (+ routing stanza in `rules/argent.md`): documents the start → interact → stop workflow and instructs the agent to schedule its own reminder/wakeup for the expected end of the recording immediately after starting one (harness reminder tool if available, otherwise a background `sleep` whose completion notification pulls it back). Scores 10/10 on `scripts/grade-skills.mjs`. ## Verification - Unit: 45 tests across `screen-recording.test.ts`, `mjpeg-stream.test.ts`, `watermark.test.ts`, `http-recording-note.test.ts`; full tool-server suite **2808 tests / 280 files green**; `tsc --noEmit -p tsconfig.test.json`, root `tsc --build`, eslint, prettier all clean. - E2E on a live tool-server (`POST /tools/...`), driving real interactions between start and stop: - **iOS sim** (iPhone 16 Pro Max, iOS 18.5): 1320×2868 h264, `r_frame_rate=30/1`, 338 frames, container duration 11.27 s vs reported `durationMs` 11314 — **within 50 ms of wall clock**. Extracted frames show real screen content (mid app-switcher animation) with the watermark rendered light-over-dark. - **Android emulator** (Pixel 3a, API 34): 1080×2220 h264, 30 fps, 353 frames, duration 11.77 s vs `durationMs` 11793 — within 30 ms. 512 KB for a mostly-static home screen. - **Static screen** (no interaction at all, 10 s): 300 frames, duration exactly 10.000 s — the case the previous `recordVideo` implementation reduced to ~0.03 s. - **Long silence then activity** (15 s untouched, then an app launch): stream survived, no warning, frames after the silence show the new screen. This caught a real bug during review — the connect timeout was also acting as a socket *inactivity* timeout and tore the stream down at 10 s of stillness; fixed and covered by a regression test that fails without the fix. - **Time-limit cap**: `timeLimitSeconds: 5` self-finalized at 4.97 s / 149 frames, the per-call note flipped to "already ended (it hit its 5s time limit)", and a stop issued 11 s later still returned the video with the matching warning. ## Not supported (capability-gated with clear errors) tvOS simulators, physical iPhones, Chromium apps, Vega, and remote (`remote:`-prefixed) simulators — none of them expose a readable frame stream. --------- Co-authored-by: Ignacy Łątka <claude-hubert.gancarczyk@swmansion.com>	2026-07-23 21:14:37 +02:00
filip131311	8d2a499eaf	Project-scope configuration with schema-driven merge + argent config (#534) ... ## Summary Adds a general, **scoped** configuration system on top of the shared `config.json`, plus a universal `argent config` command to manage it. Motivated by the discussion on #401 (iOS device set): config that needs to work naturally with the MCP server should be read off disk at runtime like telemetry consent is — not threaded through CLI flags/env and a kill-and-respawn dance. This lands the reusable machinery; the device-set becomes a one-line schema entry + a runtime reader on top of it. Four pieces, matching the requirements: ### 1. Project-scope config files `config.json` now resolves at two scopes: - `~/.argent/config.json` (**global**, default) - `<project-root>/.argent/config.json` (**project**, resolved by the same `.argent`/`.git`/`package.json` marker walk as feature flags) `configFilePath` / `readConfigObject` / `updateConfig` take an optional `scope` (default `global`), so **every existing caller is unchanged** (telemetry, notices, lens). Per-scope lock + atomic write are preserved. ### 2. Schema-driven merged reads `getConfigValue(def)` reads each scope the value's schema entry allows, merges them under the entry's policy, and falls back to the entry's default. This is the reader consumers should call instead of poking at a single global file. The existing **lens** getters (`getRememberedAgent` etc.) are migrated onto it as the first live consumer — a repo can now pin its lens agent, falling back to the user's global choice. ### 3. A registration file for configurations (`config-schema.ts`) Adding a configuration is a one-liner: `key`, `description`, allowed `scopes`, a `parse` validator, and a `merge` policy. Merge presets: - `prioritize-local` (project wins) · `prioritize-global` (global wins) - `prioritize-restrictive` (booleans/numbers — opt-out/stricter wins) - `union` / `intersection` (arrays) - …plus an escape hatch: pass your **own** `(inputs) => value` function for a bespoke rule. ### 4. `argent config` — one universal command `argent config <list | get | set | unset>` with `--scope global|project` and `--json`. New configs are added as **schema entries**, not new top-level `argent` commands, to avoid bloat. **Telemetry stays backward-compatible** on its dedicated `argent telemetry` command (which also drains/resets the live client). It's surfaced *read-only* under `argent config` via a `manageCommand` guard — so `argent config set telemetry.enabled` refuses and points at `argent telemetry`, and a committed project file can never re-enable a global opt-out (`prioritize-restrictive`, global-only). ## Testing - **Unit / integration**: 71 configuration-core tests (merge presets + custom fn, dotted-path + prototype-pollution guards, scope merge, scope/validation/manage-command errors, `listConfig`, `coerceCliValue`) and 11 real-filesystem CLI tests driving the actual `config()` entry point across sandboxed HOME + project cwd. Full suites green: configuration-core 71, argent-cli 268, telemetry 281, argent 60. - **Live, on the built binary** (`node packages/argent/dist/cli.js …`): set global + project (from a deep subdir) → effective get returns the project value; per-scope gets return each file; both files land in the right place; `argent telemetry disable/enable` writes `config.json` and `argent config get telemetry.enabled` reflects it read-only; unknown-key / invalid-value / bad-scope errors exit non-zero with hints. - `tsc --build` across the workspace, prettier, and eslint (`--max-warnings 0`) all clean. ## Notes / follow-ups - Config-file reads are not yet fingerprint-cached the way telemetry's consent read is; a long-lived tool-server re-reads on each `getConfigValue`. Fine for CLI/low-frequency use; a hot runtime consumer (e.g. a future device-set reader) may want the same mtime/inode cache.	2026-07-22 12:47:42 +02:00
Jakub Piasecki	a0d1bbb1e7	feat(flow): indent nested steps in reports by block depth (#524) ... Flow reports rendered every step flat, hiding which steps ran inside a `when:` block or a `run:` fragment. The tool-server now stamps `StepReport.depth` (+1 per block directive, omitted at top level) and the CLI/MCP renderers indent step labels and under-step lines by it: ``` ✓ 1 launch ✓ 2 when visible "What's new" — condition met ✓ 3 tap "Skip" ✓ 4 run dismiss [dismiss] ✓ 5 tap "OK" [dismiss] ``` Invariants: - **Wire-compatible both ways** — a flow with no block directives reports byte-identical to the pre-depth shape; a pre-depth server renders flat as before. - **Skipped ≡ entered** — skipped/errored/aborted blocks report the same depths as entered ones, keeping reports comparable run-to-run. - **Untrusted wire data** — renderers clamp depth (display cap, not a producer bound): hostile values render flat or at the cap, never throw or allocate huge strings. Also fixes a pre-existing bug: under-step warning/artifact lines now stay aligned past 99 steps. Tests pin depth on every producer path (entered/skipped/errored/aborted blocks, `run:` success/failure markers, `run:`-in-`when:`) and renderer alignment incl. the clamp boundary. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-07-21 07:28:48 +02:00
Jakub Piasecki	3f602a7a9b	feat(flow): conditional when blocks (#498) ... ## What A `when:` block runs a step list only when one condition holds — a UI condition (`exists`/`visible`/`hidden`/`text`, the await/assert shapes) or a static `platform` test. **No else**, by design: a block exists to restore determinism (dismiss an interstitial, reconverge), never to test two paths. Tap-if-present is a one-step block: `when: { visible: "Got it" }` + `steps: [tap: "Got it"]`. No per-step `optional:` — `when:` covers every directive once. The key is rejected at parse with a pointer to `when:`, not silently dropped (a Maestro habit that would leave a "can't fail" step hard-stopping the flow). ## How - The guard reuses the assert engine at the 1s grace (`timeout` is a parse error), so a skipped block barely costs a clean run. - Verdicts are evidence-based: no trustworthy read in the window → indeterminate → the step **errors** ("could not evaluate" is not "condition false"); a transient read failure after trusted reads showed the condition false stays a clean skip. - `platform` folds `ios-remote` into `ios` — the parser rejects that spelling, so the fold is the only way a guard matches a remote sim. - A skipped block reports one line per authored step, same shape for unmet guard, hard stop, or cancellation; everything goes through `pushReport`, so when lines stream live. Failures inside an entered block hard-stop as usual. - Results carry an explicit `aborted` flag; `ok` keys off fail/error/cancel, not skip lines. - Nesting is capped at 20, so a cyclic YAML alias is a structured parse error, not a stack overflow. ## Testing `vitest` 2546 pass (17 when-specific); `tsc --noEmit` (tool-server, argent-mcp, argent-cli), eslint, prettier clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-07-20 10:26:34 +02:00
filip131311	07427917e2	fix(launcher,lens): drop the npm postinstall — its jobs move to runtime (#510) ... ## Why Shipping *any* `postinstall` makes pnpm 10+ wall the install behind its build gate: `ERR_PNPM_IGNORED_BUILDS`, `pnpm install` exits 1, and `pnpm exec argent` is unusable until the user runs `pnpm approve-builds` — their first experience of argent is a bricked CLI. The same script is also silently skipped by `--ignore-scripts`, Yarn PnP, and locked-down CI, so anything correctness-relevant in it was already unreliable (the codebase says as much in several places, e.g. `runTrustingDisk`). Live-verified during the 0.15.0 QA: with **all builds declined** in pnpm 11, argent installs, inits, and serves MCP fine — the postinstall was never load-bearing for install correctness. Removing it means pnpm users never see the approve-builds wall for argent itself. ## What the postinstall did, and where it went | Job | New home | |---|---| | SIGTERM a tool-server stranded by an upgrade that replaced its bundle dir (pnpm/yarn version-pinned layouts) | `sweepDeadStateFiles` in the launcher's slow path now retires **live** servers whose recorded bundle is gone from disk, with the same pid-identity guard as `killToolServerForInstallDir` (never signal a recycled pid; keep unidentifiable live records reachable for `server stop`). Same-bundle in-place bumps were already self-healed by the disk-authoritative version gate. | | `chmod +x` node-pty's macOS `spawn-helper` prebuilds (shipped without the exec bit; first `pty.spawn` otherwise fails `posix_spawnp`) | `ensureSpawnHelperExecutable()` in `lens-pty.ts`, run when the module loads, best-effort with the AppleScript fallback intact. | | Print the `argent init` hint | Dropped — init flows drive the install, and the hint never printed on pnpm/PnP anyway. | `ARGENT_SKIP_POSTINSTALL` in `update.ts` is kept deliberately: downgrades and pinned installs fetch older versions whose postinstall still exists and honors it. ## Testing - New `launcher-sweep.test.ts` (6 tests) exercises the sweep against **real processes**: live-server-with-deleted-bundle is terminated and its record unlinked; live server with intact bundle untouched; recycled-pid record kept, not signalled; dead-pid record unlinked; legacy slot untouched; a SIGTERM-trapping orphan doesn't hold the sweep (and the spawn lock above it) hostage for its kill grace window — the record is unlinked and the SIGKILL escalation runs in the background. - New `ensureSpawnHelperExecutable` tests (real fs, darwin-gated) verify the +x restore and silent failure; a regression test pins that `loadNodePty` tolerates req seams without `resolve`. - Full suites green in all touched packages: tools-client 154, installer 535, cli 248, mcp 76, argent 60. 🤖 Generated with [Claude Code](https://claude.com/claude-code)	2026-07-15 20:26:39 +02:00
Jakub Piasecki	551c781fb0	feat(flow): support running end-to-end flows without agent (#429) ... # Flow E2E This PR turns flows from replayable tool-call recordings into a declarative, portable e2e test system that runs headlessly via `argent flow run <name>` — no LLM in the loop, non-zero exit on failure, suitable for CI. Agents can still replay flows via `flow-execute` and get the full output from each step after it finishes. ## Flow format Flows are YAML files in `.argent/flows/`, now built from **directives** interpreted by the runner rather than raw tool calls: - `launch` — terminate + relaunch the app under test (per-platform app id map supported); its presence marks a flow as **e2e** (controls its own start state) vs. a **fragment** (runs against current state, declares an `executionPrerequisite`, composable via `run:` with cycle/depth guards). - `tap`, `type` (focus handshake + optional submit), `scroll-to` (momentum-free, increments by half the container, `within:` for nested scrollers), `await`/`assert` (`visible`/`exists`/`hidden`/`text` conditions), `wait`, `snapshot`, `echo`, and raw `tool:` as escape hatch — still fully supported, so previously recorded flows keep working unchanged. - **Selectors** are `{ text, identifier, role }`; a bare string is a loose selector resolving identifier-first, then visible text. Any directive failure hard-stops the flow; later steps report `skip`. ## Execution engine - Flows store no device id — the runner binds a device at replay (explicit `--device`/`--platform` or the single booted one). - Selector resolution runs against **platform-unified UI trees**: iOS native view hierarchy (full testID coverage, gated on native-devtools connecting), Android full accessibility hierarchy (full resource-id coverage), Chromium CDP DOM, and the Vega automation toolkit. A shared flatten/text-hoisting pass lets `text` assertions read what an identified container visibly shows. Vega is remote-driven, so touch directives fail with guidance to use `tv-remote`/`keyboard`. - Steps wait for the tree to **settle** (two consecutive identical reads) before acting; `launch` additionally gates on platform tree-source readiness instead of silently degrading. ## Visual snapshots `snapshot` diffs a full-resolution screenshot against baselines in `.argent/flows/__baselines__/<flow>/`, keyed by platform + resolution, with configurable `maxMismatch` and `--update-baselines`. The status bar is pinned for the whole run (iOS `simctl status_bar`, Android demo mode) so clocks/battery don't drive diffs. Baseline/current/diff images are returned as artifacts on failure (and the written baseline on first capture/update); a clean pass carries none, keeping reports and agent context lean. ## Recording The record-live workflow (`flow-start-recording` → `flow-add-step` → `flow-finish-recording`) now emits directives automatically: coordinate taps are rewritten to portable selector `tap:` steps (selector captured from the pre-tap tree), a leading `restart-app` becomes `launch:`, `flow-execute` of a sibling fragment becomes `run:`, and device ids are stripped. The skill instructs the agent to polish the saved YAML afterwards (fold tap+keyboard into `type:`, swipes-to-reach into `scroll-to:`, awaits into sugar form). ## Also included - `argent flow run` / `argent flow list` CLI with per-step report rendering, artifact materialization, and `--json` output. - New structured failure codes for flow validation, device resolution, composition, and devtools readiness. - Extensive unit test coverage (tree adapters, selector matching, scrolling, composition, type focus, snapshots, status bar).	2026-07-13 17:15:01 +02:00
Ignacy Łątka	c5bab2a83d	fix(cli): let a tool's own --args field win over the whole-payload flag (#458) ... ## Bug `argent run flow-add-step` declares its own `args` field — a JSON string holding the recorded step's tool arguments. But the CLI flag parser hardcoded `--args` as a whole-payload escape hatch, so `--args` shadowed the tool's own `args` field. The documented per-flag form ``` argent run flow-add-step --command gesture-tap --args '{"udid":"...","x":0.5,"y":0.5}' ``` silently dropped the step arguments: the `--args` JSON was consumed as the whole payload and the tool's `args` field stayed `undefined`, producing a misleading downstream validation error. Only the nested full-payload form worked. ## Fix Make `--args` schema-aware in `parseFlags()`: - When the tool's schema declares a property named `args` (`schema.properties.args`), `--args <value>` is routed through the normal per-field handling and coerced by its declared type (a `string` for flow-add-step, so the raw JSON string passes straight into the `args` field). Both `--args value` and `--args=value` forms are supported. - When the schema does NOT declare `args`, the existing whole-payload behavior is preserved exactly, including the `--args -` stdin sentinel. `printToolHelp()` no longer prints the global whole-payload `--args <json>` / `--args -` lines for tools that declare their own `args` field, so the help stops contradicting the per-field `--args` shown in the schema flags. The change is general: any tool with an `args` field benefits, with no special-casing by tool name. ## Verification - `npm run build` (root tsc) — clean. - `npm test -w @argent/cli` — 172 passed, including 6 new `parseFlags` cases covering schema-with-`args` (space-separated + inline forms, plus sibling fields) and schema-without-`args` (whole-payload preserved, `--args -` sentinel, no-schema fallback). - Prettier + ESLint (`--max-warnings 0`) clean on the touched files. Full CLI end-to-end (running `flow-add-step` against a live tool-server with an active flow recording) was not exercised here; the added unit tests prove the parser behavior. Fixes #452 --- ### CLI end-to-end verification Ran the documented per-flag form against a live tool-server with an active flow recording: - **Before (global argent 0.13.0):** `argent run flow-add-step --command gesture-tap --args '{"udid":"...","x":0.5,"y":0.35}'` → `Invalid params for tool "gesture-tap": udid expected string, received undefined ...` (args dropped). - **After (this branch):** same command → `{ "message": "Step added to \"colltest\" flow", "toolResult": { "tapped": true } }`, and the recorded YAML contains the step **with** its args (`udid`/`x`/`y`). The per-flag form now works as documented.	2026-07-07 13:37:09 +02:00
Ignacy Łątka	a7722df8a2	fix(cli): reject empty numeric flags and array/-json interleave crash (#432) ... Fixes two related defects in `packages/argent-cli/src/flag-parser.ts`, the argv-to-JSON flag parser used by `argent run`. The package previously had no dedicated test file for it; this PR adds one covering both fixes. ## Defect A: empty/whitespace numeric values coerced to 0 `coerceScalar` validates number/integer fields with `Number.isNaN` / `Number.isInteger`, but `Number("")` and `Number(" ")` both evaluate to `0`, so those guards pass. An empty or whitespace-only value was therefore silently accepted as `0` instead of being rejected. Reachable via `--x=` (empty inline), `--x ""`, and `--x " "`. - Observed: `parseFlags(["--x="], { type: "object", properties: { x: { type: "number" } } })` returned `{ x: 0 }`. - Expected: rejected, the same way a non-numeric string like `"abc"` already is. Fix: reject an empty or whitespace-only value up front for number/integer types, throwing the same `FlagParseException` the function already throws for `"abc"` (`--<flag> expected a number/integer, got "<raw>"`). Valid numbers are unaffected. ## Defect B: array + `-json` interleave throws a raw TypeError `seenArrayFields` is only populated by the array branch, but the `--field-json` escape hatch writes `args[fieldName]` directly and can set it to a non-array. If a field was already seen as an array, a later array-form occurrence ran `(args[flag] as unknown[]).push(...)` on a non-array value and threw a raw `TypeError`. `run.ts` only catches `FlagParseException` and re-throws anything else, so the user got an uncaught stack trace instead of a clean error. Repro: ``` parseFlags( ["--tags", "a", "--tags-json", '"b"', "--tags", "c"], { type: "object", properties: { tags: { type: "array", items: { type: "string" } } } } ) ``` - Observed: throws `TypeError: args[flag].push is not a function` (uncaught, surfaces as a stack trace through `run.ts`). - Expected: a clean validation error. Fix: in the array branch, when `args[flag]` is not actually an array (because `--field-json` replaced it), throw a `FlagParseException` explaining the `--field` and `--field-json` forms cannot be mixed for the same field, never a raw `TypeError`. ## Tests Adds `packages/argent-cli/test/flag-parser.test.ts`. The new tests fail before the fix (4 failures) and pass after; the full `argent-cli` suite stays green (90 passed). Behavior for valid inputs is unchanged.	2026-07-03 16:19:22 +02:00
Ignacy Łątka	a92c859d07	feat(argent-lens): argent lens — bind a claude session to the preview window (#416) ... ## 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>	2026-07-01 19:57:56 +02:00
Hubert Gancarczyk	8483fe23f9	feat: add telemetry (#274) ... ## Summary Adds anonymous, opt-out telemetry for Argent installer, update/uninstall flows, CLI telemetry controls, tool-server lifecycle, and tool invocation health signals. ## What Changed - Added a new private `@argent/telemetry` package - Introduced typed telemetry events with runtime property allowlisting/sanitization. - Added lazy anonymous identity creation in `~/.argent/telemetry-id`. - Added consent handling via: `argent telemetry enable`, `argent telemetry disable`, `argent telemetry status` - Added local debug logging with `ARGENT_TELEMETRY_DEBUG=1`. - Tracks installer funnel events for init, global install/update decisions, editor selection, allowlist decisions, skill installation, rules/agents copy, update, and uninstall. - Tracks tool-server start/stop and tool invocation/complete/fail events. - Adds per-tool invocation IDs so request metadata can be correlated without relying on ordering. - Records only coarse platform metadata (`ios` / `android`) for device tools - Ensures short-lived commands drain telemetry with bounded shutdown before exit. - Wires telemetry package into bundling and injects full Argent CLI version metadata at build time. - Added central `FAILURE_CODES` and `FailureSignal` helpers in `@argent/registry`. - Attached structured, sanitized failure metadata across registry errors, tool-server tools/services, HTTP validation/dependency gates, installer flows, and `argent run`. - Added telemetry allowlisting for safe failure fields only: static error codes/stages, coarse area/kind/command, bounded exit codes, allowlisted signals/spawn codes, and coarse network failure classes. - Split CLI-local `argent run` failures into `cli:run_fail` so they are not double-counted as tool failures. - Added installer telemetry for failed package actions, update/uninstall failures, rules/agents copy results, and skill refresh results. - Made telemetry consent writes atomic and kept telemetry status side-effect free via `peekAnonId()`. - Adds a coarse, anonymous signal to tool telemetry: which AI coding tool is driving the MCP server (Claude Code, Codex, Cursor, Gemini, VS Code, Windsurf, Zed, opencode, Copilot, or other). ## Tests Added / Updated - Telemetry unit coverage for consent precedence, identity creation, base props, sanitization, PostHog config, debug logging, shutdown, opt-out, and forget behavior. - Registry/tool-server tests for invocation IDs, platform metadata boundaries, startup failure flushing, and tool lifecycle telemetry. - Installer tests for final telemetry drain, update action classification, and uninstall identity cleanup ordering. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-19 18:22:34 +02:00
Ignacy Łątka	f3d108a5a1	feat: Argent Lens (#271) ... 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>	2026-06-17 15:22:04 +02:00
Ignacy Łątka	acfe80ab6b	chore: add ESLint with typescript-eslint (#349) ... ## What Adds type-aware linting to the workspace. Until now the only static gate on JS/TS was Prettier (formatting) and `tsc` — there was no linter, so the whole class of bugs `tsc` doesn't catch (floating promises, misused promises, throwing non-Errors, unsafe stringification, dead code) went unguarded across ~450 TS files. - **`eslint.config.mjs`** — flat config. `recommendedTypeChecked` runs on the TS sources via an explicit `project` list (each package keeps tests in a separate `tsconfig.test.json` that `projectService` can't auto-discover, so it's listed explicitly). Type-checked rules are disabled for the loosely-typed plain-JS build/dev scripts. The `argent-private` submodule and build artifacts are ignored (mirrors `.prettierignore`). - **`lint` / `lint:fix`** npm scripts. - **`.github/workflows/lint.yml`** — builds the workspace (type-aware rules need the referenced projects' declarations) then runs `eslint .`. Node 24 (ESLint 10 requires `^20.19 || ^22.13 || >=24`). ## Rule calibration This is an adoption PR, so it's deliberately calibrated rather than maximal: - **Kept on (bug-catchers):** `no-floating-promises`, `no-misused-promises` (with `checksVoidReturn: false` to drop the noisy callback variant), `only-throw-error`, `no-base-to-string`, `prefer-promise-reject-errors`, `no-unused-vars` (`_`-prefix escape hatch), plus the ESLint recommended set. - **Parked off as documented debt:** the high-volume style/`any`-family rules — `no-unsafe-*`, `require-await`, `no-unnecessary-type-assertion`, `restrict-template-expressions`, `unbound-method`, `no-explicit-any`, etc. These flag broad classes of pre-existing code and are out of scope here; each is commented as a ratchet target for follow-up passes. All findings from the kept-on rules are fixed in this PR (dead code/imports, error-cause chaining, **3 genuine floating promises**, non-Error throws, unsafe stringification). Stale unused `eslint-disable` directives left over in the tree were removed by `--fix`. ## Verification Locally, all green: `eslint .` (0 errors), `tsc --build`, `typecheck:tests`/`typecheck:scripts`, the full `vitest` suite (no behavior change from the fixes), and `prettier --check`. ## Not included (intentionally) Other static-analysis gates discussed (CodeQL, dependency-audit, ShellCheck, actionlint) are out of scope for this PR.	2026-06-17 12:20:55 +02:00
Paweł Fornagiel	92cc69a75c	feat: extract configuration-core and migrate auto-screenshot to feature flag (#295) ... ## Summary - Introduces `@argent/configuration-core` as the shared source of truth for feature-flag storage, the registry, and `isFlagEnabled`, so MCP and CLI can import the same primitives without coupling runtime code to CLI-only modules. - Replaces `ARGENT_AUTO_SCREENSHOT` with the off-by-default `disable-auto-screenshot` flag (auto-screenshot stays on unless enabled via `argent enable disable-auto-screenshot`); renames `ARGENT_AUTO_SHUTDOWN` to `ARGENT_TOOL_SERVER_SHUTDOWN_ON_MCP_EXIT`. - Keeps `@argent/cli` as the command layer (`enable` / `disable` / `flags`) with backward-compat re-exports, colored flag state output (picocolors), and `--help` listings of available flags. --------- Co-authored-by: Filip131311 <contact@filipkaminski.com> Co-authored-by: Cursor <cursoragent@cursor.com>	2026-06-10 15:01:25 +02:00
filip131311	20cb452fd4	feat(remote): artifact transport for files produced by a remote tool-server (#278) ... ## Why Files produced on the **tool-server host** (screenshots, profiler exports) were surfaced to the agent as host paths / `127.0.0.1` media URLs, which the MCP client (`argent-mcp`) then fetched a *second* time to get the bytes. When the tool-server runs **remotely**, that localhost URL resolves to the client's own machine — nothing there — so screenshots fail with `(Screenshot unavailable: no valid PNG …)`. Profiler exports have the same shape: paths that only exist on the remote host. ## What A reusable **artifact boundary layer** so any file-producing tool works regardless of where the tool-server runs: **Foundation** - **tool-server** (`src/artifacts.ts`, `http.ts`): in-process artifact registry + `GET /artifacts/:id` streaming route. `registerArtifact(hostPath)` returns a wire handle (`{ __argentArtifact, id, filename, mimeType, size }`) instead of a raw path. - **argent-mcp** (`src/artifacts.ts`, `content.ts`, `mcp-server.ts`): a client materializer deep-walks tool results for handles, downloads each over the remote-aware `TOOLS_URL`, writes it into a **structured cache**, and rewrites the result to the **local** path (+ inline image rendering). **Cache layout** (override root with `ARGENT_ARTIFACTS_DIR`): ``` ~/.argent/artifacts/<project>/<session>/<device>/<filename> ``` - `project` = `basename(cwd)` + short hash of the full path (readable + collision-safe) - `session` = minted once per argent-mcp process (groups a run, easy GC) - `device` = udid/serial when device-scoped, omitted otherwise **Consumers wired** - **screenshot** → returns an image artifact; rendered inline from downloaded bytes with **no second `127.0.0.1` fetch**. Fixes `auto-screenshot` and `flow-execute` screenshots via the same path. - **native-profiler-stop** → `exportedFiles` (XML) become downloadable artifacts materialized client-side. ## Deferred (follow-ups) - **`.trace` bundle** — it's an Instruments bundle (a directory); streaming needs archiving (no archiver dep yet). `native-profiler-stop` now returns a `traceFileNote` explaining it stays on the profiling host. - **Project source on remote** — `react-profiler-component-source` / `react-profiler-analyze` read the user's source tree on the tool-server host. The profiler analysis chains already work remotely (server-internal); tracked separately. ## Compatibility Legacy `{ url, path }` screenshot rendering is retained as a fallback when no artifact context is present (older tool-servers / unit tests). ## Tests - tool-server: artifact registry (infer/override), `GET /artifacts/:id` (200/404/410), updated `stop-recovery` assertions. - argent-mcp: materializer (download/rewrite/nested/failure/device-scoping), artifact-aware `toMcpContent`. - argent-mcp typecheck + full suite green; tool-server artifact/profiler tests green. (Note: a full local tool-server typecheck trips a pre-existing zod-v4-vs-v3 mismatch in `run-sequence` that's unrelated to this change and resolves on this branch's own lockfile.) ## Notes Routes around the `argent-private` native simulator-server binary (which emits the `127.0.0.1` media URL) rather than changing it — no submodule change. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: pFornagiel <pawel.fornagiel2@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Paweł Fornagiel <85541429+pFornagiel@users.noreply.github.com>	2026-06-10 12:04:30 +02:00
filip131311	8efd7c6346	feat: add argent server start for long-lived tool-server (#182) ... ## Human summary: This adds `argent server start` command to enable us to spawn tools server in arbitrary location. we want this to enable using remote tools-server via our mcp not only local ones. ## Summary - Adds `argent server start` to spawn a tool-server that does **not** auto-shutdown on idle, with configurable bind port and host — the missing piece for running tool-server on a remote/dedicated host. - Foreground by default so process supervisors (systemd, Docker, supervisord) own the lifecycle; `--detach` keeps the existing daemon-spawn behavior. Refuses to clobber a healthy running server unless `--force`. - Phase 2 (consumer-side `--tools-url` flag pointing the MCP / CLI at a remote tool-server) is now a one-flag change away — `tools-client.ts` and `mcp-server.ts` already honor `ARGENT_TOOLS_URL`. Out of scope for this PR. ## What changed - **`tool-server`** — read `HOST` env var (default `127.0.0.1` so the existing auto-spawn path is unaffected), bind to it, attach an `error` listener on `app.listen` so `EADDRINUSE` / `EACCES` exit cleanly instead of routing through `uncaughtException`. - **`argent-tools-client`** — broaden the readiness regex to match any host; extend `buildToolsServerEnv` with optional `{ host, idleTimeoutMinutes }`; record `host` in `~/.argent/tool-server.json` (backward-compat: missing field defaults to `127.0.0.1`); export `spawnToolsServer`, `findFreePort`, `isToolsServerHealthy`, `isToolsServerProcessAlive`, the state read/write/clear helpers, and `formatToolsServerUrl` so the CLI can reuse them. - **`argent-cli`** — new `server start [flags]`: `--port`/`-p` (default 3001, `0` = pick free), `--host` (default `127.0.0.1`), `--idle-timeout` (default `0` = never), `--detach`/`-d`, `--force`, `--help`. Warns when host is non-loopback. Foreground mode forwards `SIGINT`/`SIGTERM` to the child and writes the state file so local `argent run` / `argent mcp` can attach. - **`argent` dispatcher** — pass `BUNDLED_RUNTIME_PATHS` to `server()` so the new subcommand can find the bundled tool-server. ## Test plan - [x] `argent server --help` lists the new `start` subcommand - [x] `argent server start --help` shows full flag reference - [x] `argent server start --detach --port 0` → status alive/healthy, `/tools` reachable, state file populated with `host` field - [x] Second `argent server start --detach` refuses (`exit 1`) with helpful message - [x] `argent server start --detach --force` kills the old PID and starts a new one - [x] Foreground `argent server start --port 0` runs with inherited stdio; child PID is the actual tool-server (not the wrapper); `argent server stop` from a sibling shell tears down both - [x] Existing auto-spawn path (`argent tools`) still works — verifies the regex broadening + default-host change is backward-compatible - [x] `tool-server` (444 tests) + `argent-tools-client` (1) + `argent` dispatcher (1) suites pass - [ ] Manual smoke on `--host 0.0.0.0` — could not exercise locally (sandbox declined the public-interface bind); the warning + bind path is identical to loopback besides the listen address --------- Co-authored-by: pFornagiel <pawel.fornagiel2@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Paweł Fornagiel <85541429+pFornagiel@users.noreply.github.com>	2026-06-03 17:44:15 +02:00
Ignacy Łątka	c5c3f7af11	feat: feature flags (#260) ... ## Summary - New top-level CLI commands `argent enable <flag>` / `argent disable <flag>` / `argent flags`. - Storage is a small JSON file at `~/.argent/flags.json` by default; `--scope project` writes to `<project-root>/.argent/flags.json` instead. - `enable` writes `true`. `disable` removes the entry at the chosen scope (and deletes the file + empty `.argent/` when it becomes the last flag). - `isFlagEnabled` walks project → global, so a project entry shadows the same key in the global file. To opt a single project out of a globally-enabled flag, hand-edit `<project>/.argent/flags.json` to `{"flags":{"name":false}}` — there is no CLI for an explicit override. - The dispatcher routes the new commands to `@argent/cli` exports; bundling needs no config changes (only `node:fs|path|os`). ## Behaviour - `argent enable foo` → writes `{ "flags": { "foo": true } }` to global file. - `argent disable foo` → removes `foo` from the global file (clean round trip with `enable`). - `argent enable foo --scope project` → writes to `<project-root>/.argent/flags.json`. - `argent flags` → lists effective state with the winning scope; `--json` for scripting. - Project root is the nearest ancestor with `.argent`, `.git`, or `package.json` — falls back to cwd when none found. - POSIX `--` separator: `argent enable -- weird-name` is supported. - Help (`--help` / `-h`), invalid `--scope`, invalid flag names, missing arg, unknown flags all produce a clear stderr error and `exit 2`. - Flag-name validation: `/^[a-zA-Z][a-zA-Z0-9._-]*$/`. - Writes are atomic (tmp file + rename) so concurrent invocations cannot tear the JSON. ## Reader API `isFlagEnabled(name)` is exported from `@argent/cli` for future consumers; it walks project → global and returns `false` when unset. ## Files - `packages/argent-cli/src/flags.ts` (new) — storage + CLI handlers - `packages/argent-cli/src/index.ts` — re-exports `enable` / `disable` / `flags` / `isFlagEnabled` / `FlagScope` - `packages/argent-cli/test/flags.test.ts` (new) — 41 tests - `packages/argent-cli/vitest.config.ts` (new) - `packages/argent-cli/package.json` — description bump - `packages/argent/src/cli.ts` — dispatcher routes + help text - `README.md`, `CONTRIBUTING.md` — command tables ## Test plan - [x] `npm test --workspaces --if-present` → 1085 tests pass (41 in `@argent/cli`). - [x] `npm run typecheck:tests --workspaces --if-present` → clean. - [x] `npm run build` (root `tsc --build`) → clean. - [x] `npm run build -w @swmansion/argent` (dispatcher + esbuild bundles) → clean. - [x] `npx prettier --check .` → clean. - [x] End-to-end against the built dispatcher in a tmpdir: - `argent enable my-feature-flag` (global) writes to `~/.argent/flags.json`. - `argent enable proj-only --scope project` writes to `<proj>/.argent/flags.json`. - `argent disable my-feature-flag` removes the entry; round trip leaves a clean tree (file + empty `.argent/` removed when no other state lives there). - `argent disable foo` preserves sibling flags in the same file. - `argent flags` lists each flag with the winning scope. - `argent enable --` errors cleanly; `argent enable -- name-after` accepts the literal. - `argent enable foo --scope project` walks up to `.git` / `package.json` / `.argent`; stray editor configs (`.claude`, `.cursor`, …) do NOT count as project roots. - Error paths (`--scope bogus`, no name, `1bad-name`) exit `2` with a clear message.	2026-06-01 23:22:10 +02:00