transcript

package
v0.3.0-beta.35 Latest Latest
Warning

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

Go to latest
Published: Oct 18, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source
const (
	MarkerPromptCancel           = "transcript_marker.prompt_cancel"
	MarkerPromptTimeout          = "transcript_marker.prompt_timeout"
	MarkerPromptInterrupted      = "transcript_marker.prompt_interrupted"
	MarkerPromptSuperseded       = "transcript_marker.prompt_superseded"
	MarkerPromptSteered          = "transcript_marker.prompt_steered"
	MarkerPromptQueued           = "transcript_marker.prompt_queued"
	MarkerPromptAccepted         = "transcript_marker.prompt_accepted"
	MarkerPromptDropped          = "transcript_marker.prompt_dropped"
	MarkerQueueCleared           = "transcript_marker.queue_cleared"
	MarkerSessionUnhealthy       = "transcript_marker.session_unhealthy"
	MarkerPostStop               = "transcript_marker.post_stop"
	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"
	UIMessagePartTypeFile = "file"
)
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 = 3
)

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")
)
View Source
var ErrFoldOutOfOrder = errors.New("transcript: fold events must extend the applied sequence")

ErrFoldOutOfOrder reports an event that cannot extend an incremental fold.

Functions

func IsSessionPromptCall

func IsSessionPromptCall(stored store.SessionEvent) bool

IsSessionPromptCall reports a stored tool call of `compozy__session_prompt`, under any provider's name for the hosted tool.

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 NativeSubagentTitle

func NativeSubagentTitle(event acp.AgentEvent) string

NativeSubagentTitle prefers the task description as streamed tool arguments become available.

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 {
	MinSequence int64   `json:"min_sequence"`
	Entries     []Entry `json:"entries"`
	Generation  int64   `json:"generation"`
	MaxSequence int64   `json:"max_sequence"`
	HasMore     bool    `json:"has_more"`
	NextAfter   int64   `json:"next_after_sequence,omitzero"`
}

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 CompactionItem

type CompactionItem struct {
	Kind         string     `json:"kind"`
	CompactionID string     `json:"compaction_id"`
	Status       string     `json:"status"`
	Summary      string     `json:"summary,omitempty"`
	Error        string     `json:"error,omitempty"`
	StartedAt    time.Time  `json:"started_at"`
	EndedAt      *time.Time `json:"ended_at,omitzero"`
}

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 EntryFold

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

EntryFold incrementally reduces the events assigned to one assistant entry. Appending events in sequence order yields the same entry as ProjectAssignedEntry over the full assigned event list, so a long turn costs one decode per event instead of one replay of the whole turn per append.

func NewEntryFold

func NewEntryFold(identity EntryIdentity) (*EntryFold, error)

NewEntryFold starts an empty fold for an assistant entry identity.

func (*EntryFold) Append

func (f *EntryFold) Append(events []store.SessionEvent) error

Append applies events whose sequences extend the fold in ascending order. It rejects the whole batch before mutating the fold when any event would reorder the reduction.

func (*EntryFold) Applied

func (f *EntryFold) Applied() int

Applied returns the number of applied events.

func (*EntryFold) Entry

func (f *EntryFold) Entry(identity EntryIdentity) *Entry

Entry materializes the folded entry without mutating the fold.

func (*EntryFold) LastSequence

func (f *EntryFold) LastSequence() int64

LastSequence returns the highest applied event sequence.

func (*EntryFold) Matches

func (f *EntryFold) Matches(identity EntryIdentity) bool

Matches reports whether the fold was started for the same entry and message identity.

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"
	EntryKindCompaction EntryKind = "compaction"
)

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"`
	Attachments      []acp.EventAttachment `json:"attachments,omitempty"`
	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,omitzero"`
	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 NavigationReader interface {
	TranscriptSearch(context.Context, SearchQuery) (SearchResult, error)
	TranscriptOutline(context.Context) (OutlineResult, error)
}

NavigationReader queries the existing projection without loading a UI page window.

type OutlineEntry

type OutlineEntry struct {
	Sequence     int64     `json:"sequence"`
	TurnID       string    `json:"turn_id"`
	Preview      string    `json:"preview"`
	ReplyPreview string    `json:"reply_preview"`
	At           time.Time `json:"at"`
}

OutlineEntry is one operator message and its latest reply in the same turn.

type OutlineResult

type OutlineResult struct {
	Entries []OutlineEntry `json:"entries"`
}

OutlineResult contains the lightweight operator-message trail over retained history.

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,omitzero"`
}

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 SearchMatch

type SearchMatch struct {
	Sequence int64  `json:"sequence"`
	TurnID   string `json:"turn_id"`
	Role     string `json:"role"`
	Snippet  string `json:"snippet"`
	// PartIndex and Field identify the first matching field in the projected message.
	// They are additive navigation hints; older readers can continue using the entry cursor.
	PartIndex *int   `json:"part_index,omitzero"`
	Field     string `json:"field,omitempty"`
}

SearchMatch identifies a matching materialized message by its stable start cursor.

type SearchQuery

type SearchQuery struct {
	Query string
	Limit int
}

