turn

type ApprovalGranter interface {
	GrantSession(workspaceID, tool string)
	GrantAlways(ctx context.Context, workspaceID, tool string) error
}

type AttachmentResolver interface {
	Resolve(ctx context.Context, addr protocol.MessageAddress, messages []protocol.ChatMessage) ([]protocol.ChatMessage, error)
}

type AuthorityFunc func(addr protocol.MessageAddress, user protocol.ChatMessage) tools.MemoryAuthority

type AuthzDecision struct {
	Outcome AuthzOutcome
	Reason  string
	Scope   string
}

type AuthzInput struct {
	Call       protocol.ToolInvokeEnvelope
	Addr       protocol.MessageAddress
	Trust      tools.TrustLevel
	ProviderID string // "" = local registry tool
}

type AuthzOutcome int

type BootstrapLoader interface {
	LoadBootstrap(ctx context.Context) ([]bootstrap.File, error)
}

type Config struct {
	Store     harness.HistoryStore
	Loader    BootstrapLoader
	Registry  *tools.Registry
	Provider  Provider
	Publisher EventPublisher
	// Assembler is the default context manager. ContextManager, when set,
	// overrides it (e.g. a MemoryLayer-backed strategy).
	Assembler      contextpack.Assembler
	ContextManager ContextManager
	Model          string
	// ReasoningEffort is an optional process/user preference. Per-thread
	// /reasoning overrides it; model defaults and then provider defaults apply
	// when it is empty or disallowed by a model-specific allowlist.
	ReasoningEffort string
	// DefaultWorkspaceID resolves workspace-less local/client turns. A non-empty
	// workspace carried by the turn is never replaced.
	DefaultWorkspaceID string
	// ModelRegistry is the set of available models + default. When set, the runner
	// selects the per-turn model from it (capability-matched), honoring an
	// explicit /command override first. nil → the single Model is always used.
	ModelRegistry *modelpkg.Registry
	// ModelSelector picks the per-turn model from ModelRegistry on the auto path
	// (an explicit override wins). nil with a non-nil ModelRegistry →
	// model.CapabilityDefault. The distribution plugs in a cost/complexity router
	// here (policy stays out of oss).
	ModelSelector modelpkg.Selector
	// SkillRealizer, when set, materializes a loaded skill's bundle files into the
	// sandbox's shared /skills dir (installed on ctx each turn so load_skill can call
	// it). nil → no materialization (skills load body-only). The distribution wires
	// the source (MemoryLayer bundle files / workspace folders); oss stays agnostic.
	SkillRealizer tools.SkillRealizerFunc
	// TurnRecorder, when set, receives one LLMCallRecord per successful provider
	// call (the assembled prompt + response + usage + latency) for trace/training
	// export. nil → no recording (the default; zero overhead). Opt-in because it
	// captures the full prompt on every call.
	TurnRecorder TurnRecorder
	// ProviderResolver, when set, maps the per-turn model to a distinct Provider
	// (multi-provider config/models.yaml: a model referencing a named provider is
	// served by that upstream). A model with no provider — or any resolution
	// failure — falls back to Provider. nil → the single Provider is always used
	// (unchanged single-provider behavior). Build it via NewProviderResolver.
	ProviderResolver ProviderResolver
	// MaxModelAttempts bounds how many distinct models a single turn may try
	// before surfacing the error (the initial model plus cross-model fallbacks).
	// Only relevant with a ModelSelector that opts into fallback — oss's
	// CapabilityDefault never does. <=0 → default 3.
	MaxModelAttempts int
	// MaxTransientRetries bounds same-model backoff retries for a transient
	// provider failure (rate_limit/server/overloaded/timeout/network) before
	// escalating to a fallback model or surfacing the error. 0 → default 2;
	// negative → disabled (surface immediately, the pre-safety-net behavior).
	MaxTransientRetries int
	// RetryBackoff returns the wait before transient retry attempt n (1-based).
	// nil → an exponential default (250ms, doubling, capped at 8s). The wait is
	// context-aware (a cancelled ctx aborts it).
	RetryBackoff func(attempt int) time.Duration
	// MaxToolIterations caps tool-call rounds per turn. <=0 defaults to 250.
	MaxToolIterations int
	// Steering delivers a user's mid-turn chat message into the turn already
	// running on its thread, at the next input-assembly boundary. It must be the
	// SAME inbox the runtime loop parks into. nil disables mid-turn delivery.
	Steering  *steering.Inbox
	Streaming bool
	// StreamFlushInterval coalesces streamed token deltas: deltas are buffered and
	// emitted as one token_delta at most once per interval (always on the first
	// delta; flushed before any other stream event and at finalize). This bounds
	// the per-turn message rate so a fast stream stays under the gateway's
	// per-identity quota. 0 (default) emits every delta immediately.
	StreamFlushInterval time.Duration

	// Memory integration (optional). When Memory is set: MemoryAutoCommit appends
	// the turn's user+assistant messages to the thread; MemoryAutoRecall injects
	// thread-scoped recalled memories into the turn context.
	Memory           MemoryService
	MemoryAutoCommit bool
	// MemoryAutoCommitAssistantOnly commits ONLY the assistant message on
	// auto-commit. Use it when the host already persists the user message (e.g.
	// the workclaw platform-server commits the inbound user turn before
	// dispatching the chat task); committing it again here would duplicate the
	// turn. Default false: commit user + assistant.
	MemoryAutoCommitAssistantOnly bool
	// MemoryAutoCommitAsync runs the post-turn commit in a detached goroutine so
	// it never blocks turn completion. Use it when the commit transport may stall
	// (e.g. a MemoryLayer ProxyHttp whose response does not yet route back through
	// the sandbox relay — the write still lands, but the response wait would
	// otherwise delay the turn). Only safe for long-lived runtimes (a CLI process
	// could exit before the goroutine finishes). Default false: synchronous.
	MemoryAutoCommitAsync    bool
	MemoryAutoRecall         bool
	MemoryRecallLimit        int
	MemoryRecallIncludeInput bool

	// Daily-notes startup context. When DailyNotes is set, the first turn of a
	// thread injects recent <DailyNotesDir>/memory/YYYY-MM-DD*.md as untrusted
	// background. Now supplies the clock (defaults to time.Now).
	DailyNotes     bool
	DailyNotesDir  string
	DailyNotesDays int
	Now            func() time.Time
	// NewThreadID mints a local thread id for a new chat that arrived with no
	// thread (and no ThreadRegistrar minted one). Defaults to a random hex id;
	// override for deterministic tests.
	NewThreadID func() string

	// Commands holds discovered workspace slash commands. Reserved built-ins
	// (/help, /commands, /clear) are always available; a nil registry just means
	// no workspace commands.
	Commands *commands.Registry

	// ScheduledOperations serves the reserved /schedules and /runs built-ins.
	// It is optional and normally configured only by an Aether worker host.
	ScheduledOperations ScheduledOperationsCommandProvider

	// RefinementAudit serves the reserved /refinements built-in. It is optional;
	// local and MemoryLayer-backed stores implement the same bounded query shape.
	RefinementAudit RefinementAuditCommandProvider

	// ExecutionLedger is the optional branch-aware operational audit. It also
	// persists /model pins and serves the model-free /ledger command. Local OSS
	// and distributed Aether compositions implement the same neutral contract.
	ExecutionLedger ExecutionLedger

	// Approvers gate tool calls (first denial wins); Observers watch the tool
	// lifecycle (no veto). Both are in-process today but the interfaces are
	// transport-agnostic so an external (e.g. Aether-ACL) approver or an OTel
	// observer can be plugged in later.
	Approvers []hooks.ToolApprover
	Observers []hooks.ToolObserver
	// TurnObservers watch the TURN lifecycle (start, each model call, compaction,
	// finish) — no veto. Peer to Observers (tool sub-lifecycle). A checkpoint/sync
	// or audit backend implements hooks.TurnObserver; unset → the turn fires
	// nothing. The distribution can also pass its command-hook Runtime here (it
	// implements TurnObserver) to drive external UserPromptSubmit/PostCompact hooks.
	TurnObservers []hooks.TurnObserver

	// Authority derives each turn's OBO authority from the inbound message. Core
	// leaves it nil; the distribution wires the grant extractor.
	Authority AuthorityFunc

	// DedupTrailingUserTurn drops a trailing user message from the loaded history
	// when it matches the incoming turn (same id, else same non-empty text) before
	// appending it. Use it when the host commits the inbound user turn to the store
	// out-of-band before dispatching (so the fetched history can already end with
	// it); the incoming turn is then kept as the canonical copy. Default false.
	DedupTrailingUserTurn bool

	// Approval flow (human-in-the-loop). When Approvals is set, a tool the policy
	// gates with "requires approval" emits an approval_request part and blocks for
	// an approve/deny control instead of erroring. ApprovalGranter records
	// session/always grants; ApprovalTimeout bounds the wait (0 = until ctx);
	// ApprovalScopes advertises offered scopes (default once/session/always).
	Approvals       approval.Awaiter
	ApprovalGranter ApprovalGranter
	ApprovalTimeout time.Duration
	ApprovalScopes  []string

	// ToolPolicy gates PROVIDER-surfaced tools (e.g. discovered MCP tools) in the
	// authorization pipeline: a default-trust provider tool is decided by the
	// policy (Allow / Deny / RequiresApproval → prompt), positioned after the
	// grant short-circuit (a pre-authorized/durably-granted tool skips it) and
	// before the safety authorizer. Optional; nil → provider tools are ungated by
	// policy (behavior unchanged). Local (static-registry) tools are NOT gated
	// here — they keep the registry's own policy via session.InvokeTool.
	ToolPolicy tools.Policy

	// GrantStore lets the approval slow-path consult durable "always" grants
	// before prompting: when a tool is already durably authorized for the
	// workspace, the runner records a session grant and runs it without
	// emitting an approval_request. Optional; nil → prompt every time (today's
	// behavior). Typically the same store backing ApprovalGranter's
	// GrantAlways persistence.
	GrantStore tools.GrantStore

	// SafetyAuthorizer is the pluggable safety slot in the tool authorization
	// pipeline. It runs for EVERY tool (local + provider, including
	// pre-authorized) and may Deny a call or escalate an Allow to a prompt.
	// Optional; nil → a no-op that abstains (behavior unchanged — this is the
	// future safety-classifier seam).
	SafetyAuthorizer ToolAuthorizer

	// ToolProviders are the generalized per-turn tool sources (unified discovery +
	// routing). Each is queried every turn; provided tools merge into the turn's
	// model-visible set and their invocations route back to the provider. Earlier
	// entries win a name collision among providers; the static registry always
	// wins over any provider. Optional; nil → providers-less.
	ToolProviders []ToolProvider

	// ToolSuggestionProviders contribute only dynamic prompt suggestions. They do
	// not change the ordered model tool-schema array or receive direct invocation.
	ToolSuggestionProviders []ToolSuggestionProvider

	// ToolCatalog is the common protocol-backed operational catalog used for
	// provider-surfaced tools. nil constructs an in-process standalone catalog,
	// preserving dependency-free OSS operation. A distribution may supply an
	// Aether-backed service instead.
	ToolCatalog *catalog.LiveService
	// ToolCatalogBinding derives trusted subject/context/policy-epoch state for
	// catalog query and invocation. nil uses the turn's MemoryAuthority/address,
	// with an explicit single-user fallback.
	ToolCatalogBinding ToolCatalogBindingFunc

	// Attachments, when set, resolves multimodal parts the provider cannot fetch
	// itself (vfs_ref-only image/file parts) into a model-deliverable carrier,
	// applied to the assembled request just before each provider call. Optional;
	// nil → NoopAttachmentResolver (logs undeliverable attachments, resolves
	// nothing). The sahara distribution wires a data-connectors-backed resolver.
	Attachments AttachmentResolver

	// Notifier is the ingress-write seam (channel.Enqueuer) a DETACHED background
	// sub-agent uses to push its completion notice back to the parent thread, waking
	// a fresh parent turn. Optional; nil → background sub-agents are unavailable and
	// spawn_subagent(background:true) falls back to a synchronous run. The web/tui
	// channels satisfy it directly; the Aether transport by messaging the parent.
	Notifier channel.Enqueuer
	// MaxBackgroundSubagents caps concurrent detached background children (excess
	// spawns queue on the semaphore). <=0 → default 4.
	MaxBackgroundSubagents int
	// StreamBackgroundSubagents, when true, streams a background child's activity via
	// the Publisher keyed to the child thread id (a client can subscribe to that
	// thread to render it). Default false: background children run silently (like
	// synchronous sub-agents). Independent of the child's durable commit either way.
	StreamBackgroundSubagents bool
	// StreamSubagents, when true, streams synchronous child activity via the
	// Publisher under the child thread id. Interactive clients can associate it
	// with the blocking parent spawn by TaskID. Default false.
	StreamSubagents bool
	// AuthHandoff hands the parent turn's OBO authority to the woken completion turn
	// via a single-use token carried on the notice (the credential never rides the
	// message). Optional; nil → a Store is created. The runner consumes the token
	// before applying the Authority hook; a distribution may also pre-resolve it
	// onto the context while routing across workspace-specific runners.
	AuthHandoff *authhandoff.Store
	// SubagentObserver receives best-effort authoritative lifecycle transitions
	// for durable registry/snapshot projection. Observation failures are logged
	// and never fail the child turn itself.
	SubagentObserver subagent.LifecycleObserver
	// SubagentDefaultWorkspace resolves registry identity when legacy local turns
	// omit workspace on their address. It is separate from DefaultWorkspaceID so
	// legacy unscoped transcript storage need not move on disk.
	SubagentDefaultWorkspace string
	// SubagentTasks optionally makes a durable task backend the execution
	// authority for child admission, running, terminal state, and restart
	// reconciliation. The lifecycle observer remains the session snapshot
	// projection. Nil preserves the independently useful local runner.
	SubagentTasks subagent.TaskBackend
	// SubagentExecutionScopeAuthorizer is called only for a requested binding
	// change or write-access expansion. Nil keeps OSS fail-closed while exact
	// inheritance and read-only narrowing remain independently useful.
	SubagentExecutionScopeAuthorizer subagent.ExecutionScopeAuthorizer
	// TurnJournal durably checkpoints parent model/tool execution. It is optional
	// so embedders retain the prior in-memory behavior; when set, OwnerIdentity is
	// required and active records are scoped to that stable runtime identity.
	TurnJournal       turnjournal.Store
	TurnOwnerIdentity string

	// Rubric, when set, runs an OPT-IN post-turn self-grading verifier: after a
	// turn finishes, an independent grader checks the just-produced result against
	// a declarative rubric and, if it needs revision, enqueues an actionable
	// revision follow-up (bounded by its MaxAttempts). Optional; nil → no grading
	// (default, behavior unchanged). The runner invokes AfterTurn at end-of-turn
	// when it is set.
	Rubric *RubricVerifier

	// Goals, when set, accounts finalized turns against durable goals and asks a
	// host-owned bounded policy whether to enqueue another turn. If Rubric is also
	// set it is used as the goal verifier; Rubric's standalone retry loop runs only
	// on turns not associated with a goal.
	Goals *goal.Runtime

	// ContextDecorator, when set, wraps the incoming turn ctx once at the start of
	// Run (before the tool loop), keyed off the resolved address. The ACP channel
	// uses it to attach per-session fs/terminal client delegates (tools.With*
	// Delegate) so the harness file/shell tools route through the editor. Optional;
	// nil → the ctx is untouched and turn behavior is byte-for-byte unchanged.
	ContextDecorator func(ctx context.Context, addr protocol.MessageAddress) context.Context
}

