The best way to control Claude Code, Codex and more from any computer or phone
perf(shell): cold connects skip idle subagent threads, a third of the thread list (#24648)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 24, 2026 at 18:41 UTC
67c3afbd58e72d088fec7af69d52dd255a00199e
35 files changed
+1233
-49
apps/mobile/src/features/threads/ThreadRouteScreen.tsx
+7
-1
@@ -77,7 +77,7 @@ import { useSelectedThreadWorktree } from "../../state/use-selected-thread-workt
77
import { useThreadComposerState } from "../../state/use-thread-composer-state";
78
import { resolveMergeBackTargetThreadId } from "@t3tools/client-runtime/state/thread-relationships";
79
import { resolveLatestMergeBackRun } from "@t3tools/client-runtime/state/thread-workflows";
80
-import { threadEnvironment } from "../../state/threads";
80
+import { threadEnvironment, useThreadFamily } from "../../state/threads";
81
import { projectThreadContentPresentation } from "./threadContentPresentation";
82
import { useAppearancePreferences } from "../settings/appearance/AppearancePreferencesProvider";
83
import {
@@ -205,6 +205,12 @@ function LiveThreadRouteController(props: ThreadRouteScreenProps) {
205
const connectionsReady = useConnectionsReady();
206
const { connectionState } = useRemoteConnectionStatus();
207
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
+ );
214
const params = props.route.params ?? {};
215
const environmentIdRaw = firstRouteParam(params.environmentId);
216
const threadIdRaw = firstRouteParam(params.threadId);
apps/mobile/src/state/shell.ts
+2
-5
@@ -3,6 +3,7 @@ import {
3
createEnvironmentShellSummaryAtom,
4
createEnvironmentSnapshotAtom,
5
createShellEnvironmentAtoms,
6
+ EMPTY_SHELL_STATE,
7
type EnvironmentShellState,
8
} from "@t3tools/client-runtime/state/shell";
9
import { useAtomValue } from "@effect/atom-react";
@@ -21,11 +22,7 @@ export const environmentShellSummaryAtom = createEnvironmentShellSummaryAtom({
22
shellStateValueAtom: environmentShell.stateValueAtom,
23
});
24
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);
26
27
const shellStatus = (state: EnvironmentShellState) => state.status;
28
const shellHasError = (state: EnvironmentShellState) => Option.isSome(state.error);
apps/mobile/src/state/thread-outbox-model.ts
+10
-1
@@ -4,6 +4,7 @@ import {
4
fileAttachmentTooLargeMessage,
5
} from "@t3tools/client-runtime/state/attachments";
6
import type { EnvironmentShellStatus } from "@t3tools/client-runtime/state/shell";
7
+import type { ThreadFamilyRead } from "@t3tools/client-runtime/state/threads";
8
import {
9
CommandId,
10
EnvironmentId,
@@ -176,6 +177,11 @@ export function resolveThreadOutboxDeliveryAction(input: {
177
readonly shellStatus: EnvironmentShellStatus;
178
readonly environmentConnected: boolean;
179
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;
185
}): ThreadOutboxDeliveryAction {
186
if (input.isCreation) {
187
if (input.threadExists) {
@@ -187,7 +193,10 @@ export function resolveThreadOutboxDeliveryAction(input: {
193
return input.environmentConnected && input.shellStatus === "live" ? "send" : "wait";
194
}
195
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";
200
}
201
return input.environmentConnected ? "send" : "wait";
202
}
apps/mobile/src/state/thread-outbox.test.ts
+13
@@ -1124,6 +1124,19 @@ describe("thread outbox", () => {
1124
).toBe("send");
1125
});
1126
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
+
1140
it("sends existing-thread messages whenever connected so queued messages can steer", () => {
1141
expect(
1142
resolveThreadOutboxDeliveryAction({
apps/mobile/src/state/threads.ts
+20
-2
@@ -6,18 +6,25 @@ import {
6
EMPTY_ENVIRONMENT_THREAD_STATE,
7
type EnvironmentThreadState,
8
createThreadEnvironmentAtoms,
9
+ createThreadFamilyAtoms,
10
} from "@t3tools/client-runtime/state/threads";
11
import type { EnvironmentId, ThreadId } from "@t3tools/contracts";
12
import * as Option from "effect/Option";
13
import { AsyncResult, Atom } from "effect/reactivity";
14
+import { useEffect } from "react";
15
16
import { environmentCatalog } from "../connection/catalog";
17
import { connectionAtomRuntime } from "../connection/runtime";
16
-import { environmentSnapshotAtom } from "./shell";
18
+import { appAtomRegistry } from "./atom-registry";
19
+import { environmentShell } from "./shell";
20
21
+export const threadFamilies = createThreadFamilyAtoms(
22
+ connectionAtomRuntime,
23
+ environmentShell.stateAtom,
24
+);
25
export const threadEnvironment = createThreadEnvironmentAtoms(
26
connectionAtomRuntime,
20
- environmentSnapshotAtom,
27
+ threadFamilies.snapshotAtom,
28
);
29
export const environmentThreads = createEnvironmentThreadStateAtoms(connectionAtomRuntime);
30
export const environmentThreadDetails = createEnvironmentThreadDetailAtoms(
@@ -28,6 +35,17 @@ export const environmentThreadShells = createEnvironmentThreadShellAtoms({
35
snapshotAtom: threadEnvironment.snapshotAtom,
36
});
37
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
+
49
const EMPTY_THREAD_STATE_ATOM = Atom.make(AsyncResult.success(EMPTY_ENVIRONMENT_THREAD_STATE)).pipe(
50
Atom.withLabel("mobile-environment-thread:empty"),
51
);
apps/mobile/src/state/use-composer-drafts.test.ts
+2
-1
@@ -3,6 +3,7 @@ import { createEnvironmentThreadShellAtoms } from "@t3tools/client-runtime/state
3
import {
4
applyShellStreamEvent,
5
createEnvironmentSnapshotAtom,
6
+ EMPTY_SHELL_STATE,
7
type EnvironmentShellState,
8
type EnvironmentShellStatus,
9
} from "@t3tools/client-runtime/state/shell";
@@ -284,9 +285,9 @@ function modelReconciliationHarness(
285
],
286
};
287
const shellStateAtom = Atom.make<EnvironmentShellState>({
288
+ ...EMPTY_SHELL_STATE,
289
snapshot: Option.some(initialSnapshot),
290
status: initialStatus,
289
- error: Option.none(),
291
});
292
const shellResultAtom = Atom.map(shellStateAtom, AsyncResult.success);
293
const snapshotAtom = createEnvironmentSnapshotAtom(() => shellResultAtom)(environmentId);
apps/mobile/src/state/use-thread-outbox-drain.ts
+69
-3
@@ -7,6 +7,7 @@ import {
7
type EnvironmentThreadShell,
8
} from "@t3tools/client-runtime/state/shell";
9
import type { AtomCommandResult } from "@t3tools/client-runtime/state/runtime";
10
+import { threadFamilyRead, type ThreadFamilyRead } from "@t3tools/client-runtime/state/threads";
11
import { deriveThreadTitleSeed } from "@t3tools/client-runtime/operations";
12
import {
13
AuthOrchestrationOperateScope,
@@ -66,7 +67,7 @@ import {
67
type ThreadOutboxCommandStage,
68
type ThreadOutboxFailureAction,
69
} from "./thread-outbox-model";
69
-import { environmentThreadShells, threadEnvironment } from "./threads";
70
+import { environmentThreadShells, threadEnvironment, threadFamilies } from "./threads";
71
import {
72
appendComposerDraftAttachments,
73
composerDraftsAtom,
@@ -614,6 +615,16 @@ export function useThreadOutboxDrain(): void {
615
const retryNotBeforeRef = useRef(new Map<MessageId, number>());
616
const retryTimersRef = useRef(new Map<MessageId, ReturnType<typeof setTimeout>>());
617
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
+ );
628
const blockedRecoverySubscriptionsRef = useRef(
629
new Map<
630
MessageId,
@@ -1102,6 +1113,12 @@ export function useThreadOutboxDrain(): void {
1113
acknowledgedExistingThreadMessageIdsRef.current.delete(messageId);
1114
}
1115
}
1116
+ for (const [messageId, release] of familyMountsRef.current) {
1117
+ if (!queuedMessageIds.has(messageId)) {
1118
+ release();
1119
+ familyMountsRef.current.delete(messageId);
1120
+ }
1121
+ }
1122
1123
for (const [threadKey, queuedMessages] of Object.entries(queuedMessagesByThreadKey)) {
1124
const nextQueuedMessage = queuedMessages[0];
@@ -1153,7 +1170,7 @@ export function useThreadOutboxDrain(): void {
1170
continue;
1171
}
1172
1156
- const thread = findThread(threads, nextQueuedMessage);
1173
+ let thread = findThread(threads, nextQueuedMessage);
1174
if (thread && scopedThreadKey(thread.environmentId, thread.id) !== threadKey) {
1175
continue;
1176
}
@@ -1163,17 +1180,66 @@ export function useThreadOutboxDrain(): void {
1180
(candidate) => candidate.environmentId === nextQueuedMessage.environmentId,
1181
);
1182
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
+ }
1222
const deliveryAction = resolveThreadOutboxDeliveryAction({
1223
isCreation: creation !== undefined,
1224
threadExists: thread !== undefined,
1225
shellStatus,
1226
environmentConnected: environment?.connectionState === "connected",
1227
threadBusy: threadRuntimeIsActive(thread?.runtime),
1228
+ ...(familyRead === undefined ? {} : { familyRead }),
1229
});
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
+ }
1240
if (deliveryAction === "send" && !operableEnvironments.has(nextQueuedMessage.environmentId)) {
1241
continue;
1242
}
1176
- const serverConfig = serverConfigs.get(nextQueuedMessage.environmentId);
1243
const dispatchStep = resolveThreadOutboxDispatchStep({
1244
deliveryAction,
1245
fileAttachments: nextQueuedMessage.attachments.filter(
apps/server/src/auth/RpcAuthorization.ts
+2
@@ -48,6 +48,8 @@ export const RPC_REQUIRED_SCOPES = {
48
[ORCHESTRATION_V2_WS_METHODS.searchThread]: AuthOrchestrationReadScope,
49
[ORCHESTRATION_V2_WS_METHODS.searchThreadStream]: AuthOrchestrationReadScope,
50
[ORCHESTRATION_V2_WS_METHODS.getArchivedShellSnapshot]: AuthOrchestrationReadScope,
51
+ [ORCHESTRATION_V2_WS_METHODS.getThreadFamily]: AuthOrchestrationReadScope,
52
+ [ORCHESTRATION_V2_WS_METHODS.getWorktreeThreadIds]: AuthOrchestrationReadScope,
53
[ORCHESTRATION_V2_WS_METHODS.getThreadProjection]: AuthOrchestrationReadScope,
54
[ORCHESTRATION_V2_WS_METHODS.getTurnItem]: AuthOrchestrationReadScope,
55
[ORCHESTRATION_V2_WS_METHODS.launchThread]: AuthOrchestrationOperateScope,
apps/server/src/observability/RpcInstrumentation.ts
+2
@@ -24,6 +24,8 @@ const RPC_AGGREGATES = {
24
[ORCHESTRATION_V2_WS_METHODS.searchThread]: "orchestration",
25
[ORCHESTRATION_V2_WS_METHODS.searchThreadStream]: "orchestration",
26
[ORCHESTRATION_V2_WS_METHODS.getArchivedShellSnapshot]: "orchestration",
27
+ [ORCHESTRATION_V2_WS_METHODS.getThreadFamily]: "orchestration",
28
+ [ORCHESTRATION_V2_WS_METHODS.getWorktreeThreadIds]: "orchestration",
29
[ORCHESTRATION_V2_WS_METHODS.getThreadProjection]: "orchestrationV2",
30
[ORCHESTRATION_V2_WS_METHODS.launchThread]: "orchestration",
31
[ORCHESTRATION_V2_WS_METHODS.subscribeArchivedShell]: "orchestration",
apps/server/src/orchestration-v2/ProjectionStore.test.ts
+86
@@ -1107,6 +1107,92 @@ const assertProjectScopedShells = Effect.fn("assertProjectScopedShells")(functio
1107
return { projectId, activeThreadId, forkThreadId, otherThreadId };
1108
});
1109
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
+
1196
it.effect("lists only active subagent IDs without loading shell data", () =>
1197
Effect.gen(function* () {
1198
const store = yield* ProjectionStore.ProjectionStoreV2;
apps/server/src/orchestration-v2/ProjectionStore.ts
+41
-1
@@ -406,6 +406,12 @@ export interface ShellSnapshotOptions {
406
readonly location?: "active" | "archive";
407
readonly projectId?: ProjectId;
408
readonly unsettledOnly?: boolean;
409
+ /**
410
+ * Only the subagent threads sharing this thread's `lineage.rootThreadId`. The thread may be
411
+ * deleted: forks keep a deleted source's root, and their subagent trees still need it.
412
+ */
413
+ readonly subagentFamilyOf?: ThreadId;
414
+ readonly worktreePath?: string;
415
}
416
417
export interface ProjectionStoreV2Shape {
@@ -5697,7 +5703,13 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
5703
5704
const selectShellThreadRows = (
5705
threadId?: ThreadId,
5700
- { location, projectId, unsettledOnly = false }: ShellSnapshotOptions = {},
5706
+ {
5707
+ location,
5708
+ projectId,
5709
+ unsettledOnly = false,
5710
+ subagentFamilyOf,
5711
+ worktreePath,
5712
+ }: ShellSnapshotOptions = {},
5713
) =>
5714
sql<ShellThreadRow>`
5715
SELECT
@@ -5898,6 +5910,18 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
5910
unsettledOnly
5911
? sql` AND json_extract(t.payload_json, '$.settledAt') IS NULL AND json_extract(t.payload_json, '$.settledOverride') IS NOT 'settled'`
5912
: sql``
5913
+ }${
5914
+ subagentFamilyOf === undefined
5915
+ ? sql``
5916
+ : sql` AND json_extract(t.payload_json, '$.lineage.relationshipToParent') = 'subagent' AND json_extract(t.payload_json, '$.lineage.rootThreadId') = (
5917
+ SELECT json_extract(member.payload_json, '$.lineage.rootThreadId')
5918
+ FROM orchestration_v2_projection_threads member
5919
+ WHERE member.thread_id = ${subagentFamilyOf}
5920
+ )`
5921
+ }${
5922
+ worktreePath === undefined
5923
+ ? sql``
5924
+ : sql` AND json_extract(t.payload_json, '$.worktreePath') = ${worktreePath}`
5925
}
5926
ORDER BY t.updated_at ASC, t.thread_id ASC
5927
`;
@@ -6712,6 +6736,22 @@ export const layerMemory: Layer.Layer<ProjectionStoreV2> = Layer.effect(
6736
) {
6737
return false;
6738
}
6739
+ if (options?.subagentFamilyOf !== undefined) {
6740
+ const member = existing.get(options.subagentFamilyOf)?.thread;
6741
+ if (
6742
+ member === undefined ||
6743
+ projection.thread.lineage.relationshipToParent !== "subagent" ||
6744
+ projection.thread.lineage.rootThreadId !== member.lineage.rootThreadId
6745
+ ) {
6746
+ return false;
6747
+ }
6748
+ }
6749
+ if (
6750
+ options?.worktreePath !== undefined &&
6751
+ projection.thread.worktreePath !== options.worktreePath
6752
+ ) {
6753
+ return false;
6754
+ }
6755
if (options?.location === "active") return projection.thread.archivedAt === null;
6756
if (options?.location === "archive") return projection.thread.archivedAt !== null;
6757
return true;
apps/server/src/orchestration-v2/ShellStream.test.ts
+65
@@ -17,9 +17,11 @@ import * as Stream from "effect/Stream";
17
import * as TestClock from "effect/testing/TestClock";
18
19
import {
20
+ activeShellRowsForSubscriber,
21
bufferShellLiveStream,
22
composeShellStreamWithEnrichment,
23
dedupeShellEnrichment,
24
+ omitIdleSubagentShells,
25
shellStreamItemFromEnrichmentRefresh,
26
shellStreamItemsFromInitialSnapshot,
27
shouldPublishShellApplicationEvent,
@@ -139,6 +141,69 @@ function shellFixture(overrides: Partial<OrchestrationV2ThreadShell>): Orchestra
141
return { id: "thread-a", archivedAt: null, ...overrides } as OrchestrationV2ThreadShell;
142
}
143
144
+describe("omitIdleSubagentShells", () => {
145
+ const row = (
146
+ id: string,
147
+ parent: string | null,
148
+ overrides: Partial<OrchestrationV2ThreadShell> = {},
149
+ ) =>
150
+ shellFixture({
151
+ id: ThreadId.make(id),
152
+ lineage: {
153
+ parentThreadId: parent === null ? null : ThreadId.make(parent),
154
+ relationshipToParent: parent === null ? null : "subagent",
155
+ rootThreadId: ThreadId.make("root"),
156
+ },
157
+ status: "completed",
158
+ activityRunStatus: null,
159
+ pendingRuntimeRequest: null,
160
+ pendingBackgroundTasks: [],
161
+ ...overrides,
162
+ });
163
+
164
+ it("drops idle leaf children but keeps live ones and the middle of nested chains", () => {
165
+ const threads = [
166
+ row("root", null),
167
+ row("idle", "root"),
168
+ row("running", "root", { activityRunStatus: "running" }),
169
+ row("queued", "root", { status: "queued" }),
170
+ row("asking", "root", {
171
+ pendingRuntimeRequest: {
172
+ id: "request" as never,
173
+ kind: "user_input",
174
+ createdAt: DateTime.makeUnsafe(0),
175
+ },
176
+ }),
177
+ row("background", "root", {
178
+ pendingBackgroundTasks: [{ kind: "subagent" } as never],
179
+ }),
180
+ // Idle, but a woken grandchild walks through it to reach the root's badge.
181
+ row("middle", "root"),
182
+ row("grandchild", "middle"),
183
+ ];
184
+ expect(omitIdleSubagentShells(threads).map((thread) => thread.id)).toEqual([
185
+ "root",
186
+ "running",
187
+ "queued",
188
+ "asking",
189
+ "background",
190
+ "middle",
191
+ ]);
192
+ });
193
+
194
+ it("still filters the transcript events of omitted children for a subscriber that opts in", () => {
195
+ const threads = [row("root", null), row("idle", "root")];
196
+ const omitted = activeShellRowsForSubscriber(threads, true);
197
+ expect(omitted.threads.map((thread) => thread.id)).toEqual(["root"]);
198
+ expect(
199
+ shouldPublishShellApplicationEvent(
200
+ { event: { threadId: "idle", type: "turn-item.updated" } } as ApplicationStoredEvent,
201
+ omitted.subagentThreadIds,
202
+ ),
203
+ ).toBe(false);
204
+ });
205
+});
206
+
207
describe("shellStreamItemsFromInitialSnapshot", () => {
208
it("keeps thread rows out of the metadata-only enrichment frame", () => {
209
const snapshot = {
apps/server/src/orchestration-v2/ShellStream.ts
+44
@@ -9,6 +9,7 @@ import type {
9
OrchestrationV2StoredEvent,
10
} from "@t3tools/contracts";
11
import {
12
+ isLiveSubagentShell,
13
OrchestrationProjectShell as ProjectShellSchema,
14
OrchestrationV2ThreadShell as ThreadShellSchema,
15
} from "@t3tools/contracts";
@@ -64,6 +65,49 @@ export function buildActiveShellSnapshot(input: {
65
};
66
}
67
68
+/**
69
+ * Idle subagent children have no sidebar row, so clients that opt in read them from their thread
70
+ * family instead. A child stays while it is live or the parent of another child, so the request
71
+ * and working walks over shell rows never meet a gap in a nested chain.
72
+ */
73
+export function omitIdleSubagentShells(
74
+ threads: ReadonlyArray<OrchestrationV2ThreadShell>,
75
+): ReadonlyArray<OrchestrationV2ThreadShell> {
76
+ const parentIds = new Set<string>();
77
+ for (const thread of threads) {
78
+ if (thread.lineage.relationshipToParent === "subagent" && thread.lineage.parentThreadId) {
79
+ parentIds.add(thread.lineage.parentThreadId);
80
+ }
81
+ }
82
+ return threads.filter(
83
+ (thread) =>
84
+ thread.lineage.relationshipToParent !== "subagent" ||
85
+ isLiveSubagentShell(thread) ||
86
+ parentIds.has(thread.id),
87
+ );
88
+}
89
+
90
+/**
91
+ * The active rows a shell subscriber gets, and the subagent ids whose transcript events its stream
92
+ * drops. The ids come from every row, so an omitted child that wakes keeps that filter.
93
+ */
94
+export function activeShellRowsForSubscriber(
95
+ threads: ReadonlyArray<OrchestrationV2ThreadShell>,
96
+ omitIdleSubagents: boolean,
97
+): {
98
+ readonly threads: ReadonlyArray<OrchestrationV2ThreadShell>;
99
+ readonly subagentThreadIds: Set<string>;
100
+} {
101
+ return {
102
+ threads: omitIdleSubagents ? omitIdleSubagentShells(threads) : threads,
103
+ subagentThreadIds: new Set(
104
+ threads
105
+ .filter((thread) => thread.lineage.relationshipToParent === "subagent")
106
+ .map((thread) => thread.id),
107
+ ),
108
+ };
109
+}
110
+
111
/**
112
* One transaction covers the reads so they agree; the threads are decoded after it commits,
113
* because the server shares one SQLite connection and decoding a large shell takes longer than
apps/server/src/orchestration-v2/ThreadManagementService.ts
+4
-3
@@ -6,6 +6,7 @@ import type {
6
ProjectionRecordField,
7
ProjectionRecordFilter,
8
ProjectionRecords,
9
+ ShellSnapshotOptions,
10
} from "./ProjectionStore.ts";
11
import {
12
type ChatAttachment,
@@ -383,9 +384,9 @@ export interface ThreadManagementServiceShape {
384
readonly location?: "active" | "archive";
385
}) => Effect.Effect<OrchestrationV2ThreadShellSnapshot, Orchestrator.OrchestratorV2Error>;
386
readonly listActiveSubagentThreadIds: Orchestrator.OrchestratorV2["Service"]["listActiveSubagentThreadIds"];
386
- readonly readShellSnapshot: (options?: {
387
- readonly location?: "active" | "archive";
388
- }) => Effect.Effect<
387
+ readonly readShellSnapshot: (
388
+ options?: Pick<ShellSnapshotOptions, "location" | "subagentFamilyOf" | "worktreePath">,
389
+ ) => Effect.Effect<
390
Effect.Effect<OrchestrationV2ThreadShellSnapshot, Orchestrator.OrchestratorV2Error>,
391
Orchestrator.OrchestratorV2Error
392
>;
apps/server/src/orchestration-v2/http.ts
+14
-4
@@ -30,7 +30,11 @@ import {
30
} from "./threadHistoryPaging.ts";
31
import * as ThreadManagementService from "./ThreadManagementService.ts";
32
import * as ProjectStore from "./ProjectStore.ts";
33
-import { buildActiveShellSnapshot, loadShellSnapshotParts } from "./ShellStream.ts";
33
+import {
34
+ buildActiveShellSnapshot,
35
+ loadShellSnapshotParts,
36
+ omitIdleSubagentShells,
37
+} from "./ShellStream.ts";
38
import { boundedSnapshotResponseFields } from "./ThreadStream.ts";
39
import { projectThreadProjectionForWire } from "./WireProjection.ts";
40
@@ -75,7 +79,9 @@ export const layer = HttpApiBuilder.group(
79
),
80
);
81
78
- const loadShellSnapshot = Effect.fn("http.orchestration.loadShellSnapshot")(function* () {
82
+ const loadShellSnapshot = Effect.fn("http.orchestration.loadShellSnapshot")(function* (
83
+ omitIdleSubagents: boolean,
84
+ ) {
85
const base = buildActiveShellSnapshot(
86
yield* loadShellSnapshotParts({
87
sql,
@@ -85,7 +91,11 @@ export const layer = HttpApiBuilder.group(
91
}),
92
);
93
const projects = yield* enrichProjectShells(base.projects);
88
- return { ...base, projects };
94
+ return {
95
+ ...base,
96
+ threads: omitIdleSubagents ? omitIdleSubagentShells(base.threads) : base.threads,
97
+ projects,
98
+ };
99
});
100
101
const loadThreadSnapshot = Effect.fn("http.orchestration.loadThreadSnapshot")(function* (
@@ -154,7 +164,7 @@ export const layer = HttpApiBuilder.group(
164
Effect.fn("environment.orchestration.shellSnapshot")(function* (args) {
165
yield* annotateEnvironmentRequest(args.endpoint.name);
166
yield* requireEnvironmentScope(AuthOrchestrationReadScope);
157
- return yield* loadShellSnapshot().pipe(
167
+ return yield* loadShellSnapshot(args.query.omitIdleSubagents === "1").pipe(
168
traceLocalHandlerWork,
169
Effect.catch((cause) =>
170
failEnvironmentInternal("orchestration_snapshot_failed", cause),
apps/server/src/ws.test.ts
+66
@@ -8,6 +8,7 @@ import {
8
WS_METHODS,
9
WsSubscribeServerConfigRpc,
10
type OrchestrationV2StoredEvent,
11
+ type OrchestrationV2ThreadShell,
12
type OrchestrationProjectShell,
13
type ServerConfig,
14
type ServerConfigStreamEvent,
@@ -290,6 +291,71 @@ it.live.each(["thread", "shell"] as const)(
291
}).pipe(Effect.scoped, Effect.provide(ReplayTestLayer)),
292
);
293
294
+it.effect("shell snapshots leave idle subagent children out only for clients that ask", () =>
295
+ Effect.gen(function* () {
296
+ const shell = (id: string, parent: string | null, activityRunStatus: "running" | null) =>
297
+ ({
298
+ id: ThreadId.make(id),
299
+ archivedAt: null,
300
+ status: activityRunStatus ?? "completed",
301
+ activityRunStatus,
302
+ pendingRuntimeRequest: null,
303
+ pendingBackgroundTasks: [],
304
+ lineage: {
305
+ parentThreadId: parent === null ? null : ThreadId.make(parent),
306
+ relationshipToParent: parent === null ? null : "subagent",
307
+ rootThreadId: ThreadId.make("parent"),
308
+ },
309
+ }) as unknown as OrchestrationV2ThreadShell;
310
+ const threads = [
311
+ shell("parent", null, null),
312
+ shell("idle", "parent", null),
313
+ shell("live", "parent", "running"),
314
+ ];
315
+ const firstSnapshotThreadIds = (input: { readonly omitIdleSubagents?: boolean }) =>
316
+ subscribeOrchestrationV2Shell(input).pipe(
317
+ Effect.flatMap((stream) => stream.pipe(Stream.take(1), Stream.runCollect)),
318
+ Effect.map(([item]) =>
319
+ item?.kind === "snapshot" ? item.snapshot.threads.map((thread) => thread.id) : [],
320
+ ),
321
+ Effect.provideService(ThreadManagement.ThreadManagementService, {
322
+ readShellSnapshot: () =>
323
+ Effect.succeed(
324
+ Effect.succeed({
325
+ schemaVersion: 1,
326
+ snapshotSequence: 0,
327
+ threads,
328
+ archivedThreads: [],
329
+ }),
330
+ ),
331
+ } as unknown as ThreadManagement.ThreadManagementService["Service"]),
332
+ Effect.provideService(ProjectStore.ProjectStoreV2, {
333
+ listShells: () => Effect.succeed([]),
334
+ } as unknown as ProjectStore.ProjectStoreV2["Service"]),
335
+ Effect.provideService(ProjectService.ProjectService, {
336
+ getShell: () => Effect.succeedNone,
337
+ } as unknown as ProjectService.ProjectService["Service"]),
338
+ Effect.provideServiceEffect(
339
+ ProjectEnrichment.ProjectEnrichmentService,
340
+ PubSub.unbounded().pipe(
341
+ Effect.map(
342
+ (changes) =>
343
+ ({
344
+ subscribeChanges: PubSub.subscribe(changes),
345
+ }) as unknown as ProjectEnrichment.ProjectEnrichmentService["Service"],
346
+ ),
347
+ ),
348
+ ),
349
+ );
350
+
351
+ assert.deepEqual(yield* firstSnapshotThreadIds({}), ["parent", "idle", "live"]);
352
+ assert.deepEqual(yield* firstSnapshotThreadIds({ omitIdleSubagents: true }), [
353
+ "parent",
354
+ "live",
355
+ ]);
356
+ }).pipe(Effect.scoped, Effect.provide(ReplayTestLayer)),
357
+);
358
+
359
// Build the production RPC layer; unrelated capabilities fail if this test calls them.
360
const layerUnusedConfigRpcServices = Layer.mergeAll(
361
Layer.mock(ServerSecretStore.ServerSecretStore)({}),
apps/server/src/ws.ts
+40
-6
@@ -129,6 +129,7 @@ import {
129
coalesceStoredThreadEvents,
130
composeShellStreamWithEnrichment,
131
dedupeShellEnrichment,
132
+ activeShellRowsForSubscriber,
133
loadShellSnapshotParts,
134
shellStreamItemFromEnrichmentRefresh,
135
shellStreamItemFromThreadShell,
@@ -979,6 +980,7 @@ export const subscribeOrchestrationV2Shell = Effect.fn("ws.orchestrationV2.subsc
980
function* (input: {
981
readonly afterSequence?: number;
982
readonly requestCompletionMarker?: boolean;
983
+ readonly omitIdleSubagents?: boolean;
984
}) {
985
const sql = yield* SqlClient.SqlClient;
986
const threadManagement = yield* ThreadManagementService.ThreadManagementService;
@@ -1015,14 +1017,15 @@ export const subscribeOrchestrationV2Shell = Effect.fn("ws.orchestrationV2.subsc
1017
latestSequence: applicationEvents.latestApplicationSequence,
1018
}),
1019
);
1018
- subagentThreadIds = new Set(
1019
- base.threads
1020
- .filter((thread) => thread.lineage.relationshipToParent === "subagent")
1021
- .map((thread) => thread.id),
1022
- );
1020
+ const rows = activeShellRowsForSubscriber(base.threads, input.omitIdleSubagents === true);
1021
+ subagentThreadIds = rows.subagentThreadIds;
1022
const enriched = yield* enrichProjectShells(base.projects);
1023
return {
1025
- snapshot: { ...base, projects: enriched.projects } as OrchestrationV2ShellSnapshot,
1024
+ snapshot: {
1025
+ ...base,
1026
+ threads: rows.threads,
1027
+ projects: enriched.projects,
1028
+ } as OrchestrationV2ShellSnapshot,
1029
resolvedRepositoryIdentityRoots: enriched.resolvedRepositoryIdentityRoots,
1030
};
1031
});
@@ -1772,6 +1775,7 @@ export const layerWsRpc = (
1775
},
1776
settings,
1777
shellResumeCompletionMarker: true,
1778
+ shellThreadFamilies: true,
1779
threadResumeCompletionMarker: true,
1780
threadSnapshotPagination: true,
1781
threadFind: true,
@@ -1818,6 +1822,26 @@ export const layerWsRpc = (
1822
),
1823
);
1824
1825
+ // Rows the shell can omit, read with the same snapshot sequence the shell uses.
1826
+ const readOmittableShellRows = Effect.fn("ws.orchestrationV2.readOmittableShellRows")(
1827
+ function* (
1828
+ options: { readonly subagentFamilyOf: ThreadId } | { readonly worktreePath: string },
1829
+ message: string,
1830
+ ) {
1831
+ const { threads, snapshotSequence } = yield* loadShellSnapshotParts({
1832
+ sql,
1833
+ readThreads: threadManagement.readShellSnapshot({ location: "active", ...options }),
1834
+ listProjects: Effect.succeed([]),
1835
+ latestSequence: applicationEvents.latestApplicationSequence,
1836
+ }).pipe(
1837
+ Effect.mapError(
1838
+ (cause) => new OrchestrationV2GetShellSnapshotError({ message, cause }),
1839
+ ),
1840
+ );
1841
+ return { snapshotSequence, threads: threads.threads };
1842
+ },
1843
+ );
1844
+
1845
const subscribeOrchestrationV2ArchivedShell = Effect.fn(
1846
"ws.orchestrationV2.subscribeArchivedShell",
1847
)(function* () {
@@ -1966,6 +1990,16 @@ export const layerWsRpc = (
1990
),
1991
[ORCHESTRATION_V2_WS_METHODS.getArchivedShellSnapshot]: (_input) =>
1992
getOrchestrationV2ArchivedShellSnapshot,
1993
+ [ORCHESTRATION_V2_WS_METHODS.getThreadFamily]: (input) =>
1994
+ readOmittableShellRows(
1995
+ { subagentFamilyOf: input.threadId },
1996
+ "Failed to load the thread family",
1997
+ ),
1998
+ [ORCHESTRATION_V2_WS_METHODS.getWorktreeThreadIds]: (input) =>
1999
+ readOmittableShellRows(
2000
+ { worktreePath: input.worktreePath },
2001
+ "Failed to load the worktree's threads",
2002
+ ).pipe(Effect.map(({ threads }) => ({ threadIds: threads.map((thread) => thread.id) }))),
2003
[ORCHESTRATION_V2_WS_METHODS.getThreadProjection]: (input) =>
2004
Effect.annotateCurrentSpan({ "orchestration_v2.thread_id": input.threadId }).pipe(
2005
Effect.andThen(
apps/web/src/components/ChatView.tsx
+9
-1
@@ -222,7 +222,7 @@ import {
222
primaryServerKeybindingsAtom,
223
serverEnvironment,
224
} from "../state/server";
225
-import { threadEnvironment } from "../state/threads";
225
+import { threadEnvironment, useThreadFamily } from "../state/threads";
226
import { resolveProviderSkillsForCwd } from "@t3tools/client-runtime/providerSkills";
227
import { vcsEnvironment } from "../state/vcs";
228
import {
@@ -466,6 +466,14 @@ export default function ChatView(props: ChatViewProps) {
466
});
467
const serverThreadProjection = useQuietThreadProjection(routeThreadDetailRef);
468
const serverProjection = serverThreadProjection?.projection ?? null;
469
+ // Subagent rows, an open child's own row and its ancestors come from the family when the shell
470
+ // leaves idle children out. Every source agrees on the root, so the key never flips.
471
+ useThreadFamily(
472
+ routeKind === "server" ? environmentId : null,
473
+ serverThreadShell?.lineage.rootThreadId ??
474
+ serverProjection?.thread.lineage.rootThreadId ??
475
+ null,
476
+ );
477
// Only the shell-less fallback needs these; with a shell, the shell carries them.
478
const fallbackDetailRef = serverThreadShell === null ? routeThreadDetailRef : null;
479
const fallbackUpdatedAt = useThreadUpdatedAt(fallbackDetailRef);
apps/web/src/components/chat/useThreadLifecycle.tsx
+5
-2
@@ -418,8 +418,11 @@ export function useThreadLifecycle(input: ThreadLifecycleInput) {
418
const threadRef = scopeThreadRef(environmentId, threadId);
419
const isEnvironmentLive = () =>
420
appAtomRegistry.get(environmentShell.stateValueAtom(environmentId)).status === "live";
421
+ // The shell can leave idle subagent children out, so absence is not deletion there: the
422
+ // route decides from the thread's own detail.
423
+ const shellOmitsChildren = serverConfig?.shellThreadFamilies === true;
424
// A just-launched child can reach this timeline before its shell syncs.
422
- if (isEnvironmentLive() && readThreadShell(threadRef) === null) {
425
+ if (!shellOmitsChildren && isEnvironmentLive() && readThreadShell(threadRef) === null) {
426
const location = router.latestLocation;
427
await waitForThreadShell(threadRef, RELATED_THREAD_SHELL_WAIT_MS);
428
if (
@@ -431,7 +434,7 @@ export function useThreadLifecycle(input: ThreadLifecycleInput) {
434
}
435
}
436
const shell = readThreadShell(threadRef);
434
- if (shell === null ? isEnvironmentLive() : shell.deletedAt != null) {
437
+ if (shell === null ? !shellOmitsChildren && isEnvironmentLive() : shell.deletedAt != null) {
438
toastManager.add({ type: "info", title: "This thread is no longer available" });
439
return;
440
}
apps/web/src/composerDraftStore.test.ts
+2
-1
@@ -3,6 +3,7 @@ import { createEnvironmentThreadShellAtoms } from "@t3tools/client-runtime/state
3
import {
4
applyShellStreamEvent,
5
createEnvironmentSnapshotAtom,
6
+ EMPTY_SHELL_STATE,
7
type EnvironmentShellState,
8
type EnvironmentShellStatus,
9
} from "@t3tools/client-runtime/state/shell";
@@ -1238,9 +1239,9 @@ function modelReconciliationHarness(
1239
],
1240
};
1241
const shellStateAtom = Atom.make<EnvironmentShellState>({
1242
+ ...EMPTY_SHELL_STATE,
1243
snapshot: Option.some(initialSnapshot),
1244
status: initialStatus,
1243
- error: Option.none(),
1245
});
1246
const shellResultAtom = Atom.map(shellStateAtom, AsyncResult.success);
1247
const snapshotAtom = createEnvironmentSnapshotAtom(() => shellResultAtom)(environmentId);
apps/web/src/hooks/useThreadActions.ts
+25
-4
@@ -28,6 +28,7 @@ import { environmentSession, readEnvironmentScope } from "../state/session";
28
import { appAtomRegistry } from "../rpc/atomRegistry";
29
import { environmentServerConfigsAtom } from "../state/server";
30
import { isScratchProject } from "@t3tools/client-runtime/state/projects";
31
+import { orchestrationEnvironment } from "../state/orchestration";
32
import { threadEnvironment } from "../state/threads";
33
import { vcsEnvironment } from "../state/vcs";
34
import { useNewThreadHandler } from "./useHandleNewThread";
@@ -290,6 +291,10 @@ export function useThreadActions() {
291
const loadSessionState = useAtomQueryRunner(environmentSession.sessionStateAtom, {
292
reportFailure: false,
293
});
294
+ const loadWorktreeThreadIds = useAtomQueryRunner(orchestrationEnvironment.worktreeThreadIds, {
295
+ reportFailure: false,
296
+ refresh: true,
297
+ });
298
const refreshVcsStatus = useAtomCommand(vcsEnvironment.refreshStatus, {
299
reportFailure: false,
300
});
@@ -435,16 +440,32 @@ export function useThreadActions() {
440
deletedIds && deletedIds.size > 0
441
? threads.filter((entry) => entry.id === threadRef.threadId || !deletedIds.has(entry.id))
442
: threads;
438
- const orphanedWorktreePath = getOrphanedWorktreePathForThread(
443
+ const environmentConfig = appAtomRegistry
444
+ .get(environmentServerConfigsAtom)
445
+ .get(threadRef.environmentId);
446
+ let orphanedWorktreePath = getOrphanedWorktreePathForThread(
447
survivingThreads,
448
threadRef.threadId,
449
);
450
+ // A shell that leaves idle subagent children out cannot prove nobody else uses the worktree,
451
+ // so the server's list decides. A failed read keeps the worktree.
452
+ if (orphanedWorktreePath !== null && environmentConfig?.shellThreadFamilies === true) {
453
+ const occupants = await loadWorktreeThreadIds({
454
+ environmentId: threadRef.environmentId,
455
+ input: { worktreePath: orphanedWorktreePath },
456
+ });
457
+ if (
458
+ occupants._tag !== "Success" ||
459
+ occupants.value.threadIds.some(
460
+ (threadId) => threadId !== threadRef.threadId && deletedIds?.has(threadId) !== true,
461
+ )
462
+ ) {
463
+ orphanedWorktreePath = null;
464
+ }
465
+ }
466
const displayWorktreePath = orphanedWorktreePath
467
? formatWorktreePathForDisplay(orphanedWorktreePath)
468
: null;
445
- const environmentConfig = appAtomRegistry
446
- .get(environmentServerConfigsAtom)
447
- .get(threadRef.environmentId);
469
const localApi = readLocalApi();
470
let canDeleteWorktree = false;
471
if (
apps/web/src/state/shell.test.ts
+2
-1
@@ -3,7 +3,7 @@ import {
3
PrimaryConnectionTarget,
4
} from "@t3tools/client-runtime/connection";
5
import type { EnvironmentCatalogState } from "@t3tools/client-runtime/state/connections";
6
-import type { EnvironmentShellState } from "@t3tools/client-runtime/state/shell";
6
+import { EMPTY_SHELL_STATE, type EnvironmentShellState } from "@t3tools/client-runtime/state/shell";
7
import { EnvironmentId } from "@t3tools/contracts";
8
import * as Option from "effect/Option";
9
import { Atom, AtomRegistry } from "effect/reactivity";
@@ -16,6 +16,7 @@ const REMOTE = EnvironmentId.make("remote");
16
17
function shellState(status: EnvironmentShellState["status"]): EnvironmentShellState {
18
return {
19
+ ...EMPTY_SHELL_STATE,
20
status,
21
snapshot:
22
status === "empty"
apps/web/src/state/threads.ts
+17
-2
@@ -8,18 +8,22 @@ import {
8
EMPTY_ENVIRONMENT_THREAD_STATE,
9
type EnvironmentThreadState,
10
createThreadEnvironmentAtoms,
11
+ createThreadFamilyAtoms,
12
} from "@t3tools/client-runtime/state/threads";
13
import type { EnvironmentId, OrchestrationV2ThreadShell, ThreadId } from "@t3tools/contracts";
14
import * as Option from "effect/Option";
15
import { AsyncResult, Atom } from "effect/reactivity";
16
+import { useEffect } from "react";
17
18
import { environmentCatalog } from "../connection/catalog";
19
import { connectionAtomRuntime } from "../connection/runtime";
18
-import { environmentSnapshotAtom } from "./shell";
20
+import { appAtomRegistry } from "../rpc/atomRegistry";
21
+import { environmentShell } from "./shell";
22
23
+const threadFamilies = createThreadFamilyAtoms(connectionAtomRuntime, environmentShell.stateAtom);
24
export const threadEnvironment = createThreadEnvironmentAtoms(
25
connectionAtomRuntime,
22
- environmentSnapshotAtom,
26
+ threadFamilies.snapshotAtom,
27
);
28
const environmentThreads = createEnvironmentThreadStateAtoms(connectionAtomRuntime);
29
export const environmentThreadDetails = createEnvironmentThreadDetailAtoms(
@@ -30,6 +34,17 @@ export const environmentThreadShells = createEnvironmentThreadShellAtoms({
34
snapshotAtom: threadEnvironment.snapshotAtom,
35
});
36
37
+/** Keeps the subagent tree under `rootThreadId` in the thread list while the caller shows it. */
38
+export function useThreadFamily(
39
+ environmentId: EnvironmentId | null,
40
+ rootThreadId: ThreadId | null,
41
+): void {
42
+ useEffect(() => {
43
+ if (environmentId === null || rootThreadId === null) return;
44
+ return threadFamilies.mount(appAtomRegistry, environmentId, rootThreadId);
45
+ }, [environmentId, rootThreadId]);
46
+}
47
+
48
const EMPTY_THREAD_STATE_ATOM = Atom.make(AsyncResult.success(EMPTY_ENVIRONMENT_THREAD_STATE)).pipe(
49
Atom.withLabel("web-environment-thread:empty"),
50
);
docs/internals/connection-runtime.md
+9
@@ -59,6 +59,15 @@ connection nor overwrite newer live data during a reconnect. Loading and
59
resuming snapshots belongs to the shared state services, so every view agrees
60
on which data is current.
61
62
+Servers that advertise `shellThreadFamilies` leave idle subagent children out of
63
+shell snapshots when the client asks. A child stays while it has a live or
64
+queued run, a pending request or background work, or a subagent child of its
65
+own, so badge and working walks never meet a gap. Other child rows come from the
66
+[thread family](../../packages/client-runtime/src/state/threadFamilies.ts) that
67
+a thread view or a queued message mounts. A missing shell row therefore does not
68
+prove a thread is gone: code that deletes data or a worktree on absence must
69
+check the family or the server first.
70
+
71
[Thread detail](../../packages/client-runtime/src/state/threads.ts) separates
72
subscription lifetime from cache lifetime. Mounted consumers share one live
73
stream, which stops when the last consumer unmounts; hidden mounted routes still
packages/client-runtime/src/state/orchestration.ts
+7
@@ -128,5 +128,12 @@ export function createOrchestrationEnvironmentAtoms<R, E>(
128
label: "environment-data:orchestration:archived-shell-snapshot",
129
tag: ORCHESTRATION_V2_WS_METHODS.getArchivedShellSnapshot,
130
}),
131
+ // Read right before deleting a worktree, so never served from cache.
132
+ worktreeThreadIds: createEnvironmentRpcQueryAtomFamily(runtime, {
133
+ label: "environment-data:orchestration:worktree-thread-ids",
134
+ tag: ORCHESTRATION_V2_WS_METHODS.getWorktreeThreadIds,
135
+ staleTimeMs: 0,
136
+ idleTtlMs: 0,
137
+ }),
138
};
139
}
packages/client-runtime/src/state/shell-sync.test.ts
+93
-1
@@ -27,7 +27,7 @@ import * as EnvironmentSupervisor from "../connection/supervisor.ts";
27
import * as Persistence from "../platform/persistence.ts";
28
import * as RpcSession from "../rpc/session.ts";
29
import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
30
-import { makeEnvironmentShellState } from "./shell.ts";
30
+import { type EnvironmentShellState, makeEnvironmentShellState } from "./shell.ts";
31
import * as ShellSnapshotLoader from "./shellSnapshotHttp.ts";
32
import { v2Project, v2ShellSnapshot, v2ThreadShell } from "./orchestrationV2TestFixtures.ts";
33
@@ -478,6 +478,98 @@ describe("environment shell synchronization", () => {
478
}),
479
);
480
481
+ it.effect("opts in to idle-child omission and counts authoritative snapshots and removals", () =>
482
+ Effect.gen(function* () {
483
+ const events = yield* Queue.unbounded<OrchestrationV2ShellStreamItem>();
484
+ const subscribeInput = yield* Deferred.make<unknown>();
485
+ const loadOptions = yield* Ref.make<ReadonlyArray<unknown>>([]);
486
+ const client = {
487
+ [ORCHESTRATION_V2_WS_METHODS.subscribeShell]: (input: unknown) =>
488
+ Stream.unwrap(
489
+ Deferred.succeed(subscribeInput, input).pipe(Effect.as(Stream.fromQueue(events))),
490
+ ),
491
+ } as unknown as WsRpcProtocolClient;
492
+ const familySession: RpcSession.RpcSession = {
493
+ ...session(client),
494
+ initialConfig: Effect.succeed({
495
+ shellResumeCompletionMarker: true,
496
+ shellThreadFamilies: true,
497
+ } as never),
498
+ };
499
+ const supervisor = EnvironmentSupervisor.EnvironmentSupervisor.of({
500
+ target: TARGET,
501
+ state: yield* SubscriptionRef.make(AVAILABLE_CONNECTION_STATE),
502
+ session: yield* SubscriptionRef.make(Option.some(familySession)),
503
+ prepared: yield* SubscriptionRef.make(Option.some(PREPARED)),
504
+ connect: Effect.void,
505
+ disconnect: Effect.void,
506
+ retryNow: Effect.void,
507
+ } satisfies EnvironmentSupervisor.EnvironmentSupervisor["Service"]);
508
+ const cache = Persistence.EnvironmentCacheStore.of({
509
+ loadShell: () => Effect.succeed(Option.none()),
510
+ saveShell: () => Effect.void,
511
+ loadThread: () => Effect.succeed(Option.none()),
512
+ saveThread: () => Effect.void,
513
+ removeThread: () => Effect.void,
514
+ loadServerConfig: () => Effect.succeed(Option.none()),
515
+ saveServerConfig: () => Effect.void,
516
+ loadVcsRefs: () => Effect.succeed(Option.none()),
517
+ saveVcsRefs: () => Effect.void,
518
+ removeVcsRefs: () => Effect.void,
519
+ clearVcsRefs: () => Effect.void,
520
+ clear: () => Effect.void,
521
+ });
522
+ const snapshotLoader = ShellSnapshotLoader.ShellSnapshotLoader.of({
523
+ load: (_prepared, options) =>
524
+ Ref.update(loadOptions, (all) => [...all, options]).pipe(
525
+ Effect.as(Option.some(LIVE_SHELL_SNAPSHOT)),
526
+ ),
527
+ });
528
+ const shellState = yield* makeEnvironmentShellState().pipe(
529
+ Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
530
+ Effect.provideService(Persistence.EnvironmentCacheStore, cache),
531
+ Effect.provideService(ShellSnapshotLoader.ShellSnapshotLoader, snapshotLoader),
532
+ );
533
+ const stateWhere = (predicate: (state: EnvironmentShellState) => boolean) =>
534
+ SubscriptionRef.changes(shellState).pipe(Stream.filter(predicate), Stream.runHead);
535
+
536
+ // Both transports must omit, or omitted children would come back through the socket.
537
+ expect(yield* Deferred.await(subscribeInput)).toMatchObject({
538
+ afterSequence: 1,
539
+ omitIdleSubagents: true,
540
+ });
541
+ expect(yield* Ref.get(loadOptions)).toEqual([{ omitIdleSubagents: true }]);
542
+ const loaded = Option.getOrThrow(yield* stateWhere((state) => state.generation > 0));
543
+ expect(loaded.removedAt.size).toBe(0);
544
+
545
+ const gone = ThreadId.make("thread-gone");
546
+ yield* Queue.offer(events, {
547
+ kind: "snapshot",
548
+ snapshot: { ...LIVE_SHELL_SNAPSHOT, threads: [] },
549
+ resolvedRepositoryIdentityRoots: [],
550
+ });
551
+ yield* Queue.offer(events, {
552
+ kind: "thread.removed",
553
+ sequence: 2,
554
+ location: "active",
555
+ threadId: gone,
556
+ });
557
+ const removed = Option.getOrThrow(yield* stateWhere((state) => state.removedAt.size > 0));
558
+ // An enrichment refresh is not authoritative.
559
+ expect(removed.generation).toBe(loaded.generation);
560
+ expect(removed.removedAt.get(gone)).toBe(2);
561
+
562
+ yield* Queue.offer(events, {
563
+ kind: "snapshot",
564
+ snapshot: { ...LIVE_SHELL_SNAPSHOT, snapshotSequence: 5 },
565
+ });
566
+ const reset = Option.getOrThrow(
567
+ yield* stateWhere((state) => state.generation > loaded.generation),
568
+ );
569
+ expect(reset.removedAt.size).toBe(0);
570
+ }),
571
+ );
572
+
573
it.effect("fills deferred cached pull request links without overwriting newer rows", () =>
574
Effect.gen(function* () {
575
const link = (number: number): ThreadPullRequestLink => ({
packages/client-runtime/src/state/shell.ts
+46
-7
@@ -45,12 +45,26 @@ export interface EnvironmentShellState {
45
readonly snapshot: Option.Option<OrchestrationV2ShellSnapshot>;
46
readonly status: EnvironmentShellStatus;
47
readonly error: Option.Option<string>;
48
+ /**
49
+ * Changes with each authoritative snapshot (not enrichment refreshes); 0 until the first one.
50
+ * Thread families read for an older generation may miss changes from before the latest snapshot,
51
+ * so they are read again.
52
+ */
53
+ readonly generation: number;
54
+ /** Sequences of the thread removals applied since the latest authoritative snapshot. */
55
+ readonly removedAt: ReadonlyMap<ThreadId, number>;
56
}
57
50
-const EMPTY_SHELL_STATE: EnvironmentShellState = {
58
+const EMPTY_REMOVALS: ReadonlyMap<ThreadId, number> = new Map();
59
+// Shared by every shell state, so a rebuilt one never reuses a generation another already used.
60
+let lastShellGeneration = 0;
61
+
62
+export const EMPTY_SHELL_STATE: EnvironmentShellState = {
63
snapshot: Option.none(),
64
status: "empty",
65
error: Option.none(),
66
+ generation: 0,
67
+ removedAt: EMPTY_REMOVALS,
68
};
69
70
function shellStatusForSnapshot(
@@ -86,9 +100,9 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
100
);
101
const cachedSnapshot = Option.map(cached, withoutDeferredPullRequests);
102
const state = yield* SubscriptionRef.make<EnvironmentShellState>({
103
+ ...EMPTY_SHELL_STATE,
104
snapshot: cachedSnapshot,
105
status: shellStatusForSnapshot(cachedSnapshot),
91
- error: Option.none(),
106
});
107
const awaitingCompletion = yield* Ref.make(false);
108
const lastAuthoritativeSession = yield* Ref.make<RpcSession | null>(null);
@@ -194,6 +208,8 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
208
}
209
continue;
210
}
211
+ const authoritative =
212
+ item.kind === "snapshot" && item.resolvedRepositoryIdentityRoots === undefined;
213
const nextSnapshot =
214
item.kind === "snapshot"
215
? mergeShellSnapshotProjects(
@@ -214,10 +230,21 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
230
});
231
if (nextSnapshot === null) continue;
232
receivedSnapshot ||= item.kind === "snapshot";
233
+ const removal =
234
+ item.kind === "thread.removed" &&
235
+ Option.exists(next.snapshot, (snapshot) => item.sequence > snapshot.snapshotSequence)
236
+ ? item
237
+ : null;
238
next = {
239
snapshot: Option.some(nextSnapshot),
240
status: waiting ? "synchronizing" : "live",
241
error: Option.none(),
242
+ generation: authoritative ? ++lastShellGeneration : next.generation,
243
+ removedAt: authoritative
244
+ ? EMPTY_REMOVALS
245
+ : removal === null
246
+ ? next.removedAt
247
+ : new Map(next.removedAt).set(removal.threadId, removal.sequence),
248
};
249
}
250
yield* Ref.set(awaitingCompletion, waiting);
@@ -321,9 +348,15 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
348
ORCHESTRATION_V2_WS_METHODS.subscribeShell,
349
Effect.fn("EnvironmentShellState.makeSubscribeInput")(function* (session) {
350
yield* Ref.set(activeSubscriptionSession, session);
324
- const supportsCompletionMarker = yield* session.initialConfig.pipe(
325
- Effect.map((config) => config.shellResumeCompletionMarker === true),
326
- Effect.orElseSucceed(() => false),
351
+ const { supportsCompletionMarker, omitIdleSubagents } = yield* session.initialConfig.pipe(
352
+ Effect.map((config) => ({
353
+ supportsCompletionMarker: config.shellResumeCompletionMarker === true,
354
+ omitIdleSubagents: config.shellThreadFamilies === true,
355
+ })),
356
+ Effect.orElseSucceed(() => ({
357
+ supportsCompletionMarker: false,
358
+ omitIdleSubagents: false,
359
+ })),
360
);
361
yield* Ref.set(awaitingCompletion, supportsCompletionMarker);
362
yield* setSynchronizing;
@@ -349,7 +382,8 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
382
}),
383
),
384
);
352
- const httpSnapshot = yield* snapshotLoader.load(prepared);
385
+ // HTTP and the socket must agree, or omitted children would return through the socket.
386
+ const httpSnapshot = yield* snapshotLoader.load(prepared, { omitIdleSubagents });
387
if (Option.isSome(httpSnapshot)) {
388
yield* cancelActiveFill;
389
const previous = yield* SubscriptionRef.get(state);
@@ -371,8 +405,12 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
405
}
406
}
407
408
+ const omission = omitIdleSubagents ? { omitIdleSubagents: true as const } : {};
409
if (!canResume || Option.isNone(current.snapshot)) {
375
- return supportsCompletionMarker ? { requestCompletionMarker: true as const } : {};
410
+ return {
411
+ ...omission,
412
+ ...(supportsCompletionMarker ? { requestCompletionMarker: true as const } : {}),
413
+ };
414
}
415
if (!supportsCompletionMarker) {
416
yield* SubscriptionRef.update(state, (value) => ({
@@ -383,6 +421,7 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
421
}
422
return {
423
afterSequence: current.snapshot.value.snapshotSequence,
424
+ ...omission,
425
...(supportsCompletionMarker ? { requestCompletionMarker: true as const } : {}),
426
};
427
}),
packages/client-runtime/src/state/shellSnapshotHttp.ts
+14
-3
@@ -33,17 +33,22 @@ export const fetchEnvironmentShellSnapshot = Effect.fn(
33
RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization["Service"]
34
>;
35
readonly timeoutMs?: number;
36
+ readonly omitIdleSubagents?: boolean;
37
}) {
38
+ const endpoint = {
39
+ query: input.omitIdleSubagents === true ? { omitIdleSubagents: "1" } : {},
40
+ };
41
return yield* executeAuthenticatedEnvironmentHttpRequest({
42
...input,
43
group: "orchestration",
44
method: "GET",
41
- url: (urls) => urls.shellSnapshot(),
45
+ url: (urls) => urls.shellSnapshot(endpoint),
46
timeoutMs: input.timeoutMs ?? DEFAULT_SHELL_SNAPSHOT_TIMEOUT_MS,
47
request: ({ client, headers }) =>
48
client
49
.shellSnapshot({
50
headers: withOrchestrationProtocolHeader(headers),
51
+ ...endpoint,
52
responseMode: "response-only",
53
})
54
.pipe(Effect.flatMap(decodeShellSnapshotResponse)),
@@ -80,6 +85,7 @@ export class ShellSnapshotLoader extends Context.Service<
85
{
86
readonly load: (
87
prepared: PreparedConnection,
88
+ options?: { readonly omitIdleSubagents?: boolean },
89
) => Effect.Effect<Option.Option<DeferredShellSnapshot>>;
90
}
91
>()("@t3tools/client-runtime/state/shellSnapshotHttp/ShellSnapshotLoader") {}
@@ -95,8 +101,13 @@ export const layer: Layer.Layer<ShellSnapshotLoader, never, HttpClient.HttpClien
101
RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization,
102
);
103
return ShellSnapshotLoader.of({
98
- load: (prepared: PreparedConnection) =>
99
- fetchEnvironmentShellSnapshot({ prepared, signer, remoteAuthorization }).pipe(
104
+ load: (prepared, options) =>
105
+ fetchEnvironmentShellSnapshot({
106
+ prepared,
107
+ signer,
108
+ remoteAuthorization,
109
+ ...(options?.omitIdleSubagents === true ? { omitIdleSubagents: true } : {}),
110
+ }).pipe(
111
Effect.map(Option.some<DeferredShellSnapshot>),
112
Effect.provideService(HttpClient.HttpClient, httpClient),
113
Effect.catchCause((cause) =>
packages/client-runtime/src/state/threadFamilies.test.ts
new
+193
@@ -0,0 +1,193 @@
1
+import {
2
+ EnvironmentId,
3
+ ORCHESTRATION_V2_WS_METHODS,
4
+ OrchestrationV2GetShellSnapshotError,
5
+ ThreadId,
6
+ type OrchestrationV2ShellSnapshot,
7
+ type OrchestrationV2ThreadFamily,
8
+ type OrchestrationV2ThreadShell,
9
+} from "@t3tools/contracts";
10
+import { describe, expect, it } from "@effect/vitest";
11
+import * as Effect from "effect/Effect";
12
+import * as Layer from "effect/Layer";
13
+import * as Option from "effect/Option";
14
+import * as Queue from "effect/Queue";
15
+import * as Stream from "effect/Stream";
16
+import * as SubscriptionRef from "effect/SubscriptionRef";
17
+import { AsyncResult, Atom, AtomRegistry } from "effect/reactivity";
18
+
19
+import {
20
+ AVAILABLE_CONNECTION_STATE,
21
+ PrimaryConnectionTarget,
22
+ type PreparedConnection,
23
+ type SupervisorConnectionState,
24
+} from "../connection/model.ts";
25
+import * as EnvironmentRegistry from "../connection/registry.ts";
26
+import * as EnvironmentSupervisor from "../connection/supervisor.ts";
27
+import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
28
+import type * as RpcSession from "../rpc/session.ts";
29
+import { EMPTY_SHELL_STATE, type EnvironmentShellState } from "./shell.ts";
30
+import {
31
+ createThreadFamilyAtoms,
32
+ threadFamilyRead,
33
+ threadFamilyRowsMissingFromShell,
34
+} from "./threadFamilies.ts";
35
+
36
+const row = (id: string, title = id) =>
37
+ ({ id: ThreadId.make(id), title }) as unknown as OrchestrationV2ThreadShell;
38
+
39
+describe("threadFamilyRowsMissingFromShell", () => {
40
+ it("adds only the rows the shell left out, once, with shell rows winning", () => {
41
+ const missing = threadFamilyRowsMissingFromShell({
42
+ shellThreads: [row("parent"), row("live", "live from shell")],
43
+ families: [
44
+ { snapshotSequence: 4, threads: [row("live", "stale family copy"), row("idle")] },
45
+ { snapshotSequence: 4, threads: [row("idle"), row("other")] },
46
+ ],
47
+ removedAt: new Map(),
48
+ });
49
+ expect(missing.map((thread) => thread.id)).toEqual(["idle", "other"]);
50
+ });
51
+
52
+ it("drops a family copy read before the shell removed that thread", () => {
53
+ const missing = threadFamilyRowsMissingFromShell({
54
+ shellThreads: [],
55
+ families: [
56
+ {
57
+ snapshotSequence: 5,
58
+ threads: [row("archived-after-read"), row("removed-before-read")],
59
+ },
60
+ ],
61
+ removedAt: new Map([
62
+ [ThreadId.make("archived-after-read"), 7],
63
+ [ThreadId.make("removed-before-read"), 3],
64
+ ]),
65
+ });
66
+ expect(missing.map((thread) => thread.id)).toEqual(["removed-before-read"]);
67
+ });
68
+});
69
+
70
+const TARGET = new PrimaryConnectionTarget({
71
+ environmentId: EnvironmentId.make("environment-family"),
72
+ label: "Family environment",
73
+ httpBaseUrl: "https://family.example.test",
74
+ wsBaseUrl: "wss://family.example.test",
75
+});
76
+
77
+describe("createThreadFamilyAtoms", () => {
78
+ it.effect("reads a family per shell generation and retries a failed read", () =>
79
+ Effect.scoped(
80
+ Effect.gen(function* () {
81
+ const replies =
82
+ yield* Queue.unbounded<
83
+ Effect.Effect<OrchestrationV2ThreadFamily, OrchestrationV2GetShellSnapshotError>
84
+ >();
85
+ const client = {
86
+ [ORCHESTRATION_V2_WS_METHODS.getThreadFamily]: () => Effect.flatten(Queue.take(replies)),
87
+ } as unknown as WsRpcProtocolClient;
88
+ const session = {
89
+ client,
90
+ initialConfig: Effect.succeed({ shellThreadFamilies: true } as never),
91
+ ready: Effect.void,
92
+ probe: Effect.void,
93
+ closed: Effect.never,
94
+ } as unknown as RpcSession.RpcSession;
95
+ const supervisor = EnvironmentSupervisor.EnvironmentSupervisor.of({
96
+ target: TARGET,
97
+ state: yield* SubscriptionRef.make<SupervisorConnectionState>({
98
+ ...AVAILABLE_CONNECTION_STATE,
99
+ desired: true,
100
+ network: "online",
101
+ phase: "connected",
102
+ attempt: 1,
103
+ generation: 1,
104
+ }),
105
+ session: yield* SubscriptionRef.make(Option.some(session)),
106
+ prepared: yield* SubscriptionRef.make(Option.none<PreparedConnection>()),
107
+ connect: Effect.void,
108
+ disconnect: Effect.void,
109
+ retryNow: Effect.void,
110
+ } satisfies EnvironmentSupervisor.EnvironmentSupervisor["Service"]);
111
+ const run: EnvironmentRegistry.EnvironmentRegistry["Service"]["run"] = (
112
+ _environmentId,
113
+ effect,
114
+ ) => Effect.provideService(effect, EnvironmentSupervisor.EnvironmentSupervisor, supervisor);
115
+ const followStream: EnvironmentRegistry.EnvironmentRegistry["Service"]["followStream"] = (
116
+ _environmentId,
117
+ stream,
118
+ ) => Stream.provideService(stream, EnvironmentSupervisor.EnvironmentSupervisor, supervisor);
119
+ const runtime = Atom.runtime(
120
+ Layer.succeed(
121
+ EnvironmentRegistry.EnvironmentRegistry,
122
+ EnvironmentRegistry.EnvironmentRegistry.of({
123
+ run,
124
+ followStream,
125
+ } as unknown as EnvironmentRegistry.EnvironmentRegistry["Service"]),
126
+ ),
127
+ );
128
+ const parent = row("parent");
129
+ const child = row("idle-child");
130
+ const shellSnapshot = {
131
+ schemaVersion: 1,
132
+ snapshotSequence: 3,
133
+ projects: [],
134
+ threads: [parent],
135
+ archivedThreads: [],
136
+ } as OrchestrationV2ShellSnapshot;
137
+ const shellAt = (generation: number): EnvironmentShellState => ({
138
+ ...EMPTY_SHELL_STATE,
139
+ status: "live",
140
+ snapshot: Option.some(shellSnapshot),
141
+ generation,
142
+ });
143
+ const shellState = Atom.make<AsyncResult.AsyncResult<EnvironmentShellState>>(
144
+ AsyncResult.success(shellAt(0)),
145
+ );
146
+ const families = createThreadFamilyAtoms(runtime, () => shellState);
147
+ const registry = yield* Effect.acquireRelease(Effect.sync(AtomRegistry.make), (registry) =>
148
+ Effect.sync(() => registry.dispose()),
149
+ );
150
+ const family = families.familyAtom(TARGET.environmentId, parent.id);
151
+ const mergedIds = () =>
152
+ registry.get(families.snapshotAtom(TARGET.environmentId))?.threads.map(({ id }) => id);
153
+ // Waits for the read to finish either way; the assertions read its outcome.
154
+ const settle = AtomRegistry.getResult(registry, family, { suspendOnWaiting: true }).pipe(
155
+ Effect.ignore,
156
+ Effect.tap(() => Effect.yieldNow),
157
+ );
158
+ registry.mount(families.snapshotAtom(TARGET.environmentId));
159
+ families.mount(registry, TARGET.environmentId, parent.id);
160
+
161
+ // A cached shell from before this session's first snapshot reads nothing.
162
+ expect(threadFamilyRead(registry.get(family))).toBe("pending");
163
+ expect(yield* Queue.size(replies)).toBe(0);
164
+
165
+ registry.set(shellState, AsyncResult.success(shellAt(1)));
166
+ yield* Queue.offer(replies, Effect.succeed({ snapshotSequence: 3, threads: [child] }));
167
+ yield* settle;
168
+ expect(threadFamilyRead(registry.get(family))).toBe("settled");
169
+ expect(mergedIds()).toEqual(["parent", "idle-child"]);
170
+
171
+ // A new authoritative snapshot never reuses the old read, even while the next one waits
172
+ // or fails.
173
+ registry.set(shellState, AsyncResult.success(shellAt(2)));
174
+ expect(threadFamilyRead(registry.get(family))).toBe("pending");
175
+ expect(mergedIds()).toEqual(["parent"]);
176
+ yield* Queue.offer(
177
+ replies,
178
+ Effect.fail(new OrchestrationV2GetShellSnapshotError({ message: "read failed" })),
179
+ );
180
+ yield* settle;
181
+ expect(threadFamilyRead(registry.get(family))).toBe("failed");
182
+ expect(mergedIds()).toEqual(["parent"]);
183
+
184
+ families.refresh(registry, TARGET.environmentId, parent.id);
185
+ expect(threadFamilyRead(registry.get(family))).toBe("pending");
186
+ yield* Queue.offer(replies, Effect.succeed({ snapshotSequence: 5, threads: [child] }));
187
+ yield* settle;
188
+ expect(threadFamilyRead(registry.get(family))).toBe("settled");
189
+ expect(mergedIds()).toEqual(["parent", "idle-child"]);
190
+ }),
191
+ ),
192
+ );
193
+});
packages/client-runtime/src/state/threadFamilies.ts
new
+226
@@ -0,0 +1,226 @@
1
+import {
2
+ ORCHESTRATION_V2_WS_METHODS,
3
+ type EnvironmentId,
4
+ type OrchestrationV2ShellSnapshot,
5
+ type OrchestrationV2ThreadFamily,
6
+ type OrchestrationV2ThreadShell,
7
+ type ThreadId,
8
+} from "@t3tools/contracts";
9
+import * as Effect from "effect/Effect";
10
+import * as Option from "effect/Option";
11
+import * as SubscriptionRef from "effect/SubscriptionRef";
12
+import { AsyncResult, Atom, type AtomRegistry } from "effect/reactivity";
13
+
14
+import * as EnvironmentSupervisor from "../connection/supervisor.ts";
15
+import type * as EnvironmentRegistry from "../connection/registry.ts";
16
+import { EnvironmentRpcUnavailableError, request } from "../rpc/client.ts";
17
+import { arrayElementsEqual } from "./entities.ts";
18
+import { createEnvironmentQueryAtomFamily, selectEnvironmentQueryData } from "./runtime.ts";
19
+import type { EnvironmentShellState } from "./shell.ts";
20
+
21
+const EMPTY_FAMILY: OrchestrationV2ThreadFamily = { snapshotSequence: 0, threads: [] };
22
+const EMPTY_MOUNTS: ReadonlyMap<ThreadId, number> = new Map();
23
+// Generation 0 is the cached shell from before this session's first authoritative snapshot. A read
24
+// for it would be thrown away once that snapshot lands, so it waits instead.
25
+const AWAITING_AUTHORITATIVE_SHELL = AsyncResult.initial<never, never>(true);
26
+
27
+/** Whether a family read can decide anything yet. Only a settled read can prove a thread is gone. */
28
+export type ThreadFamilyRead = "pending" | "failed" | "settled";
29
+
30
+export function threadFamilyRead(
31
+ result: AsyncResult.AsyncResult<OrchestrationV2ThreadFamily, unknown>,
32
+): ThreadFamilyRead {
33
+ // A failure whose retry is in flight is pending, so callers do not restart that retry.
34
+ if (result.waiting) return "pending";
35
+ if (AsyncResult.isFailure(result)) return "failed";
36
+ return AsyncResult.isSuccess(result) ? "settled" : "pending";
37
+}
38
+
39
+/**
40
+ * Family rows the shell does not have. A shell row is at least as new as any family copy, since
41
+ * shell deltas carry every change; a family copy read before the shell removed that thread is
42
+ * stale.
43
+ */
44
+export function threadFamilyRowsMissingFromShell(input: {
45
+ readonly shellThreads: ReadonlyArray<OrchestrationV2ThreadShell>;
46
+ readonly families: ReadonlyArray<OrchestrationV2ThreadFamily>;
47
+ readonly removedAt: ReadonlyMap<ThreadId, number>;
48
+}): ReadonlyArray<OrchestrationV2ThreadShell> {
49
+ const present = new Set<ThreadId>(input.shellThreads.map((thread) => thread.id));
50
+ const missing: OrchestrationV2ThreadShell[] = [];
51
+ for (const family of input.families) {
52
+ for (const thread of family.threads) {
53
+ if (present.has(thread.id)) continue;
54
+ if ((input.removedAt.get(thread.id) ?? -1) > family.snapshotSequence) continue;
55
+ present.add(thread.id);
56
+ missing.push(thread);
57
+ }
58
+ }
59
+ return missing;
60
+}
61
+
62
+/**
63
+ * Shells that omit idle subagent children (`omitIdleSubagents`) leave those rows to thread
64
+ * families: the active subagent tree that shares a thread's `lineage.rootThreadId`. A view, or a
65
+ * queued message, mounts the family it needs; it is read once per shell generation. Family rows
66
+ * merge behind shell rows and are never persisted. Shell deltas still carry every change, so a
67
+ * changed child always arrives as a shell row, which wins.
68
+ */
69
+export function createThreadFamilyAtoms<R, ER, E>(
70
+ runtime: Atom.AtomRuntime<EnvironmentRegistry.EnvironmentRegistry | R, ER>,
71
+ shellStateAtom: (
72
+ environmentId: EnvironmentId,
73
+ ) => Atom.Atom<AsyncResult.AsyncResult<EnvironmentShellState, E>>,
74
+) {
75
+ const shellStateValue = (state: AsyncResult.AsyncResult<EnvironmentShellState, E>) =>
76
+ Option.getOrNull(AsyncResult.value(state));
77
+ const generationAtom = Atom.family((environmentId: EnvironmentId) =>
78
+ Atom.make((get) => shellStateValue(get(shellStateAtom(environmentId)))?.generation ?? 0).pipe(
79
+ Atom.withLabel(`environment-shell-generation:${environmentId}`),
80
+ ),
81
+ );
82
+
83
+ // The generation is part of the key, so a read from before the latest authoritative snapshot is
84
+ // never used again, even while a new read is pending or failed.
85
+ const familyQueryAtom = createEnvironmentQueryAtomFamily(runtime, {
86
+ label: "environment-data:orchestration:thread-family",
87
+ staleTimeMs: Number.POSITIVE_INFINITY,
88
+ idleTtlMs: 60_000,
89
+ execute: Effect.fn("ThreadFamilies.read")(function* (input: {
90
+ readonly threadId: ThreadId;
91
+ readonly generation: number;
92
+ }) {
93
+ const supervisor = yield* EnvironmentSupervisor.EnvironmentSupervisor;
94
+ const session = yield* SubscriptionRef.get(supervisor.session);
95
+ if (Option.isNone(session)) {
96
+ return yield* new EnvironmentRpcUnavailableError({
97
+ environmentId: supervisor.target.environmentId,
98
+ message: "The environment has no session.",
99
+ });
100
+ }
101
+ // A config failure fails the read: an empty family would read as "the thread is gone".
102
+ const config = yield* session.value.initialConfig;
103
+ // Servers without families send every child in the shell, so absent means gone.
104
+ if (config.shellThreadFamilies !== true) return EMPTY_FAMILY;
105
+ return yield* request(ORCHESTRATION_V2_WS_METHODS.getThreadFamily, {
106
+ threadId: input.threadId,
107
+ });
108
+ }),
109
+ });
110
+ const queryFor = (environmentId: EnvironmentId, threadId: ThreadId, generation: number) =>
111
+ familyQueryAtom({ environmentId, input: { threadId, generation } });
112
+
113
+ const familyAtom = Atom.family((key: string) => {
114
+ const [environmentId, threadId] = JSON.parse(key) as [EnvironmentId, ThreadId];
115
+ return Atom.make((get) => {
116
+ const generation = get(generationAtom(environmentId));
117
+ return generation === 0
118
+ ? AWAITING_AUTHORITATIVE_SHELL
119
+ : get(queryFor(environmentId, threadId, generation));
120
+ }).pipe(Atom.withLabel(`environment-thread-family:${key}`));
121
+ });
122
+ const familyKey = (environmentId: EnvironmentId, threadId: ThreadId) =>
123
+ JSON.stringify([environmentId, threadId]);
124
+
125
+ /** Reads the current generation's family again, so a failed read does not last the session. */
126
+ const refresh = (
127
+ registry: AtomRegistry.AtomRegistry,
128
+ environmentId: EnvironmentId,
129
+ threadId: ThreadId,
130
+ ) => {
131
+ const generation = registry.get(generationAtom(environmentId));
132
+ if (generation !== 0) registry.refresh(queryFor(environmentId, threadId, generation));
133
+ };
134
+
135
+ const mountsAtom = Atom.family((environmentId: EnvironmentId) =>
136
+ Atom.make(EMPTY_MOUNTS).pipe(
137
+ Atom.keepAlive,
138
+ Atom.withLabel(`environment-thread-family-mounts:${environmentId}`),
139
+ ),
140
+ );
141
+
142
+ /** Keeps a thread's family in the merged rows until the returned release runs. */
143
+ const mount = (
144
+ registry: AtomRegistry.AtomRegistry,
145
+ environmentId: EnvironmentId,
146
+ threadId: ThreadId,
147
+ ): (() => void) => {
148
+ const atom = mountsAtom(environmentId);
149
+ const mounts = registry.get(atom);
150
+ registry.set(atom, new Map(mounts).set(threadId, (mounts.get(threadId) ?? 0) + 1));
151
+ // Mounting again after a failure retries instead of keeping the failure until reconnect.
152
+ if (
153
+ threadFamilyRead(registry.get(familyAtom(familyKey(environmentId, threadId)))) === "failed"
154
+ ) {
155
+ refresh(registry, environmentId, threadId);
156
+ }
157
+ let released = false;
158
+ return () => {
159
+ if (released) return;
160
+ released = true;
161
+ const next = new Map(registry.get(atom));
162
+ const count = (next.get(threadId) ?? 0) - 1;
163
+ if (count > 0) next.set(threadId, count);
164
+ else next.delete(threadId);
165
+ registry.set(atom, next);
166
+ };
167
+ };
168
+
169
+ const snapshotAtom = Atom.family((environmentId: EnvironmentId) => {
170
+ let previous: {
171
+ readonly snapshot: OrchestrationV2ShellSnapshot;
172
+ readonly removedAt: ReadonlyMap<ThreadId, number>;
173
+ readonly families: ReadonlyArray<OrchestrationV2ThreadFamily>;
174
+ readonly merged: OrchestrationV2ShellSnapshot;
175
+ } | null = null;
176
+ return Atom.make((get): OrchestrationV2ShellSnapshot | null => {
177
+ const state = shellStateValue(get(shellStateAtom(environmentId)));
178
+ const snapshot = state === null ? null : Option.getOrNull(state.snapshot);
179
+ const mounts = get(mountsAtom(environmentId));
180
+ if (snapshot === null || state === null || mounts.size === 0) return snapshot;
181
+ const families = [...mounts.keys()].flatMap((threadId) => {
182
+ const family = selectEnvironmentQueryData(
183
+ get(familyAtom(familyKey(environmentId, threadId))),
184
+ );
185
+ return family === null ? [] : [family];
186
+ });
187
+ // Most shell updates move only the cursor. With the same rows, removals and families, keep
188
+ // the merged rows so thread lists skip their rebuild.
189
+ const unchanged =
190
+ previous !== null &&
191
+ previous.snapshot.threads === snapshot.threads &&
192
+ previous.removedAt === state.removedAt &&
193
+ arrayElementsEqual(previous.families, families);
194
+ if (unchanged && previous !== null && previous.snapshot === snapshot) return previous.merged;
195
+ let merged: OrchestrationV2ShellSnapshot;
196
+ if (unchanged && previous !== null) {
197
+ merged =
198
+ previous.merged === previous.snapshot
199
+ ? snapshot
200
+ : { ...snapshot, threads: previous.merged.threads };
201
+ } else {
202
+ const extras = threadFamilyRowsMissingFromShell({
203
+ shellThreads: snapshot.threads,
204
+ removedAt: state.removedAt,
205
+ families,
206
+ });
207
+ merged =
208
+ extras.length === 0
209
+ ? snapshot
210
+ : { ...snapshot, threads: [...snapshot.threads, ...extras] };
211
+ }
212
+ previous = { snapshot, removedAt: state.removedAt, families, merged };
213
+ return merged;
214
+ }).pipe(Atom.withLabel(`environment-snapshot-with-families:${environmentId}`));
215
+ });
216
+
217
+ return {
218
+ /** The shell snapshot plus the rows of every mounted family. */
219
+ snapshotAtom,
220
+ /** The current generation's family read, for decisions that need a settled answer. */
221
+ familyAtom: (environmentId: EnvironmentId, threadId: ThreadId) =>
222
+ familyAtom(familyKey(environmentId, threadId)),
223
+ mount,
224
+ refresh,
225
+ };
226
+}
packages/client-runtime/src/state/threads.ts
+1
@@ -1047,5 +1047,6 @@ export * from "./composerPathSearch.ts";
1047
export * from "./threadCommands.ts";
1048
export * from "./threadFeedback.ts";
1049
export * from "./threadDetail.ts";
1050
+export * from "./threadFamilies.ts";
1051
export * from "./threadShell.ts";
1052
export * from "./threadState.ts";
packages/contracts/src/environmentHttp.ts
+5
@@ -667,6 +667,10 @@ const EnvironmentOrchestrationThreadSnapshotParams = Schema.Struct({
667
threadId: ThreadId,
668
});
669
670
+const EnvironmentOrchestrationShellSnapshotQuery = Schema.Struct({
671
+ omitIdleSubagents: Schema.optionalKey(Schema.String),
672
+});
673
+
674
const EnvironmentOrchestrationThreadBoundedSnapshotQuery = Schema.Struct({
675
compactTurnItems: Schema.optionalKey(Schema.String),
676
});
@@ -688,6 +692,7 @@ class EnvironmentOrchestrationHttpApi extends HttpApiGroup.make("orchestration")
692
.add(
693
HttpApiEndpoint.get("shellSnapshot", "/api/orchestration/shell", {
694
headers: OrchestrationProtocolHeaders,
695
+ query: EnvironmentOrchestrationShellSnapshotQuery,
696
success: OrchestrationV2ShellSnapshot,
697
error: EnvironmentOrchestrationSnapshotErrors,
698
}).middleware(EnvironmentAuthenticatedAuth),
packages/contracts/src/orchestrationV2.ts
+70
@@ -1962,6 +1962,33 @@ export const OrchestrationV2ThreadShell = Schema.Struct({
1962
});
1963
export type OrchestrationV2ThreadShell = typeof OrchestrationV2ThreadShell.Type;
1964
1965
+const LIVE_SHELL_STATUSES: ReadonlySet<OrchestrationV2ShellThreadStatus> = new Set([
1966
+ "queued",
1967
+ "preparing",
1968
+ "starting",
1969
+ "running",
1970
+ "waiting",
1971
+]);
1972
+
1973
+/**
1974
+ * A subagent child that can still need the user or hold its parent. Shells that omit idle children
1975
+ * keep these, so every reader of live child rows (pending requests, working parents, background
1976
+ * work) still finds them.
1977
+ */
1978
+export function isLiveSubagentShell(
1979
+ thread: Pick<
1980
+ OrchestrationV2ThreadShell,
1981
+ "activityRunStatus" | "status" | "pendingRuntimeRequest" | "pendingBackgroundTasks"
1982
+ >,
1983
+): boolean {
1984
+ return (
1985
+ (thread.activityRunStatus ?? null) !== null ||
1986
+ LIVE_SHELL_STATUSES.has(thread.status) ||
1987
+ thread.pendingRuntimeRequest !== null ||
1988
+ (thread.pendingBackgroundTasks?.length ?? 0) > 0
1989
+ );
1990
+}
1991
+
1992
export const OrchestrationV2ThreadShellSnapshot = Schema.Struct({
1993
schemaVersion: PositiveInt,
1994
snapshotSequence: NonNegativeInt,
@@ -3190,6 +3217,8 @@ export const ORCHESTRATION_V2_WS_METHODS = {
3217
searchThread: "orchestration.searchThread",
3218
searchThreadStream: "orchestration.searchThreadStream",
3219
getArchivedShellSnapshot: "orchestration.getArchivedShellSnapshot",
3220
+ getThreadFamily: "orchestration.getThreadFamily",
3221
+ getWorktreeThreadIds: "orchestration.getWorktreeThreadIds",
3222
getThreadProjection: "orchestration.getThreadProjection",
3223
getWorkflowScript: "orchestration.getWorkflowScript",
3224
stopWorkflow: "orchestration.stopWorkflow",
@@ -3307,9 +3336,42 @@ export type OrchestrationV2GetThreadProjectionInput =
3336
export const OrchestrationV2SubscribeShellInput = Schema.Struct({
3337
afterSequence: Schema.optionalKey(NonNegativeInt),
3338
requestCompletionMarker: Schema.optionalKey(Schema.Boolean),
3339
+ /**
3340
+ * Snapshots leave out idle subagent children; read them with `getThreadFamily`. Send only to
3341
+ * servers that advertise `shellThreadFamilies`.
3342
+ */
3343
+ omitIdleSubagents: Schema.optionalKey(Schema.Boolean),
3344
});
3345
export type OrchestrationV2SubscribeShellInput = typeof OrchestrationV2SubscribeShellInput.Type;
3346
3347
+export const OrchestrationV2GetThreadFamilyInput = Schema.Struct({
3348
+ threadId: ThreadId,
3349
+});
3350
+export type OrchestrationV2GetThreadFamilyInput = typeof OrchestrationV2GetThreadFamilyInput.Type;
3351
+
3352
+/**
3353
+ * The active subagent threads that share the requested thread's `lineage.rootThreadId`: its whole
3354
+ * subagent tree, in any run state. An unknown thread has an empty family; a deleted one still
3355
+ * names its root.
3356
+ */
3357
+export const OrchestrationV2ThreadFamily = Schema.Struct({
3358
+ snapshotSequence: NonNegativeInt,
3359
+ threads: Schema.Array(OrchestrationV2ThreadShell),
3360
+});
3361
+export type OrchestrationV2ThreadFamily = typeof OrchestrationV2ThreadFamily.Type;
3362
+
3363
+export const OrchestrationV2GetWorktreeThreadIdsInput = Schema.Struct({
3364
+ worktreePath: TrimmedNonEmptyString,
3365
+});
3366
+export type OrchestrationV2GetWorktreeThreadIdsInput =
3367
+ typeof OrchestrationV2GetWorktreeThreadIdsInput.Type;
3368
+
3369
+/** Active threads on a worktree path, including subagent children a shell may leave out. */
3370
+export const OrchestrationV2WorktreeThreadIds = Schema.Struct({
3371
+ threadIds: Schema.Array(ThreadId),
3372
+});
3373
+export type OrchestrationV2WorktreeThreadIds = typeof OrchestrationV2WorktreeThreadIds.Type;
3374
+
3375
export const OrchestrationV2SubscribeThreadInput = Schema.Struct({
3376
threadId: ThreadId,
3377
afterSequence: Schema.optionalKey(NonNegativeInt),
@@ -3679,6 +3741,14 @@ export const OrchestrationV2RpcSchemas = {
3741
input: Schema.Struct({}),
3742
output: OrchestrationV2ArchivedShellSnapshot,
3743
},
3744
+ getThreadFamily: {
3745
+ input: OrchestrationV2GetThreadFamilyInput,
3746
+ output: OrchestrationV2ThreadFamily,
3747
+ },
3748
+ getWorktreeThreadIds: {
3749
+ input: OrchestrationV2GetWorktreeThreadIdsInput,
3750
+ output: OrchestrationV2WorktreeThreadIds,
3751
+ },
3752
getThreadProjection: {
3753
input: OrchestrationV2GetThreadProjectionInput,
3754
output: OrchestrationV2ThreadProjection,
packages/contracts/src/rpc.ts
+17
@@ -1681,6 +1681,21 @@ const WsOrchestrationV2GetArchivedShellSnapshotRpc = Rpc.make(
1681
},
1682
);
1683
1684
+const WsOrchestrationV2GetThreadFamilyRpc = Rpc.make(ORCHESTRATION_V2_WS_METHODS.getThreadFamily, {
1685
+ payload: OrchestrationV2RpcSchemas.getThreadFamily.input,
1686
+ success: OrchestrationV2RpcSchemas.getThreadFamily.output,
1687
+ error: Schema.Union([OrchestrationV2GetShellSnapshotError, EnvironmentAuthorizationError]),
1688
+});
1689
+
1690
+const WsOrchestrationV2GetWorktreeThreadIdsRpc = Rpc.make(
1691
+ ORCHESTRATION_V2_WS_METHODS.getWorktreeThreadIds,
1692
+ {
1693
+ payload: OrchestrationV2RpcSchemas.getWorktreeThreadIds.input,
1694
+ success: OrchestrationV2RpcSchemas.getWorktreeThreadIds.output,
1695
+ error: Schema.Union([OrchestrationV2GetShellSnapshotError, EnvironmentAuthorizationError]),
1696
+ },
1697
+);
1698
+
1699
const WsOrchestrationV2GetThreadProjectionRpc = Rpc.make(
1700
ORCHESTRATION_V2_WS_METHODS.getThreadProjection,
1701
{
@@ -2082,6 +2097,8 @@ export const WsRpcGroup = RpcGroup.make(
2097
WsOrchestrationV2SearchThreadRpc,
2098
WsOrchestrationV2SearchThreadStreamRpc,
2099
WsOrchestrationV2GetArchivedShellSnapshotRpc,
2100
+ WsOrchestrationV2GetThreadFamilyRpc,
2101
+ WsOrchestrationV2GetWorktreeThreadIdsRpc,
2102
WsOrchestrationV2GetThreadProjectionRpc,
2103
WsOrchestrationV2LaunchThreadRpc,
2104
WsOrchestrationV2SubscribeArchivedShellRpc,
packages/contracts/src/server.ts
+5
@@ -626,6 +626,11 @@ export const ServerConfig = Schema.Struct({
626
observability: ServerObservability,
627
settings: ServerSettings,
628
shellResumeCompletionMarker: Schema.optionalKey(Schema.Boolean),
629
+ /**
630
+ * The shell can leave idle subagent children out of snapshots (`omitIdleSubagents`), and
631
+ * `getThreadFamily` and `getWorktreeThreadIds` serve the rows it leaves out.
632
+ */
633
+ shellThreadFamilies: Schema.optionalKey(Schema.Boolean),
634
shellRevealInFileManager: Schema.optionalKey(Schema.Boolean),
635
shellRevealInFileManagerKind: Schema.optionalKey(FileManagerRevealKind),
636
threadResumeCompletionMarker: Schema.optionalKey(Schema.Boolean),