adapter.go RawHistoryFolder

1// Package bot provides a protocol-agnostic runner for long-running bot
2// modes.  Concrete transports (Telegram, Discord, …) implement the
3// BotAdapter interface; the Runner handles turn queueing, agent
4// prompting, command dispatch, and credential refresh.
5package bot
6
7import (
8	"context"
9
10	"github.com/patriceckhart/zot/packages/provider"
11)
12
13// InboundMessage is a protocol-normalised message from a user.
14type InboundMessage struct {
15	ChannelID string // opaque; adapter owns encoding (e.g. fmt.Sprintf("%d", chatID))
16	MessageID string // optional reply anchor
17	Text      string
18	Images    []provider.ImageBlock
19}
20
21// Command is a built-in bot command that bypasses the agent.
22type Command int
23
24const (
25	CmdStart  Command = iota // first-time pairing / welcome
26	CmdHelp                  // usage information
27	CmdStatus                // agent/provider state
28	CmdStop                  // cancel the active turn
29)
30
31// SendOptions carries protocol-agnostic delivery hints for outbound messages.
32type SendOptions struct {
33	// ReplyToMessageID is an optional adapter-owned message identifier to anchor replies.
34	ReplyToMessageID string
35}
36
37// BotAdapter is the transport layer a concrete protocol must implement.
38// The Runner calls these methods; it never touches protocol types directly.
39type BotAdapter interface {
40	// Run drives inbound polling; calls handler for normal messages and
41	// commandHandler for built-in commands.  Blocks until ctx is done.
42	Run(ctx context.Context,
43		handler func(InboundMessage),
44		commandHandler func(Command, InboundMessage),
45	) error
46
47	// Send delivers a reply.  The adapter chunks to protocol limits.
48	Send(ctx context.Context, channelID, text string, opts SendOptions) error
49
50	// IndicateWorking fires a "typing…" signal; returns a stop func.
51	// Return a no-op if the protocol doesn't support it.
52	IndicateWorking(ctx context.Context, channelID string) (stop func())
53
54	// StatusText appends protocol-specific info to /status replies
55	// (e.g. "@botname").  Return "" if there is nothing to add.
56	StatusText() string
57}