feat(sdk): add Kimi Code as a built-in ACP provider (parity contract)

[simonrosenberg]

Parent epic: #4820

Goal

Add Kimi Code as a built-in ACP provider, meeting the same bar as claude-code, codex and gemini-cli.

Community PR #4714 by @ysntony is open and implements the core of this. This issue tracks the harness to the full parity contract so "supported" means the same thing it does for the three reference providers.

Parity contract

1. Registry record in openhands-sdk/openhands/sdk/settings/acp_providers.py — every field populated from Kimi's actual server behaviour:

• key, display_name
• default_command — npx -y --prefer-offline <pkg>@<KIMI_VERSION> (may need a trailing arg, as gemini-cli appends --acp)
• binary_name — the wrapper binary _prefer_pinned_binary() looks for; omit it and Kimi always pays the npx path
• data_dir_env_var — the env var pointed at a per-conversation dir so credentials, sessions and caches don't leak between runs
• api_key_env_var, base_url_env_var (or None)
• default_session_mode — the mode that disables permission prompts
• agent_name_patterns
• supports_set_session_model — does the initial model need a protocol call?
• supports_runtime_model_switch — does mid-conversation switching work?
• session_meta_key (or None)
• available_models + default_model — the model picker
• file_secrets — only if Kimi authenticates from a file on disk rather than an env var

Determine the two supports_* flags from Kimi's real behaviour rather than copying a neighbour's values. Reporting supports_runtime_model_switch=False when the server supports it silently drops a user-visible feature.

2. Version constant — [ ] KIMI_*_VERSION alongside CLAUDE_AGENT_ACP_VERSION / CODEX_ACP_VERSION / GEMINI_CLI_VERSION.

3. Pin-parity test — [ ] add the key to _REGISTRY_ACP_PACKAGES in tests/cross/test_agent_server_build_metadata.py.

Warning

This one is easy to miss and fails silently. test_agent_server_dockerfile_acp_package_versions_match_registry does registry_package = _REGISTRY_ACP_PACKAGES.get(provider_key) followed by if registry_package is None: continue — a provider present in the Dockerfile but absent from that dict is skipped, not flagged. Its pin can then drift from the registry indefinitely with CI green. #4714 currently adds a Dockerfile arm without a dict entry, so the pin would be uncovered.

4. TypeScript mirror — [ ] update clients/typescript/src/models/acp-providers.json.

clients/typescript/scripts/check-acp-drift.py compares the whole registry field-for-field and runs in typescript-client-ci.yml, so this will fail CI if skipped. #4714 does not currently touch this file.

5. Preinstall decision — [ ] decide explicitly whether Kimi joins the image, and record why.

Important

Registry membership is not image membership. Since #4805, a provider absent from the image is not broken — resolve_acp_command() falls back to the version-pinned npx install, cached under ~/.openhands. Adding Kimi to the default INSTALL_ACP_PROVIDERS=claude-code,codex,gemini-cli grows every published image for every user, so registry-only is the default and preinstalling is a deliberate, recorded decision. #4714 currently adds a Dockerfile arm; worth confirming that is intended rather than assumed necessary.

Note the default list is also hardcoded in .github/workflows/server.yml and asserted verbatim by a test, so preinstalling means changing both.

6. Tests — [ ] tests/sdk/settings/test_acp_providers.py (its set(ACP_PROVIDERS) == {...} assertion forces this), plus the paths covering the reference providers: tests/sdk/agent/test_acp_agent.py, tests/agent_server/test_credential_binding.py, test_settings_router.py.

7. Live verification — [ ] a real ACP turn against the actual Kimi server: session created, tool call executed, reply returned. The registry record is a claim about server behaviour; only a live run substantiates it.

Notes

@ysntony's PR is the starting point, not a gap list — the items above are what separates a working addition from parity with the three reference providers, and several are repo conventions that aren't discoverable from the diff alone.

---

What the existing providers actually set

