events

package
v0.0.48 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 22, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package events defines shared RocketClaw event contracts.

Index

Constants

View Source
const (
	// InboundOriginMetadataKey overrides the trusted prompt provenance origin.
	InboundOriginMetadataKey = "rocketclaw_origin"
	// InboundMediaMetadataKey overrides the trusted prompt provenance media.
	InboundMediaMetadataKey = "rocketclaw_media"
	// InboundPrincipalMetadataKey identifies the trusted human principal for prompt provenance.
	InboundPrincipalMetadataKey = "rocketclaw_principal"
	// InboundAllowedAgentsMetadataKey lists source-surface allowed agents for model-created child conversations.
	InboundAllowedAgentsMetadataKey = "rocketclaw_allowed_agents"
	// InboundStartNewThreadDisabledMetadataKey suppresses model-created child conversation tooling for this turn.
	InboundStartNewThreadDisabledMetadataKey = "rocketclaw_start_new_thread_disabled"
)
View Source
const MaxInboundTextAttachmentBytes = 256 << 10

MaxInboundTextAttachmentBytes is the per-file size limit for attachments converted to prompt text.

Variables

This section is empty.

Functions

func AttachmentNamesSpeech

func AttachmentNamesSpeech(attachments []OutboundAttachment) string

AttachmentNamesSpeech returns a short spoken description of attachment names.

func IsTextAttachment added in v0.0.7

func IsTextAttachment(name, mimeType string) bool

IsTextAttachment reports whether an attachment should be included as literal prompt text.

func SetInboundAllowedAgents added in v0.0.16

func SetInboundAllowedAgents(inbound *InboundMessage, agents []string)

SetInboundAllowedAgents records surface-constrained agents on an inbound message.

func StartNewThreadRootText added in v0.0.16

func StartNewThreadRootText(title, prompt string) string

StartNewThreadRootText returns the human-visible root text for tool-created text conversations.

Types

type AskUserQuestionAnswer added in v0.0.12

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

AskUserQuestionAnswer is returned to RocketCode after a human answers.

type AskUserQuestionOption added in v0.0.12

type AskUserQuestionOption struct{ Label, Value, Description string }

AskUserQuestionOption is one native UI choice for ask_user_question.

type AskUserQuestionRequest added in v0.0.12

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

AskUserQuestionRequest asks the originating text connector human for input.

type BridgeID added in v0.0.45

type BridgeID string

BridgeID identifies a connector participating in RocketClaw communication.

const (
	// BridgeSlack identifies the Slack connector.
	BridgeSlack BridgeID = "slack"
	// BridgeExternalMCP identifies the External MCP connector.
	BridgeExternalMCP BridgeID = "external_mcp"
)

type Broadcast added in v0.0.45

type Broadcast struct {
	Sender          BridgeID
	Message         *OutboundMessage
	Delivery        *OutboundMessage
	Relay           *ExternalMCPRelay
	RelayReply      *InboundMessage
	RelayChannel    string
	RelayCleanup    *InboundMessage
	RelayResponse   chan BroadcastReply
	Acknowledgement chan BroadcastAcknowledgement
}

Broadcast carries live output to Bridges other than its sender.

func (*Broadcast) Clone added in v0.0.45

func (b *Broadcast) Clone() Broadcast

Clone returns an independent delivery copy of b with its own acknowledgement channel.

type BroadcastAcknowledgement added in v0.0.45

type BroadcastAcknowledgement struct {
	Status BroadcastStatus
	Err    error
}

BroadcastAcknowledgement reports the outcome of one Bridge delivery.

type BroadcastPublisher added in v0.0.45

type BroadcastPublisher chan<- Broadcast

BroadcastPublisher adapts the Broadcasts channel to the outbound publisher contract.

func (BroadcastPublisher) PublishOutbound added in v0.0.45

func (p BroadcastPublisher) PublishOutbound(ctx context.Context, message *OutboundMessage) error

PublishOutbound publishes one live output Broadcast.

type BroadcastReply added in v0.0.45

type BroadcastReply struct {
	Message *InboundMessage
	Err     error
}

