@openacp/cli 0.6.10 → 2026.41.2

package/dist/index.d.ts

@@ -1,10 +1,37 @@
 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 { FastifyInstance, FastifyPluginAsync, preHandlerHookHandler, FastifyRequest, FastifyReply } from 'fastify';
 import * as http from 'node:http';
 
+type OutputMode = "low" | "medium" | "high";
+/** @deprecated Use OutputMode instead */
+type DisplayVerbosity = OutputMode;
+declare const STATUS_ICONS: Record<string, string>;
+declare const KIND_ICONS: Record<string, string>;
+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 ToolUpdateMeta extends ToolCallMeta {
+    status: string;
+}
+
 interface Attachment {
     type: 'image' | 'audio' | 'file';
     filePath: string;
@@ -21,7 +48,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 +90,7 @@ type AgentEvent = {
     content?: unknown;
     locations?: unknown;
     rawInput?: unknown;
+    rawOutput?: unknown;
     meta?: unknown;
 } | {
     type: "tool_update";
@@ -73,6 +101,7 @@ type AgentEvent = {
     content?: unknown;
     locations?: unknown;
     rawInput?: unknown;
+    rawOutput?: unknown;
     meta?: unknown;
 } | {
     type: "plan";
@@ -105,6 +134,34 @@ type AgentEvent = {
 } | {
     type: "system_message";
     message: string;
+} | {
+    type: "session_info_update";
+    title?: string;
+    updatedAt?: string;
+    _meta?: Record<string, unknown>;
+} | {
+    type: "config_option_update";
+    options: ConfigOption[];
+} | {
+    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;
+} | {
+    type: "tts_strip";
 };
 interface PlanEntry {
     content: string;
@@ -196,6 +253,12 @@ interface InstallResult {
     setupSteps?: string[];
 }
 type SessionStatus = "initializing" | "active" | "cancelled" | "finished" | "error";
+interface AgentSwitchEntry {
+    agentName: string;
+    agentSessionId: string;
+    switchedAt: string;
+    promptCount: number;
+}
 interface SessionRecord<P = Record<string, unknown>> {
     sessionId: string;
     agentSessionId: string;
@@ -208,7 +271,22 @@ interface SessionRecord<P = Record<string, unknown>> {
     lastActiveAt: string;
     name?: string;
     dangerousMode?: boolean;
+    clientOverrides?: {
+        bypassPermissions?: boolean;
+    };
+    outputMode?: OutputMode;
     platform: P;
+    firstAgent?: string;
+    currentPromptCount?: number;
+    agentSwitchHistory?: AgentSwitchEntry[];
+    acpState?: {
+        configOptions?: ConfigOption[];
+        agentCapabilities?: AgentCapabilities;
+        currentMode?: string;
+        availableModes?: SessionMode[];
+        currentModel?: string;
+        availableModels?: ModelInfo[];
+    };
 }
 interface TelegramPlatformData {
     topicId: number;
@@ -226,20 +304,172 @@ interface UsageRecord {
     };
     timestamp: string;
 }
-interface UsageSummary {
-    period: "today" | "week" | "month" | "all";
-    totalTokens: number;
-    totalCost: number;
-    currency: string;
-    sessionCount: number;
-    recordCount: number;
+interface UsageRecordEvent {
+    sessionId: string;
+    agentName: string;
+    timestamp: string;
+    tokensUsed: number;
+    contextSize: number;
+    cost?: {
+        amount: number;
+        currency: string;
+    };
 }
-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<{
     level: z.ZodDefault<z.ZodEnum<["silent", "debug", "info", "warn", "error", "fatal"]>>;
     logDir: z.ZodDefault<z.ZodString>;
@@ -278,8 +508,8 @@ declare const TunnelSchema: z.ZodDefault<z.ZodObject<{
         token?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    options: Record<string, unknown>;
     enabled: boolean;
+    options: Record<string, unknown>;
     port: number;
     provider: "cloudflare" | "ngrok" | "bore" | "tailscale";
     maxUserTunnels: number;
@@ -289,8 +519,8 @@ declare const TunnelSchema: z.ZodDefault<z.ZodObject<{
         token?: string | undefined;
     };
 }, {
-    options?: Record<string, unknown> | undefined;
     enabled?: boolean | undefined;
+    options?: Record<string, unknown> | undefined;
     port?: number | undefined;
     provider?: "cloudflare" | "ngrok" | "bore" | "tailscale" | undefined;
     maxUserTunnels?: number | undefined;
@@ -322,147 +552,52 @@ declare const UsageSchema: z.ZodDefault<z.ZodObject<{
 }>>;
 type UsageConfig = z.infer<typeof UsageSchema>;
 declare const ConfigSchema: z.ZodObject<{
-    channels: z.ZodObject<{
-        slack: z.ZodOptional<z.ZodObject<{
-            enabled: z.ZodDefault<z.ZodBoolean>;
-            adapter: z.ZodOptional<z.ZodLiteral<"slack">>;
-            botToken: z.ZodOptional<z.ZodString>;
-            appToken: z.ZodOptional<z.ZodString>;
-            signingSecret: z.ZodOptional<z.ZodString>;
-            notificationChannelId: z.ZodOptional<z.ZodString>;
-            allowedUserIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-            channelPrefix: z.ZodDefault<z.ZodString>;
-            autoCreateSession: z.ZodDefault<z.ZodBoolean>;
-            startupChannelId: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            enabled: boolean;
-            allowedUserIds: string[];
-            channelPrefix: string;
-            autoCreateSession: boolean;
-            adapter?: "slack" | undefined;
-            botToken?: string | undefined;
-            appToken?: string | undefined;
-            signingSecret?: string | undefined;
-            notificationChannelId?: string | undefined;
-            startupChannelId?: string | undefined;
-        }, {
-            enabled?: boolean | undefined;
-            adapter?: "slack" | undefined;
-            botToken?: string | undefined;
-            appToken?: string | undefined;
-            signingSecret?: string | undefined;
-            notificationChannelId?: string | undefined;
-            allowedUserIds?: string[] | undefined;
-            channelPrefix?: string | undefined;
-            autoCreateSession?: boolean | undefined;
-            startupChannelId?: string | undefined;
-        }>>;
-    }, "strip", z.ZodObject<{
+    instanceName: z.ZodOptional<z.ZodString>;
+    channels: z.ZodObject<{}, "strip", z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         adapter: z.ZodOptional<z.ZodString>;
-        displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
+        displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         adapter: z.ZodOptional<z.ZodString>;
-        displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
+        displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         adapter: z.ZodOptional<z.ZodString>;
-        displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
-    }, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
-        slack: z.ZodOptional<z.ZodObject<{
-            enabled: z.ZodDefault<z.ZodBoolean>;
-            adapter: z.ZodOptional<z.ZodLiteral<"slack">>;
-            botToken: z.ZodOptional<z.ZodString>;
-            appToken: z.ZodOptional<z.ZodString>;
-            signingSecret: z.ZodOptional<z.ZodString>;
-            notificationChannelId: z.ZodOptional<z.ZodString>;
-            allowedUserIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-            channelPrefix: z.ZodDefault<z.ZodString>;
-            autoCreateSession: z.ZodDefault<z.ZodBoolean>;
-            startupChannelId: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            enabled: boolean;
-            allowedUserIds: string[];
-            channelPrefix: string;
-            autoCreateSession: boolean;
-            adapter?: "slack" | undefined;
-            botToken?: string | undefined;
-            appToken?: string | undefined;
-            signingSecret?: string | undefined;
-            notificationChannelId?: string | undefined;
-            startupChannelId?: string | undefined;
-        }, {
-            enabled?: boolean | undefined;
-            adapter?: "slack" | undefined;
-            botToken?: string | undefined;
-            appToken?: string | undefined;
-            signingSecret?: string | undefined;
-            notificationChannelId?: string | undefined;
-            allowedUserIds?: string[] | undefined;
-            channelPrefix?: string | undefined;
-            autoCreateSession?: boolean | undefined;
-            startupChannelId?: string | undefined;
-        }>>;
-    }, z.ZodObject<{
+        displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+    }, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{}, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         adapter: z.ZodOptional<z.ZodString>;
-        displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
+        displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         adapter: z.ZodOptional<z.ZodString>;
-        displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
+        displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         adapter: z.ZodOptional<z.ZodString>;
-        displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
-    }, z.ZodTypeAny, "passthrough">>, "strip">, z.objectInputType<{
-        slack: z.ZodOptional<z.ZodObject<{
-            enabled: z.ZodDefault<z.ZodBoolean>;
-            adapter: z.ZodOptional<z.ZodLiteral<"slack">>;
-            botToken: z.ZodOptional<z.ZodString>;
-            appToken: z.ZodOptional<z.ZodString>;
-            signingSecret: z.ZodOptional<z.ZodString>;
-            notificationChannelId: z.ZodOptional<z.ZodString>;
-            allowedUserIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-            channelPrefix: z.ZodDefault<z.ZodString>;
-            autoCreateSession: z.ZodDefault<z.ZodBoolean>;
-            startupChannelId: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            enabled: boolean;
-            allowedUserIds: string[];
-            channelPrefix: string;
-            autoCreateSession: boolean;
-            adapter?: "slack" | undefined;
-            botToken?: string | undefined;
-            appToken?: string | undefined;
-            signingSecret?: string | undefined;
-            notificationChannelId?: string | undefined;
-            startupChannelId?: string | undefined;
-        }, {
-            enabled?: boolean | undefined;
-            adapter?: "slack" | undefined;
-            botToken?: string | undefined;
-            appToken?: string | undefined;
-            signingSecret?: string | undefined;
-            notificationChannelId?: string | undefined;
-            allowedUserIds?: string[] | undefined;
-            channelPrefix?: string | undefined;
-            autoCreateSession?: boolean | undefined;
-            startupChannelId?: string | undefined;
-        }>>;
-    }, z.ZodObject<{
+        displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+    }, z.ZodTypeAny, "passthrough">>, "strip">, z.objectInputType<{}, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         adapter: z.ZodOptional<z.ZodString>;
-        displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
+        displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         adapter: z.ZodOptional<z.ZodString>;
-        displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
+        displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         adapter: z.ZodOptional<z.ZodString>;
-        displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
+        displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
     }, z.ZodTypeAny, "passthrough">>, "strip">>;
     agents: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodString;
@@ -557,8 +692,8 @@ declare const ConfigSchema: z.ZodObject<{
             token?: string | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        options: Record<string, unknown>;
         enabled: boolean;
+        options: Record<string, unknown>;
         port: number;
         provider: "cloudflare" | "ngrok" | "bore" | "tailscale";
         maxUserTunnels: number;
@@ -568,8 +703,8 @@ declare const ConfigSchema: z.ZodObject<{
             token?: string | undefined;
         };
     }, {
-        options?: Record<string, unknown> | undefined;
         enabled?: boolean | undefined;
+        options?: Record<string, unknown> | undefined;
         port?: number | undefined;
         provider?: "cloudflare" | "ngrok" | "bore" | "tailscale" | undefined;
         maxUserTunnels?: number | undefined;
@@ -690,6 +825,14 @@ declare const ConfigSchema: z.ZodObject<{
             }, z.ZodTypeAny, "passthrough">> | undefined;
         } | undefined;
     }>>>;
+    outputMode: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
+    agentSwitch: z.ZodDefault<z.ZodObject<{
+        labelHistory: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        labelHistory: boolean;
+    }, {
+        labelHistory?: boolean | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     api: {
         port: number;
@@ -702,8 +845,8 @@ declare const ConfigSchema: z.ZodObject<{
         workingDirectory?: string | undefined;
     }>;
     tunnel: {
-        options: Record<string, unknown>;
         enabled: boolean;
+        options: Record<string, unknown>;
         port: number;
         provider: "cloudflare" | "ngrok" | "bore" | "tailscale";
         maxUserTunnels: number;
@@ -713,24 +856,19 @@ declare const ConfigSchema: z.ZodObject<{
             token?: string | undefined;
         };
     };
-    channels: {
-        slack?: {
-            enabled: boolean;
-            allowedUserIds: string[];
-            channelPrefix: string;
-            autoCreateSession: boolean;
-            adapter?: "slack" | undefined;
-            botToken?: string | undefined;
-            appToken?: string | undefined;
-            signingSecret?: string | undefined;
-            notificationChannelId?: string | undefined;
-            startupChannelId?: string | undefined;
-        } | undefined;
-    } & {
+    usage: {
+        enabled: boolean;
+        warningThreshold: number;
+        currency: string;
+        retentionDays: number;
+        monthlyBudget?: number | undefined;
+    };
+    channels: {} & {
         [k: string]: z.objectOutputType<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             adapter: z.ZodOptional<z.ZodString>;
-            displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
+            displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+            outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
         }, z.ZodTypeAny, "passthrough">;
     };
     defaultAgent: string;
@@ -754,13 +892,6 @@ declare const ConfigSchema: z.ZodObject<{
     sessionStore: {
         ttlDays: number;
     };
-    usage: {
-        enabled: boolean;
-        warningThreshold: number;
-        currency: string;
-        retentionDays: number;
-        monthlyBudget?: number | undefined;
-    };
     integrations: Record<string, {
         installed: boolean;
         installedAt?: string | undefined;
@@ -781,25 +912,18 @@ declare const ConfigSchema: z.ZodObject<{
             }, z.ZodTypeAny, "passthrough">>;
         };
     };
+    agentSwitch: {
+        labelHistory: boolean;
+    };
+    instanceName?: string | undefined;
+    outputMode?: "low" | "medium" | "high" | undefined;
 }, {
-    channels: {
-        slack?: {
-            enabled?: boolean | undefined;
-            adapter?: "slack" | undefined;
-            botToken?: string | undefined;
-            appToken?: string | undefined;
-            signingSecret?: string | undefined;
-            notificationChannelId?: string | undefined;
-            allowedUserIds?: string[] | undefined;
-            channelPrefix?: string | undefined;
-            autoCreateSession?: boolean | undefined;
-            startupChannelId?: string | undefined;
-        } | undefined;
-    } & {
+    channels: {} & {
         [k: string]: z.objectInputType<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             adapter: z.ZodOptional<z.ZodString>;
-            displayVerbosity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>>;
+            displayVerbosity: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+            outputMode: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
         }, z.ZodTypeAny, "passthrough">;
     };
     defaultAgent: string;
@@ -814,8 +938,8 @@ declare const ConfigSchema: z.ZodObject<{
         workingDirectory?: string | undefined;
     }> | undefined;
     tunnel?: {
-        options?: Record<string, unknown> | undefined;
         enabled?: boolean | undefined;
+        options?: Record<string, unknown> | undefined;
         port?: number | undefined;
         provider?: "cloudflare" | "ngrok" | "bore" | "tailscale" | undefined;
         maxUserTunnels?: number | undefined;
@@ -825,6 +949,15 @@ declare const ConfigSchema: z.ZodObject<{
             token?: string | undefined;
         } | undefined;
     } | undefined;
+    usage?: {
+        enabled?: boolean | undefined;
+        monthlyBudget?: number | undefined;
+        warningThreshold?: number | undefined;
+        currency?: string | undefined;
+        retentionDays?: number | undefined;
+    } | undefined;
+    instanceName?: string | undefined;
+    outputMode?: "low" | "medium" | "high" | undefined;
     workspace?: {
         baseDir?: string | undefined;
     } | undefined;
@@ -845,13 +978,6 @@ declare const ConfigSchema: z.ZodObject<{
     sessionStore?: {
         ttlDays?: number | undefined;
     } | undefined;
-    usage?: {
-        enabled?: boolean | undefined;
-        monthlyBudget?: number | undefined;
-        warningThreshold?: number | undefined;
-        currency?: string | undefined;
-        retentionDays?: number | undefined;
-    } | undefined;
     integrations?: Record<string, {
         installed: boolean;
         installedAt?: string | undefined;
@@ -872,13 +998,16 @@ declare const ConfigSchema: z.ZodObject<{
             }, z.ZodTypeAny, "passthrough">> | undefined;
         } | undefined;
     } | undefined;
+    agentSwitch?: {
+        labelHistory?: boolean | undefined;
+    } | undefined;
 }>;
 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();
+    constructor(configPath?: string);
     load(): Promise<void>;
     get(): Config;
     save(updates: Record<string, unknown>, changePath?: string): Promise<void>;
@@ -890,7 +1019,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 +1028,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 +1043,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 +1061,25 @@ 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>;
+    stripTTSBlock?(sessionId: string): Promise<void>;
+    sendSkillCommands?(sessionId: string, commands: AgentCommand[]): Promise<void>;
+    cleanupSkillCommands?(sessionId: string): Promise<void>;
+    /** Flush skill commands that were queued before threadId was available */
+    flushPendingSkillCommands?(sessionId: string): Promise<void>;
+    cleanupSessionState?(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>;
@@ -944,18 +1091,12 @@ declare abstract class ChannelAdapter<TCore = unknown> implements IChannelAdapte
     deleteSessionThread(_sessionId: string): Promise<void>;
     sendSkillCommands(_sessionId: string, _commands: AgentCommand[]): Promise<void>;
     cleanupSkillCommands(_sessionId: string): Promise<void>;
+    cleanupSessionState(_sessionId: string): Promise<void>;
     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>;
+declare function nodeToWebWritable(nodeStream: NodeJS.WritableStream): WritableStream<Uint8Array>;
+declare function nodeToWebReadable(nodeStream: NodeJS.ReadableStream): ReadableStream<Uint8Array>;
 
 declare class StderrCapture {
     private maxLines;
@@ -1000,6 +1141,57 @@ 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;
+}
+
+type TraceLayer = "acp" | "core" | "telegram";
+/**
+ * Per-session debug trace logger. Writes JSONL files to <workingDirectory>/.log/.
+ * Only active when OPENACP_DEBUG=true. Zero overhead when disabled.
+ *
+ * Note: Uses appendFileSync for simplicity. This blocks the event loop briefly per write,
+ * which is acceptable for a debug-only tool. The DEBUG_ENABLED guard ensures zero overhead
+ * in production.
+ */
+declare class DebugTracer {
+    private sessionId;
+    private workingDirectory;
+    private dirCreated;
+    private logDir;
+    constructor(sessionId: string, workingDirectory: string);
+    log(layer: TraceLayer, data: Record<string, unknown>): void;
+    /** No-op cleanup — establishes the pattern for future async implementations */
+    destroy(): void;
+}
+
 interface AgentInstanceEvents {
     agent_event: (event: AgentEvent) => void;
 }
@@ -1007,21 +1199,38 @@ declare class AgentInstance extends TypedEmitter<AgentInstanceEvents> {
     private connection;
     private child;
     private stderrCapture;
-    private terminals;
+    private terminalManager;
+    private static mcpManager;
+    private _destroying;
     sessionId: string;
     agentName: string;
     promptCapabilities?: {
         image?: boolean;
         audio?: boolean;
     };
+    agentCapabilities?: AgentCapabilities;
+    /** Preserved from newSession/resumeSession response for ACP state propagation */
+    initialSessionResponse?: {
+        modes?: unknown;
+        configOptions?: unknown;
+        models?: unknown;
+    };
+    middlewareChain?: MiddlewareChain;
+    debugTracer: DebugTracer | null;
     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>;
+    setConfigOption(configId: string, value: SetConfigOptionValue): Promise<SetSessionConfigOptionResponse>;
+    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>;
 }
@@ -1043,7 +1252,9 @@ declare class AgentStore {
 declare class AgentCatalog {
     private store;
     private registryAgents;
-    constructor(store?: AgentStore);
+    private cachePath;
+    private agentsDir;
+    constructor(store?: AgentStore, cachePath?: string, agentsDir?: string);
     load(): void;
     fetchRegistry(): Promise<void>;
     refreshRegistryIfStale(): Promise<void>;
@@ -1120,11 +1331,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 +1355,31 @@ 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;
+    unregisterTTSProvider(name: string): 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 factory-managed providers from config. Preserves externally-registered providers (e.g. from plugins). */
+    refreshProviders(newConfig: SpeechServiceConfig): void;
 }
 
-declare class GroqSTT implements STTProvider {
+declare class GroqSTT implements STTProvider$1 {
     private apiKey;
     private defaultModel;
     readonly name = "groq";
@@ -1173,6 +1394,7 @@ interface SessionEvents {
     status_change: (from: SessionStatus, to: SessionStatus) => void;
     named: (name: string) => void;
     error: (error: Error) => void;
+    prompt_count_changed: (count: number) => void;
 }
 declare class Session extends TypedEmitter<SessionEvents> {
     id: string;
@@ -1186,10 +1408,17 @@ declare class Session extends TypedEmitter<SessionEvents> {
     name?: string;
     createdAt: Date;
     voiceMode: "off" | "next" | "on";
-    dangerousMode: boolean;
+    configOptions: ConfigOption[];
+    clientOverrides: {
+        bypassPermissions?: boolean;
+    };
+    agentCapabilities?: AgentCapabilities;
     archiving: boolean;
     promptCount: number;
-    log: Logger;
+    firstAgent: string;
+    agentSwitchHistory: AgentSwitchEntry[];
+    log: Logger$1;
+    middlewareChain?: MiddlewareChain;
     readonly permissionGate: PermissionGate;
     private readonly queue;
     private speechService?;
@@ -1222,12 +1451,27 @@ declare class Session extends TypedEmitter<SessionEvents> {
     private maybeTranscribeAudio;
     private processTTSResponse;
     private autoName;
-    generateSummary(timeoutMs?: number): Promise<string>;
     /** Fire-and-forget warm-up: primes model cache while user types their first message */
     warmup(): Promise<void>;
     private runWarmup;
+    setInitialConfigOptions(options: ConfigOption[]): void;
+    setAgentCapabilities(caps: AgentCapabilities | undefined): void;
+    getConfigOption(id: string): ConfigOption | undefined;
+    getConfigByCategory(category: string): ConfigOption | undefined;
+    getConfigValue(id: string): string | undefined;
+    /** Set session name explicitly and emit 'named' event */
+    setName(name: string): void;
+    updateConfigOptions(options: ConfigOption[]): Promise<void>;
+    /** Snapshot of current ACP state for persistence */
+    toAcpStateSnapshot(): NonNullable<SessionRecord["acpState"]>;
+    /** Check if the agent supports a specific session capability */
+    supportsCapability(cap: 'list' | 'fork' | 'close' | 'loadSession'): boolean;
     /** Cancel the current prompt and clear the queue. Stays in active state. */
     abortPrompt(): Promise<void>;
+    /** Search backward through agentSwitchHistory for the last entry matching agentName */
+    findLastSwitchEntry(agentName: string): AgentSwitchEntry | undefined;
+    /** Switch the agent instance in-place, preserving session identity */
+    switchAgent(agentName: string, createAgent: () => Promise<AgentInstance>): Promise<void>;
     destroy(): Promise<void>;
 }
 
@@ -1249,90 +1493,455 @@ 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;
-}
-
-interface ViewerEntry {
-    id: string;
-    type: 'file' | 'diff';
-    filePath?: string;
-    content: string;
-    oldContent?: string;
-    language?: string;
-    sessionId: string;
-    workingDirectory: string;
-    createdAt: number;
-    expiresAt: number;
+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;
+    /** Settings keys that can be copied when creating a new instance from this one */
+    inheritableKeys?: string[];
+}
+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;
+    /** Root of the OpenACP instance directory (e.g. ~/.openacp) */
+    instanceRoot?: string;
 }
-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;
+interface MigrateContext {
+    pluginName: string;
+    settings: SettingsAPI;
+    log: Logger;
 }
-
-declare class TunnelService {
-    private registry;
-    private store;
-    private server;
-    private config;
-    private systemPort;
-    constructor(config: TunnelConfig);
+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;
+}
+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;
+}
+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;
+}
+interface ConfigManager {
+    [key: string]: unknown;
+}
+interface EventBus$1 {
+    [key: string]: unknown;
+}
+/**
+ * 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;
+    /**
+     * Root directory for this OpenACP instance (default: ~/.openacp).
+     * Plugins should derive file paths from this instead of hardcoding ~/.openacp.
+     */
+    instanceRoot: string;
+}
+interface MiddlewarePayloadMap {
+    'message:incoming': {
+        channelId: string;
+        threadId: string;
+        userId: string;
+        text: string;
+        attachments?: Attachment[];
+    };
+    'message:outgoing': {
+        sessionId: string;
+        message: OutgoingMessage;
+    };
+    'agent:beforePrompt': {
+        sessionId: string;
+        text: string;
+        attachments?: Attachment[];
+    };
+    'agent:beforeEvent': {
+        sessionId: string;
+        event: AgentEvent;
+    };
+    'agent:afterEvent': {
+        sessionId: string;
+        event: AgentEvent;
+        outgoingMessage: OutgoingMessage;
+    };
+    'turn:start': {
+        sessionId: string;
+        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;
+    };
+    'config:beforeChange': {
+        sessionId: string;
+        configId: string;
+        oldValue: unknown;
+        newValue: unknown;
+    };
+    'agent:beforeCancel': {
+        sessionId: string;
+        reason?: string;
+    };
+    'agent:beforeSwitch': {
+        sessionId: string;
+        fromAgent: string;
+        toAgent: string;
+    };
+    'agent:afterSwitch': {
+        sessionId: string;
+        fromAgent: string;
+        toAgent: string;
+        resumed: boolean;
+    };
+}
+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;
+    }>;
+}
+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;
+    storeOutput(sessionId: string, label: string, output: string): string | null;
+}
+interface TunnelServiceInterface {
+    getPublicUrl(): string;
     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;
+    getStore(): ViewerStoreInterface;
     fileUrl(entryId: string): string;
     diffUrl(entryId: string): string;
+    outputUrl(entryId: string): string;
 }
 
 declare class MessageTransformer {
-    private tunnelService?;
-    constructor(tunnelService?: TunnelService | undefined);
+    tunnelService?: TunnelServiceInterface;
+    /** Cache rawInput from tool_call so it's available in tool_update (which often lacks it) */
+    private toolRawInputCache;
+    /** Cache viewer links generated from intermediate updates so completion events carry them */
+    private toolViewerCache;
+    constructor(tunnelService?: TunnelServiceInterface);
     transform(event: AgentEvent, sessionContext?: {
         id: string;
         workingDirectory: string;
     }): OutgoingMessage;
+    /** Check if rawInput is a non-empty object (not null, not {}) */
+    private isNonEmptyInput;
     private enrichWithViewerLinks;
 }
 
-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 SessionStore {
     save(record: SessionRecord): Promise<void>;
     get(sessionId: string): SessionRecord | undefined;
@@ -1352,7 +1961,9 @@ interface EventBusEvents {
         sessionId: string;
         status?: SessionStatus;
         name?: string;
-        dangerousMode?: boolean;
+        clientOverrides?: {
+            bypassPermissions?: boolean;
+        };
     }) => void;
     "session:deleted": (data: {
         sessionId: string;
@@ -1365,6 +1976,57 @@ interface EventBusEvents {
         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;
+    "usage:recorded": (data: UsageRecordEvent) => void;
+    "session:agentSwitch": (data: {
+        sessionId: string;
+        fromAgent: string;
+        toAgent: string;
+        status: "starting" | "succeeded" | "failed";
+        resumed?: boolean;
+        error?: string;
+    }) => void;
 }
 declare class EventBus extends TypedEmitter<EventBusEvents> {
 }
@@ -1373,6 +2035,7 @@ 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>;
@@ -1390,19 +2053,23 @@ declare class SessionManager {
         statuses?: string[];
     }): SessionRecord[];
     removeRecord(sessionId: string): Promise<void>;
+    /**
+     * Graceful shutdown: persist session state without killing agent subprocesses.
+     * Agent processes will exit naturally when the parent process terminates.
+     */
+    shutdownAll(): Promise<void>;
+    /**
+     * Forcefully destroy all sessions (kill agent subprocesses).
+     * Use only when sessions must be fully torn down (e.g. archive).
+     */
     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 +2077,8 @@ interface BridgeDeps {
     notificationManager: NotificationManager;
     sessionManager: SessionManager;
     eventBus?: EventBus;
-    fileService?: FileService;
+    fileService?: FileServiceInterface;
+    middlewareChain?: MiddlewareChain;
 }
 declare class SessionBridge {
     private session;
@@ -1421,78 +2089,86 @@ declare class SessionBridge {
     private sessionEventHandler?;
     private statusChangeHandler?;
     private namedHandler?;
-    constructor(session: Session, adapter: ChannelAdapter, deps: BridgeDeps);
+    private promptCountHandler?;
+    constructor(session: Session, adapter: IChannelAdapter, deps: BridgeDeps);
+    private get tracer();
+    /** Send message to adapter, optionally running through message:outgoing middleware */
+    private sendMessage;
     connect(): void;
     disconnect(): void;
     private wireAgentToSession;
     private wireSessionToAdapter;
+    private handleAgentEvent;
+    /** Persist current ACP state (configOptions, agentCapabilities) to session store as cache */
+    private persistAcpState;
     private wirePermissions;
     private wireLifecycle;
 }
 
-declare class UsageStore {
-    private filePath;
-    private retentionDays;
-    private records;
-    private debounceTimer;
-    private cleanupInterval;
-    private flushHandler;
-    constructor(filePath: string, retentionDays: number);
-    append(record: UsageRecord): void;
-    query(period: "today" | "week" | "month" | "all"): UsageSummary;
-    getMonthlyTotal(): {
-        totalCost: number;
-        currency: string;
-    };
-    cleanup(): void;
-    flushSync(): void;
-    destroy(): void;
-    private load;
-    private getCutoff;
-    private scheduleDiskWrite;
-}
-
-declare class UsageBudget {
-    private store;
-    private config;
-    private now;
-    private lastNotifiedStatus;
-    private lastNotifiedMonth;
-    constructor(store: UsageStore, config: UsageConfig, now?: () => Date);
-    check(): {
-        status: "ok" | "warning" | "exceeded";
-        message?: string;
-    };
-    getStatus(): {
-        status: "ok" | "warning" | "exceeded";
-        used: number;
-        budget: number;
-        percent: number;
-    };
+interface TunnelEntry {
+    port: number;
+    type: 'system' | 'user';
+    provider: string;
+    label?: string;
+    publicUrl?: string;
+    sessionId?: string;
+    status: 'stopped' | 'starting' | 'active' | 'failed';
+    retryCount: number;
+    createdAt: string;
 }
 
-interface SessionCreateParams {
-    channelId: string;
-    agentName: string;
+interface ViewerEntry {
+    id: string;
+    type: 'file' | 'diff' | 'output';
+    filePath?: string;
+    content: string;
+    oldContent?: string;
+    language?: string;
+    sessionId: string;
     workingDirectory: string;
-    resumeAgentSessionId?: string;
-    existingSessionId?: string;
-    initialName?: string;
+    createdAt: number;
+    expiresAt: number;
 }
-interface SideEffectDeps {
-    usageStore?: UsageStore | null;
-    usageBudget?: UsageBudget | null;
-    notificationManager: NotificationManager;
-    tunnelService?: TunnelService;
+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;
+    storeOutput(sessionId: string, label: string, output: string): string | null;
+    get(id: string): ViewerEntry | undefined;
+    private cleanup;
+    private isPathAllowed;
+    private detectLanguage;
+    destroy(): void;
 }
-declare class SessionFactory {
-    private agentManager;
-    private sessionManager;
-    private speechService;
-    private eventBus;
-    constructor(agentManager: AgentManager, sessionManager: SessionManager, speechService: SpeechService, eventBus: EventBus);
-    create(params: SessionCreateParams): Promise<Session>;
-    wireSideEffects(session: Session, deps: SideEffectDeps): void;
+
+declare class TunnelService {
+    private registry;
+    private store;
+    private server;
+    private config;
+    private systemPort;
+    private startError;
+    constructor(config: TunnelConfig, registryPath?: string, binDir?: string);
+    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;
+    getStartError(): string | undefined;
+    getStore(): ViewerStore;
+    fileUrl(entryId: string): string;
+    diffUrl(entryId: string): string;
+    outputUrl(entryId: string): string;
 }
 
 interface ContextProvider {
@@ -1509,6 +2185,8 @@ interface ContextQuery {
 interface ContextOptions {
     maxTokens?: number;
     limit?: number;
+    /** When true, insert `## [agentName]` headers at agent boundaries in merged history */
+    labelAgent?: boolean;
 }
 interface SessionInfo {
     checkpointId: string;
@@ -1543,47 +2221,246 @@ interface ContextResult {
 declare class ContextManager {
     private providers;
     private cache;
-    constructor();
+    constructor(cachePath?: string);
     register(provider: ContextProvider): void;
     getProvider(repoPath: string): Promise<ContextProvider | null>;
     listSessions(query: ContextQuery): Promise<SessionListResult | null>;
     buildContext(query: ContextQuery, options?: ContextOptions): Promise<ContextResult | null>;
 }
 
-declare class OpenACPCore {
-    configManager: ConfigManager;
-    agentCatalog: AgentCatalog;
-    agentManager: AgentManager;
-    sessionManager: SessionManager;
+interface SessionCreateParams {
+    channelId: string;
+    agentName: string;
+    workingDirectory: string;
+    resumeAgentSessionId?: string;
+    existingSessionId?: string;
+    initialName?: string;
+}
+interface SideEffectDeps {
+    eventBus: EventBus;
     notificationManager: NotificationManager;
+    tunnelService?: TunnelService;
+}
+declare class SessionFactory {
+    private agentManager;
+    private sessionManager;
+    private speechServiceAccessor;
+    private eventBus;
+    private instanceRoot?;
+    middlewareChain?: MiddlewareChain;
+    private resumeLocks;
+    /** Injected by Core after construction — needed for lazy resume error feedback */
+    adapters?: Map<string, IChannelAdapter>;
+    /** Injected by Core after construction — needed for lazy resume store lookup */
+    sessionStore?: SessionStore | null;
+    /** Injected by Core — creates full session with thread + bridge + persist */
+    createFullSession?: (params: SessionCreateParams & {
+        threadId?: string;
+        createThread?: boolean;
+    }) => Promise<Session>;
+    /** Injected by Core — needed for resolving default agent and workspace */
+    configManager?: ConfigManager$1;
+    /** Injected by Core — needed for resolving agent definitions */
+    agentCatalog?: AgentCatalog;
+    /** Injected by Core — needed for context-aware session creation */
+    getContextManager?: () => ContextManager | undefined;
+    constructor(agentManager: AgentManager, sessionManager: SessionManager, speechServiceAccessor: SpeechService | (() => SpeechService), eventBus: EventBus, instanceRoot?: string | undefined);
+    private get speechService();
+    create(params: SessionCreateParams): Promise<Session>;
+    /**
+     * Get active session by thread, or attempt lazy resume from store.
+     * Used by adapter command handlers and handleMessage().
+     */
+    getOrResume(channelId: string, threadId: string): Promise<Session | null>;
+    private lazyResume;
+    handleNewSession(channelId: string, agentName?: string, workspacePath?: string, options?: {
+        createThread?: boolean;
+    }): Promise<Session>;
+    /** NOTE: handleNewChat is currently dead code — never called outside core.ts itself.
+     *  Moving it anyway for completeness; can be removed in a future cleanup. */
+    handleNewChat(channelId: string, currentThreadId: string): Promise<Session | null>;
+    createSessionWithContext(params: {
+        channelId: string;
+        agentName: string;
+        workingDirectory: string;
+        contextQuery: ContextQuery;
+        contextOptions?: ContextOptions;
+        createThread?: boolean;
+    }): Promise<{
+        session: Session;
+        contextResult: ContextResult | null;
+    }>;
+    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;
+    /** Root directory for this OpenACP instance (default: ~/.openacp) */
+    instanceRoot?: string;
+}
+declare class LifecycleManager {
+    readonly serviceRegistry: ServiceRegistry;
+    readonly middlewareChain: MiddlewareChain;
+    readonly errorTracker: ErrorTracker;
+    private eventBus;
+    private storagePath;
+    private sessions;
+    private config;
+    private core;
+    private log;
+    settingsManager: SettingsManager | undefined;
+    private pluginRegistry;
+    private instanceRoot;
+    private contexts;
+    private loadOrder;
+    private _loaded;
+    private _failed;
+    get loadedPlugins(): string[];
+    get failedPlugins(): string[];
+    get registry(): PluginRegistry | undefined;
+    constructor(opts?: LifecycleManagerOpts);
+    private getPluginLogger;
+    boot(plugins: OpenACPPlugin[]): Promise<void>;
+    unloadPlugin(name: string): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+interface InstanceContext {
+    id: string;
+    root: string;
+    isGlobal: boolean;
+    paths: {
+        config: string;
+        sessions: string;
+        agents: string;
+        registryCache: string;
+        plugins: string;
+        pluginsData: string;
+        pluginRegistry: string;
+        logs: string;
+        pid: string;
+        running: string;
+        apiPort: string;
+        apiSecret: string;
+        bin: string;
+        cache: string;
+        tunnels: string;
+        agentsDir: string;
+    };
+}
+
+declare class OpenACPCore {
+    configManager: ConfigManager$1;
+    agentCatalog: AgentCatalog;
+    agentManager: AgentManager;
+    sessionManager: SessionManager;
     messageTransformer: MessageTransformer;
-    fileService: FileService;
-    readonly speechService: SpeechService;
-    securityGuard: SecurityGuard;
-    adapters: Map<string, ChannelAdapter>;
+    adapters: Map<string, IChannelAdapter>;
+    /** sessionId → SessionBridge — tracks active bridges for disconnect/reconnect during agent switch */
+    private bridges;
     /** Set by main.ts — triggers graceful shutdown with restart exit code */
     requestRestart: (() => Promise<void>) | null;
     private _tunnelService?;
     private sessionStore;
-    private resumeLocks;
     eventBus: EventBus;
     sessionFactory: SessionFactory;
-    readonly usageStore: UsageStore | null;
-    readonly usageBudget: UsageBudget | null;
-    readonly contextManager: ContextManager;
-    constructor(configManager: ConfigManager);
+    readonly lifecycleManager: LifecycleManager;
+    private agentSwitchHandler;
+    readonly instanceContext?: InstanceContext;
+    private getService;
+    get securityGuard(): SecurityGuard;
+    get notificationManager(): NotificationManager;
+    get fileService(): FileServiceInterface;
+    get speechService(): SpeechService;
+    get contextManager(): ContextManager;
+    constructor(configManager: ConfigManager$1, ctx?: InstanceContext);
     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<{
-        ok: true;
-        summary: string;
-    } | {
-        ok: false;
-        error: string;
-    }>;
     archiveSession(sessionId: string): Promise<{
         ok: true;
     } | {
@@ -1599,6 +2476,7 @@ declare class OpenACPCore {
         existingSessionId?: string;
         createThread?: boolean;
         initialName?: string;
+        threadId?: string;
     }): Promise<Session>;
     handleNewSession(channelId: string, agentName?: string, workspacePath?: string, options?: {
         createThread?: boolean;
@@ -1625,40 +2503,137 @@ declare class OpenACPCore {
         session: Session;
         contextResult: ContextResult | null;
     }>;
-    /**
-     * Get active session by thread, or attempt lazy resume from store.
-     * Used by adapter command handlers that need a session but don't go through handleMessage().
-     */
+    switchSessionAgent(sessionId: string, toAgent: string): Promise<{
+        resumed: boolean;
+    }>;
     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 RegisteredCommand extends CommandDef {
+    /** Scope extracted from pluginName, e.g. '@openacp/speech' → 'speech' */
+    scope?: string;
+}
+/**
+ * Central command registry with namespace resolution and adapter-specific overrides.
+ *
+ * Namespace rules:
+ * - System commands always own the short name.
+ * - Among plugins, the first to register wins the short name.
+ * - Every plugin command also gets a qualified name: `scope:name`.
+ * - Adapter plugins (@openacp/telegram, @openacp/discord)
+ *   registering a command that already exists → stored as an override
+ *   keyed by `channelId:commandName`, used when channelId matches.
+ */
+declare class CommandRegistry {
+    /** Main registry: short names + qualified names → RegisteredCommand */
+    private commands;
+    /** Adapter-specific overrides: `channelId:commandName` → RegisteredCommand */
+    private overrides;
+    private static ADAPTER_SCOPES;
+    /**
+     * Register a command definition.
+     * @param def - Command definition
+     * @param pluginName - Plugin that owns the command (set automatically by PluginContext)
+     */
+    register(def: CommandDef, pluginName?: string): void;
+    /** Retrieve a command by name (short or qualified). */
+    get(name: string): RegisteredCommand | undefined;
+    /** Remove a command by name (short or qualified). Also removes its qualified name entry. */
+    unregister(name: string): void;
+    /** Remove all commands registered by a given plugin. */
+    unregisterByPlugin(pluginName: string): void;
+    /** Return all unique commands (deduplicated — each command appears once). */
+    getAll(): RegisteredCommand[];
+    /** Filter commands by category. */
+    getByCategory(category: 'system' | 'plugin'): RegisteredCommand[];
+    /**
+     * Parse and execute a command string.
+     * @param commandString - Full command string, e.g. "/greet hello world"
+     * @param baseArgs - Base arguments (channelId, userId, etc.)
+     * @returns CommandResponse
+     */
+    execute(commandString: string, baseArgs: CommandArgs): Promise<CommandResponse>;
+    /** Extract scope from plugin name: '@openacp/speech' → 'speech', 'my-plugin' → 'my-plugin' */
+    static extractScope(pluginName: string): string;
 }
 
-interface AdapterFactory {
+interface CheckResult {
+    status: "pass" | "warn" | "fail";
+    message: string;
+    fixable?: boolean;
+    fixRisk?: "safe" | "risky";
+    fix?: () => Promise<FixResult>;
+}
+interface FixResult {
+    success: boolean;
+    message: string;
+}
+interface DoctorReport {
+    categories: CategoryResult[];
+    summary: {
+        passed: number;
+        warnings: number;
+        failed: number;
+        fixed: number;
+    };
+    pendingFixes: PendingFix[];
+}
+interface CategoryResult {
     name: string;
-    createAdapter(core: OpenACPCore, config: ChannelConfig): ChannelAdapter;
+    results: CheckResult[];
+}
+interface PendingFix {
+    category: string;
+    message: string;
+    fix: () => Promise<FixResult>;
+}
+
+declare class DoctorEngine {
+    private dryRun;
+    private dataDir;
+    constructor(options?: {
+        dryRun?: boolean;
+        dataDir?: string;
+    });
+    runAll(): Promise<DoctorReport>;
+    private buildContext;
+}
+
+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 getPidPath(root?: string): string;
 declare function getStatus(pidPath?: string): {
     running: boolean;
     pid?: number;
 };
-declare function startDaemon(pidPath?: string, logDir?: string): {
+declare function startDaemon(pidPath?: string, logDir?: string, instanceRoot?: string): {
     pid: number;
 } | {
     error: string;
 };
-declare function stopDaemon(pidPath?: string): Promise<{
+declare function stopDaemon(pidPath?: string, instanceRoot?: string): Promise<{
     stopped: boolean;
     pid?: number;
     error?: string;
 }>;
-declare function getPidPath(): string;
 
 declare function isAutoStartSupported(): boolean;
 declare function installAutoStart(logDir: string): {
@@ -1671,7 +2646,142 @@ 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);
+    /**
+     * Remove session file directories older than maxAgeDays.
+     * Called on startup to prevent unbounded disk growth.
+     */
+    cleanupOldFiles(maxAgeDays: number): Promise<number>;
+    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 ApiConfig {
+    port: number;
+    host: string;
+}
+
+interface StoredToken {
+    id: string;
+    name: string;
+    role: string;
+    scopes?: string[];
+    createdAt: string;
+    refreshDeadline: string;
+    lastUsedAt?: string;
+    revoked: boolean;
+}
+interface CreateTokenOpts {
+    role: string;
+    name: string;
+    expire: string;
+    scopes?: string[];
+}
+
+declare class TokenStore {
+    private filePath;
+    private tokens;
+    private savePromise;
+    private savePending;
+    constructor(filePath: string);
+    load(): Promise<void>;
+    save(): Promise<void>;
+    private scheduleSave;
+    create(opts: CreateTokenOpts): StoredToken;
+    get(id: string): StoredToken | undefined;
+    revoke(id: string): void;
+    list(): StoredToken[];
+    private lastUsedSaveTimer;
+    updateLastUsed(id: string): void;
+    /** Wait for any in-flight save to complete */
+    flush(): Promise<void>;
+    destroy(): void;
+    cleanup(): void;
+}
+
+interface ApiServerOptions {
+    port: number;
+    host: string;
+    getSecret: () => string;
+    getJwtSecret: () => string;
+    tokenStore: TokenStore;
+    logger?: boolean;
+}
+interface ApiServerInstance {
+    app: FastifyInstance;
+    start(): Promise<{
+        port: number;
+        host: string;
+    }>;
+    stop(): Promise<void>;
+    registerPlugin(prefix: string, plugin: FastifyPluginAsync, opts?: {
+        auth?: boolean;
+    }): void;
+}
+declare function createApiServer(options: ApiServerOptions): Promise<ApiServerInstance>;
+
+interface ApiServerService {
+    registerPlugin(prefix: string, plugin: FastifyPluginAsync, opts?: {
+        auth?: boolean;
+    }): void;
+    authPreHandler: preHandlerHookHandler;
+    requireScopes(...scopes: string[]): preHandlerHookHandler;
+    requireRole(role: string): preHandlerHookHandler;
+    getPort(): number;
+    getBaseUrl(): string;
+    getTunnelUrl(): string | null;
+}
+declare function createApiServerService(server: ApiServerInstance, getPort: () => number, getBaseUrl: () => string, getTunnelUrl: () => string | null, authPreHandler: preHandlerHookHandler): ApiServerService;
+
+interface SessionStats {
+    active: number;
+    total: number;
+}
+declare class SSEManager {
+    private eventBus;
+    private getSessionStats;
+    private startedAt;
+    private sseConnections;
+    private sseCleanupHandlers;
+    private healthInterval?;
+    private boundHandlers;
+    constructor(eventBus: EventBus | undefined, getSessionStats: () => SessionStats, startedAt: number);
+    setup(): void;
+    handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void;
+    broadcast(event: string, data: unknown): void;
+    /**
+     * Returns a Fastify route handler that hijacks the response
+     * and delegates to the raw http SSE handler.
+     */
+    createFastifyHandler(): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    stop(): void;
+}
+
+declare class StaticServer {
+    private uiDir;
+    constructor(uiDir?: string);
+    isAvailable(): boolean;
+    serve(req: http.IncomingMessage, res: http.ServerResponse): boolean;
+}
 
 interface TopicInfo {
     sessionId: string;
@@ -1718,89 +2828,393 @@ declare class TopicManager {
     private isSystemTopic;
 }
 
-interface ApiConfig {
-    port: number;
-    host: string;
+declare class EntireProvider implements ContextProvider {
+    readonly name = "entire";
+    isAvailable(repoPath: string): Promise<boolean>;
+    listSessions(query: ContextQuery): Promise<SessionListResult>;
+    buildContext(query: ContextQuery, options?: ContextOptions): Promise<ContextResult>;
+    private buildSessionMarkdowns;
+    private resolveSessions;
+    private buildTitle;
 }
-declare class ApiServer {
-    private core;
+
+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): 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): 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 topicManager?;
-    private server;
-    private actualPort;
-    private portFilePath;
-    private startedAt;
-    private secret;
-    private secretFilePath;
-    private sseManager;
-    private staticServer;
-    private router;
-    constructor(core: OpenACPCore, config: ApiConfig, portFilePath?: string, topicManager?: TopicManager | undefined, secretFilePath?: string, uiDir?: string);
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    getPort(): number;
-    getSecret(): string;
-    private writePortFile;
-    private removePortFile;
-    private loadOrCreateSecret;
-    private authenticate;
-    private handleRequest;
-    private sendJson;
-    private readBody;
+    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 SessionStats {
-    active: number;
-    total: number;
+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 SSEManager {
-    private eventBus;
-    private getSessionStats;
-    private startedAt;
-    private sseConnections;
-    private sseCleanupHandlers;
-    private healthInterval?;
-    private boundHandlers;
-    constructor(eventBus: EventBus | undefined, getSessionStats: () => SessionStats, startedAt: number);
-    setup(): void;
-    handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void;
-    broadcast(event: string, data: unknown): void;
-    stop(): void;
+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;
 }
 
-declare class StaticServer {
-    private uiDir;
-    constructor(uiDir?: string);
-    isAvailable(): boolean;
-    serve(req: http.IncomingMessage, res: http.ServerResponse): boolean;
+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 ConfigFieldDef {
-    path: string;
-    displayName: string;
-    group: string;
-    type: "toggle" | "select" | "number" | "string";
-    options?: string[] | ((config: Config) => string[]);
-    scope: "safe" | "sensitive";
-    hotReload: boolean;
+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;
 }
-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>;
-    listSessions(query: ContextQuery): Promise<SessionListResult>;
-    buildContext(query: ContextQuery, options?: ContextOptions): Promise<ContextResult>;
-    private buildSessionMarkdowns;
-    private resolveSessions;
-    private buildTitle;
+interface ToolEntry {
+    id: string;
+    name: string;
+    kind: string;
+    rawInput: unknown;
+    content: string | null;
+    status: string;
+    viewerLinks?: ViewerLinks;
+    diffStats?: {
+        added: number;
+        removed: number;
+    };
+    displaySummary?: string;
+    displayTitle?: string;
+    displayKind?: string;
+    isNoise: boolean;
+}
+declare class ToolStateMap {
+    private entries;
+    private pendingUpdates;
+    /**
+     * Creates or updates an entry from a tool_call event.
+     * If a pending update exists for this id, applies it immediately.
+     */
+    upsert(meta: ToolCallMeta, kind: string, rawInput: unknown): ToolEntry;
+    /**
+     * Updates an existing entry from a tool_call_update event.
+     * If the entry doesn't exist yet (out-of-order delivery), buffers the update.
+     */
+    merge(id: string, status: string, rawInput?: unknown, content?: string | null, viewerLinks?: ViewerLinks, diffStats?: {
+        added: number;
+        removed: number;
+    }): ToolEntry | undefined;
+    private _applyUpdate;
+    get(id: string): ToolEntry | undefined;
+    clear(): void;
+}
+declare class ThoughtBuffer {
+    private chunks;
+    private sealed;
+    append(chunk: string): void;
+    seal(): string;
+    getText(): string;
+    isSealed(): boolean;
+    reset(): void;
 }
 
+interface ToolDisplaySpec {
+    id: string;
+    kind: string;
+    icon: string;
+    title: string;
+    description: string | null;
+    command: string | null;
+    inputContent: string | null;
+    outputSummary: string | null;
+    outputContent: string | null;
+    diffStats: {
+        added: number;
+        removed: number;
+    } | null;
+    viewerLinks?: ViewerLinks;
+    outputViewerLink?: string;
+    outputFallbackContent?: string;
+    status: string;
+    isNoise: boolean;
+    isHidden: boolean;
+}
+interface ThoughtDisplaySpec {
+    indicator: string;
+    content: string | null;
+}
+declare class DisplaySpecBuilder {
+    private tunnelService?;
+    constructor(tunnelService?: TunnelServiceInterface | undefined);
+    buildToolSpec(entry: ToolEntry, mode: OutputMode, sessionContext?: {
+        id: string;
+        workingDirectory: string;
+    }): ToolDisplaySpec;
+    buildThoughtSpec(content: string, mode: OutputMode): ThoughtDisplaySpec;
+}
+
+interface UsageData {
+    tokensUsed?: number;
+    contextSize?: number;
+    cost?: number;
+}
+interface ToolCardSnapshot {
+    specs: ToolDisplaySpec[];
+    planEntries?: PlanEntry[];
+    usage?: UsageData;
+    totalVisible: number;
+    completedVisible: number;
+    allComplete: boolean;
+}
+interface ToolCardStateConfig {
+    onFlush: (snapshot: ToolCardSnapshot) => void;
+}
+declare class ToolCardState {
+    private specs;
+    private planEntries?;
+    private usage?;
+    private finalized;
+    private isFirstFlush;
+    private debounceTimer?;
+    private onFlush;
+    constructor(config: ToolCardStateConfig);
+    updateFromSpec(spec: ToolDisplaySpec): void;
+    updatePlan(entries: PlanEntry[]): void;
+    appendUsage(usage: UsageData): void;
+    finalize(): void;
+    destroy(): void;
+    hasContent(): boolean;
+    private snapshot;
+    private flush;
+    private scheduleFlush;
+    private clearDebounce;
+}
+
+declare function progressBar(ratio: number, length?: number): string;
+declare function formatTokens(n: number): string;
+declare function stripCodeFences(text: string): string;
+declare function truncateContent(text: string, maxLen: number): string;
+declare function splitMessage(text: string, maxLength: number): string[];
+
+declare function extractContentText(content: unknown, depth?: number): string;
+declare function formatToolSummary(name: string, rawInput: unknown, displaySummary?: string): string;
+declare function formatToolTitle(name: string, rawInput: unknown, displayTitle?: string): string;
+declare function resolveToolIcon(tool: {
+    status?: string;
+    displayKind?: string;
+    kind?: string;
+}): string;
+
+interface ConfigManagerLike {
+    get(): Record<string, unknown>;
+}
+interface SessionManagerLike {
+    getSessionRecord(id: string): {
+        outputMode?: OutputMode;
+    } | undefined;
+}
+declare class OutputModeResolver {
+    resolve(configManager: ConfigManagerLike, adapterName: string, sessionId?: string, sessionManager?: SessionManagerLike): OutputMode;
+}
+
+/**
+ * OpenACP Product Guide — comprehensive reference for the AI assistant.
+ * The assistant reads this at runtime to answer user questions about features.
+ */
+declare const PRODUCT_GUIDE = "\n# OpenACP \u2014 Product Guide\n\nOpenACP lets you chat with AI coding agents (like Claude Code) through messaging platforms (Telegram, Discord).\nYou type messages in your chat platform, the agent reads/writes/runs code in your project folder, and results stream back in real time.\n\n---\n\n## Quick Start\n\n1. Start OpenACP: `openacp` (or `openacp start` for background daemon)\n2. Open your messaging platform (Telegram group or Discord server) \u2014 you'll see the Assistant topic/thread\n3. Tap/click \uD83C\uDD95 New Session or type /new\n4. Pick an agent and a project folder\n5. Chat in the session topic/thread \u2014 the agent works on your code\n\n---\n\n## Core Concepts\n\n### Sessions\nA session = one conversation with one AI agent working in one project folder.\nEach session gets its own topic (Telegram) or forum thread (Discord). Chat there to give instructions to the agent.\n\n### Agents\nAn agent is an AI coding tool (e.g., Claude Code, Gemini, Cursor, Codex, etc.).\nOpenACP supports 28+ agents from the official ACP Registry (agentclientprotocol.com).\nYou can install multiple agents and choose which one to use per session.\nThe default agent is used when you don't specify one.\n\n### Agent Management\n- Browse agents: `/agents` in your chat platform or `openacp agents` in CLI\n- Install: tap the install button in /agents, or `openacp agents install <name>`\n- Uninstall: `openacp agents uninstall <name>`\n- Setup/login: `openacp agents run <name> -- <args>` (e.g., `openacp agents run gemini -- auth login`)\n- Details: `openacp agents info <name>` shows version, dependencies, and setup steps\n\nSome agents need additional setup before they can be used:\n- Claude: requires `claude login`\n- Gemini: requires `openacp agents run gemini -- auth login`\n- Codex: requires setting `OPENAI_API_KEY` environment variable\n- GitHub Copilot: requires `openacp agents run copilot -- auth login`\n\nAgents are installed in three ways depending on the agent:\n- **npx** \u2014 Node.js agents, downloaded automatically on first use\n- **uvx** \u2014 Python agents, downloaded automatically on first use\n- **binary** \u2014 Platform-specific binaries, downloaded to `~/.openacp/agents/`\n\n### Project Folder (Workspace)\nThe directory where the agent reads, writes, and runs code.\nWhen creating a session, you choose which folder the agent works in.\nYou can type a full path like `~/code/my-project` or just a name like `my-project` (it becomes `<base-dir>/my-project`).\n\n### System Topics\n- **Assistant** \u2014 Always-on helper that can answer questions, create sessions, check status, troubleshoot\n- **Notifications** \u2014 System alerts (permission requests, session errors, completions)\n\n---\n\n## Creating Sessions\n\n### From menu\nTap \uD83C\uDD95 New Session \u2192 choose agent (if multiple) \u2192 choose project folder \u2192 confirm\n\n### From command\n- `/new` \u2014 Interactive flow (asks agent + folder)\n- `/new claude ~/code/my-project` \u2014 Create directly with specific agent and folder\n\n### From Assistant topic\nJust ask: \"Create a session for my-project with claude\" \u2014 the assistant handles it\n\n### Quick new chat\n`/newchat` in a session topic \u2014 creates new session with same agent and folder as current one\n\n---\n\n## Working with Sessions\n\n### Chat\nType messages in the session topic. The agent responds with code changes, explanations, tool outputs.\n\n### What you see while the agent works\n- **\uD83D\uDCAD Thinking indicator** \u2014 Shows when the agent is reasoning, with elapsed time\n- **Text responses** \u2014 Streamed in real time, updated every few seconds\n- **Tool calls** \u2014 When the agent runs commands or edits files, you see tool name, input, status, and output\n- **\uD83D\uDCCB Plan card** \u2014 Visual task progress with completed/in-progress/pending items and progress bar\n- **\"View File\" / \"View Diff\" buttons** \u2014 Opens in browser with Monaco editor (requires tunnel)\n\n### Session lifecycle\n1. **Creating** \u2014 Topic created, agent spawning\n2. **Warming up** \u2014 Agent primes its cache (happens automatically, invisible to you)\n3. **Active** \u2014 Ready for your messages\n4. **Auto-naming** \u2014 After your first message, the session gets a descriptive name (agent summarizes in ~5 words). The topic title updates automatically.\n5. **Finished/Error** \u2014 Session completed or hit an error\n\n### Agent skills\nSome agents provide slash commands (e.g., /compact, /review). Available skills are pinned in the session topic.\n\n### Permission requests\nWhen the agent wants to run a command, it asks for permission.\nYou see buttons: \u2705 Allow, \u274C Reject (and sometimes \"Always Allow\").\nA notification also appears in the Notifications topic with a link to the request.\n\n### Dangerous mode\nAuto-approves ALL permission requests \u2014 the agent runs any command without asking.\n- Enable: `/enable_dangerous` or tap the \u2620\uFE0F button in the session\n- Disable: `/disable_dangerous` or tap the \uD83D\uDD10 button\n- \u26A0\uFE0F Use with caution \u2014 the agent can execute anything\n\n### Session timeout\nIdle sessions are automatically cancelled after a configurable timeout (default: 60 minutes).\nConfigure via `security.sessionTimeoutMinutes` in config.\n\n---\n\n## Session Transfer (Handoff)\n\n### Chat \u2192 Terminal\n1. Type `/handoff` in a session topic/thread\n2. You get a command like `claude --resume <SESSION_ID>`\n3. Copy and run it in your terminal \u2014 the session continues there with full conversation history\n\n### Terminal \u2192 Chat\n1. First time: run `openacp integrate claude` to install the handoff skill (one-time setup)\n2. In Claude Code, use the /openacp:handoff slash command\n3. The session appears as a new topic/thread and you can continue chatting there\n\n### How it works\n- The agent session ID is shared between platforms\n- Conversation history is preserved \u2014 pick up where you left off\n- The agent that supports resume (e.g., Claude with `--resume`) handles the actual transfer\n\n---\n\n## Managing Sessions\n\n### Status\n- `/status` \u2014 Shows active sessions count and details\n- Ask the Assistant: \"What sessions are running?\"\n\n### List all sessions\n- `/sessions` \u2014 Shows all sessions with status (active, finished, error)\n\n### Cancel\n- `/cancel` in a session topic \u2014 cancels that session\n- Ask the Assistant: \"Cancel the stuck session\"\n\n### Cleanup\n- From `/sessions` \u2192 tap cleanup buttons (finished, errors, all)\n- Ask the Assistant: \"Clean up old sessions\"\n\n---\n\n## Assistant Topic\n\nThe Assistant is an always-on AI helper in its own topic. It can:\n- Answer questions about OpenACP\n- Create sessions for you\n- Check status and health\n- Cancel sessions\n- Clean up old sessions\n- Troubleshoot issues\n- Manage configuration\n\nJust chat naturally: \"How do I create a session?\", \"What's the status?\", \"Something is stuck\"\n\n### Clear history\n`/clear` in the Assistant topic \u2014 resets the conversation\n\n---\n\n## System Commands\n\n| Command | Where | What it does |\n|---------|-------|-------------|\n| `/new [agent] [path]` | Anywhere | Create new session |\n| `/newchat` | Session topic | New session, same agent + folder |\n| `/cancel` | Session topic | Cancel current session |\n| `/status` | Anywhere | Show status |\n| `/sessions` | Anywhere | List all sessions |\n| `/agents` | Anywhere | Browse & install agents from ACP Registry |\n| `/install <name>` | Anywhere | Install an agent |\n| `/enable_dangerous` | Session topic | Auto-approve all permissions |\n| `/disable_dangerous` | Session topic | Restore permission prompts |\n| `/handoff` | Session topic | Transfer session to terminal |\n| `/clear` | Assistant topic | Clear assistant history |\n| `/menu` | Anywhere | Show action menu |\n| `/help` | Anywhere | Show help |\n| `/restart` | Anywhere | Restart OpenACP |\n| `/update` | Anywhere | Update to latest version |\n| `/integrate` | Anywhere | Manage agent integrations |\n\n---\n\n## Menu Buttons\n\n| Button | Action |\n|--------|--------|\n| \uD83C\uDD95 New Session | Create new session (interactive) |\n| \uD83D\uDCCB Sessions | List all sessions with cleanup options |\n| \uD83D\uDCCA Status | Show active/total session count |\n| \uD83E\uDD16 Agents | List available agents |\n| \uD83D\uDD17 Integrate | Manage agent integrations |\n| \u2753 Help | Show help text |\n| \uD83D\uDD04 Restart | Restart OpenACP |\n| \u2B06\uFE0F Update | Check and install updates |\n\n---\n\n## CLI Commands\n\n### Server\n- `openacp` \u2014 Start (uses configured mode: foreground or daemon)\n- `openacp start` \u2014 Start as background daemon\n- `openacp stop` \u2014 Stop daemon\n- `openacp status` \u2014 Show daemon status\n- `openacp logs` \u2014 Tail daemon logs\n- `openacp --foreground` \u2014 Force foreground mode (useful for debugging or containers)\n\n### Auto-start (run on boot)\n- macOS: installs a LaunchAgent in `~/Library/LaunchAgents/`\n- Linux: installs a systemd user service in `~/.config/systemd/user/`\n- Enabled automatically when you start the daemon. Remove with `openacp stop`.\n\n### Configuration\n- `openacp config` \u2014 Interactive config editor\n- `openacp reset` \u2014 Delete all data and start fresh\n\n### Agent Management (CLI)\n- `openacp agents` \u2014 List all agents (installed + available from ACP Registry)\n- `openacp agents install <name>` \u2014 Install an agent\n- `openacp agents uninstall <name>` \u2014 Remove an agent\n- `openacp agents info <name>` \u2014 Show details, dependencies, and setup guide\n- `openacp agents run <name> [-- args]` \u2014 Run agent CLI directly (for login, config, etc.)\n- `openacp agents refresh` \u2014 Force-refresh registry cache\n\n### Plugins\n- `openacp install <package>` \u2014 Install adapter plugin\n- `openacp uninstall <package>` \u2014 Remove adapter plugin\n- `openacp plugins` \u2014 List installed plugins\n\n### Integration\n- `openacp integrate <agent>` \u2014 Install agent integration (e.g., Claude handoff skill)\n- `openacp integrate <agent> --uninstall` \u2014 Remove integration\n\n### API (requires running daemon)\n`openacp api <command>` \u2014 Interact with running daemon:\n\n| Command | Description |\n|---------|-------------|\n| `status` | List active sessions |\n| `session <id>` | Session details |\n| `new <agent> <path>` | Create session |\n| `send <id> \"text\"` | Send prompt |\n| `cancel <id>` | Cancel session |\n| `dangerous <id> on/off` | Toggle dangerous mode |\n| `topics [--status x,y]` | List topics |\n| `delete-topic <id> [--force]` | Delete topic |\n| `cleanup [--status x,y]` | Cleanup old topics |\n| `agents` | List agents |\n| `health` | System health |\n| `config` | Show config |\n| `config set <key> <value>` | Update config |\n| `adapters` | List adapters |\n| `tunnel` | Tunnel status |\n| `notify \"message\"` | Send notification |\n| `version` | Daemon version |\n| `restart` | Restart daemon |\n\n---\n\n## File Viewer (Tunnel)\n\nWhen tunnel is enabled, file edits and diffs get \"View\" buttons that open in your browser:\n- **Monaco Editor** \u2014 Full VS Code editor with syntax highlighting\n- **Diff viewer** \u2014 Side-by-side or inline comparison\n- **Line highlighting** \u2014 Click lines to highlight\n- Dark/light theme toggle\n\n### Setup\nEnable in config: set `tunnel.enabled` to `true`.\nProviders: Cloudflare (default, free), ngrok, bore, Tailscale Funnel.\n\n### Port Tunneling\n\nExpose any local port (dev servers, APIs, etc.) to the internet:\n\n**CLI commands** (agent can call these directly):\n- `openacp tunnel add <port> --label <name>` \u2014 Create tunnel to a local port\n- `openacp tunnel list` \u2014 List active tunnels\n- `openacp tunnel stop <port>` \u2014 Stop a tunnel\n- `openacp tunnel stop-all` \u2014 Stop all user tunnels\n\n**Telegram commands**:\n- `/tunnel <port> [label]` \u2014 Create tunnel\n- `/tunnels` \u2014 List active tunnels\n- `/tunnel stop <port>` \u2014 Stop tunnel\n\nExample: after starting a dev server on port 3000, run `openacp tunnel add 3000 --label my-app` to get a public URL.\n\n---\n\n## Configuration\n\nConfig file: `~/.openacp/config.json`\n\n### Channels\n- **channels.telegram.botToken** \u2014 Your Telegram bot token\n- **channels.telegram.chatId** \u2014 Your Telegram supergroup ID\n- **channels.discord.botToken** \u2014 Your Discord bot token\n- **channels.discord.guildId** \u2014 Your Discord server (guild) ID\n\n### Agents\n- **defaultAgent** \u2014 Which agent to use by default\n- Agents are managed via `/agents` (Telegram) or `openacp agents` (CLI)\n- Installed agents are stored in `~/.openacp/agents.json`\n- Agent list is fetched from the ACP Registry CDN and cached locally (24h)\n\n### Workspace\n- **workspace.baseDir** \u2014 Base directory for project folders (default: `~/openacp-workspace`)\n\n### Security\n- **security.allowedUserIds** \u2014 Restrict who can use the bot (empty = everyone)\n- **security.maxConcurrentSessions** \u2014 Max parallel sessions (default: 5)\n- **security.sessionTimeoutMinutes** \u2014 Auto-cancel idle sessions (default: 60)\n\n### Tunnel / File Viewer\n- **tunnel.enabled** \u2014 Enable file viewer tunnel\n- **tunnel.provider** \u2014 Tunnel provider: cloudflare (default, free), ngrok, bore, tailscale\n- **tunnel.port** \u2014 Local port for tunnel server (default: 3100)\n- **tunnel.auth.enabled** \u2014 Enable authentication for tunnel URLs\n- **tunnel.auth.token** \u2014 Auth token for tunnel access\n- **tunnel.storeTtlMinutes** \u2014 How long viewer links stay cached (default: 60)\n\n### Logging\n- **logging.level** \u2014 Log level: silent, debug, info, warn, error, fatal (default: info)\n- **logging.logDir** \u2014 Log directory (default: `~/.openacp/logs`)\n- **logging.maxFileSize** \u2014 Max log file size before rotation\n- **logging.maxFiles** \u2014 Max number of rotated log files\n- **logging.sessionLogRetentionDays** \u2014 Auto-delete old session logs (default: 30)\n\n### Data Retention\n- **sessionStore.ttlDays** \u2014 How long session records persist (default: 30). Old records are cleaned up automatically.\n\n### Environment variables\nOverride config with env vars:\n- `OPENACP_TELEGRAM_BOT_TOKEN`\n- `OPENACP_TELEGRAM_CHAT_ID`\n- `OPENACP_DISCORD_BOT_TOKEN`\n- `OPENACP_DISCORD_GUILD_ID`\n- `OPENACP_DEFAULT_AGENT`\n- `OPENACP_RUN_MODE` \u2014 foreground or daemon\n- `OPENACP_API_PORT` \u2014 API server port (default: 21420)\n- `OPENACP_TUNNEL_ENABLED`\n- `OPENACP_TUNNEL_PORT`\n- `OPENACP_TUNNEL_PROVIDER`\n- `OPENACP_LOG_LEVEL`\n- `OPENACP_LOG_DIR`\n- `OPENACP_DEBUG` \u2014 Sets log level to debug\n\n---\n\n## Troubleshooting\n\n### Session stuck / not responding\n- Check status: ask Assistant \"Is anything stuck?\"\n- Cancel and create new: `/cancel` then `/new`\n- Check system health: Assistant can run health check\n\n### Agent not found\n- Check available agents: `/agents` or `openacp agents`\n- Install missing agent: `openacp agents install <name>`\n- Some agents need login first: `openacp agents info <name>` to see setup steps\n- Run agent CLI for setup: `openacp agents run <name> -- <args>`\n\n### Permission request not showing\n- Check Notifications topic for the alert\n- Try `/enable_dangerous` to auto-approve (if you trust the agent)\n\n### Session disappeared after restart\n- Sessions persist across restarts\n- Send a message in the old topic \u2014 it auto-resumes\n- If topic was deleted, the session record may still exist in status\n\n### Bot not responding at all\n- Check daemon: `openacp status`\n- Check logs: `openacp logs`\n- Restart: `openacp start` or `/restart`\n\n### Messages going to wrong topic\n- Each session is bound to a specific topic/thread\n- If you see messages appearing in the Assistant topic instead of the session topic, try creating a new session\n\n### Viewing logs\n- Session-specific logs: `~/.openacp/logs/sessions/`\n- System logs: `openacp logs` to tail live\n- Set `OPENACP_DEBUG=true` for verbose output\n\n---\n\n## Data & Storage\n\nAll data is stored in `~/.openacp/`:\n- `config.json` \u2014 Configuration\n- `agents.json` \u2014 Installed agents (managed by AgentCatalog)\n- `registry-cache.json` \u2014 Cached ACP Registry data (refreshes every 24h)\n- `agents/` \u2014 Downloaded binary agents\n- `sessions/` \u2014 Session records and state\n- `topics/` \u2014 Topic-to-session mappings\n- `logs/` \u2014 System and session logs\n- `plugins/` \u2014 Installed adapter plugins\n- `openacp.pid` \u2014 Daemon PID file\n\nSession records auto-cleanup: 30 days (configurable via `sessionStore.ttlDays`).\nSession logs auto-cleanup: 30 days (configurable via `logging.sessionLogRetentionDays`).\n";
+
 interface TelegramChannelConfig extends ChannelConfig {
     botToken: string;
     chatId: number;
@@ -1808,39 +3222,88 @@ 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 saveTopicIds?;
     private permissionHandler;
     private assistantSession;
     private assistantInitializing;
     private notificationTopicId;
     private assistantTopicId;
     private sendQueue;
-    private toolTracker;
+    private _sessionThreadIds;
+    private outputModeResolver;
     private draftManager;
     private skillManager;
     private fileService;
     private sessionTrackers;
-    private get verbosity();
+    private callbackCache;
+    private callbackCounter;
+    /** Pending skill commands queued when session.threadId was not yet set */
+    private _pendingSkillCommands;
+    private getThreadId;
     private getOrCreateTracker;
-    constructor(core: OpenACPCore, config: TelegramChannelConfig);
+    constructor(core: OpenACPCore, config: TelegramChannelConfig, saveTopicIds?: (updates: {
+        notificationTopicId?: number;
+        assistantTopicId?: number;
+    }) => Promise<void>);
     start(): Promise<void>;
+    /**
+     * Retry an async operation with exponential backoff.
+     * Used for Telegram API calls that may fail due to transient network issues.
+     */
+    private retryWithBackoff;
+    /**
+     * Register Telegram commands in the background with retries.
+     * Non-critical — bot works fine without autocomplete commands.
+     */
+    private registerCommandsWithRetry;
     stop(): Promise<void>;
+    private renderCommandResponse;
+    private toCallbackData;
+    private fromCallbackData;
     private setupRoutes;
-    private messageHandlers;
+    /**
+     * Per-session serial dispatch queues.
+     * SessionBridge fires sendMessage() as fire-and-forget, so multiple events
+     * (tool_call, tool_update, text) can arrive concurrently. Without serialization,
+     * fast handlers (tool_update) overtake slow ones (tool_call with draftManager.finalize),
+     * causing out-of-order processing where a tool's completion update is processed before
+     * its creation event. This queue ensures events are processed in the order they arrive.
+     */
+    private _dispatchQueues;
+    private getTracer;
     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>;
     renameSessionThread(sessionId: string, newName: string): Promise<void>;
     deleteSessionThread(sessionId: string): Promise<void>;
     sendSkillCommands(sessionId: string, commands: AgentCommand[]): Promise<void>;
+    /** Flush any skill commands that were queued before threadId was available */
+    flushPendingSkillCommands(sessionId: string): Promise<void>;
     private resolveSessionId;
     private downloadTelegramFile;
     private handleIncomingMedia;
     cleanupSkillCommands(sessionId: string): Promise<void>;
+    cleanupSessionState(sessionId: string): Promise<void>;
+    stripTTSBlock(sessionId: string): Promise<void>;
     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 AgentSwitchEntry, type ApiConfig, type ApiServerInstance, type ApiServerOptions, type ApiServerService, type Attachment, type AuthMethod, type AuthenticateRequest, type AvailabilityResult, BaseRenderer, type BridgeDeps, CONFIG_REGISTRY, ChannelAdapter, type ChannelConfig, type CleanupResult, type CommandArgs, type CommandDef, CommandRegistry, 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, DisplaySpecBuilder, type DisplayVerbosity, DoctorEngine, type DoctorReport, DraftManager, EntireProvider, EventBus, type EventBusEvents, FileService, type FileServiceInterface, GroqSTT, type IChannelAdapter, type IRenderer, type IncomingMessage, type InstallContext, type InstallProgress, type InstallResult, type InstalledAgent, KIND_ICONS, type ListItem, type Logger$1 as Logger, type LoggingConfig, type McpServerConfig, type MenuOption, MessageTransformer, MessagingAdapter, type MessagingAdapterConfig, type MigrateContext, type ModelInfo, type NewSessionResponse, NotificationManager, type NotificationMessage, type NotificationService, OpenACPCore, type OpenACPPlugin, type OutgoingMessage, type OutputMode, OutputModeResolver, PRODUCT_GUIDE, type PendingFix, PermissionGate, type PermissionOption, type PermissionRequest, type PlanEntry, type PluginContext, type PluginPermission, type PluginStorage, PromptQueue, type PromptResponse, type RegistryAgent, type RegistryBinaryTarget, type RegistryDistribution, type RenderedMessage, SSEManager, STATUS_ICONS, 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, ThoughtBuffer, type ThoughtDisplaySpec, type ToolCallMeta, ToolCallTracker, type ToolCardSnapshot, ToolCardState, type ToolCardStateConfig, type ToolDisplaySpec, type ToolEntry, ToolStateMap, type ToolUpdateMeta, type TopicInfo, TopicManager, type TunnelServiceInterface, TypedEmitter, type UsageConfig, type UsageRecord, type UsageRecordEvent, type UsageService, type ViewerLinks, cleanupOldSessionLogs, createApiServer, createApiServerService, createChildLogger, createSessionLogger, expandHome, extractContentText, formatTokens, formatToolSummary, formatToolTitle, getConfigValue, getFieldDef, getPidPath, getSafeFields, getStatus, initLogger, installAutoStart, isAutoStartInstalled, isAutoStartSupported, isHotReloadable, log, nodeToWebReadable, nodeToWebWritable, progressBar, resolveOptions, resolveToolIcon, runConfigEditor, setLogLevel, shutdownLogger, splitMessage, startDaemon, stopDaemon, stripCodeFences, truncateContent, uninstallAutoStart };