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

package/src/_resource-registry.ts

@@ -0,0 +1,160 @@
+import { CacheManager } from "@databricks/appkit";
+import { LakeboxApiError, type LakeboxEntry } from "@dbx-tools/lakebox/rest";
+import { withAdvisoryLock, type PgPoolLike } from "@dbx-tools/postgres";
+import { log } from "@dbx-tools/shared-core";
+import { z } from "zod";
+
+const CACHE_NAMESPACE = "appkit-lakebox:resource";
+const RESOURCE_TTL_SECONDS = 365 * 24 * 60 * 60;
+const LEGACY_PREFIX = "dbx-lakebox-";
+const logger = log.logger("appkit-lakebox:resource");
+
+const LakeboxResourceReferenceSchema = z
+  .object({ sandboxId: z.string().min(1).describe("Databricks Lakebox identifier.") })
+  .strict()
+  .describe("Persistent pointer to the Databricks-assigned app Lakebox.");
+
+interface ResourceCache {
+  generateKey(parts: (string | number | object)[], userKey: string): string;
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: { ttl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/** Lakebox client capabilities required by the persistent resource registry. */
+export interface LakeboxResourceClient {
+  workspaceScope(): Promise<string>;
+  list(signal?: AbortSignal): Promise<LakeboxEntry[]>;
+  get(id: string, signal?: AbortSignal): Promise<LakeboxEntry>;
+  create(signal?: AbortSignal): Promise<LakeboxEntry>;
+  delete(id: string, signal?: AbortSignal): Promise<void>;
+}
+
+/**
+ * Persists the Databricks-assigned Lakebox ID and serializes first creation
+ * across app replicas with the Lakebase service-principal pool.
+ */
+export class LakeboxResourceRegistry {
+  private readonly pending = new Map<string, Promise<LakeboxEntry>>();
+  private readonly legacyChecked = new Set<string>();
+
+  constructor(
+    private readonly application: string,
+    private readonly pool?: PgPoolLike,
+    private readonly cache = (): ResourceCache => CacheManager.getInstanceSync(),
+  ) {}
+
+  /** Resolves the current app Lakebox without creating one. */
+  async read(
+    client: LakeboxResourceClient,
+    signal?: AbortSignal,
+  ): Promise<LakeboxEntry | undefined> {
+    const scope = await client.workspaceScope();
+    return this.resolve(client, scope, signal);
+  }
+
+  /** Returns the current app Lakebox or creates one with a Databricks-assigned name. */
+  async getOrCreate(client: LakeboxResourceClient, signal?: AbortSignal): Promise<LakeboxEntry> {
+    const scope = await client.workspaceScope();
+    const current = this.pending.get(scope);
+    if (current) return current;
+    const pending = this.withLock(scope, async () => {
+      const existing = await this.resolve(client, scope, signal);
+      if (existing) return existing;
+      const created = await client.create(signal);
+      try {
+        await this.write(scope, created.sandboxId);
+      } catch (error) {
+        await client.delete(created.sandboxId, signal).catch(() => undefined);
+        throw error;
+      }
+      logger.info("created app Lakebox", { id: created.sandboxId });
+      return created;
+    }).finally(() => this.pending.delete(scope));
+    this.pending.set(scope, pending);
+    return pending;
+  }
+
+  /** Clears the persisted pointer after the managed Lakebox is deleted. */
+  async clear(client: LakeboxResourceClient): Promise<void> {
+    const scope = await client.workspaceScope();
+    await this.cache().delete(this.key(scope));
+    this.legacyChecked.add(scope);
+  }
+
+  private async resolve(
+    client: LakeboxResourceClient,
+    scope: string,
+    signal?: AbortSignal,
+  ): Promise<LakeboxEntry | undefined> {
+    const key = this.key(scope);
+    const value = await this.cache().get<unknown>(key);
+    const parsed = LakeboxResourceReferenceSchema.safeParse(value);
+    if (value !== null && !parsed.success) {
+      logger.warn("discarded invalid cached Lakebox resource reference", {
+        application: this.application,
+      });
+      await this.cache().delete(key);
+    }
+    if (parsed.success) {
+      try {
+        return await client.get(parsed.data.sandboxId, signal);
+      } catch (error) {
+        if (!(error instanceof LakeboxApiError) || error.status !== 404) throw error;
+        await this.cache().delete(key);
+        this.legacyChecked.add(scope);
+        return undefined;
+      }
+    }
+    if (this.legacyChecked.has(scope)) return undefined;
+    this.legacyChecked.add(scope);
+    const legacy = selectLegacyLakebox(
+      await client.list(signal),
+      legacyLakeboxName(this.application),
+    );
+    if (!legacy) return undefined;
+    await this.write(scope, legacy.sandboxId);
+    logger.info("adopted legacy named app Lakebox", { id: legacy.sandboxId });
+    return legacy;
+  }
+
+  private async write(scope: string, sandboxId: string): Promise<void> {
+    await this.cache().set(this.key(scope), LakeboxResourceReferenceSchema.parse({ sandboxId }), {
+      ttl: RESOURCE_TTL_SECONDS,
+    });
+  }
+
+  private key(scope: string): string {
+    return this.cache().generateKey([CACHE_NAMESPACE, this.application], scope);
+  }
+
+  private withLock<T>(scope: string, fn: () => Promise<T>): Promise<T> {
+    if (!this.pool) return fn();
+    return withAdvisoryLock(this.pool, [CACHE_NAMESPACE, this.application, scope], fn);
+  }
+}
+
+function legacyLakeboxName(application: string): string {
+  const slug = application
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 200);
+  if (!slug) throw new Error("A managed Lakebox requires a non-empty application key");
+  return `${LEGACY_PREFIX}${slug}`;
+}
+
+function selectLegacyLakebox(
+  entries: readonly LakeboxEntry[],
+  name: string,
+): LakeboxEntry | undefined {
+  return entries
+    .filter((entry) => entry.name === name)
+    .sort(
+      (left, right) =>
+        (Date.parse(left.createTime ?? "") || Number.MAX_SAFE_INTEGER) -
+          (Date.parse(right.createTime ?? "") || Number.MAX_SAFE_INTEGER) ||
+        left.sandboxId.localeCompare(right.sandboxId),
+    )[0];
+}

package/src/_service-snapshots.ts

@@ -0,0 +1,84 @@
+import { CacheManager } from "@databricks/appkit";
+import { errorUtils, log } from "@dbx-tools/shared-core";
+import { z } from "zod";
+import { LakeboxControllerDefinitionSchema, type LakeboxControllerService } from "./services.ts";
+
+const CACHE_NAMESPACE = "appkit-lakebox:service-snapshot";
+const SNAPSHOT_TTL_SECONDS = 365 * 24 * 60 * 60;
+const logger = log.logger("appkit-lakebox:service-snapshot");
+
+export const LakeboxServiceSnapshotSchema = z
+  .object({
+    observedAt: z.string().datetime().describe("Time the controller last returned this list."),
+    definitions: z
+      .array(LakeboxControllerDefinitionSchema)
+      .describe("Last observed saved service definitions; never authoritative live state."),
+  })
+  .strict()
+  .describe("Best-effort last-known Lakebox service definitions for an unavailable machine.");
+
+export type LakeboxServiceSnapshot = z.infer<typeof LakeboxServiceSnapshotSchema>;
+
+/** Projects saved definitions into explicitly non-live stopped service records. */
+export function stoppedSnapshotServices(
+  snapshot: LakeboxServiceSnapshot,
+): Map<string, LakeboxControllerService> {
+  return new Map(
+    snapshot.definitions.map((definition) => [
+      definition.name,
+      { name: definition.name, state: "stopped", definition },
+    ]),
+  );
+}
+
+interface SnapshotCache {
+  generateKey(parts: (string | number | object)[], userKey: string): string;
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: { ttl?: number }): Promise<void>;
+}
+
+/** Best-effort persistent snapshots backed by AppKit's configured cache. */
+export class LakeboxServiceSnapshots {
+  constructor(private readonly cache = (): SnapshotCache => CacheManager.getInstanceSync()) {}
+
+  async read(lakeboxId: string, userHash: string): Promise<LakeboxServiceSnapshot | undefined> {
+    try {
+      const value = await this.cache().get<unknown>(this.key(lakeboxId, userHash));
+      if (value === null) return undefined;
+      const parsed = LakeboxServiceSnapshotSchema.safeParse(value);
+      if (parsed.success) return parsed.data;
+      logger.warn("ignored invalid cached service snapshot", { lakeboxId, userHash });
+    } catch (error) {
+      logger.warn("unable to read cached service snapshot", {
+        lakeboxId,
+        userHash,
+        error: errorUtils.toError(error),
+      });
+    }
+    return undefined;
+  }
+
+  async write(
+    lakeboxId: string,
+    userHash: string,
+    snapshot: LakeboxServiceSnapshot,
+  ): Promise<void> {
+    try {
+      await this.cache().set(
+        this.key(lakeboxId, userHash),
+        LakeboxServiceSnapshotSchema.parse(snapshot),
+        { ttl: SNAPSHOT_TTL_SECONDS },
+      );
+    } catch (error) {
+      logger.warn("unable to cache service snapshot", {
+        lakeboxId,
+        userHash,
+        error: errorUtils.toError(error),
+      });
+    }
+  }
+
+  private key(lakeboxId: string, userHash: string): string {
+    return this.cache().generateKey([CACHE_NAMESPACE, lakeboxId], userHash);
+  }
+}

