WIP: preserve background task output API

This commit is contained in:
2026-10-18 17:10:44 +01:00
parent 5946f1abc8
commit fd4c329eaf
7 changed files with 199 additions and 1 deletions
+13
View File
@@ -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.
+47
View File
@@ -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"`
}
+25
View File
@@ -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")
+24
View File
@@ -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
+4 -1
View File
@@ -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.
+10
View File
@@ -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
}
+76
View File
@@ -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_" }