executor

type Action = policy.Action

type ApprovalRecord struct {
	ID              string
	Status          ApprovalStatus
	ReviewerComment string
}

type ApprovalStatus string

type Approver interface {
	// Request creates a pending approval for the given tool call and returns its ID.
	// Implementers should persist the pending approval so WaitForResolution can query it.
	Request(ctx context.Context, toolName string, args map[string]any) (approvalID string, err error)

	// WaitForResolution blocks until the approval with the given ID is resolved
	// or the timeout elapses.
	WaitForResolution(ctx context.Context, approvalID string, timeout time.Duration) (*ApprovalRecord, error)
}

type Config struct {
	// Provider is the AI backend. Required.
	Provider provider.Provider

	// ToolRegistry provides tool definitions and execution. Optional.
	ToolRegistry *tools.Registry

	// Approver handles approval gates. Defaults to NullApprover.
	Approver Approver

	// HumanRequester handles blocking human-request gates. Defaults to NullHumanRequester.
	HumanRequester HumanRequester

	// SecretRedactor redacts secrets from messages. Defaults to NullSecretRedactor.
	SecretRedactor SecretRedactor

	// Transcript records conversation entries. Defaults to NullTranscript.
	Transcript TranscriptRecorder

	// Memory provides persistent agent memory. Defaults to NullMemoryStore.
	Memory MemoryStore

	// MaxIterations caps the agent loop. Default: 10.
	MaxIterations int

	// ApprovalTimeout is how long to wait for human approval. Default: 30m.
	ApprovalTimeout time.Duration

	// RequestTimeout is how long to wait for human request response. Default: 60m.
	RequestTimeout time.Duration

	// LoopDetector config. Zero values use defaults.
	LoopDetection LoopDetectorConfig

	// CompactionThreshold is the fraction of context limit at which compaction triggers. Default: 0.80.
	CompactionThreshold float64

	// TaskID and ProjectID are used for transcript recording.
	TaskID    string
	ProjectID string

	// Inbox receives external messages injected into the conversation
	// between loop iterations. Nil means no external messages.
	Inbox <-chan provider.Message

	// OnEvent is called for each executor event. Nil means no events emitted.
	// The callback must not block — use a buffered channel internally if needed.
	OnEvent func(Event)

	// ShouldStop is called after each tool execution round. If it returns
	// a non-empty string, the loop exits with status "completed" and that
	// string as the Result.Content. Nil means no custom termination.
	ShouldStop func() (reason string)

	// TrustEngine evaluates trust rules before tool execution. Nil = no trust enforcement.
	TrustEngine TrustEvaluator

	// SandboxMode routes bash and file tool calls through ContainerManager.
	SandboxMode bool

	// ContainerMgr provides Docker container execution. Required when SandboxMode is true.
	ContainerMgr ContainerExecutor

	// SandboxSpec is the container configuration for sandbox mode.
	SandboxSpec *SandboxConfig
}

type ContainerExecutor interface {
	IsAvailable() bool
	EnsureContainer(ctx context.Context, projectID, workspacePath string, spec SandboxConfig) (string, error)
	ExecInContainer(ctx context.Context, projectID, command, workDir string, timeout int) (stdout, stderr string, exitCode int, err error)
}

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

type DenyAllTrustEvaluator struct{}

type Event struct {
	Type       EventType      `json:"type"`
	AgentID    string         `json:"agent_id,omitempty"`
	Iteration  int            `json:"iteration,omitempty"`
	Content    string         `json:"content,omitempty"`      // text content or thinking trace
	ToolName   string         `json:"tool_name,omitempty"`    // for tool_call_start/result
	ToolCallID string         `json:"tool_call_id,omitempty"` // for tool_call_start/result
	ToolArgs   map[string]any `json:"tool_args,omitempty"`    // for tool_call_start
	ToolResult string         `json:"tool_result,omitempty"`  // for tool_call_result
	ToolError  bool           `json:"tool_error,omitempty"`   // for tool_call_result
	Error      string         `json:"error,omitempty"`        // for failed events
}

type EventType string

type HumanRequest struct {
	ID              string
	RequestType     RequestType
	Status          RequestStatus
	ResponseData    string
	ResponseComment string
	Metadata        string // JSON
}

type HumanRequester interface {
	// WaitForResolution blocks until the request with the given ID is resolved
	// or the timeout elapses.
	WaitForResolution(ctx context.Context, requestID string, timeout time.Duration) (*HumanRequest, error)
}

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

type LoopDetectorConfig struct {
	// MaxConsecutive is the number of identical consecutive tool calls before a loop is detected.
	// Default: 3.
	MaxConsecutive int
	// MaxErrors is the number of times the same tool call can return the same error before a loop is detected.
	// Default: 2.
	MaxErrors int
	// MaxAlternating is the number of A/B alternating cycles before a loop is detected.
	// Default: 3.
	MaxAlternating int
	// MaxNoProgress is the number of identical (same args + same result) non-error calls before a loop is detected.
	// Default: 3.
	MaxNoProgress int
}

type LoopStatus int

type MemoryEntry struct {
	ID       string
	AgentID  string
	Content  string
	Category string
}

type MemoryStore interface {
	// Search finds relevant memories for agentID using query text.
	Search(ctx context.Context, agentID, query string, limit int) ([]MemoryEntry, error)
	// Save persists a memory entry.
	Save(ctx context.Context, entry MemoryEntry) error
	// ExtractAndSave extracts facts from a transcript and saves them.
	ExtractAndSave(ctx context.Context, agentID, transcript string, embedder provider.Embedder) error
}

type NullApprover struct{}

type NullHumanRequester struct{}

type NullMemoryStore struct{}

type NullSecretRedactor struct{}

type NullTranscript struct{}

type NullTrustEvaluator struct{}

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

type RequestStatus string

type RequestType string

type Result struct {
	Content    string
	Thinking   string
	Iterations int
	Status     string // "completed", "failed", "loop_detected", "approval_timeout", "request_expired"
	Error      string
}

type SandboxConfig struct {
	Enabled      bool           `json:"enabled" yaml:"enabled"`
	Image        string         `json:"image" yaml:"image"`
	Network      string         `json:"network" yaml:"network"`
	Memory       string         `json:"memory" yaml:"memory"`
	CPU          float64        `json:"cpu" yaml:"cpu"`
	Mounts       []SandboxMount `json:"mounts" yaml:"mounts"`
	InitCommands []string       `json:"init" yaml:"init"`
}

type SandboxMount struct {
	Src      string `json:"src" yaml:"src"`
	Dst      string `json:"dst" yaml:"dst"`
	ReadOnly bool   `json:"readonly" yaml:"readonly"`
}

type SecretRedactor interface {
	// Redact returns the text with known secrets replaced.
	Redact(text string) string
	// CheckAndRedact redacts secrets from a message in place.
	CheckAndRedact(msg *provider.Message)
}

type TranscriptEntry struct {
	ID         string
	AgentID    string
	TaskID     string
	ProjectID  string
	Iteration  int
	Role       provider.Role
	Content    string
	Thinking   string
	ToolCalls  []provider.ToolCall
	ToolCallID string
}

type TranscriptRecorder interface {
	Record(ctx context.Context, entry TranscriptEntry) error
}

type TrustEvaluator interface {
	// Evaluate returns the trust action for a tool call.
	Evaluate(ctx context.Context, toolName string, args map[string]any) Action
	// EvaluateCommand returns the trust action for a bash command.
	EvaluateCommand(cmd string) Action
	// EvaluatePath returns the trust action for a file path.
	EvaluatePath(path string) Action
}