@dbx-tools/appkit-lakebox 0.0.0-stage → 0.9.132

package/lib/src/metrics.js

@@ -0,0 +1,151 @@
+import { EventEmitter } from "node:events";
+import { errorUtils, log } from "@dbx-tools/shared-core";
+const logger = log.logger("appkit-lakebox:metrics");
+const DEFAULT_CAPACITY = 120;
+/**
+ * In-process metrics emitter for the app Lakebox.
+ *
+ * Sampling runs only between {@link start} and {@link stop}, which the runtime
+ * ties to the Lakebox running state. Samples contain machine-level CPU,
+ * memory, persistent storage, and network counters; they never contain
+ * process names, arguments, environment, or per-process usage.
+ */
+export class LakeboxMetrics extends EventEmitter {
+    read;
+    intervalMs;
+    capacity;
+    samples = [];
+    previous;
+    timer;
+    controller;
+    /** Creates a stopped emitter that reads raw counters with `read`. */
+    constructor(read, intervalMs, capacity = DEFAULT_CAPACITY) {
+        super();
+        this.read = read;
+        this.intervalMs = intervalMs;
+        this.capacity = capacity;
+    }
+    /** Whether sampling is active. */
+    get running() {
+        return this.controller !== undefined;
+    }
+    /** Recent samples, oldest first. */
+    series() {
+        return [...this.samples];
+    }
+    /** Seeds one validated sample without starting the recurring sampler or emitting an event. */
+    seed(output, at = Date.now()) {
+        const snapshot = this.record(parseLakeboxCounters(output, at), false);
+        return snapshot;
+    }
+    /** Starts sampling. Repeated calls are ignored. */
+    start() {
+        if (this.controller)
+            return;
+        this.controller = new AbortController();
+        void this.tick(this.controller.signal);
+    }
+    /** Stops sampling and clears the series. */
+    stop() {
+        this.controller?.abort();
+        this.controller = undefined;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.previous = undefined;
+        this.samples.length = 0;
+    }
+    async tick(signal) {
+        try {
+            const counters = parseLakeboxCounters(await this.read(signal));
+            if (signal.aborted)
+                return;
+            this.record(counters, true);
+        }
+        catch (error) {
+            if (!signal.aborted) {
+                logger.debug("Lakebox metrics sample failed", { error: errorUtils.toError(error) });
+            }
+        }
+        if (signal.aborted)
+            return;
+        this.timer = setTimeout(() => void this.tick(signal), this.intervalMs);
+        this.timer.unref?.();
+    }
+    record(counters, emit) {
+        const snapshot = toSnapshot(counters, this.previous);
+        this.previous = counters;
+        this.samples.push(snapshot);
+        if (this.samples.length > this.capacity)
+            this.samples.shift();
+        if (emit)
+            this.emit("snapshot", snapshot);
+        return snapshot;
+    }
+}
+/**
+ * Parses the package-owned metrics command output.
+ *
+ * @throws When a required counter is missing.
+ */
+export function parseLakeboxCounters(output, at = Date.now()) {
+    const lines = new Map();
+    for (const line of output.split("\n")) {
+        const [key, ...values] = line.trim().split(/\s+/);
+        if (key)
+            lines.set(key.replace(/:$/, ""), values.map(Number));
+    }
+    const value = (key, index = 0) => {
+        const entry = lines.get(key)?.[index];
+        if (entry === undefined || !Number.isFinite(entry)) {
+            throw new Error(`Lakebox metrics output is missing ${key}`);
+        }
+        return entry;
+    };
+    const cpu = lines.get("cpu") ?? [];
+    const idle = (cpu[3] ?? 0) + (cpu[4] ?? 0);
+    const total = cpu
+        .slice(0, 8)
+        .reduce((sum, entry) => sum + (Number.isFinite(entry) ? entry : 0), 0);
+    return {
+        at,
+        cores: value("cores"),
+        cpuBusy: total - idle,
+        cpuTotal: total,
+        load1: value("load"),
+        memoryTotalBytes: value("MemTotal") * 1024,
+        memoryAvailableBytes: value("MemAvailable") * 1024,
+        storageTotalBytes: value("storage", 0),
+        storageUsedBytes: value("storage", 1),
+        rxBytes: value("network", 0),
+        txBytes: value("network", 1),
+    };
+}
+/** Converts cumulative counters to one snapshot using the previous sample for rates. */
+export function toSnapshot(current, previous) {
+    const seconds = previous ? Math.max((current.at - previous.at) / 1_000, 0.001) : 0;
+    const cpuTotal = previous ? current.cpuTotal - previous.cpuTotal : 0;
+    const cpuBusy = previous ? current.cpuBusy - previous.cpuBusy : 0;
+    const rate = (now, before) => previous && before !== undefined ? Math.max(0, (now - before) / seconds) : 0;
+    return {
+        at: new Date(current.at).toISOString(),
+        cpu: {
+            cores: current.cores,
+            usedPercent: cpuTotal > 0 ? clamp((cpuBusy / cpuTotal) * 100) : 0,
+            load1: current.load1,
+        },
+        memory: {
+            totalBytes: current.memoryTotalBytes,
+            usedBytes: Math.max(0, current.memoryTotalBytes - current.memoryAvailableBytes),
+        },
+        storage: { totalBytes: current.storageTotalBytes, usedBytes: current.storageUsedBytes },
+        network: {
+            rxBytesPerSecond: rate(current.rxBytes, previous?.rxBytes),
+            txBytesPerSecond: rate(current.txBytes, previous?.txBytes),
+        },
+    };
+}
+function clamp(value) {
+    return Math.min(100, Math.max(0, Math.round(value * 10) / 10));
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWV0cmljcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9tZXRyaWNzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDM0MsT0FBTyxFQUFFLFVBQVUsRUFBRSxHQUFHLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUd6RCxNQUFNLE1BQU0sR0FBRyxHQUFHLENBQUMsTUFBTSxDQUFDLHdCQUF3QixDQUFDLENBQUM7QUFDcEQsTUFBTSxnQkFBZ0IsR0FBRyxHQUFHLENBQUM7QUFzQjdCOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLE9BQU8sY0FBZSxTQUFRLFlBQWtDO0lBUWpEO0lBQ0E7SUFDQTtJQVRGLE9BQU8sR0FBNkIsRUFBRSxDQUFDO0lBQ2hELFFBQVEsQ0FBbUI7SUFDM0IsS0FBSyxDQUFpQztJQUN0QyxVQUFVLENBQW1CO0lBRXJDLHFFQUFxRTtJQUNyRSxZQUNtQixJQUE4QyxFQUM5QyxVQUFrQixFQUNsQixXQUFXLGdCQUFnQjtRQUU1QyxLQUFLLEVBQUUsQ0FBQztRQUpTLFNBQUksR0FBSixJQUFJLENBQTBDO1FBQzlDLGVBQVUsR0FBVixVQUFVLENBQVE7UUFDbEIsYUFBUSxHQUFSLFFBQVEsQ0FBbUI7SUFHOUMsQ0FBQztJQUVELGtDQUFrQztJQUNsQyxJQUFJLE9BQU87UUFDVCxPQUFPLElBQUksQ0FBQyxVQUFVLEtBQUssU0FBUyxDQUFDO0lBQ3ZDLENBQUM7SUFFRCxvQ0FBb0M7SUFDcEMsTUFBTTtRQUNKLE9BQU8sQ0FBQyxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUMzQixDQUFDO0lBRUQsOEZBQThGO0lBQzlGLElBQUksQ0FBQyxNQUFjLEVBQUUsRUFBRSxHQUFHLElBQUksQ0FBQyxHQUFHLEVBQUU7UUFDbEMsTUFBTSxRQUFRLEdBQUcsSUFBSSxDQUFDLE1BQU0sQ0FBQyxvQkFBb0IsQ0FBQyxNQUFNLEVBQUUsRUFBRSxD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S0FBSyxDQUFDLEtBQUssR0FBRyxFQUFFLENBQUMsR0FBRyxFQUFFLENBQUMsQ0FBQyxDQUFDO0FBQ2pFLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBFdmVudEVtaXR0ZXIgfSBmcm9tIFwibm9kZTpldmVudHNcIjtcbmltcG9ydCB7IGVycm9yVXRpbHMsIGxvZyB9IGZyb20gXCJAZGJ4LXRvb2xzL3NoYXJlZC1jb3JlXCI7XG5pbXBvcnQgdHlwZSB7IExha2Vib3hNZXRyaWNzU25hcHNob3QgfSBmcm9tIFwiQGRieC10b29scy9zaGFyZWQtbGFrZWJveFwiO1xuXG5jb25zdCBsb2dnZXIgPSBsb2cubG9nZ2VyKFwiYXBwa2l0LWxha2Vib3g6bWV0cmljc1wiKTtcbmNvbnN0IERFRkFVTFRfQ0FQQUNJVFkgPSAxMjA7XG5cbi8qKiBSYXcgY3VtdWxhdGl2ZSBjb3VudGVycyByZWFkIGZyb20gb25lIHNhbXBsZS4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgTGFrZWJveENvdW50ZXJzIHtcbiAgYXQ6IG51bWJlcjtcbiAgY29yZXM6IG51bWJlcjtcbiAgY3B1QnVzeTogbnVtYmVyO1xuICBjcHVUb3RhbDogbnVtYmVyO1xuICBsb2FkMTogbnVtYmVyO1xuICBtZW1vcnlUb3RhbEJ5dGVzOiBudW1iZXI7XG4gIG1lbW9yeUF2YWlsYWJsZUJ5dGVzOiBudW1iZXI7XG4gIHN0b3JhZ2VUb3RhbEJ5dGVzOiBudW1iZXI7XG4gIHN0b3JhZ2VVc2VkQnl0ZXM6IG51bWJlcjtcbiAgcnhCeXRlczogbnVtYmVyO1xuICB0eEJ5dGVzOiBudW1iZXI7XG59XG5cbi8qKiBFdmVudHMgZW1pdHRlZCBieSB7QGxpbmsgTGFrZWJveE1ldHJpY3N9LiAqL1xuZXhwb3J0IGludGVyZmFjZSBMYWtlYm94TWV0cmljc0V2ZW50cyB7XG4gIHNuYXBzaG90OiBbTGFrZWJveE1ldHJpY3NTbmFwc2hvdF07XG59XG5cbi8qKlxuICogSW4tcHJvY2VzcyBtZXRyaWNzIGVtaXR0ZXIgZm9yIHRoZSBhcHAgTGFrZWJveC5cbiAqXG4gKiBTYW1wbGluZyBydW5zIG9ubHkgYmV0d2VlbiB7QGxpbmsgc3RhcnR9IGFuZCB7QGxpbmsgc3RvcH0sIHdoaWNoIHRoZSBydW50aW1lXG4gKiB0aWVzIHRvIHRoZSBMYWtlYm94IHJ1bm5pbmcgc3RhdGUuIFNhbXBsZXMgY29udGFpbiBtYWNoaW5lLWxldmVsIENQVSxcbiAqIG1lbW9yeSwgcGVyc2lzdGVudCBzdG9yYWdlLCBhbmQgbmV0d29yayBjb3VudGVyczsgdGhleSBuZXZlciBjb250YWluXG4gKiBwcm9jZXNzIG5hbWVzLCBhcmd1bWVudHMsIGVudmlyb25tZW50LCBvciBwZXItcHJvY2VzcyB1c2FnZS5cbiAqL1xuZXhwb3J0IGNsYXNzIExha2Vib3hNZXRyaWNzIGV4dGVuZHMgRXZlbnRFbWl0dGVyPExha2Vib3hNZXRyaWNzRXZlbnRzPiB7XG4gIHByaXZhdGUgcmVhZG9ubHkgc2FtcGxlczogTGFrZWJveE1ldHJpY3NTbmFwc2hvdFtdID0gW107XG4gIHByaXZhdGUgcHJldmlvdXM/OiBMYWtlYm94Q291bnRlcnM7XG4gIHByaXZhdGUgdGltZXI/OiBSZXR1cm5UeXBlPHR5cGVvZiBzZXRUaW1lb3V0PjtcbiAgcHJpdmF0ZSBjb250cm9sbGVyPzogQWJvcnRDb250cm9sbGVyO1xuXG4gIC8qKiBDcmVhdGVzIGEgc3RvcHBlZCBlbWl0dGVyIHRoYXQgcmVhZHMgcmF3IGNvdW50ZXJzIHdpdGggYHJlYWRgLiAqL1xuICBjb25zdHJ1Y3RvcihcbiAgICBwcml2YXRlIHJlYWRvbmx5IHJlYWQ6IChzaWduYWw6IEFib3J0U2lnbmFsKSA9PiBQcm9taXNlPHN0cmluZz4sXG4gICAgcHJpdmF0ZSByZWFkb25seSBpbnRlcnZhbE1zOiBudW1iZXIsXG4gICAgcHJpdmF0ZSByZWFkb25seSBjYXBhY2l0eSA9IERFRkFVTFRfQ0FQQUNJVFksXG4gICkge1xuICAgIHN1cGVyKCk7XG4gIH1cblxuICAvKiogV2hldGhlciBzYW1wbGluZyBpcyBhY3RpdmUuICovXG4gIGdldCBydW5uaW5nKCk6IGJvb2xlYW4ge1xuICAgIHJldHVybiB0aGlzLmNvbnRyb2xsZXIgIT09IHVuZGVmaW5lZDtcbiAgfVxuXG4gIC8qKiBSZWNlbnQgc2FtcGxlcywgb2xkZXN0IGZpcnN0LiAqL1xuICBzZXJpZXMoKTogcmVhZG9ubHkgTGFrZWJveE1ldHJpY3NTbmFwc2hvdFtdIHtcbiAgICByZXR1cm4gWy4uLnRoaXMuc2FtcGxlc107XG4gIH1cblxuICAvKiogU2VlZHMgb25lIHZhbGlkYXRlZCBzYW1wbGUgd2l0aG91dCBzdGFydGluZyB0aGUgcmVjdXJyaW5nIHNhbXBsZXIgb3IgZW1pdHRpbmcgYW4gZXZlbnQuICovXG4gIHNlZWQob3V0cHV0OiBzdHJpbmcsIGF0ID0gRGF0ZS5ub3coKSk6IExha2Vib3hNZXRyaWNzU25hcHNob3Qge1xuICAgIGNvbnN0IHNuYXBzaG90ID0gdGhpcy5yZWNvcmQocGFyc2VMYWtlYm94Q291bnRlcnMob3V0cHV0LCBhdCksIGZhbHNlKTtcbiAgICByZXR1cm4gc25hcHNob3Q7XG4gIH1cblxuICAvKiogU3RhcnRzIHNhbXBsaW5nLiBSZXBlYXRlZCBjYWxscyBhcmUgaWdub3JlZC4gKi9cbiAgc3RhcnQoKTogdm9pZCB7XG4gICAgaWYgKHRoaXMuY29udHJvbGxlcikgcmV0dXJuO1xuICAgIHRoaXMuY29udHJvbGxlciA9IG5ldyBBYm9ydENvbnRyb2xsZXIoKTtcbiAgICB2b2lkIHRoaXMudGljayh0aGlzLmNvbnRyb2xsZXIuc2lnbmFsKTtcbiAgfVxuXG4gIC8qKiBTdG9wcyBzYW1wbGluZyBhbmQgY2xlYXJzIHRoZSBzZXJpZXMuICovXG4gIHN0b3AoKTogdm9pZCB7XG4gICAgdGhpcy5jb250cm9sbGVyPy5hYm9ydCgpO1xuICAgIHRoaXMuY29udHJvbGxlciA9IHVuZGVmaW5lZDtcbiAgICBpZiAodGhpcy50aW1lcikgY2xlYXJUaW1lb3V0KHRoaXMudGltZXIpO1xuICAgIHRoaXMudGltZXIgPSB1bmRlZmluZWQ7XG4gICAgdGhpcy5wcmV2aW91cyA9IHVuZGVmaW5lZDtcbiAgICB0aGlzLnNhbXBsZXMubGVuZ3RoID0gMDtcbiAgfVxuXG4gIHByaXZhdGUgYXN5bmMgdGljayhzaWduYWw6IEFib3J0U2lnbmFsKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgdHJ5IHtcbiAgICAgIGNvbnN0IGNvdW50ZXJzID0gcGFyc2VMYWtlYm94Q291bnRlcnMoYXdhaXQgdGhpcy5yZWFkKHNpZ25hbCkpO1xuICAgICAgaWYgKHNpZ25hbC5hYm9ydGVkKSByZXR1cm47XG4gICAgICB0aGlzLnJlY29yZChjb3VudGVycywgdHJ1ZSk7XG4gICAgfSBjYXRjaCAoZXJyb3IpIHtcbiAgICAgIGlmICghc2lnbmFsLmFib3J0ZWQpIHtcbiAgICAgICAgbG9nZ2VyLmRlYnVnKFwiTGFrZWJveCBtZXRyaWNzIHNhbXBsZSBmYWlsZWRcIiwgeyBlcnJvcjogZXJyb3JVdGlscy50b0Vycm9yKGVycm9yKSB9KTtcbiAgICAgIH1cbiAgICB9XG4gICAgaWYgKHNpZ25hbC5hYm9ydGVkKSByZXR1cm47XG4gICAgdGhpcy50aW1lciA9IHNldFRpbWVvdXQoKCkgPT4gdm9pZCB0aGlzLnRpY2soc2lnbmFsKSwgdGhpcy5pbnRlcnZhbE1zKTtcbiAgICB0aGlzLnRpbWVyLnVucmVmPy4oKTtcbiAgfVxuXG4gIHByaXZhdGUgcmVjb3JkKGNvdW50ZXJzOiBMYWtlYm94Q291bnRlcnMsIGVtaXQ6IGJvb2xlYW4pOiBMYWtlYm94TWV0cmljc1NuYXBzaG90IHtcbiAgICBjb25zdCBzbmFwc2hvdCA9IHRvU25hcHNob3QoY291bnRlcnMsIHRoaXMucHJldmlvdXMpO1xuICAgIHRoaXMucHJldmlvdXMgPSBjb3VudGVycztcbiAgICB0aGlzLnNhbXBsZXMucHVzaChzbmFwc2hvdCk7XG4gICAgaWYgKHRoaXMuc2FtcGxlcy5sZW5ndGggPiB0aGlzLmNhcGFjaXR5KSB0aGlzLnNhbXBsZXMuc2hpZnQoKTtcbiAgICBpZiAoZW1pdCkgdGhpcy5lbWl0KFwic25hcHNob3RcIiwgc25hcHNob3QpO1xuICAgIHJldHVybiBzbmFwc2hvdDtcbiAgfVxufVxuXG4vKipcbiAqIFBhcnNlcyB0aGUgcGFja2FnZS1vd25lZCBtZXRyaWNzIGNvbW1hbmQgb3V0cHV0LlxuICpcbiAqIEB0aHJvd3MgV2hlbiBhIHJlcXVpcmVkIGNvdW50ZXIgaXMgbWlzc2luZy5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHBhcnNlTGFrZWJveENvdW50ZXJzKG91dHB1dDogc3RyaW5nLCBhdCA9IERhdGUubm93KCkpOiBMYWtlYm94Q291bnRlcnMge1xuICBjb25zdCBsaW5lcyA9IG5ldyBNYXA8c3RyaW5nLCBudW1iZXJbXT4oKTtcbiAgZm9yIChjb25zdCBsaW5lIG9mIG91dHB1dC5zcGxpdChcIlxcblwiKSkge1xuICAgIGNvbnN0IFtrZXksIC4uLnZhbHVlc10gPSBsaW5lLnRyaW0oKS5zcGxpdCgvXFxzKy8pO1xuICAgIGlmIChrZXkpIGxpbmVzLnNldChrZXkucmVwbGFjZSgvOiQvLCBcIlwiKSwgdmFsdWVzLm1hcChOdW1iZXIpKTtcbiAgfVxuICBjb25zdCB2YWx1ZSA9IChrZXk6IHN0cmluZywgaW5kZXggPSAwKTogbnVtYmVyID0+IHtcbiAgICBjb25zdCBlbnRyeSA9IGxpbmVzLmdldChrZXkpPy5baW5kZXhdO1xuICAgIGlmIChlbnRyeSA9PT0gdW5kZWZpbmVkIHx8ICFOdW1iZXIuaXNGaW5pdGUoZW50cnkpKSB7XG4gICAgICB0aHJvdyBuZXcgRXJyb3IoYExha2Vib3ggbWV0cmljcyBvdXRwdXQgaXMgbWlzc2luZyAke2tleX1gKTtcbiAgICB9XG4gICAgcmV0dXJuIGVudHJ5O1xuICB9O1xuICBjb25zdCBjcHUgPSBsaW5lcy5nZXQoXCJjcHVcIikgPz8gW107XG4gIGNvbnN0IGlkbGUgPSAoY3B1WzNdID8/IDApICsgKGNwdVs0XSA/PyAwKTtcbiAgY29uc3QgdG90YWwgPSBjcHVcbiAgICAuc2xpY2UoMCwgOClcbiAgICAucmVkdWNlKChzdW0sIGVudHJ5KSA9PiBzdW0gKyAoTnVtYmVyLmlzRmluaXRlKGVudHJ5KSA/IGVudHJ5IDogMCksIDApO1xuICByZXR1cm4ge1xuICAgIGF0LFxuICAgIGNvcmVzOiB2YWx1ZShcImNvcmVzXCIpLFxuICAgIGNwdUJ1c3k6IHRvdGFsIC0gaWRsZSxcbiAgICBjcHVUb3RhbDogdG90YWwsXG4gICAgbG9hZDE6IHZhbHVlKFwibG9hZFwiKSxcbiAgICBtZW1vcnlUb3RhbEJ5dGVzOiB2YWx1ZShcIk1lbVRvdGFsXCIpICogMTAyNCxcbiAgICBtZW1vcnlBdmFpbGFibGVCeXRlczogdmFsdWUoXCJNZW1BdmFpbGFibGVcIikgKiAxMDI0LFxuICAgIHN0b3JhZ2VUb3RhbEJ5dGVzOiB2YWx1ZShcInN0b3JhZ2VcIiwgMCksXG4gICAgc3RvcmFnZVVzZWRCeXRlczogdmFsdWUoXCJzdG9yYWdlXCIsIDEpLFxuICAgIHJ4Qnl0ZXM6IHZhbHVlKFwibmV0d29ya1wiLCAwKSxcbiAgICB0eEJ5dGVzOiB2YWx1ZShcIm5ldHdvcmtcIiwgMSksXG4gIH07XG59XG5cbi8qKiBDb252ZXJ0cyBjdW11bGF0aXZlIGNvdW50ZXJzIHRvIG9uZSBzbmFwc2hvdCB1c2luZyB0aGUgcHJldmlvdXMgc2FtcGxlIGZvciByYXRlcy4gKi9cbmV4cG9ydCBmdW5jdGlvbiB0b1NuYXBzaG90KFxuICBjdXJyZW50OiBMYWtlYm94Q291bnRlcnMsXG4gIHByZXZpb3VzPzogTGFrZWJveENvdW50ZXJzLFxuKTogTGFrZWJveE1ldHJpY3NTbmFwc2hvdCB7XG4gIGNvbnN0IHNlY29uZHMgPSBwcmV2aW91cyA/IE1hdGgubWF4KChjdXJyZW50LmF0IC0gcHJldmlvdXMuYXQpIC8gMV8wMDAsIDAuMDAxKSA6IDA7XG4gIGNvbnN0IGNwdVRvdGFsID0gcHJldmlvdXMgPyBjdXJyZW50LmNwdVRvdGFsIC0gcHJldmlvdXMuY3B1VG90YWwgOiAwO1xuICBjb25zdCBjcHVCdXN5ID0gcHJldmlvdXMgPyBjdXJyZW50LmNwdUJ1c3kgLSBwcmV2aW91cy5jcHVCdXN5IDogMDtcbiAgY29uc3QgcmF0ZSA9IChub3c6IG51bWJlciwgYmVmb3JlOiBudW1iZXIgfCB1bmRlZmluZWQpID0+XG4gICAgcHJldmlvdXMgJiYgYmVmb3JlICE9PSB1bmRlZmluZWQgPyBNYXRoLm1heCgwLCAobm93IC0gYmVmb3JlKSAvIHNlY29uZHMpIDogMDtcbiAgcmV0dXJuIHtcbiAgICBhdDogbmV3IERhdGUoY3VycmVudC5hdCkudG9JU09TdHJpbmcoKSxcbiAgICBjcHU6IHtcbiAgICAgIGNvcmVzOiBjdXJyZW50LmNvcmVzLFxuICAgICAgdXNlZFBlcmNlbnQ6IGNwdVRvdGFsID4gMCA/IGNsYW1wKChjcHVCdXN5IC8gY3B1VG90YWwpICogMTAwKSA6IDAsXG4gICAgICBsb2FkMTogY3VycmVudC5sb2FkMSxcbiAgICB9LFxuICAgIG1lbW9yeToge1xuICAgICAgdG90YWxCeXRlczogY3VycmVudC5tZW1vcnlUb3RhbEJ5dGVzLFxuICAgICAgdXNlZEJ5dGVzOiBNYXRoLm1heCgwLCBjdXJyZW50Lm1lbW9yeVRvdGFsQnl0ZXMgLSBjdXJyZW50Lm1lbW9yeUF2YWlsYWJsZUJ5dGVzKSxcbiAgICB9LFxuICAgIHN0b3JhZ2U6IHsgdG90YWxCeXRlczogY3VycmVudC5zdG9yYWdlVG90YWxCeXRlcywgdXNlZEJ5dGVzOiBjdXJyZW50LnN0b3JhZ2VVc2VkQnl0ZXMgfSxcbiAgICBuZXR3b3JrOiB7XG4gICAgICByeEJ5dGVzUGVyU2Vjb25kOiByYXRlKGN1cnJlbnQucnhCeXRlcywgcHJldmlvdXM/LnJ4Qnl0ZXMpLFxuICAgICAgdHhCeXRlc1BlclNlY29uZDogcmF0ZShjdXJyZW50LnR4Qnl0ZXMsIHByZXZpb3VzPy50eEJ5dGVzKSxcbiAgICB9LFxuICB9O1xufVxuXG5mdW5jdGlvbiBjbGFtcCh2YWx1ZTogbnVtYmVyKTogbnVtYmVyIHtcbiAgcmV0dXJuIE1hdGgubWluKDEwMCwgTWF0aC5tYXgoMCwgTWF0aC5yb3VuZCh2YWx1ZSAqIDEwKSAvIDEwKSk7XG59XG4iXX0=

package/lib/src/plugin.d.ts

@@ -0,0 +1,259 @@
+import { type IAppRouter } from "@databricks/appkit";
+import { type ToolkitEntry, type ToolkitOptions, type ToolRegistry } from "@databricks/appkit/beta";
+import { toolOperations, ToolRegistryPlugin, type AgentToolExecutionContext } from "@dbx-tools/appkit";
+import { type CreateLakeboxServiceRequest, type LakeboxClientConfigInput, type LakeboxCommandRequest, type LakeboxServiceLogsRequest } from "@dbx-tools/shared-lakebox";
+import type { JSONSchema7 } from "json-schema";
+import { z } from "zod";
+import { type LakeboxPluginConfig } from "./config.ts";
+import { LakeboxRuntime } from "./runtime.ts";
+/**
+ * AppKit plugin for the single app Lakebox.
+ *
+ * Registers user-scoped REST routes, agent tools, the deterministic service
+ * proxy, and WebSocket upgrade handling. Every Lakebox lifecycle call uses the
+ * app service principal; the authenticated request identity only selects the
+ * user's Lakebox account and authorizes that user's routes.
+ */
+export declare class AppKitLakeboxPlugin extends ToolRegistryPlugin<LakeboxPluginConfig> {
+    static manifest: {
+        name: "lakebox";
+        displayName: string;
+        description: string;
+        stability: "beta";
+        resources: {
+            required: never[];
+            optional: never[];
+        };
+        config: {
+            schema: JSONSchema7;
+        };
+    };
+    readonly runtime: LakeboxRuntime;
+    private mounted;
+    private httpServer?;
+    private upgradeAttachTimer?;
+    private upgradeIdentityGate?;
+    private readonly upgradeHandler;
+    /** Creates a plugin with a supplied shared runtime or one from resolved config. */
+    constructor(config?: LakeboxPluginConfig);
+    protected get toolRegistry(): ToolRegistry;
+    setup(): Promise<void>;
+    injectRoutes(router: IAppRouter): void;
+    /** Returns browser-safe route defaults published through AppKit client config. */
+    clientConfig(): LakeboxClientConfigInput;
+    /** Returns selected AppKit toolkit entries backed by this plugin's agent tools. */
+    toolkit(options?: ToolkitOptions): Record<string, ToolkitEntry>;
+    /** Executes one registered agent tool for the current execution identity. */
+    executeAgentTool(name: string, args: unknown, signal?: AbortSignal, context?: AgentToolExecutionContext): Promise<unknown>;
+    /** Returns the typed sibling-plugin API. */
+    exports(): {
+        summary: (identity: string) => Promise<{
+            supported: boolean;
+            auto: boolean;
+            status: "error" | "unknown" | "missing" | "starting" | "running" | "stopping" | "stopped";
+            name: string;
+            user: {
+                hash: string;
+                name: string;
+                uid: number;
+                home: string;
+                routePrefix: string;
+            };
+            services: {
+                name: string;
+                kind: "terminal" | "desktop" | "image";
+                state: "error" | "starting" | "stopped" | "ready";
+                port: number;
+                route: boolean;
+                path: string;
+                image?: string | undefined;
+                openPath?: string | undefined;
+                openUrl?: string | undefined;
+                error?: string | undefined;
+                log?: string | undefined;
+            }[];
+            servicesStale: boolean;
+            canStart: boolean;
+            canStop: boolean;
+            id?: string | undefined;
+            idleTimeoutSeconds?: number | undefined;
+            servicesObservedAt?: string | undefined;
+        }>;
+        start: () => Promise<void>;
+        stop: () => Promise<void>;
+        delete: () => Promise<boolean>;
+        executeCommand: (identity: string, input: LakeboxCommandRequest) => Promise<{
+            success: boolean;
+            exitCode: number;
+            stdout: string;
+            stderr: string;
+            executionTimeMs: number;
+            command: string;
+            args: string[];
+            timedOut?: boolean | undefined;
+        }>;
+        listServices: (identity: string) => Promise<{
+            name: string;
+            kind: "terminal" | "desktop" | "image";
+            state: "error" | "starting" | "stopped" | "ready";
+            port: number;
+            route: boolean;
+            path: string;
+            image?: string | undefined;
+            openPath?: string | undefined;
+            openUrl?: string | undefined;
+            error?: string | undefined;
+            log?: string | undefined;
+        }[]>;
+        createService: (identity: string, input: CreateLakeboxServiceRequest) => Promise<{
+            name: string;
+            kind: "terminal" | "desktop" | "image";
+            state: "error" | "starting" | "stopped" | "ready";
+            port: number;
+            route: boolean;
+            path: string;
+            image?: string | undefined;
+            openPath?: string | undefined;
+            openUrl?: string | undefined;
+            error?: string | undefined;
+            log?: string | undefined;
+        }>;
+        startService: (identity: string, name: string) => Promise<{
+            name: string;
+            kind: "terminal" | "desktop" | "image";
+            state: "error" | "starting" | "stopped" | "ready";
+            port: number;
+            route: boolean;
+            path: string;
+            image?: string | undefined;
+            openPath?: string | undefined;
+            openUrl?: string | undefined;
+            error?: string | undefined;
+            log?: string | undefined;
+        }>;
+        stopService: (identity: string, name: string) => Promise<{
+            name: string;
+            kind: "terminal" | "desktop" | "image";
+            state: "error" | "starting" | "stopped" | "ready";
+            port: number;
+            route: boolean;
+            path: string;
+            image?: string | undefined;
+            openPath?: string | undefined;
+            openUrl?: string | undefined;
+            error?: string | undefined;
+            log?: string | undefined;
+        }>;
+        removeService: (identity: string, name: string) => Promise<boolean>;
+        serviceLogs: (identity: string, input: LakeboxServiceLogsRequest) => Promise<{
+            log: string;
+        }>;
+        operations: (identity?: string) => {
+            readonly get_lakebox: toolOperations.AppKitOperation<z.ZodObject<{}, z.core.$strict>, unknown>;
+            readonly execute_lakebox_command: toolOperations.AppKitOperation<z.ZodObject<{
+                command: z.ZodString;
+                args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                cwd: z.ZodOptional<z.ZodString>;
+                env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                timeoutMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>, unknown>;
+            readonly list_lakebox_services: toolOperations.AppKitOperation<z.ZodObject<{}, z.core.$strict>, unknown>;
+            readonly create_lakebox_service: toolOperations.AppKitOperation<z.ZodObject<{
+                name: z.ZodString;
+                image: z.ZodString;
+                command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+                workingDirectory: z.ZodOptional<z.ZodString>;
+                mounts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    source: z.ZodString;
+                    target: z.ZodString;
+                    readOnly: z.ZodDefault<z.ZodBoolean>;
+                }, z.core.$strict>>>;
+                route: z.ZodDefault<z.ZodBoolean>;
+                openPath: z.ZodOptional<z.ZodString>;
+                stripPrefix: z.ZodDefault<z.ZodBoolean>;
+                pull: z.ZodDefault<z.ZodEnum<{
+                    missing: "missing";
+                    always: "always";
+                }>>;
+            }, z.core.$strict>, unknown>;
+            readonly start_lakebox_service: toolOperations.AppKitOperation<z.ZodObject<{
+                name: z.ZodString;
+            }, z.core.$strict>, unknown>;
+            readonly stop_lakebox_service: toolOperations.AppKitOperation<z.ZodObject<{
+                name: z.ZodString;
+            }, z.core.$strict>, unknown>;
+            readonly remove_lakebox_service: toolOperations.AppKitOperation<z.ZodObject<{
+                name: z.ZodString;
+            }, z.core.$strict>, unknown>;
+            readonly get_lakebox_service_logs: toolOperations.AppKitOperation<z.ZodObject<{
+                name: z.ZodString;
+                maxLines: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+                maxChars: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+            }, z.core.$strict>, unknown>;
+        };
+        toolkit: (options?: ToolkitOptions) => Record<string, ToolkitEntry>;
+    };
+    /** Cancels in-flight work before shutdown tears down resources. */
+    abortActiveOperations(): void;
+    /** Detaches WebSocket handling and closes the shared runtime. */
+    shutdown(): Promise<void>;
+    /** Returns the Zod-owned operation contracts used by agent tools. */
+    operations(identity?: string, origin?: string): {
+        readonly get_lakebox: toolOperations.AppKitOperation<z.ZodObject<{}, z.core.$strict>, unknown>;
+        readonly execute_lakebox_command: toolOperations.AppKitOperation<z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>, unknown>;
+        readonly list_lakebox_services: toolOperations.AppKitOperation<z.ZodObject<{}, z.core.$strict>, unknown>;
+        readonly create_lakebox_service: toolOperations.AppKitOperation<z.ZodObject<{
+            name: z.ZodString;
+            image: z.ZodString;
+            command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            workingDirectory: z.ZodOptional<z.ZodString>;
+            mounts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                source: z.ZodString;
+                target: z.ZodString;
+                readOnly: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>>>;
+            route: z.ZodDefault<z.ZodBoolean>;
+            openPath: z.ZodOptional<z.ZodString>;
+            stripPrefix: z.ZodDefault<z.ZodBoolean>;
+            pull: z.ZodDefault<z.ZodEnum<{
+                missing: "missing";
+                always: "always";
+            }>>;
+        }, z.core.$strict>, unknown>;
+        readonly start_lakebox_service: toolOperations.AppKitOperation<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strict>, unknown>;
+        readonly stop_lakebox_service: toolOperations.AppKitOperation<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strict>, unknown>;
+        readonly remove_lakebox_service: toolOperations.AppKitOperation<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strict>, unknown>;
+        readonly get_lakebox_service_logs: toolOperations.AppKitOperation<z.ZodObject<{
+            name: z.ZodString;
+            maxLines: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+            maxChars: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        }, z.core.$strict>, unknown>;
+    };
+    private createToolRegistry;
+    private executionIdentity;
+    /**
+     * Resolves route identity with the same rules as REST: the forwarded user,
+     * or AppKit's development user for direct loopback navigation outside
+     * production. Everything else is anonymous and fails closed.
+     */
+    private requestIdentity;
+    private streamMetrics;
+    private attachUpgradeHandler;
+    private handleUpgrade;
+}
+/** AppKit plugin factory for {@link AppKitLakeboxPlugin}. */
+export declare const lakebox: import("@databricks/appkit").ToPlugin<typeof AppKitLakeboxPlugin, LakeboxPluginConfig | undefined, "lakebox">;