feat: add first-class Vega VVD TV support

[thymikee]

Summary

Closes #1400.

Add Amazon Vega OS TV support for Vega Virtual Devices (VVDs) across the CLI, typed client, daemon routing, capability registry, doctor diagnostics, docs, and the agent-device skill.

• Add an isolated semantic Vega provider backed by the official vega CLI, with focused discovery, lifecycle, remote-input, interactor, plugin, and unsupported-operation modules.
• Support TV lifecycle plus the full remote matrix: Up, Down, Left, Right, Select, Menu, Home, Back; ok/center/enter aliases; preset long press; and exact 0–10000 ms holds.
• Give held remote commands a fixed 10,000 ms transport/startup allowance beyond durationMs; the boundary regression proves a 10,000 ms hold receives a 20,000 ms subprocess timeout.
• Scope initial support to VVDs at discovery, command-descriptor, plugin-capability, doctor, help, documentation, and SkillGym boundaries. Physical Fire TV devices remain unsupported until durable physical discovery/lifecycle/remote evidence exists.
• Document the current AWS Device Farm boundary: its public device platform/API surface remains Android/iOS, so agent-device does not expose Vega/Fire TV through the AWS adapter.

Validation

• pnpm format:check
• pnpm typecheck
• pnpm lint
• pnpm check:layering
• pnpm check:fallow --base origin/main
• pnpm build
• Provider integration: 40 files / 145 tests passed
• Full Vitest: 553 files / 4,631 tests passed
• Coverage: 86.94% statements, 77.62% branches, 92.92% functions, 89.11% lines
• Live Vega VVD: CLI 1.3.2, SDK/VVD 0.23.9221, device VirtualDevice, legacy sample com.amazondeveloper.keplersampleapp.main
  • discovered the running VVD, opened with an explicit serial, and closed the same session cleanly
  • exercised all eight remote buttons, all three Select aliases, 500 ms long press, exact 725 ms hold, and direct Back/Home
  • verified an Appium source transition with focused=true after Down; final session inventory was empty
• The focused SkillGym case builds locally. Both external model runners stopped before producing case output because sandbox DNS resolution failed; no external prompt transmission was retried without approval.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-25 12:02 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.84 MB	1.85 MB	+9.4 kB
JS gzip	587.5 kB	591.2 kB	+3.7 kB
npm tarball	701.9 kB	705.2 kB	+3.3 kB
npm unpacked	2.46 MB	2.47 MB	+10.3 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.2 ms	26.2 ms	+0.0 ms
CLI --help	56.4 ms	55.4 ms	-1.0 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/cli-help.js	+1.5 kB	+446 B
dist/src/session.js	+964 B	+342 B
dist/src/internal/daemon.js	+440 B	+80 B
dist/src/recording-export-quality.js	+263 B	+68 B
dist/src/agent-device-client.js	+134 B	+53 B

[thymikee]

Reviewed exact head 40aa4aaa. Not ready.

P1 — a 10,000 ms exact hold cannot complete inside a 10,000 ms subprocess timeout. pressVegaTvRemote accepts that maximum, then gives the whole Vega CLI invocation the same budget. Startup, transport, and release overhead make the boundary command time out. Budget fixed overhead above durationMs, and make the boundary test inspect the timeout rather than using an immediate mock.

Readiness blocker — physical Vega support is published without physical-device evidence. Help/docs enable and claim physical Fire TV support, but practical evidence covers only a Vega Virtual Device. Attach durable PR-accessible physical discovery/lifecycle/remote evidence or scope the initial claim to VVD; artifacts kept only in a Codex task are unavailable to normal reviewers.

Process blocker — link the motivating issue/PRD. This 70+ file platform surface closes no issue and names no dependency record, so acceptance criteria and sibling ordering cannot be reviewed against repository source of truth.

The production route and VVD coverage otherwise look coherent; all checks are green. External SkillGym model execution remains disclosed residual risk.

[thymikee]

Addressed the confirmed review in 821a8af1e4acd284433eaacbdaa7a0c0c07b61b6.

• Remote timeout boundary: held remote commands now receive durationMs + 10,000 ms for fixed transport/startup overhead. The regression inspects the adapter options directly and proves a 10,000 ms hold is invoked with a 20,000 ms subprocess timeout.
• Validation boundary: initial support is now VVD-only. Physical Fire TV entries are excluded from discovery and rejected by descriptor/plugin capability gates; doctor, CLI help, README, website docs, skill guidance, and SkillGym all state the same boundary. The attached live evidence is explicitly VVD evidence.
• Motivation and acceptance: Add first-class Vega OS TV support for Vega Virtual Devices #1400 is linked with dependencies/sequencing, initial VVD acceptance criteria, and the durable physical-device evidence required before physical support can be admitted.
• AWS Device Farm: remains documented as unsupported for Vega/Fire TV because the public Device Farm platform/API catalog exposes Android/iOS rather than Vega OS.

Validation on this head:

• chained pre-push gate: format, typecheck, lint, full Vitest, then push
• full Vitest: 553 files / 4,631 tests passed
• provider integration: 40 files / 145 tests passed
• coverage: 86.94% statements, 77.62% branches, 92.92% functions, 89.11% lines
• layering, fallow, and build passed
• focused SkillGym case built; its two external runners stopped before case output because sandbox DNS resolution failed, and external prompt transmission was not retried without approval

The PR description and title now reflect the VVD-only scope and retain the live screenshot/source evidence.

[thymikee]

CI is fully green on 821a8af1e4acd284433eaacbdaa7a0c0c07b61b6.

This includes all four smoke matrices, Coverage, Integration Tests, FreeRange, CodeQL analyses, Swift runner compile/compatibility, Typecheck, Lint & Format, Layering Guard, Fallow, packaged CLI, bundle size, and web platform smoke.

