threadcase

type ConversationMessage struct {
	Timestamp string
	UserID    string
	UserName  string
	Text      string
}

type CreateDecision struct {
	Title       string          `json:"title" description:"A concise case title summarising the thread." required:"true"`
	Description string          `json:"description" description:"A clear case description derived from the thread and your investigation." required:"true"`
	Fields      []DecisionField `` /* 134-byte string literal not displayed */
}

type CreatePayload struct {
	Title       string
	Description string
	Fields      map[string]model.FieldValue
}

type Decision struct {
	Kind        DecisionKind    `` /* 300-byte string literal not displayed */
	Message     string          `json:"message,omitempty" description:"For respond: the reply text shown to the user. Omit for materialize."`
	Title       string          `json:"title,omitempty" description:"For materialize: a concise case title summarising the thread."`
	Description string          `json:"description,omitempty" description:"For materialize: a clear case description derived from the thread."`
	Fields      []DecisionField `json:"fields,omitempty" description:"For materialize: custom field assignments. Only include fields you are confident about."`
}

type DecisionField struct {
	FieldID string   `json:"field_id" description:"The field id from the workspace schema." required:"true"`
	Value   string   `json:"value,omitempty" description:"Scalar value (text / number / url / single select option id)."`
	Values  []string `json:"values,omitempty" description:"Multi-select option ids."`
}

type DecisionKind string

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

type Handler interface {
	// TraceAppend records a milestone line that must stay visible (planner
	// rounds, task results) in the thread-side trace block.
	TraceAppend(ctx context.Context, line string)
	// TraceReplace overwrites the single transient activity line in place, so
	// per-tool chatter ("Searching…", "Fetching…") does not accumulate.
	TraceReplace(ctx context.Context, line string)
	// Question posts a question to the user. Returning an error aborts the turn.
	Question(ctx context.Context, ssn *model.Session, q QuestionPayload) error
	// Create persists a new case for the ModeCreate flow and returns it. The host
	// invokes it once, AFTER the turn completes, with the field values the
	// in-loop finalizer already validated against the workspace schema. A returned
	// error is a persistence failure the model cannot repair by re-emitting JSON,
	// so it is NOT fed back for regeneration; the host surfaces it and falls back.
	// Only called in ModeCreate turns.
	Create(ctx context.Context, ssn *model.Session, p CreatePayload) (*model.Case, error)
}

type HandlerFuncs struct {
	TraceAppendFn  func(ctx context.Context, line string)
	TraceReplaceFn func(ctx context.Context, line string)
	QuestionFn     func(ctx context.Context, ssn *model.Session, q QuestionPayload) error
	CreateFn       func(ctx context.Context, ssn *model.Session, p CreatePayload) (*model.Case, error)
}

type Host interface {
	// ApplyMention applies a completed mention turn's terminal decision: post the
	// reply, or write the proposed content onto the case and confirm it.
	ApplyMention(ctx context.Context, target Target, decision *Decision) error
	// CreateCase commits a completed create turn's proposal and posts its outcome.
	CreateCase(ctx context.Context, target Target, payload CreatePayload) error
	// AskQuestion posts the planner's question and records it on the session. The
	// turn has ended; the user's answer starts the next one.
	AskQuestion(ctx context.Context, target Target, question QuestionPayload) error
	// ReportFallback tells the user the turn reached no conclusion. reason is the
	// technical cause; the host decides how much of it to show.
	ReportFallback(ctx context.Context, target Target, reason string) error
}

type Mode int

type QuestionItem struct {
	ID      string
	Text    string
	Type    QuestionItemType
	Options []string
}

type QuestionItemType string

type QuestionPayload struct {
	Reason string
	Items  []QuestionItem
}

type Result struct {
	Status Status
	// BusyOwner is the session whose turn holds the thread, set only on
	// StatusBusy.
	BusyOwner *model.Session
}

type Status int

type Target struct {
	WorkspaceID string
	// CaseID is 0 for a create turn: the case does not exist yet.
	CaseID    int64
	SessionID string
	// ChannelID / ThreadTS are the run's own thread — the case thread, which the
	// Session is keyed on and where the case's content belongs.
	ChannelID string
	ThreadTS  string
	// UIChannelID / UIThreadTS are the thread the requester is watching. They
	// differ from the pair above only for a case raised by a reaction in another
	// channel; otherwise they hold the same values.
	UIChannelID string
	UIThreadTS  string
	// ProcessID is the run that produced this outcome. A host that records a
	// question needs it so the turn started by the answer can inherit this run's
	// conversation.
	ProcessID string
}

type TurnRequest struct {
	Session   *model.Session
	Workspace *model.WorkspaceEntry
	Case      *model.Case

	ChannelID string
	ThreadTS  string
	// UIChannelID / UIThreadTS locate the thread the requester is watching, for the
	// one flow where that is not ChannelID / ThreadTS: a case raised by a reaction
	// lives in the monitored channel while the reactor watches the thread they
	// reacted in. Progress, questions and failure notices go there. Empty means the
	// two are the same thread.
	UIChannelID string
	UIThreadTS  string
	MentionTS   string
	// MentionText is the raw text of the mention that triggered this turn.
	MentionText string
	// MentionUserID / MentionUserName identify its author. The ID is what makes
	// a self-referential request ("assign me") actionable: case__assign takes
	// Slack user IDs and no tool resolves a display name into one. It is also the
	// run's access actor.
	MentionUserID   string
	MentionUserName string

	SystemMessages []ConversationMessage
	DeltaMessages  []ConversationMessage

	// TriggerTS is the Slack TS of the event that started this turn. It is the
	// idempotency key, which is what makes a re-delivered Slack event resolve to
	// the run it already started instead of starting a second one.
	TriggerTS string

	// InheritFrom continues a finished run's conversation in this one. It is how an
	// answered question resumes: the answering turn is a NEW run — its own budget,
	// its own record — but it must see the request, the investigation and the
	// question that produced it. Empty starts a fresh conversation.
	InheritFrom string

	// Mode selects the turn purpose (materialize on creation vs mention).
	Mode Mode

	// CreateInstruction is an optional extra instruction appended to the
	// ModeCreate planner system prompt (under a "# Trigger context" heading).
	// It lets a host inject trigger-specific guidance the generic prompt cannot
	// know — e.g. that the case was raised by a reaction on one message and the
	// surrounding conversation must be read. Empty and ignored for other modes.
	CreateInstruction string
}