Fixes for custom ACP agents - concurrent turns, steering and context-overflow recovery

[botdoggy]

ACP protocol officially doesn't support agent advertising the ability to do concurrent/parallel turns or be able to steer. But this can be advertised by detecting meta tags (or by allowing the user to toggle it on themselves, instead of assuming a degraded default), similar to how Zed the IDE does.

I've implemented and tested the following two features and a fix on my own fork of the openbot repo that makes custom ACP agents more capable:

https://github.com/botdoggy/openbot/tree/pr/custom-acp-features

1. [Feature] Parallel turns toggle in the ACP custom-agent dialog panel + concurrentTurns meta flag detection + entry addition in custom-agents.json
2. [Feature] steer toggle in the ACP custom-agent dialog panel + entry addition in custom-agents.json
3. [Fix] Context-overflow recovery fix for custom ACP agents, that was earlier addressed in issue Fix routine failing with "The request contains invalid parameters" error #2351 and PR Start a new OpenCode session when OpenCode rejects the request #2382 (for opencode)

This also closes #3763 — the issue is not yet labeled approved, so the Contribution policy check will
fail until a maintainer labels it (or adds policy-exempt). The steering, context-overflow, and
compaction parts have no upstream issues; happy to file feature requests or split the PR if preferred.

Type of change

• New feature or change to existing behavior (needs an approved issue)

What changed

Four opt-in extensions for custom ACP agents, developed and run on my fork :

• Concurrent turns: opt in via _meta.concurrentTurns, seeded by the startup capability check
  as one user-owned flag per agent, editable in the custom-agent dialog; a busy agent starts a new
  turn instead of queueing.
