gateway

type AgentSender interface {
	Stream(ctx context.Context, in string) (<-chan agent.StreamEvent, error)
	SetSessionID(id string)
	SessionID() string
	EStop()
	// Interrupt cancels the currently running stream for this agent.
	// Safe to call from any goroutine. No-op if no stream is running.
	Interrupt()
	// SetQuestionFunc wires the clarify callback so the agent can ask
	// the user questions mid-execution (§8.6).
	SetQuestionFunc(fn agent.QuestionFunc)
	// Undo removes the last exchange from session history.
	Undo() (string, error)
	// Retry replays the last user message with a fresh model call.
	Retry(ctx context.Context) (string, error)
	// Steer queues a guidance message for mid-run injection into the
	// agent loop. Returns a confirmation string.
	Steer(msg string) string
	// Fork creates a new session branched from the current one with
	// an optional name. Returns the new session ID.
	Fork(name string) (string, error)
	// Snapshot creates a git-based filesystem checkpoint with the
	// given name. Returns the new commit hash.
	Snapshot(name string) (string, error)
	// Rollback rolls back to the Nth most recent checkpoint
	// (0 = latest). Returns a human-readable summary.
	Rollback(n int) (string, error)
	// Snapshots returns a human-readable listing of saved checkpoints.
	Snapshots() (string, error)
	// SetGoal sets or updates the standing goal for the current session.
	SetGoal(ctx context.Context, text string) error
	// GetGoal returns the current goal text (empty string if none set).
	GetGoal(ctx context.Context) (string, error)
	// PauseGoal pauses the current goal (keeps it but stops injecting).
	PauseGoal(ctx context.Context) error
	// ResumeGoal resumes a paused goal so it injects again.
	ResumeGoal(ctx context.Context) error
	// ClearGoal removes the goal entirely.
	ClearGoal(ctx context.Context) error
	// Compact triggers context compaction on the current session.
	// Returns the compaction result with before/after token counts and a summary.
	Compact(ctx context.Context) (*agent.CompactResult, error)
	// ExportHistory writes the current session's message history to a
	// markdown file at the given path and returns the path.
	ExportHistory(path string) (string, error)
	// SetThinkingLevel sets the extended thinking budget.
	SetThinkingLevel(level string)
	// ThinkingLevel returns the current thinking level.
	ThinkingLevel() string
	// Mode returns the current plan/build mode ("plan" or "build").
	// Plan mode means analysis-only; build mode allows execution.
	Mode() string
	// IsBusy returns true when the agent loop is actively executing Run().
	// Used by harness to guard commands that would interrupt a running agent.
	IsBusy() bool
}

type Bookmark struct {
	ID        int       `json:"id"`
	SessionID string    `json:"session_id"`
	Label     string    `json:"label"`
	CreatedAt time.Time `json:"created_at"`
}

type BookmarkFn func(ctx context.Context, sessionID, label string) error

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

type Channel interface {
	Name() string
	Run(ctx context.Context) error
}

