gateway

type Adapter ¶

type Adapter interface {
	Name() string
	Start(ctx context.Context, inbound chan<- InboundMessage) error
	Send(ctx context.Context, msg OutboundMessage) error
}

Adapter is a platform integration. Implementations must be safe to Start once; Start blocks until ctx is canceled, pushing received messages to inbound. Send delivers a reply. Name identifies the platform.

func BuildConfigured() ([]Adapter, error)

type AgentFunc ¶

type AgentFunc func(ctx context.Context, session string, text string) (string, error)

AgentFunc turns an inbound user message into a final reply. It receives the session key so the implementation can keep per-conversation context. To stream progress while it works, it can pull a throttled emitter from ctx via Progress(ctx) and call it zero or more times; the returned string is the final reply delivered after the work finishes. Implementations must be safe for concurrent calls across sessions.

The full InboundMessage (Platform/UserID, for cross-channel identity) is carried on ctx — use InboundFromContext(ctx) to recover it.

type DiscordAdapter ¶

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

DiscordAdapter implements a real Discord Gateway (v10) client over WebSocket for receiving messages, plus the REST API for sending. It handles the HELLO/heartbeat(+ACK)/IDENTIFY lifecycle and reconnects on failure.

func NewDiscordAdapter(token string, logger *zap.Logger) *DiscordAdapter

func (d *DiscordAdapter) Name() string

func (d *DiscordAdapter) Send(ctx context.Context, msg OutboundMessage) error

func (d *DiscordAdapter) SetLogger(l *zap.Logger)

func (d *DiscordAdapter) Start(ctx context.Context, inbound chan<- InboundMessage) error

type InboundAudio ¶ added in v1.129.0

type InboundAudio struct {
	Data     []byte // the raw audio, populated by the adapter after download
	MimeType string // e.g. "audio/ogg" — best-effort, may be empty
	FileName string // best-effort original name, may be empty
	// contains filtered or unexported fields
}

InboundAudio is a voice/audio attachment on an inbound message.

type InboundImage ¶ added in v1.143.0

type InboundImage struct {
	Data     []byte // the raw image, populated by the adapter after download
	MimeType string // e.g. "image/jpeg" — best-effort, may be empty
	FileName string // best-effort original name, may be empty
	// contains filtered or unexported fields
}

InboundImage is a photo/image attachment on an inbound message. It mirrors InboundAudio's two-phase (parse metadata → hydrate bytes) lifecycle.

type InboundMessage ¶

type InboundMessage struct {
	Platform string // "telegram", "discord", ...
	ChatID   string // platform-specific conversation id
	UserID   string // platform-specific sender id
	UserName string // display name, best-effort
	Text     string // message body (may be empty for a voice-only message)

	// Audio carries a voice/audio attachment when the message has one. The
	// pure parser fills its metadata (and the unexported download handle); the
	// owning adapter then downloads the bytes into Data before dispatch.
	// Consumers read Data/MimeType/FileName only.
	Audio *InboundAudio

	// Image carries a photo/image attachment when the message has one. Same
	// two-phase lifecycle as Audio: the parser fills metadata + download
	// handle, the adapter hydrates Data, consumers read Data/MimeType/FileName.
	// Fed to vision-capable models (or the describe-fallback) by the agent func.
	// A single pointer (not a slice) keeps InboundMessage comparable; adapters
	// carry the primary attachment.
	Image *InboundImage
}

InboundMessage is a normalized message received from any platform.

func InboundFromContext(ctx context.Context) (InboundMessage, bool)

func (m InboundMessage) SessionKey() string

type LoggerAware ¶

type LoggerAware interface {
	SetLogger(*zap.Logger)
}

