interfaces

type ChannelManager interface {
	// GetChannel returns the channel with the given name.
	GetChannel(name string) (channels.Channel, bool)

	// GetEnabledChannels returns the list of enabled channel names.
	GetEnabledChannels() []string

	// InvokeTypingStop signals that typing has stopped.
	InvokeTypingStop(channel, chatID string)

	// SendMessage sends a text message to the specified channel and chat.
	SendMessage(ctx context.Context, msg bus.OutboundMessage) error

	// SendMessageDefiniteRetryOnly preserves ambiguous delivery failures and
	// retries only failures known to occur before remote acceptance.
	SendMessageDefiniteRetryOnly(ctx context.Context, msg bus.OutboundMessage) error

	// SendMedia sends a media message to the specified channel and chat.
	SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error

	// SendPlaceholder sends a placeholder message (e.g., for audio transcription).
	SendPlaceholder(ctx context.Context, channel, chatID string) bool

	// DismissToolFeedback clears tracked progress for the exact outbound
	// target. The message envelope keeps route, session, and turn identity
	// together; content and settlement fields are ignored.
	DismissToolFeedback(ctx context.Context, target bus.OutboundMessage)
}

type MessageBus interface {
	// PublishInbound sends an inbound message to be processed.
	PublishInbound(ctx context.Context, msg bus.InboundMessage) error

	// AckInbound confirms that a durable inbound message has been accepted or processed.
	AckInbound(ctx context.Context, msg bus.InboundMessage) error

	// ReleaseInbound returns a durable inbound message to the queue after a transient failure.
	ReleaseInbound(ctx context.Context, msg bus.InboundMessage, cause error) error

	// PendingInboundSpool returns durable inbound messages that are not acked yet.
	PendingInboundSpool(ctx context.Context) ([]bus.InboundMessage, error)

	// PublishObserved sends passive context that should be persisted without starting a turn.
	PublishObserved(ctx context.Context, msg bus.ObservedMessage) error

	// PublishOutbound sends an outbound message to the appropriate channel.
	PublishOutbound(ctx context.Context, msg bus.OutboundMessage) error

	// PublishOutboundMedia sends an outbound media message.
	PublishOutboundMedia(ctx context.Context, msg bus.OutboundMediaMessage) error

	// GetStreamer returns a channel streamer when the active channel supports streaming.
	GetStreamer(
		ctx context.Context,
		channel, chatID, sessionKey, requestID string,
		traceScope runtimeevents.TraceScope,
	) (bus.Streamer, bool)

	// InboundChan returns the channel for receiving inbound messages.
	InboundChan() <-chan bus.InboundMessage

	// ObservedChan returns passive messages that should be recorded without a response.
	ObservedChan() <-chan bus.ObservedMessage
}

type ProvisionalChannelSender interface {
	SendMessageProvisional(ctx context.Context, msg bus.OutboundMessage) error
	SendMediaProvisional(ctx context.Context, msg bus.OutboundMediaMessage) error
}