The contract above is abstract; this is the concrete shape, read from the registry on main. Use it to decide what each field should be for this harness — and to see which values are genuinely provider-specific versus conventional.

Field	claude-code	codex	gemini-cli
display_name	Claude Code	Codex	Gemini CLI
default_command	npx -y --prefer-offline @agentclientprotocol/claude-agent-acp@0.63.0	npx -y --prefer-offline @agentclientprotocol/codex-acp@1.1.7	npx -y --prefer-offline @google/gemini-cli@0.46.0 --acp
binary_name	claude-agent-acp	codex-acp	gemini
api_key_env_var	ANTHROPIC_API_KEY	OPENAI_API_KEY	GEMINI_API_KEY
base_url_env_var	ANTHROPIC_BASE_URL	OPENAI_BASE_URL	GEMINI_BASE_URL
data_dir_env_var	CLAUDE_CONFIG_DIR	CODEX_HOME	HOME
default_session_mode	bypassPermissions	agent-full-access	default
agent_name_patterns	["claude-agent"]	["codex-acp"]	["gemini-cli"]
supports_set_session_model	True	True	True
supports_runtime_model_switch	True	True	True
session_meta_key	"claudeCode"	None	None
default_model	opus[1m]	gpt-5.5	auto
available_models	5	7	7
file_secrets	none	CODEX_AUTH_JSON	GOOGLE_APPLICATION_CREDENTIALS_JSON

What to take from it

• binary_name and data_dir_env_var are part of the record and easy to overlook. binary_name is what _prefer_pinned_binary() looks for to use an installed binary instead of npx; omit it and the provider always pays the npx path. data_dir_env_var is the env var pointed at a per-conversation directory so credentials, sessions, plugins and caches don't leak between runs.
• data_dir_env_var is not always a dedicated variable. gemini-cli uses plain HOME, because the CLI has no config-dir override — which is why isolation for it means relocating HOME rather than setting a scoped var. If this harness has a dedicated config-dir variable, prefer it; if it only respects HOME, say so explicitly on the issue.
• All three set both supports_* flags to True. That makes False the value that needs justifying: it should mean this server genuinely cannot do it, verified against the running server, not not implemented yet. A silent False removes the model picker or mid-conversation switching for users of this harness.
• session_meta_key is the exception, not the rule — only claude-code sets one ("claudeCode"), because claude-agent-acp ignores session-_meta model selection and needs the model pushed via a protocol call. Default to None unless the server actually reads a _meta key.
• default_command may carry arguments, not just a package: gemini-cli appends --acp to put the CLI into ACP mode.

file_secrets, if the CLI authenticates from a file

Only needed when the credential is a file on disk rather than an env var. The two live specs:

// codex — env var points at the DIRECTORY containing auth.json
{ "secret_name": "CODEX_AUTH_JSON", "filename": "auth.json",
  "env_var": "CODEX_HOME", "subdir": "codex",
  "env_points_to": "dir", "warn_if_unset": [] }

// gemini-cli — env var points at the FILE itself
{ "secret_name": "GOOGLE_APPLICATION_CREDENTIALS_JSON", "filename": "gcloud-credentials.json",
  "env_var": "GOOGLE_APPLICATION_CREDENTIALS", "subdir": "gemini-cli",
  "env_points_to": "file", "warn_if_unset": ["GOOGLE_CLOUD_PROJECT", "GOOGLE_CLOUD_LOCATION"] }