type ContextManager interface {
	Build(ctx context.Context, bootstrap []bootstrap.File, history []protocol.ChatMessage) ([]protocol.ChatMessage, error)
}

type ContextPreparer interface {
	Prepare(ctx context.Context) (context.Context, error)
}

type EventPublisher = channel.Publisher

type ExecutionLedger interface {
	RunExecutionLedgerCommand(
		ctx context.Context,
		addr protocol.MessageAddress,
		user protocol.ChatMessage,
		args string,
	) (string, error)
	PinnedModel(ctx context.Context, addr protocol.MessageAddress) (string, error)
	PinModel(ctx context.Context, addr protocol.MessageAddress, model string) error
}

type Grader interface {
	Grade(ctx context.Context, req RubricRequest) (RubricVerdict, error)
}

type LLMCallRecord struct {
	Timestamp string                 `json:"ts,omitempty"`
	Thread    string                 `json:"thread,omitempty"`
	Model     string                 `json:"model"`
	Messages  []protocol.ChatMessage `json:"messages"`
	Response  protocol.ChatMessage   `json:"response"`
	Usage     provider.Usage         `json:"usage"`
	LatencyMS int64                  `json:"latency_ms"`
}

type MemoryProviderNamer interface {
	MemoryProviderName() string
}

type MemoryService interface {
	Recall(ctx context.Context, auth tools.MemoryAuthority, workspace, query string, limit int) ([]tools.MemoryHit, error)
	// ownership selects the storage workspace: "" / "user" folds into the
	// backend's user-chat home; "workspace" homes the messages under workspace.
	AppendThreadMessages(ctx context.Context, auth tools.MemoryAuthority, workspace, threadID, ownership string, messages []protocol.ChatMessage) error
}

type NoopAttachmentResolver struct{}

type Provider interface {
	Chat(ctx context.Context, req provider.ChatRequest) (provider.ChatResponse, error)
}

type ProviderAuthResolver interface {
	Authenticator(kind, profile string) (llmclient.Authenticator, error)
}

type ProviderResolver interface {
	ProviderForModel(model string) (Provider, bool)
}

type ProviderResolverOption func(*providerResolver)

type ProviderRetryPayload struct {
	Attempt     int    `json:"attempt"`
	RetryInMS   int64  `json:"retry_in_ms"`
	Strategy    string `json:"strategy"`
	FailureKind string `json:"failure_kind,omitempty"`
	Model       string `json:"model,omitempty"`
	NextModel   string `json:"next_model,omitempty"`
	Message     string `json:"message"`
}

type RefinementAuditCommandProvider interface {
	RunRefinementAuditCommand(
		ctx context.Context,
		addr protocol.MessageAddress,
		user protocol.ChatMessage,
		args string,
	) (string, error)
}

type RubricRequest struct {
	Criteria []string
	Prompt   string
	Nonce    string
}

type RubricVerdict struct {
	Satisfied      bool     `json:"satisfied"`
	Feedback       string   `json:"feedback,omitempty"`
	FailedCriteria []string `json:"failed_criteria,omitempty"`
}

