Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / acp-gateway-bridge

ACP gateway bridge

The ACP gateway bridge lets an ACP editor use Hermes through the gateway while the ACP process remains a viewer. It starts the protocol server, presents Hermes sessions and capabilities, sends prompts and commands to the gateway, and turns gateway events into ACP updates without owning agent execution.

Gateway role

The bridge separates the editor connection from the session owner. The gateway keeps the session policy, execution queue, tools, and durable state; the ACP process subscribes to that state and projects it to one editor.

Server startup

The ACP server starts through acp_adapter/entry.py. It loads the Hermes environment, sends logs to stderr so stdout stays available for ACP JSON-RPC, and creates GatewayACPAgent as a gateway-backed viewer. The process closes only its viewer connection. The gateway decides when an ACP session ends.

The server can also run without the gateway through the in-process agent path. The gateway path is the one that keeps execution and MCP work in the daemon, which allows another viewer to remain attached when one editor disconnects.

References: acp_adapter/entry.py• L1-9 acp_adapter/entry.py• L65-79 acp_adapter/entry.py• L201-221 acp_adapter/gateway_server.py• L125-170

Capability catalog

The bridge advertises the ACP features that an editor can use. It supports session load, image prompts, session fork, session listing, and session resume. Authentication advertises the active Hermes provider when credentials are ready and always offers terminal setup for an unconfigured installation.

Before a new gateway session is created, the bridge checks that the gateway exposes ACP session policy support. This prevents an editor from creating a session that cannot preserve the policy and tool choices expected by the ACP surface.

References: acp_adapter/gateway_server.py• L171-194 acp_adapter/gateway_server.py• L280-295 acp_adapter/auth.py• L8-50

Session attachment

Session attachment connects an editor's ACP session handle to the gateway's logical conversation. Creation freezes the editor's workspace, model route, edit policy, and selected MCP servers; loading and resuming restore the same conversation and replay its visible history.

Session creation

When an editor calls session/new, the bridge asks the gateway to create an ACP-owned session. The gateway returns a snapshot that includes the session identity and current policy. The bridge then returns model choices, the available edit mode, and protocol metadata to the editor.

The editor's MCP selection belongs to that session. It is retained across a bridge reconnect and is reapplied when the viewer attaches again. A workspace change or MCP policy change is treated as a session control action rather than as a new conversation.

References: acp_adapter/gateway_server.py• L280-320 acp_adapter/gateway_server.py• L346-389 acp_adapter/gateway_server.py• L395-408

Session reattachment

Loading or resuming maps an editor-held handle to the logical session that represents the conversation. This matters after compression or reset because the internal transcript segment can change while the editor's public session identity stays stable.

On a gateway or transport restart, the bridge resumes every session still held by the editor. It restores the latest snapshot, reattaches editor MCP servers, and reports pending approvals or unknown turn outcomes. A session that no longer exists is removed from this viewer without taking the other sessions offline.

The bridge replays prior messages before completing an attach response. This gives the editor a usable transcript before it starts sending new prompts.

References: acp_adapter/gateway_server.py• L224-244 acp_adapter/gateway_server.py• L333-389 acp_adapter/gateway_server.py• L410-414

The attachment flow connects the editor to an existing owner and then carries prompts and events through the gateway.

sequenceDiagram
    participant E as ACP editor
    participant B as ACP bridge
    participant G as Gateway owner
    E->>B: initialize
    B-->>E: capabilities and auth methods
    E->>B: session/new or session/load
    B->>G: session.create or session.resume
    G-->>B: session snapshot and policy
    B-->>E: session response and metadata
    E->>B: session/prompt
    B->>G: prompt.submit
    G-->>B: session events
    B-->>E: session/update events

Interactive controls

Interactive controls preserve the meaning of a user's decision across the ACP and gateway boundaries. The bridge shows the decision in the editor, sends only a valid response to the owner, and leaves the owner able to accept an answer from another viewer when this viewer disconnects.

Elicitation handling

Elicitation is a question from the running agent that needs a user answer rather than a tool approval. If the editor advertises ACP form elicitation, the bridge sends an elicitation/create form with a string or multi-select answer schema. Otherwise it renders the same question as a permission card with one option per choice and a Skip option.

The bridge sends the selected answer through clarify.respond. Decline, cancel, and Skip become an empty answer. A lost connection is not treated as a user answer, so another attached viewer can still respond.

References: acp_adapter/elicitation.py• L1-7 acp_adapter/elicitation.py• L17-52 acp_adapter/gateway_server.py• L723-729 acp_adapter/gateway_server.py• L866-894

Approval handling

Approval is a decision about a potentially unsafe tool action or edit. The bridge converts the gateway's approval choices into ACP permission options such as Allow once, Allow for session, Allow always, and Deny. The chosen option is mapped back to the gateway's approval result.

The bridge also presents model-switch confirmations and edit proposals through the same permission channel. A timeout produces a distinct timeout result, while a dismissed card or a detached editor does not silently deny the action.

References: acp_adapter/permissions.py• L15-51 acp_adapter/permissions.py• L77-151 acp_adapter/gateway_server.py• L896-927 acp_adapter/gateway_server.py• L488-512

Gateway command translation

ACP editors often send slash commands as prompt text. The gateway bridge recognizes registered commands and translates them into gateway reads, session mutations, or turn controls. Unknown slash commands remain normal model input.

Command surface

