@hivemagnus/magnus-agent 1.0.1 → 1.0.3

package/.env.example

@@ -95,6 +95,9 @@ LOG_LEVEL=info
 # ── Ardent (optional) ────────────────────────────────────────────────
 # ARDENT_OWNER_USER=operator
 # ARDENT_STAGED_PACKAGE=/opt/magnus-agent/ardent-package.tgz
+# Scoped npm names accepted as the Ardent runtime, in preference order. Add an
+# older build's package name to keep managing it (interoperating with older components).
+# MAGNUS_AGENT_ARDENT_PACKAGES=@hivemagnus/ardent
 
 # ── HiveMem credential renewal (optional, all lists empty by default) ─
 # Entries live in a root-owned 0600 JSON file; the lists below bound what the

package/README.md

@@ -150,7 +150,7 @@ and `magnus-agent env-schema` prints them as JSON.
 | `SKILLS_DIR` / `SKILLS_EXTRA_DIRS` | Skill directories |
 | `HERMES_USER`, `HERMES_REGISTRY_TOKEN`, `MAGNUS_HERMES_SYNC_PULL` | Hermes Agent management and registry sync |
 | `CODEX_USER`, `CODEX_BIN`, `CODEX_HOME` | Codex CLI management |
-| `ARDENT_OWNER_USER`, `ARDENT_STAGED_PACKAGE` | Ardent management |
+| `ARDENT_OWNER_USER`, `ARDENT_STAGED_PACKAGE`, `MAGNUS_AGENT_ARDENT_PACKAGES` | Ardent management |
 | `MAGNUS_AGENT_RENEWAL_*` | HiveMem credential renewal allowlists (empty by default) |
 | `MAGNUS_AGENT_TLS_RENEWAL=tailscale` | Renew a Tailscale listener certificate |
 | `MAGNUS_AGENT_PRIVILEGED` | Privileged (root, default `true`) or unprivileged mode |
@@ -175,6 +175,17 @@ With `--submit-only` it only reports the local Hermes inventory. Applying the
 server's desired skills, plugins and MCP releases also needs
 `MAGNUS_HERMES_SYNC_PULL=true`.
 
