agentimport

type Importer interface {
	// Name is the registry key and the provenance source (e.g. "claude-code").
	Name() string
	// AgentType is the display name stored in checkpoint metadata (e.g. "Claude Code").
	AgentType() types.AgentType
	// Discover returns the agent's transcript files for the repo within the
	// lookback window. overridePath replaces the default transcript dir;
	// sessionFilter, when non-empty, keeps only matching session IDs.
	Discover(repoRoot, overridePath string, now time.Time, sessionFilter []string) ([]SessionFile, error)
	// SplitTurns splits one session's raw transcript bytes into per-turn units.
	SplitTurns(sf SessionFile, full []byte) ([]Turn, error)
}

type Options struct {
	RepoRoot      string
	OverridePath  string
	SessionFilter []string
	Now           time.Time
	DryRun        bool

	// LinkCommitSHA, when non-empty, is the fallback anchor written to each
	// imported checkpoint's metadata as commit_sha — the commit the UI shows
	// imported sessions against. The caller resolves it (default branch head
	// when resolvable; see resolveImportLinkCommitSHA); Run does not. A turn
	// whose transcript records a resolvable commit that is an ancestor of this
	// fallback anchors to that real commit instead (see turnAnchorResolver).
	LinkCommitSHA string
}

type Result struct {
	SessionsScanned int
	TurnsImported   int
	TurnsSkipped    int
}

type SessionFile struct {
	Path      string // absolute path to the transcript file
	SessionID string // agent session id (used in checkpoint metadata)
}

type Turn struct {
	LineStart, LineEnd int
	UUID               string
	Prompt, Model      string
	CreatedAt          time.Time
	// Tokens is this turn's token usage. Every field is a per-turn delta:
	// main-agent fields are scoped to the turn's [LineStart, LineEnd) slice by
	// the token helpers, and SubagentTokens is rescoped from the cumulative
	// snapshot those helpers return to a per-turn increment by
	// rescopeSubagentTokensToDeltas (see linesplit.go). That invariant lets
	// callers sum turns freely: writeSessionState sums them for the session
	// total and each imported checkpoint stores its own turn's delta, so a
	// subagent's tokens are counted exactly once rather than re-added on every
	// turn after it is discovered.
	Tokens *types.TokenUsage
	// CommitSHAs are the commit SHAs (possibly abbreviated) this turn's
	// transcript records creating, in transcript order. Extraction is
	// per-importer (see commitSHAsInRange for Claude Code). Callers must
	// resolve them against the repo before use. Nil when the transcript
	// records no commits (including agents that don't extract them); the
	// anchor then falls back to Options.LinkCommitSHA.
	CommitSHAs []string
}