@elizaos/plugin-commands 2.0.3-beta.2 → 2.0.3-beta.3

package/dist/src/connector-bridge.d.ts

@@ -0,0 +1,128 @@
+/**
+ * ConnectorCommandBridge — the one documented contract every communication
+ * connector (Discord, Telegram, …) implements to register and dispatch the
+ * universal slash-command catalog onto its native command surface (#8790).
+ *
+ * The catalog (`getConnectorCommands(surface)`) is connector-neutral; each
+ * connector still has to (a) map those commands onto its own command registry
+ * and (b) run them when invoked. Before this contract, each connector invented
+ * its own register/dispatch shape and — critically — neither gated
+ * `requiresAuth` / `requiresElevated` commands at the connector boundary. This
+ * module pins down a single shape so the two connectors behave consistently and
+ * share one auth-gating decision instead of two divergent copies.
+ *
+ * The bridge is deliberately a thin interface + a few pure helpers, NOT a
+ * framework: connectors keep owning their own message pipelines and reply
+ * mechanics. What they share is:
+ *
+ *   1. the three target kinds and how they route (`agent` / `navigate` /
+ *      `client`),
+ *   2. one auth-gating decision (`gateConnectorCommand`) producing one refusal
+ *      message, and
+ *   3. one place to read a command's auth requirements
+ *      (`resolveConnectorCommandAuth`).
+ *
+ * Auth model: the connector resolves the *sender's* trust level
+ * (`isAuthorized` / `isElevated`) using whatever owner/allowlist mechanism it
+ * already has — the canonical-owner / world-role model in `@elizaos/core`
+ * (`hasRoleAccess`). The bridge does not invent a new auth model; it only
+ * decides whether a given command may run for an already-resolved sender.
+ */
+import type { CommandTarget } from "./types";
+/**
+ * The sender's resolved trust level on a connector surface. The connector fills
+ * this in from its own owner/allowlist resolution before dispatching; the
+ * bridge treats missing/false as "fails closed" (unauthorized).
+ */
+export interface ConnectorSenderAuth {
+    isAuthorized: boolean;
+    isElevated: boolean;
+    /** Optional human label for `/whoami`-style replies. */
+    senderName?: string;
+}
+/** A command's auth requirements, read from its catalog definition. */
+export interface ConnectorCommandAuth {
+    requiresAuth: boolean;
+    requiresElevated: boolean;
+}
+/** The outcome of gating a command for a sender. */
+export type ConnectorGateDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reply: string;
+};
+/**
+ * Resolve a command's auth requirements from the active command registry.
+ * `name` is the connector command name (`ConnectorCommand.name`), which is the
+ * command's `nativeName ?? key`; the registry is keyed by `key`, so the lookup
+ * tries the name as a key directly. Unknown commands are treated as requiring
+ * no special auth (the catalog only emits real commands, and agent-target
+ * commands are auth-gated again inside `runCommand`).
+ *
+ * The lookup is scoped directly by `agentId` so concurrent connector requests
+ * cannot move a shared active-store cursor underneath each other.
+ */
+export declare function resolveConnectorCommandAuth(agentId: string, name: string): ConnectorCommandAuth;
+/**
+ * The single auth-gating decision both connectors share. Given a command's
+ * requirements and the sender's resolved trust level, decide whether the
+ * command may run — and, when it may not, produce the one refusal message
+ * every connector emits. Fails closed: an unresolved sender (`isAuthorized:
+ * false`) is refused for any auth-gated command.
+ */
+export declare function gateConnectorCommand(requirements: ConnectorCommandAuth, sender: ConnectorSenderAuth): ConnectorGateDecision;
+/**
+ * Convenience: resolve a command's requirements and gate it in one call.
+ */
+export declare function gateConnectorCommandByName(agentId: string, name: string, sender: ConnectorSenderAuth): ConnectorGateDecision;
+/**
+ * The contract every connector command bridge implements. `TCommand` is the
+ * connector's native command shape (Discord `SlashCommand`, Telegram
+ * descriptor, …) and `TContext` is its per-invocation context (a Discord
+ * interaction, a Telegraf `Context`, …). Implementations are expected to:
+ *
+ *   - `registerCommands()`     — project `getConnectorCommands(surface)` onto
+ *                                the native command registry (deduping against
+ *                                connector built-ins) and return what was
+ *                                registered.
+ *   - `dispatch(target, ...)`  — run a single command, branching on its target
+ *                                kind, after the sender has been gated. The
+ *                                bridge's auth helpers (`gateConnectorCommand`)
+ *                                are applied before `dispatch` so refused
+ *                                commands never reach it.
+ *
+ * The three target kinds behave consistently across connectors:
+ *
+ *   - `agent`    → run the command. Gate-safe deterministic commands
+ *                  (help/status/models/usage/…) resolve to a local reply via
+ *                  `resolveCommand`; option/lifecycle commands route the
+ *                  reconstructed command text through the connector's message
+ *                  pipeline and surface the agent reply.
+ *   - `navigate` → reply with a description of the in-app destination (a deep
+ *                  link); the connector cannot open the Eliza app itself.
+ *   - `client`   → a GUI/TUI-only behavior with no remote surface; the catalog
+ *                  filters these off connector surfaces, so this is defensive.
+ */
+export interface ConnectorCommandBridge<TCommand, TContext> {
+    /** The catalog surface this bridge serves ("discord" | "telegram"). */
+    readonly surface: string;
+    /**
+     * Project the catalog onto the connector's native command registry and
+     * return the registered native commands. Deduping against connector
+     * built-ins is the implementation's responsibility.
+     */
+    registerCommands(): TCommand[];
+    /**
+     * Resolve the invoking sender's trust level from the connector's own
+     * owner/allowlist mechanism. Fails closed (unauthorized) when identity
+     * cannot be resolved.
+     */
+    resolveSenderAuth(context: TContext): Promise<ConnectorSenderAuth>;
+    /**
+     * Run a single command for an already-gated sender, branching on its target
+     * kind. Returns once the reply has been surfaced on the connector.
+     */
+    dispatch(target: CommandTarget, context: TContext, sender: ConnectorSenderAuth): Promise<void>;
+}
+//# sourceMappingURL=connector-bridge.d.ts.map

