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 {
	ID, Question, Details string
	ConversationID        string
	Options               []AskUserQuestionOption
	Multiple              bool
}

type AttachmentPresence string

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

type Conversation struct {
	ID, Agent, CreatedBy, Space string
	Run                         *CronRun
}

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

type CronRun struct {
	Path   string
	At     time.Time
	OneOff bool
}

type CronRunResult struct {
	ConversationID string
}

type CronjobMessage struct {
	RelativePath, Agent, RanAt string
	// Space is the cron's own Web space, empty when it names none.
	Space string
}

type Event struct {
	Message         *OutboundMessage
	Acknowledgement chan error
}

type GoalAction string

type GoalRequest struct {
	Objective 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
	// OriginHeader, set on a follow-on message such as a scheduled message, a goal continuation or a
	// background wake, is the trusted origin header of the turn that created it, which permission
	// reviews of its turn read instead of one rendered from Source and Metadata.
	OriginHeader string
	// 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, Space string
	ConversationID                     string
}

type OutboundAttachment struct {
	ID                 string
	ConversationID     string `json:"conversation_id,omitempty"` // Actual owner when projecting an input reference.
	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
	Agent                              string
	Model, SourceConversationID        string
	ReasoningEffort                    *string
	Cronjob                            *CronjobMessage
	Complete                           bool
	SlackReply                         *SlackReplyTarget
	Attachments                        []OutboundAttachment
	GoalTurn, GoalComplete, GoalActive bool
	GoalTurnNumber, GoalMaxTurns       int
	// Source is the source of the inbound that started the turn.
	Source Source
	// Terminal is how a final's turn ended: complete, failed, or stopped.
	Terminal 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"`
}

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 {
	// MentionThread reports whether a conversation records the thread and whether it is a
	// read-only report thread: one an earlier version posted a cron report or External MCP session into.
	MentionThread(target TextConversationTarget) (recorded, report bool, err error)
	// SubmitMention records the thread's conversation with agent when absent and queues inbound
	// as its next turn, at most once per mention; it reports false for a mention already accepted,
	// and true with an error when the mention was queued but its pickup failed.
	SubmitMention(ctx context.Context, agent string, target TextConversationTarget, inbound *InboundMessage) (bool, error)
	// InterruptThread stops the thread's goal and interrupts its active turn without waiting for
	// a running turn to end.
	InterruptThread(target TextConversationTarget) (*InboundMessage, error)
	// WebURL links to the conversation in the Web Interface.
	WebURL(ctx context.Context, conversationID string) (string, error)
}

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"`
	// Origin is the trusted origin header of the message's turn: ScheduledMessage and its creator's source.
	Origin string `json:"origin,omitempty"`
}

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

type ShadowBinding struct {
	ParentConversationID, ParentAgent, ShadowAgent, ChildConversationID string
	Turns                                                               []ShadowTurn
}

type ShadowTurn struct {
	ParentSourceConversationID, ParentTurnID, ChildTurnID string
	Order                                                 int64
	Running                                               bool
	Terminal                                              Terminal
	Revision                                              string
}

type SlackReplyTarget struct{ ChannelID, MessageTS, ThreadTS string }

type Source string

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 interface {
	AskUserQuestion(context.Context, *AskUserQuestionRequest) (AskUserQuestionAnswer, error)
}

type WorkflowDescription struct{ Name, Description string }

type WorkflowInvocation struct {
	Name, Args string
}