specrails-desktop 2.26.2 → 2.28.0

package/server/dist/headroom-manager.js

@@ -0,0 +1,971 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeadroomManager = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const desktop_db_1 = require("./desktop-db");
+const headroom_routing_1 = require("./headroom-routing");
+const STATE_KEY = 'plugins.headroom.state';
+const DEFAULT_PORT = 8787;
+function nowIso() {
+    return new Date().toISOString();
+}
+function toolRoot() {
+    return path_1.default.join(os_1.default.homedir(), '.specrails', 'tools');
+}
+function uvToolDir() {
+    return path_1.default.join(toolRoot(), 'uv', 'tools');
+}
+function uvCacheDir() {
+    return path_1.default.join(toolRoot(), 'uv', 'cache');
+}
+function uvBinDir() {
+    return path_1.default.join(toolRoot(), 'bin');
+}
+function headroomExeName() {
+    return process.platform === 'win32' ? 'headroom.exe' : 'headroom';
+}
+function fileExists(p) {
+    if (!p)
+        return false;
+    try {
+        return fs_1.default.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+function bundledUvCandidates() {
+    const base = process.env.SPECRAILS_BUNDLED_RUNTIMES_PATH;
+    if (!base)
+        return [];
+    if (process.platform === 'win32') {
+        return [
+            path_1.default.join(base, 'uv', 'uv.exe'),
+            path_1.default.join(base, 'uv', 'bin', 'uv.exe'),
+        ];
+    }
+    return [
+        path_1.default.join(base, 'uv', 'bin', 'uv'),
+        path_1.default.join(base, 'uv', 'uv'),
+    ];
+}
+function which(command) {
+    const probe = (0, child_process_1.spawnSync)(process.platform === 'win32' ? 'where' : 'which', [command], {
+        encoding: 'utf8',
+        timeout: 5000,
+        env: process.env,
+    });
+    if (probe.status !== 0)
+        return null;
+    return `${probe.stdout ?? ''}`.trim().split(/\r?\n/)[0] || null;
+}
+function parseHeadroomVersion(raw) {
+    const match = raw.match(/(\d+\.\d+\.\d+)/);
+    return match?.[1] ?? null;
+}
+function issue(code, detail, command) {
+    const copy = {
+        uv_missing_or_corrupt: {
+            title: 'Bundled uv is not available',
+            guidance: 'Specrails could not start its bundled uv runtime. Reinstall Specrails or use Repair once the runtime is available.',
+        },
+        network_unavailable: {
+            title: 'Headroom could not be downloaded',
+            guidance: 'Check your network connection and retry. Specrails will keep the install isolated in its own tool directory.',
+        },
+        package_resolution_failed: {
+            title: 'Headroom dependencies could not be resolved',
+            guidance: 'Retry the install. If it keeps failing, open diagnostics and share the uv output.',
+        },
+        install_permission_failed: {
+            title: 'Specrails cannot write its tool directory',
+            guidance: 'Check permissions under ~/.specrails/tools, then retry the install.',
+        },
+        headroom_not_found_after_install: {
+            title: 'Install finished but Headroom was not found',
+            guidance: 'Run Repair install. Specrails will reinstall Headroom and verify the executable.',
+        },
+        learning_setup_failed: {
+            title: 'Headroom learning could not be enabled',
+            guidance: 'Headroom is installed, but output-savings calibration did not finish. Retry learning from diagnostics or keep using proxy routing while metrics warm up.',
+        },
+        metrics_unavailable: {
+            title: 'Headroom metrics are not available yet',
+            guidance: 'Start routing traffic through Headroom. Specrails will refresh token-savings metrics as soon as the proxy reports samples.',
+        },
+        proxy_port_busy: {
+            title: 'Headroom proxy port is already in use',
+            guidance: 'Choose another port or stop the process using the current port, then retry activation.',
+        },
+        proxy_unhealthy: {
+            title: 'Headroom proxy did not become healthy',
+            guidance: 'Retry activation. If it repeats, open diagnostics to inspect the proxy output.',
+        },
+        provider_route_failed: {
+            title: 'Provider route verification failed',
+            guidance: 'Specrails could not verify the provider route. The provider remains inactive; retry after checking diagnostics.',
+        },
+        provider_config_conflict: {
+            title: 'Existing provider configuration conflicts with Headroom',
+            guidance: 'Review diagnostics before enabling system-wide activation. Specrails-managed routing remains reversible.',
+        },
+        activation_partially_applied: {
+            title: 'Activation was only partially applied',
+            guidance: 'Specrails attempted rollback. Review diagnostics and retry the affected provider.',
+        },
+        not_installed: {
+            title: 'Headroom is not installed',
+            guidance: 'Install Headroom first, then activate Codex or Claude.',
+        },
+        uninstall_failed: {
+            title: 'Headroom could not be uninstalled',
+            guidance: 'Specrails disabled Headroom routing but could not remove the managed tool. Open diagnostics, then retry uninstall.',
+        },
+        unknown: {
+            title: 'Headroom operation failed',
+            guidance: 'Retry the operation. If it repeats, open diagnostics and share the details.',
+        },
+    };
+    return { code, title: copy[code].title, guidance: copy[code].guidance, detail, command };
+}
+function classifyInstallFailure(output, command) {
+    const lower = output.toLowerCase();
+    if (lower.includes('permission') || lower.includes('eacces') || lower.includes('access is denied')) {
+        return issue('install_permission_failed', output, command);
+    }
+    if (lower.includes('network') ||
+        lower.includes('timed out') ||
+        lower.includes('temporary failure') ||
+        lower.includes('could not resolve') ||
+        lower.includes('connection refused') ||
+        lower.includes('connection reset')) {
+        return issue('network_unavailable', output, command);
+    }
+    if (lower.includes('no solution') || lower.includes('failed to resolve') || lower.includes('resolution')) {
+        return issue('package_resolution_failed', output, command);
+    }
+    return issue('unknown', output, command);
+}
+function classifyProxyFailure(output, command) {
+    const lower = output.toLowerCase();
+    if (lower.includes('address already in use') ||
+        lower.includes('eaddrinuse') ||
+        lower.includes('only one usage of each socket address')) {
+        return issue('proxy_port_busy', output, command);
+    }
+    return issue('proxy_unhealthy', output, command);
+}
+function providerLabel(provider) {
+    return provider === 'codex' ? 'Codex' : 'Claude';
+}
+function providerRecord(value) {
+    return {
+        codex: !!value?.codex,
+        claude: !!value?.claude,
+    };
+}
+function emptyProviderMetric(provider) {
+    return {
+        provider,
+        label: providerLabel(provider),
+        active: false,
+        available: false,
+        detectedRoute: false,
+        requests: 0,
+        inputTokens: 0,
+        inputTokensSaved: 0,
+        outputTokens: 0,
+        outputTokensSaved: 0,
+        outputSavingsPercent: 0,
+        outputSavingsMethod: 'none',
+        outputSavingsAllocated: false,
+    };
+}
+function emptyMetricsState(issueValue = null) {
+    return {
+        updatedAt: null,
+        proxyStatsAvailable: false,
+        durableSavingsAvailable: false,
+        outputSavingsAvailable: false,
+        outputSavingsMethod: null,
+        outputConfidence: null,
+        providers: {
+            codex: emptyProviderMetric('codex'),
+            claude: emptyProviderMetric('claude'),
+        },
+        lastIssue: issueValue,
+    };
+}
+function normalizeProviderKey(value) {
+    const raw = String(value ?? '').trim().toLowerCase().replace(/_/g, '-');
+    if (!raw)
+        return null;
+    if (raw === 'codex' || raw === 'codex-cli' || raw === 'openai')
+        return 'codex';
+    if (raw === 'claude' || raw === 'claude-code' || raw === 'claude-cli' || raw === 'anthropic')
+        return 'claude';
+    return null;
+}
+function num(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function maxNumericField(row, fields) {
+    return Math.max(0, ...fields.map((field) => Math.trunc(num(row[field]))));
+}
+const INPUT_TOKEN_FIELDS = [
+    'input_tokens',
+    'input_tokens_total',
+    'input_tokens_processed',
+    'total_input_tokens',
+    'prompt_tokens',
+    'prompt_tokens_total',
+    'prompt_tokens_processed',
+    'tokens_in',
+    'tokens_input',
+    'original_tokens',
+    'tokens_original',
+    'tokens_before',
+];
+const OUTPUT_TOKEN_FIELDS = [
+    'output_tokens',
+    'output_tokens_total',
+    'output_tokens_processed',
+    'total_output_tokens',
+    'completion_tokens',
+    'completion_tokens_total',
+    'tokens_out',
+    'tokens_output',
+];
+class HeadroomManager {
+    db;
+    broadcast;
+    availableProvidersSupplier;
+    proxy = null;
+    proxyTail = '';
+    routeDetectionCache = null;
+    metricsCache = emptyMetricsState();
+    metricsRefresh = null;
+    constructor(db, broadcast, availableProvidersSupplier = () => ['claude', 'codex']) {
+        this.db = db;
+        this.broadcast = broadcast;
+        this.availableProvidersSupplier = availableProvidersSupplier;
+        this.syncRouting();
+    }
+    getState() {
+        const persisted = this.readPersisted();
+        const uvPath = this.resolveUvPath();
+        const install = this.resolveHeadroomInstall(persisted.executablePath ?? null, !!persisted.ignoreSystemInstall);
+        const exe = install?.path ?? null;
+        const version = exe ? this.readHeadroomVersion(exe) : null;
+        const installed = !!exe && !!version;
+        const availableProviders = this.availableProviderRecord();
+        const detectedRoutes = installed && exe ? this.detectProviderRoutes(exe) : providerRecord(persisted.detectedRoutes);
+        const activeProviders = {
+            codex: persisted.activeProviders?.codex ?? (availableProviders.codex && detectedRoutes.codex),
+            claude: persisted.activeProviders?.claude ?? (availableProviders.claude && detectedRoutes.claude),
+        };
+        if (installed) {
+            const shouldPersistInstall = persisted.installed !== true ||
+                persisted.executablePath !== exe ||
+                persisted.version !== version ||
+                persisted.installSource !== install?.source ||
+                persisted.ignoreSystemInstall === true;
+            const shouldPersistRoutes = persisted.detectedRoutes?.codex !== detectedRoutes.codex ||
+                persisted.detectedRoutes?.claude !== detectedRoutes.claude ||
+                persisted.activeProviders?.codex !== activeProviders.codex ||
+                persisted.activeProviders?.claude !== activeProviders.claude;
+            if (shouldPersistInstall || shouldPersistRoutes) {
+                this.updatePersisted({
+                    installed: true,
+                    version,
+                    executablePath: exe,
+                    installSource: install?.source ?? null,
+                    ignoreSystemInstall: false,
+                    detectedRoutes,
+                    activeProviders,
+                });
+            }
+        }
+        this.refreshMetricsInBackground();
+        const learning = {
+            enabled: persisted.learningEnabled ?? installed,
+            ...this.readLearningBaseline(),
+            updatedAt: persisted.learningUpdatedAt ?? null,
+            lastIssue: persisted.learningIssue ?? null,
+        };
+        const metrics = this.decorateMetrics(this.metricsCache, activeProviders, availableProviders, detectedRoutes);
+        return {
+            installed,
+            installSource: installed ? install?.source ?? null : null,
+            version: version ?? persisted.version ?? null,
+            executablePath: exe,
+            uvPath,
+            port: this.validPort(persisted.port),
+            phase: installed ? (activeProviders.codex || activeProviders.claude ? 'active' : 'installed') : 'idle',
+            activeProviders,
+            availableProviders,
+            detectedRoutes,
+            proxyRunning: (activeProviders.codex || activeProviders.claude) && this.isProxyAvailable(),
+            proxyPid: this.proxy?.pid ?? null,
+            learning,
+            metrics,
+            lastIssue: persisted.lastIssue ?? null,
+            updatedAt: persisted.updatedAt ?? null,
+        };
+    }
+    async getFreshState() {
+        await this.refreshMetrics();
+        return this.getState();
+    }
+    async install() {
+        const uv = this.resolveUvPath();
+        if (!uv) {
+            const failure = issue('uv_missing_or_corrupt');
+            this.updatePersisted({ lastIssue: failure });
+            return { ok: false, state: this.getState(), issue: failure };
+        }
+        fs_1.default.mkdirSync(uvToolDir(), { recursive: true });
+        fs_1.default.mkdirSync(uvCacheDir(), { recursive: true });
+        fs_1.default.mkdirSync(uvBinDir(), { recursive: true });
+        const args = ['tool', 'install', 'headroom-ai[all]', '--force'];
+        const command = `${uv} ${args.join(' ')}`;
+        const logs = [`Running ${command}`];
+        this.emit('installing', logs[0]);
+        const result = await this.runCommand(uv, args, {
+            UV_TOOL_DIR: uvToolDir(),
+            UV_TOOL_BIN_DIR: uvBinDir(),
+            UV_CACHE_DIR: uvCacheDir(),
+            UV_NO_PROGRESS: '1',
+        }, logs);
+        if (result.code !== 0) {
+            const failure = classifyInstallFailure(logs.join('\n'), command);
+            this.updatePersisted({ lastIssue: failure });
+            this.emit('failed', failure.title);
+            return { ok: false, state: this.getState(), issue: failure, logs };
+        }
+        const exe = this.resolveHeadroomInstall(null, false)?.path ?? null;
+        const version = exe ? this.readHeadroomVersion(exe) : null;
+        if (!exe || !version) {
+            const failure = issue('headroom_not_found_after_install', logs.join('\n'), command);
+            this.updatePersisted({ lastIssue: failure });
+            this.emit('failed', failure.title);
+            return { ok: false, state: this.getState(), issue: failure, logs };
+        }
+        this.updatePersisted({
+            installed: true,
+            version,
+            executablePath: exe,
+            installSource: 'managed',
+            ignoreSystemInstall: false,
+            lastIssue: null,
+        });
+        await this.enableOutputLearning(exe, logs);
+        this.emit('installed', `Headroom ${version} installed`);
+        await this.refreshMetrics();
+        return { ok: true, state: this.getState(), logs };
+    }
+    async activate(provider) {
+        const state = this.getState();
+        if (!state.installed || !state.executablePath) {
+            const failure = issue('not_installed');
+            this.updatePersisted({ lastIssue: failure });
+            return { ok: false, state: this.getState(), issue: failure };
+        }
+        const proxy = await this.ensureProxy();
+        if (!proxy.ok)
+            return proxy;
+        const current = this.readPersisted();
+        const activeProviders = { ...current.activeProviders, [provider]: true };
+        this.updatePersisted({ activeProviders, lastIssue: null });
+        this.syncRouting();
+        if (!this.verifyProviderRoute(provider)) {
+            const rolledBack = { ...activeProviders, [provider]: false };
+            this.updatePersisted({ activeProviders: rolledBack, lastIssue: issue('provider_route_failed') });
+            this.syncRouting();
+            return { ok: false, state: this.getState(), issue: issue('provider_route_failed') };
+        }
+        this.emit('active', `${provider} routed through Headroom`);
+        return { ok: true, state: this.getState() };
+    }
+    async deactivate(provider) {
+        const current = this.readPersisted();
+        const activeProviders = { ...current.activeProviders, [provider]: false };
+        this.updatePersisted({ activeProviders, lastIssue: null });
+        this.syncRouting();
+        if (!activeProviders.codex && !activeProviders.claude)
+            this.stopProxy();
+        this.emit('installed', `${provider} Headroom route disabled`);
+        return { ok: true, state: this.getState() };
+    }
+    async uninstall() {
+        const before = this.getState();
+        this.updatePersisted({
+            activeProviders: { codex: false, claude: false },
+            lastIssue: null,
+        });
+        this.stopProxy();
+        this.syncRouting();
+        if (!before.installed && !before.executablePath) {
+            this.updatePersisted({
+                installed: false,
+                version: null,
+                executablePath: null,
+                installSource: null,
+                activeProviders: { codex: false, claude: false },
+                detectedRoutes: { codex: false, claude: false },
+                lastIssue: null,
+            });
+            return { ok: true, state: this.getState() };
+        }
+        if (before.installSource === 'system') {
+            this.updatePersisted({
+                installed: false,
+                version: null,
+                executablePath: null,
+                installSource: null,
+                ignoreSystemInstall: true,
+                activeProviders: { codex: false, claude: false },
+                detectedRoutes: { codex: false, claude: false },
+                lastIssue: null,
+            });
+            this.emit('idle', 'External Headroom detached from Specrails');
+            return { ok: true, state: this.getState(), logs: ['External Headroom install left untouched; Specrails routing disabled.'] };
+        }
+        const uv = this.resolveUvPath();
+        if (!uv) {
+            const failure = issue('uv_missing_or_corrupt');
+            this.updatePersisted({ lastIssue: failure });
+            return { ok: false, state: this.getState(), issue: failure };
+        }
+        const args = ['tool', 'uninstall', 'headroom-ai'];
+        const command = `${uv} ${args.join(' ')}`;
+        const logs = [`Running ${command}`];
+        this.emit('installing', logs[0]);
+        const result = await this.runCommand(uv, args, {
+            UV_TOOL_DIR: uvToolDir(),
+            UV_TOOL_BIN_DIR: uvBinDir(),
+            UV_CACHE_DIR: uvCacheDir(),
+            UV_NO_PROGRESS: '1',
+        }, logs);
+        const stillInstalled = fileExists(path_1.default.join(uvBinDir(), headroomExeName()));
+        if (result.code !== 0 || stillInstalled) {
+            const failure = issue('uninstall_failed', logs.join('\n'), command);
+            this.updatePersisted({ lastIssue: failure });
+            this.emit('failed', failure.title);
+            return { ok: false, state: this.getState(), issue: failure, logs };
+        }
+        this.updatePersisted({
+            installed: false,
+            version: null,
+            executablePath: null,
+            installSource: null,
+            activeProviders: { codex: false, claude: false },
+            detectedRoutes: { codex: false, claude: false },
+            lastIssue: null,
+        });
+        this.emit('idle', 'Headroom uninstalled');
+        return { ok: true, state: this.getState(), logs };
+    }
+    async setPort(port) {
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            const failure = issue('proxy_port_busy', 'Port must be an integer between 1 and 65535.');
+            return { ok: false, state: this.getState(), issue: failure };
+        }
+        const active = this.getState().activeProviders;
+        this.stopProxy();
+        this.updatePersisted({ port, lastIssue: null });
+        this.syncRouting();
+        if (active.codex || active.claude) {
+            return this.ensureProxy();
+        }
+        return { ok: true, state: this.getState() };
+    }
+    diagnostics() {
+        const state = this.getState();
+        return {
+            state,
+            toolDir: uvToolDir(),
+            binDir: uvBinDir(),
+            cacheDir: uvCacheDir(),
+            proxyTail: this.proxyTail.slice(-4000),
+            installSource: state.installSource,
+            detectedRoutes: state.detectedRoutes,
+            availableProviders: state.availableProviders,
+            learning: state.learning,
+            metrics: state.metrics,
+            routing: {
+                codex: state.activeProviders.codex ? `OPENAI_BASE_URL=http://127.0.0.1:${state.port}/v1` : null,
+                claude: state.activeProviders.claude ? `ANTHROPIC_BASE_URL=http://127.0.0.1:${state.port}` : null,
+            },
+        };
+    }
+    async startActiveProxyOnBoot() {
+        const active = this.getState().activeProviders;
+        this.syncRouting();
+        if (active.codex || active.claude) {
+            const result = await this.ensureProxy();
+            if (!result.ok) {
+                console.warn('[headroom] boot proxy start failed:', result.issue);
+            }
+        }
+    }
+    async ensureProxy() {
+        const state = this.getState();
+        if (!state.installed || !state.executablePath) {
+            const failure = issue('not_installed');
+            return { ok: false, state, issue: failure };
+        }
+        if (this.isProxyRunning())
+            return { ok: true, state };
+        if (await this.adoptHealthyProxy(state.port)) {
+            return { ok: true, state: this.getState() };
+        }
+        const args = ['proxy', '--host', '127.0.0.1', '--port', String(state.port)];
+        const command = `${state.executablePath} ${args.join(' ')}`;
+        this.emit('starting-proxy', `Starting proxy on ${state.port}`);
+        this.proxyTail = '';
+        const child = (0, child_process_1.spawn)(state.executablePath, args, {
+            env: {
+                ...process.env,
+                HEADROOM_PORT: String(state.port),
+                HEADROOM_OUTPUT_SHAPER: '1',
+                HEADROOM_LEARN: state.learning.enabled ? '1' : '0',
+                HEADROOM_SAVINGS_PROFILE: process.env.HEADROOM_SAVINGS_PROFILE ?? 'agent-90',
+                HEADROOM_MODE: process.env.HEADROOM_MODE ?? 'token',
+            },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        this.proxy = child;
+        child.stdout?.on('data', (chunk) => { this.proxyTail += chunk.toString(); this.trimProxyTail(); });
+        child.stderr?.on('data', (chunk) => { this.proxyTail += chunk.toString(); this.trimProxyTail(); });
+        child.on('close', () => {
+            if (this.proxy === child)
+                this.proxy = null;
+        });
+        const healthy = await this.waitForProxyHealthy(state.port, 6000);
+        if (!healthy) {
+            const failure = classifyProxyFailure(this.proxyTail, command);
+            this.stopProxy();
+            this.updatePersisted({ lastIssue: failure });
+            this.emit('failed', failure.title);
+            return { ok: false, state: this.getState(), issue: failure };
+        }
+        this.updatePersisted({ lastIssue: null });
+        await this.refreshMetrics();
+        return { ok: true, state: this.getState() };
+    }
+    resolveUvPath() {
+        for (const p of bundledUvCandidates()) {
+            if (fileExists(p))
+                return p;
+        }
+        return which('uv');
+    }
+    resolveHeadroomInstall(persisted, ignoreSystemInstall) {
+        const managed = path_1.default.join(uvBinDir(), headroomExeName());
+        if (fileExists(managed))
+            return { path: managed, source: 'managed' };
+        if (fileExists(persisted)) {
+            return { path: persisted, source: persisted === managed ? 'managed' : 'system' };
+        }
+        if (ignoreSystemInstall)
+            return null;
+        const system = which('headroom');
+        return system ? { path: system, source: 'system' } : null;
+    }
+    availableProviderRecord() {
+        const available = new Set(this.availableProvidersSupplier());
+        return {
+            codex: available.has('codex'),
+            claude: available.has('claude'),
+        };
+    }
+    detectProviderRoutes(exe) {
+        const now = Date.now();
+        if (this.routeDetectionCache?.executablePath === exe && this.routeDetectionCache.expiresAt > now) {
+            return this.routeDetectionCache.routes;
+        }
+        const routes = { codex: false, claude: false };
+        try {
+            const state = this.readPersisted();
+            const probe = (0, child_process_1.spawnSync)(exe, ['doctor', '--json', '--port', String(this.validPort(state.port))], {
+                encoding: 'utf8',
+                timeout: 5000,
+                env: process.env,
+            });
+            const raw = `${probe.stdout ?? ''}`.trim();
+            const parsed = raw ? JSON.parse(raw) : {};
+            for (const check of parsed.checks ?? []) {
+                const provider = normalizeProviderKey(check.name);
+                if (!provider)
+                    continue;
+                const routed = check.status === 'pass' || String(check.summary ?? '').toLowerCase().includes('routed');
+                if (routed)
+                    routes[provider] = true;
+            }
+            this.routeDetectionCache = { executablePath: exe, expiresAt: now + 10_000, routes, raw: parsed };
+        }
+        catch {
+            this.routeDetectionCache = { executablePath: exe, expiresAt: now + 10_000, routes, raw: null };
+        }
+        return routes;
+    }
+    readHeadroomVersion(exe) {
+        const probe = (0, child_process_1.spawnSync)(exe, ['--version'], { encoding: 'utf8', timeout: 5000 });
+        if (probe.status !== 0)
+            return null;
+        return parseHeadroomVersion(`${probe.stdout ?? ''}${probe.stderr ?? ''}`);
+    }
+    readLearningBaseline() {
+        const candidates = [
+            process.env.HEADROOM_WORKSPACE_DIR
+                ? path_1.default.join(process.env.HEADROOM_WORKSPACE_DIR, 'output_savings.json')
+                : null,
+            path_1.default.join(os_1.default.homedir(), '.headroom', 'output_savings.json'),
+        ].filter((value) => !!value);
+        for (const candidate of candidates) {
+            try {
+                if (!fs_1.default.existsSync(candidate))
+                    continue;
+                const raw = JSON.parse(fs_1.default.readFileSync(candidate, 'utf8'));
+                const samples = Math.max(0, Math.trunc(num(raw.baseline?.glob?.n)));
+                return { baselineReady: samples > 0, baselineSamples: samples };
+            }
+            catch {
+                // Keep looking; a corrupt baseline should not break plugin state.
+            }
+        }
+        return { baselineReady: false, baselineSamples: 0 };
+    }
+    async enableOutputLearning(exe, logs) {
+        const args = ['learn', '--verbosity', '--apply'];
+        const command = `${exe} ${args.join(' ')}`;
+        logs.push(`Running ${command}`);
+        this.emit('installing', 'Calibrating output-savings baseline');
+        const result = await this.runCommand(exe, args, {
+            HEADROOM_OUTPUT_SHAPER: '1',
+            HEADROOM_SAVINGS_PROFILE: process.env.HEADROOM_SAVINGS_PROFILE ?? 'agent-90',
+        }, logs);
+        if (result.code === 0) {
+            this.updatePersisted({
+                learningEnabled: true,
+                learningUpdatedAt: nowIso(),
+                learningIssue: null,
+            });
+            return;
+        }
+        const failure = issue('learning_setup_failed', logs.slice(-30).join('\n'), command);
+        this.updatePersisted({
+            learningEnabled: true,
+            learningUpdatedAt: nowIso(),
+            learningIssue: failure,
+        });
+    }
+    refreshMetricsInBackground() {
+        const state = this.getMetricsPrereqState();
+        if (!state.installed || !state.executablePath)
+            return;
+        if (this.metricsRefresh)
+            return;
+        const last = this.metricsCache.updatedAt ? Date.parse(this.metricsCache.updatedAt) : 0;
+        if (Date.now() - last < 5000)
+            return;
+        this.metricsRefresh = this.refreshMetrics().finally(() => {
+            this.metricsRefresh = null;
+        });
+    }
+    getMetricsPrereqState() {
+        const persisted = this.readPersisted();
+        const install = this.resolveHeadroomInstall(persisted.executablePath ?? null, !!persisted.ignoreSystemInstall);
+        const availableProviders = this.availableProviderRecord();
+        const detectedRoutes = install?.path ? this.detectProviderRoutes(install.path) : providerRecord(persisted.detectedRoutes);
+        return {
+            installed: !!install?.path,
+            executablePath: install?.path ?? null,
+            port: this.validPort(persisted.port),
+            availableProviders,
+            detectedRoutes,
+            activeProviders: {
+                codex: persisted.activeProviders?.codex ?? (availableProviders.codex && detectedRoutes.codex),
+                claude: persisted.activeProviders?.claude ?? (availableProviders.claude && detectedRoutes.claude),
+            },
+        };
+    }
+    async refreshMetrics() {
+        const state = this.getMetricsPrereqState();
+        if (!state.installed || !state.executablePath) {
+            this.metricsCache = emptyMetricsState();
+            return;
+        }
+        const metrics = emptyMetricsState();
+        const byProvider = {
+            codex: { ...emptyProviderMetric('codex') },
+            claude: { ...emptyProviderMetric('claude') },
+        };
+        try {
+            const savings = await this.readDurableSavings(state.executablePath);
+            if (savings) {
+                metrics.durableSavingsAvailable = true;
+                for (const row of savings.by_client ?? []) {
+                    const provider = normalizeProviderKey(row.client);
+                    if (!provider)
+                        continue;
+                    byProvider[provider].requests = Math.max(byProvider[provider].requests, Math.trunc(num(row.calls)));
+                    byProvider[provider].inputTokensSaved = Math.max(byProvider[provider].inputTokensSaved, Math.trunc(num(row.tokens_saved)));
+                    byProvider[provider].inputTokens = Math.max(byProvider[provider].inputTokens, maxNumericField(row, INPUT_TOKEN_FIELDS));
+                }
+            }
+        }
+        catch (err) {
+            metrics.lastIssue = issue('metrics_unavailable', err instanceof Error ? err.message : String(err));
+        }
+        const stats = state.activeProviders.codex || state.activeProviders.claude
+            ? await this.readProxyStats(state.port).catch((err) => {
+                metrics.lastIssue = issue('metrics_unavailable', err instanceof Error ? err.message : String(err));
+                return null;
+            })
+            : null;
+        if (stats) {
+            metrics.proxyStatsAvailable = true;
+            const agents = Array.isArray(stats.agent_usage?.agents) ? stats.agent_usage.agents : [];
+            for (const agent of agents) {
+                const provider = normalizeProviderKey(agent.agent ?? agent.label ?? agent.source);
+                if (!provider)
+                    continue;
+                byProvider[provider].requests = Math.max(byProvider[provider].requests, Math.trunc(num(agent.requests)));
+                byProvider[provider].inputTokensSaved = Math.max(byProvider[provider].inputTokensSaved, Math.trunc(num(agent.tokens_saved)));
+                byProvider[provider].inputTokens = Math.max(byProvider[provider].inputTokens, maxNumericField(agent, INPUT_TOKEN_FIELDS));
+                byProvider[provider].outputTokens = Math.max(byProvider[provider].outputTokens, maxNumericField(agent, OUTPUT_TOKEN_FIELDS));
+            }
+            const outputReduction = stats.tokens?.output_reduction;
+            if (outputReduction?.available) {
+                const method = outputReduction.method === 'measured' ? 'measured' : 'estimated';
+                const totalOutputSaved = Math.round(num(outputReduction.tokens_saved));
+                const totalWeight = ['codex', 'claude'].reduce((sum, provider) => {
+                    const row = byProvider[provider];
+                    return sum + (row.outputTokens || row.requests || (state.activeProviders[provider] ? 1 : 0));
+                }, 0);
+                metrics.outputSavingsAvailable = true;
+                metrics.outputSavingsMethod = method;
+                metrics.outputConfidence = {
+                    lowPercent: num(outputReduction.ci_low_percent),
+                    highPercent: num(outputReduction.ci_high_percent),
+                };
+                for (const provider of ['codex', 'claude']) {
+                    const row = byProvider[provider];
+                    const weight = row.outputTokens || row.requests || (state.activeProviders[provider] ? 1 : 0);
+                    const outputSaved = totalWeight > 0 ? Math.round(totalOutputSaved * (weight / totalWeight)) : 0;
+                    row.outputTokensSaved = outputSaved;
+                    row.outputSavingsPercent = num(outputReduction.reduction_percent);
+                    row.outputSavingsMethod = method;
+                    row.outputSavingsAllocated = totalWeight > weight;
+                }
+            }
+        }
+        metrics.updatedAt = nowIso();
+        metrics.providers = this.decorateMetricProviders(byProvider, state.activeProviders, state.availableProviders, state.detectedRoutes);
+        this.metricsCache = metrics;
+    }
+    async readDurableSavings(exe) {
+        const result = await this.runCommandCapture(exe, ['savings', '--json'], {}, 5000);
+        if (result.code !== 0 || !result.output.trim())
+            return null;
+        return JSON.parse(result.output);
+    }
+    async readProxyStats(port) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 2500);
+        try {
+            const res = await fetch(`http://127.0.0.1:${port}/stats?cached=1`, { signal: controller.signal });
+            if (!res.ok)
+                return null;
+            return await res.json();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    decorateMetrics(metrics, activeProviders, availableProviders, detectedRoutes) {
+        return {
+            ...metrics,
+            providers: this.decorateMetricProviders(metrics.providers, activeProviders, availableProviders, detectedRoutes),
+        };
+    }
+    decorateMetricProviders(providers, activeProviders, availableProviders, detectedRoutes) {
+        return {
+            codex: {
+                ...emptyProviderMetric('codex'),
+                ...providers.codex,
+                active: activeProviders.codex,
+                available: availableProviders.codex,
+                detectedRoute: detectedRoutes.codex,
+            },
+            claude: {
+                ...emptyProviderMetric('claude'),
+                ...providers.claude,
+                active: activeProviders.claude,
+                available: availableProviders.claude,
+                detectedRoute: detectedRoutes.claude,
+            },
+        };
+    }
+    async runCommand(command, args, extraEnv, logs) {
+        return new Promise((resolve) => {
+            const child = (0, child_process_1.spawn)(command, args, {
+                env: { ...process.env, ...extraEnv },
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            child.stdout?.on('data', (chunk) => {
+                for (const line of chunk.toString().split(/\r?\n/)) {
+                    if (!line)
+                        continue;
+                    logs.push(line);
+                    this.emit('installing', line);
+                }
+            });
+            child.stderr?.on('data', (chunk) => {
+                for (const line of chunk.toString().split(/\r?\n/)) {
+                    if (!line)
+                        continue;
+                    logs.push(line);
+                    this.emit('installing', line);
+                }
+            });
+            child.on('error', (err) => {
+                logs.push(err.message);
+                resolve({ code: null });
+            });
+            child.on('close', (code) => resolve({ code }));
+        });
+    }
+    async runCommandCapture(command, args, extraEnv, timeoutMs) {
+        return new Promise((resolve) => {
+            let output = '';
+            let settled = false;
+            const child = (0, child_process_1.spawn)(command, args, {
+                env: { ...process.env, ...extraEnv },
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            const settle = (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve({ code, output });
+            };
+            const timer = setTimeout(() => {
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { /* ignore */ }
+                settle(null);
+            }, timeoutMs);
+            child.stdout?.on('data', (chunk) => { output += chunk.toString(); });
+            child.stderr?.on('data', (chunk) => { output += chunk.toString(); });
+            child.on('error', (err) => {
+                output += err.message;
+                settle(null);
+            });
+            child.on('close', (code) => settle(code));
+        });
+    }
+    async waitForProxyHealthy(port, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            try {
+                const res = await fetch(`http://127.0.0.1:${port}/livez`);
+                if (res.ok)
+                    return true;
+            }
+            catch {
+                // retry until timeout
+            }
+            await new Promise((r) => setTimeout(r, 250));
+        }
+        return false;
+    }
+    verifyProviderRoute(provider) {
+        const state = this.getState();
+        return provider === 'codex'
+            ? !!state.activeProviders.codex && state.port > 0
+            : !!state.activeProviders.claude && state.port > 0;
+    }
+    isProxyRunning() {
+        return !!this.proxy && !this.proxy.killed && this.proxy.exitCode == null;
+    }
+    async adoptHealthyProxy(port) {
+        if (!await this.waitForProxyHealthy(port, 750))
+            return false;
+        await this.refreshMetrics();
+        this.updatePersisted({ lastIssue: null });
+        return true;
+    }
+    isProxyAvailable() {
+        return this.isProxyRunning() || this.metricsCache.proxyStatsAvailable;
+    }
+    stopProxy() {
+        const child = this.proxy;
+        this.proxy = null;
+        if (child && !child.killed) {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+        }
+    }
+    trimProxyTail() {
+        if (this.proxyTail.length > 32_000)
+            this.proxyTail = this.proxyTail.slice(-32_000);
+    }
+    validPort(value) {
+        return Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 65535 ? Number(value) : DEFAULT_PORT;
+    }
+    readPersisted() {
+        const raw = (0, desktop_db_1.getDesktopSetting)(this.db, STATE_KEY);
+        if (!raw)
+            return { port: DEFAULT_PORT, activeProviders: {} };
+        try {
+            const parsed = JSON.parse(raw);
+            return { port: DEFAULT_PORT, activeProviders: {}, ...parsed };
+        }
+        catch {
+            return { port: DEFAULT_PORT, activeProviders: {} };
+        }
+    }
+    updatePersisted(patch) {
+        const next = {
+            ...this.readPersisted(),
+            ...patch,
+            updatedAt: nowIso(),
+        };
+        (0, desktop_db_1.setDesktopSetting)(this.db, STATE_KEY, JSON.stringify(next));
+        this.syncRouting();
+    }
+    syncRouting() {
+        const persisted = this.readPersisted();
+        (0, headroom_routing_1.setHeadroomRoutingState)({
+            port: this.validPort(persisted.port),
+            activeProviders: {
+                codex: !!persisted.activeProviders?.codex,
+                claude: !!persisted.activeProviders?.claude,
+            },
+        });
+    }
+    emit(phase, line) {
+        this.broadcast({
+            type: 'plugin.headroom_progress',
+            name: 'headroom-ai',
+            status: phase,
+            line,
+            timestamp: nowIso(),
+        });
+    }
+}
+exports.HeadroomManager = HeadroomManager;