package/dist/src/connector-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-bridge.d.ts","sourceRoot":"","sources":["../../src/connector-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACpC,YAAY,EAAE,OAAO,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,MAAM,qBAAqB,GAC9B;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACV,oBAAoB,CAMtB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,YAAY,EAAE,oBAAoB,EAClC,MAAM,EAAE,mBAAmB,GACzB,qBAAqB,CAevB;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,mBAAmB,GACzB,qBAAqB,CAKvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,sBAAsB,CAAC,QAAQ,EAAE,QAAQ;IACzD,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,gBAAgB,IAAI,QAAQ,EAAE,CAAC;IAE/B;;;;OAIG;IACH,iBAAiB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEnE;;;OAGG;IACH,QAAQ,CACP,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,mBAAmB,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC;CACjB"}

package/dist/src/connector-catalog.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Connector-neutral command catalog.
+ *
+ * The text command registry (`registry.ts`) describes the agent's slash
+ * capabilities; `navigation-commands.ts` describes the app's navigation/client
+ * commands. Both are `CommandDefinition`s now, so the catalog treats them
+ * uniformly: it unions them, dedupes (navigation wins name collisions), filters
+ * by surface (`surfaces`) and active view (`views`), and projects onto either:
+ *
+ *   - `ConnectorCommand` — the shape a connector (Discord, Telegram, …) maps
+ *     onto its native command surface (`getConnectorCommands`), or
+ *   - `SerializedCommand` — the wire shape `GET /api/commands` serves the web
+ *     composer / TUI (`getCatalogCommands`), via `serializeCommand`.
+ *
+ * Each command declares a `target` discriminating where it executes (`agent` /
+ * `navigate` / `client`). `ConnectorCommand` options carry a fully-resolved
+ * `choices: string[]` so connectors never evaluate function-valued choices.
+ */
+import type { CommandTarget, SerializedCommand, SerializedCommandSource } from "./types";
+export type { ClientCommandAction, CommandTarget } from "./types";
+export type ConnectorCommandTarget = CommandTarget;
+/** A single argument of a connector command. */
+export interface ConnectorCommandOption {
+    name: string;
+    description: string;
+    required: boolean;
+    /** Resolved choice values; empty when the option is free-form. */
+    choices: string[];
+}
+/** A connector-neutral command ready to map onto a native command surface. */
+export interface ConnectorCommand {
+    name: string;
+    description: string;
+    target: CommandTarget;
+    options: ConnectorCommandOption[];
+    /**
+     * View ids this command is scoped to (#8798): present only while one of these
+     * views is the active surface. Omitted = globally available.
+     */
+    views?: string[];
+}
+/**
+ * Whether a command with the given `views` scoping is visible for the active
+ * view. Global commands (no `views`, or an empty list) are always visible;
+ * view-scoped commands appear only when their view is foreground. (#8798)
+ */
+export declare function commandVisibleForView(views: readonly string[] | undefined, activeViewId: string | null | undefined): boolean;
+/**
+ * Build the connector command catalog for a given surface (Discord, Telegram, …).
+ *
+ * @param surface "gui" | "tui" | "discord" | "telegram".
+ * @param options.activeViewId when set, view-scoped commands (#8798) are
+ *   included only if this is one of their views; global commands always appear.
+ *   When unset, view-scoped commands are filtered out entirely.
+ */
+export declare function getConnectorCommands(surface: string, options?: {
+    activeViewId?: string | null;
+    agentId?: string | null;
+}): ConnectorCommand[];
+/**
+ * Build the wire-safe catalog (`SerializedCommand[]`) served by
+ * `GET /api/commands`. This is the pure projection: surface- and view-filtered
+ * unified definitions, each run through `serializeCommand` so `surfaces`, auth
+ * flags, `category`, `dynamicChoices`, and `icon` all survive intact.
+ */
+export declare function getCatalogCommands(surface: string, options?: {
+    activeViewId?: string | null;
+    agentId?: string | null;
+    source?: SerializedCommandSource;
+}): SerializedCommand[];
+//# sourceMappingURL=connector-catalog.d.ts.map

