@openacp/cli 2026.408.4 → 2026.410.2

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as Attachment, O as OutgoingMessage, I as IChannelAdapter, N as NotificationMessage, a as AgentEvent, S as StopReason, P as PermissionRequest, U as UsageRecord, b as AgentCapabilities, c as AgentDefinition, M as McpServerConfig, d as SetConfigOptionValue, e as InstalledAgent, R as RegistryAgent, f as AgentListItem, g as AvailabilityResult, h as InstallProgress, i as InstallResult, j as SessionStatus, T as TurnContext, C as ConfigOption, k as AgentSwitchEntry, l as AgentCommand, m as TurnRouting, n as SessionRecord, o as UsageRecordEvent, p as IncomingMessage, D as DisplayVerbosity, q as ChannelConfig, r as AdapterCapabilities, s as ToolCallMeta, V as ViewerLinks, t as OutputMode, u as PlanEntry } from './channel-CKXNnTy4.js';
-export { v as AgentDistribution, w as AuthMethod, x as AuthenticateRequest, y as ChannelAdapter, z as ConfigSelectChoice, B as ConfigSelectGroup, E as ContentBlock, K as KIND_ICONS, F as ModelInfo, G as NewSessionResponse, H as PermissionOption, J as PromptResponse, L as RegistryBinaryTarget, Q as RegistryDistribution, W as STATUS_ICONS, X as SessionListItem, Y as SessionListResponse, Z as SessionMode, _ as SessionModeState, $ as SessionModelState, a0 as TelegramPlatformData, a1 as ToolUpdateMeta, a2 as createTurnContext, a3 as getEffectiveTarget, a4 as isSystemEvent } from './channel-CKXNnTy4.js';
+import { A as Attachment, O as OutgoingMessage, I as IChannelAdapter, N as NotificationMessage, a as AgentEvent, S as StopReason, P as PermissionRequest, U as UsageRecord, b as AgentCapabilities, c as AgentDefinition, M as McpServerConfig, d as SetConfigOptionValue, e as InstalledAgent, R as RegistryAgent, f as AgentListItem, g as AvailabilityResult, h as InstallProgress, i as InstallResult, j as SessionStatus, T as TurnContext, C as ConfigOption, k as AgentSwitchEntry, l as AgentCommand, m as TurnRouting, n as SessionRecord, o as UsageRecordEvent, p as IncomingMessage, D as DisplayVerbosity, q as ChannelConfig, r as AdapterCapabilities, s as ToolCallMeta, V as ViewerLinks, t as OutputMode, u as PlanEntry } from './channel-CFMUPzvH.js';
+export { v as AgentDistribution, w as AuthMethod, x as AuthenticateRequest, y as ChannelAdapter, z as ConfigSelectChoice, B as ConfigSelectGroup, E as ContentBlock, K as KIND_ICONS, F as ModelInfo, G as NewSessionResponse, H as PermissionOption, J as PromptResponse, L as RegistryBinaryTarget, Q as RegistryDistribution, W as STATUS_ICONS, X as SessionListItem, Y as SessionListResponse, Z as SessionMode, _ as SessionModeState, $ as SessionModelState, a0 as TelegramPlatformData, a1 as ToolUpdateMeta, a2 as createTurnContext, a3 as getEffectiveTarget, a4 as isSystemEvent } from './channel-CFMUPzvH.js';
 import pino from 'pino';
 import * as zod from 'zod';
 import { ZodSchema, z } from 'zod';
