@camstack/server 1.1.75 → 1.2.0

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

@@ -0,0 +1,184 @@
+"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.AgentUpdateService = exports.AGENT_RESTART_GRACE_MS = exports.AGENT_RUNTIME_ADDON_ID = void 0;
+exports.isRunningInContainer = isRunningInContainer;
+exports.resolveAgentPackageJsonPath = resolveAgentPackageJsonPath;
+exports.scheduleAgentRestart = scheduleAgentRestart;
+exports.agentRuntimeManifestEntry = agentRuntimeManifestEntry;
+/**
+ * AgentUpdateService — agent-side adapter over the SHARED `RootUpdateService`
+ * (`@camstack/node-root`, bundled into the `@camstack/server` dist by tsup).
+ * Post-consolidation the agent boots the SAME `@camstack/server` closure as
+ * the hub (via `CAMSTACK_ROLE=agent`), so this service stages/applies
+ * `@camstack/server` closures in `<agentDataDir>/server-root/`, applied on
+ * restart by the shared STARTER (single-copy in-place swap — no probation,
+ * no auto-rollback).
+ *
+ * The engine lives in the shared core; this module binds the agent's
+ * parameters, which differ from the hub only in the RESTART seam:
+ *   - spec `@camstack/server` + `dist/launcher.js` (the single root spec)
+ *   - env markers `CAMSTACK_SERVER_{BOOT_MODE,ACTIVE_VERSION}` +
+ *     `CAMSTACK_SEED_SERVER_DIR` (written by the shared starter / image) —
+ *     identical to the hub, because the on-disk root is `@camstack/server`
+ *   - restart = graceful self-SIGTERM → the supervisor (docker restart
+ *     policy / Electron main) relaunches → the shared starter swaps the copy
+ *   - confirmBootHealthy = the agent's `$hub.registerNode` reaching its
+ *     acked state (wired in main.ts) — a single-copy GC sweep, no promotion
+ *
+ * Spec: docs/superpowers/specs/2026-07-18-single-framework-copy-collapse-design.md
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const index_js_1 = require("../server-root/index.js");
+const system_exec_npm_js_1 = require("../core/server-update/system-exec-npm.js");
+/**
+ * The synthetic addonId the agent's OWN runtime registers infra providers
+ * under (no addon owns them — the bootstrap does). Appears in the agent's
+ * `$hub.registerNode` manifest so the hub's cap routing can reach the
+ * agent-hosted `server-management` provider via `nodeId` pinning.
+ */
+exports.AGENT_RUNTIME_ADDON_ID = 'agent-runtime';
+/** Grace before the self-SIGTERM so the tRPC reply can flush to the hub. */
+exports.AGENT_RESTART_GRACE_MS = 2_000;
+/**
+ * Best-effort container detection for the restart-policy startup warning
+ * (security review #3). `/.dockerenv` is present in Docker/Podman containers;
+ * this is diagnostic only — never gates any logic.
+ */
+function isRunningInContainer(existsSyncFn) {
+    return existsSyncFn('/.dockerenv');
+}
+/**
+ * Resolve the RUNNING root (`@camstack/server`) package.json. The agent boots
+ * the same `@camstack/server` closure as the hub, whose dist lives at
+ * `<pkg>/dist/*.js`, so `../package.json` is the normal hit; the second
+ * candidate covers a nested layout.
+ */
+function resolveAgentPackageJsonPath(fromDir) {
+    const candidates = [
+        path.resolve(fromDir, '..', 'package.json'),
+        path.resolve(fromDir, '..', '..', 'package.json'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            const raw = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
+            if (raw.name === index_js_1.HUB_ROOT_SPEC.packageName)
+                return candidate;
+        }
+        catch {
+            /* keep searching */
+        }
+    }
+    return candidates[0] ?? path.resolve(fromDir, '..', 'package.json');
+}
+/**
+ * Default restart seam: log, then after a short grace self-deliver SIGTERM so
+ * the bootstrap's graceful shutdown runs (addons stopped, broker stopped,
+ * exit 0) and the container restart policy relaunches into the starter. A
+ * hard exit fallback guards against a wedged shutdown.
+ *
+ * When `dataDir` is given, drop a restart-intent MARKER in the server-root dir
+ * BEFORE the SIGTERM so an external process supervisor (phase 3: the Electron
+ * shell) can tell this INTENTIONAL update/rollback restart apart from a crash
+ * and not penalise its crash-backoff. The docker restart policy ignores the
+ * marker (it relaunches regardless), so this is a no-op there. Best-effort: a
+ * marker-write failure must never block the restart.
+ */
+function scheduleAgentRestart(logger, requestedBy, dataDir) {
+    if (dataDir !== undefined && dataDir.length > 0) {
+        try {
+            (0, index_js_1.writeRestartIntentMarker)((0, index_js_1.serverRootDir)(dataDir), {
+                requestedAtMs: Date.now(),
+                reason: requestedBy,
+            });
+        }
+        catch (err) {
+            logger.warn('failed to write restart-intent marker', {
+                meta: { error: err instanceof Error ? err.message : String(err) },
+            });
+        }
+    }
+    logger.warn('agent restart requested — exiting for supervisor relaunch', {
+        meta: { requestedBy, graceMs: exports.AGENT_RESTART_GRACE_MS },
+    });
+    const grace = setTimeout(() => {
+        process.kill(process.pid, 'SIGTERM');
+        const hard = setTimeout(() => process.exit(0), 15_000);
+        hard.unref();
+    }, exports.AGENT_RESTART_GRACE_MS);
+    grace.unref();
+}
+class AgentUpdateService extends index_js_1.RootUpdateService {
+    constructor(options) {
+        super({
+            spec: index_js_1.HUB_ROOT_SPEC,
+            // The agent's on-disk root IS `@camstack/server` (booted via
+            // CAMSTACK_ROLE=agent by the shared starter), so it reads the SAME
+            // `CAMSTACK_SERVER_*` boot markers the starter writes.
+            envNames: {
+                bootMode: 'CAMSTACK_SERVER_BOOT_MODE',
+                activeVersion: 'CAMSTACK_SERVER_ACTIVE_VERSION',
+                seedDir: 'CAMSTACK_SEED_SERVER_DIR',
+            },
+            logger: options.logger,
+            restartServer: options.restartAgent ??
+                ((requestedBy) => scheduleAgentRestart(options.logger, requestedBy, options.dataDir)),
+            dataDir: options.dataDir,
+            runningPackageJsonPath: options.runningPackageJsonPath ?? resolveAgentPackageJsonPath(__dirname),
+            workspaceProbeDir: __dirname,
+            // Default to the runNpm-backed adapter — a packaged desktop agent ships a
+            // bare Node with no system npm, so the raw `execFile('npm')` default would
+            // ENOENT. `cacheDir` mirrors AddonInstaller's `<dataDir>/addons/.npm-bootstrap`.
+            execNpm: options.execNpm ??
+                (0, system_exec_npm_js_1.buildSystemExecNpm)({
+                    cacheDir: path.join(options.dataDir, 'addons', '.npm-bootstrap'),
+                    logger: options.logger,
+                }),
+            env: options.env,
+            now: options.now,
+        });
+    }
+}
+exports.AgentUpdateService = AgentUpdateService;
+/**
+ * The manifest entry for the agent runtime's own providers. Appended to
+ * `buildAgentOwnManifest`'s output so `server-management` reaches the hub's
+ * `HubNodeRegistry` (and therefore `createCapabilityProxy` node routing) even
+ * though no `loadedAddons` entry owns it.
+ */
+function agentRuntimeManifestEntry() {
+    return { addonId: exports.AGENT_RUNTIME_ADDON_ID, capabilities: ['server-management'] };
+}

