agent

type Agent interface {

	// Name returns the agent registry key (e.g., "claude-code", "gemini")
	Name() types.AgentName

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

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

	// IsPreview returns whether the agent integration is in preview or stable
	IsPreview() bool

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

	// ProtectedDirs returns repo-root-relative directories that should never be
	// modified or deleted during rewind or other destructive operations.
	// Examples: [".claude"] for Claude, [".gemini"] for Gemini.
	ProtectedDirs() []string

	// ReadTranscript reads the raw transcript bytes for a session.
	ReadTranscript(sessionRef string) ([]byte, error)

	// 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(ctx context.Context, 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)

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

	// GetSessionDir returns where agent stores session data for this repo.
	GetSessionDir(repoPath string) (string, error)

	// ResolveSessionFile returns the path to the session transcript file.
	ResolveSessionFile(sessionDir, agentSessionID string) string

	// ReadSession reads session data from agent's storage.
	ReadSession(input *HookInput) (*AgentSession, error)

	// WriteSession writes session data for resumption.
	WriteSession(ctx context.Context, session *AgentSession) error

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

type AgentSession struct {
	SessionID  string
	AgentName  types.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 EntryType string

type Event struct {
	// Type is the kind of lifecycle event.
	Type EventType

	// SessionID identifies the agent session.
	SessionID string

	// PreviousSessionID is non-empty when this event represents a session continuation
	// or handoff (e.g., Claude starting a new session ID after exiting plan mode).
	PreviousSessionID string

	// SessionRef is an agent-specific reference to the transcript (typically a file path).
	SessionRef string

	// Prompt is the user's prompt text (populated on TurnStart events).
	Prompt string

	// Timestamp is when the event occurred.
	Timestamp time.Time

	// ToolUseID identifies the tool invocation (for SubagentStart/SubagentEnd events).
	ToolUseID string

	// SubagentID identifies the subagent instance (for SubagentEnd events).
	SubagentID string

	// ToolInput is the raw tool input JSON (for subagent type/description extraction).
	// Used when both SubagentType and TaskDescription are empty (agents that don't provide
	// these fields directly parse them from ToolInput).
	ToolInput json.RawMessage

	// SubagentType is the kind of subagent (for SubagentStart/SubagentEnd events).
	// Used with TaskDescription instead of ToolInput
	SubagentType    string
	TaskDescription string

	// ResponseMessage is an optional message to display to the user via the agent.
	ResponseMessage string

	// Metadata holds agent-specific state that the framework stores and makes available
	// on subsequent events. Examples: Pi's activeLeafId, Cursor's is_background_agent.
	Metadata map[string]string
}

type EventType int

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 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 HookResponseWriter interface {
	Agent

	// WriteHookResponse outputs a message to the user via the agent's hook response protocol.
	WriteHookResponse(message string) error
}

type HookSupport interface {
	Agent

	// HookNames returns the hook verbs this agent supports.
	// These become subcommands under `entire hooks <agent>`.
	// e.g., ["stop", "user-prompt-submit", "session-start", "session-end"]
	HookNames() []string

	// ParseHookEvent translates an agent-native hook into a normalized lifecycle Event.
	// Returns nil if the hook has no lifecycle significance (e.g., pass-through hooks).
	// This is the core contribution surface for new agent implementations.
	ParseHookEvent(ctx context.Context, hookName string, stdin io.Reader) (*Event, error)

	// 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(ctx context.Context, localDev bool, force bool) (int, error)

	// UninstallHooks removes installed hooks
	UninstallHooks(ctx context.Context) error

	// AreHooksInstalled checks if hooks are currently installed
	AreHooksInstalled(ctx context.Context) bool
}

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 SubagentAwareExtractor interface {
	Agent

	// ExtractAllModifiedFiles extracts files modified by both the main agent and any spawned subagents.
	// The subagentsDir parameter specifies where subagent transcripts are stored.
	// Returns a deduplicated list of all modified file paths.
	ExtractAllModifiedFiles(transcriptData []byte, fromOffset int, subagentsDir string) ([]string, error)

	// CalculateTotalTokenUsage computes token usage including all spawned subagents.
	// The subagentsDir parameter specifies where subagent transcripts are stored.
	CalculateTotalTokenUsage(transcriptData []byte, fromOffset int, subagentsDir string) (*TokenUsage, error)
}

type TokenCalculator interface {
	Agent

	// CalculateTokenUsage computes token usage from the transcript starting at the given offset.
	CalculateTokenUsage(transcriptData []byte, fromOffset int) (*TokenUsage, error)
}

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.
	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)

	// ExtractPrompts extracts user prompts from the transcript starting at the given offset.
	ExtractPrompts(sessionRef string, fromOffset int) ([]string, error)

	// ExtractSummary extracts a summary of the session from the transcript.
	ExtractSummary(sessionRef string) (string, error)
}

type TranscriptPreparer interface {
	Agent

	// PrepareTranscript ensures the transcript is ready to read.
	// For Claude Code, this waits for the async transcript flush to complete.
	PrepareTranscript(ctx context.Context, sessionRef string) error
}