@borgee/agents-host 0.1.6 → 0.1.8

package/dist/local-config.js

@@ -0,0 +1,772 @@
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { parseDocument, stringify } from 'yaml';
+import { optionalNonEmptyString, optionalStringArray, parseCopilotSessionTtlMinutesValue, requireNonEmptyString, resolveProvider, resolveProviderCommandConfig, } from './config.js';
+const SUPPORTED_CONFIG_EXTENSIONS = new Set(['.json', '.yaml', '.yml']);
+export const DEFAULT_LOCAL_HOST_CONFIG_FILENAME = 'agents-host.yaml';
+export const DEFAULT_LOCAL_AGENTS_DIRNAME = 'agents';
+const DEFAULT_AGENTS_DIR = './agents';
+const MANAGED_GENERATIONS_DIRNAME = '.generations';
+const MANAGED_CURRENT_LINK_NAME = 'current';
+export const MANAGED_WRITE_LOCK_DIRNAME = '.generate-config.lock';
+const MANAGED_READERS_DIRNAME = '.readers';
+const MANAGED_HOLDER_METADATA_FILENAME = '.holder.json';
+const MANAGED_ROOT_MODE = 0o700;
+const MANAGED_CONFIG_MODE = 0o600;
+const MANAGED_WRITE_LOCK_WAIT_MS = 10_000;
+const MANAGED_WRITE_LOCK_RETRY_MS = 50;
+const MANAGED_HOLDER_MAX_AGE_MS = 5 * 60_000;
+const MANAGED_GENERATION_NAME_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const nodeFileSystem = {
+    async readFile(path) {
+        return fs.readFile(path, 'utf8');
+    },
+    async readDir(path) {
+        const entries = await fs.readdir(path, { withFileTypes: true });
+        return entries.map((entry) => ({
+            name: entry.name,
+            isFile: entry.isFile(),
+        }));
+    },
+    async realPath(path) {
+        return fs.realpath(path);
+    },
+    async writeFile(path, content) {
+        await fs.writeFile(path, content, { encoding: 'utf8', mode: MANAGED_CONFIG_MODE });
+    },
+    async mkdir(path, options = {}) {
+        await fs.mkdir(path, options);
+    },
+    async removeFile(path) {
+        await fs.unlink(path);
+    },
+    async removeTree(path) {
+        await fs.rm(path, { recursive: true, force: true });
+    },
+    async rename(from, to) {
+        await fs.rename(from, to);
+    },
+    async symlink(target, path) {
+        await fs.symlink(target, path);
+    },
+    async readLink(path) {
+        return fs.readlink(path);
+    },
+    async lstat(path) {
+        const status = await fs.lstat(path);
+        return {
+            isDirectory: status.isDirectory(),
+            isSymbolicLink: status.isSymbolicLink(),
+            mtimeMs: status.mtimeMs,
+        };
+    },
+    async chmod(path, mode) {
+        await fs.chmod(path, mode);
+    },
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function resolveLocalConfigLayout(rootPath) {
+    const root = resolve(rootPath);
+    return {
+        root,
+        hostConfigPath: resolve(root, DEFAULT_LOCAL_HOST_CONFIG_FILENAME),
+        agentsDir: resolve(root, DEFAULT_LOCAL_AGENTS_DIRNAME),
+    };
+}
+async function loadParsedDocument(fileSystem, filePath, kind) {
+    const raw = await fileSystem.readFile(filePath);
+    const document = parseDocument(raw);
+    if (document.errors.length > 0) {
+        throw new Error(`Invalid ${kind} file ${filePath}: ${document.errors[0]?.message ?? 'parse error'}`);
+    }
+    const parsed = document.toJS();
+    if (!isRecord(parsed)) {
+        throw new Error(`Invalid ${kind} file ${filePath}: expected a top-level object`);
+    }
+    return parsed;
+}
+function parseProviderCommandOverrides(value, sourceLabel) {
+    if (value === undefined || value === null) {
+        return {};
+    }
+    if (!isRecord(value)) {
+        throw new Error(`Invalid provider defaults in ${sourceLabel}: expected an object`);
+    }
+    const overrides = {};
+    const claudeCommand = optionalNonEmptyString(value.claudeCommand, 'claudeCommand', sourceLabel);
+    if (claudeCommand !== undefined) {
+        overrides.claudeCommand = claudeCommand;
+    }
+    const claudeArgs = optionalStringArray(value.claudeArgs, 'claudeArgs', sourceLabel);
+    if (claudeArgs !== undefined) {
+        overrides.claudeArgs = claudeArgs;
+    }
+    const copilotCommand = optionalNonEmptyString(value.copilotCommand, 'copilotCommand', sourceLabel);
+    if (copilotCommand !== undefined) {
+        overrides.copilotCommand = copilotCommand;
+    }
+    const copilotArgs = optionalStringArray(value.copilotArgs, 'copilotArgs', sourceLabel);
+    if (copilotArgs !== undefined) {
+        overrides.copilotArgs = copilotArgs;
+    }
+    if (value.copilotSessionTtlMinutes !== undefined && value.copilotSessionTtlMinutes !== null) {
+        overrides.copilotSessionTtlMinutes = parseCopilotSessionTtlMinutesValue(value.copilotSessionTtlMinutes, sourceLabel);
+    }
+    return overrides;
+}
+function toAgentsDir(hostConfigPath, rawAgentsDir) {
+    const agentsDir = rawAgentsDir ?? DEFAULT_AGENTS_DIR;
+    return isAbsolute(agentsDir) ? agentsDir : resolve(dirname(hostConfigPath), agentsDir);
+}
+function parseHostConfigFile(hostConfigPath, value) {
+    return {
+        borgeeBaseUrl: requireNonEmptyString(value.borgeeBaseUrl, `Invalid host config ${hostConfigPath}: missing required borgeeBaseUrl`),
+        agentsDir: optionalNonEmptyString(value.agentsDir, 'agentsDir', hostConfigPath),
+        defaults: parseProviderCommandOverrides(value.defaults, `host config ${hostConfigPath}`),
+    };
+}
+function toGeneratedAgentConfigFilename(key) {
+    return `${encodeURIComponent(key)}.yaml`;
+}
+function parseGenerateHostConfigFile(sourceLabel, value) {
+    if (value.agentsDir !== undefined) {
+        throw new Error(`Invalid generate-config host spec in ${sourceLabel}: agentsDir is not supported; generate-config always writes the canonical default layout`);
+    }
+    return {
+        borgeeBaseUrl: requireNonEmptyString(value.borgeeBaseUrl, `Invalid generate-config host spec in ${sourceLabel}: missing required borgeeBaseUrl`),
+        defaults: parseProviderCommandOverrides(value.defaults, `generate-config host spec ${sourceLabel}`),
+    };
+}
+function parseAgentConfigFile(agentConfigPath, value) {
+    const enabled = value.enabled;
+    if (enabled !== undefined && typeof enabled !== 'boolean') {
+        throw new Error(`Invalid enabled in ${agentConfigPath}: expected a boolean`);
+    }
+    return {
+        key: requireNonEmptyString(value.key, `Invalid agent config ${agentConfigPath}: missing required key`),
+        name: requireNonEmptyString(value.name, `Invalid agent config ${agentConfigPath}: missing required name`),
+        apiKey: requireNonEmptyString(value.apiKey, `Invalid agent config ${agentConfigPath}: missing required apiKey`),
+        provider: resolveProvider(requireNonEmptyString(value.provider, `Invalid agent config ${agentConfigPath}: missing required provider`), `Invalid provider in ${agentConfigPath}`),
+        enabled: enabled ?? true,
+        ...parseProviderCommandOverrides(value, `agent config ${agentConfigPath}`),
+    };
+}
+export function parseGenerateConfigSpec(value, sourceLabel) {
+    if (!isRecord(value)) {
+        throw new Error(`Invalid generate-config spec in ${sourceLabel}: expected a top-level object`);
+    }
+    if (!isRecord(value.host)) {
+        throw new Error(`Invalid generate-config spec in ${sourceLabel}: missing required host object`);
+    }
+    if (!Array.isArray(value.agents)) {
+        throw new Error(`Invalid generate-config spec in ${sourceLabel}: missing required agents array`);
+    }
+    const host = parseGenerateHostConfigFile(sourceLabel, value.host);
+    const seenKeys = new Map();
+    const seenGeneratedFilenames = new Map();
+    const agents = value.agents.map((entry, index) => {
+        if (!isRecord(entry)) {
+            throw new Error(`Invalid generate-config agents[${index}] in ${sourceLabel}: expected an object`);
+        }
+        const agent = parseAgentConfigFile(`generate-config agents[${index}] in ${sourceLabel}`, entry);
+        const existingIndex = seenKeys.get(agent.key);
+        if (existingIndex !== undefined) {
+            throw new Error(`Duplicate generate-config agent key "${agent.key}" in ${sourceLabel} at indexes ${existingIndex} and ${index}`);
+        }
+        seenKeys.set(agent.key, index);
+        const generatedFilename = toGeneratedAgentConfigFilename(agent.key);
+        const generatedFilenameIdentity = generatedFilename.toLowerCase();
+        const existingGeneratedFile = seenGeneratedFilenames.get(generatedFilenameIdentity);
+        if (existingGeneratedFile) {
+            throw new Error(`Conflicting generate-config agent keys "${existingGeneratedFile.key}" and "${agent.key}" in ${sourceLabel}: both map to ${generatedFilename} on a case-insensitive filesystem`);
+        }
+        seenGeneratedFilenames.set(generatedFilenameIdentity, { key: agent.key, index });
+        return agent;
+    });
+    return { host, agents };
+}
+function toGeneratedAgentConfigPath(agentsDir, key) {
+    return resolve(agentsDir, toGeneratedAgentConfigFilename(key));
+}
+function renderHostConfigYaml(host) {
+    const config = {
+        borgeeBaseUrl: host.borgeeBaseUrl,
+    };
+    if (host.defaults && Object.keys(host.defaults).length > 0) {
+        config.defaults = host.defaults;
+    }
+    return stringify(config);
+}
+function isNotFoundError(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+function isAlreadyExistsError(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST';
+}
+function wait(milliseconds) {
+    return new Promise((resolveWait) => {
+        setTimeout(resolveWait, milliseconds);
+    });
+}
+async function pathStatus(fileSystem, path) {
+    try {
+        return await fileSystem.lstat(path);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function ensureDirectory(fileSystem, path, mode) {
+    const status = await pathStatus(fileSystem, path);
+    if (status) {
+        if (!status.isDirectory || status.isSymbolicLink) {
+            throw new Error(`Managed config path must be a non-symlink directory: ${path}`);
+        }
+    }
+    else {
+        await fileSystem.mkdir(path, { recursive: true, mode });
+    }
+    await fileSystem.chmod(path, mode);
+}
+function parseManagedHolderMetadata(value) {
+    try {
+        const parsed = JSON.parse(value);
+        const pid = isRecord(parsed) ? parsed.pid : undefined;
+        const createdAt = isRecord(parsed) ? parsed.createdAt : undefined;
+        const token = isRecord(parsed) ? parsed.token : undefined;
+        if (!Number.isSafeInteger(pid) ||
+            typeof pid !== 'number' ||
+            pid <= 0 ||
+            typeof createdAt !== 'number' ||
+            !Number.isFinite(createdAt) ||
+            createdAt < 0 ||
+            createdAt > Date.now() ||
+            typeof token !== 'string' ||
+            token.length === 0) {
+            return undefined;
+        }
+        return {
+            pid,
+            createdAt,
+            token,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isOlderThanMaximumHolderAge(timestamp) {
+    return Date.now() - timestamp >= MANAGED_HOLDER_MAX_AGE_MS;
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ESRCH') {
+            return false;
+        }
+        return undefined;
+    }
+}
+async function readManagedHolderMetadata(fileSystem, holderPath) {
+    try {
+        return parseManagedHolderMetadata(await fileSystem.readFile(join(holderPath, MANAGED_HOLDER_METADATA_FILENAME)));
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function isStaleManagedHolderDirectory(fileSystem, holderPath) {
+    const status = await pathStatus(fileSystem, holderPath);
+    if (!status?.isDirectory || status.isSymbolicLink) {
+        return false;
+    }
+    const metadata = await readManagedHolderMetadata(fileSystem, holderPath);
+    if (!metadata) {
+        return isOlderThanMaximumHolderAge(status.mtimeMs);
+    }
+    const alive = isProcessAlive(metadata.pid);
+    return (alive === false || (alive === undefined && isOlderThanMaximumHolderAge(metadata.createdAt)));
+}
+async function createManagedHolderDirectory(fileSystem, holderPath) {
+    const metadata = {
+        pid: process.pid,
+        createdAt: Date.now(),
+        token: randomUUID(),
+    };
+    await fileSystem.mkdir(holderPath, { mode: MANAGED_ROOT_MODE });
+    try {
+        const metadataPath = join(holderPath, MANAGED_HOLDER_METADATA_FILENAME);
+        await fileSystem.writeFile(metadataPath, `${JSON.stringify(metadata)}\n`);
+        await fileSystem.chmod(metadataPath, MANAGED_CONFIG_MODE);
+        await fileSystem.chmod(holderPath, MANAGED_ROOT_MODE);
+        return metadata;
+    }
+    catch (error) {
+        await fileSystem.removeTree(holderPath).catch(() => undefined);
+        throw error;
+    }
+}
+async function releaseManagedHolderDirectory(fileSystem, holderPath, token) {
+    const metadata = await readManagedHolderMetadata(fileSystem, holderPath);
+    if (metadata?.token === token) {
+        await fileSystem.removeTree(holderPath);
+    }
+}
+async function acquireManagedWriteLock(fileSystem, root) {
+    const lockPath = join(root, MANAGED_WRITE_LOCK_DIRNAME);
+    const deadline = Date.now() + MANAGED_WRITE_LOCK_WAIT_MS;
+    while (true) {
+        try {
+            const metadata = await createManagedHolderDirectory(fileSystem, lockPath);
+            return async () => {
+                await releaseManagedHolderDirectory(fileSystem, lockPath, metadata.token);
+            };
+        }
+        catch (error) {
+            if (!isAlreadyExistsError(error)) {
+                throw error;
+            }
+            const status = await pathStatus(fileSystem, lockPath);
+            if (status && (!status.isDirectory || status.isSymbolicLink)) {
+                throw new Error(`Managed config write lock has an unexpected value: ${lockPath}`);
+            }
+            if (status && (await isStaleManagedHolderDirectory(fileSystem, lockPath))) {
+                await fileSystem.removeTree(lockPath);
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for managed config writer lock: ${lockPath}; another generate-config may still be running`);
+            }
+            await wait(MANAGED_WRITE_LOCK_RETRY_MS);
+        }
+    }
+}
+async function ensureManagedLink(fileSystem, path, target) {
+    const status = await pathStatus(fileSystem, path);
+    if (!status) {
+        await fileSystem.symlink(target, path);
+        return;
+    }
+    if (!status.isSymbolicLink || (await fileSystem.readLink(path)) !== target) {
+        throw new Error(`Managed config path has an unexpected value: ${path}`);
+    }
+}
+function isDirectManagedGeneration(root, target) {
+    const generationsDir = resolve(root, MANAGED_GENERATIONS_DIRNAME);
+    const resolvedTarget = resolve(root, target);
+    return (dirname(resolvedTarget) === generationsDir && relative(generationsDir, resolvedTarget) !== '');
+}
+async function prepareManagedRoot(fileSystem, root) {
+    await ensureDirectory(fileSystem, root, MANAGED_ROOT_MODE);
+    const generationsDir = join(root, MANAGED_GENERATIONS_DIRNAME);
+    await ensureDirectory(fileSystem, generationsDir, MANAGED_ROOT_MODE);
+    const currentPath = join(root, MANAGED_CURRENT_LINK_NAME);
+    const currentStatus = await pathStatus(fileSystem, currentPath);
+    const hostAliasPath = join(root, DEFAULT_LOCAL_HOST_CONFIG_FILENAME);
+    const agentsAliasPath = join(root, DEFAULT_LOCAL_AGENTS_DIRNAME);
+    if (!currentStatus) {
+        await ensureManagedLink(fileSystem, hostAliasPath, `${MANAGED_CURRENT_LINK_NAME}/${DEFAULT_LOCAL_HOST_CONFIG_FILENAME}`);
+        await ensureManagedLink(fileSystem, agentsAliasPath, `${MANAGED_CURRENT_LINK_NAME}/${DEFAULT_LOCAL_AGENTS_DIRNAME}`);
+        return {};
+    }
+    if (!currentStatus.isSymbolicLink) {
+        throw new Error(`Managed config path must be a symbolic link: ${currentPath}`);
+    }
+    const currentTarget = await fileSystem.readLink(currentPath);
+    if (!isDirectManagedGeneration(root, currentTarget)) {
+        throw new Error(`Managed config current generation must be inside ${generationsDir}`);
+    }
+    const currentGenerationPath = resolve(root, currentTarget);
+    const generationStatus = await pathStatus(fileSystem, currentGenerationPath);
+    if (!generationStatus?.isDirectory || generationStatus.isSymbolicLink) {
+        throw new Error(`Managed config current generation is not a directory: ${currentGenerationPath}`);
+    }
+    await fileSystem.chmod(currentGenerationPath, MANAGED_ROOT_MODE);
+    await ensureManagedLink(fileSystem, hostAliasPath, `${MANAGED_CURRENT_LINK_NAME}/${DEFAULT_LOCAL_HOST_CONFIG_FILENAME}`);
+    await ensureManagedLink(fileSystem, agentsAliasPath, `${MANAGED_CURRENT_LINK_NAME}/${DEFAULT_LOCAL_AGENTS_DIRNAME}`);
+    return { currentGenerationPath };
+}
+async function pruneSupersededGenerations(fileSystem, generationsDir, retainedGenerationPaths) {
+    const entries = await fileSystem.readDir(generationsDir);
+    await Promise.all(entries.map(async (entry) => {
+        if (!MANAGED_GENERATION_NAME_PATTERN.test(entry.name)) {
+            return;
+        }
+        const generationPath = resolve(generationsDir, entry.name);
+        if (dirname(generationPath) !== generationsDir ||
+            retainedGenerationPaths.has(generationPath)) {
+            return;
+        }
+        const status = await pathStatus(fileSystem, generationPath);
+        if (status?.isDirectory &&
+            !status.isSymbolicLink &&
+            !(await hasActiveGenerationReaders(fileSystem, generationPath))) {
+            await fileSystem.removeTree(generationPath);
+        }
+    }));
+}
+async function hasActiveGenerationReaders(fileSystem, generationPath) {
+    const readersPath = join(generationPath, MANAGED_READERS_DIRNAME);
+    const status = await pathStatus(fileSystem, readersPath);
+    if (!status) {
+        return false;
+    }
+    if (!status.isDirectory || status.isSymbolicLink) {
+        return true;
+    }
+    return clearStaleGenerationReaders(fileSystem, readersPath);
+}
+async function clearStaleGenerationReaders(fileSystem, readersPath) {
+    const entries = await fileSystem.readDir(readersPath);
+    let hasActiveReader = false;
+    for (const entry of entries) {
+        const leasePath = resolve(readersPath, entry.name);
+        if (dirname(leasePath) !== readersPath) {
+            hasActiveReader = true;
+            continue;
+        }
+        const leaseStatus = await pathStatus(fileSystem, leasePath);
+        if (!leaseStatus) {
+            continue;
+        }
+        if (!leaseStatus.isDirectory || leaseStatus.isSymbolicLink) {
+            hasActiveReader = true;
+            continue;
+        }
+        if (await isStaleManagedHolderDirectory(fileSystem, leasePath)) {
+            await fileSystem.removeTree(leasePath);
+            continue;
+        }
+        hasActiveReader = true;
+    }
+    return hasActiveReader;
+}
+function supportsManagedGenerationLeases(fileSystem) {
+    return ('mkdir' in fileSystem &&
+        'removeTree' in fileSystem &&
+        'lstat' in fileSystem &&
+        'chmod' in fileSystem &&
+        'readLink' in fileSystem);
+}
+async function managedRootForHostConfigPath(fileSystem, hostConfigPath) {
+    if (hostConfigPath === join(dirname(hostConfigPath), DEFAULT_LOCAL_HOST_CONFIG_FILENAME)) {
+        const generationPath = dirname(hostConfigPath);
+        const generationsDir = dirname(generationPath);
+        const root = dirname(generationsDir);
+        if (generationsDir === join(root, MANAGED_GENERATIONS_DIRNAME) &&
+            MANAGED_GENERATION_NAME_PATTERN.test(generationPath.slice(generationsDir.length + 1))) {
+            return root;
+        }
+    }
+    if (hostConfigPath !== join(dirname(hostConfigPath), DEFAULT_LOCAL_HOST_CONFIG_FILENAME)) {
+        return undefined;
+    }
+    const root = dirname(hostConfigPath);
+    const currentPath = join(root, MANAGED_CURRENT_LINK_NAME);
+    const currentStatus = await pathStatus(fileSystem, currentPath);
+    if (!currentStatus?.isSymbolicLink) {
+        return undefined;
+    }
+    return isDirectManagedGeneration(root, await fileSystem.readLink(currentPath)) ? root : undefined;
+}
+async function resolveHostConfigWithGenerationLease(fileSystem, absoluteHostConfigPath) {
+    const resolveHostConfigPath = async () => resolve(fileSystem.realPath
+        ? await fileSystem.realPath(absoluteHostConfigPath)
+        : absoluteHostConfigPath);
+    const noLease = async () => undefined;
+    if (!supportsManagedGenerationLeases(fileSystem)) {
+        return { resolvedHostConfigPath: await resolveHostConfigPath(), release: noLease };
+    }
+    const root = await managedRootForHostConfigPath(fileSystem, absoluteHostConfigPath);
+    if (!root) {
+        return { resolvedHostConfigPath: await resolveHostConfigPath(), release: noLease };
+    }
+    const releaseWriteLock = await acquireManagedWriteLock(fileSystem, root);
+    let leasePath;
+    try {
+        const resolvedHostConfigPath = await resolveHostConfigPath();
+        const generationPath = dirname(resolvedHostConfigPath);
+        const generationsDir = join(root, MANAGED_GENERATIONS_DIRNAME);
+        if (dirname(generationPath) !== generationsDir ||
+            !MANAGED_GENERATION_NAME_PATTERN.test(generationPath.slice(generationsDir.length + 1))) {
+            return { managedRootPath: root, resolvedHostConfigPath, release: noLease };
+        }
+        const generationStatus = await pathStatus(fileSystem, generationPath);
+        if (!generationStatus?.isDirectory || generationStatus.isSymbolicLink) {
+            return { managedRootPath: root, resolvedHostConfigPath, release: noLease };
+        }
+        const readersPath = join(generationPath, MANAGED_READERS_DIRNAME);
+        await ensureDirectory(fileSystem, readersPath, MANAGED_ROOT_MODE);
+        await clearStaleGenerationReaders(fileSystem, readersPath);
+        leasePath = join(readersPath, randomUUID());
+        const leaseMetadata = await createManagedHolderDirectory(fileSystem, leasePath);
+        return {
+            managedRootPath: root,
+            resolvedHostConfigPath,
+            release: async () => {
+                await releaseManagedHolderDirectory(fileSystem, leasePath, leaseMetadata.token);
+            },
+        };
+    }
+    catch (error) {
+        if (leasePath) {
+            await fileSystem.removeTree(leasePath).catch(() => undefined);
+        }
+        throw error;
+    }
+    finally {
+        await releaseWriteLock();
+    }
+}
+async function listSupportedConfigPaths(fileSystem, agentsDir) {
+    try {
+        const entries = await fileSystem.readDir(agentsDir);
+        return entries
+            .filter((entry) => entry.isFile)
+            .map((entry) => resolve(agentsDir, entry.name))
+            .filter((filePath) => SUPPORTED_CONFIG_EXTENSIONS.has(extname(filePath).toLowerCase()))
+            .sort((left, right) => left.localeCompare(right));
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return [];
+        }
+        throw error;
+    }
+}
+function renderAgentConfigYaml(agent) {
+    const config = {
+        key: agent.key,
+        name: agent.name,
+        apiKey: agent.apiKey,
+        provider: agent.provider,
+    };
+    if (agent.enabled !== undefined) {
+        config.enabled = agent.enabled;
+    }
+    if (agent.claudeCommand !== undefined) {
+        config.claudeCommand = agent.claudeCommand;
+    }
+    if (agent.claudeArgs !== undefined) {
+        config.claudeArgs = agent.claudeArgs;
+    }
+    if (agent.copilotCommand !== undefined) {
+        config.copilotCommand = agent.copilotCommand;
+    }
+    if (agent.copilotArgs !== undefined) {
+        config.copilotArgs = agent.copilotArgs;
+    }
+    if (agent.copilotSessionTtlMinutes !== undefined) {
+        config.copilotSessionTtlMinutes = agent.copilotSessionTtlMinutes;
+    }
+    return stringify(config);
+}
+function buildManagedAgentSnapshot(host, sourcePath, agent) {
+    const providerConfig = resolveProviderCommandConfig({
+        ...host.defaults,
+        ...parseProviderCommandOverrides(agent, `agent config ${sourcePath}`),
+    });
+    const config = {
+        borgeeBaseUrl: host.borgeeBaseUrl,
+        ...providerConfig,
+        agent: {
+            agentApiKey: agent.apiKey,
+            agentName: agent.name,
+            provider: agent.provider,
+        },
+    };
+    return {
+        key: agent.key,
+        sourcePath,
+        config,
+    };
+}
+export async function loadLocalConfigSnapshot(hostConfigPath, deps = {}) {
+    const fileSystem = deps.fileSystem ?? nodeFileSystem;
+    const absoluteHostConfigPath = resolve(hostConfigPath);
+    const managedGeneration = deps.acquireManagedGenerationLease === false
+        ? {
+            resolvedHostConfigPath: resolve(fileSystem.realPath
+                ? await fileSystem.realPath(absoluteHostConfigPath)
+                : absoluteHostConfigPath),
+            release: async () => undefined,
+        }
+        : await resolveHostConfigWithGenerationLease(fileSystem, absoluteHostConfigPath);
+    try {
+        const { resolvedHostConfigPath } = managedGeneration;
+        const hostConfigDir = dirname(absoluteHostConfigPath);
+        const resolvedHostConfigDir = dirname(resolvedHostConfigPath);
+        const hostConfigRecord = await loadParsedDocument(fileSystem, resolvedHostConfigPath, 'host config');
+        const hostConfig = parseHostConfigFile(absoluteHostConfigPath, hostConfigRecord);
+        const agentsDir = toAgentsDir(absoluteHostConfigPath, hostConfig.agentsDir);
+        const resolvedAgentsDir = resolve(fileSystem.realPath
+            ? await fileSystem.realPath(toAgentsDir(resolvedHostConfigPath, hostConfig.agentsDir))
+            : toAgentsDir(resolvedHostConfigPath, hostConfig.agentsDir));
+        const directoryEntries = await fileSystem.readDir(resolvedAgentsDir);
+        const agentFiles = directoryEntries
+            .filter((entry) => entry.isFile)
+            .map((entry) => resolve(resolvedAgentsDir, entry.name))
+            .filter((filePath) => filePath !== resolvedHostConfigPath)
+            .filter((filePath) => SUPPORTED_CONFIG_EXTENSIONS.has(extname(filePath).toLowerCase()))
+            .sort((left, right) => left.localeCompare(right));
+        const parsedAgents = [];
+        const seenKeys = new Map();
+        for (const agentFilePath of agentFiles) {
+            const agentRecord = await loadParsedDocument(fileSystem, agentFilePath, 'agent config');
+            const agentConfig = parseAgentConfigFile(agentFilePath, agentRecord);
+            const existingPath = seenKeys.get(agentConfig.key);
+            if (existingPath) {
+                throw new Error(`Duplicate agent key "${agentConfig.key}" in ${existingPath} and ${agentFilePath}`);
+            }
+            seenKeys.set(agentConfig.key, agentFilePath);
+            parsedAgents.push({ sourcePath: agentFilePath, config: agentConfig });
+        }
+        return {
+            hostConfigPath: absoluteHostConfigPath,
+            hostConfigDir,
+            agentsDir,
+            managedRootPath: managedGeneration.managedRootPath,
+            resolvedHostConfigPath,
+            resolvedHostConfigDir,
+            resolvedAgentsDir,
+            agents: parsedAgents
+                .filter((entry) => entry.config.enabled !== false)
+                .map((entry) => buildManagedAgentSnapshot(hostConfig, entry.sourcePath, entry.config)),
+        };
+    }
+    finally {
+        await managedGeneration.release();
+    }
+}
+export async function loadLocalConfigGenerateSpec(hostConfigPath, deps = {}) {
+    const fileSystem = deps.fileSystem ?? nodeFileSystem;
+    const absoluteHostConfigPath = resolve(hostConfigPath);
+    const managedGeneration = deps.acquireManagedGenerationLease === false
+        ? {
+            resolvedHostConfigPath: resolve(fileSystem.realPath
+                ? await fileSystem.realPath(absoluteHostConfigPath)
+                : absoluteHostConfigPath),
+            release: async () => undefined,
+        }
+        : await resolveHostConfigWithGenerationLease(fileSystem, absoluteHostConfigPath);
+    try {
+        const { resolvedHostConfigPath } = managedGeneration;
+        const hostConfigRecord = await loadParsedDocument(fileSystem, resolvedHostConfigPath, 'host config');
+        const hostConfig = parseHostConfigFile(absoluteHostConfigPath, hostConfigRecord);
+        const resolvedAgentsDir = resolve(fileSystem.realPath
+            ? await fileSystem.realPath(toAgentsDir(resolvedHostConfigPath, hostConfig.agentsDir))
+            : toAgentsDir(resolvedHostConfigPath, hostConfig.agentsDir));
+        const parsedAgents = [];
+        const seenKeys = new Map();
+        for (const agentFilePath of await listSupportedConfigPaths(fileSystem, resolvedAgentsDir)) {
+            if (agentFilePath === resolvedHostConfigPath) {
+                continue;
+            }
+            const agentRecord = await loadParsedDocument(fileSystem, agentFilePath, 'agent config');
+            const agentConfig = parseAgentConfigFile(agentFilePath, agentRecord);
+            const existingPath = seenKeys.get(agentConfig.key);
+            if (existingPath) {
+                throw new Error(`Duplicate agent key "${agentConfig.key}" in ${existingPath} and ${agentFilePath}`);
+            }
+            seenKeys.set(agentConfig.key, agentFilePath);
+            parsedAgents.push(agentConfig);
+        }
+        const host = {
+            borgeeBaseUrl: hostConfig.borgeeBaseUrl,
+        };
+        if (hostConfig.defaults && Object.keys(hostConfig.defaults).length > 0) {
+            host.defaults = hostConfig.defaults;
+        }
+        return { host, agents: parsedAgents };
+    }
+    finally {
+        await managedGeneration.release();
+    }
+}
+export async function materializeLocalConfig(rootPath, spec, deps = {}) {
+    const fileSystem = deps.fileSystem ?? nodeFileSystem;
+    const layout = resolveLocalConfigLayout(rootPath);
+    const desiredAgentFiles = new Map();
+    for (const agent of spec.agents) {
+        desiredAgentFiles.set(toGeneratedAgentConfigPath(layout.agentsDir, agent.key), agent);
+    }
+    const generatedAgents = [...desiredAgentFiles.entries()]
+        .map(([path, agent]) => ({ path, agent }))
+        .sort((left, right) => left.path.localeCompare(right.path));
+    await ensureDirectory(fileSystem, layout.root, MANAGED_ROOT_MODE);
+    const releaseWriteLock = await acquireManagedWriteLock(fileSystem, layout.root);
+    try {
+        const { currentGenerationPath } = await prepareManagedRoot(fileSystem, layout.root);
+        const priorAgentConfigPaths = await listSupportedConfigPaths(fileSystem, layout.agentsDir);
+        const generationName = randomUUID();
+        const generationsDir = join(layout.root, MANAGED_GENERATIONS_DIRNAME);
+        const generationPath = join(generationsDir, generationName);
+        const generationAgentsDir = join(generationPath, DEFAULT_LOCAL_AGENTS_DIRNAME);
+        const generationHostConfigPath = join(generationPath, DEFAULT_LOCAL_HOST_CONFIG_FILENAME);
+        const warnings = [];
+        let published = false;
+        try {
+            await fileSystem.mkdir(generationPath, { mode: MANAGED_ROOT_MODE });
+            await fileSystem.mkdir(generationAgentsDir, { mode: MANAGED_ROOT_MODE });
+            await fileSystem.writeFile(generationHostConfigPath, renderHostConfigYaml(spec.host));
+            await fileSystem.chmod(generationHostConfigPath, MANAGED_CONFIG_MODE);
+            for (const generated of generatedAgents) {
+                const generationAgentPath = join(generationAgentsDir, toGeneratedAgentConfigFilename(generated.agent.key));
+                await fileSystem.writeFile(generationAgentPath, renderAgentConfigYaml(generated.agent));
+                await fileSystem.chmod(generationAgentPath, MANAGED_CONFIG_MODE);
+            }
+            await loadLocalConfigSnapshot(generationHostConfigPath, {
+                fileSystem,
+                acquireManagedGenerationLease: false,
+            });
+            const nextCurrentPath = join(layout.root, `.${MANAGED_CURRENT_LINK_NAME}-${generationName}`);
+            await fileSystem.symlink(join(MANAGED_GENERATIONS_DIRNAME, generationName), nextCurrentPath);
+            await fileSystem.rename(nextCurrentPath, join(layout.root, MANAGED_CURRENT_LINK_NAME));
+            published = true;
+            try {
+                await pruneSupersededGenerations(fileSystem, generationsDir, new Set([generationPath, currentGenerationPath].filter((path) => path !== undefined)));
+            }
+            catch (error) {
+                warnings.push({
+                    code: 'PRUNE_SUPERSEDED_GENERATIONS_FAILED',
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        finally {
+            if (!published) {
+                await fileSystem.removeTree(generationPath).catch(() => undefined);
+            }
+        }
+        const activeAgentPaths = new Set(generatedAgents.map(({ path }) => path));
+        const prunedAgentConfigPaths = priorAgentConfigPaths.filter((path) => !activeAgentPaths.has(path));
+        return {
+            root: layout.root,
+            hostConfigPath: layout.hostConfigPath,
+            agentsDir: layout.agentsDir,
+            generatedAgents: generatedAgents.map(({ path, agent }) => ({
+                key: agent.key,
+                path,
+                provider: agent.provider,
+                enabled: agent.enabled ?? true,
+            })),
+            prunedAgentConfigPaths,
+            warnings,
+        };
+    }
+    finally {
+        await releaseWriteLock();
+    }
+}