• Steering: a custom ACP agent can steer a running turn when it advertises
  _meta.steering.supported: true, using the agreed community wire protocol
  (_session/steering {sessionId, prompt}, as in Zed's claude-code-acp).
  Agents that don't advertise it keep queue-and-refuse.
• Context-overflow recovery: a custom ACP session that fails with an overflow wording is ended
  and replaced with a new session for the next turn, instead of stalling every later turn.
• Compaction updates: ACP agents stream context-compaction updates into the chat, so a
  compaction no longer looks like a dead turn.

Verification

• biome check on changed paths and repo typechecks (pre-commit hook), plus
  bun vitest run src/backend/agent/thread-items.test.ts (8 tests pass). CI owns the full suite.
• Surfaces: renderer composer + custom-agent dialogs, IPC contracts (ipc-custom-agents.ts,
  ipc-agent-tasks.ts) and mock-openbot.ts, i18n (steer hint, overflow strings in all locales).
• E2e harnesses against the fake ACP agents: bun scripts/acp-concurrent-turns-e2e.ts and
  bun scripts/acp-steer-e2e.ts both pass on this branch.
• No credentials, private data, generated output, or real user files included.
• Tested in production on two linux servers

Failure modes

(The branch adds src/backend/agent/thread-items.test.ts)

• Gateway-style overflow wording (HTTP 400: {"error":"Context limit exceeded"}) covered by a custom test
• Common overflow phrasings — covered by the it.each block.
• Non-overflow failures (invalid schema, unauthorized) must not drop the session — covered by
  "ignores other custom ACP failures".
• Overflow wording from native providers must not reuse the ACP wedge-drop path — covered by the
  cross-provider test.

Risk and security impact

• Optional fields added to IPC contracts (ipc-custom-agents.ts, ipc-agent-tasks.ts) and the
  persisted custom-agent record; absent means off, no migration.
• New JSON-RPC requests go only to the configured custom ACP child over its existing stdio pipe:
  _session/steering (only to agents that advertised steering) and compaction-update handling.
• No changes to permissions, filesystem access, browser behavior, or remote network.

Screenshots

No layout changes; the custom-agent dialog gains two capability switches (concurrent turns,
steering) with seeded defaults and hint text per agent.

[Sniezka1927]

Thank you for this work. We read the branch (pr/custom-acp-features, 5 commits) and compared it with main. Please open one issue and one PR for each part below, so that we can review and merge each part separately. A feature PR needs an issue with the approved label.

1. Context-overflow recovery: accepted

It uses the existing refusedSessionFailure path, and the one-retry guard stops a loop. Please open an issue and a PR for this part only.

• Remove src/backend/agent/thread-items.test.ts. Our rules permit Vitest files only in protected areas (migrations, the trust boundary, secret redaction, check rules). Use an E2E script under scripts/ instead: a fake ACP agent that fails with an overflow message, and a JSON report under .openbot-build/.

2. Compaction capability: accepted, with a correct description

session.compaction: {} is a real ACP 1.9.0 client capability. But main already handles compaction_update: it sends the instructions again and updates the context meter. It does not show the compaction in the chat. Please change the changelog to say that OpenBot now asks ACP agents for their compaction updates. This change applies to all ACP providers (OpenCode, Cursor, Cline, Kimi, Antigravity), not only to custom agents. Please say which of them you tested.

3. Steering: change needed before review

The description says that the branch uses _session/steering and _meta.steering.supported. The code uses different names: _openbot/steer, _meta.steer === true, and { sessionId, messageId, content }. The community extension is _session/steering with { sessionId, prompt }, and the agent advertises it as top-level _meta.steering = { supported: true } (see docs/air-extensions.md in agentclientprotocol/claude-agent-acp, and oh-my-pi). With the current code, the check does not find steering on these agents, and each steer fails with "method not found". Please:

• send _session/steering with { sessionId, prompt },
• read _meta.steering.supported === true in the check,
• change the fake agent of scripts/acp-steer-e2e.ts to the same wire shape,
• test against one real agent that has the extension.

4. Concurrent turns: use #3763

The manual toggle is useful. But we found no ACP agent or specification that sends _meta.concurrentTurns, so the detection does nothing at this time. If you know one, please add a link in #3763. If not, keep only the manual toggle. Use #3763 for this PR after a maintainer adds the approved label.

For each PR

• Add one changelog.d/<branch>.md file.
• Write the PR body from .github/PULL_REQUEST_TEMPLATE.md.

[botdoggy]

I’ve split the custom-ACP work into separate issues as requested. No new PRs are open yet; each branch will wait for its issue’s approved label.

Part	Issue	Isolated branch	Current state
Context-overflow recovery	#4972	feat/custom-acp-context-overflow	Ready for issue review
ACP compaction updates	#4974	feat/acp-compaction-updates	Ready for issue review
Custom ACP steering	#4977	feat/custom-acp-steering	Ready for issue review; fake-agent and real-agent tests pass
Parallel turns	#3763	feat/custom-acp-concurrent-turns	Manual toggle only; waiting for approval on the existing issue

Context-overflow recovery — #4972

Branch: https://github.com/botdoggy/openbot/tree/feat/custom-acp-context-overflow

It contains only the overflow-recovery path:

• Recognizes custom-ACP context-overflow wording through refusedSessionFailure.
• Retires the failed session and retries the message once in a replacement session.
• Keeps non-overflow custom ACP failures on their original session with no retry.
• Adds the localized recovery message in all locale catalogs.
• Does not include the forbidden thread-items.test.ts Vitest file.

The requested fake-agent E2E is now scripts/acp-context-overflow-e2e.ts and can be run as:

bun run test:acp-context-overflow

It runs the real AgentService against two fake custom ACP processes. It reports that the overflow turn closes the failed session, retries once in a new session, and completes, while a non-overflow failure has one prompt, no session close, no retry, and a failed delivery. It writes .openbot-build/acp-context-overflow-e2e/report.json.

ACP compaction updates — #4974

Branch: https://github.com/botdoggy/openbot/tree/feat/acp-compaction-updates

The branch now matches the corrected description: OpenBot asks ACP agents for their compaction updates. It is not a new parser or a claim that only custom agents benefit.

It adds session.compaction: {} to the shared OPENBOT_ACP_CLIENT_CAPABILITIES, so it applies to ACP providers generally—the reviewed OpenCode, Cursor, Cline, Kimi, and Antigravity providers, and custom ACP agents—when their ACP implementation supports compaction updates. Main already handles a compaction_update when one arrives by resending the session instructions and updating context state.

The fake-agent verification is:

bun run test:acp-compaction

It confirms that the fake sends compaction_update only after seeing session.compaction in initialize, and that the real ACP client converts the completed update into OpenBot’s existing openbot/context-compaction notification.

I also smoke-tested a real agent: Codex ACP 2.0, running the bundled OpenAI Codex 0.165.0 and configured as a custom ACP agent through OpenRouter with deepseek/deepseek-v4-flash. A /compact turn completed, and OpenBot received a completed openbot/context-compaction notification for the thread.

Custom ACP steering — #4977

Branch: https://github.com/botdoggy/openbot/tree/feat/custom-acp-steering

This branch implements the corrected community extension instead of the earlier _openbot/steer implementation from the old combined branch:

• Check agent reads top-level _meta.steering.supported === true.
• The dialog has a saved, per-agent steering choice seeded from the check.
• An enabled agent receives _session/steering with { sessionId, prompt }.
• A custom agent whose saved steering choice is off keeps today’s queue-and-refuse behavior.

The fake agent uses the same wire shape, and this passes:

bun run test:acp:steer

The check drives both a steering-enabled fake and a plain fake: the enabled agent receives the steering message mid-turn; the plain agent refuses steering while preserving the queue.

I also smoke-tested the steering branch against a real agent: Codex ACP 2.0, running the bundled OpenAI Codex 0.165.0 through OpenRouter with deepseek/deepseek-v4-flash. Check agent discovered _meta.steering.supported === true; OpenBot sent _session/steering with { sessionId, prompt } during a running turn; Codex ACP returned "injected"; and the completed turn applied the steered instruction.

Parallel turns — #3763

Branch: https://github.com/botdoggy/openbot/tree/feat/custom-acp-concurrent-turns

I did not open another issue for this. As requested, it uses #3763.

The branch now keeps only the manual, saved Runs parallel turns choice. There is no _meta.concurrentTurns detection and no Check-agent seeding for parallel turns. The default remains one turn at a time; enabling the choice lets separate sessions of that custom ACP agent run in parallel up to the existing Tasks at once limit.

The fake-agent verification passes:

bun run test:acp:concurrent-turns

It confirms that a session’s fast turn can complete while another session of the same agent is still running a slow turn, and that the saved setting survives a flagless save while defaulting to off.

Each branch has one changelog.d/ entry. The relevant E2E and Biome checks were rerun and pass; the earlier node/contracts/renderer/Storybook typechecks or commit-hook checks also passed for each branch. I’ll open each PR only after its linked issue receives the approved label.

Reproducing the real-agent smoke tests

Both smoke tests used @agentclientprotocol/codex-acp@2.0—bundled OpenAI Codex 0.165.0—configured as a custom ACP agent and pointed at OpenRouter’s deepseek/deepseek-v4-flash.

[Sadrak2017]

For #4972, does the E2E deliver a delayed update from the retired ACP session after the replacement has started? I’d expect it to remain attached to the failed attempt, without settling the replacement or changing its context meter. In our work on Sinaps Studio at SinapsData, distinguishing an agent’s task from its execution attempts matters for monitoring. That case would check recovery bookkeeping beyond whether the retry succeeds.