The bridge advertises a small command catalog after session attachment. Read commands ask the gateway for reports. Model changes, reset, and compression use session mutations. Steer and queue control the current or next turn. Fork remains an ACP session operation instead of a slash command.

The command surface is intentionally narrower than the in-process implementation because each gateway command must have a matching owner-side operation. Edit-policy changes are not offered because the gateway keeps the session policy at Ask.

References: acp_adapter/gateway_session_meta.py• L21-55 acp_adapter/gateway_commands.py• L1-41 acp_adapter/gateway_server.py• L520-538

Prompt translation

For each prompt, the bridge first converts ACP text, image, and resource blocks into Hermes input. Images are staged for gateway admission, while unsupported or remote resources remain visible as text notes. A registered slash command is handled before ordinary prompt submission.

Ordinary input becomes prompt.submit with a session identity and a content fingerprint. The fingerprint lets a retry reuse an admission when the editor lost the acknowledgement, which prevents an uncertain turn from running twice. Gateway stream events then become ACP text, tool, usage, title, approval, and completion updates.

References: acp_adapter/content.py• L18-23 acp_adapter/content.py• L147-189 acp_adapter/gateway_server.py• L551-637 acp_adapter/gateway_server.py• L686-845

Session metadata

Session metadata gives an editor the information needed to display and manage a Hermes conversation. The bridge derives it from gateway snapshots, usage reads, and existing session history rather than creating a second metadata store.

Model and mode metadata

The model picker presents provider-qualified model choices so a selection keeps its provider context. It combines the shared Hermes model inventory with named custom endpoints and keeps the current model visible when the inventory cannot be read.

The gateway exposes one default mode that means Ask before edits. The editor can select that mode, but it cannot change the edit policy through the ACP bridge.

References: acp_adapter/gateway_session_meta.py• L21-25 acp_adapter/gateway_session_meta.py• L58-80 acp_adapter/model_catalog.py• L1-16 acp_adapter/model_catalog.py• L238-312

Usage and provenance metadata

Usage updates show the editor the current context size and occupancy. A completed prompt also carries token counts when the gateway has them. Title changes arrive as session information updates so the editor can keep its session list current.

Provenance metadata explains the relation between the stable ACP session handle and internal Hermes transcript segments. It identifies the current and root Hermes sessions and marks compression continuations without changing the editor-facing session identity.

References: acp_adapter/gateway_session_meta.py• L83-123 acp_adapter/provenance.py• L1-11 acp_adapter/provenance.py• L32-86 acp_adapter/gateway_server.py• L803-818

Session lifetime

The gateway owns ACP session lifetime because the bridge is only a viewer. When the last viewer leaves an idle ACP session, the gateway records the disconnect and can later reopen the session when an editor attaches and continues it.

Viewer disconnects

The bridge does not mark a session ended when its ACP process stops. The owner checks that no viewer remains and that the session FIFO is idle before ending an ACP-created local session. Gateway shutdown applies the same rule to every ACP session that has no viewer.

This preserves queued or active work and avoids closing a session simply because one editor connection failed. A later load followed by a prompt can reopen an ended local session.

References: acp_adapter/entry.py• L204-221 gateway/session_acp_lifecycle.py• L1-7 gateway/session_acp_lifecycle.py• L16-31 gateway/session_acp_lifecycle.py• L56-72

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the capabilities in initialize aligned with the session methods that the gateway can actually support.
  • Keep command advertisement, slash-command recognition, and owner-side gateway verbs aligned. A command can be displayed but fail if one of these surfaces drifts.
  • Preserve the stable ACP session handle when internal compression or reset segments change.
  • Keep approval and elicitation responses tied to the prompt id and execution generation. A response for a newer turn can answer the wrong request.
  • Keep reconnect logic idempotent. A retry after a lost prompt acknowledgement must not submit a second turn.
  • Keep viewer disconnect handling separate from owner session shutdown. Ending a busy or still-viewed session can lose work.

Important failure modes

TriggerConsequenceGuard
Gateway capability or ACP policy is unavailableSession creation is refused instead of creating an unusable editor sessionRuntime capability check before session.create
Gateway transport fails after prompt admissionThe editor cannot know if the turn ran and must not resend itRetained submit identity and explicit unknown-outcome recovery
Replay sequence is missing or out of orderThe editor may show incomplete or duplicated session stateSnapshot sequence tracking and replay-gap failure
Approval or clarification response arrives after the prompt expiresThe owner keeps the canonical request unresolved for another viewerPrompt id and execution-generation checks
Last viewer leaves while work is activeEnding the session would interrupt or hide active workEnd only sessions with no subscribers and an idle FIFO

Key files

FileWhy to read it
acp_adapter/entry.pyACP process startup, stdio rules, and viewer shutdown
acp_adapter/gateway_server.pyMain bridge lifecycle, session attachment, prompt flow, event projection, and interactive responses
acp_adapter/gateway_commands.pyTranslation from editor slash commands to gateway operations
acp_adapter/gateway_session_meta.pyEditor-facing command, model, mode, usage, title, and provenance metadata
acp_adapter/elicitation.pyForm and permission-card representations of agent questions
acp_adapter/permissions.pyMapping between ACP permission options and Hermes approval results
acp_adapter/content.pyConversion of ACP prompt resources into model input
gateway/session_acp_lifecycle.pyOwner-side rules for ACP session ending and reopening
docs/agent-client-protocol.mdParent page for the wider ACP protocol and integration model