type RubricVerifier struct {
	// Criteria is the rubric — the SOLE definition of "done" the grader judges
	// against. Free-form lines ("the answer cites its sources", "tests pass", …).
	Criteria []string
	// Grader is the injected grading backend (a fake in tests; a spawned grader
	// sub-agent in production). Required — a nil Grader makes AfterTurn a no-op.
	Grader Grader
	// Enqueuer pushes the revision follow-up turn back to the thread. Optional;
	// nil → AfterTurn only reports the verdict (no automatic retry).
	Enqueuer channel.Enqueuer
	// MaxAttempts bounds how many revision follow-ups a thread may receive so a
	// stubborn turn can't loop forever. <=0 → defaultRubricMaxAttempts.
	MaxAttempts int
}

type Runner struct {
	// contains filtered or unexported fields
}

type ScheduledOperationsCommandProvider interface {
	RunScheduledOperationsCommand(
		ctx context.Context,
		addr protocol.MessageAddress,
		user protocol.ChatMessage,
		name string,
		args string,
	) (string, error)
}

type StreamingProvider interface {
	ChatStream(ctx context.Context, req provider.ChatRequest, onDelta provider.DeltaFunc) (provider.ChatResponse, error)
}

type ThreadRegistrar interface {
	EnsureThread(ctx context.Context, auth tools.MemoryAuthority, spec ThreadSpec) (threadID string, err error)
}

