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 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
}

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
}

type ExecutionRequest struct {
	ModelID      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

	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

	// 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

	// 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
}

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
	SessionID        string            // Copilot session ID
	Usage            *models.UsageStats
}

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 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 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 WorkspaceKeeper interface {
	SetKeepWorkspace(keep bool)
}