pipeline

type ACPConfig struct {
	Agent string // explicit agent binary: "claude-agent-acp", "codex-acp", "gemini" (overrides provider mapping)
}

type Actor string

type AgentBackend interface {
	Run(ctx context.Context, cfg AgentRunConfig, emit func(agent.Event)) (agent.SessionResult, error)
}

type AgentNodeConfig struct {
	Backend         string
	WorkingDir      string
	McpServers      string // raw JSON; parsed by the handler
	AllowedTools    string
	DisallowedTools string
	MaxBudgetUSD    float64
	PermissionMode  string
	ACPAgent        string

	// ToolAccess restricts the agent's tool surface. When non-empty (any
	// value), the runtime registers zero tools, sets ToolChoice=none on
	// LLM requests, scrubs tool-naming text from the system prompt, and
	// rejects Params bypass keys. Canonical: case-insensitive, whitespace-
	// trimmed. Fail-closed for typos. See agent.SessionConfig.ToolAccess.
	// Issue: github.com/2389-research/tracker#258.
	ToolAccess string

	AutoStatus        bool
	ReflectOnError    bool // initialized to true by AgentConfig; explicit "false" disables
	ReflectOnErrorSet bool // true when the attr was present on the node

	VerifyAfterEdit    bool
	VerifyAfterEditSet bool
	VerifyCommand      string
	MaxVerifyRetries   int

	PlanBeforeExecute    bool
	PlanBeforeExecuteSet bool

	Model            string
	Provider         string
	SystemPrompt     string
	MaxTurns         int
	TurnBreachPolicy string // #303: "guard" (default) or "fail" (opt-out)
	CommandTimeout   time.Duration
	ReasoningEffort  string

	ResponseFormat string
	ResponseSchema string

	// WritablePaths bounds the file paths this agent's tools may write,
	// as author-chosen globs resolved against the session root. Non-empty
	// triggers the runtime fs-jail (Linux Landlock for Bash subprocess +
	// openat2 for in-process Write/Edit/ApplyPatch). Distinguishing absent
	// from present-but-empty requires WritablePathsSet — the configureJail
	// gate refuses-to-start when Set && len == 0 so a malformed/whitespace
	// attr can never silently degrade to unbounded. See issue #272.
	WritablePaths []string

	// WritablePathsSet records whether the writable_paths attr was present
	// on the node. Distinguishes "absent" (Set=false, jail disabled) from
	// "present but parses to no entries" (Set=true, fail-CLOSED at the
	// codergen configureJail gate per issue #272). Mirrors the three-state
	// pattern of ReflectOnErrorSet et al. above.
	WritablePathsSet bool

	CacheToolResults    bool
	CacheToolResultsSet bool

	// ContextCompaction carries the raw attr value. "auto" enables automatic
	// compaction; any other non-empty value (e.g. "none") disables it; ""
	// means the attr was absent. Kept as string so future modes can be added
	// without a type change.
	ContextCompaction    string
	ContextCompactionSet bool
	CompactionThreshold  float64
}

type AgentRunConfig struct {
	Prompt       string
	SystemPrompt string
	Model        string
	Provider     string
	WorkingDir   string
	MaxTurns     int
	Timeout      time.Duration
	Extra        any // backend-specific: *ClaudeCodeConfig for claude-code backend

	// ToolAccess restricts the agent's tool surface. When non-empty, every
	// backend must enforce: native via agent.SessionConfig.IsToolAccessRestricted;
	// claude-code via the DisallowedTools list set by applyClaudeCodeToolAccess;
	// ACP refuses session creation (no verified deny-equivalent — see
	// backend_acp.go for the refusal site). Issue: github.com/2389-research/tracker#258.
	ToolAccess string
}

type BudgetBreach struct {
	Kind    BudgetBreachKind
	Message string
}

type BudgetBreachKind int

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

type BudgetLimits struct {
	MaxTotalTokens int
	MaxCostCents   int
	MaxWallTime    time.Duration
}

type BundleInfo struct {
	Identity  string
	EntryPath string
	Manifest  dipx.Manifest
}

