appback-remoteagent 0.13.0

package/dist/services/bridge-service.js

@@ -0,0 +1,807 @@
+import fs from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { stopSpawnedExecution } from "../adapters/windows-shell.js";
+const MODEL_PRESETS = {
+    codex: ["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.2", "gpt-5.1-codex-max"],
+    claude: ["sonnet", "opus", "haiku"],
+};
+export class BridgeService {
+    store;
+    adapters;
+    defaultWorkspace;
+    workspaceRoot;
+    isProviderInstalled;
+    preferredStartMode;
+    defaultCodexSandboxMode;
+    sessionLocks = new Map();
+    constructor(store, adapters, defaultWorkspace, workspaceRoot, isProviderInstalled, preferredStartMode, defaultCodexSandboxMode) {
+        this.store = store;
+        this.adapters = adapters;
+        this.defaultWorkspace = defaultWorkspace;
+        this.workspaceRoot = workspaceRoot;
+        this.isProviderInstalled = isProviderInstalled;
+        this.preferredStartMode = preferredStartMode;
+        this.defaultCodexSandboxMode = defaultCodexSandboxMode;
+    }
+    async createSession(botId, chatId, cwd) {
+        const provider = await this.resolveStartProvider();
+        return this.startSession(botId, chatId, provider, cwd);
+    }
+    async switchSession(botId, chatId, sessionId) {
+        const selector = sessionId.trim();
+        if (!selector) {
+            throw new Error("Session selector is required.");
+        }
+        const session = await this.resolveSessionSelector(selector);
+        if (!session) {
+            throw new Error(`Session was not found: ${selector}`);
+        }
+        return this.store.bindChatToSession(botId, chatId, session.sessionId);
+    }
+    async isChatBoundToSession(botId, chatId, sessionId) {
+        const chatSession = await this.store.getChatSession(botId, chatId);
+        return chatSession?.session.sessionId === sessionId;
+    }
+    async startSession(botId, chatId, provider, cwd) {
+        this.ensureConfigured(provider);
+        const explicitWorkspace = cwd?.trim();
+        const managedWorkspace = explicitWorkspace ? undefined : await this.createManagedWorkspace();
+        const workspace = explicitWorkspace
+            ? this.resolveWorkspace(undefined, explicitWorkspace)
+            : managedWorkspace.workspace;
+        if (explicitWorkspace) {
+            await this.ensureWorkspaceExists(workspace);
+        }
+        await this.store.createSessionForChat(botId, chatId, workspace, provider, managedWorkspace?.workspaceUid);
+        const chatSession = await this.store.upsertProviderForChat(botId, chatId, provider, {
+            cwd: workspace,
+            pairedAt: new Date().toISOString(),
+            sessionId: undefined,
+            model: provider === "codex" ? "gpt-5.5" : "sonnet",
+            sandboxMode: provider === "codex" ? this.defaultCodexSandboxMode : undefined,
+            lastUsedAt: undefined,
+        }, workspace);
+        await this.store.ensureDefaultStartMode(provider);
+        return chatSession;
+    }
+    async attachPair(botId, chatId, provider, sessionId) {
+        this.ensureConfigured(provider);
+        const existing = await this.store.getChatSession(botId, chatId);
+        const normalizedSessionId = sessionId.trim();
+        if (!normalizedSessionId) {
+            throw new Error("Session id is required.");
+        }
+        let workspace;
+        if (provider === "codex") {
+            const detectedWorkspace = await this.readCodexSessionWorkspace(normalizedSessionId);
+            if (detectedWorkspace) {
+                workspace = detectedWorkspace;
+                await this.ensureWorkspaceExists(workspace);
+            }
+            else {
+                workspace = this.resolveWorkspace(existing?.session[provider]?.cwd ?? existing?.session.workspace, undefined);
+                await this.ensureWorkspaceExists(workspace);
+                await this.verifyCodexAttachWorkspace(botId, chatId, normalizedSessionId, workspace, existing?.session.codex);
+            }
+        }
+        else {
+            workspace = this.resolveWorkspace(existing?.session[provider]?.cwd ?? existing?.session.workspace, undefined);
+            await this.ensureWorkspaceExists(workspace);
+        }
+        const chatSession = await this.store.upsertProviderForChat(botId, chatId, provider, {
+            cwd: workspace,
+            pairedAt: new Date().toISOString(),
+            sessionId: normalizedSessionId,
+            model: existing?.session[provider]?.model ?? (provider === "codex" ? "gpt-5.5" : "sonnet"),
+            sandboxMode: provider === "codex"
+                ? (existing?.session[provider]?.sandboxMode ?? this.defaultCodexSandboxMode)
+                : undefined,
+            lastUsedAt: undefined,
+        }, workspace);
+        await this.store.ensureDefaultStartMode(provider);
+        return chatSession;
+    }
+    async resolveStartProvider(requested) {
+        const normalized = requested?.trim().toLowerCase();
+        if (normalized) {
+            if (normalized !== "codex" && normalized !== "claude") {
+                throw new Error("Provider must be codex or claude.");
+            }
+            const explicit = normalized;
+            if (!this.isProviderAvailable(explicit)) {
+                throw new Error(this.formatInstallGuidance(explicit));
+            }
+            return explicit;
+        }
+        const savedDefault = await this.store.getDefaultStartMode();
+        const candidates = [savedDefault, this.preferredStartMode, ...this.listAvailableProviders()]
+            .filter((value, index, items) => Boolean(value) && items.indexOf(value) === index);
+        const provider = candidates.find((item) => this.isProviderAvailable(item));
+        if (!provider) {
+            throw new Error(this.formatInstallGuidance());
+        }
+        return provider;
+    }
+    listAvailableProviders() {
+        return ["codex", "claude"].filter((provider) => this.isProviderAvailable(provider));
+    }
+    async rememberDefaultStartMode(provider) {
+        if (this.isProviderAvailable(provider)) {
+            await this.store.ensureDefaultStartMode(provider);
+        }
+    }
+    formatInstallGuidance(requested) {
+        const available = this.listAvailableProviders();
+        const availableLine = available.length > 0
+            ? `Installed modes: ${available.join(", ")}`
+            : "Installed modes: none";
+        if (requested) {
+            const nextStep = requested === "claude"
+                ? "Install Claude Code on this machine with /install claude, finish the CLI login with /login claude, then run /start claude."
+                : "Install Codex CLI on this machine, then run /install codex or /start codex.";
+            return [
+                `${requested} is not installed on this machine yet.`,
+                availableLine,
+                nextStep,
+            ].join("\n");
+        }
+        return [
+            "No installed coding mode was found on this machine.",
+            availableLine,
+            "Install Codex CLI or Claude Code first. You can run /install codex or /install claude, then use /start.",
+        ].join("\n");
+    }
+    async setCodexSandboxMode(botId, chatId, sandboxMode) {
+        const chatSession = await this.requireChat(botId, chatId);
+        this.ensurePaired(chatSession, "codex");
+        const codex = chatSession.session.codex;
+        return this.store.upsertProviderForChat(botId, chatId, "codex", {
+            ...codex,
+            sandboxMode,
+        }, chatSession.session.workspace);
+    }
+    async rememberTelegramContact(contact) {
+        await this.store.rememberTelegramContact(contact);
+    }
+    async setModel(botId, chatId, model) {
+        const chatSession = await this.requireChat(botId, chatId);
+        const provider = chatSession.session.mode;
+        this.ensurePaired(chatSession, provider);
+        const nextModel = this.resolveSelectableModel(provider, model);
+        if (!nextModel) {
+            throw new Error("Model name is required.");
+        }
+        const providerSession = chatSession.session[provider];
+        return this.store.upsertProviderForChat(botId, chatId, provider, {
+            ...providerSession,
+            model: nextModel,
+        }, chatSession.session.workspace);
+    }
+    async formatModelSelection(botId, chatId) {
+        const chatSession = await this.requireChat(botId, chatId);
+        const provider = chatSession.session.mode;
+        this.ensurePaired(chatSession, provider);
+        const providerSession = chatSession.session[provider];
+        const presets = MODEL_PRESETS[provider] ?? [];
+        const lines = [
+            `session: ${chatSession.session.publicId}`,
+            `mode: ${provider}`,
+            `currentModel: ${providerSession.model ?? this.defaultModelFor(provider)}`,
+            "availablePresets:",
+            ...presets.map((item, index) => ` ${index + 1}. ${item}`),
+            "",
+            "Use `/model <name>` or `/model <number>` to change it.",
+        ];
+        if (presets.length === 0) {
+            lines.splice(3, 1, "availablePresets: none");
+        }
+        return lines.join("\n");
+    }
+    async status(botId, chatId) {
+        return this.store.getChatSession(botId, chatId);
+    }
+    async listSessions(botId) {
+        return this.store.listSessions(botId);
+    }
+    async listActiveSessionIds(botId) {
+        return this.store.listActiveSessionIds(botId);
+    }
+    async sessionEvents(sessionId, limit) {
+        const session = await this.store.getSession(sessionId);
+        if (!session) {
+            throw new Error(`Session was not found: ${sessionId}`);
+        }
+        return this.store.readLogs(sessionId, limit);
+    }
+    async logSystem(botId, chatId, text) {
+        const chatSession = await this.store.getChatSession(botId, chatId);
+        if (!chatSession) {
+            return;
+        }
+        await this.log({
+            timestamp: new Date().toISOString(),
+            remoteSessionId: chatSession.session.sessionId,
+            botId,
+            chatId,
+            provider: "system",
+            direction: "system",
+            text,
+        });
+    }
+    async reset(botId, chatId) {
+        const chatSession = await this.store.getChatSession(botId, chatId);
+        if (chatSession) {
+            await this.log({
+                timestamp: new Date().toISOString(),
+                remoteSessionId: chatSession.session.sessionId,
+                botId,
+                chatId,
+                provider: "system",
+                direction: "system",
+                text: "Chat binding reset.",
+            });
+        }
+        await this.store.resetChat(botId, chatId);
+    }
+    async stopActiveRun(botId, chatId) {
+        const chatSession = await this.store.getChatSession(botId, chatId);
+        if (!chatSession) {
+            return { stopped: false };
+        }
+        const stopped = stopSpawnedExecution(chatSession.session.sessionId);
+        if (stopped) {
+            await this.log({
+                timestamp: new Date().toISOString(),
+                remoteSessionId: chatSession.session.sessionId,
+                botId,
+                chatId,
+                provider: "system",
+                direction: "system",
+                text: "Active provider execution was stopped by the user.",
+            });
+        }
+        return { stopped, sessionPublicId: chatSession.session.publicId };
+    }
+    async stopSessionRun(sessionId, botId, chatId, reason = "Session execution was stopped.") {
+        const session = await this.store.getSession(sessionId);
+        if (!session) {
+            return { stopped: false };
+        }
+        const stopped = stopSpawnedExecution(session.sessionId);
+        if (stopped) {
+            await this.log({
+                timestamp: new Date().toISOString(),
+                remoteSessionId: session.sessionId,
+                botId,
+                chatId,
+                provider: "system",
+                direction: "system",
+                text: reason,
+            });
+        }
+        return { stopped, sessionPublicId: session.publicId };
+    }
+    async routeMessage(botId, chatId, message) {
+        const chatSession = await this.requireChat(botId, chatId);
+        await this.log({
+            timestamp: new Date().toISOString(),
+            remoteSessionId: chatSession.session.sessionId,
+            botId,
+            chatId,
+            provider: "telegram",
+            direction: "in",
+            text: message,
+        });
+        return this.withSessionLock(chatSession.session.sessionId, () => this.routeSession(chatSession.session, message, "telegram", botId, chatId));
+    }
+    async routeSessionMessage(sessionId, message) {
+        const session = await this.store.getSession(sessionId);
+        if (!session) {
+            throw new Error(`Session was not found: ${sessionId}`);
+        }
+        await this.log({
+            timestamp: new Date().toISOString(),
+            remoteSessionId: session.sessionId,
+            provider: "pc-ui",
+            direction: "in",
+            text: message,
+        });
+        return this.withSessionLock(session.sessionId, () => this.routeSession(session, message, "pc-ui"));
+    }
+    async routeSessionMessageForChat(sessionId, botId, chatId, message) {
+        const session = await this.store.getSession(sessionId);
+        if (!session) {
+            throw new Error(`Session was not found: ${sessionId}`);
+        }
+        await this.log({
+            timestamp: new Date().toISOString(),
+            remoteSessionId: session.sessionId,
+            botId,
+            chatId,
+            provider: "telegram",
+            direction: "in",
+            text: message,
+        });
+        return this.withSessionLock(session.sessionId, () => this.routeSession(session, message, "telegram", botId, chatId));
+    }
+    formatStatus(chatSession) {
+        if (!chatSession) {
+            return "No paired session yet. Use /start, /start codex, /start claude, or /attach ...";
+        }
+        const { session } = chatSession;
+        const codex = session.codex
+            ? this.describeProviderSession(session.codex)
+            : "- codex: not paired";
+        const claude = session.claude
+            ? this.describeProviderSession(session.claude)
+            : "- claude: not paired";
+        return [
+            `session: ${session.publicId}`,
+            `bot: ${chatSession.botId ?? chatSession.binding.botId ?? "unknown"}`,
+            `chat: ${chatSession.chatId}`,
+            `mode: ${session.mode}`,
+            `workspace: ${session.workspace}`,
+            ...this.describeEffectiveAccess(session),
+            codex,
+            claude,
+            `createdAt: ${session.createdAt}`,
+            `updatedAt: ${session.updatedAt}`,
+        ].join("\n");
+    }
+    formatResponses(responses) {
+        return responses.map((response) => {
+            const sessionLabel = response.publicSessionId ?? response.sessionId;
+            const header = `[${response.provider.toUpperCase()} | ${sessionLabel}]`;
+            return `${header}\n${response.output}`;
+        });
+    }
+    formatCurrentSession(chatSession) {
+        if (!chatSession) {
+            return "No active session is bound to this chat.";
+        }
+        const { session } = chatSession;
+        return [
+            `session: ${session.publicId}`,
+            `bot: ${chatSession.botId ?? chatSession.binding.botId ?? "unknown"}`,
+            `chat: ${chatSession.chatId}`,
+            `mode: ${session.mode}`,
+            `workspace: ${session.workspace}`,
+            ...this.describeEffectiveAccess(session),
+            `updatedAt: ${session.updatedAt}`,
+        ].join("\n");
+    }
+    formatSessionList(sessions, currentSessionId, limit = 10) {
+        if (sessions.length === 0) {
+            return "No sessions found.";
+        }
+        const rows = sessions
+            .slice(0, limit)
+            .map((session, index) => {
+            const marker = session.sessionId === currentSessionId ? "*" : " ";
+            return `${marker} ${index + 1}. [${session.publicId}] ${this.workspaceLabel(session.workspace)}\n   mode: ${session.mode}\n   updatedAt: ${session.updatedAt}`;
+        });
+        return [
+            `Sessions (${Math.min(limit, sessions.length)}/${sessions.length})`,
+            ...rows,
+        ].join("\n");
+    }
+    async formatSessionListDetailed(sessions, currentSessionId, activeSessionIds) {
+        if (sessions.length === 0) {
+            return "No sessions found.";
+        }
+        const rows = [];
+        for (const [index, session] of sessions.entries()) {
+            const marker = session.sessionId === currentSessionId ? "*" : " ";
+            const status = activeSessionIds.has(session.sessionId) ? "active" : "unused";
+            const workspaceSize = await this.workspaceSizeLabel(session);
+            rows.push([
+                `${marker} ${index + 1}. [${session.publicId}] ${this.workspaceLabel(session.workspace)}`,
+                `   status: ${status}`,
+                `   mode: ${session.mode}`,
+                `   size: ${workspaceSize}`,
+                `   updatedAt: ${session.updatedAt}`,
+            ].join("\n"));
+        }
+        return [
+            `Sessions (${sessions.length}/${sessions.length})`,
+            ...rows,
+        ].join("\n");
+    }
+    async resolveSessionSelector(selector, botId) {
+        const sessions = await this.store.listSessions(botId);
+        const trimmed = selector.trim();
+        if (/^\d+$/.test(trimmed)) {
+            const index = Number.parseInt(trimmed, 10);
+            if (index >= 1 && index <= sessions.length) {
+                return sessions[index - 1];
+            }
+        }
+        const normalized = trimmed.toUpperCase();
+        return sessions.find((session) => session.publicId.toUpperCase() === normalized || session.sessionId === trimmed);
+    }
+    resolveProviders(mode) {
+        return [mode];
+    }
+    async requireChat(botId, chatId) {
+        const chatSession = await this.store.getChatSession(botId, chatId);
+        if (!chatSession) {
+            throw new Error("No paired session for this chat yet. Run `/start codex`, `/start claude`, or `/attach ...` first.");
+        }
+        return chatSession;
+    }
+    ensurePaired(chatSession, provider) {
+        if (!chatSession.session[provider]?.cwd) {
+            throw new Error(`This chat is not paired with ${provider}. Run \`/start ${provider}\` or \`/attach ${provider} <session_id>\`.`);
+        }
+    }
+    ensureProviderSession(session, provider) {
+        const providerSession = session[provider];
+        if (!providerSession?.cwd) {
+            throw new Error(`Session ${session.sessionId} is not paired with ${provider}.`);
+        }
+        return providerSession;
+    }
+    ensureConfigured(provider) {
+        if (!this.isProviderAvailable(provider)) {
+            throw new Error(this.formatInstallGuidance(provider));
+        }
+    }
+    isProviderAvailable(provider) {
+        return this.isProviderInstalled(provider) && Boolean(this.adapters[provider]);
+    }
+    async log(entry) {
+        await this.store.appendLog(entry.remoteSessionId, JSON.stringify(entry));
+    }
+    async withSessionLock(sessionId, task) {
+        const previous = this.sessionLocks.get(sessionId) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        const queued = previous.catch(() => undefined).then(() => current);
+        this.sessionLocks.set(sessionId, queued);
+        await previous.catch(() => undefined);
+        try {
+            return await task();
+        }
+        finally {
+            release();
+            if (this.sessionLocks.get(sessionId) === queued) {
+                this.sessionLocks.delete(sessionId);
+            }
+        }
+    }
+    async routeSession(session, message, requestSource, botId, chatId) {
+        const responses = [];
+        const providers = this.resolveProviders(session.mode);
+        for (const provider of providers) {
+            const providerSession = this.ensureProviderSession(session, provider);
+            this.ensureConfigured(provider);
+            const response = await this.adapters[provider].send({
+                botId,
+                chatId: chatId ?? requestSource,
+                remoteSessionId: session.sessionId,
+                publicSessionId: session.publicId,
+                cwd: providerSession.cwd,
+                sessionId: providerSession.sessionId,
+                message,
+                model: providerSession.model,
+                sandboxMode: providerSession.sandboxMode,
+            });
+            const updatedProviderSession = {
+                ...providerSession,
+                cwd: response.cwd,
+                sessionId: response.sessionId,
+                lastUsedAt: new Date().toISOString(),
+            };
+            const stillBound = chatId
+                ? await this.store.getChatSession(botId ?? "telegram", chatId)
+                : undefined;
+            if (chatId && stillBound?.session.sessionId === session.sessionId) {
+                await this.store.upsertProviderForChat(botId ?? "telegram", chatId, provider, updatedProviderSession, session.workspace);
+            }
+            else {
+                await this.store.upsertProviderForSession(session.sessionId, provider, updatedProviderSession, session.workspace);
+            }
+            session[provider] = updatedProviderSession;
+            await this.log({
+                timestamp: new Date().toISOString(),
+                remoteSessionId: session.sessionId,
+                botId,
+                chatId,
+                provider,
+                direction: "out",
+                sessionId: response.sessionId,
+                text: response.output,
+            });
+            responses.push({
+                ...response,
+                publicSessionId: session.publicId,
+            });
+        }
+        return responses;
+    }
+    async verifyCodexAttachWorkspace(botId, chatId, providerSessionId, requestedWorkspace, existingSession) {
+        const actualWorkspace = await this.readCodexSessionWorkspace(providerSessionId)
+            ?? await this.probeCodexAttachWorkspace(botId, chatId, providerSessionId, requestedWorkspace, existingSession);
+        if (!actualWorkspace) {
+            throw new Error("Attach blocked: could not verify the resumed Codex session working directory.");
+        }
+        if (!this.pathsMatch(actualWorkspace, requestedWorkspace)) {
+            throw new Error(`Attach blocked: resumed Codex session workspace is '${actualWorkspace}', not requested '${requestedWorkspace}'.`);
+        }
+    }
+    async readCodexSessionWorkspace(providerSessionId) {
+        const sessionsRoot = path.join(os.homedir(), ".codex", "sessions");
+        const sessionFile = await this.findCodexSessionFile(sessionsRoot, providerSessionId);
+        if (!sessionFile) {
+            return undefined;
+        }
+        const raw = await fs.readFile(sessionFile, "utf8").catch(() => undefined);
+        if (!raw) {
+            return undefined;
+        }
+        const firstLine = raw.split(/\r?\n/, 1)[0]?.trim();
+        if (!firstLine) {
+            return undefined;
+        }
+        try {
+            const event = JSON.parse(firstLine);
+            if (event.type === "session_meta" && typeof event.payload?.cwd === "string" && event.payload.cwd.trim()) {
+                return event.payload.cwd.trim();
+            }
+        }
+        catch {
+            return undefined;
+        }
+        return undefined;
+    }
+    async findCodexSessionFile(root, providerSessionId) {
+        const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const entryPath = path.join(root, entry.name);
+            if (entry.isDirectory()) {
+                const nested = await this.findCodexSessionFile(entryPath, providerSessionId);
+                if (nested) {
+                    return nested;
+                }
+                continue;
+            }
+            if (entry.isFile() && entry.name.endsWith(`${providerSessionId}.jsonl`)) {
+                return entryPath;
+            }
+        }
+        return undefined;
+    }
+    async probeCodexAttachWorkspace(botId, chatId, providerSessionId, requestedWorkspace, existingSession) {
+        this.ensureConfigured("codex");
+        const probe = await this.adapters.codex.send({
+            botId,
+            chatId,
+            remoteSessionId: existingSession?.sessionId ?? providerSessionId,
+            cwd: requestedWorkspace,
+            sessionId: providerSessionId,
+            model: existingSession?.model,
+            sandboxMode: existingSession?.sandboxMode,
+            message: [
+                "Safety check for workspace attach.",
+                "Reply with JSON only.",
+                "{\"cwd\":\"<current working directory>\"}",
+            ].join("\n"),
+        });
+        return this.extractCodexCwd(probe.output);
+    }
+    extractCodexCwd(output) {
+        const jsonMatch = output.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            try {
+                const parsed = JSON.parse(jsonMatch[0]);
+                if (typeof parsed.cwd === "string" && parsed.cwd.trim()) {
+                    return parsed.cwd.trim();
+                }
+            }
+            catch {
+                // Fall back to line-based parsing below.
+            }
+        }
+        for (const line of output.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith("cwd:")) {
+                return trimmed.slice(4).trim().replace(/^["'`]+|["'`]+$/g, "");
+            }
+        }
+        return undefined;
+    }
+    pathsMatch(left, right) {
+        return this.normalizeComparablePath(left) === this.normalizeComparablePath(right);
+    }
+    normalizeComparablePath(value) {
+        const trimmed = value.trim().replace(/^["'`]+|["'`]+$/g, "");
+        const slashed = trimmed.replace(/\//g, "\\");
+        const lower = slashed.toLowerCase();
+        const wslMatch = lower.match(/^\\\\wsl\.localhost\\([^\\]+)\\(.+)$/);
+        if (wslMatch) {
+            return `/${wslMatch[2].replace(/\\/g, "/")}`;
+        }
+        const mntMatch = trimmed.match(/^\/mnt\/([a-zA-Z])\/(.+)$/);
+        if (mntMatch) {
+            return `${mntMatch[1].toLowerCase()}:\\${mntMatch[2].replace(/\//g, "\\").toLowerCase()}`;
+        }
+        if (/^[a-zA-Z]:\\/.test(trimmed)) {
+            return `${trimmed[0].toLowerCase()}:${trimmed.slice(2).replace(/\//g, "\\").toLowerCase()}`;
+        }
+        if (trimmed.startsWith("/")) {
+            return trimmed.replace(/\\/g, "/").toLowerCase();
+        }
+        return lower;
+    }
+    describeProviderSession(session) {
+        const state = session.sessionId
+            ? "attached"
+            : "pending-first-run";
+        const details = [`- ${session.provider}: ${state} @ ${session.cwd}`];
+        details.push(`  model: ${session.model ?? this.defaultModelFor(session.provider)}`);
+        if (session.provider === "codex") {
+            details.push(`  sandbox: ${this.effectiveCodexSandboxMode(session)}`);
+        }
+        if (session.lastUsedAt) {
+            details.push(`  lastUsedAt: ${session.lastUsedAt}`);
+        }
+        return details.join("\n");
+    }
+    resolveWorkspace(current, next) {
+        return next?.trim() || current || this.defaultWorkspace;
+    }
+    defaultModelFor(provider) {
+        return provider === "codex" ? "gpt-5.5" : "sonnet";
+    }
+    describeEffectiveAccess(session) {
+        if (!session.codex) {
+            return [];
+        }
+        const sandboxMode = this.effectiveCodexSandboxMode(session.codex);
+        return [
+            `effectiveSandbox: ${sandboxMode}`,
+            `writableRoots: ${this.describeWritableRoots(session.workspace, sandboxMode)}`,
+        ];
+    }
+    effectiveCodexSandboxMode(session) {
+        return session.sandboxMode ?? this.defaultCodexSandboxMode ?? "read-only";
+    }
+    describeWritableRoots(workspace, sandboxMode) {
+        if (sandboxMode === "danger-full-access") {
+            return `unrestricted (session workspace: ${workspace})`;
+        }
+        if (sandboxMode === "workspace-write") {
+            return `${workspace}, /tmp`;
+        }
+        return "/tmp only";
+    }
+    describeTelegramContactChat(contact) {
+        if (contact.chatType === "private") {
+            const parts = [contact.firstName, contact.lastName].filter(Boolean);
+            const name = parts.join(" ").trim();
+            if (name) {
+                return `${name} (${contact.chatId})`;
+            }
+            if (contact.username) {
+                return `@${contact.username} (${contact.chatId})`;
+            }
+        }
+        return `${contact.chatType} ${contact.title ? `${contact.title} ` : ""}(${contact.chatId})`.trim();
+    }
+    resolveSelectableModel(provider, input) {
+        const value = input.trim();
+        if (!value) {
+            return value;
+        }
+        const presets = MODEL_PRESETS[provider] ?? [];
+        if (presets.length === 0) {
+            return value;
+        }
+        if (/^\d+$/.test(value)) {
+            const index = Number.parseInt(value, 10);
+            if (index >= 1 && index <= presets.length) {
+                return presets[index - 1];
+            }
+            throw new Error(this.formatUnknownModel(provider, value, presets));
+        }
+        const matched = presets.find((item) => item.toLowerCase() === value.toLowerCase());
+        if (matched) {
+            return matched;
+        }
+        throw new Error(this.formatUnknownModel(provider, value, presets));
+    }
+    formatUnknownModel(provider, value, presets) {
+        return [
+            `Unknown ${provider} model: ${value}`,
+            "Choose one of:",
+            ...presets.map((item, index) => ` ${index + 1}. ${item}`),
+            "",
+            "Use `/model` to see the list again.",
+        ].join("\n");
+    }
+    async createManagedWorkspace() {
+        await fs.mkdir(this.workspaceRoot, { recursive: true });
+        for (let attempt = 0; attempt < 20; attempt += 1) {
+            const workspaceUid = this.generateWorkspaceUid();
+            const workspace = path.join(this.workspaceRoot, workspaceUid);
+            try {
+                await fs.mkdir(workspace);
+                return { workspace, workspaceUid };
+            }
+            catch (error) {
+                if (error.code === "EEXIST") {
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw new Error("Could not allocate a managed workspace directory.");
+    }
+    generateWorkspaceUid() {
+        const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+        const bytes = randomBytes(8);
+        let value = "";
+        for (const byte of bytes) {
+            value += alphabet[byte % alphabet.length];
+        }
+        return value;
+    }
+    workspaceLabel(workspace) {
+        const normalized = workspace.replace(/\\/g, "/").replace(/\/+$/, "");
+        const parts = normalized.split("/");
+        return parts[parts.length - 1] || workspace;
+    }
+    async workspaceSizeLabel(session) {
+        if (!session.workspaceUid || !this.isManagedWorkspace(session.workspace)) {
+            return "external";
+        }
+        const bytes = await this.directorySize(session.workspace).catch(() => undefined);
+        return bytes === undefined ? "unknown" : this.formatBytes(bytes);
+    }
+    isManagedWorkspace(workspace) {
+        const relative = path.relative(this.workspaceRoot, workspace);
+        return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+    }
+    async directorySize(directory) {
+        const stat = await fs.stat(directory);
+        if (!stat.isDirectory()) {
+            return stat.size;
+        }
+        let total = 0;
+        const entries = await fs.readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = path.join(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                total += await this.directorySize(entryPath);
+            }
+            else if (entry.isFile()) {
+                total += (await fs.stat(entryPath)).size;
+            }
+        }
+        return total;
+    }
+    formatBytes(bytes) {
+        const units = ["B", "KB", "MB", "GB", "TB"];
+        let value = bytes;
+        let unitIndex = 0;
+        while (value >= 1024 && unitIndex < units.length - 1) {
+            value /= 1024;
+            unitIndex += 1;
+        }
+        const digits = value >= 10 || unitIndex === 0 ? 0 : 1;
+        return `${value.toFixed(digits)}${units[unitIndex]}`;
+    }
+    async ensureWorkspaceExists(cwd) {
+        const stat = await fs.stat(cwd).catch(() => undefined);
+        if (!stat?.isDirectory()) {
+            throw new Error(`Workspace path does not exist: ${cwd}`);
+        }
+    }
+}