@openacp/cli 2026.410.1 → 2026.410.2

package/dist/index.js

@@ -265,6 +265,8 @@ var init_config_migrations = __esm({
     log2 = createChildLogger({ module: "config-migrations" });
     migrations = [
       {
+        // v2025.x: instanceName was added to support multi-instance setups.
+        // Old configs lack this field — default to "Main" so the UI has a display name.
         name: "add-instance-name",
         apply(raw) {
           if (raw.instanceName) return false;
@@ -274,6 +276,8 @@ var init_config_migrations = __esm({
         }
       },
       {
+        // displayVerbosity was replaced by outputMode — remove the legacy key
+        // so it doesn't confuse Zod strict parsing or the config editor.
         name: "delete-display-verbosity",
         apply(raw) {
           if (!("displayVerbosity" in raw)) return false;
@@ -283,6 +287,9 @@ var init_config_migrations = __esm({
         }
       },
       {
+        // Instance IDs were originally only in instances.json (the global registry).
+        // This migration copies the ID into config.json so each instance is self-identifying
+        // without needing to cross-reference the registry.
         name: "add-instance-id",
         apply(raw, ctx) {
           if (raw.id) return false;
@@ -457,10 +464,11 @@ var init_config = __esm({
       sessionLogRetentionDays: z.number().default(30)
     }).default({});
     ConfigSchema = z.object({
+      /** Instance UUID, written once at creation time. */
       id: z.string().optional(),
-      // instance UUID, written once at creation time
       instanceName: z.string().optional(),
       defaultAgent: z.string(),
+      // --- Workspace security & path resolution ---
       workspace: z.object({
         allowExternalWorkspaces: z.boolean().default(true),
         security: z.object({
@@ -468,12 +476,16 @@ var init_config = __esm({
           envWhitelist: z.array(z.string()).default([])
         }).default({})
       }).default({}),
+      // --- Logging ---
       logging: LoggingSchema,
+      // --- Process lifecycle ---
       runMode: z.enum(["foreground", "daemon"]).default("foreground"),
       autoStart: z.boolean().default(false),
+      // --- Session persistence ---
       sessionStore: z.object({
         ttlDays: z.number().default(30)
       }).default({}),
+      // --- Installed integration tracking (e.g. plugins installed via CLI) ---
       integrations: z.record(
         z.string(),
         z.object({
@@ -481,7 +493,9 @@ var init_config = __esm({
           installedAt: z.string().optional()
         })
       ).default({}),
+      // --- Agent output verbosity control ---
       outputMode: z.enum(["low", "medium", "high"]).default("medium").optional(),
+      // --- Multi-agent switching behavior ---
       agentSwitch: z.object({
         labelHistory: z.boolean().default(true)
       }).default({})
@@ -497,6 +511,13 @@ var init_config = __esm({
         super();
         this.configPath = process.env.OPENACP_CONFIG_PATH || configPath || expandHome2("~/.openacp/config.json");
       }
+      /**
+       * 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
+       */
       async load() {
         const dir = path3.dirname(this.configPath);
         fs3.mkdirSync(dir, { recursive: true });
@@ -530,9 +551,17 @@ var init_config = __esm({
         }
         this.config = result.data;
       }
+      /** Returns a deep clone of the current config to prevent external mutation. */
       get() {
         return structuredClone(this.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.
+       */
       async save(updates, changePath) {
         const oldConfig = this.config ? structuredClone(this.config) : void 0;
         const raw = JSON.parse(fs3.readFileSync(this.configPath, "utf-8"));
@@ -554,9 +583,12 @@ var init_config = __esm({
         }
       }
       /**
-       * 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.
        */
       async setPath(dotPath, value) {
         const BLOCKED_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
@@ -573,6 +605,13 @@ var init_config = __esm({
         target[parts[parts.length - 1]] = value;
         await this.save(updates, dotPath);
       }
+      /**
+       * 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(input2) {
         const workspaceBase = path3.dirname(path3.dirname(this.configPath));
         if (!input2) {
@@ -607,17 +646,26 @@ var init_config = __esm({
         fs3.mkdirSync(namedPath, { recursive: true });
         return namedPath;
       }
+      /** 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. */
       async exists() {
         return fs3.existsSync(this.configPath);
       }
+      /** Returns the resolved path to the config JSON file. */
       getConfigPath() {
         return this.configPath;
       }
+      /** Writes a complete config object to disk, creating the directory if needed. Used during initial setup. */
       async writeNew(config) {
         const dir = path3.dirname(this.configPath);
         fs3.mkdirSync(dir, { recursive: true });
         fs3.writeFileSync(this.configPath, JSON.stringify(config, null, 2));
       }
+      /**
+       * 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.
+       */
       async applyEnvToPluginSettings(settingsManager) {
         const pluginOverrides = [
           { envVar: "OPENACP_TUNNEL_ENABLED", pluginName: "@openacp/tunnel", key: "enabled", transform: (v) => v === "true" },
@@ -644,6 +692,7 @@ var init_config = __esm({
           }
         }
       }
+      /** Applies env var overrides to the raw config object before Zod validation. */
       applyEnvOverrides(raw) {
         const overrides = [
           ["OPENACP_DEFAULT_AGENT", ["defaultAgent"]],
@@ -674,6 +723,7 @@ var init_config = __esm({
           raw.logging.level = "debug";
         }
       }
+      /** Recursively merges source into target, skipping prototype-pollution keys. */
       deepMerge(target, source) {
         const DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
         for (const key of Object.keys(source)) {
@@ -769,44 +819,75 @@ var init_events = __esm({
     };
     BusEvent = {
       // --- Session lifecycle ---
+      /** Fired when a new session is created and ready. */
       SESSION_CREATED: "session:created",
+      /** Fired when session metadata changes (status, name, overrides). */
       SESSION_UPDATED: "session:updated",
+      /** Fired when a session record is deleted from the store. */
       SESSION_DELETED: "session:deleted",
+      /** Fired when a session ends (agent finished or error). */
       SESSION_ENDED: "session:ended",
+      /** Fired when a session receives its auto-generated name. */
       SESSION_NAMED: "session:named",
+      /** Fired after a new session thread is created and bridge connected. */
       SESSION_THREAD_READY: "session:threadReady",
+      /** Fired when an agent's config options change (adapters update control UIs). */
       SESSION_CONFIG_CHANGED: "session:configChanged",
+      /** Fired during agent switch lifecycle (starting/succeeded/failed). */
       SESSION_AGENT_SWITCH: "session:agentSwitch",
       // --- Agent ---
+      /** Fired for every agent event (text, tool_call, usage, etc.). */
       AGENT_EVENT: "agent:event",
+      /** Fired when a prompt is sent to the agent. */
       AGENT_PROMPT: "agent:prompt",
       // --- Permissions ---
+      /** Fired when the agent requests user permission (blocks until resolved). */
       PERMISSION_REQUEST: "permission:request",
+      /** Fired after a permission request is resolved (approved or denied). */
       PERMISSION_RESOLVED: "permission:resolved",
       // --- Message visibility ---
+      /** Fired when a user message is queued (for cross-adapter input visibility). */
       MESSAGE_QUEUED: "message:queued",
+      /** Fired when a queued message starts processing. */
       MESSAGE_PROCESSING: "message:processing",
       // --- System lifecycle ---
+      /** Fired after kernel (core + plugin infrastructure) has booted. */
       KERNEL_BOOTED: "kernel:booted",
+      /** Fired when the system is fully ready (all adapters connected). */
       SYSTEM_READY: "system:ready",
+      /** Fired during graceful shutdown. */
       SYSTEM_SHUTDOWN: "system:shutdown",
+      /** Fired when all system commands are registered and available. */
       SYSTEM_COMMANDS_READY: "system:commands-ready",
       // --- Plugin lifecycle ---
+      /** Fired when a plugin loads successfully. */
       PLUGIN_LOADED: "plugin:loaded",
+      /** Fired when a plugin fails to load. */
       PLUGIN_FAILED: "plugin:failed",
+      /** Fired when a plugin is disabled (e.g., missing config). */
       PLUGIN_DISABLED: "plugin:disabled",
+      /** Fired when a plugin is unloaded during shutdown. */
       PLUGIN_UNLOADED: "plugin:unloaded",
       // --- Usage ---
+      /** Fired when a token usage record is captured (consumed by usage plugin). */
       USAGE_RECORDED: "usage:recorded"
     };
     SessionEv = {
+      /** Agent produced an event (text, tool_call, etc.) during a turn. */
       AGENT_EVENT: "agent_event",
+      /** Agent is requesting user permission — blocks until resolved. */
       PERMISSION_REQUEST: "permission_request",
+      /** Session ended (agent finished, cancelled, or errored). */
       SESSION_END: "session_end",
+      /** Session status changed (e.g., initializing → active). */
       STATUS_CHANGE: "status_change",
+      /** Session received an auto-generated name from the first response. */
       NAMED: "named",
+      /** An unrecoverable error occurred in the session. */
       ERROR: "error",
+      /** The session's prompt count changed (used for UI counters). */
       PROMPT_COUNT_CHANGED: "prompt_count_changed",
+      /** A new prompt turn started (provides TurnContext for middleware). */
       TURN_STARTED: "turn_started"
     };
   }
@@ -1563,13 +1644,16 @@ var init_settings_manager = __esm({
       constructor(basePath) {
         this.basePath = basePath;
       }
+      /** Returns the base path for all plugin settings directories. */
       getBasePath() {
         return this.basePath;
       }
+      /** Create a SettingsAPI instance scoped to a specific plugin. */
       createAPI(pluginName) {
         const settingsPath = this.getSettingsPath(pluginName);
         return new SettingsAPIImpl(settingsPath);
       }
+      /** Load a plugin's settings from disk. Returns empty object if file doesn't exist. */
       async loadSettings(pluginName) {
         const settingsPath = this.getSettingsPath(pluginName);
         try {
@@ -1579,6 +1663,7 @@ var init_settings_manager = __esm({
           return {};
         }
       }
+      /** Validate settings against a Zod schema. Returns valid if no schema is provided. */
       validateSettings(_pluginName, settings, schema) {
         if (!schema) return { valid: true };
         const result = schema.safeParse(settings);
@@ -1590,12 +1675,14 @@ var init_settings_manager = __esm({
           )
         };
       }
+      /** Resolve the absolute path to a plugin's settings.json file. */
       getSettingsPath(pluginName) {
         return path16.join(this.basePath, pluginName, "settings.json");
       }
       async getPluginSettings(pluginName) {
         return this.loadSettings(pluginName);
       }
+      /** Merge updates into existing settings (shallow merge). */
       async updatePluginSettings(pluginName, updates) {
         const api = this.createAPI(pluginName);
         const current = await api.getAll();
@@ -2321,6 +2408,12 @@ var init_doctor = __esm({
         this.dryRun = options?.dryRun ?? false;
         this.dataDir = options.dataDir;
       }
+      /**
+       * 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.
+       */
       async runAll() {
         const ctx = await this.buildContext();
         const checks = [...ALL_CHECKS].sort((a, b) => a.order - b.order);
@@ -2368,6 +2461,7 @@ var init_doctor = __esm({
         }
         return { categories, summary, pendingFixes };
       }
+      /** Constructs the shared context used by all checks — loads config if available. */
       async buildContext() {
         const dataDir = this.dataDir;
         const configPath = process.env.OPENACP_CONFIG_PATH || path22.join(dataDir, "config.json");
@@ -2432,6 +2526,7 @@ var init_instance_registry = __esm({
         this.registryPath = registryPath;
       }
       data = { version: 1, instances: {} };
+      /** Load the registry from disk. If the file is missing or corrupt, starts fresh. */
       load() {
         try {
           const raw = fs27.readFileSync(this.registryPath, "utf-8");
@@ -2459,26 +2554,33 @@ var init_instance_registry = __esm({
           this.save();
         }
       }
+      /** Persist the registry to disk, creating parent directories if needed. */
       save() {
         const dir = path25.dirname(this.registryPath);
         fs27.mkdirSync(dir, { recursive: true });
         fs27.writeFileSync(this.registryPath, JSON.stringify(this.data, null, 2));
       }
+      /** Add or update an instance entry in the registry. Does not persist — call save() after. */
       register(id, root) {
         this.data.instances[id] = { id, root };
       }
+      /** Remove an instance entry. Does not persist — call save() after. */
       remove(id) {
         delete this.data.instances[id];
       }
+      /** Look up an instance by its ID. */
       get(id) {
         return this.data.instances[id];
       }
+      /** Look up an instance by its root directory path. */
       getByRoot(root) {
         return Object.values(this.data.instances).find((e) => e.root === root);
       }
+      /** Returns all registered instances. */
       list() {
         return Object.values(this.data.instances);
       }
+      /** Returns `baseId` if available, otherwise appends `-2`, `-3`, etc. until unique. */
       uniqueId(baseId) {
         if (!this.data.instances[baseId]) return baseId;
         let n = 2;
@@ -2735,6 +2837,12 @@ var init_notification = __esm({
       constructor(adapters) {
         this.adapters = adapters;
       }
+      /**
+       * 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).
+       */
       async notify(channelId, notification) {
         const adapter = this.adapters.get(channelId);
         if (!adapter) return;
@@ -2743,6 +2851,12 @@ var init_notification = __esm({
         } catch {
         }
       }
+      /**
+       * 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.
+       */
       async notifyAll(notification) {
         for (const adapter of this.adapters.values()) {
           try {
@@ -2830,6 +2944,14 @@ var init_file_service = __esm({
         }
         return removed;
       }
+      /**
+       * 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.
+       */
       async saveFile(sessionId, fileName, data, mimeType) {
         const sessionDir = path32.join(this.baseDir, sessionId);
         await fs32.promises.mkdir(sessionDir, { recursive: true });
@@ -2844,6 +2966,10 @@ var init_file_service = __esm({
           size: data.length
         };
       }
+      /**
+       * 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.
+       */
       async resolveFile(filePath) {
         try {
           const stat = await fs32.promises.stat(filePath);
@@ -2888,6 +3014,7 @@ var init_file_service = __esm({
       extensionFromMime(mimeType) {
         return _FileService.extensionFromMime(mimeType);
       }
+      /** Returns the canonical file extension for a given MIME type (e.g. `"image/png"` → `".png"`). */
       static extensionFromMime(mimeType) {
         return MIME_TO_EXT[mimeType] || ".bin";
       }
@@ -2905,6 +3032,16 @@ var init_security_guard = __esm({
         this.getSecurityConfig = getSecurityConfig;
         this.sessionManager = sessionManager;
       }
+      /**
+       * 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`.
+       */
       async checkAccess(message) {
         const config = await this.getSecurityConfig();
         const allowedIds = config.allowedUserIds ?? [];
@@ -3298,6 +3435,13 @@ var init_sse_manager = __esm({
       sseCleanupHandlers = /* @__PURE__ */ new Map();
       healthInterval;
       boundHandlers = [];
+      /**
+       * 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() {
         if (!this.eventBus) return;
         const events = [
@@ -3331,6 +3475,13 @@ var init_sse_manager = __esm({
           });
         }, 15e3);
       }
+      /**
+       * 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, res) {
         if (this.sseConnections.size >= MAX_SSE_CONNECTIONS) {
           res.writeHead(503, { "Content-Type": "application/json" });
@@ -3365,6 +3516,13 @@ var init_sse_manager = __esm({
         this.sseCleanupHandlers.set(res, cleanup);
         req.on("close", cleanup);
       }
+      /**
+       * 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, data) {
         const payload = `event: ${event}
 data: ${JSON.stringify(data)}
@@ -3400,6 +3558,12 @@ data: ${JSON.stringify(data)}
           this.handleRequest(request.raw, reply.raw);
         };
       }
+      /**
+       * 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() {
         if (this.healthInterval) clearInterval(this.healthInterval);
         if (this.eventBus) {
@@ -3459,9 +3623,15 @@ var init_static_server = __esm({
           }
         }
       }
+      /** Returns true if a UI build was found and static serving is active. */
       isAvailable() {
         return this.uiDir !== void 0;
       }
+      /**
+       * 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, res) {
         if (!this.uiDir) return false;
         const urlPath = (req.url || "/").split("?")[0];
@@ -3523,23 +3693,38 @@ var init_speech_service = __esm({
       setProviderFactory(factory) {
         this.providerFactory = factory;
       }
+      /** Register an STT provider by name. Overwrites any existing provider with the same name. */
       registerSTTProvider(name, provider) {
         this.sttProviders.set(name, provider);
       }
+      /** Register a TTS provider by name. Called by external TTS plugins (e.g. msedge-tts-plugin). */
       registerTTSProvider(name, provider) {
         this.ttsProviders.set(name, provider);
       }
+      /** Remove a TTS provider — called by external plugins on teardown. */
       unregisterTTSProvider(name) {
         this.ttsProviders.delete(name);
       }
+      /** Returns true if an STT provider is configured and has credentials. */
       isSTTAvailable() {
         const { provider, providers } = this.config.stt;
         return provider !== null && providers[provider]?.apiKey !== void 0;
       }
+      /**
+       * 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() {
         const provider = this.config.tts.provider;
         return provider !== null && this.ttsProviders.has(provider);
       }
+      /**
+       * Transcribes audio using the configured STT provider.
+       *
+       * @throws if no STT provider is configured or if the named provider is not registered.
+       */
       async transcribe(audioBuffer, mimeType, options) {
         const providerName = this.config.stt.provider;
         if (!providerName || !this.config.stt.providers[providerName]?.apiKey) {
@@ -3551,6 +3736,11 @@ var init_speech_service = __esm({
         }
         return provider.transcribe(audioBuffer, mimeType, options);
       }
+      /**
+       * Synthesizes speech using the configured TTS provider.
+       *
+       * @throws if no TTS provider is configured or if the named provider is not registered.
+       */
       async synthesize(text3, options) {
         const providerName = this.config.tts.provider;
         if (!providerName) {
@@ -3562,10 +3752,17 @@ var init_speech_service = __esm({
         }
         return provider.synthesize(text3, options);
       }
+      /** Replace the active config without rebuilding providers. Use `refreshProviders` to also rebuild. */
       updateConfig(config) {
         this.config = config;
       }
-      /** 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) {
         this.config = newConfig;
         if (this.providerFactory) {
@@ -3605,6 +3802,12 @@ var init_groq = __esm({
         this.defaultModel = defaultModel;
       }
       name = "groq";
+      /**
+       * 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.
+       */
       async transcribe(audioBuffer, mimeType, options) {
         const ext = mimeToExt(mimeType);
         const form = new FormData();
@@ -3707,6 +3910,12 @@ var init_context_manager = __esm({
       constructor(cachePath) {
         this.cache = new ContextCache(cachePath);
       }
+      /**
+       * 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) {
         this.historyStore = store;
       }
@@ -3722,19 +3931,43 @@ var init_context_manager = __esm({
       async flushSession(sessionId) {
         if (this.sessionFlusher) await this.sessionFlusher(sessionId);
       }
+      /**
+       * 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.
+       */
       async getHistory(sessionId) {
         if (!this.historyStore) return null;
         return this.historyStore.read(sessionId);
       }
+      /**
+       * 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) {
         this.providers.push(provider);
       }
+      /**
+       * 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.
+       */
       async getProvider(repoPath) {
         for (const provider of this.providers) {
           if (await provider.isAvailable(repoPath)) return provider;
         }
         return 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.
+       */
       async listSessions(query) {
         for (const provider of this.providers) {
           if (!await provider.isAvailable(query.repoPath)) continue;
@@ -3743,6 +3976,13 @@ var init_context_manager = __esm({
         }
         return 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).
+       */
       async buildContext(query, options) {
         const queryKey = `${query.type}:${query.value}:${options?.limit ?? ""}:${options?.maxTokens ?? ""}:${options?.labelAgent ?? ""}`;
         if (!options?.noCache) {
@@ -3905,8 +4145,9 @@ var init_checkpoint_reader = __esm({
             sessionIndex: String(idx),
             transcriptPath,
             createdAt,
+            // endedAt isn't stored in the checkpoint metadata; EntireProvider fills
+            // it from the last turn timestamp when parsing the JSONL transcript.
             endedAt: createdAt,
-            // will be filled from JSONL by conversation builder
             branch: smeta.branch ?? cpMeta.branch ?? "",
             agent: smeta.agent ?? "",
             turnCount: smeta.session_metrics?.turn_count ?? 0,
@@ -4735,11 +4976,21 @@ var init_messaging_adapter = __esm({
         this.adapterConfig = adapterConfig;
       }
       // === Message dispatch flow ===
+      /**
+       * 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.
+       */
       async sendMessage(sessionId, content) {
         const verbosity = this.getVerbosity();
         if (!this.shouldDisplay(content, verbosity)) return;
         await this.dispatchMessage(sessionId, content, verbosity);
       }
+      /**
+       * Routes a message to its type-specific handler.
+       * Subclasses can override this for custom dispatch logic, but typically
+       * override individual handle* methods instead.
+       */
       async dispatchMessage(sessionId, content, verbosity) {
         switch (content.type) {
           case "text":
@@ -4777,6 +5028,8 @@ var init_messaging_adapter = __esm({
         }
       }
       // === Default handlers — all protected, all overridable ===
+      // Each handler is a no-op by default. Subclasses override only the message
+      // types they support (e.g., Telegram overrides handleText, handleToolCall, etc.).
       async handleText(_sessionId, _content) {
       }
       async handleThought(_sessionId, _content, _verbosity) {
@@ -4810,6 +5063,10 @@ var init_messaging_adapter = __esm({
       async handleResourceLink(_sessionId, _content) {
       }
       // === Helpers ===
+      /**
+       * Resolves the current output verbosity by checking (in priority order):
+       * per-channel config, global config, then adapter default. Falls back to "medium".
+       */
       getVerbosity() {
         const config = this.context.configManager.get();
         const channelConfig = config.channels;
@@ -4818,6 +5075,13 @@ var init_messaging_adapter = __esm({
         if (v === "low" || v === "high") return v;
         return "medium";
       }
+      /**
+       * 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".
+       */
       shouldDisplay(content, verbosity) {
         if (verbosity === "low" && HIDDEN_ON_LOW.has(content.type)) return false;
         if (content.type === "tool_call") {
@@ -5044,6 +5308,13 @@ var init_send_queue = __esm({
       get pending() {
         return this.items.length;
       }
+      /**
+       * 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(fn, opts) {
         const type = opts?.type ?? "other";
         const key = opts?.key;
@@ -5071,6 +5342,11 @@ var init_send_queue = __esm({
         this.scheduleProcess();
         return promise;
       }
+      /**
+       * 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() {
         this.config.onRateLimited?.();
         const remaining = [];
@@ -5089,6 +5365,10 @@ var init_send_queue = __esm({
         }
         this.items = [];
       }
+      /**
+       * Schedules the next item for processing after the rate-limit delay.
+       * Uses per-category timing when available, falling back to the global minInterval.
+       */
       scheduleProcess() {
         if (this.processing) return;
         if (this.items.length === 0) return;
@@ -5147,6 +5427,9 @@ var init_tool_card_state = __esm({
       specs = [];
       planEntries;
       usage;
+      // Lifecycle: active (first flush pending) → active (subsequent updates debounced) → finalized.
+      // Once finalized, all updateFromSpec/updatePlan/appendUsage/finalize() calls are no-ops —
+      // guards against events arriving after the session has ended or the tool has already completed.
       finalized = false;
       isFirstFlush = true;
       debounceTimer;
@@ -5154,6 +5437,7 @@ var init_tool_card_state = __esm({
       constructor(config) {
         this.onFlush = config.onFlush;
       }
+      /** Adds or updates a tool spec. First call flushes immediately; subsequent calls are debounced. */
       updateFromSpec(spec) {
         if (this.finalized) return;
         const existingIdx = this.specs.findIndex((s) => s.id === spec.id);
@@ -5169,6 +5453,7 @@ var init_tool_card_state = __esm({
           this.scheduleFlush();
         }
       }
+      /** Updates the plan entries displayed alongside tool cards. */
       updatePlan(entries) {
         if (this.finalized) return;
         this.planEntries = entries;
@@ -5179,17 +5464,20 @@ var init_tool_card_state = __esm({
           this.scheduleFlush();
         }
       }
+      /** Appends token usage data to the tool card (typically at end of turn). */
       appendUsage(usage) {
         if (this.finalized) return;
         this.usage = usage;
         this.scheduleFlush();
       }
+      /** Marks the turn as complete and flushes the final snapshot immediately. */
       finalize() {
         if (this.finalized) return;
         this.finalized = true;
         this.clearDebounce();
         this.flush();
       }
+      /** Stops all pending flushes without emitting a final snapshot. */
       destroy() {
         this.finalized = true;
         this.clearDebounce();
@@ -5295,9 +5583,11 @@ var init_stream_accumulator = __esm({
           entry.diffStats = update.diffStats;
         }
       }
+      /** Retrieves a tool entry by ID, or undefined if not yet tracked. */
       get(id) {
         return this.entries.get(id);
       }
+      /** Resets all state between turns. */
       clear() {
         this.entries.clear();
         this.pendingUpdates.clear();
@@ -5306,20 +5596,24 @@ var init_stream_accumulator = __esm({
     ThoughtBuffer = class {
       chunks = [];
       sealed = false;
+      /** Appends a thought text chunk. Ignored if already sealed. */
       append(chunk) {
         if (this.sealed) return;
         this.chunks.push(chunk);
       }
+      /** Marks the thought as complete and returns the full accumulated text. */
       seal() {
         this.sealed = true;
         return this.chunks.join("");
       }
+      /** Returns the text accumulated so far without sealing. */
       getText() {
         return this.chunks.join("");
       }
       isSealed() {
         return this.sealed;
       }
+      /** Resets the buffer for reuse in a new turn. */
       reset() {
         this.chunks = [];
         this.sealed = false;
@@ -5472,6 +5766,13 @@ var init_display_spec_builder = __esm({
       constructor(tunnelService) {
         this.tunnelService = tunnelService;
       }
+      /**
+       * 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, mode, sessionContext) {
         const effectiveKind = entry.displayKind ?? (isApplyPatchOtherTool(entry.kind, entry.name, entry.rawInput) ? "edit" : entry.kind);
         const icon = KIND_ICONS[effectiveKind] ?? KIND_ICONS["other"] ?? "\u{1F6E0}\uFE0F";
@@ -5530,6 +5831,7 @@ var init_display_spec_builder = __esm({
           isHidden
         };
       }
+      /** Builds a display spec for an agent thought. Content is only included at high verbosity. */
       buildThoughtSpec(content, mode) {
         const indicator = "Thinking...";
         return {
@@ -5551,6 +5853,7 @@ var init_output_mode_resolver = __esm({
     "use strict";
     VALID_MODES = /* @__PURE__ */ new Set(["low", "medium", "high"]);
     OutputModeResolver = class {
+      /** Resolves the effective output mode by walking the override cascade. */
       resolve(configManager, adapterName, sessionId, sessionManager) {
         const config = configManager.get();
         let mode = toOutputMode(config.outputMode) ?? "medium";
@@ -8425,6 +8728,14 @@ var init_permissions = __esm({
         this.sendNotification = sendNotification;
       }
       pending = /* @__PURE__ */ new Map();
+      /**
+       * Send a permission request to the session's topic as an inline keyboard message,
+       * and fire a notification to the Notifications topic so the user is alerted.
+       *
+       * Each button encodes `p:<callbackKey>:<optionId>`. The callbackKey is a short
+       * nanoid that maps to the full pending state stored in-memory, avoiding the
+       * 64-byte Telegram callback_data limit.
+       */
       async sendPermissionRequest(session, request) {
         const threadId = Number(session.threadId);
         const callbackKey = nanoid4(8);
@@ -8459,6 +8770,12 @@ ${escapeHtml(request.description)}`,
           deepLink
         });
       }
+      /**
+       * Register the `p:` callback handler in the bot's middleware chain.
+       *
+       * Must be called during setup so grammY processes permission responses
+       * before other generic callback handlers.
+       */
       setupCallbackHandler() {
         this.bot.on("callback_query:data", async (ctx, next) => {
           const data = ctx.callbackQuery.data;
@@ -8617,7 +8934,10 @@ var init_activity = __esm({
         this.sessionId = sessionId;
         this.state = new ToolCardState({
           onFlush: (snapshot) => {
-            this.flushPromise = this.flushPromise.then(() => this._sendOrEdit(snapshot)).catch(() => {
+            this.flushPromise = this.flushPromise.then(() => {
+              if (this.aborted) return;
+              return this._sendOrEdit(snapshot);
+            }).catch(() => {
             });
           }
         });
@@ -8627,6 +8947,7 @@ var init_activity = __esm({
       lastSentText;
       flushPromise = Promise.resolve();
       overflowMsgIds = [];
+      aborted = false;
       tracer;
       sessionId;
       updateFromSpec(spec) {
@@ -8643,6 +8964,7 @@ var init_activity = __esm({
         await this.flushPromise;
       }
       destroy() {
+        this.aborted = true;
         this.state.destroy();
       }
       hasContent() {
@@ -8883,6 +9205,7 @@ var init_streaming = __esm({
       lastSentHtml = "";
       displayTruncated = false;
       tracer;
+      /** Append a text chunk to the buffer and schedule a throttled flush. */
       append(text3) {
         if (!text3) return;
         this.buffer += text3;
@@ -8962,6 +9285,16 @@ var init_streaming = __esm({
           }
         }
       }
+      /**
+       * Flush the complete buffer as the final message for this turn.
+       *
+       * Cancels any pending debounce timer, waits for in-flight flushes to settle,
+       * then sends the full content. If the HTML exceeds 4096 bytes, the content is
+       * split at markdown boundaries to avoid breaking HTML tags mid-tag.
+       *
+       * Returns the Telegram message ID of the sent/edited message, or undefined
+       * if nothing was sent (empty buffer or all network calls failed).
+       */
       async finalize() {
         this.tracer?.log("telegram", { action: "draft:finalize", sessionId: this.sessionId, bufferLen: this.buffer.length, msgId: this.messageId });
         if (this.flushTimer) {
@@ -9033,9 +9366,14 @@ var init_streaming = __esm({
         this.tracer?.log("telegram", { action: "draft:finalize:split", sessionId: this.sessionId, chunks: mdChunks.length });
         return this.messageId;
       }
+      /** Returns the Telegram message ID for this draft, or undefined if not yet sent. */
       getMessageId() {
         return this.messageId;
       }
+      /**
+       * Strip occurrences of `pattern` from the buffer and edit the message in-place.
+       * Used by the TTS plugin to remove [TTS]...[/TTS] blocks after audio is sent.
+       */
       async stripPattern(pattern) {
         if (!this.messageId || !this.buffer) return;
         const stripped = this.buffer.replace(pattern, "").trim();
@@ -9073,6 +9411,10 @@ var init_draft_manager = __esm({
       drafts = /* @__PURE__ */ new Map();
       textBuffers = /* @__PURE__ */ new Map();
       finalizedDrafts = /* @__PURE__ */ new Map();
+      /**
+       * Return the active draft for a session, creating one if it doesn't exist yet.
+       * Only one draft per session exists at a time.
+       */
       getOrCreate(sessionId, threadId, tracer = null) {
         let draft = this.drafts.get(sessionId);
         if (!draft) {
@@ -9101,7 +9443,12 @@ var init_draft_manager = __esm({
         );
       }
       /**
-       * Finalize the current draft and return the message ID.
+       * Finalize the active draft for a session and retain a short-lived reference for post-send edits.
+       *
+       * Removes the draft from the active map before awaiting to prevent concurrent calls from
+       * double-finalizing the same draft. If the draft produces a message ID, stores it as a
+       * `FinalizedDraft` so `stripPattern` (e.g. TTS block removal) can still edit the message
+       * after it has been sent.
        */
       async finalize(sessionId, _assistantSessionId) {
         const draft = this.drafts.get(sessionId);
@@ -9128,6 +9475,12 @@ var init_draft_manager = __esm({
           await finalized.draft.stripPattern(pattern);
         }
       }
+      /**
+       * Discard all draft state for a session without sending anything.
+       *
+       * Removes the active draft, text buffer, and finalized draft reference. Called when a
+       * session ends or is reset and any unsent content should be silently dropped.
+       */
       cleanup(sessionId) {
         this.drafts.delete(sessionId);
         this.textBuffers.delete(sessionId);
@@ -9146,14 +9499,19 @@ var init_skill_command_manager = __esm({
     init_log();
     log34 = createChildLogger({ module: "skill-commands" });
     SkillCommandManager = class {
-      // sessionId → pinned msgId
       constructor(bot, chatId, sendQueue, sessionManager) {
         this.bot = bot;
         this.chatId = chatId;
         this.sendQueue = sendQueue;
         this.sessionManager = sessionManager;
       }
+      // sessionId → Telegram message ID of the pinned skills message
       messages = /* @__PURE__ */ new Map();
+      /**
+       * Send or update the pinned skill commands message for a session.
+       * Creates a new pinned message if none exists; edits the existing one otherwise.
+       * Passing an empty `commands` array removes the pinned message.
+       */
       async send(sessionId, threadId, commands) {
         if (!this.messages.has(sessionId)) {
           const record = this.sessionManager.getSessionRecord(sessionId);
@@ -9534,7 +9892,11 @@ var init_adapter = __esm({
       _topicsInitialized = false;
       /** Background watcher timer — cancelled on stop() or when topics succeed */
       _prerequisiteWatcher = null;
-      /** 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.
+       */
       storeControlMsgId(sessionId, msgId) {
         this.controlMsgIds.set(sessionId, msgId);
         const record = this.core.sessionManager.getSessionRecord(sessionId);
@@ -9599,6 +9961,12 @@ var init_adapter = __esm({
         this.telegramConfig = config;
         this.saveTopicIds = saveTopicIds;
       }
+      /**
+       * 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.
+       */
       async start() {
         this.bot = new Bot(this.telegramConfig.botToken, {
           client: {
@@ -10029,6 +10397,13 @@ OpenACP will automatically retry until this is resolved.`;
         };
         this._prerequisiteWatcher = setTimeout(retry, schedule[0]);
       }
+      /**
+       * 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.
+       */
       async stop() {
         if (this._prerequisiteWatcher !== null) {
           clearTimeout(this._prerequisiteWatcher);
@@ -10162,8 +10537,7 @@ ${lines.join("\n")}`;
             await this.draftManager.finalize(sessionId, assistantSession?.id);
           }
           if (sessionId) {
-            const tracker = this.sessionTrackers.get(sessionId);
-            if (tracker) await tracker.onNewPrompt();
+            await this.drainAndResetTracker(sessionId);
           }
           ctx.replyWithChatAction("typing").catch(() => {
           });
@@ -10252,9 +10626,26 @@ ${lines.join("\n")}`;
        * its creation event. This queue ensures events are processed in the order they arrive.
        */
       _dispatchQueues = /* @__PURE__ */ new Map();
+      /**
+       * 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.
+       */
+      async drainAndResetTracker(sessionId) {
+        const pendingDispatch = this._dispatchQueues.get(sessionId);
+        if (pendingDispatch) await pendingDispatch;
+        const tracker = this.sessionTrackers.get(sessionId);
+        if (tracker) await tracker.onNewPrompt();
+      }
       getTracer(sessionId) {
         return this.core.sessionManager.getSession(sessionId)?.agentInstance?.debugTracer ?? null;
       }
+      /**
+       * 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.
+       */
       async sendMessage(sessionId, content) {
         const session = this.core.sessionManager.getSession(sessionId);
         if (!session) return;
@@ -10568,6 +10959,11 @@ Task completed.
           )
         );
       }
+      /**
+       * 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.
+       */
       async sendPermissionRequest(sessionId, request) {
         this.getTracer(sessionId)?.log("telegram", { action: "permission:send", sessionId, requestId: request.id, description: request.description });
         log36.info({ sessionId, requestId: request.id }, "Permission request sent");
@@ -10577,6 +10973,11 @@ Task completed.
           () => this.permissionHandler.sendPermissionRequest(session, request)
         );
       }
+      /**
+       * 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.
+       */
       async sendNotification(notification) {
         this.getTracer(notification.sessionId)?.log("telegram", { action: "notification:send", sessionId: notification.sessionId, type: notification.type });
         if (notification.sessionId === this.core.assistantManager?.get("telegram")?.id) return;
@@ -10617,6 +11018,10 @@ Task completed.
           })
         );
       }
+      /**
+       * 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).
+       */
       async createSessionThread(sessionId, name) {
         this.getTracer(sessionId)?.log("telegram", { action: "thread:create", sessionId, name });
         log36.info({ sessionId, name }, "Session topic created");
@@ -10624,6 +11029,10 @@ Task completed.
           await createSessionTopic(this.bot, this.telegramConfig.chatId, name)
         );
       }
+      /**
+       * 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).
+       */
       async renameSessionThread(sessionId, newName) {
         this.getTracer(sessionId)?.log("telegram", { action: "thread:rename", sessionId, newName });
         const session = this.core.sessionManager.getSession(sessionId);
@@ -10641,6 +11050,7 @@ Task completed.
         );
         await this.core.sessionManager.patchRecord(sessionId, { name: newName });
       }
+      /** Delete the forum topic associated with a session. */
       async deleteSessionThread(sessionId) {
         const record = this.core.sessionManager.getSessionRecord(sessionId);
         const platform2 = record?.platform;
@@ -10655,6 +11065,11 @@ Task completed.
           );
         }
       }
+      /**
+       * 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.
+       */
       async sendSkillCommands(sessionId, commands) {
         if (sessionId === this.core.assistantManager?.get("telegram")?.id) return;
         const session = this.core.sessionManager.getSession(sessionId);
@@ -10739,7 +11154,10 @@ Task completed.
           return;
         }
         const sid = await this.resolveSessionId(threadId);
-        if (sid) await this.draftManager.finalize(sid, this.core.assistantManager?.get("telegram")?.id);
+        if (sid) {
+          await this.draftManager.finalize(sid, this.core.assistantManager?.get("telegram")?.id);
+          await this.drainAndResetTracker(sid);
+        }
         this.core.handleMessage({
           channelId: "telegram",
           threadId: String(threadId),
@@ -10748,10 +11166,24 @@ Task completed.
           attachments: [att]
         }).catch((err) => log36.error({ err }, "handleMessage error"));
       }
+      /**
+       * 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.
+       */
       async cleanupSkillCommands(sessionId) {
         this._pendingSkillCommands.delete(sessionId);
         await this.skillManager.cleanup(sessionId);
       }
+      /**
+       * 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.
+       */
       async cleanupSessionState(sessionId) {
         this._pendingSkillCommands.delete(sessionId);
         await this.draftManager.finalize(sessionId, this.core.assistantManager?.get("telegram")?.id);
@@ -10762,9 +11194,22 @@ Task completed.
           this.sessionTrackers.delete(sessionId);
         }
       }
+      /**
+       * 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.
+       */
       async stripTTSBlock(sessionId) {
         await this.draftManager.stripPattern(sessionId, /\[TTS\][\s\S]*?\[\/TTS\]/g);
       }
+      /**
+       * 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).
+       */
       async archiveSessionTopic(sessionId) {
         this.getTracer(sessionId)?.log("telegram", { action: "thread:archive", sessionId });
         const core = this.core;
@@ -10865,12 +11310,14 @@ var StderrCapture = class {
     this.maxLines = maxLines;
   }
   lines = [];
+  /** Append a chunk of stderr output, splitting on newlines and trimming to maxLines. */
   append(chunk) {
     this.lines.push(...chunk.split("\n").filter(Boolean));
     if (this.lines.length > this.maxLines) {
       this.lines = this.lines.slice(-this.maxLines);
     }
   }
+  /** Return all captured lines joined as a single string. */
   getLastLines() {
     return this.lines.join("\n");
   }
@@ -10891,13 +11338,18 @@ import fs4 from "fs";
 import path4 from "path";
 import ignore from "ignore";
 var DEFAULT_DENY_PATTERNS = [
+  // Environment files — contain API keys, database URLs, etc.
   ".env",
   ".env.*",
+  // Cryptographic keys
   "*.key",
   "*.pem",
+  // SSH and cloud credentials
   ".ssh/",
   ".aws/",
+  // OpenACP workspace — contains bot tokens and secrets
   ".openacp/",
+  // Generic credential/secret files
   "**/credentials*",
   "**/secrets*",
   "**/*.secret"
@@ -10925,6 +11377,20 @@ var PathGuard = class {
       this.ig.add(options.ignorePatterns);
     }
   }
+  /**
+   * Checks whether an agent is allowed to access the given path.
+   *
+   * Validation order:
+   *   1. Write to .openacpignore is always blocked (prevents agents from weakening their own restrictions)
+   *   2. Path must be within cwd or an explicitly allowlisted path
+   *   3. If within cwd but not allowlisted, path must not match any deny pattern
+   *
+   * @param targetPath - The path the agent is attempting to access.
+   * @param operation - The operation type. Write operations are subject to stricter
+   *   restrictions than reads — specifically, writing to `.openacpignore` is blocked
+   *   (to prevent agents from weakening their own restrictions), while reading it is allowed.
+   * @returns `{ allowed: true }` or `{ allowed: false, reason: "..." }`
+   */
   validatePath(targetPath, operation) {
     const resolved = path4.resolve(targetPath);
     let realPath;
@@ -10960,6 +11426,7 @@ var PathGuard = class {
     }
     return { allowed: true, reason: "" };
   }
+  /** Adds an additional allowed path at runtime (e.g. for file-service uploads). */
   addAllowedPath(p) {
     try {
       this.allowedPaths.push(fs4.realpathSync(path4.resolve(p)));
@@ -10967,6 +11434,10 @@ var PathGuard = class {
       this.allowedPaths.push(path4.resolve(p));
     }
   }
+  /**
+   * Loads additional deny patterns from .openacpignore in the workspace root.
+   * Follows .gitignore syntax — blank lines and lines starting with # are skipped.
+   */
   static loadIgnoreFile(cwd) {
     const ignorePath = path4.join(cwd, ".openacpignore");
     try {
@@ -10980,6 +11451,7 @@ var PathGuard = class {
 
 // src/core/security/env-filter.ts
 var DEFAULT_ENV_WHITELIST = [
+  // Shell basics — agents need these to resolve commands and write temp files
   "PATH",
   "HOME",
   "SHELL",
@@ -10992,11 +11464,11 @@ var DEFAULT_ENV_WHITELIST = [
   "XDG_*",
   "NODE_ENV",
   "EDITOR",
-  // Git
+  // Git — agents need git config and SSH access for code operations
   "GIT_*",
   "SSH_AUTH_SOCK",
   "SSH_AGENT_PID",
-  // Terminal rendering
+  // Terminal rendering — ensures correct color output in agent responses
   "COLORTERM",
   "FORCE_COLOR",
   "NO_COLOR",
@@ -11031,6 +11503,7 @@ var TypedEmitter = class _TypedEmitter {
   listeners = /* @__PURE__ */ new Map();
   paused = false;
   buffer = [];
+  /** Register a listener for the given event. Returns `this` for chaining. */
   on(event, listener) {
     let set = this.listeners.get(event);
     if (!set) {
@@ -11040,10 +11513,17 @@ var TypedEmitter = class _TypedEmitter {
     set.add(listener);
     return this;
   }
+  /** Remove a specific listener for the given event. */
   off(event, listener) {
     this.listeners.get(event)?.delete(listener);
     return 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(event, ...args) {
     if (this.paused) {
       if (this.passthroughFn?.(event, args)) {
@@ -11087,6 +11567,7 @@ var TypedEmitter = class _TypedEmitter {
   get bufferSize() {
     return this.buffer.length;
   }
+  /** Remove all listeners for a specific event, or all events if none specified. */
   removeAllListeners(event) {
     if (event) {
       this.listeners.delete(event);
@@ -11094,6 +11575,7 @@ var TypedEmitter = class _TypedEmitter {
       this.listeners.clear();
     }
   }
+  /** Deliver an event to listeners, isolating errors so one broken listener doesn't break others. */
   deliver(event, args) {
     const set = this.listeners.get(event);
     if (!set) return;
@@ -11158,6 +11640,11 @@ var TerminalManager = class {
   constructor(maxOutputBytes = 1024 * 1024) {
     this.maxOutputBytes = maxOutputBytes;
   }
+  /**
+   * Spawn a new terminal process. Runs terminal:beforeCreate middleware first
+   * (which can modify command/args/env or block creation entirely).
+   * Returns a terminalId for subsequent output/wait/kill operations.
+   */
   async createTerminal(sessionId, params, middlewareChain) {
     let termCommand = params.command;
     let termArgs = params.args ?? [];
@@ -11239,6 +11726,7 @@ var TerminalManager = class {
     });
     return { terminalId };
   }
+  /** Retrieve accumulated stdout/stderr output for a terminal. */
   getOutput(terminalId) {
     const state = this.terminals.get(terminalId);
     if (!state) {
@@ -11253,6 +11741,7 @@ var TerminalManager = class {
       } : void 0
     };
   }
+  /** Block until the terminal process exits, returning exit code and signal. */
   async waitForExit(terminalId) {
     const state = this.terminals.get(terminalId);
     if (!state) {
@@ -11276,6 +11765,7 @@ var TerminalManager = class {
       }
     });
   }
+  /** Send SIGTERM to a terminal process (graceful shutdown). */
   kill(terminalId) {
     const state = this.terminals.get(terminalId);
     if (!state) {
@@ -11283,6 +11773,7 @@ var TerminalManager = class {
     }
     state.process.kill("SIGTERM");
   }
+  /** Force-kill (SIGKILL) and immediately remove a terminal from the registry. */
   release(terminalId) {
     const state = this.terminals.get(terminalId);
     if (!state) {
@@ -11291,6 +11782,7 @@ var TerminalManager = class {
     state.process.kill("SIGKILL");
     this.terminals.delete(terminalId);
   }
+  /** Force-kill all terminals. Used during session/system teardown. */
   destroyAll() {
     for (const [, t] of this.terminals) {
       t.process.kill("SIGKILL");
@@ -11322,6 +11814,12 @@ var DebugTracer = class {
   }
   dirCreated = false;
   logDir;
+  /**
+   * 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, data) {
     try {
       if (!this.dirCreated) {
@@ -11442,9 +11940,13 @@ var AgentInstance = class _AgentInstance extends TypedEmitter {
   connection;
   child;
   stderrCapture;
+  /** Manages terminal subprocesses that agents can spawn for shell commands. */
   terminalManager = new TerminalManager();
+  /** Shared across all instances — resolves MCP server configs for ACP sessions. */
   static mcpManager = new McpManager();
+  /** Guards against emitting crash events during intentional shutdown. */
   _destroying = false;
+  /** Restricts agent file I/O to the workspace directory and explicitly allowed paths. */
   pathGuard;
   sessionId;
   agentName;
@@ -11454,16 +11956,36 @@ var AgentInstance = class _AgentInstance extends TypedEmitter {
   initialSessionResponse;
   middlewareChain;
   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) {
     this.pathGuard.addAllowedPath(p);
   }
-  // Callback — set by core when wiring events
+  // Callback — set by Session/Core when wiring events. Returns the selected
+  // permission option ID. Default no-op auto-selects the first option.
   onPermissionRequest = async () => "";
   constructor(agentName) {
     super();
     this.agentName = agentName;
   }
+  /**
+   * 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.
+   */
   static async spawnSubprocess(agentDef, workingDirectory, allowedPaths = []) {
     const instance = new _AgentInstance(agentDef.name);
     const resolved = resolveAgentCommand(agentDef.command);
@@ -11562,6 +12084,13 @@ var AgentInstance = class _AgentInstance extends TypedEmitter {
     );
     return instance;
   }
+  /**
+   * 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.
+   */
   setupCrashDetection() {
     this.child.on("exit", (code, signal) => {
       if (this._destroying) return;
@@ -11584,6 +12113,18 @@ ${stderr}`
       log4.debug({ sessionId: this.sessionId }, "ACP connection closed");
     });
   }
+  /**
+   * 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 async spawn(agentDef, workingDirectory, mcpServers, allowedPaths) {
     log4.debug(
       { agentName: agentDef.name, command: agentDef.command },
@@ -11617,6 +12158,15 @@ ${stderr}`
     );
     return instance;
   }
+  /**
+   * 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 async resume(agentDef, workingDirectory, agentSessionId, mcpServers, allowedPaths) {
     log4.debug({ agentName: agentDef.name, agentSessionId }, "Resuming agent");
     const spawnStart = Date.now();
@@ -11683,12 +12233,26 @@ ${stderr}`
     instance.setupCrashDetection();
     return instance;
   }
-  // createClient — implemented in Task 6b
+  /**
+   * 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)
+   */
   createClient(_agent) {
     const self = this;
     const MAX_OUTPUT_BYTES = 1024 * 1024;
     return {
       // ── Session updates ──────────────────────────────────────────────────
+      // The agent streams its response as a series of session update events.
+      // Each event type maps to an internal AgentEvent that Session relays
+      // to adapters for rendering (text chunks, tool calls, usage stats, etc.).
+      // Chunks are forwarded to Session individually as they arrive — no buffering
+      // happens at this layer. If buffering is needed (e.g., to avoid rate limits),
+      // it is the responsibility of the Session or adapter layer.
       async sessionUpdate(params) {
         const update = params.update;
         let event = null;
@@ -11817,6 +12381,10 @@ ${stderr}`
         }
       },
       // ── Permission requests ──────────────────────────────────────────────
+      // The agent needs user approval before performing sensitive operations
+      // (e.g., file writes, shell commands). This proxies the request up
+      // through Session → PermissionGate → adapter → user, then returns
+      // the user's chosen option ID back to the agent.
       async requestPermission(params) {
         const permissionRequest = {
           id: params.toolCall.toolCallId,
@@ -11833,6 +12401,9 @@ ${stderr}`
         };
       },
       // ── File operations ──────────────────────────────────────────────────
+      // The agent reads/writes files through these callbacks rather than
+      // accessing the filesystem directly. This allows PathGuard to enforce
+      // workspace boundaries and middleware hooks to intercept I/O.
       async readTextFile(params) {
         const p = params;
         const pathCheck = self.pathGuard.validatePath(p.path, "read");
@@ -11868,6 +12439,8 @@ ${stderr}`
         return {};
       },
       // ── Terminal operations (delegated to TerminalManager) ─────────────
+      // Agents can spawn shell commands via terminal operations. TerminalManager
+      // handles subprocess lifecycle, output capture, and byte-limit enforcement.
       async createTerminal(params) {
         return self.terminalManager.createTerminal(
           self.sessionId,
@@ -11897,6 +12470,13 @@ ${stderr}`
     };
   }
   // ── New ACP methods ──────────────────────────────────────────────────
+  /**
+   * 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).
+   */
   async setConfigOption(configId, value) {
     try {
       return await this.connection.setSessionConfigOption({
@@ -11924,12 +12504,14 @@ ${stderr}`
       throw err;
     }
   }
+  /** List the agent's known sessions, optionally filtered by working directory. */
   async listSessions(cwd, cursor) {
     return await this.connection.listSessions({
       cwd: cwd ?? null,
       cursor: cursor ?? null
     });
   }
+  /** Load an existing agent session by ID into this subprocess. */
   async loadSession(sessionId, cwd, mcpServers) {
     const resolvedMcp = _AgentInstance.mcpManager.resolve(mcpServers);
     return await this.connection.loadSession({
@@ -11938,9 +12520,11 @@ ${stderr}`
       mcpServers: resolvedMcp
     });
   }
+  /** Trigger agent-managed authentication (e.g., OAuth flow). */
   async authenticate(methodId) {
     await this.connection.authenticate({ methodId });
   }
+  /** Fork an existing session, creating a new branch with shared history. */
   async forkSession(sessionId, cwd, mcpServers) {
     const resolvedMcp = _AgentInstance.mcpManager.resolve(mcpServers);
     return await this.connection.unstable_forkSession({
@@ -11949,10 +12533,25 @@ ${stderr}`
       mcpServers: resolvedMcp
     });
   }
+  /** Close a session on the agent side (cleanup agent-internal state). */
   async closeSession(sessionId) {
     await this.connection.unstable_closeSession({ sessionId });
   }
   // ── Prompt & lifecycle ──────────────────────────────────────────────
+  /**
+   * 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.
+   */
   async prompt(text3, attachments) {
     const contentBlocks = [{ type: "text", text: text3 }];
     const capabilities = this.promptCapabilities ?? {};
@@ -12002,9 +12601,18 @@ ${skipNote}`;
       prompt: contentBlocks
     });
   }
+  /** Cancel the currently running prompt. The agent should stop and return partial results. */
   async cancel() {
     await this.connection.cancel({ sessionId: this.sessionId });
   }
+  /**
+   * 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.
+   */
   async destroy() {
     this._destroying = true;
     this.terminalManager.destroyAll();
@@ -12051,6 +12659,7 @@ var AgentManager = class {
   constructor(catalog) {
     this.catalog = catalog;
   }
+  /** Return definitions for all installed agents. */
   getAvailableAgents() {
     const installed = this.catalog.getInstalledEntries();
     return Object.entries(installed).map(([key, agent]) => ({
@@ -12060,14 +12669,25 @@ var AgentManager = class {
       env: agent.env
     }));
   }
+  /** Look up a single agent definition by its short name (e.g., "claude", "gemini"). */
   getAgent(name) {
     return this.catalog.resolve(name);
   }
+  /**
+   * Spawn a new agent subprocess with a fresh session.
+   *
+   * @throws If the agent is not installed — includes install instructions in the error message.
+   */
   async spawn(agentName, workingDirectory, allowedPaths) {
     const agentDef = this.getAgent(agentName);
     if (!agentDef) throw new Error(`Agent "${agentName}" is not installed. Run "openacp agents install ${agentName}" to add it.`);
     return AgentInstance.spawn(agentDef, workingDirectory, void 0, allowedPaths);
   }
+  /**
+   * Spawn a subprocess and resume an existing agent session.
+   *
+   * Falls back to a new session if the agent cannot restore the given session ID.
+   */
   async resume(agentName, workingDirectory, agentSessionId, allowedPaths) {
     const agentDef = this.getAgent(agentName);
     if (!agentDef) throw new Error(`Agent "${agentName}" is not installed. Run "openacp agents install ${agentName}" to add it.`);
@@ -12089,6 +12709,11 @@ var PromptQueue = class {
   abortController = null;
   /** Set when abort is triggered; drainNext waits for the current processor to settle before starting the next item. */
   processorSettled = null;
+  /**
+   * 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.
+   */
   async enqueue(text3, attachments, routing, turnId) {
     if (this.processing) {
       return new Promise((resolve7) => {
@@ -12097,6 +12722,7 @@ var PromptQueue = class {
     }
     await this.process(text3, attachments, routing, turnId);
   }
+  /** Run a single prompt through the processor, then drain the next queued item. */
   async process(text3, attachments, routing, turnId) {
     this.processing = true;
     this.abortController = new AbortController();
@@ -12124,12 +12750,17 @@ var PromptQueue = class {
       this.drainNext();
     }
   }
+  /** Dequeue and process the next pending prompt, if any. Called after each prompt completes. */
   drainNext() {
     const next = this.queue.shift();
     if (next) {
       this.process(next.text, next.attachments, next.routing, next.turnId).then(next.resolve);
     }
   }
+  /**
+   * Abort the in-flight prompt and discard all queued prompts.
+   * Pending promises are resolved (not rejected) so callers don't see unhandled rejections.
+   */
   clear() {
     if (this.abortController) {
       this.abortController.abort();
@@ -12159,6 +12790,10 @@ var PermissionGate = class {
   constructor(timeoutMs) {
     this.timeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS;
   }
+  /**
+   * 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) {
     if (!this.settled && this.rejectFn) {
       this.rejectFn(new Error("Superseded by new permission request"));
@@ -12177,6 +12812,7 @@ var PermissionGate = class {
       }
     });
   }
+  /** Approve the pending request with the given option ID. No-op if already settled. */
   resolve(optionId) {
     if (this.settled || !this.resolveFn) return;
     this.settled = true;
@@ -12184,6 +12820,7 @@ var PermissionGate = class {
     this.resolveFn(optionId);
     this.cleanup();
   }
+  /** Deny the pending request. No-op if already settled. */
   reject(reason) {
     if (this.settled || !this.rejectFn) return;
     this.settled = true;
@@ -12277,6 +12914,8 @@ var Session = class extends TypedEmitter {
   get agentInstance() {
     return this._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) {
     this._agentInstance = agent;
     this.wireAgentRelay();
@@ -12379,7 +13018,7 @@ var Session = class extends TypedEmitter {
     this.transition("finished");
     this.emit(SessionEv.SESSION_END, reason ?? "completed");
   }
-  /** Transition to cancelled — from active only (terminal session cancel) */
+  /** Transition to cancelled — from active or error (terminal session cancel) */
   markCancelled() {
     this.transition("cancelled");
   }
@@ -12399,19 +13038,29 @@ var Session = class extends TypedEmitter {
   get queueDepth() {
     return this.queue.pending;
   }
+  /** Whether a prompt is currently being processed by the agent */
   get promptRunning() {
     return this.queue.isProcessing;
   }
   // --- Context Injection ---
+  /** Store context markdown to be prepended to the next prompt (used for session resume with history). */
   setContext(markdown) {
     this.pendingContext = markdown;
   }
   // --- Voice Mode ---
+  /** Set TTS mode: "off" = disabled, "next" = one-shot (auto-resets after prompt), "on" = persistent. */
   setVoiceMode(mode) {
     this.voiceMode = mode;
     this.log.info({ voiceMode: mode }, "TTS mode changed");
   }
   // --- Public API ---
+  /**
+   * 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.
+   */
   async enqueuePrompt(text3, attachments, routing, externalTurnId) {
     const turnId = externalTurnId ?? nanoid2(8);
     if (this.middlewareChain) {
@@ -12521,6 +13170,10 @@ ${text3}`;
       await this.autoName();
     }
   }
+  /**
+   * 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.
+   */
   async maybeTranscribeAudio(text3, attachments) {
     if (!attachments?.length || !this.speechService) {
       return { text: text3, attachments };
@@ -12566,6 +13219,7 @@ ${result.text}` : result.text;
       attachments: remainingAttachments.length > 0 ? remainingAttachments : void 0
     };
   }
+  /** Extract [TTS] block from agent response, synthesize speech, and emit audio_content event. */
   async processTTSResponse(responseText) {
     const match = TTS_BLOCK_REGEX.exec(responseText);
     if (!match?.[1]) {
@@ -12602,7 +13256,9 @@ ${result.text}` : result.text;
       this.log.warn({ err }, "TTS synthesis failed, skipping");
     }
   }
-  // NOTE: This injects a summary prompt into the agent's conversation history.
+  // Sends a special prompt to the agent to generate a short session title.
+  // The session emitter is paused (excluding non-agent_event emissions) so the naming
+  // prompt's output is intercepted by a capture handler instead of being forwarded to adapters.
   async autoName() {
     let title = "";
     const captureHandler = (event) => {
@@ -12761,6 +13417,7 @@ ${result.text}` : result.text;
     this.applySpawnResponse(newAgent.initialSessionResponse, newAgent.agentCapabilities);
     this.log.info({ from: this.agentSwitchHistory.at(-1).agentName, to: agentName }, "Agent switched");
   }
+  /** Tear down the session: reject pending permissions, clear queue, destroy agent subprocess. */
   async destroy() {
     this.log.info("Session destroyed");
     if (this.permissionGate.isPending) {
@@ -13055,6 +13712,12 @@ var MessageTransformer = class {
   constructor(tunnelService) {
     this.tunnelService = tunnelService;
   }
+  /**
+   * 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, sessionContext) {
     switch (event.type) {
       case "text":
@@ -13285,12 +13948,17 @@ var SessionManager = class {
   store;
   eventBus;
   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) {
     this.eventBus = eventBus;
   }
   constructor(store = null) {
     this.store = store;
   }
+  /** Create a new session by spawning an agent and persisting the initial record. */
   async createSession(channelId, agentName, workingDirectory, agentManager) {
     const agentInstance = await agentManager.spawn(agentName, workingDirectory);
     const session = new Session({
@@ -13318,9 +13986,11 @@ var SessionManager = class {
     }
     return session;
   }
+  /** Look up a live session by its OpenACP session ID. */
   getSession(sessionId) {
     return this.sessions.get(sessionId);
   }
+  /** Look up a live session by adapter channel and thread ID (checks per-adapter threadIds map first, then legacy fields). */
   getSessionByThread(channelId, threadId) {
     for (const session of this.sessions.values()) {
       const adapterThread = session.threadIds.get(channelId);
@@ -13331,6 +14001,7 @@ var SessionManager = class {
     }
     return void 0;
   }
+  /** Look up a live session by the agent's internal session ID (assigned by the ACP subprocess). */
   getSessionByAgentSessionId(agentSessionId) {
     for (const session of this.sessions.values()) {
       if (session.agentSessionId === agentSessionId) {
@@ -13339,18 +14010,26 @@ var SessionManager = class {
     }
     return void 0;
   }
+  /** Look up the persisted SessionRecord by the agent's internal session ID. */
   getRecordByAgentSessionId(agentSessionId) {
     return this.store?.findByAgentSessionId(agentSessionId);
   }
+  /** Look up the persisted SessionRecord by channel and thread ID. */
   getRecordByThread(channelId, threadId) {
     return this.store?.findByPlatform(
       channelId,
       (p) => String(p.topicId) === threadId || p.threadId === threadId
     );
   }
+  /** Register a session that was created externally (e.g. restored from store on startup). */
   registerSession(session) {
     this.sessions.set(session.id, session);
   }
+  /**
+   * 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.
+   */
   async patchRecord(sessionId, patch, options) {
     if (!this.store) return;
     const record = this.store.get(sessionId);
@@ -13363,9 +14042,11 @@ var SessionManager = class {
       this.store.flush();
     }
   }
+  /** Retrieve the persisted SessionRecord for a given session ID. Returns undefined if no store or record not found. */
   getSessionRecord(sessionId) {
     return this.store?.get(sessionId);
   }
+  /** Cancel a session: abort in-flight prompt, transition to cancelled, destroy agent, and persist. */
   async cancelSession(sessionId) {
     const session = this.sessions.get(sessionId);
     if (session) {
@@ -13388,11 +14069,16 @@ var SessionManager = class {
       });
     }
   }
+  /** List live (in-memory) sessions, optionally filtered by channel. Excludes assistant sessions. */
   listSessions(channelId) {
     const all = Array.from(this.sessions.values()).filter((s) => !s.isAssistant);
     if (channelId) return all.filter((s) => s.channelId === channelId);
     return all;
   }
+  /**
+   * List all sessions (live + stored) as SessionSummary. Live sessions take precedence
+   * over stored records — their real-time state (queueDepth, promptRunning) is used.
+   */
   listAllSessions(channelId) {
     if (this.store) {
       let records = this.store.list().filter((r) => !r.isAssistant);
@@ -13454,6 +14140,7 @@ var SessionManager = class {
       isLive: true
     }));
   }
+  /** List all stored SessionRecords, optionally filtered by status. Excludes assistant sessions. */
   listRecords(filter) {
     if (!this.store) return [];
     let records = this.store.list().filter((r) => !r.isAssistant);
@@ -13462,6 +14149,7 @@ var SessionManager = class {
     }
     return records;
   }
+  /** Remove a session's stored record and emit a SESSION_DELETED event. */
   async removeRecord(sessionId) {
     if (!this.store) return;
     await this.store.remove(sessionId);
@@ -13565,7 +14253,10 @@ var SessionBridge = class {
       log6.error({ err, sessionId }, "Error in sendMessage middleware");
     }
   }
-  /** 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) {
     if (isSystemEvent(event)) return true;
     const ctx = this.session.activeTurnContext;
@@ -13574,6 +14265,13 @@ var SessionBridge = class {
     if (target === null) return false;
     return this.adapterId === target;
   }
+  /**
+   * 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() {
     if (this.connected) return;
     this.connected = true;
@@ -13650,6 +14348,7 @@ var SessionBridge = class {
       this.session.emit(SessionEv.AGENT_EVENT, { type: "config_option_update", options: this.session.configOptions });
     }
   }
+  /** Unsubscribe all session event listeners and clean up adapter state. */
   disconnect() {
     if (!this.connected) return;
     this.connected = false;
@@ -13922,6 +14621,10 @@ var SessionFactory = class {
   get speechService() {
     return typeof this.speechServiceAccessor === "function" ? this.speechServiceAccessor() : this.speechServiceAccessor;
   }
+  /**
+   * Create a new Session: spawn agent → create Session instance → hydrate ACP state → register.
+   * Runs session:beforeCreate middleware (which can modify params or block creation).
+   */
   async create(params) {
     let createParams = params;
     if (this.middlewareChain) {
@@ -14105,6 +14808,11 @@ var SessionFactory = class {
     this.resumeLocks.set(sessionId, resumePromise);
     return resumePromise;
   }
+  /**
+   * 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.
+   */
   async lazyResume(channelId, threadId) {
     const store = this.sessionStore;
     if (!store || !this.createFullSession) return null;
@@ -14208,6 +14916,7 @@ var SessionFactory = class {
     this.resumeLocks.set(lockKey, resumePromise);
     return resumePromise;
   }
+  /** Create a brand-new session, resolving agent name and workspace from config if not provided. */
   async handleNewSession(channelId, agentName, workspacePath, options) {
     if (!this.configManager || !this.agentCatalog || !this.createFullSession) {
       throw new Error("SessionFactory not fully initialized");
@@ -14252,6 +14961,7 @@ var SessionFactory = class {
       record.workingDir
     );
   }
+  /** Create a session and inject conversation context from a ContextProvider (e.g., history from a previous session). */
   async createSessionWithContext(params) {
     if (!this.createFullSession) throw new Error("SessionFactory not fully initialized");
     let contextResult = null;
@@ -14278,6 +14988,7 @@ var SessionFactory = class {
     }
     return { session, contextResult };
   }
+  /** Wire session-level side effects: usage tracking (via EventBus) and tunnel cleanup on session end. */
   wireSideEffects(session, deps) {
     session.on(SessionEv.AGENT_EVENT, (event) => {
       if (event.type !== "usage") return;
@@ -14358,6 +15069,11 @@ var JsonFileSessionStore = class {
     }
     return void 0;
   }
+  /**
+   * Find a session by its ACP agent session ID.
+   * Checks current, original, and historical agent session IDs (from agent switches)
+   * since the agent session ID changes on each switch.
+   */
   findByAgentSessionId(agentSessionId) {
     for (const record of this.records.values()) {
       if (record.agentSessionId === agentSessionId || record.originalAgentSessionId === agentSessionId) {
@@ -14402,6 +15118,7 @@ var JsonFileSessionStore = class {
     if (!fs9.existsSync(dir)) fs9.mkdirSync(dir, { recursive: true });
     fs9.writeFileSync(this.filePath, JSON.stringify(data, null, 2));
   }
+  /** Clean up timers and process listeners. Call on shutdown to prevent leaks. */
   destroy() {
     if (this.debounceTimer) clearTimeout(this.debounceTimer);
     if (this.cleanupInterval) clearInterval(this.cleanupInterval);
@@ -14437,7 +15154,11 @@ var JsonFileSessionStore = class {
       }
     }
   }
-  /** Migrate old SessionRecord format to new multi-adapter format. */
+  /**
+   * Migrate old SessionRecord format to new multi-adapter format.
+   * Converts single-adapter `platform` field to per-adapter `platforms` map,
+   * and initializes `attachedAdapters` for records created before multi-adapter support.
+   */
   migrateRecord(record) {
     if (!record.platforms && record.platform && typeof record.platform === "object") {
       const platformData = record.platform;
@@ -14450,6 +15171,7 @@ var JsonFileSessionStore = class {
     }
     return record;
   }
+  /** Remove expired session records (past TTL). Active and assistant sessions are preserved. */
   cleanup() {
     const cutoff = Date.now() - this.ttlDays * 24 * 60 * 60 * 1e3;
     let removed = 0;
@@ -14492,7 +15214,12 @@ var AgentSwitchHandler = class {
   constructor(deps) {
     this.deps = deps;
   }
+  /** Prevents concurrent switch operations on the same session */
   switchingLocks = /* @__PURE__ */ new Set();
+  /**
+   * Switch a session to a different agent. Returns whether the previous
+   * agent session was resumed or a new one was spawned.
+   */
   async switch(sessionId, toAgent) {
     if (this.switchingLocks.has(sessionId)) {
       throw new Error("Switch already in progress");
@@ -14677,20 +15404,29 @@ var REGISTRY_URL = "https://cdn.agentclientprotocol.com/registry/v1/latest/regis
 var DEFAULT_TTL_HOURS = 24;
 var AgentCatalog = class {
   store;
+  /** Agents available in the remote registry (cached in memory after load). */
   registryAgents = [];
   cachePath;
+  /** Directory where binary agent archives are extracted to. */
   agentsDir;
   constructor(store, cachePath, agentsDir) {
     this.store = store;
     this.cachePath = cachePath;
     this.agentsDir = agentsDir;
   }
+  /**
+   * 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() {
     this.store.load();
     this.loadRegistryFromCacheOrSnapshot();
     this.enrichInstalledFromRegistry();
   }
   // --- Registry ---
+  /** Fetch the latest agent registry from the CDN and update the local cache. */
   async fetchRegistry() {
     try {
       log11.info("Fetching agent registry from CDN...");
@@ -14710,6 +15446,7 @@ var AgentCatalog = class {
       log11.warn({ err }, "Failed to fetch registry, using cached data");
     }
   }
+  /** Re-fetch registry only if the local cache has expired (24-hour TTL). */
   async refreshRegistryIfStale() {
     if (this.isCacheStale()) {
       await this.fetchRegistry();
@@ -14721,6 +15458,7 @@ var AgentCatalog = class {
   getRegistryAgent(registryId) {
     return this.registryAgents.find((a) => a.id === registryId);
   }
+  /** Find a registry agent by registry ID or by its short alias (e.g., "claude"). */
   findRegistryAgent(keyOrId) {
     const byId = this.registryAgents.find((a) => a.id === keyOrId);
     if (byId) return byId;
@@ -14737,6 +15475,15 @@ var AgentCatalog = class {
     return this.store.getAgent(key);
   }
   // --- Discovery ---
+  /**
+   * 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() {
     const installed = this.getInstalledEntries();
     const items = [];
@@ -14777,6 +15524,7 @@ var AgentCatalog = class {
     }
     return items;
   }
+  /** Check if an agent can be installed on this system (platform + dependencies). */
   checkAvailability(keyOrId) {
     const agent = this.findRegistryAgent(keyOrId);
     if (!agent) return { available: false, reason: "Not found in the agent registry." };
@@ -14787,6 +15535,12 @@ var AgentCatalog = class {
     return checkDependencies(agent.id);
   }
   // --- Install/Uninstall ---
+  /**
+   * 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.
+   */
   async install(keyOrId, progress, force) {
     const agent = this.findRegistryAgent(keyOrId);
     if (!agent) {
@@ -14811,6 +15565,7 @@ var AgentCatalog = class {
   registerFallbackAgent(key, data) {
     this.store.addAgent(key, data);
   }
+  /** Remove an installed agent and delete its binary directory if applicable. */
   async uninstall(key) {
     if (this.store.hasAgent(key)) {
       await uninstallAgent(key, this.store);
@@ -14819,6 +15574,7 @@ var AgentCatalog = class {
     return { ok: false, error: `"${key}" is not installed.` };
   }
   // --- Resolution (for AgentManager) ---
+  /** Convert an installed agent's short key to an AgentDefinition for spawning. */
   resolve(key) {
     const agent = this.store.getAgent(key);
     if (!agent) return void 0;
@@ -14968,6 +15724,7 @@ var AgentStore = class {
   constructor(filePath) {
     this.filePath = filePath;
   }
+  /** Load and validate the store from disk. Starts fresh if file is missing or invalid. */
   load() {
     if (!fs13.existsSync(this.filePath)) {
       this.data = { version: 1, installed: {} };
@@ -15007,6 +15764,11 @@ var AgentStore = class {
   hasAgent(key) {
     return key in this.data.installed;
   }
+  /**
+   * 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.
+   */
   save() {
     fs13.mkdirSync(path12.dirname(this.filePath), { recursive: true });
     const tmpPath = this.filePath + ".tmp";
@@ -15086,6 +15848,10 @@ function resolveLoadOrder(plugins) {
 // src/core/plugin/service-registry.ts
 var ServiceRegistry = class {
   services = /* @__PURE__ */ new Map();
+  /**
+   * Register a service. Throws if the service name is already taken.
+   * Use `registerOverride` to intentionally replace an existing service.
+   */
   register(name, implementation, pluginName) {
     if (this.services.has(name)) {
       const existing = this.services.get(name);
@@ -15093,21 +15859,27 @@ var ServiceRegistry = class {
     }
     this.services.set(name, { implementation, pluginName });
   }
+  /** Register a service, replacing any existing registration (used by override plugins). */
   registerOverride(name, implementation, pluginName) {
     this.services.set(name, { implementation, pluginName });
   }
+  /** Retrieve a service by name. Returns undefined if not registered. */
   get(name) {
     return this.services.get(name)?.implementation;
   }
+  /** Check whether a service is registered. */
   has(name) {
     return this.services.has(name);
   }
+  /** List all registered services with their owning plugin names. */
   list() {
     return [...this.services.entries()].map(([name, { pluginName }]) => ({ name, pluginName }));
   }
+  /** Remove a single service by name. */
   unregister(name) {
     this.services.delete(name);
   }
+  /** Remove all services owned by a specific plugin (called during plugin unload). */
   unregisterByPlugin(pluginName) {
     for (const [name, entry] of this.services) {
       if (entry.pluginName === pluginName) {
@@ -15123,6 +15895,7 @@ var MiddlewareChain = class {
   chains = /* @__PURE__ */ new Map();
   errorHandler;
   errorTracker;
+  /** Register a middleware handler for a hook. Handlers are kept sorted by priority. */
   add(hook, pluginName, opts) {
     const entry = {
       pluginName,
@@ -15137,6 +15910,15 @@ var MiddlewareChain = class {
       this.chains.set(hook, [entry]);
     }
   }
+  /**
+   * 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.
+   */
   async execute(hook, payload, coreHandler) {
     const handlers = this.chains.get(hook);
     if (!handlers || handlers.length === 0) {
@@ -15206,6 +15988,7 @@ var MiddlewareChain = class {
     const start = buildNext(0, payload);
     return start();
   }
+  /** Remove all middleware handlers registered by a specific plugin. */
   removeAll(pluginName) {
     for (const [hook, handlers] of this.chains.entries()) {
       const filtered = handlers.filter((h) => h.pluginName !== pluginName);
@@ -15216,9 +15999,11 @@ var MiddlewareChain = class {
       }
     }
   }
+  /** Set a callback for middleware errors (e.g., logging). */
   setErrorHandler(fn) {
     this.errorHandler = fn;
   }
+  /** Attach an ErrorTracker for circuit-breaking misbehaving plugins. */
   setErrorTracker(tracker) {
     this.errorTracker = tracker;
   }
@@ -15230,10 +16015,15 @@ var ErrorTracker = class {
   disabled = /* @__PURE__ */ new Set();
   exempt = /* @__PURE__ */ new Set();
   config;
+  /** Callback fired when a plugin is auto-disabled due to error budget exhaustion. */
   onDisabled;
   constructor(config) {
     this.config = { maxErrors: config?.maxErrors ?? 10, windowMs: config?.windowMs ?? 36e5 };
   }
+  /**
+   * Record an error for a plugin. If the error budget is exceeded,
+   * the plugin is disabled and the `onDisabled` callback fires.
+   */
   increment(pluginName) {
     if (this.exempt.has(pluginName)) return;
     const now = Date.now();
@@ -15250,13 +16040,16 @@ var ErrorTracker = class {
       this.onDisabled?.(pluginName, reason);
     }
   }
+  /** Check if a plugin has been disabled due to errors. */
   isDisabled(pluginName) {
     return this.disabled.has(pluginName);
   }
+  /** Re-enable a plugin and clear its error history. */
   reset(pluginName) {
     this.disabled.delete(pluginName);
     this.errors.delete(pluginName);
   }
+  /** Mark a plugin as exempt from circuit-breaking (e.g., essential plugins). */
   setExempt(pluginName) {
     this.exempt.add(pluginName);
   }
@@ -15268,6 +16061,7 @@ import path13 from "path";
 var PluginStorageImpl = class {
   kvPath;
   dataDir;
+  /** Serializes writes to prevent concurrent file corruption */
   writeChain = Promise.resolve();
   constructor(baseDir) {
     this.dataDir = path13.join(baseDir, "data");
@@ -15308,6 +16102,7 @@ var PluginStorageImpl = class {
   async list() {
     return Object.keys(this.readKv());
   }
+  /** Returns the plugin's data directory, creating it lazily on first access. */
   getDataDir() {
     fs14.mkdirSync(this.dataDir, { recursive: true });
     return this.dataDir;
@@ -15481,6 +16276,11 @@ function createPluginContext(opts) {
       return core;
     },
     instanceRoot,
+    /**
+     * Called by LifecycleManager during plugin teardown.
+     * Unregisters all event handlers, middleware, commands, and services
+     * registered by this plugin, preventing leaks across reloads.
+     */
     cleanup() {
       for (const { event, handler } of registeredListeners) {
         eventBus.off(event, handler);
@@ -15572,12 +16372,15 @@ var LifecycleManager = class {
   loadOrder = [];
   _loaded = /* @__PURE__ */ new Set();
   _failed = /* @__PURE__ */ new Set();
+  /** Names of plugins that successfully completed setup(). */
   get loadedPlugins() {
     return [...this._loaded];
   }
+  /** Names of plugins whose setup() threw an error. These plugins are skipped but don't crash the system. */
   get failedPlugins() {
     return [...this._failed];
   }
+  /** The PluginRegistry tracking installed and enabled plugin state. */
   get registry() {
     return this.pluginRegistry;
   }
@@ -15624,6 +16427,12 @@ var LifecycleManager = class {
       return this;
     } };
   }
+  /**
+   * 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.
+   */
   async boot(plugins) {
     const newNames = new Set(plugins.map((p) => p.name));
     const allForResolution = [...this.loadOrder.filter((p) => !newNames.has(p.name)), ...plugins];
@@ -15735,6 +16544,11 @@ var LifecycleManager = class {
       }
     }
   }
+  /**
+   * 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.
+   */
   async unloadPlugin(name) {
     if (!this._loaded.has(name)) return;
     const plugin = this.loadOrder.find((p) => p.name === name);
@@ -15754,6 +16568,10 @@ var LifecycleManager = class {
     this.loadOrder = this.loadOrder.filter((p) => p.name !== name);
     this.eventBus?.emit(BusEvent.PLUGIN_UNLOADED, { name });
   }
+  /**
+   * Gracefully shut down all loaded plugins.
+   * Teardown runs in reverse boot order so that dependencies outlive their dependents.
+   */
   async shutdown() {
     const reversed = [...this.loadOrder].reverse();
     for (const plugin of reversed) {
@@ -15781,16 +16599,19 @@ init_log();
 var log13 = createChildLogger({ module: "menu-registry" });
 var MenuRegistry = class {
   items = /* @__PURE__ */ new Map();
+  /** Register or replace a menu item by its unique ID. */
   register(item) {
     this.items.set(item.id, item);
   }
+  /** Remove a menu item by ID. */
   unregister(id) {
     this.items.delete(id);
   }
+  /** Look up a single menu item by ID. */
   getItem(id) {
     return this.items.get(id);
   }
-  /** Get all visible items sorted by priority */
+  /** Get all visible items sorted by priority (lower number = shown first). */
   getItems() {
     return [...this.items.values()].filter((item) => {
       if (!item.visible) return true;
@@ -15869,19 +16690,31 @@ var log14 = createChildLogger({ module: "assistant-registry" });
 var AssistantRegistry = class {
   sections = /* @__PURE__ */ new Map();
   _instanceRoot = "";
-  /** Set the instance root path used in assistant guidelines */
+  /** Set the instance root path used in assistant guidelines. */
   setInstanceRoot(root) {
     this._instanceRoot = root;
   }
+  /** Register a prompt section. Overwrites any existing section with the same id. */
   register(section) {
     if (this.sections.has(section.id)) {
       log14.warn({ id: section.id }, "Assistant section overwritten");
     }
     this.sections.set(section.id, section);
   }
+  /** Remove a previously registered section by id. */
   unregister(id) {
     this.sections.delete(id);
   }
+  /**
+   * 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) {
     const sorted = [...this.sections.values()].sort((a, b) => a.priority - b.priority);
     const parts = [ASSISTANT_PREAMBLE];
@@ -15918,6 +16751,13 @@ var AssistantManager = class {
   }
   sessions = /* @__PURE__ */ new Map();
   pendingSystemPrompts = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
   async getOrSpawn(channelId, threadId) {
     const existing = this.core.sessionStore?.findAssistant(channelId);
     const session = await this.core.createSession({
@@ -15938,6 +16778,7 @@ var AssistantManager = class {
     );
     return session;
   }
+  /** Returns the active assistant session for a channel, or null if none exists. */
   get(channelId) {
     return this.sessions.get(channelId) ?? null;
   }
@@ -15950,6 +16791,7 @@ var AssistantManager = class {
     if (prompt) this.pendingSystemPrompts.delete(channelId);
     return prompt;
   }
+  /** Checks whether a given session ID belongs to the built-in assistant. */
   isAssistant(sessionId) {
     for (const s of this.sessions.values()) {
       if (s.id === sessionId) return true;
@@ -16176,30 +17018,49 @@ var OpenACPCore = class {
   menuRegistry = new MenuRegistry();
   assistantRegistry = new AssistantRegistry();
   assistantManager;
-  // --- Lazy getters: resolve from ServiceRegistry (populated by plugins during boot) ---
+  // Services (security, notifications, speech, etc.) are provided by plugins that
+  // register during boot. Core accesses them lazily via ServiceRegistry so it doesn't
+  // need compile-time dependencies on plugin implementations.
+  /** @throws if the service hasn't been registered by its plugin yet */
   getService(name) {
     const svc = this.lifecycleManager.serviceRegistry.get(name);
     if (!svc) throw new Error(`Service '${name}' not registered \u2014 is the ${name} plugin loaded?`);
     return svc;
   }
+  /** Access control and rate-limiting guard (provided by security plugin). */
   get securityGuard() {
     return this.getService("security");
   }
+  /** Cross-session notification delivery (provided by notifications plugin). */
   get notificationManager() {
     return this.getService("notifications");
   }
+  /** File I/O service for agent attachment storage (provided by file-service plugin). */
   get fileService() {
     return this.getService("file-service");
   }
+  /** Text-to-speech / speech-to-text engine (provided by speech plugin). */
   get speechService() {
     return this.getService("speech");
   }
+  /** Conversation history builder for context injection (provided by context plugin). */
   get contextManager() {
     return this.getService("context");
   }
+  /** Per-plugin persistent settings (e.g. API keys). */
   get settingsManager() {
     return this.lifecycleManager.settingsManager;
   }
+  /**
+   * 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, ctx) {
     this.configManager = configManager;
     this.instanceContext = ctx;
@@ -16310,16 +17171,28 @@ var OpenACPCore = class {
     this.lifecycleManager.serviceRegistry.register("menu-registry", this.menuRegistry, "core");
     this.lifecycleManager.serviceRegistry.register("assistant-registry", this.assistantRegistry, "core");
   }
+  /** Optional tunnel for generating public URLs (code viewer links, etc.). */
   get tunnelService() {
     return this._tunnelService;
   }
+  /** Propagate tunnel service to MessageTransformer so it can generate viewer links. */
   set tunnelService(service) {
     this._tunnelService = service;
     this.messageTransformer.tunnelService = service;
   }
+  /**
+   * 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, adapter) {
     this.adapters.set(name, adapter);
   }
+  /**
+   * Start all registered adapters. Adapters that fail are logged but do not
+   * prevent others from starting. Throws only if ALL adapters fail.
+   */
   async start() {
     this.agentCatalog.refreshRegistryIfStale().catch((err) => {
       log16.warn({ err }, "Background registry refresh failed");
@@ -16339,6 +17212,10 @@ var OpenACPCore = class {
       );
     }
   }
+  /**
+   * Graceful shutdown: notify users, persist session state, stop adapters.
+   * Agent subprocesses are not explicitly killed — they exit with the parent process.
+   */
   async stop() {
     try {
       const nm = this.lifecycleManager.serviceRegistry.get("notifications");
@@ -16357,6 +17234,13 @@ var OpenACPCore = class {
     }
   }
   // --- Archive ---
+  /**
+   * 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).
+   */
   async archiveSession(sessionId) {
     const session = this.sessionManager.getSession(sessionId);
     if (!session) return { ok: false, error: "Session not found (must be in memory)" };
@@ -16376,6 +17260,18 @@ var OpenACPCore = class {
     }
   }
   // --- Message Routing ---
+  /**
+   * 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.
+   */
   async handleMessage(message) {
     log16.debug(
       {
@@ -16457,6 +17353,17 @@ ${text3}`;
     }
   }
   // --- Unified Session Creation Pipeline ---
+  /**
+   * 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
+   */
   async createSession(params) {
     const session = await this.sessionFactory.create(params);
     if (params.threadId) {
@@ -16579,9 +17486,16 @@ ${text3}`;
     );
     return session;
   }
+  /** Convenience wrapper: create a new session with default agent/workspace resolution. */
   async handleNewSession(channelId, agentName, workspacePath, options) {
     return this.sessionFactory.handleNewSession(channelId, agentName, workspacePath, options);
   }
+  /**
+   * 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.
+   */
   async adoptSession(agentName, agentSessionId, cwd, channelId) {
     const caps = getAgentCapabilities(agentName);
     if (!caps.supportsResume) {
@@ -16692,22 +17606,33 @@ ${text3}`;
       status: "adopted"
     };
   }
+  /** Start a new chat within the same agent and workspace as the current session's thread. */
   async handleNewChat(channelId, currentThreadId) {
     return this.sessionFactory.handleNewChat(channelId, currentThreadId);
   }
+  /** Create a session and inject conversation context from a prior session or repo. */
   async createSessionWithContext(params) {
     return this.sessionFactory.createSessionWithContext(params);
   }
   // --- Agent Switch ---
+  /** Switch a session's active agent. Delegates to AgentSwitchHandler for state coordination. */
   async switchSessionAgent(sessionId, toAgent) {
     return this.agentSwitchHandler.switch(sessionId, toAgent);
   }
+  /** Find a session by channel+thread, resuming from disk if not in memory. */
   async getOrResumeSession(channelId, threadId) {
     return this.sessionFactory.getOrResume(channelId, threadId);
   }
+  /** Find a session by ID, resuming from disk if not in memory. */
   async getOrResumeSessionById(sessionId) {
     return this.sessionFactory.getOrResumeById(sessionId);
   }
+  /**
+   * 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.
+   */
   async attachAdapter(sessionId, adapterId) {
     const session = this.sessionManager.getSession(sessionId);
     if (!session) throw new Error(`Session ${sessionId} not found`);
@@ -16731,6 +17656,10 @@ ${text3}`;
     });
     return { threadId };
   }
+  /**
+   * Detach a secondary adapter from a session. The primary adapter (channelId) cannot
+   * be detached. Disconnects the bridge and cleans up thread mappings.
+   */
   async detachAdapter(sessionId, adapterId) {
     const session = this.sessionManager.getSession(sessionId);
     if (!session) throw new Error(`Session ${sessionId} not found`);
@@ -16763,6 +17692,7 @@ ${text3}`;
       platforms: this.buildPlatformsFromSession(session)
     });
   }
+  /** Build the platforms map (adapter → thread/topic IDs) for persistence. */
   buildPlatformsFromSession(session) {
     const platforms = {};
     for (const [adapterId, threadId] of session.threadIds) {
@@ -16794,8 +17724,13 @@ ${text3}`;
     const bridge = this.createBridge(session, adapter, session.channelId);
     bridge.connect();
   }
-  /** 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, adapter, adapterId) {
     const id = adapterId ?? adapter.name;
     const key = this.bridgeKey(id, session.id);
@@ -16899,10 +17834,15 @@ var CommandRegistry = class _CommandRegistry {
     return this.getAll().filter((cmd) => cmd.category === category);
   }
   /**
-   * 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).
    */
   async execute(commandString, baseArgs) {
     const trimmed = commandString.trim();
@@ -18007,6 +18947,10 @@ var TopicManager = class {
     this.adapter = adapter;
     this.systemTopicIds = systemTopicIds;
   }
+  /**
+   * List user-facing session topics, excluding system topics.
+   * Optionally filtered to specific status values.
+   */
   listTopics(filter) {
     const records = this.sessionManager.listRecords(filter);
     return records.filter((r) => !this.isSystemTopic(r)).filter((r) => !filter?.statuses?.length || filter.statuses.includes(r.status)).map((r) => ({
@@ -18018,6 +18962,12 @@ var TopicManager = class {
       lastActiveAt: r.lastActiveAt
     }));
   }
+  /**
+   * 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.
+   */
   async deleteTopic(sessionId, options) {
     const records = this.sessionManager.listRecords();
     const record = records.find((r) => r.sessionId === sessionId);
@@ -18045,6 +18995,10 @@ var TopicManager = class {
     await this.sessionManager.removeRecord(sessionId);
     return { ok: true, topicId };
   }
+  /**
+   * Bulk-delete topics by status (default: finished, error, cancelled).
+   * Active/initializing sessions are cancelled before deletion to prevent orphaned processes.
+   */
   async cleanup(statuses) {
     const targetStatuses = statuses?.length ? statuses : ["finished", "error", "cancelled"];
     const records = this.sessionManager.listRecords({ statuses: targetStatuses });
@@ -18102,6 +19056,7 @@ var StreamAdapter = class {
       ...config
     };
   }
+  /** Wraps the outgoing message as a StreamEvent and emits it to the session's listeners. */
   async sendMessage(sessionId, content) {
     await this.emit(sessionId, {
       type: content.type,
@@ -18110,6 +19065,7 @@ var StreamAdapter = class {
       timestamp: Date.now()
     });
   }
+  /** Emits a permission request event so the client can render approve/deny UI. */
   async sendPermissionRequest(sessionId, request) {
     await this.emit(sessionId, {
       type: "permission_request",
@@ -18118,6 +19074,7 @@ var StreamAdapter = class {
       timestamp: Date.now()
     });
   }
+  /** Broadcasts a notification to all connected clients (not scoped to a session). */
   async sendNotification(notification) {
     await this.broadcast({
       type: "notification",
@@ -18125,9 +19082,14 @@ var StreamAdapter = class {
       timestamp: Date.now()
     });
   }
+  /**
+   * No-op for stream adapters — threads are a platform concept (Telegram topics, Slack threads).
+   * Stream clients manage their own session UI.
+   */
   async createSessionThread(_sessionId, _name) {
     return "";
   }
+  /** Emits a rename event so connected clients can update their session title. */
   async renameSessionThread(sessionId, name) {
     await this.emit(sessionId, {
       type: "session_rename",
@@ -18152,20 +19114,27 @@ var Draft = class {
   }
   buffer = "";
   _messageId;
+  /** Guards against concurrent first-flush — ensures only one sendMessage creates the draft. */
   firstFlushPending = false;
   flushTimer;
   flushPromise = Promise.resolve();
   get isEmpty() {
     return !this.buffer;
   }
+  /** Platform message ID, set after the first successful flush. */
   get messageId() {
     return this._messageId;
   }
+  /** Appends streaming text to the buffer and schedules a flush. */
   append(text3) {
     if (!text3) return;
     this.buffer += text3;
     this.scheduleFlush();
   }
+  /**
+   * Flushes any remaining buffered text and returns the platform message ID.
+   * Called when the streaming response completes.
+   */
   async finalize() {
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
@@ -18177,6 +19146,7 @@ var Draft = class {
     }
     return this._messageId;
   }
+  /** Discards buffered text and cancels any pending flush. */
   destroy() {
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
@@ -18219,6 +19189,7 @@ var DraftManager = class {
     this.config = config;
   }
   drafts = /* @__PURE__ */ new Map();
+  /** Returns the existing draft for a session, or creates a new one. */
   getOrCreate(sessionId) {
     let draft = this.drafts.get(sessionId);
     if (!draft) {
@@ -18227,15 +19198,18 @@ var DraftManager = class {
     }
     return draft;
   }
+  /** Finalizes and removes the draft for a session. */
   async finalize(sessionId) {
     const draft = this.drafts.get(sessionId);
     if (!draft) return;
     await draft.finalize();
     this.drafts.delete(sessionId);
   }
+  /** Finalizes all active drafts (e.g., during adapter shutdown). */
   async finalizeAll() {
     await Promise.all([...this.drafts.values()].map((d) => d.finalize()));
   }
+  /** Destroys a draft without flushing (e.g., on session error). */
   destroy(sessionId) {
     const draft = this.drafts.get(sessionId);
     if (draft) {
@@ -18243,6 +19217,7 @@ var DraftManager = class {
       this.drafts.delete(sessionId);
     }
   }
+  /** Destroys all drafts without flushing. */
   destroyAll() {
     for (const draft of this.drafts.values()) {
       draft.destroy();
@@ -18254,12 +19229,14 @@ var DraftManager = class {
 // src/core/adapter-primitives/primitives/tool-call-tracker.ts
 var ToolCallTracker = class {
   sessions = /* @__PURE__ */ new Map();
+  /** Registers a new tool call and associates it with its platform message ID. */
   track(sessionId, meta, messageId) {
     if (!this.sessions.has(sessionId)) {
       this.sessions.set(sessionId, /* @__PURE__ */ new Map());
     }
     this.sessions.get(sessionId).set(meta.id, { ...meta, messageId });
   }
+  /** Updates a tracked tool call's status and optional metadata. Returns null if not found. */
   update(sessionId, toolId, status, patch) {
     const tool = this.sessions.get(sessionId)?.get(toolId);
     if (!tool) return null;
@@ -18270,10 +19247,12 @@ var ToolCallTracker = class {
     if (patch?.kind) tool.kind = patch.kind;
     return tool;
   }
+  /** Returns all tracked tool calls for a session (regardless of status). */
   getActive(sessionId) {
     const session = this.sessions.get(sessionId);
     return session ? [...session.values()] : [];
   }
+  /** Removes all tracked tool calls for a session (called at turn end). */
   clear(sessionId) {
     this.sessions.delete(sessionId);
   }
@@ -18288,6 +19267,7 @@ var ActivityTracker = class {
     this.config = config;
   }
   sessions = /* @__PURE__ */ new Map();
+  /** Shows the typing indicator and starts the periodic refresh timer. */
   onThinkingStart(sessionId, callbacks) {
     this.cleanup(sessionId);
     const state = {
@@ -18303,6 +19283,7 @@ var ActivityTracker = class {
       this.startRefresh(sessionId, state);
     }, 0);
   }
+  /** Dismisses the typing indicator when the agent starts producing text output. */
   onTextStart(sessionId) {
     const state = this.sessions.get(sessionId);
     if (!state || state.dismissed) return;
@@ -18311,9 +19292,11 @@ var ActivityTracker = class {
     state.callbacks.removeThinkingIndicator().catch(() => {
     });
   }
+  /** Cleans up the typing indicator when the session ends. */
   onSessionEnd(sessionId) {
     this.cleanup(sessionId);
   }
+  /** Cleans up all sessions (e.g., during adapter shutdown). */
   destroy() {
     for (const [id] of this.sessions) {
       this.cleanup(id);