@hydra-acp/cli 0.1.3 → 0.1.5

package/README.md

@@ -204,13 +204,19 @@ hydra-acp --session-id <id>                 # attach to existing session
                                             # (TUI in a TTY, shim otherwise)
 
 hydra-acp init                              # generate config + auth token
-hydra-acp daemon start [--port N] [--host H]
+hydra-acp daemon start [--foreground]       # detached by default; --foreground to attach
 hydra-acp daemon stop
 hydra-acp daemon status
 
 hydra-acp sessions                          # list sessions
 hydra-acp sessions kill <id>                # close a live session (keeps the on-disk record so it can be resurrected)
 hydra-acp sessions rm <id>                  # remove a session entirely (live or cold)
+hydra-acp sessions export <id> [--out <file>|.]
+                                            # write a session bundle (meta + history) to <file>,
+                                            # to a default-named file when --out=., or to stdout
+hydra-acp sessions import <file>|- [--replace]
+                                            # import a bundle from <file> or stdin (-);
+                                            # --replace overwrites an existing lineage match
 
 hydra-acp extensions                        # list configured extensions and live state
 hydra-acp extensions add <name>             # add to config (--command, --args, --env, --disabled)
@@ -261,10 +267,25 @@ Slash commands of the form `/hydra <verb> [args]` are intercepted by hydra befor
 |---|---|
 | `/hydra title` | Asks the agent for a one-line summary, applies it as the new title via `session_info_update`. The sub-prompt and reply are suppressed from clients. |
 | `/hydra title <text>` | Sets the title to `<text>` directly. No agent call. |
-| `/hydra switch <agent>` | Swaps the agent process backing this session. Spawns the new agent (must be in the registry — see `hydra-acp agents list`), kills the old one, and feeds the conversation transcript so far back in as the first prompt to the new agent. `session_info_update` carries the new `agentId`; a synthetic `agent_message_chunk` banner marks the switch in the transcript. The on-disk session record is updated so resurrection brings the session back on the new agent. |
+| `/hydra agent <agent>` | Swaps the agent process backing this session. Spawns the new agent (must be in the registry — see `hydra-acp agents list`), kills the old one, and feeds the conversation transcript so far back in as the first prompt to the new agent. `session_info_update` carries the new `agentId`; a synthetic `agent_message_chunk` banner marks the switch in the transcript. The on-disk session record is updated so resurrection brings the session back on the new agent. |
 
 These work from anywhere a session prompt can be typed — the TUI's input box, agent-shell, the slack thread composer, the browser chat composer. Hydra detects them server-side; clients send them as ordinary `session/prompt` requests.
 
+### Exporting and importing sessions
+
+`hydra-acp sessions export` writes a session to a `*.hydra` JSON bundle (meta + history + optional prompt history). `hydra-acp sessions import` brings it back into the local daemon as a new cold session. Use this to archive a session before clearing it, share one with a teammate, restore from backup, or move work between machines without running both daemons live.
+
+```text
+hydra-acp sessions export hydra_session_abc --out backup.hydra
+hydra-acp sessions import backup.hydra            # → new local id
+hydra-acp sessions import backup.hydra            # error: already imported
+hydra-acp sessions import backup.hydra --replace  # overwrites in place
+```
+
+Each session carries a stable **`lineageId`** that survives every export/import hop, so the same bundle imported twice is detected as a duplicate — the second import errors with the existing local id. `--replace` overrides that and overwrites the existing local copy, killing any live session first and preserving the local `sessionId` so bookmarks (Slack threads, editor session links) keep resolving.
+
+The first attach to an imported session is slow: hydra spawns a fresh agent, runs `session/new`, and feeds the imported history back in as a synthesized takeover transcript (same machinery as `/hydra agent`). Subsequent attaches use the normal `session/load` path. This is a text-level handover — the originating agent's internal state (tool-call chains, compacted earlier turns) isn't preserved, so the resumed conversation may be cognitively shallower than the original.
+
 ### Forwarding agent args (`hydra-acp launch <agent-id> ...`)
 
 Anything you put after `<agent-id>` in launcher mode is forwarded to the underlying agent's command. Hydra appends the extra args to the registry-provided spawn plan. Example:
@@ -319,7 +340,7 @@ When you ask hydra to spawn an agent (via `launch <id>`, `--agent-id`, or `HYDRA
 }
 ```
 
-`daemon.sessionIdleTimeoutSeconds` (default 30) controls how long a session with zero attached clients stays alive before the daemon closes it. The disk record stays so the session can be resurrected later via `session/load`. Set to `0` to disable.
+`daemon.sessionIdleTimeoutSeconds` (default 3600 — one hour) controls how long a session with no recorded agent or user activity stays alive before the daemon closes it. Snapshot-shaped state pings (model/mode/title/commands) and bare attach/detach don't count as activity — only recordable broadcasts (prompts, agent chunks, tool calls, permission prompts) do, so persistent observer clients like the slack/notifier/approver/browser extensions can't pin a quiet session open. In-flight turns and unresolved permission requests defer the close until they settle. The disk record stays so the session can be resurrected later via `session/load`, at which point extensions re-attach automatically through their poll loops. Set to `0` to disable.
 
 `daemon.sessionRecentMinutes` (default 30) controls how far back `hydra-acp sessions` (and the `/v1/sessions` REST endpoint without `?all=true`) looks for cold (disk-only) sessions. Set to `0` to never list cold sessions.
 
@@ -514,6 +535,9 @@ 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