@camstack/kernel 0.1.7 → 0.1.10

package/dist/index.d.mts

@@ -0,0 +1,645 @@
+import { AddonDeclaration, ICamstackAddon, AddonContext, InstalledPackage, IScopedLogger, CapabilityDeclaration, CapabilityConsumerRegistration, CapabilityMode, CapabilityInfo, WorkerInfo, IAddonProcessManager, WorkerToMainMessage, SubProcessConfig, IManagedSubProcess, SubProcessInfo, WorkerProcessStats } from '@camstack/types';
+export { InstalledPackage } from '@camstack/types';
+import { z } from 'zod';
+
+interface RegisteredAddon {
+    readonly declaration: AddonDeclaration;
+    readonly packageName: string;
+    readonly packageVersion: string;
+    /** Human-readable package name from camstack.displayName in package.json */
+    readonly packageDisplayName?: string;
+    readonly addonClass: new () => ICamstackAddon;
+}
+declare class AddonLoader {
+    private addons;
+    /** Scan addons directory and load all addon packages.
+     *  Supports scoped layout: addons/@scope/package-name/ */
+    loadFromDirectory(addonsDir: string): Promise<void>;
+    private tryLoadAddon;
+    /** Load addon from a specific directory (package.json + dist/) */
+    loadFromAddonDir(addonDir: string): Promise<void>;
+    /** Load addon from a direct path (for development/testing) */
+    loadFromPath(addonId: string, modulePath: string, packageName: string, declaration?: Partial<AddonDeclaration>, packageVersion?: string): Promise<void>;
+    /** Get a registered addon by ID */
+    getAddon(addonId: string): RegisteredAddon | undefined;
+    /** List all registered addons */
+    listAddons(): RegisteredAddon[];
+    /** Check if an addon is registered */
+    hasAddon(addonId: string): boolean;
+    /** Create a new instance of an addon (not yet initialized) */
+    createInstance(addonId: string): ICamstackAddon;
+}
+
+declare class AddonEngineManager {
+    private readonly loader;
+    private readonly baseContext;
+    private engines;
+    constructor(loader: AddonLoader, baseContext: Partial<Omit<AddonContext, 'addonConfig'>>);
+    /**
+     * Get or create an addon engine for the given effective config.
+     * Cameras with the same addonId + effective config share the same engine.
+     */
+    getOrCreateEngine(addonId: string, globalConfig: Record<string, unknown>, cameraOverride?: Record<string, unknown>): Promise<ICamstackAddon>;
+    /** Get all active engines */
+    getActiveEngines(): Map<string, ICamstackAddon>;
+    /** Shutdown a specific engine by its config key */
+    shutdownEngine(configKey: string): Promise<void>;
+    /** Shutdown all engines */
+    shutdownAll(): Promise<void>;
+    /** Compute a deterministic config key (visible for tests) */
+    computeConfigKey(addonId: string, effectiveConfig: Record<string, unknown>): string;
+    private hashConfig;
+}
+
+interface AddonInstallerConfig {
+    /** Directory where addons are stored (e.g., {dataDir}/addons) — each addon is a subdirectory */
+    readonly addonsDir: string;
+    /** npm registry URL (default: https://registry.npmjs.org) */
+    readonly registry?: string;
+    /** Workspace packages directory (e.g., /path/to/camstack-server/packages) — for dev installs */
+    readonly workspacePackagesDir?: string;
+}
+
+declare class AddonInstaller {
+    private readonly addonsDir;
+    private readonly registry;
+    private readonly workspacePackagesDir;
+    constructor(config: AddonInstallerConfig);
+    /** Required addon packages that must be installed for the server to function */
+    static readonly REQUIRED_PACKAGES: readonly ["@camstack/core", "@camstack/addon-stream-broker", "@camstack/addon-recording", "@camstack/addon-vision", "@camstack/addon-admin-ui", "@camstack/addon-webrtc-adaptive", "@camstack/addon-analytics", "@camstack/addon-scene-intelligence", "@camstack/addon-advanced-notifier"];
+    /** Ensure the addons directory exists */
+    initialize(): Promise<void>;
+    /**
+     * Ensure all required packages are installed in the addons directory.
+     * This replaces the standalone first-boot-installer.ts.
+     */
+    ensureRequiredPackages(): Promise<void>;
+    private findWorkspacePackage;
+    /** Install addon from a tgz file (uploaded or downloaded) */
+    installFromTgz(tgzPath: string): Promise<{
+        name: string;
+        version: string;
+    }>;
+    /**
+     * Install addon — prefers workspace if available, falls back to npm.
+     * This ensures dev builds (with vite output, etc.) are used when in workspace mode.
+     */
+    install(packageName: string, version?: string): Promise<{
+        name: string;
+        version: string;
+    }>;
+    /**
+     * Install addon from workspace by copying package.json + dist/ to addons dir.
+     * Does NOT build — expects dist/ to already exist (run `npm run build` separately).
+     */
+    installFromWorkspace(packageName: string): Promise<{
+        name: string;
+        version: string;
+    }>;
+    /** Install addon from npm (download tgz, then extract) */
+    installFromNpm(packageName: string, version?: string): Promise<{
+        name: string;
+        version: string;
+    }>;
+    /** Uninstall addon (delete directory) */
+    uninstall(packageName: string): Promise<void>;
+    /** List installed addons (directories with package.json containing camstack.addons) */
+    listInstalled(): InstalledPackage[];
+    /** Check if an addon is installed */
+    isInstalled(packageName: string): boolean;
+    /** Get installed package info */
+    getInstalledPackage(packageName: string): InstalledPackage | null;
+}
+
+/**
+ * Ensure a directory exists (recursive).
+ * Single source of truth — replaces scattered mkdirSync calls.
+ */
+declare function ensureDir(dirPath: string): void;
+/**
+ * Copy a directory recursively.
+ * Single source of truth — extracted from addon-installer + first-boot-installer.
+ */
+declare function copyDirRecursive(src: string, dest: string): void;
+/**
+ * Strip @camstack/* dependencies and devDependencies from a package.json object.
+ * Used when installing addons into the addons directory — @camstack packages
+ * are provided by the host runtime, not installed per-addon.
+ *
+ * Returns a new object (immutable).
+ */
+declare function stripCamstackDeps(pkg: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Copy extra file directories declared in package.json "files" field.
+ * Copies directories (not individual files) from source to destination.
+ * Skips "dist" (already handled) and glob patterns.
+ */
+declare function copyExtraFileDirs(pkgJson: Record<string, unknown>, sourceDir: string, destDir: string): void;
+/**
+ * Create symlinks in node_modules so that static `import from '@camstack/core'` works.
+ * Links: node_modules/@camstack/{pkg} -> data/addons/{pkg}/
+ * (not just dist -- need package.json for Node's exports resolution)
+ */
+declare function symlinkAddonsToNodeModules(addonsDir: string, nodeModulesDir: string): void;
+/**
+ * Check if any file in src/ is newer than dist/.
+ * Returns true if rebuild is needed.
+ */
+declare function isSourceNewer(packageDir: string): boolean;
+/**
+ * Ensure a library dependency (not an addon) has a dist/ directory.
+ * Does NOT rebuild — in dev mode, `npm run build` should be run separately.
+ * Only checks that dist/ exists and has an index file.
+ */
+declare function ensureLibraryBuilt(packageName: string, packagesDir: string): void;
+/**
+ * Install a single npm package into a target directory (package.json + dist/).
+ * No validation on camstack.addons -- works for any @camstack/* package.
+ * Uses synchronous child_process calls (suitable for first-boot and update paths).
+ */
+declare function installPackageFromNpmSync(packageName: string, targetDir: string): void;
+
+/**
+ * Detect whether we're running inside the monorepo workspace.
+ * Returns the absolute path to the packages/ directory if found, otherwise null.
+ *
+ * Single source of truth — replaces identical implementations in:
+ * - first-boot-installer.ts
+ * - addon-bridge.service.ts
+ */
+declare function detectWorkspacePackagesDir(startDir: string): string | null;
+
+/**
+ * Central registry for all capability providers and consumers.
+ * Lives in @camstack/kernel. Mode-aware: singleton (one active) or collection (all active).
+ *
+ * Uses injected LoggingService, NEVER NestJS static Logger.
+ */
+declare class CapabilityRegistry {
+    private readonly logger;
+    private readonly configReader;
+    private readonly capabilities;
+    /** Per-device singleton overrides: deviceId → (capability → addonId) */
+    private readonly deviceOverrides;
+    /** Per-device collection filters: deviceId → (capability → addonIds[]) */
+    private readonly deviceCollectionFilters;
+    constructor(logger: IScopedLogger, configReader: (capability: string) => string | undefined);
+    /**
+     * Declare a capability (typically called when addon manifests are loaded).
+     * Must be called before registerProvider/registerConsumer for that capability.
+     */
+    declareCapability(declaration: CapabilityDeclaration): void;
+    /**
+     * Register a capability provider (called by addon loader when addon is enabled).
+     * For singleton: auto-activates if user-preferred or first registered.
+     * For collection: adds to active set and notifies consumers.
+     */
+    registerProvider(capability: string, addonId: string, provider: unknown): void;
+    /**
+     * Unregister a provider (called when addon is disabled/uninstalled).
+     */
+    unregisterProvider(capability: string, addonId: string): void;
+    /**
+     * Register a consumer that wants to be notified when providers change.
+     * If a provider is already active, the consumer is immediately notified.
+     * Returns a disposer function for cleanup.
+     */
+    registerConsumer<T = unknown>(registration: CapabilityConsumerRegistration<T>): () => void;
+    /**
+     * Get the active singleton provider for a capability.
+     * Returns null if none set.
+     */
+    getSingleton<T = unknown>(capability: string): T | null;
+    /**
+     * Get all active collection providers for a capability.
+     */
+    getCollection<T = unknown>(capability: string): readonly T[];
+    /**
+     * Set which addon should be the active singleton for a capability.
+     * Call with `immediate: true` to also swap the runtime provider now
+     * (consumers' onSet will be awaited).
+     */
+    setActiveSingleton(capability: string, addonId: string, immediate?: boolean): Promise<void>;
+    /**
+     * Get the mode declared for a capability.
+     */
+    getMode(capability: string): CapabilityMode | undefined;
+    /**
+     * List all registered capabilities with their providers.
+     */
+    listCapabilities(): CapabilityInfo[];
+    /**
+     * Check if all dependencies for a capability are satisfied (have active providers).
+     */
+    areDependenciesMet(declaration: CapabilityDeclaration): boolean;
+    /**
+     * Get the dependency-ordered list of capability names for boot sequencing.
+     * Returns capabilities sorted topologically by dependsOn.
+     * Throws if a cycle is detected.
+     */
+    getBootOrder(): string[];
+    /**
+     * Set a per-device singleton override. When resolveForDevice is called for
+     * this device + capability, the specified addon's provider is returned
+     * instead of the global singleton.
+     */
+    setDeviceOverride(deviceId: string, capability: string, addonId: string): void;
+    /**
+     * Clear a per-device singleton override, reverting to the global singleton.
+     */
+    clearDeviceOverride(deviceId: string, capability: string): void;
+    /**
+     * Get all per-device singleton overrides for a device.
+     * Returns a Map of capability name to addon ID.
+     */
+    getDeviceOverrides(deviceId: string): Map<string, string>;
+    /**
+     * Resolve a singleton provider for a specific device.
+     * 1. Check device override — return that addon's provider
+     * 2. Fallback to global singleton
+     */
+    resolveForDevice<T = unknown>(capability: string, deviceId: string): T | null;
+    /**
+     * Set a per-device collection filter. When resolveCollectionForDevice is called
+     * for this device + capability, only providers from the specified addon IDs
+     * are returned instead of the full collection.
+     */
+    setDeviceCollectionFilter(deviceId: string, capability: string, addonIds: string[]): void;
+    /**
+     * Clear a per-device collection filter, reverting to the full collection.
+     */
+    clearDeviceCollectionFilter(deviceId: string, capability: string): void;
+    /**
+     * Resolve collection providers for a specific device.
+     * If a filter exists for the device + capability, only those addon's providers are returned.
+     * If no filter exists, the full collection is returned.
+     */
+    resolveCollectionForDevice<T = unknown>(capability: string, deviceId: string): readonly T[];
+    /**
+     * Get a specific addon's provider by addon ID, regardless of whether it's the active singleton.
+     * Useful for per-device overrides that need to look up any registered provider.
+     */
+    getProviderByAddonId<T = unknown>(capability: string, addonId: string): T | null;
+    private activateSingleton;
+    private activateSingletonAsync;
+}
+
+interface InfraCapability {
+    /** Capability name */
+    readonly name: string;
+    /** If true, boot aborts when this capability's addon fails to initialize */
+    readonly required: boolean;
+}
+/**
+ * Infrastructure capabilities that must boot before all other addons.
+ * Enabled in Phase 1 of the boot sequence. Order matters: storage before logging.
+ */
+declare const INFRA_CAPABILITIES: readonly InfraCapability[];
+/** Check if a capability name is an infrastructure capability */
+declare function isInfraCapability(name: string): boolean;
+
+/** Default data directory — used when CAMSTACK_DATA env var is not set */
+declare const DEFAULT_DATA_PATH = "camstack-data";
+/** Bootstrap config -- loaded from config.yaml ONLY at startup.
+ *  All other settings live in SQL (system_settings table). */
+declare const bootstrapSchema: z.ZodObject<{
+    /** Server mode: 'hub' (full server) or 'agent' (worker node) */
+    mode: z.ZodDefault<z.ZodEnum<["hub", "agent"]>>;
+    server: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+        host: z.ZodDefault<z.ZodString>;
+        dataPath: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        port: number;
+        host: string;
+        dataPath: string;
+    }, {
+        port?: number | undefined;
+        host?: string | undefined;
+        dataPath?: string | undefined;
+    }>>;
+    auth: z.ZodDefault<z.ZodObject<{
+        jwtSecret: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        adminUsername: z.ZodDefault<z.ZodString>;
+        adminPassword: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        jwtSecret: string | null;
+        adminUsername: string;
+        adminPassword: string;
+    }, {
+        jwtSecret?: string | null | undefined;
+        adminUsername?: string | undefined;
+        adminPassword?: string | undefined;
+    }>>;
+    /** Hub connection config — only used when mode='agent' */
+    hub: z.ZodDefault<z.ZodObject<{
+        url: z.ZodDefault<z.ZodString>;
+        token: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        token: string;
+    }, {
+        url?: string | undefined;
+        token?: string | undefined;
+    }>>;
+    /** Agent-specific config — only used when mode='agent' */
+    agent: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        /** Port for the agent status page (minimal HTML) */
+        statusPort: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        statusPort: number;
+    }, {
+        name?: string | undefined;
+        statusPort?: number | undefined;
+    }>>;
+    /** TLS configuration */
+    tls: z.ZodDefault<z.ZodObject<{
+        /** Enable HTTPS (default: true) */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Path to custom cert file (PEM). If not set, auto-generates self-signed. */
+        certPath: z.ZodOptional<z.ZodString>;
+        /** Path to custom key file (PEM). Required if certPath is set. */
+        keyPath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        certPath?: string | undefined;
+        keyPath?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        certPath?: string | undefined;
+        keyPath?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    hub: {
+        url: string;
+        token: string;
+    };
+    agent: {
+        name: string;
+        statusPort: number;
+    };
+    mode: "hub" | "agent";
+    server: {
+        port: number;
+        host: string;
+        dataPath: string;
+    };
+    auth: {
+        jwtSecret: string | null;
+        adminUsername: string;
+        adminPassword: string;
+    };
+    tls: {
+        enabled: boolean;
+        certPath?: string | undefined;
+        keyPath?: string | undefined;
+    };
+}, {
+    hub?: {
+        url?: string | undefined;
+        token?: string | undefined;
+    } | undefined;
+    agent?: {
+        name?: string | undefined;
+        statusPort?: number | undefined;
+    } | undefined;
+    mode?: "hub" | "agent" | undefined;
+    server?: {
+        port?: number | undefined;
+        host?: string | undefined;
+        dataPath?: string | undefined;
+    } | undefined;
+    auth?: {
+        jwtSecret?: string | null | undefined;
+        adminUsername?: string | undefined;
+        adminPassword?: string | undefined;
+    } | undefined;
+    tls?: {
+        enabled?: boolean | undefined;
+        certPath?: string | undefined;
+        keyPath?: string | undefined;
+    } | undefined;
+}>;
+type BootstrapConfig = z.infer<typeof bootstrapSchema>;
+/**
+ * Runtime defaults -- used by ConfigManager.get() for backward compatibility
+ * until Plan B wires all runtime settings to the system_settings SQL table.
+ */
+declare const RUNTIME_DEFAULTS: Record<string, unknown>;
+type ServerMode = 'hub' | 'agent';
+type AppConfig = BootstrapConfig & {
+    features: {
+        streaming: boolean;
+        notifications: boolean;
+        objectDetection: boolean;
+        remoteAccess: boolean;
+        agentCluster: boolean;
+        smartHome: boolean;
+        recordings: boolean;
+        backup: boolean;
+        repl: boolean;
+    };
+    storage: {
+        provider: string;
+        locations: Record<string, string>;
+    };
+    logging: {
+        level: string;
+        retentionDays: number;
+    };
+    eventBus: {
+        ringBufferSize: number;
+    };
+    retention: {
+        detectionEventsDays: number;
+        audioLevelsDays: number;
+    };
+    providers: Array<{
+        id: string;
+        type: string;
+        name: string;
+        url?: string;
+        username?: string;
+        password?: string;
+        mqtt?: {
+            brokerUrl: string;
+            username?: string;
+            password?: string;
+            topicPrefix: string;
+        };
+    }>;
+};
+
+interface ISettingsStore {
+    getSystem(key: string): unknown;
+    setSystem(key: string, value: unknown): void;
+    getAllSystem(): Record<string, unknown>;
+    getAllAddon(addonId: string): Record<string, unknown>;
+    setAllAddon(addonId: string, config: Record<string, unknown>): void;
+    getAllProvider(providerId: string): Record<string, unknown>;
+    setProvider(providerId: string, key: string, value: unknown): void;
+    getAllDevice(deviceId: string): Record<string, unknown>;
+    setDevice(deviceId: string, key: string, value: unknown): void;
+}
+/** Feature flags manifest — inlined to avoid dependency on core's feature module */
+interface FeatureManifest {
+    streaming: boolean;
+    notifications: boolean;
+    objectDetection: boolean;
+    remoteAccess: boolean;
+    agentCluster: boolean;
+    smartHome: boolean;
+    recordings: boolean;
+    backup: boolean;
+    repl: boolean;
+}
+declare class ConfigManager {
+    private readonly configPath;
+    private bootstrapConfig;
+    private settingsStore;
+    constructor(configPath: string);
+    /** Called by main.ts after the SQLite DB is ready (Phase 2). */
+    setSettingsStore(store: ISettingsStore): void;
+    /**
+     * Get a config value by dot-notation path.
+     * Priority: bootstrap config -> SQL system_settings -> RUNTIME_DEFAULTS fallback.
+     */
+    get<T>(path: string): T;
+    /**
+     * Write a value to SQL system_settings.
+     * Throws if the settings store is not yet wired.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Bulk-read all system_settings keys that belong to a logical section.
+     * A "section" is the first segment of a dot-notation key (e.g. 'features', 'logging').
+     */
+    getSection(section: string): Record<string, unknown>;
+    /**
+     * Bulk-write a section of runtime settings to SQL system_settings.
+     * Each entry in `data` is stored as `section.key`.
+     */
+    setSection(section: string, data: Record<string, unknown>): void;
+    /** Read all config for an addon from addon_settings. */
+    getAddonConfig(addonId: string): Record<string, unknown>;
+    /** Write (bulk-replace) config for an addon to addon_settings. */
+    setAddonConfig(addonId: string, config: Record<string, unknown>): void;
+    /** Read all config for a provider from provider_settings. */
+    getProviderConfig(providerId: string): Record<string, unknown>;
+    /** Write (upsert) a single key for a provider to provider_settings. */
+    setProviderConfig(providerId: string, key: string, value: unknown): void;
+    /** Read all config for a device from device_settings. */
+    getDeviceConfig(deviceId: string): Record<string, unknown>;
+    /** Write (upsert) a single key for a device to device_settings. */
+    setDeviceConfig(deviceId: string, key: string, value: unknown): void;
+    /** Get a value from the parsed bootstrap config */
+    getBootstrap<T>(path: string): T;
+    /** Features accessor -- reads from SQL when available, falls back to RUNTIME_DEFAULTS */
+    get features(): FeatureManifest;
+    /**
+     * Returns a merged view of bootstrap config + runtime defaults for backward compat.
+     */
+    get raw(): AppConfig;
+    /** Sections that live in config.yaml. Everything else goes to SQL. */
+    private static readonly BOOTSTRAP_SECTIONS;
+    /**
+     * Atomically update one top-level section of config.yaml and sync in-memory.
+     * Only bootstrap sections (server, auth, mode) are written to YAML.
+     * Runtime settings must use setSection() which writes to SQL.
+     */
+    update(section: string, data: Record<string, unknown>): void;
+    /**
+     * Deep-set a value in a nested plain object using a dot-notation path.
+     * Returns a new object (immutable).
+     */
+    private setNested;
+    /**
+     * Apply env var overrides onto the raw YAML object.
+     * Only bootstrap-level env vars are applied.
+     */
+    private applyEnvOverrides;
+    private loadYaml;
+    private warnDefaultCredentials;
+    private getFromBootstrap;
+    private getFromRuntimeDefaults;
+    /**
+     * Perform a prefix-based nested lookup against SQL system_settings.
+     * e.g. path='features' matches keys 'features.streaming', 'features.notifications', etc.
+     * Returns an object keyed by the sub-key, or undefined if nothing is found.
+     */
+    private getNestedFromSystemSettings;
+}
+
+interface WorkerHostOptions {
+    readonly workerEntryPath: string;
+    readonly devMode?: boolean;
+    /** Force all addons in-process (emergency fallback) */
+    readonly forceInProcess?: boolean;
+    readonly heartbeatIntervalMs?: number;
+    readonly heartbeatTimeoutMs?: number;
+    readonly maxCrashesInWindow?: number;
+    readonly crashWindowMs?: number;
+    readonly shutdownTimeoutMs?: number;
+    /** Log writer function — receives structured log entries from workers */
+    readonly onWorkerLog?: (entry: {
+        addonId: string;
+        level: string;
+        message: string;
+        scope: readonly string[];
+        meta?: Record<string, unknown>;
+    }) => void;
+}
+declare class AddonWorkerHost {
+    private readonly workers;
+    private readonly options;
+    private heartbeatTimer;
+    /** Set of addons that failed to fork and fell back to in-process */
+    private readonly fallbackInProcess;
+    constructor(options: WorkerHostOptions);
+    /** Check if an addon is infrastructure (must stay in-process) */
+    isInfraAddon(addonId: string): boolean;
+    /** Check if an addon fell back to in-process after fork failure */
+    isFallbackInProcess(addonId: string): boolean;
+    /** Mark an addon as fallen back to in-process */
+    markFallbackInProcess(addonId: string): void;
+    /**
+     * Determine if an addon should be forked.
+     * Default: fork everything except infra addons.
+     * Addons can opt out with `inProcess: true` in declaration.
+     * Emergency fallback: CAMSTACK_FORCE_INPROCESS=true disables all forking.
+     */
+    shouldFork(addonId: string, declaration?: {
+        forkable?: boolean;
+        inProcess?: boolean;
+    }): boolean;
+    /** Fork a worker for an addon */
+    forkWorker(addonId: string, addonDir: string, config: Record<string, unknown>, storagePaths: Record<string, string>, dataDir?: string, locationPaths?: Record<string, string>, workerToken?: string): Promise<void>;
+    /** List all workers with stats */
+    listWorkers(): readonly WorkerInfo[];
+    /** Gracefully shutdown a single worker by addon ID */
+    shutdownWorkerById(addonId: string): Promise<void>;
+    /** Gracefully restart a single worker by addon ID (stop then re-fork with same config) */
+    restartWorker(addonId: string): Promise<void>;
+    /** Gracefully shutdown all workers */
+    shutdownAll(): Promise<void>;
+    /** Start heartbeat monitoring — workers now report heartbeat via tRPC, not IPC PING */
+    startHeartbeatMonitoring(): void;
+    /** Update heartbeat timestamp for a worker (called when agent.heartbeat arrives) */
+    updateWorkerHeartbeat(addonId: string, cpuPercent?: number, memoryRss?: number): void;
+    private handleWorkerExit;
+    private shutdownWorker;
+}
+
+declare class WorkerProcessManager implements IAddonProcessManager {
+    private readonly sendToMain;
+    private readonly processes;
+    constructor(sendToMain: (msg: WorkerToMainMessage) => void);
+    spawn(config: SubProcessConfig): Promise<IManagedSubProcess>;
+    listProcesses(): readonly SubProcessInfo[];
+    getWorkerStats(): WorkerProcessStats;
+    killAll(): Promise<void>;
+}
+
+export { AddonEngineManager, AddonInstaller, type AddonInstallerConfig, AddonLoader, AddonWorkerHost, type AppConfig, type BootstrapConfig, CapabilityRegistry, ConfigManager, DEFAULT_DATA_PATH, INFRA_CAPABILITIES, type ISettingsStore, type InfraCapability, RUNTIME_DEFAULTS, type RegisteredAddon, type ServerMode, type WorkerHostOptions, WorkerProcessManager, bootstrapSchema, copyDirRecursive, copyExtraFileDirs, detectWorkspacePackagesDir, ensureDir, ensureLibraryBuilt, installPackageFromNpmSync, isInfraCapability, isSourceNewer, stripCamstackDeps, symlinkAddonsToNodeModules };