@noxsoft/anima 2.0.0

package/dist/plugin-sdk/config/types.openclaw.d.ts

@@ -0,0 +1,114 @@
+import type { AgentBinding, AgentsConfig } from "./types.agents.js";
+import type { ApprovalsConfig } from "./types.approvals.js";
+import type { AuthConfig } from "./types.auth.js";
+import type { DiagnosticsConfig, LoggingConfig, SessionConfig, WebConfig } from "./types.base.js";
+import type { BrowserConfig } from "./types.browser.js";
+import type { ChannelsConfig } from "./types.channels.js";
+import type { CronConfig } from "./types.cron.js";
+import type { CanvasHostConfig, DiscoveryConfig, GatewayConfig, TalkConfig } from "./types.gateway.js";
+import type { HooksConfig } from "./types.hooks.js";
+import type { MemoryConfig } from "./types.memory.js";
+import type { AudioConfig, BroadcastConfig, CommandsConfig, MessagesConfig } from "./types.messages.js";
+import type { ModelsConfig } from "./types.models.js";
+import type { NodeHostConfig } from "./types.node-host.js";
+import type { PluginsConfig } from "./types.plugins.js";
+import type { SkillsConfig } from "./types.skills.js";
+import type { ToolsConfig } from "./types.tools.js";
+export type AnimaConfig = {
+    meta?: {
+        /** Last Anima version that wrote this config. */
+        lastTouchedVersion?: string;
+        /** ISO timestamp when this config was last written. */
+        lastTouchedAt?: string;
+    };
+    auth?: AuthConfig;
+    env?: {
+        /** Opt-in: import missing secrets from a login shell environment (exec `$SHELL -l -c 'env -0'`). */
+        shellEnv?: {
+            enabled?: boolean;
+            /** Timeout for the login shell exec (ms). Default: 15000. */
+            timeoutMs?: number;
+        };
+        /** Inline env vars to apply when not already present in the process env. */
+        vars?: Record<string, string>;
+        /** Sugar: allow env vars directly under env (string values only). */
+        [key: string]: string | Record<string, string> | {
+            enabled?: boolean;
+            timeoutMs?: number;
+        } | undefined;
+    };
+    wizard?: {
+        lastRunAt?: string;
+        lastRunVersion?: string;
+        lastRunCommit?: string;
+        lastRunCommand?: string;
+        lastRunMode?: "local" | "remote";
+    };
+    diagnostics?: DiagnosticsConfig;
+    logging?: LoggingConfig;
+    update?: {
+        /** Update channel for git + npm installs ("stable", "beta", or "dev"). */
+        channel?: "stable" | "beta" | "dev";
+        /** Check for updates on gateway start (npm installs only). */
+        checkOnStart?: boolean;
+    };
+    browser?: BrowserConfig;
+    ui?: {
+        /** Accent color for Anima UI chrome (hex). */
+        seamColor?: string;
+        assistant?: {
+            /** Assistant display name for UI surfaces. */
+            name?: string;
+            /** Assistant avatar (emoji, short text, or image URL/data URI). */
+            avatar?: string;
+        };
+    };
+    skills?: SkillsConfig;
+    plugins?: PluginsConfig;
+    models?: ModelsConfig;
+    nodeHost?: NodeHostConfig;
+    agents?: AgentsConfig;
+    tools?: ToolsConfig;
+    bindings?: AgentBinding[];
+    broadcast?: BroadcastConfig;
+    audio?: AudioConfig;
+    messages?: MessagesConfig;
+    commands?: CommandsConfig;
+    approvals?: ApprovalsConfig;
+    session?: SessionConfig;
+    web?: WebConfig;
+    channels?: ChannelsConfig;
+    cron?: CronConfig;
+    hooks?: HooksConfig;
+    discovery?: DiscoveryConfig;
+    canvasHost?: CanvasHostConfig;
+    talk?: TalkConfig;
+    gateway?: GatewayConfig;
+    memory?: MemoryConfig;
+};
+export type ConfigValidationIssue = {
+    path: string;
+    message: string;
+};
+export type LegacyConfigIssue = {
+    path: string;
+    message: string;
+};
+export type ConfigFileSnapshot = {
+    path: string;
+    exists: boolean;
+    raw: string | null;
+    parsed: unknown;
+    /**
+     * Config after $include resolution and ${ENV} substitution, but BEFORE runtime
+     * defaults are applied. Use this for config set/unset operations to avoid
+     * leaking runtime defaults into the written config file.
+     */
+    resolved: AnimaConfig;
+    valid: boolean;
+    config: AnimaConfig;
+    hash?: string;
+    issues: ConfigValidationIssue[];
+    warnings: ConfigValidationIssue[];
+    legacyIssues: LegacyConfigIssue[];
+};

