Skip to main content

ADR-0007: VS Code extension as thin client with bundled platform CLI

  • Status: Accepted
  • Date: 2026-06-12
  • Deciders: Michel Gillet

Context​

a2c-vscode-extension provides IDE integration for A2C across VS Code–compatible hosts (VS Code, Cursor, Theia-like environments). Users expect a frictionless experience — install the extension and work — without manually installing Python, virtualenvs, or matching CLI versions.

Alternatives considered:

ApproachDrawback
Extension embeds workflow logicDuplicates a2c_core, diverges from CLI/TUI behavior
Extension discovers arbitrary CLI on PATHVersion skew, support burden, non-deterministic behavior
Extension downloads CLI at runtimeNetwork dependency, complicates enterprise/offline use
Extension supports multiple CLI versionsHigher compatibility matrix cost

A2C adopts thin client + bundled binary for v1.

Decision​

a2c-vscode-extension is a thin client over the A2C CLI/backend:

Thin client​

The extension owns:

  • activation, commands, and host abstractions
  • webviews and visualizations
  • packaged-binary invocation logic — locate, spawn, and communicate with the bundled CLI
  • compatibility shims for VS Code, Cursor, and Theia-like hosts

The extension does not own:

  • workflow engine logic (a2c_core)
  • metadata schemas or repository contracts
  • AI orchestration or prompt execution semantics

All substantive operations invoke the bundled a2c_cli binary (subprocess or equivalent), which delegates to a2c_core in the paired a2c-workflow release build.

Bundled platform-specific CLI​

Each extension release ships with bundled platform-specific CLI binaries built from the matching a2c-workflow release:

RuleDetail
PairingExtension X.Y.Z bundles CLI from a2c-workflow X.Y.Z
Single CLI versionOne CLI build per extension release — no multi-version CLI support
PlatformsAt minimum the platform matrix required by target hosts (for example linux-x64, darwin-arm64, darwin-x64, win-x64)
LocationUnder extension resources (for example resources/cli/<platform>/) — exact path is implementation detail

Host compatibility​

The extension targets VS Code–compatible extension APIs so the same package can run on VS Code, Cursor, and Theia-like hosts with thin host-specific adapters — without forking workflow logic per host.

Rationale​

  • Deterministic automation — known CLI version per extension release
  • Frictionless UX — no separate Python/CLI install for IDE users
  • Thin clients over stable core — one engine semantics path via a2c_cli → a2c_core
  • Supportability — support matrix is extension version = CLI version = core version

Consequences​

Positive​

  • Predictable behavior across IDE hosts
  • Simpler user onboarding and documentation
  • Clear release pipeline: tag a2c-workflow → build CLI artifacts → bundle into extension release

Negative​

  • Extension release artifacts grow with per-platform binaries
  • Every a2c-workflow release that affects CLI requires a new extension release to refresh bundles
  • Platform matrix maintenance (build agents, signing, notarization where applicable)

Still open (implementation)​

  • Binary signing and notarization policy per platform
  • Whether TUI ships inside CLI bundle or remains separate install
  • JSON-RPC vs stdin/stdout CLI protocol details for webview integration

Migration​

When a2c-vscode-extension is bootstrapped:

  1. Record extension ADR-0000 (foundational repo decision)
  2. Wire CI to consume a2c-workflow release artifacts for bundling
  3. Document supported host list and platform matrix in extension README.md

Relationship to other ADRs​

ADRRelationship
ADR-0005Parent — two-repo product split; extension is repo #2
ADR-0006CLI build target is package a2c_cli
ADR-0004Core and extension follow semver tag discipline

References​