Files
pipelines/docs/chat-backends.md
T
alan ad4233f7b8 Chat: /new continues the same chat on a fresh session
The composer's /new used to create a separate chat. It now sends
chat_new_session. The server starts a fresh native session on the chat's
own harness (OpenCode, Codex or Claude Code) and re-keys the
operator_sessions row in one transaction. The chat keeps its title,
directory, backend, colour, star, model and mode. The old row is kept
unlisted with replaced_by, and its native session stays resumable.

The reply and the chat_session_changed push carry previous_id, so every
client swaps the row in place and an open conversation follows it to the
fresh, empty transcript with a notice.
2026-11-03 14:06:44 +00:00

8.4 KiB

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.

Fresh context (/new)

The composer's /new sends chat_new_session. It keeps the chat and clears the agent's context, like /new or /clear in the harness's own TUI. The server creates a fresh native session on the chat's own harness, in the same directory and with the same title. OpenCode makes a new ses_ session, Codex a new thread and Claude Code a new session UUID. The server then re-keys the operator_sessions row in one transaction. The new row keeps the title, directory, tag, backend, colour, star, creation time, model override and mode. The old row is not deleted: it records replaced_by, is no longer listed, and its native session can still be resumed in a terminal.

The row is re-keyed rather than mapped from a stable id because every other layer is keyed by the native id: rooms, queues, transcripts, shells, exports and resume commands. The reply, and the chat_session_changed push to other connections, carry the new row with previous_id. Each client swaps that row in place, and an open conversation follows it to the fresh, empty transcript. A running turn is refused, so stop it first. A second /new from an id that has already been replaced is refused too.

Claude Code also accepts /clear in -p --input-format stream-json mode, but the CLI then picks the new session id itself. Re-keying keeps one path for all three harnesses and lets the server choose the id.

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.