// Package codex brokers an operator chat through the Codex App Server. // // Codex exposes threads, turns and items over JSON-RPC. The App Server is // normally reached over a Unix WebSocket socket (the desktop app and the CLI use // the same control socket). This adapter owns one client connection and mirrors // the protocol into the Pipelines chat frames; it never starts a second Codex // daemon or changes the operator's Codex configuration. package codex import ( "context" "encoding/json" "errors" "fmt" "net" "net/http" "os" "path/filepath" "strconv" "strings" "sync" "time" "git.a-wan.net/alan/pipelines/internal/protocol" "github.com/coder/websocket" ) // Backend is the wire value stored in the operator-session registry. const Backend = "codex" // DefaultSocketPath is the Codex desktop app-server control socket. func DefaultSocketPath() string { home := os.Getenv("CODEX_HOME") if home == "" { userHome, err := os.UserHomeDir() if err != nil { return "" } home = filepath.Join(userHome, ".codex") } return filepath.Join(home, "app-server-control", "app-server-control.sock") } // Chat is one owned App Server connection. type Chat struct { conn *websocket.Conn ctx context.Context cancel context.CancelFunc writeMu sync.Mutex nextID int64 mu sync.Mutex pending map[string]chan rpcResponse subs map[string]map[chan protocol.ChatEventFrame]struct{} forms map[string]pendingForm turns map[string]string emitted map[string]bool closed bool } type pendingForm struct { requestID json.RawMessage threadID string form protocol.ChatForm } type rpcResponse struct { Result json.RawMessage Error *rpcError } type rpcError struct { Code int `json:"code"` Message string `json:"message"` } type rpcMessage struct { ID json.RawMessage `json:"id"` Method string `json:"method"` Params json.RawMessage `json:"params"` Result json.RawMessage `json:"result"` Error *rpcError `json:"error"` } // Open connects to the app-server socket and performs the initialize handshake. func Open(ctx context.Context) (*Chat, error) { socket := DefaultSocketPath() if socket == "" { return nil, errors.New("Codex home is unavailable") } transport := &http.Transport{ DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) { return (&net.Dialer{}).DialContext(ctx, "unix", socket) }, } client := &http.Client{Transport: transport} conn, _, err := websocket.Dial(ctx, "ws://localhost/", &websocket.DialOptions{HTTPClient: client}) if err != nil { return nil, fmt.Errorf("connect Codex app-server: %w", err) } conn.SetReadLimit(16 << 20) child, cancel := context.WithCancel(ctx) c := &Chat{ conn: conn, ctx: child, cancel: cancel, pending: map[string]chan rpcResponse{}, subs: map[string]map[chan protocol.ChatEventFrame]struct{}{}, forms: map[string]pendingForm{}, turns: map[string]string{}, emitted: map[string]bool{}, } go c.readLoop() initCtx, initCancel := context.WithTimeout(ctx, 10*time.Second) defer initCancel() if _, err := c.call(initCtx, "initialize", map[string]any{ "clientInfo": map[string]any{"name": "pipelines", "title": "Pipelines", "version": "0.1"}, }); err != nil { c.Close() return nil, fmt.Errorf("initialize Codex app-server: %w", err) } return c, nil } // Available reports whether the app-server control socket exists. func Available() bool { path := DefaultSocketPath() if path == "" { return false } info, err := os.Stat(path) return err == nil && info.Mode()&os.ModeSocket != 0 } // Close shuts the owned client connection down. func (c *Chat) Close() { c.mu.Lock() if c.closed { c.mu.Unlock() return } c.closed = true c.mu.Unlock() c.cancel() _ = c.conn.Close(websocket.StatusNormalClosure, "") } func (c *Chat) readLoop() { for { _, data, err := c.conn.Read(c.ctx) if err != nil { c.failPending(err) return } var msg rpcMessage if err := json.Unmarshal(data, &msg); err != nil { continue } if len(msg.ID) > 0 && msg.Method != "" { c.handleServerRequest(msg) continue } if len(msg.ID) > 0 { key := string(msg.ID) c.mu.Lock() ch := c.pending[key] delete(c.pending, key) c.mu.Unlock() if ch != nil { ch <- rpcResponse{Result: msg.Result, Error: msg.Error} } continue } if msg.Method != "" { c.handleNotification(msg) } } } func (c *Chat) failPending(err error) { c.mu.Lock() pending := c.pending c.pending = map[string]chan rpcResponse{} subs := c.subs c.subs = map[string]map[chan protocol.ChatEventFrame]struct{}{} c.mu.Unlock() for _, ch := range pending { ch <- rpcResponse{Error: &rpcError{Message: err.Error()}} } for _, set := range subs { for ch := range set { close(ch) } } } func (c *Chat) call(ctx context.Context, method string, params any) (json.RawMessage, error) { c.mu.Lock() if c.closed { c.mu.Unlock() return nil, errors.New("Codex connection is closed") } c.nextID++ id := c.nextID ch := make(chan rpcResponse, 1) c.pending[strconv.FormatInt(id, 10)] = ch c.mu.Unlock() payload := map[string]any{"id": id, "method": method} if params != nil { payload["params"] = params } data, err := json.Marshal(payload) if err != nil { return nil, err } c.writeMu.Lock() err = c.conn.Write(ctx, websocket.MessageText, data) c.writeMu.Unlock() if err != nil { c.mu.Lock() delete(c.pending, strconv.FormatInt(id, 10)) c.mu.Unlock() return nil, err } select { case <-ctx.Done(): c.mu.Lock() delete(c.pending, strconv.FormatInt(id, 10)) c.mu.Unlock() return nil, ctx.Err() case resp := <-ch: if resp.Error != nil { return nil, errors.New(resp.Error.Message) } return resp.Result, nil } } func (c *Chat) respond(id json.RawMessage, result any) { payload := map[string]any{"id": id, "result": result} data, err := json.Marshal(payload) if err != nil { return } c.writeMu.Lock() _ = c.conn.Write(c.ctx, websocket.MessageText, data) c.writeMu.Unlock() } func (c *Chat) emit(frame protocol.ChatEventFrame) { c.mu.Lock() set := c.subs[frame.SessionID] var targets []chan protocol.ChatEventFrame for ch := range set { targets = append(targets, ch) } c.mu.Unlock() for _, ch := range targets { select { case ch <- frame: default: // A slow client must not block the shared Codex connection. The hub // will repair from history on its next subscription. } } } func (c *Chat) subscribe(id string) chan protocol.ChatEventFrame { ch := make(chan protocol.ChatEventFrame, 256) c.mu.Lock() if c.subs[id] == nil { c.subs[id] = map[chan protocol.ChatEventFrame]struct{}{} } c.subs[id][ch] = struct{}{} c.mu.Unlock() return ch } func (c *Chat) unsubscribe(id string, ch chan protocol.ChatEventFrame) { c.mu.Lock() if set := c.subs[id]; set != nil { delete(set, ch) if len(set) == 0 { delete(c.subs, id) } } c.mu.Unlock() } // Stream exposes one thread's notifications as chat frames. func (c *Chat) Stream(ctx context.Context, id string, ready func(), emit func(protocol.ChatEventFrame) error) error { ch := c.subscribe(id) defer c.unsubscribe(id, ch) if ready != nil { ready() } for { select { case <-ctx.Done(): return ctx.Err() case frame, ok := <-ch: if !ok { return errors.New("Codex connection closed") } if err := emit(frame); err != nil { return err } } } } // Prompt starts one turn. The user turn is already broadcast by the server, so // the adapter only forwards the assistant's items. func (c *Chat) Prompt(ctx context.Context, id, text string) error { return c.PromptWithMessageID(ctx, id, text, "") } // PromptWithMessageID carries the client's native user-message id so the // optimistic browser bubble and the authoritative history item can reconcile. func (c *Chat) PromptWithMessageID(ctx context.Context, id, text, messageID string) error { if strings.TrimSpace(text) == "" { return errors.New("empty chat prompt") } params := map[string]any{ "threadId": id, "input": []any{map[string]any{"type": "text", "text": text}}, } if messageID != "" { params["clientUserMessageId"] = messageID } _, err := c.call(ctx, "turn/start", params) return err } // Permissions is empty: Codex approvals are disabled on threads this adapter // creates (approvalPolicy never), and questions arrive as requestUserInput. func (c *Chat) Permissions(context.Context, string) ([]protocol.ChatPermissionFrame, error) { return nil, nil } // Shells is empty: Codex background terminals are not exposed through the chat // surface yet. func (c *Chat) Shells(context.Context, string) ([]protocol.ChatShell, error) { return nil, nil } // Reply is unused because Codex approvals are not created for these threads. func (c *Chat) Reply(context.Context, protocol.ChatReplyRequest) error { return errors.New("Codex approvals are not enabled for this chat backend") } // ActivateSkill is an OpenCode-only chat concept. func (c *Chat) ActivateSkill(context.Context, string, string) error { return errors.New("Codex chat has no out-of-band skill activation") } // Interrupt cancels the thread's active turn. func (c *Chat) Interrupt(ctx context.Context, id string) error { c.mu.Lock() turn := c.turns[id] c.mu.Unlock() if turn == "" { return nil } _, err := c.call(ctx, "turn/interrupt", map[string]any{"threadId": id, "turnId": turn}) return err } // Create starts one Codex thread in directory. func (c *Chat) Create(ctx context.Context, title, directory string) (protocol.ChatSession, error) { if strings.TrimSpace(directory) == "" { return protocol.ChatSession{}, errors.New("a directory is required") } raw, err := c.call(ctx, "thread/start", map[string]any{ "cwd": directory, "approvalPolicy": "never", "sandbox": "workspace-write", }) if err != nil { return protocol.ChatSession{}, err } var result struct { Thread thread `json:"thread"` } if err := json.Unmarshal(raw, &result); err != nil { return protocol.ChatSession{}, err } session := result.Thread.chatSession() session.Backend = Backend if strings.TrimSpace(title) != "" { session.Title = strings.TrimSpace(title) } if title != "" { _, _ = c.call(ctx, "thread/name/set", map[string]any{"threadId": session.ID, "name": title}) } return session, nil } // Session returns one thread's current record. func (c *Chat) Session(ctx context.Context, id string) (protocol.ChatSession, bool, error) { raw, err := c.call(ctx, "thread/read", map[string]any{"threadId": id}) if err != nil { return protocol.ChatSession{}, false, err } var result struct { Thread thread `json:"thread"` } if err := json.Unmarshal(raw, &result); err != nil { return protocol.ChatSession{}, false, err } if result.Thread.ID == "" { return protocol.ChatSession{}, false, nil } session := result.Thread.chatSession() session.Backend = Backend return session, true, nil } // Sessions lists Codex threads (bounded) so the server can intersect them with // the operator registry. func (c *Chat) Sessions(ctx context.Context) ([]protocol.ChatSession, error) { raw, err := c.call(ctx, "thread/list", map[string]any{"limit": 200}) if err != nil { return nil, err } var result struct { Data []thread `json:"data"` } if err := json.Unmarshal(raw, &result); err != nil { return nil, err } sessions := make([]protocol.ChatSession, 0, len(result.Data)) for _, t := range result.Data { session := t.chatSession() session.Backend = Backend sessions = append(sessions, session) } return sessions, nil } // Messages reads a thread's turns and flattens them into chat messages. func (c *Chat) Messages(ctx context.Context, id string, limit int, cursor string) (protocol.ChatHistoryPage, error) { _ = limit _ = cursor raw, err := c.call(ctx, "thread/read", map[string]any{"threadId": id, "includeTurns": true}) if err != nil { return protocol.ChatHistoryPage{}, err } var result struct { Thread thread `json:"thread"` } if err := json.Unmarshal(raw, &result); err != nil { return protocol.ChatHistoryPage{}, err } messages := []protocol.ChatMessage{} for _, turn := range result.Thread.Turns { for _, item := range turn.Items { if msg, ok := item.chatMessage(id); ok { messages = append(messages, msg) } } } return protocol.ChatHistoryPage{Messages: messages}, nil } // Answer replies to a pending requestUserInput request. func (c *Chat) Answer(ctx context.Context, request protocol.ChatAnswerRequest) error { c.mu.Lock() pending, ok := c.forms[request.FormID] if ok { delete(c.forms, request.FormID) } c.mu.Unlock() if !ok { return errors.New("the Codex question is no longer awaiting an answer") } answers := map[string]any{} for key, value := range request.Answers { switch v := value.(type) { case []any: answers[key] = map[string]any{"answers": v} case []string: answers[key] = map[string]any{"answers": v} case string: answers[key] = map[string]any{"answers": []string{v}} default: answers[key] = map[string]any{"answers": []string{fmt.Sprint(v)}} } } c.respond(pending.requestID, map[string]any{"answers": answers}) c.emit(protocol.ChatEventFrame{ SessionID: pending.threadID, Kind: protocol.ChatEventForm, Form: &protocol.ChatForm{ID: pending.form.ID, SessionID: pending.threadID, Resolved: true}, }) return nil } func (c *Chat) handleServerRequest(msg rpcMessage) { switch msg.Method { case "item/tool/requestUserInput": var params struct { ThreadID string `json:"threadId"` TurnID string `json:"turnId"` ItemID string `json:"itemId"` Questions []struct { ID string `json:"id"` Header string `json:"header"` Question string `json:"question"` IsOther bool `json:"isOther"` IsSecret bool `json:"isSecret"` Options []struct { Value string `json:"value"` Label string `json:"label"` Description string `json:"description"` } `json:"options"` } `json:"questions"` } if err := json.Unmarshal(msg.Params, ¶ms); err != nil || params.ThreadID == "" || params.ItemID == "" { c.respond(msg.ID, map[string]any{"answers": map[string]any{}}) return } form := protocol.ChatForm{ ID: params.ItemID, SessionID: params.ThreadID, Title: "Question", Kind: "question", } for _, q := range params.Questions { field := protocol.ChatFormField{ Key: q.ID, Title: q.Question, Description: q.Header, Type: "string", Custom: q.IsOther, Required: true, } for _, option := range q.Options { value := option.Value if value == "" { value = option.Label } field.Options = append(field.Options, protocol.ChatFormOption{ Value: value, Label: option.Label, Description: option.Description, }) } form.Fields = append(form.Fields, field) } c.mu.Lock() c.forms[form.ID] = pendingForm{requestID: msg.ID, threadID: params.ThreadID, form: form} c.mu.Unlock() c.emit(protocol.ChatEventFrame{SessionID: params.ThreadID, Kind: protocol.ChatEventForm, Form: &form}) case "item/commandExecution/requestApproval", "item/fileChange/requestApproval": // The thread is created with approvalPolicy never; if a provider still asks, // deny rather than leave the turn hanging. c.respond(msg.ID, map[string]any{"decision": "deny"}) default: // Unknown server requests must not stall the shared connection. c.respond(msg.ID, map[string]any{}) } } func (c *Chat) handleNotification(msg rpcMessage) { var params struct { ThreadID string `json:"threadId"` TurnID string `json:"turnId"` ItemID string `json:"itemId"` Delta string `json:"delta"` Item json.RawMessage `json:"item"` Turn struct { ID string `json:"id"` Status string `json:"status"` } `json:"turn"` Status struct { Type string `json:"type"` } `json:"status"` } if err := json.Unmarshal(msg.Params, ¶ms); err != nil || params.ThreadID == "" { return } switch msg.Method { case "turn/started": c.mu.Lock() c.turns[params.ThreadID] = params.TurnID if c.turns[params.ThreadID] == "" { c.turns[params.ThreadID] = params.Turn.ID } c.mu.Unlock() c.emit(stepFrame(params.ThreadID, "started")) case "turn/completed": c.mu.Lock() delete(c.turns, params.ThreadID) c.mu.Unlock() c.emit(stepFrame(params.ThreadID, protocol.ChatStepEnded)) case "item/started": c.handleItem(params.ThreadID, params.ItemID, params.Item, false) case "item/completed": c.handleItem(params.ThreadID, params.ItemID, params.Item, true) case "item/agentMessage/delta", "item/agentMessage/streaming": if params.ItemID != "" && params.Delta != "" { c.markEmitted(params.ItemID) c.emit(textFrame(params.ThreadID, params.ItemID, protocol.ChatEventText, params.Delta)) } case "item/reasoning/delta": if params.ItemID != "" && params.Delta != "" { c.markEmitted(params.ItemID) c.emit(textFrame(params.ThreadID, params.ItemID, protocol.ChatEventReasoning, params.Delta)) } } } func (c *Chat) handleItem(threadID, itemID string, raw json.RawMessage, completed bool) { var item struct { ID string `json:"id"` Type string `json:"type"` Text string `json:"text"` Status string `json:"status"` Command string `json:"command"` Query string `json:"query"` Name string `json:"name"` Input any `json:"input"` Error string `json:"error"` } if err := json.Unmarshal(raw, &item); err != nil { return } if item.ID == "" { item.ID = itemID } switch item.Type { case "agentMessage": if completed && item.Text != "" && !c.wasEmitted(item.ID) { c.emit(textFrame(threadID, item.ID, protocol.ChatEventText, item.Text)) } case "reasoning": if completed && item.Text != "" && !c.wasEmitted(item.ID) { c.emit(textFrame(threadID, item.ID, protocol.ChatEventReasoning, item.Text)) } case "commandExecution", "fileChange", "mcpToolCall", "webSearch": status := protocol.ChatToolRunning if completed { if strings.EqualFold(item.Status, "failed") || item.Error != "" { status = protocol.ChatToolError } else { status = protocol.ChatToolCompleted } } name := item.Type var input any switch item.Type { case "commandExecution": name = "shell" input = map[string]any{"command": item.Command} case "webSearch": name = "websearch" input = map[string]any{"query": item.Query} default: if item.Name != "" { name = item.Name } input = item.Input } encoded, _ := json.Marshal(input) state := &protocol.ChatToolState{Status: status, Input: encoded} if item.Text != "" { state.Content = []protocol.ChatToolContent{{Type: "text", Text: item.Text}} } if item.Error != "" { state.Error = &protocol.ChatError{Message: item.Error} } c.emit(protocol.ChatEventFrame{ SessionID: threadID, MessageID: item.ID, Kind: protocol.ChatEventTool, Part: &protocol.ChatPart{Type: protocol.ChatPartTool, ID: item.ID, Name: name, State: state}, }) } } func (c *Chat) markEmitted(id string) { c.mu.Lock() c.emitted[id] = true c.mu.Unlock() } func (c *Chat) wasEmitted(id string) bool { c.mu.Lock() defer c.mu.Unlock() return c.emitted[id] } func textFrame(threadID, itemID, kind, delta string) protocol.ChatEventFrame { return protocol.ChatEventFrame{ SessionID: threadID, MessageID: itemID, Kind: kind, Delta: delta, Part: &protocol.ChatPart{Type: kind, ID: protocol.ChatDeltaPartID(itemID, kind, 0)}, } } func stepFrame(threadID, status string) protocol.ChatEventFrame { return protocol.ChatEventFrame{ SessionID: threadID, Kind: protocol.ChatEventStep, Step: &protocol.ChatStep{Status: status}, } } type thread struct { ID string `json:"id"` Name string `json:"name"` Preview string `json:"preview"` Cwd string `json:"cwd"` CreatedAt int64 `json:"createdAt"` UpdatedAt int64 `json:"updatedAt"` Turns []turn `json:"turns"` } type turn struct { Items []item `json:"items"` } type item struct { ID string `json:"id"` ClientID string `json:"clientId"` Type string `json:"type"` Text string `json:"text"` Content json.RawMessage `json:"content"` Status string `json:"status"` Command string `json:"command"` Query string `json:"query"` Name string `json:"name"` Input any `json:"input"` Error string `json:"error"` } func (t thread) chatSession() protocol.ChatSession { title := strings.TrimSpace(t.Name) if title == "" { title = strings.TrimSpace(t.Preview) } return protocol.ChatSession{ ID: t.ID, Title: title, Directory: t.Cwd, CreatedAt: t.CreatedAt * 1000, UpdatedAt: t.UpdatedAt * 1000, } } func (i item) chatMessage(sessionID string) (protocol.ChatMessage, bool) { msg := protocol.ChatMessage{ID: i.ID, SessionID: sessionID} switch i.Type { case "userMessage": msg.Role = protocol.ChatRoleUser if i.ClientID != "" { msg.ID = i.ClientID } var content []struct { Type string `json:"type"` Text string `json:"text"` } _ = json.Unmarshal(i.Content, &content) for _, part := range content { if part.Type == "text" && part.Text != "" { msg.Parts = append(msg.Parts, protocol.ChatPart{Type: protocol.ChatPartText, Text: part.Text}) } } case "agentMessage": msg.Role = protocol.ChatRoleAssistant if i.Text != "" { msg.Parts = append(msg.Parts, protocol.ChatPart{Type: protocol.ChatPartText, Text: i.Text}) } default: return protocol.ChatMessage{}, false } return msg, len(msg.Parts) > 0 }