execution

type AgentEngine interface {
	// Initialize sets up the engine
	Initialize(ctx context.Context) error

	// Execute runs a test with the given stimulus. The caller controls
	// cancellation and deadlines through ctx.
	Execute(ctx context.Context, req *ExecutionRequest) (*ExecutionResponse, error)

	// Shutdown cleans up resources. It is safe to call multiple times;
	// subsequent calls after the first are no-ops. After Shutdown returns,
	// SessionUsage results include data from session termination events.
	Shutdown(ctx context.Context) error

	// SessionUsage returns the final usage stats for a session, including
	// data from session.shutdown events that fire during Shutdown().
	// Returns nil if no usage data is available for the given session.
	SessionUsage(sessionID string) *models.UsageStats
}

type CommandMockFinalizer interface {
	FinalizeCommandMocks(workspace string) ([]models.CommandInvocation, error)
}

type CopilotClient interface {
	// CreateSession maps to [copilot.Client.CreateSession]
	CreateSession(ctx context.Context, config *copilot.SessionConfig) (CopilotSession, error)

	// GetAuthStatus maps to [copilot.Client.GetAuthStatus]
	GetAuthStatus(ctx context.Context) (*copilot.GetAuthStatusResponse, error)

	// Start maps to [copilot.Client.Start]
	Start(ctx context.Context) error

	// Stop maps to [copilot.Client.Stop]
	Stop() error

	// ResumeSessionWithOptions maps to [copilot.Client.ResumeSessionWithOptions]
	ResumeSessionWithOptions(ctx context.Context, sessionID string, config *copilot.ResumeSessionConfig) (CopilotSession, error)

	// DeleteSession maps to [copilot.Client.DeleteSession]
	DeleteSession(ctx context.Context, sessionID string) error

	// ListModels maps to [copilot.Client.ListModels]
	ListModels(ctx context.Context) ([]copilot.ModelInfo, error)
}

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

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

type CopilotEngineBuilderOptions struct {
	NewCopilotClient func(clientOptions *copilot.ClientOptions) CopilotClient
	// OwnClient selects a fresh production client instead of SharedClient.
	OwnClient bool
	// DisableCommandMocks omits the shim registry and rejects command mocks.
	// Requires OwnClient or a supplied NewCopilotClient factory.
	DisableCommandMocks bool
	// DiagnosticObserver enables sanitized, failure-retaining lifecycle diagnostics.
	// Calls are serialized outside engine state locks. Observers must not reenter
	// engine lifecycle methods (including Execute, Initialize, DeleteSession, Shutdown).
	DiagnosticObserver func(ExecutionDiagnostic) error
}

type CopilotSession interface {
	// Disconnect maps to [copilot.Session.Disconnect]. It closes the session and releases resources, however it
	// doesn't delete data and the session is still resumable until deleted via [copilot.Client.DeleteSession].
	Disconnect() error

	// On maps to [copilot.Session.On]
	On(handler copilot.SessionEventHandler) func()

	// SendAndWait maps to [copilot.Session.SendAndWait]
	SendAndWait(ctx context.Context, options copilot.MessageOptions) (*copilot.SessionEvent, error)

	// SessionID returns [copilot.Session.SessionID]
	SessionID() string

	UsageMetrics(ctx context.Context) (*rpc.UsageGetMetricsResult, error)

	ShutdownUsage(ctx context.Context) (*copilot.SessionShutdownData, error)
}

type DiagnosticCode string

type DiagnosticError struct{ Diagnostic ExecutionDiagnostic }

type DiagnosticStage string

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

type ExecutionDiagnostic struct {
	Stage     DiagnosticStage `json:"stage"`
	Code      DiagnosticCode  `json:"code"`
	SessionID string          `json:"-"`
}

type ExecutionRequest struct {
	ModelID         string
	ReasoningEffort string
	Message         string
	Context         map[string]any
	Resources       []ResourceFile
	GitResources    []models.GitResource
	WorkDir         string
	Instructions    []InstructionFile
	Tools           []copilot.Tool

	MessageMode MessageMode
	Streaming   bool

	// FirstEventTimeout bounds how long Execute waits for the FIRST session
	// event before treating the run as a session-start hang and aborting it
	// with a distinct error. It is intentionally much shorter than the overall
	// turn deadline (the ctx passed to Execute), which must be sized for the
	// slowest legitimate full turn and therefore cannot also catch a
	// no-first-turn wedge quickly. Zero disables the check (the prior behavior).
	FirstEventTimeout time.Duration

	// EphemeralSession keeps one-off sessions out of engine shutdown tracking.
	// New ephemeral sessions are deleted at the end of Execute. Resumed
	// ephemeral sessions are only disconnected because the caller does not own
	// the original session data.
	EphemeralSession bool

	// SkipWorkspaceCapture avoids post-run workspace snapshots for callers that
	// only need model/tool output, such as prompt graders.
	SkipWorkspaceCapture bool
	// CaptureJudgeFiles freezes explicitly reviewed files before disconnect can
	// restore the actor workspace. The callback never runs in a judge session.
	CaptureJudgeFiles func(string) *models.JudgeFileCapture `json:"-"`

	SessionID    string
	WorkspaceDir string // Reuse an existing workspace directory (for follow-up prompts)
	SkillName    string

	// TaskName and TaskDescription carry test-case metadata so mock engines can
	// echo them, enabling output_contains expectations that reference task-level
	// concepts (e.g., "recursive") without a real model.
	TaskName        string
	TaskDescription string

	SourceDir  string   // used when looking for workspace items via relative path, like skills.
	SkillPaths []string // Directories to search for skills
	NoSkills   bool     // When true, skip all skill loading
	// SuppressSkillBody prevents full target skill content from being appended
	// while still allowing skill discovery and compact summaries.
	SuppressSkillBody bool

	// TriggerSkillRouting appends an eval-only routing instruction that asks
	// the agent to invoke the target skill tool when the task falls within that
	// skill's scope. It is intended for trigger-precision evals where the skill
	// body is suppressed.
	TriggerSkillRouting bool

	// MCPServers configures MCP servers for the session. Keys are server names,
	// values follow the copilot SDK MCPServerConfig format (type/command/args).
	MCPServers map[string]copilot.MCPServerConfig

	CommandMocks        []models.CommandMockConfig
	CommandMocksBaseDir string

	// PermissionHandler called when the copilot SDK wants to determine if a tool can be used.
	// Default: allows all tools.
	PermissionHandler copilot.PermissionHandlerFunc

	// CancelOnSkillInvocation, when true, causes the execution context to be
	// canceled as soon as a SkillInvoked event is received. This allows trigger
	// tests to terminate early once the skill invocation they care about has been
	// detected, avoiding unnecessary wait for the agent to finish its full turn.
	CancelOnSkillInvocation bool

	// ToolPolicy is the resolved tool-capability boundary derived from the
	// target .agent.md `tools:` declaration (see [NewToolPolicy]). Nil means
	// no policy was resolved and preserves the pre-existing unrestricted
	// behavior. Engines that support it (currently CopilotEngine) apply it to
	// both the native SDK session tool configuration and a fail-closed
	// OnPermissionRequest wrapper.
	ToolPolicy *ToolPolicy
}

type ExecutionResponse struct {
	FinalOutput      string
	Events           []agentevent.Event
	ModelID          string
	SkillInvocations []SkillInvocation
	DurationMs       int64
	ToolCalls        []models.ToolCall
	ErrorMsg         string
	Success          bool
	WorkspaceDir     string            // Path to workspace directory (for file grading)
	WorkspaceFiles   map[string][]byte // Post-execution workspace file contents captured before session disconnect
	JudgeFiles       *models.JudgeFileCapture
	SessionID        string // Copilot session ID
	Usage            *models.UsageStats
	// UsageIsCumulative distinguishes a session snapshot from per-execution
	// usage. Engines that report per-turn usage leave this false.
	UsageIsCumulative bool
	UsageRevision     uint64

	GraderSessions []models.SessionDigest

	// ToolPolicyMode is the effective ToolPolicy mode applied to this
	// execution ("unrestricted", "deny_all", or "allow_list"), empty when no
	// policy was resolved for the request.
	ToolPolicyMode string
	// ToolPolicyDenials records every tool-execution attempt the engine
	// denied under an active ToolPolicy. Empty when the policy was
	// unrestricted or no tool was ever denied.
	ToolPolicyDenials  []ToolPolicyDenial
	CommandInvocations []models.CommandInvocation
	// contains filtered or unexported fields
}

type GitResource interface {
	// Cleanup removes the materialized resource (e.g. `git worktree
	// remove`). It is safe to call multiple times; subsequent calls are
	// no-ops.
	Cleanup(ctx context.Context) error
}

type InstructionFile struct {
	Path    string
	Content []byte
}

type MessageMode string

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

type ResourceFile struct {
	Path    string
	Content []byte
}

type SessionEventModelObservation struct {
	Models         []string `json:"models"`
	EventsObserved uint64   `json:"events_observed"`
	Complete       bool     `json:"complete"`
}

type SessionEventsCollector struct {
	// SkillInvocations is a chronological list of skills invoked during the session
	SkillInvocations []SkillInvocation
	// contains filtered or unexported fields
}

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

type SessionUsageObservation struct {
	Source                   string   `json:"source"`
	Complete                 bool     `json:"complete"`
	ModelAttributionComplete bool     `json:"model_attribution_complete"`
	Models                   []string `json:"models"`
}

type SharedClientOptions struct {
	// LogLevel passed through to the underlying copilot.Client. Defaults to
	// "error" when blank.
	LogLevel string
	// CLIArgs passed through to the underlying copilot.Client. Calls with the
	// same CLIArgs share one process; calls with different CLIArgs get separate
	// processes because CLIArgs are startup-only.
	CLIArgs []string
}

type SkillInvocation struct {
	// Name of the invoked skill
	Name string
	// Path of the invoked SKILL.md
	Path string
}

type ToolPolicy struct {
	Mode ToolPolicyMode
	// contains filtered or unexported fields
}

type ToolPolicyDenial struct {
	// Tool is the canonical tool name the policy evaluated (empty when the
	// request kind/shape could not be resolved to a tool name at all).
	Tool string
	// Kind is the underlying Copilot SDK permission request kind (e.g.
	// "shell", "url", "mcp", "custom-tool", "workflow").
	Kind string
	// Reason explains why the request was denied.
	Reason string
}

type ToolPolicyMode string

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

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

type WorkspaceKeeper interface {
	SetKeepWorkspace(keep bool)
}