Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

Reduce idle work and disk churn with native resource diagnostics (#2679)

Julius Marminge49c0d96edf28
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 21fbce026..5a418a463 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -22,6 +22,11 @@ jobs:
cache: true
run-install: true
+ - name: Setup Rust
+ uses: dtolnay/rust-toolchain@stable
+ with:
+ components: rustfmt
+
- name: Ensure Electron runtime is installed
run: vp run --filter @t3tools/desktop ensure:electron
@@ -31,6 +36,9 @@ jobs:
- name: Typecheck
run: vpr typecheck
+ - name: Check resource monitor formatting
+ run: cargo fmt --manifest-path native/resource-monitor/Cargo.toml -- --check
+
- name: Build desktop pipeline
run: vp run build:desktop
@@ -55,12 +63,18 @@ jobs:
cache: true
run-install: true
+ - name: Setup Rust
+ uses: dtolnay/rust-toolchain@stable
+
- name: Ensure Electron runtime is installed
run: vp run --filter @t3tools/desktop ensure:electron
- name: Test
run: vp run test
+ - name: Test resource monitor
+ run: cargo test --locked --manifest-path native/resource-monitor/Cargo.toml
+
mobile_native_static_analysis:
name: Mobile Native Static Analysis
runs-on: blacksmith-12vcpu-macos-26
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f6e876bde..bc0b0622d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -326,21 +326,29 @@ jobs:
platform: mac
target: dmg
arch: arm64
+ rust_target: aarch64-apple-darwin
+ resource_key: darwin-arm64
- label: macOS x64
runner: blacksmith-12vcpu-macos-26
platform: mac
target: dmg
arch: x64
+ rust_target: x86_64-apple-darwin
+ resource_key: darwin-x64
- label: Linux x64
runner: blacksmith-32vcpu-ubuntu-2404
platform: linux
target: AppImage
arch: x64
+ rust_target: x86_64-unknown-linux-gnu
+ resource_key: linux-x64
- label: Windows x64
runner: blacksmith-32vcpu-windows-2025
platform: win
target: nsis
arch: x64
+ rust_target: x86_64-pc-windows-msvc
+ resource_key: win32-x64
# - label: Windows arm64
# runner: windows-11-arm
# platform: win
@@ -360,6 +368,11 @@ jobs:
cache: true
run-install: true
+ - name: Setup Rust
+ uses: dtolnay/rust-toolchain@stable
+ with:
+ targets: ${{ matrix.rust_target }}
+
- name: Download relay client tracing config
uses: actions/download-artifact@v8
with:
@@ -598,6 +611,19 @@ jobs:
# done
# fi
+ - name: Collect resource monitor
+ shell: bash
+ run: |
+ set -euo pipefail
+ binary_name="t3-resource-monitor"
+ if [[ "${{ matrix.platform }}" == "win" ]]; then
+ binary_name="${binary_name}.exe"
+ fi
+ source_path="native/resource-monitor/target/${{ matrix.rust_target }}/release/${binary_name}"
+ target_dir="resource-monitor-publish/${{ matrix.resource_key }}"
+ mkdir -p "$target_dir"
+ cp "$source_path" "$target_dir/$binary_name"
+
- name: Upload build artifacts
uses: actions/upload-artifact@v7
with:
@@ -605,6 +631,13 @@ jobs:
path: release-publish/*
if-no-files-found: error
+ - name: Upload resource monitor
+ uses: actions/upload-artifact@v7
+ with:
+ name: resource-monitor-${{ matrix.resource_key }}
+ path: resource-monitor-publish/${{ matrix.resource_key }}/*
+ if-no-files-found: error
+
publish_cli:
name: Publish CLI to npm
needs: [preflight, relay_public_config, build]
@@ -659,6 +692,24 @@ jobs:
- name: Build CLI package
run: vp run --filter t3 build
+ - name: Download resource monitors
+ uses: actions/download-artifact@v8
+ with:
+ pattern: resource-monitor-*
+ path: ${{ runner.temp }}/resource-monitors
+
+ - name: Bundle resource monitors into CLI package
+ shell: bash
+ run: |
+ set -euo pipefail
+ for artifact_dir in "$RUNNER_TEMP"/resource-monitors/resource-monitor-*; do
+ resource_key="${artifact_dir##*/resource-monitor-}"
+ target_dir="apps/server/dist/resource-monitor/${resource_key}"
+ mkdir -p "$target_dir"
+ cp "$artifact_dir"/t3-resource-monitor* "$target_dir/"
+ chmod +x "$target_dir"/t3-resource-monitor 2>/dev/null || true
+ done
+
- name: Publish CLI package
run: node apps/server/scripts/cli.ts publish --tag "${{ needs.preflight.outputs.cli_dist_tag }}" --app-version "${{ needs.preflight.outputs.version }}" --verbose
diff --git a/.gitignore b/.gitignore
index 8e1669c81..07793efe9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,6 +30,7 @@ dist-electron/
.showcase/
apps/mobile/.showcase/
artifacts/app-store/screenshots/
+native/**/target/
node_modules/
.alchemy/
*.log
diff --git a/apps/desktop/src/app/DesktopAppIdentity.test.ts b/apps/desktop/src/app/DesktopAppIdentity.test.ts
index 50f82ac30..2eb540f05 100644
--- a/apps/desktop/src/app/DesktopAppIdentity.test.ts
+++ b/apps/desktop/src/app/DesktopAppIdentity.test.ts
@@ -55,6 +55,7 @@ const makeElectronAppLayer = (calls: ElectronAppCalls) =>
}),
setAppUserModelId: () => Effect.void,
requestSingleInstanceLock: Effect.succeed(true),
+ getAppMetrics: Effect.succeed([]),
isDefaultProtocolClient: () => Effect.succeed(false),
setAsDefaultProtocolClient: () => Effect.succeed(true),
setDesktopName: () => Effect.void,
diff --git a/apps/desktop/src/app/DesktopLifecycle.test.ts b/apps/desktop/src/app/DesktopLifecycle.test.ts
index 107ee21d2..e5ce72f8e 100644
--- a/apps/desktop/src/app/DesktopLifecycle.test.ts
+++ b/apps/desktop/src/app/DesktopLifecycle.test.ts
@@ -30,6 +30,7 @@ describe("DesktopLifecycle", () => {
setAboutPanelOptions: () => Effect.void,
setAppUserModelId: () => Effect.void,
requestSingleInstanceLock: Effect.succeed(true),
+ getAppMetrics: Effect.succeed([]),
isDefaultProtocolClient: () => Effect.succeed(false),
setAsDefaultProtocolClient: () => Effect.succeed(true),
setDesktopName: () => Effect.void,
diff --git a/apps/desktop/src/app/DesktopObservability.test.ts b/apps/desktop/src/app/DesktopObservability.test.ts
index 9438175f6..cd90e7951 100644
--- a/apps/desktop/src/app/DesktopObservability.test.ts
+++ b/apps/desktop/src/app/DesktopObservability.test.ts
@@ -49,20 +49,41 @@ const environmentInput = (baseDir: string) =>
runningUnderArm64Translation: false,
}) satisfies DesktopEnvironment.MakeDesktopEnvironmentInput;
-const makeEnvironmentLayer = (baseDir: string) =>
+const makeEnvironmentLayer = (baseDir: string, isDevelopment = true) =>
DesktopEnvironment.layer(environmentInput(baseDir)).pipe(
Layer.provide(
Layer.mergeAll(
NodeServices.layer,
DesktopConfig.layerTest({
T3CODE_HOME: baseDir,
- VITE_DEV_SERVER_URL: "http://127.0.0.1:5733",
+ VITE_DEV_SERVER_URL: isDevelopment ? "http://127.0.0.1:5733" : undefined,
}),
),
),
);
describe("DesktopObservability", () => {
+ it("advances a retained output offset instead of repeatedly copying a full head chunk", () => {
+ const maxBufferedBytes = 1024 * 1024;
+ const initial = DesktopObservability.appendBoundedOutputChunk(
+ {
+ runId: "test-run",
+ startDetails: "pid=123",
+ chunks: [],
+ byteLength: 0,
+ },
+ "stderr",
+ new Uint8Array(maxBufferedBytes),
+ );
+ const initialBackingBuffer = initial.chunks[0]?.chunk.buffer;
+
+ const next = DesktopObservability.appendBoundedOutputChunk(initial, "stderr", Uint8Array.of(1));
+
+ assert.equal(next.chunks[0]?.chunk.buffer, initialBackingBuffer);
+ assert.equal(next.chunks[0]?.offset, 1);
+ assert.equal(next.byteLength, maxBufferedBytes);
+ });
+
it.effect("persists desktop Effect logs as span events in desktop.trace.ndjson", () =>
Effect.gen(function* () {
const fileSystem = yield* FileSystem.FileSystem;
@@ -112,26 +133,34 @@ describe("DesktopObservability", () => {
),
);
- it.effect("persists backend child output as structured JSON records in development", () =>
+ it.effect("buffers backend child output and persists it only when a failure is reported", () =>
Effect.gen(function* () {
const fileSystem = yield* FileSystem.FileSystem;
const baseDir = yield* fileSystem.makeTempDirectoryScoped({
prefix: "t3-desktop-backend-output-log-test-",
});
- const environmentLayer = makeEnvironmentLayer(baseDir);
+ const environmentLayer = makeEnvironmentLayer(baseDir, false);
const logPath = yield* Effect.gen(function* () {
const environment = yield* DesktopEnvironment.DesktopEnvironment;
return environment.path.join(environment.logDir, "server-child.log");
}).pipe(Effect.provide(environmentLayer));
+ const tracePath = yield* Effect.gen(function* () {
+ const environment = yield* DesktopEnvironment.DesktopEnvironment;
+ return environment.path.join(environment.logDir, "desktop.trace.ndjson");
+ }).pipe(Effect.provide(environmentLayer));
yield* Effect.gen(function* () {
const factory = yield* DesktopObservability.DesktopBackendOutputLogFactory;
const outputLog = yield* factory.forInstance("primary");
- yield* outputLog.writeSessionBoundary({
- phase: "START",
+ yield* outputLog.beginSession({
details: "pid=123 port=3773 cwd=/repo",
});
yield* outputLog.writeOutputChunk("stdout", new TextEncoder().encode("hello server\n"));
+ assert.isFalse(yield* fileSystem.exists(logPath));
+ yield* outputLog.persistFailure({ details: "code=1" });
+ yield* outputLog.beginSession({ details: "pid=456" });
+ yield* outputLog.writeOutputChunk("stderr", new TextEncoder().encode("normal shutdown\n"));
+ yield* outputLog.discardSession;
}).pipe(
Effect.annotateLogs({ runId: "test-run" }),
Effect.provide(DesktopObservability.layer.pipe(Layer.provideMerge(environmentLayer))),
@@ -139,16 +168,18 @@ describe("DesktopObservability", () => {
const log = yield* fileSystem.readFileString(logPath);
const lines = log.trimEnd().split("\n");
- const boundary = yield* decodeDesktopBackendChildLogRecord(lines[0] ?? "");
+ const start = yield* decodeDesktopBackendChildLogRecord(lines[0] ?? "");
const output = yield* decodeDesktopBackendChildLogRecord(lines[1] ?? "");
+ const end = yield* decodeDesktopBackendChildLogRecord(lines[2] ?? "");
- assert.equal(boundary.message, "backend child process session start");
- assert.equal(boundary.level, "INFO");
- assert.equal(boundary.annotations.component, "desktop-backend-child");
- assert.equal(boundary.annotations.runId, "test-run");
- assert.equal(boundary.annotations.instanceId, "primary");
- assert.equal(boundary.annotations.phase, "START");
- assert.equal(boundary.annotations.details, "pid=123 port=3773 cwd=/repo");
+ assert.equal(lines.length, 3);
+ assert.equal(start.message, "backend child process failure output start");
+ assert.equal(start.level, "ERROR");
+ assert.equal(start.annotations.component, "desktop-backend-child");
+ assert.equal(start.annotations.runId, "test-run");
+ assert.equal(start.annotations.instanceId, "primary");
+ assert.equal(start.annotations.phase, "START");
+ assert.equal(start.annotations.details, "pid=123 port=3773 cwd=/repo");
assert.equal(output.message, "backend child process output");
assert.equal(output.level, "INFO");
@@ -157,6 +188,141 @@ describe("DesktopObservability", () => {
assert.equal(output.annotations.instanceId, "primary");
assert.equal(output.annotations.stream, "stdout");
assert.equal(output.annotations.text, "hello server\n");
+
+ assert.equal(end.message, "backend child process failure output end");
+ assert.equal(end.level, "ERROR");
+ assert.equal(end.annotations.instanceId, "primary");
+ assert.equal(end.annotations.phase, "END");
+ assert.equal(end.annotations.details, "code=1");
+
+ const traceRecords = (yield* fileSystem.readFileString(tracePath))
+ .trim()
+ .split("\n")
+ .filter((line) => line.length > 0)
+ .map((line) => decodeTraceRecordLine(line));
+ assert.isFalse(
+ traceRecords.some(
+ (record) => record.name === "desktop.observability.backendOutput.writeOutputChunk",
+ ),
+ );
+ }).pipe(
+ Effect.scoped,
+ Effect.provide(Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerUndici)),
+ ),
+ );
+
+ it.effect("keeps buffering output after a non-terminal failure snapshot", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+ prefix: "t3-desktop-backend-output-snapshot-test-",
+ });
+ const environmentLayer = makeEnvironmentLayer(baseDir, false);
+ const logPath = yield* Effect.gen(function* () {
+ const environment = yield* DesktopEnvironment.DesktopEnvironment;
+ return environment.path.join(environment.logDir, "server-child.log");
+ }).pipe(Effect.provide(environmentLayer));
+
+ yield* Effect.gen(function* () {
+ const factory = yield* DesktopObservability.DesktopBackendOutputLogFactory;
+ const outputLog = yield* factory.forInstance("primary");
+ yield* outputLog.beginSession({ details: "pid=123" });
+ yield* outputLog.writeOutputChunk("stdout", new TextEncoder().encode("before timeout\n"));
+ yield* outputLog.persistFailureSnapshot({ details: "readiness timeout" });
+ yield* outputLog.writeOutputChunk("stderr", new TextEncoder().encode("after timeout\n"));
+ yield* outputLog.persistFailure({ details: "code=1" });
+ }).pipe(
+ Effect.annotateLogs({ runId: "test-run" }),
+ Effect.provide(DesktopObservability.layer.pipe(Layer.provideMerge(environmentLayer))),
+ );
+
+ const records = yield* Effect.forEach(
+ (yield* fileSystem.readFileString(logPath)).trimEnd().split("\n"),
+ (line) => decodeDesktopBackendChildLogRecord(line),
+ );
+ assert.equal(
+ records.some((record) => record.annotations.text === "after timeout\n"),
+ true,
+ );
+ assert.equal(records.at(-1)?.annotations.details, "code=1");
+ }).pipe(
+ Effect.scoped,
+ Effect.provide(Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerUndici)),
+ ),
+ );
+
+ it.effect("retains only the last mebibyte of backend child output", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+ prefix: "t3-desktop-backend-output-bound-test-",
+ });
+ const environmentLayer = makeEnvironmentLayer(baseDir, false);
+ const logPath = yield* Effect.gen(function* () {
+ const environment = yield* DesktopEnvironment.DesktopEnvironment;
+ return environment.path.join(environment.logDir, "server-child.log");
+ }).pipe(Effect.provide(environmentLayer));
+ const maxBufferedBytes = 1024 * 1024;
+ const discardedPrefixBytes = 128;
+ const output = new Uint8Array(maxBufferedBytes + discardedPrefixBytes);
+ output.fill("x".charCodeAt(0));
+ output.fill("y".charCodeAt(0), 0, discardedPrefixBytes);
+
+ yield* Effect.scoped(
+ Effect.gen(function* () {
+ const factory = yield* DesktopObservability.DesktopBackendOutputLogFactory;
+ const outputLog = yield* factory.forInstance("primary");
+ yield* outputLog.beginSession({ details: "pid=123" });
+ yield* outputLog.writeOutputChunk("stderr", output);
+ yield* outputLog.persistFailure({ details: "code=1" });
+ }).pipe(
+ Effect.provide(DesktopObservability.layer.pipe(Layer.provideMerge(environmentLayer))),
+ ),
+ );
+
+ const lines = (yield* fileSystem.readFileString(logPath)).trimEnd().split("\n");
+ const record = yield* decodeDesktopBackendChildLogRecord(lines[1] ?? "");
+ const text = record.annotations.text;
+ assert.equal(typeof text, "string");
+ if (typeof text !== "string") {
+ return;
+ }
+ assert.equal(new TextEncoder().encode(text).byteLength, maxBufferedBytes);
+ assert.isFalse(text.includes("y"));
+ }).pipe(
+ Effect.scoped,
+ Effect.provide(Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerUndici)),
+ ),
+ );
+
+ it.effect("bounds the number of retained backend child output chunks", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+ prefix: "t3-desktop-backend-output-chunks-test-",
+ });
+ const environmentLayer = makeEnvironmentLayer(baseDir, false);
+ const logPath = yield* Effect.gen(function* () {
+ const environment = yield* DesktopEnvironment.DesktopEnvironment;
+ return environment.path.join(environment.logDir, "server-child.log");
+ }).pipe(Effect.provide(environmentLayer));
+
+ yield* Effect.scoped(
+ Effect.gen(function* () {
+ const factory = yield* DesktopObservability.DesktopBackendOutputLogFactory;
+ const outputLog = yield* factory.forInstance("primary");
+ yield* outputLog.beginSession({ details: "pid=123" });
+ for (let index = 0; index < 300; index += 1) {
+ yield* outputLog.writeOutputChunk("stderr", Uint8Array.of(index % 128));
+ }
+ yield* outputLog.persistFailure({ details: "code=1" });
+ }).pipe(
+ Effect.provide(DesktopObservability.layer.pipe(Layer.provideMerge(environmentLayer))),
+ ),
+ );
+
+ const lines = (yield* fileSystem.readFileString(logPath)).trimEnd().split("\n");
+ assert.equal(lines.length, 258);
}).pipe(
Effect.scoped,
Effect.provide(Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerUndici)),
diff --git a/apps/desktop/src/app/DesktopObservability.ts b/apps/desktop/src/app/DesktopObservability.ts
index 868c5aa37..c393f4ccd 100644
--- a/apps/desktop/src/app/DesktopObservability.ts
+++ b/apps/desktop/src/app/DesktopObservability.ts
@@ -24,7 +24,9 @@ import * as DesktopEnvironment from "./DesktopEnvironment.ts";
const DESKTOP_LOG_FILE_MAX_BYTES = 10 * 1024 * 1024;
const DESKTOP_LOG_FILE_MAX_FILES = 10;
const DESKTOP_BACKEND_CHILD_LOG_FIBER_ID = "#backend-child";
-const DESKTOP_TRACE_BATCH_WINDOW_MS = 200;
+const DESKTOP_TRACE_BATCH_WINDOW_MS = 1_000;
+const DESKTOP_BACKEND_OUTPUT_BUFFER_MAX_BYTES = 1024 * 1024;
+const DESKTOP_BACKEND_OUTPUT_BUFFER_MAX_CHUNKS = 256;
export interface RotatingLogFileWriter {
readonly writeBytes: (chunk: Uint8Array) => Effect.Effect<void>;
@@ -32,14 +34,14 @@ export interface RotatingLogFileWriter {
}
export interface DesktopBackendOutputLogShape {
- readonly writeSessionBoundary: (input: {
- readonly phase: "START" | "END";
- readonly details: string;
- }) => Effect.Effect<void>;
+ readonly beginSession: (input: { readonly details: string }) => Effect.Effect<void>;
readonly writeOutputChunk: (
streamName: "stdout" | "stderr",
chunk: Uint8Array,
) => Effect.Effect<void>;
+ readonly persistFailureSnapshot: (input: { readonly details: string }) => Effect.Effect<void>;
+ readonly persistFailure: (input: { readonly details: string }) => Effect.Effect<void>;
+ readonly discardSession: Effect.Effect<void>;
}
// Factory for per-instance backend output logs. `forInstance(id)` returns
@@ -127,10 +129,80 @@ const encodeDesktopBackendChildLogRecord = Schema.encodeEffect(
);
const DesktopBackendOutputLogNoop: DesktopBackendOutputLogShape = {
- writeSessionBoundary: () => Effect.void,
+ beginSession: () => Effect.void,
writeOutputChunk: () => Effect.void,
+ persistFailureSnapshot: () => Effect.void,
+ persistFailure: () => Effect.void,
+ discardSession: Effect.void,
};
+interface BufferedBackendOutputChunk {
+ readonly streamName: "stdout" | "stderr";
+ readonly chunk: Uint8Array;
+ readonly offset: number;
+}
+
+interface BackendOutputSession {
+ readonly runId: string;
+ readonly startDetails: string;
+ readonly chunks: ReadonlyArray<BufferedBackendOutputChunk>;
+ readonly byteLength: number;
+}
+
+export function appendBoundedOutputChunk(
+ session: BackendOutputSession,
+ streamName: "stdout" | "stderr",
+ chunk: Uint8Array,
+): BackendOutputSession {
+ if (chunk.byteLength === 0) {
+ return session;
+ }
+
+ const retainedChunk =
+ chunk.byteLength > DESKTOP_BACKEND_OUTPUT_BUFFER_MAX_BYTES
+ ? chunk.slice(chunk.byteLength - DESKTOP_BACKEND_OUTPUT_BUFFER_MAX_BYTES)
+ : chunk.slice();
+ const chunks = [...session.chunks, { streamName, chunk: retainedChunk, offset: 0 }];
+ let byteLength = session.byteLength + retainedChunk.byteLength;
+ let overflow = Math.max(0, byteLength - DESKTOP_BACKEND_OUTPUT_BUFFER_MAX_BYTES);
+ let firstRetainedIndex = 0;
+
+ while (overflow > 0) {
+ const first = chunks[firstRetainedIndex];
+ if (!first) break;
+ const retainedByteLength = first.chunk.byteLength - first.offset;
+ if (retainedByteLength <= overflow) {
+ overflow -= retainedByteLength;
+ byteLength -= retainedByteLength;
+ firstRetainedIndex += 1;
+ continue;
+ }
+
+ chunks[firstRetainedIndex] = {
+ ...first,
+ offset: first.offset + overflow,
+ };
+ byteLength -= overflow;
+ overflow = 0;
+ }
+
+ const excessChunks = Math.max(
+ 0,
+ chunks.length - firstRetainedIndex - DESKTOP_BACKEND_OUTPUT_BUFFER_MAX_CHUNKS,
+ );
+ for (let index = firstRetainedIndex; index < firstRetainedIndex + excessChunks; index += 1) {
+ const chunk = chunks[index];
+ byteLength -= chunk ? chunk.chunk.byteLength - chunk.offset : 0;
+ }
+ firstRetainedIndex += excessChunks;
+
+ return {
+ ...session,
+ chunks: chunks.slice(firstRetainedIndex),
+ byteLength,
+ };
+}
+
const currentDesktopRunId = Effect.gen(function* () {
const annotations = yield* References.CurrentLogAnnotations;
const runId = annotations.runId;
@@ -345,47 +417,93 @@ const makeBackendOutputLogShape = (
environment: DesktopEnvironment.DesktopEnvironment["Service"],
id: string,
sink: Option.Option<RotatingLogFileWriter>,
-): DesktopBackendOutputLogShape =>
+): Effect.Effect<DesktopBackendOutputLogShape> =>
Option.match(sink, {
- onNone: () => DesktopBackendOutputLogNoop,
+ onNone: () => Effect.succeed(DesktopBackendOutputLogNoop),
onSome: (logFile) =>
- ({
- writeSessionBoundary: Effect.fn("desktop.observability.backendOutput.writeSessionBoundary")(
- function* ({ phase, details }) {
- const runId = yield* currentDesktopRunId;
+ Effect.gen(function* () {
+ const sessionRef = yield* Ref.make(Option.none<BackendOutputSession>());
+ const writeFailure = Effect.fn("desktop.observability.backendOutput.writeFailure")(
+ function* (session: BackendOutputSession, details: string) {
yield* writeBackendChildLogRecord(logFile, {
- message: `backend child process session ${phase.toLowerCase()}`,
- level: "INFO",
+ message: "backend child process failure output start",
+ level: "ERROR",
annotations: {
component: "desktop-backend-child",
- runId,
+ runId: session.runId,
instanceId: id,
- phase,
- details: sanitizeLogValue(details),
+ phase: "START",
+ details: session.startDetails,
},
});
- },
- ),
- writeOutputChunk: Effect.fn("desktop.observability.backendOutput.writeOutputChunk")(
- function* (streamName, chunk) {
- if (environment.isDevelopment) {
- yield* writeDevelopmentConsoleOutput(streamName, chunk);
+ for (const output of session.chunks) {
+ yield* writeBackendChildLogRecord(logFile, {
+ message: "backend child process output",
+ level: output.streamName === "stderr" ? "ERROR" : "INFO",
+ annotations: {
+ component: "desktop-backend-child",
+ runId: session.runId,
+ instanceId: id,
+ stream: output.streamName,
+ text: textDecoder.decode(output.chunk.subarray(output.offset)),
+ },
+ });
}
- const runId = yield* currentDesktopRunId;
yield* writeBackendChildLogRecord(logFile, {
- message: "backend child process output",
- level: streamName === "stderr" ? "ERROR" : "INFO",
+ message: "backend child process failure output end",
+ level: "ERROR",
annotations: {
component: "desktop-backend-child",
- runId,
+ runId: session.runId,
instanceId: id,
- stream: streamName,
- text: textDecoder.decode(chunk),
+ phase: "END",
+ details: sanitizeLogValue(details),
},
});
},
- ),
- }) satisfies DesktopBackendOutputLogShape,
+ );
+ return {
+ beginSession: Effect.fn("desktop.observability.backendOutput.beginSession")(function* ({
+ details,
+ }) {
+ const runId = yield* currentDesktopRunId;
+ yield* Ref.set(
+ sessionRef,
+ Option.some({
+ runId,
+ startDetails: sanitizeLogValue(details),
+ chunks: [],
+ byteLength: 0,
+ }),
+ );
+ }),
+ writeOutputChunk: Effect.fnUntraced(function* (streamName, chunk) {
+ if (environment.isDevelopment) {
+ yield* writeDevelopmentConsoleOutput(streamName, chunk);
+ }
+ yield* Ref.update(
+ sessionRef,
+ Option.map((session) => appendBoundedOutputChunk(session, streamName, chunk)),
+ );
+ }),
+ persistFailureSnapshot: Effect.fn(
+ "desktop.observability.backendOutput.persistFailureSnapshot",
+ )(function* ({ details }) {
+ const session = yield* Ref.get(sessionRef);
+ if (Option.isSome(session)) {
+ yield* writeFailure(session.value, details);
+ }
+ }),
+ persistFailure: Effect.fn("desktop.observability.backendOutput.persistFailure")(
+ function* ({ details }) {
+ const session = yield* Ref.modify(sessionRef, (current) => [current, Option.none()]);
+ if (Option.isNone(session)) return;
+ yield* writeFailure(session.value, details);
+ },
+ ),
+ discardSession: Ref.set(sessionRef, Option.none()),
+ } satisfies DesktopBackendOutputLogShape;
+ }),
});
const backendOutputLogFactoryLayer = Layer.effect(
@@ -412,10 +530,9 @@ const backendOutputLogFactoryLayer = Layer.effect(
const cacheKey = backendLogFilePathForInstance(environment, id);
const cached = cache.get(cacheKey);
if (cached !== undefined) {
- return Effect.succeed([
- makeBackendOutputLogShape(environment, id, cached),
- cache,
- ] as const);
+ return makeBackendOutputLogShape(environment, id, cached).pipe(
+ Effect.map((outputLog) => [outputLog, cache] as const),
+ );
}
return makeBackendOutputSinkForInstance(environment, id).pipe(
Effect.provideService(FileSystem.FileSystem, fileSystem),
@@ -424,11 +541,19 @@ const backendOutputLogFactoryLayer = Layer.effect(
Effect.map((sink) => {
const next = new Map(cache);
next.set(cacheKey, sink);
- return [
- makeBackendOutputLogShape(environment, id, sink),
- next as ReadonlyMap<string, Option.Option<RotatingLogFileWriter>>,
- ] as const;
+ return { sink, next };
}),
+ Effect.flatMap(({ sink, next }) =>
+ makeBackendOutputLogShape(environment, id, sink).pipe(
+ Effect.map(
+ (outputLog) =>
+ [
+ outputLog,
+ next as ReadonlyMap<string, Option.Option<RotatingLogFileWriter>>,
+ ] as const,
+ ),
+ ),
+ ),
);
});
diff --git a/apps/desktop/src/backend/DesktopBackendConfiguration.test.ts b/apps/desktop/src/backend/DesktopBackendConfiguration.test.ts
index 24c90943e..309dbb21d 100644
--- a/apps/desktop/src/backend/DesktopBackendConfiguration.test.ts
+++ b/apps/desktop/src/backend/DesktopBackendConfiguration.test.ts
@@ -52,6 +52,7 @@ function makeEnvironmentLayer(
baseDir: string,
options?: {
readonly appPath?: string;
+ readonly dirname?: string;
readonly isPackaged?: boolean;
readonly devServerUrl?: string;
readonly platform?: NodeJS.Platform;
@@ -59,7 +60,7 @@ function makeEnvironmentLayer(
},
) {
return DesktopEnvironment.layer({
- dirname: "/repo/apps/desktop/src",
+ dirname: options?.dirname ?? "/repo/apps/desktop/src",
homeDirectory: baseDir,
platform: options?.platform ?? "darwin",
processArch: "x64",
@@ -464,6 +465,8 @@ describe("DesktopBackendConfiguration", () => {
// both wslhost-forwarded localhost and the distro's eth0 IP.
assert.equal(config.bootstrap.host, "0.0.0.0");
assert.equal(config.bootstrap.tailscaleServeEnabled, false);
+ assert.notProperty(config.bootstrap, "desktopTelemetryFd");
+ assert.notProperty(config.bootstrap, "resourceMonitorPath");
// httpBaseUrl uses the resolved distro IP from the test stub,
// not localhost — the renderer reaches the backend directly to
// avoid relying on wslhost forwarding.
@@ -713,6 +716,97 @@ describe("DesktopBackendConfiguration", () => {
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
);
+ it.effect("prefers the external packaged resource monitor over the copy inside the asar", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+ prefix: "t3-desktop-backend-config-test-",
+ });
+ const resourcesPath = `${baseDir}/resources`;
+ const dirname = `${resourcesPath}/app.asar/apps/desktop/dist-electron`;
+ const embeddedMonitorPath = `${resourcesPath}/app.asar/apps/desktop/prod-resources/resource-monitor/t3-resource-monitor`;
+ const monitorPath = `${resourcesPath}/resource-monitor/t3-resource-monitor`;
+ yield* fileSystem.makeDirectory(
+ `${resourcesPath}/app.asar/apps/desktop/prod-resources/resource-monitor`,
+ { recursive: true },
+ );
+ yield* fileSystem.makeDirectory(`${resourcesPath}/resource-monitor`, {
+ recursive: true,
+ });
+ yield* fileSystem.writeFileString(embeddedMonitorPath, "embedded");
+ yield* fileSystem.writeFileString(monitorPath, "binary");
+ yield* fileSystem.chmod(monitorPath, 0o755);
+
+ yield* Effect.gen(function* () {
+ const configuration = yield* DesktopBackendConfiguration.DesktopBackendConfiguration;
+ const config = yield* configuration.resolvePrimary;
+ assert.equal(config.bootstrap.resourceMonitorPath, monitorPath);
+ assert.equal(config.bootstrap.desktopTelemetryFd, 4);
+ assert.equal(config.bootstrap.desktopTelemetryControlFd, 5);
+ }).pipe(
+ Effect.provide(
+ DesktopBackendConfiguration.layer.pipe(
+ Layer.provideMerge(serverExposureLayer),
+ Layer.provideMerge(DesktopAppSettings.layerTest()),
+ Layer.provideMerge(DesktopWslEnvironment.layerTest()),
+ Layer.provideMerge(
+ makeEnvironmentLayer(baseDir, {
+ appPath: `${resourcesPath}/app.asar`,
+ dirname,
+ isPackaged: true,
+ resourcesPath,
+ }),
+ ),
+ ),
+ ),
+ );
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+ );
+
+ it.effect("prefers the release resource monitor when both development builds exist", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+ prefix: "t3-desktop-backend-config-test-",
+ });
+ const dirname = path.join(baseDir, "apps/desktop/src");
+ const releaseMonitorPath = path.join(
+ baseDir,
+ "native/resource-monitor/target/release/t3-resource-monitor",
+ );
+ const debugMonitorPath = path.join(
+ baseDir,
+ "native/resource-monitor/target/debug/t3-resource-monitor",
+ );
+ yield* fileSystem.makeDirectory(path.dirname(releaseMonitorPath), { recursive: true });
+ yield* fileSystem.makeDirectory(path.dirname(debugMonitorPath), { recursive: true });
+ yield* fileSystem.writeFileString(releaseMonitorPath, "release");
+ yield* fileSystem.writeFileString(debugMonitorPath, "debug");
+
+ yield* Effect.gen(function* () {
+ const configuration = yield* DesktopBackendConfiguration.DesktopBackendConfiguration;
+ const config = yield* configuration.resolvePrimary;
+ assert.equal(config.bootstrap.resourceMonitorPath, releaseMonitorPath);
+ }).pipe(
+ Effect.provide(
+ DesktopBackendConfiguration.layer.pipe(
+ Layer.provideMerge(serverExposureLayer),
+ Layer.provideMerge(DesktopAppSettings.layerTest()),
+ Layer.provideMerge(DesktopWslEnvironment.layerTest()),
+ Layer.provideMerge(
+ makeEnvironmentLayer(baseDir, {
+ dirname,
+ devServerUrl: "http://127.0.0.1:5733",
+ isPackaged: false,
+ }),
+ ),
+ ),
+ ),
+ );
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+ );
+
it.effect("resolvePrimaryLabel reports the local environment on non-Windows platforms", () =>
withHarness(
Effect.gen(function* () {
diff --git a/apps/desktop/src/backend/DesktopBackendConfiguration.ts b/apps/desktop/src/backend/DesktopBackendConfiguration.ts
index 7ae3ad6c9..bfb9d6900 100644
--- a/apps/desktop/src/backend/DesktopBackendConfiguration.ts
+++ b/apps/desktop/src/backend/DesktopBackendConfiguration.ts
@@ -141,6 +141,44 @@ const logBackendObservabilitySettingsReadFailure = (
);
};
+function resourceMonitorBinaryName(platform: NodeJS.Platform): string {
+ return platform === "win32" ? "t3-resource-monitor.exe" : "t3-resource-monitor";
+}
+
+const resolveResourceMonitorPath = Effect.fn(
+ "desktop.backendConfiguration.resolveResourceMonitorPath",
+)(function* () {
+ const environment = yield* DesktopEnvironment.DesktopEnvironment;
+ const fileSystem = yield* FileSystem.FileSystem;
+ const binaryName = resourceMonitorBinaryName(environment.platform);
+ const candidates = environment.isDevelopment
+ ? [
+ environment.path.join(
+ environment.rootDir,
+ "native/resource-monitor/target/release",
+ binaryName,
+ ),
+ environment.path.join(
+ environment.rootDir,
+ "native/resource-monitor/target/debug",
+ binaryName,
+ ),
+ ]
+ : environment.isPackaged
+ ? [environment.path.join(environment.resourcesPath, "resource-monitor", binaryName)]
+ : environment.resolveResourcePathCandidates(
+ environment.path.join("resource-monitor", binaryName),
+ );
+
+ for (const candidate of candidates) {
+ if (yield* fileSystem.exists(candidate).pipe(Effect.orElseSucceed(() => false))) {
+ return Option.some(candidate);
+ }
+ }
+
+ return Option.none<string>();
+});
+
const readPersistedBackendObservabilitySettings = Effect.gen(function* () {
const fileSystem = yield* FileSystem.FileSystem;
const environment = yield* DesktopEnvironment.DesktopEnvironment;
@@ -326,7 +364,9 @@ const buildObservabilityFragment = (observabilitySettings: BackendObservabilityS
const resolvePrimaryStartConfig = Effect.fn("desktop.backendConfiguration.resolvePrimary")(
function* (
- input: SharedBootstrapInput,
+ input: SharedBootstrapInput & {
+ readonly resourceMonitorPath: Option.Option<string>;
+ },
): Effect.fn.Return<
DesktopBackendManager.DesktopBackendStartConfig,
never,
@@ -345,6 +385,12 @@ const resolvePrimaryStartConfig = Effect.fn("desktop.backendConfiguration.resolv
desktopBootstrapToken: input.bootstrapToken,
tailscaleServeEnabled: backendExposure.tailscaleServeEnabled,
tailscaleServePort: backendExposure.tailscaleServePort,
+ desktopTelemetryFd: 4,
+ desktopTelemetryControlFd: 5,
+ ...Option.match(input.resourceMonitorPath, {
+ onNone: () => ({}),
+ onSome: (resourceMonitorPath) => ({ resourceMonitorPath }),
+ }),
...buildObservabilityFragment(input.observabilitySettings),
};
@@ -411,6 +457,10 @@ const resolveWslStartConfig = Effect.fn("desktop.backendConfiguration.resolveWsl
// inert.
tailscaleServeEnabled: false,
tailscaleServePort: 443,
+ // The packaged sidecar is a Windows executable and cannot run inside the
+ // Linux WSL backend. Keep the field absent instead of passing an unusable
+ // `/mnt/.../*.exe` path; WSL resource telemetry is reported unavailable.
+ // See docs/architecture/resource-telemetry.md.
...buildObservabilityFragment(input.observabilitySettings),
};
@@ -621,7 +671,11 @@ export const make = Effect.gen(function* () {
const buildWindowsPrimaryConfig = Effect.gen(function* () {
const shared = yield* sharedInputs;
- return yield* resolvePrimaryStartConfig(shared).pipe(
+ const resourceMonitorPath = yield* resolveResourceMonitorPath().pipe(
+ Effect.provideService(FileSystem.FileSystem, fileSystem),
+ Effect.provideService(DesktopEnvironment.DesktopEnvironment, environment),
+ );
+ return yield* resolvePrimaryStartConfig({ ...shared, resourceMonitorPath }).pipe(
Effect.provideService(DesktopEnvironment.DesktopEnvironment, environment),
Effect.provideService(DesktopServerExposure.DesktopServerExposure, serverExposure),
);
diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts
index 858c9b0d5..a32caa1fd 100644
--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts
+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts
@@ -1,14 +1,17 @@
import {
DesktopBackendBootstrap,
type DesktopBackendBootstrap as DesktopBackendBootstrapValue,
+ DesktopTelemetryControlMessage,
} from "@t3tools/contracts";
import { assert, describe, it } from "@effect/vitest";
import * as Deferred from "effect/Deferred";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
+import * as Fiber from "effect/Fiber";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
+import * as PlatformError from "effect/PlatformError";
import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import * as Schema from "effect/Schema";
@@ -21,10 +24,15 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
import * as DesktopBackendManager from "./DesktopBackendManager.ts";
import * as DesktopObservability from "../app/DesktopObservability.ts";
+import * as DesktopTelemetryPublisher from "../telemetry/DesktopTelemetryPublisher.ts";
const decodeDesktopBackendBootstrap = Schema.decodeEffect(
Schema.fromJsonString(DesktopBackendBootstrap),
);
+const isBackendProcessError = Schema.is(DesktopBackendManager.BackendProcessError);
+const encodeDesktopTelemetryControl = Schema.encodeSync(
+ Schema.fromJsonString(DesktopTelemetryControlMessage),
+);
const baseConfig: DesktopBackendManager.DesktopBackendStartConfig = {
executablePath: "/electron",
@@ -41,6 +49,8 @@ const baseConfig: DesktopBackendManager.DesktopBackendStartConfig = {
desktopBootstrapToken: "token",
tailscaleServeEnabled: false,
tailscaleServePort: 443,
+ desktopTelemetryFd: 4,
+ desktopTelemetryControlFd: 5,
},
bootstrapDelivery: "fd3",
extendEnv: true,
@@ -52,14 +62,16 @@ const baseConfig: DesktopBackendManager.DesktopBackendStartConfig = {
const configWithObservability: DesktopBackendBootstrapValue = {
...baseConfig.bootstrap,
tailscaleServeEnabled: true,
+ desktopTelemetryFd: 4,
otlpTracesUrl: "http://127.0.0.1:4318/v1/traces",
};
function makeProcess(options?: {
- readonly stdout?: Stream.Stream<Uint8Array>;
- readonly stderr?: Stream.Stream<Uint8Array>;
- readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode>;
+ readonly stdout?: Stream.Stream<Uint8Array, PlatformError.PlatformError>;
+ readonly stderr?: Stream.Stream<Uint8Array, PlatformError.PlatformError>;
+ readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode, PlatformError.PlatformError>;
readonly kill?: ChildProcessSpawner.ChildProcessHandle["kill"];
+ readonly getOutputFd?: ChildProcessSpawner.ChildProcessHandle["getOutputFd"];
}): ChildProcessSpawner.ChildProcessHandle {
return ChildProcessSpawner.makeHandle({
pid: ChildProcessSpawner.ProcessId(123),
@@ -71,7 +83,7 @@ function makeProcess(options?: {
kill: options?.kill ?? (() => Effect.void),
stdin: Sink.drain,
getInputFd: () => Sink.drain,
- getOutputFd: () => Stream.empty,
+ getOutputFd: options?.getOutputFd ?? (() => Stream.empty),
unref: Effect.succeed(Effect.void),
});
}
@@ -112,7 +124,14 @@ interface MakeInstanceInput {
failure: DesktopBackendManager.PreflightFailure,
) => Effect.Effect<boolean>;
readonly config?: DesktopBackendManager.DesktopBackendStartConfig;
- readonly configResolve?: Effect.Effect<DesktopBackendManager.DesktopBackendStartConfig>;
+ readonly configResolve?: Effect.Effect<
+ DesktopBackendManager.DesktopBackendStartConfig,
+ PlatformError.PlatformError
+ >;
+ readonly desktopTelemetryStream?: Stream.Stream<Uint8Array>;
+ readonly desktopTelemetryPublisher?: Partial<
+ DesktopTelemetryPublisher.DesktopTelemetryPublisher["Service"]
+ >;
}
// Helper that constructs a primary backend instance using the factory
@@ -122,8 +141,11 @@ interface MakeInstanceInput {
// to drive the instance's lifecycle.
function makeTestInstance(input: MakeInstanceInput) {
const stubLog: DesktopObservability.DesktopBackendOutputLogShape = {
- writeSessionBoundary: () => Effect.void,
+ beginSession: () => Effect.void,
writeOutputChunk: () => Effect.void,
+ persistFailureSnapshot: () => Effect.void,
+ persistFailure: () => Effect.void,
+ discardSession: Effect.void,
...input.backendOutputLog,
};
const servicesLayer = Layer.mergeAll(
@@ -135,6 +157,16 @@ function makeTestInstance(input: MakeInstanceInput) {
Layer.succeed(DesktopObservability.DesktopBackendOutputLogFactory, {
forInstance: () => Effect.succeed(stubLog),
} satisfies DesktopObservability.DesktopBackendOutputLogFactory["Service"]),
+ Layer.succeed(DesktopTelemetryPublisher.DesktopTelemetryPublisher, {
+ latest: Effect.succeed(Option.none()),
+ changes: Stream.empty,
+ encoded: input.desktopTelemetryStream ?? Stream.empty,
+ handleControl: () => Effect.void,
+ handleControlForSource: (_sourceId, message) =>
+ (input.desktopTelemetryPublisher?.handleControl ?? (() => Effect.void))(message),
+ removeControlSource: () => Effect.void,
+ ...input.desktopTelemetryPublisher,
+ }),
);
const instance = DesktopBackendManager.makeBackendInstance({
@@ -150,11 +182,12 @@ function makeTestInstance(input: MakeInstanceInput) {
}
describe("DesktopBackendManager", () => {
- it.effect("spawns the backend with fd3 bootstrap JSON and reports HTTP readiness", () =>
+ it.effect("spawns the backend with fd3 bootstrap and fd4 telemetry", () =>
Effect.scoped(
Effect.gen(function* () {
let spawnedCommand: ChildProcess.Command | undefined;
let bootstrapJson = "";
+ let telemetryJson = "";
let readyCount = 0;
const ready = yield* Deferred.make<void>();
const exited = yield* Queue.unbounded<void>();
@@ -169,6 +202,10 @@ describe("DesktopBackendManager", () => {
if (fd3?.type === "input" && fd3.stream) {
bootstrapJson = yield* fd3.stream.pipe(Stream.decodeText(), Stream.mkString);
}
+ const fd4 = command.options.additionalFds?.fd4;
+ if (fd4?.type === "input" && fd4.stream) {
+ telemetryJson = yield* fd4.stream.pipe(Stream.decodeText(), Stream.mkString);
+ }
}
return makeProcess({
@@ -184,12 +221,14 @@ describe("DesktopBackendManager", () => {
bootstrap: configWithObservability,
},
spawnerLayer,
+ desktopTelemetryStream: Stream.encodeText(
+ Stream.make('{"version":1,"type":"desktopTelemetryHello","electronPid":123}\n'),
+ ),
onReady: Effect.sync(() => {
readyCount += 1;
}).pipe(Effect.andThen(Deferred.succeed(ready, void 0)), Effect.asVoid),
backendOutputLog: {
- writeSessionBoundary: ({ phase }) =>
- phase === "END" ? Queue.offer(exited, void 0).pipe(Effect.asVoid) : Effect.void,
+ persistFailure: () => Queue.offer(exited, void 0).pipe(Effect.asVoid),
},
});
@@ -210,16 +249,400 @@ describe("DesktopBackendManager", () => {
assert.equal(spawnedCommand.options.stderr, "pipe");
assert.equal(spawnedCommand.options.killSignal, "SIGTERM");
assert.isDefined(spawnedCommand.options.forceKillAfter);
+ assert.equal(spawnedCommand.options.additionalFds?.fd4?.type, "input");
+ assert.equal(spawnedCommand.options.additionalFds?.fd5?.type, "output");
assert.equal(
Duration.toMillis(Duration.fromInputUnsafe(spawnedCommand.options.forceKillAfter)),
2_000,
);
assert.deepEqual(yield* decodeBootstrap(bootstrapJson), configWithObservability);
+ assert.equal(
+ telemetryJson,
+ '{"version":1,"type":"desktopTelemetryHello","electronPid":123}\n',
+ );
+ }),
+ ),
+ );
+
+ it.effect("preserves the readiness timeout cause and process context", () =>
+ Effect.gen(function* () {
+ const requested = yield* Deferred.make<HttpClientRequest.HttpClientRequest>();
+ const layer = Layer.merge(
+ TestClock.layer(),
+ httpClientLayer((request) =>
+ Deferred.succeed(requested, request).pipe(Effect.andThen(Effect.never)),
+ ),
+ );
+
+ yield* Effect.gen(function* () {
+ const readiness = yield* DesktopBackendManager.waitForHttpReady({
+ executablePath: baseConfig.executablePath,
+ entryPath: baseConfig.entryPath,
+ cwd: baseConfig.cwd,
+ httpBaseUrl: baseConfig.httpBaseUrl,
+ timeout: Duration.millis(50),
+ }).pipe(Effect.flip, Effect.forkChild);
+
+ const request = yield* Deferred.await(requested);
+ assert.equal(request.url, "http://127.0.0.1:3773/.well-known/t3/environment");
+
+ yield* TestClock.adjust(Duration.millis(50));
+ const error = yield* Fiber.join(readiness);
+
+ assert.instanceOf(error, DesktopBackendManager.BackendReadinessTimeoutError);
+ assert.equal(error.executablePath, "/electron");
+ assert.equal(error.entryPath, "/server/bin.mjs");
+ assert.equal(error.cwd, "/server");
+ assert.equal(error.httpBaseUrl.href, "http://127.0.0.1:3773/");
+ assert.equal(error.readinessUrl.href, "http://127.0.0.1:3773/.well-known/t3/environment");
+ assert.equal(error.timeoutMs, 50);
+ assert.isDefined(error.cause);
+ assert.equal(
+ error.message,
+ "Timed out after 50ms waiting for desktop backend readiness at http://127.0.0.1:3773/.well-known/t3/environment.",
+ );
+ }).pipe(Effect.provide(layer));
+ }),
+ );
+
+ it.effect("reports bootstrap encoding failures with stable process context", () =>
+ Effect.gen(function* () {
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() => Effect.die("unexpected backend spawn")),
+ );
+ const error = yield* DesktopBackendManager.runBackendProcess({
+ ...baseConfig,
+ desktopTelemetryStream: Stream.empty,
+ bootstrap: {
+ ...baseConfig.bootstrap,
+ port: 0,
+ },
+ }).pipe(
+ Effect.flip,
+ Effect.scoped,
+ Effect.provide(Layer.merge(spawnerLayer, healthyHttpClientLayer)),
+ );
+
+ if (error._tag !== "BackendProcessBootstrapEncodeError") {
+ return assert.fail(`Expected bootstrap encode error, received ${error._tag}`);
+ }
+ assert.equal(error.executablePath, "/electron");
+ assert.equal(error.entryPath, "/server/bin.mjs");
+ assert.equal(error.cwd, "/server");
+ assert.equal(error.httpBaseUrl.href, "http://127.0.0.1:3773/");
+ assert.isDefined(error.cause);
+ assert.equal(
+ error.message,
+ "Failed to encode the desktop backend bootstrap payload for /server/bin.mjs.",
+ );
+ assert.isTrue(isBackendProcessError(error));
+ }),
+ );
+
+ it.effect("preserves spawn failures without deriving their message from the cause", () =>
+ Effect.gen(function* () {
+ const spawnCause = PlatformError.systemError({
+ _tag: "PermissionDenied",
+ module: "ChildProcessSpawner",
+ method: "spawn",
+ pathOrDescriptor: baseConfig.executablePath,
+ description: "low-level detail that must not become the public message",
+ });
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() => Effect.fail(spawnCause)),
+ );
+ const error = yield* DesktopBackendManager.runBackendProcess({
+ ...baseConfig,
+ desktopTelemetryStream: Stream.empty,
+ }).pipe(
+ Effect.flip,
+ Effect.scoped,
+ Effect.provide(Layer.merge(spawnerLayer, healthyHttpClientLayer)),
+ );
+
+ if (error._tag !== "BackendProcessSpawnError") {
+ return assert.fail(`Expected backend spawn error, received ${error._tag}`);
+ }
+ assert.equal(error.executablePath, "/electron");
+ assert.equal(error.entryPath, "/server/bin.mjs");
+ assert.equal(error.cwd, "/server");
+ assert.equal(error.httpBaseUrl.href, "http://127.0.0.1:3773/");
+ assert.strictEqual(error.cause, spawnCause);
+ assert.equal(
+ error.message,
+ "Failed to spawn desktop backend entry /server/bin.mjs with /electron.",
+ );
+ assert.notInclude(error.message, spawnCause.message);
+ assert.isTrue(isBackendProcessError(error));
+ }),
+ );
+
+ it.effect("preserves exit-status failures without copying their detail into the message", () =>
+ Effect.gen(function* () {
+ const exitCause = PlatformError.systemError({
+ _tag: "PermissionDenied",
+ module: "ChildProcess",
+ method: "exitCode",
+ description: "exit-status-secret-sentinel",
+ });
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() =>
+ Effect.succeed(
+ makeProcess({
+ exitCode: Effect.fail(exitCause),
+ }),
+ ),
+ ),
+ );
+ const error = yield* DesktopBackendManager.runBackendProcess({
+ ...baseConfig,
+ desktopTelemetryStream: Stream.empty,
+ }).pipe(
+ Effect.flip,
+ Effect.scoped,
+ Effect.provide(Layer.merge(spawnerLayer, healthyHttpClientLayer)),
+ );
+
+ if (error._tag !== "BackendProcessExitStatusError") {
+ return assert.fail(`Expected backend exit-status error, received ${error._tag}`);
+ }
+ assert.equal(error.pid, 123);
+ assert.equal(error.executablePath, "/electron");
+ assert.equal(error.entryPath, "/server/bin.mjs");
+ assert.equal(error.cwd, "/server");
+ assert.equal(error.httpBaseUrl.href, "http://127.0.0.1:3773/");
+ assert.strictEqual(error.cause, exitCause);
+ assert.equal(error.message, "Failed to read the exit status of desktop backend process 123.");
+ assert.notInclude(error.message, "exit-status-secret-sentinel");
+ assert.isTrue(isBackendProcessError(error));
+ }),
+ );
+
+ it.effect("reports output stream failures with process and stream context", () =>
+ Effect.gen(function* () {
+ const outputCause = PlatformError.systemError({
+ _tag: "BadResource",
+ module: "ChildProcess",
+ method: "stdout",
+ description: "output-stream-secret-sentinel",
+ });
+ const reported = yield* Deferred.make<DesktopBackendManager.BackendProcessOutputError>();
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() =>
+ Effect.succeed(
+ makeProcess({
+ stdout: Stream.fail(outputCause),
+ exitCode: Deferred.await(reported).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
+ }),
+ ),
+ ),
+ );
+
+ const exit = yield* DesktopBackendManager.runBackendProcess({
+ ...baseConfig,
+ desktopTelemetryStream: Stream.empty,
+ onOutputFailure: (error) => Deferred.succeed(reported, error).pipe(Effect.asVoid),
+ }).pipe(Effect.scoped, Effect.provide(Layer.merge(spawnerLayer, healthyHttpClientLayer)));
+ const error = yield* Deferred.await(reported);
+
+ assert.equal(exit.code.pipe(Option.getOrUndefined), 0);
+ if (error._tag !== "BackendProcessOutputReadError") {
+ return assert.fail(`Expected output read error, received ${error._tag}`);
+ }
+ assert.equal(error.executablePath, "/electron");
+ assert.equal(error.entryPath, "/server/bin.mjs");
+ assert.equal(error.cwd, "/server");
+ assert.equal(error.httpBaseUrl.href, "http://127.0.0.1:3773/");
+ assert.equal(error.pid, 123);
+ assert.equal(error.streamName, "stdout");
+ assert.strictEqual(error.cause, outputCause);
+ assert.equal(error.message, "Failed to read stdout from desktop backend process 123.");
+ assert.notInclude(error.message, "output-stream-secret-sentinel");
+ }),
+ );
+
+ it.effect("reports output handler failures separately from stream read failures", () =>
+ Effect.gen(function* () {
+ const chunk = new TextEncoder().encode("backend output");
+ const nextChunk = new TextEncoder().encode("still draining");
+ const outputCause = new Error("output-handler-secret-sentinel");
+ const reported = yield* Deferred.make<DesktopBackendManager.BackendProcessOutputError>();
+ const drained = yield* Deferred.make<void>();
+ let outputCount = 0;
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() =>
+ Effect.succeed(
+ makeProcess({
+ stdout: Stream.make(chunk, nextChunk),
+ exitCode: Deferred.await(drained).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
+ }),
+ ),
+ ),
+ );
+
+ const exit = yield* DesktopBackendManager.runBackendProcess({
+ ...baseConfig,
+ desktopTelemetryStream: Stream.empty,
+ onOutput: () => {
+ outputCount += 1;
+ return outputCount === 1
+ ? Effect.fail(outputCause)
+ : Deferred.succeed(drained, void 0).pipe(Effect.asVoid);
+ },
+ onOutputFailure: (error) => Deferred.succeed(reported, error).pipe(Effect.asVoid),
+ }).pipe(Effect.scoped, Effect.provide(Layer.merge(spawnerLayer, healthyHttpClientLayer)));
+ const error = yield* Deferred.await(reported);
+
+ assert.equal(exit.code.pipe(Option.getOrUndefined), 0);
+ if (error._tag !== "BackendProcessOutputHandlingError") {
+ return assert.fail(`Expected output handling error, received ${error._tag}`);
+ }
+ assert.equal(error.executablePath, "/electron");
+ assert.equal(error.entryPath, "/server/bin.mjs");
+ assert.equal(error.cwd, "/server");
+ assert.equal(error.httpBaseUrl.href, "http://127.0.0.1:3773/");
+ assert.equal(error.pid, 123);
+ assert.equal(error.streamName, "stdout");
+ assert.equal(error.chunkByteLength, chunk.byteLength);
+ assert.strictEqual(error.cause, outputCause);
+ assert.equal(
+ error.message,
+ `Failed to handle ${chunk.byteLength} bytes from stdout of desktop backend process 123.`,
+ );
+ assert.notInclude(error.message, "output-handler-secret-sentinel");
+ assert.equal(outputCount, 2);
+ }),
+ );
+
+ it.effect("reports child exit before waiting for trailing output to drain", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const exitObserved = yield* Deferred.make<void>();
+ const finishOutputDrain = yield* Deferred.make<void>();
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() =>
+ Effect.succeed(
+ makeProcess({
+ stdout: Stream.fromEffect(
+ Deferred.await(finishOutputDrain).pipe(
+ Effect.as(new TextEncoder().encode("trailing output\n")),
+ ),
+ ),
+ exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(1)),
+ }),
+ ),
+ ),
+ );
+
+ const runFiber = yield* DesktopBackendManager.runBackendProcess({
+ ...baseConfig,
+ desktopTelemetryStream: Stream.empty,
+ onExitObserved: () => Deferred.succeed(exitObserved, void 0).pipe(Effect.asVoid),
+ }).pipe(
+ Effect.provide(Layer.merge(spawnerLayer, healthyHttpClientLayer)),
+ Effect.forkChild,
+ );
+
+ yield* Deferred.await(exitObserved);
+ assert.isUndefined(runFiber.pollUnsafe());
+
+ yield* Deferred.succeed(finishOutputDrain, void 0);
+ assert.equal((yield* Fiber.join(runFiber)).code.pipe(Option.getOrUndefined), 1);
+ }),
+ ),
+ );
+
+ it.effect("continues routing desktop telemetry control messages after an invalid line", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const handled = yield* Deferred.make<boolean>();
+ const controlMessage = encodeDesktopTelemetryControl({
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled: true,
+ });
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() =>
+ Effect.succeed(
+ makeProcess({
+ getOutputFd: (fd) =>
+ fd === 5
+ ? Stream.encodeText(Stream.make(`not-json\n${controlMessage}\n`))
+ : Stream.empty,
+ exitCode: Deferred.await(handled).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
+ }),
+ ),
+ ),
+ );
+ const instance = yield* makeTestInstance({
+ spawnerLayer,
+ desktopTelemetryPublisher: {
+ handleControl: (message) =>
+ message.type === "setDiagnosticsDemand"
+ ? Deferred.succeed(handled, message.enabled).pipe(Effect.asVoid)
+ : Effect.void,
+ },
+ });
+
+ yield* instance.start;
+ assert.isTrue(yield* Deferred.await(handled));
}),
),
);
+ it.effect("drains trailing child output before persisting an unexpected exit", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const persistedOutput = yield* Deferred.make<ReadonlyArray<string>>();
+ const outputDrainStarted = yield* Deferred.make<void>();
+ const outputChunks = yield* Ref.make<Array<string>>([]);
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() =>
+ Effect.succeed(
+ makeProcess({
+ stdout: Stream.fromEffect(
+ Deferred.succeed(outputDrainStarted, void 0).pipe(
+ Effect.andThen(Effect.sleep(Duration.seconds(1))),
+ Effect.as(new TextEncoder().encode("trailing output\n")),
+ ),
+ ),
+ exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(1)),
+ }),
+ ),
+ ),
+ );
+ const instance = yield* makeTestInstance({
+ spawnerLayer,
+ httpClientLayer: httpClientLayer(() => Effect.never),
+ backendOutputLog: {
+ writeOutputChunk: (_streamName, chunk) =>
+ Ref.update(outputChunks, (current) => [...current, new TextDecoder().decode(chunk)]),
+ persistFailure: () =>
+ Ref.get(outputChunks).pipe(
+ Effect.flatMap((chunks) => Deferred.succeed(persistedOutput, chunks)),
+ Effect.asVoid,
+ ),
+ },
+ });
+
+ yield* instance.start;
+ yield* Deferred.await(outputDrainStarted);
+ yield* TestClock.adjust(Duration.seconds(1));
+
+ assert.deepEqual(yield* Deferred.await(persistedOutput), ["trailing output\n"]);
+ }).pipe(Effect.provide(TestClock.layer())),
+ ),
+ );
+
it.effect("retries HTTP readiness before reporting the backend ready", () =>
Effect.scoped(
Effect.gen(function* () {
@@ -256,8 +679,7 @@ describe("DesktopBackendManager", () => {
readyCount += 1;
}).pipe(Effect.andThen(Deferred.succeed(ready, void 0)), Effect.asVoid),
backendOutputLog: {
- writeSessionBoundary: ({ phase }) =>
- phase === "END" ? Queue.offer(exited, void 0).pipe(Effect.asVoid) : Effect.void,
+ persistFailure: () => Queue.offer(exited, void 0).pipe(Effect.asVoid),
},
});
@@ -285,9 +707,15 @@ describe("DesktopBackendManager", () => {
let startCount = 0;
let closedCount = 0;
const closed = yield* Deferred.make<void>();
+ const teardownStarted = yield* Deferred.make<void>();
+ const finishTeardown = yield* Deferred.make<void>();
const startedPids = yield* Queue.unbounded<number>();
const ready = yield* Deferred.make<void>();
const backendReadyFlag = yield* Ref.make(false);
+ let shutdownCount = 0;
+ let persistedFailureCount = 0;
+ let discardedSessionCount = 0;
+ let removedTelemetrySources = 0;
const spawnerLayer = Layer.succeed(
ChildProcessSpawner.ChildProcessSpawner,
@@ -296,9 +724,16 @@ describe("DesktopBackendManager", () => {
const scope = yield* Scope.Scope;
startCount += 1;
yield* Queue.offer(startedPids, 123);
- const close = Effect.sync(() => {
- closedCount += 1;
- }).pipe(Effect.andThen(Deferred.succeed(closed, void 0)), Effect.asVoid);
+ const close = Deferred.succeed(teardownStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(finishTeardown)),
+ Effect.andThen(
+ Effect.sync(() => {
+ closedCount += 1;
+ }),
+ ),
+ Effect.andThen(Deferred.succeed(closed, void 0)),
+ Effect.asVoid,
+ );
yield* Scope.addFinalizer(scope, close);
@@ -316,7 +751,28 @@ describe("DesktopBackendManager", () => {
Effect.andThen(Deferred.succeed(ready, void 0)),
Effect.asVoid,
),
- onShutdown: Ref.set(backendReadyFlag, false),
+ onShutdown: Ref.set(backendReadyFlag, false).pipe(
+ Effect.andThen(
+ Effect.sync(() => {
+ shutdownCount += 1;
+ }),
+ ),
+ ),
+ backendOutputLog: {
+ persistFailure: () =>
+ Effect.sync(() => {
+ persistedFailureCount += 1;
+ }),
+ discardSession: Effect.sync(() => {
+ discardedSessionCount += 1;
+ }),
+ },
+ desktopTelemetryPublisher: {
+ removeControlSource: () =>
+ Effect.sync(() => {
+ removedTelemetrySources += 1;
+ }),
+ },
});
assert.isTrue(Option.isNone(yield* instance.currentConfig));
@@ -330,12 +786,21 @@ describe("DesktopBackendManager", () => {
assert.equal(runningSnapshot.ready, true);
assert.deepEqual(runningSnapshot.activePid, Option.some(123));
- yield* instance.stop();
+ const stopFiber = yield* instance.stop().pipe(Effect.forkChild);
+ yield* Deferred.await(teardownStarted).pipe(Effect.timeout("1 second"));
+ assert.isFalse(yield* Ref.get(backendReadyFlag));
+ assert.equal(shutdownCount, 1);
+ yield* Deferred.succeed(finishTeardown, undefined);
+ yield* Fiber.join(stopFiber).pipe(Effect.timeout("1 second"));
assert.equal(startCount, 1);
assert.equal(closedCount, 1);
+ assert.equal(persistedFailureCount, 0);
+ assert.equal(discardedSessionCount, 1);
+ assert.equal(removedTelemetrySources, 1);
const stoppedSnapshot = yield* instance.snapshot;
assert.isFalse(yield* Ref.get(backendReadyFlag));
+ assert.equal(shutdownCount, 1);
assert.equal(stoppedSnapshot.desiredRunning, false);
assert.equal(stoppedSnapshot.ready, false);
assert.equal(Option.isNone(stoppedSnapshot.activePid), true);
@@ -343,6 +808,213 @@ describe("DesktopBackendManager", () => {
),
);
+ it.effect("restarts when start is requested during stop teardown", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const starts = yield* Queue.unbounded<number>();
+ const teardownStarted = yield* Deferred.make<void>();
+ const finishTeardown = yield* Deferred.make<void>();
+ let startCount = 0;
+
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() =>
+ Effect.gen(function* () {
+ const scope = yield* Scope.Scope;
+ const closed = yield* Deferred.make<void>();
+ startCount += 1;
+ yield* Queue.offer(starts, startCount);
+ if (startCount === 1) {
+ yield* Scope.addFinalizer(
+ scope,
+ Deferred.succeed(teardownStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(finishTeardown)),
+ Effect.andThen(Deferred.succeed(closed, undefined)),
+ Effect.asVoid,
+ ),
+ );
+ } else {
+ yield* Scope.addFinalizer(
+ scope,
+ Deferred.succeed(closed, undefined).pipe(Effect.asVoid),
+ );
+ }
+ return makeProcess({
+ exitCode: Deferred.await(closed).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
+ });
+ }),
+ ),
+ );
+
+ const instance = yield* makeTestInstance({
+ spawnerLayer,
+ httpClientLayer: httpClientLayer(() => Effect.never),
+ });
+
+ yield* instance.start;
+ assert.equal(yield* Queue.take(starts), 1);
+
+ const stopFiber = yield* instance.stop().pipe(Effect.forkChild);
+ yield* Deferred.await(teardownStarted).pipe(Effect.timeout("1 second"));
+ yield* instance.start;
+ assert.equal((yield* instance.snapshot).desiredRunning, true);
+
+ yield* Deferred.succeed(finishTeardown, undefined);
+ yield* Fiber.join(stopFiber).pipe(Effect.timeout("1 second"));
+ yield* TestClock.adjust(Duration.millis(500));
+
+ assert.equal(yield* Queue.take(starts).pipe(Effect.timeout("1 second")), 2);
+ const restarted = yield* instance.snapshot;
+ assert.equal(restarted.desiredRunning, true);
+ assert.deepEqual(restarted.activePid, Option.some(123));
+ }).pipe(Effect.provide(TestClock.layer())),
+ ),
+ );
+
+ it.effect("retries config resolution after a start request during stop teardown", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const starts = yield* Queue.unbounded<number>();
+ const teardownStarted = yield* Deferred.make<void>();
+ const finishTeardown = yield* Deferred.make<void>();
+ const configAttempts = yield* Ref.make(0);
+ let startCount = 0;
+
+ const configFailure = PlatformError.systemError({
+ _tag: "Unknown",
+ module: "DesktopBackendManager",
+ method: "configResolve",
+ description: "transient configuration failure",
+ });
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() =>
+ Effect.gen(function* () {
+ const scope = yield* Scope.Scope;
+ const closed = yield* Deferred.make<void>();
+ startCount += 1;
+ yield* Queue.offer(starts, startCount);
+ if (startCount === 1) {
+ yield* Scope.addFinalizer(
+ scope,
+ Deferred.succeed(teardownStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(finishTeardown)),
+ Effect.andThen(Deferred.succeed(closed, undefined)),
+ Effect.asVoid,
+ ),
+ );
+ } else {
+ yield* Scope.addFinalizer(
+ scope,
+ Deferred.succeed(closed, undefined).pipe(Effect.asVoid),
+ );
+ }
+ return makeProcess({
+ exitCode: Deferred.await(closed).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
+ });
+ }),
+ ),
+ );
+ const configResolve = Ref.updateAndGet(configAttempts, (attempt) => attempt + 1).pipe(
+ Effect.flatMap((attempt) =>
+ attempt === 2 ? Effect.fail(configFailure) : Effect.succeed(baseConfig),
+ ),
+ );
+ const instance = yield* makeTestInstance({
+ spawnerLayer,
+ configResolve,
+ httpClientLayer: httpClientLayer(() => Effect.never),
+ });
+
+ yield* instance.start;
+ assert.equal(yield* Queue.take(starts), 1);
+
+ const stopFiber = yield* instance.stop().pipe(Effect.forkChild);
+ yield* Deferred.await(teardownStarted).pipe(Effect.timeout("1 second"));
+ yield* instance.start;
+ yield* Deferred.succeed(finishTeardown, undefined);
+ yield* Fiber.join(stopFiber).pipe(Effect.timeout("1 second"));
+
+ const pendingRestart = yield* instance.snapshot;
+ assert.equal(pendingRestart.desiredRunning, true);
+ assert.equal(pendingRestart.restartScheduled, true);
+
+ yield* TestClock.adjust(Duration.seconds(2));
+
+ assert.equal(yield* Queue.take(starts).pipe(Effect.timeout("1 second")), 2);
+ assert.equal(yield* Ref.get(configAttempts), 3);
+ assert.equal((yield* instance.snapshot).desiredRunning, true);
+ }).pipe(Effect.provide(TestClock.layer())),
+ ),
+ );
+
+ it.effect("keeps a timed-out run active until its process exits", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const starts = yield* Queue.unbounded<number>();
+ const teardownStarted = yield* Deferred.make<void>();
+ const finishTeardown = yield* Deferred.make<void>();
+ let startCount = 0;
+
+ const spawnerLayer = Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make(() =>
+ Effect.gen(function* () {
+ const scope = yield* Scope.Scope;
+ const closed = yield* Deferred.make<void>();
+ startCount += 1;
+ yield* Queue.offer(starts, startCount);
+ if (startCount === 1) {
+ yield* Scope.addFinalizer(
+ scope,
+ Deferred.succeed(teardownStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(finishTeardown)),
+ Effect.andThen(Deferred.succeed(closed, undefined)),
+ Effect.asVoid,
+ ),
+ );
+ } else {
+ yield* Scope.addFinalizer(
+ scope,
+ Deferred.succeed(closed, undefined).pipe(Effect.asVoid),
+ );
+ }
+ return makeProcess({
+ exitCode: Deferred.await(closed).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
+ });
+ }),
+ ),
+ );
+
+ const instance = yield* makeTestInstance({
+ spawnerLayer,
+ httpClientLayer: httpClientLayer(() => Effect.never),
+ });
+
+ yield* instance.start;
+ assert.equal(yield* Queue.take(starts), 1);
+
+ const stopFiber = yield* instance
+ .stop({ timeout: Duration.millis(100) })
+ .pipe(Effect.forkChild);
+ yield* Deferred.await(teardownStarted).pipe(Effect.timeout("1 second"));
+ yield* instance.start;
+ yield* TestClock.adjust(Duration.millis(100));
+ yield* Fiber.join(stopFiber).pipe(Effect.timeout("1 second"));
+
+ assert.equal(startCount, 1);
+ const timedOut = yield* instance.snapshot;
+ assert.equal(timedOut.desiredRunning, true);
+ assert.deepEqual(timedOut.activePid, Option.some(123));
+
+ yield* Deferred.succeed(finishTeardown, undefined);
+ yield* TestClock.adjust(Duration.millis(500));
+
+ assert.equal(yield* Queue.take(starts).pipe(Effect.timeout("1 second")), 2);
+ }).pipe(Effect.provide(TestClock.layer())),
+ ),
+ );
+
it.effect("does not notify shutdown before the first start has prior state", () =>
Effect.scoped(
Effect.gen(function* () {
@@ -383,6 +1055,7 @@ describe("DesktopBackendManager", () => {
Effect.scoped(
Effect.gen(function* () {
const starts = yield* Queue.unbounded<number>();
+ const failures = yield* Queue.unbounded<string>();
let startCount = 0;
const spawnerLayer = Layer.succeed(
@@ -402,11 +1075,15 @@ describe("DesktopBackendManager", () => {
const instance = yield* makeTestInstance({
spawnerLayer,
httpClientLayer: httpClientLayer(() => Effect.never),
+ backendOutputLog: {
+ persistFailure: ({ details }) => Queue.offer(failures, details).pipe(Effect.asVoid),
+ },
});
yield* instance.start;
assert.equal(yield* Queue.take(starts), 1);
+ assert.equal(yield* Queue.take(failures), "pid=123 code=1");
yield* TestClock.adjust(Duration.millis(499));
assert.equal(yield* Queue.size(starts), 0);
@@ -657,6 +1334,13 @@ describe("DesktopBackendManager", () => {
yield* instance.start;
assert.equal(yield* Queue.take(starts), 1);
+ let restartScheduled = false;
+ while (!restartScheduled) {
+ restartScheduled = (yield* instance.snapshot).restartScheduled;
+ if (!restartScheduled) {
+ yield* Effect.yieldNow;
+ }
+ }
yield* instance.start;
assert.equal(yield* Queue.take(starts), 2);
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts
index e3a4de661..b50c7a55e 100644
--- a/apps/desktop/src/backend/DesktopBackendManager.ts
+++ b/apps/desktop/src/backend/DesktopBackendManager.ts
@@ -33,7 +33,6 @@ import * as FileSystem from "effect/FileSystem";
import * as Option from "effect/Option";
import * as PlatformError from "effect/PlatformError";
import * as Ref from "effect/Ref";
-import * as Result from "effect/Result";
import * as Schedule from "effect/Schedule";
import * as Schema from "effect/Schema";
import * as Semaphore from "effect/Semaphore";
@@ -46,10 +45,13 @@ import {
DesktopBackendBootstrap,
type DesktopBackendBootstrap as DesktopBackendBootstrapValue,
PRIMARY_LOCAL_ENVIRONMENT_ID,
+ DesktopTelemetryControlMessage,
+ type DesktopTelemetryControlMessage as DesktopTelemetryControlMessageValue,
} from "@t3tools/contracts";
import { waitForHttpReady as waitForHttpReadyShared } from "@t3tools/shared/httpReadiness";
import * as DesktopObservability from "../app/DesktopObservability.ts";
+import * as DesktopTelemetryPublisher from "../telemetry/DesktopTelemetryPublisher.ts";
const INITIAL_RESTART_DELAY = Duration.millis(500);
const MAX_RESTART_DELAY = Duration.seconds(10);
@@ -62,7 +64,10 @@ const DEFAULT_BACKEND_READINESS_TIMEOUT = Duration.minutes(1);
const DEFAULT_BACKEND_READINESS_INTERVAL = Duration.millis(100);
const DEFAULT_BACKEND_READINESS_REQUEST_TIMEOUT = Duration.seconds(1);
const DEFAULT_BACKEND_TERMINATE_GRACE = Duration.seconds(2);
+const DEFAULT_BACKEND_OUTPUT_DRAIN_TIMEOUT = Duration.seconds(5);
const BACKEND_READINESS_PATH = "/.well-known/t3/environment";
+const { logWarning: logBackendProcessWarning } =
+ DesktopObservability.makeComponentLogger("desktop-backend-process");
type BackendProcessLayerServices = ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient;
@@ -70,13 +75,17 @@ type BackendProcessRunRequirements = BackendProcessLayerServices | Scope.Scope;
export type BackendProcessOutputStream = "stdout" | "stderr";
-export type DesktopBackendBootstrapDelivery = "fd3" | "stdin";
-
-export interface DesktopBackendStartConfig {
+export interface BackendProcessContext {
readonly executablePath: string;
- readonly args: ReadonlyArray<string>;
readonly entryPath: string;
readonly cwd: string;
+ readonly httpBaseUrl: URL;
+}
+
+export type DesktopBackendBootstrapDelivery = "fd3" | "stdin";
+
+export interface DesktopBackendStartConfig extends BackendProcessContext {
+ readonly args: ReadonlyArray<string>;
readonly env: Record<string, string | undefined>;
// When true the spawner merges the desktop process.env on top of `env`;
// when false `env` is passed verbatim. WSL mode opts out so a leaking
@@ -106,55 +115,122 @@ export interface PreflightFailure {
interface BackendProcessExit {
readonly code: Option.Option<number>;
readonly reason: string;
- readonly result: Result.Result<ChildProcessSpawner.ExitCode, PlatformError.PlatformError>;
}
-export class BackendTimeoutError extends Schema.TaggedErrorClass<BackendTimeoutError>()(
- "BackendTimeoutError",
+const backendProcessContextSchema = {
+ executablePath: Schema.String,
+ entryPath: Schema.String,
+ cwd: Schema.String,
+ httpBaseUrl: Schema.URL,
+};
+
+export class BackendReadinessTimeoutError extends Schema.TaggedErrorClass<BackendReadinessTimeoutError>()(
+ "BackendReadinessTimeoutError",
{
- url: Schema.instanceOf(URL),
+ ...backendProcessContextSchema,
+ readinessUrl: Schema.URL,
+ timeoutMs: Schema.Number,
+ cause: Schema.Defect(),
},
) {
- override get message() {
- return `Timed out waiting for backend readiness at ${this.url.href}.`;
+ override get message(): string {
+ return `Timed out after ${this.timeoutMs}ms waiting for desktop backend readiness at ${this.readinessUrl.href}.`;
}
}
-class BackendProcessBootstrapEncodeError extends Schema.TaggedErrorClass<BackendProcessBootstrapEncodeError>()(
+export class BackendProcessBootstrapEncodeError extends Schema.TaggedErrorClass<BackendProcessBootstrapEncodeError>()(
"BackendProcessBootstrapEncodeError",
{
- entryPath: Schema.String,
+ ...backendProcessContextSchema,
cause: Schema.Defect(),
},
) {
- override get message() {
+ override get message(): string {
return `Failed to encode the desktop backend bootstrap payload for ${this.entryPath}.`;
}
}
-class BackendProcessSpawnError extends Schema.TaggedErrorClass<BackendProcessSpawnError>()(
+export class BackendProcessSpawnError extends Schema.TaggedErrorClass<BackendProcessSpawnError>()(
"BackendProcessSpawnError",
{
- executablePath: Schema.String,
+ ...backendProcessContextSchema,
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return `Failed to spawn desktop backend entry ${this.entryPath} with ${this.executablePath}.`;
+ }
+}
+
+export class BackendProcessOutputReadError extends Schema.TaggedErrorClass<BackendProcessOutputReadError>()(
+ "BackendProcessOutputReadError",
+ {
+ ...backendProcessContextSchema,
+ pid: Schema.Number,
+ streamName: Schema.Literals(["stdout", "stderr"]),
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return `Failed to read ${this.streamName} from desktop backend process ${this.pid}.`;
+ }
+}
+
+export class BackendProcessOutputHandlingError extends Schema.TaggedErrorClass<BackendProcessOutputHandlingError>()(
+ "BackendProcessOutputHandlingError",
+ {
+ ...backendProcessContextSchema,
+ pid: Schema.Number,
+ streamName: Schema.Literals(["stdout", "stderr"]),
+ chunkByteLength: Schema.Number,
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return `Failed to handle ${this.chunkByteLength} bytes from ${this.streamName} of desktop backend process ${this.pid}.`;
+ }
+}
+
+export type BackendProcessOutputError =
+ | BackendProcessOutputReadError
+ | BackendProcessOutputHandlingError;
+
+export class BackendProcessExitStatusError extends Schema.TaggedErrorClass<BackendProcessExitStatusError>()(
+ "BackendProcessExitStatusError",
+ {
+ ...backendProcessContextSchema,
+ pid: Schema.Number,
cause: Schema.Defect(),
},
) {
- override get message() {
- return `Failed to spawn the desktop backend process at ${this.executablePath}.`;
+ override get message(): string {
+ return `Failed to read the exit status of desktop backend process ${this.pid}.`;
}
}
-type BackendProcessError = BackendProcessBootstrapEncodeError | BackendProcessSpawnError;
+export const BackendProcessError = Schema.Union([
+ BackendProcessBootstrapEncodeError,
+ BackendProcessSpawnError,
+ BackendProcessExitStatusError,
+]);
+export type BackendProcessError = typeof BackendProcessError.Type;
interface RunBackendProcessOptions extends DesktopBackendStartConfig {
+ readonly desktopTelemetryStream: Stream.Stream<Uint8Array>;
+ readonly onDesktopTelemetryControl?: (
+ message: DesktopTelemetryControlMessageValue,
+ ) => Effect.Effect<void>;
readonly readinessTimeout?: Duration.Duration;
+ readonly outputDrainTimeout?: Duration.Duration;
readonly onStarted?: (pid: number) => Effect.Effect<void>;
+ readonly onExitObserved?: () => Effect.Effect<void>;
readonly onReady?: () => Effect.Effect<void>;
- readonly onReadinessFailure?: (error: BackendTimeoutError) => Effect.Effect<void>;
+ readonly onReadinessFailure?: (error: BackendReadinessTimeoutError) => Effect.Effect<void>;
readonly onOutput?: (
streamName: BackendProcessOutputStream,
chunk: Uint8Array,
- ) => Effect.Effect<void>;
+ ) => Effect.Effect<void, Error>;
+ readonly onOutputFailure?: (error: BackendProcessOutputError) => Effect.Effect<void>;
}
export interface DesktopBackendSnapshot {
@@ -225,6 +301,8 @@ interface ActiveBackendRun {
readonly scope: Scope.Closeable;
readonly fiber: Option.Option<Fiber.Fiber<void, never>>;
readonly pid: Option.Option<number>;
+ readonly exitObserved: boolean;
+ readonly stopRequested: boolean;
}
interface BackendManagerState {
@@ -266,76 +344,130 @@ const calculateRestartDelay = (attempt: number): Duration.Duration =>
const closeRun = (
run: ActiveBackendRun,
+ parentScope: Scope.Scope,
options?: { readonly timeout?: Duration.Duration },
-): Effect.Effect<void> => {
+): Effect.Effect<boolean> => {
const waitForFiber = Option.match(run.fiber, {
onNone: () => Effect.void,
onSome: (fiber) => Fiber.await(fiber).pipe(Effect.asVoid),
});
const close = Scope.close(run.scope, Exit.void).pipe(Effect.andThen(waitForFiber));
+ const timeout = options?.timeout;
- return (
- options?.timeout ? close.pipe(Effect.timeoutOption(options.timeout), Effect.asVoid) : close
- ).pipe(Effect.ignore);
+ if (!timeout) {
+ return close.pipe(Effect.as(true));
+ }
+
+ return Effect.forkIn(close, parentScope).pipe(
+ Effect.flatMap((closeFiber) =>
+ Fiber.await(closeFiber).pipe(Effect.timeoutOption(timeout), Effect.map(Option.isSome)),
+ ),
+ );
};
-const waitForHttpReady = (
- baseUrl: URL,
- timeout: Duration.Duration,
-): Effect.Effect<void, BackendTimeoutError, HttpClient.HttpClient> => {
- const readinessUrl = new URL(BACKEND_READINESS_PATH, baseUrl);
+export const waitForHttpReady = (
+ options: BackendProcessContext & { readonly timeout: Duration.Duration },
+): Effect.Effect<void, BackendReadinessTimeoutError, HttpClient.HttpClient> => {
+ const readinessUrl = new URL(BACKEND_READINESS_PATH, options.httpBaseUrl);
return waitForHttpReadyShared({
- baseUrl: baseUrl.href,
+ baseUrl: options.httpBaseUrl.href,
path: BACKEND_READINESS_PATH,
- timeoutMs: Duration.toMillis(timeout),
+ timeoutMs: Duration.toMillis(options.timeout),
intervalMs: Duration.toMillis(DEFAULT_BACKEND_READINESS_INTERVAL),
probeTimeoutMs: Duration.toMillis(DEFAULT_BACKEND_READINESS_REQUEST_TIMEOUT),
- makeError: () => new BackendTimeoutError({ url: readinessUrl }),
+ makeError: ({ cause }) =>
+ new BackendReadinessTimeoutError({
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
+ readinessUrl,
+ timeoutMs: Duration.toMillis(options.timeout),
+ cause,
+ }),
});
};
-function describeProcessExit(
- result: Result.Result<ChildProcessSpawner.ExitCode, PlatformError.PlatformError>,
-): BackendProcessExit {
- if (Result.isSuccess(result)) {
- return {
- code: Option.some(result.success),
- reason: `code=${result.success}`,
- result,
- };
- }
-
- return {
- code: Option.none(),
- reason: result.failure.message,
- result,
- };
-}
-
function drainBackendOutput(
+ context: BackendProcessContext & { readonly pid: number },
streamName: BackendProcessOutputStream,
stream: Stream.Stream<Uint8Array, PlatformError.PlatformError>,
- onOutput: (streamName: BackendProcessOutputStream, chunk: Uint8Array) => Effect.Effect<void>,
+ onOutput: (
+ streamName: BackendProcessOutputStream,
+ chunk: Uint8Array,
+ ) => Effect.Effect<void, Error>,
+ onOutputFailure: (error: BackendProcessOutputError) => Effect.Effect<void>,
): Effect.Effect<void> {
return stream.pipe(
- Stream.runForEach((chunk) => onOutput(streamName, chunk)),
- Effect.ignore,
+ Stream.mapError(
+ (cause) =>
+ new BackendProcessOutputReadError({
+ ...context,
+ streamName,
+ cause,
+ }),
+ ),
+ Stream.runForEach((chunk) =>
+ onOutput(streamName, chunk).pipe(
+ Effect.mapError(
+ (cause) =>
+ new BackendProcessOutputHandlingError({
+ ...context,
+ streamName,
+ chunkByteLength: chunk.byteLength,
+ cause,
+ }),
+ ),
+ Effect.catchTag("BackendProcessOutputHandlingError", onOutputFailure),
+ ),
+ ),
+ Effect.catchTags({
+ BackendProcessOutputReadError: onOutputFailure,
+ }),
);
}
const encodeBootstrapJson = Schema.encodeEffect(Schema.fromJsonString(DesktopBackendBootstrap));
+const decodeDesktopTelemetryControlLine = Schema.decodeUnknownEffect(
+ Schema.fromJsonString(DesktopTelemetryControlMessage),
+);
-const runBackendProcess = Effect.fn("runBackendProcess")(function* (
+export const runBackendProcess = Effect.fn("runBackendProcess")(function* (
options: RunBackendProcessOptions,
): Effect.fn.Return<BackendProcessExit, BackendProcessError, BackendProcessRunRequirements> {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const bootstrapJson = yield* encodeBootstrapJson(options.bootstrap).pipe(
Effect.mapError(
- (cause) => new BackendProcessBootstrapEncodeError({ entryPath: options.entryPath, cause }),
+ (cause) =>
+ new BackendProcessBootstrapEncodeError({
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
+ cause,
+ }),
),
);
const onOutput = options.onOutput ?? (() => Effect.void);
const bootstrapStream = Stream.encodeText(Stream.make(`${bootstrapJson}\n`));
+ const additionalFds: Record<`fd${number}`, ChildProcess.AdditionalFdConfig> = {};
+ if (options.bootstrapDelivery === "fd3") {
+ additionalFds.fd3 = {
+ type: "input",
+ stream: bootstrapStream,
+ };
+ if (options.bootstrap.desktopTelemetryFd !== undefined) {
+ additionalFds[`fd${options.bootstrap.desktopTelemetryFd}`] = {
+ type: "input",
+ stream: options.desktopTelemetryStream,
+ };
+ }
+ if (options.bootstrap.desktopTelemetryControlFd !== undefined) {
+ additionalFds[`fd${options.bootstrap.desktopTelemetryControlFd}`] = {
+ type: "output",
+ };
+ }
+ }
const command = ChildProcess.make(options.executablePath, options.args, {
cwd: options.cwd,
env: options.env,
@@ -350,34 +482,131 @@ const runBackendProcess = Effect.fn("runBackendProcess")(function* (
// wsl.exe drops additional file descriptors when forwarding to the Linux
// side, so the WSL spawn path delivers the bootstrap envelope via stdin
// (`--bootstrap-fd 0`) instead.
- ...(options.bootstrapDelivery === "fd3"
- ? { additionalFds: { fd3: { type: "input" as const, stream: bootstrapStream } } }
- : {}),
+ ...(options.bootstrapDelivery === "fd3" ? { additionalFds } : {}),
});
- const handle = yield* spawner
- .spawn(command)
- .pipe(
- Effect.mapError(
- (cause) => new BackendProcessSpawnError({ executablePath: options.executablePath, cause }),
- ),
- );
+ const handle = yield* spawner.spawn(command).pipe(
+ Effect.mapError(
+ (cause) =>
+ new BackendProcessSpawnError({
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
+ cause,
+ }),
+ ),
+ );
+ const outputFibers: Array<Fiber.Fiber<void, never>> = [];
yield* options.onStarted?.(handle.pid) ?? Effect.void;
+ if (
+ options.bootstrap.desktopTelemetryControlFd !== undefined &&
+ options.onDesktopTelemetryControl !== undefined
+ ) {
+ const controlFd = options.bootstrap.desktopTelemetryControlFd;
+ const handleControl = options.onDesktopTelemetryControl;
+ yield* handle.getOutputFd(controlFd).pipe(
+ Stream.decodeText(),
+ Stream.splitLines,
+ Stream.filter((line) => line.trim().length > 0),
+ Stream.runForEach((line) =>
+ decodeDesktopTelemetryControlLine(line).pipe(
+ Effect.flatMap(handleControl),
+ Effect.catchCause((cause) =>
+ logBackendProcessWarning("ignored invalid desktop telemetry control message", {
+ fd: controlFd,
+ cause: Cause.pretty(cause),
+ }),
+ ),
+ ),
+ ),
+ Effect.catchCause((cause) =>
+ logBackendProcessWarning("desktop telemetry control stream stopped", {
+ fd: controlFd,
+ cause: Cause.pretty(cause),
+ }),
+ ),
+ Effect.ensuring(
+ handleControl({
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled: false,
+ }),
+ ),
+ Effect.forkScoped,
+ );
+ }
if (options.captureOutput) {
- yield* drainBackendOutput("stdout", handle.stdout, onOutput).pipe(Effect.forkScoped);
- yield* drainBackendOutput("stderr", handle.stderr, onOutput).pipe(Effect.forkScoped);
+ const outputContext = {
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
+ pid: Number(handle.pid),
+ };
+ const onOutputFailure = options.onOutputFailure ?? (() => Effect.void);
+ outputFibers.push(
+ yield* drainBackendOutput(
+ outputContext,
+ "stdout",
+ handle.stdout,
+ onOutput,
+ onOutputFailure,
+ ).pipe(Effect.forkScoped),
+ yield* drainBackendOutput(
+ outputContext,
+ "stderr",
+ handle.stderr,
+ onOutput,
+ onOutputFailure,
+ ).pipe(Effect.forkScoped),
+ );
}
- yield* waitForHttpReady(
- options.httpBaseUrl,
- options.readinessTimeout ?? DEFAULT_BACKEND_READINESS_TIMEOUT,
- ).pipe(
+ yield* waitForHttpReady({
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
+ timeout: options.readinessTimeout ?? DEFAULT_BACKEND_READINESS_TIMEOUT,
+ }).pipe(
Effect.tap(() => options.onReady?.() ?? Effect.void),
- Effect.catch((error) => options.onReadinessFailure?.(error) ?? Effect.void),
+ Effect.catchTags({
+ BackendReadinessTimeoutError: (error) => options.onReadinessFailure?.(error) ?? Effect.void,
+ }),
Effect.forkScoped,
);
- return describeProcessExit(yield* Effect.result(handle.exitCode));
+ const exit = yield* handle.exitCode.pipe(
+ Effect.mapError(
+ (cause) =>
+ new BackendProcessExitStatusError({
+ executablePath: options.executablePath,
+ entryPath: options.entryPath,
+ cwd: options.cwd,
+ httpBaseUrl: options.httpBaseUrl,
+ pid: Number(handle.pid),
+ cause,
+ }),
+ ),
+ Effect.exit,
+ );
+ yield* options.onExitObserved?.() ?? Effect.void;
+ yield* Effect.forEach(outputFibers, Fiber.await, {
+ concurrency: "unbounded",
+ discard: true,
+ }).pipe(
+ Effect.timeout(options.outputDrainTimeout ?? DEFAULT_BACKEND_OUTPUT_DRAIN_TIMEOUT),
+ Effect.ignore,
+ );
+ if (Exit.isFailure(exit)) {
+ return yield* Effect.failCause(exit.cause);
+ }
+ const exitCode = exit.value;
+ return {
+ code: Option.some(exitCode),
+ reason: `code=${exitCode}`,
+ } satisfies BackendProcessExit;
});
// Factory for one pooled backend instance. The returned instance owns
@@ -394,12 +623,14 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
| ChildProcessSpawner.ChildProcessSpawner
| HttpClient.HttpClient
| DesktopObservability.DesktopBackendOutputLogFactory
+ | DesktopTelemetryPublisher.DesktopTelemetryPublisher
| Scope.Scope
> {
const parentScope = yield* Scope.Scope;
const fileSystem = yield* FileSystem.FileSystem;
const backendOutputLogFactory = yield* DesktopObservability.DesktopBackendOutputLogFactory;
const backendOutputLog = yield* backendOutputLogFactory.forInstance(spec.id);
+ const desktopTelemetryPublisher = yield* DesktopTelemetryPublisher.DesktopTelemetryPublisher;
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const httpClient = yield* HttpClient.HttpClient;
const state = yield* Ref.make(initialState);
@@ -444,6 +675,12 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
Effect.gen(function* () {
const current = yield* Ref.get(state);
if (Option.isSome(current.active)) {
+ if (!current.desiredRunning) {
+ yield* Ref.update(state, (latest) => ({
+ ...latest,
+ desiredRunning: true,
+ }));
+ }
return;
}
@@ -462,6 +699,9 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
Effect.option,
);
if (Option.isNone(config)) {
+ if (current.desiredRunning) {
+ yield* scheduleRestart("failed to generate desktop backend configuration");
+ }
return;
}
const entryExists = yield* fileSystem
@@ -561,6 +801,8 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
scope: runScope,
fiber: Option.none(),
pid: Option.none(),
+ exitObserved: false,
+ stopRequested: false,
} satisfies ActiveBackendRun),
nextRunId: latest.nextRunId + 1,
},
@@ -571,54 +813,70 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
) {
yield* mutex.withPermits(1)(
Effect.gen(function* () {
- const { isCurrentRun, nextState, pid } = yield* Ref.modify(
- state,
- (
- latest,
- ): readonly [
- {
- readonly isCurrentRun: boolean;
- readonly nextState: BackendManagerState;
- readonly pid: Option.Option<number>;
- },
- BackendManagerState,
- ] => {
- const currentRun = Option.getOrUndefined(latest.active);
- if (currentRun?.id !== runId) {
+ const { isCurrentRun, nextState, pid, exitObserved, stopRequested, wasReady } =
+ yield* Ref.modify(
+ state,
+ (
+ latest,
+ ): readonly [
+ {
+ readonly isCurrentRun: boolean;
+ readonly nextState: BackendManagerState;
+ readonly pid: Option.Option<number>;
+ readonly exitObserved: boolean;
+ readonly stopRequested: boolean;
+ readonly wasReady: boolean;
+ },
+ BackendManagerState,
+ ] => {
+ const currentRun = Option.getOrUndefined(latest.active);
+ if (currentRun?.id !== runId) {
+ return [
+ {
+ isCurrentRun: false,
+ nextState: latest,
+ pid: Option.none<number>(),
+ exitObserved: false,
+ stopRequested: false,
+ wasReady: false,
+ },
+ latest,
+ ] as const;
+ }
+
+ const next = {
+ ...latest,
+ active: Option.none<ActiveBackendRun>(),
+ ready: false,
+ };
return [
{
- isCurrentRun: false,
- nextState: latest,
- pid: Option.none<number>(),
+ isCurrentRun: true,
+ nextState: next,
+ pid: currentRun.pid,
+ exitObserved: currentRun.exitObserved,
+ stopRequested: currentRun.stopRequested,
+ wasReady: latest.ready,
},
- latest,
+ next,
] as const;
- }
-
- const next = {
- ...latest,
- active: Option.none<ActiveBackendRun>(),
- ready: false,
- };
- return [
- {
- isCurrentRun: true,
- nextState: next,
- pid: currentRun.pid,
- },
- next,
- ] as const;
- },
- );
+ },
+ );
if (isCurrentRun) {
+ yield* desktopTelemetryPublisher.removeControlSource(spec.id);
if (Option.isSome(pid)) {
- yield* backendOutputLog.writeSessionBoundary({
- phase: "END",
- details: `pid=${pid.value} ${reason}`,
- });
+ if (exitObserved && !stopRequested) {
+ yield* backendOutputLog.persistFailure({
+ details: `pid=${pid.value} ${reason}`,
+ });
+ } else {
+ yield* backendOutputLog.discardSession;
+ }
+ }
+ if (wasReady) {
+ yield* spec.onShutdown?.() ?? Effect.void;
}
- yield* spec.onShutdown?.() ?? Effect.void;
}
if (isCurrentRun && nextState.desiredRunning) {
@@ -630,16 +888,23 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
const program = runBackendProcess({
...config.value,
+ desktopTelemetryStream: desktopTelemetryPublisher.encoded,
+ onDesktopTelemetryControl: (message) =>
+ desktopTelemetryPublisher.handleControlForSource(spec.id, message),
onStarted: Effect.fn("desktop.backendInstance.onStarted")(function* (pid) {
yield* updateActiveRun(runId, (run) => ({
...run,
pid: Option.some(pid),
}));
- yield* backendOutputLog.writeSessionBoundary({
- phase: "START",
+ yield* backendOutputLog.beginSession({
details: `pid=${pid} port=${config.value.bootstrap.port} cwd=${config.value.cwd}`,
});
}),
+ onExitObserved: () =>
+ updateActiveRun(runId, (run) => ({
+ ...run,
+ exitObserved: true,
+ })),
onReady: Effect.fn("desktop.backendInstance.onReady")(function* () {
const isCurrentRun = yield* Ref.modify(state, (latest) => {
const activeRun = Option.getOrUndefined(latest.active);
@@ -662,10 +927,16 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
yield* spec.onReady?.(config.value.httpBaseUrl) ?? Effect.void;
}),
- onReadinessFailure: (error) =>
- logInstanceWarning("backend readiness check failed during bootstrap", {
- error: error.message,
- }),
+ onReadinessFailure: Effect.fn("desktop.backendInstance.onReadinessFailure")(
+ function* (error) {
+ yield* logInstanceWarning("backend readiness check failed during bootstrap", {
+ error: error.message,
+ });
+ yield* backendOutputLog.persistFailureSnapshot({
+ details: error.message,
+ });
+ },
+ ),
onOutput: (streamName, chunk) => backendOutputLog.writeOutputChunk(streamName, chunk),
}).pipe(
Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
@@ -750,41 +1021,92 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
const stop = Effect.fn("desktop.backendInstance.stop")(function* (options?: {
readonly timeout?: Duration.Duration;
}) {
- const { active, restartFiber } = yield* mutex.withPermits(1)(
+ const { active, restartFiber, notifyShutdown } = yield* mutex.withPermits(1)(
Effect.gen(function* () {
- const result = yield* Ref.modify(state, (latest) => [
- {
- active: latest.active,
- restartFiber: latest.restartFiber,
- },
- {
- ...latest,
- desiredRunning: false,
- ready: false,
- active: Option.none<ActiveBackendRun>(),
- restartFiber: Option.none<Fiber.Fiber<void, never>>(),
- },
- ]);
- // Ignore failures from spec.onShutdown so a downstream throw
- // can't abort the rest of stop(). Ref.modify above already
- // flipped state to "no active run / no restart fiber", and the
- // physical cleanup (Fiber.interrupt + closeRun) runs after the
- // mutex releases. If onShutdown were allowed to propagate, both
- // would be skipped and the child process + restart fiber would
- // be orphaned while state claimed nothing was running — the
- // next start() would then spawn a second backend on top.
- yield* (spec.onShutdown?.() ?? Effect.void).pipe(Effect.ignore);
+ const result = yield* Ref.modify(state, (latest) => {
+ const active = Option.map(latest.active, (run) =>
+ run.exitObserved ? run : { ...run, stopRequested: true },
+ );
+ return [
+ {
+ active,
+ restartFiber: latest.restartFiber,
+ notifyShutdown: latest.ready,
+ },
+ {
+ ...latest,
+ desiredRunning: false,
+ ready: false,
+ active,
+ restartFiber: Option.none<Fiber.Fiber<void, never>>(),
+ },
+ ] as const;
+ });
return result;
}),
);
+ if (notifyShutdown) {
+ yield* (spec.onShutdown?.() ?? Effect.void).pipe(Effect.ignore);
+ }
yield* Option.match(restartFiber, {
onNone: () => Effect.void,
onSome: (fiber) => Fiber.interrupt(fiber).pipe(Effect.asVoid),
});
yield* Option.match(active, {
onNone: () => Effect.void,
- onSome: (run) => closeRun(run, options),
+ onSome: (run) =>
+ Effect.gen(function* () {
+ const closed = yield* closeRun(run, parentScope, options);
+ if (!closed) {
+ return;
+ }
+ const cleanup = yield* mutex.withPermits(1)(
+ Ref.modify(
+ state,
+ (
+ latest,
+ ): readonly [
+ {
+ readonly needsCleanup: boolean;
+ readonly shouldStart: boolean;
+ },
+ BackendManagerState,
+ ] => {
+ const current = Option.getOrUndefined(latest.active);
+ if (current?.id !== run.id) {
+ return [
+ {
+ needsCleanup: false,
+ shouldStart:
+ latest.desiredRunning &&
+ Option.isNone(latest.active) &&
+ Option.isNone(latest.restartFiber),
+ },
+ latest,
+ ];
+ }
+ return [
+ {
+ needsCleanup: true,
+ shouldStart: latest.desiredRunning,
+ },
+ {
+ ...latest,
+ active: Option.none<ActiveBackendRun>(),
+ },
+ ];
+ },
+ ),
+ );
+ if (cleanup.needsCleanup) {
+ yield* desktopTelemetryPublisher.removeControlSource(spec.id);
+ yield* backendOutputLog.discardSession;
+ }
+ if (cleanup.shouldStart) {
+ yield* start;
+ }
+ }),
});
});
diff --git a/apps/desktop/src/backend/DesktopBackendPool.test.ts b/apps/desktop/src/backend/DesktopBackendPool.test.ts
index fa0811d5d..523e87646 100644
--- a/apps/desktop/src/backend/DesktopBackendPool.test.ts
+++ b/apps/desktop/src/backend/DesktopBackendPool.test.ts
@@ -5,11 +5,13 @@ import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
import * as DesktopObservability from "../app/DesktopObservability.ts";
import * as DesktopAppSettings from "../settings/DesktopAppSettings.ts";
+import * as DesktopTelemetryPublisher from "../telemetry/DesktopTelemetryPublisher.ts";
import * as ElectronDialog from "../electron/ElectronDialog.ts";
import * as DesktopWindow from "../window/DesktopWindow.ts";
import * as DesktopBackendConfiguration from "./DesktopBackendConfiguration.ts";
@@ -56,10 +58,21 @@ function makePoolLayer(
Layer.succeed(DesktopObservability.DesktopBackendOutputLogFactory, {
forInstance: () =>
Effect.succeed({
- writeSessionBoundary: () => Effect.void,
+ beginSession: () => Effect.void,
writeOutputChunk: () => Effect.void,
+ persistFailureSnapshot: () => Effect.void,
+ persistFailure: () => Effect.void,
+ discardSession: Effect.void,
} satisfies DesktopObservability.DesktopBackendOutputLogShape),
} satisfies DesktopObservability.DesktopBackendOutputLogFactory["Service"]),
+ Layer.succeed(DesktopTelemetryPublisher.DesktopTelemetryPublisher, {
+ latest: Effect.succeed(Option.none()),
+ changes: Stream.empty,
+ encoded: Stream.empty,
+ handleControl: () => Effect.void,
+ handleControlForSource: () => Effect.void,
+ removeControlSource: () => Effect.void,
+ }),
Layer.succeed(DesktopBackendConfiguration.DesktopBackendConfiguration, {
resolvePrimary: Effect.die("unexpected primary config resolve"),
resolvePrimaryLabel: Ref.get(labelRef),
diff --git a/apps/desktop/src/backend/DesktopBackendPool.ts b/apps/desktop/src/backend/DesktopBackendPool.ts
index 258f8731f..9b85d1bb2 100644
--- a/apps/desktop/src/backend/DesktopBackendPool.ts
+++ b/apps/desktop/src/backend/DesktopBackendPool.ts
@@ -97,6 +97,7 @@ import * as DesktopBackendConfiguration from "./DesktopBackendConfiguration.ts";
import * as DesktopBackendManager from "./DesktopBackendManager.ts";
import * as DesktopObservability from "../app/DesktopObservability.ts";
import * as DesktopAppSettings from "../settings/DesktopAppSettings.ts";
+import * as DesktopTelemetryPublisher from "../telemetry/DesktopTelemetryPublisher.ts";
import * as DesktopWindow from "../window/DesktopWindow.ts";
import * as ElectronDialog from "../electron/ElectronDialog.ts";
@@ -176,7 +177,8 @@ export type BackendInstanceFactoryRequirements =
| FileSystem.FileSystem
| ChildProcessSpawner.ChildProcessSpawner
| HttpClient.HttpClient
- | DesktopObservability.DesktopBackendOutputLogFactory;
+ | DesktopObservability.DesktopBackendOutputLogFactory
+ | DesktopTelemetryPublisher.DesktopTelemetryPublisher;
interface ActiveRegisteredInstance {
readonly _tag: "Active";
diff --git a/apps/desktop/src/electron/ElectronApp.ts b/apps/desktop/src/electron/ElectronApp.ts
index 933f40e17..5f8052f90 100644
--- a/apps/desktop/src/electron/ElectronApp.ts
+++ b/apps/desktop/src/electron/ElectronApp.ts
@@ -57,6 +57,7 @@ export class ElectronApp extends Context.Service<
) => Effect.Effect<void>;
readonly setAppUserModelId: (id: string) => Effect.Effect<void>;
readonly requestSingleInstanceLock: Effect.Effect<boolean>;
+ readonly getAppMetrics: Effect.Effect<ReadonlyArray<Electron.ProcessMetric>>;
readonly isDefaultProtocolClient: (protocol: string) => Effect.Effect<boolean>;
readonly setAsDefaultProtocolClient: (
protocol: string,
@@ -153,6 +154,7 @@ export const make = ElectronApp.of({
Electron.app.setAppUserModelId(id);
}),
requestSingleInstanceLock: Effect.sync(() => Electron.app.requestSingleInstanceLock()),
+ getAppMetrics: Effect.sync(() => Electron.app.getAppMetrics()),
isDefaultProtocolClient: (protocol) =>
Effect.sync(() => Electron.app.isDefaultProtocolClient(protocol)),
setAsDefaultProtocolClient: (protocol, path, args) =>
diff --git a/apps/desktop/src/electron/ElectronPowerMonitor.ts b/apps/desktop/src/electron/ElectronPowerMonitor.ts
new file mode 100644
index 000000000..ad322a573
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronPowerMonitor.ts
@@ -0,0 +1,89 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Scope from "effect/Scope";
+
+import * as Electron from "electron";
+
+export type ElectronThermalState = ReturnType<Electron.PowerMonitor["getCurrentThermalState"]>;
+export type ElectronIdleState = ReturnType<Electron.PowerMonitor["getSystemIdleState"]>;
+
+export class ElectronPowerMonitor extends Context.Service<
+ ElectronPowerMonitor,
+ {
+ readonly isOnBatteryPower: Effect.Effect<boolean>;
+ readonly getSystemIdleTime: Effect.Effect<number>;
+ readonly getSystemIdleState: (idleThresholdSeconds: number) => Effect.Effect<ElectronIdleState>;
+ readonly getCurrentThermalState: Effect.Effect<ElectronThermalState>;
+ readonly onSimpleEvent: (
+ eventName: "lock-screen" | "unlock-screen" | "on-ac" | "on-battery" | "suspend" | "resume",
+ listener: () => void,
+ ) => Effect.Effect<void, never, Scope.Scope>;
+ readonly onThermalStateChange: (
+ listener: (state: ElectronThermalState) => void,
+ ) => Effect.Effect<void, never, Scope.Scope>;
+ readonly onSpeedLimitChange: (
+ listener: (limit: number) => void,
+ ) => Effect.Effect<void, never, Scope.Scope>;
+ }
+>()("@t3tools/desktop/electron/ElectronPowerMonitor") {}
+
+const onSimpleEvent: ElectronPowerMonitor["Service"]["onSimpleEvent"] = (eventName, listener) =>
+ Effect.acquireRelease(
+ Effect.sync(() => {
+ Electron.powerMonitor.on(eventName as any, listener as any);
+ }),
+ () =>
+ Effect.sync(() => {
+ Electron.powerMonitor.removeListener(eventName as any, listener as any);
+ }),
+ ).pipe(Effect.asVoid);
+
+const onThermalStateChange: ElectronPowerMonitor["Service"]["onThermalStateChange"] = (
+ listener,
+) => {
+ const wrapped = (
+ event: Electron.Event<Electron.PowerMonitorThermalStateChangeEventParams>,
+ ): void => {
+ listener(event.state);
+ };
+ return Effect.acquireRelease(
+ Effect.sync(() => {
+ Electron.powerMonitor.on("thermal-state-change", wrapped);
+ }),
+ () =>
+ Effect.sync(() => {
+ Electron.powerMonitor.removeListener("thermal-state-change", wrapped);
+ }),
+ ).pipe(Effect.asVoid);
+};
+
+const onSpeedLimitChange: ElectronPowerMonitor["Service"]["onSpeedLimitChange"] = (listener) => {
+ const wrapped = (
+ event: Electron.Event<Electron.PowerMonitorSpeedLimitChangeEventParams>,
+ ): void => {
+ listener(event.limit);
+ };
+ return Effect.acquireRelease(
+ Effect.sync(() => {
+ Electron.powerMonitor.on("speed-limit-change", wrapped);
+ }),
+ () =>
+ Effect.sync(() => {
+ Electron.powerMonitor.removeListener("speed-limit-change", wrapped);
+ }),
+ ).pipe(Effect.asVoid);
+};
+
+export const make = ElectronPowerMonitor.of({
+ isOnBatteryPower: Effect.sync(() => Electron.powerMonitor.isOnBatteryPower()),
+ getSystemIdleTime: Effect.sync(() => Electron.powerMonitor.getSystemIdleTime()),
+ getSystemIdleState: (idleThresholdSeconds) =>
+ Effect.sync(() => Electron.powerMonitor.getSystemIdleState(idleThresholdSeconds)),
+ getCurrentThermalState: Effect.sync(() => Electron.powerMonitor.getCurrentThermalState()),
+ onSimpleEvent,
+ onThermalStateChange,
+ onSpeedLimitChange,
+});
+
+export const layer = Layer.succeed(ElectronPowerMonitor, make);
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 9795f04e8..ad370e36f 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -24,6 +24,7 @@ import * as DesktopIpc from "./ipc/DesktopIpc.ts";
import * as ElectronApp from "./electron/ElectronApp.ts";
import * as ElectronDialog from "./electron/ElectronDialog.ts";
import * as ElectronMenu from "./electron/ElectronMenu.ts";
+import * as ElectronPowerMonitor from "./electron/ElectronPowerMonitor.ts";
import * as ElectronProtocol from "./electron/ElectronProtocol.ts";
import * as ElectronSafeStorage from "./electron/ElectronSafeStorage.ts";
import * as ElectronShell from "./electron/ElectronShell.ts";
@@ -52,6 +53,7 @@ import * as DesktopShellEnvironment from "./shell/DesktopShellEnvironment.ts";
import * as DesktopSshEnvironment from "./ssh/DesktopSshEnvironment.ts";
import * as DesktopSshPasswordPrompts from "./ssh/DesktopSshPasswordPrompts.ts";
import * as DesktopState from "./app/DesktopState.ts";
+import * as DesktopTelemetryPublisher from "./telemetry/DesktopTelemetryPublisher.ts";
import * as DesktopUpdates from "./updates/DesktopUpdates.ts";
import * as BrowserSession from "./preview/BrowserSession.ts";
import * as PreviewManager from "./preview/Manager.ts";
@@ -113,6 +115,7 @@ const electronLayer = Layer.mergeAll(
ElectronApp.layer,
ElectronDialog.layer,
ElectronMenu.layer,
+ ElectronPowerMonitor.layer,
ElectronProtocol.layer,
ElectronSafeStorage.layer,
ElectronShell.layer,
@@ -160,6 +163,7 @@ const desktopBackendLayer = DesktopBackendPool.layer.pipe(
Layer.provideMerge(DesktopAppIdentity.layer),
Layer.provideMerge(DesktopBackendConfiguration.layer),
Layer.provideMerge(DesktopWslEnvironment.layer),
+ Layer.provideMerge(DesktopTelemetryPublisher.layer),
Layer.provideMerge(desktopWindowLayer),
);
diff --git a/apps/desktop/src/preview/Manager.test.ts b/apps/desktop/src/preview/Manager.test.ts
index fa962f58c..684d6655d 100644
--- a/apps/desktop/src/preview/Manager.test.ts
+++ b/apps/desktop/src/preview/Manager.test.ts
@@ -982,6 +982,92 @@ describe("PreviewManager", () => {
),
);
+ effectIt.effect("emits debugger screencast frames only while recording is active", () =>
+ withManager((manager) =>
+ Effect.gen(function* () {
+ let debuggerMessage:
+ | ((event: unknown, method: string, params: Record<string, unknown>) => void)
+ | undefined;
+ const capturePage = vi.fn(async () => ({
+ toJPEG: () => Buffer.from("scheduled-recording-frame"),
+ getSize: () => ({ width: 1280, height: 720 }),
+ }));
+ const sendCommand = vi.fn(async (method: string) =>
+ method === "Runtime.evaluate" ? { result: { value: null } } : undefined,
+ );
+ fromId.mockReturnValue({
+ id: 42,
+ isDestroyed: () => false,
+ getType: () => "webview",
+ getURL: () => "https://example.com",
+ getTitle: () => "Example",
+ isLoading: () => false,
+ isDevToolsOpened: () => false,
+ getZoomFactor: () => 1,
+ setZoomFactor: vi.fn(),
+ on: vi.fn(),
+ off: vi.fn(),
+ ipc: { on: vi.fn(), off: vi.fn() },
+ send: webviewSend,
+ navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+ setWindowOpenHandler: vi.fn(),
+ debugger: {
+ isAttached: () => false,
+ attach: vi.fn(),
+ sendCommand,
+ on: vi.fn(
+ (
+ event: string,
+ listener: (event: unknown, method: string, params: Record<string, unknown>) => void,
+ ) => {
+ if (event === "message") debuggerMessage = listener;
+ },
+ ),
+ off: vi.fn(),
+ },
+ capturePage,
+ } as never);
+ const recordingFrames: DesktopPreviewRecordingFrame[] = [];
+
+ yield* manager.subscribeRecordingFrames((frame) =>
+ Effect.sync(() => {
+ recordingFrames.push(frame);
+ }),
+ );
+ yield* manager.createTab("tab_screencast_guard");
+ yield* manager.registerWebview("tab_screencast_guard", 42);
+ yield* manager.automationEvaluate("tab_screencast_guard", { expression: "null" });
+
+ debuggerMessage?.({}, "Page.screencastFrame", {
+ sessionId: 1,
+ data: "inactive-frame",
+ metadata: { deviceWidth: 1280, deviceHeight: 720 },
+ });
+ yield* Effect.yieldNow;
+ expect(recordingFrames).toHaveLength(0);
+
+ yield* manager.startRecording("tab_screencast_guard");
+ recordingFrames.length = 0;
+ debuggerMessage?.({}, "Page.screencastFrame", {
+ sessionId: 2,
+ data: "active-frame",
+ metadata: { deviceWidth: 1280, deviceHeight: 720 },
+ });
+ yield* Effect.yieldNow;
+
+ expect(recordingFrames).toEqual([
+ expect.objectContaining({
+ tabId: "tab_screencast_guard",
+ data: "active-frame",
+ width: 1280,
+ height: 720,
+ }),
+ ]);
+ yield* manager.stopRecording("tab_screencast_guard");
+ }),
+ ),
+ );
+
effectIt.effect("shares background frame capture between recording and picture-in-picture", () =>
withManager((manager) =>
Effect.gen(function* () {
diff --git a/apps/desktop/src/preview/Manager.ts b/apps/desktop/src/preview/Manager.ts
index 4321cf9dc..d7e8376ce 100644
--- a/apps/desktop/src/preview/Manager.ts
+++ b/apps/desktop/src/preview/Manager.ts
@@ -671,10 +671,17 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
),
);
+ const tabIdForWebContents = Effect.fnUntraced(function* (webContentsId: number) {
+ const tabs = yield* SynchronizedRef.get(tabsRef);
+ return (
+ Array.from(tabs.entries()).find(([, tab]) => tab.webContentsId === webContentsId)?.[0] ?? null
+ );
+ });
+
const pushBounded = <A>(buffer: ReadonlyArray<A>, entry: A): ReadonlyArray<A> =>
[...buffer, entry].slice(-DIAGNOSTIC_BUFFER_LIMIT);
- const captureDiagnosticMessage = Effect.fn("PreviewManager.captureDiagnosticMessage")(function* (
+ const captureDiagnosticMessage = Effect.fnUntraced(function* (
webContentsId: number,
method: string,
params: Record<string, unknown>,
@@ -852,11 +859,53 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
const createControlSession = Effect.fn("PreviewManager.createControlSession")(function* () {
const semaphore = yield* Semaphore.make(1);
const scope = yield* Scope.fork(parentScope, "sequential");
- const handleDebuggerMessage = Effect.fn("PreviewManager.handleDebuggerMessage")(
- function* (method: string, params: Record<string, unknown>) {
- yield* captureDiagnosticMessage(wc.id, method, params);
- },
- );
+ const handleDebuggerMessage = Effect.fnUntraced(function* (
+ method: string,
+ params: Record<string, unknown>,
+ ) {
+ if (method === "Page.screencastFrame") {
+ const sessionId = params["sessionId"];
+ if (typeof sessionId === "number") {
+ yield* attemptPromise(
+ {
+ operation: "ackScreencastFrame",
+ webContentsId: wc.id,
+ },
+ () => wc.debugger.sendCommand("Page.screencastFrameAck", { sessionId }),
+ ).pipe(Effect.ignore);
+ }
+ const tabId = yield* tabIdForWebContents(wc.id);
+ const metadata =
+ typeof params["metadata"] === "object" && params["metadata"] !== null
+ ? (params["metadata"] as Record<string, unknown>)
+ : {};
+ if (tabId && typeof params["data"] === "string") {
+ const captureSession = (yield* SynchronizedRef.get(frameCaptureSessionsRef)).get(
+ tabId,
+ );
+ if (captureSession?.consumers.has("recording")) {
+ const receivedAt = yield* currentIso;
+ const listeners = yield* Ref.get(recordingFrameListenersRef);
+ const frame: DesktopPreviewRecordingFrame = {
+ tabId,
+ data: params["data"],
+ width:
+ typeof metadata["deviceWidth"] === "number" ? metadata["deviceWidth"] : 0,
+ height:
+ typeof metadata["deviceHeight"] === "number" ? metadata["deviceHeight"] : 0,
+ receivedAt,
+ };
+ yield* Effect.forEach(
+ listeners,
+ (listener) =>
+ deliverEvent("recording-frame", frame.tabId, () => listener(frame)),
+ { discard: true },
+ );
+ }
+ }
+ }
+ yield* captureDiagnosticMessage(wc.id, method, params);
+ });
const onMessage: BrowserControlSession["onMessage"] = (_event, method, params) => {
runFork(handleDebuggerMessage(method, params));
};
diff --git a/apps/desktop/src/telemetry/DesktopTelemetryPublisher.test.ts b/apps/desktop/src/telemetry/DesktopTelemetryPublisher.test.ts
new file mode 100644
index 000000000..475be3da1
--- /dev/null
+++ b/apps/desktop/src/telemetry/DesktopTelemetryPublisher.test.ts
@@ -0,0 +1,388 @@
+import { DesktopHostTelemetryMessage } from "@t3tools/contracts";
+import { assert, describe, it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
+
+import type * as Electron from "electron";
+
+import * as ElectronApp from "../electron/ElectronApp.ts";
+import * as ElectronPowerMonitor from "../electron/ElectronPowerMonitor.ts";
+import * as DesktopTelemetryPublisher from "./DesktopTelemetryPublisher.ts";
+
+function makeElectronAppLayer(
+ metrics: ReadonlyArray<Electron.ProcessMetric>,
+ onMetricsRead: () => void = () => undefined,
+) {
+ return Layer.succeed(ElectronApp.ElectronApp, {
+ metadata: Effect.die("unexpected metadata read"),
+ name: Effect.succeed("T3 Code"),
+ whenReady: Effect.void,
+ quit: Effect.void,
+ exit: () => Effect.void,
+ relaunch: () => Effect.void,
+ setPath: () => Effect.void,
+ setName: () => Effect.void,
+ setAboutPanelOptions: () => Effect.void,
+ setAppUserModelId: () => Effect.void,
+ requestSingleInstanceLock: Effect.succeed(true),
+ getAppMetrics: Effect.sync(() => {
+ onMetricsRead();
+ return metrics;
+ }),
+ isDefaultProtocolClient: () => Effect.succeed(false),
+ setAsDefaultProtocolClient: () => Effect.succeed(true),
+ setDesktopName: () => Effect.void,
+ setDockIcon: () => Effect.void,
+ appendCommandLineSwitch: () => Effect.void,
+ onBeforeQuitForUpdate: () => Effect.void,
+ on: () => Effect.void,
+ } satisfies ElectronApp.ElectronApp["Service"]);
+}
+
+describe("DesktopTelemetryPublisher", () => {
+ it.effect("stops when its scope closes during an Electron telemetry sample", () =>
+ Effect.gen(function* () {
+ const pollStarted = yield* Deferred.make<void>();
+ const blockPoll = yield* Deferred.make<void>();
+ const powerLayer = Layer.succeed(
+ ElectronPowerMonitor.ElectronPowerMonitor,
+ ElectronPowerMonitor.ElectronPowerMonitor.of({
+ isOnBatteryPower: Effect.succeed(false),
+ getSystemIdleTime: Deferred.succeed(pollStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(blockPoll)),
+ Effect.as(0),
+ ),
+ getSystemIdleState: () => Effect.succeed("active"),
+ getCurrentThermalState: Effect.succeed("nominal"),
+ onSimpleEvent: () => Effect.void,
+ onThermalStateChange: () => Effect.void,
+ onSpeedLimitChange: () => Effect.void,
+ }),
+ );
+ const layer = DesktopTelemetryPublisher.layer.pipe(
+ Layer.provide(Layer.mergeAll(makeElectronAppLayer([]), powerLayer)),
+ );
+ const scope = yield* Scope.make();
+
+ yield* Layer.buildWithScope(layer, scope);
+ yield* Deferred.await(pollStarted);
+
+ const closeFiber = yield* Scope.close(scope, Exit.void).pipe(Effect.forkDetach);
+ yield* Effect.yieldNow;
+ yield* Effect.yieldNow;
+
+ assert.isDefined(closeFiber.pollUnsafe());
+ }),
+ );
+
+ it.effect("publishes Electron metrics and event-driven power state over NDJSON", () =>
+ Effect.gen(function* () {
+ const onBattery = yield* Ref.make(false);
+ const systemIdleState = yield* Ref.make<ElectronPowerMonitor.ElectronIdleState>("active");
+ let beforeSystemIdleState: Effect.Effect<void> = Effect.void;
+ let metricsReadCount = 0;
+ const simpleListeners = new Map<string, () => void>();
+ let thermalListener: ((state: ElectronPowerMonitor.ElectronThermalState) => void) | null =
+ null;
+ let speedLimitListener: ((limit: number) => void) | null = null;
+ const metrics = [
+ {
+ pid: 4_242,
+ type: "Browser",
+ creationTime: 1_000.75,
+ name: "electron",
+ cpu: {
+ percentCPUUsage: 12.5,
+ cumulativeCPUUsage: 3.25,
+ idleWakeupsPerSecond: 7,
+ },
+ memory: {
+ workingSetSize: 2_048,
+ peakWorkingSetSize: 4_096,
+ },
+ } as Electron.ProcessMetric,
+ ];
+ const powerLayer = Layer.succeed(
+ ElectronPowerMonitor.ElectronPowerMonitor,
+ ElectronPowerMonitor.ElectronPowerMonitor.of({
+ isOnBatteryPower: Ref.get(onBattery),
+ getSystemIdleTime: Effect.succeed(5),
+ getSystemIdleState: () =>
+ beforeSystemIdleState.pipe(Effect.andThen(Ref.get(systemIdleState))),
+ getCurrentThermalState: Effect.succeed("nominal"),
+ onSimpleEvent: (eventName, listener) =>
+ Effect.sync(() => {
+ simpleListeners.set(eventName, listener);
+ }),
+ onThermalStateChange: (listener) =>
+ Effect.sync(() => {
+ thermalListener = listener;
+ }),
+ onSpeedLimitChange: (listener) =>
+ Effect.sync(() => {
+ speedLimitListener = listener;
+ }),
+ }),
+ );
+ const layer = DesktopTelemetryPublisher.layer.pipe(
+ Layer.provide(
+ Layer.mergeAll(
+ makeElectronAppLayer(metrics, () => {
+ metricsReadCount += 1;
+ }),
+ powerLayer,
+ ),
+ ),
+ );
+
+ yield* Effect.gen(function* () {
+ const publisher = yield* DesktopTelemetryPublisher.DesktopTelemetryPublisher;
+ const encoded = yield* publisher.encoded.pipe(Stream.take(2), Stream.runCollect);
+ const decoder = new TextDecoder();
+ const decodeMessage = Schema.decodeUnknownEffect(
+ Schema.fromJsonString(DesktopHostTelemetryMessage),
+ );
+ const messages = yield* Effect.forEach(encoded, (bytes) =>
+ decodeMessage(decoder.decode(bytes).trim()),
+ );
+
+ assert.equal(messages[0]?.type, "desktopTelemetryHello");
+ assert.equal(messages[0]?.electronPid, process.pid);
+ const initialSnapshot = messages[1];
+ if (initialSnapshot?.type !== "desktopTelemetry") {
+ return assert.fail("Expected the second telemetry message to be a snapshot.");
+ }
+ assert.deepEqual(initialSnapshot.electronProcesses, []);
+ assert.equal(initialSnapshot.electronPid, process.pid);
+ assert.equal(metricsReadCount, 0);
+
+ const nextSnapshotFiber = yield* Stream.runHead(publisher.changes).pipe(Effect.forkChild);
+ yield* Effect.yieldNow;
+ yield* publisher.handleControl({
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled: true,
+ });
+ const demandedSnapshot = Option.getOrThrow(yield* Fiber.join(nextSnapshotFiber));
+ assert.equal(demandedSnapshot.electronProcesses[0]?.pid, 4_242);
+ assert.equal(demandedSnapshot.electronProcesses[0]?.creationTimeMs, 1_001);
+ assert.equal(demandedSnapshot.electronProcesses[0]?.cpuPercent, 12.5);
+ assert.equal(demandedSnapshot.electronProcesses[0]?.workingSetBytes, 2_048 * 1_024);
+ assert.equal(metricsReadCount, 1);
+ yield* publisher.handleControlForSource("secondary-backend", {
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled: true,
+ });
+ yield* publisher.handleControl({
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled: false,
+ });
+ yield* publisher.handleControlForSource("old-backend", {
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled: true,
+ });
+ yield* publisher.handleControlForSource("secondary-backend", {
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled: false,
+ });
+ yield* Effect.all(
+ [
+ publisher.removeControlSource("old-backend"),
+ publisher.handleControlForSource("replacement-backend", {
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled: true,
+ }),
+ ],
+ { concurrency: "unbounded", discard: true },
+ );
+
+ const batterySnapshotFiber = yield* Stream.runHead(publisher.changes).pipe(
+ Effect.forkChild,
+ );
+ yield* Effect.yieldNow;
+ simpleListeners.get("on-battery")?.();
+ const batterySnapshot = Option.getOrThrow(yield* Fiber.join(batterySnapshotFiber));
+ assert.equal(batterySnapshot.power.onBattery, "true");
+ yield* Ref.set(onBattery, true);
+
+ const metricsAfterBatteryEvent = metricsReadCount;
+ yield* TestClock.adjust(Duration.millis(4_999));
+ assert.equal(metricsReadCount, metricsAfterBatteryEvent);
+ yield* TestClock.adjust(Duration.millis(1));
+ assert.equal(metricsReadCount, metricsAfterBatteryEvent + 1);
+ assert.equal((yield* publisher.latest).pipe(Option.getOrThrow).power.onBattery, "true");
+
+ yield* Ref.set(onBattery, false);
+ const metricsBeforePolledAc = metricsReadCount;
+ yield* TestClock.adjust(Duration.seconds(5));
+ assert.equal(metricsReadCount, metricsBeforePolledAc + 1);
+ assert.equal((yield* publisher.latest).pipe(Option.getOrThrow).power.onBattery, "false");
+ yield* TestClock.adjust(Duration.seconds(1));
+ assert.equal(metricsReadCount, metricsBeforePolledAc + 2);
+
+ const suspendedSnapshotFiber = yield* Stream.runHead(publisher.changes).pipe(
+ Effect.forkChild,
+ );
+ yield* Effect.yieldNow;
+ simpleListeners.get("suspend")?.();
+ const suspendedSnapshot = Option.getOrThrow(yield* Fiber.join(suspendedSnapshotFiber));
+ assert.isTrue(suspendedSnapshot.power.suspended);
+
+ const constrainedSnapshotFiber = yield* Stream.runHead(publisher.changes).pipe(
+ Effect.forkChild,
+ );
+ yield* Effect.yieldNow;
+ thermalListener?.("serious");
+ const constrainedSnapshot = Option.getOrThrow(yield* Fiber.join(constrainedSnapshotFiber));
+ assert.equal(constrainedSnapshot.power.thermalState, "serious");
+ assert.isTrue(constrainedSnapshot.power.suspended);
+
+ const metricsAfterThermalEvent = metricsReadCount;
+ const recoveredSnapshotFiber = yield* Stream.runHead(publisher.changes).pipe(
+ Effect.forkChild,
+ );
+ yield* TestClock.adjust(Duration.millis(14_999));
+ assert.equal(metricsReadCount, metricsAfterThermalEvent);
+ yield* TestClock.adjust(Duration.millis(1));
+ assert.equal(metricsReadCount, metricsAfterThermalEvent + 1);
+ const recoveredSnapshot = Option.getOrThrow(yield* Fiber.join(recoveredSnapshotFiber));
+ assert.isFalse(recoveredSnapshot.power.suspended);
+
+ const speedLimitSnapshotFiber = yield* Stream.runHead(publisher.changes).pipe(
+ Effect.forkChild,
+ );
+ yield* Effect.yieldNow;
+ speedLimitListener?.(65);
+ const speedLimitSnapshot = Option.getOrThrow(yield* Fiber.join(speedLimitSnapshotFiber));
+ assert.equal(Option.getOrNull(speedLimitSnapshot.speedLimitPercent), 65);
+
+ const encodedSpeedLimit = yield* publisher.encoded.pipe(Stream.take(2), Stream.runCollect);
+ const decodedSpeedLimit = yield* decodeMessage(decoder.decode(encodedSpeedLimit[1]).trim());
+ if (decodedSpeedLimit.type !== "desktopTelemetry") {
+ return assert.fail("Expected the encoded telemetry message to be a snapshot.");
+ }
+ assert.equal(Option.getOrNull(decodedSpeedLimit.speedLimitPercent), 65);
+ assert.equal(decodedSpeedLimit.electronProcesses[0]?.pid, 4_242);
+ assert.equal(decodedSpeedLimit.electronProcesses[0]?.creationTimeMs, 1_001);
+
+ const metricsBeforeSecondaryOnlySample = metricsReadCount;
+ yield* TestClock.adjust(Duration.seconds(15));
+ assert.equal(metricsReadCount, metricsBeforeSecondaryOnlySample + 1);
+ assert.equal(
+ (yield* publisher.latest).pipe(Option.getOrThrow).electronProcesses[0]?.pid,
+ 4_242,
+ );
+
+ const stoppedSnapshotFiber = yield* Stream.runHead(publisher.changes).pipe(
+ Effect.forkChild,
+ );
+ yield* Effect.yieldNow;
+ yield* publisher.handleControlForSource("replacement-backend", {
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled: false,
+ });
+ const stoppedSnapshot = Option.getOrThrow(yield* Fiber.join(stoppedSnapshotFiber));
+ assert.deepEqual(stoppedSnapshot.electronProcesses, []);
+ const metricsAfterStopping = metricsReadCount;
+ const configuredSnapshotFiber = yield* Stream.runHead(publisher.changes).pipe(
+ Effect.forkChild,
+ );
+ yield* Effect.yieldNow;
+ yield* publisher.handleControl({
+ version: 1,
+ type: "setHostPowerIntervals",
+ activeIntervalMs: 7_000,
+ idleIntervalMs: 11_000,
+ });
+ const configuredSequence = Option.getOrThrow(
+ yield* Fiber.join(configuredSnapshotFiber),
+ ).sequence;
+
+ yield* TestClock.adjust(Duration.millis(6_999));
+ assert.equal(
+ (yield* publisher.latest).pipe(Option.getOrThrow).sequence,
+ configuredSequence,
+ );
+ assert.equal(metricsReadCount, metricsAfterStopping);
+ yield* TestClock.adjust(Duration.millis(1));
+ assert.equal(
+ (yield* publisher.latest).pipe(Option.getOrThrow).sequence,
+ configuredSequence + 1,
+ );
+ assert.equal(metricsReadCount, metricsAfterStopping);
+
+ yield* Ref.set(systemIdleState, "locked");
+ yield* TestClock.adjust(Duration.seconds(7));
+ const lockedSequence = (yield* publisher.latest).pipe(Option.getOrThrow).sequence;
+ assert.equal((yield* publisher.latest).pipe(Option.getOrThrow).power.locked, "true");
+ yield* TestClock.adjust(Duration.millis(10_999));
+ assert.equal((yield* publisher.latest).pipe(Option.getOrThrow).sequence, lockedSequence);
+ yield* TestClock.adjust(Duration.millis(1));
+ assert.equal(
+ (yield* publisher.latest).pipe(Option.getOrThrow).sequence,
+ lockedSequence + 1,
+ );
+
+ yield* Ref.set(systemIdleState, "active");
+ yield* TestClock.adjust(Duration.seconds(11));
+ const unlockedSnapshot = (yield* publisher.latest).pipe(Option.getOrThrow);
+ assert.equal(unlockedSnapshot.power.locked, "false");
+ assert.equal(unlockedSnapshot.power.idle, "false");
+
+ yield* TestClock.adjust(Duration.millis(6_999));
+ assert.equal(
+ (yield* publisher.latest).pipe(Option.getOrThrow).sequence,
+ unlockedSnapshot.sequence,
+ );
+ yield* TestClock.adjust(Duration.millis(1));
+ assert.equal(
+ (yield* publisher.latest).pipe(Option.getOrThrow).sequence,
+ unlockedSnapshot.sequence + 1,
+ );
+
+ const pollStarted = yield* Deferred.make<void>();
+ const releasePoll = yield* Deferred.make<void>();
+ beforeSystemIdleState = Deferred.succeed(pollStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(releasePoll)),
+ );
+ const concurrentEventSnapshotFiber = yield* Stream.runHead(publisher.changes).pipe(
+ Effect.forkChild,
+ );
+ yield* Effect.yieldNow;
+ yield* publisher.handleControl({
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled: true,
+ });
+ yield* Deferred.await(pollStarted);
+ simpleListeners.get("lock-screen")?.();
+ thermalListener?.("critical");
+ yield* Effect.yieldNow;
+ yield* Effect.yieldNow;
+ yield* Deferred.succeed(releasePoll, undefined);
+
+ const concurrentEventSnapshot = Option.getOrThrow(
+ yield* Fiber.join(concurrentEventSnapshotFiber),
+ );
+ assert.equal(concurrentEventSnapshot.power.locked, "true");
+ assert.equal(concurrentEventSnapshot.power.thermalState, "critical");
+ }).pipe(Effect.provide(layer));
+ }),
+ );
+});
diff --git a/apps/desktop/src/telemetry/DesktopTelemetryPublisher.ts b/apps/desktop/src/telemetry/DesktopTelemetryPublisher.ts
new file mode 100644
index 000000000..9c17ae514
--- /dev/null
+++ b/apps/desktop/src/telemetry/DesktopTelemetryPublisher.ts
@@ -0,0 +1,379 @@
+import {
+ DesktopHostTelemetryMessage,
+ type DesktopHostTelemetrySnapshot,
+ type DesktopTelemetryControlMessage,
+ type HostPowerSnapshot,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+
+import * as ElectronApp from "../electron/ElectronApp.ts";
+import * as ElectronPowerMonitor from "../electron/ElectronPowerMonitor.ts";
+
+const LIVE_SAMPLE_INTERVAL = Duration.seconds(1);
+const BATTERY_SAMPLE_INTERVAL = Duration.seconds(5);
+const CONSTRAINED_SAMPLE_INTERVAL = Duration.seconds(15);
+const DEFAULT_HOST_POWER_ACTIVE_INTERVAL = Duration.seconds(30);
+const DEFAULT_HOST_POWER_IDLE_INTERVAL = Duration.minutes(2);
+const IDLE_THRESHOLD_SECONDS = 60;
+const encodeMessage = Schema.encodeSync(Schema.fromJsonString(DesktopHostTelemetryMessage));
+const textEncoder = new TextEncoder();
+
+type PowerEvent =
+ | { readonly type: "locked"; readonly value: boolean }
+ | { readonly type: "suspended"; readonly value: boolean }
+ | { readonly type: "onBattery"; readonly value: boolean }
+ | { readonly type: "thermal"; readonly value: HostPowerSnapshot["thermalState"] }
+ | { readonly type: "speedLimit"; readonly value: number };
+
+interface PowerState {
+ readonly idle: HostPowerSnapshot["idle"];
+ readonly locked: HostPowerSnapshot["locked"];
+ readonly lockedEventPending: boolean;
+ readonly suspended: boolean;
+ readonly suspendedEventPending: boolean;
+ readonly onBattery: HostPowerSnapshot["onBattery"];
+ readonly onBatteryEventPending: boolean;
+ readonly thermalState: HostPowerSnapshot["thermalState"];
+ readonly speedLimitPercent: Option.Option<number>;
+}
+
+interface HostPowerIntervals {
+ readonly active: Duration.Duration;
+ readonly idle: Duration.Duration;
+}
+
+export class DesktopTelemetryPublisher extends Context.Service<
+ DesktopTelemetryPublisher,
+ {
+ readonly latest: Effect.Effect<Option.Option<DesktopHostTelemetrySnapshot>>;
+ readonly changes: Stream.Stream<DesktopHostTelemetrySnapshot>;
+ readonly encoded: Stream.Stream<Uint8Array>;
+ readonly handleControl: (message: DesktopTelemetryControlMessage) => Effect.Effect<void>;
+ readonly handleControlForSource: (
+ sourceId: string,
+ message: DesktopTelemetryControlMessage,
+ ) => Effect.Effect<void>;
+ readonly removeControlSource: (sourceId: string) => Effect.Effect<void>;
+ }
+>()("@t3tools/desktop/telemetry/DesktopTelemetryPublisher") {}
+
+function booleanState(value: boolean): HostPowerSnapshot["onBattery"] {
+ return value ? "true" : "false";
+}
+
+function idleState(value: ElectronPowerMonitor.ElectronIdleState): HostPowerSnapshot["idle"] {
+ switch (value) {
+ case "active":
+ return "false";
+ case "idle":
+ case "locked":
+ return "true";
+ case "unknown":
+ return "unknown";
+ }
+}
+
+function updatePowerState(state: PowerState, event: PowerEvent): PowerState {
+ switch (event.type) {
+ case "locked":
+ return {
+ ...state,
+ locked: booleanState(event.value),
+ lockedEventPending: true,
+ };
+ case "suspended":
+ return {
+ ...state,
+ suspended: event.value,
+ suspendedEventPending: event.value,
+ };
+ case "onBattery":
+ return {
+ ...state,
+ onBattery: booleanState(event.value),
+ onBatteryEventPending: true,
+ };
+ case "thermal":
+ return { ...state, thermalState: event.value };
+ case "speedLimit":
+ return { ...state, speedLimitPercent: Option.some(event.value) };
+ }
+}
+
+function sampleInterval(
+ power: PowerState,
+ diagnosticsDemand: boolean,
+ hostPowerIntervals: HostPowerIntervals,
+): Duration.Duration {
+ if (!diagnosticsDemand) {
+ return power.suspended || power.locked === "true" || power.idle === "true"
+ ? hostPowerIntervals.idle
+ : hostPowerIntervals.active;
+ }
+ if (
+ power.suspended ||
+ power.locked === "true" ||
+ power.thermalState === "serious" ||
+ power.thermalState === "critical"
+ ) {
+ return CONSTRAINED_SAMPLE_INTERVAL;
+ }
+ if (power.onBattery === "true") return BATTERY_SAMPLE_INTERVAL;
+ return LIVE_SAMPLE_INTERVAL;
+}
+
+export const make = Effect.fn("desktop.telemetryPublisher.make")(function* () {
+ const electronApp = yield* ElectronApp.ElectronApp;
+ const powerMonitor = yield* ElectronPowerMonitor.ElectronPowerMonitor;
+ yield* electronApp.whenReady;
+
+ const initialPowerState: PowerState = {
+ idle: "unknown",
+ locked: "unknown",
+ lockedEventPending: false,
+ suspended: false,
+ suspendedEventPending: false,
+ onBattery: booleanState(yield* powerMonitor.isOnBatteryPower),
+ onBatteryEventPending: false,
+ thermalState: yield* powerMonitor.getCurrentThermalState,
+ speedLimitPercent: Option.none(),
+ };
+ const powerState = yield* Ref.make(initialPowerState);
+ const hostPowerIntervals = yield* Ref.make<HostPowerIntervals>({
+ active: DEFAULT_HOST_POWER_ACTIVE_INTERVAL,
+ idle: DEFAULT_HOST_POWER_IDLE_INTERVAL,
+ });
+ const powerEvents = yield* Queue.unbounded<PowerEvent>();
+ const sampleTriggers = yield* Queue.sliding<void>(1);
+ const diagnosticsDemandSources = yield* Ref.make<ReadonlySet<string>>(new Set());
+ const latest = yield* Ref.make(Option.none<DesktopHostTelemetrySnapshot>());
+ const changes = yield* PubSub.sliding<DesktopHostTelemetrySnapshot>(8);
+ const sequence = yield* Ref.make(0);
+
+ const offer = (event: PowerEvent): void => {
+ Queue.offerUnsafe(powerEvents, event);
+ };
+ yield* Effect.all(
+ [
+ powerMonitor.onSimpleEvent("lock-screen", () => offer({ type: "locked", value: true })),
+ powerMonitor.onSimpleEvent("unlock-screen", () => offer({ type: "locked", value: false })),
+ powerMonitor.onSimpleEvent("suspend", () => offer({ type: "suspended", value: true })),
+ powerMonitor.onSimpleEvent("resume", () => offer({ type: "suspended", value: false })),
+ powerMonitor.onSimpleEvent("on-battery", () => offer({ type: "onBattery", value: true })),
+ powerMonitor.onSimpleEvent("on-ac", () => offer({ type: "onBattery", value: false })),
+ powerMonitor.onThermalStateChange((value) => offer({ type: "thermal", value })),
+ powerMonitor.onSpeedLimitChange((value) => offer({ type: "speedLimit", value })),
+ ],
+ { concurrency: "unbounded" },
+ );
+ yield* Effect.forever(
+ Queue.take(powerEvents).pipe(
+ Effect.flatMap((event) => Ref.update(powerState, (state) => updatePowerState(state, event))),
+ Effect.andThen(Queue.offer(sampleTriggers, undefined)),
+ ),
+ ).pipe(Effect.forkScoped);
+
+ const sampleOnce = (allowSuspendRecovery: boolean) =>
+ Effect.gen(function* () {
+ const sampledAt = yield* DateTime.now;
+ const sampledAtUnixMs = DateTime.toEpochMillis(sampledAt);
+ const demand = (yield* Ref.get(diagnosticsDemandSources)).size > 0;
+ const [currentPower, idleSeconds, systemIdleState, onBattery, metrics] = yield* Effect.all(
+ [
+ Ref.get(powerState),
+ powerMonitor.getSystemIdleTime,
+ powerMonitor.getSystemIdleState(IDLE_THRESHOLD_SECONDS),
+ powerMonitor.isOnBatteryPower,
+ demand ? electronApp.getAppMetrics : Effect.succeed([]),
+ ],
+ { concurrency: "unbounded" },
+ );
+ const polledLocked =
+ systemIdleState === "unknown"
+ ? currentPower.locked
+ : booleanState(systemIdleState === "locked");
+ const polledOnBattery = booleanState(onBattery);
+ const observedPower = yield* Ref.modify(powerState, (latestPower) => {
+ const preserveEventLocked =
+ latestPower.lockedEventPending ||
+ latestPower.locked !== currentPower.locked ||
+ latestPower.lockedEventPending !== currentPower.lockedEventPending;
+ const preserveEventOnBattery =
+ latestPower.onBatteryEventPending ||
+ latestPower.onBattery !== currentPower.onBattery ||
+ latestPower.onBatteryEventPending !== currentPower.onBatteryEventPending;
+ const preserveEventSuspended =
+ latestPower.suspendedEventPending ||
+ latestPower.suspended !== currentPower.suspended ||
+ latestPower.suspendedEventPending !== currentPower.suspendedEventPending;
+ const next: PowerState = {
+ ...latestPower,
+ idle: idleState(systemIdleState),
+ locked: preserveEventLocked ? latestPower.locked : polledLocked,
+ lockedEventPending:
+ latestPower.lockedEventPending &&
+ (systemIdleState === "unknown" || polledLocked !== latestPower.locked),
+ suspended:
+ allowSuspendRecovery && !preserveEventSuspended ? false : latestPower.suspended,
+ suspendedEventPending: false,
+ onBattery: preserveEventOnBattery ? latestPower.onBattery : polledOnBattery,
+ onBatteryEventPending:
+ latestPower.onBatteryEventPending && polledOnBattery !== latestPower.onBattery,
+ };
+ return [next, next] as const;
+ });
+ const nextSequence = yield* Ref.modify(sequence, (current) => [current + 1, current + 1]);
+ const snapshot: DesktopHostTelemetrySnapshot = {
+ version: 1,
+ type: "desktopTelemetry",
+ sequence: nextSequence,
+ sampledAtUnixMs,
+ electronPid: process.pid,
+ power: {
+ source: "electron-main",
+ idle: observedPower.idle,
+ idleSeconds,
+ locked: observedPower.locked,
+ suspended: observedPower.suspended,
+ onBattery: observedPower.onBattery,
+ lowPowerMode: "unknown",
+ thermalState: observedPower.thermalState,
+ stale: false,
+ updatedAt: sampledAt,
+ },
+ speedLimitPercent: observedPower.speedLimitPercent,
+ electronProcesses: metrics.map((metric) => ({
+ pid: metric.pid,
+ creationTimeMs: Math.max(0, Math.round(metric.creationTime)),
+ type: metric.type,
+ ...(metric.name === undefined ? {} : { name: metric.name }),
+ ...(metric.serviceName === undefined ? {} : { serviceName: metric.serviceName }),
+ cpuPercent: metric.cpu.percentCPUUsage,
+ ...(metric.cpu.cumulativeCPUUsage === undefined
+ ? {}
+ : { cumulativeCpuSeconds: metric.cpu.cumulativeCPUUsage }),
+ idleWakeupsPerSecond: metric.cpu.idleWakeupsPerSecond,
+ workingSetBytes: Math.max(0, Math.round(metric.memory.workingSetSize * 1024)),
+ peakWorkingSetBytes: Math.max(0, Math.round(metric.memory.peakWorkingSetSize * 1024)),
+ })),
+ };
+
+ yield* Ref.set(latest, Option.some(snapshot));
+ yield* PubSub.publish(changes, snapshot);
+ }).pipe(
+ Effect.catchCause((cause) =>
+ Cause.hasInterrupts(cause)
+ ? Effect.failCause(cause)
+ : Effect.logWarning("Failed to sample Electron telemetry", {
+ cause: String(cause),
+ }),
+ ),
+ );
+
+ yield* Effect.gen(function* () {
+ yield* sampleOnce(false);
+ while (true) {
+ const [currentPower, demand, intervals] = yield* Effect.all([
+ Ref.get(powerState),
+ Ref.get(diagnosticsDemandSources).pipe(Effect.map((sources) => sources.size > 0)),
+ Ref.get(hostPowerIntervals),
+ ]);
+ const allowSuspendRecovery = yield* Effect.raceFirst(
+ Queue.take(sampleTriggers).pipe(Effect.as(false)),
+ Effect.sleep(sampleInterval(currentPower, demand, intervals)).pipe(Effect.as(true)),
+ );
+ yield* sampleOnce(allowSuspendRecovery);
+ }
+ }).pipe(Effect.forkScoped);
+
+ const handleControlForSource: DesktopTelemetryPublisher["Service"]["handleControlForSource"] = (
+ sourceId,
+ message,
+ ) => {
+ switch (message.type) {
+ case "setDiagnosticsDemand":
+ return Ref.modify(diagnosticsDemandSources, (sources) => {
+ const previous = sources.size > 0;
+ const next = new Set(sources);
+ if (message.enabled) {
+ next.add(sourceId);
+ } else {
+ next.delete(sourceId);
+ }
+ return [[previous, next.size > 0] as const, next] as const;
+ }).pipe(
+ Effect.flatMap(([previous, enabled]) =>
+ previous === enabled
+ ? Effect.void
+ : Queue.offer(sampleTriggers, undefined).pipe(Effect.asVoid),
+ ),
+ );
+ case "setHostPowerIntervals":
+ return Ref.set(hostPowerIntervals, {
+ active: Duration.millis(message.activeIntervalMs),
+ idle: Duration.millis(message.idleIntervalMs),
+ }).pipe(Effect.andThen(Queue.offer(sampleTriggers, undefined)), Effect.asVoid);
+ }
+ };
+ const removeControlSource: DesktopTelemetryPublisher["Service"]["removeControlSource"] = (
+ sourceId,
+ ) =>
+ Ref.modify(diagnosticsDemandSources, (sources) => {
+ const previous = sources.size > 0;
+ const next = new Set(sources);
+ next.delete(sourceId);
+ return [[previous, next.size > 0] as const, next] as const;
+ }).pipe(
+ Effect.flatMap(([previous, enabled]) =>
+ previous === enabled
+ ? Effect.void
+ : Queue.offer(sampleTriggers, undefined).pipe(Effect.asVoid),
+ ),
+ );
+ const handleControl: DesktopTelemetryPublisher["Service"]["handleControl"] = (message) =>
+ handleControlForSource("legacy", message);
+
+ const snapshots = Stream.unwrap(
+ Effect.gen(function* () {
+ const subscription = yield* PubSub.subscribe(changes);
+ const initial = yield* Ref.get(latest);
+ return Stream.concat(
+ Option.match(initial, {
+ onNone: () => Stream.empty,
+ onSome: Stream.make,
+ }),
+ Stream.fromSubscription(subscription),
+ );
+ }),
+ );
+ const encoded = Stream.concat(
+ Stream.make({
+ version: 1,
+ type: "desktopTelemetryHello",
+ electronPid: process.pid,
+ } as const),
+ snapshots,
+ ).pipe(Stream.map((message) => textEncoder.encode(`${encodeMessage(message)}\n`)));
+
+ return DesktopTelemetryPublisher.of({
+ latest: Ref.get(latest),
+ changes: Stream.fromPubSub(changes),
+ encoded,
+ handleControl,
+ handleControlForSource,
+ removeControlSource,
+ });
+});
+
+export const layer = Layer.effect(DesktopTelemetryPublisher, make());
diff --git a/apps/desktop/src/window/DesktopApplicationMenu.test.ts b/apps/desktop/src/window/DesktopApplicationMenu.test.ts
index 0d48ab04c..34fc44471 100644
--- a/apps/desktop/src/window/DesktopApplicationMenu.test.ts
+++ b/apps/desktop/src/window/DesktopApplicationMenu.test.ts
@@ -40,6 +40,7 @@ const electronAppLayer = Layer.succeed(ElectronApp.ElectronApp, {
setAboutPanelOptions: () => Effect.void,
setAppUserModelId: () => Effect.void,
requestSingleInstanceLock: Effect.succeed(true),
+ getAppMetrics: Effect.succeed([]),
isDefaultProtocolClient: () => Effect.succeed(false),
setAsDefaultProtocolClient: () => Effect.succeed(true),
setDesktopName: () => Effect.void,
diff --git a/apps/mobile/src/connection/background-activity-scopes.ts b/apps/mobile/src/connection/background-activity-scopes.ts
new file mode 100644
index 000000000..da013a572
--- /dev/null
+++ b/apps/mobile/src/connection/background-activity-scopes.ts
@@ -0,0 +1,92 @@
+import type { EnvironmentRpcSubscriptionObservation } from "@t3tools/client-runtime/rpc";
+import { type BackgroundScope, type EnvironmentId, WS_METHODS } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+
+interface RetainedScope {
+ readonly environmentId: EnvironmentId;
+ readonly scope: BackgroundScope;
+ refCount: number;
+}
+
+const retainedScopes = new Map<string, RetainedScope>();
+const listeners = new Set<() => void>();
+
+function notify(): void {
+ for (const listener of listeners) {
+ try {
+ listener();
+ } catch {
+ // A failing observer must not corrupt retained-scope lifetime.
+ }
+ }
+}
+
+function stableScopeKey(environmentId: EnvironmentId, scope: BackgroundScope): string {
+ switch (scope.type) {
+ case "server-config":
+ case "diagnostics":
+ return JSON.stringify([environmentId, scope.type]);
+ case "provider-status":
+ return JSON.stringify([environmentId, scope.type, scope.instanceId ?? null]);
+ case "vcs-status":
+ case "git-refs":
+ return JSON.stringify([environmentId, scope.type, scope.cwd]);
+ case "thread":
+ return JSON.stringify([environmentId, scope.type, scope.threadId]);
+ }
+}
+
+function scopeForSubscription(
+ observation: EnvironmentRpcSubscriptionObservation,
+): BackgroundScope | null {
+ if (observation.method === WS_METHODS.subscribeResourceTelemetry) {
+ return { type: "diagnostics" };
+ }
+ if (observation.method !== WS_METHODS.subscribeVcsStatus) {
+ return null;
+ }
+ const input = observation.input as { readonly cwd?: unknown };
+ return typeof input.cwd === "string" ? { type: "vcs-status", cwd: input.cwd } : null;
+}
+
+export function retainedMobileBackgroundScopes(
+ environmentId: EnvironmentId,
+): ReadonlyArray<BackgroundScope> {
+ return Array.from(retainedScopes.values(), (entry) =>
+ entry.environmentId === environmentId ? entry.scope : null,
+ ).filter((scope): scope is BackgroundScope => scope !== null);
+}
+
+export function observeMobileBackgroundActivitySubscription(
+ observation: EnvironmentRpcSubscriptionObservation,
+): Effect.Effect<Effect.Effect<void>> {
+ const scope = scopeForSubscription(observation);
+ if (scope === null) return Effect.succeed(Effect.void);
+ return Effect.sync(() => {
+ const environmentId = observation.environmentId as EnvironmentId;
+ const key = stableScopeKey(environmentId, scope);
+ const current = retainedScopes.get(key);
+ if (current) {
+ current.refCount += 1;
+ } else {
+ retainedScopes.set(key, { environmentId, scope, refCount: 1 });
+ notify();
+ }
+ return Effect.sync(() => {
+ const retained = retainedScopes.get(key);
+ if (!retained) return;
+ retained.refCount -= 1;
+ if (retained.refCount <= 0) {
+ retainedScopes.delete(key);
+ notify();
+ }
+ });
+ });
+}
+
+export function onRetainedMobileBackgroundScopesChange(listener: () => void): () => void {
+ listeners.add(listener);
+ return () => {
+ listeners.delete(listener);
+ };
+}
diff --git a/apps/mobile/src/connection/background-activity.test.ts b/apps/mobile/src/connection/background-activity.test.ts
new file mode 100644
index 000000000..7a2d90255
--- /dev/null
+++ b/apps/mobile/src/connection/background-activity.test.ts
@@ -0,0 +1,77 @@
+import { EnvironmentId, WS_METHODS } from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+
+import {
+ onRetainedMobileBackgroundScopesChange,
+ observeMobileBackgroundActivitySubscription,
+ retainedMobileBackgroundScopes,
+} from "./background-activity-scopes";
+
+describe("mobile background activity", () => {
+ it.effect("retains VCS demand only while the mobile subscription is active", () =>
+ Effect.gen(function* () {
+ const environmentId = EnvironmentId.make("mobile-environment");
+ const release = yield* observeMobileBackgroundActivitySubscription({
+ environmentId,
+ method: WS_METHODS.subscribeVcsStatus,
+ input: { cwd: "/workspace" },
+ });
+
+ expect(retainedMobileBackgroundScopes(environmentId)).toEqual([
+ { type: "vcs-status", cwd: "/workspace" },
+ ]);
+
+ yield* release;
+ expect(retainedMobileBackgroundScopes(environmentId)).toEqual([]);
+ }),
+ );
+
+ it.effect("keeps delimiter-containing environment and scope values distinct", () =>
+ Effect.gen(function* () {
+ const firstEnvironmentId = EnvironmentId.make("a");
+ const secondEnvironmentId = EnvironmentId.make("a:vcs-status:b");
+ const releaseFirst = yield* observeMobileBackgroundActivitySubscription({
+ environmentId: firstEnvironmentId,
+ method: WS_METHODS.subscribeVcsStatus,
+ input: { cwd: "b:vcs-status:c" },
+ });
+ const releaseSecond = yield* observeMobileBackgroundActivitySubscription({
+ environmentId: secondEnvironmentId,
+ method: WS_METHODS.subscribeVcsStatus,
+ input: { cwd: "c" },
+ });
+
+ expect(retainedMobileBackgroundScopes(firstEnvironmentId)).toEqual([
+ { type: "vcs-status", cwd: "b:vcs-status:c" },
+ ]);
+ expect(retainedMobileBackgroundScopes(secondEnvironmentId)).toEqual([
+ { type: "vcs-status", cwd: "c" },
+ ]);
+
+ yield* Effect.all([releaseFirst, releaseSecond]);
+ }),
+ );
+
+ it.effect("returns a release handle when a retained-scope listener throws", () =>
+ Effect.gen(function* () {
+ const environmentId = EnvironmentId.make("throwing-listener-environment");
+ const removeListener = onRetainedMobileBackgroundScopesChange(() => {
+ throw new Error("listener failed");
+ });
+
+ const release = yield* observeMobileBackgroundActivitySubscription({
+ environmentId,
+ method: WS_METHODS.subscribeVcsStatus,
+ input: { cwd: "/workspace" },
+ });
+ expect(retainedMobileBackgroundScopes(environmentId)).toEqual([
+ { type: "vcs-status", cwd: "/workspace" },
+ ]);
+
+ yield* release;
+ expect(retainedMobileBackgroundScopes(environmentId)).toEqual([]);
+ removeListener();
+ }),
+ );
+});
diff --git a/apps/mobile/src/connection/background-activity.ts b/apps/mobile/src/connection/background-activity.ts
new file mode 100644
index 000000000..3364eed3c
--- /dev/null
+++ b/apps/mobile/src/connection/background-activity.ts
@@ -0,0 +1,116 @@
+import { EnvironmentRegistry } from "@t3tools/client-runtime/connection";
+import { EnvironmentRpcSubscriptionObserver, request } from "@t3tools/client-runtime/rpc";
+import {
+ type BackgroundScope,
+ type ClientActivityReportInput,
+ type EnvironmentId,
+ WS_METHODS,
+} from "@t3tools/contracts";
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Queue from "effect/Queue";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import * as SubscriptionRef from "effect/SubscriptionRef";
+import { AppState, type AppStateStatus } from "react-native";
+
+import * as MobileStorage from "../persistence/mobile-storage";
+import {
+ observeMobileBackgroundActivitySubscription,
+ onRetainedMobileBackgroundScopesChange,
+ retainedMobileBackgroundScopes,
+} from "./background-activity-scopes";
+
+const REPORT_INTERVAL_MS = 25_000;
+const LEASE_TTL_MS = 45_000;
+const BASELINE_SCOPES: ReadonlyArray<BackgroundScope> = [{ type: "provider-status" }];
+
+function normalizeAppState(
+ state: AppStateStatus,
+): NonNullable<ClientActivityReportInput["appState"]> {
+ if (state === "active" || state === "inactive" || state === "background") return state;
+ return "unknown";
+}
+
+export const mobileBackgroundActivityObserverLayer = Layer.succeed(
+ EnvironmentRpcSubscriptionObserver,
+ EnvironmentRpcSubscriptionObserver.of({
+ observe: observeMobileBackgroundActivitySubscription,
+ }),
+);
+
+export const mobileBackgroundActivityReporterLayer = Layer.effectDiscard(
+ Effect.gen(function* () {
+ const registry = yield* EnvironmentRegistry;
+ const storage = yield* MobileStorage.MobileStorage;
+ const clientId = yield* storage.loadOrCreateAgentAwarenessDeviceId.pipe(
+ Effect.map((deviceId) => `mobile-${deviceId}`),
+ Effect.orElseSucceed(() => "ephemeral-mobile-client"),
+ );
+ const reportRequests = yield* Queue.sliding<void>(1);
+ const requestReport = () => Queue.offerUnsafe(reportRequests, undefined);
+ let appState = AppState.currentState;
+
+ const report = Effect.gen(function* () {
+ const observedAtMs = yield* Clock.currentTimeMillis;
+ const active = appState === "active";
+ const entries = yield* SubscriptionRef.get(registry.entries);
+ yield* Effect.forEach(
+ entries.keys(),
+ (environmentId) =>
+ registry
+ .run(
+ environmentId,
+ request(WS_METHODS.serverReportClientActivity, {
+ environmentId: environmentId as EnvironmentId,
+ clientId,
+ clientKind: "mobile",
+ visible: active,
+ focused: active,
+ recentlyInteracted: active,
+ appState: normalizeAppState(appState),
+ scopes: [
+ ...BASELINE_SCOPES,
+ ...retainedMobileBackgroundScopes(environmentId as EnvironmentId),
+ ],
+ ttlMs: LEASE_TTL_MS,
+ observedAt: DateTime.makeUnsafe(observedAtMs),
+ }),
+ )
+ .pipe(Effect.ignore),
+ { concurrency: "unbounded", discard: true },
+ );
+ }).pipe(Effect.withSpan("mobile.backgroundActivity.report"));
+
+ yield* Effect.acquireRelease(
+ Effect.sync(() => {
+ const removeScopeListener = onRetainedMobileBackgroundScopesChange(requestReport);
+ const subscription = AppState.addEventListener("change", (nextState) => {
+ appState = nextState;
+ requestReport();
+ });
+ return { removeScopeListener, subscription };
+ }),
+ ({ removeScopeListener, subscription }) =>
+ Effect.sync(() => {
+ removeScopeListener();
+ subscription.remove();
+ }),
+ );
+ yield* SubscriptionRef.changes(registry.entries).pipe(
+ Stream.runForEach(() => Effect.sync(requestReport)),
+ Effect.forkScoped,
+ );
+ yield* Stream.fromQueue(reportRequests).pipe(
+ Stream.debounce("250 millis"),
+ Stream.runForEach(() => report),
+ Effect.forkScoped,
+ );
+ yield* Effect.sync(requestReport).pipe(
+ Effect.repeat(Schedule.spaced(`${REPORT_INTERVAL_MS} millis`)),
+ Effect.forkScoped,
+ );
+ }),
+);
diff --git a/apps/mobile/src/connection/runtime.ts b/apps/mobile/src/connection/runtime.ts
index 3d4bf4944..b589c114b 100644
--- a/apps/mobile/src/connection/runtime.ts
+++ b/apps/mobile/src/connection/runtime.ts
@@ -5,6 +5,10 @@ import * as Layer from "effect/Layer";
import { Atom } from "effect/unstable/reactivity";
import { runtimeContextLayer } from "../lib/runtime";
+import {
+ mobileBackgroundActivityObserverLayer,
+ mobileBackgroundActivityReporterLayer,
+} from "./background-activity";
import { connectionPlatformLayer } from "./platform";
const providedConnectionPlatformLayer = connectionPlatformLayer.pipe(
@@ -17,10 +21,22 @@ type ConnectionLayerSource =
| typeof Connection.layer
| typeof snapshotLoaderLayer
| typeof runtimeContextLayer
- | typeof connectionPlatformLayer;
+ | typeof connectionPlatformLayer
+ | typeof mobileBackgroundActivityObserverLayer
+ | typeof mobileBackgroundActivityReporterLayer;
-const connectionLayer = Layer.merge(Connection.layer, snapshotLoaderLayer).pipe(
- Layer.provideMerge(Layer.mergeAll(runtimeContextLayer, providedConnectionPlatformLayer)),
+const providedClientConnectionLayer = Layer.merge(Connection.layer, snapshotLoaderLayer).pipe(
+ Layer.provideMerge(
+ Layer.mergeAll(
+ runtimeContextLayer,
+ providedConnectionPlatformLayer,
+ mobileBackgroundActivityObserverLayer,
+ ),
+ ),
+);
+
+const connectionLayer = mobileBackgroundActivityReporterLayer.pipe(
+ Layer.provideMerge(providedClientConnectionLayer),
);
export const connectionAtomRuntime: Atom.AtomRuntime<
diff --git a/apps/server/src/auth/RpcAuthorization.test.ts b/apps/server/src/auth/RpcAuthorization.test.ts
new file mode 100644
index 000000000..5aba97830
--- /dev/null
+++ b/apps/server/src/auth/RpcAuthorization.test.ts
@@ -0,0 +1,47 @@
+import {
+ AuthOrchestrationOperateScope,
+ AuthOrchestrationReadScope,
+ AuthRelayReadScope,
+ AuthRelayWriteScope,
+ WS_METHODS,
+ WsRpcGroup,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+
+import { RPC_REQUIRED_SCOPES, requiredScopeForRpcMethod } from "./RpcAuthorization.ts";
+
+describe("RPC authorization scopes", () => {
+ it("declares exactly one scope for every RPC in the server group", () => {
+ expect(new Set(Object.keys(RPC_REQUIRED_SCOPES))).toEqual(new Set(WsRpcGroup.requests.keys()));
+ });
+
+ it("authorizes background policy reporting and observation deliberately", () => {
+ expect(requiredScopeForRpcMethod(WS_METHODS.serverReportClientActivity)).toBe(
+ AuthOrchestrationReadScope,
+ );
+ expect(requiredScopeForRpcMethod(WS_METHODS.serverReportHostPowerState)).toBe(
+ AuthOrchestrationOperateScope,
+ );
+ expect(requiredScopeForRpcMethod(WS_METHODS.serverGetBackgroundPolicy)).toBe(
+ AuthOrchestrationReadScope,
+ );
+ expect(requiredScopeForRpcMethod(WS_METHODS.subscribeBackgroundPolicy)).toBe(
+ AuthOrchestrationReadScope,
+ );
+ });
+
+ it("allows relay status reads without granting relay installation access", () => {
+ expect(requiredScopeForRpcMethod(WS_METHODS.cloudGetRelayClientStatus)).toBe(
+ AuthRelayReadScope,
+ );
+ expect(requiredScopeForRpcMethod(WS_METHODS.cloudInstallRelayClient)).toBe(AuthRelayWriteScope);
+ });
+
+ it("rejects unknown RPC method names", () => {
+ for (const method of ["server.notRegistered", "toString", "constructor"]) {
+ expect(() => requiredScopeForRpcMethod(method)).toThrow(
+ `RPC method ${method} has no declared authorization scope.`,
+ );
+ }
+ });
+});
diff --git a/apps/server/src/auth/RpcAuthorization.ts b/apps/server/src/auth/RpcAuthorization.ts
new file mode 100644
index 000000000..5655f260b
--- /dev/null
+++ b/apps/server/src/auth/RpcAuthorization.ts
@@ -0,0 +1,111 @@
+import {
+ AuthAccessReadScope,
+ AuthOrchestrationOperateScope,
+ AuthOrchestrationReadScope,
+ AuthRelayReadScope,
+ AuthRelayWriteScope,
+ AuthReviewWriteScope,
+ AuthTerminalOperateScope,
+ ORCHESTRATION_WS_METHODS,
+ type AuthEnvironmentScope,
+ WS_METHODS,
+ WsRpcGroup,
+} from "@t3tools/contracts";
+import type * as RpcGroup from "effect/unstable/rpc/RpcGroup";
+
+type WsRpcMethod = RpcGroup.Rpcs<typeof WsRpcGroup>["_tag"];
+
+/**
+ * Keep authorization coverage coupled to the RPC group itself. Adding an RPC to
+ * `WsRpcGroup` without choosing a scope is a type error instead of a production
+ * runtime failure.
+ */
+export const RPC_REQUIRED_SCOPES = {
+ [ORCHESTRATION_WS_METHODS.dispatchCommand]: AuthOrchestrationOperateScope,
+ [ORCHESTRATION_WS_METHODS.getTurnDiff]: AuthOrchestrationReadScope,
+ [ORCHESTRATION_WS_METHODS.getFullThreadDiff]: AuthOrchestrationReadScope,
+ [ORCHESTRATION_WS_METHODS.subscribeShell]: AuthOrchestrationReadScope,
+ [ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot]: AuthOrchestrationReadScope,
+ [ORCHESTRATION_WS_METHODS.subscribeThread]: AuthOrchestrationReadScope,
+ [WS_METHODS.serverProbe]: AuthOrchestrationReadScope,
+ [WS_METHODS.serverGetConfig]: AuthOrchestrationReadScope,
+ [WS_METHODS.serverRefreshProviders]: AuthOrchestrationOperateScope,
+ [WS_METHODS.serverUpdateProvider]: AuthOrchestrationOperateScope,
+ [WS_METHODS.serverUpdateServer]: AuthOrchestrationOperateScope,
+ [WS_METHODS.serverUpsertKeybinding]: AuthOrchestrationOperateScope,
+ [WS_METHODS.serverRemoveKeybinding]: AuthOrchestrationOperateScope,
+ [WS_METHODS.serverGetSettings]: AuthOrchestrationReadScope,
+ [WS_METHODS.serverUpdateSettings]: AuthOrchestrationOperateScope,
+ [WS_METHODS.serverDiscoverSourceControl]: AuthOrchestrationReadScope,
+ [WS_METHODS.serverGetTraceDiagnostics]: AuthOrchestrationReadScope,
+ [WS_METHODS.serverGetProcessDiagnostics]: AuthOrchestrationReadScope,
+ [WS_METHODS.serverGetProcessResourceHistory]: AuthOrchestrationReadScope,
+ [WS_METHODS.serverGetResourceTelemetryHistory]: AuthOrchestrationReadScope,
+ [WS_METHODS.serverRetryResourceTelemetry]: AuthOrchestrationOperateScope,
+ [WS_METHODS.serverSignalProcess]: AuthOrchestrationOperateScope,
+ [WS_METHODS.serverReportClientActivity]: AuthOrchestrationReadScope,
+ [WS_METHODS.serverReportHostPowerState]: AuthOrchestrationOperateScope,
+ [WS_METHODS.serverGetBackgroundPolicy]: AuthOrchestrationReadScope,
+ [WS_METHODS.cloudGetRelayClientStatus]: AuthRelayReadScope,
+ [WS_METHODS.cloudInstallRelayClient]: AuthRelayWriteScope,
+ [WS_METHODS.sourceControlLookupRepository]: AuthOrchestrationReadScope,
+ [WS_METHODS.sourceControlCloneRepository]: AuthOrchestrationOperateScope,
+ [WS_METHODS.sourceControlPublishRepository]: AuthOrchestrationOperateScope,
+ [WS_METHODS.projectsListEntries]: AuthOrchestrationReadScope,
+ [WS_METHODS.projectsReadFile]: AuthOrchestrationReadScope,
+ [WS_METHODS.projectsSearchEntries]: AuthOrchestrationReadScope,
+ [WS_METHODS.projectsWriteFile]: AuthOrchestrationOperateScope,
+ [WS_METHODS.shellOpenInEditor]: AuthOrchestrationOperateScope,
+ [WS_METHODS.filesystemBrowse]: AuthOrchestrationReadScope,
+ [WS_METHODS.assetsCreateUrl]: AuthOrchestrationReadScope,
+ [WS_METHODS.subscribeVcsStatus]: AuthOrchestrationReadScope,
+ [WS_METHODS.subscribeResourceTelemetry]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsRefreshStatus]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsPull]: AuthOrchestrationOperateScope,
+ [WS_METHODS.gitRunStackedAction]: AuthOrchestrationOperateScope,
+ [WS_METHODS.gitResolvePullRequest]: AuthOrchestrationOperateScope,
+ [WS_METHODS.gitPreparePullRequestThread]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsListRefs]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsCreateWorktree]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsRemoveWorktree]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsCreateRef]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsSwitchRef]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsInit]: AuthOrchestrationOperateScope,
+ [WS_METHODS.reviewGetDiffPreview]: AuthReviewWriteScope,
+ [WS_METHODS.terminalOpen]: AuthTerminalOperateScope,
+ [WS_METHODS.terminalAttach]: AuthTerminalOperateScope,
+ [WS_METHODS.terminalWrite]: AuthTerminalOperateScope,
+ [WS_METHODS.terminalResize]: AuthTerminalOperateScope,
+ [WS_METHODS.terminalClear]: AuthTerminalOperateScope,
+ [WS_METHODS.terminalRestart]: AuthTerminalOperateScope,
+ [WS_METHODS.terminalClose]: AuthTerminalOperateScope,
+ [WS_METHODS.subscribeTerminalEvents]: AuthTerminalOperateScope,
+ [WS_METHODS.subscribeTerminalMetadata]: AuthTerminalOperateScope,
+ [WS_METHODS.previewOpen]: AuthOrchestrationOperateScope,
+ [WS_METHODS.previewNavigate]: AuthOrchestrationOperateScope,
+ [WS_METHODS.previewResize]: AuthOrchestrationOperateScope,
+ [WS_METHODS.previewRefresh]: AuthOrchestrationOperateScope,
+ [WS_METHODS.previewClose]: AuthOrchestrationOperateScope,
+ [WS_METHODS.previewList]: AuthOrchestrationReadScope,
+ [WS_METHODS.previewReportStatus]: AuthOrchestrationOperateScope,
+ [WS_METHODS.previewAutomationConnect]: AuthOrchestrationOperateScope,
+ [WS_METHODS.previewAutomationRespond]: AuthOrchestrationOperateScope,
+ [WS_METHODS.previewAutomationFocusHost]: AuthOrchestrationOperateScope,
+ [WS_METHODS.subscribePreviewEvents]: AuthOrchestrationReadScope,
+ [WS_METHODS.subscribeDiscoveredLocalServers]: AuthOrchestrationReadScope,
+ [WS_METHODS.subscribeServerConfig]: AuthOrchestrationReadScope,
+ [WS_METHODS.subscribeServerLifecycle]: AuthOrchestrationReadScope,
+ [WS_METHODS.subscribeAuthAccess]: AuthAccessReadScope,
+ [WS_METHODS.subscribeBackgroundPolicy]: AuthOrchestrationReadScope,
+} as const satisfies Readonly<Record<WsRpcMethod, AuthEnvironmentScope>>;
+
+export function requiredScopeForRpcMethod(method: string): AuthEnvironmentScope {
+ if (!Object.hasOwn(RPC_REQUIRED_SCOPES, method)) {
+ throw new Error(`RPC method ${method} has no declared authorization scope.`);
+ }
+ const requiredScope = RPC_REQUIRED_SCOPES[method as WsRpcMethod];
+ if (requiredScope === undefined) {
+ throw new Error(`RPC method ${method} has no declared authorization scope.`);
+ }
+ return requiredScope;
+}
diff --git a/apps/server/src/background/BackgroundPolicy.test.ts b/apps/server/src/background/BackgroundPolicy.test.ts
new file mode 100644
index 000000000..441a518d2
--- /dev/null
+++ b/apps/server/src/background/BackgroundPolicy.test.ts
@@ -0,0 +1,386 @@
+import { assert, describe, it } from "@effect/vitest";
+import {
+ AuthSessionId,
+ RpcClientId,
+ type HostPowerSnapshot,
+ type ClientActivityReportInput,
+} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
+
+import { ServerSettingsService } from "../serverSettings.ts";
+import * as BackgroundPolicy from "./BackgroundPolicy.ts";
+import * as HostPowerMonitor from "./HostPowerMonitor.ts";
+
+const TEST_NOW = DateTime.makeUnsafe("2026-05-13T00:00:00.000Z");
+
+const nominalHostPower: HostPowerSnapshot = {
+ source: "unknown",
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt: TEST_NOW,
+};
+
+const constrainedHostPower: HostPowerSnapshot = {
+ ...nominalHostPower,
+ lowPowerMode: "true",
+ stale: false,
+};
+
+function makeReport(overrides: Partial<ClientActivityReportInput> = {}): ClientActivityReportInput {
+ return {
+ clientId: "client-1",
+ clientKind: "web",
+ visible: true,
+ focused: true,
+ recentlyInteracted: true,
+ scopes: [{ type: "vcs-status", cwd: "/repo" }],
+ ttlMs: 45_000,
+ observedAt: TEST_NOW,
+ ...overrides,
+ };
+}
+
+function makeLayer(
+ hostPower: HostPowerSnapshot,
+ settingsOverrides: Parameters<typeof ServerSettingsService.layerTest>[0] = {},
+) {
+ const hostLayer = Layer.effect(
+ HostPowerMonitor.HostPowerMonitor,
+ Effect.gen(function* () {
+ const changes = yield* PubSub.sliding<HostPowerSnapshot>(1);
+ let snapshot = hostPower;
+ return HostPowerMonitor.HostPowerMonitor.of({
+ snapshot: Effect.sync(() => snapshot),
+ report: (next) =>
+ Effect.sync(() => {
+ snapshot = next;
+ }).pipe(Effect.andThen(PubSub.publish(changes, next)), Effect.asVoid),
+ streamChanges: Stream.fromPubSub(changes),
+ });
+ }),
+ );
+ return BackgroundPolicy.layer.pipe(
+ Layer.provide(Layer.merge(hostLayer, ServerSettingsService.layerTest(settingsOverrides))),
+ );
+}
+
+describe("BackgroundPolicy", () => {
+ it.effect("records foreground scoped client demand", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ RpcClientId.make(1),
+ makeReport(),
+ );
+
+ const snapshot = yield* policy.snapshot;
+ assert.equal(snapshot.activeForegroundLeaseCount, 1);
+ assert.deepStrictEqual(snapshot.activeScopeKeys, ["vcs-status:/repo"]);
+ assert.equal(snapshot.shouldRunOpportunisticWork, true);
+ assert.equal(yield* policy.hasDemand({ type: "vcs-status", cwd: "/repo" }), true);
+ assert.equal(yield* policy.hasDemand({ type: "vcs-status", cwd: "/other" }), false);
+ assert.equal(yield* policy.shouldRunScopeWork({ type: "vcs-status", cwd: "/repo" }), true);
+ assert.equal(yield* policy.shouldRunScopeWork({ type: "vcs-status", cwd: "/other" }), false);
+ }).pipe(Effect.provide(makeLayer(nominalHostPower))),
+ );
+
+ it.effect("removes all leases for a disconnected websocket connection", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ RpcClientId.make(1),
+ makeReport(),
+ );
+ yield* policy.removeRpcClient(AuthSessionId.make("session-1"), RpcClientId.make(1));
+
+ const snapshot = yield* policy.snapshot;
+ assert.equal(snapshot.activeForegroundLeaseCount, 0);
+ assert.deepStrictEqual(snapshot.activeScopeKeys, []);
+ assert.equal(snapshot.shouldRunOpportunisticWork, false);
+ }).pipe(Effect.provide(makeLayer(nominalHostPower))),
+ );
+
+ it.effect("keeps leases from another session when rpc client ids are reused", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ const rpcClientId = RpcClientId.make(1);
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ rpcClientId,
+ makeReport({ clientId: "client-1" }),
+ );
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-2"),
+ rpcClientId,
+ makeReport({ clientId: "client-2" }),
+ );
+
+ yield* policy.removeRpcClient(AuthSessionId.make("session-1"), rpcClientId);
+
+ const snapshot = yield* policy.snapshot;
+ assert.equal(snapshot.activeForegroundLeaseCount, 1);
+ assert.equal(snapshot.leases[0]?.sessionId, AuthSessionId.make("session-2"));
+ assert.equal(snapshot.leases[0]?.clientId, "client-2");
+ }).pipe(Effect.provide(makeLayer(nominalHostPower))),
+ );
+
+ it.effect("serializes lease mutation publications", () =>
+ Effect.gen(function* () {
+ const firstSnapshotStarted = yield* Deferred.make<void>();
+ const releaseFirstSnapshot = yield* Deferred.make<void>();
+ const snapshotReads = yield* Ref.make(0);
+ const hostLayer = Layer.succeed(
+ HostPowerMonitor.HostPowerMonitor,
+ HostPowerMonitor.HostPowerMonitor.of({
+ snapshot: Ref.updateAndGet(snapshotReads, (count) => count + 1).pipe(
+ Effect.flatMap((count) =>
+ count === 1
+ ? Deferred.succeed(firstSnapshotStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(releaseFirstSnapshot)),
+ Effect.as(nominalHostPower),
+ )
+ : Effect.succeed(nominalHostPower),
+ ),
+ ),
+ report: () => Effect.void,
+ streamChanges: Stream.empty,
+ }),
+ );
+ const layer = BackgroundPolicy.layer.pipe(
+ Layer.provide(Layer.merge(hostLayer, ServerSettingsService.layerTest())),
+ );
+
+ yield* Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ const updatesFiber = yield* policy.streamChanges.pipe(
+ Stream.take(2),
+ Stream.runCollect,
+ Effect.forkChild,
+ );
+ yield* Effect.yieldNow;
+ const reportFiber = yield* policy
+ .reportClientActivity(AuthSessionId.make("session-1"), RpcClientId.make(1), makeReport())
+ .pipe(Effect.forkChild);
+ yield* Deferred.await(firstSnapshotStarted);
+ const removeFiber = yield* policy
+ .removeRpcClient(AuthSessionId.make("session-1"), RpcClientId.make(1))
+ .pipe(Effect.forkChild);
+ yield* Effect.yieldNow;
+ yield* Deferred.succeed(releaseFirstSnapshot, undefined);
+ yield* Fiber.join(reportFiber);
+ yield* Fiber.join(removeFiber);
+ const updates = Array.from(yield* Fiber.join(updatesFiber));
+
+ assert.equal(updates.at(-1)?.activeForegroundLeaseCount, 0);
+ assert.deepStrictEqual(updates.at(-1)?.activeScopeKeys, []);
+ }).pipe(Effect.provide(layer));
+ }),
+ );
+
+ it.effect("bounds client-id churn for one websocket connection", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ const sessionId = AuthSessionId.make("session-1");
+ const rpcClientId = RpcClientId.make(1);
+ for (
+ let index = 0;
+ index <= BackgroundPolicy.MAX_CLIENT_ACTIVITY_LEASES_PER_RPC_CLIENT;
+ index += 1
+ ) {
+ yield* policy.reportClientActivity(
+ sessionId,
+ rpcClientId,
+ makeReport({ clientId: `client-${index}` }),
+ );
+ }
+
+ const snapshot = yield* policy.snapshot;
+ assert.equal(
+ snapshot.leases.length,
+ BackgroundPolicy.MAX_CLIENT_ACTIVITY_LEASES_PER_RPC_CLIENT,
+ );
+ assert.isTrue(
+ snapshot.leases.some(
+ (lease) =>
+ lease.clientId ===
+ `client-${BackgroundPolicy.MAX_CLIENT_ACTIVITY_LEASES_PER_RPC_CLIENT}`,
+ ),
+ );
+ }).pipe(Effect.provide(makeLayer(nominalHostPower))),
+ );
+
+ it.effect("host low power mode disables opportunistic work without dropping scoped demand", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ RpcClientId.make(1),
+ makeReport(),
+ );
+
+ const snapshot = yield* policy.snapshot;
+ assert.equal(snapshot.activeForegroundLeaseCount, 1);
+ assert.deepStrictEqual(snapshot.activeScopeKeys, ["vcs-status:/repo"]);
+ assert.equal(snapshot.shouldRunOpportunisticWork, false);
+ assert.equal(yield* policy.hasDemand({ type: "vcs-status", cwd: "/repo" }), true);
+ assert.equal(yield* policy.shouldRunScopeWork({ type: "vcs-status", cwd: "/repo" }), false);
+ }).pipe(Effect.provide(makeLayer(constrainedHostPower))),
+ );
+
+ it.effect("host suspension disables scoped and opportunistic work", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ RpcClientId.make(1),
+ makeReport(),
+ );
+
+ const snapshot = yield* policy.snapshot;
+ assert.equal(snapshot.activeForegroundLeaseCount, 1);
+ assert.equal(snapshot.shouldRunOpportunisticWork, false);
+ assert.equal(yield* policy.hasDemand({ type: "vcs-status", cwd: "/repo" }), true);
+ assert.equal(yield* policy.shouldRunScopeWork({ type: "vcs-status", cwd: "/repo" }), false);
+ }).pipe(
+ Effect.provide(
+ makeLayer({
+ ...nominalHostPower,
+ suspended: true,
+ stale: false,
+ }),
+ ),
+ ),
+ );
+
+ it.effect("keeps background demand visible while preventing scoped work", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ RpcClientId.make(1),
+ makeReport({ focused: false, visible: false }),
+ );
+
+ const snapshot = yield* policy.snapshot;
+ assert.equal(snapshot.activeForegroundLeaseCount, 0);
+ assert.deepStrictEqual(snapshot.activeScopeKeys, ["vcs-status:/repo"]);
+ assert.equal(yield* policy.hasDemand({ type: "vcs-status", cwd: "/repo" }), true);
+ assert.equal(yield* policy.shouldRunScopeWork({ type: "vcs-status", cwd: "/repo" }), false);
+ }).pipe(Effect.provide(makeLayer(nominalHostPower))),
+ );
+
+ it.effect("keeps scoped work active after a recently used visible window loses focus", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ RpcClientId.make(1),
+ makeReport({ focused: false, recentlyInteracted: true }),
+ );
+
+ const snapshot = yield* policy.snapshot;
+ assert.equal(snapshot.activeForegroundLeaseCount, 1);
+ assert.equal(snapshot.shouldRunOpportunisticWork, true);
+ assert.equal(yield* policy.shouldRunScopeWork({ type: "vcs-status", cwd: "/repo" }), true);
+ }).pipe(Effect.provide(makeLayer(nominalHostPower))),
+ );
+
+ it.effect("pauses scoped work for a visible unfocused client without recent interaction", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ RpcClientId.make(1),
+ makeReport({ focused: false, recentlyInteracted: false }),
+ );
+
+ const snapshot = yield* policy.snapshot;
+ assert.equal(snapshot.activeForegroundLeaseCount, 0);
+ assert.equal(snapshot.shouldRunOpportunisticWork, false);
+ assert.equal(yield* policy.shouldRunScopeWork({ type: "vcs-status", cwd: "/repo" }), false);
+ }).pipe(Effect.provide(makeLayer(nominalHostPower))),
+ );
+
+ it.effect(
+ "performance profile allows background scoped work while a scoped lease is active",
+ () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ RpcClientId.make(1),
+ makeReport({ focused: false, visible: false }),
+ );
+
+ assert.equal(yield* policy.shouldRunScopeWork({ type: "vcs-status", cwd: "/repo" }), true);
+ }).pipe(
+ Effect.provide(makeLayer(nominalHostPower, { backgroundActivityProfile: "performance" })),
+ ),
+ );
+
+ it.effect("battery saver profile pauses scoped work on battery", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ RpcClientId.make(1),
+ makeReport(),
+ );
+
+ assert.equal(yield* policy.shouldRunScopeWork({ type: "vcs-status", cwd: "/repo" }), false);
+ }).pipe(
+ Effect.provide(
+ makeLayer(
+ {
+ ...nominalHostPower,
+ onBattery: "true",
+ stale: false,
+ },
+ { backgroundActivityProfile: "battery-saver" },
+ ),
+ ),
+ ),
+ );
+
+ it.effect("does not gate work on stale host power values", () =>
+ Effect.gen(function* () {
+ const policy = yield* BackgroundPolicy.BackgroundPolicy;
+ yield* policy.reportClientActivity(
+ AuthSessionId.make("session-1"),
+ RpcClientId.make(1),
+ makeReport(),
+ );
+
+ assert.equal(yield* policy.shouldRunScopeWork({ type: "vcs-status", cwd: "/repo" }), true);
+ }).pipe(
+ Effect.provide(
+ makeLayer(
+ {
+ ...nominalHostPower,
+ locked: "true",
+ onBattery: "true",
+ lowPowerMode: "true",
+ thermalState: "critical",
+ stale: true,
+ },
+ { backgroundActivityProfile: "battery-saver" },
+ ),
+ ),
+ ),
+ );
+});
diff --git a/apps/server/src/background/BackgroundPolicy.ts b/apps/server/src/background/BackgroundPolicy.ts
new file mode 100644
index 000000000..a2a8e99d3
--- /dev/null
+++ b/apps/server/src/background/BackgroundPolicy.ts
@@ -0,0 +1,349 @@
+import {
+ type AuthSessionId,
+ type BackgroundPolicySnapshot,
+ type BackgroundScope,
+ type ClientActivityLease,
+ type ClientActivityReportInput,
+ type HostPowerSnapshot,
+ type RpcClientId,
+} from "@t3tools/contracts";
+import {
+ getBackgroundActivityPresetSettings,
+ resolveServerBackgroundActivitySettings,
+ type ResolvedBackgroundActivitySettings,
+} from "@t3tools/shared/backgroundActivitySettings";
+import * as DateTime from "effect/DateTime";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+
+import { ServerSettingsService } from "../serverSettings.ts";
+import { subscribeBeforeSnapshot } from "../utils/subscribeBeforeSnapshot.ts";
+import * as HostPowerMonitor from "./HostPowerMonitor.ts";
+
+export class BackgroundPolicy extends Context.Service<
+ BackgroundPolicy,
+ {
+ readonly reportClientActivity: (
+ sessionId: AuthSessionId,
+ rpcClientId: RpcClientId,
+ input: ClientActivityReportInput,
+ ) => Effect.Effect<void>;
+ readonly removeRpcClient: (
+ sessionId: AuthSessionId,
+ rpcClientId: RpcClientId,
+ ) => Effect.Effect<void>;
+ readonly reportHostPowerState: (snapshot: HostPowerSnapshot) => Effect.Effect<void>;
+ readonly snapshot: Effect.Effect<BackgroundPolicySnapshot>;
+ readonly streamChanges: Stream.Stream<BackgroundPolicySnapshot>;
+ readonly subscribe: Effect.Effect<
+ {
+ readonly latest: BackgroundPolicySnapshot;
+ readonly changes: Stream.Stream<BackgroundPolicySnapshot>;
+ },
+ never,
+ Scope.Scope
+ >;
+ readonly hasDemand: (scope: BackgroundScope) => Effect.Effect<boolean>;
+ readonly shouldRunScopeWork: (scope: BackgroundScope) => Effect.Effect<boolean>;
+ readonly shouldRunOpportunisticWork: Effect.Effect<boolean>;
+ }
+>()("t3/background/BackgroundPolicy") {}
+
+const DEFAULT_LEASE_TTL_MS = 45_000;
+const MAX_LEASE_TTL_MS = 120_000;
+export const MAX_CLIENT_ACTIVITY_LEASES_PER_RPC_CLIENT = 16;
+
+function scopeKey(scope: BackgroundScope): string {
+ switch (scope.type) {
+ case "server-config":
+ case "diagnostics":
+ return scope.type;
+ case "provider-status":
+ return scope.instanceId ? `${scope.type}:${scope.instanceId}` : scope.type;
+ case "vcs-status":
+ case "git-refs":
+ return `${scope.type}:${scope.cwd}`;
+ case "thread":
+ return `${scope.type}:${scope.threadId}`;
+ }
+}
+
+function isLeaseActive(lease: ClientActivityLease, now: DateTime.Utc): boolean {
+ return DateTime.isGreaterThan(lease.expiresAt, now);
+}
+
+function leaseKey(lease: Pick<ClientActivityLease, "sessionId" | "rpcClientId" | "clientId">) {
+ return JSON.stringify([lease.sessionId, lease.rpcClientId, lease.clientId]);
+}
+
+export function upsertClientActivityLease(
+ leases: ReadonlyMap<string, ClientActivityLease>,
+ lease: ClientActivityLease,
+ now: DateTime.Utc,
+): Map<string, ClientActivityLease> {
+ const next = new Map(leases);
+ for (const [key, current] of next) {
+ if (!isLeaseActive(current, now)) {
+ next.delete(key);
+ }
+ }
+
+ const key = leaseKey(lease);
+ if (!next.has(key)) {
+ let connectionLeaseCount = 0;
+ let oldestConnectionLease:
+ | {
+ readonly key: string;
+ readonly updatedAtMs: number;
+ }
+ | undefined;
+ for (const [currentKey, current] of next) {
+ if (current.sessionId !== lease.sessionId || current.rpcClientId !== lease.rpcClientId) {
+ continue;
+ }
+ connectionLeaseCount += 1;
+ const updatedAtMs = DateTime.toEpochMillis(current.updatedAt);
+ if (oldestConnectionLease === undefined || updatedAtMs < oldestConnectionLease.updatedAtMs) {
+ oldestConnectionLease = { key: currentKey, updatedAtMs };
+ }
+ }
+ if (
+ connectionLeaseCount >= MAX_CLIENT_ACTIVITY_LEASES_PER_RPC_CLIENT &&
+ oldestConnectionLease !== undefined
+ ) {
+ next.delete(oldestConnectionLease.key);
+ }
+ }
+
+ next.set(key, lease);
+ return next;
+}
+
+function isForegroundLease(lease: ClientActivityLease, now: DateTime.Utc): boolean {
+ return isLeaseActive(lease, now) && lease.visible && (lease.focused || lease.recentlyInteracted);
+}
+
+function leaseHasScope(lease: ClientActivityLease, scope: BackgroundScope): boolean {
+ const key = scopeKey(scope);
+ return lease.scopes.some((leaseScope) => scopeKey(leaseScope) === key);
+}
+
+function hasThermalPressure(hostPower: HostPowerSnapshot): boolean {
+ return hostPower.thermalState === "serious" || hostPower.thermalState === "critical";
+}
+
+function isHostConstrained(
+ hostPower: HostPowerSnapshot,
+ settings: ResolvedBackgroundActivitySettings,
+): boolean {
+ if (hostPower.stale) return false;
+ if (
+ hostPower.suspended ||
+ (settings.pauseWhenHostLocked && hostPower.locked === "true") ||
+ hasThermalPressure(hostPower)
+ ) {
+ return true;
+ }
+ if (settings.pauseWhenHostLowPower && hostPower.lowPowerMode === "true") return true;
+ return settings.pauseWhenOnBattery && hostPower.onBattery === "true";
+}
+
+function isClientConstrained(
+ lease: ClientActivityLease,
+ settings: ResolvedBackgroundActivitySettings,
+): boolean {
+ if (settings.pauseWhenClientLowPower && lease.lowPowerMode === "true") return true;
+ return settings.pauseWhenOnBattery && lease.batteryState === "unplugged";
+}
+
+function leaseMayRunScopedWork(
+ lease: ClientActivityLease,
+ scope: BackgroundScope,
+ now: DateTime.Utc,
+ settings: ResolvedBackgroundActivitySettings,
+): boolean {
+ const activeWithScope = isLeaseActive(lease, now) && leaseHasScope(lease, scope);
+ if (!activeWithScope || isClientConstrained(lease, settings)) {
+ return false;
+ }
+ if (settings.profile === "performance") {
+ return true;
+ }
+ return isForegroundLease(lease, now);
+}
+
+function computeSnapshot(input: {
+ readonly hostPower: HostPowerSnapshot;
+ readonly leases: ReadonlyMap<string, ClientActivityLease>;
+ readonly now: DateTime.Utc;
+ readonly settings: ResolvedBackgroundActivitySettings;
+ readonly updatedAt: DateTime.Utc;
+}): BackgroundPolicySnapshot {
+ const activeLeases = [...input.leases.values()].filter((lease) =>
+ isLeaseActive(lease, input.now),
+ );
+ const foregroundLeases = activeLeases.filter((lease) => isForegroundLease(lease, input.now));
+ const activeScopeKeys = new Set<string>();
+ for (const lease of activeLeases) {
+ for (const scope of lease.scopes) {
+ activeScopeKeys.add(scopeKey(scope));
+ }
+ }
+
+ return {
+ hostPower: input.hostPower,
+ leases: activeLeases,
+ activeForegroundLeaseCount: foregroundLeases.length,
+ activeScopeKeys: [...activeScopeKeys].toSorted(),
+ shouldRunOpportunisticWork:
+ foregroundLeases.some((lease) => !isClientConstrained(lease, input.settings)) &&
+ !isHostConstrained(input.hostPower, input.settings),
+ updatedAt: input.updatedAt,
+ };
+}
+
+export const make = Effect.fn("background.policy.make")(function* () {
+ const hostPowerMonitor = yield* HostPowerMonitor.HostPowerMonitor;
+ const serverSettings = yield* ServerSettingsService;
+ const leasesRef = yield* Ref.make(new Map<string, ClientActivityLease>());
+ const changes = yield* PubSub.sliding<BackgroundPolicySnapshot>(1);
+ const publishMutex = yield* Semaphore.make(1);
+
+ const backgroundActivitySettings = serverSettings.getSettings.pipe(
+ Effect.map(resolveServerBackgroundActivitySettings),
+ Effect.orElseSucceed(() => getBackgroundActivityPresetSettings("balanced")),
+ );
+
+ const snapshot = Effect.gen(function* () {
+ const [hostPower, leases, now, settings] = yield* Effect.all([
+ hostPowerMonitor.snapshot,
+ Ref.get(leasesRef),
+ DateTime.now,
+ backgroundActivitySettings,
+ ]);
+ return computeSnapshot({ hostPower, leases, now, settings, updatedAt: now });
+ });
+
+ const publishSnapshotUnlocked = snapshot.pipe(
+ Effect.flatMap((next) => PubSub.publish(changes, next)),
+ );
+ const publishSnapshot = publishMutex.withPermits(1)(publishSnapshotUnlocked);
+
+ const reportClientActivity: BackgroundPolicy["Service"]["reportClientActivity"] = (
+ sessionId,
+ rpcClientId,
+ input,
+ ) =>
+ publishMutex.withPermits(1)(
+ Effect.gen(function* () {
+ const ttlMs = Math.min(
+ Math.max(input.ttlMs ?? DEFAULT_LEASE_TTL_MS, 1_000),
+ MAX_LEASE_TTL_MS,
+ );
+ const now = yield* DateTime.now;
+ const expiresAt = DateTime.add(now, { milliseconds: ttlMs });
+ const lease: ClientActivityLease = {
+ sessionId,
+ rpcClientId,
+ clientId: input.clientId,
+ clientKind: input.clientKind,
+ visible: input.visible,
+ focused: input.focused,
+ recentlyInteracted: input.recentlyInteracted,
+ ...(input.appState !== undefined ? { appState: input.appState } : {}),
+ ...(input.lowPowerMode !== undefined ? { lowPowerMode: input.lowPowerMode } : {}),
+ ...(input.batteryState !== undefined ? { batteryState: input.batteryState } : {}),
+ ...(input.networkType !== undefined ? { networkType: input.networkType } : {}),
+ scopes: input.scopes,
+ updatedAt: now,
+ expiresAt,
+ };
+ yield* Ref.update(leasesRef, (leases) => upsertClientActivityLease(leases, lease, now));
+ yield* publishSnapshotUnlocked;
+ }),
+ );
+
+ const removeRpcClient: BackgroundPolicy["Service"]["removeRpcClient"] = (
+ sessionId,
+ rpcClientId,
+ ) =>
+ publishMutex.withPermits(1)(
+ Ref.update(leasesRef, (leases) => {
+ const next = new Map(leases);
+ for (const [key, lease] of next) {
+ if (lease.sessionId === sessionId && lease.rpcClientId === rpcClientId) {
+ next.delete(key);
+ }
+ }
+ return next;
+ }).pipe(Effect.andThen(publishSnapshotUnlocked), Effect.asVoid),
+ );
+
+ const hasDemand: BackgroundPolicy["Service"]["hasDemand"] = (scope) =>
+ Effect.map(snapshot, (current) => current.activeScopeKeys.includes(scopeKey(scope)));
+
+ const shouldRunScopeWork: BackgroundPolicy["Service"]["shouldRunScopeWork"] = (scope) =>
+ Effect.gen(function* () {
+ const [current, settings] = yield* Effect.all([snapshot, backgroundActivitySettings]);
+ if (isHostConstrained(current.hostPower, settings)) {
+ return false;
+ }
+ return current.leases.some((lease) =>
+ leaseMayRunScopedWork(lease, scope, current.updatedAt, settings),
+ );
+ });
+
+ const shouldRunOpportunisticWork = Effect.map(
+ snapshot,
+ (current) => current.shouldRunOpportunisticWork,
+ );
+
+ yield* Stream.runForEach(hostPowerMonitor.streamChanges, () => publishSnapshot).pipe(
+ Effect.forkScoped,
+ );
+ yield* Stream.runForEach(serverSettings.streamChanges, () => publishSnapshot).pipe(
+ Effect.forkScoped,
+ );
+
+ yield* Effect.forever(
+ Effect.sleep("15 seconds").pipe(
+ Effect.andThen(
+ publishMutex.withPermits(1)(
+ Effect.gen(function* () {
+ const now = yield* DateTime.now;
+ yield* Ref.update(leasesRef, (leases) => {
+ const next = new Map(leases);
+ for (const [key, lease] of next) {
+ if (!isLeaseActive(lease, now)) {
+ next.delete(key);
+ }
+ }
+ return next;
+ });
+ yield* publishSnapshotUnlocked;
+ }),
+ ),
+ ),
+ ),
+ ).pipe(Effect.forkScoped);
+
+ return BackgroundPolicy.of({
+ reportClientActivity,
+ removeRpcClient,
+ reportHostPowerState: hostPowerMonitor.report,
+ snapshot,
+ streamChanges: Stream.fromPubSub(changes),
+ subscribe: subscribeBeforeSnapshot(changes, snapshot, publishMutex),
+ hasDemand,
+ shouldRunScopeWork,
+ shouldRunOpportunisticWork,
+ });
+});
+
+export const layer = Layer.effect(BackgroundPolicy, make());
diff --git a/apps/server/src/background/HostPowerMonitor.test.ts b/apps/server/src/background/HostPowerMonitor.test.ts
new file mode 100644
index 000000000..2bd4dc0fe
--- /dev/null
+++ b/apps/server/src/background/HostPowerMonitor.test.ts
@@ -0,0 +1,188 @@
+import type { DesktopHostTelemetrySnapshot } from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
+
+import * as DesktopTelemetryReceiver from "../resourceTelemetry/DesktopTelemetryReceiver.ts";
+import * as HostPowerMonitor from "./HostPowerMonitor.ts";
+
+describe("HostPowerMonitor", () => {
+ it.effect("publishes semantic power changes without idle-time heartbeat churn", () =>
+ Effect.gen(function* () {
+ const monitor = yield* HostPowerMonitor.make();
+ const initial = {
+ source: "electron-main",
+ idle: "false",
+ idleSeconds: 0,
+ locked: "false",
+ suspended: false,
+ onBattery: "false",
+ lowPowerMode: "unknown",
+ thermalState: "nominal",
+ stale: false,
+ updatedAt: DateTime.makeUnsafe("2026-06-17T12:00:00.000Z"),
+ } as const;
+ yield* monitor.report(initial);
+
+ const nextChange = yield* Stream.runHead(monitor.streamChanges).pipe(Effect.forkChild);
+ yield* Effect.yieldNow;
+ yield* monitor.report({
+ ...initial,
+ idleSeconds: 1,
+ updatedAt: DateTime.makeUnsafe("2026-06-17T12:00:01.000Z"),
+ });
+ yield* monitor.report({
+ ...initial,
+ locked: "true",
+ updatedAt: DateTime.makeUnsafe("2026-06-17T12:00:02.000Z"),
+ });
+
+ expect(Option.getOrThrow(yield* Fiber.join(nextChange)).locked).toBe("true");
+ }),
+ );
+
+ it.effect("ignores host power reports older than the latest accepted snapshot", () =>
+ Effect.gen(function* () {
+ const initial = {
+ source: "electron-main",
+ idle: "false",
+ idleSeconds: 0,
+ locked: "false",
+ suspended: false,
+ onBattery: "false",
+ lowPowerMode: "false",
+ thermalState: "nominal",
+ stale: false,
+ updatedAt: DateTime.makeUnsafe("2026-06-17T12:00:00.000Z"),
+ } as const;
+ const monitor = yield* HostPowerMonitor.make(initial);
+ const latestAt = DateTime.makeUnsafe("2026-06-17T12:00:02.000Z");
+ yield* monitor.report({
+ ...initial,
+ locked: "true",
+ updatedAt: latestAt,
+ });
+ yield* monitor.report({
+ ...initial,
+ updatedAt: DateTime.makeUnsafe("2026-06-17T12:00:01.000Z"),
+ });
+
+ const snapshot = yield* monitor.snapshot;
+ expect(snapshot.locked).toBe("true");
+ expect(DateTime.toEpochMillis(snapshot.updatedAt)).toBe(DateTime.toEpochMillis(latestAt));
+ }),
+ );
+
+ it.effect("consumes desktop power directly without retaining diagnostics telemetry", () =>
+ Effect.gen(function* () {
+ const sampledAt = DateTime.makeUnsafe("2026-06-17T12:00:00.000Z");
+ const desktopChanges = yield* PubSub.sliding<DesktopHostTelemetrySnapshot>(1);
+ const diagnosticsDemandWrites = yield* Ref.make(0);
+ const receiverLayer = DesktopTelemetryReceiver.layerTest({
+ changes: Stream.fromPubSub(desktopChanges),
+ setDiagnosticsDemand: () => Ref.update(diagnosticsDemandWrites, (count) => count + 1),
+ });
+ const layer = HostPowerMonitor.layer.pipe(Layer.provide(receiverLayer));
+
+ yield* Effect.gen(function* () {
+ const monitor = yield* HostPowerMonitor.HostPowerMonitor;
+ const nextPower = yield* Stream.runHead(monitor.streamChanges).pipe(Effect.forkChild);
+ yield* Effect.yieldNow;
+ yield* PubSub.publish(desktopChanges, {
+ version: 1,
+ type: "desktopTelemetry",
+ sequence: 1,
+ sampledAtUnixMs: DateTime.toEpochMillis(sampledAt),
+ electronPid: 100,
+ power: {
+ source: "electron-main",
+ idle: "false",
+ idleSeconds: 0,
+ locked: "false",
+ suspended: false,
+ onBattery: "true",
+ lowPowerMode: "unknown",
+ thermalState: "nominal",
+ stale: false,
+ updatedAt: sampledAt,
+ },
+ speedLimitPercent: Option.none(),
+ electronProcesses: [],
+ });
+
+ expect(Option.getOrThrow(yield* Fiber.join(nextPower)).onBattery).toBe("true");
+ expect(yield* Ref.get(diagnosticsDemandWrites)).toBe(0);
+ }).pipe(Effect.provide(layer));
+ }),
+ );
+
+ it.effect(
+ "subscribes before reading the desktop snapshot so concurrent power updates survive",
+ () =>
+ Effect.gen(function* () {
+ const sampledAt = DateTime.makeUnsafe("2026-06-17T12:00:00.000Z");
+ const initial: DesktopHostTelemetrySnapshot = {
+ version: 1,
+ type: "desktopTelemetry",
+ sequence: 1,
+ sampledAtUnixMs: DateTime.toEpochMillis(sampledAt),
+ electronPid: 100,
+ power: {
+ source: "electron-main",
+ idle: "false",
+ idleSeconds: 0,
+ locked: "false",
+ suspended: false,
+ onBattery: "false",
+ lowPowerMode: "unknown",
+ thermalState: "nominal",
+ stale: false,
+ updatedAt: sampledAt,
+ },
+ speedLimitPercent: Option.none(),
+ electronProcesses: [],
+ };
+ const updated: DesktopHostTelemetrySnapshot = {
+ ...initial,
+ sequence: 2,
+ power: {
+ ...initial.power,
+ onBattery: "true",
+ updatedAt: DateTime.makeUnsafe("2026-06-17T12:00:01.000Z"),
+ },
+ };
+ const desktopChanges = yield* PubSub.sliding<DesktopHostTelemetrySnapshot>(1);
+ const receiverLayer = DesktopTelemetryReceiver.layerTest({
+ latest: Effect.succeedSome(initial),
+ changes: Stream.empty,
+ subscribe: Effect.gen(function* () {
+ const subscription = yield* PubSub.subscribe(desktopChanges);
+ yield* PubSub.publish(desktopChanges, updated);
+ return {
+ latest: Option.some(initial),
+ changes: Stream.fromSubscription(subscription),
+ };
+ }),
+ });
+ const layer = HostPowerMonitor.layer.pipe(Layer.provide(receiverLayer));
+
+ yield* Effect.gen(function* () {
+ const monitor = yield* HostPowerMonitor.HostPowerMonitor;
+ for (
+ let attempt = 0;
+ attempt < 100 && (yield* monitor.snapshot).onBattery !== "true";
+ attempt += 1
+ ) {
+ yield* Effect.yieldNow;
+ }
+ expect((yield* monitor.snapshot).onBattery).toBe("true");
+ }).pipe(Effect.provide(layer));
+ }),
+ );
+});
diff --git a/apps/server/src/background/HostPowerMonitor.ts b/apps/server/src/background/HostPowerMonitor.ts
new file mode 100644
index 000000000..273548faa
--- /dev/null
+++ b/apps/server/src/background/HostPowerMonitor.ts
@@ -0,0 +1,101 @@
+import type { HostPowerSnapshot } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
+
+import * as DesktopTelemetryReceiver from "../resourceTelemetry/DesktopTelemetryReceiver.ts";
+
+export class HostPowerMonitor extends Context.Service<
+ HostPowerMonitor,
+ {
+ readonly snapshot: Effect.Effect<HostPowerSnapshot>;
+ readonly report: (snapshot: HostPowerSnapshot) => Effect.Effect<void>;
+ readonly streamChanges: Stream.Stream<HostPowerSnapshot>;
+ }
+>()("t3/background/HostPowerMonitor") {}
+
+export const makeUnknownSnapshot = (
+ source: HostPowerSnapshot["source"],
+ updatedAt: HostPowerSnapshot["updatedAt"],
+): HostPowerSnapshot => ({
+ source,
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt,
+});
+
+function samePowerState(left: HostPowerSnapshot, right: HostPowerSnapshot): boolean {
+ return (
+ left.source === right.source &&
+ left.idle === right.idle &&
+ left.locked === right.locked &&
+ left.suspended === right.suspended &&
+ left.onBattery === right.onBattery &&
+ left.lowPowerMode === right.lowPowerMode &&
+ left.thermalState === right.thermalState &&
+ left.stale === right.stale
+ );
+}
+
+export const make = Effect.fn("background.hostPower.make")(function* (
+ initialSnapshot?: HostPowerSnapshot,
+) {
+ const initial = initialSnapshot ?? makeUnknownSnapshot("unknown", yield* DateTime.now);
+ const latestRef = yield* Ref.make(initial);
+ const changes = yield* PubSub.sliding<HostPowerSnapshot>(1);
+
+ const report: HostPowerMonitor["Service"]["report"] = (snapshot) =>
+ Ref.modify(latestRef, (current) => {
+ if (DateTime.isLessThan(snapshot.updatedAt, current.updatedAt)) {
+ return [Option.none<HostPowerSnapshot>(), current] as const;
+ }
+ return [
+ samePowerState(current, snapshot) ? Option.none() : Option.some(snapshot),
+ snapshot,
+ ] as const;
+ }).pipe(
+ Effect.flatMap(
+ Option.match({
+ onNone: () => Effect.void,
+ onSome: (next) => PubSub.publish(changes, next),
+ }),
+ ),
+ Effect.asVoid,
+ );
+
+ return HostPowerMonitor.of({
+ snapshot: Ref.get(latestRef),
+ report,
+ streamChanges: Stream.fromPubSub(changes),
+ });
+});
+
+export const layer = Layer.effect(
+ HostPowerMonitor,
+ Effect.gen(function* () {
+ const desktopTelemetry = yield* DesktopTelemetryReceiver.DesktopTelemetryReceiver;
+ const desktopSubscription = yield* desktopTelemetry.subscribe;
+ const initial = desktopSubscription.latest;
+ const monitor = yield* Option.match(initial, {
+ onNone: () => make(),
+ onSome: (snapshot) => make(snapshot.power),
+ });
+ yield* desktopSubscription.changes.pipe(
+ Stream.map((snapshot) => snapshot.power),
+ Stream.runForEach(monitor.report),
+ Effect.forkScoped,
+ );
+ return monitor;
+ }),
+);
diff --git a/apps/server/src/cli/config.test.ts b/apps/server/src/cli/config.test.ts
index 39c00053f..cc1821dd1 100644
--- a/apps/server/src/cli/config.test.ts
+++ b/apps/server/src/cli/config.test.ts
@@ -41,7 +41,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
const defaultObservabilityConfig = {
traceMinLevel: "Info",
traceTimingEnabled: true,
- traceBatchWindowMs: 200,
+ traceBatchWindowMs: 1_000,
traceMaxBytes: 10 * 1024 * 1024,
traceMaxFiles: 10,
otlpTracesUrl: undefined,
@@ -286,6 +286,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
t3Home: baseDir,
noBrowser: true,
desktopBootstrapToken: "desktop-token",
+ desktopTelemetryFd: 4,
+ desktopTelemetryControlFd: 5,
tailscaleServeEnabled: false,
tailscaleServePort: 443,
otlpTracesUrl: "http://localhost:4318/v1/traces",
@@ -341,12 +343,17 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
noBrowser: true,
startupPresentation: "browser",
desktopBootstrapToken: "desktop-token",
+ desktopTelemetryFd: 4,
+ desktopTelemetryControlFd: 5,
+ resourceMonitorPath: undefined,
autoBootstrapProjectFromCwd: false,
logWebSocketEvents: false,
tailscaleServeEnabled: false,
tailscaleServePort: 443,
});
assert.equal(join(baseDir, "userdata"), resolved.stateDir);
+ assert.equal(resolved.desktopTelemetryFd, 4);
+ assert.equal(resolved.desktopTelemetryControlFd, 5);
}),
);
diff --git a/apps/server/src/cli/config.ts b/apps/server/src/cli/config.ts
index e3f231cca..6814d251a 100644
--- a/apps/server/src/cli/config.ts
+++ b/apps/server/src/cli/config.ts
@@ -85,7 +85,7 @@ const EnvServerConfig = Config.all({
),
traceMaxBytes: Config.int("T3CODE_TRACE_MAX_BYTES").pipe(Config.withDefault(10 * 1024 * 1024)),
traceMaxFiles: Config.int("T3CODE_TRACE_MAX_FILES").pipe(Config.withDefault(10)),
- traceBatchWindowMs: Config.int("T3CODE_TRACE_BATCH_WINDOW_MS").pipe(Config.withDefault(200)),
+ traceBatchWindowMs: Config.int("T3CODE_TRACE_BATCH_WINDOW_MS").pipe(Config.withDefault(1_000)),
otlpTracesUrl: Config.string("T3CODE_OTLP_TRACES_URL").pipe(
Config.option,
Config.map(Option.getOrUndefined),
@@ -303,6 +303,9 @@ export const resolveServerConfig = (
() => mode === "desktop",
);
const desktopBootstrapToken = bootstrap?.desktopBootstrapToken;
+ const desktopTelemetryFd = bootstrap?.desktopTelemetryFd;
+ const desktopTelemetryControlFd = bootstrap?.desktopTelemetryControlFd;
+ const resourceMonitorPath = bootstrap?.resourceMonitorPath;
const autoBootstrapProjectFromCwd = Option.getOrElse(
resolveOptionPrecedence(
Option.fromUndefinedOr(options?.forceAutoBootstrapProjectFromCwd),
@@ -376,6 +379,9 @@ export const resolveServerConfig = (
noBrowser,
startupPresentation,
desktopBootstrapToken,
+ desktopTelemetryFd,
+ desktopTelemetryControlFd,
+ resourceMonitorPath,
autoBootstrapProjectFromCwd,
logWebSocketEvents,
tailscaleServeEnabled,
diff --git a/apps/server/src/config.ts b/apps/server/src/config.ts
index 5a16e144e..e678264dd 100644
--- a/apps/server/src/config.ts
+++ b/apps/server/src/config.ts
@@ -76,6 +76,9 @@ export class ServerConfig extends Context.Service<
readonly noBrowser: boolean;
readonly startupPresentation: StartupPresentation;
readonly desktopBootstrapToken: string | undefined;
+ readonly desktopTelemetryFd?: number | undefined;
+ readonly desktopTelemetryControlFd?: number | undefined;
+ readonly resourceMonitorPath?: string | undefined;
readonly autoBootstrapProjectFromCwd: boolean;
readonly logWebSocketEvents: boolean;
readonly tailscaleServeEnabled: boolean;
@@ -186,6 +189,9 @@ const makeTest = Effect.fn("ServerConfig.makeTest")(function* (
port: 0,
host: undefined,
desktopBootstrapToken: undefined,
+ desktopTelemetryFd: undefined,
+ desktopTelemetryControlFd: undefined,
+ resourceMonitorPath: undefined,
staticDir: undefined,
devUrl,
devAllowedOrigins: [],
diff --git a/apps/server/src/diagnostics/ProcessDiagnostics.test.ts b/apps/server/src/diagnostics/ProcessDiagnostics.test.ts
index 7d16a11c8..2efa3375d 100644
--- a/apps/server/src/diagnostics/ProcessDiagnostics.test.ts
+++ b/apps/server/src/diagnostics/ProcessDiagnostics.test.ts
@@ -1,291 +1,293 @@
import { describe, expect, it } from "@effect/vitest";
+import type {
+ DesktopHostTelemetrySnapshot,
+ ResourceMonitorSnapshotEvent,
+} from "@t3tools/contracts";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
-import * as Sink from "effect/Sink";
import * as Stream from "effect/Stream";
-import { ChildProcessSpawner } from "effect/unstable/process";
-import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import * as DesktopTelemetryReceiver from "../resourceTelemetry/DesktopTelemetryReceiver.ts";
+import * as NativeTelemetryClient from "../resourceTelemetry/NativeTelemetryClient.ts";
+import * as ResourceAttribution from "../resourceTelemetry/ResourceAttribution.ts";
+import * as ResourceTelemetry from "../resourceTelemetry/ResourceTelemetry.ts";
import * as ProcessDiagnostics from "./ProcessDiagnostics.ts";
-const encoder = new TextEncoder();
+function makeNativeSnapshot(
+ processes: ResourceMonitorSnapshotEvent["processes"],
+): ResourceMonitorSnapshotEvent {
+ return {
+ version: 2,
+ type: "snapshot",
+ sequence: 1,
+ sampledAtUnixMs: DateTime.toEpochMillis(DateTime.makeUnsafe("2026-05-05T10:00:00.000Z")),
+ collectionDurationMicros: 250,
+ scannedProcessCount: processes.length,
+ retainedProcessCount: processes.length,
+ inaccessibleProcessCount: 0,
+ processes,
+ };
+}
-function mockHandle(result: {
- readonly stdout?: string;
- readonly stderr?: string;
- readonly code?: number;
-}) {
- return ChildProcessSpawner.makeHandle({
- pid: ChildProcessSpawner.ProcessId(1),
- exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(result.code ?? 0)),
- isRunning: Effect.succeed(false),
- kill: () => Effect.void,
- unref: Effect.succeed(Effect.void),
- stdin: Sink.drain,
- stdout: Stream.make(encoder.encode(result.stdout ?? "")),
- stderr: Stream.make(encoder.encode(result.stderr ?? "")),
- all: Stream.empty,
- getInputFd: () => Sink.drain,
- getOutputFd: () => Stream.empty,
+function makeTelemetryLayer(
+ snapshot: ResourceMonitorSnapshotEvent,
+ desktopSnapshot?: DesktopHostTelemetrySnapshot,
+) {
+ const nativeLayer = NativeTelemetryClient.layerTest({
+ sampleNow: Effect.succeed({ generation: 0, snapshot }),
+ health: Effect.succeed({
+ status: "healthy",
+ hello: Option.none(),
+ lastSampleAt: Option.some(DateTime.makeUnsafe(snapshot.sampledAtUnixMs)),
+ lastError: Option.none(),
+ restartCount: 0,
+ sampleIntervalMs: 1_000,
+ }),
});
+ const desktopLayer = desktopSnapshot
+ ? DesktopTelemetryReceiver.layerTest({
+ latest: Effect.succeedSome(desktopSnapshot),
+ health: Effect.succeed({
+ status: "healthy",
+ lastSampleAt: Option.some(DateTime.makeUnsafe(desktopSnapshot.sampledAtUnixMs)),
+ lastError: Option.none(),
+ }),
+ })
+ : DesktopTelemetryReceiver.layerTest();
+ return ResourceTelemetry.layer.pipe(
+ Layer.provide(Layer.mergeAll(nativeLayer, desktopLayer, ResourceAttribution.layer)),
+ );
}
describe("ProcessDiagnostics", () => {
- it.effect("parses POSIX ps rows with full commands", () =>
- Effect.sync(() => {
- const rows = ProcessDiagnostics.parsePosixProcessRows(
- [
- " 10 1 10 Ss 0.0 1024 01:02.03 /usr/bin/node server.js",
- " 11 10 10 S+ 12.5 20480 00:04 codex app-server --config /tmp/one two",
- ].join("\n"),
- );
-
- expect(rows).toEqual([
+ it.effect("projects live process data from resource telemetry", () =>
+ Effect.gen(function* () {
+ const snapshot = makeNativeSnapshot([
{
- pid: 10,
+ pid: process.pid,
ppid: 1,
- pgid: 10,
- status: "Ss",
+ startTimeMs: 1_000,
+ runTimeMs: 60_000,
+ name: "node",
+ command: "t3 server",
+ status: "Running",
cpuPercent: 0,
- rssBytes: 1024 * 1024,
- elapsed: "01:02.03",
- command: "/usr/bin/node server.js",
+ cpuTimeMs: 100,
+ residentBytes: 1_024,
+ virtualBytes: 2_048,
+ ioReadBytes: 100,
+ ioWriteBytes: 200,
+ ioSemantics: "storage",
},
{
- pid: 11,
- ppid: 10,
- pgid: 10,
- status: "S+",
- cpuPercent: 12.5,
- rssBytes: 20480 * 1024,
- elapsed: "00:04",
- command: "codex app-server --config /tmp/one two",
+ pid: 4_242,
+ ppid: process.pid,
+ startTimeMs: 2_000,
+ runTimeMs: 4_000,
+ name: "agent",
+ command: "codex app-server",
+ status: "Running",
+ cpuPercent: 1.5,
+ cpuTimeMs: 60,
+ residentBytes: 2_048,
+ virtualBytes: 4_096,
+ ioReadBytes: 300,
+ ioWriteBytes: 400,
+ ioSemantics: "storage",
},
]);
- }),
- );
-
- it.effect("aggregates only descendants of the server process", () =>
- Effect.sync(() => {
- const diagnostics = ProcessDiagnostics.aggregateProcessDiagnostics({
- serverPid: 100,
- readAt: DateTime.makeUnsafe("2026-05-05T10:00:00.000Z"),
- rows: [
- {
- pid: 100,
- ppid: 1,
- pgid: 100,
- status: "S",
- cpuPercent: 0,
- rssBytes: 1_000,
- elapsed: "01:00",
- command: "t3 server",
- },
- {
- pid: 101,
- ppid: 100,
- pgid: 100,
- status: "S",
- cpuPercent: 1.5,
- rssBytes: 2_000,
- elapsed: "00:20",
- command: "codex app-server",
- },
- {
- pid: 102,
- ppid: 101,
- pgid: 100,
- status: "R",
- cpuPercent: 3.25,
- rssBytes: 4_000,
- elapsed: "00:05",
- command: "git status",
- },
- {
- pid: 200,
- ppid: 1,
- pgid: 200,
- status: "S",
- cpuPercent: 99,
- rssBytes: 8_000,
- elapsed: "00:01",
- command: "unrelated",
- },
- {
- pid: 201,
- ppid: 100,
- pgid: 100,
- status: "R",
- cpuPercent: 9,
- rssBytes: 9_000,
- elapsed: "00:00",
- command: "ps -axo pid=,ppid=,pgid=,stat=,pcpu=,rss=,etime=,command=",
- },
- ],
- });
+ const telemetryLayer = makeTelemetryLayer(snapshot);
+ const layer = ProcessDiagnostics.layer.pipe(Layer.provideMerge(telemetryLayer));
- expect(diagnostics.serverPid).toBe(100);
- expect(DateTime.formatIso(diagnostics.readAt)).toBe("2026-05-05T10:00:00.000Z");
- expect(diagnostics.processCount).toBe(2);
- expect(diagnostics.totalRssBytes).toBe(6_000);
- expect(diagnostics.totalCpuPercent).toBe(4.75);
- expect(diagnostics.processes.map((process) => process.pid)).toEqual([101, 102]);
- expect(diagnostics.processes.map((process) => process.depth)).toEqual([0, 1]);
- expect(Option.getOrNull(diagnostics.processes[0]!.pgid)).toBe(100);
- expect(diagnostics.processes[0]?.childPids).toEqual([102]);
- }),
- );
+ const diagnostics = yield* Effect.gen(function* () {
+ const processDiagnostics = yield* ProcessDiagnostics.ProcessDiagnostics;
+ return yield* processDiagnostics.read;
+ }).pipe(Effect.provide(layer));
- it.effect("preserves ascending sibling order for nested descendants", () =>
- Effect.sync(() => {
- const diagnostics = ProcessDiagnostics.aggregateProcessDiagnostics({
- serverPid: 100,
- readAt: DateTime.makeUnsafe("2026-05-05T10:00:00.000Z"),
- rows: [
- {
- pid: 101,
- ppid: 100,
- pgid: 100,
- status: "S",
- cpuPercent: 0,
- rssBytes: 100,
- elapsed: "00:10",
- command: "agent",
- },
- {
- pid: 103,
- ppid: 101,
- pgid: 100,
- status: "S",
- cpuPercent: 0,
- rssBytes: 100,
- elapsed: "00:10",
- command: "child-b",
- },
- {
- pid: 102,
- ppid: 101,
- pgid: 100,
- status: "S",
- cpuPercent: 0,
- rssBytes: 100,
- elapsed: "00:10",
- command: "child-a",
- },
- ],
- });
-
- expect(diagnostics.processes.map((process) => process.pid)).toEqual([101, 102, 103]);
+ expect(diagnostics.processes.map((process) => process.pid)).toEqual([4242]);
+ expect(diagnostics.processes[0]?.startTimeMs).toBe(2_000);
+ expect(diagnostics.processes[0]?.cpuPercent).toBe(1.5);
+ expect(diagnostics.processes[0]?.rssBytes).toBe(2_048);
}),
);
- it.effect("queries processes through the ChildProcessSpawner service", () =>
+ it.effect("rejects stale process identities before signaling", () =>
Effect.gen(function* () {
- const commands: Array<{ readonly command: string; readonly args: ReadonlyArray<string> }> =
- [];
- const spawnerLayer = Layer.succeed(
- ChildProcessSpawner.ChildProcessSpawner,
- ChildProcessSpawner.make((command) => {
- const childProcess = command as unknown as {
- readonly command: string;
- readonly args: ReadonlyArray<string>;
- };
- commands.push({ command: childProcess.command, args: childProcess.args });
- return Effect.succeed(
- mockHandle({
- stdout: [
- ` ${process.pid} 1 ${process.pid} Ss 0.0 1024 01:02.03 t3 server`,
- ` 4242 ${process.pid} ${process.pid} S 1.5 2048 00:04 agent`,
- ].join("\n"),
- }),
- );
- }),
- );
- const layer = ProcessDiagnostics.layer.pipe(Layer.provide(spawnerLayer));
+ const snapshot = makeNativeSnapshot([]);
+ const telemetryLayer = makeTelemetryLayer(snapshot);
+ const layer = ProcessDiagnostics.layer.pipe(Layer.provide(telemetryLayer));
- const diagnostics = yield* Effect.service(ProcessDiagnostics.ProcessDiagnostics).pipe(
- Effect.flatMap((pd) => pd.read),
+ const result = yield* Effect.service(ProcessDiagnostics.ProcessDiagnostics).pipe(
+ Effect.flatMap((processDiagnostics) =>
+ processDiagnostics.signal({
+ pid: 4_242,
+ startTimeMs: 2_000,
+ signal: "SIGINT",
+ }),
+ ),
Effect.provide(layer),
);
- expect(diagnostics.processes.map((process) => process.pid)).toEqual([4242]);
- expect(commands).toEqual([
- {
- command: "ps",
- args: ["-axo", "pid=,ppid=,pgid=,stat=,pcpu=,rss=,etime=,command="],
- },
- ]);
+ expect(result).toEqual({
+ pid: 4242,
+ signal: "SIGINT",
+ signaled: false,
+ message: Option.some("Process 4242 no longer matches the selected process identity."),
+ });
}),
);
- it.effect("keeps bounded command diagnostics when the process query exits unsuccessfully", () =>
+ it.effect("refuses to signal when a fresh identity check cannot be collected", () =>
Effect.gen(function* () {
- const spawnerLayer = Layer.succeed(
- ChildProcessSpawner.ChildProcessSpawner,
- ChildProcessSpawner.make(() =>
- Effect.succeed(
- mockHandle({
- code: 17,
- stdout: "partial process output",
- stderr: "process access denied",
+ const snapshot = makeNativeSnapshot([
+ {
+ pid: 4_242,
+ ppid: process.pid,
+ startTimeMs: 2_000,
+ runTimeMs: 4_000,
+ name: "agent",
+ command: "codex app-server",
+ status: "Running",
+ cpuPercent: 1.5,
+ cpuTimeMs: 60,
+ residentBytes: 2_048,
+ virtualBytes: 4_096,
+ ioReadBytes: 300,
+ ioWriteBytes: 400,
+ ioSemantics: "storage",
+ },
+ ]);
+ const staleTelemetry = yield* Effect.service(ResourceTelemetry.ResourceTelemetry).pipe(
+ Effect.flatMap((telemetry) => telemetry.latest),
+ Effect.provide(makeTelemetryLayer(snapshot)),
+ );
+ const telemetryLayer = Layer.succeed(
+ ResourceTelemetry.ResourceTelemetry,
+ ResourceTelemetry.ResourceTelemetry.of({
+ latest: Effect.succeed(staleTelemetry),
+ changes: Stream.empty,
+ subscribe: Effect.die("unused"),
+ readHistory: () => Effect.die("unused"),
+ refresh: Effect.fail(
+ new ResourceTelemetry.ResourceTelemetryRefreshFailed({
+ operation: "refresh",
+ cause: new Error("collector unavailable"),
}),
),
- ),
+ validateProcessIdentity: () => Effect.die("unused"),
+ retry: Effect.die("unused"),
+ }),
);
+ const layer = ProcessDiagnostics.layer.pipe(Layer.provide(telemetryLayer));
- const error = yield* ProcessDiagnostics.readProcessRows.pipe(
- Effect.provide(spawnerLayer),
- Effect.provideService(HostProcessPlatform, "linux"),
- Effect.flip,
+ const result = yield* Effect.service(ProcessDiagnostics.ProcessDiagnostics).pipe(
+ Effect.flatMap((processDiagnostics) =>
+ processDiagnostics.signal({
+ pid: 4_242,
+ startTimeMs: 2_000,
+ signal: "SIGINT",
+ }),
+ ),
+ Effect.provide(layer),
);
- expect(error).toMatchObject({
- _tag: "ProcessDiagnosticsQueryFailedError",
- command: "ps",
- argCount: 2,
- cwd: process.cwd(),
- exitCode: 17,
- stdoutBytes: 22,
- stderrBytes: 21,
- stdoutTruncated: false,
- stderrTruncated: false,
+ expect(result).toEqual({
+ pid: 4_242,
+ signal: "SIGINT",
+ signaled: false,
+ message: Option.some(
+ "Could not refresh process 4242; refusing to signal a stale identity.",
+ ),
});
- expect(error.message).toBe(
- `Process diagnostics query 'ps' failed with exit code 17 in '${process.cwd()}'.`,
- );
}),
);
- it.effect("does not allow signaling the diagnostics query process", () =>
+ it.effect("rejects Electron processes as signal targets", () =>
Effect.gen(function* () {
- const spawnerLayer = Layer.succeed(
- ChildProcessSpawner.ChildProcessSpawner,
- ChildProcessSpawner.make(() =>
- Effect.succeed(
- mockHandle({
- stdout: [
- ` ${process.pid} 1 ${process.pid} Ss 0.0 1024 01:02.03 t3 server`,
- ` 4242 ${process.pid} ${process.pid} R 1.5 2048 00:00 ps -axo pid=,ppid=,pgid=,stat=,pcpu=,rss=,etime=,command=`,
- ].join("\n"),
- }),
- ),
- ),
+ const sampledAtUnixMs = DateTime.toEpochMillis(
+ DateTime.makeUnsafe("2026-05-05T10:00:00.000Z"),
);
- const layer = ProcessDiagnostics.layer.pipe(Layer.provide(spawnerLayer));
+ const snapshot = makeNativeSnapshot([
+ {
+ pid: 4_242,
+ ppid: 1,
+ startTimeMs: 2_000,
+ runTimeMs: 4_000,
+ name: "electron",
+ command: "electron",
+ status: "Running",
+ cpuPercent: 1.5,
+ cpuTimeMs: 60,
+ residentBytes: 2_048,
+ virtualBytes: 4_096,
+ ioReadBytes: 300,
+ ioWriteBytes: 400,
+ ioSemantics: "storage",
+ },
+ ]);
+ const sampledAt = DateTime.makeUnsafe(sampledAtUnixMs);
+ const telemetryLayer = makeTelemetryLayer(snapshot, {
+ version: 1,
+ type: "desktopTelemetry",
+ sequence: 1,
+ sampledAtUnixMs,
+ electronPid: 4_242,
+ power: {
+ source: "electron-main",
+ idle: "false",
+ idleSeconds: 0,
+ locked: "false",
+ suspended: false,
+ onBattery: "false",
+ lowPowerMode: "unknown",
+ thermalState: "nominal",
+ stale: false,
+ updatedAt: sampledAt,
+ },
+ speedLimitPercent: Option.none(),
+ electronProcesses: [
+ {
+ pid: 4_242,
+ creationTimeMs: 2_000,
+ type: "Browser",
+ name: "electron",
+ cpuPercent: 1.5,
+ idleWakeupsPerSecond: 0,
+ workingSetBytes: 2_048,
+ peakWorkingSetBytes: 2_048,
+ },
+ ],
+ });
+ const layer = ProcessDiagnostics.layer.pipe(Layer.provide(telemetryLayer));
const result = yield* Effect.service(ProcessDiagnostics.ProcessDiagnostics).pipe(
- Effect.flatMap((pd) => pd.signal({ pid: 4242, signal: "SIGINT" })),
+ Effect.flatMap((processDiagnostics) =>
+ processDiagnostics.signal({
+ pid: 4_242,
+ startTimeMs: 2_000,
+ signal: "SIGKILL",
+ }),
+ ),
Effect.provide(layer),
);
expect(result).toEqual({
- pid: 4242,
- signal: "SIGINT",
+ pid: 4_242,
+ signal: "SIGKILL",
signaled: false,
- message: Option.some("Process 4242 is not a live descendant of the T3 server."),
+ message: Option.some("Process 4242 is not a signalable T3 backend descendant."),
});
+
+ const diagnostics = yield* Effect.service(ProcessDiagnostics.ProcessDiagnostics).pipe(
+ Effect.flatMap((processDiagnostics) => processDiagnostics.read),
+ Effect.provide(layer),
+ );
+ expect(diagnostics.processes).toEqual([]);
+ expect(diagnostics.processCount).toBe(0);
+ expect(diagnostics.totalCpuPercent).toBe(0);
+ expect(diagnostics.totalRssBytes).toBe(0);
}),
);
});
diff --git a/apps/server/src/diagnostics/ProcessDiagnostics.ts b/apps/server/src/diagnostics/ProcessDiagnostics.ts
index b39d560a2..8aeb7ba24 100644
--- a/apps/server/src/diagnostics/ProcessDiagnostics.ts
+++ b/apps/server/src/diagnostics/ProcessDiagnostics.ts
@@ -1,105 +1,20 @@
import type {
+ ResourceTelemetryProcessCategory,
ServerProcessDiagnosticsEntry,
ServerProcessDiagnosticsResult,
ServerProcessSignal,
ServerSignalProcessResult,
} from "@t3tools/contracts";
-import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
import * as Context from "effect/Context";
-import * as DateTime from "effect/DateTime";
-import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";
-import * as ChildProcess from "effect/unstable/process/ChildProcess";
-import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
-import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
+import * as ResourceTelemetry from "../resourceTelemetry/ResourceTelemetry.ts";
-export interface ProcessRow {
- readonly pid: number;
- readonly ppid: number;
- readonly pgid: number | null;
- readonly status: string;
- readonly cpuPercent: number;
- readonly rssBytes: number;
- readonly elapsed: string;
- readonly command: string;
-}
-
-const PROCESS_QUERY_TIMEOUT_MS = 1_000;
-const POSIX_PROCESS_QUERY_COMMAND = "pid=,ppid=,pgid=,stat=,pcpu=,rss=,etime=,command=";
-const PROCESS_QUERY_MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
-
-export class ProcessDiagnostics extends Context.Service<
- ProcessDiagnostics,
- {
- readonly read: Effect.Effect<ServerProcessDiagnosticsResult>;
- readonly signal: (input: {
- readonly pid: number;
- readonly signal: ServerProcessSignal;
- }) => Effect.Effect<ServerSignalProcessResult>;
- }
->()("t3/diagnostics/ProcessDiagnostics") {}
-
-class ProcessDiagnosticsQueryTimeoutError extends Schema.TaggedErrorClass<ProcessDiagnosticsQueryTimeoutError>()(
- "ProcessDiagnosticsQueryTimeoutError",
- {
- command: Schema.String,
- argCount: Schema.Number,
- cwd: Schema.String,
- timeoutMillis: Schema.Number,
- },
-) {
- override get message(): string {
- return `Process diagnostics query '${this.command}' timed out after ${this.timeoutMillis}ms in '${this.cwd}'.`;
- }
-}
-
-class ProcessDiagnosticsQueryFailedError extends Schema.TaggedErrorClass<ProcessDiagnosticsQueryFailedError>()(
- "ProcessDiagnosticsQueryFailedError",
- {
- command: Schema.String,
- argCount: Schema.Number,
- cwd: Schema.String,
- exitCode: Schema.optional(Schema.Number),
- stdoutBytes: Schema.optional(Schema.Number),
- stderrBytes: Schema.optional(Schema.Number),
- stdoutTruncated: Schema.optional(Schema.Boolean),
- stderrTruncated: Schema.optional(Schema.Boolean),
- cause: Schema.optional(Schema.Defect()),
- },
-) {
- override get message(): string {
- const exitCode = this.exitCode === undefined ? "" : ` with exit code ${this.exitCode}`;
- return `Process diagnostics query '${this.command}' failed${exitCode} in '${this.cwd}'.`;
- }
-}
-
-class ProcessDiagnosticsServerProcessSignalError extends Schema.TaggedErrorClass<ProcessDiagnosticsServerProcessSignalError>()(
- "ProcessDiagnosticsServerProcessSignalError",
- { pid: Schema.Number },
-) {
- override get message(): string {
- return "Refusing to signal the T3 server process.";
- }
-}
-
-class ProcessDiagnosticsNotDescendantError extends Schema.TaggedErrorClass<ProcessDiagnosticsNotDescendantError>()(
- "ProcessDiagnosticsNotDescendantError",
- {
- pid: Schema.Number,
- serverPid: Schema.Number,
- },
-) {
- override get message(): string {
- return `Process ${this.pid} is not a live descendant of the T3 server.`;
- }
-}
-
-class ProcessDiagnosticsSignalFailedError extends Schema.TaggedErrorClass<ProcessDiagnosticsSignalFailedError>()(
- "ProcessDiagnosticsSignalFailedError",
+export class ProcessSignalFailed extends Schema.TaggedErrorClass<ProcessSignalFailed>()(
+ "ProcessSignalFailed",
{
pid: Schema.Number,
signal: Schema.String,
@@ -111,458 +26,136 @@ class ProcessDiagnosticsSignalFailedError extends Schema.TaggedErrorClass<Proces
}
}
-const ProcessDiagnosticsError = Schema.Union([
- ProcessDiagnosticsQueryTimeoutError,
- ProcessDiagnosticsQueryFailedError,
- ProcessDiagnosticsServerProcessSignalError,
- ProcessDiagnosticsNotDescendantError,
- ProcessDiagnosticsSignalFailedError,
-]);
-type ProcessDiagnosticsError = typeof ProcessDiagnosticsError.Type;
-const isProcessDiagnosticsError = Schema.is(ProcessDiagnosticsError);
-
-function parsePositiveInt(value: string): number | null {
- const parsed = Number.parseInt(value, 10);
- return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
-}
-
-function parseNonNegativeInt(value: string): number | null {
- const parsed = Number.parseInt(value, 10);
- return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
-}
-
-function parseNumber(value: string): number | null {
- const parsed = Number.parseFloat(value);
- return Number.isFinite(parsed) ? parsed : null;
-}
-
-export function parsePosixProcessRows(output: string): ReadonlyArray<ProcessRow> {
- const rows: ProcessRow[] = [];
- const rowPattern =
- /^\s*(\d+)\s+(\d+)\s+(-?\d+)\s+(\S+)\s+([+-]?(?:\d+\.?\d*|\.\d+))\s+(\d+)\s+(\S+)\s+(.+)$/;
-
- for (const line of output.split(/\r?\n/)) {
- if (line.trim().length === 0) continue;
-
- const match = rowPattern.exec(line);
- if (!match) continue;
-
- const pidText = match[1];
- const ppidText = match[2];
- const pgidText = match[3];
- const status = match[4];
- const cpuText = match[5];
- const rssText = match[6];
- const elapsed = match[7];
- const command = match[8];
- if (
- pidText === undefined ||
- ppidText === undefined ||
- pgidText === undefined ||
- status === undefined ||
- cpuText === undefined ||
- rssText === undefined ||
- elapsed === undefined ||
- command === undefined
- ) {
- continue;
- }
-
- const pid = parsePositiveInt(pidText);
- const ppid = parseNonNegativeInt(ppidText);
- const pgid = Number.parseInt(pgidText, 10);
- const cpuPercent = parseNumber(cpuText);
- const rssKiB = parseNonNegativeInt(rssText);
- if (
- pid === null ||
- ppid === null ||
- !Number.isInteger(pgid) ||
- cpuPercent === null ||
- rssKiB === null ||
- !status ||
- !elapsed ||
- !command
- ) {
- continue;
- }
-
- rows.push({
- pid,
- ppid,
- pgid,
- status,
- cpuPercent,
- rssBytes: rssKiB * 1024,
- elapsed,
- command,
- });
- }
-
- return rows;
-}
-
-function normalizeWindowsProcessRow(value: unknown): ProcessRow | null {
- if (typeof value !== "object" || value === null) return null;
- const record = value as Record<string, unknown>;
- const pid = typeof record.ProcessId === "number" ? record.ProcessId : null;
- const ppid = typeof record.ParentProcessId === "number" ? record.ParentProcessId : null;
- const commandLine =
- typeof record.CommandLine === "string" && record.CommandLine.trim().length > 0
- ? record.CommandLine
- : typeof record.Name === "string"
- ? record.Name
- : null;
- const workingSet =
- typeof record.WorkingSetSize === "number" && Number.isFinite(record.WorkingSetSize)
- ? Math.max(0, Math.round(record.WorkingSetSize))
- : 0;
- const cpuPercent =
- typeof record.PercentProcessorTime === "number" && Number.isFinite(record.PercentProcessorTime)
- ? Math.max(0, record.PercentProcessorTime)
- : 0;
-
- if (!pid || pid <= 0 || ppid === null || ppid < 0 || !commandLine) return null;
- return {
- pid,
- ppid,
- pgid: null,
- status: typeof record.Status === "string" && record.Status.length > 0 ? record.Status : "Live",
- cpuPercent,
- rssBytes: workingSet,
- elapsed: "",
- command: commandLine,
- };
-}
-
-function parseWindowsProcessRows(output: string): ReadonlyArray<ProcessRow> {
- if (output.trim().length === 0) return [];
- try {
- const parsed = JSON.parse(output) as unknown;
- const records = Array.isArray(parsed) ? parsed : [parsed];
- return records.flatMap((record) => {
- const row = normalizeWindowsProcessRow(record);
- return row ? [row] : [];
- });
- } catch {
- return [];
- }
-}
-
-export function buildDescendantEntries(
- rows: ReadonlyArray<ProcessRow>,
- serverPid: number,
-): ReadonlyArray<ServerProcessDiagnosticsEntry> {
- const childrenByParent = new Map<number, ProcessRow[]>();
- for (const row of rows) {
- const children = childrenByParent.get(row.ppid) ?? [];
- children.push(row);
- childrenByParent.set(row.ppid, children);
- }
-
- const entries: ServerProcessDiagnosticsEntry[] = [];
- const visited = new Set<number>();
- const stack = [...(childrenByParent.get(serverPid) ?? [])]
- .toSorted((left, right) => left.pid - right.pid)
- .map((row) => ({ row, depth: 0 }));
-
- while (stack.length > 0) {
- const item = stack.shift();
- if (!item || visited.has(item.row.pid)) continue;
- visited.add(item.row.pid);
-
- const children = [...(childrenByParent.get(item.row.pid) ?? [])].toSorted(
- (left, right) => left.pid - right.pid,
- );
- entries.push({
- pid: item.row.pid,
- ppid: item.row.ppid,
- pgid: Option.fromNullishOr(item.row.pgid),
- status: item.row.status,
- cpuPercent: item.row.cpuPercent,
- rssBytes: item.row.rssBytes,
- elapsed: item.row.elapsed || "n/a",
- command: item.row.command,
- depth: item.depth,
- childPids: children.map((child) => child.pid),
- });
-
- stack.unshift(...children.map((row) => ({ row, depth: item.depth + 1 })));
+export class ProcessDiagnostics extends Context.Service<
+ ProcessDiagnostics,
+ {
+ readonly read: Effect.Effect<ServerProcessDiagnosticsResult>;
+ readonly signal: (input: {
+ readonly pid: number;
+ readonly startTimeMs: number;
+ readonly signal: ServerProcessSignal;
+ }) => Effect.Effect<ServerSignalProcessResult>;
}
+>()("t3/diagnostics/ProcessDiagnostics") {}
- return entries;
+function formatElapsed(runTimeMs: number): string {
+ const totalSeconds = Math.max(0, Math.floor(runTimeMs / 1_000));
+ const hours = Math.floor(totalSeconds / 3_600);
+ const minutes = Math.floor((totalSeconds % 3_600) / 60);
+ const seconds = totalSeconds % 60;
+ return hours > 0
+ ? `${hours}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`
+ : `${minutes}:${String(seconds).padStart(2, "0")}`;
}
-export function isDiagnosticsQueryProcess(row: ProcessRow, serverPid: number): boolean {
- if (row.ppid !== serverPid) return false;
-
- const command = row.command.trim();
+function canSignalCategory(category: ResourceTelemetryProcessCategory): boolean {
return (
- /(?:^|[/\\])ps\s+-axo\s+pid=,ppid=,pgid=,stat=,pcpu=,rss=,etime=,command=/.test(command) ||
- (/\bpowershell(?:\.exe)?\b/i.test(command) &&
- /\bGet-CimInstance\s+Win32_Process\b/i.test(command))
+ category === "server-child" || category === "provider-root" || category === "terminal-root"
);
}
-function makeResult(input: {
- readonly serverPid: number;
- readonly rows: ReadonlyArray<ProcessRow>;
- readonly readAt: DateTime.Utc;
- readonly error?: string;
-}): ServerProcessDiagnosticsResult {
- const readAt = input.readAt;
- const rows = input.rows.filter((row) => !isDiagnosticsQueryProcess(row, input.serverPid));
- const processes = buildDescendantEntries(rows, input.serverPid);
- const totalRssBytes = processes.reduce((total, process) => total + process.rssBytes, 0);
- const totalCpuPercent = processes.reduce((total, process) => total + process.cpuPercent, 0);
-
- return {
- serverPid: input.serverPid,
- readAt,
- processCount: processes.length,
- totalRssBytes,
- totalCpuPercent,
- processes,
- error: input.error ? Option.some({ message: input.error }) : Option.none(),
- };
-}
-
-interface ProcessOutput {
- readonly cwd: string;
- readonly exitCode: number;
- readonly stdout: string;
- readonly stdoutBytes: number;
- readonly stdoutTruncated: boolean;
- readonly stderr: string;
- readonly stderrBytes: number;
- readonly stderrTruncated: boolean;
-}
-
-const runProcess = Effect.fn("runProcess")(function* (input: {
- readonly command: string;
- readonly args: ReadonlyArray<string>;
-}) {
- const cwd = process.cwd();
- return yield* Effect.gen(function* () {
- const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
- // `ps` and `powershell.exe` are real executables; spawning through cmd.exe
- // shell mode would re-tokenize the PowerShell `-Command` payload (which
- // contains pipes) before PowerShell ever sees it.
- const child = yield* spawner.spawn(
- ChildProcess.make(input.command, input.args, {
- cwd,
- }),
- );
- const [stdout, stderr, exitCode] = yield* Effect.all(
- [
- collectUint8StreamText({
- stream: child.stdout,
- maxBytes: PROCESS_QUERY_MAX_OUTPUT_BYTES,
- truncatedMarker: "\n\n[truncated]",
- }),
- collectUint8StreamText({
- stream: child.stderr,
- maxBytes: PROCESS_QUERY_MAX_OUTPUT_BYTES,
- truncatedMarker: "\n\n[truncated]",
- }),
- child.exitCode,
- ],
- { concurrency: "unbounded" },
- );
-
- return {
- cwd,
- exitCode,
- stdout: stdout.text,
- stdoutBytes: stdout.bytes,
- stdoutTruncated: stdout.truncated,
- stderr: stderr.text,
- stderrBytes: stderr.bytes,
- stderrTruncated: stderr.truncated,
- } satisfies ProcessOutput;
- }).pipe(
- Effect.scoped,
- Effect.timeoutOption(Duration.millis(PROCESS_QUERY_TIMEOUT_MS)),
- Effect.flatMap((result) =>
- Option.match(result, {
- onNone: () =>
- Effect.fail(
- new ProcessDiagnosticsQueryTimeoutError({
- command: input.command,
- argCount: input.args.length,
- cwd,
- timeoutMillis: PROCESS_QUERY_TIMEOUT_MS,
- }),
- ),
- onSome: Effect.succeed,
- }),
- ),
- Effect.mapError((cause) =>
- isProcessDiagnosticsError(cause)
- ? cause
- : new ProcessDiagnosticsQueryFailedError({
- command: input.command,
- argCount: input.args.length,
- cwd,
- cause,
+export const make = Effect.fn("makeProcessDiagnostics")(function* () {
+ const telemetry = yield* ResourceTelemetry.ResourceTelemetry;
+ const refreshedTelemetry = telemetry.refresh.pipe(Effect.catch(() => telemetry.latest));
+ const read: ProcessDiagnostics["Service"]["read"] = refreshedTelemetry.pipe(
+ Effect.map((snapshot) => {
+ const processes = snapshot.processes
+ .filter((entry) => canSignalCategory(entry.category))
+ .map(
+ (entry): ServerProcessDiagnosticsEntry => ({
+ pid: entry.identity.pid,
+ startTimeMs: entry.identity.startTimeMs,
+ ppid: entry.ppid,
+ pgid: Option.none(),
+ status: entry.status || "Unknown",
+ cpuPercent: entry.cpuPercent,
+ rssBytes: entry.residentBytes,
+ elapsed: formatElapsed(entry.runTimeMs),
+ command: entry.command || entry.name || "unknown",
+ depth: Math.max(0, entry.depth - 1),
+ childPids: entry.childPids,
}),
- ),
- );
-});
-
-function readPosixProcessRows(): Effect.Effect<
- ReadonlyArray<ProcessRow>,
- ProcessDiagnosticsError,
- ChildProcessSpawner.ChildProcessSpawner
-> {
- return runProcess({
- command: "ps",
- args: ["-axo", POSIX_PROCESS_QUERY_COMMAND],
- }).pipe(
- Effect.flatMap((result) =>
- result.exitCode !== 0
- ? Effect.fail(
- new ProcessDiagnosticsQueryFailedError({
- command: "ps",
- argCount: 2,
- cwd: result.cwd,
- exitCode: result.exitCode,
- stdoutBytes: result.stdoutBytes,
- stderrBytes: result.stderrBytes,
- stdoutTruncated: result.stdoutTruncated,
- stderrTruncated: result.stderrTruncated,
- }),
- )
- : Effect.succeed(parsePosixProcessRows(result.stdout)),
- ),
- );
-}
-
-function readWindowsProcessRows(): Effect.Effect<
- ReadonlyArray<ProcessRow>,
- ProcessDiagnosticsError,
- ChildProcessSpawner.ChildProcessSpawner
-> {
- const command = [
- "$processes = Get-CimInstance Win32_Process | ForEach-Object {",
- '$perf = Get-CimInstance Win32_PerfFormattedData_PerfProc_Process -Filter "IDProcess = $($_.ProcessId)" -ErrorAction SilentlyContinue;',
- "[pscustomobject]@{ ProcessId = $_.ProcessId; ParentProcessId = $_.ParentProcessId; Name = $_.Name; CommandLine = $_.CommandLine; Status = $_.Status; WorkingSetSize = $_.WorkingSetSize; PercentProcessorTime = if ($perf) { $perf.PercentProcessorTime } else { 0 } }",
- "};",
- "$processes | ConvertTo-Json -Compress -Depth 3",
- ].join(" ");
-
- return runProcess({
- command: "powershell.exe",
- args: ["-NoProfile", "-NonInteractive", "-Command", command],
- }).pipe(
- Effect.flatMap((result) =>
- result.exitCode !== 0
- ? Effect.fail(
- new ProcessDiagnosticsQueryFailedError({
- command: "powershell.exe",
- argCount: 4,
- cwd: result.cwd,
- exitCode: result.exitCode,
- stdoutBytes: result.stdoutBytes,
- stderrBytes: result.stderrBytes,
- stdoutTruncated: result.stdoutTruncated,
- stderrTruncated: result.stderrTruncated,
- }),
- )
- : Effect.succeed(parseWindowsProcessRows(result.stdout)),
- ),
- );
-}
-
-export const readProcessRows = Effect.gen(function* () {
- const platform = yield* HostProcessPlatform;
- return yield* platform === "win32" ? readWindowsProcessRows() : readPosixProcessRows();
-});
-
-export function aggregateProcessDiagnostics(input: {
- readonly serverPid: number;
- readonly rows: ReadonlyArray<ProcessRow>;
- readonly readAt: DateTime.Utc;
-}): ServerProcessDiagnosticsResult {
- return makeResult(input);
-}
-
-function assertDescendantPid(
- pid: number,
-): Effect.Effect<void, ProcessDiagnosticsError, ChildProcessSpawner.ChildProcessSpawner> {
- if (pid === process.pid) {
- return Effect.fail(
- new ProcessDiagnosticsServerProcessSignalError({
- pid,
- }),
- );
- }
-
- return readProcessRows.pipe(
- Effect.flatMap((rows) => {
- const filteredRows = rows.filter((row) => !isDiagnosticsQueryProcess(row, process.pid));
- const descendant = buildDescendantEntries(filteredRows, process.pid).some(
- (entry) => entry.pid === pid,
- );
- return descendant
- ? Effect.void
- : Effect.fail(
- new ProcessDiagnosticsNotDescendantError({
- pid,
- serverPid: process.pid,
- }),
- );
+ );
+ return {
+ serverPid: process.pid,
+ readAt: snapshot.readAt,
+ processCount: processes.length,
+ totalRssBytes: processes.reduce((total, entry) => total + entry.rssBytes, 0),
+ totalCpuPercent: processes.reduce((total, entry) => total + entry.cpuPercent, 0),
+ processes,
+ error: Option.map(snapshot.health.native.lastError, (message) => ({ message })),
+ };
}),
);
-}
-
-export const make = Effect.gen(function* () {
- const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-
- const read: ProcessDiagnostics["Service"]["read"] = Effect.gen(function* () {
- const readAt = yield* DateTime.now;
- const rows = yield* readProcessRows.pipe(
- Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
- );
- return makeResult({ serverPid: process.pid, rows, readAt });
- }).pipe(
- Effect.catch((error: ProcessDiagnosticsError) =>
- DateTime.now.pipe(
- Effect.map((readAt) =>
- makeResult({ serverPid: process.pid, rows: [], readAt, error: error.message }),
- ),
- ),
- ),
- );
const signal: ProcessDiagnostics["Service"]["signal"] = Effect.fn("ProcessDiagnostics.signal")(
function* (input) {
- return yield* assertDescendantPid(input.pid).pipe(
- Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
- Effect.flatMap(() =>
- Effect.try({
- try: () => {
- process.kill(input.pid, input.signal);
- return {
- pid: input.pid,
- signal: input.signal,
- signaled: true,
- message: Option.none(),
- };
- },
- catch: (cause) =>
- new ProcessDiagnosticsSignalFailedError({
- pid: input.pid,
- signal: input.signal,
- cause,
- }),
+ if (input.pid === process.pid) {
+ return {
+ pid: input.pid,
+ signal: input.signal,
+ signaled: false,
+ message: Option.some("Refusing to signal the T3 server process."),
+ };
+ }
+ const current = yield* telemetry.refresh.pipe(Effect.option);
+ if (Option.isNone(current)) {
+ return {
+ pid: input.pid,
+ signal: input.signal,
+ signaled: false,
+ message: Option.some(
+ `Could not refresh process ${input.pid}; refusing to signal a stale identity.`,
+ ),
+ };
+ }
+ const selected = current.value.processes.find(
+ (entry) =>
+ entry.identity.pid === input.pid && entry.identity.startTimeMs === input.startTimeMs,
+ );
+ if (!selected) {
+ return {
+ pid: input.pid,
+ signal: input.signal,
+ signaled: false,
+ message: Option.some(
+ `Process ${input.pid} no longer matches the selected process identity.`,
+ ),
+ };
+ }
+ if (!canSignalCategory(selected.category)) {
+ return {
+ pid: input.pid,
+ signal: input.signal,
+ signaled: false,
+ message: Option.some(`Process ${input.pid} is not a signalable T3 backend descendant.`),
+ };
+ }
+ return yield* Effect.try({
+ try: () => {
+ process.kill(input.pid, input.signal);
+ return {
+ pid: input.pid,
+ signal: input.signal,
+ signaled: true,
+ message: Option.none(),
+ };
+ },
+ catch: (cause) =>
+ new ProcessSignalFailed({
+ pid: input.pid,
+ signal: input.signal,
+ cause,
}),
- ),
- Effect.catch((error: ProcessDiagnosticsError) =>
+ }).pipe(
+ Effect.catch((error) =>
Effect.succeed({
pid: input.pid,
signal: input.signal,
signaled: false,
- message: Option.some(error.message),
+ message: Option.some(
+ error instanceof Error ? error.message : "Failed to signal process.",
+ ),
}),
),
);
@@ -572,4 +165,4 @@ export const make = Effect.gen(function* () {
return ProcessDiagnostics.of({ read, signal });
});
-export const layer = Layer.effect(ProcessDiagnostics, make);
+export const layer = Layer.effect(ProcessDiagnostics, make());
diff --git a/apps/server/src/diagnostics/ProcessResourceMonitor.test.ts b/apps/server/src/diagnostics/ProcessResourceMonitor.test.ts
index d9c4eb06e..1a1943ecf 100644
--- a/apps/server/src/diagnostics/ProcessResourceMonitor.test.ts
+++ b/apps/server/src/diagnostics/ProcessResourceMonitor.test.ts
@@ -1,255 +1,170 @@
import { describe, expect, it } from "@effect/vitest";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import * as ResourceTelemetry from "../resourceTelemetry/ResourceTelemetry.ts";
+import type { ResourceTelemetryHistoryWithLegacyBuckets } from "../resourceTelemetry/ResourceTelemetryHistory.ts";
import * as ProcessResourceMonitor from "./ProcessResourceMonitor.ts";
describe("ProcessResourceMonitor", () => {
- it.effect("samples the server root process and descendants", () =>
- Effect.sync(() => {
- const sampledAt = DateTime.makeUnsafe("2026-05-05T10:00:00.000Z");
- const samples = ProcessResourceMonitor.collectMonitoredSamples({
- serverPid: 100,
- sampledAt,
- sampledAtMs: DateTime.toEpochMillis(sampledAt),
- rows: [
- {
- pid: 100,
- ppid: 1,
- pgid: 100,
- status: "S",
- cpuPercent: 2,
- rssBytes: 1_000,
- elapsed: "01:00",
- command: "t3 server",
- },
+ it.effect("projects resource telemetry history into the legacy diagnostics contract", () =>
+ Effect.gen(function* () {
+ const readAt = DateTime.makeUnsafe("2026-05-05T10:00:00.000Z");
+ const history: ResourceTelemetryHistoryWithLegacyBuckets = {
+ readAt,
+ windowMs: 60_000,
+ bucketMs: 10_000,
+ sampleIntervalMs: 1_000,
+ retainedSampleCount: 2,
+ buckets: [
{
- pid: 101,
- ppid: 100,
- pgid: 100,
- status: "S",
- cpuPercent: 10,
- rssBytes: 2_000,
- elapsed: "00:20",
- command: "codex app-server",
+ startedAt: DateTime.makeUnsafe("2026-05-05T09:59:50.000Z"),
+ endedAt: readAt,
+ avgCpuPercent: 15,
+ maxCpuPercent: 25,
+ maxRssBytes: 4_096,
+ ioReadBytes: 1_024,
+ ioWriteBytes: 2_048,
+ maxProcessCount: 2,
},
+ ],
+ legacyBackendBuckets: [
{
- pid: 102,
- ppid: 101,
- pgid: 100,
- status: "R",
- cpuPercent: 50,
- rssBytes: 3_000,
- elapsed: "00:05",
- command: "rg needle",
+ startedAt: DateTime.makeUnsafe("2026-05-05T09:59:50.000Z"),
+ endedAt: readAt,
+ avgCpuPercent: 5,
+ maxCpuPercent: 8,
+ maxRssBytes: 4_096,
+ ioReadBytes: 1_024,
+ ioWriteBytes: 2_048,
+ maxProcessCount: 1,
},
+ ],
+ topProcesses: [
{
- pid: 200,
+ identity: { pid: process.pid, startTimeMs: 100 },
ppid: 1,
- pgid: 200,
- status: "R",
- cpuPercent: 99,
- rssBytes: 9_000,
- elapsed: "00:05",
- command: "unrelated",
+ depth: 0,
+ name: "node",
+ command: "t3 server",
+ category: "server",
+ firstSeenAt: DateTime.makeUnsafe("2026-05-05T09:59:55.000Z"),
+ lastSeenAt: readAt,
+ currentCpuPercent: 5,
+ avgCpuPercent: 4,
+ maxCpuPercent: 8,
+ cpuTimeMs: 1_500,
+ currentRssBytes: 2_048,
+ peakRssBytes: 4_096,
+ ioReadBytes: 1_024,
+ ioWriteBytes: 2_048,
+ ioSemantics: "storage",
+ sampleCount: 2,
},
- ],
- });
-
- expect(samples.map((sample) => sample.pid)).toEqual([100, 101, 102]);
- expect(samples.map((sample) => sample.depth)).toEqual([0, 1, 2]);
- expect(samples[0]?.isServerRoot).toBe(true);
- expect(samples[1]?.isServerRoot).toBe(false);
- }),
- );
-
- it.effect("rolls samples up by process and CPU time", () =>
- Effect.sync(() => {
- const firstAt = DateTime.makeUnsafe("2026-05-05T10:00:00.000Z");
- const secondAt = DateTime.makeUnsafe("2026-05-05T10:00:05.000Z");
- const samples = [
- ...ProcessResourceMonitor.collectMonitoredSamples({
- serverPid: 100,
- sampledAt: firstAt,
- sampledAtMs: DateTime.toEpochMillis(firstAt),
- rows: [
- {
- pid: 100,
- ppid: 1,
- pgid: 100,
- status: "S",
- cpuPercent: 10,
- rssBytes: 1_000,
- elapsed: "01:00",
- command: "t3 server",
- },
- ],
- }),
- ...ProcessResourceMonitor.collectMonitoredSamples({
- serverPid: 100,
- sampledAt: secondAt,
- sampledAtMs: DateTime.toEpochMillis(secondAt),
- rows: [
- {
- pid: 100,
- ppid: 1,
- pgid: 100,
- status: "S",
- cpuPercent: 30,
- rssBytes: 2_000,
- elapsed: "01:05",
- command: "t3 server",
- },
- ],
- }),
- ];
-
- const result = ProcessResourceMonitor.aggregateProcessResourceHistory({
- samples,
- readAt: secondAt,
- readAtMs: DateTime.toEpochMillis(secondAt),
- windowMs: 60_000,
- bucketMs: 10_000,
- lastFailure: null,
- });
-
- expect(Option.isNone(result.error)).toBe(true);
- expect(result.topProcesses).toHaveLength(1);
- expect(result.topProcesses[0]?.avgCpuPercent).toBe(20);
- expect(result.topProcesses[0]?.maxCpuPercent).toBe(30);
- expect(result.topProcesses[0]?.cpuSecondsApprox).toBe(2);
- expect(result.totalCpuSecondsApprox).toBe(2);
- expect(result.buckets.some((bucket) => bucket.maxCpuPercent === 30)).toBe(true);
- }),
- );
-
- it.effect("keeps a process grouped when elapsed time drifts between samples", () =>
- Effect.sync(() => {
- const firstAt = DateTime.makeUnsafe("2026-05-05T10:00:00.400Z");
- const secondAt = DateTime.makeUnsafe("2026-05-05T10:00:05.900Z");
- const samples = [
- ...ProcessResourceMonitor.collectMonitoredSamples({
- serverPid: 100,
- sampledAt: firstAt,
- sampledAtMs: DateTime.toEpochMillis(firstAt),
- rows: [
- {
- pid: 100,
- ppid: 1,
- pgid: 100,
- status: "S",
- cpuPercent: 1,
- rssBytes: 1_000,
- elapsed: "01:00",
- command: "t3 server",
- },
- ],
- }),
- ...ProcessResourceMonitor.collectMonitoredSamples({
- serverPid: 100,
- sampledAt: secondAt,
- sampledAtMs: DateTime.toEpochMillis(secondAt),
- rows: [
- {
- pid: 100,
- ppid: 1,
- pgid: 100,
- status: "S",
- cpuPercent: 2,
- rssBytes: 2_000,
- elapsed: "01:06",
- command: "t3 server",
- },
- ],
- }),
- ];
-
- const result = ProcessResourceMonitor.aggregateProcessResourceHistory({
- samples,
- readAt: secondAt,
- readAtMs: DateTime.toEpochMillis(secondAt),
- windowMs: 60_000,
- bucketMs: 10_000,
- lastFailure: null,
- });
-
- expect(result.topProcesses).toHaveLength(1);
- expect(result.topProcesses[0]?.isServerRoot).toBe(true);
- expect(result.topProcesses[0]?.sampleCount).toBe(2);
- expect(result.topProcesses[0]?.maxRssBytes).toBe(2_000);
- }),
- );
-
- it.effect("returns all process summaries in the selected window", () =>
- Effect.sync(() => {
- const sampledAt = DateTime.makeUnsafe("2026-05-05T10:00:00.000Z");
- const samples = ProcessResourceMonitor.collectMonitoredSamples({
- serverPid: 100,
- sampledAt,
- sampledAtMs: DateTime.toEpochMillis(sampledAt),
- rows: [
{
- pid: 100,
+ identity: { pid: 5_000, startTimeMs: 200 },
ppid: 1,
- pgid: 100,
- status: "S",
- cpuPercent: 1,
- rssBytes: 1_000,
- elapsed: "01:00",
- command: "t3 server",
+ depth: 0,
+ name: "electron",
+ command: "electron",
+ category: "electron-main",
+ firstSeenAt: DateTime.makeUnsafe("2026-05-05T09:59:55.000Z"),
+ lastSeenAt: readAt,
+ currentCpuPercent: 50,
+ avgCpuPercent: 40,
+ maxCpuPercent: 80,
+ cpuTimeMs: 15_000,
+ currentRssBytes: 20_480,
+ peakRssBytes: 40_960,
+ ioReadBytes: 10_240,
+ ioWriteBytes: 20_480,
+ ioSemantics: "storage",
+ sampleCount: 2,
},
- ...Array.from({ length: 35 }, (_, index) => ({
- pid: 200 + index,
- ppid: index === 0 ? 100 : 199 + index,
- pgid: 100,
- status: "S",
- cpuPercent: 35 - index,
- rssBytes: 2_000 + index,
- elapsed: "00:10",
- command: `worker ${index}`,
- })),
],
- });
-
- const result = ProcessResourceMonitor.aggregateProcessResourceHistory({
- samples,
- readAt: sampledAt,
- readAtMs: DateTime.toEpochMillis(sampledAt),
- windowMs: 60_000,
- bucketMs: 10_000,
- lastFailure: null,
- });
-
- expect(result.topProcesses).toHaveLength(36);
- expect(result.topProcesses.some((process) => process.command === "worker 34")).toBe(true);
- }),
- );
-
- it.effect("exposes bounded failure diagnostics while retaining the exact cause", () =>
- Effect.sync(() => {
- const readAt = DateTime.makeUnsafe("2026-05-05T10:00:00.000Z");
- const cause = new Error("stderr included credential=secret-value");
- const failure = new ProcessResourceMonitor.ProcessResourceSamplingError({
- failureTag: "ProcessDiagnosticsQueryFailedError",
- cause,
- });
+ health: {
+ native: {
+ status: "degraded",
+ lastSampleAt: Option.some(readAt),
+ lastError: Option.some("collector stalled"),
+ },
+ desktop: {
+ status: "healthy",
+ lastSampleAt: Option.some(readAt),
+ lastError: Option.none(),
+ },
+ sidecarVersion: Option.some("0.1.0"),
+ sidecarPid: Option.some(9_000),
+ restartCount: 1,
+ collectionDurationMicros: 250,
+ scannedProcessCount: 80,
+ retainedProcessCount: 2,
+ inaccessibleProcessCount: 0,
+ },
+ };
+ const telemetry: ResourceTelemetry.ResourceTelemetry["Service"] = {
+ latest: Effect.die("unused"),
+ changes: Stream.empty,
+ subscribe: Effect.die("unused"),
+ readHistory: () => Effect.succeed(history),
+ refresh: Effect.die("unused"),
+ validateProcessIdentity: () => Effect.die("unused"),
+ retry: Effect.die("unused"),
+ };
+ const layer = ProcessResourceMonitor.layer.pipe(
+ Layer.provide(
+ Layer.succeed(
+ ResourceTelemetry.ResourceTelemetry,
+ ResourceTelemetry.ResourceTelemetry.of(telemetry),
+ ),
+ ),
+ );
- const result = ProcessResourceMonitor.aggregateProcessResourceHistory({
- samples: [],
- readAt,
- readAtMs: DateTime.toEpochMillis(readAt),
- windowMs: 60_000,
- bucketMs: 10_000,
- lastFailure: failure,
- });
+ const result = yield* Effect.service(ProcessResourceMonitor.ProcessResourceMonitor).pipe(
+ Effect.flatMap((monitor) =>
+ monitor.readHistory({
+ windowMs: 60_000,
+ bucketMs: 10_000,
+ }),
+ ),
+ Effect.provide(layer),
+ );
- expect(failure.cause).toBe(cause);
- expect(Option.getOrThrow(result.error)).toEqual({
- failureTag: "ProcessDiagnosticsQueryFailedError",
- message: "Failed to sample process resources (ProcessDiagnosticsQueryFailedError).",
+ expect(result.totalCpuSecondsApprox).toBe(1.5);
+ expect(result.topProcesses).toEqual([
+ {
+ processKey: `${process.pid}:100`,
+ pid: process.pid,
+ ppid: 1,
+ command: "t3 server",
+ depth: 0,
+ isServerRoot: true,
+ firstSeenAt: DateTime.makeUnsafe("2026-05-05T09:59:55.000Z"),
+ lastSeenAt: readAt,
+ currentCpuPercent: 5,
+ avgCpuPercent: 4,
+ maxCpuPercent: 8,
+ cpuSecondsApprox: 1.5,
+ currentRssBytes: 2_048,
+ maxRssBytes: 4_096,
+ sampleCount: 2,
+ },
+ ]);
+ expect(result.buckets[0]).toMatchObject({
+ avgCpuPercent: 5,
+ maxCpuPercent: 8,
+ maxRssBytes: 4_096,
+ maxProcessCount: 1,
});
- expect(Option.getOrThrow(result.error).message).not.toContain("secret-value");
+ expect(result.error).toEqual(
+ Option.some({
+ failureTag: "ProcessDiagnosticsQueryFailedError",
+ message: "collector stalled",
+ }),
+ );
}),
);
});
diff --git a/apps/server/src/diagnostics/ProcessResourceMonitor.ts b/apps/server/src/diagnostics/ProcessResourceMonitor.ts
index 6030e4172..5f5e32dd2 100644
--- a/apps/server/src/diagnostics/ProcessResourceMonitor.ts
+++ b/apps/server/src/diagnostics/ProcessResourceMonitor.ts
@@ -1,55 +1,14 @@
-import {
- ServerProcessResourceHistoryFailureTag,
- type ServerProcessResourceHistoryBucket,
- type ServerProcessResourceHistoryFailureTag as ServerProcessResourceHistoryFailureTagType,
- type ServerProcessResourceHistoryInput,
- type ServerProcessResourceHistoryResult,
- type ServerProcessResourceHistorySummary,
+import type {
+ ResourceTelemetryProcessCategory,
+ ServerProcessResourceHistoryInput,
+ ServerProcessResourceHistoryResult,
} from "@t3tools/contracts";
import * as Context from "effect/Context";
-import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
-import * as Ref from "effect/Ref";
-import * as Schema from "effect/Schema";
-import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
-import * as ProcessDiagnostics from "./ProcessDiagnostics.ts";
-
-const SAMPLE_INTERVAL_MS = 5_000;
-const RETENTION_MS = 60 * 60_000;
-const MAX_RETAINED_SAMPLES = 20_000;
-
-export interface ProcessResourceSample {
- readonly sampledAt: DateTime.Utc;
- readonly sampledAtMs: number;
- readonly processKey: string;
- readonly pid: number;
- readonly ppid: number;
- readonly command: string;
- readonly cpuPercent: number;
- readonly rssBytes: number;
- readonly depth: number;
- readonly isServerRoot: boolean;
-}
-
-export class ProcessResourceSamplingError extends Schema.TaggedErrorClass<ProcessResourceSamplingError>()(
- "ProcessResourceSamplingError",
- {
- failureTag: ServerProcessResourceHistoryFailureTag,
- cause: Schema.Defect(),
- },
-) {
- override get message(): string {
- return `Failed to sample process resources (${this.failureTag}).`;
- }
-}
-
-interface MonitorState {
- readonly samples: ReadonlyArray<ProcessResourceSample>;
- readonly lastFailure: ProcessResourceSamplingError | null;
-}
+import * as ResourceTelemetry from "../resourceTelemetry/ResourceTelemetry.ts";
export class ProcessResourceMonitor extends Context.Service<
ProcessResourceMonitor,
@@ -60,270 +19,69 @@ export class ProcessResourceMonitor extends Context.Service<
}
>()("t3/diagnostics/ProcessResourceMonitor") {}
-function dateTimeFromMillis(ms: number): DateTime.Utc {
- return DateTime.makeUnsafe(ms);
-}
-
-function sampleKey(row: Pick<ProcessDiagnostics.ProcessRow, "pid" | "command">): string {
- return `${row.pid}:${row.command}`;
-}
-
-function findServerRootRow(
- rows: ReadonlyArray<ProcessDiagnostics.ProcessRow>,
- serverPid: number,
-): ProcessDiagnostics.ProcessRow | null {
- return rows.find((row) => row.pid === serverPid) ?? null;
-}
-
-export function collectMonitoredSamples(input: {
- readonly rows: ReadonlyArray<ProcessDiagnostics.ProcessRow>;
- readonly serverPid: number;
- readonly sampledAt: DateTime.Utc;
- readonly sampledAtMs: number;
-}): ReadonlyArray<ProcessResourceSample> {
- const rows = input.rows.filter(
- (row) => !ProcessDiagnostics.isDiagnosticsQueryProcess(row, input.serverPid),
+function isLegacyBackendCategory(category: ResourceTelemetryProcessCategory): boolean {
+ return (
+ category === "server" ||
+ category === "server-child" ||
+ category === "provider-root" ||
+ category === "terminal-root"
);
- const root = findServerRootRow(rows, input.serverPid);
- const descendants = ProcessDiagnostics.buildDescendantEntries(rows, input.serverPid);
- const samples: ProcessResourceSample[] = [];
-
- if (root) {
- samples.push({
- sampledAt: input.sampledAt,
- sampledAtMs: input.sampledAtMs,
- processKey: sampleKey(root),
- pid: root.pid,
- ppid: root.ppid,
- command: root.command,
- cpuPercent: root.cpuPercent,
- rssBytes: root.rssBytes,
- depth: 0,
- isServerRoot: true,
- });
- }
-
- for (const process of descendants) {
- samples.push({
- sampledAt: input.sampledAt,
- sampledAtMs: input.sampledAtMs,
- processKey: sampleKey(process),
- pid: process.pid,
- ppid: process.ppid,
- command: process.command,
- cpuPercent: process.cpuPercent,
- rssBytes: process.rssBytes,
- depth: process.depth + 1,
- isServerRoot: false,
- });
- }
-
- return samples;
-}
-
-function trimSamples(
- samples: ReadonlyArray<ProcessResourceSample>,
- nowMs: number,
-): ReadonlyArray<ProcessResourceSample> {
- const minSampledAtMs = nowMs - RETENTION_MS;
- const retained = samples.filter((sample) => sample.sampledAtMs >= minSampledAtMs);
- return retained.length <= MAX_RETAINED_SAMPLES
- ? retained
- : retained.slice(retained.length - MAX_RETAINED_SAMPLES);
}
-function summarizeProcesses(
- samples: ReadonlyArray<ProcessResourceSample>,
-): ReadonlyArray<ServerProcessResourceHistorySummary> {
- const groups = new Map<string, ProcessResourceSample[]>();
- for (const sample of samples) {
- const processSamples = groups.get(sample.processKey) ?? [];
- processSamples.push(sample);
- groups.set(sample.processKey, processSamples);
- }
-
- return [...groups.entries()]
- .map(([processKey, processSamples]) => {
- const sorted = processSamples.toSorted((left, right) => left.sampledAtMs - right.sampledAtMs);
- const first = sorted[0]!;
- const latest = sorted[sorted.length - 1]!;
- const cpuPercentTotal = sorted.reduce((total, sample) => total + sample.cpuPercent, 0);
- const maxCpuPercent = Math.max(...sorted.map((sample) => sample.cpuPercent));
- const maxRssBytes = Math.max(...sorted.map((sample) => sample.rssBytes));
- const cpuSecondsApprox = sorted.reduce(
- (total, sample) => total + (sample.cpuPercent / 100) * (SAMPLE_INTERVAL_MS / 1_000),
- 0,
- );
-
- return {
- processKey,
- pid: latest.pid,
- ppid: latest.ppid,
- command: latest.command,
- depth: latest.depth,
- isServerRoot: latest.isServerRoot,
- firstSeenAt: first.sampledAt,
- lastSeenAt: latest.sampledAt,
- currentCpuPercent: latest.cpuPercent,
- avgCpuPercent: cpuPercentTotal / sorted.length,
- maxCpuPercent,
- cpuSecondsApprox,
- currentRssBytes: latest.rssBytes,
- maxRssBytes,
- sampleCount: sorted.length,
- } satisfies ServerProcessResourceHistorySummary;
- })
- .toSorted((left, right) => right.cpuSecondsApprox - left.cpuSecondsApprox);
-}
-
-function buildBuckets(input: {
- readonly samples: ReadonlyArray<ProcessResourceSample>;
- readonly nowMs: number;
- readonly windowMs: number;
- readonly bucketMs: number;
-}): ReadonlyArray<ServerProcessResourceHistoryBucket> {
- const bucketMs = Math.max(1_000, input.bucketMs);
- const windowStartMs = input.nowMs - input.windowMs;
- const buckets: ServerProcessResourceHistoryBucket[] = [];
-
- for (let startedAtMs = windowStartMs; startedAtMs < input.nowMs; startedAtMs += bucketMs) {
- const endedAtMs = Math.min(input.nowMs, startedAtMs + bucketMs);
- const bucketSamples = input.samples.filter(
- (sample) =>
- sample.sampledAtMs >= startedAtMs &&
- (endedAtMs === input.nowMs
- ? sample.sampledAtMs <= endedAtMs
- : sample.sampledAtMs < endedAtMs),
- );
- const samplesByRead = new Map<number, ProcessResourceSample[]>();
- for (const sample of bucketSamples) {
- const samplesAtTime = samplesByRead.get(sample.sampledAtMs) ?? [];
- samplesAtTime.push(sample);
- samplesByRead.set(sample.sampledAtMs, samplesAtTime);
- }
-
- const readTotals = [...samplesByRead.values()].map((samplesAtTime) => ({
- cpuPercent: samplesAtTime.reduce((total, sample) => total + sample.cpuPercent, 0),
- rssBytes: samplesAtTime.reduce((total, sample) => total + sample.rssBytes, 0),
- processCount: samplesAtTime.length,
- }));
- const avgCpuPercent =
- readTotals.length === 0
- ? 0
- : readTotals.reduce((total, read) => total + read.cpuPercent, 0) / readTotals.length;
-
- buckets.push({
- startedAt: dateTimeFromMillis(startedAtMs),
- endedAt: dateTimeFromMillis(endedAtMs),
- avgCpuPercent,
- maxCpuPercent: readTotals.length ? Math.max(...readTotals.map((read) => read.cpuPercent)) : 0,
- maxRssBytes: readTotals.length ? Math.max(...readTotals.map((read) => read.rssBytes)) : 0,
- maxProcessCount: readTotals.length
- ? Math.max(...readTotals.map((read) => read.processCount))
- : 0,
- });
- }
-
- return buckets;
-}
-
-export function aggregateProcessResourceHistory(input: {
- readonly samples: ReadonlyArray<ProcessResourceSample>;
- readonly readAt: DateTime.Utc;
- readonly readAtMs: number;
- readonly windowMs: number;
- readonly bucketMs: number;
- readonly lastFailure: ProcessResourceSamplingError | null;
-}): ServerProcessResourceHistoryResult {
- const windowMs = Math.max(1_000, input.windowMs);
- const bucketMs = Math.max(1_000, input.bucketMs);
- const minSampledAtMs = input.readAtMs - windowMs;
- const samples = input.samples.filter((sample) => sample.sampledAtMs >= minSampledAtMs);
- const topProcesses = summarizeProcesses(samples);
- const totalCpuSecondsApprox = samples.reduce(
- (total, sample) => total + (sample.cpuPercent / 100) * (SAMPLE_INTERVAL_MS / 1_000),
- 0,
- );
-
- return {
- readAt: input.readAt,
- windowMs,
- bucketMs,
- sampleIntervalMs: SAMPLE_INTERVAL_MS,
- retainedSampleCount: input.samples.length,
- totalCpuSecondsApprox,
- buckets: buildBuckets({ samples, nowMs: input.readAtMs, windowMs, bucketMs }),
- topProcesses,
- error: input.lastFailure
- ? Option.some({
- failureTag: input.lastFailure.failureTag,
- message: input.lastFailure.message,
- })
- : Option.none(),
- };
-}
-
-export const make = Effect.gen(function* () {
- const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
- const state = yield* Ref.make<MonitorState>({ samples: [], lastFailure: null });
-
- const recordSamplingFailure = (cause: {
- readonly _tag: ServerProcessResourceHistoryFailureTagType;
- }) =>
- Ref.update(state, (current) => ({
- ...current,
- lastFailure: new ProcessResourceSamplingError({
- failureTag: cause._tag,
- cause,
+export const make = Effect.fn("makeProcessResourceMonitor")(function* () {
+ const telemetry = yield* ResourceTelemetry.ResourceTelemetry;
+ const readHistory: ProcessResourceMonitor["Service"]["readHistory"] = (input) =>
+ telemetry.readHistory(input).pipe(
+ Effect.map((history) => {
+ const topProcesses = history.topProcesses
+ .filter((entry) => isLegacyBackendCategory(entry.category))
+ .map((entry) => ({
+ processKey: `${entry.identity.pid}:${entry.identity.startTimeMs}`,
+ pid: entry.identity.pid,
+ ppid: entry.ppid,
+ command: entry.command || entry.name || "unknown",
+ depth: entry.depth,
+ isServerRoot: entry.category === "server",
+ firstSeenAt: entry.firstSeenAt,
+ lastSeenAt: entry.lastSeenAt,
+ currentCpuPercent: entry.currentCpuPercent,
+ avgCpuPercent: entry.avgCpuPercent,
+ maxCpuPercent: entry.maxCpuPercent,
+ cpuSecondsApprox: entry.cpuTimeMs / 1_000,
+ currentRssBytes: entry.currentRssBytes,
+ maxRssBytes: entry.peakRssBytes,
+ sampleCount: entry.sampleCount,
+ }));
+ return {
+ readAt: history.readAt,
+ windowMs: history.windowMs,
+ bucketMs: history.bucketMs,
+ sampleIntervalMs: history.sampleIntervalMs,
+ retainedSampleCount: history.retainedSampleCount,
+ totalCpuSecondsApprox: topProcesses.reduce(
+ (total, entry) => total + entry.cpuSecondsApprox,
+ 0,
+ ),
+ buckets: (history.legacyBackendBuckets ?? history.buckets).map((bucket) => ({
+ startedAt: bucket.startedAt,
+ endedAt: bucket.endedAt,
+ avgCpuPercent: bucket.avgCpuPercent,
+ maxCpuPercent: bucket.maxCpuPercent,
+ maxRssBytes: bucket.maxRssBytes,
+ maxProcessCount: bucket.maxProcessCount,
+ })),
+ topProcesses,
+ error: history.health.native.lastError.pipe(
+ Option.map((message) => ({
+ failureTag: "ProcessDiagnosticsQueryFailedError" as const,
+ message,
+ })),
+ ),
+ };
}),
- }));
-
- const sampleOnce = Effect.gen(function* () {
- const sampledAt = yield* DateTime.now;
- const sampledAtMs = DateTime.toEpochMillis(sampledAt);
- const rows = yield* ProcessDiagnostics.readProcessRows.pipe(
- Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
);
- const samples = collectMonitoredSamples({
- rows,
- serverPid: process.pid,
- sampledAt,
- sampledAtMs,
- });
- yield* Ref.update(state, (current) => ({
- samples: trimSamples([...current.samples, ...samples], sampledAtMs),
- lastFailure: null,
- }));
- }).pipe(
- Effect.catchTags({
- ProcessDiagnosticsQueryTimeoutError: recordSamplingFailure,
- ProcessDiagnosticsQueryFailedError: recordSamplingFailure,
- ProcessDiagnosticsServerProcessSignalError: recordSamplingFailure,
- ProcessDiagnosticsNotDescendantError: recordSamplingFailure,
- ProcessDiagnosticsSignalFailedError: recordSamplingFailure,
- }),
- );
-
- yield* Effect.forever(sampleOnce.pipe(Effect.andThen(Effect.sleep(SAMPLE_INTERVAL_MS)))).pipe(
- Effect.forkScoped,
- );
-
- const readHistory: ProcessResourceMonitor["Service"]["readHistory"] = (input) =>
- Effect.gen(function* () {
- const readAt = yield* DateTime.now;
- const readAtMs = DateTime.toEpochMillis(readAt);
- const current = yield* Ref.get(state);
- return aggregateProcessResourceHistory({
- samples: current.samples,
- readAt,
- readAtMs,
- windowMs: input.windowMs,
- bucketMs: input.bucketMs,
- lastFailure: current.lastFailure,
- });
- });
return ProcessResourceMonitor.of({ readHistory });
});
-export const layer = Layer.effect(ProcessResourceMonitor, make);
+export const layer = Layer.effect(ProcessResourceMonitor, make());
diff --git a/apps/server/src/observability/Layers/Observability.ts b/apps/server/src/observability/Layers/Observability.ts
index b9b0012d3..8aac09275 100644
--- a/apps/server/src/observability/Layers/Observability.ts
+++ b/apps/server/src/observability/Layers/Observability.ts
@@ -10,6 +10,7 @@ import * as OtlpSerialization from "effect/unstable/observability/OtlpSerializat
import * as OtlpTracer from "effect/unstable/observability/OtlpTracer";
import * as ServerConfig from "../../config.ts";
+import * as ResourceAttribution from "../../resourceTelemetry/ResourceAttribution.ts";
import { ServerLoggerLive } from "../../serverLogger.ts";
import * as BrowserTraceCollector from "../BrowserTraceCollector.ts";
@@ -18,6 +19,7 @@ const otlpSerializationLayer = OtlpSerialization.layerJson;
export const ObservabilityLive = Layer.unwrap(
Effect.gen(function* () {
const config = yield* ServerConfig.ServerConfig;
+ const attribution = yield* ResourceAttribution.ResourceAttribution;
const traceReferencesLayer = Layer.mergeAll(
Layer.succeed(Tracer.MinimumTraceLevel, config.traceMinLevel),
@@ -32,6 +34,14 @@ export const ObservabilityLive = Layer.unwrap(
maxBytes: config.traceMaxBytes,
maxFiles: config.traceMaxFiles,
batchWindowMs: config.traceBatchWindowMs,
+ onFlush: (stats) =>
+ attribution.record({
+ component: "server-trace",
+ operation: "append",
+ logicalWriteBytes: stats.logicalWriteBytes,
+ count: stats.count,
+ durationMs: stats.durationMs,
+ }),
});
const delegate =
config.otlpTracesUrl === undefined
diff --git a/apps/server/src/provider/Drivers/ClaudeDriver.ts b/apps/server/src/provider/Drivers/ClaudeDriver.ts
index c2fc11311..e099d52e5 100644
--- a/apps/server/src/provider/Drivers/ClaudeDriver.ts
+++ b/apps/server/src/provider/Drivers/ClaudeDriver.ts
@@ -24,6 +24,7 @@ import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
import { makeClaudeTextGeneration } from "../../textGeneration/ClaudeTextGeneration.ts";
+import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
import { ServerConfig } from "../../config.ts";
import { ServerSettingsService } from "../../serverSettings.ts";
import { ProviderDriverError } from "../Errors.ts";
@@ -57,7 +58,6 @@ import { makeClaudeCapabilitiesCacheKey, makeClaudeContinuationGroupKey } from "
const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
const DRIVER_KIND = ProviderDriverKind.make("claudeAgent");
-const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
const CAPABILITIES_PROBE_TTL = Duration.minutes(5);
function isClaudeNativeCommandPath(commandPath: string): boolean {
@@ -82,6 +82,7 @@ const UPDATE = makePackageManagedProviderMaintenanceResolver({
});
export type ClaudeDriverEnv =
+ | BackgroundPolicy.BackgroundPolicy
| ChildProcessSpawner.ChildProcessSpawner
| Crypto.Crypto
| FileSystem.FileSystem
@@ -190,7 +191,6 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
Effect.provideService(HttpClient.HttpClient, httpClient),
Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
),
- refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
}).pipe(
Effect.mapError(
(cause) =>
diff --git a/apps/server/src/provider/Drivers/CodexDriver.ts b/apps/server/src/provider/Drivers/CodexDriver.ts
index ffcc94ca7..15d7a1ff0 100644
--- a/apps/server/src/provider/Drivers/CodexDriver.ts
+++ b/apps/server/src/provider/Drivers/CodexDriver.ts
@@ -22,7 +22,6 @@
* @module provider/Drivers/CodexDriver
*/
import { CodexSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
-import * as Duration from "effect/Duration";
import * as Crypto from "effect/Crypto";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
@@ -32,6 +31,7 @@ import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
import { makeCodexTextGeneration } from "../../textGeneration/CodexTextGeneration.ts";
+import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
import { ServerConfig } from "../../config.ts";
import { ServerSettingsService } from "../../serverSettings.ts";
import { ProviderDriverError } from "../Errors.ts";
@@ -60,7 +60,6 @@ import {
const decodeCodexSettings = Schema.decodeSync(CodexSettings);
const DRIVER_KIND = ProviderDriverKind.make("codex");
-const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
const UPDATE = makePackageManagedProviderMaintenanceResolver({
provider: DRIVER_KIND,
npmPackageName: "@openai/codex",
@@ -74,6 +73,7 @@ const UPDATE = makePackageManagedProviderMaintenanceResolver({
* registered driver and the runtime satisfies them once.
*/
export type CodexDriverEnv =
+ | BackgroundPolicy.BackgroundPolicy
| ChildProcessSpawner.ChildProcessSpawner
| Crypto.Crypto
| FileSystem.FileSystem
@@ -186,7 +186,6 @@ export const CodexDriver: ProviderDriver<CodexSettings, CodexDriverEnv> = {
Effect.provideService(HttpClient.HttpClient, httpClient),
Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
),
- refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
}).pipe(
Effect.mapError(
(cause) =>
diff --git a/apps/server/src/provider/Drivers/CursorDriver.ts b/apps/server/src/provider/Drivers/CursorDriver.ts
index 61f804897..2101664d5 100644
--- a/apps/server/src/provider/Drivers/CursorDriver.ts
+++ b/apps/server/src/provider/Drivers/CursorDriver.ts
@@ -12,7 +12,6 @@
* @module provider/Drivers/CursorDriver
*/
import { CursorSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
-import * as Duration from "effect/Duration";
import * as Crypto from "effect/Crypto";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
@@ -21,6 +20,7 @@ import * as Schema from "effect/Schema";
import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
+import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
import { ServerConfig } from "../../config.ts";
import { ServerSettingsService } from "../../serverSettings.ts";
import { makeCursorTextGeneration } from "../../textGeneration/CursorTextGeneration.ts";
@@ -53,7 +53,6 @@ import {
const decodeCursorSettings = Schema.decodeSync(CursorSettings);
const DRIVER_KIND = ProviderDriverKind.make("cursor");
-const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
const UPDATE: ProviderMaintenanceCapabilitiesResolver = {
resolve: (options) =>
makeProviderMaintenanceCapabilities({
@@ -66,6 +65,7 @@ const UPDATE: ProviderMaintenanceCapabilitiesResolver = {
};
export type CursorDriverEnv =
+ | BackgroundPolicy.BackgroundPolicy
| ChildProcessSpawner.ChildProcessSpawner
| Crypto.Crypto
| FileSystem.FileSystem
@@ -160,8 +160,7 @@ export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
publishSnapshot,
stampIdentity,
httpClient,
- }),
- refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
+ }).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner)),
}).pipe(
Effect.mapError(
(cause) =>
diff --git a/apps/server/src/provider/Drivers/GrokDriver.ts b/apps/server/src/provider/Drivers/GrokDriver.ts
index 4eb32c20c..112f11013 100644
--- a/apps/server/src/provider/Drivers/GrokDriver.ts
+++ b/apps/server/src/provider/Drivers/GrokDriver.ts
@@ -1,5 +1,4 @@
import { GrokSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
-import * as Duration from "effect/Duration";
import * as Crypto from "effect/Crypto";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
@@ -8,6 +7,7 @@ import * as Schema from "effect/Schema";
import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
+import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
import { ServerConfig } from "../../config.ts";
import { ServerSettingsService } from "../../serverSettings.ts";
import { makeGrokTextGeneration } from "../../textGeneration/GrokTextGeneration.ts";
@@ -40,7 +40,6 @@ import {
const decodeGrokSettings = Schema.decodeSync(GrokSettings);
const DRIVER_KIND = ProviderDriverKind.make("grok");
-const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
const UPDATE = makeStaticProviderMaintenanceResolver(
makeManualOnlyProviderMaintenanceCapabilities({
provider: DRIVER_KIND,
@@ -49,6 +48,7 @@ const UPDATE = makeStaticProviderMaintenanceResolver(
);
export type GrokDriverEnv =
+ | BackgroundPolicy.BackgroundPolicy
| ChildProcessSpawner.ChildProcessSpawner
| Crypto.Crypto
| FileSystem.FileSystem
@@ -136,7 +136,6 @@ export const GrokDriver: ProviderDriver<GrokSettings, GrokDriverEnv> = {
publishSnapshot,
httpClient,
}),
- refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
}).pipe(
Effect.mapError(
(cause) =>
diff --git a/apps/server/src/provider/Drivers/OpenCodeDriver.ts b/apps/server/src/provider/Drivers/OpenCodeDriver.ts
index 6342d1765..a01e414f8 100644
--- a/apps/server/src/provider/Drivers/OpenCodeDriver.ts
+++ b/apps/server/src/provider/Drivers/OpenCodeDriver.ts
@@ -13,7 +13,6 @@
* @module provider/Drivers/OpenCodeDriver
*/
import { OpenCodeSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
-import * as Duration from "effect/Duration";
import * as Crypto from "effect/Crypto";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
@@ -23,6 +22,7 @@ import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
import { makeOpenCodeTextGeneration } from "../../textGeneration/OpenCodeTextGeneration.ts";
+import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
import { ServerConfig } from "../../config.ts";
import { ServerSettingsService } from "../../serverSettings.ts";
import { ProviderDriverError } from "../Errors.ts";
@@ -55,7 +55,6 @@ import {
const decodeOpenCodeSettings = Schema.decodeSync(OpenCodeSettings);
const DRIVER_KIND = ProviderDriverKind.make("opencode");
-const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
function isOpenCodeNativeCommandPath(commandPath: string): boolean {
const normalized = normalizeCommandPath(commandPath);
@@ -78,6 +77,7 @@ const UPDATE = makePackageManagedProviderMaintenanceResolver({
});
export type OpenCodeDriverEnv =
+ | BackgroundPolicy.BackgroundPolicy
| ChildProcessSpawner.ChildProcessSpawner
| Crypto.Crypto
| FileSystem.FileSystem
@@ -166,7 +166,6 @@ export const OpenCodeDriver: ProviderDriver<OpenCodeSettings, OpenCodeDriverEnv>
Effect.provideService(HttpClient.HttpClient, httpClient),
Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
),
- refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
},
).pipe(
Effect.mapError(
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.ts b/apps/server/src/provider/Layers/ClaudeAdapter.ts
index 285d9dac6..f87d5be74 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.ts
@@ -1354,6 +1354,8 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
stream: "native",
})
: undefined);
+ const managedNativeEventLogger =
+ options?.nativeEventLogger === undefined ? nativeEventLogger : undefined;
const createQuery =
options?.createQuery ??
@@ -1387,7 +1389,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
const offerRuntimeEvent = (event: ProviderRuntimeEvent): Effect.Effect<void> =>
Queue.offer(runtimeEventQueue, event).pipe(Effect.asVoid);
- const logNativeSdkMessage = Effect.fn("logNativeSdkMessage")(function* (
+ const logNativeSdkMessage = Effect.fnUntraced(function* (
context: ClaudeSessionContext,
message: SDKMessage,
) {
@@ -3922,6 +3924,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
Effect.logError("Failed to emit Claude session shutdown event.", { cause }),
),
Effect.tap(() => Queue.shutdown(runtimeEventQueue)),
+ Effect.tap(() => managedNativeEventLogger?.close() ?? Effect.void),
),
);
diff --git a/apps/server/src/provider/Layers/CodexAdapter.test.ts b/apps/server/src/provider/Layers/CodexAdapter.test.ts
index 4ae654a51..7b8fbec56 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.test.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.test.ts
@@ -1291,7 +1291,7 @@ it.effect("flushes managed native logs when the adapter layer shuts down", () =>
yield* Scope.close(scope, Exit.void);
scopeClosed = true;
- const threadLogPath = NodePath.join(tempDir, "thread-logger.log");
+ const threadLogPath = NodePath.join(tempDir, "provider-native.thread-logger.log");
NodeAssert.equal(NodeFS.existsSync(threadLogPath), true);
const contents = NodeFS.readFileSync(threadLogPath, "utf8");
NodeAssert.match(contents, /NTIVE: .*"message":"native flush test"/);
diff --git a/apps/server/src/provider/Layers/CodexAdapter.ts b/apps/server/src/provider/Layers/CodexAdapter.ts
index 38a5887cd..4146121b1 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.ts
@@ -1646,7 +1646,7 @@ export const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
),
);
- const writeNativeEvent = Effect.fn("writeNativeEvent")(function* (event: ProviderEvent) {
+ const writeNativeEvent = Effect.fnUntraced(function* (event: ProviderEvent) {
if (!nativeEventLogger) {
return;
}
diff --git a/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts b/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts
index 71ac7831e..39d93ddc1 100644
--- a/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts
+++ b/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts
@@ -5,14 +5,30 @@ import * as NodePath from "node:path";
import { ThreadId } from "@t3tools/contracts";
import { assert, describe, it } from "@effect/vitest";
+import * as Clock from "effect/Clock";
import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
import * as Logger from "effect/Logger";
import * as Schema from "effect/Schema";
+import * as TestClock from "effect/testing/TestClock";
-import { makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
+import * as ResourceAttribution from "../../resourceTelemetry/ResourceAttribution.ts";
+import {
+ makeEventNdjsonLogger,
+ makeEventNdjsonLogStore,
+ type PendingRecord,
+ writeBatchedMessages,
+} from "./EventNdjsonLogger.ts";
const encodeUnknownJson = Schema.encodeUnknownSync(Schema.UnknownFromJsonString);
+function ownedLogPath(basePath: string, segment: string): string {
+ const basename = NodePath.basename(basePath);
+ const extension = NodePath.extname(basename);
+ const stem = extension.length > 0 ? basename.slice(0, -extension.length) : basename;
+ return NodePath.join(NodePath.dirname(basePath), `${stem}.${segment}.log`);
+}
+
function parseLogLine(line: string) {
const match = /^\[([^\]]+)\] ([A-Z]+): (.+)$/.exec(line);
assert.notEqual(match, null);
@@ -87,8 +103,8 @@ describe("EventNdjsonLogger", () => {
);
yield* logger.close();
- const threadOnePath = NodePath.join(tempDir, "thread-1.log");
- const threadTwoPath = NodePath.join(tempDir, "thread-2.log");
+ const threadOnePath = ownedLogPath(basePath, "thread-1");
+ const threadTwoPath = ownedLogPath(basePath, "thread-2");
assert.equal(NodeFS.existsSync(threadOnePath), true);
assert.equal(NodeFS.existsSync(threadTwoPath), true);
@@ -129,7 +145,7 @@ describe("EventNdjsonLogger", () => {
yield* logger.write({ id: "evt-invalid-thread" }, "!!!" as unknown as ThreadId);
yield* logger.close();
- const globalPath = NodePath.join(tempDir, "_global.log");
+ const globalPath = ownedLogPath(basePath, "_global");
assert.equal(NodeFS.existsSync(globalPath), true);
const lines = NodeFS.readFileSync(globalPath, "utf8")
.trim()
@@ -138,9 +154,9 @@ describe("EventNdjsonLogger", () => {
assert.equal(lines.length, 2);
assert.equal(Number.isNaN(Date.parse(lines[0]?.observedAt ?? "")), false);
assert.equal(Number.isNaN(Date.parse(lines[1]?.observedAt ?? "")), false);
- assert.equal(lines[0]?.stream, "CANON");
+ assert.equal(lines[0]?.stream, "ORCH");
assert.equal(lines[0]?.payload, '{"id":"evt-no-thread"}');
- assert.equal(lines[1]?.stream, "CANON");
+ assert.equal(lines[1]?.stream, "ORCH");
assert.equal(lines[1]?.payload, '{"id":"evt-invalid-thread"}');
} finally {
NodeFS.rmSync(tempDir, { recursive: true, force: true });
@@ -148,6 +164,197 @@ describe("EventNdjsonLogger", () => {
}),
);
+ it.effect("shares one thread writer across native and canonical streams", () =>
+ Effect.gen(function* () {
+ const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
+ const basePath = NodePath.join(tempDir, "events.log");
+
+ try {
+ const store = yield* makeEventNdjsonLogStore(basePath, { batchWindowMs: 0 });
+ const native = store.logger("native");
+ const canonical = store.logger("canonical");
+ const threadId = ThreadId.make("thread-shared");
+
+ yield* native.write({ id: "native-event" }, threadId);
+ yield* canonical.write({ type: "item.completed", id: "canonical-event" }, threadId);
+ yield* store.close();
+
+ const lines = NodeFS.readFileSync(ownedLogPath(basePath, "thread-shared"), "utf8")
+ .trim()
+ .split("\n")
+ .map(parseLogLine);
+
+ assert.deepEqual(
+ lines.map(({ stream, payload }) => ({ stream, payload })),
+ [
+ { stream: "NTIVE", payload: '{"id":"native-event"}' },
+ {
+ stream: "CANON",
+ payload: '{"type":"item.completed","id":"canonical-event"}',
+ },
+ ],
+ );
+ } finally {
+ NodeFS.rmSync(tempDir, { recursive: true, force: true });
+ }
+ }),
+ );
+
+ it.effect("keeps shared store views non-owning when one adapter closes", () =>
+ Effect.gen(function* () {
+ const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
+ const basePath = NodePath.join(tempDir, "events.log");
+
+ try {
+ const store = yield* makeEventNdjsonLogStore(basePath, { batchWindowMs: 0 });
+ const native = store.logger("native");
+ const canonical = store.logger("canonical");
+ const threadId = ThreadId.make("thread-shared-close");
+
+ yield* native.write({ id: "before-close" }, threadId);
+ yield* native.close();
+ yield* canonical.write({ type: "item.completed", id: "after-close" }, threadId);
+ yield* store.close();
+
+ const lines = NodeFS.readFileSync(ownedLogPath(basePath, "thread-shared-close"), "utf8")
+ .trim()
+ .split("\n")
+ .map(parseLogLine);
+
+ assert.deepEqual(
+ lines.map(({ stream, payload }) => ({ stream, payload })),
+ [
+ { stream: "NTIVE", payload: '{"id":"before-close"}' },
+ {
+ stream: "CANON",
+ payload: '{"type":"item.completed","id":"after-close"}',
+ },
+ ],
+ );
+ } finally {
+ NodeFS.rmSync(tempDir, { recursive: true, force: true });
+ }
+ }),
+ );
+
+ it.effect("flushes an active batch without a permanent polling loop", () =>
+ Effect.gen(function* () {
+ const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
+ const basePath = NodePath.join(tempDir, "events.log");
+ const threadPath = ownedLogPath(basePath, "thread-batched");
+
+ try {
+ const store = yield* makeEventNdjsonLogStore(basePath, { batchWindowMs: 1_000 });
+ yield* store
+ .logger("native")
+ .write({ id: "batched-event" }, ThreadId.make("thread-batched"));
+
+ assert.equal(NodeFS.existsSync(threadPath), false);
+ yield* TestClock.adjust(1_000);
+ assert.equal(NodeFS.existsSync(threadPath), true);
+ yield* store.close();
+ } finally {
+ NodeFS.rmSync(tempDir, { recursive: true, force: true });
+ }
+ }),
+ );
+
+ it.effect("does not strand a later batch after an interrupted write", () =>
+ Effect.gen(function* () {
+ const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
+ const basePath = NodePath.join(tempDir, "events.log");
+ const threadPath = ownedLogPath(basePath, "thread-interrupted");
+
+ try {
+ const store = yield* makeEventNdjsonLogStore(basePath, { batchWindowMs: 1_000 });
+ const logger = store.logger("native");
+ const interruptedWrite = yield* logger
+ .write({ id: "possibly-interrupted" }, ThreadId.make("thread-interrupted"))
+ .pipe(Effect.forkChild);
+ yield* Effect.yieldNow;
+ yield* Fiber.interrupt(interruptedWrite);
+ yield* logger.write({ id: "accepted" }, ThreadId.make("thread-interrupted"));
+
+ yield* TestClock.adjust(1_000);
+
+ assert.equal(NodeFS.existsSync(threadPath), true);
+ assert.include(NodeFS.readFileSync(threadPath, "utf8"), '{"id":"accepted"}');
+ yield* store.close();
+ } finally {
+ NodeFS.rmSync(tempDir, { recursive: true, force: true });
+ }
+ }),
+ );
+
+ it.effect("drops transient canonical events before serialization", () =>
+ Effect.gen(function* () {
+ const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
+ const basePath = NodePath.join(tempDir, "events.log");
+
+ try {
+ const store = yield* makeEventNdjsonLogStore(basePath, { batchWindowMs: 0 });
+ const canonical = store.logger("canonical");
+ const native = store.logger("native");
+ const threadId = ThreadId.make("thread-filtered");
+ const circularDelta: Record<string, unknown> = { type: "content.delta" };
+ circularDelta["self"] = circularDelta;
+
+ yield* canonical.write(circularDelta, threadId);
+ yield* canonical.write({ type: "item.completed", id: "final" }, threadId);
+ yield* native.write({ type: "content.delta", id: "native-delta" }, threadId);
+ yield* store.close();
+
+ const lines = NodeFS.readFileSync(ownedLogPath(basePath, "thread-filtered"), "utf8")
+ .trim()
+ .split("\n")
+ .map(parseLogLine);
+
+ assert.deepEqual(
+ lines.map(({ stream, payload }) => ({ stream, payload })),
+ [
+ { stream: "CANON", payload: '{"type":"item.completed","id":"final"}' },
+ { stream: "NTIVE", payload: '{"type":"content.delta","id":"native-delta"}' },
+ ],
+ );
+ } finally {
+ NodeFS.rmSync(tempDir, { recursive: true, force: true });
+ }
+ }),
+ );
+
+ it.effect("contains hostile event accessors inside guarded serialization", () =>
+ Effect.gen(function* () {
+ const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
+ const basePath = NodePath.join(tempDir, "events.log");
+
+ try {
+ const logger = yield* makeEventNdjsonLogger(basePath, {
+ stream: "canonical",
+ batchWindowMs: 0,
+ });
+ assert.exists(logger);
+ if (!logger) return;
+ const hostile = new Proxy(
+ { id: "hostile" },
+ {
+ get(_target, property) {
+ if (property === "type") throw new Error("blocked");
+ return undefined;
+ },
+ },
+ );
+
+ yield* logger.write(hostile, ThreadId.make("thread-hostile"));
+ yield* logger.close();
+
+ const contents = NodeFS.readFileSync(ownedLogPath(basePath, "thread-hostile"), "utf8");
+ assert.notInclude(contents, "blocked");
+ } finally {
+ NodeFS.rmSync(tempDir, { recursive: true, force: true });
+ }
+ }),
+ );
+
it.effect("serializes concurrent first writes for the same segment", () =>
Effect.gen(function* () {
const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
@@ -172,7 +379,7 @@ describe("EventNdjsonLogger", () => {
);
yield* logger.close();
- const globalPath = NodePath.join(tempDir, "_global.log");
+ const globalPath = ownedLogPath(basePath, "_global");
assert.equal(NodeFS.existsSync(globalPath), true);
const lines = NodeFS.readFileSync(globalPath, "utf8")
.trim()
@@ -196,19 +403,19 @@ describe("EventNdjsonLogger", () => {
const basePath = NodePath.join(tempDir, "provider-native.ndjson");
try {
- const logger = yield* makeEventNdjsonLogger(basePath, {
- stream: "native",
+ const store = yield* makeEventNdjsonLogStore(basePath, {
maxBytes: 120,
maxFiles: 2,
+ batchWindowMs: 0,
});
- assert.notEqual(logger, undefined);
- if (!logger) {
- return;
- }
+ const native = store.logger("native");
+ const canonical = store.logger("canonical");
for (let index = 0; index < 10; index += 1) {
+ const logger = index % 2 === 0 ? native : canonical;
yield* logger.write(
{
+ type: "session.started",
threadId: "provider-thread-rotate",
id: `evt-${index}`,
payload: "x".repeat(40),
@@ -216,9 +423,9 @@ describe("EventNdjsonLogger", () => {
ThreadId.make("thread-rotate"),
);
}
- yield* logger.close();
+ yield* store.close();
- const fileStem = "thread-rotate.log";
+ const fileStem = NodePath.basename(ownedLogPath(basePath, "thread-rotate"));
const matchingFiles = NodeFS.readdirSync(tempDir)
.filter((entry) => entry === fileStem || entry.startsWith(`${fileStem}.`))
.toSorted();
@@ -240,4 +447,143 @@ describe("EventNdjsonLogger", () => {
}
}),
);
+
+ it.effect("enforces aggregate age and byte retention on startup", () =>
+ Effect.gen(function* () {
+ const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
+ const basePath = NodePath.join(tempDir, "events.log");
+ const expiredPath = ownedLogPath(basePath, "expired");
+ const oldPath = ownedLogPath(basePath, "old");
+ const newPath = ownedLogPath(basePath, "new");
+ const unrelatedLogPath = NodePath.join(tempDir, "unrelated.log");
+ const legacyLogPath = NodePath.join(tempDir, "legacy-thread.log");
+ const ignoredPath = NodePath.join(tempDir, "ignored.txt");
+
+ try {
+ yield* TestClock.setTime(1_800_000_000_000);
+ const now = yield* Clock.currentTimeMillis;
+ for (const filePath of [expiredPath, oldPath, newPath, unrelatedLogPath, ignoredPath]) {
+ NodeFS.writeFileSync(filePath, "x".repeat(40));
+ }
+ NodeFS.writeFileSync(
+ legacyLogPath,
+ "[2026-01-01T00:00:00.000Z] CANON: legacy provider event\n",
+ );
+ NodeFS.utimesSync(expiredPath, (now - 20_000) / 1_000, (now - 20_000) / 1_000);
+ NodeFS.utimesSync(legacyLogPath, (now - 20_000) / 1_000, (now - 20_000) / 1_000);
+ NodeFS.utimesSync(oldPath, (now - 5_000) / 1_000, (now - 5_000) / 1_000);
+ NodeFS.utimesSync(newPath, now / 1_000, now / 1_000);
+
+ const store = yield* makeEventNdjsonLogStore(basePath, {
+ maxAgeMs: 10_000,
+ maxTotalBytes: 60,
+ });
+ yield* store.close();
+
+ assert.equal(NodeFS.existsSync(expiredPath), false);
+ assert.equal(NodeFS.existsSync(legacyLogPath), false);
+ assert.equal(NodeFS.existsSync(oldPath), false);
+ assert.equal(NodeFS.existsSync(newPath), true);
+ assert.equal(NodeFS.existsSync(unrelatedLogPath), true);
+ assert.equal(NodeFS.existsSync(ignoredPath), true);
+ } finally {
+ NodeFS.rmSync(tempDir, { recursive: true, force: true });
+ }
+ }),
+ );
+
+ it.effect("does not prune an active thread sink during an unrelated flush", () =>
+ Effect.gen(function* () {
+ const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
+ const basePath = NodePath.join(tempDir, "events.log");
+ const activePath = ownedLogPath(basePath, "active");
+
+ try {
+ yield* TestClock.setTime(1_800_000_000_000);
+ const store = yield* makeEventNdjsonLogStore(basePath, {
+ batchWindowMs: 0,
+ maxAgeMs: 1,
+ retentionCheckIntervalMs: 1,
+ });
+ const logger = store.logger("native");
+
+ yield* logger.write({ id: "active-before-retention" }, ThreadId.make("active"));
+ assert.equal(NodeFS.existsSync(activePath), true);
+
+ yield* TestClock.adjust("2 millis");
+ yield* logger.write({ id: "retention-trigger" }, ThreadId.make("other"));
+
+ assert.equal(NodeFS.existsSync(activePath), true);
+ yield* store.close();
+ } finally {
+ NodeFS.rmSync(tempDir, { recursive: true, force: true });
+ }
+ }),
+ );
+
+ it("attributes batches that were written before a later chunk fails", () => {
+ const records: ReadonlyArray<PendingRecord> = [
+ {
+ stream: "native",
+ threadSegment: "thread",
+ line: "first",
+ bytes: 5,
+ },
+ {
+ stream: "canonical",
+ threadSegment: "thread",
+ line: "second",
+ bytes: 6,
+ },
+ ];
+ const attributed: Array<PendingRecord> = [];
+ let writes = 0;
+
+ assert.throws(() =>
+ writeBatchedMessages(
+ {
+ write: () => {
+ writes += 1;
+ if (writes === 2) throw new Error("simulated disk exhaustion");
+ },
+ },
+ records,
+ 5,
+ (written) => attributed.push(...written),
+ ),
+ );
+ assert.deepEqual(attributed, [records[0]]);
+ });
+
+ it.effect("reports logical provider log writes to resource attribution", () =>
+ Effect.gen(function* () {
+ const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
+ const basePath = NodePath.join(tempDir, "provider-native.ndjson");
+
+ try {
+ const attribution = yield* ResourceAttribution.make();
+ const logger = yield* makeEventNdjsonLogger(basePath, {
+ stream: "native",
+ batchWindowMs: 0,
+ attribution,
+ });
+ assert.notEqual(logger, undefined);
+ if (!logger) {
+ return;
+ }
+
+ yield* logger.write({ id: "attributed-event" }, ThreadId.make("thread-attribution"));
+ yield* logger.close();
+
+ const snapshot = yield* attribution.snapshot;
+ assert.equal(snapshot.entries.length, 1);
+ assert.equal(snapshot.entries[0]?.component, "provider-event-log");
+ assert.equal(snapshot.entries[0]?.operation, "native.append");
+ assert.equal(snapshot.entries[0]?.count, 1);
+ assert.isAbove(snapshot.entries[0]?.logicalWriteBytes ?? 0, 0);
+ } finally {
+ NodeFS.rmSync(tempDir, { recursive: true, force: true });
+ }
+ }),
+ );
});
diff --git a/apps/server/src/provider/Layers/EventNdjsonLogger.ts b/apps/server/src/provider/Layers/EventNdjsonLogger.ts
index 8c20a4c19..8eb9d11e7 100644
--- a/apps/server/src/provider/Layers/EventNdjsonLogger.ts
+++ b/apps/server/src/provider/Layers/EventNdjsonLogger.ts
@@ -1,10 +1,9 @@
// @effect-diagnostics nodeBuiltinImport:off
/**
- * Provider event logger helper.
+ * Best-effort provider event logging with one shared writer per thread.
*
- * Best-effort writer for observability logs. Each record is formatted as a
- * single effect-style text line in a thread-scoped file. Failures are
- * downgraded to warnings so provider runtime behavior is unaffected.
+ * Native and canonical views share batching, rotation, and retention state so
+ * they cannot race while appending to the same thread-scoped file.
*/
import * as NodeFS from "node:fs";
import * as NodePath from "node:path";
@@ -12,45 +11,147 @@ import * as NodePath from "node:path";
import type { ThreadId } from "@t3tools/contracts";
import { RotatingFileSink } from "@t3tools/shared/logging";
import { errorTag } from "@t3tools/shared/observability";
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
-import * as Logger from "effect/Logger";
import * as Schema from "effect/Schema";
import * as Scope from "effect/Scope";
import * as SynchronizedRef from "effect/SynchronizedRef";
import { toSafeThreadAttachmentSegment } from "../../attachmentStore.ts";
+import type { ResourceAttribution } from "../../resourceTelemetry/ResourceAttribution.ts";
-const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const MEBIBYTE = 1024 * 1024;
+const DAY_MS = 24 * 60 * 60 * 1_000;
+const DEFAULT_MAX_BYTES = 10 * MEBIBYTE;
const DEFAULT_MAX_FILES = 10;
-const DEFAULT_BATCH_WINDOW_MS = 200;
+const DEFAULT_BATCH_WINDOW_MS = 1_000;
+const DEFAULT_MAX_TOTAL_BYTES = 512 * MEBIBYTE;
+const DEFAULT_MAX_AGE_MS = 14 * DAY_MS;
+const DEFAULT_RETENTION_CHECK_INTERVAL_MS = 5 * 60 * 1_000;
+const DEFAULT_MAX_BUFFERED_BYTES = MEBIBYTE;
+const DEFAULT_MAX_BUFFERED_RECORDS = 512;
const GLOBAL_THREAD_SEGMENT = "_global";
const LOG_SCOPE = "provider-observability";
const encodeUnknownJsonString = Schema.encodeUnknownEffect(Schema.UnknownFromJsonString);
+const transientCanonicalEventTypes = new Set([
+ "content.delta",
+ "hook.progress",
+ "item.updated",
+ "task.progress",
+ "thread.realtime.audio.delta",
+ "tool.progress",
+ "turn.proposed.delta",
+]);
+
export type EventNdjsonStream = "native" | "canonical" | "orchestration";
export interface EventNdjsonLogger {
readonly filePath: string;
- write: (event: unknown, threadId: ThreadId | null) => Effect.Effect<void, never, never>;
- close: () => Effect.Effect<void, never, never>;
+ readonly write: (event: unknown, threadId: ThreadId | null) => Effect.Effect<void>;
+ readonly close: () => Effect.Effect<void>;
}
-export interface EventNdjsonLoggerOptions {
- readonly stream: EventNdjsonStream;
+export interface EventNdjsonLogStore {
+ readonly filePath: string;
+ readonly logger: (stream: EventNdjsonStream) => EventNdjsonLogger;
+ readonly close: () => Effect.Effect<void>;
+}
+
+export interface EventNdjsonLogStoreOptions {
readonly maxBytes?: number;
readonly maxFiles?: number;
readonly batchWindowMs?: number;
+ readonly maxTotalBytes?: number;
+ readonly maxAgeMs?: number;
+ readonly retentionCheckIntervalMs?: number;
+ readonly maxBufferedBytes?: number;
+ readonly maxBufferedRecords?: number;
+ readonly attribution?: ResourceAttribution["Service"];
+}
+
+export interface EventNdjsonLoggerOptions extends EventNdjsonLogStoreOptions {
+ readonly stream: EventNdjsonStream;
+}
+
+export class EventNdjsonLogConfigurationError extends Schema.TaggedErrorClass<EventNdjsonLogConfigurationError>()(
+ "EventNdjsonLogConfigurationError",
+ {
+ filePath: Schema.String,
+ option: Schema.String,
+ value: Schema.Number,
+ minimum: Schema.Number,
+ },
+) {
+ override get message(): string {
+ return `Provider event log option '${this.option}' must be an integer >= ${this.minimum}; received ${this.value} for '${this.filePath}'`;
+ }
+}
+
+export class EventNdjsonLogDirectoryError extends Schema.TaggedErrorClass<EventNdjsonLogDirectoryError>()(
+ "EventNdjsonLogDirectoryError",
+ {
+ directory: Schema.String,
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return `Failed to create provider event log directory '${this.directory}'`;
+ }
+}
+
+export type EventNdjsonLogStoreError =
+ | EventNdjsonLogConfigurationError
+ | EventNdjsonLogDirectoryError;
+
+interface ResolvedOptions {
+ readonly maxBytes: number;
+ readonly maxFiles: number;
+ readonly batchWindowMs: number;
+ readonly maxTotalBytes: number;
+ readonly maxAgeMs: number;
+ readonly retentionCheckIntervalMs: number;
+ readonly maxBufferedBytes: number;
+ readonly maxBufferedRecords: number;
+ readonly attribution: ResourceAttribution["Service"] | undefined;
}
-interface ThreadWriter {
- writeMessage: (message: string) => Effect.Effect<void>;
- close: () => Effect.Effect<void>;
+export interface PendingRecord {
+ readonly stream: EventNdjsonStream;
+ readonly threadSegment: string;
+ readonly line: string;
+ readonly bytes: number;
}
-interface LoggerState {
- readonly threadWriters: Map<string, ThreadWriter>;
- readonly failedSegments: Set<string>;
+interface StoreState {
+ readonly pending: ReadonlyArray<PendingRecord>;
+ readonly pendingBytes: number;
+ readonly sinks: ReadonlyMap<string, RotatingFileSink>;
+ readonly flushScheduled: boolean;
+ readonly closed: boolean;
+ readonly lastRetentionAt: number;
+}
+
+interface AttributionSummary {
+ readonly stream: EventNdjsonStream;
+ readonly count: number;
+ readonly logicalWriteBytes: number;
+}
+
+interface FileOperationFailure {
+ readonly filePath: string;
+ readonly cause: unknown;
+}
+
+interface RetentionResult {
+ readonly failures: ReadonlyArray<FileOperationFailure>;
+}
+
+interface DrainResult {
+ readonly attributions: ReadonlyArray<AttributionSummary>;
+ readonly failures: ReadonlyArray<FileOperationFailure>;
}
function logWarning(message: string, context: Record<string, unknown>): Effect.Effect<void> {
@@ -62,225 +163,454 @@ function resolveThreadSegment(raw: string | null | undefined): string {
return normalized ?? GLOBAL_THREAD_SEGMENT;
}
-function formatLoggerMessage(message: unknown): string {
- if (Array.isArray(message)) {
- return message.map((part) => (typeof part === "string" ? part : String(part))).join(" ");
+function resolveStreamLabel(stream: EventNdjsonStream): string {
+ return stream === "native" ? "NTIVE" : stream === "orchestration" ? "ORCH" : "CANON";
+}
+
+function providerLogPrefix(filePath: string): string {
+ const basename = NodePath.basename(filePath);
+ const extension = NodePath.extname(basename);
+ return `${extension.length > 0 ? basename.slice(0, -extension.length) : basename}.`;
+}
+
+function providerLogPath(directory: string, prefix: string, threadSegment: string): string {
+ return NodePath.join(directory, `${prefix}${threadSegment}.log`);
+}
+
+function shouldPersist(stream: EventNdjsonStream, event: unknown): boolean {
+ if (stream !== "canonical" || typeof event !== "object" || event === null) {
+ return true;
+ }
+ try {
+ const type = Reflect.get(event, "type");
+ return typeof type !== "string" || !transientCanonicalEventTypes.has(type);
+ } catch {
+ return true;
}
- return typeof message === "string" ? message : String(message);
}
-function makeLineLogger(streamLabel: string): Logger.Logger<unknown, string> {
- return Logger.make(
- ({ date, message }) =>
- `[${date.toISOString()}] ${streamLabel}: ${formatLoggerMessage(message)}\n`,
- );
+export function writeBatchedMessages(
+ sink: Pick<RotatingFileSink, "write">,
+ records: ReadonlyArray<PendingRecord>,
+ maxBytes: number,
+ onWritten: (records: ReadonlyArray<PendingRecord>) => void,
+): void {
+ let pendingRecords: Array<PendingRecord> = [];
+ let pendingBytes = 0;
+
+ const flush = () => {
+ if (pendingRecords.length === 0) return;
+ const writtenRecords = pendingRecords;
+ sink.write(writtenRecords.map((record) => record.line).join(""));
+ onWritten(writtenRecords);
+ pendingRecords = [];
+ pendingBytes = 0;
+ };
+
+ for (const record of records) {
+ if (pendingBytes > 0 && pendingBytes + record.bytes > maxBytes) {
+ flush();
+ }
+ pendingRecords.push(record);
+ pendingBytes += record.bytes;
+ if (pendingBytes >= maxBytes) {
+ flush();
+ }
+ }
+ flush();
}
-function resolveStreamLabel(stream: EventNdjsonStream): string {
- switch (stream) {
- case "native":
- return "NTIVE";
- case "canonical":
- case "orchestration":
- default:
- return "CANON";
+function isProviderLogFile(filePath: string, fileName: string, filePrefix: string): boolean {
+ if (!/\.log(?:\.\d+)?$/u.test(fileName)) return false;
+ if (fileName.startsWith(filePrefix)) return true;
+
+ const descriptor = NodeFS.openSync(filePath, "r");
+ try {
+ const header = Buffer.alloc(256);
+ const bytesRead = NodeFS.readSync(descriptor, header, 0, header.byteLength, 0);
+ return /^\[[^\]\r\n]+\] (?:NTIVE|CANON|ORCH): /u.test(header.toString("utf8", 0, bytesRead));
+ } finally {
+ NodeFS.closeSync(descriptor);
}
}
-const toLogMessage = Effect.fn("toLogMessage")(function* (
- event: unknown,
-): Effect.fn.Return<string | undefined> {
- return yield* encodeUnknownJsonString(event).pipe(
- Effect.catch((error) =>
- logWarning("failed to serialize provider event log record", {
- errorTag: errorTag(error),
- }).pipe(Effect.as(undefined)),
- ),
- );
-});
+function enforceRetention(input: {
+ readonly directory: string;
+ readonly maxTotalBytes: number;
+ readonly maxAgeMs: number;
+ readonly activeFilePaths: ReadonlySet<string>;
+ readonly filePrefix: string;
+ readonly now: number;
+}): RetentionResult {
+ const failures: Array<FileOperationFailure> = [];
+ const files: Array<{ filePath: string; mtimeMs: number; size: number }> = [];
+
+ let entries: ReadonlyArray<NodeFS.Dirent>;
+ try {
+ entries = NodeFS.readdirSync(input.directory, { withFileTypes: true });
+ } catch (cause) {
+ return { failures: [{ filePath: input.directory, cause }] };
+ }
-const makeThreadWriter = Effect.fn("makeThreadWriter")(function* (input: {
- readonly filePath: string;
- readonly maxBytes: number;
- readonly maxFiles: number;
- readonly batchWindowMs: number;
- readonly streamLabel: string;
-}): Effect.fn.Return<ThreadWriter | undefined> {
- const sinkResult = yield* Effect.sync(() => {
+ for (const entry of entries) {
+ if (!entry.isFile()) continue;
+ const filePath = NodePath.join(input.directory, entry.name);
try {
- return {
- ok: true as const,
- sink: new RotatingFileSink({
- filePath: input.filePath,
- maxBytes: input.maxBytes,
- maxFiles: input.maxFiles,
- throwOnError: true,
- }),
- };
- } catch (error) {
- return { ok: false as const, error };
+ if (!isProviderLogFile(filePath, entry.name, input.filePrefix)) continue;
+ const stat = NodeFS.statSync(filePath);
+ files.push({ filePath, mtimeMs: stat.mtimeMs, size: stat.size });
+ } catch (cause) {
+ failures.push({ filePath, cause });
}
+ }
+
+ let totalBytes = files.reduce((total, file) => total + file.size, 0);
+ const remove = (file: (typeof files)[number]) => {
+ if (input.activeFilePaths.has(file.filePath)) return false;
+ try {
+ NodeFS.rmSync(file.filePath, { force: true });
+ totalBytes -= file.size;
+ return true;
+ } catch (cause) {
+ failures.push({ filePath: file.filePath, cause });
+ return false;
+ }
+ };
+
+ const retained = files.filter((file) => {
+ if (input.now - file.mtimeMs <= input.maxAgeMs) return true;
+ return !remove(file);
});
- if (!sinkResult.ok) {
- yield* logWarning("failed to initialize provider thread log file", {
- filePath: input.filePath,
- errorTag: errorTag(sinkResult.error),
- });
- return undefined;
+ for (const file of retained.toSorted(
+ (left, right) => left.mtimeMs - right.mtimeMs || left.filePath.localeCompare(right.filePath),
+ )) {
+ if (totalBytes <= input.maxTotalBytes) break;
+ remove(file);
}
- const sink = sinkResult.sink;
- const scope = yield* Scope.make();
- const lineLogger = makeLineLogger(input.streamLabel);
- const batchedLogger = yield* Logger.batched(lineLogger, {
- window: input.batchWindowMs,
- flush: Effect.fn("makeThreadWriter.flush")(function* (messages) {
- const flushResult = yield* Effect.sync(() => {
- try {
- for (const message of messages) {
- sink.write(message);
- }
- return { ok: true as const };
- } catch (error) {
- return { ok: false as const, error };
- }
- });
+ return { failures };
+}
+
+function validateOption(input: {
+ readonly filePath: string;
+ readonly option: string;
+ readonly value: number;
+ readonly minimum: number;
+}): EventNdjsonLogConfigurationError | undefined {
+ if (Number.isInteger(input.value) && input.value >= input.minimum) return undefined;
+ return new EventNdjsonLogConfigurationError(input);
+}
+
+function resolveOptions(
+ filePath: string,
+ options: EventNdjsonLogStoreOptions,
+): Effect.Effect<ResolvedOptions, EventNdjsonLogConfigurationError> {
+ const resolved = {
+ maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
+ maxFiles: options.maxFiles ?? DEFAULT_MAX_FILES,
+ batchWindowMs: options.batchWindowMs ?? DEFAULT_BATCH_WINDOW_MS,
+ maxTotalBytes: options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES,
+ maxAgeMs: options.maxAgeMs ?? DEFAULT_MAX_AGE_MS,
+ retentionCheckIntervalMs:
+ options.retentionCheckIntervalMs ?? DEFAULT_RETENTION_CHECK_INTERVAL_MS,
+ maxBufferedBytes: options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES,
+ maxBufferedRecords: options.maxBufferedRecords ?? DEFAULT_MAX_BUFFERED_RECORDS,
+ attribution: options.attribution,
+ } satisfies ResolvedOptions;
+
+ const validations = [
+ ["maxBytes", resolved.maxBytes, 1],
+ ["maxFiles", resolved.maxFiles, 1],
+ ["batchWindowMs", resolved.batchWindowMs, 0],
+ ["maxTotalBytes", resolved.maxTotalBytes, 1],
+ ["maxAgeMs", resolved.maxAgeMs, 1],
+ ["retentionCheckIntervalMs", resolved.retentionCheckIntervalMs, 1],
+ ["maxBufferedBytes", resolved.maxBufferedBytes, 1],
+ ["maxBufferedRecords", resolved.maxBufferedRecords, 1],
+ ] as const;
+
+ for (const [option, value, minimum] of validations) {
+ const error = validateOption({ filePath, option, value, minimum });
+ if (error) return Effect.fail(error);
+ }
+ return Effect.succeed(resolved);
+}
- if (!flushResult.ok) {
- yield* logWarning("provider event log batch flush failed", {
- filePath: input.filePath,
- errorTag: errorTag(flushResult.error),
+function drainPending(input: {
+ readonly directory: string;
+ readonly options: ResolvedOptions;
+ readonly state: StoreState;
+ readonly filePrefix: string;
+ readonly now: number;
+ readonly timerFired: boolean;
+ readonly close: boolean;
+}): readonly [DrainResult, StoreState] {
+ if (input.state.closed) {
+ return [{ attributions: [], failures: [] }, input.state];
+ }
+
+ const sinks = new Map(input.state.sinks);
+ const failures: Array<FileOperationFailure> = [];
+ const attributionByStream = new Map<
+ EventNdjsonStream,
+ { count: number; logicalWriteBytes: number }
+ >();
+ const recordsBySegment = new Map<string, Array<PendingRecord>>();
+
+ for (const record of input.state.pending) {
+ const records = recordsBySegment.get(record.threadSegment) ?? [];
+ records.push(record);
+ recordsBySegment.set(record.threadSegment, records);
+ }
+
+ for (const [threadSegment, records] of recordsBySegment) {
+ const filePath = providerLogPath(input.directory, input.filePrefix, threadSegment);
+ let sink = sinks.get(threadSegment);
+ if (!sink) {
+ try {
+ sink = new RotatingFileSink({
+ filePath,
+ maxBytes: input.options.maxBytes,
+ maxFiles: input.options.maxFiles,
+ throwOnError: true,
});
+ sinks.set(threadSegment, sink);
+ } catch (cause) {
+ failures.push({ filePath, cause });
+ continue;
}
- }),
- }).pipe(Effect.provideService(Scope.Scope, scope));
+ }
- const loggerLayer = Logger.layer([batchedLogger], { mergeWithExisting: false });
+ try {
+ writeBatchedMessages(sink, records, input.options.maxBytes, (writtenRecords) => {
+ for (const record of writtenRecords) {
+ const current = attributionByStream.get(record.stream) ?? {
+ count: 0,
+ logicalWriteBytes: 0,
+ };
+ attributionByStream.set(record.stream, {
+ count: current.count + 1,
+ logicalWriteBytes: current.logicalWriteBytes + record.bytes,
+ });
+ }
+ });
+ } catch (cause) {
+ sinks.delete(threadSegment);
+ failures.push({ filePath, cause });
+ }
+ }
- return {
- writeMessage(message: string) {
- return Effect.log(message).pipe(Effect.provide(loggerLayer));
+ const retentionDue =
+ input.now - input.state.lastRetentionAt >= input.options.retentionCheckIntervalMs;
+ const retention = retentionDue
+ ? enforceRetention({
+ directory: input.directory,
+ maxTotalBytes: input.options.maxTotalBytes,
+ maxAgeMs: input.options.maxAgeMs,
+ activeFilePaths: new Set(
+ Array.from(sinks.keys(), (threadSegment) =>
+ providerLogPath(input.directory, input.filePrefix, threadSegment),
+ ),
+ ),
+ filePrefix: input.filePrefix,
+ now: input.now,
+ })
+ : { failures: [] };
+
+ return [
+ {
+ attributions: Array.from(attributionByStream, ([stream, value]) => ({
+ stream,
+ ...value,
+ })),
+ failures: [...failures, ...retention.failures],
},
- close() {
- return Scope.close(scope, Exit.void);
+ {
+ pending: [],
+ pendingBytes: 0,
+ sinks,
+ flushScheduled: input.timerFired ? false : input.state.flushScheduled,
+ closed: input.close,
+ lastRetentionAt: retentionDue ? input.now : input.state.lastRetentionAt,
},
- } satisfies ThreadWriter;
+ ];
+}
+
+const serializeEvent = Effect.fnUntraced(function* (event: unknown) {
+ return yield* encodeUnknownJsonString(event).pipe(
+ Effect.catch((error) =>
+ logWarning("failed to serialize provider event log record", {
+ errorTag: errorTag(error),
+ }).pipe(Effect.as(undefined)),
+ ),
+ );
});
-export const makeEventNdjsonLogger = Effect.fn("makeEventNdjsonLogger")(function* (
+export const makeEventNdjsonLogStore = Effect.fnUntraced(function* (
filePath: string,
- options: EventNdjsonLoggerOptions,
-): Effect.fn.Return<EventNdjsonLogger | undefined> {
- const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
- const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
- const batchWindowMs = options.batchWindowMs ?? DEFAULT_BATCH_WINDOW_MS;
- const streamLabel = resolveStreamLabel(options.stream);
-
- const directoryReady = yield* Effect.sync(() => {
- try {
- NodeFS.mkdirSync(NodePath.dirname(filePath), { recursive: true });
- return true;
- } catch (error) {
- return { ok: false as const, error };
- }
+ options: EventNdjsonLogStoreOptions = {},
+): Effect.fn.Return<EventNdjsonLogStore, EventNdjsonLogStoreError> {
+ const resolved = yield* resolveOptions(filePath, options);
+ const directory = NodePath.dirname(filePath);
+ const filePrefix = providerLogPrefix(filePath);
+
+ yield* Effect.try({
+ try: () => NodeFS.mkdirSync(directory, { recursive: true }),
+ catch: (cause) => new EventNdjsonLogDirectoryError({ directory, cause }),
});
- if (directoryReady !== true) {
- yield* logWarning("failed to create provider event log directory", {
- filePath,
- errorTag: errorTag(directoryReady.error),
+
+ const initializedAt = yield* Clock.currentTimeMillis;
+ const initialRetention = yield* Effect.sync(() =>
+ enforceRetention({
+ directory,
+ maxTotalBytes: resolved.maxTotalBytes,
+ maxAgeMs: resolved.maxAgeMs,
+ activeFilePaths: new Set(),
+ filePrefix,
+ now: initializedAt,
+ }),
+ );
+ for (const failure of initialRetention.failures) {
+ yield* logWarning("provider event log retention failed", {
+ filePath: failure.filePath,
+ errorTag: errorTag(failure.cause),
});
- return undefined;
}
- const stateRef = yield* SynchronizedRef.make<LoggerState>({
- threadWriters: new Map(),
- failedSegments: new Set(),
+ const stateRef = yield* SynchronizedRef.make<StoreState>({
+ pending: [],
+ pendingBytes: 0,
+ sinks: new Map(),
+ flushScheduled: false,
+ closed: false,
+ lastRetentionAt: initializedAt,
});
-
- const resolveThreadWriter = Effect.fn("resolveThreadWriter")(function* (
- threadSegment: string,
- ): Effect.fn.Return<ThreadWriter | undefined> {
- return yield* SynchronizedRef.modifyEffect(stateRef, (state) => {
- if (state.failedSegments.has(threadSegment)) {
- return Effect.succeed([undefined, state] as const);
- }
-
- const existing = state.threadWriters.get(threadSegment);
- if (existing) {
- return Effect.succeed([existing, state] as const);
- }
-
- return makeThreadWriter({
- filePath: NodePath.join(NodePath.dirname(filePath), `${threadSegment}.log`),
- maxBytes,
- maxFiles,
- batchWindowMs,
- streamLabel,
- }).pipe(
- Effect.map((writer) => {
- if (!writer) {
- const nextFailedSegments = new Set(state.failedSegments);
- nextFailedSegments.add(threadSegment);
- return [
- undefined,
- {
- ...state,
- failedSegments: nextFailedSegments,
- },
- ] as const;
- }
-
- const nextThreadWriters = new Map(state.threadWriters);
- nextThreadWriters.set(threadSegment, writer);
- return [
- writer,
- {
- ...state,
- threadWriters: nextThreadWriters,
- },
- ] as const;
+ const timerScope = yield* Scope.make();
+
+ const flush = Effect.fnUntraced(function* (timerFired: boolean, close: boolean) {
+ const startedAt = yield* Clock.currentTimeMillis;
+ const result = yield* SynchronizedRef.modifyEffect(stateRef, (state) =>
+ Effect.sync(() =>
+ drainPending({
+ directory,
+ options: resolved,
+ state,
+ filePrefix,
+ now: startedAt,
+ timerFired,
+ close,
}),
- );
- });
- });
+ ),
+ );
- const write = Effect.fn("write")(function* (event: unknown, threadId: ThreadId | null) {
- const threadSegment = resolveThreadSegment(threadId);
- const message = yield* toLogMessage(event);
- if (!message) {
- return;
+ for (const failure of result.failures) {
+ yield* logWarning("provider event log write or retention failed", {
+ filePath: failure.filePath,
+ errorTag: errorTag(failure.cause),
+ });
}
- const writer = yield* resolveThreadWriter(threadSegment);
- if (!writer) {
- return;
+ if (resolved.attribution && result.attributions.length > 0) {
+ const completedAt = yield* Clock.currentTimeMillis;
+ const durationMs = Math.max(0, completedAt - startedAt);
+ const totalBytes = result.attributions.reduce(
+ (total, entry) => total + entry.logicalWriteBytes,
+ 0,
+ );
+ yield* Effect.forEach(
+ result.attributions,
+ (entry) =>
+ resolved.attribution?.record({
+ component: "provider-event-log",
+ operation: `${entry.stream}.append`,
+ logicalWriteBytes: entry.logicalWriteBytes,
+ count: entry.count,
+ durationMs:
+ totalBytes === 0
+ ? 0
+ : Math.round(durationMs * (entry.logicalWriteBytes / totalBytes)),
+ }) ?? Effect.void,
+ { discard: true },
+ );
}
+ });
+
+ const scheduleFlush = Effect.fnUntraced(function* () {
+ yield* Effect.forkIn(
+ Effect.sleep(resolved.batchWindowMs).pipe(Effect.andThen(flush(true, false))),
+ timerScope,
+ { startImmediately: true },
+ );
+ });
- yield* writer.writeMessage(message);
+ const close = Effect.fnUntraced(function* () {
+ yield* flush(false, true);
+ yield* Scope.close(timerScope, Exit.void);
});
- const close = Effect.fn("close")(function* () {
- yield* SynchronizedRef.modifyEffect(stateRef, (state) =>
- Effect.gen(function* () {
- for (const writer of state.threadWriters.values()) {
- yield* writer.close();
+ const loggerViews = new Map<EventNdjsonStream, EventNdjsonLogger>();
+ const logger = (stream: EventNdjsonStream): EventNdjsonLogger => {
+ const existing = loggerViews.get(stream);
+ if (existing) return existing;
+
+ const write = Effect.fnUntraced(function* (event: unknown, threadId: ThreadId | null) {
+ if (!shouldPersist(stream, event)) return;
+ const payload = yield* serializeEvent(event);
+ if (payload === undefined) return;
+
+ const observedAt = yield* DateTime.now.pipe(Effect.map(DateTime.formatIso));
+ const line = `[${observedAt}] ${resolveStreamLabel(stream)}: ${payload}\n`;
+ const bytes = Buffer.byteLength(line);
+ const action = yield* SynchronizedRef.modifyEffect(stateRef, (state) => {
+ if (state.closed) {
+ return Effect.succeed([{ flush: false }, state] as const);
}
+ const pending = [
+ ...state.pending,
+ { stream, threadSegment: resolveThreadSegment(threadId), line, bytes },
+ ];
+ const pendingBytes = state.pendingBytes + bytes;
+ const flush =
+ resolved.batchWindowMs === 0 ||
+ pending.length >= resolved.maxBufferedRecords ||
+ pendingBytes >= resolved.maxBufferedBytes;
+ const schedule = !flush && !state.flushScheduled;
+ const nextState = {
+ ...state,
+ pending,
+ pendingBytes,
+ flushScheduled: state.flushScheduled || schedule,
+ };
+ return (schedule ? scheduleFlush() : Effect.void).pipe(
+ Effect.as([{ flush }, nextState] as const),
+ );
+ }).pipe(Effect.uninterruptible);
+
+ if (action.flush) {
+ yield* flush(false, false);
+ }
+ });
- return [
- undefined,
- {
- threadWriters: new Map<string, ThreadWriter>(),
- failedSegments: new Set<string>(),
- },
- ] as const;
- }),
- );
- });
+ const view = { filePath, write, close: () => Effect.void } satisfies EventNdjsonLogger;
+ loggerViews.set(stream, view);
+ return view;
+ };
- return {
- filePath,
- write,
- close,
- } satisfies EventNdjsonLogger;
+ return { filePath, logger, close } satisfies EventNdjsonLogStore;
+});
+
+export const makeEventNdjsonLogger = Effect.fnUntraced(function* (
+ filePath: string,
+ options: EventNdjsonLoggerOptions,
+): Effect.fn.Return<EventNdjsonLogger | undefined> {
+ const store = yield* makeEventNdjsonLogStore(filePath, options).pipe(
+ Effect.catch((error) =>
+ logWarning(error.message, { error }).pipe(
+ Effect.as<EventNdjsonLogStore | undefined>(undefined),
+ ),
+ ),
+ );
+ if (!store) return undefined;
+ return { ...store.logger(options.stream), close: store.close };
});
diff --git a/apps/server/src/provider/Layers/ProviderEventLoggers.ts b/apps/server/src/provider/Layers/ProviderEventLoggers.ts
index 711aa6e76..a4f0b01e8 100644
--- a/apps/server/src/provider/Layers/ProviderEventLoggers.ts
+++ b/apps/server/src/provider/Layers/ProviderEventLoggers.ts
@@ -1,6 +1,6 @@
/**
- * ProviderEventLoggers — single observability service that owns the two
- * shared NDJSON streams the provider runtime writes:
+ * ProviderEventLoggers — single observability service that owns the shared
+ * provider event log store and exposes its two runtime views:
*
* - `native` — provider-protocol events as the SDK emits them, written
* from inside each `<X>Adapter` factory.
@@ -13,17 +13,14 @@
* not at the boot Layer. There is no longer a single `make<X>AdapterLive(options)`
* call site where we can hand an `EventNdjsonLogger` in by hand.
* - Multiple driver instances per kind (`codex_personal`, `codex_work`)
- * should share one underlying log writer per stream — opening N writers
- * against the same rotating file would race the rotation logic. Owning
- * the loggers on a single tag keeps that invariant intact.
+ * must share one underlying log store — opening N writers against the
+ * same rotating file would race the rotation logic. Owning the loggers on
+ * a single tag keeps that invariant intact.
* - Tests can swap one (or both) loggers with in-memory recorders by
* `Layer.succeed(ProviderEventLoggers, { native, canonical })` instead of
* juggling per-Layer option threading.
*
- * Both fields are optional. `makeEventNdjsonLogger` returns `undefined` when
- * the target directory cannot be created; we forward that as `undefined`
- * rather than failing the boot Layer, matching the previous best-effort
- * behavior of `server.ts`.
+ * Both fields are optional because observability must not prevent startup.
*
* @module provider/Layers/ProviderEventLoggers
*/
@@ -32,24 +29,23 @@ import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import { ServerConfig } from "../../config.ts";
-import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
-
-export interface ProviderEventLoggersShape {
- readonly native: EventNdjsonLogger | undefined;
- readonly canonical: EventNdjsonLogger | undefined;
-}
+import * as ResourceAttribution from "../../resourceTelemetry/ResourceAttribution.ts";
+import * as EventNdjsonLogger from "./EventNdjsonLogger.ts";
/**
* Shared logger pair for native + canonical provider event streams.
*
* Service value is intentionally a struct of two optional loggers rather
* than two parallel tags. Construction site is one place
- * (`ProviderEventLoggersLive`); consumers (drivers, `ProviderService`) read
- * one tag and pluck the field they need.
+ * (`layer`); consumers (drivers, `ProviderService`) read one tag and pluck the
+ * field they need.
*/
export class ProviderEventLoggers extends Context.Service<
ProviderEventLoggers,
- ProviderEventLoggersShape
+ {
+ readonly native: EventNdjsonLogger.EventNdjsonLogger | undefined;
+ readonly canonical: EventNdjsonLogger.EventNdjsonLogger | undefined;
+ }
>()("t3/provider/Layers/ProviderEventLoggers") {}
/**
@@ -57,29 +53,38 @@ export class ProviderEventLoggers extends Context.Service<
* + canonical logging entirely. Keeps the tag non-optional in the type
* system while letting the runtime treat absence as a no-op.
*/
-export const NoOpProviderEventLoggers: ProviderEventLoggersShape = {
+export const NoOpProviderEventLoggers: ProviderEventLoggers["Service"] = {
native: undefined,
canonical: undefined,
};
/**
- * Live Layer that builds both loggers from `ServerConfig.providerEventLogPath`.
- * If the directory create fails for either stream, the corresponding field
- * is `undefined` and writes from that stream become no-ops downstream.
+ * Builds both stream views over one shared store. Setup failures are logged
+ * and downgraded to the no-op service so diagnostics never block startup.
*/
-export const ProviderEventLoggersLive = Layer.effect(
- ProviderEventLoggers,
- Effect.gen(function* () {
- const { providerEventLogPath } = yield* ServerConfig;
- const native = yield* makeEventNdjsonLogger(providerEventLogPath, {
- stream: "native",
- });
- const canonical = yield* makeEventNdjsonLogger(providerEventLogPath, {
- stream: "canonical",
- });
- return {
- native,
- canonical,
- } satisfies ProviderEventLoggersShape;
- }),
-);
+export const make = Effect.gen(function* () {
+ const { providerEventLogPath } = yield* ServerConfig;
+ const attribution = yield* ResourceAttribution.ResourceAttribution;
+ const store = yield* EventNdjsonLogger.makeEventNdjsonLogStore(providerEventLogPath, {
+ attribution,
+ }).pipe(
+ Effect.catch((error) =>
+ Effect.logWarning(error.message, { error }).pipe(
+ Effect.annotateLogs({ scope: "provider-observability" }),
+ Effect.as<EventNdjsonLogger.EventNdjsonLogStore | undefined>(undefined),
+ ),
+ ),
+ );
+
+ if (!store) {
+ return ProviderEventLoggers.of(NoOpProviderEventLoggers);
+ }
+
+ yield* Effect.addFinalizer(() => store.close());
+ return ProviderEventLoggers.of({
+ native: store.logger("native"),
+ canonical: store.logger("canonical"),
+ });
+});
+
+export const layer = Layer.effect(ProviderEventLoggers, make);
diff --git a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
index 384de852f..dcc3ac0b5 100644
--- a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
@@ -34,10 +34,13 @@ import {
type ProviderInstanceConfigMap,
ProviderInstanceId,
} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
import { ServerConfig } from "../../config.ts";
import { ServerSettingsService } from "../../serverSettings.ts";
import { ClaudeDriver } from "../Drivers/ClaudeDriver.ts";
@@ -56,6 +59,37 @@ const TestHttpClientLive = Layer.succeed(
),
);
+const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
+
+const BackgroundPolicyAlwaysRunLayer = Layer.mock(BackgroundPolicy.BackgroundPolicy)({
+ reportClientActivity: () => Effect.void,
+ removeRpcClient: () => Effect.void,
+ reportHostPowerState: () => Effect.void,
+ snapshot: Effect.succeed({
+ hostPower: {
+ source: "unknown",
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt: TEST_EPOCH,
+ },
+ leases: [],
+ activeForegroundLeaseCount: 0,
+ activeScopeKeys: [],
+ shouldRunOpportunisticWork: true,
+ updatedAt: TEST_EPOCH,
+ }),
+ streamChanges: Stream.empty,
+ hasDemand: () => Effect.succeed(true),
+ shouldRunScopeWork: () => Effect.succeed(true),
+ shouldRunOpportunisticWork: Effect.succeed(true),
+});
+
const makeCodexConfig = (overrides: Partial<CodexSettings>): CodexSettings => ({
enabled: false,
binaryPath: "codex",
@@ -109,6 +143,7 @@ describe("ProviderInstanceRegistryLive — multi-instance codex slice", () => {
prefix: "provider-instance-registry-test",
}).pipe(
Layer.provideMerge(NodeServices.layer),
+ Layer.provideMerge(BackgroundPolicyAlwaysRunLayer),
Layer.provideMerge(ServerSettingsService.layerTest()),
Layer.provideMerge(TestHttpClientLive),
Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
@@ -247,6 +282,7 @@ describe("ProviderInstanceRegistryLive — all drivers slice", () => {
prefix: "provider-instance-registry-all-drivers-test",
}).pipe(
Layer.provideMerge(infraLayer),
+ Layer.provideMerge(BackgroundPolicyAlwaysRunLayer),
Layer.provideMerge(ServerSettingsService.layerTest()),
Layer.provideMerge(TestHttpClientLive),
Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.test.ts b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
index 3f00d3cc6..c78ecb395 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
@@ -1,5 +1,6 @@
import * as NodeServices from "@effect/platform-node/NodeServices";
import { describe, it, assert } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Fiber from "effect/Fiber";
@@ -32,6 +33,7 @@ import { applyServerSettingsPatch } from "@t3tools/shared/serverSettings";
import { checkCodexProviderStatus, type CodexAppServerProviderSnapshot } from "./CodexProvider.ts";
import { checkClaudeProviderStatus } from "./ClaudeProvider.ts";
+import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
import * as OpenCodeRuntime from "../opencodeRuntime.ts";
import * as ProviderEventLoggers from "./ProviderEventLoggers.ts";
import { ProviderInstanceRegistryHydrationLive } from "./ProviderInstanceRegistryHydration.ts";
@@ -65,6 +67,7 @@ process.env.T3CODE_CURSOR_ENABLED = "1";
// ── Test helpers ────────────────────────────────────────────────────
const encoder = new TextEncoder();
+const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
const TestHttpClientLive = Layer.succeed(
HttpClient.HttpClient,
@@ -73,6 +76,35 @@ const TestHttpClientLive = Layer.succeed(
),
);
+const BackgroundPolicyAlwaysRunLayer = Layer.mock(BackgroundPolicy.BackgroundPolicy)({
+ reportClientActivity: () => Effect.void,
+ removeRpcClient: () => Effect.void,
+ reportHostPowerState: () => Effect.void,
+ snapshot: Effect.succeed({
+ hostPower: {
+ source: "unknown",
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt: TEST_EPOCH,
+ },
+ leases: [],
+ activeForegroundLeaseCount: 0,
+ activeScopeKeys: [],
+ shouldRunOpportunisticWork: true,
+ updatedAt: TEST_EPOCH,
+ }),
+ streamChanges: Stream.empty,
+ hasDemand: () => Effect.succeed(true),
+ shouldRunScopeWork: () => Effect.succeed(true),
+ shouldRunOpportunisticWork: Effect.succeed(true),
+});
+
function selectDescriptor(
id: string,
label: string,
@@ -297,6 +329,11 @@ function makeMutableServerSettingsService(
get streamChanges() {
return Stream.fromPubSub(changes);
},
+ get subscribeChanges() {
+ return PubSub.subscribe(changes).pipe(
+ Effect.map((subscription) => Stream.fromSubscription(subscription)),
+ );
+ },
} satisfies ServerSettingsModule.ServerSettingsService["Service"];
});
}
@@ -1000,6 +1037,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
prefix: "t3-provider-registry-merged-persist-",
}),
),
+ Layer.provideMerge(BackgroundPolicyAlwaysRunLayer),
Layer.provideMerge(NodeServices.layer),
),
).pipe(Scope.provide(scope));
@@ -1235,6 +1273,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
prefix: "t3-provider-registry-refresh-failure-",
}),
),
+ Layer.provideMerge(BackgroundPolicyAlwaysRunLayer),
Layer.provideMerge(NodeServices.layer),
),
).pipe(Scope.provide(scope));
@@ -1342,6 +1381,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
prefix: "t3-provider-registry-sync-failure-",
}),
),
+ Layer.provideMerge(BackgroundPolicyAlwaysRunLayer),
Layer.provideMerge(NodeServices.layer),
),
).pipe(Scope.provide(scope));
@@ -1446,6 +1486,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
),
),
Layer.provideMerge(OpenCodeRuntime.OpenCodeRuntimeLive),
+ Layer.provideMerge(BackgroundPolicyAlwaysRunLayer),
// NO spawner mock — `ChildProcessSpawner` is supplied by the
// outer `NodeServices.layer` on `it.layer(...)` and will
// genuinely spawn a subprocess. The missing-binary ENOENT is
@@ -1545,6 +1586,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
}),
),
Layer.provideMerge(NodeServices.layer),
+ Layer.provideMerge(BackgroundPolicyAlwaysRunLayer),
);
const runtimeServices = yield* Layer.build(providerRegistryLayer).pipe(
Scope.provide(scope),
@@ -1660,6 +1702,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
),
Layer.provideMerge(OpenCodeRuntime.OpenCodeRuntimeLive),
Layer.provideMerge(NodeServices.layer),
+ Layer.provideMerge(BackgroundPolicyAlwaysRunLayer),
);
const runtimeServices = yield* Layer.build(providerRegistryLayer).pipe(
Scope.provide(scope),
@@ -1720,6 +1763,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
),
),
Layer.provideMerge(OpenCodeRuntime.OpenCodeRuntimeLive),
+ Layer.provideMerge(BackgroundPolicyAlwaysRunLayer),
Layer.provideMerge(
mockCommandSpawnerLayer((command, args) => {
if (command === "cursor-agent") {
diff --git a/apps/server/src/provider/makeManagedServerProvider.test.ts b/apps/server/src/provider/makeManagedServerProvider.test.ts
index ba1f01fe2..5bfd3e14c 100644
--- a/apps/server/src/provider/makeManagedServerProvider.test.ts
+++ b/apps/server/src/provider/makeManagedServerProvider.test.ts
@@ -1,16 +1,28 @@
import { describe, it, assert } from "@effect/vitest";
-import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+import {
+ DEFAULT_SERVER_SETTINGS,
+ ProviderDriverKind,
+ ProviderInstanceId,
+ type ServerProvider,
+} from "@t3tools/contracts";
import { createModelCapabilities } from "@t3tools/shared/model";
+import * as DateTime from "effect/DateTime";
import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
import * as PubSub from "effect/PubSub";
import * as Ref from "effect/Ref";
import * as Stream from "effect/Stream";
+import { TestClock } from "effect/testing";
+import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
+import { ServerSettingsService } from "../serverSettings.ts";
import { makeManagedServerProvider } from "./makeManagedServerProvider.ts";
const emptyCapabilities = createModelCapabilities({ optionDescriptors: [] });
+const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
const fastModeCapabilities = createModelCapabilities({
optionDescriptors: [
{
@@ -87,6 +99,43 @@ const refreshedSnapshotSecond: ServerProvider = {
message: "Refreshed provider availability again.",
};
+function makeBackgroundPolicyLayer(shouldRunScopeWork: boolean) {
+ return Layer.mock(BackgroundPolicy.BackgroundPolicy)({
+ reportClientActivity: () => Effect.void,
+ removeRpcClient: () => Effect.void,
+ reportHostPowerState: () => Effect.void,
+ snapshot: Effect.succeed({
+ hostPower: {
+ source: "unknown",
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt: TEST_EPOCH,
+ },
+ leases: [],
+ activeForegroundLeaseCount: 0,
+ activeScopeKeys: [],
+ shouldRunOpportunisticWork: true,
+ updatedAt: TEST_EPOCH,
+ }),
+ streamChanges: Stream.empty,
+ hasDemand: () => Effect.succeed(shouldRunScopeWork),
+ shouldRunScopeWork: () => Effect.succeed(shouldRunScopeWork),
+ shouldRunOpportunisticWork: Effect.succeed(shouldRunScopeWork),
+ });
+}
+
+const BackgroundPolicyAlwaysRunLayer = makeBackgroundPolicyLayer(true);
+const BackgroundPolicyNeverRunLayer = makeBackgroundPolicyLayer(false);
+const ServerSettingsTestLayer = ServerSettingsService.layerTest();
+const AlwaysRunTestLayer = Layer.merge(BackgroundPolicyAlwaysRunLayer, ServerSettingsTestLayer);
+const NeverRunTestLayer = Layer.merge(BackgroundPolicyNeverRunLayer, ServerSettingsTestLayer);
+
const enrichedSnapshotSecond: ServerProvider = {
...refreshedSnapshotSecond,
checkedAt: "2026-04-10T00:00:04.000Z",
@@ -140,7 +189,125 @@ describe("makeManagedServerProvider", () => {
assert.deepStrictEqual(latest, refreshedSnapshot);
assert.strictEqual(yield* Ref.get(checkCalls), 1);
}),
- ),
+ ).pipe(Effect.provide(AlwaysRunTestLayer)),
+ );
+
+ it.effect("skips periodic provider refreshes without foreground provider-status demand", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const checkCalls = yield* Ref.make(0);
+ const initialCheckDone = yield* Deferred.make<void>();
+ yield* makeManagedServerProvider<TestSettings>({
+ maintenanceCapabilities,
+ getSettings: Effect.succeed({ enabled: true }),
+ streamSettings: Stream.empty,
+ haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
+ initialSnapshot: () => Effect.succeed(initialSnapshot),
+ checkProvider: Ref.updateAndGet(checkCalls, (count) => count + 1).pipe(
+ Effect.tap((count) =>
+ count === 1
+ ? Deferred.succeed(initialCheckDone, undefined).pipe(Effect.ignore)
+ : Effect.void,
+ ),
+ Effect.as(refreshedSnapshot),
+ ),
+ refreshInterval: "1 second",
+ });
+
+ yield* Deferred.await(initialCheckDone);
+ yield* TestClock.adjust("1 second");
+ yield* Effect.yieldNow;
+
+ assert.strictEqual(yield* Ref.get(checkCalls), 1);
+ }),
+ ).pipe(Effect.provide(Layer.mergeAll(NeverRunTestLayer, TestClock.layer()))),
+ );
+
+ it.effect("disables periodic provider refreshes when the explicit interval is zero", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const checkCalls = yield* Ref.make(0);
+ const initialCheckDone = yield* Deferred.make<void>();
+ yield* makeManagedServerProvider<TestSettings>({
+ maintenanceCapabilities,
+ getSettings: Effect.succeed({ enabled: true }),
+ streamSettings: Stream.empty,
+ haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
+ initialSnapshot: () => Effect.succeed(initialSnapshot),
+ checkProvider: Ref.updateAndGet(checkCalls, (count) => count + 1).pipe(
+ Effect.tap(() => Deferred.succeed(initialCheckDone, undefined).pipe(Effect.ignore)),
+ Effect.as(refreshedSnapshot),
+ ),
+ refreshInterval: 0,
+ });
+
+ yield* Deferred.await(initialCheckDone);
+ yield* TestClock.adjust("5 minutes");
+ yield* Effect.yieldNow;
+
+ assert.strictEqual(yield* Ref.get(checkCalls), 1);
+ }),
+ ).pipe(Effect.provide(Layer.mergeAll(AlwaysRunTestLayer, TestClock.layer()))),
+ );
+
+ it.effect("wakes a sleeping provider refresh loop when its interval changes", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const initialServerSettings = {
+ ...DEFAULT_SERVER_SETTINGS,
+ providerHealthRefreshInterval: Duration.hours(1),
+ };
+ const serverSettingsRef = yield* Ref.make(initialServerSettings);
+ const serverSettingsChanges = yield* PubSub.unbounded<typeof initialServerSettings>();
+ const serverSettingsLayer = Layer.succeed(
+ ServerSettingsService,
+ ServerSettingsService.of({
+ start: Effect.void,
+ ready: Effect.void,
+ getSettings: Ref.get(serverSettingsRef),
+ updateSettings: () => Effect.die(new Error("unused in this test")),
+ streamChanges: Stream.empty,
+ subscribeChanges: PubSub.subscribe(serverSettingsChanges).pipe(
+ Effect.map((subscription) => Stream.fromSubscription(subscription)),
+ ),
+ }),
+ );
+ const checkCalls = yield* Ref.make(0);
+ const initialCheckDone = yield* Deferred.make<void>();
+ const periodicCheckDone = yield* Deferred.make<void>();
+
+ yield* makeManagedServerProvider<TestSettings>({
+ maintenanceCapabilities,
+ getSettings: Effect.succeed({ enabled: true }),
+ streamSettings: Stream.empty,
+ haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
+ initialSnapshot: () => Effect.succeed(initialSnapshot),
+ checkProvider: Ref.updateAndGet(checkCalls, (count) => count + 1).pipe(
+ Effect.tap((count) =>
+ count === 1
+ ? Deferred.succeed(initialCheckDone, undefined).pipe(Effect.ignore)
+ : Deferred.succeed(periodicCheckDone, undefined).pipe(Effect.ignore),
+ ),
+ Effect.as(refreshedSnapshot),
+ ),
+ }).pipe(Effect.provide(Layer.merge(BackgroundPolicyAlwaysRunLayer, serverSettingsLayer)));
+
+ yield* Deferred.await(initialCheckDone);
+ const nextServerSettings = {
+ ...initialServerSettings,
+ providerHealthRefreshInterval: Duration.seconds(1),
+ };
+ yield* Ref.set(serverSettingsRef, nextServerSettings);
+ yield* PubSub.publish(serverSettingsChanges, nextServerSettings);
+ yield* Effect.yieldNow;
+
+ yield* TestClock.adjust("999 millis");
+ assert.strictEqual(yield* Ref.get(checkCalls), 1);
+ yield* TestClock.adjust("1 millis");
+ yield* Deferred.await(periodicCheckDone);
+ assert.strictEqual(yield* Ref.get(checkCalls), 2);
+ }),
+ ).pipe(Effect.provide(TestClock.layer())),
);
it.effect("reruns the provider check when streamed settings change", () =>
@@ -185,7 +352,7 @@ describe("makeManagedServerProvider", () => {
assert.deepStrictEqual(latest, refreshedSnapshotSecond);
assert.strictEqual(yield* Ref.get(checkCalls), 2);
}),
- ),
+ ).pipe(Effect.provide(AlwaysRunTestLayer)),
);
it.effect("streams supplemental snapshot updates after the base provider check completes", () =>
@@ -223,7 +390,7 @@ describe("makeManagedServerProvider", () => {
assert.deepStrictEqual(updates, [refreshedSnapshot, enrichedSnapshot]);
assert.deepStrictEqual(latest, enrichedSnapshot);
}),
- ),
+ ).pipe(Effect.provide(AlwaysRunTestLayer)),
);
it.effect("ignores stale enrichment callbacks after a newer refresh advances generation", () =>
@@ -284,6 +451,6 @@ describe("makeManagedServerProvider", () => {
]);
assert.deepStrictEqual(latest, enrichedSnapshotSecond);
}),
- ),
+ ).pipe(Effect.provide(AlwaysRunTestLayer)),
);
});
diff --git a/apps/server/src/provider/makeManagedServerProvider.ts b/apps/server/src/provider/makeManagedServerProvider.ts
index bbf301fa4..d2b6b52e8 100644
--- a/apps/server/src/provider/makeManagedServerProvider.ts
+++ b/apps/server/src/provider/makeManagedServerProvider.ts
@@ -1,16 +1,23 @@
-import type { ServerProvider } from "@t3tools/contracts";
+import {
+ DEFAULT_PROVIDER_HEALTH_REFRESH_INTERVAL,
+ type ServerProvider,
+ ServerSettingsError,
+} from "@t3tools/contracts";
+import { resolveServerBackgroundActivitySettings } from "@t3tools/shared/backgroundActivitySettings";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Equal from "effect/Equal";
import * as Fiber from "effect/Fiber";
import * as PubSub from "effect/PubSub";
+import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import * as Scope from "effect/Scope";
import * as Stream from "effect/Stream";
import * as Semaphore from "effect/Semaphore";
+import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
+import { ServerSettingsService } from "../serverSettings.ts";
import type { ServerProviderShape } from "./Services/ServerProvider.ts";
-import { ServerSettingsError } from "@t3tools/contracts";
interface ProviderSnapshotState {
readonly snapshot: ServerProvider;
@@ -33,7 +40,13 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
readonly publishSnapshot: (snapshot: ServerProvider) => Effect.Effect<void>;
}) => Effect.Effect<void>;
readonly refreshInterval?: Duration.Input;
-}): Effect.fn.Return<ServerProviderShape, ServerSettingsError, Scope.Scope> {
+}): Effect.fn.Return<
+ ServerProviderShape,
+ ServerSettingsError,
+ Scope.Scope | BackgroundPolicy.BackgroundPolicy | ServerSettingsService
+> {
+ const backgroundPolicy = yield* BackgroundPolicy.BackgroundPolicy;
+ const serverSettings = yield* ServerSettingsService;
const refreshSemaphore = yield* Semaphore.make(1);
const changesPubSub = yield* Effect.acquireRelease(
PubSub.unbounded<ServerProvider>(),
@@ -134,13 +147,68 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
return yield* applySnapshot(nextSettings, { forceRefresh: true });
});
+ const hasProviderStatusDemand = Effect.gen(function* () {
+ const state = yield* Ref.get(snapshotStateRef);
+ const instanceId = state.snapshot.instanceId;
+ const [genericDemand, instanceDemand] = yield* Effect.all([
+ backgroundPolicy.shouldRunScopeWork({ type: "provider-status" }),
+ backgroundPolicy.shouldRunScopeWork({ type: "provider-status", instanceId }),
+ ]);
+ return genericDemand || instanceDemand;
+ });
+
+ const getRefreshInterval =
+ input.refreshInterval !== undefined
+ ? Effect.succeed(input.refreshInterval)
+ : serverSettings.getSettings.pipe(
+ Effect.map(
+ (settings) =>
+ resolveServerBackgroundActivitySettings(settings).providerHealthRefreshInterval,
+ ),
+ Effect.orElseSucceed(() => DEFAULT_PROVIDER_HEALTH_REFRESH_INTERVAL),
+ );
+
+ const refreshIntervalChanges = yield* Queue.sliding<void>(1);
+ if (input.refreshInterval === undefined) {
+ const serverSettingsChanges = yield* serverSettings.subscribeChanges;
+ yield* serverSettingsChanges.pipe(
+ Stream.map((settings) =>
+ Duration.toMillis(
+ resolveServerBackgroundActivitySettings(settings).providerHealthRefreshInterval,
+ ),
+ ),
+ Stream.changes,
+ Stream.runForEach(() => Queue.offer(refreshIntervalChanges, undefined).pipe(Effect.asVoid)),
+ Effect.forkScoped,
+ );
+ }
+
yield* Stream.runForEach(input.streamSettings, (nextSettings) =>
Effect.asVoid(applySnapshot(nextSettings)),
).pipe(Effect.forkScoped);
yield* Effect.forever(
- Effect.sleep(input.refreshInterval ?? "60 seconds").pipe(
- Effect.flatMap(() => refreshSnapshot()),
+ getRefreshInterval.pipe(
+ Effect.flatMap((refreshInterval) =>
+ Effect.raceFirst(
+ Effect.sleep(
+ Duration.toMillis(Duration.fromInputUnsafe(refreshInterval)) <= 0
+ ? "60 seconds"
+ : refreshInterval,
+ ).pipe(Effect.as(true)),
+ Queue.take(refreshIntervalChanges).pipe(Effect.as(false)),
+ ).pipe(
+ Effect.flatMap((intervalElapsed) =>
+ intervalElapsed && Duration.toMillis(Duration.fromInputUnsafe(refreshInterval)) > 0
+ ? hasProviderStatusDemand.pipe(
+ Effect.flatMap((shouldRefresh) =>
+ shouldRefresh ? refreshSnapshot().pipe(Effect.asVoid) : Effect.void,
+ ),
+ )
+ : Effect.void,
+ ),
+ ),
+ ),
Effect.ignoreCause({ log: true }),
),
).pipe(Effect.forkScoped);
diff --git a/apps/server/src/resourceTelemetry/DesktopTelemetryReceiver.test.ts b/apps/server/src/resourceTelemetry/DesktopTelemetryReceiver.test.ts
new file mode 100644
index 000000000..50c8ea2b7
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/DesktopTelemetryReceiver.test.ts
@@ -0,0 +1,105 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+
+import { it } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import { assert, describe, expect } from "vite-plus/test";
+
+import {
+ type DesktopTelemetryReceiverHealth,
+ initialDesktopTelemetryContactAt,
+ isDesktopTelemetryContactStale,
+ recordDesktopTelemetrySampleHealth,
+ requireDesktopTelemetryWriteProgress,
+ resolveDesktopTelemetrySnapshotStaleAfterMs,
+ writeAllToFileDescriptor,
+} from "./DesktopTelemetryReceiver.ts";
+
+describe("DesktopTelemetryReceiver", () => {
+ it("degrades a hello-only stream after the first-sample deadline", () => {
+ expect(isDesktopTelemetryContactStale(Option.some(1_000), 90_999)).toBe(false);
+ expect(isDesktopTelemetryContactStale(Option.some(1_000), 91_000)).toBe(true);
+ expect(isDesktopTelemetryContactStale(Option.none(), 1_000_000)).toBe(false);
+ });
+
+ it("starts the stale deadline as soon as a telemetry descriptor is opened", () => {
+ expect(initialDesktopTelemetryContactAt(7, 1_000)).toEqual(Option.some(1_000));
+ expect(initialDesktopTelemetryContactAt(undefined, 1_000)).toEqual(Option.none());
+ });
+
+ it("keeps the snapshot deadline beyond the configured idle polling interval", () => {
+ expect(resolveDesktopTelemetrySnapshotStaleAfterMs(30_000, 120_000)).toBe(150_000);
+ expect(resolveDesktopTelemetrySnapshotStaleAfterMs(60_000, 600_000)).toBe(630_000);
+ expect(resolveDesktopTelemetrySnapshotStaleAfterMs(1_000, 1_000)).toBe(90_000);
+ });
+
+ it.effect("publishes the latest sample timestamp while health remains healthy", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const initialSample = DateTime.makeUnsafe(1_000);
+ const nextSample = DateTime.makeUnsafe(2_000);
+ const health = yield* Ref.make<DesktopTelemetryReceiverHealth>({
+ status: "healthy",
+ lastSampleAt: Option.some(initialSample),
+ lastError: Option.none<string>(),
+ });
+ const healthChanges = yield* PubSub.sliding<DesktopTelemetryReceiverHealth>(4);
+ const subscription = yield* PubSub.subscribe(healthChanges);
+
+ yield* recordDesktopTelemetrySampleHealth(health, healthChanges, nextSample);
+ const published = yield* PubSub.take(subscription).pipe(Effect.timeout("1 second"));
+
+ expect(DateTime.toEpochMillis(Option.getOrThrow(published.lastSampleAt))).toBe(2_000);
+ }),
+ ),
+ );
+
+ it.effect("writes control messages through the asynchronous descriptor path", () =>
+ Effect.acquireUseRelease(
+ Effect.sync(() => {
+ const directory = NodeFS.mkdtempSync(
+ NodePath.join(NodeOS.tmpdir(), "t3-desktop-telemetry-control-test-"),
+ );
+ const path = NodePath.join(directory, "control.ndjson");
+ return {
+ directory,
+ path,
+ fd: NodeFS.openSync(path, "w"),
+ };
+ }),
+ ({ fd, path }) =>
+ Effect.gen(function* () {
+ const payload = Buffer.from('{"type":"setDiagnosticsDemand","enabled":true}\n');
+ yield* writeAllToFileDescriptor(fd, payload);
+ NodeFS.fsyncSync(fd);
+
+ assert.equal(NodeFS.readFileSync(path, "utf8"), payload.toString("utf8"));
+ }),
+ ({ directory, fd }) =>
+ Effect.sync(() => {
+ NodeFS.closeSync(fd);
+ NodeFS.rmSync(directory, { recursive: true, force: true });
+ }),
+ ),
+ );
+
+ it.effect("models a zero-byte control write as a stalled descriptor", () =>
+ Effect.gen(function* () {
+ const error = yield* requireDesktopTelemetryWriteProgress(7, 42, 0).pipe(Effect.flip);
+
+ expect(error._tag).toBe("DesktopTelemetryControlStalled");
+ expect(error.fd).toBe(7);
+ expect(error.remainingBytes).toBe(42);
+ expect(error.message).toBe(
+ "Desktop telemetry control stalled on fd 7 with 42 bytes remaining.",
+ );
+ yield* requireDesktopTelemetryWriteProgress(7, 42, 1);
+ }),
+ );
+});
diff --git a/apps/server/src/resourceTelemetry/DesktopTelemetryReceiver.ts b/apps/server/src/resourceTelemetry/DesktopTelemetryReceiver.ts
new file mode 100644
index 000000000..1fca5696a
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/DesktopTelemetryReceiver.ts
@@ -0,0 +1,662 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+
+import * as NodeStream from "@effect/platform-node/NodeStream";
+import {
+ DesktopHostTelemetryMessage,
+ type DesktopHostTelemetryMessage as DesktopHostTelemetryMessageValue,
+ type DesktopHostTelemetrySnapshot,
+ DesktopTelemetryControlMessage,
+ type ResourceTelemetrySourceStatus,
+} from "@t3tools/contracts";
+import { resolveServerBackgroundActivitySettings } from "@t3tools/shared/backgroundActivitySettings";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as Ndjson from "effect/unstable/encoding/Ndjson";
+
+import { ServerConfig } from "../config.ts";
+import { ServerSettingsService } from "../serverSettings.ts";
+import { subscribeBeforeSnapshotWithoutMutex } from "../utils/subscribeBeforeSnapshot.ts";
+
+const INITIAL_SAMPLE_DEADLINE_MS = 90_000;
+const MIN_SNAPSHOT_STALE_AFTER_MS = 90_000;
+const STALE_GRACE_MS = 30_000;
+const DEFAULT_HOST_POWER_ACTIVE_INTERVAL_MS = 30_000;
+const DEFAULT_HOST_POWER_IDLE_INTERVAL_MS = 120_000;
+const STALE_CHECK_INTERVAL = Duration.seconds(30);
+
+export class DesktopTelemetryDescriptorUnavailable extends Schema.TaggedErrorClass<DesktopTelemetryDescriptorUnavailable>()(
+ "DesktopTelemetryDescriptorUnavailable",
+ {
+ mode: Schema.String,
+ },
+) {
+ override get message(): string {
+ return `Desktop telemetry descriptor is unavailable in '${this.mode}' mode.`;
+ }
+}
+
+export class DesktopTelemetryProtocolMismatch extends Schema.TaggedErrorClass<DesktopTelemetryProtocolMismatch>()(
+ "DesktopTelemetryProtocolMismatch",
+ {
+ expectedVersion: Schema.Number,
+ receivedVersion: Schema.Number,
+ },
+) {
+ override get message(): string {
+ return `Desktop telemetry protocol ${this.receivedVersion} is incompatible with expected protocol ${this.expectedVersion}.`;
+ }
+}
+
+export class DesktopTelemetryDecodeFailed extends Schema.TaggedErrorClass<DesktopTelemetryDecodeFailed>()(
+ "DesktopTelemetryDecodeFailed",
+ {
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return "Failed to decode desktop telemetry.";
+ }
+}
+
+export class DesktopTelemetryStreamFailed extends Schema.TaggedErrorClass<DesktopTelemetryStreamFailed>()(
+ "DesktopTelemetryStreamFailed",
+ {
+ fd: Schema.Number,
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return `Desktop telemetry stream on fd ${this.fd} failed.`;
+ }
+}
+
+export class DesktopTelemetryStreamClosed extends Schema.TaggedErrorClass<DesktopTelemetryStreamClosed>()(
+ "DesktopTelemetryStreamClosed",
+ {
+ fd: Schema.Number,
+ },
+) {
+ override get message(): string {
+ return `Desktop telemetry stream on fd ${this.fd} closed.`;
+ }
+}
+
+export class DesktopTelemetryStale extends Schema.TaggedErrorClass<DesktopTelemetryStale>()(
+ "DesktopTelemetryStale",
+ {
+ fd: Schema.Number,
+ staleAfterMs: Schema.Number,
+ },
+) {
+ override get message(): string {
+ return `Desktop telemetry on fd ${this.fd} has not updated for ${this.staleAfterMs}ms.`;
+ }
+}
+
+export type DesktopTelemetryReceiverError =
+ | DesktopTelemetryDescriptorUnavailable
+ | DesktopTelemetryProtocolMismatch
+ | DesktopTelemetryDecodeFailed
+ | DesktopTelemetryStreamFailed
+ | DesktopTelemetryStreamClosed;
+
+export class DesktopTelemetryControlFailed extends Schema.TaggedErrorClass<DesktopTelemetryControlFailed>()(
+ "DesktopTelemetryControlFailed",
+ {
+ fd: Schema.Number,
+ operation: Schema.String,
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return `Desktop telemetry control '${this.operation}' failed on fd ${this.fd}.`;
+ }
+}
+
+export class DesktopTelemetryControlStalled extends Schema.TaggedErrorClass<DesktopTelemetryControlStalled>()(
+ "DesktopTelemetryControlStalled",
+ {
+ fd: Schema.Number,
+ remainingBytes: Schema.Number,
+ },
+) {
+ override get message(): string {
+ return `Desktop telemetry control stalled on fd ${this.fd} with ${this.remainingBytes} bytes remaining.`;
+ }
+}
+
+export type DesktopTelemetryControlError =
+ | DesktopTelemetryControlFailed
+ | DesktopTelemetryControlStalled;
+
+export interface DesktopTelemetryReceiverHealth {
+ readonly status: ResourceTelemetrySourceStatus;
+ readonly lastSampleAt: Option.Option<DateTime.Utc>;
+ readonly lastError: Option.Option<string>;
+}
+
+export class DesktopTelemetryReceiver extends Context.Service<
+ DesktopTelemetryReceiver,
+ {
+ readonly latest: Effect.Effect<Option.Option<DesktopHostTelemetrySnapshot>>;
+ readonly changes: Stream.Stream<DesktopHostTelemetrySnapshot>;
+ readonly subscribe: Effect.Effect<
+ {
+ readonly latest: Option.Option<DesktopHostTelemetrySnapshot>;
+ readonly changes: Stream.Stream<DesktopHostTelemetrySnapshot>;
+ },
+ never,
+ Scope.Scope
+ >;
+ readonly health: Effect.Effect<DesktopTelemetryReceiverHealth>;
+ readonly subscribeHealth: Effect.Effect<
+ {
+ readonly latest: DesktopTelemetryReceiverHealth;
+ readonly changes: Stream.Stream<DesktopTelemetryReceiverHealth>;
+ },
+ never,
+ Scope.Scope
+ >;
+ readonly setDiagnosticsDemand: (
+ enabled: boolean,
+ ) => Effect.Effect<void, DesktopTelemetryControlError>;
+ }
+>()("t3/resourceTelemetry/DesktopTelemetryReceiver") {}
+
+const decodeMessage = Schema.decodeUnknownEffect(DesktopHostTelemetryMessage);
+const encodeControlMessage = Schema.encodeEffect(
+ Schema.fromJsonString(DesktopTelemetryControlMessage),
+);
+const isDescriptorUnavailable = Schema.is(DesktopTelemetryDescriptorUnavailable);
+const isProtocolMismatch = Schema.is(DesktopTelemetryProtocolMismatch);
+const isDecodeFailed = Schema.is(DesktopTelemetryDecodeFailed);
+const isStreamFailed = Schema.is(DesktopTelemetryStreamFailed);
+
+export function isDesktopTelemetryContactStale(
+ lastContactAtMs: Option.Option<number>,
+ nowMs: number,
+): boolean {
+ return Option.exists(
+ lastContactAtMs,
+ (lastContact) => nowMs - lastContact >= INITIAL_SAMPLE_DEADLINE_MS,
+ );
+}
+
+export function resolveDesktopTelemetrySnapshotStaleAfterMs(
+ activeIntervalMs: number,
+ idleIntervalMs: number,
+): number {
+ return Math.max(
+ MIN_SNAPSHOT_STALE_AFTER_MS,
+ Math.max(activeIntervalMs, idleIntervalMs) + STALE_GRACE_MS,
+ );
+}
+
+export function initialDesktopTelemetryContactAt(
+ desktopTelemetryFd: number | undefined,
+ nowMs: number,
+): Option.Option<number> {
+ return desktopTelemetryFd === undefined ? Option.none() : Option.some(nowMs);
+}
+
+export const recordDesktopTelemetrySampleHealth = Effect.fn(
+ "resourceTelemetry.desktopTelemetryReceiver.recordSampleHealth",
+)(function* (
+ health: Ref.Ref<DesktopTelemetryReceiverHealth>,
+ healthChanges: PubSub.PubSub<DesktopTelemetryReceiverHealth>,
+ sampledAt: DateTime.Utc,
+) {
+ const next: DesktopTelemetryReceiverHealth = {
+ status: "healthy",
+ lastSampleAt: Option.some(sampledAt),
+ lastError: Option.none(),
+ };
+ yield* Ref.set(health, next);
+ yield* PubSub.publish(healthChanges, next);
+});
+
+function normalizeReceiverError(error: unknown): DesktopTelemetryReceiverError {
+ if (
+ isDescriptorUnavailable(error) ||
+ isProtocolMismatch(error) ||
+ isDecodeFailed(error) ||
+ isStreamFailed(error)
+ ) {
+ return error;
+ }
+ return new DesktopTelemetryDecodeFailed({ cause: error });
+}
+
+function messageVersion(value: unknown): number | undefined {
+ if (typeof value !== "object" || value === null) return undefined;
+ const version = Reflect.get(value, "version");
+ return typeof version === "number" ? version : undefined;
+}
+
+export const writeAllToFileDescriptor = Effect.fn(
+ "resourceTelemetry.desktopTelemetryReceiver.writeAllToFileDescriptor",
+)(function* (fd: number, payload: Buffer) {
+ let offset = 0;
+ while (offset < payload.byteLength) {
+ const written = yield* Effect.callback<number, DesktopTelemetryControlFailed>(
+ (resume, signal) => {
+ if (signal.aborted) return;
+ try {
+ NodeFS.write(
+ fd,
+ payload,
+ offset,
+ payload.byteLength - offset,
+ null,
+ (error, bytesWritten) => {
+ if (error) {
+ resume(
+ Effect.fail(
+ new DesktopTelemetryControlFailed({
+ fd,
+ operation: "write",
+ cause: error,
+ }),
+ ),
+ );
+ return;
+ }
+ resume(Effect.succeed(bytesWritten));
+ },
+ );
+ } catch (cause) {
+ resume(
+ Effect.fail(
+ new DesktopTelemetryControlFailed({
+ fd,
+ operation: "write",
+ cause,
+ }),
+ ),
+ );
+ }
+ },
+ );
+ yield* requireDesktopTelemetryWriteProgress(fd, payload.byteLength - offset, written);
+ offset += written;
+ }
+});
+
+export function requireDesktopTelemetryWriteProgress(
+ fd: number,
+ remainingBytes: number,
+ written: number,
+): Effect.Effect<void, DesktopTelemetryControlStalled> {
+ return written > 0
+ ? Effect.void
+ : Effect.fail(new DesktopTelemetryControlStalled({ fd, remainingBytes }));
+}
+
+export const make = Effect.fn("resourceTelemetry.desktopTelemetryReceiver.make")(function* () {
+ const config = yield* ServerConfig;
+ const serverSettings = yield* ServerSettingsService;
+ const latest = yield* Ref.make(Option.none<DesktopHostTelemetrySnapshot>());
+ const receiverStartedAt = yield* DateTime.now;
+ const lastContactAtMs = yield* Ref.make(
+ initialDesktopTelemetryContactAt(
+ config.desktopTelemetryFd,
+ DateTime.toEpochMillis(receiverStartedAt),
+ ),
+ );
+ const snapshotStaleAfterMs = yield* Ref.make(
+ resolveDesktopTelemetrySnapshotStaleAfterMs(
+ DEFAULT_HOST_POWER_ACTIVE_INTERVAL_MS,
+ DEFAULT_HOST_POWER_IDLE_INTERVAL_MS,
+ ),
+ );
+ const changes = yield* PubSub.sliding<DesktopHostTelemetrySnapshot>(8);
+ const healthChanges = yield* PubSub.sliding<DesktopTelemetryReceiverHealth>(4);
+ const controlMutex = yield* Semaphore.make(1);
+ const snapshotMutex = yield* Semaphore.make(1);
+ const health = yield* Ref.make<DesktopTelemetryReceiverHealth>({
+ status: config.desktopTelemetryFd === undefined ? "unavailable" : "starting",
+ lastSampleAt: Option.none(),
+ lastError:
+ config.desktopTelemetryFd === undefined
+ ? Option.some(
+ new DesktopTelemetryDescriptorUnavailable({
+ mode: config.mode,
+ }).message,
+ )
+ : Option.none(),
+ });
+ const updateHealth = (
+ update: (current: DesktopTelemetryReceiverHealth) => DesktopTelemetryReceiverHealth,
+ ) =>
+ Ref.modify(health, (current) => {
+ const next = update(current);
+ return [next, next];
+ }).pipe(
+ Effect.flatMap((next) => PubSub.publish(healthChanges, next)),
+ Effect.asVoid,
+ );
+ const updateSampleHealth = (sampledAt: DateTime.Utc) =>
+ recordDesktopTelemetrySampleHealth(health, healthChanges, sampledAt);
+
+ const sendControlMessage = (message: DesktopTelemetryControlMessage) =>
+ controlMutex.withPermits(1)(
+ Effect.gen(function* () {
+ const fd = config.desktopTelemetryControlFd;
+ if (fd === undefined) return;
+ const encoded = yield* encodeControlMessage(message).pipe(
+ Effect.mapError(
+ (cause) =>
+ new DesktopTelemetryControlFailed({
+ fd,
+ operation: "encode",
+ cause,
+ }),
+ ),
+ );
+ yield* writeAllToFileDescriptor(fd, Buffer.from(`${encoded}\n`)).pipe(
+ Effect.tapError((error) =>
+ updateHealth((current) => ({
+ ...current,
+ status: "degraded",
+ lastError: Option.some(error.message),
+ })),
+ ),
+ );
+ }),
+ );
+ const setDiagnosticsDemand: DesktopTelemetryReceiver["Service"]["setDiagnosticsDemand"] = (
+ enabled,
+ ) =>
+ sendControlMessage({
+ version: 1,
+ type: "setDiagnosticsDemand",
+ enabled,
+ });
+
+ const sendHostPowerIntervals = (
+ settings: Parameters<typeof resolveServerBackgroundActivitySettings>[0],
+ ) => {
+ const resolved = resolveServerBackgroundActivitySettings(settings);
+ const activeIntervalMs = Math.max(
+ 1,
+ Math.round(Duration.toMillis(resolved.hostPowerMonitorActiveInterval)),
+ );
+ const idleIntervalMs = Math.max(
+ 1,
+ Math.round(Duration.toMillis(resolved.hostPowerMonitorIdleInterval)),
+ );
+ return sendControlMessage({
+ version: 1,
+ type: "setHostPowerIntervals",
+ activeIntervalMs,
+ idleIntervalMs,
+ }).pipe(
+ Effect.andThen(
+ Ref.set(
+ snapshotStaleAfterMs,
+ resolveDesktopTelemetrySnapshotStaleAfterMs(activeIntervalMs, idleIntervalMs),
+ ),
+ ),
+ );
+ };
+ if (config.desktopTelemetryControlFd !== undefined) {
+ const settingsChanges = yield* serverSettings.subscribeChanges;
+ const settings = yield* serverSettings.getSettings;
+ yield* sendHostPowerIntervals(settings).pipe(
+ Effect.catchCause((cause) =>
+ Effect.logWarning("Failed to configure desktop host-power intervals", {
+ cause: String(cause),
+ }),
+ ),
+ );
+ yield* settingsChanges.pipe(
+ Stream.runForEach((settings) =>
+ sendHostPowerIntervals(settings).pipe(
+ Effect.catchCause((cause) =>
+ Effect.logWarning("Failed to update desktop host-power intervals", {
+ cause: String(cause),
+ }),
+ ),
+ ),
+ ),
+ Effect.forkScoped,
+ );
+ }
+
+ if (config.desktopTelemetryFd !== undefined) {
+ const fd = config.desktopTelemetryFd;
+ const readable = yield* Effect.acquireRelease(
+ Effect.try({
+ try: () =>
+ NodeFS.createReadStream("", {
+ fd,
+ autoClose: true,
+ }),
+ catch: (cause) => new DesktopTelemetryStreamFailed({ fd, cause }),
+ }),
+ (stream) =>
+ Effect.sync(() => {
+ stream.destroy();
+ }),
+ );
+
+ const messages: Stream.Stream<DesktopHostTelemetryMessageValue, DesktopTelemetryReceiverError> =
+ NodeStream.fromReadable<Uint8Array, DesktopTelemetryStreamFailed>({
+ evaluate: () => readable,
+ closeOnDone: true,
+ onError: (cause) => new DesktopTelemetryStreamFailed({ fd, cause }),
+ }).pipe(
+ Stream.pipeThroughChannel(Ndjson.decode({ ignoreEmptyLines: true })),
+ Stream.mapEffect(
+ (
+ value,
+ ): Effect.Effect<
+ DesktopHostTelemetryMessageValue,
+ DesktopTelemetryProtocolMismatch | DesktopTelemetryDecodeFailed
+ > => {
+ const version = messageVersion(value);
+ if (version !== undefined && version !== 1) {
+ return Effect.fail(
+ new DesktopTelemetryProtocolMismatch({
+ expectedVersion: 1,
+ receivedVersion: version,
+ }),
+ );
+ }
+ return decodeMessage(value).pipe(
+ Effect.mapError((cause) => new DesktopTelemetryDecodeFailed({ cause })),
+ );
+ },
+ ),
+ Stream.mapError(normalizeReceiverError),
+ );
+
+ yield* messages.pipe(
+ Stream.runForEach((message) => {
+ const recordContact = DateTime.now.pipe(
+ Effect.flatMap((now) =>
+ Ref.set(lastContactAtMs, Option.some(DateTime.toEpochMillis(now))),
+ ),
+ );
+ if (message.type === "desktopTelemetryHello") {
+ return recordContact.pipe(
+ Effect.andThen(
+ updateHealth(
+ (current): DesktopTelemetryReceiverHealth => ({
+ ...current,
+ status: "healthy",
+ lastError: Option.none(),
+ }),
+ ),
+ ),
+ );
+ }
+
+ const sampledAt = DateTime.makeUnsafe(message.sampledAtUnixMs);
+ return snapshotMutex.withPermits(1)(
+ recordContact.pipe(
+ Effect.andThen(Ref.set(latest, Option.some(message))),
+ Effect.andThen(updateSampleHealth(sampledAt)),
+ Effect.andThen(PubSub.publish(changes, message)),
+ Effect.asVoid,
+ ),
+ );
+ }),
+ Effect.andThen(
+ updateHealth(
+ (current): DesktopTelemetryReceiverHealth => ({
+ ...current,
+ status: "stopped",
+ lastError: Option.some(new DesktopTelemetryStreamClosed({ fd }).message),
+ }),
+ ),
+ ),
+ Effect.catch((error) =>
+ updateHealth(
+ (current): DesktopTelemetryReceiverHealth => ({
+ ...current,
+ status: "degraded",
+ lastError: Option.some(error.message),
+ }),
+ ),
+ ),
+ Effect.forkScoped,
+ );
+
+ yield* Effect.forever(
+ Effect.sleep(STALE_CHECK_INTERVAL).pipe(
+ Effect.andThen(
+ snapshotMutex.withPermits(1)(
+ Effect.gen(function* () {
+ const now = yield* DateTime.now;
+ const nowMs = DateTime.toEpochMillis(now);
+ const staleAfterMs = yield* Ref.get(snapshotStaleAfterMs);
+ const staleSnapshot = yield* Ref.modify(latest, (current) => {
+ if (
+ Option.isNone(current) ||
+ current.value.power.stale ||
+ nowMs - current.value.sampledAtUnixMs < staleAfterMs
+ ) {
+ return [Option.none<DesktopHostTelemetrySnapshot>(), current] as const;
+ }
+ const stale: DesktopHostTelemetrySnapshot = {
+ ...current.value,
+ power: { ...current.value.power, stale: true },
+ };
+ return [Option.some(stale), Option.some(stale)] as const;
+ });
+ if (Option.isNone(staleSnapshot)) {
+ const lastContact = yield* Ref.get(lastContactAtMs);
+ if (!isDesktopTelemetryContactStale(lastContact, nowMs)) return;
+ const staleMessage = new DesktopTelemetryStale({
+ fd,
+ staleAfterMs: INITIAL_SAMPLE_DEADLINE_MS,
+ }).message;
+ const changed = yield* Ref.modify(health, (current) => {
+ if (
+ current.status === "stopped" ||
+ Option.isSome(current.lastSampleAt) ||
+ (current.status === "degraded" &&
+ Option.contains(current.lastError, staleMessage))
+ ) {
+ return [Option.none<DesktopTelemetryReceiverHealth>(), current] as const;
+ }
+ const next: DesktopTelemetryReceiverHealth = {
+ ...current,
+ status: "degraded",
+ lastError: Option.some(staleMessage),
+ };
+ return [Option.some(next), next] as const;
+ });
+ if (Option.isSome(changed)) {
+ yield* PubSub.publish(healthChanges, changed.value);
+ }
+ return;
+ }
+ yield* updateHealth((currentHealth) => ({
+ ...currentHealth,
+ status: currentHealth.status === "stopped" ? "stopped" : "degraded",
+ lastError:
+ currentHealth.status === "stopped"
+ ? currentHealth.lastError
+ : Option.some(new DesktopTelemetryStale({ fd, staleAfterMs }).message),
+ }));
+ yield* PubSub.publish(changes, staleSnapshot.value);
+ }),
+ ),
+ ),
+ ),
+ ).pipe(Effect.forkScoped);
+ }
+
+ return DesktopTelemetryReceiver.of({
+ latest: Ref.get(latest),
+ changes: Stream.fromPubSub(changes),
+ subscribe: snapshotMutex.withPermits(1)(
+ Effect.gen(function* () {
+ const initial = yield* Ref.get(latest);
+ const subscription = yield* PubSub.subscribe(changes);
+ return {
+ latest: initial,
+ changes: Stream.fromSubscription(subscription),
+ };
+ }),
+ ),
+ health: Ref.get(health),
+ subscribeHealth: subscribeBeforeSnapshotWithoutMutex(healthChanges, Ref.get(health)),
+ setDiagnosticsDemand,
+ });
+});
+
+export const layer = Layer.effect(DesktopTelemetryReceiver, make());
+
+export const layerTest = (
+ overrides: Partial<DesktopTelemetryReceiver["Service"]> = {},
+): Layer.Layer<DesktopTelemetryReceiver> => {
+ const latest = overrides.latest ?? Effect.succeedNone;
+ const changes = overrides.changes ?? Stream.empty;
+ const health =
+ overrides.health ??
+ Effect.succeed({
+ status: "unavailable" as const,
+ lastSampleAt: Option.none<DateTime.Utc>(),
+ lastError: Option.some("Desktop telemetry test implementation is unavailable."),
+ });
+ return Layer.succeed(
+ DesktopTelemetryReceiver,
+ DesktopTelemetryReceiver.of({
+ latest,
+ changes,
+ subscribe:
+ overrides.subscribe ??
+ latest.pipe(
+ Effect.map((initial) => ({
+ latest: initial,
+ changes,
+ })),
+ ),
+ health,
+ subscribeHealth:
+ overrides.subscribeHealth ??
+ health.pipe(
+ Effect.map((initial) => ({
+ latest: initial,
+ changes: Stream.empty,
+ })),
+ ),
+ setDiagnosticsDemand: () => Effect.void,
+ ...overrides,
+ }),
+ );
+};
diff --git a/apps/server/src/resourceTelemetry/Model.test.ts b/apps/server/src/resourceTelemetry/Model.test.ts
new file mode 100644
index 000000000..94690e396
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/Model.test.ts
@@ -0,0 +1,581 @@
+import {
+ type DesktopElectronProcessMetric,
+ type DesktopHostTelemetrySnapshot,
+ type ResourceMonitorProcessSample,
+ type ResourceMonitorSnapshotEvent,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+
+import { emptyTelemetryCounters, mergeProcesses, type MergeProcessesResult } from "./Model.ts";
+
+const SERVER_PID = 100;
+const BASE_TIME_MS = DateTime.toEpochMillis(DateTime.makeUnsafe("2026-06-17T12:00:00.000Z"));
+
+function processSample(
+ input: Partial<ResourceMonitorProcessSample> &
+ Pick<ResourceMonitorProcessSample, "pid" | "ppid" | "startTimeMs">,
+): ResourceMonitorProcessSample {
+ return {
+ runTimeMs: 1_000,
+ name: `process-${input.pid}`,
+ command: `process-${input.pid}`,
+ status: "Running",
+ cpuPercent: 0,
+ cpuTimeMs: 0,
+ residentBytes: 1_024,
+ virtualBytes: 2_048,
+ ioReadBytes: 0,
+ ioWriteBytes: 0,
+ ioSemantics: "storage",
+ ...input,
+ };
+}
+
+function nativeSnapshot(
+ sampledAtUnixMs: number,
+ processes: ReadonlyArray<ResourceMonitorProcessSample>,
+ sequence = 1,
+): ResourceMonitorSnapshotEvent {
+ return {
+ version: 2,
+ type: "snapshot",
+ sequence,
+ sampledAtUnixMs,
+ collectionDurationMicros: 250,
+ scannedProcessCount: processes.length,
+ retainedProcessCount: processes.length,
+ inaccessibleProcessCount: 0,
+ processes: [...processes],
+ };
+}
+
+function electronMetric(
+ input: Partial<DesktopElectronProcessMetric> &
+ Pick<DesktopElectronProcessMetric, "pid" | "creationTimeMs" | "type">,
+): DesktopElectronProcessMetric {
+ return {
+ cpuPercent: 0,
+ idleWakeupsPerSecond: 0,
+ workingSetBytes: 1_024,
+ peakWorkingSetBytes: 2_048,
+ ...input,
+ };
+}
+
+function desktopSnapshot(
+ sampledAtUnixMs: number,
+ electronProcesses: ReadonlyArray<DesktopElectronProcessMetric>,
+): DesktopHostTelemetrySnapshot {
+ const sampledAt = DateTime.makeUnsafe(sampledAtUnixMs);
+ return {
+ version: 1,
+ type: "desktopTelemetry",
+ sequence: 1,
+ sampledAtUnixMs,
+ electronPid: electronProcesses[0]?.pid ?? 10_000,
+ power: {
+ source: "electron-main",
+ idle: "false",
+ idleSeconds: 0,
+ locked: "false",
+ suspended: false,
+ onBattery: "false",
+ lowPowerMode: "unknown",
+ thermalState: "nominal",
+ stale: false,
+ updatedAt: sampledAt,
+ },
+ speedLimitPercent: Option.none(),
+ electronProcesses: [...electronProcesses],
+ };
+}
+
+function merge(input: {
+ readonly native: ResourceMonitorSnapshotEvent;
+ readonly desktop?: DesktopHostTelemetrySnapshot;
+ readonly previous?: MergeProcessesResult;
+ readonly sidecarPid?: number;
+}): MergeProcessesResult {
+ return mergeProcesses({
+ serverPid: SERVER_PID,
+ sidecarPid: Option.fromUndefinedOr(input.sidecarPid),
+ fallbackSampledAtMs: input.native.sampledAtUnixMs,
+ nativeSnapshot: Option.some(input.native),
+ desktopSnapshot: Option.fromUndefinedOr(input.desktop),
+ previous: input.previous?.previous ?? new Map(),
+ counters: input.previous?.counters ?? emptyTelemetryCounters(),
+ updatePrevious: true,
+ });
+}
+
+describe("resource telemetry process model", () => {
+ it("builds complete descendant depths and isolates monitor overhead", () => {
+ const result = merge({
+ sidecarPid: 900,
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 }),
+ processSample({ pid: 200, ppid: SERVER_PID, startTimeMs: 2_000 }),
+ processSample({ pid: 201, ppid: 200, startTimeMs: 3_000 }),
+ processSample({ pid: 202, ppid: 201, startTimeMs: 4_000 }),
+ processSample({ pid: 900, ppid: SERVER_PID, startTimeMs: 5_000 }),
+ ]),
+ });
+
+ expect(result.processes.map((process) => [process.identity.pid, process.depth])).toEqual([
+ [100, 0],
+ [200, 1],
+ [201, 2],
+ [202, 3],
+ [900, 1],
+ ]);
+ expect(result.processes.find((process) => process.identity.pid === 900)?.category).toBe(
+ "resource-monitor",
+ );
+ expect(result.groups.backend.processCount).toBe(4);
+ expect(result.groups.monitor.processCount).toBe(1);
+ expect(result.groups.monitor.processStarts).toBe(1);
+ expect(result.groups.allT3.processStarts).toBe(5);
+ });
+
+ it("deduplicates Electron metrics and classifies Electron descendants", () => {
+ const electronStart = 10_000;
+ const result = merge({
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 }),
+ processSample({ pid: 300, ppid: 1, startTimeMs: electronStart }),
+ processSample({ pid: 301, ppid: 300, startTimeMs: electronStart + 1 }),
+ ]),
+ desktop: desktopSnapshot(BASE_TIME_MS, [
+ electronMetric({
+ pid: 300,
+ creationTimeMs: electronStart + 500,
+ type: "Browser",
+ name: "electron",
+ }),
+ electronMetric({
+ pid: 301,
+ creationTimeMs: electronStart + 500,
+ type: "Utility",
+ name: "network-service",
+ }),
+ ]),
+ });
+
+ expect(result.processes.filter((process) => process.identity.pid === 300)).toHaveLength(1);
+ expect(result.processes.find((process) => process.identity.pid === 300)?.category).toBe(
+ "electron-main",
+ );
+ expect(result.processes.find((process) => process.identity.pid === 301)?.category).toBe(
+ "electron-utility",
+ );
+ expect(result.processes.find((process) => process.identity.pid === 301)?.depth).toBe(1);
+ expect(result.groups.electron.processCount).toBe(2);
+ });
+
+ it("ignores stale Electron metrics after PID reuse", () => {
+ const result = merge({
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 }),
+ processSample({ pid: 300, ppid: SERVER_PID, startTimeMs: 50_000 }),
+ ]),
+ desktop: desktopSnapshot(BASE_TIME_MS, [
+ electronMetric({
+ pid: 300,
+ creationTimeMs: 10_000,
+ type: "Browser",
+ }),
+ ]),
+ });
+
+ expect(result.processes.find((process) => process.identity.pid === 300)?.category).toBe(
+ "server-child",
+ );
+ expect(result.groups.electron.processCount).toBe(0);
+ });
+
+ it("derives cumulative CPU time for synthetic Electron-only processes", () => {
+ const first = merge({
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 }),
+ ]),
+ desktop: desktopSnapshot(BASE_TIME_MS, [
+ electronMetric({
+ pid: 300,
+ creationTimeMs: 10_000,
+ type: "Browser",
+ cpuPercent: 50,
+ }),
+ ]),
+ });
+ const second = merge({
+ previous: first,
+ native: nativeSnapshot(
+ BASE_TIME_MS + 1_000,
+ [processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 })],
+ 2,
+ ),
+ desktop: desktopSnapshot(BASE_TIME_MS + 1_000, [
+ electronMetric({
+ pid: 300,
+ creationTimeMs: 10_000,
+ type: "Browser",
+ cpuPercent: 50,
+ }),
+ ]),
+ });
+
+ expect(second.processes.find((process) => process.identity.pid === 300)?.cpuTimeMs).toBe(500);
+ expect(second.groups.electron.cpuTimeMs).toBe(500);
+ });
+
+ it("uses the native timestamp for native cumulative-counter deltas", () => {
+ const first = merge({
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 1_000,
+ }),
+ ]),
+ desktop: desktopSnapshot(BASE_TIME_MS + 10_000, []),
+ });
+ const second = merge({
+ previous: first,
+ native: nativeSnapshot(
+ BASE_TIME_MS + 1_000,
+ [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 1_500,
+ }),
+ ],
+ 2,
+ ),
+ desktop: desktopSnapshot(BASE_TIME_MS + 11_000, []),
+ });
+
+ expect(second.processes[0]?.cpuPercent).toBe(50);
+ expect(second.groups.backend.cpuTimeMs).toBe(500);
+ });
+
+ it("does not advance synthetic CPU time when reusing the same desktop sample", () => {
+ const metric = electronMetric({
+ pid: 300,
+ creationTimeMs: 10_000,
+ type: "Browser",
+ cpuPercent: 50,
+ });
+ const first = merge({
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 }),
+ ]),
+ desktop: desktopSnapshot(BASE_TIME_MS, [metric]),
+ });
+ const second = merge({
+ previous: first,
+ native: nativeSnapshot(
+ BASE_TIME_MS + 1_000,
+ [processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 })],
+ 2,
+ ),
+ desktop: desktopSnapshot(BASE_TIME_MS, [metric]),
+ });
+
+ expect(second.processes.find((process) => process.identity.pid === 300)?.cpuTimeMs).toBe(0);
+ expect(second.groups.electron.cpuTimeMs).toBe(0);
+ });
+
+ it("does not apply an explicit Electron root to a reused PID", () => {
+ const first = mergeProcesses({
+ serverPid: SERVER_PID,
+ sidecarPid: Option.none(),
+ electronRootPids: new Set([300]),
+ fallbackSampledAtMs: BASE_TIME_MS,
+ nativeSnapshot: Option.some(
+ nativeSnapshot(BASE_TIME_MS, [
+ processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 }),
+ processSample({ pid: 300, ppid: 1, startTimeMs: 10_000 }),
+ ]),
+ ),
+ desktopSnapshot: Option.some(
+ desktopSnapshot(BASE_TIME_MS, [
+ electronMetric({
+ pid: 300,
+ creationTimeMs: 10_000,
+ type: "Browser",
+ }),
+ ]),
+ ),
+ previous: new Map(),
+ counters: emptyTelemetryCounters(),
+ updatePrevious: true,
+ });
+ const reused = mergeProcesses({
+ serverPid: SERVER_PID,
+ sidecarPid: Option.none(),
+ electronRootPids: new Set([300]),
+ fallbackSampledAtMs: BASE_TIME_MS + 1_000,
+ nativeSnapshot: Option.some(
+ nativeSnapshot(
+ BASE_TIME_MS + 1_000,
+ [
+ processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 }),
+ processSample({ pid: 300, ppid: SERVER_PID, startTimeMs: 20_000 }),
+ ],
+ 2,
+ ),
+ ),
+ desktopSnapshot: Option.none(),
+ previous: first.previous,
+ counters: first.counters,
+ updatePrevious: true,
+ });
+
+ expect(reused.processes.find((process) => process.identity.pid === 300)?.category).toBe(
+ "server-child",
+ );
+ expect(reused.groups.electron.processCount).toBe(0);
+ });
+
+ it("derives rates from cumulative counters and preserves I/O semantics", () => {
+ const first = merge({
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 1_000,
+ ioReadBytes: 10_000,
+ ioWriteBytes: 20_000,
+ ioSemantics: "all-io",
+ }),
+ ]),
+ });
+ const second = merge({
+ previous: first,
+ native: nativeSnapshot(
+ BASE_TIME_MS + 1_000,
+ [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 1_250,
+ ioReadBytes: 12_000,
+ ioWriteBytes: 23_000,
+ ioSemantics: "all-io",
+ }),
+ ],
+ 2,
+ ),
+ });
+ const server = second.processes[0]!;
+
+ expect(server.cpuPercent).toBe(25);
+ expect(server.ioReadBytesPerSecond).toBe(2_000);
+ expect(server.ioWriteBytesPerSecond).toBe(3_000);
+ expect(server.ioSemantics).toBe("all-io");
+ expect(second.groups.backend.cpuTimeMs).toBe(250);
+ expect(second.groups.backend.ioReadBytes).toBe(2_000);
+ expect(second.groups.backend.ioWriteBytes).toBe(3_000);
+ });
+
+ it("derives deltas at the constrained 15-second sampling cadence", () => {
+ const first = merge({
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 1_000,
+ ioReadBytes: 10_000,
+ ioWriteBytes: 20_000,
+ }),
+ ]),
+ });
+ const second = merge({
+ previous: first,
+ native: nativeSnapshot(
+ BASE_TIME_MS + 15_000,
+ [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 2_500,
+ ioReadBytes: 25_000,
+ ioWriteBytes: 50_000,
+ }),
+ ],
+ 2,
+ ),
+ });
+
+ expect(second.processes[0]?.cpuPercent).toBe(10);
+ expect(second.processes[0]?.ioReadBytesPerSecond).toBe(1_000);
+ expect(second.processes[0]?.ioWriteBytesPerSecond).toBe(2_000);
+ expect(second.groups.backend.cpuTimeMs).toBe(1_500);
+ expect(second.groups.backend.ioReadBytes).toBe(15_000);
+ expect(second.groups.backend.ioWriteBytes).toBe(30_000);
+ });
+
+ it("preserves native rates while applying a desktop-only update", () => {
+ const first = merge({
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 1_000,
+ ioReadBytes: 10_000,
+ ioWriteBytes: 20_000,
+ }),
+ ]),
+ });
+ const second = merge({
+ previous: first,
+ native: nativeSnapshot(
+ BASE_TIME_MS + 1_000,
+ [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 1_250,
+ ioReadBytes: 12_000,
+ ioWriteBytes: 23_000,
+ }),
+ ],
+ 2,
+ ),
+ });
+ const desktopOnly = mergeProcesses({
+ serverPid: SERVER_PID,
+ sidecarPid: Option.none(),
+ fallbackSampledAtMs: BASE_TIME_MS + 1_000,
+ nativeSnapshot: Option.some(
+ nativeSnapshot(
+ BASE_TIME_MS + 1_000,
+ [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 1_250,
+ ioReadBytes: 12_000,
+ ioWriteBytes: 23_000,
+ }),
+ ],
+ 2,
+ ),
+ ),
+ desktopSnapshot: Option.some(desktopSnapshot(BASE_TIME_MS + 1_500, [])),
+ previous: second.previous,
+ counters: second.counters,
+ updatePrevious: false,
+ });
+
+ expect(desktopOnly.processes[0]?.cpuPercent).toBe(25);
+ expect(desktopOnly.processes[0]?.ioReadBytesPerSecond).toBe(2_000);
+ expect(desktopOnly.processes[0]?.ioWriteBytesPerSecond).toBe(3_000);
+ expect(desktopOnly.sampledAtMs).toBe(BASE_TIME_MS + 1_500);
+ });
+
+ it("resets deltas when counters decrease or the sampling gap is unsafe", () => {
+ const first = merge({
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 1_000,
+ ioReadBytes: 10_000,
+ ioWriteBytes: 20_000,
+ }),
+ ]),
+ });
+ const decreased = merge({
+ previous: first,
+ native: nativeSnapshot(
+ BASE_TIME_MS + 1_000,
+ [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 100,
+ ioReadBytes: 100,
+ ioWriteBytes: 200,
+ }),
+ ],
+ 2,
+ ),
+ });
+ const delayed = merge({
+ previous: decreased,
+ native: nativeSnapshot(
+ BASE_TIME_MS + 90_000,
+ [
+ processSample({
+ pid: SERVER_PID,
+ ppid: 1,
+ startTimeMs: 1_000,
+ cpuTimeMs: 10_000,
+ ioReadBytes: 100_000,
+ ioWriteBytes: 200_000,
+ }),
+ ],
+ 3,
+ ),
+ });
+
+ expect(decreased.processes[0]?.cpuPercent).toBe(0);
+ expect(decreased.processes[0]?.ioReadBytesPerSecond).toBe(0);
+ expect(decreased.processes[0]?.ioWriteBytesPerSecond).toBe(0);
+ expect(delayed.processes[0]?.cpuPercent).toBe(0);
+ expect(delayed.processes[0]?.ioReadBytesPerSecond).toBe(0);
+ expect(delayed.processes[0]?.ioWriteBytesPerSecond).toBe(0);
+ expect(delayed.groups.backend.cpuTimeMs).toBe(0);
+ expect(delayed.groups.backend.ioReadBytes).toBe(0);
+ expect(delayed.groups.backend.ioWriteBytes).toBe(0);
+ });
+
+ it("treats reused PIDs as an exit plus a new process", () => {
+ const first = merge({
+ native: nativeSnapshot(BASE_TIME_MS, [
+ processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 }),
+ processSample({ pid: 200, ppid: SERVER_PID, startTimeMs: 2_000 }),
+ ]),
+ });
+ const second = merge({
+ previous: first,
+ native: nativeSnapshot(
+ BASE_TIME_MS + 1_000,
+ [
+ processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 1_000 }),
+ processSample({
+ pid: 200,
+ ppid: SERVER_PID,
+ startTimeMs: 9_000,
+ cpuTimeMs: 999,
+ ioReadBytes: 999,
+ ioWriteBytes: 999,
+ }),
+ ],
+ 2,
+ ),
+ });
+ const reused = second.processes.find((process) => process.identity.pid === 200)!;
+
+ expect(reused.identity.startTimeMs).toBe(9_000);
+ expect(reused.cpuPercent).toBe(0);
+ expect(reused.ioReadBytesPerSecond).toBe(0);
+ expect(second.groups.backend.processStarts).toBe(3);
+ expect(second.groups.backend.processExits).toBe(1);
+ });
+});
diff --git a/apps/server/src/resourceTelemetry/Model.ts b/apps/server/src/resourceTelemetry/Model.ts
new file mode 100644
index 000000000..a198c4b31
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/Model.ts
@@ -0,0 +1,608 @@
+import type {
+ DesktopElectronProcessMetric,
+ DesktopHostTelemetrySnapshot,
+ ResourceMonitorProcessSample,
+ ResourceMonitorSnapshotEvent,
+ ResourceTelemetryAggregate,
+ ResourceTelemetryProcess,
+ ResourceTelemetryProcessCategory,
+} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+
+const MAX_DELTA_INTERVAL_MS = 30_000;
+const ELECTRON_IDENTITY_TOLERANCE_MS = 2_000;
+
+export interface ProcessState {
+ readonly process: ResourceTelemetryProcess;
+ readonly sampledAtMs: number;
+}
+
+export interface GroupCounters {
+ readonly cpuTimeMs: number;
+ readonly ioReadBytes: number;
+ readonly ioWriteBytes: number;
+ readonly processStarts: number;
+ readonly processExits: number;
+}
+
+export interface TelemetryCounters {
+ readonly backend: GroupCounters;
+ readonly electron: GroupCounters;
+ readonly monitor: GroupCounters;
+ readonly allT3: GroupCounters;
+}
+
+export interface ProcessDelta {
+ readonly identityKey: string;
+ readonly category: ResourceTelemetryProcessCategory;
+ readonly cpuTimeMs: number;
+ readonly ioReadBytes: number;
+ readonly ioWriteBytes: number;
+}
+
+export interface MergeProcessesInput {
+ readonly serverPid: number;
+ readonly sidecarPid: Option.Option<number>;
+ readonly fallbackSampledAtMs: number;
+ readonly nativeSnapshot: Option.Option<ResourceMonitorSnapshotEvent>;
+ readonly desktopSnapshot: Option.Option<DesktopHostTelemetrySnapshot>;
+ readonly electronRootPids?: ReadonlySet<number>;
+ readonly electronRootStartTimes?: ReadonlyMap<number, number>;
+ readonly previous: ReadonlyMap<string, ProcessState>;
+ readonly counters: TelemetryCounters;
+ readonly updatePrevious: boolean;
+}
+
+export interface MergeProcessesResult {
+ readonly sampledAtMs: number;
+ readonly processes: ReadonlyArray<ResourceTelemetryProcess>;
+ readonly previous: ReadonlyMap<string, ProcessState>;
+ readonly counters: TelemetryCounters;
+ readonly groups: {
+ readonly backend: ResourceTelemetryAggregate;
+ readonly electron: ResourceTelemetryAggregate;
+ readonly monitor: ResourceTelemetryAggregate;
+ readonly allT3: ResourceTelemetryAggregate;
+ };
+ readonly deltas: ReadonlyArray<ProcessDelta>;
+}
+
+export const emptyGroupCounters = (): GroupCounters => ({
+ cpuTimeMs: 0,
+ ioReadBytes: 0,
+ ioWriteBytes: 0,
+ processStarts: 0,
+ processExits: 0,
+});
+
+export const emptyTelemetryCounters = (): TelemetryCounters => ({
+ backend: emptyGroupCounters(),
+ electron: emptyGroupCounters(),
+ monitor: emptyGroupCounters(),
+ allT3: emptyGroupCounters(),
+});
+
+export function processIdentityKey(pid: number, startTimeMs: number): string {
+ return `${pid}:${startTimeMs}`;
+}
+
+function finiteNonNegative(value: number): number {
+ return Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+function categoryGroup(
+ category: ResourceTelemetryProcessCategory,
+): "backend" | "electron" | "monitor" {
+ if (category === "resource-monitor") return "monitor";
+ if (category.startsWith("electron-")) return "electron";
+ return "backend";
+}
+
+function electronCategory(metric: DesktopElectronProcessMetric): ResourceTelemetryProcessCategory {
+ switch (metric.type) {
+ case "Browser":
+ return "electron-main";
+ case "Tab":
+ return "electron-renderer";
+ case "GPU":
+ return "electron-gpu";
+ default:
+ return "electron-utility";
+ }
+}
+
+function inferredElectronCategory(
+ process: ResourceMonitorProcessSample,
+): ResourceTelemetryProcessCategory {
+ const command = process.command.toLowerCase();
+ if (command.includes("--type=renderer")) return "electron-renderer";
+ if (command.includes("--type=gpu-process")) return "electron-gpu";
+ return "electron-utility";
+}
+
+function matchElectronMetric(
+ process: ResourceMonitorProcessSample,
+ metricsByPid: ReadonlyMap<number, DesktopElectronProcessMetric>,
+): DesktopElectronProcessMetric | undefined {
+ const metric = metricsByPid.get(process.pid);
+ if (!metric) return undefined;
+ return Math.abs(metric.creationTimeMs - process.startTimeMs) <= ELECTRON_IDENTITY_TOLERANCE_MS
+ ? metric
+ : undefined;
+}
+
+function syntheticNativeSample(
+ metric: DesktopElectronProcessMetric,
+ sampledAtMs: number,
+ previous: ProcessState | undefined,
+): ResourceMonitorProcessSample {
+ const cpuTimeMs =
+ metric.cumulativeCpuSeconds !== undefined
+ ? Math.max(0, Math.round(metric.cumulativeCpuSeconds * 1_000))
+ : previous
+ ? previous.process.cpuTimeMs +
+ Math.max(0, ((sampledAtMs - previous.sampledAtMs) * metric.cpuPercent) / 100)
+ : 0;
+ return {
+ pid: metric.pid,
+ ppid: 0,
+ startTimeMs: metric.creationTimeMs,
+ runTimeMs: Math.max(0, sampledAtMs - metric.creationTimeMs),
+ name: metric.name ?? metric.serviceName ?? metric.type,
+ command: metric.name ?? metric.serviceName ?? metric.type,
+ status: "Running",
+ cpuPercent: metric.cpuPercent,
+ cpuTimeMs,
+ residentBytes: metric.workingSetBytes,
+ virtualBytes: 0,
+ ioReadBytes: 0,
+ ioWriteBytes: 0,
+ ioSemantics: "storage",
+ };
+}
+
+function processDepths(
+ processes: ReadonlyArray<ResourceMonitorProcessSample>,
+ roots: ReadonlySet<number>,
+): ReadonlyMap<number, number> {
+ const childrenByParent = new Map<number, number[]>();
+ for (const process of processes) {
+ const children = childrenByParent.get(process.ppid) ?? [];
+ children.push(process.pid);
+ childrenByParent.set(process.ppid, children);
+ }
+
+ const depths = new Map<number, number>();
+ const queue = [...roots].map((pid) => ({ pid, 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;
+}
+
+function isElectronDescendant(
+ pid: number,
+ processesByPid: ReadonlyMap<number, ResourceMonitorProcessSample>,
+ electronPids: ReadonlySet<number>,
+): boolean {
+ const visited = new Set<number>();
+ let currentPid = pid;
+ while (!visited.has(currentPid)) {
+ visited.add(currentPid);
+ if (electronPids.has(currentPid)) return true;
+ const current = processesByPid.get(currentPid);
+ if (!current || current.ppid <= 0 || current.ppid === currentPid) return false;
+ currentPid = current.ppid;
+ }
+ return false;
+}
+
+function hasElectronAncestor(
+ process: ResourceMonitorProcessSample,
+ processesByPid: ReadonlyMap<number, ResourceMonitorProcessSample>,
+ electronPids: ReadonlySet<number>,
+): boolean {
+ const visited = new Set<number>();
+ let currentPid = process.ppid;
+ while (currentPid > 0 && !visited.has(currentPid)) {
+ visited.add(currentPid);
+ if (electronPids.has(currentPid)) return true;
+ const current = processesByPid.get(currentPid);
+ if (!current || current.ppid === currentPid) return false;
+ currentPid = current.ppid;
+ }
+ return false;
+}
+
+function orderProcessTree(
+ processes: ReadonlyArray<ResourceTelemetryProcess>,
+ rootPids: ReadonlyArray<number>,
+): ReadonlyArray<ResourceTelemetryProcess> {
+ const processesByPid = new Map(processes.map((process) => [process.identity.pid, process]));
+ const childrenByParent = new Map<number, ResourceTelemetryProcess[]>();
+ 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: ResourceTelemetryProcess[] = [];
+ const visited = new Set<number>();
+ const visit = (process: ResourceTelemetryProcess): void => {
+ 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;
+}
+
+function delta(input: {
+ readonly current: number;
+ readonly previous: number;
+ readonly elapsedMs: number;
+}): number {
+ if (
+ input.elapsedMs <= 0 ||
+ input.elapsedMs > MAX_DELTA_INTERVAL_MS ||
+ input.current < input.previous
+ ) {
+ return 0;
+ }
+ return input.current - input.previous;
+}
+
+function incrementCounters(counters: GroupCounters, update: Partial<GroupCounters>): GroupCounters {
+ return {
+ 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),
+ };
+}
+
+function applyLifecycleCounters(input: {
+ readonly counters: TelemetryCounters;
+ readonly deltas: ReadonlyArray<ProcessDelta>;
+ readonly current: ReadonlyMap<string, ProcessState>;
+ readonly previous: ReadonlyMap<string, ProcessState>;
+}): TelemetryCounters {
+ let backend = input.counters.backend;
+ let electron = input.counters.electron;
+ let monitor = input.counters.monitor;
+ let allT3 = input.counters.allT3;
+ for (const processDelta of input.deltas) {
+ const group = categoryGroup(processDelta.category);
+ switch (group) {
+ case "backend":
+ backend = incrementCounters(backend, processDelta);
+ break;
+ case "electron":
+ electron = incrementCounters(electron, processDelta);
+ break;
+ case "monitor":
+ monitor = incrementCounters(monitor, processDelta);
+ break;
+ }
+ allT3 = incrementCounters(allT3, processDelta);
+ }
+
+ for (const [identityKey, current] of input.current) {
+ if (input.previous.has(identityKey)) continue;
+ const group = categoryGroup(current.process.category);
+ switch (group) {
+ case "backend":
+ backend = incrementCounters(backend, { processStarts: 1 });
+ break;
+ case "electron":
+ electron = incrementCounters(electron, { processStarts: 1 });
+ break;
+ case "monitor":
+ monitor = incrementCounters(monitor, { processStarts: 1 });
+ break;
+ }
+ allT3 = incrementCounters(allT3, { processStarts: 1 });
+ }
+
+ for (const [identityKey, previous] of input.previous) {
+ if (input.current.has(identityKey)) continue;
+ const group = categoryGroup(previous.process.category);
+ switch (group) {
+ case "backend":
+ backend = incrementCounters(backend, { processExits: 1 });
+ break;
+ case "electron":
+ electron = incrementCounters(electron, { processExits: 1 });
+ break;
+ case "monitor":
+ monitor = incrementCounters(monitor, { processExits: 1 });
+ break;
+ }
+ allT3 = incrementCounters(allT3, { processExits: 1 });
+ }
+
+ return { backend, electron, monitor, allT3 };
+}
+
+function aggregate(
+ processes: ReadonlyArray<ResourceTelemetryProcess>,
+ counters: GroupCounters,
+): ResourceTelemetryAggregate {
+ return {
+ 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,
+ };
+}
+
+export function mergeProcesses(input: MergeProcessesInput): MergeProcessesResult {
+ const nativeProcesses = Option.match(input.nativeSnapshot, {
+ onNone: () => [] as ReadonlyArray<ResourceMonitorProcessSample>,
+ onSome: (snapshot) => snapshot.processes,
+ });
+ const electronMetrics = Option.match(input.desktopSnapshot, {
+ onNone: () => [] as ReadonlyArray<DesktopElectronProcessMetric>,
+ onSome: (snapshot) => snapshot.electronProcesses,
+ });
+ const sampledAtMs = Option.match(input.nativeSnapshot, {
+ onNone: () =>
+ Option.match(input.desktopSnapshot, {
+ onNone: () => input.fallbackSampledAtMs,
+ onSome: (snapshot) => snapshot.sampledAtUnixMs,
+ }),
+ onSome: (native) =>
+ Option.match(input.desktopSnapshot, {
+ onNone: () => native.sampledAtUnixMs,
+ onSome: (desktop) => Math.max(native.sampledAtUnixMs, desktop.sampledAtUnixMs),
+ }),
+ });
+ const nativeSampledAtMs = Option.map(
+ input.nativeSnapshot,
+ (snapshot) => snapshot.sampledAtUnixMs,
+ );
+ const desktopSampledAtMs = Option.map(
+ input.desktopSnapshot,
+ (snapshot) => snapshot.sampledAtUnixMs,
+ );
+ const nativeProcessPids = new Set(nativeProcesses.map((process) => process.pid));
+ const nativeByPid = new Map(nativeProcesses.map((process) => [process.pid, process]));
+ const metricsByPid = new Map<number, DesktopElectronProcessMetric>();
+ for (const metric of electronMetrics) {
+ const nativeProcess = nativeByPid.get(metric.pid);
+ if (!nativeProcess) {
+ nativeByPid.set(
+ metric.pid,
+ syntheticNativeSample(
+ metric,
+ Option.getOrElse(desktopSampledAtMs, () => sampledAtMs),
+ input.previous.get(processIdentityKey(metric.pid, metric.creationTimeMs)),
+ ),
+ );
+ metricsByPid.set(metric.pid, metric);
+ continue;
+ }
+ if (
+ Math.abs(metric.creationTimeMs - nativeProcess.startTimeMs) <= ELECTRON_IDENTITY_TOLERANCE_MS
+ ) {
+ metricsByPid.set(metric.pid, metric);
+ }
+ }
+ const processes = [...nativeByPid.values()];
+ const processesByPid = new Map(processes.map((process) => [process.pid, process]));
+ const requestedElectronRootPids = input.electronRootPids ?? new Set<number>();
+ const explicitElectronRootPids = new Set(
+ [...requestedElectronRootPids].filter((pid) => {
+ const process = processesByPid.get(pid);
+ if (!process) return false;
+ const expectedStartTime = input.electronRootStartTimes?.get(pid);
+ if (expectedStartTime !== undefined) {
+ return Math.abs(process.startTimeMs - expectedStartTime) <= ELECTRON_IDENTITY_TOLERANCE_MS;
+ }
+ if (metricsByPid.has(pid)) return true;
+ return [...input.previous.values()].some(
+ (previous) =>
+ previous.process.category === "electron-main" &&
+ previous.process.identity.pid === pid &&
+ previous.process.identity.startTimeMs === process.startTimeMs,
+ );
+ }),
+ );
+ const electronPids = new Set([...metricsByPid.keys(), ...explicitElectronRootPids]);
+ const electronRootPids = [
+ ...explicitElectronRootPids,
+ ...[...electronPids]
+ .filter((pid) => {
+ if (explicitElectronRootPids.has(pid)) return false;
+ const process = processesByPid.get(pid);
+ return process === undefined
+ ? true
+ : !hasElectronAncestor(process, processesByPid, electronPids);
+ })
+ .toSorted((left, right) => left - right),
+ ].filter((pid, index, values) => values.indexOf(pid) === index);
+ const rootPids = [input.serverPid, ...electronRootPids];
+ const roots = new Set(rootPids);
+ const depths = processDepths(processes, roots);
+ const childrenByParent = new Map<number, number[]>();
+ for (const process of processes) {
+ const children = childrenByParent.get(process.ppid) ?? [];
+ children.push(process.pid);
+ childrenByParent.set(process.ppid, children);
+ }
+
+ const nextPrevious = new Map<string, ProcessState>();
+ const processDeltas: ProcessDelta[] = [];
+ const normalized = processes.map((process): ResourceTelemetryProcess => {
+ const identityKey = processIdentityKey(process.pid, process.startTimeMs);
+ const previous = input.previous.get(identityKey);
+ const counterSampledAtMs = nativeProcessPids.has(process.pid)
+ ? Option.getOrElse(nativeSampledAtMs, () => sampledAtMs)
+ : Option.getOrElse(desktopSampledAtMs, () => sampledAtMs);
+ const elapsedMs = previous ? counterSampledAtMs - previous.sampledAtMs : 0;
+ const cpuTimeDelta = previous
+ ? delta({
+ current: process.cpuTimeMs,
+ previous: previous.process.cpuTimeMs,
+ elapsedMs,
+ })
+ : 0;
+ const ioReadDelta = previous
+ ? delta({
+ current: process.ioReadBytes,
+ previous: previous.process.ioReadBytes,
+ elapsedMs,
+ })
+ : 0;
+ const ioWriteDelta = previous
+ ? delta({
+ current: process.ioWriteBytes,
+ previous: previous.process.ioWriteBytes,
+ elapsedMs,
+ })
+ : 0;
+ const electronMetric = matchElectronMetric(process, metricsByPid);
+ const category: ResourceTelemetryProcessCategory =
+ process.pid === input.serverPid
+ ? "server"
+ : Option.contains(input.sidecarPid, process.pid)
+ ? "resource-monitor"
+ : explicitElectronRootPids.has(process.pid)
+ ? "electron-main"
+ : electronMetric
+ ? electronCategory(electronMetric)
+ : isElectronDescendant(process.pid, processesByPid, electronPids)
+ ? inferredElectronCategory(process)
+ : "server-child";
+ const firstSeenAt = previous?.process.firstSeenAt ?? DateTime.makeUnsafe(sampledAtMs);
+ const preservePreviousRates = !input.updatePrevious && previous !== undefined;
+ const cpuPercent = preservePreviousRates
+ ? previous.process.cpuPercent
+ : previous && elapsedMs > 0 && elapsedMs <= MAX_DELTA_INTERVAL_MS
+ ? (cpuTimeDelta / elapsedMs) * 100
+ : finiteNonNegative(process.cpuPercent);
+ const normalizedProcess: ResourceTelemetryProcess = {
+ identity: {
+ pid: process.pid,
+ startTimeMs: process.startTimeMs,
+ },
+ ppid: process.ppid,
+ childPids: [...(childrenByParent.get(process.pid) ?? [])].toSorted(
+ (left, right) => left - right,
+ ),
+ depth: depths.get(process.pid) ?? 0,
+ name: process.name,
+ command: process.command,
+ status: process.status,
+ category,
+ ...(electronMetric ? { electronType: electronMetric.type } : {}),
+ ...(electronMetric?.serviceName ? { electronServiceName: electronMetric.serviceName } : {}),
+ cpuPercent: finiteNonNegative(cpuPercent),
+ cpuTimeMs: process.cpuTimeMs,
+ residentBytes: process.residentBytes,
+ peakResidentBytes: Math.max(
+ process.residentBytes,
+ electronMetric?.peakWorkingSetBytes ?? 0,
+ previous?.process.peakResidentBytes ?? 0,
+ ),
+ virtualBytes: process.virtualBytes,
+ ioReadBytes: process.ioReadBytes,
+ ioWriteBytes: process.ioWriteBytes,
+ ioReadBytesPerSecond: preservePreviousRates
+ ? previous.process.ioReadBytesPerSecond
+ : elapsedMs > 0
+ ? finiteNonNegative((ioReadDelta * 1_000) / elapsedMs)
+ : 0,
+ ioWriteBytesPerSecond: preservePreviousRates
+ ? previous.process.ioWriteBytesPerSecond
+ : elapsedMs > 0
+ ? finiteNonNegative((ioWriteDelta * 1_000) / elapsedMs)
+ : 0,
+ ioSemantics: process.ioSemantics,
+ ...(electronMetric ? { idleWakeupsPerSecond: electronMetric.idleWakeupsPerSecond } : {}),
+ runTimeMs: process.runTimeMs,
+ firstSeenAt,
+ lastSeenAt: DateTime.makeUnsafe(sampledAtMs),
+ };
+ nextPrevious.set(identityKey, {
+ process: normalizedProcess,
+ sampledAtMs: counterSampledAtMs,
+ });
+ processDeltas.push({
+ identityKey,
+ category,
+ cpuTimeMs: cpuTimeDelta,
+ ioReadBytes: ioReadDelta,
+ ioWriteBytes: ioWriteDelta,
+ });
+ return normalizedProcess;
+ });
+ const ordered = orderProcessTree(normalized, rootPids);
+
+ const counters = input.updatePrevious
+ ? applyLifecycleCounters({
+ counters: input.counters,
+ deltas: processDeltas,
+ current: nextPrevious,
+ previous: input.previous,
+ })
+ : input.counters;
+ const backendProcesses = ordered.filter(
+ (process) => categoryGroup(process.category) === "backend",
+ );
+ const electronProcesses = ordered.filter(
+ (process) => categoryGroup(process.category) === "electron",
+ );
+ const monitorProcesses = ordered.filter(
+ (process) => categoryGroup(process.category) === "monitor",
+ );
+
+ return {
+ sampledAtMs,
+ processes: ordered,
+ previous: input.updatePrevious ? nextPrevious : input.previous,
+ counters,
+ groups: {
+ backend: aggregate(backendProcesses, counters.backend),
+ electron: aggregate(electronProcesses, counters.electron),
+ monitor: aggregate(monitorProcesses, counters.monitor),
+ allT3: aggregate(ordered, counters.allT3),
+ },
+ deltas: processDeltas,
+ };
+}
diff --git a/apps/server/src/resourceTelemetry/NativeTelemetryClient.test.ts b/apps/server/src/resourceTelemetry/NativeTelemetryClient.test.ts
new file mode 100644
index 000000000..61a67d116
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/NativeTelemetryClient.test.ts
@@ -0,0 +1,241 @@
+import type { HostPowerSnapshot } from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Ref from "effect/Ref";
+import * as Semaphore from "effect/Semaphore";
+
+import {
+ NativeTelemetryRequestTimedOut,
+ NativeTelemetryStreamClosed,
+ canCommandNativeTelemetrySidecar,
+ canRequestNativeTelemetryRetry,
+ commitCollectionControlUpdate,
+ nativeTelemetrySupervisorFailureMessage,
+ retainRecentNativeTelemetryFailures,
+ resolveNativeSampleIntervalMs,
+ synchronizeCollectionControlOnStart,
+} from "./NativeTelemetryClient.ts";
+
+const basePower: HostPowerSnapshot = {
+ source: "electron-main",
+ idle: "false",
+ idleSeconds: 0,
+ locked: "false",
+ suspended: false,
+ onBattery: "false",
+ lowPowerMode: "false",
+ thermalState: "nominal",
+ stale: false,
+ updatedAt: DateTime.makeUnsafe("2026-06-17T12:00:00.000Z"),
+};
+
+describe("resolveNativeSampleIntervalMs", () => {
+ it("keeps a recovery cadence while suspended and backs off under host constraints", () => {
+ expect(resolveNativeSampleIntervalMs({ ...basePower, suspended: true }, 1)).toBe(15_000);
+ expect(resolveNativeSampleIntervalMs({ ...basePower, locked: "true" }, 1)).toBe(15_000);
+ expect(resolveNativeSampleIntervalMs({ ...basePower, lowPowerMode: "true" }, 1)).toBe(15_000);
+ expect(resolveNativeSampleIntervalMs({ ...basePower, thermalState: "critical" }, 1)).toBe(
+ 15_000,
+ );
+ expect(resolveNativeSampleIntervalMs({ ...basePower, onBattery: "true" }, 1)).toBe(5_000);
+ });
+
+ it("keeps unknown background telemetry cheap but serves live diagnostics at 1Hz", () => {
+ const unknown: HostPowerSnapshot = {
+ ...basePower,
+ source: "unknown",
+ stale: true,
+ };
+ expect(resolveNativeSampleIntervalMs(unknown, 0)).toBe(5_000);
+ expect(resolveNativeSampleIntervalMs(unknown, 1)).toBe(1_000);
+ expect(
+ resolveNativeSampleIntervalMs(
+ { ...basePower, stale: true, locked: "true", suspended: true },
+ 0,
+ ),
+ ).toBe(5_000);
+ expect(resolveNativeSampleIntervalMs(basePower, 0)).toBe(1_000);
+ });
+});
+
+describe("canRequestNativeTelemetryRetry", () => {
+ it("only accepts retry while the supervisor is waiting without a live sidecar", () => {
+ expect(canRequestNativeTelemetryRetry("degraded", false)).toBe(true);
+ expect(canRequestNativeTelemetryRetry("unavailable", false)).toBe(true);
+ expect(canRequestNativeTelemetryRetry("degraded", true)).toBe(false);
+ expect(canRequestNativeTelemetryRetry("healthy", false)).toBe(false);
+ expect(canRequestNativeTelemetryRetry("starting", false)).toBe(false);
+ });
+});
+
+describe("canCommandNativeTelemetrySidecar", () => {
+ it("keeps on-demand recovery commands available while a live sidecar is degraded", () => {
+ expect(canCommandNativeTelemetrySidecar("healthy", true)).toBe(true);
+ expect(canCommandNativeTelemetrySidecar("degraded", true)).toBe(true);
+ expect(canCommandNativeTelemetrySidecar("unavailable", true)).toBe(false);
+ expect(canCommandNativeTelemetrySidecar("degraded", false)).toBe(false);
+ });
+});
+
+describe("NativeTelemetryRequestTimedOut", () => {
+ it("models history and sample request deadlines without a fabricated cause", () => {
+ const historyTimeout = new NativeTelemetryRequestTimedOut({
+ operation: "readHistory",
+ timeoutMs: 15_000,
+ });
+ const sampleTimeout = new NativeTelemetryRequestTimedOut({
+ operation: "sampleNow",
+ timeoutMs: 5_000,
+ });
+
+ expect(historyTimeout.message).toBe(
+ "Resource monitor 'readHistory' request timed out after 15000ms.",
+ );
+ expect(sampleTimeout.message).toBe(
+ "Resource monitor 'sampleNow' request timed out after 5000ms.",
+ );
+ expect("cause" in historyTimeout).toBe(false);
+ expect("cause" in sampleTimeout).toBe(false);
+ });
+});
+
+describe("native telemetry supervisor failures", () => {
+ it("distinguishes a closed event stream from a process exit", () => {
+ expect(new NativeTelemetryStreamClosed().message).toBe(
+ "Resource monitor event stream closed unexpectedly.",
+ );
+ });
+
+ it("keeps defect details out of the caller-visible health message", () => {
+ const secret = "credential=do-not-expose";
+ const message = nativeTelemetrySupervisorFailureMessage(Cause.die(new Error(secret)));
+
+ expect(message).toBe("Resource monitor supervisor stopped unexpectedly.");
+ expect(message).not.toContain(secret);
+ });
+});
+
+describe("retainRecentNativeTelemetryFailures", () => {
+ it("expires old failures so an isolated crash restarts from the initial backoff", () => {
+ expect(retainRecentNativeTelemetryFailures([0, 30_000], 90_001)).toEqual([]);
+ expect(retainRecentNativeTelemetryFailures([30_000, 60_000], 90_000)).toEqual([30_000, 60_000]);
+ });
+});
+
+describe("commitCollectionControlUpdate", () => {
+ it.effect("retains desired demand and retries unapplied sidecar state", () =>
+ Effect.gen(function* () {
+ const initial = {
+ hostPower: basePower,
+ liveSubscriberCount: 0,
+ sampleIntervalMs: 5_000,
+ };
+ const desired = yield* Ref.make(initial);
+ const applied = yield* Ref.make(initial);
+ const failure = new Error("sidecar write failed");
+ const receivedStates: Array<readonly [number, number]> = [];
+
+ const received = yield* commitCollectionControlUpdate(
+ desired,
+ applied,
+ (current) => ({
+ ...current,
+ liveSubscriberCount: 1,
+ sampleIntervalMs: 1_000,
+ }),
+ (previous, next) => {
+ receivedStates.push([previous.sampleIntervalMs, next.sampleIntervalMs]);
+ return Effect.fail(failure);
+ },
+ ).pipe(Effect.flip);
+
+ expect(received).toBe(failure);
+ expect(yield* Ref.get(desired)).toEqual({
+ ...initial,
+ liveSubscriberCount: 1,
+ sampleIntervalMs: 1_000,
+ });
+ expect(yield* Ref.get(applied)).toEqual(initial);
+
+ yield* commitCollectionControlUpdate(
+ desired,
+ applied,
+ (current) => current,
+ (previous, next) => {
+ receivedStates.push([previous.sampleIntervalMs, next.sampleIntervalMs]);
+ return Effect.void;
+ },
+ );
+ expect(receivedStates).toEqual([
+ [5_000, 1_000],
+ [5_000, 1_000],
+ ]);
+ expect(yield* Ref.get(applied)).toEqual(yield* Ref.get(desired));
+ }),
+ );
+
+ it.effect("serializes startup synchronization with runtime control updates", () =>
+ Effect.gen(function* () {
+ const initial = {
+ hostPower: basePower,
+ liveSubscriberCount: 0,
+ sampleIntervalMs: 5_000,
+ };
+ const desired = yield* Ref.make(initial);
+ const applied = yield* Ref.make(initial);
+ const ready = yield* Ref.make(false);
+ const mutex = yield* Semaphore.make(1);
+ const startupApplying = yield* Deferred.make<void>();
+ const releaseStartup = yield* Deferred.make<void>();
+ const appliedIntervals: Array<number> = [];
+
+ const startupFiber = yield* synchronizeCollectionControlOnStart(
+ mutex,
+ desired,
+ applied,
+ (control) =>
+ Effect.sync(() => {
+ appliedIntervals.push(control.sampleIntervalMs);
+ }).pipe(
+ Effect.andThen(Deferred.succeed(startupApplying, undefined)),
+ Effect.andThen(Deferred.await(releaseStartup)),
+ Effect.asVoid,
+ ),
+ Ref.set(ready, true),
+ ).pipe(Effect.forkChild);
+ yield* Deferred.await(startupApplying);
+
+ const updateFiber = yield* mutex
+ .withPermits(1)(
+ commitCollectionControlUpdate(
+ desired,
+ applied,
+ (current) => ({
+ ...current,
+ liveSubscriberCount: 1,
+ sampleIntervalMs: 1_000,
+ }),
+ (_previous, next) =>
+ Effect.gen(function* () {
+ expect(yield* Ref.get(ready)).toBe(true);
+ appliedIntervals.push(next.sampleIntervalMs);
+ }),
+ ),
+ )
+ .pipe(Effect.forkChild);
+ yield* Effect.yieldNow;
+ expect(yield* Ref.get(desired)).toEqual(initial);
+
+ yield* Deferred.succeed(releaseStartup, undefined);
+ yield* Fiber.join(startupFiber);
+ yield* Fiber.join(updateFiber);
+
+ expect(appliedIntervals).toEqual([5_000, 1_000]);
+ expect(yield* Ref.get(applied)).toEqual(yield* Ref.get(desired));
+ }),
+ );
+});
diff --git a/apps/server/src/resourceTelemetry/NativeTelemetryClient.ts b/apps/server/src/resourceTelemetry/NativeTelemetryClient.ts
new file mode 100644
index 000000000..e8d81cc4c
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/NativeTelemetryClient.ts
@@ -0,0 +1,1024 @@
+import type {
+ HostPowerSnapshot,
+ ResourceMonitorCapabilities,
+ ResourceMonitorCommand,
+ ResourceMonitorEvent,
+ ResourceMonitorExternalProcess,
+ ResourceMonitorHelloEvent,
+ ResourceMonitorSnapshotEvent,
+ ResourceTelemetrySourceStatus,
+} from "@t3tools/contracts";
+import {
+ RESOURCE_MONITOR_PROTOCOL_VERSION,
+ ResourceMonitorCommand as ResourceMonitorCommandSchema,
+ ResourceMonitorEvent as ResourceMonitorEventSchema,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as Ndjson from "effect/unstable/encoding/Ndjson";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import * as ResourceMonitorBinary from "./ResourceMonitorBinary.ts";
+import { ServerConfig } from "../config.ts";
+import { subscribeBeforeSnapshotWithoutMutex } from "../utils/subscribeBeforeSnapshot.ts";
+
+const SAMPLE_INTERVAL_MS = 1_000;
+const UNKNOWN_BACKGROUND_SAMPLE_INTERVAL_MS = 5_000;
+const BATTERY_SAMPLE_INTERVAL_MS = 5_000;
+const CONSTRAINED_SAMPLE_INTERVAL_MS = 15_000;
+const HANDSHAKE_TIMEOUT = Duration.seconds(5);
+const SAMPLE_REQUEST_TIMEOUT = Duration.seconds(5);
+const HISTORY_REQUEST_TIMEOUT = Duration.seconds(15);
+const INITIAL_RESTART_DELAY = Duration.millis(500);
+const MAX_RESTART_DELAY = Duration.seconds(10);
+const FAILURE_WINDOW_MS = 60_000;
+const MAX_FAILURES_PER_WINDOW = 5;
+
+export class NativeTelemetrySpawnFailed extends Schema.TaggedErrorClass<NativeTelemetrySpawnFailed>()(
+ "NativeTelemetrySpawnFailed",
+ {
+ path: Schema.String,
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return `Failed to start resource monitor '${this.path}'.`;
+ }
+}
+
+export class NativeTelemetryHandshakeTimedOut extends Schema.TaggedErrorClass<NativeTelemetryHandshakeTimedOut>()(
+ "NativeTelemetryHandshakeTimedOut",
+ {
+ timeoutMs: Schema.Number,
+ },
+) {
+ override get message(): string {
+ return `Resource monitor handshake timed out after ${this.timeoutMs}ms.`;
+ }
+}
+
+export class NativeTelemetryRequestTimedOut extends Schema.TaggedErrorClass<NativeTelemetryRequestTimedOut>()(
+ "NativeTelemetryRequestTimedOut",
+ {
+ operation: Schema.Literals(["readHistory", "sampleNow"]),
+ timeoutMs: Schema.Number,
+ },
+) {
+ override get message(): string {
+ return `Resource monitor '${this.operation}' request timed out after ${this.timeoutMs}ms.`;
+ }
+}
+
+export class NativeTelemetryProtocolMismatch extends Schema.TaggedErrorClass<NativeTelemetryProtocolMismatch>()(
+ "NativeTelemetryProtocolMismatch",
+ {
+ expectedVersion: Schema.Number,
+ receivedVersion: Schema.Number,
+ },
+) {
+ override get message(): string {
+ return `Resource monitor protocol ${this.receivedVersion} is incompatible with expected protocol ${this.expectedVersion}.`;
+ }
+}
+
+export class NativeTelemetryDecodeFailed extends Schema.TaggedErrorClass<NativeTelemetryDecodeFailed>()(
+ "NativeTelemetryDecodeFailed",
+ {
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return "Failed to decode resource monitor output.";
+ }
+}
+
+export class NativeTelemetryCommandFailed extends Schema.TaggedErrorClass<NativeTelemetryCommandFailed>()(
+ "NativeTelemetryCommandFailed",
+ {
+ operation: Schema.String,
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return `Resource monitor command '${this.operation}' failed.`;
+ }
+}
+
+export class NativeTelemetryExited extends Schema.TaggedErrorClass<NativeTelemetryExited>()(
+ "NativeTelemetryExited",
+ {
+ exitCode: Schema.Number,
+ },
+) {
+ override get message(): string {
+ return `Resource monitor exited with code ${this.exitCode}.`;
+ }
+}
+
+export class NativeTelemetryStreamClosed extends Schema.TaggedErrorClass<NativeTelemetryStreamClosed>()(
+ "NativeTelemetryStreamClosed",
+ {},
+) {
+ override get message(): string {
+ return "Resource monitor event stream closed unexpectedly.";
+ }
+}
+
+export class NativeTelemetryUnavailable extends Schema.TaggedErrorClass<NativeTelemetryUnavailable>()(
+ "NativeTelemetryUnavailable",
+ {
+ reason: Schema.String,
+ },
+) {
+ override get message(): string {
+ return `Resource monitor is unavailable: ${this.reason}`;
+ }
+}
+
+export type NativeTelemetryClientError =
+ | ResourceMonitorBinary.ResourceMonitorBinaryError
+ | NativeTelemetrySpawnFailed
+ | NativeTelemetryHandshakeTimedOut
+ | NativeTelemetryRequestTimedOut
+ | NativeTelemetryProtocolMismatch
+ | NativeTelemetryDecodeFailed
+ | NativeTelemetryCommandFailed
+ | NativeTelemetryExited
+ | NativeTelemetryStreamClosed
+ | NativeTelemetryUnavailable;
+
+export interface NativeTelemetryClientHealth {
+ readonly status: ResourceTelemetrySourceStatus;
+ readonly hello: Option.Option<ResourceMonitorHelloEvent>;
+ readonly lastSampleAt: Option.Option<DateTime.Utc>;
+ readonly lastError: Option.Option<string>;
+ readonly restartCount: number;
+ readonly sampleIntervalMs: number;
+}
+
+export interface NativeTelemetrySnapshot {
+ readonly generation: number;
+ readonly snapshot: ResourceMonitorSnapshotEvent;
+}
+
+export class NativeTelemetryClient extends Context.Service<
+ NativeTelemetryClient,
+ {
+ readonly capabilities: Effect.Effect<ResourceMonitorCapabilities, NativeTelemetryClientError>;
+ readonly snapshots: Stream.Stream<NativeTelemetrySnapshot, NativeTelemetryClientError>;
+ readonly readHistory: (
+ windowMs: number,
+ ) => Effect.Effect<ReadonlyArray<ResourceMonitorSnapshotEvent>, NativeTelemetryClientError>;
+ readonly setExternalProcesses: (
+ processes: ReadonlyArray<ResourceMonitorExternalProcess>,
+ ) => Effect.Effect<void, NativeTelemetryClientError>;
+ readonly setHostPowerState: (
+ snapshot: HostPowerSnapshot,
+ ) => Effect.Effect<void, NativeTelemetryClientError>;
+ readonly sampleNow: Effect.Effect<NativeTelemetrySnapshot, NativeTelemetryClientError>;
+ readonly retry: Effect.Effect<boolean>;
+ readonly health: Effect.Effect<NativeTelemetryClientHealth>;
+ readonly subscribeHealth: Effect.Effect<
+ {
+ readonly latest: NativeTelemetryClientHealth;
+ readonly changes: Stream.Stream<NativeTelemetryClientHealth>;
+ },
+ never,
+ Scope.Scope
+ >;
+ }
+>()("t3/resourceTelemetry/NativeTelemetryClient") {}
+
+interface ClientState {
+ readonly status: ResourceTelemetrySourceStatus;
+ readonly handle: Option.Option<ChildProcessSpawner.ChildProcessHandle>;
+ readonly hello: Option.Option<ResourceMonitorHelloEvent>;
+ readonly lastSampleAt: Option.Option<DateTime.Utc>;
+ readonly lastError: Option.Option<string>;
+ readonly restartCount: number;
+}
+
+export interface CollectionControl {
+ readonly hostPower: HostPowerSnapshot;
+ readonly liveSubscriberCount: number;
+ readonly sampleIntervalMs: number;
+}
+
+interface PendingHistoryRequest {
+ readonly deferred: Deferred.Deferred<
+ ReadonlyArray<ResourceMonitorSnapshotEvent>,
+ NativeTelemetryClientError
+ >;
+ readonly snapshots: ReadonlyArray<ResourceMonitorSnapshotEvent>;
+}
+
+const initialState: ClientState = {
+ status: "starting",
+ handle: Option.none(),
+ hello: Option.none(),
+ lastSampleAt: Option.none(),
+ lastError: Option.none(),
+ restartCount: 0,
+};
+
+function toHealth(state: ClientState, sampleIntervalMs: number): NativeTelemetryClientHealth {
+ return {
+ status: state.status,
+ hello: state.hello,
+ lastSampleAt: state.lastSampleAt,
+ lastError: state.lastError,
+ restartCount: state.restartCount,
+ sampleIntervalMs,
+ };
+}
+
+function isThermallyConstrained(snapshot: HostPowerSnapshot): boolean {
+ return snapshot.thermalState === "serious" || snapshot.thermalState === "critical";
+}
+
+export function resolveNativeSampleIntervalMs(
+ snapshot: HostPowerSnapshot,
+ liveSubscriberCount: number,
+): number {
+ if (snapshot.stale || snapshot.source === "unknown") {
+ return liveSubscriberCount > 0 ? SAMPLE_INTERVAL_MS : UNKNOWN_BACKGROUND_SAMPLE_INTERVAL_MS;
+ }
+ if (
+ snapshot.suspended ||
+ snapshot.locked === "true" ||
+ snapshot.lowPowerMode === "true" ||
+ isThermallyConstrained(snapshot)
+ ) {
+ return CONSTRAINED_SAMPLE_INTERVAL_MS;
+ }
+ if (snapshot.onBattery === "true") return BATTERY_SAMPLE_INTERVAL_MS;
+ return SAMPLE_INTERVAL_MS;
+}
+
+export function commitCollectionControlUpdate<E, R>(
+ desiredState: Ref.Ref<CollectionControl>,
+ appliedState: Ref.Ref<CollectionControl>,
+ update: (current: CollectionControl) => CollectionControl,
+ apply: (previous: CollectionControl, next: CollectionControl) => Effect.Effect<void, E, R>,
+): Effect.Effect<readonly [CollectionControl, CollectionControl], E, R> {
+ return Effect.gen(function* () {
+ const [previousDesired, next] = yield* Ref.modify(desiredState, (previous) => {
+ const next = update(previous);
+ return [[previous, next] as const, next];
+ });
+ const previousApplied = yield* Ref.get(appliedState);
+ yield* apply(previousApplied, next);
+ yield* Ref.set(appliedState, next);
+ return [previousDesired, next] as const;
+ });
+}
+
+export function synchronizeCollectionControlOnStart<E1, R1, E2, R2>(
+ mutex: Semaphore.Semaphore,
+ desiredState: Ref.Ref<CollectionControl>,
+ appliedState: Ref.Ref<CollectionControl>,
+ apply: (control: CollectionControl) => Effect.Effect<void, E1, R1>,
+ markReady: Effect.Effect<void, E2, R2>,
+) {
+ return mutex.withPermits(1)(
+ Effect.gen(function* () {
+ const control = yield* Ref.get(desiredState);
+ yield* apply(control);
+ yield* Ref.set(appliedState, control);
+ yield* markReady;
+ return control;
+ }),
+ );
+}
+
+const decodeMonitorEvent: (
+ value: unknown,
+) => Effect.Effect<ResourceMonitorEvent, Schema.SchemaError> = Schema.decodeUnknownEffect(
+ ResourceMonitorEventSchema,
+);
+const encodeMonitorCommand = Schema.encodeEffect(
+ Schema.fromJsonString(ResourceMonitorCommandSchema),
+);
+const isProtocolMismatch = Schema.is(NativeTelemetryProtocolMismatch);
+const isDecodeFailed = Schema.is(NativeTelemetryDecodeFailed);
+const isCommandFailed = Schema.is(NativeTelemetryCommandFailed);
+
+function eventVersion(value: unknown): number | undefined {
+ if (typeof value !== "object" || value === null) return undefined;
+ const version = Reflect.get(value, "version");
+ return typeof version === "number" ? version : undefined;
+}
+
+function restartDelay(attempt: number): Duration.Duration {
+ return Duration.min(Duration.times(INITIAL_RESTART_DELAY, 2 ** attempt), MAX_RESTART_DELAY);
+}
+
+export function retainRecentNativeTelemetryFailures(
+ failures: ReadonlyArray<number>,
+ now: number,
+): ReadonlyArray<number> {
+ return failures.filter((failedAt) => now - failedAt <= FAILURE_WINDOW_MS);
+}
+
+function errorMessage(error: NativeTelemetryClientError): string {
+ return error.message;
+}
+
+export function nativeTelemetrySupervisorFailureMessage(_cause: Cause.Cause<unknown>): string {
+ return "Resource monitor supervisor stopped unexpectedly.";
+}
+
+export function canRequestNativeTelemetryRetry(
+ status: ResourceTelemetrySourceStatus,
+ hasHandle: boolean,
+): boolean {
+ return status !== "healthy" && status !== "starting" && !hasHandle;
+}
+
+export function canCommandNativeTelemetrySidecar(
+ status: ResourceTelemetrySourceStatus,
+ hasHandle: boolean,
+): boolean {
+ return hasHandle && (status === "healthy" || status === "degraded");
+}
+
+export const make = Effect.fn("resourceTelemetry.nativeTelemetryClient.make")(function* () {
+ const binary = yield* ResourceMonitorBinary.ResourceMonitorBinary;
+ const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+ const crypto = yield* Crypto.Crypto;
+ const config = yield* ServerConfig;
+ const initializedAt = yield* DateTime.now;
+ const state = yield* Ref.make(initialState);
+ const collectionControl = yield* Ref.make<CollectionControl>({
+ hostPower: {
+ source: "unknown",
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt: initializedAt,
+ },
+ liveSubscriberCount: 0,
+ sampleIntervalMs: UNKNOWN_BACKGROUND_SAMPLE_INTERVAL_MS,
+ });
+ const appliedCollectionControl = yield* Ref.make(yield* Ref.get(collectionControl));
+ const externalProcesses = yield* Ref.make<ReadonlyArray<ResourceMonitorExternalProcess>>([]);
+ const pendingSamples = yield* Ref.make(
+ new Map<string, Deferred.Deferred<NativeTelemetrySnapshot, NativeTelemetryClientError>>(),
+ );
+ const pendingHistories = yield* Ref.make(new Map<string, PendingHistoryRequest>());
+ const snapshots = yield* PubSub.sliding<NativeTelemetrySnapshot>(8);
+ const healthChanges = yield* PubSub.sliding<NativeTelemetryClientHealth>(4);
+ const retryQueue = yield* Queue.sliding<void>(1);
+ const commandMutex = yield* Semaphore.make(1);
+ const controlMutex = yield* Semaphore.make(1);
+ const currentHealth = Effect.all([Ref.get(state), Ref.get(collectionControl)]).pipe(
+ Effect.map(([current, control]) => toHealth(current, control.sampleIntervalMs)),
+ );
+ const publishHealth = currentHealth.pipe(
+ Effect.flatMap((health) => PubSub.publish(healthChanges, health)),
+ Effect.asVoid,
+ );
+
+ const failPending = (error: NativeTelemetryClientError) =>
+ Effect.gen(function* () {
+ const samples = yield* Ref.getAndSet(pendingSamples, new Map());
+ const histories = yield* Ref.getAndSet(pendingHistories, new Map());
+ yield* Effect.forEach(samples.values(), (deferred) => Deferred.fail(deferred, error), {
+ discard: true,
+ });
+ yield* Effect.forEach(
+ histories.values(),
+ (request) => Deferred.fail(request.deferred, error),
+ { discard: true },
+ );
+ });
+
+ const writeCommand = (
+ handle: ChildProcessSpawner.ChildProcessHandle,
+ command: ResourceMonitorCommand,
+ ): Effect.Effect<void, NativeTelemetryClientError> =>
+ commandMutex.withPermits(1)(
+ encodeMonitorCommand(command).pipe(
+ Effect.map((encoded) => `${encoded}\n`),
+ Effect.mapError(
+ (cause) =>
+ new NativeTelemetryCommandFailed({
+ operation: command.type,
+ cause,
+ }),
+ ),
+ Effect.flatMap((encoded) =>
+ Stream.run(Stream.encodeText(Stream.make(encoded)), handle.stdin),
+ ),
+ Effect.mapError(
+ (cause) =>
+ new NativeTelemetryCommandFailed({
+ operation: command.type,
+ cause,
+ }),
+ ),
+ ),
+ );
+
+ const processEvent = (
+ event: ResourceMonitorEvent,
+ helloDeferred: Deferred.Deferred<ResourceMonitorHelloEvent>,
+ generation: number,
+ ): Effect.Effect<void, NativeTelemetryClientError> => {
+ switch (event.type) {
+ case "hello":
+ return Ref.update(state, (current) => ({
+ ...current,
+ status: "starting" as const,
+ hello: Option.some(event),
+ lastError: Option.none(),
+ })).pipe(
+ Effect.andThen(publishHealth),
+ Effect.andThen(Deferred.succeed(helloDeferred, event)),
+ Effect.asVoid,
+ );
+ case "snapshot":
+ return Effect.gen(function* () {
+ const nativeSnapshot = { generation, snapshot: event } satisfies NativeTelemetrySnapshot;
+ const sampledAt = DateTime.makeUnsafe(event.sampledAtUnixMs);
+ yield* Ref.update(state, (current) => ({
+ ...current,
+ status: "healthy" as const,
+ lastSampleAt: Option.some(sampledAt),
+ lastError: Option.none(),
+ }));
+ yield* publishHealth;
+ yield* PubSub.publish(snapshots, nativeSnapshot);
+ if (event.requestId) {
+ const deferred = yield* Ref.modify(pendingSamples, (pending) => {
+ const next = new Map(pending);
+ const current = next.get(event.requestId!);
+ next.delete(event.requestId!);
+ return [Option.fromUndefinedOr(current), next];
+ });
+ if (Option.isSome(deferred)) {
+ yield* Deferred.succeed(deferred.value, nativeSnapshot);
+ }
+ }
+ });
+ case "historyChunk":
+ return Effect.gen(function* () {
+ const latestSnapshot = event.snapshots.at(-1);
+ yield* Ref.update(state, (current) => ({
+ ...current,
+ status: "healthy" as const,
+ lastSampleAt: latestSnapshot
+ ? Option.some(DateTime.makeUnsafe(latestSnapshot.sampledAtUnixMs))
+ : current.lastSampleAt,
+ lastError: Option.none(),
+ }));
+ yield* publishHealth;
+ const completed = yield* Ref.modify(pendingHistories, (pending) => {
+ const request = pending.get(event.requestId);
+ if (!request) return [Option.none(), pending] as const;
+ const snapshots = [...request.snapshots, ...event.snapshots];
+ const next = new Map(pending);
+ if (event.done) {
+ next.delete(event.requestId);
+ return [Option.some({ deferred: request.deferred, snapshots }), next] as const;
+ }
+ next.set(event.requestId, { deferred: request.deferred, snapshots });
+ return [Option.none(), next] as const;
+ });
+ if (Option.isSome(completed)) {
+ yield* Deferred.succeed(completed.value.deferred, completed.value.snapshots);
+ }
+ });
+ case "error":
+ return Ref.update(state, (current) => ({
+ ...current,
+ status: "degraded" as const,
+ lastError: Option.some(event.message),
+ })).pipe(
+ Effect.andThen(publishHealth),
+ Effect.andThen(
+ event.recoverable
+ ? Effect.void
+ : Effect.fail(
+ new NativeTelemetryCommandFailed({
+ operation: event.code,
+ cause: event.message,
+ }),
+ ),
+ ),
+ );
+ }
+ };
+
+ const runAttempt: Effect.Effect<void, NativeTelemetryClientError> = Effect.scoped(
+ Effect.gen(function* () {
+ const executablePath = yield* binary.resolve;
+ const command = ChildProcess.make(executablePath, [], {
+ cwd: config.cwd,
+ stdin: {
+ stream: "pipe",
+ endOnDone: false,
+ },
+ stdout: "pipe",
+ stderr: "pipe",
+ killSignal: "SIGTERM",
+ forceKillAfter: Duration.seconds(2),
+ });
+ const handle = yield* Effect.acquireRelease(
+ spawner
+ .spawn(command)
+ .pipe(
+ Effect.mapError(
+ (cause) => new NativeTelemetrySpawnFailed({ path: executablePath, cause }),
+ ),
+ ),
+ (child) => child.kill().pipe(Effect.ignore),
+ );
+ yield* Ref.update(state, (current) => ({
+ ...current,
+ status: "starting" as const,
+ handle: Option.some(handle),
+ hello: Option.none(),
+ }));
+ yield* publishHealth;
+ const generation = (yield* Ref.get(state)).restartCount;
+
+ const helloDeferred = yield* Deferred.make<ResourceMonitorHelloEvent>();
+ const eventFiber = yield* handle.stdout.pipe(
+ Stream.pipeThroughChannel(Ndjson.decode({ ignoreEmptyLines: true })),
+ Stream.mapEffect(
+ (
+ value,
+ ): Effect.Effect<
+ ResourceMonitorEvent,
+ NativeTelemetryProtocolMismatch | NativeTelemetryDecodeFailed
+ > => {
+ const version = eventVersion(value);
+ if (version !== undefined && version !== RESOURCE_MONITOR_PROTOCOL_VERSION) {
+ return Effect.fail(
+ new NativeTelemetryProtocolMismatch({
+ expectedVersion: RESOURCE_MONITOR_PROTOCOL_VERSION,
+ receivedVersion: version,
+ }),
+ );
+ }
+ return decodeMonitorEvent(value).pipe(
+ Effect.mapError((cause) => new NativeTelemetryDecodeFailed({ cause })),
+ );
+ },
+ ),
+ Stream.runForEach((event) => processEvent(event, helloDeferred, generation)),
+ Effect.mapError((cause) =>
+ isProtocolMismatch(cause) || isDecodeFailed(cause) || isCommandFailed(cause)
+ ? cause
+ : new NativeTelemetryDecodeFailed({ cause }),
+ ),
+ Effect.forkScoped,
+ );
+ yield* handle.stderr.pipe(Stream.runDrain, Effect.ignore, Effect.forkScoped);
+
+ const hello = yield* Deferred.await(helloDeferred).pipe(
+ Effect.timeoutOption(HANDSHAKE_TIMEOUT),
+ Effect.flatMap(
+ Option.match({
+ onNone: () =>
+ Effect.fail(
+ new NativeTelemetryHandshakeTimedOut({
+ timeoutMs: Duration.toMillis(HANDSHAKE_TIMEOUT),
+ }),
+ ),
+ onSome: Effect.succeed,
+ }),
+ ),
+ );
+ yield* synchronizeCollectionControlOnStart(
+ controlMutex,
+ collectionControl,
+ appliedCollectionControl,
+ (control) =>
+ Effect.gen(function* () {
+ yield* writeCommand(handle, {
+ version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+ type: "configure",
+ rootPid: process.pid,
+ sampleIntervalMs: control.sampleIntervalMs,
+ externalProcesses: [...(yield* Ref.get(externalProcesses))],
+ });
+ if (control.liveSubscriberCount > 0) {
+ yield* writeCommand(handle, {
+ version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+ type: "setStreaming",
+ enabled: true,
+ });
+ }
+ }),
+ Ref.update(state, (current) => ({
+ ...current,
+ status: "healthy" as const,
+ hello: Option.some(hello),
+ })).pipe(Effect.andThen(publishHealth)),
+ );
+
+ yield* writeCommand(handle, {
+ version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+ type: "setExternalProcesses",
+ processes: [...(yield* Ref.get(externalProcesses))],
+ });
+
+ const exitEffect = handle.exitCode.pipe(
+ Effect.mapError(
+ (cause) =>
+ new NativeTelemetryCommandFailed({
+ operation: "waitForExit",
+ cause,
+ }),
+ ),
+ Effect.flatMap((exitCode) =>
+ Effect.fail(new NativeTelemetryExited({ exitCode: Number(exitCode) })),
+ ),
+ );
+ const decoderEffect = Fiber.join(eventFiber).pipe(
+ Effect.andThen(Effect.fail(new NativeTelemetryStreamClosed())),
+ );
+ return yield* Effect.raceFirst(exitEffect, decoderEffect);
+ }),
+ ).pipe(
+ Effect.ensuring(
+ Ref.update(state, (current) => ({
+ ...current,
+ handle: Option.none(),
+ })),
+ ),
+ );
+
+ yield* Effect.gen(function* () {
+ let failures: ReadonlyArray<number> = [];
+ let restartAttempt = 0;
+
+ while (true) {
+ const result = yield* Effect.result(runAttempt);
+ if (Result.isSuccess(result)) {
+ return;
+ }
+
+ const error = result.failure;
+ const now = DateTime.toEpochMillis(yield* DateTime.now);
+ const recentFailures = retainRecentNativeTelemetryFailures(failures, now);
+ if (recentFailures.length === 0) {
+ restartAttempt = 0;
+ }
+ failures = [...recentFailures, now];
+ const exhausted = failures.length >= MAX_FAILURES_PER_WINDOW;
+ yield* Ref.update(state, (current) => ({
+ ...current,
+ status: exhausted ? ("unavailable" as const) : ("degraded" as const),
+ hello: Option.none(),
+ lastError: Option.some(errorMessage(error)),
+ restartCount: current.restartCount + 1,
+ }));
+ yield* publishHealth;
+ yield* failPending(error);
+
+ if (exhausted) {
+ yield* Queue.take(retryQueue);
+ failures = [];
+ restartAttempt = 0;
+ yield* Ref.update(state, (current) => ({
+ ...current,
+ status: "starting" as const,
+ hello: Option.none(),
+ lastError: Option.none(),
+ }));
+ yield* publishHealth;
+ continue;
+ }
+
+ const manuallyRetried = yield* Effect.raceFirst(
+ Effect.sleep(restartDelay(restartAttempt)).pipe(Effect.as(false)),
+ Queue.take(retryQueue).pipe(Effect.as(true)),
+ );
+ restartAttempt = manuallyRetried ? 0 : restartAttempt + 1;
+ }
+ }).pipe(
+ Effect.catchCause((cause) =>
+ Cause.hasInterruptsOnly(cause)
+ ? Effect.void
+ : Ref.update(state, (current) => ({
+ ...current,
+ status: "unavailable" as const,
+ hello: Option.none(),
+ lastError: Option.some(nativeTelemetrySupervisorFailureMessage(cause)),
+ })).pipe(
+ Effect.andThen(publishHealth),
+ Effect.andThen(
+ Effect.logWarning("Resource monitor supervisor failed", {
+ cause: Cause.pretty(cause),
+ }),
+ ),
+ ),
+ ),
+ Effect.forkScoped,
+ );
+
+ const applyCollectionControl = Effect.fn(
+ "resourceTelemetry.nativeTelemetryClient.applyCollectionControl",
+ )(function* (previous: CollectionControl, next: CollectionControl) {
+ const current = yield* Ref.get(state);
+ if (canCommandNativeTelemetrySidecar(current.status, Option.isSome(current.handle))) {
+ const handle = Option.getOrThrow(current.handle);
+ if (previous.sampleIntervalMs !== next.sampleIntervalMs) {
+ yield* writeCommand(handle, {
+ version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+ type: "setSampleInterval",
+ sampleIntervalMs: next.sampleIntervalMs,
+ });
+ }
+ const wasStreaming = previous.liveSubscriberCount > 0;
+ const isStreaming = next.liveSubscriberCount > 0;
+ if (wasStreaming !== isStreaming) {
+ yield* writeCommand(handle, {
+ version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+ type: "setStreaming",
+ enabled: isStreaming,
+ });
+ }
+ }
+ });
+
+ const updateCollectionControl = (update: (current: CollectionControl) => CollectionControl) =>
+ controlMutex.withPermits(1)(
+ commitCollectionControlUpdate(
+ collectionControl,
+ appliedCollectionControl,
+ update,
+ applyCollectionControl,
+ ).pipe(Effect.ensuring(publishHealth), Effect.asVoid),
+ );
+
+ const setHostPowerState: NativeTelemetryClient["Service"]["setHostPowerState"] = (hostPower) =>
+ updateCollectionControl((current) => ({
+ ...current,
+ hostPower,
+ sampleIntervalMs: resolveNativeSampleIntervalMs(hostPower, current.liveSubscriberCount),
+ }));
+
+ const changeLiveSubscriberCount = Effect.fn(
+ "resourceTelemetry.nativeTelemetryClient.changeLiveSubscriberCount",
+ )(function* (delta: 1 | -1) {
+ yield* updateCollectionControl((current) => {
+ const liveSubscriberCount = Math.max(0, current.liveSubscriberCount + delta);
+ return {
+ ...current,
+ liveSubscriberCount,
+ sampleIntervalMs: resolveNativeSampleIntervalMs(current.hostPower, liveSubscriberCount),
+ };
+ });
+ });
+
+ const liveSnapshots = Stream.unwrap(
+ Effect.gen(function* () {
+ const subscription = yield* PubSub.subscribe(snapshots);
+ yield* Effect.acquireRelease(changeLiveSubscriberCount(1), () =>
+ changeLiveSubscriberCount(-1).pipe(Effect.ignore),
+ );
+ return Stream.fromSubscription(subscription);
+ }),
+ );
+
+ const setExternalProcesses: NativeTelemetryClient["Service"]["setExternalProcesses"] = (
+ processes,
+ ) =>
+ Effect.gen(function* () {
+ yield* Ref.set(externalProcesses, [...processes]);
+ const current = yield* Ref.get(state);
+ if (!canCommandNativeTelemetrySidecar(current.status, Option.isSome(current.handle))) return;
+ yield* writeCommand(Option.getOrThrow(current.handle), {
+ version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+ type: "setExternalProcesses",
+ processes: [...processes],
+ });
+ });
+
+ const readHistory: NativeTelemetryClient["Service"]["readHistory"] = (windowMs) =>
+ Effect.gen(function* () {
+ const current = yield* Ref.get(state);
+ if (!canCommandNativeTelemetrySidecar(current.status, Option.isSome(current.handle))) {
+ return yield* new NativeTelemetryUnavailable({
+ reason: Option.getOrElse(current.lastError, () => "sidecar is not running"),
+ });
+ }
+ const requestId = yield* crypto.randomUUIDv4.pipe(
+ Effect.mapError(
+ (cause) =>
+ new NativeTelemetryCommandFailed({
+ operation: "createHistoryRequestId",
+ cause,
+ }),
+ ),
+ );
+ const deferred = yield* Deferred.make<
+ ReadonlyArray<ResourceMonitorSnapshotEvent>,
+ NativeTelemetryClientError
+ >();
+ yield* Ref.update(pendingHistories, (pending) => {
+ const next = new Map(pending);
+ next.set(requestId, { deferred, snapshots: [] });
+ return next;
+ });
+ return yield* writeCommand(Option.getOrThrow(current.handle), {
+ version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+ type: "readHistory",
+ requestId,
+ windowMs: Math.max(0, Math.round(windowMs)),
+ }).pipe(
+ Effect.andThen(
+ Deferred.await(deferred).pipe(
+ Effect.timeoutOption(HISTORY_REQUEST_TIMEOUT),
+ Effect.flatMap(
+ Option.match({
+ onNone: () =>
+ Effect.fail(
+ new NativeTelemetryRequestTimedOut({
+ operation: "readHistory",
+ timeoutMs: Duration.toMillis(HISTORY_REQUEST_TIMEOUT),
+ }),
+ ),
+ onSome: Effect.succeed,
+ }),
+ ),
+ ),
+ ),
+ Effect.ensuring(
+ Ref.update(pendingHistories, (pending) => {
+ const next = new Map(pending);
+ next.delete(requestId);
+ return next;
+ }),
+ ),
+ );
+ });
+
+ const sampleNow: NativeTelemetryClient["Service"]["sampleNow"] = Effect.gen(function* () {
+ const current = yield* Ref.get(state);
+ if (!canCommandNativeTelemetrySidecar(current.status, Option.isSome(current.handle))) {
+ return yield* new NativeTelemetryUnavailable({
+ reason: Option.getOrElse(current.lastError, () => "sidecar is not running"),
+ });
+ }
+
+ const requestId = yield* crypto.randomUUIDv4.pipe(
+ Effect.mapError(
+ (cause) =>
+ new NativeTelemetryCommandFailed({
+ operation: "createRequestId",
+ cause,
+ }),
+ ),
+ );
+ const deferred = yield* Deferred.make<NativeTelemetrySnapshot, NativeTelemetryClientError>();
+ yield* Ref.update(pendingSamples, (pending) => {
+ const next = new Map(pending);
+ next.set(requestId, deferred);
+ return next;
+ });
+ return yield* writeCommand(Option.getOrThrow(current.handle), {
+ version: RESOURCE_MONITOR_PROTOCOL_VERSION,
+ type: "sampleNow",
+ requestId,
+ }).pipe(
+ Effect.andThen(
+ Deferred.await(deferred).pipe(
+ Effect.timeoutOption(SAMPLE_REQUEST_TIMEOUT),
+ Effect.flatMap(
+ Option.match({
+ onNone: () =>
+ Effect.fail(
+ new NativeTelemetryRequestTimedOut({
+ operation: "sampleNow",
+ timeoutMs: Duration.toMillis(SAMPLE_REQUEST_TIMEOUT),
+ }),
+ ),
+ onSome: Effect.succeed,
+ }),
+ ),
+ ),
+ ),
+ Effect.ensuring(
+ Ref.update(pendingSamples, (pending) => {
+ const next = new Map(pending);
+ next.delete(requestId);
+ return next;
+ }),
+ ),
+ );
+ });
+
+ const health = currentHealth;
+
+ return NativeTelemetryClient.of({
+ capabilities: Ref.get(state).pipe(
+ Effect.flatMap((current) =>
+ Option.match(current.hello, {
+ onNone: () =>
+ Effect.fail(
+ new NativeTelemetryUnavailable({
+ reason: Option.getOrElse(current.lastError, () => "handshake is incomplete"),
+ }),
+ ),
+ onSome: (hello) => Effect.succeed(hello.capabilities),
+ }),
+ ),
+ ),
+ snapshots: liveSnapshots,
+ readHistory,
+ setExternalProcesses,
+ setHostPowerState,
+ sampleNow,
+ retry: Ref.get(state).pipe(
+ Effect.flatMap((current) =>
+ !canRequestNativeTelemetryRetry(current.status, Option.isSome(current.handle))
+ ? Effect.succeed(false)
+ : Queue.offer(retryQueue, undefined).pipe(Effect.as(true)),
+ ),
+ ),
+ health,
+ subscribeHealth: subscribeBeforeSnapshotWithoutMutex(healthChanges, health),
+ });
+});
+
+export const layer = Layer.effect(NativeTelemetryClient, make());
+
+export const layerTest = (
+ overrides: Partial<NativeTelemetryClient["Service"]> = {},
+): Layer.Layer<NativeTelemetryClient> => {
+ const health =
+ overrides.health ??
+ Effect.succeed({
+ status: "unavailable" as const,
+ hello: Option.none<ResourceMonitorHelloEvent>(),
+ lastSampleAt: Option.none<DateTime.Utc>(),
+ lastError: Option.some("Resource monitor test implementation is unavailable."),
+ restartCount: 0,
+ sampleIntervalMs: UNKNOWN_BACKGROUND_SAMPLE_INTERVAL_MS,
+ });
+ return Layer.succeed(
+ NativeTelemetryClient,
+ NativeTelemetryClient.of({
+ capabilities: Effect.succeed({
+ cumulativeCpuTime: true,
+ currentCpuPercent: true,
+ residentMemory: true,
+ virtualMemory: true,
+ ioBytes: true,
+ processStartTime: true,
+ processTree: true,
+ }),
+ snapshots: Stream.empty,
+ readHistory: () =>
+ Effect.fail(
+ new NativeTelemetryUnavailable({
+ reason: "No resource monitor history was configured for this test.",
+ }),
+ ),
+ setExternalProcesses: () => Effect.void,
+ setHostPowerState: () => Effect.void,
+ sampleNow: Effect.fail(
+ new NativeTelemetryUnavailable({
+ reason: "No resource monitor sample was configured for this test.",
+ }),
+ ),
+ retry: Effect.succeed(false),
+ health,
+ subscribeHealth:
+ overrides.subscribeHealth ??
+ health.pipe(
+ Effect.map((initial) => ({
+ latest: initial,
+ changes: Stream.empty,
+ })),
+ ),
+ ...overrides,
+ }),
+ );
+};
diff --git a/apps/server/src/resourceTelemetry/ResourceAttribution.ts b/apps/server/src/resourceTelemetry/ResourceAttribution.ts
new file mode 100644
index 000000000..374564bb7
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/ResourceAttribution.ts
@@ -0,0 +1,71 @@
+import type { ResourceAttributionEntry, ResourceAttributionSnapshot } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+
+export interface ResourceAttributionRecord {
+ readonly component: string;
+ readonly operation: string;
+ readonly logicalReadBytes?: number;
+ readonly logicalWriteBytes?: number;
+ readonly count?: number;
+ readonly durationMs?: number;
+}
+
+export class ResourceAttribution extends Context.Service<
+ ResourceAttribution,
+ {
+ readonly record: (input: ResourceAttributionRecord) => Effect.Effect<void>;
+ readonly snapshot: Effect.Effect<ResourceAttributionSnapshot>;
+ }
+>()("t3/resourceTelemetry/ResourceAttribution") {}
+
+function key(input: Pick<ResourceAttributionRecord, "component" | "operation">): string {
+ return `${input.component}\u0000${input.operation}`;
+}
+
+function nonNegativeInteger(value: number | undefined, fallback: number): number {
+ if (value === undefined) return fallback;
+ if (!Number.isFinite(value)) return 0;
+ return Math.max(0, Math.round(value));
+}
+
+export const make = Effect.fn("resourceTelemetry.resourceAttribution.make")(function* () {
+ const entries = yield* Ref.make(new Map<string, ResourceAttributionEntry>());
+
+ const record: ResourceAttribution["Service"]["record"] = (input) =>
+ Ref.update(entries, (current) => {
+ const next = new Map(current);
+ const entryKey = key(input);
+ const existing = next.get(entryKey);
+ next.set(entryKey, {
+ component: input.component,
+ operation: input.operation,
+ logicalReadBytes:
+ (existing?.logicalReadBytes ?? 0) + nonNegativeInteger(input.logicalReadBytes, 0),
+ logicalWriteBytes:
+ (existing?.logicalWriteBytes ?? 0) + nonNegativeInteger(input.logicalWriteBytes, 0),
+ count: (existing?.count ?? 0) + nonNegativeInteger(input.count, 1),
+ durationMs: (existing?.durationMs ?? 0) + nonNegativeInteger(input.durationMs, 0),
+ });
+ return next;
+ });
+
+ return ResourceAttribution.of({
+ record,
+ snapshot: Effect.gen(function* () {
+ const readAt = yield* DateTime.now;
+ const current = yield* Ref.get(entries);
+ return {
+ readAt,
+ entries: [...current.values()].toSorted(
+ (left, right) => right.logicalWriteBytes - left.logicalWriteBytes,
+ ),
+ };
+ }),
+ });
+});
+
+export const layer = Layer.effect(ResourceAttribution, make());
diff --git a/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts b/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts
new file mode 100644
index 000000000..4c3afa97a
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts
@@ -0,0 +1,124 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import {
+ HostProcessArchitecture,
+ HostProcessEnvironment,
+ HostProcessPlatform,
+} from "@t3tools/shared/hostProcess";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+
+import { ServerConfig } from "../config.ts";
+import * as ResourceMonitorBinary from "./ResourceMonitorBinary.ts";
+
+describe("ResourceMonitorBinary", () => {
+ it.effect("resolves an executable override", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+ prefix: "t3-resource-monitor-binary-",
+ });
+ const binaryPath = `${baseDir}/t3-resource-monitor`;
+ yield* fileSystem.writeFileString(binaryPath, "binary");
+ yield* fileSystem.chmod(binaryPath, 0o755);
+
+ const service = yield* ResourceMonitorBinary.make().pipe(
+ Effect.provide(ServerConfig.layerTest(process.cwd(), baseDir)),
+ Effect.provideService(HostProcessPlatform, "linux"),
+ Effect.provideService(HostProcessArchitecture, "x64"),
+ Effect.provideService(ResourceMonitorBinary.ResourceMonitorHostLinuxLibc, "musl"),
+ Effect.provideService(HostProcessEnvironment, {
+ T3CODE_RESOURCE_MONITOR_PATH: binaryPath,
+ }),
+ );
+
+ assert.equal(yield* service.resolve, binaryPath);
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+ );
+
+ it.effect("resolves an executable override on an unsupported platform", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+ prefix: "t3-resource-monitor-binary-",
+ });
+ const binaryPath = `${baseDir}/custom-resource-monitor`;
+ yield* fileSystem.writeFileString(binaryPath, "binary");
+ yield* fileSystem.chmod(binaryPath, 0o755);
+
+ const service = yield* ResourceMonitorBinary.make().pipe(
+ Effect.provide(ServerConfig.layerTest(process.cwd(), baseDir)),
+ Effect.provideService(HostProcessPlatform, "freebsd"),
+ Effect.provideService(HostProcessArchitecture, "ia32"),
+ Effect.provideService(HostProcessEnvironment, {
+ T3CODE_RESOURCE_MONITOR_PATH: binaryPath,
+ }),
+ );
+
+ assert.equal(yield* service.resolve, binaryPath);
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+ );
+
+ it.effect("rejects a non-executable POSIX override", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+ prefix: "t3-resource-monitor-binary-",
+ });
+ const binaryPath = `${baseDir}/t3-resource-monitor`;
+ yield* fileSystem.writeFileString(binaryPath, "binary");
+ yield* fileSystem.chmod(binaryPath, 0o644);
+
+ const service = yield* ResourceMonitorBinary.make().pipe(
+ Effect.provide(ServerConfig.layerTest(process.cwd(), baseDir)),
+ Effect.provideService(HostProcessPlatform, "linux"),
+ Effect.provideService(HostProcessArchitecture, "x64"),
+ Effect.provideService(ResourceMonitorBinary.ResourceMonitorHostLinuxLibc, "gnu"),
+ Effect.provideService(HostProcessEnvironment, {
+ T3CODE_RESOURCE_MONITOR_PATH: binaryPath,
+ }),
+ );
+ const error = yield* Effect.flip(service.resolve);
+
+ assert.instanceOf(error, ResourceMonitorBinary.ResourceMonitorBinaryNotExecutable);
+ assert.equal(error.path, binaryPath);
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+ );
+
+ it.effect("rejects unsupported platform and architecture pairs", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+ prefix: "t3-resource-monitor-binary-",
+ });
+ const service = yield* ResourceMonitorBinary.make().pipe(
+ Effect.provide(ServerConfig.layerTest(process.cwd(), baseDir)),
+ Effect.provideService(HostProcessPlatform, "freebsd"),
+ Effect.provideService(HostProcessArchitecture, "ia32"),
+ Effect.provideService(HostProcessEnvironment, {}),
+ );
+ const error = yield* Effect.flip(service.resolve);
+
+ assert.instanceOf(error, ResourceMonitorBinary.ResourceMonitorBinaryUnsupported);
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+ );
+
+ it.effect("rejects bundled glibc binaries on musl Linux hosts", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+ prefix: "t3-resource-monitor-binary-",
+ });
+ const service = yield* ResourceMonitorBinary.make().pipe(
+ Effect.provide(ServerConfig.layerTest(process.cwd(), baseDir)),
+ Effect.provideService(HostProcessPlatform, "linux"),
+ Effect.provideService(HostProcessArchitecture, "x64"),
+ Effect.provideService(ResourceMonitorBinary.ResourceMonitorHostLinuxLibc, "musl"),
+ Effect.provideService(HostProcessEnvironment, {}),
+ );
+ const error = yield* Effect.flip(service.resolve);
+
+ assert.instanceOf(error, ResourceMonitorBinary.ResourceMonitorBinaryUnsupported);
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+ );
+});
diff --git a/apps/server/src/resourceTelemetry/ResourceMonitorBinary.ts b/apps/server/src/resourceTelemetry/ResourceMonitorBinary.ts
new file mode 100644
index 000000000..1f14df518
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/ResourceMonitorBinary.ts
@@ -0,0 +1,226 @@
+import {
+ HostProcessArchitecture,
+ HostProcessEnvironment,
+ HostProcessPlatform,
+} from "@t3tools/shared/hostProcess";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+import { ServerConfig } from "../config.ts";
+
+export class ResourceMonitorBinaryUnsupported extends Schema.TaggedErrorClass<ResourceMonitorBinaryUnsupported>()(
+ "ResourceMonitorBinaryUnsupported",
+ {
+ platform: Schema.String,
+ architecture: Schema.String,
+ },
+) {
+ override get message(): string {
+ return `Resource monitoring is unsupported on ${this.platform}/${this.architecture}.`;
+ }
+}
+
+export class ResourceMonitorBinaryNotFound extends Schema.TaggedErrorClass<ResourceMonitorBinaryNotFound>()(
+ "ResourceMonitorBinaryNotFound",
+ {
+ platform: Schema.String,
+ architecture: Schema.String,
+ candidates: Schema.Array(Schema.String),
+ },
+) {
+ override get message(): string {
+ return `Resource monitor binary was not found for ${this.platform}/${this.architecture}.`;
+ }
+}
+
+export class ResourceMonitorBinaryNotExecutable extends Schema.TaggedErrorClass<ResourceMonitorBinaryNotExecutable>()(
+ "ResourceMonitorBinaryNotExecutable",
+ {
+ path: Schema.String,
+ mode: Schema.Number,
+ },
+) {
+ override get message(): string {
+ return `Resource monitor binary at '${this.path}' is not executable.`;
+ }
+}
+
+export type ResourceMonitorBinaryError =
+ | ResourceMonitorBinaryUnsupported
+ | ResourceMonitorBinaryNotFound
+ | ResourceMonitorBinaryNotExecutable;
+
+export class ResourceMonitorBinary extends Context.Service<
+ ResourceMonitorBinary,
+ {
+ readonly resolve: Effect.Effect<string, ResourceMonitorBinaryError>;
+ }
+>()("t3/resourceTelemetry/ResourceMonitorBinary") {}
+
+function binaryName(platform: NodeJS.Platform): string {
+ return platform === "win32" ? "t3-resource-monitor.exe" : "t3-resource-monitor";
+}
+
+export type ResourceMonitorLinuxLibc = "gnu" | "musl";
+
+function detectResourceMonitorLinuxLibc(): ResourceMonitorLinuxLibc {
+ try {
+ const report = process.report?.getReport() as
+ | {
+ readonly header?: {
+ readonly glibcVersionRuntime?: unknown;
+ };
+ }
+ | undefined;
+ return typeof report?.header?.glibcVersionRuntime === "string" ? "gnu" : "musl";
+ } catch {
+ return "musl";
+ }
+}
+
+export const ResourceMonitorHostLinuxLibc = Context.Reference<ResourceMonitorLinuxLibc>(
+ "t3/resourceTelemetry/ResourceMonitorHostLinuxLibc",
+ {
+ defaultValue: detectResourceMonitorLinuxLibc,
+ },
+);
+
+export function resourceMonitorPlatformKey(
+ platform: NodeJS.Platform,
+ architecture: NodeJS.Architecture,
+): string | undefined {
+ if (
+ (platform !== "darwin" && platform !== "linux" && platform !== "win32") ||
+ (architecture !== "arm64" && architecture !== "x64")
+ ) {
+ return undefined;
+ }
+ return `${platform}-${architecture}`;
+}
+
+export function resourceMonitorRustTarget(
+ platform: NodeJS.Platform,
+ architecture: NodeJS.Architecture,
+ linuxLibc: ResourceMonitorLinuxLibc,
+): string | undefined {
+ if (platform === "darwin") {
+ return architecture === "arm64"
+ ? "aarch64-apple-darwin"
+ : architecture === "x64"
+ ? "x86_64-apple-darwin"
+ : undefined;
+ }
+ if (platform === "linux") {
+ if (linuxLibc !== "gnu") {
+ return undefined;
+ }
+ return architecture === "arm64"
+ ? "aarch64-unknown-linux-gnu"
+ : architecture === "x64"
+ ? "x86_64-unknown-linux-gnu"
+ : undefined;
+ }
+ if (platform === "win32") {
+ return architecture === "arm64"
+ ? "aarch64-pc-windows-msvc"
+ : architecture === "x64"
+ ? "x86_64-pc-windows-msvc"
+ : undefined;
+ }
+ return undefined;
+}
+
+export const make = Effect.fn("resourceTelemetry.resourceMonitorBinary.make")(function* () {
+ const config = yield* ServerConfig;
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const platform = yield* HostProcessPlatform;
+ const architecture = yield* HostProcessArchitecture;
+ const environment = yield* HostProcessEnvironment;
+ const linuxLibc = yield* ResourceMonitorHostLinuxLibc;
+ const executableName = binaryName(platform);
+ const platformKey = resourceMonitorPlatformKey(platform, architecture);
+ const rustTarget = resourceMonitorRustTarget(platform, architecture, linuxLibc);
+ const overrideCandidates = [
+ environment.T3CODE_RESOURCE_MONITOR_PATH,
+ config.resourceMonitorPath,
+ ].filter((candidate): candidate is string => Boolean(candidate));
+ const bundledCandidates =
+ platformKey === undefined || rustTarget === undefined
+ ? []
+ : [
+ path.resolve(import.meta.dirname, "resource-monitor", platformKey, executableName),
+ path.resolve(import.meta.dirname, "resource-monitor", executableName),
+ path.resolve(import.meta.dirname, "../resource-monitor", executableName),
+ path.resolve(
+ import.meta.dirname,
+ "../../../../native/resource-monitor/target",
+ rustTarget,
+ "release",
+ executableName,
+ ),
+ path.resolve(
+ import.meta.dirname,
+ "../../../native/resource-monitor/target",
+ rustTarget,
+ "release",
+ executableName,
+ ),
+ path.resolve(
+ import.meta.dirname,
+ "../../../../native/resource-monitor/target/release",
+ executableName,
+ ),
+ path.resolve(
+ import.meta.dirname,
+ "../../../../native/resource-monitor/target/debug",
+ executableName,
+ ),
+ ];
+ if (overrideCandidates.length === 0 && bundledCandidates.length === 0) {
+ return ResourceMonitorBinary.of({
+ resolve: Effect.fail(
+ new ResourceMonitorBinaryUnsupported({
+ platform,
+ architecture,
+ }),
+ ),
+ });
+ }
+
+ const candidates = [...overrideCandidates, ...bundledCandidates];
+
+ const resolve: ResourceMonitorBinary["Service"]["resolve"] = Effect.gen(function* () {
+ for (const candidate of candidates) {
+ const exists = yield* fileSystem.exists(candidate).pipe(Effect.orElseSucceed(() => false));
+ if (!exists) continue;
+
+ if (platform !== "win32") {
+ const stat = yield* fileSystem.stat(candidate).pipe(Effect.option);
+ if (Option.isSome(stat) && (stat.value.mode & 0o111) === 0) {
+ return yield* new ResourceMonitorBinaryNotExecutable({
+ path: candidate,
+ mode: stat.value.mode,
+ });
+ }
+ }
+
+ return candidate;
+ }
+
+ return yield* new ResourceMonitorBinaryNotFound({
+ platform,
+ architecture,
+ candidates,
+ });
+ });
+
+ return ResourceMonitorBinary.of({ resolve });
+});
+
+export const layer = Layer.effect(ResourceMonitorBinary, make());
diff --git a/apps/server/src/resourceTelemetry/ResourceTelemetry.test.ts b/apps/server/src/resourceTelemetry/ResourceTelemetry.test.ts
new file mode 100644
index 000000000..a96423607
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/ResourceTelemetry.test.ts
@@ -0,0 +1,647 @@
+import type {
+ DesktopHostTelemetrySnapshot,
+ ResourceMonitorProcessSample,
+ ResourceMonitorSnapshotEvent,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
+
+import * as DesktopTelemetryReceiver from "./DesktopTelemetryReceiver.ts";
+import * as NativeTelemetryClient from "./NativeTelemetryClient.ts";
+import * as ResourceAttribution from "./ResourceAttribution.ts";
+import * as ResourceTelemetry from "./ResourceTelemetry.ts";
+
+function processSample(
+ input: Partial<ResourceMonitorProcessSample> &
+ Pick<ResourceMonitorProcessSample, "pid" | "ppid" | "startTimeMs">,
+): ResourceMonitorProcessSample {
+ return {
+ runTimeMs: 1_000,
+ name: `process-${input.pid}`,
+ command: `process-${input.pid}`,
+ status: "Running",
+ cpuPercent: 0,
+ cpuTimeMs: 0,
+ residentBytes: 1_024,
+ virtualBytes: 2_048,
+ ioReadBytes: 0,
+ ioWriteBytes: 0,
+ ioSemantics: "storage",
+ ...input,
+ };
+}
+
+function nativeSnapshot(input: {
+ readonly sequence: number;
+ readonly sampledAtUnixMs: number;
+ readonly childCpuTimeMs: number;
+ readonly childWriteBytes: number;
+ readonly externalProcesses?: ResourceMonitorSnapshotEvent["externalProcesses"];
+}): ResourceMonitorSnapshotEvent {
+ const processes = [
+ processSample({
+ pid: process.pid,
+ ppid: 1,
+ startTimeMs: 100,
+ cpuTimeMs: input.sequence * 10,
+ }),
+ processSample({
+ pid: 4_242,
+ ppid: process.pid,
+ startTimeMs: 200,
+ name: "codex",
+ command: "codex app-server",
+ cpuTimeMs: input.childCpuTimeMs,
+ ioWriteBytes: input.childWriteBytes,
+ }),
+ processSample({
+ pid: 5_000,
+ ppid: 1,
+ startTimeMs: 300,
+ name: "electron",
+ command: "electron",
+ cpuTimeMs: input.sequence * 20,
+ }),
+ processSample({
+ pid: 9_000,
+ ppid: process.pid,
+ startTimeMs: 400,
+ name: "t3-resource-monitor",
+ command: "t3-resource-monitor",
+ cpuTimeMs: input.sequence * 5,
+ }),
+ ];
+ return {
+ version: 2,
+ type: "snapshot",
+ sequence: input.sequence,
+ sampledAtUnixMs: input.sampledAtUnixMs,
+ collectionDurationMicros: 300,
+ scannedProcessCount: 80,
+ retainedProcessCount: processes.length,
+ inaccessibleProcessCount: 1,
+ ...(input.externalProcesses === undefined
+ ? {}
+ : { externalProcesses: input.externalProcesses }),
+ processes,
+ };
+}
+
+function nativeGeneration(
+ snapshot: ResourceMonitorSnapshotEvent,
+ generation: number,
+): NativeTelemetryClient.NativeTelemetrySnapshot {
+ return { generation, snapshot };
+}
+
+function desktopSnapshot(sampledAtUnixMs: number): DesktopHostTelemetrySnapshot {
+ const sampledAt = DateTime.makeUnsafe(sampledAtUnixMs);
+ return {
+ version: 1,
+ type: "desktopTelemetry",
+ sequence: 1,
+ sampledAtUnixMs,
+ electronPid: 5_000,
+ power: {
+ source: "electron-main",
+ idle: "false",
+ idleSeconds: 2,
+ locked: "false",
+ suspended: false,
+ onBattery: "true",
+ lowPowerMode: "unknown",
+ thermalState: "fair",
+ stale: false,
+ updatedAt: sampledAt,
+ },
+ speedLimitPercent: Option.some(90),
+ electronProcesses: [
+ {
+ pid: 5_000,
+ creationTimeMs: 300,
+ type: "Browser",
+ name: "electron",
+ cpuPercent: 2,
+ cumulativeCpuSeconds: 0.02,
+ idleWakeupsPerSecond: 3,
+ workingSetBytes: 4_096,
+ peakWorkingSetBytes: 8_192,
+ },
+ ],
+ };
+}
+
+describe("ResourceTelemetry", () => {
+ it.effect("enables live native and Electron collection only while changes are retained", () =>
+ Effect.gen(function* () {
+ const sampledAtUnixMs = DateTime.toEpochMillis(yield* DateTime.now);
+ const sample = nativeSnapshot({
+ sequence: 1,
+ sampledAtUnixMs,
+ childCpuTimeMs: 100,
+ childWriteBytes: 1_000,
+ });
+ const demandChanges = yield* Ref.make<ReadonlyArray<boolean>>([]);
+ const nativeLayer = NativeTelemetryClient.layerTest({
+ sampleNow: Effect.succeed(nativeGeneration(sample, 0)),
+ health: Effect.succeed({
+ status: "healthy",
+ hello: Option.none(),
+ lastSampleAt: Option.none(),
+ lastError: Option.none(),
+ restartCount: 0,
+ sampleIntervalMs: 1_000,
+ }),
+ });
+ const desktopLayer = DesktopTelemetryReceiver.layerTest({
+ latest: Effect.succeedSome(desktopSnapshot(sampledAtUnixMs)),
+ setDiagnosticsDemand: (enabled) =>
+ Ref.update(demandChanges, (changes) => [...changes, enabled]),
+ });
+ const telemetryLayer = ResourceTelemetry.layer.pipe(
+ Layer.provide(Layer.mergeAll(nativeLayer, desktopLayer, ResourceAttribution.layer)),
+ );
+
+ const live = yield* Stream.runHead(
+ Effect.gen(function* () {
+ const telemetry = yield* ResourceTelemetry.ResourceTelemetry;
+ return telemetry.changes;
+ }).pipe(Stream.unwrap),
+ ).pipe(Effect.provide(telemetryLayer));
+
+ expect(Option.isSome(live)).toBe(true);
+ expect(yield* Ref.get(demandChanges)).toEqual([true, false]);
+ }),
+ );
+
+ it.effect("releases live demand when acquisition is interrupted by an idle collector", () =>
+ Effect.gen(function* () {
+ const sampledAtUnixMs = DateTime.toEpochMillis(yield* DateTime.now);
+ const demandChanges = yield* Ref.make<ReadonlyArray<boolean>>([]);
+ const nativeLayer = NativeTelemetryClient.layerTest({
+ sampleNow: Effect.never,
+ health: Effect.succeed({
+ status: "healthy",
+ hello: Option.none(),
+ lastSampleAt: Option.none(),
+ lastError: Option.none(),
+ restartCount: 0,
+ sampleIntervalMs: 1_000,
+ }),
+ });
+ const desktopLayer = DesktopTelemetryReceiver.layerTest({
+ latest: Effect.succeedSome(desktopSnapshot(sampledAtUnixMs)),
+ setDiagnosticsDemand: (enabled) =>
+ Ref.update(demandChanges, (changes) => [...changes, enabled]),
+ });
+ const telemetryLayer = ResourceTelemetry.layer.pipe(
+ Layer.provide(Layer.mergeAll(nativeLayer, desktopLayer, ResourceAttribution.layer)),
+ );
+
+ const resultFiber = yield* Stream.runHead(
+ Effect.gen(function* () {
+ const telemetry = yield* ResourceTelemetry.ResourceTelemetry;
+ return telemetry.changes;
+ }).pipe(Stream.unwrap),
+ ).pipe(Effect.timeoutOption("10 millis"), Effect.provide(telemetryLayer), Effect.forkChild);
+ yield* Effect.yieldNow;
+ yield* TestClock.adjust("10 millis");
+ const result = yield* Fiber.join(resultFiber);
+
+ expect(Option.isNone(result)).toBe(true);
+ expect(yield* Ref.get(demandChanges)).toEqual([true, false]);
+ }),
+ );
+
+ it.effect(
+ "attributes an initial Electron root from the identity recorded by the native snapshot",
+ () =>
+ Effect.gen(function* () {
+ const sampledAtUnixMs = DateTime.toEpochMillis(yield* DateTime.now);
+ const sample = nativeSnapshot({
+ sequence: 1,
+ sampledAtUnixMs,
+ childCpuTimeMs: 100,
+ childWriteBytes: 1_000,
+ externalProcesses: [{ pid: 5_000, startTimeMs: 300 }],
+ });
+ const desktop = {
+ ...desktopSnapshot(sampledAtUnixMs),
+ electronProcesses: [],
+ };
+ const nativeLayer = NativeTelemetryClient.layerTest({
+ sampleNow: Effect.succeed(nativeGeneration(sample, 0)),
+ health: Effect.succeed({
+ status: "healthy",
+ hello: Option.none(),
+ lastSampleAt: Option.none(),
+ lastError: Option.none(),
+ restartCount: 0,
+ sampleIntervalMs: 1_000,
+ }),
+ });
+ const desktopLayer = DesktopTelemetryReceiver.layerTest({
+ latest: Effect.succeedSome(desktop),
+ });
+ const telemetryLayer = ResourceTelemetry.layer.pipe(
+ Layer.provide(Layer.mergeAll(nativeLayer, desktopLayer, ResourceAttribution.layer)),
+ );
+
+ const snapshot = yield* Effect.gen(function* () {
+ const telemetry = yield* ResourceTelemetry.ResourceTelemetry;
+ return yield* telemetry.refresh;
+ }).pipe(Effect.provide(telemetryLayer));
+
+ expect(snapshot.processes.find((entry) => entry.identity.pid === 5_000)?.category).toBe(
+ "electron-main",
+ );
+ expect(snapshot.groups.electron.processStarts).toBe(1);
+ expect(snapshot.groups.backend.processStarts).toBe(3);
+ }),
+ );
+
+ it.effect("rejects buffered snapshots from an earlier sidecar generation", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const startedAt = DateTime.toEpochMillis(yield* DateTime.now);
+ const stale = nativeSnapshot({
+ sequence: 100,
+ sampledAtUnixMs: startedAt + 1_000,
+ childCpuTimeMs: 100,
+ childWriteBytes: 1_000,
+ });
+ const current = nativeSnapshot({
+ sequence: 1,
+ sampledAtUnixMs: startedAt + 2_000,
+ childCpuTimeMs: 200,
+ childWriteBytes: 2_000,
+ });
+ const nativeSnapshots =
+ yield* PubSub.unbounded<NativeTelemetryClient.NativeTelemetrySnapshot>();
+ const nativeLayer = NativeTelemetryClient.layerTest({
+ snapshots: Stream.fromPubSub(nativeSnapshots),
+ sampleNow: Effect.never,
+ health: Effect.succeed({
+ status: "healthy",
+ hello: Option.none(),
+ lastSampleAt: Option.none(),
+ lastError: Option.none(),
+ restartCount: 1,
+ sampleIntervalMs: 1_000,
+ }),
+ });
+ const telemetryLayer = ResourceTelemetry.layer.pipe(
+ Layer.provide(
+ Layer.mergeAll(
+ nativeLayer,
+ DesktopTelemetryReceiver.layerTest(),
+ ResourceAttribution.layer,
+ ),
+ ),
+ );
+
+ yield* Effect.gen(function* () {
+ const telemetry = yield* ResourceTelemetry.ResourceTelemetry;
+ const subscription = yield* telemetry.subscribe;
+ const nextSnapshot = yield* Stream.runHead(subscription.changes).pipe(Effect.forkChild);
+
+ yield* PubSub.publish(nativeSnapshots, nativeGeneration(stale, 0));
+ yield* Effect.yieldNow;
+ expect((yield* telemetry.latest).health.scannedProcessCount).toBe(0);
+
+ yield* PubSub.publish(nativeSnapshots, nativeGeneration(current, 1));
+ const received = yield* Fiber.join(nextSnapshot);
+
+ expect(Option.isSome(received)).toBe(true);
+ expect(DateTime.toEpochMillis(Option.getOrThrow(received).readAt)).toBe(
+ current.sampledAtUnixMs,
+ );
+ }).pipe(Effect.provide(telemetryLayer));
+ }),
+ ),
+ );
+
+ it.effect("retains desktop health changes while aggregate telemetry initializes", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const health = yield* Ref.make<DesktopTelemetryReceiver.DesktopTelemetryReceiverHealth>({
+ status: "starting",
+ lastSampleAt: Option.none(),
+ lastError: Option.none(),
+ });
+ const healthChanges =
+ yield* PubSub.sliding<DesktopTelemetryReceiver.DesktopTelemetryReceiverHealth>(4);
+ const healthSubscribed = yield* Deferred.make<void>();
+ const finishDesktopSnapshot = yield* Deferred.make<void>();
+ const desktopLayer = DesktopTelemetryReceiver.layerTest({
+ health: Ref.get(health),
+ subscribeHealth: Effect.gen(function* () {
+ const subscription = yield* PubSub.subscribe(healthChanges);
+ const latest = yield* Ref.get(health);
+ yield* Deferred.succeed(healthSubscribed, undefined);
+ return {
+ latest,
+ changes: Stream.fromSubscription(subscription),
+ };
+ }),
+ subscribe: Deferred.await(finishDesktopSnapshot).pipe(
+ Effect.as({
+ latest: Option.none(),
+ changes: Stream.empty,
+ }),
+ ),
+ });
+ const telemetryLayer = ResourceTelemetry.layer.pipe(
+ Layer.provide(
+ Layer.mergeAll(
+ NativeTelemetryClient.layerTest(),
+ desktopLayer,
+ ResourceAttribution.layer,
+ ),
+ ),
+ );
+ const resultFiber = yield* Effect.gen(function* () {
+ const telemetry = yield* ResourceTelemetry.ResourceTelemetry;
+ while (true) {
+ const snapshot = yield* telemetry.latest;
+ if (snapshot.health.desktop.status === "degraded") return snapshot;
+ yield* Effect.yieldNow;
+ }
+ }).pipe(Effect.provide(telemetryLayer), Effect.timeout("1 second"), Effect.forkChild);
+
+ yield* Deferred.await(healthSubscribed);
+ const degraded: DesktopTelemetryReceiver.DesktopTelemetryReceiverHealth = {
+ status: "degraded",
+ lastSampleAt: Option.none(),
+ lastError: Option.some("desktop telemetry failed"),
+ };
+ yield* Ref.set(health, degraded);
+ yield* PubSub.publish(healthChanges, degraded);
+ yield* Deferred.succeed(finishDesktopSnapshot, undefined);
+
+ const snapshot = yield* Fiber.join(resultFiber);
+ expect(snapshot.health.desktop.status).toBe("degraded");
+ expect(Option.getOrNull(snapshot.health.desktop.lastError)).toBe(
+ "desktop telemetry failed",
+ );
+ }),
+ ),
+ );
+
+ it.effect("atomically subscribes while a desktop update is being rebuilt", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const startedAt = DateTime.toEpochMillis(yield* DateTime.now);
+ const nextDesktopSnapshot = desktopSnapshot(startedAt + 1_000);
+ const desktopChanges = yield* PubSub.unbounded<DesktopHostTelemetrySnapshot>();
+ const rebuildStarted = yield* Deferred.make<void>();
+ const finishRebuild = yield* Deferred.make<void>();
+ const attributionReads = yield* Ref.make(0);
+ const attributionLayer = Layer.succeed(
+ ResourceAttribution.ResourceAttribution,
+ ResourceAttribution.ResourceAttribution.of({
+ record: () => Effect.void,
+ snapshot: Ref.updateAndGet(attributionReads, (count) => count + 1).pipe(
+ Effect.flatMap((count) =>
+ count === 1
+ ? Effect.void
+ : Deferred.succeed(rebuildStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(finishRebuild)),
+ ),
+ ),
+ Effect.andThen(
+ Effect.succeed({
+ readAt: DateTime.makeUnsafe(startedAt),
+ entries: [],
+ }),
+ ),
+ ),
+ }),
+ );
+ const nativeLayer = NativeTelemetryClient.layerTest({
+ sampleNow: Effect.never,
+ health: Effect.succeed({
+ status: "healthy",
+ hello: Option.none(),
+ lastSampleAt: Option.none(),
+ lastError: Option.none(),
+ restartCount: 0,
+ sampleIntervalMs: 1_000,
+ }),
+ });
+ const desktopLayer = DesktopTelemetryReceiver.layerTest({
+ changes: Stream.fromPubSub(desktopChanges),
+ });
+ const telemetryLayer = ResourceTelemetry.layer.pipe(
+ Layer.provide(Layer.mergeAll(nativeLayer, desktopLayer, attributionLayer)),
+ );
+
+ yield* Effect.gen(function* () {
+ const telemetry = yield* ResourceTelemetry.ResourceTelemetry;
+ yield* Effect.yieldNow;
+ yield* PubSub.publish(desktopChanges, nextDesktopSnapshot);
+ yield* Deferred.await(rebuildStarted);
+
+ const subscriptionFiber = yield* telemetry.subscribe.pipe(Effect.forkChild);
+ yield* Effect.yieldNow;
+ yield* Deferred.succeed(finishRebuild, undefined);
+ const subscription = yield* Fiber.join(subscriptionFiber);
+
+ expect(DateTime.toEpochMillis(subscription.latest.readAt)).toBe(
+ nextDesktopSnapshot.sampledAtUnixMs,
+ );
+ expect(subscription.latest.power).toEqual(nextDesktopSnapshot.power);
+ }).pipe(Effect.provide(telemetryLayer));
+ }),
+ ),
+ );
+
+ it.effect("combines native, Electron, attribution, retry, and history data", () =>
+ Effect.gen(function* () {
+ const startedAt = DateTime.toEpochMillis(yield* DateTime.now);
+ const samples = [
+ nativeSnapshot({
+ sequence: 1,
+ sampledAtUnixMs: startedAt,
+ childCpuTimeMs: 100,
+ childWriteBytes: 1_000,
+ }),
+ nativeSnapshot({
+ sequence: 2,
+ sampledAtUnixMs: startedAt + 1_000,
+ childCpuTimeMs: 350,
+ childWriteBytes: 5_000,
+ }),
+ nativeSnapshot({
+ sequence: 1,
+ sampledAtUnixMs: startedAt + 2_000,
+ childCpuTimeMs: 500,
+ childWriteBytes: 7_000,
+ }),
+ ] as const;
+ const sampleIndex = yield* Ref.make(0);
+ const externalProcesses = yield* Ref.make<
+ ReadonlyArray<{ readonly pid: number; readonly startTimeMs?: number }>
+ >([]);
+ const retryCount = yield* Ref.make(0);
+ const nativeHealth = yield* Ref.make<NativeTelemetryClient.NativeTelemetryClientHealth>({
+ status: "healthy",
+ hello: Option.some({
+ version: 2,
+ type: "hello",
+ sidecarVersion: "0.1.0",
+ sidecarPid: 9_000,
+ platform: "test",
+ arch: "test",
+ capabilities: {
+ cumulativeCpuTime: true,
+ currentCpuPercent: true,
+ residentMemory: true,
+ virtualMemory: true,
+ ioBytes: true,
+ processStartTime: true,
+ processTree: true,
+ },
+ }),
+ lastSampleAt: Option.some(DateTime.makeUnsafe(startedAt)),
+ lastError: Option.none(),
+ restartCount: 2,
+ sampleIntervalMs: 1_000,
+ });
+ const nativeHealthChanges =
+ yield* PubSub.sliding<NativeTelemetryClient.NativeTelemetryClientHealth>(4);
+ const nativeLayer = NativeTelemetryClient.layerTest({
+ setExternalProcesses: (processes) => Ref.set(externalProcesses, processes),
+ readHistory: () => Effect.succeed(samples.slice(0, 2)),
+ sampleNow: Ref.modify(sampleIndex, (index) => {
+ const sampleIndex = Math.min(index, samples.length - 1);
+ return [nativeGeneration(samples[sampleIndex]!, sampleIndex === 2 ? 3 : 2), index + 1];
+ }),
+ retry: Ref.updateAndGet(retryCount, (count) => count + 1).pipe(Effect.as(true)),
+ health: Ref.get(nativeHealth),
+ subscribeHealth: Effect.gen(function* () {
+ const subscription = yield* PubSub.subscribe(nativeHealthChanges);
+ const latest = yield* Ref.get(nativeHealth);
+ return {
+ latest,
+ changes: Stream.fromSubscription(subscription),
+ };
+ }),
+ });
+ const desktopLayer = DesktopTelemetryReceiver.layerTest({
+ latest: Effect.succeedSome(desktopSnapshot(startedAt)),
+ health: Effect.succeed({
+ status: "healthy",
+ lastSampleAt: Option.some(DateTime.makeUnsafe(startedAt)),
+ lastError: Option.none(),
+ }),
+ });
+ const attributionLayer = ResourceAttribution.layer;
+ const dependencies = Layer.mergeAll(nativeLayer, desktopLayer, attributionLayer);
+ const telemetryLayer = ResourceTelemetry.layer.pipe(Layer.provide(dependencies));
+ const layer = Layer.mergeAll(dependencies, telemetryLayer);
+
+ yield* Effect.gen(function* () {
+ const telemetry = yield* ResourceTelemetry.ResourceTelemetry;
+ const attribution = yield* ResourceAttribution.ResourceAttribution;
+
+ expect(yield* Ref.get(externalProcesses)).toEqual([{ pid: 5_000, startTimeMs: 300 }]);
+
+ yield* attribution.record({
+ component: "provider-event-log",
+ operation: "append",
+ logicalWriteBytes: 512,
+ count: 2,
+ durationMs: 4,
+ });
+ const first = yield* telemetry.refresh;
+ expect(first.groups.backend.processCount).toBe(2);
+ expect(first.groups.electron.processCount).toBe(1);
+ expect(first.groups.monitor.processCount).toBe(1);
+ expect(first.power.onBattery).toBe("true");
+ expect(Option.getOrNull(first.speedLimitPercent)).toBe(90);
+ expect(first.attribution.entries).toEqual([
+ {
+ component: "provider-event-log",
+ operation: "append",
+ logicalReadBytes: 0,
+ logicalWriteBytes: 512,
+ count: 2,
+ durationMs: 4,
+ },
+ ]);
+
+ yield* TestClock.adjust(Duration.seconds(1));
+ const second = yield* telemetry.refresh;
+ const codex = second.processes.find((entry) => entry.identity.pid === 4_242);
+ expect(codex?.cpuPercent).toBe(25);
+ expect(codex?.ioWriteBytesPerSecond).toBe(4_000);
+ expect(second.groups.backend.ioWriteBytes).toBe(4_000);
+ expect(second.health.collectionDurationMicros).toBe(300);
+ expect(second.health.scannedProcessCount).toBe(80);
+ expect(second.health.inaccessibleProcessCount).toBe(1);
+
+ const history = yield* telemetry.readHistory({
+ windowMs: 60_000,
+ bucketMs: 10_000,
+ });
+ expect(history.retainedSampleCount).toBeGreaterThan(0);
+ expect(
+ history.topProcesses.find((entry) => entry.identity.pid === 4_242)?.sampleCount,
+ ).toBe(2);
+ expect(history.topProcesses.find((entry) => entry.identity.pid === 4_242)?.cpuTimeMs).toBe(
+ 250,
+ );
+ expect(
+ history.topProcesses.find((entry) => entry.identity.pid === 4_242)?.ioWriteBytes,
+ ).toBe(4_000);
+ expect(history.buckets.reduce((total, bucket) => total + bucket.ioWriteBytes, 0)).toBe(
+ 4_000,
+ );
+
+ const retry = yield* telemetry.retry;
+ expect(retry.accepted).toBe(true);
+ expect(yield* Ref.get(retryCount)).toBe(1);
+
+ yield* Ref.update(nativeHealth, (current) => ({
+ ...current,
+ hello: Option.map(current.hello, (hello) => ({
+ ...hello,
+ sidecarPid: 9_001,
+ })),
+ restartCount: 3,
+ }));
+ yield* TestClock.adjust(Duration.seconds(1));
+ const restarted = yield* telemetry.refresh;
+ expect(DateTime.toEpochMillis(restarted.readAt)).toBe(startedAt + 2_000);
+ expect(Option.getOrNull(restarted.health.sidecarPid)).toBe(9_001);
+
+ yield* Ref.update(nativeHealth, (current) => ({
+ ...current,
+ status: "degraded" as const,
+ lastError: Option.some("collector exited"),
+ }));
+ yield* PubSub.publish(nativeHealthChanges, yield* Ref.get(nativeHealth));
+ yield* Effect.yieldNow;
+ const healthUpdate = yield* telemetry.latest;
+ expect(healthUpdate.health.native.status).toBe("degraded");
+ expect(Option.getOrNull(healthUpdate.health.native.lastError)).toBe("collector exited");
+ const degradedHistory = yield* telemetry.readHistory({
+ windowMs: 60_000,
+ bucketMs: 10_000,
+ });
+ expect(degradedHistory.health.native.status).toBe("degraded");
+ }).pipe(Effect.provide(layer));
+ }),
+ );
+});
diff --git a/apps/server/src/resourceTelemetry/ResourceTelemetry.ts b/apps/server/src/resourceTelemetry/ResourceTelemetry.ts
new file mode 100644
index 000000000..4dd7e721d
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/ResourceTelemetry.ts
@@ -0,0 +1,504 @@
+import type {
+ DesktopHostTelemetrySnapshot,
+ HostPowerSnapshot,
+ ResourceMonitorSnapshotEvent,
+ ResourceTelemetryHealth,
+ ResourceTelemetryHistoryInput,
+ ResourceTelemetryProcessIdentity,
+ ResourceTelemetryRetryResult,
+ ResourceTelemetrySnapshot,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+
+import * as DesktopTelemetryReceiver from "./DesktopTelemetryReceiver.ts";
+import {
+ emptyTelemetryCounters,
+ mergeProcesses,
+ type ProcessState,
+ type TelemetryCounters,
+} from "./Model.ts";
+import * as NativeTelemetryClient from "./NativeTelemetryClient.ts";
+import * as ResourceAttribution from "./ResourceAttribution.ts";
+import {
+ buildResourceTelemetryHistory,
+ normalizeResourceTelemetryHistoryInput,
+ type ResourceTelemetryHistoryWithLegacyBuckets,
+} from "./ResourceTelemetryHistory.ts";
+import { subscribeBeforeSnapshot } from "../utils/subscribeBeforeSnapshot.ts";
+
+export class ResourceTelemetryRefreshFailed extends Schema.TaggedErrorClass<ResourceTelemetryRefreshFailed>()(
+ "ResourceTelemetryRefreshFailed",
+ {
+ operation: Schema.String,
+ cause: Schema.Defect(),
+ },
+) {
+ override get message(): string {
+ return `Resource telemetry operation '${this.operation}' failed.`;
+ }
+}
+
+export class ResourceTelemetry extends Context.Service<
+ ResourceTelemetry,
+ {
+ readonly latest: Effect.Effect<ResourceTelemetrySnapshot>;
+ readonly changes: Stream.Stream<ResourceTelemetrySnapshot>;
+ readonly subscribe: Effect.Effect<
+ {
+ readonly latest: ResourceTelemetrySnapshot;
+ readonly changes: Stream.Stream<ResourceTelemetrySnapshot>;
+ },
+ never,
+ Scope.Scope
+ >;
+ readonly readHistory: (
+ input: ResourceTelemetryHistoryInput,
+ ) => Effect.Effect<ResourceTelemetryHistoryWithLegacyBuckets>;
+ readonly refresh: Effect.Effect<ResourceTelemetrySnapshot, ResourceTelemetryRefreshFailed>;
+ readonly validateProcessIdentity: (
+ identity: ResourceTelemetryProcessIdentity,
+ ) => Effect.Effect<boolean, ResourceTelemetryRefreshFailed>;
+ readonly retry: Effect.Effect<ResourceTelemetryRetryResult>;
+ }
+>()("t3/resourceTelemetry/ResourceTelemetry") {}
+
+interface TelemetryState {
+ readonly nativeSnapshot: Option.Option<ResourceMonitorSnapshotEvent>;
+ readonly desktopSnapshot: Option.Option<DesktopHostTelemetrySnapshot>;
+ readonly previous: ReadonlyMap<string, ProcessState>;
+ readonly counters: TelemetryCounters;
+ readonly latest: ResourceTelemetrySnapshot;
+ readonly lastNativeSequence: number;
+ readonly lastNativeGeneration: number;
+}
+
+interface LiveTelemetryState {
+ readonly retainCount: number;
+ readonly scope: Option.Option<Scope.Closeable>;
+}
+
+function unknownPower(updatedAt: DateTime.Utc): HostPowerSnapshot {
+ return {
+ source: "unknown",
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt,
+ };
+}
+
+function buildHealth(input: {
+ readonly native: NativeTelemetryClient.NativeTelemetryClientHealth;
+ readonly desktop: DesktopTelemetryReceiver.DesktopTelemetryReceiverHealth;
+ readonly nativeSnapshot: Option.Option<ResourceMonitorSnapshotEvent>;
+}): ResourceTelemetryHealth {
+ return {
+ native: {
+ status: input.native.status,
+ lastSampleAt: input.native.lastSampleAt,
+ lastError: input.native.lastError,
+ },
+ desktop: {
+ status: input.desktop.status,
+ lastSampleAt: input.desktop.lastSampleAt,
+ lastError: input.desktop.lastError,
+ },
+ sidecarVersion: Option.map(input.native.hello, (hello) => hello.sidecarVersion),
+ sidecarPid: Option.map(input.native.hello, (hello) => hello.sidecarPid),
+ restartCount: input.native.restartCount,
+ collectionDurationMicros: Option.match(input.nativeSnapshot, {
+ onNone: () => 0,
+ onSome: (snapshot) => snapshot.collectionDurationMicros,
+ }),
+ scannedProcessCount: Option.match(input.nativeSnapshot, {
+ onNone: () => 0,
+ onSome: (snapshot) => snapshot.scannedProcessCount,
+ }),
+ retainedProcessCount: Option.match(input.nativeSnapshot, {
+ onNone: () => 0,
+ onSome: (snapshot) => snapshot.retainedProcessCount,
+ }),
+ inaccessibleProcessCount: Option.match(input.nativeSnapshot, {
+ onNone: () => 0,
+ onSome: (snapshot) => snapshot.inaccessibleProcessCount,
+ }),
+ };
+}
+
+export const make = Effect.fn("resourceTelemetry.resourceTelemetry.make")(function* () {
+ const nativeClient = yield* NativeTelemetryClient.NativeTelemetryClient;
+ const desktopReceiver = yield* DesktopTelemetryReceiver.DesktopTelemetryReceiver;
+ const attribution = yield* ResourceAttribution.ResourceAttribution;
+ const mutex = yield* Semaphore.make(1);
+ const changes = yield* PubSub.sliding<ResourceTelemetrySnapshot>(8);
+ const initialReadAt = yield* DateTime.now;
+ const nativeHealthSubscription = yield* nativeClient.subscribeHealth;
+ const desktopHealthSubscription = yield* desktopReceiver.subscribeHealth;
+ const desktopSubscription = yield* desktopReceiver.subscribe;
+ const initialDesktop = desktopSubscription.latest;
+ if (Option.isSome(initialDesktop)) {
+ const electronRoot = initialDesktop.value.electronProcesses.find(
+ (process) => process.pid === initialDesktop.value.electronPid,
+ );
+ yield* nativeClient
+ .setExternalProcesses([
+ {
+ pid: initialDesktop.value.electronPid,
+ ...(electronRoot === undefined ? {} : { startTimeMs: electronRoot.creationTimeMs }),
+ },
+ ])
+ .pipe(Effect.ignore);
+ yield* nativeClient.setHostPowerState(initialDesktop.value.power).pipe(Effect.ignore);
+ }
+ const initialNativeHealth = nativeHealthSubscription.latest;
+ const initialDesktopHealth = desktopHealthSubscription.latest;
+ const initialAttribution = yield* attribution.snapshot;
+ const initialMerge = mergeProcesses({
+ serverPid: process.pid,
+ sidecarPid: Option.map(initialNativeHealth.hello, (hello) => hello.sidecarPid),
+ fallbackSampledAtMs: DateTime.toEpochMillis(initialReadAt),
+ nativeSnapshot: Option.none(),
+ desktopSnapshot: initialDesktop,
+ previous: new Map(),
+ counters: emptyTelemetryCounters(),
+ updatePrevious: false,
+ });
+ const initialSnapshot: ResourceTelemetrySnapshot = {
+ readAt: initialReadAt,
+ sampleIntervalMs: initialNativeHealth.sampleIntervalMs,
+ processes: initialMerge.processes,
+ groups: initialMerge.groups,
+ power: Option.match(initialDesktop, {
+ onNone: () => unknownPower(initialReadAt),
+ onSome: (desktop) => desktop.power,
+ }),
+ speedLimitPercent: Option.flatMap(initialDesktop, (desktop) => desktop.speedLimitPercent),
+ attribution: initialAttribution,
+ health: buildHealth({
+ native: initialNativeHealth,
+ desktop: initialDesktopHealth,
+ nativeSnapshot: Option.none(),
+ }),
+ };
+ const state = yield* Ref.make<TelemetryState>({
+ nativeSnapshot: Option.none(),
+ desktopSnapshot: initialDesktop,
+ previous: new Map(),
+ counters: emptyTelemetryCounters(),
+ latest: initialSnapshot,
+ lastNativeSequence: 0,
+ lastNativeGeneration: initialNativeHealth.restartCount,
+ });
+ const liveState = yield* Ref.make<LiveTelemetryState>({
+ retainCount: 0,
+ scope: Option.none(),
+ });
+ const liveMutex = yield* Semaphore.make(1);
+ const refreshHealth = mutex.withPermits(1)(
+ Effect.gen(function* () {
+ const current = yield* Ref.get(state);
+ const [nativeHealth, desktopHealth] = yield* Effect.all([
+ nativeClient.health,
+ desktopReceiver.health,
+ ]);
+ const snapshot: ResourceTelemetrySnapshot = {
+ ...current.latest,
+ health: buildHealth({
+ native: nativeHealth,
+ desktop: desktopHealth,
+ nativeSnapshot: current.nativeSnapshot,
+ }),
+ };
+ yield* Ref.set(state, {
+ ...current,
+ latest: snapshot,
+ });
+ if ((yield* Ref.get(liveState)).retainCount > 0) {
+ yield* PubSub.publish(changes, snapshot);
+ }
+ }),
+ );
+
+ const rebuild = (input: {
+ readonly nativeSnapshot?: NativeTelemetryClient.NativeTelemetrySnapshot;
+ readonly desktopSnapshot?: DesktopHostTelemetrySnapshot;
+ readonly updatePrevious: boolean;
+ readonly publishWhenLive?: boolean;
+ }): Effect.Effect<ResourceTelemetrySnapshot> =>
+ mutex.withPermits(1)(
+ Effect.gen(function* () {
+ const current = yield* Ref.get(state);
+ const nativeHealth = yield* nativeClient.health;
+ const incomingNativeSnapshot = input.nativeSnapshot;
+ if (
+ incomingNativeSnapshot &&
+ (incomingNativeSnapshot.generation < nativeHealth.restartCount ||
+ incomingNativeSnapshot.generation < current.lastNativeGeneration ||
+ (incomingNativeSnapshot.generation === current.lastNativeGeneration &&
+ incomingNativeSnapshot.snapshot.sequence <= current.lastNativeSequence))
+ ) {
+ return current.latest;
+ }
+ const nativeSnapshot = incomingNativeSnapshot
+ ? Option.some(incomingNativeSnapshot.snapshot)
+ : current.nativeSnapshot;
+ const desktopSnapshot = input.desktopSnapshot
+ ? Option.some(input.desktopSnapshot)
+ : current.desktopSnapshot;
+ const [desktopHealth, attributionSnapshot] = yield* Effect.all([
+ desktopReceiver.health,
+ attribution.snapshot,
+ ]);
+ const recordedElectronRoots = Option.match(nativeSnapshot, {
+ onNone: () => [],
+ onSome: (snapshot) => snapshot.externalProcesses ?? [],
+ });
+ const electronRootPids = new Set(recordedElectronRoots.map((process) => process.pid));
+ Option.match(desktopSnapshot, {
+ onNone: () => undefined,
+ onSome: (desktop) => electronRootPids.add(desktop.electronPid),
+ });
+ const electronRootStartTimes = new Map(
+ recordedElectronRoots.flatMap((process) =>
+ process.startTimeMs === undefined ? [] : [[process.pid, process.startTimeMs] as const],
+ ),
+ );
+ const merged = mergeProcesses({
+ serverPid: process.pid,
+ sidecarPid: Option.map(nativeHealth.hello, (hello) => hello.sidecarPid),
+ fallbackSampledAtMs: DateTime.toEpochMillis(current.latest.readAt),
+ nativeSnapshot,
+ desktopSnapshot,
+ electronRootPids,
+ electronRootStartTimes,
+ previous: current.previous,
+ counters: current.counters,
+ updatePrevious: input.updatePrevious,
+ });
+ const readAt = DateTime.makeUnsafe(merged.sampledAtMs);
+ const snapshot: ResourceTelemetrySnapshot = {
+ readAt,
+ sampleIntervalMs: nativeHealth.sampleIntervalMs,
+ processes: merged.processes,
+ groups: merged.groups,
+ power: Option.match(desktopSnapshot, {
+ onNone: () => unknownPower(readAt),
+ onSome: (desktop) => desktop.power,
+ }),
+ speedLimitPercent: Option.match(desktopSnapshot, {
+ onNone: () => Option.none(),
+ onSome: (desktop) => desktop.speedLimitPercent,
+ }),
+ attribution: attributionSnapshot,
+ health: buildHealth({
+ native: nativeHealth,
+ desktop: desktopHealth,
+ nativeSnapshot,
+ }),
+ };
+ yield* Ref.set(state, {
+ nativeSnapshot,
+ desktopSnapshot,
+ previous: merged.previous,
+ counters: merged.counters,
+ latest: snapshot,
+ lastNativeSequence:
+ incomingNativeSnapshot?.snapshot.sequence ?? current.lastNativeSequence,
+ lastNativeGeneration: incomingNativeSnapshot?.generation ?? current.lastNativeGeneration,
+ });
+ if (!input.publishWhenLive || (yield* Ref.get(liveState)).retainCount > 0) {
+ yield* PubSub.publish(changes, snapshot);
+ }
+ return snapshot;
+ }),
+ );
+
+ const ingestNative = (snapshot: NativeTelemetryClient.NativeTelemetrySnapshot) =>
+ rebuild({ nativeSnapshot: snapshot, updatePrevious: true });
+ const ingestDesktop = (snapshot: DesktopHostTelemetrySnapshot) =>
+ Effect.gen(function* () {
+ const electronRoot = snapshot.electronProcesses.find(
+ (process) => process.pid === snapshot.electronPid,
+ );
+ yield* nativeClient
+ .setExternalProcesses([
+ {
+ pid: snapshot.electronPid,
+ ...(electronRoot === undefined ? {} : { startTimeMs: electronRoot.creationTimeMs }),
+ },
+ ])
+ .pipe(Effect.ignore);
+ yield* nativeClient.setHostPowerState(snapshot.power).pipe(Effect.ignore);
+ return yield* rebuild({
+ desktopSnapshot: snapshot,
+ updatePrevious: false,
+ publishWhenLive: true,
+ });
+ });
+
+ yield* desktopSubscription.changes.pipe(
+ Stream.runForEach((snapshot) => ingestDesktop(snapshot)),
+ Effect.forkScoped,
+ );
+
+ const acquireLive = liveMutex.withPermits(1)(
+ Effect.uninterruptible(
+ Effect.gen(function* () {
+ const current = yield* Ref.get(liveState);
+ if (current.retainCount > 0) {
+ yield* Ref.set(liveState, { ...current, retainCount: current.retainCount + 1 });
+ return;
+ }
+
+ const scope = yield* Scope.make();
+ yield* desktopReceiver.setDiagnosticsDemand(true).pipe(Effect.ignore);
+ yield* nativeClient.snapshots.pipe(
+ Stream.runForEach(ingestNative),
+ Effect.catch((error) =>
+ Effect.logWarning("Native resource telemetry stream stopped", {
+ cause: error.message,
+ }),
+ ),
+ Effect.forkIn(scope),
+ );
+ yield* nativeClient.sampleNow.pipe(
+ Effect.flatMap(ingestNative),
+ Effect.ignore,
+ Effect.forkIn(scope),
+ );
+ yield* Ref.set(liveState, { retainCount: 1, scope: Option.some(scope) });
+ }),
+ ),
+ );
+
+ const releaseLive = liveMutex.withPermits(1)(
+ Effect.gen(function* () {
+ const current = yield* Ref.get(liveState);
+ if (current.retainCount <= 1) {
+ yield* Ref.set(liveState, { retainCount: 0, scope: Option.none() });
+ if (Option.isSome(current.scope)) {
+ yield* Scope.close(current.scope.value, Exit.void).pipe(Effect.ignore);
+ }
+ yield* desktopReceiver.setDiagnosticsDemand(false).pipe(Effect.ignore);
+ return;
+ }
+ yield* Ref.set(liveState, { ...current, retainCount: current.retainCount - 1 });
+ }),
+ );
+
+ const latest = Ref.get(state).pipe(Effect.map((current) => current.latest));
+ const subscribe = subscribeBeforeSnapshot(
+ changes,
+ Effect.acquireRelease(acquireLive, () => releaseLive).pipe(Effect.andThen(latest)),
+ mutex,
+ );
+ const liveChanges = Stream.unwrap(Effect.map(subscribe, ({ changes }) => changes));
+
+ const readHistory: ResourceTelemetry["Service"]["readHistory"] = (input) =>
+ Effect.gen(function* () {
+ const readAt = yield* DateTime.now;
+ const normalizedInput = normalizeResourceTelemetryHistoryInput(input);
+ const historyResult = yield* Effect.result(
+ nativeClient.readHistory(normalizedInput.windowMs),
+ );
+ if (Result.isFailure(historyResult)) {
+ yield* Effect.logWarning("Failed to read native resource telemetry history", {
+ cause: historyResult.failure.message,
+ });
+ }
+ const [nativeHealth, desktopHealth] = yield* Effect.all([
+ nativeClient.health,
+ desktopReceiver.health,
+ ]);
+ const current = yield* Ref.get(state);
+ return buildResourceTelemetryHistory({
+ readAt,
+ windowMs: normalizedInput.windowMs,
+ bucketMs: normalizedInput.bucketMs,
+ sampleIntervalMs: nativeHealth.sampleIntervalMs,
+ serverPid: process.pid,
+ sidecarPid: Option.map(nativeHealth.hello, (hello) => hello.sidecarPid),
+ desktopSnapshot: current.desktopSnapshot,
+ snapshots: Result.isSuccess(historyResult) ? historyResult.success : [],
+ health: buildHealth({
+ native: nativeHealth,
+ desktop: desktopHealth,
+ nativeSnapshot: current.nativeSnapshot,
+ }),
+ });
+ });
+ yield* nativeHealthSubscription.changes.pipe(
+ Stream.runForEach(() => refreshHealth),
+ Effect.forkScoped,
+ );
+ yield* desktopHealthSubscription.changes.pipe(
+ Stream.runForEach(() => refreshHealth),
+ Effect.forkScoped,
+ );
+
+ const refresh: ResourceTelemetry["Service"]["refresh"] = nativeClient.sampleNow.pipe(
+ Effect.flatMap(ingestNative),
+ Effect.mapError(
+ (cause) =>
+ new ResourceTelemetryRefreshFailed({
+ operation: "refresh",
+ cause,
+ }),
+ ),
+ );
+
+ const validateProcessIdentity: ResourceTelemetry["Service"]["validateProcessIdentity"] = (
+ identity,
+ ) =>
+ nativeClient.sampleNow.pipe(
+ Effect.map(({ snapshot }) =>
+ snapshot.processes.some(
+ (process) => process.pid === identity.pid && process.startTimeMs === identity.startTimeMs,
+ ),
+ ),
+ Effect.mapError(
+ (cause) =>
+ new ResourceTelemetryRefreshFailed({
+ operation: "validateProcessIdentity",
+ cause,
+ }),
+ ),
+ );
+
+ return ResourceTelemetry.of({
+ latest,
+ changes: liveChanges,
+ subscribe,
+ readHistory,
+ refresh,
+ validateProcessIdentity,
+ retry: nativeClient.retry.pipe(
+ Effect.zip(Ref.get(state)),
+ Effect.map(
+ ([accepted, current]): ResourceTelemetryRetryResult => ({
+ accepted,
+ snapshot: current.latest,
+ }),
+ ),
+ ),
+ });
+});
+
+export const layer = Layer.effect(ResourceTelemetry, make());
diff --git a/apps/server/src/resourceTelemetry/ResourceTelemetryHistory.test.ts b/apps/server/src/resourceTelemetry/ResourceTelemetryHistory.test.ts
new file mode 100644
index 000000000..879c83d86
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/ResourceTelemetryHistory.test.ts
@@ -0,0 +1,357 @@
+import type {
+ DesktopHostTelemetrySnapshot,
+ ResourceMonitorProcessSample,
+ ResourceMonitorSnapshotEvent,
+ ResourceTelemetryHealth,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+
+import {
+ buildResourceTelemetryHistory,
+ normalizeResourceTelemetryHistoryInput,
+} from "./ResourceTelemetryHistory.ts";
+
+const SERVER_PID = 100;
+const ELECTRON_PID = 200;
+const CHILD_PID = 300;
+const STARTED_AT_MS = DateTime.toEpochMillis(DateTime.makeUnsafe("2026-06-17T12:00:00.000Z"));
+
+function processSample(
+ input: Partial<ResourceMonitorProcessSample> &
+ Pick<ResourceMonitorProcessSample, "pid" | "ppid" | "startTimeMs">,
+): ResourceMonitorProcessSample {
+ return {
+ runTimeMs: 1_000,
+ name: `process-${input.pid}`,
+ command: `process-${input.pid}`,
+ status: "Running",
+ cpuPercent: 0,
+ cpuTimeMs: 0,
+ residentBytes: 1_024,
+ virtualBytes: 2_048,
+ ioReadBytes: 0,
+ ioWriteBytes: 0,
+ ioSemantics: "storage",
+ ...input,
+ };
+}
+
+function snapshot(
+ sequence: number,
+ sampledAtUnixMs: number,
+ childCpuTimeMs: number,
+ childWriteBytes: number,
+): ResourceMonitorSnapshotEvent {
+ const processes = [
+ processSample({ pid: SERVER_PID, ppid: 1, startTimeMs: 10 }),
+ processSample({
+ pid: ELECTRON_PID,
+ ppid: 1,
+ startTimeMs: 20,
+ name: "electron",
+ command: "electron",
+ }),
+ processSample({
+ pid: CHILD_PID,
+ ppid: SERVER_PID,
+ startTimeMs: 30,
+ name: "codex",
+ command: "codex app-server",
+ cpuTimeMs: childCpuTimeMs,
+ ioWriteBytes: childWriteBytes,
+ }),
+ ];
+ return {
+ version: 2,
+ type: "snapshot",
+ sequence,
+ sampledAtUnixMs,
+ collectionDurationMicros: 100,
+ scannedProcessCount: processes.length,
+ retainedProcessCount: processes.length,
+ inaccessibleProcessCount: 0,
+ processes,
+ };
+}
+
+const health: ResourceTelemetryHealth = {
+ native: {
+ status: "healthy",
+ lastSampleAt: Option.none(),
+ lastError: Option.none(),
+ },
+ desktop: {
+ status: "healthy",
+ lastSampleAt: Option.none(),
+ lastError: Option.none(),
+ },
+ sidecarVersion: Option.some("0.1.0"),
+ sidecarPid: Option.some(400),
+ restartCount: 0,
+ collectionDurationMicros: 100,
+ scannedProcessCount: 3,
+ retainedProcessCount: 3,
+ inaccessibleProcessCount: 0,
+};
+
+function desktopSnapshot(): DesktopHostTelemetrySnapshot {
+ const sampledAt = DateTime.makeUnsafe(STARTED_AT_MS + 1_000);
+ return {
+ version: 1,
+ type: "desktopTelemetry",
+ sequence: 1,
+ sampledAtUnixMs: STARTED_AT_MS + 1_000,
+ electronPid: ELECTRON_PID,
+ power: {
+ source: "electron-main",
+ idle: "false",
+ idleSeconds: 0,
+ locked: "false",
+ suspended: false,
+ onBattery: "false",
+ lowPowerMode: "unknown",
+ thermalState: "nominal",
+ stale: false,
+ updatedAt: sampledAt,
+ },
+ speedLimitPercent: Option.none(),
+ electronProcesses: [
+ {
+ pid: ELECTRON_PID,
+ creationTimeMs: 20,
+ type: "Browser",
+ cpuPercent: 999,
+ idleWakeupsPerSecond: 999,
+ workingSetBytes: 999_999,
+ peakWorkingSetBytes: 999_999,
+ },
+ ],
+ };
+}
+
+describe("buildResourceTelemetryHistory", () => {
+ it("normalizes query bounds before requesting native history", () => {
+ expect(normalizeResourceTelemetryHistoryInput({ windowMs: 0, bucketMs: 0 })).toEqual({
+ windowMs: 1_000,
+ bucketMs: 1_000,
+ });
+ });
+
+ it("replays native snapshots on demand without applying current Electron metrics", () => {
+ const history = buildResourceTelemetryHistory({
+ readAt: DateTime.makeUnsafe(STARTED_AT_MS + 2_000),
+ windowMs: 10_000,
+ bucketMs: 10_000,
+ sampleIntervalMs: 1_000,
+ serverPid: SERVER_PID,
+ sidecarPid: Option.some(400),
+ desktopSnapshot: Option.some(desktopSnapshot()),
+ snapshots: [
+ snapshot(1, STARTED_AT_MS, 100, 1_000),
+ snapshot(2, STARTED_AT_MS + 1_000, 350, 5_000),
+ ],
+ health,
+ });
+
+ const child = history.topProcesses.find((process) => process.identity.pid === CHILD_PID);
+ const electron = history.topProcesses.find((process) => process.identity.pid === ELECTRON_PID);
+ expect(child?.sampleCount).toBe(2);
+ expect(child?.cpuTimeMs).toBe(250);
+ expect(child?.ioWriteBytes).toBe(4_000);
+ expect(electron?.category).toBe("electron-main");
+ expect(electron?.currentRssBytes).toBe(1_024);
+ expect(history.buckets.reduce((total, bucket) => total + bucket.ioWriteBytes, 0)).toBe(4_000);
+ });
+
+ it("uses observed RSS for the history-window peak instead of the lifetime process peak", () => {
+ const first = snapshot(1, STARTED_AT_MS, 100, 1_000);
+ const second = snapshot(2, STARTED_AT_MS + 1_000, 200, 2_000);
+ const history = buildResourceTelemetryHistory({
+ readAt: DateTime.makeUnsafe(STARTED_AT_MS + 2_000),
+ windowMs: 10_000,
+ bucketMs: 10_000,
+ sampleIntervalMs: 1_000,
+ serverPid: SERVER_PID,
+ sidecarPid: Option.none(),
+ desktopSnapshot: Option.none(),
+ snapshots: [
+ {
+ ...first,
+ processes: first.processes.map((process) =>
+ process.pid === CHILD_PID
+ ? { ...process, residentBytes: 2_000, peakResidentBytes: 50_000 }
+ : process,
+ ),
+ },
+ {
+ ...second,
+ processes: second.processes.map((process) =>
+ process.pid === CHILD_PID
+ ? { ...process, residentBytes: 3_000, peakResidentBytes: 60_000 }
+ : process,
+ ),
+ },
+ ],
+ health,
+ });
+
+ expect(
+ history.topProcesses.find((process) => process.identity.pid === CHILD_PID)?.peakRssBytes,
+ ).toBe(3_000);
+ });
+
+ it("retains cumulative baselines while a process is absent from an intermediate sample", () => {
+ const first = snapshot(1, STARTED_AT_MS, 100, 1_000);
+ const absent = snapshot(2, STARTED_AT_MS + 1_000, 0, 0);
+ const returned = snapshot(3, STARTED_AT_MS + 2_000, 350, 5_000);
+ const history = buildResourceTelemetryHistory({
+ readAt: DateTime.makeUnsafe(STARTED_AT_MS + 3_000),
+ windowMs: 10_000,
+ bucketMs: 10_000,
+ sampleIntervalMs: 1_000,
+ serverPid: SERVER_PID,
+ sidecarPid: Option.none(),
+ desktopSnapshot: Option.none(),
+ snapshots: [
+ first,
+ {
+ ...absent,
+ processes: absent.processes.filter((process) => process.pid !== CHILD_PID),
+ },
+ returned,
+ ],
+ health,
+ });
+
+ const child = history.topProcesses.find((process) => process.identity.pid === CHILD_PID);
+ expect(child?.cpuTimeMs).toBe(250);
+ expect(child?.ioWriteBytes).toBe(4_000);
+ });
+
+ it("uses an exact current Electron identity for slightly older native samples", () => {
+ const history = buildResourceTelemetryHistory({
+ readAt: DateTime.makeUnsafe(STARTED_AT_MS + 2_000),
+ windowMs: 10_000,
+ bucketMs: 10_000,
+ sampleIntervalMs: 1_000,
+ serverPid: SERVER_PID,
+ sidecarPid: Option.none(),
+ desktopSnapshot: Option.some(desktopSnapshot()),
+ snapshots: [snapshot(1, STARTED_AT_MS, 100, 1_000)],
+ health,
+ });
+
+ expect(
+ history.topProcesses.find((process) => process.identity.pid === ELECTRON_PID)?.category,
+ ).toBe("electron-main");
+ });
+
+ it("uses the preceding sample as a baseline without attributing pre-window deltas", () => {
+ const readAtMs = STARTED_AT_MS + 10_000;
+ const history = buildResourceTelemetryHistory({
+ readAt: DateTime.makeUnsafe(readAtMs),
+ windowMs: 5_000,
+ bucketMs: 5_000,
+ sampleIntervalMs: 1_000,
+ serverPid: SERVER_PID,
+ sidecarPid: Option.none(),
+ desktopSnapshot: Option.none(),
+ snapshots: [
+ snapshot(1, STARTED_AT_MS, 100, 1_000),
+ snapshot(2, STARTED_AT_MS + 5_000, 600, 6_000),
+ snapshot(3, readAtMs + 1_000, 10_000, 20_000),
+ ],
+ health,
+ });
+
+ const child = history.topProcesses.find((process) => process.identity.pid === CHILD_PID);
+ expect(child?.sampleCount).toBe(1);
+ expect(child?.cpuTimeMs).toBe(0);
+ expect(child?.ioWriteBytes).toBe(0);
+ expect(history.buckets.reduce((total, bucket) => total + bucket.ioWriteBytes, 0)).toBe(0);
+ expect(
+ history.buckets.every((bucket) => DateTime.toEpochMillis(bucket.startedAt) <= readAtMs),
+ ).toBe(true);
+ });
+
+ it("prorates a cumulative delta that crosses the history window boundary", () => {
+ const readAtMs = STARTED_AT_MS + 10_000;
+ const history = buildResourceTelemetryHistory({
+ readAt: DateTime.makeUnsafe(readAtMs),
+ windowMs: 5_000,
+ bucketMs: 5_000,
+ sampleIntervalMs: 1_000,
+ serverPid: SERVER_PID,
+ sidecarPid: Option.none(),
+ desktopSnapshot: Option.none(),
+ snapshots: [
+ snapshot(1, STARTED_AT_MS, 100, 1_000),
+ snapshot(2, STARTED_AT_MS + 7_500, 850, 8_500),
+ ],
+ health,
+ });
+
+ const child = history.topProcesses.find((process) => process.identity.pid === CHILD_PID);
+ expect(child?.cpuTimeMs).toBe(250);
+ expect(child?.ioWriteBytes).toBe(2_500);
+ expect(history.buckets.reduce((total, bucket) => total + bucket.ioWriteBytes, 0)).toBe(2_500);
+ });
+
+ it("replays the Electron root identity recorded with each native sample", () => {
+ const oldElectron = snapshot(1, STARTED_AT_MS, 100, 1_000);
+ const restartedElectron = snapshot(2, STARTED_AT_MS + 1_000, 200, 2_000);
+ const history = buildResourceTelemetryHistory({
+ readAt: DateTime.makeUnsafe(STARTED_AT_MS + 2_000),
+ windowMs: 10_000,
+ bucketMs: 10_000,
+ sampleIntervalMs: 1_000,
+ serverPid: SERVER_PID,
+ sidecarPid: Option.none(),
+ desktopSnapshot: Option.none(),
+ snapshots: [
+ {
+ ...oldElectron,
+ externalProcesses: [{ pid: ELECTRON_PID, startTimeMs: 20 }],
+ },
+ {
+ ...restartedElectron,
+ externalProcesses: [{ pid: 201, startTimeMs: 40 }],
+ processes: [
+ ...restartedElectron.processes.filter((process) => process.pid !== ELECTRON_PID),
+ processSample({
+ pid: ELECTRON_PID,
+ ppid: SERVER_PID,
+ startTimeMs: 999,
+ name: "reused",
+ command: "unrelated process",
+ }),
+ processSample({
+ pid: 201,
+ ppid: 1,
+ startTimeMs: 40,
+ name: "electron",
+ command: "electron",
+ }),
+ ],
+ },
+ ],
+ health,
+ });
+
+ expect(
+ history.topProcesses.find(
+ (process) => process.identity.pid === ELECTRON_PID && process.identity.startTimeMs === 20,
+ )?.category,
+ ).toBe("electron-main");
+ expect(
+ history.topProcesses.find(
+ (process) => process.identity.pid === ELECTRON_PID && process.identity.startTimeMs === 999,
+ )?.category,
+ ).toBe("server-child");
+ expect(history.topProcesses.find((process) => process.identity.pid === 201)?.category).toBe(
+ "electron-main",
+ );
+ });
+});
diff --git a/apps/server/src/resourceTelemetry/ResourceTelemetryHistory.ts b/apps/server/src/resourceTelemetry/ResourceTelemetryHistory.ts
new file mode 100644
index 000000000..737a934de
--- /dev/null
+++ b/apps/server/src/resourceTelemetry/ResourceTelemetryHistory.ts
@@ -0,0 +1,290 @@
+import type {
+ DesktopHostTelemetrySnapshot,
+ ResourceMonitorSnapshotEvent,
+ ResourceTelemetryHealth,
+ ResourceTelemetryHistory,
+ ResourceTelemetryHistoryBucket,
+ ResourceTelemetryProcess,
+ ResourceTelemetryProcessSummary,
+} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+
+import {
+ emptyTelemetryCounters,
+ mergeProcesses,
+ processIdentityKey,
+ type ProcessState,
+ type TelemetryCounters,
+} from "./Model.ts";
+
+const MAX_HISTORY_WINDOW_MS = 60 * 60_000;
+
+export function normalizeResourceTelemetryHistoryInput(input: {
+ readonly windowMs: number;
+ readonly bucketMs: number;
+}): { readonly windowMs: number; readonly bucketMs: number } {
+ const windowMs = Math.max(1_000, Math.min(MAX_HISTORY_WINDOW_MS, input.windowMs));
+ return {
+ windowMs,
+ bucketMs: Math.max(1_000, Math.min(windowMs, input.bucketMs)),
+ };
+}
+
+interface AggregateSample {
+ readonly sampledAtMs: number;
+ readonly cpuPercent: number;
+ readonly rssBytes: number;
+ readonly processCount: number;
+ readonly ioReadBytes: number;
+ readonly ioWriteBytes: number;
+}
+
+interface ProcessSample {
+ readonly sampledAtMs: number;
+ readonly process: ResourceTelemetryProcess;
+ readonly cpuTimeMs: number;
+ readonly ioReadBytes: number;
+ readonly ioWriteBytes: number;
+}
+
+export interface BuildResourceTelemetryHistoryInput {
+ readonly readAt: DateTime.Utc;
+ readonly windowMs: number;
+ readonly bucketMs: number;
+ readonly sampleIntervalMs: number;
+ readonly serverPid: number;
+ readonly sidecarPid: Option.Option<number>;
+ readonly desktopSnapshot: Option.Option<DesktopHostTelemetrySnapshot>;
+ readonly snapshots: ReadonlyArray<ResourceMonitorSnapshotEvent>;
+ readonly health: ResourceTelemetryHealth;
+}
+
+export type ResourceTelemetryHistoryWithLegacyBuckets = ResourceTelemetryHistory & {
+ readonly legacyBackendBuckets?: ReadonlyArray<ResourceTelemetryHistoryBucket>;
+};
+
+function summarizeProcesses(
+ samples: ReadonlyArray<ProcessSample>,
+): ReadonlyArray<ResourceTelemetryProcessSummary> {
+ const groups = new Map<string, ProcessSample[]>();
+ 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): ResourceTelemetryProcessSummary => {
+ 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,
+ firstSeenAt: first.process.firstSeenAt,
+ lastSeenAt: latest.process.lastSeenAt,
+ 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,
+ );
+}
+
+function buildBuckets(input: {
+ readonly samples: ReadonlyArray<AggregateSample>;
+ readonly nowMs: number;
+ readonly windowMs: number;
+ readonly bucketMs: number;
+}): ReadonlyArray<ResourceTelemetryHistoryBucket> {
+ const windowStartMs = input.nowMs - input.windowMs;
+ const buckets: ResourceTelemetryHistoryBucket[] = [];
+ for (let startedAtMs = windowStartMs; 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({
+ startedAt: DateTime.makeUnsafe(startedAtMs),
+ endedAt: DateTime.makeUnsafe(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;
+}
+
+export function buildResourceTelemetryHistory(
+ input: BuildResourceTelemetryHistoryInput,
+): ResourceTelemetryHistoryWithLegacyBuckets & {
+ readonly legacyBackendBuckets: ReadonlyArray<ResourceTelemetryHistoryBucket>;
+} {
+ const readAtMs = DateTime.toEpochMillis(input.readAt);
+ const { windowMs, bucketMs } = normalizeResourceTelemetryHistoryInput(input);
+ const windowStartMs = readAtMs - windowMs;
+ const eligibleSnapshots = input.snapshots
+ .filter((snapshot) => snapshot.sampledAtUnixMs <= readAtMs)
+ .toSorted((left, right) => left.sampledAtUnixMs - right.sampledAtUnixMs);
+ const snapshotsInWindow = eligibleSnapshots.filter(
+ (snapshot) => snapshot.sampledAtUnixMs >= windowStartMs,
+ );
+ const precedingSnapshot = eligibleSnapshots.findLast(
+ (snapshot) => snapshot.sampledAtUnixMs < windowStartMs,
+ );
+ const snapshots = precedingSnapshot
+ ? [precedingSnapshot, ...snapshotsInWindow]
+ : snapshotsInWindow;
+ const aggregateSamples: AggregateSample[] = [];
+ const legacyBackendAggregateSamples: AggregateSample[] = [];
+ const processSamples: ProcessSample[] = [];
+ let previous: ReadonlyMap<string, ProcessState> = new Map();
+ let counters: TelemetryCounters = emptyTelemetryCounters();
+ let previousSnapshotAtMs: number | undefined;
+
+ for (const snapshot of snapshots) {
+ const deltaWindowFraction =
+ previousSnapshotAtMs !== undefined &&
+ previousSnapshotAtMs < windowStartMs &&
+ snapshot.sampledAtUnixMs > previousSnapshotAtMs
+ ? Math.max(
+ 0,
+ Math.min(
+ 1,
+ (snapshot.sampledAtUnixMs - windowStartMs) /
+ (snapshot.sampledAtUnixMs - previousSnapshotAtMs),
+ ),
+ )
+ : 1;
+ previousSnapshotAtMs = snapshot.sampledAtUnixMs;
+ const recordedExternalProcesses =
+ snapshot.externalProcesses ??
+ Option.match(input.desktopSnapshot, {
+ onNone: () => [],
+ onSome: (desktopSnapshot) => [
+ {
+ pid: desktopSnapshot.electronPid,
+ startTimeMs: desktopSnapshot.electronProcesses.find(
+ (metric) => metric.pid === desktopSnapshot.electronPid,
+ )?.creationTimeMs,
+ },
+ ],
+ });
+ const electronRootPids = new Set(recordedExternalProcesses.map((process) => process.pid));
+ const electronRootStartTimes = new Map(
+ recordedExternalProcesses.flatMap((process) =>
+ process.startTimeMs === undefined ? [] : [[process.pid, process.startTimeMs] as const],
+ ),
+ );
+ const merged = mergeProcesses({
+ serverPid: input.serverPid,
+ sidecarPid: input.sidecarPid,
+ fallbackSampledAtMs: snapshot.sampledAtUnixMs,
+ nativeSnapshot: Option.some(snapshot),
+ desktopSnapshot: Option.none(),
+ electronRootPids,
+ electronRootStartTimes,
+ previous,
+ counters,
+ updatePrevious: true,
+ });
+ previous = new Map([...previous, ...merged.previous]);
+ counters = merged.counters;
+ if (snapshot.sampledAtUnixMs < windowStartMs) {
+ continue;
+ }
+ const deltas =
+ deltaWindowFraction === 1
+ ? merged.deltas
+ : merged.deltas.map((delta) => ({
+ ...delta,
+ cpuTimeMs: Math.round(delta.cpuTimeMs * deltaWindowFraction),
+ ioReadBytes: Math.round(delta.ioReadBytes * deltaWindowFraction),
+ ioWriteBytes: Math.round(delta.ioWriteBytes * deltaWindowFraction),
+ }));
+ const deltasByIdentity = new Map(
+ deltas.map((processDelta) => [processDelta.identityKey, processDelta]),
+ );
+ aggregateSamples.push({
+ sampledAtMs: snapshot.sampledAtUnixMs,
+ cpuPercent: merged.groups.allT3.currentCpuPercent,
+ rssBytes: merged.groups.allT3.currentRssBytes,
+ processCount: merged.groups.allT3.processCount,
+ ioReadBytes: deltas.reduce((total, process) => total + process.ioReadBytes, 0),
+ ioWriteBytes: deltas.reduce((total, process) => total + process.ioWriteBytes, 0),
+ });
+ const backendDeltas = deltas.filter(
+ (processDelta) =>
+ processDelta.category === "server" ||
+ processDelta.category === "server-child" ||
+ processDelta.category === "provider-root" ||
+ processDelta.category === "terminal-root",
+ );
+ legacyBackendAggregateSamples.push({
+ sampledAtMs: snapshot.sampledAtUnixMs,
+ cpuPercent: merged.groups.backend.currentCpuPercent,
+ rssBytes: merged.groups.backend.currentRssBytes,
+ processCount: merged.groups.backend.processCount,
+ ioReadBytes: backendDeltas.reduce((total, process) => total + process.ioReadBytes, 0),
+ ioWriteBytes: backendDeltas.reduce((total, process) => total + process.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 {
+ readAt: input.readAt,
+ windowMs,
+ bucketMs,
+ sampleIntervalMs: input.sampleIntervalMs,
+ retainedSampleCount: aggregateSamples.length + processSamples.length,
+ buckets: buildBuckets({ samples: aggregateSamples, nowMs: readAtMs, windowMs, bucketMs }),
+ legacyBackendBuckets: buildBuckets({
+ samples: legacyBackendAggregateSamples,
+ nowMs: readAtMs,
+ windowMs,
+ bucketMs,
+ }),
+ topProcesses: summarizeProcesses(processSamples),
+ health: input.health,
+ };
+}
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index cb68c0bba..0b233d7d9 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -71,6 +71,7 @@ import { vi } from "vite-plus/test";
const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
+import * as BackgroundPolicy from "./background/BackgroundPolicy.ts";
import * as ServerConfig from "./config.ts";
import * as HttpResponseCompression from "./httpCompression/HttpResponseCompression.ts";
import { makeRoutesLayer } from "./server.ts";
@@ -116,6 +117,10 @@ import * as CloudCliTokenManager from "./cloud/CliTokenManager.ts";
import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";
import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";
import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";
+import * as DesktopTelemetryReceiver from "./resourceTelemetry/DesktopTelemetryReceiver.ts";
+import * as NativeTelemetryClient from "./resourceTelemetry/NativeTelemetryClient.ts";
+import * as ResourceAttribution from "./resourceTelemetry/ResourceAttribution.ts";
+import * as ResourceTelemetry from "./resourceTelemetry/ResourceTelemetry.ts";
import * as Data from "effect/Data";
const defaultProjectId = ProjectId.make("project-default");
@@ -355,6 +360,10 @@ const buildAppUnderTest = (options?: {
>;
relayClient?: Partial<RelayClient.RelayClient["Service"]>;
cloudCliTokenManager?: Partial<CloudCliTokenManager.CloudCliTokenManager["Service"]>;
+ nativeTelemetryClient?: Partial<NativeTelemetryClient.NativeTelemetryClient["Service"]>;
+ desktopTelemetryReceiver?: Partial<
+ DesktopTelemetryReceiver.DesktopTelemetryReceiver["Service"]
+ >;
};
}) =>
Effect.gen(function* () {
@@ -531,6 +540,15 @@ const buildAppUnderTest = (options?: {
...options.layers.vcsStatusBroadcaster,
})
: VcsStatusBroadcaster.layer.pipe(Layer.provide(gitWorkflowLayer));
+ const resourceTelemetryLayer = ResourceTelemetry.layer.pipe(
+ Layer.provide(
+ Layer.mergeAll(
+ NativeTelemetryClient.layerTest(options?.layers?.nativeTelemetryClient),
+ DesktopTelemetryReceiver.layerTest(options?.layers?.desktopTelemetryReceiver),
+ ResourceAttribution.layer,
+ ),
+ ),
+ );
const servedRoutesLayer = HttpRouter.serve(makeRoutesLayer, {
disableListenLog: true,
@@ -745,6 +763,7 @@ const buildAppUnderTest = (options?: {
);
const appLayer = servedRoutesLayer.pipe(
+ Layer.provide(resourceTelemetryLayer),
Layer.provide(
Layer.mock(BrowserTraceCollector.BrowserTraceCollector)({
record: () => Effect.void,
@@ -767,6 +786,58 @@ const buildAppUnderTest = (options?: {
...options?.layers?.serverRuntimeStartup,
}),
),
+ Layer.provide(
+ Layer.mock(BackgroundPolicy.BackgroundPolicy)({
+ reportClientActivity: () => Effect.void,
+ removeRpcClient: () => Effect.void,
+ reportHostPowerState: () => Effect.void,
+ snapshot: Effect.succeed({
+ hostPower: {
+ source: "unknown",
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt: TEST_EPOCH,
+ },
+ leases: [],
+ activeForegroundLeaseCount: 0,
+ activeScopeKeys: [],
+ shouldRunOpportunisticWork: false,
+ updatedAt: TEST_EPOCH,
+ }),
+ streamChanges: Stream.empty,
+ subscribe: Effect.succeed({
+ latest: {
+ hostPower: {
+ source: "unknown",
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt: TEST_EPOCH,
+ },
+ leases: [],
+ activeForegroundLeaseCount: 0,
+ activeScopeKeys: [],
+ shouldRunOpportunisticWork: false,
+ updatedAt: TEST_EPOCH,
+ },
+ changes: Stream.empty,
+ }),
+ hasDemand: () => Effect.succeed(false),
+ shouldRunScopeWork: () => Effect.succeed(false),
+ shouldRunOpportunisticWork: Effect.succeed(false),
+ }),
+ ),
Layer.provide(
Layer.mock(ServerEnvironment.ServerEnvironment)({
getEnvironmentId: Effect.succeed(testEnvironmentDescriptor.environmentId),
@@ -4395,6 +4466,23 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
}).pipe(Effect.provide(NodeHttpServer.layerTest)),
);
+ it.effect("routes websocket resource telemetry through the subscription", () =>
+ Effect.gen(function* () {
+ yield* buildAppUnderTest();
+
+ const wsUrl = yield* getWsServerUrl("/ws");
+ const snapshot = yield* Effect.scoped(
+ withWsRpcClient(wsUrl, (client) =>
+ client[WS_METHODS.subscribeResourceTelemetry]({}).pipe(Stream.runHead),
+ ),
+ );
+
+ assertTrue(Option.isSome(snapshot));
+ assert.equal(snapshot.value.processes.length, 0);
+ assert.equal(snapshot.value.groups.backend.processCount, 0);
+ }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+ );
+
it.effect("routes websocket rpc subscribeServerConfig emits provider status updates", () =>
Effect.gen(function* () {
const nextProviders = [
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 0b7c8ccd0..e0d36e99b 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -4,6 +4,8 @@ import * as Layer from "effect/Layer";
import { FetchHttpClient, HttpRouter, HttpServer } from "effect/unstable/http";
import * as HttpApiBuilder from "effect/unstable/httpapi/HttpApiBuilder";
+import * as BackgroundPolicy from "./background/BackgroundPolicy.ts";
+import * as HostPowerMonitor from "./background/HostPowerMonitor.ts";
import * as ServerConfig from "./config.ts";
import * as HttpResponseCompression from "./httpCompression/HttpResponseCompression.ts";
import {
@@ -90,6 +92,11 @@ import * as ServerSelfUpdate from "./cloud/selfUpdate.ts";
import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";
import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";
import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";
+import * as DesktopTelemetryReceiver from "./resourceTelemetry/DesktopTelemetryReceiver.ts";
+import * as NativeTelemetryClient from "./resourceTelemetry/NativeTelemetryClient.ts";
+import * as ResourceAttribution from "./resourceTelemetry/ResourceAttribution.ts";
+import * as ResourceMonitorBinary from "./resourceTelemetry/ResourceMonitorBinary.ts";
+import * as ResourceTelemetry from "./resourceTelemetry/ResourceTelemetry.ts";
import { OrchestrationLayerLive } from "./orchestration/runtimeLayer.ts";
import {
clearPersistedServerRuntimeState,
@@ -106,6 +113,10 @@ import { disableTailscaleServe, ensureTailscaleServe } from "@t3tools/tailscale"
// already closes the websocket gracefully. Do not add an artificial drain before
// those finalizers get a chance to run.
const HTTP_PREEMPTIVE_SHUTDOWN_GRACE_MS = 0;
+const ResourceAttributionLayerLive = ResourceAttribution.layer;
+const ApplicationObservabilityLive = ObservabilityLive.pipe(
+ Layer.provideMerge(ResourceAttributionLayerLive),
+);
const PtyAdapterLive = Layer.unwrap(
Effect.gen(function* () {
@@ -119,6 +130,35 @@ const PtyAdapterLive = Layer.unwrap(
}),
);
+const ServerSettingsLayerLive = ServerSettings.layer.pipe(Layer.provide(ServerSecretStore.layer));
+
+const NativeTelemetryLayerLive = NativeTelemetryClient.layer.pipe(
+ Layer.provide(ResourceMonitorBinary.layer),
+);
+const DesktopTelemetryReceiverLayerLive = DesktopTelemetryReceiver.layer.pipe(
+ Layer.provideMerge(ServerSettingsLayerLive),
+);
+
+const ResourceTelemetryLayerLive = ResourceTelemetry.layer.pipe(
+ Layer.provideMerge(NativeTelemetryLayerLive),
+ Layer.provideMerge(DesktopTelemetryReceiverLayerLive),
+);
+
+const HostPowerMonitorLayerLive = HostPowerMonitor.layer.pipe(
+ Layer.provide(DesktopTelemetryReceiverLayerLive),
+);
+
+const BackgroundLayerLive = BackgroundPolicy.layer.pipe(
+ Layer.provide(HostPowerMonitorLayerLive),
+ Layer.provideMerge(ServerSettingsLayerLive),
+);
+
+const ResourceDiagnosticsLayerLive = Layer.mergeAll(
+ ResourceTelemetryLayerLive,
+ ProcessDiagnostics.layer.pipe(Layer.provide(ResourceTelemetryLayerLive)),
+ ProcessResourceMonitor.layer.pipe(Layer.provide(ResourceTelemetryLayerLive)),
+);
+
const RelayClientLive = Layer.unwrap(
Effect.gen(function* () {
const config = yield* ServerConfig.ServerConfig;
@@ -184,7 +224,7 @@ const ProviderSessionDirectoryLayerLive = ProviderSessionDirectoryLive.pipe(
// `ProviderAdapterRegistryLive` is now a facade that resolves kind → adapter
// by looking up the default `ProviderInstance` per driver in the instance
// registry. Adapter construction itself moved inside each driver's
-// `create()`; `ProviderEventLoggersLive` owns the shared native/canonical
+// `create()`; `ProviderEventLoggers.layer` owns the shared native/canonical
// NDJSON writers and is provided at the outer runtime layer so both
// `ProviderService` and the per-instance drivers read the same logger pair.
const ProviderLayerLive = ProviderServiceLive.pipe(
@@ -298,6 +338,7 @@ const ProviderRuntimeLayerLive = ProviderSessionReaperLive.pipe(
const RuntimeCoreDependenciesLive = ReactorLayerLive.pipe(
// Core Services
+ Layer.provideMerge(ServerSettingsLayerLive),
Layer.provideMerge(CheckpointingLayerLive),
Layer.provideMerge(SourceControlProviderRegistryLayerLive),
Layer.provideMerge(GitLayerLive),
@@ -318,14 +359,13 @@ const RuntimeCoreDependenciesLive = ReactorLayerLive.pipe(
// `ProviderService` (canonical stream, written after event normalization).
// Provided once at the runtime level so every consumer sees the same
// logger instances.
- Layer.provideMerge(ProviderEventLoggers.ProviderEventLoggersLive),
+ Layer.provideMerge(ProviderEventLoggers.layer),
// `OpenCodeDriver.create()` yields `OpenCodeRuntime`; previously the old
// `ProviderRegistryLive` pulled `OpenCodeRuntimeLive` in for itself, but
// the rewritten registry reads snapshots off the instance registry and
// no longer transitively provides it. Exposing it at the runtime level
// keeps a single Live for all opencode consumers.
Layer.provideMerge(OpenCodeRuntime.OpenCodeRuntimeLive),
- Layer.provideMerge(ServerSettings.layer.pipe(Layer.provide(ServerSecretStore.layer))),
Layer.provideMerge(WorkspaceLayerLive),
Layer.provideMerge(ProjectFaviconResolverLayerLive),
Layer.provideMerge(RepositoryIdentityResolver.layer),
@@ -345,8 +385,8 @@ const RuntimeCoreDependenciesLive = ReactorLayerLive.pipe(
const RuntimeDependenciesLive = RuntimeCoreDependenciesLive.pipe(
// Misc.
- Layer.provideMerge(ProcessDiagnostics.layer),
- Layer.provideMerge(ProcessResourceMonitor.layer),
+ Layer.provideMerge(BackgroundLayerLive),
+ Layer.provideMerge(ResourceDiagnosticsLayerLive),
Layer.provideMerge(TraceDiagnostics.layer),
Layer.provideMerge(AnalyticsService.layer),
Layer.provideMerge(ExternalLauncher.layer),
@@ -522,7 +562,7 @@ export const makeServerLayer = Layer.unwrap(
Layer.provideMerge(serverRelayBrokerTracingLayer),
Layer.provideMerge(HttpResponseCompressionLive),
Layer.provideMerge(HttpServerLive),
- Layer.provide(ObservabilityLive),
+ Layer.provide(ApplicationObservabilityLive),
Layer.provideMerge(FetchHttpClient.layer),
Layer.provideMerge(VcsProcess.layer),
Layer.provideMerge(PlatformServicesLive),
diff --git a/apps/server/src/serverSettings.test.ts b/apps/server/src/serverSettings.test.ts
index 50ca810a9..d38a30649 100644
--- a/apps/server/src/serverSettings.test.ts
+++ b/apps/server/src/serverSettings.test.ts
@@ -12,8 +12,10 @@ import * as Effect from "effect/Effect";
import * as Duration from "effect/Duration";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
import * as PlatformError from "effect/PlatformError";
import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
import * as ServerSecretStore from "./auth/ServerSecretStore.ts";
import * as ServerConfig from "./config.ts";
import * as ServerSettingsModule from "./serverSettings.ts";
@@ -203,6 +205,29 @@ it.layer(NodeServices.layer)("server settings", (it) => {
}).pipe(Effect.provide(makeServerSettingsLayer())),
);
+ it.effect("buffers changes after a subscription is acquired but before it is consumed", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const serverSettings = yield* ServerSettingsModule.ServerSettingsService;
+ const changes = yield* serverSettings.subscribeChanges;
+
+ yield* serverSettings.updateSettings({
+ providers: {
+ codex: {
+ binaryPath: "/usr/local/bin/codex-next",
+ },
+ },
+ });
+
+ const firstChange = yield* changes.pipe(Stream.runHead, Effect.timeout("1 second"));
+ assert.equal(
+ Option.getOrUndefined(firstChange)?.providers.codex.binaryPath,
+ "/usr/local/bin/codex-next",
+ );
+ }),
+ ).pipe(Effect.provide(makeServerSettingsLayer())),
+ );
+
it.effect("preserves model when switching providers via textGenerationModelSelection", () =>
Effect.gen(function* () {
const serverSettings = yield* ServerSettingsModule.ServerSettingsService;
@@ -590,6 +615,14 @@ it.layer(NodeServices.layer)("server settings", (it) => {
serverPassword: "secret-password",
},
},
+ backgroundActivity: {
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "balanced",
+ overrides: {
+ automaticGitFetchInterval: 10_000,
+ },
+ },
automaticGitFetchInterval: 10_000,
});
}).pipe(Effect.provide(makeServerSettingsLayer())),
diff --git a/apps/server/src/serverSettings.ts b/apps/server/src/serverSettings.ts
index 82fd2f29f..2798faf6f 100644
--- a/apps/server/src/serverSettings.ts
+++ b/apps/server/src/serverSettings.ts
@@ -131,6 +131,13 @@ export class ServerSettingsService extends Context.Service<
/** Stream of settings change events. */
readonly streamChanges: Stream.Stream<ServerSettings>;
+
+ /**
+ * Acquire a settings change subscription synchronously in the current
+ * fiber. Use this before reading a snapshot when changes between the
+ * snapshot and a lazily started stream must not be lost.
+ */
+ readonly subscribeChanges: Effect.Effect<Stream.Stream<ServerSettings>, never, Scope.Scope>;
}
>()("t3/serverSettings/ServerSettingsService") {
/** @deprecated Import and use `layerTest` from this module. */
@@ -139,13 +146,17 @@ export class ServerSettingsService extends Context.Service<
const makeTest = (overrides: DeepPartial<ServerSettings> = {}) =>
Effect.gen(function* () {
- const { automaticGitFetchInterval, ...overridesForMerge } = overrides;
+ const { automaticGitFetchInterval, providerHealthRefreshInterval, ...overridesForMerge } =
+ overrides;
const merged = deepMerge(DEFAULT_SERVER_SETTINGS, overridesForMerge);
const initialSettings = yield* normalizeServerSettings({
...merged,
...(automaticGitFetchInterval !== undefined
? { automaticGitFetchInterval: automaticGitFetchInterval as Duration.Duration }
: {}),
+ ...(providerHealthRefreshInterval !== undefined
+ ? { providerHealthRefreshInterval: providerHealthRefreshInterval as Duration.Duration }
+ : {}),
});
const currentSettingsRef = yield* Ref.make<ServerSettings>(initialSettings);
@@ -161,6 +172,7 @@ const makeTest = (overrides: DeepPartial<ServerSettings> = {}) =>
Effect.map(resolveTextGenerationProvider),
),
streamChanges: Stream.empty,
+ subscribeChanges: Effect.succeed(Stream.empty),
} satisfies ServerSettingsService["Service"];
});
@@ -197,7 +209,9 @@ function fallbackTextGenerationProvider(settings: ServerSettings): ServerSetting
// Values under these keys are compared as a whole — never stripped field-by-field.
const ATOMIC_SETTINGS_KEYS: ReadonlySet<string> = new Set([
+ "backgroundActivity",
"automaticGitFetchInterval",
+ "providerHealthRefreshInterval",
"sourceControlWriterModelSelection",
"textGenerationModelSelection",
]);
@@ -344,6 +358,23 @@ const make = Effect.gen(function* () {
};
});
+ const materializeChanges = (changes: Stream.Stream<ServerSettings>) =>
+ changes.pipe(
+ Stream.mapEffect((settings) =>
+ materializeProviderEnvironmentSecrets(settings).pipe(
+ Effect.catch((error: ServerSettingsError) =>
+ Effect.logWarning("failed to materialize provider environment secrets", {
+ operation: error.operation,
+ providerInstanceId: error.providerInstanceId,
+ environmentVariable: error.environmentVariable,
+ cause: error.cause,
+ }).pipe(Effect.as(settings)),
+ ),
+ ),
+ ),
+ Stream.map(resolveTextGenerationProvider),
+ );
+
const persistProviderEnvironmentSecrets = (
current: ServerSettings,
next: ServerSettings,
@@ -561,20 +592,11 @@ const make = Effect.gen(function* () {
}),
),
get streamChanges() {
- return Stream.fromPubSub(changesPubSub).pipe(
- Stream.mapEffect((settings) =>
- materializeProviderEnvironmentSecrets(settings).pipe(
- Effect.catch((error: ServerSettingsError) =>
- Effect.logWarning("failed to materialize provider environment secrets", {
- operation: error.operation,
- providerInstanceId: error.providerInstanceId,
- environmentVariable: error.environmentVariable,
- cause: error.cause,
- }).pipe(Effect.as(settings)),
- ),
- ),
- ),
- Stream.map(resolveTextGenerationProvider),
+ return materializeChanges(Stream.fromPubSub(changesPubSub));
+ },
+ get subscribeChanges() {
+ return PubSub.subscribe(changesPubSub).pipe(
+ Effect.map((subscription) => materializeChanges(Stream.fromSubscription(subscription))),
);
},
} satisfies ServerSettingsService["Service"];
diff --git a/apps/server/src/utils/subscribeBeforeSnapshot.test.ts b/apps/server/src/utils/subscribeBeforeSnapshot.test.ts
new file mode 100644
index 000000000..70f0beda2
--- /dev/null
+++ b/apps/server/src/utils/subscribeBeforeSnapshot.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+
+import {
+ subscribeBeforeSnapshot,
+ subscribeBeforeSnapshotWithoutMutex,
+} from "./subscribeBeforeSnapshot.ts";
+
+describe("subscribeBeforeSnapshot", () => {
+ it.effect("atomically reads the initial snapshot before receiving later changes", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const changes = yield* PubSub.sliding<number>(1);
+ const latest = yield* Ref.make(1);
+ const mutex = yield* Semaphore.make(1);
+ const snapshotStarted = yield* Deferred.make<void>();
+ const finishSnapshot = yield* Deferred.make<void>();
+ const subscriptionFiber = yield* subscribeBeforeSnapshot(
+ changes,
+ Deferred.succeed(snapshotStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(finishSnapshot)),
+ Effect.andThen(Ref.get(latest)),
+ ),
+ mutex,
+ ).pipe(Effect.forkChild);
+
+ yield* Deferred.await(snapshotStarted);
+ const publishFiber = yield* mutex
+ .withPermits(1)(Ref.set(latest, 2).pipe(Effect.andThen(PubSub.publish(changes, 2))))
+ .pipe(Effect.forkChild);
+ yield* Deferred.succeed(finishSnapshot, undefined);
+
+ const subscription = yield* Fiber.join(subscriptionFiber);
+ yield* Fiber.join(publishFiber);
+ const firstChange = yield* subscription.changes.pipe(
+ Stream.runHead,
+ Effect.timeout("1 second"),
+ );
+
+ expect(subscription.latest).toBe(1);
+ expect(firstChange).toEqual(Option.some(2));
+ }),
+ ),
+ );
+
+ it.effect("subscribes before an uncoordinated snapshot can change", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const changes = yield* PubSub.sliding<number>(1);
+ const latest = yield* Ref.make(1);
+ const snapshotStarted = yield* Deferred.make<void>();
+ const finishSnapshot = yield* Deferred.make<void>();
+ const subscriptionFiber = yield* subscribeBeforeSnapshotWithoutMutex(
+ changes,
+ Deferred.succeed(snapshotStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(finishSnapshot)),
+ Effect.andThen(Ref.get(latest)),
+ ),
+ ).pipe(Effect.forkChild);
+
+ yield* Deferred.await(snapshotStarted);
+ yield* Ref.set(latest, 2);
+ yield* PubSub.publish(changes, 2);
+ yield* Deferred.succeed(finishSnapshot, undefined);
+
+ const subscription = yield* Fiber.join(subscriptionFiber);
+ const firstChange = yield* subscription.changes.pipe(
+ Stream.runHead,
+ Effect.timeout("1 second"),
+ );
+
+ expect(subscription.latest).toBe(2);
+ expect(firstChange).toEqual(Option.some(2));
+ }),
+ ),
+ );
+});
diff --git a/apps/server/src/utils/subscribeBeforeSnapshot.ts b/apps/server/src/utils/subscribeBeforeSnapshot.ts
new file mode 100644
index 000000000..7ca1e1c4f
--- /dev/null
+++ b/apps/server/src/utils/subscribeBeforeSnapshot.ts
@@ -0,0 +1,37 @@
+import * as Effect from "effect/Effect";
+import * as PubSub from "effect/PubSub";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+
+export interface SnapshotSubscription<A> {
+ readonly latest: A;
+ readonly changes: Stream.Stream<A>;
+}
+
+export const subscribeBeforeSnapshot = Effect.fn("subscribeBeforeSnapshot")(function* <A, E, R>(
+ changes: PubSub.PubSub<A>,
+ snapshot: Effect.Effect<A, E, R>,
+ mutex: Semaphore.Semaphore,
+) {
+ return yield* mutex.withPermits(1)(
+ Effect.gen(function* () {
+ const latest = yield* snapshot;
+ const subscription = yield* PubSub.subscribe(changes);
+ return {
+ latest,
+ changes: Stream.fromSubscription(subscription),
+ } satisfies SnapshotSubscription<A>;
+ }),
+ );
+});
+
+export const subscribeBeforeSnapshotWithoutMutex = Effect.fn("subscribeBeforeSnapshotWithoutMutex")(
+ function* <A, E, R>(changes: PubSub.PubSub<A>, snapshot: Effect.Effect<A, E, R>) {
+ const subscription = yield* PubSub.subscribe(changes);
+ const latest = yield* snapshot;
+ return {
+ latest,
+ changes: Stream.fromSubscription(subscription),
+ } satisfies SnapshotSubscription<A>;
+ },
+);
diff --git a/apps/server/src/vcs/VcsStatusBroadcaster.test.ts b/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
index ee595b1f8..6820a29e2 100644
--- a/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
+++ b/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
@@ -2,6 +2,7 @@ import { assert, it, describe } from "@effect/vitest";
import * as NodeServices from "@effect/platform-node/NodeServices";
import * as Cause from "effect/Cause";
import * as Deferred from "effect/Deferred";
+import * as DateTime from "effect/DateTime";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
@@ -14,6 +15,7 @@ import * as Scope from "effect/Scope";
import * as Stream from "effect/Stream";
import * as TestClock from "effect/testing/TestClock";
import type {
+ BackgroundScope,
VcsStatusLocalResult,
VcsStatusRemoteResult,
VcsStatusResult,
@@ -22,8 +24,11 @@ import type {
import { GitManagerError } from "@t3tools/contracts";
import * as VcsStatusBroadcaster from "./VcsStatusBroadcaster.ts";
+import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
import * as GitWorkflowService from "../git/GitWorkflowService.ts";
+const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
+
const baseLocalStatus: VcsStatusLocalResult = {
isRepo: true,
sourceControlProvider: {
@@ -73,6 +78,7 @@ function makeTestLayer(state: {
}) {
return VcsStatusBroadcaster.layer.pipe(
Layer.provideMerge(NodeServices.layer),
+ Layer.provide(makeBackgroundPolicyLayer(() => true)),
Layer.provide(
Layer.mock(GitWorkflowService.GitWorkflowService)({
localStatus: () =>
@@ -104,6 +110,37 @@ function makeTestLayer(state: {
);
}
+function makeBackgroundPolicyLayer(shouldRunScopeWork: (scope: BackgroundScope) => boolean) {
+ return Layer.mock(BackgroundPolicy.BackgroundPolicy)({
+ reportClientActivity: () => Effect.void,
+ removeRpcClient: () => Effect.void,
+ reportHostPowerState: () => Effect.void,
+ snapshot: Effect.succeed({
+ hostPower: {
+ source: "unknown",
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt: TEST_EPOCH,
+ },
+ leases: [],
+ activeForegroundLeaseCount: 0,
+ activeScopeKeys: [],
+ shouldRunOpportunisticWork: false,
+ updatedAt: TEST_EPOCH,
+ }),
+ streamChanges: Stream.empty,
+ hasDemand: () => Effect.succeed(true),
+ shouldRunScopeWork: (scope) => Effect.sync(() => shouldRunScopeWork(scope)),
+ shouldRunOpportunisticWork: Effect.succeed(true),
+ });
+}
+
describe("VcsStatusBroadcaster", () => {
it.effect("reuses the cached VCS status across repeated reads", () => {
const state = {
@@ -183,6 +220,7 @@ describe("VcsStatusBroadcaster", () => {
};
const testLayer = VcsStatusBroadcaster.layer.pipe(
Layer.provideMerge(NodeServices.layer),
+ Layer.provide(makeBackgroundPolicyLayer(() => true)),
Layer.provide(
Layer.mock(GitWorkflowService.GitWorkflowService)({
localStatus: () =>
@@ -290,6 +328,7 @@ describe("VcsStatusBroadcaster", () => {
};
const testLayer = VcsStatusBroadcaster.layer.pipe(
Layer.provideMerge(NodeServices.layer),
+ Layer.provide(makeBackgroundPolicyLayer(() => true)),
Layer.provide(
Layer.mock(GitWorkflowService.GitWorkflowService)({
localStatus: (input) =>
@@ -453,6 +492,7 @@ describe("VcsStatusBroadcaster", () => {
let firstRemoteAttemptDeferred: Deferred.Deferred<void> | null = null;
const testLayer = VcsStatusBroadcaster.layer.pipe(
Layer.provideMerge(NodeServices.layer),
+ Layer.provide(makeBackgroundPolicyLayer(() => true)),
Layer.provide(
Layer.mock(GitWorkflowService.GitWorkflowService)({
localStatus: () =>
@@ -641,6 +681,57 @@ describe("VcsStatusBroadcaster", () => {
});
});
+ it.effect("does not start automatic remote refreshes without foreground client demand", () => {
+ const state = {
+ currentLocalStatus: baseLocalStatus,
+ currentRemoteStatus: baseRemoteStatus,
+ localStatusCalls: 0,
+ remoteStatusCalls: 0,
+ localInvalidationCalls: 0,
+ remoteInvalidationCalls: 0,
+ };
+ const testLayer = VcsStatusBroadcaster.layer.pipe(
+ Layer.provideMerge(NodeServices.layer),
+ Layer.provide(makeBackgroundPolicyLayer(() => false)),
+ Layer.provide(
+ Layer.mock(GitWorkflowService.GitWorkflowService)({
+ localStatus: () =>
+ Effect.sync(() => {
+ state.localStatusCalls += 1;
+ return state.currentLocalStatus;
+ }),
+ remoteStatus: () =>
+ Effect.sync(() => {
+ state.remoteStatusCalls += 1;
+ return state.currentRemoteStatus;
+ }),
+ invalidateLocalStatus: () =>
+ Effect.sync(() => {
+ state.localInvalidationCalls += 1;
+ }),
+ invalidateRemoteStatus: () =>
+ Effect.sync(() => {
+ state.remoteInvalidationCalls += 1;
+ }),
+ } satisfies Partial<GitWorkflowService.GitWorkflowService["Service"]>),
+ ),
+ );
+
+ return Effect.gen(function* () {
+ const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
+ const snapshot = yield* Stream.runHead(
+ broadcaster.streamStatus(
+ { cwd: "/repo" },
+ { automaticRemoteRefreshInterval: Effect.succeed(Duration.seconds(1)) },
+ ),
+ );
+
+ assert.isTrue(Option.isSome(snapshot));
+ assert.equal(state.remoteStatusCalls, 0);
+ assert.equal(state.remoteInvalidationCalls, 0);
+ }).pipe(Effect.provide(testLayer));
+ });
+
it.effect("stops the remote poller after the last stream subscriber disconnects", () => {
const state = {
currentLocalStatus: baseLocalStatus,
@@ -654,6 +745,7 @@ describe("VcsStatusBroadcaster", () => {
let remoteStartedDeferred: Deferred.Deferred<void, never> | null = null;
const testLayer = VcsStatusBroadcaster.layer.pipe(
Layer.provideMerge(NodeServices.layer),
+ Layer.provide(makeBackgroundPolicyLayer(() => true)),
Layer.provide(
Layer.mock(GitWorkflowService.GitWorkflowService)({
localStatus: () =>
diff --git a/apps/server/src/vcs/VcsStatusBroadcaster.ts b/apps/server/src/vcs/VcsStatusBroadcaster.ts
index d1a670532..f28069f6d 100644
--- a/apps/server/src/vcs/VcsStatusBroadcaster.ts
+++ b/apps/server/src/vcs/VcsStatusBroadcaster.ts
@@ -22,6 +22,7 @@ import type {
} from "@t3tools/contracts";
import { mergeGitStatusParts } from "@t3tools/shared/git";
+import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
import * as GitWorkflowService from "../git/GitWorkflowService.ts";
const DEFAULT_VCS_STATUS_REFRESH_INTERVAL = Duration.seconds(30);
@@ -131,6 +132,7 @@ interface CachedVcsStatus {
interface ActiveRemotePoller {
readonly fiber: Fiber.Fiber<void, never>;
readonly subscriberCount: number;
+ readonly demandCwds: Ref.Ref<ReadonlyMap<string, number>>;
}
interface StreamStatusOptions {
@@ -180,6 +182,7 @@ const normalizeCwd = (cwd: string) =>
export const make = Effect.gen(function* () {
const workflow = yield* GitWorkflowService.GitWorkflowService;
+ const backgroundPolicy = yield* BackgroundPolicy.BackgroundPolicy;
const fs = yield* FileSystem.FileSystem;
const changesPubSub = yield* Effect.acquireRelease(
PubSub.unbounded<VcsStatusChange>(),
@@ -378,6 +381,7 @@ export const make = Effect.gen(function* () {
const makeRemoteRefreshLoop = (
cwd: string,
+ demandCwdsRef: Ref.Ref<ReadonlyMap<string, number>>,
automaticRemoteRefreshInterval: Effect.Effect<Duration.Duration, never>,
refreshImmediately: boolean,
) => {
@@ -394,6 +398,22 @@ export const make = Effect.gen(function* () {
return activeInterval;
}
+ const demandCwds = yield* Ref.get(demandCwdsRef);
+ const shouldRun =
+ needsInitialRefresh ||
+ (yield* Effect.all(
+ [...demandCwds.keys()].map((demandCwd) =>
+ backgroundPolicy.shouldRunScopeWork({
+ type: "vcs-status",
+ cwd: demandCwd,
+ }),
+ ),
+ { concurrency: "unbounded" },
+ )).some(Boolean);
+ if (!shouldRun) {
+ return activeInterval;
+ }
+
const exit = yield* refreshRemoteStatus(cwd, {
refreshUpstream: !Duration.isZero(configuredInterval),
}).pipe(Effect.exit);
@@ -444,55 +464,88 @@ export const make = Effect.gen(function* () {
const retainRemotePoller = Effect.fn("VcsStatusBroadcaster.retainRemotePoller")(function* (
cwd: string,
+ demandCwd: string,
automaticRemoteRefreshInterval: Effect.Effect<Duration.Duration, never>,
refreshImmediately: boolean,
) {
yield* SynchronizedRef.modifyEffect(pollersRef, (activePollers) => {
const existing = activePollers.get(cwd);
if (existing) {
- const nextPollers = new Map(activePollers);
- nextPollers.set(cwd, {
- ...existing,
- subscriberCount: existing.subscriberCount + 1,
- });
- return Effect.succeed([undefined, nextPollers] as const);
+ return Ref.update(existing.demandCwds, (demandCwds) => {
+ const next = new Map(demandCwds);
+ next.set(demandCwd, (next.get(demandCwd) ?? 0) + 1);
+ return next;
+ }).pipe(
+ Effect.map(() => {
+ const nextPollers = new Map(activePollers);
+ nextPollers.set(cwd, {
+ ...existing,
+ subscriberCount: existing.subscriberCount + 1,
+ });
+ return [undefined, nextPollers] as const;
+ }),
+ );
}
- return makeRemoteRefreshLoop(cwd, automaticRemoteRefreshInterval, refreshImmediately).pipe(
- Effect.forkIn(broadcasterScope),
- Effect.map((fiber) => {
- const nextPollers = new Map(activePollers);
- nextPollers.set(cwd, {
- fiber,
- subscriberCount: 1,
- });
- return [undefined, nextPollers] as const;
- }),
+ return Ref.make<ReadonlyMap<string, number>>(new Map([[demandCwd, 1]])).pipe(
+ Effect.flatMap((demandCwds) =>
+ makeRemoteRefreshLoop(
+ cwd,
+ demandCwds,
+ automaticRemoteRefreshInterval,
+ refreshImmediately,
+ ).pipe(
+ Effect.forkIn(broadcasterScope),
+ Effect.map((fiber) => {
+ const nextPollers = new Map(activePollers);
+ nextPollers.set(cwd, {
+ fiber,
+ subscriberCount: 1,
+ demandCwds,
+ });
+ return [undefined, nextPollers] as const;
+ }),
+ ),
+ ),
);
});
});
const releaseRemotePoller = Effect.fn("VcsStatusBroadcaster.releaseRemotePoller")(function* (
cwd: string,
+ demandCwd: string,
) {
- const pollerToInterrupt = yield* SynchronizedRef.modify(pollersRef, (activePollers) => {
+ const pollerToInterrupt = yield* SynchronizedRef.modifyEffect(pollersRef, (activePollers) => {
const existing = activePollers.get(cwd);
if (!existing) {
- return [null, activePollers] as const;
+ return Effect.succeed([null, activePollers] as const);
}
if (existing.subscriberCount > 1) {
- const nextPollers = new Map(activePollers);
- nextPollers.set(cwd, {
- ...existing,
- subscriberCount: existing.subscriberCount - 1,
- });
- return [null, nextPollers] as const;
+ return Ref.update(existing.demandCwds, (demandCwds) => {
+ const nextDemandCwds = new Map(demandCwds);
+ const count = nextDemandCwds.get(demandCwd) ?? 0;
+ if (count <= 1) {
+ nextDemandCwds.delete(demandCwd);
+ } else {
+ nextDemandCwds.set(demandCwd, count - 1);
+ }
+ return nextDemandCwds;
+ }).pipe(
+ Effect.as([
+ null,
+ new Map(activePollers).set(cwd, {
+ ...existing,
+ subscriberCount: existing.subscriberCount - 1,
+ }),
+ ] as const),
+ );
}
- const nextPollers = new Map(activePollers);
- nextPollers.delete(cwd);
- return [existing.fiber, nextPollers] as const;
+ return Effect.succeed([
+ existing.fiber,
+ new Map([...activePollers].filter(([activeCwd]) => activeCwd !== cwd)),
+ ] as const);
});
if (pollerToInterrupt) {
@@ -510,12 +563,13 @@ export const make = Effect.gen(function* () {
const initialRemote = cachedStatus?.remote?.value ?? null;
yield* retainRemotePoller(
cwd,
+ input.cwd,
options?.automaticRemoteRefreshInterval ??
Effect.succeed(DEFAULT_VCS_STATUS_REFRESH_INTERVAL),
cachedStatus?.remote === null || cachedStatus?.remote === undefined,
);
- const release = releaseRemotePoller(cwd).pipe(Effect.ignore, Effect.asVoid);
+ const release = releaseRemotePoller(cwd, input.cwd).pipe(Effect.ignore, Effect.asVoid);
return Stream.concat(
Stream.make({
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index 744e48661..6c021c9af 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -11,12 +11,6 @@ import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
import {
DEFAULT_AUTOMATIC_GIT_FETCH_INTERVAL,
- AuthOrchestrationOperateScope,
- AuthOrchestrationReadScope,
- AuthReviewWriteScope,
- AuthRelayWriteScope,
- AuthTerminalOperateScope,
- AuthAccessReadScope,
AuthAccessStreamError,
type AuthAccessStreamEvent,
type AuthEnvironmentScope,
@@ -50,6 +44,7 @@ import {
FilesystemBrowseError,
AssetWorkspaceContextNotFoundError,
AssetWorkspaceContextResolutionError,
+ RpcClientId,
EnvironmentAuthorizationError,
ThreadId,
type TerminalAttachStreamEvent,
@@ -59,6 +54,7 @@ import {
WS_METHODS,
WsRpcGroup,
} from "@t3tools/contracts";
+import { resolveServerBackgroundActivitySettings } from "@t3tools/shared/backgroundActivitySettings";
import { HttpRouter, HttpServerRequest, HttpServerRespondable } from "effect/unstable/http";
import { RpcSerialization, RpcServer } from "effect/unstable/rpc";
@@ -98,9 +94,12 @@ import * as GitWorkflowService from "./git/GitWorkflowService.ts";
import * as ReviewService from "./review/ReviewService.ts";
import * as ProjectSetupScriptRunner from "./project/ProjectSetupScriptRunner.ts";
import * as ServerEnvironment from "./environment/ServerEnvironment.ts";
+import * as BackgroundPolicy from "./background/BackgroundPolicy.ts";
import * as EnvironmentAuth from "./auth/EnvironmentAuth.ts";
+import { requiredScopeForRpcMethod } from "./auth/RpcAuthorization.ts";
import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";
import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";
+import * as ResourceTelemetry from "./resourceTelemetry/ResourceTelemetry.ts";
import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";
import * as SourceControlDiscovery from "./sourceControl/SourceControlDiscovery.ts";
import * as SourceControlRepositoryService from "./sourceControl/SourceControlRepositoryService.ts";
@@ -295,78 +294,6 @@ const PROVIDER_STATUS_DEBOUNCE_MS = 200;
// Matches the event store's default page size (DEFAULT_READ_FROM_SEQUENCE_LIMIT).
const SHELL_RESUME_MAX_GAP = 1_000;
-const RPC_REQUIRED_SCOPE = new Map<string, AuthEnvironmentScope>([
- [ORCHESTRATION_WS_METHODS.dispatchCommand, AuthOrchestrationOperateScope],
- [ORCHESTRATION_WS_METHODS.getTurnDiff, AuthOrchestrationReadScope],
- [ORCHESTRATION_WS_METHODS.getFullThreadDiff, AuthOrchestrationReadScope],
- [ORCHESTRATION_WS_METHODS.subscribeShell, AuthOrchestrationReadScope],
- [ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot, AuthOrchestrationReadScope],
- [ORCHESTRATION_WS_METHODS.subscribeThread, AuthOrchestrationReadScope],
- [WS_METHODS.serverProbe, AuthOrchestrationReadScope],
- [WS_METHODS.serverGetConfig, AuthOrchestrationReadScope],
- [WS_METHODS.serverRefreshProviders, AuthOrchestrationOperateScope],
- [WS_METHODS.serverUpdateProvider, AuthOrchestrationOperateScope],
- [WS_METHODS.serverUpdateServer, AuthOrchestrationOperateScope],
- [WS_METHODS.serverUpsertKeybinding, AuthOrchestrationOperateScope],
- [WS_METHODS.serverRemoveKeybinding, AuthOrchestrationOperateScope],
- [WS_METHODS.serverGetSettings, AuthOrchestrationReadScope],
- [WS_METHODS.serverUpdateSettings, AuthOrchestrationOperateScope],
- [WS_METHODS.serverDiscoverSourceControl, AuthOrchestrationReadScope],
- [WS_METHODS.serverGetTraceDiagnostics, AuthOrchestrationReadScope],
- [WS_METHODS.serverGetProcessDiagnostics, AuthOrchestrationReadScope],
- [WS_METHODS.serverGetProcessResourceHistory, AuthOrchestrationReadScope],
- [WS_METHODS.serverSignalProcess, AuthOrchestrationOperateScope],
- [WS_METHODS.cloudGetRelayClientStatus, AuthRelayWriteScope],
- [WS_METHODS.cloudInstallRelayClient, AuthRelayWriteScope],
- [WS_METHODS.sourceControlLookupRepository, AuthOrchestrationReadScope],
- [WS_METHODS.sourceControlCloneRepository, AuthOrchestrationOperateScope],
- [WS_METHODS.sourceControlPublishRepository, AuthOrchestrationOperateScope],
- [WS_METHODS.projectsListEntries, AuthOrchestrationReadScope],
- [WS_METHODS.projectsReadFile, AuthOrchestrationReadScope],
- [WS_METHODS.projectsSearchEntries, AuthOrchestrationReadScope],
- [WS_METHODS.projectsWriteFile, AuthOrchestrationOperateScope],
- [WS_METHODS.shellOpenInEditor, AuthOrchestrationOperateScope],
- [WS_METHODS.filesystemBrowse, AuthOrchestrationReadScope],
- [WS_METHODS.assetsCreateUrl, AuthOrchestrationReadScope],
- [WS_METHODS.subscribeVcsStatus, AuthOrchestrationReadScope],
- [WS_METHODS.vcsRefreshStatus, AuthOrchestrationReadScope],
- [WS_METHODS.vcsPull, AuthOrchestrationOperateScope],
- [WS_METHODS.gitRunStackedAction, AuthOrchestrationOperateScope],
- [WS_METHODS.gitResolvePullRequest, AuthOrchestrationOperateScope],
- [WS_METHODS.gitPreparePullRequestThread, AuthOrchestrationOperateScope],
- [WS_METHODS.vcsListRefs, AuthOrchestrationReadScope],
- [WS_METHODS.vcsCreateWorktree, AuthOrchestrationOperateScope],
- [WS_METHODS.vcsRemoveWorktree, AuthOrchestrationOperateScope],
- [WS_METHODS.vcsCreateRef, AuthOrchestrationOperateScope],
- [WS_METHODS.vcsSwitchRef, AuthOrchestrationOperateScope],
- [WS_METHODS.vcsInit, AuthOrchestrationOperateScope],
- [WS_METHODS.reviewGetDiffPreview, AuthReviewWriteScope],
- [WS_METHODS.terminalOpen, AuthTerminalOperateScope],
- [WS_METHODS.terminalAttach, AuthTerminalOperateScope],
- [WS_METHODS.terminalWrite, AuthTerminalOperateScope],
- [WS_METHODS.terminalResize, AuthTerminalOperateScope],
- [WS_METHODS.terminalClear, AuthTerminalOperateScope],
- [WS_METHODS.terminalRestart, AuthTerminalOperateScope],
- [WS_METHODS.terminalClose, AuthTerminalOperateScope],
- [WS_METHODS.subscribeTerminalEvents, AuthTerminalOperateScope],
- [WS_METHODS.subscribeTerminalMetadata, AuthTerminalOperateScope],
- [WS_METHODS.previewOpen, AuthOrchestrationOperateScope],
- [WS_METHODS.previewNavigate, AuthOrchestrationOperateScope],
- [WS_METHODS.previewResize, AuthOrchestrationOperateScope],
- [WS_METHODS.previewRefresh, AuthOrchestrationOperateScope],
- [WS_METHODS.previewClose, AuthOrchestrationOperateScope],
- [WS_METHODS.previewList, AuthOrchestrationReadScope],
- [WS_METHODS.previewReportStatus, AuthOrchestrationOperateScope],
- [WS_METHODS.previewAutomationConnect, AuthOrchestrationOperateScope],
- [WS_METHODS.previewAutomationRespond, AuthOrchestrationOperateScope],
- [WS_METHODS.previewAutomationFocusHost, AuthOrchestrationOperateScope],
- [WS_METHODS.subscribePreviewEvents, AuthOrchestrationReadScope],
- [WS_METHODS.subscribeDiscoveredLocalServers, AuthOrchestrationReadScope],
- [WS_METHODS.subscribeServerConfig, AuthOrchestrationReadScope],
- [WS_METHODS.subscribeServerLifecycle, AuthOrchestrationReadScope],
- [WS_METHODS.subscribeAuthAccess, AuthAccessReadScope],
-]);
-
function toAuthAccessStreamEvent(
change: PairingGrantStore.BootstrapCredentialChange | SessionStore.SessionCredentialChange,
revision: number,
@@ -438,10 +365,28 @@ const makeWsRpcLayer = (
const workspaceFileSystem = yield* WorkspaceFileSystem.WorkspaceFileSystem;
const projectSetupScriptRunner = yield* ProjectSetupScriptRunner.ProjectSetupScriptRunner;
const serverEnvironment = yield* ServerEnvironment.ServerEnvironment;
+ const backgroundPolicy = yield* BackgroundPolicy.BackgroundPolicy;
+ const rpcClientIds = yield* Ref.make(new Set<RpcClientId>());
+ yield* Effect.addFinalizer(() =>
+ Ref.get(rpcClientIds).pipe(
+ Effect.flatMap((clientIds) =>
+ Effect.forEach(
+ clientIds,
+ (clientId) => backgroundPolicy.removeRpcClient(currentSessionId, clientId),
+ {
+ discard: true,
+ },
+ ),
+ ),
+ Effect.ignore,
+ ),
+ );
const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;
const sourceControlDiscovery = yield* SourceControlDiscovery.SourceControlDiscovery;
const automaticGitFetchInterval = serverSettings.getSettings.pipe(
- Effect.map((settings) => settings.automaticGitFetchInterval),
+ Effect.map(
+ (settings) => resolveServerBackgroundActivitySettings(settings).automaticGitFetchInterval,
+ ),
Effect.catch((cause) =>
Effect.logWarning("Failed to read automatic Git fetch interval setting", {
detail: cause.message,
@@ -454,6 +399,7 @@ const makeWsRpcLayer = (
const sessions = yield* SessionStore.SessionStore;
const processDiagnostics = yield* ProcessDiagnostics.ProcessDiagnostics;
const processResourceMonitor = yield* ProcessResourceMonitor.ProcessResourceMonitor;
+ const resourceTelemetry = yield* ResourceTelemetry.ResourceTelemetry;
const relayClient = yield* RelayClient.RelayClient;
const authorizationError = (requiredScope: AuthEnvironmentScope) =>
new EnvironmentAuthorizationError({
@@ -474,13 +420,6 @@ const makeWsRpcLayer = (
currentSession.scopes.includes(requiredScope)
? stream
: Stream.fail(authorizationError(requiredScope));
- const requiredScopeForMethod = (method: string): AuthEnvironmentScope => {
- const requiredScope = RPC_REQUIRED_SCOPE.get(method);
- if (requiredScope === undefined) {
- throw new Error(`RPC method ${method} has no declared authorization scope.`);
- }
- return requiredScope;
- };
const observeRpcEffect = <A, E, R>(
method: string,
effect: Effect.Effect<A, E, R>,
@@ -488,7 +427,7 @@ const makeWsRpcLayer = (
) =>
instrumentRpcEffect(
method,
- authorizeEffect(requiredScopeForMethod(method), effect),
+ authorizeEffect(requiredScopeForRpcMethod(method), effect),
traceAttributes,
);
const observeRpcStream = <A, E, R>(
@@ -498,7 +437,7 @@ const makeWsRpcLayer = (
) =>
instrumentRpcStream(
method,
- authorizeStream(requiredScopeForMethod(method), stream),
+ authorizeStream(requiredScopeForRpcMethod(method), stream),
traceAttributes,
);
const observeRpcStreamEffect = <A, StreamError, StreamContext, EffectError, EffectContext>(
@@ -512,7 +451,7 @@ const makeWsRpcLayer = (
) =>
instrumentRpcStreamEffect(
method,
- authorizeEffect(requiredScopeForMethod(method), effect),
+ authorizeEffect(requiredScopeForRpcMethod(method), effect),
traceAttributes,
);
const toDispatchCommandError = (cause: unknown, fallbackMessage: string) =>
@@ -1494,10 +1433,50 @@ const makeWsRpcLayer = (
"rpc.aggregate": "server",
},
),
+ [WS_METHODS.serverGetResourceTelemetryHistory]: (input) =>
+ observeRpcEffect(
+ WS_METHODS.serverGetResourceTelemetryHistory,
+ resourceTelemetry.readHistory(input),
+ {
+ "rpc.aggregate": "server",
+ },
+ ),
+ [WS_METHODS.serverRetryResourceTelemetry]: (_input) =>
+ observeRpcEffect(WS_METHODS.serverRetryResourceTelemetry, resourceTelemetry.retry, {
+ "rpc.aggregate": "server",
+ }),
[WS_METHODS.serverSignalProcess]: (input) =>
observeRpcEffect(WS_METHODS.serverSignalProcess, processDiagnostics.signal(input), {
"rpc.aggregate": "server",
}),
+ [WS_METHODS.serverReportClientActivity]: (input, metadata) =>
+ Ref.update(rpcClientIds, (clientIds) => {
+ const next = new Set(clientIds);
+ next.add(RpcClientId.make(metadata.client.id));
+ return next;
+ }).pipe(
+ Effect.andThen(
+ observeRpcEffect(
+ WS_METHODS.serverReportClientActivity,
+ backgroundPolicy.reportClientActivity(
+ currentSessionId,
+ RpcClientId.make(metadata.client.id),
+ input,
+ ),
+ { "rpc.aggregate": "server" },
+ ),
+ ),
+ ),
+ [WS_METHODS.serverReportHostPowerState]: (input) =>
+ observeRpcEffect(
+ WS_METHODS.serverReportHostPowerState,
+ backgroundPolicy.reportHostPowerState(input),
+ { "rpc.aggregate": "server" },
+ ),
+ [WS_METHODS.serverGetBackgroundPolicy]: (_input) =>
+ observeRpcEffect(WS_METHODS.serverGetBackgroundPolicy, backgroundPolicy.snapshot, {
+ "rpc.aggregate": "server",
+ }),
[WS_METHODS.cloudGetRelayClientStatus]: (_input) =>
observeRpcEffect(WS_METHODS.cloudGetRelayClientStatus, relayClient.resolve, {
"rpc.aggregate": "cloud",
@@ -2021,6 +2000,26 @@ const makeWsRpcLayer = (
}),
{ "rpc.aggregate": "auth" },
),
+ [WS_METHODS.subscribeBackgroundPolicy]: (_input) =>
+ observeRpcStream(
+ WS_METHODS.subscribeBackgroundPolicy,
+ Stream.unwrap(
+ Effect.map(backgroundPolicy.subscribe, ({ latest, changes }) =>
+ Stream.concat(Stream.make(latest), changes),
+ ),
+ ),
+ { "rpc.aggregate": "server" },
+ ),
+ [WS_METHODS.subscribeResourceTelemetry]: (_input) =>
+ observeRpcStream(
+ WS_METHODS.subscribeResourceTelemetry,
+ Stream.unwrap(
+ Effect.map(resourceTelemetry.subscribe, ({ latest, changes }) =>
+ Stream.concat(Stream.make(latest), changes),
+ ),
+ ),
+ { "rpc.aggregate": "server" },
+ ),
});
}),
);
diff --git a/apps/web/src/components/settings/DiagnosticsSettings.tsx b/apps/web/src/components/settings/DiagnosticsSettings.tsx
index b1a54feb7..adce508f7 100644
--- a/apps/web/src/components/settings/DiagnosticsSettings.tsx
+++ b/apps/web/src/components/settings/DiagnosticsSettings.tsx
@@ -37,6 +37,7 @@ import { Button } from "../ui/button";
import { ScrollArea } from "../ui/scroll-area";
import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
import { toastManager } from "../ui/toast";
+import { ResourceTelemetryDiagnostics } from "./ResourceTelemetryDiagnostics";
import { SettingsPageContainer, SettingsSection, useRelativeTimeTick } from "./settingsLayout";
import { useAtomCommand } from "../../state/use-atom-command";
@@ -904,12 +905,16 @@ export function DiagnosticsSettingsPanel() {
if (environmentId === null) {
return;
}
+ const process = processData?.processes.find((entry) => entry.pid === pid);
+ if (process === undefined) {
+ return;
+ }
setSignalingPid(pid);
void (async () => {
const result = await signalServerProcess({
environmentId,
- input: { pid, signal },
+ input: { pid, startTimeMs: process.startTimeMs, signal },
});
setSignalingPid(null);
if (result._tag === "Failure") {
@@ -946,7 +951,7 @@ export function DiagnosticsSettingsPanel() {
refreshProcesses();
})();
},
- [environmentId, refreshProcesses, signalServerProcess],
+ [environmentId, processData?.processes, refreshProcesses, signalServerProcess],
);
const processDiagnosticsError = processData ? Option.getOrNull(processData.error) : null;
@@ -957,7 +962,9 @@ export function DiagnosticsSettingsPanel() {
: false;
return (
- <SettingsPageContainer>
+ <SettingsPageContainer className="max-w-6xl gap-10">
+ <ResourceTelemetryDiagnostics />
+
<SettingsSection
title="Live Processes"
headerAction={
diff --git a/apps/web/src/components/settings/ResourceTelemetryDiagnostics.logic.test.ts b/apps/web/src/components/settings/ResourceTelemetryDiagnostics.logic.test.ts
new file mode 100644
index 000000000..2d735447b
--- /dev/null
+++ b/apps/web/src/components/settings/ResourceTelemetryDiagnostics.logic.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import type { ResourceTelemetryProcess } from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+
+import {
+ resourceHistoryBarHeight,
+ resourceHistoryCpuScaleMax,
+ shouldShowResourceMonitorRetry,
+ visibleResourceTelemetryProcesses,
+} from "./ResourceTelemetryDiagnostics.logic";
+
+const process = (pid: number, ppid: number, depth: number): ResourceTelemetryProcess => ({
+ identity: { pid, startTimeMs: pid * 1_000 },
+ ppid,
+ childPids: [],
+ depth,
+ name: `process-${pid}`,
+ command: `process-${pid}`,
+ status: "Running",
+ category: pid === 1 ? "server" : "server-child",
+ cpuPercent: 0,
+ cpuTimeMs: 0,
+ residentBytes: 0,
+ peakResidentBytes: 0,
+ virtualBytes: 0,
+ ioReadBytes: 0,
+ ioWriteBytes: 0,
+ ioReadBytesPerSecond: 0,
+ ioWriteBytesPerSecond: 0,
+ ioSemantics: "storage",
+ runTimeMs: 0,
+ firstSeenAt: DateTime.makeUnsafe(0),
+ lastSeenAt: DateTime.makeUnsafe(0),
+});
+
+describe("shouldShowResourceMonitorRetry", () => {
+ it("allows retry when the initial telemetry request fails before a snapshot", () => {
+ expect(
+ shouldShowResourceMonitorRetry({
+ nativeStatus: null,
+ error: "Resource monitor is unavailable.",
+ }),
+ ).toBe(true);
+ });
+
+ it("does not show retry for an initial load without an error or a healthy snapshot", () => {
+ expect(shouldShowResourceMonitorRetry({ nativeStatus: null, error: null })).toBe(false);
+ expect(shouldShowResourceMonitorRetry({ nativeStatus: "healthy", error: null })).toBe(false);
+ });
+});
+
+describe("resourceHistoryBarHeight", () => {
+ it("renders an exactly zero sample with no visible bar", () => {
+ expect(resourceHistoryBarHeight({ value: 0, max: 100, minimumVisiblePercent: 2 })).toBe(0);
+ });
+
+ it("keeps nonzero samples visible without changing proportional heights", () => {
+ expect(resourceHistoryBarHeight({ value: 0.5, max: 100, minimumVisiblePercent: 2 })).toBe(2);
+ expect(resourceHistoryBarHeight({ value: 50, max: 100, minimumVisiblePercent: 2 })).toBe(50);
+ });
+});
+
+describe("resourceHistoryCpuScaleMax", () => {
+ it("scales average bars independently of brief peak spikes", () => {
+ const buckets = [
+ { avgCpuPercent: 1, maxCpuPercent: 100 },
+ { avgCpuPercent: 8, maxCpuPercent: 8 },
+ ];
+ expect(resourceHistoryCpuScaleMax(buckets)).toBe(8);
+ });
+});
+
+describe("visibleResourceTelemetryProcesses", () => {
+ it("hides descendants by parentage even when rows are not depth-first", () => {
+ const processes = [
+ process(1, 0, 0),
+ process(10, 0, 0),
+ process(2, 1, 1),
+ process(11, 10, 1),
+ process(3, 2, 2),
+ ];
+
+ expect(visibleResourceTelemetryProcesses(processes, new Set(["1:1000"]))).toEqual([
+ processes[0],
+ processes[1],
+ processes[3],
+ ]);
+ });
+});
diff --git a/apps/web/src/components/settings/ResourceTelemetryDiagnostics.logic.ts b/apps/web/src/components/settings/ResourceTelemetryDiagnostics.logic.ts
new file mode 100644
index 000000000..6b7ab749c
--- /dev/null
+++ b/apps/web/src/components/settings/ResourceTelemetryDiagnostics.logic.ts
@@ -0,0 +1,60 @@
+import type { ResourceTelemetryProcess, ResourceTelemetrySourceStatus } from "@t3tools/contracts";
+
+function processIdentityKey(process: ResourceTelemetryProcess): string {
+ return `${process.identity.pid}:${process.identity.startTimeMs}`;
+}
+
+export function visibleResourceTelemetryProcesses(
+ processes: ReadonlyArray<ResourceTelemetryProcess>,
+ collapsed: ReadonlySet<string>,
+): ReadonlyArray<ResourceTelemetryProcess> {
+ const childrenByParent = new Map<number, ResourceTelemetryProcess[]>();
+ for (const process of processes) {
+ const children = childrenByParent.get(process.ppid) ?? [];
+ children.push(process);
+ childrenByParent.set(process.ppid, children);
+ }
+
+ const hidden = new Set<string>();
+ const hideDescendants = (pid: number): void => {
+ for (const child of childrenByParent.get(pid) ?? []) {
+ const key = processIdentityKey(child);
+ if (hidden.has(key)) continue;
+ hidden.add(key);
+ hideDescendants(child.identity.pid);
+ }
+ };
+ for (const process of processes) {
+ if (collapsed.has(processIdentityKey(process))) {
+ hideDescendants(process.identity.pid);
+ }
+ }
+ return processes.filter((process) => !hidden.has(processIdentityKey(process)));
+}
+
+export function shouldShowResourceMonitorRetry(input: {
+ readonly nativeStatus: ResourceTelemetrySourceStatus | null;
+ readonly error: string | null;
+}): boolean {
+ return (
+ (input.nativeStatus === null && input.error !== null) ||
+ input.nativeStatus === "degraded" ||
+ input.nativeStatus === "unavailable" ||
+ input.nativeStatus === "stopped"
+ );
+}
+
+export function resourceHistoryBarHeight(input: {
+ readonly value: number;
+ readonly max: number;
+ readonly minimumVisiblePercent: number;
+}): number {
+ if (input.value <= 0) return 0;
+ return Math.max(input.minimumVisiblePercent, (input.value / Math.max(1, input.max)) * 100);
+}
+
+export function resourceHistoryCpuScaleMax(
+ buckets: ReadonlyArray<{ readonly avgCpuPercent: number }>,
+): number {
+ return Math.max(1, ...buckets.map((bucket) => bucket.avgCpuPercent));
+}
diff --git a/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx b/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx
new file mode 100644
index 000000000..d831c7637
--- /dev/null
+++ b/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx
@@ -0,0 +1,1268 @@
+import {
+ ActivityIcon,
+ AlertTriangleIcon,
+ BatteryIcon,
+ ChevronDownIcon,
+ ChevronRightIcon,
+ CpuIcon,
+ DatabaseIcon,
+ GaugeIcon,
+ HardDriveIcon,
+ MemoryStickIcon,
+ RefreshCwIcon,
+ RotateCcwIcon,
+} from "lucide-react";
+import type {
+ BackgroundBooleanState,
+ ResourceAttributionEntry,
+ ResourceTelemetryAggregate,
+ ResourceTelemetryHistoryBucket,
+ ResourceTelemetryIoSemantics,
+ ResourceTelemetryProcess,
+ ResourceTelemetryProcessCategory,
+ ResourceTelemetryProcessSummary,
+ ResourceTelemetrySourceHealth,
+ ResourceTelemetrySourceStatus,
+ ServerProcessSignal,
+} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+import { useCallback, useMemo, useState, type ReactNode } from "react";
+import {
+ isAtomCommandInterrupted,
+ squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+
+import {
+ useResourceTelemetry,
+ useResourceTelemetryHistory,
+} from "../../lib/resourceTelemetryState";
+import { cn } from "../../lib/utils";
+import { usePrimaryEnvironment } from "../../state/environments";
+import { serverEnvironment } from "../../state/server";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { formatRelativeTime } from "../../timestampFormat";
+import { Button } from "../ui/button";
+import { ScrollArea } from "../ui/scroll-area";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import { toastManager } from "../ui/toast";
+import {
+ resourceHistoryBarHeight,
+ resourceHistoryCpuScaleMax,
+ shouldShowResourceMonitorRetry,
+ visibleResourceTelemetryProcesses,
+} from "./ResourceTelemetryDiagnostics.logic";
+import { SettingsSection, useRelativeTimeTick } from "./settingsLayout";
+
+const HISTORY_WINDOWS = [
+ { label: "5m", windowMs: 5 * 60_000, bucketMs: 15_000 },
+ { label: "15m", windowMs: 15 * 60_000, bucketMs: 30_000 },
+ { label: "30m", windowMs: 30 * 60_000, bucketMs: 60_000 },
+ { label: "1h", windowMs: 60 * 60_000, bucketMs: 2 * 60_000 },
+] as const;
+
+function formatBytes(value: number): string {
+ if (value < 1_024) return `${Math.round(value)} B`;
+ const units = ["KB", "MB", "GB", "TB"] as const;
+ let next = value;
+ let unitIndex = -1;
+ do {
+ next /= 1_024;
+ unitIndex += 1;
+ } while (next >= 1_024 && unitIndex < units.length - 1);
+ return `${next.toFixed(next >= 100 ? 0 : next >= 10 ? 1 : 2)} ${units[unitIndex]}`;
+}
+
+function formatRate(value: number): string {
+ return `${formatBytes(value)}/s`;
+}
+
+function formatCpuTime(valueMs: number): string {
+ const seconds = valueMs / 1_000;
+ if (seconds < 60) return `${seconds.toFixed(seconds >= 10 ? 1 : 2)}s`;
+ const minutes = seconds / 60;
+ if (minutes < 60) return `${minutes.toFixed(minutes >= 10 ? 1 : 2)}m`;
+ return `${(minutes / 60).toFixed(2)}h`;
+}
+
+function formatDurationMicros(value: number): string {
+ if (value < 1_000) return `${Math.round(value)} µs`;
+ if (value < 1_000_000) return `${(value / 1_000).toFixed(2)} ms`;
+ return `${(value / 1_000_000).toFixed(2)} s`;
+}
+
+function formatSampleInterval(valueMs: number): string {
+ if (valueMs < 1_000) return `${Math.max(0, Math.round(valueMs))} ms`;
+ const seconds = valueMs / 1_000;
+ return `${seconds.toLocaleString(undefined, { maximumFractionDigits: 1 })} ${
+ seconds === 1 ? "second" : "seconds"
+ }`;
+}
+
+function processIdentityKey(process: ResourceTelemetryProcess): string {
+ return `${process.identity.pid}:${process.identity.startTimeMs}`;
+}
+
+function processSummaryIdentityKey(process: ResourceTelemetryProcessSummary): string {
+ return `${process.identity.pid}:${process.identity.startTimeMs}`;
+}
+
+function formatProcessName(process: Pick<ResourceTelemetryProcess, "command" | "name">): string {
+ if (process.name.trim()) return process.name;
+ const firstToken = process.command.trim().split(/\s+/)[0] ?? process.command;
+ const normalized = firstToken.replace(/^['"]|['"]$/g, "");
+ return normalized.split(/[\\/]/).findLast((segment) => segment.length > 0) ?? normalized;
+}
+
+function categoryLabel(category: ResourceTelemetryProcessCategory): string {
+ switch (category) {
+ case "server":
+ return "Server";
+ case "server-child":
+ return "Backend child";
+ case "provider-root":
+ return "Provider";
+ case "terminal-root":
+ return "Terminal";
+ case "electron-main":
+ return "Electron main";
+ case "electron-renderer":
+ return "Renderer";
+ case "electron-gpu":
+ return "GPU";
+ case "electron-utility":
+ return "Electron utility";
+ case "resource-monitor":
+ return "Monitor";
+ case "unknown-t3":
+ return "T3 process";
+ }
+}
+
+function categoryDotClass(category: ResourceTelemetryProcessCategory): string {
+ if (category === "resource-monitor") return "bg-amber-500";
+ if (category.startsWith("electron-")) return "bg-sky-500";
+ if (category === "server") return "bg-violet-500";
+ return "bg-emerald-500";
+}
+
+function ioSemanticsLabel(semantics: ResourceTelemetryIoSemantics): string {
+ switch (semantics) {
+ case "storage":
+ return "Storage bytes";
+ case "logical":
+ return "Logical bytes";
+ case "all-io":
+ return "All I/O bytes";
+ case "unavailable":
+ return "Unavailable";
+ }
+}
+
+function booleanStateLabel(
+ value: BackgroundBooleanState,
+ labels: { readonly true: string; readonly false: string },
+): string {
+ if (value === "true") return labels.true;
+ if (value === "false") return labels.false;
+ return "Unknown";
+}
+
+function sourceStatusTone(status: ResourceTelemetrySourceStatus): "default" | "warning" | "danger" {
+ if (status === "healthy") return "default";
+ if (status === "starting" || status === "degraded") return "warning";
+ return "danger";
+}
+
+function SourceStatusBadge({
+ label,
+ status,
+ presentation,
+}: {
+ label: string;
+ status: ResourceTelemetrySourceStatus;
+ presentation?:
+ | {
+ readonly label: string;
+ readonly tone: "neutral";
+ }
+ | undefined;
+}) {
+ const tone = presentation?.tone ?? sourceStatusTone(status);
+ return (
+ <span
+ className={cn(
+ "inline-flex items-center gap-1.5 rounded-full border px-2.5 py-1 text-[10px] font-semibold uppercase tracking-[0.08em]",
+ tone === "neutral" && "border-border/70 bg-muted/45 text-muted-foreground",
+ tone === "default" &&
+ "border-emerald-500/25 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300",
+ tone === "warning" &&
+ "border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-300",
+ tone === "danger" && "border-destructive/30 bg-destructive/10 text-destructive",
+ )}
+ >
+ <span
+ className={cn(
+ "size-1.5 rounded-full",
+ tone === "neutral" && "bg-muted-foreground/55",
+ tone === "default" && "bg-emerald-500",
+ tone === "warning" && "bg-amber-500",
+ tone === "danger" && "bg-destructive",
+ )}
+ />
+ {label} {presentation?.label ?? status}
+ </span>
+ );
+}
+
+function LastSampleLabel({ sampledAt }: { sampledAt: DateTime.Utc | null }) {
+ useRelativeTimeTick();
+ if (!sampledAt) {
+ return <span className="text-[11px] text-muted-foreground/55">Waiting for sample</span>;
+ }
+ const relative = formatRelativeTime(DateTime.formatIso(sampledAt));
+ if (!relative) {
+ return <span className="text-[11px] text-muted-foreground/55">Waiting for sample</span>;
+ }
+ return (
+ <span className="text-[11px] text-muted-foreground/60">
+ Updated <span className="font-mono tabular-nums">{relative.value}</span>
+ {relative.suffix ? ` ${relative.suffix}` : ""}
+ </span>
+ );
+}
+
+function IconStat({
+ icon,
+ label,
+ value,
+ detail,
+ tone = "default",
+}: {
+ icon: ReactNode;
+ label: string;
+ value: string;
+ detail?: string | undefined;
+ tone?: "default" | "warning" | "danger";
+}) {
+ return (
+ <div className="group min-w-0 px-4 py-4 sm:px-5">
+ <div className="flex items-center gap-2 text-[10px] font-semibold uppercase tracking-[0.11em] text-muted-foreground/70">
+ <span className="text-muted-foreground/55 transition-colors group-hover:text-foreground/65">
+ {icon}
+ </span>
+ <span className="truncate">{label}</span>
+ </div>
+ <div
+ className={cn(
+ "mt-2.5 truncate font-mono text-2xl font-semibold tracking-[-0.05em] tabular-nums text-foreground",
+ tone === "warning" && "text-amber-600 dark:text-amber-300",
+ tone === "danger" && "text-destructive",
+ )}
+ >
+ {value}
+ </div>
+ {detail ? (
+ <div className="mt-1.5 truncate text-[10px] text-muted-foreground/60">{detail}</div>
+ ) : null}
+ </div>
+ );
+}
+
+function AggregateCard({
+ label,
+ accentClass,
+ aggregate,
+}: {
+ label: string;
+ accentClass: string;
+ aggregate: ResourceTelemetryAggregate;
+}) {
+ return (
+ <div className="relative overflow-hidden border-t border-border/60 px-4 py-4 first:border-t-0 md:border-t-0 md:border-l md:first:border-l-0 sm:px-5">
+ <span className={cn("absolute inset-x-5 top-0 h-0.5 rounded-full opacity-75", accentClass)} />
+ <div className="flex items-center justify-between gap-3">
+ <div className="text-[10px] font-semibold uppercase tracking-[0.11em] text-muted-foreground/75">
+ {label}
+ </div>
+ <div className="rounded-md bg-muted/55 px-1.5 py-0.5 font-mono text-[9px] tabular-nums text-muted-foreground/70">
+ {aggregate.processCount} {aggregate.processCount === 1 ? "process" : "processes"}
+ </div>
+ </div>
+ <div className="mt-3.5 grid grid-cols-2 gap-x-4 gap-y-2.5">
+ <MetricPair label="CPU" value={`${aggregate.currentCpuPercent.toFixed(1)}%`} />
+ <MetricPair label="Memory" value={formatBytes(aggregate.currentRssBytes)} />
+ <MetricPair label="Read" value={formatRate(aggregate.ioReadBytesPerSecond)} />
+ <MetricPair label="Write" value={formatRate(aggregate.ioWriteBytesPerSecond)} />
+ </div>
+ </div>
+ );
+}
+
+function MetricPair({ label, value }: { label: string; value: string }) {
+ return (
+ <div className="min-w-0">
+ <div className="text-[9px] font-semibold uppercase tracking-[0.08em] text-muted-foreground/45">
+ {label}
+ </div>
+ <div className="truncate font-mono text-xs font-medium tabular-nums text-foreground/90">
+ {value}
+ </div>
+ </div>
+ );
+}
+
+function HealthSource({ label, health }: { label: string; health: ResourceTelemetrySourceHealth }) {
+ const expectedInBrowser =
+ health.status === "unavailable" &&
+ Option.exists(health.lastError, (error) => error.includes("'web' mode"));
+ return (
+ <div className="flex items-start justify-between gap-4 border-t border-border/50 py-3 first:border-t-0">
+ <div className="min-w-0">
+ <div className="text-[13px] font-medium text-foreground">{label}</div>
+ <div className="mt-1 text-[11px] leading-relaxed text-muted-foreground/65">
+ {expectedInBrowser
+ ? "Available when this page runs inside the desktop app."
+ : Option.match(health.lastError, {
+ onNone: () => "No reported errors",
+ onSome: (error) => error,
+ })}
+ </div>
+ </div>
+ <SourceStatusBadge
+ label=""
+ status={health.status}
+ presentation={
+ expectedInBrowser
+ ? {
+ label: "Desktop only",
+ tone: "neutral",
+ }
+ : undefined
+ }
+ />
+ </div>
+ );
+}
+
+function DetailRow({
+ label,
+ value,
+ valueClassName,
+}: {
+ label: string;
+ value: ReactNode;
+ valueClassName?: string | undefined;
+}) {
+ return (
+ <div className="flex items-center justify-between gap-4 border-t border-border/50 py-2.5 first:border-t-0">
+ <span className="text-[11px] text-muted-foreground/75">{label}</span>
+ <span
+ className={cn(
+ "min-w-0 truncate text-right font-mono text-[11px] tabular-nums text-foreground/85",
+ valueClassName,
+ )}
+ >
+ {value}
+ </span>
+ </div>
+ );
+}
+
+function HistoryWindowSelector({
+ selectedWindowMs,
+ onSelect,
+}: {
+ selectedWindowMs: number;
+ onSelect: (windowMs: number) => void;
+}) {
+ return (
+ <div className="flex items-center rounded-md border border-border/60 p-0.5">
+ {HISTORY_WINDOWS.map((option) => (
+ <button
+ key={option.windowMs}
+ type="button"
+ className={cn(
+ "h-6 rounded-sm px-2 text-[11px] font-medium text-muted-foreground hover:text-foreground",
+ selectedWindowMs === option.windowMs && "bg-muted text-foreground",
+ )}
+ onClick={() => onSelect(option.windowMs)}
+ >
+ {option.label}
+ </button>
+ ))}
+ </div>
+ );
+}
+
+function ResourceHistoryChart({
+ buckets,
+}: {
+ buckets: ReadonlyArray<ResourceTelemetryHistoryBucket>;
+}) {
+ const maxCpu = resourceHistoryCpuScaleMax(buckets);
+ const maxIo = Math.max(1, ...buckets.map((bucket) => bucket.ioReadBytes + bucket.ioWriteBytes));
+
+ return (
+ <div className="border-t border-border/60 px-4 py-4 sm:px-5">
+ <div className="mb-3 flex flex-wrap items-center gap-x-4 gap-y-1 text-[10px] text-muted-foreground/65">
+ <span className="inline-flex items-center gap-1.5">
+ <span className="h-1.5 w-3 rounded-full bg-foreground/70" /> CPU average
+ </span>
+ <span className="inline-flex items-center gap-1.5">
+ <span className="h-1.5 w-3 rounded-full bg-sky-500/70" /> I/O reads
+ </span>
+ <span className="inline-flex items-center gap-1.5">
+ <span className="h-1.5 w-3 rounded-full bg-amber-500/80" /> I/O writes
+ </span>
+ </div>
+ <div className="flex h-32 items-end gap-1 overflow-hidden rounded-lg border border-border/40 bg-muted/8 px-2 pt-3 pb-2">
+ {buckets.map((bucket) => {
+ const cpuHeight = resourceHistoryBarHeight({
+ value: bucket.avgCpuPercent,
+ max: maxCpu,
+ minimumVisiblePercent: 2,
+ });
+ const readHeight = resourceHistoryBarHeight({
+ value: bucket.ioReadBytes,
+ max: maxIo,
+ minimumVisiblePercent: 1,
+ });
+ const writeHeight = resourceHistoryBarHeight({
+ value: bucket.ioWriteBytes,
+ max: maxIo,
+ minimumVisiblePercent: 1,
+ });
+ return (
+ <Tooltip key={DateTime.formatIso(bucket.startedAt)}>
+ <TooltipTrigger
+ render={
+ <div className="grid h-full min-w-1 flex-1 grid-cols-3 items-end gap-px">
+ <span
+ className="block rounded-t-sm bg-foreground/65"
+ style={{ height: `${cpuHeight}%` }}
+ />
+ <span
+ className="block rounded-t-sm bg-sky-500/70"
+ style={{ height: `${readHeight}%` }}
+ />
+ <span
+ className="block rounded-t-sm bg-amber-500/80"
+ style={{ height: `${writeHeight}%` }}
+ />
+ </div>
+ }
+ />
+ <TooltipPopup side="top" className="space-y-0.5 text-left">
+ <div>CPU avg {bucket.avgCpuPercent.toFixed(1)}%</div>
+ <div>CPU peak {bucket.maxCpuPercent.toFixed(1)}%</div>
+ <div>Read {formatBytes(bucket.ioReadBytes)}</div>
+ <div>Write {formatBytes(bucket.ioWriteBytes)}</div>
+ </TooltipPopup>
+ </Tooltip>
+ );
+ })}
+ </div>
+ </div>
+ );
+}
+
+function ProcessTreeName({
+ process,
+ collapsed,
+ onToggle,
+}: {
+ process: ResourceTelemetryProcess;
+ collapsed: boolean;
+ onToggle: (process: ResourceTelemetryProcess) => void;
+}) {
+ const name = formatProcessName(process);
+ const hasChildren = process.childPids.length > 0;
+ const ChevronIcon = collapsed ? ChevronRightIcon : ChevronDownIcon;
+ return (
+ <div
+ className="grid min-w-0 grid-cols-[1.25rem_0.375rem_minmax(0,1fr)] items-center gap-2"
+ style={{ paddingLeft: `${Math.min(process.depth, 7) * 10}px` }}
+ >
+ {hasChildren ? (
+ <button
+ type="button"
+ className="inline-flex size-5 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground"
+ onClick={() => onToggle(process)}
+ aria-label={collapsed ? `Expand ${name}` : `Collapse ${name}`}
+ >
+ <ChevronIcon className="size-3.5" />
+ </button>
+ ) : (
+ <span className="size-5" aria-hidden />
+ )}
+ <span className={cn("size-1.5 rounded-full", categoryDotClass(process.category))} />
+ <Tooltip>
+ <TooltipTrigger
+ render={<span className="min-w-0 truncate font-medium text-foreground">{name}</span>}
+ />
+ <TooltipPopup
+ side="top"
+ className="max-w-[min(520px,calc(100vw-2rem))] whitespace-normal break-words text-left font-mono text-[11px]"
+ >
+ {process.command || process.name}
+ </TooltipPopup>
+ </Tooltip>
+ </div>
+ );
+}
+
+function canSignalProcess(process: ResourceTelemetryProcess): boolean {
+ return (
+ process.category === "server-child" ||
+ process.category === "provider-root" ||
+ process.category === "terminal-root"
+ );
+}
+
+function ProcessActions({
+ process,
+ signalingKeys,
+ onSignal,
+}: {
+ process: ResourceTelemetryProcess;
+ signalingKeys: ReadonlySet<string>;
+ onSignal: (process: ResourceTelemetryProcess, signal: ServerProcessSignal) => void;
+}) {
+ if (!canSignalProcess(process)) {
+ return <span className="text-[10px] text-muted-foreground/35">—</span>;
+ }
+ const isSignaling = signalingKeys.has(processIdentityKey(process));
+ return (
+ <div className="flex items-center justify-end gap-1.5">
+ <button
+ type="button"
+ disabled={isSignaling}
+ className="text-[10px] font-semibold text-muted-foreground hover:text-foreground disabled:opacity-50"
+ onClick={() => onSignal(process, "SIGINT")}
+ >
+ INT
+ </button>
+ <button
+ type="button"
+ disabled={isSignaling}
+ className="text-[10px] font-semibold text-destructive hover:underline disabled:opacity-50"
+ onClick={() => onSignal(process, "SIGKILL")}
+ >
+ KILL
+ </button>
+ </div>
+ );
+}
+
+function ProcessTable({
+ processes,
+ signalingKeys,
+ onSignal,
+}: {
+ processes: ReadonlyArray<ResourceTelemetryProcess>;
+ signalingKeys: ReadonlySet<string>;
+ onSignal: (process: ResourceTelemetryProcess, signal: ServerProcessSignal) => void;
+}) {
+ const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(() => new Set());
+ const visible = useMemo(
+ () => visibleResourceTelemetryProcesses(processes, collapsed),
+ [collapsed, processes],
+ );
+ const toggle = useCallback((process: ResourceTelemetryProcess) => {
+ const identityKey = processIdentityKey(process);
+ setCollapsed((current) => {
+ const next = new Set(current);
+ if (next.has(identityKey)) {
+ next.delete(identityKey);
+ } else {
+ next.add(identityKey);
+ }
+ return next;
+ });
+ }, []);
+
+ return (
+ <ScrollArea
+ chainVerticalScroll
+ scrollFade
+ hideScrollbars
+ className="max-h-[min(68vh,48rem)] w-full max-w-full border-t border-border/60"
+ >
+ <table className="w-full min-w-[1320px] table-fixed text-left text-xs">
+ <colgroup>
+ <col className="w-[20%]" />
+ <col className="w-[10%]" />
+ <col className="w-[7%]" />
+ <col className="w-[8%]" />
+ <col className="w-[9%]" />
+ <col className="w-[9%]" />
+ <col className="w-[9%]" />
+ <col className="w-[10%]" />
+ <col className="w-[8%]" />
+ <col className="w-[6%]" />
+ <col className="w-[4%]" />
+ </colgroup>
+ <thead className="sticky top-0 z-10 border-b border-border/60 bg-card text-[10px] uppercase tracking-[0.08em] text-muted-foreground/65">
+ <tr>
+ <th className="px-4 py-2 font-semibold sm:pl-5">Process</th>
+ <th className="px-3 py-2 font-semibold">Category</th>
+ <th className="px-3 py-2 text-right font-semibold">CPU</th>
+ <th className="px-3 py-2 text-right font-semibold">CPU Time</th>
+ <th className="px-3 py-2 text-right font-semibold">Memory</th>
+ <th className="px-3 py-2 text-right font-semibold">Read/s</th>
+ <th className="px-3 py-2 text-right font-semibold">Write/s</th>
+ <th className="px-3 py-2 text-right font-semibold">Read Total</th>
+ <th className="px-3 py-2 text-right font-semibold">Write Total</th>
+ <th className="px-3 py-2 text-right font-semibold">PID</th>
+ <th className="px-2 py-2 text-right font-semibold sm:pr-4">Kill</th>
+ </tr>
+ </thead>
+ <tbody className="divide-y divide-border/50">
+ {visible.length === 0 ? (
+ <tr>
+ <td colSpan={11} className="px-4 py-5 text-xs text-muted-foreground sm:px-5">
+ Waiting for the native process monitor.
+ </td>
+ </tr>
+ ) : null}
+ {visible.map((process) => (
+ <tr key={processIdentityKey(process)} className="hover:bg-muted/20">
+ <td className="px-4 py-2 sm:pl-5">
+ <ProcessTreeName
+ process={process}
+ collapsed={collapsed.has(processIdentityKey(process))}
+ onToggle={toggle}
+ />
+ </td>
+ <td className="truncate px-3 py-2 text-[11px] text-muted-foreground">
+ {categoryLabel(process.category)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums">
+ {process.cpuPercent.toFixed(1)}%
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums">
+ {formatCpuTime(process.cpuTimeMs)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums">
+ {formatBytes(process.residentBytes)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-sky-700 dark:text-sky-300">
+ {formatRate(process.ioReadBytesPerSecond)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-amber-700 dark:text-amber-300">
+ {formatRate(process.ioWriteBytesPerSecond)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-muted-foreground">
+ {formatBytes(process.ioReadBytes)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-muted-foreground">
+ <Tooltip>
+ <TooltipTrigger render={<span>{formatBytes(process.ioWriteBytes)}</span>} />
+ <TooltipPopup side="top">{ioSemanticsLabel(process.ioSemantics)}</TooltipPopup>
+ </Tooltip>
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-muted-foreground">
+ {process.identity.pid}
+ </td>
+ <td className="px-2 py-2 text-right sm:pr-4">
+ <ProcessActions
+ process={process}
+ signalingKeys={signalingKeys}
+ onSignal={onSignal}
+ />
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </ScrollArea>
+ );
+}
+
+function HistoryProcessTable({
+ processes,
+}: {
+ processes: ReadonlyArray<ResourceTelemetryProcessSummary>;
+}) {
+ return (
+ <ScrollArea
+ chainVerticalScroll
+ scrollFade
+ hideScrollbars
+ className="max-h-[28rem] w-full max-w-full border-t border-border/60"
+ >
+ <table className="w-full min-w-[1020px] table-fixed text-left text-xs">
+ <colgroup>
+ <col className="w-[24%]" />
+ <col className="w-[11%]" />
+ <col className="w-[10%]" />
+ <col className="w-[10%]" />
+ <col className="w-[11%]" />
+ <col className="w-[11%]" />
+ <col className="w-[11%]" />
+ <col className="w-[7%]" />
+ <col className="w-[5%]" />
+ </colgroup>
+ <thead className="sticky top-0 z-10 border-b border-border/60 bg-card text-[10px] uppercase tracking-[0.08em] text-muted-foreground/65">
+ <tr>
+ <th className="px-4 py-2 font-semibold sm:pl-5">Process</th>
+ <th className="px-3 py-2 font-semibold">Category</th>
+ <th className="px-3 py-2 text-right font-semibold">CPU Time</th>
+ <th className="px-3 py-2 text-right font-semibold">Peak CPU</th>
+ <th className="px-3 py-2 text-right font-semibold">Peak Mem</th>
+ <th className="px-3 py-2 text-right font-semibold">Read</th>
+ <th className="px-3 py-2 text-right font-semibold">Write</th>
+ <th className="px-3 py-2 text-right font-semibold">Samples</th>
+ <th className="px-3 py-2 text-right font-semibold sm:pr-5">PID</th>
+ </tr>
+ </thead>
+ <tbody className="divide-y divide-border/50">
+ {processes.length === 0 ? (
+ <tr>
+ <td colSpan={9} className="px-4 py-5 text-xs text-muted-foreground sm:px-5">
+ No retained process samples in this window.
+ </td>
+ </tr>
+ ) : null}
+ {processes.map((process) => (
+ <tr key={processSummaryIdentityKey(process)} className="hover:bg-muted/20">
+ <td className="px-4 py-2 sm:pl-5">
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <span className="block truncate font-medium text-foreground">
+ {process.name || process.command}
+ </span>
+ }
+ />
+ <TooltipPopup
+ side="top"
+ className="max-w-[min(520px,calc(100vw-2rem))] whitespace-normal break-words text-left font-mono text-[11px]"
+ >
+ {process.command || process.name}
+ </TooltipPopup>
+ </Tooltip>
+ </td>
+ <td className="truncate px-3 py-2 text-[11px] text-muted-foreground">
+ {categoryLabel(process.category)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums">
+ {formatCpuTime(process.cpuTimeMs)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums">
+ {process.maxCpuPercent.toFixed(1)}%
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums">
+ {formatBytes(process.peakRssBytes)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-sky-700 dark:text-sky-300">
+ {formatBytes(process.ioReadBytes)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-amber-700 dark:text-amber-300">
+ {formatBytes(process.ioWriteBytes)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-muted-foreground">
+ {process.sampleCount}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-muted-foreground sm:pr-5">
+ {process.identity.pid}
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </ScrollArea>
+ );
+}
+
+function AttributionTable({ entries }: { entries: ReadonlyArray<ResourceAttributionEntry> }) {
+ return (
+ <div className="overflow-x-auto border-t border-border/60">
+ <table className="w-full min-w-[720px] table-fixed text-left text-xs">
+ <colgroup>
+ <col className="w-[22%]" />
+ <col className="w-[28%]" />
+ <col className="w-[14%]" />
+ <col className="w-[14%]" />
+ <col className="w-[10%]" />
+ <col className="w-[12%]" />
+ </colgroup>
+ <thead className="border-b border-border/60 text-[10px] uppercase tracking-[0.08em] text-muted-foreground/65">
+ <tr>
+ <th className="px-4 py-2 font-semibold sm:pl-5">Component</th>
+ <th className="px-3 py-2 font-semibold">Operation</th>
+ <th className="px-3 py-2 text-right font-semibold">Logical Read</th>
+ <th className="px-3 py-2 text-right font-semibold">Logical Write</th>
+ <th className="px-3 py-2 text-right font-semibold">Count</th>
+ <th className="px-3 py-2 text-right font-semibold sm:pr-5">Time</th>
+ </tr>
+ </thead>
+ <tbody className="divide-y divide-border/50">
+ {entries.length === 0 ? (
+ <tr>
+ <td colSpan={6} className="px-4 py-5 text-xs text-muted-foreground sm:px-5">
+ No instrumented application I/O has been recorded yet.
+ </td>
+ </tr>
+ ) : null}
+ {entries.map((entry) => (
+ <tr key={`${entry.component}:${entry.operation}`} className="hover:bg-muted/20">
+ <td className="truncate px-4 py-2 font-medium text-foreground sm:pl-5">
+ {entry.component}
+ </td>
+ <td className="truncate px-3 py-2 text-muted-foreground">{entry.operation}</td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-sky-700 dark:text-sky-300">
+ {formatBytes(entry.logicalReadBytes)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-amber-700 dark:text-amber-300">
+ {formatBytes(entry.logicalWriteBytes)}
+ </td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums">{entry.count}</td>
+ <td className="px-3 py-2 text-right font-mono tabular-nums text-muted-foreground sm:pr-5">
+ {(entry.durationMs / 1_000).toFixed(2)}s
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </div>
+ );
+}
+
+export function ResourceTelemetryDiagnostics() {
+ const [windowMs, setWindowMs] = useState(15 * 60_000);
+ const selectedWindow =
+ HISTORY_WINDOWS.find((option) => option.windowMs === windowMs) ?? HISTORY_WINDOWS[1];
+ const telemetry = useResourceTelemetry();
+ const retryTelemetry = telemetry.retry;
+ const history = useResourceTelemetryHistory({
+ windowMs: selectedWindow.windowMs,
+ bucketMs: selectedWindow.bucketMs,
+ });
+ const primaryEnvironment = usePrimaryEnvironment();
+ const signalServerProcess = useAtomCommand(serverEnvironment.signalProcess, {
+ reportFailure: false,
+ });
+ const [signalingKeys, setSignalingKeys] = useState<ReadonlySet<string>>(() => new Set());
+ const [isRetrying, setIsRetrying] = useState(false);
+ const snapshot = telemetry.data;
+ const allT3 = snapshot?.groups.allT3;
+
+ const signalProcess = useCallback(
+ (process: ResourceTelemetryProcess, signal: ServerProcessSignal) => {
+ if (
+ signal === "SIGKILL" &&
+ !window.confirm(
+ `Send SIGKILL to process ${process.identity.pid}? This cannot be handled by the process.`,
+ )
+ ) {
+ return;
+ }
+ const identityKey = processIdentityKey(process);
+ const environmentId = primaryEnvironment?.environmentId;
+ if (environmentId === undefined) {
+ return;
+ }
+ setSignalingKeys((current) => new Set(current).add(identityKey));
+ void signalServerProcess({
+ environmentId,
+ input: {
+ pid: process.identity.pid,
+ startTimeMs: process.identity.startTimeMs,
+ signal,
+ },
+ })
+ .then((result) => {
+ if (result._tag === "Failure") {
+ if (isAtomCommandInterrupted(result)) return;
+ throw squashAtomCommandFailure(result);
+ }
+ if (result.value.signaled) return;
+ toastManager.add({
+ type: "error",
+ title: `Could not send ${signal}`,
+ description: Option.getOrElse(
+ result.value.message,
+ () => `Failed to send ${signal} to process ${process.identity.pid}.`,
+ ),
+ });
+ })
+ .catch((error: unknown) => {
+ toastManager.add({
+ type: "error",
+ title: `Could not send ${signal}`,
+ description: error instanceof Error ? error.message : `Failed to send ${signal}.`,
+ });
+ })
+ .finally(() => {
+ setSignalingKeys((current) => {
+ if (!current.has(identityKey)) return current;
+ const next = new Set(current);
+ next.delete(identityKey);
+ return next;
+ });
+ });
+ },
+ [primaryEnvironment?.environmentId, signalServerProcess],
+ );
+
+ const retryCollector = useCallback(() => {
+ setIsRetrying(true);
+ void retryTelemetry()
+ .catch((error: unknown) => {
+ toastManager.add({
+ type: "error",
+ title: "Could not restart resource monitor",
+ description:
+ error instanceof Error ? error.message : "The resource monitor retry failed.",
+ });
+ })
+ .finally(() => {
+ setIsRetrying(false);
+ });
+ }, [retryTelemetry]);
+
+ const speedLimit = snapshot ? Option.getOrNull(snapshot.speedLimitPercent) : null;
+ const collectorNeedsRetry = shouldShowResourceMonitorRetry({
+ nativeStatus: snapshot?.health.native.status ?? null,
+ error: telemetry.error,
+ });
+ const hasHostPowerSignal =
+ snapshot !== null &&
+ (snapshot.power.onBattery !== "unknown" ||
+ snapshot.power.lowPowerMode !== "unknown" ||
+ snapshot.power.idle !== "unknown" ||
+ snapshot.power.locked !== "unknown" ||
+ snapshot.power.thermalState !== "unknown");
+
+ return (
+ <>
+ <SettingsSection
+ title="Resource monitor"
+ icon={<ActivityIcon className="size-4 text-muted-foreground" />}
+ headerAction={
+ <div className="flex items-center gap-2">
+ {snapshot ? (
+ <SourceStatusBadge label="Native" status={snapshot.health.native.status} />
+ ) : null}
+ <LastSampleLabel sampledAt={snapshot?.readAt ?? null} />
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <Button
+ size="icon-xs"
+ variant="ghost"
+ className="size-5 rounded-sm p-0"
+ disabled={telemetry.isPending}
+ onClick={telemetry.refresh}
+ aria-label="Refresh resource telemetry"
+ >
+ <RefreshCwIcon
+ className={cn("size-3", telemetry.isPending && "animate-spin")}
+ />
+ </Button>
+ }
+ />
+ <TooltipPopup side="top">Refresh telemetry snapshot</TooltipPopup>
+ </Tooltip>
+ </div>
+ }
+ >
+ <div className="overflow-hidden rounded-2xl border border-border/70 bg-card shadow-[0_1px_1px_rgb(0_0_0/0.03),0_8px_30px_rgb(0_0_0/0.035)]">
+ <div className="flex flex-col gap-3 border-b border-border/60 bg-linear-to-r from-muted/45 via-muted/20 to-transparent px-4 py-4 sm:flex-row sm:items-center sm:justify-between sm:px-5">
+ <div>
+ <div className="text-[10px] font-semibold uppercase tracking-[0.14em] text-muted-foreground/70">
+ T3 system footprint
+ </div>
+ <p className="mt-1 max-w-xl text-xs leading-relaxed text-muted-foreground">
+ Live native counters for the server, providers, terminals, desktop processes, and
+ the monitor itself.
+ </p>
+ </div>
+ <div className="flex items-center gap-2 text-[10px] text-muted-foreground/65">
+ <span className="size-1.5 rounded-full bg-emerald-500" />
+ Sampling every {snapshot ? formatSampleInterval(snapshot.sampleIntervalMs) : "..."}
+ </div>
+ </div>
+ <div className="grid grid-cols-2 divide-x divide-y divide-border/55 md:grid-cols-3">
+ <IconStat
+ icon={<CpuIcon className="size-3.5" />}
+ label="Current CPU"
+ value={allT3 ? `${allT3.currentCpuPercent.toFixed(1)}%` : "..."}
+ detail={allT3 ? `${formatCpuTime(allT3.cpuTimeMs)} observed CPU time` : undefined}
+ />
+ <IconStat
+ icon={<MemoryStickIcon className="size-3.5" />}
+ label="Resident memory"
+ value={allT3 ? formatBytes(allT3.currentRssBytes) : "..."}
+ detail={
+ allT3 ? `${formatBytes(allT3.peakRssBytes)} combined process peaks` : undefined
+ }
+ />
+ <IconStat
+ icon={<ActivityIcon className="size-3.5" />}
+ label="Process count"
+ value={allT3 ? String(allT3.processCount) : "..."}
+ detail={
+ allT3 ? `${allT3.processStarts} starts · ${allT3.processExits} exits` : undefined
+ }
+ />
+ <IconStat
+ icon={<HardDriveIcon className="size-3.5" />}
+ label="Read throughput"
+ value={allT3 ? formatRate(allT3.ioReadBytesPerSecond) : "..."}
+ detail={allT3 ? `${formatBytes(allT3.ioReadBytes)} observed` : undefined}
+ />
+ <IconStat
+ icon={<DatabaseIcon className="size-3.5" />}
+ label="Write throughput"
+ value={allT3 ? formatRate(allT3.ioWriteBytesPerSecond) : "..."}
+ detail={allT3 ? `${formatBytes(allT3.ioWriteBytes)} observed` : undefined}
+ tone={
+ allT3 && allT3.ioWriteBytesPerSecond >= 10 * 1_024 * 1_024
+ ? "danger"
+ : allT3 && allT3.ioWriteBytesPerSecond >= 1_024 * 1_024
+ ? "warning"
+ : "default"
+ }
+ />
+ <IconStat
+ icon={<GaugeIcon className="size-3.5" />}
+ label="CPU speed limit"
+ value={
+ snapshot ? (speedLimit === null ? "Unknown" : `${speedLimit.toFixed(0)}%`) : "..."
+ }
+ detail={snapshot ? `${snapshot.power.thermalState} thermal state` : undefined}
+ tone={speedLimit !== null && speedLimit < 80 ? "warning" : "default"}
+ />
+ </div>
+ {telemetry.error ? (
+ <div className="flex items-start gap-2 border-t border-destructive/20 bg-destructive/5 px-4 py-3 text-xs text-destructive sm:px-5">
+ <AlertTriangleIcon className="mt-0.5 size-3.5 shrink-0" />
+ <span>{telemetry.error}</span>
+ </div>
+ ) : null}
+ {snapshot ? (
+ <div className="grid border-t border-border/60 bg-muted/10 md:grid-cols-3">
+ <AggregateCard
+ label="Backend + agents"
+ accentClass="bg-emerald-500/80"
+ aggregate={snapshot.groups.backend}
+ />
+ <AggregateCard
+ label="Desktop"
+ accentClass="bg-sky-500/80"
+ aggregate={snapshot.groups.electron}
+ />
+ <AggregateCard
+ label="Monitor overhead"
+ accentClass="bg-amber-500/80"
+ aggregate={snapshot.groups.monitor}
+ />
+ </div>
+ ) : null}
+ </div>
+ </SettingsSection>
+
+ <SettingsSection
+ title="Host & collection"
+ icon={<GaugeIcon className="size-4 text-muted-foreground" />}
+ headerAction={
+ collectorNeedsRetry ? (
+ <Button size="xs" variant="outline" disabled={isRetrying} onClick={retryCollector}>
+ <RotateCcwIcon className={cn("size-3", isRetrying && "animate-spin")} />
+ Retry monitor
+ </Button>
+ ) : null
+ }
+ >
+ <div className="grid overflow-hidden rounded-2xl border border-border/70 bg-card shadow-[0_1px_1px_rgb(0_0_0/0.03)] md:grid-cols-2 md:divide-x md:divide-border/60">
+ <div className="px-4 py-4 sm:px-5">
+ <div className="mb-3 flex items-center gap-2 text-[10px] font-semibold uppercase tracking-[0.12em] text-muted-foreground/70">
+ <span className="flex size-6 items-center justify-center rounded-md bg-muted/60">
+ <BatteryIcon className="size-3.5" />
+ </span>
+ Host state
+ </div>
+ {hasHostPowerSignal && snapshot ? (
+ <>
+ <DetailRow
+ label="Power source"
+ value={booleanStateLabel(snapshot.power.onBattery, {
+ true: "Battery",
+ false: "External power",
+ })}
+ />
+ <DetailRow
+ label="Low power mode"
+ value={booleanStateLabel(snapshot.power.lowPowerMode, {
+ true: "Enabled",
+ false: "Disabled",
+ })}
+ />
+ <DetailRow
+ label="Idle"
+ value={`${booleanStateLabel(snapshot.power.idle, {
+ true: "Idle",
+ false: "Active",
+ })}${
+ snapshot.power.idleSeconds === null
+ ? ""
+ : ` · ${Math.round(snapshot.power.idleSeconds)}s`
+ }`}
+ />
+ <DetailRow
+ label="Session"
+ value={
+ snapshot.power.suspended
+ ? "Suspended"
+ : booleanStateLabel(snapshot.power.locked, {
+ true: "Locked",
+ false: "Unlocked",
+ })
+ }
+ />
+ <DetailRow
+ label="Thermal"
+ value={snapshot.power.thermalState}
+ valueClassName={
+ snapshot.power.thermalState === "serious" ||
+ snapshot.power.thermalState === "critical"
+ ? "text-destructive"
+ : undefined
+ }
+ />
+ </>
+ ) : (
+ <div className="rounded-xl border border-dashed border-border/70 bg-muted/20 px-4 py-5">
+ <div className="text-[13px] font-medium text-foreground">
+ Desktop host signals not connected
+ </div>
+ <p className="mt-1.5 max-w-sm text-[11px] leading-relaxed text-muted-foreground/70">
+ Power, idle, lock, and thermal state are supplied by the desktop host. Process
+ telemetry remains fully active in this browser session.
+ </p>
+ </div>
+ )}
+ </div>
+ <div className="border-t border-border/60 px-4 py-4 md:border-t-0 sm:px-5">
+ <div className="mb-3 flex items-center gap-2 text-[10px] font-semibold uppercase tracking-[0.12em] text-muted-foreground/70">
+ <span className="flex size-6 items-center justify-center rounded-md bg-muted/60">
+ <GaugeIcon className="size-3.5" />
+ </span>
+ Collection health
+ </div>
+ {snapshot ? (
+ <>
+ <HealthSource label="Native process monitor" health={snapshot.health.native} />
+ <HealthSource label="Electron main process" health={snapshot.health.desktop} />
+ <DetailRow
+ label="Collection time"
+ value={formatDurationMicros(snapshot.health.collectionDurationMicros)}
+ />
+ <DetailRow
+ label="Process scan"
+ value={`${snapshot.health.retainedProcessCount}/${snapshot.health.scannedProcessCount} retained`}
+ />
+ <DetailRow
+ label="Inaccessible"
+ value={String(snapshot.health.inaccessibleProcessCount)}
+ valueClassName={
+ snapshot.health.inaccessibleProcessCount > 0
+ ? "text-amber-600 dark:text-amber-300"
+ : undefined
+ }
+ />
+ <DetailRow
+ label="Sidecar"
+ value={Option.match(snapshot.health.sidecarVersion, {
+ onNone: () => "Unavailable",
+ onSome: (version) =>
+ `${version}${Option.match(snapshot.health.sidecarPid, {
+ onNone: () => "",
+ onSome: (pid) => ` · PID ${pid}`,
+ })}`,
+ })}
+ />
+ <DetailRow label="Restarts" value={String(snapshot.health.restartCount)} />
+ </>
+ ) : (
+ <div className="py-4 text-xs text-muted-foreground">
+ Waiting for collector health.
+ </div>
+ )}
+ </div>
+ </div>
+ </SettingsSection>
+
+ <SettingsSection
+ title="Resource timeline"
+ icon={<HardDriveIcon className="size-4 text-muted-foreground" />}
+ headerAction={
+ <div className="flex items-center gap-2">
+ <HistoryWindowSelector selectedWindowMs={windowMs} onSelect={setWindowMs} />
+ <Button
+ size="icon-xs"
+ variant="ghost"
+ className="size-5 rounded-sm p-0"
+ disabled={history.isPending}
+ onClick={history.refresh}
+ aria-label="Refresh resource history"
+ >
+ <RefreshCwIcon className={cn("size-3", history.isPending && "animate-spin")} />
+ </Button>
+ </div>
+ }
+ >
+ <div className="overflow-hidden rounded-2xl border border-border/70 bg-card shadow-[0_1px_1px_rgb(0_0_0/0.03)]">
+ {history.error ? (
+ <div className="flex items-start gap-2 border-b border-destructive/20 bg-destructive/5 px-4 py-3 text-xs text-destructive sm:px-5">
+ <AlertTriangleIcon className="mt-0.5 size-3.5 shrink-0" />
+ <span>{history.error}</span>
+ </div>
+ ) : null}
+ <ResourceHistoryChart buckets={history.data?.buckets ?? []} />
+ <HistoryProcessTable processes={history.data?.topProcesses ?? []} />
+ </div>
+ </SettingsSection>
+
+ <SettingsSection
+ title="Live process tree"
+ icon={<CpuIcon className="size-4 text-muted-foreground" />}
+ headerAction={
+ snapshot ? (
+ <span className="text-[10px] text-muted-foreground/55">
+ Identity: <span className="font-mono">PID + start time</span>
+ </span>
+ ) : null
+ }
+ >
+ <div className="overflow-hidden rounded-2xl border border-border/70 bg-card shadow-[0_1px_1px_rgb(0_0_0/0.03)]">
+ <ProcessTable
+ processes={snapshot?.processes ?? []}
+ signalingKeys={signalingKeys}
+ onSignal={signalProcess}
+ />
+ </div>
+ </SettingsSection>
+
+ <SettingsSection
+ title="Instrumented application I/O"
+ icon={<DatabaseIcon className="size-4 text-muted-foreground" />}
+ headerAction={
+ <span className="text-[10px] text-muted-foreground/55">Logical bytes by operation</span>
+ }
+ >
+ <div className="overflow-hidden rounded-2xl border border-border/70 bg-card shadow-[0_1px_1px_rgb(0_0_0/0.03)]">
+ <div className="bg-muted/15 px-4 py-3 text-[11px] leading-relaxed text-muted-foreground sm:px-5">
+ Native counters identify which process is reading or writing. These application-level
+ counters identify known T3 operations so process spikes can be correlated with specific
+ persistence and logging paths.
+ </div>
+ <AttributionTable entries={snapshot?.attribution.entries ?? []} />
+ </div>
+ </SettingsSection>
+ </>
+ );
+}
diff --git a/apps/web/src/components/settings/SettingsPanels.logic.test.ts b/apps/web/src/components/settings/SettingsPanels.logic.test.ts
index 077991f8d..d0bdb58db 100644
--- a/apps/web/src/components/settings/SettingsPanels.logic.test.ts
+++ b/apps/web/src/components/settings/SettingsPanels.logic.test.ts
@@ -1,17 +1,126 @@
import {
DEFAULT_SERVER_SETTINGS,
+ DEFAULT_UNIFIED_SETTINGS,
ProviderDriverKind,
ProviderInstanceId,
type ProviderInstanceConfig,
} from "@t3tools/contracts";
+import { getBackgroundActivityPresetSettings } from "@t3tools/shared/backgroundActivitySettings";
+import * as Duration from "effect/Duration";
import { describe, expect, it } from "vite-plus/test";
import {
+ backgroundActivitySharedPolicySettings,
buildProviderInstanceUpdatePatch,
formatDiagnosticsDescription,
+ hasChangedBackgroundActivitySettings,
isProjectGroupingEnabled,
projectGroupingModeFromToggle,
+ resolveBackgroundActivityProfileOption,
} from "./SettingsPanels.logic";
+describe("background activity settings restore", () => {
+ it("detects legacy interval values even when the structured setting is at its default", () => {
+ expect(
+ hasChangedBackgroundActivitySettings({
+ backgroundActivity: DEFAULT_UNIFIED_SETTINGS.backgroundActivity,
+ backgroundActivityProfile: DEFAULT_UNIFIED_SETTINGS.backgroundActivityProfile,
+ automaticGitFetchInterval: Duration.seconds(45),
+ providerHealthRefreshInterval: DEFAULT_UNIFIED_SETTINGS.providerHealthRefreshInterval,
+ }),
+ ).toBe(true);
+ expect(
+ hasChangedBackgroundActivitySettings({
+ backgroundActivity: DEFAULT_UNIFIED_SETTINGS.backgroundActivity,
+ backgroundActivityProfile: DEFAULT_UNIFIED_SETTINGS.backgroundActivityProfile,
+ automaticGitFetchInterval: DEFAULT_UNIFIED_SETTINGS.automaticGitFetchInterval,
+ providerHealthRefreshInterval: Duration.minutes(7),
+ }),
+ ).toBe(true);
+ expect(hasChangedBackgroundActivitySettings(DEFAULT_UNIFIED_SETTINGS)).toBe(false);
+ });
+
+ it("detects a legacy profile override so restoring defaults clears it", () => {
+ expect(
+ hasChangedBackgroundActivitySettings({
+ ...DEFAULT_UNIFIED_SETTINGS,
+ backgroundActivityProfile: "performance",
+ }),
+ ).toBe(true);
+ });
+
+ it("shows the effective legacy preset and marks custom legacy intervals as advanced", () => {
+ const performance = getBackgroundActivityPresetSettings("performance");
+ expect(
+ resolveBackgroundActivityProfileOption({
+ ...DEFAULT_UNIFIED_SETTINGS,
+ backgroundActivity: DEFAULT_UNIFIED_SETTINGS.backgroundActivity,
+ backgroundActivityProfile: "performance",
+ automaticGitFetchInterval: performance.automaticGitFetchInterval,
+ providerHealthRefreshInterval: performance.providerHealthRefreshInterval,
+ }),
+ ).toBe("performance");
+
+ expect(
+ resolveBackgroundActivityProfileOption({
+ ...DEFAULT_UNIFIED_SETTINGS,
+ backgroundActivity: DEFAULT_UNIFIED_SETTINGS.backgroundActivity,
+ backgroundActivityProfile: "performance",
+ automaticGitFetchInterval: Duration.seconds(45),
+ providerHealthRefreshInterval: Duration.minutes(7),
+ }),
+ ).toBe("advanced");
+ });
+
+ it("preserves advanced overrides when the shared policy changes", () => {
+ const automaticGitFetchInterval = Duration.seconds(42);
+ expect(
+ backgroundActivitySharedPolicySettings(
+ {
+ ...DEFAULT_UNIFIED_SETTINGS,
+ backgroundActivity: {
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "balanced",
+ overrides: {
+ automaticGitFetchInterval,
+ pauseWhenOnBattery: true,
+ },
+ },
+ },
+ "performance",
+ ),
+ ).toEqual({
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "performance",
+ overrides: {
+ automaticGitFetchInterval,
+ pauseWhenOnBattery: true,
+ },
+ });
+ });
+
+ it("materializes legacy advanced overrides before changing the shared policy", () => {
+ const automaticGitFetchInterval = Duration.seconds(42);
+ expect(
+ backgroundActivitySharedPolicySettings(
+ {
+ ...DEFAULT_UNIFIED_SETTINGS,
+ automaticGitFetchInterval,
+ },
+ "battery-saver",
+ ),
+ ).toEqual({
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "battery-saver",
+ overrides: {
+ automaticGitFetchInterval,
+ },
+ });
+ });
+});
+
describe("project grouping toggle", () => {
it("enables repository grouping and disables into separate projects", () => {
expect(isProjectGroupingEnabled("repository")).toBe(true);
diff --git a/apps/web/src/components/settings/SettingsPanels.logic.ts b/apps/web/src/components/settings/SettingsPanels.logic.ts
index 51e318225..1d4baefa5 100644
--- a/apps/web/src/components/settings/SettingsPanels.logic.ts
+++ b/apps/web/src/components/settings/SettingsPanels.logic.ts
@@ -1,4 +1,6 @@
import type {
+ BackgroundActivityProfile,
+ BackgroundActivitySettings,
ProviderDriverKind,
ProviderInstanceConfig,
ProviderInstanceId,
@@ -7,6 +9,12 @@ import type {
UnifiedSettings,
} from "@t3tools/contracts";
import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
+import {
+ normalizeBackgroundActivitySettings,
+ normalizeServerBackgroundActivitySettings,
+ resolveServerBackgroundActivitySettings,
+} from "@t3tools/shared/backgroundActivitySettings";
+import * as Equal from "effect/Equal";
export function isProjectGroupingEnabled(mode: SidebarProjectGroupingMode): boolean {
return mode !== "separate";
@@ -41,6 +49,65 @@ export function rememberEnabledProjectGroupingMode(mode: SidebarProjectGroupingM
}
}
+export function hasChangedBackgroundActivitySettings(
+ settings: Pick<
+ UnifiedSettings,
+ | "backgroundActivity"
+ | "backgroundActivityProfile"
+ | "automaticGitFetchInterval"
+ | "providerHealthRefreshInterval"
+ >,
+): boolean {
+ return (
+ !Equal.equals(settings.backgroundActivity, DEFAULT_UNIFIED_SETTINGS.backgroundActivity) ||
+ settings.backgroundActivityProfile !== DEFAULT_UNIFIED_SETTINGS.backgroundActivityProfile ||
+ !Equal.equals(
+ settings.automaticGitFetchInterval,
+ DEFAULT_UNIFIED_SETTINGS.automaticGitFetchInterval,
+ ) ||
+ !Equal.equals(
+ settings.providerHealthRefreshInterval,
+ DEFAULT_UNIFIED_SETTINGS.providerHealthRefreshInterval,
+ )
+ );
+}
+
+export function resolveBackgroundActivityProfileOption(
+ settings: ServerSettings,
+): BackgroundActivityProfile | "advanced" {
+ const resolved = resolveServerBackgroundActivitySettings(settings);
+ const normalized = normalizeBackgroundActivitySettings({
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: resolved.profile,
+ overrides: {
+ automaticGitFetchInterval: resolved.automaticGitFetchInterval,
+ providerHealthRefreshInterval: resolved.providerHealthRefreshInterval,
+ hostPowerMonitorActiveInterval: resolved.hostPowerMonitorActiveInterval,
+ hostPowerMonitorIdleInterval: resolved.hostPowerMonitorIdleInterval,
+ idleClientTtl: resolved.idleClientTtl,
+ pauseWhenHostLocked: resolved.pauseWhenHostLocked,
+ pauseWhenHostLowPower: resolved.pauseWhenHostLowPower,
+ pauseWhenClientLowPower: resolved.pauseWhenClientLowPower,
+ pauseWhenOnBattery: resolved.pauseWhenOnBattery,
+ },
+ });
+ return normalized.profile === "custom" ? "advanced" : normalized.profile;
+}
+
+export function backgroundActivitySharedPolicySettings(
+ settings: ServerSettings,
+ profile: BackgroundActivityProfile,
+): BackgroundActivitySettings {
+ const normalized = normalizeServerBackgroundActivitySettings(settings);
+ return {
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: profile,
+ overrides: normalized.profile === "custom" ? normalized.overrides : {},
+ };
+}
+
function collapseOtelSignalsUrl(input: {
readonly tracesUrl: string;
readonly metricsUrl: string;
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 611cafc14..538575192 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1,10 +1,20 @@
-import { ArchiveIcon, ArchiveX, LoaderIcon, PlusIcon, RefreshCwIcon } from "lucide-react";
+import {
+ ArchiveIcon,
+ ArchiveX,
+ InfoIcon,
+ LoaderIcon,
+ PlusIcon,
+ RefreshCwIcon,
+ SettingsIcon,
+} from "lucide-react";
import { Link } from "@tanstack/react-router";
import type { CSSProperties } from "react";
import { useCallback, useMemo, useRef, useState } from "react";
import { useAtomValue } from "@effect/atom-react";
import {
defaultInstanceIdForDriver,
+ type BackgroundActivityProfile,
+ type BackgroundActivitySettings,
type DesktopUpdateChannel,
PROVIDER_DISPLAY_NAMES,
ProviderDriverKind,
@@ -27,6 +37,11 @@ import {
MAX_GLASS_OPACITY,
MIN_GLASS_OPACITY,
} from "@t3tools/contracts/settings";
+import {
+ getBackgroundActivityBaseProfile,
+ getBackgroundActivityPresetSettings,
+ resolveServerBackgroundActivitySettings,
+} from "@t3tools/shared/backgroundActivitySettings";
import { createModelSelection } from "@t3tools/shared/model";
import * as Arr from "effect/Array";
import * as Duration from "effect/Duration";
@@ -72,7 +87,23 @@ import { useProjects } from "../../state/entities";
import { useArchivedThreadSnapshots } from "../../lib/archivedThreadsState";
import { formatRelativeTimeLabel, getRelativeTimeState } from "../../timestampFormat";
import { Button } from "../ui/button";
+import {
+ Dialog,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogPanel,
+ DialogPopup,
+ DialogTitle,
+} from "../ui/dialog";
import { DraftInput } from "../ui/draft-input";
+import {
+ NumberField,
+ NumberFieldDecrement,
+ NumberFieldGroup,
+ NumberFieldIncrement,
+ NumberFieldInput,
+} from "../ui/number-field";
import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
import { Switch } from "../ui/switch";
import { stackedThreadToast, toastManager } from "../ui/toast";
@@ -88,12 +119,15 @@ import {
import { ProviderInstanceCard } from "./ProviderInstanceCard";
import { DRIVER_OPTIONS, getDriverOption } from "./providerDriverMeta";
import {
+ backgroundActivitySharedPolicySettings,
buildProviderInstanceUpdatePatch,
formatDiagnosticsDescription,
+ hasChangedBackgroundActivitySettings,
isProjectGroupingEnabled,
projectGroupingModeFromToggle,
readLastEnabledProjectGroupingMode,
rememberEnabledProjectGroupingMode,
+ resolveBackgroundActivityProfileOption,
} from "./SettingsPanels.logic";
import {
SettingResetButton,
@@ -132,7 +166,129 @@ const TIMESTAMP_FORMAT_LABELS = {
"24-hour": "24-hour",
} as const;
+const BACKGROUND_ACTIVITY_PROFILE_LABELS: Record<BackgroundActivityProfile, string> = {
+ balanced: "Balanced",
+ performance: "Performance",
+ "battery-saver": "Battery saver",
+};
+
+type BackgroundActivityProfileOption = BackgroundActivityProfile | "advanced";
+type BackgroundActivityOverridePatch = Partial<{
+ [K in keyof BackgroundActivitySettings["overrides"]]:
+ | BackgroundActivitySettings["overrides"][K]
+ | undefined;
+}>;
+
+const BACKGROUND_ACTIVITY_PROFILE_OPTION_LABELS: Record<BackgroundActivityProfileOption, string> = {
+ ...BACKGROUND_ACTIVITY_PROFILE_LABELS,
+ advanced: "Advanced",
+};
+
+const BACKGROUND_ACTIVITY_PROFILE_DESCRIPTIONS: Record<BackgroundActivityProfile, string> = {
+ balanced:
+ "Pauses background probes when clients are idle, the host is locked, or low power mode is active.",
+ performance: "Allows scoped background probes while any subscribed client remains connected.",
+ "battery-saver": "Also pauses background probes when the host or client is on battery.",
+};
+
+const ADVANCED_BACKGROUND_ACTIVITY_DESCRIPTION =
+ "Uses custom background intervals with the selected shared power policy.";
+
+const PROVIDER_HEALTH_INTERVAL_STEP_SECONDS = 30;
const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
+const BACKGROUND_ACTIVITY_BOOLEAN_OVERRIDES: ReadonlyArray<{
+ readonly key:
+ | "pauseWhenHostLocked"
+ | "pauseWhenHostLowPower"
+ | "pauseWhenClientLowPower"
+ | "pauseWhenOnBattery";
+ readonly label: string;
+}> = [
+ { key: "pauseWhenHostLocked", label: "Pause when host is locked" },
+ { key: "pauseWhenHostLowPower", label: "Pause on host low power" },
+ { key: "pauseWhenClientLowPower", label: "Pause on client low power" },
+ { key: "pauseWhenOnBattery", label: "Pause on battery" },
+];
+
+function durationToSeconds(duration: Duration.Duration): number {
+ return Math.round(Duration.toMillis(duration) / 1_000);
+}
+
+function normalizeIntervalSeconds(value: number | null, minimum = 0): number {
+ if (value === null || !Number.isFinite(value)) {
+ return minimum;
+ }
+ return Math.max(minimum, Math.round(value));
+}
+
+function resetBackgroundActivitySettings() {
+ return {
+ backgroundActivity: DEFAULT_UNIFIED_SETTINGS.backgroundActivity,
+ };
+}
+
+function backgroundActivityProfileSettings(profile: BackgroundActivityProfile) {
+ return {
+ backgroundActivity: {
+ schemaVersion: 1 as const,
+ profile,
+ overrides: {},
+ },
+ };
+}
+
+function backgroundActivityOverrideSettings(
+ current: BackgroundActivitySettings,
+ resolved: ReturnType<typeof resolveServerBackgroundActivitySettings>,
+ overrides: BackgroundActivityOverridePatch,
+) {
+ const nextOverrides: BackgroundActivityOverridePatch = {
+ automaticGitFetchInterval: resolved.automaticGitFetchInterval,
+ providerHealthRefreshInterval: resolved.providerHealthRefreshInterval,
+ hostPowerMonitorActiveInterval: resolved.hostPowerMonitorActiveInterval,
+ hostPowerMonitorIdleInterval: resolved.hostPowerMonitorIdleInterval,
+ idleClientTtl: resolved.idleClientTtl,
+ pauseWhenHostLocked: resolved.pauseWhenHostLocked,
+ pauseWhenHostLowPower: resolved.pauseWhenHostLowPower,
+ pauseWhenClientLowPower: resolved.pauseWhenClientLowPower,
+ pauseWhenOnBattery: resolved.pauseWhenOnBattery,
+ ...overrides,
+ };
+ for (const [key, value] of Object.entries(nextOverrides)) {
+ if (value === undefined) {
+ delete nextOverrides[key as keyof typeof nextOverrides];
+ }
+ }
+ return {
+ backgroundActivity: {
+ schemaVersion: 1 as const,
+ profile: "custom" as const,
+ baseProfile: getBackgroundActivityBaseProfile(current),
+ overrides: nextOverrides as BackgroundActivitySettings["overrides"],
+ },
+ };
+}
+
+function PolicyTooltip({ children }: { readonly children: string }) {
+ return (
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <button
+ type="button"
+ className="inline-flex size-5 items-center justify-center rounded-sm text-muted-foreground hover:text-foreground"
+ aria-label="Background policy details"
+ >
+ <InfoIcon className="size-3.5" />
+ </button>
+ }
+ />
+ <TooltipPopup side="top" className="max-w-72">
+ {children}
+ </TooltipPopup>
+ </Tooltip>
+ );
+}
function withoutProviderInstanceKey<V>(
record: Readonly<Record<ProviderInstanceId, V>> | undefined,
@@ -408,6 +564,7 @@ export function useSettingsRestore(onRestored?: () => void) {
settings.textGenerationModelSelection ?? null,
DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection ?? null,
);
+ const isBackgroundActivityDirty = hasChangedBackgroundActivitySettings(settings);
const changedSettingLabels = useMemo(
() => [
@@ -441,10 +598,7 @@ export function useSettingsRestore(onRestored?: () => void) {
DEFAULT_UNIFIED_SETTINGS.enableProviderUpdateChecks
? ["Provider update checks"]
: []),
- ...(Duration.toMillis(settings.automaticGitFetchInterval) !==
- Duration.toMillis(DEFAULT_UNIFIED_SETTINGS.automaticGitFetchInterval)
- ? ["Automatic Git fetch interval"]
- : []),
+ ...(isBackgroundActivityDirty ? ["Background activity"] : []),
...(settings.defaultThreadEnvMode !== DEFAULT_UNIFIED_SETTINGS.defaultThreadEnvMode
? ["New thread mode"]
: []),
@@ -465,6 +619,7 @@ export function useSettingsRestore(onRestored?: () => void) {
],
[
isTextGenerationModelDirty,
+ isBackgroundActivityDirty,
settings.autoOpenPlanSidebar,
settings.confirmThreadArchive,
settings.confirmThreadDelete,
@@ -474,7 +629,6 @@ export function useSettingsRestore(onRestored?: () => void) {
settings.diffIgnoreWhitespace,
settings.environmentIdentificationMode,
settings.glassOpacity,
- settings.automaticGitFetchInterval,
settings.enableAssistantStreaming,
settings.enableProviderUpdateChecks,
settings.sidebarProjectGroupingMode,
@@ -507,7 +661,10 @@ export function useSettingsRestore(onRestored?: () => void) {
autoOpenPlanSidebar: DEFAULT_UNIFIED_SETTINGS.autoOpenPlanSidebar,
enableAssistantStreaming: DEFAULT_UNIFIED_SETTINGS.enableAssistantStreaming,
enableProviderUpdateChecks: DEFAULT_UNIFIED_SETTINGS.enableProviderUpdateChecks,
+ backgroundActivity: DEFAULT_UNIFIED_SETTINGS.backgroundActivity,
+ backgroundActivityProfile: DEFAULT_UNIFIED_SETTINGS.backgroundActivityProfile,
automaticGitFetchInterval: DEFAULT_UNIFIED_SETTINGS.automaticGitFetchInterval,
+ providerHealthRefreshInterval: DEFAULT_UNIFIED_SETTINGS.providerHealthRefreshInterval,
defaultThreadEnvMode: DEFAULT_UNIFIED_SETTINGS.defaultThreadEnvMode,
newWorktreesStartFromOrigin: DEFAULT_UNIFIED_SETTINGS.newWorktreesStartFromOrigin,
addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
@@ -524,6 +681,272 @@ export function useSettingsRestore(onRestored?: () => void) {
};
}
+function BackgroundActivityAdvancedDialog({
+ open,
+ onOpenChange,
+}: {
+ readonly open: boolean;
+ readonly onOpenChange: (open: boolean) => void;
+}) {
+ const settings = usePrimarySettings();
+ const updateSettings = useUpdatePrimarySettings();
+ const resolvedBackgroundActivity = resolveServerBackgroundActivitySettings(settings);
+ const activeProfile = resolvedBackgroundActivity.profile;
+ const automaticGitFetchIntervalSeconds = durationToSeconds(
+ resolvedBackgroundActivity.automaticGitFetchInterval,
+ );
+ const providerHealthRefreshIntervalSeconds = durationToSeconds(
+ resolvedBackgroundActivity.providerHealthRefreshInterval,
+ );
+ const hostPowerMonitorActiveIntervalSeconds = durationToSeconds(
+ resolvedBackgroundActivity.hostPowerMonitorActiveInterval,
+ );
+ const hostPowerMonitorIdleIntervalSeconds = durationToSeconds(
+ resolvedBackgroundActivity.hostPowerMonitorIdleInterval,
+ );
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogPopup className="max-w-xl">
+ <DialogHeader>
+ <DialogTitle>Background Activity</DialogTitle>
+ <DialogDescription>
+ Tune the shared power policy and the background intervals that feed it.
+ </DialogDescription>
+ </DialogHeader>
+ <DialogPanel className="space-y-0 px-6 pb-5">
+ <div className="overflow-hidden rounded-xl border bg-card text-card-foreground">
+ <div className="flex flex-col gap-3 border-b px-4 py-3 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 space-y-1">
+ <div className="text-sm font-medium">Shared policy</div>
+ <p className="text-xs leading-relaxed text-muted-foreground">
+ Controls whether background work may run after a subscribed interval fires.
+ </p>
+ </div>
+ <Select
+ value={activeProfile}
+ onValueChange={(value) => {
+ if (
+ value === "balanced" ||
+ value === "performance" ||
+ value === "battery-saver"
+ ) {
+ updateSettings({
+ backgroundActivity: backgroundActivitySharedPolicySettings(settings, value),
+ });
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Shared background policy">
+ <SelectValue>{BACKGROUND_ACTIVITY_PROFILE_LABELS[activeProfile]}</SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ <SelectItem hideIndicator value="balanced">
+ {BACKGROUND_ACTIVITY_PROFILE_LABELS.balanced}
+ </SelectItem>
+ <SelectItem hideIndicator value="performance">
+ {BACKGROUND_ACTIVITY_PROFILE_LABELS.performance}
+ </SelectItem>
+ <SelectItem hideIndicator value="battery-saver">
+ {BACKGROUND_ACTIVITY_PROFILE_LABELS["battery-saver"]}
+ </SelectItem>
+ </SelectPopup>
+ </Select>
+ </div>
+
+ <div className="flex flex-col gap-3 border-b px-4 py-3 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 space-y-1">
+ <div className="text-sm font-medium">Git fetch interval</div>
+ <p className="text-xs leading-relaxed text-muted-foreground">
+ Refresh remote branch status in the background.
+ </p>
+ </div>
+ <div className="flex shrink-0 items-center gap-2">
+ <NumberField
+ value={automaticGitFetchIntervalSeconds}
+ min={0}
+ step={5}
+ size="sm"
+ className="w-32"
+ onValueChange={(value) =>
+ updateSettings(
+ backgroundActivityOverrideSettings(
+ settings.backgroundActivity,
+ resolvedBackgroundActivity,
+ {
+ automaticGitFetchInterval: Duration.seconds(
+ normalizeIntervalSeconds(value),
+ ),
+ },
+ ),
+ )
+ }
+ >
+ <NumberFieldGroup>
+ <NumberFieldDecrement aria-label="Decrease Git fetch interval" />
+ <NumberFieldInput aria-label="Git fetch interval in seconds" />
+ <NumberFieldIncrement aria-label="Increase Git fetch interval" />
+ </NumberFieldGroup>
+ </NumberField>
+ <span className="text-xs text-muted-foreground">seconds</span>
+ </div>
+ </div>
+
+ <div className="flex flex-col gap-3 px-4 py-3 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 space-y-1">
+ <div className="text-sm font-medium">Provider health interval</div>
+ <p className="text-xs leading-relaxed text-muted-foreground">
+ Refresh provider availability, versions, auth state, and model metadata.
+ </p>
+ </div>
+ <div className="flex shrink-0 items-center gap-2">
+ <NumberField
+ value={providerHealthRefreshIntervalSeconds}
+ min={0}
+ step={PROVIDER_HEALTH_INTERVAL_STEP_SECONDS}
+ size="sm"
+ className="w-32"
+ onValueChange={(value) =>
+ updateSettings(
+ backgroundActivityOverrideSettings(
+ settings.backgroundActivity,
+ resolvedBackgroundActivity,
+ {
+ providerHealthRefreshInterval: Duration.seconds(
+ normalizeIntervalSeconds(value),
+ ),
+ },
+ ),
+ )
+ }
+ >
+ <NumberFieldGroup>
+ <NumberFieldDecrement aria-label="Decrease provider health interval" />
+ <NumberFieldInput aria-label="Provider health interval in seconds" />
+ <NumberFieldIncrement aria-label="Increase provider health interval" />
+ </NumberFieldGroup>
+ </NumberField>
+ <span className="text-xs text-muted-foreground">seconds</span>
+ </div>
+ </div>
+
+ <div className="flex flex-col gap-3 border-t px-4 py-3 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 space-y-1">
+ <div className="text-sm font-medium">Host power monitor</div>
+ <p className="text-xs leading-relaxed text-muted-foreground">
+ Poll host power state while clients are active.
+ </p>
+ </div>
+ <div className="flex shrink-0 items-center gap-2">
+ <NumberField
+ value={hostPowerMonitorActiveIntervalSeconds}
+ min={5}
+ step={5}
+ size="sm"
+ className="w-32"
+ onValueChange={(value) =>
+ updateSettings(
+ backgroundActivityOverrideSettings(
+ settings.backgroundActivity,
+ resolvedBackgroundActivity,
+ {
+ hostPowerMonitorActiveInterval: Duration.seconds(
+ normalizeIntervalSeconds(value, 5),
+ ),
+ },
+ ),
+ )
+ }
+ >
+ <NumberFieldGroup>
+ <NumberFieldDecrement aria-label="Decrease active host power interval" />
+ <NumberFieldInput aria-label="Active host power interval in seconds" />
+ <NumberFieldIncrement aria-label="Increase active host power interval" />
+ </NumberFieldGroup>
+ </NumberField>
+ <span className="text-xs text-muted-foreground">seconds</span>
+ </div>
+ </div>
+
+ <div className="flex flex-col gap-3 border-t px-4 py-3 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 space-y-1">
+ <div className="text-sm font-medium">Idle host monitor</div>
+ <p className="text-xs leading-relaxed text-muted-foreground">
+ Poll host power state when no foreground client is active.
+ </p>
+ </div>
+ <div className="flex shrink-0 items-center gap-2">
+ <NumberField
+ value={hostPowerMonitorIdleIntervalSeconds}
+ min={5}
+ step={30}
+ size="sm"
+ className="w-32"
+ onValueChange={(value) =>
+ updateSettings(
+ backgroundActivityOverrideSettings(
+ settings.backgroundActivity,
+ resolvedBackgroundActivity,
+ {
+ hostPowerMonitorIdleInterval: Duration.seconds(
+ normalizeIntervalSeconds(value, 5),
+ ),
+ },
+ ),
+ )
+ }
+ >
+ <NumberFieldGroup>
+ <NumberFieldDecrement aria-label="Decrease idle host power interval" />
+ <NumberFieldInput aria-label="Idle host power interval in seconds" />
+ <NumberFieldIncrement aria-label="Increase idle host power interval" />
+ </NumberFieldGroup>
+ </NumberField>
+ <span className="text-xs text-muted-foreground">seconds</span>
+ </div>
+ </div>
+
+ <div className="grid gap-0 border-t sm:grid-cols-2">
+ {BACKGROUND_ACTIVITY_BOOLEAN_OVERRIDES.map(({ key, label }) => (
+ <label
+ key={key}
+ className="flex items-center justify-between gap-3 border-b px-4 py-3 last:border-b-0 sm:border-r sm:even:border-r-0"
+ >
+ <span className="text-sm font-medium">{label}</span>
+ <Switch
+ checked={resolvedBackgroundActivity[key]}
+ onCheckedChange={(checked) =>
+ updateSettings(
+ backgroundActivityOverrideSettings(
+ settings.backgroundActivity,
+ resolvedBackgroundActivity,
+ {
+ [key]: Boolean(checked),
+ },
+ ),
+ )
+ }
+ aria-label={label}
+ />
+ </label>
+ ))}
+ </div>
+ </div>
+ </DialogPanel>
+ <DialogFooter>
+ <Button
+ variant="outline"
+ onClick={() => updateSettings(resetBackgroundActivitySettings())}
+ >
+ Reset all
+ </Button>
+ <Button onClick={() => onOpenChange(false)}>Done</Button>
+ </DialogFooter>
+ </DialogPopup>
+ </Dialog>
+ );
+}
+
export function AppearanceSettingsPanel() {
const { theme, setTheme } = useTheme();
const settings = usePrimarySettings();
@@ -693,6 +1116,7 @@ export function AppearanceSettingsPanel() {
export function GeneralSettingsPanel() {
const settings = usePrimarySettings();
const updateSettings = useUpdatePrimarySettings();
+ const [backgroundActivityDialogOpen, setBackgroundActivityDialogOpen] = useState(false);
const lastEnabledProjectGroupingMode = useRef<SidebarProjectGroupingMode>(
readLastEnabledProjectGroupingMode(),
);
@@ -728,6 +1152,19 @@ export function GeneralSettingsPanel() {
settings.textGenerationModelSelection ?? null,
DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection ?? null,
);
+ const resolvedBackgroundActivity = resolveServerBackgroundActivitySettings(settings);
+ const activeBackgroundActivityProfile = resolvedBackgroundActivity.profile;
+ const backgroundActivityProfileOption = resolveBackgroundActivityProfileOption(settings);
+ const backgroundActivityDescription =
+ backgroundActivityProfileOption === "advanced"
+ ? `${ADVANCED_BACKGROUND_ACTIVITY_DESCRIPTION} Current shared policy: ${
+ BACKGROUND_ACTIVITY_PROFILE_LABELS[activeBackgroundActivityProfile]
+ }.`
+ : BACKGROUND_ACTIVITY_PROFILE_DESCRIPTIONS[resolvedBackgroundActivity.profile];
+ const canResetBackgroundActivity = !Equal.equals(
+ settings.backgroundActivity,
+ DEFAULT_UNIFIED_SETTINGS.backgroundActivity,
+ );
return (
<SettingsPageContainer>
@@ -890,6 +1327,88 @@ export function GeneralSettingsPanel() {
}
/>
+ <SettingsRow
+ title={
+ <span className="inline-flex items-center gap-1.5">
+ Background activity
+ <PolicyTooltip>
+ This shared policy gates background work such as Git refreshes and provider health
+ probes after their individual intervals elapse.
+ </PolicyTooltip>
+ </span>
+ }
+ description={backgroundActivityDescription}
+ resetAction={
+ canResetBackgroundActivity ? (
+ <SettingResetButton
+ label="background activity"
+ onClick={() => updateSettings(resetBackgroundActivitySettings())}
+ />
+ ) : null
+ }
+ control={
+ <>
+ <Select
+ value={backgroundActivityProfileOption}
+ onValueChange={(value) => {
+ if (value === "advanced") {
+ setBackgroundActivityDialogOpen(true);
+ return;
+ }
+ if (
+ value === "balanced" ||
+ value === "performance" ||
+ value === "battery-saver"
+ ) {
+ updateSettings(backgroundActivityProfileSettings(value));
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Background activity profile">
+ <SelectValue>
+ {BACKGROUND_ACTIVITY_PROFILE_OPTION_LABELS[backgroundActivityProfileOption]}
+ </SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ <SelectItem hideIndicator value="balanced">
+ {BACKGROUND_ACTIVITY_PROFILE_LABELS.balanced}
+ </SelectItem>
+ <SelectItem hideIndicator value="performance">
+ {BACKGROUND_ACTIVITY_PROFILE_LABELS.performance}
+ </SelectItem>
+ <SelectItem hideIndicator value="battery-saver">
+ {BACKGROUND_ACTIVITY_PROFILE_LABELS["battery-saver"]}
+ </SelectItem>
+ <SelectItem hideIndicator value="advanced">
+ {BACKGROUND_ACTIVITY_PROFILE_OPTION_LABELS.advanced}
+ </SelectItem>
+ </SelectPopup>
+ </Select>
+ {backgroundActivityProfileOption === "advanced" ? (
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <Button
+ size="icon-sm"
+ variant="outline"
+ aria-label="Configure advanced background activity"
+ onClick={() => setBackgroundActivityDialogOpen(true)}
+ >
+ <SettingsIcon className="size-4" />
+ </Button>
+ }
+ />
+ <TooltipPopup side="top">Configure background activity</TooltipPopup>
+ </Tooltip>
+ ) : null}
+ <BackgroundActivityAdvancedDialog
+ open={backgroundActivityDialogOpen}
+ onOpenChange={setBackgroundActivityDialogOpen}
+ />
+ </>
+ }
+ />
+
<SettingsRow
title="Auto-open task panel"
description="Open the right-side plan and task panel automatically when steps appear."
@@ -1207,6 +1726,14 @@ export function ProviderSettingsPanel() {
);
const textGenerationModelSelection = resolveAppModelSelectionState(settings, serverProviders);
const textGenInstanceId = textGenerationModelSelection.instanceId;
+ const resolvedBackgroundActivity = resolveServerBackgroundActivitySettings(settings);
+ const providerHealthPreset = getBackgroundActivityPresetSettings(
+ resolvedBackgroundActivity.profile,
+ ).providerHealthRefreshInterval;
+ const providerHealthRefreshIntervalSeconds = durationToSeconds(
+ resolvedBackgroundActivity.providerHealthRefreshInterval,
+ );
+ const defaultProviderHealthRefreshIntervalSeconds = durationToSeconds(providerHealthPreset);
const lastCheckedAt =
serverProviders.length > 0
? serverProviders.reduce(
@@ -1508,6 +2035,69 @@ export function ProviderSettingsPanel() {
</div>
}
>
+ <SettingsRow
+ title={
+ <span className="inline-flex items-center gap-1.5">
+ Health check interval
+ <PolicyTooltip>
+ This interval is configured here, then the shared Background activity policy decides
+ whether provider probes may run when the timer fires. Custom intervals appear as
+ Advanced in General settings.
+ </PolicyTooltip>
+ </span>
+ }
+ description="Refresh provider availability, versions, auth state, and model metadata in the background. Set this to 0 seconds to rely on manual refreshes."
+ resetAction={
+ providerHealthRefreshIntervalSeconds !== defaultProviderHealthRefreshIntervalSeconds ? (
+ <SettingResetButton
+ label="provider health check interval"
+ onClick={() =>
+ updateSettings(
+ backgroundActivityOverrideSettings(
+ settings.backgroundActivity,
+ resolvedBackgroundActivity,
+ {
+ providerHealthRefreshInterval: undefined,
+ },
+ ),
+ )
+ }
+ />
+ ) : null
+ }
+ control={
+ <div className="flex shrink-0 items-center gap-2">
+ <NumberField
+ value={providerHealthRefreshIntervalSeconds}
+ min={0}
+ step={PROVIDER_HEALTH_INTERVAL_STEP_SECONDS}
+ size="sm"
+ className="w-32"
+ onValueChange={(value) =>
+ updateSettings(
+ backgroundActivityOverrideSettings(
+ settings.backgroundActivity,
+ resolvedBackgroundActivity,
+ {
+ providerHealthRefreshInterval: Duration.seconds(
+ normalizeIntervalSeconds(value),
+ ),
+ },
+ ),
+ )
+ }
+ >
+ <NumberFieldGroup>
+ <NumberFieldDecrement aria-label="Decrease provider health check interval" />
+ <NumberFieldInput aria-label="Provider health check interval in seconds" />
+ <NumberFieldIncrement aria-label="Increase provider health check interval" />
+ </NumberFieldGroup>
+ </NumberField>
+ <span className="text-xs text-muted-foreground">seconds</span>
+ </div>
+ }
+ />
+
{rows.map((row) => {
const driverOption = getDriverOption(row.driver);
const liveProvider = serverProviders.find(
diff --git a/apps/web/src/components/settings/SourceControlSettings.tsx b/apps/web/src/components/settings/SourceControlSettings.tsx
index 764f682fb..cf6da231c 100644
--- a/apps/web/src/components/settings/SourceControlSettings.tsx
+++ b/apps/web/src/components/settings/SourceControlSettings.tsx
@@ -1,8 +1,9 @@
-import { ChevronDownIcon, GitPullRequestIcon, RefreshCwIcon } from "lucide-react";
+import { ChevronDownIcon, GitPullRequestIcon, InfoIcon, RefreshCwIcon } from "lucide-react";
import * as Duration from "effect/Duration";
import * as Option from "effect/Option";
import { useState, type ReactNode } from "react";
import type {
+ BackgroundActivitySettings,
SourceControlProviderKind,
SourceControlDiscoveryResult,
SourceControlProviderAuth,
@@ -10,7 +11,11 @@ import type {
VcsDriverKind,
VcsDiscoveryItem,
} from "@t3tools/contracts";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
+import {
+ getBackgroundActivityBaseProfile,
+ getBackgroundActivityPresetSettings,
+ resolveServerBackgroundActivitySettings,
+} from "@t3tools/shared/backgroundActivitySettings";
import { usePrimarySettings, useUpdatePrimarySettings } from "../../hooks/useSettings";
import { cn } from "../../lib/utils";
@@ -70,6 +75,11 @@ const VCS_ICONS: Partial<Record<VcsDriverKind, Icon>> = {
const SOURCE_CONTROL_SKELETON_ROWS = ["primary", "secondary"] as const;
const GIT_FETCH_INTERVAL_STEP_SECONDS = 5;
+type BackgroundActivityOverridePatch = Partial<{
+ [K in keyof BackgroundActivitySettings["overrides"]]:
+ | BackgroundActivitySettings["overrides"][K]
+ | undefined;
+}>;
function durationToSeconds(duration: Duration.Duration): number {
return Math.round(Duration.toMillis(duration) / 1_000);
@@ -82,6 +92,50 @@ function normalizeFetchIntervalSeconds(value: number | null): number {
return Math.max(0, Math.round(value));
}
+function backgroundActivityOverrideSettings(
+ current: BackgroundActivitySettings,
+ overrides: BackgroundActivityOverridePatch,
+) {
+ const nextOverrides: BackgroundActivityOverridePatch = {
+ ...current.overrides,
+ ...overrides,
+ };
+ for (const [key, value] of Object.entries(nextOverrides)) {
+ if (value === undefined) {
+ delete nextOverrides[key as keyof typeof nextOverrides];
+ }
+ }
+ return {
+ backgroundActivity: {
+ schemaVersion: 1 as const,
+ profile: "custom" as const,
+ baseProfile: getBackgroundActivityBaseProfile(current),
+ overrides: nextOverrides as BackgroundActivitySettings["overrides"],
+ },
+ };
+}
+
+function BackgroundPolicyTooltip({ children }: { readonly children: string }) {
+ return (
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <button
+ type="button"
+ className="inline-flex size-5 items-center justify-center rounded-sm text-muted-foreground hover:text-foreground"
+ aria-label="Background policy details"
+ >
+ <InfoIcon className="size-3.5" />
+ </button>
+ }
+ />
+ <TooltipPopup side="top" className="max-w-72">
+ {children}
+ </TooltipPopup>
+ </Tooltip>
+ );
+}
+
function optionLabel(value: Option.Option<string>): string | null {
return Option.getOrNull(value);
}
@@ -292,13 +346,16 @@ function DiscoveryItemRow({
}
function GitFetchIntervalSettings() {
- const automaticGitFetchInterval = usePrimarySettings(
- (settings) => settings.automaticGitFetchInterval,
- );
+ const settings = usePrimarySettings();
const updateSettings = useUpdatePrimarySettings();
- const automaticGitFetchIntervalSeconds = durationToSeconds(automaticGitFetchInterval);
+ const resolvedBackgroundActivity = resolveServerBackgroundActivitySettings(settings);
+ const automaticGitFetchIntervalSeconds = durationToSeconds(
+ resolvedBackgroundActivity.automaticGitFetchInterval,
+ );
const defaultAutomaticGitFetchIntervalSeconds = durationToSeconds(
- DEFAULT_UNIFIED_SETTINGS.automaticGitFetchInterval,
+ getBackgroundActivityPresetSettings(
+ getBackgroundActivityBaseProfile(settings.backgroundActivity),
+ ).automaticGitFetchInterval,
);
const canResetFetchInterval =
automaticGitFetchIntervalSeconds !== defaultAutomaticGitFetchIntervalSeconds;
@@ -309,6 +366,11 @@ function GitFetchIntervalSettings() {
<div className="min-w-0 space-y-1">
<div className="flex min-w-0 items-center gap-1">
<span className="text-xs font-medium text-foreground">Fetch interval</span>
+ <BackgroundPolicyTooltip>
+ This interval is configured for Git only. The shared Background activity policy still
+ decides whether Git refreshes may run when the timer fires. Custom intervals appear as
+ Advanced in General settings.
+ </BackgroundPolicyTooltip>
<span
className={cn(
"inline-flex size-5 shrink-0 items-center justify-center transition-opacity",
@@ -320,9 +382,11 @@ function GitFetchIntervalSettings() {
<SettingResetButton
label="fetch interval"
onClick={() =>
- updateSettings({
- automaticGitFetchInterval: DEFAULT_UNIFIED_SETTINGS.automaticGitFetchInterval,
- })
+ updateSettings(
+ backgroundActivityOverrideSettings(settings.backgroundActivity, {
+ automaticGitFetchInterval: undefined,
+ }),
+ )
}
/>
) : null}
@@ -341,9 +405,11 @@ function GitFetchIntervalSettings() {
size="sm"
className="w-32"
onValueChange={(value) =>
- updateSettings({
- automaticGitFetchInterval: Duration.seconds(normalizeFetchIntervalSeconds(value)),
- })
+ updateSettings(
+ backgroundActivityOverrideSettings(settings.backgroundActivity, {
+ automaticGitFetchInterval: Duration.seconds(normalizeFetchIntervalSeconds(value)),
+ }),
+ )
}
>
<NumberFieldGroup>
diff --git a/apps/web/src/connection/runtime.ts b/apps/web/src/connection/runtime.ts
index 3d4bf4944..0b5e2c9df 100644
--- a/apps/web/src/connection/runtime.ts
+++ b/apps/web/src/connection/runtime.ts
@@ -5,6 +5,10 @@ import * as Layer from "effect/Layer";
import { Atom } from "effect/unstable/reactivity";
import { runtimeContextLayer } from "../lib/runtime";
+import {
+ backgroundActivityObserverLayer,
+ backgroundActivityReporterLayer,
+} from "../lib/backgroundActivityReporter";
import { connectionPlatformLayer } from "./platform";
const providedConnectionPlatformLayer = connectionPlatformLayer.pipe(
@@ -17,10 +21,22 @@ type ConnectionLayerSource =
| typeof Connection.layer
| typeof snapshotLoaderLayer
| typeof runtimeContextLayer
- | typeof connectionPlatformLayer;
+ | typeof connectionPlatformLayer
+ | typeof backgroundActivityObserverLayer
+ | typeof backgroundActivityReporterLayer;
-const connectionLayer = Layer.merge(Connection.layer, snapshotLoaderLayer).pipe(
- Layer.provideMerge(Layer.mergeAll(runtimeContextLayer, providedConnectionPlatformLayer)),
+const providedClientConnectionLayer = Layer.merge(Connection.layer, snapshotLoaderLayer).pipe(
+ Layer.provideMerge(
+ Layer.mergeAll(
+ runtimeContextLayer,
+ providedConnectionPlatformLayer,
+ backgroundActivityObserverLayer,
+ ),
+ ),
+);
+
+const connectionLayer = backgroundActivityReporterLayer.pipe(
+ Layer.provideMerge(providedClientConnectionLayer),
);
export const connectionAtomRuntime: Atom.AtomRuntime<
diff --git a/apps/web/src/env.ts b/apps/web/src/env.ts
index fb2e493ca..2e08dd336 100644
--- a/apps/web/src/env.ts
+++ b/apps/web/src/env.ts
@@ -1,8 +1,6 @@
/**
* True when running inside the Electron preload bridge, false in a regular browser.
- * The preload script sets window.nativeApi via contextBridge before any web-app
+ * The preload script sets window.desktopBridge via contextBridge before any web-app
* code executes, so this is reliable at module load time.
*/
-export const isElectron =
- typeof window !== "undefined" &&
- (window.desktopBridge !== undefined || window.nativeApi !== undefined);
+export const isElectron = typeof window !== "undefined" && window.desktopBridge !== undefined;
diff --git a/apps/web/src/environments/primary/httpLayer.ts b/apps/web/src/environments/primary/httpLayer.ts
index bedb4954d..306b5de63 100644
--- a/apps/web/src/environments/primary/httpLayer.ts
+++ b/apps/web/src/environments/primary/httpLayer.ts
@@ -10,7 +10,6 @@ function isSameOriginBrowserPrimary(): boolean {
if (
typeof window === "undefined" ||
window.desktopBridge !== undefined ||
- window.nativeApi !== undefined ||
!window.location.origin.startsWith("http")
) {
return false;
diff --git a/apps/web/src/hooks/useSettings.ts b/apps/web/src/hooks/useSettings.ts
index 739f6cfce..e58876b19 100644
--- a/apps/web/src/hooks/useSettings.ts
+++ b/apps/web/src/hooks/useSettings.ts
@@ -302,7 +302,6 @@ function useUpdateSettingsTarget(environmentId: EnvironmentId | null) {
});
}
}
-
if (Object.keys(clientPatch).length > 0) {
persistClientSettings({
...getClientSettingsSnapshot(),
diff --git a/apps/web/src/lib/backgroundActivityReporter.test.ts b/apps/web/src/lib/backgroundActivityReporter.test.ts
new file mode 100644
index 000000000..e32d991f9
--- /dev/null
+++ b/apps/web/src/lib/backgroundActivityReporter.test.ts
@@ -0,0 +1,63 @@
+import { EnvironmentId, WS_METHODS } from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+
+import {
+ observeBackgroundActivitySubscription,
+ retainedBackgroundScopes,
+ wasRecentlyInteracted,
+} from "./backgroundActivityReporter.ts";
+
+describe("wasRecentlyInteracted", () => {
+ it("expires interaction independently of window focus", () => {
+ expect(wasRecentlyInteracted(10_000, 55_000)).toBe(true);
+ expect(wasRecentlyInteracted(10_000, 55_001)).toBe(false);
+ });
+
+ it("rejects future timestamps", () => {
+ expect(wasRecentlyInteracted(10_001, 10_000)).toBe(false);
+ });
+
+ it.effect("retains an observed subscription until its returned finalizer runs", () =>
+ Effect.gen(function* () {
+ const environmentId = EnvironmentId.make("environment-observation-test");
+ const scope = { type: "vcs-status" as const, cwd: "/repo" };
+ const release = yield* observeBackgroundActivitySubscription({
+ environmentId,
+ method: WS_METHODS.subscribeVcsStatus,
+ input: { cwd: scope.cwd },
+ });
+
+ expect(retainedBackgroundScopes(environmentId)).toEqual([scope]);
+
+ yield* release;
+ expect(retainedBackgroundScopes(environmentId)).toEqual([]);
+ }),
+ );
+
+ it.effect("keeps delimiter-containing environment and scope values distinct", () =>
+ Effect.gen(function* () {
+ const firstEnvironmentId = EnvironmentId.make("a");
+ const secondEnvironmentId = EnvironmentId.make("a:vcs-status:b");
+ const releaseFirst = yield* observeBackgroundActivitySubscription({
+ environmentId: firstEnvironmentId,
+ method: WS_METHODS.subscribeVcsStatus,
+ input: { cwd: "b:vcs-status:c" },
+ });
+ const releaseSecond = yield* observeBackgroundActivitySubscription({
+ environmentId: secondEnvironmentId,
+ method: WS_METHODS.subscribeVcsStatus,
+ input: { cwd: "c" },
+ });
+
+ expect(retainedBackgroundScopes(firstEnvironmentId)).toEqual([
+ { type: "vcs-status", cwd: "b:vcs-status:c" },
+ ]);
+ expect(retainedBackgroundScopes(secondEnvironmentId)).toEqual([
+ { type: "vcs-status", cwd: "c" },
+ ]);
+
+ yield* Effect.all([releaseFirst, releaseSecond]);
+ }),
+ );
+});
diff --git a/apps/web/src/lib/backgroundActivityReporter.ts b/apps/web/src/lib/backgroundActivityReporter.ts
new file mode 100644
index 000000000..8af048b47
--- /dev/null
+++ b/apps/web/src/lib/backgroundActivityReporter.ts
@@ -0,0 +1,254 @@
+import { EnvironmentRegistry } from "@t3tools/client-runtime/connection";
+import {
+ EnvironmentRpcSubscriptionObserver,
+ request,
+ type EnvironmentRpcSubscriptionObservation,
+} from "@t3tools/client-runtime/rpc";
+import {
+ type BackgroundScope,
+ type ClientActivityReportInput,
+ type EnvironmentId,
+ WS_METHODS,
+} from "@t3tools/contracts";
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Queue from "effect/Queue";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import * as SubscriptionRef from "effect/SubscriptionRef";
+
+import { randomUUID } from "./utils";
+
+const CLIENT_ID_STORAGE_KEY = "t3.backgroundActivity.clientId";
+const REPORT_INTERVAL_MS = 25_000;
+const LEASE_TTL_MS = 45_000;
+const RECENT_INTERACTION_WINDOW_MS = LEASE_TTL_MS;
+const BASELINE_SCOPES: ReadonlyArray<BackgroundScope> = [{ type: "provider-status" }];
+
+interface RetainedScope {
+ readonly environmentId: EnvironmentId;
+ readonly scope: BackgroundScope;
+ refCount: number;
+}
+
+const retainedScopes = new Map<string, RetainedScope>();
+const retainedScopeListeners = new Set<() => void>();
+
+function notifyRetainedScopesChanged(): void {
+ for (const listener of retainedScopeListeners) {
+ try {
+ listener();
+ } catch {
+ // A failing observer must not corrupt retained-scope lifetime.
+ }
+ }
+}
+
+function stableScopeKey(environmentId: EnvironmentId, scope: BackgroundScope): string {
+ switch (scope.type) {
+ case "server-config":
+ case "diagnostics":
+ return JSON.stringify([environmentId, scope.type]);
+ case "provider-status":
+ return JSON.stringify([environmentId, scope.type, scope.instanceId ?? null]);
+ case "vcs-status":
+ case "git-refs":
+ return JSON.stringify([environmentId, scope.type, scope.cwd]);
+ case "thread":
+ return JSON.stringify([environmentId, scope.type, scope.threadId]);
+ }
+}
+
+function getClientId(): string {
+ try {
+ const existing = window.localStorage.getItem(CLIENT_ID_STORAGE_KEY);
+ if (existing) return existing;
+ const next = randomUUID();
+ window.localStorage.setItem(CLIENT_ID_STORAGE_KEY, next);
+ return next;
+ } catch {
+ return "ephemeral-browser-client";
+ }
+}
+
+function resolveClientKind(): ClientActivityReportInput["clientKind"] {
+ return window.desktopBridge ? "desktop-renderer" : "web";
+}
+
+export function wasRecentlyInteracted(lastInteractionAtMs: number, observedAtMs: number): boolean {
+ return (
+ lastInteractionAtMs <= observedAtMs &&
+ observedAtMs - lastInteractionAtMs <= RECENT_INTERACTION_WINDOW_MS
+ );
+}
+
+function createActivityReport(
+ environmentId: EnvironmentId,
+ lastInteractionAtMs: number,
+ observedAtMs: number,
+): ClientActivityReportInput {
+ const scopes = [...BASELINE_SCOPES];
+ for (const entry of retainedScopes.values()) {
+ if (entry.environmentId === environmentId) {
+ scopes.push(entry.scope);
+ }
+ }
+ return {
+ environmentId,
+ clientId: getClientId(),
+ clientKind: resolveClientKind(),
+ visible: document.visibilityState === "visible",
+ focused: document.hasFocus(),
+ recentlyInteracted: wasRecentlyInteracted(lastInteractionAtMs, observedAtMs),
+ appState: document.visibilityState === "visible" ? "active" : "background",
+ scopes,
+ ttlMs: LEASE_TTL_MS,
+ observedAt: DateTime.makeUnsafe(observedAtMs),
+ };
+}
+
+function scopeForSubscription(
+ observation: EnvironmentRpcSubscriptionObservation,
+): BackgroundScope | null {
+ if (observation.method === WS_METHODS.subscribeResourceTelemetry) {
+ return { type: "diagnostics" };
+ }
+ if (observation.method !== WS_METHODS.subscribeVcsStatus) {
+ return null;
+ }
+ const input = observation.input as { readonly cwd?: unknown };
+ return typeof input.cwd === "string" ? { type: "vcs-status", cwd: input.cwd } : null;
+}
+
+function retainBackgroundScope(environmentId: EnvironmentId, scope: BackgroundScope): () => void {
+ const key = stableScopeKey(environmentId, scope);
+ const existing = retainedScopes.get(key);
+ if (existing) {
+ existing.refCount += 1;
+ } else {
+ retainedScopes.set(key, { environmentId, scope, refCount: 1 });
+ notifyRetainedScopesChanged();
+ }
+
+ return () => {
+ const current = retainedScopes.get(key);
+ if (!current) return;
+ current.refCount -= 1;
+ if (current.refCount <= 0) {
+ retainedScopes.delete(key);
+ notifyRetainedScopesChanged();
+ }
+ };
+}
+
+export function observeBackgroundActivitySubscription(
+ observation: EnvironmentRpcSubscriptionObservation,
+): Effect.Effect<Effect.Effect<void>> {
+ const scope = scopeForSubscription(observation);
+ if (scope === null) {
+ return Effect.succeed(Effect.void);
+ }
+ return Effect.sync(() => {
+ const release = retainBackgroundScope(observation.environmentId as EnvironmentId, scope);
+ return Effect.sync(release);
+ });
+}
+
+export function retainedBackgroundScopes(
+ environmentId: EnvironmentId,
+): ReadonlyArray<BackgroundScope> {
+ return Array.from(retainedScopes.values(), (entry) =>
+ entry.environmentId === environmentId ? entry.scope : null,
+ ).filter((scope): scope is BackgroundScope => scope !== null);
+}
+
+export const backgroundActivityObserverLayer = Layer.succeed(
+ EnvironmentRpcSubscriptionObserver,
+ EnvironmentRpcSubscriptionObserver.of({
+ observe: observeBackgroundActivitySubscription,
+ }),
+);
+
+export const backgroundActivityReporterLayer = Layer.effectDiscard(
+ Effect.gen(function* () {
+ if (typeof window === "undefined" || typeof document === "undefined") {
+ return;
+ }
+
+ const registry = yield* EnvironmentRegistry;
+ const clock = yield* Clock.Clock;
+ const reportRequests = yield* Queue.sliding<void>(1);
+ const requestReport = () => Queue.offerUnsafe(reportRequests, undefined);
+ let lastInteractionAtMs = clock.currentTimeMillisUnsafe();
+ const recordInteraction = () => {
+ const observedAtMs = clock.currentTimeMillisUnsafe();
+ const wasRecent = wasRecentlyInteracted(lastInteractionAtMs, observedAtMs);
+ lastInteractionAtMs = observedAtMs;
+ if (!wasRecent) {
+ requestReport();
+ }
+ };
+ const passiveListenerOptions = { passive: true } as const;
+
+ const report = Effect.gen(function* () {
+ const observedAtMs = yield* Clock.currentTimeMillis;
+ const entries = yield* SubscriptionRef.get(registry.entries);
+ yield* Effect.forEach(
+ entries.keys(),
+ (environmentId) =>
+ registry
+ .run(
+ environmentId,
+ request(
+ WS_METHODS.serverReportClientActivity,
+ createActivityReport(environmentId, lastInteractionAtMs, observedAtMs),
+ ),
+ )
+ .pipe(Effect.ignore),
+ { concurrency: "unbounded", discard: true },
+ );
+ }).pipe(Effect.withSpan("web.backgroundActivity.report"));
+
+ yield* Effect.acquireRelease(
+ Effect.sync(() => {
+ retainedScopeListeners.add(requestReport);
+ document.addEventListener("visibilitychange", requestReport);
+ window.addEventListener("focus", requestReport);
+ window.addEventListener("blur", requestReport);
+ window.addEventListener("online", requestReport);
+ window.addEventListener("pointermove", recordInteraction);
+ window.addEventListener("keydown", recordInteraction);
+ window.addEventListener("wheel", recordInteraction, passiveListenerOptions);
+ window.addEventListener("touchstart", recordInteraction, passiveListenerOptions);
+ }),
+ () =>
+ Effect.sync(() => {
+ retainedScopeListeners.delete(requestReport);
+ document.removeEventListener("visibilitychange", requestReport);
+ window.removeEventListener("focus", requestReport);
+ window.removeEventListener("blur", requestReport);
+ window.removeEventListener("online", requestReport);
+ window.removeEventListener("pointermove", recordInteraction);
+ window.removeEventListener("keydown", recordInteraction);
+ window.removeEventListener("wheel", recordInteraction);
+ window.removeEventListener("touchstart", recordInteraction);
+ }),
+ );
+
+ yield* SubscriptionRef.changes(registry.entries).pipe(
+ Stream.runForEach(() => Effect.sync(requestReport)),
+ Effect.forkScoped,
+ );
+ yield* Stream.fromQueue(reportRequests).pipe(
+ Stream.debounce("250 millis"),
+ Stream.runForEach(() => report),
+ Effect.forkScoped,
+ );
+ yield* Effect.sync(requestReport).pipe(
+ Effect.repeat(Schedule.spaced(`${REPORT_INTERVAL_MS} millis`)),
+ Effect.forkScoped,
+ );
+ }),
+);
diff --git a/apps/web/src/lib/resourceTelemetryState.ts b/apps/web/src/lib/resourceTelemetryState.ts
new file mode 100644
index 000000000..47ca79898
--- /dev/null
+++ b/apps/web/src/lib/resourceTelemetryState.ts
@@ -0,0 +1,51 @@
+import type { ResourceTelemetryHistoryInput, ResourceTelemetrySnapshot } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { useCallback } from "react";
+
+import { usePrimaryEnvironment } from "../state/environments";
+import { useEnvironmentQuery } from "../state/query";
+import { serverEnvironment } from "../state/server";
+import { useAtomCommand } from "../state/use-atom-command";
+
+export interface ResourceTelemetryState {
+ readonly data: ResourceTelemetrySnapshot | null;
+ readonly error: string | null;
+ readonly isPending: boolean;
+ readonly refresh: () => void;
+ readonly retry: () => Promise<ResourceTelemetrySnapshot>;
+}
+
+export function useResourceTelemetry(): ResourceTelemetryState {
+ const primaryEnvironment = usePrimaryEnvironment();
+ const environmentId = primaryEnvironment?.environmentId ?? null;
+ const query = useEnvironmentQuery(
+ environmentId === null
+ ? null
+ : serverEnvironment.resourceTelemetry({ environmentId, input: {} }),
+ );
+ const retryCommand = useAtomCommand(serverEnvironment.retryResourceTelemetry, {
+ reportFailure: false,
+ });
+ const retry = useCallback(async () => {
+ if (environmentId === null) {
+ throw new Error("No environment is selected.");
+ }
+ const result = await retryCommand({ environmentId, input: {} });
+ if (result._tag === "Failure") {
+ throw Cause.squash(result.cause);
+ }
+ return result.value.snapshot;
+ }, [environmentId, retryCommand]);
+
+ return { ...query, retry };
+}
+
+export function useResourceTelemetryHistory(input: ResourceTelemetryHistoryInput) {
+ const primaryEnvironment = usePrimaryEnvironment();
+ const environmentId = primaryEnvironment?.environmentId ?? null;
+ return useEnvironmentQuery(
+ environmentId === null
+ ? null
+ : serverEnvironment.resourceTelemetryHistory({ environmentId, input }),
+ );
+}
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 3379f5ed9..260256c12 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -49,7 +49,6 @@ beforeEach(() => {
});
}
Reflect.deleteProperty(testWindow(), "desktopBridge");
- Reflect.deleteProperty(testWindow(), "nativeApi");
Object.defineProperty(testWindow(), "localStorage", {
configurable: true,
value: createLocalStorageStub(),
@@ -61,16 +60,12 @@ afterEach(() => {
});
describe("LocalApi", () => {
- it("keeps backend operations unavailable in the browser facade", async () => {
+ it("keeps backend operations out of the local host facade", async () => {
const { createLocalApi } = await import("./localApi");
const api = createLocalApi();
- await expect(api.server.getConfig()).rejects.toThrow(
- "Local backend API is unavailable before a backend is paired.",
- );
- await expect(api.shell.openInEditor("/tmp", "cursor")).rejects.toThrow(
- "Local backend API is unavailable before a backend is paired.",
- );
+ expect(api).not.toHaveProperty("server");
+ expect(api.shell).not.toHaveProperty("openInEditor");
});
it("uses the browser context-menu fallback without a desktop bridge", async () => {
@@ -120,12 +115,4 @@ describe("LocalApi", () => {
await api.persistence.setClientSettings(settings);
await expect(api.persistence.getClientSettings()).resolves.toEqual(settings);
});
-
- it("prefers the native LocalApi when one is injected", async () => {
- const nativeApi = { dialogs: {} };
- testWindow().nativeApi = nativeApi as never;
- const { readLocalApi } = await import("./localApi");
-
- expect(readLocalApi()).toBe(nativeApi);
- });
});
diff --git a/apps/web/src/localApi.ts b/apps/web/src/localApi.ts
index 2fbf183f9..b42702c7a 100644
--- a/apps/web/src/localApi.ts
+++ b/apps/web/src/localApi.ts
@@ -6,10 +6,6 @@ import { readBrowserClientSettings, writeBrowserClientSettings } from "./clientP
let cachedApi: LocalApi | undefined;
-function unavailableLocalBackendError(): Error {
- return new Error("Local backend API is unavailable before a backend is paired.");
-}
-
function createBrowserLocalApi(): LocalApi {
return {
dialogs: {
@@ -25,7 +21,6 @@ function createBrowserLocalApi(): LocalApi {
},
},
shell: {
- openInEditor: () => Promise.reject(unavailableLocalBackendError()),
openExternal: async (url) => {
if (window.desktopBridge) {
const opened = await window.desktopBridge.openExternal(url);
@@ -63,20 +58,6 @@ function createBrowserLocalApi(): LocalApi {
writeBrowserClientSettings(settings);
},
},
- server: {
- getConfig: () => Promise.reject(unavailableLocalBackendError()),
- refreshProviders: () => Promise.reject(unavailableLocalBackendError()),
- updateProvider: () => Promise.reject(unavailableLocalBackendError()),
- upsertKeybinding: () => Promise.reject(unavailableLocalBackendError()),
- removeKeybinding: () => Promise.reject(unavailableLocalBackendError()),
- getSettings: () => Promise.reject(unavailableLocalBackendError()),
- updateSettings: () => Promise.reject(unavailableLocalBackendError()),
- discoverSourceControl: () => Promise.reject(unavailableLocalBackendError()),
- getTraceDiagnostics: () => Promise.reject(unavailableLocalBackendError()),
- getProcessDiagnostics: () => Promise.reject(unavailableLocalBackendError()),
- getProcessResourceHistory: () => Promise.reject(unavailableLocalBackendError()),
- signalProcess: () => Promise.reject(unavailableLocalBackendError()),
- },
};
}
@@ -88,12 +69,7 @@ export function readLocalApi(): LocalApi | undefined {
if (typeof window === "undefined") return undefined;
if (cachedApi) return cachedApi;
- if (window.nativeApi) {
- cachedApi = window.nativeApi;
- return cachedApi;
- }
-
- cachedApi = createBrowserLocalApi();
+ cachedApi = createLocalApi();
return cachedApi;
}
diff --git a/apps/web/src/vite-env.d.ts b/apps/web/src/vite-env.d.ts
index ac1da93f5..31260c8ae 100644
--- a/apps/web/src/vite-env.d.ts
+++ b/apps/web/src/vite-env.d.ts
@@ -1,6 +1,6 @@
/// <reference types="vite-plus/client" />
-import type { DesktopBridge, LocalApi } from "@t3tools/contracts";
+import type { DesktopBridge } from "@t3tools/contracts";
interface ImportMetaEnv {
readonly VITE_HTTP_URL: string;
@@ -22,7 +22,6 @@ interface ImportMeta {
declare global {
interface Window {
- nativeApi?: LocalApi;
desktopBridge?: DesktopBridge;
}
}
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 7983bef37..eca184aa0 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -39,6 +39,10 @@ T3 Code runs as a **Node.js WebSocket server** that wraps `codex app-server` (JS
- **Server updates**: A connected environment advertises whether its server can replace itself. When client and server versions differ, the browser selects an automatic, desktop-managed, or manual update path without changing connection ownership. See [Server Update Architecture](./server-updates.md).
+Related design:
+
+- [Resource telemetry architecture](./resource-telemetry.md)
+
## Event Lifecycle
### Startup and client connect
diff --git a/docs/architecture/resource-telemetry.md b/docs/architecture/resource-telemetry.md
new file mode 100644
index 000000000..504aa3f8b
--- /dev/null
+++ b/docs/architecture/resource-telemetry.md
@@ -0,0 +1,391 @@
+# Resource telemetry architecture
+
+Status: implemented
+
+## Purpose
+
+Resource telemetry replaces recurring `ps`, PowerShell, `ioreg`, and `pmset`
+subprocess probes with two persistent, direct data sources:
+
+1. a standalone Rust resource-monitor executable that reads process counters
+ through operating-system APIs via `sysinfo`;
+2. Electron main-process APIs for Electron process metrics and host power state.
+
+The native monitor owns bounded in-memory history. The server only merges and
+summarizes that history when diagnostics requests it. Telemetry history is not
+persisted to disk or continuously copied into Node.
+
+## Why a standalone executable
+
+The monitor is intentionally not a Node native addon.
+
+- No N-API, `ffi-rs`, or dynamic-library ABI is loaded into the server process.
+- A monitor crash cannot corrupt the Node runtime.
+- The server can supervise, restart, version-check, and measure the monitor as a
+ normal child process.
+- The same protocol works for the desktop app and the published CLI.
+- Packaging is a single platform executable instead of an addon toolchain plus
+ Node/Electron ABI matrix.
+
+The cost is one persistent child process and NDJSON serialization. That is a
+better failure boundary than repeatedly spawning shell utilities or loading
+native code into Node.
+
+## Runtime topology
+
+### Desktop
+
+```text
+Electron main
+ ├─ powerMonitor
+ ├─ app.getAppMetrics() while diagnostics is open
+ ├─ inherited fd 4, telemetry NDJSON ─────────────┐
+ └─ inherited fd 5, demand-control NDJSON ◀──────┤
+ ▼
+Node server ── stdin/stdout NDJSON ── Rust resource monitor
+ │
+ ├─ ResourceTelemetry Effect service
+ ├─ background power policy projection
+ └─ WebSocket RPC/subscription ── diagnostics UI
+```
+
+### Web, headless, and remote server
+
+Electron telemetry is unavailable. The native monitor still runs beside the
+server and tracks the server process tree. Power fields degrade to `unknown`
+instead of invoking platform shell commands.
+
+### WSL backend limitation
+
+Windows desktop packages currently ship the Windows resource-monitor executable.
+That executable cannot run inside the Linux WSL backend, so a WSL-only backend
+does not receive `resourceMonitorPath` and reports native process telemetry as
+unavailable. Electron host-power telemetry remains available over the inherited
+desktop pipe. Supporting native WSL process telemetry requires publishing a
+Linux sidecar for each supported architecture in the Windows artifact and
+converting its packaged path into the selected distro; the configuration
+deliberately does not pass the Windows `.exe` into WSL as a false fallback.
+
+## Native monitor
+
+The executable lives in `native/resource-monitor`.
+
+It receives schema-compatible commands on stdin and emits one JSON object per
+line on stdout:
+
+- `configure`
+- `setExternalProcesses`
+- `setSampleInterval`
+- `setStreaming`
+- `sampleNow`
+- `readHistory`
+- `shutdown`
+- `hello`
+- `snapshot`
+- `historyChunk`
+- `error`
+
+The protocol version is defined by
+`RESOURCE_MONITOR_PROTOCOL_VERSION` in
+`packages/contracts/src/resourceTelemetry.ts`.
+
+### Collection
+
+The monitor keeps one `sysinfo::System` instance and refreshes it at the
+power-adaptive interval selected by the server. It collects:
+
+- PID and parent PID;
+- process start time and run time;
+- process name and command line;
+- current and cumulative CPU usage;
+- resident and virtual memory;
+- cumulative process I/O counters.
+
+On Linux, task/thread enumeration is disabled. Command lines are loaded only
+when first needed. This avoids the expensive default behavior of walking every
+`/proc/<pid>/task/<tid>` directory on each refresh.
+
+### Process-tree selection
+
+Each sample scans the accessible process table, builds the PID/PPID graph, and
+retains:
+
+- the server process;
+- every descendant of the server, including provider-spawned grandchildren such
+ as shells, `node`, `tsgo`, language servers, and other tools;
+- Electron processes supplied as explicit external roots;
+- descendants of those Electron roots;
+- the resource monitor itself, because it is a server child.
+
+Process identity is `(pid, startTimeMs)`, not PID alone. Electron and native
+start times are matched with a two-second tolerance because native start times
+can have coarser platform resolution.
+
+The process list is emitted in depth-first tree order so renderer collapse and
+expansion preserves complete subtrees.
+
+### Native history and streaming
+
+Every native sample is appended to a one-hour in-memory ring bounded to 3,600
+snapshots, 20,000 retained process rows, and 64 MiB of retained history bytes.
+History stays in the sidecar until a `readHistory` request and is returned in
+bounded chunks. The first bound reached wins, so high process counts or large
+process names and command lines shorten the effective history window.
+
+Periodic snapshot streaming is disabled by default. The server enables it only
+while at least one diagnostics subscription is retained. `sampleNow` remains
+available for explicit refreshes and identity validation.
+
+The server adjusts native sampling without restarting the sidecar:
+
+- suspended, locked, low-power, or serious/critical thermal state: 15 seconds;
+- battery: 5 seconds;
+- normal AC: 1 second;
+- unknown or stale power: 5 seconds in the background and 1 second while live
+ diagnostics is open.
+
+### Sampling limits
+
+This is counter sampling, not syscall tracing.
+
+- A process that starts and exits entirely between samples may not be observed.
+- Cumulative CPU and I/O counters still provide accurate deltas for processes
+ that survive across samples.
+- Exact file paths, individual write syscalls, ETW events, eBPF events, and
+ Endpoint Security events are outside this implementation.
+
+Those deeper tracing systems can be added later as opt-in diagnostic modes
+without changing the public `ResourceTelemetry` model.
+
+## I/O semantics
+
+The monitor preserves platform semantics instead of presenting all counters as
+equivalent:
+
+- Unix-like platforms report storage I/O counters exposed by `sysinfo`.
+- Windows reports all process I/O bytes, not only disk bytes.
+- Operating-system caches can prevent logical application reads or writes from
+ appearing as physical storage bytes.
+
+The UI therefore labels these values as I/O reads and writes and exposes the
+per-process `ioSemantics` value.
+
+Group totals are observed deltas since telemetry startup. Per-process total
+columns are the operating system's cumulative counters for that process.
+
+## Electron telemetry
+
+Electron main owns `DesktopTelemetryPublisher`.
+
+Power events trigger an immediate snapshot. While diagnostics is closed, the
+server sends the configured active and idle host-power intervals to Electron
+(30 seconds and 2 minutes in the balanced profile). During those heartbeats
+Electron reads:
+
+- `powerMonitor.isOnBatteryPower()`;
+- `powerMonitor.getSystemIdleTime()`;
+- `powerMonitor.getSystemIdleState()`;
+- `powerMonitor.getCurrentThermalState()`.
+
+`app.getAppMetrics()` is only called while diagnostics demand is active. Its
+live cadence is 1 second on AC, 5 seconds on battery, and 15 seconds while
+locked, suspended, or thermally constrained.
+
+It also listens for:
+
+- lock and unlock;
+- suspend and resume;
+- AC and battery transitions;
+- thermal-state changes;
+- CPU speed-limit changes.
+
+Suspension stays latched across event-driven snapshots. An explicit resume
+clears it immediately; a periodic heartbeat also clears a stale latch so a
+missed resume event cannot leave telemetry permanently constrained.
+
+Electron does not expose a cross-platform low-power-mode getter, so that field
+remains `unknown`.
+
+The desktop backend is spawned with:
+
+- fd 3 for the existing bootstrap payload;
+- fd 4 for Electron-to-server telemetry NDJSON;
+- fd 5 for server-to-Electron diagnostics-demand NDJSON.
+
+These are private Electron-main/server pipes. They do not use the renderer
+WebSocket and are recreated for every backend restart.
+
+## Server Effect services
+
+The implementation is under `apps/server/src/resourceTelemetry`.
+
+### `ResourceMonitorBinary`
+
+Resolves an executable from:
+
+1. `T3CODE_RESOURCE_MONITOR_PATH`;
+2. desktop bootstrap configuration;
+3. bundled CLI resources;
+4. local Cargo build outputs.
+
+Unsupported platforms, missing binaries, and non-executable binaries use
+schema-backed tagged errors with descriptive messages.
+
+### `NativeTelemetryClient`
+
+Owns the resource-monitor process and protocol.
+
+- validates the hello/version handshake;
+- sends configuration and external process roots;
+- adapts the native interval from host power state;
+- enables streaming only for scoped live subscribers;
+- reads chunked native history on demand;
+- exposes `sampleNow`;
+- serializes commands;
+- supervises process exit and protocol failure;
+- restarts with bounded exponential backoff;
+- opens a circuit after repeated failures;
+- supports explicit retry;
+- publishes health changes immediately.
+
+Snapshot sequence numbers are scoped to a monitor generation. Server ingestion
+uses the monitor restart count as the generation key, so sequence reset after a
+restart cannot freeze telemetry.
+
+### `DesktopTelemetryReceiver`
+
+Reads fd 4, decodes schema-validated messages, stores the latest Electron
+snapshot, and publishes desktop health. It writes diagnostics demand to fd 5
+and gives the first sample a 90-second startup deadline. Once samples arrive,
+the stale deadline stays beyond the slower configured host-power interval with
+30 seconds of scheduling grace, so intentional 2–10 minute idle polling does
+not oscillate the policy between constrained and unconstrained states. Decode
+errors, protocol mismatch, control-write failure, stream failure, stale input,
+and normal stream closure are represented explicitly.
+
+### `ResourceTelemetry`
+
+Merges native and Electron data and owns public telemetry semantics.
+
+- calculates CPU and I/O rates from cumulative native counters;
+- preserves the last native rates during desktop-only updates;
+- classifies backend, Electron, and monitor processes;
+- computes process depth and child relationships;
+- tracks starts, exits, CPU time, and observed I/O;
+- projects power data;
+- acquires native streaming and Electron process metrics only for scoped live
+ subscribers;
+- queries and replays native history only when requested;
+- validates `(pid, startTimeMs)` before process signaling;
+- updates history health even when no further native sample arrives.
+
+Electron and monitor processes are visible but are not valid targets for the
+existing process-signal RPC.
+
+### History projection
+
+`ResourceTelemetryHistory` is a pure on-demand projection. It replays raw native
+snapshots to derive rates, lifecycle counters, buckets, and process summaries.
+Current Electron process metrics are intentionally excluded from historical
+replay so they cannot overwrite older native CPU or memory samples.
+
+### `ResourceAttribution`
+
+Tracks known logical application I/O separately from OS counters. Current
+integration points record successful writes for:
+
+- provider native and canonical event logs;
+- the local server trace sink.
+
+Entries contain component, operation, logical bytes, count, and elapsed time.
+Future persistence paths should call `ResourceAttribution.record` rather than
+adding diagnostics-specific counters.
+
+## Background policy integration
+
+`HostPowerMonitor` consumes `DesktopTelemetryReceiver` directly; observing host
+power does not retain live resource diagnostics or invoke shell probes.
+
+The monitor updates its latest timestamp on every Electron sample but only
+publishes semantic state changes. Increasing idle seconds alone does not cause a
+background-policy broadcast every second.
+
+## Public API and UI
+
+The WebSocket RPC surface provides:
+
+- current snapshot;
+- bounded history;
+- explicit monitor retry;
+- a live snapshot subscription.
+
+The diagnostics page displays:
+
+- aggregate CPU, memory, I/O, and process counts;
+- backend, Electron, and monitor overhead groups;
+- power and thermal state;
+- collector health and restart information;
+- CPU and I/O history;
+- a collapsible live process tree;
+- safe process signaling for backend descendants;
+- instrumented logical application I/O.
+
+Legacy process diagnostics RPCs are projected from the same service so they no
+longer start recurring process-table commands.
+
+## Packaging
+
+Desktop artifact builds compile the Rust target, stage it as
+`resources/resource-monitor/t3-resource-monitor[.exe]`, and pass its path to the
+backend bootstrap.
+
+CLI release jobs upload each active platform monitor artifact and copy it into:
+
+```text
+apps/server/dist/resource-monitor/<platform>-<arch>/
+```
+
+The published server package already includes `dist`, so those executables ship
+with the CLI. Missing platform artifacts degrade native telemetry to
+`unavailable`; the server continues running.
+
+## Resource and failure behavior
+
+Steady state uses:
+
+- one native process;
+- power-adaptive native counter sampling with no periodic Node snapshot stream;
+- event-driven Electron power updates plus profile-driven heartbeats (30–60
+ seconds while active and 2–10 minutes while idle);
+- no `app.getAppMetrics()` calls while diagnostics is closed;
+- no telemetry database;
+- no recurring shell probes;
+- bounded PubSub queues and native ring history.
+
+The diagnostics page exposes the monitor's own process resource usage and
+collection duration so the observer's cost is measurable.
+
+Failures are isolated:
+
+- native failure does not stop the server;
+- Electron telemetry loss does not stop native telemetry;
+- schema/version errors are visible in health;
+- repeated native failures stop automatic restart churn until explicit retry;
+- server and desktop shutdown close their respective streams and child process
+ scopes.
+
+## Future integration points
+
+High-value follow-up work can use the existing service boundaries:
+
+- opt-in file-path attribution through platform-specific tracing;
+- process lifecycle events to reduce the chance of missing very short-lived
+ children;
+- additional `ResourceAttribution` instrumentation for databases, checkpoints,
+ caches, and file synchronization;
+- exported diagnostic bundles;
+- adaptive sample intervals based on diagnostics visibility and active work.
+
+These additions should preserve the current rules: direct platform APIs,
+schema-validated boundaries, explicit metric semantics, bounded retention, and
+no mandatory telemetry persistence.
diff --git a/native/resource-monitor/Cargo.lock b/native/resource-monitor/Cargo.lock
new file mode 100644
index 000000000..cdc5f9522
--- /dev/null
+++ b/native/resource-monitor/Cargo.lock
@@ -0,0 +1,343 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "bitflags"
+version = "2.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
+
+[[package]]
+name = "dispatch2"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38"
+dependencies = [
+ "bitflags",
+ "objc2",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "memchr"
+version = "2.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+
+[[package]]
+name = "ntapi"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3b335231dfd352ffb0f8017f3b6027a4917f7df785ea2143d8af2adc66980ae"
+dependencies = [
+ "winapi",
+]
+
+[[package]]
+name = "objc2"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a12a8ed07aefc768292f076dc3ac8c48f3781c8f2d5851dd3d98950e8c5a89f"
+dependencies = [
+ "objc2-encode",
+]
+
+[[package]]
+name = "objc2-core-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
+dependencies = [
+ "bitflags",
+ "dispatch2",
+ "objc2",
+]
+
+[[package]]
+name = "objc2-encode"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33"
+
+[[package]]
+name = "objc2-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
+dependencies = [
+ "bitflags",
+ "objc2",
+]
+
+[[package]]
+name = "objc2-io-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33fafba39597d6dc1fb709123dfa8289d39406734be322956a69f0931c73bb15"
+dependencies = [
+ "libc",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-open-directory"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb82bed227edf5201dfedf072bba4015a33d3d4a98519837295a90f0a23f676d"
+dependencies = [
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "sysinfo"
+version = "0.39.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21d0d938c10fcda3e897e28aaddf4ab462375d411f4378cd63b1c945f69aba96"
+dependencies = [
+ "libc",
+ "memchr",
+ "ntapi",
+ "objc2-core-foundation",
+ "objc2-io-kit",
+ "objc2-open-directory",
+ "windows",
+]
+
+[[package]]
+name = "t3-resource-monitor"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "serde_json",
+ "sysinfo",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "windows"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580"
+dependencies = [
+ "windows-collections",
+ "windows-core",
+ "windows-future",
+ "windows-numerics",
+]
+
+[[package]]
+name = "windows-collections"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610"
+dependencies = [
+ "windows-core",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-future"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb"
+dependencies = [
+ "windows-core",
+ "windows-link",
+ "windows-threading",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-numerics"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26"
+dependencies = [
+ "windows-core",
+ "windows-link",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-threading"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
diff --git a/native/resource-monitor/Cargo.toml b/native/resource-monitor/Cargo.toml
new file mode 100644
index 000000000..30cf2ad78
--- /dev/null
+++ b/native/resource-monitor/Cargo.toml
@@ -0,0 +1,17 @@
+[package]
+name = "t3-resource-monitor"
+version = "0.1.0"
+edition = "2024"
+license = "MIT"
+publish = false
+
+[dependencies]
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.150"
+sysinfo = "0.39.3"
+
+[profile.release]
+codegen-units = 1
+lto = "thin"
+panic = "abort"
+strip = true
diff --git a/native/resource-monitor/src/main.rs b/native/resource-monitor/src/main.rs
new file mode 100644
index 000000000..0e5dd6630
--- /dev/null
+++ b/native/resource-monitor/src/main.rs
@@ -0,0 +1,1160 @@
+use serde::{Deserialize, Serialize};
+use std::collections::{HashMap, HashSet, VecDeque};
+use std::io::{self, BufRead, BufWriter, Write};
+use std::sync::mpsc::{self, Receiver, RecvTimeoutError};
+use std::thread;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use sysinfo::{
+ MINIMUM_CPU_UPDATE_INTERVAL, Pid, ProcessRefreshKind, ProcessesToUpdate, System, UpdateKind,
+};
+
+const PROTOCOL_VERSION: u32 = 2;
+const MIN_SAMPLE_INTERVAL_MS: u64 = 250;
+const MAX_SAMPLE_INTERVAL_MS: u64 = 60_000;
+const PROCESS_START_TIME_PRECISION_MS: u64 = 1_000;
+const HISTORY_RETENTION_MS: u64 = 60 * 60_000;
+const MAX_HISTORY_SNAPSHOTS: usize = 3_600;
+const INPUT_QUEUE_CAPACITY: usize = 64;
+const MAX_HISTORY_RETAINED_ENTRIES: usize = 20_000;
+const MAX_HISTORY_RETAINED_BYTES: usize = 64 * 1024 * 1024;
+const MAX_PROCESS_NAME_BYTES: usize = 1_024;
+const MAX_PROCESS_COMMAND_BYTES: usize = 16 * 1_024;
+const MAX_PROCESS_STATUS_BYTES: usize = 256;
+const HISTORY_CHUNK_SNAPSHOTS: usize = 32;
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ExternalProcess {
+ pid: u32,
+ #[serde(default)]
+ start_time_ms: Option<u64>,
+}
+
+impl ExternalProcess {
+ fn estimated_history_bytes(&self) -> usize {
+ std::mem::size_of::<Self>()
+ }
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(
+ tag = "type",
+ rename_all = "camelCase",
+ rename_all_fields = "camelCase"
+)]
+enum Command {
+ Configure {
+ version: u32,
+ root_pid: u32,
+ sample_interval_ms: u64,
+ #[serde(default)]
+ external_processes: Vec<ExternalProcess>,
+ },
+ SetExternalProcesses {
+ version: u32,
+ processes: Vec<ExternalProcess>,
+ },
+ SetSampleInterval {
+ version: u32,
+ sample_interval_ms: u64,
+ },
+ SetStreaming {
+ version: u32,
+ enabled: bool,
+ },
+ SampleNow {
+ version: u32,
+ request_id: String,
+ },
+ ReadHistory {
+ version: u32,
+ request_id: String,
+ window_ms: u64,
+ },
+ Shutdown {
+ version: u32,
+ },
+}
+
+impl Command {
+ fn version(&self) -> u32 {
+ match self {
+ Self::Configure { version, .. }
+ | Self::SetExternalProcesses { version, .. }
+ | Self::SetSampleInterval { version, .. }
+ | Self::SetStreaming { version, .. }
+ | Self::SampleNow { version, .. }
+ | Self::ReadHistory { version, .. }
+ | Self::Shutdown { version } => *version,
+ }
+ }
+}
+
+enum Input {
+ Command(Command),
+ Invalid(String),
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct Capabilities {
+ cumulative_cpu_time: bool,
+ current_cpu_percent: bool,
+ resident_memory: bool,
+ virtual_memory: bool,
+ io_bytes: bool,
+ process_start_time: bool,
+ process_tree: bool,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct HelloEvent {
+ version: u32,
+ #[serde(rename = "type")]
+ event_type: &'static str,
+ sidecar_version: &'static str,
+ sidecar_pid: u32,
+ platform: &'static str,
+ arch: &'static str,
+ capabilities: Capabilities,
+}
+
+#[derive(Debug, Clone, Copy, Serialize)]
+#[serde(rename_all = "kebab-case")]
+enum IoSemantics {
+ Storage,
+ AllIo,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ProcessSample {
+ pid: u32,
+ ppid: u32,
+ start_time_ms: u64,
+ run_time_ms: u64,
+ name: String,
+ command: String,
+ status: String,
+ cpu_percent: f32,
+ cpu_time_ms: u64,
+ resident_bytes: u64,
+ virtual_bytes: u64,
+ io_read_bytes: u64,
+ io_write_bytes: u64,
+ io_semantics: IoSemantics,
+}
+
+impl ProcessSample {
+ fn estimated_history_bytes(&self) -> usize {
+ std::mem::size_of::<Self>()
+ .saturating_add(self.name.len())
+ .saturating_add(self.command.len())
+ .saturating_add(self.status.len())
+ }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct SnapshotEvent {
+ version: u32,
+ #[serde(rename = "type")]
+ event_type: &'static str,
+ sequence: u64,
+ sampled_at_unix_ms: u64,
+ collection_duration_micros: u64,
+ scanned_process_count: usize,
+ retained_process_count: usize,
+ inaccessible_process_count: usize,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ request_id: Option<String>,
+ external_processes: Vec<ExternalProcess>,
+ processes: Vec<ProcessSample>,
+}
+
+impl SnapshotEvent {
+ fn retained_entry_count(&self) -> usize {
+ self.processes
+ .len()
+ .saturating_add(self.external_processes.len())
+ }
+
+ fn estimated_history_bytes(&self) -> usize {
+ std::mem::size_of::<Self>()
+ .saturating_add(
+ self.processes
+ .iter()
+ .map(ProcessSample::estimated_history_bytes)
+ .sum::<usize>(),
+ )
+ .saturating_add(
+ self.external_processes
+ .iter()
+ .map(ExternalProcess::estimated_history_bytes)
+ .sum::<usize>(),
+ )
+ }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct HistoryChunkEvent<'a> {
+ version: u32,
+ #[serde(rename = "type")]
+ event_type: &'static str,
+ request_id: &'a str,
+ done: bool,
+ snapshots: &'a [SnapshotEvent],
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ErrorEvent {
+ version: u32,
+ #[serde(rename = "type")]
+ event_type: &'static str,
+ code: &'static str,
+ message: String,
+ recoverable: bool,
+}
+
+#[derive(Debug, Clone)]
+struct CollectorConfig {
+ root_pid: u32,
+ sample_interval: Option<Duration>,
+ external_processes: HashMap<u32, Option<u64>>,
+}
+
+#[derive(Default)]
+struct HistoryRecorder {
+ snapshots: VecDeque<SnapshotEvent>,
+ retained_entry_count: usize,
+ retained_bytes: usize,
+}
+
+impl HistoryRecorder {
+ fn record(&mut self, snapshot: &SnapshotEvent) {
+ self.record_with_limits(
+ snapshot,
+ MAX_HISTORY_SNAPSHOTS,
+ MAX_HISTORY_RETAINED_ENTRIES,
+ MAX_HISTORY_RETAINED_BYTES,
+ );
+ }
+
+ fn record_with_limits(
+ &mut self,
+ snapshot: &SnapshotEvent,
+ max_snapshots: usize,
+ max_retained_entries: usize,
+ max_retained_bytes: usize,
+ ) {
+ let mut retained = snapshot.clone();
+ retained.request_id = None;
+ self.retained_entry_count = self
+ .retained_entry_count
+ .saturating_add(retained.retained_entry_count());
+ self.retained_bytes = self
+ .retained_bytes
+ .saturating_add(retained.estimated_history_bytes());
+ self.snapshots.push_back(retained);
+ self.trim_to_limits(
+ snapshot.sampled_at_unix_ms,
+ max_snapshots,
+ max_retained_entries,
+ max_retained_bytes,
+ );
+ }
+
+ fn trim_to_limits(
+ &mut self,
+ now_ms: u64,
+ max_snapshots: usize,
+ max_retained_entries: usize,
+ max_retained_bytes: usize,
+ ) {
+ let mut future_entry_count = 0usize;
+ let mut future_bytes = 0usize;
+ self.snapshots.retain(|snapshot| {
+ let keep = snapshot.sampled_at_unix_ms <= now_ms;
+ if !keep {
+ future_entry_count =
+ future_entry_count.saturating_add(snapshot.retained_entry_count());
+ future_bytes = future_bytes.saturating_add(snapshot.estimated_history_bytes());
+ }
+ keep
+ });
+ self.retained_entry_count = self.retained_entry_count.saturating_sub(future_entry_count);
+ self.retained_bytes = self.retained_bytes.saturating_sub(future_bytes);
+
+ while self.snapshots.front().is_some_and(|snapshot| {
+ snapshot.sampled_at_unix_ms < now_ms.saturating_sub(HISTORY_RETENTION_MS)
+ || self.snapshots.len() > max_snapshots
+ || self.retained_entry_count > max_retained_entries
+ || self.retained_bytes > max_retained_bytes
+ }) {
+ if let Some(removed) = self.snapshots.pop_front() {
+ self.retained_entry_count = self
+ .retained_entry_count
+ .saturating_sub(removed.retained_entry_count());
+ self.retained_bytes = self
+ .retained_bytes
+ .saturating_sub(removed.estimated_history_bytes());
+ }
+ }
+ }
+
+ fn read(&self, window_ms: u64, now_ms: u64) -> Vec<SnapshotEvent> {
+ let started_at_ms = now_ms.saturating_sub(window_ms.min(HISTORY_RETENTION_MS));
+ self.snapshots
+ .iter()
+ .filter(|snapshot| {
+ snapshot.sampled_at_unix_ms >= started_at_ms
+ && snapshot.sampled_at_unix_ms <= now_ms
+ })
+ .cloned()
+ .collect()
+ }
+}
+
+struct Collector {
+ system: System,
+ sequence: u64,
+ cpu_baseline_refreshed_at: Option<Instant>,
+}
+
+impl Collector {
+ fn new() -> Self {
+ Self {
+ system: System::new(),
+ sequence: 0,
+ cpu_baseline_refreshed_at: None,
+ }
+ }
+
+ fn prime_cpu_usage(&mut self) {
+ self.system.refresh_processes_specifics(
+ ProcessesToUpdate::All,
+ true,
+ process_refresh_kind(),
+ );
+ self.cpu_baseline_refreshed_at = Some(Instant::now());
+ }
+
+ fn sample(&mut self, config: &CollectorConfig, request_id: Option<String>) -> SnapshotEvent {
+ if let Some(delay) =
+ remaining_cpu_measurement_delay(self.cpu_baseline_refreshed_at.take(), Instant::now())
+ {
+ thread::sleep(delay);
+ }
+ let collection_started = Instant::now();
+ self.system.refresh_processes_specifics(
+ ProcessesToUpdate::All,
+ true,
+ process_refresh_kind(),
+ );
+ self.cpu_baseline_refreshed_at = Some(Instant::now());
+
+ let rows = self
+ .system
+ .processes()
+ .iter()
+ .map(|(pid, process)| {
+ let pid = pid.as_u32();
+ let ppid = process.parent().map(Pid::as_u32).unwrap_or(0);
+ (pid, ppid, process.start_time().saturating_mul(1_000))
+ })
+ .collect::<Vec<_>>();
+ let external_processes = config
+ .external_processes
+ .iter()
+ .filter_map(|(pid, expected_start_time_ms)| {
+ let (_, _, actual_start_time_ms) = rows
+ .iter()
+ .find(|(candidate_pid, _, _)| candidate_pid == pid)?;
+ matches_external_identity(*actual_start_time_ms, *expected_start_time_ms).then_some(
+ ExternalProcess {
+ pid: *pid,
+ start_time_ms: Some(*actual_start_time_ms),
+ },
+ )
+ })
+ .collect::<Vec<_>>();
+ let mut roots = external_processes
+ .iter()
+ .map(|process| process.pid)
+ .collect::<HashSet<_>>();
+ roots.insert(config.root_pid);
+ let tracked = select_tracked_pids(&rows, &roots);
+ let tracked_process_count = tracked.len();
+ let mut processes = tracked
+ .into_iter()
+ .filter_map(|pid| {
+ let process = self.system.process(Pid::from_u32(pid))?;
+ let disk_usage = process.disk_usage();
+ let command = if process.cmd().is_empty() {
+ process.name().to_string_lossy().into_owned()
+ } else {
+ process
+ .cmd()
+ .iter()
+ .map(|part| part.to_string_lossy())
+ .collect::<Vec<_>>()
+ .join(" ")
+ };
+
+ Some(ProcessSample {
+ pid,
+ ppid: process.parent().map(Pid::as_u32).unwrap_or(0),
+ start_time_ms: process.start_time().saturating_mul(1_000),
+ run_time_ms: process.run_time().saturating_mul(1_000),
+ name: truncate_utf8(
+ process.name().to_string_lossy().into_owned(),
+ MAX_PROCESS_NAME_BYTES,
+ ),
+ command: truncate_utf8(command, MAX_PROCESS_COMMAND_BYTES),
+ status: truncate_utf8(
+ format!("{:?}", process.status()),
+ MAX_PROCESS_STATUS_BYTES,
+ ),
+ cpu_percent: process.cpu_usage(),
+ cpu_time_ms: process.accumulated_cpu_time(),
+ resident_bytes: process.memory(),
+ virtual_bytes: process.virtual_memory(),
+ io_read_bytes: disk_usage.total_read_bytes,
+ io_write_bytes: disk_usage.total_written_bytes,
+ io_semantics: io_semantics(),
+ })
+ })
+ .collect::<Vec<_>>();
+ processes.sort_by_key(|process| process.pid);
+ self.sequence = self.sequence.saturating_add(1);
+
+ SnapshotEvent {
+ version: PROTOCOL_VERSION,
+ event_type: "snapshot",
+ sequence: self.sequence,
+ sampled_at_unix_ms: unix_time_ms(),
+ collection_duration_micros: collection_started.elapsed().as_micros() as u64,
+ scanned_process_count: self.system.processes().len(),
+ retained_process_count: processes.len(),
+ inaccessible_process_count: inaccessible_process_count(
+ tracked_process_count,
+ processes.len(),
+ ),
+ request_id,
+ external_processes,
+ processes,
+ }
+ }
+}
+
+fn process_refresh_kind() -> ProcessRefreshKind {
+ ProcessRefreshKind::nothing()
+ .with_memory()
+ .with_cpu()
+ .with_disk_usage()
+ .with_cmd(UpdateKind::Always)
+ .without_tasks()
+}
+
+fn inaccessible_process_count(selected: usize, materialized: usize) -> usize {
+ selected.saturating_sub(materialized)
+}
+
+fn remaining_cpu_measurement_delay(
+ baseline_refreshed_at: Option<Instant>,
+ now: Instant,
+) -> Option<Duration> {
+ baseline_refreshed_at
+ .and_then(|baseline| MINIMUM_CPU_UPDATE_INTERVAL.checked_sub(now.duration_since(baseline)))
+ .filter(|delay| !delay.is_zero())
+}
+
+fn matches_external_identity(
+ actual_start_time_ms: u64,
+ expected_start_time_ms: Option<u64>,
+) -> bool {
+ // sysinfo reports process starts at whole-second precision. Normalize the
+ // higher-resolution Electron timestamp to that same bucket instead of
+ // accepting adjacent seconds, which could attach a quickly reused PID.
+ expected_start_time_ms.is_none_or(|expected| {
+ actual_start_time_ms == expected - (expected % PROCESS_START_TIME_PRECISION_MS)
+ })
+}
+
+fn select_tracked_pids(rows: &[(u32, u32, u64)], roots: &HashSet<u32>) -> HashSet<u32> {
+ let mut children_by_parent = HashMap::<u32, Vec<(u32, u64)>>::new();
+ let mut start_time_by_pid = HashMap::<u32, u64>::new();
+ for (pid, ppid, start_time_ms) in rows {
+ children_by_parent
+ .entry(*ppid)
+ .or_default()
+ .push((*pid, *start_time_ms));
+ start_time_by_pid.insert(*pid, *start_time_ms);
+ }
+
+ let mut tracked = HashSet::new();
+ let mut visited_identities = HashSet::new();
+ let mut queue = roots
+ .iter()
+ .filter_map(|pid| {
+ start_time_by_pid
+ .get(pid)
+ .map(|start_time_ms| (*pid, *start_time_ms))
+ })
+ .collect::<VecDeque<_>>();
+
+ while let Some((pid, start_time_ms)) = queue.pop_front() {
+ if !visited_identities.insert((pid, start_time_ms)) {
+ continue;
+ }
+ tracked.insert(pid);
+ if let Some(children) = children_by_parent.get(&pid) {
+ queue.extend(
+ children
+ .iter()
+ .copied()
+ .filter(|(_, child_start_time_ms)| *child_start_time_ms >= start_time_ms),
+ );
+ }
+ }
+
+ tracked
+}
+
+fn truncate_utf8(mut value: String, max_bytes: usize) -> String {
+ if value.len() <= max_bytes {
+ return value;
+ }
+ let mut boundary = max_bytes;
+ while !value.is_char_boundary(boundary) {
+ boundary = boundary.saturating_sub(1);
+ }
+ value.truncate(boundary);
+ value
+}
+
+fn io_semantics() -> IoSemantics {
+ if cfg!(target_os = "windows") {
+ IoSemantics::AllIo
+ } else {
+ IoSemantics::Storage
+ }
+}
+
+fn unix_time_ms() -> u64 {
+ SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .unwrap_or_default()
+ .as_millis() as u64
+}
+
+fn clamp_sample_interval(sample_interval_ms: u64) -> Option<Duration> {
+ (sample_interval_ms > 0).then(|| {
+ Duration::from_millis(
+ sample_interval_ms.clamp(MIN_SAMPLE_INTERVAL_MS, MAX_SAMPLE_INTERVAL_MS),
+ )
+ })
+}
+
+fn spawn_input_reader() -> Receiver<Input> {
+ let (sender, receiver) = mpsc::sync_channel(INPUT_QUEUE_CAPACITY);
+ thread::spawn(move || {
+ let stdin = io::stdin();
+ for line in stdin.lock().lines() {
+ let line = match line {
+ Ok(line) => line,
+ Err(error) => {
+ let _ = sender.send(Input::Invalid(format!(
+ "failed reading command stream: {error}"
+ )));
+ return;
+ }
+ };
+ if line.trim().is_empty() {
+ continue;
+ }
+ match serde_json::from_str::<Command>(&line) {
+ Ok(command) => {
+ if sender.send(Input::Command(command)).is_err() {
+ return;
+ }
+ }
+ Err(error) => {
+ if sender
+ .send(Input::Invalid(format!("invalid command: {error}")))
+ .is_err()
+ {
+ return;
+ }
+ }
+ }
+ }
+ });
+ receiver
+}
+
+fn sample_now_deadline(
+ current: Option<Instant>,
+ interval: Option<Duration>,
+ now: Instant,
+) -> Option<Instant> {
+ current.or_else(|| interval.map(|duration| now + duration))
+}
+
+fn write_event<T: Serialize>(writer: &mut impl Write, event: &T) -> io::Result<()> {
+ serde_json::to_writer(&mut *writer, event)?;
+ writer.write_all(b"\n")?;
+ writer.flush()
+}
+
+fn write_error(
+ writer: &mut impl Write,
+ code: &'static str,
+ message: impl Into<String>,
+ recoverable: bool,
+) -> io::Result<()> {
+ write_event(
+ writer,
+ &ErrorEvent {
+ version: PROTOCOL_VERSION,
+ event_type: "error",
+ code,
+ message: message.into(),
+ recoverable,
+ },
+ )
+}
+
+fn write_history(
+ writer: &mut impl Write,
+ request_id: &str,
+ snapshots: &[SnapshotEvent],
+) -> io::Result<()> {
+ if snapshots.is_empty() {
+ return write_event(
+ writer,
+ &HistoryChunkEvent {
+ version: PROTOCOL_VERSION,
+ event_type: "historyChunk",
+ request_id,
+ done: true,
+ snapshots,
+ },
+ );
+ }
+
+ let chunk_count = snapshots.len().div_ceil(HISTORY_CHUNK_SNAPSHOTS);
+ for (index, chunk) in snapshots.chunks(HISTORY_CHUNK_SNAPSHOTS).enumerate() {
+ write_event(
+ writer,
+ &HistoryChunkEvent {
+ version: PROTOCOL_VERSION,
+ event_type: "historyChunk",
+ request_id,
+ done: index + 1 == chunk_count,
+ snapshots: chunk,
+ },
+ )?;
+ }
+ Ok(())
+}
+
+fn main() -> io::Result<()> {
+ let mut writer = BufWriter::new(io::stdout().lock());
+ write_event(
+ &mut writer,
+ &HelloEvent {
+ version: PROTOCOL_VERSION,
+ event_type: "hello",
+ sidecar_version: env!("CARGO_PKG_VERSION"),
+ sidecar_pid: std::process::id(),
+ platform: std::env::consts::OS,
+ arch: std::env::consts::ARCH,
+ capabilities: Capabilities {
+ cumulative_cpu_time: true,
+ current_cpu_percent: true,
+ resident_memory: true,
+ virtual_memory: true,
+ io_bytes: true,
+ process_start_time: true,
+ process_tree: true,
+ },
+ },
+ )?;
+
+ let receiver = spawn_input_reader();
+ let mut collector = Collector::new();
+ let mut history = HistoryRecorder::default();
+ let mut config: Option<CollectorConfig> = None;
+ let mut next_sample_at: Option<Instant> = None;
+ let mut streaming_enabled = false;
+
+ loop {
+ if next_sample_at.is_some_and(|deadline| deadline <= Instant::now()) {
+ if let Some(current) = config.as_ref() {
+ if let Some(interval) = current.sample_interval {
+ let event = collector.sample(current, None);
+ history.record(&event);
+ if streaming_enabled {
+ write_event(&mut writer, &event)?;
+ }
+ next_sample_at = Some(Instant::now() + interval);
+ } else {
+ next_sample_at = None;
+ }
+ } else {
+ next_sample_at = None;
+ }
+ continue;
+ }
+
+ let timeout = next_sample_at
+ .map(|deadline| deadline.saturating_duration_since(Instant::now()))
+ .unwrap_or(Duration::from_secs(60));
+
+ match receiver.recv_timeout(timeout) {
+ Ok(Input::Invalid(message)) => {
+ write_error(&mut writer, "invalid-command", message, true)?;
+ }
+ Ok(Input::Command(command)) => {
+ if command.version() != PROTOCOL_VERSION {
+ write_error(
+ &mut writer,
+ "protocol-mismatch",
+ format!(
+ "unsupported protocol version {}; expected {PROTOCOL_VERSION}",
+ command.version()
+ ),
+ false,
+ )?;
+ continue;
+ }
+
+ match command {
+ Command::Configure {
+ root_pid,
+ sample_interval_ms,
+ external_processes,
+ ..
+ } => {
+ let sample_interval = clamp_sample_interval(sample_interval_ms);
+ config = Some(CollectorConfig {
+ root_pid,
+ sample_interval,
+ external_processes: external_processes
+ .into_iter()
+ .map(|process| (process.pid, process.start_time_ms))
+ .collect(),
+ });
+ collector.prime_cpu_usage();
+ next_sample_at = sample_interval.map(|_| Instant::now());
+ }
+ Command::SetExternalProcesses { processes, .. } => {
+ if let Some(current) = config.as_mut() {
+ current.external_processes = processes
+ .into_iter()
+ .map(|process| (process.pid, process.start_time_ms))
+ .collect();
+ } else {
+ write_error(
+ &mut writer,
+ "not-configured",
+ "configure must be sent before external processes",
+ true,
+ )?;
+ }
+ }
+ Command::SetSampleInterval {
+ sample_interval_ms, ..
+ } => {
+ if let Some(current) = config.as_mut() {
+ current.sample_interval = clamp_sample_interval(sample_interval_ms);
+ next_sample_at = current
+ .sample_interval
+ .map(|interval| Instant::now() + interval);
+ } else {
+ write_error(
+ &mut writer,
+ "not-configured",
+ "configure must be sent before changing the sample interval",
+ true,
+ )?;
+ }
+ }
+ Command::SetStreaming { enabled, .. } => {
+ streaming_enabled = enabled;
+ }
+ Command::SampleNow { request_id, .. } => {
+ if let Some(current) = config.as_ref() {
+ let event = collector.sample(current, Some(request_id));
+ history.record(&event);
+ write_event(&mut writer, &event)?;
+ next_sample_at = sample_now_deadline(
+ next_sample_at,
+ current.sample_interval,
+ Instant::now(),
+ );
+ } else {
+ write_error(
+ &mut writer,
+ "not-configured",
+ "configure must be sent before sampling",
+ true,
+ )?;
+ }
+ }
+ Command::ReadHistory {
+ request_id,
+ window_ms,
+ ..
+ } => {
+ if config.is_some() {
+ let snapshots = history.read(window_ms, unix_time_ms());
+ write_history(&mut writer, &request_id, &snapshots)?;
+ } else {
+ write_error(
+ &mut writer,
+ "not-configured",
+ "configure must be sent before reading history",
+ true,
+ )?;
+ }
+ }
+ Command::Shutdown { .. } => return Ok(()),
+ }
+ }
+ Err(RecvTimeoutError::Timeout) => {}
+ Err(RecvTimeoutError::Disconnected) => return Ok(()),
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn selects_roots_and_all_descendants() {
+ let rows = vec![
+ (10, 1, 1_000),
+ (11, 10, 1_100),
+ (12, 11, 1_200),
+ (20, 1, 2_000),
+ (21, 20, 2_100),
+ (30, 99, 3_000),
+ ];
+ let tracked = select_tracked_pids(&rows, &HashSet::from([10, 20]));
+
+ assert_eq!(tracked, HashSet::from([10, 11, 12, 20, 21]));
+ }
+
+ #[test]
+ fn rejects_descendants_older_than_a_reused_parent_pid() {
+ let rows = vec![
+ (20, 1, 5_000),
+ (21, 20, 4_000),
+ (22, 20, 5_100),
+ (23, 21, 5_200),
+ ];
+ let tracked = select_tracked_pids(&rows, &HashSet::from([20]));
+
+ assert_eq!(tracked, HashSet::from([20, 22]));
+ }
+
+ #[test]
+ fn ignores_missing_roots() {
+ let rows = vec![(10, 1, 1_000), (11, 10, 1_100)];
+ let tracked = select_tracked_pids(&rows, &HashSet::from([99]));
+
+ assert!(tracked.is_empty());
+ }
+
+ #[test]
+ fn validates_external_process_start_identity() {
+ assert!(matches_external_identity(10_000, None));
+ assert!(matches_external_identity(10_000, Some(10_999)));
+ assert!(!matches_external_identity(10_000, Some(11_000)));
+ assert!(!matches_external_identity(10_000, Some(9_999)));
+ }
+
+ #[test]
+ fn decodes_protocol_commands() {
+ let configure = serde_json::from_str::<Command>(
+ r#"{"version":2,"type":"configure","rootPid":42,"sampleIntervalMs":1000,"externalProcesses":[{"pid":7}]}"#,
+ )
+ .expect("configure command");
+
+ match configure {
+ Command::Configure {
+ root_pid,
+ sample_interval_ms,
+ external_processes,
+ ..
+ } => {
+ assert_eq!(root_pid, 42);
+ assert_eq!(sample_interval_ms, 1_000);
+ assert_eq!(external_processes[0].pid, 7);
+ assert_eq!(external_processes[0].start_time_ms, None);
+ }
+ _ => panic!("unexpected command"),
+ }
+
+ let read_history = serde_json::from_str::<Command>(
+ r#"{"version":2,"type":"readHistory","requestId":"history-1","windowMs":60000}"#,
+ )
+ .expect("read history command");
+ assert!(matches!(
+ read_history,
+ Command::ReadHistory {
+ request_id,
+ window_ms: 60_000,
+ ..
+ } if request_id == "history-1"
+ ));
+ }
+
+ #[test]
+ fn clamps_sample_interval() {
+ assert_eq!(clamp_sample_interval(0), None);
+ assert_eq!(clamp_sample_interval(1), Some(Duration::from_millis(250)));
+ assert_eq!(
+ clamp_sample_interval(100_000),
+ Some(Duration::from_millis(60_000))
+ );
+ }
+
+ #[test]
+ fn counts_selected_processes_that_could_not_be_materialized() {
+ assert_eq!(inaccessible_process_count(5, 3), 2);
+ assert_eq!(inaccessible_process_count(3, 5), 0);
+ }
+
+ #[test]
+ fn waits_for_a_cpu_measurement_window_after_priming() {
+ let baseline = Instant::now();
+
+ assert_eq!(
+ remaining_cpu_measurement_delay(Some(baseline), baseline),
+ Some(MINIMUM_CPU_UPDATE_INTERVAL)
+ );
+ assert_eq!(
+ remaining_cpu_measurement_delay(Some(baseline), baseline + MINIMUM_CPU_UPDATE_INTERVAL),
+ None
+ );
+ assert_eq!(remaining_cpu_measurement_delay(None, baseline), None);
+ }
+
+ #[test]
+ fn retains_bounded_history_without_request_ids() {
+ let mut history = HistoryRecorder::default();
+ for sequence in 0..=MAX_HISTORY_SNAPSHOTS {
+ history.record(&SnapshotEvent {
+ version: PROTOCOL_VERSION,
+ event_type: "snapshot",
+ sequence: sequence as u64,
+ sampled_at_unix_ms: sequence as u64 * 1_000,
+ collection_duration_micros: 1,
+ scanned_process_count: 0,
+ retained_process_count: 0,
+ inaccessible_process_count: 0,
+ request_id: Some("request".to_owned()),
+ external_processes: vec![ExternalProcess {
+ pid: 7,
+ start_time_ms: Some(1_000),
+ }],
+ processes: Vec::new(),
+ });
+ }
+
+ assert_eq!(history.snapshots.len(), MAX_HISTORY_SNAPSHOTS);
+ assert!(
+ history
+ .snapshots
+ .iter()
+ .all(|snapshot| snapshot.request_id.is_none())
+ );
+ assert!(history.snapshots.iter().all(|snapshot| {
+ snapshot.external_processes.len() == 1
+ && snapshot.external_processes[0].pid == 7
+ && snapshot.external_processes[0].start_time_ms == Some(1_000)
+ }));
+ assert_eq!(
+ history
+ .read(10_000, MAX_HISTORY_SNAPSHOTS as u64 * 1_000)
+ .len(),
+ 11
+ );
+ }
+
+ #[test]
+ fn excludes_and_trims_future_history_after_the_clock_moves_backward() {
+ let mut history = HistoryRecorder::default();
+ let snapshot = SnapshotEvent {
+ version: PROTOCOL_VERSION,
+ event_type: "snapshot",
+ sequence: 1,
+ sampled_at_unix_ms: 2_000,
+ collection_duration_micros: 1,
+ scanned_process_count: 0,
+ retained_process_count: 0,
+ inaccessible_process_count: 0,
+ request_id: None,
+ external_processes: Vec::new(),
+ processes: Vec::new(),
+ };
+ history.record(&snapshot);
+
+ assert!(history.read(0, 1_000).is_empty());
+
+ history.record(&SnapshotEvent {
+ sequence: 2,
+ sampled_at_unix_ms: 1_000,
+ ..snapshot
+ });
+ assert_eq!(history.snapshots.len(), 1);
+ assert_eq!(
+ history.snapshots.front().map(|entry| entry.sequence),
+ Some(2)
+ );
+ }
+
+ #[test]
+ fn bounds_history_by_estimated_process_bytes() {
+ let mut history = HistoryRecorder::default();
+ let command = "x".repeat(128);
+ let process = ProcessSample {
+ pid: 1,
+ ppid: 0,
+ start_time_ms: 0,
+ run_time_ms: 0,
+ name: "process".to_owned(),
+ command,
+ status: "Run".to_owned(),
+ cpu_percent: 0.0,
+ cpu_time_ms: 0,
+ resident_bytes: 0,
+ virtual_bytes: 0,
+ io_read_bytes: 0,
+ io_write_bytes: 0,
+ io_semantics: IoSemantics::Storage,
+ };
+ let snapshot_bytes =
+ std::mem::size_of::<SnapshotEvent>() + process.estimated_history_bytes();
+ for sequence in 0..3 {
+ history.record_with_limits(
+ &SnapshotEvent {
+ version: PROTOCOL_VERSION,
+ event_type: "snapshot",
+ sequence,
+ sampled_at_unix_ms: sequence * 1_000,
+ collection_duration_micros: 1,
+ scanned_process_count: 1,
+ retained_process_count: 1,
+ inaccessible_process_count: 0,
+ request_id: None,
+ external_processes: Vec::new(),
+ processes: vec![ProcessSample {
+ pid: sequence as u32 + 1,
+ start_time_ms: sequence * 1_000,
+ ..process.clone()
+ }],
+ },
+ 3,
+ 3,
+ snapshot_bytes * 2,
+ );
+ }
+
+ assert!(history.retained_bytes <= snapshot_bytes * 2);
+ assert_eq!(history.snapshots.len(), 2);
+ assert_eq!(
+ history.snapshots.front().map(|snapshot| snapshot.sequence),
+ Some(1)
+ );
+ }
+
+ #[test]
+ fn counts_external_processes_toward_history_limits() {
+ let mut history = HistoryRecorder::default();
+ let external_processes = (1..=128)
+ .map(|pid| ExternalProcess {
+ pid,
+ start_time_ms: Some(u64::from(pid) * 1_000),
+ })
+ .collect::<Vec<_>>();
+ let snapshot = SnapshotEvent {
+ version: PROTOCOL_VERSION,
+ event_type: "snapshot",
+ sequence: 0,
+ sampled_at_unix_ms: 0,
+ collection_duration_micros: 1,
+ scanned_process_count: 0,
+ retained_process_count: 0,
+ inaccessible_process_count: 0,
+ request_id: None,
+ external_processes,
+ processes: Vec::new(),
+ };
+ let snapshot_bytes = snapshot.estimated_history_bytes();
+ let snapshot_entries = snapshot.retained_entry_count();
+
+ for sequence in 0..3 {
+ history.record_with_limits(
+ &SnapshotEvent {
+ sequence,
+ sampled_at_unix_ms: sequence * 1_000,
+ ..snapshot.clone()
+ },
+ 3,
+ snapshot_entries * 2,
+ snapshot_bytes * 2,
+ );
+ }
+
+ assert_eq!(history.retained_entry_count, snapshot_entries * 2);
+ assert!(history.retained_bytes <= snapshot_bytes * 2);
+ assert_eq!(history.snapshots.len(), 2);
+ assert_eq!(
+ history.snapshots.front().map(|snapshot| snapshot.sequence),
+ Some(1)
+ );
+ }
+
+ #[test]
+ fn truncates_process_strings_at_utf8_boundaries() {
+ let value = "é".repeat(MAX_PROCESS_NAME_BYTES);
+ let truncated = truncate_utf8(value, MAX_PROCESS_NAME_BYTES - 1);
+
+ assert!(truncated.len() < MAX_PROCESS_NAME_BYTES);
+ assert!(truncated.is_char_boundary(truncated.len()));
+ }
+
+ #[test]
+ fn refreshes_commands_without_enumerating_linux_tasks() {
+ let refresh_kind = process_refresh_kind();
+
+ assert_eq!(refresh_kind.cmd(), UpdateKind::Always);
+ assert!(!refresh_kind.tasks());
+ assert!(refresh_kind.cpu());
+ assert!(refresh_kind.memory());
+ assert!(refresh_kind.disk_usage());
+ }
+
+ #[test]
+ fn sample_now_does_not_postpone_an_existing_periodic_deadline() {
+ let now = Instant::now();
+ let deadline = now + Duration::from_secs(1);
+
+ assert_eq!(
+ sample_now_deadline(
+ Some(deadline),
+ Some(Duration::from_secs(5)),
+ now + Duration::from_millis(100)
+ ),
+ Some(deadline)
+ );
+ }
+}
diff --git a/package.json b/package.json
index aebbd8a2f..3f6c269ae 100644
--- a/package.json
+++ b/package.json
@@ -20,11 +20,13 @@
"build": "vp run --filter './apps/*' --filter './packages/*' --filter './oxlint-plugin-t3code' --filter './scripts' build",
"build:marketing": "vp run --filter @t3tools/marketing build",
"build:desktop": "vp run --filter @t3tools/desktop --filter t3 build",
+ "build:resource-monitor": "cargo build --locked --release --manifest-path native/resource-monitor/Cargo.toml",
"typecheck": "vp run -r --concurrency-limit 2 typecheck",
"tc": "vp run -r --concurrency-limit 2 typecheck",
"lint": "vp lint --report-unused-disable-directives",
"lint:mobile": "node scripts/mobile-native-static-check.ts",
"test": "vp run -r test",
+ "test:resource-monitor": "cargo test --locked --manifest-path native/resource-monitor/Cargo.toml",
"test:desktop-smoke": "vp run --filter @t3tools/desktop smoke-test",
"fmt": "vp fmt",
"fmt:check": "vp fmt --check",
diff --git a/packages/client-runtime/src/rpc/client.ts b/packages/client-runtime/src/rpc/client.ts
index c7c928b3c..8013a1358 100644
--- a/packages/client-runtime/src/rpc/client.ts
+++ b/packages/client-runtime/src/rpc/client.ts
@@ -49,6 +49,7 @@ export type EnvironmentSubscriptionRpcTag =
| typeof WS_METHODS.subscribeTerminalMetadata
| typeof WS_METHODS.subscribePreviewEvents
| typeof WS_METHODS.subscribeDiscoveredLocalServers
+ | typeof WS_METHODS.subscribeResourceTelemetry
| typeof WS_METHODS.previewAutomationConnect
| typeof WS_METHODS.subscribeVcsStatus
| typeof WS_METHODS.terminalAttach;
@@ -62,6 +63,23 @@ export type EnvironmentStreamRpcTag =
| EnvironmentStreamCommandRpcTag;
export type EnvironmentUnaryRpcTag = Exclude<EnvironmentRpcTag, EnvironmentStreamRpcTag>;
+
+export interface EnvironmentRpcSubscriptionObservation {
+ readonly environmentId: string;
+ readonly method: EnvironmentSubscriptionRpcTag;
+ readonly input: unknown;
+}
+
+export class EnvironmentRpcSubscriptionObserver extends Context.Reference<{
+ readonly observe: (
+ subscription: EnvironmentRpcSubscriptionObservation,
+ ) => Effect.Effect<Effect.Effect<void>>;
+}>("@t3tools/client-runtime/rpc/EnvironmentRpcSubscriptionObserver", {
+ defaultValue: () => ({
+ observe: () => Effect.succeed(Effect.void),
+ }),
+}) {}
+
const isRpcClientError = Schema.is(RpcClientError.RpcClientError);
export type EnvironmentRpcInput<TTag extends EnvironmentRpcTag> = Parameters<RpcMethod<TTag>>[0];
@@ -166,93 +184,94 @@ export function subscribeDynamic<TTag extends EnvironmentSubscriptionRpcTag>(
EnvironmentSupervisor
> {
return Stream.unwrap(
- EnvironmentSupervisor.pipe(
- Effect.map((supervisor) => {
- const sessionChanges = SubscriptionRef.changes(supervisor.session);
- const sessions =
- options?.resubscribe === undefined
- ? sessionChanges
- : Stream.merge(
- sessionChanges,
- options.resubscribe.pipe(
- Stream.mapEffect(() => SubscriptionRef.get(supervisor.session)),
- ),
- );
- return sessions.pipe(
- Stream.switchMap(
- Option.match({
- onNone: () => Stream.empty,
- onSome: (session) => {
- const method = session.client[tag] as (
- input: EnvironmentRpcInput<TTag>,
- ) => Stream.Stream<
- EnvironmentRpcStreamValue<TTag>,
- EnvironmentRpcStreamFailure<TTag>
- >;
- const subscribeToSession = (): Stream.Stream<
- EnvironmentRpcStreamValue<TTag>,
- EnvironmentRpcStreamFailure<TTag>
- > =>
- Stream.suspend(() =>
- Stream.unwrap(
- makeInput(session).pipe(
- Effect.map((input) =>
- method(input).pipe(
- Stream.catchCause((cause) => {
- const hasOnlyExpectedFailures =
- cause.reasons.length > 0 &&
- cause.reasons.every((reason) => reason._tag === "Fail");
- const isTransportFailure =
- hasOnlyExpectedFailures &&
- cause.reasons.every(
- (reason) =>
- reason._tag === "Fail" && isRpcClientError(reason.error),
- );
- if (isTransportFailure) {
- return Stream.fromEffect(
- Effect.logWarning(
- "Durable RPC subscription lost its transport; waiting for the next session.",
- {
- cause: Cause.pretty(cause),
- method: tag,
- environmentId: supervisor.target.environmentId,
- },
- ),
- ).pipe(Stream.drain);
- }
- if (
- hasOnlyExpectedFailures &&
- options?.onExpectedFailure !== undefined
- ) {
- const handled = Stream.fromEffect(
- options.onExpectedFailure(cause),
- ).pipe(Stream.drain);
- if (options.retryExpectedFailureAfter === undefined) {
- return handled;
- }
- return handled.pipe(
- Stream.concat(
- Stream.fromEffect(
- Effect.sleep(options.retryExpectedFailureAfter),
- ).pipe(Stream.drain),
- ),
- Stream.concat(subscribeToSession()),
- );
- }
- return Stream.failCause(cause);
- }),
- ),
- ),
- ),
- ),
- );
- return subscribeToSession();
- },
- }),
- ),
- );
- }),
- ),
+ Effect.gen(function* () {
+ const supervisor = yield* EnvironmentSupervisor;
+ const observer = yield* EnvironmentRpcSubscriptionObserver;
+ const sessionChanges = SubscriptionRef.changes(supervisor.session);
+ const sessions =
+ options?.resubscribe === undefined
+ ? sessionChanges
+ : Stream.merge(
+ sessionChanges,
+ options.resubscribe.pipe(
+ Stream.mapEffect(() => SubscriptionRef.get(supervisor.session)),
+ ),
+ );
+ return sessions.pipe(
+ Stream.switchMap(
+ Option.match({
+ onNone: () => Stream.empty,
+ onSome: (session) => {
+ const method = session.client[tag] as (
+ input: EnvironmentRpcInput<TTag>,
+ ) => Stream.Stream<
+ EnvironmentRpcStreamValue<TTag>,
+ EnvironmentRpcStreamFailure<TTag>
+ >;
+ const subscribeToSession = (): Stream.Stream<
+ EnvironmentRpcStreamValue<TTag>,
+ EnvironmentRpcStreamFailure<TTag>
+ > =>
+ Stream.suspend(() =>
+ Stream.unwrap(
+ Effect.gen(function* () {
+ const input = yield* makeInput(session);
+ const completeObservation = yield* observer.observe({
+ environmentId: supervisor.target.environmentId,
+ method: tag,
+ input,
+ });
+ return method(input).pipe(
+ Stream.ensuring(completeObservation),
+ Stream.catchCause((cause) => {
+ const hasOnlyExpectedFailures =
+ cause.reasons.length > 0 &&
+ cause.reasons.every((reason) => reason._tag === "Fail");
+ const isTransportFailure =
+ hasOnlyExpectedFailures &&
+ cause.reasons.every(
+ (reason) => reason._tag === "Fail" && isRpcClientError(reason.error),
+ );
+ if (isTransportFailure) {
+ return Stream.fromEffect(
+ Effect.logWarning(
+ "Durable RPC subscription lost its transport; waiting for the next session.",
+ {
+ cause: Cause.pretty(cause),
+ method: tag,
+ environmentId: supervisor.target.environmentId,
+ },
+ ),
+ ).pipe(Stream.drain);
+ }
+ if (hasOnlyExpectedFailures && options?.onExpectedFailure !== undefined) {
+ const handled = Stream.fromEffect(
+ options.onExpectedFailure(cause),
+ ).pipe(Stream.drain);
+ if (options.retryExpectedFailureAfter === undefined) {
+ return handled;
+ }
+ return handled.pipe(
+ Stream.concat(
+ Stream.fromEffect(
+ Effect.sleep(options.retryExpectedFailureAfter),
+ ).pipe(Stream.drain),
+ ),
+ Stream.concat(subscribeToSession()),
+ );
+ }
+ return Stream.failCause(cause);
+ }),
+ );
+ }),
+ ),
+ );
+ return subscribeToSession();
+ },
+ }),
+ ),
+ );
+ }),
).pipe(
Stream.withSpan("EnvironmentRpc.subscribe", {
attributes: { "rpc.method": tag },
diff --git a/packages/client-runtime/src/state/server.ts b/packages/client-runtime/src/state/server.ts
index ea7f5fb6d..5f93a3edb 100644
--- a/packages/client-runtime/src/state/server.ts
+++ b/packages/client-runtime/src/state/server.ts
@@ -298,6 +298,16 @@ export function createServerEnvironmentAtoms<R, E>(
label: "environment-data:server:process-resource-history",
tag: WS_METHODS.serverGetProcessResourceHistory,
}),
+ resourceTelemetry: createEnvironmentRpcSubscriptionAtomFamily(runtime, {
+ label: "environment-data:server:resource-telemetry",
+ tag: WS_METHODS.subscribeResourceTelemetry,
+ idleTtlMs: 0,
+ }),
+ resourceTelemetryHistory: createEnvironmentRpcQueryAtomFamily(runtime, {
+ label: "environment-data:server:resource-telemetry-history",
+ tag: WS_METHODS.serverGetResourceTelemetryHistory,
+ staleTimeMs: 5_000,
+ }),
configProjection,
welcome: createEnvironmentRpcSubscriptionAtomFamily(runtime, {
label: "environment-data:server:welcome",
@@ -349,5 +359,13 @@ export function createServerEnvironmentAtoms<R, E>(
label: "environment-data:server:signal-process",
tag: WS_METHODS.serverSignalProcess,
}),
+ retryResourceTelemetry: createEnvironmentRpcCommand(runtime, {
+ label: "environment-data:server:retry-resource-telemetry",
+ tag: WS_METHODS.serverRetryResourceTelemetry,
+ concurrency: {
+ mode: "singleFlight",
+ key: ({ environmentId }) => environmentId,
+ },
+ }),
};
}
diff --git a/packages/contracts/src/background.test.ts b/packages/contracts/src/background.test.ts
new file mode 100644
index 000000000..fcb772098
--- /dev/null
+++ b/packages/contracts/src/background.test.ts
@@ -0,0 +1,18 @@
+import * as Schema from "effect/Schema";
+import { describe, expect, it } from "vite-plus/test";
+
+import { ClientActivityClientId } from "./background.ts";
+
+const decodeClientActivityClientId = Schema.decodeUnknownSync(ClientActivityClientId);
+
+describe("ClientActivityClientId", () => {
+ it("trims and accepts bounded client identifiers", () => {
+ expect(decodeClientActivityClientId(" client-1 ")).toBe("client-1");
+ expect(decodeClientActivityClientId("x".repeat(128))).toBe("x".repeat(128));
+ });
+
+ it("rejects empty and oversized client identifiers", () => {
+ expect(() => decodeClientActivityClientId(" ")).toThrow();
+ expect(() => decodeClientActivityClientId("x".repeat(129))).toThrow();
+ });
+});
diff --git a/packages/contracts/src/background.ts b/packages/contracts/src/background.ts
new file mode 100644
index 000000000..3042b4b19
--- /dev/null
+++ b/packages/contracts/src/background.ts
@@ -0,0 +1,110 @@
+import * as Schema from "effect/Schema";
+
+import {
+ AuthSessionId,
+ EnvironmentId,
+ RpcClientId,
+ ThreadId,
+ TrimmedNonEmptyString,
+} from "./baseSchemas.ts";
+import { ProviderInstanceId } from "./providerInstance.ts";
+
+export const BackgroundBooleanState = Schema.Literals(["true", "false", "unknown"]);
+export type BackgroundBooleanState = typeof BackgroundBooleanState.Type;
+
+export const HostPowerThermalState = Schema.Literals([
+ "unknown",
+ "nominal",
+ "fair",
+ "serious",
+ "critical",
+]);
+export type HostPowerThermalState = typeof HostPowerThermalState.Type;
+
+export const HostPowerSource = Schema.Literals([
+ "unknown",
+ "node-macos-shell",
+ "node-macos-native",
+ "node-linux",
+ "node-windows",
+ "electron-main",
+]);
+export type HostPowerSource = typeof HostPowerSource.Type;
+
+export const HostPowerSnapshot = Schema.Struct({
+ source: HostPowerSource,
+ idle: BackgroundBooleanState,
+ idleSeconds: Schema.NullOr(Schema.Number),
+ locked: BackgroundBooleanState,
+ suspended: Schema.Boolean,
+ onBattery: BackgroundBooleanState,
+ lowPowerMode: BackgroundBooleanState,
+ thermalState: HostPowerThermalState,
+ stale: Schema.Boolean,
+ updatedAt: Schema.DateTimeUtc,
+});
+export type HostPowerSnapshot = typeof HostPowerSnapshot.Type;
+
+export const BackgroundScope = Schema.Union([
+ Schema.Struct({ type: Schema.Literal("server-config") }),
+ Schema.Struct({
+ type: Schema.Literal("provider-status"),
+ instanceId: Schema.optionalKey(ProviderInstanceId),
+ }),
+ Schema.Struct({ type: Schema.Literal("vcs-status"), cwd: Schema.String }),
+ Schema.Struct({ type: Schema.Literal("git-refs"), cwd: Schema.String }),
+ Schema.Struct({ type: Schema.Literal("diagnostics") }),
+ Schema.Struct({ type: Schema.Literal("thread"), threadId: ThreadId }),
+]);
+export type BackgroundScope = typeof BackgroundScope.Type;
+
+export const ClientKind = Schema.Literals(["web", "desktop-renderer", "mobile", "unknown"]);
+export type ClientKind = typeof ClientKind.Type;
+
+export const ClientActivityClientId = TrimmedNonEmptyString.check(Schema.isMaxLength(128));
+export type ClientActivityClientId = typeof ClientActivityClientId.Type;
+
+export const ClientActivityReportInput = Schema.Struct({
+ environmentId: Schema.optionalKey(EnvironmentId),
+ clientId: ClientActivityClientId,
+ clientKind: ClientKind,
+ visible: Schema.Boolean,
+ focused: Schema.Boolean,
+ recentlyInteracted: Schema.Boolean,
+ appState: Schema.optionalKey(Schema.Literals(["active", "inactive", "background", "unknown"])),
+ lowPowerMode: Schema.optionalKey(BackgroundBooleanState),
+ batteryState: Schema.optionalKey(Schema.Literals(["unknown", "unplugged", "charging", "full"])),
+ networkType: Schema.optionalKey(Schema.String),
+ scopes: Schema.Array(BackgroundScope),
+ ttlMs: Schema.optionalKey(Schema.Number),
+ observedAt: Schema.DateTimeUtc,
+});
+export type ClientActivityReportInput = typeof ClientActivityReportInput.Type;
+
+export const ClientActivityLease = Schema.Struct({
+ sessionId: AuthSessionId,
+ rpcClientId: RpcClientId,
+ clientId: ClientActivityClientId,
+ clientKind: ClientKind,
+ visible: Schema.Boolean,
+ focused: Schema.Boolean,
+ recentlyInteracted: Schema.Boolean,
+ appState: Schema.optionalKey(Schema.Literals(["active", "inactive", "background", "unknown"])),
+ lowPowerMode: Schema.optionalKey(BackgroundBooleanState),
+ batteryState: Schema.optionalKey(Schema.Literals(["unknown", "unplugged", "charging", "full"])),
+ networkType: Schema.optionalKey(Schema.String),
+ scopes: Schema.Array(BackgroundScope),
+ updatedAt: Schema.DateTimeUtc,
+ expiresAt: Schema.DateTimeUtc,
+});
+export type ClientActivityLease = typeof ClientActivityLease.Type;
+
+export const BackgroundPolicySnapshot = Schema.Struct({
+ hostPower: HostPowerSnapshot,
+ leases: Schema.Array(ClientActivityLease),
+ activeForegroundLeaseCount: Schema.Number,
+ activeScopeKeys: Schema.Array(Schema.String),
+ shouldRunOpportunisticWork: Schema.Boolean,
+ updatedAt: Schema.DateTimeUtc,
+});
+export type BackgroundPolicySnapshot = typeof BackgroundPolicySnapshot.Type;
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts
index 614ea5131..a8fa565ce 100644
--- a/packages/contracts/src/baseSchemas.ts
+++ b/packages/contracts/src/baseSchemas.ts
@@ -43,6 +43,8 @@ export const TurnId = makeEntityId("TurnId");
export type TurnId = typeof TurnId.Type;
export const AuthSessionId = makeEntityId("AuthSessionId");
export type AuthSessionId = typeof AuthSessionId.Type;
+export const RpcClientId = NonNegativeInt.pipe(Schema.brand("RpcClientId"));
+export type RpcClientId = typeof RpcClientId.Type;
export const ProviderItemId = makeEntityId("ProviderItemId");
export type ProviderItemId = typeof ProviderItemId.Type;
diff --git a/packages/contracts/src/desktopBootstrap.ts b/packages/contracts/src/desktopBootstrap.ts
index e09f43a0e..f4d1a0927 100644
--- a/packages/contracts/src/desktopBootstrap.ts
+++ b/packages/contracts/src/desktopBootstrap.ts
@@ -1,6 +1,6 @@
import * as Schema from "effect/Schema";
-import { PortSchema } from "./baseSchemas.ts";
+import { PortSchema, PositiveInt, TrimmedNonEmptyString } from "./baseSchemas.ts";
export const DesktopBackendBootstrap = Schema.Struct({
mode: Schema.Literal("desktop"),
@@ -16,6 +16,9 @@ export const DesktopBackendBootstrap = Schema.Struct({
tailscaleServePort: PortSchema,
otlpTracesUrl: Schema.optional(Schema.String),
otlpMetricsUrl: Schema.optional(Schema.String),
+ desktopTelemetryFd: Schema.optionalKey(PositiveInt),
+ desktopTelemetryControlFd: Schema.optionalKey(PositiveInt),
+ resourceMonitorPath: Schema.optionalKey(TrimmedNonEmptyString),
});
export type DesktopBackendBootstrap = typeof DesktopBackendBootstrap.Type;
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 5936cb0fc..f0ee18891 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -1,4 +1,5 @@
export * from "./baseSchemas.ts";
+export * from "./background.ts";
export * from "./auth.ts";
export * from "./environment.ts";
export * from "./environmentHttp.ts";
@@ -26,4 +27,5 @@ export * from "./assets.ts";
export * from "./review.ts";
export * from "./preview.ts";
export * from "./previewAutomation.ts";
+export * from "./resourceTelemetry.ts";
export * from "./rpc.ts";
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index f6f28262a..a92eb972d 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -31,20 +31,6 @@ import type {
ProjectWriteFileInput,
ProjectWriteFileResult,
} from "./project.ts";
-import type { ProviderInstanceId } from "./providerInstance.ts";
-import type {
- ServerConfig,
- ServerProcessDiagnosticsResult,
- ServerProcessResourceHistoryInput,
- ServerProcessResourceHistoryResult,
- ServerProviderUpdateInput,
- ServerProviderUpdatedPayload,
- ServerRemoveKeybindingResult,
- ServerSignalProcessInput,
- ServerSignalProcessResult,
- ServerTraceDiagnosticsResult,
- ServerUpsertKeybindingResult,
-} from "./server.ts";
import type {
TerminalAttachInput,
TerminalAttachStreamEvent,
@@ -57,7 +43,6 @@ import type {
TerminalSessionSnapshot,
TerminalWriteInput,
} from "./terminal.ts";
-import type { ServerRemoveKeybindingInput, ServerUpsertKeybindingInput } from "./server.ts";
import * as Schema from "effect/Schema";
import type {
DiscoveredLocalServerList,
@@ -100,13 +85,11 @@ import type {
import { EnvironmentId } from "./baseSchemas.ts";
import { AuthAccessTokenResult, AuthSessionState, AuthWebSocketTicketResult } from "./auth.ts";
import { AdvertisedEndpoint } from "./remoteAccess.ts";
-import { EditorId } from "./editor.ts";
import { ExecutionEnvironmentDescriptor } from "./environment.ts";
-import type { ClientSettings, ServerSettings, ServerSettingsPatch } from "./settings.ts";
+import type { ClientSettings } from "./settings.ts";
import type {
SourceControlCloneRepositoryInput,
SourceControlCloneRepositoryResult,
- SourceControlDiscoveryResult,
SourceControlPublishRepositoryInput,
SourceControlPublishRepositoryResult,
SourceControlRepositoryInfo,
@@ -1115,7 +1098,7 @@ export interface DesktopPreviewBridge {
* APIs bound to the local app shell, not to any particular backend environment.
*
* These capabilities describe the desktop/browser host that the user is
- * currently running: dialogs, editor/external-link opening, context menus, and
+ * currently running: dialogs, external-link opening, context menus, and
* app-level settings/config access. They must not be used as a proxy for
* "whatever environment the user is targeting", because in a multi-environment
* world the local shell and a selected backend environment are distinct
@@ -1127,7 +1110,6 @@ export interface LocalApi {
confirm: (message: string) => Promise<boolean>;
};
shell: {
- openInEditor: (cwd: string, editor: EditorId) => Promise<void>;
openExternal: (url: string) => Promise<void>;
};
contextMenu: {
@@ -1140,29 +1122,6 @@ export interface LocalApi {
getClientSettings: () => Promise<ClientSettings | null>;
setClientSettings: (settings: ClientSettings) => Promise<void>;
};
- server: {
- getConfig: () => Promise<ServerConfig>;
- /**
- * Refresh provider snapshots. When `input.instanceId` is supplied only that
- * configured instance is probed; otherwise every configured instance is
- * refreshed (legacy untargeted refresh).
- */
- refreshProviders: (input?: {
- readonly instanceId?: ProviderInstanceId;
- }) => Promise<ServerProviderUpdatedPayload>;
- updateProvider: (input: ServerProviderUpdateInput) => Promise<ServerProviderUpdatedPayload>;
- upsertKeybinding: (input: ServerUpsertKeybindingInput) => Promise<ServerUpsertKeybindingResult>;
- removeKeybinding: (input: ServerRemoveKeybindingInput) => Promise<ServerRemoveKeybindingResult>;
- getSettings: () => Promise<ServerSettings>;
- updateSettings: (patch: ServerSettingsPatch) => Promise<ServerSettings>;
- discoverSourceControl: () => Promise<SourceControlDiscoveryResult>;
- getTraceDiagnostics: () => Promise<ServerTraceDiagnosticsResult>;
- getProcessDiagnostics: () => Promise<ServerProcessDiagnosticsResult>;
- getProcessResourceHistory: (
- input: ServerProcessResourceHistoryInput,
- ) => Promise<ServerProcessResourceHistoryResult>;
- signalProcess: (input: ServerSignalProcessInput) => Promise<ServerSignalProcessResult>;
- };
}
/**
diff --git a/packages/contracts/src/resourceTelemetry.ts b/packages/contracts/src/resourceTelemetry.ts
new file mode 100644
index 000000000..2c1b2ffec
--- /dev/null
+++ b/packages/contracts/src/resourceTelemetry.ts
@@ -0,0 +1,430 @@
+import * as Schema from "effect/Schema";
+
+import { NonNegativeInt, PositiveInt, TrimmedNonEmptyString } from "./baseSchemas.ts";
+import { HostPowerSnapshot } from "./background.ts";
+
+export const RESOURCE_MONITOR_PROTOCOL_VERSION = 2 as const;
+
+export const ResourceTelemetryIoSemantics = Schema.Literals([
+ "storage",
+ "logical",
+ "all-io",
+ "unavailable",
+]);
+export type ResourceTelemetryIoSemantics = typeof ResourceTelemetryIoSemantics.Type;
+
+export const ResourceTelemetryProcessCategory = Schema.Literals([
+ "server",
+ "server-child",
+ "provider-root",
+ "terminal-root",
+ "electron-main",
+ "electron-renderer",
+ "electron-gpu",
+ "electron-utility",
+ "resource-monitor",
+ "unknown-t3",
+]);
+export type ResourceTelemetryProcessCategory = typeof ResourceTelemetryProcessCategory.Type;
+
+export const ResourceTelemetrySourceStatus = Schema.Literals([
+ "starting",
+ "healthy",
+ "degraded",
+ "unavailable",
+ "stopped",
+]);
+export type ResourceTelemetrySourceStatus = typeof ResourceTelemetrySourceStatus.Type;
+
+export const ResourceTelemetryProcessIdentity = Schema.Struct({
+ pid: PositiveInt,
+ startTimeMs: NonNegativeInt,
+});
+export type ResourceTelemetryProcessIdentity = typeof ResourceTelemetryProcessIdentity.Type;
+
+export const ResourceMonitorExternalProcess = Schema.Struct({
+ pid: PositiveInt,
+ startTimeMs: Schema.optionalKey(NonNegativeInt),
+});
+export type ResourceMonitorExternalProcess = typeof ResourceMonitorExternalProcess.Type;
+
+export const ResourceMonitorCapabilities = Schema.Struct({
+ cumulativeCpuTime: Schema.Boolean,
+ currentCpuPercent: Schema.Boolean,
+ residentMemory: Schema.Boolean,
+ virtualMemory: Schema.Boolean,
+ ioBytes: Schema.Boolean,
+ processStartTime: Schema.Boolean,
+ processTree: Schema.Boolean,
+});
+export type ResourceMonitorCapabilities = typeof ResourceMonitorCapabilities.Type;
+
+export const ResourceMonitorProcessSample = Schema.Struct({
+ pid: PositiveInt,
+ ppid: NonNegativeInt,
+ startTimeMs: NonNegativeInt,
+ runTimeMs: NonNegativeInt,
+ name: Schema.String,
+ command: Schema.String,
+ status: Schema.String,
+ cpuPercent: Schema.Number,
+ cpuTimeMs: NonNegativeInt,
+ residentBytes: NonNegativeInt,
+ virtualBytes: NonNegativeInt,
+ ioReadBytes: NonNegativeInt,
+ ioWriteBytes: NonNegativeInt,
+ ioSemantics: Schema.Literals(["storage", "all-io"]),
+});
+export type ResourceMonitorProcessSample = typeof ResourceMonitorProcessSample.Type;
+
+export const ResourceMonitorConfigureCommand = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("configure"),
+ rootPid: PositiveInt,
+ sampleIntervalMs: NonNegativeInt,
+ externalProcesses: Schema.Array(ResourceMonitorExternalProcess),
+});
+export type ResourceMonitorConfigureCommand = typeof ResourceMonitorConfigureCommand.Type;
+
+export const ResourceMonitorSetExternalProcessesCommand = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("setExternalProcesses"),
+ processes: Schema.Array(ResourceMonitorExternalProcess),
+});
+export type ResourceMonitorSetExternalProcessesCommand =
+ typeof ResourceMonitorSetExternalProcessesCommand.Type;
+
+export const ResourceMonitorSampleNowCommand = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("sampleNow"),
+ requestId: TrimmedNonEmptyString,
+});
+export type ResourceMonitorSampleNowCommand = typeof ResourceMonitorSampleNowCommand.Type;
+
+export const ResourceMonitorSetSampleIntervalCommand = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("setSampleInterval"),
+ sampleIntervalMs: NonNegativeInt,
+});
+export type ResourceMonitorSetSampleIntervalCommand =
+ typeof ResourceMonitorSetSampleIntervalCommand.Type;
+
+export const ResourceMonitorSetStreamingCommand = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("setStreaming"),
+ enabled: Schema.Boolean,
+});
+export type ResourceMonitorSetStreamingCommand = typeof ResourceMonitorSetStreamingCommand.Type;
+
+export const ResourceMonitorReadHistoryCommand = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("readHistory"),
+ requestId: TrimmedNonEmptyString,
+ windowMs: NonNegativeInt,
+});
+export type ResourceMonitorReadHistoryCommand = typeof ResourceMonitorReadHistoryCommand.Type;
+
+export const ResourceMonitorShutdownCommand = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("shutdown"),
+});
+export type ResourceMonitorShutdownCommand = typeof ResourceMonitorShutdownCommand.Type;
+
+export const ResourceMonitorCommand = Schema.Union([
+ ResourceMonitorConfigureCommand,
+ ResourceMonitorSetExternalProcessesCommand,
+ ResourceMonitorSetSampleIntervalCommand,
+ ResourceMonitorSetStreamingCommand,
+ ResourceMonitorSampleNowCommand,
+ ResourceMonitorReadHistoryCommand,
+ ResourceMonitorShutdownCommand,
+]);
+export type ResourceMonitorCommand = typeof ResourceMonitorCommand.Type;
+
+export const ResourceMonitorHelloEvent = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("hello"),
+ sidecarVersion: TrimmedNonEmptyString,
+ sidecarPid: PositiveInt,
+ platform: TrimmedNonEmptyString,
+ arch: TrimmedNonEmptyString,
+ capabilities: ResourceMonitorCapabilities,
+});
+export type ResourceMonitorHelloEvent = typeof ResourceMonitorHelloEvent.Type;
+
+export const ResourceMonitorSnapshotEvent = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("snapshot"),
+ sequence: NonNegativeInt,
+ sampledAtUnixMs: NonNegativeInt,
+ collectionDurationMicros: NonNegativeInt,
+ scannedProcessCount: NonNegativeInt,
+ retainedProcessCount: NonNegativeInt,
+ inaccessibleProcessCount: NonNegativeInt,
+ requestId: Schema.optionalKey(TrimmedNonEmptyString),
+ externalProcesses: Schema.optionalKey(Schema.Array(ResourceMonitorExternalProcess)),
+ processes: Schema.Array(ResourceMonitorProcessSample),
+});
+export type ResourceMonitorSnapshotEvent = typeof ResourceMonitorSnapshotEvent.Type;
+
+export const ResourceMonitorHistoryChunkEvent = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("historyChunk"),
+ requestId: TrimmedNonEmptyString,
+ done: Schema.Boolean,
+ snapshots: Schema.Array(ResourceMonitorSnapshotEvent),
+});
+export type ResourceMonitorHistoryChunkEvent = typeof ResourceMonitorHistoryChunkEvent.Type;
+
+export const ResourceMonitorErrorEvent = Schema.Struct({
+ version: Schema.Literal(RESOURCE_MONITOR_PROTOCOL_VERSION),
+ type: Schema.Literal("error"),
+ code: TrimmedNonEmptyString,
+ message: TrimmedNonEmptyString,
+ recoverable: Schema.Boolean,
+});
+export type ResourceMonitorErrorEvent = typeof ResourceMonitorErrorEvent.Type;
+
+export const ResourceMonitorEvent = Schema.Union([
+ ResourceMonitorHelloEvent,
+ ResourceMonitorSnapshotEvent,
+ ResourceMonitorHistoryChunkEvent,
+ ResourceMonitorErrorEvent,
+]);
+export type ResourceMonitorEvent = typeof ResourceMonitorEvent.Type;
+
+export const DesktopElectronProcessType = Schema.Literals([
+ "Browser",
+ "Tab",
+ "Utility",
+ "Zygote",
+ "Sandbox helper",
+ "GPU",
+ "Pepper Plugin",
+ "Pepper Plugin Broker",
+ "Unknown",
+]);
+export type DesktopElectronProcessType = typeof DesktopElectronProcessType.Type;
+
+export const DesktopElectronProcessMetric = Schema.Struct({
+ pid: PositiveInt,
+ creationTimeMs: NonNegativeInt,
+ type: DesktopElectronProcessType,
+ name: Schema.optionalKey(Schema.String),
+ serviceName: Schema.optionalKey(Schema.String),
+ cpuPercent: Schema.Number,
+ cumulativeCpuSeconds: Schema.optionalKey(Schema.Number),
+ idleWakeupsPerSecond: Schema.Number,
+ workingSetBytes: NonNegativeInt,
+ peakWorkingSetBytes: NonNegativeInt,
+});
+export type DesktopElectronProcessMetric = typeof DesktopElectronProcessMetric.Type;
+
+const DesktopHostPowerSnapshot = Schema.Struct({
+ ...HostPowerSnapshot.fields,
+ updatedAt: Schema.DateTimeUtcFromString,
+});
+
+export const DesktopHostTelemetrySnapshot = Schema.Struct({
+ version: Schema.Literal(1),
+ type: Schema.Literal("desktopTelemetry"),
+ sequence: NonNegativeInt,
+ sampledAtUnixMs: NonNegativeInt,
+ electronPid: PositiveInt,
+ power: DesktopHostPowerSnapshot,
+ speedLimitPercent: Schema.OptionFromNullOr(Schema.Number),
+ electronProcesses: Schema.Array(DesktopElectronProcessMetric),
+});
+export type DesktopHostTelemetrySnapshot = typeof DesktopHostTelemetrySnapshot.Type;
+
+export const DesktopHostTelemetryHello = Schema.Struct({
+ version: Schema.Literal(1),
+ type: Schema.Literal("desktopTelemetryHello"),
+ electronPid: PositiveInt,
+});
+export type DesktopHostTelemetryHello = typeof DesktopHostTelemetryHello.Type;
+
+export const DesktopHostTelemetryMessage = Schema.Union([
+ DesktopHostTelemetryHello,
+ DesktopHostTelemetrySnapshot,
+]);
+export type DesktopHostTelemetryMessage = typeof DesktopHostTelemetryMessage.Type;
+
+export const DesktopTelemetrySetDiagnosticsDemand = Schema.Struct({
+ version: Schema.Literal(1),
+ type: Schema.Literal("setDiagnosticsDemand"),
+ enabled: Schema.Boolean,
+});
+export type DesktopTelemetrySetDiagnosticsDemand = typeof DesktopTelemetrySetDiagnosticsDemand.Type;
+
+export const DesktopTelemetrySetHostPowerIntervals = Schema.Struct({
+ version: Schema.Literal(1),
+ type: Schema.Literal("setHostPowerIntervals"),
+ activeIntervalMs: PositiveInt,
+ idleIntervalMs: PositiveInt,
+});
+export type DesktopTelemetrySetHostPowerIntervals =
+ typeof DesktopTelemetrySetHostPowerIntervals.Type;
+
+export const DesktopTelemetryControlMessage = Schema.Union([
+ DesktopTelemetrySetDiagnosticsDemand,
+ DesktopTelemetrySetHostPowerIntervals,
+]);
+export type DesktopTelemetryControlMessage = typeof DesktopTelemetryControlMessage.Type;
+
+export const ResourceTelemetryProcess = Schema.Struct({
+ identity: ResourceTelemetryProcessIdentity,
+ ppid: NonNegativeInt,
+ childPids: Schema.Array(PositiveInt),
+ depth: NonNegativeInt,
+ name: Schema.String,
+ command: Schema.String,
+ status: Schema.String,
+ category: ResourceTelemetryProcessCategory,
+ electronType: Schema.optionalKey(DesktopElectronProcessType),
+ electronServiceName: Schema.optionalKey(Schema.String),
+ cpuPercent: Schema.Number,
+ cpuTimeMs: NonNegativeInt,
+ residentBytes: NonNegativeInt,
+ peakResidentBytes: NonNegativeInt,
+ virtualBytes: NonNegativeInt,
+ ioReadBytes: NonNegativeInt,
+ ioWriteBytes: NonNegativeInt,
+ ioReadBytesPerSecond: Schema.Number,
+ ioWriteBytesPerSecond: Schema.Number,
+ ioSemantics: ResourceTelemetryIoSemantics,
+ idleWakeupsPerSecond: Schema.optionalKey(Schema.Number),
+ runTimeMs: NonNegativeInt,
+ firstSeenAt: Schema.DateTimeUtc,
+ lastSeenAt: Schema.DateTimeUtc,
+});
+export type ResourceTelemetryProcess = typeof ResourceTelemetryProcess.Type;
+
+export const ResourceTelemetryAggregate = Schema.Struct({
+ processCount: NonNegativeInt,
+ currentCpuPercent: Schema.Number,
+ cpuTimeMs: NonNegativeInt,
+ currentRssBytes: NonNegativeInt,
+ peakRssBytes: NonNegativeInt,
+ ioReadBytes: NonNegativeInt,
+ ioWriteBytes: NonNegativeInt,
+ ioReadBytesPerSecond: Schema.Number,
+ ioWriteBytesPerSecond: Schema.Number,
+ processStarts: NonNegativeInt,
+ processExits: NonNegativeInt,
+});
+export type ResourceTelemetryAggregate = typeof ResourceTelemetryAggregate.Type;
+
+export const ResourceTelemetryGroups = Schema.Struct({
+ backend: ResourceTelemetryAggregate,
+ electron: ResourceTelemetryAggregate,
+ monitor: ResourceTelemetryAggregate,
+ allT3: ResourceTelemetryAggregate,
+});
+export type ResourceTelemetryGroups = typeof ResourceTelemetryGroups.Type;
+
+export const ResourceTelemetrySourceHealth = Schema.Struct({
+ status: ResourceTelemetrySourceStatus,
+ lastSampleAt: Schema.Option(Schema.DateTimeUtc),
+ lastError: Schema.Option(TrimmedNonEmptyString),
+});
+export type ResourceTelemetrySourceHealth = typeof ResourceTelemetrySourceHealth.Type;
+
+export const ResourceTelemetryHealth = Schema.Struct({
+ native: ResourceTelemetrySourceHealth,
+ desktop: ResourceTelemetrySourceHealth,
+ sidecarVersion: Schema.Option(TrimmedNonEmptyString),
+ sidecarPid: Schema.Option(PositiveInt),
+ restartCount: NonNegativeInt,
+ collectionDurationMicros: NonNegativeInt,
+ scannedProcessCount: NonNegativeInt,
+ retainedProcessCount: NonNegativeInt,
+ inaccessibleProcessCount: NonNegativeInt,
+});
+export type ResourceTelemetryHealth = typeof ResourceTelemetryHealth.Type;
+
+export const ResourceAttributionEntry = Schema.Struct({
+ component: TrimmedNonEmptyString,
+ operation: TrimmedNonEmptyString,
+ logicalReadBytes: NonNegativeInt,
+ logicalWriteBytes: NonNegativeInt,
+ count: NonNegativeInt,
+ durationMs: NonNegativeInt,
+});
+export type ResourceAttributionEntry = typeof ResourceAttributionEntry.Type;
+
+export const ResourceAttributionSnapshot = Schema.Struct({
+ readAt: Schema.DateTimeUtc,
+ entries: Schema.Array(ResourceAttributionEntry),
+});
+export type ResourceAttributionSnapshot = typeof ResourceAttributionSnapshot.Type;
+
+export const ResourceTelemetrySnapshot = Schema.Struct({
+ readAt: Schema.DateTimeUtc,
+ sampleIntervalMs: NonNegativeInt,
+ processes: Schema.Array(ResourceTelemetryProcess),
+ groups: ResourceTelemetryGroups,
+ power: HostPowerSnapshot,
+ speedLimitPercent: Schema.Option(Schema.Number),
+ attribution: ResourceAttributionSnapshot,
+ health: ResourceTelemetryHealth,
+});
+export type ResourceTelemetrySnapshot = typeof ResourceTelemetrySnapshot.Type;
+
+export const ResourceTelemetryHistoryInput = Schema.Struct({
+ windowMs: NonNegativeInt,
+ bucketMs: NonNegativeInt,
+});
+export type ResourceTelemetryHistoryInput = typeof ResourceTelemetryHistoryInput.Type;
+
+export const ResourceTelemetryHistoryBucket = Schema.Struct({
+ startedAt: Schema.DateTimeUtc,
+ endedAt: Schema.DateTimeUtc,
+ avgCpuPercent: Schema.Number,
+ maxCpuPercent: Schema.Number,
+ maxRssBytes: NonNegativeInt,
+ ioReadBytes: NonNegativeInt,
+ ioWriteBytes: NonNegativeInt,
+ maxProcessCount: NonNegativeInt,
+});
+export type ResourceTelemetryHistoryBucket = typeof ResourceTelemetryHistoryBucket.Type;
+
+export const ResourceTelemetryProcessSummary = Schema.Struct({
+ identity: ResourceTelemetryProcessIdentity,
+ ppid: NonNegativeInt,
+ depth: NonNegativeInt,
+ name: Schema.String,
+ command: Schema.String,
+ category: ResourceTelemetryProcessCategory,
+ firstSeenAt: Schema.DateTimeUtc,
+ lastSeenAt: Schema.DateTimeUtc,
+ currentCpuPercent: Schema.Number,
+ avgCpuPercent: Schema.Number,
+ maxCpuPercent: Schema.Number,
+ cpuTimeMs: NonNegativeInt,
+ currentRssBytes: NonNegativeInt,
+ peakRssBytes: NonNegativeInt,
+ ioReadBytes: NonNegativeInt,
+ ioWriteBytes: NonNegativeInt,
+ ioSemantics: ResourceTelemetryIoSemantics,
+ sampleCount: NonNegativeInt,
+});
+export type ResourceTelemetryProcessSummary = typeof ResourceTelemetryProcessSummary.Type;
+
+export const ResourceTelemetryHistory = Schema.Struct({
+ readAt: Schema.DateTimeUtc,
+ windowMs: NonNegativeInt,
+ bucketMs: NonNegativeInt,
+ sampleIntervalMs: NonNegativeInt,
+ retainedSampleCount: NonNegativeInt,
+ buckets: Schema.Array(ResourceTelemetryHistoryBucket),
+ topProcesses: Schema.Array(ResourceTelemetryProcessSummary),
+ health: ResourceTelemetryHealth,
+});
+export type ResourceTelemetryHistory = typeof ResourceTelemetryHistory.Type;
+
+export const ResourceTelemetryRetryResult = Schema.Struct({
+ accepted: Schema.Boolean,
+ snapshot: ResourceTelemetrySnapshot,
+});
+export type ResourceTelemetryRetryResult = typeof ResourceTelemetryRetryResult.Type;
diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts
index 43fc2d1ac..0701e15a6 100644
--- a/packages/contracts/src/rpc.ts
+++ b/packages/contracts/src/rpc.ts
@@ -8,6 +8,11 @@ import {
AuthAccessStreamEvent,
EnvironmentAuthorizationError,
} from "./auth.ts";
+import {
+ BackgroundPolicySnapshot,
+ ClientActivityReportInput,
+ HostPowerSnapshot,
+} from "./background.ts";
import {
FilesystemBrowseInput,
FilesystemBrowseResult,
@@ -132,6 +137,12 @@ import {
ServerUpsertKeybindingInput,
ServerUpsertKeybindingResult,
} from "./server.ts";
+import {
+ ResourceTelemetryHistory,
+ ResourceTelemetryHistoryInput,
+ ResourceTelemetryRetryResult,
+ ResourceTelemetrySnapshot,
+} from "./resourceTelemetry.ts";
import { ServerSettings, ServerSettingsError, ServerSettingsPatch } from "./settings.ts";
import {
SourceControlCloneRepositoryInput,
@@ -215,7 +226,12 @@ export const WS_METHODS = {
serverGetTraceDiagnostics: "server.getTraceDiagnostics",
serverGetProcessDiagnostics: "server.getProcessDiagnostics",
serverGetProcessResourceHistory: "server.getProcessResourceHistory",
+ serverGetResourceTelemetryHistory: "server.getResourceTelemetryHistory",
+ serverRetryResourceTelemetry: "server.retryResourceTelemetry",
serverSignalProcess: "server.signalProcess",
+ serverReportClientActivity: "server.reportClientActivity",
+ serverReportHostPowerState: "server.reportHostPowerState",
+ serverGetBackgroundPolicy: "server.getBackgroundPolicy",
// Cloud environment methods
cloudGetRelayClientStatus: "cloud.getRelayClientStatus",
@@ -235,6 +251,8 @@ export const WS_METHODS = {
subscribeServerConfig: "subscribeServerConfig",
subscribeServerLifecycle: "subscribeServerLifecycle",
subscribeAuthAccess: "subscribeAuthAccess",
+ subscribeBackgroundPolicy: "subscribeBackgroundPolicy",
+ subscribeResourceTelemetry: "subscribeResourceTelemetry",
} as const;
export const WsServerUpsertKeybindingRpc = Rpc.make(WS_METHODS.serverUpsertKeybinding, {
@@ -326,6 +344,21 @@ export const WsServerGetProcessResourceHistoryRpc = Rpc.make(
},
);
+export const WsServerGetResourceTelemetryHistoryRpc = Rpc.make(
+ WS_METHODS.serverGetResourceTelemetryHistory,
+ {
+ payload: ResourceTelemetryHistoryInput,
+ success: ResourceTelemetryHistory,
+ error: EnvironmentAuthorizationError,
+ },
+);
+
+export const WsServerRetryResourceTelemetryRpc = Rpc.make(WS_METHODS.serverRetryResourceTelemetry, {
+ payload: Schema.Struct({}),
+ success: ResourceTelemetryRetryResult,
+ error: EnvironmentAuthorizationError,
+});
+
export const WsServerSignalProcessRpc = Rpc.make(WS_METHODS.serverSignalProcess, {
payload: ServerSignalProcessInput,
success: ServerSignalProcessResult,
@@ -345,6 +378,22 @@ export const WsCloudInstallRelayClientRpc = Rpc.make(WS_METHODS.cloudInstallRela
stream: true,
});
+export const WsServerReportClientActivityRpc = Rpc.make(WS_METHODS.serverReportClientActivity, {
+ payload: ClientActivityReportInput,
+ error: EnvironmentAuthorizationError,
+});
+
+export const WsServerReportHostPowerStateRpc = Rpc.make(WS_METHODS.serverReportHostPowerState, {
+ payload: HostPowerSnapshot,
+ error: EnvironmentAuthorizationError,
+});
+
+export const WsServerGetBackgroundPolicyRpc = Rpc.make(WS_METHODS.serverGetBackgroundPolicy, {
+ payload: Schema.Struct({}),
+ success: BackgroundPolicySnapshot,
+ error: EnvironmentAuthorizationError,
+});
+
export const WsSourceControlLookupRepositoryRpc = Rpc.make(
WS_METHODS.sourceControlLookupRepository,
{
@@ -690,6 +739,20 @@ export const WsSubscribeAuthAccessRpc = Rpc.make(WS_METHODS.subscribeAuthAccess,
stream: true,
});
+export const WsSubscribeBackgroundPolicyRpc = Rpc.make(WS_METHODS.subscribeBackgroundPolicy, {
+ payload: Schema.Struct({}),
+ success: BackgroundPolicySnapshot,
+ error: EnvironmentAuthorizationError,
+ stream: true,
+});
+
+export const WsSubscribeResourceTelemetryRpc = Rpc.make(WS_METHODS.subscribeResourceTelemetry, {
+ payload: Schema.Struct({}),
+ success: ResourceTelemetrySnapshot,
+ error: EnvironmentAuthorizationError,
+ stream: true,
+});
+
export const WsRpcGroup = RpcGroup.make(
WsServerProbeRpc,
WsServerGetConfigRpc,
@@ -704,7 +767,12 @@ export const WsRpcGroup = RpcGroup.make(
WsServerGetTraceDiagnosticsRpc,
WsServerGetProcessDiagnosticsRpc,
WsServerGetProcessResourceHistoryRpc,
+ WsServerGetResourceTelemetryHistoryRpc,
+ WsServerRetryResourceTelemetryRpc,
WsServerSignalProcessRpc,
+ WsServerReportClientActivityRpc,
+ WsServerReportHostPowerStateRpc,
+ WsServerGetBackgroundPolicyRpc,
WsCloudGetRelayClientStatusRpc,
WsCloudInstallRelayClientRpc,
WsSourceControlLookupRepositoryRpc,
@@ -754,6 +822,8 @@ export const WsRpcGroup = RpcGroup.make(
WsSubscribeServerConfigRpc,
WsSubscribeServerLifecycleRpc,
WsSubscribeAuthAccessRpc,
+ WsSubscribeBackgroundPolicyRpc,
+ WsSubscribeResourceTelemetryRpc,
WsOrchestrationDispatchCommandRpc,
WsOrchestrationGetTurnDiffRpc,
WsOrchestrationGetFullThreadDiffRpc,
diff --git a/packages/contracts/src/server.ts b/packages/contracts/src/server.ts
index 69699c7a8..8e42c938c 100644
--- a/packages/contracts/src/server.ts
+++ b/packages/contracts/src/server.ts
@@ -303,6 +303,7 @@ export type ServerProcessSignal = typeof ServerProcessSignal.Type;
export const ServerProcessDiagnosticsEntry = Schema.Struct({
pid: PositiveInt,
+ startTimeMs: NonNegativeInt,
ppid: NonNegativeInt,
pgid: Schema.Option(Schema.Int),
status: TrimmedNonEmptyString,
@@ -395,6 +396,7 @@ export type ServerProcessResourceHistoryResult = typeof ServerProcessResourceHis
export const ServerSignalProcessInput = Schema.Struct({
pid: PositiveInt,
+ startTimeMs: NonNegativeInt,
signal: ServerProcessSignal,
});
export type ServerSignalProcessInput = typeof ServerSignalProcessInput.Type;
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index b97d46812..7edda2e52 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -426,15 +426,66 @@ export const SourceControlWritingStyleSettings = Schema.Struct({
export type SourceControlWritingStyleSettings = typeof SourceControlWritingStyleSettings.Type;
export const DEFAULT_AUTOMATIC_GIT_FETCH_INTERVAL = Duration.seconds(30);
+export const DEFAULT_PROVIDER_HEALTH_REFRESH_INTERVAL = Duration.minutes(5);
+
+export const BackgroundActivityProfile = Schema.Literals([
+ "balanced",
+ "performance",
+ "battery-saver",
+]);
+export type BackgroundActivityProfile = typeof BackgroundActivityProfile.Type;
+export const DEFAULT_BACKGROUND_ACTIVITY_PROFILE: BackgroundActivityProfile = "balanced";
+
+export const BackgroundActivityProfileSelection = Schema.Literals([
+ "balanced",
+ "performance",
+ "battery-saver",
+ "custom",
+]);
+export type BackgroundActivityProfileSelection = typeof BackgroundActivityProfileSelection.Type;
+
+export const BackgroundActivityOverrides = Schema.Struct({
+ automaticGitFetchInterval: Schema.optionalKey(Schema.DurationFromMillis),
+ providerHealthRefreshInterval: Schema.optionalKey(Schema.DurationFromMillis),
+ hostPowerMonitorActiveInterval: Schema.optionalKey(Schema.DurationFromMillis),
+ hostPowerMonitorIdleInterval: Schema.optionalKey(Schema.DurationFromMillis),
+ idleClientTtl: Schema.optionalKey(Schema.DurationFromMillis),
+ pauseWhenHostLocked: Schema.optionalKey(Schema.Boolean),
+ pauseWhenHostLowPower: Schema.optionalKey(Schema.Boolean),
+ pauseWhenClientLowPower: Schema.optionalKey(Schema.Boolean),
+ pauseWhenOnBattery: Schema.optionalKey(Schema.Boolean),
+});
+export type BackgroundActivityOverrides = typeof BackgroundActivityOverrides.Type;
+
+export const BackgroundActivitySettings = Schema.Struct({
+ schemaVersion: Schema.Literal(1).pipe(Schema.withDecodingDefault(Effect.succeed(1 as const))),
+ profile: BackgroundActivityProfileSelection.pipe(
+ Schema.withDecodingDefault(Effect.succeed(DEFAULT_BACKGROUND_ACTIVITY_PROFILE)),
+ ),
+ baseProfile: Schema.optionalKey(BackgroundActivityProfile),
+ overrides: BackgroundActivityOverrides.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
+}).pipe(Schema.withDecodingDefault(Effect.succeed({})));
+export type BackgroundActivitySettings = typeof BackgroundActivitySettings.Type;
export const ServerSettings = Schema.Struct({
enableAssistantStreaming: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
enableProviderUpdateChecks: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+ backgroundActivity: BackgroundActivitySettings,
+ // Legacy flat fields retained for old settings files and old clients. New
+ // consumers should resolve `backgroundActivity` instead.
automaticGitFetchInterval: Schema.DurationFromMillis.pipe(
Schema.withDecodingDefault(
Effect.succeed(Duration.toMillis(DEFAULT_AUTOMATIC_GIT_FETCH_INTERVAL)),
),
),
+ providerHealthRefreshInterval: Schema.DurationFromMillis.pipe(
+ Schema.withDecodingDefault(
+ Effect.succeed(Duration.toMillis(DEFAULT_PROVIDER_HEALTH_REFRESH_INTERVAL)),
+ ),
+ ),
+ backgroundActivityProfile: BackgroundActivityProfile.pipe(
+ Schema.withDecodingDefault(Effect.succeed(DEFAULT_BACKGROUND_ACTIVITY_PROFILE)),
+ ),
defaultThreadEnvMode: ThreadEnvMode.pipe(
Schema.withDecodingDefault(Effect.succeed("local" as const satisfies ThreadEnvMode)),
),
@@ -576,7 +627,17 @@ export const ServerSettingsPatch = Schema.Struct({
// Server settings
enableAssistantStreaming: Schema.optionalKey(Schema.Boolean),
enableProviderUpdateChecks: Schema.optionalKey(Schema.Boolean),
+ backgroundActivity: Schema.optionalKey(
+ Schema.Struct({
+ schemaVersion: Schema.optionalKey(Schema.Literal(1)),
+ profile: Schema.optionalKey(BackgroundActivityProfileSelection),
+ baseProfile: Schema.optionalKey(BackgroundActivityProfile),
+ overrides: Schema.optionalKey(BackgroundActivityOverrides),
+ }),
+ ),
automaticGitFetchInterval: Schema.optionalKey(Schema.DurationFromMillis),
+ providerHealthRefreshInterval: Schema.optionalKey(Schema.DurationFromMillis),
+ backgroundActivityProfile: Schema.optionalKey(BackgroundActivityProfile),
defaultThreadEnvMode: Schema.optionalKey(ThreadEnvMode),
newWorktreesStartFromOrigin: Schema.optionalKey(Schema.Boolean),
addProjectBaseDirectory: Schema.optionalKey(TrimmedString),
diff --git a/packages/shared/package.json b/packages/shared/package.json
index 8a45591fd..8cdae3e51 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -79,6 +79,10 @@
"types": "./src/serverSettings.ts",
"import": "./src/serverSettings.ts"
},
+ "./backgroundActivitySettings": {
+ "types": "./src/backgroundActivitySettings.ts",
+ "import": "./src/backgroundActivitySettings.ts"
+ },
"./String": {
"types": "./src/String.ts",
"import": "./src/String.ts"
diff --git a/packages/shared/src/backgroundActivitySettings.ts b/packages/shared/src/backgroundActivitySettings.ts
new file mode 100644
index 000000000..fbba3359c
--- /dev/null
+++ b/packages/shared/src/backgroundActivitySettings.ts
@@ -0,0 +1,270 @@
+import {
+ type BackgroundActivityProfile,
+ type BackgroundActivitySettings,
+ DEFAULT_BACKGROUND_ACTIVITY_PROFILE,
+ DEFAULT_AUTOMATIC_GIT_FETCH_INTERVAL,
+ DEFAULT_PROVIDER_HEALTH_REFRESH_INTERVAL,
+ type ServerSettings,
+} from "@t3tools/contracts";
+import * as Duration from "effect/Duration";
+
+export interface ResolvedBackgroundActivitySettings {
+ readonly profile: BackgroundActivityProfile;
+ readonly automaticGitFetchInterval: Duration.Duration;
+ readonly providerHealthRefreshInterval: Duration.Duration;
+ readonly hostPowerMonitorActiveInterval: Duration.Duration;
+ readonly hostPowerMonitorIdleInterval: Duration.Duration;
+ readonly idleClientTtl: Duration.Duration;
+ readonly pauseWhenHostLocked: boolean;
+ readonly pauseWhenHostLowPower: boolean;
+ readonly pauseWhenClientLowPower: boolean;
+ readonly pauseWhenOnBattery: boolean;
+}
+
+const PRESET_SETTINGS: Record<BackgroundActivityProfile, ResolvedBackgroundActivitySettings> = {
+ performance: {
+ profile: "performance",
+ automaticGitFetchInterval: Duration.seconds(15),
+ providerHealthRefreshInterval: Duration.minutes(1),
+ hostPowerMonitorActiveInterval: Duration.seconds(30),
+ hostPowerMonitorIdleInterval: Duration.minutes(2),
+ idleClientTtl: Duration.seconds(45),
+ pauseWhenHostLocked: true,
+ pauseWhenHostLowPower: false,
+ pauseWhenClientLowPower: false,
+ pauseWhenOnBattery: false,
+ },
+ balanced: {
+ profile: "balanced",
+ automaticGitFetchInterval: DEFAULT_AUTOMATIC_GIT_FETCH_INTERVAL,
+ providerHealthRefreshInterval: DEFAULT_PROVIDER_HEALTH_REFRESH_INTERVAL,
+ hostPowerMonitorActiveInterval: Duration.seconds(30),
+ hostPowerMonitorIdleInterval: Duration.minutes(5),
+ idleClientTtl: Duration.seconds(45),
+ pauseWhenHostLocked: true,
+ pauseWhenHostLowPower: true,
+ pauseWhenClientLowPower: true,
+ pauseWhenOnBattery: false,
+ },
+ "battery-saver": {
+ profile: "battery-saver",
+ automaticGitFetchInterval: Duration.seconds(0),
+ providerHealthRefreshInterval: Duration.minutes(15),
+ hostPowerMonitorActiveInterval: Duration.minutes(1),
+ hostPowerMonitorIdleInterval: Duration.minutes(10),
+ idleClientTtl: Duration.seconds(45),
+ pauseWhenHostLocked: true,
+ pauseWhenHostLowPower: true,
+ pauseWhenClientLowPower: true,
+ pauseWhenOnBattery: true,
+ },
+};
+
+export function getBackgroundActivityPresetSettings(
+ profile: BackgroundActivityProfile,
+): ResolvedBackgroundActivitySettings {
+ return PRESET_SETTINGS[profile];
+}
+
+export function getBackgroundActivityBaseProfile(
+ backgroundActivity: BackgroundActivitySettings,
+): BackgroundActivityProfile {
+ if (backgroundActivity.profile === "custom") {
+ return backgroundActivity.baseProfile ?? DEFAULT_BACKGROUND_ACTIVITY_PROFILE;
+ }
+ return backgroundActivity.profile;
+}
+
+export function resolveBackgroundActivitySettings(
+ backgroundActivity: BackgroundActivitySettings,
+): ResolvedBackgroundActivitySettings {
+ const baseProfile = getBackgroundActivityBaseProfile(backgroundActivity);
+ const preset = PRESET_SETTINGS[baseProfile];
+ const overrides = backgroundActivity.profile === "custom" ? backgroundActivity.overrides : {};
+ return {
+ profile: baseProfile,
+ automaticGitFetchInterval:
+ overrides.automaticGitFetchInterval ?? preset.automaticGitFetchInterval,
+ providerHealthRefreshInterval:
+ overrides.providerHealthRefreshInterval ?? preset.providerHealthRefreshInterval,
+ hostPowerMonitorActiveInterval:
+ overrides.hostPowerMonitorActiveInterval ?? preset.hostPowerMonitorActiveInterval,
+ hostPowerMonitorIdleInterval:
+ overrides.hostPowerMonitorIdleInterval ?? preset.hostPowerMonitorIdleInterval,
+ idleClientTtl: overrides.idleClientTtl ?? preset.idleClientTtl,
+ pauseWhenHostLocked: overrides.pauseWhenHostLocked ?? preset.pauseWhenHostLocked,
+ pauseWhenHostLowPower: overrides.pauseWhenHostLowPower ?? preset.pauseWhenHostLowPower,
+ pauseWhenClientLowPower: overrides.pauseWhenClientLowPower ?? preset.pauseWhenClientLowPower,
+ pauseWhenOnBattery: overrides.pauseWhenOnBattery ?? preset.pauseWhenOnBattery,
+ };
+}
+
+function durationsEqual(a: Duration.Duration, b: Duration.Duration): boolean {
+ return Duration.toMillis(a) === Duration.toMillis(b);
+}
+
+function resolvedSettingsEqual(
+ a: ResolvedBackgroundActivitySettings,
+ b: ResolvedBackgroundActivitySettings,
+): boolean {
+ return (
+ durationsEqual(a.automaticGitFetchInterval, b.automaticGitFetchInterval) &&
+ durationsEqual(a.providerHealthRefreshInterval, b.providerHealthRefreshInterval) &&
+ durationsEqual(a.hostPowerMonitorActiveInterval, b.hostPowerMonitorActiveInterval) &&
+ durationsEqual(a.hostPowerMonitorIdleInterval, b.hostPowerMonitorIdleInterval) &&
+ durationsEqual(a.idleClientTtl, b.idleClientTtl) &&
+ a.pauseWhenHostLocked === b.pauseWhenHostLocked &&
+ a.pauseWhenHostLowPower === b.pauseWhenHostLowPower &&
+ a.pauseWhenClientLowPower === b.pauseWhenClientLowPower &&
+ a.pauseWhenOnBattery === b.pauseWhenOnBattery
+ );
+}
+
+export function normalizeBackgroundActivitySettings(
+ backgroundActivity: BackgroundActivitySettings,
+): BackgroundActivitySettings {
+ if (backgroundActivity.profile !== "custom") {
+ return {
+ schemaVersion: 1,
+ profile: backgroundActivity.profile,
+ overrides: {},
+ };
+ }
+
+ const resolved = resolveBackgroundActivitySettings(backgroundActivity);
+ const profiles: ReadonlyArray<BackgroundActivityProfile> = [
+ getBackgroundActivityBaseProfile(backgroundActivity),
+ "balanced",
+ "performance",
+ "battery-saver",
+ ];
+ for (const profile of profiles) {
+ if (resolvedSettingsEqual(resolved, PRESET_SETTINGS[profile])) {
+ return {
+ schemaVersion: 1,
+ profile,
+ overrides: {},
+ };
+ }
+ }
+
+ const baseProfile = getBackgroundActivityBaseProfile(backgroundActivity);
+ const preset = PRESET_SETTINGS[baseProfile];
+ const overrides: BackgroundActivitySettings["overrides"] = {
+ ...(!durationsEqual(resolved.automaticGitFetchInterval, preset.automaticGitFetchInterval)
+ ? { automaticGitFetchInterval: resolved.automaticGitFetchInterval }
+ : {}),
+ ...(!durationsEqual(
+ resolved.providerHealthRefreshInterval,
+ preset.providerHealthRefreshInterval,
+ )
+ ? { providerHealthRefreshInterval: resolved.providerHealthRefreshInterval }
+ : {}),
+ ...(!durationsEqual(
+ resolved.hostPowerMonitorActiveInterval,
+ preset.hostPowerMonitorActiveInterval,
+ )
+ ? { hostPowerMonitorActiveInterval: resolved.hostPowerMonitorActiveInterval }
+ : {}),
+ ...(!durationsEqual(resolved.hostPowerMonitorIdleInterval, preset.hostPowerMonitorIdleInterval)
+ ? { hostPowerMonitorIdleInterval: resolved.hostPowerMonitorIdleInterval }
+ : {}),
+ ...(!durationsEqual(resolved.idleClientTtl, preset.idleClientTtl)
+ ? { idleClientTtl: resolved.idleClientTtl }
+ : {}),
+ ...(resolved.pauseWhenHostLocked !== preset.pauseWhenHostLocked
+ ? { pauseWhenHostLocked: resolved.pauseWhenHostLocked }
+ : {}),
+ ...(resolved.pauseWhenHostLowPower !== preset.pauseWhenHostLowPower
+ ? { pauseWhenHostLowPower: resolved.pauseWhenHostLowPower }
+ : {}),
+ ...(resolved.pauseWhenClientLowPower !== preset.pauseWhenClientLowPower
+ ? { pauseWhenClientLowPower: resolved.pauseWhenClientLowPower }
+ : {}),
+ ...(resolved.pauseWhenOnBattery !== preset.pauseWhenOnBattery
+ ? { pauseWhenOnBattery: resolved.pauseWhenOnBattery }
+ : {}),
+ };
+
+ return {
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile,
+ overrides,
+ };
+}
+
+export function resolveServerBackgroundActivitySettings(
+ settings: ServerSettings,
+): ResolvedBackgroundActivitySettings {
+ const defaultBackgroundActivity: BackgroundActivitySettings = {
+ schemaVersion: 1,
+ profile: DEFAULT_BACKGROUND_ACTIVITY_PROFILE,
+ overrides: {},
+ };
+ const backgroundActivityIsDefault =
+ settings.backgroundActivity.profile === defaultBackgroundActivity.profile &&
+ settings.backgroundActivity.baseProfile === undefined &&
+ Object.keys(settings.backgroundActivity.overrides).length === 0;
+ const legacyProfile = settings.backgroundActivityProfile;
+ const hasLegacyOverrides =
+ legacyProfile !== DEFAULT_BACKGROUND_ACTIVITY_PROFILE ||
+ Duration.toMillis(settings.automaticGitFetchInterval) !==
+ Duration.toMillis(DEFAULT_AUTOMATIC_GIT_FETCH_INTERVAL) ||
+ Duration.toMillis(settings.providerHealthRefreshInterval) !==
+ Duration.toMillis(DEFAULT_PROVIDER_HEALTH_REFRESH_INTERVAL);
+ if (backgroundActivityIsDefault && hasLegacyOverrides) {
+ return resolveBackgroundActivitySettings({
+ schemaVersion: 1,
+ profile:
+ Duration.toMillis(settings.automaticGitFetchInterval) ===
+ Duration.toMillis(
+ getBackgroundActivityPresetSettings(legacyProfile).automaticGitFetchInterval,
+ ) &&
+ Duration.toMillis(settings.providerHealthRefreshInterval) ===
+ Duration.toMillis(
+ getBackgroundActivityPresetSettings(legacyProfile).providerHealthRefreshInterval,
+ )
+ ? legacyProfile
+ : "custom",
+ baseProfile: legacyProfile,
+ overrides: {
+ ...(Duration.toMillis(settings.automaticGitFetchInterval) !==
+ Duration.toMillis(
+ getBackgroundActivityPresetSettings(legacyProfile).automaticGitFetchInterval,
+ )
+ ? { automaticGitFetchInterval: settings.automaticGitFetchInterval }
+ : {}),
+ ...(Duration.toMillis(settings.providerHealthRefreshInterval) !==
+ Duration.toMillis(
+ getBackgroundActivityPresetSettings(legacyProfile).providerHealthRefreshInterval,
+ )
+ ? { providerHealthRefreshInterval: settings.providerHealthRefreshInterval }
+ : {}),
+ },
+ });
+ }
+ return resolveBackgroundActivitySettings(settings.backgroundActivity);
+}
+
+export function normalizeServerBackgroundActivitySettings(
+ settings: ServerSettings,
+): BackgroundActivitySettings {
+ const resolved = resolveServerBackgroundActivitySettings(settings);
+ return normalizeBackgroundActivitySettings({
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: resolved.profile,
+ overrides: {
+ automaticGitFetchInterval: resolved.automaticGitFetchInterval,
+ providerHealthRefreshInterval: resolved.providerHealthRefreshInterval,
+ hostPowerMonitorActiveInterval: resolved.hostPowerMonitorActiveInterval,
+ hostPowerMonitorIdleInterval: resolved.hostPowerMonitorIdleInterval,
+ idleClientTtl: resolved.idleClientTtl,
+ pauseWhenHostLocked: resolved.pauseWhenHostLocked,
+ pauseWhenHostLowPower: resolved.pauseWhenHostLowPower,
+ pauseWhenClientLowPower: resolved.pauseWhenClientLowPower,
+ pauseWhenOnBattery: resolved.pauseWhenOnBattery,
+ },
+ });
+}
diff --git a/packages/shared/src/logging.test.ts b/packages/shared/src/logging.test.ts
index 0e1ea2738..4b19bd291 100644
--- a/packages/shared/src/logging.test.ts
+++ b/packages/shared/src/logging.test.ts
@@ -127,6 +127,25 @@ describe("RotatingFileSink", () => {
expect((thrown as RotatingFileSinkError).cause).toBeInstanceOf(Error);
});
+ it("never reports a rotation failure after successfully appending a chunk", () => {
+ const directory = makeTempDirectory();
+ const filePath = NodePath.join(directory, "log.ndjson");
+ NodeFS.mkdirSync(`${filePath}.1`);
+ const sink = new RotatingFileSink({
+ filePath,
+ maxBytes: 1,
+ maxFiles: 1,
+ throwOnError: true,
+ });
+
+ sink.write("oversized");
+
+ expect(NodeFS.readFileSync(filePath, "utf8")).toBe("oversized");
+ const thrown = captureError(() => sink.write("next"));
+ expect(thrown).toMatchObject({ operation: "rotate", filePath });
+ expect(NodeFS.readFileSync(filePath, "utf8")).toBe("oversized");
+ });
+
it("preserves backup pruning failures", () => {
const directory = makeTempDirectory();
const filePath = NodePath.join(directory, "log.ndjson");
diff --git a/packages/shared/src/logging.ts b/packages/shared/src/logging.ts
index 4aa9c7843..ac3d56e28 100644
--- a/packages/shared/src/logging.ts
+++ b/packages/shared/src/logging.ts
@@ -93,10 +93,6 @@ export class RotatingFileSink {
NodeFS.appendFileSync(this.filePath, buffer);
this.currentSize += buffer.length;
-
- if (this.currentSize > this.maxBytes) {
- this.rotate();
- }
} catch (cause) {
if (isRotatingFileSinkError(cause)) {
throw cause;
diff --git a/packages/shared/src/observability.test.ts b/packages/shared/src/observability.test.ts
index f9cf1b1cb..4bd1070bf 100644
--- a/packages/shared/src/observability.test.ts
+++ b/packages/shared/src/observability.test.ts
@@ -8,6 +8,7 @@ import * as Layer from "effect/Layer";
import * as Logger from "effect/Logger";
import * as Order from "effect/Order";
import * as Path from "effect/Path";
+import * as Ref from "effect/Ref";
import * as References from "effect/References";
import * as Schema from "effect/Schema";
import * as Tracer from "effect/Tracer";
@@ -19,6 +20,7 @@ import {
makeLocalFileTracer,
makeTraceSink,
type TraceRecord,
+ type TraceSinkFlushStats,
} from "./observability.ts";
describe("errorTag", () => {
@@ -176,6 +178,34 @@ describe("observability", () => {
),
);
+ it.effect("reports successful logical trace writes", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const tempDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-trace-sink-" });
+ const tracePath = path.join(tempDir, "shared.trace.ndjson");
+ const reported = yield* Ref.make<ReadonlyArray<TraceSinkFlushStats>>([]);
+
+ const sink = yield* makeTraceSink({
+ filePath: tracePath,
+ maxBytes: 1024,
+ maxFiles: 2,
+ batchWindowMs: 10_000,
+ onFlush: (stats) => Ref.update(reported, (current) => [...current, stats]),
+ });
+
+ sink.push(makeRecord("attributed"));
+ yield* sink.flush;
+
+ const stats = yield* Ref.get(reported);
+ assert.equal(stats.length, 1);
+ assert.equal(stats[0]?.count, 1);
+ assert.isAbove(stats[0]?.logicalWriteBytes ?? 0, 0);
+ }),
+ ),
+ );
+
it.effect("rotates the trace file when the configured max size is exceeded", () =>
Effect.scoped(
Effect.gen(function* () {
@@ -186,7 +216,7 @@ describe("observability", () => {
const sink = yield* makeTraceSink({
filePath: tracePath,
- maxBytes: 180,
+ maxBytes: 500,
maxFiles: 2,
batchWindowMs: 10_000,
});
@@ -217,6 +247,70 @@ describe("observability", () => {
),
);
+ it.effect("keeps every trace file within the configured limit for threshold flushes", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const tempDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-trace-sink-" });
+ const tracePath = path.join(tempDir, "shared.trace.ndjson");
+ const maxBytes = 1_024;
+
+ const sink = yield* makeTraceSink({
+ filePath: tracePath,
+ maxBytes,
+ maxFiles: 2,
+ batchWindowMs: 10_000,
+ });
+
+ for (let index = 0; index < 256; index += 1) {
+ sink.push(makeRecord("threshold", `${index}-${"x".repeat(48)}`));
+ }
+ yield* sink.close();
+
+ const matchingFiles = (yield* fileSystem.readDirectory(tempDir)).filter(
+ (entry) => entry === "shared.trace.ndjson" || entry.startsWith("shared.trace.ndjson."),
+ );
+ assert.include(matchingFiles, "shared.trace.ndjson.1");
+ for (const entry of matchingFiles) {
+ const stat = yield* fileSystem.stat(path.join(tempDir, entry));
+ assert.isAtMost(Number(stat.size), maxBytes, entry);
+ }
+ }),
+ ),
+ );
+
+ it.effect("drops a single trace record that cannot fit within the configured limit", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const tempDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-trace-sink-" });
+ const tracePath = path.join(tempDir, "shared.trace.ndjson");
+ const maxBytes = 1_024;
+
+ const sink = yield* makeTraceSink({
+ filePath: tracePath,
+ maxBytes,
+ maxFiles: 2,
+ batchWindowMs: 10_000,
+ });
+
+ sink.push(makeRecord("oversized", "x".repeat(maxBytes * 2)));
+ sink.push(makeRecord("retained"));
+ yield* sink.close();
+
+ const records = yield* readTraceRecords(tracePath);
+ const stat = yield* fileSystem.stat(tracePath);
+ assert.deepEqual(
+ records.map((record) => record.name),
+ ["retained"],
+ );
+ assert.isAtMost(Number(stat.size), maxBytes);
+ }),
+ ),
+ );
+
it.effect("drops only the invalid trace record when serialization fails", () =>
Effect.scoped(
Effect.gen(function* () {
diff --git a/packages/shared/src/observability.ts b/packages/shared/src/observability.ts
index 1b92b9873..e0a759586 100644
--- a/packages/shared/src/observability.ts
+++ b/packages/shared/src/observability.ts
@@ -8,7 +8,8 @@ import { OtlpResource, OtlpTracer } from "effect/unstable/observability";
import { RotatingFileSink } from "./logging.ts";
-const FLUSH_BUFFER_THRESHOLD = 32;
+const FLUSH_BUFFER_THRESHOLD = 256;
+const textEncoder = new TextEncoder();
export type TraceAttributes = Readonly<Record<string, unknown>>;
@@ -109,6 +110,13 @@ export interface TraceSinkOptions {
readonly maxBytes: number;
readonly maxFiles: number;
readonly batchWindowMs: number;
+ readonly onFlush?: (stats: TraceSinkFlushStats) => Effect.Effect<void>;
+}
+
+export interface TraceSinkFlushStats {
+ readonly logicalWriteBytes: number;
+ readonly count: number;
+ readonly durationMs: number;
}
export interface TraceSink {
@@ -275,26 +283,73 @@ export const makeTraceSink = Effect.fn("makeTraceSink")(function* (options: Trac
filePath: options.filePath,
maxBytes: options.maxBytes,
maxFiles: options.maxFiles,
+ throwOnError: true,
});
let buffer: Array<string> = [];
+ let pendingFlushStats: TraceSinkFlushStats = {
+ logicalWriteBytes: 0,
+ count: 0,
+ durationMs: 0,
+ };
const flushUnsafe = () => {
if (buffer.length === 0) {
return;
}
- const chunk = buffer.join("");
+ const records = buffer;
buffer = [];
+ let persistedCount = 0;
+
+ while (persistedCount < records.length) {
+ const firstRecordBytes = textEncoder.encode(records[persistedCount]).byteLength;
+ if (firstRecordBytes > options.maxBytes) {
+ persistedCount += 1;
+ continue;
+ }
+
+ let nextIndex = persistedCount + 1;
+ let chunkBytes = firstRecordBytes;
+ while (nextIndex < records.length) {
+ const nextRecordBytes = textEncoder.encode(records[nextIndex]).byteLength;
+ if (chunkBytes + nextRecordBytes > options.maxBytes) break;
+ chunkBytes += nextRecordBytes;
+ nextIndex += 1;
+ }
- try {
- sink.write(chunk);
- } catch {
- buffer.unshift(chunk);
+ const chunk = records.slice(persistedCount, nextIndex).join("");
+ const startedAt = performance.now();
+ try {
+ sink.write(chunk);
+ } catch {
+ buffer.unshift(...records.slice(persistedCount));
+ return;
+ }
+ pendingFlushStats = {
+ logicalWriteBytes: pendingFlushStats.logicalWriteBytes + chunkBytes,
+ count: pendingFlushStats.count + nextIndex - persistedCount,
+ durationMs: pendingFlushStats.durationMs + Math.max(0, performance.now() - startedAt),
+ };
+ persistedCount = nextIndex;
}
};
- const flush = Effect.sync(flushUnsafe).pipe(Effect.withTracerEnabled(false));
+ const flush = Effect.sync(() => {
+ flushUnsafe();
+ const stats = pendingFlushStats;
+ pendingFlushStats = {
+ logicalWriteBytes: 0,
+ count: 0,
+ durationMs: 0,
+ };
+ return stats;
+ }).pipe(
+ Effect.flatMap((stats) =>
+ stats.count > 0 && options.onFlush ? options.onFlush(stats).pipe(Effect.ignore) : Effect.void,
+ ),
+ Effect.withTracerEnabled(false),
+ );
yield* Effect.addFinalizer(() => flush.pipe(Effect.ignore));
yield* Effect.forkScoped(
@@ -399,6 +454,7 @@ export const makeLocalFileTracer = Effect.fn("makeLocalFileTracer")(function* (
maxBytes: options.maxBytes,
maxFiles: options.maxFiles,
batchWindowMs: options.batchWindowMs,
+ ...(options.onFlush ? { onFlush: options.onFlush } : {}),
}));
const delegate =
diff --git a/packages/shared/src/serverSettings.test.ts b/packages/shared/src/serverSettings.test.ts
index 2352c6e29..baa84a4e1 100644
--- a/packages/shared/src/serverSettings.test.ts
+++ b/packages/shared/src/serverSettings.test.ts
@@ -4,7 +4,9 @@ import {
ProviderInstanceId,
type ServerProvider,
} from "@t3tools/contracts";
+import * as Duration from "effect/Duration";
import { describe, expect, it } from "vite-plus/test";
+import { resolveServerBackgroundActivitySettings } from "./backgroundActivitySettings.ts";
import { createModelSelection } from "./model.ts";
import {
applyServerSettingsPatch,
@@ -295,4 +297,219 @@ describe("serverSettings helpers", () => {
config: { homePath: "~/.codex" },
});
});
+
+ it("stores background activity profiles as a versioned object and syncs legacy aliases", () => {
+ const next = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
+ backgroundActivity: {
+ schemaVersion: 1,
+ profile: "battery-saver",
+ overrides: {},
+ },
+ });
+
+ expect(next.backgroundActivity).toEqual({
+ schemaVersion: 1,
+ profile: "battery-saver",
+ overrides: {},
+ });
+ expect(next.backgroundActivityProfile).toBe("battery-saver");
+ expect(Duration.toMillis(next.automaticGitFetchInterval)).toBe(0);
+ expect(Duration.toMillis(next.providerHealthRefreshInterval)).toBe(
+ Duration.toMillis(Duration.minutes(15)),
+ );
+ });
+
+ it("turns legacy interval patches into custom background activity overrides", () => {
+ const next = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
+ automaticGitFetchInterval: Duration.seconds(15),
+ });
+
+ expect(next.backgroundActivity).toEqual({
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "balanced",
+ overrides: {
+ automaticGitFetchInterval: Duration.seconds(15),
+ },
+ });
+ expect(resolveServerBackgroundActivitySettings(next).profile).toBe("balanced");
+ expect(
+ Duration.toMillis(resolveServerBackgroundActivitySettings(next).automaticGitFetchInterval),
+ ).toBe(15_000);
+ });
+
+ it("preserves legacy background activity settings when applying an unrelated patch", () => {
+ const current = {
+ ...DEFAULT_SERVER_SETTINGS,
+ backgroundActivityProfile: "performance" as const,
+ automaticGitFetchInterval: Duration.seconds(7),
+ providerHealthRefreshInterval: Duration.minutes(4),
+ };
+
+ const next = applyServerSettingsPatch(current, {
+ sourceControlWriterModelSelection: createModelSelection(
+ ProviderInstanceId.make("codex"),
+ "gpt-5.4-mini",
+ ),
+ });
+
+ expect(next.backgroundActivity).toEqual({
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "performance",
+ overrides: {
+ automaticGitFetchInterval: Duration.seconds(7),
+ providerHealthRefreshInterval: Duration.minutes(4),
+ },
+ });
+ expect(next.backgroundActivityProfile).toBe("performance");
+ expect(Duration.toMillis(next.automaticGitFetchInterval)).toBe(7_000);
+ expect(Duration.toMillis(next.providerHealthRefreshInterval)).toBe(240_000);
+ });
+
+ it("does not reactivate dormant overrides from a concrete profile", () => {
+ const current = {
+ ...DEFAULT_SERVER_SETTINGS,
+ backgroundActivity: {
+ schemaVersion: 1 as const,
+ profile: "battery-saver" as const,
+ overrides: {
+ providerHealthRefreshInterval: Duration.seconds(5),
+ },
+ },
+ };
+
+ const next = applyServerSettingsPatch(current, {
+ automaticGitFetchInterval: Duration.seconds(15),
+ });
+
+ expect(next.backgroundActivity).toEqual({
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "battery-saver",
+ overrides: {
+ automaticGitFetchInterval: Duration.seconds(15),
+ },
+ });
+ });
+
+ it("prefers structured background activity settings over legacy aliases", () => {
+ const next = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
+ backgroundActivity: {
+ schemaVersion: 1,
+ profile: "battery-saver",
+ overrides: {},
+ },
+ automaticGitFetchInterval: Duration.seconds(5),
+ backgroundActivityProfile: "performance",
+ });
+
+ expect(next.backgroundActivity).toEqual({
+ schemaVersion: 1,
+ profile: "battery-saver",
+ overrides: {},
+ });
+ expect(next.backgroundActivityProfile).toBe("battery-saver");
+ expect(Duration.toMillis(next.automaticGitFetchInterval)).toBe(0);
+ });
+
+ it("reconciles custom background activity back to a preset when overrides match the preset", () => {
+ const custom = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
+ automaticGitFetchInterval: Duration.seconds(15),
+ });
+ const next = applyServerSettingsPatch(custom, {
+ automaticGitFetchInterval: Duration.seconds(30),
+ });
+
+ expect(next.backgroundActivity).toEqual({
+ schemaVersion: 1,
+ profile: "balanced",
+ overrides: {},
+ });
+ expect(next.backgroundActivityProfile).toBe("balanced");
+ expect(Duration.toMillis(next.automaticGitFetchInterval)).toBe(30_000);
+ });
+
+ it("drops custom overrides that duplicate the base profile", () => {
+ const next = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
+ backgroundActivity: {
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "balanced",
+ overrides: {
+ automaticGitFetchInterval: Duration.seconds(30),
+ },
+ },
+ });
+
+ expect(next.backgroundActivity).toEqual({
+ schemaVersion: 1,
+ profile: "balanced",
+ overrides: {},
+ });
+ });
+
+ it("replaces the complete background override record", () => {
+ const current = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
+ backgroundActivity: {
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "balanced",
+ overrides: {
+ automaticGitFetchInterval: Duration.seconds(15),
+ providerHealthRefreshInterval: Duration.minutes(3),
+ },
+ },
+ });
+
+ const next = applyServerSettingsPatch(current, {
+ backgroundActivity: {
+ overrides: {
+ automaticGitFetchInterval: Duration.seconds(10),
+ },
+ },
+ });
+
+ expect(next.backgroundActivity).toEqual({
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "balanced",
+ overrides: {
+ automaticGitFetchInterval: Duration.seconds(10),
+ },
+ });
+ });
+
+ it("keeps interval overrides supplied with a profile patch", () => {
+ const next = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
+ backgroundActivityProfile: "performance",
+ automaticGitFetchInterval: Duration.seconds(0),
+ providerHealthRefreshInterval: Duration.minutes(4),
+ });
+
+ expect(next.backgroundActivity).toEqual({
+ schemaVersion: 1,
+ profile: "custom",
+ baseProfile: "performance",
+ overrides: {
+ automaticGitFetchInterval: Duration.seconds(0),
+ providerHealthRefreshInterval: Duration.minutes(4),
+ },
+ });
+ });
+
+ it("ignores overrides attached to a concrete background profile", () => {
+ const resolved = resolveServerBackgroundActivitySettings({
+ ...DEFAULT_SERVER_SETTINGS,
+ backgroundActivity: {
+ schemaVersion: 1,
+ profile: "balanced",
+ overrides: {
+ pauseWhenOnBattery: true,
+ },
+ },
+ });
+
+ expect(resolved.pauseWhenOnBattery).toBe(false);
+ });
});
diff --git a/packages/shared/src/serverSettings.ts b/packages/shared/src/serverSettings.ts
index e0e53648a..21d819a1c 100644
--- a/packages/shared/src/serverSettings.ts
+++ b/packages/shared/src/serverSettings.ts
@@ -12,6 +12,12 @@ import * as Schema from "effect/Schema";
import { deepMerge } from "./Struct.ts";
import { fromLenientJson } from "./schemaJson.ts";
import { createModelSelection } from "./model.ts";
+import {
+ getBackgroundActivityBaseProfile,
+ normalizeBackgroundActivitySettings,
+ normalizeServerBackgroundActivitySettings,
+ resolveBackgroundActivitySettings,
+} from "./backgroundActivitySettings.ts";
const ServerSettingsJson = fromLenientJson(ServerSettings);
const decodeServerSettingsJson = Schema.decodeUnknownOption(ServerSettingsJson);
@@ -120,10 +126,64 @@ export function applyServerSettingsPatch(
patch: ServerSettingsPatch,
): ServerSettings {
const selectionPatch = patch.textGenerationModelSelection;
- const { automaticGitFetchInterval, ...patchForMerge } = patch;
+ const {
+ automaticGitFetchInterval,
+ providerHealthRefreshInterval,
+ backgroundActivityProfile,
+ backgroundActivity,
+ ...patchForMerge
+ } = patch;
+ const currentBackgroundActivity = normalizeServerBackgroundActivitySettings(current);
+ const backgroundActivityPatch =
+ backgroundActivityProfile !== undefined
+ ? {
+ schemaVersion: 1 as const,
+ profile:
+ automaticGitFetchInterval !== undefined || providerHealthRefreshInterval !== undefined
+ ? ("custom" as const)
+ : backgroundActivityProfile,
+ ...(automaticGitFetchInterval !== undefined || providerHealthRefreshInterval !== undefined
+ ? { baseProfile: backgroundActivityProfile }
+ : {}),
+ overrides: {
+ ...(automaticGitFetchInterval !== undefined ? { automaticGitFetchInterval } : {}),
+ ...(providerHealthRefreshInterval !== undefined
+ ? { providerHealthRefreshInterval }
+ : {}),
+ },
+ }
+ : automaticGitFetchInterval !== undefined || providerHealthRefreshInterval !== undefined
+ ? {
+ schemaVersion: 1 as const,
+ profile: "custom" as const,
+ baseProfile: getBackgroundActivityBaseProfile(currentBackgroundActivity),
+ overrides: {
+ ...(currentBackgroundActivity.profile === "custom"
+ ? currentBackgroundActivity.overrides
+ : {}),
+ ...(automaticGitFetchInterval !== undefined ? { automaticGitFetchInterval } : {}),
+ ...(providerHealthRefreshInterval !== undefined
+ ? { providerHealthRefreshInterval }
+ : {}),
+ },
+ }
+ : undefined;
const next = deepMerge(current, patchForMerge);
- const nextWithReplacements = {
+ const nextWithReplacementsBase = {
...next,
+ ...(backgroundActivity !== undefined
+ ? {
+ backgroundActivity: {
+ ...deepMerge(currentBackgroundActivity, backgroundActivity),
+ ...(backgroundActivity.overrides !== undefined
+ ? { overrides: backgroundActivity.overrides }
+ : {}),
+ },
+ }
+ : { backgroundActivity: currentBackgroundActivity }),
+ ...(backgroundActivity === undefined && backgroundActivityPatch !== undefined
+ ? { backgroundActivity: backgroundActivityPatch }
+ : {}),
...(patch.providerInstances !== undefined
? { providerInstances: patch.providerInstances }
: {}),
@@ -131,6 +191,20 @@ export function applyServerSettingsPatch(
? { sourceControlWriterModelSelection: patch.sourceControlWriterModelSelection }
: {}),
...(automaticGitFetchInterval !== undefined ? { automaticGitFetchInterval } : {}),
+ ...(providerHealthRefreshInterval !== undefined ? { providerHealthRefreshInterval } : {}),
+ };
+ const normalizedBackgroundActivity = normalizeBackgroundActivitySettings(
+ nextWithReplacementsBase.backgroundActivity,
+ );
+ const resolvedBackgroundActivity = resolveBackgroundActivitySettings(
+ normalizedBackgroundActivity,
+ );
+ const nextWithReplacements = {
+ ...nextWithReplacementsBase,
+ backgroundActivity: normalizedBackgroundActivity,
+ automaticGitFetchInterval: resolvedBackgroundActivity.automaticGitFetchInterval,
+ providerHealthRefreshInterval: resolvedBackgroundActivity.providerHealthRefreshInterval,
+ backgroundActivityProfile: resolvedBackgroundActivity.profile,
};
if (!selectionPatch) {
return nextWithReplacements;
diff --git a/scripts/build-desktop-artifact.test.ts b/scripts/build-desktop-artifact.test.ts
index 53c5dc4fa..64bb6c061 100644
--- a/scripts/build-desktop-artifact.test.ts
+++ b/scripts/build-desktop-artifact.test.ts
@@ -15,9 +15,11 @@ import {
createBuildConfig,
DESKTOP_ELECTRON_LANGUAGES,
DESKTOP_FILE_EXCLUSIONS,
+ DESKTOP_EXTRA_RESOURCES,
InvalidMacPasskeyRpDomainError,
InvalidMacPasskeyPublishableKeyError,
InvalidMockUpdateServerPortError,
+ UnsupportedDesktopBuildArchitectureError,
isMacPasskeySigningConfigurationError,
LinuxIconResizeError,
MacPasskeySigningConfigurationResolutionError,
@@ -32,6 +34,8 @@ import {
resolveDesktopProductName,
resolveDesktopUpdateChannel,
resolveDesktopWebAssetBrand,
+ resolveResourceMonitorRustTargets,
+ resourceMonitorExecutableName,
resolveGitHubPublishConfig,
resolveMockUpdateServerPort,
resolveMockUpdateServerUrl,
@@ -543,6 +547,26 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
}).pipe(Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env: {} })))),
);
+ it("stages the resource monitor as an external executable resource", () => {
+ assert.deepStrictEqual(DESKTOP_EXTRA_RESOURCES, [
+ {
+ from: "apps/desktop/prod-resources/resource-monitor",
+ to: "resource-monitor",
+ },
+ ]);
+ assert.deepStrictEqual(resolveResourceMonitorRustTargets("mac", "universal"), [
+ "aarch64-apple-darwin",
+ "x86_64-apple-darwin",
+ ]);
+ assert.deepStrictEqual(resolveResourceMonitorRustTargets("linux", "x64"), [
+ "x86_64-unknown-linux-gnu",
+ ]);
+ assert.deepStrictEqual(resolveResourceMonitorRustTargets("win", "arm64"), [
+ "aarch64-pc-windows-msvc",
+ ]);
+ assert.equal(resourceMonitorExecutableName("mac"), "t3-resource-monitor");
+ assert.equal(resourceMonitorExecutableName("win"), "t3-resource-monitor.exe");
+ });
it("promotes target fff binaries to direct staged dependencies", () => {
assert.deepStrictEqual(resolveFffNativeDependencies("mac", "arm64", "0.9.4"), {
"@ff-labs/fff-bin-darwin-arm64": "0.9.4",
@@ -673,6 +697,32 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
}),
);
+ it.effect("rejects universal builds on Linux and Windows before staging binaries", () =>
+ Effect.gen(function* () {
+ for (const platform of ["linux", "win"] as const) {
+ const error = yield* Effect.flip(
+ resolveBuildOptions({
+ platform: Option.some(platform),
+ target: Option.none(),
+ arch: Option.some("universal"),
+ buildVersion: Option.none(),
+ outputDir: Option.none(),
+ skipBuild: Option.none(),
+ keepStage: Option.none(),
+ signed: Option.none(),
+ verbose: Option.none(),
+ mockUpdates: Option.none(),
+ mockUpdateServerPort: Option.none(),
+ wslPrebuild: Option.none(),
+ }),
+ );
+
+ assert.instanceOf(error, UnsupportedDesktopBuildArchitectureError);
+ assert.deepStrictEqual(error.supportedArchitectures, ["x64", "arm64"]);
+ }
+ }),
+ );
+
it.effect("preserves explicit false boolean flags over true env defaults", () =>
Effect.gen(function* () {
const resolved = yield* resolveBuildOptions({
diff --git a/scripts/build-desktop-artifact.ts b/scripts/build-desktop-artifact.ts
index 0a0287507..9687e76a1 100644
--- a/scripts/build-desktop-artifact.ts
+++ b/scripts/build-desktop-artifact.ts
@@ -94,6 +94,26 @@ interface PlatformConfig {
readonly archChoices: ReadonlyArray<typeof BuildArch.Type>;
}
+export function resolveResourceMonitorRustTargets(
+ platform: typeof BuildPlatform.Type,
+ arch: typeof BuildArch.Type,
+): ReadonlyArray<string> {
+ if (platform === "mac") {
+ if (arch === "universal") {
+ return ["aarch64-apple-darwin", "x86_64-apple-darwin"];
+ }
+ return [arch === "arm64" ? "aarch64-apple-darwin" : "x86_64-apple-darwin"];
+ }
+ if (platform === "linux") {
+ return [arch === "arm64" ? "aarch64-unknown-linux-gnu" : "x86_64-unknown-linux-gnu"];
+ }
+ return [arch === "arm64" ? "aarch64-pc-windows-msvc" : "x86_64-pc-windows-msvc"];
+}
+
+export function resourceMonitorExecutableName(platform: typeof BuildPlatform.Type): string {
+ return platform === "win" ? "t3-resource-monitor.exe" : "t3-resource-monitor";
+}
+
const PLATFORM_CONFIG: Record<typeof BuildPlatform.Type, PlatformConfig> = {
mac: {
cliFlag: "--mac",
@@ -189,6 +209,19 @@ export class UnsupportedHostBuildPlatformError extends Schema.TaggedErrorClass<U
}
}
+export class UnsupportedDesktopBuildArchitectureError extends Schema.TaggedErrorClass<UnsupportedDesktopBuildArchitectureError>()(
+ "UnsupportedDesktopBuildArchitectureError",
+ {
+ platform: BuildPlatform,
+ arch: BuildArch,
+ supportedArchitectures: Schema.Array(BuildArch),
+ },
+) {
+ override get message(): string {
+ return `Unsupported architecture '${this.arch}' for ${this.platform}.`;
+ }
+}
+
const InvalidMockUpdateServerPortReason = Schema.Literals([
"not-numeric",
"not-integer",
@@ -236,6 +269,20 @@ export class BuildCommandFailedError extends Schema.TaggedErrorClass<BuildComman
}
}
+export class ResourceMonitorBuildOutputMissingError extends Schema.TaggedErrorClass<ResourceMonitorBuildOutputMissingError>()(
+ "ResourceMonitorBuildOutputMissingError",
+ {
+ binaryPath: Schema.String,
+ rustTarget: Schema.String,
+ platform: BuildPlatform,
+ arch: BuildArch,
+ },
+) {
+ override get message(): string {
+ return `Resource monitor build for ${this.rustTarget} did not produce ${this.binaryPath}.`;
+ }
+}
+
const desktopIconPlatformNames = {
mac: "macOS",
linux: "Linux",
@@ -593,6 +640,12 @@ export const DESKTOP_FILE_EXCLUSIONS = [
// The Windows primary backend reads the same files through the asar redirect,
// so nothing is duplicated.
export const WINDOWS_ASAR_UNPACK = ["apps/server/dist/**", "**/node_modules/**"] as const;
+export const DESKTOP_EXTRA_RESOURCES = [
+ {
+ from: "apps/desktop/prod-resources/resource-monitor",
+ to: "resource-monitor",
+ },
+] as const;
export interface MacPasskeySigningConfiguration {
readonly appId: string;
@@ -1044,6 +1097,14 @@ export const resolveBuildOptions = Effect.fn("resolveBuildOptions")(function* (
const target = mergeOptions(input.target, env.target, PLATFORM_CONFIG[platform].defaultTarget);
const defaultArch = yield* getDefaultArch(platform);
const arch = mergeOptions(input.arch, env.arch, defaultArch);
+ const supportedArchitectures = PLATFORM_CONFIG[platform].archChoices;
+ if (!supportedArchitectures.includes(arch)) {
+ return yield* new UnsupportedDesktopBuildArchitectureError({
+ platform,
+ arch,
+ supportedArchitectures: [...supportedArchitectures],
+ });
+ }
const version = mergeOptions(input.buildVersion, env.version, undefined);
const releaseDir = resolveBooleanFlag(input.mockUpdates, env.mockUpdates)
? "release-mock"
@@ -1117,6 +1178,81 @@ const runCommand = Effect.fn("runCommand")(function* (
}
});
+const stageResourceMonitor = Effect.fn("stageResourceMonitor")(function* (input: {
+ readonly repoRoot: string;
+ readonly stageResourcesDir: string;
+ readonly platform: typeof BuildPlatform.Type;
+ readonly arch: typeof BuildArch.Type;
+ readonly verbose: boolean;
+}) {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const manifestPath = path.join(input.repoRoot, "native/resource-monitor/Cargo.toml");
+ const executableName = resourceMonitorExecutableName(input.platform);
+ const rustTargets = resolveResourceMonitorRustTargets(input.platform, input.arch);
+ const builtBinaries: string[] = [];
+
+ for (const rustTarget of rustTargets) {
+ const spawnCommand = yield* resolveSpawnCommand("cargo", [
+ "build",
+ "--locked",
+ "--release",
+ "--manifest-path",
+ manifestPath,
+ "--target",
+ rustTarget,
+ ]);
+ yield* runCommand(
+ ChildProcess.make(spawnCommand.command, spawnCommand.args, {
+ cwd: input.repoRoot,
+ shell: spawnCommand.shell,
+ }),
+ {
+ label: `cargo build resource monitor (${rustTarget})`,
+ verbose: input.verbose,
+ },
+ );
+
+ const binaryPath = path.join(
+ input.repoRoot,
+ "native/resource-monitor/target",
+ rustTarget,
+ "release",
+ executableName,
+ );
+ if (!(yield* fs.exists(binaryPath))) {
+ return yield* new ResourceMonitorBuildOutputMissingError({
+ binaryPath,
+ rustTarget,
+ platform: input.platform,
+ arch: input.arch,
+ });
+ }
+ builtBinaries.push(binaryPath);
+ }
+
+ const destinationDirectory = path.join(input.stageResourcesDir, "resource-monitor");
+ const destinationPath = path.join(destinationDirectory, executableName);
+ yield* fs.remove(destinationDirectory, { recursive: true, force: true }).pipe(Effect.ignore);
+ yield* fs.makeDirectory(destinationDirectory, { recursive: true });
+
+ if (builtBinaries.length === 1) {
+ yield* fs.copyFile(builtBinaries[0]!, destinationPath);
+ } else {
+ yield* runCommand(
+ ChildProcess.make("lipo", ["-create", ...builtBinaries, "-output", destinationPath]),
+ {
+ label: "lipo resource monitor universal binary",
+ verbose: input.verbose,
+ },
+ );
+ }
+
+ if (input.platform !== "win") {
+ yield* fs.chmod(destinationPath, 0o755);
+ }
+});
+
function generateMacIconSet(
sourcePng: string,
targetIcns: string,
@@ -1412,6 +1548,7 @@ export const createBuildConfig = Effect.fn("createBuildConfig")(function* (
// WINDOWS_ASAR_UNPACK); macOS and Linux stay packed — smart unpack
// extracts native libraries, which fff-node finds in app.asar.unpacked.
...(platform === "win" ? { asarUnpack: [...WINDOWS_ASAR_UNPACK] } : {}),
+ extraResources: DESKTOP_EXTRA_RESOURCES,
};
const updateChannel = resolveDesktopUpdateChannel(version);
const publishConfig = yield* resolveGitHubPublishConfig(updateChannel);
@@ -1691,6 +1828,13 @@ const buildDesktopArtifact = Effect.fn("buildDesktopArtifact")(function* (
yield* fs.copy(distDirs.desktopDist, path.join(stageAppDir, "apps/desktop/dist-electron"));
yield* fs.copy(distDirs.desktopResources, stageResourcesDir);
yield* fs.copy(distDirs.serverDist, path.join(stageAppDir, "apps/server/dist"));
+ yield* stageResourceMonitor({
+ repoRoot,
+ stageResourcesDir,
+ platform: options.platform,
+ arch: options.arch,
+ verbose: options.verbose,
+ });
yield* assertPlatformBuildResources(
options.platform,