Refactor external agent runtime lifecycle

[lpcox]

Summary

Stack layer 1/6.

• introduce a typed external agent runtime backend lifecycle and resolver/adapter seam
• move sbx-specific preflight, environment construction, reflection checks, diagnostics, execution state, and teardown out of main-action
• route cleanup and signal fast-stop through the selected backend instance
• keep Docker and gVisor on the existing Compose path without abstracting Compose internals
• document how future microVM backends register without adding Firecracker behavior

Behavior is intentionally unchanged for Docker, gVisor, and sbx, including API-proxy reflection, credential environment handling, diagnostics, timeout/TTY behavior, keep-containers semantics, and exit-code propagation.

Validation

• tsc --noEmit -p tsconfig.check.json
• focused Jest suites: 118 tests across runtime resolver/adapter, sbx lifecycle, container runtime, main action, and CLI workflow
• npm run build

Stack

1. Runtime backend abstraction (this PR)
2. Firecracker runtime implementation
3. Runtime-specific networking and environment integration
4. Firecracker lifecycle hardening
5. Integration and platform coverage
6. Rollout documentation and final wiring

[github-actions]

Documentation Preview

Documentation build failed for this PR. View logs.

Built from commit a605c26

[github-actions]

✅ Coverage Check Passed

Overall Coverage

Metric	Base	PR	Delta
Lines	94.09%	94.14%	📈 +0.05%
Statements	93.06%	93.12%	📈 +0.06%
Functions	94.47%	94.54%	📈 +0.07%
Branches	86.27%	86.33%	📈 +0.06%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
src/commands/main-action.ts	95.8% → 94.7% (-1.12%)	95.3% → 94.8% (-0.57%)
src/log-directory-setup.ts	96.2% → 100.0% (+3.78%)	96.3% → 100.0% (+3.71%)

✨ New Files (3 files)

• src/external-runtime-backend-resolver.ts: 100.0% lines
• src/external-runtime-backend.ts: 100.0% lines
• src/sbx-runtime-backend.ts: 98.5% lines

---

Coverage comparison generated by scripts/ci/compare-coverage.ts

[Copilot]

Pull request overview

Introduces an external runtime lifecycle abstraction while preserving Compose handling for Docker and gVisor.

Changes:

• Adds backend contracts, resolution, and adaptation.
• Moves sbx lifecycle logic out of main-action.
• Adds lifecycle tests and extension documentation.

Show a summary per file

File	Description
src/sbx-runtime-backend.ts	Implements the sbx backend lifecycle.
src/sbx-runtime-backend.test.ts	Tests sbx lifecycle behavior.
src/external-runtime-backend.ts	Defines and adapts external backends.
src/external-runtime-backend.test.ts	Tests resolution and adaptation.
src/external-runtime-backend-resolver.ts	Registers and resolves backends.
src/container-runtime.ts	Updates microVM extension guidance.
src/commands/main-action.ts	Integrates backend execution and cleanup.
src/commands/main-action.test.ts	Tests resolver failure handling.
src/commands/main-action-coverage-gaps.test.ts	Tests external-backend signal handling.
src/cli-workflow.ts	Exports the workflow dependency contract.
docs/sbx-integration.md	Documents backend registration.

Review details

Tip

Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 11/11 changed files
• Comments generated: 1
• Review effort level: Balanced

[github-actions]

✅ Copilot review passed with no inline comments.

@lpcox Add the ready-for-aw label to this PR to trigger agentic CI smoke tests.