Files
pipelines/docs/chat-backends.md
T

116 lines
7.0 KiB
Markdown

# Chat backends
Chats can be created on more than one harness. OpenCode remains the default;
Codex is available when its App Server control socket exists, and Claude Code
when the `claude` CLI is installed. The selected backend is stored on the
operator-session row and returned as `backend` on every `chat_sessions` row, so a
restart does not have to guess from the session id.
## Codex
The adapter in `internal/codex` connects to the Codex App Server's Unix
WebSocket control socket (`$CODEX_HOME/app-server-control/app-server-control.sock`,
falling back to `~/.codex`). It uses the operator's existing Codex login. A new
chat issues `thread/start`; a prompt issues `turn/start`; history comes from
`thread/read`; questions map from `item/tool/requestUserInput` to the normal
question card and `chat_answer` returns the JSON-RPC response. Threads created
this way are ordinary Codex threads and remain visible to the Codex app.
New threads retain the `workspace-write` sandbox and inherit Codex's configured
approval policy (Pipelines no longer forces `never`). Command, file-change,
network and explicit permission requests appear in the web approval cards. Each
JSON-RPC callback has its own identity, including Code Mode subcommands sharing
one item. Allow once maps to `accept`, session grants to `acceptForSession`, and
Reject to `decline`; explicit permission profiles grant only requested fields.
The web labels session scope explicitly, never as a permanent policy change.
Pending questions and approvals survive browser reconnects while the App Server
connection lives. Standard MCP form/URL elicitation supports typed answers,
Accept/Decline/Cancel and safe external links. Extended OpenAI elicitation is not
advertised; unknown request formats return an explicit unsupported RPC error,
not a fake empty success or silent auto-approval. App Server socket loss does
not provide durable callback recovery; a disconnected transport is reported as
an error rather than claiming old requests are still actionable.
## Claude Code
The adapter in `internal/claude` owns one Claude Code CLI process per active
session. It starts `claude -p` with stream-json input and output, partial
messages, and `--permission-prompt-tool=stdio`, then performs the SDK-style
`initialize` handshake before any turn. The operator's existing Claude Code login
and configuration are used unchanged; Pipelines does not store a second
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.
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
tool cards, Bash commands as the existing background-command rows, and results
attach to the call. `can_use_tool` becomes the normal approval card: Allow once
returns the original input, Always allow forwards the CLI's own permission
suggestions, and Reject returns a deny. `AskUserQuestion` becomes the normal
question card and `chat_answer` returns the chosen answers. Interrupt sends the
CLI's own `interrupt` control request.
The model catalog comes from the CLI's initialize response and is switched live
with `set_model`; Pipelines persists the choice for the next turn so a resumed
process starts with it. Usage and context totals come from the CLI's `get_usage`
and `get_context_usage` queries: session cost, processed tokens, context tokens
and the model window are reported values, not estimates. Compaction boundaries
surface as native compaction activity.
History is read from Claude Code's own session transcript
(`$CLAUDE_CONFIG_DIR/projects/*/<id>.jsonl` or `~/.claude`). Entries are merged by
message id, tool results attach to their calls, subagent sidechains and local
command noise are excluded, and paging is bounded. A session file larger than
64 MiB is reported as exceeding the history bound rather than silently truncated.
The live user turn keeps the client's optimistic id when it can be matched to the
recorded prompt.
## Web interaction contract
All advertised chat adapters (OpenCode V2, Codex and Claude Code) implement the
same server contract for uploads, models, pending approvals, questions, form
replies, interrupts, command readback and bounded output. Compile-time assertions
and browser regressions protect this contract; support is not satisfied by text
streaming alone. Pi's pipeline executor is not advertised as a Pi web-chat
adapter, and a harness whose CLI is absent is not presented as a working choice.
Codex uploads use native `localImage` for verified supported images. Other files
are retained intact with an explicit server-local reference; the model's own
tools inspect them rather than pretending their contents were already loaded.
The saved next-turn model is also respected with uploads. Model sandbox and
approval policy remain in force. Claude Code receives images as native image
blocks, small text files inline, and larger files by absolute server path; the
saved next-turn model is applied before the turn.
Codex's paged history retains tool and reasoning items, including structured MCP
errors and Code Mode outputs, instead of discarding everything except text.
Unknown item kinds remain inspectable. Tool detail is explicitly truncated at
64 KiB, not silently represented as complete. Running commands and their output
use real command items plus read-only thread history; no unsupported terminal
endpoint, process control, resumed turn or experimental flag is invented.
Output reads are bounded and verify thread ownership. The installed Codex
version exposes no API for controlling an agent-owned terminal through the
separate, client-owned `command/exec` process IDs; those IDs are never conflated.
A fresh Codex connection can accept a turn without subscribing to its native
thread notifications. The adapter therefore reconciles the latest turn through
the read-only paged API and emits an authoritative-history resync when it changes.
It does not call `thread/resume` on open/model selection, so merely watching a
chat cannot awaken a queued goal. Native turn IDs protect the queue/UI from stale
completion events. A real, isolated tool-free turn passed after replacing the
owning connection; no command, permission grant or global setting was involved.
An explicit Send can load a persisted thread if `turn/start` is refused with
the exact application error `thread not found: <owned-thread-id>`. Only then
does the adapter call `thread/resume` (metadata only, no policy/configuration
override) and submit the original message/model/files. Transport failures and
unrelated errors are never retried. This loading is not performed by browsing,
history reads or model selection. As in Codex's native client, explicitly
continuing a thread also resumes that thread's configured execution context.