Enforce runtime report contracts and recoverable session exports

This commit is contained in:
2026-10-20 16:02:38 +01:00
parent 1d9cb80cdb
commit fdf0369ede
36 changed files with 1636 additions and 177 deletions
+171 -60
View File
@@ -4,7 +4,9 @@ import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
@@ -15,6 +17,10 @@ import (
// never presented as the whole session.
const MaxSessionExport = 8 << 20
var ErrEmptySessionExport = errors.New("session recorded but native export contains no messages")
var errTransientExport = errors.New("native session export temporarily unavailable")
var errSessionIdentity = errors.New("native export session identity mismatch")
// nativeExportResult is one bounded `opencode export` readback. envelope is the
// stdout prefix the CLI wrote, capped at the caller's limit; truncated is true
// when the CLI wrote more than the cap, so the prefix is not valid whole JSON.
@@ -45,6 +51,15 @@ func exportNative(ctx context.Context, executable, directory, backend, id string
cmd.Stdout = stdout
cmd.Stderr = stderr
if err := cmd.Run(); err != nil {
// Only known temporary transport/store failures are retried. Do not
// expose stderr: it may contain session text or credentials.
text := strings.ToLower(string(stderr.Bytes()))
for _, temporary := range []string{"temporarily unavailable", "connection refused", "database is locked", "server is busy"} {
if strings.Contains(text, temporary) {
err = errors.Join(errTransientExport, err)
break
}
}
return nativeExportResult{envelope: stdout.Bytes(), truncated: stdout.overflow}, err
}
return nativeExportResult{envelope: stdout.Bytes(), truncated: stdout.overflow}, nil
@@ -52,18 +67,47 @@ func exportNative(ctx context.Context, executable, directory, backend, id string
// validNativeExport is the exact-ID and messages-array validation
// Connection.Messages and ExportSession share: the envelope must parse, carry an
// info.id equal to wantID and a non-empty JSON messages array.
// info.id equal to wantID and a JSON messages array. An empty array is valid
// readback syntax, not complete evidence; consumers must label it empty.
func validNativeExport(data []byte, wantID string) (json.RawMessage, bool) {
var envelope struct {
Info struct {
ID string `json:"id"`
} `json:"info"`
Messages json.RawMessage `json:"messages"`
Data json.RawMessage `json:"data"`
}
if json.Unmarshal(data, &envelope) != nil || envelope.Info.ID != wantID || len(envelope.Messages) == 0 || envelope.Messages[0] != '[' {
if json.Unmarshal(data, &envelope) != nil {
return nil, false
}
return envelope.Messages, true
// The HTTP/CLI readback can wrap a payload in data. Only unwrap an
// otherwise absent envelope, never use data to override a mismatched ID.
if envelope.Info.ID == "" && len(envelope.Messages) == 0 && len(envelope.Data) > 0 {
if json.Unmarshal(envelope.Data, &envelope) != nil {
return nil, false
}
}
if envelope.Info.ID != wantID || len(envelope.Messages) == 0 {
return nil, false
}
messages := bytes.TrimSpace(envelope.Messages)
if len(messages) > 0 && messages[0] == '{' {
var wrapped struct {
Data json.RawMessage `json:"data"`
}
if json.Unmarshal(messages, &wrapped) != nil {
return nil, false
}
messages = bytes.TrimSpace(wrapped.Data)
}
if len(messages) == 0 || messages[0] != '[' {
return nil, false
}
var records []json.RawMessage
if json.Unmarshal(messages, &records) != nil {
return nil, false
}
return messages, true
}
// ExportedPart is one decoded content element of an exported session. Raw keeps
@@ -94,6 +138,7 @@ type ExportedMessage struct {
// export. Truncated is true when the source exceeded MaxSessionExport; Messages
// then covers the complete turns decoded before the cut.
type ExportedSession struct {
Attempts int
ID string
Backend string
Messages []ExportedMessage
@@ -105,68 +150,123 @@ type ExportedSession struct {
// decodes the v1/v2 message and part shapes through chatMessageRecords and, when
// the source exceeded MaxSessionExport, streams the complete turns decoded from
// the bounded prefix and reports Truncated instead of failing. It performs no
// writes, no resumption, no idleness wait and no retries.
// writes, no resumption and no idleness wait. Empty readbacks and explicitly
// temporary failures get at most three attempts within the caller's deadline;
// wrong identity and permanent failures never retry.
func ExportSession(ctx context.Context, executable, directory, backend, id string) (ExportedSession, error) {
if !sessionID.MatchString(id) {
return ExportedSession{}, fmt.Errorf("invalid session ID")
}
exported, err := exportNative(ctx, executable, directory, backend, id, MaxSessionExport)
if err != nil {
if ctx.Err() != nil {
return ExportedSession{}, ctx.Err()
}
return ExportedSession{}, fmt.Errorf("native session export failed: %w", err)
}
session := ExportedSession{ID: id, Backend: backend}
if !exported.truncated {
messages, ok := validNativeExport(exported.envelope, id)
if !ok {
// The CLI can observe a session whose final write is still landing
// (the stage just settled). One short, bounded retry recovers the
// session evidence instead of dropping session.html for the stage.
timer := time.NewTimer(200 * time.Millisecond)
select {
case <-ctx.Done():
timer.Stop()
return ExportedSession{}, ctx.Err()
case <-timer.C:
}
retried, retryErr := exportNative(ctx, executable, directory, backend, id, MaxSessionExport)
if retryErr != nil {
if ctx.Err() != nil {
return ExportedSession{}, ctx.Err()
}
return ExportedSession{}, fmt.Errorf("native session export failed: %w", retryErr)
}
exported = retried
if !exported.truncated {
messages, ok = validNativeExport(exported.envelope, id)
if !ok {
return ExportedSession{}, fmt.Errorf("native export returned invalid or mismatched session evidence")
}
}
}
if !exported.truncated {
records, err := chatMessageRecords(messages)
if err != nil {
return ExportedSession{}, err
}
session.Messages = exportedMessages(records)
for attempt := 0; attempt < 3; attempt++ {
session, err := exportSessionOnce(ctx, executable, directory, backend, id)
session.Attempts = attempt + 1
if err == nil {
return session, nil
}
if ctx.Err() != nil {
return session, ctx.Err()
}
if attempt == 2 || (!errors.Is(err, ErrEmptySessionExport) && !errors.Is(err, errTransientExport)) {
return session, err
}
// Bounded recovery, not a causal claim about why readback was empty.
timer := time.NewTimer(time.Duration(attempt+1) * 200 * time.Millisecond)
select {
case <-ctx.Done():
timer.Stop()
return session, ctx.Err()
case <-timer.C:
}
}
// The source exceeded the cap, so the session is larger than what was read
// and must never be presented as whole. The prefix still yields every turn
// that decoded before the cut.
records, _, err := decodeExportPrefix(exported.envelope, id)
panic("unreachable")
}
func exportSessionOnce(ctx context.Context, executable, directory, backend, id string) (ExportedSession, error) {
session := ExportedSession{ID: id, Backend: backend}
exported, err := exportNative(ctx, executable, directory, backend, id, MaxSessionExport)
if err != nil {
return ExportedSession{}, err
return session, fmt.Errorf("native session export failed: %w", err)
}
if exported.truncated {
records, _, err := decodeExportPrefix(exported.envelope, id)
if err != nil {
return session, err
}
session.Messages, session.Truncated = exportedMessages(records), true
if len(session.Messages) == 0 {
return session, ErrEmptySessionExport
}
return session, nil
}
messages, ok := validNativeExport(exported.envelope, id)
if !ok {
// Incomplete JSON is a possible interrupted read; valid but wrong
// identity/schema is permanent and must never be retried as settling.
var syntax *json.SyntaxError
var envelope struct {
Info struct {
ID string `json:"id"`
} `json:"info"`
Data json.RawMessage `json:"data"`
}
if err := json.Unmarshal(exported.envelope, &envelope); err != nil {
identity := exportPrefixIdentity(exported.envelope)
if identity != "" && identity != id {
return session, errSessionIdentity
}
if identity == id && errors.As(err, &syntax) && strings.Contains(syntax.Error(), "unexpected end") {
return session, errTransientExport
}
return session, fmt.Errorf("native export returned invalid session evidence")
}
if envelope.Info.ID == "" && len(envelope.Data) > 0 {
_ = json.Unmarshal(envelope.Data, &envelope)
}
if envelope.Info.ID != "" && envelope.Info.ID != id {
return session, errSessionIdentity
}
return session, fmt.Errorf("native export returned unsupported or missing session evidence")
}
records, err := chatMessageRecords(messages)
if err != nil {
return session, err
}
session.Messages = exportedMessages(records)
session.Truncated = true
if len(session.Messages) == 0 {
return session, ErrEmptySessionExport
}
return session, nil
}
// exportPrefixIdentity reads only complete metadata preceding an interrupted
// messages array. A known wrong session is permanent even when JSON is cut.
func exportPrefixIdentity(data []byte) string {
decoder := json.NewDecoder(bytes.NewReader(data))
if token, err := decoder.Token(); err != nil || token != json.Delim('{') {
return ""
}
for decoder.More() {
token, err := decoder.Token()
if err != nil {
return ""
}
if token == "info" {
var info struct {
ID string `json:"id"`
}
if decoder.Decode(&info) == nil {
return info.ID
}
return ""
}
var skip json.RawMessage
if decoder.Decode(&skip) != nil {
return ""
}
}
return ""
}
// exportedMessages maps decoded native turns onto ExportedMessage, preserving
// every role and each part's raw JSON for unknown types.
func exportedMessages(records []nativeChatMessage) []ExportedMessage {
@@ -209,10 +309,17 @@ func decodeExportPrefix(data []byte, wantID string) ([]nativeChatMessage, bool,
}
var messages []nativeChatMessage
sawMessages := false
sawIdentity := false
partial := func() ([]nativeChatMessage, bool, error) {
if !sawIdentity {
return nil, false, fmt.Errorf("native export prefix has no verified session identity")
}
return messages, true, nil
}
for decoder.More() {
keyToken, err := decoder.Token()
if err != nil {
return messages, true, nil
return partial()
}
key, _ := keyToken.(string)
switch key {
@@ -221,16 +328,17 @@ func decodeExportPrefix(data []byte, wantID string) ([]nativeChatMessage, bool,
ID string `json:"id"`
}
if err := decoder.Decode(&info); err != nil {
return messages, true, nil
return partial()
}
if info.ID != "" && info.ID != wantID {
if info.ID != wantID {
return nil, false, fmt.Errorf("native export session id mismatch")
}
sawIdentity = true
case "messages":
sawMessages = true
open, err := decoder.Token()
if err != nil {
return messages, true, nil
return partial()
}
if delim, ok := open.(json.Delim); !ok || delim != '[' {
return nil, false, fmt.Errorf("native export returned invalid session evidence")
@@ -238,25 +346,28 @@ func decodeExportPrefix(data []byte, wantID string) ([]nativeChatMessage, bool,
for decoder.More() {
var message nativeChatMessage
if err := decoder.Decode(&message); err != nil {
return messages, true, nil
return partial()
}
messages = append(messages, message)
}
if _, err := decoder.Token(); err != nil {
return messages, true, nil
return partial()
}
default:
var skip json.RawMessage
if err := decoder.Decode(&skip); err != nil {
return messages, true, nil
return partial()
}
}
}
if !sawMessages {
return nil, false, fmt.Errorf("native export returned no session messages")
}
if !sawIdentity {
return nil, false, fmt.Errorf("native export prefix has no verified session identity")
}
if _, err := decoder.Token(); err != nil {
return messages, true, nil
return partial()
}
return messages, false, nil
}