type Checkpoint struct {
	RunID          string            `json:"run_id"`
	CurrentNode    string            `json:"current_node"`
	CompletedNodes []string          `json:"completed_nodes"`
	RetryCounts    map[string]int    `json:"retry_counts"`
	Context        map[string]string `json:"context"`
	Timestamp      time.Time         `json:"timestamp"`
	RestartCount   int               `json:"restart_count"`

	// EdgeSelections stores the selected outgoing edge target for each
	// completed node (nodeID -> selected edge To). Used on resume to
	// replay routing decisions instead of re-evaluating stale conditions.
	EdgeSelections map[string]string `json:"edge_selections,omitempty"`

	// FallbackTaken tracks which goal-gate nodes have already used their
	// one-shot fallback/escalation route. Persisted in checkpoint JSON so
	// the guard survives checkpoint save/restore cycles.
	FallbackTaken map[string]bool `json:"fallback_taken,omitempty"`

	// WIPRefs maps a failed/exhausted node ID to the recoverable git ref
	// (a tag tracker/wip/<runID>/<nodeID>) where its uncommitted work was
	// preserved before the engine routed away from it (#302). Additive;
	// omitempty keeps older checkpoints without the field loading cleanly.
	WIPRefs map[string]string `json:"wip_refs,omitempty"`

	// BundleIdentity is the content-addressed identity of the .dipx bundle
	// the run was started against ("sha256:<hex>"). Empty for runs started
	// from a plain .dip file. Used for strict resume verification.
	BundleIdentity string `json:"bundle_identity,omitempty"`

	// ValidationOverrides persists the override sticky list across resume and
	// bundle export. Appended at the flip-point in advanceToNextNode whenever
	// an override edge is traversed; never cleared by clearDownstream or
	// handleLoopRestart. omitempty for backwards compat with pre-v0.35
	// checkpoints (absent = "no overrides happened").
	ValidationOverrides []OverrideDetail `json:"validation_overrides,omitempty"`
	// contains filtered or unexported fields
}

type ChildRunContext struct {
	// BudgetGuard is the parent engine's budget guard. Child runs should
	// pass it via WithBudgetGuard so the same limits enforce within the
	// child. Nil when the parent has no budget configured.
	BudgetGuard *BudgetGuard

	// Baseline is an immutable snapshot of the parent's aggregated usage
	// at the moment the child was launched. Child runs should pass it via
	// WithBaselineUsage so the child's budget check folds baseline + its
	// own trace aggregate before comparing to limits. Without this, a
	// nested budget check would only see child-local spend and the
	// effective ceiling inside a subgraph would grow by the parent's
	// already-consumed amount.
	Baseline *UsageSummary
}

type ClaudeCodeConfig struct {
	MCPServers      []MCPServerConfig
	AllowedTools    []string
	DisallowedTools []string
	MaxBudgetUSD    float64
	PermissionMode  PermissionMode
}

type ConditionEval struct {
	EdgeTo    string `json:"edge_to"`
	Condition string `json:"condition"`
}

type CostSnapshot struct {
	TotalTokens    int
	TotalCostUSD   float64
	ProviderTotals map[string]ProviderUsage
	WallElapsed    time.Duration
	Estimated      bool
}

type DecisionDetail struct {
	// Edge selection fields.
	EdgeFrom     string `json:"edge_from,omitempty"`
	EdgeTo       string `json:"edge_to,omitempty"`
	EdgePriority string `json:"edge_priority,omitempty"` // "condition", "label", "suggested", "weight", "lexical", "override"

	// Condition evaluation fields.
	EdgeCondition  string `json:"edge_condition,omitempty"`
	ConditionMatch bool   `json:"condition_match,omitempty"`

	// Node outcome fields.
	OutcomeStatus  string            `json:"outcome_status,omitempty"`
	ContextUpdates map[string]string `json:"context_updates,omitempty"`

	// Context snapshot at the decision point (routing-relevant keys).
	ContextSnapshot map[string]string `json:"context_snapshot,omitempty"`

	// Restart/loop fields.
	RestartCount int      `json:"restart_count,omitempty"`
	ClearedNodes []string `json:"cleared_nodes,omitempty"`

	// Session stats from handler outcome.
	TokenInput  int `json:"token_input,omitempty"`
	TokenOutput int `json:"token_output,omitempty"`

	// ConditionsTried lists the conditional edges that were evaluated
	// false on the way to a fallback selection. Populated only on
	// EventConditionalFallthrough events. Each entry pairs the target
	// node with the literal condition string so a diagnostics consumer
	// can render "your routing intents X, Y, Z all missed" without
	// re-evaluating expressions.
	ConditionsTried []ConditionEval `json:"conditions_tried,omitempty"`
}