package/src/config.ts

@@ -0,0 +1,128 @@
+import { basename } from "node:path";
+import type { BasePluginConfig } from "@databricks/appkit";
+import { configUtils, projectUtils } from "@dbx-tools/core";
+import { Ssh2PatchModeSchema, SshTransportModeSchema } from "@dbx-tools/lakebox/transport";
+import { LAKEBOX_DEFAULT_ROUTE_PREFIX } from "@dbx-tools/shared-lakebox";
+import { z } from "zod";
+
+const APPLICATION_CONFIG_KEY = "LAKEBOX_APPLICATION";
+const IDLE_TIMEOUT_CONFIG_KEY = "LAKEBOX_IDLE_TIMEOUT_SECONDS";
+const SSH_TRANSPORT_CONFIG_KEY = "LAKEBOX_SSH_TRANSPORT";
+const SSH2_PATCH_CONFIG_KEY = "LAKEBOX_SSH_SSH2_PATCH";
+
+export const LakeboxPluginConfigSchema = z
+  .object({
+    auto: z
+      .boolean()
+      .default(true)
+      .describe(
+        "Whether commands, services, and routes create or start the app Lakebox on demand. Defaults to true.",
+      ),
+    application: z
+      .string()
+      .trim()
+      .min(1)
+      .describe(
+        `Stable application key for the persisted Lakebox resource ID. Defaults to ${configUtils.name(APPLICATION_CONFIG_KEY)}, then DATABRICKS_APP_NAME, then the project directory name.`,
+      ),
+    idleTimeoutSeconds: z
+      .number()
+      .int()
+      .min(60)
+      .max(86_400)
+      .default(3_600)
+      .describe(
+        `Platform idle timeout that stops the Lakebox after inactivity, from 60 to 86400 seconds. Defaults to 3600; configure with ${configUtils.name(IDLE_TIMEOUT_CONFIG_KEY)}.`,
+      ),
+    routePrefix: z
+      .string()
+      .startsWith("/")
+      .default(LAKEBOX_DEFAULT_ROUTE_PREFIX)
+      .describe("AppKit root path for user service routes. Defaults to /lakebox."),
+    gatewayPort: z
+      .number()
+      .int()
+      .min(1)
+      .max(65535)
+      .default(2222)
+      .describe("Lakebox SSH gateway port. Defaults to 2222."),
+    connectTimeoutMs: z
+      .number()
+      .int()
+      .positive()
+      .default(30_000)
+      .describe("SSH connection timeout in milliseconds. Defaults to 30000."),
+    commandTimeoutMs: z
+      .number()
+      .int()
+      .positive()
+      .default(120_000)
+      .describe("Default command timeout in milliseconds. Defaults to 120000."),
+    metricsIntervalSeconds: z
+      .number()
+      .int()
+      .min(1)
+      .max(300)
+      .default(5)
+      .describe("Interval between metrics samples while the Lakebox runs. Defaults to 5."),
+    sshTransport: SshTransportModeSchema.describe(
+      `SSH transport: auto, openssh, or ssh2. Configure with ${configUtils.name(SSH_TRANSPORT_CONFIG_KEY)}.`,
+    ),
+    ssh2Patch: Ssh2PatchModeSchema.describe(
+      `ssh2 missing-exec-reply workaround: auto, true, or false. Configure with ${configUtils.name(SSH2_PATCH_CONFIG_KEY)}.`,
+    ),
+    keyDirectory: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("Server-side directory for the app SSH key and gateway host keys."),
+  })
+  .strict()
+  .describe("Serializable Lakebox AppKit plugin configuration.");
+
+export type SerializableLakeboxPluginConfig = z.input<typeof LakeboxPluginConfigSchema>;
+export type ResolvedLakeboxPluginConfig = z.output<typeof LakeboxPluginConfigSchema>;
+
+/**
+ * Configuration accepted by the Lakebox AppKit plugin.
+ *
+ * Pass a shared runtime when the plugin and the Mastra workspace resolver must
+ * use the same sessions, routes, and metrics.
+ */
+export type LakeboxPluginConfig = BasePluginConfig &
+  Partial<SerializableLakeboxPluginConfig> & {
+    runtime?: import("./runtime.ts").LakeboxRuntime;
+  };
+
+/**
+ * Resolves defaults through configUtils and removes AppKit-only fields.
+ *
+ * @throws A Zod validation error when a field has an invalid type or range.
+ */
+export function resolveLakeboxPluginConfig(
+  config: LakeboxPluginConfig = {},
+): ResolvedLakeboxPluginConfig {
+  const {
+    runtime: _runtime,
+    name: _name,
+    host: _host,
+    context: _context,
+    telemetry: _telemetry,
+    streamConfig: _stream,
+    application,
+    idleTimeoutSeconds,
+    sshTransport,
+    ssh2Patch,
+    ...serializable
+  } = config;
+  return LakeboxPluginConfigSchema.parse({
+    ...serializable,
+    application:
+      configUtils.string(application, APPLICATION_CONFIG_KEY) ??
+      configUtils.string(undefined, "DATABRICKS_APP_NAME", configUtils.ENV_ONLY) ??
+      basename(projectUtils.root() ?? process.cwd()),
+    idleTimeoutSeconds: configUtils.positiveInt(idleTimeoutSeconds, IDLE_TIMEOUT_CONFIG_KEY, 3_600),
+    sshTransport: configUtils.string(sshTransport, SSH_TRANSPORT_CONFIG_KEY),
+    ssh2Patch: configUtils.string(ssh2Patch, SSH2_PATCH_CONFIG_KEY),
+  });
+}

