From fd4c329eafc46d1ce32dc9bc36fd9bd09b34e058 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 17:10:44 +0100 Subject: [PATCH] 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_" }