channel

type AgentCommander ¶

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

func NewAgentCommander(store config.Store, users auth.UserStore) *AgentCommander

func (ac *AgentCommander) List(ctx context.Context) ([]config.Agent, error)

func (ac *AgentCommander) ListForChat(ctx context.Context, chat ChatContext) ([]config.Agent, error)

func (ac *AgentCommander) Switch(ctx context.Context, user auth.User, chat ChatContext, agentSlug string) error

type Arbiter ¶ added in v0.42.0

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

Arbiter decides which agents should respond to a group message. v1 is purely rule-based (no LLM calls):

• @mentioned agent → always respond (bypass rules)
• no mention → channel default agent responds
• agent-origin messages → never trigger other agents (except explicit @handoff)

func NewArbiter(cfg ArbiterConfig) *Arbiter

func (a *Arbiter) Decide(_ context.Context, groupID string, mentions []pkgchannel.Mention, groupMembers []GroupMember, channelAgentID string, opts ...DecideOptions) ArbiterDecision

type ArbiterConfig ¶ added in v0.42.0

type ArbiterConfig struct {
	// MaxRepliesPerTrigger caps the number of agent replies a single human
	// message can produce. 0 means use the default (1).
	MaxRepliesPerTrigger int

	// DebounceWindow is the minimum time between two dispatch triggers for
	// the same group. Messages arriving within the window are silently skipped.
	// 0 means no debounce.
	DebounceWindow time.Duration
}

ArbiterConfig controls the group arbiter's behavior.

type ArbiterDecision ¶ added in v0.42.0

type ArbiterDecision struct {
	RespondingAgents []string // agent IDs that should respond (in order)
	Debounced        bool     // true = message was suppressed by debounce window
}

ArbiterDecision is the outcome of a Decide call.

type BotIdentityRegistry ¶ added in v0.42.0

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

BotIdentityRegistry is an in-memory map from a bot's platform identity (e.g., Telegram username) to the channel instance that owns that bot. Adapters populate it at startup; the group dispatcher reads it to resolve @-mentions to Stella agents.

func NewBotIdentityRegistry() *BotIdentityRegistry

func (r *BotIdentityRegistry) ChannelIDForBot(platform, platformBotID string) (string, bool)

func (r *BotIdentityRegistry) Register(platform, platformBotID, channelID string)

type ChatContext ¶

type ChatContext struct {
	Platform  string
	ChannelID string
	ChatID    string
	IsGroup   bool
}

type CompleteFunc ¶

type CompleteFunc func(context.Context, ai.Model, ai.Context, ai.CompleteOptions, providers.StreamFunc) (ai.AssistantMessage, error)

type Coordinator ¶

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

func NewCoordinator(
	pm interface {
		agent.ServiceManager
		userInvalidator
	},
	store config.Store,
	listFn func() []pkgchannel.ModelOption,
	switchFn func(provider, model string) error,
	opts ...CoordinatorOption,
) *Coordinator

func (c *Coordinator) EnsurePlatformGroupMember(ctx context.Context, platform, platformGroupID, channelID string) error

func (c *Coordinator) HandleIncoming(ctx context.Context, msg pkgchannel.IncomingMessage, command, args string) (string, bool, *pkgchannel.ChatStream, error)

func (c *Coordinator) ListAgents(ctx context.Context, msg pkgchannel.IncomingMessage) ([]pkgchannel.AgentInfo, string, error)

func (c *Coordinator) ListModels() []pkgchannel.ModelOption

func (c *Coordinator) ProvisionUser(ctx context.Context, req pkgchannel.ProvisionRequest) error

func (c *Coordinator) RegisterBotIdentity(platform, platformBotID, channelID string)

func (c *Coordinator) RegisterGroupPublisher(channelID string, publisher GroupPublisher)

func (c *Coordinator) RemovePlatformGroupMember(ctx context.Context, platform, platformGroupID, channelID string) error

func (c *Coordinator) ResolveUserRoot(ctx context.Context, msg pkgchannel.IncomingMessage) (string, error)

func (c *Coordinator) SetGroupDispatcher(dispatcher *GroupDispatcher)

func (c *Coordinator) SwitchAgent(ctx context.Context, msg pkgchannel.IncomingMessage, agentSlug string) error

func (c *Coordinator) SwitchModel(provider, model string) error

type CoordinatorOption ¶

type CoordinatorOption func(*Coordinator)

CoordinatorOption configures the Coordinator.

func WithArbiter(a *Arbiter) CoordinatorOption

func WithBotRegistry(reg *BotIdentityRegistry) CoordinatorOption

func WithCoordinatorAuth(store channelAuthStore, engine *auth.PolicyEngine, linkCodes *auth.LinkCodeStore) CoordinatorOption

func WithDB(db *sql.DB) CoordinatorOption

func WithEventLog(el *eventlog.Store) CoordinatorOption

