protocol

type AskUserQuestionAnswer struct {
	Selected []string `json:"selected"`
	Custom   string   `json:"custom"`
	Source   Source   `json:"source"`
}

type AskUserQuestionOption struct{ Label, Value, Description string }

type AskUserQuestionRequest struct {
	Source                Source
	ID, Question, Details string
	ConversationID        string
	Options               []AskUserQuestionOption
	Multiple              bool
	SlackReply            *SlackReplyTarget
}

type AttachmentPresence string

type BackgroundJob struct {
	ID, Kind, State, Label, ToolCallID, SubagentKey, StoppedBy, Note string
	Hidden                                                           bool
}

type Conversation struct {
	ID, Agent, CreatedBy string
}

type ConversationChange struct {
	ConversationID string `json:"conversationId"`
	Revision       string `json:"revision"`
}

type CronRunResult struct {
	ConversationID string
}

type CronjobMessage struct {
	RelativePath, Agent, RanAt string
}

type Event struct {
	Message         *OutboundMessage
	Acknowledgement chan error
}

type ExternalMCPRelay struct {
	ConversationID, ExternalConversationID, Agent, Text string
	Attachments                                         []OutboundAttachment
}

type GoalAction string

type GoalRequest struct {
	Objective, CheckScript string
	MaxTurns               int
}

type InboundAttachment struct {
	Name, MIMEType string
	Data           []byte
}

type InboundContent struct {
	Text               string
	TextAttachments    []string
	Attachments        []InboundAttachment
	AttachmentPresence AttachmentPresence
	AttachmentWarnings []string
}

type InboundKind string

type InboundMessage struct {
	// Source is the surface that produced the message.
	Source Source
	// Text is the prompt body, with any text attachments appended after the typed text.
	Text string
	// Attachments are inline files, such as images, sent to the model alongside Text.
	Attachments []InboundAttachment
	// SlackReply is the Slack message that receives the reply; nil when the reply has no Slack target.
	SlackReply *SlackReplyTarget
	// AttachmentPresence records which attachments the source message carried, so the model can be told about ones it did not receive.
	AttachmentPresence AttachmentPresence
	// Human reports that a person wrote the message, rather than RocketClaw itself.
	Human bool
	// GoalTurn marks a turn that runs while a goal is active, including human input that does not spend the goal's turn budget.
	GoalTurn bool
	// AttachmentWarnings explain to the model, in plain text, why attachments were skipped.
	AttachmentWarnings []string
	// Kind says how the message enters the conversation's input queue.
	Kind InboundKind
	// GoalAction marks goal kickoff or continuation work that spends the goal's turn budget.
	GoalAction GoalAction
	// PreserveWhitespace keeps Text unchanged when framing the prompt instead of trimming it.
	PreserveWhitespace bool
	// ConversationID is the conversation that runs the turn; empty until the message is routed.
	ConversationID string
	// Metadata carries source-supplied context; the Inbound*MetadataKey keys are RocketClaw's trusted provenance and routing hints.
	Metadata map[string]string
	// Workflow, when it names a workflow, starts that workflow instead of an ordinary model turn.
	Workflow WorkflowInvocation
	// SyncDestination, when set, is a conversation that receives this turn: the turn waits in its queue,
	// runs in ConversationID, and then its new history and final reply are copied into SyncDestination.
	SyncDestination string
	// RequireOutputDecision marks a private cron-style background turn; an empty reply posts nothing.
	RequireOutputDecision bool
	// Cronjob identifies the cron job that produced the message; nil for other messages.
	Cronjob *CronjobMessage
	// contains filtered or unexported fields
}

type InboundResponse struct {
	Text        string
	Attachments []OutboundAttachment
	Err         error
}

type LaterWorkKind string

type LaterWorkRow struct {
	Kind        LaterWorkKind
	Queue       ThreadQueueItem
	ScheduledID string
	Scheduled   ScheduledMessageState
}

type OneOffCronjob struct {
	Agent, Prompt, RelativePath, TextChannel string
	ConversationID                           string
}

type OutboundAttachment struct {
	ID                 string
	Name, MIMEType     string
	Data               []byte `json:"-"` // Persisted turn state keeps only ID; large files exceed Postgres JSON limits.
	OriginalUnverified bool
	Size               int64 // Stored byte length for metadata-only reads.
}

