Documentation
¶
Overview ¶
Package conversations defines types and interfaces for conversation data structures, query options, and conversation records used throughout kodelet's conversation management system.
Index ¶
- Constants
- Variables
- func ContextWithConversationForkInitiator(ctx context.Context, initiator ConversationForkInitiator) context.Context
- func GenerateID() string
- func GetDefaultBasePath() (string, error)
- type ConversationForkInitiator
- type ConversationForkMetadata
- type ConversationForkMode
- type ConversationForkOptions
- type ConversationRecord
- type ConversationSummary
- func (cs ConversationSummary) GetCreatedAt() time.Time
- func (cs ConversationSummary) GetID() string
- func (cs ConversationSummary) GetMessageCount() int
- func (cs ConversationSummary) GetProvider() string
- func (cs ConversationSummary) GetUpdatedAt() time.Time
- func (cs ConversationSummary) GetUsage() llmtypes.Usage
- type QueryOptions
- type QueryResult
Constants ¶
const ( // ConversationForkMetadataKey stores durable conversation fork lineage. ConversationForkMetadataKey = "conversation_fork" // ConversationForkMetadataVersion is the current fork metadata schema version. ConversationForkMetadataVersion = 1 // RunnerIDMetadataKey identifies a conversation whose environment belongs to a remote runner. RunnerIDMetadataKey = "runner_id" // RunnerEnvironmentProfileMetadataKey stores the runner-local profile independently from model policy. RunnerEnvironmentProfileMetadataKey = "environment_profile" // CodexResponsesWindowGenerationMetadataKey stores the logical Codex Responses // context-window generation. Forks intentionally start a new generation lineage. CodexResponsesWindowGenerationMetadataKey = "codex_responses_window_generation" )
Variables ¶
var ErrConversationNotFound = errors.New("conversation not found")
ErrConversationNotFound identifies a missing durable conversation record.
Functions ¶
func ContextWithConversationForkInitiator ¶
func ContextWithConversationForkInitiator(ctx context.Context, initiator ConversationForkInitiator) context.Context
ContextWithConversationForkInitiator attaches the operation requesting a live fork.
func GenerateID ¶
func GenerateID() string
GenerateID creates a unique identifier for a conversation
func GetDefaultBasePath ¶
GetDefaultBasePath returns the default path for storing conversations
Types ¶
type ConversationForkInitiator ¶
type ConversationForkInitiator struct {
Type string `json:"type"`
ExtensionID string `json:"extension_id,omitempty"`
ToolName string `json:"tool_name,omitempty"`
}
ConversationForkInitiator identifies the host operation that requested a fork.
func ConversationForkInitiatorFromContext ¶
func ConversationForkInitiatorFromContext(ctx context.Context) (ConversationForkInitiator, bool)
ConversationForkInitiatorFromContext returns the operation requesting a live fork.
func ConversationForkInitiatorFromMetadata ¶
func ConversationForkInitiatorFromMetadata(metadata map[string]any) (ConversationForkInitiator, bool)
ConversationForkInitiatorFromMetadata returns the operation that created a persisted fork.
type ConversationForkMetadata ¶
type ConversationForkMetadata struct {
Version int `json:"version"`
SourceConversationID string `json:"source_conversation_id"`
RootConversationID string `json:"root_conversation_id"`
Depth int `json:"depth"`
Mode ConversationForkMode `json:"mode"`
Initiator *ConversationForkInitiator `json:"initiator,omitempty"`
}
ConversationForkMetadata describes the durable lineage of a forked conversation.
type ConversationForkMode ¶
type ConversationForkMode string
ConversationForkMode identifies how the source state was obtained.
const ( // ConversationForkModeLiveSnapshot captures the active in-memory thread state. ConversationForkModeLiveSnapshot ConversationForkMode = "live_snapshot" // ConversationForkModeStoredCopy duplicates an already persisted conversation record. ConversationForkModeStoredCopy ConversationForkMode = "stored_copy" // ConversationForkInitiatorTypeExtensionTool identifies an extension tool request. ConversationForkInitiatorTypeExtensionTool = "extension_tool" )
type ConversationForkOptions ¶
type ConversationForkOptions struct {
Mode ConversationForkMode
Initiator *ConversationForkInitiator
}
ConversationForkOptions configures metadata attached to a forked conversation.
type ConversationRecord ¶
type ConversationRecord struct {
ID string `json:"id"`
CWD string `json:"cwd,omitempty"`
RawMessages json.RawMessage `json:"rawMessages"` // Raw LLM provider messages
Provider string `json:"provider"` // e.g., "anthropic"
Usage llmtypes.Usage `json:"usage"`
Summary string `json:"summary,omitempty"`
CreatedAt time.Time `json:"createdAt"`
UpdatedAt time.Time `json:"updatedAt"`
Metadata map[string]any `json:"metadata,omitempty"`
ToolResults map[string]tools.StructuredToolResult `json:"toolResults,omitempty"` // Maps tool_call_id to structured result
}
ConversationRecord represents a persisted conversation with its messages and metadata
func ForkConversationRecord ¶
func ForkConversationRecord(source ConversationRecord) ConversationRecord
ForkConversationRecord creates an isolated copy of a conversation while resetting cumulative usage and preserving context-window accounting.
func ForkConversationRecordWithOptions ¶
func ForkConversationRecordWithOptions(source ConversationRecord, options ConversationForkOptions) ConversationRecord
ForkConversationRecordWithOptions creates an isolated conversation copy and records its durable lineage.
func NewConversationRecord ¶
func NewConversationRecord(id string) ConversationRecord
NewConversationRecord creates a new conversation record with a unique ID
func (*ConversationRecord) ToSummary ¶
func (cr *ConversationRecord) ToSummary() ConversationSummary
ToSummary converts a ConversationRecord to a ConversationSummary
type ConversationSummary ¶
type ConversationSummary struct {
ID string `json:"id"`
CWD string `json:"cwd,omitempty"`
MessageCount int `json:"messageCount"`
FirstMessage string `json:"firstMessage"`
Summary string `json:"summary,omitempty"`
Provider string `json:"provider"`
Metadata map[string]any `json:"metadata,omitempty"`
Usage llmtypes.Usage `json:"usage"`
CreatedAt time.Time `json:"createdAt"`
UpdatedAt time.Time `json:"updatedAt"`
IsRunning bool `json:"isRunning,omitempty"`
}
ConversationSummary provides a brief overview of a conversation
func (ConversationSummary) GetCreatedAt ¶
func (cs ConversationSummary) GetCreatedAt() time.Time
GetCreatedAt returns the creation timestamp of the conversation
func (ConversationSummary) GetID ¶
func (cs ConversationSummary) GetID() string
GetID returns the conversation ID for usage.ConversationSummary compatibility
func (ConversationSummary) GetMessageCount ¶
func (cs ConversationSummary) GetMessageCount() int
GetMessageCount returns the number of messages in the conversation
func (ConversationSummary) GetProvider ¶
func (cs ConversationSummary) GetProvider() string
GetProvider returns the LLM provider name used for the conversation
func (ConversationSummary) GetUpdatedAt ¶
func (cs ConversationSummary) GetUpdatedAt() time.Time
GetUpdatedAt returns the last update timestamp of the conversation
func (ConversationSummary) GetUsage ¶
func (cs ConversationSummary) GetUsage() llmtypes.Usage
GetUsage returns the LLM usage statistics for the conversation
type QueryOptions ¶
type QueryOptions struct {
StartDate *time.Time // Filter by start date
EndDate *time.Time // Filter by end date
SearchTerm string // Text to search for in IDs, working directories, first messages, or summaries
SearchCWDTerm string // Optional normalized override for working-directory matching
Provider string // Filter by LLM provider (e.g., "anthropic", "openai")
CWD string // Filter by canonical working directory
RunnerID string // Filter by durable runner affinity
Limit int // Maximum number of results
Offset int // Offset for pagination
SortBy string // Field to sort by
SortOrder string // "asc" or "desc"
}
QueryOptions provides filtering and sorting options for conversation queries
type QueryResult ¶
type QueryResult struct {
ConversationSummaries []ConversationSummary `json:"conversationSummaries"`
Total int `json:"total"` // Represents the total number of the entries that match the query without pagination
CWDs []string `json:"cwds,omitempty"` // All distinct persisted working directories, independent of pagination
QueryOptions
}
QueryResult represents the result of a query operation
Source Files