@borgee/agents-host 0.2.73 → 0.2.74

package/README.md

@@ -140,7 +140,7 @@ and resumable in that case.
 
 Each managed runtime root keeps:
 
-- `agents-host.yaml` and `agents/` as the stable generated local-config entrypoints
+- `.generations/<uuid>/` as validated immutable config generations; Unix and macOS publish `current`, `agents-host.yaml`, and `agents/` symlinks, while Windows publishes the active generation through the atomically replaced ordinary `current.json` pointer and resolves the generation internally without requiring Developer Mode or elevation
 - `managed-runtime-settings.json` as the persisted managed runtime surface snapshot
 - `daemon.log` as the detached managed daemon stdout/stderr log file
 - `.state/` as the per-agent runtime state base
@@ -302,8 +302,7 @@ printf '%s' '{"host":{"borgeeBaseUrl":"https://borgee.example.com"},"agents":[{"
 - if that post-publication pruning fails, the apply remains successful and its
   JSON summary includes a `warnings` entry with code
   `PRUNE_SUPERSEDED_GENERATIONS_FAILED`
-- it uses a dedicated managed root: `<root>/agents-host.yaml` and
-  `<root>/agents` are stable links to the active private generation
+- it uses a dedicated managed root: Unix and macOS expose `<root>/agents-host.yaml` and `<root>/agents` as stable links to the active private generation, while Windows uses `<root>/current.json` as the stable publication point and resolves the active generation internally
 - it replaces stale supported agent config files as part of that atomic
   full-set publication, never by pruning the active set first
 - it creates and normalizes the managed root and generation directories to
@@ -349,12 +348,13 @@ The spec shape is:
 always targets `<root>/agents`, and validation is re-run after generation using
 the same local-config loader as `start --config` / `validate --config`. Start
 the generated layout with `agents-host start --config <root>/agents-host.yaml`;
-that stable path follows the active atomically published generation.
+the managed loader treats that path as the stable logical entrypoint even when
+Windows does not materialize a filesystem alias there.
 The loader preserves that stable path for validation output and publication
 watches, while pinning resolved host and agents-directory paths before reading.
 Managed snapshots hold a short-lived reader lease until the read finishes, so
-each snapshot uses one generation even if publication changes `current`
-concurrently.
+each snapshot uses one generation even if publication changes `current` or
+`current.json` concurrently.
 
 The supervisor loads:
 

package/dist/agents-host-supervisor.d.ts

