Skip to content

Commit d0514c4

Browse files
committed
refactor(settings): share sync target eligibility
1 parent 024b9ca commit d0514c4

8 files changed

Lines changed: 119 additions & 107 deletions

File tree

‎apps/mobile/src/features/settings/SettingsRouteScreen.logic.test.ts‎

Lines changed: 1 addition & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,6 @@
11
import { describe, expect, it } from "vite-plus/test";
22

3-
import {
4-
resolveAgentAwarenessPlatformPresentation,
5-
supportsSharedSettingsSync,
6-
} from "./SettingsRouteScreen.logic";
7-
8-
describe("supportsSharedSettingsSync", () => {
9-
it("accepts only connected servers that advertise the shared-settings capability", () => {
10-
expect(
11-
supportsSharedSettingsSync({
12-
connectionPhase: "connected",
13-
capabilities: { threadAutoSettlement: true },
14-
}),
15-
).toBe(true);
16-
expect(supportsSharedSettingsSync({ connectionPhase: "connected", capabilities: {} })).toBe(
17-
false,
18-
);
19-
expect(
20-
supportsSharedSettingsSync({
21-
connectionPhase: "reconnecting",
22-
capabilities: { threadAutoSettlement: true },
23-
}),
24-
).toBe(false);
25-
});
26-
});
3+
import { resolveAgentAwarenessPlatformPresentation } from "./SettingsRouteScreen.logic";
274

