agent

type CompactInput struct {
	System     model.Message   // role-scoped system prompt (kept verbatim)
	Objective  string          // kept verbatim
	Messages   []model.Message // current, over-budget working history
	KeepRecent int             // recent turns to preserve verbatim (~6; default 6)

	Facts        []store.Entry      // oracle-verified spine
	Observations []store.Entry      // gathered, not certified (run_pov verdicts, tool findings)
	ActiveHyps   []store.Hypothesis // the open frontier
	RuledOut     []store.Hypothesis // resolved lines — the anti-drift memory
}

type Compactor interface {
	Compact(ctx context.Context, in CompactInput) ([]model.Message, error)
}

type Config struct {
	Role        router.Role
	TaskKind    router.TaskKind
	Objective   string
	TargetDesc  string
	MaxIters    int
	Temperature float64
	MaxTokens   int

	// M3 governance: guards for unattended, drift-resistant long runs.
	// TokenBudget halts the run once cumulative tokens reach it (0 → unlimited).
	// StallLimit halts after this many consecutive iterations with no new
	// observation and no new PoV submission — the loop is spinning (0 → default 5).
	TokenBudget int
	StallLimit  int

	// Context compaction (context compaction): when the estimated prompt
	// exceeds ContextBudget tokens, the working context is reprojected onto a
	// bounded digest over the durable trajectory (needs ReAct.Compactor set).
	// 0 → disabled. KeepRecent is the number of recent turns kept verbatim (default 6).
	ContextBudget int
	KeepRecent    int
}

type ContainerSandbox struct {
	DockerBin string        // default "docker"
	Image     string        // MUST be digest-pinned (contains "@sha256:")
	HostDir   string        // workspace root, bind-mounted at /work
	Name      string        // container name
	Memory    string        // e.g. "2g" (default)
	PidsLimit int           // default 512
	StartWait time.Duration // grace for the keepalive to come up (default 20s)
	// Network is the docker network mode. Default "none" (fully air-gapped). A
	// named network is the SCOPED HOLE: the operator provisions a
	// network where only the tool broker/store is reachable — pull-only tool
	// provisioning, never open egress the untrusted target could exfil through.
	Network string
	// contains filtered or unexported fields
}

type ExecResult struct {
	ExitCode int
	Stdout   string
	Stderr   string
	TimedOut bool
}

type ModelCompactor struct {
	Model  model.Model
	Router router.Router
}

type Outcome struct {
	Confirmed    bool
	Iterations   int
	StopReason   string // confirmed | model-concluded | max-iters | error
	TotalUsage   model.Usage
	FinalMessage string
}

type ReAct struct {
	Model   model.Model
	Router  router.Router
	Session *Session
	Tools   []Tool
	// Compactor, if set, reprojects the working context onto a bounded view over
	// the durable trajectory when the prompt approaches ContextBudget — so a run
	// goes long instead of halting when history fills (context compaction).
	// nil → no compaction (the M1 behavior).
	Compactor Compactor
	// Log, if set, receives short human-readable progress lines.
	Log func(string)
}

type Sandbox interface {
	Exec(ctx context.Context, name string, args []string, stdin string, timeout time.Duration, maxOutput int) (ExecResult, error)
	Close() error
}

type Session struct {
	Store    *store.Store
	Verifier *verify.Verifier

	RunID        string
	HypothesisID string
	Model        string // model producing PoVs, recorded as provenance

	Workspace *Workspace

	Oracle oracle.Spec     // the spec run_pov applies
	Base   runner.RunSpec  // authoritative target run template
	Fixed  *runner.RunSpec // optional differential fixed-image template

	// Spawned holds sub-hypothesis statements the agent proposed via
	// spawn_hypothesis; the supervisor dispatches them as child lines (M2).
	Spawned []string

	// Outcome, updated by run_pov.
	Confirmed      bool
	LastVerdict    *oracle.Verdict
	LastResult     *verify.Result
	ConfirmedPoV   []byte // the exact PoV bytes that produced the passing verdict
	PoVSubmissions int
}

type TemplateCompactor struct{}

type Tool interface {
	Name() string
	Description() string
	Schema() json.RawMessage
	Invoke(ctx context.Context, args json.RawMessage) (string, error)
}

type Workspace struct {
	Root string
	// ExecTimeout bounds a single exec call (default 60s).
	ExecTimeout time.Duration
	// MaxOutput caps captured stdout/stderr per exec (default 64 KiB).
	MaxOutput int
	// Sandbox, if set, runs exec inside an isolated container instead of on the
	// host (the isolation boundary). File tools stay host-side via os.Root; the
	// workspace is bind-mounted into the sandbox so both see the same files.
	Sandbox Sandbox
}