+## Interoperating with older components
+
+`MAGNUS_AGENT_ARDENT_PACKAGES` (default `@hivemagnus/ardent`) lists the scoped
+npm package names the agent accepts as the Ardent runtime, in preference order.
+It applies to the staged `ardent-package.json` sidecar, the install path
+`node_modules/<name>`, the install receipt and the managed `ardent@<profile>`
+user unit. To keep managing an Ardent build published under another scope, add
+its name, for example `MAGNUS_AGENT_ARDENT_PACKAGES=@hivemagnus/ardent,@legacy-scope/ardent`.
+Older sidecars with the `{name, version, sha256}` shape are accepted unchanged.
+Profile channel maps accept any channel key that matches `[a-z][a-z0-9_-]{0,31}`.
+
 ## Development
 
 ```bash

package/dist/env-catalog.js

@@ -36,6 +36,7 @@ export const agentEnvCatalog = [
     { name: 'CODEX_HOME', required: false, secret: false, default: '~/.codex', group: 'codex', description: 'Codex state directory override.' },
     { name: 'ARDENT_OWNER_USER', required: false, secret: false, group: 'ardent', description: 'Local account that owns the Ardent runtime and profiles.' },
     { name: 'ARDENT_STAGED_PACKAGE', required: false, secret: false, default: '/opt/magnus-agent/ardent-package.tgz', group: 'ardent', description: 'Verified Ardent package tarball staged for installation.' },
+    { name: 'MAGNUS_AGENT_ARDENT_PACKAGES', required: false, secret: false, default: '@hivemagnus/ardent', group: 'ardent', description: 'Comma-separated scoped npm package names accepted as the Ardent runtime (staged sidecar, install path, receipt), in preference order. Add a legacy name to keep managing an older Ardent build.' },
     { name: 'MAGNUS_AGENT_RENEWAL_CONFIG', required: false, secret: false, default: '$AGENT_INSTALL_DIR/credential-renewal.json', group: 'renewal', description: 'HiveMem credential renewal entries (root-owned, mode 0600). Absent means renewal is off.' },
     { name: 'MAGNUS_AGENT_RENEWAL_ENDPOINTS', required: false, secret: false, group: 'renewal', description: 'Comma-separated HTTPS HiveMem base URLs renewal may call.' },
     { name: 'MAGNUS_AGENT_RENEWAL_UNITS', required: false, secret: false, group: 'renewal', description: 'Comma-separated systemd units renewal may try-restart after replacing a credential.' },

package/dist/env.js

@@ -10,6 +10,7 @@
 import { getFqdn } from './fqdn.js';
 import { isIPv4 } from 'node:net';
 import { agentPrivileged, isRoot } from './privileged.js';
+import { ardentPackageNames } from './executors/ardent-packages.js';
 function envFlag(name, fallback = false) {
     return (process.env[name] ?? String(fallback)).toLowerCase() === 'true';
 }
@@ -113,6 +114,12 @@ export function configurationErrors() {
     if (!agentPrivileged() && MAGNUS_EXECUTION_SUPERVISOR_ENABLED) {
         errors.push('MAGNUS_EXECUTION_SUPERVISOR_ENABLED=true requires MAGNUS_AGENT_PRIVILEGED=true');
     }
+    try {
+        ardentPackageNames();
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : 'MAGNUS_AGENT_ARDENT_PACKAGES is invalid');
+    }
     return errors;
 }
 //# sourceMappingURL=env.js.map

package/dist/executors/ardent-manager.d.ts

@@ -1,4 +1,5 @@
 import { Hono } from 'hono';
+export { ardentPackageNames, DEFAULT_ARDENT_PACKAGE } from './ardent-packages.js';
 type ArdentRoot = {
     owner: string;
     home: string;
@@ -6,13 +7,13 @@ type ArdentRoot = {
     install: string;
 };
 export declare function verifiedInstalledArdentPackage(install: string, staged: {
+    name?: string;
     version: string;
     sha256: string;
 }): Promise<boolean>;
 export declare function readArdentState(target?: ArdentRoot): Promise<object>;
 export declare function hermesTrafficConsumersDisabled(home: string): Promise<boolean>;
-export declare function ardentUserUnit(root: ArdentRoot, profile: string): string;
+export declare function ardentUserUnit(root: ArdentRoot, profile: string, packageName?: string): string;
 export declare function createArdentRoutes(resolveRoot?: () => Promise<ArdentRoot>): Hono;
 export declare const ardentRoutes: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
-export {};
 //# sourceMappingURL=ardent-manager.d.ts.map

package/dist/executors/ardent-manager.js

@@ -7,6 +7,8 @@ import { Hono } from 'hono';
 import { parse as parseEnv } from 'dotenv';
 import YAML from 'yaml';
 import { z } from 'zod';
+import { ardentPackageNames } from './ardent-packages.js';
+export { ardentPackageNames, DEFAULT_ARDENT_PACKAGE } from './ardent-packages.js';
 const profileName = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
 const configSummary = z.object({
     schema_version: z.literal(1), profile: profileName, name: z.string().min(1),
@@ -15,12 +17,34 @@ const configSummary = z.object({
     a2a: z.object({ enabled: z.boolean() }).passthrough(),
     channels: z.record(z.string().regex(/^[a-z][a-z0-9_-]{0,31}$/), z.object({ enabled: z.boolean() }).passthrough()).default({}),
 }).passthrough();
-const packageVersion = z.object({ name: z.literal('@hivemagnus/ardent'), version: z.string() });
+const acceptedPackageName = z.string().refine(name => ardentPackageNames().includes(name), 'Ardent package name is not accepted by MAGNUS_AGENT_ARDENT_PACKAGES');
+const packageVersion = z.object({ name: acceptedPackageName, version: z.string() });
 const installedPackageReceipt = z.object({
-    schemaVersion: z.literal(1), name: z.literal('@hivemagnus/ardent'),
+    schemaVersion: z.literal(1), name: acceptedPackageName,
     version: z.string(), sha256: z.string().regex(/^[a-f0-9]{64}$/),
     packageTreeSha256: z.string().regex(/^[a-f0-9]{64}$/),
 }).strict();
+/** Package directory of an accepted Ardent package name inside an install prefix. */
+function packageDir(install, name) {
+    if (!ardentPackageNames().includes(name))
+        throw new Error('Ardent package name is not accepted by MAGNUS_AGENT_ARDENT_PACKAGES');
+    return join(install, 'node_modules', ...name.split('/'));
+}
+/** The accepted Ardent package installed under `install`, in preference order. */
+async function installedPackageName(install) {
+    for (const name of ardentPackageNames()) {
+        try {
+            const installed = packageVersion.parse(JSON.parse(await readFile(join(packageDir(install, name), 'package.json'), 'utf8')));
+            if (installed.name === name)
+                return name;
+        }
+        catch { /* Try the next accepted name. */ }
+    }
+    return null;
+}
+async function installedCli(install) {
+    return join(packageDir(install, await installedPackageName(install) ?? ardentPackageNames()[0]), 'dist/cli.js');
+}
 /** Channel name -> enabled, for every channel the profile config declares. */
 function channelStates(config) {
     return Object.fromEntries(Object.entries(config.channels).map(([name, channel]) => [name, channel.enabled]));
@@ -112,11 +136,11 @@ async function stagedPackage() {
     const sidecarBytes = await readFile(sidecar);
     if (createHash('sha256').update(sidecarBytes).digest('hex') !== entry('ardent-package.json'))
         throw new Error('Staged Ardent package sidecar differs from release manifest');
-    const details = z.object({ name: z.literal('@hivemagnus/ardent'), version: z.string(), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).parse(JSON.parse(sidecarBytes.toString('utf8')));
+    const details = z.object({ name: acceptedPackageName, version: z.string(), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).parse(JSON.parse(sidecarBytes.toString('utf8')));
     const digest = createHash('sha256').update(await readFile(archive)).digest('hex');
     if (digest !== details.sha256 || digest !== entry('ardent-package.tgz'))
         throw new Error('Staged Ardent package differs from release manifest');
-    return { version: details.version, sha256: digest };
+    return { name: details.name, version: details.version, sha256: digest };
 }
 async function packageTreeDigest(packageRoot) {
     const entries = [];
@@ -160,15 +184,20 @@ export async function verifiedInstalledArdentPackage(install, staged) {
     const receipt = installedPackageReceipt.safeParse(JSON.parse(await readFile(receiptPath, 'utf8')));
     if (!receipt.success || receipt.data.version !== staged.version || receipt.data.sha256 !== staged.sha256)
         return false;
-    return await packageTreeDigest(join(install, 'node_modules/@hivemagnus/ardent')) === receipt.data.packageTreeSha256;
+    if (staged.name !== undefined && receipt.data.name !== staged.name)
+        return false;
+    return await packageTreeDigest(packageDir(install, receipt.data.name)) === receipt.data.packageTreeSha256;
 }
 export async function readArdentState(target) {
     const root = target ?? await ardentRoot();
     let version = null;
+    let packageName = null;
     try {
-        const packageFile = join(root.install, 'node_modules/@hivemagnus/ardent/package.json');
-        const installed = JSON.parse(await readFile(packageFile, 'utf8'));
-        version = packageVersion.parse(installed).version;
+        packageName = await installedPackageName(root.install);
+        if (packageName) {
+            const installed = JSON.parse(await readFile(join(packageDir(root.install, packageName), 'package.json'), 'utf8'));
+            version = packageVersion.parse(installed).version;
+        }
     }
     catch { /* An uninstalled package is a normal inventory state. */ }
     const profiles = await Promise.all((await safeProfiles(root.root)).map(async (name) => {
@@ -191,7 +220,7 @@ export async function readArdentState(target) {
     catch (error) {
         stagedPackageError = error instanceof Error ? error.message.slice(0, 200) : 'Staged package unavailable';
     }
-    return { installed: version !== null, version, owner: root.owner, profiles, stagedPackage: staged, stagedPackageError, checkedAt: new Date().toISOString() };
+    return { installed: version !== null, version, packageName, owner: root.owner, profiles, stagedPackage: staged, stagedPackageError, checkedAt: new Date().toISOString() };
 }
 async function managementToken(dir, envName) {
     const processToken = process.env[envName];
@@ -264,12 +293,12 @@ export async function hermesTrafficConsumersDisabled(home) {
         return false;
     }
 }
-export function ardentUserUnit(root, profile) {
+export function ardentUserUnit(root, profile, packageName = ardentPackageNames()[0]) {
     profileName.parse(profile);
     const safe = /^[A-Za-z0-9_./-]+$/;
     if (![root.home, root.root, root.install].every(path => safe.test(path)))
         throw new Error('Ardent service paths contain unsupported characters');
-    return `[Unit]\nDescription=Magnus Ardent ${profile}\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nWorkingDirectory=${join(root.root, 'profiles', profile)}\nEnvironment=ARDENT_HOME=${root.root}\nExecStart=/usr/bin/node ${join(root.install, 'node_modules/@hivemagnus/ardent/dist/cli.js')} --profile ${profile} gateway run\nRestart=on-failure\nRestartSec=5\nTimeoutStopSec=75\nNoNewPrivileges=true\n\n[Install]\nWantedBy=default.target\n`;
+    return `[Unit]\nDescription=Magnus Ardent ${profile}\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nWorkingDirectory=${join(root.root, 'profiles', profile)}\nEnvironment=ARDENT_HOME=${root.root}\nExecStart=/usr/bin/node ${join(packageDir(root.install, packageName), 'dist/cli.js')} --profile ${profile} gateway run\nRestart=on-failure\nRestartSec=5\nTimeoutStopSec=75\nNoNewPrivileges=true\n\n[Install]\nWantedBy=default.target\n`;
 }
 async function serviceAction(root, profile, action) {
     if (process.getuid?.() !== 0)
@@ -289,7 +318,7 @@ async function serviceAction(root, profile, action) {
     }
     const unit = `ardent@${profile}.service`;
     const path = join(root.home, '.config/systemd/user', unit);
-    const expected = ardentUserUnit(root, profile);
+    const expected = ardentUserUnit(root, profile, await installedPackageName(root.install) ?? undefined);
     const metadata = await lstat(path).catch((error) => {
         if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
             return undefined;
@@ -307,7 +336,7 @@ async function serviceAction(root, profile, action) {
     if (action !== 'service-start' && existing === undefined)
         throw new Error('Managed Ardent user service is not installed');
     if (action === 'service-start' && existing === undefined) {
-        const script = join(root.install, 'node_modules/@hivemagnus/ardent/dist/cli.js');
+        const script = await installedCli(root.install);
         const scriptInfo = await lstat(script);
         if (!scriptInfo.isFile() || scriptInfo.isSymbolicLink())
             throw new Error('Ardent package executable is unavailable');
@@ -377,14 +406,14 @@ async function installPackage(root) {
     let installed = false;
     try {
         await runAsOwner(root, ['/usr/bin/npm', 'install', '--prefix', stage, '--omit=dev', '--no-audit', '--no-fund', '--no-save', archive], 9 * 60_000);
-        const packageFile = join(stage, 'node_modules/@hivemagnus/ardent/package.json');
+        const packageFile = join(packageDir(stage, staged.name), 'package.json');
         const candidate = packageVersion.parse(JSON.parse(await readFile(packageFile, 'utf8')));
-        if (candidate.version !== staged.version)
-            throw new Error('Staged Ardent package version differs');
+        if (candidate.name !== staged.name || candidate.version !== staged.version)
+            throw new Error('Staged Ardent package name or version differs');
         await runAsOwner(root, ['/usr/bin/node', '-e', "const Database=require(process.argv[1]);new Database(':memory:').close()", join(stage, 'node_modules/better-sqlite3')], 10_000);
-        const packageTreeSha256 = await packageTreeDigest(join(stage, 'node_modules/@hivemagnus/ardent'));
+        const packageTreeSha256 = await packageTreeDigest(packageDir(stage, staged.name));
         await writeFile(join(stage, 'package-receipt.json'), `${JSON.stringify({
-            schemaVersion: 1, name: '@hivemagnus/ardent', version: staged.version, sha256: staged.sha256, packageTreeSha256,
+            schemaVersion: 1, name: staged.name, version: staged.version, sha256: staged.sha256, packageTreeSha256,
         })}\n`, { mode: 0o644 });
         if (priorInfo) {
             await rename(root.install, previous);
@@ -426,7 +455,7 @@ async function createProfile(root, profile, body) {
         if (current.config.api.port === input.api_port)
             throw new Error(`API port is already assigned to profile ${name}`);
     }
-    const script = join(root.install, 'node_modules/@hivemagnus/ardent/dist/cli.js');
+    const script = await installedCli(root.install);
     const metadata = await lstat(script);
     if (!metadata.isFile() || metadata.isSymbolicLink())
         throw new Error('Installed Ardent CLI is unsafe');
@@ -453,7 +482,7 @@ async function importHermesProfile(root, profile, body) {
     const sourceInfo = await lstat(source);
     if (!sourceInfo.isDirectory() || sourceInfo.isSymbolicLink())
         throw new Error('Hermes source home is unsafe');
-    const script = join(root.install, 'node_modules/@hivemagnus/ardent/dist/cli.js');
+    const script = await installedCli(root.install);
     const scriptInfo = await lstat(script);
     if (!scriptInfo.isFile() || scriptInfo.isSymbolicLink())
         throw new Error('Installed Ardent CLI is unsafe');

package/dist/executors/ardent-packages.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_ARDENT_PACKAGE = "@hivemagnus/ardent";
+/**
+ * npm package names the agent accepts as the Ardent runtime, in preference
+ * order. `MAGNUS_AGENT_ARDENT_PACKAGES` (comma-separated scoped names) lets a
+ * node keep managing an Ardent build published under another scope.
+ */
+export declare function ardentPackageNames(value?: string | undefined): string[];
+//# sourceMappingURL=ardent-packages.d.ts.map

package/dist/executors/ardent-packages.js

@@ -0,0 +1,16 @@
+export const DEFAULT_ARDENT_PACKAGE = '@hivemagnus/ardent';
+const scopedPackageName = /^@[a-z0-9][a-z0-9._-]{0,99}\/[a-z0-9][a-z0-9._-]{0,99}$/;
+/**
+ * npm package names the agent accepts as the Ardent runtime, in preference
+ * order. `MAGNUS_AGENT_ARDENT_PACKAGES` (comma-separated scoped names) lets a
+ * node keep managing an Ardent build published under another scope.
+ */
+export function ardentPackageNames(value = process.env['MAGNUS_AGENT_ARDENT_PACKAGES']) {
+    if (value === undefined || value.trim() === '')
+        return [DEFAULT_ARDENT_PACKAGE];
+    const names = value.split(',').map(item => item.trim()).filter(Boolean);
+    if (!names.length || names.some(name => !scopedPackageName.test(name)))
+        throw new Error('MAGNUS_AGENT_ARDENT_PACKAGES must list scoped npm package names such as @scope/ardent');
+    return [...new Set(names)];
+}
+//# sourceMappingURL=ardent-packages.js.map

package/dist/executors/managed-scheduler.d.ts

@@ -110,11 +110,11 @@ export declare const schedulerSourceSettlementSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type SchedulerSourceSettlement = z.infer<typeof schedulerSourceSettlementSchema>;
 export declare const schedulerSourceSettlementReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
     expiresAt: z.ZodNumber;
     nodeId: z.ZodString;
     count: z.ZodNumber;
     kind: z.ZodString;
-    version: z.ZodLiteral<1>;
     nodeFqdn: z.ZodString;
     disposition: z.ZodEnum<{
         effects_verified: "effects_verified";
@@ -138,11 +138,11 @@ export declare function schedulerSourceSettlementReceiptPayload(value: Omit<Sche
     replayed: boolean;
 }): string;
 declare const legacySettlementReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
     expiresAt: z.ZodNumber;
     nodeId: z.ZodString;
     count: z.ZodNumber;
     kind: z.ZodString;
-    version: z.ZodLiteral<1>;
     nodeFqdn: z.ZodString;
     disposition: z.ZodEnum<{
         effects_verified: "effects_verified";
@@ -194,11 +194,11 @@ export declare class ManagedScheduler {
             count: number;
         }[];
         settlements: {
+            version: 1;
             expiresAt: number;
             nodeId: string;
             count: number;
             kind: string;
-            version: 1;
             nodeFqdn: string;
             disposition: "effects_verified" | "no_effect_verified";
             evidenceSha256: string;
@@ -213,11 +213,11 @@ export declare class ManagedScheduler {
             receiptSignature: string;
         }[];
         legacySettlements: {
+            version: 1;
             expiresAt: number;
             nodeId: string;
             count: number;
             kind: string;
-            version: 1;
             nodeFqdn: string;
             disposition: "effects_verified" | "no_effect_verified";
             evidenceSha256: string;
@@ -240,11 +240,11 @@ export declare class ManagedScheduler {
     settlementReceipt(decisionId: string): Promise<SchedulerSourceSettlementReceipt | z.infer<typeof legacySettlementReceiptSchema> | undefined>;
     settleForeignSource(raw: SchedulerSourceSettlement, signReceipt: (payload: Omit<SchedulerSourceSettlementReceipt, 'receiptSignature'>) => string): Promise<{
         receipt: {
+            version: 1;
             expiresAt: number;
             nodeId: string;
             count: number;
             kind: string;
-            version: 1;
             nodeFqdn: string;
             disposition: "effects_verified" | "no_effect_verified";
             evidenceSha256: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/magnus-agent",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Magnus node agent: a small daemon that enrolls a Linux host with a magnus-server and runs authenticated health, command, cron, file and skill management, with optional Hermes Agent, Codex and Ardent management.",
   "keywords": [
     "magnus",
@@ -55,19 +55,19 @@
   },
   "dependencies": {
     "@hono/node-server": "^2.1.5",
-    "dotenv": "^17.3.1",
-    "hono": "^4.13.7",
-    "ky": "^1.7.5",
+    "dotenv": "^18.0.9",
+    "hono": "^4.13.14",
+    "ky": "^2.2.0",
     "nanoid": "^5.1.16",
-    "tar-stream": "3.2.1",
+    "tar-stream": "3.2.2",
     "undici": "^7.30.1",
     "yaml": "^2.9.1",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@types/node": "^22.10.0",
-    "@types/tar-stream": "^3.1.4",
-    "tsx": "^4.19.4",
+    "@types/node": "^22.20.5",
+    "@types/tar-stream": "^3.1.5",
+    "tsx": "^4.23.15",
     "typescript": "^5.8.3",
     "vitest": "^4.1.12"
   }