proposal

type Handler interface {
	// Question renders the planner's terminal question payload. Items can
	// be 1-5 with each item carrying a select / multi-select control.
	Question(ctx context.Context, ssn *model.Session, q QuestionPayload) error
	// Materialize persists / refreshes the CaseProposal for ssn with the given
	// payload. The host validates against the workspace's FieldSchema.
	Materialize(ctx context.Context, ssn *model.Session, m MaterializePayload) error
	// Trace appends one progress line to the host's per-turn trace UI.
	// Used for phase-level updates (planner round start, planner.message).
	// Per-task transitions go through TraceTask instead.
	Trace(ctx context.Context, line string)
	// TraceRound posts or updates a per-round phase line. The first call
	// for a given roundKey posts a fresh thread reply; subsequent calls
	// with the same key REPLACE the prior content of that round's
	// message in place (no append). This collapses the
	// "Planning… → retry → Planning… → action" sequence within one
	// planner round into a single self-updating message instead of a
	// stack of three Slack posts. A new roundKey opens a new message;
	// passing an empty roundKey or empty line is a no-op.
	TraceRound(ctx context.Context, roundKey, line string)
	// RegisterTasks reserves a stable trace block per investigation task
	// before the sub-agents start. The host renders one block per task in
	// the supplied order so subsequent TraceTask calls overwrite that
	// block in place. Block creation is deliberately the host's job —
	// sub-agents only update their line via TraceTask, never create new
	// blocks. Calling RegisterTasks with an empty slice is a no-op.
	RegisterTasks(ctx context.Context, tasks []TaskInfo)
	// TraceTask updates the line associated with a task that was previously
	// registered via RegisterTasks. Calling with an unknown taskID is a
	// no-op; calling before RegisterTasks is also a no-op (the host has no
	// block to address). The line replaces the prior content for that task
	// — there is no append.
	TraceTask(ctx context.Context, taskID, line string)
	// PostBusy notifies the user that another turn is running on this
	// session and the new trigger is being dropped.
	PostBusy(ctx context.Context, ssn *model.Session, info agent.BusyInfo) error
}

type HandlerFuncs struct {
	QuestionFn      func(ctx context.Context, ssn *model.Session, q QuestionPayload) error
	MaterializeFn   func(ctx context.Context, ssn *model.Session, m MaterializePayload) error
	TraceFn         func(ctx context.Context, line string)
	TraceRoundFn    func(ctx context.Context, roundKey, line string)
	RegisterTasksFn func(ctx context.Context, tasks []TaskInfo)
	TraceTaskFn     func(ctx context.Context, taskID, line string)
	PostBusyFn      func(ctx context.Context, ssn *model.Session, info agent.BusyInfo) error
}

type MaterializePayload struct {
	WorkspaceID       string
	Title             string
	Description       string
	CustomFieldValues map[string]any
	// IsTest marks the proposed case as a test case. Defaults to false.
	IsTest bool
}

type QuestionItem struct {
	// ID uniquely identifies the question within the payload; the host
	// uses it to correlate answers back when the user submits.
	ID string
	// Text is the prompt shown to the user.
	Text string
	// Type discriminates the answer control (select / multi_select /
	// free_text).
	Type QuestionItemType
	// Options is the allowed answer set for select / multi_select
	// (always ≥2 entries). Ignored for free_text.
	Options []string
}

type QuestionItemType string

type QuestionPayload struct {
	// Reason explains the information gap (single rationale shared across
	// all items).
	Reason string
	// Items is the ordered list of questions to ask in this turn. Always
	// non-empty (validation guarantees ≥1).
	Items []QuestionItem
}

type Result struct {
	Status Status
	// EndedWith is the SessionEndReason recorded on Session when the turn
	// hit a terminal action. Zero-valued for StatusBusy / StatusIdempotent.
	EndedWith model.SessionEndReason
	// FallbackReason describes why StatusFallback was returned (e.g.
	// "planner budget exhausted"). Non-empty only when Status==Fallback.
	FallbackReason string
}

type Status int

type TaskInfo struct {
	ID    string
	Title string
}

type Trigger int

type TurnRequest struct {
	// Session is the per-thread Session row. The runtime reads / writes
	// the turn-lock fields via deps.StartTurn.
	Session *model.Session

	// UserInput is the planner's first user message. For app_mention this
	// is the mention text; for thread_reply it is the reply text; for
	// ws_switch it is a synthetic system event sentence (see spec §2.11).
	UserInput string

	// Trigger discriminates the entry point — drives prompt hints.
	Trigger Trigger

	// TriggerTS is the Slack TS used as both the trace ID and the lock
	// trigger key. For ws_switch, the host generates a UUID and uses it
	// here.
	TriggerTS string

	// ActorUserID is the Slack user who initiated the turn. Pass to
	// sub-agent tools that need actor authorisation.
	ActorUserID string

	// ExistingProposal is the prior draft persisted by the host (when this
	// turn is resuming an existing draft, e.g. ws-switch or thread reply).
	// The planner does not consume it directly — the host uses it to keep
	// preview state coherent across turns.
	ExistingProposal *model.CaseProposal

	// Handler implements the host-side terminal action dispatchers and
	// trace updates.
	Handler Handler
}

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