@openacp/cli 0.6.10 → 2026.326.3

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import pino from 'pino';
-import { z } from 'zod';
+import * as zod from 'zod';
+import { z, ZodSchema } from 'zod';
 import { EventEmitter } from 'node:events';
 import { Readable, Writable } from 'node:stream';
-import { PromptResponse } from '@agentclientprotocol/sdk';
+import { SetSessionConfigOptionResponse, ListSessionsResponse, LoadSessionResponse, ForkSessionResponse, PromptResponse as PromptResponse$1 } from '@agentclientprotocol/sdk';
 import * as http from 'node:http';
 
 interface Attachment {
@@ -21,7 +22,7 @@ interface IncomingMessage {
     attachments?: Attachment[];
 }
 interface OutgoingMessage {
-    type: "text" | "thought" | "tool_call" | "tool_update" | "plan" | "usage" | "session_end" | "error" | "attachment" | "system_message";
+    type: "text" | "thought" | "tool_call" | "tool_update" | "plan" | "usage" | "session_end" | "error" | "attachment" | "system_message" | "mode_change" | "config_update" | "model_update" | "user_replay" | "resource" | "resource_link";
     text: string;
     metadata?: Record<string, unknown>;
     attachment?: Attachment;
@@ -63,6 +64,7 @@ type AgentEvent = {
     content?: unknown;
     locations?: unknown;
     rawInput?: unknown;
+    rawOutput?: unknown;
     meta?: unknown;
 } | {
     type: "tool_update";
@@ -73,6 +75,7 @@ type AgentEvent = {
     content?: unknown;
     locations?: unknown;
     rawInput?: unknown;
+    rawOutput?: unknown;
     meta?: unknown;
 } | {
     type: "plan";
@@ -105,6 +108,38 @@ type AgentEvent = {
 } | {
     type: "system_message";
     message: string;
+} | {
+    type: "session_info_update";
+    title?: string;
+    updatedAt?: string;
+    _meta?: Record<string, unknown>;
+} | {
+    type: "current_mode_update";
+    modeId: string;
+} | {
+    type: "config_option_update";
+    options: ConfigOption[];
+} | {
+    type: "model_update";
+    modelId: string;
+} | {
+    type: "user_message_chunk";
+    content: string;
+} | {
+    type: "resource_content";
+    uri: string;
+    name: string;
+    text?: string;
+    blob?: string;
+    mimeType?: string;
+} | {
+    type: "resource_link";
+    uri: string;
+    name: string;
+    mimeType?: string;
+    title?: string;
+    description?: string;
+    size?: number;
 };
 interface PlanEntry {
     content: string;
@@ -238,6 +273,160 @@ interface DiscordPlatformData {
     threadId: string;
     skillMsgId?: string;
 }
+interface SessionMode {
+    id: string;
+    name: string;
+    description?: string;
+}
+interface SessionModeState {
+    currentModeId: string;
+    availableModes: SessionMode[];
+}
+interface ConfigSelectChoice {
+    value: string;
+    label: string;
+    description?: string;
+}
+interface ConfigSelectGroup {
+    group: string;
+    name: string;
+    options: ConfigSelectChoice[];
+}
+type ConfigOption = {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    type: "select";
+    currentValue: string;
+    options: (ConfigSelectChoice | ConfigSelectGroup)[];
+    _meta?: Record<string, unknown>;
+} | {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    type: "boolean";
+    currentValue: boolean;
+    _meta?: Record<string, unknown>;
+};
+type SetConfigOptionValue = {
+    type: "select";
+    value: string;
+} | {
+    type: "boolean";
+    value: boolean;
+};
+interface ModelInfo {
+    id: string;
+    name: string;
+    description?: string;
+}
+interface SessionModelState {
+    currentModelId: string;
+    availableModels: ModelInfo[];
+}
+interface AgentCapabilities {
+    name: string;
+    title?: string;
+    version?: string;
+    loadSession?: boolean;
+    promptCapabilities?: {
+        image?: boolean;
+        audio?: boolean;
+        embeddedContext?: boolean;
+    };
+    sessionCapabilities?: {
+        list?: boolean;
+        fork?: boolean;
+        close?: boolean;
+    };
+    mcp?: {
+        http?: boolean;
+        sse?: boolean;
+    };
+    authMethods?: AuthMethod[];
+}
+interface NewSessionResponse {
+    sessionId: string;
+    modes?: SessionModeState;
+    configOptions?: ConfigOption[];
+    models?: SessionModelState;
+}
+type AuthMethod = {
+    type: "agent";
+} | {
+    type: "env_var";
+    name: string;
+    description?: string;
+} | {
+    type: "terminal";
+};
+interface AuthenticateRequest {
+    methodId: string;
+}
+type StopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
+interface PromptResponse {
+    stopReason: StopReason;
+    _meta?: Record<string, unknown>;
+}
+type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+    uri?: string;
+} | {
+    type: "audio";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        text?: string;
+        blob?: string;
+        mimeType?: string;
+    };
+} | {
+    type: "resource_link";
+    uri: string;
+    name: string;
+    mimeType?: string;
+    title?: string;
+    description?: string;
+    size?: number;
+};
+interface SessionListItem {
+    sessionId: string;
+    title?: string;
+    createdAt: string;
+    updatedAt?: string;
+    _meta?: Record<string, unknown>;
+}
+interface SessionListResponse {
+    sessions: SessionListItem[];
+    nextCursor?: string;
+}
+type McpServerConfig = {
+    type?: "stdio";
+    name: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+} | {
+    type: "http";
+    name: string;
+    url: string;
+    headers?: Record<string, string>;
+} | {
+    type: "sse";
+    name: string;
+    url: string;
+    headers?: Record<string, string>;
+};
 
 declare const PLUGINS_DIR: string;
 declare const LoggingSchema: z.ZodDefault<z.ZodObject<{
@@ -875,7 +1064,7 @@ declare const ConfigSchema: z.ZodObject<{
 }>;
 type Config = z.infer<typeof ConfigSchema>;
 declare function expandHome(p: string): string;
-declare class ConfigManager extends EventEmitter {
+declare class ConfigManager$1 extends EventEmitter {
     private config;
     private configPath;
     constructor();
@@ -890,7 +1079,7 @@ declare class ConfigManager extends EventEmitter {
     private deepMerge;
 }
 
-type Logger = pino.Logger;
+type Logger$1 = pino.Logger;
 declare const log: {
     info: (...args: unknown[]) => void;
     warn: (...args: unknown[]) => void;
@@ -899,14 +1088,14 @@ declare const log: {
     fatal: (...args: unknown[]) => void;
     child: (bindings: pino.Bindings) => pino.Logger<never, boolean>;
 };
-declare function initLogger(config: LoggingConfig): Logger;
+declare function initLogger(config: LoggingConfig): Logger$1;
 /** Change log level at runtime. Pino transport targets respect parent level changes automatically. */
 declare function setLogLevel(level: string): void;
 declare function createChildLogger(context: {
     module: string;
     [key: string]: unknown;
-}): Logger;
-declare function createSessionLogger(sessionId: string, parentLogger: Logger): Logger;
+}): Logger$1;
+declare function createSessionLogger(sessionId: string, parentLogger: Logger$1): Logger$1;
 declare function shutdownLogger(): Promise<void>;
 declare function cleanupOldSessionLogs(retentionDays: number): Promise<void>;
 
@@ -914,7 +1103,17 @@ interface ChannelConfig {
     enabled: boolean;
     [key: string]: unknown;
 }
+interface AdapterCapabilities {
+    streaming: boolean;
+    richFormatting: boolean;
+    threads: boolean;
+    reactions: boolean;
+    fileUpload: boolean;
+    voice: boolean;
+}
 interface IChannelAdapter {
+    readonly name: string;
+    readonly capabilities: AdapterCapabilities;
     start(): Promise<void>;
     stop(): Promise<void>;
     sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>;
@@ -922,17 +1121,21 @@ interface IChannelAdapter {
     sendNotification(notification: NotificationMessage): Promise<void>;
     createSessionThread(sessionId: string, name: string): Promise<string>;
     renameSessionThread(sessionId: string, newName: string): Promise<void>;
-    deleteSessionThread(sessionId: string): Promise<void>;
-    sendSkillCommands(sessionId: string, commands: AgentCommand[]): Promise<void>;
-    cleanupSkillCommands(sessionId: string): Promise<void>;
+    deleteSessionThread?(sessionId: string): Promise<void>;
+    archiveSessionTopic?(sessionId: string): Promise<void>;
+    sendSkillCommands?(sessionId: string, commands: AgentCommand[]): Promise<void>;
+    cleanupSkillCommands?(sessionId: string): Promise<void>;
 }
 /**
  * Base class providing default no-op implementations for optional methods.
  * Adapters can extend this or implement IChannelAdapter directly.
+ * @deprecated Use MessagingAdapter or StreamAdapter instead. Kept for backward compat during migration.
  */
 declare abstract class ChannelAdapter<TCore = unknown> implements IChannelAdapter {
     readonly core: TCore;
     protected config: ChannelConfig;
+    abstract readonly name: string;
+    readonly capabilities: AdapterCapabilities;
     constructor(core: TCore, config: ChannelConfig);
     abstract start(): Promise<void>;
     abstract stop(): Promise<void>;
@@ -947,13 +1150,6 @@ declare abstract class ChannelAdapter<TCore = unknown> implements IChannelAdapte
     archiveSessionTopic(_sessionId: string): Promise<void>;
 }
 
-declare class NotificationManager {
-    private adapters;
-    constructor(adapters: Map<string, ChannelAdapter>);
-    notify(channelId: string, notification: NotificationMessage): Promise<void>;
-    notifyAll(notification: NotificationMessage): Promise<void>;
-}
-
 declare function nodeToWebWritable(nodeStream: Writable): WritableStream<Uint8Array>;
 declare function nodeToWebReadable(nodeStream: Readable): ReadableStream<Uint8Array>;
 
@@ -1000,6 +1196,37 @@ declare class TypedEmitter<T extends Record<string & keyof T, (...args: any[]) =
     private deliver;
 }
 
+interface ErrorBudgetConfig {
+    maxErrors: number;
+    windowMs: number;
+}
+declare class ErrorTracker {
+    private errors;
+    private disabled;
+    private exempt;
+    private config;
+    onDisabled?: (pluginName: string, reason: string) => void;
+    constructor(config?: Partial<ErrorBudgetConfig>);
+    increment(pluginName: string): void;
+    isDisabled(pluginName: string): boolean;
+    reset(pluginName: string): void;
+    setExempt(pluginName: string): void;
+}
+
+declare class MiddlewareChain {
+    private chains;
+    private errorHandler?;
+    private errorTracker?;
+    add(hook: string, pluginName: string, opts: {
+        priority?: number;
+        handler: Function;
+    }): void;
+    execute<T>(hook: string, payload: T, coreHandler: (p: T) => T | Promise<T>): Promise<T | null>;
+    removeAll(pluginName: string): void;
+    setErrorHandler(fn: (pluginName: string, error: Error) => void): void;
+    setErrorTracker(tracker: ErrorTracker): void;
+}
+
 interface AgentInstanceEvents {
     agent_event: (event: AgentEvent) => void;
 }
@@ -1007,21 +1234,31 @@ declare class AgentInstance extends TypedEmitter<AgentInstanceEvents> {
     private connection;
     private child;
     private stderrCapture;
-    private terminals;
+    private terminalManager;
+    private static mcpManager;
     sessionId: string;
     agentName: string;
     promptCapabilities?: {
         image?: boolean;
         audio?: boolean;
     };
+    middlewareChain?: MiddlewareChain;
     onPermissionRequest: (request: PermissionRequest) => Promise<string>;
     private constructor();
     private static spawnSubprocess;
     private setupCrashDetection;
-    static spawn(agentDef: AgentDefinition, workingDirectory: string): Promise<AgentInstance>;
-    static resume(agentDef: AgentDefinition, workingDirectory: string, agentSessionId: string): Promise<AgentInstance>;
+    static spawn(agentDef: AgentDefinition, workingDirectory: string, mcpServers?: McpServerConfig[]): Promise<AgentInstance>;
+    static resume(agentDef: AgentDefinition, workingDirectory: string, agentSessionId: string, mcpServers?: McpServerConfig[]): Promise<AgentInstance>;
     private createClient;
-    prompt(text: string, attachments?: Attachment[]): Promise<PromptResponse>;
+    setMode(modeId: string): Promise<void>;
+    setConfigOption(configId: string, value: SetConfigOptionValue): Promise<SetSessionConfigOptionResponse>;
+    setModel(modelId: string): Promise<void>;
+    listSessions(cwd?: string, cursor?: string): Promise<ListSessionsResponse>;
+    loadSession(sessionId: string, cwd: string, mcpServers?: McpServerConfig[]): Promise<LoadSessionResponse>;
+    authenticate(methodId: string): Promise<void>;
+    forkSession(sessionId: string, cwd: string, mcpServers?: McpServerConfig[]): Promise<ForkSessionResponse>;
+    closeSession(sessionId: string): Promise<void>;
+    prompt(text: string, attachments?: Attachment[]): Promise<PromptResponse$1>;
     cancel(): Promise<void>;
     destroy(): Promise<void>;
 }
@@ -1120,11 +1357,11 @@ interface TTSResult {
     audioBuffer: Buffer;
     mimeType: string;
 }
-interface STTProvider {
+interface STTProvider$1 {
     readonly name: string;
     transcribe(audioBuffer: Buffer, mimeType: string, options?: STTOptions): Promise<STTResult>;
 }
-interface TTSProvider {
+interface TTSProvider$1 {
     readonly name: string;
     synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
 }
@@ -1144,21 +1381,30 @@ interface SpeechServiceConfig {
     };
 }
 
+type ProviderFactory = (config: SpeechServiceConfig) => {
+    stt: Map<string, STTProvider$1>;
+    tts: Map<string, TTSProvider$1>;
+};
 declare class SpeechService {
     private config;
     private sttProviders;
     private ttsProviders;
+    private providerFactory?;
     constructor(config: SpeechServiceConfig);
-    registerSTTProvider(name: string, provider: STTProvider): void;
-    registerTTSProvider(name: string, provider: TTSProvider): void;
+    /** Set a factory function that can recreate providers from config (for hot-reload) */
+    setProviderFactory(factory: ProviderFactory): void;
+    registerSTTProvider(name: string, provider: STTProvider$1): void;
+    registerTTSProvider(name: string, provider: TTSProvider$1): void;
     isSTTAvailable(): boolean;
     isTTSAvailable(): boolean;
     transcribe(audioBuffer: Buffer, mimeType: string, options?: STTOptions): Promise<STTResult>;
     synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
     updateConfig(config: SpeechServiceConfig): void;
+    /** Re-create all providers from current config using the registered factory */
+    refreshProviders(newConfig: SpeechServiceConfig): void;
 }
 
-declare class GroqSTT implements STTProvider {
+declare class GroqSTT implements STTProvider$1 {
     private apiKey;
     private defaultModel;
     readonly name = "groq";
@@ -1187,9 +1433,16 @@ declare class Session extends TypedEmitter<SessionEvents> {
     createdAt: Date;
     voiceMode: "off" | "next" | "on";
     dangerousMode: boolean;
+    currentMode?: string;
+    availableModes: SessionMode[];
+    configOptions: ConfigOption[];
+    currentModel?: string;
+    availableModels: ModelInfo[];
+    agentCapabilities?: AgentCapabilities;
     archiving: boolean;
     promptCount: number;
-    log: Logger;
+    log: Logger$1;
+    middlewareChain?: MiddlewareChain;
     readonly permissionGate: PermissionGate;
     private readonly queue;
     private speechService?;
@@ -1226,6 +1479,17 @@ declare class Session extends TypedEmitter<SessionEvents> {
     /** Fire-and-forget warm-up: primes model cache while user types their first message */
     warmup(): Promise<void>;
     private runWarmup;
+    setInitialAcpState(state: {
+        modes?: SessionModeState | null;
+        configOptions?: ConfigOption[] | null;
+        models?: SessionModelState | null;
+        agentCapabilities?: AgentCapabilities | null;
+    }): void;
+    /** Set session name explicitly and emit 'named' event */
+    setName(name: string): void;
+    updateMode(modeId: string): Promise<void>;
+    updateConfigOptions(options: ConfigOption[]): Promise<void>;
+    updateModel(modelId: string): Promise<void>;
     /** Cancel the current prompt and clear the queue. Stays in active state. */
     abortPrompt(): Promise<void>;
     destroy(): Promise<void>;
@@ -1249,130 +1513,521 @@ declare class PromptQueue {
     get isProcessing(): boolean;
 }
 
-interface TunnelEntry {
-    port: number;
-    type: 'system' | 'user';
-    provider: string;
-    label?: string;
-    publicUrl?: string;
-    sessionId?: string;
-    status: 'stopped' | 'starting' | 'active' | 'failed';
-    createdAt: string;
+type PluginPermission = 'events:read' | 'events:emit' | 'services:register' | 'services:use' | 'middleware:register' | 'commands:register' | 'storage:read' | 'storage:write' | 'kernel:access';
+interface OpenACPPlugin {
+    /** Unique identifier, e.g., '@openacp/security' */
+    name: string;
+    /** Semver version */
+    version: string;
+    /** Human-readable description */
+    description?: string;
+    /** Required plugin dependencies — loaded before this plugin's setup() */
+    pluginDependencies?: Record<string, string>;
+    /** Optional dependencies — used if available, gracefully degrade if not */
+    optionalPluginDependencies?: Record<string, string>;
+    /** Override a built-in plugin (replaces it entirely) */
+    overrides?: string;
+    /** Required permissions — PluginContext enforces these */
+    permissions?: PluginPermission[];
+    /** Called during startup in dependency order */
+    setup(ctx: PluginContext): Promise<void>;
+    /** Called during shutdown in reverse order. 10s timeout. */
+    teardown?(): Promise<void>;
+    install?(ctx: InstallContext): Promise<void>;
+    uninstall?(ctx: InstallContext, opts: {
+        purge: boolean;
+    }): Promise<void>;
+    configure?(ctx: InstallContext): Promise<void>;
+    migrate?(ctx: MigrateContext, oldSettings: unknown, oldVersion: string): Promise<unknown>;
+    settingsSchema?: zod.ZodSchema;
+    essential?: boolean;
+}
+interface PluginStorage {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(): Promise<string[]>;
+    getDataDir(): string;
+}
+interface SettingsAPI {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    getAll(): Promise<Record<string, unknown>>;
+    setAll(settings: Record<string, unknown>): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+}
+interface TerminalIO {
+    text(opts: {
+        message: string;
+        placeholder?: string;
+        defaultValue?: string;
+        validate?: (value: string) => string | undefined;
+    }): Promise<string>;
+    select<T>(opts: {
+        message: string;
+        options: {
+            value: T;
+            label: string;
+            hint?: string;
+        }[];
+    }): Promise<T>;
+    confirm(opts: {
+        message: string;
+        initialValue?: boolean;
+    }): Promise<boolean>;
+    password(opts: {
+        message: string;
+        validate?: (value: string) => string | undefined;
+    }): Promise<string>;
+    multiselect<T>(opts: {
+        message: string;
+        options: {
+            value: T;
+            label: string;
+            hint?: string;
+        }[];
+        required?: boolean;
+    }): Promise<T[]>;
+    log: {
+        info(message: string): void;
+        success(message: string): void;
+        warning(message: string): void;
+        error(message: string): void;
+        step(message: string): void;
+    };
+    spinner(): {
+        start(message: string): void;
+        stop(message?: string): void;
+        fail(message?: string): void;
+    };
+    note(message: string, title?: string): void;
+    cancel(message?: string): void;
+}
+interface InstallContext {
+    pluginName: string;
+    terminal: TerminalIO;
+    settings: SettingsAPI;
+    legacyConfig?: Record<string, unknown>;
+    dataDir: string;
+    log: Logger;
 }
-
-interface ViewerEntry {
-    id: string;
-    type: 'file' | 'diff';
-    filePath?: string;
-    content: string;
-    oldContent?: string;
-    language?: string;
-    sessionId: string;
-    workingDirectory: string;
-    createdAt: number;
-    expiresAt: number;
+interface MigrateContext {
+    pluginName: string;
+    settings: SettingsAPI;
+    log: Logger;
 }
-declare class ViewerStore {
-    private entries;
-    private cleanupTimer;
-    private ttlMs;
-    constructor(ttlMinutes?: number);
-    storeFile(sessionId: string, filePath: string, content: string, workingDirectory: string): string | null;
-    storeDiff(sessionId: string, filePath: string, oldContent: string, newContent: string, workingDirectory: string): string | null;
-    get(id: string): ViewerEntry | undefined;
-    private cleanup;
-    private isPathAllowed;
-    private detectLanguage;
-    destroy(): void;
+type CommandResponse = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'menu';
+    title: string;
+    options: MenuOption[];
+} | {
+    type: 'list';
+    title: string;
+    items: ListItem[];
+} | {
+    type: 'confirm';
+    question: string;
+    onYes: string;
+    onNo: string;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'silent';
+};
+interface MenuOption {
+    label: string;
+    command: string;
+    hint?: string;
 }
-
-declare class TunnelService {
-    private registry;
-    private store;
-    private server;
-    private config;
-    private systemPort;
-    constructor(config: TunnelConfig);
-    start(): Promise<string>;
-    stop(): Promise<void>;
-    addTunnel(port: number, opts?: {
-        label?: string;
-        sessionId?: string;
-    }): Promise<TunnelEntry>;
-    stopTunnel(port: number): Promise<void>;
-    stopAllUser(): Promise<void>;
-    stopBySession(sessionId: string): Promise<TunnelEntry[]>;
-    listTunnels(): TunnelEntry[];
-    getTunnel(port: number): TunnelEntry | null;
-    getPublicUrl(): string;
-    getStore(): ViewerStore;
-    fileUrl(entryId: string): string;
-    diffUrl(entryId: string): string;
+interface ListItem {
+    label: string;
+    detail?: string;
+}
+interface CommandArgs {
+    /** Raw argument string after command name */
+    raw: string;
+    /** Parsed key/value options (e.g., --flag value) */
+    options?: Record<string, string>;
+    /** Session ID where command was invoked (null if from notification/system topic) */
+    sessionId: string | null;
+    /** Channel ID ('telegram', 'discord', 'slack') */
+    channelId: string;
+    /** User ID who invoked the command */
+    userId: string;
+    /** Reply helper — sends message to the topic where command was invoked */
+    reply(content: string | CommandResponse | OutgoingMessage): Promise<void>;
+    /** Direct access to OpenACPCore instance. Available when 'kernel:access' permission is granted. */
+    coreAccess?: CoreAccess;
 }
-
-declare class MessageTransformer {
-    private tunnelService?;
-    constructor(tunnelService?: TunnelService | undefined);
-    transform(event: AgentEvent, sessionContext?: {
-        id: string;
-        workingDirectory: string;
-    }): OutgoingMessage;
-    private enrichWithViewerLinks;
+interface CommandDef {
+    /** Command name without slash, e.g., 'context' for /context */
+    name: string;
+    /** Short description shown in command list */
+    description: string;
+    /** Usage pattern, e.g., '<session-number>' */
+    usage?: string;
+    /** Whether this is a built-in system command or registered by a plugin */
+    category: 'system' | 'plugin';
+    /** Plugin that registered this command (set automatically by plugin manager) */
+    pluginName?: string;
+    /** Handler function */
+    handler(args: CommandArgs): Promise<CommandResponse | void>;
+}
+interface SessionManager$1 {
+    [key: string]: unknown;
 }
-
-declare class FileService {
-    private baseDir;
-    constructor(baseDir: string);
-    saveFile(sessionId: string, fileName: string, data: Buffer, mimeType: string): Promise<Attachment>;
-    resolveFile(filePath: string): Promise<Attachment | null>;
-    /**
-     * Convert OGG Opus audio to WAV format.
-     * Telegram voice messages use OGG Opus which many AI agents can't read.
-     */
-    convertOggToWav(oggData: Buffer): Promise<Buffer>;
-    static extensionFromMime(mimeType: string): string;
+interface ConfigManager {
+    [key: string]: unknown;
 }
-
-interface SessionStore {
-    save(record: SessionRecord): Promise<void>;
-    get(sessionId: string): SessionRecord | undefined;
-    findByPlatform(channelId: string, predicate: (platform: Record<string, unknown>) => boolean): SessionRecord | undefined;
-    findByAgentSessionId(agentSessionId: string): SessionRecord | undefined;
-    list(channelId?: string): SessionRecord[];
-    remove(sessionId: string): Promise<void>;
+interface EventBus$1 {
+    [key: string]: unknown;
 }
-
-interface EventBusEvents {
-    "session:created": (data: {
+/**
+ * Typed view of the OpenACPCore instance exposed to plugins via ctx.core.
+ * Plugins that need kernel:access should cast ctx.core to this interface
+ * instead of using `as any`. Only includes fields plugins actually need.
+ */
+interface CoreAccess {
+    configManager: ConfigManager;
+    sessionManager: SessionManager$1;
+    adapters: Map<string, IChannelAdapter>;
+}
+interface Logger {
+    trace(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    fatal(msg: string, ...args: unknown[]): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+interface PluginContext {
+    pluginName: string;
+    pluginConfig: Record<string, unknown>;
+    /** Subscribe to events. Auto-cleaned on teardown. Requires 'events:read'. */
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    /** Emit custom events. Event names MUST be prefixed with plugin name. Requires 'events:emit'. */
+    emit(event: string, payload: unknown): void;
+    /** Register middleware. Requires 'middleware:register'. */
+    registerMiddleware<H extends MiddlewareHook>(hook: H, opts: MiddlewareOptions<MiddlewarePayloadMap[H]>): void;
+    /** Provide a service. Requires 'services:register'. */
+    registerService<T>(name: string, implementation: T): void;
+    /** Consume a service. Requires 'services:use'. */
+    getService<T>(name: string): T | undefined;
+    /** Register slash command. Requires 'commands:register'. */
+    registerCommand(def: CommandDef): void;
+    /** Plugin-scoped storage. Requires 'storage:read' and/or 'storage:write'. */
+    storage: PluginStorage;
+    /** Plugin-scoped logger. Always available (no permission needed). */
+    log: Logger;
+    /**
+     * Send message to a session. Requires 'services:use'.
+     *
+     * Routing: sessionId → lookup session → find adapter for session's channelId
+     *          → [HOOK: message:outgoing] → adapter.sendMessage()
+     */
+    sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>;
+    sessions: SessionManager$1;
+    config: ConfigManager;
+    eventBus: EventBus$1;
+    /** Direct access to OpenACPCore instance. Requires 'kernel:access'. */
+    core: unknown;
+}
+interface MiddlewarePayloadMap {
+    'message:incoming': {
+        channelId: string;
+        threadId: string;
+        userId: string;
+        text: string;
+        attachments?: Attachment[];
+    };
+    'message:outgoing': {
         sessionId: string;
-        agent: string;
-        status: SessionStatus;
-    }) => void;
-    "session:updated": (data: {
+        message: OutgoingMessage;
+    };
+    'agent:beforePrompt': {
         sessionId: string;
-        status?: SessionStatus;
-        name?: string;
-        dangerousMode?: boolean;
-    }) => void;
-    "session:deleted": (data: {
+        text: string;
+        attachments?: Attachment[];
+    };
+    'agent:beforeEvent': {
         sessionId: string;
-    }) => void;
-    "agent:event": (data: {
+        event: AgentEvent;
+    };
+    'agent:afterEvent': {
         sessionId: string;
         event: AgentEvent;
-    }) => void;
-    "permission:request": (data: {
+        outgoingMessage: OutgoingMessage;
+    };
+    'turn:start': {
         sessionId: string;
-        permission: PermissionRequest;
-    }) => void;
-}
-declare class EventBus extends TypedEmitter<EventBusEvents> {
-}
+        promptText: string;
+        promptNumber: number;
+    };
+    'turn:end': {
+        sessionId: string;
+        stopReason: StopReason;
+        durationMs: number;
+    };
+    'fs:beforeRead': {
+        sessionId: string;
+        path: string;
+        line?: number;
+        limit?: number;
+    };
+    'fs:beforeWrite': {
+        sessionId: string;
+        path: string;
+        content: string;
+    };
+    'terminal:beforeCreate': {
+        sessionId: string;
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+        cwd?: string;
+    };
+    'terminal:afterExit': {
+        sessionId: string;
+        terminalId: string;
+        command: string;
+        exitCode: number;
+        durationMs: number;
+    };
+    'permission:beforeRequest': {
+        sessionId: string;
+        request: PermissionRequest;
+        autoResolve?: string;
+    };
+    'permission:afterResolve': {
+        sessionId: string;
+        requestId: string;
+        decision: string;
+        userId: string;
+        durationMs: number;
+    };
+    'session:beforeCreate': {
+        agentName: string;
+        workingDir: string;
+        userId: string;
+        channelId: string;
+        threadId: string;
+    };
+    'session:afterDestroy': {
+        sessionId: string;
+        reason: string;
+        durationMs: number;
+        promptCount: number;
+    };
+    'mode:beforeChange': {
+        sessionId: string;
+        fromMode: string | undefined;
+        toMode: string;
+    };
+    'config:beforeChange': {
+        sessionId: string;
+        configId: string;
+        oldValue: unknown;
+        newValue: unknown;
+    };
+    'model:beforeChange': {
+        sessionId: string;
+        fromModel: string | undefined;
+        toModel: string;
+    };
+    'agent:beforeCancel': {
+        sessionId: string;
+        reason?: string;
+    };
+}
+type MiddlewareHook = keyof MiddlewarePayloadMap;
+type MiddlewareFn<T> = (payload: T, next: () => Promise<T>) => Promise<T | null>;
+interface MiddlewareOptions<T> {
+    /** Override execution order within same dependency level. Lower = earlier. */
+    priority?: number;
+    /** The middleware handler */
+    handler: MiddlewareFn<T>;
+}
+interface SecurityService {
+    checkAccess(userId: string): Promise<{
+        allowed: boolean;
+        reason?: string;
+    }>;
+    checkSessionLimit(userId: string): Promise<{
+        allowed: boolean;
+        reason?: string;
+    }>;
+    getUserRole(userId: string): Promise<'admin' | 'user' | 'blocked'>;
+}
+interface FileServiceInterface {
+    saveFile(sessionId: string, fileName: string, data: Buffer, mimeType: string): Promise<Attachment>;
+    resolveFile(filePath: string): Promise<Attachment | null>;
+    readTextFileWithRange(path: string, opts?: {
+        line?: number;
+        limit?: number;
+    }): Promise<string>;
+    extensionFromMime(mimeType: string): string;
+    convertOggToWav(oggData: Buffer): Promise<Buffer>;
+}
+interface NotificationService {
+    notify(channelId: string, notification: NotificationMessage): Promise<void>;
+    notifyAll(notification: NotificationMessage): Promise<void>;
+}
+interface UsageService {
+    trackUsage(record: UsageRecord): Promise<void>;
+    checkBudget(sessionId: string): Promise<{
+        ok: boolean;
+        percent: number;
+        warning?: string;
+    }>;
+    getSummary(period: string): Promise<UsageSummary>;
+}
+interface TTSProvider {
+    synthesize(text: string, opts?: {
+        language?: string;
+        voice?: string;
+    }): Promise<Buffer>;
+}
+interface STTProvider {
+    transcribe(audio: Buffer, opts?: {
+        language?: string;
+    }): Promise<string>;
+}
+interface SpeechServiceInterface {
+    textToSpeech(text: string, opts?: {
+        language?: string;
+        voice?: string;
+    }): Promise<Buffer>;
+    speechToText(audio: Buffer, opts?: {
+        language?: string;
+    }): Promise<string>;
+    registerTTSProvider(name: string, provider: TTSProvider): void;
+    registerSTTProvider(name: string, provider: STTProvider): void;
+}
+interface ContextProvider$1 {
+    provide(sessionId: string, opts?: {
+        maxTokens?: number;
+    }): Promise<string>;
+}
+interface ContextService {
+    buildContext(sessionId: string, opts?: {
+        maxTokens?: number;
+    }): Promise<string>;
+    registerProvider(provider: ContextProvider$1): void;
+}
+interface ViewerStoreInterface {
+    storeFile(sessionId: string, filePath: string, content: string, workingDirectory: string): string | null;
+    storeDiff(sessionId: string, filePath: string, oldContent: string, newContent: string, workingDirectory: string): string | null;
+}
+interface TunnelServiceInterface {
+    getPublicUrl(): string;
+    start(): Promise<string>;
+    stop(): Promise<void>;
+    getStore(): ViewerStoreInterface;
+    fileUrl(entryId: string): string;
+    diffUrl(entryId: string): string;
+}
+
+declare class MessageTransformer {
+    private tunnelService?;
+    constructor(tunnelService?: TunnelServiceInterface | undefined);
+    transform(event: AgentEvent, sessionContext?: {
+        id: string;
+        workingDirectory: string;
+    }): OutgoingMessage;
+    private enrichWithViewerLinks;
+}
+
+interface SessionStore {
+    save(record: SessionRecord): Promise<void>;
+    get(sessionId: string): SessionRecord | undefined;
+    findByPlatform(channelId: string, predicate: (platform: Record<string, unknown>) => boolean): SessionRecord | undefined;
+    findByAgentSessionId(agentSessionId: string): SessionRecord | undefined;
+    list(channelId?: string): SessionRecord[];
+    remove(sessionId: string): Promise<void>;
+}
+
+interface EventBusEvents {
+    "session:created": (data: {
+        sessionId: string;
+        agent: string;
+        status: SessionStatus;
+    }) => void;
+    "session:updated": (data: {
+        sessionId: string;
+        status?: SessionStatus;
+        name?: string;
+        dangerousMode?: boolean;
+    }) => void;
+    "session:deleted": (data: {
+        sessionId: string;
+    }) => void;
+    "agent:event": (data: {
+        sessionId: string;
+        event: AgentEvent;
+    }) => void;
+    "permission:request": (data: {
+        sessionId: string;
+        permission: PermissionRequest;
+    }) => void;
+    "permission:resolved": (data: {
+        sessionId: string;
+        requestId: string;
+        decision: string;
+    }) => void;
+    "kernel:booted": () => void;
+    "system:ready": () => void;
+    "system:shutdown": () => void;
+    "system:commands-ready": (data: {
+        commands: Array<{
+            name: string;
+            description: string;
+        }>;
+    }) => void;
+    "plugin:loaded": (data: {
+        name: string;
+        version: string;
+    }) => void;
+    "plugin:failed": (data: {
+        name: string;
+        error: string;
+    }) => void;
+    "plugin:disabled": (data: {
+        name: string;
+        reason: string;
+    }) => void;
+    "plugin:unloaded": (data: {
+        name: string;
+    }) => void;
+    "session:ended": (data: {
+        sessionId: string;
+        reason: string;
+    }) => void;
+    "session:named": (data: {
+        sessionId: string;
+        name: string;
+    }) => void;
+    "agent:prompt": (data: {
+        sessionId: string;
+        text: string;
+        attachments?: unknown[];
+    }) => void;
+}
+declare class EventBus extends TypedEmitter<EventBusEvents> {
+}
 
 declare class SessionManager {
     private sessions;
     private store;
     private eventBus?;
+    middlewareChain?: MiddlewareChain;
     setEventBus(eventBus: EventBus): void;
     constructor(store?: SessionStore | null);
     createSession(channelId: string, agentName: string, workingDirectory: string, agentManager: AgentManager): Promise<Session>;
@@ -1393,16 +2048,11 @@ declare class SessionManager {
     destroyAll(): Promise<void>;
 }
 
-declare class SecurityGuard {
-    private configManager;
-    private sessionManager;
-    constructor(configManager: ConfigManager, sessionManager: SessionManager);
-    checkAccess(message: IncomingMessage): {
-        allowed: true;
-    } | {
-        allowed: false;
-        reason: string;
-    };
+declare class NotificationManager {
+    private adapters;
+    constructor(adapters: Map<string, IChannelAdapter>);
+    notify(channelId: string, notification: NotificationMessage): Promise<void>;
+    notifyAll(notification: NotificationMessage): Promise<void>;
 }
 
 interface BridgeDeps {
@@ -1410,7 +2060,8 @@ interface BridgeDeps {
     notificationManager: NotificationManager;
     sessionManager: SessionManager;
     eventBus?: EventBus;
-    fileService?: FileService;
+    fileService?: FileServiceInterface;
+    middlewareChain?: MiddlewareChain;
 }
 declare class SessionBridge {
     private session;
@@ -1421,11 +2072,14 @@ declare class SessionBridge {
     private sessionEventHandler?;
     private statusChangeHandler?;
     private namedHandler?;
-    constructor(session: Session, adapter: ChannelAdapter, deps: BridgeDeps);
+    constructor(session: Session, adapter: IChannelAdapter, deps: BridgeDeps);
+    /** Send message to adapter, optionally running through message:outgoing middleware */
+    private sendMessage;
     connect(): void;
     disconnect(): void;
     private wireAgentToSession;
     private wireSessionToAdapter;
+    private handleAgentEvent;
     private wirePermissions;
     private wireLifecycle;
 }
@@ -1471,6 +2125,67 @@ declare class UsageBudget {
     };
 }
 
+interface TunnelEntry {
+    port: number;
+    type: 'system' | 'user';
+    provider: string;
+    label?: string;
+    publicUrl?: string;
+    sessionId?: string;
+    status: 'stopped' | 'starting' | 'active' | 'failed';
+    createdAt: string;
+}
+
+interface ViewerEntry {
+    id: string;
+    type: 'file' | 'diff';
+    filePath?: string;
+    content: string;
+    oldContent?: string;
+    language?: string;
+    sessionId: string;
+    workingDirectory: string;
+    createdAt: number;
+    expiresAt: number;
+}
+declare class ViewerStore {
+    private entries;
+    private cleanupTimer;
+    private ttlMs;
+    constructor(ttlMinutes?: number);
+    storeFile(sessionId: string, filePath: string, content: string, workingDirectory: string): string | null;
+    storeDiff(sessionId: string, filePath: string, oldContent: string, newContent: string, workingDirectory: string): string | null;
+    get(id: string): ViewerEntry | undefined;
+    private cleanup;
+    private isPathAllowed;
+    private detectLanguage;
+    destroy(): void;
+}
+
+declare class TunnelService {
+    private registry;
+    private store;
+    private server;
+    private config;
+    private systemPort;
+    constructor(config: TunnelConfig);
+    start(): Promise<string>;
+    stop(): Promise<void>;
+    addTunnel(port: number, opts?: {
+        label?: string;
+        sessionId?: string;
+    }): Promise<TunnelEntry>;
+    stopTunnel(port: number): Promise<void>;
+    stopAllUser(): Promise<void>;
+    stopBySession(sessionId: string): Promise<TunnelEntry[]>;
+    listTunnels(): TunnelEntry[];
+    getTunnel(port: number): TunnelEntry | null;
+    getPublicUrl(): string;
+    getStore(): ViewerStore;
+    fileUrl(entryId: string): string;
+    diffUrl(entryId: string): string;
+}
+
 interface SessionCreateParams {
     channelId: string;
     agentName: string;
@@ -1488,13 +2203,124 @@ interface SideEffectDeps {
 declare class SessionFactory {
     private agentManager;
     private sessionManager;
-    private speechService;
+    private speechServiceAccessor;
     private eventBus;
-    constructor(agentManager: AgentManager, sessionManager: SessionManager, speechService: SpeechService, eventBus: EventBus);
+    middlewareChain?: MiddlewareChain;
+    constructor(agentManager: AgentManager, sessionManager: SessionManager, speechServiceAccessor: SpeechService | (() => SpeechService), eventBus: EventBus);
+    private get speechService();
     create(params: SessionCreateParams): Promise<Session>;
     wireSideEffects(session: Session, deps: SideEffectDeps): void;
 }
 
+declare class SecurityGuard {
+    private configManager;
+    private sessionManager;
+    constructor(configManager: ConfigManager$1, sessionManager: SessionManager);
+    checkAccess(message: IncomingMessage): {
+        allowed: true;
+    } | {
+        allowed: false;
+        reason: string;
+    };
+}
+
+declare class ServiceRegistry {
+    private services;
+    register<T>(name: string, implementation: T, pluginName: string): void;
+    registerOverride<T>(name: string, implementation: T, pluginName: string): void;
+    get<T>(name: string): T | undefined;
+    has(name: string): boolean;
+    list(): Array<{
+        name: string;
+        pluginName: string;
+    }>;
+    unregister(name: string): void;
+    unregisterByPlugin(pluginName: string): void;
+}
+
+interface ValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+declare class SettingsManager {
+    private basePath;
+    constructor(basePath: string);
+    getBasePath(): string;
+    createAPI(pluginName: string): SettingsAPI;
+    loadSettings(pluginName: string): Promise<Record<string, unknown>>;
+    validateSettings(_pluginName: string, settings: unknown, schema?: ZodSchema): ValidationResult;
+    getSettingsPath(pluginName: string): string;
+    getPluginSettings(pluginName: string): Promise<Record<string, unknown>>;
+    updatePluginSettings(pluginName: string, updates: Record<string, unknown>): Promise<void>;
+}
+
+interface PluginEntry {
+    version: string;
+    installedAt: string;
+    updatedAt: string;
+    source: 'builtin' | 'npm' | 'local';
+    enabled: boolean;
+    settingsPath: string;
+    description?: string;
+}
+type RegisterInput = Omit<PluginEntry, 'installedAt' | 'updatedAt'>;
+declare class PluginRegistry {
+    private registryPath;
+    private data;
+    constructor(registryPath: string);
+    list(): Map<string, PluginEntry>;
+    get(name: string): PluginEntry | undefined;
+    register(name: string, entry: RegisterInput): void;
+    remove(name: string): void;
+    setEnabled(name: string, enabled: boolean): void;
+    updateVersion(name: string, version: string): void;
+    listEnabled(): Map<string, PluginEntry>;
+    listBySource(source: PluginEntry['source']): Map<string, PluginEntry>;
+    load(): Promise<void>;
+    save(): Promise<void>;
+}
+
+interface LifecycleManagerOpts {
+    serviceRegistry?: ServiceRegistry;
+    middlewareChain?: MiddlewareChain;
+    errorTracker?: ErrorTracker;
+    eventBus?: EventBus$1 & {
+        on(event: string, handler: (...args: unknown[]) => void): void;
+        off(event: string, handler: (...args: unknown[]) => void): void;
+        emit(event: string, payload: unknown): void;
+    };
+    storagePath?: string;
+    sessions?: unknown;
+    config?: unknown;
+    core?: unknown;
+    log?: Logger;
+    settingsManager?: SettingsManager;
+    pluginRegistry?: PluginRegistry;
+}
+declare class LifecycleManager {
+    readonly serviceRegistry: ServiceRegistry;
+    readonly middlewareChain: MiddlewareChain;
+    readonly errorTracker: ErrorTracker;
+    private eventBus;
+    private storagePath;
+    private sessions;
+    private config;
+    private core;
+    private log;
+    private settingsManager;
+    private pluginRegistry;
+    private contexts;
+    private loadOrder;
+    private _loaded;
+    private _failed;
+    get loadedPlugins(): string[];
+    get failedPlugins(): string[];
+    constructor(opts?: LifecycleManagerOpts);
+    boot(plugins: OpenACPPlugin[]): Promise<void>;
+    unloadPlugin(name: string): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
 interface ContextProvider {
     readonly name: string;
     isAvailable(repoPath: string): Promise<boolean>;
@@ -1551,16 +2377,12 @@ declare class ContextManager {
 }
 
 declare class OpenACPCore {
-    configManager: ConfigManager;
+    configManager: ConfigManager$1;
     agentCatalog: AgentCatalog;
     agentManager: AgentManager;
     sessionManager: SessionManager;
-    notificationManager: NotificationManager;
     messageTransformer: MessageTransformer;
-    fileService: FileService;
-    readonly speechService: SpeechService;
-    securityGuard: SecurityGuard;
-    adapters: Map<string, ChannelAdapter>;
+    adapters: Map<string, IChannelAdapter>;
     /** Set by main.ts — triggers graceful shutdown with restart exit code */
     requestRestart: (() => Promise<void>) | null;
     private _tunnelService?;
@@ -1568,13 +2390,18 @@ declare class OpenACPCore {
     private resumeLocks;
     eventBus: EventBus;
     sessionFactory: SessionFactory;
-    readonly usageStore: UsageStore | null;
-    readonly usageBudget: UsageBudget | null;
-    readonly contextManager: ContextManager;
-    constructor(configManager: ConfigManager);
+    readonly lifecycleManager: LifecycleManager;
+    get securityGuard(): SecurityGuard;
+    get notificationManager(): NotificationManager;
+    get fileService(): FileServiceInterface;
+    get speechService(): SpeechService;
+    get contextManager(): ContextManager;
+    get usageStore(): UsageStore | null;
+    get usageBudget(): UsageBudget | null;
+    constructor(configManager: ConfigManager$1);
     get tunnelService(): TunnelService | undefined;
     set tunnelService(service: TunnelService | undefined);
-    registerAdapter(name: string, adapter: ChannelAdapter): void;
+    registerAdapter(name: string, adapter: IChannelAdapter): void;
     start(): Promise<void>;
     stop(): Promise<void>;
     summarizeSession(sessionId: string): Promise<{
@@ -1632,17 +2459,26 @@ declare class OpenACPCore {
     getOrResumeSession(channelId: string, threadId: string): Promise<Session | null>;
     private lazyResume;
     /** Create a SessionBridge for the given session and adapter */
-    createBridge(session: Session, adapter: ChannelAdapter): SessionBridge;
+    createBridge(session: Session, adapter: IChannelAdapter): SessionBridge;
 }
 
-interface AdapterFactory {
-    name: string;
-    createAdapter(core: OpenACPCore, config: ChannelConfig): ChannelAdapter;
+interface ConfigFieldDef {
+    path: string;
+    displayName: string;
+    group: string;
+    type: "toggle" | "select" | "number" | "string";
+    options?: string[] | ((config: Config) => string[]);
+    scope: "safe" | "sensitive";
+    hotReload: boolean;
 }
-declare function installPlugin(packageName: string): void;
-declare function uninstallPlugin(packageName: string): void;
-declare function listPlugins(): Record<string, string>;
-declare function loadAdapterFactory(packageName: string): Promise<AdapterFactory | null>;
+declare const CONFIG_REGISTRY: ConfigFieldDef[];
+declare function getFieldDef(path: string): ConfigFieldDef | undefined;
+declare function getSafeFields(): ConfigFieldDef[];
+declare function isHotReloadable(path: string): boolean;
+declare function resolveOptions(def: ConfigFieldDef, config: Config): string[] | undefined;
+declare function getConfigValue(config: Config, path: string): unknown;
+
+declare function runConfigEditor(configManager: ConfigManager$1, mode?: 'file' | 'api', apiPort?: number): Promise<void>;
 
 declare function getStatus(pidPath?: string): {
     running: boolean;
@@ -1671,7 +2507,29 @@ declare function uninstallAutoStart(): {
 };
 declare function isAutoStartInstalled(): boolean;
 
-declare function runConfigEditor(configManager: ConfigManager, mode?: 'file' | 'api', apiPort?: number): Promise<void>;
+declare class FileService {
+    private baseDir;
+    constructor(baseDir: string);
+    saveFile(sessionId: string, fileName: string, data: Buffer, mimeType: string): Promise<Attachment>;
+    resolveFile(filePath: string): Promise<Attachment | null>;
+    /**
+     * Convert OGG Opus audio to WAV format.
+     * Telegram voice messages use OGG Opus which many AI agents can't read.
+     */
+    convertOggToWav(oggData: Buffer): Promise<Buffer>;
+    /** Instance method — delegates to static for FileServiceInterface compliance */
+    readTextFileWithRange(filePath: string, options?: {
+        line?: number;
+        limit?: number;
+    }): Promise<string>;
+    static readTextFileWithRange(filePath: string, options?: {
+        line?: number;
+        limit?: number;
+    }): Promise<string>;
+    /** Instance method — delegates to static for FileServiceInterface compliance */
+    extensionFromMime(mimeType: string): string;
+    static extensionFromMime(mimeType: string): string;
+}
 
 interface TopicInfo {
     sessionId: string;
@@ -1775,22 +2633,6 @@ declare class StaticServer {
     serve(req: http.IncomingMessage, res: http.ServerResponse): boolean;
 }
 
-interface ConfigFieldDef {
-    path: string;
-    displayName: string;
-    group: string;
-    type: "toggle" | "select" | "number" | "string";
-    options?: string[] | ((config: Config) => string[]);
-    scope: "safe" | "sensitive";
-    hotReload: boolean;
-}
-declare const CONFIG_REGISTRY: ConfigFieldDef[];
-declare function getFieldDef(path: string): ConfigFieldDef | undefined;
-declare function getSafeFields(): ConfigFieldDef[];
-declare function isHotReloadable(path: string): boolean;
-declare function resolveOptions(def: ConfigFieldDef, config: Config): string[] | undefined;
-declare function getConfigValue(config: Config, path: string): unknown;
-
 declare class EntireProvider implements ContextProvider {
     readonly name = "entire";
     isAvailable(repoPath: string): Promise<boolean>;
@@ -1801,6 +2643,250 @@ declare class EntireProvider implements ContextProvider {
     private buildTitle;
 }
 
+type DisplayVerbosity = "low" | "medium" | "high";
+interface ViewerLinks {
+    file?: string;
+    diff?: string;
+}
+interface ToolCallMeta {
+    id: string;
+    name: string;
+    kind?: string;
+    status?: string;
+    content?: unknown;
+    rawInput?: unknown;
+    viewerLinks?: ViewerLinks;
+    viewerFilePath?: string;
+    displaySummary?: string;
+    displayTitle?: string;
+    displayKind?: string;
+}
+
+interface RenderedMessage<TComponents = unknown> {
+    body: string;
+    format: 'html' | 'markdown' | 'plain' | 'structured';
+    attachments?: RenderedAttachment[];
+    components?: TComponents;
+}
+interface RenderedPermission<TComponents = unknown> extends RenderedMessage<TComponents> {
+    actions: RenderedAction[];
+}
+interface RenderedAction {
+    id: string;
+    label: string;
+    isAllow?: boolean;
+}
+interface RenderedAttachment {
+    type: 'file' | 'image' | 'audio';
+    data: Buffer | string;
+    mimeType?: string;
+    filename?: string;
+}
+interface IRenderer {
+    renderText(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderToolCall(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderToolUpdate(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderPlan(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderUsage(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderPermission(request: PermissionRequest): RenderedPermission;
+    renderError(content: OutgoingMessage): RenderedMessage;
+    renderNotification(notification: NotificationMessage): RenderedMessage;
+    renderThought?(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderAttachment?(content: OutgoingMessage): RenderedMessage;
+    renderSessionEnd?(content: OutgoingMessage): RenderedMessage;
+    renderSystemMessage?(content: OutgoingMessage): RenderedMessage;
+    renderModeChange?(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderConfigUpdate?(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderModelUpdate?(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderResource?(content: OutgoingMessage): RenderedMessage;
+    renderResourceLink?(content: OutgoingMessage): RenderedMessage;
+}
+/**
+ * BaseRenderer — plain text defaults. Extend for platform-specific rendering.
+ */
+declare class BaseRenderer implements IRenderer {
+    renderText(content: OutgoingMessage): RenderedMessage;
+    renderToolCall(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderToolUpdate(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderPlan(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderUsage(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
+    renderPermission(request: PermissionRequest): RenderedPermission;
+    renderError(content: OutgoingMessage): RenderedMessage;
+    renderNotification(notification: NotificationMessage): RenderedMessage;
+    renderSystemMessage(content: OutgoingMessage): RenderedMessage;
+    renderModeChange(content: OutgoingMessage): RenderedMessage;
+    renderConfigUpdate(): RenderedMessage;
+    renderModelUpdate(content: OutgoingMessage): RenderedMessage;
+    renderResource(content: OutgoingMessage): RenderedMessage;
+    renderResourceLink(content: OutgoingMessage): RenderedMessage;
+}
+
+interface AdapterContext {
+    configManager: {
+        get(): Record<string, unknown>;
+    };
+    fileService?: unknown;
+}
+interface MessagingAdapterConfig extends ChannelConfig {
+    maxMessageLength: number;
+    flushInterval?: number;
+    sendInterval?: number;
+    thinkingRefreshInterval?: number;
+    thinkingDuration?: number;
+    displayVerbosity?: DisplayVerbosity;
+}
+declare abstract class MessagingAdapter implements IChannelAdapter {
+    protected context: AdapterContext;
+    protected adapterConfig: MessagingAdapterConfig;
+    abstract readonly name: string;
+    abstract readonly renderer: IRenderer;
+    abstract readonly capabilities: AdapterCapabilities;
+    constructor(context: AdapterContext, adapterConfig: MessagingAdapterConfig);
+    sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>;
+    protected dispatchMessage(sessionId: string, content: OutgoingMessage, verbosity: DisplayVerbosity): Promise<void>;
+    protected handleText(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleThought(_sessionId: string, _content: OutgoingMessage, _verbosity: DisplayVerbosity): Promise<void>;
+    protected handleToolCall(_sessionId: string, _content: OutgoingMessage, _verbosity: DisplayVerbosity): Promise<void>;
+    protected handleToolUpdate(_sessionId: string, _content: OutgoingMessage, _verbosity: DisplayVerbosity): Promise<void>;
+    protected handlePlan(_sessionId: string, _content: OutgoingMessage, _verbosity: DisplayVerbosity): Promise<void>;
+    protected handleUsage(_sessionId: string, _content: OutgoingMessage, _verbosity: DisplayVerbosity): Promise<void>;
+    protected handleError(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleAttachment(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleSystem(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleSessionEnd(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleModeChange(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleConfigUpdate(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleModelUpdate(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleUserReplay(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleResource(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleResourceLink(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected getVerbosity(): DisplayVerbosity;
+    protected shouldDisplay(content: OutgoingMessage, verbosity: DisplayVerbosity): boolean;
+    abstract start(): Promise<void>;
+    abstract stop(): Promise<void>;
+    abstract createSessionThread(sessionId: string, name: string): Promise<string>;
+    abstract renameSessionThread(sessionId: string, newName: string): Promise<void>;
+    abstract sendPermissionRequest(sessionId: string, request: PermissionRequest): Promise<void>;
+    abstract sendNotification(notification: NotificationMessage): Promise<void>;
+}
+
+interface StreamEvent {
+    type: string;
+    sessionId?: string;
+    payload: unknown;
+    timestamp: number;
+}
+declare abstract class StreamAdapter implements IChannelAdapter {
+    abstract readonly name: string;
+    capabilities: AdapterCapabilities;
+    constructor(config?: Partial<AdapterCapabilities>);
+    sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>;
+    sendPermissionRequest(sessionId: string, request: PermissionRequest): Promise<void>;
+    sendNotification(notification: NotificationMessage): Promise<void>;
+    createSessionThread(_sessionId: string, _name: string): Promise<string>;
+    renameSessionThread(sessionId: string, name: string): Promise<void>;
+    protected abstract emit(sessionId: string, event: StreamEvent): Promise<void>;
+    protected abstract broadcast(event: StreamEvent): Promise<void>;
+    abstract start(): Promise<void>;
+    abstract stop(): Promise<void>;
+}
+
+type QueueItemType = 'text' | 'other';
+interface SendQueueConfig {
+    minInterval: number;
+    categoryIntervals?: Record<string, number>;
+    onRateLimited?: () => void;
+    onError?: (error: Error) => void;
+}
+interface EnqueueOptions {
+    type?: QueueItemType;
+    key?: string;
+    category?: string;
+}
+declare class SendQueue {
+    private config;
+    private items;
+    private processing;
+    private lastExec;
+    private lastCategoryExec;
+    constructor(config: SendQueueConfig);
+    get pending(): number;
+    enqueue<T>(fn: () => Promise<T>, opts?: EnqueueOptions): Promise<T | undefined>;
+    onRateLimited(): void;
+    clear(): void;
+    private scheduleProcess;
+    private getInterval;
+    private processNext;
+}
+
+interface DraftConfig {
+    flushInterval: number;
+    maxLength: number;
+    onFlush: (sessionId: string, text: string, isEdit: boolean) => Promise<string | undefined>;
+    onError?: (sessionId: string, error: Error) => void;
+}
+declare class Draft {
+    private sessionId;
+    private config;
+    private buffer;
+    private _messageId?;
+    private firstFlushPending;
+    private flushTimer?;
+    private flushPromise;
+    constructor(sessionId: string, config: DraftConfig);
+    get isEmpty(): boolean;
+    get messageId(): string | undefined;
+    append(text: string): void;
+    finalize(): Promise<string | undefined>;
+    destroy(): void;
+    private scheduleFlush;
+    private flush;
+}
+declare class DraftManager {
+    private config;
+    private drafts;
+    constructor(config: DraftConfig);
+    getOrCreate(sessionId: string): Draft;
+    finalize(sessionId: string): Promise<void>;
+    finalizeAll(): Promise<void>;
+    destroy(sessionId: string): void;
+    destroyAll(): void;
+}
+
+interface TrackedToolCall extends ToolCallMeta {
+    messageId: string;
+}
+declare class ToolCallTracker {
+    private sessions;
+    track(sessionId: string, meta: ToolCallMeta, messageId: string): void;
+    update(sessionId: string, toolId: string, status: string, patch?: Partial<Pick<ToolCallMeta, 'viewerLinks' | 'viewerFilePath' | 'name' | 'kind'>>): TrackedToolCall | null;
+    getActive(sessionId: string): TrackedToolCall[];
+    clear(sessionId: string): void;
+    clearAll(): void;
+}
+
+interface ActivityConfig {
+    thinkingRefreshInterval: number;
+    maxThinkingDuration: number;
+}
+interface ActivityCallbacks {
+    sendThinkingIndicator(): Promise<void>;
+    updateThinkingIndicator(): Promise<void>;
+    removeThinkingIndicator(): Promise<void>;
+}
+declare class ActivityTracker {
+    private config;
+    private sessions;
+    constructor(config: ActivityConfig);
+    onThinkingStart(sessionId: string, callbacks: ActivityCallbacks): void;
+    onTextStart(sessionId: string): void;
+    onSessionEnd(sessionId: string): void;
+    destroy(): void;
+    private cleanup;
+    private startRefresh;
+    private stopRefresh;
+}
+
 interface TelegramChannelConfig extends ChannelConfig {
     botToken: string;
     chatId: number;
@@ -1808,7 +2894,11 @@ interface TelegramChannelConfig extends ChannelConfig {
     assistantTopicId: number | null;
 }
 
-declare class TelegramAdapter extends ChannelAdapter<OpenACPCore> {
+declare class TelegramAdapter extends MessagingAdapter {
+    readonly name = "telegram";
+    readonly renderer: IRenderer;
+    readonly capabilities: AdapterCapabilities;
+    private core;
     private bot;
     private telegramConfig;
     private permissionHandler;
@@ -1817,19 +2907,34 @@ declare class TelegramAdapter extends ChannelAdapter<OpenACPCore> {
     private notificationTopicId;
     private assistantTopicId;
     private sendQueue;
+    private _sessionThreadIds;
     private toolTracker;
     private draftManager;
     private skillManager;
     private fileService;
     private sessionTrackers;
-    private get verbosity();
+    private callbackCache;
+    private callbackCounter;
+    private getThreadId;
     private getOrCreateTracker;
     constructor(core: OpenACPCore, config: TelegramChannelConfig);
     start(): Promise<void>;
     stop(): Promise<void>;
+    private renderCommandResponse;
+    private toCallbackData;
+    private fromCallbackData;
     private setupRoutes;
-    private messageHandlers;
     sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>;
+    protected handleThought(sessionId: string, _content: OutgoingMessage, _verbosity: DisplayVerbosity): Promise<void>;
+    protected handleText(sessionId: string, content: OutgoingMessage): Promise<void>;
+    protected handleToolCall(sessionId: string, content: OutgoingMessage, verbosity: DisplayVerbosity): Promise<void>;
+    protected handleToolUpdate(sessionId: string, content: OutgoingMessage, verbosity: DisplayVerbosity): Promise<void>;
+    protected handlePlan(sessionId: string, content: OutgoingMessage, verbosity: DisplayVerbosity): Promise<void>;
+    protected handleUsage(sessionId: string, content: OutgoingMessage, verbosity: DisplayVerbosity): Promise<void>;
+    protected handleAttachment(sessionId: string, content: OutgoingMessage): Promise<void>;
+    protected handleSessionEnd(sessionId: string, _content: OutgoingMessage): Promise<void>;
+    protected handleError(sessionId: string, content: OutgoingMessage): Promise<void>;
+    protected handleSystem(sessionId: string, content: OutgoingMessage): Promise<void>;
     sendPermissionRequest(sessionId: string, request: PermissionRequest): Promise<void>;
     sendNotification(notification: NotificationMessage): Promise<void>;
     createSessionThread(sessionId: string, name: string): Promise<string>;
@@ -1843,4 +2948,4 @@ declare class TelegramAdapter extends ChannelAdapter<OpenACPCore> {
     archiveSessionTopic(sessionId: string): Promise<void>;
 }
 
-export { type AdapterFactory, AgentCatalog, type AgentCommand, type AgentDefinition, type AgentDistribution, type AgentEvent, AgentInstance, type AgentListItem, AgentManager, AgentStore, type ApiConfig, ApiServer, type Attachment, type AvailabilityResult, type BridgeDeps, CONFIG_REGISTRY, ChannelAdapter, type ChannelConfig, type CleanupResult, type Config, type ConfigFieldDef, ConfigManager, ContextManager, type ContextOptions, type ContextProvider, type ContextQuery, type ContextResult, type SessionInfo as ContextSessionInfo, type DeleteTopicResult, type DiscordPlatformData, EntireProvider, EventBus, type EventBusEvents, FileService, GroqSTT, type IChannelAdapter, type IncomingMessage, type InstallProgress, type InstallResult, type InstalledAgent, type Logger, type LoggingConfig, MessageTransformer, NotificationManager, type NotificationMessage, OpenACPCore, type OutgoingMessage, PLUGINS_DIR, PermissionGate, type PermissionOption, type PermissionRequest, type PlanEntry, PromptQueue, type RegistryAgent, type RegistryBinaryTarget, type RegistryDistribution, SSEManager, type STTOptions, type STTProvider, type STTResult, SecurityGuard, Session, SessionBridge, type SessionCreateParams, type SessionEvents, SessionFactory, type SessionListResult, SessionManager, type SessionRecord, type SessionStatus, type SideEffectDeps, type SpeechProviderConfig, SpeechService, type SpeechServiceConfig, StaticServer, StderrCapture, type TTSOptions, type TTSProvider, type TTSResult, TelegramAdapter, type TelegramPlatformData, type TopicInfo, TopicManager, TypedEmitter, UsageBudget, type UsageConfig, type UsageRecord, UsageStore, type UsageSummary, cleanupOldSessionLogs, createChildLogger, createSessionLogger, expandHome, getConfigValue, getFieldDef, getPidPath, getSafeFields, getStatus, initLogger, installAutoStart, installPlugin, isAutoStartInstalled, isAutoStartSupported, isHotReloadable, listPlugins, loadAdapterFactory, log, nodeToWebReadable, nodeToWebWritable, resolveOptions, runConfigEditor, setLogLevel, shutdownLogger, startDaemon, stopDaemon, uninstallAutoStart, uninstallPlugin };
+export { ActivityTracker, type AdapterCapabilities, type AgentCapabilities, AgentCatalog, type AgentCommand, type AgentDefinition, type AgentDistribution, type AgentEvent, AgentInstance, type AgentListItem, AgentManager, AgentStore, type ApiConfig, ApiServer, type Attachment, type AuthMethod, type AuthenticateRequest, type AvailabilityResult, BaseRenderer, type BridgeDeps, CONFIG_REGISTRY, ChannelAdapter, type ChannelConfig, type CleanupResult, type CommandArgs, type CommandDef, type CommandResponse, type Config, type ConfigFieldDef, ConfigManager$1 as ConfigManager, type ConfigOption, type ConfigSelectChoice, type ConfigSelectGroup, type ContentBlock, ContextManager, type ContextOptions, type ContextProvider, type ContextQuery, type ContextResult, type ContextService, type SessionInfo as ContextSessionInfo, type DeleteTopicResult, type DiscordPlatformData, DraftManager, EntireProvider, EventBus, type EventBusEvents, FileService, type FileServiceInterface, GroqSTT, type IChannelAdapter, type IncomingMessage, type InstallContext, type InstallProgress, type InstallResult, type InstalledAgent, type ListItem, type Logger$1 as Logger, type LoggingConfig, type McpServerConfig, type MenuOption, MessageTransformer, MessagingAdapter, type MigrateContext, type ModelInfo, type NewSessionResponse, NotificationManager, type NotificationMessage, type NotificationService, OpenACPCore, type OpenACPPlugin, type OutgoingMessage, PLUGINS_DIR, PermissionGate, type PermissionOption, type PermissionRequest, type PlanEntry, type PluginContext, type PluginPermission, type PluginStorage, PromptQueue, type PromptResponse, type RegistryAgent, type RegistryBinaryTarget, type RegistryDistribution, SSEManager, type STTOptions, type STTProvider$1 as STTProvider, type STTResult, SecurityGuard, type SecurityService, SendQueue, Session, SessionBridge, type SessionCreateParams, type SessionEvents, SessionFactory, type SessionListItem, type SessionListResponse, type SessionListResult, SessionManager, type SessionMode, type SessionModeState, type SessionModelState, type SessionRecord, type SessionStatus, type SetConfigOptionValue, type SettingsAPI, type SideEffectDeps, type SpeechProviderConfig, SpeechService, type SpeechServiceConfig, type SpeechServiceInterface, StaticServer, StderrCapture, type StopReason, StreamAdapter, type TTSOptions, type TTSProvider$1 as TTSProvider, type TTSResult, TelegramAdapter, type TelegramPlatformData, type TerminalIO, ToolCallTracker, type TopicInfo, TopicManager, type TunnelServiceInterface, TypedEmitter, UsageBudget, type UsageConfig, type UsageRecord, type UsageService, UsageStore, type UsageSummary, cleanupOldSessionLogs, createChildLogger, createSessionLogger, expandHome, getConfigValue, getFieldDef, getPidPath, getSafeFields, getStatus, initLogger, installAutoStart, isAutoStartInstalled, isAutoStartSupported, isHotReloadable, log, nodeToWebReadable, nodeToWebWritable, resolveOptions, runConfigEditor, setLogLevel, shutdownLogger, startDaemon, stopDaemon, uninstallAutoStart };