feat(examples): add runnable Node.js SDK examples under examples/sdk/

[thymikee]

Summary

• Adds examples/sdk/ with four standalone, typechecked Node.js scripts covering the minimum surface from chore: examples/test-app is a fixture, not an example — rename or add real SDK examples #1463: root client session (createAgentDeviceClient → open → snapshot/tap → close, with typed error handling via AppError/isAgentDeviceError/normalizeAgentDeviceError), agent-device/metro (normalizeBaseUrl/resolveRuntimeTransport), agent-device/contracts (centerOfRect on a snapshot node), and agent-device/batch (runBatch for a custom transport). Each example imports the published agent-device/... subpaths (not relative src/ paths) and has a top comment stating what it demonstrates and its prerequisites.
• examples/sdk/tsconfig.json path-maps those subpaths to src/sdk/ so pnpm typecheck (now also run against this tsconfig) checks the examples in CI without a prior build, workspace link, or publish step — no new CI workflow needed. Running an example for real still resolves agent-device as a self-referencing package after pnpm build.
• src/__tests__/client-api-examples-drift.test.ts guards the examples against drifting from website/docs/docs/client-api.md's subpath API manifest, in both directions. It's picked up automatically by the existing unit-core vitest project (src/**/*.test.ts), so pnpm test:unit already runs it.
• examples/README.md (new) indexes the examples and notes that examples/test-app/ is a fixture, not an example. Per the issue's maintainer decision, examples/test-app is not renamed or moved.

Test plan

• pnpm check:tooling (lint, both typecheck lanes, layering, depgraph, production-exports, mcp-metadata, build, bundle-owner-files) — green
• pnpm test:unit — 524 test files / 4663 tests passed, including the new drift-guard test
• pnpm format:check on the new files — clean

Refs #1463

🤖 Generated with Claude Code

https://claude.ai/code/session_01HDEZF6hT2iSB4ysCU8pos7

---

Generated by Claude Code

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.87 MB	1.87 MB	+320 B
JS gzip	602.0 kB	602.8 kB	+815 B
npm tarball	719.9 kB	720.6 kB	+628 B
npm unpacked	2.52 MB	2.52 MB	+2.6 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.7 ms	28.4 ms	+1.7 ms
CLI --help	56.5 ms	59.0 ms	+2.4 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/agent-device-client.js	-14.0 kB	-4.2 kB
dist/src/cli.js	-1.4 kB	-359 B
dist/src/session.js	-34 B	-8 B

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-28 19:36 UTC

[thymikee]

P1 — the drift guard does not satisfy the issue requirement for the actual client-api.md snippets. It only parses the Public subpath API manifest and compares imported symbol names, so every example can typecheck while a code snippet in the docs has drifted or no longer compiles. Make the docs snippets import/include these examples, or extract and compile the documented TypeScript snippets in the guard.

[thymikee]

Good catch — fixed in 0da436c.