type Edge struct {
	From      string
	To        string
	Label     string
	Condition string
	// Override marks the edge as a validation-override path. When the engine
	// traverses an override edge from a wait.human gate, the run's terminal
	// EngineResult.Status becomes OutcomeValidationOverridden (audit-only;
	// routing is unaffected). Valid only on edges from wait.human-handler
	// nodes; enforced by the adapter at graph construction time.
	Override bool
	Attrs    map[string]string
}

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

type EngineOption func(*Engine)

type EngineResult struct {
	RunID           string
	Status          TerminalStatus
	CompletedNodes  []string
	Context         map[string]string
	Trace           *Trace
	Usage           *UsageSummary
	BudgetLimitsHit []string // populated when a BudgetGuard halted the run
	// ValidationOverrides is the list of override edges traversed during this
	// run, in chronological order. Populated for every terminal path (success,
	// fail, budget, validation_overridden) so failure-after-override forensics
	// still see the override. Empty for runs with no override edges.
	//
	// The terminal-status rule writes Status=OutcomeValidationOverridden when
	// len(ValidationOverrides) > 0 AND the run reached the success exit;
	// failure paths return fail/budget regardless of override presence.
	ValidationOverrides []OverrideDetail
}

type Fidelity string

type GitPreflight string

type Graph struct {
	Name      string
	Nodes     map[string]*Node
	Edges     []*Edge
	Attrs     map[string]string
	StartNode string
	ExitNode  string

	// NodeOrder preserves the declaration order of nodes from the source file.
	// Used by the TUI to display nodes in a sensible order (declaration order)
	// rather than BFS order which puts "Done" in the middle.
	NodeOrder []string

	// DippinValidated is set to true when the graph was produced from a .dip
	// source that has already passed dippin-lang's structural validator
	// (DIP001–DIP009). Tracker's own validateGraph skips checks that overlap
	// with those diagnostics, preventing false positives and divergence between
	// `dippin doctor` and `tracker validate`.
	//
	// CONTRACT: this flag reflects the graph's state at the moment dippin
	// validation ran. If the graph is subsequently mutated (nodes or edges
	// added/removed programmatically), callers MUST clear this flag or
	// re-run dippin validation before calling Validate again — otherwise
	// tracker's structural checks will be skipped for a shape that has
	// changed since dippin last validated it.
	DippinValidated bool

	// LintWarnings carries pre-formatted warning lines from dippin-lang's
	// lint pass (DIP1XX). Populated by LoadDippinWorkflowFromIR for .dip /
	// .dipx sources and empty for DOT graphs. tracker.ValidateAll surfaces
	// these alongside its own structural warnings so callers (validate /
	// simulate / doctor) see a single warnings list without re-running any
	// DIP-coded check on the tracker side. Format matches tracker's
	// single-line convention ("warning[DIPxxx]: ...") to render cleanly
	// inside bulleted "Validation Warnings" output.
	LintWarnings []string
	// contains filtered or unexported fields
}

type Handler interface {
	Name() string
	Execute(ctx context.Context, node *Node, pctx *PipelineContext) (Outcome, error)
}

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

type HumanNodeConfig struct {
	Mode          string // "" or "choice" (default — presents outgoing edge labels), "yes_no", "interview", "freeform"
	DefaultChoice string // "default_choice" attr, falling back to "default"
	Prompt        string
	QuestionsKey  string
	AnswersKey    string
	Timeout       time.Duration
	TimeoutAction string // "fail", "default", or "" (unset — treated as "default")
	// Writes carries the raw "writes:" attr; consumers that need the parsed
	// key list should still call pipeline.ParseDeclaredKeys.
	Writes string
}

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

type LoggingEventHandler struct {
	Writer io.Writer
	// contains filtered or unexported fields
}

type MCPServerConfig struct {
	Name    string
	Command string
	Args    []string
}

