@camstack/core 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -1,5 +1,7 @@
-import { ModelDownloadOptions, ModelDownloadResult, IPythonEnvironment, PythonProbeResult, PythonEnvReady, AddonDeclaration, ICamstackAddon, AddonContext, PipelineConfig, FrameInput, PipelineResult } from '@camstack/types';
+import { ModelDownloadOptions, ModelDownloadResult, IPythonEnvironment, PythonProbeResult, PythonEnvReady, AddonDeclaration, ICamstackAddon, AddonContext, PipelineConfig, FrameInput, PipelineResult, AudioChunkInput, PipelineNode, IScopedLogger, CapabilityDeclaration, CapabilityConsumerRegistration, CapabilityMode, CapabilityInfo, LoggerFactory, AgentRegistrationInfo, AgentToHubMessage, HubToAgentMessage, AgentRuntimeStatus, ITaskHandler, TaskContext, IFileStorage as IFileStorage$1, IStorageProvider as IStorageProvider$1, StorageLocationName as StorageLocationName$1, IStorageLocation as IStorageLocation$1, IConfigurable, AddonManifest, CapabilityProviderMap, ConfigUISchema, ILogDestination as ILogDestination$1, LogEntry as LogEntry$1, LogFilter as LogFilter$1, IEventBus, SystemEvent, EventFilter, TokenScope, ScopedToken, INotificationOutput, Notification, Toast, IAddonRouteProvider, IAddonHttpRoute } from '@camstack/types';
+export { EventFilter, EventSource, IScopedLogger, SystemEvent } from '@camstack/types';
 import { ChildProcess } from 'node:child_process';
