transcript

package
v0.3.0-beta.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 4, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source
const (
	MarkerPromptCancel           = "transcript_marker.prompt_cancel"
	MarkerPromptTimeout          = "transcript_marker.prompt_timeout"
	MarkerPromptInterrupted      = "transcript_marker.prompt_interrupted"
	MarkerPromptSteered          = "transcript_marker.prompt_steered"
	MarkerPromptQueued           = "transcript_marker.prompt_queued"
	MarkerPromptAccepted         = "transcript_marker.prompt_accepted"
	MarkerPromptDropped          = "transcript_marker.prompt_dropped"
	MarkerSessionUnhealthy       = "transcript_marker.session_unhealthy"
	MarkerSessionRecovered       = "transcript_marker.session_recovered"
	MarkerProviderFailure        = "transcript_marker.provider_failure"
	MarkerMCPAuthRequired        = "transcript_marker.mcp_auth_required"
	MarkerFileMutationUnverified = "transcript_marker.file_mutation_unverified"
)
View Source
const (
	UIRoleSystem    = "system"
	UIRoleUser      = "user"
	UIRoleAssistant = "assistant"
)
View Source
const CanonicalSchema = "compozy.session.event.v1"

CanonicalSchema is the stored envelope schema for transcript-aware session events.

View Source
const (
	// ProjectionVersion identifies the deterministic transcript projection contract.
	ProjectionVersion = 1
)

Variables

View Source
var (
	// ErrProjectionCorrupt reports materialized transcript data that cannot be decoded.
	ErrProjectionCorrupt = errors.New("transcript: materialized projection is corrupt")
	// ErrProjectionIncompatible reports a projection produced by an unsupported contract version.
	ErrProjectionIncompatible = errors.New("transcript: materialized projection is incompatible")
)

Functions

func JoinUIMessageText

func JoinUIMessageText(messages []UIMessage) string

JoinUIMessageText joins visible text parts across all messages with newlines.

func MarshalAgentEvent

func MarshalAgentEvent(event acp.AgentEvent) (string, error)

MarshalAgentEvent converts a runtime ACP event into the canonical stored payload.

func MarshalPromptInputEvent

func MarshalPromptInputEvent(event acp.AgentEvent, authoredText string) (string, error)

MarshalPromptInputEvent preserves the exact authored text alongside the effective input sent through prompt hooks.

func RedactAgentEvent

func RedactAgentEvent(event acp.AgentEvent) acp.AgentEvent

RedactAgentEvent removes displayable secret material before an ACP event is stored, replayed, or streamed to a caller.

func UIMessageText

func UIMessageText(message UIMessage) string

UIMessageText returns the concatenated visible text parts for one UI message.

func UnmarshalAgentEvent

func UnmarshalAgentEvent(payload string) (acp.AgentEvent, error)

UnmarshalAgentEvent converts a canonical stored payload back into an ACP event.

Types

type Assembler

type Assembler interface {
	Assemble(events []store.SessionEvent) ([]Message, error)
}

Assembler assembles persisted session events into the canonical transcript shape.

type Assignment

type Assignment struct {
	Entry         EntryIdentity
	CompletedKeys []string
	ToolKey       string
}

Assignment binds one canonical event to its stable logical entry.

type ChangePage

type ChangePage struct {
	Entries     []Entry `json:"entries"`
	Generation  int64   `json:"generation"`
	MaxSequence int64   `json:"max_sequence"`
	HasMore     bool    `json:"has_more"`
	NextAfter   int64   `json:"next_after_sequence,omitempty"`
}

ChangePage is one bounded set of entries shaped by events after a cursor.

type ChangeQuery

type ChangeQuery struct {
	AfterSequence int64
	Limit         int
}

ChangeQuery selects materialized entries updated after an event cursor.

func (ChangeQuery) Normalize

func (q ChangeQuery) Normalize() (ChangeQuery, error)

