software-mansion__argent

skills/software-mansion__argent

Fork 0

mirror of https://github.com/software-mansion/argent.git synced 2026-09-14 19:27:14 +08:00

Commit Graph

Author	SHA1	Message	Date
Mateusz Aliyev	6e9e45c9f0	feat: attach to devices offered by external providers (#735 ) This pull request lets Argent drive a simulator or emulator another process is already running, attaching to its simulator-server rather than spawning a second one. A provider writes a JSON descriptor to `~/.argent/providers/` listing the devices it offers and the mechanisms Argent may use on each. They appear in `list-devices` with an `ext:` id and work with the existing tools. The file is re-read on every call, so a withdrawal or a narrowed grant applies immediately. `ios.additionalDeviceSets` (#600) already makes such a simulator reachable by UDID. What changes is ownership. `boot-device` and `stop-simulator-server` refuse these devices, anything the provider did not grant is refused with a message naming it and Argent uses only the endpoints its own simulator-server build serves. A grant binds to the device rather than to one of its names, so the real udid or serial is gated exactly like the `ext:` id. Android emulators are covered too and a device visible to both a provider and `adb`/`simctl` is listed once. The contract ships as `schemas/device-provider-v1.json`, validated by `argent providers check`, and is documented in `docs/reference/device-providers.mdx`. Includes unit tests and an e2e phase where the harness acts as its own provider. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * New Features * Added support for discovering and connecting to externally managed devices. * Added `argent providers` commands for listing, validating, publishing, withdrawing, and pruning providers. * Added provider-aware simulator, debugger, profiler, native tools, and device listings. * Added capability controls, endpoint validation, revocation handling, and provider-specific diagnostics. * Added automatic CLI discovery for provider integrations. * Bug Fixes * Improved service recovery and paused-runtime error reporting. * Improved simulator keyboard and paste command reliability. * Documentation * Documented provider descriptors, capabilities, lifecycle rules, and CLI usage. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-04 22:02:57 +02:00
Ignacy Łątka	a2ed83e041	fix(tool-server): await the simulator-server command ack so a lost tap fails (#985 ) ## The defect `sendCommand` returns `void`. It writes the JSON command onto the WebSocket — or queues it behind `once("open")` — and returns without ever reading the reply: ```ts export function sendCommand(api, cmd): void { const ws = getOrCreateWs(api); const payload = JSON.stringify({ id: String(++cmdId), ...cmd }); if (ws.readyState === WebSocket.OPEN) ws.send(payload); else ws.once("open", () => ws.send(payload)); // queued, never awaited } ``` simulator-server does acknowledge every command; argent just never looked. Probing the shipped binary's `/ws` endpoint: \| sent \| reply \| \|---\|---\| \| `{"id":"1","cmd":"touch","type":"Down",…}` \| `{"id":"1","status":"ok"}` \| \| `{"id":"7","cmd":"button","button":"notARealButton"}` \| `{"status":"error","message":"parse error: unknown variant `notARealButton`…"}` \| Because the return type was `void` there was no ack to check and no error to surface, so `gesture-tap` ended in an unconditional `return { tapped: true, timestampMs }`. Repro: shut a simulator down underneath an open session. The server sends no reply at all and `gesture-tap` still reports `{ tapped: true }`. Every transport failure — that one, a dead socket, a wedged device — looks identical to success from the agent's side. This is argent's own bug, and it is what turns an Apple regression into a silent one: awaiting the reply would have made #932 an actionable failure on day one instead of a silent no-op. ## The fix `sendCommand` now returns a promise that resolves on `{"status":"ok"}` and rejects when: \| condition \| `error_code` \| \|---\|---\| \| server answers `status: "error"` \| `SIMULATOR_COMMAND_REJECTED` \| \| socket fails or closes with the command in flight \| `SIMULATOR_COMMAND_TRANSPORT_FAILED` \| \| reachable server never answers (5s) \| `SIMULATOR_COMMAND_ACK_TIMEOUT` \| Every WebSocket call site awaits it: `gesture-tap`, `gesture-swipe`, `gesture-custom`, `gesture-pinch`, `gesture-rotate`, `button`, `rotate`. Two details of the wire protocol shaped the implementation: - A success reply echoes the command id; an error reply carries no id at all. So a rejection can only be matched positionally, against the oldest outstanding command. Since every send is awaited, that is normally the only one in flight. - The abort paths in `gesture-swipe` / `gesture-rotate` lift the finger before unwinding, and that lift is now fallible. It is therefore best-effort: a refused lift rides along as the `AbortError`'s `cause` rather than replacing it — matching the existing pattern in `gesture-drag`, because `format-error.ts` and `cdp-session.ts` key on `err.name === "AbortError"`. ## Verified on a real simulator Before, after shutting the device down mid-session: `{"tapped": true}`. After: ``` result: {"tapped":true,"timestampMs":…} ← healthy tap, unchanged --- simulator shut down underneath the open session --- tap FAILED as it should: code: SIMULATOR_COMMAND_TRANSPORT_FAILED msg : simulator-server did not accept the 'touch' command: connect ECONNREFUSED 127.0.0.1:62818. The command was NOT delivered to the device. … ``` The failure signal is fully populated for telemetry (`error_kind: "network"`, `network_failure: "connection_reset"`, `failure_command: "simulator_server"`). ## Cost An ack is a localhost round-trip behind an already-open socket: 0.06ms p50 / 0.17ms max, measured over 200 sends against a booted iOS sim. Awaiting one per event adds a flat ~30ms to a swipe of any duration — against the 36–142ms of `setTimeout` skew the 16ms frame loop already carries: \| `durationMs` \| wall before \| wall after \| added \| \|---\|---\|---\|---\| \| 200 \| 236ms \| 266ms \| +30ms \| \| 500 \| 559ms \| 591ms \| +31ms \| \| 1000 \| 1142ms \| 1178ms \| +35ms \| Flagging it explicitly since the swipe cadence is deliberately tuned. If reviewers would rather keep the cadence byte-identical, the alternative is to pipeline within a gesture and await all acks at the end; that costs more code and defers failure to the end of the gesture, so I kept the simpler per-send await. ## Deliberately out of scope - The MoQ (`ios-remote`) transport is unchanged — it has no equivalent ack. - The stdin `pressKey` channel, used by `keyboard` and paste's ⌘V, is untouched: simulator-server never replies on stdin, so it has the same blind spot with no local remedy. The WebSocket protocol does expose an acked `key` command (`{"cmd":"key","direction":"Down","code":4}` → `{"status":"ok"}`), so moving those onto it would close the gap — a separate, riskier change to the text-entry path that deserves its own PR. ## Tests `packages/tool-server/test/simulator-command-ack.test.ts` — 8 tests against a fake `/ws` server that mirrors the real wire format, all 8 fail on `main`: ack resolves, `status: error` rejects, socket death rejects in flight, silent server times out, no phantom success, `gesture-tap` throws instead of claiming a rejected tap, and the aborted swipe still reports `AbortError`. Full suite: 369 files / 4840 tests pass, `npm run lint` clean, `tsc --build` clean. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_011bEvNDV7o3CpKdFmzjVBYF <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * New Features * Simulator commands now confirm successful delivery before completing. * Added clear errors for rejected commands, connection failures, and acknowledgement timeouts. * Bug Fixes * Button, rotation, tap, swipe, pinch, and custom gestures now report failures instead of silently succeeding. * In-progress gestures handle connection interruptions and cleanup failures more reliably. * Tests * Added coverage for command acknowledgements, rejections, timeouts, transport failures, and gesture error handling. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: latekvo <f.kaminski2000@gmail.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-31 18:31:53 +02:00

Author

SHA1

Message

Date

Mateusz Aliyev

6e9e45c9f0

feat: attach to devices offered by external providers (#735 )

This pull request lets Argent drive a simulator or emulator another
process is already running, attaching to its simulator-server rather
than spawning a second one.

A provider writes a JSON descriptor to `~/.argent/providers/` listing
the devices it offers and the mechanisms Argent may use on each. They
appear in `list-devices` with an `ext:` id and work with the existing
tools. The file is re-read on every call, so a withdrawal or a narrowed
grant applies immediately.

`ios.additionalDeviceSets` (#600) already makes such a simulator
reachable by UDID. What changes is ownership. `boot-device` and
`stop-simulator-server` refuse these devices, anything the provider did
not grant is refused with a message naming it and Argent uses only the
endpoints its own simulator-server build serves. A grant binds to the
device rather than to one of its names, so the real udid or serial is
gated exactly like the `ext:` id. Android emulators are covered too and
a device visible to both a provider and `adb`/`simctl` is listed once.

The contract ships as `schemas/device-provider-v1.json`, validated by
`argent providers check`, and is documented in
`docs/reference/device-providers.mdx`. Includes unit tests and an e2e
phase where the harness acts as its own provider.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added support for discovering and connecting to externally managed
devices.
* Added `argent providers` commands for listing, validating, publishing,
withdrawing, and pruning providers.
* Added provider-aware simulator, debugger, profiler, native tools, and
device listings.
* Added capability controls, endpoint validation, revocation handling,
and provider-specific diagnostics.
  * Added automatic CLI discovery for provider integrations.
* **Bug Fixes**
  * Improved service recovery and paused-runtime error reporting.
  * Improved simulator keyboard and paste command reliability.
* **Documentation**
* Documented provider descriptors, capabilities, lifecycle rules, and
CLI usage.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

2026-09-04 22:02:57 +02:00

Ignacy Łątka

a2ed83e041

fix(tool-server): await the simulator-server command ack so a lost tap fails (#985 )

## The defect

`sendCommand` returns `void`. It writes the JSON command onto the
WebSocket — or queues it behind `once("open")` — and returns without
ever reading the reply:

```ts
export function sendCommand(api, cmd): void {
  const ws = getOrCreateWs(api);
  const payload = JSON.stringify({ id: String(++cmdId), ...cmd });
  if (ws.readyState === WebSocket.OPEN) ws.send(payload);
  else ws.once("open", () => ws.send(payload));   // queued, never awaited
}
```

simulator-server *does* acknowledge every command; argent just never
looked. Probing the shipped binary's `/ws` endpoint:

| sent | reply |
|---|---|
| `{"id":"1","cmd":"touch","type":"Down",…}` |
`{"id":"1","status":"ok"}` |
| `{"id":"7","cmd":"button","button":"notARealButton"}` |
`{"status":"error","message":"parse error: unknown variant
`notARealButton`…"}` |

Because the return type was `void` there was no ack to check and no
error to surface, so `gesture-tap` ended in an unconditional `return {
tapped: true, timestampMs }`.

**Repro:** shut a simulator down underneath an open session. The server
sends no reply at all and `gesture-tap` still reports `{ tapped: true
}`. Every transport failure — that one, a dead socket, a wedged device —
looks identical to success from the agent's side.

This is argent's own bug, and it is what turns an Apple regression into
a silent one: awaiting the reply would have made #932 an actionable
failure on day one instead of a silent no-op.

## The fix

`sendCommand` now returns a promise that resolves on `{"status":"ok"}`
and rejects when:

| condition | `error_code` |
|---|---|
| server answers `status: "error"` | `SIMULATOR_COMMAND_REJECTED` |
| socket fails or closes with the command in flight |
`SIMULATOR_COMMAND_TRANSPORT_FAILED` |
| reachable server never answers (5s) | `SIMULATOR_COMMAND_ACK_TIMEOUT`
|

Every WebSocket call site awaits it: `gesture-tap`, `gesture-swipe`,
`gesture-custom`, `gesture-pinch`, `gesture-rotate`, `button`, `rotate`.

Two details of the wire protocol shaped the implementation:

- **A success reply echoes the command id; an error reply carries no id
at all.** So a rejection can only be matched positionally, against the
oldest outstanding command. Since every send is awaited, that is
normally the only one in flight.
- **The abort paths in `gesture-swipe` / `gesture-rotate` lift the
finger before unwinding, and that lift is now fallible.** It is
therefore best-effort: a refused lift rides along as the `AbortError`'s
`cause` rather than replacing it — matching the existing pattern in
`gesture-drag`, because `format-error.ts` and `cdp-session.ts` key on
`err.name === "AbortError"`.

## Verified on a real simulator

Before, after shutting the device down mid-session: `{"tapped": true}`.
After:

```
result: {"tapped":true,"timestampMs":…}          ← healthy tap, unchanged

--- simulator shut down underneath the open session ---
tap FAILED as it should:
   code: SIMULATOR_COMMAND_TRANSPORT_FAILED
   msg : simulator-server did not accept the 'touch' command: connect ECONNREFUSED
         127.0.0.1:62818. The command was NOT delivered to the device. …
```

The failure signal is fully populated for telemetry (`error_kind:
"network"`, `network_failure: "connection_reset"`, `failure_command:
"simulator_server"`).

## Cost

An ack is a localhost round-trip behind an already-open socket: **0.06ms
p50 / 0.17ms max**, measured over 200 sends against a booted iOS sim.
Awaiting one per event adds a flat **~30ms to a swipe of any duration**
— against the 36–142ms of `setTimeout` skew the 16ms frame loop already
carries:

| `durationMs` | wall before | wall after | added |
|---|---|---|---|
| 200 | 236ms | 266ms | +30ms |
| 500 | 559ms | 591ms | +31ms |
| 1000 | 1142ms | 1178ms | +35ms |

Flagging it explicitly since the swipe cadence is deliberately tuned. If
reviewers would rather keep the cadence byte-identical, the alternative
is to pipeline within a gesture and await all acks at the end; that
costs more code and defers failure to the end of the gesture, so I kept
the simpler per-send await.

## Deliberately out of scope

- **The MoQ (`ios-remote`) transport** is unchanged — it has no
equivalent ack.
- **The stdin `pressKey` channel**, used by `keyboard` and paste's ⌘V,
is untouched: simulator-server never replies on stdin, so it has the
same blind spot with no local remedy. The WebSocket protocol *does*
expose an acked `key` command
(`{"cmd":"key","direction":"Down","code":4}` → `{"status":"ok"}`), so
moving those onto it would close the gap — a separate, riskier change to
the text-entry path that deserves its own PR.

## Tests

`packages/tool-server/test/simulator-command-ack.test.ts` — 8 tests
against a fake `/ws` server that mirrors the real wire format, **all 8
fail on `main`**: ack resolves, `status: error` rejects, socket death
rejects in flight, silent server times out, no phantom success,
`gesture-tap` throws instead of claiming a rejected tap, and the aborted
swipe still reports `AbortError`.

Full suite: 369 files / 4840 tests pass, `npm run lint` clean, `tsc
--build` clean.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_011bEvNDV7o3CpKdFmzjVBYF

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Simulator commands now confirm successful delivery before completing.
* Added clear errors for rejected commands, connection failures, and
acknowledgement timeouts.
* **Bug Fixes**
* Button, rotation, tap, swipe, pinch, and custom gestures now report
failures instead of silently succeeding.
* In-progress gestures handle connection interruptions and cleanup
failures more reliably.
* **Tests**
* Added coverage for command acknowledgements, rejections, timeouts,
transport failures, and gesture error handling.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: latekvo <f.kaminski2000@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-31 18:31:53 +02:00

2 Commits