52 Commits

Author	SHA1	Message	Date
Ignacy Łątka	00e3e07cf9	Merge origin/main into fix/docs-high-severity	2026-08-25 14:05:24 +02:00
Ignacy Łątka	6e1e1c2770	docs(tool-server): correct why auth can be disabled ... The empty-string token is no longer just an npm-run-dev artifact: the launcher ships it on purpose for `argent server start --no-auth`. Say what the warning actually guards (non-loopback reachability) instead of implying the flag does not exist.	2026-08-25 12:07:03 +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
filip131311	b232114422	docs: audit every comment in src against the code it describes (#931) ... Audits every comment in `src/` and `scripts/` against the code it describes. **462 files, 57 commits, net −8,194 lines.** Comment text only — the whole branch is code-identical to `main`. ## Method One subagent per file, strictly sequential. Scope was `src/` + `scripts/` (459 files); three more files were added at the end because they carried dead references of the same kind — two test headers citing design docs that do not exist, and `publish-npm.yml` citing a retired workflow. Each agent verified every comment — line, block, JSDoc, file header, trailing — against the surrounding code and the rest of the repo, following identifiers, paths, tool ids, config keys, env vars and issue links to see whether they still exist and still behave as described. Rules: - **A false or misleading comment is deleted, not reworded.** If a claim could not be confirmed by reading the source, it went. That is why the deletion count is so much larger than the rewrite count. - Survivors are cut to the shortest form carrying something the code does not already say. Restatement, preamble, hedging, changelog prose and ASCII banners are gone; the non-obvious *why* stays. - Preserved byte-identical: license headers, pragmas and directives (`@ts-*`, `eslint-disable`, shebangs, `/// <reference>`), JSDoc tag tokens, everything inside a string or template literal, and the sole comment inside an otherwise empty block (ESLint `no-empty` counts a comment-bearing block as non-empty). ## Verification Every file passed two independent gates before being recorded as done: 1. `comments-only` — the required check. 2. A second comment-stripping comparator with a proper mode stack, written for this pass because `comments-only`'s flat scanner desyncs on nested template literals and quote-bearing regex literals and then reports comment lines as code changes. Two files hit that false FAIL (`utils/android-profiler/pipeline/index.ts`, `scripts/extract-tools.mjs`); in both the "changed code" it printed was literally `//` lines, and the second checker confirmed the code was byte-identical. After the last file, all 462 changed files were re-checked against `main` with the same comparator, rather than trusting any agent's self-report. **459 code-identical; 2 are non-code (`.svg`, `.md`); 1 intentional.** The intentional one is `packages/argent/scripts/bundle-tools.cjs`: the changed template literal *is* the comment header of the file it generates, `packages/native-devtools-android/src/bundled-meta.ts`. Fixing only the generated file would have been reverted by the next build, so the generator changed too — and it has been verified to reproduce the committed generated file byte-for-byte. ## Representative false claims removed Not wording nits — statements a reader would have acted on: - **Reversed directions.** `proxyStart`'s JSDoc had the tunnel backwards (it is a reverse tunnel: the host binds first and the simulator dials in). A `paste()` doc had the pasteboard copy direction reversed. - **Contradicted by the code below it.** A timeout budget multiplied by three where the probes run concurrently — the same comment said so six lines later. A "warn once" that warns on every call. A "binary search" that is a linear scan. - **Named things that do not exist.** A `vega-fast-cli` binary, a `finish-recording.ts`, a `publish-next.yml` workflow, two `profiler-react19-*.md` design docs, a `DebuggerTarget.ts`, a commit hash git does not know, two tool ids, an `ensureEnv` cycle. - **Wrong by construction.** "Welford accumulators" across four files where the code keeps naive `n`/`sum`/`sumSq`; `sum`/`sumSq` documented over `actualDuration` when reduce sums `selfDuration`; a strict-mode halving written `n/2` where the code ceils; field docs listing enum values the producers never emit. - **Guarantees the code does not make.** A validation matrix claiming to cover "EVERY tool" that skips flagless ones; a Pareto cutoff that `slice(0, 20)` makes inert; an idempotence claim where the real rule is at-or-ahead; a capability note describing a clean 400 the shape-based device resolver can never produce. - **Unverifiable assertions** about prebuilt binaries, external CLIs and the cloud SDK — deleted rather than kept as folklore, since nothing in the repo can confirm them. - **Stale numbers**: invented Android tool versions, hard-coded tool counts and description lengths that had drifted. ## Review A Fable agent reviewed both halves adversarially for over-deletion, misread code, `no-empty` hazards and byte-identity violations. Second-half verdict: **SHIP**, with two one-line restores, both applied in the final commit — the `npm view ""` rationale behind a blank-token guard, and the note that `argent-mcp` keeps a copy of `SECRET_PLACEHOLDER_MARKER` it cannot import. ## Code issues surfaced but deliberately not fixed This pass changes comments only. Eight genuine findings are logged for a follow-up: 1. `telemetry/src/consent.ts` — a non-ENOENT read error returns null and falls through to the default-on path, so file errors *can* silently flip telemetry on. 2. `chromium-server/navigation.ts` — `navigate()` is reachable from `POST /api/navigate` with only a `typeof === "string"` check; open-url's schema is a bare `z.string()`, so the "already validated by zod" premise never held. 3. `http.ts` — `constantTimeEqual` returns early on a length mismatch, so the auth token's length is observable. 4. `describe/index.ts:~114` — the ios-remote branch passes `{ isTvOs: false }` unconditionally, so a remote tvOS simulator takes the iOS ax-service path, though `isRemoteTvOsSimulator` exists and shake/paste do use it. 5. `devices/boot-device.ts` — `-crash-report-mode never` is passed unconditionally *and* appended again by the feature-detecting path, so every emulator spawn passes it twice. 6. `react-profiler/pipeline/04-rank.ts` — `PARETO_THRESHOLD_PCT` is dead: `slice(0, 20)` always wins. 7. `reaped-sessions.ts` — a user-facing hint string tells the agent that `react-profiler-start { force: true }` disposes the debugger and profiler session; it does not. Left byte-identical because it is a string literal, not a comment. 8. `utils/simctl-backend.ts` — `localSimctl` is exported with no importers anywhere. ## Docs No documentation change is needed: this pass touches only source comments, and no user-facing capability, tool, CLI flag, config key or flow-file behaviour changed. --------- Co-authored-by: filip131311 <f.kaminski2000@gmail.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-24 12:16:20 +02:00
filip131311	4975ff490c	fix(debugger): cut debugger tool fail rate — structured not-connected results, classified CDP failures, narrow recovery (#610) ... ## Why PostHog (30d) shows the debugger tool family is argent's least reliable surface: | tool | fail rate | dominant causes | |---|---|---| | `debugger-status` | **37%** | METRO_NO_TARGETS / SERVICE_INITIALIZATION_FAILED / zod | | `debugger-connect` | **24%** | SERVICE_INITIALIZATION_FAILED (~7k, >1k users), METRO_NO_TARGETS | | `debugger-log-registry` | 41.7% raw / 4.2% excl. storms | one user retry-looped it **12,742×** on NO_TARGETS | Three design issues drive this: (1) "app/Metro not ready yet" — an expected precondition — is reported as a tool *error*, which both inflates fail rates and invites agent retry storms; (2) every CDP init/lifecycle fault lands in telemetry as the catch-all `REGISTRY_SERVICE_INITIALIZATION_FAILED` with `error_kind=unknown`; (3) ~600 users/30d hit zod validation failures with zero visibility into which parameter was wrong. ## What **1. Classified failures** (`d71efa43`) — six former plain-`Error` sites in `cdp-client.ts` / `target-selection.ts` now carry dedicated `DEBUGGER_CDP_*` / `DEBUGGER_TARGET_DEVICE_MISMATCH` signals (messages byte-identical). The registry's two causeless "terminating window" `ServiceInitializationError`s get their own `REGISTRY_SERVICE_TERMINATING` code. **2. Narrow recovery** (`ff9c1955`) — `recoverable()` on both debugger blueprints, scoped to windows where retry is provably safe: Metro recovers only `DEBUGGER_CDP_NOT_CONNECTED` (request never left the host; a detected socket death already self-heals for the *next* call via the terminated cascade — recovering `CONNECTION_CLOSED` there would be dead code, see the blueprint comment). Chromium also recovers `CONNECTION_CLOSED` for the tab-switch reconnect window. `REQUEST_TIMEOUT` stays unrecoverable (double-execution risk). A reachability test proves the retry actually fires for a RUNNING node. **3. Structured not-connected results** (`48b91ffd`) — `debugger-status` and `debugger-log-registry` become factories that return `{ status: "not_connected", reason, detail, guidance }` for classified preconditions (`metro_not_running | no_app_connected | device_mismatch | cdp_unreachable | stale_connection | reconnecting`) and still throw on unexpected faults. `detail` preserves the original error text for string-matching agents. `debugger-status` gains a socket-state gate (Metro: dispose stale node; Chromium: report transient reconnect, no dispose — the client belongs to the ChromiumCdp dependency). log-registry keeps **no** gate on purpose: captured logs are readable over a dead socket, and disposal would destroy the post-crash log file. Flows/run-sequence map a not_connected result to a **failed step** (mirrors `isUnmetUiWaitResult`) so recorded connectivity gates don't silently pass. `debugger-evaluate` re-codes agent-expression throws as `DEBUGGER_EVALUATE_EXPRESSION_THREW`. **4. Telemetry + guidance + docs** (`7602a70d`) — `tool:fail.invalid_params` (schema-declared names only; unknown keys → literal `"unrecognized_keys"`; capped emit-side at 16), new `debugger:tool_outcome` event (coded enum; joins `tool:invoke`/`complete` via `tool_invocation_id` — `ai_client`/`duration` live on the joined row), anti-retry-loop guidance appended to the Metro discovery errors (first sentences verbatim — skills match on them), six skills updated, Telemetry.md bumped to v1.03 with the new coded diagnostics disclosed. ## Dashboard migration note `debugger-status` / `debugger-log-registry` precondition failures stop emitting `tool:fail` — track them via `debugger:tool_outcome` (`outcome != 'connected'`). Per-AI-client breakdowns of those outcomes need a join on `tool_invocation_id` against `tool:complete`. ## Testing - Full suites green: tool-server 3,142, telemetry 290, registry 87. New coverage: recoverable truth tables (incl. non-Error inputs), status not-connected matrix (Metro/Chromium/terminating-window/stale/dispose-side-effect/fall-through-rethrow), log-registry rows, zod `invalid_params` derivation + emission-level guard, flow gate, evaluate rewrap, sanitize-level enum checks. - Live-tested against a booted iOS simulator + RN app and an Electron target (details in PR comments). Plan hardened through 3 adversarial review rounds (46 confirmed findings addressed) before implementation. 🤖 Generated with [Claude Code](https://claude.com/claude-code)	2026-08-10 11:51:45 +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	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
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
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
Hubert Gancarczyk	f002fc9540	feat(telemetry): track Argent Lens design-review funnel (#478) ... ## What Adds three privacy-safe telemetry events for the Argent Lens design-review flow, capturing the human-decision funnel that the generic `tool:*` path can't see (submission is an HTTP POST, and the `await_user_selection` tool is hidden in `argent lens` CLI sessions): - **`lens:preview_opened`** — a human loaded the preview UI (`GET /preview/`), deduped per round. - **`lens:round_completed`** — the human submitted their picks (once per round, never on a resubmit). - **`lens:round_abandoned`** — a staged round was discarded before submit (window closed, `argent lens` exited mid-review, or the round superseded). ## Privacy Payloads carry only aggregate counts, booleans, durations, and the device `platform` enum — never element names, comment text, variant code, file paths, or raw device ids. The store emits privacy-safe aggregate structs that are decoupled from the telemetry package; structural assignability to the event props is enforced at the `track()` call site (drift is a compile error). ## Event fields - **`preview_opened`**: `round, element_count, variant_count, is_cli_session, platform` - **`round_completed`**: `round, element_count, variant_count, annotation_count, element_comment_count, skipped_comment_count, has_global_comment, is_cli_session, had_parked_await, round_duration_ms, platform` - **`round_abandoned`**: `round, element_count, variant_count, had_parked_await, is_cli_session, platform` ## Testing - Unit tests for all three events: per-round dedup, exactly-once completion (no resubmit re-emit), abandoned vs happy-path roll, CLI up-front open, and content-agnostic privacy assertions. - Verified end-to-end against a live tool-server: all three events fire with correct aggregate values and zero content leakage through the real sanitize pipeline. --------- Co-authored-by: Ignacy Łątka <latkaignacy@gmail.com>	2026-07-13 16:56:49 +02:00
Ignacy Łątka	44b38d490e	fix(tool-server): inject Android keyboard/button over adb input (#449) (#455) ... ## What & why `keyboard` and `button` drive Android through the simulator-server's USB-HID transport (`pressKey` / `cmd:"button"`). The guest only receives those HID events when the AVD exposes a hardware keyboard (`hw.keyboard = yes`) — the default, but CI / headless AVDs are routinely created with `hw.keyboard = no` (and `hw.mainKeys = no`), where the guest **silently drops** them. Because that transport is fire-and-forget, both tools returned `{ typed }` / `{ pressed }` **success while injecting nothing**. This still affects current `main`: after the keyboard refactor, `makeAndroidImpl` routes Android **TV** to `adb input` but Android **phones/tablets** still to `typeSimulatorServer` (the HID path). Fixes #449 (found during 0.13.0 RC E2E testing on a `hw.keyboard=no` AVD — `argent-test-ci-repro`, the config CI uses). ## Change Route Android **phone/tablet** key / text / button injection through `adb shell input text` and `input keyevent` (new `utils/android-input.ts`), the same on-device transport Android TV and Vega already use: - **`keyboard`** — `platforms/android.ts` now sends the non-TV branch to a `typeAndroidPhone` helper (adb `input`); the Android-TV and iOS branches are untouched. - **`button`** — the Android branch presses via `injectAndroidKeycode`; iOS keeps the simulator-server HID path. `adb input` lands regardless of `hw.keyboard`, on emulators (any config) and physical devices alike, and a non-zero exit surfaces as a **thrown error** instead of a silent no-op — directly addressing the fire-and-forget concern already called out in the `button` tool. Touch gestures are unchanged. ## Verification - **Unit tests — 11/11 pass** (rebased on current `main`): new `keyboard-android.test.ts` (vocabulary parity vs `NAMED_KEYS`, `input text` shell-quoting incl. spaces, `input keyevent` mapping, empty-text no-op, newline rejection) + updated `button.test.ts` (Android `back` now asserts `KEYCODE_BACK` over adb). - **eslint** on the changed files: clean. - **Live tool-server** on a `hw.keyboard=no` AVD: the `keyboard` tool now issues `adb … shell input text '…'` (vs the RC's HID `pressKey`), and a failed inject **raises an error** rather than a fake success. The `adb input` path was independently observed typing/deleting on this exact AVD during RC testing (where the HID path silently no-op'd). - Note: a full `tsc --build` / whole-suite run couldn't be completed in my environment (the `argent-private` submodule isn't checked out, which breaks the npm workspace install, and `main` added upstream deps my base lacked). `platforms/android.ts` mirrors the existing `platforms/ios.ts` branch structure one-for-one, and the pre-rebase revision of this change passed `tsc --build` + eslint. CI here is authoritative for the full typecheck. ## Reviewer notes - `input text` receives the string as one shell-quoted argv token, so spaces are preserved verbatim; newlines are rejected (they'd truncate the `input` line) — callers use `key: "enter"`. - `keys` counts by codepoint, matching the tv/vega/simulator-server backends.	2026-07-10 12:51:24 +02:00
Gabe Debes	10a78d0527	feat(file-inputs): add tar-upload kind for streaming remote file/directory uploads (#443) ... ## What A new `tar-upload` file-input kind so a tool that reads a local file or directory (e.g. `reinstall-app`'s app bundle) works when the tool-server runs on a different machine than the caller. ## Why `reinstall-app` assumes the bundle is on the tool-server's filesystem. That breaks with a cloud-hosted simulator — the bundle is on your machine, not the server's. The existing `file` kind inlines base64 and is capped at 32 MB, too small for a real `.app`/`.apk`; `tar-upload` streams instead. ## How When you're not linked to a remote server, an existing local path is used in place. When you are (e.g. `argent link`), the client tars the path, streams it to `POST /upload`, and the tool call carries `uploadId` plus a SHA-256 `contentHash`. The server always extracts from that upload — even if the same path already exists on disk — verifies the hash, and vets tar members before extracting. The client only uploads when the path is on its own machine (a line on stderr so you know it's working). Same command local or remote: ``` argent run reinstall-app --udid <udid> --bundleId <id> --appPath ./MyApp.app ``` ## Shared extraction Per review feedback, the tar pack/unpack logic is unified in a small `@argent/archive` package used by **both** directions — this upload path and the pre-existing artifact download (`streamDirectoryAsTarGz` / `downloadAndExtractArchive`). The shared extractor rejects path-traversal entries, symlinks whose target escapes the extract dir, and non-file/dir members (hardlinks, devices) — while still allowing a bundle's internal symlinks. This also hardens the artifact-download path, which previously extracted without those checks. ## Tests Client + server unit and HTTP round-trip tests: dir and file upload, skip-when-not-local, co-located no-op, hash required, path-traversal / escaping-symlink / hardlink rejection, sidecar handling, single-member resolution, `/upload` auth + size caps, and artifact download extraction. All suites pass. --------- Co-authored-by: Filip131311 <contact@filipkaminski.com>	2026-07-10 12:29:48 +02:00
Hubert Gancarczyk	f38f0e3876	feat(telemetry): distinguish tvOS and Android TV from iOS/Android (#477) ... ## Summary Telemetry inferred the device platform purely from device-id **shape** on the per-tool-call hot path, so a tvOS simulator (same 8-4-4-4-12 UUID as an iPhone) and an Android TV emulator (same `emulator-NNNN` serial as a phone) were both reported as `ios` / `android` — TV usage was invisible in analytics. This adds `tvos` and `android-tv` to the **telemetry** `PLATFORMS` enum and refines the inference so a TV target is attributed correctly. ## Approach - The runtime kind (`mobile` / `tv`) is already resolved and memoized in two module-level caches (`runtimeKindCache` in `ios-devices.ts`, `androidRuntimeKindCache` in `adb.ts`), warmed by the usual TV-path tools (describe, screenshot, keyboard, launch/restart-app, the streaming blueprint, tv-control). - New synchronous, **cache-only** readers (`getCachedSimulatorRuntimeKind`, `getCachedAndroidRuntimeKind`) let `refineTvPlatform` in `http.ts` map `ios → tvos` / `android → android-tv` with **no new `simctl`/`adb` round-trip** on the hot path. - The registry **device** `Platform` (`@argent/registry`) is intentionally left unchanged — a TV stays a `runtimeKind`, not its own device platform, so capability gating and dispatch remain TV-agnostic. The two new values are confined to the telemetry boundary (`tool:invoke` / `tool:complete` / `tool:fail` and child sub-tool attribution). ## Behavior notes - The **first** tool call on a device may land before the cache is warm and reports the coarse base platform (`ios`/`android`); subsequent calls, once describe/screenshot/streaming have run, report the TV variant. This is best-effort coarse telemetry by design. - For an `emulator-NNNN` slot reclaimed by a different-form-factor AVD within one tool-server lifetime, the synchronous reader can momentarily report the prior occupant's kind until an async, avdName-checked path re-probes. Documented inline; no crash and no dispatch impact. ## Verification - **Live E2E** against real booted devices (real `simctl`/`adb` → real cache → real http telemetry recording): Apple TV → `tvos` (cold-cache `ios`, warm `tvos`); iPhone → `ios`; Android phone → `android`. The `android-tv` path is symmetric and covered by unit/integration tests with real leanback-feature probing. - Unit + integration tests added: sanitize allowlist, http platform inference (cold/warm/TV/child), and cache readers. Telemetry suite 192/192; tool-server affected suites green. - `tsc` build, `typecheck:tests`, eslint (`--max-warnings 0`), and prettier all clean.	2026-07-07 16:29: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
Mateusz Ścianek	b8afbed183	feat(tv): Apple TV (tvOS) and Android TV support (#374) ... Adds end-to-end support for driving **Apple TV (tvOS)** and **Android TV (leanback)** targets through argent, using a focus-driven interaction model (TVs have no touchscreen — interaction is moving a focus highlight with the remote). This PR was reworked after review to **reuse the existing cross-platform tool surface and the `tv-remote` tool from the Vega/Fire TV work (#366)** rather than ship a separate family of `tv-*` tools. ## What this delivers TV targets are driven by the **same cross-platform tools as every other platform**, routed through the existing `dispatchByPlatform` fork mechanism — there are no dedicated `tv-describe`/`tv-navigate`/`tv-type`/`tv-set-focus` tools: - **`describe`** — on a `runtimeKind: "tv"` target, returns the focus-driven view (focused + focusable elements) instead of a tap tree. On Android TV it auto-falls-back to the full `uiautomator` tree when the RN focus engine exposes nothing. - **`tv-remote`** — the cross-platform remote/D-pad tool from #366, now extended with `ios` (Apple TV HID daemon) and `android` (Android TV adb keyevents) branches alongside the existing `vega` branch. Single button, a `repeat`, or a whole path (`["up","right","select"]`) in one call. - **`keyboard`** — types into the focused field on a TV target (named keys are rejected there — they're navigation, which belongs to `tv-remote`). - **`button`** stays hardware-only (phones/tablets); it is not a TV tool. **Apple TV** runs two native daemons (in-sim AX service + host-side HID daemon), shipped via the `argent-private` submodule. **Android TV** reuses the same tool surface, adb-backed (`input keyevent`, `uiautomator dump`, `input text`). ## Remote vocabulary parity `tv-remote` exposes the full 16-button vocabulary (`up`/`down`/`left`/`right`/`select`/`back`/`home`/`menu`/`playPause`/`rewind`/`fastForward`/`next`/`previous`/`volumeUp`/`volumeDown`/`mute`): | | Apple TV | Android TV | Vega | |---|---|---|---| | D-pad / select / back / menu / home / playPause | ✅ | ✅ | ✅ | | media-transport + volume/mute | ❌ rejected | ✅ | ✅ | Media-transport/volume keys **genuinely work on Android TV** (real keycodes — verified live: `volumeUp` moved `STREAM_MUSIC`, `mute` toggled per `dumpsys audio`). On the **Apple TV simulator** they are **rejected with a clear error**: on-device testing confirmed the tvOS sim's HID stack silently drops Consumer-Control events, so returning success would be a lie. ## Key design points - **tvOS UDIDs are UUID-shaped and indistinguishable from iOS by shape.** Handled with `runtimeKind` detection (tvOS runtime string for Apple TV; `pm list features` leanback/television for Android TV — *not* `ro.build.characteristics`, which lies on TV emulators). - Converted launch-app / restart-app / screenshot / screenshot-diff / run-sequence from **eager** to **lazy** service resolution, so a tvOS target never spins up (and hangs on) the iOS-only simulator-server / native-devtools blueprints. - Native injection selects the platform-matched (TVOSSIMULATOR) dylib slice; daemons recycle across sim reboots and app relaunches so injection and focus survive. - SKILL.md footprint minimized per review: the two TV skills were collapsed into a single lean **`argent-tv-interact`** (~40 lines). ## Verification - `npm run build`, ESLint, Prettier, and the full tool-server suite (**1565 tests**) all pass; CI green (incl. the Apple TV / Android TV / Vega e2e jobs). - Core flows verified live against real apps on both an Apple TV 4K simulator and a Google ATV emulator. ## Dependency / merge order Pins the `argent-private` submodule to the tip of its `feat/tv-support` branch (software-mansion/argent-private#20). **Merge that PR to `main` first, then bump the submodule pointer here to the merged SHA before merging this PR.** 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-01 14:59:37 +02:00
Ignacy Łątka	3a2e4af017	fix(tool-server): authenticate Chromium-control WebSocket upgrades (#411) ... ## Problem The per-device Chromium control WebSocket (`/chromium-server/<id>/ws`) accepted **any** upgrade handshake. The `ws` library owns the HTTP `upgrade` event, so neither protection that guards every HTTP route ran on it — the **Host-header guard** (DNS-rebinding defense) and the **Bearer-token auth gate** are both registered as Express `request`-event middleware and never fire on an `upgrade`. That channel dispatches `touch` / `key` / `button` / `wheel` / `rotate` / `clipboardSync` straight onto the live `ChromiumServer`. So while a Chromium/Electron session is warm (the normal state when an agent is driving one), **any web page the operator visits could connect cross-origin and inject synthetic input**: ```js new WebSocket("ws://127.0.0.1:<port>/chromium-server/chromium-cdp-9222/ws") .onopen = e => e.target.send(JSON.stringify({ cmd: "key", direction: "Down", text: "…" })); ``` WebSocket handshakes aren't subject to the Same-Origin Policy and no `Origin` was checked — cross-site WebSocket hijacking (CSWSH). An attacker can't bootstrap a session (that still needs the authenticated REST path), only ride one already open. ## Fix The browser-loaded preview UI is the legitimate consumer and **can't set an `Authorization` header on a WebSocket** — which is why the whole `/preview` surface is intentionally token-exempt. So this mirrors the existing **origin/host-based** defense rather than adding token auth, applied in the upgrade handler: - **Host guard** — reuse the same loopback/bind-host allow-list the HTTP requests use, closing the DNS-rebinding bypass on the upgrade path. - **Origin guard** — browsers always send `Origin` on a WS handshake; accept only our own loopback/bind-host origin. A non-browser client (Node `ws`) sends no `Origin` and is still constrained by the Host guard. Opaque / `null` origins are rejected. A wildcard bind (`--host 0.0.0.0`) disables the guard, matching the existing HTTP Host-guard behavior. The check runs before `resolveServer`, so a cross-origin probe can't even learn whether a device exists. The legitimate same-origin preview UI and Node clients are unaffected. ## Tests New `chromium-ws-upgrade-auth.test.ts`: - unit-tests `isWebsocketUpgradeAllowed` across loopback / localhost / `::1`, no-Origin (Node client), cross-origin (rejected), `null` origin, DNS-rebinding Host, missing Host, explicit bind host, and wildcard-disabled; - wiring-tests that `attachChromiumServerWebsocket` destroys the socket and never reaches `resolveServer` on a cross-origin upgrade, and passes an allowed one through. Verified locally on `origin/main`: `tsc --build` clean, full tool-server suite **1573 passing**, `typecheck:tests` clean, ESLint clean, Prettier clean.	2026-06-25 21:16:03 +02:00
Hubert Gancarczyk	0edefebe06	fix(telemetry): orchestator sub-tools invocations was missing ai_client and platform attributes (#400) ... ## Summary Fixes telemetry attribution for tools dispatched by orchestrators. `run-sequence`, `flow-execute`, and `flow-add-step` run their steps via `registry.invokeTool()` directly, which minted a fresh, unregistered invocation id per nested call — so the `ai_client` / `platform` the HTTP layer captured for the outer request never reached the nested gestures, and they were recorded as **anonymous** in telemetry. Remove `opt_out` event that is a leftover. ## Changes - Add an optional `recordChildInvocation` recorder to `InvokeToolOptions` / `ToolContext`, bound by the HTTP layer to the outer request's attribution. - New `invokeSubTool` helper: registers each sub-tool under a minted id inheriting the request's AI client, with the platform re-derived from the sub-tool's **own** device arg (`udid` / `device_id` / `avdName`); forwards the recorder so propagation survives arbitrary nesting (e.g. `flow-execute → run-sequence → gesture-tap`). - Route the three orchestrators' sub-dispatch through - Refactor platform inference in the HTTP layer into a shared `platformFromArgs` helper (also hardened to not throw on a malformed device arg). - Remove opt_out event leftover Why re-derive platform per child: an orchestrator like `flow-execute` has no platform of its own and a single flow can target several devices, so the child's device arg is the only correct platform source; the parent's platform is the fallback.	2026-06-24 14:03:57 +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	56033b62ca	chore(deps): bump express to 5.x and migrate route params (fixes #314) (#354) ... ## What Bumps `express` `^4.19.2` → `^5.2.1` and `@types/express` `^4.17.21` → `^5.0.6` in `@argent/tool-server`, with the source change Express 5 requires. This is the **express-5 half of dependabot #314**, which can't merge as-is because it breaks the build. ## Why #314 broke Express 5 / `@types/express` 5 widen route param values from `string` to `string | string[]`, so every single-segment param read fails to typecheck — 9 `TS2345` errors across `artifacts.ts`, `http.ts`, `preview.ts`: ``` packages/tool-server/src/artifacts.ts(61,42): error TS2345: Argument of type 'string | string[]' is not assignable to parameter of type 'string'. ... (9 total, incl. preview.ts variant-image/describe routes added by Argent Lens) ``` ## Fix Narrow each param read with `as string`. Every tool-server route uses single-segment params, which path-to-regexp v8 always resolves to a string, so the cast is sound: - `artifacts.ts` — `id` - `http.ts` — `deviceId`, `name` - `preview.ts` — `udid` (×2), `elementId`, `variantId` No removed Express 5 APIs (`app.del`, `res.sendfile`, `req.param()`, numeric `res.send`/`res.json` status) are used, and no route relies on the changed wildcard/optional path syntax. Lockfile regenerated on **Node 20 / npm 10.8.2** to match the repo's package-lock toolchain. ## Verification (local) - Reproduced the 9 `TS2345` errors on express 5, then `tsc --build` clean after the narrowings. - Full CI-equivalent on **Node 20** (the unit-tests toolchain): `tsc --build`, `eslint --max-warnings 0`, `prettier --check`, `typecheck:tests`/`typecheck:scripts`, full unit suite incl. **1250 tool-server tests** — all green. `test/artifacts.test.ts` boots the real Express app via supertest and exercises `GET /artifacts/:id` under Express 5. - `npm ci` from the committed lockfile succeeds; the lock is idempotent under `npm install --package-lock-only --ignore-scripts` (Node 20). - **Live device E2E** (out-of-process tool-server under Express 5, booted iPhone 16 Pro Max): `GET /artifacts/:id` → `200 image/png` (331 KB PNG, ws + simulator-server); `GET /preview/simulator-server/:udid` → `200`; `GET /preview/variant-image/:elementId/:variantId` → route matched + params parsed. Unknown artifact id → `404`. Supersedes #314 (Dependabot auto-closes it once express reaches 5.x on `main`).	2026-06-18 11:50:30 +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
Stanisław Chmiela	6e4d8babec	feat: GET /artifacts/ endpoint (#347) ... EAS is going to poll this endpoint for new artifacts and upload as session artifacts for later user inspection. I'm open to better ways to integrate, this seems the easiest to merge and move forward.	2026-06-16 15:46:41 +02:00
filip131311	f288a461b0	refactor: rename the Electron device platform to "chromium" (CDP) (#332) ... ## Summary The Electron support added in #247 is **generic Chromium/CDP under the hood**. The discovery layer probes the Chromium-default CDP port (`9222`) and any `ARGENT_*_PORTS` entries; the connection picks the first non-devtools page target; describe is a plain in-page DOM walker; input/screenshot/screencast/navigation/JS-debugger are all straight CDP. Nothing in that path is Electron-specific — the only Electron-specific piece is the *launcher* (`boot-electron.ts`, which resolves and spawns an Electron binary). So any Chromium-family runtime exposing a CDP endpoint — an Electron app, **or** Chrome/Brave/Edge/WebView2 launched with `--remote-debugging-port` — is discoverable and drivable through the same tool surface. This PR renames the platform discriminator (and everything keyed off it) from `electron` to `chromium` so the naming matches reality. ## What changed **Public/contract surface (clean hard rename, no back-compat aliases):** - Platform discriminator `"electron"` → `"chromium"`; device id `electron-cdp-<port>` → `chromium-cdp-<port>`. - `ToolCapability.electron` → `.chromium`; the capability-gate rejection now reads `Tool 'X' is not supported on chromium app`. - Env `ARGENT_ELECTRON_PORTS`(`_FILE`) → `ARGENT_CHROMIUM_PORTS`(`_FILE`); ports cache `~/.argent/electron-cdp-ports.json` → `chromium-cdp-ports.json`; HTTP surface `/electron-server/` → `/chromium-server/`. **Files / dirs / symbols:** - `src/electron-server/` → `src/chromium-server/`; blueprints `electron-cdp` / `electron-js-runtime-debugger` → `chromium-*`; `describe`/`open-url`/`launch-app` `platforms/electron.ts` → `chromium.ts`; `keyboard/electron-keys` → `chromium-keys`; `utils/electron-discovery` → `chromium-discovery`. - `ElectronServer`/`ElectronCdpApi`/`ElectronJsRuntimeDebugger`/`describeElectron`/`discoverElectronDevices`/`ELECTRON_ID_PREFIX`/… → `Chromium*` / `CHROMIUM_*`. Tests renamed to match. **Stays "electron" (the Electron-specific launcher):** - `boot-device` keeps the `electronAppPath` / `electronPort` / `electronArgs` inputs, and `boot-electron.ts` still resolves & spawns an Electron binary. It just yields a `chromium` device now (an Electron app *is* a Chromium/CDP runtime). **Skills:** `argent-device-interact`, `argent-metro-debugger`, `rules/argent.md`, and the RN-workflow reference were reframed to describe **Chromium (CDP)** availability — Electron apps *plus* any Chromium browser over CDP (auto-discovered on `9222` / `ARGENT_CHROMIUM_PORTS`) — instead of Electron only. ## Test plan - [x] `tsc --build` clean - [x] `typecheck:tests` clean - [x] **1116 vitest cases pass (126 files)** - [x] prettier clean on all changed/renamed files - [x] Full-repo sweep: every remaining "electron" mention is intentional (the launcher path + skill prose explaining Electron as one kind of Chromium/CDP app); `electronic` in LICENSE/COC untouched.	2026-06-15 11:03:23 +02:00
Ignacy Łątka	9b027096d7	feat: Electron support (#247) ... ## Summary Adds Electron (Chromium + CDP) as a third device platform alongside iOS and Android. Argent can boot an Electron app, list it next to simulators/emulators, drive it with the same tool surface where it makes sense — taps, swipes, keyboard, screenshots, describe, navigation — and debug it via the four ported `debugger-*` tools. Mirrors the sim-server architecture in TypeScript: a per-device server with HTTP API, MJPEG screencast, refcounted CDP screencast, FPS tracker, clipboard, and a WebSocket command bus. ## What works on Electron | group | tools | status | |---|---|---| | Lifecycle | `boot-device` (with `electronAppPath`), `launch-app`, `open-url` | ✅ works | | Vision | `screenshot`, `describe` (DOM walker w/ shadow-DOM + same-origin iframes) | ✅ works | | Input | `gesture-tap`, `gesture-swipe`, `keyboard` (text + named keys) | ✅ works | | Sequencing | `run-sequence` (per-step capability check) | ✅ works | | **JS debugger** | `debugger-connect`, `debugger-status`, `debugger-evaluate`, `debugger-log-registry` | ✅ **direct CDP** | | Discovery | `list-devices` (Electron entries shown alongside sims/emulators) | ✅ works | | Cleanup | `stop-simulator-server`, `stop-all-simulator-servers`, `stop-metro` | ✅ works | | Misc | `update-argent`, `dismiss-update`, `gather-workspace-data`, all `flow-*` recording tools | ✅ works | ### Debugger port — how it routes Dispatch lives in `tools/debugger/debugger-service-ref.ts`: an Electron device id (`electron-cdp-<port>`) routes to a new `ElectronJsRuntimeDebugger` blueprint that wraps the page CDP session already opened by `boot-device`. Everything else stays on the Metro-driven `JsRuntimeDebugger` blueprint. The new blueprint exposes the same `JsRuntimeDebuggerApi` shape so tool code is unchanged. `Runtime.consoleAPICalled` events feed into the existing `LogFileWriter` + cluster pipeline — `debugger-log-registry` returns the same shape on Electron as it does on Metro. ## What is cleanly rejected with `Tool 'X' is not supported on electron app` HTTP capability gate declines these up-front (HTTP 400): | group | tools | |---|---| | Mobile gestures | `gesture-pinch`, `gesture-rotate`, `gesture-custom` | | Mobile controls | `button`, `rotate` | | App lifecycle | `restart-app`, `reinstall-app` | | iOS-native | `paste`, all `native-*`, `native-profiler-*` | | RN-only debugger | `debugger-component-tree`, `debugger-reload-metro`, `debugger-inspect-element` | | RN-only network | `view-network-logs`, `view-network-request-details` | | RN-only profiler | all `react-profiler-*` (incl. `component-source`), all `profiler-*` query / combined tools | ## Verification history Three commits resolved findings from two parallel verification swarms: - `507b295` — swarm v1 fixes: early-disconnect race in new blueprint, NaN timestamp crash, disconnect listener leak, missing test coverage for 13 of 15 lockouts, missing disconnect→terminated propagation test, stale skill + tool descriptions. - `dd0f185` — pre-existing crash: `spawn()` in boot-electron lacked an `'error'` event handler; ENOENT escalated to `uncaughtException`. + 4 regression test cases. - `95161ab` — swarm v2 fixes: orphan promise rejection when pid-less spawn fires deferred `'error'`, misleading rationale comment, stale cross-skill references calling this "Metro debugging only". Branch was also cherry-picked onto v0.8.0 (`e1327b4`) to pick up #245. ## Follow-ups left for separate PRs - **CPU profiling on Electron** — Chromium's `Profiler.start`/`Profiler.stop` work fine; only the V8 sample format differs from Hermes'. A normalizer in the query layer would unlock `react-profiler-cpu-summary` + `profiler-cpu-query` for arbitrary Electron renderers (without the React-DevTools commit half). - **Source-mapped element inspection on Electron** — `debugger-inspect-element` could be rebuilt on top of `DOM.getNodeForLocation` + CSS source maps, but it'd be a from-scratch implementation rather than a port. ## New sim-server-equivalent HTTP surface Mounted at `/electron-server/:deviceId/*` — not advertised to MCP, consumed by preview UIs and integration tests: - `GET /viewport`, `GET /stream.mjpeg` (multipart-JPEG screencast) - `POST /api/screenshot`, `/api/clipboard/text`, `/api/fps`, `/api/navigate`, `/api/reload`, `/api/history/back`, `/api/history/forward` - `WS /ws` (input commands + event bus) Sharp is loaded as an optional dependency — screenshots still work without it (no rotate/resize, just raw PNG). ## Test plan - [x] 786 vitest cases pass; new coverage for the dispatch helper, blueprint factory edge cases (early disconnect, NaN timestamp, dispose symmetry), 15-tool table-driven lockout assertion, and 5 boot-electron spawn-error scenarios. - [x] Build + prettier clean. - [x] E2E swept the original 27 surfaces (11 MCP tools, 8 HTTP endpoints, MJPEG, WebSocket, 6 capability rejections, session cleanup). - [x] E2E swept the debugger surface against a live Electron app — connect / status / evaluate (`1+1`, JSON-stringified globals, `document.title`) / log-registry (clusters + log file). - [x] E2E swept the 17 lockouts — every one returns HTTP 400 with `Tool 'X' is not supported on electron app`. - [x] Two rounds of parallel verification swarm; every real finding addressed. - [ ] Reviewer drives an Electron app end-to-end via MCP and confirms describe / tap / swipe / keyboard / debugger-evaluate land correctly. --------- Co-authored-by: Filip131311 <contact@filipkaminski.com>	2026-06-12 17:54:45 +02:00
filip131311	c01f41cd5f	feat(remote): input-side file boundary — flows, screenshot-diff, profiler reports, workspace tools (#319) ... ## Why PR #278 fixed the **output** half of the remote file boundary: files a tool *produces* travel to the client as `ArtifactHandle`s. But seven tools still break when the tool-server runs on a different machine than the agent, in one (or both) of two ways: - **Output-side leftovers** — `native-profiler-analyze` and `screenshot-diff` still returned raw host paths (and embedded them in report/summary prose), so the agent can't open them remotely. - **Input-side gap** — nothing moved a file the *agent* owns onto the tool-server. Any tool taking a client-local path as a parameter (`screenshot-diff` baselines, the three flow tools' `project_root`, `react-profiler-component-source`, `gather-workspace-data`) silently read/wrote the wrong machine's disk. Flows were fully broken in remote mode: the YAML landed on the server's disk under the agent's path. ## What ### Output side (apply the existing pattern) - **native-profiler-analyze** — `reportFile` is now an `ArtifactHandle` (mirrors `react-profiler-analyze`'s `fileArtifact()`); the inline report now says *"use the Read tool on the `reportFile` path in this result"* instead of embedding the server path. - **screenshot-diff** — `diffPath` / `contextDiffPath` are now `ArtifactHandle`s; the MCP adapter renders the context-diff image from materialized bytes (legacy string-path results from older servers still render co-located). The summary references the result fields instead of embedding host paths. ### Input side (new, symmetric mechanism) A declarative **file-input boundary**, mirroring the artifact gate in the opposite direction: - A tool declares `fileInputs: [{ target, path: "${param}…", kind }]` on its `ToolDefinition`; the declaration ships to the client via `GET /tools`. - Before sending a call, the client (`@argent/tools-client`, shared by CLI and MCP) interpolates each template from the args and replaces the target arg with a wrapper: `{ __argentFileInput, path, size, mtimeMs, content? }`. File bytes are base64-inlined **only when routed to an external tool-server** (`argent link` / `ARGENT_TOOLS_URL`) — unlinked local calls never pay for encoding. - The server resolves wrappers **before zod validation**, so tools always execute against a plain local path: - path matches on the server's own filesystem (existence for dirs, size+mtime for files) → used **in place**, zero copies — the exact dual of the artifact materializer's co-located gate; - otherwise `kind: "file"` content is materialized into a temp file (with size-integrity check, 32 MB cap); - `kind: "directory"` (trees that can't ride in a call) → 422 with actionable remote-mode guidance; - `kind: "probe"` → never fails; the tool learns host-presence via `ctx.fileInputs` and adapts. - The reverse channel: a tool whose output belongs in the **agent's project** returns a `__argentClientFile` directive (path + content); the client writes it and rewrites the directive to the path. Writes are constrained to `**/.argent/flows/<safe-name>.yaml` so a tool-server can't direct writes anywhere else on the client machine. ### Tool migrations | Tool | Boundary use | |---|---| | `flow-start-recording` | `probe` on `project_root`: present → host persistence exactly as before; absent (remote) → recording kept in server memory, YAML returned as a client-write directive | | `flow-add-step` / `flow-add-echo` / `flow-finish-recording` | follow the session's persist mode; every mutation returns `savedTo` (path locally, directive remotely) so the agent-side file is always current | | `flow-execute` / `flow-read-prerequisite` | `file` input derived from `${project_root}/.argent/flows/${name}.yaml` into an internal `flow_file` param — read in place locally, uploaded when remote | | `screenshot-diff` | `baselinePath`/`currentPath` as `file` inputs; `outputDir` now **optional** (temp default) and probe-ignored when absent on the host | | `react-profiler-component-source`, `gather-workspace-data` | `directory` gate — unchanged locally; clear error remotely instead of a silent empty AST index / all-nulls snapshot | ### Version skew Both halves degrade to today's behavior: an old client sends plain strings (the resolver passes them through, tools take their legacy paths), and an old server doesn't advertise `fileInputs` (the new client never wraps). Wrappers on undeclared params fail the tool's own schema validation, so nothing can be smuggled through free-form args. ## Tests **Unit** (all green: registry 68, tool-server 992, tools-client 107, argent-mcp 66, argent-cli 117): - `tool-server/test/file-inputs.test.ts` — in-place gate, stat-mismatch → upload, truncated-upload rejection, directory gate, probe semantics, undeclared-target smuggling. - `argent-tools-client/test/file-inputs.test.ts` — wrapping (stat-only vs inlined content), multi-param template derivation, explicit-override respect, directive writes incl. path-validation refusals (relative, traversal, outside `.argent/flows`, bad charset/extension). - `tool-server/test/flows/flow-remote-recording.test.ts` — remote recording stays in memory + returns directives, nothing written on the host, replay/read from a boundary-resolved `flow_file`. - Updated existing screenshot-diff / native-profiler tests to the artifact-handle contract. **Local / co-located (unlink scenario)** — isolated tool-server + CLI on an iPhone 17 Pro simulator: full flow record→finish→read-prerequisite→execute loop (YAML written via the same path as before, in-place gate hit, no byte copies); screenshot-diff with and without `outputDir`; wire-level checks of the unlinked client shape (wrapper without content → in-place read) and the legacy plain-string shape; missing-file → 422 with a precise message. **Remote (Lima Linux VM as the agent machine, tool-server on the host Mac, `--host` bind + bearer auth)** — via both the CLI and the real MCP stdio server: - flow recording from the VM: YAML lands **in the VM's project**, `savedTo` rewritten to the VM path, *no* agent-path directories created on the host; replay from the VM uploads the YAML and drives the host simulator. - `screenshot` materializes into the VM temp cache; `screenshot-diff` round-trips both directions (VM baseline uploaded, live capture on host, diff artifacts downloaded back; MCP returns `image,text` content with the context diff inlined). - `gather-workspace-data` / `react-profiler-component-source` with VM-only paths → the new actionable 422. ## Notes - `native-profiler-analyze` was not exercised live (xctrace export is unusable on this machine's iOS 26.4 simulators — known, unrelated); its change is the same one-line `fileArtifact` pattern `react-profiler-analyze` already ships, covered by unit tests. - `react-profiler-analyze`'s own `project_root` (AST resolve stage) is left as-is deliberately: it degrades gracefully (report still renders) and gating it would break currently-working remote analysis. Tracked as follow-up alongside nested invocations (`run-sequence`/`flow-execute` steps bypass the HTTP boundary by design). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-06-12 17:14:04 +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	74c2065ca0	fix: multiple minor bugs (#194) ... ## Human Summary This PR aims to fix bugs that are benign for now, could become serious in the future: - multiple CSRF via CORS misconfiguration on `tool-server` - multiple SSRF that were possible due to the CSRF - path traversal via flow creator - multiple shell injections - lack of auth on `MCP/CLI <-> tool-server` path (bug details discussed in person). After the other fixes this is somewhat redundant, but doesn't hurt and protects against theoretical access attempts from within other processes running on the user's device. ## AI Summary <details> Bundles six independent fixes that together close a CSRF cluster on the local tool-server. The vulnerabilities chain because the HTTP API has no auth and serves wildcard CORS, so any web origin (Firefox unconditionally; Chrome via PNA-disabled or loopback-served) can drive the tool-server from a cross-origin tab. Each individual fix lives on its own branch (linked below) and stands alone — this PR exists so the cluster can be reviewed and shipped as one piece. ### Fixes 1. **`fix(http): require auth token + drop wildcard CORS`** — per-process 32-byte hex Bearer token, generated by the launcher, persisted in `~/.argent/tool-server.json` with mode `0600`, required on every route except `/preview`. Constant-time compare. Wildcard CORS dropped. Threaded through MCP server + CLI + tools-client. Backwards-compat: when `ARGENT_AUTH_TOKEN` is unset (e.g. `npm run dev`), the server logs a one-shot warning and skips the gate. 2. **`fix(http): reject non-loopback Host headers`** — middleware (before the auth gate) returns 403 for any request whose Host is not `127.0.0.1`, `localhost`, or `::1`. Closes DNS-rebinding bypass. 3. **`fix(ios-profiler-start): prevent shell injection via device_id`** — `detectRunningApp(udid)` no longer interpolates `params.device_id` into `execSync` template strings. Both `xcrun simctl spawn ${udid} …` and the piped `xcrun simctl listapps ${udid} | plutil …` are rewritten to `execFileSync` array form, with the pipe to `plutil` happening in JS (input option) rather than the shell. 4. **`fix(flows): validate name to close path-traversal in getFlowPath`** — `getFlowPath()` requires `^[A-Za-z0-9_\\-]+$` and verifies `path.relative(getFlowsDir(), filePath)` does not start with `..`. Centralizing the check in `getFlowPath` covers every caller (start-recording, add-step, insert-echo, finish-recording, run, read-prerequisite) without per-tool churn. 5. **`fix(source-resolver): reject paths outside projectRoot + non-source extensions`** — `readSourceFragment()` previously accepted any `file` field on the SourceLocation it was given (the field traces back to a React fiber's `_debugSource.fileName`, which is attacker-controllable). Now: containment check via `path.relative(projectRoot, abs)` plus an extension allowlist (`.js/.jsx/.ts/.tsx/.mjs/.cjs/.json`). 6. **`fix(source-maps): reject non-loopback URLs (close SSRF)`** — `doRegister()` validates `sourceMapURL` before fetching: only `http://`/`https://` URLs whose hostname is loopback. Closes a blind-SSRF probe of the host network (cloud metadata at `169.254.169.254`, intranet pages, etc.). ### Individual branches - `fix/auth-token-drop-cors` - `fix/host-header-validation` - `fix/profiler-command-injection` - `fix/flow-name-validation` - `fix/source-resolver-traversal` - `fix/source-map-ssrf` If you want to land them as separate PRs, the integration branch can be dropped after each lands. ## Test plan Unit tests (already in CI): - [x] `npm run build` passes (workspace tsc clean) - [x] `npm run test -w @argent/tool-server` — **510 passed (was 473 on `main`)**, +37 new tests across: - `test/http-auth.test.ts` — 10 tests (auth, CORS removal, dev-mode escape hatch) - `test/http-host-validation.test.ts` — 7 tests (loopback allow, DNS-rebinding reject) - `test/flows/flow-utils.test.ts` — +5 tests (path-traversal name rejection) - `test/metro/source-resolver.test.ts` — +5 tests (containment + extension allowlist) - `test/metro/source-maps-ssrf.test.ts` — 10 tests (loopback-only allow) Live end-to-end (run locally against this branch's bundled artifacts): - [x] Launcher spawns tool-server; `~/.argent/tool-server.json` contains a 64-char hex token and is mode `0600` - [x] `GET /tools` without `Authorization` → **401** - [x] `GET /tools` with wrong token → **401** - [x] `GET /tools` with correct token → **200** (61 tools) - [x] Request with `Host: attacker.example` → **403** - [x] No `Access-Control-Allow-Origin` header on responses - [x] Cross-origin command-injection probe via `device_id=\"x;touch /tmp/marker;#\"` does NOT create the marker file (Vuln 4 closed) - [x] `flow-start-recording` with `name=\"../../../tmp/escape\"` rejected with `Invalid flow name` - [x] `flow-start-recording` with a valid name still works - [x] `tools-client.fetchTools()` and `tools-client.callTool('list-simulators')` succeed via the auth-token threading (the path the MCP server uses internally) - [x] MCP-stdio entry point (`startMcpServer`) end-to-end: `initialize` → `tools/list` (61 tools) → `tools/call('list-simulators')` returns content. Confirms the launcher → token → fetch → tool-server flow is intact for the production `argent mcp` path. ## Notes for reviewers - `/preview` is intentionally exempt from the auth gate (it was not gated before; tightening it deserves a separate PR). - The `ARGENT_AUTH_TOKEN`-unset escape hatch keeps `npm run dev` workable; production `argent mcp` always passes a token via env, so the warning never fires there. - The auth bundle changes the public return shape of `ensureToolsServer` from `Promise<string>` to `Promise<{ url, token }>`. The two in-tree callers (`argent-mcp/mcp-server.ts`, `argent-tools-client/tools-client.ts`) were updated; external consumers using `ARGENT_TOOLS_URL` should also set `ARGENT_AUTH_TOKEN` to match the server. </details>	2026-06-03 15:57:42 +02:00
filip131311	ee97c443b7	feat(tool-server): make the update reminder configurable and release-age aware (#276) ... ## Why The tools-server shows an update reminder (a `note` appended to every tool response) once a newer `@swmansion/argent` lands on npm. Two pain points: 1. **No way to turn it off.** Suppression is in-memory only (`dismiss-update`, 30-min auto), so it comes back on every server restart. 2. **It nags about versions you can't install yet.** Registries with a **minimum-release-age** (package-cooldown) security policy refuse to install a version until it has been public for N days. Until then the reminder repeats every day for the whole cooldown window with nothing the user can do about it — exactly the "reminded for 5+ days" situation. ## What's in this PR **1. A config option to disable the reminder** - New env var **`ARGENT_DISABLE_UPDATE_NOTIFICATIONS=1`** (`"1"` or `"true"`). - When set, `startUpdateChecker()` is a no-op: **no registry request** is made and **no note** is ever attached. - The opt-out is also surfaced inside the reminder text itself, so the agent can tell the user how to silence it permanently. **2. Minimum-release-age awareness** (answers "detect the policy and check the update is actually installable first") - The checker now fetches the **npm packument** (`registry.npmjs.org/@swmansion/argent`) instead of `/latest`, because only the packument carries the `time` map of version → publish timestamp. - It detects the machine's policy and only reminds once the latest version has **aged past** it. Notification is gated on a new **`updateInstallable`** flag (newer **and** old enough) rather than `updateAvailable`. - `updateAvailable` keeps its pure version-comparison meaning; with no policy, `updateInstallable === updateAvailable` (no behavior change for users without a policy). ### Is detecting the user's min-age policy possible? Yes — partially. Each package manager stores it differently, and the tools-server has no reliable signal for *which* PM installed argent, so we probe every PM present and take the **most restrictive** (largest) value. Erring toward over-waiting is intentional: a slightly late reminder beats nagging about a forbidden version. | PM | Config key | Unit | Detect via | Min PM version | |----|-----------|------|-----------|----------------| | npm | `min-release-age` | days | `npm config get min-release-age` | 11.10.0 | | pnpm | `minimumReleaseAge` | minutes | `pnpm config get minimumReleaseAge` | 10.16 | | yarn (berry) | `npmMinimalAgeGate` | minutes | `yarn config get npmMinimalAgeGate` | 4.10 | | bun | `minimumReleaseAge` (bunfig.toml `[install]`) | seconds | no `config get` — not auto-probed | 1.3 | | yarn classic | — (unsupported) | — | — | — | Because bun has no `config get` for this and auto-detection is best-effort, there's also an explicit override: - **`ARGENT_MIN_RELEASE_AGE_DAYS`** — positive number of days; wins outright and skips probing (useful for bun users, locked-down CI, or pinning the value). When a policy holds an update back, a single stderr line explains the silence; no reminder reaches the agent. ## Conservative edge handling - Network/registry failure → state unchanged (never crashes the server). - Policy in effect but publish time missing/unparseable → treated as **not** installable (stay silent rather than nag). - PM probe errors / PM absent → treated as no policy (0). - Probes shell out via PATH (`exec`, 3s timeout, constant commands only — no caller input) so Windows `.cmd`/`.ps1` shims resolve. ## Tests - `test/min-release-age.test.ts` (new): unit-level parsing, override precedence, unit normalization, most-restrictive-wins, PM-absent. - `test/update-checker.test.ts`: rewritten for the packument shape; new cases for held-by-policy, aged-past-policy, unknown publish time, and the disable flag (probe mocked so tests never spawn a real PM). - `test/http-update-note.test.ts`: gate now keys off `updateInstallable`; added a "available but held by policy → no note" case. - Full tool-server suite green (**732 tests**), `tsc --noEmit` and `typecheck:tests` clean. ## Follow-up (not in this PR) The env-var reference lives in the `argent-private` submodule (`docs/environment-variables.md`), which is a separate repo — needs a companion PR. Suggested rows for the tools-server table: ``` | `ARGENT_DISABLE_UPDATE_NOTIFICATIONS` | `"1"`/`"true"` or unset | disabled | When truthy, disables the update reminder entirely (no registry check, no note). | | `ARGENT_MIN_RELEASE_AGE_DAYS` | number | _(auto-detect)_ | Minimum age (days) a newer version must reach before it is advertised. Overrides auto-detection of the npm/pnpm/yarn minimum-release-age policy. | ``` ## Open questions for review - **Most-restrictive-across-PMs** vs. detecting a single PM — is "max wins" the behavior we want, or should it follow `npm_config_user_agent`? - Should an update held by policy stay fully silent (current), or emit a softened "available, installable in ~N days" note? --------- Co-authored-by: Cursor <cursoragent@cursor.com>	2026-06-01 17:15:12 +02:00
Ignacy Łątka	f34ce22b9a	fix(tool-server): persist update-note suppression across restarts (#273) ... ## Summary `dismiss-update` (and the auto-suppression after delivering an update note) only stored `suppressUntil` in a module-scoped variable, so the dismissal evaporated the moment the tool-server process exited — which the launcher does after 30 min of idleness, on machine reboot, and on `npx @swmansion/argent update`. Users asking to silence the note for 24 h would see it reappear well within the window, contradicting the tool's own description. This PR persists `suppressUntil` to `~/.argent/update-suppression.json` (alongside the existing `tool-server.json` / `tool-server.log`) and reads it back on module init, so the dismissal survives restarts. - `suppressUpdateNote` now writes through to disk and throws on write failure (matches `dismiss-update`'s documented "Fails if … the suppression state cannot be persisted"). - The HTTP auto-suppress call (after delivering a note alongside an unrelated tool result) is wrapped in try/catch — a disk-write failure there must not 500 the user's tool call. Worst case: the note repeats next request. - Missing/malformed/wrong-typed file all degrade to "no suppression" — never crashes the server. ## Test plan - [x] `npx vitest run test/update-checker.test.ts` — 19/19 pass (10 original + 9 new persistence tests). - [x] `test/http-update-note.test.ts` + `test/http-tools-meta.test.ts` — 14/14 pass (mock update-checker; persistence is transparent). - [x] Full `@argent/tool-server` suite — 726/727 pass. The single failure (`test/android-binary.test.ts:73`, `/usr/bin/adb` resolution) is pre-existing on `main` and unrelated. - [x] `npm run typecheck:tests` clean, `npm run build` clean, `prettier --check` clean. - [x] Restart simulated via `vi.resetModules()` + re-import → suppression loaded back from disk.	2026-06-01 15:18:12 +02:00
Ignacy Łątka	bea43f555a	feat: per-step delayMs on flow steps (#198) ... - Tool steps in a flow YAML may carry an optional `delayMs` that sleeps that long *before* the step runs; `flow-add-step` exposes the same field. - New `longRunning?: boolean` field on `ToolDefinition`; when set, the MCP fetch wrapper bypasses its 30s per-request timeout (`fetchTimeoutMs: null`) so long invocations aren't aborted. `run-sequence` and `flow-execute` opt in.	2026-05-13 18:32:42 +02:00
Ignacy Łątka	d017ba340c	feat: Android emulator support (#148) ... ### For reviewers - what to focus on: The diff is ~6k LoC; this breakdown should help triage where to spend attention: | Bucket | Lines | Effort | | --- | --- | --- | | **Net-new Android logic**: `boot-device.ts` (660) + `adb.ts` (399) + `uiautomator-parser.ts` (292) | 1351 | **Read carefully** | | Blueprint `DeviceInfo` refactor: `simulator-server`, `ax-service`, `native-devtools` | 365 | Read | | Tool `index.ts` / `types.ts` sprawl across ~20 tools (capability gates, `services()`, descriptions) | ~965 | Skim — watch for cross-file consistency | | `platforms/android.ts` impls (stub → real implementation) | ~426 | Skim | | Skill/docs prose, profiler rename ripple | ~1000 | Skim | | **`platforms/ios.ts` deletions** — 12 files, 0 additions; logic moved into unified handlers | 684 | **Skip — mechanical** | ## What works, what doesn't: ### Just works thanks to either sim server or metro: - `gesture-*` - `button`, `keyboard` - `screenshot` - `run-sequence`, `flow-*` - `debugger-*` - `react-profiler-*` ### Adjusted to work on android too: | tool | android | ios | | --- | --- | --- | | `describe` | `uiautomator dump` → `DescribeNode` | `AXServiceApi` | | `launch-app` | `cmd package resolve-activity` + `am start -W` | `simctl launch` | | `restart-app` | `cmd package resolve-activity` + `am force-stop` + `am start -W` | `simctl terminate` + `simctl launch` | | `reinstall-app` | `adb install -r` (+`-g`/`-d`) | `simctl uninstall` + `simctl install` | | `open-url` | `am start -a VIEW -d <url>` | `simctl openurl` | | `list-devices` | `adb devices` + `emulator -list-avds` | `xcrun simctl list --json` | | `boot-device` | snapshot probe → `-force-snapshot-load` hot boot with screencap-alive guard, falls back to cold boot on any failure | `simctl boot` + `bootstatus -b` | ### Will not work on android for now: - `native-devtools-*` (7 total) - `native-profiler-*` (3 total — was `ios-profiler-*`) - `profiler-stack-query`, `profiler-combined-report` (depend on `native-profiler-*`) - `paste` — unregistered on both platforms for now. --------- Co-authored-by: Paweł Fornagiel <pawel.fornagiel2@gmail.com>	2026-05-11 11:39:10 +02:00
filip131311	dbf4de1ab0	refactor(tool-server): per-tool dirs + cross-platform dispatch (iOS only, Android-ready) (#164) ... ## Summary Sets up the foundation for adding Android support without changing any user-visible iOS behavior. iOS works exactly as before; Android handlers are stubs that throw a clear \"not yet implemented\" message until they're filled in. ### New primitives - `Platform`, `DeviceKind`, `DeviceInfo`, `ToolCapability`, `ToolDependency` (in `@argent/registry`) - `classifyDevice(udid)` + `resolveDevice(udid)` (UUID shape → iOS, else Android) - `assertSupported(toolId, capability, device)` — throws `UnsupportedOperationError` - `ensureDep(s)` — host-binary preflight with install hints - `dispatchByPlatform({ toolId, capability, ios, android })` — one-line cross-platform `execute()` ### HTTP gating `/tools/:name` now runs: - Host-binary preflight (`requires`) → 424 with install hint - Capability gate (`capability` + `udid`) → 400 with reason ### Per-tool directory layout Every cross-platform tool now lives in its own directory: \`\`\` tools/gesture-tap/ index.ts ← ToolDefinition, capability, dispatchByPlatform platforms/ ios.ts ← iOS impl (existing logic) android.ts ← stub: throws \"not yet implemented\" \`\`\` Refactored 17 tools this way: gesture-{tap,swipe,custom,pinch,rotate}, screenshot, button, paste, keyboard, launch-app, restart-app, reinstall-app, open-url, rotate, run-sequence, describe (with shared contract + iOS adapters under platforms/). ### Tool call flow (iOS, today) 1. Agent calls \`gesture-tap { udid: \"<uuid>\", x, y }\` 2. HTTP zod-parses, then host-binary preflight, then capability gate (passes — capability has \`apple\`) 3. Tool's \`execute()\` (built by \`dispatchByPlatform\`): - \`resolveDevice(udid)\` → \`{ platform: \"ios\", kind: \"simulator\", id }\` - \`assertSupported\` → passes - branches to \`tapIos(services, params, device)\` 4. iOS impl uses \`SimulatorServerApi\` exactly as before. ### Tool call flow (Android, future) Same flow; the Android branch in \`dispatchByPlatform\` runs. Filling in Android = three steps: 1. Implement the function in \`tools/<tool>/platforms/android.ts\` 2. Add \`android: { emulator: true, device: true, unknown: true }\` to the tool's capability 3. Make \`services()\` platform-aware where the iOS service URN doesn't apply (e.g. \`launch-app\` declares \`nativeDevtools\` for iOS only) ## Test plan - [x] All 395 existing tests pass; 9 new tests for `device-info` + `capability` - [x] TypeScript clean across `@argent/registry` and `@argent/tool-server` - [ ] Manual smoke-test on a real iOS simulator (gesture-tap, screenshot, describe, launch-app) ## Deferred to follow-ups - **Per-tool capability declarations on iOS-only tools** (`native-devtools/*`, `profiler/ios-profiler/*`, `network/*`, `simulator/*`). They still work; the HTTP capability gate is a no-op when no declaration exists. Adding them is mechanical and doesn't affect iOS behavior. - **`list-simulators` / `boot-simulator` rename to `list-devices` / `boot-device`** — that's a behavior change, paired with the Android impls. - **Platform-aware `services()`** for tools whose iOS service has no Android equivalent (e.g. `nativeDevtools` in `launch-app` / `restart-app`). Needed when filling in Android impls.	2026-04-28 15:32:39 +02:00
filip131311	037c474956	Feat: Baseline web UI for the simulator (#158) ... This is a very base line UI: - integrates into the existing simulator server on tools server - does not expose any endpoints via mcp	2026-04-24 15:27:53 +02:00
Ignacy Łątka	acc5798185	feat(mcp): support progressive tool loading via _meta hints (#120) ... * feat(mcp): support progressive tool loading via _meta hints Add optional alwaysLoad and searchHint fields to ToolDefinition, forward them through GET /tools, and emit them as _meta["anthropic/alwaysLoad"] / _meta["anthropic/searchHint"] in the MCP ListTools response. Claude Code's ToolSearch defers MCP tools by default; tools marked alwaysLoad stay in context on every turn, and searchHint feeds the BM25 ranker so deferred tools surface for relevant queries. Mark the core discovery + interaction tools as alwaysLoad so Claude never has to round-trip through ToolSearch to tap the screen: describe, debugger-component-tree, screenshot, gesture-tap, gesture-swipe, launch-app, run-sequence. Everything else defers. * feat(mcp): mark restart-app as alwaysLoad Tools that depend on controlling app startup (relaunch for clean state, refreshing native-devtools injection) need restart-app to be immediately callable rather than routed through a search round-trip.	2026-04-23 17:04:24 +02:00
Ignacy Łątka	112336079e	fix: crash recovery review issues from #135 + other findings (#137) ... * fix: address crash recovery review issues from #135 - crashShutdown now exits with code 1 (was 0 via shared shutdown()) - reconnect() failure no longer aborts the retry loop - health monitor timeout 3s → 10s (avoids false positives on busy server) - ListToolsRequestSchema lets errors propagate (empty list could be cached) - event emitter catches async listener rejections - forceExit timer keeps event loop alive (removed .unref()) - stderr error handler no longer writes to stdout - SIGINT/SIGTERM handlers fall back to process.exit(0) if shutdown is null - fetchTools() checks res.ok * fix: clarify stderr error handler comment * fix: revert stderr handler — stdout fallback is safe The launcher uses readline + regex matching on stdout, so extra non-matching lines are harmlessly discarded. Restore the original stdout fallback for stderr errors. * fix: add fetch timeout, MCP error handlers, and idle timer on GET /tools - fetchWithReconnect: wrap each attempt in an AbortController with a configurable timeout (ARGENT_FETCH_TIMEOUT_MS, default 30s) so a hanging tool-server doesn't wedge the MCP parent indefinitely - MCP parent (mcp-server.ts): install process.stdout/stderr error handlers and uncaughtException/unhandledRejection listeners so an EPIPE from a closed Codex transport doesn't crash the process - GET /tools: touch the idle timer so list_tools polling keeps the tool-server alive between tool calls - Add tests for fetch timeout and idle timer on GET /tools * chore: update showcase GIF asset * Revert "chore: update showcase GIF asset" This reverts commit 2b9379fb05. * fix: add safety timeout to shutdown and validate FETCH_TIMEOUT_MS - shutdown() now has a 5s force-exit safety timeout matching crashShutdown, preventing hangs if server.close() blocks on a lingering connection - ARGENT_FETCH_TIMEOUT_MS is validated: NaN/0/negative values fall back to 30s instead of causing immediate aborts * fix: remove dead null guard on SIGINT/SIGTERM handlers shutdown is always assigned (line 57) before the handlers are registered (line 98-99) in the same synchronous block. The arrow wrapper is still needed to avoid passing the signal string as exitCode. * cleanup unneeded bang op * update comment * update comment * prettier * fix: rewrite fetch-timeout test to not depend on pre-built dist The test spawned `node dist/cli.js mcp` which requires running `npm run build:mcp` first. If the dist is stale (e.g. from main), the old code without the AbortController timeout runs and the test hangs. Rewrite as an in-process test using a replica of the fetchWithReconnect pattern against a hanging HTTP server. * test: add minimal EPIPE → Transport Closed repro Proves the mechanism: a Node child (mimicking argent mcp) without a stdout error handler dies on EPIPE when the parent (mimicking Codex) closes its read end. With the handler, the child survives and the transport stays usable. * revert: remove speculative EPIPE stdout/stderr handlers from MCP parent The EPIPE defense assumed Codex would close its read end of the stdio pipe while the MCP server is still alive. We can't evidence this from the logs — the proven root cause is the fetch-timeout hang (repro #3). Remove the handlers and the EPIPE repro test. * revert emitter promise error handling * use universal process timeout value * remove dubious fixes * remove unused const * rev event emitter to main * revert mcp server to main * move const to file scope --------- Co-authored-by: pFornagiel <pawel.fornagiel2@gmail.com>	2026-04-16 13:57:56 +02:00
Ignacy Łątka	445bc044c1	feat: Add update system to Argent (#78) ... * feat: add update notification and update-argent tool Injects an update note into HTTP responses when a newer version of Argent is available, forwards the note through the MCP server so agents see it prepended to tool results, and adds an update-argent tool that agents can call (with explicit user consent) to apply the pending update. * test: add edge-case tests for update note injection and update-argent tool * fix: guard update-argent against double-spawn and no-op calls, use argent binary * feat: auto-suppress update note for 30min after delivery, add dismiss-update tool * fix: correct npm package name to @software-mansion/argent * fix: use semver ordering for version comparison, guard double-start, handle response stream errors * feat: add update notification and update-argent tool Injects an update note into HTTP responses when a newer version of Argent is available, forwards the note through the MCP server so agents see it prepended to tool results, and adds an update-argent tool that agents can call (with explicit user consent) to apply the pending update. * test: add edge-case tests for update note injection and update-argent tool * fix: guard update-argent against double-spawn and no-op calls, use argent binary * feat: auto-suppress update note for 30min after delivery, add dismiss-update tool * fix: correct npm package name to @software-mansion/argent * fix: use semver ordering for version comparison, guard double-start, handle response stream errors * fix unresolved conflicts * add yarn to gitignore * cleanup typecasting * isolate update note builder * remove unused import * fix package name * change update rate to once per day * add note against using permanent storage mediums * update tool descriptions * fix tests	2026-04-07 17:42:59 +02:00
Filip131311	c8e8669c56	Revert "feat: add update-argent tool and per-response update notification (#74)" ... This reverts commit c9a673e97a.	2026-04-07 10:00:10 +02:00
Ignacy Łątka	c9a673e97a	feat: add update-argent tool and per-response update notification (#74) ... * feat: add update notification and update-argent tool Injects an update note into HTTP responses when a newer version of Argent is available, forwards the note through the MCP server so agents see it prepended to tool results, and adds an update-argent tool that agents can call (with explicit user consent) to apply the pending update. * test: add edge-case tests for update note injection and update-argent tool * fix: guard update-argent against double-spawn and no-op calls, use argent binary * feat: auto-suppress update note for 30min after delivery, add dismiss-update tool * fix: correct npm package name to @software-mansion/argent * fix: use semver ordering for version comparison, guard double-start, handle response stream errors	2026-04-06 20:49:06 +02:00
Filip131311	8c2a313c76	chore: format codebase with Prettier ... Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-03 14:53:58 +02:00
filip131311	aec65427ab	chore: remove license validation (#58) ... * init * init * Delete .vscode/mcp.json	2026-03-31 21:32:08 +02:00
Ignacy Łątka	5ce4ace181	Merge branch 'main' into @latekvo/automation-scripting	2026-03-18 15:40:47 +01:00
Ignacy Łątka	629007ba54	rename	2026-03-17 16:20:57 +01:00
Ignacy Łątka	9c5967602e	add flow prerequisites	2026-03-17 13:13:43 +01:00
Paweł Fornagiel	56a238e9ce	feat: add environment inspector (#24) ... * feat: add first implememntation of environment subagent * chore: remove the irrelavnt skill from main project config * feat: add rules support and enhance postinstall script for Argent tools (#23) * feat: add first implememntation of environment subagent * feat: enhance argent.md with environment inspection subagent details and workspace information retrieval guidelines * feat: introduce argent.md with comprehensive guidelines for iOS simulator interactions and React Native workflows * fix: fix postinstall script * fix: fix Install Argent launch.json job * feat: add environment inspector design document and research notes on MCP error signaling * chore: update .gitignore to include MCP agents and rules directories * fix: update `argent.md` rule with alwaysApply: true for cursor compatibility * chore: remove mcp/rules from index	2026-03-16 21:47:48 +01:00
Ignacy Łątka	11655fa478	rename tools	2026-03-13 08:33:21 +01:00
Ignacy Łątka	47e6d66999	Merge branch 'main' into @latekvo/automation-scripting	2026-03-12 13:56:11 +01:00
Ignacy Łątka	baed3605c8	initial flow impl	2026-03-11 22:39:04 +01:00
pFornagiel	74ec322a70	feat: add more advanced logging on failure	2026-03-11 20:09:08 +01:00
Paweł Fornagiel	badf203d57	feat: add timeout system and process killing capabilities (#14) ... * feat: add termination * refactor: refactor how idletimer is used within index and http server * feat: enhance confirmation message for stopping Metro bundler process	2026-03-11 15:23:38 +01:00