@chrisromp/copilot-bridge 0.9.2 → 0.10.0

package/dist/core/session-manager.js

@@ -10,9 +10,10 @@ import { canCall, createContext, extendContext, getBotWorkspaceMap, buildWorkspa
 import { createLogger } from '../logger.js';
 import { tryWithFallback, isModelError, buildFallbackChain } from './model-fallback.js';
 import { loadHooks, getHooksInfo } from './hooks-loader.js';
+import { getBridgeDocs } from './bridge-docs.js';
 const log = createLogger('session');
-/** Custom tools auto-approved without interactive prompt (they enforce workspace boundaries internally). */
-export const BRIDGE_CUSTOM_TOOLS = ['send_file', 'show_file_in_chat', 'ask_agent', 'schedule'];
+/** Custom tools auto-approved without interactive prompt (read-only or enforce workspace boundaries internally). */
+export const BRIDGE_CUSTOM_TOOLS = ['send_file', 'show_file_in_chat', 'ask_agent', 'schedule', 'fetch_copilot_bridge_documentation'];
 /** Simple mutex for serializing env-sensitive session creation. */
 let envLock = Promise.resolve();
 /**
@@ -210,6 +211,35 @@ function loadWorkspaceMcpServers(workspacePath) {
         return { servers: {}, env: workspaceEnv };
     }
 }
+/**
+ * Merge global and workspace MCP server configs, injecting cwd and env into local servers.
+ * Exported for testing — used internally by SessionManager.resolveMcpServers().
+ */
+export function mergeMcpServers(globalServers, workspaceServers, workspaceEnv, workingDirectory) {
+    const merged = {};
+    for (const [name, config] of Object.entries(globalServers)) {
+        const serverConfig = { ...config };
+        const isLocal = !serverConfig.type || serverConfig.type === 'local' || serverConfig.type === 'stdio';
+        if (isLocal) {
+            if (!serverConfig.cwd) {
+                serverConfig.cwd = workingDirectory;
+            }
+            if (Object.keys(workspaceEnv).length > 0) {
+                serverConfig.env = { ...workspaceEnv, ...(serverConfig.env || {}) };
+            }
+        }
+        merged[name] = serverConfig;
+    }
+    for (const [name, config] of Object.entries(workspaceServers)) {
+        const serverConfig = { ...config };
+        const isLocal = !serverConfig.type || serverConfig.type === 'local' || serverConfig.type === 'stdio';
+        if (isLocal && !serverConfig.cwd) {
+            serverConfig.cwd = workingDirectory;
+        }
+        merged[name] = serverConfig;
+    }
+    return merged;
+}
 /**
  * Extract individual command names from a shell command string.
  * Handles chained commands: "ls -la && grep -r foo . | head" → ["ls", "grep", "head"]
@@ -294,6 +324,36 @@ function discoverSkillDirectories(workingDirectory) {
     }
     return dirs;
 }
+/** Extract a succinct summary from plan content (first heading + first body line, ~150 chars max). */
+export function extractPlanSummary(content) {
+    if (!content?.trim())
+        return '(empty plan)';
+    const lines = content.split('\n');
+    let heading = '';
+    let body = '';
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (!heading && trimmed.startsWith('#')) {
+            heading = trimmed.replace(/^#+\s*/, '');
+            continue;
+        }
+        if (!trimmed.startsWith('#') && !body) {
+            body = trimmed;
+            break;
+        }
+    }
+    if (heading && body) {
+        const full = `${heading}: ${body}`;
+        return full.length > 150 ? full.slice(0, 147) + '...' : full;
+    }
+    if (heading)
+        return heading.length > 150 ? heading.slice(0, 147) + '...' : heading;
+    if (body)
+        return body.length > 150 ? body.slice(0, 147) + '...' : body;
+    return '(empty plan)';
+}
 export class SessionManager {
     bridge;
     channelSessions = new Map(); // channelId → sessionId
@@ -307,6 +367,8 @@ export class SessionManager {
     pendingUserInput = new Map();
     // Cached context usage from session.usage_info events
     contextUsage = new Map();
+    // Cached max_context_window_tokens from listModels() (separate from usage_info to avoid ordering issues)
+    contextWindowTokens = new Map();
     lastMessageUserIds = new Map(); // channelId → userId of last message sender
     // MCP server names that were passed to the session at creation/resume time
     sessionMcpServers = new Map(); // channelId → server names
@@ -314,6 +376,12 @@ export class SessionManager {
     sessionSkillDirs = new Map(); // channelId → skill dir paths
     // Loaded session hooks per workspace (cached after first load)
     workspaceHooks = new Map();
+    // Pending plan exit requests (one per channel)
+    pendingPlanExit = new Map();
+    // Debounce timers for plan_changed events
+    planChangedDebounce = new Map();
+    // Previous permissionMode before yolo was auto-enabled by plan exit
+    yoloPreviousState = new Map();
     // Handler for send_file tool (set by index.ts, calls adapter.sendFile)
     sendFileHandler = null;
     getAdapterForChannel = null;
@@ -408,19 +476,7 @@ export class SessionManager {
      */
     resolveMcpServers(workingDirectory) {
         const { servers: workspaceServers, env: workspaceEnv } = loadWorkspaceMcpServers(workingDirectory);
-        // Clone global servers and inject workspace .env into local ones
-        const merged = {};
-        for (const [name, config] of Object.entries(this.mcpServers)) {
-            const serverConfig = { ...config };
-            const isLocal = !serverConfig.type || serverConfig.type === 'local' || serverConfig.type === 'stdio';
-            if (isLocal && Object.keys(workspaceEnv).length > 0) {
-                serverConfig.env = { ...workspaceEnv, ...(serverConfig.env || {}) };
-            }
-            merged[name] = serverConfig;
-        }
-        if (Object.keys(workspaceServers).length === 0)
-            return merged;
-        return { ...merged, ...workspaceServers };
+        return mergeMcpServers(this.mcpServers, workspaceServers, workspaceEnv, workingDirectory);
     }
     /** Get annotated MCP server info for a channel, showing which layer each server came from. */
     getMcpServerInfo(channelId) {
@@ -546,9 +602,17 @@ export class SessionManager {
             this.channelSessions.delete(channelId);
             this.sessionChannels.delete(existingId);
             this.contextUsage.delete(channelId);
+            this.contextWindowTokens.delete(channelId);
             this.lastMessageUserIds.delete(channelId);
             this.sessionMcpServers.delete(channelId);
             this.sessionSkillDirs.delete(channelId);
+            this.pendingPlanExit.delete(channelId);
+            this.revertYoloIfNeeded(channelId);
+            const debounceTimer = this.planChangedDebounce.get(channelId);
+            if (debounceTimer) {
+                clearTimeout(debounceTimer);
+                this.planChangedDebounce.delete(channelId);
+            }
         }
         clearChannelSession(channelId);
         return this.createNewSession(channelId);
@@ -575,9 +639,19 @@ export class SessionManager {
         this.mcpServers = loadMcpServers();
         // Re-attach the same session (re-reads workspace config, AGENTS.md, MCP, etc.)
         this.contextUsage.delete(channelId);
+        this.contextWindowTokens.delete(channelId);
         this.lastMessageUserIds.delete(channelId);
         this.sessionMcpServers.delete(channelId);
         this.sessionSkillDirs.delete(channelId);
+        this.pendingPlanExit.delete(channelId);
+        this.revertYoloIfNeeded(channelId);
+        {
+            const dt = this.planChangedDebounce.get(channelId);
+            if (dt) {
+                clearTimeout(dt);
+                this.planChangedDebounce.delete(channelId);
+            }
+        }
         try {
             await this.attachSession(channelId, existingId);
             log.info(`Reloaded session ${existingId} for channel ${channelId}`);
@@ -589,9 +663,12 @@ export class SessionManager {
             this.channelSessions.delete(channelId);
             this.sessionChannels.delete(existingId);
             this.contextUsage.delete(channelId);
+            this.contextWindowTokens.delete(channelId);
             this.lastMessageUserIds.delete(channelId);
             this.sessionMcpServers.delete(channelId);
             this.sessionSkillDirs.delete(channelId);
+            this.pendingPlanExit.delete(channelId);
+            // yoloPreviousState already reverted above
             clearChannelSession(channelId);
             return this.createNewSession(channelId);
         }
@@ -617,9 +694,19 @@ export class SessionManager {
             this.channelSessions.delete(channelId);
             this.sessionChannels.delete(existingId);
             this.contextUsage.delete(channelId);
+            this.contextWindowTokens.delete(channelId);
             this.lastMessageUserIds.delete(channelId);
             this.sessionMcpServers.delete(channelId);
             this.sessionSkillDirs.delete(channelId);
+            this.pendingPlanExit.delete(channelId);
+            this.revertYoloIfNeeded(channelId);
+            {
+                const dt = this.planChangedDebounce.get(channelId);
+                if (dt) {
+                    clearTimeout(dt);
+                    this.planChangedDebounce.delete(channelId);
+                }
+            }
         }
         // If target session is active on another channel, disconnect it first
         const otherChannel = this.sessionChannels.get(targetSessionId);
@@ -636,9 +723,19 @@ export class SessionManager {
             this.channelSessions.delete(otherChannel);
             this.sessionChannels.delete(targetSessionId);
             this.contextUsage.delete(otherChannel);
+            this.contextWindowTokens.delete(otherChannel);
             this.lastMessageUserIds.delete(otherChannel);
             this.sessionMcpServers.delete(otherChannel);
             this.sessionSkillDirs.delete(otherChannel);
+            this.pendingPlanExit.delete(otherChannel);
+            this.revertYoloIfNeeded(otherChannel);
+            {
+                const dt = this.planChangedDebounce.get(otherChannel);
+                if (dt) {
+                    clearTimeout(dt);
+                    this.planChangedDebounce.delete(otherChannel);
+                }
+            }
             clearChannelSession(otherChannel);
         }
         // Attach to the target session — fail hard if it doesn't exist
@@ -785,6 +882,16 @@ export class SessionManager {
             }
         }
         setChannelPrefs(channelId, { model });
+        // Clear stale context window tokens so /context falls back to tokenLimit during transition
+        this.contextWindowTokens.delete(channelId);
+        // Update cached context window tokens for the new model (best-effort)
+        this.bridge.listModels().then(models => {
+            // Guard against rapid switches: only cache if the channel is still on this model
+            const currentPrefs = this.getEffectivePrefs(channelId);
+            if (currentPrefs.model === model) {
+                this.cacheContextWindowTokens(channelId, model, models);
+            }
+        }).catch(() => { });
     }
     /** Switch the agent for a channel's session. */
     async switchAgent(channelId, agent) {
@@ -877,6 +984,94 @@ export class SessionManager {
             return false;
         }
     }
+    /**
+     * Extract a succinct summary from plan content.
+     * Returns the first heading + first 1-2 sentences, ~100-150 chars.
+     */
+    extractPlanSummary(content) {
+        return extractPlanSummary(content);
+    }
+    // Preferred models for plan summarization — balanced for quality and cost.
+    // Summarization needs accurate extraction without hallucination, so we
+    // prefer capable mid-tier models over the cheapest options.
+    // Matched against available models via exact-then-prefix so partial matches
+    // work even if the catalog adds suffixes or version bumps.
+    static SUMMARIZER_MODELS = [
+        'claude-sonnet-4.6', // strong comprehension, likely to stay available
+        'claude-sonnet-4.5', // strong comprehension
+        'gpt-4.1', // fast, capable
+        'gpt-5-mini', // smaller but still capable
+        'claude-haiku-4.5', // fastest Claude, adequate for short summaries
+        'gpt-5.1', // full-size fallback
+        'gpt-5.2', // full-size fallback
+    ];
+    /**
+     * Summarize a plan using a lightweight ephemeral session.
+     * Creates a throwaway session with a cheap model, sends the plan for summarization,
+     * collects the streamed response, and destroys the session.
+     */
+    async summarizePlan(channelId) {
+        const plan = await this.readPlan(channelId);
+        if (!plan.exists || !plan.content)
+            return null;
+        // Pick the best available cheap model
+        let availableIds = [];
+        try {
+            const models = await this.bridge.listModels();
+            availableIds = models.map(m => m.id);
+        }
+        catch { /* best-effort */ }
+        let model;
+        for (const candidate of SessionManager.SUMMARIZER_MODELS) {
+            const match = availableIds.find(id => id === candidate || id.startsWith(candidate));
+            if (match) {
+                model = match;
+                break;
+            }
+        }
+        // If none matched, leave model undefined — SDK picks its default
+        log.info(`Summarizing plan for ${channelId.slice(0, 8)}... using model ${model ?? '(sdk default)'}`);
+        let session;
+        try {
+            session = await this.bridge.createSession({
+                ...(model ? { model } : {}),
+                onPermissionRequest: async () => ({ kind: 'denied-interactively-by-user' }),
+                systemMessage: { content: 'You are a concise summarizer. Respond with only the summary, no preamble.' },
+            });
+            const prompt = `Condense this plan into a short summary that preserves the main section headings (## level). Under each heading, write one sentence capturing the key point. Include any unresolved questions or TBDs. Omit code blocks, type definitions, and resolved questions. Keep the total under 500 characters.\n\n${plan.content}`;
+            const response = await this.sendAndWaitForIdle(session, prompt, 30_000);
+            return response.trim() || null;
+        }
+        catch (err) {
+            log.warn(`Plan summarization failed: ${err?.message ?? err}`);
+            return null;
+        }
+        finally {
+            if (session) {
+                try {
+                    await this.bridge.destroySession(session.sessionId);
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
+    /**
+     * Check for an existing plan and return summary if found.
+     * Called after session resume to notify the user.
+     */
+    async surfacePlanIfExists(channelId) {
+        const plan = await this.readPlan(channelId);
+        if (!plan.exists || !plan.content)
+            return null;
+        const summary = this.extractPlanSummary(plan.content);
+        let inPlanMode = false;
+        try {
+            const mode = await this.getSessionMode(channelId);
+            inPlanMode = mode === 'plan';
+        }
+        catch { /* best-effort */ }
+        return { exists: true, summary, inPlanMode };
+    }
     /** Check if the Copilot CLI is authenticated. */
     async getAuthStatus() {
         try {
@@ -965,6 +1160,49 @@ export class SessionManager {
         const queue = this.pendingPermissions.get(channelId);
         return !!queue && queue.length > 0 && !!queue[0].fromHook;
     }
+    /** Store a pending plan exit request. */
+    setPendingPlanExit(channelId, pending) {
+        this.pendingPlanExit.set(channelId, pending);
+    }
+    /** Check if channel has a pending plan exit request. */
+    hasPendingPlanExit(channelId) {
+        return this.pendingPlanExit.has(channelId);
+    }
+    /** Get and clear the pending plan exit request. */
+    consumePendingPlanExit(channelId) {
+        const pending = this.pendingPlanExit.get(channelId);
+        if (pending)
+            this.pendingPlanExit.delete(channelId);
+        return pending;
+    }
+    /** Save previous permission mode before auto-enabling yolo. */
+    saveYoloPreviousState(channelId) {
+        const prefs = getChannelPrefs(channelId);
+        const channelConfig = getChannelConfig(channelId);
+        const current = prefs?.permissionMode ?? channelConfig.permissionMode;
+        this.yoloPreviousState.set(channelId, current);
+    }
+    /** Revert yolo to previous state (called on session.idle after plan implementation). */
+    revertYoloIfNeeded(channelId) {
+        const previous = this.yoloPreviousState.get(channelId);
+        if (previous === undefined)
+            return false;
+        this.yoloPreviousState.delete(channelId);
+        setChannelPrefs(channelId, { permissionMode: previous });
+        return true;
+    }
+    /** Debounced plan change handler — calls callback after debounce window. */
+    debouncePlanChanged(channelId, callback, delayMs = 3000) {
+        const existing = this.planChangedDebounce.get(channelId);
+        if (existing)
+            clearTimeout(existing);
+        this.planChangedDebounce.set(channelId, setTimeout(() => {
+            this.planChangedDebounce.delete(channelId);
+            void Promise.resolve(callback()).catch((err) => {
+                log.warn(`Debounced plan callback failed for ${channelId.slice(0, 8)}...: ${err}`);
+            });
+        }, delayMs));
+    }
     /** Get the current session ID for a channel (if any). */
     getSessionId(channelId) {
         return this.channelSessions.get(channelId) ?? getChannelSession(channelId) ?? undefined;
@@ -991,7 +1229,19 @@ export class SessionManager {
     }
     /** Get cached context window usage for a channel. */
     getContextUsage(channelId) {
-        return this.contextUsage.get(channelId) ?? null;
+        const usage = this.contextUsage.get(channelId);
+        if (!usage)
+            return null;
+        const ctxWindow = this.contextWindowTokens.get(channelId);
+        return ctxWindow ? { ...usage, contextWindowTokens: ctxWindow } : usage;
+    }
+    /** Cache the model's max_context_window_tokens for accurate /context display. */
+    cacheContextWindowTokens(channelId, modelId, modelList) {
+        const model = modelList.find((m) => m.id === modelId);
+        const ctxTokens = model?.capabilities?.limits?.max_context_window_tokens;
+        if (typeof ctxTokens === 'number' && ctxTokens > 0) {
+            this.contextWindowTokens.set(channelId, ctxTokens);
+        }
     }
     /**
      * Resolve a session ID prefix to matching full session IDs.
@@ -1042,9 +1292,10 @@ export class SessionManager {
         const configFallbacks = configChannel.fallbackModels ?? getConfig().defaults.fallbackModels;
         // Fetch available models for fallback chain (best-effort — don't block on failure)
         let availableModels = [];
+        let modelList = [];
         try {
-            const models = await this.bridge.listModels();
-            availableModels = models.map(m => m.id);
+            modelList = await this.bridge.listModels();
+            availableModels = modelList.map(m => m.id);
         }
         catch {
             log.warn('Failed to fetch model list for fallback resolution');
@@ -1074,6 +1325,7 @@ export class SessionManager {
         const { result: session, usedModel, didFallback } = await tryWithFallback(prefs.model, availableModels, configFallbacks, createWithModel);
         this.sessionMcpServers.set(channelId, new Set(Object.keys(resolvedMcpServers)));
         this.sessionSkillDirs.set(channelId, new Set(skillDirectories));
+        this.cacheContextWindowTokens(channelId, usedModel, modelList);
         if (didFallback) {
             log.info(`Model fallback: "${prefs.model}" → "${usedModel}" for channel ${channelId}`);
             setChannelPrefs(channelId, { model: usedModel });
@@ -1125,6 +1377,15 @@ export class SessionManager {
         this.channelSessions.set(channelId, sessionId);
         this.sessionChannels.set(sessionId, channelId);
         this.attachSessionEvents(session, channelId);
+        // Cache context window tokens for /context display (best-effort, non-blocking)
+        const resumeModel = prefs.model;
+        this.bridge.listModels().then(models => {
+            // Guard against model changes before this resolves
+            const currentPrefs = this.getEffectivePrefs(channelId);
+            if (currentPrefs.model === resumeModel) {
+                this.cacheContextWindowTokens(channelId, resumeModel, models);
+            }
+        }).catch(() => { });
     }
     /**
      * Execute an ephemeral inter-agent call: create a fresh session for the target bot,
@@ -1761,6 +2022,8 @@ export class SessionManager {
         }
         // Scheduler tool: create/list/cancel/pause/resume scheduled tasks
         tools.push(this.buildScheduleToolDef(channelId));
+        // Bridge documentation tool
+        tools.push(this.buildBridgeDocsTool(channelId));
         if (tools.length > 0) {
             log.info(`Built ${tools.length} custom tool(s) for channel ${channelId.slice(0, 8)}...`);
         }
@@ -1877,6 +2140,38 @@ export class SessionManager {
             },
         };
     }
+    buildBridgeDocsTool(channelId) {
+        const channelConfig = getChannelConfig(channelId);
+        const botName = getChannelBotName(channelId);
+        const isAdmin = isBotAdmin(channelConfig.platform, botName);
+        return {
+            name: 'fetch_copilot_bridge_documentation',
+            description: 'Fetch documentation about copilot-bridge capabilities, commands, configuration, and system status. Use this when you need to understand bridge features, help users with commands, troubleshoot issues, or check system status. Call with a specific topic to get focused information. If the documentation doesn\'t fully answer your question, each topic includes source code pointers for deeper investigation.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    topic: {
+                        type: 'string',
+                        enum: ['overview', 'commands', 'config', 'mcp', 'permissions', 'workspaces', 'hooks', 'skills', 'inter-agent', 'scheduling', 'troubleshooting', 'status'],
+                        description: "Topic to query. 'overview' = what the bridge is and key features. 'commands' = common slash commands. 'config' = configuration options. 'mcp' = MCP server setup. 'permissions' = permission system. 'workspaces' = workspace structure. 'hooks' = tool hooks. 'skills' = skill discovery. 'inter-agent' = bot-to-bot communication. 'scheduling' = task scheduling. 'troubleshooting' = common issues. 'status' = live system state.",
+                    },
+                },
+                required: [],
+            },
+            handler: async (args) => {
+                const sessionInfo = this.getSessionInfo(channelId);
+                return {
+                    content: getBridgeDocs({
+                        topic: args.topic,
+                        isAdmin,
+                        channelId,
+                        model: sessionInfo?.model,
+                        sessionId: sessionInfo?.sessionId,
+                    }),
+                };
+            },
+        };
+    }
     attachSessionEvents(session, channelId) {
         const unsub = session.on((event) => {
             if (event.type === 'session.usage_info' && event.data) {