promptkit/exchange.go

package promptkit

import "go.maximumdirect.net/promptkit/internal/domain"

const exchangeString = "promptkit.Exchange{opaque}"

// Exchange is an immutable, reusable in-process snapshot of a completed
// conversation. It is not a persistence or restart format. Different engines
// can continue it, and independent branches do not alter one another.
//
// History preserves the effective request's message content, roles, and cache
// metadata, followed by the exact final [RunResult.RawOutput] as an assistant
// message. Intermediate structural-repair candidates and corrective instructions
// are excluded. A continuation extends that logical history according to
// [RunRequest.ContinueFrom], without changing its source exchange.
type Exchange struct{ internal *domain.Exchange }

// ExchangeDetails contains a detached copy of an exchange's logical history.
type ExchangeDetails struct {
	// RunID identifies the execution that produced this exchange.
	RunID string `json:"run_id"`
	// ParentRunID identifies the immediate source execution, or is empty.
	ParentRunID string            `json:"parent_run_id,omitempty"`
	Messages    []RenderedMessage `json:"messages"`
}

// Details returns detached history, or zero details for a nil or empty handle.
// Messages include caller and model content and require appropriate handling.
// Inspection uses only retained state, without rendering, filesystem reads, or
// provider calls. Mutating returned messages or cache metadata cannot affect
// this exchange, another branch, or subsequent Details calls.
func (e *Exchange) Details() ExchangeDetails {
	if e == nil || e.internal == nil {
		return ExchangeDetails{}
	}
	return ExchangeDetails{RunID: e.internal.RunID(), ParentRunID: e.internal.ParentRunID(), Messages: fromDomainRenderedMessages(e.internal.Messages())}
}

// String returns an opaque representation without conversation content.
func (e Exchange) String() string { return exchangeString }

// GoString returns an opaque representation without conversation content.
func (e Exchange) GoString() string { return exchangeString }