type MarkerDetail struct {
	Pattern      string `json:"pattern"`
	CapturedTail string `json:"captured_tail,omitempty"`
	Error        string `json:"error,omitempty"`
}

type Node struct {
	ID      string
	Shape   string
	Label   string
	Attrs   map[string]string
	Handler string
}

type Outcome struct {
	Status             string
	ContextUpdates     map[string]string
	PreferredLabel     string
	SuggestedNextNodes []string
	Stats              *SessionStats // optional, populated by codergen handler
	// ChildUsage is the aggregated usage of a child run that executed under
	// this node (subgraph, manager_loop). When non-nil, Trace.AggregateUsage
	// folds it into totals and per-provider rollups so the parent trace
	// reflects spend that happened inside the child. Required for
	// BudgetGuard enforcement to see child spend once control returns to
	// the parent.
	ChildUsage *UsageSummary
	// Truncations records output streams that exceeded their per-stream
	// cap during this node's execution. The engine emits one
	// EventToolOutputTruncated per entry so `tracker diagnose` and the
	// audit log can correlate routing misses with truncation (issue #208).
	// Currently populated only by the tool handler.
	Truncations []TruncationDetail
	// MissingMarker records a marker_grep regex that produced no match
	// (issue #210). When non-nil the engine emits EventToolMarkerMissing
	// before the engine's normal post-node accounting; the handler also
	// sets Status = OutcomeFail so routing does not silently fall through
	// to an unconditional edge. Populated only by the tool handler.
	MissingMarker *MarkerDetail
	// MissingRoute records the absence of a _TRACKER_ROUTE= sentinel
	// in captured stdout when the node had route_required: true
	// (#212). Same flow as MissingMarker: handler sets Status = Fail,
	// engine emits EventToolRouteMissing. Sentinel extraction itself
	// runs unconditionally; this field is populated only when the
	// missing-sentinel + route_required combination triggers a fail.
	MissingRoute *RouteDetail
	// OverrideActor is the Actor classification of the interviewer that produced
	// this outcome. Populated by HumanHandler from its bound interviewer's
	// Actor() method (via actorOf helper). The engine reads this at edge-selection
	// time when an override edge is traversed, to populate OverrideDetail.Actor.
	// Empty for non-wait.human handlers (they cannot originate override edges).
	OverrideActor Actor
	// ChildOverride carries OverrideDetail entries propagated up from a child
	// run (subgraph, manager_loop, or parallel branch with a subgraph child).
	// The engine's applyOutcome path appends these to the parent's
	// runState.validationOverrides after the handler returns.
	ChildOverride []OverrideDetail
}

type OverrideDetail struct {
	// GateNodeID is the source node of the override edge (the wait.human gate).
	GateNodeID string `json:"gate_node_id"`

	// Label is the edge label of the override edge ("accept", "mark done", etc.).
	// Empty when the override edge has no label.
	Label string `json:"label,omitempty"`

	// Actor identifies who took the override edge.
	Actor Actor `json:"actor"`

	// SubgraphPath is populated when this override was propagated from a child
	// run via Outcome.ChildOverride. Outermost-to-innermost subgraph node IDs;
	// the leaf gate node ID lives in GateNodeID, not in SubgraphPath. Empty for
	// overrides taken in the run's own graph.
	SubgraphPath []string `json:"subgraph_path,omitempty"`

	// Timestamp is the moment the override edge was traversed. In the JSONL wire
	// format, the enclosing event line carries its own timestamp; this field is
	// primarily for Checkpoint persistence where there is no enclosing timestamp.
	Timestamp time.Time `json:"timestamp"`
}

type ParallelNodeConfig struct {
	ParallelTargets string
	FanInSources    string
	JoinID          string
	MaxConcurrency  int
	BranchTimeout   time.Duration
}

type PermissionMode string

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

