mirror of
https://github.com/software-mansion/argent.git
synced 2026-09-14 19:27:14 +08:00
filip131311
4975ff490c
## 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)
69 lines
2.6 KiB
TypeScript
69 lines
2.6 KiB
TypeScript
import { describe, it, expect, afterEach, vi } from "vitest";
|
|
|
|
vi.mock("@argent/telemetry", async (importOriginal) => {
|
|
const actual = await importOriginal<typeof import("@argent/telemetry")>();
|
|
return { ...actual, track: vi.fn() };
|
|
});
|
|
|
|
import { track } from "@argent/telemetry";
|
|
import { trackDebuggerOutcome } from "../../src/tools/debugger/not-connected";
|
|
import { rememberDeviceAlias, forgetDeviceAlias } from "../../src/utils/debugger/device-alias";
|
|
|
|
const mockTrack = vi.mocked(track);
|
|
|
|
/**
|
|
* The platform dimension of debugger:tool_outcome must classify the id the
|
|
* caller CONNECTED with, not the raw param: agents follow debugger-connect's
|
|
* contract and forward the returned logicalDeviceId (an opaque 40-hex Metro
|
|
* handle) on every subsequent call, and that shape fails the iOS-UDID test in
|
|
* classifyDevice — without the alias rewrite every iOS Metro session lands in
|
|
* telemetry as "android" (observed live), which is exactly the per-platform
|
|
* dashboard this event exists to power.
|
|
*/
|
|
|
|
const LOGICAL_ID = "8b9223b1392be193fa9058e0cef5cefb2bddeb68";
|
|
const IOS_UDID = "BE1DCAD9-43CE-40C4-B8B2-9CB30BC03227";
|
|
|
|
afterEach(() => {
|
|
forgetDeviceAlias(LOGICAL_ID);
|
|
mockTrack.mockClear();
|
|
});
|
|
|
|
describe("trackDebuggerOutcome platform classification", () => {
|
|
it("classifies a forwarded Metro logicalDeviceId via its learned alias — ios, not android", () => {
|
|
rememberDeviceAlias(LOGICAL_ID, IOS_UDID);
|
|
trackDebuggerOutcome("debugger-status", "connected", { device_id: LOGICAL_ID }, undefined);
|
|
expect(mockTrack).toHaveBeenCalledWith(
|
|
"debugger:tool_outcome",
|
|
expect.objectContaining({ platform: "ios" })
|
|
);
|
|
});
|
|
|
|
it("an id with no learned alias keeps the shape-based fallback (android)", () => {
|
|
trackDebuggerOutcome("debugger-status", "connected", { device_id: LOGICAL_ID }, undefined);
|
|
expect(mockTrack).toHaveBeenCalledWith(
|
|
"debugger:tool_outcome",
|
|
expect.objectContaining({ platform: "android" })
|
|
);
|
|
});
|
|
|
|
it("chromium ids classify as chromium (the alias map never rewrites them)", () => {
|
|
trackDebuggerOutcome(
|
|
"debugger-log-registry",
|
|
"cdp_unreachable",
|
|
{ device_id: "chromium-cdp-54427" },
|
|
undefined
|
|
);
|
|
expect(mockTrack).toHaveBeenCalledWith(
|
|
"debugger:tool_outcome",
|
|
expect.objectContaining({ platform: "chromium" })
|
|
);
|
|
});
|
|
|
|
it("omits platform entirely when there is no device_id", () => {
|
|
trackDebuggerOutcome("debugger-status", "metro_not_running", {}, undefined);
|
|
const props = mockTrack.mock.calls.at(-1)![1] as Record<string, unknown>;
|
|
expect("platform" in props).toBe(false);
|
|
});
|
|
});
|