type Dispatcher struct {
	// RejectBusy disables detached per-session queues for server-owned bridges.
	RejectBusy bool
	Agent      AgentSender
	Router     *SessionRouter
	Vision     vision.Describer // optional; when set, attached images are
	// captioned and inlined into the agent prompt
	Logger      *log.Logger
	UpdateEvery time.Duration // batch reply edits; default 750ms

	// MaxTextLen caps text per inbound message. 0 means use default (100000).
	MaxTextLen int
	// MaxImageBytes caps total image bytes per message. 0 means use default (20000000).
	MaxImageBytes int
	// MaxReqsPerMinute is the rate limit per sender per minute. 0 means use default (10).
	MaxReqsPerMinute int

	// Bookmark, when set, handles the /bm <label> slash command from
	// any gateway. Nil leaves the command unwired; users see a
	// helpful error rather than a silent no-op.
	Bookmark BookmarkFn

	// SessionTitler, when set, is called once per session when the
	// first user message arrives, so the session Title is auto-set.
	// Nil disables auto-titling. Called synchronously before the
	// agent turn — should be fast (fire-and-forget is fine).
	SessionTitler func(sessionID, firstMsg string)

	// Pairing, when set, gates inbound messages from unknown senders.
	// Unapproved senders receive a challenge code; their messages are
	// not processed or persisted until the owner approves them.
	Pairing PairingGate

	// InputHistory, when set, records incoming messages to PostgreSQL
	// for context-aware reply history. Recording happens only after
	// the pairing gate passes — unapproved messages are never stored.
	InputHistory InputHistoryStore

	// MsgDelivery, when set, tracks message delivery status in Postgres.
	// Messages are recorded as 'pending' before the provider call.
	// On provider failure they're marked 'failed' — on the next Handle()
	// call for the same session, failed messages are auto-retried first.
	// On success they're marked 'delivered'. No message is ever lost.
	MsgDelivery *MessageDelivery

	// OnActivity, when set, is called every time a non-command user
	// message is accepted for processing (after rate-limit and pairing
	// gates). Cron systems wire their ActivityTracker.Record here so
	// cron output delivery can defer until the user is idle.
	OnActivity func()

	// CostTracker, when set, powers the /usage slash command and the
	// session.usage RPC endpoint. Nil disables usage tracking from
	// gateways (the command returns a helpful error message).
	CostTracker cost.Tracker
	// contains filtered or unexported fields
}

type GatewayLimitsCfg struct {
	MaxTextLen      int
	MaxImageBytes   int
	RateLimitPerMin int
	UpdateEveryMs   int
}

type HealthChecker interface {
	Healthy() bool
}

type Hub struct {
	Channels []Channel
	Logger   *log.Logger
	// BackoffInitial is the initial backoff duration for channel
	// restart attempts. Zero falls back to 1s.
	BackoffInitial time.Duration
	// BackoffMax is the maximum backoff cap for channel restart
	// attempts. Zero falls back to 30s.
	BackoffMax time.Duration
	// contains filtered or unexported fields
}

type Inbound struct {
	Channel  string // "telegram", "discord", "whatsapp", "bridge:<name>"
	ChatKey  string
	Thread   string
	From     string // display name or user id, for logging only
	Text     string
	Images   []InboundImage // attached photos; describer turns into prose
	IsDirect bool           // DM/private chat vs group
}

type InboundImage struct {
	Bytes []byte
	Mime  string
}

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

type InputHistoryStore interface {
	Append(ctx context.Context, chatKey, text string) error
}

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

type Notifier interface {
	Notify(ctx context.Context, target string, text string) error
}

type PairingGate interface {
	IsApproved(channel, senderID string) bool
	IssueChallenge(channel, senderID string) (string, error)
}

type RecentEntry struct {
	SessionID string
	Channel   string
	ChatKey   string
	Thread    string
	Updated   time.Time
	// contains filtered or unexported fields
}

type Reconnecter interface {
	Reconnect(ctx context.Context) error
}

type Reply interface {
	PostInitial(ctx context.Context, in Inbound, text string) (handle string, err error)
	Update(ctx context.Context, handle, text string) error
	Final(ctx context.Context, handle, text string) error
	Error(ctx context.Context, handle string, err error) error
	// StartTyping begins the native typing indicator if the channel supports it.
	// Returns a stop function that clears the indicator. Channels without
	// native typing support return a no-op stop function.
	StartTyping() (stop func())
}

type SessionAgentProvider interface {
	AgentForSession(context.Context, string) (AgentSender, error)
}

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

type SessionStopper interface {
	InterruptSession() error
	EmergencyStop() error
}

type UndeliveredMessage struct {
	ID        int64
	SessionID string
	Message   string
	ErrorMsg  string
	CreatedAt time.Time
}