package/src/desktop.ts

@@ -0,0 +1,97 @@
+import { brandUtils } from "@dbx-tools/shared-core";
+import { dbxToolsAssetDataUrls, dbxToolsAssetSvg } from "@dbx-tools/ui/branding/assets";
+
+const BRAND = brandUtils.defaultBrandContext;
+const BRAND_COLORS = BRAND.colors;
+const WALLPAPER_LOGO = dbxToolsAssetSvg.logoDark.replace(
+  "<svg ",
+  '<svg x="500" y="378" width="600" height="135" ',
+);
+
+const DBX_TOOLS_WALLPAPER =
+  // ============================================================================
+  /*xml*/ `
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1000" viewBox="0 0 1600 1000">
+  <defs>
+    <linearGradient id="background" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0B161B"/>
+      <stop offset="0.55" stop-color="${BRAND_COLORS.primary}"/>
+      <stop offset="1" stop-color="${BRAND_COLORS.primaryHover}"/>
+    </linearGradient>
+    <pattern id="grid" width="64" height="64" patternUnits="userSpaceOnUse">
+      <path d="M64 0H0V64" fill="none" stroke="${BRAND_COLORS.surface}" stroke-opacity="0.045"/>
+    </pattern>
+  </defs>
+  <rect width="1600" height="1000" fill="url(#background)"/>
+  <rect width="1600" height="1000" fill="url(#grid)"/>
+  <path d="M0 780C310 650 475 920 780 775s500-220 820-55v280H0Z" fill="${BRAND_COLORS.accent}" fill-opacity="0.13"/>
+  <path d="M0 835c300-125 510 105 790-10s500-170 810-65" fill="none" stroke="${BRAND_COLORS.accent}" stroke-width="4" stroke-opacity="0.7"/>
+  ${WALLPAPER_LOGO}
+  <text x="800" y="558" text-anchor="middle" fill="${BRAND_COLORS.muted}" font-family="${BRAND.typography.sans}" font-size="24" letter-spacing="5">LAKEBOX DESKTOP</text>
+</svg>
+`
+    // ============================================================================
+    .trim();
+
+const DBX_TOOLS_TERMINAL_ICON =
+  // ============================================================================
+  /*xml*/ `
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
+  <rect x="4" y="6" width="56" height="52" rx="12" fill="${BRAND_COLORS.primary}"/>
+  <rect x="8" y="10" width="48" height="44" rx="8" fill="${BRAND_COLORS.primaryHover}"/>
+  <path d="m18 23 9 9-9 9" fill="none" stroke="${BRAND_COLORS.surface}" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M34 41h12" fill="none" stroke="${BRAND_COLORS.accent}" stroke-width="4" stroke-linecap="round"/>
+</svg>
+`
+    // ============================================================================
+    .trim();
+
+const DESKTOP_BRAND_HEAD =
+  // ============================================================================
+  /*html*/ `
+<style id="dbx-tools-desktop-brand">
+html,body{width:100%;max-width:100%;height:100%;max-height:100%;min-width:0;min-height:0;overflow:hidden}
+body{position:fixed;inset:0;width:var(--dbx-tools-viewport-width,100vw);height:var(--dbx-tools-viewport-height,100dvh)}
+#noVNC_container{width:100%!important;max-width:100%;height:100%!important;max-height:100%;overflow:hidden}
+.noVNC_logo,h1.noVNC_logo,a[title="KasmVNC Learn More"]{display:none!important}
+#noVNC_fallback_errormsg{overflow-wrap:anywhere}
+</style>
+<link data-dbx-tools-desktop-icon rel="icon" href="${dbxToolsAssetDataUrls.iconDark}">
+<script id="dbx-tools-kasm-mobile-guard">(()=>{const ignored=(error)=>error instanceof ReferenceError&&/^Can't find variable: W[0-9A-F]{32}$/.test(error.message);window.addEventListener("error",(event)=>{if(ignored(event.error)){event.preventDefault();event.stopImmediatePropagation()}},true);window.addEventListener("unhandledrejection",(event)=>{if(ignored(event.reason)){event.preventDefault();event.stopImmediatePropagation()}},true);let timer;const sync=()=>{const viewport=window.visualViewport;document.documentElement.style.setProperty("--dbx-tools-viewport-width",String(Math.round(viewport?.width??window.innerWidth))+"px");document.documentElement.style.setProperty("--dbx-tools-viewport-height",String(Math.round(viewport?.height??window.innerHeight))+"px");window.dispatchEvent(new Event("resize"))};const schedule=()=>{clearTimeout(timer);sync();setTimeout(sync,250);timer=setTimeout(sync,750)};window.visualViewport?.addEventListener("resize",schedule);window.visualViewport?.addEventListener("scroll",schedule);window.addEventListener("orientationchange",schedule);window.addEventListener("pageshow",schedule);document.readyState==="loading"?document.addEventListener("DOMContentLoaded",schedule,{once:true}):schedule()})();</script>
+<script id="dbx-tools-desktop-brand-script">(()=>{const icon=${JSON.stringify(dbxToolsAssetDataUrls.iconDark)};const rewrite=(root)=>{if(root.nodeType===Node.TEXT_NODE){if(root.nodeValue?.includes("KasmVNC"))root.nodeValue=root.nodeValue.replaceAll("KasmVNC","dbx tools Desktop");return}const walker=document.createTreeWalker(root,NodeFilter.SHOW_TEXT);let node;while(node=walker.nextNode())if(node.nodeValue?.includes("KasmVNC"))node.nodeValue=node.nodeValue.replaceAll("KasmVNC","dbx tools Desktop")};const apply=()=>{document.title="dbx tools Desktop";for(const link of document.querySelectorAll('link[rel~="icon"],link[rel="apple-touch-icon"]'))link.setAttribute("href",icon);if(document.body)rewrite(document.body)};if(document.readyState==="loading")document.addEventListener("DOMContentLoaded",apply,{once:true});else apply();new MutationObserver((entries)=>{for(const entry of entries){if(entry.type==="characterData")rewrite(entry.target);else for(const node of entry.addedNodes)rewrite(node)}}).observe(document.documentElement,{childList:true,subtree:true,characterData:true})})();</script>
+`
+    // ============================================================================
+    .trim();
+
+/** Markup injected into the KasmVNC client page to apply dbx-tools branding. */
+export const desktopHtmlHead = DESKTOP_BRAND_HEAD;
+
+/** Browser entry URL for the built-in KasmVNC desktop. */
+export function desktopOpenUrl(path: string): string {
+  const normalized = path.replace(/\/+$/, "");
+  const websocketPath = `${normalized.replace(/^\/+/, "")}/websockify`;
+  const parameters = new URLSearchParams({
+    autoconnect: "1",
+    resize: "remote",
+    show_dot: "1",
+    clipboard_seamless: "0",
+    enable_webp: "0",
+    kasmvnc_mode_preference: "-1027",
+    path: websocketPath,
+  });
+  return `${normalized}/?${parameters.toString()}`;
+}
+
+/** Branding environment consumed by the packaged desktop session entrypoint. */
+export function desktopEnvironment(): Readonly<Record<string, string>> {
+  return {
+    DBX_TOOLS_DESKTOP_WALLPAPER_BASE64: Buffer.from(DBX_TOOLS_WALLPAPER).toString("base64"),
+    DBX_TOOLS_DESKTOP_BRAND_ICON_BASE64: Buffer.from(dbxToolsAssetSvg.iconDark).toString("base64"),
+    DBX_TOOLS_DESKTOP_TERMINAL_ICON_BASE64: Buffer.from(DBX_TOOLS_TERMINAL_ICON).toString("base64"),
+    DBX_TOOLS_DESKTOP_HOMEPAGE_BASE64: Buffer.from(BRAND.links.website).toString("base64"),
+    DBX_TOOLS_DESKTOP_PRIMARY: BRAND_COLORS.primary,
+    DBX_TOOLS_DESKTOP_PRIMARY_HOVER: BRAND_COLORS.primaryHover,
+    DBX_TOOLS_DESKTOP_SURFACE: BRAND_COLORS.surface,
+    DBX_TOOLS_DESKTOP_FONT: "DejaVu Sans",
+  };
+}