package/dist/plugin-sdk/config/types.plugins.d.ts

@@ -0,0 +1,32 @@
+export type PluginEntryConfig = {
+    enabled?: boolean;
+    config?: Record<string, unknown>;
+};
+export type PluginSlotsConfig = {
+    /** Select which plugin owns the memory slot ("none" disables memory plugins). */
+    memory?: string;
+};
+export type PluginsLoadConfig = {
+    /** Additional plugin/extension paths to load. */
+    paths?: string[];
+};
+export type PluginInstallRecord = {
+    source: "npm" | "archive" | "path";
+    spec?: string;
+    sourcePath?: string;
+    installPath?: string;
+    version?: string;
+    installedAt?: string;
+};
+export type PluginsConfig = {
+    /** Enable or disable plugin loading. */
+    enabled?: boolean;
+    /** Optional plugin allowlist (plugin ids). */
+    allow?: string[];
+    /** Optional plugin denylist (plugin ids). */
+    deny?: string[];
+    load?: PluginsLoadConfig;
+    slots?: PluginSlotsConfig;
+    entries?: Record<string, PluginEntryConfig>;
+    installs?: Record<string, PluginInstallRecord>;
+};

package/dist/plugin-sdk/config/types.queue.d.ts

@@ -0,0 +1,14 @@
+export type QueueMode = "steer" | "followup" | "collect" | "steer-backlog" | "steer+backlog" | "queue" | "interrupt";
+export type QueueDropPolicy = "old" | "new" | "summarize";
+export type QueueModeByProvider = {
+    whatsapp?: QueueMode;
+    telegram?: QueueMode;
+    discord?: QueueMode;
+    irc?: QueueMode;
+    googlechat?: QueueMode;
+    slack?: QueueMode;
+    signal?: QueueMode;
+    imessage?: QueueMode;
+    msteams?: QueueMode;
+    webchat?: QueueMode;
+};

package/dist/plugin-sdk/config/types.sandbox.d.ts

@@ -0,0 +1,78 @@
+export type SandboxDockerSettings = {
+    /** Docker image to use for sandbox containers. */
+    image?: string;
+    /** Prefix for sandbox container names. */
+    containerPrefix?: string;
+    /** Container workdir mount path (default: /workspace). */
+    workdir?: string;
+    /** Run container rootfs read-only. */
+    readOnlyRoot?: boolean;
+    /** Extra tmpfs mounts for read-only containers. */
+    tmpfs?: string[];
+    /** Container network mode (bridge|none|custom). */
+    network?: string;
+    /** Container user (uid:gid). */
+    user?: string;
+    /** Drop Linux capabilities. */
+    capDrop?: string[];
+    /** Extra environment variables for sandbox exec. */
+    env?: Record<string, string>;
+    /** Optional setup command run once after container creation. */
+    setupCommand?: string;
+    /** Limit container PIDs (0 = Docker default). */
+    pidsLimit?: number;
+    /** Limit container memory (e.g. 512m, 2g, or bytes as number). */
+    memory?: string | number;
+    /** Limit container memory swap (same format as memory). */
+    memorySwap?: string | number;
+    /** Limit container CPU shares (e.g. 0.5, 1, 2). */
+    cpus?: number;
+    /**
+     * Set ulimit values by name (e.g. nofile, nproc).
+     * Use "soft:hard" string, a number, or { soft, hard }.
+     */
+    ulimits?: Record<string, string | number | {
+        soft?: number;
+        hard?: number;
+    }>;
+    /** Seccomp profile (path or profile name). */
+    seccompProfile?: string;
+    /** AppArmor profile name. */
+    apparmorProfile?: string;
+    /** DNS servers (e.g. ["1.1.1.1", "8.8.8.8"]). */
+    dns?: string[];
+    /** Extra host mappings (e.g. ["api.local:10.0.0.2"]). */
+    extraHosts?: string[];
+    /** Additional bind mounts (host:container:mode format, e.g. ["/host/path:/container/path:rw"]). */
+    binds?: string[];
+};
+export type SandboxBrowserSettings = {
+    enabled?: boolean;
+    image?: string;
+    containerPrefix?: string;
+    cdpPort?: number;
+    vncPort?: number;
+    noVncPort?: number;
+    headless?: boolean;
+    enableNoVnc?: boolean;
+    /**
+     * Allow sandboxed sessions to target the host browser control server.
+     * Default: false.
+     */
+    allowHostControl?: boolean;
+    /**
+     * When true (default), sandboxed browser control will try to start/reattach to
+     * the sandbox browser container when a tool call needs it.
+     */
+    autoStart?: boolean;
+    /** Max time to wait for CDP to become reachable after auto-start (ms). */
+    autoStartTimeoutMs?: number;
+    /** Additional bind mounts for the browser container only. When set, replaces docker.binds for the browser container. */
+    binds?: string[];
+};
+export type SandboxPruneSettings = {
+    /** Prune if idle for more than N hours (0 disables). */
+    idleHours?: number;
+    /** Prune if older than N days (0 disables). */
+    maxAgeDays?: number;
+};

