planexec

type BudgetConfig struct {
	// PlannerLoopMax bounds the number of planner (or replan) LLM
	// invocations (rounds) within one run. Planner / replan output that fails
	// validation is retried within the same pool. (Final-output regeneration in
	// Run[T] is bounded separately by finalOutputMaxRetry and does NOT consume
	// planner rounds.)
	PlannerLoopMax int

	// SubAgentLoopMax bounds the inner gollem loop limit of each
	// sub-agent (passed through to gollem.WithLoopLimit). Granted fresh to
	// every sub-agent, so it recovers per round.
	SubAgentLoopMax int
}

type DirectPlan struct {
	// Tools is the subset of RunRequest.KnownToolIDs the direct agent may
	// call. May be empty for a pure conversational reply that needs no tool.
	// Bounded by maxToolsPerTask.
	Tools []string `json:"tools,omitempty"`
}

type FinalizePlan struct {
	// Reason is a 1-sentence rationale for terminating now (optional).
	Reason string `json:"reason,omitempty"`
}

type PhaseSummary struct {
	Phase   int
	Tasks   []TaskPlan
	Results []TaskResult
}

type PlanInfo struct {
	// Round is 1-based.
	Round int
	// Reasoning is the planner's `message` field (1-2 sentence rationale).
	Reasoning string
	// IsReplan is true when this round was a replan (i.e. Round > 1).
	IsReplan bool
	// Direct is true when this round chose the direct (no-investigation)
	// fast path instead of proposing tasks. Round is 1 in this case and no
	// PhaseStarted / TaskProgress events follow.
	Direct bool
}

type PlanResult struct {
	// Message is a 1-2 sentence rationale shown to the user via
	// Sink.PlanProposed.
	Message string `json:"message,omitempty"`
	// Tasks is the parallel investigation phase emitted by the planner.
	// Empty / omitted when Direct is set — the two are mutually exclusive.
	Tasks []TaskPlan `json:"tasks,omitempty"`
	// Direct, when non-nil, signals the planner judged the request trivial
	// enough to answer without any investigation phase. The nil Direct (the
	// common case) means "investigate via Tasks". Mutually exclusive with
	// Tasks; rejected unless RunRequest.AllowDirect is true.
	Direct *DirectPlan `json:"direct,omitempty"`
}

type Question struct {
	// Reason is the rationale shared across every item ("why am I
	// asking?").
	Reason string `json:"reason"`
	// Items is the ordered list of questions to ask (1..5 items,
	// enforced by Validate).
	Items []QuestionItem `json:"items"`
}

type QuestionAnswer struct {
	ID       string   `json:"id"`
	Choice   string   `json:"choice,omitempty"`    // select
	Choices  []string `json:"choices,omitempty"`   // multi_select
	FreeText string   `json:"free_text,omitempty"` // free_text
}

type QuestionItem struct {
	ID      string           `json:"id"`
	Text    string           `json:"text"`
	Type    QuestionItemType `json:"type"`
	Options []string         `json:"options,omitempty"`
}

type QuestionItemType string

type QuestionResult struct {
	// Terminate, when true, signals planexec.Runner to stop the loop
	// immediately and return RunStatus=Completed without invoking the
	// final-response phase. Used by proposal to defer the conversation
	// to the next thread reply.
	Terminate bool
	// Items, when Terminate=false, supplies the user's answers and the
	// loop continues with these injected into the next planner round.
	// Empty when Terminate=true.
	Items []QuestionAnswer
}

type ReplanResult struct {
	Message  string        `json:"message,omitempty"`
	Tasks    []TaskPlan    `json:"tasks,omitempty"`
	Question *Question     `json:"question,omitempty"`
	Finalize *FinalizePlan `json:"finalize,omitempty"`
}

type ResumeRequest struct {
	// RunRequest carries the same identity / planner / tool / output
	// configuration as the original Run. HistoryKey MUST equal the
	// suspended run's key so the conversation continues. UserInput is
	// validated (non-empty) but not used to drive the first round — the
	// answers do; callers may set it to the original job prompt.
	RunRequest

	// Question is the question the planner asked before suspending,
	// reconstructed by the host from its persisted form. Used to label the
	// answers in the resumed planner input.
	Question Question

	// Answers is the user's reply, one entry per answered item. Required
	// (non-empty).
	Answers []QuestionAnswer
}

