events

package
v0.0.21 Latest Latest
Warning

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

Go to latest
Published: Jun 30, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package events defines the shared rocketclaw event bus.

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.

View Source
const TerminalCLIClientIDMetadataKey = "terminal_cli_client_id"

TerminalCLIClientIDMetadataKey identifies the attached terminal client for terminal-originated turns.

View Source
const TerminalCLIEmbeddedClientID = "embedded"

TerminalCLIEmbeddedClientID marks direct in-process CLI input that has no server-owned control client.

Variables

View Source
var ErrBusClosed = errors.New("bus closed")

ErrBusClosed reports that an event was published after the bus shut down.

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 MainConversationID

func MainConversationID() string

MainConversationID returns the stable key for the shared main session.

func SetInboundAllowedAgents added in v0.0.16

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

SetInboundAllowedAgents records surface-constrained agents on an inbound message.

func StartNewThreadFirstPrompt added in v0.0.16

func StartNewThreadFirstPrompt(req *StartNewThreadRequest, targetAgent string) string

StartNewThreadFirstPrompt returns the first model-visible task prompt body for tool-created conversations.

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
	ID, Question, Details string
	ConversationID        string
	TerminalClientID      string
	Options               []AskUserQuestionOption
	Multiple              bool
	SlackReply            *SlackReplyTarget
	DiscordReply          *DiscordReplyTarget
}

AskUserQuestionRequest asks the originating text connector human for input.

type AudioChunk

type AudioChunk struct {
	SessionID, SpeakerID, Format string
	Source                       Source
	RTPSequence                  uint16
	Timestamp, SSRC              uint32
	SampleRate, Channels         int
	Data                         []byte
}

AudioChunk carries a connector audio frame into the transcription pipeline.

type Bus

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

Bus routes inbound text, outbound text, and audio events between components.

func New

func New(configs ...Config) *Bus

New constructs an event bus.

func (*Bus) Audio

func (b *Bus) Audio(ctx context.Context) iter.Seq[*AudioChunk]

Audio returns a single-use iterator over inbound audio chunks.

func (*Bus) Close

func (b *Bus) Close()

Close shuts down the bus and wakes all waiting consumers.

func (*Bus) Inbound

func (b *Bus) Inbound(ctx context.Context) iter.Seq[*InboundMessage]

Inbound returns a single-use iterator over inbound text messages.

func (*Bus) Observe added in v0.0.12

func (b *Bus) Observe(ctx context.Context) iter.Seq[ObservedMessage]

Observe returns a non-consuming single-use iterator over inbound and outbound text events.

func (*Bus) Outbound

func (b *Bus) Outbound(ctx context.Context) iter.Seq[*OutboundMessage]

Outbound returns a single-use iterator over outbound text messages.

func (*Bus) PublishAudio

func (b *Bus) PublishAudio(ctx context.Context, chunk *AudioChunk) error

PublishAudio publishes an audio chunk into the voice pipeline.

func (*Bus) PublishInbound

func (b *Bus) PublishInbound(ctx context.Context, msg *InboundMessage) error

PublishInbound publishes a text message into the shared input queue.

func (*Bus) PublishOutbound

func (b *Bus) PublishOutbound(ctx context.Context, msg *OutboundMessage) error

PublishOutbound publishes a text message to all output sinks.

func (*Bus) StopInbound

func (b *Bus) StopInbound()

StopInbound stops new inbound messages while allowing accepted messages to be dequeued.

func (*Bus) WaitInboundDequeued

func (b *Bus) WaitInboundDequeued(ctx context.Context, logger *slog.Logger) error

WaitInboundDequeued waits for accepted inbound work to leave the bus queues.

func (*Bus) WaitOutboundIdle

func (b *Bus) WaitOutboundIdle(ctx context.Context, logger *slog.Logger) error

WaitOutboundIdle waits until outbound work is queued nowhere and delivered everywhere.

type Config

type Config struct {
	MinimumWaitAfterHumanInteraction time.Duration
}

Config controls event bus behavior.

type DiscordReplyTarget

type DiscordReplyTarget struct{ ChannelID, MessageID, ThreadID string }

DiscordReplyTarget identifies the Discord message or thread that owns a streamed reply.

type InboundAttachment

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

InboundAttachment carries an inline attachment into the shared main-session 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
	Label, Text                                             string
	VerbatimMessage                                         string
	VerbatimAttachments                                     []OutboundAttachment
	Attachments                                             []InboundAttachment
	SlackReply                                              *SlackReplyTarget
	DiscordReply                                            *DiscordReplyTarget
	HadAttachments, HadNonImageAttachments, Human, GoalTurn bool
	AttachmentWarnings                                      []string
	Kind                                                    InboundKind
	ConversationID, WebSessionID                            string
	Metadata                                                map[string]string
	// contains filtered or unexported fields
}

InboundMessage is a message headed into the shared main-session prompt queue.

func NewMainInboundMessage

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

NewMainInboundMessage constructs a message for the shared main session.

func NewMainInboundMessageFromContent added in v0.0.7

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

NewMainInboundMessageFromContent constructs a main 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 ObservedMessage added in v0.0.12

type ObservedMessage struct {
	Inbound  *InboundMessage
	Outbound *OutboundMessage
}

ObservedMessage is a non-consuming bus event tap record.

type Observer added in v0.0.12

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

Observer receives non-consuming inbound and outbound bus events.

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
	Targets                              []OutputTarget
	ConversationID, TurnID, WebSessionID string
	Sequence                             int
	PostProgressText, Complete           bool
	SlackReply                           *SlackReplyTarget
	DiscordReply                         *DiscordReplyTarget
	Checkpoint                           *ResponseCheckpoint
	Attachments                          []OutboundAttachment
	GoalTurn, GoalComplete               bool
	GoalTurnNumber, GoalMaxTurns         int
	// contains filtered or unexported fields
}

OutboundMessage is a text message headed to enabled connectors.

func NewMainOutboundMessage

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

NewMainOutboundMessage constructs an outbound message for the shared main session.

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 OutputTarget

type OutputTarget string

OutputTarget identifies which connector should receive an outbound message.

const (
	// OutputTargetSlackMain delivers a response to the main Slack DM.
	OutputTargetSlackMain OutputTarget = "slack_main"
	// OutputTargetDiscordText delivers a response to Discord text.
	OutputTargetDiscordText OutputTarget = "discord_text"
	// OutputTargetDiscord delivers a response to Discord voice.
	OutputTargetDiscord OutputTarget = "discord"
	// OutputTargetWebUI delivers a response to the browser voice-mode client.
	OutputTargetWebUI OutputTarget = "web_ui"
	// OutputTargetTerminal delivers a response to the invoking terminal CLI.
	OutputTargetTerminal OutputTarget = "terminal"
)

func MainOutputTargets

func MainOutputTargets() []OutputTarget

MainOutputTargets returns the default targets for main-session replies.

type ResponseCheckpoint

type ResponseCheckpoint struct {
	ConversationID, ResponseID, Model, AssistantText string
	SessionEntryID                                   int64
}

ResponseCheckpoint identifies a persisted main-session turn that can seed a Slack thread.

type SlackReplyTarget

type SlackReplyTarget struct{ ChannelID, MessageTS, ThreadTS 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"
	SourceDiscordText  Source = "discord_text"
	SourceDiscordVoice Source = "discord_voice"
	SourceExternalMCP  Source = "external_mcp"
	SourceTerminalCLI  Source = "terminal_cli"
	SourceWebVoice     Source = "web_voice"
	SourceSystem       Source = "system"
)

Known inbound and outbound message source labels.

type StartNewThreadRequest added in v0.0.16

type StartNewThreadRequest struct {
	Source                                                   Source
	SourceConversationID, CurrentAgent, Agent, Title, Prompt string
	TerminalClientID                                         string
	AllowedAgents                                            []string
	SlackReply                                               *SlackReplyTarget
	DiscordReply                                             *DiscordReplyTarget
}

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

type StartNewThreadResult added in v0.0.16

type StartNewThreadResult struct {
	ConversationID string `json:"conversation_id"`
	URL            string `json:"url,omitempty"`
	AttachCommand  string `json:"attach_command,omitempty"`
	CMUXOpened     bool   `json:"cmux_opened,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.

Jump to

Keyboard shortcuts

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