History

feat(connections): balance new threads across connected machines (#9895)

maria committed 2 months ago

Commit 420fd761 parent 9f40b2f26 files · +865 −22Browse files

Unified · Split

26 files
  1. apps/desktop/src/settings/DesktopClientSettings.test.ts +2 −0
  2. apps/server/src/auth/RpcAuthorization.ts +1 −0
  3. apps/server/src/resourceTelemetry/HostResources.ts +93 −0
  4. apps/server/src/server.test.ts +92 −2
  5. apps/server/src/server.ts +2 −0
  6. apps/server/src/ws.ts +6 −0
  7. apps/web/src/components/BranchToolbar.tsx +45 −7
  8. apps/web/src/components/BranchToolbarBranchSelector.tsx +4 −2
  9. apps/web/src/components/BranchToolbarEnvironmentSelector.tsx +37 −9
  10. apps/web/src/components/ChatView.tsx +131 −0
  11. apps/web/src/components/GitActionsControl.tsx +6 −2
  12. apps/web/src/components/settings/ConnectionsSettings.tsx +2 −0
  13. apps/web/src/components/settings/LoadBalancingSettings.tsx +94 −0
  14. apps/web/src/components/settings/settingsSearch.ts +8 −0
  15. apps/web/src/composerDraftStore.test.ts +57 −0
  16. apps/web/src/composerDraftStore.ts +59 −0
  17. apps/web/src/hooks/useLoadBalancedEnvironment.ts +50 −0
  18. docs/user/remote-access.md +17 −0
  19. packages/client-runtime/package.json +4 −0
  20. packages/client-runtime/src/load-balancing.ts +40 −0
  21. packages/client-runtime/src/state/projectGrouping.test.ts +65 −0
  22. packages/client-runtime/src/state/server.ts +7 −0
  23. packages/contracts/src/resourceTelemetry.ts +10 −0
  24. packages/contracts/src/rpc.ts +9 −0
  25. packages/contracts/src/settings.test.ts +15 −0
  26. packages/contracts/src/settings.ts +9 −0
apps/desktop/src/settings/DesktopClientSettings.test.ts+2−0
@@ -58,6 +58,8 @@ const clientSettings: ClientSettings = { · 57 unmodified lines
5858 sidebarThreadSortOrder: "created_at",
5959 sidebarThreadPreviewCount: 6,
6060 legacySidebarEnabled: false,
61+ loadBalancingEnabled: false,
62+ loadBalancingWeights: { "environment-1": 75, "environment-2": 0 },
6163 timestampFormat: "24-hour",
6264 wordWrap: true,
6365 };
apps/server/src/auth/RpcAuthorization.ts+1−0
@@ -53,6 +53,7 @@ export const RPC_REQUIRED_SCOPES = { · 52 unmodified lines
5353 [WS_METHODS.serverDiscoverSourceControl]: AuthOrchestrationReadScope,
5454 [WS_METHODS.serverGetTraceDiagnostics]: AuthOrchestrationReadScope,
5555 [WS_METHODS.serverGetProcessDiagnostics]: AuthOrchestrationReadScope,
56+ [WS_METHODS.serverGetHostResources]: AuthOrchestrationReadScope,
5657 [WS_METHODS.serverGetProcessResourceHistory]: AuthOrchestrationReadScope,
5758 [WS_METHODS.serverGetResourceTelemetryHistory]: AuthOrchestrationReadScope,
5859 [WS_METHODS.serverRetryResourceTelemetry]: AuthOrchestrationOperateScope,
apps/server/src/resourceTelemetry/HostResources.ts+93−0
@@ -0,0 +1,93 @@
1+import * as NodeOS from "node:os";
2+import type { HostResourcesSnapshot } from "@t3tools/contracts";
3+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
4+import * as Cache from "effect/Cache";
5+import * as Context from "effect/Context";
6+import * as DateTime from "effect/DateTime";
7+import * as Effect from "effect/Effect";
8+import * as FileSystem from "effect/FileSystem";
9+import * as Layer from "effect/Layer";
10+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
11+
12+export class HostResources extends Context.Service<
13+ HostResources,
14+ { readonly read: Effect.Effect<HostResourcesSnapshot> }
15+>()("t3/resourceTelemetry/HostResources") {}
16+
17+function readCpu() {
18+ const cpus = NodeOS.cpus();
19+ const cpu = cpus.reduce(
20+ (sum, { times }) => ({
21+ idle: sum.idle + times.idle,
22+ total: sum.total + times.user + times.nice + times.sys + times.idle + times.irq,
23+ }),
24+ { idle: 0, total: 0 },
25+ );
26+ return { ...cpu, count: cpus.length };
27+}
28+
29+function darwinAvailableMemory(output: string): number | null {
30+ const pageSize = /page size of (\d+) bytes/.exec(output)?.[1];
31+ const free = /^Pages free:\s+(\d+)\./m.exec(output)?.[1];
32+ const inactive = /^Pages inactive:\s+(\d+)\./m.exec(output)?.[1];
33+ const speculative = /^Pages speculative:\s+(\d+)\./m.exec(output)?.[1];
34+ if (!pageSize || !free || !inactive || !speculative) return null;
35+ // vm_stat subtracts speculative pages from its printed "Pages free" count.
36+ // Adding them here counts each reclaimable page once; purgeable pages overlap.
37+ const available = (Number(free) + Number(inactive) + Number(speculative)) * Number(pageSize);
38+ return Number.isSafeInteger(available) && Number(pageSize) > 0 ? available : null;
39+}
40+
41+export const make = Effect.fn("makeHostResources")(function* () {
42+ const fs = yield* FileSystem.FileSystem;
43+ const platform = yield* HostProcessPlatform;
44+ const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
45+
46+ const sample = Effect.fn("HostResources.sample")(function* () {
47+ const previousCpu = readCpu();
48+ // CPU counters need two readings; idle servers do no polling or process scans.
49+ yield* Effect.sleep("200 millis");
50+ const cpu = readCpu();
51+ const totalDelta = cpu.total - previousCpu.total;
52+ const idleDelta = cpu.idle - previousCpu.idle;
53+ const cpuUtilization =
54+ previousCpu.count === cpu.count && totalDelta > 0 && idleDelta >= 0
55+ ? Math.min(1, Math.max(0, 1 - idleDelta / totalDelta))
56+ : null;
57+ const totalMemoryBytes = NodeOS.totalmem();
58+ // On Windows libuv returns GlobalMemoryStatusEx.ullAvailPhys, including standby memory.
59+ let availableMemoryBytes = NodeOS.freemem();
60+ if (platform === "linux") {
61+ const meminfo = yield* fs
62+ .readFileString("/proc/meminfo")
63+ .pipe(Effect.catch(() => Effect.succeed("")));
64+ const available = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(meminfo)?.[1];
65+ if (available) availableMemoryBytes = Number(available) * 1024;
66+ } else if (platform === "darwin") {
67+ const output = yield* spawner
68+ .string(ChildProcess.make("/usr/bin/vm_stat", [], { stdin: "ignore", stderr: "ignore" }))
69+ .pipe(
70+ Effect.timeout("1 second"),
71+ Effect.catch(() => Effect.succeed("")),
72+ );
73+ availableMemoryBytes = darwinAvailableMemory(output) ?? availableMemoryBytes;
74+ }
75+ return {
76+ sampledAt: DateTime.toEpochMillis(yield* DateTime.now),
77+ cpuUtilization,
78+ cpuCount: cpu.count,
79+ availableMemoryBytes: Math.min(totalMemoryBytes, Math.max(0, availableMemoryBytes)),
80+ totalMemoryBytes,
81+ };
82+ });
83+
84+ // One server-lifetime cache deduplicates simultaneous requests from all sockets.
85+ const cache = yield* Cache.make({
86+ capacity: 1,
87+ lookup: (_key: "host") => sample(),
88+ timeToLive: "5 seconds",
89+ });
90+ return HostResources.of({ read: Cache.get(cache, "host") });
91+});
92+
93+export const layer = Layer.effect(HostResources, make());
apps/server/src/server.test.ts+92−2
@@ -165,6 +165,7 @@ import * as PairingGrantStore from "./auth/PairingGrantStore.ts"; · 164 unmodified lines
165165 import * as CloudManagedEndpointRuntime from "./cloud/ManagedEndpointRuntime.ts";
166166 import * as CloudCliTokenManager from "./cloud/CliTokenManager.ts";
167167 import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";
168+import * as HostResources from "./resourceTelemetry/HostResources.ts";
168169 import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";
169170 import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";
170171 import * as DesktopTelemetryReceiver from "./resourceTelemetry/DesktopTelemetryReceiver.ts";
@@ -845,7 +846,8 @@ const buildAppUnderTest = (options?: { · 674 unmodified lines
845846 }),
846847 }),
847848 ),
848− Layer.provide(
849+ Layer.provide([
850+ HostResources.layer,
849851 Layer.mock(ProcessResourceMonitor.ProcessResourceMonitor)({
850852 readHistory: (input) =>
851853 Effect.succeed({
@@ -860,7 +862,7 @@ const buildAppUnderTest = (options?: { · 8 unmodified lines
860862 error: Option.none(),
861863 }),
862864 }),
863− ),
865+ ]),
864866 Layer.provide(
865867 Layer.mock(TraceDiagnostics.TraceDiagnostics)({
866868 read: () =>
@@ -6154,6 +6156,94 @@ it.layer(NodeServices.layer)("server router seam", (it) => { · 5287 unmodified lines
61546156 }).pipe(Effect.provide(NodeHttpServer.layerTest)),
61556157 );
61566158
6159+ it.effect("returns cached whole-host resources over websocket", () =>
6160+ Effect.gen(function* () {
6161+ yield* buildAppUnderTest();
6162+ const wsUrl = yield* getWsServerUrl("/ws");
6163+ const [first, second] = yield* Effect.scoped(
6164+ withWsRpcClient(wsUrl, (client) =>
6165+ Effect.all(
6166+ [
6167+ client[WS_METHODS.serverGetHostResources]({}),
6168+ client[WS_METHODS.serverGetHostResources]({}),
6169+ ],
6170+ { concurrency: "unbounded" },
6171+ ),
6172+ ),
6173+ );
6174+ assert.deepEqual(first, second);
6175+ assert.isAtLeast(first.sampledAt, 0);
6176+ assert.isAbove(first.cpuCount, 0);
6177+ assert.isAbove(first.totalMemoryBytes, 0);
6178+ assert.isAtLeast(first.availableMemoryBytes, 0);
6179+ assert.isAtMost(first.availableMemoryBytes, first.totalMemoryBytes);
6180+ if (first.cpuUtilization !== null) {
6181+ assert.isAtLeast(first.cpuUtilization, 0);
6182+ assert.isAtMost(first.cpuUtilization, 1);
6183+ }
6184+ }).pipe(Effect.provide(NodeHttpServer.layerTest), TestClock.withLive),
6185+ );
6186+
6187+ it.effect("counts macOS reclaimable memory once and shares concurrent samples", () =>
6188+ Effect.gen(function* () {
6189+ const commandCalls = yield* Ref.make(0);
6190+ const hostResources = yield* HostResources.make().pipe(
6191+ Effect.provideService(HostProcessPlatform, "darwin"),
6192+ Effect.provide(
6193+ Layer.mock(ChildProcessSpawner.ChildProcessSpawner)({
6194+ string: () =>
6195+ Ref.update(commandCalls, (count) => count + 1).pipe(
6196+ Effect.as(
6197+ "Mach Virtual Memory Statistics: (page size of 16384 bytes)\n" +
6198+ "Pages free: 10.\nPages inactive: 20.\nPages speculative: 5.\n" +
6199+ "Pages purgeable: 999.\n",
6200+ ),
6201+ ),
6202+ }),
6203+ ),
6204+ );
6205+ const [first, second] = yield* Effect.all([hostResources.read, hostResources.read], {
6206+ concurrency: "unbounded",
6207+ });
6208+ assert.equal(first.availableMemoryBytes, 35 * 16384);
6209+ assert.deepEqual(first, second);
6210+ assert.deepEqual(yield* hostResources.read, first);
6211+ assert.equal(yield* Ref.get(commandCalls), 1);
6212+ }).pipe(TestClock.withLive),
6213+ );
6214+
6215+ it.effect("retries host sampling immediately after its caller is interrupted", () =>
6216+ Effect.gen(function* () {
6217+ const started = yield* Deferred.make<void>();
6218+ const commandCalls = yield* Ref.make(0);
6219+ const hostResources = yield* HostResources.make().pipe(
6220+ Effect.provideService(HostProcessPlatform, "darwin"),
6221+ Effect.provide(
6222+ Layer.mock(ChildProcessSpawner.ChildProcessSpawner)({
6223+ string: () =>
6224+ Effect.gen(function* () {
6225+ const call = yield* Ref.updateAndGet(commandCalls, (count) => count + 1);
6226+ if (call === 1) {
6227+ yield* Deferred.succeed(started, undefined);
6228+ return yield* Effect.never;
6229+ }
6230+ return (
6231+ "Mach Virtual Memory Statistics: (page size of 4096 bytes)\n" +
6232+ "Pages free: 10.\nPages inactive: 20.\nPages speculative: 5.\n"
6233+ );
6234+ }),
6235+ }),
6236+ ),
6237+ );
6238+ const firstRead = yield* hostResources.read.pipe(Effect.forkChild);
6239+ yield* Deferred.await(started);
6240+ yield* Fiber.interrupt(firstRead);
6241+ const recovered = yield* hostResources.read;
6242+ assert.equal(recovered.availableMemoryBytes, 35 * 4096);
6243+ assert.equal(yield* Ref.get(commandCalls), 2);
6244+ }).pipe(TestClock.withLive),
6245+ );
6246+
61576247 it.effect("routes websocket resource telemetry through the subscription", () =>
61586248 Effect.gen(function* () {
61596249 yield* buildAppUnderTest();
apps/server/src/server.ts+2−0
@@ -115,6 +115,7 @@ import * as ServerSelfUpdate from "./cloud/selfUpdate.ts"; · 114 unmodified lines
115115 import * as DesktopAppUpdate from "./desktopUpdate/DesktopAppUpdate.ts";
116116 import * as ServiceLauncherClient from "./cloud/serviceLauncherClient.ts";
117117 import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";
118+import * as HostResources from "./resourceTelemetry/HostResources.ts";
118119 import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";
119120 import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";
120121 import * as DesktopTelemetryReceiver from "./resourceTelemetry/DesktopTelemetryReceiver.ts";
@@ -199,6 +200,7 @@ const BackgroundLayerLive = BackgroundPolicy.layer.pipe( · 78 unmodified lines
199200 const UsageLayerLive = UsageService.layer.pipe(Layer.provide(ServerSettingsLayerLive));
200201
201202 const ResourceDiagnosticsLayerLive = Layer.mergeAll(
203+ HostResources.layer,
202204 ResourceTelemetryLayerLive,
203205 ProcessDiagnostics.layer.pipe(Layer.provide(ResourceTelemetryLayerLive)),
204206 ProcessResourceMonitor.layer.pipe(Layer.provide(ResourceTelemetryLayerLive)),
apps/server/src/ws.ts+6−0
@@ -135,6 +135,7 @@ import { requiredScopeForRpcMethod } from "./auth/RpcAuthorization.ts"; · 134 unmodified lines
135135 import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";
136136 import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";
137137 import * as ResourceTelemetry from "./resourceTelemetry/ResourceTelemetry.ts";
138+import * as HostResources from "./resourceTelemetry/HostResources.ts";
138139 import * as AnalyticsService from "./telemetry/AnalyticsService.ts";
139140 import * as UsageLimitSources from "./usage/UsageLimitSources.ts";
140141 import * as UsageService from "./usage/UsageService.ts";
@@ -605,6 +606,7 @@ const makeWsRpcLayer = ( · 464 unmodified lines
605606 const bootstrapCredentials = yield* PairingGrantStore.PairingGrantStore;
606607 const sessions = yield* SessionStore.SessionStore;
607608 const processDiagnostics = yield* ProcessDiagnostics.ProcessDiagnostics;
609+ const hostResources = yield* HostResources.HostResources;
608610 const processResourceMonitor = yield* ProcessResourceMonitor.ProcessResourceMonitor;
609611 const resourceTelemetry = yield* ResourceTelemetry.ResourceTelemetry;
610612 const usage = yield* UsageService.UsageService;
@@ -2020,6 +2022,10 @@ const makeWsRpcLayer = ( · 1409 unmodified lines
20202022 observeRpcEffect(WS_METHODS.serverGetProcessDiagnostics, processDiagnostics.read, {
20212023 "rpc.aggregate": "server",
20222024 }),
2025+ [WS_METHODS.serverGetHostResources]: (_input) =>
2026+ observeRpcEffect(WS_METHODS.serverGetHostResources, hostResources.read, {
2027+ "rpc.aggregate": "server",
2028+ }),
20232029 [WS_METHODS.serverGetProcessResourceHistory]: (input) =>
20242030 observeRpcEffect(
20252031 WS_METHODS.serverGetProcessResourceHistory,
apps/web/src/components/BranchToolbar.tsx+45−7
@@ -6,6 +6,7 @@ import { · 5 unmodified lines
66 FolderGitIcon,
77 FolderIcon,
88 HistoryIcon,
9+ ScaleIcon,
910 } from "lucide-react";
1011 import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
1112
@@ -56,6 +57,8 @@ interface BranchToolbarProps { · 44 unmodified lines
5657 onActiveThreadBranchOverrideChange?: (branch: string | null) => void;
5758 startFromOrigin: boolean;
5859 onStartFromOriginChange: (startFromOrigin: boolean) => void;
60+ autoEnvironmentLabel?: string | undefined;
61+ onAutoEnvironment?: (() => void) | undefined;
5962 envLocked: boolean;
6063 onCheckoutPullRequestRequest?: (reference: string) => void;
6164 onComposerFocusRequest?: () => void;
@@ -66,6 +69,8 @@ interface BranchToolbarProps { · 4 unmodified lines
6669 }
6770
6871 interface MobileRunContextSelectorProps {
72+ autoEnvironmentLabel?: string | undefined;
73+ onAutoEnvironment?: (() => void) | undefined;
6974 envLocked: boolean;
7075 envModeLocked: boolean;
7176 environmentId: EnvironmentId;
@@ -81,6 +86,8 @@ interface MobileRunContextSelectorProps { · 9 unmodified lines
8186 }
8287
8388 const MobileRunContextSelector = memo(function MobileRunContextSelector({
89+ autoEnvironmentLabel,
90+ onAutoEnvironment,
8491 envLocked,
8592 envModeLocked,
8693 environmentId,
@@ -114,10 +121,14 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({ · 27 unmodified lines
114121 // Button's base styles apply `-mx-0.5` to descendant SVGs, which eats 4px
115122 // out of whatever gap we set. mx-0! cancels that so gap-0.5 reads as 2px.
116123 <span className="inline-flex shrink-0 items-center gap-0.5">
117− <EnvironmentMachineIcon
118− kind={activeEnvironment?.machine ?? "server"}
119− className="size-3 shrink-0 mx-0!"
120− />
124+ {autoEnvironmentLabel ? (
125+ <ScaleIcon className="size-3 shrink-0 mx-0!" aria-hidden="true" />
126+ ) : (
127+ <EnvironmentMachineIcon
128+ kind={activeEnvironment?.machine ?? "server"}
129+ className="size-3 shrink-0 mx-0!"
130+ />
131+ )}
121132 <WorkspaceIcon className="size-3 shrink-0 mx-0!" />
122133 </span>
123134 ) : (
@@ -134,7 +145,8 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({ · 10 unmodified lines
134145 data-composer-label-motion
135146 className="block w-full min-w-0 max-w-[240px] origin-left truncate transition-[opacity,transform] duration-180 ease-[cubic-bezier(0.32,0.72,0,1)] group-data-[compact]/composer-context:[transform:translateX(-0.25rem)_scaleX(0.95)] group-data-[compact]/composer-context:opacity-0 motion-reduce:transform-none motion-reduce:transition-opacity"
136147 >
137− {showEnvironmentIndicator ? (activeEnvironment?.label ?? "Run on") : workspaceLabel}
148+ {autoEnvironmentLabel ??
149+ (showEnvironmentIndicator ? (activeEnvironment?.label ?? "Run on") : workspaceLabel)}
138150 </span>
139151 </span>
140152 </>
@@ -167,9 +179,29 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({ · 26 unmodified lines
167179 <MenuGroup>
168180 <MenuGroupLabel>Run on</MenuGroupLabel>
169181 <MenuRadioGroup
170− value={environmentId}
171− onValueChange={(value) => onEnvironmentChange(value as EnvironmentId)}
182+ value={autoEnvironmentLabel ? "auto" : environmentId}
183+ onValueChange={(value) =>
184+ value === "auto"
185+ ? onAutoEnvironment?.()
186+ : onEnvironmentChange(value as EnvironmentId)
187+ }
172188 >
189+ {onAutoEnvironment && (
190+ <MenuRadioItem
191+ value="auto"
192+ disabled={envLocked}
193+ onClick={() => {
194+ if (autoEnvironmentLabel) onAutoEnvironment?.();
195+ }}
196+ >
197+ <span className="flex min-w-0 items-center gap-1.5">
198+ <ScaleIcon className="size-3" aria-hidden="true" />
199+ <span className="min-w-0 truncate">
200+ {autoEnvironmentLabel ?? "Auto balance"}
201+ </span>
202+ </span>
203+ </MenuRadioItem>
204+ )}
173205 {availableEnvironments.map((env) => (
174206 <MenuRadioItem
175207 key={env.environmentId}
@@ -421,6 +453,8 @@ export const BranchToolbar = memo(function BranchToolbar({ · 245 unmodified lines
421453 onActiveThreadBranchOverrideChange,
422454 startFromOrigin,
423455 onStartFromOriginChange,
456+ autoEnvironmentLabel,
457+ onAutoEnvironment,
424458 envLocked,
425459 onCheckoutPullRequestRequest,
426460 onComposerFocusRequest,
@@ -518,6 +552,8 @@ export const BranchToolbar = memo(function BranchToolbar({ · 91 unmodified lines
518552 {showGitControls ? (
519553 <div className="contents @3xl/composer-surface:hidden">
520554 <MobileRunContextSelector
555+ autoEnvironmentLabel={autoEnvironmentLabel}
556+ onAutoEnvironment={onAutoEnvironment}
521557 envLocked={envLocked}
522558 envModeLocked={envModeLocked}
523559 environmentId={environmentId}
@@ -544,6 +580,8 @@ export const BranchToolbar = memo(function BranchToolbar({ · 20 unmodified lines
544580 {showEnvironmentIndicator && availableEnvironments && (
545581 <>
546582 <BranchToolbarEnvironmentSelector
583+ autoEnvironmentLabel={autoEnvironmentLabel}
584+ onAutoEnvironment={onAutoEnvironment}
547585 envLocked={envLocked}
548586 environmentId={environmentId}
549587 availableEnvironments={availableEnvironments}
apps/web/src/components/BranchToolbarBranchSelector.tsx+4−2
@@ -155,7 +155,7 @@ export function BranchToolbarBranchSelector({ · 154 unmodified lines
155155 // Thread branch mutation (colocated — only this component calls it)
156156 // ---------------------------------------------------------------------------
157157 const setThreadBranch = useCallback(
158− (branch: string | null, worktreePath: string | null) => {
158+ (branch: string | null, worktreePath: string | null, automatic = false) => {
159159 if (!activeThreadId || !activeProject) return;
160160 if (serverSession && worktreePath !== activeWorktreePath) {
161161 void stopThreadSession({
@@ -186,6 +186,7 @@ export function BranchToolbarBranchSelector({ · 24 unmodified lines
186186 branch,
187187 worktreePath,
188188 envMode: nextDraftEnvMode,
189+ environmentSelection: automatic ? (draftThread?.environmentSelection ?? "auto") : "manual",
189190 projectRef: scopeProjectRef(environmentId, activeProject.id),
190191 });
191192 },
@@ -201,6 +202,7 @@ export function BranchToolbarBranchSelector({ · 9 unmodified lines
201202 threadRef,
202203 environmentId,
203204 effectiveEnvMode,
205+ draftThread?.environmentSelection,
204206 stopThreadSession,
205207 updateThreadMetadata,
206208 ],
@@ -507,7 +509,7 @@ export function BranchToolbarBranchSelector({ · 300 unmodified lines
507509 ) {
508510 return;
509511 }
510− setThreadBranch(worktreeBaseBranchCandidate, null);
512+ setThreadBranch(worktreeBaseBranchCandidate, null, true);
511513 }, [
512514 activeThreadBranch,
513515 activeWorktreePath,
apps/web/src/components/BranchToolbarEnvironmentSelector.tsx+37−9
@@ -1,4 +1,5 @@
11 import type { EnvironmentId } from "@t3tools/contracts";
2+import { ScaleIcon } from "lucide-react";
23 import { memo, useMemo } from "react";
34
45 import type { EnvironmentOption } from "./BranchToolbar.logic";
@@ -15,6 +16,8 @@ import { · 10 unmodified lines
1516 } from "./ui/select";
1617
1718 interface BranchToolbarEnvironmentSelectorProps {
19+ autoEnvironmentLabel?: string | undefined;
20+ onAutoEnvironment?: (() => void) | undefined;
1821 envLocked: boolean;
1922 environmentId: EnvironmentId;
2023 availableEnvironments: readonly EnvironmentOption[];
@@ -24,6 +27,8 @@ interface BranchToolbarEnvironmentSelectorProps { · 3 unmodified lines
2427 }
2528
2629 export const BranchToolbarEnvironmentSelector = memo(function BranchToolbarEnvironmentSelector({
30+ autoEnvironmentLabel,
31+ onAutoEnvironment,
2732 envLocked,
2833 environmentId,
2934 availableEnvironments,
@@ -34,12 +39,16 @@ export const BranchToolbarEnvironmentSelector = memo(function BranchToolbarEnvir · 4 unmodified lines
3439 }, [availableEnvironments, environmentId]);
3540
3641 const environmentItems = useMemo(
37− () =>
38− availableEnvironments.map((env) => ({
42+ () => [
43+ ...(onAutoEnvironment
44+ ? [{ value: "auto", label: autoEnvironmentLabel ?? "Auto balance" }]
45+ : []),
46+ ...availableEnvironments.map((env) => ({
3947 value: env.environmentId,
4048 label: env.label,
4149 })),
42− [availableEnvironments],
50+ ],
51+ [availableEnvironments, autoEnvironmentLabel, onAutoEnvironment],
4352 );
4453
4554 // The static label carries the xs control's height (h-7 sm:h-6) as well as
@@ -75,8 +84,10 @@ export const BranchToolbarEnvironmentSelector = memo(function BranchToolbarEnvir · 29 unmodified lines
7584 return (
7685 <Select
7786 modal={false}
78− value={environmentId}
79− onValueChange={(value) => onEnvironmentChange(value as EnvironmentId)}
87+ value={autoEnvironmentLabel ? "auto" : environmentId}
88+ onValueChange={(value) =>
89+ value === "auto" ? onAutoEnvironment?.() : onEnvironmentChange(value as EnvironmentId)
90+ }
8091 items={environmentItems}
8192 >
8293 <SelectTrigger
@@ -86,10 +97,14 @@ export const BranchToolbarEnvironmentSelector = memo(function BranchToolbarEnvir · 3 unmodified lines
8697 aria-label="Run on"
8798 data-composer-context-control
8899 >
89− <EnvironmentMachineIcon
90− kind={activeEnvironment?.machine ?? "server"}
91− className="size-3 shrink-0"
92− />
100+ {autoEnvironmentLabel ? (
101+ <ScaleIcon className="size-3 shrink-0" aria-hidden="true" />
102+ ) : (
103+ <EnvironmentMachineIcon
104+ kind={activeEnvironment?.machine ?? "server"}
105+ className="size-3 shrink-0"
106+ />
107+ )}
93108 <span
94109 data-composer-label
95110 className="min-w-0 max-w-[240px] group-data-[compact]/composer-context:max-w-0"
@@ -105,6 +120,19 @@ export const BranchToolbarEnvironmentSelector = memo(function BranchToolbarEnvir · 9 unmodified lines
105120 <SelectPopup alignItemWithTrigger={false} {...composerFloatingLayerProps}>
106121 <SelectGroup>
107122 <SelectGroupLabel>Run on</SelectGroupLabel>
123+ {onAutoEnvironment && (
124+ <SelectItem
125+ value="auto"
126+ onClick={() => {
127+ if (autoEnvironmentLabel) onAutoEnvironment?.();
128+ }}
129+ >
130+ <span className="inline-flex items-center gap-1.5">
131+ <ScaleIcon className="size-3" aria-hidden="true" />
132+ {autoEnvironmentLabel ?? "Auto balance"}
133+ </span>
134+ </SelectItem>
135+ )}
108136 {availableEnvironments.map((env) => (
109137 <SelectItem key={env.environmentId} value={env.environmentId}>
110138 <span className="inline-flex items-center gap-1.5">
apps/web/src/components/ChatView.tsx+131−0
@@ -1,3 +1,4 @@
1+import { useLoadBalancedEnvironment } from "../hooks/useLoadBalancedEnvironment";
12 import type { UsageLimitSourceSnapshots } from "@t3tools/contracts";
23 import {
34 collectProviderUsageLimits,
@@ -3278,6 +3279,112 @@ export default function ChatView(props: ChatViewProps) { · 3274 unmodified lines
32783279 (activeThread.session !== null && activeThread.session.status !== "stopped")),
32793280 );
32803281
3282+ const loadBalancingSettings = useClientSettings();
3283+ const automaticEnvironment = Boolean(
3284+ clientSettingsHydrated &&
3285+ draftId &&
3286+ !envLocked &&
3287+ hasMultipleEnvironments &&
3288+ loadBalancingSettings.loadBalancingEnabled &&
3289+ draftThread?.environmentSelection !== "manual" &&
3290+ (!composerHasAttachments || Boolean(draftThread?.loadBalancedEnvironmentId)) &&
3291+ (!draftThread?.branch || draftThread.environmentSelection === "auto") &&
3292+ !draftThread?.worktreePath,
3293+ );
3294+ const needsLoadBalancing = automaticEnvironment && !draftThread?.loadBalancedEnvironmentId;
3295+ const loadBalancingCandidates = useMemo(
3296+ () =>
3297+ needsLoadBalancing
3298+ ? logicalProjectEnvironments
3299+ .filter((candidate) => {
3300+ const environment = environmentById.get(candidate.environmentId);
3301+ return (
3302+ environment?.connection.phase === "connected" &&
3303+ (loadBalancingSettings.loadBalancingWeights[candidate.environmentId] ?? 50) > 0 &&
3304+ environment.serverConfig?.providers.some(
3305+ (provider) =>
3306+ (activeProviderInstanceId === null ||
3307+ provider.instanceId === activeProviderInstanceId) &&
3308+ provider.driver === selectedProvider &&
3309+ provider.enabled &&
3310+ provider.installed &&
3311+ provider.status !== "error" &&
3312+ provider.auth.status !== "unauthenticated" &&
3313+ provider.availability !== "unavailable",
3314+ )
3315+ );
3316+ })
3317+ .map((candidate) => candidate.environmentId)
3318+ : [],
3319+ [
3320+ needsLoadBalancing,
3321+ logicalProjectEnvironments,
3322+ environmentById,
3323+ loadBalancingSettings.loadBalancingWeights,
3324+ activeProviderInstanceId,
3325+ selectedProvider,
3326+ ],
3327+ );
3328+ const loadBalancing = useLoadBalancedEnvironment(
3329+ loadBalancingCandidates,
3330+ loadBalancingSettings.loadBalancingWeights,
3331+ );
3332+ useEffect(() => {
3333+ if (!needsLoadBalancing || loadBalancing.pending || !draftId || sendInFlightRef.current) return;
3334+ const target = logicalProjectEnvironments.find(
3335+ (environment) => environment.environmentId === loadBalancing.environmentId,
3336+ );
3337+ if (!target) return;
3338+ setDraftThreadContext(draftId, {
3339+ projectRef: scopeProjectRef(target.environmentId, target.projectId),
3340+ environmentSelection: "auto",
3341+ loadBalancedEnvironmentId: target.environmentId,
3342+ });
3343+ }, [
3344+ needsLoadBalancing,
3345+ loadBalancing.pending,
3346+ loadBalancing.environmentId,
3347+ draftId,
3348+ logicalProjectEnvironments,
3349+ setDraftThreadContext,
3350+ ]);
3351+ const onAutoEnvironment = useCallback(() => {
3352+ if (envLocked || !draftId) return;
3353+ if (composerHasAttachments) {
3354+ toastManager.add({
3355+ type: "warning",
3356+ id: "load-balancing-attachments",
3357+ title: "Keep attachments on this machine",
3358+ description:
3359+ "Remove attachments before choosing automatic routing, then attach them on the selected machine.",
3360+ });
3361+ return;
3362+ }
3363+ loadBalancing.refresh(
3364+ logicalProjectEnvironments.map((environment) => environment.environmentId),
3365+ );
3366+ setDraftThreadContext(draftId, {
3367+ environmentSelection: "auto",
3368+ loadBalancedEnvironmentId: null,
3369+ branch: null,
3370+ worktreePath: null,
3371+ });
3372+ }, [
3373+ envLocked,
3374+ draftId,
3375+ setDraftThreadContext,
3376+ loadBalancing.refresh,
3377+ logicalProjectEnvironments,
3378+ composerHasAttachments,
3379+ ]);
3380+ const autoEnvironmentLabel = automaticEnvironment
3381+ ? draftThread?.loadBalancedEnvironmentId
3382+ ? "Auto balance"
3383+ : loadBalancing.pending
3384+ ? "Checking machines…"
3385+ : "Auto balance unavailable"
3386+ : undefined;
3387+
32813388 // Handle environment change for draft threads. When the user picks a
32823389 // different environment we update the draft context to point at the physical
32833390 // project in that environment while keeping the same logical project.
@@ -3290,6 +3397,8 @@ export default function ChatView(props: ChatViewProps) { · 6 unmodified lines
32903397 if (!target) return;
32913398 setDraftThreadContext(draftId, {
32923399 projectRef: scopeProjectRef(target.environmentId, target.projectId),
3400+ environmentSelection: "manual",
3401+ loadBalancedEnvironmentId: null,
32933402 });
32943403 },
32953404 [draftId, envLocked, logicalProjectEnvironments, setDraftThreadContext],
@@ -6249,6 +6358,7 @@ export default function ChatView(props: ChatViewProps) { · 2953 unmodified lines
62496358 !activeThread ||
62506359 isSendBusy ||
62516360 isConnecting ||
6361+ !clientSettingsHydrated ||
62526362 threadDetailLoading ||
62536363 sendInFlightRef.current ||
62546364 feedbackUploadsInFlightRef.current.has(routeThreadKey)
@@ -6256,6 +6366,18 @@ export default function ChatView(props: ChatViewProps) { · 1 unmodified line
62566366 notifyDirectAnnotationAttached();
62576367 return;
62586368 }
6369+ if (needsLoadBalancing) {
6370+ toastManager.add({
6371+ type: "warning",
6372+ title: loadBalancing.pending
6373+ ? "Checking machine resources"
6374+ : "Choose a machine to continue",
6375+ description: loadBalancing.pending
6376+ ? "Resource checks are still running. You can choose a machine in the composer."
6377+ : "No eligible machine has available resources. Choose a machine in the composer to override.",
6378+ });
6379+ return;
6380+ }
62596381 if (activeEnvironmentUnavailable) {
62606382 const toastSlot = environmentUnavailableSendToastSlotRef.current;
62616383 environmentUnavailableSendToastSlotRef.current =
@@ -8231,6 +8353,15 @@ export default function ChatView(props: ChatViewProps) { · 1969 unmodified lines
82318353 ? { onCheckoutPullRequestRequest: openPullRequestDialog }
82328354 : {})}
82338355 {...(hasMultipleEnvironments ? { onEnvironmentChange } : {})}
8356+ autoEnvironmentLabel={autoEnvironmentLabel}
8357+ onAutoEnvironment={
8358+ draftId &&
8359+ !envLocked &&
8360+ hasMultipleEnvironments &&
8361+ loadBalancingSettings.loadBalancingEnabled
8362+ ? onAutoEnvironment
8363+ : undefined
8364+ }
82348365 availableEnvironments={logicalProjectEnvironments}
82358366 composerControlsHostRef={setRestingComposerControlsHost}
82368367 contextStripVisible={showComposerContextStrip}
apps/web/src/components/GitActionsControl.tsx+6−2
@@ -1042,7 +1042,7 @@ export default function GitActionsControl({ · 1041 unmodified lines
10421042 }, []);
10431043
10441044 const persistThreadBranchSync = useCallback(
1045− (branch: string | null) => {
1045+ (branch: string | null, manualSelection = false) => {
10461046 if (!activeThreadRef) {
10471047 return;
10481048 }
@@ -1070,6 +1070,10 @@ export default function GitActionsControl({ · 21 unmodified lines
10701070 setDraftThreadContext(draftId ?? activeThreadRef, {
10711071 branch,
10721072 worktreePath: activeDraftThread.worktreePath,
1073+ environmentSelection: manualSelection
1074+ ? "manual"
1075+ : (activeDraftThread.environmentSelection ??
1076+ (activeDraftThread.branch ? "manual" : "auto")),
10731077 });
10741078 },
10751079 [
@@ -1089,7 +1093,7 @@ export default function GitActionsControl({ · 13 unmodified lines
10891093 return;
10901094 }
10911095
1092− persistThreadBranchSync(branchUpdate.branch);
1096+ persistThreadBranchSync(branchUpdate.branch, true);
10931097 },
10941098 [persistThreadBranchSync],
10951099 );
apps/web/src/components/settings/ConnectionsSettings.tsx+2−0
@@ -60,6 +60,7 @@ import { · 59 unmodified lines
6060 } from "./settingsLayout";
6161 import { searchableSetting } from "./settingsSearch";
6262 import { EnvironmentIconPicker } from "./EnvironmentIconPicker";
63+import { LoadBalancingSettings } from "./LoadBalancingSettings";
6364 import { Input } from "../ui/input";
6465 import { CommandShortcut } from "../ui/command";
6566 import {
@@ -3592,6 +3593,7 @@ export function ConnectionsSettings() { · 3526 unmodified lines
35923593 savedEnvironments={savedEnvironments}
35933594 />
35943595 </SettingsSection>
3596+ <LoadBalancingSettings environments={environments} />
35953597 </SettingsPageContainer>
35963598 );
35973599 }
apps/web/src/components/settings/LoadBalancingSettings.tsx+94−0
@@ -0,0 +1,94 @@
1+import { connectionStatusText } from "@t3tools/client-runtime/connection";
2+
3+import {
4+ useClientSettings,
5+ useClientSettingsHydrated,
6+ useUpdateClientSettings,
7+} from "~/hooks/useSettings";
8+import type { EnvironmentPresentation } from "~/state/environments";
9+import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
10+import { Switch } from "../ui/switch";
11+import { SettingsRow, SettingsSection } from "./settingsLayout";
12+import { searchableSetting } from "./settingsSearch";
13+
14+const preferences = [
15+ { value: 100, label: "Prefer" },
16+ { value: 50, label: "Normal" },
17+ { value: 25, label: "Less often" },
18+ { value: 0, label: "Manual only" },
19+];
20+
21+export function LoadBalancingSettings({
22+ environments,
23+}: {
24+ environments: ReadonlyArray<EnvironmentPresentation>;
25+}) {
26+ const settings = useClientSettings();
27+ const settingsHydrated = useClientSettingsHydrated();
28+ const updateSettings = useUpdateClientSettings();
29+
30+ return (
31+ <SettingsSection
32+ {...searchableSetting("load-balancing")}
33+ description="Choose how often each machine is used. Prefer gives a machine more work when it has capacity; Less often gives it less. Manual only excludes it from automatic selection. Preferences are saved for this client."
34+ >
35+ <SettingsRow
36+ title="Automatically balance load"
37+ description="Automatically choose a connected machine for new threads in shared projects. You can choose a machine in the composer."
38+ control={
39+ <Switch
40+ aria-label="Automatically balance load"
41+ checked={settings.loadBalancingEnabled}
42+ disabled={!settingsHydrated}
43+ onCheckedChange={(loadBalancingEnabled) => updateSettings({ loadBalancingEnabled })}
44+ />
45+ }
46+ />
47+ {environments.map((environment) => {
48+ const weight = settings.loadBalancingWeights[environment.environmentId] ?? 50;
49+ // Keep saved slider weights until the user chooses a different preference.
50+ const preference = weight === 0 ? 0 : weight < 50 ? 25 : weight === 50 ? 50 : 100;
51+
52+ return (
53+ <SettingsRow
54+ key={environment.environmentId}
55+ title={environment.label}
56+ description={connectionStatusText(environment.connection)}
57+ control={
58+ <Select
59+ items={preferences}
60+ value={preference}
61+ disabled={!settingsHydrated || !settings.loadBalancingEnabled}
62+ onValueChange={(value) => {
63+ if (value !== null) {
64+ updateSettings({
65+ loadBalancingWeights: {
66+ ...settings.loadBalancingWeights,
67+ [environment.environmentId]: value,
68+ },
69+ });
70+ }
71+ }}
72+ >
73+ <SelectTrigger
74+ size="sm"
75+ className="w-full sm:w-40"
76+ aria-label={`${environment.label} load preference`}
77+ >
78+ <SelectValue />
79+ </SelectTrigger>
80+ <SelectPopup align="end" alignItemWithTrigger={false}>
81+ {preferences.map(({ value, label }) => (
82+ <SelectItem key={value} value={value}>
83+ {label}
84+ </SelectItem>
85+ ))}
86+ </SelectPopup>
87+ </Select>
88+ }
89+ />
90+ );
91+ })}
92+ </SettingsSection>
93+ );
94+}
apps/web/src/components/settings/settingsSearch.ts+8−0
@@ -514,6 +514,14 @@ export const SETTINGS_SEARCH_ITEMS = [ · 513 unmodified lines
514514 to: "/settings/connections",
515515 searchTerms: ["add pair backend host code ssh config agent tunnel saved t3 connect"],
516516 },
517+ {
518+ id: "load-balancing",
519+ title: "Load balancing",
520+ to: "/settings/connections",
521+ searchTerms: [
522+ "automatic machine environment resources cpu memory capacity preference weight shared projects",
523+ ],
524+ },
517525 {
518526 id: "archive",
519527 title: "Archived threads",
apps/web/src/composerDraftStore.test.ts+57−0
@@ -1623,6 +1623,63 @@ describe("composerDraftStore project draft thread mapping", () => { · 1622 unmodified lines
16231623 expect(file && composerFileNeedsReattach(file)).toBe(true);
16241624 });
16251625
1626+ it("rechecks balancing when an empty draft is remapped to another project member", () => {
1627+ const store = useComposerDraftStore.getState();
1628+ store.setProjectDraftThreadId(projectRef, draftId, {
1629+ threadId,
1630+ environmentSelection: "auto",
1631+ loadBalancedEnvironmentId: TEST_ENVIRONMENT_ID,
1632+ });
1633+ store.setProjectDraftThreadId(remoteProjectRef, draftId, { threadId });
1634+ expect(store.getDraftThread(draftId)).toMatchObject({
1635+ environmentSelection: "auto",
1636+ loadBalancedEnvironmentId: null,
1637+ });
1638+ store.setDraftThreadContext(draftId, { loadBalancedEnvironmentId: OTHER_TEST_ENVIRONMENT_ID });
1639+ store.setDraftThreadContext(draftId, { projectRef });
1640+ expect(store.getDraftThread(draftId)).toMatchObject({
1641+ environmentSelection: "auto",
1642+ loadBalancedEnvironmentId: null,
1643+ });
1644+ });
1645+
1646+ it("does not opt a legacy branch choice into balancing when runtime mode changes", () => {
1647+ const store = useComposerDraftStore.getState();
1648+ store.setProjectDraftThreadId(projectRef, draftId, { threadId, branch: "feature/pinned" });
1649+ store.setDraftThreadContext(draftId, { runtimeMode: "full-access" });
1650+ expect(store.getDraftThread(draftId)?.environmentSelection).toBeUndefined();
1651+ expect(store.getDraftThread(draftId)?.branch).toBe("feature/pinned");
1652+ });
1653+
1654+ it("pins manual workspace choices and can return to automatic routing without losing the prompt", () => {
1655+ const store = useComposerDraftStore.getState();
1656+ store.setProjectDraftThreadId(projectRef, draftId, { threadId });
1657+ store.setPrompt(draftId, "keep this prompt");
1658+ store.setDraftThreadContext(draftId, {
1659+ projectRef: remoteProjectRef,
1660+ environmentSelection: "auto",
1661+ loadBalancedEnvironmentId: OTHER_TEST_ENVIRONMENT_ID,
1662+ });
1663+ expect(store.getDraftThread(draftId)).toMatchObject({
1664+ environmentId: OTHER_TEST_ENVIRONMENT_ID,
1665+ environmentSelection: "auto",
1666+ loadBalancedEnvironmentId: OTHER_TEST_ENVIRONMENT_ID,
1667+ });
1668+ store.setDraftThreadContext(draftId, { branch: "feature/pinned" });
1669+ expect(store.getDraftThread(draftId)?.environmentSelection).toBe("manual");
1670+ store.setDraftThreadContext(draftId, {
1671+ branch: null,
1672+ environmentSelection: "auto",
1673+ loadBalancedEnvironmentId: null,
1674+ });
1675+ expect(store.getDraftThread(draftId)).toMatchObject({
1676+ branch: null,
1677+ environmentSelection: "auto",
1678+ loadBalancedEnvironmentId: null,
1679+ });
1680+ expect(store.getComposerDraft(draftId)?.prompt).toBe("keep this prompt");
1681+ });
1682+
16261683 it("clears branch and worktree but keeps env mode when changing a draft thread project ref", () => {
16271684 const store = useComposerDraftStore.getState();
16281685 store.setProjectDraftThreadId(projectRef, draftId, {
apps/web/src/composerDraftStore.ts+59−0
@@ -315,6 +315,8 @@ const PersistedDraftThreadState = Schema.Struct({ · 314 unmodified lines
315315 environmentId: Schema.String,
316316 projectId: ProjectId,
317317 logicalProjectKey: Schema.optionalKey(Schema.String),
318+ environmentSelection: Schema.optionalKey(Schema.Literals(["auto", "manual"])),
319+ loadBalancedEnvironmentId: Schema.optionalKey(Schema.NullOr(Schema.String)),
318320 createdAt: Schema.String,
319321 runtimeMode: RuntimeMode,
320322 interactionMode: ProviderInteractionMode,
@@ -427,6 +429,8 @@ export interface DraftSessionState { · 106 unmodified lines
427429 environmentId: EnvironmentId;
428430 projectId: ProjectId;
429431 logicalProjectKey: string;
432+ environmentSelection?: "auto" | "manual";
433+ loadBalancedEnvironmentId?: EnvironmentId | null;
430434 createdAt: string;
431435 runtimeMode: RuntimeMode;
432436 interactionMode: ProviderInteractionMode;
@@ -503,6 +507,8 @@ interface ComposerDraftStoreState { · 70 unmodified lines
503507 startFromOrigin?: boolean;
504508 runtimeMode?: RuntimeMode;
505509 interactionMode?: ProviderInteractionMode;
510+ environmentSelection?: "auto" | "manual";
511+ loadBalancedEnvironmentId?: EnvironmentId | null;
506512 },
507513 ) => void;
508514 /** Creates or updates the draft session tracked for a concrete project ref. */
@@ -518,6 +524,8 @@ interface ComposerDraftStoreState { · 9 unmodified lines
518524 startFromOrigin?: boolean;
519525 runtimeMode?: RuntimeMode;
520526 interactionMode?: ProviderInteractionMode;
527+ environmentSelection?: "auto" | "manual";
528+ loadBalancedEnvironmentId?: EnvironmentId | null;
521529 },
522530 ) => void;
523531 /** Updates mutable draft-session metadata without touching composer content. */
@@ -532,6 +540,8 @@ interface ComposerDraftStoreState { · 8 unmodified lines
532540 startFromOrigin?: boolean;
533541 runtimeMode?: RuntimeMode;
534542 interactionMode?: ProviderInteractionMode;
543+ environmentSelection?: "auto" | "manual";
544+ loadBalancedEnvironmentId?: EnvironmentId | null;
535545 },
536546 ) => void;
537547 clearProjectDraftThreadId: (projectRef: ScopedProjectRef) => void;
@@ -1534,6 +1544,8 @@ function createDraftThreadState( · 996 unmodified lines
15341544 startFromOrigin?: boolean;
15351545 runtimeMode?: RuntimeMode;
15361546 interactionMode?: ProviderInteractionMode;
1547+ environmentSelection?: "auto" | "manual";
1548+ loadBalancedEnvironmentId?: EnvironmentId | null;
15371549 },
15381550 ): DraftThreadState {
15391551 // A project change (including switching environments within a logical
@@ -1560,11 +1572,23 @@ function createDraftThreadState( · 20 unmodified lines
15601572 options?.startFromOrigin === undefined
15611573 ? (existingThread?.startFromOrigin ?? false)
15621574 : options.startFromOrigin;
1575+ const environmentSelection =
1576+ options?.environmentSelection ?? existingThread?.environmentSelection;
15631577 return {
15641578 threadId,
15651579 environmentId: projectRef.environmentId,
15661580 projectId: projectRef.projectId,
15671581 logicalProjectKey,
1582+ ...(environmentSelection ? { environmentSelection } : {}),
1583+ ...(options?.loadBalancedEnvironmentId !== undefined
1584+ ? { loadBalancedEnvironmentId: options.loadBalancedEnvironmentId }
1585+ : existingThread?.loadBalancedEnvironmentId !== undefined
1586+ ? {
1587+ loadBalancedEnvironmentId: projectChanged
1588+ ? null
1589+ : existingThread.loadBalancedEnvironmentId,
1590+ }
1591+ : {}),
15681592 createdAt: options?.createdAt ?? existingThread?.createdAt ?? new Date().toISOString(),
15691593 runtimeMode: options?.runtimeMode ?? existingThread?.runtimeMode ?? DEFAULT_RUNTIME_MODE,
15701594 interactionMode:
@@ -1599,6 +1623,8 @@ function draftThreadsEqual(left: DraftThreadState | undefined, right: DraftThrea · 28 unmodified lines
15991623 left.environmentId === right.environmentId &&
16001624 left.projectId === right.projectId &&
16011625 left.logicalProjectKey === right.logicalProjectKey &&
1626+ left.environmentSelection === right.environmentSelection &&
1627+ left.loadBalancedEnvironmentId === right.loadBalancedEnvironmentId &&
16021628 left.createdAt === right.createdAt &&
16031629 left.runtimeMode === right.runtimeMode &&
16041630 left.interactionMode === right.interactionMode &&
@@ -1754,6 +1780,16 @@ function normalizePersistedDraftThreads( · 149 unmodified lines
17541780 worktreePath: normalizedWorktreePath,
17551781 envMode: normalizeDraftThreadEnvMode(candidateDraftThread.envMode, normalizedWorktreePath),
17561782 startFromOrigin,
1783+ ...(candidateDraftThread.environmentSelection === "manual" ||
1784+ candidateDraftThread.environmentSelection === "auto"
1785+ ? { environmentSelection: candidateDraftThread.environmentSelection }
1786+ : {}),
1787+ ...(typeof candidateDraftThread.loadBalancedEnvironmentId === "string" &&
1788+ candidateDraftThread.loadBalancedEnvironmentId.length > 0
1789+ ? { loadBalancedEnvironmentId: candidateDraftThread.loadBalancedEnvironmentId }
1790+ : candidateDraftThread.loadBalancedEnvironmentId === null
1791+ ? { loadBalancedEnvironmentId: null }
1792+ : {}),
17571793 promotedTo,
17581794 };
17591795 }
@@ -2453,6 +2489,15 @@ function toHydratedDraftThreadState( · 693 unmodified lines
24532489 worktreePath: persistedDraftThread.worktreePath,
24542490 envMode: persistedDraftThread.envMode,
24552491 startFromOrigin: persistedDraftThread.startFromOrigin,
2492+ ...(persistedDraftThread.environmentSelection
2493+ ? { environmentSelection: persistedDraftThread.environmentSelection }
2494+ : {}),
2495+ ...(persistedDraftThread.loadBalancedEnvironmentId !== undefined
2496+ ? {
2497+ loadBalancedEnvironmentId:
2498+ persistedDraftThread.loadBalancedEnvironmentId as EnvironmentId | null,
2499+ }
2500+ : {}),
24562501 promotedTo: persistedDraftThread.promotedTo
24572502 ? scopeThreadRef(
24582503 persistedDraftThread.promotedTo.environmentId as EnvironmentId,
@@ -2707,11 +2752,23 @@ const composerDraftStore = create<ComposerDraftStoreState>()( · 248 unmodified lines
27072752 options.startFromOrigin === undefined
27082753 ? existing.startFromOrigin
27092754 : options.startFromOrigin;
2755+ const environmentSelection =
2756+ options.environmentSelection ??
2757+ (options.branch != null || options.worktreePath != null
2758+ ? "manual"
2759+ : existing.environmentSelection);
27102760 const nextDraftThread: DraftThreadState = {
27112761 threadId: existing.threadId,
27122762 environmentId: nextProjectRef.environmentId,
27132763 projectId: nextProjectRef.projectId,
27142764 logicalProjectKey: existing.logicalProjectKey,
2765+ ...(environmentSelection ? { environmentSelection } : {}),
2766+ loadBalancedEnvironmentId:
2767+ options.loadBalancedEnvironmentId === undefined
2768+ ? projectChanged
2769+ ? null
2770+ : (existing.loadBalancedEnvironmentId ?? null)
2771+ : options.loadBalancedEnvironmentId,
27152772 createdAt:
27162773 options.createdAt === undefined
27172774 ? existing.createdAt
@@ -2729,6 +2786,8 @@ const composerDraftStore = create<ComposerDraftStoreState>()( · 11 unmodified lines
27292786 nextDraftThread.environmentId === existing.environmentId &&
27302787 nextDraftThread.projectId === existing.projectId &&
27312788 nextDraftThread.logicalProjectKey === existing.logicalProjectKey &&
2789+ nextDraftThread.environmentSelection === existing.environmentSelection &&
2790+ nextDraftThread.loadBalancedEnvironmentId === existing.loadBalancedEnvironmentId &&
27322791 nextDraftThread.createdAt === existing.createdAt &&
27332792 nextDraftThread.runtimeMode === existing.runtimeMode &&
27342793 nextDraftThread.interactionMode === existing.interactionMode &&
apps/web/src/hooks/useLoadBalancedEnvironment.ts+50−0
@@ -0,0 +1,50 @@
1+import { RegistryContext, useAtomValue } from "@effect/atom-react";
2+import { chooseLoadBalancedEnvironment } from "@t3tools/client-runtime/load-balancing";
3+import type { EnvironmentId } from "@t3tools/contracts";
4+import { Atom } from "effect/unstable/reactivity";
5+import { useCallback, useContext, useMemo } from "react";
6+
7+import { serverEnvironment } from "../state/server";
8+
9+/** Only mounted for unresolved automatic drafts, so idle clients do not poll hosts. */
10+export function useLoadBalancedEnvironment(
11+ environmentIds: readonly EnvironmentId[],
12+ weights: Readonly<Record<string, number>>,
13+) {
14+ const registry = useContext(RegistryContext);
15+ const refresh = useCallback(
16+ (ids: readonly EnvironmentId[]) => {
17+ for (const environmentId of ids) {
18+ registry.refresh(serverEnvironment.hostResources({ environmentId, input: {} }));
19+ }
20+ },
21+ [registry],
22+ );
23+ const resourcesAtom = useMemo(
24+ () =>
25+ Atom.make((get) =>
26+ environmentIds.map((environmentId) => {
27+ const result = get(serverEnvironment.hostResources({ environmentId, input: {} }));
28+ return {
29+ environmentId,
30+ resources: result._tag === "Success" ? result.value : null,
31+ receivedAt: result._tag === "Success" ? result.timestamp : 0,
32+ pending: result._tag === "Initial" || result.waiting,
33+ };
34+ }),
35+ ),
36+ [environmentIds],
37+ );
38+ const resources = useAtomValue(resourcesAtom);
39+ return {
40+ refresh,
41+ pending: resources.some((resource) => resource.pending),
42+ environmentId: chooseLoadBalancedEnvironment(
43+ resources.map((resource) => ({
44+ ...resource,
45+ weight: weights[resource.environmentId] ?? 50,
46+ })),
47+ Date.now(),
48+ ) as EnvironmentId | null,
49+ };
50+}
docs/user/remote-access.md+17−0
@@ -61,6 +61,23 @@ created in Settings can only be copied from the client that created them while · 60 unmodified lines
6161 its Connections page stays open. If you leave or reload that page, create
6262 another link to share.
6363
64+### Balance new threads across machines
65+
66+Auto balance is off by default. On web and desktop, enable it in
67+**Settings → Connections → Load balancing** to automatically choose a machine for
68+new threads in projects grouped across connected environments.
69+Each machine starts at **Normal**. Choose **Prefer** to favor it when it has CPU and
70+memory available, **Less often** to reduce its share, or **Manual only** to exclude
71+it from automatic selection. These are preferences, not fixed traffic percentages.
72+Preferences are saved separately in each client.
73+
74+The composer checks eligible machines when choosing a draft's environment, then keeps
75+that choice stable. Choose **Auto balance** again to check current resources, or choose
76+a specific machine to override it. Choosing a branch or worktree also keeps the draft
77+on that machine. Existing threads stay where they started. If resource checks are
78+unavailable or all eligible machines are full, choose a machine manually to continue.
79+Mobile keeps its manual environment selection.
80+
6481 ### Tailscale HTTPS
6582
6683 Join both devices to the same tailnet. In the desktop app, enable **Tailscale
packages/client-runtime/package.json+4−0
@@ -3,6 +3,10 @@ · 2 unmodified lines
33 "private": true,
44 "type": "module",
55 "exports": {
6+ "./load-balancing": {
7+ "types": "./src/load-balancing.ts",
8+ "default": "./src/load-balancing.ts"
9+ },
610 "./project-favicon-cache": {
711 "types": "./src/projectFaviconCache.ts",
812 "default": "./src/projectFaviconCache.ts"
packages/client-runtime/src/load-balancing.ts+40−0
@@ -0,0 +1,40 @@
1+import type { HostResourcesSnapshot } from "@t3tools/contracts";
2+
3+/** Callers supply only connected machines hosting the project and selected provider. */
4+export function chooseLoadBalancedEnvironment(
5+ candidates: ReadonlyArray<{
6+ environmentId: string;
7+ resources: HostResourcesSnapshot | null;
8+ /** Client receipt time avoids comparing clocks on different machines. */
9+ receivedAt?: number;
10+ weight: number;
11+ }>,
12+ now: number,
13+): string | null {
14+ let selected: string | null = null;
15+ let bestScore = 0;
16+ for (const { environmentId, resources, receivedAt, weight } of candidates) {
17+ const sampledAt = receivedAt ?? resources?.sampledAt ?? 0;
18+ if (
19+ !resources ||
20+ !Number.isFinite(weight) ||
21+ weight <= 0 ||
22+ now - sampledAt > 15_000 ||
23+ sampledAt > now + 5_000 ||
24+ resources.cpuUtilization === null ||
25+ resources.cpuUtilization >= 0.95 ||
26+ resources.totalMemoryBytes <= 0 ||
27+ resources.cpuCount <= 0
28+ ) {
29+ continue;
30+ }
31+ const memoryAvailable = resources.availableMemoryBytes / resources.totalMemoryBytes;
32+ if (memoryAvailable <= 0.05) continue;
33+ const score = weight * resources.cpuCount * (1 - resources.cpuUtilization) * memoryAvailable;
34+ if (score > bestScore) {
35+ selected = environmentId;
36+ bestScore = score;
37+ }
38+ }
39+ return selected;
40+}
packages/client-runtime/src/state/projectGrouping.test.ts+65−0
@@ -2,6 +2,7 @@ import { EnvironmentId, ProjectId } from "@t3tools/contracts"; · 1 unmodified line
22 import { describe, expect, it } from "vite-plus/test";
33
44 import type { EnvironmentProject } from "./models.ts";
5+import { chooseLoadBalancedEnvironment } from "../load-balancing.ts";
56 import {
67 buildProjectGroups,
78 derivePhysicalProjectKey,
@@ -9,6 +10,70 @@ import { · 1 unmodified line
910 } from "./projectGrouping.ts";
1011
1112 const environmentId = EnvironmentId.make("environment");
13+
14+describe("load balancing shared project machines", () => {
15+ const now = 100_000;
16+ const resources = {
17+ sampledAt: now,
18+ cpuUtilization: 0.2,
19+ cpuCount: 8,
20+ availableMemoryBytes: 8_000,
21+ totalMemoryBytes: 16_000,
22+ };
23+
24+ it("compares three machines using free capacity and preference", () => {
25+ const candidates = [
26+ { environmentId: "busy", resources: { ...resources, cpuUtilization: 0.9 }, weight: 1 },
27+ { environmentId: "idle", resources, weight: 1 },
28+ { environmentId: "preferred", resources: { ...resources, cpuCount: 4 }, weight: 3 },
29+ ];
30+ expect(chooseLoadBalancedEnvironment(candidates, now)).toBe("preferred");
31+ expect(chooseLoadBalancedEnvironment(candidates.slice(0, 2), now)).toBe("idle");
32+ });
33+
34+ it("rejects stale, unknown, excluded and saturated machines", () => {
35+ expect(
36+ chooseLoadBalancedEnvironment(
37+ [
38+ {
39+ environmentId: "stale",
40+ resources: { ...resources, sampledAt: now - 15_001 },
41+ weight: 1,
42+ },
43+ { environmentId: "unknown", resources: null, weight: 1 },
44+ {
45+ environmentId: "no-cpu-sample",
46+ resources: { ...resources, cpuUtilization: null },
47+ weight: 1,
48+ },
49+ { environmentId: "excluded", resources, weight: 0 },
50+ {
51+ environmentId: "cpu-full",
52+ resources: { ...resources, cpuUtilization: 0.95 },
53+ weight: 1,
54+ },
55+ {
56+ environmentId: "memory-full",
57+ resources: { ...resources, availableMemoryBytes: 100 },
58+ weight: 1,
59+ },
60+ ],
61+ now,
62+ ),
63+ ).toBeNull();
64+ });
65+
66+ it("uses client receipt time when host clocks differ", () => {
67+ const candidate = {
68+ environmentId: "different-clock",
69+ resources: { ...resources, sampledAt: now + 60_000 },
70+ receivedAt: now,
71+ weight: 1,
72+ };
73+ expect(chooseLoadBalancedEnvironment([candidate], now)).toBe("different-clock");
74+ expect(chooseLoadBalancedEnvironment([candidate], now + 15_001)).toBeNull();
75+ });
76+});
1277 const repositoryIdentity = {
1378 canonicalKey: "github.com/t3tools/t3code",
1479 locator: {
packages/client-runtime/src/state/server.ts+7−0
@@ -26,6 +26,7 @@ import { AsyncResult, Atom } from "effect/unstable/reactivity"; · 25 unmodified lines
2626 import {
2727 createAtomCommandScheduler,
2828 createEnvironmentRpcCommand,
29+ createEnvironmentQueryAtomFamily,
2930 createEnvironmentRpcQueryAtomFamily,
3031 createEnvironmentRpcSubscriptionAtomFamily,
3132 createRuntimeCommand,
@@ -1018,6 +1019,12 @@ export function createServerEnvironmentAtoms<R, E>( · 986 unmodified lines
10181019 label: "environment-data:server:process-diagnostics",
10191020 tag: WS_METHODS.serverGetProcessDiagnostics,
10201021 }),
1022+ hostResources: createEnvironmentQueryAtomFamily(runtime, {
1023+ label: "environment-data:server:host-resources",
1024+ staleTimeMs: 5_000,
1025+ execute: (input: EnvironmentRpcInput<typeof WS_METHODS.serverGetHostResources>) =>
1026+ request(WS_METHODS.serverGetHostResources, input).pipe(Effect.timeout("5 seconds")),
1027+ }),
10211028 processResourceHistory: createEnvironmentRpcQueryAtomFamily(runtime, {
10221029 label: "environment-data:server:process-resource-history",
10231030 tag: WS_METHODS.serverGetProcessResourceHistory,
packages/contracts/src/resourceTelemetry.ts+10−0
@@ -6,6 +6,16 @@ import { DesktopUpdateStateSchema } from "./ipc.ts"; · 5 unmodified lines
66
77 export const RESOURCE_MONITOR_PROTOCOL_VERSION = 2 as const;
88
9+/** Whole-host capacity, independent of T3's process diagnostics. */
10+export const HostResourcesSnapshot = Schema.Struct({
11+ sampledAt: NonNegativeInt,
12+ cpuUtilization: Schema.NullOr(Schema.Number.check(Schema.isBetween({ minimum: 0, maximum: 1 }))),
13+ cpuCount: NonNegativeInt,
14+ availableMemoryBytes: NonNegativeInt,
15+ totalMemoryBytes: NonNegativeInt,
16+});
17+export type HostResourcesSnapshot = typeof HostResourcesSnapshot.Type;
18+
919 export const ResourceTelemetryIoSemantics = Schema.Literals([
1020 "storage",
1121 "logical",
packages/contracts/src/rpc.ts+9−0
@@ -210,6 +210,7 @@ import { · 209 unmodified lines
210210 ServerUpsertKeybindingResult,
211211 } from "./server.ts";
212212 import {
213+ HostResourcesSnapshot,
213214 ResourceTelemetryHistory,
214215 ResourceTelemetryHistoryInput,
215216 ResourceTelemetryRetryResult,
@@ -323,6 +324,7 @@ export const WS_METHODS = { · 107 unmodified lines
323324 serverDiscoverSourceControl: "server.discoverSourceControl",
324325 serverGetTraceDiagnostics: "server.getTraceDiagnostics",
325326 serverGetProcessDiagnostics: "server.getProcessDiagnostics",
327+ serverGetHostResources: "server.getHostResources",
326328 serverGetProcessResourceHistory: "server.getProcessResourceHistory",
327329 serverGetResourceTelemetryHistory: "server.getResourceTelemetryHistory",
328330 serverRetryResourceTelemetry: "server.retryResourceTelemetry",
@@ -538,6 +540,12 @@ const WsServerGetProcessDiagnosticsRpc = Rpc.make(WS_METHODS.serverGetProcessDia · 209 unmodified lines
538540 error: EnvironmentAuthorizationError,
539541 });
540542
543+const WsServerGetHostResourcesRpc = Rpc.make(WS_METHODS.serverGetHostResources, {
544+ payload: Schema.Struct({}),
545+ success: HostResourcesSnapshot,
546+ error: EnvironmentAuthorizationError,
547+});
548+
541549 const WsServerGetProcessResourceHistoryRpc = Rpc.make(WS_METHODS.serverGetProcessResourceHistory, {
542550 payload: ServerProcessResourceHistoryInput,
543551 success: ServerProcessResourceHistoryResult,
@@ -1197,6 +1205,7 @@ export const WsRpcGroup = RpcGroup.make( · 653 unmodified lines
11971205 WsServerDiscoverSourceControlRpc,
11981206 WsServerGetTraceDiagnosticsRpc,
11991207 WsServerGetProcessDiagnosticsRpc,
1208+ WsServerGetHostResourcesRpc,
12001209 WsServerGetProcessResourceHistoryRpc,
12011210 WsServerGetResourceTelemetryHistoryRpc,
12021211 WsServerRetryResourceTelemetryRpc,
packages/contracts/src/settings.test.ts+15−0
@@ -135,6 +135,21 @@ describe("ClaudeSettings auto-compaction", () => { · 134 unmodified lines
135135 });
136136 });
137137
138+describe("ClientSettings load balancing", () => {
139+ it("requires opt-in when settings are new or omit load balancing", () => {
140+ expect(decodeClientSettings({}).loadBalancingEnabled).toBe(false);
141+ expect(decodeClientSettings({ loadBalancingWeights: {} }).loadBalancingEnabled).toBe(false);
142+ });
143+
144+ it.each([true, false])("preserves a saved choice of %s", (loadBalancingEnabled) => {
145+ const settings = decodeClientSettings({ loadBalancingEnabled });
146+ expect(encodeClientSettings(settings).loadBalancingEnabled).toBe(loadBalancingEnabled);
147+ expect(decodeClientSettingsPatch({ loadBalancingEnabled }).loadBalancingEnabled).toBe(
148+ loadBalancingEnabled,
149+ );
150+ });
151+});
152+
138153 describe("ClientSettings word wrap", () => {
139154 it("defaults word wrap on", () => {
140155 expect(decodeClientSettings({}).wordWrap).toBe(true);
packages/contracts/src/settings.ts+9−0
@@ -204,7 +204,14 @@ export const BrowserLinkTarget = Schema.Literals(["system", "app"]); · 203 unmodified lines
204204 export type BrowserLinkTarget = typeof BrowserLinkTarget.Type;
205205 export const DEFAULT_BROWSER_LINK_TARGET: BrowserLinkTarget = "system";
206206
207+export const LoadBalancingWeights = Schema.Record(
208+ TrimmedNonEmptyString,
209+ Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 100 })),
210+);
211+
207212 export const ClientSettingsSchema = Schema.Struct({
213+ loadBalancingEnabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
214+ loadBalancingWeights: LoadBalancingWeights.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
208215 appearanceContrast: AppearanceContrast.pipe(
209216 Schema.withDecodingDefault(Effect.succeed(DEFAULT_APPEARANCE_CONTRAST)),
210217 ),
@@ -1210,6 +1217,8 @@ export const ServerSettingsPatch = Schema.Struct({ · 999 unmodified lines
12101217 export type ServerSettingsPatch = typeof ServerSettingsPatch.Type;
12111218
12121219 export const ClientSettingsPatch = Schema.Struct({
1220+ loadBalancingEnabled: Schema.optionalKey(Schema.Boolean),
1221+ loadBalancingWeights: Schema.optionalKey(LoadBalancingWeights),
12131222 appearanceContrast: Schema.optionalKey(AppearanceContrast),
12141223 panelAnimationDurationMs: Schema.optionalKey(PanelAnimationDurationMs),
12151224 browserDefaultViewport: Schema.optionalKey(PreviewViewportSetting),

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t