server: export a finished stage's real session as session.md and session.html
Every OpenCode-harness model stage now writes its real session into its own step artifacts directory as session.md and session.html, so the existing bounded artifact listing, the /artifacts/<run>/<step>/<name> serving path and the artifact scan find and serve them with no special casing, while the stage keeps its bounded preview in the run record unchanged. - internal/opencode/export.go adds the one shared native export invocation and the exact session-ID/messages validation used by both Connection.Messages and the new ExportSession, so the readback path does not diverge. The backend's published subcommand is used (v1 `export <id>`, v2 `session export <id>`), the source read is capped at 8 MiB, and a larger session is read as a prefix and reported truncated instead of failing. boundedOutput.ReadFrom keeps the cap effective so overflow and the truncation path are real. - internal/stage/session_export.go renders markdown and html with a metadata header, every role and every part (unknown part types as raw JSON, every session text escaped in html), atomic temp+rename writes that never overwrite an existing file, a visible truncation banner at both ends when the source or the 2 MiB rendered cap cuts it, and an honest 0-message header for an empty session rather than fabricated text. - protocol.SessionExport and RunStep.SessionExport are stored in a new step_session_exports table (CREATE TABLE IF NOT EXISTS, so an old database gains an empty table with no migration) loaded through the existing main SELECT alongside the other per-step evidence and deleted by run retention. - internal/server/runner.go exports after the post-stage filediff capture and before scanArtifacts, with context.WithTimeout(context.WithoutCancel(ctx), 10s); it never waits for session idleness and a failure or a Pi stage (no native export path) records a sanitized diagnostic and continues, never changing the stage status, outcome, target, timing or result validation. Reflected where it belongs: the packaged skill references (internal/author/skill/references/operations.md and delivery.md) carry the new Session export rules and the run-artifacts bullet, and docs/stage-artifacts.md documents the names, the <run>/<step> paths, the served URL, the caps, the truncation labels, failure isolation and the Pi limitation. The packaged templates (examples/*.md) only tell a stage to save its own artifacts and say nothing about the server-written session export, so none needed updating; no new reference file was added, so install.go's managed inventory is unchanged. Shared documentation: README.md's per-step artifacts sentence is now stale - it should name the exported session alongside images, screenshots, reports and logs. It is deliberately not committed here; the shared documents are folded by the single documentation writer. Checks: gofmt -l on the touched packages produced no output; go vet ./... passed; go test -race -count=1 ./... passed.
This commit is contained in:
@@ -0,0 +1,236 @@
|
||||
package opencode
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
|
||||
"git.a-wan.net/alan/pipelines/internal/protocol"
|
||||
)
|
||||
|
||||
// MaxSessionExport bounds the native session readback used for the stage session
|
||||
// export. A larger session is read as a bounded prefix and reported truncated,
|
||||
// never presented as the whole session.
|
||||
const MaxSessionExport = 8 << 20
|
||||
|
||||
// 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.
|
||||
type nativeExportResult struct {
|
||||
envelope []byte
|
||||
truncated bool
|
||||
}
|
||||
|
||||
// exportNative runs the read-only session export CLI once with stdout capped at
|
||||
// limit bytes. It is the single export invocation shared by Connection.Messages
|
||||
// and ExportSession; the returned envelope is validated by the one
|
||||
// validNativeExport check both call. The subcommand follows the backend's
|
||||
// published interface: the native v1 CLI exposes top-level `export <id>`, while
|
||||
// the installed v2 CLI exposes it as `session export <id>`. It never writes to,
|
||||
// resumes or mutates the session, and it does not wait for session idleness.
|
||||
func exportNative(ctx context.Context, executable, directory, backend, id string, limit int) (nativeExportResult, error) {
|
||||
if !sessionID.MatchString(id) {
|
||||
return nativeExportResult{}, fmt.Errorf("invalid session ID")
|
||||
}
|
||||
args := []string{"export", id}
|
||||
if backend == "v2" {
|
||||
args = []string{"session", "export", id}
|
||||
}
|
||||
cmd := CommandContext(ctx, executable, args...)
|
||||
cmd.Dir = directory
|
||||
stdout := &boundedOutput{limit: limit}
|
||||
stderr := &boundedOutput{limit: 8 << 10}
|
||||
cmd.Stdout = stdout
|
||||
cmd.Stderr = stderr
|
||||
if err := cmd.Run(); err != nil {
|
||||
return nativeExportResult{envelope: stdout.Bytes(), truncated: stdout.overflow}, err
|
||||
}
|
||||
return nativeExportResult{envelope: stdout.Bytes(), truncated: stdout.overflow}, nil
|
||||
}
|
||||
|
||||
// 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.
|
||||
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"`
|
||||
}
|
||||
if json.Unmarshal(data, &envelope) != nil || envelope.Info.ID != wantID || len(envelope.Messages) == 0 || envelope.Messages[0] != '[' {
|
||||
return nil, false
|
||||
}
|
||||
return envelope.Messages, true
|
||||
}
|
||||
|
||||
// ExportedPart is one decoded content element of an exported session. Raw keeps
|
||||
// the part's original JSON so an unrecognised type is rendered rather than
|
||||
// silently dropped; State carries a tool call's status, input, result and error.
|
||||
type ExportedPart struct {
|
||||
Type string
|
||||
ID string
|
||||
Text string
|
||||
Name string
|
||||
State *protocol.ChatToolState
|
||||
Time *protocol.ChatTime
|
||||
Raw json.RawMessage
|
||||
}
|
||||
|
||||
// ExportedMessage is one decoded turn. Every role is kept, not only
|
||||
// user/assistant, so the export is the session the harness stored.
|
||||
type ExportedMessage struct {
|
||||
ID string
|
||||
Role string
|
||||
Model string
|
||||
Agent string
|
||||
CreatedAt int64
|
||||
Parts []ExportedPart
|
||||
}
|
||||
|
||||
// ExportedSession is one bounded native session readback for the stage session
|
||||
// export. Truncated is true when the source exceeded MaxSessionExport; Messages
|
||||
// then covers the complete turns decoded before the cut.
|
||||
type ExportedSession struct {
|
||||
ID string
|
||||
Backend string
|
||||
Messages []ExportedMessage
|
||||
Truncated bool
|
||||
}
|
||||
|
||||
// ExportSession reads the session's native export read-only and decodes it into
|
||||
// ExportedSession. It reuses the shared export invocation and exact-ID check,
|
||||
// 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.
|
||||
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 {
|
||||
return ExportedSession{}, fmt.Errorf("native export returned invalid or mismatched session evidence")
|
||||
}
|
||||
records, err := chatMessageRecords(messages)
|
||||
if err != nil {
|
||||
return ExportedSession{}, err
|
||||
}
|
||||
session.Messages = exportedMessages(records)
|
||||
return session, nil
|
||||
}
|
||||
// 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)
|
||||
if err != nil {
|
||||
return ExportedSession{}, err
|
||||
}
|
||||
session.Messages = exportedMessages(records)
|
||||
session.Truncated = true
|
||||
return session, nil
|
||||
}
|
||||
|
||||
// exportedMessages maps decoded native turns onto ExportedMessage, preserving
|
||||
// every role and each part's raw JSON for unknown types.
|
||||
func exportedMessages(records []nativeChatMessage) []ExportedMessage {
|
||||
messages := make([]ExportedMessage, 0, len(records))
|
||||
for _, record := range records {
|
||||
message := ExportedMessage{
|
||||
ID: record.messageID(),
|
||||
Role: record.role(),
|
||||
Model: record.modelID(),
|
||||
Agent: record.agent(),
|
||||
CreatedAt: record.createdAt(),
|
||||
}
|
||||
for _, part := range record.contentParts() {
|
||||
message.Parts = append(message.Parts, ExportedPart{
|
||||
Type: part.Type, ID: part.ID, Text: part.Text, Name: part.Name,
|
||||
State: part.State, Time: part.Time, Raw: part.Raw,
|
||||
})
|
||||
}
|
||||
// A v2 user turn carries its prompt text as a message-level string rather
|
||||
// than a content array, so surface it as the turn's single text part.
|
||||
if len(message.Parts) == 0 && message.Role == protocol.ChatRoleUser && record.Text != "" {
|
||||
message.Parts = append(message.Parts, ExportedPart{Type: protocol.ChatPartText, Text: record.Text})
|
||||
}
|
||||
messages = append(messages, message)
|
||||
}
|
||||
return messages
|
||||
}
|
||||
|
||||
// decodeExportPrefix streams the messages of a bounded export prefix. Complete
|
||||
// turns decoded before the cut are returned with truncated=true; a mismatched
|
||||
// info.id is an error so an unrelated session is never exported.
|
||||
func decodeExportPrefix(data []byte, wantID string) ([]nativeChatMessage, bool, error) {
|
||||
decoder := json.NewDecoder(bytes.NewReader(data))
|
||||
open, err := decoder.Token()
|
||||
if err != nil {
|
||||
return nil, false, fmt.Errorf("native export returned invalid session evidence")
|
||||
}
|
||||
if delim, ok := open.(json.Delim); !ok || delim != '{' {
|
||||
return nil, false, fmt.Errorf("native export returned invalid session evidence")
|
||||
}
|
||||
var messages []nativeChatMessage
|
||||
sawMessages := false
|
||||
for decoder.More() {
|
||||
keyToken, err := decoder.Token()
|
||||
if err != nil {
|
||||
return messages, true, nil
|
||||
}
|
||||
key, _ := keyToken.(string)
|
||||
switch key {
|
||||
case "info":
|
||||
var info struct {
|
||||
ID string `json:"id"`
|
||||
}
|
||||
if err := decoder.Decode(&info); err != nil {
|
||||
return messages, true, nil
|
||||
}
|
||||
if info.ID != "" && info.ID != wantID {
|
||||
return nil, false, fmt.Errorf("native export session id mismatch")
|
||||
}
|
||||
case "messages":
|
||||
sawMessages = true
|
||||
open, err := decoder.Token()
|
||||
if err != nil {
|
||||
return messages, true, nil
|
||||
}
|
||||
if delim, ok := open.(json.Delim); !ok || delim != '[' {
|
||||
return nil, false, fmt.Errorf("native export returned invalid session evidence")
|
||||
}
|
||||
for decoder.More() {
|
||||
var message nativeChatMessage
|
||||
if err := decoder.Decode(&message); err != nil {
|
||||
return messages, true, nil
|
||||
}
|
||||
messages = append(messages, message)
|
||||
}
|
||||
if _, err := decoder.Token(); err != nil {
|
||||
return messages, true, nil
|
||||
}
|
||||
default:
|
||||
var skip json.RawMessage
|
||||
if err := decoder.Decode(&skip); err != nil {
|
||||
return messages, true, nil
|
||||
}
|
||||
}
|
||||
}
|
||||
if !sawMessages {
|
||||
return nil, false, fmt.Errorf("native export returned no session messages")
|
||||
}
|
||||
if _, err := decoder.Token(); err != nil {
|
||||
return messages, true, nil
|
||||
}
|
||||
return messages, false, nil
|
||||
}
|
||||
Reference in New Issue
Block a user