func WithGroupDispatcher(dispatcher *GroupDispatcher) CoordinatorOption

func WithGroupMemberLister(lister GroupMemberLister) CoordinatorOption

func WithGroupResolver(gr GroupResolver) CoordinatorOption

func WithIntentClassifier(classifier IntentClassifier) CoordinatorOption

func WithPublisherRegistry(reg *PublisherRegistry) CoordinatorOption

func WithSemanticGroupArbiter(a SemanticGroupArbiter) CoordinatorOption

func WithVaultRecipient(r *age.X25519Recipient) CoordinatorOption

func WithVaultService(svc *vault.Service) CoordinatorOption

type DecideOptions ¶ added in v0.43.0

type DecideOptions struct {
	// AllMembersFallback: when true, if there is no @mention and no
	// channelAgentID, return all group members instead of empty.
	AllMembersFallback bool
	// DisableDebounce skips the in-memory fallback debounce for durable dispatch
	// replays. Mention routing already bypasses debounce.
	DisableDebounce bool
}

DecideOptions controls per-call arbiter behavior.

type FuncGroupMemberLister ¶ added in v0.42.0

type FuncGroupMemberLister func(ctx context.Context, groupID string) ([]GroupMember, error)

FuncGroupMemberLister adapts a function to GroupMemberLister.

func (f FuncGroupMemberLister) ListGroupMembers(ctx context.Context, groupID string) ([]GroupMember, error)

type GroupDispatcher ¶ added in v0.43.0

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

GroupDispatcher materializes durable group response decisions and executes one selected-agent dispatch at a time. Ingest owns facts; this owns work.

func NewGroupDispatcher(db *sql.DB, coord *Coordinator, publishers *PublisherRegistry) *GroupDispatcher

func (d *GroupDispatcher) DispatchSync(ctx context.Context, outbox sqlc.CtxGroupOutbox, publisherOverride GroupPublisher) error

func (d *GroupDispatcher) ExecuteDispatch(ctx context.Context, row sqlc.CtxGroupDispatch, publisherOverride GroupPublisher) error

func (d *GroupDispatcher) ProcessOutbox(ctx context.Context, outbox sqlc.CtxGroupOutbox) error

func (d *GroupDispatcher) Run(ctx context.Context) error

func (d *GroupDispatcher) Wake()

type GroupMember ¶ added in v0.42.0

type GroupMember struct {
	AgentID        string
	ReplyChannelID string
}

GroupMember represents a bot's membership in a group chat.

type GroupMemberLister ¶ added in v0.42.0

type GroupMemberLister interface {
	ListGroupMembers(ctx context.Context, groupID string) ([]GroupMember, error)
}

GroupMemberLister returns the agents that belong to a group.

type GroupOutboxEnvelope ¶ added in v0.43.0

type GroupOutboxEnvelope struct {
	Mentions []pkgchannel.Mention `json:"mentions,omitempty"`
}

GroupOutboxEnvelope stores dispatch metadata that must be decided at ingest time, while the group_id and membership view are available in the append transaction.

func DecodeGroupOutboxEnvelope(raw string) (GroupOutboxEnvelope, error)

type GroupPublishRequest ¶ added in v0.43.0

type GroupPublishRequest struct {
	GroupID          string
	AgentID          string
	AgentName        string
	ReplyChannelID   string
	Platform         string
	PlatformGroupID  string
	PlatformThreadID string
	ReplyTo          string
	Stream           *pkgchannel.ChatStream
}

type GroupPublisher ¶ added in v0.43.0

type GroupPublisher interface {
	Publish(ctx context.Context, req GroupPublishRequest) error
}

GroupPublisher renders and sends an agent response stream to one concrete group egress. It must not resolve sessions, call agents, or write event-log rows; the dispatcher owns those cross-platform concerns. Returning nil means the platform API confirmed delivery for platform publishers, or the stream was fully consumed for Web publishers (client write errors do not make Web publish fail; the event log is the durable delivery channel).

func NoopGroupPublisher() GroupPublisher

type GroupResolver ¶ added in v0.42.0

type GroupResolver interface {
	ResolveGroupID(ctx context.Context, platform, platformGroupID, platformThreadID string) (string, error)
}

GroupResolver resolves the canonical group_id for a physical group identity.

type IndexedAgent ¶

type IndexedAgent struct {
	config.Agent
	GlobalIdx int
}

func IndexAgents(agents []config.Agent) []IndexedAgent

type Intent ¶

type Intent string

const (
	IntentHelp    Intent = "help"
	IntentNew     Intent = "new"
	IntentAbort   Intent = "abort"
	IntentCompact Intent = "compact"
	IntentNone    Intent = "none"
)

type IntentClassifier ¶

type IntentClassifier interface {
	Classify(ctx context.Context, agentID string, content []ai.ContentBlock) Intent
}

type LLMIntentClassifier ¶

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

