@borgee/agents-host 0.2.29 → 0.2.32

package/dist/providers/create-provider.js

@@ -1,7 +1,7 @@
 import { FileChannelContextStore } from '../context/injection.js';
 import { createProviderConnectionsSessionStore } from '../connections-state-store.js';
 import { ProviderTurnPreparer } from '../context/turn-preparation.js';
-import { CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE, CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE, CONTEXT_INJECTION_COMPATIBILITY_GATE, CODEX_PROVIDER_COMPATIBILITY_GATE, COPILOT_PROVIDER_V2_COMPATIBILITY_GATE, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, LOCALHOST_GATEWAY_COMPATIBILITY_GATE, parseInternalProviderImplementationOverrides, POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE, resolveInternalPolicyMode, resolveInternalCompatibilityGates, SKILL_RUNTIME_COMPATIBILITY_GATE, } from '../compatibility-gates.js';
+import { CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE, CONTEXT_INJECTION_COMPATIBILITY_GATE, CODEX_PROVIDER_COMPATIBILITY_GATE, COPILOT_PROVIDER_V2_COMPATIBILITY_GATE, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, LOCALHOST_GATEWAY_COMPATIBILITY_GATE, parseInternalProviderImplementationOverrides, POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE, resolveInternalPolicyMode, resolveInternalCompatibilityGates, SKILL_RUNTIME_COMPATIBILITY_GATE, } from '../compatibility-gates.js';
 import { ClaudeCliClient } from './claude/cli-client.js';
 import { ClaudeProviderAdapter } from './claude/adapter.js';
 import { FileClaudeChannelSessionStore } from './claude/session-store.js';
@@ -45,22 +45,19 @@ class CliBackedProviderV2 {
         await this.cli.dispose();
     }
 }
-class ClaudeProviderV2 extends CliBackedProviderV2 {
-}
 class CopilotProviderV2 extends CliBackedProviderV2 {
 }
 const TASK_WORKSPACE_ROOT_DIR_ENV = 'AGENTS_HOST_INTERNAL_TASK_WORKSPACE_ROOT_DIR';
 const PROVIDER_V2_COMPATIBILITY_GATES = {
-    claude: CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE,
     copilot: COPILOT_PROVIDER_V2_COMPATIBILITY_GATE,
 };
