@hydra-acp/cli 0.1.33 → 0.1.34

package/README.md

@@ -27,11 +27,11 @@
 
 ## What it is
 
-`hydra-acp` is a daemon + CLI shim that implements four open ACP RFDs as a single coherent surface, plus the official ACP Registry as its agent-distribution mechanism.
+`hydra-acp` is a daemon + CLI shim that implements two open ACP RFDs as a single coherent surface, on top of the standard ACP protocol (including `session/list` for session discovery), plus the official ACP Registry as its agent-distribution mechanism.
 
 ### The standards it stitches together
 
-ACP itself is the [Agent Client Protocol](https://agentclientprotocol.com/) — a JSON-RPC 2.0 protocol between editors (clients) and AI coding agents. Today the protocol is canonically a 1:1 stdio relationship: one editor spawns one agent and owns its stdin/stdout. Four RFDs in the [`agentclientprotocol/agent-client-protocol`](https://github.com/agentclientprotocol/agent-client-protocol) repo extend that model. `hydra-acp` is one daemon that implements all four together so they can be used as a coherent system rather than four independent extensions.
+ACP itself is the [Agent Client Protocol](https://agentclientprotocol.com/) — a JSON-RPC 2.0 protocol between editors (clients) and AI coding agents. Today the protocol is canonically a 1:1 stdio relationship: one editor spawns one agent and owns its stdin/stdout. Two RFDs in the [`agentclientprotocol/agent-client-protocol`](https://github.com/agentclientprotocol/agent-client-protocol) repo extend that model. `hydra-acp` is one daemon that implements both together so they can be used as a coherent system rather than two independent extensions.
 
 #### 1. Multi-Client Session Attach — [RFD #533](https://github.com/agentclientprotocol/agent-client-protocol/pull/533)
 
@@ -42,17 +42,15 @@ Adds two new methods that turn ACP from 1:1 into 1:N:
 
 Every event the agent emits is broadcast to every attached client; clients self-filter what they act on. Permission requests broadcast the same way: the first response wins, and the rest receive a `session/update` notification with `sessionUpdate: "permission_resolved"`. Capability is advertised in `initialize` under `agentCapabilities.sessionCapabilities.attach`.
 
-#### 2. Agent Extensions via ACP Proxies — [RFD: proxy-chains](https://agentclientprotocol.com/rfds/proxy-chains)
+#### 2. Streamable HTTP & WebSocket Transport — [RFD: streamable-http-websocket-transport](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport) (WebSocket profile only)
 
-Defines the proxy-chain pattern: a component that sits between an ACP client and an ACP agent and either passes traffic through or transforms it. Proxies use `proxy/initialize` (instead of `initialize`) so the conductor of the chain can tell terminal agents apart from intermediate proxies. Proxies "send messages to successor and receive messages from successor" without knowing what or where the successor is — the conductor's job. `hydra-acp` operates as the conductor and as one such proxy: editors spawn it, and from their perspective it appears as a single ACP agent regardless of how many real agents the daemon is managing behind it.
+Defines the network transport that lets ACP run between processes that aren't parent and child. The RFD specifies two profiles on one `/acp` endpoint: a Streamable HTTP profile (POST/GET-SSE/DELETE with `Acp-Connection-Id` and `Acp-Session-Id` headers, HTTP/2 required) and a WebSocket profile (GET with `Upgrade: websocket`). The RFD explicitly permits servers to support **only** the WebSocket profile, and that's the route `hydra-acp` takes — the Streamable HTTP half isn't implemented. The RFD itself is still Draft as of April 2026, with the routing model rewritten twice in the six weeks before this writing, so deferring HTTP-transport work until the spec stabilizes is deliberate.
 
-#### 3. Session List — [RFD: session-list](https://agentclientprotocol.com/rfds/session-list)
+On the WebSocket side, `hydra-acp` exposes its WSS endpoint at `/acp`: a client sends `GET /acp` with `Upgrade: websocket`, receives a `101 Switching Protocols` response, and the connection becomes a bidirectional stream of JSON-RPC text frames (binary frames are ignored). The server negotiates the `acp.v1` subprotocol via the standard `Sec-WebSocket-Protocol` mechanism (echoed back in the 101 when advertised; absent otherwise). Authentication is layered on top — HTTP headers, query parameters, or WebSocket subprotocols — and is treated as orthogonal by the spec. `hydra-acp` authenticates via a bearer token carried in a `hydra-acp-token.<token>` subprotocol entry or a `?token=<token>` query parameter.
 
-Adds **`session/list { cwd?, cursor?, limit? }`** — an optional capability for enumerating live sessions on an agent (or, in this case, on the daemon). Each entry returns `{ sessionId, cwd, title, updatedAt, _meta }` plus a cursor for pagination. Capability is advertised as `agentCapabilities.sessionCapabilities.list: true`. This is what makes "list and attach" usable from any compliant client without a hydra-specific REST call.
+### Standard ACP it relies on
 
-#### 4. Streamable HTTP & WebSocket Transport — [RFD: streamable-http-websocket-transport](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport)
-
-Defines the network transport that lets ACP run between processes that aren't parent and child. The relevant half for `hydra-acp` is the WebSocket binding: a client sends `GET /acp` with `Upgrade: websocket`, receives a `101 Switching Protocols` response, and the connection becomes a bidirectional stream of JSON-RPC text frames (binary frames are ignored). Authentication is layered on top — HTTP headers, query parameters, or WebSocket subprotocols — and is treated as orthogonal by the spec. `hydra-acp` exposes its WSS endpoint at `/acp` and authenticates via a bearer token carried in a WebSocket subprotocol or a query parameter.
+Beyond the bedrock of `initialize` / `session/new` / `session/prompt`, the daemon implements **`session/list`** ([Protocol: Session List](https://agentclientprotocol.com/protocol/session-list), stabilized 2026-03-09) so any compliant client can enumerate sessions known to the daemon and attach to one — `{ sessionId, cwd, title?, updatedAt?, _meta? }` per entry, with `cwd` filtering and `cursor`-based pagination. Hydra-specific fields ride under `_meta["hydra-acp"]` per the [Extensibility](https://agentclientprotocol.com/protocol/extensibility) convention.
 
 ### The registry it depends on
 
@@ -83,10 +81,10 @@ Agents are sourced from the [ACP Registry](https://github.com/agentclientprotoco
 
 1. **Editor spawns `hydra-acp`** as it would any ACP agent. The shim looks like a normal stdio agent.
 2. **Shim opens a WSS connection** to the daemon at `/acp`, authenticating via the bearer token.
-3. **`session/new` from the editor** → daemon resolves the requested agent against the cached ACP Registry, downloads it on first use under `~/.hydra-acp/agents/`, spawns it as a child process, and creates an ACP session inside it (per RFD: proxy-chains).
+3. **`session/new` from the editor** → daemon resolves the requested agent against the cached ACP Registry, downloads it on first use under `~/.hydra-acp/agents/`, spawns it as a child process, and creates an ACP session inside it.
 4. **`session/attach` from a second client** → daemon adds the new client to the session's broadcast list and replays history per `historyPolicy` (per RFD #533).
 5. **Notifications** fan out to every attached client. **Prompts** are serialized through the daemon's per-session queue. **Permission requests** broadcast to every attached client; first response wins and the rest receive a `session/update` with `sessionUpdate: "permission_resolved"` carrying the resolving client's outcome.
-6. **`session/list`** returns the daemon's active sessions, filterable by `cwd` (per RFD: session-list).
+6. **`session/list`** returns the daemon's sessions (live and cold), filterable by `cwd`.
 7. **`session/detach`** lets a client leave voluntarily; the session continues until the last client detaches (per RFD #533).
 
 ### Why a shim?
@@ -99,7 +97,7 @@ Clients that adopt the streamable-http-websocket-transport RFD natively can conn
 
 The shim and daemon together implement a "resume hint" pattern that lets editor sessions survive a daemon restart without the editor noticing:
 
-1. **The daemon's `session/new` and `session/attach` responses include a `_meta` block**, with hydra-specific data namespaced under `_meta["hydra-acp"]` (per the [Session List RFD](https://agentclientprotocol.com/rfds/session-list)'s "agent-specific `_meta` fields" convention). The underlying agent's own `_meta` keys, if any, are passed through unchanged alongside `hydra-acp`.
+1. **The daemon's `session/new` and `session/attach` responses include a `_meta` block**, with hydra-specific data namespaced under `_meta["hydra-acp"]` (per the ACP [Extensibility](https://agentclientprotocol.com/protocol/extensibility) convention). The underlying agent's own `_meta` keys, if any, are passed through unchanged alongside `hydra-acp`.
 2. **The shim caches that namespaced data in a `SessionTracker`** as messages flow through, keyed by the hydra sessionId the editor knows.
 3. **The shim's WS connection is wrapped in a `ResilientWsStream`** that reconnects with exponential backoff (200ms → 5s, capped, max 60 attempts) and buffers outbound messages from the editor while disconnected.
 4. **After each successful reconnect, the shim replays a `session/attach`** for every cached session, including the resume hints under `_meta["hydra-acp"].resume`.
@@ -504,7 +502,7 @@ Logs are also fanned out to stderr while the daemon is running. To follow live:
 
 ## Wire protocol
 
-The daemon's WSS endpoint follows the [Streamable HTTP & WebSocket Transport RFD](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport):
+The daemon's WSS endpoint follows the WebSocket profile of the [Streamable HTTP & WebSocket Transport RFD](https://agentclientprotocol.com/rfds/streamable-http-websocket-transport) (the Streamable HTTP profile isn't implemented — see the transport section above):
 
 ```
 GET /acp HTTP/1.1
@@ -513,9 +511,9 @@ Upgrade: websocket
 Sec-WebSocket-Protocol: acp.v1, hydra-acp-token.<token>
 ```
 
-Frames are JSON-RPC 2.0 text frames; binary frames are ignored.
+The server selects `acp.v1` and echoes it back in `Sec-WebSocket-Protocol` on the 101 response; the `hydra-acp-token.<token>` entry is consumed as auth and never echoed. Frames are JSON-RPC 2.0 text frames; binary frames are ignored.
 
-The first JSON-RPC message a client sends is `initialize` (per ACP), or `proxy/initialize` if the client wants the daemon to act as a proxy in the proxy-chain sense (per RFD: proxy-chains).
+The first JSON-RPC message a client sends is `initialize` (per ACP).
 
 ### Methods implemented
 
@@ -525,13 +523,12 @@ Standard ACP:
 - `session/new` — create a new session, spawning the requested agent
 - `session/prompt`
 - `session/cancel`
+- `session/list { cwd?, cursor? }` — enumerate sessions known to the daemon
 
 RFD additions:
 
 - `session/attach { sessionId, historyPolicy: "full"|"pending_only"|"none" }` — RFD #533
 - `session/detach { sessionId }` — RFD #533
-- `session/list { cwd?, cursor?, limit? }` — RFD: session-list
-- `proxy/initialize` — RFD: proxy-chains
 
 Capabilities advertised in the `initialize` response:
 
@@ -550,7 +547,7 @@ Capabilities advertised in the `initialize` response:
     "loadSession": false,
     "sessionCapabilities": {
       "attach": {},
-      "list": true
+      "list": {}
     }
   }
 }