runtime

type Command struct {
	Name    string
	Usage   string
	Summary string
	Run     func(s *Session, args string) (string, error)
}

type CoordinatedResult struct {
	ID     string
	Prompt string
	Output string
	Err    error

	Merged        bool
	Blocked       bool
	BlockedBy     string
	BlockedSymbol string
}

type Options struct {
	// Model overrides the configured model ("<provider>/<model>").
	Model string
	// SkipPermissions applies --dangerously-skip-permissions: an allow-all base
	// where explicit rules still win.
	SkipPermissions bool
	// Fake uses the scripted fake provider, so the binary runs with no
	// credential (the offline smoke path).
	Fake bool
	// BaseSystemPrompt precedes the project instructions.
	BaseSystemPrompt string
	// ConfigPath overrides the default <root>/opencode.json. Empty means
	// use the default. Used by --config / -c in the CLI.
	ConfigPath string
	// Goal, when non-empty, makes Run consult Session.Judge after the
	// agent loop returns. Empty Goal skips the judge entirely. Used by
	// --goal in the CLI (T-440..T-445).
	Goal string
	// Judge is the optional goal / stop-condition evaluator (ADR-0006).
	// Nil disables judging even when Goal is set, preserving pre-0007
	// behavior for callers that want a goal field but no judge yet.
	Judge *orchestrate.Judge
	// MaxJudgeIterations caps the number of judge consults in a single
	// Run when the judge keeps replying UNMET. Zero or negative falls
	// back to DefaultMaxJudgeIterations (3).
	MaxJudgeIterations int
}

type Session struct {
	Root  string
	Model string

	Config       *config.Config
	SystemPrompt string

	Provider    ports.Provider
	Tools       *tool.Registry
	ToolSchemas []ports.ToolSchema

	// Goal is the stop-condition text (Change 0007). Empty disables
	// judging; Run then terminates when the agent's tool-call count hits
	// zero (the pre-0007 behavior).
	Goal string
	// Judge is the optional goal / stop-condition evaluator (ADR-0006).
	// When Goal is non-empty and Judge is non-nil, Run consults Judge
	// after the agent loop returns. MET stops; UNMET appends feedback
	// to history and loops; the loop is bounded by MaxJudgeIterations.
	Judge *orchestrate.Judge
	// MaxJudgeIterations caps the judge loop. Zero or negative falls
	// back to DefaultMaxJudgeIterations (3).
	MaxJudgeIterations int

	// Gate authorizes tool calls. Until a Prompter is wired, an Ask rule
	// degrades to Deny — safe, but not interactive.
	Gate policy.Gate
	// Rules is the decision table behind Gate, exposed so a caller can inspect
	// what a rule decides independently of how Ask is resolved.
	Rules *policy.Rules

	// Memory is nil when no embedder is configured.
	Memory   *memory.Store
	Embedder embed.Embedder

	// LanguageService answers code-intelligence questions (change 0026,
	// ADR-0017). Nil unless the lsp config is enabled with at least one server
	// — and always nil in a fake session, which must never spawn a process.
	LanguageService ports.LanguageService

	Skills   *skills.Index
	Budgeter contextmgr.Budgeter

	// Checkpointer writes and restores checkpoint.md (ADR-0008). Nil when no
	// context window is configured, which disables checkpointing end to end.
	Checkpointer *contextmgr.Checkpointer
	// Tasks is the task tree, restored from the checkpoint at assembly and
	// written back on every checkpoint (milestone subsystem #3).
	Tasks contextmgr.TaskTree

	// OnEvent and OnToolResult are the front-end render hooks, forwarded to the
	// agent loop on every Run. Nil means no rendering (the non-interactive path).
	OnEvent      func(ports.Event)
	OnToolResult func(call ports.ToolCall, result ports.Block)

	// OnCheckpointError reports a failed checkpoint write. The turn itself
	// succeeded, but the session is no longer durable, so the operator needs to
	// know. Nil drops the report rather than failing the turn.
	OnCheckpointError func(error)

	// KeepRecent bounds how many trailing messages survive compaction
	// (change 0010). Zero uses DefaultKeepRecent.
	KeepRecent int

	// MaxSubagents caps how many subagents one fan-out may launch, and
	// MaxSubagentParallel how many run at once (change 0011). Each subagent is a
	// full model turn, so these are cost controls. Zero uses the defaults.
	MaxSubagents        int
	MaxSubagentParallel int
	// OnSubagentDir reports the isolated directory a subagent is running in
	// (empty when running in place). Nil is a no-op.
	OnSubagentDir func(dir string)

	// Workflows holds the registered deterministic workflows (ADR-0006),
	// keyed by name and invoked with /workflow.
	Workflows map[string]orchestrate.Workflow

	// Coordinator locks code symbols before subagents edit them (change 0012).
	// Defaults to NoCoordinator, so coordinated fan-out is unavailable until a
	// real coordinator (grit) is wired and installed.
	Coordinator orchestrate.Coordinator
	// OnCompact reports a compaction as (before, after) message counts, so a
	// front-end can tell the user rather than the context shrinking invisibly.
	// Nil is a no-op.
	OnCompact func(before, after int)

	// Memo is the file-based memory surface: MEMORY.md, notes.md, and
	// tasks/<id>/progress.md under the project root (ADR-0002 #1). /dream
	// appends extracted facts here.
	Memo memo.Files

	// Compose is the active compose session, nil until /compose starts one
	// (ADR-0002 #6). It lives for the process; persisting a phase machine across
	// invocations is deliberately out of scope for change 0009.
	Compose *compose.Session

	// History accumulates this session's turns, so /dream has a transcript to
	// extract from and /distill has runs to mine.
	History []ports.Message
	// Runs records each turn's tool sequence for /distill.
	Runs []improve.Run

	// MaxSamples is the default N for /max (change 0016). Zero uses
	// orchestrate.DefaultSamples; over-cap values are clamped at use.
	MaxSamples int
	// MaxModel is the judge model /max ranks with. Empty judges with the
	// session's own model.
	MaxModel string

	// ConfigPath is the resolved opencode.json this session was loaded from,
	// whether or not the file exists. /theme persists into it.
	ConfigPath string

	// Theme is the attached front-end's palette control (change 0017). Nil when
	// no front-end is attached, which makes /theme report that rather than
	// pretending to switch — theming is a front-end capability.
	Theme Themer

	// MCPWarnings records each declared MCP server that could not be used, by
	// name (change 0015). A broken server is skipped rather than fatal, so the
	// front-end must surface these — otherwise its tools go missing silently.
	MCPWarnings []string
	// contains filtered or unexported fields
}

type SubagentTask struct {
	Prompt  string
	Symbols []string
}

type Themer interface {
	// ThemeNames lists the selectable palettes, in presentation order.
	ThemeNames() []string
	// Theme reports the active palette's name.
	Theme() string
	// SetTheme switches the active palette. An unknown name is an error.
	SetTheme(name string) error
}

type Turn struct {
	System  string
	History []ports.Message
	// Used is the budgeter's estimate of the assembled context's token cost.
	// It is what the checkpoint high-water decision is measured against.
	Used int
}