// Package claudehost keeps one Claude Code CLI process alive across Pipelines // server restarts. // // The server cannot own a `claude -p` process directly and also restart: the // CLI's stdin/stdout pipes die with their parent. A host is a small helper // process in its own session that owns those pipes instead. It spools the // CLI's stream-json output to a bounded per-session file with byte offsets and // serves one local Unix socket (0600, in a 0700 directory) on which the server // writes stdin frames, reads output from an offset, acknowledges what it has // processed, and finally closes the host. A restarted server finds live hosts // through their registry files, reconnects and replays from its last // acknowledged offset. // // The wire format is one JSON object per line in both directions. package claudehost import ( "crypto/sha256" "encoding/hex" "encoding/json" "errors" "os" "path/filepath" "strings" ) // NativeAutomationCallbackID is private to this adapter. Other hook callbacks // (and operator permission requests) must never be acknowledged as snapshots. const NativeAutomationCallbackID = "pipelines-native-session-automations-v1" const MaxAutomationEntries = 128 // Version is the host protocol version reported in every status. const Version = 1 // Client-to-host operations. const ( // OpAttach starts (or restarts) delivery from Frame.Offset. The host // replies with OpStatus, then streams OpOut frames. A newer attach replaces // an older connection. OpAttach = "attach" // OpIn writes Frame.Data, one JSON line, to the CLI's stdin. OpIn = "in" // OpAck commits that output up to Frame.Offset has been processed. OpAck = "ack" // OpStatus asks for a status snapshot without changing delivery. OpStatus = "status" // OpClose stops the CLI and the host. The host replies OpClosed. OpClose = "close" ) // Host-to-client operations. const ( OpOut = "out" OpExit = "exit" OpClosed = "closed" OpError = "error" ) // Frame is one line on the socket. type Frame struct { Op string `json:"op"` Offset int64 `json:"offset,omitempty"` End int64 `json:"end,omitempty"` Data json.RawMessage `json:"data,omitempty"` Status *Status `json:"status,omitempty"` Error string `json:"error,omitempty"` } // Pending is a CLI control request (can_use_tool, a hook) that nobody has // answered yet. It survives a disconnected server. type Pending struct { ID string `json:"id"` Offset int64 `json:"offset"` } // Task is a native background tool still owned by the hosted CLI. It is kept // separately from the bounded output spool, so trimming old output cannot erase // the identity needed by a reattaching server. Missing metadata stays absent. type Task struct { ToolUseID string `json:"tool_use_id,omitempty"` TaskID string `json:"task_id,omitempty"` Name string `json:"name,omitempty"` Description string `json:"description,omitempty"` TaskType string `json:"task_type,omitempty"` Command string `json:"command,omitempty"` Timestamp string `json:"timestamp,omitempty"` } // Status is the host's snapshot of its CLI. type Status struct { Version int `json:"version"` SessionID string `json:"session_id"` HostPID int `json:"host_pid"` ClaudePID int `json:"claude_pid"` // Base is the oldest offset still in the spool; End is the offset after the // last spooled line; Acked is the last offset a client committed. Base int64 `json:"base"` End int64 `json:"end"` Acked int64 `json:"acked"` // Busy is whether a turn is in flight now; BusyAtAcked is whether one was // in flight at the Acked offset, which is where a reconnecting server's // live processing resumes. Busy bool `json:"busy"` BusyAtAcked bool `json:"busy_at_acked"` // Tasks is the authoritative running background set at End. Nil means an // older host did not report this capability; a nonnil empty list means it // knows that no background tasks remain. Reconcile after replay reaches End. Tasks *[]Task `json:"tasks,omitempty"` // Init is the CLI's initialize response (models, account), so a // reconnecting server does not initialize the CLI twice. Init json.RawMessage `json:"init,omitempty"` // Model and Mode are the CLI's model and permission mode as last applied // (start flags, then successful set_model / set_permission_mode). Model string `json:"model,omitempty"` Mode string `json:"mode,omitempty"` Pending []Pending `json:"pending"` Exited bool `json:"exited,omitempty"` ExitErr string `json:"exit_error,omitempty"` Stderr string `json:"stderr,omitempty"` // Directory is the CLI's working directory. Directory string `json:"directory,omitempty"` // Automations is the last validated native Stop-hook snapshot. A nil value // means unknown (including hosts that predate this capability). Automations *AutomationSnapshot `json:"automations,omitempty"` } // AutomationSnapshot contains only bounded native schedule identities and a // count. This snapshot omits prompts; native CLI events follow the existing // bounded private spool policy. type AutomationSnapshot struct { SessionID string `json:"session_id"` IDs []string `json:"ids"` ObservedAtMS int64 `json:"observed_at_ms"` } // IsAutomationHook recognizes the private callback without making any claim // about its optional metadata. Recognized callbacks must always be answered. func IsAutomationHook(callbackID string) bool { return callbackID == NativeAutomationCallbackID } // ParseAutomationHook accepts only the SDK's main-thread Stop input. It returns // false for absent or malformed metadata; callers should still acknowledge a // callback recognized by IsAutomationHook, while treating the snapshot as // unknown. func ParseAutomationHook(callbackID, expectedSession string, input json.RawMessage, nowMS int64) (*AutomationSnapshot, bool) { if callbackID != NativeAutomationCallbackID || expectedSession == "" || len(input) == 0 || len(input) > 1<<20 { return nil, false } var hook struct { SessionID string `json:"session_id"` HookEventName string `json:"hook_event_name"` SessionCrons *[]struct { ID string `json:"id"` } `json:"session_crons"` } if json.Unmarshal(input, &hook) != nil || hook.SessionID != expectedSession || hook.HookEventName != "Stop" || hook.SessionCrons == nil || len(*hook.SessionCrons) > MaxAutomationEntries { return nil, false } ids := make([]string, 0, len(*hook.SessionCrons)) seen := map[string]bool{} for _, cron := range *hook.SessionCrons { if cron.ID == "" || len(cron.ID) > 256 || seen[cron.ID] { return nil, false } seen[cron.ID] = true ids = append(ids, cron.ID) } return &AutomationSnapshot{SessionID: expectedSession, IDs: ids, ObservedAtMS: nowMS}, true } // Record is the registry file a host writes next to its socket so a // restarted server can find it. type Record struct { Version int `json:"version"` SessionID string `json:"session_id"` HostPID int `json:"host_pid"` ClaudePID int `json:"claude_pid"` Socket string `json:"socket"` Spool string `json:"spool"` Directory string `json:"directory"` Created int64 `json:"created"` } // Key is the short file name used for a session's host files. Unix socket // paths are limited to about 100 bytes, so the session id is hashed. func Key(sessionID string) string { sum := sha256.Sum256([]byte(sessionID)) return hex.EncodeToString(sum[:8]) } // Paths are one session's files inside a host directory. type Paths struct { Socket, Record, Spool, Log string } func PathsFor(dir, sessionID string) Paths { key := Key(sessionID) return Paths{ Socket: filepath.Join(dir, key+".sock"), Record: filepath.Join(dir, key+".json"), Spool: filepath.Join(dir, key+".spool"), Log: filepath.Join(dir, key+".log"), } } // EnsureDir creates a private host directory. func EnsureDir(dir string) error { if strings.TrimSpace(dir) == "" || !filepath.IsAbs(dir) { return errors.New("the Claude host directory must be absolute") } if err := os.MkdirAll(dir, 0o700); err != nil { return err } return os.Chmod(dir, 0o700) } // Records lists the registry files in dir. Unreadable files are skipped. func Records(dir string) []Record { matches, _ := filepath.Glob(filepath.Join(dir, "*.json")) records := make([]Record, 0, len(matches)) for _, path := range matches { data, err := os.ReadFile(path) if err != nil { continue } var record Record if json.Unmarshal(data, &record) != nil || record.SessionID == "" || record.Socket == "" { continue } records = append(records, record) } return records } // Remove deletes one session's host files. func Remove(dir, sessionID string) { paths := PathsFor(dir, sessionID) for _, path := range []string{paths.Record, paths.Socket, paths.Spool, paths.Log} { _ = os.Remove(path) } } func writeFileAtomic(path string, data []byte) error { tmp := path + ".tmp" if err := os.WriteFile(tmp, data, 0o600); err != nil { return err } return os.Rename(tmp, path) }