Files
pipelines/internal/claude/claude.go
T
alan 01040a7b12 Stop the replaced session on /new for every harness
/new already released the old native session through the chat-close
release path, but two gaps let the replaced session stay alive, and the
client told the operator it could still be resumed in a terminal:

- Claude Code: ReleaseSession only closed a host this server was
  attached to. A host registered for the session but not attached (a
  failed reattach, or one left by an earlier server) kept running. It is
  now asked to close over its socket and killed as a fallback.
- Codex: ReleaseSession only interrupted an active turn. It now also
  sends thread/unsubscribe so the App Server unloads the thread; a later
  prompt reloads it through the existing "thread not found" resume path.
- The /new notice now says the previous session was stopped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 18:10:41 +00:00

606 lines
17 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
// 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()
}
}
}
// closeProcess stops the session's CLI and reports whether one was attached.
func (s *session) closeProcess() bool {
s.mu.Lock()
p := s.proc
s.proc = nil
s.mu.Unlock()
if p != nil {
p.close()
}
return p != nil
}
// 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
}