type ThreadSpec struct {
	WorkspaceID    string
	ThreadID       string
	ParentThreadID string
	// Origin records what created the thread (e.g. "subagent"); a hint only.
	Origin string
	// Ownership selects where the thread is stored: "" / "user" folds into the
	// backend's user-chat home; "workspace" homes the thread under WorkspaceID
	// (workspace-homed threads). A hint the registrar MAY honor.
	Ownership string
}

type ToolAuthorizer interface {
	Authorize(ctx context.Context, in AuthzInput) AuthzDecision
}

type ToolCatalogBindingFunc func(
	ctx context.Context,
	addr protocol.MessageAddress,
	user protocol.ChatMessage,
	catalogContext spec.ToolCatalogContext,
) (catalog.QueryBinding, error)

type ToolProvider interface {
	ID() string
	Tools(ctx context.Context, addr protocol.MessageAddress, user protocol.ChatMessage) ([]tools.Descriptor, error)
	Invoke(ctx context.Context, req tools.Request) (tools.Result, error)
}

type ToolSuggestionProvider interface {
	ID() string
	Suggestions(ctx context.Context, addr protocol.MessageAddress, user protocol.ChatMessage) ([]tools.Descriptor, error)
}

type TurnRecorder interface {
	RecordLLMCall(ctx context.Context, rec LLMCallRecord) error
}