adapter

package
v0.74.1 Latest Latest
Warning

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

 Go to latest Published: Feb 19, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package adapter defines the pluggable interface for AI session data sources, including the core Adapter, Session, Message, and Event types shared by all provider implementations.

Package adapter provides shared utilities for message search across adapters.

Index

Constants

View Source 
const (
	LargeSessionThreshold = 100 * 1024 * 1024 // 100MB - show warning
	HugeSessionThreshold  = 500 * 1024 * 1024 // 500MB - disable auto-reload
)

Session file size thresholds for performance warnings

View Source 
const (
	SessionCategoryInteractive = "interactive"
	SessionCategoryCron        = "cron"
	SessionCategorySystem      = "system"
)

Session category constants classify how a session was initiated.

View Source 
const DefaultMaxResults = 50

DefaultMaxResults is the default per-session match limit.

Variables

This section is empty.

Functions

func AllAdapters 

func AllAdapters() map[string]Adapter

AllAdapters creates all registered adapter instances without filtering by Detect. Use this at startup so that all adapters are available across project switches; consumers (e.g. conversations plugin) call Detect() per-adapter to filter by project.

func CompileSearchPattern 

func CompileSearchPattern(query string, opts SearchOptions) (*regexp.Regexp, error)

CompileSearchPattern compiles a search pattern based on options. Returns a compiled regexp for matching, or error if pattern is invalid.

func DetectAdapters 

func DetectAdapters(projectRoot string) (map[string]Adapter, error)

DetectAdapters scans for available adapters for the given project.

func RegisterFactory 

func RegisterFactory(factory func() Adapter)

RegisterFactory registers an adapter constructor.

func TotalMatches 

func TotalMatches(matches []MessageMatch) int

TotalMatches returns the total number of content matches across all messages.

Types

type Adapter 

type Adapter interface {
	ID() string
	Name() string
	Icon() string
	Detect(projectRoot string) (bool, error)
	Capabilities() CapabilitySet
	Sessions(projectRoot string) ([]Session, error)
	Messages(sessionID string) ([]Message, error)
	Usage(sessionID string) (*UsageStats, error)
	Watch(projectRoot string) (<-chan Event, io.Closer, error)
}

Adapter provides access to AI session data from various sources.

type Capability 

type Capability string

Capability represents a feature supported by an adapter. 

const (
	CapSessions Capability = "sessions"
	CapMessages Capability = "messages"
	CapUsage    Capability = "usage"
	CapWatch    Capability = "watch"
)

type CapabilitySet 

type CapabilitySet map[Capability]bool

CapabilitySet tracks which features an adapter supports.

type ContentBlock 

type ContentBlock struct {
	Type       string // "text", "tool_use", "tool_result", "thinking"
	Text       string // For text/thinking blocks
	ToolUseID  string // For tool_use and tool_result linking
	ToolName   string // For tool_use
	ToolInput  string // For tool_use (JSON string)
	ToolOutput string // For tool_result
	IsError    bool   // For tool_result errors
	TokenCount int    // For thinking blocks
}

ContentBlock represents a single block in structured message content.

type ContentMatch 

type ContentMatch struct {
	// BlockType identifies the content block type:
	// "text", "tool_use", "tool_result", or "thinking".
	BlockType string

	// LineNo is the 1-indexed line number within the block.
	LineNo int

	// LineText is the full line containing the match.
	LineText string

	// ColStart is the 0-indexed byte position where the match begins in LineText.
	ColStart int

	// ColEnd is the 0-indexed byte position where the match ends in LineText.
	ColEnd int
}

ContentMatch represents a single match location within message content.

func SearchContent 

func SearchContent(content string, blockType string, re *regexp.Regexp) []ContentMatch

SearchContent searches text content line-by-line and returns matches. Returns all matches found in content with line numbers and positions.

type Event 

type Event struct {
	Type      EventType
	SessionID string
	Data      any
}

Event represents a change in session data.

type EventType 

type EventType string

EventType identifies the kind of adapter event. 

const (
	EventSessionCreated EventType = "session_created"
	EventSessionUpdated EventType = "session_updated"
	EventMessageAdded   EventType = "message_added"
)

type Message 

type Message struct {
	ID        string
	Role      string
	Content   string
	Timestamp time.Time
	Model     string // Model ID (e.g., "claude-opus-4-5-20251101")
	TokenUsage
	ToolUses       []ToolUse
	ThinkingBlocks []ThinkingBlock
	ContentBlocks  []ContentBlock // Structured content for rich display
	SourceLabel    string         // Channel badge, e.g. "[TG] Marcus Vorwaller", "[WA]", "[cron] job-name"
}

Message represents a message in a session.

type MessageMatch 

