@camstack/agent 1.0.7 → 1.1.0

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import { createRequire as __cr } from 'node:module'; const require = globalThis.require ?? __cr(import.meta.url);
 import {
   startAgent
-} from "./chunk-GM2IV7NO.mjs";
+} from "./chunk-PFQZTXGW.mjs";
 
 // src/cli.ts
 import * as os from "os";

package/dist/index.d.ts

@@ -75,11 +75,27 @@ interface AgentServiceDeps {
      * presenting a matching `clusterSecretHash`. (Cluster-secret gate.)
      */
     readonly expectedClusterSecretHash?: string;
+    /** Pull-install a published addon from npm/GHCR (wired by agent-bootstrap). */
+    readonly installFromNpm?: (packageName: string, version: string) => Promise<void>;
 }
 declare function createAgentService(deps: AgentServiceDeps): ServiceSchema;
 
 declare function startAgent(configPath?: string): Promise<void>;
 
+/**
+ * Discriminated hub connection state surfaced by the agent status API.
+ *
+ * - `connected`      — hub node is in the Moleculer registry (available).
+ * - `searching`      — discovery mode active, no hub found yet.
+ * - `disconnected`   — direct address configured but hub not in registry.
+ * - `secret-mismatch`— `$hub.registerNode` was rejected with a cluster-secret error.
+ *
+ * `registering` (transport up but registerNode not yet acked) is not
+ * currently deterministic from the broker registry alone — it would require
+ * a tighter integration with the retry loop. Omitted until a clean signal
+ * exists; the brief gap is invisible at 3 s poll rate.
+ */
+type HubConnectionState = 'connected' | 'searching' | 'disconnected' | 'secret-mismatch';
 interface AgentHttpConfig {
     readonly port: number;
     readonly nodeId: string;
@@ -87,6 +103,14 @@ interface AgentHttpConfig {
     readonly configPath: string;
     /** Called when the UI requests a reconnect (hub/secret changed). */
     readonly onReconnect?: () => Promise<void>;
+    /**
+     * Optional getter for the current hub connection state. When provided,
+     * the status endpoint uses this to surface a richer discriminated state
+     * instead of the legacy boolean `hubConnected`. The bootstrap wires this
+     * to expose `secret-mismatch` which is not derivable from the broker
+     * registry alone.
+     */
+    readonly getHubConnectionState?: () => HubConnectionState;
 }
 declare function createAgentHttpServer(getBroker: () => ServiceBroker, config: AgentHttpConfig): Promise<FastifyInstance>;
 declare function startAgentHttpServer(getBroker: () => ServiceBroker, config: AgentHttpConfig): Promise<void>;

package/dist/index.js

@@ -176,6 +176,29 @@ async function applyDeployedBundle(input) {
   return { addonDir: liveDir };
 }
 
+// src/fetch-bundle-from-hub.ts
+var import_node_crypto2 = require("crypto");
+var import_undici = require("undici");
+async function fetchBundleFromHub(opts) {
+  const authHeader = { Authorization: `Bearer ${opts.token}` };
+  const res = opts.fetchImpl ? await opts.fetchImpl(opts.url, { headers: authHeader }) : await (0, import_undici.fetch)(opts.url, {
+    headers: authHeader,
+    dispatcher: new import_undici.Agent({ connect: { rejectUnauthorized: false } })
+  });
+  if (!res.ok) {
+    throw new Error(`bundle fetch failed: HTTP ${res.status}`);
+  }
+  const buffer = Buffer.from(await res.arrayBuffer());
+  if (buffer.length !== opts.bytes) {
+    throw new Error(`bundle bytes mismatch: expected ${opts.bytes}, got ${buffer.length}`);
+  }
+  const sha = (0, import_node_crypto2.createHash)("sha256").update(buffer).digest("hex");
+  if (sha !== opts.sha256) {
+    throw new Error(`bundle sha256 mismatch: expected ${opts.sha256}, got ${sha}`);
+  }
+  return buffer;
+}
+
 // src/agent-service.ts
 var deploySwapLogger = {
   info: (msg) => console.log(`[Agent] ${msg}`),
@@ -209,6 +232,28 @@ async function withTimeout(p, ms, fallback) {
   }
 }
 var METRICS_SNAPSHOT_TIMEOUT_MS = 2e3;
+function resolveDeployAction(seam) {
+  return async (params) => {
+    const { addonId, source, bundle } = params;
+    if (source && (0, import_system.isAddonDeploySource)(source)) {
+      if (source.kind === "npm") {
+        await seam.installFromNpm(addonId, source.version);
+        return { success: true, addonId };
+      }
+      const buf2 = await seam.fetchBundle(source);
+      const { addonDir: addonDir2 } = await seam.applyBundle(buf2);
+      seam.onApplied(addonDir2);
+      return { success: true, addonId, path: addonDir2 };
+    }
+    if (bundle === void 0) {
+      throw new Error("$agent.deploy: no source descriptor and no legacy bundle provided");
+    }
+    const buf = typeof bundle === "string" ? Buffer.from(bundle, "base64") : bundle;
+    const { addonDir } = await seam.applyBundle(buf);
+    seam.onApplied(addonDir);
+    return { success: true, addonId, path: addonDir };
+  };
+}
 function readHubAddressFromConfig(configPath) {
   if (!configPath) return null;
   try {
@@ -381,8 +426,7 @@ function createAgentService(deps) {
       deploy: {
         handler: async (ctx) => {
           const { params } = ctx;
-          const { addonId, bundle } = params;
-          const bufferData = typeof bundle === "string" ? Buffer.from(bundle, "base64") : bundle;
+          const { addonId, source, bundle } = params;
           const { execFile } = await import("child_process");
           const { promisify } = await import("util");
           const execFileAsync = promisify(execFile);
@@ -400,17 +444,37 @@ function createAgentService(deps) {
               }
             }
           };
-          const { addonDir } = await applyDeployedBundle({
-            addonsDir: deps.addonsDir,
-            addonId,
-            bundle: bufferData,
-            extract,
-            logger: deploySwapLogger
-          });
-          for (const declId of readDeployedAddonIds(addonDir)) {
-            deps.loadedAddons.delete(declId);
-          }
-          return { success: true, addonId, path: addonDir };
+          const seam = {
+            installFromNpm: (pkg, v) => {
+              if (!deps.installFromNpm) {
+                throw new Error("npm deploy source unsupported on this agent");
+              }
+              return deps.installFromNpm(pkg, v);
+            },
+            applyBundle: (buf) => applyDeployedBundle({
+              addonsDir: deps.addonsDir,
+              addonId,
+              bundle: buf,
+              extract,
+              logger: deploySwapLogger
+            }),
+            fetchBundle: (s) => fetchBundleFromHub(s),
+            // Evict every addon DECLARATION id this package contributes
+            // from `loadedAddons` so the follow-up `$agent.reload` actually
+            // re-instantiates it. `loadDeployedAddons` skips any addon
+            // still present in `loadedAddons`; without this eviction a
+            // redeploy would leave the agent pinned to the pre-update
+            // version. The `deploy` param `addonId` is the PACKAGE name
+            // (used only as the on-disk dir), whereas `loadedAddons` is
+            // keyed by the addon DECLARATION id — they differ for scoped
+            // packages, so we read the extracted manifest to bridge them.
+            onApplied: (addonDir) => {
+              for (const declId of readDeployedAddonIds(addonDir)) {
+                deps.loadedAddons.delete(declId);
+              }
+            }
+          };
+          return resolveDeployAction(seam)({ addonId, source, bundle });
         }
       },
       /**
@@ -554,6 +618,12 @@ function getRegistryNodes(broker) {
     return [];
   }
 }
+function deriveHubConnectionState(nodes, discoveryMode) {
+  const hubInRegistry = nodes.some((n) => n.id === "hub");
+  if (hubInRegistry) return "connected";
+  if (discoveryMode) return "searching";
+  return "disconnected";
+}
 function getEffectiveConfig(configPath, nodeId) {
   const raw = readConfigFile(configPath);
   return {
@@ -585,6 +655,7 @@ async function createAgentHttpServer(getBroker, config) {
     const nodes = getRegistryNodes(broker);
     const hubConnected = nodes.some((n) => n.id === "hub");
     const discoveryMode = !eff.hubAddress;
+    const hubConnectionState = config.getHubConnectionState ? config.getHubConnectionState() : deriveHubConnectionState(nodes, discoveryMode);
     try {
       const status = await broker.call("$agent.status");
       return {
@@ -592,6 +663,7 @@ async function createAgentHttpServer(getBroker, config) {
         name: eff.name,
         hubAddress: eff.hubAddress,
         hubConnected,
+        hubConnectionState,
         discoveryMode,
         hasSecret: eff.hasSecret,
         discoveredNodes: nodes.filter((n) => n.id !== broker.nodeID).map((n) => n.id)
@@ -602,6 +674,7 @@ async function createAgentHttpServer(getBroker, config) {
         name: eff.name,
         hubAddress: eff.hubAddress,
         hubConnected,
+        hubConnectionState,
         discoveryMode,
         hasSecret: eff.hasSecret,
         discoveredNodes: [],
@@ -814,7 +887,7 @@ function narrowParams(raw) {
     deviceId: typeof deviceId === "number" ? deviceId : void 0
   };
 }
-function createAgentCapDispatchService(agentNodeId, agentUdsRegistry, logger) {
+function createAgentCapDispatchService(agentNodeId, agentUdsRegistry, inProcessLookup, logger) {
   return {
     name: import_system2.AGENT_CAP_FWD_SERVICE,
     actions: {
@@ -824,11 +897,15 @@ function createAgentCapDispatchService(agentNodeId, agentUdsRegistry, logger) {
           const { capName, method, args, deviceId } = params;
           const childId = params.childId !== void 0 ? params.childId : agentUdsRegistry.resolveChildId(capName, deviceId);
           if (childId == null) {
+            const ref = inProcessLookup?.(capName) ?? null;
+            if (ref !== null) {
+              return ref.invoke(method, args);
+            }
             logger?.info(
-              `agent ${agentNodeId}: no UDS child for cap "${capName}"${deviceId !== void 0 ? ` (deviceId ${deviceId})` : ""}`
+              `agent ${agentNodeId}: no provider for cap "${capName}"${deviceId !== void 0 ? ` (deviceId ${deviceId})` : ""}`
             );
             throw new Error(
-              `agent ${agentNodeId} has no UDS child for cap "${capName}"${deviceId !== void 0 ? ` (deviceId ${deviceId})` : ""}`
+              `agent ${agentNodeId} has no provider for cap "${capName}"${deviceId !== void 0 ? ` (deviceId ${deviceId})` : ""}`
             );
           }
           const input = {
@@ -845,9 +922,11 @@ function createAgentCapDispatchService(agentNodeId, agentUdsRegistry, logger) {
 }
 
 // src/register-agent-cap-dispatch.ts
-function registerAgentCapDispatch(registrar, agentUdsRegistry, logger) {
+function registerAgentCapDispatch(registrar, agentUdsRegistry, inProcessLookup, logger) {
   if (agentUdsRegistry === void 0) return;
-  registrar.createService(createAgentCapDispatchService(registrar.nodeID, agentUdsRegistry, logger));
+  registrar.createService(
+    createAgentCapDispatchService(registrar.nodeID, agentUdsRegistry, inProcessLookup, logger)
+  );
 }
 
 // src/agent-bootstrap.ts
@@ -913,6 +992,27 @@ async function startAgent(configPath) {
   };
   const loadedAddons = /* @__PURE__ */ new Map();
   const subtree = new import_system3.HubNodeRegistry();
+  let hubConnectionStateOverride = null;
+  function getHubConnectionState() {
+    if (hubConnectionStateOverride !== null) return hubConnectionStateOverride;
+    try {
+      const registry = broker.registry;
+      const nodes = registry?.getNodeList?.({ onlyAvailable: true }) ?? [];
+      if (nodes.some((n) => n.id === "hub")) return "connected";
+    } catch {
+    }
+    const configNow = readConfigFile2(config.configPath);
+    const discoveryMode = typeof configNow.hubAddress !== "string" || configNow.hubAddress.length === 0;
+    return discoveryMode ? "searching" : "disconnected";
+  }
+  function readConfigFile2(p) {
+    if (!fs6.existsSync(p)) return {};
+    try {
+      return JSON.parse(fs6.readFileSync(p, "utf-8"));
+    } catch {
+      return {};
+    }
+  }
   const registerAbortController = new AbortController();
   function buildAgentOwnManifest() {
     const addonCapMap = /* @__PURE__ */ new Map();
@@ -975,6 +1075,7 @@ async function startAgent(configPath) {
         consoleLogger.error(
           "hub registration rejected: cluster secret mismatch \u2014 correct CAMSTACK_CLUSTER_SECRET and restart the agent"
         );
+        hubConnectionStateOverride = "secret-mismatch";
         return;
       }
     });
@@ -1045,7 +1146,10 @@ async function startAgent(configPath) {
       subtree.registerNode(params);
       triggerUpwardRegistration();
     },
-    expectedClusterSecretHash: config.secret ? (0, import_system3.hashClusterSecret)(config.secret) : void 0
+    expectedClusterSecretHash: config.secret ? (0, import_system3.hashClusterSecret)(config.secret) : void 0,
+    installFromNpm: async (pkg, version) => {
+      await installer.install(pkg, version);
+    }
   });
   broker.createService(agentServiceSchema);
   const agentTcpPort = (0, import_system3.deriveAgentListenPort)(broker.nodeID);
