chat

type Adapter interface {
	// Platform returns the platform name matched against [Message.Platform].
	Platform() string
	// Account returns the bot/business account identity matched against
	// [Message.Account]. An empty string makes the adapter the wildcard for
	// its platform: it receives every message no more specific adapter
	// claims. Registering several adapters for one platform requires
	// distinct accounts.
	Account() string
	// NewDelivery creates the output surface for one turn. A non-empty
	// resumePreviewID signals crash recovery: Finalize must edit that
	// message instead of sending a new one.
	NewDelivery(key ConversationKey, replyTo string, resumePreviewID string) Delivery
	// Download resolves an attachment reference to its content and MIME type.
	Download(ctx context.Context, ref AttachmentRef) (io.ReadCloser, string, error)
}

type Agent struct {
	// Serve runs the agent's ACP server on one connection until it closes.
	Serve func(ctx context.Context, in io.Reader, out io.Writer) error
	// Connect returns the command line of a process that relays its stdio to
	// the ACP socket at path, for a client that starts its agent as a command.
	Connect func(socket string) ([]string, error)
	// Environ is the environment the agent's tools get; Export adds to it.
	Environ func() []string
	Export  func(name, value string)
	// Log receives the platform's diagnostics.
	Log io.Writer
}

type AttachmentRef struct {
	// Kind is one of "photo", "document", "audio", "video", "voice".
	Kind string `json:"kind"`
	// ID is the platform handle (telegram file_id / whatsapp media id).
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
	MIME string `json:"mime,omitempty"`
	Size int64  `json:"size,omitempty"`
}

type Conversation struct {
	Reset   func() error
	Session *agent.AgentSession
	// Manager receives ledger writes and serves raw entry reads.
	Manager *sessionstore.SessionManager
	// Close persists and releases the conversation; it must be called
	// exactly once.
	Close func(ctx context.Context) error
}

type ConversationKey struct {
	Tenant   string
	Platform string
	Account  string
	ChatID   string
	ThreadID string
}

type Delivery interface {
	// Typing signals a best-effort, repeatable typing indicator.
	Typing(ctx context.Context) error
	// Preview creates or edits the persistent preview message.
	Preview(ctx context.Context, text string) error
	// PreviewID returns the platform id of the preview message, or "" until
	// a preview exists.
	PreviewID() string
	// Finalize delivers the final text: it edits the preview when possible
	// and chunks long text into follow-up messages.
	Finalize(ctx context.Context, text string) (Receipt, error)
	// Notify sends a small out-of-band notice (/status output, errors).
	Notify(ctx context.Context, text string) error
}

type FileSender interface {
	// SendFile sends size bytes of content as the file name to the
	// conversation key, or fails with the platform's reason, a size limit
	// included.
	SendFile(ctx context.Context, key ConversationKey, name string, size int64, content io.Reader) error
}

type Handler interface {
	Handle(ctx context.Context, m Message) error
}

type Identity struct {
	Name, About, Avatar string
}

type Inbound struct {
	Poll    func(ctx context.Context, publish func(Message) error) error
	Webhook func(publish func(Message) error) http.Handler
}

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

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

type LocalProviderOption func(*LocalProvider)

type Message struct {
	// EventID is platform-unique and stable across redelivery; it is the
	// dedupe key for the turn ledger.
	EventID string `json:"eventId"`

	Tenant   string `json:"tenant,omitempty"`
	Platform string `json:"platform"`
	Account  string `json:"account"`
	ChatID   string `json:"chatId"`
	ThreadID string `json:"threadId,omitempty"`

	// ChatType classifies the conversation: "dm" (one-to-one), "group"
	// (multi-party), or "channel" (broadcast). Group messages carry sender
	// attribution in the prompt.
	ChatType string `json:"chatType,omitempty"`

	SenderID   string `json:"senderId,omitempty"`
	SenderName string `json:"senderName,omitempty"`

	Text        string          `json:"text,omitempty"`
	ReplyToID   string          `json:"replyToId,omitempty"`
	Attachments []AttachmentRef `json:"attachments,omitempty"`
	SentAt      time.Time       `json:"sentAt,omitzero"`
}

type Open func(ctx context.Context, key ConversationKey, manager *sessionstore.SessionManager) (session *agent.AgentSession, close func(), err error)

type Options struct {
	// Sessions provides exclusive conversation ownership. Required.
	Sessions SessionProvider
	// Adapters lists one adapter per platform. Required, unique platforms.
	Adapters []Adapter
	// Authorize gates every inbound message. Required; pass [AllowAll] to
	// opt out explicitly.
	Authorize func(Message) error
	// MaxConcurrent bounds concurrent turns globally. Default 64.
	MaxConcurrent int
	// PreviewInterval is the preview edit cadence. Default 1s.
	PreviewInterval time.Duration
	// TurnTimeout guards each turn's context. Default 10m.
	TurnTimeout time.Duration
	// Logger receives non-fatal diagnostics. Optional.
	Logger *slog.Logger
}

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

type Receipt struct {
	MessageIDs []string  `json:"messageIds"`
	At         time.Time `json:"at"`
}

type SessionProvider interface {
	Acquire(ctx context.Context, key ConversationKey) (*Conversation, error)
}

type Spool interface {
	Pending(context.Context) ([]Message, error)
	Put(context.Context, Message) error
	Ack(context.Context, string) error
}