Merge main; use the shared chatShutdownDetacher for OpenCode and Codex
OpenCode and Codex chats implement Detach (called by chatManager.Close) instead of a parallel DetachSessions interface. Docs follow the Claude Code host and the systemd KillMode=process unit. The opt-in live restart check copies only the stage provider's login row into its scratch OpenCode database, builds the CLI for skill install and removes its scratch tree.
This commit is contained in:
+72
-7
@@ -25,8 +25,9 @@ the text the harness recorded), and queued prompts are delivered in order. The
|
||||
older start-up probe of recently used chats still runs for anything not
|
||||
recorded, for example after a crash.
|
||||
|
||||
Per backend (the contract is `chatSessionDetacher` in
|
||||
`internal/server/chat_detach.go`):
|
||||
Per backend (the contract is `chatShutdownDetacher.Detach`, which
|
||||
`chatManager.Close` calls instead of `Close`, plus `chatSessionReleaser` for
|
||||
chat_close; see `internal/server/chat_manager.go` and `chat_detach.go`):
|
||||
|
||||
- **OpenCode**: sessions live in the OpenCode service. An attached endpoint
|
||||
(the operator's CLI-managed service) already outlives the server. Without
|
||||
@@ -39,8 +40,8 @@ Per backend (the contract is `chatSessionDetacher` in
|
||||
control connection, and the next server reconciles through `thread/read`.
|
||||
An approval or question the App Server sent to the old connection is bound to
|
||||
it, so one still pending at shutdown cannot be answered after the restart.
|
||||
- **Claude Code**: closed as before until its host implements
|
||||
`DetachSessions`.
|
||||
- **Claude Code**: its detachable hosts keep the CLI running (see the Claude
|
||||
Code section).
|
||||
|
||||
`PIPELINES_SHUTDOWN_SESSIONS=stop` restores the old shutdown, which closes the
|
||||
chat clients and records nothing. See [Installation](install.md#restarts-keep-sessions-running).
|
||||
@@ -82,9 +83,73 @@ credential or alter global settings. `PIPELINES_CLAUDE` may name the executable;
|
||||
otherwise `claude` is resolved from `PATH` and common per-user locations.
|
||||
|
||||
A new session pins a generated UUID with `--session-id`. When the process is
|
||||
released (idle or server restart), the next prompt resumes the same conversation
|
||||
with `--resume <id>`, so context and the selected model survive. Chat creation is
|
||||
local: the CLI starts on the first prompt or model-catalog read.
|
||||
released (idle, an explicit close, or a host that crashed), the next prompt
|
||||
resumes the same conversation with `--resume <id>`, so context and the selected
|
||||
model survive. Chat creation is local: the CLI starts on the first prompt or
|
||||
model-catalog read.
|
||||
|
||||
### Surviving a server restart
|
||||
|
||||
A server restart does not stop a Claude Code chat. The installed server runs each
|
||||
CLI inside `pipelines-claude-host` (`cmd/pipelines-claude-host`,
|
||||
`internal/claudehost`), a small helper installed next to `pipelines-server`. The
|
||||
host starts in its own session and process group, so neither launchd nor the
|
||||
supervisor stops it with the server (the systemd unit uses `KillMode=process`
|
||||
for the same reason). The host owns the CLI's stdin/stdout. It appends every
|
||||
output line to a per-session spool file with byte offsets and serves a Unix
|
||||
socket. The socket is mode 0600 in a 0700 directory:
|
||||
`<user cache dir>/pipelines/claude-hosts/<hash of the database path>/`. Two
|
||||
servers of one user never adopt each other's chats. Each host also writes a
|
||||
registry file (`<key>.json`) there.
|
||||
|
||||
The socket speaks one JSON object per line: `attach` (deliver output from an
|
||||
offset; a newer attach replaces the older connection), `in` (one stdin frame),
|
||||
`ack` (output processed up to an offset), `status` and `close`. Interrupts,
|
||||
model and mode switches travel as the CLI's own control requests inside `in`. The
|
||||
host snoops these frames to keep the CLI's initialize response (models, account),
|
||||
the applied model and permission mode, a turn's running state, and the control
|
||||
requests nobody has answered yet (`can_use_tool`, `AskUserQuestion`).
|
||||
|
||||
On shutdown the server only disconnects (`Detach`). On start it reads the
|
||||
registry and reattaches to every live host before serving. It replays the spool
|
||||
from its start without broadcasting, which rebuilds the session's stream state,
|
||||
background commands and agents, and pending approvals and questions. Requests
|
||||
already answered are skipped. Output after the last acknowledged offset, written
|
||||
while no server was attached, is then processed live. The turn is shown running
|
||||
if it was running at that offset, watchers get a resync, and the start-up turn
|
||||
probe keeps observing it for notifications. An approval or question asked before
|
||||
the restart can be answered after it. Stop works as usual, and the CLI is never
|
||||
restarted or initialized twice.
|
||||
|
||||
The host stops the CLI (EOF, then SIGINT, then SIGKILL to its process group) and
|
||||
removes its files only when one of these happens:
|
||||
|
||||
- The operator closes the chat (`chat_close`).
|
||||
- The server's idle release or live-process cap fires.
|
||||
- The CLI exits; the server then gets its stderr.
|
||||
- With no server attached, the CLI has been idle for the same 20 minutes, or
|
||||
no server has attached for 24 hours.
|
||||
|
||||
If the host itself dies, the server first tries to reconnect once. If that fails,
|
||||
it stops the orphaned CLI's process group (only when that pid's command line
|
||||
still names the session) and removes the host files. A running turn ends with
|
||||
the notice "the Claude Code host stopped unexpectedly; the next prompt resumes
|
||||
this session with --resume". The next prompt then resumes the session.
|
||||
|
||||
Limits:
|
||||
|
||||
- A container restart (Docker) still ends every host. So does a reboot or
|
||||
logout. The transcript survives and `--resume` applies.
|
||||
- The spool keeps at most 64 MiB of acknowledged output. Older output is
|
||||
dropped, so background-task state from before that point is not rebuilt after
|
||||
a restart. Unacknowledged output is dropped only beyond 256 MiB; the server
|
||||
then logs the gap and clients reload the transcript.
|
||||
- Turn bookkeeping that lived only in server memory restarts fresh: the turn id,
|
||||
and which mid-turn messages are still outstanding. Output that begins a
|
||||
follow-up turn after a reconnect is adopted as a running turn.
|
||||
- Without the host binary (`PIPELINES_CLAUDE_HOST=off`, or not found next to the
|
||||
server or on `PATH`), the CLI is the server's child as before and a restart
|
||||
resumes it.
|
||||
|
||||
Text and reasoning stream from the CLI's partial-message events; completed
|
||||
messages are de-duplicated against the streamed text. Tool calls appear as normal
|
||||
|
||||
+8
-7
@@ -42,7 +42,8 @@ Linux needs `systemctl --user`. Other platforms are refused.
|
||||
2. Builds the Flutter web app in Docker (pinned to `app/.flutter-version`).
|
||||
Builds are cached in `~/.cache/pipelines/app-builds` by a digest of the app
|
||||
sources, so an unchanged app is reused.
|
||||
3. Builds `pipelines-server` and `pipelines` with `go build -trimpath`.
|
||||
3. Builds `pipelines-server`, `pipelines` and `pipelines-claude-host` (keeps
|
||||
Claude Code chats alive across server restarts) with `go build -trimpath`.
|
||||
4. Installs into the prefix: binaries in `bin/`, web app in `lib/app-web`, web
|
||||
proxy in `lib/web`, `lib/manage.py`, and an empty `lib/app-updates` for APKs.
|
||||
5. Runs `pipelines skill install` (the authoring skill for OpenCode and Claude
|
||||
@@ -222,11 +223,11 @@ endpoint, keeps running and is reused. Stop it by killing the `pid` in
|
||||
clients as before, add `"PIPELINES_SHUTDOWN_SESSIONS": "stop"` to
|
||||
`opencode_env` in `<prefix>/pipelines-install.json` and restart.
|
||||
|
||||
Limit on Linux: systemd stops every process in the service's cgroup. The
|
||||
OpenCode services the server starts (stage service, owned chat service) end
|
||||
with `pipelines stop`/`restart`, and their runs fall back as described above.
|
||||
An attached OpenCode endpoint and the Codex App Server are separate and
|
||||
survive. macOS launchd does not kill them.
|
||||
The OpenCode services the server starts (stage service, owned chat service)
|
||||
run in their own process session, so macOS launchd leaves them running. The
|
||||
systemd unit uses `KillMode=process`, so Linux stops only the supervisor, which
|
||||
stops its own children; the detached services survive. An attached OpenCode
|
||||
endpoint and the Codex App Server are separate processes anyway.
|
||||
|
||||
The login service is `~/Library/LaunchAgents/net.a-wan.pipelines.plist` on
|
||||
macOS and `~/.config/systemd/user/net.a-wan.pipelines.service` on Linux. It
|
||||
@@ -238,7 +239,7 @@ autostart, not boot-without-login.
|
||||
| Path | Contents |
|
||||
| --- | --- |
|
||||
| `<prefix>/pipelines-install.json` | manifest (ports, paths, install args, environment) |
|
||||
| `<prefix>/bin/` | `pipelines`, `pipelines-server`, `ntfy` |
|
||||
| `<prefix>/bin/` | `pipelines`, `pipelines-server`, `pipelines-claude-host`, `ntfy` |
|
||||
| `<prefix>/data/pipelines.db` | SQLite database (definitions, runs, chats, settings) |
|
||||
| `<prefix>/data/artifacts/` | run artifacts and session exports |
|
||||
| `<prefix>/data/ntfy/` | ntfy config, cache and accounts |
|
||||
|
||||
Reference in New Issue
Block a user