env_points_to distinguishes the two shapes and is the field most likely to be set wrong — Codex wants a directory, Gemini wants the file. warn_if_unset names companion variables that are useless alone (Gemini's Vertex project and location). The SDK owns the mechanism — materialising the file under the conversation's durable root, seed-if-absent, setting the env var; the spec is only policy.

[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.
• Add an ### Acceptance Criteria section with testable checklist items.

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.

[all-hands-bot]

#4819 is a maintainer-authored parity-contract tracking issue for Kimi Code as ACP provider; #4716 is the original community feature request for the same work. Both track adding Kimi Code as a built-in ACP provider and reference the same community PR #4714. #4819 is a deliberate superset with a comprehensive 7-point checklist (TypeScript mirror, pin-parity test, preinstall decision, live verification, etc.) and is referenced as the canonical Kimi child by the umbrella epic #4820. Rather than closing #4819, #4716 should likely be closed as superseded by #4819.

Found 2 possible duplicate issues:

1. #4716 — [Feature]: Add Kimi Code CLI as a built-in ACP provider (kimi acp)
2. #4820 — [Epic] Built-in ACP harness parity: Kimi, OpenCode, Pi, Hermes, Antigravity

These may not be exact duplicates, but the scope appears to overlap enough that keeping discussion in one place may be more useful.

This comment was created by an AI assistant (OpenHands) on behalf of the repository maintainer.

[simonrosenberg]

Harnessed #4714 to the parity contract and verified the registry record against the running CLI. Pushed ba25b5e4a to @ysntony's branch.

Contract status

#	Item	Status
1	Registry record	✅ every field verified against Kimi Code CLI 0.39.1 (details below)
2	KIMI_CODE_VERSION constant	✅ was already there
3	Pin-parity test	✅ added — was missing, and failing silently
4	TypeScript mirror	✅ added — was missing; validate-acp-providers now passes on the PR
5	Preinstall decision	✅ registry-only; Dockerfile arm is opt-in, default list untouched
6	Tests	✅ 820 passing across the reference-provider paths
7	Live verification	⚠️ partial — see the disclosure below

The two silent gaps were both real

#4 would have failed CI, and the PR's green checks hid it. #4714 is a fork PR, so all 13 substantive workflows sat in action_required and never ran — the "2 checks passed" badge was Validate PR description and check-pr-artifacts. I approved the runs; validate-acp-providers now passes with the mirror entry, which it would not have without it.

#3 failed exactly as this issue predicted. I proved the arm is now live by injecting a deliberate drift (Dockerfile 0.40.1 vs registry 0.39.1):

AssertionError: ACP package @moonshot-ai/kimi-code has version 0.40.1,
but acp_providers.py pins 0.39.1

Before the dict entry, that same drift passed green.

Also added --prefer-offline to default_command (the other three have it; it matters precisely on the npx fallback path this provider defaults to).

Registry record — all verified, no copied-from-a-neighbour values

@ysntony got the easy-to-overlook fields right independently. agent_name_patterns matches live agentInfo.name = "Kimi Code CLI"; data_dir_env_var="KIMI_CODE_HOME" genuinely relocates the root (resolveKimiHome() = env.KIMI_CODE_HOME ?? ~/.kimi-code, and the CLI wrote state into my temp dir); binary_name="kimi" resolves in-image; both supports_* flags are True because session/set_model and mid-conversation set_config_option(configId="model") both land on the same setModel and a bogus id is genuinely rejected; session_meta_key=None is right because newSession reads only cwd/additionalDirectories/mcpServers — a _meta key would be a silent no-op.

On default_session_mode="yolo" — this issue warned against copying a neighbour's value, and the choice here is genuinely justified. The engine ships a yolo-mode-approve policy (approves all tools) and an auto-mode-ask-user-question-deny policy, and the CLI's own text reads "YOLO mode can still stop for questions. Switch to Auto if you want questions skipped." So yolo is the tool-permission-disabling mode, and auto is strictly more aggressive about suppressing elicitation. Confirmed live: a full turn ran with zero session/request_permission calls.

The remaining parity gap: the credential path

This is the one item I'd hold the "supported" label on, and it isn't in the current contract table.

KIMI_API_KEY alone does not authenticate an ACP session on 0.39.1.

KIMI_API_KEY=… KIMI_BASE_URL=…  →  session/new
{"code": -32000, "message": "Authentication required"}
stderr: "no provider configured; complete onboarding via /login or the providers endpoint"

The resolver reads the config file, never the process environment:

function hasEnvValue(provider, envKey) {
  return nonEmptyString(provider.env?.[envKey]) !== void 0;   // config.toml, not process.env
}

So KIMI_API_KEY is only consulted for a provider already present in $KIMI_CODE_HOME/config.toml. The gate needs an OAuth token or such an entry. Kimi's actual env-only path is KIMI_MODEL_NAME + KIMI_MODEL_API_KEY, which works but pins one model under the reserved alias __kimi_env_model__ and bypasses the picker — so it is not a drop-in for api_key_env_var + available_models.

I left api_key_env_var="KIMI_API_KEY" (correct variable, consumed once a provider exists) and recorded the constraint in a comment rather than redesigning the credential model inside a parity PR. This is a file_secrets-shaped problem — exactly the shape #4820 anticipates, and @ysntony's own Notes flagged that Kimi's nested credentials/kimi-code.json can't be expressed by today's ACPFileSecretSpec (basename + single subdir). Worth tracking as its own item here, and it likely generalises to other harnesses in the epic.

Live verification — what is and isn't substantiated

Important

I had no Kimi account credential, so the live turn ran with the model served through KIMI_MODEL_* pointed at an OpenAI-compatible endpoint.

Substantiated: process launch, initialize, session lifecycle, the mode taxonomy, set_model / set_config_option, tool dispatch and workspace I/O, and the npx fallback installing the pin.

agentInfo: {"name": "Kimi Code CLI", "version": "0.39.1"}
set_mode(yolo) -> {}
TOOL START title='Bash' kind='execute'
  -> completed: "The magic number for this validation run is 8675309.\n"
AGENT REPLY: 8675309          prompt -> {"stopReason": "end_turn"}

Not substantiated: the four kimi-code/* ids and the OAuth catalog against Moonshot's servers. Those are verified from the shipped catalog and the alias construction (`${KIMI_CODE_PLATFORM_ID}/${modelId}`, KIMI_CODE_PLATFORM_ID = "kimi-code", four Kimi-native models kimi-for-coding, kimi-for-coding-highspeed, k3, k3-256k) — consistent, but not a live logged-in session/new. Someone with a Kimi account should confirm those four ids before this ships, and that same run would settle the credential question above.

Note for the other four harnesses

Two things here generalise to OpenCode / Pi / Hermes / Antigravity:

1. Fork PRs give you no CI signal at all. feat(sdk): register Pi as a built-in ACP provider #4419 (Pi) is also a fork PR — assume its checks are equally uninformative until someone approves the runs.
2. endpoint-audit fails on every fork PR (403 Resource not accessible by integration when posting its report comment) regardless of the diff. It's report-only; don't chase it.

[ysntony]

@simonrosenberg I have a Kimi account subscription and I'm happy to confirm them.

I can close the live-verification gap on the OAuth path. Everything below was tested on pinned @moonshot-ai/kimi-code@0.38.0 via npx … acp, driven over JSON-RPC stdio (results identical on 0.39.1).

The four kimi-code/ ids:* confirmed. With my account logged in (device-code OAuth), session/new returns a configOptions select with id: "model" containing exactly these four entries from the built-in provider: kimi-code/kimi-for-coding ("K2.7 Coding"), kimi-code/kimi-for-coding-highspeed ("K2.7 Coding Highspeed"), kimi-code/k3 ("K3"), kimi-code/k3-256k ("K3-256k"). The provider list marks all four as managed:kimi-code (type: kimi, source: oauth, https://api.kimi.com/coding/v1).

The credential question: confirmed as you analyzed. With a fresh empty KIMI_CODE_HOME, session/new fails with -32000 Authentication required ("no provider configured; complete onboarding via /login or the providers endpoint") even with KIMI_API_KEY exported. After kimi login, the same call succeeds. The gate reads the config file only; env alone authenticates nothing.

Full turn on the logged-in account: passes. After set_mode("yolo") and set_config_option("model", "kimi-code/kimi-for-coding") (acknowledged: currentValue updated), I prompted the agent to write 42 into magic.txt. The turn executed real tool calls, created the file with the right content on disk, replied 42, and ended with stopReason: "end_turn". Zero session/request_permission calls under yolo.

[simonrosenberg]

@simonrosenberg I have a Kimi account subscription and I'm happy to confirm them.

I can close the live-verification gap on the OAuth path. Everything below was tested on pinned @moonshot-ai/kimi-code@0.38.0 via npx … acp, driven over JSON-RPC stdio (results identical on 0.39.1).

_The four kimi-code/ ids:_* confirmed. With my account logged in (device-code OAuth), session/new returns a configOptions select with id: "model" containing exactly these four entries from the built-in provider: kimi-code/kimi-for-coding ("K2.7 Coding"), kimi-code/kimi-for-coding-highspeed ("K2.7 Coding Highspeed"), kimi-code/k3 ("K3"), kimi-code/k3-256k ("K3-256k"). The provider list marks all four as managed:kimi-code (type: kimi, source: oauth, https://api.kimi.com/coding/v1).

The credential question: confirmed as you analyzed. With a fresh empty KIMI_CODE_HOME, session/new fails with -32000 Authentication required ("no provider configured; complete onboarding via /login or the providers endpoint") even with KIMI_API_KEY exported. After kimi login, the same call succeeds. The gate reads the config file only; env alone authenticates nothing.

Full turn on the logged-in account: passes. After set_mode("yolo") and set_config_option("model", "kimi-code/kimi-for-coding") (acknowledged: currentValue updated), I prompted the agent to write 42 into magic.txt. The turn executed real tool calls, created the file with the right content on disk, replied 42, and ended with stopReason: "end_turn". Zero session/request_permission calls under yolo.

Thank you so much for the confirmation!

[simonrosenberg]

Landed in #4714 (merged 2026-09-03), which also carried the hardening the other provider PRs needed.

Contract items satisfied:

• Registry record present, with binary_name and data_dir_env_var="KIMI_CODE_HOME" set, both supports_* flags True, session_meta_key=None, default_session_mode="yolo".
• ACPServerKind updated; tests/sdk/settings/test_acp_providers.py key-set assertion updated.
• TypeScript mirror updated — kimi-code is in acp-providers.json with all 16 fields, so check-acp-drift.py passes. This was the gap flagged here.
• Not in the default preinstall list — ARG INSTALL_ACP_PROVIDERS=claude-code,codex,gemini-cli is unchanged, so Kimi ships registry-only and relies on the feat: add ACP-less agent-server image fallback #4805 npx path, which is the intended default.

Two gaps closed structurally rather than individually, via #4832:

• The pin-parity concern is gone. _REGISTRY_ACP_PACKAGES and the fail-open Dockerfile-regex test were deleted, not patched — ACP_INSTALL_CATALOG is now the single source, the registry derives default_command/binary_name from it, and the Dockerfile renders its install plan from it. Drift between them is no longer representable, so the silent-skip hole this issue warned about cannot recur.
• --prefer-offline is centralised in the catalog, so it applies to every provider uniformly. No per-provider omission is possible.

Two deliberate deviations from the PR as filed, worth recording:

• available_models=() and default_model=None — the PR proposed four curated model ids; main leaves the CLI to pick its own default. So Kimi has no model picker today. Deliberate, but it means the picker item in the contract is unmet by choice rather than satisfied.
• api_key_env_var=None, where the PR had KIMI_API_KEY.
• Pin landed at 0.38.0, not the PR's 0.39.1 (npm latest is 0.41.0).

Live conformance and model-acceptance probes now exist for built-in providers (#4834), though they are path-filtered and non-required — see #4830 for the remaining CI hardening backlog and OpenHands/automation#414 for scheduled drift detection.

Closing as delivered.