Files
pipelines/internal/claude/claude.go
T
alan 06001697c8 Add per-chat thinking levels for Codex, Claude Code and OpenCode
Codex: model/list supportedReasoningEfforts per model, turn/start effort,
thread reasoningEffort as the current level. Claude Code: initialize
supportedEffortLevels, apply_flag_settings effortLevel at the next turn
start. OpenCode v2: model variants via the session model endpoint.
chat_effort sets a level; rows and chat_models carry the levels; Codex and
Claude levels persist in operator_sessions.chat_effort and are re-applied
before every turn.
2026-11-09 20:07:41 +00:00

604 lines
16 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()
}
}
}
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
}