Documentation
¶
Index ¶
- Constants
- Variables
- func IsSessionPromptCall(stored store.SessionEvent) bool
- func JoinUIMessageText(messages []UIMessage) string
- func MarshalAgentEvent(event acp.AgentEvent) (string, error)
- func MarshalPromptInputEvent(event acp.AgentEvent, authoredText string) (string, error)
- func NativeSubagentTitle(event acp.AgentEvent) string
- func RedactAgentEvent(event acp.AgentEvent) acp.AgentEvent
- func UIMessageText(message UIMessage) string
- func UnmarshalAgentEvent(payload string) (acp.AgentEvent, error)
- type Assembler
- type Assignment
- type ChangePage
- type ChangeQuery
- type CompactionItem
- type Entry
- type EntryFold
- type EntryIdentity
- type EntryKind
- type Marker
- type Message
- type NavigationReader
- type OutlineEntry
- type OutlineResult
- type Page
- type PageQuery
- type Projection
- type ProjectionResolver
- type ProjectionSegment
- type ProjectionState
- type Projector
- type PruneOptions
- type Reader
- type Role
- type SearchMatch
- type SearchQuery
- type SearchResult
- type SessionMessageCards
- type ToolResult
- type UIAgentEventPayload
- type UIMessage
- type UIMessagePart
- type UISessionMessagePayload
- type UISubagentPayload
- type UITokenUsagePayload
Constants ¶
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" MarkerRuntimeChanged = "transcript_marker.runtime_changed" )
const ( UIRoleSystem = "system" UIRoleUser = "user" UIRoleAssistant = "assistant" UIMessagePartTypeFile = "file" )
const CanonicalSchema = "compozy.session.event.v1"
CanonicalSchema is the stored envelope schema for transcript-aware session events.
const (
// ProjectionVersion identifies the deterministic transcript projection contract.
ProjectionVersion = 4
)
const ReportEventType = "session.report"
ReportEventType is the durable event an always-on agent's report lands as. It starts no turn.
Variables ¶
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") )
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 ¶
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 ¶
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 ¶
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 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 ¶
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) Entry ¶
func (f *EntryFold) Entry(identity EntryIdentity) *Entry
Entry materializes the folded entry without mutating the fold.
func (*EntryFold) LastSequence ¶
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.
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 ¶
AgentEvent converts the marker to the durable transcript marker event shape.
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 ¶
type NavigationReader interface {
}
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 ¶
PageQuery selects one bounded chronological window ending before a stable start cursor.
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 ¶
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 ¶
ToolRoutes returns tool lifecycle routes learned by this projector.
type PruneOptions ¶
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.
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 ¶
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 ¶
func (c *SessionMessageCards) Card(stored store.SessionEvent) (UISessionMessagePayload, bool)
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 ¶
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 ¶
func (p UISessionMessagePayload) WithFallback(prior UISessionMessagePayload) UISessionMessagePayload
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.
Source Files
¶
- agent_event_codec.go
- canonical_payload.go
- entries.go
- entry_fold.go
- markers.go
- native_task_payload.go
- navigation.go
- projection.go
- projection_compaction.go
- projection_report.go
- projection_types.go
- projector.go
- prune.go
- redaction.go
- redaction_origin.go
- transcript.go
- transcript_parse.go
- transcript_payload.go
- transcript_tool_result.go
- ui_agent_event_payload.go
- ui_input_messages.go
- ui_messages.go
- ui_messages_decode.go
- ui_messages_identity.go
- ui_messages_session_message.go
- ui_messages_session_message_wire.go
- ui_messages_subagent.go
- ui_messages_tool.go
- ui_tool_result_payload.go