type OutboundMessage struct {
	ConsumedID, ConsumedText           string
	ConsumedHeader                     string
	ConsumedRawText                    string
	ConsumedSource                     Source
	Text                               string
	ConversationID, TurnID             string
	ExternalConversationID             string
	Agent                              string
	Model, SourceConversationID        string
	ReasoningEffort                    *string
	Cronjob                            *CronjobMessage
	Complete                           bool
	SlackReply                         *SlackReplyTarget
	Attachments                        []OutboundAttachment
	GoalTurn, GoalComplete, GoalActive bool
	GoalTurnNumber, GoalMaxTurns       int
	WorkflowTerminal                   Terminal
	// ReplyState is the connector's recorded reply attachment for TurnID, copied
	// from the turn's journal when the turn finishes, so a delivery after a restart
	// edits the original placeholder.
	ReplyState json.RawMessage `json:",omitempty"`
	// contains filtered or unexported fields
}

type OutboundPublisher interface {
	PublishOutbound(context.Context, *OutboundMessage) error
}

type PhaseStatus string

type PhaseUpdate struct {
	PhaseID, Name                string
	Status                       PhaseStatus
	Scheduled, Running, Complete int
}

type PrimaryTextRouter interface {
	StartThread(ctx context.Context, agent string, target TextConversationTarget, inbound *InboundMessage) error
	StartGoalInThread(ctx context.Context, agent, objective, checkScript string, maxTurns int, target TextConversationTarget, inbound *InboundMessage) error
	SkillDescriptions(agent string) ([]SkillDescription, error)
	InterruptConversation(conversationID string) *InboundMessage
	InterruptThread(target TextConversationTarget) (*InboundMessage, error)
	RegisterThread(target TextConversationTarget, agent string) (created bool, err error)
	ThreadAgent(target TextConversationTarget) (agent string, handled bool, err error)
	SwitchThreadAgent(target TextConversationTarget, agent string) (bool, error)
	SubmitThreadReply(ctx context.Context, target TextConversationTarget, inbound *InboundMessage) (bool, error)
	StashThreadQueueItem(ctx context.Context, target TextConversationTarget, item *ThreadQueueItem) error
	ThreadQueueItems(target TextConversationTarget) ([]ThreadQueueItem, error)
	DeleteThreadQueueItem(ctx context.Context, target TextConversationTarget, id string) (bool, error)
	PromoteThreadQueueItem(ctx context.Context, target TextConversationTarget, id string) (bool, error)
	ScheduledMessages(target TextConversationTarget) (map[string]ScheduledMessageState, error)
	ThreadBusy(target TextConversationTarget) bool
}

type ScheduledMessageState struct {
	ConversationID string        `json:"conversation_id,omitempty"`
	Agent          string        `json:"agent,omitempty"`
	Message        string        `json:"message,omitempty"`
	DueAt          time.Time     `json:"due_at,omitzero"`
	Recurring      bool          `json:"recurring,omitempty"`
	Interval       time.Duration `json:"interval,omitempty"`
}

type SessionSummary struct {
	ConversationID, LastMessage string
	LastUpdated                 time.Time
}

type SkillDescription struct {
	Name, Description string
}

type SlackReplyTarget struct {
	ChannelID, MessageTS, ThreadTS   string
	RecipientTeamID, RecipientUserID string
}

type Source string

type StartNewThreadRequest struct {
	CurrentAgent, Agent, Title, Prompt, CreatedBy string
	AllowedAgents                                 []string
}

type StartNewThreadResult struct {
	ConversationID string `json:"conversation_id"`
	URL            string `json:"url"`
}

type Terminal string

type TextConversationTarget struct{ ChannelID, MessageID, ThreadID string }

type ThreadQueueItem struct {
	Kind           InboundKind
	ID             string
	ConversationID string
	Message        string
	Content        InboundContent
	Source         Source
	SlackReply     *SlackReplyTarget
	Principal      string
	StashAt        time.Time
	Position       int
	ParkAfter      string
	SlackChannel   string
	SlackTS        string
	// Inbound, when set, is the full stored request; it replaces the fields above when the row runs.
	Inbound *InboundMessage
}

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

type WorkflowDescription struct{ Name, Description string }

type WorkflowInvocation struct {
	Name, Args string
}