type MessageMatch struct {
	// MessageID is the unique identifier of the matched message.
	MessageID string

	// MessageIdx is the zero-based index of the message in the session.
	MessageIdx int

	// Role is the message author (e.g., "user", "assistant").
	Role string

	// Timestamp is when the message was created.
	Timestamp time.Time

	// Model is the AI model used for this message (may be empty for user messages).
	Model string

	// Matches contains the specific content matches within this message.
	Matches []ContentMatch
}

MessageMatch represents a message containing one or more search matches.

func SearchMessage 

func SearchMessage(msg *Message, msgIdx int, re *regexp.Regexp, maxResults int, currentTotal int) *MessageMatch

SearchMessage searches all content in a message and returns matches. Searches across text content, tool uses, tool results, and thinking blocks.

func SearchMessagesSlice 

func SearchMessagesSlice(messages []Message, query string, opts SearchOptions) ([]MessageMatch, error)

SearchMessagesSlice is a helper that searches a slice of messages. Returns MessageMatch results up to opts.MaxResults.

type MessageSearcher 

type MessageSearcher interface {
	// SearchMessages searches message content within a session.
	// Returns matches with context, limited by opts.MaxResults.
	// The query is interpreted as regex if opts.UseRegex is true,
	// otherwise as a literal substring.
	SearchMessages(sessionID, query string, opts SearchOptions) ([]MessageMatch, error)
}

MessageSearcher is an optional interface for adapters that support searching message content across sessions. Adapters implement this to enable the cross-conversation search feature.

type ProjectDiscoverer 

type ProjectDiscoverer interface {
	// DiscoverRelatedProjectDirs returns paths to project directories that
	// appear related to the given main worktree path. Used to find conversations
	// from deleted worktrees that git no longer knows about.
	DiscoverRelatedProjectDirs(mainWorktreePath string) ([]string, error)
}

ProjectDiscoverer is an optional interface for adapters that can discover related project directories (e.g., from deleted worktrees).

type SearchOptions 

type SearchOptions struct {
	// UseRegex treats the query as a regular expression if true,
	// otherwise as a literal substring match.
	UseRegex bool

	// CaseSensitive enables case-sensitive matching if true.
	// Defaults to case-insensitive when false.
	CaseSensitive bool

	// MaxResults limits matches per session. Zero uses default (50).
	MaxResults int
}

SearchOptions configures how message search is performed.

func DefaultSearchOptions 

func DefaultSearchOptions() SearchOptions

DefaultSearchOptions returns sensible defaults for search.

type Session 

type Session struct {
	ID           string
	Name         string
	Slug         string // Short identifier for display (e.g., "ses_abc123")
	AdapterID    string // Adapter identifier (e.g., "claude-code", "codex")
	AdapterName  string // Human-readable adapter name
	AdapterIcon  string // Single character icon for badge display
	CreatedAt    time.Time
	UpdatedAt    time.Time
	Duration     time.Duration
	IsActive     bool
	TotalTokens  int     // Sum of input + output tokens
	EstCost      float64 // Estimated cost in dollars
	IsSubAgent   bool    // True if this is a sub-agent spawned by another session
	MessageCount int     // Number of user/assistant messages (0 = metadata-only)
	FileSize     int64   // Session file size in bytes, for performance-aware behavior
	Path         string  // Absolute path to session file (for tiered watching, td-dca6fe)

	SessionCategory string `json:"sessionCategory,omitempty"` // "interactive", "cron", "system", ""

	// Rich metadata (adapter-specific, optional)
	CronJobName   string `json:"cronJobName,omitempty"`   // For cron sessions
	SourceChannel string `json:"sourceChannel,omitempty"` // "telegram", "whatsapp", "direct"

	// Worktree fields - populated when session is from a different worktree
	WorktreeName string // Branch name or directory name of the worktree (empty if main or non-worktree)
	WorktreePath string // Absolute path to the worktree (empty if same as current workdir)
}

Session represents an AI coding session.

func (*Session) SizeLevel 

func (s *Session) SizeLevel() int

SizeLevel returns the severity level for this session's file size. 0 = normal, 1 = large (100MB+), 2 = huge (500MB+)

func (*Session) SizeMB 

func (s *Session) SizeMB() float64

SizeMB returns the session file size in megabytes.

type TargetedRefresher 

type TargetedRefresher interface {
	SessionByID(sessionID string) (*Session, error)
}

TargetedRefresher is an optional interface for adapters that support refreshing a single session by ID without scanning the full directory (td-2b8ebe).

type ThinkingBlock 

type ThinkingBlock struct {
	Content    string
	TokenCount int // Estimated from len(Content)/4
}

ThinkingBlock represents Claude's extended thinking content.

type TokenUsage 