LoggerAware lets the daemon inject its real logger into an adapter that a registry builder created with a no-op logger (builders run at import time, before the daemon's logger exists). Implementations should also route their HTTP client through newLoggingClient so external requests are traced.

type OutboundAudio ¶ added in v1.130.0

type OutboundAudio struct {
	Data     []byte
	Mime     string // e.g. "audio/ogg", "audio/mpeg"
	FileName string // e.g. "reply.ogg"
}

OutboundAudio is a synthesized voice reply to deliver alongside/instead of text on adapters that support it.

type OutboundImage ¶ added in v1.143.0

type OutboundImage struct {
	Data     []byte
	Mime     string // e.g. "image/png"
	FileName string // e.g. "reply.png"
}

OutboundImage is an image reply (generated/edited) to deliver alongside or instead of text on adapters that support sending photos.

type OutboundMessage ¶

type OutboundMessage struct {
	ChatID string
	Text   string
	Audio  *OutboundAudio
	Image  *OutboundImage
}

OutboundMessage is a reply to deliver back to a conversation. When Audio is set, adapters that support voice replies send the clip (using Text as the caption); adapters that don't simply send Text, so a reply is never lost.

type Runner ¶

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

Runner wires adapters to the agent: it fans inbound messages out to the AgentFunc (bounded concurrency) and delivers replies through the adapter that received them.

func NewRunner(adapters []Adapter, agent AgentFunc, logger *zap.Logger, maxConcurrent int) *Runner

func (r *Runner) Run(ctx context.Context) error

func (r *Runner) SetImageProvider(fn func(ctx context.Context, session string) *OutboundImage)

func (r *Runner) SetThinkingNotice(s string)

func (r *Runner) SetVoiceMode(mode string)

func (r *Runner) SetVoicePrefs(p *VoicePrefs)

func (r *Runner) SetVoiceSynthesizer(fn func(ctx context.Context, text string) *OutboundAudio)

type SlackAdapter ¶

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

SlackAdapter integrates with Slack via the Events API (inbound HTTP) and chat.postMessage (outbound), over plain HTTP — no SDK. Inbound requests are verified with the Slack signing secret (HMAC-SHA256) and a timestamp freshness check, per Slack's security guidance.

func NewSlackAdapter(botToken, signingSecret, addr, path string, logger *zap.Logger) *SlackAdapter

func (s *SlackAdapter) Name() string

func (s *SlackAdapter) Send(ctx context.Context, msg OutboundMessage) error

func (s *SlackAdapter) SetLogger(l *zap.Logger)

func (s *SlackAdapter) Start(ctx context.Context, inbound chan<- InboundMessage) error

type TelegramAdapter ¶

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

TelegramAdapter integrates with Telegram via the plain HTTP Bot API (getUpdates long-polling + sendMessage). No third-party SDK.

func NewTelegramAdapter(token string, allowedUserIDs []string, logger *zap.Logger) *TelegramAdapter

func (t *TelegramAdapter) Name() string

func (t *TelegramAdapter) Send(ctx context.Context, msg OutboundMessage) error

func (t *TelegramAdapter) SendTyping(ctx context.Context, chatID string) error

func (t *TelegramAdapter) SetLogger(l *zap.Logger)

func (t *TelegramAdapter) Start(ctx context.Context, inbound chan<- InboundMessage) error

type TypingAware ¶ added in v1.129.0

type TypingAware interface {
	SendTyping(ctx context.Context, chatID string) error
}

TypingAware is an optional adapter capability: a platform that can show a native "typing…" indicator implements it. The Runner refreshes it while the agent works, so the user sees activity without message clutter.

type VoicePrefs ¶ added in v1.132.0

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

VoicePrefs stores per-session voice reply preferences with JSON persistence.

func NewVoicePrefs(path string) *VoicePrefs

func SharedVoicePrefs() *VoicePrefs

func (v *VoicePrefs) ActiveSession() string

func (v *VoicePrefs) Get(session string) string

func (v *VoicePrefs) Set(session, mode string) error

func (v *VoicePrefs) SetActiveSession(session string)

type WebhookAdapter ¶

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

WebhookAdapter is a generic, platform-agnostic adapter: it runs an HTTP server that accepts inbound messages as JSON and delivers replies by POSTing to a configured callback URL. Any platform or custom integration that can send/receive an HTTP POST can use it — no per-platform code.

Inbound (POST <path>): {"chat_id":"...", "user_id":"...", "text":"..."} Outbound (POST callbackURL): {"chat_id":"...", "text":"..."}

SecOps: an optional shared secret is required in the X-ChatCLI-Secret header and compared in constant time.

func NewWebhookAdapter(addr, path, secret, callbackURL string, logger *zap.Logger) *WebhookAdapter

func (w *WebhookAdapter) Name() string

func (w *WebhookAdapter) Send(ctx context.Context, msg OutboundMessage) error

func (w *WebhookAdapter) SetLogger(l *zap.Logger)

func (w *WebhookAdapter) Start(ctx context.Context, inbound chan<- InboundMessage) error

type WhatsAppAdapter ¶

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

WhatsAppAdapter integrates with the WhatsApp Cloud API: inbound via the Meta webhook (GET verification handshake + POST message events) and outbound via the Graph API messages endpoint. Plain HTTP, no SDK.

func NewWhatsAppAdapter(accessToken, phoneID, verifyToken, addr, path string, logger *zap.Logger) *WhatsAppAdapter

func (a *WhatsAppAdapter) Name() string

func (a *WhatsAppAdapter) Send(ctx context.Context, msg OutboundMessage) error

func (a *WhatsAppAdapter) SetLogger(l *zap.Logger)

func (a *WhatsAppAdapter) Start(ctx context.Context, inbound chan<- InboundMessage) error