Provider wiring plan (follow-up edits to existing CLI modules)

Status (2026-10-13): wiring is done for the sandbox path; this file is now the record of the plan plus the list of what is still open. provider is a command group, --provider / --opt / --all-providers and qualified ids work, Sandbox.create/connect/list/killById select the provider, SandboxNotFoundError (E2009) exists, network.resolve routes through ports.url, and an OpenSandbox server was driven end to end from the CLI (evidence). Sections 1 to 8 below are kept as the original plan; ignore any item that the code already does. The open items are in the section "10. Known gaps". Earlier status: handoff note, no existing command module edited. Grammar, help text and JSON shapes are owned by providers-and-credentials-cli.md; this file only says where each piece plugs in.

中文版: ../zh/design/provider-wiring-plan.md

0. What already exists (do not rewrite)

Everything below is wiring. Names are the Python names, snake_case on the wire.

1. Preconditions

1. Version bump: package.json and src/**/_version to 0.3.0 in lockstep with python-sdk (_version.py). The reference plugins declare compat.requires = { cli = ">=0.3" }; tests currently pass hostVersion: "0.3.0" explicitly. After the bump, drop that override in tests/_support/plugins.ts (TEST_HOST_VERSION).
2. package.json: files already ships dist; no change needed because src/providers/** compiles into it. Add "./providers" to exports only if a library entry is wanted (optional). The manifest parser uses the in-repo src/utils/toml_plain.ts; no new dependency was added.
3. models/errors.ts: add SandboxNotFoundError (code E2009, mirror of Python models/errors.py). providers/errors.ts#exitCodeFor must map it to exit code 4 (the Python mapping already does).
4. protocol/sandbox.ts: raise SandboxNotFoundError on HTTP 404 for get, connect, set_timeout, pause, resume (and kill returns false, unchanged), as Python does.
5. models/sandbox.ts: SandboxConfig gains secure?: boolean and provider_options?: Record<string, unknown>. The built-in adapter currently uses Object.assign to carry them; replace with real fields. ProcessInfo.pid becomes number | string (exec providers use string process_id; the adapter currently returns a plain object for string ids).
6. api/network.ts: add resolve(port) / resolve_url(port) that go through ports.url for non-envd providers (Python api/network.py gained +22 lines). Built-in behaviour unchanged.

2. src/api/sandbox.ts (the API layer)

Current seam: _buildInfra(opts) at the top builds loadConfig → createAuthProvider → HttpClient → SandboxProtocol, and Sandbox.create/connect/list/killById call it (lines around create, connect, list, killById).

Edits:

1. BuildInfraOptions gains provider?: string | null and provider_options?: Record<string, unknown> | null.
2. _buildInfra becomes: const p = getProvider(resolveProviderId(opts.provider)); if p.id === BUILTIN_PROVIDER_ID run the existing code path verbatim (keeps every mock/spy-based test byte-identical); otherwise const infra = await p.buildInfra(loadLayeredConfig(overrides)) and map ProviderInfra to the same tuple shape. _buildInfra therefore becomes async only on the plugin branch; keep a sync fast path for built-in (or make the tuple return a promise and await it at the 4 call sites).
3. Sandbox.create(template, { provider, provider_options, secure, ... }): pass provider_options and secure into SandboxConfig; call p.require("sandbox.create")-style feature gates through the adapters (already done inside ExecProvider).
4. Sandbox.connect(ref) / killById(ref): const [pid, sid] = parseSandboxRef(ref); a prefix selects the provider (E8030 ProviderMismatchError when it conflicts with an explicit --provider). Un-prefixed ids use the ambient provider.
5. Sandbox.list({ provider }) unchanged for one provider. listAllProviders() (new static) iterates listProviders(), calls each provider's list, tolerates per-provider failure (returns { results, errors }), and tags rows with qualify(providerId, id).
6. Instances produced by an exec provider carry envd_url when the plugin returns one: keep the existing envd transport for exec/files/PTY (hybrid mode, implemented in ExecProvider).
7. Un-skip the two it.todo tests in tests/test_providers/test_sandbox_provider.test.ts (Sandbox.connect('provider:id') mismatch → E8030, and the built-in default path).

api/commands.ts: no routing change; Commands.run/start/... already take the ProcessProtocol from the sandbox. Only needed: accept string pids in kill/connect/send_stdin signatures (follows the ProcessInfo.pid widening).

3. src/cli/main.ts and command_surface.ts

1. Register the command group: in GROUP_COMMANDS (src/cli/command_surface.ts) add provider: "commands/provider:provider"; abx --help lists it under its own Providers heading.
2. Root group options (root-level and leaf-level, leaf wins; spec §4):
3. --provider ID (envvar: "ABX_PROVIDER"), validated with the id grammar; stored on the click context as ctx.obj.provider.
4. --opt KEY=VALUE (repeatable). Parse with parseProviderOptions from src/providers/testing.ts (move it to providers/options.ts if you prefer; it is re-exported from the barrel). Refuse secret fields (ConfigField.secret) with the spec's exit-2 text.
5. abx --help epilog: add the Related commands line (spec §0) — regenerate the root help golden.
6. Top-level error handler: replace the existing status-code switch with exitCodeFor(err) only for provider-typed errors; keep the current mapping for the rest (so goldens stay unchanged): auth 3, not-found 4 (now includes SandboxNotFoundError), timeouts 5, quota 6, config/trust/mismatch 2, otherwise 1.
7. ABX_WARN_DEPRECATED=1: nothing to do in main.ts; warnLegacyOnce reads the env at call time. Make sure _resetDeprecationWarnings() is called from the test setup used by the CLI test suites.

4. New file src/cli/commands/provider.ts

One group provider and subcommands, each a thin wrapper over the library (names per spec §5; all honour --json/--quiet/--ci/--no-color):

Errors raised by the library are ProviderError subclasses carrying code (E80xx) and suggestion; render them with the existing error formatter and exit through exitCodeFor.

5. src/cli/commands/config_cmd.ts

config_cmd.ts resolves each key by its one name. Replace the old multi-name tables with that rule, in this order:

1. Key resolution (get/set/delete KEY): the layer-first resolveKey looks up the one environment variable for the key. Qualified providers.<id>.<key> and --provider select the provider. An unknown key exits 2 and lists the keys that exist (spec §3.2).
2. Reading values: loadLayeredConfig()/explainConfig() for get/list (source labels). Output channel/format unchanged.
3. Writing: config set writes the one environment variable for the key (secrets in ~/.abx/.env, other keys under their config key in config.toml). delete removes that stored value.
4. get/set/delete/list accept --provider and --all. config list shows sandbox_base_url, sandbox_domain, and the other keys from the registry.
5. explainConfig() reports the one variable that decided each key. Secrets are masked.
6. config list shows the one name for each key and masks secrets. There is no second name to audit or rewrite.
7. Provider-scoped keys (acr_*, team_id, region, plugin fields) — config set <provider>:<key> or with --provider; secrets go to ~/.abx/.env (0600).

Gap to close first: config-keys.json has no description_zh/required; if config list needs zh descriptions, regenerate the fixture from the Python repo (the drift test will force the update).

6. src/cli/commands/sandbox.ts

Edit sites (line numbers drift; use the command names):

• create (≈ export const create): add --provider, repeatable --opt, and --secure/--no-secure; pass provider, provider_options, secure to Sandbox.create. Provider-scoped flags (--region, --access-key-* …) are valid only for the built-in provider; for others raise exit 2 with the spec text. Print qualify(providerId, id) and add "provider" to --json only when the provider is not the built-in (byte-identical otherwise).
• list (≈ list_cmd): add --provider and --all-providers (JSON: add provider key per row, only for non-builtin or in all-providers mode; per-provider failures go to stderr as warnings, exit 0 unless all fail).
• kill, connect, and every command taking a sandbox id (files, process, system — sandbox_files.ts, sandbox_process.ts, sandbox_system.ts): accept qualified provider:id via parseSandboxRef; call Sandbox.connect(ref, { provider }).
• loadConfig({ region }) call sites (create/kill): keep for the built-in provider; non-builtin goes through loadLayeredConfig.
• info: add a Provider row only for non-builtin providers.
• The root --provider/--opt values are read from ctx.obj; leaf values override.

sandbox.yaml (provider: key): in the sandbox spec loader (declarative create path, src/cli/commands/sandbox.ts and src/api/_yaml.ts consumers) add optional provider: <id> and provider_options: {…}; precedence: CLI flag > sandbox.yaml > ambient. Unknown/secret option names are rejected with the same exit 2 text as --opt.

7. src/cli/commands/mcp.ts

• The server env (_spawnBackground, around the env build for mcp start) must forward ABX_PROVIDER and any ABX_<P>_* provider-scoped variables only when explicitly present in the process env; it must never forward LLM/GitHub keys to providers (the registry already enforces this at provider construction — nothing extra to do).
• loadConfig().api_key at the auth-token helper (≈ line 162) stays: it is the built-in key lookup used for MCP auth.
• MCP tools that create/list/kill sandboxes: add optional provider argument (string) to sandbox_create, sandbox_list, sandbox_kill, sandbox_connect tool schemas; accept qualified ids. JSON results add provider only for non-builtin.
• mcp install copy rules (spec §4.3): the generated client config keeps provider selection through ABX_PROVIDER only, never secrets.

8. Documentation and goldens

• Regenerate goldens: config list (text/JSON), config --help, abx --help; add goldens for provider commands.
• Update docs/en/reference, docs/en/guide/{environment-variables,authentication,troubleshooting}.md, add docs/{en,zh}/guide/providers.md; keep zh mirrors in lockstep; SKILL.md, llms.txt, README*.md.
• Docs must not contain absolute local paths (scripts/check-no-local-paths.sh).

9. Verification checklist after wiring

1. npx tsc -p tsconfig.json --noEmit and npm run lint.
2. npx vitest run tests/test_providers tests/test_transport/test_config_names.test.ts tests/test_utils (currently 338 passed, 2 todo in providers).
3. Differential cases under parity/diff/ with the built-in provider only: every case byte-identical except the config list ones.
4. abx provider test <id> against local-process, e2b-compatible, and (if a local OpenSandbox server is running) opensandbox; the last is skipped politely otherwise.
5. Cross-implementation: install a plugin with the Node installer, load it with the Python SDK (digests equal), and vice versa.

10. Known gaps (carry into the review)

Open after the 2026-10-13 OpenSandbox run (each has a verified symptom):

• template commands ignore --provider. abx --provider opensandbox template deploy ... runs the Alibaba Cloud ACR flow (ACR credentials missing). They should check templates.read / templates.build and answer E8004 like every other feature-gated command.
• The capability set is not derived from provider features. abx sandbox capabilities and sandbox.capabilities report code, files, shell for OpenSandbox, which declares no code.interpret; Provider.capabilities() and FEATURE_TO_CAPABILITY exist but nothing calls them. Image-based providers also log Could not resolve capabilities for template '<image>' on every create.
• abx sandbox command run on a plugin without an HTTP data plane fails with this._http_client._createEnvdClient is not a function. The Python SDK has _require_data_plane("named commands") and answers E8004; port that guard to _callServerCommand in src/api/sandbox.ts.
• SandboxInfo defaults (region = "cn-hangzhou", timeout = 300) belong to the built-in platform. recordToInfo now overrides them for plugins, so a plugin that reports no region and no lifetime shows an empty Region row and the requested timeout; the model should make both optional.
• No CLI for pause/resume: Sandbox.pause() / resume() work (verified from Python), but there is no abx sandbox pause command in this tree.
• The catalog still ships ebx-provider.toml. Apply e2e/providers/awesome-providers-abx-rename.patch in alibaba-agent-sandbox/awesome-providers; until then abx provider install of the catalog fails with E8014 (no abx-provider.toml at the plugin root).

Older gaps:

• FilesystemProtocol.watchDir is native-only; exec providers return E8004 for files.watch unless hybrid.
• models/errors provider classes live in providers/errors.ts; move or re-export if the framework wants one error module.
• Legacy transport/config.ts is bridged by LayeredConfig.toTransportConfig(); it can be removed once config_cmd.ts and mcp.ts stop importing loadConfig.
• No entry-point discovery of providers in Node (installed plugins and registerProvider() only).