package/dist/src/connector-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-catalog.d.ts","sourceRoot":"","sources":["../../src/connector-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAGX,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,MAAM,SAAS,CAAC;AAIjB,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC;AAEnD,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AASD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACpC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,OAAO,CAIT;AA0ED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GACrE,gBAAgB,EAAE,CAIpB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACR,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAC5B,GACJ,iBAAiB,EAAE,CAQrB"}

package/dist/src/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Plugin Commands - Chat command system for Eliza agents
+ *
+ * Provides a slash-command system with:
+ * - /help, /status, /commands for information
+ * - /stop, /reset, /compact for session control
+ * - /think, /verbose, /model for options
+ * - /allowlist, /approve for management
+ * - /tts for media
+ * - /bash for tools (elevated)
+ *
+ * INTEGRATION NOTES:
+ * - Commands are registered as Actions with strict validate() that only
+ *   matches slash-prefixed messages (e.g. /help, !stop). This prevents
+ *   conflicts with bootstrap actions (STATUS, IGNORE) and messaging plugins.
+ * - Similes use ONLY slash-command forms (no natural language) so the LLM
+ *   won't accidentally route "I need help" to HELP_COMMAND instead of REPLY.
+ * - The registry is scoped per runtime to prevent cross-agent state leaks.
+ * - The COMMAND_REGISTRY provider includes the command list in the LLM context
+ *   ONLY when the message is a command, reducing prompt noise for normal messages.
+ */
+import { type Plugin, type Provider } from "@elizaos/core";
+import type { CommandContext, CommandDefinition, CommandResult } from "./types";
+export * from "./actions";
+export * from "./connector-bridge";
+export * from "./connector-catalog";
+export * from "./navigation-commands";
+export * from "./parser";
+export * from "./registry";
+export * from "./serialize";
+export * from "./settings-sections";
+export * from "./types";
+/**
+ * Provider that exposes available commands to the LLM context.
+ *
+ * Only injects the full command list when the message looks like a command.
+ * For normal messages, returns a minimal hint so the LLM knows commands
+ * exist but doesn't get a wall of command documentation in its context.
+ */
+export declare const commandRegistryProvider: Provider;
+/**
+ * Format command result for display
+ */
+export declare function formatCommandResult(result: CommandResult): string;
+/**
+ * Check if a sender is authorized
+ */
+export declare function isAuthorized(context: CommandContext, command: CommandDefinition): boolean;
+/**
+ * Check if a sender has elevated permissions
+ */
+export declare function isElevated(context: CommandContext, command: CommandDefinition): boolean;
+/**
+ * Plugin Commands
+ *
+ * Provides chat commands as Eliza actions. Commands are detected
+ * by their text aliases (e.g., /help, /status) and executed as actions.
+ *
+ * Design decisions for messaging integration:
+ * 1. Actions use strict validate() — only true for slash-prefixed messages
+ * 2. Similes are slash-only — no natural language to prevent LLM misrouting
+ * 3. Provider is context-aware — full docs for commands, empty for normal msgs
+ * 4. Registry is scoped per agentId — no cross-agent contamination
+ * 5. Events use proper EventType enums — not raw strings
+ */
+export declare const commandsPlugin: Plugin;
+export default commandsPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAIN,KAAK,MAAM,EACX,KAAK,QAAQ,EAGb,MAAM,eAAe,CAAC;AAevB,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAIhF,cAAc,WAAW,CAAC;AAG1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAE3B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AAEpC,cAAc,SAAS,CAAC;AAExB;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,QA+CrC,CAAC;AAEF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAKjE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC3B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,iBAAiB,GACxB,OAAO,CAKT;AAED;;GAEG;AACH,wBAAgB,UAAU,CACzB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,iBAAiB,GACxB,OAAO,CAKT;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,MAkO5B,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/dist/src/navigation-commands.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Navigation + client commands as first-class `CommandDefinition`s.
+ *
+ * These used to be defined inline in `connector-catalog.ts` as bare
+ * `ConnectorCommand`s, which meant they could not carry `surfaces`, auth flags,
+ * `category`, or flow through `serializeCommand` like agent commands do (#8790).
+ * Defining them as `CommandDefinition`s with an explicit `target` and `surfaces`
+ * lets the catalog treat agent / navigate / client commands uniformly:
+ *
+ *   - `navigate` commands open a destination in the Eliza app; `path` is the
+ *     in-app deep link a connector advertises, `tab`/`viewId`/`section` are the
+ *     routing hints the GUI/TUI use to open it deterministically. Offered on
+ *     every surface (chat connectors reply with the deep link).
+ *   - `client` commands run a GUI/TUI-only behavior with no remote surface, so
+ *     they declare `surfaces: ["gui", "tui"]` and are filtered off chat
+ *     connectors by surface, not by an ad-hoc branch.
+ *
+ * The `path`/`tab` values mirror the canonical route table in `@elizaos/ui`
+ * (`navigation/index.ts` `TAB_PATHS`); keep them in sync there.
+ */
+import type { CommandDefinition } from "./types";
+/**
+ * Navigation + client commands the app surfaces in addition to the agent
+ * capabilities from the text command registry. Returns a fresh array so callers
+ * can't mutate the shared definitions.
+ */
+export declare function navigationCommandDefinitions(): CommandDefinition[];
+//# sourceMappingURL=navigation-commands.d.ts.map

package/dist/src/navigation-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-commands.d.ts","sourceRoot":"","sources":["../../src/navigation-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,SAAS,CAAC;AAmRjE;;;;GAIG;AACH,wBAAgB,4BAA4B,IAAI,iBAAiB,EAAE,CAElE"}

package/dist/src/parser.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Command parser - detects and parses commands from message text
+ */
+import type { CommandDefinition, CommandDetectionResult, ParsedCommand } from "./types";
+/**
+ * Check if text contains a command
+ */
+export declare function hasCommand(text: string): boolean;
+/**
+ * Detect command in text
+ */
+export declare function detectCommand(text: string): CommandDetectionResult;
+/**
+ * Parse a command from text
+ */
+export declare function parseCommand(text: string, definition: CommandDefinition): ParsedCommand | null;
+/**
+ * Normalize command body (handle bot mentions, colon syntax, etc.)
+ */
+export declare function normalizeCommandBody(text: string, botMention?: string): string;
+/**
+ * Check if text is a command-only message (no other content)
+ */
+export declare function isCommandOnly(text: string): boolean;
+/**
+ * Get command and remaining text
+ */
+export declare function extractCommand(text: string): {
+    command: ParsedCommand;
+    remainingText: string;
+} | null;
+//# sourceMappingURL=parser.d.ts.map

package/dist/src/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACX,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,MAAM,SAAS,CAAC;AAKjB;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKhD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB,CAuBlE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC3B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,iBAAiB,GAC3B,aAAa,GAAG,IAAI,CA6CtB;AA+ED;;GAEG;AACH,wBAAgB,oBAAoB,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,GACjB,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAanD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC7B,IAAI,EAAE,MAAM,GACV;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAc1D"}

package/dist/src/registry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Command registry - defines all available chat commands
+ *
+ * IMPORTANT: The registry uses module-level state for convenience, but
+ * provides `cloneCommands()` and `resetCommands()` so that `init()` can
+ * work on isolated copies per runtime. The `init()` function in the main
+ * plugin file should clone before mutating to avoid cross-agent contamination.
+ */
+import type { CommandDefinition } from "./types";
+export declare const DEFAULT_COMMANDS: ReadonlyArray<CommandDefinition>;
+/**
+ * Initialize an isolated command store for a specific runtime.
+ * Called from plugin init() to prevent cross-agent contamination.
+ */
+export declare function initForRuntime(agentId: string): void;
+/**
+ * Set the active command store for a given runtime.
+ * Providers and actions should call this before accessing commands.
+ */
+export declare function useRuntime(agentId: string): void;
+/**
+ * Get all registered commands
+ */
+export declare function getCommands(): CommandDefinition[];
+/**
+ * Get enabled commands
+ */
+export declare function getEnabledCommands(): CommandDefinition[];
+/**
+ * Get commands by category
+ */
+export declare function getCommandsByCategory(category: string): CommandDefinition[];
+/**
+ * Register a custom command
+ */
+export declare function registerCommand(command: CommandDefinition): void;
+/**
+ * Register multiple commands
+ */
+export declare function registerCommands(newCommands: CommandDefinition[]): void;
+/**
+ * Unregister a command
+ */
+export declare function unregisterCommand(key: string): void;
+/**
+ * Reset to default commands (for the active store)
+ */
+export declare function resetCommands(): void;
+/**
+ * Find command by alias
+ */
+export declare function findCommandByAlias(alias: string): CommandDefinition | undefined;
+/**
+ * Find command by key
+ */
+export declare function findCommandByKey(key: string): CommandDefinition | undefined;
+/**
+ * Check if text starts with any command alias
+ */
+export declare function startsWithCommand(text: string): CommandDefinition | undefined;
+export declare function getCommandsForRuntime(agentId?: string | null): CommandDefinition[];
+export declare function getEnabledCommandsForRuntime(agentId?: string | null): CommandDefinition[];
+export declare function getCommandsByCategoryForRuntime(category: string, agentId?: string | null): CommandDefinition[];
+export declare function findCommandByAliasForRuntime(alias: string, agentId?: string | null): CommandDefinition | undefined;
+export declare function findCommandByKeyForRuntime(key: string, agentId?: string | null): CommandDefinition | undefined;
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGjD,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAAC,iBAAiB,CAqT7D,CAAC;AAwBF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAOpD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,EAAE,CAEjD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,iBAAiB,EAAE,CAExD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAI3E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAOhE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAIvE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGnD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAGpC;AAsBD;;GAEG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,MAAM,GACX,iBAAiB,GAAG,SAAS,CAG/B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAE3E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAgB7E;AAuCD,wBAAgB,qBAAqB,CACpC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,iBAAiB,EAAE,CAErB;AAED,wBAAgB,4BAA4B,CAC3C,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,iBAAiB,EAAE,CAErB;AAED,wBAAgB,+BAA+B,CAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,iBAAiB,EAAE,CAErB;AAED,wBAAgB,4BAA4B,CAC3C,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,iBAAiB,GAAG,SAAS,CAI/B;AAED,wBAAgB,0BAA0B,CACzC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,iBAAiB,GAAG,SAAS,CAE/B"}

package/dist/src/serialize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Canonical command serialization.
+ *
+ * `serializeCommand` is the single projection from a `CommandDefinition` onto
+ * the wire-safe `SerializedCommand` shape every client consumes (web composer,
+ * TUI autocomplete, connector bridges). The `GET /api/commands` route is a pure
+ * pass-through of this function — it fabricates nothing. This is what closes the
+ * "catalog contract dropped at the route" gap (#8790): `surfaces`, auth flags,
+ * `category`, real `dynamicChoices`, `icon`, and the full `textAliases` all
+ * survive instead of being hardcoded to `false`/`"both"`/`"builtin"`.
+ */
+import type { CommandDefinition, CommandSurface, SerializedCommand, SerializedCommandSource } from "./types";
+/**
+ * Whether a command is offered on `surface`. A definition with no `surfaces`
+ * is offered everywhere (the default). When `surface` is omitted the command is
+ * always included (the catalog query is surface-agnostic).
+ */
+export declare function commandVisibleForSurface(surfaces: readonly CommandSurface[] | undefined, surface: CommandSurface | null | undefined): boolean;
+/**
+ * Serialize a `CommandDefinition` onto the canonical `SerializedCommand` wire
+ * shape. Every field is read from the definition — nothing is fabricated.
+ *
+ * @param command the registry definition.
+ * @param options.source where the item came from (default `"builtin"`); skills
+ *   pass `"custom-action"`/`"saved"` so the menu can group/label them.
+ */
+export declare function serializeCommand(command: CommandDefinition, options?: {
+    source?: SerializedCommandSource;
+}): SerializedCommand;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/src/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAEX,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EAEjB,uBAAuB,EACvB,MAAM,SAAS,CAAC;AAKjB;;;;GAIG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,EAC/C,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GACxC,OAAO,CAIT;AAmBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,uBAAuB,CAAA;CAAO,GAChD,iBAAiB,CAwBnB"}

package/dist/src/settings-sections.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Settings sections — the canonical destinations the `/settings <section>`
+ * command can open in the Eliza app.
+ *
+ * Each section has a stable `id` (the canonical token connectors advertise and
+ * the app routes on), a human `label`, and optional `aliases` that map common
+ * synonyms onto the canonical id. `resolveSettingsSection` turns any raw token
+ * (id or alias) into its canonical id.
+ */
+export interface SettingsSection {
+    /** Canonical, stable section id used for routing and as the choice token. */
+    id: string;
+    /** Human-readable label for display. */
+    label: string;
+    /** Alternate tokens that resolve to this section. */
+    aliases?: string[];
+}
+/** All canonical section ids, in declaration order. */
+export declare function getSettingsSections(): SettingsSection[];
+/**
+ * Canonical section ids, usable directly as connector option choices.
+ *
+ * Returns ids only (not aliases) so the choice list stays small and stable; the
+ * count is well under Discord's 25-choice cap.
+ */
+export declare function getSettingsSectionChoices(): string[];
+/**
+ * Resolve a raw `/settings` section token (canonical id or alias) to its
+ * canonical section id. Returns `undefined` when the token matches nothing.
+ */
+export declare function resolveSettingsSection(raw: string): string | undefined;
+//# sourceMappingURL=settings-sections.d.ts.map

package/dist/src/settings-sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-sections.d.ts","sourceRoot":"","sources":["../../src/settings-sections.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,eAAe;IAC/B,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAqCD,uDAAuD;AACvD,wBAAgB,mBAAmB,IAAI,eAAe,EAAE,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAEpD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAItE"}