@camstack/system 1.0.5 → 1.0.7

package/dist/addon-runner.js

@@ -1,11 +1,14 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_manifest_python_deps = require("./manifest-python-deps-B4BmMoGT.js");
+const require_manifest_python_deps = require("./manifest-python-deps-eBDj5HEY.js");
+const require_custom_action_registry = require("./custom-action-registry-vLYEFTtv.js");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
-let _camstack_types = require("@camstack/types");
+let _camstack_types_addon = require("@camstack/types/addon");
 let node_url = require("node:url");
+let node_v8 = require("node:v8");
+node_v8 = require_chunk.__toESM(node_v8);
 let node_module = require("node:module");
 //#region src/kernel/moleculer/worker-device-restore.ts
 /**
@@ -41,7 +44,7 @@ async function runWorkerDeviceRestoreWithRetry(addon, context, addonId, sourceNo
 		return;
 	}
 	const shared = context.kernel?.readinessRegistry ?? null;
-	const registry = shared ?? new _camstack_types.ReadinessRegistry({
+	const registry = shared ?? new _camstack_types_addon.ReadinessRegistry({
 		eventBus: bus,
 		sourceNodeId,
 		logger: context.logger
@@ -54,13 +57,13 @@ async function runWorkerDeviceRestoreWithRetry(addon, context, addonId, sourceNo
 		}, { timeoutMs: 6e4 });
 		log?.debug?.(`[worker-restore] "${addonId}": device-manager READY`);
 	} catch (err) {
-		if (err instanceof _camstack_types.ReadinessTimeoutError) {
+		if (err instanceof _camstack_types_addon.ReadinessTimeoutError) {
 			context.logger?.warn?.(`[worker-restore] device-manager not ready within ${err.waitedMs}ms — skipping for "${addonId}"`);
 			return;
 		}
 		throw err;
 	} finally {
-		if (!shared && registry instanceof _camstack_types.ReadinessRegistry) registry.close();
+		if (!shared && registry instanceof _camstack_types_addon.ReadinessRegistry) registry.close();
 	}
 	try {
 		const deviceManager = Reflect.get(api, "deviceManager");
@@ -86,7 +89,7 @@ async function runWorkerDeviceRestoreWithRetry(addon, context, addonId, sourceNo
 		await restoreFn.call(addon, savedDevices);
 		log?.info?.(`[worker-restore] "${addonId}": restored ${savedDevices.length} device(s)`);
 	} catch (err) {
-		log?.warn?.(`[worker-restore] "${addonId}": restoreDevices threw: ${(0, _camstack_types.errMsg)(err)}`);
+		log?.warn?.(`[worker-restore] "${addonId}": restoreDevices threw: ${(0, _camstack_types_addon.errMsg)(err)}`);
 	}
 }
 //#endregion
@@ -272,11 +275,11 @@ function createChildAddonCallDispatch(deps) {
 * every loaded addon before closing the UDS channel.
 */
 process.on("uncaughtException", (err) => {
-	console.error(`[addon-runner CRASH] uncaughtException: ${(0, _camstack_types.errMsg)(err)}\n${err instanceof Error ? err.stack ?? "" : ""}`);
+	console.error(`[addon-runner CRASH] uncaughtException: ${(0, _camstack_types_addon.errMsg)(err)}\n${err instanceof Error ? err.stack ?? "" : ""}`);
 	process.exit(1);
 });
 process.on("unhandledRejection", (reason) => {
-	console.error(`[addon-runner CRASH] unhandledRejection: ${(0, _camstack_types.errMsg)(reason)}\n${reason instanceof Error ? reason.stack ?? "" : ""}`);
+	console.error(`[addon-runner CRASH] unhandledRejection: ${(0, _camstack_types_addon.errMsg)(reason)}\n${reason instanceof Error ? reason.stack ?? "" : ""}`);
 });
 process.on("exit", (code) => {
 	console.error(`[addon-runner EXIT] code=${String(code)} nodeId=${process.env["CAMSTACK_RUNNER_ID"] ?? "?"}`);
@@ -297,7 +300,7 @@ function parseAddonsSpec(raw) {
 	try {
 		parsed = JSON.parse(raw);
 	} catch (err) {
-		throw new Error(`[addon-runner] CAMSTACK_RUNNER_ADDONS is not valid JSON: ${(0, _camstack_types.errMsg)(err)}`, { cause: err });
+		throw new Error(`[addon-runner] CAMSTACK_RUNNER_ADDONS is not valid JSON: ${(0, _camstack_types_addon.errMsg)(err)}`, { cause: err });
 	}
 	if (!Array.isArray(parsed)) throw new Error(`[addon-runner] CAMSTACK_RUNNER_ADDONS must be a JSON array`);
 	const specs = [];
@@ -370,7 +373,7 @@ async function main() {
 	try {
 		specs = parseAddonsSpec(addonsJson);
 	} catch (err) {
-		console.error((0, _camstack_types.errMsg)(err));
+		console.error((0, _camstack_types_addon.errMsg)(err));
 		process.exit(1);
 	}
 	if (specs.length === 0) {
@@ -393,7 +396,7 @@ async function main() {
 			AddonClass
 		});
 	} catch (err) {
-		console.error(`[addon-runner] Failed to load "${spec.addonId}": ${(0, _camstack_types.errMsg)(err)}`);
+		console.error(`[addon-runner] Failed to load "${spec.addonId}": ${(0, _camstack_types_addon.errMsg)(err)}`);
 		process.exit(1);
 	}
 	let storageProvider;
@@ -463,7 +466,7 @@ async function main() {
 	* removed `custom.<action>` Moleculer action). Constructed up front so the
 	* addon-call handler can close over it at client-construction time.
 	*/
-	const customActionRegistry = new require_manifest_python_deps.CustomActionRegistry();
+	const customActionRegistry = new require_custom_action_registry.CustomActionRegistry();
 	let shuttingDown = false;
 	const udsChildClient = new require_manifest_python_deps.LocalChildClient({
 		nodeId: parentNodeId,
@@ -488,12 +491,12 @@ async function main() {
 	try {
 		await udsChildClient.start();
 	} catch (err) {
-		console.error(`[addon-runner] "${nodeId}" UDS connect failed — exiting: ${(0, _camstack_types.errMsg)(err)}`);
+		console.error(`[addon-runner] "${nodeId}" UDS connect failed — exiting: ${(0, _camstack_types_addon.errMsg)(err)}`);
 		process.exit(1);
 	}
 	runnerLog.info("UDS child transport connected", { meta: { childId: runnerId } });
 	if (storageProvider) runnerLog.info(`"${nodeId}" storage provider rooted at ${dataDir}`);
-	else runnerLog.warn(`"${nodeId}" failed to load FilesystemStorageProvider`, { meta: { error: (0, _camstack_types.errMsg)(storageProviderError) } });
+	else runnerLog.warn(`"${nodeId}" failed to load FilesystemStorageProvider`, { meta: { error: (0, _camstack_types_addon.errMsg)(storageProviderError) } });
 	const refreshChildCaps = (reason) => {
 		const freshDescriptors = buildChildCapDescriptors(runnerManifest, require_manifest_python_deps.getWorkerNativeCapSnapshot());
 		udsChildClient.updateCaps(freshDescriptors).catch((err) => {
@@ -523,12 +526,12 @@ async function main() {
 			const pkgRaw = JSON.parse(node_fs.readFileSync(node_path.join(spec.addonDir, "package.json"), "utf-8"));
 			await require_manifest_python_deps.installManifestNativeDeps(spec.addonDir, pkgRaw, context.logger);
 		} catch (nativeErr) {
-			console.error(`[addon-runner] native deps install failed for "${spec.addonId}": ${(0, _camstack_types.errMsg)(nativeErr)}`);
+			console.error(`[addon-runner] native deps install failed for "${spec.addonId}": ${(0, _camstack_types_addon.errMsg)(nativeErr)}`);
 			process.exit(1);
 		}
 		await require_manifest_python_deps.installManifestPythonDeps(declaration, spec.addonDir, context.deps, context.logger);
 		const registeredProviders = /* @__PURE__ */ new Map();
-		const initResult = (0, _camstack_types.normalizeAddonInitResult)(await addon.initialize(context));
+		const initResult = (0, _camstack_types_addon.normalizeAddonInitResult)(await addon.initialize(context));
 		for (const reg of initResult?.providers ?? []) {
 			const capName = reg.capability.name;
 			registeredProviders.set(capName, reg.provider);
@@ -564,7 +567,7 @@ async function main() {
 			initResult: initResult ?? null
 		});
 	} catch (err) {
-		console.error(`[addon-runner] Init failed for "${spec.addonId}": ${(0, _camstack_types.errMsg)(err)}`);
+		console.error(`[addon-runner] Init failed for "${spec.addonId}": ${(0, _camstack_types_addon.errMsg)(err)}`);
 		process.exit(1);
 	}
 	if (deviceRestorePromises.length > 0 && !shuttingDown) await Promise.allSettled(deviceRestorePromises);
@@ -574,7 +577,7 @@ async function main() {
 		if (hubReachableFired) return;
 		hubReachableFired = true;
 		for (const entry of loaded) if (typeof entry.addon.onHubReachable === "function") Promise.resolve(entry.addon.onHubReachable()).catch((err) => {
-			runnerLog.error(`"${entry.addonId}" onHubReachable() threw`, { meta: { error: (0, _camstack_types.errMsg)(err) } });
+			runnerLog.error(`"${entry.addonId}" onHubReachable() threw`, { meta: { error: (0, _camstack_types_addon.errMsg)(err) } });
 		});
 	};
 	udsChildClient.onConnected(() => {
@@ -584,6 +587,20 @@ async function main() {
 	fireHubReachableOnce();
 	runnerLog.info(`"${nodeId}" started — ${loaded.length} addon(s) ready (UDS connected)`);
 	process.stdout.write(`READY:${nodeId}\n`);
+	process.on("SIGUSR2", () => {
+		const MB = (x) => Math.round(x / 1048576 * 10) / 10;
+		try {
+			const mu = process.memoryUsage();
+			const spaces = node_v8.getHeapSpaceStatistics().filter((s) => s.space_used_size > 0).map((s) => `${s.space_name}=${MB(s.space_used_size)}`).join(" ");
+			const addons = loaded.map((e) => e.addonId).join(",");
+			runnerLog.info(`[mem] node="${nodeId}" addons=[${addons}] rss=${MB(mu.rss)} heapUsed=${MB(mu.heapUsed)} heapTotal=${MB(mu.heapTotal)} external=${MB(mu.external)} arrayBuffers=${MB(mu.arrayBuffers)} | ${spaces}`);
+			const snapPath = `/tmp/heap-${nodeId.replace(/[^\w.-]/g, "_")}.heapsnapshot`;
+			node_v8.writeHeapSnapshot(snapPath);
+			runnerLog.info(`[mem] node="${nodeId}" heap snapshot written -> ${snapPath}`);
+		} catch (err) {
+			runnerLog.warn(`[mem] snapshot failed: ${(0, _camstack_types_addon.errMsg)(err)}`);
+		}
+	});
 	const shutdown = async () => {
 		shuttingDown = true;
 		require_manifest_python_deps.setWorkerNativeCapsChangeListener(null);
@@ -595,12 +612,12 @@ async function main() {
 		for (const entry of loaded) try {
 			await entry.addon.shutdown();
 		} catch (err) {
-			runnerLog.error(`"${entry.addonId}" shutdown threw`, { meta: { error: (0, _camstack_types.errMsg)(err) } });
+			runnerLog.error(`"${entry.addonId}" shutdown threw`, { meta: { error: (0, _camstack_types_addon.errMsg)(err) } });
 		}
 		try {
 			await udsChildClient.close();
 		} catch (err) {
-			runnerLog.warn("UDS child transport close threw during shutdown", { meta: { error: (0, _camstack_types.errMsg)(err) } });
+			runnerLog.warn("UDS child transport close threw during shutdown", { meta: { error: (0, _camstack_types_addon.errMsg)(err) } });
 		}
 		process.exit(0);
 	};
@@ -619,7 +636,7 @@ async function main() {
 	}, 5e3);
 }
 main().catch((err) => {
-	console.error(`[addon-runner] Fatal error: ${(0, _camstack_types.errMsg)(err)}`);
+	console.error(`[addon-runner] Fatal error: ${(0, _camstack_types_addon.errMsg)(err)}`);
 	process.exit(1);
 });
 //#endregion

package/dist/addon-runner.mjs

@@ -1,9 +1,11 @@
-import { $ as setWorkerNativeCapsChangeListener, A as createUdsLoggerWithControl, L as LocalChildClient, X as getWorkerNativeCapProvider, Z as getWorkerNativeCapSnapshot, dt as CustomActionRegistry, ht as resolveAddonClass, i as createUdsAddonContext, mt as installManifestNativeDeps, t as installManifestPythonDeps, tt as validateProviderRegistrations } from "./manifest-python-deps-CXbKrOdk.mjs";
+import { $ as setWorkerNativeCapsChangeListener, A as createUdsLoggerWithControl, L as LocalChildClient, X as getWorkerNativeCapProvider, Z as getWorkerNativeCapSnapshot, i as createUdsAddonContext, mt as resolveAddonClass, pt as installManifestNativeDeps, t as installManifestPythonDeps, tt as validateProviderRegistrations } from "./manifest-python-deps-CoJXeb9u.mjs";
+import { t as CustomActionRegistry } from "./custom-action-registry-BEXwC-oo.mjs";
 import { register } from "node:module";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
-import { ReadinessRegistry, ReadinessTimeoutError, errMsg, normalizeAddonInitResult } from "@camstack/types";
+import { ReadinessRegistry, ReadinessTimeoutError, errMsg, normalizeAddonInitResult } from "@camstack/types/addon";
 import { pathToFileURL } from "node:url";
+import * as v8 from "node:v8";
 //#region src/kernel/moleculer/worker-device-restore.ts
 /**
 * Worker-side device restore helper.
@@ -581,6 +583,20 @@ async function main() {
 	fireHubReachableOnce();
 	runnerLog.info(`"${nodeId}" started — ${loaded.length} addon(s) ready (UDS connected)`);
 	process.stdout.write(`READY:${nodeId}\n`);
+	process.on("SIGUSR2", () => {
+		const MB = (x) => Math.round(x / 1048576 * 10) / 10;
+		try {
+			const mu = process.memoryUsage();
+			const spaces = v8.getHeapSpaceStatistics().filter((s) => s.space_used_size > 0).map((s) => `${s.space_name}=${MB(s.space_used_size)}`).join(" ");
+			const addons = loaded.map((e) => e.addonId).join(",");
+			runnerLog.info(`[mem] node="${nodeId}" addons=[${addons}] rss=${MB(mu.rss)} heapUsed=${MB(mu.heapUsed)} heapTotal=${MB(mu.heapTotal)} external=${MB(mu.external)} arrayBuffers=${MB(mu.arrayBuffers)} | ${spaces}`);
+			const snapPath = `/tmp/heap-${nodeId.replace(/[^\w.-]/g, "_")}.heapsnapshot`;
+			v8.writeHeapSnapshot(snapPath);
+			runnerLog.info(`[mem] node="${nodeId}" heap snapshot written -> ${snapPath}`);
+		} catch (err) {
+			runnerLog.warn(`[mem] snapshot failed: ${errMsg(err)}`);
+		}
+	});
 	const shutdown = async () => {
 		shuttingDown = true;
 		setWorkerNativeCapsChangeListener(null);

package/dist/addon-utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Lightweight addon-facing utility surface for `@camstack/system`.
+ *
+ * Importing the root barrel (`@camstack/system`) loads the ENTIRE framework —
+ * the kernel (moleculer) + every builtin addon (sqlite-storage, winston-logging,
+ * device-manager, …) — ~64MB of V8 heap PER process, even when an addon only
+ * needs a model-download or data-plane helper. Node has no runtime tree-shaking
+ * and the package is host-provided (loaded as the prebuilt barrel), so every
+ * addon that imported one util from the barrel paid the full ~64MB — multiplied
+ * across every forked pipeline runner.
+ *
+ * This subpath re-exports ONLY the addon-facing helpers, each from its DEEP,
+ * kernel-free source module, so importing it costs a few MB instead of ~64MB.
+ *
+ * See memory: camstack_runner_ram_and_build_rootcause.
+ */
+export { downloadFile, ensureModel, isModelDownloaded, deleteModelFromDisk, } from './download/model-downloader.js';
+export { ModelDownloadService } from './download/model-download-service.js';
+export { createFileDataPlaneHandler } from './http/file-data-plane.js';
+export { CustomActionRegistry } from './kernel/custom-action-registry.js';

package/dist/addon-utils.js

@@ -0,0 +1,11 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("./chunk-Cek0wNdY.js");
+const require_model_download_service = require("./model-download-service-JtVQtbb6.js");
+const require_custom_action_registry = require("./custom-action-registry-vLYEFTtv.js");
+exports.CustomActionRegistry = require_custom_action_registry.CustomActionRegistry;
+exports.ModelDownloadService = require_model_download_service.ModelDownloadService;
+exports.createFileDataPlaneHandler = require_model_download_service.createFileDataPlaneHandler;
+exports.deleteModelFromDisk = require_model_download_service.deleteModelFromDisk;
+exports.downloadFile = require_model_download_service.downloadFile;
+exports.ensureModel = require_model_download_service.ensureModel;
+exports.isModelDownloaded = require_model_download_service.isModelDownloaded;

package/dist/addon-utils.mjs

@@ -0,0 +1,3 @@
+import { a as ensureModel, c as isModelDownloaded, l as createFileDataPlaneHandler, n as deleteModelFromDisk, r as downloadFile, t as ModelDownloadService } from "./model-download-service-C7AjBsX9.mjs";
+import { t as CustomActionRegistry } from "./custom-action-registry-BEXwC-oo.mjs";
+export { CustomActionRegistry, ModelDownloadService, createFileDataPlaneHandler, deleteModelFromDisk, downloadFile, ensureModel, isModelDownloaded };

package/dist/builtins/native-metrics/native-metrics.addon.d.ts

@@ -66,6 +66,14 @@ export default class NativeMetricsAddon extends BaseAddon<NativeMetricsConfig> {
      * the dedicated `$process.restart` action, not this kill API.
      */
     private killProcess;
+    /**
+     * Ask the addon's forked runner to write a V8 heap snapshot (SIGUSR2 → the
+     * runner's diagnostic handler in addon-runner.ts), for deep per-addon memory
+     * attribution. Resolves the addon's worker pid from the kernel `$process.list`
+     * and signals it; the runner writes `/tmp/heap-<sanitized nodeId>.heapsnapshot`
+     * and logs its memoryUsage + heap-space breakdown. '$hub' targets this process.
+     */
+    private dumpHeapSnapshot;
     /** Raw `ps` scan returning every pid + command + resource stats. */
     private runPs;
     protected globalSettingsSchema(): import('@camstack/types').ConfigUISchema;

package/dist/builtins/native-metrics/native-metrics.addon.js

@@ -123,13 +123,15 @@ var NativeMetricsProvider = class {
 		return getCpuTemperatureInternal();
 	}
 	async getProcessStats(input) {
-		const { getPidStats } = await Promise.resolve().then(() => require("../../resource-monitor-IIEanuJt.js")).then((n) => n.resource_monitor_exports);
+		const { getPidStats } = await Promise.resolve().then(() => require("../../resource-monitor-DNNomR-i.js")).then((n) => n.resource_monitor_exports);
 		const raw = await getPidStats(input.pids);
 		const result = [];
 		for (const [pid, s] of raw) result.push({
 			pid,
 			cpu: s.cpu,
-			memory: s.memory
+			memory: s.memory,
+			privateBytes: s.privateBytes,
+			sharedBytes: s.sharedBytes
 		});
 		return result;
 	}
@@ -596,7 +598,8 @@ var NativeMetricsAddon = class extends _camstack_types.BaseAddon {
 			listAddonInstances: () => this.listAddonInstances(),
 			getAddonStats: (params) => this.getAddonStats(params.addonId),
 			listNodeProcesses: () => this.listNodeProcesses(),
-			killProcess: (params) => this.killProcess(params)
+			killProcess: (params) => this.killProcess(params),
+			dumpHeapSnapshot: (params) => this.dumpHeapSnapshot(params)
 		};
 		this.snapshotTimer = setInterval(() => this.emitMetricsSnapshots(), METRICS_SNAPSHOT_INTERVAL_MS);
 		return [{
@@ -845,6 +848,50 @@ var NativeMetricsAddon = class extends _camstack_types.BaseAddon {
 			};
 		}
 	}
+	/**
+	* Ask the addon's forked runner to write a V8 heap snapshot (SIGUSR2 → the
+	* runner's diagnostic handler in addon-runner.ts), for deep per-addon memory
+	* attribution. Resolves the addon's worker pid from the kernel `$process.list`
+	* and signals it; the runner writes `/tmp/heap-<sanitized nodeId>.heapsnapshot`
+	* and logs its memoryUsage + heap-space breakdown. '$hub' targets this process.
+	*/
+	async dumpHeapSnapshot(input) {
+		const sanitize = (nodeId) => nodeId.replace(/[^\w.-]/g, "_");
+		let pid;
+		let nodeId;
+		if (input.addonId === "$hub") {
+			pid = process.pid;
+			nodeId = this.ctx.kernel.cluster?.broker?.nodeID ?? "$hub";
+		} else {
+			const target = (await this.listWorkerInstances()).find((w) => w.addonId === input.addonId);
+			if (!target) return {
+				success: false,
+				reason: `no runner process for addon '${input.addonId}'`
+			};
+			pid = target.pid;
+			nodeId = target.nodeId;
+		}
+		const path = `/tmp/heap-${sanitize(nodeId)}.heapsnapshot`;
+		try {
+			process.kill(pid, "SIGUSR2");
+			this.ctx.logger.info("Requested heap snapshot from runner", { meta: {
+				addonId: input.addonId,
+				pid,
+				path
+			} });
+			return {
+				success: true,
+				pid,
+				path
+			};
+		} catch (err) {
+			return {
+				success: false,
+				reason: err instanceof Error ? err.message : String(err),
+				pid
+			};
+		}
+	}
 	/** Raw `ps` scan returning every pid + command + resource stats. */
 	async runPs() {
 		try {

package/dist/builtins/native-metrics/native-metrics.addon.mjs

@@ -116,13 +116,15 @@ var NativeMetricsProvider = class {
 		return getCpuTemperatureInternal();
 	}
 	async getProcessStats(input) {
-		const { getPidStats } = await import("../../resource-monitor-ClDGFyf6.mjs").then((n) => n.r);
+		const { getPidStats } = await import("../../resource-monitor-BkP504Vq.mjs").then((n) => n.r);
 		const raw = await getPidStats(input.pids);
 		const result = [];
 		for (const [pid, s] of raw) result.push({
 			pid,
 			cpu: s.cpu,
-			memory: s.memory
+			memory: s.memory,
+			privateBytes: s.privateBytes,
+			sharedBytes: s.sharedBytes
 		});
 		return result;
 	}
@@ -589,7 +591,8 @@ var NativeMetricsAddon = class extends BaseAddon {
 			listAddonInstances: () => this.listAddonInstances(),
 			getAddonStats: (params) => this.getAddonStats(params.addonId),
 			listNodeProcesses: () => this.listNodeProcesses(),
-			killProcess: (params) => this.killProcess(params)
+			killProcess: (params) => this.killProcess(params),
+			dumpHeapSnapshot: (params) => this.dumpHeapSnapshot(params)
 		};
 		this.snapshotTimer = setInterval(() => this.emitMetricsSnapshots(), METRICS_SNAPSHOT_INTERVAL_MS);
 		return [{
@@ -838,6 +841,50 @@ var NativeMetricsAddon = class extends BaseAddon {
 			};
 		}
 	}
+	/**
+	* Ask the addon's forked runner to write a V8 heap snapshot (SIGUSR2 → the
+	* runner's diagnostic handler in addon-runner.ts), for deep per-addon memory
+	* attribution. Resolves the addon's worker pid from the kernel `$process.list`
+	* and signals it; the runner writes `/tmp/heap-<sanitized nodeId>.heapsnapshot`
+	* and logs its memoryUsage + heap-space breakdown. '$hub' targets this process.
+	*/
+	async dumpHeapSnapshot(input) {
+		const sanitize = (nodeId) => nodeId.replace(/[^\w.-]/g, "_");
+		let pid;
+		let nodeId;
+		if (input.addonId === "$hub") {
+			pid = process.pid;
+			nodeId = this.ctx.kernel.cluster?.broker?.nodeID ?? "$hub";
+		} else {
+			const target = (await this.listWorkerInstances()).find((w) => w.addonId === input.addonId);
+			if (!target) return {
+				success: false,
+				reason: `no runner process for addon '${input.addonId}'`
+			};
+			pid = target.pid;
+			nodeId = target.nodeId;
+		}
+		const path = `/tmp/heap-${sanitize(nodeId)}.heapsnapshot`;
+		try {
+			process.kill(pid, "SIGUSR2");
+			this.ctx.logger.info("Requested heap snapshot from runner", { meta: {
+				addonId: input.addonId,
+				pid,
+				path
+			} });
+			return {
+				success: true,
+				pid,
+				path
+			};
+		} catch (err) {
+			return {
+				success: false,
+				reason: err instanceof Error ? err.message : String(err),
+				pid
+			};
+		}
+	}
 	/** Raw `ps` scan returning every pid + command + resource stats. */
 	async runPs() {
 		try {

package/dist/custom-action-registry-BEXwC-oo.mjs

@@ -0,0 +1,38 @@
+//#region src/kernel/custom-action-registry.ts
+/**
+* CustomActionRegistry — per-process registry of addon custom actions.
+*
+* Populated at boot from each addon's `AddonInitResult.customActions` +
+* `handleCustomAction` handler. Rejects actions declared with scope other
+* than 'system' (today only 'system' is runtime-supported; the descriptor
+* allows future scopes for forward compat).
+*/
+var CustomActionRegistry = class {
+	byAddon = /* @__PURE__ */ new Map();
+	registerAddon(addonId, catalog, handler) {
+		const actions = /* @__PURE__ */ new Map();
+		for (const [name, spec] of Object.entries(catalog)) {
+			const scope = spec.scope ?? { kind: "system" };
+			if (scope.kind !== "system") throw new Error(`custom action '${addonId}.${name}' declared scope '${scope.kind}' — not yet implemented`);
+			actions.set(name, {
+				spec,
+				handler: (input) => handler(name, input)
+			});
+		}
+		this.byAddon.set(addonId, actions);
+	}
+	unregisterAddon(addonId) {
+		this.byAddon.delete(addonId);
+	}
+	resolve(addonId, action) {
+		return this.byAddon.get(addonId)?.get(action) ?? null;
+	}
+	listActions(addonId) {
+		return [...this.byAddon.get(addonId)?.keys() ?? []];
+	}
+	listAddons() {
+		return [...this.byAddon.keys()];
+	}
+};
+//#endregion
+export { CustomActionRegistry as t };

package/dist/custom-action-registry-vLYEFTtv.js

@@ -0,0 +1,43 @@
+//#region src/kernel/custom-action-registry.ts
+/**
+* CustomActionRegistry — per-process registry of addon custom actions.
+*
+* Populated at boot from each addon's `AddonInitResult.customActions` +
+* `handleCustomAction` handler. Rejects actions declared with scope other
+* than 'system' (today only 'system' is runtime-supported; the descriptor
+* allows future scopes for forward compat).
+*/
+var CustomActionRegistry = class {
+	byAddon = /* @__PURE__ */ new Map();
+	registerAddon(addonId, catalog, handler) {
+		const actions = /* @__PURE__ */ new Map();
+		for (const [name, spec] of Object.entries(catalog)) {
+			const scope = spec.scope ?? { kind: "system" };
+			if (scope.kind !== "system") throw new Error(`custom action '${addonId}.${name}' declared scope '${scope.kind}' — not yet implemented`);
+			actions.set(name, {
+				spec,
+				handler: (input) => handler(name, input)
+			});
+		}
+		this.byAddon.set(addonId, actions);
+	}
+	unregisterAddon(addonId) {
+		this.byAddon.delete(addonId);
+	}
+	resolve(addonId, action) {
+		return this.byAddon.get(addonId)?.get(action) ?? null;
+	}
+	listActions(addonId) {
+		return [...this.byAddon.get(addonId)?.keys() ?? []];
+	}
+	listAddons() {
+		return [...this.byAddon.keys()];
+	}
+};
+//#endregion
+Object.defineProperty(exports, "CustomActionRegistry", {
+	enumerable: true,
+	get: function() {
+		return CustomActionRegistry;
+	}
+});