-function resolveProviderImplementation(provider, routingConfig) {
-    if (!routingConfig.compatibilityGates.has(PROVIDER_V2_COMPATIBILITY_GATES[provider])) {
+function resolveCopilotImplementation(routingConfig) {
+    if (!routingConfig.compatibilityGates.has(PROVIDER_V2_COMPATIBILITY_GATES.copilot)) {
         return 'v1';
     }
-    return routingConfig.implementationOverrides[provider] ?? 'v2';
+    return routingConfig.implementationOverrides.copilot ?? 'v2';
 }
-function createClaudeProvider(config, debugLogger, connectionsStateGateEnabled, implementation, turnPreparer) {
+function createClaudeProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer) {
     const cli = new ClaudeCliClient(config.claudeCommand, config.claudeArgs, {}, createProviderConnectionsSessionStore({
         provider: 'claude',
         legacyStore: new FileClaudeChannelSessionStore({
@@ -70,9 +67,7 @@ function createClaudeProvider(config, debugLogger, connectionsStateGateEnabled,
         gateEnabled: connectionsStateGateEnabled,
         logger: debugLogger,
     }), config.resolveStableAgentId, debugLogger);
-    return implementation === 'v2'
-        ? new ProviderV2CompatibilityAdapter(new ClaudeProviderV2(cli), turnPreparer)
-        : new ClaudeProviderAdapter(cli, turnPreparer);
+    return new ClaudeProviderAdapter(cli, turnPreparer);
 }
 function createCopilotProvider(config, debugLogger, connectionsStateGateEnabled, implementation, turnPreparer, policyAuditGateEnabled, authorizationAuditSink) {
     const policyMode = resolveInternalPolicyMode(policyAuditGateEnabled);
@@ -129,7 +124,7 @@ export function createProvider(config, debugLogger, options = {}) {
     const turnPreparer = new ProviderTurnPreparer(channelContextStore, debugLogger);
     switch (config.provider) {
         case 'claude': {
-            return createClaudeProvider(config, debugLogger, connectionsStateGateEnabled, resolveProviderImplementation('claude', routingConfig), turnPreparer);
+            return createClaudeProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer);
         }
         case 'codex': {
             if (!routingConfig.compatibilityGates.has(CODEX_PROVIDER_COMPATIBILITY_GATE)) {
@@ -138,7 +133,7 @@ export function createProvider(config, debugLogger, options = {}) {
             return createCodexProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer);
         }
         case 'copilot': {
-            return createCopilotProvider(config, debugLogger, connectionsStateGateEnabled, resolveProviderImplementation('copilot', routingConfig), turnPreparer, policyAuditGateEnabled, options.authorizationAuditSink);
+            return createCopilotProvider(config, debugLogger, connectionsStateGateEnabled, resolveCopilotImplementation(routingConfig), turnPreparer, policyAuditGateEnabled, options.authorizationAuditSink);
         }
         default:
             throw new Error(`Unsupported provider: ${String(config.provider)}`);

package/dist/state-paths.d.ts

@@ -1,6 +1,11 @@
 export declare function normalizeManagedRuntimeKey(serverUrl: string): string;
 export declare function resolveSingleAgentStateRoot(env?: NodeJS.ProcessEnv, resolvedHomeDir?: string, agentKey?: string): string;
 export declare function resolveManagedRuntimeRoot(serverUrl: string, env?: NodeJS.ProcessEnv, resolvedHomeDir?: string): string;
+/**
+ * The update check is a property of the installed CLI, not of any one agent or
+ * server runtime, so its cache lives directly under the shared agents-host home.
+ */
+export declare function resolveUpdateCheckCachePath(env?: NodeJS.ProcessEnv, resolvedHomeDir?: string): string;
 export declare function resolveManagedStateRoot(rootPath: string): string;
 export declare function resolveManagedDaemonSocketPath(rootPath: string): string;
 export declare function resolveManagedDaemonLogPath(rootPath: string): string;

package/dist/state-paths.js

@@ -10,6 +10,7 @@ const MANAGED_DAEMON_SOCKET_FILENAME = 'ctl.sock';
 const MANAGED_DAEMON_LOG_FILENAME = 'daemon.log';
 const MANAGED_RUNTIME_SETTINGS_FILENAME = 'managed-runtime-settings.json';
 const MANAGED_BOOTSTRAP_LOCK_DIRNAME = '.bootstrap.lock';
+const UPDATE_CHECK_CACHE_FILENAME = 'update-check.json';
 const STATE_ROOT_LABEL_MAX_LENGTH = 48;
 const MANAGED_RUNTIME_LABEL_MAX_LENGTH = 24;
 function encodeSegment(value) {
@@ -80,6 +81,17 @@ export function resolveManagedRuntimeRoot(serverUrl, env = process.env, resolved
     }
     return join(home, SINGLE_AGENT_HOME_ROOT, AGENTS_HOST_ROOT, MANAGED_RUNTIME_NAMESPACE, `${sanitizeManagedRuntimeLabel(serverUrl)}-${hashManagedRuntimeKey(serverUrl)}`);
 }
+/**
+ * The update check is a property of the installed CLI, not of any one agent or
+ * server runtime, so its cache lives directly under the shared agents-host home.
+ */
+export function resolveUpdateCheckCachePath(env = process.env, resolvedHomeDir = homedir()) {
+    const home = env.HOME?.trim() || resolvedHomeDir.trim();
+    if (!home) {
+        throw new Error('Unable to resolve a user home directory for agents-host state');
+    }
+    return join(home, SINGLE_AGENT_HOME_ROOT, AGENTS_HOST_ROOT, UPDATE_CHECK_CACHE_FILENAME);
+}
 export function resolveManagedStateRoot(rootPath) {
     return join(resolve(rootPath), MANAGED_STATE_DIRNAME);
 }

package/dist/types.d.ts

@@ -377,6 +377,7 @@ export interface UpdateTaskInput {
     status?: string;
     assigneeId?: string;
     title?: string;
+    description?: string;
 }
 export interface ProviderProgressUpdate {
     text: string;

package/dist/update/package-installation.d.ts

@@ -0,0 +1,52 @@
+import { type PackageManagerName, type RunPackageManagerDeps } from './package-manager.js';
+export declare const AGENTS_HOST_PACKAGE_NAME = "@borgee/agents-host";
+/**
+ * Where the running CLI sits on disk, before anyone has asked a package manager
+ * about it. Everything here comes from the filesystem, so a startup that has
+ * nothing to report never pays for a subprocess.
+ */
+export interface PackageLocation {
+    packageName: string;
+    version: string;
+    packageRootDir: string;
+    /**
+     * Directory owning the outermost `node_modules` above the package, or `null`
+     * when the package is not inside one at all. Outermost rather than innermost
+     * because pnpm links a dependency out of `<owner>/node_modules/.pnpm/<pkg>@<version>`,
+     * so the innermost `node_modules` belongs to the store, not to anyone's project.
+     */
+    nodeModulesOwnerDir: string | null;
+}
+/**
+ * How the running CLI got onto this machine. The three shapes need different
+ * update advice, so they are modelled as separate variants rather than as one
+ * record with optional fields.
+ */
+export type PackageInstallation = (PackageLocation & {
+    kind: 'global';
+    packageManager: PackageManagerName;
+}) | (PackageLocation & {
+    kind: 'project';
+    projectRootDir: string;
+}) | (PackageLocation & {
+    kind: 'source-checkout';
+});
+export interface PackageInstallationFs {
+    readFile(path: string): Promise<string>;
+    fileExists(path: string): Promise<boolean>;
+}
+export interface ResolvePackageLocationDeps {
+    fs?: PackageInstallationFs;
+    startDir?: string;
+}
+export interface ClassifyPackageInstallationDeps extends RunPackageManagerDeps {
+    packageManagers?: readonly PackageManagerName[];
+}
+export declare function resolvePackageLocation(deps?: ResolvePackageLocationDeps): Promise<PackageLocation>;
+/**
+ * Decides between a global install, someone's project dependency, and a git
+ * checkout by asking each installed package manager where it puts its global
+ * installs and seeing which answer contains this package. Managers that are not
+ * installed simply never match.
+ */
+export declare function classifyPackageInstallation(location: PackageLocation, deps?: ClassifyPackageInstallationDeps): Promise<PackageInstallation>;

package/dist/update/package-installation.js

@@ -0,0 +1,90 @@
+import { promises as fs } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PACKAGE_MANAGERS, readGlobalRootDir, } from './package-manager.js';
+export const AGENTS_HOST_PACKAGE_NAME = '@borgee/agents-host';
+const GLOBAL_ROOT_TIMEOUT_MS = 5000;
+const defaultPackageInstallationFs = {
+    readFile: (path) => fs.readFile(path, 'utf8'),
+    fileExists: async (path) => {
+        try {
+            return (await fs.stat(path)).isFile();
+        }
+        catch (error) {
+            if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+                return false;
+            }
+            throw error;
+        }
+    },
+};
+function splitPathSegments(path) {
+    return path.split(/[\\/]/u);
+}
+function resolveNodeModulesOwnerDir(packageRootDir) {
+    const segments = splitPathSegments(packageRootDir);
+    const nodeModulesIndex = segments.indexOf('node_modules');
+    if (nodeModulesIndex < 0) {
+        return null;
+    }
+    const owner = segments.slice(0, nodeModulesIndex).join('/');
+    return owner.length > 0 ? owner : '/';
+}
+/** True when `descendantDir` is `ancestorDir` itself or sits underneath it. */
+function isWithinDir(ancestorDir, descendantDir) {
+    const ancestor = resolve(ancestorDir);
+    const descendant = resolve(descendantDir);
+    return descendant === ancestor || descendant.startsWith(`${ancestor}${sep}`);
+}
+async function findOwningPackageManifest(startDir, installationFs) {
+    let currentDir = startDir;
+    for (;;) {
+        const manifestPath = join(currentDir, 'package.json');
+        if (await installationFs.fileExists(manifestPath)) {
+            const manifest = JSON.parse(await installationFs.readFile(manifestPath));
+            if (typeof manifest === 'object' &&
+                manifest !== null &&
+                manifest.name === AGENTS_HOST_PACKAGE_NAME) {
+                const version = manifest.version;
+                if (typeof version !== 'string' || version.length === 0) {
+                    throw new Error(`${manifestPath} declares no version`);
+                }
+                return { packageRootDir: currentDir, version };
+            }
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            throw new Error(`Unable to locate the ${AGENTS_HOST_PACKAGE_NAME} package manifest above ${startDir}`);
+        }
+        currentDir = parentDir;
+    }
+}
+export async function resolvePackageLocation(deps = {}) {
+    const installationFs = deps.fs ?? defaultPackageInstallationFs;
+    const startDir = deps.startDir ?? dirname(fileURLToPath(import.meta.url));
+    const { packageRootDir, version } = await findOwningPackageManifest(startDir, installationFs);
+    return {
+        packageName: AGENTS_HOST_PACKAGE_NAME,
+        version,
+        packageRootDir,
+        nodeModulesOwnerDir: resolveNodeModulesOwnerDir(packageRootDir),
+    };
+}
+/**
+ * Decides between a global install, someone's project dependency, and a git
+ * checkout by asking each installed package manager where it puts its global
+ * installs and seeing which answer contains this package. Managers that are not
+ * installed simply never match.
+ */
+export async function classifyPackageInstallation(location, deps = {}) {
+    if (location.nodeModulesOwnerDir === null) {
+        return { ...location, kind: 'source-checkout' };
+    }
+    for (const packageManager of deps.packageManagers ?? PACKAGE_MANAGERS) {
+        const globalRootDir = await readGlobalRootDir(packageManager, GLOBAL_ROOT_TIMEOUT_MS, deps);
+        if (globalRootDir !== null && isWithinDir(globalRootDir, location.packageRootDir)) {
+            return { ...location, kind: 'global', packageManager };
+        }
+    }
+    return { ...location, kind: 'project', projectRootDir: location.nodeModulesOwnerDir };
+}

package/dist/update/package-manager.d.ts

@@ -0,0 +1,33 @@
+export type PackageManagerName = 'npm' | 'pnpm' | 'yarn' | 'bun';
+export declare const PACKAGE_MANAGERS: readonly PackageManagerName[];
+export declare class PackageManagerAbsentError extends Error {
+}
+export interface RunPackageManagerDeps {
+    runCommand?: (command: string, args: string[], timeoutMs: number) => Promise<string>;
+}
+export declare function buildGlobalInstallArgv(packageManager: PackageManagerName, packageSpec: string): {
+    command: string;
+    args: string[];
+};
+/**
+ * Where `packageManager` puts its global installs, or `null` when that manager
+ * is not installed on this machine.
+ */
+export declare function readGlobalRootDir(packageManager: PackageManagerName, timeoutMs: number, deps?: RunPackageManagerDeps): Promise<string | null>;
+/**
+ * The registry npm resolves for this working directory. Asking npm rather than
+ * reading `npm_config_registry` ourselves is what makes project-level and user
+ * `.npmrc` files count, which is also where a private registry's credentials
+ * live.
+ */
+export declare function readConfiguredRegistry(timeoutMs: number, deps?: RunPackageManagerDeps): Promise<string>;
+/**
+ * Newest published release of `packageName`, as npm resolves it.
+ *
+ * `npm view` rather than a hand-rolled request to the registry: npm is the
+ * reference implementation of everything around that request — `.npmrc`
+ * discovery, scoped auth tokens, proxies, custom CAs, retries, mirrors — and
+ * all four supported managers publish to and read from the same registry, so
+ * the answer does not depend on which one owns the install.
+ */
+export declare function readPublishedVersion(packageName: string, timeoutMs: number, deps?: RunPackageManagerDeps): Promise<string>;

package/dist/update/package-manager.js

@@ -0,0 +1,137 @@
+import spawn from 'cross-spawn';
+import { dirname, join } from 'node:path';
+import { isSemanticVersion } from './semantic-version.js';
+export const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
+const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
+export class PackageManagerAbsentError extends Error {
+}
+/**
+ * Runs a package-manager command and returns its stdout. stderr is dropped:
+ * every manager writes advisory noise there (pnpm's npmrc warnings, npm's
+ * update banner), and none of it is part of the answer.
+ *
+ * The deadline kills the child rather than merely rejecting. That is the whole
+ * reason the registry is reached through a subprocess: a resolver that swallows
+ * DNS queries hangs inside `getaddrinfo`, which has no cancellation, so the
+ * same lookup done in-process would keep this process alive long past its
+ * budget. A killed child takes its hung syscall with it.
+ */
+function runCommandProcess(command, args, timeoutMs) {
+    return new Promise((resolveOutput, rejectCommand) => {
+        const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        let bytes = 0;
+        let timedOut = false;
+        const deadline = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        child.stdout?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => {
+            bytes += Buffer.byteLength(chunk, 'utf8');
+            if (bytes > MAX_COMMAND_OUTPUT_BYTES) {
+                child.kill('SIGKILL');
+                return;
+            }
+            stdout += chunk;
+        });
+        child.on('error', (error) => {
+            clearTimeout(deadline);
+            if (error.code === 'ENOENT') {
+                rejectCommand(new PackageManagerAbsentError(`${command} is not on PATH`));
+                return;
+            }
+            rejectCommand(error);
+        });
+        child.on('close', (code) => {
+            clearTimeout(deadline);
+            if (timedOut) {
+                rejectCommand(new Error(`${command} ${args.join(' ')} exceeded its ${timeoutMs}ms deadline`));
+                return;
+            }
+            if (code !== 0) {
+                rejectCommand(new Error(`${command} ${args.join(' ')} exited with code ${code}`));
+                return;
+            }
+            resolveOutput(stdout.trim());
+        });
+    });
+}
+/**
+ * How each manager reports the directory its global installs land in. Verified
+ * against the real CLIs rather than inferred from paths, because every
+ * path-shaped rule we tried missed at least one layout: pnpm links a dependency
+ * out of a virtual store, yarn v1 capitalises `%LOCALAPPDATA%\Yarn\Data` on
+ * Windows, and bun relocates everything under `BUN_INSTALL`.
+ *
+ * `npm root -g` and `pnpm root -g` already name the `node_modules` directory.
+ * `yarn global dir` names its parent. `bun pm bin -g` names `<BUN_INSTALL>/bin`,
+ * whose sibling `install/global` is the root bun installs into.
+ */
+const GLOBAL_ROOT_QUERIES = {
+    npm: { args: ['root', '-g'], toRootDir: (output) => output },
+    pnpm: { args: ['root', '-g'], toRootDir: (output) => output },
+    yarn: { args: ['global', 'dir'], toRootDir: (output) => join(output, 'node_modules') },
+    bun: {
+        args: ['pm', 'bin', '-g'],
+        toRootDir: (output) => join(dirname(output), 'install', 'global', 'node_modules'),
+    },
+};
+const GLOBAL_INSTALL_ARGV = {
+    npm: ['install', '-g'],
+    pnpm: ['add', '-g'],
+    yarn: ['global', 'add'],
+    bun: ['add', '-g'],
+};
+export function buildGlobalInstallArgv(packageManager, packageSpec) {
+    return { command: packageManager, args: [...GLOBAL_INSTALL_ARGV[packageManager], packageSpec] };
+}
+/**
+ * Where `packageManager` puts its global installs, or `null` when that manager
+ * is not installed on this machine.
+ */
+export async function readGlobalRootDir(packageManager, timeoutMs, deps = {}) {
+    const runCommand = deps.runCommand ?? runCommandProcess;
+    const query = GLOBAL_ROOT_QUERIES[packageManager];
+    try {
+        const output = await runCommand(packageManager, [...query.args], timeoutMs);
+        return output.length > 0 ? query.toRootDir(output) : null;
+    }
+    catch (error) {
+        if (error instanceof PackageManagerAbsentError) {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * The registry npm resolves for this working directory. Asking npm rather than
+ * reading `npm_config_registry` ourselves is what makes project-level and user
+ * `.npmrc` files count, which is also where a private registry's credentials
+ * live.
+ */
+export async function readConfiguredRegistry(timeoutMs, deps = {}) {
+    const runCommand = deps.runCommand ?? runCommandProcess;
+    return runCommand('npm', ['config', 'get', 'registry'], timeoutMs);
+}
+/**
+ * Newest published release of `packageName`, as npm resolves it.
+ *
+ * `npm view` rather than a hand-rolled request to the registry: npm is the
+ * reference implementation of everything around that request — `.npmrc`
+ * discovery, scoped auth tokens, proxies, custom CAs, retries, mirrors — and
+ * all four supported managers publish to and read from the same registry, so
+ * the answer does not depend on which one owns the install.
+ */
+export async function readPublishedVersion(packageName, timeoutMs, deps = {}) {
+    const runCommand = deps.runCommand ?? runCommandProcess;
+    const output = await runCommand('npm', ['view', packageName, 'version', '--json'], timeoutMs);
+    const parsed = JSON.parse(output);
+    // Whatever comes back here ends up as an npm install spec, so anything that
+    // is not a plain version — a git URL, a tarball URL, a dist-tag — would let a
+    // hostile registry point the install at a source npm never vetted.
+    if (typeof parsed !== 'string' || !isSemanticVersion(parsed)) {
+        throw new Error(`npm view reported no semantic version for ${packageName}`);
+    }
+    return parsed.trim();
+}

package/dist/update/semantic-version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Semantic-version precedence for update decisions. Implemented here rather
+ * than pulled in as a dependency because the published CLI needs exactly one
+ * comparison, and precedence is fully specified by https://semver.org/#spec-item-11.
+ */
+export declare function isSemanticVersion(value: string): boolean;
+export declare function isNewerSemanticVersion(candidate: string, baseline: string): boolean;

package/dist/update/semantic-version.js

@@ -0,0 +1,76 @@
+/**
+ * Semantic-version precedence for update decisions. Implemented here rather
+ * than pulled in as a dependency because the published CLI needs exactly one
+ * comparison, and precedence is fully specified by https://semver.org/#spec-item-11.
+ */
+const SEMANTIC_VERSION_PATTERN = /^(?<major>0|[1-9]\d*)\.(?<minor>0|[1-9]\d*)\.(?<patch>0|[1-9]\d*)(?:-(?<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/u;
+const NUMERIC_IDENTIFIER_PATTERN = /^(?:0|[1-9]\d*)$/u;
+function parseSemanticVersion(value) {
+    const match = SEMANTIC_VERSION_PATTERN.exec(value.trim());
+    if (!match?.groups) {
+        throw new Error(`Not a semantic version: ${value}`);
+    }
+    const { major, minor, patch, prerelease } = match.groups;
+    return {
+        release: [major, minor, patch],
+        prerelease: prerelease === undefined ? [] : prerelease.split('.'),
+    };
+}
+export function isSemanticVersion(value) {
+    return SEMANTIC_VERSION_PATTERN.test(value.trim());
+}
+/**
+ * Semver puts no upper bound on numeric identifiers, so they are compared as
+ * digit strings: without leading zeroes the longer string is always the larger
+ * number. `parseInt` would silently collapse anything past 2^53.
+ */
+function compareNumericIdentifiers(left, right) {
+    if (left.length !== right.length) {
+        return left.length < right.length ? -1 : 1;
+    }
+    return compareStrings(left, right);
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function comparePrereleaseIdentifier(left, right) {
+    const leftIsNumeric = NUMERIC_IDENTIFIER_PATTERN.test(left);
+    const rightIsNumeric = NUMERIC_IDENTIFIER_PATTERN.test(right);
+    if (leftIsNumeric && rightIsNumeric) {
+        return compareNumericIdentifiers(left, right);
+    }
+    if (leftIsNumeric) {
+        return -1;
+    }
+    if (rightIsNumeric) {
+        return 1;
+    }
+    return compareStrings(left, right);
+}
+function comparePrerelease(left, right) {
+    if (left.length === 0 || right.length === 0) {
+        // A prerelease ranks below the release it leads up to.
+        return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
+    }
+    for (let index = 0; index < Math.min(left.length, right.length); index++) {
+        const identifierOrder = comparePrereleaseIdentifier(left[index], right[index]);
+        if (identifierOrder !== 0) {
+            return identifierOrder;
+        }
+    }
+    return Math.sign(left.length - right.length);
+}
+function compareSemanticVersions(left, right) {
+    const parsedLeft = parseSemanticVersion(left);
+    const parsedRight = parseSemanticVersion(right);
+    for (let index = 0; index < parsedLeft.release.length; index++) {
+        const releaseOrder = compareNumericIdentifiers(parsedLeft.release[index], parsedRight.release[index]);
+        if (releaseOrder !== 0) {
+            return releaseOrder;
+        }
+    }
+    return comparePrerelease(parsedLeft.prerelease, parsedRight.prerelease);
+}
+export function isNewerSemanticVersion(candidate, baseline) {
+    return compareSemanticVersions(candidate, baseline) > 0;
+}

package/dist/update/update-command.d.ts

@@ -0,0 +1,9 @@
+import { type PackageInstallation, type PackageLocation } from './package-installation.js';
+export interface RunUpdateCommandDeps {
+    resolveLocation?: () => Promise<PackageLocation>;
+    classifyInstallation?: (location: PackageLocation) => Promise<PackageInstallation>;
+    resolveLatestVersion?: (packageName: string, timeoutMs: number) => Promise<string>;
+    runInstall?: (command: string, args: string[]) => Promise<number>;
+    logger?: Pick<Console, 'log'>;
+}
+export declare function runUpdateCommand(deps?: RunUpdateCommandDeps): Promise<void>;

package/dist/update/update-command.js

@@ -0,0 +1,55 @@
+import spawn from 'cross-spawn';
+import { classifyPackageInstallation, resolvePackageLocation, } from './package-installation.js';
+import { buildGlobalInstallArgv, readPublishedVersion } from './package-manager.js';
+import { isNewerSemanticVersion } from './semantic-version.js';
+const UPDATE_LOOKUP_TIMEOUT_MS = 30000;
+function runInstallProcess(command, args) {
+    return new Promise((resolveExitCode, rejectInstall) => {
+        const child = spawn(command, args, { stdio: 'inherit' });
+        child.on('error', rejectInstall);
+        child.on('close', (code, signal) => {
+            if (signal !== null) {
+                rejectInstall(new Error(`${command} ${args.join(' ')} was terminated by ${signal}`));
+                return;
+            }
+            resolveExitCode(code ?? 0);
+        });
+    });
+}
+/**
+ * Only a globally installed CLI owns its own version. A source checkout is
+ * updated with git, and rewriting a project's dependency behind its manifest is
+ * that project's decision, not this command's.
+ */
+function assertSelfUpdatableInstallation(installation) {
+    if (installation.kind === 'source-checkout') {
+        throw new Error(`${installation.packageName} is running from a source checkout at ${installation.packageRootDir}; update that checkout with git instead of the npm registry`);
+    }
+    if (installation.kind === 'project') {
+        throw new Error(`${installation.packageName} is installed as a dependency of ${installation.projectRootDir}; update it through that project's manifest instead of self-updating`);
+    }
+}
+export async function runUpdateCommand(deps = {}) {
+    const logger = deps.logger ?? console;
+    const resolveLocation = deps.resolveLocation ?? (() => resolvePackageLocation());
+    const classifyInstallation = deps.classifyInstallation ?? ((location) => classifyPackageInstallation(location));
+    const resolveLatestVersion = deps.resolveLatestVersion ?? readPublishedVersion;
+    const runInstall = deps.runInstall ?? runInstallProcess;
+    const installation = await classifyInstallation(await resolveLocation());
+    assertSelfUpdatableInstallation(installation);
+    const latestVersion = await resolveLatestVersion(installation.packageName, UPDATE_LOOKUP_TIMEOUT_MS);
+    // Ordering rather than inequality: a machine running ahead of `latest` — a
+    // prerelease, or a release that was unpublished — must not be walked backwards.
+    if (!isNewerSemanticVersion(latestVersion, installation.version)) {
+        logger.log(`[agents-host] already on ${installation.packageName}@${installation.version}`);
+        return;
+    }
+    const { command, args } = buildGlobalInstallArgv(installation.packageManager, `${installation.packageName}@${latestVersion}`);
+    logger.log(`[agents-host] updating ${installation.packageName} ${installation.version} -> ${latestVersion}`);
+    logger.log(`[agents-host] running: ${command} ${args.join(' ')}`);
+    const exitCode = await runInstall(command, args);
+    if (exitCode !== 0) {
+        throw new Error(`${command} ${args.join(' ')} exited with code ${exitCode}`);
+    }
+    logger.log(`[agents-host] updated to ${installation.packageName}@${latestVersion}`);
+}

package/dist/update/update-notice.d.ts

@@ -0,0 +1,39 @@
+import { type LoggerLike } from '../debug.js';
+import { type PackageInstallation, type PackageLocation } from './package-installation.js';
+export declare const DISABLE_UPDATE_CHECK_ENV = "AGENTS_HOST_DISABLE_UPDATE_CHECK";
+export interface AvailableUpdate {
+    installation: PackageInstallation;
+    latestVersion: string;
+}
+export interface UpdateCheckOptions {
+    env?: NodeJS.ProcessEnv;
+}
+export interface UpdateCheckDeps {
+    resolveLocation?: () => Promise<PackageLocation>;
+    classifyInstallation?: (location: PackageLocation) => Promise<PackageInstallation>;
+    readRegistry?: (timeoutMs: number) => Promise<string>;
+    readLatestVersion?: (packageName: string, timeoutMs: number) => Promise<string>;
+    readCache?: (path: string) => Promise<string>;
+    writeCache?: (path: string, contents: string) => Promise<void>;
+    now?: () => number;
+    logger?: LoggerLike;
+}
+export declare function isUpdateCheckDisabled(env: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolves the newest published release for the running installation, or `null`
+ * when there is nothing worth telling the operator.
+ *
+ * Source checkouts never check: their version is whatever the working tree
+ * says, and `agents-host update` is the wrong advice for a git tree. That is
+ * settled from the path alone, so `pnpm dev` never spawns a package manager.
+ * Which manager owns a real install is only asked once there is a notice to
+ * word, so a start with nothing to report never pays for that either.
+ */
+export declare function resolveAvailableUpdate(options?: UpdateCheckOptions, deps?: UpdateCheckDeps): Promise<AvailableUpdate | null>;
+/**
+ * Startup-path entry point. The notice is advisory, so every failure below it —
+ * offline machine, unreachable registry, unreadable cache — is logged in debug
+ * mode and then dropped: a registry outage must never keep an agent from
+ * starting. It writes to stderr so machine-readable stdout stays clean.
+ */
+export declare function emitUpdateNotice(options?: UpdateCheckOptions, deps?: UpdateCheckDeps): Promise<void>;