Files
pipelines/internal/claude/claude.go
T
alan c810437aa5 Claude Code chats survive server restarts in a detachable host
A pipelines-claude-host process owns each claude -p CLI and its pipes,
spools its stream-json output with offsets and serves a private Unix
socket. The server detaches on shutdown and reattaches on start,
replaying the spool to rebuild turns, approvals, questions, background
tasks and the live model. Explicit close, idle release and CLI exit stop
the host; a crashed host falls back to --resume with a notice.
2026-11-04 16:09:56 +00:00

530 lines
14 KiB
Go

// Package claude brokers an operator chat through the installed Claude Code CLI.
//
// Claude Code exposes a bidirectional JSON protocol over stdio in `--print`
// mode: stream-json input carries user turns, stream-json output carries
// assistant/tool events, and control requests carry interactive prompts
// (can_use_tool) and session queries. This adapter owns one CLI process per
// active session and mirrors that protocol into Pipelines chat frames. In the
// installed server each CLI runs inside a per-session pipelines-claude-host so
// it survives a server restart (hosted.go). It never changes the operator's
// Claude configuration or invents a transcript: history is read back from the
// CLI's own session files.
package claude
import (
"context"
"crypto/rand"
"encoding/hex"
"errors"
"log"
"os"
"os/exec"
"path/filepath"
"sort"
"strings"
"sync"
"time"
"git.a-wan.net/alan/pipelines/internal/claudehost"
"git.a-wan.net/alan/pipelines/internal/protocol"
"git.a-wan.net/alan/pipelines/internal/workenv"
)
// Backend is the wire value stored in the operator-session registry.
const Backend = "claude"
const (
// idleProcessExpiry releases a CLI process whose session nobody is watching.
// A later prompt resumes the same Claude session, so context is not lost.
idleProcessExpiry = 20 * time.Minute
maxLiveProcesses = 8
stderrRetained = 8 << 10
)
// BinaryPath resolves the Claude Code executable. PIPELINES_CLAUDE overrides it,
// matching the OpenCode override; common per-user install locations are tried
// because a service PATH may not carry a shell's later additions.
func BinaryPath() string {
if path := strings.TrimSpace(os.Getenv("PIPELINES_CLAUDE")); path != "" {
return path
}
if path, err := exec.LookPath("claude"); err == nil {
return path
}
home, err := os.UserHomeDir()
if err != nil {
return ""
}
for _, candidate := range []string{
filepath.Join(home, ".local/bin/claude"),
"/opt/homebrew/bin/claude",
"/usr/local/bin/claude",
} {
if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
return candidate
}
}
return ""
}
// Available reports whether a Claude Code executable exists. It does not prove
// the CLI is signed in; that is established by the initialize handshake.
func Available() bool {
path := BinaryPath()
if path == "" {
return false
}
info, err := os.Stat(path)
return err == nil && !info.IsDir()
}
// ConfigDir is where Claude Code keeps its session transcripts.
func ConfigDir() string {
if dir := strings.TrimSpace(os.Getenv("CLAUDE_CONFIG_DIR")); dir != "" {
return dir
}
home, err := os.UserHomeDir()
if err != nil {
return ""
}
return filepath.Join(home, ".claude")
}
// Chat owns every Claude session this server has opened. Processes are started
// lazily per session and resumed after being released.
type Chat struct {
ctx context.Context
cancel context.CancelFunc
binary string
// auth picks how started CLI processes sign in (see authEnv).
auth authEnv
// dirEnv supplies each chat directory's own environment (direnv, mise).
dirEnv *workenv.Resolver
// hostDir is the private directory of detachable CLI hosts, "" when the
// CLI is this server's child (see hosted.go).
hostDir string
// hinted records sessions whose registry directory has been resolved.
hinted sync.Map
mu sync.Mutex
sessions map[string]*session
closed bool
// titles holds the operator's chat titles by session id (see SetTitle), so a
// session rebuilt after an idle release keeps its name.
titles map[string]string
// quotas is the latest rate_limit_event quota per account (see quota.go).
quotaMu sync.Mutex
quotas map[string]*protocol.ChatAccountUsage
}
func New(ctx context.Context) *Chat {
if ctx == nil {
ctx = context.Background()
}
c := newChat(ctx)
if c.hostDir != "" {
if err := claudehost.EnsureDir(c.hostDir); err != nil {
log.Printf("claude chat: host directory %s: %v; Claude Code chats stop on a server restart", c.hostDir, err)
c.hostDir = ""
}
}
c.reattachHosts()
go c.reapIdle()
return c
}
// newChat is New without the reattach pass and the reaper (tests).
func newChat(ctx context.Context) *Chat {
ctx, cancel := context.WithCancel(ctx)
c := &Chat{ctx: ctx, cancel: cancel, binary: BinaryPath(), dirEnv: workenv.Default, sessions: map[string]*session{}}
hostConfig.Lock()
c.hostDir = hostConfig.dir
hostConfig.Unlock()
return c
}
// Close stops every owned CLI process, hosted ones included. Session
// transcripts stay on disk. A server shutdown uses Detach instead.
func (c *Chat) Close() {
c.cancel()
c.mu.Lock()
c.closed = true
sessions := make([]*session, 0, len(c.sessions))
for _, s := range c.sessions {
sessions = append(sessions, s)
}
c.sessions = map[string]*session{}
c.mu.Unlock()
for _, s := range sessions {
s.closeProcess()
}
}
// ReleaseShells drops a session's retained shell snapshot after the last
// observer leaves. A later attach re-reads the authoritative transcript.
func (c *Chat) ReleaseShells(id string) {
if s := c.session(id); s != nil {
s.mu.Lock()
s.shells = map[string]*shellSnapshot{}
s.shellOrder = nil
s.mu.Unlock()
}
}
func (c *Chat) session(id string) *session {
c.mu.Lock()
defer c.mu.Unlock()
return c.sessions[id]
}
// sessionFor returns the existing state or records a new one for an id this
// server did not create (an adopted registry row after restart).
func (c *Chat) sessionFor(id, directory string) *session {
c.mu.Lock()
defer c.mu.Unlock()
if s := c.sessions[id]; s != nil {
if directory != "" && s.directory == "" {
s.directory = directory
}
return s
}
s := &session{
chat: c,
id: id,
directory: directory,
subs: map[chan protocol.ChatEventFrame]struct{}{},
approvals: map[string]*pendingApproval{},
forms: map[string]*pendingForm{},
shells: map[string]*shellSnapshot{},
toolMessages: map[string]string{},
streamBlocks: map[int]blockState{},
streamText: map[int]string{},
streamOrdinals: map[string]int{},
streamClaimed: map[int]bool{},
lastUsed: time.Now(),
}
s.title = c.titles[id]
c.sessions[id] = s
return s
}
// SetTitle records the chat's current title. The server calls it on a rename
// and when it first routes a session after a restart. A running CLI keeps the
// name it started with; the next spawn passes the new one as --name. The server
// never writes into Claude Code's transcript itself.
func (c *Chat) SetTitle(_ context.Context, id, title string) {
title = strings.TrimSpace(title)
if id == "" || title == "" {
return
}
c.mu.Lock()
if c.titles == nil {
c.titles = map[string]string{}
}
c.titles[id] = title
s := c.sessions[id]
c.mu.Unlock()
if s != nil {
s.mu.Lock()
s.title = title
s.mu.Unlock()
}
}
func (c *Chat) forget(id string) {
c.mu.Lock()
delete(c.sessions, id)
c.mu.Unlock()
}
// reapIdle releases long-idle processes and caps how many can stay alive. The
// session record and its transcript-based history survive; the next prompt
// resumes the same Claude session.
func (c *Chat) reapIdle() {
ticker := time.NewTicker(time.Minute)
defer ticker.Stop()
for {
select {
case <-c.ctx.Done():
return
case <-ticker.C:
}
now := time.Now()
type candidate struct {
s *session
used time.Time
alive bool
}
var live []candidate
c.mu.Lock()
for _, s := range c.sessions {
s.mu.Lock()
alive := s.proc != nil
used := s.lastUsed
s.mu.Unlock()
if alive {
live = append(live, candidate{s: s, used: used})
}
}
c.mu.Unlock()
sort.Slice(live, func(i, j int) bool { return live[i].used.Before(live[j].used) })
for _, entry := range live {
entry.s.mu.Lock()
excess := len(live) > maxLiveProcesses && !entry.s.running
idle := !entry.s.running && len(entry.s.subs) == 0 && now.Sub(entry.used) > idleProcessExpiry
entry.s.mu.Unlock()
if excess || idle {
entry.s.closeProcess()
// Recompute the live count on the next tick after a close.
live = live[1:]
break
}
}
}
}
// ---------------------------------------------------------------------------
// Session state
type session struct {
chat *Chat
mu sync.Mutex
id string
directory string
title string
model string // CLI model selection (alias or full id); "" uses the CLI default
mode string // permission mode id; "" uses the CLI's own default
createdAt int64
proc *process
starting chan struct{}
startErr error
turnID string
running bool
// promptMu serializes writing user turns, so a prompt and a mid-turn
// message never both decide the CLI is idle. steered counts messages
// written into the running turn; awaitFollowUp is set when a turn ended
// with some outstanding, because the CLI then runs them as its own turn.
promptMu sync.Mutex
steered int
awaitFollowUp bool
lastUsed time.Time
lastErr string
// envNotices are directory-environment warnings from the last spawn,
// shown once in the next turn.
envNotices []string
subs map[chan protocol.ChatEventFrame]struct{}
approvals map[string]*pendingApproval
forms map[string]*pendingForm
shells map[string]*shellSnapshot
shellOrder []string
usage *protocol.ChatEventFrame
compaction *protocol.ChatEventFrame
// account is the signed-in account the live process reported.
account accountIdentity
prompts []promptRecord
models []protocol.ChatModel
// model is the requested selection; modelActual is the model the CLI last
// reported for a message. appliedModel is what the live process was told.
modelActual string
appliedModel string
// Stream assembly for the message currently being received.
streamID string
streamBlocks map[int]blockState
streamText map[int]string
streamOrdinals map[string]int
streamClaimed map[int]bool
toolMessages map[string]string
// injectedSeen holds the identities of agent reports and notices already
// published live, so a delivery the stream repeats is shown once.
injectedSeen map[string]bool
// silent is set while a reattached host replays output an earlier server
// already published: state is rebuilt, nothing is broadcast.
silent bool
}
type promptRecord struct {
id string
text string
}
type blockState struct {
kind string
ordinal int
}
func (s *session) sessionID() string { return s.id }
// emit broadcasts one frame to every watcher. A slow watcher never blocks the
// CLI reader; the hub repairs from history on its next subscription.
func (s *session) emit(frame protocol.ChatEventFrame) {
if frame.SessionID == "" {
frame.SessionID = s.id
}
s.mu.Lock()
if frame.Kind == protocol.ChatEventUsage && frame.Usage != nil {
usage := *frame.Usage
usage.Account = s.chat.accountUsage(s.account.key)
frame.Usage = &usage
s.usage = &frame
}
if frame.Kind == protocol.ChatEventCompaction && frame.Compaction != nil {
if frame.Compaction.Status == "running" {
s.compaction = &frame
} else {
s.compaction = nil
}
}
if s.silent {
s.mu.Unlock()
return
}
targets := make([]chan protocol.ChatEventFrame, 0, len(s.subs))
for ch := range s.subs {
targets = append(targets, ch)
}
s.mu.Unlock()
for _, ch := range targets {
select {
case ch <- frame:
default:
}
}
}
func (s *session) subscribe() chan protocol.ChatEventFrame {
ch := make(chan protocol.ChatEventFrame, 256)
s.mu.Lock()
s.subs[ch] = struct{}{}
if s.usage != nil {
// Account quota may have moved since (another chat on the account).
frame := *s.usage
usage := *frame.Usage
usage.Account = s.chat.accountUsage(s.account.key)
frame.Usage = &usage
ch <- frame
} else if account := s.chat.accountUsage(s.account.key); account != nil {
ch <- protocol.ChatEventFrame{SessionID: s.id, Kind: protocol.ChatEventUsage, Usage: &protocol.ChatUsage{Account: account}}
}
if s.compaction != nil {
ch <- *s.compaction
}
running := s.running
s.mu.Unlock()
if running {
// A client attaching mid-turn has missed earlier text. Ask it to reload
// the authoritative transcript instead of pretending the stream is whole.
select {
case ch <- protocol.ChatEventFrame{SessionID: s.id, Kind: protocol.ChatEventResync}:
default:
}
}
return ch
}
func (s *session) unsubscribe(ch chan protocol.ChatEventFrame) {
s.mu.Lock()
delete(s.subs, ch)
s.mu.Unlock()
}
func (s *session) closeProcess() {
s.mu.Lock()
p := s.proc
s.proc = nil
s.mu.Unlock()
if p != nil {
p.close()
}
}
// findTranscriptFile locates the CLI's session file. Project directories are
// named from the working directory, so searching is more robust than deriving
// the encoding (and avoids guessing for a resumed/adopted session).
// Sessions whose directory selects its own CLAUDE_CONFIG_DIR keep their
// transcripts there, so every config directory seen is searched too.
func findTranscriptFile(id string) string {
if id == "" {
return ""
}
for _, base := range configDirs() {
matches, err := filepath.Glob(filepath.Join(base, "projects", "*", id+".jsonl"))
if err != nil || len(matches) == 0 {
continue
}
sort.Strings(matches)
return matches[len(matches)-1]
}
return ""
}
var (
extraConfigMu sync.Mutex
extraConfigDirs []string
)
// rememberConfigDir records a directory-provided CLAUDE_CONFIG_DIR.
func rememberConfigDir(dir string) {
dir = strings.TrimSpace(dir)
if dir == "" || !filepath.IsAbs(dir) {
return
}
dir = filepath.Clean(dir)
extraConfigMu.Lock()
defer extraConfigMu.Unlock()
for _, known := range extraConfigDirs {
if known == dir {
return
}
}
extraConfigDirs = append(extraConfigDirs, dir)
}
func configDirs() []string {
var dirs []string
if base := ConfigDir(); base != "" {
dirs = append(dirs, filepath.Clean(base))
}
extraConfigMu.Lock()
defer extraConfigMu.Unlock()
for _, dir := range extraConfigDirs {
if len(dirs) == 0 || dir != dirs[0] {
dirs = append(dirs, dir)
}
}
return dirs
}
// newSessionID returns an RFC 4122 version 4 UUID, the exact form the CLI's
// --session-id accepts.
func newSessionID() (string, error) {
var raw [16]byte
if _, err := rand.Read(raw[:]); err != nil {
return "", err
}
raw[6] = (raw[6] & 0x0f) | 0x40
raw[8] = (raw[8] & 0x3f) | 0x80
hexed := hex.EncodeToString(raw[:])
return hexed[0:8] + "-" + hexed[8:12] + "-" + hexed[12:16] + "-" + hexed[16:20] + "-" + hexed[20:32], nil
}
var errNoBinary = errors.New("Claude Code is not installed (set PIPELINES_CLAUDE or install the claude CLI)")
func (s *session) requireBinary() error {
if s.chat.binary == "" {
return errNoBinary
}
if info, err := os.Stat(s.chat.binary); err != nil || info.IsDir() {
return errNoBinary
}
return nil
}