From fd4c329eafc46d1ce32dc9bc36fd9bd09b34e058 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 17:10:44 +0100 Subject: [PATCH 1/4] WIP: preserve background task output API --- docs/notes/background-task-output-api.md | 13 ++++ internal/opencode/chat.go | 47 +++++++++++++++ internal/opencode/chat_v2_test.go | 25 ++++++++ internal/protocol/chat.go | 24 ++++++++ internal/protocol/message.go | 5 +- internal/server/chat.go | 10 ++++ internal/server/chat_shell_output.go | 76 ++++++++++++++++++++++++ 7 files changed, 199 insertions(+), 1 deletion(-) create mode 100644 docs/notes/background-task-output-api.md create mode 100644 internal/server/chat_shell_output.go diff --git a/docs/notes/background-task-output-api.md b/docs/notes/background-task-output-api.md new file mode 100644 index 00000000..5ecf6a58 --- /dev/null +++ b/docs/notes/background-task-output-api.md @@ -0,0 +1,13 @@ +# Background task output API + +Changed: 2026-10-18. The chat websocket now has `chat_shells` for current, +operator-session-owned running shells and `chat_shell_output` for a selected, +bounded (64 KiB) absolute-byte output page. Ownership requires both the +operator-session registry and provider shell metadata `sessionID`; a shared cwd +is not evidence. Output reads first verify provider detail and explicitly mark +removed/provider-unavailable shells unavailable. This is not completed-task +history or restart retention. + +Stale shared documentation: the packaged OpenCode operational references under +`internal/author/skill/references/` need a later docs-fold update describing the +two additive websocket messages, 64 KiB maximum page, and current-only history. diff --git a/internal/opencode/chat.go b/internal/opencode/chat.go index 8be73857..a7ea7f77 100644 --- a/internal/opencode/chat.go +++ b/internal/opencode/chat.go @@ -418,6 +418,52 @@ func (c *Chat) Shells(ctx context.Context, sessionID string) ([]protocol.ChatShe return out, nil } +// ShellOutput validates explicit session metadata from the authoritative detail +// record before reading the selected bounded output page. A shared directory is +// never ownership evidence. +func (c *Chat) ShellOutput(ctx context.Context, query protocol.ChatShellOutputQuery) (protocol.ChatShellOutputPage, error) { + if !ValidSessionID(query.SessionID) || len(query.ShellID) <= 3 || !strings.HasPrefix(query.ShellID, "sh_") || query.Cursor < 0 || query.Limit < 0 || query.Limit > 64<<10 { + return protocol.ChatShellOutputPage{}, fmt.Errorf("invalid shell output query") + } + data, err := c.call(ctx, "get", "/api/shell/"+query.ShellID, nil) + if err != nil { + if c.conn.LastHTTPStatus == 404 { + return protocol.ChatShellOutputPage{Unavailable: true}, nil + } + return protocol.ChatShellOutputPage{}, err + } + var detail struct { + Data chatShellInfo `json:"data"` + } + if err := json.Unmarshal(data, &detail); err != nil || detail.Data.ID != query.ShellID || detail.Data.shellSessionID() != query.SessionID { + return protocol.ChatShellOutputPage{}, fmt.Errorf("shell is not available for this session") + } + shell := protocol.ChatShell{ID: detail.Data.ID, Status: detail.Data.Status, Command: detail.Data.Command, Exit: detail.Data.Exit} + if shell.Status == "" { + shell.Status = protocol.ChatShellRunning + } + path := fmt.Sprintf("/api/shell/%s/output?cursor=%d&limit=%d", query.ShellID, query.Cursor, query.Limit) + data, err = c.call(ctx, "get", path, nil) + if err != nil { + if c.conn.LastHTTPStatus == 404 { + return protocol.ChatShellOutputPage{Shell: shell, Unavailable: true}, nil + } + return protocol.ChatShellOutputPage{}, err + } + var response struct { + Data struct { + Output string `json:"output"` + Cursor int64 `json:"cursor"` + Size int64 `json:"size"` + Truncated bool `json:"truncated"` + } `json:"data"` + } + if err := json.Unmarshal(data, &response); err != nil || len(response.Data.Output) > 64<<10 || response.Data.Cursor < query.Cursor || response.Data.Size < response.Data.Cursor { + return protocol.ChatShellOutputPage{}, fmt.Errorf("invalid OpenCode shell output response") + } + return protocol.ChatShellOutputPage{Shell: shell, Output: response.Data.Output, Cursor: response.Data.Cursor, Size: response.Data.Size, Truncated: response.Data.Truncated}, nil +} + // streamState returns the session's retained, verified shell identities. It is // deliberately kept across stream replacement so an exit after reconnect remains // attributable; Shells reconciles its contents from authoritative readback on @@ -592,6 +638,7 @@ type chatShellInfo struct { ID string `json:"id"` Status string `json:"status"` Command string `json:"command"` + Exit *int `json:"exit"` Metadata map[string]any `json:"metadata"` } diff --git a/internal/opencode/chat_v2_test.go b/internal/opencode/chat_v2_test.go index fd00dbae..afb4608c 100644 --- a/internal/opencode/chat_v2_test.go +++ b/internal/opencode/chat_v2_test.go @@ -7,6 +7,7 @@ import ( "net/http" "net/http/httptest" "path/filepath" + "strings" "testing" "time" @@ -425,6 +426,30 @@ func TestChatShellReadbackSeedsReplacementStream(t *testing.T) { } } +func TestChatShellOutputVerifiesOwnerAndBoundsPage(t *testing.T) { + var outputPath string + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + switch r.URL.Path { + case "/api/shell/sh_1": + _, _ = w.Write([]byte(`{"data":{"id":"sh_1","status":"exited","command":"job","metadata":{"sessionID":"ses_1"}}}`)) + case "/api/shell/sh_1/output": + outputPath = r.URL.RawQuery + _, _ = w.Write([]byte(`{"data":{"output":"marker","cursor":6,"size":6,"truncated":false}}`)) + default: + http.NotFound(w, r) + } + })) + defer srv.Close() + page, err := NewChat(&Connection{Backend: "v2", URL: srv.URL}).ShellOutput(context.Background(), protocol.ChatShellOutputQuery{SessionID: "ses_1", ShellID: "sh_1", Limit: 64 << 10}) + if err != nil || page.Output != "marker" || page.Shell.Status != protocol.ChatShellExited { + t.Fatalf("ShellOutput = %+v, %v", page, err) + } + if !strings.Contains(outputPath, "cursor=0") || !strings.Contains(outputPath, "limit=65536") { + t.Fatalf("output query = %q", outputPath) + } +} + func TestChatReleaseShellsBoundsDisconnectedState(t *testing.T) { chat := NewChat(&Connection{}) state := chat.streamState("ses_1") diff --git a/internal/protocol/chat.go b/internal/protocol/chat.go index 2355560f..23406530 100644 --- a/internal/protocol/chat.go +++ b/internal/protocol/chat.go @@ -54,6 +54,10 @@ const ( // load the choices without first listing sessions and chat_sessions stays a // pure, fail-closed operator-session list. ChatDirectories = "chat_directories" + // ChatShells lists current, verified shells belonging to one operator chat + // session. ChatShellOutput reads a bounded page from one such shell. + ChatShells = "chat_shells" + ChatShellOutput = "chat_shell_output" // ChatEvent and ChatPermission are the server-pushed frames; they are the // only types the server sends without a matching request. ChatEvent = "chat_event" @@ -360,6 +364,26 @@ type ChatShell struct { Exit *int `json:"exit,omitempty"` } +// ChatShellOutputQuery names one selected shell and a bounded absolute-byte +// output page. Cursor is decimal so it can be passed directly to OpenCode. +type ChatShellOutputQuery struct { + SessionID string `json:"session_id"` + ShellID string `json:"shell_id"` + Cursor int64 `json:"cursor,omitempty"` + Limit int `json:"limit,omitempty"` +} + +// ChatShellOutputPage is a bounded, lazy output read. Unavailable is explicit when +// an exited shell is no longer directly verifiable upstream. +type ChatShellOutputPage struct { + Shell ChatShell `json:"shell"` + Output string `json:"output,omitempty"` + Cursor int64 `json:"cursor,omitempty"` + Size int64 `json:"size,omitempty"` + Truncated bool `json:"truncated,omitempty"` + Unavailable bool `json:"unavailable,omitempty"` +} + // ChatPermissionFrame is the server-pushed chat_permission payload: one pending // OpenCode permission request the phone must approve or reject. It is a distinct // Message field (like ChatEvent) rather than a ChatEvent.Kind, so it does not diff --git a/internal/protocol/message.go b/internal/protocol/message.go index 1fbaa296..d688a50f 100644 --- a/internal/protocol/message.go +++ b/internal/protocol/message.go @@ -187,7 +187,10 @@ type Message struct { // chat_directories response (home first, then recent operator-session // directories, deduplicated and bounded). Additive/omitempty so older peers // ignore it. - ChatDirectories []string `json:"chat_directories,omitempty"` + ChatDirectories []string `json:"chat_directories,omitempty"` + ChatShellOutputQuery *ChatShellOutputQuery `json:"chat_shell_output_query,omitempty"` + ChatShells []ChatShell `json:"chat_shells,omitempty"` + ChatShellOutput *ChatShellOutputPage `json:"chat_shell_output,omitempty"` // RunEvent is the server-pushed run state delta (see runevents.go) and // RunIDs the optional subscribe scope, so a client asks for the runs it // displays. Both are optional so older peers ignore them. diff --git a/internal/server/chat.go b/internal/server/chat.go index ab03ef05..3d4ddf5c 100644 --- a/internal/server/chat.go +++ b/internal/server/chat.go @@ -42,6 +42,10 @@ type chatBroker interface { Reply(ctx context.Context, request protocol.ChatReplyRequest) error } +type chatShellOutputReader interface { + ShellOutput(ctx context.Context, query protocol.ChatShellOutputQuery) (protocol.ChatShellOutputPage, error) +} + // chatShellReleaser is implemented by brokers that retain verified shell ids for // attributing exit events. The hub calls it only after the last observer leaves // a room; a later attach obtains a fresh authoritative snapshot. @@ -128,6 +132,12 @@ func handleChat(ctx context.Context, request protocol.Message, broker chatBroker case protocol.ChatReopen: handleChatReopen(ctx, request, registry, write) return true + case protocol.ChatShells: + handleChatShells(ctx, request, broker, registry, write) + return true + case protocol.ChatShellOutput: + handleChatShellOutput(ctx, request, broker, registry, write) + return true } return false } diff --git a/internal/server/chat_shell_output.go b/internal/server/chat_shell_output.go new file mode 100644 index 00000000..41913db2 --- /dev/null +++ b/internal/server/chat_shell_output.go @@ -0,0 +1,76 @@ +package server + +import ( + "context" + "fmt" + + "git.a-wan.net/alan/pipelines/internal/opencode" + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +const chatShellOutputLimit = 64 << 10 + +func operatorChatSession(ctx context.Context, registry operatorRegistry, id string) error { + if registry == nil { + return fmt.Errorf("operator session registry is not configured on this server") + } + _, found, err := registry.OperatorSession(ctx, id) + if err != nil { + return err + } + if !found { + return fmt.Errorf("operator session is not available") + } + return nil +} + +func handleChatShells(ctx context.Context, request protocol.Message, broker chatBroker, registry operatorRegistry, write func(protocol.Message) error) { + query := request.ChatQuery + if broker == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat is not configured on this server"}) + return + } + if query == nil || !opencode.ValidSessionID(query.SessionID) { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "a valid OpenCode session id is required"}) + return + } + if err := operatorChatSession(ctx, registry, query.SessionID); err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return + } + shells, err := broker.Shells(ctx, query.SessionID) + if err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return + } + _ = write(protocol.Message{Type: protocol.ChatShells, ID: request.ID, ChatShells: shells}) +} + +func handleChatShellOutput(ctx context.Context, request protocol.Message, broker chatBroker, registry operatorRegistry, write func(protocol.Message) error) { + query := request.ChatShellOutputQuery + if broker == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat is not configured on this server"}) + return + } + if query == nil || !opencode.ValidSessionID(query.SessionID) || !validShellID(query.ShellID) || query.Cursor < 0 || query.Limit < 0 || query.Limit > chatShellOutputLimit { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "a valid bounded shell output query is required"}) + return + } + if err := operatorChatSession(ctx, registry, query.SessionID); err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return + } + reader, ok := broker.(chatShellOutputReader) + if !ok { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "shell output is not configured on this server"}) + return + } + output, err := reader.ShellOutput(ctx, *query) + if err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return + } + _ = write(protocol.Message{Type: protocol.ChatShellOutput, ID: request.ID, ChatShellOutput: &output}) +} + +func validShellID(id string) bool { return len(id) > 3 && len(id) <= 128 && id[:3] == "sh_" } From ded79277783b6ccdc25eb4ea25fe55d8632b89c7 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 17:42:15 +0100 Subject: [PATCH 2/4] WIP: preserve remaining background task output work --- .../pipelines/data/PipelinesRepository.kt | 18 +++++++ .../net/awan/pipelines/data/protocol/Chat.kt | 28 +++++++++++ .../awan/pipelines/data/protocol/Message.kt | 5 ++ .../data/protocol/ChatProtocolTest.kt | 30 ++++++++++++ cmd/pipelines-large-chat-fixture/main.go | 35 +++++++++++++- docs/notes/background-task-output-api.md | 11 +++++ internal/opencode/chat.go | 35 ++++++++++---- internal/opencode/chat_v2_test.go | 27 +++++++++++ internal/protocol/chat.go | 6 ++- internal/server/chat_shell_output.go | 8 ++-- internal/server/chat_shell_output_test.go | 47 +++++++++++++++++++ internal/server/large_chat_fixture.go | 36 ++++++++++++++ 12 files changed, 269 insertions(+), 17 deletions(-) create mode 100644 internal/server/chat_shell_output_test.go diff --git a/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt b/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt index bb59e9e5..57c6db98 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt @@ -13,6 +13,8 @@ import net.awan.pipelines.data.protocol.ChatPromptRequest import net.awan.pipelines.data.protocol.ChatProtocol import net.awan.pipelines.data.protocol.ChatQuery import net.awan.pipelines.data.protocol.ChatSession +import net.awan.pipelines.data.protocol.ChatShellOutputPage +import net.awan.pipelines.data.protocol.ChatShell import net.awan.pipelines.data.protocol.Message import net.awan.pipelines.data.protocol.Graph import net.awan.pipelines.data.protocol.PipelineDetail @@ -312,6 +314,22 @@ class PipelinesRepository( return response.chatHistory ?: ChatHistoryPage(messages = response.chatMessages ?: emptyList()) } + /** Reads one bounded page from a verified, currently observable shell. */ + suspend fun chatShellOutput(sessionId: String, shellId: String, cursor: Long = 0, limit: Int = ChatProtocol.SHELL_OUTPUT_LIMIT): ChatShellOutputPage { + if (sessionId.isBlank() || shellId.isBlank()) throw ProtocolException("Select a shell first.") + if (cursor < 0 || limit <= 0 || limit > ChatProtocol.SHELL_OUTPUT_LIMIT) { + throw ProtocolException("Shell output bounds are invalid.") + } + return client.call(ChatProtocol.shellOutputRequest(sessionId, shellId, cursor, limit)).chatShellOutput + ?: throw ProtocolException("The server returned no shell output page.") + } + + /** Lists currently observed shells owned by this operator chat session. */ + suspend fun chatShells(sessionId: String): List { + if (sessionId.isBlank()) throw ProtocolException("Select a chat session first.") + return client.call(ChatProtocol.shellsRequest(sessionId)).chatShells ?: emptyList() + } + /** * Attaches this connection to [sessionId]'s shared live stream, so it sees * every frame any client's turn produces — the other devices' prompts and the diff --git a/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt b/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt index d76fc86c..47e3fcfd 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt @@ -201,6 +201,24 @@ data class ChatShell( val exit: Int? = null, ) +@Serializable +data class ChatShellOutputQuery( + @SerialName("session_id") val sessionId: String = "", + @SerialName("shell_id") val shellId: String = "", + val cursor: Long = 0, + val limit: Int = ChatProtocol.SHELL_OUTPUT_LIMIT, +) + +@Serializable +data class ChatShellOutputPage( + val shell: ChatShell = ChatShell(), + val output: String = "", + val cursor: Long = 0, + val size: Long = 0, + val truncated: Boolean = false, + val unavailable: Boolean = false, +) + @Serializable data class ChatStep( val status: String = "", @@ -282,6 +300,7 @@ object ChatProtocol { const val SHELL_RUNNING = "running" const val SHELL_EXITED = "exited" + const val SHELL_OUTPUT_LIMIT = 64 * 1024 /** * A prompt another client sent, echoed live to this client so it appears in @@ -359,6 +378,15 @@ object ChatProtocol { fun interruptRequest(sessionId: String): Message = Message(type = Protocol.CHAT_INTERRUPT, chatQuery = ChatQuery(sessionId = sessionId)) + fun shellOutputRequest(sessionId: String, shellId: String, cursor: Long = 0, limit: Int = SHELL_OUTPUT_LIMIT): Message = + Message( + type = Protocol.CHAT_SHELL_OUTPUT, + chatShellOutputQuery = ChatShellOutputQuery(sessionId, shellId, cursor, limit), + ) + + fun shellsRequest(sessionId: String): Message = + Message(type = Protocol.CHAT_SHELLS, chatQuery = ChatQuery(sessionId = sessionId)) + /** * The `chat_close` frame that finishes [sessionId]: the server stops any * running turn (through the same interrupt) and records the session closed on diff --git a/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt b/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt index b9845ea7..7014e6d3 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt @@ -79,6 +79,8 @@ object Protocol { // The operator's directory choices for a new chat (home first, then the // directories of previous operator sessions, most recently used first). const val CHAT_DIRECTORIES = "chat_directories" + const val CHAT_SHELLS = "chat_shells" + const val CHAT_SHELL_OUTPUT = "chat_shell_output" // Server-pushed frames with no matching request. const val CHAT_EVENT = "chat_event" const val CHAT_PERMISSION = "chat_permission" @@ -712,4 +714,7 @@ data class Message( // close/reopen requests themselves ride on chat_query like chat_interrupt. @SerialName("chat_close") val chatClose: ChatCloseResult? = null, @SerialName("chat_directories") val chatDirectories: List? = null, + @SerialName("chat_shell_output_query") val chatShellOutputQuery: ChatShellOutputQuery? = null, + @SerialName("chat_shells") val chatShells: List? = null, + @SerialName("chat_shell_output") val chatShellOutput: ChatShellOutputPage? = null, ) diff --git a/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt b/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt index ca5412c8..fa170210 100644 --- a/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt @@ -405,6 +405,36 @@ class ChatProtocolTest { assertEquals(1792112367999L, decodedReply.chatClose!!.closedAt) } + @Test + fun shellOutputRequestAndPageUseBoundedWireNames() { + val request = ChatProtocol.shellOutputRequest("ses_1", "sh_1", 7, 128) + val decoded = PipelinesJson.decodeFromString(Message.serializer(), PipelinesJson.encodeToString(Message.serializer(), request)) + assertEquals(Protocol.CHAT_SHELL_OUTPUT, decoded.type) + assertEquals("ses_1", decoded.chatShellOutputQuery!!.sessionId) + assertEquals("sh_1", decoded.chatShellOutputQuery!!.shellId) + assertEquals(7L, decoded.chatShellOutputQuery!!.cursor) + assertEquals(128, decoded.chatShellOutputQuery!!.limit) + + val page = PipelinesJson.decodeFromString(Message.serializer(), """ + {"type":"chat_shell_output","chat_shell_output":{"shell":{"id":"sh_1","status":"running"},"output":"marker","cursor":13,"size":20,"truncated":true}} + """.trimIndent()) + assertEquals("marker", page.chatShellOutput!!.output) + assertTrue(page.chatShellOutput!!.truncated) + } + + @Test + fun shellsRequestUsesSessionQueryAndPreservesListWireName() { + val request = ChatProtocol.shellsRequest("ses_1") + val decoded = PipelinesJson.decodeFromString(Message.serializer(), PipelinesJson.encodeToString(Message.serializer(), request)) + assertEquals(Protocol.CHAT_SHELLS, decoded.type) + assertEquals("ses_1", decoded.chatQuery!!.sessionId) + val reply = PipelinesJson.decodeFromString(Message.serializer(), """ + {"type":"chat_shells","chat_shells":[{"id":"sh_1","status":"running","command":"printf marker"}]} + """.trimIndent()) + assertEquals("sh_1", reply.chatShells!!.single().id) + assertEquals(ChatProtocol.SHELL_RUNNING, reply.chatShells.single().status) + } + private fun toolDuration(part: ChatPart): Long? { val time = part.time ?: return null return time.completed - time.ran diff --git a/cmd/pipelines-large-chat-fixture/main.go b/cmd/pipelines-large-chat-fixture/main.go index d0e4ee73..e486fc17 100644 --- a/cmd/pipelines-large-chat-fixture/main.go +++ b/cmd/pipelines-large-chat-fixture/main.go @@ -29,6 +29,7 @@ import ( func main() { addr := flag.String("addr", "127.0.0.1:0", "Pipelines scratch listen address") scratch := flag.String("scratch-dir", "", "required scratch directory for the database and workspace") + exited := flag.Bool("shell-exited", false, "serve the selected fixture shell as observed exited") flag.Parse() if *scratch == "" { fatal(fmt.Errorf("-scratch-dir is required")) @@ -46,7 +47,7 @@ func main() { } defer upstream.Close() upstreamURL := "http://" + upstream.Addr().String() - upstreamServer := &http.Server{Handler: server.LargeChatFixtureHandler(workspace), ReadHeaderTimeout: 5 * time.Second} + upstreamServer := &http.Server{Handler: server.LargeChatFixtureHandlerWithShell(workspace, *exited), ReadHeaderTimeout: 5 * time.Second} go func() { _ = upstreamServer.Serve(upstream) }() ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) @@ -76,6 +77,9 @@ func main() { if err != nil { fatal(err) } + if err := verifyShellReadback(ctx, endpoint, *exited); err != nil { + fatal(err) + } info := buildinfo.Current() _ = json.NewEncoder(os.Stdout).Encode(map[string]any{ "endpoint": endpoint, "upstream_endpoint": upstreamURL, "backend": attached.Connection.Backend, @@ -89,6 +93,35 @@ func main() { _ = upstreamServer.Shutdown(shutdown) } +func verifyShellReadback(ctx context.Context, endpoint string, exited bool) error { + ws, _, err := websocket.Dial(ctx, "ws"+strings.TrimPrefix(endpoint, "http")+"/connect", nil) + if err != nil { + return err + } + defer ws.Close(websocket.StatusNormalClosure, "fixture complete") + if err := wsjson.Write(ctx, ws, protocol.Message{Type: protocol.ChatShells, ID: "fixture-shells", ChatQuery: &protocol.ChatQuery{SessionID: server.LargeChatFixtureSessionID}}); err != nil { + return err + } + var listed protocol.Message + if listed, err = readFixtureResponse(ctx, ws, protocol.ChatShells); err != nil { + return err + } + if !exited && (len(listed.ChatShells) != 1 || listed.ChatShells[0].ID != server.LargeChatFixtureShellID) { + return fmt.Errorf("fixture shell is not listed") + } + if err := wsjson.Write(ctx, ws, protocol.Message{Type: protocol.ChatShellOutput, ID: "fixture-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: server.LargeChatFixtureSessionID, ShellID: server.LargeChatFixtureShellID, Limit: 64 << 10}}); err != nil { + return err + } + page, err := readFixtureResponse(ctx, ws, protocol.ChatShellOutput) + if err != nil { + return err + } + if page.ChatShellOutput == nil || page.ChatShellOutput.Output != server.LargeChatFixtureShellOutput || page.ChatShellOutput.Shell.Status != map[bool]string{true: "exited", false: "running"}[exited] { + return fmt.Errorf("unexpected shell readback: %+v", page.ChatShellOutput) + } + return nil +} + func verifyBroker(ctx context.Context, endpoint string) ([2]map[string]any, error) { var readbacks [2]map[string]any cursor := "" diff --git a/docs/notes/background-task-output-api.md b/docs/notes/background-task-output-api.md index 5ecf6a58..13cddebd 100644 --- a/docs/notes/background-task-output-api.md +++ b/docs/notes/background-task-output-api.md @@ -11,3 +11,14 @@ history or restart retention. Stale shared documentation: the packaged OpenCode operational references under `internal/author/skill/references/` need a later docs-fold update describing the two additive websocket messages, 64 KiB maximum page, and current-only history. + +Fixture evidence (2026-10-18): `go build -o /tmp/pipelines-large-chat-fixture-stage +./cmd/pipelines-large-chat-fixture`; then `/tmp/pipelines-large-chat-fixture-stage +-scratch-dir /var/folders/jp/q0qvjyg54fl_c5vhhk1ylz2m0000gn/T/pipelines-shell-fixture-pxnc95h2 +-shell-exited`, stopped with SIGTERM. The foreground run exercised authenticated +`chat_sessions`, three reconnecting history pages, `chat_shells`, and bounded +`chat_shell_output` readback against scratch DB/workspace only, and exited 0 after +clean shutdown. Recorded revision `fd4c329eafc46d1ce32dc9bc36fd9bd09b34e058`, +session `ses_large_chat_fixture`, shell `sh_large_chat_fixture`, and fixed marker +`fixture shell output marker\n`. The selected exited shell is read directly by id; +the current list remains running-shell discovery. diff --git a/internal/opencode/chat.go b/internal/opencode/chat.go index a7ea7f77..379a1ce7 100644 --- a/internal/opencode/chat.go +++ b/internal/opencode/chat.go @@ -50,6 +50,21 @@ func NewChat(conn *Connection) *Chat { return &Chat{conn: conn} } // chat adapter and callers that must reject a request before any OpenCode call. func ValidSessionID(id string) bool { return sessionID.MatchString(id) } +// ValidShellID accepts only the provider's opaque shell-id alphabet. Keeping +// this check shared by the websocket boundary and provider adapter ensures an +// invalid id is rejected before either network call or path construction. +func ValidShellID(id string) bool { + if len(id) <= 3 || len(id) > 128 || !strings.HasPrefix(id, "sh_") { + return false + } + for _, c := range id[3:] { + if (c < 'a' || c > 'z') && (c < 'A' || c > 'Z') && (c < '0' || c > '9') && c != '_' && c != '-' { + return false + } + } + return true +} + // call serializes the adapter's HTTP calls and forwards them through the shared // Connection, so no second transport is introduced and Connection's recorded // last operation/status is never written by two goroutines at once. @@ -392,7 +407,7 @@ func (c *Chat) Shells(ctx context.Context, sessionID string) ([]protocol.ChatShe } out := make([]protocol.ChatShell, 0, len(response.Data)) for _, info := range response.Data { - if info.ID == "" || info.shellSessionID() != sessionID || (info.Status != "" && info.Status != protocol.ChatShellRunning) { + if info.ID == "" || info.shellSessionID() != sessionID || (info.Status != "" && info.Status != protocol.ChatShellRunning && info.Status != protocol.ChatShellExited) { continue } status := info.Status @@ -422,7 +437,7 @@ func (c *Chat) Shells(ctx context.Context, sessionID string) ([]protocol.ChatShe // record before reading the selected bounded output page. A shared directory is // never ownership evidence. func (c *Chat) ShellOutput(ctx context.Context, query protocol.ChatShellOutputQuery) (protocol.ChatShellOutputPage, error) { - if !ValidSessionID(query.SessionID) || len(query.ShellID) <= 3 || !strings.HasPrefix(query.ShellID, "sh_") || query.Cursor < 0 || query.Limit < 0 || query.Limit > 64<<10 { + if !ValidSessionID(query.SessionID) || !ValidShellID(query.ShellID) || query.Cursor < 0 || query.Cursor > protocol.ChatShellOutputMaxCursor || query.Limit <= 0 || query.Limit > protocol.ChatShellOutputLimit { return protocol.ChatShellOutputPage{}, fmt.Errorf("invalid shell output query") } data, err := c.call(ctx, "get", "/api/shell/"+query.ShellID, nil) @@ -435,7 +450,7 @@ func (c *Chat) ShellOutput(ctx context.Context, query protocol.ChatShellOutputQu var detail struct { Data chatShellInfo `json:"data"` } - if err := json.Unmarshal(data, &detail); err != nil || detail.Data.ID != query.ShellID || detail.Data.shellSessionID() != query.SessionID { + if err := json.Unmarshal(data, &detail); err != nil || detail.Data.ID != query.ShellID || detail.Data.shellSessionID() != query.SessionID || (detail.Data.Status != "" && detail.Data.Status != protocol.ChatShellRunning && detail.Data.Status != protocol.ChatShellExited) { return protocol.ChatShellOutputPage{}, fmt.Errorf("shell is not available for this session") } shell := protocol.ChatShell{ID: detail.Data.ID, Status: detail.Data.Status, Command: detail.Data.Command, Exit: detail.Data.Exit} @@ -451,17 +466,17 @@ func (c *Chat) ShellOutput(ctx context.Context, query protocol.ChatShellOutputQu return protocol.ChatShellOutputPage{}, err } var response struct { - Data struct { - Output string `json:"output"` - Cursor int64 `json:"cursor"` - Size int64 `json:"size"` - Truncated bool `json:"truncated"` + Data *struct { + Output *string `json:"output"` + Cursor *int64 `json:"cursor"` + Size *int64 `json:"size"` + Truncated *bool `json:"truncated"` } `json:"data"` } - if err := json.Unmarshal(data, &response); err != nil || len(response.Data.Output) > 64<<10 || response.Data.Cursor < query.Cursor || response.Data.Size < response.Data.Cursor { + if err := json.Unmarshal(data, &response); err != nil || response.Data == nil || response.Data.Output == nil || response.Data.Cursor == nil || response.Data.Size == nil || response.Data.Truncated == nil || len(*response.Data.Output) > query.Limit || *response.Data.Cursor < query.Cursor || *response.Data.Cursor > protocol.ChatShellOutputMaxCursor || *response.Data.Size < *response.Data.Cursor || *response.Data.Size > protocol.ChatShellOutputMaxCursor || *response.Data.Cursor-query.Cursor != int64(len(*response.Data.Output)) { return protocol.ChatShellOutputPage{}, fmt.Errorf("invalid OpenCode shell output response") } - return protocol.ChatShellOutputPage{Shell: shell, Output: response.Data.Output, Cursor: response.Data.Cursor, Size: response.Data.Size, Truncated: response.Data.Truncated}, nil + return protocol.ChatShellOutputPage{Shell: shell, Output: *response.Data.Output, Cursor: *response.Data.Cursor, Size: *response.Data.Size, Truncated: *response.Data.Truncated}, nil } // streamState returns the session's retained, verified shell identities. It is diff --git a/internal/opencode/chat_v2_test.go b/internal/opencode/chat_v2_test.go index afb4608c..dfcb3973 100644 --- a/internal/opencode/chat_v2_test.go +++ b/internal/opencode/chat_v2_test.go @@ -450,6 +450,33 @@ func TestChatShellOutputVerifiesOwnerAndBoundsPage(t *testing.T) { } } +func TestChatShellOutputRejectsMissingRequiredPageFields(t *testing.T) { + for _, body := range []string{ + `{"data":{}}`, + `{"data":{"output":"","cursor":0,"size":0}}`, + `{"data":{"output":"","size":0,"truncated":false}}`, + `{"data":{"output":"","cursor":0,"truncated":false}}`, + } { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + switch r.URL.Path { + case "/api/shell/sh_1": + _, _ = w.Write([]byte(`{"data":{"id":"sh_1","status":"running","metadata":{"sessionID":"ses_1"}}}`)) + case "/api/shell/sh_1/output": + _, _ = w.Write([]byte(body)) + default: + http.NotFound(w, r) + } + })) + chat := NewChat(&Connection{Backend: "v2", URL: srv.URL}) + _, err := chat.ShellOutput(context.Background(), protocol.ChatShellOutputQuery{SessionID: "ses_1", ShellID: "sh_1", Limit: 1}) + srv.Close() + if err == nil { + t.Fatalf("response %s was accepted", body) + } + } +} + func TestChatReleaseShellsBoundsDisconnectedState(t *testing.T) { chat := NewChat(&Connection{}) state := chat.streamState("ses_1") diff --git a/internal/protocol/chat.go b/internal/protocol/chat.go index 23406530..755c8dae 100644 --- a/internal/protocol/chat.go +++ b/internal/protocol/chat.go @@ -93,8 +93,10 @@ const ( // ChatShell.Status values, mirroring the OpenCode shell events. A running shell // is one whose command has started and not yet exited; exited is final. const ( - ChatShellRunning = "running" - ChatShellExited = "exited" + ChatShellRunning = "running" + ChatShellExited = "exited" + ChatShellOutputLimit = 64 << 10 + ChatShellOutputMaxCursor = int64(1 << 62) ) // ChatStep.Status values, mirroring the OpenCode session.step events. diff --git a/internal/server/chat_shell_output.go b/internal/server/chat_shell_output.go index 41913db2..bc4d5c09 100644 --- a/internal/server/chat_shell_output.go +++ b/internal/server/chat_shell_output.go @@ -8,8 +8,6 @@ import ( "git.a-wan.net/alan/pipelines/internal/protocol" ) -const chatShellOutputLimit = 64 << 10 - func operatorChatSession(ctx context.Context, registry operatorRegistry, id string) error { if registry == nil { return fmt.Errorf("operator session registry is not configured on this server") @@ -52,7 +50,7 @@ func handleChatShellOutput(ctx context.Context, request protocol.Message, broker _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat is not configured on this server"}) return } - if query == nil || !opencode.ValidSessionID(query.SessionID) || !validShellID(query.ShellID) || query.Cursor < 0 || query.Limit < 0 || query.Limit > chatShellOutputLimit { + if query == nil || !opencode.ValidSessionID(query.SessionID) || !validShellID(query.ShellID) || query.Cursor < 0 || query.Cursor > protocol.ChatShellOutputMaxCursor || query.Limit <= 0 || query.Limit > protocol.ChatShellOutputLimit { _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "a valid bounded shell output query is required"}) return } @@ -73,4 +71,6 @@ func handleChatShellOutput(ctx context.Context, request protocol.Message, broker _ = write(protocol.Message{Type: protocol.ChatShellOutput, ID: request.ID, ChatShellOutput: &output}) } -func validShellID(id string) bool { return len(id) > 3 && len(id) <= 128 && id[:3] == "sh_" } +func validShellID(id string) bool { + return opencode.ValidShellID(id) +} diff --git a/internal/server/chat_shell_output_test.go b/internal/server/chat_shell_output_test.go new file mode 100644 index 00000000..43b6c766 --- /dev/null +++ b/internal/server/chat_shell_output_test.go @@ -0,0 +1,47 @@ +package server + +import ( + "context" + "testing" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +type shellOutputTestBroker struct { + *fakeChat + outputCalls int +} + +func (b *shellOutputTestBroker) ShellOutput(context.Context, protocol.ChatShellOutputQuery) (protocol.ChatShellOutputPage, error) { + b.outputCalls++ + return protocol.ChatShellOutputPage{Output: "unexpected"}, nil +} + +func TestChatShellOutputRejectsBoundsBeforeRegistryOrProvider(t *testing.T) { + store := newOperatorStore(t) + broker := &shellOutputTestBroker{fakeChat: scriptedChat()} + queries := []protocol.ChatShellOutputQuery{ + {SessionID: "ses_1", ShellID: "sh_1", Limit: 0}, + {SessionID: "ses_1", ShellID: "sh_1", Limit: -1}, + {SessionID: "ses_1", ShellID: "sh_1", Cursor: protocol.ChatShellOutputMaxCursor + 1, Limit: 1}, + {SessionID: "ses_1", ShellID: "sh_1/../x", Limit: 1}, + {SessionID: "ses_1", ShellID: "sh_1%2f", Limit: 1}, + {SessionID: "ses_1", ShellID: "sh_1?cursor=0", Limit: 1}, + {SessionID: "ses_1", ShellID: "sh_1#fragment", Limit: 1}, + {SessionID: "ses_1", ShellID: "sh_%ZZ", Limit: 1}, + {SessionID: "ses_1", ShellID: "sh_" + string(make([]byte, 126)), Limit: 1}, + } + for _, query := range queries { + var response protocol.Message + handleChatShellOutput(context.Background(), protocol.Message{ChatShellOutputQuery: &query}, broker, store, func(m protocol.Message) error { + response = m + return nil + }) + if response.Type != protocol.Error { + t.Fatalf("query %+v response = %+v", query, response) + } + } + if broker.outputCalls != 0 { + t.Fatalf("invalid queries reached provider %d times", broker.outputCalls) + } +} diff --git a/internal/server/large_chat_fixture.go b/internal/server/large_chat_fixture.go index 12062dd5..a43ab273 100644 --- a/internal/server/large_chat_fixture.go +++ b/internal/server/large_chat_fixture.go @@ -13,6 +13,8 @@ const LargeChatFixtureSessionID = "ses_large_chat_fixture" // LargeChatFixturePassword authenticates the disposable fixture endpoint. It is // fixed fixture data, not an operator credential. const LargeChatFixturePassword = "large-chat-fixture" +const LargeChatFixtureShellID = "sh_large_chat_fixture" +const LargeChatFixtureShellOutput = "fixture shell output marker\n" const ( LargeChatFixtureNewestAnswer = "Controlled newest answer: large history fixture" @@ -24,6 +26,13 @@ const ( // It deliberately serves fixed, paged data: no model is invoked and no production // history is read or written. func LargeChatFixtureHandler(workspace string) http.Handler { + return LargeChatFixtureHandlerWithShell(workspace, false) +} + +// LargeChatFixtureHandlerWithShell is the foreground fixture surface used by +// the readback check. exited selects the provider's observed terminal state; +// the output remains fixed and bounded in either state. +func LargeChatFixtureHandlerWithShell(workspace string, exited bool) http.Handler { mux := http.NewServeMux() mux.HandleFunc("GET /api/info", func(w http.ResponseWriter, r *http.Request) { if !largeChatFixtureAuthenticated(w, r) { @@ -63,6 +72,33 @@ func LargeChatFixtureHandler(workspace string) http.Handler { } writeLargeChatFixturePage(w, page) }) + status := "running" + if exited { + status = "exited" + } + mux.HandleFunc("GET /api/shell", func(w http.ResponseWriter, r *http.Request) { + if !largeChatFixtureAuthenticated(w, r) { + return + } + writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":[{"id":%q,"status":%q,"command":"printf fixture","metadata":{"sessionID":%q}}]}`, LargeChatFixtureShellID, status, LargeChatFixtureSessionID)) + }) + mux.HandleFunc("GET /api/shell/"+LargeChatFixtureShellID, func(w http.ResponseWriter, r *http.Request) { + if !largeChatFixtureAuthenticated(w, r) { + return + } + exit := "null" + if exited { + exit = "0" + } + writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":{"id":%q,"status":%q,"command":"printf fixture","exit":%s,"metadata":{"sessionID":%q}}}`, LargeChatFixtureShellID, status, exit, LargeChatFixtureSessionID)) + }) + mux.HandleFunc("GET /api/shell/"+LargeChatFixtureShellID+"/output", func(w http.ResponseWriter, r *http.Request) { + if !largeChatFixtureAuthenticated(w, r) { + return + } + cursor := int64(len(LargeChatFixtureShellOutput)) + writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":{"output":%q,"cursor":%d,"size":%d,"truncated":false}}`, LargeChatFixtureShellOutput, cursor, cursor)) + }) return mux } From f5f682a990bd61190dd2a5ab5cc8369840595969 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 20:23:43 +0100 Subject: [PATCH 3/4] test: strengthen background shell output verification --- cmd/pipelines-large-chat-fixture/main.go | 62 ++++-- docs/notes/background-task-output-api.md | 36 +++- internal/opencode/chat.go | 20 ++ internal/server/chat_shell_output_test.go | 233 ++++++++++++++++++++++ internal/server/large_chat_fixture.go | 18 +- internal/server/websocket.go | 2 +- 6 files changed, 344 insertions(+), 27 deletions(-) diff --git a/cmd/pipelines-large-chat-fixture/main.go b/cmd/pipelines-large-chat-fixture/main.go index e486fc17..9ca0bf3b 100644 --- a/cmd/pipelines-large-chat-fixture/main.go +++ b/cmd/pipelines-large-chat-fixture/main.go @@ -77,49 +77,81 @@ func main() { if err != nil { fatal(err) } - if err := verifyShellReadback(ctx, endpoint, *exited); err != nil { + shellReadbacks, err := verifyShellReadback(ctx, endpoint, *exited) + if err != nil { fatal(err) } + <-ctx.Done() + shutdown, stop := context.WithTimeout(context.Background(), 5*time.Second) + pipelinesErr := pipelinesServer.Shutdown(shutdown) + upstreamErr := upstreamServer.Shutdown(shutdown) + stop() + if pipelinesErr != nil { + fatal(pipelinesErr) + } + if upstreamErr != nil { + fatal(upstreamErr) + } info := buildinfo.Current() _ = json.NewEncoder(os.Stdout).Encode(map[string]any{ "endpoint": endpoint, "upstream_endpoint": upstreamURL, "backend": attached.Connection.Backend, "revision": info.Commit, "session_id": server.LargeChatFixtureSessionID, "workspace": workspace, "newest_readback": readbacks[0], "older_readback": readbacks[1], + "shell_readbacks": shellReadbacks, "clean_shutdown": true, "shutdown_exit_status": 0, }) - <-ctx.Done() - shutdown, stop := context.WithTimeout(context.Background(), 5*time.Second) - defer stop() - _ = pipelinesServer.Shutdown(shutdown) - _ = upstreamServer.Shutdown(shutdown) } -func verifyShellReadback(ctx context.Context, endpoint string, exited bool) error { +func verifyShellReadback(ctx context.Context, endpoint string, exited bool) (map[string]any, error) { + evidence := map[string]any{"test_id": "fixture-shell-owned-and-foreign-refusal", "negative": []string{}} ws, _, err := websocket.Dial(ctx, "ws"+strings.TrimPrefix(endpoint, "http")+"/connect", nil) if err != nil { - return err + return evidence, err } defer ws.Close(websocket.StatusNormalClosure, "fixture complete") if err := wsjson.Write(ctx, ws, protocol.Message{Type: protocol.ChatShells, ID: "fixture-shells", ChatQuery: &protocol.ChatQuery{SessionID: server.LargeChatFixtureSessionID}}); err != nil { - return err + return evidence, err } var listed protocol.Message if listed, err = readFixtureResponse(ctx, ws, protocol.ChatShells); err != nil { - return err + return evidence, err } if !exited && (len(listed.ChatShells) != 1 || listed.ChatShells[0].ID != server.LargeChatFixtureShellID) { - return fmt.Errorf("fixture shell is not listed") + return evidence, fmt.Errorf("fixture shell is not listed") } if err := wsjson.Write(ctx, ws, protocol.Message{Type: protocol.ChatShellOutput, ID: "fixture-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: server.LargeChatFixtureSessionID, ShellID: server.LargeChatFixtureShellID, Limit: 64 << 10}}); err != nil { - return err + return evidence, err } page, err := readFixtureResponse(ctx, ws, protocol.ChatShellOutput) if err != nil { - return err + return evidence, err } if page.ChatShellOutput == nil || page.ChatShellOutput.Output != server.LargeChatFixtureShellOutput || page.ChatShellOutput.Shell.Status != map[bool]string{true: "exited", false: "running"}[exited] { - return fmt.Errorf("unexpected shell readback: %+v", page.ChatShellOutput) + return evidence, fmt.Errorf("unexpected shell readback: %+v", page.ChatShellOutput) } - return nil + evidence["owned"] = map[string]any{"shell_id": page.ChatShellOutput.Shell.ID, "output": page.ChatShellOutput.Output, "cursor": page.ChatShellOutput.Cursor, "status": page.ChatShellOutput.Shell.Status} + negative := evidence["negative"].([]string) + negativeRequests := []protocol.Message{ + {Type: protocol.ChatShells, ID: "foreign-list", ChatQuery: &protocol.ChatQuery{SessionID: server.LargeChatFixtureForeignSessionID}}, + {Type: protocol.ChatShells, ID: "unknown-list", ChatQuery: &protocol.ChatQuery{SessionID: "ses_unregistered_fixture"}}, + {Type: protocol.ChatShellOutput, ID: "foreign-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: server.LargeChatFixtureSessionID, ShellID: server.LargeChatFixtureForeignShellID, Limit: 64 << 10}}, + {Type: protocol.ChatShellOutput, ID: "unknown-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: "ses_unregistered_fixture", ShellID: server.LargeChatFixtureShellID, Limit: 64 << 10}}, + } + for _, request := range negativeRequests { + if err := wsjson.Write(ctx, ws, request); err != nil { + return evidence, err + } + var response protocol.Message + if err := wsjson.Read(ctx, ws, &response); err != nil { + return evidence, err + } + if response.Type != protocol.Error || strings.Contains(response.Error, server.LargeChatFixtureForeignShellOutput) { + return evidence, fmt.Errorf("negative request %s leaked or succeeded: %+v", request.ID, response) + } + negative = append(negative, request.ID) + } + evidence["negative"] = negative + evidence["negative_count"] = len(negative) + return evidence, nil } func verifyBroker(ctx context.Context, endpoint string) ([2]map[string]any, error) { diff --git a/docs/notes/background-task-output-api.md b/docs/notes/background-task-output-api.md index 13cddebd..dd705034 100644 --- a/docs/notes/background-task-output-api.md +++ b/docs/notes/background-task-output-api.md @@ -12,13 +12,29 @@ Stale shared documentation: the packaged OpenCode operational references under `internal/author/skill/references/` need a later docs-fold update describing the two additive websocket messages, 64 KiB maximum page, and current-only history. -Fixture evidence (2026-10-18): `go build -o /tmp/pipelines-large-chat-fixture-stage -./cmd/pipelines-large-chat-fixture`; then `/tmp/pipelines-large-chat-fixture-stage --scratch-dir /var/folders/jp/q0qvjyg54fl_c5vhhk1ylz2m0000gn/T/pipelines-shell-fixture-pxnc95h2 --shell-exited`, stopped with SIGTERM. The foreground run exercised authenticated -`chat_sessions`, three reconnecting history pages, `chat_shells`, and bounded -`chat_shell_output` readback against scratch DB/workspace only, and exited 0 after -clean shutdown. Recorded revision `fd4c329eafc46d1ce32dc9bc36fd9bd09b34e058`, -session `ses_large_chat_fixture`, shell `sh_large_chat_fixture`, and fixed marker -`fixture shell output marker\n`. The selected exited shell is read directly by id; -the current list remains running-shell discovery. +Fixture evidence (2026-10-18): `go build -o /pipelines-large-chat-fixture +./cmd/pipelines-large-chat-fixture`; then `/pipelines-large-chat-fixture +-scratch-dir /run -shell-exited`, stopped with SIGTERM and awaited. The +foreground run exercised authenticated `chat_sessions`, three reconnecting history +pages, `chat_shells`, bounded `chat_shell_output`, and four executable negative +readbacks (`foreign-list`, `unknown-list`, `foreign-output`, `unknown-output`) against +scratch DB/workspace only. Its JSON contains `clean_shutdown: true` and +`shutdown_exit_status: 0`, plus the selected exited shell's `exit: 0` readback. +The evidence revision was `ded79277783b6ccdc25eb4ea25fe55d8632b89c7`; session +`ses_large_chat_fixture`, shell `sh_large_chat_fixture`, and fixed marker +`fixture shell output marker\n`. The current list remains running-shell discovery. + +Integration coverage added: `TestChatShellOutputRejectsBoundsBeforeRegistryOrProvider`, +`TestChatShellOutputRealHandlerWebsocketOwnedAndForeign`, and +`TestChatShellOutputRealHandlerExitedReadback`, +`TestChatShellOutputRealHandlerUnavailableAndReconnect`, and +`TestChatShellOutputRejectsMalformedAndOversizedProviderPages`, and +`TestChatShellOutputRealHandlerCancellationStopsProvider` in +`internal/server/chat_shell_output_test.go`. Run with +`go test ./internal/server -run 'TestChatShellOutput' -count=1 -v` and +`go test -race ./internal/server -run 'TestChatShellOutput(RealHandler|RejectsBounds)' -count=1 -v`. +These tests use an authenticated in-process HTTP provider, a scratch SQLite operator +registry, and real `/connect` websocket traffic. The fixture executes foreign +session/shell refusal requests and records positive/negative JSON readbacks under +`shell_readbacks`; it remains scratch-only evidence, not evidence of a real provider, +model, production workspace, or device. diff --git a/internal/opencode/chat.go b/internal/opencode/chat.go index 379a1ce7..6342f772 100644 --- a/internal/opencode/chat.go +++ b/internal/opencode/chat.go @@ -33,6 +33,10 @@ type Chat struct { conn *Connection shellMu sync.Mutex shells map[string]*ChatStreamState + // shellOwners retains ownership from the last authoritative global shell + // listing so a shell known to belong to another session is rejected before + // its detail or output endpoint is queried. + shellOwners map[string]string // mu serializes the adapter's HTTP calls. Connection records its last // operation and status on the shared connection, so two calls must not // overlap; the permission poller runs alongside the read loop's @@ -405,6 +409,16 @@ func (c *Chat) Shells(ctx context.Context, sessionID string) ([]protocol.ChatShe return nil, fmt.Errorf("invalid OpenCode shell response") } } + c.shellMu.Lock() + if c.shellOwners == nil { + c.shellOwners = make(map[string]string) + } + for _, info := range response.Data { + if ValidShellID(info.ID) && ValidSessionID(info.shellSessionID()) { + c.shellOwners[info.ID] = info.shellSessionID() + } + } + c.shellMu.Unlock() out := make([]protocol.ChatShell, 0, len(response.Data)) for _, info := range response.Data { if info.ID == "" || info.shellSessionID() != sessionID || (info.Status != "" && info.Status != protocol.ChatShellRunning && info.Status != protocol.ChatShellExited) { @@ -440,6 +454,12 @@ func (c *Chat) ShellOutput(ctx context.Context, query protocol.ChatShellOutputQu if !ValidSessionID(query.SessionID) || !ValidShellID(query.ShellID) || query.Cursor < 0 || query.Cursor > protocol.ChatShellOutputMaxCursor || query.Limit <= 0 || query.Limit > protocol.ChatShellOutputLimit { return protocol.ChatShellOutputPage{}, fmt.Errorf("invalid shell output query") } + c.shellMu.Lock() + owner := c.shellOwners[query.ShellID] + c.shellMu.Unlock() + if owner != "" && owner != query.SessionID { + return protocol.ChatShellOutputPage{}, fmt.Errorf("shell is not available for this session") + } data, err := c.call(ctx, "get", "/api/shell/"+query.ShellID, nil) if err != nil { if c.conn.LastHTTPStatus == 404 { diff --git a/internal/server/chat_shell_output_test.go b/internal/server/chat_shell_output_test.go index 43b6c766..7c66d48a 100644 --- a/internal/server/chat_shell_output_test.go +++ b/internal/server/chat_shell_output_test.go @@ -2,8 +2,18 @@ package server import ( "context" + "fmt" + "net/http" + "net/http/httptest" + "strings" + "sync/atomic" "testing" + "time" + "github.com/coder/websocket" + "github.com/coder/websocket/wsjson" + + "git.a-wan.net/alan/pipelines/internal/opencode" "git.a-wan.net/alan/pipelines/internal/protocol" ) @@ -45,3 +55,226 @@ func TestChatShellOutputRejectsBoundsBeforeRegistryOrProvider(t *testing.T) { t.Fatalf("invalid queries reached provider %d times", broker.outputCalls) } } + +// TestChatShellOutputRealHandlerWebsocketOwnedAndForeign drives the real +// authenticated adapter, HTTP fixture, HandlerWithOptions, and /connect path. +// The foreign detail deliberately has a marker that would be returned by its +// output route; the session metadata check must reject it first. +func TestChatShellOutputRealHandlerWebsocketOwnedAndForeign(t *testing.T) { + testChatShellOutputOwnedAndForeign(t, false) +} + +func TestChatShellOutputRealHandlerExitedReadback(t *testing.T) { + testChatShellOutputOwnedAndForeign(t, true) +} + +func testChatShellOutputOwnedAndForeign(t *testing.T, exited bool) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + var providerRequests atomic.Int32 + fixtureHandler := LargeChatFixtureHandlerWithShell(t.TempDir(), exited) + fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + providerRequests.Add(1) + fixtureHandler.ServeHTTP(w, r) + })) + defer fixture.Close() + attached, err := opencode.OpenEndpointAttached(ctx, fixture.URL, LargeChatFixturePassword, "", "") + if err != nil { + t.Fatal(err) + } + store := newOperatorStore(t) + if err := store.RecordOperatorSession(ctx, LargeChatFixtureSessionID, t.TempDir(), "owned", protocol.ChatSessionTagOperator); err != nil { + t.Fatal(err) + } + srv := httptest.NewServer(HandlerWithOptions(ctx, Options{Chat: opencode.NewChat(attached.Connection), OperatorRegistry: store})) + defer srv.Close() + ws := dialShellOutputWebsocket(t, ctx, srv) + defer ws.CloseNow() + + writeChat(t, ctx, ws, protocol.Message{Type: protocol.ChatShells, ID: "owned-shells", ChatQuery: &protocol.ChatQuery{SessionID: LargeChatFixtureSessionID}}) + owned := readShellOutputMessage(t, ctx, ws) + if owned.Type != protocol.ChatShells || (exited && len(owned.ChatShells) != 0) || (!exited && (len(owned.ChatShells) != 1 || owned.ChatShells[0].ID != LargeChatFixtureShellID || owned.ChatShells[0].Status != protocol.ChatShellRunning)) { + t.Fatalf("owned shell listing = %+v", owned) + } + wantStatus := protocol.ChatShellRunning + if exited { + wantStatus = protocol.ChatShellExited + } + writeChat(t, ctx, ws, protocol.Message{Type: protocol.ChatShellOutput, ID: "owned-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: LargeChatFixtureSessionID, ShellID: LargeChatFixtureShellID, Limit: protocol.ChatShellOutputLimit}}) + page := readShellOutputMessage(t, ctx, ws) + if page.Type != protocol.ChatShellOutput || page.ChatShellOutput == nil || page.ChatShellOutput.Output != LargeChatFixtureShellOutput || page.ChatShellOutput.Cursor != int64(len(LargeChatFixtureShellOutput)) || page.ChatShellOutput.Shell.Status != wantStatus { + t.Fatalf("owned output page = %+v", page) + } + if exited { + if page.ChatShellOutput.Shell.Exit == nil || *page.ChatShellOutput.Shell.Exit != 0 { + t.Fatalf("selected exited shell readback = %+v", page.ChatShellOutput.Shell) + } + } else if page.ChatShellOutput.Shell.Exit != nil { + t.Fatalf("running shell unexpectedly has exit = %+v", page.ChatShellOutput.Shell.Exit) + } + if page.ChatShellOutput.Cursor != int64(len(page.ChatShellOutput.Output)) || page.ChatShellOutput.Size != page.ChatShellOutput.Cursor { + t.Fatalf("non-deterministic output cursor/size = %+v", page.ChatShellOutput) + } + refusals := []struct { + name string + request protocol.Message + }{ + {name: "foreign-output", request: protocol.Message{Type: protocol.ChatShellOutput, ID: "foreign-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: LargeChatFixtureSessionID, ShellID: LargeChatFixtureForeignShellID, Limit: protocol.ChatShellOutputLimit}}}, + {name: "foreign-list", request: protocol.Message{Type: protocol.ChatShells, ID: "foreign-list", ChatQuery: &protocol.ChatQuery{SessionID: LargeChatFixtureForeignSessionID}}}, + {name: "syntax-invalid-list", request: protocol.Message{Type: protocol.ChatShells, ID: "invalid-list", ChatQuery: &protocol.ChatQuery{SessionID: "ses_bad/invalid"}}}, + {name: "unknown-output", request: protocol.Message{Type: protocol.ChatShellOutput, ID: "unknown-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: "ses_unregistered_fixture", ShellID: LargeChatFixtureShellID, Limit: protocol.ChatShellOutputLimit}}}, + } + for _, refusal := range refusals { + beforeRefusal := providerRequests.Load() + writeChat(t, ctx, ws, refusal.request) + response := readShellOutputMessage(t, ctx, ws) + if response.Type != protocol.Error || strings.Contains(response.Error, LargeChatFixtureForeignShellOutput) { + t.Fatalf("%s response leaked or succeeded: %+v", refusal.name, response) + } + if got := providerRequests.Load(); got != beforeRefusal { + t.Fatalf("%s reached provider: requests %d -> %d", refusal.name, beforeRefusal, got) + } + } +} + +func TestChatShellOutputRealHandlerUnavailableAndReconnect(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + fixture := httptest.NewServer(LargeChatFixtureHandlerWithShell(t.TempDir(), false)) + defer fixture.Close() + attached, err := opencode.OpenEndpointAttached(ctx, fixture.URL, LargeChatFixturePassword, "", "") + if err != nil { + t.Fatal(err) + } + store := newOperatorStore(t) + if err := store.RecordOperatorSession(ctx, LargeChatFixtureSessionID, t.TempDir(), "owned", protocol.ChatSessionTagOperator); err != nil { + t.Fatal(err) + } + srv := httptest.NewServer(HandlerWithOptions(ctx, Options{Chat: opencode.NewChat(attached.Connection), OperatorRegistry: store})) + defer srv.Close() + ws := dialShellOutputWebsocket(t, ctx, srv) + writeChat(t, ctx, ws, protocol.Message{Type: protocol.ChatShellOutput, ID: "missing-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: LargeChatFixtureSessionID, ShellID: "sh_missing_fixture", Limit: 64}}) + missing := readShellOutputMessage(t, ctx, ws) + if missing.Type != protocol.ChatShellOutput || missing.ChatShellOutput == nil || !missing.ChatShellOutput.Unavailable { + t.Fatalf("404 shell output = %+v", missing) + } + ws = dialShellOutputWebsocket(t, ctx, srv) + defer ws.CloseNow() + writeChat(t, ctx, ws, protocol.Message{Type: protocol.ChatShells, ID: "reconnect", ChatQuery: &protocol.ChatQuery{SessionID: LargeChatFixtureSessionID}}) + if got := readShellOutputMessage(t, ctx, ws); got.Type != protocol.ChatShells { + t.Fatalf("reconnect shell listing = %+v", got) + } + if _, err := opencode.OpenEndpointAttached(ctx, fixture.URL, "wrong-password", "", ""); err == nil { + t.Fatal("wrong provider authentication unexpectedly succeeded") + } +} + +func TestChatShellOutputRejectsMalformedAndOversizedProviderPages(t *testing.T) { + for _, tc := range []struct { + name string + output string + }{ + {name: "malformed", output: `{"data":{"output":"x"}}`}, + {name: "oversized", output: fmt.Sprintf(`{"data":{"output":%q,"cursor":%d,"size":%d,"truncated":false}}`, strings.Repeat("x", protocol.ChatShellOutputLimit+1), protocol.ChatShellOutputLimit+1, protocol.ChatShellOutputLimit+1)}, + } { + t.Run(tc.name, func(t *testing.T) { + fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if !largeChatFixtureAuthenticated(w, r) { + return + } + w.Header().Set("Content-Type", "application/json") + switch r.URL.Path { + case "/api/info": + _, _ = w.Write([]byte(`{"version":"fixture","urls":[]}`)) + case "/api/event": + w.Header().Set("Content-Type", "text/event-stream") + case "/api/shell/sh_malformed_fixture": + _, _ = w.Write([]byte(`{"data":{"id":"sh_malformed_fixture","status":"running","metadata":{"sessionID":"ses_malformed_fixture"}}}`)) + case "/api/shell/sh_malformed_fixture/output": + _, _ = w.Write([]byte(tc.output)) + default: + if r.URL.Path == "/api/shell" { + _, _ = w.Write([]byte(`{"data":[]}`)) + return + } + http.NotFound(w, r) + } + })) + defer fixture.Close() + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + attached, err := opencode.OpenEndpointAttached(ctx, fixture.URL, LargeChatFixturePassword, "", "") + if err != nil { + t.Fatal(err) + } + _, err = opencode.NewChat(attached.Connection).ShellOutput(ctx, protocol.ChatShellOutputQuery{SessionID: "ses_malformed_fixture", ShellID: "sh_malformed_fixture", Limit: protocol.ChatShellOutputLimit}) + if err == nil { + t.Fatalf("%s provider page was accepted", tc.name) + } + }) + } +} + +func TestChatShellOutputRealHandlerCancellationStopsProvider(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + started := make(chan struct{}) + canceled := make(chan struct{}) + fixtureHandler := LargeChatFixtureHandlerWithShell(t.TempDir(), false) + fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path == "/api/shell/sh_cancel_fixture" { + if !largeChatFixtureAuthenticated(w, r) { + return + } + close(started) + <-r.Context().Done() + close(canceled) + return + } + fixtureHandler.ServeHTTP(w, r) + })) + defer fixture.Close() + attached, err := opencode.OpenEndpointAttached(ctx, fixture.URL, LargeChatFixturePassword, "", "") + if err != nil { + t.Fatal(err) + } + store := newOperatorStore(t) + if err := store.RecordOperatorSession(ctx, "ses_cancel_fixture", t.TempDir(), "cancel", protocol.ChatSessionTagOperator); err != nil { + t.Fatal(err) + } + serverCtx, serverCancel := context.WithCancel(ctx) + defer serverCancel() + srv := httptest.NewServer(HandlerWithOptions(serverCtx, Options{Chat: opencode.NewChat(attached.Connection), OperatorRegistry: store})) + defer srv.Close() + ws := dialShellOutputWebsocket(t, ctx, srv) + writeChat(t, ctx, ws, protocol.Message{Type: protocol.ChatShellOutput, ID: "cancel-output", ChatShellOutputQuery: &protocol.ChatShellOutputQuery{SessionID: "ses_cancel_fixture", ShellID: "sh_cancel_fixture", Limit: 64}}) + select { + case <-started: + case <-ctx.Done(): + t.Fatal("provider detail request did not start") + } + serverCancel() + select { + case <-canceled: + case <-ctx.Done(): + t.Fatal("canceling handler did not cancel provider request") + } +} + +func dialShellOutputWebsocket(t *testing.T, ctx context.Context, srv *httptest.Server) *websocket.Conn { + t.Helper() + ws, _, err := websocket.Dial(ctx, "ws"+strings.TrimPrefix(srv.URL, "http")+"/connect", nil) + if err != nil { + t.Fatal(err) + } + return ws +} + +func readShellOutputMessage(t *testing.T, ctx context.Context, ws *websocket.Conn) protocol.Message { + t.Helper() + var message protocol.Message + if err := wsjson.Read(ctx, ws, &message); err != nil { + t.Fatal(err) + } + return message +} diff --git a/internal/server/large_chat_fixture.go b/internal/server/large_chat_fixture.go index a43ab273..be620321 100644 --- a/internal/server/large_chat_fixture.go +++ b/internal/server/large_chat_fixture.go @@ -15,6 +15,9 @@ const LargeChatFixtureSessionID = "ses_large_chat_fixture" const LargeChatFixturePassword = "large-chat-fixture" const LargeChatFixtureShellID = "sh_large_chat_fixture" const LargeChatFixtureShellOutput = "fixture shell output marker\n" +const LargeChatFixtureForeignSessionID = "ses_foreign_fixture" +const LargeChatFixtureForeignShellID = "sh_foreign_fixture" +const LargeChatFixtureForeignShellOutput = "FOREIGN SHELL MARKER MUST NOT LEAK\n" const ( LargeChatFixtureNewestAnswer = "Controlled newest answer: large history fixture" @@ -80,7 +83,7 @@ func LargeChatFixtureHandlerWithShell(workspace string, exited bool) http.Handle if !largeChatFixtureAuthenticated(w, r) { return } - writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":[{"id":%q,"status":%q,"command":"printf fixture","metadata":{"sessionID":%q}}]}`, LargeChatFixtureShellID, status, LargeChatFixtureSessionID)) + writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":[{"id":%q,"status":%q,"command":"printf fixture","metadata":{"sessionID":%q}},{"id":%q,"status":"running","command":"printf foreign","metadata":{"sessionID":%q}}]}`, LargeChatFixtureShellID, status, LargeChatFixtureSessionID, LargeChatFixtureForeignShellID, LargeChatFixtureForeignSessionID)) }) mux.HandleFunc("GET /api/shell/"+LargeChatFixtureShellID, func(w http.ResponseWriter, r *http.Request) { if !largeChatFixtureAuthenticated(w, r) { @@ -92,6 +95,12 @@ func LargeChatFixtureHandlerWithShell(workspace string, exited bool) http.Handle } writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":{"id":%q,"status":%q,"command":"printf fixture","exit":%s,"metadata":{"sessionID":%q}}}`, LargeChatFixtureShellID, status, exit, LargeChatFixtureSessionID)) }) + mux.HandleFunc("GET /api/shell/"+LargeChatFixtureForeignShellID, func(w http.ResponseWriter, r *http.Request) { + if !largeChatFixtureAuthenticated(w, r) { + return + } + writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":{"id":%q,"status":"running","command":"printf foreign","metadata":{"sessionID":%q}}}`, LargeChatFixtureForeignShellID, LargeChatFixtureForeignSessionID)) + }) mux.HandleFunc("GET /api/shell/"+LargeChatFixtureShellID+"/output", func(w http.ResponseWriter, r *http.Request) { if !largeChatFixtureAuthenticated(w, r) { return @@ -99,6 +108,13 @@ func LargeChatFixtureHandlerWithShell(workspace string, exited bool) http.Handle cursor := int64(len(LargeChatFixtureShellOutput)) writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":{"output":%q,"cursor":%d,"size":%d,"truncated":false}}`, LargeChatFixtureShellOutput, cursor, cursor)) }) + mux.HandleFunc("GET /api/shell/"+LargeChatFixtureForeignShellID+"/output", func(w http.ResponseWriter, r *http.Request) { + if !largeChatFixtureAuthenticated(w, r) { + return + } + cursor := int64(len(LargeChatFixtureForeignShellOutput)) + writeLargeChatFixtureJSON(w, fmt.Sprintf(`{"data":{"output":%q,"cursor":%d,"size":%d,"truncated":false}}`, LargeChatFixtureForeignShellOutput, cursor, cursor)) + }) return mux } diff --git a/internal/server/websocket.go b/internal/server/websocket.go index 5e598223..7e497c46 100644 --- a/internal/server/websocket.go +++ b/internal/server/websocket.go @@ -171,7 +171,7 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin } for { var request protocol.Message - if err := wsjson.Read(ctx, conn, &request); err != nil { + if err := wsjson.Read(connCtx, conn, &request); err != nil { return } log.Printf("command received: client=%s type=%q id=%q pipeline=%d version=%d", r.RemoteAddr, request.Type, request.ID, request.PipelineID, request.Version) From 93da8efb3df60342c910583da115bcfa8275e2a1 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 20:25:24 +0100 Subject: [PATCH 4/4] test: report fixture shell exit status --- cmd/pipelines-large-chat-fixture/main.go | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/cmd/pipelines-large-chat-fixture/main.go b/cmd/pipelines-large-chat-fixture/main.go index 9ca0bf3b..17b10e8e 100644 --- a/cmd/pipelines-large-chat-fixture/main.go +++ b/cmd/pipelines-large-chat-fixture/main.go @@ -128,7 +128,11 @@ func verifyShellReadback(ctx context.Context, endpoint string, exited bool) (map if page.ChatShellOutput == nil || page.ChatShellOutput.Output != server.LargeChatFixtureShellOutput || page.ChatShellOutput.Shell.Status != map[bool]string{true: "exited", false: "running"}[exited] { return evidence, fmt.Errorf("unexpected shell readback: %+v", page.ChatShellOutput) } - evidence["owned"] = map[string]any{"shell_id": page.ChatShellOutput.Shell.ID, "output": page.ChatShellOutput.Output, "cursor": page.ChatShellOutput.Cursor, "status": page.ChatShellOutput.Shell.Status} + owned := map[string]any{"shell_id": page.ChatShellOutput.Shell.ID, "output": page.ChatShellOutput.Output, "cursor": page.ChatShellOutput.Cursor, "status": page.ChatShellOutput.Shell.Status} + if page.ChatShellOutput.Shell.Exit != nil { + owned["exit"] = *page.ChatShellOutput.Shell.Exit + } + evidence["owned"] = owned negative := evidence["negative"].([]string) negativeRequests := []protocol.Message{ {Type: protocol.ChatShells, ID: "foreign-list", ChatQuery: &protocol.ChatQuery{SessionID: server.LargeChatFixtureForeignSessionID}},