@camstack/server 1.2.93 → 1.2.95

package/dist/agent/addon-scan.js

@@ -0,0 +1,131 @@
+"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.BUILTINS_PACKAGE = void 0;
+exports.resolveAddonPackageDirs = resolveAddonPackageDirs;
+exports.planAgentAddonScan = planAgentAddonScan;
+/**
+ * Which directories the agent scans for addons — decided as pure data.
+ *
+ * ── The single-copy collapse, finally on the agent ─────────────────────────
+ * The hub stopped loading framework builtins from a physical
+ * `<addonsDir>/@camstack/system` on 2026-07-18: it loads them from the ACTIVE
+ * CLOSURE it is itself running (`addon-registry.service.ts`, `loadFromAddonDir`
+ * on the closure dir, then `loadFromDirectory(addonsDir, ['@camstack/system'])`
+ * so the copy is skipped). The reason is in that file's comment — *"that copy
+ * drifted because no update channel refreshed it"*.
+ *
+ * The agent never got the change, and drifted exactly as predicted. Measured
+ * 2026-08-11: little-unraid carried `@camstack/system@1.2.61` and macmini
+ * `1.2.62` in their addon roots while both ran a `1.2.78` closure. Nothing
+ * refreshed them, because `seedBuiltinsFromClosure` (now deleted) only wrote
+ * the copy when it was ABSENT — a self-heal that guaranteed a copy existed and
+ * never that it was current. It also contradicted
+ * `AddonInstaller.shouldSkipClosureProvidedSeed`, which already refused to
+ * plant that copy for this very reason.
+ *
+ * ── Why the skip is correctness, not tidiness ──────────────────────────────
+ * `AddonLoader` keys its map on `declaration.id`, so loading the closure AND a
+ * stale copy through one loader is not a duplicate — it is LAST-LOAD-WINS. The
+ * builtins a node runs would depend on directory iteration order. The copy must
+ * be skipped, not merely deprioritized.
+ *
+ * ── The fallback ──────────────────────────────────────────────────────────
+ * If the closure cannot be resolved, the copy is NOT skipped and the node boots
+ * from it. In a running agent this is near-impossible — `agent/main.ts`
+ * statically imports `@camstack/system`, so if the process exists the walk-up
+ * resolves — but a node with neither source must fail through the D87 guard
+ * (`assertRequiredInfraResolved`, which names every missing required cap),
+ * never through a silent "no addon packages found" early return.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** The framework builtins package. Loaded from the closure, never from a copy. */
+exports.BUILTINS_PACKAGE = '@camstack/system';
+function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every installed addon package under `addonsDir`, minus `skipPackages`.
+ *
+ * Matching mirrors `AddonLoader.loadFromDirectory`'s skip list exactly —
+ * `<scope>/<name>` for a scoped directory, the bare name for a flat one — so
+ * the hub and the agent exclude the same thing given the same list.
+ */
+function resolveAddonPackageDirs(addonsDir, skipPackages = []) {
+    const dirs = [];
+    if (!fs.existsSync(addonsDir))
+        return dirs;
+    const skip = new Set(skipPackages);
+    for (const name of fs.readdirSync(addonsDir)) {
+        const full = path.join(addonsDir, name);
+        if (name.startsWith('@') && isDir(full)) {
+            // Scoped packages: @camstack/addon-xyz
+            for (const sub of fs.readdirSync(full)) {
+                const subFull = path.join(full, sub);
+                if (skip.has(`${name}/${sub}`))
+                    continue;
+                if (isDir(subFull) && fs.existsSync(path.join(subFull, 'package.json'))) {
+                    dirs.push(subFull);
+                }
+            }
+        }
+        else if (isDir(full) && fs.existsSync(path.join(full, 'package.json'))) {
+            if (skip.has(name))
+                continue;
+            dirs.push(full);
+        }
+    }
+    return dirs;
+}
+/**
+ * The ordered directory list `bootCoreAddons` loads, closure first.
+ *
+ * `closureSystemDir` is `resolveHubClosurePackageDir(BUILTINS_PACKAGE)` — null
+ * only when the builtins are not resolvable from the running closure at all.
+ */
+function planAgentAddonScan(addonsDir, closureSystemDir) {
+    if (closureSystemDir === null) {
+        // No closure copy: fall back to whatever is on disk, including the
+        // addon-root builtins, rather than booting with no infra at all.
+        return resolveAddonPackageDirs(addonsDir);
+    }
+    return [closureSystemDir, ...resolveAddonPackageDirs(addonsDir, [exports.BUILTINS_PACKAGE])];
+}