type PipelineEvent struct {
	Type       PipelineEventType
	Timestamp  time.Time
	RunID      string
	NodeID     string
	Message    string
	Err        error
	Decision   *DecisionDetail   // non-nil for decision audit trail events
	Cost       *CostSnapshot     // non-nil for EventCostUpdated and EventBudgetExceeded events
	Truncation *TruncationDetail // non-nil for EventToolOutputTruncated
	Marker     *MarkerDetail     // non-nil for EventToolMarkerMissing
	Route      *RouteDetail      // non-nil for EventToolRouteMissing
	// Override is non-nil on EventValidationOverridden events. Carries the
	// gate, label, actor, and subgraph_path of the traversed override edge.
	Override *OverrideDetail

	// BundleIdentity is the content-addressed identity of the .dipx bundle
	// the run was started against ("sha256:<hex>"). Empty for runs from a
	// plain .dip file. The engine stamps this on every emitted event so
	// activity.jsonl carries provenance on every line.
	BundleIdentity string
}

type PipelineEventHandler interface {
	HandlePipelineEvent(evt PipelineEvent)
}

type PipelineEventHandlerFunc func(evt PipelineEvent)

type PipelineEventType string

type PreflightConfig struct {
	WorkDir        string                           // absolute path; required
	Requires       []string                         // from graph.Attrs["requires"]
	Policy         GitPreflight                     // resolved from CLI > library > default ""
	AllowInit      bool                             // required when Policy == GitPreflightInit and !InteractiveTTY
	InteractiveTTY bool                             // when true, --git=init may prompt instead of needing --allow-init
	Warner         func(format string, args ...any) // optional; defaults to a no-op
	// PromptYN is used by --git=init in interactive mode. Tests inject a stub.
	// When nil, the default reads from stdin.
	PromptYN func(prompt string) bool
}

type ProviderUsage struct {
	InputTokens      int     `json:"input_tokens"`
	OutputTokens     int     `json:"output_tokens"`
	TotalTokens      int     `json:"total_tokens"`
	CostUSD          float64 `json:"cost_usd"`
	ReasoningTokens  int     `json:"reasoning_tokens"`
	CacheReadTokens  int     `json:"cache_read_tokens"`
	CacheWriteTokens int     `json:"cache_write_tokens"`
	SessionCount     int     `json:"session_count"`
	Estimated        bool    `json:"estimated,omitempty"`
}

type RegistryFactory func(graph *Graph, parentNodeID string) *HandlerRegistry

type RetryConfig struct {
	PolicyName    string // "" means "use graph default or 'standard'"
	MaxRetries    int    // 0 and MaxRetriesSet=false means "unset"
	MaxRetriesSet bool
	BaseDelay     time.Duration
	BaseDelaySet  bool
}

type RetryPolicy struct {
	Name       string
	MaxRetries int
	BaseDelay  time.Duration
	BackoffFn  func(attempt int, base time.Duration) time.Duration
}

type RouteDetail struct {
	CapturedTail string `json:"captured_tail,omitempty"`
}

type SessionStats struct {
	Turns            int            `json:"turns"`
	ToolCalls        map[string]int `json:"tool_calls,omitempty"`
	TotalToolCalls   int            `json:"total_tool_calls"`
	FilesModified    []string       `json:"files_modified,omitempty"`
	FilesCreated     []string       `json:"files_created,omitempty"`
	Compactions      int            `json:"compactions"`
	LongestTurn      time.Duration  `json:"longest_turn"`
	CacheHits        int            `json:"cache_hits"`
	CacheMisses      int            `json:"cache_misses"`
	InputTokens      int            `json:"input_tokens"`
	OutputTokens     int            `json:"output_tokens"`
	TotalTokens      int            `json:"total_tokens"`
	CostUSD          float64        `json:"cost_usd"`
	ReasoningTokens  int            `json:"reasoning_tokens"`
	CacheReadTokens  int            `json:"cache_read_tokens"`
	CacheWriteTokens int            `json:"cache_write_tokens"`
	Provider         string         `json:"provider,omitempty"`
	// Estimated is true when the token/cost numbers come from a heuristic
	// rather than metered usage (e.g. the ACP backend's rune-count
	// estimator). Downstream consumers — CLI summary, TUI header, tracker
	// diagnose — use this to mark provider rollups with an "(estimated)"
	// suffix so operators don't confuse approximate spend with metered
	// spend. EstimateSource names the heuristic (e.g. "acp-chars-heuristic")
	// and is reserved for future per-source reporting. Derived in
	// buildSessionStats from llm.Usage.Raw.
	Estimated      bool   `json:"estimated,omitempty"`
	EstimateSource string `json:"estimate_source,omitempty"`
	// BreachVerify is the verify-on-breach result (#303): 0=not-run, 1=passed,
	// 2=failed. Mirrors agent.BreachVerifyState as an int so the trace JSON is
	// self-contained. Non-zero only on a turn-limit breach under guard policy.
	BreachVerify int `json:"breach_verify,omitempty"`
}

