@xenosystem/agent-interface-host 0.1.3

package/dist/acp/AcpProviderCatalogService.js

@@ -0,0 +1,707 @@
+import { execFile } from 'child_process';
+import { createHash } from 'crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'path';
+import extractZip from 'extract-zip';
+import { x as extractTar } from 'tar';
+import { canAutomaticallyCertifyProvider, fallbackProviderRegistry, fetchOfficialProviderRegistry, installKimiNativeUpdate as installXenoKimiNativeUpdate, nativeLauncherFor, normalizeProviderHttpsUrl, normalizeProviderRegistry, providerConfigId, providerConfigIds, providerDistributionKind, providerPlatformTarget, resolveProviderLifecycle, resolveProviderBinaryInstallPlan, resolveProviderUpdatePlan, selectProviderExecutableCandidate, } from '@xenosystem/acp-provider-manager';
+import { AcpAgentRegistryService } from './AcpAgentRegistryService.js';
+import { runAcpExternalCertification, } from './AcpExternalCertificationHarness.js';
+import { getAcpProviderVersionReadinessAsync } from './AcpProviderVersionReadiness.js';
+import { redactAcpText } from './acpRedaction.js';
+const CATALOG_CACHE_VERSION = 1;
+const CATALOG_PREFERENCES_VERSION = 1;
+const CATALOG_CACHE_MAX_AGE_MS = 24 * 60 * 60_000;
+export class AcpProviderCatalogService {
+    registryService;
+    rootDir;
+    cachePath;
+    preferencesPath;
+    fetchRegistry;
+    fetchArchive;
+    executableFinder;
+    now;
+    certify;
+    checkVersionReadiness;
+    runProviderUpdate;
+    certificationInFlight = new Map();
+    updatesInFlight = new Map();
+    versionReadiness = new Map();
+    syncInFlight;
+    syncGeneration = 0;
+    discoveredLaunchers = new Map();
+    constructor(options = {}) {
+        this.registryService = options.registryService || new AcpAgentRegistryService({ rootDir: options.rootDir });
+        this.rootDir = options.rootDir || this.registryService.rootDir;
+        this.cachePath = join(this.rootDir, 'acp-provider-catalog-cache.json');
+        this.preferencesPath = join(this.rootDir, 'acp-provider-preferences.json');
+        this.fetchRegistry = options.fetchRegistry || (() => fetchOfficialProviderRegistry((url, init) => fetch(url, init)));
+        this.fetchArchive = options.fetchArchive || fetchProviderArchive;
+        this.executableFinder = options.findExecutableAsync
+            || (options.findExecutable ? async (name) => options.findExecutable(name) : findExecutable);
+        this.now = options.now || (() => new Date());
+        this.certify = options.certify || runAcpExternalCertification;
+        this.checkVersionReadiness = options.checkVersionReadiness || getAcpProviderVersionReadinessAsync;
+        this.runProviderUpdate = options.runProviderUpdate || runProviderUpdateCommand;
+    }
+    async listCatalog(options = {}) {
+        const loaded = await this.loadRegistry(!!options.refresh);
+        return this.buildSnapshot(loaded);
+    }
+    async syncCatalog(options = {}) {
+        if (this.syncInFlight)
+            return this.syncInFlight;
+        const generation = ++this.syncGeneration;
+        const operation = this.performCatalogSync(options, generation);
+        this.syncInFlight = operation;
+        try {
+            return await operation;
+        }
+        finally {
+            if (this.syncInFlight === operation)
+                this.syncInFlight = undefined;
+        }
+    }
+    async performCatalogSync(options, generation) {
+        const loaded = await this.loadRegistry(!!options.refresh);
+        const preferences = this.loadPreferences();
+        const discovered = new Map();
+        if (preferences.acpEnabled) {
+            for (const manifest of loaded.registry.agents) {
+                if (generation !== this.syncGeneration)
+                    return this.buildSnapshot(loaded);
+                let configured = this.findConfiguredAgent(manifest);
+                if (configured) {
+                    if (nativeLauncherFor(manifest.id)) {
+                        const launcher = await this.resolveLauncher(manifest, true);
+                        if (launcher?.installed && !sameCommandPath(launcher.command, configured.command)) {
+                            configured = this.saveResolvedLauncher(manifest, configured, launcher);
+                        }
+                    }
+                    const readiness = await this.refreshVersionReadiness(configured);
+                    if (options.autoCertify !== false
+                        && configured.enabled
+                        && !configured.certification
+                        && canAutomaticallyCertifyProvider(readiness)) {
+                        this.startProviderCertification(configured);
+                    }
+                    continue;
+                }
+                if (!nativeLauncherFor(manifest.id))
+                    continue;
+                const launcher = await this.resolveLauncher(manifest, true);
+                if (generation !== this.syncGeneration)
+                    return this.buildSnapshot(loaded);
+                if (launcher?.installed)
+                    discovered.set(manifest.id, launcher);
+            }
+        }
+        if (generation === this.syncGeneration)
+            this.discoveredLaunchers = discovered;
+        return this.buildSnapshot(loaded);
+    }
+    async setProviderEnabled(providerId, enabled) {
+        const loaded = await this.loadRegistry(false);
+        const manifest = loaded.registry.agents.find((entry) => entry.id === providerId);
+        if (!manifest)
+            throw new Error('ACP catalog provider was not found.');
+        let agent = this.findConfiguredAgent(manifest);
+        if (enabled && !agent) {
+            const launcher = this.discoveredLaunchers.get(manifest.id)
+                || await this.resolveLauncher(manifest, false)
+                || await this.installBinaryLauncher(manifest);
+            if (!launcher) {
+                throw new Error(`${manifest.name} is not installed and has no automatic setup available on this computer.`);
+            }
+            const saved = this.registryService.saveAgent({
+                id: providerConfigId(manifest.id),
+                name: manifest.name,
+                command: launcher.command,
+                args: launcher.args,
+                cwd: this.rootDir,
+                enabled: true,
+                trustLevel: 'restricted',
+            }, { includeRuntimeStatus: false });
+            if (!saved.success)
+                throw new Error(saved.error || `Could not configure ${manifest.name}.`);
+            agent = this.registryService.getAgentInternal(saved.result?.id || providerConfigId(manifest.id));
+        }
+        else if (agent) {
+            const updated = this.registryService.setAgentsEnabled({ [agent.id]: enabled });
+            if (!updated.success)
+                throw new Error(updated.error || `Could not ${enabled ? 'enable' : 'disable'} ${manifest.name}.`);
+            agent = this.registryService.getAgentInternal(agent.id);
+            if (enabled && agent && nativeLauncherFor(manifest.id)) {
+                const launcher = await this.resolveLauncher(manifest, true);
+                if (launcher?.installed && !sameCommandPath(launcher.command, agent.command)) {
+                    agent = this.saveResolvedLauncher(manifest, agent, launcher);
+                }
+            }
+        }
+        const readiness = agent ? await this.refreshVersionReadiness(agent) : undefined;
+        const preferences = this.loadPreferences();
+        preferences.acpEnabled = true;
+        preferences.enabledAgentIds = updateStringSet(preferences.enabledAgentIds, agent?.id, enabled);
+        if (!enabled && preferences.preferredAgentId === agent?.id)
+            preferences.preferredAgentId = undefined;
+        this.ensurePreferredAgent(preferences);
+        const errors = [...loaded.errors];
+        if (enabled && agent) {
+            if (canAutomaticallyCertifyProvider(readiness) && agent.certification?.status !== 'certified') {
+                this.startProviderCertification(agent);
+            }
+        }
+        return this.buildSnapshot({ ...loaded, errors });
+    }
+    async updateProvider(providerId) {
+        const inFlight = this.updatesInFlight.get(providerId);
+        if (inFlight)
+            return inFlight;
+        const operation = this.performProviderUpdate(providerId);
+        this.updatesInFlight.set(providerId, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            if (this.updatesInFlight.get(providerId) === operation)
+                this.updatesInFlight.delete(providerId);
+        }
+    }
+    async performProviderUpdate(providerId) {
+        const loaded = await this.loadRegistry(false);
+        const manifest = loaded.registry.agents.find((entry) => entry.id === providerId);
+        if (!manifest)
+            throw new Error('ACP catalog provider was not found.');
+        const agent = this.findConfiguredAgent(manifest);
+        if (!agent)
+            throw new Error(`${manifest.name} must be configured before it can be updated.`);
+        if (!agent.enabled)
+            throw new Error(`${manifest.name} must be enabled before it can be updated.`);
+        const readiness = await this.refreshVersionReadiness(agent);
+        if (readiness?.status !== 'outdated') {
+            throw new Error(readiness?.ok
+                ? `${manifest.name} is already up to date.`
+                : readiness?.message || `${manifest.name} does not expose a supported automatic updater.`);
+        }
+        const updateCommand = providerUpdateCommand(manifest, agent);
+        if (!updateCommand)
+            throw new Error(`${manifest.name} does not expose a supported automatic updater.`);
+        const cleared = this.registryService.clearAgentCertification(agent.id, { includeRuntimeStatus: false });
+        if (!cleared.success)
+            throw new Error(cleared.error || `Could not prepare ${manifest.name} for update.`);
+        await this.runProviderUpdate(updateCommand);
+        const updatedAgent = this.registryService.getAgentInternal(agent.id);
+        if (!updatedAgent)
+            throw new Error(`${manifest.name} configuration disappeared during update.`);
+        const updatedReadiness = await this.refreshVersionReadiness(updatedAgent);
+        if (!updatedReadiness?.ok) {
+            throw new Error(updatedReadiness?.updateHint || updatedReadiness?.message || `${manifest.name} did not report a supported version after updating.`);
+        }
+        this.startProviderCertification(updatedAgent);
+        return this.buildSnapshot(loaded);
+    }
+    async setCatalogEnabled(enabled) {
+        this.syncGeneration += 1;
+        const loaded = await this.loadRegistry(false);
+        const preferences = this.loadPreferences();
+        const configured = this.registryService.loadRegistry().registry.agents;
+        if (!enabled) {
+            preferences.enabledAgentIds = configured.filter((agent) => agent.enabled).map((agent) => agent.id);
+            const updates = Object.fromEntries(configured.filter((agent) => agent.enabled).map((agent) => [agent.id, false]));
+            const updated = this.registryService.setAgentsEnabled(updates);
+            if (!updated.success)
+                throw new Error(updated.error || 'Could not disable ACP providers.');
+        }
+        else {
+            const configuredIds = new Set(configured.map((agent) => agent.id));
+            const updates = Object.fromEntries(preferences.enabledAgentIds.filter((id) => configuredIds.has(id)).map((id) => [id, true]));
+            const updated = this.registryService.setAgentsEnabled(updates);
+            if (!updated.success)
+                throw new Error(updated.error || 'Could not enable ACP providers.');
+        }
+        preferences.acpEnabled = enabled;
+        this.writePreferences(preferences);
+        return this.buildSnapshot(loaded);
+    }
+    async setPreferredProvider(providerId) {
+        const loaded = await this.loadRegistry(false);
+        const manifest = loaded.registry.agents.find((entry) => entry.id === providerId);
+        if (!manifest)
+            throw new Error('ACP catalog provider was not found.');
+        const agent = this.findConfiguredAgent(manifest);
+        if (!agent?.enabled || agent.certification?.status !== 'certified') {
+            throw new Error('Enable this provider and let automatic setup finish before making it preferred.');
+        }
+        const preferences = this.loadPreferences();
+        preferences.preferredAgentId = agent.id;
+        preferences.acpEnabled = true;
+        preferences.enabledAgentIds = updateStringSet(preferences.enabledAgentIds, agent.id, true);
+        this.writePreferences(preferences);
+        return this.buildSnapshot(loaded);
+    }
+    async certifyAgent(agent) {
+        const result = await this.certify(agent, {
+            registryRoot: this.registryService.rootDir,
+            requestTimeoutMs: 120_000,
+        });
+        return result.status === 'PASSED' || result.status === 'FALLBACK_FIXTURE_ONLY'
+            ? undefined
+            : result.error || result.certification.notes || 'Automatic ACP setup did not pass.';
+    }
+    startProviderCertification(agent) {
+        if (this.certificationInFlight.has(agent.id))
+            return;
+        const operation = (async () => {
+            try {
+                const error = await this.certifyAgent(agent);
+                if (error && !this.registryService.getAgentInternal(agent.id)?.certification) {
+                    this.registryService.setAgentCertification(agent.id, {
+                        status: 'failed',
+                        certifiedAt: this.now().toISOString(),
+                        certifiedBy: 'harness',
+                        notes: redactAcpText(error, 500),
+                    }, { includeRuntimeStatus: false });
+                }
+            }
+            catch (error) {
+                this.registryService.setAgentCertification(agent.id, {
+                    status: 'failed',
+                    certifiedAt: this.now().toISOString(),
+                    certifiedBy: 'harness',
+                    notes: redactAcpText(error instanceof Error ? error.message : 'Automatic ACP setup failed.', 500),
+                }, { includeRuntimeStatus: false });
+            }
+        })().finally(() => {
+            this.certificationInFlight.delete(agent.id);
+        });
+        this.certificationInFlight.set(agent.id, operation);
+    }
+    async loadRegistry(refresh) {
+        const cached = this.readCache();
+        const cachedAge = cached ? this.now().getTime() - Date.parse(cached.fetchedAt) : Number.POSITIVE_INFINITY;
+        if (!refresh && cached && cachedAge >= 0 && cachedAge < CATALOG_CACHE_MAX_AGE_MS) {
+            return { registry: cached.registry, source: 'cache', refreshedAt: cached.fetchedAt, errors: [] };
+        }
+        try {
+            const registry = normalizeProviderRegistry(await this.fetchRegistry());
+            if (!registry)
+                throw new Error('Official ACP Registry returned invalid metadata.');
+            const fetchedAt = this.now().toISOString();
+            this.writeCache({ version: CATALOG_CACHE_VERSION, fetchedAt, registry });
+            return { registry, source: 'network', refreshedAt: fetchedAt, errors: [] };
+        }
+        catch (error) {
+            const safeError = redactAcpText(error instanceof Error ? error.message : 'Official ACP Registry is unavailable.', 500);
+            if (cached) {
+                return { registry: cached.registry, source: 'cache', refreshedAt: cached.fetchedAt, errors: [safeError] };
+            }
+            return {
+                registry: fallbackProviderRegistry(),
+                source: 'fallback',
+                refreshedAt: this.now().toISOString(),
+                errors: [safeError],
+            };
+        }
+    }
+    buildSnapshot(loaded) {
+        const preferences = this.loadPreferences();
+        const configuredAgents = this.registryService.loadRegistry().registry.agents;
+        const configuredById = new Map(configuredAgents.map((agent) => [agent.id, agent]));
+        const entries = loaded.registry.agents.map((manifest) => this.toCatalogEntry(manifest, preferences, configuredById));
+        const representedIds = new Set(entries.flatMap((entry) => [entry.agentConfigId, entry.id].filter((id) => !!id)));
+        for (const agent of configuredAgents) {
+            if (representedIds.has(agent.id))
+                continue;
+            entries.push(customCatalogEntry(agent, preferences.preferredAgentId === agent.id));
+        }
+        return {
+            acpEnabled: preferences.acpEnabled,
+            preferredAgentId: preferences.preferredAgentId,
+            source: loaded.source,
+            refreshedAt: loaded.refreshedAt,
+            entries: entries.sort(catalogSort),
+            syncErrors: loaded.errors.map((error) => redactAcpText(error, 500)),
+        };
+    }
+    toCatalogEntry(manifest, preferences, configuredById) {
+        const agent = this.findConfiguredAgent(manifest, configuredById);
+        const discoveredLauncher = this.discoveredLaunchers.get(manifest.id);
+        const readiness = agent ? this.versionReadiness.get(agent.id) : undefined;
+        const lifecycle = resolveProviderLifecycle({
+            manifest,
+            configured: !!agent,
+            enabled: preferences.acpEnabled && agent?.enabled === true,
+            setupInProgress: !!agent && this.certificationInFlight.has(agent.id),
+            ...(agent?.certification?.status ? { certificationStatus: agent.certification.status } : {}),
+            ...(agent?.certification?.notes ? { certificationMessage: agent.certification.notes } : {}),
+            ...(readiness ? {
+                readiness: {
+                    ok: readiness.ok,
+                    status: readiness.status,
+                    message: readiness.message,
+                    ...(readiness.updateHint ? { updateHint: readiness.updateHint } : {}),
+                },
+            } : {}),
+        });
+        return {
+            id: manifest.id,
+            name: manifest.name,
+            description: manifest.description,
+            version: manifest.version,
+            iconUrl: normalizeProviderHttpsUrl(manifest.icon),
+            website: normalizeProviderHttpsUrl(manifest.website),
+            repository: normalizeProviderHttpsUrl(manifest.repository),
+            authors: manifest.authors,
+            license: manifest.license,
+            distributionKind: providerDistributionKind(manifest),
+            installed: !!agent || discoveredLauncher?.installed === true,
+            configured: !!agent,
+            enabled: preferences.acpEnabled && agent?.enabled === true,
+            preferred: preferences.preferredAgentId === agent?.id,
+            canAutoSetup: lifecycle.canAutoSetup,
+            primaryAction: lifecycle.primaryAction,
+            availableActions: lifecycle.availableActions,
+            agentConfigId: agent?.id,
+            status: lifecycle.status,
+            statusMessage: lifecycle.statusMessage,
+        };
+    }
+    findConfiguredAgent(manifest, configuredById) {
+        const ids = providerConfigIds(manifest.id);
+        for (const id of ids) {
+            const agent = configuredById?.get(id) || this.registryService.getAgentInternal(id);
+            if (agent)
+                return agent;
+        }
+        return undefined;
+    }
+    async refreshVersionReadiness(agent) {
+        const readiness = await this.checkVersionReadiness(agent);
+        if (readiness)
+            this.versionReadiness.set(agent.id, readiness);
+        else
+            this.versionReadiness.delete(agent.id);
+        return readiness;
+    }
+    async resolveLauncher(manifest, installedOnly) {
+        const native = nativeLauncherFor(manifest.id);
+        if (native) {
+            const command = await this.executableFinder(native.executable);
+            if (command)
+                return { command, args: native.args, installed: true, distributionKind: providerDistributionKind(manifest) };
+        }
+        const target = manifest.distribution.binary?.[providerPlatformTarget()];
+        if (target) {
+            const executableName = basename(target.cmd).replace(/^\.\\|^\.\//, '');
+            const command = await this.executableFinder(executableName.replace(/\.exe$/i, ''))
+                || await this.executableFinder(executableName);
+            if (command)
+                return { command, args: target.args || [], installed: true, distributionKind: 'binary' };
+        }
+        if (installedOnly)
+            return undefined;
+        if (manifest.distribution.npx) {
+            const npx = await resolveNpxLauncher(this.executableFinder);
+            if (npx) {
+                return {
+                    command: npx.command,
+                    args: [...npx.args, '--yes', manifest.distribution.npx.package, ...(manifest.distribution.npx.args || [])],
+                    installed: false,
+                    distributionKind: 'npx',
+                };
+            }
+        }
+        if (manifest.distribution.uvx) {
+            const uvx = await this.executableFinder('uvx');
+            if (uvx) {
+                return {
+                    command: uvx,
+                    args: [manifest.distribution.uvx.package, ...(manifest.distribution.uvx.args || [])],
+                    installed: false,
+                    distributionKind: 'uvx',
+                };
+            }
+        }
+        return undefined;
+    }
+    async installBinaryLauncher(manifest) {
+        const plan = resolveProviderBinaryInstallPlan(manifest);
+        if (!plan)
+            return undefined;
+        const managedRoot = resolve(this.rootDir, 'acp-providers');
+        const installDir = resolve(managedRoot, manifest.id, manifest.version);
+        const relativeCommand = plan.command.replace(/^\.([/\\])/, '');
+        const command = resolve(installDir, relativeCommand);
+        assertWithin(managedRoot, command);
+        if (existsSync(command)) {
+            return { command, args: plan.args, installed: true, distributionKind: 'binary' };
+        }
+        const stagingDir = resolve(managedRoot, '.staging', `${manifest.id}-${process.pid}-${Date.now()}`);
+        const archivePath = resolve(managedRoot, '.downloads', `${manifest.id}-${process.pid}-${Date.now()}${archiveExtension(plan.archiveUrl)}`);
+        assertWithin(managedRoot, stagingDir);
+        assertWithin(managedRoot, archivePath);
+        mkdirSync(dirname(archivePath), { recursive: true });
+        mkdirSync(stagingDir, { recursive: true });
+        try {
+            const archive = await this.fetchArchive(plan.archiveUrl);
+            const actualHash = createHash('sha256').update(archive).digest('hex');
+            if (actualHash !== plan.sha256)
+                throw new Error('Downloaded provider failed SHA-256 verification.');
+            writeFileSync(archivePath, archive);
+            if (/\.zip$/i.test(archivePath)) {
+                await extractZip(archivePath, { dir: stagingDir });
+            }
+            else if (/\.(?:tar\.gz|tgz)$/i.test(archivePath)) {
+                await extractTar({
+                    file: archivePath,
+                    cwd: stagingDir,
+                    strict: true,
+                    preservePaths: false,
+                    filter: (entryPath, entry) => {
+                        if ('type' in entry && (entry.type === 'SymbolicLink' || entry.type === 'Link'))
+                            return false;
+                        try {
+                            assertWithin(stagingDir, resolve(stagingDir, entryPath));
+                            return true;
+                        }
+                        catch {
+                            return false;
+                        }
+                    },
+                });
+            }
+            else {
+                throw new Error('Provider archive format is not supported on this platform.');
+            }
+            assertNoSymlinks(stagingDir);
+            const stagedCommand = resolve(stagingDir, relativeCommand);
+            assertWithin(stagingDir, stagedCommand);
+            if (!existsSync(stagedCommand) || !lstatSync(stagedCommand).isFile()) {
+                throw new Error('Provider archive did not contain its declared executable.');
+            }
+            mkdirSync(dirname(installDir), { recursive: true });
+            if (existsSync(installDir))
+                removeManagedDirectory(managedRoot, installDir);
+            renameSync(stagingDir, installDir);
+            if (process.platform !== 'win32')
+                chmodSync(command, 0o755);
+            return { command, args: plan.args, installed: true, distributionKind: 'binary' };
+        }
+        finally {
+            if (existsSync(archivePath))
+                unlinkSync(archivePath);
+            if (existsSync(stagingDir))
+                removeManagedDirectory(managedRoot, stagingDir);
+        }
+    }
+    saveResolvedLauncher(manifest, agent, launcher) {
+        const saved = this.registryService.saveAgent({
+            id: agent.id,
+            name: manifest.name,
+            command: launcher.command,
+            args: launcher.args,
+            cwd: this.rootDir,
+            enabled: agent.enabled,
+            trustLevel: agent.trustLevel,
+        }, { includeRuntimeStatus: false });
+        if (!saved.success)
+            throw new Error(saved.error || `Could not update ${manifest.name}.`);
+        const updated = this.registryService.getAgentInternal(agent.id);
+        if (!updated)
+            throw new Error(`Could not reload ${manifest.name} after updating its launcher.`);
+        return updated;
+    }
+    ensurePreferredAgent(preferences) {
+        const current = preferences.preferredAgentId
+            ? this.registryService.getAgentInternal(preferences.preferredAgentId)
+            : undefined;
+        if (!current?.enabled || current.certification?.status !== 'certified') {
+            preferences.preferredAgentId = this.registryService.loadRegistry().registry.agents.find((agent) => agent.enabled && agent.certification?.status === 'certified')?.id;
+        }
+        this.writePreferences(preferences);
+    }
+    loadPreferences() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.preferencesPath, 'utf-8'));
+            if (isRecord(parsed) && parsed.version === CATALOG_PREFERENCES_VERSION) {
+                return {
+                    version: CATALOG_PREFERENCES_VERSION,
+                    acpEnabled: parsed.acpEnabled !== false,
+                    preferredAgentId: cleanString(parsed.preferredAgentId),
+                    enabledAgentIds: Array.isArray(parsed.enabledAgentIds)
+                        ? parsed.enabledAgentIds.filter((id) => typeof id === 'string' && !!id.trim())
+                        : [],
+                };
+            }
+        }
+        catch {
+            // Missing or corrupt preferences fall back to the durable agent registry state.
+        }
+        return {
+            version: CATALOG_PREFERENCES_VERSION,
+            acpEnabled: true,
+            enabledAgentIds: this.registryService.loadRegistry().registry.agents.filter((agent) => agent.enabled).map((agent) => agent.id),
+        };
+    }
+    writePreferences(preferences) {
+        writeJsonAtomic(this.preferencesPath, preferences);
+    }
+    readCache() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.cachePath, 'utf-8'));
+            if (!isRecord(parsed) || parsed.version !== CATALOG_CACHE_VERSION)
+                return undefined;
+            const registry = normalizeProviderRegistry(parsed.registry);
+            const fetchedAt = cleanString(parsed.fetchedAt);
+            if (!registry || !fetchedAt || !Number.isFinite(Date.parse(fetchedAt)))
+                return undefined;
+            return { version: CATALOG_CACHE_VERSION, fetchedAt, registry };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    writeCache(cache) {
+        writeJsonAtomic(this.cachePath, cache);
+    }
+}
+function sameCommandPath(left, right) {
+    const normalizedLeft = resolve(left);
+    const normalizedRight = resolve(right);
+    return process.platform === 'win32'
+        ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+        : normalizedLeft === normalizedRight;
+}
+function providerUpdateCommand(manifest, agent) {
+    return resolveProviderUpdatePlan(manifest, {
+        command: agent.command,
+        args: agent.args,
+        ...(agent.cwd ? { cwd: agent.cwd } : {}),
+    });
+}
+async function runProviderUpdateCommand(input) {
+    return installXenoKimiNativeUpdate(input, {
+        fetchImpl: (url, init) => fetch(url, init),
+    });
+}
+function customCatalogEntry(agent, preferred) {
+    const ready = agent.enabled && (agent.certification?.status === 'certified' || agent.certification?.status === 'fixture_only');
+    return {
+        id: agent.id,
+        name: agent.name,
+        description: 'Custom ACP agent configured in XENO Hub.',
+        authors: [],
+        distributionKind: 'custom',
+        installed: true,
+        configured: true,
+        enabled: agent.enabled,
+        preferred,
+        canAutoSetup: true,
+        availableActions: agent.enabled
+            ? [{ id: 'disable', label: 'Disable', mode: 'automatic' }, { id: 'configure', label: 'Configure', mode: 'automatic' }]
+            : [{ id: 'enable', label: 'Enable', mode: 'automatic' }],
+        primaryAction: agent.enabled ? undefined : { id: 'enable', label: 'Enable', mode: 'automatic' },
+        agentConfigId: agent.id,
+        status: ready ? 'ready' : agent.enabled ? 'needs_attention' : 'disabled',
+        statusMessage: ready ? 'Enabled and ready.' : agent.certification?.notes || (agent.enabled ? 'Automatic setup needs attention.' : 'Disabled.'),
+    };
+}
+function catalogSort(left, right) {
+    const rank = (entry) => entry.preferred ? 0 : entry.status === 'ready' ? 1 : entry.enabled ? 2 : 3;
+    return rank(left) - rank(right) || left.name.localeCompare(right.name);
+}
+function archiveExtension(url) {
+    const pathname = new URL(url).pathname.toLowerCase();
+    if (pathname.endsWith('.tar.gz'))
+        return '.tar.gz';
+    if (pathname.endsWith('.tgz'))
+        return '.tgz';
+    if (pathname.endsWith('.zip'))
+        return '.zip';
+    return '.archive';
+}
+function assertWithin(root, candidate) {
+    const rel = relative(resolve(root), resolve(candidate));
+    if (!rel || (!rel.startsWith('..') && !isAbsolute(rel)))
+        return;
+    throw new Error('Provider installation path escaped the XENO-managed directory.');
+}
+function removeManagedDirectory(root, target) {
+    assertWithin(root, target);
+    rmSync(target, { recursive: true, force: true });
+}
+function assertNoSymlinks(root) {
+    const pending = [resolve(root)];
+    while (pending.length) {
+        const current = pending.pop();
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const path = resolve(current, entry.name);
+            assertWithin(root, path);
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink())
+                throw new Error('Provider archive contains unsupported symbolic links.');
+            if (stat.isDirectory())
+                pending.push(path);
+        }
+    }
+}
+async function resolveNpxLauncher(finder) {
+    const node = await finder('node');
+    if (!node)
+        return undefined;
+    const candidates = [
+        join(dirname(node), 'node_modules', 'npm', 'bin', 'npx-cli.js'),
+        join(dirname(node), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ];
+    const cli = candidates.find((candidate) => existsSync(candidate));
+    return cli ? { command: node, args: [cli] } : undefined;
+}
+function findExecutable(name) {
+    const lookup = process.platform === 'win32' ? 'where.exe' : 'which';
+    return new Promise((resolveResult) => {
+        execFile(lookup, [name], {
+            encoding: 'utf-8',
+            timeout: 3_000,
+            windowsHide: true,
+        }, (error, stdout) => {
+            if (error)
+                return resolveResult(null);
+            const found = selectProviderExecutableCandidate(stdout.split(/\r?\n/), process.platform);
+            resolveResult(found ? resolve(found) : null);
+        });
+    });
+}
+async function fetchProviderArchive(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    if (!response.ok)
+        throw new Error(`Download failed with status ${response.status}.`);
+    return Buffer.from(await response.arrayBuffer());
+}
+function writeJsonAtomic(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+    try {
+        renameSync(tempPath, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch { /* Preserve the original write failure. */ }
+        throw error;
+    }
+}
+function updateStringSet(values, id, enabled) {
+    const next = new Set(values);
+    if (id)
+        enabled ? next.add(id) : next.delete(id);
+    return [...next];
+}
+function cleanString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+//# sourceMappingURL=AcpProviderCatalogService.js.map