BroadcastReply carries the result of a Bridge-specific Broadcast operation.

type BroadcastStatus added in v0.0.45

type BroadcastStatus string

BroadcastStatus describes how a Bridge handled a Broadcast.

const (
	// BroadcastHandled reports that a Bridge delivered or acted on a Broadcast.
	BroadcastHandled BroadcastStatus = "handled"
	// BroadcastDropped reports that a Bridge intentionally ignored a Broadcast.
	BroadcastDropped BroadcastStatus = "dropped"
	// BroadcastFailed reports that a Bridge could not handle a Broadcast.
	BroadcastFailed BroadcastStatus = "failed"
)

type Channels added in v0.0.45

type Channels struct {
	Requests   chan Request
	Broadcasts chan Broadcast
}

Channels are the two unbuffered channels used for connector communication.

func NewChannels added in v0.0.45

func NewChannels() Channels

NewChannels constructs the unbuffered connector channels.

type CronjobMessage added in v0.0.43

type CronjobMessage struct {
	RelativePath, Agent, RanAt string
}

CronjobMessage identifies a human-visible cronjob result.

type ExternalMCPRelay added in v0.0.33

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

ExternalMCPRelay carries one MCP request to its Slack surface.

type InboundAttachment

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

InboundAttachment carries an inline attachment into a conversation prompt.

type InboundContent added in v0.0.7

type InboundContent struct {
	Text                   string
	TextAttachments        []string
	Attachments            []InboundAttachment
	HadAttachments         bool
	HadNonImageAttachments bool
	AttachmentWarnings     []string
}

InboundContent carries source-acquired inbound text and attachments before message routing details are applied.

type InboundKind

type InboundKind string

InboundKind describes how an inbound message should be handled.

const (
	// InboundKindPrompt is a normal conversational prompt.
	InboundKindPrompt InboundKind = "prompt"
	// InboundKindInternalize is a note the session should absorb without replying.
	InboundKindInternalize InboundKind = "internalize"
)

type InboundMessage

type InboundMessage struct {
	Source                                                  Source
	Bridge                                                  BridgeID
	Label, Text                                             string
	VerbatimMessage                                         string
	VerbatimAttachments                                     []OutboundAttachment
	Attachments                                             []InboundAttachment
	SlackReply                                              *SlackReplyTarget
	HadAttachments, HadNonImageAttachments, Human, GoalTurn bool
	AttachmentWarnings                                      []string
	Kind                                                    InboundKind
	ConversationID                                          string
	Metadata                                                map[string]string
	Workflow                                                *workflow.RunRequest
	Response                                                chan Response
	// contains filtered or unexported fields
}

InboundMessage is a message headed into its conversation prompt queue.

func NewInboundMessage added in v0.0.33

func NewInboundMessage(source Source, kind InboundKind, label, text string, human bool) *InboundMessage

NewInboundMessage constructs an unrouted inbound message.

func NewInboundMessageFromContent added in v0.0.33

func NewInboundMessageFromContent(source Source, kind InboundKind, label string, content *InboundContent, human bool) *InboundMessage

NewInboundMessageFromContent constructs an unrouted inbound message from normalized source content.

func (*InboundMessage) CompleteResponse

func (m *InboundMessage) CompleteResponse(text string, err error)

CompleteResponse marks this inbound turn result ready.

func (*InboundMessage) CompleteResponseWithAttachments added in v0.0.7

func (m *InboundMessage) CompleteResponseWithAttachments(text string, attachments []OutboundAttachment, err error)

CompleteResponseWithAttachments marks this inbound turn result ready with response attachments.

func (*InboundMessage) EnableResponseWait

func (m *InboundMessage) EnableResponseWait() <-chan InboundResponse

EnableResponseWait returns a channel that receives the final result for this inbound turn.

type InboundResponse

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

InboundResponse is the final plain-text result for a queued inbound turn.

type OutboundAttachment

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

OutboundAttachment carries a human-visible file attachment to output sinks.

func CloneOutboundAttachments

func CloneOutboundAttachments(attachments []OutboundAttachment) []OutboundAttachment