package/dist/plugin-sdk/config/types.signal.d.ts

@@ -0,0 +1,86 @@
+import type { BlockStreamingCoalesceConfig, DmPolicy, GroupPolicy, MarkdownConfig } from "./types.base.js";
+import type { ChannelHeartbeatVisibilityConfig } from "./types.channels.js";
+import type { DmConfig } from "./types.messages.js";
+export type SignalReactionNotificationMode = "off" | "own" | "all" | "allowlist";
+export type SignalReactionLevel = "off" | "ack" | "minimal" | "extensive";
+export type SignalAccountConfig = {
+    /** Optional display name for this account (used in CLI/UI lists). */
+    name?: string;
+    /** Optional provider capability tags used for agent/runtime guidance. */
+    capabilities?: string[];
+    /** Markdown formatting overrides (tables). */
+    markdown?: MarkdownConfig;
+    /** Allow channel-initiated config writes (default: true). */
+    configWrites?: boolean;
+    /** If false, do not start this Signal account. Default: true. */
+    enabled?: boolean;
+    /** Optional explicit E.164 account for signal-cli. */
+    account?: string;
+    /** Optional full base URL for signal-cli HTTP daemon. */
+    httpUrl?: string;
+    /** HTTP host for signal-cli daemon (default 127.0.0.1). */
+    httpHost?: string;
+    /** HTTP port for signal-cli daemon (default 8080). */
+    httpPort?: number;
+    /** signal-cli binary path (default: signal-cli). */
+    cliPath?: string;
+    /** Auto-start signal-cli daemon (default: true if httpUrl not set). */
+    autoStart?: boolean;
+    /** Max time to wait for signal-cli daemon startup (ms, cap 120000). */
+    startupTimeoutMs?: number;
+    receiveMode?: "on-start" | "manual";
+    ignoreAttachments?: boolean;
+    ignoreStories?: boolean;
+    sendReadReceipts?: boolean;
+    /** Direct message access policy (default: pairing). */
+    dmPolicy?: DmPolicy;
+    allowFrom?: Array<string | number>;
+    /** Optional allowlist for Signal group senders (E.164). */
+    groupAllowFrom?: Array<string | number>;
+    /**
+     * Controls how group messages are handled:
+     * - "open": groups bypass allowFrom, no extra gating
+     * - "disabled": block all group messages
+     * - "allowlist": only allow group messages from senders in groupAllowFrom/allowFrom
+     */
+    groupPolicy?: GroupPolicy;
+    /** Max group messages to keep as history context (0 disables). */
+    historyLimit?: number;
+    /** Max DM turns to keep as history context. */
+    dmHistoryLimit?: number;
+    /** Per-DM config overrides keyed by user ID. */
+    dms?: Record<string, DmConfig>;
+    /** Outbound text chunk size (chars). Default: 4000. */
+    textChunkLimit?: number;
+    /** Chunking mode: "length" (default) splits by size; "newline" splits on every newline. */
+    chunkMode?: "length" | "newline";
+    blockStreaming?: boolean;
+    /** Merge streamed block replies before sending. */
+    blockStreamingCoalesce?: BlockStreamingCoalesceConfig;
+    mediaMaxMb?: number;
+    /** Reaction notification mode (off|own|all|allowlist). Default: own. */
+    reactionNotifications?: SignalReactionNotificationMode;
+    /** Allowlist for reaction notifications when mode is allowlist. */
+    reactionAllowlist?: Array<string | number>;
+    /** Action toggles for message tool capabilities. */
+    actions?: {
+        /** Enable/disable sending reactions via message tool (default: true). */
+        reactions?: boolean;
+    };
+    /**
+     * Controls agent reaction behavior:
+     * - "off": No reactions
+     * - "ack": Only automatic ack reactions (👀 when processing)
+     * - "minimal": Agent can react sparingly (default)
+     * - "extensive": Agent can react liberally
+     */
+    reactionLevel?: SignalReactionLevel;
+    /** Heartbeat visibility settings for this channel. */
+    heartbeat?: ChannelHeartbeatVisibilityConfig;
+    /** Outbound response prefix override for this channel/account. */
+    responsePrefix?: string;
+};
+export type SignalConfig = {
+    /** Optional per-account Signal configuration (multi-account). */
+    accounts?: Record<string, SignalAccountConfig>;
+} & SignalAccountConfig;

