Preserve background shell visibility across readback races

Reconcile authoritative shell snapshots with bounded lifecycle journals so concurrent exits and creates cannot be overwritten, coalesce observation setup, and retain verified ownership across reconnects. Add deterministic reconciliation and cancellation regressions plus stable limited-visibility handling.\n\nChecked packaged templates and authoring skill references: none need updating. The task-owned docs note records the stale shared chat documentation for docs-fold; shared documentation was not edited.
This commit is contained in:
2026-10-18 12:54:36 +01:00
parent 101e5e8dfe
commit e9d902213e
12 changed files with 1036 additions and 25 deletions
+198 -11
View File
@@ -28,7 +28,9 @@ var ErrPermissionUnsupported = errors.New("OpenCode permission approval is not i
// semantics, the session-id shape and the 64 KiB / 1 MiB bounds of Connection so
// no second transport or credential path is introduced.
type Chat struct {
conn *Connection
conn *Connection
shellMu sync.Mutex
shells map[string]*ChatStreamState
// 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
@@ -294,6 +296,114 @@ func decodeChatPermissions(sessionID string, data []byte) ([]protocol.ChatPermis
return frames, nil
}
// Shells reads the endpoint's authoritative shell list and returns only running
// operations whose metadata explicitly names sessionID. The shell API is global;
// filtering locally avoids guessing an unsupported query filter and never assigns
// ownership from a shared working directory. A successful read also seeds the
// stream state used to attribute later shell.exited events, which carry no session.
func (c *Chat) Shells(ctx context.Context, sessionID string) ([]protocol.ChatShell, error) {
if !ValidSessionID(sessionID) {
return nil, fmt.Errorf("invalid OpenCode session id")
}
state, err := c.streamStateContext(ctx, sessionID)
if err != nil {
return nil, err
}
// One read per state; waiting and I/O never hold the event-state mutex.
state.mu.Lock()
if state.readGate == nil {
state.readGate = make(chan struct{}, 1)
}
gate := state.readGate
state.mu.Unlock()
select {
case gate <- struct{}{}:
case <-ctx.Done():
return nil, ctx.Err()
}
defer func() { <-gate }()
state.mu.Lock()
state.readback = &ShellSnapshot{}
state.mu.Unlock()
defer func() { state.mu.Lock(); state.readback = nil; state.mu.Unlock() }()
data, err := c.call(ctx, "get", "/api/shell", nil)
if err != nil {
return nil, err
}
var response struct {
Data []chatShellInfo `json:"data"`
}
if err := json.Unmarshal(data, &response); err != nil || response.Data == nil {
if err := json.Unmarshal(data, &response.Data); err != nil {
return nil, fmt.Errorf("invalid OpenCode shell response")
}
}
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) {
continue
}
status := info.Status
if status == "" {
status = protocol.ChatShellRunning
}
out = append(out, protocol.ChatShell{ID: info.ID, Status: status, Command: info.Command})
}
state.mu.Lock()
defer state.mu.Unlock()
out, err = state.readback.Merge(out)
if err != nil {
return nil, err
}
if err := ctx.Err(); err != nil {
return nil, err
}
ids := make([]string, 0, len(out))
for _, shell := range out {
ids = append(ids, shell.ID)
}
state.replaceShellsLocked(ids)
return out, 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
// each attach rather than replacing the pointer a live scanner is using.
func (c *Chat) streamState(sessionID string) *ChatStreamState {
state, _ := c.streamStateContext(context.Background(), sessionID)
return state
}
func (c *Chat) streamStateContext(ctx context.Context, sessionID string) (*ChatStreamState, error) {
c.shellMu.Lock()
defer c.shellMu.Unlock()
if err := ctx.Err(); err != nil {
return nil, err
}
if c.shells == nil {
c.shells = map[string]*ChatStreamState{}
}
state := c.shells[sessionID]
if state == nil {
state = &ChatStreamState{}
c.shells[sessionID] = state
}
return state, nil
}
// ReleaseShells discards verified shell identities after the last room observer
// disconnects. A future attach calls Shells for a fresh authoritative snapshot,
// so this bounds state without attributing a foreign shell during the gap.
func (c *Chat) ReleaseShells(sessionID string) {
if sessionID == "" {
return
}
c.shellMu.Lock()
delete(c.shells, sessionID)
c.shellMu.Unlock()
}
// Stream subscribes to the OpenCode event firehose and invokes emit for every
// frame belonging to sessionID. It reads one bounded SSE frame at a time and
// never polls the per-session message log; the global firehose is the only
@@ -306,6 +416,12 @@ func (c *Chat) Stream(ctx context.Context, id string, ready func(), emit func(pr
if !sessionID.MatchString(id) {
return fmt.Errorf("invalid OpenCode session id")
}
// Pin state before opening/announcing the stream so a canceled scanner
// cannot acquire a replacement room's identity map.
state, err := c.streamStateContext(ctx, id)
if err != nil {
return err
}
body, err := c.conn.EventStream(ctx)
if err != nil {
return err
@@ -314,7 +430,7 @@ func (c *Chat) Stream(ctx context.Context, id string, ready func(), emit func(pr
if ready != nil {
ready()
}
return scanChatEvents(ctx, body, id, emit)
return c.scanChatEventsWithState(ctx, body, id, state, emit)
}
// scanChatEvents turns an SSE body into protocol frames, one bounded frame at a
@@ -322,10 +438,13 @@ func (c *Chat) Stream(ctx context.Context, id string, ready func(), emit func(pr
// malformed JSON fails the stream instead of producing a malformed frame. The
// last assistant message id is retained so a later tool/step event that omits it
// still attributes every frame to a stable message.
func scanChatEvents(ctx context.Context, body io.Reader, sessionID string, emit func(protocol.ChatEventFrame) error) error {
func (c *Chat) scanChatEvents(ctx context.Context, body io.Reader, sessionID string, emit func(protocol.ChatEventFrame) error) error {
return c.scanChatEventsWithState(ctx, body, sessionID, c.streamState(sessionID), emit)
}
func (c *Chat) scanChatEventsWithState(ctx context.Context, body io.Reader, sessionID string, state *ChatStreamState, emit func(protocol.ChatEventFrame) error) error {
scanner := bufio.NewScanner(body)
scanner.Buffer(make([]byte, 0, 64<<10), MaxResponse)
state := &ChatStreamState{}
for scanner.Scan() {
if err := ctx.Err(); err != nil {
return err
@@ -346,7 +465,7 @@ func scanChatEvents(ctx context.Context, body io.Reader, sessionID string, emit
continue
}
if frame.MessageID != "" {
state.LastMessageID = frame.MessageID
state.setLastMessageID(frame.MessageID)
}
if err := emit(frame); err != nil {
return err
@@ -449,8 +568,29 @@ func (i *chatShellInfo) shellSessionID() string {
// what attributes the exit to its session: another session's shell is an
// unknown id and is ignored.
type ChatStreamState struct {
mu sync.Mutex
LastMessageID string
Shells map[string]struct{}
readGate chan struct{}
readback *ShellSnapshot
}
func (s *ChatStreamState) lastMessageID() string {
if s == nil {
return ""
}
s.mu.Lock()
defer s.mu.Unlock()
return s.LastMessageID
}
func (s *ChatStreamState) setLastMessageID(id string) {
if s == nil || id == "" {
return
}
s.mu.Lock()
s.LastMessageID = id
s.mu.Unlock()
}
// knowsShell reports whether id is a shell this stream has already surfaced for
@@ -459,6 +599,8 @@ func (s *ChatStreamState) knowsShell(id string) bool {
if s == nil || id == "" {
return false
}
s.mu.Lock()
defer s.mu.Unlock()
_, ok := s.Shells[id]
return ok
}
@@ -468,6 +610,8 @@ func (s *ChatStreamState) markShell(id string) {
if s == nil || id == "" {
return
}
s.mu.Lock()
defer s.mu.Unlock()
if s.Shells == nil {
s.Shells = map[string]struct{}{}
}
@@ -476,12 +620,37 @@ func (s *ChatStreamState) markShell(id string) {
// forgetShell drops id once its exit has been surfaced.
func (s *ChatStreamState) forgetShell(id string) {
if s == nil || s.Shells == nil {
if s == nil {
return
}
s.mu.Lock()
defer s.mu.Unlock()
if s.Shells == nil {
return
}
delete(s.Shells, id)
}
// replaceShells applies one authoritative running-shell snapshot without
// replacing the state object an already attached event scanner owns.
func (s *ChatStreamState) replaceShells(ids []string) {
if s == nil {
return
}
s.mu.Lock()
defer s.mu.Unlock()
s.replaceShellsLocked(ids)
}
func (s *ChatStreamState) replaceShellsLocked(ids []string) {
s.Shells = make(map[string]struct{}, len(ids))
for _, id := range ids {
if id != "" {
s.Shells[id] = struct{}{}
}
}
}
// NormalizeChatEvent maps one OpenCode firehose `data:` payload to a
// protocol.ChatEventFrame, folding the small per-session context ([stream]) it
// needs across frames. ok is false for an event type this adapter does not
@@ -528,7 +697,7 @@ func NormalizeChatEvent(payload []byte, sessionID string, stream *ChatStreamStat
messageID = data.MessageIDAlt
}
if messageID == "" && stream != nil {
messageID = stream.LastMessageID
messageID = stream.lastMessageID()
}
// Every pushed frame must carry a stable message id so the client can
// attribute it; without one this is not a chat frame.
@@ -590,20 +759,38 @@ func normalizeShellEvent(eventType string, data chatEvent, sessionID string, str
if status == "" {
status = protocol.ChatShellRunning
}
stream.markShell(data.Info.ID)
shell := &protocol.ChatShell{ID: data.Info.ID, Status: status, Command: data.Info.Command}
if stream != nil {
stream.mu.Lock()
stream.readback.Record(shell)
if stream.Shells == nil {
stream.Shells = map[string]struct{}{}
}
if status == protocol.ChatShellRunning && len(stream.Shells) < chatShellIdentityLimit {
stream.Shells[shell.ID] = struct{}{}
}
stream.mu.Unlock()
}
return protocol.ChatEventFrame{
SessionID: sessionID,
Kind: protocol.ChatEventShell,
Shell: &protocol.ChatShell{ID: data.Info.ID, Status: status, Command: data.Info.Command},
Shell: shell,
}, true, nil
}
if data.ID == "" {
return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode shell.exited event")
}
if !stream.knowsShell(data.ID) {
if stream == nil {
return protocol.ChatEventFrame{}, false, nil
}
stream.mu.Lock()
stream.readback.Record(&protocol.ChatShell{ID: data.ID, Status: protocol.ChatShellExited})
_, known := stream.Shells[data.ID]
delete(stream.Shells, data.ID)
stream.mu.Unlock()
if !known {
return protocol.ChatEventFrame{}, false, nil
}
stream.forgetShell(data.ID)
status := data.Status
if status == "" {
status = protocol.ChatShellExited
@@ -0,0 +1,116 @@
package opencode
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"testing"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
func TestChatShellReadbackBarrier(t *testing.T) {
for _, known := range []bool{false, true} {
t.Run(fmt.Sprint(known), func(t *testing.T) {
read, apply := make(chan struct{}), make(chan struct{})
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
close(read)
select {
case <-apply:
fmt.Fprint(w, `{"data":[{"id":"sh_old","status":"running","metadata":{"sessionID":"ses_1"}},{"id":"sh_foreign","status":"running","metadata":{"sessionID":"ses_other"}}]}`)
case <-r.Context().Done():
}
}))
defer srv.Close()
c := NewChat(&Connection{Backend: "v2", URL: srv.URL})
state := c.streamState("ses_1")
if known {
state.markShell("sh_old")
}
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
result := make(chan []protocol.ChatShell, 1)
errs := make(chan error, 1)
go func() { shells, err := c.Shells(ctx, "ses_1"); result <- shells; errs <- err }()
select {
case <-read:
case <-ctx.Done():
t.Fatal("read did not reach barrier")
}
// Both a previously verified exit and an exit first learned while
// reading must suppress the stale running snapshot.
frame, ok, err := NormalizeChatEvent([]byte(`{"type":"shell.exited","data":{"id":"sh_old","status":"exited","exit":0}}`), "ses_1", state)
if err != nil || ok != known || (ok && frame.Shell.Status != protocol.ChatShellExited) {
t.Fatalf("exit = %+v %v %v", frame, ok, err)
}
frame, ok, err = NormalizeChatEvent([]byte(`{"type":"shell.created","data":{"info":{"id":"sh_new","status":"running","command":"sleep 10","metadata":{"sessionID":"ses_1"}}}}`), "ses_1", state)
if err != nil || !ok || frame.Shell.ID != "sh_new" {
t.Fatalf("create = %+v %v %v", frame, ok, err)
}
close(apply)
got := <-result
if err := <-errs; err != nil {
t.Fatal(err)
}
if len(got) != 1 || got[0].ID != "sh_new" || got[0].Command != "sleep 10" {
t.Fatalf("readback lost events/leaked ownership: %+v", got)
}
if state.knowsShell("sh_old") || state.knowsShell("sh_foreign") || !state.knowsShell("sh_new") {
t.Fatal("adapter identity state regressed")
}
// User-visible subsequent exit remains attributable after reconciliation.
frame, ok, err = NormalizeChatEvent([]byte(`{"type":"shell.exited","data":{"id":"sh_new","status":"exited","exit":0}}`), "ses_1", state)
if err != nil || !ok || frame.Shell.ID != "sh_new" {
t.Fatalf("new shell exit lost: %+v %v %v", frame, ok, err)
}
})
}
}
func TestChatShellReadbackCancelWaiter(t *testing.T) {
read := make(chan struct{})
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { close(read); <-r.Context().Done() }))
defer srv.Close()
c := NewChat(&Connection{Backend: "v2", URL: srv.URL})
ctx, cancel := context.WithCancel(context.Background())
result := make(chan error, 2)
go func() { _, err := c.Shells(ctx, "ses_1"); result <- err }()
select {
case <-read:
case <-time.After(time.Second):
t.Fatal("read stuck")
}
go func() { _, err := c.Shells(ctx, "ses_1"); result <- err }()
cancel()
for range 2 {
select {
case err := <-result:
if err == nil {
t.Fatal("canceled read succeeded")
}
case <-time.After(time.Second):
t.Fatal("read or waiter stuck")
}
}
old := c.streamState("ses_1")
c.ReleaseShells("ses_1")
if c.streamState("ses_1") == old {
t.Fatal("reconnect reused released state")
}
}
func TestShellSnapshotBounded(t *testing.T) {
var snapshot ShellSnapshot
for i := 0; i <= chatShellIdentityLimit; i++ {
snapshot.Record(&protocol.ChatShell{ID: fmt.Sprintf("sh_%d", i), Status: protocol.ChatShellExited})
}
if len(snapshot.changes) != chatShellIdentityLimit {
t.Fatalf("unbounded journal: %d", len(snapshot.changes))
}
if _, err := snapshot.Merge([]protocol.ChatShell{{ID: "sh_0", Status: protocol.ChatShellRunning}}); err == nil {
t.Fatal("overflow accepted stale snapshot")
}
}
+72
View File
@@ -0,0 +1,72 @@
package opencode
import (
"fmt"
"sort"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// ShellSnapshot records changes while an authoritative read is in flight. Its
// owner serializes access. Unknown exits may be recorded, but can only remove an
// id: they never establish ownership. Overflow rejects the snapshot, not events.
type ShellSnapshot struct {
changes map[string]protocol.ChatShell
bytes int
overflow bool
}
const chatShellIdentityLimit = 256
func (s *ShellSnapshot) Record(shell *protocol.ChatShell) {
if s == nil || shell == nil || shell.ID == "" || s.overflow {
return
}
if s.changes == nil {
s.changes = make(map[string]protocol.ChatShell)
}
old := s.changes[shell.ID]
n := s.bytes - len(old.ID) - len(old.Command) + len(shell.ID) + len(shell.Command)
if n > MaxResponse || (old.ID == "" && len(s.changes) >= chatShellIdentityLimit) {
s.overflow = true
return
}
// A terminal event wins even if a duplicate create is delivered later.
if old.ID != "" && old.Status != protocol.ChatShellRunning {
return
}
s.changes[shell.ID] = *shell
s.bytes = n
}
func (s *ShellSnapshot) Merge(shells []protocol.ChatShell) ([]protocol.ChatShell, error) {
if s.overflow {
return nil, fmt.Errorf("shell reconciliation capacity exceeded")
}
byID := make(map[string]protocol.ChatShell)
for _, shell := range shells {
if shell.ID != "" && shell.Status == protocol.ChatShellRunning {
byID[shell.ID] = shell
}
}
for id, shell := range s.changes {
if shell.Status == protocol.ChatShellRunning {
byID[id] = shell
} else {
delete(byID, id)
}
}
if len(byID) > chatShellIdentityLimit {
return nil, fmt.Errorf("shell reconciliation capacity exceeded")
}
ids := make([]string, 0, len(byID))
for id := range byID {
ids = append(ids, id)
}
sort.Strings(ids)
out := make([]protocol.ChatShell, 0, len(ids))
for _, id := range ids {
out = append(out, byID[id])
}
return out, nil
}
+42
View File
@@ -395,3 +395,45 @@ func TestOpenChatRejectsUnrunnableCLI(t *testing.T) {
t.Fatal("a missing CLI must fail detection, not open an endpoint")
}
}
// TestChatShellReadbackSeedsReplacementStream proves an authoritative shell
// readback survives a later stream replacement: shell.exited has no session id,
// so it must still clear the verified shell after reconnect.
func TestChatShellReadbackSeedsReplacementStream(t *testing.T) {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/api/shell":
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(`{"data":[{"id":"sh_1","status":"running","command":"sleep 30","metadata":{"sessionID":"ses_1"}},{"id":"sh_other","status":"running","command":"sleep 30","metadata":{"sessionID":"ses_other"}}]}`))
case "/api/event":
w.Header().Set("Content-Type", "text/event-stream")
_, _ = w.Write([]byte("data: {\"type\":\"shell.exited\",\"data\":{\"id\":\"sh_1\",\"status\":\"exited\",\"exit\":0}}\n\n"))
}
}))
defer srv.Close()
chat := NewChat(&Connection{Backend: "v2", URL: srv.URL})
shells, err := chat.Shells(context.Background(), "ses_1")
if err != nil || len(shells) != 1 || shells[0].ID != "sh_1" {
t.Fatalf("Shells = %+v, %v", shells, err)
}
var got []protocol.ChatEventFrame
if err := chat.Stream(context.Background(), "ses_1", nil, func(frame protocol.ChatEventFrame) error { got = append(got, frame); return nil }); err != nil {
t.Fatal(err)
}
if len(got) != 1 || got[0].Shell == nil || got[0].Shell.ID != "sh_1" || got[0].Shell.Status != protocol.ChatShellExited {
t.Fatalf("exit after readback = %+v", got)
}
}
func TestChatReleaseShellsBoundsDisconnectedState(t *testing.T) {
chat := NewChat(&Connection{})
state := chat.streamState("ses_1")
state.markShell("sh_1")
chat.ReleaseShells("ses_1")
chat.shellMu.Lock()
_, retained := chat.shells["ses_1"]
chat.shellMu.Unlock()
if retained {
t.Fatal("released session shell state was retained")
}
}