Normalize validates and applies bounded defaults to a change query.

type Entry

type Entry struct {
	Message       UIMessage `json:"message"`
	StartSequence int64     `json:"start_sequence"`
	Sequence      int64     `json:"sequence"`
	EventType     string    `json:"-"`
	Marker        *Marker   `json:"-"`
}

Entry pairs a UI message with the event sequence that last shaped it.

func CloneEntries

func CloneEntries(entries []Entry) []Entry

CloneEntries returns an isolated copy of sequence-bearing UI messages.

func ProjectAssignedEntry

func ProjectAssignedEntry(events []store.SessionEvent, identity EntryIdentity) (*Entry, error)

ProjectAssignedEntry reduces only the raw events assigned to one stable entry.

func ToUIEntries

func ToUIEntries(events []store.SessionEvent) ([]Entry, error)

ToUIEntries projects persisted session events into sequence-bearing AI SDK messages.

type EntryIdentity

type EntryIdentity struct {
	Key             string
	Kind            EntryKind
	LogicalID       string
	TurnID          string
	BaseMessageID   string
	MessageID       string
	StartSequence   int64
	UpdatedSequence int64
	Complete        bool
}

EntryIdentity is the stable metadata for one logical transcript segment.

type EntryKind

type EntryKind string

EntryKind classifies one independently materialized transcript segment.

const (
	EntryKindAssistant EntryKind = "assistant"
	EntryKindUser      EntryKind = "user"
	EntryKindSystem    EntryKind = "system"
	EntryKindMarker    EntryKind = "marker"
)

type Marker

type Marker struct {
	Kind       string          `json:"kind"`
	OccurredAt time.Time       `json:"occurred_at"`
	Summary    string          `json:"summary"`
	Evidence   map[string]any  `json:"evidence,omitempty"`
	Diagnostic json.RawMessage `json:"diagnostic,omitempty"`
}

Marker is the canonical transcript marker payload persisted as a typed event.

func NewMarker

func NewMarker(kind string, summary string, occurredAt time.Time, evidence map[string]any) (Marker, error)

NewMarker builds a redacted marker payload from daemon-owned runtime evidence.

func ParseMarker

func ParseMarker(raw json.RawMessage) (Marker, bool)

ParseMarker decodes and validates a persisted marker payload.

func (Marker) AgentEvent

func (m Marker) AgentEvent(sessionID string, turnID string) (acp.AgentEvent, error)

AgentEvent converts the marker to the durable transcript marker event shape.

func (Marker) Normalize

func (m Marker) Normalize() Marker

Normalize returns a redacted, UTC-normalized marker copy.

func (Marker) Validate

func (m Marker) Validate() error

Validate ensures the marker is one of the closed runtime marker vocabulary.

type Message

type Message struct {
	ID               string          `json:"id"`
	Role             Role            `json:"role"`
	Content          string          `json:"content"`
	Thinking         string          `json:"thinking,omitempty"`
	ThinkingComplete bool            `json:"thinking_complete"`
	ToolName         string          `json:"tool_name,omitempty"`
	ToolInput        json.RawMessage `json:"tool_input,omitempty"`
	ToolResult       *ToolResult     `json:"tool_result,omitempty"`
	ToolError        bool            `json:"tool_error"`
	Timestamp        time.Time       `json:"timestamp"`
}

Message is the canonical replay message returned to transport callers.

func Assemble

func Assemble(events []store.SessionEvent) ([]Message, error)

Assemble returns the canonical replay transcript for the provided persisted events.

func Prune

func Prune(messages []Message, opts PruneOptions) []Message

Prune returns an isolated transcript projection with bounded tool noise.

type Page

type Page struct {
	Entries            []Entry `json:"entries"`
	Generation         int64   `json:"generation"`
	MaxSequence        int64   `json:"max_sequence"`
	HasOlder           bool    `json:"has_older"`
	NextBeforeSequence int64   `json:"next_before_sequence,omitempty"`
}