package/dist/plugin-sdk/config/types.skills.d.ts

@@ -0,0 +1,28 @@
+export type SkillConfig = {
+    enabled?: boolean;
+    apiKey?: string;
+    env?: Record<string, string>;
+    config?: Record<string, unknown>;
+};
+export type SkillsLoadConfig = {
+    /**
+     * Additional skill folders to scan (lowest precedence).
+     * Each directory should contain skill subfolders with `SKILL.md`.
+     */
+    extraDirs?: string[];
+    /** Watch skill folders for changes and refresh the skills snapshot. */
+    watch?: boolean;
+    /** Debounce for the skills watcher (ms). */
+    watchDebounceMs?: number;
+};
+export type SkillsInstallConfig = {
+    preferBrew?: boolean;
+    nodeManager?: "npm" | "pnpm" | "yarn" | "bun";
+};
+export type SkillsConfig = {
+    /** Optional bundled-skill allowlist (only affects bundled skills). */
+    allowBundled?: string[];
+    load?: SkillsLoadConfig;
+    install?: SkillsInstallConfig;
+    entries?: Record<string, SkillConfig>;
+};

package/dist/plugin-sdk/config/types.slack.d.ts

@@ -0,0 +1,150 @@
+import type { BlockStreamingCoalesceConfig, DmPolicy, GroupPolicy, MarkdownConfig, ReplyToMode } from "./types.base.js";
+import type { ChannelHeartbeatVisibilityConfig } from "./types.channels.js";
+import type { DmConfig, ProviderCommandsConfig } from "./types.messages.js";
+import type { GroupToolPolicyBySenderConfig, GroupToolPolicyConfig } from "./types.tools.js";
+export type SlackDmConfig = {
+    /** If false, ignore all incoming Slack DMs. Default: true. */
+    enabled?: boolean;
+    /** Direct message access policy (default: pairing). */
+    policy?: DmPolicy;
+    /** Allowlist for DM senders (ids). */
+    allowFrom?: Array<string | number>;
+    /** If true, allow group DMs (default: false). */
+    groupEnabled?: boolean;
+    /** Optional allowlist for group DM channels (ids or slugs). */
+    groupChannels?: Array<string | number>;
+    /** @deprecated Prefer channels.slack.replyToModeByChatType.direct. */
+    replyToMode?: ReplyToMode;
+};
+export type SlackChannelConfig = {
+    /** If false, disable the bot in this channel. (Alias for allow: false.) */
+    enabled?: boolean;
+    /** Legacy channel allow toggle; prefer enabled. */
+    allow?: boolean;
+    /** Require mentioning the bot to trigger replies. */
+    requireMention?: boolean;
+    /** Optional tool policy overrides for this channel. */
+    tools?: GroupToolPolicyConfig;
+    toolsBySender?: GroupToolPolicyBySenderConfig;
+    /** Allow bot-authored messages to trigger replies (default: false). */
+    allowBots?: boolean;
+    /** Allowlist of users that can invoke the bot in this channel. */
+    users?: Array<string | number>;
+    /** Optional skill filter for this channel. */
+    skills?: string[];
+    /** Optional system prompt for this channel. */
+    systemPrompt?: string;
+};
+export type SlackReactionNotificationMode = "off" | "own" | "all" | "allowlist";
+export type SlackActionConfig = {
+    reactions?: boolean;
+    messages?: boolean;
+    pins?: boolean;
+    search?: boolean;
+    permissions?: boolean;
+    memberInfo?: boolean;
+    channelInfo?: boolean;
+    emojiList?: boolean;
+};
+export type SlackSlashCommandConfig = {
+    /** Enable handling for the configured slash command (default: false). */
+    enabled?: boolean;
+    /** Slash command name (default: "anima"). */
+    name?: string;
+    /** Session key prefix for slash commands (default: "slack:slash"). */
+    sessionPrefix?: string;
+    /** Reply ephemerally (default: true). */
+    ephemeral?: boolean;
+};
+export type SlackThreadConfig = {
+    /** Scope for thread history context (thread|channel). Default: thread. */
+    historyScope?: "thread" | "channel";
+    /** If true, thread sessions inherit the parent channel transcript. Default: false. */
+    inheritParent?: boolean;
+    /** Maximum number of thread messages to fetch as context when starting a new thread session (default: 20). Set to 0 to disable thread history fetching. */
+    initialHistoryLimit?: number;
+};
+export type SlackAccountConfig = {
+    /** Optional display name for this account (used in CLI/UI lists). */
+    name?: string;
+    /** Slack connection mode (socket|http). Default: socket. */
+    mode?: "socket" | "http";
+    /** Slack signing secret (required for HTTP mode). */
+    signingSecret?: string;
+    /** Slack Events API webhook path (default: /slack/events). */
+    webhookPath?: string;
+    /** Optional provider capability tags used for agent/runtime guidance. */
+    capabilities?: string[];
+    /** Markdown formatting overrides (tables). */
+    markdown?: MarkdownConfig;
+    /** Override native command registration for Slack (bool or "auto"). */
+    commands?: ProviderCommandsConfig;
+    /** Allow channel-initiated config writes (default: true). */
+    configWrites?: boolean;
+    /** If false, do not start this Slack account. Default: true. */
+    enabled?: boolean;
+    botToken?: string;
+    appToken?: string;
+    userToken?: string;
+    /** If true, restrict user token to read operations only. Default: true. */
+    userTokenReadOnly?: boolean;
+    /** Allow bot-authored messages to trigger replies (default: false). */
+    allowBots?: boolean;
+    /** Default mention requirement for channel messages (default: true). */
+    requireMention?: boolean;
+    /**
+     * Controls how channel messages are handled:
+     * - "open": channels bypass allowlists; mention-gating applies
+     * - "disabled": block all channel messages
+     * - "allowlist": only allow channels present in channels.slack.channels
+     */
+    groupPolicy?: GroupPolicy;
+    /** Max channel messages to keep as history context (0 disables). */
+    historyLimit?: number;
+    /** Max DM turns to keep as history context. */
+    dmHistoryLimit?: number;
+    /** Per-DM config overrides keyed by user ID. */
+    dms?: Record<string, DmConfig>;
+    textChunkLimit?: number;
+    /** Chunking mode: "length" (default) splits by size; "newline" splits on every newline. */
+    chunkMode?: "length" | "newline";
+    blockStreaming?: boolean;
+    /** Merge streamed block replies before sending. */
+    blockStreamingCoalesce?: BlockStreamingCoalesceConfig;
+    mediaMaxMb?: number;
+    /** Reaction notification mode (off|own|all|allowlist). Default: own. */
+    reactionNotifications?: SlackReactionNotificationMode;
+    /** Allowlist for reaction notifications when mode is allowlist. */
+    reactionAllowlist?: Array<string | number>;
+    /** Control reply threading when reply tags are present (off|first|all). */
+    replyToMode?: ReplyToMode;
+    /**
+     * Optional per-chat-type reply threading overrides.
+     * Example: { direct: "all", group: "first", channel: "off" }.
+     */
+    replyToModeByChatType?: Partial<Record<"direct" | "group" | "channel", ReplyToMode>>;
+    /** Thread session behavior. */
+    thread?: SlackThreadConfig;
+    actions?: SlackActionConfig;
+    slashCommand?: SlackSlashCommandConfig;
+    /**
+     * Alias for dm.policy (prefer this so it inherits cleanly via base->account shallow merge).
+     * Legacy key: channels.slack.dm.policy.
+     */
+    dmPolicy?: DmPolicy;
+    /**
+     * Alias for dm.allowFrom (prefer this so it inherits cleanly via base->account shallow merge).
+     * Legacy key: channels.slack.dm.allowFrom.
+     */
+    allowFrom?: Array<string | number>;
+    dm?: SlackDmConfig;
+    channels?: Record<string, SlackChannelConfig>;
+    /** Heartbeat visibility settings for this channel. */
+    heartbeat?: ChannelHeartbeatVisibilityConfig;
+    /** Outbound response prefix override for this channel/account. */
+    responsePrefix?: string;
+};
+export type SlackConfig = {
+    /** Optional per-account Slack configuration (multi-account). */
+    accounts?: Record<string, SlackAccountConfig>;
+} & SlackAccountConfig;

