runtime

type Caller struct {
	SessionID string
	TurnID    string
	ParentID  string
	Depth     int
	// Role is populated by role-aware dispatch. It is empty until roles are in
	// use, but remains part of the principal so later role separation does not
	// require another boundary signature change.
	Role string
}

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

type Event struct {
	Type     string
	Metadata Metadata
}

type Handler interface {
	Invoke(context.Context, Request) (json.RawMessage, error)
}

type HookResult struct {
	Context string
	Runs    []HookRun
}

type HookRun struct {
	// Event is PreToolUse, PostToolUse or Stop.
	Event string
	// Program is the hook script's name, not its path: this reaches a screen,
	// and the absolute path runs through the operator's home directory.
	Program string
	// Tool is the tool this hook fired for.
	Tool string
	// Input is the tool input this handler saw, bounded and redacted before
	// it is set (internal/composition's hookRunsFor): it is retained in the
	// dispatcher's dedup completed map for the life of the turn, not just at
	// display time, so it must already be safe to hold and to show.
	//
	// A plain string, not json.RawMessage: HookRun is compared with != in
	// the ID-keyed dedup regression tests, and a slice-backed field would
	// make the struct non-comparable.
	Input string
	// Denied is true for the PreToolUse run that blocked the call.
	Denied bool
	// Output is what this hook said - advisory text, or the block reason.
	// Empty means it ran silently, which is normal and still worth showing.
	Output string
	// Warning is the operator diagnostic this run produced, if it misbehaved.
	Warning string
}

type HookVerdict struct {
	// Denied blocks the invocation. The handler is never reached.
	Denied bool
	// Reason is why. It reaches the model - that is the point of a block.
	Reason string
	// Context is advisory text the gate produced even when it allowed. It
	// reaches the model merged with the reactive event's context.
	Context string
	// Runs is what executed, for the operator's view. A denial carries its own
	// run: the tool did not happen, and the reason came from a script.
	Runs []HookRun
}

type Kind string

type MailboxAccess struct {
	Drain     MailboxDrainFunc
	Interrupt func() <-chan struct{}
	Pending   func() bool
	// PendingInterrupt reports whether an Interrupt-flagged steer is queued
	// (the strict gate for the loop watcher's signal branch; Pending is the
	// len-based gate for the watchdog branch).
	PendingInterrupt func() bool
}

type MailboxDrainFunc func() []ParentMessage

type Metadata struct {
	ID, ParentID, TurnID, Name, Kind, Status, Scope, InputHash, OutputHash string
	Duration                                                               time.Duration
	InputPreview, OutputPreview                                            string
}

type ParentMessage struct {
	Kind      string // "steer", "answer", or "ask"
	Body      string
	MessageID string // correlation id (required for kind=ask answers)
}

type Policy struct {
	MaxDepth, MaxRetries, MaxInputBytes, MaxOutputBytes int
	MaxBudget                                           int
	Allow                                               map[Kind]map[string]bool
	Sink                                                func(Event)
	// PreInvokeHook and PostInvokeHook are the optional lifecycle gates. They
	// live on Policy next to Sink, and that placement is load-bearing rather
	// than incidental: Policy is copied to derived dispatchers by
	// Dispatcher.Policy(), which clears only Allow, so the hooks propagate to
	// scoped subagent dispatchers. A PreToolUse gate a subagent escapes is not
	// a gate - subagents run the same tools against the same workspace.
	//
	// internal/runtime deliberately does not import internal/hooks: these are
	// plain func fields, so nil is no hooks, one nil compare, and today's
	// behaviour exactly.
	PreInvokeHook  func(context.Context, Request) HookVerdict
	PostInvokeHook func(context.Context, Request, Result) HookResult
}

type Request struct {
	ID, ParentID, TurnID, SessionID, Role, Name, Scope string
	// AgentName, AgentDigest, Skill, ProviderName and Model are immutable work metadata used by
	// agent-routing handlers. They are not policy scope or permission grants.
	AgentName, AgentDigest, Skill string
	ProviderName, Model           string
	Kind                          Kind
	Input                         json.RawMessage
	Timeout                       time.Duration
	Budget                        int
	WorkLimits                    WorkLimits
	DisableProviderReplay         bool
	Permission                    string
	Depth, Retry                  int
	// Step is the loop-stamped model step this invocation belongs to. 0 means
	// legacy turn-scoped dedup; Step > 0 scopes the per-turn dedup to that step,
	// so an identical call re-issued in a LATER step of the same turn re-runs
	// while a same-step re-issue still dedups.
	Step int
	// SkipDedup exempts this Tool invocation from the per-turn dedup and the
	// ID-keyed dedup state (completed map, active/waiters): it never reserves a
	// flight key, never joins a waiter, is never answered from a recorded
	// result, and never writes dedup state. Zero value keeps today's behavior.
	SkipDedup bool
	// OutputSchema: structured subagent output schema (tools/02); nil = free-text.
	OutputSchema map[string]any
}

type RequestValidator interface {
	ValidateRequest(Request) error
}

type Result struct {
	ID, Name string
	Kind     Kind
	Output   json.RawMessage
	Err      error
	Attempts int
	Metadata Metadata
	// HookContext is advisory text a PostToolUse hook produced for this
	// invocation. It travels in its own separately bounded field and is NEVER
	// spliced into Output: appending it there would write past the per-tool
	// ceiling check inside execute (INV-AG-25/26/27) and leave Metadata's
	// OutputHash and OutputPreview describing bytes the model never received.
	HookContext string
	// HookRuns records the lifecycle hooks that executed for this invocation,
	// for the OPERATOR's view. It is not the model's copy and not the audit
	// record: a hook that ran and said nothing appears here and nowhere else,
	// which is the whole reason it exists.
	HookRuns []HookRun
}

type TaskIdentity struct {
	RunID  string
	TaskID string
	Agent  string
}

type WorkLimits struct {
	MaxTurns         int       `json:"max_turns,omitempty"`
	MaxPromptTokens  int       `json:"max_prompt_tokens,omitempty"`
	MaxOutputTokens  int       `json:"max_output_tokens,omitempty"`
	MaxOutputPerCall int       `json:"max_output_per_call,omitempty"`
	MaxToolCalls     int       `json:"max_tool_calls,omitempty"`
	DeadlineAt       time.Time `json:"deadline_at,omitempty"`
}