Skip to content

feat(acp): support mid-turn steering / 支持 ACP 回合中引导 - #6715

Merged
SivanCola merged 3 commits into
esengine:main-v2from
gcoder1991:feat/acp-steer
Jul 20, 2026
Merged

feat(acp): support mid-turn steering / 支持 ACP 回合中引导#6715
SivanCola merged 3 commits into
esengine:main-v2from
gcoder1991:feat/acp-steer

Conversation

@gcoder1991

@gcoder1991 gcoder1991 commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Expose Reasonix's existing mid-turn steer queue through the ACP v1 vendor extension _reasonix.io/session/steer.
  • Advertise the extension through agentCapabilities._meta["reasonix.io"].sessionSteer, so clients do not have to guess whether the method exists.
  • Accept the same {sessionId, prompt} content-block shape as session/prompt, but only while a prompt is active; idle sessions return InvalidRequest instead of silently starting a new turn.
  • Keep existing CLI/Desktop/Bot fallback behavior unchanged by splitting strict TrySteer acceptance from the existing Steer fallback.
  • Replay persisted steers as the user's raw text instead of leaking Reasonix's internal steer wrapper.
  • Add dedicated bilingual ACP integration guides and surface them from both READMEs, the main guides, and the project website.

This is intentionally a Reasonix ACP v1 extension, not an implementation of the still-unreleased ACP v2 session/inject proposal.

Refs #3470

ACP v2 context: agentclientprotocol/agent-client-protocol#1261

Documentation

  • docs/ACP.md and docs/ACP.zh-CN.md consolidate startup, capability negotiation, session lifecycle, independent controls, host-supplied MCP transports, permissions, steering errors, compatibility, cache behavior, and a client checklist.
  • Both READMEs and the full English/Chinese guides now link to the dedicated ACP section instead of duplicating a partial protocol description.
  • The bilingual website documents ACP at /docs/#acp, links the complete source guides, and exposes reasonix acp from the homepage.

Capability discovery

The initialize response includes:

{
  "agentCapabilities": {
    "_meta": {
      "reasonix.io": {
        "sessionSteer": {
          "method": "_reasonix.io/session/steer"
        }
      }
    }
  }
}

Wire shape

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "_reasonix.io/session/steer",
  "params": {
    "sessionId": "session-id",
    "prompt": [{"type": "text", "text": "use plan B"}]
  }
}

Successful acceptance returns {}. Unknown sessions and empty prompts use the existing ACP validation errors; sessions without an active prompt return -32600 InvalidRequest. The unnamespaced session/steer method is intentionally not registered because ACP v1 reserves non-underscore method names for the core protocol.

Backward compatibility

Surface Existing behavior Result
Existing ACP v1 methods Unchanged Compatible
agentCapabilities._meta Additive and ignored by clients that do not understand it Compatible
Persisted transcripts No persisted schema change; replay hides the internal steer wrapper Compatible
CLI/Desktop/Bot steer Existing idle and turn-exit fallback remains unchanged Compatible

Provider-visible prompts, tool schemas, and cache-stable prefixes are unchanged apart from the user-requested steer message entering normal conversation history.

Verification

  • go test ./internal/acp -run 'TestServe(Lifecycle|SteerInjectsIntoActivePrompt)$' -count=20
  • go test ./internal/acp ./internal/control ./internal/agent
  • go test -race ./internal/acp ./internal/control ./internal/agent
  • go test ./internal/acp ./internal/cli ./internal/control ./internal/agent
  • go vet ./...
  • env -u DEEPSEEK_API_KEY go test ./...
  • cd site && npm test
  • cd site && npm run build
  • Local Markdown link and bilingual ACP protocol-token parity checks
  • Chrome DevTools checks for English/Chinese ACP deep links at desktop and 390px mobile widths, with no console errors, failed resources, or horizontal overflow
  • git diff --check
  • Synthetic merge with the latest origin/main-v2, followed by go test ./internal/acp ./internal/control ./internal/agent

Focused coverage verifies capability discovery, rejection of the reserved unnamespaced route, active-turn injection, idle rejection, model visibility at the next safe loop boundary, and replay without the internal wrapper.

Cache impact

Cache-impact: none - ACP transport and documentation/site only; no provider-visible system prompt, tool schema, or cache-stable input changes.
Cache-guard: go test ./... and focused ACP steer, capability, and replay regression tests cover the changed surface.
System-prompt-review: N/A

Expose the existing agent steer queue through a Reasonix ACP v1 session/steer extension. Accept guidance only while a prompt is active, preserve existing frontend fallback behavior, and replay delivered steers as the user's raw text.

Refs esengine#3470
@github-actions github-actions Bot added v2 Go rewrite (1.x) — main-v2 branch, active development agent Core agent loop (internal/agent, internal/control) labels Jul 20, 2026
@gcoder1991
gcoder1991 marked this pull request as ready for review July 20, 2026 06:02
Problem:
The ACP v1 steer extension used the reserved core method name session/steer and was not discoverable through initialize capabilities.

Root cause:
The initial adapter registered the feature like a core ACP method instead of using ACP vendor extension naming and the capability _meta contract.

Fix:
Register _reasonix.io/session/steer, advertise it under agentCapabilities._meta["reasonix.io"], and lock the wire contract with tests.

Verification:
- go test ./internal/acp ./internal/control ./internal/agent
- go test -race ./internal/acp ./internal/control ./internal/agent
- go vet ./...
- env -u DEEPSEEK_API_KEY go test ./...
- git diff --check

Co-authored-by: SivanCola <32437197+SivanCola@users.noreply.github.com>
Documentation: Consolidate ACP v1 startup, capabilities, session lifecycle, controls, MCP transport, permissions, and mid-turn steering into dedicated English and Chinese guides.

Website: Surface ACP from both READMEs, the main guides, the bilingual docs page, and the homepage; keep deep links visible below the fixed header after language initialization.

Verification: npm test; npm run build; go test ./internal/acp ./internal/cli ./internal/control ./internal/agent; env -u DEEPSEEK_API_KEY go test ./...; go vet ./...; git diff --check; desktop and 390px Chrome DevTools checks in English and Chinese.
@SivanCola
SivanCola merged commit 29151f3 into esengine:main-v2 Jul 20, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent Core agent loop (internal/agent, internal/control) v2 Go rewrite (1.x) — main-v2 branch, active development

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants