testkit

type Call struct {
	Step int
	Tool string
	Args json.RawMessage
	// Returned is false for the call a Crash at AfterToolEffect stopped
	// after: the tool did its work and the runtime never recorded it.
	Returned bool
}

type Crash struct {
	Step int
	At   Point
}

type Fuzz struct {
	// Seed selects the sequence. Zero means 1.
	Seed uint64
	// Count is how many arguments Valid returns and at most how many
	// Invalid returns. Zero means 32.
	Count int
	// MaxItems bounds a generated array where the schema does not, and
	// MaxLength a generated string, in characters. Zero means 4 and 32.
	MaxItems  int
	MaxLength int
	// MaxDepth bounds nesting where the schema recurses: below it, optional
	// properties are left out and arrays are as short as allowed. Zero
	// means 4.
	MaxDepth int
}

type Point string

type PolicyCase struct {
	Name string
	// Tool is a registered tool's name and Args its JSON arguments; empty
	// Args mean {}. Both go through the runtime's validation first, as a
	// decision does, and the policy sees the ToolRequest the runtime built.
	Tool string
	Args string
	// View is the run state handed to the policy. Its Run.ID, when set,
	// is also the request's.
	View agentrt.RunView
	// Want is the outcome, or Refused when the runtime must refuse the
	// arguments before the policy sees them.
	Want agentrt.PolicyOutcome
	// Kind, when set, is the approval kind a require_approval must carry.
	// Reason, Capability, and Presentation, when set, are substrings the
	// decision's reason, capability JSON, and presentation JSON must
	// contain.
	Kind         string
	Reason       string
	Capability   string
	Presentation string
}

type Result struct {
	RunID     string
	Run       agentrt.Run
	Steps     []agentrt.Step
	Approvals []agentrt.Approval
	Events    []agentrt.Event
	// Calls is every tool invocation across every Driver, in order.
	Calls []Call
	// Inputs is what the Agent was handed at every decision across every
	// Driver, in order, for rendering checks.
	Inputs []agentrt.StepInput
	// Crashes are the crashes that fired, in order.
	Crashes []Crash
	// Resumes counts every Driver that ran the run after the first, which
	// started it: the resume after an operator's approval as well as the
	// resume after a crash. A resume refused while a crashed Driver's
	// lease is live, and the Driver that records the operator's decision,
	// are not counted. A run that pauses for one approval and crashes once
	// after it is resumed is started (Driver 1), resumed after the
	// approval (Driver 2, which crashes), and resumed after the crash
	// (Driver 3): Resumes is 3 - 1 = 2, with one Crash.
	Resumes int
}

type Scenario struct {
	Tools  []agentrt.Tool
	Policy agentrt.Policy
	// Agent is usually a scripted.Agent or the consumer's own replayer. It
	// is handed to every Driver the harness builds, so it must decide from
	// the recorded steps alone, as the runtime requires anyway. A replayer
	// keyed by step index skips the decision of a step that was
	// interrupted, because the interrupted step keeps its index.
	Agent agentrt.Agent
	Goal  string
	// Limits for the run. A zero MaxSteps means agentrt.DefaultLimits.
	Limits agentrt.Limits
	// Reconcile is the consumer's Config.Reconcile; nil leaves the runtime
	// to pause an interrupted side effect for an operator.
	Reconcile func(context.Context, agentrt.RunView) (agentrt.Reconciliation, error)
	// Operator answers each pending approval. Nil approves every one.
	Operator func(agentrt.Approval) Verdict
	// Now and NewID are passed to every Driver, so a deterministic clock
	// and id sequence make two runs of one Scenario record identically.
	Now   func() time.Time
	NewID func() string
	// DB is the database file to run in, for a consumer whose own tables
	// share the runtime's file. Empty means a file of the harness's own.
	DB string
	// LeaseTTL is Config.LeaseTTL for every Driver. Zero means one second.
	// A crashed Driver never releases its lease, Resume refuses the run
	// until the lease expires, and the harness waits that long per crash,
	// as a restarted process would; a value too short for the machine
	// makes a live loop lose its own lease between heartbeats.
	LeaseTTL time.Duration
	// Loop, when set, is the consumer's own loop over a Gate, which the
	// harness runs in place of a Driver and its Agent. Each process opens a
	// fresh Gate on the scenario's tools, policy, reconciliation, clock,
	// ids, and lease, takes a session with Begin, or with Attach after a
	// pause or a crash, hands it to Loop, and closes it when Loop returns.
	// Loop drives the session until it is Done; when Current is not nil,
	// Attach left an approved step open for Execute. An error Loop returns
	// is reported. Result.Inputs is then empty, and SameRenders, which
	// renders what an Agent was handed, needs an Agent.
	Loop func(ctx context.Context, s *agentrt.Session) error
}

type Verdict int