Each client declares which ACP harnesses it offers — adding one to the SDK must not reach Cloud or Replicated

[simonrosenberg]

Important

Rewritten 2026-09-04. Filed as an open design question (options A–D); the decision is below. Requirement: adding an ACP harness to the SDK must not change Cloud or Replicated behaviour.

Problem

ACP_PROVIDERS declares what exists. Nothing declares what a deployment offers, so registry membership leaks straight into product surfaces.

Enterprise republishes the whole registry unfiltered:

# openhands/app_server/web_client/default_web_client_config_injector.py:320-335
acp_providers = [... for provider in ACP_PROVIDERS.values()]   # no filter

frontend/src/routes/agent-settings.tsx:97 renders it. Enterprise pins openhands-sdk==1.44.1, which predates Kimi (#4714) and Pi (#4419) — so the next routine bump puts both in Cloud Settings → Agent with no brand mark, no secret fields, no credential preflight, and a KIMI_API_KEY that per #4819 does not authenticate on its own.

Cloud legitimately differs from OSS: headless credential shape (#4629, #4819), image size (#4624 is 518 MiB, #4639 ~123 MB), install shape (#4823), licensing (#4644).

Decision

Each client declares the harnesses it offers and enforces that at conversation start. The SDK stays a registry and carries no deployment policy.

Client	Declares	Posture
Cloud / Replicated (OpenHands/enterprise)	CLOUD_ACP_PROVIDERS, hardcoded — operators cannot widen	claude-code, codex, gemini-cli
Canvas / OSS (OpenHands/OpenHands)	ACP_PROVIDER_UI	everything registered; missing branding degrades to a generic tile
Evaluation (OpenHands/benchmarks)	derived from the registry (#4833)	everything; one harness per run

Adding a harness is an OSS-and-eval event. Cloud enablement is a separate, deliberate issue.

A UI filter alone is not enough. ACPServerKind widens with the registry, so a persisted setting, an org-settings value (#14675/#14678), an agent profile or a direct API call will validate a harness the client does not offer. Filter and fail closed.

Why not the alternatives. A cloud_supported field on ACPProviderInfo puts deployment policy in a library that also serves OSS and eval, where the answer differs. Deriving from image contents does not work — #4805's npx fallback runs an absent npm provider anyway. A runtime capability endpoint cannot serve the app server's global web-client config, which is emitted before any sandbox exists.

Acceptance Criteria

• Cloud declares its set, filters /api/options to it, and returns 400 for anything else at conversation start — [Feature]: Gate Cloud on an explicit ACP provider allowlist — SDK harness additions must not reach Cloud or Replicated enterprise#315
• Bumping openhands-sdk to a version registering a new harness produces no observable Cloud change: no /api/options diff, no image change, no new code path
• DEFAULT_PREINSTALLED_ACP_PROVIDERS is frozen by a test, so growing the default image stays a deliberate PR ([Feature]: Reorganise agent-server image build — selectable capabilities, parameterised provider set, and shared eval layers #4643, [Epic] Built-in ACP harness parity: Kimi, OpenCode, Pi, Hermes, Antigravity #4820)
• Canvas surfaces every registered harness rather than hiding unlisted ones
• Benchmarks and evaluation derive their ACP tables from the registry (ACP downstream CI: what each consuming repo must assert against the SDK registry #4833)
• No deployment-policy field is added to ACPProviderInfo

Open question. Cloud's free-text acp_command field launches any ACP server regardless of the allowlist. Gate it, or accept that the list governs the picker and not the escape hatch — product call.

Out of scope

Support for any particular harness (#4819, #4639, #4635, #4624) and the non-npm install mechanism (#4823).

Related: #4820 · #4833 · #4832 · #4805 · #4643 · #4644 · OpenHands/enterprise#315

[github-actions]

⚠️ Not yet ready-for-dev

This issue does not yet meet the readiness criteria, so the
ready-for-dev label has not been applied (or has been removed).
The criteria are type-specific:

Bug reports (bug label, see .github/ISSUE_TEMPLATE/bug_template.yml):

• The ### Actual Behavior section must describe reproducible SDK steps
  and include a command such as python, pytest, uv, or pip.
• An ### Acceptance Criteria section with at least one checklist item (- [ ] …).

Enhancements (enhancement label, see .github/ISSUE_TEMPLATE/feature_request.yml):

• A ### Desired Behavior section.
• An ### Acceptance Criteria section with at least one checklist item.

What is missing:

• Add a ### Desired Behavior section describing the behavior you want.

Edit the issue to address the gaps and the ready-for-dev label will be
applied automatically.

Note: Section headings require exact ### matches from the templates.
If a missing type label is reported, no action is needed from external
contributors — maintainers will add the label during triage.

This is an automated check — no AI was used to generate this comment.