CloneOutboundAttachments returns a deep copy of attachments.

type OutboundMessage

type OutboundMessage struct {
	Text, ProgressText                 string
	Source                             Source
	Bridge                             BridgeID
	Targets                            []OutputTarget
	ConversationID, TurnID             string
	SessionEntryID                     int64
	ExternalConversationID             string
	Agent                              string
	Cronjob                            *CronjobMessage
	Sequence                           int
	PostProgressText, Complete         bool
	SlackReply                         *SlackReplyTarget
	Attachments                        []OutboundAttachment
	GoalTurn, GoalComplete, GoalActive bool
	GoalTurnNumber, GoalMaxTurns       int
	WorkflowAgent                      *workflow.AgentUpdate
	WorkflowPhase                      *workflow.PhaseUpdate
	WorkflowTerminal                   workflow.Terminal
	Response                           chan Response
	// contains filtered or unexported fields
}

OutboundMessage is a text message headed to enabled connectors.

func CloneOutboundMessage added in v0.0.45

func CloneOutboundMessage(message *OutboundMessage) *OutboundMessage

CloneOutboundMessage returns a deep copy suitable for an independent connector delivery.

func NewOutboundMessage added in v0.0.33

func NewOutboundMessage(source Source, conversationID, text string, targets ...OutputTarget) *OutboundMessage

NewOutboundMessage constructs an outbound message for one explicit conversation.

func (*OutboundMessage) MarkDelivered

func (m *OutboundMessage) MarkDelivered(err error)

MarkDelivered marks outbound delivery for this message complete.

func (*OutboundMessage) WaitDelivered

func (m *OutboundMessage) WaitDelivered(ctx context.Context) error

WaitDelivered waits until outbound delivery for this message finishes.

type OutboundPublisher added in v0.0.45

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

OutboundPublisher sends one outbound message into connector delivery.

type OutputTarget

type OutputTarget string

OutputTarget identifies which connector should receive an outbound message.

const (
	// OutputTargetSlack delivers a response to its explicit Slack thread.
	OutputTargetSlack OutputTarget = "slack"
)

type Request added in v0.0.45

type Request struct {
	Sender    BridgeID
	Operation RequestOperation
	Response  chan Response
}

Request carries one connector operation into RocketClaw.

type RequestKind added in v0.0.45

type RequestKind string

RequestKind identifies the operation carried by a Request.

const (
	RequestTextStartThread           RequestKind = "text_start_thread"
	RequestTextStartGoal             RequestKind = "text_start_goal"
	RequestTextStartWorkflow         RequestKind = "text_start_workflow"
	RequestTextReserveWorkflowTurn   RequestKind = "text_reserve_workflow_turn"
	RequestTextWorkflowDescriptions  RequestKind = "text_workflow_descriptions"
	RequestTextInterruptConversation RequestKind = "text_interrupt_conversation"
	RequestTextInterruptThread       RequestKind = "text_interrupt_thread"
	RequestTextRegisterThread        RequestKind = "text_register_thread"
	RequestTextRegisterCronThread    RequestKind = "text_register_cron_thread"
	RequestTextThreadAgent           RequestKind = "text_thread_agent"
	RequestTextSwitchThreadAgent     RequestKind = "text_switch_thread_agent"
	RequestTextSubmitThreadReply     RequestKind = "text_submit_thread_reply"
	RequestTextSubmitExternalMCP     RequestKind = "text_submit_external_mcp"
)

Text request operation kinds.

type RequestOperation added in v0.0.45

type RequestOperation interface {
	RequestKind() RequestKind
}

RequestOperation is the typed operation payload carried by a Request. Concrete operation values are defined alongside the shared event data they use.

type Response added in v0.0.45

type Response struct {
	Payload ResponsePayload
	Err     error
}

Response carries progress, interaction, result, or error information for a Request.

type ResponseKind added in v0.0.45

type ResponseKind string

ResponseKind identifies the kind of value carried by a Response.

const (
	// ResponseProgress carries observable operation progress.
	ResponseProgress ResponseKind = "progress"
	// ResponseInteraction carries an interaction for a connector to handle.
	ResponseInteraction ResponseKind = "interaction"
	// ResponseResult carries a completed operation result.
	ResponseResult ResponseKind = "result"
)

