vanspod 0.0.0-stage → 0.1.2

package/dist/classroomApp.js

@@ -0,0 +1,1814 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClassroomApp = exports.ENVIRONMENT_TOOLS = void 0;
+const secureStorage_1 = require("./secureStorage");
+const storageErrors_1 = require("./storageErrors");
+const adapterSettings_1 = require("./adapterSettings");
+const clientRoutes_1 = require("./clientRoutes");
+const node_util_1 = require("node:util");
+const courseCatalog_1 = require("./courseCatalog");
+const modelProxy_1 = require("./modelProxy");
+exports.ENVIRONMENT_TOOLS = ["uv", "git", "node", "pwsh"];
+const ENVIRONMENT_LABEL = {
+    uv: "uv",
+    git: "git",
+    node: "Node.js",
+    pwsh: "PowerShell 7",
+};
+const LOCAL_LIST_NOTE = "這是本機清單。";
+const INSTALL_UNAVAILABLE = "尚未指定專案資料夾，安裝不可用。";
+const REOPEN_TERMINAL = "請重開終端機再重新檢查。";
+const ENVIRONMENT_ABORTED = "已中止安裝。系統安裝程式可能仍在執行，請等待結束或稍後重新安裝。";
+const PROXY_CLIENTS = ["codex", "claude", "copilot"];
+class ClassroomApp {
+    deps;
+    adapters = (0, adapterSettings_1.defaultAdapters)();
+    clientRoutes = (0, clientRoutes_1.defaultClientRoutes)();
+    clientRouteOrigins = {};
+    adapterNotice;
+    hiddenKeys = new Set();
+    initialization;
+    connectionOperations = Promise.resolve();
+    connected = false;
+    classLabel;
+    nickname;
+    courseTitle;
+    sessionTitle;
+    detail = "";
+    connectionError;
+    connectionNotice;
+    connectionDraft;
+    notice;
+    projectFolder;
+    folderError;
+    catalog;
+    catalogError;
+    remoteCatalogHeld = false;
+    pendingCommand;
+    pendingActionId;
+    installedActions = new Map();
+    copiedSnippets = new Map();
+    commandOutput;
+    commandRunning = false;
+    commandAborted;
+    runningInstall;
+    stopping = false;
+    commandSucceeded;
+    clientModes = { codex: "native", claude: "native" };
+    detectedClients = { codex: false, claude: false, vsCodeChat: false };
+    // Legacy shared operations still reset both clients; aggregate mode keeps old connections readable.
+    get mode() {
+        return Object.values(this.clientModes).includes("classroom") ? "classroom" : "native";
+    }
+    set mode(mode) { this.clientModes = { codex: mode, claude: mode }; }
+    modelIds = [];
+    modelProviders = [];
+    environmentInstalled = {
+        uv: false,
+        git: false,
+        node: false,
+        pwsh: false,
+    };
+    environmentSelected = new Set();
+    environmentNotice;
+    proxyRunning = false;
+    mustRestart = [];
+    modelRestart = [];
+    allowlistError;
+    routeRestartNoted = false;
+    vsCodeOrigin;
+    sending = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    serialConnectionOperation(operation) {
+        const next = this.connectionOperations.then(operation, operation);
+        this.connectionOperations = next.catch(() => { });
+        return next;
+    }
+    view() {
+        const view = {
+            connected: this.connected,
+            detail: this.detail,
+            canCopyKey: this.connected,
+            installAvailable: Boolean(this.projectFolder),
+            commandRunning: this.commandRunning,
+            mode: this.mode,
+            clientModes: { ...this.clientModes },
+            clientRoutes: this.clientRouteView(),
+            detectedClients: { codex: this.detectedClients.codex, claude: this.detectedClients.claude },
+            allowedModels: [...this.modelIds],
+            adapters: { ...this.adapters },
+            adapterNotice: this.adapterNotice,
+            tools: this.environmentTools(),
+        };
+        if (this.connectionError)
+            view.connectionError = this.connectionError;
+        if (this.notice && this.notice === this.connectionNotice)
+            view.connectionNotice = this.connectionNotice;
+        if (this.connectionDraft && !this.connected)
+            view.connectionDraft = { ...this.connectionDraft };
+        if (this.classLabel) {
+            view.classLabel = this.classLabel;
+        }
+        if (this.nickname) {
+            view.nickname = this.nickname;
+        }
+        if (this.courseTitle) {
+            view.courseTitle = this.courseTitle;
+        }
+        if (this.sessionTitle) {
+            view.sessionTitle = this.sessionTitle;
+        }
+        const notice = this.visibleNotice();
+        if (notice) {
+            view.notice = notice;
+        }
+        if (this.projectFolder) {
+            view.projectFolder = this.projectFolder;
+        }
+        else {
+            view.installNotice = INSTALL_UNAVAILABLE;
+        }
+        if (this.folderError) {
+            view.folderError = this.folderError;
+        }
+        if (this.catalog) {
+            view.catalog = this.catalog;
+            const installed = this.installedActions.get(this.projectFolder ?? "");
+            view.installedActionIds = this.catalog.actions
+                .filter((action) => installed?.get(action.id) === action.command)
+                .map((action) => action.id);
+            view.copiedSnippetIds = (this.catalog.snippets ?? [])
+                .filter((snippet) => this.copiedSnippets.get(snippet.id) === snippet.body)
+                .map((snippet) => snippet.id);
+        }
+        if (this.catalogError) {
+            view.catalogError = this.catalogError;
+        }
+        if (this.allowlistError)
+            view.allowlistError = this.allowlistError;
+        if (this.pendingCommand) {
+            view.pendingCommand = this.pendingCommand;
+        }
+        if (this.commandOutput !== undefined) {
+            view.commandOutput = this.commandOutput;
+        }
+        if (this.commandSucceeded !== undefined)
+            view.commandSucceeded = this.commandSucceeded;
+        if (this.commandAborted)
+            view.commandAborted = true;
+        if (this.mode === "classroom" && this.modelIds[0]) {
+            view.modelId = this.modelIds[0];
+        }
+        if (this.environmentNotice) {
+            view.environmentNotice = this.environmentNotice;
+        }
+        if (this.mustRestart.length > 0) {
+            view.mustRestart = [...this.mustRestart];
+        }
+        if (this.modelRestart.length > 0)
+            view.modelRestart = [...this.modelRestart];
+        let rendered = JSON.stringify(view);
+        for (const key of this.hiddenKeys) {
+            rendered = rendered.split(JSON.stringify(key).slice(1, -1)).join("[redacted]");
+        }
+        return JSON.parse(rendered);
+    }
+    redactSecrets(value) {
+        let redacted = value;
+        for (const key of this.hiddenKeys)
+            redacted = redacted.split(key).join("[redacted]");
+        return redacted;
+    }
+    clientRouteView() {
+        return {
+            codex: { ...this.clientRoutes.codex },
+            claudeCode: { ...this.clientRoutes.claudeCode },
+            vsCodeChat: { ...this.clientRoutes.vsCodeChat },
+        };
+    }
+    async checkEnvironment() {
+        if (this.commandRunning) {
+            return;
+        }
+        for (const tool of exports.ENVIRONMENT_TOOLS) {
+            let installed = false;
+            try {
+                installed = (await this.deps.environment.probe(tool)).installed;
+            }
+            catch {
+                installed = false;
+            }
+            this.environmentInstalled[tool] = installed;
+        }
+    }
+    selectEnvironment(tools) {
+        if (this.commandRunning) {
+            return;
+        }
+        this.environmentSelected = new Set(exports.ENVIRONMENT_TOOLS.filter((id) => tools.includes(id)));
+    }
+    async confirmEnvironment() {
+        if (this.stopping || this.commandRunning || !this.projectFolder) {
+            return;
+        }
+        const selected = exports.ENVIRONMENT_TOOLS.filter((id) => this.environmentSelected.has(id));
+        if (selected.length === 0) {
+            return;
+        }
+        const cwd = this.projectFolder;
+        this.commandRunning = true;
+        this.environmentNotice = undefined;
+        const abort = this.beginInstall();
+        let succeeded = false;
+        try {
+            for (const tool of selected) {
+                let result;
+                try {
+                    result = await this.deps.environment.install(tool, cwd, abort.signal);
+                }
+                catch {
+                    break;
+                }
+                if (abort.signal.aborted || !environmentInstallSucceeded(result)) {
+                    break;
+                }
+                succeeded = true;
+            }
+        }
+        finally {
+            this.endInstall();
+            this.commandRunning = false;
+        }
+        if (abort.signal.aborted) {
+            await this.checkEnvironment();
+            this.environmentNotice = ENVIRONMENT_ABORTED;
+        }
+        else if (succeeded) {
+            this.environmentNotice = REOPEN_TERMINAL;
+        }
+    }
+    environmentTools() {
+        return exports.ENVIRONMENT_TOOLS.map((id) => ({
+            id,
+            label: ENVIRONMENT_LABEL[id],
+            installed: this.environmentInstalled[id],
+            selected: this.environmentSelected.has(id),
+        }));
+    }
+    async copilotRequest(selection) {
+        const upstream = await this.serialConnectionOperation(() => this.copilotUpstream(selection));
+        if (upstream)
+            await this.deps.send(upstream);
+    }
+    async copilotUpstream(selection) {
+        if (selection !== "VCRouter") {
+            return;
+        }
+        if (!this.proxyRunning) {
+            throw new Error("VCRouter 目前無法使用。請先啟動 VansPod。");
+        }
+        await this.deps.proxy.receive({ provider: "VCRouter" });
+        return this.classroomUpstream("copilot");
+    }
+    async forward(request) {
+        // Only select a coherent connection and permissions under the lock; streaming stays concurrent.
+        const upstream = await this.serialConnectionOperation(() => this.forwardUpstream(request));
+        const outcome = await this.deps.send(withHttp(upstream, request));
+        // Only a successful request proves the client loaded the new settings and the route works.
+        if (!outcome.ok)
+            return forwardedRecord(upstream);
+        if (this.deps.clientRouteRuntime && request.client !== "copilot" && this.clientModes[request.client] === "classroom") {
+            const route = request.client === "codex" ? this.clientRoutes.codex : this.clientRoutes.claudeCode;
+            route.health = "green";
+            route.restart = "ready";
+            this.modelRestart = this.modelRestart.filter(client => client !== request.client);
+        }
+        if (this.deps.clientRouteRuntime && request.client === "copilot" && this.clientRoutes.vsCodeChat.mode === "classroom") {
+            this.clientRoutes.vsCodeChat.health = "green";
+            this.clientRoutes.vsCodeChat.restart = "ready";
+            this.modelRestart = this.modelRestart.filter(client => client !== "vscode");
+        }
+        return forwardedRecord(upstream);
+    }
+    async forwardUpstream(request) {
+        if (this.deps.clientRouteRuntime && !this.proxyRunning) {
+            if (request.client === "codex" && this.clientRoutes.codex.health === "red") {
+                throw new Error("Codex Client Route 尚未恢復。請重開 Codex 後再試。");
+            }
+            if (request.client === "claude" && this.clientRoutes.claudeCode.health === "red") {
+                throw new Error("Claude Code Client Route 尚未恢復。請重開 Claude Code CLI 後再試。");
+            }
+            if (request.client === "copilot" && this.clientRoutes.vsCodeChat.health === "red") {
+                throw new Error("VS Code Client Route 尚未恢復。請重開 VS Code 後再試。");
+            }
+        }
+        if (!this.proxyRunning) {
+            throw new Error(request.client === "copilot"
+                ? "VCRouter 目前無法使用。請先啟動 VansPod。"
+                : "代理沒有在跑。");
+        }
+        if (request.client === "copilot") {
+            if (this.deps.clientRouteRuntime && this.clientRoutes.vsCodeChat.mode === "native") {
+                throw new Error("VS Code 已切回 Native。請重開 VS Code 後再試。");
+            }
+            await this.deps.proxy.receive({ provider: "VCRouter" });
+            this.assertAllowedModel(request.model);
+            const upstream = await this.classroomUpstream("copilot", request.model);
+            if (!upstream) {
+                throw new Error("沒有上課模型。");
+            }
+            return upstream;
+        }
+        if (request.client === "codex" && this.deps.clientRouteRuntime && this.clientModes.codex === "native") {
+            throw new Error("Codex 已切回 Native。請重開 Codex 後再試。");
+        }
+        if (request.client === "claude" && this.deps.clientRouteRuntime && this.clientModes.claude === "native") {
+            throw new Error("Claude Code 已切回 Native。請重開 Claude Code CLI 後再試。");
+        }
+        if (this.clientModes[request.client] === "classroom") {
+            // Web Search is a switch on the Class Session that Router enforces, not a model on the allowlist.
+            if (!(0, modelProxy_1.isCodexSearch)(request.client, request.path))
+                this.assertAllowedModel(request.model);
+            const upstream = await this.classroomUpstream(request.client, request.model);
+            if (!upstream) {
+                throw new Error("沒有上課模型。");
+            }
+            return upstream;
+        }
+        const target = request.client === "codex" ? "chatgpt" : "claude.ai";
+        const upstream = {
+            client: request.client,
+            target,
+            model: request.model,
+        };
+        return upstream;
+    }
+    assertAllowedModel(requested) {
+        if (this.modelIds.length === 0)
+            return;
+        const id = requested?.startsWith("VCRouter/")
+            ? requested.slice("VCRouter/".length)
+            : requested;
+        if (!id || !this.modelIds.includes(id)) {
+            throw new Error(`模型 ${id || "(missing)"} 不在課堂允許清單。`);
+        }
+    }
+    async classroomUpstream(client, requested) {
+        if (!this.connected)
+            return undefined;
+        let apiKey;
+        try {
+            apiKey = (await this.deps.storage.getConnection())?.apiKey;
+        }
+        catch {
+            return undefined;
+        }
+        const model = this.classroomModel(client, requested);
+        if (!apiKey || !model) {
+            return undefined;
+        }
+        return {
+            client,
+            target: "router",
+            model,
+            apiKey,
+            adapter: client === "copilot" ? this.clientRoutes.vsCodeChat.adapter : this.adapters[client],
+        };
+    }
+    async setAdapter(client, id) {
+        if (client === "vscode") {
+            if (id !== "responses" && id !== "chat")
+                throw new Error("無效的 VS Code adapter。");
+            await this.serialConnectionOperation(() => this.setVsCodeAdapter(id));
+            return;
+        }
+        if (!(0, adapterSettings_1.isAdapterChoice)(client, id))
+            throw new Error(`無效的 ${client === "codex" ? "Codex" : "Claude Code"} adapter。`);
+        await this.serialConnectionOperation(async () => {
+            if (client === "codex" && this.deps.clientRouteRuntime) {
+                if (this.clientRoutes.codex.health === "red" || this.clientRoutes.codex.health === "gray") {
+                    this.adapterNotice = "Codex Client Route 目前無法變更 adapter。";
+                    return;
+                }
+                const previous = this.clientRoutes.codex.adapter;
+                this.clientRoutes.codex.adapter = id;
+                try {
+                    await this.saveClientRoutePreferences();
+                }
+                catch {
+                    this.clientRoutes.codex.adapter = previous;
+                    this.adapterNotice = "無法儲存 adapter 選擇，已保留原本設定。";
+                    return;
+                }
+                this.adapters = { ...this.adapters, codex: id === "messages" ? "responses" : id };
+                if (this.clientRoutes.codex.mode === "classroom") {
+                    this.clientRoutes.codex.health = "yellow";
+                    this.clientRoutes.codex.restart = "restart-required";
+                }
+                this.adapterNotice = undefined;
+                return;
+            }
+            if (client === "claude" && this.deps.clientRouteRuntime) {
+                const route = this.clientRoutes.claudeCode;
+                if (route.health === "red" || route.health === "gray") {
+                    this.adapterNotice = "Claude Code Client Route 目前無法變更 adapter。";
+                    return;
+                }
+                const previous = route.adapter;
+                route.adapter = id;
+                try {
+                    await this.saveClientRoutePreferences();
+                }
+                catch {
+                    route.adapter = previous;
+                    this.adapterNotice = "無法儲存 adapter 選擇，已保留原本設定。";
+                    return;
+                }
+                this.adapters = { ...this.adapters, claude: id };
+                if (route.mode === "classroom") {
+                    route.health = "yellow";
+                    route.restart = "restart-required";
+                }
+                this.adapterNotice = undefined;
+                return;
+            }
+            if (this.clientModes[client] !== "classroom") {
+                this.adapterNotice = "請先將這個客戶端切換到課堂模式。";
+                return;
+            }
+            const next = { ...this.adapters, [client]: id };
+            try {
+                await this.deps.adapterSettings?.save(next);
+            }
+            catch {
+                this.adapterNotice = "無法儲存 adapter 選擇，已保留原本設定。";
+                return;
+            }
+            this.adapters = next;
+            this.adapterNotice = undefined;
+        });
+    }
+    classroomModel(client, requested) {
+        const first = this.modelIds[0];
+        if (!first) {
+            return undefined;
+        }
+        const id = requested?.startsWith("VCRouter/")
+            ? requested.slice("VCRouter/".length)
+            : requested;
+        if (id && this.modelIds.includes(id)) {
+            this.sending.set(client, id);
+            return id;
+        }
+        return this.sending.get(client) ?? first;
+    }
+    visibleNotice() {
+        const parts = [];
+        if (this.notice) {
+            parts.push(this.notice);
+        }
+        if (this.allowlistError)
+            parts.push(this.allowlistError);
+        return parts.length > 0 ? parts.join(" ") : undefined;
+    }
+    forgetModelChoices() {
+        this.sending.clear();
+    }
+    async publishModelOptions(updateClient) {
+        const first = this.modelIds[0];
+        if (!first || this.mode !== "classroom") {
+            await this.restoreModelOptions();
+            return;
+        }
+        const options = this.codexClassroomOptions(first);
+        if (updateClient !== "claude") {
+            const mode = this.deps.clientRouteRuntime ? this.clientRoutes.codex.mode : this.clientModes.codex;
+            await this.codexLifecycle().write(mode, options);
+        }
+    }
+    codexClassroomOptions(first = this.modelIds[0]) {
+        return {
+            mode: "classroom",
+            ids: [...this.modelIds],
+            selectedModel: this.sending.get("codex") ?? first,
+            proxyBaseUrl: this.clientRouteOrigins.codex ?? this.deps.proxyBaseUrl,
+            restart: true,
+        };
+    }
+    async restoreModelOptions() {
+        await this.deps.routes.setCodexRoute({ mode: "native", proxyBaseUrl: this.deps.proxyBaseUrl });
+    }
+    codexLifecycle() {
+        const route = this.clientRoutes.codex;
+        const origin = this.clientRouteOrigins.codex ?? this.deps.proxyBaseUrl;
+        return {
+            route,
+            write: (mode, classroom) => this.deps.routes.setCodexRoute(mode === "classroom" ? classroom ?? this.codexClassroomOptions() : { mode: "native", proxyBaseUrl: origin }),
+            setMode: (mode) => {
+                route.mode = mode;
+                this.clientModes.codex = mode;
+            },
+            setState: (mode, health, restart = "ready") => {
+                route.mode = mode;
+                route.health = health;
+                route.restart = restart;
+                this.clientModes.codex = mode;
+            },
+            stop: async () => {
+                await this.deps.routes.setCodexRoute({ mode: "native", proxyBaseUrl: origin });
+                await this.deps.clientRouteRuntime?.stop("codex");
+            },
+        };
+    }
+    prepare(actionId) {
+        if (this.commandRunning || !this.projectFolder) {
+            return;
+        }
+        const action = this.catalog?.actions.find((item) => item.id === actionId);
+        if (!action) {
+            return;
+        }
+        this.pendingCommand = action.command;
+        this.pendingActionId = action.id;
+        this.commandOutput = undefined;
+        this.commandAborted = undefined;
+        this.commandSucceeded = undefined;
+    }
+    async confirm() {
+        if (this.stopping || this.commandRunning || !this.projectFolder || !this.pendingCommand) {
+            return;
+        }
+        const cwd = this.projectFolder;
+        const command = this.pendingCommand;
+        const actionId = this.pendingActionId;
+        this.commandRunning = true;
+        this.commandOutput = undefined;
+        this.commandSucceeded = undefined;
+        this.commandAborted = undefined;
+        const abort = this.beginInstall();
+        try {
+            const result = await this.deps.commands.run(cwd, command, (output) => {
+                this.commandOutput = output;
+            }, abort.signal);
+            this.commandOutput = result.output;
+            if (result.aborted)
+                this.commandAborted = true;
+            this.commandSucceeded = !result.aborted && result.exitCode === 0;
+            if (this.commandSucceeded && actionId) {
+                let installed = this.installedActions.get(cwd);
+                if (!installed) {
+                    installed = new Map();
+                    this.installedActions.set(cwd, installed);
+                }
+                installed.set(actionId, command);
+            }
+        }
+        catch {
+            this.commandOutput = "指令執行失敗。";
+            this.commandSucceeded = false;
+        }
+        finally {
+            this.pendingCommand = undefined;
+            this.pendingActionId = undefined;
+            this.endInstall();
+            this.commandRunning = false;
+        }
+    }
+    beginInstall() {
+        const abort = new AbortController();
+        let settle;
+        const settled = new Promise((resolve) => { settle = resolve; });
+        this.runningInstall = { abort, settled, settle };
+        return abort;
+    }
+    endInstall() {
+        this.runningInstall?.settle();
+        this.runningInstall = undefined;
+    }
+    /** Abort Install：學生確認後終止執行中的安裝；沒有安裝時不做事。 */
+    async abortInstall() {
+        const install = this.runningInstall;
+        install?.abort.abort();
+        await install?.settled;
+    }
+    cancel() {
+        if (this.commandRunning) {
+            return;
+        }
+        this.pendingCommand = undefined;
+        this.pendingActionId = undefined;
+    }
+    async redeem(inviteCode, nickname) {
+        return this.serialConnectionOperation(() => this.redeemNow(inviteCode, nickname));
+    }
+    async redeemNow(inviteCode, nickname) {
+        const invite = inviteCode.trim();
+        const name = nickname.trim();
+        this.connectionError = undefined;
+        this.connectionDraft = { inviteCode, nickname };
+        if (!invite || !name) {
+            this.connectionError = "請先輸入邀請碼與課堂暱稱，再按「連線」。";
+            if (!this.connected)
+                this.detail = "";
+            this.notice = undefined;
+            return;
+        }
+        let redeemed;
+        try {
+            redeemed = await this.deps.router.redeemNickname({
+                invite_code: invite,
+                nickname: name,
+            });
+        }
+        catch {
+            if (!this.connected) {
+                this.connectionError = "連線失敗，請確認邀請碼與課堂暱稱後再試。";
+                this.detail = "";
+                this.notice = undefined;
+            }
+            return;
+        }
+        const connection = { version: 1, apiKey: redeemed?.api_key, session: redeemed?.session, nickname: name };
+        if (!(0, secureStorage_1.isClassroomConnection)(connection)) {
+            this.notice = this.connectionNotice = "兌換回應資料格式不正確，已保留原有課堂連線。請稍後再試。";
+            return;
+        }
+        this.hiddenKeys.add(connection.apiKey);
+        try {
+            await this.deps.storage.setConnection(connection, { allowTemporary: true });
+        }
+        catch {
+            this.notice = this.connectionNotice = "無法安全保存或清除原有課堂連線，換堂未完成。請稍後再試。";
+            return;
+        }
+        const desiredMode = this.mode;
+        const desiredClientModes = { ...this.clientModes };
+        const desiredVsCodeMode = this.clientRoutes.vsCodeChat.mode;
+        // A committed new session must never inherit permissions or resources from the old one.
+        this.mode = "native";
+        this.clientRoutes.vsCodeChat.mode = "native";
+        this.clientRoutes.vsCodeChat.restart = "ready";
+        this.modelIds = [];
+        this.modelProviders = [];
+        this.allowlistError = undefined;
+        this.forgetModelChoices();
+        this.catalog = undefined;
+        this.catalogError = undefined;
+        this.remoteCatalogHeld = false;
+        this.pendingCommand = undefined;
+        this.pendingActionId = undefined;
+        this.applyConnectionIdentity(connection);
+        this.connectionDraft = undefined;
+        this.notice = undefined;
+        // Storage is committed: publish its identity before any client-file operation can fail.
+        if (desiredVsCodeMode === "classroom") {
+            try {
+                await this.deps.vsCodeRouteSettings?.restore();
+            }
+            catch {
+                this.clientRoutes.vsCodeChat.health = "red";
+                try {
+                    await this.saveClientRoutePreferences();
+                }
+                catch { /* Native/red remains authoritative in memory. */ }
+                this.notice = this.connectionNotice = "新課堂連線已建立，但無法恢復 VS Code 的 Native 設定。備份已保留，請稍後再試。";
+                return;
+            }
+        }
+        try {
+            await this.restoreModelOptions();
+        }
+        catch {
+            this.notice = this.connectionNotice = "新課堂連線已建立，但無法更新模型設定。目前使用 Native，請稍後再試。";
+            return;
+        }
+        await this.loadCatalog();
+        await this.loadModels(redeemed.api_key);
+        if (desiredMode === "classroom" && this.modelIds.length > 0) {
+            this.mode = "classroom";
+            this.clientModes = desiredClientModes;
+            try {
+                await this.publishModelOptions();
+            }
+            catch {
+                this.mode = "native";
+                this.modelIds = [];
+                this.forgetModelChoices();
+                try {
+                    await this.restoreModelOptions();
+                }
+                catch { /* Keep proxy routing safely Native. */ }
+                this.notice = this.connectionNotice = "新課堂連線已建立，但無法更新模型設定。目前使用 Native，請稍後再試。";
+            }
+        }
+        if (desiredVsCodeMode === "classroom" && this.modelIds.length > 0 && this.vsCodeOrigin) {
+            this.clientRoutes.vsCodeChat.mode = "classroom";
+            try {
+                const result = await this.deps.vsCodeRouteSettings?.publish({
+                    providers: this.modelProviders,
+                    adapter: this.clientRoutes.vsCodeChat.adapter,
+                    origin: this.vsCodeOrigin,
+                });
+                this.settleVsCodePublish(result?.changed);
+            }
+            catch (error) {
+                this.clientRoutes.vsCodeChat.mode = "native";
+                this.clientRoutes.vsCodeChat.health = "red";
+                this.clientRoutes.vsCodeChat.restart = "ready";
+                this.notice = this.connectionNotice = error instanceof Error ? error.message : "新課堂連線已建立，但無法更新 VS Code 設定。";
+            }
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch {
+                this.clientRoutes.vsCodeChat.health = "red";
+            }
+        }
+    }
+    async setProjectFolder(folder) {
+        return this.serialConnectionOperation(() => this.setProjectFolderNow(folder));
+    }
+    async setProjectFolderNow(folder) {
+        if (this.commandRunning) {
+            return;
+        }
+        const next = folder.trim();
+        this.folderError = undefined;
+        this.projectFolder = next || undefined;
+        if (!this.remoteCatalogHeld) {
+            await this.loadCatalog();
+        }
+    }
+    rejectProjectFolder() {
+        this.folderError = "這不是資料夾。";
+    }
+    async setSwitch(mode, client) {
+        return this.serialConnectionOperation(() => client ? this.setClientSwitch(mode, client) : this.setSwitchNow(mode));
+    }
+    async setClientSwitch(mode, client) {
+        if (client === "vscode") {
+            await this.setVsCodeClientRouteSwitch(mode);
+            return;
+        }
+        if (client === "codex" && this.deps.clientRouteRuntime) {
+            await this.setCodexClientRouteSwitch(mode);
+            return;
+        }
+        if (client === "claude" && this.deps.clientRouteRuntime) {
+            await this.setClaudeCodeClientRouteSwitch(mode);
+            return;
+        }
+        if (mode === "classroom" && (!this.connected || this.modelIds.length === 0)) {
+            this.notice = "請先連線到有可用模型的課堂。";
+            return;
+        }
+        const previous = { ...this.clientModes };
+        if (previous[client] === mode && mode !== "native")
+            return;
+        const next = { ...previous, [client]: mode };
+        const aggregate = Object.values(next).includes("classroom") ? "classroom" : "native";
+        if (!await this.saveMode(aggregate, next))
+            return;
+        this.clientModes = next;
+        this.sending.delete(client);
+        try {
+            await this.publishModelOptions(client);
+            this.notice = undefined;
+            if (!this.modelRestart.includes(client))
+                this.modelRestart.push(client);
+            this.adapterNotice = undefined;
+        }
+        catch {
+            this.clientModes = previous;
+            let restored = true;
+            try {
+                await this.publishModelOptions(client);
+            }
+            catch {
+                restored = false;
+                this.mode = "native";
+                try {
+                    await this.restoreModelOptions();
+                }
+                catch { /* Surface partial recovery below. */ }
+            }
+            const persisted = await this.saveMode(this.mode, this.clientModes);
+            this.notice = "無法更新客戶端模型設定，請稍後再試。" +
+                (restored ? " 已保留原本模式。" : " 目前使用個人模式，部分客戶端設定需要重新檢查。") +
+                (persisted ? "" : " 無法儲存恢復後的模式，請重試。");
+        }
+    }
+    async setCodexClientRouteSwitch(mode) {
+        const lifecycle = this.codexLifecycle();
+        const route = lifecycle.route;
+        if (route.health === "red" || route.health === "gray") {
+            this.notice = "Codex Client Route 目前無法切換 Classroom。";
+            return;
+        }
+        if (mode === "classroom" && (!this.connected || this.modelIds.length === 0)) {
+            this.notice = "請先連線到有可用模型的課堂。";
+            return;
+        }
+        if (route.mode === mode)
+            return;
+        const previousRoute = { ...route };
+        const previousModes = { ...this.clientModes };
+        lifecycle.setMode(mode);
+        try {
+            // Preference persistence and the route-file journal both precede the client write.
+            await this.saveClientRoutePreferences();
+            const aggregate = Object.values(this.clientModes).includes("classroom") ? "classroom" : "native";
+            if (!await this.saveMode(aggregate, this.clientModes))
+                throw new Error("mode persistence failed");
+            await lifecycle.write(mode);
+            lifecycle.setState(mode, mode === "classroom" ? "yellow" : "green", mode === "classroom" ? "restart-required" : "ready");
+            route.adapter = this.adapters.codex;
+            this.notice = undefined;
+            this.adapterNotice = undefined;
+        }
+        catch {
+            this.clientRoutes.codex = previousRoute;
+            this.clientModes = previousModes;
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch { /* Keep the rollback visible in memory. */ }
+            try {
+                await this.codexLifecycle().write(previousRoute.mode);
+            }
+            catch { /* The route remains in its previous mode. */ }
+            this.notice = "無法更新 Codex Client Route，已保留原本模式。";
+        }
+    }
+    async setVsCodeClientRouteSwitch(mode) {
+        const route = this.clientRoutes.vsCodeChat;
+        if (route.health === "red" || route.health === "gray") {
+            this.notice = "VS Code Chat Client Route 目前無法切換 Classroom。";
+            return;
+        }
+        if (mode === "classroom" && (!this.connected || this.modelIds.length === 0 || !this.vsCodeOrigin)) {
+            this.notice = "請先連線到有可用模型的課堂。";
+            return;
+        }
+        if (route.mode === mode)
+            return;
+        const previous = { ...route };
+        route.mode = mode;
+        try {
+            await this.saveClientRoutePreferences();
+            const result = mode === "classroom"
+                ? await this.deps.vsCodeRouteSettings?.publish({ providers: this.modelProviders, adapter: route.adapter, origin: this.vsCodeOrigin })
+                : await this.deps.vsCodeRouteSettings?.restore();
+            if (mode === "classroom")
+                this.settleVsCodePublish(result?.changed);
+            else {
+                route.health = "green";
+                route.restart = "ready";
+                if (result?.changed)
+                    this.noteModelRestart("vscode");
+            }
+            this.notice = undefined;
+        }
+        catch (error) {
+            this.clientRoutes.vsCodeChat = previous;
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch { /* Keep visible state. */ }
+            if (String(error).includes("舊擴充") || String(error).includes("ownership") || String(error).includes("其他程式")) {
+                this.clientRoutes.vsCodeChat.health = "red";
+                this.notice = error instanceof Error ? error.message : "VS Code VCRouter provider 衝突。";
+            }
+            else {
+                this.notice = "無法更新 VS Code Chat Client Route，已保留原本模式。";
+            }
+        }
+    }
+    async setVsCodeAdapter(id) {
+        const route = this.clientRoutes.vsCodeChat;
+        if (route.health === "red" || route.health === "gray") {
+            this.adapterNotice = "VS Code Chat Client Route 目前無法變更 adapter。";
+            return;
+        }
+        const previous = route.adapter;
+        route.adapter = id;
+        try {
+            await this.saveClientRoutePreferences();
+            if (route.mode === "classroom") {
+                const result = await this.deps.vsCodeRouteSettings?.publish({ providers: this.modelProviders, adapter: id, origin: this.vsCodeOrigin });
+                if (result?.changed) {
+                    route.health = "yellow";
+                    route.restart = "restart-required";
+                    this.noteModelRestart("vscode");
+                }
+            }
+            this.adapterNotice = undefined;
+        }
+        catch {
+            route.adapter = previous;
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch { /* Keep rollback in memory. */ }
+            this.adapterNotice = "無法更新 VS Code adapter，已保留原本設定。";
+        }
+    }
+    async setClaudeCodeClientRouteSwitch(mode) {
+        const route = this.clientRoutes.claudeCode;
+        if (route.health === "red" || route.health === "gray") {
+            this.notice = "Claude Code Client Route 目前無法切換 Classroom。";
+            return;
+        }
+        if (mode === "classroom" && (!this.connected || this.modelIds.length === 0)) {
+            this.notice = "請先連線到有可用模型的課堂。";
+            return;
+        }
+        if (route.mode === mode)
+            return;
+        const previousRoute = { ...route };
+        const previousModes = { ...this.clientModes };
+        route.mode = mode;
+        this.clientModes.claude = mode;
+        try {
+            await this.saveClientRoutePreferences();
+            const aggregate = Object.values(this.clientModes).includes("classroom") ? "classroom" : "native";
+            if (!await this.saveMode(aggregate, this.clientModes))
+                throw new Error("mode persistence failed");
+            await this.deps.routes.setClaudeCodeRoute(mode === "classroom", this.clientRouteOrigins.claudeCode ?? this.deps.proxyBaseUrl, this.modelIds[0]);
+            route.health = mode === "classroom" ? "yellow" : "green";
+            route.restart = mode === "classroom" ? "restart-required" : "ready";
+            this.notice = undefined;
+            this.adapterNotice = undefined;
+        }
+        catch {
+            this.clientRoutes.claudeCode = previousRoute;
+            this.clientModes = previousModes;
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch { /* Keep the rollback visible in memory. */ }
+            try {
+                await this.deps.routes.setClaudeCodeRoute(previousRoute.mode === "classroom", this.clientRouteOrigins.claudeCode ?? this.deps.proxyBaseUrl, this.modelIds[0]);
+            }
+            catch { /* The visible route state remains authoritative. */ }
+            this.notice = "無法更新 Claude Code Client Route，已保留原本模式。";
+        }
+    }
+    async setSwitchNow(mode) {
+        const requested = mode === "classroom" && this.connected && this.modelIds.length > 0 ? "classroom" : "native";
+        if (!await this.saveMode(requested))
+            return;
+        const entering = Object.values(this.clientModes).some(mode => mode !== requested);
+        this.mode = requested;
+        if (entering || requested === "native")
+            this.forgetModelChoices();
+        try {
+            if (requested === "classroom")
+                await this.publishModelOptions();
+            else
+                await this.restoreModelOptions();
+            if (entering)
+                this.modelRestart = ["codex", "claude"];
+        }
+        catch {
+            // Sequential client-file writes may have partially succeeded. Upstream must be safe immediately.
+            this.mode = "native";
+            this.forgetModelChoices();
+            let restored = true;
+            try {
+                await this.restoreModelOptions();
+            }
+            catch {
+                restored = false;
+            }
+            const persisted = requested === "native" || await this.saveMode("native");
+            this.notice = "無法更新模型設定。目前使用 Native，請稍後再試。" +
+                (restored ? "" : " 部分客戶端設定無法恢復，請重試或手動檢查。") +
+                (persisted ? "" : " 無法儲存 Native 模式，重新啟動仍可能恢復 Classroom；請重試。");
+        }
+    }
+    async saveMode(mode, clientModes = { codex: mode, claude: mode }) {
+        try {
+            const connection = await this.deps.storage.getConnection();
+            if (connection && !this.deps.clientRouteSettings) {
+                await this.deps.storage.setConnection({ ...connection, mode, clientModes }, { allowTemporary: false });
+            }
+            this.notice = undefined;
+            return true;
+        }
+        catch {
+            this.notice = "無法儲存模型模式。已保留原本模式，請稍後再試。";
+            return false;
+        }
+    }
+    async reloadCatalog() {
+        return this.serialConnectionOperation(() => this.loadCatalog());
+    }
+    async reloadAllowlist() {
+        await this.detectClients();
+        await this.deps.routes.migrateLegacyState(this.deps.proxyBaseUrl, this.detectedClients);
+        if (this.deps.clientRouteRuntime) {
+            await this.startCodexRoute();
+            await this.startClaudeCodeRoute();
+            await this.startVsCodeRoute();
+        }
+        return this.serialConnectionOperation(() => this.reloadAllowlistNow());
+    }
+    async saveClientRoutePreferences() {
+        await this.deps.clientRouteSettings?.save({
+            codex: { mode: this.clientRoutes.codex.mode, adapter: this.clientRoutes.codex.adapter },
+            claudeCode: { mode: this.clientRoutes.claudeCode.mode, adapter: this.clientRoutes.claudeCode.adapter },
+            vsCodeChat: { mode: this.clientRoutes.vsCodeChat.mode, adapter: this.clientRoutes.vsCodeChat.adapter },
+        });
+    }
+    async startCodexRoute() {
+        const runtime = this.deps.clientRouteRuntime;
+        if (!runtime)
+            return;
+        let lifecycle = this.codexLifecycle();
+        if (!this.detectedClients.codex) {
+            lifecycle.setState("native", "gray");
+            return;
+        }
+        const alreadyRunning = runtime.current?.("codex")?.health === "green";
+        const restartPending = this.clientRoutes.codex.health === "yellow" &&
+            this.clientRoutes.codex.restart === "restart-required";
+        const retryingNativeRecovery = this.clientRoutes.codex.health === "red" && this.clientRoutes.codex.mode === "native";
+        let health = "red";
+        try {
+            const started = await runtime.start("codex");
+            this.clientRouteOrigins.codex = started.origin;
+            health = started.health === "green" ? "green" : "red";
+        }
+        catch {
+            health = "red";
+        }
+        if (health === "red") {
+            lifecycle.setState("native", "red");
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch { /* The visible red state remains authoritative. */ }
+            try {
+                await lifecycle.write("native");
+            }
+            catch { /* Retried on reload. */ }
+            return;
+        }
+        lifecycle = this.codexLifecycle(); // start() supplied the route's authoritative origin.
+        if (this.clientRoutes.codex.mode === "classroom" && (!this.connected || this.modelIds.length === 0)) {
+            lifecycle.setMode("native");
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch { /* Native remains the safe runtime state. */ }
+        }
+        if (retryingNativeRecovery) {
+            try {
+                await lifecycle.write("native");
+            }
+            catch {
+                lifecycle.setState("native", "red");
+                return;
+            }
+        }
+        this.clientModes.codex = this.clientRoutes.codex.mode === "classroom" && this.connected && this.modelIds.length > 0
+            ? "classroom"
+            : "native";
+        if (alreadyRunning && restartPending && this.clientModes.codex === "classroom")
+            return;
+        // Listener recovery never restores Classroom automatically after a red failure.
+        lifecycle.setState(this.clientModes.codex, "green");
+        if (!alreadyRunning && this.clientModes.codex === "classroom") {
+            try {
+                await lifecycle.write("classroom");
+                lifecycle.setState("classroom", "yellow", "restart-required");
+            }
+            catch {
+                lifecycle.setState("native", "red");
+                try {
+                    await this.saveClientRoutePreferences();
+                }
+                catch { /* Visible red state wins. */ }
+            }
+        }
+    }
+    async startVsCodeRoute() {
+        const runtime = this.deps.clientRouteRuntime;
+        if (!runtime)
+            return;
+        const retryingNativeRecovery = this.clientRoutes.vsCodeChat.health === "red" && this.clientRoutes.vsCodeChat.mode === "native";
+        if (!this.detectedClients.vsCodeChat) {
+            this.clientRoutes.vsCodeChat = { ...this.clientRoutes.vsCodeChat, mode: "native", health: "gray", restart: "ready" };
+            return;
+        }
+        const alreadyRunning = this.vsCodeOrigin !== undefined &&
+            (this.clientRoutes.vsCodeChat.health === "green" || this.clientRoutes.vsCodeChat.health === "yellow") &&
+            (runtime.current?.("vsCodeChat")?.health ?? "green") === "green";
+        let started;
+        try {
+            started = await runtime.start("vsCodeChat");
+        }
+        catch {
+            await this.failVsCodeRouteStart();
+            return;
+        }
+        this.vsCodeOrigin = started.origin;
+        if (started.health !== "green") {
+            await this.failVsCodeRouteStart();
+            return;
+        }
+        if (retryingNativeRecovery) {
+            try {
+                await this.deps.vsCodeRouteSettings?.restore();
+                this.clientRoutes.vsCodeChat.health = "green";
+                this.clientRoutes.vsCodeChat.restart = "ready";
+            }
+            catch {
+                this.clientRoutes.vsCodeChat.health = "red";
+                this.clientRoutes.vsCodeChat.restart = "ready";
+            }
+            return;
+        }
+        if (alreadyRunning)
+            return;
+        try {
+            if (this.clientRoutes.vsCodeChat.mode === "classroom" && this.connected && this.modelIds.length > 0) {
+                const result = await this.deps.vsCodeRouteSettings?.publish({
+                    providers: this.modelProviders,
+                    adapter: this.clientRoutes.vsCodeChat.adapter,
+                    origin: started.origin,
+                });
+                this.settleVsCodePublish(result?.changed);
+            }
+            else {
+                this.clientRoutes.vsCodeChat.mode = "native";
+                await this.deps.vsCodeRouteSettings?.initializeNative();
+                this.clientRoutes.vsCodeChat.health = "green";
+                this.clientRoutes.vsCodeChat.restart = "ready";
+            }
+        }
+        catch (error) {
+            this.clientRoutes.vsCodeChat.mode = "native";
+            this.clientRoutes.vsCodeChat.health = "red";
+            this.clientRoutes.vsCodeChat.restart = "ready";
+            this.notice = error instanceof Error ? error.message : "VS Code Chat Client Route 設定失敗。";
+        }
+        try {
+            await this.saveClientRoutePreferences();
+        }
+        catch { /* Route health remains visible. */ }
+    }
+    async failVsCodeRouteStart() {
+        try {
+            await this.deps.vsCodeRouteSettings?.restore();
+        }
+        catch { /* Journal remains available for retry. */ }
+        this.clientRoutes.vsCodeChat = { ...this.clientRoutes.vsCodeChat, mode: "native", health: "red", restart: "ready" };
+        try {
+            await this.saveClientRoutePreferences();
+        }
+        catch { /* Visible red state wins. */ }
+    }
+    async startClaudeCodeRoute() {
+        const runtime = this.deps.clientRouteRuntime;
+        if (!runtime)
+            return;
+        const route = this.clientRoutes.claudeCode;
+        const retryingNativeRecovery = route.health === "red" && route.mode === "native";
+        if (!this.detectedClients.claude) {
+            route.mode = "native";
+            route.health = "gray";
+            route.restart = "ready";
+            this.clientModes.claude = "native";
+            return;
+        }
+        const alreadyRunning = runtime.current?.("claudeCode")?.health === "green";
+        const restartPending = route.health === "yellow" && route.restart === "restart-required";
+        let health = "red";
+        try {
+            const started = await runtime.start("claudeCode");
+            this.clientRouteOrigins.claudeCode = started.origin;
+            health = started.health === "green" ? "green" : "red";
+        }
+        catch {
+            health = "red";
+        }
+        if (health === "red") {
+            route.mode = "native";
+            route.health = "red";
+            route.restart = "ready";
+            this.clientModes.claude = "native";
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch { /* The visible red state remains authoritative. */ }
+            try {
+                await this.deps.routes.setClaudeCodeRoute(false, this.clientRouteOrigins.claudeCode ?? this.deps.proxyBaseUrl);
+            }
+            catch { /* Retried on reload. */ }
+            return;
+        }
+        if (route.mode === "classroom" && (!this.connected || this.modelIds.length === 0)) {
+            route.mode = "native";
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch { /* Native remains the safe runtime state. */ }
+        }
+        if (retryingNativeRecovery) {
+            try {
+                await this.deps.routes.setClaudeCodeRoute(false, this.clientRouteOrigins.claudeCode ?? this.deps.proxyBaseUrl);
+            }
+            catch {
+                route.health = "red";
+                route.restart = "ready";
+                return;
+            }
+        }
+        this.clientModes.claude = route.mode === "classroom" && this.connected && this.modelIds.length > 0
+            ? "classroom"
+            : "native";
+        if (alreadyRunning && restartPending && this.clientModes.claude === "classroom")
+            return;
+        route.health = "green";
+        route.restart = "ready";
+        if (alreadyRunning)
+            return;
+        try {
+            await this.deps.routes.setClaudeCodeRoute(this.clientModes.claude === "classroom", this.clientRouteOrigins.claudeCode ?? this.deps.proxyBaseUrl, this.modelIds[0]);
+            if (this.clientModes.claude === "classroom") {
+                route.health = "yellow";
+                route.restart = "restart-required";
+            }
+        }
+        catch {
+            route.mode = "native";
+            route.health = "red";
+            route.restart = "ready";
+            this.clientModes.claude = "native";
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch { /* The visible red state remains authoritative. */ }
+        }
+    }
+    async detectClients() {
+        await Promise.all(["codex", "claude", "vsCodeChat"].map(async (client) => {
+            try {
+                this.detectedClients[client] = await this.deps.detectClient?.(client) ?? false;
+            }
+            catch {
+                this.detectedClients[client] = false;
+            }
+        }));
+    }
+    async reloadAllowlistNow() {
+        if (!this.connected)
+            return;
+        const apiKey = (await this.deps.storage.getConnection())?.apiKey;
+        if (!apiKey) {
+            return;
+        }
+        const previous = this.mode === "classroom" ? this.modelIds.join("\0") : "";
+        const refreshed = await this.loadModels(apiKey);
+        this.allowlistError = refreshed
+            ? undefined
+            : "重新載入課堂模型失敗，已保留上次成功的模型清單。";
+        const current = this.mode === "classroom" ? this.modelIds.join("\0") : "";
+        if (previous !== current) {
+            this.modelRestart = ["codex", "claude"].filter(client => this.clientModes[client] === "classroom");
+            if (this.deps.clientRouteRuntime) {
+                if (this.clientRoutes.codex.mode === "classroom") {
+                    this.clientRoutes.codex.health = "yellow";
+                    this.clientRoutes.codex.restart = "restart-required";
+                }
+                if (this.clientRoutes.claudeCode.mode === "classroom") {
+                    this.clientRoutes.claudeCode.health = "yellow";
+                    this.clientRoutes.claudeCode.restart = "restart-required";
+                }
+            }
+        }
+    }
+    async loadModels(apiKey) {
+        let payload;
+        try {
+            payload = await this.deps.router.fetchSessionModels(apiKey);
+        }
+        catch {
+            return false;
+        }
+        if (!Array.isArray(payload))
+            return false;
+        const items = payload;
+        const stringPayload = items.every(item => typeof item === "string");
+        const providerPayload = items.every(item => !!item && typeof item === "object" && !Array.isArray(item));
+        if (!stringPayload && !providerPayload)
+            return false;
+        const providers = stringPayload ? [] : items;
+        const ids = [];
+        if (stringPayload) {
+            ids.push(...items);
+        }
+        else {
+            for (const provider of providers) {
+                if (!Array.isArray(provider.models))
+                    return false;
+                for (const model of provider.models) {
+                    const id = model && typeof model === "object" && !Array.isArray(model)
+                        ? model.id
+                        : undefined;
+                    if (typeof id !== "string" || !id.trim())
+                        return false;
+                    ids.push(id);
+                }
+            }
+        }
+        if (ids.length === 0 || ids.some(id => !id.trim())) {
+            this.modelIds = [];
+            this.modelProviders = [];
+            this.mode = "native";
+            if (this.deps.clientRouteRuntime) {
+                this.codexLifecycle().setMode("native");
+                this.clientRoutes.claudeCode.mode = "native";
+                this.clientRoutes.vsCodeChat.mode = "native";
+                this.clientRoutes.codex.restart = "ready";
+                this.clientRoutes.claudeCode.restart = "ready";
+                this.clientRoutes.vsCodeChat.restart = "ready";
+                try {
+                    await this.saveClientRoutePreferences();
+                }
+                catch {
+                    this.clientRoutes.codex.health = "red";
+                    this.clientRoutes.claudeCode.health = "red";
+                    this.clientRoutes.vsCodeChat.health = "red";
+                }
+                try {
+                    await this.deps.routes.setClaudeCodeRoute(false, this.clientRouteOrigins.claudeCode ?? this.deps.proxyBaseUrl);
+                    if (this.clientRoutes.claudeCode.health !== "red") {
+                        this.clientRoutes.claudeCode.health = this.detectedClients.claude ? "green" : "gray";
+                    }
+                }
+                catch {
+                    this.clientRoutes.claudeCode.health = "red";
+                }
+                try {
+                    await this.deps.vsCodeRouteSettings?.restore();
+                    if (this.clientRoutes.vsCodeChat.health !== "red") {
+                        this.clientRoutes.vsCodeChat.health = this.detectedClients.vsCodeChat ? "green" : "gray";
+                    }
+                }
+                catch {
+                    this.clientRoutes.vsCodeChat.health = "red";
+                }
+            }
+            this.forgetModelChoices();
+            if (this.deps.clientRouteRuntime) {
+                try {
+                    await this.codexLifecycle().write("native");
+                    if (this.clientRoutes.codex.health !== "red") {
+                        this.clientRoutes.codex.health = this.detectedClients.codex ? "green" : "gray";
+                    }
+                }
+                catch {
+                    this.clientRoutes.codex.health = "red";
+                }
+            }
+            else {
+                await this.restoreModelOptions();
+            }
+            return true;
+        }
+        const previous = this.modelIds;
+        const providersChanged = !(0, node_util_1.isDeepStrictEqual)(this.modelProviders, providers);
+        const changed = previous.join("\0") !== ids.join("\0");
+        this.modelIds = ids;
+        this.modelProviders = structuredClone(providers);
+        if (providersChanged && this.deps.clientRouteRuntime && this.clientRoutes.vsCodeChat.mode === "classroom" && this.vsCodeOrigin) {
+            try {
+                const result = await this.deps.vsCodeRouteSettings?.publish({
+                    providers: this.modelProviders,
+                    adapter: this.clientRoutes.vsCodeChat.adapter,
+                    origin: this.vsCodeOrigin,
+                });
+                if (result?.changed) {
+                    this.clientRoutes.vsCodeChat.health = "yellow";
+                    this.clientRoutes.vsCodeChat.restart = "restart-required";
+                    this.noteModelRestart("vscode");
+                }
+            }
+            catch (error) {
+                this.clientRoutes.vsCodeChat.health = "red";
+                this.notice = error instanceof Error ? error.message : "VS Code Chat Client Route 設定失敗。";
+            }
+        }
+        if (!changed || this.mode !== "classroom") {
+            return true;
+        }
+        for (const client of PROXY_CLIENTS) {
+            const current = this.sending.get(client);
+            if (!current || ids.includes(current)) {
+                continue;
+            }
+            this.sending.delete(client);
+        }
+        await this.publishModelOptions();
+        if (this.clientModes.claude === "classroom" && previous[0] !== ids[0]) {
+            try {
+                await this.deps.routes.setClaudeCodeRoute(true, this.clientRouteOrigins.claudeCode ?? this.deps.proxyBaseUrl, ids[0]);
+            }
+            catch {
+                this.notice = "無法更新 Claude Code 的課堂模型選項。";
+            }
+        }
+        return true;
+    }
+    async copyKey() {
+        return this.serialConnectionOperation(() => this.copyKeyNow());
+    }
+    async copyKeyNow() {
+        this.connectionError = undefined;
+        try {
+            const apiKey = this.connected ? (await this.deps.storage.getConnection())?.apiKey : undefined;
+            if (!apiKey) {
+                this.notice = this.connectionNotice = "無法複製 Classroom API Key。請重新連線後再試。";
+                return;
+            }
+            await this.deps.clipboard.write(apiKey);
+        }
+        catch {
+            this.notice = this.connectionNotice = "無法複製 Classroom API Key。請重新連線後再試。";
+            return;
+        }
+        this.notice = this.connectionNotice = "已複製 Classroom API Key。請勿分享給不信任的人。";
+    }
+    async copySnippet(snippetId) {
+        const snippet = this.catalog?.snippets?.find((item) => item.id === snippetId);
+        if (!snippet)
+            return false;
+        try {
+            await this.deps.clipboard.write(snippet.body);
+            this.copiedSnippets.set(snippet.id, snippet.body);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async clearConnection() {
+        return this.serialConnectionOperation(() => this.clearConnectionNow());
+    }
+    async clearConnectionNow() {
+        try {
+            await this.deps.storage.clearConnection();
+        }
+        catch {
+            this.notice = this.connectionNotice = "無法清除課堂連線。已保留原本連線，重新啟動後仍可能恢復。請稍後再試。";
+            return;
+        }
+        this.applyConnectionIdentity(undefined);
+        this.connectionError = undefined;
+        this.connectionDraft = undefined;
+        this.notice = undefined;
+        this.allowlistError = undefined;
+        this.catalog = undefined;
+        this.catalogError = undefined;
+        this.remoteCatalogHeld = false;
+        this.mode = "native";
+        if (this.deps.clientRouteRuntime) {
+            this.codexLifecycle().setMode("native");
+            this.clientRoutes.codex.restart = "ready";
+            this.clientRoutes.claudeCode.mode = "native";
+            this.clientRoutes.claudeCode.restart = "ready";
+            this.clientRoutes.vsCodeChat.mode = "native";
+            this.clientRoutes.vsCodeChat.restart = "ready";
+            try {
+                await this.saveClientRoutePreferences();
+            }
+            catch {
+                this.clientRoutes.codex.health = "red";
+                this.clientRoutes.claudeCode.health = "red";
+                this.clientRoutes.vsCodeChat.health = "red";
+            }
+        }
+        this.modelIds = [];
+        this.forgetModelChoices();
+        let restoreFailed = false;
+        try {
+            if (this.deps.clientRouteRuntime)
+                await this.codexLifecycle().write("native");
+            else
+                await this.restoreModelOptions();
+            if (this.deps.clientRouteRuntime && this.clientRoutes.codex.health !== "red") {
+                this.clientRoutes.codex.health = this.detectedClients.codex ? "green" : "gray";
+            }
+        }
+        catch {
+            restoreFailed = true;
+            if (this.deps.clientRouteRuntime)
+                this.clientRoutes.codex.health = "red";
+        }
+        if (this.deps.clientRouteRuntime) {
+            try {
+                await this.deps.routes.setClaudeCodeRoute(false, this.clientRouteOrigins.claudeCode ?? this.deps.proxyBaseUrl);
+                if (this.clientRoutes.claudeCode.health !== "red") {
+                    this.clientRoutes.claudeCode.health = this.detectedClients.claude ? "green" : "gray";
+                }
+            }
+            catch {
+                restoreFailed = true;
+                this.clientRoutes.claudeCode.health = "red";
+            }
+            try {
+                await this.deps.vsCodeRouteSettings?.restore();
+                if (this.clientRoutes.vsCodeChat.health !== "red") {
+                    this.clientRoutes.vsCodeChat.health = this.detectedClients.vsCodeChat ? "green" : "gray";
+                }
+            }
+            catch {
+                restoreFailed = true;
+                this.clientRoutes.vsCodeChat.health = "red";
+            }
+        }
+        if (restoreFailed) {
+            this.notice = this.connectionNotice = "課堂連線已清除，但無法恢復客戶端的 Native 模型設定。請稍後重試或重新啟動。";
+        }
+    }
+    async start() {
+        return this.serialConnectionOperation(() => this.startNow());
+    }
+    async startNow() {
+        this.stopping = false;
+        if (!this.initialization)
+            this.initialization = (async () => {
+                if (this.deps.adapterSettings) {
+                    try {
+                        this.adapters = await this.deps.adapterSettings.load();
+                    }
+                    catch {
+                        this.adapterNotice = "無法讀取 adapter 設定，目前使用 Responses 預設值。";
+                    }
+                }
+                if (this.deps.clientRouteSettings) {
+                    try {
+                        const settings = await this.deps.clientRouteSettings.load();
+                        this.clientRoutes = {
+                            codex: { ...this.clientRoutes.codex, ...settings.codex },
+                            claudeCode: { ...this.clientRoutes.claudeCode, ...settings.claudeCode },
+                            vsCodeChat: { ...this.clientRoutes.vsCodeChat, ...settings.vsCodeChat },
+                        };
+                        this.adapters = { ...this.adapters, codex: settings.codex.adapter };
+                        this.adapters = { ...this.adapters, claude: settings.claudeCode.adapter };
+                    }
+                    catch {
+                        this.clientRoutes = (0, clientRoutes_1.defaultClientRoutes)();
+                    }
+                }
+                await this.detectClients();
+                await this.deps.routes.migrateLegacyState(this.deps.proxyBaseUrl, this.detectedClients);
+                await this.restoreConnection();
+                await this.startCodexRoute();
+                await this.startClaudeCodeRoute();
+                await this.startVsCodeRoute();
+            })();
+        await this.initialization;
+        this.deps.proxy.start();
+        this.proxyRunning = true;
+        if (!this.routeRestartNoted) {
+            this.noteRestart("codex");
+            this.noteRestart("claude");
+            this.routeRestartNoted = true;
+        }
+        // Embedders created before the route runtime existed still receive the Codex
+        // projection. The shipped app always supplies the independent runtime.
+        if (!this.deps.clientRouteRuntime) {
+            try {
+                if (this.mode === "classroom")
+                    await this.publishModelOptions();
+                else
+                    await this.restoreModelOptions();
+            }
+            catch {
+                this.mode = "native";
+                this.notice = "無法完成客戶端設定恢復。備份已保留，請重試切換個人模式。";
+            }
+        }
+    }
+    applyConnectionIdentity(connection) {
+        this.connected = connection !== undefined;
+        this.classLabel = connection && ([connection.session.class_name, connection.session.name].filter(Boolean).join(" · ") || undefined);
+        this.courseTitle = connection?.session.class_name || undefined;
+        this.sessionTitle = connection?.session.name || undefined;
+        this.nickname = connection?.nickname;
+        this.detail = connection ? "Classroom API Key 已設定。" : "";
+    }
+    async restoreConnection() {
+        if (this.connected)
+            return;
+        let connection;
+        try {
+            connection = await this.deps.storage.getConnection();
+        }
+        catch (error) {
+            this.detail = error instanceof storageErrors_1.StorageError ? error.message : "課堂連線無法讀取。請重新連線。";
+            return;
+        }
+        if (!connection)
+            return;
+        this.hiddenKeys.add(connection.apiKey);
+        this.applyConnectionIdentity(connection);
+        this.mode = "native";
+        await this.loadCatalog();
+        await this.loadModels(connection.apiKey);
+        if (connection.mode === "classroom" && this.modelIds.length > 0) {
+            this.mode = "classroom";
+            this.clientModes = connection.clientModes ?? { codex: "classroom", claude: "classroom" };
+        }
+    }
+    async stop() {
+        if (this.commandRunning)
+            throw new Error("安裝中，請完成後再結束。");
+        this.stopping = true;
+        try {
+            await this.serialConnectionOperation(() => this.stopNow());
+        }
+        catch (error) {
+            this.stopping = false;
+            throw error;
+        }
+    }
+    async stopNow() {
+        this.proxyRunning = false;
+        this.deps.proxy.stop();
+        let failure;
+        try {
+            if (this.deps.clientRouteRuntime)
+                await this.codexLifecycle().stop();
+            else
+                await this.restoreModelOptions();
+        }
+        catch (error) {
+            failure = error;
+            if (this.deps.clientRouteRuntime)
+                this.clientRoutes.codex.health = "red";
+        }
+        try {
+            if (this.deps.clientRouteRuntime) {
+                await this.deps.routes.setClaudeCodeRoute(false, this.clientRouteOrigins.claudeCode ?? this.deps.proxyBaseUrl);
+                await this.deps.clientRouteRuntime.stop("claudeCode");
+            }
+        }
+        catch (error) {
+            failure ??= error;
+            this.clientRoutes.claudeCode.health = "red";
+        }
+        try {
+            if (this.deps.clientRouteRuntime) {
+                await this.deps.vsCodeRouteSettings?.restore();
+                await this.deps.clientRouteRuntime.stop("vsCodeChat");
+            }
+        }
+        catch (error) {
+            failure ??= error;
+            this.clientRoutes.vsCodeChat.health = "red";
+        }
+        if (failure) {
+            const message = failure instanceof Error ? failure.message : String(failure);
+            throw new Error(this.redactSecrets(message || "無法停止 Client Route。"));
+        }
+    }
+    noteRestart(client) {
+        if (!this.mustRestart.includes(client)) {
+            this.mustRestart.push(client);
+        }
+    }
+    noteModelRestart(client) {
+        if (!this.modelRestart.includes(client))
+            this.modelRestart.push(client);
+    }
+    // An unchanged republish cannot clear a restart VS Code still owes; only its first request can.
+    settleVsCodePublish(changed) {
+        if (changed)
+            this.noteModelRestart("vscode");
+        const waiting = this.modelRestart.includes("vscode");
+        this.clientRoutes.vsCodeChat.health = waiting ? "yellow" : "green";
+        this.clientRoutes.vsCodeChat.restart = waiting ? "restart-required" : "ready";
+    }
+    closeWindow() {
+        // 關分頁不停止代理，也不改路由。
+    }
+    async loadCatalog() {
+        if (!this.connected) {
+            return;
+        }
+        const apiKey = (await this.deps.storage.getConnection())?.apiKey;
+        if (!apiKey) {
+            this.catalog = undefined;
+            this.catalogError = undefined;
+            this.remoteCatalogHeld = false;
+            return;
+        }
+        let body;
+        try {
+            body = await this.deps.catalog.fetchCourseCatalog(apiKey);
+        }
+        catch {
+            await this.loadLocalCatalog();
+            return;
+        }
+        const yaml = usableCatalogYaml(body?.course_catalog_yaml);
+        if (yaml === undefined) {
+            await this.loadLocalCatalog();
+            return;
+        }
+        const parsed = (0, courseCatalog_1.parseCourseCatalog)(yaml);
+        if (!parsed.ok) {
+            await this.loadLocalCatalog();
+            return;
+        }
+        this.catalog = catalogView(parsed.actions, parsed.snippets, "remote");
+        this.catalogError = undefined;
+        this.remoteCatalogHeld = true;
+    }
+    async loadLocalCatalog() {
+        this.remoteCatalogHeld = false;
+        if (!this.projectFolder) {
+            this.catalog = undefined;
+            this.catalogError = "遠端清單不可用。";
+            return;
+        }
+        let text;
+        try {
+            text = await this.deps.projectFiles.readClassroomInstalls(this.projectFolder);
+        }
+        catch {
+            text = undefined;
+        }
+        if (text === undefined) {
+            this.catalog = undefined;
+            this.catalogError = "找不到 classroom-installs.yaml";
+            return;
+        }
+        const parsed = (0, courseCatalog_1.parseCourseCatalog)(text);
+        if (!parsed.ok) {
+            this.catalog = undefined;
+            this.catalogError = parsed.error;
+            return;
+        }
+        this.catalog = catalogView(parsed.actions, parsed.snippets, "local");
+        this.catalogError = undefined;
+    }
+}
+exports.ClassroomApp = ClassroomApp;
+function environmentInstallSucceeded(result) {
+    if (result.exitCode === 0) {
+        return true;
+    }
+    if (typeof result.exitCode !== "number") {
+        return false;
+    }
+    return (/already installed/i.test(result.output) ||
+        /no available upgrade found/i.test(result.output));
+}
+function usableCatalogYaml(value) {
+    if (typeof value !== "string" || value.trim() === "") {
+        return undefined;
+    }
+    return value;
+}
+function withHttp(upstream, request) {
+    const next = { ...upstream };
+    if (request.headers)
+        next.headers = request.headers;
+    if (request.signal)
+        next.signal = request.signal;
+    if (request.method !== undefined) {
+        next.method = request.method;
+    }
+    if (request.path !== undefined) {
+        next.path = request.path;
+    }
+    if (request.body !== undefined) {
+        next.body = request.body;
+    }
+    return next;
+}
+function forwardedRecord(upstream) {
+    return {
+        client: upstream.client,
+        target: upstream.target,
+        model: upstream.model,
+    };
+}
+function catalogView(actions, snippets, source) {
+    const view = { source, actions };
+    if (snippets.length > 0) {
+        view.snippets = snippets;
+    }
+    if (source === "local") {
+        view.localNote = LOCAL_LIST_NOTE;
+    }
+    return view;
+}