@chrisromp/copilot-bridge 0.9.2 → 0.11.0

package/dist/core/session-manager.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { getChannelSession, setChannelSession, clearChannelSession, getChannelPrefs, setChannelPrefs, checkPermission, addPermissionRule, getWorkspaceOverride, setWorkspaceOverride, listWorkspaceOverrides, recordAgentCall, } from '../state/store.js';
-import { getChannelConfig, getChannelBotName, evaluateConfigPermissions, isBotAdmin, getConfig, getInterAgentConfig, isHardDeny } from '../config.js';
+import { getChannelConfig, getChannelBotName, evaluateConfigPermissions, isBotAdmin, getConfig, getInterAgentConfig, isHardDeny, resolveProviderConfig } from '../config.js';
 import { getWorkspacePath, getWorkspaceAllowPaths, ensureWorkspacesDir } from './workspace-manager.js';
 import { onboardProject } from './onboarding.js';
 import { addJob, removeJob, pauseJob, resumeJob, listJobs, formatInTimezone } from './scheduler.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
@@ -675,11 +772,12 @@ export class SessionManager {
                 const configFallbacks = configChannel.fallbackModels ?? getConfig().defaults.fallbackModels;
                 let availableModels = [];
                 try {
-                    const models = await this.bridge.listModels();
+                    const models = await this.bridge.listModels(getConfig().providers);
                     availableModels = models.map(m => m.id);
                 }
                 catch { /* best-effort */ }
-                const chain = buildFallbackChain(prefs.model, availableModels, configFallbacks);
+                const byokPrefixes = Object.keys(getConfig().providers ?? {});
+                const chain = buildFallbackChain(prefs.model, availableModels, configFallbacks, byokPrefixes);
                 // Try each fallback: create session + send
                 let lastError = err;
                 for (const fallbackModel of chain) {
@@ -774,17 +872,78 @@ export class SessionManager {
         }
     }
     /** Switch the model for a channel's session. */
-    async switchModel(channelId, model) {
-        const sessionId = this.channelSessions.get(channelId);
-        if (sessionId) {
+    async switchModel(channelId, model, provider) {
+        const currentPrefs = this.getEffectivePrefs(channelId);
+        const currentProvider = currentPrefs.provider ?? null;
+        const newProvider = provider ?? null;
+        const providerChanged = currentProvider !== newProvider;
+        if (providerChanged) {
+            // Provider change requires a fresh session (different endpoint/auth)
+            log.info(`Provider switch ${currentProvider ?? 'copilot'} → ${newProvider ?? 'copilot'} for channel ${channelId.slice(0, 8)}...`);
+            // Set prefs before newSession so createNewSession picks up the new provider,
+            // but restore on failure so the channel isn't left in a broken state.
+            const prevModel = currentPrefs.model;
+            setChannelPrefs(channelId, { model, provider: newProvider });
+            try {
+                await this.newSession(channelId);
+            }
+            catch (err) {
+                log.warn(`Provider switch failed, reverting prefs:`, err);
+                setChannelPrefs(channelId, { model: prevModel, provider: currentProvider });
+                throw err;
+            }
+        }
+        else if (newProvider && this.wireApiChanged(newProvider, currentPrefs.model ?? '', model)) {
+            // Same provider but wireApi differs between models — need fresh session
+            log.info(`wireApi change for provider ${newProvider}, model ${currentPrefs.model} → ${model} — creating new session`);
+            const prevModel = currentPrefs.model;
+            setChannelPrefs(channelId, { model, provider: newProvider });
             try {
-                await this.bridge.switchSessionModel(sessionId, model);
+                await this.newSession(channelId);
             }
             catch (err) {
-                log.warn(`RPC model switch failed:`, err);
+                log.warn(`wireApi switch failed, reverting prefs:`, err);
+                setChannelPrefs(channelId, { model: prevModel, provider: currentProvider });
+                throw err;
             }
         }
-        setChannelPrefs(channelId, { model });
+        else {
+            // Same provider — use RPC model switch
+            const sessionId = this.channelSessions.get(channelId);
+            if (sessionId) {
+                try {
+                    await this.bridge.switchSessionModel(sessionId, model);
+                }
+                catch (err) {
+                    log.warn(`RPC model switch failed:`, err);
+                }
+            }
+            setChannelPrefs(channelId, { model, provider: newProvider });
+        }
+        // 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(getConfig().providers).then(models => {
+            // Guard against rapid switches: only cache if the channel is still on this model
+            const prefs = this.getEffectivePrefs(channelId);
+            if (prefs.model === model) {
+                this.cacheContextWindowTokens(channelId, model, models);
+            }
+        }).catch(() => { });
+    }
+    /** Check if two models on the same provider have different wireApi settings. */
+    wireApiChanged(providerName, oldModel, newModel) {
+        const providers = getConfig().providers;
+        if (!providers)
+            return false;
+        const entry = providers[providerName];
+        if (!entry)
+            return false;
+        const oldEntry = entry.models.find(m => m.id === oldModel);
+        const newEntry = entry.models.find(m => m.id === newModel);
+        const oldWire = oldEntry?.wireApi ?? entry.wireApi;
+        const newWire = newEntry?.wireApi ?? entry.wireApi;
+        return oldWire !== newWire;
     }
     /** Switch the agent for a channel's session. */
     async switchAgent(channelId, agent) {
@@ -808,6 +967,7 @@ export class SessionManager {
         const storedPrefs = getChannelPrefs(channelId);
         return {
             model: storedPrefs?.model ?? configChannel.model ?? 'claude-sonnet-4.6',
+            provider: storedPrefs?.provider ?? null,
             agent: storedPrefs?.agent !== undefined ? storedPrefs.agent : configChannel.agent,
             verbose: storedPrefs?.verbose ?? configChannel.verbose,
             triggerMode: configChannel.triggerMode,
@@ -820,7 +980,7 @@ export class SessionManager {
     /** Get model info (for checking capabilities like reasoning effort). */
     async getModelInfo(modelId) {
         try {
-            const models = await this.bridge.listModels();
+            const models = await this.bridge.listModels(getConfig().providers);
             return models.find(m => m.id === modelId) ?? null;
         }
         catch {
@@ -829,7 +989,7 @@ export class SessionManager {
     }
     /** List all available models. */
     async listModels() {
-        return this.bridge.listModels();
+        return this.bridge.listModels(getConfig().providers);
     }
     /** Get the current session mode (interactive, plan, autopilot). Falls back to persisted prefs after restart. */
     async getSessionMode(channelId) {
@@ -877,6 +1037,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(getConfig().providers);
+            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 +1213,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 +1282,26 @@ 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) {
+        let model = modelList.find((m) => m.id === modelId);
+        // For BYOK models, the merged list has provider-prefixed IDs (e.g., "ollama-local:qwen3:8b")
+        if (!model) {
+            const prefs = getChannelPrefs(channelId);
+            if (prefs?.provider) {
+                model = modelList.find((m) => m.id === `${prefs.provider}:${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.
@@ -1040,11 +1350,20 @@ export class SessionManager {
         // Resolve fallback configuration
         const configChannel = getChannelConfig(channelId);
         const configFallbacks = configChannel.fallbackModels ?? getConfig().defaults.fallbackModels;
+        // Resolve BYOK provider if set in prefs
+        const providerName = prefs.provider ?? null;
+        const sdkProvider = providerName
+            ? resolveProviderConfig(providerName, getConfig().providers, prefs.model ?? undefined)
+            : undefined;
+        if (providerName && !sdkProvider) {
+            log.warn(`Provider "${providerName}" set for channel ${channelId} but not found in config — using Copilot`);
+        }
         // 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(getConfig().providers);
+            availableModels = modelList.map(m => m.id);
         }
         catch {
             log.warn('Failed to fetch model list for fallback resolution');
@@ -1058,6 +1377,7 @@ export class SessionManager {
         const createWithModel = async (model) => {
             return withWorkspaceEnv(workingDirectory, () => this.bridge.createSession({
                 model,
+                provider: sdkProvider || undefined,
                 workingDirectory,
                 configDir: defaultConfigDir,
                 reasoningEffort: reasoningEffort ?? undefined,
@@ -1071,9 +1391,37 @@ export class SessionManager {
                 infiniteSessions: getConfig().infiniteSessions,
             }));
         };
-        const { result: session, usedModel, didFallback } = await tryWithFallback(prefs.model, availableModels, configFallbacks, createWithModel);
+        const byokPrefixes = Object.keys(getConfig().providers ?? {});
+        let session;
+        let usedModel;
+        let didFallback;
+        try {
+            const result = await tryWithFallback(prefs.model, availableModels, configFallbacks, createWithModel, byokPrefixes);
+            session = result.result;
+            usedModel = result.usedModel;
+            didFallback = result.didFallback;
+        }
+        catch (err) {
+            // Enhance error message with BYOK context (only when provider actually resolved)
+            if (providerName && sdkProvider) {
+                const msg = String(err?.message ?? err);
+                const provConfig = getConfig().providers?.[providerName];
+                if (msg.includes('ECONNREFUSED') || msg.includes('ENOTFOUND') || msg.includes('fetch failed')) {
+                    throw new Error(`Provider "${providerName}" is unreachable at ${provConfig?.baseUrl ?? 'unknown URL'}. Check that the service is running.`);
+                }
+                if (msg.includes('401') || msg.includes('403') || msg.includes('Unauthorized') || msg.includes('Forbidden')) {
+                    throw new Error(`Provider "${providerName}" rejected authentication. Check your API key configuration.`);
+                }
+                if (msg.includes('404') || msg.includes('model not found') || msg.includes('does not exist')) {
+                    throw new Error(`Model "${prefs.model}" not found on provider "${providerName}". Check the model ID in your config.`);
+                }
+                throw new Error(`Provider "${providerName}" error: ${msg}`);
+            }
+            throw err;
+        }
         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 });
@@ -1107,11 +1455,20 @@ export class SessionManager {
         if (hooks) {
             log.debug(`Hooks resolved for session resume: ${Object.keys(hooks).join(', ')}`);
         }
+        // Resolve BYOK provider for resume
+        const providerName = prefs.provider ?? null;
+        let sdkProvider = providerName
+            ? resolveProviderConfig(providerName, getConfig().providers, prefs.model ?? undefined)
+            : undefined;
+        if (providerName && !sdkProvider) {
+            log.warn(`Provider "${providerName}" set for channel ${channelId} but not found in config — using Copilot`);
+        }
         const session = await withWorkspaceEnv(workingDirectory, () => this.bridge.resumeSession(sessionId, {
             onPermissionRequest: (request, invocation) => this.handlePermissionRequest(channelId, request, invocation),
             onUserInputRequest: (request, invocation) => this.handleUserInputRequest(channelId, request, invocation),
             configDir: defaultConfigDir,
             workingDirectory,
+            provider: sdkProvider || undefined,
             reasoningEffort: reasoningEffort ?? undefined,
             mcpServers,
             skillDirectories: skillDirectories.length > 0 ? skillDirectories : undefined,
@@ -1125,6 +1482,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(getConfig().providers).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 +2127,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 +2245,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', 'providers', '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. 'providers' = BYOK provider setup and commands. '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) {