// 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 // catalog is the latest initialize model list of any session (efforts.go), // so a listed row names its levels without starting a CLI. catalogMu sync.Mutex catalog []protocol.ChatModel } 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 releases completed display snapshots, never liveness for // running tasks. A room/observer expiry is not permission to stop native work. func (c *Chat) ReleaseShells(id string) { if s := c.session(id); s != nil { s.mu.Lock() kept := make(map[string]*shellSnapshot) ids := map[string]bool{} for key, task := range s.shells { if task.shell.Status == protocol.ChatShellRunning { kept[key] = task ids[task.shell.ID] = true } } var order []string for _, id := range s.shellOrder { if ids[id] { order = append(order, id) } } s.shells, s.shellOrder = kept, order 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: } c.reapIdleAt(time.Now()) } } func (c *Chat) reapIdleAt(now time.Time) { type candidate struct { s *session used time.Time } 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() busy := entry.s.running || entry.s.hasAutomationsLocked() for _, task := range entry.s.shells { if task.shell.Status == protocol.ChatShellRunning { busy = true break } } excess := len(live) > maxLiveProcesses && !busy idle := !busy && len(entry.s.subs) == 0 && now.Sub(entry.used) > idleProcessExpiry entry.s.mu.Unlock() if excess || idle { entry.s.releaseIdleProcess() // 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 effort string // thinking level for the next turn; "" uses the CLI default createdAt int64 // toolsOff is set after a spawn carrying the Pipelines tools failed, so // the chat keeps starting without them (chattools). toolsOff bool 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 shellMetadataMu sync.Mutex shellLookupAfter time.Time shellScanAfter time.Time shellTranscriptPath string shellTranscriptSize int64 shellTranscriptMtime int64 shellTranscriptTargets map[string]bool usage *protocol.ChatEventFrame compaction *protocol.ChatEventFrame automations *claudehost.AutomationSnapshot automationProcess *process // 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() } // The cache reaper may relinquish an idle control connection, not stop a // hosted session. Only the host knows authoritative tasks beyond spool replay; // an explicit operator close remains the hard-close path below. func (s *session) releaseIdleProcess() { s.mu.Lock() if s.running || len(s.subs) > 0 || s.hasAutomationsLocked() { s.mu.Unlock() return } for _, task := range s.shells { if task.shell.Status == protocol.ChatShellRunning { s.mu.Unlock() return } } p := s.proc // Older hosts have no authoritative task capability and their detached idle // timer ignores background work. Keep their connection until explicit close. if p != nil && p.link != nil && !p.link.tasksKnown { s.mu.Unlock() return } s.proc = nil s.mu.Unlock() if p != nil { if p.link != nil { p.detach() } else { p.close() } } } 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 }