/** * Bot configuration for the PraisonAI TypeScript SDK. * * Python parity: praisonaiagents/bots/config.py * * Provides {@link BotConfig} (single-platform bot settings), the per-platform * {@link DisplayPolicy} resolution and {@link BotOSConfig} (multi-platform * orchestrator settings). Constructors take an options object whose defaults * match the Python dataclass field defaults; `toDict()` keeps Python's * snake_case keys and masks secrets exactly as the Python `to_dict` does. * * NOTE: `src/gateway/index.ts` also exports a slim `BotConfig` interface. The * class here is the full Python `BotConfig`; the barrel decides which name wins. */ /** Policy for handling unknown users. Python parity: `UnknownUserPolicy` (bots/pairing_types.py). */ export type UnknownUserPolicy = 'deny' | 'pair' | 'allow'; /** * Default safe tools auto-injected for bots with no tools configured. * Python parity: `BotConfig.default_tools` default factory. */ export declare const DEFAULT_BOT_TOOLS: readonly string[]; /** Constructor options for {@link BotConfig}; every field mirrors a Python dataclass field. */ export interface BotConfigOptions { token?: string; /** poll | ws | webhook | hybrid */ mode?: string; webhookUrl?: string | null; webhookPath?: string; webhookPort?: number; pollingInterval?: number; allowedUsers?: string[]; allowedChannels?: string[]; commandPrefix?: string; mentionRequired?: boolean; typingIndicator?: boolean; maxMessageLength?: number; retryAttempts?: number; timeout?: number; replyInThread?: boolean; threadThreshold?: number; /** respond_all, mention_only, command_only, observe */ groupPolicy?: string; defaultTools?: string[]; autoApproveTools?: boolean; debounceMs?: number; ackEmoji?: string; doneEmoji?: string; /** off | direct | group-mentions | group-all | all */ ackScope?: string; sessionTtl?: number; /** queue | interrupt | steer */ busyMode?: string; busyAck?: string; workspaceDir?: string | null; /** rw | ro | none */ workspaceAccess?: string; /** shared | session | user | agent */ workspaceScope?: string; unknownUserPolicy?: UnknownUserPolicy; ownerUserId?: string | null; streaming?: boolean; streamEditIntervalMs?: number; allowSilence?: boolean; silenceToken?: string | null; metadata?: Record; } /** * Configuration for messaging bots. * * Python parity: `BotConfig` (dataclass) in praisonaiagents/bots/config.py. * Throws when `unknownUserPolicy` is not one of deny/pair/allow, like the * Python `__post_init__` ValueError. */ export declare class BotConfig { /** Bot authentication token */ token: string; /** poll | ws | webhook | hybrid */ mode: string; /** URL for webhook mode (optional) */ webhookUrl: string | null; /** Path for webhook endpoint */ webhookPath: string; webhookPort: number; /** Interval for polling mode (seconds) */ pollingInterval: number; /** Explicitly-allowed user IDs; empty defers to `unknownUserPolicy` */ allowedUsers: string[]; /** Allowed channel IDs (empty = all allowed) */ allowedChannels: string[]; commandPrefix: string; mentionRequired: boolean; typingIndicator: boolean; maxMessageLength: number; retryAttempts: number; /** Request timeout in seconds */ timeout: number; replyInThread: boolean; /** Auto-thread responses longer than this (0 = disabled) */ threadThreshold: number; groupPolicy: string; defaultTools: string[]; autoApproveTools: boolean; /** Inbound message debounce (ms); 0 = disabled */ debounceMs: number; ackEmoji: string; doneEmoji: string; ackScope: string; /** Session TTL in seconds; 0 = disabled */ sessionTtl: number; busyMode: string; /** Template for busy acknowledgment messages (use {action} placeholder) */ busyAck: string; workspaceDir: string | null; workspaceAccess: string; workspaceScope: string; unknownUserPolicy: UnknownUserPolicy; ownerUserId: string | null; streaming: boolean; streamEditIntervalMs: number; allowSilence: boolean; silenceToken: string | null; metadata: Record; constructor(options?: BotConfigOptions); /** Convert to a dictionary (snake_case keys; token and owner id masked). */ toDict(): Record; /** Whether bot is configured for webhook mode. */ get isWebhookMode(): boolean; /** Whether bot is configured for WebSocket mode. */ get isWsMode(): boolean; /** Whether bot is configured for hybrid mode (WS + slow poll). */ get isHybridMode(): boolean; /** * Check if a user is allowed to interact with the bot. An empty * `allowedUsers` returns true for backward compatibility; the inbound * pipeline gates on {@link isExplicitlyAllowed} instead. */ isUserAllowed(userId: string): boolean; /** Whether a user is explicitly allow-listed (empty list returns false). */ isExplicitlyAllowed(userId: string): boolean; /** Check if a channel is allowed for bot interaction. */ isChannelAllowed(channelId: string): boolean; } /** * Platform -> tier mapping. Python parity: `_PLATFORM_TIERS`. * edit - edit-capable personal chats (stream live, hide tool spam) * work - workspace chats (post discrete progress steps) * noedit - no-edit chats (single final message) * batch - batch-only channels (one final message, no interim) */ export declare const PLATFORM_TIERS: Readonly>; /** Constructor options for {@link DisplayPolicy}. */ export interface DisplayPolicyOptions { /** off | draft | progress */ streaming?: string; /** off | inline */ toolProgress?: string; interimAssistantMessages?: boolean; /** off | compact */ footer?: string; } /** * Per-platform display / verbosity policy. * Python parity: `DisplayPolicy` (dataclass). */ export declare class DisplayPolicy { streaming: string; toolProgress: string; interimAssistantMessages: boolean; footer: string; constructor(options?: DisplayPolicyOptions); /** Convert to a dictionary with Python's snake_case keys. */ toDict(): Record; /** Create a policy from a (partial) dict (snake_case or camelCase), ignoring unknown keys. */ static fromDict(data: Record): DisplayPolicy; } /** Built-in per-tier defaults. Python parity: `_TIER_DEFAULTS`. */ export declare const TIER_DEFAULTS: Readonly>; /** Return `value` if it is an allowed choice, else `defaultValue`. Python parity: `_coerce_choice`. */ export declare function coerceChoice(value: unknown, allowed: ReadonlySet, defaultValue: string): string; /** Coerce `value` to a boolean without `Boolean("false") === true` surprises. Python parity: `_coerce_bool`. */ export declare function coerceBool(value: unknown, defaultValue: boolean): boolean; /** * Resolve the effective {@link DisplayPolicy} for a platform. * * Python parity: `resolve_display_policy(platform, config)`. Precedence * (highest first): explicit `display.platforms..`, the * `display.` global default, the platform-tier default, then the * built-in default. */ export declare function resolveDisplayPolicy(platform: string, config: Record | null | undefined): DisplayPolicy; /** Constructor options for {@link BotOSConfig}. */ export interface BotOSConfigOptions { /** Human-readable name for this BotOS instance */ name?: string; /** Per-platform config dicts keyed by platform name */ platforms?: Record>; } /** * Configuration for BotOS, the multi-platform bot orchestrator. * * Python parity: `BotOSConfig` (dataclass) in praisonaiagents/bots/config.py. * * @example * ```typescript * const cfg = new BotOSConfig({ platforms: { telegram: { token: 'secret' } } }); * cfg.toDict().platforms.telegram.token; // '***' * ``` */ export declare class BotOSConfig { name: string; platforms: Record>; constructor(options?: BotOSConfigOptions); /** Serialize to a dictionary, masking every platform's `token`. */ toDict(): Record; }