harness

type Scenario struct {
	Name   string
	Script []testutil.ScriptEntry

	// Setup is called before the scenario runs. It receives the workspace
	// root and should create any files/repos needed. Returns the prompt.
	Setup func(t *testing.T, root string) string

	// ExtraTools adds additional tools beyond the standard local tool set.
	ExtraTools []agent.AgentTool

	// SystemPrompt overrides the default system prompt.
	SystemPrompt string

	// OnRunning is called after the agent starts but before waiting for
	// completion. Use for injecting steering or follow-ups mid-run.
	OnRunning func(t *testing.T, a *agent.Agent)

	// ProviderGates blocks specific provider calls (0-indexed) until closed.
	// Use to synchronize mid-turn actions like steering/follow-ups.
	ProviderGates map[int]chan struct{}

	// Timeout for the entire scenario. Defaults to 10s.
	Timeout time.Duration

	// Assert is called after the scenario completes to verify outcomes.
	Assert func(t *testing.T, result *ScenarioResult)
}

type ScenarioResult struct {
	// Events is the ordered sequence of all agent events.
	Events []agent.AgentEvent

	// Session is the final agent session state.
	Session *agent.Session

	// WorkspaceRoot is the path to the workspace directory.
	WorkspaceRoot string

	// ProviderCalls is the number of calls made to the provider.
	ProviderCalls int
	ProviderLog   []testutil.ScriptedProviderCall

	// Error is set if the scenario failed to start or errored.
	Error error
}