@@ -1104,7 +1208,21 @@ async function startAgent(configPath) {
     agentParentUdsPath
   );
   broker.createService(processServiceSchema);
-  registerAgentCapDispatch(broker, agentUdsRegistry, consoleLogger);
+  const agentInProcessLookup = (capName) => {
+    const provider = capabilityRegistry.getSingleton(capName);
+    if (provider === null || provider === void 0) return null;
+    return {
+      invoke: (method, args) => {
+        const fn = provider[method];
+        if (typeof fn !== "function") {
+          return Promise.reject(new Error(`method "${method}" not found on cap "${capName}"`));
+        }
+        const result = fn.call(provider, args);
+        return Promise.resolve(result);
+      }
+    };
+  };
+  registerAgentCapDispatch(broker, agentUdsRegistry, agentInProcessLookup, consoleLogger);
   (0, import_system3.registerEventBusService)(broker);
   broker.createService((0, import_system3.createHwAccelService)((0, import_system3.createKernelHwAccel)()));
   await broker.start();
@@ -1131,7 +1249,8 @@ async function startAgent(configPath) {
     nodeId: config.nodeId,
     dataDir: config.dataDir,
     configPath: config.configPath,
-    onReconnect: reconnect
+    onReconnect: reconnect,
+    getHubConnectionState
   });
   await bootCoreAddons(broker, config, capabilityRegistry, loadedAddons, loggerFactory);
   for (const dest of capabilityRegistry.getCollection("log-destination")) {
@@ -1153,6 +1272,9 @@ async function startAgent(configPath) {
   broker.localBus.on("$node.connected", (data) => {
     const node = data.node;
     if (node?.id !== "hub") return;
+    if (hubConnectionStateOverride === "secret-mismatch") {
+      hubConnectionStateOverride = null;
+    }
     triggerUpwardRegistration();
     if (hubReachableFired) return;
     hubReachableFired = true;