command

type AccessEvaluator ¶

type AccessEvaluator interface {
	Evaluate(ctx context.Context, req acl.EvaluateRequest) (bool, error)
}

AccessEvaluator checks whether the current channel context may trigger chat.

type BotMemberRoleAdapter ¶

type BotMemberRoleAdapter struct {
	BotService     *bots.Service
	ManageResolver ChannelManageResolver
}

BotMemberRoleAdapter adapts bots.Service to MemberRoleResolver.

func (a *BotMemberRoleAdapter) GetMemberRole(ctx context.Context, botID, channelIdentityID string) (string, error)

type ChannelManageResolver ¶

type ChannelManageResolver interface {
	HasManageGrant(ctx context.Context, botID, channelIdentityID string) (bool, error)
}

ChannelManageResolver reports whether a channel identity has been granted the manage capability on a bot (Channel Access "Manage"). It lets an IM identity run owner-only slash commands without being the web owner.

type ChoicesView ¶

type ChoicesView struct {
	Title                 string
	Choices               []ListItem
	Columns               int // optional keyboard columns; 0 lets renderers pick
	BodyEnumeratesChoices bool
}

ChoicesView is a flat set of selectable choices (no pagination).

BodyEnumeratesChoices asserts that the body Text already enumerates every typeable affordance (e.g. /help <group>'s Usage block lists every sub-command verbatim), so the no-button fallback trailer should skip this surface to avoid duplicating what the body already says.

This is a bool (not a HintVerb sentinel like ListView's HintVerb) because the question being answered is different: ChoicesView picks WHETHER to emit a trailer at all, ListView picks WHICH verb to use. See ListView.HintVerb.

type CommandContext ¶

type CommandContext struct {
	Ctx               context.Context
	BotID             string
	Role              string // "owner", "admin", "member", or "" (guest)
	WriteAccess       bool
	Args              []string
	ChannelIdentityID string
	UserID            string
	ChannelType       string
	ConversationType  string
	ConversationID    string
	ThreadID          string
	RouteID           string
	SessionID         string
	Page              int    // zero-based page offset for paginated list commands
	Prov              int    // provider index for the model picker (-1 if absent)
	SelectID          string // stable model id for picker selection ("" if absent)
	Range             string // time-window key for time-series commands ("" = default)
	Locale            string // resolved command-UI locale ("en", "zh", …)
	L                 *i18n.Localizer
}

CommandContext carries execution context for a sub-command.

func (cc CommandContext) T(key string, params ...map[string]any) string

type CommandGroup ¶

type CommandGroup struct {
	Name          string
	Description   string
	DefaultAction string
	// contains filtered or unexported fields
}

CommandGroup groups sub-commands under a resource name.

func (g *CommandGroup) ActionHelp(action string, localizers ...*i18n.Localizer) string

func (g *CommandGroup) Register(sub SubCommand)

func (g *CommandGroup) Usage(localizers ...*i18n.Localizer) string

type CommandQueries ¶

type CommandQueries interface {
	GetLatestSessionIDByBot(ctx context.Context, botID pgtype.UUID) (pgtype.UUID, error)
	CountMessagesBySession(ctx context.Context, sessionID pgtype.UUID) (int64, error)
	GetLatestAssistantUsage(ctx context.Context, sessionID pgtype.UUID) (int64, error)
	GetSessionCacheStats(ctx context.Context, sessionID pgtype.UUID) (dbsqlc.GetSessionCacheStatsRow, error)
	GetSessionUsedSkills(ctx context.Context, sessionID pgtype.UUID) ([]string, error)
	GetTokenUsageByDayAndType(ctx context.Context, arg dbsqlc.GetTokenUsageByDayAndTypeParams) ([]dbsqlc.GetTokenUsageByDayAndTypeRow, error)
	GetTokenUsageByModel(ctx context.Context, arg dbsqlc.GetTokenUsageByModelParams) ([]dbsqlc.GetTokenUsageByModelRow, error)
	// UpdateSessionModelPreference is the /model and /reasoning clear path
	// (issue #879, spec P11′): called with NULL fields to drop a web-pinned
	// pair so the session returns to the bot-default chain.
	UpdateSessionModelPreference(ctx context.Context, arg dbsqlc.UpdateSessionModelPreferenceParams) error
}

CommandQueries captures the sqlc methods used by slash commands. dbstore.Queries satisfies this interface directly.

type ContainerFS ¶

type ContainerFS interface {
	ListDir(ctx context.Context, botID, path string) ([]FSEntry, error)
	ReadFile(ctx context.Context, botID, path string) (string, error)
}

ContainerFS provides read-only access to a bot's container filesystem.

type CurrentContext ¶

type CurrentContext struct {
	ChatModel string
	// ReasoningEffort carries models.ReasoningEffortDisable when reasoning is off.
	ReasoningEffort string
	ContextWindow   string // resolved chat-model context window (e.g. "128.0K"), "" if unknown
}

CurrentContext is the resolved current-state summary used to enrich /new and bare /model output. All fields are display-ready strings.

type ExecuteInput ¶

type ExecuteInput struct {
	BotID             string
	ChannelIdentityID string
	UserID            string
	Text              string
	// Invocation is the canonical channel parse. When present, command handling
	// must use it instead of interpreting Text again.
	Invocation       *Invocation
	ChannelType      string
	ConversationType string
	ConversationID   string
	ThreadID         string
	RouteID          string
	SessionID        string
	// CommandTarget optionally identifies the bot username for transport-specific
	// command guidance. Channel callers set it only for Telegram group messages.
	CommandTarget string
	// Locale optionally pins the command-UI locale. When empty, ExecuteResult
	// resolves it from the bot's command_ui_language setting (auto → en).
	Locale string
}

ExecuteInput carries the caller identity and channel context for command execution.

type FSEntry ¶

type FSEntry struct {
	Name  string
	IsDir bool
	Size  int64
}

FSEntry represents a file or directory in a container filesystem.

type Handler ¶

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

Handler processes slash commands intercepted before they reach the LLM.

func NewHandler(
	log *slog.Logger,
	roleResolver MemberRoleResolver,
	scheduleService *schedule.Service,
	settingsService *settings.Service,
	mcpConnService *mcp.ConnectionService,
	modelsService *models.Service,
	providersService *providers.Service,
	memProvService *memprovider.Service,
	searchProvService *searchproviders.Service,
	emailService *emailpkg.Service,
	emailOutboxService *emailpkg.OutboxService,
	queries CommandQueries,
	aclEvaluator AccessEvaluator,
	skillLoader SkillLoader,
	containerFS ContainerFS,
) *Handler

func (h *Handler) CommandAccess(ctx context.Context, input ExecuteInput) (bool, error)

func (h *Handler) CurrentContext(ctx context.Context, botID string) (CurrentContext, error)

func (h *Handler) Execute(ctx context.Context, botID, channelIdentityID, text string) (string, error)

func (h *Handler) ExecuteResult(ctx context.Context, input ExecuteInput) (res *Result, err error)

func (h *Handler) ExecuteWithInput(ctx context.Context, input ExecuteInput) (string, error)

func (h *Handler) HasCommandResource(resource string) bool

func (h *Handler) IsCommand(text string) bool

func (*Handler) IsCommandShaped(text string) bool

func (h *Handler) MemberRole(ctx context.Context, botID, channelIdentityID string) (string, error)

func (h *Handler) ResolveLocale(ctx context.Context, botID string) string

func (h *Handler) SetCompactionService(s *compaction.Service, q dbstore.Queries)

func (h *Handler) SetLinkConsumer(c LinkConsumer)

type HintVerb ¶

type HintVerb string

HintVerb names the shape of a typeable affordance when rendering the no-button fallback trailer. Setting ListView.HintVerb to one of these overrides the automatic inference in FallbackTrailer.

The values double as the suffix of the i18n key (cmd.fallback.<verb>) so adding a verb is a two-step change: register the constant here and add the matching localized template in locales/*.json.

const (
	HintVerbSwitch  HintVerb = "switch"
	HintVerbPick    HintVerb = "pick"
	HintVerbToggle  HintVerb = "toggle"
	HintVerbOpen    HintVerb = "open"
	HintVerbDetails HintVerb = "details"
	HintVerbRange   HintVerb = "range"
	HintVerbMenu    HintVerb = "menu"
)

type Interactive ¶

type Interactive struct {
	Kind    InteractiveKind
	List    *ListView
	Picker  *ModelPickerView
	Choices *ChoicesView
	Range   *RangeView
}

Interactive carries optional structured data for rich rendering. Exactly one of the typed views is set, selected by Kind.

type InteractiveKind ¶

type InteractiveKind string

InteractiveKind discriminates the structured payload carried by a Result.

const (
	// InteractiveList is a generic, paginated list of display rows.
	InteractiveList InteractiveKind = "list"
	// InteractiveModelPicker is the two-level provider→model drill-down picker.
	InteractiveModelPicker InteractiveKind = "model_picker"
	// InteractiveChoices is a flat one-shot set of selectable choices.
	InteractiveChoices InteractiveKind = "choices"
	// InteractiveRange is a time-window selector for time-series commands.
	InteractiveRange InteractiveKind = "range"
)

type Invocation ¶

type Invocation = commandsyntax.Invocation

ParsedCommand remains an alias so command handlers and callers can migrate to the shared syntax package without duplicating the parser implementation.

func ParseInvocation(input InvocationInput) (Invocation, error)

type InvocationInput ¶

type InvocationInput = commandsyntax.InvocationInput

ParsedCommand remains an alias so command handlers and callers can migrate to the shared syntax package without duplicating the parser implementation.

type ItemAction ¶

type ItemAction struct {
	Resource string
	Action   string
	Args     []string
}

ItemAction triggers a command when a row is tapped.

func (a *ItemAction) Typeable() string

type LinkConsumer ¶

type LinkConsumer interface {
	ConsumeLinkCode(ctx context.Context, token, channelIdentityID string) (channelaccess.Binding, error)
}

LinkConsumer binds the calling channel identity to the web user that owns a one-time link code. It is satisfied by channelaccess.Service.

type ListItem ¶

type ListItem struct {
	Label    string
	Detail   string
	Selected bool
	Action   *ItemAction
	Callback string
}

ListItem is one row in a ListView. Action is nil for display-only rows.

Callback optionally carries pre-encoded callback_data for button-capable renderers; when set it takes precedence over Action as the button value. Rows with only Callback stay out of the no-button fallback trailer (which derives typeable hints from Action), so such callers must carry the typeable form in the body text instead.

type ListView ¶

type ListView struct {
	Title        string
	ButtonText   string   // optional compact text for button-capable channels
	Resource     string   // command resource (e.g. "mcp"), round-trips in callback data
	Action       string   // command action (e.g. "list")
	Args         []string // narrowing args (e.g. a provider filter) that round-trip
	Items        []ListItem
	Total        int        // total items across all pages
	Page         int        // zero-based page index of this view
	PageSize     int        // items per page
	ExtraActions []ListItem // contextual action buttons below the list rows (e.g. "All commands")
	HintVerb     HintVerb   // optional fallback-trailer verb override (HintVerb*)
}

ListView is a generic paginated list. It is re-derivable by re-running the originating command with a page offset, so Resource/Action/Args round-trip through the callback data of pagination buttons.

HintVerb is an optional explicit verb (one of HintVerb*) for trailer derivation on no-button channels — used when rows are display-only but the list has a paired typeable affordance (e.g. /mcp list rows are display-only but /mcp get <name> is the typeable next step). Empty = infer from structure.

Note the asymmetry with ChoicesView.BodyEnumeratesChoices: ListView needs to pick WHICH verb to emit, ChoicesView only needs to choose WHETHER to emit. Different questions, different mechanisms — kept that way rather than forcing them into one shape that fits neither cleanly.

type MemberRoleResolver ¶

type MemberRoleResolver interface {
	GetMemberRole(ctx context.Context, botID, channelIdentityID string) (string, error)
}

MemberRoleResolver resolves a user's role within a bot.

type MenuCommand ¶

type MenuCommand struct {
	Command     string // command name without the leading slash, lowercase
	Description string // short label shown beside the command in the menu
}

MenuCommand is one entry for a channel's native slash-command menu (e.g. Telegram's setMyCommands), so users discover and tap commands without typing.

func MenuCommands(t *i18n.Localizer) []MenuCommand

type ModelPickerView ¶

type ModelPickerView struct {
	Level            PickerLevel
	Providers        []PickerProvider // populated at the provider level
	Models           []PickerModel    // populated at the model level
	ProviderIndex    int              // which provider we drilled into (model level)
	ProviderName     string           // name of that provider (model level), for the header
	Page             int
	PageSize         int
	Total            int
	CurrentModelDBID string // settings.ChatModelID, for ●/✓ marking
	CurrentDisplay   string // resolved current chat model "Name (Provider)", for the header
	Reasoning        string // current reasoning effort label, for the header
}

ModelPickerView is the two-level model picker (populated in the model-picker phase). Level selects whether Providers or Models is rendered.

type ParsedCallback ¶

type ParsedCallback struct {
	Kind          string
	Resource      string
	Action        string
	Args          []string
	Page          int
	ProviderIndex int
	SelectID      string
	Range         string
}

ParsedCallback is the decoded form of an interactive callback_data string.

func DecodeCallback(data string) (ParsedCallback, bool)

func (p ParsedCallback) IsDismiss() bool

func (p ParsedCallback) IsNoop() bool

func (p ParsedCallback) IsSkillActivation() bool

func (p ParsedCallback) SyntheticCommand() string

type ParsedCommand ¶

type ParsedCommand = commandsyntax.ParsedCommand

ParsedCommand remains an alias so command handlers and callers can migrate to the shared syntax package without duplicating the parser implementation.

func Parse(text string) (ParsedCommand, error)

type PickerLevel ¶

type PickerLevel string

PickerLevel is the drill-down level of a ModelPickerView.

const (
	// LevelProviders renders the provider grid.
	LevelProviders PickerLevel = "providers"
	// LevelModels renders the paginated model list for one provider.
	LevelModels PickerLevel = "models"
)

type PickerModel ¶

type PickerModel struct {
	DBID     string
	Name     string
	Provider string
	Selected bool
}

PickerModel is one model button in the picker. Selected marks the active model (rendered with ✓). DBID is the model's stable id, carried in the selection callback so a list change between render and tap can't resolve the tap to a different model.

type PickerProvider ¶

type PickerProvider struct {
	Index      int
	Name       string
	Count      int
	HasCurrent bool
}

PickerProvider is one provider button in the picker. HasCurrent marks the provider that holds the currently-selected model (rendered with ●). Count is the number of chat models the provider offers.

type RangeView ¶

type RangeView struct {
	Resource string
	Action   string
	Current  string   // the active preset key (normalized), for the ● marker
	Presets  []string // ordered preset keys, e.g. ["24h","7d","30d","all"]
}

RangeView is a time-window selector for a time-series command. Selecting a preset re-runs "/{Resource} {Action} --range <preset>" in place.

type Registry ¶

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

Registry holds all registered command groups.

func (r *Registry) ActionHelp(groupName, action string, localizers ...*i18n.Localizer) string

func (r *Registry) GlobalHelp(t *i18n.Localizer, commandTarget string) string

func (r *Registry) GroupHelp(name string, localizers ...*i18n.Localizer) string

func (r *Registry) GroupHelpResult(name string, localizers ...*i18n.Localizer) *Result

func (r *Registry) RegisterGroup(group *CommandGroup)

type Result ¶

type Result struct {
	Text          string
	Interactive   *Interactive
	Locale        string
	FeedbackError *agentfeedback.Error
}

Result is the neutral, platform-independent output of a command.

Text is always a complete rendering usable by channels without rich UI. Interactive is optional structured data that capable renderers (e.g. the Telegram inline keyboard) may upgrade into buttons and pagination.

Locale is the resolved command-UI locale ("en", "zh", …) the Text/Interactive labels were rendered in. Channels use it to localize their own renderer chrome (Close/Prev/Next/…) so the whole reply stays in one language. Empty means the server default (English).

func WithButtons(r *Result, buttons ...ListItem) *Result

func WithExtraActions(r *Result, extras ...ListItem) *Result

type RuntimeSkillLister ¶

type RuntimeSkillLister interface {
	ListRuntimeSkills(ctx context.Context, botID string) ([]Skill, error)
}

RuntimeSkillLister lists the bot's runtime-usable skills — the same safe catalog the Web slash picker shows (unique, enabled, loadable as model context). Optional capability of SkillLoader implementations: when present, /skill list renders these entries with tap-to-activate buttons instead of the raw full listing, so IM and Web expose one identical skill surface.

type Skill ¶

type Skill struct {
	Name        string
	Description string
}

Skill represents a single skill loaded from a bot's container.

type SkillLoader ¶

type SkillLoader interface {
	LoadSkills(ctx context.Context, botID string) ([]Skill, error)
}

SkillLoader loads skills for a bot.

type SubCommand ¶

type SubCommand struct {
	Name          string
	Usage         string
	IsWrite       bool
	Handler       func(cc CommandContext) (string, error)
	ResultHandler func(cc CommandContext) (*Result, error)
}

SubCommand describes a single sub-command within a resource group.

A sub-command provides either Handler (plain text) or ResultHandler (structured Result for rich rendering). When both are set, ResultHandler takes precedence.