@openacp/cli 2026.410.1 → 2026.410.2

package/dist/cli.js

@@ -429,37 +429,46 @@ var init_plugin_registry = __esm({
         this.registryPath = registryPath;
       }
       data = { installed: {} };
+      /** Return all installed plugins as a Map. */
       list() {
         return new Map(Object.entries(this.data.installed));
       }
+      /** Look up a plugin by name. Returns undefined if not installed. */
       get(name) {
         return this.data.installed[name];
       }
+      /** Record a newly installed plugin. Timestamps are set automatically. */
       register(name, entry) {
         const now = (/* @__PURE__ */ new Date()).toISOString();
         this.data.installed[name] = { ...entry, installedAt: now, updatedAt: now };
       }
+      /** Remove a plugin from the registry. */
       remove(name) {
         delete this.data.installed[name];
       }
+      /** Enable or disable a plugin. Disabled plugins are skipped at boot. */
       setEnabled(name, enabled) {
         const entry = this.data.installed[name];
         if (!entry) return;
         entry.enabled = enabled;
         entry.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
       }
+      /** Update the stored version (called after successful migration). */
       updateVersion(name, version) {
         const entry = this.data.installed[name];
         if (!entry) return;
         entry.version = version;
         entry.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
       }
+      /** Return only enabled plugins. */
       listEnabled() {
         return new Map(Object.entries(this.data.installed).filter(([, e]) => e.enabled));
       }
+      /** Filter plugins by installation source. */
       listBySource(source) {
         return new Map(Object.entries(this.data.installed).filter(([, e]) => e.source === source));
       }
+      /** Load registry data from disk. Silently starts empty if file doesn't exist. */
       async load() {
         try {
           const content = fs4.readFileSync(this.registryPath, "utf-8");
@@ -471,6 +480,7 @@ var init_plugin_registry = __esm({
           this.data = { installed: {} };
         }
       }
+      /** Persist registry data to disk. */
       async save() {
         const dir = path4.dirname(this.registryPath);
         fs4.mkdirSync(dir, { recursive: true });
@@ -497,6 +507,7 @@ var init_registry_client = __esm({
       constructor(registryUrl) {
         this.registryUrl = registryUrl ?? REGISTRY_URL;
       }
+      /** Fetch the registry, returning cached data if still fresh. */
       async getRegistry() {
         if (this.cache && Date.now() - this.cache.fetchedAt < CACHE_TTL) {
           return this.cache.data;
@@ -507,6 +518,7 @@ var init_registry_client = __esm({
         this.cache = { data, fetchedAt: Date.now() };
         return data;
       }
+      /** Search plugins by name, description, or tags (case-insensitive substring match). */
       async search(query) {
         const registry = await this.getRegistry();
         const q = query.toLowerCase();
@@ -515,11 +527,13 @@ var init_registry_client = __esm({
           return text5.includes(q);
         });
       }
+      /** Resolve a registry plugin name to its npm package name. Returns null if not found. */
       async resolve(name) {
         const registry = await this.getRegistry();
         const plugin2 = registry.plugins.find((p2) => p2.name === name);
         return plugin2?.npm ?? null;
       }
+      /** Force next getRegistry() call to refetch from network. */
       clearCache() {
         this.cache = null;
       }
@@ -1738,6 +1752,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 ?? [];
@@ -1813,44 +1837,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"
     };
   }
@@ -1868,6 +1923,7 @@ function createSecurityPlugin() {
     description: "User access control and session limits",
     essential: false,
     permissions: ["services:register", "middleware:register", "kernel:access", "commands:register"],
+    // These keys are propagated to child plugin configs so adapters can read them directly.
     inheritableKeys: ["allowedUserIds", "maxConcurrentSessions", "sessionTimeoutMinutes"],
     async install(ctx) {
       await ctx.settings.setAll({
@@ -2074,6 +2130,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 = path6.join(this.baseDir, sessionId);
         await fs7.promises.mkdir(sessionDir, { recursive: true });
@@ -2088,6 +2152,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 fs7.promises.stat(filePath);
@@ -2132,6 +2200,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";
       }
@@ -2258,6 +2327,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;
       }
@@ -2273,19 +2348,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;
@@ -2294,6 +2393,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) {
@@ -2456,8 +2562,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,
@@ -3588,6 +3695,7 @@ var init_history_recorder = __esm({
               status: event.status
             };
             if (event.kind) step2.kind = event.kind;
+            if (event.rawInput !== void 0) step2.input = event.rawInput;
             steps.push(step2);
             break;
           }
@@ -3744,6 +3852,8 @@ var init_history_recorder = __esm({
           this.debounceTimers.delete(sessionId);
         }
       }
+      // Search backwards so we match the most recent tool call with this ID first,
+      // in case the same tool is invoked multiple times within one turn.
       findToolCall(steps, id) {
         for (let i = steps.length - 1; i >= 0; i--) {
           const s = steps[i];
@@ -3931,23 +4041,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) {
@@ -3959,6 +4084,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(text5, options) {
         const providerName = this.config.tts.provider;
         if (!providerName) {
@@ -3970,10 +4100,17 @@ var init_speech_service = __esm({
         }
         return provider.synthesize(text5, 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) {
@@ -4013,6 +4150,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();
@@ -4138,6 +4281,7 @@ var init_speech = __esm({
       version: "1.0.0",
       description: "Text-to-speech and speech-to-text with pluggable providers",
       essential: false,
+      // file-service is needed to persist synthesized audio for adapters that send files
       optionalPluginDependencies: { "@openacp/file-service": "^1.0.0" },
       permissions: ["services:register", "commands:register", "kernel:access"],
       inheritableKeys: ["ttsProvider", "ttsVoice"],
@@ -4349,6 +4493,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;
@@ -4357,6 +4507,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 {
@@ -4380,6 +4536,7 @@ function createNotificationsPlugin() {
     version: "1.0.0",
     description: "Cross-session notification routing",
     essential: false,
+    // Depends on security so the notification service is only active for authorized sessions
     pluginDependencies: { "@openacp/security": "^1.0.0" },
     permissions: ["services:register", "kernel:access"],
     async install(ctx) {
@@ -4434,6 +4591,10 @@ var init_keepalive = __esm({
       static PING_INTERVAL = 3e4;
       static FAIL_THRESHOLD = 3;
       static PING_TIMEOUT = 5e3;
+      /**
+       * Start polling. Replaces any existing interval.
+       * `onDead` is called once when the failure threshold is reached.
+       */
       start(tunnelUrl, onDead) {
         this.stop();
         this.interval = setInterval(async () => {
@@ -4455,6 +4616,10 @@ var init_keepalive = __esm({
           }
         }, _TunnelKeepAlive.PING_INTERVAL);
       }
+      /**
+       * Stop the keepalive interval and reset the failure counter.
+       * Resetting ensures a clean slate if the keepalive is restarted after stopping.
+       */
       stop() {
         if (this.interval) {
           clearInterval(this.interval);
@@ -5741,6 +5906,8 @@ var init_openacp = __esm({
       getPublicUrl() {
         return this.publicUrl;
       }
+      // Try to reuse a persisted tunnel (stable URL across restarts).
+      // If the saved tunnel is no longer alive on the worker, create a fresh one.
       async resolveCredentials(saved, all, localPort) {
         if (saved) {
           const alive = await this.pingWorker(saved.tunnelId);
@@ -5904,6 +6071,13 @@ var init_tunnel_registry = __esm({
         this.binDir = opts.binDir;
         this.storage = opts.storage ?? null;
       }
+      /**
+       * Spawn a new tunnel process for the given port and register it.
+       *
+       * Persists the entry to `tunnels.json` once the tunnel reaches `active` status.
+       * Throws if the port is already in use by an active or starting tunnel, or if the
+       * user tunnel limit is reached.
+       */
       async add(port, opts, _autoRetry = true) {
         if (this.entries.has(port)) {
           const existing = this.entries.get(port);
@@ -6022,6 +6196,12 @@ var init_tunnel_registry = __esm({
           this.scheduleSave();
         }
       }
+      /**
+       * Stop a user tunnel by port and remove it from the registry.
+       *
+       * Cancels any pending retry timer and waits for an in-progress spawn to settle
+       * before terminating the process. Throws if the port is a system tunnel.
+       */
       async stop(port) {
         const live = this.entries.get(port);
         if (!live) return;
@@ -6054,6 +6234,7 @@ var init_tunnel_registry = __esm({
         }
         return stopped;
       }
+      /** Stop all user tunnels. Errors from individual stops are silently ignored. */
       async stopAllUser() {
         const userEntries = this.list(false);
         for (const entry of userEntries) {
@@ -6083,6 +6264,12 @@ var init_tunnel_registry = __esm({
         this.save();
         this.entries.clear();
       }
+      /**
+       * Return all current tunnel entries.
+       *
+       * Pass `includeSystem = true` to include the system tunnel in the result;
+       * by default only user tunnels are returned.
+       */
       list(includeSystem = false) {
         const entries = Array.from(this.entries.values()).map((l) => l.entry);
         if (includeSystem) return entries;
@@ -6094,12 +6281,23 @@ var init_tunnel_registry = __esm({
       getBySession(sessionId) {
         return this.list(false).filter((e) => e.sessionId === sessionId);
       }
+      /**
+       * Return the system tunnel entry, or null if it hasn't been registered yet
+       * (e.g. `TunnelService.start()` hasn't been called, or the tunnel failed to start).
+       */
       getSystemEntry() {
         for (const live of this.entries.values()) {
           if (live.entry.type === "system") return live.entry;
         }
         return null;
       }
+      /**
+       * Re-launch tunnels persisted from a previous run.
+       *
+       * Only user tunnels are restored — the system tunnel is registered separately by
+       * `TunnelService.start()`. `sessionId` is intentionally dropped: sessions do not
+       * survive a restart, so restored tunnels are session-less until an agent claims them.
+       */
       async restore() {
         if (!fs16.existsSync(this.registryPath)) return;
         try {
@@ -6112,7 +6310,6 @@ var init_tunnel_registry = __esm({
                 type: persisted.type,
                 provider: persisted.provider,
                 label: persisted.label
-                // sessionId intentionally omitted — sessions don't survive restart
               })
             )
           );
@@ -6151,6 +6348,8 @@ var init_tunnel_registry = __esm({
             return new OpenACPTunnelProvider(this.providerOptions, this.binDir ?? "", this.storage);
         }
       }
+      // Debounce disk writes — multiple tunnel state changes may occur in rapid succession
+      // (e.g. status update + URL assignment). Coalesce them into a single write after 2s.
       scheduleSave() {
         if (this.saveTimeout) clearTimeout(this.saveTimeout);
         this.saveTimeout = setTimeout(() => this.save(), 2e3);
@@ -6814,6 +7013,9 @@ var init_viewer_store = __esm({
           log10.debug({ removed, remaining: this.entries.size }, "Cleaned up expired viewer entries");
         }
       }
+      // Guard against agents trying to serve files outside the session workspace
+      // (e.g. /etc/passwd or ~/ paths). Uses realpath to handle symlinks and canonicalize
+      // case on macOS/Windows where the filesystem is case-insensitive.
       isPathAllowed(filePath, workingDirectory) {
         const caseInsensitive = process.platform === "darwin" || process.platform === "win32";
         let resolved;
@@ -7254,6 +7456,7 @@ var init_token_store = __esm({
       codes = /* @__PURE__ */ new Map();
       savePromise = null;
       savePending = false;
+      /** Loads token and code state from disk. Safe to call at startup; missing file is not an error. */
       async load() {
         try {
           const data = await readFile2(this.filePath, "utf-8");
@@ -7284,6 +7487,10 @@ var init_token_store = __esm({
         };
         await writeFile(this.filePath, JSON.stringify(data, null, 2), "utf-8");
       }
+      /**
+       * Coalesces concurrent writes: if a save is in-flight, sets a pending flag
+       * so the next save fires immediately after the current one completes.
+       */
       scheduleSave() {
         if (this.savePromise) {
           this.savePending = true;
@@ -7299,6 +7506,7 @@ var init_token_store = __esm({
           }
         });
       }
+      /** Creates a new token record and schedules a persist. Returns the stored token including its generated id. */
       create(opts) {
         const now = /* @__PURE__ */ new Date();
         const token = {
@@ -7317,6 +7525,7 @@ var init_token_store = __esm({
       get(id) {
         return this.tokens.get(id);
       }
+      /** Marks a token as revoked; future auth checks will reject it immediately. */
       revoke(id) {
         const token = this.tokens.get(id);
         if (token) {
@@ -7324,10 +7533,17 @@ var init_token_store = __esm({
           this.scheduleSave();
         }
       }
+      /** Returns all non-revoked tokens. Revoked tokens are retained until cleanup() removes them. */
       list() {
         return Array.from(this.tokens.values()).filter((t) => !t.revoked);
       }
       lastUsedSaveTimer = null;
+      /**
+       * Records the current timestamp as `lastUsedAt` for the given token.
+       *
+       * Writes are debounced to 60 seconds — every API request updates this field,
+       * so flushing on every call would cause excessive disk I/O.
+       */
       updateLastUsed(id) {
         const token = this.tokens.get(id);
         if (token) {
@@ -7357,6 +7573,12 @@ var init_token_store = __esm({
           this.lastUsedSaveTimer = null;
         }
       }
+      /**
+       * Generates a one-time authorization code that can be exchanged for a JWT.
+       *
+       * Used for the CLI login flow: the server emits a code that the user copies into
+       * the App, which exchanges it for a proper JWT without ever exposing the raw API secret.
+       */
       createCode(opts) {
         const code = randomBytes(16).toString("hex");
         const now = /* @__PURE__ */ new Date();
@@ -7382,6 +7604,13 @@ var init_token_store = __esm({
         if (new Date(stored.expiresAt).getTime() < Date.now()) return void 0;
         return stored;
       }
+      /**
+       * Atomically marks a code as used and returns it.
+       *
+       * Returns undefined if the code is unknown, already used, or expired.
+       * The one-time-use flag is set before returning, so concurrent calls for the
+       * same code will only succeed once.
+       */
       exchangeCode(code) {
         const stored = this.codes.get(code);
         if (!stored) return void 0;
@@ -7401,6 +7630,13 @@ var init_token_store = __esm({
         this.codes.delete(code);
         this.scheduleSave();
       }
+      /**
+       * Removes tokens past their refresh deadline and expired/used codes.
+       *
+       * Called on a 1-hour interval from the plugin setup to prevent unbounded file growth.
+       * Tokens within their refresh deadline are retained even if revoked, so that the
+       * "token revoked" error can be returned instead of "token unknown".
+       */
       cleanup() {
         const now = Date.now();
         for (const [id, token] of this.tokens) {
@@ -7928,6 +8164,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 = [
@@ -7961,6 +8204,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" });
@@ -7995,6 +8245,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)}
@@ -8030,6 +8287,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) {
@@ -8093,9 +8356,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];
@@ -8828,6 +9097,8 @@ var init_config_migrations = __esm({
     log13 = 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;
@@ -8837,6 +9108,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;
@@ -8846,6 +9119,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;
@@ -8906,10 +9182,11 @@ var init_config2 = __esm({
       sessionLogRetentionDays: z4.number().default(30)
     }).default({});
     ConfigSchema = z4.object({
+      /** Instance UUID, written once at creation time. */
       id: z4.string().optional(),
-      // instance UUID, written once at creation time
       instanceName: z4.string().optional(),
       defaultAgent: z4.string(),
+      // --- Workspace security & path resolution ---
       workspace: z4.object({
         allowExternalWorkspaces: z4.boolean().default(true),
         security: z4.object({
@@ -8917,12 +9194,16 @@ var init_config2 = __esm({
           envWhitelist: z4.array(z4.string()).default([])
         }).default({})
       }).default({}),
+      // --- Logging ---
       logging: LoggingSchema,
+      // --- Process lifecycle ---
       runMode: z4.enum(["foreground", "daemon"]).default("foreground"),
       autoStart: z4.boolean().default(false),
+      // --- Session persistence ---
       sessionStore: z4.object({
         ttlDays: z4.number().default(30)
       }).default({}),
+      // --- Installed integration tracking (e.g. plugins installed via CLI) ---
       integrations: z4.record(
         z4.string(),
         z4.object({
@@ -8930,7 +9211,9 @@ var init_config2 = __esm({
           installedAt: z4.string().optional()
         })
       ).default({}),
+      // --- Agent output verbosity control ---
       outputMode: z4.enum(["low", "medium", "high"]).default("medium").optional(),
+      // --- Multi-agent switching behavior ---
       agentSwitch: z4.object({
         labelHistory: z4.boolean().default(true)
       }).default({})
@@ -8946,6 +9229,13 @@ var init_config2 = __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 = path24.dirname(this.configPath);
         fs21.mkdirSync(dir, { recursive: true });
@@ -8979,9 +9269,17 @@ var init_config2 = __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(fs21.readFileSync(this.configPath, "utf-8"));
@@ -9003,9 +9301,12 @@ var init_config2 = __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"]);
@@ -9022,6 +9323,13 @@ var init_config2 = __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 = path24.dirname(path24.dirname(this.configPath));
         if (!input2) {
@@ -9056,17 +9364,26 @@ var init_config2 = __esm({
         fs21.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 fs21.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 = path24.dirname(this.configPath);
         fs21.mkdirSync(dir, { recursive: true });
         fs21.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" },
@@ -9093,6 +9410,7 @@ var init_config2 = __esm({
           }
         }
       }
+      /** Applies env var overrides to the raw config object before Zod validation. */
       applyEnvOverrides(raw) {
         const overrides = [
           ["OPENACP_DEFAULT_AGENT", ["defaultAgent"]],
@@ -9123,6 +9441,7 @@ var init_config2 = __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)) {
@@ -9933,6 +10252,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 = fs22.readFileSync(this.registryPath, "utf-8");
@@ -9960,26 +10280,33 @@ var init_instance_registry = __esm({
           this.save();
         }
       }
+      /** Persist the registry to disk, creating parent directories if needed. */
       save() {
         const dir = path26.dirname(this.registryPath);
         fs22.mkdirSync(dir, { recursive: true });
         fs22.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;
@@ -10485,6 +10812,7 @@ var init_connection_manager = __esm({
     "use strict";
     ConnectionManager = class {
       connections = /* @__PURE__ */ new Map();
+      // Secondary index: sessionId → Set of connection IDs for O(1) broadcast targeting
       sessionIndex = /* @__PURE__ */ new Map();
       maxConnectionsPerSession;
       maxTotalConnections;
@@ -10492,6 +10820,14 @@ var init_connection_manager = __esm({
         this.maxConnectionsPerSession = opts?.maxPerSession ?? 10;
         this.maxTotalConnections = opts?.maxTotal ?? 100;
       }
+      /**
+       * Registers a new SSE connection for the given session.
+       *
+       * Wires a `close` listener on the response so the connection is automatically
+       * removed when the client disconnects (browser tab closed, network drop, etc.).
+       *
+       * @throws if the global or per-session connection limit is reached.
+       */
       addConnection(sessionId, tokenId, response) {
         if (this.connections.size >= this.maxTotalConnections) {
           throw new Error("Maximum total connections reached");
@@ -10512,6 +10848,7 @@ var init_connection_manager = __esm({
         response.on("close", () => this.removeConnection(id));
         return connection;
       }
+      /** Remove a connection from both indexes. Called automatically on client disconnect. */
       removeConnection(connectionId) {
         const conn = this.connections.get(connectionId);
         if (!conn) return;
@@ -10522,11 +10859,20 @@ var init_connection_manager = __esm({
           if (sessionConns.size === 0) this.sessionIndex.delete(conn.sessionId);
         }
       }
+      /** Returns all active connections for a session. */
       getConnectionsBySession(sessionId) {
         const connIds = this.sessionIndex.get(sessionId);
         if (!connIds) return [];
         return Array.from(connIds).map((id) => this.connections.get(id)).filter((c3) => c3 !== void 0);
       }
+      /**
+       * Writes a serialized SSE event to all connections for the given session.
+       *
+       * Backpressure handling: if `response.write()` returns false (OS send buffer full),
+       * the connection is flagged as `backpressured`. On the next write attempt, if it is
+       * still backpressured, the connection is forcibly closed to prevent unbounded memory
+       * growth from queuing writes on a slow or stalled client.
+       */
       broadcast(sessionId, serializedEvent) {
         for (const conn of this.getConnectionsBySession(sessionId)) {
           if (conn.response.writableEnded) continue;
@@ -10548,6 +10894,10 @@ var init_connection_manager = __esm({
           }
         }
       }
+      /**
+       * Force-close all connections associated with a given auth token.
+       * Called when a token is revoked to immediately terminate those streams.
+       */
       disconnectByToken(tokenId) {
         for (const [id, conn] of this.connections) {
           if (conn.tokenId === tokenId) {
@@ -10556,9 +10906,11 @@ var init_connection_manager = __esm({
           }
         }
       }
+      /** Returns a snapshot of all active connections (used by the admin endpoint). */
       listConnections() {
         return Array.from(this.connections.values());
       }
+      /** Close all connections and clear all indexes. Called on plugin teardown. */
       cleanup() {
         for (const [, conn] of this.connections) {
           if (!conn.response.writableEnded) conn.response.end();
@@ -10576,10 +10928,15 @@ var init_event_buffer = __esm({
   "src/plugins/sse-adapter/event-buffer.ts"() {
     "use strict";
     EventBuffer = class {
+      /**
+       * @param maxSize Maximum events retained per session. Older events are evicted when
+       *   this limit is exceeded. Defaults to 100.
+       */
       constructor(maxSize = 100) {
         this.maxSize = maxSize;
       }
       buffers = /* @__PURE__ */ new Map();
+      /** Append an event to the session's buffer, evicting the oldest entry if at capacity. */
       push(sessionId, event) {
         let buffer = this.buffers.get(sessionId);
         if (!buffer) {
@@ -10591,6 +10948,14 @@ var init_event_buffer = __esm({
           buffer.shift();
         }
       }
+      /**
+       * Returns events that occurred after `lastEventId`.
+       *
+       * - If `lastEventId` is `undefined`, returns all buffered events (fresh connection).
+       * - If `lastEventId` is not found in the buffer, returns `null` — the event has been
+       *   evicted and the client must be informed that a gap may exist.
+       * - Otherwise returns the slice after the matching event.
+       */
       getSince(sessionId, lastEventId) {
         const buffer = this.buffers.get(sessionId);
         if (!buffer || buffer.length === 0) return [];
@@ -10599,6 +10964,7 @@ var init_event_buffer = __esm({
         if (index === -1) return null;
         return buffer.slice(index + 1);
       }
+      /** Remove the buffer for a session — called when the session ends to free memory. */
       cleanup(sessionId) {
         this.buffers.delete(sessionId);
       }
@@ -10680,6 +11046,12 @@ var init_adapter = __esm({
         voice: false
       };
       heartbeatTimer;
+      /**
+       * Starts the heartbeat timer that keeps idle SSE connections alive.
+       *
+       * `.unref()` prevents the timer from blocking the Node.js event loop from
+       * exiting if this is the only remaining async operation (e.g. during tests).
+       */
       async start() {
         this.heartbeatTimer = setInterval(() => {
           const heartbeat = serializeHeartbeat();
@@ -10696,6 +11068,7 @@ var init_adapter = __esm({
           this.heartbeatTimer.unref();
         }
       }
+      /** Stops the heartbeat timer and closes all active connections. */
       async stop() {
         if (this.heartbeatTimer) {
           clearInterval(this.heartbeatTimer);
@@ -10703,18 +11076,32 @@ var init_adapter = __esm({
         }
         this.connectionManager.cleanup();
       }
+      /**
+       * Serializes an outgoing agent message, pushes it to the event buffer,
+       * then broadcasts it to all active connections for the session.
+       *
+       * Buffering before broadcast ensures that a client reconnecting immediately
+       * after this call can still replay the event via `Last-Event-ID`.
+       */
       async sendMessage(sessionId, content) {
         const eventId = generateEventId();
         const serialized = serializeOutgoingMessage(sessionId, eventId, content);
         this.eventBuffer.push(sessionId, { id: eventId, data: serialized });
         this.connectionManager.broadcast(sessionId, serialized);
       }
+      /** Serializes and delivers a permission request UI to the session's SSE clients. */
       async sendPermissionRequest(sessionId, request) {
         const eventId = generateEventId();
         const serialized = serializePermissionRequest(sessionId, eventId, request);
         this.eventBuffer.push(sessionId, { id: eventId, data: serialized });
         this.connectionManager.broadcast(sessionId, serialized);
       }
+      /**
+       * Delivers a cross-session notification to the target session's SSE clients.
+       *
+       * Notifications are always buffered in addition to being broadcast so that
+       * a client reconnecting shortly after (e.g. page refresh) still sees the alert.
+       */
       async sendNotification(notification) {
         if (notification.sessionId) {
           const eventId = generateEventId();
@@ -10723,9 +11110,11 @@ var init_adapter = __esm({
           this.connectionManager.broadcast(notification.sessionId, serialized);
         }
       }
+      /** SSE has no concept of threads — return sessionId as the threadId */
       async createSessionThread(sessionId, _name) {
         return sessionId;
       }
+      /** No-op for SSE — there are no named threads to rename. */
       async renameSessionThread(_sessionId, _newName) {
       }
     };
@@ -10765,6 +11154,7 @@ async function sseRoutes(app, deps) {
         "Content-Type": "text/event-stream",
         "Cache-Control": "no-cache",
         "Connection": "keep-alive",
+        // Disable buffering in Nginx/Cloudflare so events arrive without delay
         "X-Accel-Buffering": "no"
       });
       raw.write(serializeConnected(connection.id, sessionId));
@@ -13694,13 +14084,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 {
@@ -13710,6 +14103,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);
@@ -13721,12 +14115,14 @@ var init_settings_manager = __esm({
           )
         };
       }
+      /** Resolve the absolute path to a plugin's settings.json file. */
       getSettingsPath(pluginName) {
         return path30.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();
@@ -14297,6 +14693,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);
@@ -14344,6 +14746,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 || path35.join(dataDir, "config.json");
@@ -14991,6 +15394,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 = nanoid3(8);
@@ -15025,6 +15436,12 @@ ${escapeHtml4(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;
@@ -15072,6 +15489,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;
@@ -15079,6 +15499,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);
@@ -15094,6 +15515,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;
@@ -15104,17 +15526,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();
@@ -15220,9 +15645,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();
@@ -15231,20 +15658,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;
@@ -15416,6 +15847,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";
@@ -15474,6 +15912,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 {
@@ -15607,7 +16046,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(() => {
             });
           }
         });
@@ -15617,6 +16059,7 @@ var init_activity = __esm({
       lastSentText;
       flushPromise = Promise.resolve();
       overflowMsgIds = [];
+      aborted = false;
       tracer;
       sessionId;
       updateFromSpec(spec) {
@@ -15633,6 +16076,7 @@ var init_activity = __esm({
         await this.flushPromise;
       }
       destroy() {
+        this.aborted = true;
         this.state.destroy();
       }
       hasContent() {
@@ -15864,6 +16308,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;
@@ -15891,6 +16342,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 remaining2 = [];
@@ -15909,6 +16365,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;
@@ -15981,6 +16441,7 @@ var init_streaming = __esm({
       lastSentHtml = "";
       displayTruncated = false;
       tracer;
+      /** Append a text chunk to the buffer and schedule a throttled flush. */
       append(text5) {
         if (!text5) return;
         this.buffer += text5;
@@ -16060,6 +16521,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) {
@@ -16131,9 +16602,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();
@@ -16171,6 +16647,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) {
@@ -16199,7 +16679,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);
@@ -16226,6 +16711,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);
@@ -16244,14 +16735,19 @@ var init_skill_command_manager = __esm({
     init_log();
     log28 = 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);
@@ -16351,11 +16847,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":
@@ -16393,6 +16899,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) {
@@ -16426,6 +16934,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;
@@ -16434,6 +16946,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") {
@@ -16665,6 +17184,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";
@@ -16763,7 +17283,11 @@ var init_adapter2 = __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);
@@ -16828,6 +17352,12 @@ var init_adapter2 = __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: {
@@ -17258,6 +17788,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);
@@ -17391,8 +17928,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(() => {
           });
@@ -17481,9 +18017,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;
@@ -17797,6 +18350,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 });
         log29.info({ sessionId, requestId: request.id }, "Permission request sent");
@@ -17806,6 +18364,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;
@@ -17846,6 +18409,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 });
         log29.info({ sessionId, name }, "Session topic created");
@@ -17853,6 +18420,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);
@@ -17870,6 +18441,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;
@@ -17884,6 +18456,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);
@@ -17968,7 +18545,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),
@@ -17977,10 +18557,24 @@ Task completed.
           attachments: [att]
         }).catch((err) => log29.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);
@@ -17991,9 +18585,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;
@@ -19022,13 +19629,18 @@ var init_path_guard = __esm({
   "src/core/security/path-guard.ts"() {
     "use strict";
     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"
@@ -19056,6 +19668,20 @@ var init_path_guard = __esm({
           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 = path43.resolve(targetPath);
         let realPath;
@@ -19091,6 +19717,7 @@ var init_path_guard = __esm({
         }
         return { allowed: true, reason: "" };
       }
+      /** Adds an additional allowed path at runtime (e.g. for file-service uploads). */
       addAllowedPath(p2) {
         try {
           this.allowedPaths.push(fs38.realpathSync(path43.resolve(p2)));
@@ -19098,6 +19725,10 @@ var init_path_guard = __esm({
           this.allowedPaths.push(path43.resolve(p2));
         }
       }
+      /**
+       * 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 = path43.join(cwd, ".openacpignore");
         try {
@@ -19137,6 +19768,7 @@ var init_env_filter = __esm({
   "src/core/security/env-filter.ts"() {
     "use strict";
     DEFAULT_ENV_WHITELIST = [
+      // Shell basics — agents need these to resolve commands and write temp files
       "PATH",
       "HOME",
       "SHELL",
@@ -19149,11 +19781,11 @@ var init_env_filter = __esm({
       "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",
@@ -19221,12 +19853,14 @@ var init_stderr_capture = __esm({
         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");
       }
@@ -19245,6 +19879,7 @@ var init_typed_emitter = __esm({
       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) {
@@ -19254,10 +19889,17 @@ var init_typed_emitter = __esm({
         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, ...args2) {
         if (this.paused) {
           if (this.passthroughFn?.(event, args2)) {
@@ -19301,6 +19943,7 @@ var init_typed_emitter = __esm({
       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);
@@ -19308,6 +19951,7 @@ var init_typed_emitter = __esm({
           this.listeners.clear();
         }
       }
+      /** Deliver an event to listeners, isolating errors so one broken listener doesn't break others. */
       deliver(event, args2) {
         const set = this.listeners.get(event);
         if (!set) return;
@@ -19379,6 +20023,11 @@ var init_terminal_manager = __esm({
       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 ?? [];
@@ -19460,6 +20109,7 @@ var init_terminal_manager = __esm({
         });
         return { terminalId };
       }
+      /** Retrieve accumulated stdout/stderr output for a terminal. */
       getOutput(terminalId) {
         const state = this.terminals.get(terminalId);
         if (!state) {
@@ -19474,6 +20124,7 @@ var init_terminal_manager = __esm({
           } : void 0
         };
       }
+      /** Block until the terminal process exits, returning exit code and signal. */
       async waitForExit(terminalId) {
         const state = this.terminals.get(terminalId);
         if (!state) {
@@ -19497,6 +20148,7 @@ var init_terminal_manager = __esm({
           }
         });
       }
+      /** Send SIGTERM to a terminal process (graceful shutdown). */
       kill(terminalId) {
         const state = this.terminals.get(terminalId);
         if (!state) {
@@ -19504,6 +20156,7 @@ var init_terminal_manager = __esm({
         }
         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) {
@@ -19512,6 +20165,7 @@ var init_terminal_manager = __esm({
         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");
@@ -19559,6 +20213,12 @@ var init_debug_tracer = __esm({
       }
       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) {
@@ -19716,9 +20376,13 @@ var init_agent_instance = __esm({
       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;
@@ -19728,16 +20392,36 @@ var init_agent_instance = __esm({
       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(p2) {
         this.pathGuard.addAllowedPath(p2);
       }
-      // 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);
@@ -19836,6 +20520,13 @@ var init_agent_instance = __esm({
         );
         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;
@@ -19858,6 +20549,18 @@ ${stderr}`
           log33.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) {
         log33.debug(
           { agentName: agentDef.name, command: agentDef.command },
@@ -19891,6 +20594,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) {
         log33.debug({ agentName: agentDef.name, agentSessionId }, "Resuming agent");
         const spawnStart = Date.now();
@@ -19957,12 +20669,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;
@@ -20091,6 +20817,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,
@@ -20107,6 +20837,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 p2 = params;
             const pathCheck = self.pathGuard.validatePath(p2.path, "read");
@@ -20142,6 +20875,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,
@@ -20171,6 +20906,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({
@@ -20198,12 +20940,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({
@@ -20212,9 +20956,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({
@@ -20223,10 +20969,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(text5, attachments) {
         const contentBlocks = [{ type: "text", text: text5 }];
         const capabilities = this.promptCapabilities ?? {};
@@ -20276,9 +21037,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();
@@ -20313,6 +21083,7 @@ var init_agent_manager = __esm({
       constructor(catalog) {
         this.catalog = catalog;
       }
+      /** Return definitions for all installed agents. */
       getAvailableAgents() {
         const installed = this.catalog.getInstalledEntries();
         return Object.entries(installed).map(([key, agent]) => ({
@@ -20322,14 +21093,25 @@ var init_agent_manager = __esm({
           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.`);
@@ -20354,6 +21136,11 @@ var init_prompt_queue = __esm({
       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(text5, attachments, routing, turnId) {
         if (this.processing) {
           return new Promise((resolve9) => {
@@ -20362,6 +21149,7 @@ var init_prompt_queue = __esm({
         }
         await this.process(text5, attachments, routing, turnId);
       }
+      /** Run a single prompt through the processor, then drain the next queued item. */
       async process(text5, attachments, routing, turnId) {
         this.processing = true;
         this.abortController = new AbortController();
@@ -20389,12 +21177,17 @@ var init_prompt_queue = __esm({
           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();
@@ -20430,6 +21223,10 @@ var init_permission_gate = __esm({
       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"));
@@ -20448,6 +21245,7 @@ var init_permission_gate = __esm({
           }
         });
       }
+      /** 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;
@@ -20455,6 +21253,7 @@ var init_permission_gate = __esm({
         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;
@@ -20563,6 +21362,8 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
       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();
@@ -20665,7 +21466,7 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
         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");
       }
@@ -20685,19 +21486,29 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
       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(text5, attachments, routing, externalTurnId) {
         const turnId = externalTurnId ?? nanoid5(8);
         if (this.middlewareChain) {
@@ -20807,6 +21618,10 @@ ${text5}`;
           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(text5, attachments) {
         if (!attachments?.length || !this.speechService) {
           return { text: text5, attachments };
@@ -20852,6 +21667,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]) {
@@ -20888,7 +21704,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) => {
@@ -21047,6 +21865,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) {
@@ -21072,12 +21891,17 @@ var init_session_manager = __esm({
       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({
@@ -21105,9 +21929,11 @@ var init_session_manager = __esm({
         }
         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);
@@ -21118,6 +21944,7 @@ var init_session_manager = __esm({
         }
         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) {
@@ -21126,18 +21953,26 @@ var init_session_manager = __esm({
         }
         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,
           (p2) => String(p2.topicId) === threadId || p2.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);
@@ -21150,9 +21985,11 @@ var init_session_manager = __esm({
           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) {
@@ -21175,11 +22012,16 @@ var init_session_manager = __esm({
           });
         }
       }
+      /** 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);
@@ -21241,6 +22083,7 @@ var init_session_manager = __esm({
           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);
@@ -21249,6 +22092,7 @@ var init_session_manager = __esm({
         }
         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);
@@ -21359,7 +22203,10 @@ var init_session_bridge = __esm({
           log34.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;
@@ -21368,6 +22215,13 @@ var init_session_bridge = __esm({
         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;
@@ -21444,6 +22298,7 @@ var init_session_bridge = __esm({
           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;
@@ -21976,6 +22831,12 @@ var init_message_transformer = __esm({
       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":
@@ -22250,6 +23111,11 @@ var init_session_store = __esm({
         }
         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) {
@@ -22294,6 +23160,7 @@ var init_session_store = __esm({
         if (!fs42.existsSync(dir)) fs42.mkdirSync(dir, { recursive: true });
         fs42.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);
@@ -22329,7 +23196,11 @@ var init_session_store = __esm({
           }
         }
       }
-      /** 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;
@@ -22342,6 +23213,7 @@ var init_session_store = __esm({
         }
         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;
@@ -22412,6 +23284,10 @@ var init_session_factory = __esm({
       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) {
@@ -22595,6 +23471,11 @@ var init_session_factory = __esm({
         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;
@@ -22698,6 +23579,7 @@ var init_session_factory = __esm({
         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");
@@ -22742,6 +23624,7 @@ var init_session_factory = __esm({
           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;
@@ -22768,6 +23651,7 @@ var init_session_factory = __esm({
         }
         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;
@@ -22814,7 +23698,12 @@ var init_agent_switch_handler = __esm({
       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");
@@ -23025,20 +23914,29 @@ var init_agent_catalog = __esm({
     DEFAULT_TTL_HOURS = 24;
     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 {
           log39.info("Fetching agent registry from CDN...");
@@ -23058,6 +23956,7 @@ var init_agent_catalog = __esm({
           log39.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();
@@ -23069,6 +23968,7 @@ var init_agent_catalog = __esm({
       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;
@@ -23085,6 +23985,15 @@ var init_agent_catalog = __esm({
         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 = [];
@@ -23125,6 +24034,7 @@ var init_agent_catalog = __esm({
         }
         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." };
@@ -23135,6 +24045,12 @@ var init_agent_catalog = __esm({
         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) {
@@ -23159,6 +24075,7 @@ var init_agent_catalog = __esm({
       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);
@@ -23167,6 +24084,7 @@ var init_agent_catalog = __esm({
         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;
@@ -23310,6 +24228,7 @@ var init_agent_store = __esm({
       constructor(filePath) {
         this.filePath = filePath;
       }
+      /** Load and validate the store from disk. Starts fresh if file is missing or invalid. */
       load() {
         if (!fs44.existsSync(this.filePath)) {
           this.data = { version: 1, installed: {} };
@@ -23349,6 +24268,11 @@ var init_agent_store = __esm({
       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() {
         fs44.mkdirSync(path49.dirname(this.filePath), { recursive: true });
         const tmpPath = this.filePath + ".tmp";
@@ -23446,6 +24370,10 @@ var init_service_registry = __esm({
     "use strict";
     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);
@@ -23453,21 +24381,27 @@ var init_service_registry = __esm({
         }
         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) {
@@ -23489,6 +24423,7 @@ var init_middleware_chain = __esm({
       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,
@@ -23503,6 +24438,15 @@ var init_middleware_chain = __esm({
           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) {
@@ -23572,6 +24516,7 @@ var init_middleware_chain = __esm({
         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);
@@ -23582,9 +24527,11 @@ var init_middleware_chain = __esm({
           }
         }
       }
+      /** 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;
       }
@@ -23602,10 +24549,15 @@ var init_error_tracker = __esm({
       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();
@@ -23622,13 +24574,16 @@ var init_error_tracker = __esm({
           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);
       }
@@ -23646,6 +24601,7 @@ var init_plugin_storage = __esm({
     PluginStorageImpl = class {
       kvPath;
       dataDir;
+      /** Serializes writes to prevent concurrent file corruption */
       writeChain = Promise.resolve();
       constructor(baseDir) {
         this.dataDir = path50.join(baseDir, "data");
@@ -23686,6 +24642,7 @@ var init_plugin_storage = __esm({
       async list() {
         return Object.keys(this.readKv());
       }
+      /** Returns the plugin's data directory, creating it lazily on first access. */
       getDataDir() {
         fs45.mkdirSync(this.dataDir, { recursive: true });
         return this.dataDir;
@@ -23861,6 +24818,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);
@@ -23967,12 +24929,15 @@ var init_lifecycle_manager = __esm({
       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;
       }
@@ -24019,6 +24984,12 @@ var init_lifecycle_manager = __esm({
           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((p2) => p2.name));
         const allForResolution = [...this.loadOrder.filter((p2) => !newNames.has(p2.name)), ...plugins];
@@ -24130,6 +25101,11 @@ var init_lifecycle_manager = __esm({
           }
         }
       }
+      /**
+       * 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 plugin2 = this.loadOrder.find((p2) => p2.name === name);
@@ -24149,6 +25125,10 @@ var init_lifecycle_manager = __esm({
         this.loadOrder = this.loadOrder.filter((p2) => p2.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 plugin2 of reversed) {
@@ -24182,16 +25162,19 @@ var init_menu_registry = __esm({
     log41 = createChildLogger({ module: "menu-registry" });
     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;
@@ -24281,19 +25264,31 @@ var init_assistant_registry = __esm({
     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)) {
           log42.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];
@@ -24336,6 +25331,13 @@ var init_assistant_manager = __esm({
       }
       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({
@@ -24356,6 +25358,7 @@ var init_assistant_manager = __esm({
         );
         return session;
       }
+      /** Returns the active assistant session for a channel, or null if none exists. */
       get(channelId) {
         return this.sessions.get(channelId) ?? null;
       }
@@ -24368,6 +25371,7 @@ var init_assistant_manager = __esm({
         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;
@@ -24666,30 +25670,49 @@ var init_core = __esm({
       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;
@@ -24800,16 +25823,28 @@ var init_core = __esm({
         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) => {
           log44.warn({ err }, "Background registry refresh failed");
@@ -24829,6 +25864,10 @@ var init_core = __esm({
           );
         }
       }
+      /**
+       * 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");
@@ -24847,6 +25886,13 @@ var init_core = __esm({
         }
       }
       // --- 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)" };
@@ -24866,6 +25912,18 @@ var init_core = __esm({
         }
       }
       // --- 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) {
         log44.debug(
           {
@@ -24947,6 +26005,17 @@ ${text5}`;
         }
       }
       // --- 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) {
@@ -25069,9 +26138,16 @@ ${text5}`;
         );
         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) {
@@ -25182,22 +26258,33 @@ ${text5}`;
           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`);
@@ -25221,6 +26308,10 @@ ${text5}`;
         });
         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`);
@@ -25253,6 +26344,7 @@ ${text5}`;
           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) {
@@ -25284,8 +26376,13 @@ ${text5}`;
         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);
@@ -25395,10 +26492,15 @@ var init_command_registry = __esm({
         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();
@@ -26193,12 +27295,15 @@ var init_plugin_field_registry = __esm({
     "use strict";
     PluginFieldRegistry = class {
       fields = /* @__PURE__ */ new Map();
+      /** Register (or replace) the editable fields for a plugin. */
       register(pluginName, fields) {
         this.fields.set(pluginName, fields);
       }
+      /** Get the editable fields for a specific plugin. */
       getForPlugin(pluginName) {
         return this.fields.get(pluginName) ?? [];
       }
+      /** Get all fields grouped by plugin name. */
       getAll() {
         return new Map(this.fields);
       }
@@ -27555,6 +28660,10 @@ var init_dev_loader = __esm({
       constructor(pluginPath) {
         this.pluginPath = path55.resolve(pluginPath);
       }
+      /**
+       * Import the plugin's default export from dist/index.js.
+       * Each call uses a unique URL query to bypass Node's ESM cache.
+       */
       async load() {
         const distIndex = path55.join(this.pluginPath, "dist", "index.js");
         const srcIndex = path55.join(this.pluginPath, "src", "index.ts");
@@ -27572,9 +28681,11 @@ var init_dev_loader = __esm({
         }
         return plugin2;
       }
+      /** Returns the resolved absolute path to the plugin's root directory. */
       getPluginPath() {
         return this.pluginPath;
       }
+      /** Returns the path to the plugin's dist directory. */
       getDistPath() {
         return path55.join(this.pluginPath, "dist");
       }