agent

type BreachVerifyState int

type Checkpoint struct {
	Fraction float64 // 0.0–1.0 fraction of MaxTurns
	Message  string  // message injected as a user message
}

type CompactionMode string

type Completer = tools.Completer

type ContextWindowTracker struct {
	Limit            int
	WarningThreshold float64

	WarningEmitted bool
	// contains filtered or unexported fields
}

type EpisodeEntry struct {
	Tool    string `json:"tool"`
	Args    string `json:"args"`
	Success bool   `json:"success"`
	Summary string `json:"summary"`
}

type EpisodeLog struct {
	Entries []EpisodeEntry `json:"entries"`
}

type Event struct {
	Type               EventType
	Timestamp          time.Time
	SessionID          string
	NodeID             string // Pipeline node that owns this session (empty for standalone sessions).
	Turn               int
	ToolName           string
	ToolInput          string
	ToolOutput         string
	ToolError          string
	Text               string
	Err                error
	ContextUtilization float64
	Provider           string
	Model              string
	Preview            string
	ProviderEvent      string
	FinishReason       string
	Usage              llm.Usage
	Metrics            *TurnMetrics
	ToolDuration       time.Duration
}

type EventHandler interface {
	HandleEvent(evt Event)
}

type EventHandlerFunc func(evt Event)

type EventType string

type Session struct {
	// contains filtered or unexported fields
}

