@devries-cameron20 / t3code Mirror · read-only / commits / 67c3afbd58
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 18:15 UTC

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),