Skip to content

Commit 67c3afb

Browse files
t3dotggclaude
andauthored
perf(shell): cold connects skip idle subagent threads, a third of the thread list (pingdotgg#24648)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 074d9e4 commit 67c3afb

35 files changed

Lines changed: 1233 additions & 49 deletions

‎apps/mobile/src/features/threads/ThreadRouteScreen.tsx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ import { useSelectedThreadWorktree } from "../../state/use-selected-thread-workt
7777
import { useThreadComposerState } from "../../state/use-thread-composer-state";
7878
import { resolveMergeBackTargetThreadId } from "@t3tools/client-runtime/state/thread-relationships";
7979
import { resolveLatestMergeBackRun } from "@t3tools/client-runtime/state/thread-workflows";
80-
import { threadEnvironment } from "../../state/threads";
80+
import { threadEnvironment, useThreadFamily } from "../../state/threads";
8181
import { projectThreadContentPresentation } from "./threadContentPresentation";
8282
import { useAppearancePreferences } from "../settings/appearance/AppearancePreferencesProvider";
8383
import {
@@ -205,6 +205,12 @@ function LiveThreadRouteController(props: ThreadRouteScreenProps) {
205205
const connectionsReady = useConnectionsReady();
206206
const { connectionState } = useRemoteConnectionStatus();
207207
const { selectedThread } = useThreadSelection();
208+
// Subagent rows, the open child's own row and its ancestors come from the family when the
209+
// shell leaves idle children out.
210+
useThreadFamily(
211+
selectedThread?.environmentId ?? null,
212+
selectedThread?.lineage.rootThreadId ?? null,
213+
);
208214
const params = props.route.params ?? {};
209215
const environmentIdRaw = firstRouteParam(params.environmentId);
210216
const threadIdRaw = firstRouteParam(params.threadId);

‎apps/mobile/src/state/shell.ts‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import {
33
createEnvironmentShellSummaryAtom,
44
createEnvironmentSnapshotAtom,
55
createShellEnvironmentAtoms,
6+
EMPTY_SHELL_STATE,
67
type EnvironmentShellState,
78
} from "@t3tools/client-runtime/state/shell";
89
import { useAtomValue } from "@effect/atom-react";
@@ -21,11 +22,7 @@ export const environmentShellSummaryAtom = createEnvironmentShellSummaryAtom({
2122
shellStateValueAtom: environmentShell.stateValueAtom,
2223
});
2324

24-
const EMPTY_ENVIRONMENT_SHELL_STATE_ATOM = Atom.make<EnvironmentShellState>({
25-
snapshot: Option.none(),
26-
status: "empty",
27-
error: Option.none(),
28-
});
25+
const EMPTY_ENVIRONMENT_SHELL_STATE_ATOM = Atom.make<EnvironmentShellState>(EMPTY_SHELL_STATE);
2926

3027
const shellStatus = (state: EnvironmentShellState) => state.status;
3128
const shellHasError = (state: EnvironmentShellState) => Option.isSome(state.error);

‎apps/mobile/src/state/thread-outbox-model.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import {
44
fileAttachmentTooLargeMessage,
55
} from "@t3tools/client-runtime/state/attachments";
66
import type { EnvironmentShellStatus } from "@t3tools/client-runtime/state/shell";
7+
import type { ThreadFamilyRead } from "@t3tools/client-runtime/state/threads";
78
import {
89
CommandId,
910
EnvironmentId,
@@ -176,6 +177,11 @@ export function resolveThreadOutboxDeliveryAction(input: {
176177
readonly shellStatus: EnvironmentShellStatus;
177178
readonly environmentConnected: boolean;
178179
readonly threadBusy: boolean;
180+
/**
181+
* Set when the shell can leave idle subagent children out: absence alone is not deletion there,
182+
* only a settled family read without the row is.
183+
*/
184+
readonly familyRead?: ThreadFamilyRead;
179185
}): ThreadOutboxDeliveryAction {
180186
if (input.isCreation) {
181187
if (input.threadExists) {
@@ -187,7 +193,10 @@ export function resolveThreadOutboxDeliveryAction(input: {
187193
return input.environmentConnected && input.shellStatus === "live" ? "send" : "wait";
188194
}
189195
if (!input.threadExists) {
190-
return input.shellStatus === "live" ? "remove" : "wait";
196+
return input.shellStatus === "live" &&
197+
(input.familyRead === undefined || input.familyRead === "settled")
198+
? "remove"
199+
: "wait";
191200
}
192201
return input.environmentConnected ? "send" : "wait";
193202
}

‎apps/mobile/src/state/thread-outbox.test.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1124,6 +1124,19 @@ describe("thread outbox", () => {
11241124
).toBe("send");
11251125
});
11261126

1127+
it("removes a missing-thread message only after a settled family read when idle children can be omitted", () => {
1128+
const missing = {
1129+
isCreation: false,
1130+
threadExists: false,
1131+
shellStatus: "live",
1132+
environmentConnected: true,
1133+
threadBusy: false,
1134+
} as const;
1135+
expect(resolveThreadOutboxDeliveryAction({ ...missing, familyRead: "pending" })).toBe("wait");
1136+
expect(resolveThreadOutboxDeliveryAction({ ...missing, familyRead: "failed" })).toBe("wait");
1137+
expect(resolveThreadOutboxDeliveryAction({ ...missing, familyRead: "settled" })).toBe("remove");
1138+
});
1139+
11271140
it("sends existing-thread messages whenever connected so queued messages can steer", () => {
11281141
expect(
11291142
resolveThreadOutboxDeliveryAction({

‎apps/mobile/src/state/threads.ts‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,25 @@ import {
66
EMPTY_ENVIRONMENT_THREAD_STATE,
77
type EnvironmentThreadState,
88
createThreadEnvironmentAtoms,
9+
createThreadFamilyAtoms,
910
} from "@t3tools/client-runtime/state/threads";
1011
import type { EnvironmentId, ThreadId } from "@t3tools/contracts";
1112
import * as Option from "effect/Option";
1213
import { AsyncResult, Atom } from "effect/reactivity";
14+
import { useEffect } from "react";
1315

1416
import { environmentCatalog } from "../connection/catalog";
1517
import { connectionAtomRuntime } from "../connection/runtime";
16-
import { environmentSnapshotAtom } from "./shell";
18+
import { appAtomRegistry } from "./atom-registry";
19+
import { environmentShell } from "./shell";
1720

21+
export const threadFamilies = createThreadFamilyAtoms(
22+
connectionAtomRuntime,
23+
environmentShell.stateAtom,
24+
);
1825
export const threadEnvironment = createThreadEnvironmentAtoms(
1926
connectionAtomRuntime,
20-
environmentSnapshotAtom,
27+
threadFamilies.snapshotAtom,
2128
);
2229
export const environmentThreads = createEnvironmentThreadStateAtoms(connectionAtomRuntime);
2330
export const environmentThreadDetails = createEnvironmentThreadDetailAtoms(
@@ -28,6 +35,17 @@ export const environmentThreadShells = createEnvironmentThreadShellAtoms({
2835
snapshotAtom: threadEnvironment.snapshotAtom,
2936
});
3037

38+
/** Keeps the subagent tree under `rootThreadId` in the thread list while the caller shows it. */
39+
export function useThreadFamily(
40+
environmentId: EnvironmentId | null,
41+
rootThreadId: ThreadId | null,
42+
): void {
43+
useEffect(() => {
44+
if (environmentId === null || rootThreadId === null) return;
45+
return threadFamilies.mount(appAtomRegistry, environmentId, rootThreadId);
46+
}, [environmentId, rootThreadId]);
47+
}
48+
3149
const EMPTY_THREAD_STATE_ATOM = Atom.make(AsyncResult.success(EMPTY_ENVIRONMENT_THREAD_STATE)).pipe(
3250
Atom.withLabel("mobile-environment-thread:empty"),
3351
);

‎apps/mobile/src/state/use-composer-drafts.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { createEnvironmentThreadShellAtoms } from "@t3tools/client-runtime/state
33
import {
44
applyShellStreamEvent,
55
createEnvironmentSnapshotAtom,
6+
EMPTY_SHELL_STATE,
67
type EnvironmentShellState,
78
type EnvironmentShellStatus,
89
} from "@t3tools/client-runtime/state/shell";
@@ -284,9 +285,9 @@ function modelReconciliationHarness(
284285
],
285286
};
286287
const shellStateAtom = Atom.make<EnvironmentShellState>({
288+
...EMPTY_SHELL_STATE,
287289
snapshot: Option.some(initialSnapshot),
288290
status: initialStatus,
289-
error: Option.none(),
290291
});
291292
const shellResultAtom = Atom.map(shellStateAtom, AsyncResult.success);
292293
const snapshotAtom = createEnvironmentSnapshotAtom(() => shellResultAtom)(environmentId);

‎apps/mobile/src/state/use-thread-outbox-drain.ts‎

Lines changed: 69 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import {
77
type EnvironmentThreadShell,
88
} from "@t3tools/client-runtime/state/shell";
99
import type { AtomCommandResult } from "@t3tools/client-runtime/state/runtime";
10+
import { threadFamilyRead, type ThreadFamilyRead } from "@t3tools/client-runtime/state/threads";
1011
import { deriveThreadTitleSeed } from "@t3tools/client-runtime/operations";
1112
import {
1213
AuthOrchestrationOperateScope,
@@ -66,7 +67,7 @@ import {
6667
type ThreadOutboxCommandStage,
6768
type ThreadOutboxFailureAction,
6869
} from "./thread-outbox-model";
69-
import { environmentThreadShells, threadEnvironment } from "./threads";
70+
import { environmentThreadShells, threadEnvironment, threadFamilies } from "./threads";
7071
import {
7172
appendComposerDraftAttachments,
7273
composerDraftsAtom,
@@ -614,6 +615,16 @@ export function useThreadOutboxDrain(): void {
614615
const retryNotBeforeRef = useRef(new Map<MessageId, number>());
615616
const retryTimersRef = useRef(new Map<MessageId, ReturnType<typeof setTimeout>>());
616617
const acknowledgedExistingThreadMessageIdsRef = useRef(new Set<MessageId>());
618+
// Targets the shell may have left out hold their thread family until they leave the queue, so
619+
// the row stays readable through dispatch.
620+
const familyMountsRef = useRef(new Map<MessageId, () => void>());
621+
useEffect(
622+
() => () => {
623+
for (const release of familyMountsRef.current.values()) release();
624+
familyMountsRef.current.clear();
625+
},
626+
[],
627+
);
617628
const blockedRecoverySubscriptionsRef = useRef(
618629
new Map<
619630
MessageId,
@@ -1102,6 +1113,12 @@ export function useThreadOutboxDrain(): void {
11021113
acknowledgedExistingThreadMessageIdsRef.current.delete(messageId);
11031114
}
11041115
}
1116+
for (const [messageId, release] of familyMountsRef.current) {
1117+
if (!queuedMessageIds.has(messageId)) {
1118+
release();
1119+
familyMountsRef.current.delete(messageId);
1120+
}
1121+
}
11051122

11061123
for (const [threadKey, queuedMessages] of Object.entries(queuedMessagesByThreadKey)) {
11071124
const nextQueuedMessage = queuedMessages[0];
@@ -1153,7 +1170,7 @@ export function useThreadOutboxDrain(): void {
11531170
continue;
11541171
}
11551172

1156-
const thread = findThread(threads, nextQueuedMessage);
1173+
let thread = findThread(threads, nextQueuedMessage);
11571174
if (thread && scopedThreadKey(thread.environmentId, thread.id) !== threadKey) {
11581175
continue;
11591176
}
@@ -1163,17 +1180,66 @@ export function useThreadOutboxDrain(): void {
11631180
(candidate) => candidate.environmentId === nextQueuedMessage.environmentId,
11641181
);
11651182
const shellStatus = shellStatuses.get(nextQueuedMessage.environmentId) ?? "empty";
1183+
const serverConfig = serverConfigs.get(nextQueuedMessage.environmentId);
1184+
let familyRead: ThreadFamilyRead | undefined;
1185+
if (
1186+
thread === undefined &&
1187+
creation === undefined &&
1188+
serverConfig?.shellThreadFamilies === true
1189+
) {
1190+
// The family keeps the row readable through dispatch once it loads; the current shell
1191+
// generation's read decides whether the thread is gone.
1192+
if (!familyMountsRef.current.has(nextQueuedMessage.messageId)) {
1193+
familyMountsRef.current.set(
1194+
nextQueuedMessage.messageId,
1195+
threadFamilies.mount(
1196+
appAtomRegistry,
1197+
nextQueuedMessage.environmentId,
1198+
nextQueuedMessage.threadId,
1199+
),
1200+
);
1201+
}
1202+
familyRead = threadFamilyRead(
1203+
appAtomRegistry.get(
1204+
threadFamilies.familyAtom(nextQueuedMessage.environmentId, nextQueuedMessage.threadId),
1205+
),
1206+
);
1207+
if (familyRead === "settled") {
1208+
// The rows from this render can lag the family that just settled; decide from the
1209+
// merged rows as they are now.
1210+
thread = findThread(
1211+
appAtomRegistry.get(environmentThreadShells.threadShellsAtom),
1212+
nextQueuedMessage,
1213+
);
1214+
} else if (familyRead === "failed") {
1215+
threadFamilies.refresh(
1216+
appAtomRegistry,
1217+
nextQueuedMessage.environmentId,
1218+
nextQueuedMessage.threadId,
1219+
);
1220+
}
1221+
}
11661222
const deliveryAction = resolveThreadOutboxDeliveryAction({
11671223
isCreation: creation !== undefined,
11681224
threadExists: thread !== undefined,
11691225
shellStatus,
11701226
environmentConnected: environment?.connectionState === "connected",
11711227
threadBusy: threadRuntimeIsActive(thread?.runtime),
1228+
...(familyRead === undefined ? {} : { familyRead }),
11721229
});
1230+
if (
1231+
deliveryAction === "wait" &&
1232+
shellStatus === "live" &&
1233+
familyRead !== undefined &&
1234+
familyRead !== "settled"
1235+
) {
1236+
// An empty family read changes no merged row, so nothing else would wake the drain.
1237+
scheduleQueuedMessageRetry(nextQueuedMessage.messageId);
1238+
continue;
1239+
}
11731240
if (deliveryAction === "send" && !operableEnvironments.has(nextQueuedMessage.environmentId)) {
11741241
continue;
11751242
}
1176-
const serverConfig = serverConfigs.get(nextQueuedMessage.environmentId);
11771243
const dispatchStep = resolveThreadOutboxDispatchStep({
11781244
deliveryAction,
11791245
fileAttachments: nextQueuedMessage.attachments.filter(

‎apps/server/src/auth/RpcAuthorization.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ export const RPC_REQUIRED_SCOPES = {
4848
[ORCHESTRATION_V2_WS_METHODS.searchThread]: AuthOrchestrationReadScope,
4949
[ORCHESTRATION_V2_WS_METHODS.searchThreadStream]: AuthOrchestrationReadScope,
5050
[ORCHESTRATION_V2_WS_METHODS.getArchivedShellSnapshot]: AuthOrchestrationReadScope,
51+
[ORCHESTRATION_V2_WS_METHODS.getThreadFamily]: AuthOrchestrationReadScope,
52+
[ORCHESTRATION_V2_WS_METHODS.getWorktreeThreadIds]: AuthOrchestrationReadScope,
5153
[ORCHESTRATION_V2_WS_METHODS.getThreadProjection]: AuthOrchestrationReadScope,
5254
[ORCHESTRATION_V2_WS_METHODS.getTurnItem]: AuthOrchestrationReadScope,
5355
[ORCHESTRATION_V2_WS_METHODS.launchThread]: AuthOrchestrationOperateScope,

‎apps/server/src/observability/RpcInstrumentation.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ const RPC_AGGREGATES = {
2424
[ORCHESTRATION_V2_WS_METHODS.searchThread]: "orchestration",
2525
[ORCHESTRATION_V2_WS_METHODS.searchThreadStream]: "orchestration",
2626
[ORCHESTRATION_V2_WS_METHODS.getArchivedShellSnapshot]: "orchestration",
27+
[ORCHESTRATION_V2_WS_METHODS.getThreadFamily]: "orchestration",
28+
[ORCHESTRATION_V2_WS_METHODS.getWorktreeThreadIds]: "orchestration",
2729
[ORCHESTRATION_V2_WS_METHODS.getThreadProjection]: "orchestrationV2",
2830
[ORCHESTRATION_V2_WS_METHODS.launchThread]: "orchestration",
2931
[ORCHESTRATION_V2_WS_METHODS.subscribeArchivedShell]: "orchestration",

‎apps/server/src/orchestration-v2/ProjectionStore.test.ts‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1107,6 +1107,92 @@ const assertProjectScopedShells = Effect.fn("assertProjectScopedShells")(functio
11071107
return { projectId, activeThreadId, forkThreadId, otherThreadId };
11081108
});
11091109

1110+
it.effect.each([
1111+
["memory", ProjectionStore.layerMemory],
1112+
["SQL", layerTest],
1113+
] as const)("%s shells read a subagent family and a worktree's threads", ([, layer]) =>
1114+
Effect.gen(function* () {
1115+
const store = yield* ProjectionStore.ProjectionStoreV2;
1116+
const now = yield* DateTime.now;
1117+
const projectId = ProjectId.make("project:family");
1118+
const worktreePath = "/repo/.t3/worktrees/family";
1119+
const id = (name: string) => ThreadId.make(`thread:family:${name}`);
1120+
const payloadOf = (input: {
1121+
readonly name: string;
1122+
readonly parent?: string;
1123+
readonly root?: string;
1124+
readonly worktreePath?: string;
1125+
readonly archived?: boolean;
1126+
}) =>
1127+
({
1128+
createdBy: "user",
1129+
creationSource: input.parent === undefined ? "web" : "mcp",
1130+
id: id(input.name),
1131+
projectId,
1132+
title: input.name,
1133+
providerInstanceId,
1134+
modelSelection,
1135+
runtimeMode: "full-access",
1136+
interactionMode: "default",
1137+
branch: null,
1138+
worktreePath: input.worktreePath ?? null,
1139+
activeProviderThreadId: null,
1140+
lineage: {
1141+
parentThreadId: input.parent === undefined ? null : id(input.parent),
1142+
relationshipToParent: input.parent === undefined ? null : "subagent",
1143+
rootThreadId: id(input.root ?? input.name),
1144+
},
1145+
forkedFrom: null,
1146+
createdAt: now,
1147+
updatedAt: now,
1148+
archivedAt: input.archived === true ? now : null,
1149+
settledOverride: null,
1150+
settledAt: null,
1151+
lastVisitedAt: null,
1152+
deletedAt: null,
1153+
}) as const;
1154+
const createThread = (input: Parameters<typeof payloadOf>[0]) =>
1155+
store.apply({
1156+
id: EventId.make(`event:family:${input.name}`),
1157+
type: "thread.created",
1158+
threadId: id(input.name),
1159+
occurredAt: now,
1160+
payload: payloadOf(input),
1161+
});
1162+
yield* createThread({ name: "root", worktreePath });
1163+
yield* createThread({ name: "child", parent: "root", root: "root", worktreePath });
1164+
yield* createThread({ name: "grandchild", parent: "child", root: "root" });
1165+
yield* createThread({ name: "archived-child", parent: "root", root: "root", archived: true });
1166+
yield* createThread({ name: "other", worktreePath: "/repo" });
1167+
yield* createThread({ name: "other-child", parent: "other", root: "other", worktreePath });
1168+
1169+
const family = (threadId: ThreadId) =>
1170+
store
1171+
.getShellSnapshot({ location: "active", subagentFamilyOf: threadId })
1172+
.pipe(Effect.map((snapshot) => snapshot.threads.map((thread) => thread.id)));
1173+
// Any member, or the root itself, names the same active subagent tree.
1174+
assert.sameMembers([...(yield* family(id("root")))], [id("child"), id("grandchild")]);
1175+
assert.sameMembers([...(yield* family(id("grandchild")))], [id("child"), id("grandchild")]);
1176+
assert.deepEqual([...(yield* family(id("missing")))], []);
1177+
1178+
// Includes another root's idle child on the same path, which a shell may leave out.
1179+
const onWorktree = yield* store.getShellSnapshot({ location: "active", worktreePath });
1180+
assert.sameMembers(
1181+
onWorktree.threads.map((thread) => thread.id),
1182+
[id("root"), id("child"), id("other-child")],
1183+
);
1184+
// A fork keeps its deleted source's root, so the deleted root still names the live tree.
1185+
yield* store.apply({
1186+
id: EventId.make("event:family:root-deleted"),
1187+
type: "thread.deleted",
1188+
threadId: id("root"),
1189+
occurredAt: now,
1190+
payload: { ...payloadOf({ name: "root", worktreePath }), deletedAt: now },
1191+
});
1192+
assert.sameMembers([...(yield* family(id("root")))], [id("child"), id("grandchild")]);
1193+
}).pipe(Effect.provide(layer)),
1194+
);
1195+
11101196
it.effect("lists only active subagent IDs without loading shell data", () =>
11111197
Effect.gen(function* () {
11121198
const store = yield* ProjectionStore.ProjectionStoreV2;

0 commit comments

Comments
 (0)