Files
pipelines/docs/notes/codex-pending-interactions-restart.md
T

56 lines
3.5 KiB
Markdown

# Codex pending interactions across Pipelines restarts
The App Server's pending approval/question callback IDs belong to the connection
that received them. Its current official schema exposes no pending-request
listing/replay method. Saving JSON in the Pipelines database cannot make an old
callback answerable on a new upstream connection.
Added `pipelines-codex-host`: a detached, private local WebSocket bridge that owns
the existing App Server connection. It does not launch Codex. The installed
server scopes hosts by database and upstream socket, finds/reuses the helper,
and initializes only its downstream connection after a restart. The host caches
the one upstream initialization and replays exactly the still-unanswered server
requests. Responses or matching serverRequest/resolved notifications remove
pending entries. Client call IDs are translated to unique host IDs and routed
only to the originating client; replacing a client discards old routes. Client
and callback RPC IDs are capped at 256 bytes.
Unix sockets are mode 0600 under an owner-verified mode-0700 directory. Per-scope
file locks prevent simultaneous helpers. The existing daemon connection, not a
PID or a model statement, owns pending callbacks. Pending memory is capped at
128 requests / 8 MiB; calls at 256; incoming frames at 16 MiB. Overflow closes
rather than answering an interaction. With no Pipelines client, helpers expire
after 20 minutes with no pending callbacks, or after 24 hours even when pending.
Ordinary notifications are not spooled; current thread readback repairs gaps.
Native installation, tester packages and Docker include the helper; Go-bin
uninstallation verifies and removes its executable. Missing helper or explicit
PIPELINES_CODEX_HOST=off retains direct mode and logs its restart limitation.
Direct-mode fixtures still pass. Hosts run independently of a launching request's
context and are not killed by installing a replacement binary.
Verification:
- `go test -race ./internal/codexhost ./internal/codex ./internal/installation
./cmd/pipelines-server` passes. Real Unix-socket fixtures cover pending approval
and question responses across client replacement, duplicate response rejection,
resolved callbacks, matching thread ownership, old/new RPC-ID collision
isolation, detached arrival/replay, bounded pending state, singleton ownership,
private permissions, shutdown cleanup, and actual helper process spawning/reuse.
- The actual Codex adapter's Open -> Detach -> Open integration retains both
permission and question maps, answers their original IDs, initializes upstream
once, and does not replay resolved requests on a third client.
- Existing direct Codex tests pass; `go build ./...`, `go vet ./...`, and all 53
native-installer Python tests pass. Full Go integration is the manager's check.
No live service, conversation, daemon, credential or deployment was changed.
The initial deployment cannot rescue callbacks already owned by the old direct
connection; pending interactions must settle before that first replacement.
A helper crash, upstream App Server restart, or expiry breaks callback identity
and remains an explicit limitation. No disk reconstruction is claimed.
Handshake follow-up: the bridge now sends the upstream `initialized` notification
once after a successful initialize response and before declaring readiness.
Downstream initialized notifications remain suppressed on every attach. A real
socket fixture verifies initialize -> initialized ordering and exactly one of
each across client replacement, and the adapter integration checks both counts.