package/src/metrics.ts

@@ -0,0 +1,178 @@
+import { EventEmitter } from "node:events";
+import { errorUtils, log } from "@dbx-tools/shared-core";
+import type { LakeboxMetricsSnapshot } from "@dbx-tools/shared-lakebox";
+
+const logger = log.logger("appkit-lakebox:metrics");
+const DEFAULT_CAPACITY = 120;
+
+/** Raw cumulative counters read from one sample. */
+export interface LakeboxCounters {
+  at: number;
+  cores: number;
+  cpuBusy: number;
+  cpuTotal: number;
+  load1: number;
+  memoryTotalBytes: number;
+  memoryAvailableBytes: number;
+  storageTotalBytes: number;
+  storageUsedBytes: number;
+  rxBytes: number;
+  txBytes: number;
+}
+
+/** Events emitted by {@link LakeboxMetrics}. */
+export interface LakeboxMetricsEvents {
+  snapshot: [LakeboxMetricsSnapshot];
+}
+
+/**
+ * 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<LakeboxMetricsEvents> {
+  private readonly samples: LakeboxMetricsSnapshot[] = [];
+  private previous?: LakeboxCounters;
+  private timer?: ReturnType<typeof setTimeout>;
+  private controller?: AbortController;
+
+  /** Creates a stopped emitter that reads raw counters with `read`. */
+  constructor(
+    private readonly read: (signal: AbortSignal) => Promise<string>,
+    private readonly intervalMs: number,
+    private readonly capacity = DEFAULT_CAPACITY,
+  ) {
+    super();
+  }
+
+  /** Whether sampling is active. */
+  get running(): boolean {
+    return this.controller !== undefined;
+  }
+
+  /** Recent samples, oldest first. */
+  series(): readonly LakeboxMetricsSnapshot[] {
+    return [...this.samples];
+  }
+
+  /** Seeds one validated sample without starting the recurring sampler or emitting an event. */
+  seed(output: string, at = Date.now()): LakeboxMetricsSnapshot {
+    const snapshot = this.record(parseLakeboxCounters(output, at), false);
+    return snapshot;
+  }
+
+  /** Starts sampling. Repeated calls are ignored. */
+  start(): void {
+    if (this.controller) return;
+    this.controller = new AbortController();
+    void this.tick(this.controller.signal);
+  }
+
+  /** Stops sampling and clears the series. */
+  stop(): void {
+    this.controller?.abort();
+    this.controller = undefined;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+    this.previous = undefined;
+    this.samples.length = 0;
+  }
+
+  private async tick(signal: AbortSignal): Promise<void> {
+    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?.();
+  }
+
+  private record(counters: LakeboxCounters, emit: boolean): LakeboxMetricsSnapshot {
+    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: string, at = Date.now()): LakeboxCounters {
+  const lines = new Map<string, number[]>();
+  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: string, index = 0): number => {
+    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: LakeboxCounters,
+  previous?: LakeboxCounters,
+): LakeboxMetricsSnapshot {
+  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: number, before: number | undefined) =>
+    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: number): number {
+  return Math.min(100, Math.max(0, Math.round(value * 10) / 10));
+}