package/dist/agent/apply-model-distribution.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Agent-side model distribution (P2): pull a staged model tarball from the hub
+ * and untar it into this node's modelsDir. Factored behind a seam so the
+ * fetch/extract/fs effects are injectable in tests.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyModelDistribution = applyModelDistribution;
+async function applyModelDistribution(seam, params) {
+    seam.mkdirp(seam.modelsDir);
+    const buffer = await seam.fetchBundle(params.source);
+    await seam.extract(buffer, seam.modelsDir);
+    return { success: true, modelId: params.modelId, format: params.format, path: seam.modelsDir };
+}

package/dist/agent/derive-hub-url.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Derive the agent's `CAMSTACK_HUB_URL` from its friendly `hubAddress`.
+ *
+ * `hubAddress` is the agent's single source of truth for "where is the hub"
+ * (the Moleculer TCP dial target). The cross-node consumers of
+ * `CAMSTACK_HUB_URL` — the pipeline-runner remote-source leg and the
+ * cross-node recorder pull — only ever extract the HOSTNAME from it
+ * (`resolveHubHostname` / `extractHost` in
+ * `packages/addon-pipeline/src/shared/hub-hostname.ts`). Deriving the value
+ * here removes the historical requirement to set a second, redundant env var
+ * by hand on every remote agent (the cross-node-source trap).
+ *
+ * Accepts every friendly form `normalizeHubUrl`
+ * (`packages/system/src/kernel/moleculer/broker-factory.ts`) accepts:
+ *   `host`, `host:port`, `host:port/nodeID`, `nodeID@host`,
+ *   `nodeID@host:port`, and bracketed IPv6 (`[::1]:6000`).
+ * The optional `nodeID@` prefix and `/nodeID` suffix are stripped and the
+ * Moleculer `:port` (6000-family) is dropped — only the host survives.
+ *
+ * Port note: the emitted `:4443` is the DEFAULT hub API port (matching the
+ * hub-side default in `server/backend/src/api/addon-upload.ts` and the
+ * manually-proven value used on live remote agents), NOT a probed value.
+ * Because every current consumer keeps only the host, the port is convention;
+ * a future full-URL consumer must treat it as the default, not authoritative.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveHubUrlFromHubAddress = deriveHubUrlFromHubAddress;
+exports.deriveHubUrlForExport = deriveHubUrlForExport;
+exports.pickIpv4 = pickIpv4;
+exports.normalizeObservedHost = normalizeObservedHost;
+exports.deriveHubUrlFromRegistry = deriveHubUrlFromRegistry;
+const HUB_API_PORT = 4443;
+function deriveHubUrlFromHubAddress(hubAddress) {
+    const trimmed = hubAddress.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    // Strip an optional `nodeID@` prefix.
+    const afterAt = trimmed.includes('@') ? (trimmed.split('@')[1] ?? '') : trimmed;
+    // Strip an optional `/nodeID` suffix — keep only the `host[:port]` authority.
+    const authority = afterAt.split('/')[0] ?? '';
+    const host = extractHostFromAuthority(authority);
+    if (host === undefined)
+        return undefined;
+    return `https://${host}:${HUB_API_PORT}`;
+}
+/**
+ * Compute the `CAMSTACK_HUB_URL` value the agent should export, or `undefined`
+ * when it must be left untouched. An explicit operator-provided env value
+ * (`hubUrlWasExplicit`) always wins and is never clobbered — this preserves
+ * today's working deployments. Kept pure (env is passed in) so both the
+ * boot-time derivation and the reconnect path can be unit-tested.
+ */
+function deriveHubUrlForExport(hubUrlWasExplicit, hubAddress) {
+    if (hubUrlWasExplicit)
+        return undefined;
+    if (hubAddress === undefined)
+        return undefined;
+    return deriveHubUrlFromHubAddress(hubAddress);
+}
+/** Take the bare host from a `host[:port]` authority, keeping bracketed IPv6. */
+function extractHostFromAuthority(authority) {
+    const value = authority.trim();
+    if (value.length === 0)
+        return undefined;
+    if (value.startsWith('[')) {
+        const end = value.indexOf(']');
+        if (end > 0)
+            return value.slice(0, end + 1);
+        return undefined;
+    }
+    const host = value.split(':')[0] ?? '';
+    return host.length > 0 ? host : undefined;
+}
+/** Node id the hub broker always registers under. */
+const HUB_NODE_ID = 'hub';
+const IPV4_MAPPED_PREFIX = '::ffff:';
+const IPV4_DOTTED_QUAD = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+/**
+ * First non-internal IPv4 in a Moleculer node's advertised IP list.
+ * Canonical home of this helper — `resolveHubEndpoint` in `agent-http.ts`
+ * (UI-facing `resolvedHubAddress`) re-exports and reuses it so the UI display
+ * and the exported `CAMSTACK_HUB_URL` always agree.
+ */
+function pickIpv4(ipList) {
+    if (!ipList)
+        return null;
+    for (const ip of ipList) {
+        if (ip.includes(':'))
+            continue; // skip IPv6
+        if (ip.startsWith('127.'))
+            continue; // skip loopback
+        return ip;
+    }
+    return null;
+}
+/**
+ * Normalize a socket-observed address so it survives a WHATWG-`URL` hostname
+ * write (`substituteRtspHost`): strip the `::ffff:` IPv4-mapped prefix,
+ * bracket bare IPv6 (an unbracketed IPv6 assigned to `url.hostname` is
+ * silently IGNORED — the URL would keep 127.0.0.1), pass plain IPv4 /
+ * hostnames / already-bracketed IPv6 through untouched.
+ */
+function normalizeObservedHost(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed.startsWith('['))
+        return trimmed; // already-bracketed IPv6
+    if (trimmed.toLowerCase().startsWith(IPV4_MAPPED_PREFIX)) {
+        const mapped = trimmed.slice(IPV4_MAPPED_PREFIX.length);
+        if (IPV4_DOTTED_QUAD.test(mapped))
+            return mapped;
+    }
+    // Any remaining colon means bare IPv6 — bracket it.
+    if (trimmed.includes(':'))
+        return `[${trimmed}]`;
+    return trimmed;
+}
+/**
+ * Best hub host from the agent-side Moleculer registry view:
+ *   `udpAddress` (wire truth) → first non-loopback IPv4 in `ipList`
+ *   (hub self-advertised; container-internal in bridge-mode Docker) →
+ *   `hostname` (hub's `os.hostname()`; often unresolvable — last resort).
+ * Returns `undefined` when the hub node is not (yet) known. Emits the SAME
+ * `https://host:4443` shape as `deriveHubUrlFromHubAddress` — see the port
+ * note at the top of this file.
+ */
+function deriveHubUrlFromRegistry(nodes) {
+    const hub = nodes.find((node) => node.id === HUB_NODE_ID);
+    if (hub === undefined)
+        return undefined;
+    const host = normalizeObservedHost(hub.udpAddress) ?? pickIpv4(hub.ipList) ?? hub.hostname;
+    if (host === undefined || host.length === 0)
+        return undefined;
+    return `https://${host}:${HUB_API_PORT}`;
+}

