tracker

type ActivityEntry struct {
	Timestamp time.Time
	// Source is the emitting subsystem: "pipeline" (engine), "agent" (LLM
	// session), "llm" (raw provider events), or "cli" (CLI-level audit).
	Source  string
	Type    string
	RunID   string
	NodeID  string
	Message string
	Error   string
	// Identity of the emitting LLM call / tool, and its payload text
	// (tool output or response preview). Set on agent and llm lines.
	Provider string
	Model    string
	ToolName string
	Content  string
	// BundleIdentity is the content-addressed identity of the .dipx bundle
	// the run executed against ("sha256:<hex>"); empty for a plain .dip run.
	BundleIdentity string

	// Decision fields — populated for decision_edge / decision_condition /
	// decision_outcome / decision_restart / conditional_fallthrough entries.
	EdgeFrom        string
	EdgeTo          string
	EdgeCondition   string
	EdgePriority    string
	ConditionMatch  *bool
	OutcomeStatus   string
	ContextSnapshot map[string]string
	ContextUpdates  map[string]string
	RestartCount    *int
	ClearedNodes    []string
	ConditionsTried []pipeline.ConditionEval
	// TokenInput / TokenOutput are the node's session token counts on a
	// decision entry — never run-cumulative (that is TotalTokens).
	TokenInput  int
	TokenOutput int
	// TokenCacheRead / TokenCacheWrite / TurnCostUSD are the per-turn agent
	// usage extras carried on agent turn_metrics / llm_finish entries (#508);
	// they mirror the same-named StreamEvent fields. Zero on decision entries.
	TokenCacheRead  int
	TokenCacheWrite int
	TurnCostUSD     float64

	// Cost snapshot fields — populated for cost_updated and budget_exceeded
	// entries. Run-cumulative, not per-node. Estimated is true when any
	// contributing session was heuristic-derived.
	TotalTokens    int
	TotalCostUSD   float64
	ProviderTotals map[string]pipeline.ProviderUsage
	WallElapsedMs  int64
	Estimated      bool

	// Truncation fields — populated for tool_output_truncated entries (#208).
	TruncStream   string
	TruncLimit    int
	TruncCaptured int
	TruncDropped  int
	TruncTotal    int

	// Marker fields — populated for tool_marker_missing entries (#210).
	MarkerPattern string
	MarkerTail    string
	MarkerError   string

	// RouteTail is populated for tool_route_missing entries (#212).
	RouteTail string

	// Auto-status fields — populated for auto_status_missing entries (#346).
	AutoStatusTail       string
	AutoStatusFailClosed bool

	// Override fields — populated for "validation_overridden" entries.
	// Mirror the wire-format fields written by the runtime's
	// jsonlLogEntry (see pipeline/events_jsonl.go): the gate that
	// produced the override, the label that selected the override
	// edge, who acted, and the subgraph_path when propagated up from
	// a child run. Empty for non-override entries.
	OverrideGate         string
	OverrideLabel        string
	OverrideActor        pipeline.Actor
	OverrideSubgraphPath []string

	// Gate lifecycle fields — populated for gate_opened / gate_resolved
	// entries (#509). GateID correlates the pair; NodeID identifies the gate
	// node on both. Open-time: GateMode, GateLabel, GatePrompt, GateChoices,
	// GateQuestions. Resolve-time: GateResponse, GateOutcome, GateActor,
	// GateTimedOut (plus Error when the gate failed to collect an answer).
	GateID        string
	GateMode      string
	GateLabel     string
	GatePrompt    string
	GateChoices   []string
	GateQuestions []pipeline.GateQuestion
	GateResponse  string
	GateOutcome   string
	GateActor     pipeline.Actor
	GateTimedOut  bool
}

type ActivityError struct {
	Timestamp time.Time `json:"ts"`
	NodeID    string    `json:"node_id,omitempty"`
	Message   string    `json:"message"`
}

type ActivityLogScan struct {
	Path          string
	SecureUsed    bool
	Entries       []ActivityEntry
	InjectedLines int
	TotalLines    int
	SentinelLines int
}