type ResponsePayload added in v0.0.45

type ResponsePayload interface {
	ResponseKind() ResponseKind
}

ResponsePayload is the typed value carried by a Response.

type SlackReplyTarget

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

SlackReplyTarget identifies the Slack message that owns a streamed reply.

type Source

type Source string

Source identifies where an inbound or outbound message originated.

const (
	SourceSlack       Source = "slack"
	SourceExternalMCP Source = "external_mcp"
	SourceSystem      Source = "system"
)

Known inbound and outbound message source labels.

type StartNewThreadRequest added in v0.0.16

type StartNewThreadRequest struct {
	Source                                                   Source
	Bridge                                                   BridgeID
	SourceConversationID, CurrentAgent, Agent, Title, Prompt string
	AllowedAgents                                            []string
	SlackReply                                               *SlackReplyTarget
	Response                                                 chan Response
}

StartNewThreadRequest asks RocketClaw to create a new managed conversation from the current turn.

type StartNewThreadResponse added in v0.0.45

type StartNewThreadResponse struct {
	Request *StartNewThreadRequest
	Root    chan StartNewThreadRootResult
	Err     chan error
}

StartNewThreadResponse asks a connector to create a native thread root.

func (StartNewThreadResponse) ResponseKind added in v0.0.45

func (StartNewThreadResponse) ResponseKind() ResponseKind

ResponseKind identifies the child-thread interaction.

type StartNewThreadResult added in v0.0.16

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

StartNewThreadResult reports the created conversation and openable surface.

type StartNewThreadRootResult added in v0.0.16

type StartNewThreadRootResult struct {
	Target TextConversationTarget
	URL    string
}

StartNewThreadRootResult reports the native root surface created by a text connector.

type TextConversationTarget added in v0.0.7

type TextConversationTarget struct{ ChannelID, MessageID, ThreadID string }

TextConversationTarget identifies a conversation/message in the configured primary text connector.

type TextRequest added in v0.0.45

type TextRequest struct {
	Kind                                      RequestKind
	Target                                    TextConversationTarget
	Agent, Objective, CheckScript, Name, Args string
	ConversationID                            string
	MaxTurns                                  int
	Inbound                                   *InboundMessage
}

TextRequest carries one operation formerly sent through the primary text router.

func (*TextRequest) RequestKind added in v0.0.45

func (r *TextRequest) RequestKind() RequestKind

RequestKind identifies the TextRequest operation.

type TextResponse added in v0.0.45

type TextResponse struct {
	Kind         ResponseKind
	Message      *OutboundMessage
	Handled      bool
	Created      bool
	Reserved     bool
	Agent        string
	Descriptions []workflow.Description
	Inbound      *InboundMessage
	Release      chan struct{}
}

TextResponse carries the result of one TextRequest operation.

func (*TextResponse) ResponseKind added in v0.0.45

func (r *TextResponse) ResponseKind() ResponseKind

ResponseKind identifies the TextResponse result.

type UserQuestionAsker added in v0.0.45

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

UserQuestionAsker is the origin-owned ask_user_question capability for one turn path. The zero value is inert (ExposeTool is false).

func InteractiveUserQuestionAsker added in v0.0.45

func InteractiveUserQuestionAsker(ask func(context.Context, *AskUserQuestionRequest) (AskUserQuestionAnswer, error)) UserQuestionAsker

InteractiveUserQuestionAsker returns an asker that exposes the tool and delegates to ask.

func NoUserQuestionAsker added in v0.0.45

func NoUserQuestionAsker() UserQuestionAsker

NoUserQuestionAsker returns the inert asker that omits the tool from the model list.

func (UserQuestionAsker) AskUserQuestion added in v0.0.45

AskUserQuestion runs the origin ask path, or rejects when the tool is not exposed.

func (UserQuestionAsker) ExposeTool added in v0.0.45

func (a UserQuestionAsker) ExposeTool() bool

ExposeTool reports whether ask_user_question belongs in the model tool list.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL