messaging

type AttachmentKind string

type AttachmentStream struct {
	Reader      io.ReadCloser
	Filename    string
	MediaType   string
	ContentSize int64
}

type DurableDeliveryExecutor interface {
	ExecuteDurableDelivery(context.Context, DurableDeliveryRequest) (DurableDeliveryResult, error)
}

type DurableDeliveryRequest struct {
	Intent            session.DeliveryIntent
	Operation         session.DeliveryOperation
	Dependency        *session.DeliveryOperation
	Caption           string
	ArtifactKind      AttachmentKind
	ArtifactFilename  string
	ArtifactMediaType string
	OpenArtifact      func(context.Context) (io.ReadCloser, error)
}

type DurableDeliveryResult struct {
	Status            string
	ProviderAssetID   string
	ProviderMessageID string
	ProviderState     []byte
	FailureCode       string
	NextAttemptAt     *time.Time
}

type InboundMessage struct {
	Platform string // "wechat", "feishu", etc.
	ChatID   string // Conversation/chat identifier
	UserID   string // Sender user ID
	// MessageID is an optional provider-native event/message identifier. It is
	// used only for durable background idempotency when a platform supplies one.
	MessageID string
	UserName  string    // Sender display name
	Text      string    // Message text content
	Timestamp time.Time // When the message was sent
	// Attachments contains opaque, platform-authenticated media references.
	// The channel dispatcher turns these into Runtime-owned attachments before
	// any Agent is constructed. Transport adapters must not put a public URL or
	// credential in Reference.
	Attachments []PlatformAttachment
	// ReplyContext is an opaque platform-owned value (for example WeChat's
	// context_token) captured at ingress and frozen by Runtime delivery plans.
	ReplyContext string

	// ProgressFunc is called to send intermediate progress updates during agent execution.
	// If nil, no progress updates are sent.
	ProgressFunc func(text string)
}

type MessageHandler func(ctx context.Context, msg InboundMessage) (MessageResponse, error)

type MessageResponse struct {
	Text         string
	TextDelivery *OutboundText
	// TextDeliveries is the ordered Runtime projection for caption and
	// fallback operations. TextDelivery remains the first-operation
	// compatibility field for older embedders.
	TextDeliveries []OutboundText
	Attachments    []OutboundAttachment
}

type OutboundAttachment struct {
	ID                string
	RunID             string
	TargetID          string
	ReplyContext      string
	UploadOperationID string
	SendOperationID   string
	ProviderAssetID   string
	ProviderState     []byte
	Kind              AttachmentKind
	Filename          string
	MediaType         string
	Prepare           func(context.Context) error
	// ProgressUpload persists provider state while the upload operation keeps
	// its lease. It is called before the next provider phase.
	ProgressUpload func(context.Context, string, string, string, string)
	CompleteUpload func(context.Context, string, string, string, string)
	PrepareSend    func(context.Context) error
	CompleteSend   func(context.Context, string, string, string, string)
	Open           func(context.Context) (io.ReadCloser, error)
	// Complete remains for transports that perform upload and send in one
	// opaque call. New staged transports should use the phase callbacks above.
	Complete func(ctx context.Context, status, providerMessageID, failureCode string)
}

type OutboundText struct {
	ID             string
	RunID          string
	TargetID       string
	ReplyMessageID string
	ReplyContext   string
	// Text is the exact payload for this durable operation. It lets a
	// transport preserve operation boundaries when MessageResponse.Text is a
	// compatibility summary containing more than one text operation.
	Text     string
	Prepare  func(context.Context) error
	Complete func(context.Context, string, string, string)
}

type Platform interface {
	// Name returns the platform identifier (e.g. "wechat", "feishu").
	Name() string
	// Start begins receiving messages. Blocks until ctx is cancelled or Stop is called.
	Start(ctx context.Context, handler MessageHandler) error
	// Stop gracefully shuts down the platform connection.
	Stop() error
	// SendMessage sends a text message to a specific chat.
	SendMessage(ctx context.Context, chatID string, text string) error
	// IsConnected reports whether the platform is currently connected.
	IsConnected() bool
}

type PlatformAttachment struct {
	Reference string
	Kind      AttachmentKind
	Filename  string
	MediaType string
	SizeHint  int64
	MessageID string
	Open      func(context.Context) (AttachmentStream, error)
}

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

type Readiness interface {
	Ready() <-chan error
}

type StatusCallbackSetter interface {
	SetStatusCallback(callback func(connected bool))
}