agent

type Agent interface {
	// Name returns the agent registry key (e.g., "claude-code", "gemini")
	Name() AgentName

	// Type returns the agent type identifier (e.g., "Claude Code", "Gemini CLI")
	// This is stored in metadata and trailers.
	Type() AgentType

	// Description returns a human-readable description for UI
	Description() string

	// DetectPresence checks if this agent is configured in the repository
	DetectPresence() (bool, error)

	// GetHookConfigPath returns path to hook config file (empty if none)
	GetHookConfigPath() string

	// SupportsHooks returns true if agent supports lifecycle hooks
	SupportsHooks() bool

	// ParseHookInput parses hook callback input from stdin
	ParseHookInput(hookType HookType, reader io.Reader) (*HookInput, error)

	// GetSessionID extracts session ID from hook input
	GetSessionID(input *HookInput) string

	// TransformSessionID converts agent session ID to Entire session ID
	TransformSessionID(agentSessionID string) string

	// ExtractAgentSessionID extracts agent session ID from Entire ID
	ExtractAgentSessionID(entireSessionID string) string

	// GetSessionDir returns where agent stores session data for this repo.
	// Examples:
	//   Claude: ~/.claude/projects/<sanitized-repo-path>/
	//   Aider: current working directory (returns repoPath)
	//   Cursor: ~/Library/Application Support/Cursor/User/globalStorage/
	GetSessionDir(repoPath string) (string, error)

	// ReadSession reads session data from agent's storage.
	// Handles different formats: JSONL (Claude), SQLite (Cursor), Markdown (Aider)
	ReadSession(input *HookInput) (*AgentSession, error)

	// WriteSession writes session data for resumption.
	// Agent handles format conversion (JSONL, SQLite, etc.)
	WriteSession(session *AgentSession) error

	// FormatResumeCommand returns command to resume a session
	FormatResumeCommand(sessionID string) string
}

type AgentName string

type AgentSession struct {
	SessionID  string
	AgentName  AgentName
	RepoPath   string
	SessionRef string // Path/reference to session in agent's storage
	StartTime  time.Time

	// NativeData holds the session content in the agent's native format.
	// Only the originating agent can interpret this data.
	// Examples:
	//   - Claude Code: raw JSONL bytes
	//   - Cursor: serialized SQLite rows
	//   - Aider: Markdown content
	NativeData []byte

	// Computed fields - populated by the agent when reading
	ModifiedFiles []string
	NewFiles      []string
	DeletedFiles  []string

	// Optional normalized entries - agents may populate this if needed
	// for operations that benefit from structured access
	Entries []SessionEntry
}

type AgentType string

type EntryType string

type Factory func() Agent

type FileWatcher interface {
	Agent

	// GetWatchPaths returns paths to watch for session changes
	GetWatchPaths() ([]string, error)

	// OnFileChange handles a detected file change and returns session info
	OnFileChange(path string) (*SessionChange, error)
}

type HookHandler interface {
	Agent

	// GetHookNames returns the hook verbs this agent supports.
	// These are the subcommand names that will appear under `entire hooks <agent>`.
	// e.g., ["stop", "user-prompt-submit", "pre-task", "post-task", "post-todo"]
	GetHookNames() []string
}

type HookInput struct {
	HookType  HookType
	SessionID string
	// SessionRef is an agent-specific session reference (file path, db key, etc.)
	SessionRef string
	Timestamp  time.Time

	// UserPrompt is the user's prompt text (from UserPromptSubmit hooks)
	UserPrompt string

	// Tool-specific fields (PreToolUse/PostToolUse)
	ToolName     string
	ToolUseID    string
	ToolInput    []byte // Raw JSON
	ToolResponse []byte // Raw JSON (PostToolUse only)

	// RawData preserves agent-specific data for extension
	RawData map[string]interface{}
}

type HookSupport interface {
	Agent

	// InstallHooks installs agent-specific hooks.
	// If localDev is true, hooks point to local development build.
	// If force is true, removes existing Entire hooks before installing.
	// Returns the number of hooks installed.
	InstallHooks(localDev bool, force bool) (int, error)

	// UninstallHooks removes installed hooks
	UninstallHooks() error

	// AreHooksInstalled checks if hooks are currently installed
	AreHooksInstalled() bool

	// GetSupportedHooks returns the hook types this agent supports
	GetSupportedHooks() []HookType
}

type HookType string

type SessionChange struct {
	SessionID  string
	SessionRef string
	EventType  HookType
	Timestamp  time.Time
}

type SessionEntry struct {
	UUID      string
	Type      EntryType
	Timestamp time.Time
	Content   string

	// Tool-specific fields
	ToolName      string
	ToolInput     interface{}
	ToolOutput    interface{}
	FilesAffected []string
}

type TokenUsage struct {
	// InputTokens is the number of input tokens (fresh, not from cache)
	InputTokens int `json:"input_tokens"`
	// CacheCreationTokens is tokens written to cache (billable at cache write rate)
	CacheCreationTokens int `json:"cache_creation_tokens"`
	// CacheReadTokens is tokens read from cache (discounted rate)
	CacheReadTokens int `json:"cache_read_tokens"`
	// OutputTokens is the number of output tokens generated
	OutputTokens int `json:"output_tokens"`
	// APICallCount is the number of API calls made
	APICallCount int `json:"api_call_count"`
	// SubagentTokens contains token usage from spawned subagents (if any)
	SubagentTokens *TokenUsage `json:"subagent_tokens,omitempty"`
}

type TranscriptAnalyzer interface {
	Agent

	// GetTranscriptPosition returns the current position (length) of a transcript.
	// For JSONL formats (Claude Code), this is the line count.
	// For JSON formats (Gemini CLI), this is the message count.
	// Returns 0 if the file doesn't exist or is empty.
	// Use this to efficiently check if the transcript has grown since last checkpoint.
	GetTranscriptPosition(path string) (int, error)

	// ExtractModifiedFilesFromOffset extracts files modified since a given offset.
	// For JSONL formats (Claude Code), offset is the starting line number.
	// For JSON formats (Gemini CLI), offset is the starting message index.
	// Returns:
	//   - files: list of file paths modified by the agent (from Write/Edit tools)
	//   - currentPosition: the current position (line count or message count)
	//   - error: any error encountered during reading
	ExtractModifiedFilesFromOffset(path string, startOffset int) (files []string, currentPosition int, err error)
}

type TranscriptChunker interface {
	Agent

	// ChunkTranscript splits a transcript into chunks if it exceeds maxSize.
	// Returns a slice of chunks. If the transcript fits in one chunk, returns single-element slice.
	// The chunking is format-aware: JSONL splits at line boundaries, JSON splits message arrays.
	ChunkTranscript(content []byte, maxSize int) ([][]byte, error)

	// ReassembleTranscript combines chunks back into a single transcript.
	// Handles format-specific reassembly (JSONL concatenation, JSON message merging).
	ReassembleTranscript(chunks [][]byte) ([]byte, error)
}