Added test/integration/client-api-doc-snippets.test.ts, which extracts every fenced ```ts block from client-api.md and typechecks it against the real agent-device/* sources (reusing examples/sdk/tsconfig.json's existing paths mapping via tsc --showConfig, so there's one source of truth for the subpath map). It lives in the Node integration lane rather than vitest's unit-core since it spawns a real tsc Program and comfortably blows the unit suite's 2.5s budget. The existing manifest-based guard in src/__tests__/client-api-examples-drift.test.ts is unchanged and still covers the bullet-list-vs-imports check.

Running this against the current doc surfaced three real, pre-existing snippet bugs unrelated to the new examples, which I fixed as part of this:

• sessions.artifacts: result.cloudArtifacts was accessed without narrowing CloudArtifactsResult | DaemonArtifactsResult first — added the 'cloudArtifacts' in result guard.
• Device cloud sessions: platform/device were passed into the createAgentDeviceClient() config, which doesn't accept them — moved to the apps.open() call, matching every other example.
• Android ADB providers: the inline exec handler had no parameter types and failed under strict mode — annotated with the real AndroidAdbExecutorOptions.

It also surfaced two gaps that look like genuine, pre-existing product/API questions rather than doc typos, so I didn't fix them unilaterally — allowlisted in KNOWN_DOC_GAPS with comments instead, pending your call:

1. "Remote Metro helpers" documents prepareRemoteMetro, reloadRemoteMetro, stopMetroTunnel (from agent-device/metro) and resolveRemoteConfigProfile (from agent-device/remote-config) as public, but none of the four are actually re-exported from those subpaths' src/sdk/*.ts files today — only buildBundleUrl/normalizeBaseUrl/resolveRuntimeTransport and the RemoteConfigProfile type are. Doesn't look related to the chore: remove dead code and tune fallow's dead-code rules #1363 dead-code pass; may have been missing for longer. Should these become public SDK exports, or should that doc section be rewritten to drop the remote-Metro-lifecycle workflow?
2. "Web sessions" / audio probe: both pass platform to client.observability.network()/.audio(), but NetworkOptions/AudioOptions have no platform field — even though the CLI's network/audio commands accept --platform for the same use case. Looks like the typed client's contracts are narrower than the CLI here. Want me to add platform to those two contract types in a follow-up, or handle differently?

Happy to open follow-up issues for both if you'd rather track them separately from this PR.

---

Generated by Claude Code

[thymikee]

Review blocker — the new snippet compiler still does not prove the contract required by #1463.

stubFreeNamesAndRecompile turns every TS2304 into a declaration and falls back to any, so a typo or deleted import such as cliet.apps.open() is auto-stubbed and passes on the second compile. Stub only the explicitly recognized continuation names with real SDK-derived types; leave every unknown identifier as a failure, and add a regression proving an unexpected free name fails.

KNOWN_DOC_GAPS also filters six real compile errors from the final assertion, while the test claims every fenced TypeScript snippet compiles. Fix the docs or the actual exported contracts, or narrow/restructure the guard so it does not claim coverage it deliberately suppresses. Finally, this TypeScript integration test should use the repository exec helper instead of importing raw execFileSync, per the process-execution invariant in AGENTS.md.

All checks are green, but the drift acceptance guard remains porous, so this is not ready yet.

[thymikee]

All three addressed in 0cb6fd0:

1. Stubbing hole (cliet.apps.open() typo case). stubFreeNamesAndRecompile now only stubs identifiers in an explicit allowlist (KNOWN_FREE_NAME_STUB_TYPES) — client/androidClient/snapshot (typed against the real SDK return type) plus the doc's own invented host-glue names (runAdbThroughRemoteTunnel, dispatch, bridgeErrorToDaemonResponse, each typed to the real shape they're actually used against, not any). Anything outside that list is left as a genuine "Cannot find name" failure. Added a regression test that runs a cliet typo through the guard and asserts it fails.

2. KNOWN_DOC_GAPS suppressing 6 real errors. Investigated both instead of punting again — turned out both were fixable contracts, not just docs:

• prepareMetroRuntime/reloadMetro (src/metro/client-metro.ts) and stopMetroTunnel (src/metro/metro.ts) already existed, already used internally by the CLI's connect flow, and matched the doc's described workflow almost exactly (same result shape, iosRuntime/androidRuntime) — they just weren't re-exported from agent-device/metro. Same for resolveRemoteConfigProfile and agent-device/remote-config. Added the four exports and fixed the doc's stale names (prepareRemoteMetro→prepareMetroRuntime, reloadRemoteMetro→reloadMetro, profileKey→companionProfileKey on the prepare call).
• NetworkOptions/AudioOptions had no platform field even though the CLI's network/audio commands accept --platform, and the client methods already forward options to the daemon generically (executeCommand('network'|'audio', options)) — a type gap, not a runtime one. Switched both from AgentDeviceRequestOverrides to DeviceCommandBaseOptions, matching PerfOptions' existing pattern.
• The installFromSource snippet was just missing its createAgentDeviceClient import.

KNOWN_DOC_GAPS is gone entirely — every fenced snippet compiles for real now, no suppression list, and the test's assertion matches what it actually verifies.

3. Raw execFileSync. Swapped both call sites to runCmdSync from src/utils/exec.ts per AGENTS.md's process-execution invariant.

All gates green: check:tooling, test:unit (524 files / 4663 tests), check:fallow (clean, including complexity), pnpm typecheck, docs build, and the integration test itself (now 2 tests, both passing).

---

Generated by Claude Code

[thymikee]

Re-reviewed exact head 0cb6fd0: the closed typed free-name allowlist, typo regression, removal of all diagnostic suppressions, and runCmdSync migration genuinely fix the prior blockers. The new exports match existing production implementations. One P2 cleanup remains in website/docs/docs/client-api.md: the prose immediately after the corrected snippet still says reloadRemoteMetro() even though the public/exported API is now reloadMetro(). The compile guard cannot catch prose, so please rename that reference. CI is still running with no failures observed.

[thymikee]

Fixed in 59ea285 — renamed the stray reloadRemoteMetro() prose reference to reloadMetro(). Good catch on that one slipping past the compile guard (fenced code only, not prose). Re-verified the doc-snippet compile test and docs build stay green.

---

Generated by Claude Code

[thymikee]

Re-reviewed exact head 59ea285. The remaining stale reloadRemoteMetro prose reference is corrected to the actual public reloadMetro name. The delta is docs-only, the substantive guard fixes remain intact, and all exact-head checks are green. Ready for human review.