planexec

type Asker interface {
	Ask(ctx context.Context, pid agentkit.ProcessID, meta map[string]string,
		key agentkit.AwaitKey, q Question) error
}

type Config[T Validatable] struct {
	// Decode turns the terminal JSON into T. nil uses encoding/json.
	Decode func([]byte) (*T, error)
	// Finalizers run in order after T.Validate(); the first rejection wins.
	Finalizers []Finalizer[T]
	// Asker delivers a question for a host that waits in-band. Required when a run
	// sets Input.SuspendOnQuestion — without one there would be nobody to show the
	// question to, and the run would park on an await nothing can answer.
	Asker Asker
	// TextOnly generates the terminal output as prose instead of JSON and puts it
	// in Output.Text.
	TextOnly bool
	// Remaining reports what this run may still spend and the total it was
	// allowed, so the planner can size the tasks it plans and each child can be
	// given a ceiling of its own.
	//
	// It is a function rather than a value because a strategy is registered once
	// at startup and then serves every run: the figures come from the run's own
	// metadata and metrics, never from anything a registration could close over.
	// Same reason Finalizers take the run's metadata.
	//
	// nil turns the per-task budget off entirely: the planner is shown no budget
	// line, `budget_usd` leaves the task schema and is not validated, and a child
	// is spawned with the metadata it would have had otherwise — its parent's, so
	// it is judged against the ROOT figure on its own metrics.
	Remaining func(meta map[string]string, metrics agentkit.Metrics) (remaining, total pricing.NanoUSD)
}

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 Finalizer[T any] func(ctx context.Context, meta map[string]string, out *T) error

type Input struct {
	// SystemPrompt is the host's base persona prompt. The planner prompt is
	// rendered around it.
	SystemPrompt string `json:"system_prompt"`
	// UserInput is the first user message.
	UserInput string `json:"user_input"`
	// LanguageLabel ("Japanese", "English", …) drives the user-facing-language
	// directive. Empty omits it.
	LanguageLabel string `json:"language_label,omitempty"`
	// KnownToolIDs is the toolset-id vocabulary the planner may assign to a task.
	// It is both the prompt's enumeration and the JSON schema's enum.
	KnownToolIDs []string `json:"known_tool_ids"`
	// TaskContext is an opaque block the host renders into EVERY sub-agent's
	// system prompt. planexec neither parses nor validates it.
	//
	// It exists because a sub-agent's prompt is otherwise built from the planner's
	// task text alone, while its tools are pinned to the run's subject: a task
	// handed the Slack read tools and told to "read the case thread" has no way to
	// know the channel id or thread ts, so it invents them and the call fails
	// (slack__get_messages then reports "requires both channel_id and ts"). The
	// host puts the identifiers its tools are pinned to here — see
	// .claude/rules/architecture.md § "Agent tool wiring": a prompt that names a
	// tool and the context that tool needs must ship together.
	TaskContext string `json:"task_context,omitempty"`

	AllowQuestion       bool `json:"allow_question,omitempty"`
	AllowDirect         bool `json:"allow_direct,omitempty"`
	AllowSubAgentWrites bool `json:"allow_sub_agent_writes,omitempty"`
	// SuspendOnQuestion keeps the run open across the human's reply instead of
	// ending the turn on it: the run parks on a question await and continues when
	// the host calls Kernel.Respond with the answer.
	//
	// A host should set it ONLY when its own record spans the wait — an
	// interactive Job, whose run id covers the whole exchange. For a Slack thread
	// it is the wrong trade: the run would hold the thread's subject for as long as
	// the person takes to answer, blocking every later turn on that thread.
	SuspendOnQuestion bool `json:"suspend_on_question,omitempty"`

	// Progress locates the thread milestone lines are drawn into. A zero value
	// draws nothing.
	Progress ProgressTarget `json:"progress,omitempty"`
}

type Output[T any] struct {
	Kind OutputKind `json:"kind"`
	// Data is the validated structured output. Set only for OutputFinal on a
	// structured host.
	Data *T `json:"data,omitempty"`
	// Text is the reply for OutputDirect, and for OutputFinal on a text-only host.
	Text string `json:"text,omitempty"`
	// Question is what to ask the user. Set only for OutputQuestion.
	Question *Question `json:"question,omitempty"`
	// FallbackReason says why no conclusion was reached.
	FallbackReason string `json:"fallback_reason,omitempty"`
	// Observations is the per-round trail, carried on every kind so even a
	// fallback can report what was learnt.
	Observations []PhaseSummary `json:"observations,omitempty"`
}

type OutputKind string

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

type PlanResult struct {
	// Message is a 1-2 sentence rationale for the decision. No code reads it, and
	// that is not a reason to remove it: the planner reply carrying it is committed
	// to the run's conversation and recorded as that transition's LLM_RESPONSE, so
	// it is what the run timeline and the trace archive preserve of WHY the turn
	// decided as it did. Deleting the field would take that out of the record.
	//
	// It is NOT user-facing. The user sees the progress lines the strategy writes
	// and the terminal output, never this. (It once reached the user through
	// Sink.PlanProposed, removed with the in-process Runner in #261.) Do not wire it
	// into a reply — publishing the planner's reasoning as the answer is exactly
	// what rationaleDescription is worded to prevent.
	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 Progress interface {
	// Render draws lines as one message and returns its id. An empty messageTS
	// means "post a new one"; anything else means "update that one".
	Render(ctx context.Context, target ProgressTarget, messageTS string, lines []string) (string, error)
}

type ProgressTarget struct {
	ChannelID string `json:"channel_id,omitempty"`
	ThreadTS  string `json:"thread_ts,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 is the replan round's counterpart of PlanResult.Message, kept for the
	// same reason and carrying the same warning: no code reads it, it survives in
	// the run's record, and it is not user-facing.
	Message  string        `json:"message,omitempty"`
	Tasks    []TaskPlan    `json:"tasks,omitempty"`
	Question *Question     `json:"question,omitempty"`
	Finalize *FinalizePlan `json:"finalize,omitempty"`
}

type TaskPlan struct {
	ID                 string   `json:"id"`
	Title              string   `json:"title"`
	Description        string   `json:"description"`
	AcceptanceCriteria string   `json:"acceptance_criteria"`
	Tools              []string `json:"tools"`
	// BudgetUSD is what this task's sub-agent may spend, in USD, carved by the
	// planner out of what the run has left. It is the planner's job because the
	// planner is the only party that knows which of the tasks it just wrote is the
	// heavy one.
	//
	// It is omitempty and validated only when the host wired Config.Remaining: a
	// host that did not is not asking for per-task budgets, and its children keep
	// inheriting the run's own figure.
	BudgetUSD float64 `json:"budget_usd,omitempty"`
}

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

type TaskStatus string

type TextResult struct {
	Text string `json:"text"`
}

type Validatable interface {
	Validate() error
}