116 lines
7.0 KiB
Markdown
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.
|