type TokenUsage struct {
	InputTokens  int
	OutputTokens int
	CacheRead    int
	CacheWrite   int
}

TokenUsage tracks token counts for a message or session.

type ToolUse 

type ToolUse struct {
	ID     string
	Name   string
	Input  string
	Output string
}

ToolUse represents a tool call made by the AI.

type UsageStats 

type UsageStats struct {
	TotalInputTokens  int
	TotalOutputTokens int
	TotalCacheRead    int
	TotalCacheWrite   int
	MessageCount      int
}

UsageStats provides aggregate usage statistics.

type WatchScope 

type WatchScope int

WatchScope indicates whether an adapter watches global or per-project paths. 

const (
	// WatchScopeProject indicates the adapter watches a unique path per project.
	WatchScopeProject WatchScope = iota
	// WatchScopeGlobal indicates the adapter watches a global path regardless of project.
	WatchScopeGlobal
)

type WatchScopeProvider 

type WatchScopeProvider interface {
	// WatchScope returns the scope of this adapter's Watch method.
	// Global-scoped adapters only need one watcher regardless of worktree paths.
	WatchScope() WatchScope
}

WatchScopeProvider is an optional interface for adapters to indicate their watch scope (td-7a72b6f7). Adapters that watch global paths (like codex, warp) should implement this to avoid duplicate watchers when the plugin iterates over multiple worktree paths.

type WatchTier 

type WatchTier int

WatchTier indicates whether a session should be watched with fsnotify or polling. 

const (
	// WatchTierHot uses real-time fsnotify watching (high priority, limited count).
	WatchTierHot WatchTier = iota
	// WatchTierCold uses periodic polling (low priority, unlimited count).
	WatchTierCold
)

Source Files

View all Source files

Directories

Path Synopsis
Package amp provides an adapter for Amp Code that reads thread JSON files from ~/.local/share/amp/threads/.
 Package amp provides an adapter for Amp Code that reads thread JSON files from ~/.local/share/amp/threads/.
Package cache provides a generic thread-safe LRU cache with file-metadata invalidation, along with incremental, tail, and head JSONL readers that share pooled scanner buffers.
 Package cache provides a generic thread-safe LRU cache with file-metadata invalidation, along with incremental, tail, and head JSONL readers that share pooled scanner buffers.
Package claudecode provides an adapter for Claude Code (Anthropic's CLI) that parses JSONL session files to display conversations and token usage.
 Package claudecode provides an adapter for Claude Code (Anthropic's CLI) that parses JSONL session files to display conversations and token usage.
Package codex provides an adapter for Codex CLI that reads session files with two-pass parsing optimization for large conversation files.
 Package codex provides an adapter for Codex CLI that reads session files with two-pass parsing optimization for large conversation files.
Package cursor provides an adapter for Cursor that reads SQLite databases to extract conversation history with workspace-based organization.
 Package cursor provides an adapter for Cursor that reads SQLite databases to extract conversation history with workspace-based organization.
Package geminicli provides an adapter for Gemini CLI that parses JSON session files with project-specific conversation tracking.
 Package geminicli provides an adapter for Gemini CLI that parses JSON session files with project-specific conversation tracking.
Package kiro provides an adapter for Kiro CLI (kiro-cli from AWS) that queries its SQLite database for conversation history filtered by working directory.
 Package kiro provides an adapter for Kiro CLI (kiro-cli from AWS) that queries its SQLite database for conversation history filtered by working directory.
Package opencode provides an adapter for OpenCode that reads sessions with project indexing and session metadata caching.
 Package opencode provides an adapter for OpenCode that reads sessions with project indexing and session metadata caching.
Package pi provides an adapter for Pi AI agent sessions (embedded in OpenClaw).
 Package pi provides an adapter for Pi AI agent sessions (embedded in OpenClaw).
Package piagent implements an adapter for standalone Pi Agent sessions.
 Package piagent implements an adapter for standalone Pi Agent sessions.
Package testutil provides fixture generators for adapter testing and benchmarking, producing realistic JSONL session files in Claude Code and Codex formats.
 Package testutil provides fixture generators for adapter testing and benchmarking, producing realistic JSONL session files in Claude Code and Codex formats.
Package tieredwatcher implements tiered file watching with a HOT tier using real-time fsnotify and a COLD tier using periodic polling, reducing file descriptor usage while keeping recently active sessions responsive.
 Package tieredwatcher implements tiered file watching with a HOT tier using real-time fsnotify and a COLD tier using periodic polling, reducing file descriptor usage while keeping recently active sessions responsive.
Package warp provides an adapter for Warp terminal AI that queries its SQLite database for conversation history filtered by working directory.
 Package warp provides an adapter for Warp terminal AI that queries its SQLite database for conversation history filtered by working directory.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.