type AuditConfig struct {
	// LogWriter receives non-fatal warnings (unreadable activity.jsonl
	// in a run directory, etc.). Nil is treated as io.Discard so
	// embedded library callers do not see warnings on os.Stderr. The
	// tracker CLI sets this to io.Discard for user-facing commands.
	LogWriter io.Writer
}

type AuditReport struct {
	RunID string `json:"run_id"`
	// Status is one of:
	//   - "success"
	//   - "fail"
	//   - "budget_exceeded"
	//   - "validation_overridden"
	//   - "paused_billing"
	// The enum is open — future minor releases may add new values. Consumers
	// should use StatusClass for stable {succeeded|failed|paused} bucketing.
	// See classifyStatus for the resolution algorithm.
	Status string `json:"status"`
	// StatusClass is one of "succeeded", "failed", or "paused" — stable
	// companion to Status for downstream consumers that need bucket
	// categorization that survives future enum extensions. "paused" flags the
	// recoverable, resumable paused_billing terminal (#514); everything else is
	// classified via pipeline.TerminalStatus(Status).IsSuccess().
	StatusClass string `json:"status_class"`
	// TotalDuration is encoded as integer nanoseconds in JSON
	// ("total_duration_ns"), not as a duration string.
	TotalDuration   time.Duration   `json:"total_duration_ns"`
	Timeline        []TimelineEntry `json:"timeline"`
	Retries         []RetryRecord   `json:"retries,omitempty"`
	Errors          []ActivityError `json:"errors,omitempty"`
	Recommendations []string        `json:"recommendations,omitempty"`
	// CompletedNodes is the number of completed nodes recorded in checkpoint.json.
	CompletedNodes int `json:"completed_nodes"`
	// RestartCount is the checkpoint restart counter for the run.
	RestartCount int `json:"restart_count"`
	// CheckpointTimestamp is the last checkpoint write time.
	CheckpointTimestamp time.Time `json:"checkpoint_timestamp"`
	// BundleIdentity is the content-addressed identity ("sha256:<hex>") of
	// the .dipx bundle the run was executed against. Read from the run's
	// checkpoint. Empty for runs from a plain .dip file.
	BundleIdentity string `json:"bundle_identity,omitempty"`
	// ValidationOverrides is populated when one or more override edges were
	// traversed during the run. Sourced from activity-log
	// EventValidationOverridden entries (chronological order); falls back to
	// Checkpoint.ValidationOverrides when the activity log carries no
	// override entries. Empty for runs with no override edges.
	ValidationOverrides []pipeline.OverrideDetail `json:"validation_overrides,omitempty"`
	// OverrideCount is len(ValidationOverrides). Kept as its own field so
	// thin consumers can read it without unmarshaling the slice.
	OverrideCount int `json:"override_count,omitempty"`
}

type BudgetHalt struct {
	TotalTokens   int     `json:"total_tokens"`
	TotalCostUSD  float64 `json:"total_cost_usd"`
	WallElapsedMs int64   `json:"wall_elapsed_ms"`
	Message       string  `json:"message"`
}

type CheckDetail struct {
	Status  CheckStatus `json:"status"` // "ok" | "warn" | "error" | "hint"
	Message string      `json:"message"`
	Hint    string      `json:"hint,omitempty"`
}

type CheckResult struct {
	Name    string        `json:"name"`
	Status  CheckStatus   `json:"status"` // "ok" | "warn" | "error" | "skip"
	Message string        `json:"message,omitempty"`
	Hint    string        `json:"hint,omitempty"`
	Details []CheckDetail `json:"details,omitempty"`
}

type CheckStatus string

type Config struct {
	WorkingDir    string // default: os.Getwd()
	CheckpointDir string // checkpoint file path (checkpoint.json); default: empty (engine auto-generates)
	ResumeRunID   string // optional: resume a previous run by ID or unique prefix; resolved via ResolveCheckpoint
	ArtifactDir   string // default: empty (engine auto-generates)
	// GitArtifacts, when true, makes the artifact dir a git repo and commits
	// after every terminal node outcome (the basis for branch-per-run / PR
	// delivery and portable ExportBundle history). Requires git in PATH and is
	// a no-op unless ArtifactDir is set. Off by default.
	GitArtifacts bool
	Format       string                        // "dip" (default), "dot" (deprecated); empty = auto-detect
	Model        string                        // default: env or claude-sonnet-4-6; graph-level attrs take precedence
	Provider     string                        // default: auto-detect from env
	RetryPolicy  string                        // "none" (default), "standard", "aggressive"; graph-level attrs take precedence
	EventHandler pipeline.PipelineEventHandler // optional: live pipeline events
	AgentEvents  agent.EventHandler            // optional: live agent session events
	// LLMTrace attaches a raw-trace observer to the auto-created client or a
	// *llm.Client passed as LLMClient. A custom agent.Completer carries no
	// observable transport, so LLMTrace is a no-op there (as is TokenTracker).
	LLMTrace  llm.TraceObserver // optional: raw LLM trace events
	LLMClient agent.Completer   // optional: override auto-created client
	// TokenTracker optionally injects the per-provider token/cost tracker instead
	// of the engine creating its own. An in-process transport that renders spend
	// (the TUI) shares one tracker between its view model and the engine. The
	// engine attaches it idempotently — re-adding the same tracker to a supplied
	// *llm.Client is skipped, so usage is never double-counted.
	TokenTracker *llm.TokenTracker
	Context      map[string]string // optional: initial pipeline context
	Params       map[string]string // optional: override declared workflow params (keys without "params." prefix)
	// Subgraphs are pre-loaded child graphs keyed by subgraph_ref, for a graph
	// with subgraph nodes; nil/empty for flat pipelines. See NewEngineFromGraph.
	Subgraphs map[string]*pipeline.Graph
	Backend   string // "native" (default), "claude-code", "acp"; selects agent backend
	// ToolSafety overrides the tool-handler security config (denylist/allowlist,
	// output limits, env passthrough); nil uses the registry defaults.
	ToolSafety  *handlers.ToolHandlerConfig
	Autopilot   string                // "" (interactive), "lax", "mid", "hard", "mentor"; LLM-driven gate decisions
	AutoApprove bool                  // auto-approve all human gates with default/first option
	Budget      pipeline.BudgetLimits // configures pipeline-level token, cost, and wall-time ceilings
	// GatewayURL is the root URL of a Cloudflare AI Gateway (or any compatible
	// proxy). When non-empty it is used as the base for all provider URLs, with
	// the per-provider suffix appended (e.g. "<gateway>/anthropic"). A
	// per-provider *_BASE_URL env var always takes precedence over GatewayURL so
	// library callers can still override individual providers. The TRACKER_GATEWAY_URL
	// env var is the fallback when GatewayURL is empty.
	GatewayURL string
	// GatewayKind selects the path convention used with GatewayURL (or its
	// TRACKER_GATEWAY_URL env-var fallback). Empty or GatewayKindCFAIG
	// (default, backcompat) routes via Cloudflare AI Gateway conventions:
	// /anthropic, /openai, /google-ai-studio, /compat. GatewayKindBedrock
	// targets the 2389 bedrock-gateway Worker which uses native SDK paths.
	// The TRACKER_GATEWAY_KIND env var is the fallback when GatewayKind is
	// empty. See ResolveProviderBaseURL.
	GatewayKind GatewayKind
	// Interviewer optionally injects a custom in-process human-gate handler.
	// This is the seam for interactive transports (TUI, Slack, web, mobile):
	// the transport implements handlers.Interviewer and, optionally, the richer
	// handlers.FreeformInterviewer / LabeledFreeformInterviewer /
	// InterviewInterviewer extensions plus the optional Actor() / Cancel() /
	// ContextSetter side-interfaces — the human handler upgrades via type
	// assertion and picks the richest supported mode. When set, it takes
	// precedence over AutoApprove, WebhookGate, and Autopilot. Nil is a no-op.
	Interviewer handlers.Interviewer
	WebhookGate *WebhookGateConfig // optional: post human gates to an HTTP webhook and wait for callback
	// BundleIdentity is the content-addressed identity ("sha256:<hex>") of
	// the .dipx bundle this run was loaded from. Stamped onto every emitted
	// PipelineEvent and persisted to the checkpoint for resume verification.
	// Empty (the default) is a no-op and matches plain .dip behavior.
	//
	// Callers that build their own JSONLEventHandler should also call
	// activityLog.SetBundleIdentity(cfg.BundleIdentity) so agent/llm writes
	// outside the engine event chain carry the same provenance.
	BundleIdentity string
	// Git configures the v0.29.0 git preflight check. Nil = auto, which
	// respects the workflow's `requires:` block. See GitConfig.
	Git *GitConfig
	// SteeringChan optionally injects mid-run context updates from an external
	// supervisor (a chat "steer" command, a web control, a manager loop). Each
	// map sent on it is merged into the pipeline context between node
	// executions, so steered values are visible to the next node's edge
	// selection and prompt expansion. Values are namespaced by the sender
	// (e.g. "steer.guidance"); a workflow references them like any context key.
	// Nil disables steering. The channel is drained non-blockingly — sends never
	// block the engine, and updates surface at the next inter-node boundary.
	SteeringChan <-chan map[string]string
}

type CostReport struct {
	TotalUSD   float64
	ByProvider map[string]llm.ProviderCost
	LimitsHit  []string
}

type DiagnoseConfig struct {
	// LogWriter receives non-fatal parse/read warnings — specifically
	// malformed status.json content (one warning per bad file) and
	// bufio.Scanner errors while reading activity.jsonl (e.g. lines
	// exceeding the 1 MB buffer limit, I/O failures). Nil is treated
	// as io.Discard so library callers do not see stray warnings on
	// os.Stderr. The tracker CLI sets this to io.Discard for user-
	// facing commands.
	LogWriter io.Writer
}

type DiagnoseReport struct {
	RunID          string      `json:"run_id"`
	CompletedNodes int         `json:"completed_nodes"`
	BudgetHalt     *BudgetHalt `json:"budget_halt,omitempty"`
	// ValidationOverrides is the list of override edges traversed during the run.
	// Sourced from activity log first, with checkpoint fallback for runs whose
	// activity log is missing (legacy / archived). Empty for runs with no
	// override edges. Populated for every terminal status (success, fail,
	// budget_exceeded, validation_overridden) so override forensics survive
	// failure-after-override scenarios. Per spec §9.4 the override section in
	// `tracker diagnose` is informational only — override is NOT a failure and
	// does NOT raise a Suggestion of its own.
	ValidationOverrides []pipeline.OverrideDetail `json:"validation_overrides,omitempty"`
	// OverrideCount is len(ValidationOverrides). Kept as its own field so
	// JSON consumers can branch without iterating the slice.
	OverrideCount int           `json:"override_count,omitempty"`
	Failures      []NodeFailure `json:"failures"`
	Suggestions   []Suggestion  `json:"suggestions"`
}

type DoctorConfig struct {
	// WorkDir is the working directory to check. If empty, os.Getwd() is used.
	WorkDir string
	// Backend is the agent backend ("", "native", "claude-code"). When
	// "claude-code", a missing claude binary is a hard error.
	Backend string
	// ProbeProviders, when true, makes a minimal network call to each
	// configured provider to verify auth. Default false — key presence only.
	ProbeProviders bool
	// PipelineFile, when non-empty, adds a "Pipeline File" check that parses
	// and validates the given .dip / .dot file.
	PipelineFile string
	// contains filtered or unexported fields
}

type DoctorOption func(*DoctorConfig)

type DoctorReport struct {
	Checks   []CheckResult `json:"checks"`
	OK       bool          `json:"ok"`
	Warnings int           `json:"warnings"`
	Errors   int           `json:"errors"`
}

type DuplicateTestGroup struct {
	Kind  string         `json:"kind"` // "identical" | "near-identical"
	Tests []TestLocation `json:"tests"`
}

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

type FailureCause struct {
	Kind      string // "billing" | "auth" | "rate_limit" | "context_length" | "network" | "timeout" | "config" | "content_filter" | "generic"
	Icon      string
	Title     string // the headline — the most important, actionable thing
	Detail    string // the underlying cause (e.g. the provider message), may be ""
	NextSteps string // what the user should do, may be ""
}

type GatewayKind string

type GitConfig struct {
	Preflight GitPreflight
	AllowInit bool
}

type GitPreflight = pipeline.GitPreflight

type ManagedRun struct {
	Key     string // caller-chosen external id (e.g. a Slack thread_ts)
	WorkDir string // isolated working directory for this run
	// contains filtered or unexported fields
}

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

type NodeFailure struct {
	NodeID  string `json:"node_id"`
	Outcome string `json:"outcome"`
	Handler string `json:"handler,omitempty"`
	// Duration is the elapsed time for the most recent attempt of the node.
	// It is encoded as integer nanoseconds in JSON ("duration_ns"), not
	// as a duration string.
	Duration time.Duration `json:"duration_ns,omitempty"`
	// RetryCount is the number of stage_failed events observed for this node
	// — i.e., the total failure count, not "retries beyond the first attempt."
	// A node that failed once (no retry) has RetryCount == 1.
	RetryCount int `json:"retry_count,omitempty"`
	// IdenticalRetries is true when every stage_failed event had the same
	// error/tool_error signature — a deterministic bug, not a flaky one.
	IdenticalRetries bool     `json:"identical_retries,omitempty"`
	Stdout           string   `json:"stdout,omitempty"`
	Stderr           string   `json:"stderr,omitempty"`
	Errors           []string `json:"errors,omitempty"`
}

type PlanStep struct {
	Step   int       `json:"step"`
	NodeID string    `json:"node_id"`
	Edges  []SimEdge `json:"edges,omitempty"`
}

type Result struct {
	RunID string
	// Status carries the run's terminal status. Known values today:
	//   - "success"
	//   - "fail"
	//   - "budget_exceeded"
	//   - "validation_overridden"
	//   - "paused_billing" — recoverable provider credit/quota exhaustion: the
	//     checkpoint is saved and in-flight work preserved, so the run resumes
	//     from the paused node (Config.ResumeRunID / `tracker -r`) once credits
	//     are topped up. Not a failure; offer resume, not a from-scratch redo.
	// The enum is OPEN — future minor releases may add new values, so never
	// switch exhaustively on the raw string. Use
	// pipeline.TerminalStatus(r.Status).IsSuccess() to classify (fail-closed).
	Status           string
	CompletedNodes   []string
	Context          map[string]string
	EngineResult     *pipeline.EngineResult
	Trace            *pipeline.Trace      // full execution trace (nodes, timing, stats)
	TokensByProvider map[string]llm.Usage // per-provider token totals
	ToolCallsByName  map[string]int       // tool call counts by name
	Cost             *CostReport          // per-provider cost rollup; nil when no usage recorded
	// ArtifactRunDir is the run-specific artifact directory (e.g.
	// "<artifactDir>/<runID>"). Populated when WithArtifactDir is set via
	// Config.ArtifactDir. Pass this to ExportBundle to create a portable
	// git bundle of the run's history.
	ArtifactRunDir string
	// BundlePath is the path of the exported git bundle. Populated only when
	// ExportBundle is invoked by the caller after Run completes.
	BundlePath string
	// BundleIdentity is the content-addressed identity ("sha256:<hex>") of
	// the .dipx bundle the run was loaded from, mirrored from Config.BundleIdentity
	// for the caller's convenience. Empty for plain .dip runs.
	BundleIdentity string
	// ValidationOverrides is the list of override edges traversed during the run.
	// Empty for runs with no override edges. Populated for every terminal status
	// (including fail and budget_exceeded) so forensics see overrides even when
	// failure dominates.
	ValidationOverrides []pipeline.OverrideDetail
}

type RetryRecord struct {
	NodeID   string `json:"node_id"`
	Attempts int    `json:"attempts"`
}

type RunEstimate struct {
	Steps       int      `json:"steps"`        // execution-plan length
	AgentNodes  int      `json:"agent_nodes"`  // LLM agent nodes
	Models      []string `json:"models"`       // distinct models, sorted
	LowUSD      float64  `json:"low_usd"`      // ~1 turn per agent node
	ExpectedUSD float64  `json:"expected_usd"` // a typical fraction of max turns
	HighUSD     float64  `json:"high_usd"`     // max turns per agent node
}

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

type RunManagerOption func(*RunManager)

type RunState string

type RunSummary struct {
	RunID string `json:"run_id"`
	// Status is one of: "success", "fail", "budget_exceeded",
	// "validation_overridden", "paused_billing". Open enum; prefer StatusClass
	// for stable {succeeded|failed|paused} bucketing. See classifyStatus for the
	// resolution algorithm.
	Status string `json:"status"`
	// StatusClass is one of "succeeded", "failed", or "paused" — stable
	// companion to Status. "paused" flags paused_billing (#514); everything else
	// is classified via pipeline.TerminalStatus(Status).IsSuccess().
	StatusClass string    `json:"status_class"`
	Nodes       int       `json:"nodes"`
	Retries     int       `json:"retries"`
	Restarts    int       `json:"restarts"`
	Timestamp   time.Time `json:"timestamp"`
	// Duration is encoded as integer nanoseconds in JSON ("duration_ns"),
	// not as a duration string.
	Duration time.Duration `json:"duration_ns"`
	// FailedAt is the node ID where the run halted, populated for both
	// "fail" and "budget_exceeded" runs (Gap 5.2: budget-halted runs are
	// no longer classified as "fail", so the gate also fires on
	// "budget_exceeded").
	FailedAt string `json:"failed_at,omitempty"`
	// BundleIdentity is the content-addressed identity ("sha256:<hex>") of
	// the .dipx bundle the run was executed against. Read from the run's
	// checkpoint at summary-build time. Empty for runs from a plain .dip file.
	BundleIdentity string `json:"bundle_identity,omitempty"`
	// OverrideCount is the number of override edges traversed in this run.
	// Sourced from activity log when present, else
	// len(Checkpoint.ValidationOverrides). RunSummary stays thin — for the
	// full OverrideDetail slice see AuditReport.ValidationOverrides.
	OverrideCount int `json:"override_count,omitempty"`
}

type SimEdge struct {
	From      string `json:"from"`
	To        string `json:"to"`
	Label     string `json:"label,omitempty"`
	Condition string `json:"condition,omitempty"`
}

type SimNode struct {
	ID      string            `json:"id"`
	Handler string            `json:"handler,omitempty"`
	Shape   string            `json:"shape,omitempty"`
	Label   string            `json:"label,omitempty"`
	Attrs   map[string]string `json:"attrs,omitempty"`
}

type SimulateReport struct {
	Format        string            `json:"format"`
	Name          string            `json:"name,omitempty"`
	StartNode     string            `json:"start_node,omitempty"`
	ExitNode      string            `json:"exit_node,omitempty"`
	GraphAttrs    map[string]string `json:"graph_attrs,omitempty"`
	Nodes         []SimNode         `json:"nodes"`
	Edges         []SimEdge         `json:"edges"`
	ExecutionPlan []PlanStep        `json:"execution_plan"`
	Unreachable   []string          `json:"unreachable,omitempty"`
}

type StatusEntry struct {
	Timestamp string `json:"ts"`
	NodeID    string `json:"node_id,omitempty"`
	Text      string `json:"text"`
}

type StreamEvent struct {
	Timestamp string `json:"ts"`
	Source    string `json:"source"`              // "pipeline", "llm", "agent"
	Type      string `json:"type"`                // event type within source
	RunID     string `json:"run_id,omitempty"`    // pipeline run ID
	NodeID    string `json:"node_id,omitempty"`   // pipeline node ID
	Message   string `json:"message,omitempty"`   // human-readable message
	Error     string `json:"error,omitempty"`     // error text
	Provider  string `json:"provider,omitempty"`  // LLM provider
	Model     string `json:"model,omitempty"`     // LLM model
	ToolName  string `json:"tool_name,omitempty"` // tool name for agent/LLM tool events
	Content   string `json:"content,omitempty"`   // text content (LLM output, tool output)
	// TerminalStatus is set only on a pipeline run's terminal event
	// (pipeline_completed / pipeline_failed / budget_exceeded): "success",
	// "validation_overridden", "fail", or "budget_exceeded". Empty otherwise.
	TerminalStatus string `json:"terminal_status,omitempty"`
	// BundleIdentity is the content-addressed identity of the .dipx bundle the
	// run executes against ("sha256:<hex>"). Set on pipeline events of a bundle
	// run; empty for a plain .dip run.
	BundleIdentity string `json:"bundle_identity,omitempty"`

	// Decision fields — set on decision_edge / decision_condition /
	// decision_outcome / decision_restart / conditional_fallthrough events, from
	// pipeline.DecisionDetail. ConditionMatch and RestartCount are pointers so a
	// consumer can distinguish "false"/"0" from "not carried".
	EdgeFrom        string                   `json:"edge_from,omitempty"`
	EdgeTo          string                   `json:"edge_to,omitempty"`
	EdgeCondition   string                   `json:"edge_condition,omitempty"`
	EdgePriority    string                   `json:"edge_priority,omitempty"`
	ConditionMatch  *bool                    `json:"condition_match,omitempty"`
	OutcomeStatus   string                   `json:"outcome_status,omitempty"`
	ContextSnapshot map[string]string        `json:"context_snapshot,omitempty"`
	ContextUpdates  map[string]string        `json:"context_updates,omitempty"`
	RestartCount    *int                     `json:"restart_count,omitempty"`
	ClearedNodes    []string                 `json:"cleared_nodes,omitempty"`
	ConditionsTried []pipeline.ConditionEval `json:"conditions_tried,omitempty"`

	// TokenInput / TokenOutput carry the token counts of whatever the event
	// describes: the node's session stats on a pipeline decision event, the
	// turn's usage on an agent turn_metrics / llm_finish event. They are never
	// run-cumulative — that is total_tokens below.
	TokenInput  int `json:"token_input,omitempty"`
	TokenOutput int `json:"token_output,omitempty"`
	// TokenCacheRead / TokenCacheWrite / TurnCostUSD are the per-turn agent
	// extras (turn_metrics, llm_finish). No activity.jsonl counterpart.
	TokenCacheRead  int     `json:"token_cache_read,omitempty"`
	TokenCacheWrite int     `json:"token_cache_write,omitempty"`
	TurnCostUSD     float64 `json:"turn_cost_usd,omitempty"`

	// Cost snapshot fields — set on cost_updated and budget_exceeded events,
	// from pipeline.CostSnapshot. Run-cumulative, not per-node. Estimated is
	// true when any contributing session was heuristic-derived.
	TotalTokens    int                               `json:"total_tokens,omitempty"`
	TotalCostUSD   float64                           `json:"total_cost_usd,omitempty"`
	ProviderTotals map[string]pipeline.ProviderUsage `json:"provider_totals,omitempty"`
	WallElapsedMs  int64                             `json:"wall_elapsed_ms,omitempty"`
	Estimated      bool                              `json:"estimated,omitempty"`

	// Truncation fields — set on tool_output_truncated events (#208).
	TruncStream   string `json:"trunc_stream,omitempty"`
	TruncLimit    int    `json:"trunc_limit,omitempty"`
	TruncCaptured int    `json:"trunc_captured_bytes,omitempty"`
	TruncDropped  int    `json:"trunc_dropped_bytes,omitempty"`
	TruncTotal    int    `json:"trunc_total_bytes,omitempty"`

	// Marker fields — set on tool_marker_missing events (#210).
	MarkerPattern string `json:"marker_pattern,omitempty"`
	MarkerTail    string `json:"marker_tail,omitempty"`
	MarkerError   string `json:"marker_error,omitempty"`

	// RouteTail is set on tool_route_missing events (#212).
	RouteTail string `json:"route_tail,omitempty"`

	// Auto-status fields — set on auto_status_missing events (#346).
	AutoStatusTail       string `json:"auto_status_tail,omitempty"`
	AutoStatusFailClosed bool   `json:"auto_status_fail_closed,omitempty"`

	// Override fields — set on validation_overridden events.
	OverrideGate         string         `json:"override_gate,omitempty"`
	OverrideLabel        string         `json:"override_label,omitempty"`
	OverrideActor        pipeline.Actor `json:"override_actor,omitempty"`
	OverrideSubgraphPath []string       `json:"override_subgraph_path,omitempty"`

	// GateID is set only on the gate lifecycle events (gate_opened /
	// gate_resolved) and correlates the pair (#509). NodeID identifies the gate
	// node on both.
	GateID string `json:"gate_id,omitempty"`
	// Gate payload fields, from pipeline.GateDetail. Open-time: GateMode,
	// GateLabel, GatePrompt, GateChoices, GateQuestions. Resolve-time:
	// GateResponse, GateOutcome, GateActor, GateTimedOut (plus Error above when
	// the gate failed to collect an answer). GateMode is repeated on the
	// resolution so GateResponse can be interpreted without joining.
	GateMode      string                  `json:"gate_mode,omitempty"`
	GateLabel     string                  `json:"gate_label,omitempty"`
	GatePrompt    string                  `json:"gate_prompt,omitempty"`
	GateChoices   []string                `json:"gate_choices,omitempty"`
	GateQuestions []pipeline.GateQuestion `json:"gate_questions,omitempty"`
	GateResponse  string                  `json:"gate_response,omitempty"`
	GateOutcome   string                  `json:"gate_outcome,omitempty"`
	GateActor     pipeline.Actor          `json:"gate_actor,omitempty"`
	GateTimedOut  bool                    `json:"gate_timed_out,omitempty"`

	// Run snapshot fields — set on pipeline_started, from pipeline.RunSnapshot:
	// the top-level node inventory (sorted by ID, not execution order) plus
	// resume state, so a subscriber joining at run start can seed its progress
	// model without separate access to the graph or checkpoint.
	// SnapshotCurrentNode / SnapshotCompletedNodes are populated only on resume.
	// No activity.jsonl counterpart — these names are new.
	SnapshotNodes          []StreamSnapshotNode `json:"snapshot_nodes,omitempty"`
	SnapshotStartNode      string               `json:"snapshot_start_node,omitempty"`
	SnapshotExitNode       string               `json:"snapshot_exit_node,omitempty"`
	SnapshotCurrentNode    string               `json:"snapshot_current_node,omitempty"`
	SnapshotCompletedNodes []string             `json:"snapshot_completed_nodes,omitempty"`
}

type StreamSnapshotNode struct {
	ID      string `json:"id"`
	Label   string `json:"label,omitempty"`
	Handler string `json:"handler,omitempty"`
}

type Suggestion struct {
	NodeID  string         `json:"node_id,omitempty"`
	Kind    SuggestionKind `json:"kind"`
	Message string         `json:"message"`
}

type SuggestionKind string

type TestFidelityReport struct {
	// DuplicateGroups are sets of ≥2 test functions with the same body. "identical"
	// = byte-for-byte equal bodies; "near-identical" = equal after normalizing
	// literal values (so tests differing only in a string/number collide).
	DuplicateGroups []DuplicateTestGroup `json:"duplicate_groups,omitempty"`
}

type TestLocation struct {
	Name string `json:"name"`
	File string `json:"file"`
	Line int    `json:"line"`
}

type TimelineEntry struct {
	Timestamp time.Time `json:"ts"`
	Type      string    `json:"type"`
	NodeID    string    `json:"node_id,omitempty"`
	Message   string    `json:"message,omitempty"`
	// Duration is encoded as integer nanoseconds in JSON ("duration_ns"),
	// not as a duration string.
	Duration time.Duration `json:"duration_ns,omitempty"`
}

type ValidateOption func(*validateConfig)

type ValidationResult struct {
	Graph    *pipeline.Graph
	Errors   []string
	Warnings []string
	Hints    []string
}

type WebhookGateConfig struct {
	WebhookURL    string        // required: URL to post gate payloads to
	CallbackAddr  string        // local listen addr for callback server (default: :0, an OS-assigned ephemeral port; the bound address is advertised via each gate's callback_url)
	Timeout       time.Duration // wait timeout per gate (default: 10m)
	TimeoutAction string        // "fail" (default) or "success" on timeout
	AuthHeader    string        // Authorization header for outbound requests
	RunID         string        // optional: run ID embedded in gate payloads
}

type WorkflowInfo struct {
	Name        string   // bare name used for lookup, e.g. "build_product"
	File        string   // path within the embedded FS, e.g. "examples/build_product.dip"
	DisplayName string   // workflow declaration name, e.g. "BuildProduct"
	Goal        string   // parsed from the goal: field at the top of the .dip file
	Requires    []string // parsed from the `requires:` field (v0.29.0); nil if not declared
}