@ycodium-ai/plugin-resource-telemetry 0.2.0

package/README.md

@@ -0,0 +1,53 @@
+# @ycodium-ai/plugin-resource-telemetry
+
+Measures what this machine's processes cost in CPU, memory, and disk. The
+diagnostics page reads this plugin; there is no separate settings card.
+
+## What it does
+
+A Rust sidecar samples processes. This package owns the protocol, the merge,
+and the history projection, and exposes:
+
+- **snapshots** — a live stream (latest 8 frames; slow subscribers drop old
+  ones, not host memory)
+- **snapshot** — one current sample on demand
+- **history** — bucketed CPU, memory, and I/O from the sidecar ring buffer
+- **retry** — closes the collector's circuit breaker and restarts the monitor
+
+The sidecar path is injected by the host as `config:resourceMonitorPath`. If
+the host cannot resolve a binary, that key is omitted and spawn is refused.
+Unloading the plugin stops the sidecar.
+
+## Requirements
+
+A Ycodium server that can resolve `ycodium-resource-monitor`. The plugin asks
+to spawn that one program, at most one at a time.
+
+## Install
+
+```
+ycodium plugin add @ycodium-ai/plugin-resource-telemetry
+```
+
+The plugin ships enabled with Ycodium as `core.resource-telemetry`. Disabling
+it stops the measuring process; the diagnostics page reports that it is not
+running rather than showing stale figures. Uninstalling it writes a removal
+onto the home patch, so a restart or upgrade does not bring it back.
+Reinstalling the unversioned bundled package restores the same entry without
+an npm fetch.
+
+## Surfaces
+
+- **Web / Desktop** — diagnostics page, via this plugin's commands and stream.
+- **Mobile** — the same stream is in the background-activity reporter; there
+  is no native diagnostics page that draws the process table.
+
+## Developing
+
+The package builds its own code into `dist/index.js`. The host supplies the
+shared `@ycodium-ai/plugin-api` at runtime. The plugin requires plugin API
+version 2. The monitor binary stays with the host.
+
+## License
+
+UNLICENSED.

package/dist/index.js