type StyleRule struct {
	Selector   string
	Properties map[string]string
}

type Stylesheet struct {
	Rules []StyleRule
}

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

type TerminalStatus string

type ToolNodeConfig struct {
	Command     string
	OutputLimit int // bytes; 0 means use default
	WorkingDir  string
	PassEnv     string        // comma-separated env var names to pass through
	Timeout     time.Duration // raw parsed timeout from node attrs; zero means the attr was absent, unparseable, or parsed to 0. ToolHandler.parseTimeout rejects non-positive values at execution time.
	MarkerGrep  string        // regex applied to captured stdout to extract a routing marker into ctx.tool_marker (issue #210). Empty disables. If non-empty and no match, the node fails with OutcomeFail and an EventToolMarkerMissing audit event is emitted.
	// RouteRequired is true when the node MUST receive a _TRACKER_ROUTE=
	// sentinel line in its captured stdout (issue #212). Sentinel
	// extraction itself runs unconditionally; this flag controls whether
	// the absence of a match fails the node. When true, no match →
	// OutcomeFail + EventToolRouteMissing. Symmetric to marker_grep's
	// failure path, but the matcher is built-in (no per-node regex).
	RouteRequired bool
}

type Trace struct {
	RunID     string       `json:"run_id"`
	Entries   []TraceEntry `json:"entries"`
	StartTime time.Time    `json:"start_time"`
	EndTime   time.Time    `json:"end_time"`
}

type TraceEntry struct {
	Timestamp   time.Time     `json:"timestamp"`
	NodeID      string        `json:"node_id"`
	HandlerName string        `json:"handler_name"`
	Status      string        `json:"status"`
	Duration    time.Duration `json:"duration"`
	EdgeTo      string        `json:"edge_to,omitempty"`
	Error       string        `json:"error,omitempty"`
	Stats       *SessionStats `json:"stats,omitempty"`
	// ChildUsage is the aggregated usage of a child run that executed under
	// this node (subgraph, manager_loop). Populated when the handler's
	// Outcome carries child-run totals so AggregateUsage can include them
	// in the parent's rollup. Omitted from JSON when nil.
	ChildUsage *UsageSummary `json:"child_usage,omitempty"`
	// WIPRef is the recoverable git ref (tag tracker/wip/<runID>/<nodeID>)
	// where this node's uncommitted work was preserved before the engine
	// routed away from a failure/exhaustion (#302). Empty when the tree was
	// clean or no git artifact adapter was configured.
	WIPRef string `json:"wip_ref,omitempty"`
}

type TruncationDetail struct {
	Stream        string `json:"stream"`         // "stdout" or "stderr"
	Limit         int    `json:"limit"`          // per-stream cap in effect
	CapturedBytes int    `json:"captured_bytes"` // bytes preserved in the captured tail
	DroppedBytes  int    `json:"dropped_bytes"`  // bytes elided from the head
	TotalBytes    int    `json:"total_bytes"`    // CapturedBytes + DroppedBytes for convenience
}

type UsageSummary struct {
	TotalInputTokens      int                      `json:"total_input_tokens"`
	TotalOutputTokens     int                      `json:"total_output_tokens"`
	TotalTokens           int                      `json:"total_tokens"`
	TotalCostUSD          float64                  `json:"total_cost_usd"`
	TotalReasoningTokens  int                      `json:"total_reasoning_tokens"`
	TotalCacheReadTokens  int                      `json:"total_cache_read_tokens"`
	TotalCacheWriteTokens int                      `json:"total_cache_write_tokens"`
	SessionCount          int                      `json:"session_count"`
	ProviderTotals        map[string]ProviderUsage `json:"provider_totals,omitempty"`
	Estimated             bool                     `json:"estimated,omitempty"`
}

type ValidationError struct {
	Errors   []string
	Warnings []string
}