package claudehost import ( "bufio" "encoding/json" "errors" "flag" "fmt" "io" "log" "net" "os" "os/exec" "os/signal" "sort" "strings" "sync" "syscall" "time" ) // Defaults for a host started without explicit limits. const ( DefaultIdle = 20 * time.Minute DefaultMaxDetached = time.Duration(0) DefaultSpoolLimit = 64 << 20 maxLineBytes = 32 << 20 stderrRetained = 8 << 10 ) type lineRef struct{ start, end int64 } type transition struct { offset int64 busy bool } type client struct { conn net.Conn writeMu sync.Mutex gone chan struct{} once sync.Once exitSent bool } func (c *client) send(frame Frame) error { data, err := json.Marshal(frame) if err != nil { return err } data = append(data, '\n') c.writeMu.Lock() defer c.writeMu.Unlock() _, err = c.conn.Write(data) return err } func (c *client) close() { c.once.Do(func() { close(c.gone) _ = c.conn.Close() }) } type host struct { dir string id string paths Paths idle time.Duration maxDetached time.Duration spoolLimit int64 listener net.Listener cmd *exec.Cmd stdin io.WriteCloser stdinMu sync.Mutex fileMu sync.RWMutex // guards spool replacement against readers mu sync.Mutex spool *os.File base int64 end int64 lines []lineRef acked int64 trans []transition busy bool // pending maps unanswered CLI control request ids to their offsets. tasks map[string]string // running native background tools, independent of foreground busy taskOrigins map[string]Task // native identity/metadata retained independently of spool compaction pending map[string]int64 initID string init json.RawMessage modelReqs map[string]string modeReqs map[string]string model string mode string automations *AutomationSnapshot exited bool exitErr string exitedAt time.Time stderr strings.Builder changed chan struct{} active *client detached time.Time activity time.Time stopping bool stopped chan struct{} claudeEnd chan struct{} } // Main runs a host. args are the host flags, then "--", then the Claude Code // executable and its arguments. The working directory and environment are the // CLI's own. It returns the process exit code. func Main(args []string) int { flags := flag.NewFlagSet("pipelines-claude-host", flag.ContinueOnError) dir := flags.String("dir", "", "private host directory (registry, socket, spool)") id := flags.String("id", "", "Claude session id") idle := flags.Duration("idle", DefaultIdle, "release an idle CLI after this long with no server attached") maxDetached := flags.Duration("max-detached", DefaultMaxDetached, "optional detached lifetime limit (0 keeps live sessions until explicitly closed)") spoolLimit := flags.Int64("spool-limit", DefaultSpoolLimit, "bytes of acknowledged output kept in the spool") if err := flags.Parse(args); err != nil { return 2 } command := flags.Args() if len(command) == 0 || *id == "" || *dir == "" { fmt.Fprintln(os.Stderr, "usage: pipelines-claude-host -dir DIR -id SESSION -- claude ARGS...") return 2 } log.SetFlags(log.LstdFlags) log.SetPrefix("claude-host " + *id + ": ") syscall.Umask(0o077) if err := EnsureDir(*dir); err != nil { log.Print(err) return 1 } h := &host{ dir: *dir, id: *id, paths: PathsFor(*dir, *id), idle: *idle, maxDetached: *maxDetached, spoolLimit: *spoolLimit, pending: map[string]int64{}, modelReqs: map[string]string{}, modeReqs: map[string]string{}, changed: make(chan struct{}), stopped: make(chan struct{}), claudeEnd: make(chan struct{}), trans: []transition{{offset: 0, busy: false}}, activity: time.Now(), detached: time.Now(), } h.model, h.mode = flagValue(command, "--model"), flagValue(command, "--permission-mode") if err := h.start(command); err != nil { log.Print(err) fmt.Fprintln(os.Stdout, "error "+strings.ReplaceAll(err.Error(), "\n", " ")) return 1 } // The server waits for this line, then stops reading our stdout. fmt.Fprintln(os.Stdout, "ready "+h.paths.Socket) if null, err := os.OpenFile(os.DevNull, os.O_RDWR, 0); err == nil { _ = syscall.Dup2(int(null.Fd()), 1) _ = syscall.Dup2(int(null.Fd()), 0) _ = null.Close() } signals := make(chan os.Signal, 2) signal.Ignore(syscall.SIGHUP, syscall.SIGPIPE) signal.Notify(signals, syscall.SIGTERM, syscall.SIGINT) go func() { <-signals h.shutdown("signal") }() go h.accept() go h.watchIdle() <-h.stopped return 0 } func flagValue(args []string, name string) string { for index, arg := range args { if arg == name && index+1 < len(args) { return args[index+1] } if strings.HasPrefix(arg, name+"=") { return strings.TrimPrefix(arg, name+"=") } } return "" } func (h *host) start(command []string) error { if conn, err := net.DialTimeout("unix", h.paths.Socket, time.Second); err == nil { _ = conn.Close() return errors.New("a host is already serving this session") } _ = os.Remove(h.paths.Socket) spool, err := os.OpenFile(h.paths.Spool, os.O_CREATE|os.O_TRUNC|os.O_RDWR, 0o600) if err != nil { return err } h.spool = spool listener, err := net.Listen("unix", h.paths.Socket) if err != nil { return err } _ = os.Chmod(h.paths.Socket, 0o600) h.listener = listener cmd := exec.Command(command[0], command[1:]...) cmd.Env = os.Environ() // Its own process group, so the CLI and its tool subprocesses stop together. cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true} stdin, err := cmd.StdinPipe() if err != nil { return err } stdout, err := cmd.StdoutPipe() if err != nil { return err } stderr, err := cmd.StderrPipe() if err != nil { return err } if err := cmd.Start(); err != nil { _ = listener.Close() _ = os.Remove(h.paths.Socket) return fmt.Errorf("start Claude Code: %w", err) } h.cmd, h.stdin = cmd, stdin cwd, _ := os.Getwd() record := Record{Version: Version, SessionID: h.id, HostPID: os.Getpid(), ClaudePID: cmd.Process.Pid, Socket: h.paths.Socket, Spool: h.paths.Spool, Directory: cwd, Created: time.Now().UnixMilli()} data, _ := json.Marshal(record) if err := writeFileAtomic(h.paths.Record, data); err != nil { _ = cmd.Process.Kill() return err } stderrDone := make(chan struct{}) go h.readStderr(stderr, stderrDone) readDone := make(chan struct{}) go h.readStdout(stdout, readDone) go func() { err := cmd.Wait() <-readDone select { case <-stderrDone: case <-time.After(time.Second): } h.mu.Lock() h.exited = true h.exitedAt = time.Now() if err != nil { h.exitErr = err.Error() } h.broadcastLocked() h.mu.Unlock() close(h.claudeEnd) }() return nil } func (h *host) readStderr(stderr io.Reader, done chan struct{}) { defer close(done) buffer := make([]byte, 4<<10) for { n, err := stderr.Read(buffer) if n > 0 { h.mu.Lock() if remaining := stderrRetained - h.stderr.Len(); remaining > 0 { if n > remaining { n = remaining } h.stderr.Write(buffer[:n]) } h.mu.Unlock() } if err != nil { return } } } func (h *host) readStdout(stdout io.Reader, done chan struct{}) { defer close(done) reader := bufio.NewReaderSize(stdout, 64<<10) for { line, err := reader.ReadBytes('\n') if len(line) > 0 && len(line) <= maxLineBytes { trimmed := strings.TrimSpace(string(line)) if trimmed != "" { h.appendLine([]byte(trimmed)) } } if err != nil { return } } } // broadcastLocked wakes every sender. Callers hold h.mu. func (h *host) broadcastLocked() { close(h.changed) h.changed = make(chan struct{}) } type snoop struct { Type string `json:"type"` Subtype string `json:"subtype"` RequestID string `json:"request_id"` ParentToolUseID string `json:"parent_tool_use_id"` Request struct { Subtype string `json:"subtype"` Model string `json:"model"` Mode string `json:"mode"` CallbackID string `json:"callback_id"` Input json.RawMessage `json:"input"` } `json:"request"` Response struct { Subtype string `json:"subtype"` RequestID string `json:"request_id"` Response json.RawMessage `json:"response"` } `json:"response"` } func (h *host) setBusyLocked(busy bool, offset int64) { if h.busy == busy { return } h.busy = busy h.trans = append(h.trans, transition{offset: offset, busy: busy}) } func (h *host) busyAtLocked(offset int64) bool { busy := false for _, t := range h.trans { if t.offset > offset { break } busy = t.busy } return busy } func (h *host) appendLine(line []byte) { var env snoop _ = json.Unmarshal(line, &env) h.mu.Lock() ackObserver := false start := h.end data := append(append([]byte(nil), line...), '\n') h.fileMu.RLock() _, err := h.spool.WriteAt(data, start-h.base) h.fileMu.RUnlock() if err != nil { log.Printf("spool write: %v", err) } h.end += int64(len(data)) h.lines = append(h.lines, lineRef{start: start, end: h.end}) h.activity = time.Now() h.trackTasksLocked(line) switch env.Type { case "control_request": if env.RequestID != "" { h.pending[env.RequestID] = start } if env.Request.Subtype == "hook_callback" { if IsAutomationHook(env.Request.CallbackID) { snapshot, _ := ParseAutomationHook(env.Request.CallbackID, h.id, env.Request.Input, time.Now().UnixMilli()) h.automations = snapshot delete(h.pending, env.RequestID) ackObserver = true } } case "control_cancel_request": delete(h.pending, env.RequestID) case "control_response": id := env.Response.RequestID if env.Response.Subtype == "success" { if id != "" && id == h.initID { h.init = append(json.RawMessage(nil), env.Response.Response...) } if model, ok := h.modelReqs[id]; ok { h.model = model } if mode, ok := h.modeReqs[id]; ok { h.mode = mode } } delete(h.modelReqs, id) delete(h.modeReqs, id) case "result": h.setBusyLocked(false, h.end) // A finished turn no longer waits on any approval. h.pending = map[string]int64{} case "stream_event", "assistant": if env.ParentToolUseID == "" { h.setBusyLocked(true, start) } } h.compactLocked() h.broadcastLocked() h.mu.Unlock() if ackObserver { response, _ := json.Marshal(map[string]any{"type": "control_response", "response": map[string]any{ "subtype": "success", "request_id": env.RequestID, "response": map[string]any{}, }}) h.writeIn(response) } } // compactLocked bounds the spool. Acknowledged output beyond the limit is // dropped first; unacknowledged output is dropped only beyond four times the // limit (a server gone for very long), which a reconnecting server sees as a // gap because Acked < Base. func (h *host) compactLocked() { size := h.end - h.base if size <= h.spoolLimit { return } keep := h.acked if h.end-keep > 4*h.spoolLimit { keep = h.end - h.spoolLimit } index := sort.Search(len(h.lines), func(i int) bool { return h.lines[i].start >= keep }) if index == 0 || index >= len(h.lines) { return } keep = h.lines[index].start if keep-h.base < size/4 { return // not worth rewriting yet } next, err := os.OpenFile(h.paths.Spool+".next", os.O_CREATE|os.O_TRUNC|os.O_RDWR, 0o600) if err != nil { return } h.fileMu.Lock() defer h.fileMu.Unlock() if _, err := io.Copy(next, io.NewSectionReader(h.spool, keep-h.base, h.end-keep)); err != nil { _ = next.Close() _ = os.Remove(h.paths.Spool + ".next") return } if err := os.Rename(h.paths.Spool+".next", h.paths.Spool); err != nil { _ = next.Close() return } _ = h.spool.Close() h.spool = next h.base = keep h.lines = append([]lineRef(nil), h.lines[index:]...) } func (h *host) statusLocked() *Status { pending := make([]Pending, 0, len(h.pending)) for id, offset := range h.pending { pending = append(pending, Pending{ID: id, Offset: offset}) } sort.Slice(pending, func(i, j int) bool { return pending[i].Offset < pending[j].Offset }) cwd, _ := os.Getwd() tasks := make([]Task, 0, len(h.tasks)) for key, taskID := range h.tasks { task := h.taskOrigins[key] if task.ToolUseID == "" && !strings.HasPrefix(key, "task:") { task.ToolUseID = key } if task.TaskID == "" { task.TaskID = taskID } tasks = append(tasks, task) } sort.Slice(tasks, func(i, j int) bool { if tasks[i].ToolUseID == tasks[j].ToolUseID { return tasks[i].TaskID < tasks[j].TaskID } return tasks[i].ToolUseID < tasks[j].ToolUseID }) status := &Status{ Version: Version, SessionID: h.id, HostPID: os.Getpid(), Base: h.base, End: h.end, Acked: h.acked, Busy: h.busy, BusyAtAcked: h.busyAtLocked(h.acked), Init: h.init, Model: h.model, Mode: h.mode, Pending: pending, Tasks: &tasks, Exited: h.exited, ExitErr: h.exitErr, Stderr: h.stderr.String(), Directory: cwd, Automations: h.automations, } if h.cmd != nil && h.cmd.Process != nil { status.ClaudePID = h.cmd.Process.Pid } return status } func (h *host) accept() { for { conn, err := h.listener.Accept() if err != nil { return } c := &client{conn: conn, gone: make(chan struct{})} go h.serveClient(c) } } func (h *host) serveClient(c *client) { defer h.dropClient(c) reader := bufio.NewReaderSize(c.conn, 64<<10) for { line, err := reader.ReadBytes('\n') if len(strings.TrimSpace(string(line))) > 0 { var frame Frame if json.Unmarshal(line, &frame) != nil { _ = c.send(Frame{Op: OpError, Error: "invalid frame"}) } else if !h.handle(c, frame) { return } } if err != nil { return } } } func (h *host) dropClient(c *client) { c.close() h.mu.Lock() if h.active == c { h.active = nil h.detached = time.Now() } h.mu.Unlock() } // handle runs one client frame; false ends the connection. func (h *host) handle(c *client, frame Frame) bool { switch frame.Op { case OpAttach: h.mu.Lock() previous := h.active h.active = c status := h.statusLocked() h.mu.Unlock() if previous != nil && previous != c { previous.close() } if err := c.send(Frame{Op: OpStatus, Status: status}); err != nil { return false } go h.deliver(c, frame.Offset) case OpIn: h.writeIn(frame.Data) case OpAck: h.mu.Lock() if frame.Offset > h.acked && frame.Offset <= h.end { h.acked = frame.Offset h.trimTransitionsLocked() } h.mu.Unlock() case OpStatus: h.mu.Lock() status := h.statusLocked() h.mu.Unlock() _ = c.send(Frame{Op: OpStatus, Status: status}) case OpClose: h.stopClaude() _ = c.send(Frame{Op: OpClosed}) h.shutdown("closed") return false default: _ = c.send(Frame{Op: OpError, Error: "unknown op " + frame.Op}) } return true } func (h *host) trimTransitionsLocked() { keep := 0 for i, t := range h.trans { if t.offset <= h.acked { keep = i } } h.trans = append([]transition(nil), h.trans[keep:]...) } func (h *host) writeIn(data json.RawMessage) { if len(data) == 0 { return } var env snoop _ = json.Unmarshal(data, &env) h.mu.Lock() h.activity = time.Now() switch env.Type { case "user": h.setBusyLocked(true, h.end) case "control_response": delete(h.pending, env.Response.RequestID) case "control_request": switch env.Request.Subtype { case "initialize": h.initID = env.RequestID case "set_model": h.modelReqs[env.RequestID] = env.Request.Model case "set_permission_mode": h.modeReqs[env.RequestID] = env.Request.Mode } } h.mu.Unlock() line := append(append([]byte(nil), data...), '\n') h.stdinMu.Lock() defer h.stdinMu.Unlock() if _, err := h.stdin.Write(line); err != nil { log.Printf("write to Claude Code: %v", err) } } // deliver streams spooled lines from offset, then the exit, to one client. func (h *host) deliver(c *client, offset int64) { cursor := offset for { h.mu.Lock() if h.active != c { h.mu.Unlock() return } index := sort.Search(len(h.lines), func(i int) bool { return h.lines[i].start >= cursor }) if index < len(h.lines) { ref := h.lines[index] h.fileMu.RLock() h.mu.Unlock() data := make([]byte, ref.end-ref.start) _, err := h.spool.ReadAt(data, ref.start-h.base) h.fileMu.RUnlock() if err != nil { log.Printf("spool read: %v", err) c.close() return } if err := c.send(Frame{Op: OpOut, Offset: ref.start, End: ref.end, Data: json.RawMessage(strings.TrimSpace(string(data)))}); err != nil { c.close() return } cursor = ref.end continue } if h.exited && !c.exitSent { c.exitSent = true status := h.statusLocked() h.mu.Unlock() _ = c.send(Frame{Op: OpExit, Status: status, Error: status.ExitErr}) // The server has everything; it closes the connection, then we go. go func() { select { case <-c.gone: case <-time.After(30 * time.Second): } h.shutdown("exited") }() continue } changed := h.changed h.mu.Unlock() select { case <-changed: case <-c.gone: return case <-h.stopped: return } } } // stopClaude ends the CLI: stdin EOF, then an interrupt, then a kill, to the // CLI's whole process group. func (h *host) stopClaude() { if h.cmd == nil || h.cmd.Process == nil { return } h.stdinMu.Lock() _ = h.stdin.Close() h.stdinMu.Unlock() pid := h.cmd.Process.Pid select { case <-h.claudeEnd: return case <-time.After(500 * time.Millisecond): } _ = syscall.Kill(-pid, syscall.SIGINT) select { case <-h.claudeEnd: return case <-time.After(3 * time.Second): } _ = syscall.Kill(-pid, syscall.SIGKILL) select { case <-h.claudeEnd: case <-time.After(2 * time.Second): } } // shutdown stops the CLI, removes the host files and ends Main. func (h *host) shutdown(reason string) { h.mu.Lock() if h.stopping { h.mu.Unlock() return } h.stopping = true active := h.active h.mu.Unlock() log.Printf("stopping (%s)", reason) h.stopClaude() _ = h.listener.Close() Remove(h.dir, h.id) _ = os.Remove(h.paths.Spool + ".next") if active != nil { active.close() } close(h.stopped) } // watchIdle releases the CLI while no server is attached: after the idle // expiry when nothing is in flight (the same release the server applies), and // after maxDetached regardless. A CLI that exited with nobody attached is // cleaned up after the idle expiry. func (h *host) watchIdle() { tick := h.idle / 10 if tick > 5*time.Second { tick = 5 * time.Second } if tick < 50*time.Millisecond { tick = 50 * time.Millisecond } ticker := time.NewTicker(tick) defer ticker.Stop() for { select { case <-h.stopped: return case <-ticker.C: } now := time.Now() h.mu.Lock() attached := h.active != nil automationsPending := h.automations != nil && len(h.automations.IDs) > 0 idle := !h.busy && len(h.pending) == 0 && len(h.tasks) == 0 && !automationsPending && now.Sub(h.detached) > h.idle && now.Sub(h.activity) > h.idle tooLong := h.maxDetached > 0 && now.Sub(h.detached) > h.maxDetached exitedLong := h.exited && now.Sub(h.exitedAt) > h.idle h.mu.Unlock() if attached { continue } switch { case exitedLong: h.shutdown("exited with no server attached") return case idle: h.shutdown("idle with no server attached") return case tooLong: h.shutdown("no server attached for " + h.maxDetached.String()) return } } }