[thymikee]

Reviewed exact head 821a8af1e4acd284433eaacbdaa7a0c0c07b61b6. Clean for the VVD-only scope in #1400.\n\nThe boundary is enforced in discovery and capability admission; physical Fire TV remains a separately evidenced follow-up. The timeout regression proves a 10,000 ms hold receives a 20,000 ms subprocess budget, and provider integration covers the daemon route through lifecycle, remote controls, aliases, exact hold, and teardown. CI is green.\n\nResidual risk: external SkillGym runners were blocked by DNS, and no cross-vendor review was authorized.

[thymikee]

Addressed the attached architecture/correctness review in commit dd20c74c9 (dd20c74c9a145f24e02715f5a656cbd4b19fd221).

What changed:

• Replaced per-platform unsupported stubs with one exhaustive shared interactor base. Required operations fail with typed UNSUPPORTED_OPERATION; optional selector/viewport/gesture members stay absent, so optional dispatch still returns undefined.
• Replaced the boolean-array Vega open guard with variant-specific URL, activity, launch-console, relaunch, and launch-argument errors/hints.
• Removed duplicate Vega duration validation. The shared TV contract remains authoritative, while the transport regression still proves a 10,000 ms hold receives a 20,000 ms subprocess timeout (10,000 ms hold plus fixed 10,000 ms startup/transport overhead).
• Exported and reused one serial-addressable-platform predicate across selection, open, serialization, and client normalization. Explicit Android/Vega serials now survive in both identifiers.serial and their platform blob; inapplicable client blobs are omitted instead of emitted as undefined fields.
• Reused the Vega device-list parser in doctor and made discovery explicitly VVD-only. A physical-only CLI result now fails with a targeted DEVICE_NOT_FOUND and VVD startup guidance instead of silently returning an empty inventory.
• Deepened the provider seam: platform callers use semantic methods, while argv construction is owned by a two-method local CLI adapter. Successful CLI resolution is cached without caching absence, so an SDK installed later can still be detected.
• Kept emulator-kind ownership in the command descriptor and TV-target ownership in the plugin; the full VVD predicate remains only for the actionable physical-device capability hint.
• Routed core inventory directly to the Vega discovery module, matching neighboring platform branches.
• Removed the lifecycle wrapper, reused constant execution options, dropped the redundant Vega device subtype, and consolidated duplicate Vega help into one section.

Support scope remains the linked PRD boundary: initial support is Vega Virtual Device only until durable physical Fire TV lifecycle/remote evidence exists. This does not broaden claims to physical Vega hardware. Motivation, dependencies, and acceptance criteria remain tracked in #1400.

Validation on the pushed tree:

• pnpm format:check, pnpm typecheck, pnpm lint
• pnpm check:layering — 886 source files, no value cycles or target-spine back-edges
• pnpm check:fallow --base origin/main — no issues in 74 changed files; no dead code or duplication
• pnpm build
• pnpm exec vitest run --coverage --maxWorkers=1 --fileParallelism=false — 553 files / 4,633 tests passed, including all provider-integration, interaction-contract, Vega transport, client normalization, and boundary tests; 86.95% statements / 89.12% lines
• pnpm test:integration:node — 15 passed, 6 opt-in live tests skipped
• final chained pre-push focused suite — 15 files / 78 tests passed, followed by git push

The repository affected planner initially exposed host-load timeouts while running many projects concurrently. Every failed file was rerun serially, the last Apple runner cancellation case passed alone in 0.77 s, and the full serialized coverage run above completed green. No manual device session was opened by this follow-up.

[thymikee]

Re-reviewed exact head dd20c74. The Vega boundary-tightening delta is code-clean: descriptor/plugin/discovery/provider routing remains coherent, physical listings fail with a typed actionable error, unsupported open variants are explicit, and focused tests cover argv, remote keys/budgets, lifecycle, capability, serialization, and unsupported operations. The branch is not merge-ready, however: GitHub reports CONFLICTING/DIRTY, with the reproducible overlap in CONTEXT.md between upstream architecture text and the VVD-only Vega model. Only five CodeQL checks exist on this head; the prior full-green suite was for 821a8af. Rebase, preserve both meanings in CONTEXT.md, and rerun current-head checks. The coordinator removed ready-for-human until that evidence exists.

[thymikee]

Superseding head after rebasing onto current origin/main (14be01b78):

• Exact PR head: 948a718b596ce8ef408f8da9523d0696ff0bedab
• GitHub now reports mergeable: MERGEABLE; the previous DIRTY state is resolved.
• The only content conflict was CONTEXT.md. Resolution preserves current main domain guidance plus the VVD-only Vega platform model. The review-fix commit replayed without conflict.

Validation repeated on this exact rebased tree:

• format, typecheck, lint, layering (891 source files), fallow (no issues in 73 PR files), and build passed
• serialized full coverage: 557 files / 4,703 tests passed; 87.12% statements / 89.29% lines
• Node integration: 15 passed / 6 opt-in live tests skipped
• final chained focused pre-push suite: 15 files / 78 tests passed
• lease-protected force push succeeded only against the expected prior remote head

The short hash in the prior disposition comment referred to the pre-rebase commit; this exact head and validation supersede it.

[thymikee]

Latest review sweep completed on exact head 948a718. GitHub currently has no review threads, no submitted reviews, and no newer actionable comments. The PR is MERGEABLE and every current-head status check is successful. I restored ready-for-human, which had been removed only while the pre-rebase head was conflicting. The timeout boundary, VVD-only scope, and linked #1400 acceptance/dependency record remain addressed on this head.