type SessionConfig struct {
	MaxTurns                      int
	CommandTimeout                time.Duration
	MaxCommandTimeout             time.Duration
	LoopDetectionThreshold        int
	ContextWindowLimit            int
	ContextWindowWarningThreshold float64
	ToolOutputLimits              map[string]int
	WorkingDir                    string
	SystemPrompt                  string
	Model                         string
	Provider                      string
	CacheToolResults              bool
	ContextCompaction             CompactionMode
	CompactionThreshold           float64
	ReasoningEffort               string // OpenAI reasoning effort: "low", "medium", "high"
	ResponseFormat                string // "json_object" or "json_schema" — forces structured output
	ResponseSchema                string // JSON schema string when ResponseFormat is "json_schema"
	// ReflectOnError injects a structured reflection prompt after tool call
	// errors to help the LLM reason about what went wrong before retrying.
	// Default: true.
	ReflectOnError bool

	// VerifyAfterEdit enables automatic test/lint verification after turns that
	// include file writes or edits. If verification fails, the error is fed back
	// to the LLM with a repair prompt. Default: false (opt-in).
	VerifyAfterEdit bool

	// VerifyCommand is the explicit verification command to run. When empty,
	// auto-detection is used (looks for go.mod → "go test ./...", Cargo.toml →
	// "cargo test", package.json → "npm test", Makefile with test target →
	// "make test", pytest markers → "pytest").
	VerifyCommand string

	// MaxVerifyRetries is the maximum number of verify→repair cycles per edit
	// turn before giving up and proceeding. Default: 2.
	MaxVerifyRetries int

	// VerifyOnBreach, when true, makes the session run one verify pass after
	// the turn loop exhausts (MaxTurns reached without a detected loop), using
	// VerifyCommand only (never auto-detection — see resolveBreachVerifier).
	// The pipeline layer sets this to (turn_breach_policy != "fail") so the
	// opt-out path pays no verify cost. Independent of VerifyAfterEdit. (#303)
	VerifyOnBreach bool

	// Checkpoints are messages injected at specific turn-budget fractions.
	// Each checkpoint fires exactly once, on the turn where the fraction is
	// first reached. Fraction is in [0, 1] — e.g. 0.6 means "at 60% of MaxTurns".
	Checkpoints []Checkpoint

	// VerifyBroadCommand is an optional second verification command run after
	// the focused VerifyCommand passes. Use this for regression detection
	// (e.g. run the full test module without -x). Empty means disabled.
	VerifyBroadCommand string

	// Localize enables a pre-processing localization phase that scans the
	// working directory for files relevant to the task prompt and injects a
	// structured context block before the first LLM turn. Pure text analysis
	// plus filesystem scan — no LLM calls. Default: false.
	Localize bool

	// PriorEpisodeSummaries carries summaries from earlier attempts so retries
	// can avoid repeating known-failing approaches.
	PriorEpisodeSummaries []string
	// PlanBeforeExecute inserts one planning-only LLM call before the main turn
	// loop and keeps that plan in conversation context for subsequent turns.
	// Default: false.
	PlanBeforeExecute bool

	// ToolAccess restricts the agent's tool surface. When non-empty (any value),
	// the session registers zero tools, sets ToolChoice=none on LLM requests,
	// scrubs the built-in tool-naming prefix from the system prompt, and rejects
	// Params bypass keys (allowed_tools, disallowed_tools, permission_mode).
	//
	// Defends the v0.28.2 single-agent multi-tool-call vector: an LLM emitting
	// multiple tool calls in one response cannot execute any of them because
	// the registry is empty by construction.
	//
	// Canonical: case-insensitive, whitespace-trimmed. Only recognized spelling
	// is "none"; any other non-empty value still disables tools (fail-closed for
	// typos). Default: "" (unrestricted).
	//
	// System-prompt scope: tracker only scrubs its own built-in basePrompt
	// (which names "read", "write", etc. for path-relative semantics). A
	// caller-supplied SystemPrompt is appended verbatim — if it names tools,
	// the assembled prompt will still contain those tokens. The registry +
	// ToolChoice + dispatch-shortcircuit defenses do not depend on the prompt
	// scrub; the scrub is defense-in-depth against the LLM noticing tool
	// affordances. Callers who need a fully scrubbed assembled prompt should
	// audit their own SystemPrompt under restriction.
	//
	// Issue: github.com/2389-research/tracker#258.
	ToolAccess string

	// WritablePaths is the author-declared write-scope glob list resolved
	// against WorkingDir. Empty/absent = unbounded; non-empty = jail enforced
	// by the runtime (Linux Landlock for Bash subprocess + openat2 for
	// in-process tools). Empty values, malformed globs, working_dir escapes,
	// unsupported backends, and Landlock-unavailable hosts all refuse-to-start
	// at session creation via pipeline/handlers/codergen_jail.go's
	// configureJail gate (Task 14). See issue #272.
	WritablePaths []string

	// WritablePathsSet records whether the writable_paths attr was specified
	// on the originating node, even if the parsed slice is empty. Allows
	// configureJail to distinguish "absent" (Set=false, jail disabled) from
	// "present but parses to no entries" (Set=true, fail-CLOSED). Mirrors
	// pipeline.AgentNodeConfig.WritablePathsSet so the signal carries
	// through the codergen buildConfig handoff intact.
	WritablePathsSet bool

	// Backend names the execution backend for this session. Carried from
	// pipeline.AgentNodeConfig.Backend so configureJail can refuse
	// out-of-process backends (claude-code, acp) and unknown backends
	// (fail-closed) before wiring the writable_paths fs-jail. Empty string
	// is treated as "native" by configureJail. See issue #272.
	Backend string
}

type SessionOption func(*Session)

type SessionResult struct {
	SessionID          string
	Provider           string
	Duration           time.Duration
	Turns              int
	MaxTurnsUsed       bool
	LoopDetected       bool
	BreachVerify       BreachVerifyState // #303: result of the verify-on-breach pass
	ToolCalls          map[string]int
	FilesModified      []string
	FilesCreated       []string
	Usage              llm.Usage
	ContextUtilization float64
	ToolCacheHits      int
	ToolCacheMisses    int
	ToolTimings        map[string]time.Duration
	CompactionsApplied int
	LongestTurn        time.Duration
	EpisodeSummary     string
	Error              error
}

type TurnMetrics struct {
	InputTokens        int
	OutputTokens       int
	CacheReadTokens    int
	CacheWriteTokens   int
	ContextUtilization float64
	ToolCacheHits      int
	ToolCacheMisses    int
	TurnDuration       time.Duration
	EstimatedCost      float64
}