@@ -8,28 +8,91 @@ import { SetSessionConfigOptionResponse, ListSessionsResponse, LoadSessionRespon
 import { FastifyInstance, FastifyPluginAsync, preHandlerHookHandler, FastifyRequest, FastifyReply } from 'fastify';
 import * as http from 'node:http';
 
+/** A CLI command the assistant can run, shown as a code block in the system prompt. */
 interface AssistantCommand {
     command: string;
     description: string;
 }
+/**
+ * A section that injects live system state into the assistant's system prompt.
+ *
+ * Each section provides a `buildContext()` callback that is called at prompt
+ * composition time. Sections are sorted by priority (lower = earlier in prompt)
+ * so the most important context appears first.
+ */
 interface AssistantSection {
     id: string;
     title: string;
+    /** Lower priority = appears earlier in the system prompt. */
     priority: number;
+    /** Returns the section's context string, or null to skip this section entirely. */
     buildContext: () => string | null;
     commands?: AssistantCommand[];
 }
+/**
+ * Registry that collects assistant prompt sections and composes them into
+ * a single system prompt.
+ *
+ * Core modules and plugins register sections (e.g. sessions, agents, config)
+ * that each contribute a fragment of live system state. At prompt build time,
+ * sections are sorted by priority, their `buildContext()` is called, and the
+ * results are assembled with the preamble and CLI guidelines.
+ */
 declare class AssistantRegistry {
     private sections;
     private _instanceRoot;
-    /** Set the instance root path used in assistant guidelines */
+    /** Set the instance root path used in assistant guidelines. */
     setInstanceRoot(root: string): void;
+    /** Register a prompt section. Overwrites any existing section with the same id. */
     register(section: AssistantSection): void;
+    /** Remove a previously registered section by id. */
     unregister(id: string): void;
+    /**
+     * Compose the full system prompt from all registered sections.
+     *
+     * Sections are sorted by priority (ascending), each contributing a titled
+     * markdown block. If a section's `buildContext()` throws, it is skipped
+     * gracefully so one broken section doesn't break the entire prompt.
+     *
+     * If `channelId` is provided, a "Current Channel" block is injected at the
+     * top of the prompt so the assistant can adapt its behavior to the platform.
+     */
     buildSystemPrompt(channelId?: string): string;
 }
 
-type PluginPermission = 'events:read' | 'events:emit' | 'services:register' | 'services:use' | 'middleware:register' | 'commands:register' | 'storage:read' | 'storage:write' | 'kernel:access';
+/**
+ * Permission tokens that gate access to PluginContext capabilities.
+ * Declared in a plugin's `permissions` array; enforced at runtime by PluginContext.
+ */
+type PluginPermission = 
+/** Subscribe to EventBus events */
+'events:read'
+/** Emit custom events on the EventBus */
+ | 'events:emit'
+/** Register services in the ServiceRegistry */
+ | 'services:register'
+/** Look up and consume services from the ServiceRegistry */
+ | 'services:use'
+/** Register middleware handlers on hook points */
+ | 'middleware:register'
+/** Register slash commands, menu items, assistant sections, and editable fields */
+ | 'commands:register'
+/** Read from plugin-scoped storage */
+ | 'storage:read'
+/** Write to plugin-scoped storage */
+ | 'storage:write'
+/** Direct access to OpenACPCore internals (sessions, config, eventBus) */
+ | 'kernel:access';
+/**
+ * The runtime plugin instance — the object a plugin module default-exports.
+ *
+ * This is distinct from `PluginEntry` (the registry's persisted metadata about
+ * an installed plugin). `OpenACPPlugin` defines behavior (setup/teardown hooks),
+ * while `PluginEntry` tracks install state (version, source, enabled flag).
+ *
+ * Lifecycle: LifecycleManager topo-sorts plugins by `pluginDependencies`,
+ * then calls `setup()` on each in order, passing a scoped `PluginContext`.
+ */
 interface OpenACPPlugin {
     /** Unique identifier, e.g., '@openacp/security' */
     name: string;
@@ -43,30 +106,48 @@ interface OpenACPPlugin {
     optionalPluginDependencies?: Record<string, string>;
     /** Override a built-in plugin (replaces it entirely) */
     overrides?: string;
-    /** Required permissions — PluginContext enforces these */
+    /** Required permissions — PluginContext enforces these at runtime */
     permissions?: PluginPermission[];
-    /** Called during startup in dependency order */
+    /** Called during startup in dependency order. 30s timeout. */
     setup(ctx: PluginContext): Promise<void>;
-    /** Called during shutdown in reverse order. 10s timeout. */
+    /** Called during shutdown in reverse dependency order. 10s timeout. */
     teardown?(): Promise<void>;
+    /** Called once when the plugin is first installed via CLI */
     install?(ctx: InstallContext): Promise<void>;
+    /** Called when the plugin is removed via CLI. `purge` deletes data too. */
     uninstall?(ctx: InstallContext, opts: {
         purge: boolean;
     }): Promise<void>;
+    /** Interactive configuration via CLI (post-install) */
     configure?(ctx: InstallContext): Promise<void>;
+    /**
+     * Called at boot when the registry's stored version differs from the plugin's
+     * current version. Returns new settings to persist, or void to keep existing.
+     */
     migrate?(ctx: MigrateContext, oldSettings: unknown, oldVersion: string): Promise<unknown>;
+    /** Zod schema to validate settings before setup(). Validation failure skips the plugin. */
     settingsSchema?: zod.ZodSchema;
+    /** If true, the plugin is critical to core operation (informational flag) */
     essential?: boolean;
     /** Settings keys that can be copied when creating a new instance from this one */
     inheritableKeys?: string[];
 }
+/**
+ * Per-plugin key-value storage backed by a JSON file on disk.
+ * Each plugin gets an isolated namespace at `~/.openacp/plugins/<name>/kv.json`.
+ */
 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[]>;
+    /** Returns the plugin's dedicated data directory, creating it if needed */
     getDataDir(): string;
 }
+/**
+ * Typed API for reading and writing a plugin's settings.json file.
+ * Backed by SettingsManager; available in InstallContext and MigrateContext.
+ */
 interface SettingsAPI {
     get<T = unknown>(key: string): Promise<T | undefined>;
     set<T = unknown>(key: string, value: T): Promise<void>;
@@ -90,6 +171,11 @@ interface FieldDef {
     /** Valid values for "select" type */
     options?: string[];
 }
+/**
+ * Interactive CLI primitives for plugin install/configure flows.
+ * Wraps @clack/prompts — only available during CLI operations (install, configure),
+ * NOT during normal runtime. Plugins use this in their `install()` and `configure()` hooks.
+ */
 interface TerminalIO {
     text(opts: {
         message: string;
@@ -137,6 +223,11 @@ interface TerminalIO {
     note(message: string, title?: string): void;
     cancel(message?: string): void;
 }
+/**
+ * Context provided to plugin install/uninstall/configure hooks.
+ * Unlike PluginContext (runtime), InstallContext provides terminal I/O
+ * for interactive setup but no access to services, middleware, or events.
+ */
 interface InstallContext {
     pluginName: string;
     terminal: TerminalIO;
@@ -146,11 +237,19 @@ interface InstallContext {
     /** Root of the OpenACP instance directory (e.g. ~/.openacp) */
     instanceRoot?: string;
 }
+/**
+ * Context provided to the `migrate()` hook at boot time when the plugin's
+ * current version differs from the version stored in the registry.
+ */
 interface MigrateContext {
     pluginName: string;
     settings: SettingsAPI;
     log: Logger$1;
 }
+/**
+ * Possible response shapes from a command handler.
+ * Adapters render each type per-platform (e.g., Telegram inline keyboards for menus).
+ */
 type CommandResponse = {
     type: 'text';
     text: string;
@@ -170,9 +269,13 @@ type CommandResponse = {
 } | {
     type: 'error';
     message: string;
-} | {
+}
+/** Command handled successfully but produces no visible output */
+ | {
     type: 'silent';
-} | {
+}
+/** Command delegates further processing to another system (e.g., agent prompt) */
+ | {
     type: 'delegated';
 };
 interface MenuItem {
@@ -250,6 +353,7 @@ interface CoreAccess {
     sessionManager: SessionManager$1;
     adapters: Map<string, IChannelAdapter>;
 }
+/** Pino-compatible logger interface used throughout the plugin system. */
 interface Logger$1 {
     trace(msg: string, ...args: unknown[]): void;
     debug(msg: string, ...args: unknown[]): void;
@@ -257,13 +361,32 @@ interface Logger$1 {
     warn(msg: string, ...args: unknown[]): void;
     error(msg: string, ...args: unknown[]): void;
     fatal(msg: string, ...args: unknown[]): void;
+    /** Create a child logger with additional context bindings (e.g., `{ plugin: name }`) */
     child(bindings: Record<string, unknown>): Logger$1;
 }
+/**
+ * Scoped API surface given to each plugin during setup().
+ *
+ * Each plugin receives its own PluginContext instance with permission-gated
+ * access. This provides isolation: storage is namespaced per-plugin, logs are
+ * prefixed with the plugin name, and only declared permissions are allowed.
+ *
+ * Tier 1 (Events) — subscribe/emit on the shared EventBus.
+ * Tier 2 (Actions) — register services, middleware, commands.
+ * Tier 3 (Kernel)  — direct access to core internals (requires kernel:access).
+ */
 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;
+    /**
+     * Unsubscribes a previously registered event handler.
+     *
+     * Called automatically for all listeners registered via `on()` during plugin teardown.
+     * Use manually only when conditional unsubscription is needed before teardown.
+     * Requires 'events:read' permission.
+     */
     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;
@@ -300,8 +423,11 @@ interface PluginContext {
      *          → [HOOK: message:outgoing] → adapter.sendMessage()
      */
     sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>;
+    /** Direct access to SessionManager. Requires 'kernel:access'. */
     sessions: SessionManager$1;
+    /** Direct access to ConfigManager. Requires 'kernel:access'. */
     config: ConfigManager$1;
+    /** Direct access to EventBus. Requires 'kernel:access'. */
     eventBus: EventBus$1;
     /** Direct access to OpenACPCore instance. Requires 'kernel:access'. */
     core: unknown;
@@ -311,6 +437,14 @@ interface PluginContext {
      */
     instanceRoot: string;
 }
+/**
+ * Maps each middleware hook name to its payload type.
+ *
+ * Middleware handlers receive the payload, can modify it, and call `next()` to pass
+ * it down the chain. Returning `null` short-circuits the chain (blocks the operation).
+ * There are 19 hook points covering message flow, agent lifecycle, file system,
+ * terminal, permissions, sessions, config changes, and agent switching.
+ */
 interface MiddlewarePayloadMap {
     'message:incoming': {
         channelId: string;
@@ -420,7 +554,14 @@ interface MiddlewarePayloadMap {
         resumed: boolean;
     };
 }
+/** Union of all valid middleware hook names */
 type MiddlewareHook = keyof MiddlewarePayloadMap;
+/**
+ * Middleware handler signature. Receives the current payload and a `next` function.
+ * - Call `next()` to continue the chain (optionally with a modified payload).
+ * - Return the (possibly modified) payload to pass it upstream.
+ * - Return `null` to short-circuit — the operation is blocked entirely.
+ */
 type MiddlewareFn<T> = (payload: T, next: () => Promise<T>) => Promise<T | null>;
 interface MiddlewareOptions<T> {
     /** Override execution order within same dependency level. Lower = earlier. */
@@ -509,22 +650,38 @@ interface TunnelServiceInterface {
     outputUrl(entryId: string): string;
 }
 
+/** Result of validating plugin settings against a Zod schema. */
 interface ValidationResult {
     valid: boolean;
     errors?: string[];
 }
+/**
+ * Manages per-plugin settings files.
+ *
+ * Each plugin's settings are stored at `<basePath>/<pluginName>/settings.json`.
+ * The basePath is typically `~/.openacp/plugins/`.
+ * Settings are distinct from plugin storage (kv.json) — settings are user-facing
+ * configuration, while storage is internal plugin state.
+ */
 declare class SettingsManager {
     private basePath;
     constructor(basePath: string);
+    /** Returns the base path for all plugin settings directories. */
     getBasePath(): string;
+    /** Create a SettingsAPI instance scoped to a specific plugin. */
     createAPI(pluginName: string): SettingsAPI;
+    /** Load a plugin's settings from disk. Returns empty object if file doesn't exist. */
     loadSettings(pluginName: string): Promise<Record<string, unknown>>;
+    /** Validate settings against a Zod schema. Returns valid if no schema is provided. */
     validateSettings(_pluginName: string, settings: unknown, schema?: ZodSchema): ValidationResult;
+    /** Resolve the absolute path to a plugin's settings.json file. */
     getSettingsPath(pluginName: string): string;
     getPluginSettings(pluginName: string): Promise<Record<string, unknown>>;
+    /** Merge updates into existing settings (shallow merge). */
     updatePluginSettings(pluginName: string, updates: Record<string, unknown>): Promise<void>;
 }
 
+/** Log rotation and verbosity settings. */
 declare const LoggingSchema: z.ZodDefault<z.ZodObject<{
     level: z.ZodDefault<z.ZodEnum<["silent", "debug", "info", "warn", "error", "fatal"]>>;
     logDir: z.ZodDefault<z.ZodString>;
@@ -544,12 +701,26 @@ declare const LoggingSchema: z.ZodDefault<z.ZodObject<{
     maxFiles?: number | undefined;
     sessionLogRetentionDays?: number | undefined;
 }>>;
+/** Runtime logging configuration. Controls per-module log levels and output destinations. */
 type LoggingConfig = z.infer<typeof LoggingSchema>;
+/**
+ * Zod schema for the global OpenACP config file (`~/.openacp/config.json`).
+ *
+ * Every field uses `.default()` or `.optional()` so that config files from older
+ * versions — which lack newly added fields — still pass validation without error.
+ * This is critical for backward compatibility: users should never have to manually
+ * edit their config after upgrading.
+ *
+ * Plugin-specific settings live separately in per-plugin settings files
+ * (`~/.openacp/plugins/<name>/settings.json`), not here. This schema only
+ * covers global, cross-cutting concerns.
+ */
 declare const ConfigSchema: z.ZodObject<{
+    /** Instance UUID, written once at creation time. */
+    id: z.ZodOptional<z.ZodString>;
     instanceName: z.ZodOptional<z.ZodString>;
     defaultAgent: z.ZodString;
     workspace: z.ZodDefault<z.ZodObject<{
-        baseDir: z.ZodDefault<z.ZodString>;
         allowExternalWorkspaces: z.ZodDefault<z.ZodBoolean>;
         security: z.ZodDefault<z.ZodObject<{
             allowedPaths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
@@ -562,14 +733,12 @@ declare const ConfigSchema: z.ZodObject<{
             envWhitelist?: string[] | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        baseDir: string;
         allowExternalWorkspaces: boolean;
         security: {
             allowedPaths: string[];
             envWhitelist: string[];
         };
     }, {
-        baseDir?: string | undefined;
         allowExternalWorkspaces?: boolean | undefined;
         security?: {
             allowedPaths?: string[] | undefined;
@@ -625,7 +794,6 @@ declare const ConfigSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     defaultAgent: string;
     workspace: {
-        baseDir: string;
         allowExternalWorkspaces: boolean;
         security: {
             allowedPaths: string[];
@@ -652,12 +820,13 @@ declare const ConfigSchema: z.ZodObject<{
         labelHistory: boolean;
     };
     instanceName?: string | undefined;
+    id?: string | undefined;
     outputMode?: "low" | "medium" | "high" | undefined;
 }, {
     defaultAgent: string;
     instanceName?: string | undefined;
+    id?: string | undefined;
     workspace?: {
-        baseDir?: string | undefined;
         allowExternalWorkspaces?: boolean | undefined;
         security?: {
             allowedPaths?: string[] | undefined;
@@ -685,27 +854,72 @@ declare const ConfigSchema: z.ZodObject<{
         labelHistory?: boolean | undefined;
     } | undefined;
 }>;
+/** Validated config object used throughout the codebase. Always obtained via `ConfigManager.get()` to ensure it's up-to-date. */
 type Config = z.infer<typeof ConfigSchema>;
+/** Expands a leading `~` to the user's home directory. Returns the path unchanged if no `~` prefix. */
 declare function expandHome(p: string): string;
+/**
+ * Manages loading, validating, and persisting the global config file.
+ *
+ * The load cycle is: read JSON -> apply migrations -> apply env overrides -> validate with Zod.
+ * Emits `config:changed` events when individual fields are updated, enabling
+ * hot-reload for fields marked as `hotReload` in the config registry.
+ */
 declare class ConfigManager extends EventEmitter {
     private config;
     private configPath;
     constructor(configPath?: string);
+    /**
+     * Loads config from disk through the full validation pipeline:
+     * 1. Create default config if missing (first run)
+     * 2. Apply migrations for older config formats
+     * 3. Apply environment variable overrides
+     * 4. Validate against Zod schema — exits on failure
+     */
     load(): Promise<void>;
+    /** Returns a deep clone of the current config to prevent external mutation. */
     get(): Config;
+    /**
+     * Merges partial updates into the config file using atomic write (write tmp + rename).
+     *
+     * Validates the merged result before writing. If `changePath` is provided,
+     * emits a `config:changed` event with old and new values for that path,
+     * enabling hot-reload without restart.
+     */
     save(updates: Record<string, unknown>, changePath?: string): Promise<void>;
     /**
-     * Set a single config value by dot-path (e.g. "logging.level").
-     * Builds the nested update object, validates, and saves.
-     * Throws if the path contains blocked keys or the value fails Zod validation.
+     * Convenience wrapper for updating a single deeply-nested config field
+     * without constructing the full update object manually.
+     *
+     * Accepts a dot-path (e.g. "logging.level") and builds the nested
+     * update object internally before delegating to `save()`.
+     * Throws if the path contains prototype-pollution keys.
      */
     setPath(dotPath: string, value: unknown): Promise<void>;
+    /**
+     * Resolves a workspace path from user input.
+     *
+     * Supports three forms: no input (returns base dir), absolute/tilde paths
+     * (validated against allowExternalWorkspaces), and named workspaces
+     * (alphanumeric subdirectories under the base).
+     */
     resolveWorkspace(input?: string): string;
+    /** Checks whether the config file exists on disk. Wraps synchronous `fs.existsSync` behind an async interface for consistency with the rest of the ConfigManager API. */
     exists(): Promise<boolean>;
+    /** Returns the resolved path to the config JSON file. */
     getConfigPath(): string;
+    /** Writes a complete config object to disk, creating the directory if needed. Used during initial setup. */
     writeNew(config: Config): Promise<void>;
+    /**
+     * Applies `OPENACP_*` environment variables as overrides to per-plugin settings.
+     *
+     * This lets users configure plugin values (bot tokens, ports, etc.) via env vars
+     * without editing settings files — useful for Docker, CI, and headless setups.
+     */
     applyEnvToPluginSettings(settingsManager: SettingsManager): Promise<void>;
+    /** Applies env var overrides to the raw config object before Zod validation. */
     private applyEnvOverrides;
+    /** Recursively merges source into target, skipping prototype-pollution keys. */
     private deepMerge;
 }
 
@@ -718,30 +932,94 @@ declare const log: {
     fatal: (...args: unknown[]) => void;
     child: (bindings: pino.Bindings) => pino.Logger<never, boolean>;
 };
+/**
+ * Initialize the root logger with file + console output.
+ *
+ * Sets up a multi-target pino transport: pino-pretty to stderr (for humans)
+ * and pino-roll to a rotating log file (for persistence). Also creates
+ * the sessions/ subdirectory for per-session log files.
+ *
+ * Safe to call multiple times — subsequent calls are no-ops.
+ */
 declare function initLogger(config: LoggingConfig): Logger;
 /** Change log level at runtime. Pino transport targets respect parent level changes automatically. */
 declare function setLogLevel(level: string): void;
+/**
+ * Create a child logger scoped to a module (e.g., "core", "session", "telegram").
+ *
+ * Returns a Proxy that always delegates to the current rootLogger — this
+ * ensures child loggers created at module-level (before initLogger runs)
+ * pick up the initialized logger with proper transports once it's ready.
+ */
 declare function createChildLogger(context: {
     module: string;
     [key: string]: unknown;
 }): Logger;
+/**
+ * Create a per-session logger that writes to both the combined log and
+ * a session-specific file (`<logDir>/sessions/<sessionId>.log`).
+ *
+ * This dual-write pattern allows operators to view all logs in one place
+ * (combined log) while also being able to inspect a single session's
+ * activity in isolation (session file).
+ *
+ * Falls back to a simple child logger if the session log file can't be created.
+ */
 declare function createSessionLogger(sessionId: string, parentLogger: Logger): Logger;
+/**
+ * Flush and close the root logger transport.
+ *
+ * Resets all state so the logger can be re-initialized (e.g., after restart).
+ * Waits up to 3 seconds for the transport to close gracefully.
+ */
 declare function shutdownLogger(): Promise<void>;
+/**
+ * Delete session log files older than the given retention period.
+ *
+ * Called during startup to prevent unbounded disk usage from accumulated
+ * per-session log files.
+ */
 declare function cleanupOldSessionLogs(retentionDays: number): Promise<void>;
 
+/**
+ * Wrap a Node.js WritableStream as a Web API WritableStream.
+ *
+ * Handles backpressure by waiting for the 'drain' event when the Node
+ * stream's internal buffer is full.
+ */
 declare function nodeToWebWritable(nodeStream: NodeJS.WritableStream): WritableStream<Uint8Array>;
+/**
+ * Wrap a Node.js ReadableStream as a Web API ReadableStream.
+ *
+ * Converts Node Buffer chunks to Uint8Array for Web Streams compatibility.
+ */
 declare function nodeToWebReadable(nodeStream: NodeJS.ReadableStream): ReadableStream<Uint8Array>;
 
+/**
+ * Rolling buffer that captures the last N lines of an agent subprocess's stderr.
+ *
+ * Agent stdout carries the ACP protocol (JSON-RPC); stderr is used for
+ * debug/diagnostic output. This capture provides context when the agent
+ * crashes or errors — the last lines of stderr are included in error
+ * messages shown to the user.
+ */
 declare class StderrCapture {
     private maxLines;
     private lines;
     constructor(maxLines?: number);
+    /** Append a chunk of stderr output, splitting on newlines and trimming to maxLines. */
     append(chunk: string): void;
+    /** Return all captured lines joined as a single string. */
     getLastLines(): string;
 }
 
 /**
- * A minimal, generic typed event emitter.
+ * Type-safe event emitter where the event map is enforced at compile time.
+ *
+ * Unlike Node's EventEmitter, event names and listener signatures are
+ * validated by TypeScript — no stringly-typed events. Supports pause/resume
+ * with buffering, used by Session and EventBus to defer events during
+ * initialization or agent switches.
  *
  * Usage:
  *   interface MyEvents {
@@ -757,8 +1035,16 @@ declare class TypedEmitter<T extends Record<string & keyof T, (...args: any[]) =
     private listeners;
     private paused;
     private buffer;
+    /** Register a listener for the given event. Returns `this` for chaining. */
     on<K extends keyof T>(event: K, listener: T[K]): this;
+    /** Remove a specific listener for the given event. */
     off<K extends keyof T>(event: K, listener: T[K]): this;
+    /**
+     * Emit an event to all registered listeners.
+     *
+     * When paused, events are buffered (up to MAX_BUFFER_SIZE) unless
+     * the passthrough filter allows them through immediately.
+     */
     emit<K extends keyof T>(event: K, ...args: Parameters<T[K]>): void;
     /**
      * Pause event delivery. Events emitted while paused are buffered.
@@ -772,49 +1058,99 @@ declare class TypedEmitter<T extends Record<string & keyof T, (...args: any[]) =
     clearBuffer(): void;
     get isPaused(): boolean;
     get bufferSize(): number;
+    /** Remove all listeners for a specific event, or all events if none specified. */
     removeAllListeners(event?: keyof T): void;
+    /** Deliver an event to listeners, isolating errors so one broken listener doesn't break others. */
     private deliver;
 }
 
+/** Configuration for the sliding-window error budget. */
 interface ErrorBudgetConfig {
+    /** Maximum errors allowed within the window before disabling the plugin. Default: 10. */
     maxErrors: number;
+    /** Sliding window duration in milliseconds. Default: 3600000 (1 hour). */
     windowMs: number;
 }
+/**
+ * Circuit breaker for misbehaving plugins.
+ *
+ * Tracks errors per plugin within a sliding time window. When a plugin exceeds
+ * its error budget (default: 10 errors in 1 hour), it is auto-disabled —
+ * its middleware handlers are skipped by MiddlewareChain. This prevents a
+ * single broken plugin from degrading the entire system.
+ *
+ * Essential plugins can be marked exempt via `setExempt()`.
+ */
 declare class ErrorTracker {
     private errors;
     private disabled;
     private exempt;
     private config;
+    /** Callback fired when a plugin is auto-disabled due to error budget exhaustion. */
     onDisabled?: (pluginName: string, reason: string) => void;
     constructor(config?: Partial<ErrorBudgetConfig>);
+    /**
+     * Record an error for a plugin. If the error budget is exceeded,
+     * the plugin is disabled and the `onDisabled` callback fires.
+     */
     increment(pluginName: string): void;
+    /** Check if a plugin has been disabled due to errors. */
     isDisabled(pluginName: string): boolean;
+    /** Re-enable a plugin and clear its error history. */
     reset(pluginName: string): void;
+    /** Mark a plugin as exempt from circuit-breaking (e.g., essential plugins). */
     setExempt(pluginName: string): void;
 }
 
+/**
+ * Manages ordered middleware chains for each hook point.
+ *
+ * Execution model:
+ * - Handlers run in priority order (lower number = earlier). Default priority: 100.
+ * - Each handler receives the current payload and a `next()` function.
+ * - Calling `next()` passes control to the next handler in the chain.
+ * - Returning `null` short-circuits: the operation is blocked and no further handlers run.
+ * - If a handler throws or times out, it is skipped and the error is tracked.
+ *   After enough errors (see ErrorTracker), the plugin's middleware is auto-disabled.
+ */
 declare class MiddlewareChain {
     private chains;
     private errorHandler?;
     private errorTracker?;
+    /** Register a middleware handler for a hook. Handlers are kept sorted by priority. */
     add(hook: string, pluginName: string, opts: {
         priority?: number;
         handler: Function;
     }): void;
+    /**
+     * Execute the middleware chain for a hook, ending with the core handler.
+     *
+     * The chain is built recursively: each handler calls `next()` to invoke the
+     * next handler, with the core handler at the end. If no middleware is registered,
+     * the core handler runs directly.
+     *
+     * @returns The final payload, or `null` if any handler short-circuited.
+     */
     execute<T>(hook: string, payload: T, coreHandler: (p: T) => T | Promise<T>): Promise<T | null>;
+    /** Remove all middleware handlers registered by a specific plugin. */
     removeAll(pluginName: string): void;
+    /** Set a callback for middleware errors (e.g., logging). */
     setErrorHandler(fn: (pluginName: string, error: Error) => void): void;
+    /** Attach an ErrorTracker for circuit-breaking misbehaving plugins. */
     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.
+ * Per-session debug trace logger that writes JSONL files to `<workingDirectory>/.log/`.
+ *
+ * Only active when `OPENACP_DEBUG=true` is set in the environment.
+ * Each trace layer (acp, core, telegram) gets its own file, making it easy
+ * to inspect protocol-level, core-level, or adapter-level events separately.
  *
- * 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.
+ * 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;
@@ -822,21 +1158,45 @@ declare class DebugTracer {
     private dirCreated;
     private logDir;
     constructor(sessionId: string, workingDirectory: string);
+    /**
+     * Write a timestamped JSONL entry to the trace file for the given layer.
+     *
+     * Handles circular references gracefully and silently swallows errors —
+     * debug logging must never crash the application.
+     */
     log(layer: TraceLayer, data: Record<string, unknown>): void;
     /** No-op cleanup — establishes the pattern for future async implementations */
     destroy(): void;
 }
 
+/** Events emitted by AgentInstance — consumed by Session to relay to adapters. */
 interface AgentInstanceEvents {
     agent_event: (event: AgentEvent) => void;
 }
+/**
+ * Manages an ACP agent subprocess and implements the ACP Client interface.
+ *
+ * Each AgentInstance owns exactly one child process. It handles:
+ * - Subprocess spawning with filtered environment and path guarding
+ * - ACP protocol handshake (initialize → newSession/loadSession)
+ * - Translating ACP session updates into internal AgentEvent types
+ * - File I/O and terminal operations requested by the agent
+ * - Permission request proxying (agent → Session → adapter → user → agent)
+ * - Graceful shutdown (SIGTERM with SIGKILL fallback)
+ *
+ * Session wraps this class to add prompt queuing and lifecycle management.
+ */
 declare class AgentInstance extends TypedEmitter<AgentInstanceEvents> {
     private connection;
     private child;
     private stderrCapture;
+    /** Manages terminal subprocesses that agents can spawn for shell commands. */
     private terminalManager;
+    /** Shared across all instances — resolves MCP server configs for ACP sessions. */
     private static mcpManager;
+    /** Guards against emitting crash events during intentional shutdown. */
     private _destroying;
+    /** Restricts agent file I/O to the workspace directory and explicitly allowed paths. */
     private pathGuard;
     sessionId: string;
     agentName: string;
@@ -853,30 +1213,132 @@ declare class AgentInstance extends TypedEmitter<AgentInstanceEvents> {
     };
     middlewareChain?: MiddlewareChain;
     debugTracer: DebugTracer | null;
-    /** Allow external callers (e.g. SessionFactory) to whitelist additional read paths */
+    /**
+     * Whitelist an additional filesystem path for agent read access.
+     *
+     * Called by SessionFactory to allow agents to read files outside the
+     * workspace (e.g., the file-service upload directory for attachments).
+     */
     addAllowedPath(p: string): void;
     onPermissionRequest: (request: PermissionRequest) => Promise<string>;
     private constructor();
+    /**
+     * Spawn the agent child process and complete the ACP protocol handshake.
+     *
+     * Steps:
+     *  1. Resolve the agent command to a directly executable path
+     *  2. Create a PathGuard scoped to the working directory
+     *  3. Spawn the subprocess with a filtered environment (security: only whitelisted
+     *     env vars are passed to prevent leaking secrets like API keys)
+     *  4. Wire stdin/stdout through debug-tracing Transform streams
+     *  5. Convert Node streams → Web streams for the ACP SDK
+     *  6. Perform the ACP `initialize` handshake and negotiate capabilities
+     *
+     * Does NOT create a session — callers must follow up with newSession or loadSession.
+     */
     private static spawnSubprocess;
+    /**
+     * Monitor the subprocess for unexpected exits and emit error events.
+     *
+     * Distinguishes intentional shutdown (SIGTERM/SIGINT during destroy) from
+     * crashes (non-zero exit code or unexpected signal). Crash events include
+     * captured stderr output for diagnostic context.
+     */
     private setupCrashDetection;
+    /**
+     * Spawn a new agent subprocess and create a fresh ACP session.
+     *
+     * This is the primary entry point for starting an agent. It spawns the
+     * subprocess, completes the ACP handshake, and calls `newSession` to
+     * initialize the agent's working context (cwd, MCP servers).
+     *
+     * @param agentDef - Agent definition (command, args, env) from the catalog
+     * @param workingDirectory - Workspace root the agent operates in
+     * @param mcpServers - Optional MCP server configs to extend agent capabilities
+     * @param allowedPaths - Extra filesystem paths the agent may access
+     */
     static spawn(agentDef: AgentDefinition, workingDirectory: string, mcpServers?: McpServerConfig[], allowedPaths?: string[]): Promise<AgentInstance>;
+    /**
+     * Spawn a new subprocess and restore an existing agent session.
+     *
+     * Tries loadSession first (preferred, stable API), falls back to the
+     * unstable resumeSession, and finally falls back to creating a brand-new
+     * session if resume fails entirely (e.g., agent lost its state).
+     *
+     * @param agentSessionId - The agent-side session ID to restore
+     */
     static resume(agentDef: AgentDefinition, workingDirectory: string, agentSessionId: string, mcpServers?: McpServerConfig[], allowedPaths?: string[]): Promise<AgentInstance>;
+    /**
+     * Build the ACP Client callback object.
+     *
+     * The ACP SDK invokes these callbacks when the agent sends notifications
+     * or requests. Each callback maps an ACP protocol message to either:
+     * - An internal AgentEvent (emitted for Session/adapters to consume)
+     * - A filesystem or terminal operation (executed on the agent's behalf)
+     * - A permission request (proxied to the user via the adapter)
+     */
     private createClient;
+    /**
+     * Update a session config option (mode, model, etc.) on the agent.
+     *
+     * Falls back to legacy `setSessionMode`/`unstable_setSessionModel` methods
+     * for agents that haven't adopted the unified `session/set_config_option`
+     * ACP method (detected via JSON-RPC -32601 "Method Not Found" error).
+     */
     setConfigOption(configId: string, value: SetConfigOptionValue): Promise<SetSessionConfigOptionResponse>;
+    /** List the agent's known sessions, optionally filtered by working directory. */
     listSessions(cwd?: string, cursor?: string): Promise<ListSessionsResponse>;
+    /** Load an existing agent session by ID into this subprocess. */
     loadSession(sessionId: string, cwd: string, mcpServers?: McpServerConfig[]): Promise<LoadSessionResponse>;
+    /** Trigger agent-managed authentication (e.g., OAuth flow). */
     authenticate(methodId: string): Promise<void>;
+    /** Fork an existing session, creating a new branch with shared history. */
     forkSession(sessionId: string, cwd: string, mcpServers?: McpServerConfig[]): Promise<ForkSessionResponse>;
+    /** Close a session on the agent side (cleanup agent-internal state). */
     closeSession(sessionId: string): Promise<void>;
+    /**
+     * Send a user prompt to the agent and wait for the complete response.
+     *
+     * Builds ACP content blocks from the text and any attachments (images
+     * are base64-encoded if the agent supports them, otherwise appended as
+     * file paths). The promise resolves when the agent finishes responding;
+     * streaming events arrive via the `agent_event` emitter during execution.
+     *
+     * Attachments that exceed size limits or use unsupported formats are
+     * skipped with a note appended to the prompt text.
+     *
+     * Call `cancel()` to interrupt a running prompt; the agent will stop and
+     * the promise resolves with partial results.
+     */
     prompt(text: string, attachments?: Attachment[]): Promise<PromptResponse>;
+    /** Cancel the currently running prompt. The agent should stop and return partial results. */
     cancel(): Promise<void>;
+    /**
+     * Gracefully shut down the agent subprocess.
+     *
+     * Sends SIGTERM first, giving the agent up to 10 seconds to clean up.
+     * If the process hasn't exited by then, SIGKILL forces termination.
+     * The timer is unref'd so it doesn't keep the Node process alive
+     * during shutdown.
+     */
     destroy(): Promise<void>;
 }
 
+/**
+ * Persistent storage for installed agent definitions.
+ *
+ * Agents are stored in `agents.json` (typically `~/.openacp/agents.json`).
+ * The file is validated with Zod on load; corrupted or invalid data is
+ * discarded gracefully with a warning. Writes use atomic rename to
+ * prevent partial writes from corrupting the file.
+ */
+
+/** JSON-backed store for installed agent definitions (`agents.json`). */
 declare class AgentStore {
     private data;
     readonly filePath: string;
-    constructor(filePath?: string);
+    constructor(filePath: string);
+    /** Load and validate the store from disk. Starts fresh if file is missing or invalid. */
     load(): void;
     exists(): boolean;
     getInstalled(): Record<string, InstalledAgent>;
@@ -884,27 +1346,69 @@ declare class AgentStore {
     addAgent(key: string, agent: InstalledAgent): void;
     removeAgent(key: string): void;
     hasAgent(key: string): boolean;
+    /**
+     * Persist the store to disk using atomic write (write to .tmp, then rename).
+     * File permissions are restricted to owner-only (0o600) since the store
+     * may contain agent binary paths and environment variables.
+     */
     private save;
 }
 
+/**
+ * Central catalog of available and installed agents.
+ *
+ * Combines two data sources:
+ *  1. **Registry** — the remote ACP agent registry (CDN-hosted JSON), cached
+ *     locally with a 24-hour TTL and a bundled snapshot as fallback.
+ *  2. **Store** — locally installed agents persisted in `agents.json`.
+ *
+ * Provides discovery (list all agents), installation, uninstallation,
+ * and resolution (name → AgentDefinition for spawning).
+ */
 declare class AgentCatalog {
     private store;
-    private globalStore;
+    /** Agents available in the remote registry (cached in memory after load). */
     private registryAgents;
     private cachePath;
+    /** Directory where binary agent archives are extracted to. */
     private agentsDir;
-    constructor(store?: AgentStore, cachePath?: string, agentsDir?: string);
+    constructor(store: AgentStore, cachePath: string, agentsDir?: string);
+    /**
+     * Load installed agents from disk and hydrate the registry from cache/snapshot.
+     *
+     * Also enriches installed agents with registry metadata — fixes agents that
+     * were migrated from older config formats with incomplete data.
+     */
     load(): void;
+    /** Fetch the latest agent registry from the CDN and update the local cache. */
     fetchRegistry(): Promise<void>;
+    /** Re-fetch registry only if the local cache has expired (24-hour TTL). */
     refreshRegistryIfStale(): Promise<void>;
     getRegistryAgents(): RegistryAgent[];
     getRegistryAgent(registryId: string): RegistryAgent | undefined;
+    /** Find a registry agent by registry ID or by its short alias (e.g., "claude"). */
     findRegistryAgent(keyOrId: string): RegistryAgent | undefined;
     getInstalled(): InstalledAgent[];
     getInstalledEntries(): Record<string, InstalledAgent>;
     getInstalledAgent(key: string): InstalledAgent | undefined;
+    /**
+     * Build the unified list of all agents (installed + registry-only).
+     *
+     * Installed agents appear first with their live availability status.
+     * Registry agents that aren't installed yet show whether a distribution
+     * exists for the current platform. Missing external dependencies
+     * (e.g., claude CLI) are surfaced as `missingDeps` for UI display
+     * but do NOT block installation.
+     */
     getAvailable(): AgentListItem[];
+    /** Check if an agent can be installed on this system (platform + dependencies). */
     checkAvailability(keyOrId: string): AvailabilityResult;
+    /**
+     * Install an agent from the registry.
+     *
+     * Resolves the distribution (npx/uvx/binary), downloads binary archives
+     * if needed, and persists the agent definition in the store.
+     */
     install(keyOrId: string, progress?: InstallProgress, force?: boolean): Promise<InstallResult>;
     /**
      * Register an agent directly into the catalog store without going through
@@ -912,10 +1416,12 @@ declare class AgentCatalog {
      * when their CLI dependency is not yet installed.
      */
     registerFallbackAgent(key: string, data: InstalledAgent): void;
+    /** Remove an installed agent and delete its binary directory if applicable. */
     uninstall(key: string): Promise<{
         ok: boolean;
         error?: string;
     }>;
+    /** Convert an installed agent's short key to an AgentDefinition for spawning. */
     resolve(key: string): AgentDefinition | undefined;
     /**
      * Enrich installed agents (especially migrated ones) with registry data.
@@ -927,17 +1433,52 @@ declare class AgentCatalog {
     private loadRegistryFromCacheOrSnapshot;
 }
 
+/**
+ * High-level facade for spawning and resuming agent instances.
+ *
+ * Resolves agent names to definitions via AgentCatalog, then delegates
+ * to AgentInstance for subprocess management. Used by SessionFactory
+ * to create the agent backing a session.
+ *
+ * Agent switching (swapping the agent mid-session) is coordinated at the
+ * Session layer — AgentManager only handles individual spawn/resume calls.
+ */
 declare class AgentManager {
     private catalog;
     constructor(catalog: AgentCatalog);
+    /** Return definitions for all installed agents. */
     getAvailableAgents(): AgentDefinition[];
+    /** Look up a single agent definition by its short name (e.g., "claude", "gemini"). */
     getAgent(name: string): AgentDefinition | undefined;
+    /**
+     * Spawn a new agent subprocess with a fresh session.
+     *
+     * @throws If the agent is not installed — includes install instructions in the error message.
+     */
     spawn(agentName: string, workingDirectory: string, allowedPaths?: string[]): Promise<AgentInstance>;
+    /**
+     * Spawn a subprocess and resume an existing agent session.
+     *
+     * Falls back to a new session if the agent cannot restore the given session ID.
+     */
     resume(agentName: string, workingDirectory: string, agentSessionId: string, allowedPaths?: string[]): Promise<AgentInstance>;
 }
 
 /**
- * Encapsulates pending permission state with a typed Promise API.
+ * Blocks the prompt pipeline until the user approves or denies a permission request.
+ *
+ * When an agent requests permission (e.g., to run a shell command), AgentInstance
+ * calls its `onPermissionRequest` callback. SessionBridge handles this by calling
+ * `setPending()`, which returns a promise that blocks the ACP prompt/response cycle
+ * until `resolve()` or `reject()` is called. If the user doesn't respond within
+ * the timeout, the request is automatically rejected.
+ *
+ * Only one permission request can be pending at a time — setting a new one
+ * supersedes (rejects) the previous.
+ *
+ * When `bypassPermissions` is enabled on the session, SessionBridge short-circuits
+ * this gate entirely: `setPending()` is never called, and permissions are auto-approved
+ * upstream before the request reaches this class.
  */
 declare class PermissionGate {
     private request?;
@@ -947,8 +1488,14 @@ declare class PermissionGate {
     private timeoutTimer?;
     private timeoutMs;
     constructor(timeoutMs?: number);
+    /**
+     * Register a new permission request and return a promise that resolves with the
+     * chosen option ID when the user responds, or rejects on timeout / supersession.
+     */
     setPending(request: PermissionRequest): Promise<string>;
+    /** Approve the pending request with the given option ID. No-op if already settled. */
     resolve(optionId: string): void;
+    /** Deny the pending request. No-op if already settled. */
     reject(reason?: string): void;
     get isPending(): boolean;
     get currentRequest(): PermissionRequest | undefined;
@@ -958,37 +1505,57 @@ declare class PermissionGate {
     private cleanup;
 }
 
+/** Options passed to an STT provider for a single transcription request. */
 interface STTOptions {
+    /** BCP-47 language code hint (e.g. `"en"`, `"vi"`). Improves accuracy when known. */
     language?: string;
+    /** Override the default model for this request. */
     model?: string;
 }
+/** Result returned by an STT provider after transcription. */
 interface STTResult {
     text: string;
+    /** Detected or confirmed language (BCP-47). */
     language?: string;
+    /** Audio duration in seconds. */
     duration?: number;
 }
+/** Options passed to a TTS provider for a single synthesis request. */
 interface TTSOptions {
     language?: string;
+    /** Voice identifier (provider-specific, e.g. `"en-US-AriaNeural"` for Edge TTS). */
     voice?: string;
     model?: string;
 }
+/** Audio data produced by a TTS provider. */
 interface TTSResult {
     audioBuffer: Buffer;
+    /** MIME type of the audio (e.g. `"audio/mp3"`, `"audio/wav"`). */
     mimeType: string;
 }
+/** Contract for a speech-to-text provider. */
 interface STTProvider {
     readonly name: string;
     transcribe(audioBuffer: Buffer, mimeType: string, options?: STTOptions): Promise<STTResult>;
 }
+/** Contract for a text-to-speech provider. */
 interface TTSProvider {
     readonly name: string;
     synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
 }
+/** Provider-level configuration stored in plugin settings (API key, model override, etc.). */
 interface SpeechProviderConfig {
     apiKey?: string;
     model?: string;
     [key: string]: unknown;
 }
+/**
+ * Top-level configuration for SpeechService.
+ *
+ * `stt.provider` and `tts.provider` name the active provider.
+ * `null` disables the respective capability.
+ * `providers` holds per-provider credentials and options.
+ */
 interface SpeechServiceConfig {
     stt: {
         provider: string | null;
@@ -1000,10 +1567,28 @@ interface SpeechServiceConfig {
     };
 }
 
+/**
+ * A factory that recreates provider instances from a new config snapshot.
+ * Used for hot-reload: when settings change, the plugin calls `refreshProviders`
+ * which invokes this factory to build fresh provider objects.
+ *
+ * Returns separate Maps for STT and TTS so that externally-registered providers
+ * (e.g. from `@openacp/msedge-tts-plugin`) are not discarded — only factory-owned
+ * providers are overwritten.
+ */
 type ProviderFactory = (config: SpeechServiceConfig) => {
     stt: Map<string, STTProvider>;
     tts: Map<string, TTSProvider>;
 };
+/**
+ * Central service for speech-to-text and text-to-speech operations.
+ *
+ * Providers are registered at setup time and may also be registered by external
+ * plugins (e.g. `@openacp/msedge-tts-plugin` registers a TTS provider after boot).
+ * The service itself is registered under the `"speech"` key in the ServiceRegistry
+ * and accessed by `session.ts` to synthesize audio after agent responses when
+ * `voiceMode` is active.
+ */
 declare class SpeechService {
     private config;
     private sttProviders;
@@ -1012,26 +1597,69 @@ declare class SpeechService {
     constructor(config: SpeechServiceConfig);
     /** Set a factory function that can recreate providers from config (for hot-reload) */
     setProviderFactory(factory: ProviderFactory): void;
+    /** Register an STT provider by name. Overwrites any existing provider with the same name. */
     registerSTTProvider(name: string, provider: STTProvider): void;
+    /** Register a TTS provider by name. Called by external TTS plugins (e.g. msedge-tts-plugin). */
     registerTTSProvider(name: string, provider: TTSProvider): void;
+    /** Remove a TTS provider — called by external plugins on teardown. */
     unregisterTTSProvider(name: string): void;
+    /** Returns true if an STT provider is configured and has credentials. */
     isSTTAvailable(): boolean;
+    /**
+     * Returns true if a TTS provider is configured and an implementation is registered.
+     *
+     * Config alone is not enough — the TTS provider plugin must have registered
+     * its implementation via `registerTTSProvider` before this returns true.
+     */
     isTTSAvailable(): boolean;
+    /**
+     * Transcribes audio using the configured STT provider.
+     *
+     * @throws if no STT provider is configured or if the named provider is not registered.
+     */
     transcribe(audioBuffer: Buffer, mimeType: string, options?: STTOptions): Promise<STTResult>;
+    /**
+     * Synthesizes speech using the configured TTS provider.
+     *
+     * @throws if no TTS provider is configured or if the named provider is not registered.
+     */
     synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
+    /** Replace the active config without rebuilding providers. Use `refreshProviders` to also rebuild. */
     updateConfig(config: SpeechServiceConfig): void;
-    /** Re-create factory-managed providers from config. Preserves externally-registered providers (e.g. from plugins). */
+    /**
+     * Reloads TTS and STT providers from a new config snapshot.
+     *
+     * Called after config changes or plugin hot-reload. Factory-managed providers are
+     * rebuilt via the registered `ProviderFactory`; externally-registered providers
+     * (e.g. from `@openacp/msedge-tts-plugin`) are preserved rather than discarded.
+     */
     refreshProviders(newConfig: SpeechServiceConfig): void;
 }
 
+/**
+ * Speech-to-text provider backed by Groq's hosted Whisper API.
+ *
+ * Groq requires the audio to be submitted as a multipart form upload. The file
+ * must have a valid extension matching its MIME type — Groq uses the extension
+ * to determine the codec, so a mismatch causes a transcription error.
+ *
+ * Free tier limit: 28,800 seconds of audio per day. Max file size: 25 MB.
+ */
 declare class GroqSTT implements STTProvider {
     private apiKey;
     private defaultModel;
     readonly name = "groq";
     constructor(apiKey: string, defaultModel?: string);
+    /**
+     * Transcribes audio using the Groq Whisper API.
+     *
+     * `verbose_json` response format is requested so the API returns language
+     * detection and duration metadata alongside the transcript text.
+     */
     transcribe(audioBuffer: Buffer, mimeType: string, options?: STTOptions): Promise<STTResult>;
 }
 
+/** Events emitted by a Session instance — SessionBridge subscribes to relay them to adapters. */
 interface SessionEvents {
     agent_event: (event: AgentEvent) => void;
     permission_request: (request: PermissionRequest) => void;
@@ -1042,6 +1670,17 @@ interface SessionEvents {
     prompt_count_changed: (count: number) => void;
     turn_started: (ctx: TurnContext) => void;
 }
+/**
+ * Manages a single conversation between a user and an AI agent.
+ *
+ * Wraps an AgentInstance with serial prompt queuing (via PromptQueue), permission
+ * gating (via PermissionGate), TTS/STT integration, auto-naming, and a state
+ * machine tracking the session lifecycle. SessionBridge subscribes to this
+ * emitter to forward agent output to channel adapters.
+ *
+ * A session can be attached to multiple adapters simultaneously (e.g., Telegram
+ * and SSE). The `threadIds` map tracks which thread each adapter uses.
+ */
 declare class Session extends TypedEmitter<SessionEvents> {
     id: string;
     channelId: string;
@@ -1052,6 +1691,8 @@ declare class Session extends TypedEmitter<SessionEvents> {
     workingDirectory: string;
     private _agentInstance;
     get agentInstance(): AgentInstance;
+    /** Setting agentInstance wires the agent→session event relay and commands buffer.
+     *  This happens both at construction and on agent switch (switchAgent). */
     set agentInstance(agent: AgentInstance);
     agentSessionId: string;
     private _status;
@@ -1108,17 +1749,32 @@ declare class Session extends TypedEmitter<SessionEvents> {
     fail(reason: string): void;
     /** Transition to finished — from active only. Emits session_end for backward compat. */
     finish(reason?: string): void;
-    /** Transition to cancelled — from active only (terminal session cancel) */
+    /** Transition to cancelled — from active or error (terminal session cancel) */
     markCancelled(): void;
     private transition;
     /** Number of prompts waiting in queue */
     get queueDepth(): number;
+    /** Whether a prompt is currently being processed by the agent */
     get promptRunning(): boolean;
+    /** Store context markdown to be prepended to the next prompt (used for session resume with history). */
     setContext(markdown: string): void;
+    /** Set TTS mode: "off" = disabled, "next" = one-shot (auto-resets after prompt), "on" = persistent. */
     setVoiceMode(mode: "off" | "next" | "on"): void;
+    /**
+     * Enqueue a user prompt for serial processing.
+     *
+     * Runs the prompt through agent:beforePrompt middleware (which can modify or block),
+     * then adds it to the PromptQueue. Returns a turnId that callers can use to correlate
+     * queued/processing events before the prompt actually runs.
+     */
     enqueuePrompt(text: string, attachments?: Attachment[], routing?: TurnRouting, externalTurnId?: string): Promise<string>;
     private processPrompt;
+    /**
+     * Transcribe audio attachments to text if the agent doesn't support audio natively.
+     * Audio attachments are removed and their transcriptions are appended to the prompt text.
+     */
     private maybeTranscribeAudio;
+    /** Extract [TTS] block from agent response, synthesize speech, and emit audio_content event. */
     private processTTSResponse;
     private autoName;
     setInitialConfigOptions(options: ConfigOption[]): void;
@@ -1150,11 +1806,17 @@ declare class Session extends TypedEmitter<SessionEvents> {
     findLastSwitchEntry(agentName: string): AgentSwitchEntry | undefined;
     /** Switch the agent instance in-place, preserving session identity */
     switchAgent(agentName: string, createAgent: () => Promise<AgentInstance>): Promise<void>;
+    /** Tear down the session: reject pending permissions, clear queue, destroy agent subprocess. */
     destroy(): Promise<void>;
 }
 
 /**
  * Serial prompt queue — ensures prompts are processed one at a time.
+ *
+ * Agents are stateful (each prompt builds on prior context), so concurrent
+ * prompts would corrupt the conversation. This queue guarantees that only
+ * one prompt is processed at a time; additional prompts are buffered and
+ * drained sequentially after the current one completes.
  */
 declare class PromptQueue {
     private processor;
@@ -1165,14 +1827,37 @@ declare class PromptQueue {
     /** Set when abort is triggered; drainNext waits for the current processor to settle before starting the next item. */
     private processorSettled;
     constructor(processor: (text: string, attachments?: Attachment[], routing?: TurnRouting, turnId?: string) => Promise<void>, onError?: ((err: unknown) => void) | undefined);
+    /**
+     * Add a prompt to the queue. If no prompt is currently processing, it runs
+     * immediately. Otherwise, it's buffered and the returned promise resolves
+     * only after the prompt finishes processing.
+     */
     enqueue(text: string, attachments?: Attachment[], routing?: TurnRouting, turnId?: string): Promise<void>;
+    /** Run a single prompt through the processor, then drain the next queued item. */
     private process;
+    /** Dequeue and process the next pending prompt, if any. Called after each prompt completes. */
     private drainNext;
+    /**
+     * Abort the in-flight prompt and discard all queued prompts.
+     * Pending promises are resolved (not rejected) so callers don't see unhandled rejections.
+     */
     clear(): void;
     get pending(): number;
     get isProcessing(): boolean;
 }
 
+/**
+ * Transforms AgentEvents into OutgoingMessages suitable for adapter delivery.
+ *
+ * Handles two key concerns beyond simple type mapping:
+ * 1. **Tool input caching** — `tool_call` events carry `rawInput`, but subsequent
+ *    `tool_update` events for the same tool often omit it. The transformer caches
+ *    rawInput so updates can inherit it for viewer link generation.
+ * 2. **Viewer link enrichment** — when a tunnel service is available, tool events
+ *    for file reads/edits are enriched with public URLs to the code viewer and diff viewer.
+ *    Intermediate updates (with raw content) are preferred over completion events
+ *    (which have formatted content with line numbers).
+ */
 declare class MessageTransformer {
     tunnelService?: TunnelServiceInterface;
     /** Cache rawInput from tool_call so it's available in tool_update (which often lacks it) */
@@ -1180,6 +1865,12 @@ declare class MessageTransformer {
     /** Cache viewer links generated from intermediate updates so completion events carry them */
     private toolViewerCache;
     constructor(tunnelService?: TunnelServiceInterface);
+    /**
+     * Convert an agent event to an outgoing message for adapter delivery.
+     *
+     * For tool events, enriches the metadata with diff stats and viewer links
+     * when a tunnel service is available.
+     */
     transform(event: AgentEvent, sessionContext?: {
         id: string;
         workingDirectory: string;
@@ -1193,6 +1884,7 @@ declare class MessageTransformer {
     private enrichWithViewerLinks;
 }
 
+/** Persistence interface for session records. Implementations handle serialization format and storage. */
 interface SessionStore {
     save(record: SessionRecord): Promise<void>;
     /** Immediately flush pending writes to disk (no debounce). */
@@ -1205,6 +1897,13 @@ interface SessionStore {
     remove(sessionId: string): Promise<void>;
 }
 
+/**
+ * Event map for the global EventBus.
+ *
+ * Defines all cross-cutting events that flow between core, plugins, and adapters.
+ * Plugins subscribe via `eventBus.on(...)` without needing direct references
+ * to the components that emit these events.
+ */
 interface EventBusEvents {
     "session:created": (data: {
         sessionId: string;
@@ -1307,9 +2006,18 @@ interface EventBusEvents {
         error?: string;
     }) => void;
 }
+/**
+ * Global event bus for cross-cutting communication.
+ *
+ * Decouples plugins from direct session/core references — plugins and adapters
+ * subscribe to bus events without knowing which component emits them. The core
+ * and sessions emit events here; plugins consume them for features like usage
+ * tracking, notifications, and UI updates.
+ */
 declare class EventBus extends TypedEmitter<EventBusEvents> {
 }
 
+/** Flattened view of a session for API consumers — merges live state with stored record. */
 interface SessionSummary {
     id: string;
     agent: string;
@@ -1326,30 +2034,63 @@ interface SessionSummary {
     capabilities: AgentCapabilities | null;
     isLive: boolean;
 }
+/**
+ * Registry for live Session instances. Provides lookup by session ID, channel+thread,
+ * or agent session ID. Coordinates session lifecycle: creation, cancellation, persistence,
+ * and graceful shutdown.
+ *
+ * Live sessions are kept in an in-memory Map. The optional SessionStore handles
+ * disk persistence — the manager delegates save/patch/remove operations to the store.
+ */
 declare class SessionManager {
     private sessions;
     private store;
     private eventBus?;
     middlewareChain?: MiddlewareChain;
+    /**
+     * Inject the EventBus after construction. Deferred because EventBus is created
+     * after SessionManager during bootstrap, so it cannot be passed to the constructor.
+     */
     setEventBus(eventBus: EventBus): void;
     constructor(store?: SessionStore | null);
+    /** Create a new session by spawning an agent and persisting the initial record. */
     createSession(channelId: string, agentName: string, workingDirectory: string, agentManager: AgentManager): Promise<Session>;
+    /** Look up a live session by its OpenACP session ID. */
     getSession(sessionId: string): Session | undefined;
+    /** Look up a live session by adapter channel and thread ID (checks per-adapter threadIds map first, then legacy fields). */
     getSessionByThread(channelId: string, threadId: string): Session | undefined;
+    /** Look up a live session by the agent's internal session ID (assigned by the ACP subprocess). */
     getSessionByAgentSessionId(agentSessionId: string): Session | undefined;
+    /** Look up the persisted SessionRecord by the agent's internal session ID. */
     getRecordByAgentSessionId(agentSessionId: string): SessionRecord | undefined;
+    /** Look up the persisted SessionRecord by channel and thread ID. */
     getRecordByThread(channelId: string, threadId: string): SessionRecord | undefined;
+    /** Register a session that was created externally (e.g. restored from store on startup). */
     registerSession(session: Session): void;
+    /**
+     * Merge a partial update into the stored SessionRecord. If no record exists yet and
+     * the patch includes `sessionId`, it is treated as an initial save.
+     * Pass `{ immediate: true }` to flush the store to disk synchronously.
+     */
     patchRecord(sessionId: string, patch: Partial<SessionRecord>, options?: {
         immediate?: boolean;
     }): Promise<void>;
+    /** Retrieve the persisted SessionRecord for a given session ID. Returns undefined if no store or record not found. */
     getSessionRecord(sessionId: string): SessionRecord | undefined;
+    /** Cancel a session: abort in-flight prompt, transition to cancelled, destroy agent, and persist. */
     cancelSession(sessionId: string): Promise<void>;
+    /** List live (in-memory) sessions, optionally filtered by channel. Excludes assistant sessions. */
     listSessions(channelId?: string): Session[];
+    /**
+     * List all sessions (live + stored) as SessionSummary. Live sessions take precedence
+     * over stored records — their real-time state (queueDepth, promptRunning) is used.
+     */
     listAllSessions(channelId?: string): SessionSummary[];
+    /** List all stored SessionRecords, optionally filtered by status. Excludes assistant sessions. */
     listRecords(filter?: {
         statuses?: string[];
     }): SessionRecord[];
+    /** Remove a session's stored record and emit a SESSION_DELETED event. */
     removeRecord(sessionId: string): Promise<void>;
     /**
      * Graceful shutdown: persist session state without killing agent subprocesses.
@@ -1365,13 +2106,38 @@ declare class SessionManager {
     destroyAll(): Promise<void>;
 }
 
+/**
+ * Routes cross-session notifications to the appropriate channel adapter.
+ *
+ * Notifications are triggered by `SessionBridge` when a session completes,
+ * errors, or hits a budget threshold. Unlike regular messages, notifications
+ * are not tied to a specific outgoing message stream — they are pushed to the
+ * channel that owns the session (identified by `channelId` on the session).
+ *
+ * The adapters Map is the live registry maintained by `OpenACPCore`. Holding a
+ * reference to the Map (rather than a snapshot) ensures that adapters registered
+ * after this service is created are still reachable.
+ */
 declare class NotificationManager {
     private adapters;
     constructor(adapters: Map<string, IChannelAdapter>);
+    /**
+     * Send a notification to a specific channel adapter.
+     *
+     * Failures are swallowed — notifications are best-effort and must not crash
+     * the session or caller (e.g. on session completion).
+     */
     notify(channelId: string, notification: NotificationMessage): Promise<void>;
+    /**
+     * Broadcast a notification to every registered adapter.
+     *
+     * Used for system-wide alerts (e.g. global budget exhausted). Each adapter
+     * failure is isolated so one broken adapter cannot block the rest.
+     */
     notifyAll(notification: NotificationMessage): Promise<void>;
 }
 
+/** Services required by SessionBridge for message transformation, persistence, and middleware. */
 interface BridgeDeps {
     messageTransformer: MessageTransformer;
     notificationManager: NotificationManager;
@@ -1380,6 +2146,18 @@ interface BridgeDeps {
     fileService?: FileServiceInterface;
     middlewareChain?: MiddlewareChain;
 }
+/**
+ * Connects a Session to a channel adapter, forwarding agent events to the adapter's
+ * stream interface and wiring up permission handling, lifecycle persistence, and middleware.
+ *
+ * Each adapter attached to a session gets its own bridge. The bridge subscribes to
+ * Session events (agent_event, permission_request, status_change, etc.) and translates
+ * them into adapter-specific calls (sendMessage, sendPermissionRequest, renameSessionThread).
+ *
+ * Multi-adapter routing: when a TurnContext is active, turn events (text, tool_call, etc.)
+ * are forwarded only to the adapter that originated the prompt. System events (commands_update,
+ * session_end, etc.) are always broadcast to all bridges.
+ */
 declare class SessionBridge {
     private session;
     private adapter;
@@ -1393,9 +2171,20 @@ declare class SessionBridge {
     private listen;
     /** Send message to adapter, optionally running through message:outgoing middleware */
     private sendMessage;
-    /** Determine if this bridge should forward the given event based on turn routing. */
+    /**
+     * Determine if this bridge should forward the given event based on turn routing.
+     * System events are always forwarded; turn events are routed only to the target adapter.
+     */
     shouldForward(event: AgentEvent): boolean;
+    /**
+     * Subscribe to session events and start forwarding them to the adapter.
+     *
+     * Wires: agent events → adapter dispatch, permission UI, lifecycle persistence
+     * (status changes, naming, prompt count), and EventBus notifications.
+     * Also replays any commands or config options that arrived before the bridge connected.
+     */
     connect(): void;
+    /** Unsubscribe all session event listeners and clean up adapter state. */
     disconnect(): void;
     /** Dispatch an agent event through middleware and to the adapter */
     private dispatchAgentEvent;
@@ -1410,6 +2199,11 @@ declare class SessionBridge {
     private emitAfterResolve;
 }
 
+/**
+ * Represents a single running (or recently failed) tunnel.
+ * `type: "system"` is the main OpenACP tunnel; `type: "user"` are agent-created tunnels.
+ * `status` transitions: starting → active | failed. Failed entries may auto-retry.
+ */
 interface TunnelEntry {
     port: number;
     type: 'system' | 'user';
@@ -1422,6 +2216,12 @@ interface TunnelEntry {
     createdAt: string;
 }
 
+/**
+ * Metadata for a single viewer entry.
+ * For `type: "diff"`, `content` holds the new text and `oldContent` holds the original.
+ * For `type: "output"`, `filePath` is used as the display label (not a real file path).
+ * Entries expire after the configured TTL and are cleaned up lazily on read and periodically.
+ */
 interface ViewerEntry {
     id: string;
     type: 'file' | 'diff' | 'output';
@@ -1434,6 +2234,13 @@ interface ViewerEntry {
     createdAt: number;
     expiresAt: number;
 }
+/**
+ * In-memory store for content shared via tunnel viewer routes.
+ *
+ * Agents call `storeFile()` / `storeDiff()` / `storeOutput()` to get a short URL id,
+ * then pass that URL to the user. The viewer routes serve HTML pages using the stored content.
+ * Content is scoped to the session's working directory to avoid leaking files outside the workspace.
+ */
 declare class ViewerStore {
     private entries;
     private cleanupTimer;
@@ -1449,6 +2256,11 @@ declare class ViewerStore {
     destroy(): void;
 }
 
+/**
+ * Tunnel plugin settings shape.
+ * `port` is deprecated — the tunnel now always points to the API server port.
+ * `auth` is deprecated — viewer routes are public; authentication was removed.
+ */
 interface TunnelConfig {
     enabled: boolean;
     port: number;
@@ -1462,6 +2274,14 @@ interface TunnelConfig {
     };
 }
 
+/**
+ * High-level facade over TunnelRegistry and ViewerStore.
+ *
+ * Owns the system tunnel (started in `start()` once the API server port is known),
+ * user tunnel management (add/stop/list), and viewer URL generation.
+ * Registered as the `"tunnel"` service so other plugins can call `fileUrl()`,
+ * `diffUrl()`, etc. to share content via the public tunnel URL.
+ */
 declare class TunnelService {
     private registry;
     private store;
@@ -1488,12 +2308,26 @@ declare class TunnelService {
     outputUrl(entryId: string): string;
 }
 
+/**
+ * Abstract interface for conversation context sources.
+ *
+ * Two providers are built-in: "local" (history recorder) and "entire" (Claude Code checkpoints).
+ * ContextManager iterates providers in priority order and returns the first non-empty result.
+ */
 interface ContextProvider {
     readonly name: string;
     isAvailable(repoPath: string): Promise<boolean>;
     listSessions(query: ContextQuery): Promise<SessionListResult>;
     buildContext(query: ContextQuery, options?: ContextOptions): Promise<ContextResult>;
 }
+/**
+ * Describes which sessions to include in a context build.
+ *
+ * - `type: "latest"` with `value: "5"` returns the 5 most recent sessions.
+ * - `type: "session"` with a UUID returns exactly that session.
+ * - `type: "branch"` / `"commit"` / `"pr"` are only supported by the "entire" provider
+ *   which reads Claude Code checkpoints stored in the git repo.
+ */
 interface ContextQuery {
     repoPath: string;
     type: "branch" | "commit" | "pr" | "latest" | "checkpoint" | "session";
@@ -1507,6 +2341,11 @@ interface ContextOptions {
     /** When true, skip the context cache (use for live switches where history just changed) */
     noCache?: boolean;
 }
+/**
+ * Metadata for a single recorded session, used when listing available context.
+ * Fields like `checkpointId` and `transcriptPath` are populated by the "entire" provider;
+ * the "local" provider leaves them empty since it stores sessions in its own HistoryStore.
+ */
 interface SessionInfo {
     checkpointId: string;
     sessionIndex: string;
@@ -1523,7 +2362,18 @@ interface SessionListResult {
     sessions: SessionInfo[];
     estimatedTokens: number;
 }
+/**
+ * Controls how much detail is rendered per turn in the context markdown.
+ * - `full`: full diffs, tool call outputs, thinking blocks, usage stats
+ * - `balanced`: diffs truncated, thinking omitted
+ * - `compact`: single-line summary per turn pair (user + tools used)
+ */
 type ContextMode = "full" | "balanced" | "compact";
+/**
+ * The built context block to be prepended to an agent prompt.
+ * `markdown` is the formatted text; `truncated` is true when oldest sessions
+ * were dropped to fit within `maxTokens`.
+ */
 interface ContextResult {
     markdown: string;
     tokenEstimate: number;
@@ -1537,11 +2387,22 @@ interface ContextResult {
     };
 }
 
+/**
+ * Root structure persisted to disk for one session.
+ * `version` allows future schema migrations without breaking existing files.
+ */
 interface SessionHistory {
     version: 1;
     sessionId: string;
     turns: Turn[];
 }
+/**
+ * One complete user→assistant exchange within a session.
+ *
+ * User turns carry `content` + optional `attachments`.
+ * Assistant turns carry `steps` (the sequence of actions the agent took)
+ * plus optional `usage` (token/cost accounting) and `stopReason`.
+ */
 interface Turn {
     index: number;
     role: "user" | "assistant";
@@ -1641,6 +2502,12 @@ interface ConfigChangeStep {
     value: string;
 }
 
+/**
+ * Persists session history to disk as one JSON file per session.
+ *
+ * Files are stored as `<dir>/<sessionId>.json`. The path is validated to prevent
+ * directory traversal — session IDs that resolve outside `dir` are rejected.
+ */
 declare class HistoryStore {
     private readonly dir;
     constructor(dir: string);
@@ -1652,12 +2519,30 @@ declare class HistoryStore {
     private filePath;
 }
 
+/**
+ * Orchestrates context providers and caching.
+ *
+ * Providers are tried in registration order — the first one that is available
+ * and returns non-empty markdown wins. This lets the "local" history provider
+ * take priority over the "entire" checkpoint provider for sessions that are
+ * still in progress (not yet checkpointed).
+ *
+ * The context service is registered under the `"context"` key in the
+ * ServiceRegistry so other plugins (e.g. the git-pilot plugin) can call
+ * `buildContext()` before injecting context into a new agent.
+ */
 declare class ContextManager {
     private providers;
     private cache;
     private historyStore?;
     private sessionFlusher?;
-    constructor(cachePath?: string);
+    constructor(cachePath: string);
+    /**
+     * Wire in the history store after construction.
+     *
+     * Injected separately because the history store (backed by the context plugin's
+     * recorder) may not be ready when ContextManager is first instantiated.
+     */
     setHistoryStore(store: HistoryStore): void;
     /** Register a callback that flushes in-memory recorder state for a session to disk. */
     registerFlusher(fn: (sessionId: string) => Promise<void>): void;
@@ -1667,13 +2552,45 @@ declare class ContextManager {
      * where the last turn hasn't been persisted yet.
      */
     flushSession(sessionId: string): Promise<void>;
+    /**
+     * Read the raw history for a session directly from the history store.
+     *
+     * Returns null if no historyStore has been configured via `setHistoryStore()`,
+     * or if the session has no recorded history.
+     */
     getHistory(sessionId: string): Promise<SessionHistory | null>;
+    /**
+     * Register a provider. Providers are queried in insertion order.
+     * Register higher-priority sources (e.g. local history) before lower-priority ones (e.g. entire).
+     */
     register(provider: ContextProvider): void;
+    /**
+     * Return the first provider that reports itself available for the given repo.
+     *
+     * This is a availability check — it returns the highest-priority available provider
+     * (i.e. the first registered one that passes `isAvailable`), not necessarily the
+     * one that would yield the richest context for a specific query.
+     */
     getProvider(repoPath: string): Promise<ContextProvider | null>;
+    /**
+     * List sessions using the same provider-waterfall logic as `buildContext`.
+     *
+     * Tries each registered provider in order, returning the first non-empty result.
+     * Unlike `buildContext`, results are not cached — callers should avoid calling
+     * this in hot paths.
+     */
     listSessions(query: ContextQuery): Promise<SessionListResult | null>;
+    /**
+     * Build a context block for injection into an agent prompt.
+     *
+     * Tries each registered provider in order. Results are cached by (repoPath + queryKey)
+     * to avoid redundant disk reads. Pass `options.noCache = true` when the caller knows
+     * the history just changed (e.g. immediately after an agent switch + flush).
+     */
     buildContext(query: ContextQuery, options?: ContextOptions): Promise<ContextResult | null>;
 }
 
+/** Parameters for creating a new session — used by SessionFactory.create() and Core.createFullSession(). */
 interface SessionCreateParams {
     channelId: string;
     agentName: string;
@@ -1688,6 +2605,14 @@ interface SideEffectDeps {
     notificationManager: NotificationManager;
     tunnelService?: TunnelService;
 }
+/**
+ * Constructs new Sessions with the right agent, working directory, and initial state.
+ *
+ * Handles agent spawning (or resuming from a previous ACP session), middleware integration,
+ * ACP state hydration, and side-effect wiring (usage tracking, tunnel cleanup).
+ * Also provides lazy resume: when a message arrives for a stored (not live) session,
+ * the factory transparently resumes it by re-spawning the agent with the stored session ID.
+ */
 declare class SessionFactory {
     private agentManager;
     private sessionManager;
@@ -1717,6 +2642,10 @@ declare class SessionFactory {
     getAgentAllowedPaths?: () => string[];
     constructor(agentManager: AgentManager, sessionManager: SessionManager, speechServiceAccessor: SpeechService | (() => SpeechService), eventBus: EventBus, instanceRoot?: string | undefined);
     private get speechService();
+    /**
+     * Create a new Session: spawn agent → create Session instance → hydrate ACP state → register.
+     * Runs session:beforeCreate middleware (which can modify params or block creation).
+     */
     create(params: SessionCreateParams): Promise<Session>;
     /**
      * Get active session by thread, or attempt lazy resume from store.
@@ -1724,7 +2653,13 @@ declare class SessionFactory {
      */
     getOrResume(channelId: string, threadId: string): Promise<Session | null>;
     getOrResumeById(sessionId: string): Promise<Session | null>;
+    /**
+     * Attempt to resume a session from disk when a message arrives on a thread with
+     * no live session. Deduplicates concurrent resume attempts for the same thread
+     * via resumeLocks to avoid spawning multiple agents.
+     */
     private lazyResume;
+    /** Create a brand-new session, resolving agent name and workspace from config if not provided. */
     handleNewSession(channelId: string, agentName?: string, workspacePath?: string, options?: {
         createThread?: boolean;
         threadId?: string;
@@ -1732,6 +2667,7 @@ declare class SessionFactory {
     /** 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>;
+    /** Create a session and inject conversation context from a ContextProvider (e.g., history from a previous session). */
     createSessionWithContext(params: {
         channelId: string;
         agentName: string;
@@ -1744,13 +2680,29 @@ declare class SessionFactory {
         session: Session;
         contextResult: ContextResult | null;
     }>;
+    /** Wire session-level side effects: usage tracking (via EventBus) and tunnel cleanup on session end. */
     wireSideEffects(session: Session, deps: SideEffectDeps): void;
 }
 
+/**
+ * Configuration for the SecurityGuard access policy.
+ *
+ * `allowedUserIds`: if non-empty, only users whose string ID appears in this list
+ * are permitted. An empty array means "allow all" (open access).
+ * `maxConcurrentSessions`: caps how many active/initializing sessions may exist
+ * at once across all users, preventing resource exhaustion.
+ */
 interface SecurityConfig {
     allowedUserIds: string[];
     maxConcurrentSessions: number;
 }
+/**
+ * Enforces user allowlist and global session-count limits on every incoming message.
+ *
+ * Implemented as a plugin service (rather than baked into core) so that the access
+ * policy is swappable — deployments can replace or extend it without touching core.
+ * The plugin registers this guard as a `message:incoming` middleware handler.
+ */
 declare class SecurityGuard {
     private getSecurityConfig;
     private sessionManager;
@@ -1759,6 +2711,16 @@ declare class SecurityGuard {
             status: string;
         }>;
     });
+    /**
+     * Returns `{ allowed: true }` when the message may proceed, or
+     * `{ allowed: false, reason }` when it should be blocked.
+     *
+     * Two checks run in order:
+     * 1. **Allowlist** — if `allowedUserIds` is non-empty, the user's ID (coerced to string)
+     *    must appear in the list. Telegram/Slack IDs are numbers, so coercion is required.
+     * 2. **Session cap** — counts sessions in `active` or `initializing` state. `initializing`
+     *    is included because a session holds resources before it reaches `active`.
+     */
     checkAccess(message: {
         userId: string | number;
     }): Promise<{
@@ -1769,46 +2731,91 @@ declare class SecurityGuard {
     }>;
 }
 
+/**
+ * Central service discovery for the plugin system.
+ *
+ * Plugins register service implementations by string key (e.g., 'security', 'speech').
+ * Core and other plugins retrieve them via typed accessors:
+ *   `registry.get<SecurityService>('security')`
+ *
+ * Each service key is unique — registering a duplicate throws unless `registerOverride` is used.
+ * Services are tracked by the owning plugin name so they can be bulk-removed on plugin unload.
+ */
 declare class ServiceRegistry {
     private services;
+    /**
+     * Register a service. Throws if the service name is already taken.
+     * Use `registerOverride` to intentionally replace an existing service.
+     */
     register<T>(name: string, implementation: T, pluginName: string): void;
+    /** Register a service, replacing any existing registration (used by override plugins). */
     registerOverride<T>(name: string, implementation: T, pluginName: string): void;
+    /** Retrieve a service by name. Returns undefined if not registered. */
     get<T>(name: string): T | undefined;
+    /** Check whether a service is registered. */
     has(name: string): boolean;
+    /** List all registered services with their owning plugin names. */
     list(): Array<{
         name: string;
         pluginName: string;
     }>;
+    /** Remove a single service by name. */
     unregister(name: string): void;
+    /** Remove all services owned by a specific plugin (called during plugin unload). */
     unregisterByPlugin(pluginName: string): void;
 }
 
+/**
+ * Persisted metadata about an installed plugin.
+ *
+ * This is the registry's view of a plugin — install state, version, source.
+ * Distinct from `OpenACPPlugin` which is the runtime instance with setup/teardown hooks.
+ */
 interface PluginEntry {
     version: string;
     installedAt: string;
     updatedAt: string;
+    /** How the plugin was installed: bundled with core, from npm, or from a local path */
     source: 'builtin' | 'npm' | 'local';
     enabled: boolean;
     settingsPath: string;
     description?: string;
 }
 type RegisterInput = Omit<PluginEntry, 'installedAt' | 'updatedAt'>;
+/**
+ * Tracks which plugins are installed, their versions, and enabled state.
+ * Persisted as JSON at `~/.openacp/plugins/registry.json`.
+ *
+ * Used by LifecycleManager to detect version changes (triggering migration)
+ * and to skip disabled plugins at boot time.
+ */
 declare class PluginRegistry {
     private registryPath;
     private data;
     constructor(registryPath: string);
+    /** Return all installed plugins as a Map. */
     list(): Map<string, PluginEntry>;
+    /** Look up a plugin by name. Returns undefined if not installed. */
     get(name: string): PluginEntry | undefined;
+    /** Record a newly installed plugin. Timestamps are set automatically. */
     register(name: string, entry: RegisterInput): void;
+    /** Remove a plugin from the registry. */
     remove(name: string): void;
+    /** Enable or disable a plugin. Disabled plugins are skipped at boot. */
     setEnabled(name: string, enabled: boolean): void;
+    /** Update the stored version (called after successful migration). */
     updateVersion(name: string, version: string): void;
+    /** Return only enabled plugins. */
     listEnabled(): Map<string, PluginEntry>;
+    /** Filter plugins by installation source. */
     listBySource(source: PluginEntry['source']): Map<string, PluginEntry>;
+    /** Load registry data from disk. Silently starts empty if file doesn't exist. */
     load(): Promise<void>;
+    /** Persist registry data to disk. */
     save(): Promise<void>;
 }
 
+/** Options for constructing a LifecycleManager. All fields are optional with sensible defaults. */
 interface LifecycleManagerOpts {
     serviceRegistry?: ServiceRegistry;
     middlewareChain?: MiddlewareChain;
@@ -1828,6 +2835,21 @@ interface LifecycleManagerOpts {
     /** Root directory for this OpenACP instance (default: ~/.openacp) */
     instanceRoot?: string;
 }
+/**
+ * Orchestrates plugin boot, teardown, and hot-reload.
+ *
+ * Boot sequence:
+ * 1. Topological sort by `pluginDependencies` — ensures a plugin's deps are ready first
+ * 2. Version migration if registry version != plugin version
+ * 3. Settings validation against Zod schema
+ * 4. Create scoped PluginContext, call `plugin.setup(ctx)` with timeout
+ *
+ * Error isolation: if a plugin's setup() fails, it is marked as failed and skipped.
+ * Any plugin that depends on a failed plugin is also skipped (cascade failure).
+ * Other independent plugins continue booting normally.
+ *
+ * Shutdown calls teardown() in reverse boot order — dependencies are torn down last.
+ */
 declare class LifecycleManager {
     readonly serviceRegistry: ServiceRegistry;
     readonly middlewareChain: MiddlewareChain;
@@ -1845,8 +2867,11 @@ declare class LifecycleManager {
     private loadOrder;
     private _loaded;
     private _failed;
+    /** Names of plugins that successfully completed setup(). */
     get loadedPlugins(): string[];
+    /** Names of plugins whose setup() threw an error. These plugins are skipped but don't crash the system. */
     get failedPlugins(): string[];
+    /** The PluginRegistry tracking installed and enabled plugin state. */
     get registry(): PluginRegistry | undefined;
     /** Plugin definitions currently in load order (loaded + failed). */
     get plugins(): OpenACPPlugin[];
@@ -1854,20 +2879,46 @@ declare class LifecycleManager {
     get instanceRoot(): string | undefined;
     constructor(opts?: LifecycleManagerOpts);
     private getPluginLogger;
+    /**
+     * Boot a set of plugins in dependency order.
+     *
+     * Can be called multiple times (e.g., core plugins first, then dev plugins later).
+     * Already-loaded plugins are included in dependency resolution but not re-booted.
+     */
     boot(plugins: OpenACPPlugin[]): Promise<void>;
+    /**
+     * Unload a single plugin: call teardown(), clean up its context
+     * (listeners, middleware, services), and remove from tracked state.
+     * Used for hot-reload: unload → rebuild → re-boot.
+     */
     unloadPlugin(name: string): Promise<void>;
+    /**
+     * Gracefully shut down all loaded plugins.
+     * Teardown runs in reverse boot order so that dependencies outlive their dependents.
+     */
     shutdown(): Promise<void>;
 }
 
+/**
+ * Registry for interactive menu items displayed to users (e.g. Telegram inline keyboards).
+ *
+ * Core registers default items (new session, agents, help, etc.) during construction.
+ * Plugins can add their own items. Items are sorted by priority (lower = higher position)
+ * and filtered by an optional `visible()` predicate at render time.
+ */
 declare class MenuRegistry {
     private items;
+    /** Register or replace a menu item by its unique ID. */
     register(item: MenuItem): void;
+    /** Remove a menu item by ID. */
     unregister(id: string): void;
+    /** Look up a single menu item by ID. */
     getItem(id: string): MenuItem | undefined;
-    /** Get all visible items sorted by priority */
+    /** Get all visible items sorted by priority (lower number = shown first). */
     getItems(): MenuItem[];
 }
 
+/** Subset of OpenACPCore methods needed by AssistantManager, avoiding a circular import. */
 interface AssistantManagerCore {
     createSession(params: {
         channelId: string;
@@ -1887,46 +2938,96 @@ interface AssistantManagerCore {
     };
     sessionStore: SessionStore | null;
 }
+/**
+ * Manages the OpenACP built-in assistant session.
+ *
+ * The assistant is a special session (marked with `isAssistant: true`) that
+ * can answer questions about the running OpenACP system — sessions, agents,
+ * config, etc. Unlike user-created sessions, it is created and managed by
+ * core, and its system prompt is dynamically composed from registry sections
+ * that inject live system state.
+ *
+ * One assistant session exists per channel. The system prompt is built at
+ * spawn time and deferred — it's prepended to the first user message rather
+ * than sent immediately, so the agent receives it alongside real context.
+ */
 declare class AssistantManager {
     private core;
     private registry;
     private sessions;
     private pendingSystemPrompts;
     constructor(core: AssistantManagerCore, registry: AssistantRegistry);
+    /**
+     * Returns the assistant session for a channel, creating one if needed.
+     *
+     * If a persisted assistant session exists in the store, it is reused
+     * (same session ID) to preserve conversation history. The system prompt
+     * is always rebuilt fresh and deferred until the first user message.
+     */
     getOrSpawn(channelId: string, threadId: string): Promise<Session>;
+    /** Returns the active assistant session for a channel, or null if none exists. */
     get(channelId: string): Session | null;
     /**
      * Consume and return any pending system prompt for a channel.
      * Should be prepended to the first real user message.
      */
     consumePendingSystemPrompt(channelId: string): string | undefined;
+    /** Checks whether a given session ID belongs to the built-in assistant. */
     isAssistant(sessionId: string): boolean;
 }
 
+/**
+ * Describes a single OpenACP instance and all its filesystem paths.
+ *
+ * An "instance" is one running OpenACP server process, identified by a
+ * unique ID. Multiple instances can run on the same machine with different
+ * configs, ports, and data directories. The instance root is typically
+ * `<workspace>/.openacp/`.
+ */
 interface InstanceContext {
+    /** Unique identifier for this instance (UUID). */
     id: string;
+    /** Absolute path to the instance root directory (e.g. `~/my-project/.openacp/`). */
     root: string;
-    isGlobal: boolean;
+    /** Pre-resolved paths to all instance files and directories. */
     paths: {
         config: string;
         sessions: string;
         agents: string;
+        /** Shared across all instances — lives under ~/.openacp/cache/. */
         registryCache: string;
         plugins: string;
         pluginsData: string;
         pluginRegistry: string;
         logs: string;
+        /** PID file written by the daemon process to track the running server. */
         pid: string;
+        /** Marker file that indicates the daemon was intentionally started. */
         running: string;
+        /** Written at startup with the API server's port number. */
         apiPort: string;
         apiSecret: string;
+        /** Shared across all instances — lives under ~/.openacp/bin/. */
         bin: string;
         cache: string;
         tunnels: string;
+        /** Shared across all instances — lives under ~/.openacp/agents/. */
         agentsDir: string;
     };
 }
 
+/**
+ * Top-level orchestrator that wires all OpenACP modules together.
+ *
+ * Responsibilities:
+ * - Registers messaging adapters (Telegram, Slack, SSE, etc.)
+ * - Routes incoming messages to the correct Session (by channel + thread)
+ * - Manages the full session lifecycle: creation, agent switch, archive, shutdown
+ * - Connects agent events to adapter callbacks via SessionBridge
+ * - Accesses plugin-provided services (security, notifications, speech, etc.)
+ *   through ServiceRegistry rather than direct references, since plugins
+ *   register their services asynchronously during boot
+ */
 declare class OpenACPCore {
     configManager: ConfigManager;
     agentCatalog: AgentCatalog;
@@ -1944,30 +3045,93 @@ declare class OpenACPCore {
     sessionFactory: SessionFactory;
     readonly lifecycleManager: LifecycleManager;
     private agentSwitchHandler;
-    readonly instanceContext?: InstanceContext;
+    readonly instanceContext: InstanceContext;
     readonly menuRegistry: MenuRegistry;
     readonly assistantRegistry: AssistantRegistry;
     assistantManager: AssistantManager;
+    /** @throws if the service hasn't been registered by its plugin yet */
     private getService;
+    /** Access control and rate-limiting guard (provided by security plugin). */
     get securityGuard(): SecurityGuard;
+    /** Cross-session notification delivery (provided by notifications plugin). */
     get notificationManager(): NotificationManager;
+    /** File I/O service for agent attachment storage (provided by file-service plugin). */
     get fileService(): FileServiceInterface;
+    /** Text-to-speech / speech-to-text engine (provided by speech plugin). */
     get speechService(): SpeechService;
+    /** Conversation history builder for context injection (provided by context plugin). */
     get contextManager(): ContextManager;
+    /** Per-plugin persistent settings (e.g. API keys). */
     get settingsManager(): SettingsManager | undefined;
-    constructor(configManager: ConfigManager, ctx?: InstanceContext);
+    /**
+     * Bootstrap all core subsystems. The boot order matters:
+     * 1. AgentCatalog + AgentManager (agent definitions)
+     * 2. SessionStore + SessionManager (session persistence and lookup)
+     * 3. EventBus (inter-module communication)
+     * 4. SessionFactory (session creation pipeline)
+     * 5. LifecycleManager (plugin infrastructure)
+     * 6. Wire middleware chain into factory + manager
+     * 7. AgentSwitchHandler, config listeners, menu/assistant registries
+     */
+    constructor(configManager: ConfigManager, ctx: InstanceContext);
+    /** Optional tunnel for generating public URLs (code viewer links, etc.). */
     get tunnelService(): TunnelService | undefined;
+    /** Propagate tunnel service to MessageTransformer so it can generate viewer links. */
     set tunnelService(service: TunnelService | undefined);
+    /**
+     * Register a messaging adapter (e.g. Telegram, Slack, SSE).
+     *
+     * Adapters must be registered before `start()`. The adapter name serves as its
+     * channel ID throughout the system — used in session records, bridge keys, and routing.
+     */
     registerAdapter(name: string, adapter: IChannelAdapter): void;
+    /**
+     * Start all registered adapters. Adapters that fail are logged but do not
+     * prevent others from starting. Throws only if ALL adapters fail.
+     */
     start(): Promise<void>;
+    /**
+     * Graceful shutdown: notify users, persist session state, stop adapters.
+     * Agent subprocesses are not explicitly killed — they exit with the parent process.
+     */
     stop(): Promise<void>;
+    /**
+     * Archive a session: delete its adapter topic/thread and cancel the session.
+     *
+     * Only sessions in archivable states (active, cancelled, error) can be archived —
+     * initializing and finished sessions are excluded.
+     * The adapter handles platform-side cleanup (e.g. deleting a Telegram topic).
+     */
     archiveSession(sessionId: string): Promise<{
         ok: true;
     } | {
         ok: false;
         error: string;
     }>;
+    /**
+     * Route an incoming platform message to the appropriate session.
+     *
+     * Flow:
+     * 1. Run `message:incoming` middleware (plugins can modify or block)
+     * 2. SecurityGuard checks user access and per-user session limits
+     * 3. Find session by channel+thread (in-memory lookup, then lazy resume from disk)
+     * 4. For assistant sessions, prepend any deferred system prompt
+     * 5. Emit `message:queued` for SSE clients, then enqueue the prompt on the session
+     *
+     * If no session is found, the user is told to start one with /new.
+     */
     handleMessage(message: IncomingMessage): Promise<void>;
+    /**
+     * Create (or resume) a session with full wiring: agent, adapter thread, bridge, persistence.
+     *
+     * This is the single entry point for session creation. The pipeline:
+     * 1. SessionFactory spawns/resumes the agent process
+     * 2. Adapter creates a thread/topic if requested
+     * 3. Initial session record is persisted (so lazy resume can find it by threadId)
+     * 4. SessionBridge connects agent events to the adapter
+     * 5. For headless sessions (no adapter), fallback event handlers are wired inline
+     * 6. Side effects (usage tracking, tunnel cleanup) are attached
+     */
     createSession(params: {
         channelId: string;
         agentName: string;
@@ -1979,10 +3143,17 @@ declare class OpenACPCore {
         threadId?: string;
         isAssistant?: boolean;
     }): Promise<Session>;
+    /** Convenience wrapper: create a new session with default agent/workspace resolution. */
     handleNewSession(channelId: string, agentName?: string, workspacePath?: string, options?: {
         createThread?: boolean;
         threadId?: string;
     }): Promise<Session>;
+    /**
+     * Adopt an externally-started agent session (e.g. from a CLI `openacp adopt` command).
+     *
+     * Validates that the agent supports resume, checks session limits, avoids duplicates,
+     * then creates a full session via the unified pipeline with resume semantics.
+     */
     adoptSession(agentName: string, agentSessionId: string, cwd: string, channelId?: string): Promise<{
         ok: true;
         sessionId: string;
@@ -1993,7 +3164,9 @@ declare class OpenACPCore {
         error: string;
         message: string;
     }>;
+    /** Start a new chat within the same agent and workspace as the current session's thread. */
     handleNewChat(channelId: string, currentThreadId: string): Promise<Session | null>;
+    /** Create a session and inject conversation context from a prior session or repo. */
     createSessionWithContext(params: {
         channelId: string;
         agentName: string;
@@ -2006,15 +3179,29 @@ declare class OpenACPCore {
         session: Session;
         contextResult: ContextResult | null;
     }>;
+    /** Switch a session's active agent. Delegates to AgentSwitchHandler for state coordination. */
     switchSessionAgent(sessionId: string, toAgent: string): Promise<{
         resumed: boolean;
     }>;
+    /** Find a session by channel+thread, resuming from disk if not in memory. */
     getOrResumeSession(channelId: string, threadId: string): Promise<Session | null>;
+    /** Find a session by ID, resuming from disk if not in memory. */
     getOrResumeSessionById(sessionId: string): Promise<Session | null>;
+    /**
+     * Attach an additional adapter to an existing session (multi-adapter support).
+     *
+     * Creates a thread on the target adapter and connects a SessionBridge so the
+     * session's agent events are forwarded to both the primary and attached adapters.
+     */
     attachAdapter(sessionId: string, adapterId: string): Promise<{
         threadId: string;
     }>;
+    /**
+     * Detach a secondary adapter from a session. The primary adapter (channelId) cannot
+     * be detached. Disconnects the bridge and cleans up thread mappings.
+     */
     detachAdapter(sessionId: string, adapterId: string): Promise<void>;
+    /** Build the platforms map (adapter → thread/topic IDs) for persistence. */
     private buildPlatformsFromSession;
     /** Composite bridge key: "adapterId:sessionId" */
     private bridgeKey;
@@ -2022,11 +3209,20 @@ declare class OpenACPCore {
     private getSessionBridgeKeys;
     /** Connect a session bridge for the given session (used by AssistantManager) */
     connectSessionBridge(session: Session): void;
-    /** Create a SessionBridge for the given session and adapter.
-     *  Disconnects any existing bridge for the same adapter+session first. */
+    /**
+     * Create a SessionBridge for the given session and adapter.
+     *
+     * The bridge subscribes to Session events (agent output, status changes, naming)
+     * and forwards them to the adapter for platform delivery. Disconnects any existing
+     * bridge for the same adapter+session first to avoid duplicate event handlers.
+     */
     createBridge(session: Session, adapter: IChannelAdapter, adapterId?: string): SessionBridge;
 }
 
+/**
+ * Internal representation of a registered command, extending CommandDef with
+ * a `scope` derived from the plugin name for namespace-qualified lookups.
+ */
 interface RegisteredCommand extends CommandDef {
     /** Scope extracted from pluginName, e.g. '@openacp/speech' → 'speech' */
     scope?: string;
@@ -2041,6 +3237,11 @@ interface RegisteredCommand extends CommandDef {
  * - Adapter plugins (@openacp/telegram, @openacp/discord)
  *   registering a command that already exists → stored as an override
  *   keyed by `channelId:commandName`, used when channelId matches.
+ *
+ * Note: this registry only handles slash commands (e.g. /new, /session).
+ * Callback button routing (inline keyboard buttons) is handled separately
+ * at the adapter level using a `c/` prefix — it is not part of command dispatch
+ * and does not go through this registry.
  */
 declare class CommandRegistry {
     /** Main registry: short names + qualified names → RegisteredCommand */
@@ -2065,27 +3266,53 @@ declare class CommandRegistry {
     /** 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
+     * Parse and execute a command string (e.g. "/greet hello world").
+     *
+     * Resolution order:
+     * 1. Adapter-specific override (e.g. Telegram's version of /new)
+     * 2. Short name or qualified name in the main registry
+     *
+     * Strips Telegram-style bot mentions (e.g. "/help@MyBot" → "help").
+     * Returns `{ type: 'delegated' }` if the handler returns null/undefined
+     * (meaning it handled the response itself, e.g. via assistant).
      */
     execute(commandString: string, baseArgs: CommandArgs): Promise<CommandResponse>;
     /** Extract scope from plugin name: '@openacp/speech' → 'speech', 'my-plugin' → 'my-plugin' */
     static extractScope(pluginName: string): string;
 }
 
+/**
+ * Type definitions for the doctor diagnostic system.
+ *
+ * The doctor runs a collection of checks, each producing CheckResults
+ * with a severity level. The CLI renders these results and optionally
+ * applies automatic fixes:
+ *
+ * - **pass** — check succeeded, shown as green checkmark
+ * - **warn** — non-critical issue, shown as yellow warning
+ * - **fail** — critical issue that will prevent OpenACP from working
+ *
+ * Fixable results include a `fix()` function with a risk level:
+ * - **safe** — auto-applied without prompting (e.g. creating missing dirs)
+ * - **risky** — requires user confirmation (e.g. resetting corrupted data)
+ */
+
+/** Result of a single diagnostic check within a category. */
 interface CheckResult {
     status: "pass" | "warn" | "fail";
     message: string;
+    /** Whether this result has an associated automatic fix. */
     fixable?: boolean;
+    /** "safe" fixes are applied automatically; "risky" fixes require user confirmation. */
     fixRisk?: "safe" | "risky";
     fix?: () => Promise<FixResult>;
 }
+/** Outcome of applying a fix. */
 interface FixResult {
     success: boolean;
     message: string;
 }
+/** Aggregated report returned by DoctorEngine.runAll(). */
 interface DoctorReport {
     categories: CategoryResult[];
     summary: {
@@ -2094,18 +3321,28 @@ interface DoctorReport {
         failed: number;
         fixed: number;
     };
+    /** Risky fixes that were deferred for user confirmation. */
     pendingFixes: PendingFix[];
 }
+/** All results for a single check category (e.g. "Config", "Agents"). */
 interface CategoryResult {
     name: string;
     results: CheckResult[];
 }
+/** A risky fix deferred for interactive user confirmation. */
 interface PendingFix {
     category: string;
     message: string;
     fix: () => Promise<FixResult>;
 }
 
+/**
+ * Orchestrates diagnostic checks for an OpenACP installation.
+ *
+ * Runs all registered checks in order, collects results, and automatically
+ * applies safe fixes (unless in dry-run mode). Risky fixes are collected
+ * as `pendingFixes` for the CLI to present interactively.
+ */
 declare class DoctorEngine {
     private dryRun;
     private dataDir;
@@ -2113,55 +3350,153 @@ declare class DoctorEngine {
         dryRun?: boolean;
         dataDir?: string;
     });
+    /**
+     * Executes all checks and returns an aggregated report.
+     *
+     * Safe fixes are applied inline (mutating CheckResult.message to show "Fixed").
+     * Risky fixes are deferred to `report.pendingFixes` for user confirmation.
+     */
     runAll(): Promise<DoctorReport>;
+    /** Constructs the shared context used by all checks — loads config if available. */
     private buildContext;
 }
 
+/**
+ * Config registry — declarative metadata for config fields.
+ *
+ * Each registered field describes its UI type, whether it can be hot-reloaded,
+ * and whether it's safe to expose via the API. This drives:
+ * - The API server's PATCH /api/config endpoint (validates + applies changes)
+ * - Hot-reload: fields marked `hotReload: true` take effect immediately via
+ *   ConfigManager's `config:changed` event, without requiring a restart
+ * - Security: only `scope: "safe"` fields are exposed to the REST API
+ */
+
+/**
+ * Metadata for a single config field, describing how it should be
+ * displayed, validated, and applied at runtime.
+ */
 interface ConfigFieldDef {
+    /** Dot-path into the Config object (e.g. "logging.level"). */
     path: string;
+    /** Human-readable label for UI display. */
     displayName: string;
+    /** Grouping key for organizing fields in the editor (e.g. "agent", "logging"). */
     group: string;
+    /** UI control type — determines validation and rendering. */
     type: "toggle" | "select" | "number" | "string";
+    /** For "select" type: allowed values, either static or derived from current config. */
     options?: string[] | ((config: Config) => string[]);
+    /** "safe" fields can be exposed via the API; "sensitive" fields require direct file access. */
     scope: "safe" | "sensitive";
+    /** Whether changes to this field take effect without restarting the server. */
     hotReload: boolean;
 }
+/**
+ * Static registry of all config fields that support programmatic access.
+ * Fields not listed here can still exist in config.json but won't be
+ * editable via the API or shown in the config UI.
+ */
 declare const CONFIG_REGISTRY: ConfigFieldDef[];
+/** Looks up a field definition by its dot-path. */
 declare function getFieldDef(path: string): ConfigFieldDef | undefined;
+/** Returns only fields safe to expose via the REST API. */
 declare function getSafeFields(): ConfigFieldDef[];
+/** Checks whether a config field can be changed without restarting the server. */
 declare function isHotReloadable(path: string): boolean;
+/** Resolves select options — evaluates the function form against the current config if needed. */
 declare function resolveOptions(def: ConfigFieldDef, config: Config): string[] | undefined;
+/** Traverses a config object by dot-path (e.g. "logging.level") and returns the value. */
 declare function getConfigValue(config: Config, path: string): unknown;
 
+/**
+ * Launches the interactive config editor.
+ *
+ * In `file` mode, changes accumulate and are written to disk on exit.
+ * In `api` mode, each section's changes are sent to the running daemon
+ * via the REST API, enabling hot-reload without restart.
+ */
 declare function runConfigEditor(configManager: ConfigManager, mode?: 'file' | 'api', apiPort?: number, settingsManager?: SettingsManager): Promise<void>;
 
-declare function getPidPath(root?: string): string;
-declare function getStatus(pidPath?: string): {
+/** Returns the path to the PID file for the given instance root. */
+declare function getPidPath(root: string): string;
+/**
+ * Return the running status and PID of the daemon.
+ * Cleans up stale PID files if the recorded process is no longer alive.
+ */
+declare function getStatus(pidPath: string): {
     running: boolean;
     pid?: number;
 };
-declare function startDaemon(pidPath?: string, logDir?: string, instanceRoot?: string): {
+/**
+ * Fork the daemon as a detached background process.
+ *
+ * Spawn mechanics:
+ * - The child runs `node <cli> --daemon-child` with OPENACP_INSTANCE_ROOT in its env.
+ * - `detached: true` creates a new process group so the child survives terminal close.
+ * - stdout/stderr are redirected to the log file (append mode); the parent closes its
+ *   copies immediately after spawn so the child holds the only references.
+ * - `child.unref()` removes the child from the parent's event loop reference count,
+ *   allowing the parent (`openacp start`) to exit while the child keeps running.
+ * - The PID file is written by both parent (early report) and child (authoritative write
+ *   in main.ts startServer) to handle race conditions with launchd/systemd starts.
+ */
+declare function startDaemon(pidPath: string, logDir: string | undefined, instanceRoot: string): {
     pid: number;
 } | {
     error: string;
 };
-declare function stopDaemon(pidPath?: string, instanceRoot?: string): Promise<{
+/**
+ * Gracefully stop the daemon, escalating to SIGKILL if it doesn't exit.
+ *
+ * Stop sequence:
+ * 1. Send SIGTERM; poll every 100ms for up to 5 seconds.
+ * 2. If still alive after 5s, send SIGKILL; poll for up to 1 more second.
+ * 3. If still alive after SIGKILL, the process is in uninterruptible I/O — very rare.
+ *
+ * Also clears the "running" marker so the daemon is not restarted on next login.
+ */
+declare function stopDaemon(pidPath: string, instanceRoot: string): Promise<{
     stopped: boolean;
     pid?: number;
     error?: string;
 }>;
 
+/** Returns true if the current platform supports auto-start management. */
 declare function isAutoStartSupported(): boolean;
-declare function installAutoStart(logDir: string): {
+/**
+ * Register the daemon as a login-time service for the given instance.
+ *
+ * macOS: writes a LaunchAgent plist and bootstraps it into the user's GUI session.
+ * Linux: writes a systemd user unit, reloads the daemon, and enables the service.
+ * Runs `migrateLegacy()` first to remove the old single-instance service if present.
+ */
+declare function installAutoStart(logDir: string, instanceRoot: string, instanceId: string): {
     success: boolean;
     error?: string;
 };
-declare function uninstallAutoStart(): {
+/**
+ * Remove the login-time service registration for the given instance.
+ * No-op if the service is not installed.
+ */
+declare function uninstallAutoStart(instanceId: string): {
     success: boolean;
     error?: string;
 };
-declare function isAutoStartInstalled(): boolean;
+/** Returns true if the login-time service is currently registered for this instance. */
+declare function isAutoStartInstalled(instanceId: string): boolean;
 
+/**
+ * Provides file I/O for session attachments and agent-generated files.
+ *
+ * All files are stored under `baseDir/<sessionId>/` so that access is naturally
+ * scoped per session and cleanup is a single directory removal. File names are
+ * sanitized and prefixed with a timestamp to prevent collisions and path traversal.
+ *
+ * This service acts as the security boundary between adapters/agents and the
+ * filesystem — callers never write directly; they go through `saveFile` so that
+ * naming, MIME classification, and path normalization are always applied.
+ */
 declare class FileService {
     readonly baseDir: string;
     constructor(baseDir: string);
@@ -2170,7 +3505,19 @@ declare class FileService {
      * Called on startup to prevent unbounded disk growth.
      */
     cleanupOldFiles(maxAgeDays: number): Promise<number>;
+    /**
+     * Persist a file to the session's directory and return an `Attachment` descriptor.
+     *
+     * The file name is sanitized (non-safe characters replaced with `_`) and prefixed
+     * with a millisecond timestamp to prevent name collisions across multiple saves in
+     * the same session. The original `fileName` is preserved in the returned descriptor
+     * so the user-facing name is not lost.
+     */
     saveFile(sessionId: string, fileName: string, data: Buffer, mimeType: string): Promise<Attachment>;
+    /**
+     * Build an `Attachment` descriptor for a file that already exists on disk.
+     * Returns `null` if the path does not exist or is not a regular file.
+     */
     resolveFile(filePath: string): Promise<Attachment | null>;
     /**
      * Convert OGG Opus audio to WAV format.
@@ -2188,6 +3535,7 @@ declare class FileService {
     }): Promise<string>;
     /** Instance method — delegates to static for FileServiceInterface compliance */
     extensionFromMime(mimeType: string): string;
+    /** Returns the canonical file extension for a given MIME type (e.g. `"image/png"` → `".png"`). */
     static extensionFromMime(mimeType: string): string;
 }
 
@@ -2196,12 +3544,15 @@ interface ApiConfig {
     host: string;
 }
 
+/** A token record persisted in tokens.json. Tokens are never deleted; they are revoked by flag. */
 interface StoredToken {
     id: string;
     name: string;
     role: string;
+    /** Custom scope overrides; when absent, role defaults from ROLES apply. */
     scopes?: string[];
     createdAt: string;
+    /** Absolute deadline after which the token cannot be refreshed — requires re-authentication. */
     refreshDeadline: string;
     lastUsedAt?: string;
     revoked: boolean;
@@ -2209,14 +3560,20 @@ interface StoredToken {
 interface CreateTokenOpts {
     role: string;
     name: string;
+    /** Duration string, e.g. "24h", "7d". Parsed by parseDuration(). */
     expire: string;
     scopes?: string[];
 }
+/**
+ * A one-time authorization code stored until exchange.
+ * The code is a 32-char hex string; it becomes unusable after `expiresAt` or first use.
+ */
 interface StoredCode {
     code: string;
     role: string;
     scopes?: string[];
     name: string;
+    /** Duration that the resulting JWT will be valid for. */
     expire: string;
     createdAt: string;
     expiresAt: string;
@@ -2227,9 +3584,21 @@ interface CreateCodeOpts {
     name: string;
     expire: string;
     scopes?: string[];
+    /** How long the code itself is valid; defaults to 30 minutes. */
     codeTtlMs?: number;
 }
 
+/**
+ * Persists JWT tokens and one-time authorization codes to a JSON file.
+ *
+ * Revocation is flag-based: tokens are marked `revoked: true` rather than deleted,
+ * so the auth middleware can distinguish a revoked token from an unknown one.
+ * Periodic cleanup (via `cleanup()`) removes tokens past their refresh deadline
+ * and expired/used codes to prevent unbounded file growth.
+ *
+ * Saves are asynchronous and coalesced: concurrent mutations schedule a single write
+ * to avoid thundering-herd disk I/O under bursty auth traffic.
+ */
 declare class TokenStore {
     private filePath;
     private tokens;
@@ -2237,64 +3606,150 @@ declare class TokenStore {
     private savePromise;
     private savePending;
     constructor(filePath: string);
+    /** Loads token and code state from disk. Safe to call at startup; missing file is not an error. */
     load(): Promise<void>;
     save(): Promise<void>;
+    /**
+     * Coalesces concurrent writes: if a save is in-flight, sets a pending flag
+     * so the next save fires immediately after the current one completes.
+     */
     private scheduleSave;
+    /** Creates a new token record and schedules a persist. Returns the stored token including its generated id. */
     create(opts: CreateTokenOpts): StoredToken;
     get(id: string): StoredToken | undefined;
+    /** Marks a token as revoked; future auth checks will reject it immediately. */
     revoke(id: string): void;
+    /** Returns all non-revoked tokens. Revoked tokens are retained until cleanup() removes them. */
     list(): StoredToken[];
     private lastUsedSaveTimer;
+    /**
+     * Records the current timestamp as `lastUsedAt` for the given token.
+     *
+     * Writes are debounced to 60 seconds — every API request updates this field,
+     * so flushing on every call would cause excessive disk I/O.
+     */
     updateLastUsed(id: string): void;
     /** Wait for any in-flight and pending saves to complete */
     flush(): Promise<void>;
     destroy(): void;
+    /**
+     * Generates a one-time authorization code that can be exchanged for a JWT.
+     *
+     * Used for the CLI login flow: the server emits a code that the user copies into
+     * the App, which exchanges it for a proper JWT without ever exposing the raw API secret.
+     */
     createCode(opts: CreateCodeOpts): StoredCode;
     getCode(code: string): StoredCode | undefined;
+    /**
+     * Atomically marks a code as used and returns it.
+     *
+     * Returns undefined if the code is unknown, already used, or expired.
+     * The one-time-use flag is set before returning, so concurrent calls for the
+     * same code will only succeed once.
+     */
     exchangeCode(code: string): StoredCode | undefined;
     listCodes(): StoredCode[];
     revokeCode(code: string): void;
+    /**
+     * Removes tokens past their refresh deadline and expired/used codes.
+     *
+     * Called on a 1-hour interval from the plugin setup to prevent unbounded file growth.
+     * Tokens within their refresh deadline are retained even if revoked, so that the
+     * "token revoked" error can be returned instead of "token unknown".
+     */
     cleanup(): void;
 }
 
 interface ApiServerOptions {
     port: number;
     host: string;
+    /** Returns the raw API secret used for full-admin Bearer auth. Fetched lazily so rotation is safe. */
     getSecret: () => string;
+    /** Returns the HMAC secret used to sign and verify JWTs. */
     getJwtSecret: () => string;
     tokenStore: TokenStore;
     logger?: boolean;
 }
+/**
+ * The handle returned by `createApiServer`.
+ *
+ * Route plugins are registered before `start()` is called; Fastify's plugin
+ * encapsulation keeps each prefix isolated with its own auth hooks.
+ */
 interface ApiServerInstance {
     app: FastifyInstance;
+    /** Binds to the configured host/port, auto-incrementing if EADDRINUSE. */
     start(): Promise<{
         port: number;
         host: string;
     }>;
     stop(): Promise<void>;
+    /**
+     * Registers a Fastify plugin scoped to `prefix`.
+     *
+     * Auth is applied by default. Pass `{ auth: false }` only for public endpoints
+     * (e.g. `/api/v1/system` health, `/api/v1/auth/exchange`).
+     */
     registerPlugin(prefix: string, plugin: FastifyPluginAsync, opts?: {
         auth?: boolean;
     }): void;
 }
+/**
+ * Creates and configures the Fastify HTTP server.
+ *
+ * Sets up in order: Zod validation, CORS, rate limiting, Swagger docs,
+ * backward-compat redirects (`/api/*` → `/api/v1/*`), and the global error handler.
+ * Route plugins are registered after this returns via `ApiServerInstance.registerPlugin`.
+ */
 declare function createApiServer(options: ApiServerOptions): Promise<ApiServerInstance>;
 
+/**
+ * The `api-server` service interface exposed to other plugins via ServiceRegistry.
+ *
+ * Other plugins (e.g. SSE adapter, tunnel plugin) use this to register their own
+ * Fastify route plugins under the shared HTTP server without needing a direct
+ * reference to the Fastify instance.
+ */
 interface ApiServerService {
+    /** Register a Fastify plugin at the given prefix, with optional auth bypass. */
     registerPlugin(prefix: string, plugin: FastifyPluginAsync, opts?: {
         auth?: boolean;
     }): void;
+    /** Pre-handler that validates Bearer/JWT auth — attach to routes that need custom auth. */
     authPreHandler: preHandlerHookHandler;
+    /** Creates a pre-handler that requires all listed scopes. */
     requireScopes(...scopes: string[]): preHandlerHookHandler;
+    /** Creates a pre-handler that requires a minimum role level. */
     requireRole(role: string): preHandlerHookHandler;
     getPort(): number;
     getBaseUrl(): string;
+    /** Returns the public tunnel URL, or null if no tunnel is active. */
     getTunnelUrl(): string | null;
 }
+/**
+ * Wraps an `ApiServerInstance` as a service object registered in the ServiceRegistry.
+ *
+ * The getPort/getBaseUrl/getTunnelUrl callbacks are evaluated lazily so callers always
+ * get the current values (port is only known after the server starts listening).
+ */
 declare function createApiServerService(server: ApiServerInstance, getPort: () => number, getBaseUrl: () => string, getTunnelUrl: () => string | null, authPreHandler: preHandlerHookHandler): ApiServerService;
 
 interface SessionStats {
     active: number;
     total: number;
 }
+/**
+ * Manages Server-Sent Events (SSE) connections and broadcasts OpenACP bus events to clients.
+ *
+ * SSE is used instead of WebSockets because:
+ * - It works natively through HTTP/1.1 proxies (Cloudflare, nginx) without upgrade negotiation.
+ * - The communication is unidirectional (server → client); clients send commands via REST.
+ * - It requires no additional dependencies and is built into all modern browsers.
+ *
+ * Clients can subscribe to a specific session by passing `?sessionId=` to filter the stream.
+ * Health heartbeats are sent every 15 seconds to keep the connection alive through idle-timeout
+ * proxies and to deliver periodic memory/session stats to the dashboard.
+ */
 declare class SSEManager {
     private eventBus;
     private getSessionStats;
@@ -2304,24 +3759,74 @@ declare class SSEManager {
     private healthInterval?;
     private boundHandlers;
     constructor(eventBus: EventBus | undefined, getSessionStats: () => SessionStats, startedAt: number);
+    /**
+     * Subscribes to EventBus events and starts the health heartbeat interval.
+     *
+     * Must be called after the HTTP server is listening, not during plugin setup —
+     * before `setup()` runs, no EventBus listeners are registered, so any events
+     * emitted in the interim are silently missed.
+     */
     setup(): void;
+    /**
+     * Handles an incoming SSE request by upgrading the HTTP response to an event stream.
+     *
+     * The response is kept open indefinitely; cleanup runs when the client disconnects.
+     * An initial `: connected` comment is written immediately so proxies and browsers
+     * flush the response headers before the first real event arrives.
+     */
     handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void;
+    /**
+     * Broadcasts an event to all connected SSE clients.
+     *
+     * Session-scoped events (agent_event, permission_request, etc.) are filtered per-connection:
+     * a client that subscribed with `?sessionId=X` only receives events for session X.
+     * Global events (session_created, health) are delivered to every client.
+     */
     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>;
+    /**
+     * Stops the heartbeat, removes all EventBus listeners, and closes all open SSE connections.
+     *
+     * Only listeners registered by this instance are removed — other consumers on the same
+     * EventBus are unaffected.
+     */
     stop(): void;
 }
 
+/**
+ * Serves the bundled OpenACP App (a Vite SPA) from the local filesystem.
+ *
+ * Two directory layouts are probed at startup to support both the development
+ * build (`ui/dist/`) and the npm publish layout (`../ui/`). If neither exists,
+ * `isAvailable()` returns false and the server skips static file serving.
+ *
+ * Path traversal is blocked in two stages:
+ * 1. String prefix check before resolving symlinks (catches obvious `..` segments).
+ * 2. `realpathSync` check after resolution (catches symlinks that escape the UI dir).
+ *
+ * Vite content-hashed assets (`*.{hash}.js/css`) receive a 1-year immutable cache.
+ * All other files use `no-cache` so updates roll out on the next page refresh.
+ *
+ * Non-asset routes fall through to `index.html` (SPA client-side routing).
+ */
 declare class StaticServer {
     private uiDir;
     constructor(uiDir?: string);
+    /** Returns true if a UI build was found and static serving is active. */
     isAvailable(): boolean;
+    /**
+     * Attempts to serve a static file or SPA fallback for the given request.
+     *
+     * @returns true if the response was handled, false if the caller should return a 404.
+     */
     serve(req: http.IncomingMessage, res: http.ServerResponse): boolean;
 }
 
+/** Flat view of a session record, enriched with its Telegram topic ID. */
 interface TopicInfo {
     sessionId: string;
     topicId: number | null;
@@ -2330,8 +3835,10 @@ interface TopicInfo {
     agentName: string;
     lastActiveAt: string;
 }
+/** Result of a single-topic deletion operation. */
 interface DeleteTopicResult {
     ok: boolean;
+    /** True when deletion requires explicit confirmation (session is still active). */
     needsConfirmation?: boolean;
     topicId?: number | null;
     session?: {
@@ -2341,6 +3848,7 @@ interface DeleteTopicResult {
     };
     error?: string;
 }
+/** Aggregate result for a bulk cleanup operation. */
 interface CleanupResult {
     deleted: string[];
     failed: {
@@ -2352,21 +3860,54 @@ interface SystemTopicIds {
     notificationTopicId: number | null;
     assistantTopicId: number | null;
 }
+/**
+ * High-level topic management for the Telegram adapter.
+ *
+ * Sits above the raw Telegram API (`topics.ts`) and adds session-level concerns:
+ * guarding system topics, requiring confirmation for active sessions, and
+ * coordinating with the SessionManager to remove session records after deletion.
+ */
 declare class TopicManager {
     private sessionManager;
     private adapter;
     private systemTopicIds;
     constructor(sessionManager: SessionManager, adapter: IChannelAdapter | null, systemTopicIds: SystemTopicIds);
+    /**
+     * List user-facing session topics, excluding system topics.
+     * Optionally filtered to specific status values.
+     */
     listTopics(filter?: {
         statuses?: string[];
     }): TopicInfo[];
+    /**
+     * Delete a session topic and its session record.
+     *
+     * Returns `needsConfirmation: true` when the session is still active and
+     * `options.confirmed` was not set — callers must ask the user before proceeding.
+     */
     deleteTopic(sessionId: string, options?: {
         confirmed?: boolean;
     }): Promise<DeleteTopicResult>;
+    /**
+     * Bulk-delete topics by status (default: finished, error, cancelled).
+     * Active/initializing sessions are cancelled before deletion to prevent orphaned processes.
+     */
     cleanup(statuses?: string[]): Promise<CleanupResult>;
     private isSystemTopic;
 }
 
+/**
+ * Context provider backed by Claude Code checkpoint data stored in the git repo.
+ *
+ * Only available when the repo has an `origin/entire/checkpoints/v1` branch,
+ * which is pushed by the Entire Claude Code extension. Supports all query types
+ * (branch, commit, PR, session, latest) by reading checkpoint metadata and
+ * reconstructing conversation turns from JSONL transcripts.
+ *
+ * Used as a lower-priority fallback after HistoryProvider: the live history
+ * recorder takes precedence for sessions still in memory, while this provider
+ * covers older sessions or cross-branch queries.
+ */
 declare class EntireProvider implements ContextProvider {
     readonly name = "entire";
     isAvailable(repoPath: string): Promise<boolean>;
@@ -2377,26 +3918,43 @@ declare class EntireProvider implements ContextProvider {
     private buildTitle;
 }
 
+/**
+ * A rendered message ready for platform delivery.
+ * The `format` field tells the adapter how to interpret the body
+ * (e.g., pass as HTML to Telegram, or as plain text to SSE).
+ */
 interface RenderedMessage<TComponents = unknown> {
     body: string;
     format: "html" | "markdown" | "plain" | "structured";
     attachments?: RenderedAttachment[];
+    /** Platform-specific UI components (e.g., Telegram inline keyboards). */
     components?: TComponents;
 }
+/** A rendered permission request with approve/deny action buttons. */
 interface RenderedPermission<TComponents = unknown> extends RenderedMessage<TComponents> {
     actions: RenderedAction[];
 }
+/** A single action button for permission requests. */
 interface RenderedAction {
     id: string;
     label: string;
     isAllow?: boolean;
 }
+/** A file, image, or audio attachment to include with a rendered message. */
 interface RenderedAttachment {
     type: "file" | "image" | "audio";
     data: Buffer | string;
     mimeType?: string;
     filename?: string;
 }
+/**
+ * Rendering contract for platform-specific message formatting.
+ *
+ * Each adapter provides its own IRenderer implementation (e.g., TelegramRenderer
+ * outputs HTML, a CLI renderer might output ANSI). Required methods handle the
+ * core message types; optional methods handle less common types and fall back
+ * to no-ops if not implemented.
+ */
 interface IRenderer {
     renderText(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
     renderToolCall(content: OutgoingMessage, verbosity: DisplayVerbosity): RenderedMessage;
@@ -2417,7 +3975,11 @@ interface IRenderer {
     renderResourceLink?(content: OutgoingMessage): RenderedMessage;
 }
 /**
- * BaseRenderer — plain text defaults. Extend for platform-specific rendering.
+ * Default renderer producing plain-text output for all message types.
+ *
+ * Platform-specific renderers (e.g., TelegramRenderer) extend this class
+ * and override methods to produce HTML, markdown, or structured output.
+ * Methods not overridden fall back to these plain-text defaults.
  */
 declare class BaseRenderer implements IRenderer {
     renderText(content: OutgoingMessage): RenderedMessage;
@@ -2436,28 +3998,60 @@ declare class BaseRenderer implements IRenderer {
     renderResourceLink(content: OutgoingMessage): RenderedMessage;
 }
 
+/** Runtime services available to adapters via dependency injection. */
 interface AdapterContext {
     configManager: {
         get(): Record<string, unknown>;
     };
     fileService?: unknown;
 }
+/** Configuration for adapters that extend MessagingAdapter. */
 interface MessagingAdapterConfig extends ChannelConfig {
+    /** Platform-imposed limit on a single message body (e.g., 4096 for Telegram). */
     maxMessageLength: number;
+    /** How often (ms) to flush buffered streaming text to the platform. */
     flushInterval?: number;
+    /** Minimum interval (ms) between consecutive send-queue operations. */
     sendInterval?: number;
+    /** How often (ms) to refresh the typing indicator during agent thinking. */
     thinkingRefreshInterval?: number;
+    /** Max duration (ms) to show the typing indicator before auto-dismissing. */
     thinkingDuration?: number;
+    /** Default output verbosity for this adapter (can be overridden per-session). */
     displayVerbosity?: DisplayVerbosity;
 }
+/**
+ * Abstract base class for platform-specific messaging adapters (Telegram, Slack, etc.).
+ *
+ * Provides a dispatch pipeline: incoming OutgoingMessage -> verbosity filter -> type-based
+ * handler. Subclasses override the `handle*` methods to implement platform-specific rendering
+ * and delivery. The base implementations are no-ops, so subclasses only override what they need.
+ */
 declare abstract class MessagingAdapter implements IChannelAdapter {
     protected context: AdapterContext;
     protected adapterConfig: MessagingAdapterConfig;
     abstract readonly name: string;
+    /** Platform-specific renderer that converts OutgoingMessage to formatted output. */
     abstract readonly renderer: IRenderer;
+    /**
+     * Declares what this adapter can do. The platform-specific subclass sets these flags,
+     * and core/stream-adapter use them to decide how to route and format output — e.g.,
+     * whether to stream text in-place (streaming), send to threads/topics (threads),
+     * render markdown (richFormatting), upload files (fileUpload), or play audio (voice).
+     */
     abstract readonly capabilities: AdapterCapabilities;
     constructor(context: AdapterContext, adapterConfig: MessagingAdapterConfig);
+    /**
+     * Entry point for all outbound messages from sessions to the platform.
+     * Resolves the current verbosity, filters messages that should be hidden,
+     * then dispatches to the appropriate type-specific handler.
+     */
     sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>;
+    /**
+     * Routes a message to its type-specific handler.
+     * Subclasses can override this for custom dispatch logic, but typically
+     * override individual handle* methods instead.
+     */
     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>;
@@ -2475,49 +4069,106 @@ declare abstract class MessagingAdapter implements IChannelAdapter {
     protected handleUserReplay(_sessionId: string, _content: OutgoingMessage): Promise<void>;
     protected handleResource(_sessionId: string, _content: OutgoingMessage): Promise<void>;
     protected handleResourceLink(_sessionId: string, _content: OutgoingMessage): Promise<void>;
+    /**
+     * Resolves the current output verbosity by checking (in priority order):
+     * per-channel config, global config, then adapter default. Falls back to "medium".
+     */
     protected getVerbosity(): DisplayVerbosity;
+    /**
+     * Determines whether a message should be displayed at the given verbosity.
+     *
+     * Noise filtering: tool calls matching noise rules (e.g., `ls`, `glob`, `grep`)
+     * are hidden at medium/low verbosity to reduce clutter. Thoughts and usage
+     * stats are hidden entirely at "low".
+     */
     protected shouldDisplay(content: OutgoingMessage, verbosity: DisplayVerbosity): boolean;
+    /** Initializes the adapter (e.g., connect to platform API, start polling). */
     abstract start(): Promise<void>;
+    /** Gracefully shuts down the adapter and releases resources. */
     abstract stop(): Promise<void>;
+    /** Creates a platform-specific thread/topic for a session. Returns the thread ID. */
     abstract createSessionThread(sessionId: string, name: string): Promise<string>;
+    /** Renames an existing session thread/topic on the platform. */
     abstract renameSessionThread(sessionId: string, newName: string): Promise<void>;
+    /** Sends a permission request to the user with approve/deny actions. */
     abstract sendPermissionRequest(sessionId: string, request: PermissionRequest): Promise<void>;
+    /** Sends a cross-session notification (e.g., session completed, budget warning). */
     abstract sendNotification(notification: NotificationMessage): Promise<void>;
 }
 
+/** A structured event emitted over the stream (SSE, WebSocket, etc.). */
 interface StreamEvent {
     type: string;
     sessionId?: string;
     payload: unknown;
     timestamp: number;
 }
+/**
+ * Base class for stream-based adapters (SSE, WebSocket) that push events
+ * directly to connected clients rather than rendering messages on a platform.
+ *
+ * Unlike MessagingAdapter (which renders and sends formatted messages),
+ * StreamAdapter wraps each outgoing message as a StreamEvent and emits it
+ * to all connections watching that session. The client is responsible for
+ * rendering.
+ */
 declare abstract class StreamAdapter implements IChannelAdapter {
     abstract readonly name: string;
     capabilities: AdapterCapabilities;
     constructor(config?: Partial<AdapterCapabilities>);
+    /** Wraps the outgoing message as a StreamEvent and emits it to the session's listeners. */
     sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>;
+    /** Emits a permission request event so the client can render approve/deny UI. */
     sendPermissionRequest(sessionId: string, request: PermissionRequest): Promise<void>;
+    /** Broadcasts a notification to all connected clients (not scoped to a session). */
     sendNotification(notification: NotificationMessage): Promise<void>;
+    /**
+     * No-op for stream adapters — threads are a platform concept (Telegram topics, Slack threads).
+     * Stream clients manage their own session UI.
+     */
     createSessionThread(_sessionId: string, _name: string): Promise<string>;
+    /** Emits a rename event so connected clients can update their session title. */
     renameSessionThread(sessionId: string, name: string): Promise<void>;
+    /** Sends an event to all connections watching a specific session. */
     protected abstract emit(sessionId: string, event: StreamEvent): Promise<void>;
+    /** Sends an event to all connected clients regardless of session. */
     protected abstract broadcast(event: StreamEvent): Promise<void>;
     abstract start(): Promise<void>;
     abstract stop(): Promise<void>;
 }
 
+/**
+ * Item type determines deduplication behavior:
+ * - `"text"` items with the same key replace each other (only latest is sent)
+ * - `"other"` items are always queued individually
+ */
 type QueueItemType = 'text' | 'other';
+/** Configuration for the SendQueue rate limiter. */
 interface SendQueueConfig {
+    /** Minimum interval (ms) between consecutive operations. */
     minInterval: number;
+    /** Per-category interval overrides (e.g., separate limits for edits vs. sends). */
     categoryIntervals?: Record<string, number>;
     onRateLimited?: () => void;
     onError?: (error: Error) => void;
 }
+/** Options for enqueuing an operation. */
 interface EnqueueOptions {
     type?: QueueItemType;
+    /** Deduplication key — text items with the same key replace earlier ones. */
     key?: string;
+    /** Category for per-category rate limiting. */
     category?: string;
 }
+/**
+ * Serializes outbound platform API calls to respect rate limits and maintain ordering.
+ *
+ * Key behaviors:
+ * - Enforces a minimum interval between consecutive operations
+ * - Supports per-category intervals (e.g., different limits for message edits vs. sends)
+ * - Deduplicates text-type items with the same key (only the latest update is sent)
+ * - On rate limit, drops all pending text items to reduce backlog
+ */
 declare class SendQueue {
     private config;
     private items;
@@ -2526,87 +4177,166 @@ declare class SendQueue {
     private lastCategoryExec;
     constructor(config: SendQueueConfig);
     get pending(): number;
+    /**
+     * Queues an async operation for rate-limited execution.
+     *
+     * For text-type items with a key, replaces any existing queued item with
+     * the same key (deduplication). This is used for streaming draft updates
+     * where only the latest content matters.
+     */
     enqueue<T>(fn: () => Promise<T>, opts?: EnqueueOptions): Promise<T | undefined>;
+    /**
+     * Called when a platform rate limit is hit. Drops all pending text items
+     * (draft updates) to reduce backlog, keeping only non-text items that
+     * represent important operations (e.g., permission requests).
+     */
     onRateLimited(): void;
     clear(): void;
+    /**
+     * Schedules the next item for processing after the rate-limit delay.
+     * Uses per-category timing when available, falling back to the global minInterval.
+     */
     private scheduleProcess;
     private getInterval;
     private processNext;
 }
 
+/** Configuration for draft message flushing behavior. */
 interface DraftConfig {
+    /** How often (ms) to flush buffered text to the platform. */
     flushInterval: number;
     maxLength: number;
+    /**
+     * Called to send or update a message on the platform.
+     * Returns the platform message ID on first send (isEdit=false);
+     * subsequent calls are edits (isEdit=true).
+     */
     onFlush: (sessionId: string, text: string, isEdit: boolean) => Promise<string | undefined>;
     onError?: (sessionId: string, error: Error) => void;
 }
+/**
+ * Manages a single in-progress (draft) message for streaming text output.
+ *
+ * As text chunks arrive from the agent, they are appended to an internal buffer.
+ * The buffer is flushed to the platform on a timer. The first flush creates the
+ * message; subsequent flushes edit it in place. This avoids sending many small
+ * messages and instead shows a live-updating message.
+ */
 declare class Draft {
     private sessionId;
     private config;
     private buffer;
     private _messageId?;
+    /** Guards against concurrent first-flush — ensures only one sendMessage creates the draft. */
     private firstFlushPending;
     private flushTimer?;
     private flushPromise;
     constructor(sessionId: string, config: DraftConfig);
     get isEmpty(): boolean;
+    /** Platform message ID, set after the first successful flush. */
     get messageId(): string | undefined;
+    /** Appends streaming text to the buffer and schedules a flush. */
     append(text: string): void;
+    /**
+     * Flushes any remaining buffered text and returns the platform message ID.
+     * Called when the streaming response completes.
+     */
     finalize(): Promise<string | undefined>;
+    /** Discards buffered text and cancels any pending flush. */
     destroy(): void;
     private scheduleFlush;
     private flush;
 }
+/**
+ * Manages draft messages across multiple sessions.
+ *
+ * Each session gets at most one active draft. When a session's streaming
+ * response completes, the draft is finalized (final flush + cleanup).
+ */
 declare class DraftManager {
     private config;
     private drafts;
     constructor(config: DraftConfig);
+    /** Returns the existing draft for a session, or creates a new one. */
     getOrCreate(sessionId: string): Draft;
+    /** Finalizes and removes the draft for a session. */
     finalize(sessionId: string): Promise<void>;
+    /** Finalizes all active drafts (e.g., during adapter shutdown). */
     finalizeAll(): Promise<void>;
+    /** Destroys a draft without flushing (e.g., on session error). */
     destroy(sessionId: string): void;
+    /** Destroys all drafts without flushing. */
     destroyAll(): void;
 }
 
+/** A tool call associated with the platform message ID where it is displayed. */
 interface TrackedToolCall extends ToolCallMeta {
+    /** Platform message ID of the tool card message, used for in-place updates. */
     messageId: string;
 }
+/**
+ * Tracks active tool calls per session, associating each with the platform
+ * message that displays it. Used by adapters that render individual tool
+ * cards and need to update them in-place when tool status changes.
+ */
 declare class ToolCallTracker {
     private sessions;
+    /** Registers a new tool call and associates it with its platform message ID. */
     track(sessionId: string, meta: ToolCallMeta, messageId: string): void;
+    /** Updates a tracked tool call's status and optional metadata. Returns null if not found. */
     update(sessionId: string, toolId: string, status: string, patch?: Partial<Pick<ToolCallMeta, 'viewerLinks' | 'viewerFilePath' | 'name' | 'kind'>>): TrackedToolCall | null;
+    /** Returns all tracked tool calls for a session (regardless of status). */
     getActive(sessionId: string): TrackedToolCall[];
+    /** Removes all tracked tool calls for a session (called at turn end). */
     clear(sessionId: string): void;
     clearAll(): void;
 }
 
+/** Timing configuration for the thinking indicator lifecycle. */
 interface ActivityConfig {
+    /** How often (ms) to refresh the typing indicator (e.g., re-send "typing..." action). */
     thinkingRefreshInterval: number;
+    /** Maximum duration (ms) before auto-dismissing the indicator to avoid stale UI. */
     maxThinkingDuration: number;
 }
+/** Platform-specific callbacks for showing/updating/removing typing indicators. */
 interface ActivityCallbacks {
     sendThinkingIndicator(): Promise<void>;
     updateThinkingIndicator(): Promise<void>;
     removeThinkingIndicator(): Promise<void>;
 }
+/**
+ * Manages typing/thinking indicators across sessions.
+ *
+ * When the agent starts processing, a typing indicator is shown. It is
+ * periodically refreshed (platforms like Telegram expire typing status after
+ * ~5 seconds) and auto-dismissed either when text output begins or when
+ * the max thinking duration is reached.
+ */
 declare class ActivityTracker {
     private config;
     private sessions;
     constructor(config: ActivityConfig);
+    /** Shows the typing indicator and starts the periodic refresh timer. */
     onThinkingStart(sessionId: string, callbacks: ActivityCallbacks): void;
+    /** Dismisses the typing indicator when the agent starts producing text output. */
     onTextStart(sessionId: string): void;
+    /** Cleans up the typing indicator when the session ends. */
     onSessionEnd(sessionId: string): void;
+    /** Cleans up all sessions (e.g., during adapter shutdown). */
     destroy(): void;
     private cleanup;
     private startRefresh;
     private stopRefresh;
 }
 
+/** Accumulated state for a single tool call during a streaming response. */
 interface ToolEntry {
     id: string;
     name: string;
     kind: string;
     rawInput: unknown;
+    /** Tool output content, populated when the tool completes. */
     content: string | null;
     status: string;
     viewerLinks?: ViewerLinks;
@@ -2617,8 +4347,16 @@ interface ToolEntry {
     displaySummary?: string;
     displayTitle?: string;
     displayKind?: string;
+    /** Whether this tool is considered noise (e.g., ls, glob) and should be hidden at lower verbosities. */
     isNoise: boolean;
 }
+/**
+ * Tracks all tool calls within a single streaming turn.
+ *
+ * Tool call events and update events can arrive out of order (e.g., a
+ * `tool_update` may arrive before the corresponding `tool_call`). This map
+ * handles that by buffering updates until the initial call arrives.
+ */
 declare class ToolStateMap {
     private entries;
     private pendingUpdates;
@@ -2636,19 +4374,37 @@ declare class ToolStateMap {
         removed: number;
     }): ToolEntry | undefined;
     private _applyUpdate;
+    /** Retrieves a tool entry by ID, or undefined if not yet tracked. */
     get(id: string): ToolEntry | undefined;
+    /** Resets all state between turns. */
     clear(): void;
 }
+/**
+ * Buffers partial thought text chunks from the agent's extended thinking.
+ *
+ * Chunks are appended until `seal()` is called, which marks the thought
+ * as complete and returns the full text. Once sealed, further appends
+ * are ignored.
+ */
 declare class ThoughtBuffer {
     private chunks;
     private sealed;
+    /** Appends a thought text chunk. Ignored if already sealed. */
     append(chunk: string): void;
+    /** Marks the thought as complete and returns the full accumulated text. */
     seal(): string;
+    /** Returns the text accumulated so far without sealing. */
     getText(): string;
     isSealed(): boolean;
+    /** Resets the buffer for reuse in a new turn. */
     reset(): void;
 }
 
+/**
+ * A fully resolved, platform-agnostic description of how to display a tool call.
+ * Built by DisplaySpecBuilder from a ToolEntry + output mode, then consumed
+ * by adapters to render tool cards.
+ */
 interface ToolDisplaySpec {
     id: string;
     kind: string;
@@ -2673,36 +4429,68 @@ interface ToolDisplaySpec {
     isNoise: boolean;
     isHidden: boolean;
 }
+/** Display specification for an agent's extended thinking block. */
 interface ThoughtDisplaySpec {
     indicator: string;
+    /** Full thought text, only populated at high verbosity. */
     content: string | null;
 }
+/**
+ * Transforms raw ToolEntry state into display-ready ToolDisplaySpec objects.
+ *
+ * This is the central place where output mode (low/medium/high) controls what
+ * information is included in tool cards. Low mode strips metadata; medium mode
+ * includes summaries; high mode includes full output content and viewer links.
+ */
 declare class DisplaySpecBuilder {
     private tunnelService?;
     constructor(tunnelService?: TunnelServiceInterface | undefined);
+    /**
+     * Builds a display spec for a single tool call entry.
+     *
+     * Deduplicates fields to avoid repeating the same info (e.g., if the title
+     * was derived from the command, the command field is omitted). For long
+     * output, generates a viewer link via the tunnel service when available.
+     */
     buildToolSpec(entry: ToolEntry, mode: OutputMode, sessionContext?: {
         id: string;
         workingDirectory: string;
     }): ToolDisplaySpec;
+    /** Builds a display spec for an agent thought. Content is only included at high verbosity. */
     buildThoughtSpec(content: string, mode: OutputMode): ThoughtDisplaySpec;
 }
 
+/** Token usage and cost data appended to the tool card after the turn completes. */
 interface UsageData {
     tokensUsed?: number;
     contextSize?: number;
     cost?: number;
 }
+/**
+ * A point-in-time snapshot of all tool cards in a turn, used for rendering.
+ * Includes completion counts so adapters can show progress (e.g., "3/5 tools done").
+ */
 interface ToolCardSnapshot {
     specs: ToolDisplaySpec[];
     planEntries?: PlanEntry[];
     usage?: UsageData;
     totalVisible: number;
     completedVisible: number;
+    /** True when all visible tools have reached a terminal status. */
     allComplete: boolean;
 }
 interface ToolCardStateConfig {
+    /** Called with a snapshot whenever the tool card content changes. */
     onFlush: (snapshot: ToolCardSnapshot) => void;
 }
+/**
+ * Aggregates tool display specs, plan entries, and usage data for a single
+ * turn, then flushes snapshots to the adapter for rendering.
+ *
+ * Uses debouncing to batch rapid updates (e.g., multiple tools starting
+ * in quick succession) into a single render pass. The first update flushes
+ * immediately for responsiveness; subsequent updates are debounced.
+ */
 declare class ToolCardState {
     private specs;
     private planEntries?;
@@ -2712,10 +4500,15 @@ declare class ToolCardState {
     private debounceTimer?;
     private onFlush;
     constructor(config: ToolCardStateConfig);
+    /** Adds or updates a tool spec. First call flushes immediately; subsequent calls are debounced. */
     updateFromSpec(spec: ToolDisplaySpec): void;
+    /** Updates the plan entries displayed alongside tool cards. */
     updatePlan(entries: PlanEntry[]): void;
+    /** Appends token usage data to the tool card (typically at end of turn). */
     appendUsage(usage: UsageData): void;
+    /** Marks the turn as complete and flushes the final snapshot immediately. */
     finalize(): void;
+    /** Stops all pending flushes without emitting a final snapshot. */
     destroy(): void;
     hasContent(): boolean;
     private snapshot;
@@ -2724,15 +4517,54 @@ declare class ToolCardState {
     private clearDebounce;
 }
 
+/** Renders a text-based progress bar (e.g., "▓▓▓▓░░░░░░") for token usage display. */
 declare function progressBar(ratio: number, length?: number): string;
+/** Formats a token count with SI suffixes (e.g., 1500 -> "1.5k", 2000000 -> "2M"). */
 declare function formatTokens(n: number): string;
+/** Strips markdown code fences (```lang ... ```) from text, leaving only the content. */
 declare function stripCodeFences(text: string): string;
+/** Truncates text to maxLen characters, appending a truncation marker if cut. */
 declare function truncateContent(text: string, maxLen: number): string;
+/**
+ * Splits a long message into chunks that fit within maxLength.
+ *
+ * Splitting strategy:
+ * 1. Prefer paragraph boundaries (\n\n), then line boundaries (\n)
+ * 2. If remaining text is only slightly over the limit (< 1.3x), split
+ *    near the midpoint to avoid leaving a tiny trailing chunk
+ * 3. Avoid splitting inside markdown code fences — extend past the closing
+ *    fence if it doesn't exceed 2x maxLength
+ */
 declare function splitMessage(text: string, maxLength: number): string[];
 
+/**
+ * Recursively extracts plain text from an agent's response content.
+ *
+ * Agent responses can be strings, arrays of content blocks, or nested
+ * objects with `text`, `content`, `input`, or `output` fields. This
+ * function normalizes all variants into a single string. Falls back
+ * to JSON serialization for unrecognized structures to avoid silently
+ * dropping edge-case responses.
+ */
 declare function extractContentText(content: unknown, depth?: number): string;
+/**
+ * Builds a human-readable summary line for a tool call (used at medium/high verbosity).
+ *
+ * Includes an icon and key arguments (e.g., "Read src/foo.ts (50 lines)").
+ * If the agent provides a `displaySummary` override, it takes precedence.
+ */
 declare function formatToolSummary(name: string, rawInput: unknown, displaySummary?: string): string;
+/**
+ * Builds a compact title for a tool call (used at low verbosity).
+ *
+ * Returns just the key identifier (file path, command, pattern) without
+ * icons or extra decoration. If `displayTitle` is provided, it takes precedence.
+ */
 declare function formatToolTitle(name: string, rawInput: unknown, displayTitle?: string): string;
+/**
+ * Selects the appropriate emoji icon for a tool call card.
+ * Priority: status icon (e.g., running, done, error) > kind icon (e.g., read, execute) > default.
+ */
 declare function resolveToolIcon(tool: {
     status?: string;
     displayKind?: string;
@@ -2747,23 +4579,71 @@ interface SessionManagerLike {
         outputMode?: OutputMode;
     } | undefined;
 }
+/**
+ * Resolves the effective output mode (low/medium/high) for a session.
+ *
+ * Override cascade (most specific wins):
+ * 1. Global config `outputMode` (default: "medium")
+ * 2. Per-adapter config `channels.<adapterName>.outputMode`
+ * 3. Per-session override stored on the session record
+ */
 declare class OutputModeResolver {
+    /** Resolves the effective output mode by walking the override cascade. */
     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.
+ * OpenACP Product Guide — comprehensive reference text injected into the AI assistant's system prompt.
+ *
+ * The assistant (in the Assistant topic/thread) reads this at startup to answer user questions
+ * about features, CLI commands, configuration, and troubleshooting without hitting the network.
+ *
+ * **How it's used:** The assistant plugin reads `PRODUCT_GUIDE` and prepends it to the system
+ * prompt so the AI has full product knowledge baked in, not fetched per-session.
+ *
+ * **How to update:** Edit the Markdown content below. Keep it accurate with the current feature set —
+ * outdated entries cause the assistant to give wrong answers. Sections use `---` dividers and
+ * `##` headings so the assistant can navigate the content efficiently.
  */
-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### Bypass permissions\nAuto-approves ALL permission requests \u2014 the agent runs any command without asking.\n- Toggle: `/bypass_permissions on` or tap the \u2620\uFE0F button in the session\n- Disable: `/bypass_permissions off` 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 <agent>` to install handoff integration (one-time setup)\n2. In supported agents (for example Claude Code or OpenCode), use /openacp:handoff\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| `/bypass_permissions` | Session topic | Toggle bypass permissions (on/off) |\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| `bypass <id> on/off` | Toggle bypass permissions |\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 `/bypass_permissions on` 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";
+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### Bypass permissions\nAuto-approves ALL permission requests \u2014 the agent runs any command without asking.\n- Toggle: `/bypass_permissions on` or tap the \u2620\uFE0F button in the session\n- Disable: `/bypass_permissions off` 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 <agent>` to install handoff integration (one-time setup)\n2. In supported agents (for example Claude Code or OpenCode), use /openacp:handoff\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| `/bypass_permissions` | Session topic | Toggle bypass permissions (on/off) |\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| `bypass <id> on/off` | Toggle bypass permissions |\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 directory is the parent of `.openacp/` (where you ran `openacp` setup)\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 `/bypass_permissions on` 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";
 
+/**
+ * Runtime configuration for the Telegram adapter.
+ *
+ * `notificationTopicId` and `assistantTopicId` start as `null` on first run and are
+ * populated by `ensureTopics()` when the system topics are created in the group.
+ * Both IDs are persisted to plugin settings so they survive restarts.
+ */
 interface TelegramChannelConfig extends ChannelConfig {
     botToken: string;
     chatId: number;
+    /** Forum topic used for all cross-session notifications (completions, permissions). Null until first run. */
     notificationTopicId: number | null;
+    /** Forum topic where users chat with the assistant. Null until first run. */
     assistantTopicId: number | null;
 }
 
+/**
+ * Telegram adapter — bridges the OpenACP session system to a Telegram supergroup.
+ *
+ * Architecture overview:
+ * - **Topic-per-session model**: each agent session lives in its own Telegram forum
+ *   topic. The topic ID is stored as `session.threadId` and used to route all
+ *   inbound and outbound messages.
+ * - **Two system topics**: "📋 Notifications" (cross-session alerts) and
+ *   "🤖 Assistant" (conversational AI). Created once on first run, IDs persisted.
+ * - **Streaming**: agent text arrives as `text_delta` chunks. A `MessageDraft`
+ *   accumulates chunks and edits the message in-place every 5 seconds, reducing
+ *   API calls while keeping the response live.
+ * - **Callback routing**:
+ *   - `p:<key>:<optionId>` — permission approval buttons
+ *   - `c/<command>` (or `c/#<id>` for long commands) — command button actions
+ *   - `m:<itemId>` — MenuRegistry item dispatch
+ *   - Domain prefixes (`d:`, `v:`, `ns:`, `sw:`, etc.) — specific feature flows
+ * - **Two-phase startup**: Phase 1 starts the bot and registers handlers.
+ *   Phase 2 checks group prerequisites (admin, topics enabled) and creates
+ *   system topics. If prerequisites are not met, a background watcher retries.
+ */
 declare class TelegramAdapter extends MessagingAdapter {
     readonly name = "telegram";
     readonly renderer: IRenderer;
@@ -2796,7 +4676,11 @@ declare class TelegramAdapter extends MessagingAdapter {
     private _topicsInitialized;
     /** Background watcher timer — cancelled on stop() or when topics succeed */
     private _prerequisiteWatcher;
-    /** Store control message ID in memory + persist to session record */
+    /**
+     * Persist the control message ID both in-memory and to the session record.
+     * The control message is the pinned status card with bypass/TTS buttons; its ID
+     * is needed after a restart to edit it when config changes.
+     */
     private storeControlMsgId;
     /** Get control message ID (from Map, with fallback to session record) */
     private getControlMsgId;
@@ -2806,6 +4690,12 @@ declare class TelegramAdapter extends MessagingAdapter {
         notificationTopicId?: number;
         assistantTopicId?: number;
     }) => Promise<void>);
+    /**
+     * Set up the grammY bot, register all callback and message handlers, then perform
+     * two-phase startup: Phase 1 starts polling immediately; Phase 2 checks group
+     * prerequisites (bot is admin, topics are enabled) and creates/restores system topics.
+     * If prerequisites are not met, a background watcher retries until they are.
+     */
     start(): Promise<void>;
     /**
      * Retry an async operation with exponential backoff.
@@ -2819,6 +4709,13 @@ declare class TelegramAdapter extends MessagingAdapter {
     private registerCommandsWithRetry;
     private initTopicDependentFeatures;
     private startPrerequisiteWatcher;
+    /**
+     * Tear down the bot and release all associated resources.
+     *
+     * Cancels the background prerequisite watcher, destroys all per-session activity
+     * trackers (which hold interval timers), removes eventBus listeners, clears the
+     * send queue, and stops the grammY bot polling loop.
+     */
     stop(): Promise<void>;
     private renderCommandResponse;
     private toCallbackData;
@@ -2833,7 +4730,19 @@ declare class TelegramAdapter extends MessagingAdapter {
      * its creation event. This queue ensures events are processed in the order they arrive.
      */
     private _dispatchQueues;
+    /**
+     * Drain pending event dispatches from the previous prompt, then reset the
+     * activity tracker so late tool_call events don't leak into the new card.
+     */
+    private drainAndResetTracker;
     private getTracer;
+    /**
+     * Primary outbound dispatch method — routes an agent message to the session's Telegram topic.
+     *
+     * Wraps the base class `sendMessage` in a per-session promise chain (`_dispatchQueues`)
+     * so that concurrent events fired from SessionBridge are serialized and delivered in the
+     * order they arrive, preventing fast handlers from overtaking slower ones.
+     */
     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>;
@@ -2851,20 +4760,71 @@ declare class TelegramAdapter extends MessagingAdapter {
     updateControlMessage(sessionId: string): Promise<void>;
     protected handleError(sessionId: string, content: OutgoingMessage): Promise<void>;
     protected handleSystem(sessionId: string, content: OutgoingMessage): Promise<void>;
+    /**
+     * Render a PermissionRequest as an inline keyboard in the session topic and
+     * notify the Notifications topic. Runs inside a sendQueue item, so
+     * notification is fire-and-forget to avoid deadlock.
+     */
     sendPermissionRequest(sessionId: string, request: PermissionRequest): Promise<void>;
+    /**
+     * Post a notification to the Notifications topic.
+     * Assistant session notifications are suppressed — the assistant topic is
+     * the user's primary interface and does not need a separate alert.
+     */
     sendNotification(notification: NotificationMessage): Promise<void>;
+    /**
+     * Create a new Telegram forum topic for a session and return its thread ID as a string.
+     * Called by the core when a session is created via the API or CLI (not from the Telegram UI).
+     */
     createSessionThread(sessionId: string, name: string): Promise<string>;
+    /**
+     * Rename the forum topic for a session and update the session record's display name.
+     * No-ops silently if the session doesn't have a threadId yet (e.g. still initializing).
+     */
     renameSessionThread(sessionId: string, newName: string): Promise<void>;
+    /** Delete the forum topic associated with a session. */
     deleteSessionThread(sessionId: string): Promise<void>;
+    /**
+     * Display or update the pinned skill commands message for a session.
+     * If the session's threadId is not yet set (e.g. session created from API),
+     * the commands are queued and flushed once the thread becomes available.
+     */
     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;
+    /**
+     * Remove skill slash commands from the Telegram bot command list for a session.
+     *
+     * Clears any queued pending commands that hadn't been sent yet, then delegates
+     * to `SkillCommandManager` to delete the commands from the Telegram API. Called
+     * when a session with registered skill commands ends.
+     */
     cleanupSkillCommands(sessionId: string): Promise<void>;
+    /**
+     * Clean up all adapter state associated with a session.
+     *
+     * Finalizes and discards any in-flight draft, destroys the activity tracker
+     * (stopping ThinkingIndicator timers and finalizing any open ToolCard), and
+     * clears pending skill commands. Called when a session ends or is reset.
+     */
     cleanupSessionState(sessionId: string): Promise<void>;
+    /**
+     * Remove `[TTS]...[/TTS]` blocks from the active or finalized draft for a session.
+     *
+     * The agent embeds these blocks so the speech plugin can extract the TTS text, but
+     * they should never appear in the chat message. Called after TTS audio has been sent.
+     */
     stripTTSBlock(sessionId: string): Promise<void>;
+    /**
+     * Archive a session by deleting its forum topic.
+     *
+     * Sets `session.archiving = true` to suppress any outgoing messages while the
+     * topic is being torn down, finalizes pending drafts, cleans up all trackers,
+     * then deletes the Telegram topic (which removes all messages).
+     */
     archiveSessionTopic(sessionId: string): Promise<void>;
 }