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 is the required full hexadecimal fallback commit ID written
	// to imported checkpoint metadata as commit_sha — the commit the UI shows
	// imported sessions against. The caller resolves it (the default branch
	// head; see resolveImportLinkCommitSHA); Run validates the exact
	// commit object and canonicalizes its ID before any writes, even on dry-run
	// or fully skipped imports. 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

	// Progress, when non-nil, receives session/turn progress notifications
	// as Run executes. Nil (the default) reports nothing.
	Progress *Progress

	// ReadRemotes is the ordered checkpoint read-candidate chain (see
	// checkpoint.OpenOptions.ReadRemotes) used by the idempotency listing.
	// Without it the listing reads only origin's tracking refs: turns already
	// on the elected sync remote get re-imported, and turns present solely in
	// origin's stale tracking ref get skipped. Callers resolve it via
	// strategy.CheckpointReadRemotes.
	ReadRemotes []string

	// RemoteRefLister, when set, adds the checkpoint refs present only on the
	// remote (names only, no fetch) to the idempotency listing, so a re-import
	// from a fresh clone skips turns imported elsewhere instead of writing them
	// again (under a new ID format, if the primary has since changed). Callers
	// pass the CLI's ListCheckpointRefsOnRemote.
	RemoteRefLister cp.RemoteRefListFunc
}

type Progress struct {
	// SessionStart fires once per session, after its transcript has been
	// split into turns and before any of them are written. sessionIndex is
	// 0-based against sessionTotal, the number of sessions Discover
	// returned; turnCount is the number of turns split from this session.
	SessionStart func(sessionIndex, sessionTotal int, agentName, sessionID string, turnCount int)
	// TurnWritten fires once per turn Run actually writes to the checkpoint
	// store — never for a turn skipped as already-imported, nor under
	// DryRun (see TurnSkipped for those). turnIndex is 0-based against
	// turnCount, matching the turnCount reported by this turn's
	// SessionStart call.
	TurnWritten func(sessionIndex, turnIndex, turnCount int)
	// TurnSkipped fires once per turn Run processes without writing: a turn
	// already imported (idempotent re-run) or, under DryRun, every turn
	// (dry runs never write). Index semantics match TurnWritten exactly.
	TurnSkipped func(sessionIndex, turnIndex, turnCount int)
}

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
	// CreatedAtFromModTime reports that CreatedAt is the transcript file's
	// modtime because the transcript records no per-turn time (Cursor,
	// Factory). It changes whenever the file grows, so it must not feed the
	// turn's checkpoint ID.
	CreatedAtFromModTime bool
	// 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
}