+import { z } from 'zod';
 
 type EventCallback<T = unknown> = (data: T) => void;
 declare class EventBus {
@@ -47,6 +49,12 @@ declare class AddonInstaller {
     private ensureAddonDirectory;
     /** Install builtin packages if not already present */
     private installBuiltins;
+    /**
+     * Ensure a set of packages are installed — installs any that are missing.
+     * This is the public entry-point used during boot to guarantee required
+     * addon packages are present before the loader tries to resolve them.
+     */
+    ensureInstalled(packages: string[]): Promise<void>;
     /** Check if a package is installed */
     isInstalled(packageName: string): boolean;
     /** Get installed package info */
@@ -59,12 +67,14 @@ declare class AddonInstaller {
     uninstallPackage(packageName: string): Promise<void>;
     /** Update a package to latest version */
     updatePackage(packageName: string): Promise<void>;
+    /** Install an addon from a local .tgz file */
+    installFromTgz(tgzPath: string): Promise<void>;
     /** Update all packages */
     updateAll(): Promise<void>;
     /** Get the node_modules path for require/import resolution */
     getNodeModulesPath(): string;
 }
-/** Default builtin packages that are auto-installed */
+/** Default builtin packages that are auto-installed on first boot */
 declare const BUILTIN_PACKAGES: readonly string[];
 
 interface RegisteredAddon {
@@ -77,7 +87,7 @@ declare class AddonLoader {
     /** Load all addons from an npm package */
     loadPackage(packageName: string): Promise<void>;
     /** Load addon from a direct path (for development/testing) */
-    loadFromPath(addonId: string, modulePath: string, packageName: string): Promise<void>;
+    loadFromPath(addonId: string, modulePath: string, packageName: string, declaration?: Partial<AddonDeclaration>): Promise<void>;
     /** Get a registered addon by ID */
     getAddon(addonId: string): RegisteredAddon | undefined;
     /** List all registered addons */
@@ -96,7 +106,7 @@ declare class AddonEngineManager {
     private readonly loader;
     private readonly baseContext;
     private engines;
-    constructor(loader: AddonLoader, baseContext: Omit<AddonContext, 'addonConfig'>);
+    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.
@@ -136,8 +146,1529 @@ declare class PipelineRunner {
     private readonly addonConfigs;
     constructor(engineManager: AddonEngineManager, addonConfigs: Map<string, Record<string, unknown>>);
     run(frame: FrameInput, config: PipelineConfig): Promise<PipelineResult>;
+    /**
+     * Run only the audio classification node on an audio chunk.
+     * Used by the audio path in DetectionWiringService (separate from video pipeline).
+     */
+    runAudioNode(chunk: AudioChunkInput, audioNode: PipelineNode): Promise<PipelineResult>;
     private executeNode;
     private executeChildren;
 }
 
-export { AddonEngineManager, AddonInstaller, type AddonInstallerConfig, AddonLoader, BUILTIN_PACKAGES, EventBus, type InstalledPackage, PipelineRunner, PipelineValidator, PythonEnvManager, type RegisteredAddon, type ValidationIssue, type ValidationResult, downloadModel };
+/**
+ * Central registry for all capability providers and consumers.
+ * Lives in @camstack/core. 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;
+
+type ProcessState = 'stopped' | 'starting' | 'running' | 'stopping' | 'error';
+interface ProcessConfig {
+    readonly id: string;
+    readonly label: string;
+    readonly command?: string;
+    readonly modulePath?: string;
+    readonly args?: string[];
+    readonly env?: Record<string, string>;
+    readonly autoRestart: boolean;
+    readonly maxRestarts?: number;
+    readonly healthCheck?: {
+        readonly intervalMs: number;
+        readonly timeoutMs: number;
+        readonly failureThreshold: number;
+    };
+}
+interface ProcessStats {
+    readonly pid: number;
+    readonly cpu: number;
+    readonly memory: number;
+    readonly uptime: number;
+    readonly restartCount: number;
+}
+interface ManagedProcessStatus {
+    readonly id: string;
+    readonly label: string;
+    readonly state: ProcessState;
+    readonly pid?: number;
+    readonly stats?: ProcessStats;
+    readonly lastCrashAt?: number;
+    readonly lastCrashError?: string;
+    readonly restartCount: number;
+    readonly nextRestartAt?: number;
+}
+
+/** Event emitter for process lifecycle events */
+type ProcessEventEmitter = {
+    emitProcessCrashed(processId: string, code: number | null, signal: string | null, restartCount: number): void;
+    emitProcessRestartScheduled(processId: string, restartCount: number, delayMs: number): void;
+    emitProcessRestarted(processId: string, restartCount: number): void;
+};
+/** Re-export LoggerFactory as ProcessLoggerFactory for backward compatibility */
+type ProcessLoggerFactory = LoggerFactory;
+
+declare class ManagedProcess {
+    private readonly config;
+    private readonly events;
+    private readonly logger;
+    private childProcess;
+    private _state;
+    private _startedAt?;
+    private restartTimer?;
+    private _restartCount;
+    private _lastCrashAt?;
+    private _lastCrashError?;
+    constructor(config: ProcessConfig, events: ProcessEventEmitter, logger: IScopedLogger);
+    get state(): ProcessState;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStatus(): ManagedProcessStatus;
+    private scheduleRestart;
+    private getStats;
+    private getNextRestartTime;
+}
+
+declare class ProcessManager {
+    private readonly events;
+    private readonly loggerFactory;
+    private readonly processes;
+    constructor(events: ProcessEventEmitter, loggerFactory: ProcessLoggerFactory);
+    register(config: ProcessConfig): ManagedProcess;
+    start(id: string): Promise<void>;
+    stop(id: string): Promise<void>;
+    restart(id: string): Promise<void>;
+    get(id: string): ManagedProcess;
+    listAll(): readonly ManagedProcessStatus[];
+    shutdownAll(): Promise<void>;
+}
+
+interface StreamNetworkStats {
+    readonly nominalBitrateKbps: number;
+    readonly observedBitrateKbps: number;
+    readonly peakBitrateKbps: number;
+    readonly packetLossPercent: number;
+    readonly lastUpdated: number;
+}
+interface ClientNetworkStats {
+    readonly rttMs: number;
+    readonly jitterMs: number;
+    readonly estimatedBandwidthKbps: number;
+    readonly lastUpdated: number;
+}
+interface DeviceNetworkStats {
+    readonly deviceId: string;
+    readonly streams: Readonly<Record<string, StreamNetworkStats>>;
+    readonly client?: ClientNetworkStats;
+}
+interface INetworkQualityTracker {
+    reportStreamStats(deviceId: string, streamId: string, bitrateKbps: number, packetLoss?: number): void;
+    reportClientStats(deviceId: string, stats: Omit<ClientNetworkStats, 'lastUpdated'>): void;
+    getDeviceStats(deviceId: string): DeviceNetworkStats | null;
+    getAllStats(): readonly DeviceNetworkStats[];
+}
+declare class NetworkQualityTracker implements INetworkQualityTracker {
+    private readonly devices;
+    private static readonly MAX_SAMPLES;
+    reportStreamStats(deviceId: string, streamId: string, bitrateKbps: number, packetLoss?: number): void;
+    reportClientStats(deviceId: string, stats: Omit<ClientNetworkStats, 'lastUpdated'>): void;
+    getDeviceStats(deviceId: string): DeviceNetworkStats | null;
+    getAllStats(): readonly DeviceNetworkStats[];
+    private getOrCreateDevice;
+}
+
+interface ReplScope {
+    readonly type: 'system' | 'provider' | 'device' | 'addon';
+    readonly providerId?: string;
+    readonly deviceId?: string;
+    readonly addonId?: string;
+}
+interface ReplSessionContext {
+    readonly scope: ReplScope;
+    /** Pre-populated variables available in the REPL session */
+    readonly variables: Record<string, unknown>;
+}
+interface ReplResult {
+    readonly output: string;
+    readonly type: 'value' | 'error' | 'void';
+    readonly duration: number;
+}
+interface IReplEngine {
+    execute(code: string, context: ReplSessionContext): Promise<ReplResult>;
+    getCompletions(partial: string, context: ReplSessionContext): Promise<string[]>;
+}
+/**
+ * Context provider that the server kernel implements.
+ * The REPL engine calls this to build the sandbox for each scope type.
+ */
+interface IReplContextProvider {
+    getSystemSandbox(): Record<string, unknown>;
+    getDeviceSandbox(deviceId: string): Record<string, unknown>;
+    getProviderSandbox(providerId: string): Record<string, unknown>;
+    getAddonSandbox(addonId: string): Record<string, unknown>;
+}
+
+declare class ReplEngine implements IReplEngine {
+    private readonly contextProvider;
+    constructor(contextProvider: IReplContextProvider);
+    execute(code: string, context: ReplSessionContext): Promise<ReplResult>;
+    getCompletions(partial: string, context: ReplSessionContext): Promise<string[]>;
+    private buildSandbox;
+}
+
+interface AgentInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly capabilities: readonly string[];
+    readonly host: string;
+    readonly port: number;
+    readonly resources?: AgentResources;
+}
+interface AgentResources {
+    readonly cpuCores?: number;
+    readonly memoryMB?: number;
+    readonly gpuAvailable?: boolean;
+    readonly gpuModel?: string;
+}
+interface AgentStatus {
+    readonly id: string;
+    readonly name: string;
+    readonly state: 'online' | 'offline' | 'degraded';
+    readonly capabilities: readonly string[];
+    readonly lastHeartbeat: number;
+    readonly connectedSince?: number;
+    readonly resources?: AgentResources;
+    readonly activeTaskCount: number;
+    readonly completedTaskCount: number;
+    readonly failedTaskCount: number;
+}
+interface AgentTask {
+    readonly id: string;
+    readonly capability: string;
+    readonly input: Record<string, unknown>;
+    readonly timeout: number;
+    readonly priority: 'low' | 'normal' | 'high';
+    readonly label?: string;
+}
+interface AgentTaskResult {
+    readonly taskId: string;
+    readonly agentId: string;
+    readonly status: 'success' | 'error' | 'timeout';
+    readonly output?: Record<string, unknown>;
+    readonly error?: string;
+    readonly durationMs: number;
+}
+interface TaskDispatchOptions {
+    readonly preferredAgent?: string;
+    readonly capability: string;
+    readonly remoteOnly?: boolean;
+}
+interface AgentEntry {
+    readonly info: AgentInfo;
+    state: 'online' | 'offline' | 'degraded';
+    connectedSince: number;
+    lastHeartbeat: number;
+    activeTaskCount: number;
+    completedTaskCount: number;
+    failedTaskCount: number;
+}
+/** Event emitter for agent lifecycle and task events */
+type AgentEventEmitter = {
+    emitAgentRegistered(agentId: string, capabilities: readonly string[]): void;
+    emitAgentUnregistered(agentId: string): void;
+    emitAgentOnline(agentId: string): void;
+    emitAgentOffline(agentId: string): void;
+    emitTaskDispatched(taskId: string, agentId: string, capability: string): void;
+};
+
+declare class AgentRegistry {
+    private readonly events;
+    private readonly heartbeatTimeoutMs;
+    private readonly heartbeatCheckIntervalMs;
+    private readonly agents;
+    private readonly heartbeatIntervals;
+    constructor(events: AgentEventEmitter, heartbeatTimeoutMs?: number, heartbeatCheckIntervalMs?: number);
+    /** Register a new agent */
+    registerAgent(info: AgentInfo): void;
+    /** Remove agent */
+    unregisterAgent(id: string): void;
+    /** Update heartbeat timestamp */
+    heartbeat(id: string): void;
+    /** Find agents with a specific capability */
+    getAgentsWithCapability(capability: string): readonly AgentEntry[];
+    /** Get best agent for a task (least loaded) */
+    selectAgent(capability: string, preferredId?: string): AgentEntry | null;
+    /** List all agents with status */
+    listAgents(): readonly AgentStatus[];
+    /** Get single agent */
+    getAgent(id: string): AgentEntry | null;
+    /** Destroy all heartbeat intervals */
+    destroy(): void;
+    private startHeartbeatCheck;
+}
+
+declare class TaskDispatcher {
+    private readonly agentRegistry;
+    private readonly events;
+    private readonly pendingTasks;
+    private readonly localExecutors;
+    constructor(agentRegistry: AgentRegistry, events: AgentEventEmitter);
+    /** Dispatch a task to the best available agent */
+    dispatch(task: AgentTask, options?: TaskDispatchOptions): Promise<AgentTaskResult>;
+    /** Register a local executor for a capability (in-process fallback) */
+    registerLocalExecutor(capability: string, executor: (input: Record<string, unknown>) => Promise<Record<string, unknown>>): void;
+    /** Called when an agent returns a result */
+    handleTaskResult(result: AgentTaskResult): void;
+    private executeLocally;
+    private sendToAgent;
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LogEntry {
+    timestamp: Date;
+    level: LogLevel;
+    scope: string[];
+    message: string;
+    meta?: Record<string, unknown>;
+}
+interface LogFilter {
+    scope?: string[];
+    level?: LogLevel;
+    since?: Date;
+    until?: Date;
+    limit?: number;
+}
+declare class LogRingBuffer {
+    private readonly capacity;
+    private readonly buffer;
+    private head;
+    private count;
+    constructor(capacity?: number);
+    push(entry: LogEntry): void;
+    getAll(): LogEntry[];
+    query(filter: LogFilter): LogEntry[];
+}
+
+declare class ScopedLogger implements IScopedLogger {
+    private readonly scope;
+    private readonly writeFn;
+    constructor(scope: string[], writeFn: (entry: LogEntry) => void);
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    child(childScope: string): IScopedLogger;
+    private write;
+}
+
+interface AgentClientConfig {
+    readonly hubUrl: string;
+    readonly token?: string;
+    readonly logger: IScopedLogger;
+    readonly registrationInfo: AgentRegistrationInfo;
+}
+type MessageHandler = (msg: HubToAgentMessage) => void;
+type BinaryHandler = (data: Buffer) => void;
+type ConnectionHandler = () => void;
+/**
+ * WebSocket client for agent mode. Framework-agnostic (no NestJS).
+ * Connects to the hub, sends registration, handles messages,
+ * reconnects with exponential backoff.
+ */
+declare class AgentClient {
+    private ws;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private destroyed;
+    private readonly messageHandlers;
+    private readonly binaryHandlers;
+    private readonly connectHandlers;
+    private readonly disconnectHandlers;
+    private readonly logger;
+    private readonly hubUrl;
+    private readonly token?;
+    private readonly registrationInfo;
+    private runtimeStatus;
+    constructor(config: AgentClientConfig);
+    /** Connect to the hub WebSocket */
+    connect(): Promise<void>;
+    /** Disconnect and stop reconnecting */
+    disconnect(): void;
+    /** Send a JSON control message to the hub */
+    send(msg: AgentToHubMessage): void;
+    /** Send a binary frame to the hub */
+    sendBinary(data: Buffer): void;
+    /** Register a handler for JSON messages from hub */
+    onMessage(handler: MessageHandler): void;
+    /** Register a handler for binary frames from hub */
+    onBinaryFrame(handler: BinaryHandler): void;
+    /** Register a handler for successful connection */
+    onConnect(handler: ConnectionHandler): void;
+    /** Register a handler for disconnection */
+    onDisconnect(handler: ConnectionHandler): void;
+    /** Update the runtime status (used in heartbeat) */
+    updateStatus(status: AgentRuntimeStatus): void;
+    /** Whether currently connected */
+    get connected(): boolean;
+    private doConnect;
+    private handleBuiltinMessage;
+    private scheduleReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private clearTimers;
+}
+
+/**
+ * Receives task assignments from hub, routes to registered ITaskHandler instances.
+ * Maintains handler registry, manages task lifecycle.
+ * Framework-agnostic (no NestJS).
+ */
+declare class AgentTaskRunner {
+    private readonly agentId;
+    private readonly client;
+    private readonly handlers;
+    private readonly runningTasks;
+    private readonly logger;
+    constructor(agentId: string, client: AgentClient, logger: IScopedLogger);
+    /** Register a task handler for a given task type */
+    registerHandler(handler: ITaskHandler): void;
+    /** Unregister a task handler */
+    unregisterHandler(taskType: string): void;
+    /** Get all registered task types */
+    getTaskTypes(): readonly string[];
+    /** Get a handler by task type */
+    getHandler(taskType: string): ITaskHandler | undefined;
+    /**
+     * Execute a task dispatched from the hub.
+     * Sends result or error back to hub via the AgentClient.
+     */
+    executeTask(taskId: string, taskType: string, payload: unknown): Promise<void>;
+    /** Cancel a running task */
+    cancelTask(taskId: string): Promise<void>;
+    /** Number of currently running tasks */
+    get activeTaskCount(): number;
+    /** Destroy: cancel all running tasks */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Stub task handler for pipeline.decode.
+ * In the full implementation, this would start a StreamBroker for a camera
+ * and send decoded frames to the hub via the AgentClient.
+ */
+declare class DecodeTaskHandler implements ITaskHandler {
+    readonly taskType = "pipeline.decode";
+    readonly description = "Decode an RTSP stream and produce JPEG frames";
+    handle(payload: unknown, context: TaskContext): Promise<unknown>;
+    cancel(): Promise<void>;
+}
+/**
+ * Stub task handler for pipeline.detect.
+ * In the full implementation, this would receive frames (via binary WS),
+ * run them through the detection engine, and send results back.
+ */
+declare class DetectTaskHandler implements ITaskHandler {
+    readonly taskType = "pipeline.detect";
+    readonly description = "Run object detection on received frames";
+    handle(payload: unknown, context: TaskContext): Promise<unknown>;
+    cancel(): Promise<void>;
+}
+/**
+ * Stub task handler for pipeline.record.
+ * In the full implementation, this would start recording an RTSP stream
+ * to disk in segments and report segment metadata back to the hub.
+ */
+declare class RecordTaskHandler implements ITaskHandler {
+    readonly taskType = "pipeline.record";
+    readonly description = "Record an RTSP stream to disk segments";
+    handle(payload: unknown, context: TaskContext): Promise<unknown>;
+    cancel(): Promise<void>;
+}
+
+declare class FileSystemStorage implements IFileStorage$1 {
+    private readonly basePath;
+    constructor(basePath: string);
+    readFile(filePath: string): Promise<Buffer>;
+    writeFile(filePath: string, data: Buffer): Promise<void>;
+    deleteFile(filePath: string): Promise<void>;
+    listFiles(prefix?: string): Promise<readonly string[]>;
+    getFileUrl(_path: string): Promise<string>;
+    exists(filePath: string): Promise<boolean>;
+}
+declare class SqliteStorageProvider implements IStorageProvider$1 {
+    private mainDb;
+    private sharedStructured;
+    private readonly locations;
+    initialize(): Promise<void>;
+    /**
+     * Configure all storage locations.
+     * ONE single SQLite database (camstack.db) is used for ALL structured storage.
+     * File-based locations use the filesystem at their configured path.
+     */
+    configure(config: {
+        locations: Record<string, string>;
+    }): Promise<void>;
+    getLocation(name: StorageLocationName$1): IStorageLocation$1;
+    shutdown(): Promise<void>;
+    export(_locationName: StorageLocationName$1): Promise<Buffer>;
+    import(_locationName: StorageLocationName$1, _data: Buffer): Promise<void>;
+}
+
+declare class SqliteStorageAddon implements ICamstackAddon, IConfigurable {
+    readonly manifest: AddonManifest;
+    private provider;
+    initialize(context: AddonContext): Promise<void>;
+    shutdown(): Promise<void>;
+    getProvider(): SqliteStorageProvider;
+    getCapabilityProvider<K extends keyof CapabilityProviderMap>(name: K): CapabilityProviderMap[K] | null;
+    getConfigSchema(): ConfigUISchema;
+    getConfig(): Record<string, unknown>;
+    onConfigChange(_config: Record<string, unknown>): Promise<void>;
+}
+
+interface WinstonConfig {
+    readonly level: string;
+    readonly retentionDays: number;
+    /** Resolved absolute path to the logs directory (replaces the old dataPath field). */
+    readonly logsDir: string;
+}
+declare class WinstonDestination implements ILogDestination$1 {
+    private logger;
+    initialize(config?: WinstonConfig): Promise<void>;
+    write(entry: LogEntry$1): void;
+    query(_filter: LogFilter$1): Promise<readonly LogEntry$1[]>;
+    shutdown(): Promise<void>;
+}
+
+declare class WinstonLoggingAddon implements ICamstackAddon, IConfigurable {
+    readonly manifest: AddonManifest;
+    private destination;
+    private currentConfig;
+    initialize(context: AddonContext): Promise<void>;
+    shutdown(): Promise<void>;
+    getDestination(): WinstonDestination;
+    getCapabilityProvider<K extends keyof CapabilityProviderMap>(name: K): CapabilityProviderMap[K] | null;
+    getConfigSchema(): ConfigUISchema;
+    getConfig(): Record<string, unknown>;
+    onConfigChange(config: Record<string, unknown>): Promise<void>;
+}
+
+interface BackupManifest {
+    readonly id: string;
+    readonly timestamp: number;
+    readonly label?: string;
+    readonly locations: readonly string[];
+    readonly sizeMB: number;
+    readonly path: string;
+}
+interface BackupConfig {
+    readonly backupDir: string;
+    readonly retentionCount: number;
+}
+declare class LocalBackupService {
+    private readonly config;
+    private readonly logger;
+    private readonly eventBus;
+    private readonly storage;
+    private manifests;
+    constructor(config: BackupConfig, logger: IScopedLogger, eventBus: IEventBus, storage: IStorageLocation$1);
+    /** Create a backup of specified locations */
+    backup(options?: {
+        locations?: string[];
+        label?: string;
+    }): Promise<BackupManifest>;
+    /** Restore from a backup */
+    restore(backupId: string): Promise<void>;
+    /** List all backups sorted by timestamp descending */
+    list(): readonly BackupManifest[];
+    /** Delete a specific backup */
+    delete(backupId: string): Promise<void>;
+    private pruneOldBackups;
+}
+
+declare class LocalBackupAddon implements ICamstackAddon, IConfigurable {
+    readonly manifest: AddonManifest;
+    private service;
+    private currentConfig;
+    initialize(context: AddonContext): Promise<void>;
+    shutdown(): Promise<void>;
+    getService(): LocalBackupService;
+    getCapabilityProvider<K extends keyof CapabilityProviderMap>(name: K): CapabilityProviderMap[K] | null;
+    getConfigSchema(): ConfigUISchema;
+    getConfig(): Record<string, unknown>;
+    onConfigChange(config: Record<string, unknown>): Promise<void>;
+}
+
+declare class AdminUIAddon implements ICamstackAddon {
+    readonly id = "admin-ui";
+    readonly manifest: AddonManifest;
+    initialize(_ctx: AddonContext): Promise<void>;
+    shutdown(): Promise<void>;
+    getCapabilityProvider<K extends keyof CapabilityProviderMap>(name: K): CapabilityProviderMap[K] | null;
+}
+
+type ElementState = 'stopped' | 'starting' | 'running' | 'stopping' | 'error' | 'disabled';
+interface ElementStatus {
+    state: ElementState;
+    error?: string;
+    startedAt?: number;
+    stoppedAt?: number;
+    restartCount: number;
+    uptime: number;
+}
+declare class LifecycleStateMachine {
+    private readonly elementId;
+    private readonly elementType;
+    private readonly eventBus;
+    private readonly logger;
+    private _state;
+    private _error?;
+    private _startedAt?;
+    private _stoppedAt?;
+    private _restartCount;
+    private _hasStartedOnce;
+    constructor(elementId: string, elementType: 'provider' | 'device' | 'addon' | 'process', eventBus: IEventBus, logger: IScopedLogger);
+    get state(): ElementState;
+    getStatus(): ElementStatus;
+    transition(to: ElementState, error?: string): boolean;
+    incrementRestartCount(): void;
+    private isValidTransition;
+}
+
+interface FeatureManifest {
+    streaming: boolean;
+    notifications: boolean;
+    objectDetection: boolean;
+    remoteAccess: boolean;
+    agentCluster: boolean;
+    smartHome: boolean;
+    recordings: boolean;
+    backup: boolean;
+    repl: boolean;
+}
+type FeatureFlag = keyof FeatureManifest;
+type FeatureConfigReader = {
+    readonly features: FeatureManifest;
+};
+declare class FeatureManager {
+    private readonly configReader;
+    constructor(configReader: FeatureConfigReader);
+    isEnabled(flag: FeatureFlag): boolean;
+    getManifest(): FeatureManifest;
+}
+
+/** 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;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    agent: {
+        name: string;
+        statusPort: number;
+    };
+    auth: {
+        jwtSecret: string | null;
+        adminUsername: string;
+        adminPassword: string;
+    };
+    mode: "agent" | "hub";
+    hub: {
+        url: string;
+        token: string;
+    };
+    server: {
+        port: number;
+        host: string;
+        dataPath: string;
+    };
+}, {
+    agent?: {
+        name?: string | undefined;
+        statusPort?: number | undefined;
+    } | undefined;
+    auth?: {
+        jwtSecret?: string | null | undefined;
+        adminUsername?: string | undefined;
+        adminPassword?: string | undefined;
+    } | undefined;
+    mode?: "agent" | "hub" | undefined;
+    hub?: {
+        url?: string | undefined;
+        token?: string | undefined;
+    } | undefined;
+    server?: {
+        port?: number | undefined;
+        host?: string | undefined;
+        dataPath?: 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;
+    };
+    addons: {
+        enabled: string[];
+    };
+    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;
+}
+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;
+    /**
+     * Atomically update one top-level section of config.yaml and sync in-memory.
+     * Only bootstrap sections (server, auth) are persisted. Runtime settings should
+     * go to SQL (Plan B).
+     */
+    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;
+}
+
+declare class SystemEventBus implements IEventBus {
+    private readonly ringBuffer;
+    private readonly subscribers;
+    constructor(bufferSize?: number);
+    emit(event: SystemEvent): void;
+    subscribe(filter: EventFilter, handler: (event: SystemEvent) => void): () => void;
+    getRecent(filter?: EventFilter, limit?: number): readonly SystemEvent[];
+}
+
+interface ILogDestination {
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    write(entry: LogEntry): void;
+    query?(filter: LogFilter): Promise<readonly LogEntry[]>;
+}
+declare class LogManager {
+    private readonly ringBuffer;
+    private readonly destinations;
+    constructor(bufferSize?: number);
+    createLogger(scope: string): IScopedLogger;
+    addDestination(dest: ILogDestination): void;
+    removeDestination(dest: ILogDestination): void;
+    query(filter: LogFilter): LogEntry[];
+}
+
+interface IStorageBackend {
+    /** Backend type identifier */
+    readonly type: string;
+    /** Base path of this backend */
+    readonly basePath: string;
+    /** Resolve a subpath to an absolute path */
+    resolve(subpath: string): string;
+    /** Check if the backend path exists and is writable */
+    isAvailable(): boolean;
+    /** Ensure base directory exists (mkdir -p equivalent) */
+    initialize(): Promise<void>;
+}
+declare class FsStorageBackend implements IStorageBackend {
+    readonly type = "local";
+    readonly basePath: string;
+    constructor(basePath: string);
+    resolve(subpath: string): string;
+    isAvailable(): boolean;
+    initialize(): Promise<void>;
+}
+
+type StorageLocationName = 'data' | 'media' | 'recordings' | 'models' | 'cache' | 'logs';
+declare class StorageLocationManager {
+    private readonly backends;
+    private readonly dataPath;
+    constructor(dataPath: string);
+    /** Initialize all locations with default paths */
+    initializeDefaults(): Promise<void>;
+    /** Override a specific location's backend path */
+    setLocationPath(name: StorageLocationName, basePath: string): Promise<void>;
+    /** Get the backend for a location */
+    getBackend(name: StorageLocationName): IStorageBackend;
+    /** Resolve a path within a location */
+    resolve(location: StorageLocationName, subpath: string): string;
+    /** Check if all locations are available */
+    getStatus(): Array<{
+        name: StorageLocationName;
+        available: boolean;
+        path: string;
+    }>;
+    /** All location names */
+    getLocationNames(): StorageLocationName[];
+}
+
+interface IStorageProvider {
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    getLocation(name: StorageLocationName): IStorageLocation;
+    export(locationName: StorageLocationName): Promise<Buffer>;
+    import(locationName: StorageLocationName, data: Buffer): Promise<void>;
+}
+interface QueryFilter {
+    where?: Record<string, unknown>;
+    whereIn?: Record<string, unknown[]>;
+    whereBetween?: Record<string, [unknown, unknown]>;
+    orderBy?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    limit?: number;
+    offset?: number;
+}
+interface StorageRecord {
+    collection: string;
+    id: string;
+    data: Record<string, unknown>;
+}
+interface IStructuredStorage {
+    query(collection: string, filter?: QueryFilter): Promise<readonly StorageRecord[]>;
+    insert(record: StorageRecord): Promise<StorageRecord>;
+    update(collection: string, id: string, data: Record<string, unknown>): Promise<StorageRecord>;
+    delete(collection: string, id: string): Promise<void>;
+    count(collection: string, filter?: QueryFilter): Promise<number>;
+}
+interface IFileStorage {
+    readFile(path: string): Promise<Buffer>;
+    writeFile(path: string, data: Buffer): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    listFiles(prefix?: string): Promise<readonly string[]>;
+    getFileUrl(path: string): Promise<string>;
+    exists(path: string): Promise<boolean>;
+}
+interface IStorageLocation {
+    structured?: IStructuredStorage;
+    files?: IFileStorage;
+}
+declare class StorageManager {
+    private provider;
+    private locationManager;
+    setProvider(provider: IStorageProvider): void;
+    getProvider(): IStorageProvider;
+    /**
+     * Set the StorageLocationManager (called from main.ts during Phase 2 boot,
+     * before NestJS lifecycle hooks run).
+     */
+    setLocationManager(manager: StorageLocationManager): void;
+    /**
+     * Get the StorageLocationManager (for file path resolution).
+     * Available after Phase 2 boot (main.ts calls setLocationManager).
+     */
+    getLocationManager(): StorageLocationManager;
+    /**
+     * Initialize the StorageLocationManager with a dataPath and set it on this service.
+     * Called during 3-phase boot from main.ts (Phase 2).
+     */
+    initializeLocations(dataPath: string): Promise<void>;
+    /**
+     * Return the base filesystem path for a named storage location.
+     * Convenience wrapper around locationManager.getBackend(name).basePath.
+     * Available after Phase 2 boot (main.ts calls setLocationManager).
+     */
+    getLocationPath(name: StorageLocationName): string;
+    /**
+     * Get a storage location, optionally namespaced.
+     * Without namespace: returns the raw location (e.g., 'config' -> config DB)
+     * With namespace: returns a scoped view where all collections/paths are prefixed
+     *   e.g., getLocation('addon', 'providers/frigate-1') -> collections prefixed with 'providers/frigate-1/'
+     */
+    getLocation(name: StorageLocationName | string, namespace?: string): IStorageLocation;
+    private createNamespacedLocation;
+}
+
+/**
+ * Thin wrapper over better-sqlite3 that manages the four settings tables:
+ * system_settings, addon_settings, provider_settings, device_settings.
+ *
+ * All values are stored as JSON text and deserialized on read.
+ */
+declare class SettingsStore {
+    private readonly db;
+    constructor(dbPath: string);
+    getSystem(key: string): unknown;
+    setSystem(key: string, value: unknown): void;
+    getAllSystem(): Record<string, unknown>;
+    getAddon(addonId: string, key: string): unknown;
+    setAddon(addonId: string, key: string, value: unknown): void;
+    getAllAddon(addonId: string): Record<string, unknown>;
+    /** Bulk-replace all keys for an addon (within a transaction). */
+    setAllAddon(addonId: string, config: Record<string, unknown>): void;
+    getProvider(providerId: string, key: string): unknown;
+    setProvider(providerId: string, key: string, value: unknown): void;
+    getAllProvider(providerId: string): Record<string, unknown>;
+    getDevice(deviceId: string, key: string): unknown;
+    setDevice(deviceId: string, key: string, value: unknown): void;
+    getAllDevice(deviceId: string): Record<string, unknown>;
+    /** Close the SQLite connection (call on shutdown). */
+    close(): void;
+    /** Check if system_settings is empty (used for first-boot seeding). */
+    isSystemSettingsEmpty(): boolean;
+    /** Seed system_settings with RUNTIME_DEFAULTS (only on first boot). */
+    seedDefaults(): void;
+    private initTables;
+}
+
+/** Core table DDL statements -- executed on first boot */
+declare const CORE_TABLE_DDL: readonly string[];
+/** Addon table schema declaration */
+interface AddonTableSchema {
+    readonly name: string;
+    readonly columns: ReadonlyArray<{
+        readonly name: string;
+        readonly type: 'TEXT' | 'INTEGER' | 'REAL' | 'JSON';
+        readonly primaryKey?: boolean;
+        readonly notNull?: boolean;
+    }>;
+    readonly indexes?: ReadonlyArray<{
+        readonly name: string;
+        readonly columns: readonly string[];
+        readonly unique?: boolean;
+    }>;
+}
+/** Generate CREATE TABLE DDL from addon schema */
+declare function addonTableToDdl(schema: AddonTableSchema): string[];
+
+/**
+ * Manages scoped API tokens with restricted addon/route/capability access.
+ * Framework-agnostic — dependencies injected via constructor.
+ */
+declare class ScopedTokenManager {
+    private readonly storage;
+    constructor(storage: IStructuredStorage);
+    /**
+     * Create a new scoped token. Returns the raw token string (shown once)
+     * and the stored record (with hash, not the raw token).
+     */
+    create(userId: string, name: string, scopes: TokenScope[], expiresAt?: number): Promise<{
+        token: string;
+        record: ScopedToken;
+    }>;
+    /**
+     * Validate a raw token string. Returns the token record if valid, null otherwise.
+     */
+    validate(rawToken: string): Promise<ScopedToken | null>;
+    /**
+     * Check whether a token's scopes grant access to the given addon, route, or capability.
+     */
+    matchesScope(token: ScopedToken, addonId?: string, routePath?: string, capability?: string): boolean;
+    /**
+     * Revoke a token by ID.
+     */
+    revoke(tokenId: string): Promise<void>;
+    /**
+     * List all tokens for a user (without exposing the raw token).
+     */
+    listForUser(userId: string): Promise<ScopedToken[]>;
+    /**
+     * Update the lastUsedAt timestamp for a token.
+     */
+    updateLastUsed(tokenId: string): Promise<void>;
+}
+
+type UserRole = 'super_admin' | 'admin' | 'viewer';
+interface TokenPayload {
+    type?: 'api_key';
+    keyId?: string;
+    userId?: string;
+    username?: string;
+    role: UserRole;
+    allowedProviders: string[] | '*';
+    allowedDevices: Record<string, string[] | '*'>;
+    iat?: number;
+    exp?: number;
+}
+type AuthConfigReader = {
+    get<T>(path: string): T;
+    update(section: string, data: Record<string, unknown>): void;
+};
+declare class AuthManager {
+    private readonly config;
+    private readonly jwtSecret;
+    private scopedTokenManager;
+    constructor(config: AuthConfigReader);
+    signToken(payload: Omit<TokenPayload, 'iat' | 'exp'>): string;
+    verifyToken(token: string): TokenPayload;
+    hashPassword(password: string): Promise<string>;
+    comparePassword(password: string, hash: string): Promise<boolean>;
+    generateApiKey(): {
+        token: string;
+        hash: string;
+        prefix: string;
+    };
+    validateApiKey(token: string, storedHash: string): boolean;
+    /**
+     * Set the scoped token manager for the auth chain.
+     */
+    setScopedTokenManager(manager: ScopedTokenManager): void;
+    /**
+     * Validate a scoped token string.
+     * Returns the token record if valid, null otherwise.
+     */
+    validateScopedToken(rawToken: string): Promise<ScopedToken | null>;
+    /**
+     * Check whether a scoped token grants access to a given addon/route/capability.
+     */
+    matchesScopedTokenScope(token: ScopedToken, addonId?: string, routePath?: string, capability?: string): boolean;
+}
+
+interface ApiKeyRecord {
+    id: string;
+    label: string;
+    role: UserRole;
+    allowedProviders: string[] | '*';
+    allowedDevices: Record<string, string[] | '*'>;
+    tokenHash: string;
+    tokenPrefix: string;
+    createdAt: number;
+    lastUsedAt?: number;
+}
+interface CreateApiKeyInput {
+    label: string;
+    role: UserRole;
+    allowedProviders?: string[] | '*';
+    allowedDevices?: Record<string, string[] | '*'>;
+}
+type ApiKeyStorageAccess = {
+    getStructuredStorage(): IStructuredStorage;
+};
+declare class ApiKeyManager {
+    private readonly storageAccess;
+    private readonly auth;
+    constructor(storageAccess: ApiKeyStorageAccess, auth: AuthManager);
+    private get structured();
+    create(input: CreateApiKeyInput): Promise<{
+        record: ApiKeyRecord;
+        token: string;
+    }>;
+    validateToken(token: string): Promise<ApiKeyRecord | null>;
+    listAll(): Promise<Omit<ApiKeyRecord, 'tokenHash'>[]>;
+    revoke(id: string): Promise<void>;
+    findById(id: string): Promise<ApiKeyRecord | null>;
+}
+
+interface UserRecord {
+    id: string;
+    username: string;
+    passwordHash: string;
+    role: UserRole;
+    allowedProviders: string[] | '*';
+    allowedDevices: Record<string, string[] | '*'>;
+    createdAt: number;
+    updatedAt: number;
+}
+interface CreateUserInput {
+    username: string;
+    password: string;
+    role: UserRole;
+    allowedProviders?: string[] | '*';
+    allowedDevices?: Record<string, string[] | '*'>;
+}
+type UpdatableUserFields = Partial<Pick<UserRecord, 'role' | 'allowedProviders' | 'allowedDevices'>>;
+type UserStorageAccess = {
+    getStructuredStorage(): IStructuredStorage;
+};
+type UserConfigReader = {
+    get<T>(path: string): T;
+};
+declare class UserManager {
+    private readonly storageAccess;
+    private readonly auth;
+    private readonly config;
+    constructor(storageAccess: UserStorageAccess, auth: AuthManager, config: UserConfigReader);
+    private get structured();
+    create(input: CreateUserInput): Promise<UserRecord>;
+    findByUsername(username: string): Promise<UserRecord | null>;
+    findById(id: string): Promise<UserRecord | null>;
+    validateCredentials(username: string, password: string): Promise<UserRecord | null>;
+    listAll(): Promise<Omit<UserRecord, 'passwordHash'>[]>;
+    update(id: string, data: UpdatableUserFields): Promise<void>;
+    delete(id: string): Promise<void>;
+    resetPassword(id: string, newPassword: string): Promise<void>;
+    ensureAdminExists(): Promise<void>;
+}
+
+/**
+ * Central notification service that routes notifications to configured outputs.
+ * Framework-agnostic — dependencies injected via constructor.
+ *
+ * Outputs are resolved from the CapabilityRegistry's 'notification-output'
+ * collection on each call (proxy pattern). Falls back to a local map
+ * when no registry is provided (backward compat).
+ */
+declare class NotificationService {
+    private readonly logger;
+    private readonly localOutputs;
+    private readonly routing;
+    private readonly rateLimits;
+    private readonly lastSent;
+    private registry;
+    constructor(logger: IScopedLogger);
+    /** Set the registry for live output lookup. Called once during boot. */
+    setRegistry(registry: CapabilityRegistry): void;
+    /** Resolve all outputs — prefers registry, falls back to local map */
+    private get outputs();
+    /** @deprecated Use registry-based resolution. Kept for backward compat only. */
+    addOutput(output: INotificationOutput): void;
+    /** @deprecated Use registry-based resolution. Kept for backward compat only. */
+    removeOutput(id: string): void;
+    setRouting(category: string, outputIds: string[]): void;
+    setRateLimit(category: string, minIntervalMs: number): void;
+    notify(notification: Notification): Promise<void>;
+    getOutputs(): ReadonlyArray<{
+        id: string;
+        name: string;
+        icon: string;
+    }>;
+    getRouting(): ReadonlyMap<string, string[]>;
+    getOutput(id: string): INotificationOutput | undefined;
+}
+
+type Unsubscribe = () => void;
+/**
+ * Service for broadcasting toast notifications to connected UI clients.
+ * Framework-agnostic — integrates with tRPC subscriptions via subscribe().
+ */
+declare class ToastService {
+    private readonly listeners;
+    /**
+     * Subscribe to toast events for a specific user.
+     * Returns an unsubscribe function.
+     */
+    subscribe(connectionId: string, userId: string, callback: (toast: Toast) => void): Unsubscribe;
+    /**
+     * Broadcast a toast to all connected clients.
+     */
+    broadcast(toast: Toast): void;
+    /**
+     * Send a toast to a specific user's connections only.
+     */
+    sendToUser(userId: string, toast: Toast): void;
+}
+
+interface RouteMatch {
+    readonly route: IAddonHttpRoute;
+    readonly addonId: string;
+    readonly params: Record<string, string>;
+}
+/**
+ * Registry for dynamic HTTP routes registered by addons.
+ * Framework-agnostic — the server HTTP layer queries this registry to dispatch requests.
+ */
+declare class AddonRouteRegistry {
+    private readonly routes;
+    /**
+     * Register all routes from an addon's route provider.
+     */
+    registerRoutes(addonId: string, provider: IAddonRouteProvider): void;
+    /**
+     * Unregister all routes for an addon.
+     */
+    unregisterRoutes(addonId: string): void;
+    /**
+     * Match an incoming request method + path to a registered route.
+     * Supports simple path parameters (e.g., /items/:id).
+     */
+    matchRoute(method: string, path: string): RouteMatch | null;
+    /**
+     * List all registered routes across all addons.
+     */
+    listRoutes(): ReadonlyArray<{
+        addonId: string;
+        method: string;
+        path: string;
+        access: string;
+        description?: string;
+    }>;
+}
+
+interface IRegisteredDevice {
+    readonly id: string;
+    readonly name: string;
+    readonly providerId: string;
+    readonly capabilities: readonly string[];
+}
+declare class DeviceRegistry<T extends IRegisteredDevice = IRegisteredDevice> {
+    private readonly eventBus;
+    private readonly devices;
+    private readonly logger;
+    constructor(eventBus: IEventBus, loggingService: LoggerFactory);
+    registerDevice(device: T): void;
+    unregisterDevice(id: string): void;
+    getDevice(id: string): T | null;
+    listDevices(): T[];
+    getDevicesByProvider(providerId: string): T[];
+    getDevicesWithCapability(cap: string): T[];
+    registerProviderDevices(providerId: string, devices: readonly T[]): void;
+    unregisterProviderDevices(providerId: string): void;
+}
+
+interface IDeviceCapability {
+    kind: string;
+}
+interface CapabilityBinding {
+    source: 'native' | 'addon' | 'disabled';
+    addonId?: string;
+    config?: Record<string, unknown>;
+}
+interface IResolvableDevice {
+    readonly id: string;
+    readonly capabilities: string[];
+    getCapability<T extends IDeviceCapability>(cap: string): T | null;
+}
+interface IAddonRegistryAccess {
+    getAddon(addonId: string): unknown | null;
+}
+declare class CapabilityResolver {
+    private readonly addonRegistry;
+    private readonly bindings;
+    constructor(addonRegistry: IAddonRegistryAccess);
+    resolve<T extends IDeviceCapability>(device: IResolvableDevice, cap: string): T | null;
+    setBinding(deviceId: string, cap: string, binding: CapabilityBinding): void;
+    removeBinding(deviceId: string, cap: string): void;
+    getBindings(deviceId: string): Partial<Record<string, CapabilityBinding>>;
+    getEffectiveCapabilities(device: IResolvableDevice): string[];
+}
+
+/** Minimal device registry interface for provider management */
+type ProviderDeviceRegistry = {
+    registerProviderDevices(providerId: string, devices: readonly IRegistrableDevice[]): void;
+    unregisterProviderDevices(providerId: string): void;
+};
+interface IRegistrableDevice {
+    readonly id: string;
+    readonly name: string;
+    readonly providerId: string;
+    readonly capabilities: readonly string[];
+}
+interface ProviderStatus {
+    connected: boolean;
+    error?: string;
+    deviceCount: number;
+}
+interface LiveEvent {
+    type: string;
+    camera: string;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+interface IManagedProvider {
+    readonly id: string;
+    readonly type: string;
+    readonly name: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStatus(): ProviderStatus;
+    getDevices(): readonly IRegistrableDevice[];
+    subscribeLiveEvents(callback: (event: LiveEvent) => void): () => void;
+}
+interface ProviderListItem {
+    id: string;
+    type: string;
+    name: string;
+    status: ProviderStatus;
+    started: boolean;
+    lifecycle: ElementStatus;
+}
+declare class ProviderManager<P extends IManagedProvider = IManagedProvider> {
+    private readonly deviceRegistry;
+    private readonly eventBus;
+    private readonly loggingService;
+    private readonly providers;
+    private readonly logger;
+    constructor(deviceRegistry: ProviderDeviceRegistry, eventBus: IEventBus, loggingService: LoggerFactory);
+    registerProvider(provider: P): void;
+    startProvider(id: string): Promise<void>;
+    stopProvider(id: string): Promise<void>;
+    disableProvider(id: string): Promise<void>;
+    enableProvider(id: string): Promise<void>;
+    restartProvider(id: string): Promise<void>;
+    getProvider(id: string): P | null;
+    getProviderStatus(id: string): ElementStatus | null;
+    listProviders(): readonly ProviderListItem[];
+    shutdownAll(): Promise<void>;
+}
+
+export { AddonEngineManager, AddonInstaller, type AddonInstallerConfig, AddonLoader, AddonRouteRegistry, type AddonTableSchema, AdminUIAddon, AgentClient, type AgentClientConfig, type AgentEntry, type AgentEventEmitter, type AgentInfo, AgentRegistry, type AgentResources, type AgentStatus, type AgentTask, type AgentTaskResult, AgentTaskRunner, ApiKeyManager, type ApiKeyRecord, type ApiKeyStorageAccess, type AppConfig, type AuthConfigReader, AuthManager, BUILTIN_PACKAGES, type BackupConfig, type BackupManifest, type BinaryHandler, type BootstrapConfig, CORE_TABLE_DDL, type CapabilityBinding, CapabilityRegistry, CapabilityResolver, type ClientNetworkStats, ConfigManager, type ConnectionHandler, DecodeTaskHandler, DetectTaskHandler, type DeviceNetworkStats, DeviceRegistry, type ElementState, type ElementStatus, EventBus, type FeatureConfigReader, type FeatureFlag, FeatureManager, type FeatureManifest, FileSystemStorage, FsStorageBackend, type IAddonRegistryAccess, type IStorageProvider as ICoreStorageProvider, type IDeviceCapability, type IFileStorage, type ILogDestination, type IManagedProvider, INFRA_CAPABILITIES, type INetworkQualityTracker, type IRegisteredDevice, type IReplContextProvider, type IReplEngine, type IResolvableDevice, type ISettingsStore, type IStorageBackend, type IStorageLocation, type IStructuredStorage, type InfraCapability, type InstalledPackage, LifecycleStateMachine, LocalBackupAddon, LocalBackupService, type LogEntry, type LogFilter, type LogLevel, LogManager, LogRingBuffer, ManagedProcess, type ManagedProcessStatus, type MessageHandler, NetworkQualityTracker, NotificationService, PipelineRunner, PipelineValidator, type ProcessConfig, type ProcessEventEmitter, type ProcessLoggerFactory, ProcessManager, type ProcessState, type ProcessStats, type ProviderDeviceRegistry, type ProviderListItem, ProviderManager, PythonEnvManager, type QueryFilter, RUNTIME_DEFAULTS, RecordTaskHandler, type RegisteredAddon, ReplEngine, type ReplResult, type ReplScope, type ReplSessionContext, ScopedLogger, ScopedTokenManager, type ServerMode, SettingsStore, SqliteStorageAddon, SqliteStorageProvider, StorageLocationManager, type StorageLocationName, StorageManager, type StorageRecord, type StreamNetworkStats, SystemEventBus, type TaskDispatchOptions, TaskDispatcher, ToastService, type TokenPayload, type Unsubscribe, type UserConfigReader, UserManager, type UserRecord, type UserRole, type UserStorageAccess, type ValidationIssue, type ValidationResult, WinstonDestination, WinstonLoggingAddon, addonTableToDdl, bootstrapSchema, downloadModel, isInfraCapability };