sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/providers/codexDatabase.js

@@ -0,0 +1,297 @@
+/**
+ * Read-only SQLite wrapper for Codex CLI's state database.
+ * Ported from sidekick-vscode/src/services/providers/CodexDatabase.ts
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFile, execFileSync } from 'child_process';
+/**
+ * Ids per inlined `IN (…)` query. Values are passed inside a single argv
+ * element to sqlite3, so an unbounded list would hit E2BIG on large stores.
+ */
+const SQL_ID_CHUNK_SIZE = 400;
+/** Parent thread id recorded in a Codex `threads.source` JSON value, if any. */
+export function spawnParentFromSource(source) {
+    let parsed = source;
+    if (typeof source === 'string') {
+        if (!source.startsWith('{'))
+            return undefined;
+        try {
+            parsed = JSON.parse(source);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    const parent = parsed
+        .subagent?.thread_spawn?.parent_thread_id;
+    return typeof parent === 'string' ? parent : undefined;
+}
+export class CodexDatabase {
+    dbPath;
+    sqlite3Available = null;
+    runtimeStatus = null;
+    constructor(codexHome) {
+        this.dbPath = findLatestStateDatabase(codexHome) ?? path.join(codexHome, 'state.sqlite');
+    }
+    isAvailable() {
+        try {
+            return fs.statSync(this.dbPath).size > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    open() {
+        if (this.sqlite3Available !== null)
+            return this.sqlite3Available;
+        if (!this.isAvailable()) {
+            this.sqlite3Available = false;
+            this.runtimeStatus = { available: false, kind: 'db_missing' };
+            return false;
+        }
+        try {
+            execFileSync('sqlite3', ['--version'], {
+                encoding: 'utf-8',
+                timeout: 4000,
+                killSignal: 'SIGKILL',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            this.sqlite3Available = true;
+            this.runtimeStatus = { available: true, kind: 'available' };
+            return true;
+        }
+        catch (error) {
+            this.sqlite3Available = false;
+            this.runtimeStatus = classifySqliteError(error);
+            return false;
+        }
+    }
+    getRuntimeStatus() {
+        if (this.runtimeStatus)
+            return this.runtimeStatus;
+        if (!this.isAvailable())
+            return { available: false, kind: 'db_missing' };
+        return {
+            available: false,
+            kind: 'query_failed',
+            message: 'Codex database has not been initialized yet.',
+        };
+    }
+    close() { }
+    query(sql, params = []) {
+        if (!this.sqlite3Available)
+            return [];
+        let paramIndex = 0;
+        const query = sql.replace(/\?/g, () => {
+            if (paramIndex >= params.length)
+                return '?';
+            const param = params[paramIndex++];
+            if (typeof param === 'number') {
+                if (!Number.isFinite(param))
+                    return '0';
+                return String(param);
+            }
+            const escaped = String(param).replace(/'/g, "''");
+            return `'${escaped}'`;
+        });
+        try {
+            const result = execFileSync('sqlite3', ['-json', '-readonly', this.dbPath, query], {
+                encoding: 'utf-8',
+                timeout: 4000,
+                killSignal: 'SIGKILL',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                maxBuffer: 10 * 1024 * 1024,
+            });
+            const trimmed = result.trim();
+            if (!trimmed)
+                return [];
+            return JSON.parse(trimmed);
+        }
+        catch (error) {
+            this.runtimeStatus = {
+                ...classifySqliteError(error, 'query_failed'),
+                available: this.sqlite3Available === true,
+            };
+            return [];
+        }
+    }
+    async queryAsync(sql, params = []) {
+        if (!this.isAvailable()) {
+            this.runtimeStatus = { available: false, kind: 'db_missing' };
+            return [];
+        }
+        const query = bindSqlParams(sql, params);
+        try {
+            const result = await execSqlite(this.dbPath, query, 10 * 1024 * 1024);
+            this.sqlite3Available = true;
+            this.runtimeStatus = { available: true, kind: 'available' };
+            const trimmed = result.trim();
+            return trimmed ? JSON.parse(trimmed) : [];
+        }
+        catch (error) {
+            const status = classifySqliteError(error, 'query_failed');
+            // Only a missing sqlite3 binary gates future attempts. A failed query
+            // is transient and must not latch the database off (mirrors query()).
+            if (status.kind === 'sqlite_missing')
+                this.sqlite3Available = false;
+            this.runtimeStatus = status;
+            return [];
+        }
+    }
+    queryOne(sql, params = []) {
+        return this.query(sql, params)[0] ?? null;
+    }
+    getThreadsByCwd(cwd) {
+        const normalized = normalizePath(cwd);
+        const exact = this.query('SELECT * FROM threads WHERE cwd = ? ORDER BY updated_at DESC', [normalized]);
+        if (exact.length > 0)
+            return exact;
+        const all = this.query('SELECT * FROM threads ORDER BY updated_at DESC');
+        return all.filter((t) => {
+            const threadCwd = normalizePath(t.cwd);
+            return (threadCwd === normalized ||
+                normalized.startsWith(threadCwd + path.sep) ||
+                threadCwd.startsWith(normalized + path.sep));
+        });
+    }
+    getMostRecentThread(cwd) {
+        return this.getThreadsByCwd(cwd)[0] ?? null;
+    }
+    getAllDistinctCwds() {
+        return this.query('SELECT cwd, COUNT(*) as count, MAX(updated_at) as lastUpdated FROM threads GROUP BY cwd ORDER BY lastUpdated DESC');
+    }
+    getThread(id) {
+        return this.queryOne('SELECT * FROM threads WHERE id = ?', [id]);
+    }
+    /**
+     * Resolve many thread ids with non-blocking sqlite3 subprocesses — one per
+     * chunk of ids, so the inlined query stays clear of argv length limits.
+     */
+    async getThreadsByIdsAsync(ids) {
+        const results = [];
+        for (let i = 0; i < ids.length; i += SQL_ID_CHUNK_SIZE) {
+            const chunk = ids.slice(i, i + SQL_ID_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(', ');
+            results.push(...(await this.queryAsync(`SELECT * FROM threads WHERE id IN (${placeholders})`, [...chunk])));
+        }
+        return results;
+    }
+    threadColumns = null;
+    /** Column names of the `threads` table (cached; the schema varies across Codex versions). */
+    getThreadColumns() {
+        if (!this.threadColumns) {
+            const rows = this.query("SELECT name FROM pragma_table_info('threads')");
+            if (rows.length === 0)
+                return new Set();
+            this.threadColumns = new Set(rows.map((row) => row.name));
+        }
+        return this.threadColumns;
+    }
+    /**
+     * Get all threads forked from a given session ID. Older Codex schemas carry
+     * a `forked_from_id` column; newer ones drop it, so the query only runs
+     * when the column exists (otherwise it fails and reports a diagnostic).
+     */
+    getThreadsByForkedFromId(parentId) {
+        if (!this.getThreadColumns().has('forked_from_id'))
+            return [];
+        return this.query('SELECT * FROM threads WHERE forked_from_id = ? ORDER BY created_at ASC', [parentId]);
+    }
+    /**
+     * Get the subagent threads a session spawned. Codex records the parent in
+     * the `source` JSON (`{"subagent":{"thread_spawn":{"parent_thread_id":…}}}`);
+     * the LIKE narrows the scan and the JSON parse confirms the match.
+     */
+    getSpawnedChildThreads(parentId) {
+        if (!this.getThreadColumns().has('source'))
+            return [];
+        const rows = this.query('SELECT * FROM threads WHERE source LIKE ? ORDER BY created_at ASC', [`%${parentId}%`]);
+        return rows.filter((row) => spawnParentFromSource(row.source) === parentId);
+    }
+    /** Get the database file's mtime (ms epoch). Returns 0 if unavailable. */
+    getDbMtime() {
+        try {
+            return fs.statSync(this.dbPath).mtime.getTime();
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+function classifySqliteError(error, fallback = 'sqlite_blocked') {
+    const code = error?.code;
+    if (code === 'ENOENT') {
+        return {
+            available: false,
+            kind: 'sqlite_missing',
+            message: 'The sqlite3 executable was not found.',
+        };
+    }
+    return {
+        available: false,
+        kind: fallback,
+        message: error instanceof Error ? error.message : 'sqlite3 could not be executed.',
+    };
+}
+function bindSqlParams(sql, params) {
+    let paramIndex = 0;
+    return sql.replace(/\?/g, () => {
+        if (paramIndex >= params.length)
+            return '?';
+        const param = params[paramIndex++];
+        if (typeof param === 'number')
+            return Number.isFinite(param) ? String(param) : '0';
+        return `'${String(param).replace(/'/g, "''")}'`;
+    });
+}
+function execSqlite(dbPath, query, maxBuffer) {
+    return new Promise((resolve, reject) => {
+        execFile('sqlite3', ['-json', '-readonly', dbPath, query], {
+            encoding: 'utf8',
+            timeout: 4_000,
+            killSignal: 'SIGKILL',
+            maxBuffer,
+        }, (error, stdout) => {
+            if (error)
+                reject(error);
+            else
+                resolve(stdout);
+        });
+    });
+}
+function findLatestStateDatabase(codexHome) {
+    try {
+        const entries = fs.readdirSync(codexHome, { withFileTypes: true });
+        const candidates = [];
+        for (const entry of entries) {
+            if (!entry.isFile() || !/^state(?:_\d+)?\.sqlite$/.test(entry.name))
+                continue;
+            const dbPath = path.join(codexHome, entry.name);
+            try {
+                const stat = fs.statSync(dbPath);
+                if (stat.size > 0) {
+                    candidates.push({ path: dbPath, mtime: stat.mtime.getTime() });
+                }
+            }
+            catch {
+                // Skip inaccessible candidates.
+            }
+        }
+        candidates.sort((a, b) => b.mtime - a.mtime);
+        return candidates[0]?.path ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function normalizePath(input) {
+    try {
+        return fs.realpathSync(input);
+    }
+    catch {
+        return path.resolve(input);
+    }
+}

package/dist/esm/providers/codexRollouts.js

@@ -0,0 +1,215 @@
+/**
+ * Codex rollout-file helpers shared by the provider and by callers that only
+ * list rollouts: bounded first-line reads, session_meta and cwd lookups, and
+ * the async session-file listing. Kept apart from the provider class so a
+ * listing does not bundle the provider's stats, context and reader code.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCodexSessionsDirs } from '../codexPaths';
+import { DirectoryListingCache } from './directoryListingCache';
+import { walkRolloutFilesAsync } from './rolloutWalker';
+/** Every directory across the monitored homes that may hold rollouts, archived ones included. */
+export function getSessionsDirs() {
+    return getCodexSessionsDirs();
+}
+/**
+ * Read the first N complete lines from a file using chunked reads.
+ * Handles arbitrarily long lines (Codex session_meta can be 10KB+).
+ */
+export function readFirstLines(filePath, maxLines, maxBytes = 256 * 1024) {
+    const lines = [];
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch {
+        return [];
+    }
+    let pending = '';
+    let totalRead = 0;
+    const chunkSize = 16384;
+    try {
+        while (totalRead < maxBytes && lines.length < maxLines) {
+            const buf = Buffer.alloc(Math.min(chunkSize, maxBytes - totalRead));
+            const bytesRead = fs.readSync(fd, buf, 0, buf.length, totalRead);
+            if (bytesRead === 0)
+                break;
+            totalRead += bytesRead;
+            pending += buf.toString('utf-8', 0, bytesRead);
+            let nlIdx;
+            while ((nlIdx = pending.indexOf('\n')) !== -1 && lines.length < maxLines) {
+                lines.push(pending.substring(0, nlIdx));
+                pending = pending.substring(nlIdx + 1);
+            }
+        }
+        if (pending.trim() && lines.length < maxLines) {
+            lines.push(pending);
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return lines;
+}
+/** Read session_meta from the beginning of a rollout file. */
+export function readSessionMeta(rolloutPath) {
+    try {
+        const lines = readFirstLines(rolloutPath, 1);
+        const firstLine = lines[0]?.trim();
+        if (!firstLine)
+            return null;
+        const parsed = JSON.parse(firstLine);
+        if (parsed.type === 'session_meta') {
+            return parsed.payload;
+        }
+    }
+    catch {
+        // Skip
+    }
+    return null;
+}
+/**
+ * First line of a rollout, chunk-read under the same 256 KiB cap as
+ * readFirstLines(). `complete` is false while the line has no newline yet
+ * (a rollout that was just created) or the file could not be read, so
+ * callers know not to cache the answer.
+ */
+export async function readFirstLineAsync(rolloutPath) {
+    // Mirrors readSessionMeta()/readFirstLines(): chunk-read until the first
+    // line is complete under the same 256 KiB cap — session_meta carries
+    // `instructions` and can far exceed a single chunk.
+    const maxBytes = 256 * 1024;
+    const chunkSize = 64 * 1024;
+    let handle = null;
+    try {
+        handle = await fs.promises.open(rolloutPath, 'r');
+        const chunks = [];
+        let totalRead = 0;
+        let newlineFound = false;
+        while (totalRead < maxBytes && !newlineFound) {
+            const buffer = Buffer.alloc(Math.min(chunkSize, maxBytes - totalRead));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, totalRead);
+            if (bytesRead === 0)
+                break;
+            const chunk = buffer.subarray(0, bytesRead);
+            chunks.push(chunk);
+            totalRead += bytesRead;
+            newlineFound = chunk.includes(0x0a);
+        }
+        const firstLine = Buffer.concat(chunks).toString('utf8').split('\n', 1)[0]?.trim();
+        return { line: firstLine || null, complete: newlineFound || totalRead >= maxBytes };
+    }
+    catch {
+        return { line: null, complete: false };
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+export function parseSessionMetaLine(line) {
+    if (!line)
+        return null;
+    try {
+        const parsed = JSON.parse(line);
+        return parsed.type === 'session_meta' ? parsed.payload : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the CWD from a rollout file's session_meta. Cached per path, bounded
+ * so a long-lived host watching a large history cannot grow it without limit
+ * (insertion order doubles as an eviction order).
+ */
+const CWD_CACHE_LIMIT = 5000;
+const cwdCache = new Map();
+function rememberCwd(rolloutPath, cwd) {
+    if (!cwdCache.has(rolloutPath) && cwdCache.size >= CWD_CACHE_LIMIT) {
+        const oldest = cwdCache.keys().next().value;
+        if (oldest !== undefined)
+            cwdCache.delete(oldest);
+    }
+    cwdCache.set(rolloutPath, cwd);
+}
+export function readSessionCwd(rolloutPath) {
+    const cached = cwdCache.get(rolloutPath);
+    if (cached !== undefined)
+        return cached;
+    const meta = readSessionMeta(rolloutPath);
+    const cwd = meta?.cwd || null;
+    rememberCwd(rolloutPath, cwd);
+    return cwd;
+}
+/** Async twin of readSessionCwd, sharing its cache so repeat listings do no content reads. */
+export async function readSessionCwdAsync(rolloutPath) {
+    const cached = cwdCache.get(rolloutPath);
+    if (cached !== undefined)
+        return cached;
+    const { line, complete } = await readFirstLineAsync(rolloutPath);
+    const cwd = parseSessionMetaLine(line)?.cwd || null;
+    // A rollout observed before its session_meta line is flushed has no cwd
+    // yet; caching that null would hide the session from its workspace until
+    // the entry aged out, so only conclusive answers are remembered.
+    if (cwd !== null || complete)
+        rememberCwd(rolloutPath, cwd);
+    return cwd;
+}
+/** Built-in enumerators report explicit zeros rather than leaving a counter unset. */
+export function initializeCounters(stats) {
+    if (!stats)
+        return;
+    stats.directoriesListed ??= 0;
+    stats.directoriesStatted ??= 0;
+    stats.filesStatted ??= 0;
+}
+/** Check if a session's CWD matches a workspace path. */
+export function cwdMatches(sessionCwd, workspacePath) {
+    const normalizedSession = normalizePath(sessionCwd);
+    const normalizedWorkspace = normalizePath(workspacePath);
+    return (normalizedSession === normalizedWorkspace ||
+        normalizedWorkspace.startsWith(normalizedSession + path.sep) ||
+        normalizedSession.startsWith(normalizedWorkspace + path.sep));
+}
+/** Normalize a path using realpathSync. */
+export function normalizePath(input) {
+    try {
+        return fs.realpathSync(input);
+    }
+    catch {
+        return path.resolve(input);
+    }
+}
+/**
+ * List rollout files across the monitored Codex homes, newest first. With
+ * `workspacePath`, keeps rollouts whose session_meta cwd equals, contains, or
+ * sits inside it.
+ */
+export async function listCodexSessionFilesAsync(workspacePath, options = {}, cache = new DirectoryListingCache()) {
+    const results = [];
+    initializeCounters(options.stats);
+    // One capped walk across the homes (deduplicated, newest first) through
+    // the directory cache. With a workspace filter the limit applies after
+    // filtering, so the walk itself is bounded only by its file cap.
+    const files = await walkRolloutFilesAsync(getSessionsDirs(), {
+        limit: workspacePath ? undefined : options.limit,
+        since: options.since,
+        cache,
+        revalidateRecent: options.revalidateRecent,
+        stats: options.stats,
+    });
+    for (const file of files) {
+        if (options.limit !== undefined && results.length >= options.limit)
+            break;
+        const info = { ...file };
+        if (workspacePath) {
+            const cwd = await readSessionCwdAsync(file.path);
+            if (!cwd || !cwdMatches(cwd, workspacePath))
+                continue;
+            info.workspacePath = cwd;
+        }
+        results.push(info);
+    }
+    return results;
+}

package/dist/esm/providers/detect.js

@@ -0,0 +1,185 @@
+/**
+ * Filesystem-based provider auto-detection.
+ * Ported from sidekick-vscode/src/services/providers/ProviderDetector.ts
+ * without VS Code dependency (no vscode.workspace.getConfiguration).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCodexMonitoringHomes } from '../codexPaths';
+import { getOpenCodeDataDir } from './openCode';
+import { getClaudeProjectsDir } from '../claudePaths';
+function getCodexHomes() {
+    return getCodexMonitoringHomes();
+}
+function hasCodexStateDb(codexHome) {
+    try {
+        return fs.readdirSync(codexHome).some((entry) => /^state(?:_\d+)?\.sqlite$/.test(entry));
+    }
+    catch {
+        return false;
+    }
+}
+function getCodexStateDbMtime(codexHome) {
+    try {
+        let latest = 0;
+        for (const entry of fs.readdirSync(codexHome)) {
+            if (!/^state(?:_\d+)?\.sqlite$/.test(entry))
+                continue;
+            try {
+                const mtime = fs.statSync(path.join(codexHome, entry)).mtime.getTime();
+                if (mtime > latest)
+                    latest = mtime;
+            }
+            catch {
+                // Skip inaccessible files.
+            }
+        }
+        return latest;
+    }
+    catch {
+        return 0;
+    }
+}
+function getMostRecentMtime(dir) {
+    try {
+        if (!fs.existsSync(dir))
+            return 0;
+        let latest = 0;
+        const entries = fs.readdirSync(dir);
+        for (const entry of entries) {
+            try {
+                const stats = fs.statSync(path.join(dir, entry));
+                if (stats.mtime.getTime() > latest) {
+                    latest = stats.mtime.getTime();
+                }
+            }
+            catch {
+                /* skip */
+            }
+        }
+        return latest;
+    }
+    catch {
+        return 0;
+    }
+}
+function getMostRecentFileMtime(dir, isCandidate, depth) {
+    if (depth < 0)
+        return 0;
+    let latest = 0;
+    try {
+        for (const entry of fs.readdirSync(dir)) {
+            const filePath = path.join(dir, entry);
+            try {
+                const stats = fs.statSync(filePath);
+                if (stats.isDirectory?.()) {
+                    latest = Math.max(latest, getMostRecentFileMtime(filePath, isCandidate, depth - 1));
+                }
+                else if (isCandidate(filePath)) {
+                    latest = Math.max(latest, stats.mtime.getTime());
+                }
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    catch {
+        return 0;
+    }
+    return latest;
+}
+function getClaudeActivityMtime(claudeBase) {
+    return getMostRecentFileMtime(claudeBase, (filePath) => filePath.endsWith('.jsonl'), 2);
+}
+function getOpenCodeActivityMtime() {
+    const dataDir = getOpenCodeDataDir();
+    const dbPath = path.join(dataDir, 'opencode.db');
+    try {
+        const dbMtime = fs.statSync(dbPath).mtime.getTime();
+        if (dbMtime > 0)
+            return dbMtime;
+    }
+    catch {
+        /* no DB */
+    }
+    const storageDir = path.join(dataDir, 'storage');
+    const sessionMtime = getMostRecentMtime(path.join(storageDir, 'session'));
+    const messageMtime = getMostRecentMtime(path.join(storageDir, 'message'));
+    const partMtime = getMostRecentMtime(path.join(storageDir, 'part'));
+    return Math.max(sessionMtime, messageMtime, partMtime);
+}
+function getCodexActivityMtime() {
+    let latest = 0;
+    for (const codexHome of getCodexHomes()) {
+        const dbMtime = getCodexStateDbMtime(codexHome);
+        if (dbMtime > latest)
+            latest = dbMtime;
+        const sessionsMtime = getMostRecentFileMtime(path.join(codexHome, 'sessions'), (filePath) => path.basename(filePath).startsWith('rollout-') && filePath.endsWith('.jsonl'), 4);
+        if (sessionsMtime > latest)
+            latest = sessionsMtime;
+    }
+    return latest;
+}
+function getProviderPaths() {
+    const claudeBase = getClaudeProjectsDir();
+    const openCodeDataDir = getOpenCodeDataDir();
+    const codexHomes = getCodexHomes();
+    return {
+        claudeBase,
+        openCodeDbPath: path.join(openCodeDataDir, 'opencode.db'),
+        openCodeStorageDir: path.join(openCodeDataDir, 'storage'),
+        codexHomes,
+    };
+}
+/** Ranked detection results are reused within a process for this long. */
+const DETECTION_CACHE_TTL_MS = 5_000;
+let detectionCache = null;
+/** Forget the memoised ranking. Test-only. */
+export function _resetProviderDetectionCache() {
+    detectionCache = null;
+}
+/**
+ * Providers with data on disk, most recently active first.
+ *
+ * Detection walks every provider's session corpus (a recursive stat over
+ * `~/.claude/projects`, every Codex home, and the OpenCode data dir), so the
+ * ranking is memoised briefly: the CLI resolves the provider several times per
+ * command and the extension asks again on every settings-driven re-detect.
+ */
+function rankDetectedProviders(now = Date.now()) {
+    if (detectionCache && now - detectionCache.at < DETECTION_CACHE_TTL_MS) {
+        return detectionCache.ranked;
+    }
+    const { claudeBase, openCodeDbPath, openCodeStorageDir, codexHomes } = getProviderPaths();
+    const hasClaude = fs.existsSync(claudeBase);
+    const hasOpenCode = fs.existsSync(openCodeStorageDir) || fs.existsSync(openCodeDbPath);
+    const hasCodex = codexHomes.some((codexHome) => fs.existsSync(path.join(codexHome, 'sessions')) || hasCodexStateDb(codexHome));
+    const available = [];
+    if (hasClaude)
+        available.push({ id: 'claude-code', mtime: getClaudeActivityMtime(claudeBase) });
+    if (hasOpenCode)
+        available.push({ id: 'opencode', mtime: getOpenCodeActivityMtime() });
+    if (hasCodex)
+        available.push({ id: 'codex', mtime: getCodexActivityMtime() });
+    available.sort((a, b) => b.mtime - a.mtime);
+    const ranked = available.map((a) => a.id);
+    detectionCache = { at: now, ranked };
+    return ranked;
+}
+/**
+ * Returns all provider IDs whose data directories exist on the filesystem.
+ * Ordered by most-recent activity first.
+ */
+export function getAllDetectedProviders() {
+    return [...rankDetectedProviders()];
+}
+/**
+ * Detects the most appropriate provider based on filesystem presence and recency.
+ * Pass an explicit provider ID to override auto-detection.
+ */
+export function detectProvider(override) {
+    if (override && override !== 'auto')
+        return override;
+    return rankDetectedProviders()[0] ?? 'claude-code';
+}