@camstack/system 1.2.13 → 1.2.14

package/dist/kernel/config-schema.d.ts

@@ -5,8 +5,8 @@ export declare const DEFAULT_DATA_PATH = "camstack-data";
  *  All other settings live in SQL (system_settings table). */
 export declare const bootstrapSchema: z.ZodObject<{
     mode: z.ZodDefault<z.ZodEnum<{
-        agent: "agent";
         hub: "hub";
+        agent: "agent";
     }>>;
     server: z.ZodDefault<z.ZodObject<{
         port: z.ZodDefault<z.ZodNumber>;
@@ -70,7 +70,44 @@ export type AppConfig = BootstrapConfig & {
         retentionDays: number;
     };
     eventBus: {
+        /** System-EVENT ring size. Separate from the log buffer below. */
         ringBufferSize: number;
+        /**
+         * Per-addon log ring-buffer capacity, in entries. Default 5000.
+         *
+         * A HARD bound on EACH addon's bucket, not the total — the buffer is
+         * partitioned by `addonId` (`PartitionedLogBuffer`), so a chatty addon evicts
+         * only its own lines and a quiet one keeps its sparse history. Worst-case
+         * memory is therefore `this × number of addons that have logged`, which is
+         * why the total below exists.
+         *
+         * Hub-only: the agent constructs its `LogManager` with a hardcoded 5000.
+         */
+        perAddonLogBufferSize?: number;
+        /**
+         * SOFT ceiling on retained entries across every addon bucket. `null` (the
+         * default) means the per-addon rings are the only bound — the historical
+         * behaviour, unchanged unless you set this.
+         *
+         * Set it when `perAddonLogBufferSize × addons` is more than the box can spare:
+         * 70 addons × 5000 is 350k retained entries, which is a lot on a mini PC.
+         *
+         * Soft, and deliberately so: it is met by discarding only entries at or below
+         * `logBufferPruneLevel`. If pruning every prunable entry still leaves the total
+         * above this number, the buffer stays above it. A cap that could evict an
+         * `error` would trade the lines that explain an incident for lines about frame
+         * timings.
+         */
+        maxTotalLogBufferSize?: number | null;
+        /**
+         * Highest severity the total-cap sweep may discard. Default `debug`.
+         *
+         * `debug` reclaims nearly all the space on any busy buffer while leaving
+         * `info`/`warn`/`error` untouched. Raise it to `info` only if debug alone is
+         * not enough; `warn` and `error` are then still safe. Setting it to `error`
+         * means "evict anything", which defeats the point.
+         */
+        logBufferPruneLevel?: 'debug' | 'info' | 'warn' | 'error';
     };
     retention: {
         detectionEventsDays: number;

package/dist/logging/log-manager.d.ts

@@ -1,4 +1,5 @@
 import { LogEntry, LogFilter } from './log-ring-buffer.js';
+import { PartitionedLogBufferOptions } from './partitioned-log-buffer.js';
 import { IScopedLogger } from './scoped-logger.js';
 export interface ILogDestination {
     initialize(): Promise<void>;
@@ -11,10 +12,19 @@ export declare class LogManager {
     private readonly destinations;
     private readonly subscribers;
     private deviceNameLookup;
-    /** `perAddonCapacity` bounds EACH addon's bucket, not the total — a chatty
-     *  addon evicts only its own lines, so quiet addons keep their sparse history.
-     *  See {@link PartitionedLogBuffer}. */
-    constructor(perAddonCapacity?: number);
+    /**
+     * `perAddonCapacity` bounds EACH addon's bucket, not the total — a chatty addon
+     * evicts only its own lines, so quiet addons keep their sparse history.
+     *
+     * `options.maxTotalEntries` adds a soft ceiling across all buckets, because the
+     * per-bucket bound scales with addon count. When it is exceeded, only entries at
+     * or below `options.pruneLevel` (default `debug`) are discarded — `warn` and
+     * `error` are never evicted to satisfy it. Both default to the previous
+     * behaviour: no total cap. See {@link PartitionedLogBuffer}.
+     */
+    constructor(perAddonCapacity?: number, options?: PartitionedLogBufferOptions);
+    /** Entries currently retained across every bucket. */
+    bufferSize(): number;
     /**
      * Register a callback that resolves `deviceId → deviceName`. Called
      * for every emitted entry that carries `tags.deviceId` but no

package/dist/logging/log-ring-buffer.d.ts

@@ -44,4 +44,19 @@ export declare class LogRingBuffer {
      * gets removed.
      */
     clear(filter?: LogFilter): number;
+    /** Entries currently retained. */
+    size(): number;
+    /**
+     * Drop up to `max` entries, OLDEST first, whose level is at or below
+     * `threshold`. Returns how many were removed.
+     *
+     * This is what lets a total-memory cap be enforced without losing the entries
+     * that matter: sweeping `debug` reclaims almost all of the space (debug is the
+     * overwhelming majority of any busy buffer) while `warn` and `error` are never
+     * touched. Losing the one error line that explains an incident, in order to keep
+     * a thousand debug lines about frame timings, would be the wrong trade.
+     *
+     * Oldest-first because recent context is what an operator is looking at.
+     */
+    pruneOldestAtOrBelow(threshold: LogLevel, max: number): number;
 }

package/dist/logging/partitioned-log-buffer.d.ts

@@ -1,4 +1,15 @@
-import { LogEntry, LogFilter } from '@camstack/types';
+import { LogEntry, LogFilter, LogLevel } from '@camstack/types';
+export interface PartitionedLogBufferOptions {
+    /** Hard ring size for EACH addon's bucket. */
+    readonly perAddonCapacity?: number;
+    /**
+     * Soft ceiling on entries across all buckets. `null` (the default) means the
+     * only bound is the per-addon rings.
+     */
+    readonly maxTotalEntries?: number | null;
+    /** Highest severity the total-cap sweep may discard. Default `debug`. */
+    readonly pruneLevel?: LogLevel;
+}
 /**
  * A log buffer partitioned into one fixed-capacity {@link LogRingBuffer} per
  * `addonId`. A chatty addon (e.g. detection-pipeline) only ever evicts its OWN
@@ -6,16 +17,48 @@ import { LogEntry, LogFilter } from '@camstack/types';
  * survive far longer than they would in a single shared FIFO ring.
  *
  * Drop-in for {@link LogRingBuffer} from {@link LogManager}'s perspective —
- * exposes the same `push` / `getAll` / `query` / `clear` surface. Total memory
- * is bounded by `perAddonCapacity × (number of distinct addons seen)`; quiet
- * buckets never grow past the handful of lines they actually emit.
+ * exposes the same `push` / `getAll` / `query` / `clear` surface.
+ *
+ * ## Two bounds, doing different jobs
+ *
+ * **`perAddonCapacity`** is a HARD bound: each bucket is a fixed-size ring, so
+ * total memory can never exceed `perAddonCapacity × buckets` whatever else
+ * happens. This is the safety net.
+ *
+ * **`maxTotalEntries`** is a SOFT target across all buckets, and it exists because
+ * the hard bound scales with addon count — 70 addons × 5000 is a lot of retained
+ * entries on a small box. When the total is exceeded, the sweep discards only
+ * entries at or below `pruneLevel` (default `debug`), oldest first, from the
+ * largest buckets first.
+ *
+ * It is deliberately soft. Meeting a total cap by discarding `warn` and `error`
+ * would trade the entries that explain an incident for entries about frame
+ * timings; if pruning every prunable entry still leaves the total above the cap,
+ * the buffer stays above it and the hard per-bucket bound is what holds. A cap
+ * that can evict an error is not a feature.
+ *
+ * Largest-bucket-first because the noisy addon is the one creating the pressure —
+ * the same principle that motivated partitioning in the first place.
  */
 export declare class PartitionedLogBuffer {
-    private readonly perAddonCapacity;
     private readonly buffers;
-    constructor(perAddonCapacity?: number);
+    private readonly perAddonCapacity;
+    private readonly maxTotalEntries;
+    private readonly pruneLevel;
+    /** Running total, so `push` does not walk every bucket to decide. */
+    private totalEntries;
+    constructor(perAddonCapacity?: number, options?: PartitionedLogBufferOptions);
     private bufferFor;
     push(entry: LogEntry): void;
+    /**
+     * Bring the total down to `PRUNE_TARGET_RATIO × cap` by discarding prunable
+     * entries, largest bucket first. Stops early when nothing prunable is left —
+     * see the class docblock on why that is the correct outcome rather than a
+     * failure to enforce.
+     */
+    private enforceTotalCap;
+    /** Entries retained across every bucket. */
+    size(): number;
     /** Every retained entry across all buckets, newest-first (mirrors
      *  {@link LogRingBuffer.getAll}). Used to replay history to a destination. */
     getAll(): LogEntry[];

package/dist/{manifest-python-deps-1I7WdPDD.js → manifest-python-deps-DSrmih6E.js}

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_dist = require("./dist-BQOCTD5b.js");
+const require_dist = require("./dist-yttC1aUI.js");
 let _camstack_types_node = require("@camstack/types/node");
 let node_http = require("node:http");
 let node_fs = require("node:fs");

package/dist/{manifest-python-deps-I2MGvDvo.mjs → manifest-python-deps-bn3qrsxR.mjs}

@@ -1,4 +1,4 @@
-import { J as readNodePin } from "./dist-DpKeSZel.mjs";
+import { Y as readNodePin } from "./dist-eOaraBhT.mjs";
 import { ensureBinary, ensureFfmpeg, ensurePython, installPythonPackages, installPythonRequirements } from "@camstack/types/node";
 import { createServer } from "node:http";
 import * as fs from "node:fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.13",
+  "version": "1.2.14",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",
@@ -81,6 +81,18 @@
           }
         ]
       },
+      {
+        "id": "loki-logging",
+        "category": "system",
+        "name": "Loki Logging",
+        "description": "Opt-in log destination — batches this node's log entries and pushes them to a Grafana Loki instance via /loki/api/v1/push. Registered always, inert until enabled with a URL.",
+        "entry": "./dist/builtins/loki-logging/index.js",
+        "capabilities": [
+          {
+            "name": "log-destination"
+          }
+        ]
+      },
       {
         "id": "hub-forwarder",
         "category": "system",