285
describe("resolveAgentAwarenessPlatformPresentation", () => {
296
it("explains that agent awareness settings are unavailable on Android", () => {

‎apps/mobile/src/features/settings/SettingsRouteScreen.logic.ts‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,3 @@
1-
import type { EnvironmentConnectionPhase } from "@t3tools/client-runtime/connection";
2-
import type { ExecutionEnvironmentCapabilities } from "@t3tools/contracts";
3-
4-
export function supportsSharedSettingsSync(input: {
5-
readonly connectionPhase: EnvironmentConnectionPhase;
6-
readonly capabilities: Pick<ExecutionEnvironmentCapabilities, "threadAutoSettlement"> | null;
7-
}): boolean {
8-
return input.connectionPhase === "connected" && input.capabilities?.threadAutoSettlement === true;
9-
}
10-
111
export function resolveAgentAwarenessPlatformPresentation(platform: string): {
122
readonly supported: boolean;
133
readonly subtitle: string | undefined;

‎apps/mobile/src/features/settings/SettingsRouteScreen.tsx‎

Lines changed: 10 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ import {
4646
import {
4747
findSharedSettingsMismatches,
4848
pickSharedServerSettings,
49+
supportsSharedSettingsSync,
4950
} from "@t3tools/client-runtime/state/shared-settings";
5051
import { useThreadListV2Enabled } from "../threads/use-thread-list-v2-enabled";
5152
import {
@@ -58,10 +59,7 @@ import { useSavedRemoteConnections } from "../../state/use-remote-environment-re
5859
import { SettingsRow } from "./components/SettingsRow";
5960
import { SettingsSection } from "./components/SettingsSection";
6061
import { SettingsSwitchRow } from "./components/SettingsSwitchRow";
61-
import {
62-
resolveAgentAwarenessPlatformPresentation,
63-
supportsSharedSettingsSync,
64-
} from "./SettingsRouteScreen.logic";
62+
import { resolveAgentAwarenessPlatformPresentation } from "./SettingsRouteScreen.logic";
6563

6664
type NotificationStatus = "checking" | "enabled" | "disabled" | "unsupported";
6765
type LiveActivityStatus = "checking" | "enabled" | "disabled" | "signed-out" | "linking";
@@ -556,9 +554,9 @@ const AUTO_SETTLE_DEFAULT_DAYS = DEFAULT_SERVER_SETTINGS.sidebarAutoSettleAfterD
556554

557555
/**
558556
* Auto-settlement is a user preference that every server has to hold. Mobile
559-
* has no primary environment, so the first connected environment that
560-
* supports it is the reference value. Edits fan out to every connected
561-
* environment, and a mismatch row lets the user push the reference out.
557+
* has no primary environment, so the first eligible sync target provides the
558+
* reference value. Edits fan out to every eligible target, and a mismatch row
559+
* lets the user push the reference out.
562560
*/
563561
function AutoSettleSettingsRows() {
564562
const { environments } = useEnvironments();
@@ -567,13 +565,8 @@ function AutoSettleSettingsRows() {
567565
reportFailure: true,
568566
});
569567

570-
const supportsSharedSettings = (environment: (typeof environments)[number]) =>
571-
supportsSharedSettingsSync({
572-
connectionPhase: environment.connection.phase,
573-
capabilities: environment.serverConfig?.environment.capabilities ?? null,
574-
});
575-
const connected = environments.filter(supportsSharedSettings);
576-
const reference = connected[0] ?? null;
568+
const syncTargets = environments.filter(supportsSharedSettingsSync);
569+
const reference = syncTargets[0] ?? null;
577570
const referenceSettings = reference?.serverConfig?.settings ?? null;
578571

579572
const [daysDraft, setDaysDraft] = useState<string | null>(null);
@@ -583,7 +576,7 @@ function AutoSettleSettingsRows() {
583576
}
584577

585578
const writeToAll = (patch: ServerSettingsPatch) => {
586-
for (const environment of connected) {
579+
for (const environment of syncTargets) {
587580
void updateSettings({ environmentId: environment.environmentId, input: { patch } });
588581
}
589582
};
@@ -594,7 +587,7 @@ function AutoSettleSettingsRows() {
594587
environments: environments.map((environment) => ({
595588
environmentId: environment.environmentId,
596589
label: environment.label,
597-
connected: supportsSharedSettings(environment),
590+
syncEligible: supportsSharedSettingsSync(environment),
598591
settings: environment.serverConfig?.settings ?? null,
599592
})),
600593
});
@@ -604,7 +597,7 @@ function AutoSettleSettingsRows() {
604597
const draft = (daysDraft ?? "").trim();
605598
setDaysDraft(null);
606599
// Whole-string check so "3.5" and "3days" are rejected instead of
607-
// silently becoming 3 on every connected environment.
600+
// silently becoming 3 on every eligible sync target.
608601
const parsed = /^\d+$/.test(draft) ? Number(draft) : Number.NaN;
609602
if (
610603
Number.isInteger(parsed) &&

‎apps/web/src/hooks/useSettings.ts‎

Lines changed: 15 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ import {
2929
findSharedSettingsMismatches,
3030
pickSharedServerSettings,
3131
splitSharedServerPatch,
32+
supportsSharedSettingsSync,
3233
} from "@t3tools/client-runtime/state/shared-settings";
3334
import { ensureLocalApi } from "~/localApi";
3435
import {
@@ -42,11 +43,7 @@ import * as Struct from "effect/Struct";
4243
import { toastManager } from "~/components/ui/toast";
4344
import { isHostedStaticApp } from "~/hostedPairing";
4445
import { primaryServerSettingsAtom, serverEnvironment } from "~/state/server";
45-
import {
46-
type EnvironmentPresentation,
47-
useEnvironments,
48-
usePrimaryEnvironment,
49-
} from "~/state/environments";
46+
import { useEnvironments, usePrimaryEnvironment } from "~/state/environments";
5047
import { useAtomCommand } from "~/state/use-atom-command";
5148
import { useTheme } from "./useTheme";
5249

@@ -332,26 +329,14 @@ export function usePrimarySettingsAvailable(): boolean {
332329
return primaryEnvironment !== null || !isHostedStaticApp();
333330
}
334331

335-
/**
336-
* Whether an environment can hold every shared key right now. Gated on the
337-
* auto-settlement capability because it is the newest of the shared keys: a
338-
* server that has it has all of them. Older servers drop unknown keys on
339-
* write, so a mismatch against them could never clear, and their decoded
340-
* defaults must not be treated as real values.
341-
*/
342-
function supportsSharedSettings(environment: EnvironmentPresentation): boolean {
343-
return (
344-
environment.connection.phase === "connected" &&
345-
environment.serverConfig?.environment.capabilities.threadAutoSettlement === true
346-
);
347-
}
348-
349332
/** Environments that can receive a shared settings write right now. */
350-
function useConnectedEnvironmentIds(): ReadonlyArray<EnvironmentId> {
333+
function useSharedSettingsSyncTargetIds(): ReadonlyArray<EnvironmentId> {
351334
const { environments } = useEnvironments();
352335
return useMemo(
353336
() =>
354-
environments.filter(supportsSharedSettings).map((environment) => environment.environmentId),
337+
environments
338+
.filter(supportsSharedSettingsSync)
339+
.map((environment) => environment.environmentId),
355340
[environments],
356341
);
357342
}
@@ -361,16 +346,16 @@ function useConnectedEnvironmentIds(): ReadonlyArray<EnvironmentId> {
361346
*
362347
* Server keys are optimistically patched in atom-backed server state, then
363348
* persisted via RPC. Shared server keys (see `SHARED_SERVER_SETTING_KEYS`)
364-
* are written to every connected environment, not only the target, so a user
365-
* preference does not silently drift between machines. Client keys go through
366-
* client persistence.
349+
* are written to every eligible sync target, not only the selected target, so
350+
* a user preference does not silently drift between machines. Client keys go
351+
* through client persistence.
367352
*/
368353
function useUpdateSettingsTarget(environmentId: EnvironmentId | null) {
369354
const persistServerSettings = useAtomCommand(
370355
serverEnvironment.updateSettings,
371356
"server settings update",
372357
);
373-
const connectedEnvironmentIds = useConnectedEnvironmentIds();
358+
const sharedSettingsSyncTargetIds = useSharedSettingsSyncTargetIds();
374359
const updateSettings = useCallback(
375360
(patch: UnifiedSettingsPatch) => {
376361
const { serverPatch, clientPatch } = splitPatch(patch);
@@ -395,7 +380,7 @@ function useUpdateSettingsTarget(environmentId: EnvironmentId | null) {
395380
}
396381
}
397382
if (Object.keys(sharedPatch).length > 0) {
398-
const targets = new Set(connectedEnvironmentIds);
383+
const targets = new Set(sharedSettingsSyncTargetIds);
399384
if (environmentId) {
400385
targets.add(environmentId);
401386
}
@@ -417,14 +402,14 @@ function useUpdateSettingsTarget(environmentId: EnvironmentId | null) {
417402
});
418403
}
419404
},
420-
[connectedEnvironmentIds, environmentId, persistServerSettings],
405+
[environmentId, persistServerSettings, sharedSettingsSyncTargetIds],
421406
);
422407

423408
return updateSettings;
424409
}
425410

426411
/**
427-
* Connected environments whose shared settings differ from the primary's,
412+
* Shared-settings sync targets whose values differ from the primary's,
428413
* plus an action that writes the primary's values to all of them. Drift
429414
* happens when an environment was offline during an edit or was changed by
430415
* an older client.
@@ -437,7 +422,7 @@ export function useSharedSettingsSync() {
437422
// must never push defaults over real values. Same for a primary too old to
438423
// hold the shared keys: its decoded defaults are not a source of truth.
439424
const primarySettings =
440-
primaryEnvironment !== null && supportsSharedSettings(primaryEnvironment)
425+
primaryEnvironment !== null && supportsSharedSettingsSync(primaryEnvironment)
441426
? (primaryEnvironment.serverConfig?.settings ?? null)
442427
: null;
443428
const { environments } = useEnvironments();
@@ -454,7 +439,7 @@ export function useSharedSettingsSync() {
454439
environments: environments.map((environment) => ({
455440
environmentId: environment.environmentId,
456441
label: environment.label,
457-
connected: supportsSharedSettings(environment),
442+
syncEligible: supportsSharedSettingsSync(environment),
458443
settings: environment.serverConfig?.settings ?? null,
459444
})),
460445
}),

‎docs/internals/overview.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -90,9 +90,10 @@ A turn is complete when its session leaves `running` status, projected by
9090
does not define turn end.
9191

9292
Thread settlement is server-owned. Each server's own settings control PR and inactivity
93-
settlement. Those keys are user preferences, so clients write them to every connected environment
94-
(`SHARED_SERVER_SETTING_KEYS` in `packages/client-runtime/src/state/sharedSettings.ts`) and warn
95-
when a connected environment drifts.
93+
settlement. Those keys are user preferences, so clients write them to every shared-settings sync
94+
target (`SHARED_SERVER_SETTING_KEYS` in `packages/client-runtime/src/state/sharedSettings.ts`) and
95+
warn when another target drifts. A target must have an active connection and advertise the
96+
`threadAutoSettlement` capability, which signals that the server can hold every shared key.
9697
[`ThreadSettlementReactor`][settlement] checks threads at startup, when those settings change, and
9798
once per minute, including when no client is connected. It dispatches the guarded internal
9899
`thread.auto-settle` command, which uses the existing settlement event lifecycle. Automatic

‎docs/user/thread-sidebar.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,11 @@ available, the inactivity rule still applies. A manual un-settle also keeps the
2222
sorts by the moment you settled it. A thread that settled on its own sorts by its last message or
2323
turn, not by when the server noticed it was inactive.
2424

25-
Change these rules in **Settings > General**. The change is written to every environment you are
26-
connected to at that moment. An environment that is offline keeps its old value. When a connected
27-
environment holds a different value, **Settings > General** shows a warning that names it. Choose
28-
**Apply to all** to write your current values to every connected environment. The same applies to
25+
Change these rules in **Settings > General**. The change is written to every connected environment
26+
whose server supports shared settings. An environment that is offline or needs a server update
27+
keeps its old value. When one of those environments holds a different value,
28+
**Settings > General** shows a warning that names it. Choose **Apply to all** to write your current
29+
values to every environment that is connected and supports shared settings. The same applies to
2930
the new-thread workspace mode and the source control writing style.
3031

3132
A settings change affects future settlement and does not reopen a settled thread. Settings saved

‎packages/client-runtime/src/state/sharedSettings.test.ts‎

Lines changed: 48 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,36 @@ import {
55
findSharedSettingsMismatches,
66
pickSharedServerSettings,
77
splitSharedServerPatch,
8+
supportsSharedSettingsSync,
89
} from "./sharedSettings.ts";
910

1011
const primaryId = EnvironmentId.make("env-primary");
1112
const laptopId = EnvironmentId.make("env-laptop");
1213
const boxId = EnvironmentId.make("env-box");
1314

15+
describe("supportsSharedSettingsSync", () => {
16+
it("accepts only connected servers that advertise the shared-settings capability", () => {
17+
expect(
18+
supportsSharedSettingsSync({
19+
connection: { phase: "connected" },
20+
serverConfig: { environment: { capabilities: { threadAutoSettlement: true } } },
21+
}),
22+
).toBe(true);
23+
expect(
24+
supportsSharedSettingsSync({
25+
connection: { phase: "connected" },
26+
serverConfig: { environment: { capabilities: {} } },
27+
}),
28+
).toBe(false);
29+
expect(
30+
supportsSharedSettingsSync({
31+
connection: { phase: "reconnecting" },
32+
serverConfig: { environment: { capabilities: { threadAutoSettlement: true } } },
33+
}),
34+
).toBe(false);
35+
});
36+
});
37+
1438
describe("splitSharedServerPatch", () => {
1539
it("routes preference keys to the shared patch and machine keys to the local patch", () => {
1640
const { sharedPatch, localPatch } = splitSharedServerPatch({
@@ -38,17 +62,27 @@ describe("pickSharedServerSettings", () => {
3862
describe("findSharedSettingsMismatches", () => {
3963
const primarySettings = { ...DEFAULT_SERVER_SETTINGS, sidebarAutoSettleAfterDays: 7 };
4064

41-
it("lists connected environments whose shared settings differ", () => {
65+
it("lists sync-eligible environments whose shared settings differ", () => {
4266
const mismatches = findSharedSettingsMismatches({
4367
primaryEnvironmentId: primaryId,
4468
primarySettings,
4569
environments: [
46-
{ environmentId: primaryId, label: "Desktop", connected: true, settings: primarySettings },
47-
{ environmentId: laptopId, label: "Laptop", connected: true, settings: primarySettings },
70+
{
71+
environmentId: primaryId,
72+
label: "Desktop",
73+
syncEligible: true,
74+
settings: primarySettings,
75+
},
76+
{
77+
environmentId: laptopId,
78+
label: "Laptop",
79+
syncEligible: true,
80+
settings: primarySettings,
81+
},
4882
{
4983
environmentId: boxId,
5084
label: "Remote Box",
51-
connected: true,
85+
syncEligible: true,
5286
settings: DEFAULT_SERVER_SETTINGS,
5387
},
5488
],
@@ -64,7 +98,7 @@ describe("findSharedSettingsMismatches", () => {
6498
{
6599
environmentId: boxId,
66100
label: "Remote Box",
67-
connected: true,
101+
syncEligible: true,
68102
settings: { ...primarySettings, enableAgentBrowserAccess: false },
69103
},
70104
],
@@ -74,7 +108,12 @@ describe("findSharedSettingsMismatches", () => {
74108

75109
it("reports nothing until the primary environment's settings are loaded", () => {
76110
const environments = [
77-
{ environmentId: boxId, label: "Remote Box", connected: true, settings: primarySettings },
111+
{
112+
environmentId: boxId,
113+
label: "Remote Box",
114+
syncEligible: true,
115+
settings: primarySettings,
116+
},
78117
];
79118
expect(
80119
findSharedSettingsMismatches({ primaryEnvironmentId: null, primarySettings, environments }),
@@ -88,18 +127,18 @@ describe("findSharedSettingsMismatches", () => {
88127
).toEqual([]);
89128
});
90129

91-
it("skips offline environments and environments without a loaded config", () => {
130+
it("skips ineligible environments and environments without a loaded config", () => {
92131
const mismatches = findSharedSettingsMismatches({
93132
primaryEnvironmentId: primaryId,
94133
primarySettings,
95134
environments: [
96135
{
97136
environmentId: laptopId,
98137
label: "Laptop",
99-
connected: false,
138+
syncEligible: false,
100139
settings: DEFAULT_SERVER_SETTINGS,
101140
},
102-
{ environmentId: boxId, label: "Remote Box", connected: true, settings: null },
141+
{ environmentId: boxId, label: "Remote Box", syncEligible: true, settings: null },
103142
],
104143
});
105144
expect(mismatches).toEqual([]);

0 commit comments

Comments
 (0)