package/dist/agent/main.js

@@ -47,7 +47,8 @@ const agent_update_service_js_1 = require("./agent-update-service.js");
 const server_management_provider_js_1 = require("../api/core/server-management.provider.js");
 const infra_boot_guard_js_1 = require("./infra-boot-guard.js");
 const infra_boot_plan_js_1 = require("./infra-boot-plan.js");
-const builtins_seed_js_1 = require("./builtins-seed.js");
+const package_dir_utils_js_1 = require("../core/addon/package-dir-utils.js");
+const addon_scan_js_1 = require("./addon-scan.js");
 const agent_service_js_1 = require("./agent-service.js");
 const agent_group_runner_js_1 = require("./agent-group-runner.js");
 const register_agent_cap_dispatch_js_1 = require("./register-agent-cap-dispatch.js");
@@ -769,13 +770,21 @@ async function startAgent(configPath) {
 // Core infra addons to load on agent — all infra including log-destination (hub-forwarder)
 const AGENT_INFRA = system_1.INFRA_CAPABILITIES;
 async function bootCoreAddons(broker, config, registry, loadedAddons, loggerFactory) {
-    // Self-heal FIRST: a missing builtins package is answerable from the
-    // running closure (see `builtins-seed.ts`) — without this, the D87 guard
-    // below turns a recoverable gap into a crash-loop.
-    (0, builtins_seed_js_1.seedBuiltinsFromClosure)(config.addonsDir);
-    // Scan every installed addon package — infra providers may live outside
-    // `@camstack/system` (e.g. `@camstack/addon-platform-probe-native`).
-    const packageDirs = resolveAddonPackageDirs(config.addonsDir);
+    // Builtins come from the CLOSURE this process is running, exactly as the hub
+    // has done since 2026-07-18 — never from a `<addonsDir>/@camstack/system`
+    // copy, which nothing refreshes and which therefore drifts (both agents were
+    // 17 versions behind on 2026-08-11). `planAgentAddonScan` owns the decision
+    // and the fallback; see `addon-scan.ts`. Non-framework infra providers
+    // (e.g. `@camstack/addon-platform-probe-native`) still come from the scan.
+    const closureSystemDir = (0, package_dir_utils_js_1.resolveHubClosurePackageDir)(addon_scan_js_1.BUILTINS_PACKAGE);
+    if (closureSystemDir === null) {
+        // Louder than the hub's warn: on an agent the builtins ARE the infra, so
+        // this is pre-fatal. Boot continues to the D87 guard, which names every
+        // required cap it could not resolve.
+        console.error(`[Agent] ${addon_scan_js_1.BUILTINS_PACKAGE} not resolvable from the running closure — ` +
+            'falling back to the addon-root copy, if there is one');
+    }
+    const packageDirs = (0, addon_scan_js_1.planAgentAddonScan)(config.addonsDir, closureSystemDir);
     if (packageDirs.length === 0) {
         console.warn('[Agent] No addon packages found — running without infrastructure addons');
         return;
@@ -876,7 +885,13 @@ async function bootCoreAddons(broker, config, registry, loadedAddons, loggerFact
 // Phase 1.5: Load cluster-capable addon packages
 // ---------------------------------------------------------------------------
 async function loadClusterCapableAddons(broker, config, capabilityRegistry, loadedAddons) {
-    const addonPackageDirs = resolveAddonPackageDirs(config.addonsDir);
+    // Builtins are in-process infra, never group-spawned, and they come from the
+    // closure — so the addon-root copy is skipped here too. Leaving it in would
+    // import a stale entry module during the scan below, which is the whole thing
+    // the single-copy collapse removes. The closure dir is deliberately NOT added:
+    // adding it would newly expose `hub-forwarder` / `platform-probe` (the only
+    // builtins carrying `execution`) as spawn candidates.
+    const addonPackageDirs = (0, addon_scan_js_1.resolveAddonPackageDirs)(config.addonsDir, systemSkipList());
     if (addonPackageDirs.length === 0)
         return;
     // ── Phase 0 (cross-package): collect every group-eligible addon
@@ -974,7 +989,9 @@ async function loadDeployedAddons(broker, addonsDir, dataDir, loadedAddons, stor
     // the agent MAIN thread is what wedged `$agent.reload` and dropped the node
     // from topology. A group-runner addon only needs its declaration to be
     // (re)dispatched to a subprocess, which loads the real module itself.
-    const packageDirs = resolveAddonPackageDirs(addonsDir);
+    // Same skip: a `$agent.deploy` of `@camstack/system` still lands bytes in the
+    // addon root, but a reload must not adopt them over the closure.
+    const packageDirs = (0, addon_scan_js_1.resolveAddonPackageDirs)(addonsDir, systemSkipList());
     const groupCandidates = [];
     // Dirs holding a deployable NON-group addon — and ONLY these — need the
     // importing loader. None exist under the default `hub-only` placement
@@ -1118,36 +1135,14 @@ function readAgentVersion() {
     }
     return 'unknown';
 }
-/** Check if path is a directory (follows symlinks) */
-function isDir(p) {
-    try {
-        return fs.statSync(p).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-/** Scan addonsDir for addon packages (scoped and unscoped, follows symlinks) */
-function resolveAddonPackageDirs(addonsDir) {
-    const dirs = [];
-    if (!fs.existsSync(addonsDir))
-        return dirs;
-    for (const name of fs.readdirSync(addonsDir)) {
-        const full = path.join(addonsDir, name);
-        if (name.startsWith('@') && isDir(full)) {
-            // Scoped packages: @camstack/addon-xyz
-            for (const sub of fs.readdirSync(full)) {
-                const subFull = path.join(full, sub);
-                if (isDir(subFull) && fs.existsSync(path.join(subFull, 'package.json'))) {
-                    dirs.push(subFull);
-                }
-            }
-        }
-        else if (isDir(full) && fs.existsSync(path.join(full, 'package.json'))) {
-            dirs.push(full);
-        }
-    }
-    return dirs;
+/**
+ * Skip the addon-root builtins copy — but ONLY when the closure can supply
+ * them. Same condition `planAgentAddonScan` applies, kept in one place so the
+ * infra scan and the two deployable-addon scans can never disagree about which
+ * copy is authoritative.
+ */
+function systemSkipList() {
+    return (0, package_dir_utils_js_1.resolveHubClosurePackageDir)(addon_scan_js_1.BUILTINS_PACKAGE) === null ? [] : [addon_scan_js_1.BUILTINS_PACKAGE];
 }
 // ---------------------------------------------------------------------------
 // E1 helper — agent-local UDS child manifest adaptation

package/dist/api/core/cap-providers.js

@@ -1176,14 +1176,24 @@ function isHubNode(nodeId) {
  * agent reports its addon roster (id + status + version + packageName);
  * we keep only entries that carry both a package name and a version so
  * the hub can diff them against npm.
+ *
+ * `@camstack/system` is KEPT, and it is one of the most important entries here.
+ * On an agent, `addons/@camstack/system` is the only copy of the builtin infra
+ * ([D87](../../../../docs/decisions/adr-0087.md)), so a pending update on it is
+ * a true, actionable signal: the node's infra is behind the closure it runs
+ * against. Both agents sat 17 versions behind that way until 2026-08-11. Do not
+ * filter it out to make the list look clean — the number reaching zero is the
+ * point of the number.
  */
 async function fetchAgentInstalledPackages(broker, nodeId) {
     const status = await broker.call('$agent.status', {}, { nodeID: nodeId, timeout: 5_000 });
     const out = [];
     for (const a of status.addons ?? []) {
-        if (typeof a.packageName === 'string' && typeof a.version === 'string') {
-            out.push({ name: a.packageName, version: a.version });
-        }
+        if (typeof a.packageName !== 'string' || typeof a.version !== 'string')
+            continue;
+        if ((0, addon_package_service_js_1.isFrameworkPackage)(a.packageName))
+            continue;
+        out.push({ name: a.packageName, version: a.version });
     }
     return out;
 }
@@ -1253,6 +1263,22 @@ function buildAddonsProvider(ar, ps, ls, moleculer, configService, ctx) {
                 }
                 return { success: false, error: task?.error ?? 'update failed', jobId };
             }
+            // `@camstack/system` DELIBERATELY travels this way to an agent, and it is
+            // the only way it can. On the hub, `addons/@camstack/system` is a shadow
+            // of the closure; on an AGENT it is THE ONLY COPY of the builtin infra —
+            // `bootCoreAddons` scans the addon root and nothing else, and the image
+            // seed excludes the framework set on purpose ([D87](../../../../docs/decisions/adr-0087.md)).
+            // Removing it on 2026-08-07 left the node with no `filesystem-storage`,
+            // `sqlite-settings`, `storage-orchestrator`, `hub-forwarder`,
+            // `metrics-native` or `platform-probe`, and the outage was unobservable
+            // because the log shipper was in the same package.
+            //
+            // So do NOT add a framework guard here. A 2026-08-11 attempt to do so read
+            // the launcher's `resolved @camstack/system@… from <activeRoot>` line as
+            // proof that nothing loads the addon-root copy. That line answers which
+            // copy the LAUNCHER resolves for its own imports — a different consumer
+            // from `bootCoreAddons`. Same trap D45 names: a version is a property of a
+            // path, and a path is only evidence about the consumer that reads it.
             // Agent target: the hub packs the resolved version and ships the
             // tarball over `$agent.deploy` — the agent has no npm runtime.
             // The reload re-instantiates the changed package's addons; for a large
@@ -1349,12 +1375,30 @@ function buildAddonsProvider(ar, ps, ls, moleculer, configService, ctx) {
             return { success: true };
         },
         // ── Lifecycle job engine ─────────────────────────────────────────
-        startJob: async (input) => lifecycleRunner.startJob({
-            kind: input.kind,
-            targets: input.targets,
-            nodeIds: input.nodeIds,
-            createdBy: lifecycleCreatedBy,
-        }),
+        startJob: async (input) => {
+            // The engine is HUB-LOCAL: `StartJobInput.nodeIds` is declared
+            // "reserved for future cluster jobs" and nothing reads it. Passing an
+            // agent id therefore used to apply every target to the HUB while the
+            // job, its per-task `nodeId` and the UI all reported the agent — so
+            // "Update all" on a selected agent silently updated the wrong node and
+            // left the agent pending forever. That is how two agents sat at 8
+            // pending addons across several sessions (2026-08-11). Refuse instead:
+            // an agent converges one package at a time through `updatePackage`,
+            // which has a real `$agent.deploy` path.
+            const offNode = (input.nodeIds ?? []).filter((id) => !isHubNode(id));
+            if (offNode.length > 0) {
+                throw new server_1.TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: `The lifecycle job engine is hub-local; it cannot target ${offNode.join(', ')}. Update an agent's packages via updatePackage({ nodeId }).`,
+                });
+            }
+            return lifecycleRunner.startJob({
+                kind: input.kind,
+                targets: input.targets,
+                nodeIds: input.nodeIds,
+                createdBy: lifecycleCreatedBy,
+            });
+        },
         getJob: async (input) => lifecycleRunner.getJob(input.jobId),
         listJobs: async (input) => lifecycleRunner.listJobs({ activeOnly: input.activeOnly }),
         cancelJob: async (input) => lifecycleRunner.cancelJob(input.jobId),

package/dist/api/trpc/generated-cap-mounts.js

@@ -2,7 +2,7 @@
 // AUTO-GENERATED by scripts/generate-cap-mounts.ts — DO NOT EDIT
 // Re-run: npx tsx scripts/generate-cap-mounts.ts
 //
-// Mounted: 145    Skipped (legacy): 3
+// Mounted: 146    Skipped (legacy): 3
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LEGACY_SHAPE_SKIP = void 0;
 exports.mountAllCaps = mountAllCaps;
@@ -406,6 +406,8 @@ function mountAllCaps(services) {
             const entries = reg.getCollectionEntries('storage-evictable');
             return entries[0]?.[1] ?? null;
         }, remoteCapProxy),
+        storageMigration: (0, generated_cap_routers_js_1.createCapRouter_storageMigration)((_ctx) => reg?.getSingleton('storage-migration') ??
+            null, remoteCapProxy),
         storageProvider: (0, generated_cap_routers_js_1.createCapRouter_storageProvider)((_ctx, addonId) => {
             if (!reg)
                 return null;