Page is one bounded chronological transcript window.

type PageQuery

type PageQuery struct {
	BeforeSequence int64
	Limit          int
}

PageQuery selects one bounded chronological window ending before a stable start cursor.

func (PageQuery) Normalize

func (q PageQuery) Normalize() (PageQuery, error)

Normalize validates and applies bounded defaults to a page query.

type Projection

type Projection struct {
	Segments       []ProjectionSegment
	EventEntryKeys map[string]string
	ToolRoutes     map[string]string
	State          ProjectionState
}

Projection is a complete deterministic materialization of canonical events.

func BuildProjection

func BuildProjection(events []store.SessionEvent, generation int64) (Projection, error)

BuildProjection routes and reduces a complete event log with the canonical projector.

type ProjectionResolver

type ProjectionResolver interface {
	EntryIdentity(context.Context, string) (EntryIdentity, bool, error)
	ToolEntryIdentity(context.Context, string) (EntryIdentity, bool, error)
	LatestAssistantIdentity(context.Context, string) (EntryIdentity, bool, error)
}

ProjectionResolver resolves durable routing identities without replaying history.

type ProjectionSegment

type ProjectionSegment struct {
	Identity EntryIdentity
	Events   []store.SessionEvent
	Entry    *Entry
}

ProjectionSegment is one complete rebuildable materialized entry.

type ProjectionState

type ProjectionState struct {
	Version        int
	Generation     int64
	ActiveEntryKey string
}

ProjectionState is the durable routing state for incremental projection.

type Projector

type Projector struct {
	// contains filtered or unexported fields
}

Projector routes ordered events to deterministic, independently rebuildable entries.

func NewProjector

func NewProjector(state ProjectionState, resolver ProjectionResolver) (*Projector, error)

NewProjector starts an incremental projection from durable routing state.

func (*Projector) Assign

func (p *Projector) Assign(ctx context.Context, stored store.SessionEvent) (Assignment, error)

Assign binds one ordered, sequenced event to a stable logical entry.

func (*Projector) Identity

func (p *Projector) Identity(key string) (EntryIdentity, bool)

Identity returns the latest metadata for an entry touched by this projector.

func (*Projector) State

func (p *Projector) State() ProjectionState

State returns the routing state after all assigned events.

func (*Projector) ToolRoutes

func (p *Projector) ToolRoutes() map[string]string

ToolRoutes returns tool lifecycle routes learned by this projector.

type PruneOptions

type PruneOptions struct {
	MaxToolResultLines int
	MaxArgBytes        int
	Dedup              bool
}

PruneOptions bounds deterministic transcript pruning.

type Reader

type Reader interface {
	TranscriptPage(context.Context, PageQuery) (Page, error)
	TranscriptChanges(context.Context, ChangeQuery) (ChangePage, error)
}

Reader exposes proportional transcript page and change reads.

type Role

type Role string

Role is the renderable chat role emitted by the canonical transcript API.

const (
	RoleUser       Role = "user"
	RoleAssistant  Role = "assistant"
	RoleToolCall   Role = "tool_call"
	RoleToolResult Role = "tool_result"
	RoleSystem     Role = "system"
)

type ToolResult

type ToolResult struct {
	Stdout          string          `json:"stdout,omitempty"`
	Stderr          string          `json:"stderr,omitempty"`
	FilePath        string          `json:"file_path,omitempty"`
	Content         string          `json:"content,omitempty"`
	StructuredPatch json.RawMessage `json:"structured_patch,omitempty"`
	Error           string          `json:"error,omitempty"`
	RawOutput       json.RawMessage `json:"raw_output,omitempty"`
}

ToolResult is the canonical renderable tool output shape for replay.

type UIAgentEventPayload