func NewLLMIntentClassifier(loadSnapshot SnapshotLoader, buildStream StreamFuncBuilder) *LLMIntentClassifier

func (c *LLMIntentClassifier) Classify(ctx context.Context, agentID string, content []ai.ContentBlock) Intent

type LLMSemanticGroupArbiter ¶ added in v0.43.0

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

func NewLLMSemanticGroupArbiter(loadSnapshot SnapshotLoader, buildStream StreamFuncBuilder) *LLMSemanticGroupArbiter

func (a *LLMSemanticGroupArbiter) Decide(ctx context.Context, req SemanticGroupRequest) SemanticGroupDecision

type PublisherRegistry ¶ added in v0.43.0

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

func NewPublisherRegistry() *PublisherRegistry

func (r *PublisherRegistry) Get(channelID string) (GroupPublisher, bool)

func (r *PublisherRegistry) Register(channelID string, publisher GroupPublisher)

type ResolvedChat ¶

type ResolvedChat struct {
	Service    *agent.Service
	User       auth.User
	AgentID    string
	SessionKey string
	Channel    session.Channel
	ChatCtx    ChatContext
	GroupID    string // non-empty for group sessions; used as session scope (D9)
	// CurrentSpeaker is the per-turn group speaker (personalization target only).
	// Canonical source for group personalization; runtime/session scope still
	// flows from GroupID / sessionUserID(), never from User.ID.
	CurrentSpeaker memory.CurrentSpeaker
}

func Resolve(ctx context.Context, sm agent.ServiceManager, store config.Store, authStore channelAuthStore, engine *auth.PolicyEngine, platform, senderID, senderName, chatID string, isGroup bool) (*ResolvedChat, error)

func ResolveWithChannel(ctx context.Context, sm agent.ServiceManager, store config.Store, authStore channelAuthStore, engine *auth.PolicyEngine, groupResolver GroupResolver, platform, channelID, senderID string, senderIDs []string, senderName, chatID, threadID string, isGroup bool) (*ResolvedChat, error)

func (rc *ResolvedChat) Chat(ctx context.Context, message agent.MessageContent) (<-chan agent.Event, string, error)

func (rc *ResolvedChat) CompactSession(ctx context.Context) (string, error)

func (rc *ResolvedChat) ResolveSession(ctx context.Context) (agent.SessionInfo, error)

func (rc *ResolvedChat) UserID() string

type ResolvedIdentity ¶

type ResolvedIdentity struct {
	User auth.User
}

func ResolveUser(ctx context.Context, store channelAuthStore, platform, externalID string) (ResolvedIdentity, error)

func ResolveUserCandidates(ctx context.Context, store channelAuthStore, platform string, externalIDs []string) (ResolvedIdentity, identityMatch, error)

type SemanticGroupArbiter ¶ added in v0.43.0

type SemanticGroupArbiter interface {
	Decide(ctx context.Context, req SemanticGroupRequest) SemanticGroupDecision
}

SemanticGroupArbiter decides which agents (if any) should answer a no-mention group message. A nil decision (ShouldReply=false) means "stay silent" — the only safe fallback for an ambiguous classifier.

type SemanticGroupContextMessage ¶ added in v0.43.0

type SemanticGroupContextMessage struct {
	ActorType string
	ActorID   string
	Content   string
}

SemanticGroupContextMessage is one prior group message, oldest→newest.

type SemanticGroupDecision ¶ added in v0.43.0

type SemanticGroupDecision struct {
	ShouldReply      bool
	RespondingAgents []string
	Reason           string
}

SemanticGroupDecision is the strict outcome. RespondingAgents is always a subset of request member IDs, deduped and capped; empty when ShouldReply.

type SemanticGroupMember ¶ added in v0.43.0

type SemanticGroupMember struct {
	AgentID        string
	Name           string
	Scope          string
	CreatorID      string
	Summary        string // bounded public routing summary
	ReplyChannelID string
}

SemanticGroupMember is one candidate agent for a no-mention group decision. Scope/CreatorID drive routing-agent eligibility (whose model_fast and creds classify the message); they are credential/billing signals, not access checks.

type SemanticGroupRequest ¶ added in v0.43.0

type SemanticGroupRequest struct {
	Message       string
	RecentContext []SemanticGroupContextMessage
	Members       []SemanticGroupMember
	OwnerUserID   string // ctx_group_state.created_by_user_id; "" for platform groups
}

SemanticGroupRequest is everything the arbiter needs to route a no-mention human message. The dispatcher owns DB access and builds this; the arbiter owns model I/O and policy.

type SnapshotLoader ¶

type SnapshotLoader func(context.Context, string) (*config.Snapshot, error)

type StreamFuncBuilder ¶ added in v0.28.0

type StreamFuncBuilder func(context.Context, string, config.ProviderCreds) (providers.StreamFunc, error)