@camstack/server 1.2.676 → 1.2.677

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.677] - 2026-10-28
+
+### Changed
+
+- An agent now keeps its own server closure current: unpaired it follows the npm latest, paired it follows the hub's version, checked at boot and every 6 hours (turn off with CAMSTACK_AGENT_SELF_UPDATE=off).
+
 ## [1.2.676] - 2026-10-28
 
 ### Fixed

package/dist/agent/agent-hub-registration.js

@@ -50,9 +50,9 @@ function createAgentHubRegistration(opts) {
                     opts.onCertificateRefused?.(err);
             },
         })
-            .then(() => {
+            .then((ack) => {
             opts.log(`[register-node] the hub acked this node's capabilities: ${manifest.addons.length} addon(s), ${bindings} binding(s) (${reason})`);
-            opts.onAcked?.();
+            opts.onAcked?.((0, system_1.hubServerVersionOf)(ack));
         })
             .catch(() => {
             // Aborted: shutting down.

package/dist/agent/agent-self-update.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideAgentSelfUpdate = decideAgentSelfUpdate;
+exports.agentSelfUpdateEnabled = agentSelfUpdateEnabled;
+exports.runAgentSelfUpdate = runAgentSelfUpdate;
+/**
+ * An agent keeps its own `@camstack/server` closure current, with nobody driving it.
+ *
+ * Until now a closure reached an agent only when the HUB called `applyServerUpdate` on it. A
+ * freshly installed desktop agent boots the seed closure baked into the app and, being unpaired,
+ * had no hub to receive a fix from — not even the fix for its own unpaired boot (D857).
+ *
+ * The target version:
+ *  - UNPAIRED: the npm `latest` of `@camstack/server` — there is no hub to follow;
+ *  - PAIRED: the version the HUB runs (carried on the registration ack), never npm latest, so
+ *    the cluster has no hub/agent skew.
+ *
+ * It reuses the one updater (`AgentUpdateService` → stage → `scheduleAgentRestart`, lifecycle =
+ * respawn, D5), never downgrades, and treats a failed read as "unknown", never as "up to date"
+ * (D49, D393): the reason is logged and nothing changes. The cadence is the update-check
+ * constant; there is no retry loop (D3).
+ *
+ * Off switch: `CAMSTACK_AGENT_SELF_UPDATE=off` (or `0`/`false`).
+ */
+const index_js_1 = require("../server-root/index.js");
+function skip(reason, failedRead = false) {
+    return { action: 'skip', reason, failedRead };
+}
+function decideAgentSelfUpdate(input) {
+    if (input.running === null)
+        return skip('the running version is unknown', true);
+    let target;
+    let source;
+    if (input.paired) {
+        if (input.hubVersion === null) {
+            return skip('paired, but the hub version is unknown (no registration ack carrying it yet, or an older hub)', true);
+        }
+        target = input.hubVersion;
+        source = 'hub';
+    }
+    else {
+        if (!input.npmLatest.ok) {
+            return skip(`the registry read failed: ${input.npmLatest.reason}`, true);
+        }
+        target = input.npmLatest.version;
+        source = 'npm-latest';
+    }
+    const order = (0, index_js_1.compareSemver)(target, input.running);
+    if (order === 0)
+        return skip(`already running ${target} (${source})`);
+    if (order < 0)
+        return skip(`target ${target} (${source}) is older than running ${input.running}: never a downgrade`);
+    if (input.pendingVersion === target)
+        return skip(`${target} is already staged, awaiting restart`);
+    return { action: 'stage', version: target, source };
+}
+function agentSelfUpdateEnabled(env) {
+    const raw = env['CAMSTACK_AGENT_SELF_UPDATE']?.trim().toLowerCase();
+    return !(raw === 'off' || raw === '0' || raw === 'false' || raw === 'no');
+}
+/** One self-update pass. Every decision is logged with the versions; it never throws. */
+async function runAgentSelfUpdate(ports) {
+    const { log } = ports;
+    try {
+        if (!ports.enabled()) {
+            log.info('agent self-update: off (CAMSTACK_AGENT_SELF_UPDATE) — nothing checked');
+            return;
+        }
+        const paired = ports.isPaired();
+        const running = ports.runningVersion();
+        const hubVersion = ports.getHubServerVersion();
+        let npmLatest = { ok: false, reason: 'not needed' };
+        let pendingVersion = null;
+        if (!paired) {
+            const check = await ports.checkLatest();
+            pendingVersion = check.pendingVersion;
+            npmLatest =
+                check.error === null && check.latestVersion !== null
+                    ? { ok: true, version: check.latestVersion }
+                    : {
+                        ok: false,
+                        reason: check.error ?? 'the registry returned no version',
+                    };
+        }
+        log.info(`agent self-update: checked (${paired ? 'paired' : 'unpaired'}) running=${running ?? 'unknown'} ` +
+            `hub=${hubVersion ?? 'unknown'} npmLatest=${npmLatest.ok ? npmLatest.version : 'n/a'}`);
+        const decision = decideAgentSelfUpdate({
+            paired,
+            running,
+            npmLatest,
+            hubVersion,
+            pendingVersion,
+        });
+        if (decision.action === 'skip') {
+            const line = `agent self-update: skip — ${decision.reason}`;
+            if (decision.failedRead)
+                log.warn(line);
+            else
+                log.info(line);
+            return;
+        }
+        log.info(`agent self-update: staging ${decision.version} (${decision.source}) over ${running ?? 'unknown'}`);
+        const result = await ports.apply(decision.version);
+        if (result.accepted) {
+            log.info(`agent self-update: applied ${decision.version} (${result.outcome}) — restarting to swap the closure`);
+        }
+        else {
+            log.warn(`agent self-update: ${decision.version} not applied (${result.outcome}): ${result.message}`);
+        }
+    }
+    catch (err) {
+        log.warn(`agent self-update: failed — ${err instanceof Error ? err.message : String(err)}; nothing changed`);
+    }
+}

package/dist/agent/main.js

@@ -57,6 +57,8 @@ const agent_node_certificates_js_1 = require("./agent-node-certificates.js");
 const agent_reconnect_js_1 = require("./agent-reconnect.js");
 const serial_queue_js_1 = require("./serial-queue.js");
 const agent_boot_mode_js_1 = require("./agent-boot-mode.js");
+const agent_self_update_js_1 = require("./agent-self-update.js");
+const update_check_scheduler_js_1 = require("../core/updates/update-check-scheduler.js");
 const agent_infra_capabilities_js_1 = require("./agent-infra-capabilities.js");
 const agent_service_js_1 = require("./agent-service.js");
 const agent_hub_addon_update_js_1 = require("./agent-hub-addon-update.js");
@@ -306,6 +308,9 @@ async function startAgent(configPath) {
     // AbortController for the upward hub registration retry loop — cancelled on
     // agent shutdown so we don't leak the retry loop after stop().
     const registerAbortController = new AbortController();
+    // The hub's `@camstack/server` version from the last `registerNode` ack (agent self-update).
+    let hubServerVersion = null;
+    let selfUpdateOnFirstAck = null;
     /**
      * Build the manifest for the agent's OWN in-process addons (those loaded by
      * bootCoreAddons and loadDeployedAddons that ended up in `loadedAddons` WITH
@@ -395,10 +400,15 @@ async function startAgent(configPath) {
         log: (msg) => console.log(`[Agent] ${msg}`),
         // The hub acked the manifest — the agent reached its registered state.
         // Run the single-copy GC sweep once (first ack only; no-op after).
-        onAcked: () => {
+        onAcked: (ackedHubServerVersion) => {
             if (hubConnectionStateOverride === 'certificate-rejected')
                 hubConnectionStateOverride = null;
+            hubServerVersion = ackedHubServerVersion;
             confirmAgentBootHealthy();
+            // Paired: the first ack is the first moment the hub's version is known.
+            const firstAck = selfUpdateOnFirstAck;
+            selfUpdateOnFirstAck = null;
+            firstAck?.();
         },
         onCertificateRefused: () => {
             if (hubConnectionStateOverride === 'certificate-rejected')
@@ -902,6 +912,43 @@ async function startAgent(configPath) {
         });
     };
     const addonsBooted = (0, agent_boot_mode_js_1.decideAgentBootMode)({ paired: (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath) }) === 'full';
+    // ── Self-update (agent-self-update.ts): keep this closure current with nobody driving it.
+    // Unpaired -> npm latest, at boot; paired -> the hub's version, at the first registration ack.
+    // Then on the update-check cadence (a periodic check, no retry loop). Lifecycle = respawn (D5).
+    const selfUpdatePorts = {
+        enabled: () => (0, agent_self_update_js_1.agentSelfUpdateEnabled)(process.env),
+        isPaired: () => (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath),
+        getHubServerVersion: () => hubServerVersion,
+        runningVersion: () => agentUpdateService.getRunningRootPackage().version,
+        checkLatest: async () => {
+            const check = await agentUpdateService.checkServerUpdate();
+            return {
+                latestVersion: check.latestVersion,
+                error: check.error,
+                pendingVersion: check.pendingVersion ?? null,
+            };
+        },
+        apply: async (version) => {
+            const result = await agentUpdateService.applyServerUpdate({ version });
+            return {
+                accepted: result.accepted,
+                outcome: result.outcome ?? 'unknown',
+                message: result.message,
+            };
+        },
+        log: {
+            info: (message) => consoleLogger.info(message, { tags: { nodeId: config.nodeId } }),
+            warn: (message) => consoleLogger.warn(message, { tags: { nodeId: config.nodeId } }),
+        },
+    };
+    if ((0, agent_pairing_store_js_1.isAgentPaired)(config.configPath)) {
+        selfUpdateOnFirstAck = () => void (0, agent_self_update_js_1.runAgentSelfUpdate)(selfUpdatePorts);
+    }
+    else {
+        void (0, agent_self_update_js_1.runAgentSelfUpdate)(selfUpdatePorts);
+    }
+    const selfUpdateTimer = setInterval(() => void (0, agent_self_update_js_1.runAgentSelfUpdate)(selfUpdatePorts), update_check_scheduler_js_1.DEFAULT_UPDATE_CHECK_INTERVAL_SECONDS * 1000);
+    selfUpdateTimer.unref();
     const localPairing = (0, agent_pairing_local_js_1.createLocalPairingAnnouncer)(config.dataDir, consoleLogger);
     const pairing = new system_1.AgentPairing({
         nodeId: config.nodeId,

package/dist/core/moleculer/hub-server-version.js

@@ -0,0 +1,68 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readServerVersionFrom = readServerVersionFrom;
+exports.readHubServerVersion = readHubServerVersion;
+/**
+ * The `@camstack/server` version this hub runs, carried on every `$hub.registerNode` ack so an
+ * agent can align its own closure to it (agent self-update). Read once from the running
+ * package.json (`dist/core/moleculer/` -> `../../../package.json`); null when it cannot be read —
+ * the ack then simply omits it and the agent says "hub version unknown" instead of guessing.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const index_js_1 = require("../../server-root/index.js");
+function readServerVersionFrom(packageJsonPath) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        if (typeof raw !== 'object' || raw === null)
+            return null;
+        const name = Reflect.get(raw, 'name');
+        const version = Reflect.get(raw, 'version');
+        if (name !== index_js_1.SERVER_ROOT_PACKAGE_NAME)
+            return null;
+        return typeof version === 'string' && version.length > 0 ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+let cached;
+function readHubServerVersion() {
+    if (cached === undefined) {
+        cached = readServerVersionFrom(path.resolve(__dirname, '..', '..', '..', 'package.json'));
+    }
+    return cached;
+}

package/dist/core/moleculer/moleculer.service.js

@@ -11,6 +11,7 @@ const core_cap_bridge_js_1 = require("../../api/trpc/core-cap-bridge.js");
 const agent_readiness_pull_js_1 = require("./agent-readiness-pull.js");
 const agent_registration_request_js_1 = require("./agent-registration-request.js");
 const hub_mesh_guard_js_1 = require("./hub-mesh-guard.js");
+const hub_server_version_js_1 = require("./hub-server-version.js");
 const cap_call_fn_js_1 = require("./cap-call-fn.js");
 const cap_route_authority_js_1 = require("./cap-route-authority.js");
 class MoleculerService {
@@ -270,6 +271,8 @@ class MoleculerService {
             onUnregisterNode: (nodeId) => {
                 this.removeNodeFromRegistry(nodeId);
             },
+            // The ack carries the hub's closure version so an agent aligns to it (agent self-update).
+            getServerVersion: () => (0, hub_server_version_js_1.readHubServerVersion)(),
             // D857: a node registers only itself, and only with a certificate identity.
             meshIdentity: this.meshGuard.gate,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.676",
+  "version": "1.2.677",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -60,7 +60,7 @@
     "@camstack/addon-post-analysis": "1.2.649",
     "@camstack/develop": "0.1.38",
     "@camstack/sdk": "1.2.154",
-    "@camstack/system": "1.2.507",
+    "@camstack/system": "1.2.508",
     "@camstack/types": "1.2.436",
     "@camstack/ui-library": "1.2.345",
     "@fastify/compress": "^9.0.0",