type UIAgentEventPayload struct {
	Type             string                `json:"type"`
	SessionID        string                `json:"session_id,omitempty"`
	TurnID           string                `json:"turn_id,omitempty"`
	RequestID        string                `json:"request_id,omitempty"`
	Timestamp        string                `json:"timestamp,omitempty"`
	Text             string                `json:"text,omitempty"`
	Title            string                `json:"title,omitempty"`
	ToolCallID       string                `json:"tool_call_id,omitempty"`
	StopReason       string                `json:"stop_reason,omitempty"`
	PromptStopReason acp.PromptStopReason  `json:"prompt_stop_reason,omitempty"`
	Action           string                `json:"action,omitempty"`
	Resource         string                `json:"resource,omitempty"`
	Decision         string                `json:"decision,omitempty"`
	Error            string                `json:"error,omitempty"`
	Failure          *store.SessionFailure `json:"failure,omitempty"`
	Goal             *acp.GoalPromptMeta   `json:"goal,omitempty"`
	Usage            *UITokenUsagePayload  `json:"usage,omitempty"`
	Runtime          *acp.RuntimeActivity  `json:"runtime,omitempty"`
	Raw              json.RawMessage       `json:"raw,omitempty"`
}

UIAgentEventPayload mirrors the prompt-stream data payload shape.

func UIAgentEventPayloadFromEvent

func UIAgentEventPayloadFromEvent(event acp.AgentEvent) UIAgentEventPayload

UIAgentEventPayloadFromEvent converts an ACP event into the prompt-stream data payload.

type UIMessage

type UIMessage struct {
	ID       string          `json:"id"`
	Role     string          `json:"role"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
	Parts    []UIMessagePart `json:"parts"`
}

UIMessage mirrors the AI SDK UIMessage wire shape used by the web client.

func MessagesFromEntries

func MessagesFromEntries(entries []Entry) []UIMessage

MessagesFromEntries returns the UI messages carried by sequence-bearing entries.

func ToUIMessages

func ToUIMessages(events []store.SessionEvent) ([]UIMessage, error)

ToUIMessages projects persisted session events into AI SDK UIMessage objects.

type UIMessagePart

type UIMessagePart struct {
	Type        string          `json:"type"`
	ID          string          `json:"id,omitempty"`
	Text        string          `json:"text,omitempty"`
	State       string          `json:"state,omitempty"`
	ToolName    string          `json:"toolName,omitempty"`
	ToolCallID  string          `json:"toolCallId,omitempty"`
	Title       string          `json:"title,omitempty"`
	Input       json.RawMessage `json:"input,omitempty"`
	RawInput    json.RawMessage `json:"rawInput,omitempty"`
	Output      json.RawMessage `json:"output,omitempty"`
	ErrorText   string          `json:"errorText,omitempty"`
	Data        json.RawMessage `json:"data,omitempty"`
	Preliminary bool            `json:"preliminary,omitempty"`
}

UIMessagePart mirrors the AI SDK UIMessage part wire shape used by the web client.

type UITokenUsagePayload

type UITokenUsagePayload struct {
	TurnID           string   `json:"turn_id,omitempty"`
	InputTokens      *int64   `json:"input_tokens,omitempty"`
	OutputTokens     *int64   `json:"output_tokens,omitempty"`
	TotalTokens      *int64   `json:"total_tokens,omitempty"`
	ThoughtTokens    *int64   `json:"thought_tokens,omitempty"`
	CacheReadTokens  *int64   `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens *int64   `json:"cache_write_tokens,omitempty"`
	ContextUsed      *int64   `json:"context_used,omitempty"`
	ContextSize      *int64   `json:"context_size,omitempty"`
	CostAmount       *float64 `json:"cost_amount,omitempty"`
	CostCurrency     *string  `json:"cost_currency,omitempty"`
	Timestamp        string   `json:"timestamp,omitempty"`
}

UITokenUsagePayload mirrors the prompt-stream token usage payload.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL