policy

type CapsState struct {
	// MaxToolCalls is the total allowed tool invocations for the run. Zero means
	// unlimited. Configured per-agent in the design via RunPolicy.
	MaxToolCalls int

	// RemainingToolCalls tracks how many tool invocations are still allowed. The
	// runtime decrements this after each tool execution (success or failure).
	// When this reaches zero, no more tool calls are permitted.
	RemainingToolCalls int

	// MaxConsecutiveFailedToolCalls caps consecutive failures per run. Zero means
	// unlimited. Used for circuit breaking: if N tools fail in a row, terminate.
	MaxConsecutiveFailedToolCalls int

	// RemainingConsecutiveFailedToolCalls tracks how many consecutive failures are allowed
	// before circuit breaking. The runtime decrements this on each failure and resets
	// it to MaxConsecutiveFailedToolCalls on success. When this reaches zero, the
	// run is terminated.
	RemainingConsecutiveFailedToolCalls int

	// ExpiresAt conveys when the run-level budgets expire (wall-clock deadline).
	// Zero means no deadline. The runtime terminates the workflow if time.Now()
	// exceeds this timestamp. Configured per-agent via RunPolicy.TimeBudget.
	ExpiresAt time.Time
}

type Decision struct {
	// AllowedTools is the final allowlist of tools for this turn. The runtime
	// ensures planners can only invoke tools in this list. Empty means no tools
	// are allowed (planner must produce a final response).
	AllowedTools []tools.Ident

	// Caps carries the updated caps that should be enforced for this turn and
	// subsequent turns. Policies can decrement counts (consume budget) or adjust
	// limits based on observed behavior.
	Caps CapsState

	// DisableTools signals that no further tool calls should be executed for this
	// run. If true, the runtime forces the planner to produce a final response or
	// terminates with an error. Used for circuit breaking or budget exhaustion.
	DisableTools bool

	// Labels allows policies to annotate downstream telemetry, memory, or hooks.
	// These labels are merged into the RunContext and propagated to subsequent
	// turns. Example: {"policy_applied": "failure_circuit_breaker"}.
	Labels map[string]string

	// Metadata captures policy-specific information (e.g., reason codes, approval IDs)
	// that should be persisted for audit trails or surfaced via hooks. The runtime
	// stores this alongside run records and emits it in policy decision events.
	Metadata map[string]any
}

type Engine interface {
	// Decide evaluates policy constraints and returns the decision for this turn.
	// The runtime passes candidate tools, remaining caps, retry hints, and context.
	// Returns an error if the policy engine fails (e.g., external system unavailable);
	// this typically terminates the workflow.
	//
	// Implementations should be fast (< 100ms) to avoid blocking planner execution.
	// Heavy operations (API calls, database lookups) should use caching or background
	// precomputation.
	Decide(ctx context.Context, input Input) (Decision, error)
}

type Input struct {
	// RunContext carries run-level identifiers, labels, and caps configuration.
	// Policies can inspect labels for routing decisions (e.g., allow privileged
	// tools for "admin" runs).
	RunContext run.Context

	// Tools lists all candidate tools allowed by the agent design and runtime
	// registration. The policy engine filters this list down to the allowlist
	// for the current turn.
	Tools []ToolMetadata

	// RetryHint carries planner suggestions after tool failures (e.g., "disable
	// this tool", "increase timeout"). Nil if no hint was provided. Policies
	// can honor or ignore these hints based on configuration.
	RetryHint *RetryHint

	// RemainingCaps reflects the current execution budgets (remaining tool calls,
	// consecutive failures allowed, time budget). Policies use this to decide
	// whether to allow more tool invocations or terminate the run.
	RemainingCaps CapsState

	// Requested enumerates tools explicitly requested by the caller or planner
	// (e.g., via caller override or planner-generated tool calls). Policies can
	// use this to prioritize or restrict requested tools.
	Requested []tools.Ident

	// Labels are arbitrary key/value pairs propagated to policy decisions. These
	// come from the RunContext or may be augmented by prior policy decisions.
	// Example: {"environment": "production", "user_tier": "premium"}.
	Labels map[string]string
}

type RetryHint struct {
	Reason             RetryReason
	Tool               tools.Ident
	RestrictToTool     bool
	MissingFields      []string
	ExampleInput       map[string]any
	PriorInput         map[string]any
	ClarifyingQuestion string
	Message            string
}

type RetryReason string

type ToolMetadata struct {
	// ID is the fully qualified tool identifier (e.g., "weather.search.forecast").
	// Format: <service>.<toolset>.<tool>.
	ID tools.Ident

	// Title is a human-readable display title (e.g., "Get Weather Forecast").
	// It is presentation-only; policy engines should make decisions based on
	// ID and Tags. Codegen derives a sensible default from the tool name and
	// the DSL can optionally override it.
	Title string

	// Description documents the tool's purpose and behavior. Policies may inspect
	// this for keyword-based filtering (e.g., block tools mentioning "delete").
	Description string

	// Tags lists metadata labels for filtering (e.g., ["privileged", "external"]).
	// Policies can allowlist/blocklist based on tags without hardcoding tool IDs.
	Tags []string
}