// 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. It never // changes the operator's Claude configuration, starts a daemon, or invents a // transcript: history is read back from the CLI's own session files. package claude import ( "context" "crypto/rand" "encoding/hex" "errors" "os" "os/exec" "path/filepath" "sort" "strings" "sync" "time" "git.a-wan.net/alan/pipelines/internal/protocol" ) // 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 mu sync.Mutex sessions map[string]*session closed bool } func New(ctx context.Context) *Chat { if ctx == nil { ctx = context.Background() } ctx, cancel := context.WithCancel(ctx) c := &Chat{ctx: ctx, cancel: cancel, binary: BinaryPath(), sessions: map[string]*session{}} go c.reapIdle() return c } // Close stops every owned CLI process. Session transcripts stay on disk. 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{}, lastUsed: time.Now(), } c.sessions[id] = s return s } 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 createdAt int64 proc *process starting chan struct{} startErr error turnID string running bool lastUsed time.Time lastErr 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 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 toolMessages map[string]string } 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 { s.usage = &frame } if frame.Kind == protocol.ChatEventCompaction && frame.Compaction != nil { if frame.Compaction.Status == "running" { s.compaction = &frame } else { s.compaction = nil } } 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 { ch <- *s.usage } 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). func findTranscriptFile(id string) string { base := ConfigDir() if base == "" || id == "" { return "" } matches, err := filepath.Glob(filepath.Join(base, "projects", "*", id+".jsonl")) if err != nil || len(matches) == 0 { return "" } sort.Strings(matches) return matches[len(matches)-1] } // 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 }