package/dist/agent/fetch-bundle-from-hub.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchBundleFromHub = fetchBundleFromHub;
+const node_crypto_1 = require("node:crypto");
+const undici_1 = require("undici");
+/**
+ * Stream a staged addon tgz from the hub's one-time-token bundle route and
+ * verify integrity (byte count + sha256) before handing it to the installer.
+ */
+async function fetchBundleFromHub(opts) {
+    // When a fetchImpl is injected (tests), call it as-is — the stub ignores dispatcher.
+    // For production (global fetch against the real hub's self-signed TLS cert), use
+    // undici.fetch with an Agent that disables CA verification. The hub serves HTTPS with a
+    // self-signed cert; bare fetch rejects it with UNABLE_TO_VERIFY_LEAF_SIGNATURE.
+    // Integrity is independently guaranteed by the sha256+bytes checks below; trust is
+    // established by the cluster relationship — consistent with the CLI's approach.
+    //
+    // We call undici.fetch (not the global fetch) so that `Agent` and `RequestInit` share
+    // the same undici type declarations; the global fetch augmentation uses `undici-types`
+    // which ships a structurally incompatible `Dispatcher` type. Both return a structurally
+    // compatible Response; we narrow via the shared `ResponseLike` interface to avoid
+    // cross-package type unification.
+    // `accept-encoding: identity` — never let the hub gzip/brotli this binary
+    // pull. A Brotli-encoded response made undici's BrotliDecompress abort with
+    // "TypeError: terminated", silently breaking the pull. The hub also opts the
+    // route out of compression; this is the client-side belt-and-suspenders.
+    const authHeader = { Authorization: `Bearer ${opts.token}`, 'accept-encoding': 'identity' };
+    const res = opts.fetchImpl
+        ? await opts.fetchImpl(opts.url, { headers: authHeader })
+        : await (0, undici_1.fetch)(opts.url, {
+            headers: authHeader,
+            dispatcher: new undici_1.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, node_crypto_1.createHash)('sha256').update(buffer).digest('hex');
+    if (sha !== opts.sha256) {
+        throw new Error(`bundle sha256 mismatch: expected ${opts.sha256}, got ${sha}`);
+    }
+    return buffer;
+}