agent

type ApprovalHandler interface {
	RequestApproval(name string, args map[string]any) bool
}

type CompactionHistory interface {
	MessageHistory
	// AddCompaction advances the compaction boundary by summarizedCount messages and stores summary.
	AddCompaction(summary string, summarizedCount int)
}

type ContextCompactor interface {
	Compact(ctx context.Context, msgs []llm.Message) (summary string, err error)
}

type Event struct {
	Kind EventKind

	// EventIterStart, EventLLMStart, EventLLMEnd
	Iter int

	// EventLLMDelta, EventLLMEnd
	Content string

	// EventLLMEnd
	HasToolCalls bool

	// EventLLMStart, EventLLMEnd
	ContextTokens    int
	ContextWindow    int
	PromptTokens     int
	CompletionTokens int

	// EventToolStart, EventToolEnd, EventToolDenied
	ToolName   string
	ToolCallID string
	ToolArgs   string // JSON-encoded arguments

	// EventToolEnd
	ToolResult   string
	ToolDuration time.Duration

	// EventToolDenied
	DenyReason string

	// EventContextCompacted
	Summarized int
	Kept       int

	// EventRunEnd
	Stats RunStats
	Err   error // nil on success or graceful cancellation
}

type EventKind uint8

type HookDecision string

type HookEvent string

type HookInput struct {
	Event     HookEvent `json:"event"`
	SessionID string    `json:"session_id,omitempty"`
	Workspace string    `json:"workspace,omitempty"`

	// IsSubagent is true when the event fires inside a subagent run.
	// AgentType identifies which subagent (its def name). Both fields are
	// stamped on every event from a subagent so audit hooks can attribute.
	IsSubagent bool   `json:"is_subagent,omitempty"`
	AgentType  string `json:"agent_type,omitempty"`

	// Populated for HookUserPromptSubmit.
	Prompt string `json:"prompt,omitempty"`

	// Populated for HookPreToolUse, HookPostToolUse, HookPostToolUseFailure,
	// and HookNotification (when tied to an approval flow).
	ToolName   string         `json:"tool_name,omitempty"`
	ToolCallID string         `json:"tool_call_id,omitempty"`
	ToolArgs   map[string]any `json:"tool_args,omitempty"`

	// Populated for HookPostToolUse (result string) and
	// HookPostToolUseFailure (error string).
	ToolResult string `json:"tool_result,omitempty"`
	ToolError  string `json:"tool_error,omitempty"`

	// Populated for HookNotification: see NotificationApprovalRequired /
	// NotificationPermissionDenied. NotificationReason carries any extra
	// human-readable context.
	NotificationKind   string `json:"notification_kind,omitempty"`
	NotificationReason string `json:"notification_reason,omitempty"`

	// Populated for HookPreCompact (about-to-summarize counts) and
	// HookPostCompact (final counts plus summary).
	Summarized int    `json:"summarized,omitempty"`
	Kept       int    `json:"kept,omitempty"`
	Summary    string `json:"summary,omitempty"`

	// Populated for HookStop, HookSubagentStop, HookStopFailure, and
	// HookSessionEnd.
	Stats *RunStats `json:"stats,omitempty"`
	// Populated for HookStopFailure (the failure message).
	Error string `json:"error,omitempty"`

	// Sandbox is the runtime sandbox snapshot for the current run.
	// Populated on HookSessionStart (always) and on every gating event
	// thereafter so hooks can enforce policy like "fail if the sandbox
	// is off on the worker" without having to read settings themselves.
	Sandbox *SandboxInfo `json:"sandbox,omitempty"`
}

type HookOutput struct {
	Decision HookDecision `json:"decision,omitempty"`
	Reason   string       `json:"reason,omitempty"`
}

type HookRunner interface {
	Run(ctx context.Context, in HookInput) HookOutput
}

type MessageHistory interface {
	HistoryMessages() []llm.Message
	Append(m llm.Message) error
}

type NoopSandbox struct{}

type RunLoopOpts struct {
	LLMClient    llm.LLMClient
	SystemPrompt string
	ToolRegistry llm.ToolRegistry
	MaxIter      int
	History      MessageHistory
	StreamSink   llm.StreamSink
	// Policy is consulted before each tool execution. Nil defaults to AllowAllPolicy.
	Policy ToolPolicy
	// Approval is invoked when Policy returns ToolActionAsk.
	// Nil approval with ToolActionAsk falls through to Allow for backward compatibility.
	Approval ApprovalHandler
	// Compactor summarizes old messages when the context window is filling up.
	// Nil disables compaction; TrimHistory is used as a fallback.
	Compactor ContextCompactor
	// EventSink receives structured runtime events from the agent loop.
	// Nil disables event emission entirely (zero overhead).
	// The callback is invoked synchronously from the RunLoop goroutine; it must not block.
	EventSink func(Event)
	// Hooks runs lifecycle hooks at fixed points (PreToolUse, PostToolUse,
	// PostToolUseFailure, Notification, PreCompact, PostCompact, Stop /
	// SubagentStop / StopFailure). Nil or NoopHookRunner disables hooks.
	// PreToolUse and PreCompact hooks may block their respective actions.
	Hooks HookRunner
	// SessionID is forwarded to hook payloads so external scripts can correlate runs.
	// Optional; an empty value is omitted from hook input.
	SessionID string
	// Workspace is forwarded to hook payloads so external scripts can locate files
	// under the active workspace. Optional.
	Workspace string
	// IsSubagent is true when this RunLoop is a subagent execution. It
	// flips the lifecycle event on success from Stop to SubagentStop and
	// is stamped on every event from this run for audit attribution.
	IsSubagent bool
	// AgentType is the subagent definition name when IsSubagent is true.
	// Empty for main-agent runs.
	AgentType string
}

type RunStats struct {
	ToolCalls        int
	PromptTokens     int
	CompletionTokens int
}

type SandboxInfo struct {
	Enabled    bool     `json:"enabled,omitempty"`
	Mode       string   `json:"mode,omitempty"`
	Backend    string   `json:"backend,omitempty"`
	Sources    []string `json:"sources,omitempty"`
	Downgraded bool     `json:"downgraded,omitempty"`
}

type SandboxView interface {
	// Enabled reports whether the sandbox is active for this run. When
	// false, tools should fall back to current (pre-sandbox) behavior.
	Enabled() bool

	// Mode is "auto_allow" or "regular". See docs/design/sandbox-boundaries.md §5.
	// Returns "" when Enabled() is false.
	Mode() string

	// Backend identifies the OS backend providing isolation
	// ("seatbelt", "bwrap", "none"). Returns "none" when the sandbox
	// is enabled in settings but the OS backend is unavailable.
	Backend() string

	// WrapBashCommand returns the (binary, argv) the Bash tool should
	// exec to run the given command isolated by the active backend.
	// `shell` is the inner shell the backend should invoke
	// (e.g. "/bin/bash"); on unsupported platforms or when not wrapping
	// the caller should fall back to its own default invocation.
	//
	// When (name == "" && err == nil) the caller must run the command
	// unwrapped. This is how NoopSandbox signals "do nothing." Phase B
	// fills in the real wrap; Phase A only ships NoopSandbox.
	//
	// ctx allows cancellation of any backend preparation (writing a
	// Seatbelt profile to disk, etc.).
	WrapBashCommand(ctx context.Context, command, shell string) (name string, args []string, err error)

	// ShouldSandboxCommand reports whether the command should be wrapped.
	// Honors the excluded_commands list (commands the user has opted
	// out of the sandbox). Returns false when Enabled() is false.
	ShouldSandboxCommand(command string) bool

	// HostAllowed reports whether outbound network requests to host are
	// permitted by the sandbox policy, plus a short reason when denied.
	// When Enabled() is false this returns (true, "") — no enforcement.
	//
	// Non-bash tools (WebFetch, the http hook driver) consult this
	// before issuing requests so the same allow-list governs every
	// network egress path in the agent. The bash sandbox enforces the
	// same policy at the OS level via the in-process proxy.
	HostAllowed(host string) (ok bool, reason string)

	// ProxyAddress returns the listen address of the in-process HTTP
	// proxy ("127.0.0.1:<port>") when one is running, otherwise "".
	// Surfaces in `buildmax sandbox status`; backends use it to direct
	// child processes via HTTP_PROXY env.
	ProxyAddress() string

	// ScrubEnv returns env with secret-shaped variables removed. Applied
	// by the Bash tool before composing the sandboxed child env so
	// agent-process secrets (API keys, tokens, worker auth) do not
	// leak into untrusted subprocesses. Returns input unchanged when
	// Enabled() is false.
	ScrubEnv(env []string) []string

	// AllowUnsandboxed reports whether the per-call
	// `dangerously_disable_sandbox` arg is honored. When false ("strict
	// sandbox mode"), the arg is ignored and the call is wrapped
	// regardless. Mirrors Claude Code's allowUnsandboxedCommands.
	AllowUnsandboxed() bool

	// ChildEnv returns env-var "KEY=VALUE" entries the caller should add
	// to spawned child processes when the sandbox is active. Includes
	// HTTP_PROXY routing so cooperating tools (curl, wget, git http)
	// reach the network through the host-filtered proxy. Returns nil
	// when no injection is needed. Unlike backend-specific env knobs
	// (bwrap --setenv, sandbox-exec -D), this entry point works on every
	// platform because the bash tool sets cmd.Env itself.
	ChildEnv() []string
}

type ToolPolicy interface {
	Check(name string, args map[string]any) llm.ToolAction
}