@hydra-acp/cli 0.1.56 → 0.1.58

package/README.md

@@ -59,24 +59,21 @@ Agents are sourced from the [ACP Registry](https://github.com/agentclientprotoco
 ## Architecture
 
 ```
-            editor       browser        Slack       ← clients (the heads)
-              │             │             │
-            stdio           │             │
-              │             │             │
-       hydra-acp shim       │             │
-              │             │             │
-              └─────────────┼─────────────┘
-                            │
-                       WSS / HTTP
-                            │
-                    hydra-acp daemon                ← daemon (the body)
-                            │
-                    T1 → T2 → … → Tn                ← transformers (per-session middleware)
-                            │
-              ┌─────────────┼─────────────┐
-              │             │             │
-       ACP agent A      ACP agent B   ACP agent C   ← agents (the feet)
-       (one per session, sourced from the ACP Registry)
+            editor         browser          Slack        ← clients
+              │               │               │
+          hydra-acp   hydra-acp-browser hydra-acp-slack  ← hydra extensions
+              │               │               │
+              └───────────────┼───────────────┘
+                              │
+                          WSS / HTTP
+                              │
+                          hydra-acp                      ← hydra daemon
+                              │
+                      T1 → T2 → … → Tn                  ← hydra transformers
+                              │
+              ┌───────────────┼───────────────┐
+              │               │               │
+            claude         opencode         gemini       ← agents
 ```
 
 ### How it works
@@ -156,6 +153,15 @@ npm install -g @hydra-acp/cli
 
 Drops `hydra-acp` (and `hydra`) on your PATH.
 
+Then pick the agent the daemon should spawn by default. `defaultAgent` is the registry id used when `session/new` doesn't specify one (the common case for editor-spawned shims), and `defaultModels[<agent>]` pins a per-agent default model. Both are read once at daemon startup, so a `daemon restart` is needed for changes to take effect:
+
+```sh
+hydra-acp agent list                              # browse known agent ids
+hydra-acp agent set opencode                      # update the default agent
+hydra-acp agent set opencode openai/gpt-5-codex   # update the default model for agent
+hydra-acp daemon restart                          # restart the daemon to pickup changes
+```
+
 ## Quick start
 
 ```bash
@@ -255,6 +261,12 @@ hydra-acp transformer log <name> [-f] [-n] # tail (default 50) or follow a trans
 
 hydra-acp agent [list]                     # list agents in the registry
 hydra-acp agent install <id>               # pre-install an agent (else lazy on first use)
+hydra-acp agent set [<id>] [model]         # with no args, report the daemon's current default
+                                           # agent and its default model. With <id>, set <id> as
+                                           # the default agent (config.defaultAgent). With <id>
+                                           # and [model], set the per-agent default model
+                                           # (config.defaultModels[<id>]). Writes require
+                                           # `daemon restart` to take effect.
 hydra-acp agent refresh                    # force a registry re-fetch
 hydra-acp agent sync <id>                  # spawn <id> just long enough to ACP session/list it,
                                            # then persist any sessions it remembers as cold rows
@@ -513,7 +525,9 @@ client ← daemon ← [Tn ← … ← T1] ← agent
 
 This means a transformer can inspect every prompt before the LLM sees it and every response before it reaches clients or mutates daemon state (model, mode, history). It cannot do this invisibly — the chain is operator-visible and each transformer's intercepts are declared up front.
 
-A transformer is configured in the same way as an extension but under a separate key. ```json
+A transformer is configured in the same way as an extension but under a separate key.
+
+```json
 {
   "transformers": {
     "my-transformer": {
@@ -626,40 +640,15 @@ Capabilities advertised in the `initialize` response:
 
 Hydra is a transparent proxy for prompt content and MCP server configs — they're forwarded to the underlying agent unchanged — so the daemon advertises the union of relevant capabilities. The agent ultimately determines what it accepts. If an editor sends a content type the underlying agent rejects, the rejection surfaces as a normal ACP error from the agent, not a hydra-side error.
 
-## REST API
-
-All REST endpoints require `Authorization: Bearer <token>`.
+## Protocol surfaces
 
-```
-GET    /v1/health                 # liveness
-GET    /v1/sessions               # list sessions
-POST   /v1/sessions               # create session (alternative to ACP session/new)
-POST   /v1/sessions/:id/kill      # demote a live session to cold (keeps the on-disk record); idempotent
-DELETE /v1/sessions/:id           # remove a session entirely (live or cold)
-GET    /v1/sessions/:id/export    # download a session bundle (*.hydra JSON; meta + history)
-POST   /v1/sessions/import        # body { bundle, replace? } → { sessionId, importedFromSessionId, replaced }
-                                  # 409 with existingSessionId on a lineageId clash unless replace:true
-GET    /v1/agents                 # list known agents (registry + installed)
-POST   /v1/agents/:id/install     # pre-install an agent
-GET    /v1/registry               # current cached registry contents
-POST   /v1/registry/refresh       # force refresh
+The daemon exposes three surfaces on a single TCP port (default `127.0.0.1:55514`):
 
-GET    /v1/extensions             # list configured extensions and live state
-POST   /v1/extensions             # register a new extension (takes effect immediately)
-DELETE /v1/extensions/:name       # unregister and stop an extension
-POST   /v1/extensions/:name/start
-POST   /v1/extensions/:name/stop
-POST   /v1/extensions/:name/restart
-
-GET    /v1/transformers           # list configured transformers and live state
-POST   /v1/transformers           # register a new transformer (takes effect immediately)
-DELETE /v1/transformers/:name     # unregister and stop a transformer
-POST   /v1/transformers/:name/start
-POST   /v1/transformers/:name/stop
-POST   /v1/transformers/:name/restart
-```
+- **REST API** at `/v1/*` — management plane (auth, sessions, agents, registry, extensions, transformers, MCP routes).
+- **ACP WebSocket** at `/acp` — JSON-RPC 2.0. Standard ACP plus the Hydra-specific extensions (prompt queue, stdin streaming, transformer plumbing, …).
+- **Agent-facing MCP** at `/mcp/*` — Streamable HTTP MCP transport used by spawned agents to reach the per-session stdin ring buffer and extension-contributed tools.
 
-Sessions are also reachable via `session/list` over ACP itself, for clients that prefer the protocol-native path.
+All three are documented in [`PROTOCOL.md`](PROTOCOL.md), with endpoint shapes, request/response bodies, JSON-RPC method semantics, capability discovery, and the JSON-RPC error code reservations.
 
 ## Security
 
@@ -673,7 +662,7 @@ The daemon exposes a process-management surface. Treat the service token like an
 
 ## Registry entry mockup
 
-If accepted, `hydra-acp` would land in the [ACP Registry](https://github.com/agentclientprotocol/registry) under either `agent.json` or `extension.json` (TBD with maintainers — likely `extension.json`, since hydra is a session-multiplexer rather than an LLM-backed coding agent).
+If accepted, `hydra-acp` could land in the [ACP Registry](https://github.com/agentclientprotocol/registry):
 
 ```json
 {