SearchQuery selects literal, case-insensitive matches across retained history.

func (SearchQuery) Normalize

func (q SearchQuery) Normalize() (SearchQuery, error)

Normalize applies the same bounded result limit as other transcript reads.

type SearchResult

type SearchResult struct {
	Matches   []SearchMatch `json:"matches"`
	Truncated bool          `json:"truncated"`
}

SearchResult reports whether additional matching messages were omitted.

type SessionMessageCards

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

SessionMessageCards projects the card of each event in one ordered stream the way the transcript entry does: a call's later events resolve against the card its earlier events named. The zero value is ready to use; it is not safe for concurrent use.

func (*SessionMessageCards) Card

Card returns the call's card after this event, or false when the event is not part of a session message the card can name yet.

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 {
	ParentToolCallID string                       `json:"parent_tool_call_id,omitempty"`
	ProviderToolName string                       `json:"provider_tool_name,omitempty"`
	CompactionID     string                       `json:"compaction_id,omitempty"`
	Status           string                       `json:"status,omitempty"`
	Summary          string                       `json:"summary,omitempty"`
	Terminal         bool                         `json:"terminal,omitzero"`
	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"`
	ResolvedBy       string                       `json:"resolved_by,omitempty"`
	Error            string                       `json:"error,omitempty"`
	Failure          *store.SessionFailure        `json:"failure,omitempty"`
	ProviderError    *acp.ProviderErrorDiagnostic `json:"provider_error,omitzero"`
	Goal             *acp.GoalPromptMeta          `json:"goal,omitempty"`
	Delivery         *acp.DeliveryManifest        `json:"delivery,omitzero"`
	Usage            *UITokenUsagePayload         `json:"usage,omitzero"`
	Runtime          *acp.RuntimeActivity         `json:"runtime,omitzero"`
	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 {
	ParentToolCallID string          `json:"parentToolCallId,omitempty"`
	Type             string          `json:"type"`
	ID               string          `json:"id,omitempty"`
	Text             string          `json:"text,omitempty"`
	MediaType        string          `json:"mediaType,omitempty"`
	URL              string          `json:"url,omitempty"`
	Filename         string          `json:"filename,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,omitzero"`
}

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

type UISessionMessagePayload

type UISessionMessagePayload struct {
	ToolCallID        string `json:"tool_call_id"`
	TargetSessionID   string `json:"target_session_id"`
	TargetWorkspaceID string `json:"target_workspace_id,omitempty"`
	MessageID         string `json:"message_id,omitempty"`
	Mode              string `json:"mode,omitempty"`
	Delivery          string `json:"delivery,omitempty"`
	SteerDelivery     string `json:"steer_delivery,omitempty"`
	ReplyWatchID      string `json:"reply_watch_id,omitempty"`
	InReplyTo         string `json:"in_reply_to,omitempty"`
	State             string `json:"state"`
}

func SessionMessagePartForStoredEvent

func SessionMessagePartForStoredEvent(stored store.SessionEvent) (UISessionMessagePayload, bool)

SessionMessagePartForStoredEvent projects one event on its own. It knows no earlier event of the call, so a result that names no tool (Codex) needs SessionMessageCards instead.

func (UISessionMessagePayload) WithFallback

type UISubagentPayload

type UISubagentPayload struct {
	SubagentID      string `json:"subagent_id"`
	ToolCallID      string `json:"tool_call_id"`
	TurnID          string `json:"turn_id"`
	Origin          string `json:"origin,omitempty"`
	Title           string `json:"title,omitempty"`
	RuntimeProvider string `json:"runtime_provider,omitempty"`
	RuntimeAgent    string `json:"runtime_agent,omitempty"`
	RuntimeModel    string `json:"runtime_model,omitempty"`
}

UISubagentPayload identifies the roster entry and supplies initial display hints.

func SubagentPartForStoredEvent

func SubagentPartForStoredEvent(stored store.SessionEvent) (UISubagentPayload, bool)

SubagentPartForStoredEvent is the card a committed or about-to-be-committed event projects, if any. Live surfaces (the prompt stream) use it so the card they emit is the one the transcript projection persists.

type UITokenUsagePayload

type UITokenUsagePayload struct {
	Meta             map[string]any `json:"meta,omitempty"`
	Sequence         *int64         `json:"sequence,omitzero"`
	TurnID           string         `json:"turn_id,omitempty"`
	InputTokens      *int64         `json:"input_tokens,omitzero"`
	OutputTokens     *int64         `json:"output_tokens,omitzero"`
	TotalTokens      *int64         `json:"total_tokens,omitzero"`
	ThoughtTokens    *int64         `json:"thought_tokens,omitzero"`
	CacheReadTokens  *int64         `json:"cache_read_tokens,omitzero"`
	CacheWriteTokens *int64         `json:"cache_write_tokens,omitzero"`
	ContextUsed      *int64         `json:"context_used,omitzero"`
	ContextSize      *int64         `json:"context_size,omitzero"`
	CostAmount       *float64       `json:"cost_amount,omitzero"`
	CostCurrency     *string        `json:"cost_currency,omitzero"`
	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