@@ -0,0 +1,1311 @@
+// src/index.ts
+import * as NodeProcess from "node:process";
+import {
+  definePlugin
+} from "@ycodium-ai/plugin-api";
+
+// src/model.ts
+var RESOURCE_MONITOR_PROTOCOL_VERSION = 2;
+var MAX_DELTA_INTERVAL_MS = 3e4;
+var MAX_HISTORY_WINDOW_MS = 60 * 6e4;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var finite = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+var nonNegativeInt = (value) => {
+  const parsed = finite(value);
+  return parsed === null || parsed < 0 || !Number.isInteger(parsed) ? null : parsed;
+};
+var positiveInt = (value) => {
+  const parsed = nonNegativeInt(value);
+  return parsed === null || parsed === 0 ? null : parsed;
+};
+var nonEmptyString = (value) => typeof value === "string" && value.trim().length > 0 ? value : null;
+var boolean = (value) => typeof value === "boolean" ? value : null;
+var readEventVersion = (value) => isRecord(value) ? finite(value["version"]) : null;
+var parseCapabilities = (value) => {
+  if (!isRecord(value)) return null;
+  const flags = [
+    "cumulativeCpuTime",
+    "currentCpuPercent",
+    "residentMemory",
+    "virtualMemory",
+    "ioBytes",
+    "processStartTime",
+    "processTree"
+  ];
+  const parsed = {};
+  for (const flag of flags) {
+    const item = boolean(value[flag]);
+    if (item === null) return null;
+    parsed[flag] = item;
+  }
+  return parsed;
+};
+var parseProcessSample = (value) => {
+  if (!isRecord(value)) return null;
+  const pid2 = positiveInt(value["pid"]);
+  const ppid = nonNegativeInt(value["ppid"]);
+  const startTimeMs = nonNegativeInt(value["startTimeMs"]);
+  const runTimeMs = nonNegativeInt(value["runTimeMs"]);
+  const cpuPercent = finite(value["cpuPercent"]);
+  const cpuTimeMs = nonNegativeInt(value["cpuTimeMs"]);
+  const residentBytes = nonNegativeInt(value["residentBytes"]);
+  const virtualBytes = nonNegativeInt(value["virtualBytes"]);
+  const ioReadBytes = nonNegativeInt(value["ioReadBytes"]);
+  const ioWriteBytes = nonNegativeInt(value["ioWriteBytes"]);
+  const ioSemantics = value["ioSemantics"];
+  const name = value["name"];
+  const command = value["command"];
+  const status = value["status"];
+  if (pid2 === null || ppid === null || startTimeMs === null || runTimeMs === null || cpuPercent === null || cpuTimeMs === null || residentBytes === null || virtualBytes === null || ioReadBytes === null || ioWriteBytes === null || typeof name !== "string" || typeof command !== "string" || typeof status !== "string" || ioSemantics !== "storage" && ioSemantics !== "all-io") {
+    return null;
+  }
+  return {
+    pid: pid2,
+    ppid,
+    startTimeMs,
+    runTimeMs,
+    name,
+    command,
+    status,
+    cpuPercent,
+    cpuTimeMs,
+    residentBytes,
+    virtualBytes,
+    ioReadBytes,
+    ioWriteBytes,
+    ioSemantics
+  };
+};
+var parseSnapshot = (value) => {
+  const sequence = nonNegativeInt(value["sequence"]);
+  const sampledAtUnixMs = nonNegativeInt(value["sampledAtUnixMs"]);
+  const collectionDurationMicros = nonNegativeInt(value["collectionDurationMicros"]);
+  const scannedProcessCount = nonNegativeInt(value["scannedProcessCount"]);
+  const retainedProcessCount = nonNegativeInt(value["retainedProcessCount"]);
+  const inaccessibleProcessCount = nonNegativeInt(value["inaccessibleProcessCount"]);
+  const rawProcesses = value["processes"];
+  if (sequence === null || sampledAtUnixMs === null || collectionDurationMicros === null || scannedProcessCount === null || retainedProcessCount === null || inaccessibleProcessCount === null || !Array.isArray(rawProcesses)) {
+    return null;
+  }
+  const processes = [];
+  for (const item of rawProcesses) {
+    const parsed = parseProcessSample(item);
+    if (parsed === null) return null;
+    processes.push(parsed);
+  }
+  const requestId = nonEmptyString(value["requestId"]);
+  return {
+    type: "snapshot",
+    sequence,
+    sampledAtUnixMs,
+    collectionDurationMicros,
+    scannedProcessCount,
+    retainedProcessCount,
+    inaccessibleProcessCount,
+    ...requestId === null ? {} : { requestId },
+    processes
+  };
+};
+var parseMonitorEvent = (value) => {
+  if (!isRecord(value)) return null;
+  switch (value["type"]) {
+    case "hello": {
+      const sidecarVersion = nonEmptyString(value["sidecarVersion"]);
+      const sidecarPid = positiveInt(value["sidecarPid"]);
+      const platform = nonEmptyString(value["platform"]);
+      const arch = nonEmptyString(value["arch"]);
+      const capabilities = parseCapabilities(value["capabilities"]);
+      if (sidecarVersion === null || sidecarPid === null || platform === null || arch === null || capabilities === null) {
+        return null;
+      }
+      return { type: "hello", sidecarVersion, sidecarPid, platform, arch, capabilities };
+    }
+    case "snapshot":
+      return parseSnapshot(value);
+    case "historyChunk": {
+      const requestId = nonEmptyString(value["requestId"]);
+      const done = boolean(value["done"]);
+      const rawSnapshots = value["snapshots"];
+      if (requestId === null || done === null || !Array.isArray(rawSnapshots)) return null;
+      const snapshots = [];
+      for (const item of rawSnapshots) {
+        if (!isRecord(item)) return null;
+        const parsed = parseSnapshot(item);
+        if (parsed === null) return null;
+        snapshots.push(parsed);
+      }
+      return { type: "historyChunk", requestId, done, snapshots };
+    }
+    case "error": {
+      const code = nonEmptyString(value["code"]);
+      const message = nonEmptyString(value["message"]);
+      const recoverable = boolean(value["recoverable"]);
+      if (code === null || message === null || recoverable === null) return null;
+      return { type: "error", code, message, recoverable };
+    }
+    default:
+      return null;
+  }
+};
+var emptyGroupCounters = () => ({
+  cpuTimeMs: 0,
+  ioReadBytes: 0,
+  ioWriteBytes: 0,
+  processStarts: 0,
+  processExits: 0
+});
+var emptyTelemetryCounters = () => ({
+  backend: emptyGroupCounters(),
+  monitor: emptyGroupCounters(),
+  all: emptyGroupCounters()
+});
+var processIdentityKey = (pid2, startTimeMs) => `${pid2}:${startTimeMs}`;
+var toIso = (epochMs) => new Date(epochMs).toISOString();
+var finiteNonNegative = (value) => Number.isFinite(value) ? Math.max(0, value) : 0;
+var categoryGroup = (category) => category === "resource-monitor" ? "monitor" : "backend";
+var delta = (input) => {
+  if (input.elapsedMs <= 0 || input.elapsedMs > MAX_DELTA_INTERVAL_MS || input.current < input.previous) {
+    return 0;
+  }
+  return input.current - input.previous;
+};
+var processDepths = (processes, roots) => {
+  const childrenByParent = /* @__PURE__ */ new Map();
+  for (const process of processes) {
+    const children = childrenByParent.get(process.ppid) ?? [];
+    children.push(process.pid);
+    childrenByParent.set(process.ppid, children);
+  }
+  const depths = /* @__PURE__ */ new Map();
+  const queue = [...roots].map((pid2) => ({ pid: pid2, depth: 0 }));
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || depths.has(current.pid)) continue;
+    depths.set(current.pid, current.depth);
+    for (const childPid of childrenByParent.get(current.pid) ?? []) {
+      queue.push({ pid: childPid, depth: current.depth + 1 });
+    }
+  }
+  return depths;
+};
+var orderProcessTree = (processes, rootPids) => {
+  const processesByPid = new Map(processes.map((process) => [process.identity.pid, process]));
+  const childrenByParent = /* @__PURE__ */ new Map();
+  for (const process of processes) {
+    const children = childrenByParent.get(process.ppid) ?? [];
+    children.push(process);
+    childrenByParent.set(process.ppid, children);
+  }
+  for (const children of childrenByParent.values()) {
+    children.sort((left, right) => left.identity.pid - right.identity.pid);
+  }
+  const ordered = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (process) => {
+    if (visited.has(process.identity.pid)) return;
+    visited.add(process.identity.pid);
+    ordered.push(process);
+    for (const child of childrenByParent.get(process.identity.pid) ?? []) visit(child);
+  };
+  for (const rootPid of rootPids) {
+    const root = processesByPid.get(rootPid);
+    if (root) visit(root);
+  }
+  for (const process of processes.toSorted(
+    (left, right) => left.depth - right.depth || left.identity.pid - right.identity.pid
+  )) {
+    visit(process);
+  }
+  return ordered;
+};
+var incrementCounters = (counters, update) => ({
+  cpuTimeMs: counters.cpuTimeMs + (update.cpuTimeMs ?? 0),
+  ioReadBytes: counters.ioReadBytes + (update.ioReadBytes ?? 0),
+  ioWriteBytes: counters.ioWriteBytes + (update.ioWriteBytes ?? 0),
+  processStarts: counters.processStarts + (update.processStarts ?? 0),
+  processExits: counters.processExits + (update.processExits ?? 0)
+});
+var applyLifecycleCounters = (input) => {
+  let backend = input.counters.backend;
+  let monitor = input.counters.monitor;
+  let all = input.counters.all;
+  const bump = (category, update) => {
+    if (categoryGroup(category) === "monitor") monitor = incrementCounters(monitor, update);
+    else backend = incrementCounters(backend, update);
+    all = incrementCounters(all, update);
+  };
+  for (const processDelta of input.deltas) bump(processDelta.category, processDelta);
+  for (const [identityKey, current] of input.current) {
+    if (input.previous.has(identityKey)) continue;
+    bump(current.process.category, { processStarts: 1 });
+  }
+  for (const [identityKey, previous] of input.previous) {
+    if (input.current.has(identityKey)) continue;
+    bump(previous.process.category, { processExits: 1 });
+  }
+  return { backend, monitor, all };
+};
+var aggregate = (processes, counters) => ({
+  processCount: processes.length,
+  currentCpuPercent: processes.reduce((total, process) => total + process.cpuPercent, 0),
+  cpuTimeMs: counters.cpuTimeMs,
+  currentRssBytes: processes.reduce((total, process) => total + process.residentBytes, 0),
+  peakRssBytes: processes.reduce((total, process) => total + process.peakResidentBytes, 0),
+  ioReadBytes: counters.ioReadBytes,
+  ioWriteBytes: counters.ioWriteBytes,
+  ioReadBytesPerSecond: processes.reduce(
+    (total, process) => total + process.ioReadBytesPerSecond,
+    0
+  ),
+  ioWriteBytesPerSecond: processes.reduce(
+    (total, process) => total + process.ioWriteBytesPerSecond,
+    0
+  ),
+  processStarts: counters.processStarts,
+  processExits: counters.processExits
+});
+var mergeProcesses = (input) => {
+  const sampledAtMs = input.snapshot.sampledAtUnixMs;
+  const samples = input.snapshot.processes;
+  const rootPids = [input.serverPid];
+  const depths = processDepths(samples, new Set(rootPids));
+  const childrenByParent = /* @__PURE__ */ new Map();
+  for (const sample of samples) {
+    const children = childrenByParent.get(sample.ppid) ?? [];
+    children.push(sample.pid);
+    childrenByParent.set(sample.ppid, children);
+  }
+  const nextPrevious = /* @__PURE__ */ new Map();
+  const deltas = [];
+  const normalized = samples.map((sample) => {
+    const identityKey = processIdentityKey(sample.pid, sample.startTimeMs);
+    const previous = input.previous.get(identityKey);
+    const elapsedMs = previous ? sampledAtMs - previous.sampledAtMs : 0;
+    const cpuTimeDelta = previous ? delta({ current: sample.cpuTimeMs, previous: previous.process.cpuTimeMs, elapsedMs }) : 0;
+    const ioReadDelta = previous ? delta({ current: sample.ioReadBytes, previous: previous.process.ioReadBytes, elapsedMs }) : 0;
+    const ioWriteDelta = previous ? delta({ current: sample.ioWriteBytes, previous: previous.process.ioWriteBytes, elapsedMs }) : 0;
+    const category = sample.pid === input.serverPid ? "server" : sample.pid === input.sidecarPid ? "resource-monitor" : "server-child";
+    const cpuPercent = previous && elapsedMs > 0 && elapsedMs <= MAX_DELTA_INTERVAL_MS ? cpuTimeDelta / elapsedMs * 100 : finiteNonNegative(sample.cpuPercent);
+    const process = {
+      identity: { pid: sample.pid, startTimeMs: sample.startTimeMs },
+      ppid: sample.ppid,
+      childPids: [...childrenByParent.get(sample.pid) ?? []].toSorted(
+        (left, right) => left - right
+      ),
+      depth: depths.get(sample.pid) ?? 0,
+      name: sample.name,
+      command: sample.command,
+      status: sample.status,
+      category,
+      cpuPercent: finiteNonNegative(cpuPercent),
+      cpuTimeMs: sample.cpuTimeMs,
+      residentBytes: sample.residentBytes,
+      peakResidentBytes: Math.max(sample.residentBytes, previous?.process.peakResidentBytes ?? 0),
+      virtualBytes: sample.virtualBytes,
+      ioReadBytes: sample.ioReadBytes,
+      ioWriteBytes: sample.ioWriteBytes,
+      ioReadBytesPerSecond: elapsedMs > 0 ? finiteNonNegative(ioReadDelta * 1e3 / elapsedMs) : 0,
+      ioWriteBytesPerSecond: elapsedMs > 0 ? finiteNonNegative(ioWriteDelta * 1e3 / elapsedMs) : 0,
+      ioSemantics: sample.ioSemantics,
+      runTimeMs: sample.runTimeMs,
+      firstSeenAtIso: previous?.process.firstSeenAtIso ?? toIso(sampledAtMs),
+      lastSeenAtIso: toIso(sampledAtMs)
+    };
+    nextPrevious.set(identityKey, { process, sampledAtMs });
+    deltas.push({
+      identityKey,
+      category,
+      cpuTimeMs: cpuTimeDelta,
+      ioReadBytes: ioReadDelta,
+      ioWriteBytes: ioWriteDelta
+    });
+    return process;
+  });
+  const ordered = orderProcessTree(normalized, rootPids);
+  const counters = applyLifecycleCounters({
+    counters: input.counters,
+    deltas,
+    current: nextPrevious,
+    previous: input.previous
+  });
+  const monitorProcesses = ordered.filter(
+    (process) => categoryGroup(process.category) === "monitor"
+  );
+  const backendProcesses = ordered.filter(
+    (process) => categoryGroup(process.category) === "backend"
+  );
+  return {
+    sampledAtMs,
+    processes: ordered,
+    previous: nextPrevious,
+    counters,
+    groups: {
+      backend: aggregate(backendProcesses, counters.backend),
+      monitor: aggregate(monitorProcesses, counters.monitor),
+      all: aggregate(ordered, counters.all)
+    },
+    deltas
+  };
+};
+var normalizeHistoryInput = (input) => {
+  const windowMs = Math.max(1e3, Math.min(MAX_HISTORY_WINDOW_MS, Math.round(input.windowMs)));
+  return {
+    windowMs,
+    bucketMs: Math.max(1e3, Math.min(windowMs, Math.round(input.bucketMs)))
+  };
+};
+var summarizeProcesses = (samples) => {
+  const groups = /* @__PURE__ */ new Map();
+  for (const sample of samples) {
+    const identityKey = processIdentityKey(
+      sample.process.identity.pid,
+      sample.process.identity.startTimeMs
+    );
+    const current = groups.get(identityKey) ?? [];
+    current.push(sample);
+    groups.set(identityKey, current);
+  }
+  return [...groups.values()].map((processSamples) => {
+    const sorted = processSamples.toSorted((left, right) => left.sampledAtMs - right.sampledAtMs);
+    const first = sorted[0];
+    const latest = sorted[sorted.length - 1];
+    const cpuTotal = sorted.reduce((total, sample) => total + sample.process.cpuPercent, 0);
+    return {
+      identity: latest.process.identity,
+      ppid: latest.process.ppid,
+      depth: latest.process.depth,
+      name: latest.process.name,
+      command: latest.process.command,
+      category: latest.process.category,
+      firstSeenAtIso: first.process.firstSeenAtIso,
+      lastSeenAtIso: latest.process.lastSeenAtIso,
+      currentCpuPercent: latest.process.cpuPercent,
+      avgCpuPercent: cpuTotal / sorted.length,
+      maxCpuPercent: Math.max(...sorted.map((sample) => sample.process.cpuPercent)),
+      cpuTimeMs: sorted.reduce((total, sample) => total + sample.cpuTimeMs, 0),
+      currentRssBytes: latest.process.residentBytes,
+      peakRssBytes: Math.max(...sorted.map((sample) => sample.process.residentBytes)),
+      ioReadBytes: sorted.reduce((total, sample) => total + sample.ioReadBytes, 0),
+      ioWriteBytes: sorted.reduce((total, sample) => total + sample.ioWriteBytes, 0),
+      ioSemantics: latest.process.ioSemantics,
+      sampleCount: sorted.length
+    };
+  }).toSorted(
+    (left, right) => right.cpuTimeMs - left.cpuTimeMs || right.peakRssBytes - left.peakRssBytes
+  );
+};
+var buildBuckets = (input) => {
+  const buckets = [];
+  for (let startedAtMs = input.nowMs - input.windowMs; startedAtMs < input.nowMs; startedAtMs += input.bucketMs) {
+    const endedAtMs = Math.min(input.nowMs, startedAtMs + input.bucketMs);
+    const samples = input.samples.filter(
+      (sample) => sample.sampledAtMs >= startedAtMs && (endedAtMs === input.nowMs ? sample.sampledAtMs <= endedAtMs : sample.sampledAtMs < endedAtMs)
+    );
+    const cpuTotal = samples.reduce((total, sample) => total + sample.cpuPercent, 0);
+    buckets.push({
+      startedAtIso: toIso(startedAtMs),
+      endedAtIso: toIso(endedAtMs),
+      avgCpuPercent: samples.length === 0 ? 0 : cpuTotal / samples.length,
+      maxCpuPercent: samples.length === 0 ? 0 : Math.max(...samples.map((sample) => sample.cpuPercent)),
+      maxRssBytes: samples.length === 0 ? 0 : Math.max(...samples.map((sample) => sample.rssBytes)),
+      ioReadBytes: samples.reduce((total, sample) => total + sample.ioReadBytes, 0),
+      ioWriteBytes: samples.reduce((total, sample) => total + sample.ioWriteBytes, 0),
+      maxProcessCount: samples.length === 0 ? 0 : Math.max(...samples.map((sample) => sample.processCount))
+    });
+  }
+  return buckets;
+};
+var buildHistory = (input) => {
+  const { windowMs, bucketMs } = normalizeHistoryInput(input);
+  const windowStartMs = input.readAtMs - windowMs;
+  const eligible = input.snapshots.filter((snapshot) => snapshot.sampledAtUnixMs <= input.readAtMs).toSorted((left, right) => left.sampledAtUnixMs - right.sampledAtUnixMs);
+  const inWindow = eligible.filter((snapshot) => snapshot.sampledAtUnixMs >= windowStartMs);
+  const preceding = eligible.findLast((snapshot) => snapshot.sampledAtUnixMs < windowStartMs);
+  const snapshots = preceding ? [preceding, ...inWindow] : inWindow;
+  const aggregateSamples = [];
+  const processSamples = [];
+  let previous = /* @__PURE__ */ new Map();
+  let counters = emptyTelemetryCounters();
+  let previousSnapshotAtMs;
+  for (const snapshot of snapshots) {
+    const windowFraction = previousSnapshotAtMs !== void 0 && previousSnapshotAtMs < windowStartMs && snapshot.sampledAtUnixMs > previousSnapshotAtMs ? Math.max(
+      0,
+      Math.min(
+        1,
+        (snapshot.sampledAtUnixMs - windowStartMs) / (snapshot.sampledAtUnixMs - previousSnapshotAtMs)
+      )
+    ) : 1;
+    previousSnapshotAtMs = snapshot.sampledAtUnixMs;
+    const merged = mergeProcesses({
+      serverPid: input.serverPid,
+      sidecarPid: input.sidecarPid,
+      snapshot,
+      previous,
+      counters
+    });
+    previous = new Map([...previous, ...merged.previous]);
+    counters = merged.counters;
+    if (snapshot.sampledAtUnixMs < windowStartMs) continue;
+    const deltas = windowFraction === 1 ? merged.deltas : merged.deltas.map((processDelta) => ({
+      ...processDelta,
+      cpuTimeMs: Math.round(processDelta.cpuTimeMs * windowFraction),
+      ioReadBytes: Math.round(processDelta.ioReadBytes * windowFraction),
+      ioWriteBytes: Math.round(processDelta.ioWriteBytes * windowFraction)
+    }));
+    const deltasByIdentity = new Map(
+      deltas.map((processDelta) => [processDelta.identityKey, processDelta])
+    );
+    aggregateSamples.push({
+      sampledAtMs: snapshot.sampledAtUnixMs,
+      cpuPercent: merged.groups.all.currentCpuPercent,
+      rssBytes: merged.groups.all.currentRssBytes,
+      processCount: merged.groups.all.processCount,
+      ioReadBytes: deltas.reduce((total, item) => total + item.ioReadBytes, 0),
+      ioWriteBytes: deltas.reduce((total, item) => total + item.ioWriteBytes, 0)
+    });
+    for (const process of merged.processes) {
+      const processDelta = deltasByIdentity.get(
+        processIdentityKey(process.identity.pid, process.identity.startTimeMs)
+      );
+      processSamples.push({
+        sampledAtMs: snapshot.sampledAtUnixMs,
+        process,
+        cpuTimeMs: processDelta?.cpuTimeMs ?? 0,
+        ioReadBytes: processDelta?.ioReadBytes ?? 0,
+        ioWriteBytes: processDelta?.ioWriteBytes ?? 0
+      });
+    }
+  }
+  return {
+    windowMs,
+    bucketMs,
+    retainedSampleCount: aggregateSamples.length + processSamples.length,
+    buckets: buildBuckets({
+      samples: aggregateSamples,
+      nowMs: input.readAtMs,
+      windowMs,
+      bucketMs
+    }),
+    topProcesses: summarizeProcesses(processSamples)
+  };
+};
+
+// src/sidecar.ts
+import * as NodeCrypto from "node:crypto";
+var SAMPLE_INTERVAL_MS = 1e3;
+var UNKNOWN_BACKGROUND_SAMPLE_INTERVAL_MS = 5e3;
+var BATTERY_SAMPLE_INTERVAL_MS = 5e3;
+var CONSTRAINED_SAMPLE_INTERVAL_MS = 15e3;
+var HANDSHAKE_TIMEOUT_MS = 5e3;
+var SAMPLE_REQUEST_TIMEOUT_MS = 5e3;
+var HISTORY_REQUEST_TIMEOUT_MS = 15e3;
+var INITIAL_RESTART_DELAY_MS = 500;
+var MAX_RESTART_DELAY_MS = 1e4;
+var FAILURE_WINDOW_MS = 6e4;
+var MAX_FAILURES_PER_WINDOW = 5;
+var STDERR_TAIL_LIMIT = 2e3;
+var resolveSampleIntervalMs = (power, liveSubscriberCount) => {
+  if (power === null || power.stale || power.source === "unknown") {
+    return liveSubscriberCount > 0 ? SAMPLE_INTERVAL_MS : UNKNOWN_BACKGROUND_SAMPLE_INTERVAL_MS;
+  }
+  if (power.suspended || power.locked === "true" || power.lowPowerMode === "true" || power.thermalState === "serious" || power.thermalState === "critical") {
+    return CONSTRAINED_SAMPLE_INTERVAL_MS;
+  }
+  return power.onBattery === "false" ? SAMPLE_INTERVAL_MS : BATTERY_SAMPLE_INTERVAL_MS;
+};
+var restartDelayMs = (attempt) => Math.min(INITIAL_RESTART_DELAY_MS * 2 ** attempt, MAX_RESTART_DELAY_MS);
+var toError = (value) => value instanceof Error ? value : new Error(String(value));
+var TelemetrySidecar = class {
+  input;
+  state = {
+    status: "starting",
+    hello: null,
+    lastSampleAtMs: null,
+    lastError: null,
+    restartCount: 0,
+    collectionDurationMicros: 0,
+    scannedProcessCount: 0,
+    retainedProcessCount: 0,
+    inaccessibleProcessCount: 0
+  };
+  listeners = /* @__PURE__ */ new Set();
+  pendingSamples = /* @__PURE__ */ new Map();
+  pendingHistories = /* @__PURE__ */ new Map();
+  handle = null;
+  generation = 0;
+  liveSubscriberCount = 0;
+  power = null;
+  sampleIntervalMs = UNKNOWN_BACKGROUND_SAMPLE_INTERVAL_MS;
+  streamingApplied = false;
+  intervalApplied = 0;
+  stopped = false;
+  supervisor = null;
+  supervisorRunning = false;
+  /** 命令按序写，不并发：两条命令交错写进同一条 stdin 会拼出一行坏 JSON。 */
+  writeChain = Promise.resolve();
+  retrySignal = null;
+  /** 重启请求可能落在「刚失败、还没开始等」的缝里；记成标志，等的那一方进门先查。 */
+  retryRequested = false;
+  constructor(input) {
+    this.input = input;
+  }
+  /** 起监督循环。不 await：activate 有 5 秒上限，握手不该占用它。 */
+  start() {
+    if (this.supervisor !== null || this.stopped) return;
+    if (this.input.program === null) {
+      this.state.status = "unavailable";
+      this.state.lastError = "the resource monitor binary was not resolved on this environment";
+      return;
+    }
+    this.supervisor = this.supervise().catch((error) => {
+      this.state.status = "unavailable";
+      this.state.lastError = toError(error).message;
+      this.input.log.warn("resource monitor supervisor stopped unexpectedly", {
+        error: toError(error).message
+      });
+    });
+  }
+  /** 插件停用即杀 sidecar：不再重启，句柄自己关掉，不指望别人替它收尾。 */
+  async stop() {
+    this.stopped = true;
+    this.retrySignal?.();
+    this.retrySignal = null;
+    const handle = this.handle;
+    this.handle = null;
+    if (handle !== null) {
+      try {
+        await handle.kill();
+      } catch {
+      }
+    }
+    this.failPending(new Error("the resource monitor was stopped"));
+    this.state.status = "stopped";
+    this.state.hello = null;
+    const supervisor = this.supervisor;
+    this.supervisor = null;
+    if (supervisor !== null) await supervisor;
+  }
+  health() {
+    return {
+      status: this.state.status,
+      sidecarVersion: this.state.hello?.sidecarVersion ?? null,
+      sidecarPid: this.state.hello?.sidecarPid ?? null,
+      restartCount: this.state.restartCount,
+      lastSampleAtIso: this.state.lastSampleAtMs === null ? null : new Date(this.state.lastSampleAtMs).toISOString(),
+      lastError: this.state.lastError,
+      sampleIntervalMs: this.sampleIntervalMs,
+      collectionDurationMicros: this.state.collectionDurationMicros,
+      scannedProcessCount: this.state.scannedProcessCount,
+      retainedProcessCount: this.state.retainedProcessCount,
+      inaccessibleProcessCount: this.state.inaccessibleProcessCount
+    };
+  }
+  /** sidecar 自己的 pid，用来把它从被观察的进程里认出来。 */
+  sidecarPid() {
+    return this.state.hello?.sidecarPid ?? null;
+  }
+  onSnapshot(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /** 订阅方 +1；返回的函数是 -1。数到 0 就关掉推流。 */
+  retainStreaming() {
+    this.liveSubscriberCount += 1;
+    void this.applyControl();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.liveSubscriberCount = Math.max(0, this.liveSubscriberCount - 1);
+      void this.applyControl();
+    };
+  }
+  /** 电源快照只能轮询（宿主不推给插件），拿到就重算节奏。 */
+  applyPower(power) {
+    this.power = power;
+    void this.applyControl();
+  }
+  /**
+   * 显式重启。熔断之后唯一能合上电路的东西；跑着的时候调它没有意义，返回 false。
+   */
+  retry() {
+    if (this.stopped || this.input.program === null) return false;
+    if (this.state.status === "healthy" || this.state.status === "starting") return false;
+    if (this.handle !== null) return false;
+    if (!this.supervisorRunning) return false;
+    this.retryRequested = true;
+    this.retrySignal?.();
+    return true;
+  }
+  async sampleNow() {
+    this.assertCommandable();
+    const requestId = NodeCrypto.randomUUID();
+    const settled = new Promise((resolve, reject) => {
+      this.pendingSamples.set(requestId, { resolve, reject });
+    });
+    try {
+      await this.write({
+        version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+        type: "sampleNow",
+        requestId
+      });
+      return await withTimeout(settled, SAMPLE_REQUEST_TIMEOUT_MS, "sampleNow");
+    } finally {
+      this.pendingSamples.delete(requestId);
+    }
+  }
+  async readHistory(windowMs) {
+    this.assertCommandable();
+    const requestId = NodeCrypto.randomUUID();
+    const settled = new Promise((resolve, reject) => {
+      this.pendingHistories.set(requestId, { resolve, reject, snapshots: [] });
+    });
+    try {
+      await this.write({
+        version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+        type: "readHistory",
+        requestId,
+        windowMs: Math.max(0, Math.round(windowMs))
+      });
+      return await withTimeout(settled, HISTORY_REQUEST_TIMEOUT_MS, "readHistory");
+    } finally {
+      this.pendingHistories.delete(requestId);
+    }
+  }
+  // ── 内部 ────────────────────────────────────────────────────
+  assertCommandable() {
+    if (this.handle === null || this.state.status !== "healthy" && this.state.status !== "degraded") {
+      throw new Error(
+        `the resource monitor is not running: ${this.state.lastError ?? this.state.status}`
+      );
+    }
+  }
+  write(command) {
+    const handle = this.handle;
+    if (handle === null) return Promise.reject(new Error("the resource monitor is not running"));
+    const line = `${JSON.stringify(command)}
+`;
+    this.writeChain = this.writeChain.then(
+      () => handle.writeStdin(line),
+      () => handle.writeStdin(line)
+    );
+    return this.writeChain;
+  }
+  /** 把「想要的采样节奏 / 推不推流」推给 sidecar；只在真的变了时才写命令。 */
+  async applyControl() {
+    const desiredInterval = resolveSampleIntervalMs(this.power, this.liveSubscriberCount);
+    this.sampleIntervalMs = desiredInterval;
+    const desiredStreaming = this.liveSubscriberCount > 0;
+    if (this.handle === null) return;
+    if (this.state.status !== "healthy" && this.state.status !== "degraded") return;
+    try {
+      if (this.intervalApplied !== desiredInterval) {
+        await this.write({
+          version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+          type: "setSampleInterval",
+          sampleIntervalMs: desiredInterval
+        });
+        this.intervalApplied = desiredInterval;
+      }
+      if (this.streamingApplied !== desiredStreaming) {
+        await this.write({
+          version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+          type: "setStreaming",
+          enabled: desiredStreaming
+        });
+        this.streamingApplied = desiredStreaming;
+      }
+    } catch (error) {
+      this.input.log.warn("resource monitor control write failed", {
+        error: toError(error).message
+      });
+    }
+  }
+  failPending(error) {
+    for (const pending of this.pendingSamples.values()) pending.reject(error);
+    this.pendingSamples.clear();
+    for (const pending of this.pendingHistories.values()) pending.reject(error);
+    this.pendingHistories.clear();
+  }
+  async supervise() {
+    this.supervisorRunning = true;
+    try {
+      await this.superviseLoop();
+    } finally {
+      this.supervisorRunning = false;
+    }
+  }
+  async superviseLoop() {
+    let failures = [];
+    let attempt = 0;
+    while (!this.stopped) {
+      const outcome = await this.runAttempt();
+      if (this.stopped) break;
+      if (outcome.fatal) {
+        this.state.status = "unavailable";
+        this.state.lastError = outcome.error.message;
+        this.failPending(outcome.error);
+        this.input.log.warn("resource monitor cannot start", { error: outcome.error.message });
+        return;
+      }
+      const now = Date.now();
+      failures = failures.filter((failedAt) => now - failedAt <= FAILURE_WINDOW_MS);
+      if (failures.length === 0) attempt = 0;
+      failures.push(now);
+      const exhausted = failures.length >= MAX_FAILURES_PER_WINDOW;
+      this.state.status = exhausted ? "unavailable" : "degraded";
+      this.state.hello = null;
+      this.state.lastError = outcome.error.message;
+      this.state.restartCount += 1;
+      this.failPending(outcome.error);
+      this.input.log.warn("resource monitor stopped", {
+        error: outcome.error.message,
+        restartCount: this.state.restartCount,
+        circuitOpen: exhausted
+      });
+      if (exhausted) {
+        await this.waitForRetry();
+        if (this.stopped) break;
+        failures = [];
+        attempt = 0;
+        this.state.status = "starting";
+        this.state.lastError = null;
+        continue;
+      }
+      const manuallyRetried = await this.waitForRetryOrDelay(restartDelayMs(attempt));
+      attempt = manuallyRetried ? 0 : attempt + 1;
+    }
+  }
+  consumeRetryRequest() {
+    const requested = this.retryRequested;
+    this.retryRequested = false;
+    return requested;
+  }
+  waitForRetry() {
+    if (this.consumeRetryRequest()) return Promise.resolve();
+    return new Promise((resolve) => {
+      this.retrySignal = () => {
+        this.retrySignal = null;
+        this.retryRequested = false;
+        resolve();
+      };
+    });
+  }
+  waitForRetryOrDelay(delayMs) {
+    if (this.consumeRetryRequest()) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.retrySignal = null;
+        resolve(false);
+      }, delayMs);
+      this.retrySignal = () => {
+        this.retrySignal = null;
+        this.retryRequested = false;
+        clearTimeout(timer);
+        resolve(true);
+      };
+    });
+  }
+  /**
+   * 一次 incarnation：起进程、握手、跑到它以某种方式结束为止。返回结束的原因；
+   * `fatal` 表示这个原因重试也没用。
+   */
+  async runAttempt() {
+    const program = this.input.program;
+    if (program === null) {
+      return {
+        error: new Error("the resource monitor binary was not resolved on this environment"),
+        fatal: true
+      };
+    }
+    let handle;
+    try {
+      handle = await this.input.process.spawn({ program });
+    } catch (error2) {
+      const reason = error2.reason;
+      return {
+        error: toError(error2),
+        fatal: reason === "undeclared" || reason === "not-declared" || reason === "unknown-key"
+      };
+    }
+    this.generation += 1;
+    const generation = this.generation;
+    this.handle = handle;
+    this.writeChain = Promise.resolve();
+    this.streamingApplied = false;
+    this.intervalApplied = 0;
+    this.state.status = "starting";
+    this.state.hello = null;
+    let settle = () => void 0;
+    const ended = new Promise((resolve) => {
+      settle = resolve;
+    });
+    let onHello = () => void 0;
+    const helloReceived = new Promise((resolve) => {
+      onHello = resolve;
+    });
+    let stderrTail = "";
+    const stdoutPump = pumpLines(handle.stdout, (line) => {
+      this.consumeLine(line, generation, onHello, settle);
+    }).then(
+      () => settle(new Error("the resource monitor event stream closed")),
+      (error2) => settle(toError(error2))
+    );
+    const stderrPump = pumpChunks(handle.stderr, (text) => {
+      stderrTail = `${stderrTail}${text}`.slice(-STDERR_TAIL_LIMIT);
+    }).catch(() => void 0);
+    void handle.exited.then(
+      (code) => {
+        const tail = stderrTail.trim();
+        settle(
+          new Error(
+            `the resource monitor exited with code ${String(code)}${tail.length > 0 ? `: ${tail}` : ""}`
+          )
+        );
+      },
+      () => settle(new Error("the resource monitor ended unexpectedly"))
+    );
+    const hello = await raceHandshake(helloReceived, ended, HANDSHAKE_TIMEOUT_MS);
+    if (hello !== null) {
+      this.state.hello = hello;
+      this.state.status = "healthy";
+      this.state.lastError = null;
+      try {
+        await this.write({
+          version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+          type: "configure",
+          rootPid: this.input.rootPid,
+          sampleIntervalMs: resolveSampleIntervalMs(this.power, this.liveSubscriberCount),
+          externalProcesses: []
+        });
+        this.intervalApplied = resolveSampleIntervalMs(this.power, this.liveSubscriberCount);
+        this.sampleIntervalMs = this.intervalApplied;
+        if (this.liveSubscriberCount > 0) {
+          await this.write({
+            version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+            type: "setStreaming",
+            enabled: true
+          });
+          this.streamingApplied = true;
+        }
+      } catch (error2) {
+        settle(toError(error2));
+      }
+    } else {
+      settle(new Error(`the resource monitor handshake timed out after ${HANDSHAKE_TIMEOUT_MS}ms`));
+    }
+    const error = await ended;
+    this.handle = null;
+    try {
+      await handle.kill();
+    } catch {
+    }
+    await Promise.all([stdoutPump, stderrPump]);
+    return { error, fatal: false };
+  }
+  consumeLine(line, generation, onHello, settle) {
+    if (line.trim().length === 0) return;
+    let value;
+    try {
+      value = JSON.parse(line);
+    } catch {
+      settle(new Error("the resource monitor wrote a line that is not JSON"));
+      return;
+    }
+    const version = readEventVersion(value);
+    if (version !== null && version !== RESOURCE_MONITOR_PROTOCOL_VERSION) {
+      settle(
+        new Error(
+          `the resource monitor speaks protocol ${String(version)}, this build expects ${String(RESOURCE_MONITOR_PROTOCOL_VERSION)}`
+        )
+      );
+      return;
+    }
+    const event = parseMonitorEvent(value);
+    if (event === null) {
+      settle(new Error("the resource monitor sent an event this build does not understand"));
+      return;
+    }
+    switch (event.type) {
+      case "hello":
+        onHello(event);
+        return;
+      case "snapshot": {
+        this.state.status = "healthy";
+        this.state.lastError = null;
+        this.state.lastSampleAtMs = event.sampledAtUnixMs;
+        this.state.collectionDurationMicros = event.collectionDurationMicros;
+        this.state.scannedProcessCount = event.scannedProcessCount;
+        this.state.retainedProcessCount = event.retainedProcessCount;
+        this.state.inaccessibleProcessCount = event.inaccessibleProcessCount;
+        const requestId = event.requestId;
+        if (requestId !== void 0) {
+          const pending = this.pendingSamples.get(requestId);
+          if (pending !== void 0) {
+            this.pendingSamples.delete(requestId);
+            pending.resolve(event);
+          }
+        }
+        for (const listener of this.listeners) listener({ generation, snapshot: event });
+        return;
+      }
+      case "historyChunk": {
+        const pending = this.pendingHistories.get(event.requestId);
+        if (pending === void 0) return;
+        pending.snapshots.push(...event.snapshots);
+        if (event.done) {
+          this.pendingHistories.delete(event.requestId);
+          pending.resolve(pending.snapshots);
+        }
+        return;
+      }
+      case "error":
+        this.state.lastError = event.message;
+        if (event.recoverable) {
+          this.state.status = "degraded";
+          this.input.log.warn("resource monitor reported an error", {
+            code: event.code,
+            error: event.message
+          });
+          return;
+        }
+        settle(new Error(`the resource monitor failed (${event.code}): ${event.message}`));
+        return;
+    }
+  }
+};
+var raceHandshake = (hello, ended, timeoutMs) => {
+  let timer;
+  return Promise.race([
+    hello,
+    ended.then(() => null),
+    new Promise((resolve) => {
+      timer = setTimeout(() => resolve(null), timeoutMs);
+    })
+  ]).finally(() => {
+    if (timer !== void 0) clearTimeout(timer);
+  });
+};
+var withTimeout = (promise, timeoutMs, operation) => {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(
+          new Error(
+            `the resource monitor '${operation}' request timed out after ${String(timeoutMs)}ms`
+          )
+        );
+      }, timeoutMs);
+    })
+  ]).finally(() => {
+    if (timer !== void 0) clearTimeout(timer);
+  });
+};
+var pumpLines = async (source, onLine) => {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of source) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let index = buffer.indexOf("\n");
+    while (index >= 0) {
+      onLine(buffer.slice(0, index));
+      buffer = buffer.slice(index + 1);
+      index = buffer.indexOf("\n");
+    }
+  }
+  onLine(buffer);
+};
+var pumpChunks = async (source, onText) => {
+  const decoder = new TextDecoder();
+  for await (const chunk of source) onText(decoder.decode(chunk, { stream: true }));
+};
+
+// src/index.ts
+var unknownPower = (readAtIso) => ({
+  source: "unknown",
+  idle: "unknown",
+  idleSeconds: null,
+  locked: "unknown",
+  suspended: false,
+  onBattery: "unknown",
+  lowPowerMode: "unknown",
+  thermalState: "unknown",
+  stale: true,
+  updatedAtIso: readAtIso
+});
+var EMPTY_PAYLOAD_SCHEMA = {
+  type: "object",
+  properties: {},
+  additionalProperties: false
+};
+var HISTORY_PAYLOAD_SCHEMA = {
+  type: "object",
+  properties: {
+    windowMs: { type: "number", minimum: 0 },
+    bucketMs: { type: "number", minimum: 0 }
+  },
+  additionalProperties: false
+};
+var DEFAULT_HISTORY_WINDOW_MS = 15 * 6e4;
+var DEFAULT_HISTORY_BUCKET_MS = 15e3;
+var POWER_POLL_INTERVAL_MS = 3e4;
+var TelemetryRuntime = class {
+  ctx;
+  sidecar;
+  subscribers = /* @__PURE__ */ new Set();
+  previous = /* @__PURE__ */ new Map();
+  counters = emptyTelemetryCounters();
+  latest;
+  lastGeneration = 0;
+  lastSequence = -1;
+  /** 合并按序做：两份快照并发进来会各自读到同一份 `previous`，速率就双算了。 */
+  chain = Promise.resolve();
+  powerWarned = false;
+  attributionWarned = false;
+  constructor(ctx) {
+    this.ctx = ctx;
+    const program = ctx.config.resourceMonitorPath?.trim();
+    this.sidecar = new TelemetrySidecar({
+      process: ctx.process,
+      program: program === void 0 || program.length === 0 ? null : program,
+      rootPid: NodeProcess.pid,
+      log: ctx.log
+    });
+    const readAtIso = (/* @__PURE__ */ new Date()).toISOString();
+    const empty = mergeProcesses({
+      serverPid: NodeProcess.pid,
+      sidecarPid: null,
+      snapshot: {
+        type: "snapshot",
+        sequence: 0,
+        sampledAtUnixMs: Date.now(),
+        collectionDurationMicros: 0,
+        scannedProcessCount: 0,
+        retainedProcessCount: 0,
+        inaccessibleProcessCount: 0,
+        processes: []
+      },
+      previous: /* @__PURE__ */ new Map(),
+      counters: emptyTelemetryCounters()
+    });
+    this.latest = {
+      readAtIso,
+      sampleIntervalMs: this.sidecar.health().sampleIntervalMs,
+      processes: [],
+      groups: empty.groups,
+      power: unknownPower(readAtIso),
+      attribution: { readAtIso, entries: [] },
+      health: this.sidecar.health()
+    };
+  }
+  start() {
+    this.sidecar.onSnapshot((item) => this.enqueue(item));
+    this.sidecar.start();
+  }
+  async stop() {
+    this.subscribers.clear();
+    await this.sidecar.stop();
+  }
+  currentSnapshot() {
+    this.latest = { ...this.latest, health: this.sidecar.health() };
+    return this.latest;
+  }
+  /**
+   * 取一份尽量新的：能采就现采一次，采不到就退回缓存的那一份，不让读侧失败。
+   *
+   * 采到的那一份是经**订阅回调**进合并的（sidecar 把每一份快照都广播出去，包括
+   * 应答 `sampleNow` 的那一份），所以这里等的是合并队列，不是再喂一次。
+   */
+  async refreshedSnapshot() {
+    try {
+      await this.sidecar.sampleNow();
+      await this.chain;
+    } catch (error) {
+      this.ctx.log.warn("resource monitor sample failed", { error: messageOf(error) });
+    }
+    return this.currentSnapshot();
+  }
+  async readHistory(input) {
+    const normalized = normalizeHistoryInput(input);
+    let snapshots = [];
+    try {
+      snapshots = await this.sidecar.readHistory(normalized.windowMs);
+    } catch (error) {
+      this.ctx.log.warn("resource monitor history read failed", { error: messageOf(error) });
+    }
+    const health = this.sidecar.health();
+    const built = buildHistory({
+      readAtMs: Date.now(),
+      windowMs: normalized.windowMs,
+      bucketMs: normalized.bucketMs,
+      serverPid: NodeProcess.pid,
+      sidecarPid: this.sidecar.sidecarPid(),
+      snapshots
+    });
+    return {
+      readAtIso: (/* @__PURE__ */ new Date()).toISOString(),
+      windowMs: built.windowMs,
+      bucketMs: built.bucketMs,
+      sampleIntervalMs: health.sampleIntervalMs,
+      retainedSampleCount: built.retainedSampleCount,
+      buckets: built.buckets,
+      topProcesses: built.topProcesses,
+      health
+    };
+  }
+  retry() {
+    return { accepted: this.sidecar.retry(), snapshot: this.currentSnapshot() };
+  }
+  /** 订阅一条流：+1 推流引用，返回的函数在订阅方挂断时调。 */
+  retain(listener) {
+    this.subscribers.add(listener);
+    const release = this.sidecar.retainStreaming();
+    void this.sidecar.sampleNow().catch(() => void 0);
+    return () => {
+      this.subscribers.delete(listener);
+      release();
+    };
+  }
+  /** 电源轮询：拿到就喂给 sidecar 重算节奏，并把它记进下一份快照。 */
+  async pollPower() {
+    this.sidecar.applyPower(await this.readPower());
+  }
+  enqueue(item) {
+    this.chain = this.chain.then(
+      () => this.ingest(item),
+      () => this.ingest(item)
+    );
+    void this.chain.catch((error) => {
+      this.ctx.log.warn("resource telemetry ingest failed", { error: messageOf(error) });
+    });
+  }
+  async ingest(item) {
+    if (item.generation < this.lastGeneration) return;
+    if (item.generation === this.lastGeneration && item.snapshot.sequence <= this.lastSequence) {
+      return;
+    }
+    const merged = mergeProcesses({
+      serverPid: NodeProcess.pid,
+      sidecarPid: this.sidecar.sidecarPid(),
+      snapshot: item.snapshot,
+      previous: this.previous,
+      counters: this.counters
+    });
+    this.previous = merged.previous;
+    this.counters = merged.counters;
+    this.lastGeneration = item.generation;
+    this.lastSequence = item.snapshot.sequence;
+    const [power, attribution] = await Promise.all([this.readPower(), this.readAttribution()]);
+    const readAtIso = new Date(merged.sampledAtMs).toISOString();
+    this.sidecar.applyPower(power);
+    this.latest = {
+      readAtIso,
+      sampleIntervalMs: this.sidecar.health().sampleIntervalMs,
+      processes: merged.processes,
+      groups: merged.groups,
+      power: power ?? unknownPower(readAtIso),
+      attribution: attribution ?? { readAtIso, entries: [] },
+      health: this.sidecar.health()
+    };
+    for (const listener of this.subscribers) listener(this.latest);
+  }
+  /** 宿主没装遥测层（`ycodium x` 那种 CLI 装配）时这条会被拒；那不该拖垮采样。 */
+  async readPower() {
+    try {
+      return await this.ctx.projections.getPower();
+    } catch (error) {
+      if (!this.powerWarned) {
+        this.powerWarned = true;
+        this.ctx.log.warn("host power state is unavailable", { error: messageOf(error) });
+      }
+      return null;
+    }
+  }
+  async readAttribution() {
+    try {
+      return await this.ctx.projections.getAttribution();
+    } catch (error) {
+      if (!this.attributionWarned) {
+        this.attributionWarned = true;
+        this.ctx.log.warn("host io attribution is unavailable", { error: messageOf(error) });
+      }
+      return null;
+    }
+  }
+};
+var messageOf = (error) => error instanceof Error ? error.message : String(error);
+var numberField = (payload, key, fallback) => {
+  const value = payload[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+};
+var index_default = definePlugin({
+  id: "resource-telemetry",
+  apiVersion: 2,
+  activate: (ctx) => {
+    const runtime = new TelemetryRuntime(ctx);
+    runtime.start();
+    ctx.stream({
+      name: "snapshots",
+      description: "Live process, group, power and I/O telemetry for this environment.",
+      scope: "read",
+      payloadSchema: EMPTY_PAYLOAD_SCHEMA,
+      // 持续推状态的流必须封顶：慢订阅方丢掉的是旧的那几份，不是宿主的内存。
+      buffer: { latest: 8 },
+      handle: async (_payload, emit, signal) => {
+        const release = runtime.retain((snapshot) => {
+          if (!signal.aborted) emit(snapshot);
+        });
+        try {
+          emit(runtime.currentSnapshot());
+          await new Promise((resolve) => {
+            if (signal.aborted) {
+              resolve();
+              return;
+            }
+            signal.addEventListener("abort", () => resolve(), { once: true });
+          });
+        } finally {
+          release();
+        }
+      }
+    });
+    ctx.command({
+      name: "snapshot",
+      description: "One current telemetry snapshot, sampled on demand.",
+      scope: "read",
+      payloadSchema: EMPTY_PAYLOAD_SCHEMA,
+      handle: () => runtime.refreshedSnapshot()
+    });
+    ctx.command({
+      name: "history",
+      description: "Bucketed CPU, memory and I/O history replayed from the sidecar's ring buffer.",
+      scope: "read",
+      payloadSchema: HISTORY_PAYLOAD_SCHEMA,
+      handle: (payload) => runtime.readHistory({
+        windowMs: numberField(payload, "windowMs", DEFAULT_HISTORY_WINDOW_MS),
+        bucketMs: numberField(payload, "bucketMs", DEFAULT_HISTORY_BUCKET_MS)
+      })
+    });
+    ctx.command({
+      name: "retry",
+      description: "Closes the collector's circuit breaker and restarts the resource monitor.",
+      // 起进程的动作不是只读：熔断之后要不要再试一次，得由拿着 operate 凭据的人决定。
+      scope: "operate",
+      payloadSchema: EMPTY_PAYLOAD_SCHEMA,
+      handle: () => runtime.retry()
+    });
+    ctx.interval({
+      name: "power",
+      everyMs: POWER_POLL_INTERVAL_MS,
+      handle: () => runtime.pollPower()
+    });
+    ctx.onDispose(() => runtime.stop());
+  }
+});
+export {
+  index_default as default
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ycodium-ai/plugin-resource-telemetry",
+  "version": "0.2.0",
+  "description": "Measures what this machine's processes cost in CPU, memory and disk.",
+  "keywords": [
+    "telemetry",
+    "ycodium",
+    "ycodium-plugin"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-beta.103",
+    "effect": "4.0.0-beta.103",
+    "esbuild": "0.28.1",
+    "vite-plus": "0.2.2",
+    "@ycodium-ai/plugin-api": "0.1.1"
+  },
+  "ycodium": {
+    "plugin": "./dist/index.js",
+    "displayName": "Resource monitoring",
+    "description": "Measures what this machine's processes cost in CPU, memory and disk.",
+    "icon": "activity",
+    "permissions": [
+      {
+        "kind": "process.spawn",
+        "programs": [
+          "config:resourceMonitorPath"
+        ],
+        "maxConcurrent": 1
+      }
+    ]
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsgo --noEmit",
+    "test": "vp test run"
+  }
+}