@cmdop/bot 2026.2.26

package/dist/index.d.ts

@@ -0,0 +1,873 @@
+import { z } from 'zod/v4';
+import { CMDOPClient } from '@cmdop/node';
+import { WebClient } from '@slack/web-api';
+import { InlineKeyboardButton } from 'grammy/types';
+import { RESTPostAPIChatInputApplicationCommandsJSONBody } from 'discord.js';
+
+declare const AttachmentSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        photo: "photo";
+        document: "document";
+        audio: "audio";
+        video: "video";
+    }>;
+    fileId: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    size: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type Attachment = z.infer<typeof AttachmentSchema>;
+declare const IncomingMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    userId: z.ZodString;
+    channelId: z.ZodString;
+    text: z.ZodString;
+    timestamp: z.ZodCoercedDate<unknown>;
+    attachments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            photo: "photo";
+            document: "document";
+            audio: "audio";
+            video: "video";
+        }>;
+        fileId: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    replyToId: z.ZodOptional<z.ZodString>;
+    threadId: z.ZodOptional<z.ZodString>;
+    raw: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type IncomingMessage = z.infer<typeof IncomingMessageSchema>;
+declare const TextMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>;
+type TextMessage = z.infer<typeof TextMessageSchema>;
+declare const CodeMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"code">;
+    code: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CodeMessage = z.infer<typeof CodeMessageSchema>;
+declare const ErrorMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    message: z.ZodString;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ErrorMessage = z.infer<typeof ErrorMessageSchema>;
+declare const OutgoingMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"code">;
+    code: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    message: z.ZodString;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+type OutgoingMessage = z.infer<typeof OutgoingMessageSchema>;
+
+declare const PermissionLevelSchema: z.ZodEnum<{
+    NONE: "NONE";
+    READ: "READ";
+    EXECUTE: "EXECUTE";
+    FILES: "FILES";
+    ADMIN: "ADMIN";
+}>;
+type PermissionLevel = z.infer<typeof PermissionLevelSchema>;
+declare const PERMISSION_ORDER: Record<PermissionLevel, number>;
+declare const UserIdentitySchema: z.ZodObject<{
+    platform: z.ZodString;
+    platformId: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    displayName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type UserIdentity = z.infer<typeof UserIdentitySchema>;
+declare const BotUserSchema: z.ZodObject<{
+    id: z.ZodString;
+    identity: z.ZodObject<{
+        platform: z.ZodString;
+        platformId: z.ZodString;
+        username: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    permission: z.ZodEnum<{
+        NONE: "NONE";
+        READ: "READ";
+        EXECUTE: "EXECUTE";
+        FILES: "FILES";
+        ADMIN: "ADMIN";
+    }>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    lastSeenAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+type BotUser = z.infer<typeof BotUserSchema>;
+
+declare const ParsedCommandSchema: z.ZodObject<{
+    name: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+    rawText: z.ZodString;
+}, z.core.$strip>;
+type ParsedCommand = z.infer<typeof ParsedCommandSchema>;
+type CommandContext = {
+    readonly userId: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly channelId: string;
+    readonly message: IncomingMessage;
+    readonly machine?: string;
+};
+type CommandInfo = {
+    readonly name: string;
+    readonly description: string;
+    readonly usage: string;
+    readonly requiredPermission: string;
+};
+/**
+ * Parse a bot command from message text.
+ * Supports: /exec ls -la, !exec ls -la
+ * Requires a / or ! prefix to distinguish commands from plain chat messages.
+ */
+declare function parseCommand(text: string): ParsedCommand | null;
+
+/**
+ * @cmdop/bot — Error hierarchy
+ *
+ * All errors thrown by @cmdop/bot extend BotError.
+ * Never expose raw @cmdop/node or platform errors to consumers — wrap them.
+ */
+declare class BotError extends Error {
+    readonly code: string;
+    readonly context: Record<string, unknown>;
+    constructor(message: string, options?: {
+        code?: string;
+        context?: Record<string, unknown>;
+        cause?: Error;
+    });
+    toLog(): Record<string, unknown>;
+}
+declare class PermissionDeniedError extends BotError {
+    constructor(userId: string, required: string);
+}
+declare class RateLimitError extends BotError {
+    readonly retryAfterMs?: number;
+    constructor(message: string, retryAfterMs?: number);
+}
+declare class HandlerError extends BotError {
+    constructor(message: string, options?: {
+        code?: string;
+        context?: Record<string, unknown>;
+        cause?: Error;
+    });
+}
+declare class CommandNotFoundError extends HandlerError {
+    constructor(command: string);
+}
+declare class CommandArgsError extends HandlerError {
+    constructor(command: string, hint: string);
+}
+declare class ExecutionTimeoutError extends HandlerError {
+    constructor(command: string, timeoutMs: number);
+}
+declare class CMDOPError extends BotError {
+    constructor(message: string, cause?: Error);
+}
+declare class MachineNotFoundError extends BotError {
+    constructor(machine: string);
+}
+declare class MachineOfflineError extends BotError {
+    constructor(machine: string);
+}
+declare class CMDOPTimeoutError extends BotError {
+    constructor(operation: string, timeoutMs: number, cause?: Error);
+}
+declare class ChannelError extends BotError {
+    constructor(message: string, options?: {
+        code?: string;
+        context?: Record<string, unknown>;
+        cause?: Error;
+    });
+}
+declare class TelegramError extends ChannelError {
+    constructor(message: string, cause?: Error);
+}
+declare class DiscordError extends ChannelError {
+    constructor(message: string, cause?: Error);
+}
+declare class SlackError extends ChannelError {
+    constructor(message: string, cause?: Error);
+}
+declare class TeamsError extends ChannelError {
+    constructor(message: string, cause?: Error);
+}
+declare class ConfigError extends BotError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+
+type HandlerResult = {
+    ok: true;
+    value: OutgoingMessage;
+} | {
+    ok: false;
+    error: BotError;
+};
+declare function ok(value: OutgoingMessage): HandlerResult;
+declare function err(error: BotError): HandlerResult;
+interface ChannelProtocol {
+    readonly id: string;
+    readonly name: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(userId: string, message: OutgoingMessage): Promise<void>;
+    onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
+}
+interface HandlerProtocol {
+    readonly name: string;
+    readonly description: string;
+    readonly usage: string;
+    readonly requiredPermission: PermissionLevel;
+    handle(ctx: CommandContext): Promise<HandlerResult>;
+}
+interface FormatterProtocol {
+    formatText(text: string): string;
+    formatCode(code: string, language?: string): string;
+    formatError(error: BotError): string;
+}
+interface PermissionStoreProtocol {
+    getLevel(userId: string): Promise<PermissionLevel>;
+    setLevel(userId: string, level: PermissionLevel): Promise<void>;
+    deleteUser(userId: string): Promise<void>;
+}
+interface LoggerProtocol {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+
+declare class InMemoryPermissionStore implements PermissionStoreProtocol {
+    private readonly store;
+    constructor(seed?: Record<string, PermissionLevel>);
+    getLevel(userId: string): Promise<PermissionLevel>;
+    setLevel(userId: string, level: PermissionLevel): Promise<void>;
+    deleteUser(userId: string): Promise<void>;
+}
+/**
+ * Maps platform-scoped user IDs to a single canonical user ID.
+ *
+ * Platform IDs are namespaced as `"<channel>:<userId>"` (e.g. `"telegram:12345"`).
+ * When a user is linked, all their platform IDs resolve to the same canonical ID,
+ * so a permission granted on Telegram automatically applies on Discord and Slack.
+ *
+ * Example:
+ *   map.link('telegram:12345', 'discord:67890');
+ *   map.resolve('discord:67890') // → 'telegram:12345'  (canonical = first linked)
+ */
+declare class IdentityMap {
+    private readonly links;
+    /**
+     * Build a namespaced platform ID.
+     */
+    static platformId(channel: string, userId: string): string;
+    /**
+     * Link two platform IDs together.
+     * The first ID becomes (or joins) the canonical identity for the group.
+     * Both IDs resolve to the same canonical ID after linking.
+     */
+    link(idA: string, idB: string): void;
+    /**
+     * Resolve a platform ID to its canonical ID.
+     * Returns the original ID if no link exists (it is its own canonical).
+     */
+    resolve(id: string): string;
+    /**
+     * Remove all links for a given platform ID.
+     * The canonical group still exists — only this ID is unlinked.
+     */
+    unlink(id: string): void;
+    /**
+     * True if the two IDs resolve to the same canonical identity.
+     */
+    areSameIdentity(idA: string, idB: string): boolean;
+}
+interface PermissionManagerOptions {
+    adminUsers?: string[];
+    defaultLevel?: PermissionLevel;
+    /** Cross-channel identity map. Shared across all channels in an IntegrationHub. */
+    identityMap?: IdentityMap;
+}
+declare class PermissionManager {
+    private readonly store;
+    private readonly adminSet;
+    private readonly defaultLevel;
+    private readonly identityMap;
+    constructor(store: PermissionStoreProtocol, options?: PermissionManagerOptions);
+    /**
+     * Get the effective permission level for a user.
+     * Resolves cross-channel identity before looking up the store.
+     */
+    getLevel(userId: string): Promise<PermissionLevel>;
+    setLevel(userId: string, level: PermissionLevel): Promise<void>;
+    deleteUser(userId: string): Promise<void>;
+    /**
+     * Throws PermissionDeniedError if user doesn't have required level.
+     */
+    checkPermission(userId: string, required: PermissionLevel): Promise<void>;
+    hasPermission(userId: string, required: PermissionLevel): Promise<boolean>;
+    /** Expose the identity map for cross-channel linking at the hub level. */
+    get identity(): IdentityMap;
+}
+
+declare class MessageDispatcher {
+    private readonly permissions;
+    private readonly logger;
+    private readonly handlers;
+    constructor(permissions: PermissionManager, logger: LoggerProtocol);
+    register(handler: HandlerProtocol): void;
+    dispatch(ctx: CommandContext): Promise<HandlerResult>;
+    getCommandList(minPermission?: PermissionLevel): CommandInfo[];
+    hasCommand(name: string): boolean;
+}
+
+declare abstract class BaseChannel implements ChannelProtocol {
+    readonly id: string;
+    readonly name: string;
+    protected readonly permissions: PermissionManager;
+    protected readonly dispatcher: MessageDispatcher;
+    protected readonly logger: LoggerProtocol;
+    protected constructor(id: string, name: string, permissions: PermissionManager, dispatcher: MessageDispatcher, logger: LoggerProtocol);
+    abstract start(): Promise<void>;
+    abstract stop(): Promise<void>;
+    abstract send(userId: string, message: OutgoingMessage): Promise<void>;
+    abstract onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
+    /**
+     * Process an incoming message: parse command → check permission → dispatch → send result.
+     * Channels call this from their platform event handler.
+     */
+    protected processMessage(msg: IncomingMessage): Promise<void>;
+    private formatErrorMessage;
+    protected logEvent(event: string, meta?: Record<string, unknown>): void;
+}
+
+interface SlackChannelOptions {
+    /** Bot OAuth token (xoxb-...) */
+    token: string;
+    /** App-level token for Socket Mode (xapp-...) */
+    appToken: string;
+    /** User IDs that get ADMIN permission automatically */
+    adminUsers?: string[];
+    /** Max characters before truncating outgoing messages. Default: 2800 */
+    maxMessageLength?: number;
+}
+declare class SlackChannel extends BaseChannel {
+    private app;
+    private readonly token;
+    private readonly appToken;
+    private readonly formatter;
+    private readonly maxLength;
+    private messageHandlers;
+    constructor(options: SlackChannelOptions, permissions: PermissionManager, dispatcher: MessageDispatcher, logger: LoggerProtocol);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(userId: string, message: OutgoingMessage): Promise<void>;
+    onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
+    private processMessageWithSay;
+    private buildText;
+    private truncate;
+}
+
+interface DiscordChannelOptions {
+    /** Bot token from Discord Developer Portal */
+    token: string;
+    /** Your Discord application/client ID */
+    clientId: string;
+    /** Guild ID for guild-scoped command registration (instant). Omit for global commands (up to 1h). */
+    guildId?: string;
+    /** User IDs (string) that get ADMIN permission automatically */
+    adminUsers?: string[];
+    /** Max characters before truncating outgoing messages. Default: 1900 */
+    maxMessageLength?: number;
+}
+declare class DiscordChannel extends BaseChannel {
+    private client;
+    private readonly token;
+    private readonly clientId;
+    private readonly guildId;
+    private readonly formatter;
+    private readonly maxLength;
+    private messageHandlers;
+    constructor(options: DiscordChannelOptions, permissions: PermissionManager, dispatcher: MessageDispatcher, logger: LoggerProtocol);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(userId: string, message: OutgoingMessage): Promise<void>;
+    onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
+    private handleInteraction;
+    private buildCommandText;
+    private extractArgs;
+    private outgoingToString;
+    private truncate;
+    private registerSlashCommands;
+}
+
+interface TelegramChannelOptions {
+    token: string;
+    /** User IDs (numeric as string) that get ADMIN permission automatically */
+    adminUsers?: string[];
+    /** Max length before truncating outgoing messages. Default: 4000 */
+    maxMessageLength?: number;
+}
+declare class TelegramChannel extends BaseChannel {
+    private bot;
+    private readonly token;
+    private readonly formatter;
+    private readonly maxLength;
+    private messageHandlers;
+    constructor(options: TelegramChannelOptions, permissions: PermissionManager, dispatcher: MessageDispatcher, logger: LoggerProtocol);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(userId: string, message: OutgoingMessage): Promise<void>;
+    onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
+    private normalizeContext;
+    private truncate;
+}
+
+declare const BotSettingsSchema: z.ZodObject<{
+    logLevel: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+    }>>;
+    allowedUsers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    maxOutputLength: z.ZodDefault<z.ZodNumber>;
+    debounceMs: z.ZodDefault<z.ZodNumber>;
+    defaultMachine: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type BotSettings = z.infer<typeof BotSettingsSchema>;
+declare function loadSettings(env?: NodeJS.ProcessEnv): BotSettings;
+
+type TelegramOptions = TelegramChannelOptions;
+type DiscordOptions = DiscordChannelOptions;
+type SlackOptions = SlackChannelOptions;
+interface HubOptions {
+    /** CMDOP cloud API key. If omitted, uses local IPC connection. */
+    apiKey?: string;
+    /** Connect to local IPC agent instead of cloud. Default: false unless apiKey is absent. */
+    local?: boolean;
+    /** Default machine hostname for all operations. */
+    defaultMachine?: string;
+    /** Permission store for user levels. Default: in-memory. */
+    permissionStore?: PermissionStoreProtocol;
+    /** Admin user IDs (always have ADMIN permission). */
+    adminUsers?: string[];
+    /** Logger instance. Default: stderr JSON logger at info level. */
+    logger?: LoggerProtocol;
+    /** Bot settings. Default: loaded from environment variables. */
+    settings?: Partial<BotSettings>;
+    /**
+     * Whether a channel start() failure should be treated as fatal (throws) or
+     * isolated (logs error and continues with remaining channels).
+     * Default: 'isolated'
+     */
+    channelStartMode?: 'strict' | 'isolated';
+}
+/** Per-channel runtime status */
+type ChannelStatus = 'pending' | 'running' | 'failed' | 'stopped';
+declare class IntegrationHub {
+    private readonly _client;
+    private readonly _logger;
+    private readonly _settings;
+    private readonly channels;
+    private readonly channelStatus;
+    private readonly _dispatcher;
+    private readonly _permissions;
+    private readonly channelStartMode;
+    private started;
+    private constructor();
+    /**
+     * Create and configure an IntegrationHub.
+     * Registers default handlers: exec, agent, files, help.
+     */
+    static create(options?: HubOptions): Promise<IntegrationHub>;
+    registerChannel(channel: ChannelProtocol): this;
+    /**
+     * Convenience: create and register a TelegramChannel without importing it manually.
+     * Requires `grammy` to be installed.
+     */
+    addTelegram(options: TelegramOptions): Promise<this>;
+    /**
+     * Convenience: create and register a DiscordChannel without importing it manually.
+     * Requires `discord.js`, `@discordjs/rest`, and `@discordjs/builders` to be installed.
+     */
+    addDiscord(options: DiscordOptions): Promise<this>;
+    /**
+     * Convenience: create and register a SlackChannel without importing it manually.
+     * Requires `@slack/bolt` and `@slack/web-api` to be installed.
+     */
+    addSlack(options: SlackOptions): Promise<this>;
+    registerHandler(handler: HandlerProtocol): this;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Link two platform-scoped user IDs to share the same permission identity.
+     *
+     * Example — a user's Telegram ID and Discord ID map to the same permissions:
+     *   hub.linkIdentities('telegram', '12345', 'discord', '67890');
+     *
+     * After linking, granting EXECUTE to the Telegram user also grants it to the
+     * Discord user (and vice versa), because both resolve to the same canonical ID.
+     */
+    linkIdentities(channelA: string, userIdA: string, channelB: string, userIdB: string): void;
+    /** Get a registered channel by its ID, or undefined if not found. */
+    getChannel(id: string): ChannelProtocol | undefined;
+    /** IDs of all registered channels. */
+    get channelIds(): string[];
+    /** Total number of registered channels. */
+    get channelCount(): number;
+    /** IDs of channels that started successfully. */
+    get runningChannelIds(): string[];
+    /** IDs of channels that failed to start. */
+    get failedChannelIds(): string[];
+    /** Runtime status of a specific channel. */
+    getChannelStatus(id: string): ChannelStatus | undefined;
+    /** Read-only access to the CMDOP client (for advanced usage in handlers). */
+    get cmdop(): CMDOPClient;
+    get settings(): BotSettings;
+    get isStarted(): boolean;
+    /** Read-only access to the permission manager (for programmatic grants). */
+    get permissions(): PermissionManager;
+}
+
+declare abstract class BaseHandler implements HandlerProtocol {
+    protected readonly client: CMDOPClient;
+    protected readonly logger: LoggerProtocol;
+    abstract readonly name: string;
+    abstract readonly description: string;
+    abstract readonly usage: string;
+    abstract readonly requiredPermission: PermissionLevel;
+    protected constructor(client: CMDOPClient, logger: LoggerProtocol);
+    abstract handle(ctx: CommandContext): Promise<HandlerResult>;
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+declare function createLogger(level?: LogLevel): LoggerProtocol;
+
+declare const UserSessionSchema: z.ZodObject<{
+    userId: z.ZodString;
+    currentMachine: z.ZodOptional<z.ZodString>;
+    lastCommand: z.ZodOptional<z.ZodString>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+type UserSession = z.infer<typeof UserSessionSchema>;
+declare const MachineSessionSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    hostname: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        online: "online";
+        offline: "offline";
+    }>;
+    connectedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+}, z.core.$strip>;
+type MachineSession = z.infer<typeof MachineSessionSchema>;
+
+/**
+ * TokenBuffer — debounced flush for streaming tokens to rate-limited platforms.
+ *
+ * Telegram/Discord enforce ~1 message edit per second per chat.
+ * Accumulate tokens and flush on a timer to avoid 429 errors.
+ */
+declare class TokenBuffer {
+    private readonly flush;
+    private readonly debounceMs;
+    private buffer;
+    private timer;
+    private stopped;
+    constructor(flush: (text: string) => Promise<void>, debounceMs?: number);
+    /**
+     * Append a token. Schedules a flush if not already scheduled.
+     * No-op after drain() is called.
+     */
+    append(token: string): void;
+    private scheduleFlush;
+    /**
+     * Cancel pending timer, flush remaining content immediately, stop accepting tokens.
+     * Always call this after the stream ends.
+     */
+    drain(): Promise<void>;
+    get bufferedLength(): number;
+    get isStopped(): boolean;
+}
+
+/**
+ * Slack native streaming via chat.startStream / appendStream / stopStream.
+ *
+ * Unlike Telegram/Discord (which need TokenBuffer debouncing), Slack provides
+ * first-class streaming primitives — no debounce required.
+ *
+ * The streaming protocol uses the message `ts` (timestamp) as the handle:
+ *   1. startStream() → returns { ts, channel }
+ *   2. appendStream({ channel, ts, markdown_text })
+ *   3. stopStream({ channel, ts })
+ *
+ * Usage:
+ *   const stream = await SlackStream.start(client, channel, threadTs);
+ *   await stream.append('token...');
+ *   await stream.finish();
+ */
+declare class SlackStream {
+    private readonly client;
+    private readonly channel;
+    private readonly ts;
+    private stopped;
+    private constructor();
+    /**
+     * Start a new streaming message in the given channel/thread.
+     */
+    static start(client: WebClient, channel: string, threadTs?: string): Promise<SlackStream>;
+    /**
+     * Append a token/chunk to the in-progress stream.
+     * Silently ignores appends after finish().
+     */
+    append(text: string): Promise<void>;
+    /**
+     * Stop the stream and finalise the message.
+     * Idempotent — safe to call multiple times.
+     */
+    finish(): Promise<void>;
+    get isFinished(): boolean;
+    /** The Slack message ts that identifies this stream. */
+    get messageTs(): string;
+}
+
+interface TerminalHandlerConfig {
+    maxOutputLength?: number;
+    defaultTimeoutMs?: number;
+}
+declare class TerminalHandler extends BaseHandler {
+    readonly name = "exec";
+    readonly description = "Execute a shell command on the remote machine";
+    readonly usage = "/exec <command>";
+    readonly requiredPermission: "EXECUTE";
+    private readonly maxOutput;
+    private readonly timeoutMs;
+    constructor(client: CMDOPClient, logger: LoggerProtocol, config?: TerminalHandlerConfig);
+    handle(ctx: CommandContext): Promise<HandlerResult>;
+    private formatResult;
+}
+
+interface AgentHandlerConfig {
+    timeoutSeconds?: number;
+    maxOutputLength?: number;
+}
+declare class AgentHandler extends BaseHandler {
+    readonly name = "agent";
+    readonly description = "Run an AI agent prompt on the remote machine";
+    readonly usage = "/agent <prompt>";
+    readonly requiredPermission: "EXECUTE";
+    private readonly timeout;
+    private readonly maxOutput;
+    constructor(client: CMDOPClient, logger: LoggerProtocol, config?: AgentHandlerConfig);
+    handle(ctx: CommandContext): Promise<HandlerResult>;
+}
+
+interface FilesHandlerConfig {
+    maxEntries?: number;
+    maxFileSize?: number;
+}
+declare class FilesHandler extends BaseHandler {
+    readonly name = "files";
+    readonly description = "List files in a directory on the remote machine";
+    readonly usage = "/files <path>";
+    readonly requiredPermission: "READ";
+    private readonly maxEntries;
+    constructor(client: CMDOPClient, logger: LoggerProtocol, config?: FilesHandlerConfig);
+    handle(ctx: CommandContext): Promise<HandlerResult>;
+    private handleList;
+    private handleRead;
+}
+
+interface HelpHandlerConfig {
+    getCommands: () => CommandInfo[];
+}
+declare class HelpHandler extends BaseHandler {
+    private readonly config;
+    readonly name = "help";
+    readonly description = "Show available commands and their usage";
+    readonly usage = "/help";
+    readonly requiredPermission: "NONE";
+    constructor(client: CMDOPClient, logger: LoggerProtocol, config: HelpHandlerConfig);
+    handle(_ctx: CommandContext): Promise<HandlerResult>;
+}
+
+interface DemoChannelOptions {
+    /** Called for every outgoing message (default: JSON to stdout) */
+    onOutput?: (text: string, message: OutgoingMessage) => void;
+}
+/**
+ * DemoChannel — stdio-based channel for local testing and CLI usage.
+ * No real platform; messages are injected programmatically via injectMessage().
+ */
+declare class DemoChannel extends BaseChannel {
+    private messageHandlers;
+    private readonly onOutput;
+    constructor(permissions: PermissionManager, dispatcher: MessageDispatcher, logger: LoggerProtocol, options?: DemoChannelOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(_userId: string, message: OutgoingMessage): Promise<void>;
+    onMessage(handler: (msg: IncomingMessage) => Promise<void>): void;
+    /**
+     * Inject a message as if it came from a real platform user.
+     * Primarily used in tests and CLI demos.
+     */
+    injectMessage(input: {
+        userId?: string;
+        text: string;
+    }): Promise<void>;
+}
+
+declare class TelegramFormatter implements FormatterProtocol {
+    /**
+     * Escape plain text for safe inclusion in MarkdownV2 messages.
+     */
+    formatText(text: string): string;
+    /**
+     * Wrap code in a triple-backtick code block.
+     * Truncates if over Telegram's limit.
+     */
+    formatCode(code: string, language?: string): string;
+    /**
+     * Format a BotError into a user-friendly Telegram message.
+     */
+    formatError(error: BotError): string;
+    /**
+     * Format a file listing entry line.
+     */
+    formatFileEntry(name: string, isDir: boolean, size?: number): string;
+    private escapeInline;
+}
+
+interface KeyboardAction {
+    label: string;
+    command: string;
+}
+/**
+ * Build a simple inline keyboard row from command shortcuts.
+ */
+declare function buildInlineKeyboard(actions: KeyboardAction[]): {
+    inline_keyboard: InlineKeyboardButton[][];
+};
+/**
+ * Standard machine selection keyboard.
+ */
+declare function buildMachineKeyboard(machines: string[]): {
+    inline_keyboard: InlineKeyboardButton[][];
+};
+
+declare class DiscordFormatter implements FormatterProtocol {
+    /**
+     * Escape Discord Markdown in user-supplied text.
+     * Escapes: _ * ~ ` | > \
+     */
+    formatText(text: string): string;
+    /**
+     * Wrap code in a triple-backtick code block.
+     * Truncates if over Discord's limit.
+     */
+    formatCode(code: string, language?: string): string;
+    /**
+     * Format a BotError into a user-friendly Discord message.
+     */
+    formatError(error: BotError): string;
+    /**
+     * Format a file listing entry line.
+     */
+    formatFileEntry(name: string, isDir: boolean, size?: number): string;
+}
+
+/**
+ * Discord slash command definitions for CMDOP bot.
+ *
+ * All commands use the Interactions API (slash commands).
+ * Message content intent is NOT required — preferred since 2022.
+ */
+declare const DISCORD_COMMANDS: RESTPostAPIChatInputApplicationCommandsJSONBody[];
+/** All slash command names — used to build the prefix-based text fallback */
+declare const DISCORD_COMMAND_NAMES: string[];
+
+/**
+ * Slack mrkdwn formatter.
+ *
+ * Slack uses its own "mrkdwn" dialect (not standard Markdown).
+ * Bold: *text*   Italic: _text_   Code: `text`   Code block: ```text```
+ * No escaping of . - ! etc. Special chars are: * _ ` & < >
+ */
+declare const SLACK_MAX_TEXT_LENGTH = 3000;
+declare class SlackFormatter implements FormatterProtocol {
+    /**
+     * Escape mrkdwn special characters in plain text.
+     * Slack requires escaping: & < >
+     * Ampersand must be escaped first to avoid double-escaping.
+     */
+    formatText(text: string): string;
+    /**
+     * Wrap code in a triple-backtick code block.
+     * Truncates if over Slack's limit.
+     */
+    formatCode(code: string, language?: string): string;
+    /**
+     * Format a BotError into a user-friendly Slack mrkdwn message.
+     */
+    formatError(error: BotError): string;
+    /**
+     * Format a file listing entry line.
+     */
+    formatFileEntry(name: string, isDir: boolean, size?: number): string;
+}
+
+/**
+ * Slack Block Kit builders for structured CMDOP output.
+ *
+ * Blocks are the Slack equivalent of Discord embeds.
+ * Used for file listings, machine tables, and error cards.
+ *
+ * Reference: https://api.slack.com/block-kit
+ */
+interface SlackBlock {
+    type: string;
+    [key: string]: unknown;
+}
+declare function sectionBlock(text: string): SlackBlock;
+declare function headerBlock(text: string): SlackBlock;
+declare function dividerBlock(): SlackBlock;
+declare function contextBlock(text: string): SlackBlock;
+interface FileEntry {
+    name: string;
+    isDir: boolean;
+    size?: number;
+}
+/**
+ * Build a Block Kit representation of a file listing.
+ * Splits into chunks of up to `chunkSize` entries per section block
+ * to respect Slack's 3000-char section limit.
+ */
+declare function fileListBlocks(path: string, entries: FileEntry[], chunkSize?: number): SlackBlock[];
+interface MachineStatus {
+    hostname: string;
+    online: boolean;
+    label?: string;
+}
+/**
+ * Build a Block Kit machine status table.
+ */
+declare function machineStatusBlocks(machines: MachineStatus[]): SlackBlock[];
+/**
+ * Build a Block Kit error card with context.
+ */
+declare function errorBlocks(message: string, detail?: string): SlackBlock[];
+
+export { AgentHandler, type AgentHandlerConfig, type Attachment, AttachmentSchema, BaseChannel, BaseHandler, BotError, type BotSettings, BotSettingsSchema, type BotUser, BotUserSchema, CMDOPError, CMDOPTimeoutError, ChannelError, type ChannelProtocol, type ChannelStatus, type CodeMessage, CodeMessageSchema, CommandArgsError, type CommandContext, type CommandInfo, CommandNotFoundError, ConfigError, DISCORD_COMMANDS, DISCORD_COMMAND_NAMES, DemoChannel, type DemoChannelOptions, DiscordChannel, type DiscordChannelOptions, DiscordError, DiscordFormatter, type ErrorMessage, ErrorMessageSchema, ExecutionTimeoutError, type FileEntry, FilesHandler, type FilesHandlerConfig, type FormatterProtocol, HandlerError, type HandlerProtocol, type HandlerResult, HelpHandler, type HelpHandlerConfig, type HubOptions, IdentityMap, InMemoryPermissionStore, type IncomingMessage, IncomingMessageSchema, IntegrationHub, type KeyboardAction, type LoggerProtocol, MachineNotFoundError, MachineOfflineError, type MachineSession, MachineSessionSchema, type MachineStatus, MessageDispatcher, type OutgoingMessage, OutgoingMessageSchema, PERMISSION_ORDER, type ParsedCommand, ParsedCommandSchema, PermissionDeniedError, type PermissionLevel, PermissionLevelSchema, PermissionManager, type PermissionStoreProtocol, RateLimitError, SLACK_MAX_TEXT_LENGTH, type SlackBlock, SlackChannel, type SlackChannelOptions, SlackError, SlackFormatter, SlackStream, TeamsError, TelegramChannel, type TelegramChannelOptions, TelegramError, TelegramFormatter, TerminalHandler, type TerminalHandlerConfig, type TextMessage, TextMessageSchema, TokenBuffer, type UserIdentity, UserIdentitySchema, type UserSession, UserSessionSchema, buildInlineKeyboard, buildMachineKeyboard, contextBlock, createLogger, dividerBlock, err, errorBlocks, fileListBlocks, headerBlock, loadSettings, machineStatusBlocks, ok, parseCommand, sectionBlock };