@@ -17,6 +17,7 @@ export interface AgentsHostSupervisorDeps {
     watchPath?: (path: string, onEvent: (event?: WatchEventInfo) => void) => WatchHandle;
     logger?: LoggerLike;
     debug?: boolean;
+    platform?: NodeJS.Platform;
 }
 export declare class AgentsHostSupervisor {
     private readonly hostConfigPath;

package/dist/agents-host-supervisor.js

@@ -26,7 +26,9 @@ export class AgentsHostSupervisor {
     constructor(hostConfigPath, deps = {}) {
         this.hostConfigPath = resolve(hostConfigPath);
         this.createHost = deps.createHost ?? ((config, runtimeOptions) => new AgentsHost(config, { runtimeOptions }));
-        this.loadSnapshot = deps.loadSnapshot ?? ((configPath) => loadLocalConfigSnapshot(configPath));
+        this.loadSnapshot =
+            deps.loadSnapshot ??
+                ((configPath) => loadLocalConfigSnapshot(configPath, { platform: deps.platform }));
         this.watchPath =
             deps.watchPath ??
                 ((path, onEvent) => watch(path, (eventType, filename) => {

package/dist/local-config.d.ts

@@ -41,14 +41,21 @@ export declare function loadLocalConfigSnapshot(hostConfigPath: string, deps?: {
     fileSystem?: LocalConfigFileSystem;
     acquireManagedGenerationLease?: boolean;
     env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
 }): Promise<LocalConfigSnapshot>;
 export declare function loadLocalConfigGenerateSpec(hostConfigPath: string, deps?: {
     fileSystem?: LocalConfigFileSystem;
     acquireManagedGenerationLease?: boolean;
     env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
 }): Promise<LocalConfigGenerateSpec>;
+export declare function hasManagedLocalConfig(rootPath: string, deps?: {
+    fileSystem?: ManagedLocalConfigFileSystem;
+    platform?: NodeJS.Platform;
+}): Promise<boolean>;
 export declare function materializeLocalConfig(rootPath: string, spec: LocalConfigGenerateSpec, deps?: {
     fileSystem?: ManagedLocalConfigFileSystem;
     env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
 }): Promise<LocalConfigGenerateResult>;
 export {};

package/dist/local-config.js

@@ -10,6 +10,8 @@ export const DEFAULT_LOCAL_AGENTS_DIRNAME = 'agents';
 const DEFAULT_AGENTS_DIR = './agents';
 const MANAGED_GENERATIONS_DIRNAME = '.generations';
 const MANAGED_CURRENT_LINK_NAME = 'current';
+const MANAGED_CURRENT_POINTER_FILENAME = 'current.json';
+const MANAGED_CURRENT_POINTER_SCHEMA_VERSION = 1;
 export const MANAGED_WRITE_LOCK_DIRNAME = '.generate-config.lock';
 const MANAGED_READERS_DIRNAME = '.readers';
 const MANAGED_HOLDER_METADATA_FILENAME = '.holder.json';
@@ -391,10 +393,106 @@ function isDirectManagedGeneration(root, target) {
     const resolvedTarget = resolve(root, target);
     return (dirname(resolvedTarget) === generationsDir && relative(generationsDir, resolvedTarget) !== '');
 }
-async function prepareManagedRoot(fileSystem, root) {
+function parseManagedCurrentPointer(raw, pointerPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid managed config pointer ${pointerPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(parsed) ||
+        Object.keys(parsed).sort().join(',') !== 'generation,schemaVersion' ||
+        parsed.schemaVersion !== MANAGED_CURRENT_POINTER_SCHEMA_VERSION ||
+        typeof parsed.generation !== 'string' ||
+        !MANAGED_GENERATION_NAME_PATTERN.test(parsed.generation) ||
+        isAbsolute(parsed.generation) ||
+        parsed.generation.includes('/') ||
+        parsed.generation.includes('\\')) {
+        throw new Error(`Invalid managed config pointer ${pointerPath}: expected schemaVersion ${MANAGED_CURRENT_POINTER_SCHEMA_VERSION} and one direct generation identifier`);
+    }
+    return {
+        schemaVersion: MANAGED_CURRENT_POINTER_SCHEMA_VERSION,
+        generation: parsed.generation,
+    };
+}
+async function resolvePointerGeneration(fileSystem, root) {
+    const pointerPath = join(root, MANAGED_CURRENT_POINTER_FILENAME);
+    const pointerStatus = await pathStatus(fileSystem, pointerPath);
+    if (!pointerStatus) {
+        return undefined;
+    }
+    if (pointerStatus.isDirectory || pointerStatus.isSymbolicLink) {
+        throw new Error(`Managed config pointer must be an ordinary file: ${pointerPath}`);
+    }
+    const pointer = parseManagedCurrentPointer(await fileSystem.readFile(pointerPath), pointerPath);
+    const generationsDir = join(root, MANAGED_GENERATIONS_DIRNAME);
+    const generationPath = resolve(generationsDir, pointer.generation);
+    if (dirname(generationPath) !== generationsDir ||
+        relative(generationsDir, generationPath) !== pointer.generation) {
+        throw new Error(`Managed config pointer generation must be a direct child of ${generationsDir}`);
+    }
+    const generationStatus = await pathStatus(fileSystem, generationPath);
+    if (!generationStatus?.isDirectory || generationStatus.isSymbolicLink) {
+        throw new Error(`Managed config pointer target is not a directory: ${generationPath}`);
+    }
+    return generationPath;
+}
+async function resolveLegacyCurrentGeneration(fileSystem, root) {
+    const generationsDir = join(root, MANAGED_GENERATIONS_DIRNAME);
+    const currentPath = join(root, MANAGED_CURRENT_LINK_NAME);
+    const currentStatus = await pathStatus(fileSystem, currentPath);
+    if (!currentStatus) {
+        return undefined;
+    }
+    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}`);
+    }
+    return currentGenerationPath;
+}
+async function validateOptionalLegacyAliases(fileSystem, root) {
+    const aliases = [
+        [
+            join(root, DEFAULT_LOCAL_HOST_CONFIG_FILENAME),
+            `${MANAGED_CURRENT_LINK_NAME}/${DEFAULT_LOCAL_HOST_CONFIG_FILENAME}`,
+        ],
+        [
+            join(root, DEFAULT_LOCAL_AGENTS_DIRNAME),
+            `${MANAGED_CURRENT_LINK_NAME}/${DEFAULT_LOCAL_AGENTS_DIRNAME}`,
+        ],
+    ];
+    for (const [path, target] of aliases) {
+        const status = await pathStatus(fileSystem, path);
+        if (status && (!status.isSymbolicLink || (await fileSystem.readLink(path)) !== target)) {
+            throw new Error(`Managed config path has an unexpected value: ${path}`);
+        }
+    }
+}
+async function prepareManagedRoot(fileSystem, root, platform) {
     await ensureDirectory(fileSystem, root, MANAGED_ROOT_MODE);
     const generationsDir = join(root, MANAGED_GENERATIONS_DIRNAME);
     await ensureDirectory(fileSystem, generationsDir, MANAGED_ROOT_MODE);
+    if (platform === 'win32') {
+        await validateOptionalLegacyAliases(fileSystem, root);
+        const pointerGeneration = await resolvePointerGeneration(fileSystem, root);
+        const legacyGeneration = pointerGeneration
+            ? undefined
+            : await resolveLegacyCurrentGeneration(fileSystem, root);
+        const currentGenerationPath = pointerGeneration ?? legacyGeneration;
+        if (currentGenerationPath) {
+            await fileSystem.chmod(currentGenerationPath, MANAGED_ROOT_MODE);
+        }
+        return { currentGenerationPath };
+    }
     const currentPath = join(root, MANAGED_CURRENT_LINK_NAME);
     const currentStatus = await pathStatus(fileSystem, currentPath);
     const hostAliasPath = join(root, DEFAULT_LOCAL_HOST_CONFIG_FILENAME);
@@ -483,7 +581,7 @@ function supportsManagedGenerationLeases(fileSystem) {
         'chmod' in fileSystem &&
         'readLink' in fileSystem);
 }
-async function managedRootForHostConfigPath(fileSystem, hostConfigPath) {
+async function managedRootForHostConfigPath(fileSystem, hostConfigPath, platform) {
     if (hostConfigPath === join(dirname(hostConfigPath), DEFAULT_LOCAL_HOST_CONFIG_FILENAME)) {
         const generationPath = dirname(hostConfigPath);
         const generationsDir = dirname(generationPath);
@@ -497,6 +595,11 @@ async function managedRootForHostConfigPath(fileSystem, hostConfigPath) {
         return undefined;
     }
     const root = dirname(hostConfigPath);
+    if (platform === 'win32') {
+        const pointerStatus = await pathStatus(fileSystem, join(root, MANAGED_CURRENT_POINTER_FILENAME));
+        const currentStatus = await pathStatus(fileSystem, join(root, MANAGED_CURRENT_LINK_NAME));
+        return pointerStatus || currentStatus ? root : undefined;
+    }
     const currentPath = join(root, MANAGED_CURRENT_LINK_NAME);
     const currentStatus = await pathStatus(fileSystem, currentPath);
     if (!currentStatus?.isSymbolicLink) {
@@ -504,7 +607,7 @@ async function managedRootForHostConfigPath(fileSystem, hostConfigPath) {
     }
     return isDirectManagedGeneration(root, await fileSystem.readLink(currentPath)) ? root : undefined;
 }
-async function resolveHostConfigWithGenerationLease(fileSystem, absoluteHostConfigPath) {
+async function resolveHostConfigWithGenerationLease(fileSystem, absoluteHostConfigPath, platform) {
     const resolveHostConfigPath = async () => resolve(fileSystem.realPath
         ? await fileSystem.realPath(absoluteHostConfigPath)
         : absoluteHostConfigPath);
@@ -512,14 +615,20 @@ async function resolveHostConfigWithGenerationLease(fileSystem, absoluteHostConf
     if (!supportsManagedGenerationLeases(fileSystem)) {
         return { resolvedHostConfigPath: await resolveHostConfigPath(), release: noLease };
     }
-    const root = await managedRootForHostConfigPath(fileSystem, absoluteHostConfigPath);
+    const root = await managedRootForHostConfigPath(fileSystem, absoluteHostConfigPath, platform);
     if (!root) {
         return { resolvedHostConfigPath: await resolveHostConfigPath(), release: noLease };
     }
     const releaseWriteLock = await acquireManagedWriteLock(fileSystem, root);
     let leasePath;
     try {
-        const resolvedHostConfigPath = await resolveHostConfigPath();
+        const activeGenerationPath = platform === 'win32'
+            ? ((await resolvePointerGeneration(fileSystem, root)) ??
+                (await resolveLegacyCurrentGeneration(fileSystem, root)))
+            : undefined;
+        const resolvedHostConfigPath = activeGenerationPath
+            ? join(activeGenerationPath, DEFAULT_LOCAL_HOST_CONFIG_FILENAME)
+            : await resolveHostConfigPath();
         const generationPath = dirname(resolvedHostConfigPath);
         const generationsDir = join(root, MANAGED_GENERATIONS_DIRNAME);
         if (dirname(generationPath) !== generationsDir ||
@@ -660,7 +769,7 @@ export async function loadLocalConfigSnapshot(hostConfigPath, deps = {}) {
                 : absoluteHostConfigPath),
             release: async () => undefined,
         }
-        : await resolveHostConfigWithGenerationLease(fileSystem, absoluteHostConfigPath);
+        : await resolveHostConfigWithGenerationLease(fileSystem, absoluteHostConfigPath, deps.platform ?? process.platform);
     try {
         const { resolvedHostConfigPath } = managedGeneration;
         const hostConfigDir = dirname(absoluteHostConfigPath);
@@ -718,7 +827,7 @@ export async function loadLocalConfigGenerateSpec(hostConfigPath, deps = {}) {
                 : absoluteHostConfigPath),
             release: async () => undefined,
         }
-        : await resolveHostConfigWithGenerationLease(fileSystem, absoluteHostConfigPath);
+        : await resolveHostConfigWithGenerationLease(fileSystem, absoluteHostConfigPath, deps.platform ?? process.platform);
     try {
         const { resolvedHostConfigPath } = managedGeneration;
         const hostConfigRecord = await loadParsedDocument(fileSystem, resolvedHostConfigPath, 'host config');
@@ -755,9 +864,20 @@ export async function loadLocalConfigGenerateSpec(hostConfigPath, deps = {}) {
         await managedGeneration.release();
     }
 }
+export async function hasManagedLocalConfig(rootPath, deps = {}) {
+    const fileSystem = deps.fileSystem ?? nodeFileSystem;
+    const root = resolve(rootPath);
+    const platform = deps.platform ?? process.platform;
+    if (platform === 'win32') {
+        return ((await resolvePointerGeneration(fileSystem, root)) !== undefined ||
+            (await resolveLegacyCurrentGeneration(fileSystem, root)) !== undefined);
+    }
+    return (await pathStatus(fileSystem, join(root, DEFAULT_LOCAL_HOST_CONFIG_FILENAME))) !== undefined;
+}
 export async function materializeLocalConfig(rootPath, spec, deps = {}) {
     const fileSystem = deps.fileSystem ?? nodeFileSystem;
     const layout = resolveLocalConfigLayout(rootPath);
+    const platform = deps.platform ?? process.platform;
     const desiredAgentFiles = new Map();
     for (const agent of spec.agents) {
         desiredAgentFiles.set(toGeneratedAgentConfigPath(layout.agentsDir, agent.key), agent);
@@ -768,8 +888,10 @@ export async function materializeLocalConfig(rootPath, spec, deps = {}) {
     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 { currentGenerationPath } = await prepareManagedRoot(fileSystem, layout.root, platform);
+        const priorAgentConfigPaths = (await listSupportedConfigPaths(fileSystem, currentGenerationPath
+            ? join(currentGenerationPath, DEFAULT_LOCAL_AGENTS_DIRNAME)
+            : layout.agentsDir)).map((path) => join(layout.agentsDir, path.slice(dirname(path).length + 1)));
         const generationName = randomUUID();
         const generationsDir = join(layout.root, MANAGED_GENERATIONS_DIRNAME);
         const generationPath = join(generationsDir, generationName);
@@ -792,9 +914,33 @@ export async function materializeLocalConfig(rootPath, spec, deps = {}) {
                 acquireManagedGenerationLease: false,
                 env: deps.env,
             });
-            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));
+            if (platform === 'win32') {
+                const nextCurrentPath = join(layout.root, `.${MANAGED_CURRENT_POINTER_FILENAME}-${generationName}`);
+                await fileSystem.writeFile(nextCurrentPath, `${JSON.stringify({
+                    schemaVersion: MANAGED_CURRENT_POINTER_SCHEMA_VERSION,
+                    generation: generationName,
+                })}\n`);
+                await fileSystem.chmod(nextCurrentPath, MANAGED_CONFIG_MODE);
+                try {
+                    await fileSystem.rename(nextCurrentPath, join(layout.root, MANAGED_CURRENT_POINTER_FILENAME));
+                }
+                catch (error) {
+                    try {
+                        await fileSystem.removeFile(nextCurrentPath);
+                    }
+                    catch (cleanupError) {
+                        if (!isNotFoundError(cleanupError)) {
+                            throw new AggregateError([error, cleanupError], 'Managed config pointer publication and cleanup both failed');
+                        }
+                    }
+                    throw error;
+                }
+            }
+            else {
+                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)));

package/dist/managed-daemon.js

@@ -9,7 +9,7 @@ import { DEFAULT_PROJECTION_STRATEGY, normalizeProjectionStrategy, } from './pro
 import { resolveChannelWorkspaceDirectory, resolveChannelWorkspaceRootDirectory, resolveManagedWorkspaceCollectionRoot, resolveTaskThreadScratchWorkspaceDirectory, } from './context/injection.js';
 import { CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE, COMPATIBILITY_GATES_ENV, CURRENT_AGENTS_HOST_PACKAGE_VERSION, createManagedRuntimeSettingsFingerprint, INTERNAL_CLAUDE_PROMPT_STRATEGY_ENV, INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV, INTERNAL_POLICY_MODE_ENV, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE, MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION, resolveDisabledDefaultCompatibilityGates, resolveManagedRuntimeSettingsSnapshot, serializeManagedRuntimeSettingsSnapshot, normalizeInternalProviderImplementationOverrides, } from './compatibility-gates.js';
 import { DEFAULT_PROVIDER_COMMAND_CONFIG, hasLegacyClaudeOneShotArgs, loadConfigFromEnv, } from './config.js';
-import { loadLocalConfigGenerateSpec, materializeLocalConfig, parseGenerateConfigSpec, resolveLocalConfigLayout, } from './local-config.js';
+import { hasManagedLocalConfig, loadLocalConfigGenerateSpec, materializeLocalConfig, parseGenerateConfigSpec, resolveLocalConfigLayout, } from './local-config.js';
 import { normalizeManagedRuntimeKey, resolveManagedBootstrapLockPath, resolveManagedDaemonEndpoint, resolveManagedDaemonLogPath, resolveManagedRuntimeRoot, resolveManagedStateRoot, resolveManagedRuntimeSettingsPath, } from './state-paths.js';
 const MANAGED_ROOT_MODE = 0o700;
 const MANAGED_CONFIG_MODE = 0o600;
@@ -1130,7 +1130,7 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
             });
         if (options.apiKey !== undefined
             && currentRuntimeSettings.persistedSettingsSnapshot == null
-            && await fs.access(resolved.hostConfigPath).then(() => true).catch(() => false)) {
+            && await hasManagedLocalConfig(resolved.rootPath)) {
             throw new Error(`Managed runtime root ${resolved.rootPath} predates managed-runtime-settings.json; run \`agents-host start-managed ${options.serverUrl}\` once to migrate it before updating an individual agent`);
         }
         const explicitManagedAgentOverrides = collectExplicitManagedAgentEnvOverrides(options.processEnv ?? process.env, options.env);
@@ -1628,9 +1628,16 @@ export class ManagedAgentsHostDaemon {
         this.endpoint = resolveManagedDaemonEndpoint(this.rootPath, deps.platform);
         this.createSupervisor =
             deps.createSupervisor ??
-                ((configPath, daemonDebug) => new AgentsHostSupervisor(configPath, { debug: daemonDebug }));
-        this.loadSpec = deps.loadSpec ?? loadLocalConfigGenerateSpec;
-        this.materialize = deps.materialize ?? materializeLocalConfig;
+                ((configPath, daemonDebug) => new AgentsHostSupervisor(configPath, {
+                    debug: daemonDebug,
+                    platform: deps.platform,
+                }));
+        this.loadSpec =
+            deps.loadSpec ??
+                ((configPath) => loadLocalConfigGenerateSpec(configPath, { platform: deps.platform }));
+        this.materialize =
+            deps.materialize ??
+                ((managedRootPath, spec) => materializeLocalConfig(managedRootPath, spec, { platform: deps.platform }));
         const managedRuntimeSettings = resolveDesiredManagedRuntimeSettings(process.env);
         this.managedRuntimeFingerprint = managedRuntimeSettings.fingerprint;
         this.logger = deps.logger ?? console;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgee/agents-host",
-  "version": "0.2.73",
+  "version": "0.2.74",
   "private": false,
   "publishConfig": {
     "access": "public"