type RunRequest struct {

	// HistoryKey is the gollem.WithHistoryRepository key. Required.
	// Used to bind every planner / replan call to one continuous
	// conversation history.
	HistoryKey string

	// TraceID is the trace.WithTraceID value handed to the trace.Recorder.
	// Required.
	TraceID string

	// TraceMetadata is attached to the trace.Recorder as labels.
	// Optional — zero value is fine.
	TraceMetadata trace.TraceMetadata

	// TraceHandler, when non-nil, is wired (in addition to the run's
	// internal archive recorder) into every gollem agent the run drives —
	// planner, sub-agents, direct, and final — so a host can capture
	// per-call LLM / tool events for its own timeline. The Job host
	// supplies its jobRunTraceHandler here so planexec Jobs populate the
	// JobRunEvent timeline the same way the single-loop executor does.
	// Optional; nil preserves the archive-only behaviour (the proposal
	// host passes nil).
	TraceHandler trace.Handler

	// LanguageLabel is interpolated into the planner system prompt's
	// "respond in" directive (e.g. "Japanese", "English"). Optional —
	// empty disables the directive.
	LanguageLabel string

	// UserInput is the very first user message handed to the planner.
	// Required.
	UserInput string

	// SystemPrompt is the planner's base system prompt. Required.
	// Host-specific guidance lives here; planexec appends only the
	// budget / action-shape boilerplate it owns.
	SystemPrompt string

	// PlannerTools are tools the planner itself is allowed to call
	// during a round (e.g. proposal's wsmeta tools). Optional — nil
	// means the planner is tool-less.
	PlannerTools []gollem.Tool

	// AllowDirect lets the planner short-circuit round 1: when the request
	// is trivially answerable without any investigation phase, the planner
	// may emit a `direct` payload instead of `tasks`, and the runtime
	// answers in a single tool-enabled ReAct loop. The direct path is plain
	// text only: even under Run[T] it returns RunResult.Text (not Data), since
	// side-effecting terminal actions must go through the investigate →
	// finalize loop. Hosts opt in (structured-only flows may still enable it
	// for a trivial text reply). Default false.
	AllowDirect bool

	// AllowSubAgentWrites lets this run's sub-agents perform writes /
	// side-effecting actions (post a message, change case status, ...) with
	// the tools the planner assigns them, instead of being restricted to
	// observation-only investigation. Default false → sub-agents are told
	// they are observation-only (the historical behaviour).
	//
	// The flag governs only the sub-agent prompt wording; the tools a
	// sub-agent can physically call are decided by ToolResolver. A caller
	// that sets this false MUST supply a read-only resolver so a sub-agent
	// is never handed a write tool it is then told not to use — that
	// prompt-vs-capability mismatch is exactly the failure this feature
	// fixes. A caller that sets it true supplies a resolver that includes
	// the write tools, and the planner assigns them per task.
	//
	// job sets true (Job deliverables are side effects, e.g. a Slack post);
	// threadcase sets true for mention turns (the sub-agent may close /
	// transition the case via case__update_case_status) and false for create
	// turns (no case to act on yet; the case is materialized by the host from
	// the structured final output).
	AllowSubAgentWrites bool

	// ToolResolver maps TaskPlan.Tools entries into concrete gollem
	// tool slices for each sub-agent. Required.
	ToolResolver ToolResolver

	// KnownToolIDs is the enum the planner sees in the JSON schema's
	// task.tools field. Required (must be non-empty).
	KnownToolIDs []string

	// AllowQuestion toggles the question section in the planner prompt
	// and schema. proposal sets true; job sets false.
	AllowQuestion bool

	// OnQuestion is the host callback fired when the planner emits a
	// Question. Required iff AllowQuestion is true.
	OnQuestion func(ctx context.Context, q Question) (QuestionResult, error)

	// Sink is the progress / state output channel. Required (use
	// SinkFuncs{} for a no-op).
	Sink Sink
}

type RunResult[T any] struct {
	Status RunStatus
	// Data is the validated structured final output. Non-nil ONLY for a Run[T]
	// turn that completed via an explicit finalize (not direct, not question,
	// not fallback). Always nil for RunText / ResumeText.
	Data *T
	// Text is the plain-text terminal reply: the whole output of RunText /
	// ResumeText, OR the round-1 direct fast-path reply on any run
	// (Direct == true). Empty for a structured Run[T] that finalized normally
	// (the payload is in Data instead).
	Text string
	// Direct is true when the turn terminated via the round-1 direct fast path
	// (no investigation phase ran); Text holds the reply and Data is nil.
	Direct bool
	// EndedWithQuestion is true when the loop exited because OnQuestion returned
	// QuestionResult{Terminate: true}. Status is still StatusCompleted; the host
	// uses this to distinguish "we answered" from "we asked".
	EndedWithQuestion bool
	// AllResults is the per-phase observation trail.
	AllResults []PhaseSummary
	// FallbackReason is the human-readable cause for a StatusFallback* result.
	FallbackReason string
}

type RunStatus int

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

type RunnerDeps struct {
	LLMClient   gollem.LLMClient
	HistoryRepo gollem.HistoryRepository
	TraceRepo   trace.Repository
	Budget      BudgetConfig
}

type Sink interface {
	// Notify is a free-form line aimed at the user. Examples:
	// planner.message at the top of a phase, "couldn't reach a
	// conclusion" on fallback, etc.
	Notify(ctx context.Context, line string)

	// PlanProposed fires once per planner round AFTER the JSON parses.
	// The host typically renders the round's reasoning / message into a
	// progress card that it can later update in place.
	PlanProposed(ctx context.Context, info PlanInfo)

	// PhaseStarted reserves a progress block per TaskPlan before the
	// sub-agents start. Tasks come in the order they will run; the host
	// renders one row each and addresses them via TaskProgress later.
	PhaseStarted(ctx context.Context, phase int, tasks []TaskInfo)

	// TaskProgress overwrites the line of a previously-registered task
	// (running / tool-call / final result snippet). The host MUST
	// no-op gracefully if taskID is unknown — that path fires when a
	// progress middleware races a phase boundary.
	TaskProgress(ctx context.Context, taskID, line string)

	// TaskFinished marks a single task as completed or failed. The host
	// updates the corresponding row to its terminal display.
	TaskFinished(ctx context.Context, result TaskResult)
}

type SinkFuncs struct {
	NotifyFn       func(ctx context.Context, line string)
	PlanProposedFn func(ctx context.Context, info PlanInfo)
	PhaseStartedFn func(ctx context.Context, phase int, tasks []TaskInfo)
	TaskProgressFn func(ctx context.Context, taskID, line string)
	TaskFinishedFn func(ctx context.Context, result TaskResult)
}

type TaskInfo struct {
	ID    string
	Title string
}

type TaskPlan struct {
	ID                 string   `json:"id"`
	Title              string   `json:"title"`
	Description        string   `json:"description"`
	AcceptanceCriteria string   `json:"acceptance_criteria"`
	Tools              []string `json:"tools"`
}

type TaskResult struct {
	TaskID             string
	Title              string
	AcceptanceCriteria string
	Status             TaskStatus
	Summary            string
	Error              string

	// InnerLoopsUsed / InnerLoopsMax surface in the trace UI but are not
	// fed back into the planner (the planner doesn't need them for
	// decisions).
	InnerLoopsUsed int64
	InnerLoopsMax  int
}

type TaskStatus string

type ToolResolver interface {
	// Resolve returns the concatenated tool list for the requested IDs.
	// Unknown IDs MUST be silently dropped — they should already have
	// been rejected at plan validation, and we never want to crash a
	// running sub-agent because the planner emitted a stray name.
	Resolve(ids []string) []gollem.Tool
}

type Validatable interface {
	Validate() error
}