package/dist/plugin-sdk/config/types.telegram.d.ts

@@ -0,0 +1,163 @@
+import type { BlockStreamingChunkConfig, BlockStreamingCoalesceConfig, DmPolicy, GroupPolicy, MarkdownConfig, OutboundRetryConfig, ReplyToMode } from "./types.base.js";
+import type { ChannelHeartbeatVisibilityConfig } from "./types.channels.js";
+import type { DmConfig, ProviderCommandsConfig } from "./types.messages.js";
+import type { GroupToolPolicyBySenderConfig, GroupToolPolicyConfig } from "./types.tools.js";
+export type TelegramActionConfig = {
+    reactions?: boolean;
+    sendMessage?: boolean;
+    deleteMessage?: boolean;
+    editMessage?: boolean;
+    /** Enable sticker actions (send and search). */
+    sticker?: boolean;
+};
+export type TelegramNetworkConfig = {
+    /** Override Node's autoSelectFamily behavior (true = enable, false = disable). */
+    autoSelectFamily?: boolean;
+};
+export type TelegramInlineButtonsScope = "off" | "dm" | "group" | "all" | "allowlist";
+export type TelegramCapabilitiesConfig = string[] | {
+    inlineButtons?: TelegramInlineButtonsScope;
+};
+/** Custom command definition for Telegram bot menu. */
+export type TelegramCustomCommand = {
+    /** Command name (without leading /). */
+    command: string;
+    /** Description shown in Telegram command menu. */
+    description: string;
+};
+export type TelegramAccountConfig = {
+    /** Optional display name for this account (used in CLI/UI lists). */
+    name?: string;
+    /** Optional provider capability tags used for agent/runtime guidance. */
+    capabilities?: TelegramCapabilitiesConfig;
+    /** Markdown formatting overrides (tables). */
+    markdown?: MarkdownConfig;
+    /** Override native command registration for Telegram (bool or "auto"). */
+    commands?: ProviderCommandsConfig;
+    /** Custom commands to register in Telegram's command menu (merged with native). */
+    customCommands?: TelegramCustomCommand[];
+    /** Allow channel-initiated config writes (default: true). */
+    configWrites?: boolean;
+    /**
+     * Controls how Telegram direct chats (DMs) are handled:
+     * - "pairing" (default): unknown senders get a pairing code; owner must approve
+     * - "allowlist": only allow senders in allowFrom (or paired allow store)
+     * - "open": allow all inbound DMs (requires allowFrom to include "*")
+     * - "disabled": ignore all inbound DMs
+     */
+    dmPolicy?: DmPolicy;
+    /** If false, do not start this Telegram account. Default: true. */
+    enabled?: boolean;
+    botToken?: string;
+    /** Path to file containing bot token (for secret managers like agenix). */
+    tokenFile?: string;
+    /** Control reply threading when reply tags are present (off|first|all). */
+    replyToMode?: ReplyToMode;
+    groups?: Record<string, TelegramGroupConfig>;
+    /** DM allowlist (numeric Telegram user IDs). Onboarding can resolve @username to IDs. */
+    allowFrom?: Array<string | number>;
+    /** Optional allowlist for Telegram group senders (numeric Telegram user IDs). */
+    groupAllowFrom?: Array<string | number>;
+    /**
+     * Controls how group messages are handled:
+     * - "open": groups bypass allowFrom, only mention-gating applies
+     * - "disabled": block all group messages entirely
+     * - "allowlist": only allow group messages from senders in groupAllowFrom/allowFrom
+     */
+    groupPolicy?: GroupPolicy;
+    /** Max group messages to keep as history context (0 disables). */
+    historyLimit?: number;
+    /** Max DM turns to keep as history context. */
+    dmHistoryLimit?: number;
+    /** Per-DM config overrides keyed by user ID. */
+    dms?: Record<string, DmConfig>;
+    /** Outbound text chunk size (chars). Default: 4000. */
+    textChunkLimit?: number;
+    /** Chunking mode: "length" (default) splits by size; "newline" splits on every newline. */
+    chunkMode?: "length" | "newline";
+    /** Disable block streaming for this account. */
+    blockStreaming?: boolean;
+    /** Chunking config for draft streaming in `streamMode: "block"`. */
+    draftChunk?: BlockStreamingChunkConfig;
+    /** Merge streamed block replies before sending. */
+    blockStreamingCoalesce?: BlockStreamingCoalesceConfig;
+    /** Draft streaming mode for Telegram (off|partial|block). Default: partial. */
+    streamMode?: "off" | "partial" | "block";
+    mediaMaxMb?: number;
+    /** Telegram API client timeout in seconds (grammY ApiClientOptions). */
+    timeoutSeconds?: number;
+    /** Retry policy for outbound Telegram API calls. */
+    retry?: OutboundRetryConfig;
+    /** Network transport overrides for Telegram. */
+    network?: TelegramNetworkConfig;
+    proxy?: string;
+    webhookUrl?: string;
+    webhookSecret?: string;
+    webhookPath?: string;
+    /** Local webhook listener bind host (default: 127.0.0.1). */
+    webhookHost?: string;
+    /** Per-action tool gating (default: true for all). */
+    actions?: TelegramActionConfig;
+    /**
+     * Controls which user reactions trigger notifications:
+     * - "off" (default): ignore all reactions
+     * - "own": notify when users react to bot messages
+     * - "all": notify agent of all reactions
+     */
+    reactionNotifications?: "off" | "own" | "all";
+    /**
+     * Controls agent's reaction capability:
+     * - "off": agent cannot react
+     * - "ack" (default): bot sends acknowledgment reactions (👀 while processing)
+     * - "minimal": agent can react sparingly (guideline: 1 per 5-10 exchanges)
+     * - "extensive": agent can react liberally when appropriate
+     */
+    reactionLevel?: "off" | "ack" | "minimal" | "extensive";
+    /** Heartbeat visibility settings for this channel. */
+    heartbeat?: ChannelHeartbeatVisibilityConfig;
+    /** Controls whether link previews are shown in outbound messages. Default: true. */
+    linkPreview?: boolean;
+    /**
+     * Per-channel outbound response prefix override.
+     *
+     * When set, this takes precedence over the global `messages.responsePrefix`.
+     * Use `""` to explicitly disable a global prefix for this channel.
+     * Use `"auto"` to derive `[{identity.name}]` from the routed agent.
+     */
+    responsePrefix?: string;
+};
+export type TelegramTopicConfig = {
+    requireMention?: boolean;
+    /** Per-topic override for group message policy (open|disabled|allowlist). */
+    groupPolicy?: GroupPolicy;
+    /** If specified, only load these skills for this topic. Omit = all skills; empty = no skills. */
+    skills?: string[];
+    /** If false, disable the bot for this topic. */
+    enabled?: boolean;
+    /** Optional allowlist for topic senders (numeric Telegram user IDs). */
+    allowFrom?: Array<string | number>;
+    /** Optional system prompt snippet for this topic. */
+    systemPrompt?: string;
+};
+export type TelegramGroupConfig = {
+    requireMention?: boolean;
+    /** Per-group override for group message policy (open|disabled|allowlist). */
+    groupPolicy?: GroupPolicy;
+    /** Optional tool policy overrides for this group. */
+    tools?: GroupToolPolicyConfig;
+    toolsBySender?: GroupToolPolicyBySenderConfig;
+    /** If specified, only load these skills for this group (when no topic). Omit = all skills; empty = no skills. */
+    skills?: string[];
+    /** Per-topic configuration (key is message_thread_id as string) */
+    topics?: Record<string, TelegramTopicConfig>;
+    /** If false, disable the bot for this group (and its topics). */
+    enabled?: boolean;
+    /** Optional allowlist for group senders (numeric Telegram user IDs). */
+    allowFrom?: Array<string | number>;
+    /** Optional system prompt snippet for this group. */
+    systemPrompt?: string;
+};
+export type TelegramConfig = {
+    /** Optional per-account Telegram configuration (multi-account). */
+    accounts?: Record<string, TelegramAccountConfig>;
+} & TelegramAccountConfig;