The best way to control Claude Code, Codex and more from any computer or phone
feat(server): delegate_task to a linked environment (#16719)
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: Lenori <122464369+Lenoridev@users.noreply.github.com>
Julius Marminge committed
Oct 27, 2026 at 14:04 UTC
594f1ce2eb3f1a2f41e71476a83b1522c5b65dd9
67 files changed
+5156
-322
apps/mobile/src/features/home/useThreadListActions.test.ts
+4
-1
@@ -114,7 +114,10 @@ vi.mock("../../state/thread-order", () => ({
114
},
115
}));
116
vi.mock("../../state/threads", () => ({
117
- environmentThreadShells: { threadShellsAtom: "thread-shells" },
117
+ environmentThreadShells: {
118
+ threadShellsAtom: "thread-shells",
119
+ navigationThreadShellsAtom: "thread-shells",
120
+ },
121
threadEnvironment: Object.fromEntries(
122
[
123
"archive",
apps/mobile/src/features/home/useThreadListActions.ts
+1
-1
@@ -611,7 +611,7 @@ export function useThreadListActions(): {
611
const moveThread = async (thread: EnvironmentThreadShell, direction: ThreadMoveDestination) => {
612
if (!checkThreadOperationPermission(thread, "Could not move thread")) return false;
613
if (getPendingThreadOrder() !== null || appAtomRegistry.get(threadDropBusyAtom)) return false;
614
- const shells = appAtomRegistry.get(environmentThreadShells.threadShellsAtom);
614
+ const shells = appAtomRegistry.get(environmentThreadShells.navigationThreadShellsAtom);
615
const current = shells.find(
616
(row) => row.id === thread.id && row.environmentId === thread.environmentId,
617
);
apps/mobile/src/features/threads/SubagentRow.tsx
+11
-2
@@ -26,14 +26,17 @@ type SubagentRowSubagent = Pick<
26
| "status"
27
| "progress"
28
| "result"
29
+ | "remoteChild"
30
>;
31
32
export function SubagentRow(props: {
33
readonly environmentId: EnvironmentId;
34
readonly subagent: SubagentRowSubagent;
35
readonly elapsed: ReactNode;
36
+ /** The task runs in a linked environment this app is connected to. */
37
+ readonly canOpenRemote?: boolean;
38
}) {
36
- const presentation = resolveSubagentRowPresentation(props.subagent);
39
+ const presentation = resolveSubagentRowPresentation(props.subagent, props.canOpenRemote);
40
const detail = subagentCardDetail(presentation.detail);
41
return (
42
<View className="flex-row gap-3">
@@ -64,6 +67,11 @@ export function SubagentRow(props: {
67
>
68
{presentation.statusLabel}
69
</Text>
70
+ {presentation.runsOn !== null ? (
71
+ <Text numberOfLines={1} className="shrink text-xs text-foreground-muted">
72
+ on {presentation.runsOn}
73
+ </Text>
74
+ ) : null}
75
</View>
76
{props.elapsed}
77
{presentation.canOpenThread ? (
@@ -92,7 +100,8 @@ function SubagentMetadata(props: {
100
readonly subagent: SubagentRowSubagent;
101
}) {
102
const { environmentId, subagent } = props;
95
- const config = useEnvironmentServerConfig(environmentId);
103
+ // A task in a linked environment runs a provider instance of that environment.
104
+ const config = useEnvironmentServerConfig(subagent.remoteChild?.environmentId ?? environmentId);
105
const provider = config?.providers.find(
106
(candidate) => candidate.instanceId === subagent.providerInstanceId,
107
);
apps/mobile/src/features/threads/ThreadAgentsSheet.tsx
+20
-10
@@ -20,10 +20,12 @@ import { AppText as Text } from "../../components/ui/AppText";
20
import { environmentThreadDetails } from "../../state/threads";
21
import { NativeStackScreenOptions, nativeHeaderScrollEdgeEffects } from "../../native/StackHeader";
22
import { NativeHeader, NativeScreen } from "../../native/ThemedScreenStack";
23
+import { useEnvironments } from "../../state/environments";
24
import { SubagentRow } from "./SubagentRow";
25
import { useVisibleSecondClock } from "./use-visible-second-clock";
26
import { ScreenContent } from "../../components/ui/ScreenContent";
27
import { useAdaptiveWorkspaceLayout } from "../layout/AdaptiveWorkspaceLayout";
28
+import { subagentThreadTarget } from "./threadAgentsPresentation";
29
30
import { useOpenThreadInspector } from "./thread-inspector-navigation";
31
@@ -53,21 +55,21 @@ export function ThreadAgentsSheet({ route }: StaticScreenProps<AgentsTarget>) {
55
const subagents = turn?.subagents ?? [];
56
const hasLiveAgent = (turn?.liveCount ?? 0) > 0;
57
56
- const openChildThread = (childThreadId: ThreadId) => {
58
+ const openChildThread = (child: { environmentId: EnvironmentId; threadId: ThreadId }) => {
59
void Haptics.selectionAsync();
60
if (
61
openInspector(target, {
62
type: "thread",
61
- environmentId: target.environmentId,
62
- threadId: childThreadId,
63
+ environmentId: child.environmentId,
64
+ threadId: child.threadId,
65
})
66
)
67
return;
68
// Replace this leaf sheet so the child enters the workspace stack expected by Home's Back button.
69
navigation.dispatch(
70
StackActions.replace("Thread", {
69
- environmentId: target.environmentId,
70
- threadId: childThreadId,
71
+ environmentId: child.environmentId,
72
+ threadId: child.threadId,
73
}),
74
);
75
};
@@ -143,26 +145,34 @@ function AgentRow(props: {
145
readonly environmentId: EnvironmentId;
146
readonly subagent: OrchestrationV2Subagent;
147
readonly tickSeconds: boolean;
146
- readonly onOpen: (childThreadId: ThreadId) => void;
148
+ readonly onOpen: (child: { environmentId: EnvironmentId; threadId: ThreadId }) => void;
149
}) {
150
const { subagent } = props;
149
- const childThreadId = subagent.childThreadId;
151
+ const { presentationById } = useEnvironments();
152
+ const target = subagentThreadTarget(subagent, props.environmentId, (id) =>
153
+ presentationById.has(id),
154
+ );
155
156
const row = (
157
<View className="border-b border-border py-3.5">
158
<SubagentRow
159
environmentId={props.environmentId}
160
subagent={subagent}
161
+ canOpenRemote={target !== null}
162
elapsed={<AgentElapsed subagent={subagent} tickSeconds={props.tickSeconds} />}
163
/>
164
</View>
165
);
166
161
- if (childThreadId === null) {
167
+ if (target === null) {
168
return (
169
<View
170
accessible
165
- accessibilityHint="Provider-managed agent. Its work appears in the transcript."
171
+ accessibilityHint={
172
+ subagent.remoteChild === undefined
173
+ ? "Provider-managed agent. Its work appears in the transcript."
174
+ : `Runs on ${subagent.remoteChild.label}. Connect to it to open its thread.`
175
+ }
176
>
177
{row}
178
</View>
@@ -173,7 +183,7 @@ function AgentRow(props: {
183
<Pressable
184
accessibilityRole="link"
185
accessibilityHint="Opens this agent's thread"
176
- onPress={() => props.onOpen(childThreadId)}
186
+ onPress={() => props.onOpen(target)}
187
className="active:opacity-70"
188
>
189
{row}
apps/mobile/src/features/threads/ThreadRouteScreen.tsx
+15
-1
@@ -43,6 +43,8 @@ import { vcsEnvironment } from "../../state/vcs";
43
import { EmptyState } from "../../components/ui/EmptyState";
44
import { LoadingScreen } from "../../components/LoadingScreen";
45
import { scopedThreadKey } from "../../lib/scopedEntities";
46
+import { scopeThreadRef } from "@t3tools/client-runtime/environment";
47
+import { useThreadShell } from "../../state/entities";
48
import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../../native/native-glass";
49
import { connectionTone } from "../connection/connectionTone";
50
import {
@@ -486,10 +488,22 @@ function ThreadRouteContent(
488
: null;
489
490
const usesNativeHeaderGlass = NATIVE_LIQUID_GLASS_SUPPORTED;
491
+ const delegatedFrom = selectedThread?.delegatedFrom ?? null;
492
+ const delegatedFromRef =
493
+ delegatedFrom === null
494
+ ? null
495
+ : scopeThreadRef(delegatedFrom.environmentId, delegatedFrom.threadId);
496
+ // The title it had at delegation, until this client sees the parent itself.
497
+ const delegatedFromThread = useThreadShell(delegatedFromRef);
498
const headerSubtitle = [
499
selectedThreadProject?.title ?? null,
500
selectedEnvironmentConnection?.environmentLabel ?? null,
492
- selectedThread?.linkOrigin ? `From ${selectedThread.linkOrigin.label}` : null,
501
+ // A linked environment's delegated task names its parent; other linked work its origin.
502
+ delegatedFrom !== null
503
+ ? `Subagent of ${delegatedFromThread?.title ?? delegatedFrom.title}`
504
+ : selectedThread?.linkOrigin
505
+ ? `From ${selectedThread.linkOrigin.label}`
506
+ : null,
507
]
508
.filter(Boolean)
509
.join(" · ");
apps/mobile/src/features/threads/thread-subagent-group.tsx
+30
-9
@@ -18,8 +18,11 @@ import type { ThreadFeedActivity } from "../../lib/threadActivity";
18
import { serverEnvironment } from "../../state/server";
19
import { environmentThreadDetails } from "../../state/threads";
20
import { subagentCardElapsed } from "./subagent-card-presentation";
21
+import { useEnvironments } from "../../state/environments";
22
+import { useServerConfigs } from "../../state/entities";
23
import { SubagentRow } from "./SubagentRow";
24
import { useVisibleSecondClock } from "./use-visible-second-clock";
25
+import { subagentThreadTarget } from "./threadAgentsPresentation";
26
import { WorkLogBlock } from "./work-log-layout";
27
28
import { useOpenThreadInspector } from "./thread-inspector-navigation";
@@ -68,6 +71,7 @@ export function ThreadSubagentGroup(props: {
71
environmentThreadDetails.threadAtom(scopeThreadRef(props.environmentId, members[0]!.threadId)),
72
(thread) => thread?.projection.subagents,
73
);
74
+ const { presentationById } = useEnvironments();
75
const agents = members.map((item) => {
76
const live = liveAgents?.find((agent) => agent.id === item.subagentId);
77
return {
@@ -85,8 +89,13 @@ export function ThreadSubagentGroup(props: {
89
const label = `${agents.length} subagents`;
90
const summary = summarizeSubagentStatuses(agents.map((agent) => agent.status));
91
const expanded = props.expandedRows[props.anchorKey] ?? false;
92
+ const serverConfigs = useServerConfigs();
93
+ // A task in a linked environment runs a provider instance of that environment.
94
const iconUrl = (item: SubagentItem) =>
89
- config?.providers.find((provider) => provider.instanceId === item.providerInstanceId)?.iconUrl;
95
+ (item.remoteChild === undefined
96
+ ? config
97
+ : serverConfigs.get(item.remoteChild.environmentId)
98
+ )?.providers.find((provider) => provider.instanceId === item.providerInstanceId)?.iconUrl;
99
return (
100
<WorkLogBlock>
101
{grouped ? (
@@ -137,29 +146,40 @@ export function ThreadSubagentGroup(props: {
146
{!grouped || expanded ? (
147
<View className="mb-1 gap-px rounded-xl border border-border bg-card/30 p-1">
148
{agents.map((agent) => {
140
- const threadId = agent.childThreadId;
149
+ // A task in a linked environment opens there, if this app is connected to it.
150
+ const target = subagentThreadTarget(agent, props.environmentId, (id) =>
151
+ presentationById.has(id),
152
+ );
153
return (
154
<Pressable
155
key={agent.item.id}
156
accessible
145
- accessibilityRole={threadId === null ? undefined : "link"}
157
+ accessibilityRole={target === null ? undefined : "link"}
158
accessibilityHint={
147
- threadId === null ? "Provider-managed agent" : "Opens this agent's thread"
159
+ target !== null
160
+ ? "Opens this agent's thread"
161
+ : agent.remoteChild !== undefined
162
+ ? `Runs on ${agent.remoteChild.label}`
163
+ : "Provider-managed agent"
164
}
149
- disabled={threadId === null}
165
+ disabled={target === null}
166
onPress={() => {
151
- if (threadId === null) return;
167
+ if (target === null) return;
168
if (
169
openInspector(
170
{ environmentId: props.environmentId, threadId: members[0]!.threadId },
155
- { type: "thread", environmentId: props.environmentId, threadId },
171
+ {
172
+ type: "thread",
173
+ environmentId: target.environmentId,
174
+ threadId: target.threadId,
175
+ },
176
)
177
)
178
return;
179
navigation.dispatch(
180
StackActions.push("Thread", {
161
- environmentId: String(props.environmentId),
162
- threadId: String(threadId),
181
+ environmentId: String(target.environmentId),
182
+ threadId: String(target.threadId),
183
}),
184
);
185
}}
@@ -168,6 +188,7 @@ export function ThreadSubagentGroup(props: {
188
<SubagentRow
189
environmentId={props.environmentId}
190
subagent={agent}
191
+ canOpenRemote={target !== null}
192
elapsed={<SubagentElapsed agents={[agent]} />}
193
/>
194
</Pressable>
apps/mobile/src/features/threads/threadAgentsPresentation.ts
+27
-3
@@ -3,7 +3,7 @@ import {
3
subagentDetailPreview,
4
} from "@t3tools/client-runtime/state/subagent-display";
5
import { isActiveSubagentStatus } from "@t3tools/client-runtime/state/subagentRuntime";
6
-import type { OrchestrationV2Subagent } from "@t3tools/contracts";
6
+import type { EnvironmentId, OrchestrationV2Subagent, ThreadId } from "@t3tools/contracts";
7
8
const PROMPT_TITLE_LIMIT = 80;
9
@@ -16,6 +16,27 @@ export interface SubagentRowPresentation {
16
readonly tone: SubagentRowTone;
17
readonly live: boolean;
18
readonly canOpenThread: boolean;
19
+ /** The linked environment the task runs in, when it runs in one. */
20
+ readonly runsOn: string | null;
21
+}
22
+
23
+/**
24
+ * Where an agent's thread opens: here, or in the linked environment that runs
25
+ * it. Null when there is no thread, or this app is not connected to that
26
+ * environment.
27
+ */
28
+export function subagentThreadTarget(
29
+ subagent: Pick<OrchestrationV2Subagent, "childThreadId" | "remoteChild">,
30
+ environmentId: EnvironmentId,
31
+ isKnownEnvironment: (environmentId: EnvironmentId) => boolean,
32
+): { readonly environmentId: EnvironmentId; readonly threadId: ThreadId } | null {
33
+ if (subagent.childThreadId !== null) {
34
+ return { environmentId, threadId: subagent.childThreadId };
35
+ }
36
+ const remote = subagent.remoteChild;
37
+ return remote !== undefined && isKnownEnvironment(remote.environmentId)
38
+ ? { environmentId: remote.environmentId, threadId: remote.threadId }
39
+ : null;
40
}
41
42
function rowTitle(subagent: Pick<OrchestrationV2Subagent, "title" | "prompt">): string {
@@ -58,8 +79,9 @@ function rowStatusLabel(status: OrchestrationV2Subagent["status"]): string {
79
export function resolveSubagentRowPresentation(
80
subagent: Pick<
81
OrchestrationV2Subagent,
61
- "title" | "prompt" | "status" | "progress" | "result" | "childThreadId"
82
+ "title" | "prompt" | "status" | "progress" | "result" | "childThreadId" | "remoteChild"
83
>,
84
+ canOpenRemote = false,
85
): SubagentRowPresentation {
86
const live = isActiveSubagentStatus(subagent.status);
87
return {
@@ -68,6 +90,8 @@ export function resolveSubagentRowPresentation(
90
statusLabel: rowStatusLabel(subagent.status),
91
tone: rowTone(subagent.status),
92
live,
71
- canOpenThread: subagent.childThreadId !== null,
93
+ canOpenThread:
94
+ subagent.childThreadId !== null || (subagent.remoteChild !== undefined && canOpenRemote),
95
+ runsOn: subagent.remoteChild?.label ?? null,
96
};
97
}
apps/mobile/src/state/thread-order.test.ts
+4
-2
@@ -20,7 +20,9 @@ vi.mock("./atom-registry", async () => {
20
});
21
vi.mock("./threads", async () => {
22
const { Atom } = await import("effect/reactivity");
23
- return { environmentThreadShells: { threadShellsAtom: Atom.make([]).pipe(Atom.keepAlive) } };
23
+ return {
24
+ environmentThreadShells: { navigationThreadShellsAtom: Atom.make([]).pipe(Atom.keepAlive) },
25
+ };
26
});
27
vi.mock("./server", async () => {
28
const { Atom } = await import("effect/reactivity");
@@ -34,7 +36,7 @@ vi.mock("./use-thread-outbox", async () => {
36
type ServerConfigs = Atom.Type<typeof environmentServerConfigsAtom>;
37
type ServerConfig = ServerConfigs extends ReadonlyMap<EnvironmentId, infer Config> ? Config : never;
38
const configsAtom = environmentServerConfigsAtom as Atom.Writable<ServerConfigs, ServerConfigs>;
37
-const shellsAtom = environmentThreadShells.threadShellsAtom as Atom.Writable<
39
+const shellsAtom = environmentThreadShells.navigationThreadShellsAtom as Atom.Writable<
40
readonly EnvironmentThreadShell[],
41
readonly EnvironmentThreadShell[]
42
>;
apps/mobile/src/state/thread-order.ts
+6
-3
@@ -64,7 +64,7 @@ export function beginPendingThreadOrder(pending: PendingThreadOrder) {
64
const current = appAtomRegistry.get(pendingThreadOrderAtom);
65
if (current === null) return;
66
const configs = appAtomRegistry.get(environmentServerConfigsAtom);
67
- const threads = appAtomRegistry.get(environmentThreadShells.threadShellsAtom);
67
+ const threads = appAtomRegistry.get(environmentThreadShells.navigationThreadShellsAtom);
68
const nowMs = Date.now();
69
const ordered = getThreadListV2OrderedSection({
70
threads,
@@ -95,13 +95,16 @@ export function beginPendingThreadOrder(pending: PendingThreadOrder) {
95
teardownPendingOrder = teardown;
96
appAtomRegistry.set(pendingThreadOrderAtom, pending);
97
unsubscribers.push(
98
- appAtomRegistry.subscribe(environmentThreadShells.threadShellsAtom, refresh),
98
+ appAtomRegistry.subscribe(environmentThreadShells.navigationThreadShellsAtom, refresh),
99
appAtomRegistry.subscribe(environmentServerConfigsAtom, refresh),
100
appAtomRegistry.subscribe(queuedThreadKeysAtom, refresh),
101
minuteTick.subscribe(refresh),
102
);
103
armWake(
104
- nextSnoozeWakeAfter(appAtomRegistry.get(environmentThreadShells.threadShellsAtom), Date.now()),
104
+ nextSnoozeWakeAfter(
105
+ appAtomRegistry.get(environmentThreadShells.navigationThreadShellsAtom),
106
+ Date.now(),
107
+ ),
108
);
109
return {
110
isPending: () => {
apps/server/src/mcp/McpToolAccess.ts
+1
-1
@@ -23,7 +23,7 @@ import {
23
import * as PeerForwarding from "../peer/PeerForwarding.ts";
24
import { assertNotLinked, assertSameLink, callerLinkOrigin } from "./linkOrigin.ts";
25
import * as McpInvocationContext from "./McpInvocationContext.ts";
26
-import { resolveInteractionMode, resolveRuntimeMode } from "./OrchestratorMcpService.ts";
26
+import { resolveInteractionMode, resolveRuntimeMode } from "./delegatedTaskModes.ts";
27
import {
28
assertFullAccess,
29
assertLiveCaller,
apps/server/src/mcp/OrchestratorMcpService.activity.test.ts
+4
@@ -24,6 +24,7 @@ import * as ServerSettings from "../serverSettings.ts";
24
import * as SecretRequests from "../secrets/SecretRequests.ts";
25
import * as ThreadLaunchService from "../orchestration-v2/ThreadLaunchService.ts";
26
import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
27
+import * as RemoteDelegation from "../peer/RemoteDelegation.ts";
28
import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
29
import type * as McpInvocationContext from "./McpInvocationContext.ts";
30
import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";
@@ -161,6 +162,7 @@ it("readThread prefers activity-run status over a newer cancelled queued run", a
162
} satisfies Partial<ProviderRegistry.ProviderRegistry["Service"]>),
163
Layer.mock(ProjectService.ProjectService)({}),
164
Layer.mock(SecretRequests.SecretRequests)({}),
165
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
166
Layer.mock(ScheduledTaskService.ScheduledTaskService)({
167
list: () => Effect.succeed({ tasks: [] }),
168
} satisfies Partial<ScheduledTaskService.ScheduledTaskService["Service"]>),
@@ -276,6 +278,7 @@ it("taskStatus returns task.providerInstanceId rather than the driver kind", asy
278
} satisfies Partial<ProviderRegistry.ProviderRegistry["Service"]>),
279
Layer.mock(ProjectService.ProjectService)({}),
280
Layer.mock(SecretRequests.SecretRequests)({}),
281
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
282
Layer.mock(ScheduledTaskService.ScheduledTaskService)({
283
list: () => Effect.succeed({ tasks: [] }),
284
} satisfies Partial<ScheduledTaskService.ScheduledTaskService["Service"]>),
@@ -403,6 +406,7 @@ it("readThread and sendToThread reach threads in other projects", async () => {
406
} satisfies Partial<ProviderRegistry.ProviderRegistry["Service"]>),
407
Layer.mock(ProjectService.ProjectService)({}),
408
Layer.mock(SecretRequests.SecretRequests)({}),
409
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
410
Layer.mock(ScheduledTaskService.ScheduledTaskService)({
411
list: () =>
412
Effect.succeed({
apps/server/src/mcp/OrchestratorMcpService.test.ts
+30
-13
@@ -57,9 +57,11 @@ import * as ProjectService from "../project/ProjectService.ts";
57
import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts";
58
import * as ServerSettings from "../serverSettings.ts";
59
import * as SecretRequests from "../secrets/SecretRequests.ts";
60
+import * as RemoteDelegation from "../peer/RemoteDelegation.ts";
61
import type { McpInvocationScope } from "./McpInvocationContext.ts";
62
import { idleThreadProjection, liveThreadShell } from "./McpToolAccess.testkit.ts";
63
import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";
64
+import { resolveRuntimeMode } from "./delegatedTaskModes.ts";
65
import type * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
66
67
const decodeTarget = Schema.decodeUnknownEffect(OrchestratorMcpTarget);
@@ -165,6 +167,7 @@ describe("OrchestratorMcpService", () => {
167
}),
168
Layer.mock(ProjectService.ProjectService)({}),
169
Layer.mock(SecretRequests.SecretRequests)({}),
170
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
171
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
172
);
173
const scope: McpInvocationScope = {
@@ -265,6 +268,7 @@ describe("OrchestratorMcpService", () => {
268
}),
269
Layer.mock(ProjectService.ProjectService)({}),
270
Layer.mock(SecretRequests.SecretRequests)({}),
271
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
272
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
273
);
274
const scope: McpInvocationScope = {
@@ -365,6 +369,7 @@ describe("OrchestratorMcpService", () => {
369
}),
370
Layer.mock(ProjectService.ProjectService)({}),
371
Layer.mock(SecretRequests.SecretRequests)({}),
372
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
373
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
374
);
375
const scope: McpInvocationScope = {
@@ -457,6 +462,7 @@ describe("OrchestratorMcpService", () => {
462
}),
463
Layer.mock(ProjectService.ProjectService)({}),
464
Layer.mock(SecretRequests.SecretRequests)({}),
465
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
466
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
467
);
468
const scope: McpInvocationScope = {
@@ -553,6 +559,7 @@ describe("OrchestratorMcpService", () => {
559
}),
560
Layer.mock(ProjectService.ProjectService)({}),
561
Layer.mock(SecretRequests.SecretRequests)({}),
562
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
563
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
564
);
565
const scope: McpInvocationScope = {
@@ -644,6 +651,7 @@ describe("OrchestratorMcpService", () => {
651
}),
652
Layer.mock(ProjectService.ProjectService)({}),
653
Layer.mock(SecretRequests.SecretRequests)({}),
654
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
655
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
656
);
657
const scope: McpInvocationScope = {
@@ -729,6 +737,7 @@ describe("OrchestratorMcpService", () => {
737
}),
738
Layer.mock(ProjectService.ProjectService)({}),
739
Layer.mock(SecretRequests.SecretRequests)({}),
740
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
741
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
742
);
743
const scope: McpInvocationScope = {
@@ -815,6 +824,7 @@ describe("OrchestratorMcpService", () => {
824
}),
825
Layer.mock(ProjectService.ProjectService)({}),
826
Layer.mock(SecretRequests.SecretRequests)({}),
827
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
828
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
829
);
830
const scope: McpInvocationScope = {
@@ -948,6 +958,7 @@ describe("OrchestratorMcpService", () => {
958
}),
959
Layer.mock(ProjectService.ProjectService)({}),
960
Layer.mock(SecretRequests.SecretRequests)({}),
961
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
962
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
963
);
964
const scope: McpInvocationScope = {
@@ -1189,6 +1200,7 @@ describe("OrchestratorMcpService provider resolution", () => {
1200
]),
1201
Layer.mock(ProjectService.ProjectService)({}),
1202
Layer.mock(SecretRequests.SecretRequests)({}),
1203
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
1204
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
1205
);
1206
@@ -1365,6 +1377,7 @@ describe("OrchestratorMcpService provider resolution", () => {
1377
adapterRegistryLayer([codexInstanceId, opencodeInstanceId]),
1378
Layer.mock(ProjectService.ProjectService)({}),
1379
Layer.mock(SecretRequests.SecretRequests)({}),
1380
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
1381
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
1382
),
1383
),
@@ -1469,6 +1482,7 @@ describe("OrchestratorMcpService provider resolution", () => {
1482
adapterRegistryLayer([codexInstanceId]),
1483
Layer.mock(ProjectService.ProjectService)({}),
1484
Layer.mock(SecretRequests.SecretRequests)({}),
1485
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
1486
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
1487
);
1488
@@ -1581,6 +1595,7 @@ describe("OrchestratorMcpService provider resolution", () => {
1595
adapterRegistryLayer([codexInstanceId, altInstanceId]),
1596
Layer.mock(ProjectService.ProjectService)({}),
1597
Layer.mock(SecretRequests.SecretRequests)({}),
1598
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
1599
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
1600
ServerSettings.layerTest(),
1601
);
@@ -1689,6 +1704,7 @@ describe("OrchestratorMcpService provider resolution", () => {
1704
adapterRegistryLayer([codexInstanceId, altInstanceId]),
1705
Layer.mock(ProjectService.ProjectService)({}),
1706
Layer.mock(SecretRequests.SecretRequests)({}),
1707
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
1708
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
1709
ServerSettings.layerTest(),
1710
);
@@ -1784,6 +1800,7 @@ describe("OrchestratorMcpService provider resolution", () => {
1800
]),
1801
Layer.mock(ProjectService.ProjectService)({}),
1802
Layer.mock(SecretRequests.SecretRequests)({}),
1803
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
1804
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
1805
),
1806
),
@@ -2040,6 +2057,7 @@ describe("OrchestratorMcpService provider resolution", () => {
2057
),
2058
Layer.mock(ProjectService.ProjectService)({}),
2059
Layer.mock(SecretRequests.SecretRequests)({}),
2060
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
2061
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
2062
);
2063
@@ -2204,6 +2222,7 @@ describe("OrchestratorMcpService provider resolution", () => {
2222
}),
2223
Layer.mock(ProjectService.ProjectService)({}),
2224
Layer.mock(SecretRequests.SecretRequests)({}),
2225
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
2226
Layer.mock(ScheduledTaskService.ScheduledTaskService)({
2227
list: () => Effect.succeed({ tasks }),
2228
upsert: () =>
@@ -2274,6 +2293,7 @@ describe("OrchestratorMcpService provider resolution", () => {
2293
}),
2294
Layer.mock(ProjectService.ProjectService)({}),
2295
Layer.mock(SecretRequests.SecretRequests)({}),
2296
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
2297
Layer.mock(ScheduledTaskService.ScheduledTaskService)({
2298
list: () => Effect.succeed({ tasks: [task({})] }),
2299
}),
@@ -2362,6 +2382,7 @@ describe("OrchestratorMcpService provider resolution", () => {
2382
}),
2383
Layer.mock(ProjectService.ProjectService)({}),
2384
Layer.mock(SecretRequests.SecretRequests)({}),
2385
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
2386
Layer.mock(ScheduledTaskService.ScheduledTaskService)({
2387
list: () => Effect.succeed({ tasks: [bound] }),
2388
upsert: () =>
@@ -2438,6 +2459,7 @@ describe("OrchestratorMcpService provider resolution", () => {
2459
adapterRegistryLayer([]),
2460
Layer.mock(ProjectService.ProjectService)({}),
2461
Layer.mock(SecretRequests.SecretRequests)({}),
2462
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
2463
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
2464
);
2465
yield* Effect.gen(function* () {
@@ -2547,6 +2569,7 @@ describe("OrchestratorMcpService provider resolution", () => {
2569
adapterRegistryLayer([codexInstanceId, peerId]),
2570
Layer.mock(ProjectService.ProjectService)({}),
2571
Layer.mock(SecretRequests.SecretRequests)({}),
2572
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
2573
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
2574
);
2575
yield* Effect.gen(function* () {
@@ -2577,11 +2600,9 @@ describe("OrchestratorMcpService provider resolution", () => {
2600
2601
it.effect("refuses an explicit mode the target provider does not offer", () =>
2602
Effect.gen(function* () {
2580
- const error = yield* OrchestratorMcpService.resolveRuntimeMode(
2581
- "full-access",
2582
- "auto-accept-edits",
2583
- muse,
2584
- ).pipe(Effect.flip);
2603
+ const error = yield* resolveRuntimeMode("full-access", "auto-accept-edits", muse).pipe(
2604
+ Effect.flip,
2605
+ );
2606
assert.equal(error.code, "invalid_request");
2607
assert.include(error.message, "approval-required, full-access");
2608
}),
@@ -2589,14 +2610,8 @@ describe("OrchestratorMcpService provider resolution", () => {
2610
2611
it.effect("steps an inherited mode down to the broadest one the provider offers", () =>
2612
Effect.gen(function* () {
2592
- assert.equal(
2593
- yield* OrchestratorMcpService.resolveRuntimeMode("full-access", "inherit", muse),
2594
- "full-access",
2595
- );
2596
- assert.equal(
2597
- yield* OrchestratorMcpService.resolveRuntimeMode("auto", undefined, muse),
2598
- "approval-required",
2599
- );
2613
+ assert.equal(yield* resolveRuntimeMode("full-access", "inherit", muse), "full-access");
2614
+ assert.equal(yield* resolveRuntimeMode("auto", undefined, muse), "approval-required");
2615
}),
2616
);
2617
});
@@ -2631,6 +2646,7 @@ describe("OrchestratorMcpService thread lookup", () => {
2646
}),
2647
Layer.mock(ProjectService.ProjectService)({}),
2648
Layer.mock(SecretRequests.SecretRequests)({}),
2649
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
2650
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
2651
),
2652
),
@@ -2793,6 +2809,7 @@ describe("OrchestratorMcpService thread stop", () => {
2809
Layer.mock(ProviderRegistry.ProviderRegistry)({ getProviders: Effect.succeed([]) }),
2810
Layer.mock(ProjectService.ProjectService)({}),
2811
Layer.mock(SecretRequests.SecretRequests)({}),
2812
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
2813
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
2814
),
2815
),
apps/server/src/mcp/OrchestratorMcpService.ts
+204
-123
@@ -22,13 +22,11 @@ import {
22
type OrchestratorMcpCreatedThread,
23
type OrchestratorMcpDelegateTaskInput,
24
type OrchestratorMcpDelegateTaskResult,
25
- type OrchestratorMcpInteractionMode,
25
type OrchestratorMcpDeleteScheduledTaskInput,
26
type OrchestratorMcpRequestSecretInput,
27
type OrchestratorMcpRequestSecretResult,
28
type OrchestratorMcpDeleteScheduledTaskResult,
29
type OrchestratorMcpListScheduledTasksResult,
31
- type OrchestratorMcpRuntimeMode,
30
type OrchestratorMcpScheduledTask,
31
type OrchestratorMcpScheduleTaskInput,
32
type OrchestratorMcpScheduleTaskResult,
@@ -54,7 +52,6 @@ import {
52
type OrchestratorMcpThreadWaitInput,
53
type OrchestratorMcpThreadWaitResult,
54
type ProviderInteractionMode,
57
- type ProviderInstanceId,
55
type ProviderOptionDescriptor,
56
type ProviderOptionSelection,
57
ProviderRequestKind,
@@ -112,7 +109,17 @@ import {
109
requireThreadScope,
110
} from "./McpInvocationContext.ts";
111
import * as Metrics from "../observability/Metrics.ts";
112
+import {
113
+ interactionModeRank,
114
+ resolveInteractionMode,
115
+ resolveRuntimeMode,
116
+ runtimeModeRank,
117
+ taskPrompt,
118
+} from "./delegatedTaskModes.ts";
119
+import { isLiveCallerShell, threadNotFound } from "./threadAccess.ts";
120
import * as SecretRequests from "../secrets/SecretRequests.ts";
121
+import * as PeerForwarding from "../peer/PeerForwarding.ts";
122
+import * as RemoteDelegation from "../peer/RemoteDelegation.ts";
123
124
const DEFAULT_WAIT_TIMEOUT_MS = 10 * 60 * 1_000;
125
const MAX_WAIT_TIMEOUT_MS = 60 * 60 * 1_000;
@@ -214,43 +221,6 @@ function failure(code: OrchestratorMcpFailure["code"], message: string): Orchest
221
return new OrchestratorMcpFailure({ code, message });
222
}
223
217
-/** Background subagents retain credentials until provider exit; archived threads and other instances cannot act. */
218
-export const isLiveCallerShell = (
219
- shell: Pick<
220
- OrchestrationV2ThreadShell,
221
- "archivedAt" | "activeRunId" | "providerInstanceId" | "pendingBackgroundTasks"
222
- > | null,
223
- providerInstanceId: ProviderInstanceId | undefined,
224
-) =>
225
- shell !== null &&
226
- shell.archivedAt === null &&
227
- shell.providerInstanceId === providerInstanceId &&
228
- (shell.activeRunId !== null ||
229
- (shell.pendingBackgroundTasks?.some(
230
- (task) => task.kind === "subagent" && task.providerInstanceId === providerInstanceId,
231
- ) ??
232
- false));
233
-
234
-/**
235
- * Threads an agent starts over MCP are `mcp:<uuid>`, and agents often paste the
236
- * bare uuid. The id is never rewritten, so permission checks keyed on it still
237
- * hold; the miss only names a live thread the caller could read by its full id.
238
- */
239
-export const threadNotFound = Effect.fn("OrchestratorMcpService.threadNotFound")(function* (
240
- threads: Pick<ThreadManagementService.ThreadManagementService["Service"], "getThreadShell">,
241
- threadId: ThreadId,
242
- message: string,
243
-) {
244
- const prefixed = ThreadId.make(`mcp:${threadId}`);
245
- const shell = yield* threads.getThreadShell(prefixed).pipe(Effect.orElseSucceed(() => null));
246
- return yield* failure(
247
- "thread_not_found",
248
- shell === null || shell.deletedAt !== null
249
- ? message
250
- : `${message} Did you mean \`${prefixed}\`?`,
251
- );
252
-});
253
-
224
function threadManagementFailure(error: unknown): OrchestratorMcpFailure {
225
if (!isThreadManagementError(error)) return failure("orchestration_error", errorMessage(error));
226
switch (error._tag) {
@@ -661,73 +631,6 @@ function canExposeTaskRunResult(run: OrchestrationV2Run | undefined): run is Orc
631
);
632
}
633
664
-function runtimeModeRank(mode: RuntimeMode): number {
665
- switch (mode) {
666
- case "approval-required":
667
- return 0;
668
- case "auto-accept-edits":
669
- return 1;
670
- case "auto":
671
- return 2;
672
- case "full-access":
673
- return 3;
674
- }
675
-}
676
-
677
-function interactionModeRank(mode: ProviderInteractionMode): number {
678
- return mode === "plan" ? 0 : 1;
679
-}
680
-
681
-export function resolveRuntimeMode(
682
- parentMode: RuntimeMode,
683
- requested: OrchestratorMcpRuntimeMode | undefined,
684
- target?: Pick<ResolvedTarget, "modelSelection" | "supportedRuntimeModes">,
685
-): Effect.Effect<RuntimeMode, OrchestratorMcpFailure> {
686
- const inherited = requested === undefined || requested === "inherit";
687
- const resolved = inherited ? parentMode : requested;
688
- if (runtimeModeRank(resolved) > runtimeModeRank(parentMode)) {
689
- return Effect.fail(
690
- failure(
691
- "runtime_mode_escalation_denied",
692
- `Child runtime mode ${resolved} is broader than parent mode ${parentMode}.`,
693
- ),
694
- );
695
- }
696
- const supported = target?.supportedRuntimeModes;
697
- if (supported === undefined || supported.length === 0 || supported.includes(resolved)) {
698
- return Effect.succeed(resolved);
699
- }
700
- if (!inherited) {
701
- return Effect.fail(
702
- failure(
703
- "invalid_request",
704
- `Provider ${target?.modelSelection.instanceId} does not offer runtime mode ${resolved}, so it would run as approval-required. Use one of: ${supported.join(", ")}.`,
705
- ),
706
- );
707
- }
708
- return Effect.succeed(
709
- supported
710
- .filter((mode) => runtimeModeRank(mode) <= runtimeModeRank(resolved))
711
- .toSorted((left, right) => runtimeModeRank(right) - runtimeModeRank(left))[0] ??
712
- "approval-required",
713
- );
714
-}
715
-
716
-export function resolveInteractionMode(
717
- parentMode: ProviderInteractionMode,
718
- requested: OrchestratorMcpInteractionMode | undefined,
719
-): Effect.Effect<ProviderInteractionMode, OrchestratorMcpFailure> {
720
- const resolved = requested === undefined || requested === "inherit" ? parentMode : requested;
721
- return interactionModeRank(resolved) > interactionModeRank(parentMode)
722
- ? Effect.fail(
723
- failure(
724
- "interaction_mode_escalation_denied",
725
- `Child interaction mode ${resolved} is broader than parent mode ${parentMode}.`,
726
- ),
727
- )
728
- : Effect.succeed(resolved);
729
-}
730
-
634
function stablePart(value: string): string {
635
return encodeURIComponent(value);
636
}
@@ -809,12 +712,6 @@ function threadTitle(input: {
712
return detail.length > 80 ? `${detail.slice(0, 77)}...` : detail;
713
}
714
812
-export function taskPrompt(input: OrchestratorMcpDelegateTaskInput): string {
813
- return input.role === undefined || input.role === "general"
814
- ? input.task
815
- : `Act as the ${input.role} sub-agent for this task.\n\n${input.task}`;
816
-}
817
-
715
function threadSettlement(
716
thread: Pick<OrchestrationV2ThreadShell, "settledOverride" | "settledAt">,
717
): Pick<OrchestratorMcpThreadListItem, "settled" | "settledAt"> {
@@ -1062,6 +959,7 @@ const make = Effect.gen(function* () {
959
const threadLaunch = yield* ThreadLaunchService.ThreadLaunchService;
960
const gitDriver = yield* GitVcsDriver.GitVcsDriver;
961
const serverSettings = yield* ServerSettings.ServerSettingsService;
962
+ const remoteDelegation = yield* RemoteDelegation.RemoteDelegation;
963
964
const requireProject = (projectId: ProjectId) =>
965
projects.getById(projectId).pipe(
@@ -1125,6 +1023,22 @@ const make = Effect.gen(function* () {
1023
),
1024
);
1025
1026
+ // Task waits read on every wake of a parent that may hold thousands of
1027
+ // tasks, so they read only the task they watch and what its status needs.
1028
+ const loadTaskParent = (threadId: ThreadId, taskId: NodeId) =>
1029
+ threadManagement
1030
+ .getThreadRecords(threadId, ["runs", "subagents", "contextTransfers"], {
1031
+ subagentIds: [taskId],
1032
+ })
1033
+ .pipe(
1034
+ Effect.mapError((error) =>
1035
+ failure(
1036
+ "orchestration_error",
1037
+ `Unable to read thread ${threadId}: ${errorMessage(error)}`,
1038
+ ),
1039
+ ),
1040
+ );
1041
+
1042
const loadProjectThread = (
1043
projectId: OrchestrationV2ThreadProjection["thread"]["projectId"],
1044
threadId: ThreadId,
@@ -1477,19 +1391,22 @@ const make = Effect.gen(function* () {
1391
acknowledgementOperation = "task-status-acknowledge",
1392
): Effect.fn.Return<OrchestratorMcpDelegateTaskResult, OrchestratorMcpFailure> {
1393
yield* requireCapability(scope);
1480
- const parentProjection = yield* loadProjection(scope.thread.threadId);
1394
+ const parentProjection = yield* loadTaskParent(scope.thread.threadId, taskId);
1395
const task = parentProjection.subagents.find(
1396
(candidate) =>
1397
candidate.id === taskId &&
1398
candidate.origin === "app_owned" &&
1399
candidate.threadId === scope.thread.threadId,
1400
);
1487
- if (task === undefined || task.childThreadId === null) {
1401
+ if (task === undefined || (task.childThreadId === null && task.remoteChild === undefined)) {
1402
return yield* failure(
1403
"task_not_found",
1404
`Delegated task ${taskId} does not belong to thread ${scope.thread.threadId}.`,
1405
);
1406
}
1407
+ if (task.childThreadId === null) {
1408
+ return yield* readRemoteTask(scope, task, waitTimedOut, acknowledgeTerminal);
1409
+ }
1410
const childControls = yield* threadManagement
1411
.getThreadRecords(
1412
task.childThreadId,
@@ -1670,6 +1587,113 @@ const make = Effect.gen(function* () {
1587
return response;
1588
});
1589
1590
+ /** `mode=wait` on a task already recorded, as `delegateTask` does for its own. */
1591
+ const awaitTask = Effect.fn("OrchestratorMcpService.awaitTask")(function* (
1592
+ scope: McpThreadInvocationScope,
1593
+ taskId: NodeId,
1594
+ requestedTimeoutMs: number | undefined,
1595
+ ): Effect.fn.Return<OrchestratorMcpDelegateTaskResult, OrchestratorMcpFailure> {
1596
+ const timeoutMs = Math.min(
1597
+ MAX_WAIT_TIMEOUT_MS,
1598
+ Math.max(1, requestedTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS),
1599
+ );
1600
+ const waited = yield* waitForTask(scope, taskId, timeoutMs);
1601
+ if (Option.isSome(waited)) return waited.value;
1602
+ // As for a local task: once the blocking wait ends, a later result wakes the parent.
1603
+ yield* threadManagement
1604
+ .dispatch({
1605
+ type: "delegated_task.wake-policy",
1606
+ commandId: stableCommandId({
1607
+ scope,
1608
+ requestKey: taskId,
1609
+ operation: "delegate-task-wake-policy",
1610
+ }),
1611
+ parentThreadId: scope.thread.threadId,
1612
+ taskId,
1613
+ completionWake: "always",
1614
+ })
1615
+ .pipe(Effect.ignoreCause({ log: true }));
1616
+ return yield* readTask(scope, taskId, true, true);
1617
+ });
1618
+
1619
+ /**
1620
+ * A task that runs in a linked environment, answered from its row here:
1621
+ * the follower records its result once its thread there ends.
1622
+ */
1623
+ const readRemoteTask = Effect.fn("OrchestratorMcpService.readRemoteTask")(function* (
1624
+ scope: McpThreadInvocationScope,
1625
+ task: OrchestrationV2Subagent,
1626
+ waitTimedOut: boolean,
1627
+ acknowledgeTerminal: boolean,
1628
+ ): Effect.fn.Return<OrchestratorMcpDelegateTaskResult, OrchestratorMcpFailure> {
1629
+ const status: OrchestratorMcpDelegateTaskResult["status"] =
1630
+ task.result === null
1631
+ ? "running"
1632
+ : task.status === "completed" ||
1633
+ task.status === "failed" ||
1634
+ task.status === "cancelled" ||
1635
+ task.status === "interrupted"
1636
+ ? task.status
1637
+ : "completed";
1638
+ const terminal = isTerminalTaskStatus(status);
1639
+ if (
1640
+ acknowledgeTerminal &&
1641
+ terminal &&
1642
+ task.completionDelivery?.state !== "acknowledged" &&
1643
+ task.completionDelivery?.state !== "disposed"
1644
+ ) {
1645
+ const parentProjection = yield* loadProjection(scope.thread.threadId);
1646
+ const observingRun = ThreadManagementService.latestActiveRun(parentProjection);
1647
+ yield* threadManagement
1648
+ .dispatch({
1649
+ type: "delegated_task.completion-delivery.acknowledge",
1650
+ commandId: stableCommandId({
1651
+ scope,
1652
+ requestKey: yield* requestKey(undefined),
1653
+ operation: "task-status-acknowledge",
1654
+ }),
1655
+ parentThreadId: scope.thread.threadId,
1656
+ taskId: task.id,
1657
+ observedByRunId:
1658
+ observingRun?.providerInstanceId === scope.thread.providerInstanceId
1659
+ ? observingRun.id
1660
+ : null,
1661
+ })
1662
+ .pipe(
1663
+ Effect.mapError((error) =>
1664
+ failure(
1665
+ "orchestration_error",
1666
+ `Unable to acknowledge delegated task ${task.id}: ${errorMessage(error)}`,
1667
+ ),
1668
+ ),
1669
+ );
1670
+ }
1671
+ return {
1672
+ taskId: task.id,
1673
+ childThreadId: null,
1674
+ ...(task.remoteChild === undefined ? {} : { remoteChild: task.remoteChild }),
1675
+ childRunId: null,
1676
+ childNodeId: task.id,
1677
+ status,
1678
+ workState: terminal ? "result_available" : "working",
1679
+ hasPendingChildRuns: false,
1680
+ providerInstanceId: task.providerInstanceId,
1681
+ model: task.model,
1682
+ summary: task.result,
1683
+ resultContextTransferId: null,
1684
+ latestTerminalRunId: null,
1685
+ latestTerminalStatus: terminal
1686
+ ? (status as OrchestratorMcpDelegateTaskResult["latestTerminalStatus"])
1687
+ : null,
1688
+ latestTerminalSummary: terminal ? task.result : null,
1689
+ latestTerminalResultContextTransferId: null,
1690
+ // Its questions and approvals are answered in the environment it runs in.
1691
+ hasPendingQuestion: false,
1692
+ pendingApproval: null,
1693
+ waitTimedOut,
1694
+ } satisfies OrchestratorMcpDelegateTaskResult;
1695
+ });
1696
+
1697
const waitForTask = Effect.fn("OrchestratorMcpService.waitForTask")(
1698
function* (scope: McpThreadInvocationScope, taskId: NodeId, _timeoutMs: number) {
1699
const streamError = (error: unknown) =>
@@ -1686,10 +1710,17 @@ const make = Effect.gen(function* () {
1710
return Option.some(initial);
1711
}
1712
// One stream per event type, so transcript events never fill a buffer.
1713
+ // A remote task has no child here; its completion lands on the parent.
1714
+ const childThreadId = initial.childThreadId;
1715
+ const wakeEvents =
1716
+ childThreadId === null
1717
+ ? TASK_WAKE_EVENTS.filter(({ thread }) => thread === "parent")
1718
+ : TASK_WAKE_EVENTS;
1719
return yield* Stream.mergeAll(
1690
- TASK_WAKE_EVENTS.map(({ thread, eventType }) =>
1720
+ wakeEvents.map(({ thread, eventType }) =>
1721
threadManagement.streamStoredEventsFrom({
1692
- threadId: thread === "parent" ? scope.thread.threadId : initial.childThreadId,
1722
+ threadId:
1723
+ thread === "parent" || childThreadId === null ? scope.thread.threadId : childThreadId,
1724
afterSequence,
1725
eventType,
1726
}),
@@ -2131,7 +2162,32 @@ const make = Effect.gen(function* () {
2162
};
2163
}),
2164
delegateTask: Effect.fn("OrchestratorMcpService.delegateTask")(function* (callerScope, input) {
2165
+ const environmentId =
2166
+ input.target === undefined
2167
+ ? undefined
2168
+ : PeerForwarding.remoteTarget(callerScope, input.target.environmentId);
2169
+ if (input.target !== undefined && environmentId !== undefined) {
2170
+ yield* requireCapability(callerScope);
2171
+ const scope = yield* requireThreadScope(callerScope, "delegate_task");
2172
+ // The task's child runs as an ordinary thread there; this thread keeps the task.
2173
+ const { taskId } = yield* remoteDelegation.delegate(scope, {
2174
+ ...input,
2175
+ target: { ...input.target, environmentId },
2176
+ });
2177
+ return yield* input.mode === "wait"
2178
+ ? awaitTask(scope, taskId, input.timeoutMs)
2179
+ : readTask(scope, taskId, false, true);
2180
+ }
2181
const { scope, parent } = yield* loadThreadCaller(callerScope, "delegate_task");
2182
+ if (
2183
+ input.target?.projectId !== undefined &&
2184
+ input.target.projectId !== parent.thread.projectId
2185
+ ) {
2186
+ return yield* failure(
2187
+ "invalid_request",
2188
+ "A local task runs in this thread's project. Omit target.projectId, or pass target.environmentId to run it in that environment's project.",
2189
+ );
2190
+ }
2191
const parentRun = parent.runs
2192
.filter(ThreadManagementService.isActiveRun)
2193
.toSorted((left, right) => right.ordinal - left.ordinal)[0];
@@ -2311,6 +2367,24 @@ const make = Effect.gen(function* () {
2367
cancelTask: Effect.fn("OrchestratorMcpService.cancelTask")(function* (callerScope, input) {
2368
const scope = yield* requireThreadScope(callerScope, "task_cancel");
2369
const current = yield* readTask(scope, input.taskId);
2370
+ const childThreadId = current.childThreadId;
2371
+ if (childThreadId === null) {
2372
+ // The task runs in a linked environment: its thread there is stopped through the link.
2373
+ const { subagents } = yield* loadProjection(scope.thread.threadId);
2374
+ const remoteTask = subagents.find(
2375
+ (task) =>
2376
+ task.id === input.taskId &&
2377
+ task.origin === "app_owned" &&
2378
+ task.remoteChild !== undefined,
2379
+ );
2380
+ if (remoteTask === undefined) {
2381
+ return yield* failure(
2382
+ "task_not_found",
2383
+ `Delegated task ${input.taskId} does not belong to thread ${scope.thread.threadId}.`,
2384
+ );
2385
+ }
2386
+ return yield* remoteDelegation.cancel(scope, remoteTask, input);
2387
+ }
2388
const key = yield* requestKey(input.clientRequestId);
2389
const parentProjection = yield* loadProjection(scope.thread.threadId);
2390
// Cancelling stops the child and every task under it, each a write to a
@@ -2338,7 +2412,7 @@ const make = Effect.gen(function* () {
2412
}
2413
}
2414
});
2341
- yield* assertStoppable(current.childThreadId);
2415
+ yield* assertStoppable(childThreadId);
2416
const parentTask = parentProjection.subagents.find(
2417
(task) => task.id === input.taskId && task.origin === "app_owned",
2418
);
@@ -2372,7 +2446,7 @@ const make = Effect.gen(function* () {
2446
.dispatch({
2447
type: "thread.stop",
2448
commandId,
2375
- threadId: current.childThreadId,
2449
+ threadId: childThreadId,
2450
stopDelegatedTasks: false,
2451
reason,
2452
})
@@ -2385,7 +2459,7 @@ const make = Effect.gen(function* () {
2459
),
2460
);
2461
yield* threadManagement
2388
- .stopDelegatedTasks({ threadId: current.childThreadId, commandId, reason })
2462
+ .stopDelegatedTasks({ threadId: childThreadId, commandId, reason })
2463
.pipe(
2464
Effect.mapError((error) =>
2465
failure(
@@ -2395,7 +2469,7 @@ const make = Effect.gen(function* () {
2469
),
2470
);
2471
const stopped = yield* threadManagement
2398
- .getThreadRecords(current.childThreadId, ["runs"])
2472
+ .getThreadRecords(childThreadId, ["runs"])
2473
.pipe(Effect.mapError(threadManagementFailure));
2474
for (const run of stopped.runs) {
2475
if (
@@ -2413,7 +2487,7 @@ const make = Effect.gen(function* () {
2487
requestKey: key,
2488
operation: `cancel-task-queued-run:${run.id}`,
2489
}),
2416
- threadId: current.childThreadId,
2490
+ threadId: childThreadId,
2491
runId: run.id,
2492
})
2493
.pipe(Effect.mapError(threadManagementFailure));
@@ -2474,7 +2548,7 @@ const make = Effect.gen(function* () {
2548
status: cancelled ? "cancelled" : current.status,
2549
} satisfies OrchestratorMcpTaskCancelResult;
2550
}
2477
- const child = yield* loadProjection(current.childThreadId);
2551
+ const child = yield* loadProjection(childThreadId);
2552
if (
2553
current.workState !== "waiting_for_children" &&
2554
ThreadManagementService.latestActiveRun(child) === undefined &&
@@ -2873,6 +2947,7 @@ const make = Effect.gen(function* () {
2947
MAX_WAIT_TIMEOUT_MS,
2948
Math.max(1, input.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS),
2949
),
2950
+ ...(input.untilDelegatedWorkSettled === true ? { untilDelegatedWorkSettled: true } : {}),
2951
})
2952
.pipe(Effect.mapError(threadManagementFailure));
2953
const status = result.run === null ? "idle" : runOutcome(result.run);
@@ -2902,6 +2977,11 @@ const make = Effect.gen(function* () {
2977
status,
2978
timedOut: result.timedOut,
2979
...(wakesCaller ? { next: ORCHESTRATOR_MCP_RUNNING_TASK_NEXT } : {}),
2980
+ ...(result.resultRun === undefined
2981
+ ? {}
2982
+ : {
2983
+ resultRun: { runId: result.resultRun.id, status: runOutcome(result.resultRun) },
2984
+ }),
2985
} satisfies OrchestratorMcpThreadWaitResult;
2986
}),
2987
interruptThread: Effect.fn("OrchestratorMcpService.interruptThread")(function* (scope, input) {
@@ -3006,4 +3086,5 @@ export const layer: Layer.Layer<
3086
| ProjectService.ProjectService
3087
| SecretRequests.SecretRequests
3088
| ServerSettings.ServerSettingsService
3089
+ | RemoteDelegation.RemoteDelegation
3090
> = Layer.effect(OrchestratorMcpService, make);
apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts
+24
-10
@@ -43,6 +43,7 @@ import * as ProviderRegistryMock from "../provider/testUtils/providerRegistryMoc
43
import * as ProjectService from "../project/ProjectService.ts";
44
import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts";
45
import * as SecretRequests from "../secrets/SecretRequests.ts";
46
+import * as RemoteDelegation from "../peer/RemoteDelegation.ts";
47
import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
48
import * as McpHttpServer from "./McpHttpServer.ts";
49
import * as McpInvocationContext from "./McpInvocationContext.ts";
@@ -53,6 +54,12 @@ const layerOrchestratorToolkit = McpHttpServer.layerOrchestratorToolkit.pipe(
54
Layer.provide(Layer.mock(GitVcsDriver.GitVcsDriver)({})),
55
);
56
57
+/** A task delegated here always has a local child thread. */
58
+const localChild = (childThreadId: ThreadId | null): ThreadId => {
59
+ if (childThreadId === null) throw new Error("expected a local delegated child");
60
+ return childThreadId;
61
+};
62
+
63
// Effect returns a declared tool failure as `isError` with its encoded payload
64
// as JSON text, never as `structuredContent`.
65
@@ -229,6 +236,7 @@ describe("orchestrator MCP toolkit", () => {
236
Layer.provide(layerOrchestration),
237
),
238
),
239
+ Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
240
Layer.provide(NodeServices.layer),
241
);
242
@@ -355,14 +363,16 @@ describe("orchestrator MCP toolkit", () => {
363
});
364
expect(delegated.resultContextTransferId).not.toBeNull();
365
358
- const delegatedChild = yield* orchestrator.getThreadProjection(delegated.childThreadId);
366
+ const delegatedChild = yield* orchestrator.getThreadProjection(
367
+ localChild(delegated.childThreadId),
368
+ );
369
expect(delegatedChild.thread.lineage.relationshipToParent).toBe("subagent");
370
expect(isProviderNativeSubagentThread(delegatedChild.thread)).toBe(false);
371
const followupStartSequence = yield* orchestrator.getThreadEventSequence(
362
- delegated.childThreadId,
372
+ localChild(delegated.childThreadId),
373
);
374
const runningFollowupCall = yield* invoke("t3_thread_send", {
365
- threadId: delegated.childThreadId,
375
+ threadId: localChild(delegated.childThreadId),
376
message: cancellationPrompt,
377
clientRequestId: "delegated-child-replay-running-1",
378
});
@@ -371,7 +381,7 @@ describe("orchestrator MCP toolkit", () => {
381
).pipe(Effect.orDie);
382
yield* orchestrator
383
.streamStoredEventsFrom({
374
- threadId: delegated.childThreadId,
384
+ threadId: localChild(delegated.childThreadId),
385
afterSequence: followupStartSequence,
386
})
387
.pipe(
@@ -390,7 +400,7 @@ describe("orchestrator MCP toolkit", () => {
400
);
401
402
const queuedFollowupCall = yield* invoke("t3_thread_send", {
393
- threadId: delegated.childThreadId,
403
+ threadId: localChild(delegated.childThreadId),
404
message: queuedFollowupPrompt,
405
mode: "queue",
406
clientRequestId: "delegated-child-replay-queued-1",
@@ -404,7 +414,7 @@ describe("orchestrator MCP toolkit", () => {
414
});
415
416
const pendingProjection = yield* orchestrator.getThreadProjection(
407
- delegated.childThreadId,
417
+ localChild(delegated.childThreadId),
418
);
419
const followupTasks = (yield* orchestrator.getThreadProjection(
420
parentThreadId,
@@ -451,9 +461,11 @@ describe("orchestrator MCP toolkit", () => {
461
latestTerminalResultContextTransferId: null,
462
});
463
454
- const finalSequence = yield* orchestrator.getThreadEventSequence(delegated.childThreadId);
464
+ const finalSequence = yield* orchestrator.getThreadEventSequence(
465
+ localChild(delegated.childThreadId),
466
+ );
467
const interruptCall = yield* invoke("t3_thread_interrupt", {
456
- threadId: delegated.childThreadId,
468
+ threadId: localChild(delegated.childThreadId),
469
runId: runningFollowup.runId,
470
reason: "Allow the queued replay follow-up to run.",
471
clientRequestId: "interrupt-delegated-child-replay-1",
@@ -467,7 +479,7 @@ describe("orchestrator MCP toolkit", () => {
479
});
480
yield* orchestrator
481
.streamStoredEventsFrom({
470
- threadId: delegated.childThreadId,
482
+ threadId: localChild(delegated.childThreadId),
483
afterSequence: finalSequence,
484
})
485
.pipe(
@@ -486,7 +498,9 @@ describe("orchestrator MCP toolkit", () => {
498
),
499
);
500
489
- const finalProjection = yield* orchestrator.getThreadProjection(delegated.childThreadId);
501
+ const finalProjection = yield* orchestrator.getThreadProjection(
502
+ localChild(delegated.childThreadId),
503
+ );
504
expect(finalProjection.runs.find((run) => run.id === runningFollowup.runId)?.status).toBe(
505
"interrupted",
506
);
apps/server/src/mcp/TaskCancelNativeSubagent.integration.test.ts
+2
@@ -40,6 +40,7 @@ import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts
40
import * as SecretRequests from "../secrets/SecretRequests.ts";
41
import type { McpInvocationScope } from "./McpInvocationContext.ts";
42
import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";
43
+import * as RemoteDelegation from "../peer/RemoteDelegation.ts";
44
45
const layerOrchestratorService = OrchestratorMcpService.layer.pipe(
46
Layer.provide(Layer.mock(ThreadLaunchService.ThreadLaunchService)({})),
@@ -155,6 +156,7 @@ it.effect("task_cancel ends a delegated child's background native subagent", ()
156
Layer.mock(ProviderRegistry.ProviderRegistry)({ getProviders: Effect.succeed([]) }),
157
Layer.mock(ProjectService.ProjectService)({}),
158
Layer.mock(SecretRequests.SecretRequests)({}),
159
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
160
ServerSettings.layerTest(),
161
Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
162
NodeServices.layer,
apps/server/src/mcp/ThreadMetadataMcpService.ts
+1
-1
@@ -16,7 +16,7 @@ import * as Layer from "effect/Layer";
16
17
import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
18
import type { McpInvocationScope } from "./McpInvocationContext.ts";
19
-import { threadNotFound } from "./OrchestratorMcpService.ts";
19
+import { threadNotFound } from "./threadAccess.ts";
20
21
export class ThreadMetadataMcpService extends Context.Service<
22
ThreadMetadataMcpService,
apps/server/src/mcp/delegatedTaskModes.ts
new
+95
@@ -0,0 +1,95 @@
1
+import {
2
+ type ModelSelection,
3
+ OrchestratorMcpFailure,
4
+ type OrchestratorMcpDelegateTaskInput,
5
+ type OrchestratorMcpInteractionMode,
6
+ type OrchestratorMcpRuntimeMode,
7
+ type ProviderInteractionMode,
8
+ type RuntimeMode,
9
+} from "@t3tools/contracts";
10
+import * as Effect from "effect/Effect";
11
+
12
+/** How much a runtime mode allows, narrowest first. */
13
+export function runtimeModeRank(mode: RuntimeMode): number {
14
+ switch (mode) {
15
+ case "approval-required":
16
+ return 0;
17
+ case "auto-accept-edits":
18
+ return 1;
19
+ case "auto":
20
+ return 2;
21
+ case "full-access":
22
+ return 3;
23
+ }
24
+}
25
+
26
+/** How much an interaction mode allows: plan, then default. */
27
+export function interactionModeRank(mode: ProviderInteractionMode): number {
28
+ return mode === "plan" ? 0 : 1;
29
+}
30
+
31
+/**
32
+ * The mode a child runs at: the one asked for, never broader than its parent's.
33
+ * An inherited mode the target provider does not offer steps down to the
34
+ * broadest one it does; an explicitly requested one is refused instead.
35
+ */
36
+export function resolveRuntimeMode(
37
+ parentMode: RuntimeMode,
38
+ requested: OrchestratorMcpRuntimeMode | undefined,
39
+ target?: {
40
+ readonly modelSelection: ModelSelection;
41
+ readonly supportedRuntimeModes: ReadonlyArray<RuntimeMode> | undefined;
42
+ },
43
+): Effect.Effect<RuntimeMode, OrchestratorMcpFailure> {
44
+ const inherited = requested === undefined || requested === "inherit";
45
+ const resolved = inherited ? parentMode : requested;
46
+ if (runtimeModeRank(resolved) > runtimeModeRank(parentMode)) {
47
+ return Effect.fail(
48
+ new OrchestratorMcpFailure({
49
+ code: "runtime_mode_escalation_denied",
50
+ message: `Child runtime mode ${resolved} is broader than parent mode ${parentMode}.`,
51
+ }),
52
+ );
53
+ }
54
+ const supported = target?.supportedRuntimeModes;
55
+ if (supported === undefined || supported.length === 0 || supported.includes(resolved)) {
56
+ return Effect.succeed(resolved);
57
+ }
58
+ if (!inherited) {
59
+ return Effect.fail(
60
+ new OrchestratorMcpFailure({
61
+ code: "invalid_request",
62
+ message: `Provider ${target?.modelSelection.instanceId} does not offer runtime mode ${resolved}, so it would run as approval-required. Use one of: ${supported.join(", ")}.`,
63
+ }),
64
+ );
65
+ }
66
+ return Effect.succeed(
67
+ supported
68
+ .filter((mode) => runtimeModeRank(mode) <= runtimeModeRank(resolved))
69
+ .toSorted((left, right) => runtimeModeRank(right) - runtimeModeRank(left))[0] ??
70
+ "approval-required",
71
+ );
72
+}
73
+
74
+/** The same, for interaction modes. */
75
+export function resolveInteractionMode(
76
+ parentMode: ProviderInteractionMode,
77
+ requested: OrchestratorMcpInteractionMode | undefined,
78
+): Effect.Effect<ProviderInteractionMode, OrchestratorMcpFailure> {
79
+ const resolved = requested === undefined || requested === "inherit" ? parentMode : requested;
80
+ return interactionModeRank(resolved) > interactionModeRank(parentMode)
81
+ ? Effect.fail(
82
+ new OrchestratorMcpFailure({
83
+ code: "interaction_mode_escalation_denied",
84
+ message: `Child interaction mode ${resolved} is broader than parent mode ${parentMode}.`,
85
+ }),
86
+ )
87
+ : Effect.succeed(resolved);
88
+}
89
+
90
+/** The task as its child receives it, with the role the caller asked for. */
91
+export function taskPrompt(input: OrchestratorMcpDelegateTaskInput): string {
92
+ return input.role === undefined || input.role === "general"
93
+ ? input.task
94
+ : `Act as the ${input.role} sub-agent for this task.\n\n${input.task}`;
95
+}
apps/server/src/mcp/linkOrigin.test.ts
+20
-1
@@ -37,6 +37,7 @@ import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts
37
import * as ServerSettings from "../serverSettings.ts";
38
import * as CommandReceiptStore from "../orchestration-v2/CommandReceiptStore.ts";
39
import * as SecretRequests from "../secrets/SecretRequests.ts";
40
+import * as RemoteDelegation from "../peer/RemoteDelegation.ts";
41
import * as SourceControlRepositoryService from "../sourceControl/SourceControlRepositoryService.ts";
42
import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
43
import * as McpHttpServer from "./McpHttpServer.ts";
@@ -92,6 +93,7 @@ const layerLaunches = Layer.effect(
93
branch: null,
94
worktreePath: null,
95
...(input.linkOrigin === undefined ? {} : { linkOrigin: input.linkOrigin }),
96
+ ...(input.delegatedFrom === undefined ? {} : { delegatedFrom: input.delegatedFrom }),
97
createdBy: input.createdBy,
98
creationSource: input.creationSource,
99
})
@@ -156,6 +158,7 @@ const layerTools = Layer.mergeAll(
158
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
159
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
160
Layer.provide(Layer.mock(ThreadSearch.ThreadSearch)({})),
161
+ Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
162
Layer.provide(
163
Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({ namedProjectsRoot: "/p" }),
164
),
@@ -226,11 +229,16 @@ const failureCode = (result: McpSchema.CallToolResult) => {
229
: undefined;
230
};
231
229
-const launch = (scope: McpInvocationContext.McpInvocationScope, title: string) =>
232
+const launch = (
233
+ scope: McpInvocationContext.McpInvocationScope,
234
+ title: string,
235
+ extra: Record<string, unknown> = {},
236
+) =>
237
call(scope, "t3_thread_launch", {
238
projectId,
239
title,
240
modelSelection: { instanceId, model: "gpt-5" },
241
+ ...extra,
242
}).pipe(
243
Effect.map((result) => {
244
assert.equal(result.isError, false, JSON.stringify(result.content));
@@ -309,6 +317,17 @@ it.layer(Layer.provideMerge(layerTools, layerOrchestration))("work a link starts
317
// An ordinary outside agent's launch is not a link's.
318
const plain = yield* launch(claudeCode, "Started by Claude Code");
319
assert.equal((yield* projections.getThreadShell(plain))?.linkOrigin, undefined);
320
+
321
+ // A link's delegated task names its parent there; only a link's launch may.
322
+ const delegatedFrom = {
323
+ environmentId: "environment-laptop",
324
+ threadId: "thread:laptop-parent",
325
+ title: "Laptop parent",
326
+ };
327
+ const task = yield* launch(laptop, "Delegated from the laptop", { delegatedFrom });
328
+ assert.deepEqual((yield* projections.getThreadShell(task))?.delegatedFrom, delegatedFrom);
329
+ const claimed = yield* launch(claudeCode, "Claims a parent", { delegatedFrom });
330
+ assert.equal((yield* projections.getThreadShell(claimed))?.delegatedFrom, undefined);
331
}),
332
);
333
apps/server/src/mcp/threadAccess.ts
+45
-12
@@ -3,9 +3,10 @@ import {
3
CommandId,
4
OrchestratorMcpFailure,
5
type ProjectId,
6
+ type ProviderInstanceId,
7
type ProviderInteractionMode,
8
type RuntimeMode,
8
- type ThreadId,
9
+ ThreadId,
10
type OrchestrationV2ThreadShell,
11
} from "@t3tools/contracts";
12
import * as Crypto from "effect/Crypto";
@@ -13,9 +14,30 @@ import * as Effect from "effect/Effect";
14
15
import type { OrchestratorV2Error } from "../orchestration-v2/Orchestrator.ts";
16
import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts";
16
-import * as OrchestrationMcp from "./OrchestratorMcpService.ts";
17
+import { resolveInteractionMode, resolveRuntimeMode } from "./delegatedTaskModes.ts";
18
import * as McpInvocationContext from "./McpInvocationContext.ts";
19
20
+/**
21
+ * Threads an agent starts over MCP are `mcp:<uuid>`, and agents often paste the
22
+ * bare uuid. The id is never rewritten, so permission checks keyed on it still
23
+ * hold; the miss only names a live thread the caller could read by its full id.
24
+ */
25
+export const threadNotFound = Effect.fn("OrchestratorMcpService.threadNotFound")(function* (
26
+ threads: Pick<ThreadManagement.ThreadManagementService["Service"], "getThreadShell">,
27
+ threadId: ThreadId,
28
+ message: string,
29
+) {
30
+ const prefixed = ThreadId.make(`mcp:${threadId}`);
31
+ const shell = yield* threads.getThreadShell(prefixed).pipe(Effect.orElseSucceed(() => null));
32
+ return yield* new OrchestratorMcpFailure({
33
+ code: "thread_not_found",
34
+ message:
35
+ shell === null || shell.deletedAt !== null
36
+ ? message
37
+ : `${message} Did you mean \`${prefixed}\`?`,
38
+ });
39
+});
40
+
41
export const unavailable = () =>
42
new OrchestratorMcpFailure({
43
code: "orchestration_error",
@@ -92,17 +114,32 @@ export const assertTargetWithinLimits = (
114
limits: CallerLimits,
115
target: { readonly runtimeMode: RuntimeMode; readonly interactionMode: ProviderInteractionMode },
116
) =>
95
- OrchestrationMcp.resolveRuntimeMode(limits.runtimeMode, target.runtimeMode).pipe(
96
- Effect.andThen(
97
- OrchestrationMcp.resolveInteractionMode(limits.interactionMode, target.interactionMode),
98
- ),
117
+ resolveRuntimeMode(limits.runtimeMode, target.runtimeMode).pipe(
118
+ Effect.andThen(resolveInteractionMode(limits.interactionMode, target.interactionMode)),
119
Effect.asVoid,
120
);
121
122
+/** Background subagents retain credentials until provider exit; archived threads and other instances cannot act. */
123
+export const isLiveCallerShell = (
124
+ shell: Pick<
125
+ OrchestrationV2ThreadShell,
126
+ "archivedAt" | "activeRunId" | "providerInstanceId" | "pendingBackgroundTasks"
127
+ > | null,
128
+ providerInstanceId: ProviderInstanceId | undefined,
129
+) =>
130
+ shell !== null &&
131
+ shell.archivedAt === null &&
132
+ shell.providerInstanceId === providerInstanceId &&
133
+ (shell.activeRunId !== null ||
134
+ (shell.pendingBackgroundTasks?.some(
135
+ (task) => task.kind === "subagent" && task.providerInstanceId === providerInstanceId,
136
+ ) ??
137
+ false));
138
+
139
/** Thread callers need a live run or its background subagent in an unarchived thread. OAuth clients rely on their session and ceiling. */
140
export function assertLiveCaller({ caller, scope }: Caller) {
141
if (caller === undefined) return Effect.void;
105
- return OrchestrationMcp.isLiveCallerShell(caller, scope.thread?.providerInstanceId)
142
+ return isLiveCallerShell(caller, scope.thread?.providerInstanceId)
143
? Effect.void
144
: Effect.fail(
145
new OrchestratorMcpFailure({
@@ -148,11 +185,7 @@ export const readThread = Effect.fn("mcp.readThread")(function* <
185
const targetId = yield* resolveThreadId(context, threadId);
186
const shell = yield* context.threads.getThreadShell(targetId).pipe(Effect.mapError(unavailable));
187
if (shell === null || shell.deletedAt !== null) {
151
- return yield* OrchestrationMcp.threadNotFound(
152
- context.threads,
153
- targetId,
154
- "The thread was not found.",
155
- );
188
+ return yield* threadNotFound(context.threads, targetId, "The thread was not found.");
189
}
190
const projection = yield* context.threads
191
.getProjectThreadRecords({ projectId: shell.projectId, threadId: targetId }, fields, {
apps/server/src/mcp/toolkits/core.test.ts
+5
@@ -45,6 +45,7 @@ import * as PreviewBrowser from "../../preview/PreviewBrowser.ts";
45
import * as ProjectService from "../../project/ProjectService.ts";
46
import * as ProviderRegistry from "../../provider/ProviderRegistry.ts";
47
import * as SecretRequests from "../../secrets/SecretRequests.ts";
48
+import * as RemoteDelegation from "../../peer/RemoteDelegation.ts";
49
import * as ScheduledTaskService from "../../scheduledTasks/ScheduledTaskService.ts";
50
import * as ServerSettings from "../../serverSettings.ts";
51
import * as McpHttpServer from "../McpHttpServer.ts";
@@ -603,6 +604,7 @@ it.effect("refuses act-as-caller tools to a client caller", () =>
604
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
605
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
606
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
607
+ Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
608
),
609
),
610
),
@@ -659,6 +661,7 @@ it.effect("a caller cannot rewrite a scheduled task that runs above its own mode
661
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
662
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
663
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
664
+ Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
665
),
666
),
667
),
@@ -743,6 +746,7 @@ it.effect.each(["t3_thread_interrupt", "t3_workflow_stop"])(
746
Layer.provide(Layer.mock(ScheduledTaskService.ScheduledTaskService)({})),
747
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
748
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
749
+ Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
750
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
751
),
752
),
@@ -837,6 +841,7 @@ it.effect("discovers workflow stop targets and requires orchestration capability
841
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
842
Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
843
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
844
+ Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
845
),
846
),
847
);
apps/server/src/mcp/toolkits/project/handlers.ts
+7
-6
@@ -20,7 +20,7 @@ import * as GitVcsDriver from "../../../vcs/GitVcsDriver.ts";
20
import * as ServerSettings from "../../../serverSettings.ts";
21
import { resolveProjectSettings } from "@t3tools/shared/projectSettings";
22
import { formatThreadLink } from "@t3tools/shared/threadLinks";
23
-import { resolveRuntimeMode } from "../../OrchestratorMcpService.ts";
23
+import { resolveRuntimeMode } from "../../delegatedTaskModes.ts";
24
import * as McpInvocationContext from "../../McpInvocationContext.ts";
25
import * as McpToolAccess from "../../McpToolAccess.ts";
26
import { newCommandId, readCaller, resolveProjectId, unavailable } from "../../threadAccess.ts";
@@ -217,6 +217,8 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, {
217
createdBy: "agent",
218
creationSource: "mcp",
219
...(linkOrigin === undefined ? {} : { linkOrigin }),
220
+ // Kept only alongside linkOrigin: thread.create drops it otherwise.
221
+ ...(input.delegatedFrom === undefined ? {} : { delegatedFrom: input.delegatedFrom }),
222
}).pipe(
223
Effect.mapError((error) => {
224
if (error._tag === "AttachmentClaimError") {
@@ -251,11 +253,10 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, {
253
t3_project_list: McpToolAccess.reads((input) =>
254
Effect.gen(function* () {
255
const projects = yield* access;
254
- const snapshot = yield* projects.snapshot.pipe(Effect.mapError(unavailable));
255
- const rows = snapshot.projects.filter((project) => project.deletedAt === null);
256
- const start = input.cursor ?? 0,
257
- end = start + (input.limit ?? 20);
258
- return { projects: rows.slice(start, end), nextCursor: end < rows.length ? end : null };
256
+ // Identities are resolved: linked environments find this side's project by repository.
257
+ return yield* projects
258
+ .listPage({ cursor: input.cursor ?? 0, limit: input.limit ?? 20 })
259
+ .pipe(Effect.mapError(unavailable));
260
}),
261
),
262
t3_project_read: McpToolAccess.reads((input) =>
apps/server/src/mcp/toolkits/project/tools.ts
+3
@@ -5,6 +5,7 @@ import {
5
TrimmedNonEmptyString,
6
ThreadId,
7
RunId,
8
+ OrchestrationV2DelegatedFrom,
9
OrchestrationV2RunStatus,
10
OrchestrationV2ThreadLaunchWorkspaceStrategy,
11
RuntimeMode,
@@ -146,6 +147,8 @@ const ThreadLaunchTool = Tool.make("t3_thread_launch", {
147
),
148
attachments: Schema.optional(Schema.Array(McpAttachmentInput).check(Schema.isMaxLength(8))),
149
clientRequestId: Schema.optional(OrchestratorMcpClientRequestId),
150
+ /** Set by a linked environment launching its agent's delegated task here; ignored otherwise. */
151
+ delegatedFrom: Schema.optional(OrchestrationV2DelegatedFrom),
152
}),
153
success: Schema.Struct({
154
threadId: ThreadId,
apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts
+1
@@ -121,6 +121,7 @@ const layerTest = Layer.mergeAll(RuntimeLayer.layer, RuntimeLayer.layerEventSink
121
repositoryIdentityResolved: false,
122
}),
123
request: () => Effect.void,
124
+ readRepositoryIdentity: () => Effect.succeed(null),
125
getAvailable: () =>
126
Effect.succeed({
127
repositoryIdentity: null,
apps/server/src/orchestration-v2/Orchestrator.ts
+401
-1
@@ -47,6 +47,7 @@ import {
47
type OrchestrationV2ExecutionNode,
48
type OrchestrationV2ProviderThread,
49
type OrchestrationV2ProviderTurn,
50
+ type OrchestrationV2RemoteTaskChild,
51
type OrchestrationV2Run,
52
type OrchestrationV2RunAttempt,
53
type OrchestrationV2ThreadShell,
@@ -516,6 +517,9 @@ function commandThreadId(command: OrchestrationV2ServerCommand): ThreadId {
517
case "provider.switch":
518
return command.threadId;
519
case "delegated_task.request":
520
+ case "delegated_task.remote.request":
521
+ case "delegated_task.remote.complete":
522
+ case "delegated_task.remote.stop":
523
case "delegated_task.wake-policy":
524
case "delegated_task.completion-delivery.acknowledge":
525
case "delegated_task.completion-delivery.dispose":
@@ -2540,6 +2544,10 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
2544
activeProviderThreadId: null,
2545
pullRequests: [],
2546
...(command.linkOrigin === undefined ? {} : { linkOrigin: command.linkOrigin }),
2547
+ // Only stamped work names a remote parent, so a client cannot claim one.
2548
+ ...(command.linkOrigin === undefined || command.delegatedFrom === undefined
2549
+ ? {}
2550
+ : { delegatedFrom: command.delegatedFrom }),
2551
lineage: {
2552
parentThreadId: null,
2553
relationshipToParent: null,
@@ -7561,6 +7569,386 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
7569
});
7570
});
7571
7572
+ /**
7573
+ * Records a task that runs in a linked environment on its parent: the
7574
+ * task, its node and its turn item, as a local delegation does, but no child
7575
+ * thread here. The parent's own checks are the local request's.
7576
+ */
7577
+ const dispatchRemoteDelegatedTaskRequest = Effect.fn(
7578
+ "orchestrationV2.dispatch.remoteDelegatedTaskRequest",
7579
+ )(function* (
7580
+ command: Extract<
7581
+ OrchestrationV2InternalCommand,
7582
+ { readonly type: "delegated_task.remote.request" }
7583
+ >,
7584
+ events: Ref.Ref<Array<OrchestrationV2DomainEvent>>,
7585
+ ) {
7586
+ const parentProjection = yield* projectionStore
7587
+ .getThreadRecords(command.parentThreadId, [
7588
+ "runs",
7589
+ "nodes",
7590
+ "subagents",
7591
+ "providerTurns",
7592
+ "attempts",
7593
+ ])
7594
+ .pipe(
7595
+ Effect.mapError(
7596
+ (cause) => new OrchestratorProjectionError({ threadId: command.parentThreadId, cause }),
7597
+ ),
7598
+ );
7599
+ const parentRun = parentProjection.runs.find(
7600
+ (candidate) => candidate.id === command.parentRunId,
7601
+ );
7602
+ if (parentRun === undefined || !isBlockingRun(parentRun) || parentRun.rootNodeId === null) {
7603
+ return yield* new OrchestratorDispatchError({
7604
+ commandId: command.commandId,
7605
+ commandType: command.type,
7606
+ cause: `Parent run ${command.parentRunId} is not active.`,
7607
+ });
7608
+ }
7609
+ if (yield* stopReachedRun(command, command.parentThreadId, parentRun.id)) {
7610
+ return yield* new OrchestratorDispatchError({
7611
+ commandId: command.commandId,
7612
+ commandType: command.type,
7613
+ cause: `Parent run ${command.parentRunId} is stopping.`,
7614
+ });
7615
+ }
7616
+ const now = yield* DateTime.now;
7617
+ const taskNodeId = idAllocator.derive.delegatedTaskNode({ commandId: command.commandId });
7618
+ const taskTurnItemId = idAllocator.derive.delegatedTaskTurnItem({
7619
+ commandId: command.commandId,
7620
+ });
7621
+ const taskTitle = subagentThreadTitle({
7622
+ parentTitle: parentProjection.thread.title,
7623
+ prompt: command.task,
7624
+ ...(command.title === undefined ? {} : { title: command.title }),
7625
+ ordinal: parentProjection.subagents.length + 1,
7626
+ });
7627
+ const common = {
7628
+ threadId: command.parentThreadId,
7629
+ runId: parentRun.id,
7630
+ nodeId: taskNodeId,
7631
+ driver: command.driver,
7632
+ providerInstanceId: command.modelSelection.instanceId,
7633
+ occurredAt: now,
7634
+ };
7635
+ const emitEvent = emit(events, command);
7636
+ yield* emitEvent({
7637
+ ...common,
7638
+ type: "node.updated",
7639
+ payload: {
7640
+ id: taskNodeId,
7641
+ threadId: command.parentThreadId,
7642
+ runId: parentRun.id,
7643
+ parentNodeId: command.parentNodeId,
7644
+ rootNodeId: parentRun.rootNodeId,
7645
+ kind: "subagent",
7646
+ status: "running",
7647
+ countsForRun: false,
7648
+ providerThreadId: null,
7649
+ providerTurnId: null,
7650
+ nativeItemRef: null,
7651
+ runtimeRequestId: null,
7652
+ checkpointScopeId: null,
7653
+ startedAt: now,
7654
+ completedAt: null,
7655
+ },
7656
+ });
7657
+ yield* emitEvent({
7658
+ ...common,
7659
+ type: "subagent.updated",
7660
+ payload: {
7661
+ id: taskNodeId,
7662
+ threadId: command.parentThreadId,
7663
+ runId: parentRun.id,
7664
+ parentNodeId: command.parentNodeId,
7665
+ origin: "app_owned",
7666
+ createdBy: "agent",
7667
+ driver: command.driver,
7668
+ providerInstanceId: command.modelSelection.instanceId,
7669
+ providerThreadId: null,
7670
+ childThreadId: null,
7671
+ remoteChild: command.remoteChild,
7672
+ nativeTaskRef: null,
7673
+ prompt: command.task,
7674
+ title: command.title ?? null,
7675
+ model: command.modelSelection.model,
7676
+ ...(command.completionWake === undefined ? {} : { completionWake: command.completionWake }),
7677
+ status: "running",
7678
+ result: null,
7679
+ startedAt: now,
7680
+ completedAt: null,
7681
+ updatedAt: now,
7682
+ },
7683
+ });
7684
+ yield* emitEvent({
7685
+ ...common,
7686
+ type: "turn-item.updated",
7687
+ payload: {
7688
+ id: taskTurnItemId,
7689
+ threadId: command.parentThreadId,
7690
+ runId: parentRun.id,
7691
+ nodeId: taskNodeId,
7692
+ providerThreadId: parentRun.providerThreadId,
7693
+ providerTurnId: providerTurnForRun(parentProjection, parentRun)?.id ?? null,
7694
+ nativeItemRef: null,
7695
+ parentItemId: null,
7696
+ ordinal: yield* nextTurnItemOrdinal(parentProjection),
7697
+ status: "running",
7698
+ title: command.title ?? taskTitle,
7699
+ startedAt: now,
7700
+ completedAt: null,
7701
+ updatedAt: now,
7702
+ type: "subagent",
7703
+ subagentId: taskNodeId,
7704
+ origin: "app_owned",
7705
+ driver: command.driver,
7706
+ providerInstanceId: command.modelSelection.instanceId,
7707
+ childThreadId: null,
7708
+ remoteChild: command.remoteChild,
7709
+ prompt: command.task,
7710
+ result: null,
7711
+ },
7712
+ });
7713
+ });
7714
+
7715
+ /**
7716
+ * Completes a task that ran in a linked environment: the parent half of
7717
+ * `finalizeAppOwnedSubagent`, with the result its thread there ended with.
7718
+ * It runs under the parent's lock, so it never interleaves with a wake
7719
+ * policy change or a delivery on the same task.
7720
+ */
7721
+ const dispatchRemoteDelegatedTaskComplete = Effect.fn(
7722
+ "orchestrationV2.dispatch.remoteDelegatedTaskComplete",
7723
+ )(function* (
7724
+ command: Extract<
7725
+ OrchestrationV2InternalCommand,
7726
+ { readonly type: "delegated_task.remote.complete" }
7727
+ >,
7728
+ events: Ref.Ref<Array<OrchestrationV2DomainEvent>>,
7729
+ ) {
7730
+ const parentProjection = yield* projectionStore
7731
+ .getThreadRecords(
7732
+ command.parentThreadId,
7733
+ ["runs", "messages", "subagents", "providerTurns", "nodes", "turnItems"],
7734
+ { turnItemTypes: ["subagent"], messageRoles: ["user"] },
7735
+ )
7736
+ .pipe(
7737
+ Effect.mapError(
7738
+ (cause) => new OrchestratorProjectionError({ threadId: command.parentThreadId, cause }),
7739
+ ),
7740
+ );
7741
+ const task = parentProjection.subagents.find(
7742
+ (candidate) =>
7743
+ candidate.id === command.taskId &&
7744
+ candidate.origin === "app_owned" &&
7745
+ candidate.remoteChild !== undefined,
7746
+ );
7747
+ if (task === undefined) {
7748
+ return yield* new OrchestratorDispatchError({
7749
+ commandId: command.commandId,
7750
+ commandType: command.type,
7751
+ cause: `Delegated task ${command.taskId} is not a remote task of thread ${command.parentThreadId}.`,
7752
+ });
7753
+ }
7754
+ if (
7755
+ command.stoppedThere === "stopped" &&
7756
+ (command.stopCount ?? 0) !== (task.remoteChild?.stopCount ?? 0)
7757
+ )
7758
+ return;
7759
+ const remoteChild =
7760
+ command.stoppedThere === undefined
7761
+ ? task.remoteChild
7762
+ : { ...task.remoteChild!, stoppedThere: true };
7763
+ // The first result stands; a repeated follower report records nothing, which
7764
+ // the dispatcher refuses. A stop there after the result is still recorded, but
7765
+ // a run that ended by itself does not settle a stop the task here still owes.
7766
+ if (task.result !== null) {
7767
+ // A Stop or cancel here that lost the race to the result still owes its stop.
7768
+ if (command.stoppedThere === undefined) {
7769
+ return yield* emitRemoteStopOwed(events, command, task, task.remoteChild!);
7770
+ }
7771
+ const owesStop =
7772
+ task.status === "cancelled" ||
7773
+ task.status === "interrupted" ||
7774
+ task.remoteChild?.stoppedThere === false;
7775
+ if (
7776
+ task.remoteChild?.stoppedThere === true ||
7777
+ (owesStop && command.stoppedThere !== "stopped")
7778
+ )
7779
+ return;
7780
+ const now = yield* DateTime.now;
7781
+ yield* emit(
7782
+ events,
7783
+ command,
7784
+ )({
7785
+ type: "subagent.updated",
7786
+ threadId: command.parentThreadId,
7787
+ ...(task.runId === null ? {} : { runId: task.runId }),
7788
+ nodeId: task.id,
7789
+ driver: task.driver,
7790
+ occurredAt: now,
7791
+ payload: { ...task, remoteChild, updatedAt: now },
7792
+ });
7793
+ return;
7794
+ }
7795
+ const now = yield* DateTime.now;
7796
+ const updatedTask: OrchestrationV2Subagent = {
7797
+ ...task,
7798
+ remoteChild,
7799
+ status: command.status,
7800
+ result: command.result,
7801
+ completedAt: now,
7802
+ updatedAt: now,
7803
+ };
7804
+ const parentRun =
7805
+ task.runId === null
7806
+ ? undefined
7807
+ : parentProjection.runs.find((candidate) => candidate.id === task.runId);
7808
+ const plan = yield* planDelegatedCompletionDelivery({
7809
+ parentProjection,
7810
+ parentRun,
7811
+ task,
7812
+ updatedTask,
7813
+ now,
7814
+ }).pipe(mapDispatchError(command));
7815
+ const emitEvent = emit(events, command);
7816
+ yield* emitEvent({
7817
+ type: "subagent.updated",
7818
+ threadId: command.parentThreadId,
7819
+ ...(task.runId === null ? {} : { runId: task.runId }),
7820
+ nodeId: task.id,
7821
+ driver: task.driver,
7822
+ occurredAt: now,
7823
+ payload: plan.task,
7824
+ });
7825
+ if (plan.parentRun !== undefined) {
7826
+ yield* emitEvent({
7827
+ type: "run.updated",
7828
+ threadId: command.parentThreadId,
7829
+ runId: plan.parentRun.id,
7830
+ ...(plan.parentRun.rootNodeId === null ? {} : { nodeId: plan.parentRun.rootNodeId }),
7831
+ providerInstanceId: plan.parentRun.providerInstanceId,
7832
+ occurredAt: now,
7833
+ payload: plan.parentRun,
7834
+ });
7835
+ }
7836
+ if (plan.message !== undefined) {
7837
+ yield* emitEvent({
7838
+ type: "message.updated",
7839
+ threadId: command.parentThreadId,
7840
+ ...(plan.message.runId === null ? {} : { runId: plan.message.runId }),
7841
+ ...(plan.message.nodeId === null ? {} : { nodeId: plan.message.nodeId }),
7842
+ providerInstanceId:
7843
+ plan.parentRun?.providerInstanceId ?? parentProjection.thread.providerInstanceId,
7844
+ occurredAt: now,
7845
+ payload: plan.message,
7846
+ });
7847
+ }
7848
+ const node = parentProjection.nodes.find((candidate) => candidate.id === task.id);
7849
+ if (node !== undefined) {
7850
+ yield* emitEvent({
7851
+ type: "node.updated",
7852
+ threadId: command.parentThreadId,
7853
+ ...(node.runId === null ? {} : { runId: node.runId }),
7854
+ nodeId: node.id,
7855
+ driver: task.driver,
7856
+ occurredAt: now,
7857
+ payload: { ...node, status: command.status, completedAt: now },
7858
+ });
7859
+ }
7860
+ const item = parentProjection.turnItems.find(
7861
+ (candidate) => candidate.type === "subagent" && candidate.subagentId === task.id,
7862
+ );
7863
+ if (item !== undefined) {
7864
+ yield* emitEvent({
7865
+ type: "turn-item.updated",
7866
+ threadId: command.parentThreadId,
7867
+ ...(item.runId === null ? {} : { runId: item.runId }),
7868
+ ...(item.nodeId === null ? {} : { nodeId: item.nodeId }),
7869
+ driver: task.driver,
7870
+ occurredAt: now,
7871
+ payload: {
7872
+ ...item,
7873
+ status: command.status,
7874
+ result: command.result,
7875
+ completedAt: now,
7876
+ updatedAt: now,
7877
+ } as OrchestrationV2TurnItem,
7878
+ });
7879
+ }
7880
+ });
7881
+
7882
+ /**
7883
+ * Owes a stop to the thread there of a remote task that already has its
7884
+ * result. Only `remoteChild.stoppedThere` changes, so the result and its
7885
+ * delivery stand; the follower sends the stop and clears it.
7886
+ */
7887
+ const dispatchRemoteDelegatedTaskStop = Effect.fn(
7888
+ "orchestrationV2.dispatch.remoteDelegatedTaskStop",
7889
+ )(function* (
7890
+ command: Extract<
7891
+ OrchestrationV2InternalCommand,
7892
+ { readonly type: "delegated_task.remote.stop" }
7893
+ >,
7894
+ events: Ref.Ref<Array<OrchestrationV2DomainEvent>>,
7895
+ ) {
7896
+ const { subagents } = yield* projectionStore
7897
+ .getThreadRecords(command.parentThreadId, ["subagents"])
7898
+ .pipe(
7899
+ Effect.mapError(
7900
+ (cause) => new OrchestratorProjectionError({ threadId: command.parentThreadId, cause }),
7901
+ ),
7902
+ );
7903
+ const task = subagents.find(
7904
+ (candidate) =>
7905
+ candidate.id === command.taskId &&
7906
+ candidate.origin === "app_owned" &&
7907
+ candidate.remoteChild !== undefined &&
7908
+ candidate.result !== null,
7909
+ );
7910
+ if (task?.remoteChild === undefined) {
7911
+ return yield* new OrchestratorDispatchError({
7912
+ commandId: command.commandId,
7913
+ commandType: command.type,
7914
+ cause: `Delegated task ${command.taskId} is not a finished remote task of thread ${command.parentThreadId}.`,
7915
+ });
7916
+ }
7917
+ yield* emitRemoteStopOwed(events, command, task, task.remoteChild);
7918
+ });
7919
+
7920
+ const emitRemoteStopOwed = Effect.fn("orchestrationV2.dispatch.remoteStopOwed")(function* (
7921
+ events: Ref.Ref<Array<OrchestrationV2DomainEvent>>,
7922
+ command: Extract<
7923
+ OrchestrationV2InternalCommand,
7924
+ { readonly type: "delegated_task.remote.complete" | "delegated_task.remote.stop" }
7925
+ >,
7926
+ task: OrchestrationV2Subagent,
7927
+ remoteChild: OrchestrationV2RemoteTaskChild,
7928
+ ) {
7929
+ const now = yield* DateTime.now;
7930
+ yield* emit(
7931
+ events,
7932
+ command,
7933
+ )({
7934
+ type: "subagent.updated",
7935
+ threadId: command.parentThreadId,
7936
+ ...(task.runId === null ? {} : { runId: task.runId }),
7937
+ nodeId: task.id,
7938
+ driver: task.driver,
7939
+ occurredAt: now,
7940
+ payload: {
7941
+ ...task,
7942
+ remoteChild: {
7943
+ ...remoteChild,
7944
+ stoppedThere: false,
7945
+ stopCount: (remoteChild.stopCount ?? 0) + 1,
7946
+ },
7947
+ updatedAt: now,
7948
+ },
7949
+ });
7950
+ });
7951
+
7952
// After blocking waits time out, enable later completions to wake the parent.
7953
// Hold the parent dispatch lock shared with finalization to serialize full-row writes.
7954
const dispatchDelegatedTaskWakePolicy = Effect.fn(
@@ -12117,6 +12505,15 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
12505
case "delegated_task.request":
12506
yield* dispatchDelegatedTaskRequest(command, events, effects);
12507
break;
12508
+ case "delegated_task.remote.request":
12509
+ yield* dispatchRemoteDelegatedTaskRequest(command, events);
12510
+ break;
12511
+ case "delegated_task.remote.complete":
12512
+ yield* dispatchRemoteDelegatedTaskComplete(command, events);
12513
+ break;
12514
+ case "delegated_task.remote.stop":
12515
+ yield* dispatchRemoteDelegatedTaskStop(command, events);
12516
+ break;
12517
case "delegated_task.wake-policy":
12518
yield* dispatchDelegatedTaskWakePolicy(command, events);
12519
break;
@@ -12350,7 +12747,10 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
12747
if (command.type === "notification.delivery.accept") {
12748
yield* mapDispatchError(command)(offerDelegatedCompletionDeliveries(command.threadId));
12749
}
12353
- if (command.type === "delegated_task.wake-policy") {
12750
+ if (
12751
+ command.type === "delegated_task.wake-policy" ||
12752
+ command.type === "delegated_task.remote.complete"
12753
+ ) {
12754
yield* mapDispatchError(command)(offerDelegatedCompletionDeliveries(command.parentThreadId));
12755
}
12756
apps/server/src/orchestration-v2/ProjectionStore.test.ts
+51
@@ -964,6 +964,56 @@ const runlessNativeSubagentNeedsRecovery = Effect.gen(function* () {
964
}
965
});
966
967
+const subagentRecordsSelectById = Effect.gen(function* () {
968
+ const store = yield* ProjectionStore.ProjectionStoreV2;
969
+ const threadId = yield* addRolledBackRecoveryCandidate("subagent-records-by-id");
970
+ const now = yield* DateTime.now;
971
+ const ids = [NodeId.make("node:subagent-by-id:a"), NodeId.make("node:subagent-by-id:b")];
972
+ for (const id of ids) {
973
+ yield* store.apply({
974
+ id: EventId.make(`event:${id}`),
975
+ type: "subagent.updated",
976
+ threadId,
977
+ nodeId: id,
978
+ driver,
979
+ providerInstanceId,
980
+ occurredAt: now,
981
+ payload: {
982
+ id,
983
+ threadId,
984
+ runId: null,
985
+ parentNodeId: NodeId.make("node:subagent-by-id:parent"),
986
+ origin: "app_owned",
987
+ createdBy: "agent",
988
+ driver,
989
+ providerInstanceId,
990
+ providerThreadId: null,
991
+ childThreadId: null,
992
+ nativeTaskRef: null,
993
+ prompt: "Do the work",
994
+ title: "Delegated task",
995
+ model: null,
996
+ status: "running",
997
+ result: null,
998
+ startedAt: now,
999
+ completedAt: null,
1000
+ updatedAt: now,
1001
+ },
1002
+ });
1003
+ }
1004
+ const read = (subagentIds?: ReadonlyArray<NodeId>) =>
1005
+ store
1006
+ .getThreadRecords(threadId, ["subagents"], subagentIds === undefined ? {} : { subagentIds })
1007
+ .pipe(Effect.map(({ subagents }) => subagents.map((task) => task.id)));
1008
+ assert.deepEqual(yield* read(), ids);
1009
+ assert.deepEqual(yield* read([ids[1]!]), [ids[1]]);
1010
+ assert.deepEqual(yield* read([]), []);
1011
+});
1012
+
1013
+it.effect("memory record reads select subagents by id", () =>
1014
+ subagentRecordsSelectById.pipe(Effect.provide(ProjectionStore.layerMemory)),
1015
+);
1016
+
1017
const assertProjectScopedShells = Effect.fn("assertProjectScopedShells")(function* (
1018
suffix: string,
1019
) {
@@ -1392,6 +1442,7 @@ it.layer(layerTest)("ProjectionStoreV2", (it) => {
1442
assert.deepEqual(recovery?.restartCancelledBackgroundWork, work);
1443
}),
1444
);
1445
+ it.effect("record reads select subagents by id", () => subagentRecordsSelectById);
1446
it.effect(
1447
"command reads skip finished leaf nodes of finished runs",
1448
() => commandReadsSkipSettledLeafNodes,
apps/server/src/orchestration-v2/ProjectionStore.ts
+51
-1
@@ -333,6 +333,7 @@ export interface ProjectionRecordFilter {
333
readonly messageRunIds?: ReadonlyArray<RunId>;
334
readonly turnItemRunIds?: ReadonlyArray<RunId | null>;
335
readonly runIds?: ReadonlyArray<RunId>;
336
+ readonly subagentIds?: ReadonlyArray<NodeId>;
337
readonly turnItemTypes?: ReadonlyArray<OrchestrationV2TurnItem["type"]>;
338
readonly turnItemStatuses?: ReadonlyArray<OrchestrationV2TurnItem["status"]>;
339
readonly omitSettledLeafNodes?: boolean;
@@ -518,6 +519,15 @@ export interface ProjectionStoreV2Shape {
519
ReadonlyArray<{ readonly threadId: ThreadId; readonly worktreePath: string }>,
520
ProjectionStoreV2Error
521
>;
522
+ /**
523
+ * Delegated tasks in a linked environment with work left for this one: no
524
+ * result yet, or cancelled or stopped here without that stop reaching there,
525
+ * including a Stop after the task had its result.
526
+ */
527
+ readonly getOpenRemoteDelegatedTasks: Effect.Effect<
528
+ ReadonlyArray<{ readonly parentThreadId: ThreadId; readonly taskId: NodeId }>,
529
+ ProjectionStoreV2Error
530
+ >;
531
readonly getTurnStartContext: (
532
threadId: ThreadId,
533
runId: RunId,
@@ -1660,6 +1670,9 @@ export function threadShellFromProjection(
1670
...(projection.thread.linkOrigin === undefined
1671
? {}
1672
: { linkOrigin: projection.thread.linkOrigin }),
1673
+ ...(projection.thread.delegatedFrom === undefined
1674
+ ? {}
1675
+ : { delegatedFrom: projection.thread.delegatedFrom }),
1676
latestRunId: latestRun?.id ?? null,
1677
latestRunRequestedAt: latestRun?.requestedAt ?? null,
1678
latestRunStartedAt: latestRun?.startedAt ?? null,
@@ -1939,6 +1952,9 @@ function shellFromState(input: {
1952
...(input.state.thread.linkOrigin === undefined
1953
? {}
1954
: { linkOrigin: input.state.thread.linkOrigin }),
1955
+ ...(input.state.thread.delegatedFrom === undefined
1956
+ ? {}
1957
+ : { delegatedFrom: input.state.thread.delegatedFrom }),
1958
latestRunId: input.state.latestRunId,
1959
latestRunRequestedAt: input.state.latestRunRequestedAt,
1960
latestRunStartedAt: input.state.latestRunStartedAt,
@@ -3350,13 +3366,15 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
3366
rows.toSorted((left, right) => left.position - right.position),
3367
),
3368
),
3353
- fields !== undefined && !fields.includes("subagents")
3369
+ (fields !== undefined && !fields.includes("subagents")) ||
3370
+ (window === undefined && matchesNothing(filter?.subagentIds))
3371
? Effect.succeed([])
3372
: window === undefined
3373
? sql<PayloadRow>`
3374
SELECT payload_json
3375
FROM orchestration_v2_projection_subagents
3376
WHERE thread_id = ${threadId}
3377
+ ${filter?.subagentIds === undefined ? sql`` : sql`AND subagent_id IN (SELECT value FROM json_each(${encodeIdList(filter.subagentIds)}))`}
3378
ORDER BY COALESCE(started_at, ''), subagent_id ASC
3379
`
3380
: sql<PayloadRow>`
@@ -6268,6 +6286,32 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
6286
)
6287
.pipe(Effect.mapError((cause) => new ProjectionStoreSetupError({ cause })));
6288
6289
+ const getOpenRemoteDelegatedTasks: ProjectionStoreV2Shape["getOpenRemoteDelegatedTasks"] = sql<{
6290
+ readonly thread_id: string;
6291
+ readonly subagent_id: string;
6292
+ }>`
6293
+ SELECT thread_id, subagent_id FROM orchestration_v2_projection_subagents
6294
+ WHERE origin = 'app_owned'
6295
+ AND child_thread_id IS NULL
6296
+ AND json_type(payload_json, '$.remoteChild') = 'object'
6297
+ AND (
6298
+ json_type(payload_json, '$.result') = 'null'
6299
+ OR (
6300
+ json_extract(payload_json, '$.status') IN ('cancelled', 'interrupted')
6301
+ AND json_type(payload_json, '$.remoteChild.stoppedThere') IS NOT 'true'
6302
+ )
6303
+ OR json_type(payload_json, '$.remoteChild.stoppedThere') = 'false'
6304
+ )
6305
+ `.pipe(
6306
+ Effect.map((rows) =>
6307
+ rows.map((row) => ({
6308
+ parentThreadId: ThreadId.make(row.thread_id),
6309
+ taskId: NodeId.make(row.subagent_id),
6310
+ })),
6311
+ ),
6312
+ Effect.mapError((cause) => new ProjectionStoreSetupError({ cause })),
6313
+ );
6314
+
6315
const getThreadsWithPullRequests: ProjectionStoreV2Shape["getThreadsWithPullRequests"] =
6316
Effect.fn("ProjectionStore.getThreadsWithPullRequests")(
6317
function* (threadId) {
@@ -6787,6 +6831,7 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
6831
getSettlementCandidates: readOnReader(getSettlementCandidates),
6832
getThreadsWithPullRequests: readOnReader(getThreadsWithPullRequests),
6833
getThreadWorktreePaths: readOnReader(getThreadWorktreePaths),
6834
+ getOpenRemoteDelegatedTasks: getOpenRemoteDelegatedTasks.pipe(NodeSqliteClient.readOnly),
6835
getThreadProjection,
6836
getTurnStartContext: readOnReader(getTurnStartContext),
6837
getTurnStartHistory: readOnReader(getTurnStartHistory),
@@ -7039,6 +7084,7 @@ export const layerMemory: Layer.Layer<ProjectionStoreV2> = Layer.effect(
7084
),
7085
),
7086
),
7087
+ getOpenRemoteDelegatedTasks: Effect.succeed([]),
7088
getThreadsWithPullRequests: (threadId) =>
7089
Ref.get(replayState).pipe(
7090
Effect.map((state) =>
@@ -7235,6 +7281,10 @@ export const layerMemory: Layer.Layer<ProjectionStoreV2> = Layer.effect(
7281
filter?.runIds === undefined
7282
? projection.runs
7283
: projection.runs.filter((row) => filter.runIds!.includes(row.id)),
7284
+ subagents:
7285
+ filter?.subagentIds === undefined
7286
+ ? projection.subagents
7287
+ : projection.subagents.filter((row) => filter.subagentIds!.includes(row.id)),
7288
turnItems: projection.turnItems.filter(
7289
(row) =>
7290
(filter?.turnItemRunIds === undefined ||
apps/server/src/orchestration-v2/ProviderRuntimeRecoveryService.ts
+9
-1
@@ -100,11 +100,19 @@ function isNonterminalNodeStatus(status: string): boolean {
100
return status === "pending" || status === "running" || status === "waiting";
101
}
102
103
+/**
104
+ * A delegate_task child. Its own thread is reconciled and continued on its own
105
+ * (here, or in the linked environment it runs in) and reports back through
106
+ * the app, so it is not provider background work.
107
+ */
108
function isAppOwnedDelegation(task: {
109
readonly origin: OrchestrationV2Subagent["origin"];
110
readonly childThreadId: ThreadId | null;
111
+ readonly remoteChild?: OrchestrationV2Subagent["remoteChild"];
112
}): boolean {
107
- return task.origin === "app_owned" && task.childThreadId !== null;
113
+ return (
114
+ task.origin === "app_owned" && (task.childThreadId !== null || task.remoteChild !== undefined)
115
+ );
116
}
117
118
function isAppOwnedDelegationItem(
apps/server/src/orchestration-v2/ProviderTurnControlService.test.ts
+1
@@ -210,6 +210,7 @@ it.effect(
210
ProjectionStore.ProjectionStoreV2.of({
211
apply: () => Effect.void,
212
getLimitRecoveryCandidates: () => Effect.die("unused getLimitRecoveryCandidates"),
213
+ getOpenRemoteDelegatedTasks: Effect.die("unused getOpenRemoteDelegatedTasks"),
214
getShellSnapshot: () => Effect.die("unused getShellSnapshot"),
215
listActiveSubagentThreadIds: () => Effect.die("unused listActiveSubagentThreadIds"),
216
listOlderSettledThreads: () => Effect.die("unused listOlderSettledThreads"),
apps/server/src/orchestration-v2/RemoteDelegatedTask.test.ts
new
+411
@@ -0,0 +1,411 @@
1
+import { assert, it } from "@effect/vitest";
2
+import {
3
+ CommandId,
4
+ EnvironmentId,
5
+ EventId,
6
+ MessageId,
7
+ NodeId,
8
+ ProjectId,
9
+ ProviderDriverKind,
10
+ ProviderInstanceId,
11
+ ProviderThreadId,
12
+ RunId,
13
+ ThreadId,
14
+} from "@t3tools/contracts";
15
+import * as Context from "effect/Context";
16
+import * as DateTime from "effect/DateTime";
17
+import * as Effect from "effect/Effect";
18
+import * as Layer from "effect/Layer";
19
+import * as Ref from "effect/Ref";
20
+
21
+import { CodexProviderCapabilitiesV2 } from "./Adapters/CodexAdapterV2.ts";
22
+import * as EventSink from "./EventSink.ts";
23
+import * as Orchestrator from "./Orchestrator.ts";
24
+import type * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
25
+import * as ProjectionStore from "./ProjectionStore.ts";
26
+import * as ProviderAdapterRegistry from "./ProviderAdapterRegistry.ts";
27
+import * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
28
+import * as ProviderReplayHarness from "./testkit/ProviderReplayHarness.ts";
29
+import * as SqlitePersistence from "../persistence/Sqlite.ts";
30
+
31
+// A delegated task whose child runs in a linked environment is recorded on
32
+// its parent without a child thread here, and completing it wakes the parent
33
+// the way a local child's result does.
34
+
35
+const instanceId = ProviderInstanceId.make("codex");
36
+const driver = ProviderDriverKind.make("codex");
37
+const modelSelection = { instanceId, model: "gpt-5.4" };
38
+const adapter = {
39
+ instanceId,
40
+ driver,
41
+ getCapabilities: () => Effect.succeed(CodexProviderCapabilitiesV2),
42
+ planSelectionTransition: () => Effect.succeed({ type: "apply_on_next_turn" as const }),
43
+ openSession: () => Effect.die("No provider process needed for delegated task records"),
44
+} as ProviderAdapter.ProviderAdapterV2["Service"];
45
+
46
+/** Every parent wake the orchestrator offers, for the tests to read. */
47
+class Offers extends Context.Service<
48
+ Offers,
49
+ Ref.Ref<ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>>
50
+>()("t3/orchestration-v2/RemoteDelegatedTask.test/Offers") {}
51
+const layerOffers = Layer.effect(
52
+ Offers,
53
+ Ref.make<ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>>([]),
54
+);
55
+const layerDatabase = SqlitePersistence.layerMemory;
56
+const layerTest = Layer.mergeAll(
57
+ layerDatabase,
58
+ ProjectionStore.layer.pipe(Layer.provide(layerDatabase)),
59
+ ProviderReplayHarness.layerWithRegistry(
60
+ { name: "remote-delegated-task" },
61
+ ProviderAdapterRegistry.layerFromAdapters([adapter]),
62
+ { databaseLayer: layerDatabase, runEffectWorker: false },
63
+ ),
64
+).pipe(
65
+ Layer.provide(
66
+ Layer.effect(
67
+ ProviderContinuationRequests.ProviderContinuationRequests,
68
+ Offers.pipe(
69
+ Effect.map((offers) => ({
70
+ offer: (request: ProviderContinuationRequests.ProviderContinuationRequest) =>
71
+ Ref.update(offers, (seen) => [...seen, request]),
72
+ take: Effect.never,
73
+ })),
74
+ ),
75
+ ),
76
+ ),
77
+ Layer.provideMerge(layerOffers),
78
+);
79
+
80
+/** A parent thread whose run is live, as when its agent calls delegate_task. */
81
+const seedLiveParent = (name: string) =>
82
+ Effect.gen(function* () {
83
+ const orchestrator = yield* Orchestrator.OrchestratorV2;
84
+ const sink = yield* EventSink.EventSinkV2;
85
+ const now = yield* DateTime.now;
86
+ const threadId = ThreadId.make(`thread:${name}`);
87
+ const runId = RunId.make(`run:${name}`);
88
+ const rootNodeId = NodeId.make(`node:${name}:root`);
89
+ const providerThreadId = ProviderThreadId.make(`provider-thread:${name}`);
90
+ yield* orchestrator.dispatch({
91
+ type: "thread.create",
92
+ createdBy: "user",
93
+ creationSource: "web",
94
+ commandId: CommandId.make(`command:create:${name}`),
95
+ threadId,
96
+ projectId: ProjectId.make("project:remote-delegated-task"),
97
+ title: "Parent",
98
+ modelSelection,
99
+ runtimeMode: "full-access",
100
+ interactionMode: "default",
101
+ branch: null,
102
+ worktreePath: null,
103
+ });
104
+ yield* sink.write({
105
+ commandId: CommandId.make(`command:seed:${name}`),
106
+ events: [
107
+ {
108
+ id: EventId.make(`event:seed-provider-thread:${name}`),
109
+ type: "provider-thread.updated",
110
+ threadId,
111
+ driver,
112
+ providerInstanceId: instanceId,
113
+ occurredAt: now,
114
+ payload: {
115
+ id: providerThreadId,
116
+ driver,
117
+ providerInstanceId: instanceId,
118
+ providerSessionId: null,
119
+ appThreadId: threadId,
120
+ ownerNodeId: rootNodeId,
121
+ nativeThreadRef: { driver, nativeId: `native:${name}`, strength: "strong" },
122
+ nativeConversationHeadRef: null,
123
+ status: "active",
124
+ firstRunOrdinal: 1,
125
+ lastRunOrdinal: 1,
126
+ handoffIds: [],
127
+ forkedFrom: null,
128
+ createdAt: now,
129
+ updatedAt: now,
130
+ },
131
+ },
132
+ {
133
+ id: EventId.make(`event:seed-node:${name}`),
134
+ type: "node.updated",
135
+ threadId,
136
+ runId,
137
+ nodeId: rootNodeId,
138
+ driver,
139
+ providerInstanceId: instanceId,
140
+ occurredAt: now,
141
+ payload: {
142
+ id: rootNodeId,
143
+ threadId,
144
+ runId,
145
+ parentNodeId: null,
146
+ rootNodeId,
147
+ kind: "root_turn",
148
+ status: "running",
149
+ countsForRun: true,
150
+ providerThreadId,
151
+ providerTurnId: null,
152
+ nativeItemRef: null,
153
+ runtimeRequestId: null,
154
+ checkpointScopeId: null,
155
+ startedAt: now,
156
+ completedAt: null,
157
+ },
158
+ },
159
+ {
160
+ id: EventId.make(`event:seed-run:${name}`),
161
+ type: "run.updated",
162
+ threadId,
163
+ runId,
164
+ nodeId: rootNodeId,
165
+ providerInstanceId: instanceId,
166
+ occurredAt: now,
167
+ payload: {
168
+ id: runId,
169
+ threadId,
170
+ ordinal: 1,
171
+ providerInstanceId: instanceId,
172
+ modelSelection,
173
+ providerThreadId,
174
+ userMessageId: MessageId.make(`message:seed-user:${name}`),
175
+ rootNodeId,
176
+ activeAttemptId: null,
177
+ status: "running",
178
+ requestedAt: now,
179
+ startedAt: now,
180
+ completedAt: null,
181
+ checkpointId: null,
182
+ contextHandoffId: null,
183
+ },
184
+ },
185
+ ],
186
+ });
187
+ return { threadId, runId, rootNodeId };
188
+ });
189
+
190
+const remoteChild = {
191
+ environmentId: EnvironmentId.make("environment:box"),
192
+ threadId: ThreadId.make("thread:on-the-box"),
193
+ label: "Box",
194
+};
195
+
196
+it.layer(layerTest)("a delegated task in a linked environment", (it) => {
197
+ it.effect("is recorded on its parent without a child thread here, once", () =>
198
+ Effect.gen(function* () {
199
+ const orchestrator = yield* Orchestrator.OrchestratorV2;
200
+ const parent = yield* seedLiveParent("records");
201
+ const request = {
202
+ type: "delegated_task.remote.request" as const,
203
+ commandId: CommandId.make("command:remote-delegate:records"),
204
+ parentThreadId: parent.threadId,
205
+ parentRunId: parent.runId,
206
+ parentNodeId: parent.rootNodeId,
207
+ task: "Run the suite there.",
208
+ driver: ProviderDriverKind.make("remote"),
209
+ modelSelection,
210
+ remoteChild,
211
+ completionWake: "always" as const,
212
+ };
213
+ yield* orchestrator.dispatch(request);
214
+ yield* orchestrator.dispatch(request);
215
+ const projection = yield* orchestrator.getThreadProjection(parent.threadId);
216
+ assert.equal(projection.subagents.length, 1);
217
+ const [task] = projection.subagents;
218
+ assert.equal(task?.childThreadId, null);
219
+ assert.deepEqual(task?.remoteChild, remoteChild);
220
+ assert.equal(task?.status, "running");
221
+ const item = projection.turnItems.find((candidate) => candidate.type === "subagent");
222
+ assert.deepEqual(item?.type === "subagent" ? item.remoteChild : undefined, remoteChild);
223
+ // No thread was created here for the child.
224
+ assert.equal(yield* orchestrator.getThreadShell(remoteChild.threadId), null);
225
+ }),
226
+ );
227
+
228
+ it.effect("keeps a newer stop recoverable after an older acknowledgement", () =>
229
+ Effect.gen(function* () {
230
+ const orchestrator = yield* Orchestrator.OrchestratorV2;
231
+ const projections = yield* ProjectionStore.ProjectionStoreV2;
232
+ const parent = yield* seedLiveParent("stop-generation");
233
+ yield* orchestrator.dispatch({
234
+ type: "delegated_task.remote.request",
235
+ commandId: CommandId.make("command:remote-delegate:stop-generation"),
236
+ parentThreadId: parent.threadId,
237
+ parentRunId: parent.runId,
238
+ parentNodeId: parent.rootNodeId,
239
+ task: "Run a check.",
240
+ driver: ProviderDriverKind.make("remote"),
241
+ modelSelection,
242
+ remoteChild,
243
+ });
244
+ const task = (yield* orchestrator.getThreadProjection(parent.threadId)).subagents[0]!;
245
+ const openFor = projections.getOpenRemoteDelegatedTasks.pipe(
246
+ Effect.map((open) => open.filter((entry) => entry.parentThreadId === parent.threadId)),
247
+ );
248
+ const complete = {
249
+ type: "delegated_task.remote.complete" as const,
250
+ parentThreadId: parent.threadId,
251
+ taskId: task.id,
252
+ status: "completed" as const,
253
+ result: "Original result.",
254
+ };
255
+ yield* orchestrator.dispatch({
256
+ ...complete,
257
+ commandId: CommandId.make("command:result:stop-generation"),
258
+ stoppedThere: "ran-out",
259
+ });
260
+ for (const count of [1, 2]) {
261
+ yield* orchestrator.dispatch({
262
+ type: "delegated_task.remote.stop",
263
+ parentThreadId: parent.threadId,
264
+ taskId: task.id,
265
+ commandId: CommandId.make(`command:stop-generation:${count}`),
266
+ });
267
+ }
268
+ // Reports from before generation tracking cannot clear a later numbered Stop either.
269
+ for (const stopCount of [undefined, 1]) {
270
+ const rejected = yield* orchestrator
271
+ .dispatch({
272
+ ...complete,
273
+ commandId: CommandId.make(`command:stale-stop:${stopCount}`),
274
+ stoppedThere: "stopped",
275
+ ...(stopCount === undefined ? {} : { stopCount }),
276
+ })
277
+ .pipe(Effect.flip);
278
+ assert.equal(rejected._tag, "OrchestratorDispatchError");
279
+ assert.deepEqual(yield* openFor, [{ parentThreadId: parent.threadId, taskId: task.id }]);
280
+ }
281
+ yield* orchestrator.dispatch({
282
+ ...complete,
283
+ commandId: CommandId.make("command:current-stop:2"),
284
+ stoppedThere: "stopped",
285
+ stopCount: 2,
286
+ });
287
+ const settled = (yield* orchestrator.getThreadProjection(parent.threadId)).subagents[0]!;
288
+ assert.equal(settled.result, "Original result.");
289
+ assert.equal(settled.status, "completed");
290
+ assert.equal(settled.remoteChild?.stoppedThere, true);
291
+ assert.deepEqual(yield* openFor, []);
292
+ }),
293
+ );
294
+
295
+ it.effect("owes a stop there for a Stop here that loses the race to its result", () =>
296
+ Effect.gen(function* () {
297
+ const orchestrator = yield* Orchestrator.OrchestratorV2;
298
+ const projections = yield* ProjectionStore.ProjectionStoreV2;
299
+ const parent = yield* seedLiveParent("stop-after-result");
300
+ yield* orchestrator.dispatch({
301
+ type: "delegated_task.remote.request",
302
+ commandId: CommandId.make("command:remote-delegate:stop-after-result"),
303
+ parentThreadId: parent.threadId,
304
+ parentRunId: parent.runId,
305
+ parentNodeId: parent.rootNodeId,
306
+ task: "Run a check.",
307
+ driver: ProviderDriverKind.make("remote"),
308
+ modelSelection,
309
+ remoteChild,
310
+ });
311
+ const task = (yield* orchestrator.getThreadProjection(parent.threadId)).subagents[0]!;
312
+ const complete = {
313
+ type: "delegated_task.remote.complete" as const,
314
+ parentThreadId: parent.threadId,
315
+ taskId: task.id,
316
+ };
317
+ yield* orchestrator.dispatch({
318
+ ...complete,
319
+ commandId: CommandId.make("command:result:stop-after-result"),
320
+ status: "completed",
321
+ result: "Done there.",
322
+ stoppedThere: "ran-out",
323
+ });
324
+ // The parent's Stop read the task before its result landed.
325
+ yield* orchestrator.dispatch({
326
+ ...complete,
327
+ commandId: CommandId.make("command:parent-stop:stop-after-result"),
328
+ status: "interrupted",
329
+ result: "Stopped with its parent.",
330
+ });
331
+
332
+ const stopped = (yield* orchestrator.getThreadProjection(parent.threadId)).subagents[0]!;
333
+ assert.equal(stopped.status, "completed");
334
+ assert.equal(stopped.result, "Done there.");
335
+ assert.equal(stopped.remoteChild?.stoppedThere, false);
336
+ assert.equal(stopped.remoteChild?.stopCount, 1);
337
+ const open = yield* projections.getOpenRemoteDelegatedTasks;
338
+ assert.deepEqual(
339
+ open.filter((entry) => entry.parentThreadId === parent.threadId),
340
+ [{ parentThreadId: parent.threadId, taskId: task.id }],
341
+ );
342
+ }),
343
+ );
344
+
345
+ it.effect("wakes its parent with the result when it completes there", () =>
346
+ Effect.gen(function* () {
347
+ const orchestrator = yield* Orchestrator.OrchestratorV2;
348
+ const parent = yield* seedLiveParent("completes");
349
+ const recorded = yield* orchestrator.dispatch({
350
+ type: "delegated_task.remote.request",
351
+ commandId: CommandId.make("command:remote-delegate:completes"),
352
+ parentThreadId: parent.threadId,
353
+ parentRunId: parent.runId,
354
+ parentNodeId: parent.rootNodeId,
355
+ task: "Run the suite there.",
356
+ driver: ProviderDriverKind.make("remote"),
357
+ modelSelection,
358
+ remoteChild,
359
+ completionWake: "always",
360
+ });
361
+ const taskEvent = recorded.storedEvents.find(
362
+ (stored) => stored.event.type === "subagent.updated",
363
+ );
364
+ const taskId =
365
+ taskEvent?.event.type === "subagent.updated" ? taskEvent.event.payload.id : undefined;
366
+ assert.isDefined(taskId);
367
+ // Until it completes, it is open, and a restarted follower picks it up.
368
+ const projections = yield* ProjectionStore.ProjectionStoreV2;
369
+ const openFor = projections.getOpenRemoteDelegatedTasks.pipe(
370
+ Effect.map((open) => open.filter((task) => task.parentThreadId === parent.threadId)),
371
+ );
372
+ assert.deepEqual(yield* openFor, [{ parentThreadId: parent.threadId, taskId: taskId! }]);
373
+ const offers = yield* Offers;
374
+ yield* Ref.set(offers, []);
375
+ const complete = (result: string) =>
376
+ orchestrator.dispatch({
377
+ type: "delegated_task.remote.complete",
378
+ commandId: CommandId.make(`command:remote-complete:${result}`),
379
+ parentThreadId: parent.threadId,
380
+ taskId: taskId!,
381
+ status: "completed",
382
+ result,
383
+ stoppedThere: "ran-out",
384
+ });
385
+ yield* complete("All 412 tests pass on the box.");
386
+ // A second report is refused, so the first result stands.
387
+ const late = yield* complete("A late, different answer.").pipe(Effect.flip);
388
+ assert.equal(late._tag, "OrchestratorDispatchError");
389
+
390
+ const projection = yield* orchestrator.getThreadProjection(parent.threadId);
391
+ const task = projection.subagents.find((candidate) => candidate.id === taskId);
392
+ assert.equal(task?.status, "completed");
393
+ assert.equal(task?.result, "All 412 tests pass on the box.");
394
+ // The live parent run claimed it, so task_status acknowledges it as for a local child.
395
+ assert.equal(task?.completionDelivery?.state, "claimed");
396
+ // Nothing is left for the follower to pick up after a restart.
397
+ assert.deepEqual(yield* openFor, []);
398
+ const item = projection.turnItems.find(
399
+ (candidate) => candidate.type === "subagent" && candidate.subagentId === taskId,
400
+ );
401
+ assert.equal(item?.status, "completed");
402
+ // The parent's live run is offered the delivery, as for a local child.
403
+ const delivery = projection.runs.find((run) => run.id === parent.runId)?.delegatedCompletion
404
+ ?.delivery;
405
+ assert.deepEqual(delivery?.taskIds, [taskId]);
406
+ const offered = yield* Ref.get(offers);
407
+ assert.equal(offered.length, 1);
408
+ assert.equal(offered[0]?.threadId, parent.threadId);
409
+ }),
410
+ );
411
+});
apps/server/src/orchestration-v2/ThreadLaunchService.test.ts
+3
@@ -63,6 +63,7 @@ import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
63
import * as ThreadManagement from "./ThreadManagementService.ts";
64
import * as ThreadTitleRegeneration from "./ThreadTitleRegenerationService.ts";
65
import * as ProviderReplayHarness from "./testkit/ProviderReplayHarness.ts";
66
+import * as RemoteDelegation from "../peer/RemoteDelegation.ts";
67
import type * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
68
69
const projectId = ProjectId.make("project:launch-test");
@@ -179,6 +180,7 @@ function makeHarness(options: HarnessOptions = {}) {
180
bootstrap: () => Effect.die("unused"),
181
update: () => Effect.die("unused"),
182
delete: () => Effect.die("unused"),
183
+ listPage: () => Effect.die("unused"),
184
getById: (id) =>
185
Effect.succeed(
186
id === projectId
@@ -321,6 +323,7 @@ it.effect.each(
323
NodeCrypto.layer,
324
Scheduler.layer,
325
Layer.mock(SecretRequests.SecretRequests)({}),
326
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
327
),
328
),
329
);
apps/server/src/orchestration-v2/ThreadLaunchService.ts
+6
@@ -9,6 +9,7 @@ import {
9
type ModelSelection,
10
type OrchestrationV2Actor,
11
type OrchestrationV2CreationSource,
12
+ type OrchestrationV2DelegatedFrom,
13
type OrchestrationV2LinkOrigin,
14
type OrchestrationV2ProviderThreadNativeMetadata,
15
type OrchestrationV2ThreadProjection,
@@ -100,6 +101,8 @@ export interface ThreadLaunchInput {
101
readonly creationSource: OrchestrationV2CreationSource;
102
/** The linked environment this launch is for, if one asked for it. */
103
readonly linkOrigin?: OrchestrationV2LinkOrigin;
104
+ /** The parent there, when that environment's agent delegated this as a task. */
105
+ readonly delegatedFrom?: OrchestrationV2DelegatedFrom;
106
}
107
108
type PreparationInput = Pick<
@@ -916,6 +919,9 @@ const make = Effect.gen(function* () {
919
? {}
920
: { importedNativeThread: input.importedNativeThread }),
921
...(input.linkOrigin === undefined ? {} : { linkOrigin: input.linkOrigin }),
922
+ ...(input.delegatedFrom === undefined
923
+ ? {}
924
+ : { delegatedFrom: input.delegatedFrom }),
925
createdBy: input.createdBy,
926
creationSource: input.creationSource,
927
});
apps/server/src/orchestration-v2/ThreadManagementService.test.ts
+155
-1
@@ -1,6 +1,7 @@
1
import { expect, it } from "@effect/vitest";
2
import {
3
CommandId,
4
+ EnvironmentId,
5
MessageId,
6
type OrchestrationV2Command,
7
type OrchestrationV2Run,
@@ -17,12 +18,14 @@ import {
18
} from "@t3tools/contracts";
19
import * as Deferred from "effect/Deferred";
20
import * as DateTime from "effect/DateTime";
21
+import * as Duration from "effect/Duration";
22
import * as Option from "effect/Option";
23
import * as Effect from "effect/Effect";
24
import * as Fiber from "effect/Fiber";
25
import * as Layer from "effect/Layer";
26
import * as Queue from "effect/Queue";
27
import * as Stream from "effect/Stream";
28
+import * as TestClock from "effect/testing/TestClock";
29
30
import * as ServerSettings from "../serverSettings.ts";
31
import * as SqlitePersistence from "../persistence/Sqlite.ts";
@@ -50,8 +53,13 @@ it("stamps authoritative provenance on commands that create threads or messages"
53
interactionMode: "default",
54
branch: null,
55
worktreePath: null,
53
- // A client cannot claim a linked environment's origin for its own thread.
56
+ // A client cannot claim a linked environment's origin, or a parent there.
57
linkOrigin: { sessionId: "forged", label: "Somewhere else" },
58
+ delegatedFrom: {
59
+ environmentId: EnvironmentId.make("environment:elsewhere"),
60
+ threadId: ThreadId.make("thread:elsewhere"),
61
+ title: "Somewhere else",
62
+ },
63
};
64
65
const stamped = ThreadManagementService.withCreationProvenance(command, {
@@ -63,6 +71,7 @@ it("stamps authoritative provenance on commands that create threads or messages"
71
creationSource: "web",
72
});
73
expect(stamped).not.toHaveProperty("linkOrigin");
74
+ expect(stamped).not.toHaveProperty("delegatedFrom");
75
});
76
77
const layerReceiptsTest = CommandReceiptStore.layer.pipe(
@@ -290,6 +299,151 @@ it.effect("waitForThread follows a restart continuation instead of the cut run",
299
}),
300
);
301
302
+it.effect("waitForThread can wait past an ended run for the thread's delegated work", () =>
303
+ Effect.gen(function* () {
304
+ const projectId = ProjectId.make("project:thread-management:wait-delegated");
305
+ const threadId = ThreadId.make("thread:thread-management:wait-delegated");
306
+ const runId = RunId.make("run:thread-management:wait-delegated");
307
+ const wakeRunId = RunId.make("run:thread-management:wait-delegated:wake");
308
+ const subscribed = yield* Deferred.make<void>();
309
+ const events = yield* Queue.unbounded<OrchestrationV2StoredEvent>();
310
+ const at = (seconds: number) => DateTime.makeUnsafe(seconds * 1_000);
311
+ const run = (id: RunId, ordinal: number, status: OrchestrationV2Run["status"], end: number) =>
312
+ ({
313
+ id,
314
+ ordinal,
315
+ status,
316
+ startedAt: at(end - 1),
317
+ completedAt: status === "running" ? null : at(end),
318
+ }) as unknown as OrchestrationV2Run;
319
+ // The run ended, but a task it delegated still runs and will wake the thread.
320
+ let runs = [run(runId, 1, "completed", 1)];
321
+ let subagents = [{ status: "running" }];
322
+ const stored = (sequence: number, event: object) =>
323
+ ({ sequence, event: { threadId, ...event } }) as unknown as OrchestrationV2StoredEvent;
324
+ const layerTest = ThreadManagementService.layer.pipe(
325
+ Layer.provide(Layer.mock(ProviderSessionManager.ProviderSessionManagerV2)({})),
326
+ Layer.provide(
327
+ Layer.mock(Orchestrator.OrchestratorV2)({
328
+ getThreadEventSequence: () => Effect.succeed(0),
329
+ restartContinuationPending: () => Effect.succeed(false),
330
+ delegatedTaskResultPending: () => Effect.succeed(false),
331
+ streamStoredEventsFrom: (input) =>
332
+ input?.eventType === "subagent.updated"
333
+ ? Stream.fromEffect(Deferred.succeed(subscribed, undefined)).pipe(
334
+ Stream.drain,
335
+ Stream.concat(Stream.fromQueue(events)),
336
+ )
337
+ : Stream.never,
338
+ getThreadRecords: () =>
339
+ Effect.sync(
340
+ () =>
341
+ ({
342
+ thread: { id: threadId, projectId, deletedAt: null },
343
+ runs,
344
+ messages: [],
345
+ subagents,
346
+ providerThreads: [],
347
+ }) as unknown as OrchestrationV2ThreadProjection,
348
+ ),
349
+ }),
350
+ ),
351
+ Layer.provide(ServerSettings.layerTest()),
352
+ Layer.provide(layerReceiptsTest),
353
+ );
354
+ const service = yield* ThreadManagementService.ThreadManagementService.pipe(
355
+ Effect.provide(layerTest),
356
+ );
357
+ // Without the option, the ended run is the answer, as before.
358
+ expect(
359
+ yield* service.waitForThread({ projectId, threadId, runId, timeoutMs: 60 * 60 * 1_000 }),
360
+ ).toMatchObject({ timedOut: false, run: { id: runId } });
361
+ expect(
362
+ yield* service.waitForThread({ projectId, threadId, runId, timeoutMs: 60 * 60 * 1_000 }),
363
+ ).not.toHaveProperty("resultRun");
364
+
365
+ const fiber = yield* service
366
+ .waitForThread({
367
+ projectId,
368
+ threadId,
369
+ runId,
370
+ timeoutMs: 60 * 60 * 1_000,
371
+ untilDelegatedWorkSettled: true,
372
+ })
373
+ .pipe(Effect.forkChild);
374
+ // A wait that returns early fails below instead of hanging here.
375
+ yield* Effect.raceFirst(Deferred.await(subscribed), Fiber.await(fiber));
376
+ // The task finishes; its delivery wakes the thread, whose next run answers.
377
+ subagents = [{ status: "completed" }];
378
+ runs = [...runs, run(wakeRunId, 2, "completed", 3)];
379
+ yield* Queue.offer(events, stored(1, { type: "subagent.updated", payload: {} }));
380
+ const result = yield* Fiber.join(fiber);
381
+
382
+ expect(result).toMatchObject({
383
+ timedOut: false,
384
+ run: { id: runId, status: "completed" },
385
+ resultRun: { id: wakeRunId, status: "completed" },
386
+ });
387
+ }),
388
+);
389
+
390
+it.effect("waitForThread settles delegated work on a thread rolled back past its only run", () =>
391
+ Effect.gen(function* () {
392
+ const projectId = ProjectId.make("project:thread-management:wait-rolled-back");
393
+ const threadId = ThreadId.make("thread:thread-management:wait-rolled-back");
394
+ const runId = RunId.make("run:thread-management:wait-rolled-back");
395
+ const rolledBack = {
396
+ id: runId,
397
+ ordinal: 1,
398
+ status: "rolled_back",
399
+ startedAt: DateTime.makeUnsafe(0),
400
+ completedAt: DateTime.makeUnsafe(1_000),
401
+ } as unknown as OrchestrationV2Run;
402
+ const layerTest = ThreadManagementService.layer.pipe(
403
+ Layer.provide(Layer.mock(ProviderSessionManager.ProviderSessionManagerV2)({})),
404
+ Layer.provide(
405
+ Layer.mock(Orchestrator.OrchestratorV2)({
406
+ getThreadEventSequence: () => Effect.succeed(0),
407
+ restartContinuationPending: () => Effect.succeed(false),
408
+ delegatedTaskResultPending: () => Effect.succeed(false),
409
+ streamStoredEventsFrom: () => Stream.never,
410
+ getThreadRecords: () =>
411
+ Effect.succeed({
412
+ thread: { id: threadId, projectId, deletedAt: null },
413
+ runs: [rolledBack],
414
+ messages: [],
415
+ subagents: [],
416
+ providerThreads: [],
417
+ } as unknown as OrchestrationV2ThreadProjection),
418
+ }),
419
+ ),
420
+ Layer.provide(ServerSettings.layerTest()),
421
+ Layer.provide(layerReceiptsTest),
422
+ );
423
+ const service = yield* ThreadManagementService.ThreadManagementService.pipe(
424
+ Effect.provide(layerTest),
425
+ );
426
+ const fiber = yield* service
427
+ .waitForThread({
428
+ projectId,
429
+ threadId,
430
+ runId,
431
+ timeoutMs: 60_000,
432
+ untilDelegatedWorkSettled: true,
433
+ })
434
+ .pipe(Effect.forkChild);
435
+ // Nothing will ever run there again, so a wait still open runs out here.
436
+ yield* TestClock.adjust(Duration.millis(60_000));
437
+ const result = yield* Fiber.join(fiber);
438
+
439
+ expect(result).toMatchObject({
440
+ timedOut: false,
441
+ run: { id: runId, status: "rolled_back" },
442
+ resultRun: { id: runId, status: "rolled_back" },
443
+ });
444
+ }),
445
+);
446
+
447
it.effect("waitForThread returns the cut run once its continuation is declined", () =>
448
Effect.gen(function* () {
449
const projectId = ProjectId.make("project:thread-management:wait-declined");
apps/server/src/orchestration-v2/ThreadManagementService.ts
+111
-23
@@ -36,6 +36,7 @@ import {
36
ThreadId,
37
type TurnItemId,
38
} from "@t3tools/contracts";
39
+import { delegatedTaskProgress } from "@t3tools/provider-core/server/subagentProjection";
40
import { threadTranscriptHeader } from "@t3tools/shared/threadTranscript";
41
import * as Context from "effect/Context";
42
import * as DateTime from "effect/DateTime";
@@ -72,7 +73,7 @@ export function withCreationProvenance(
73
switch (command.type) {
74
case "thread.create": {
75
// Only the server stamps a link's origin, so a client cannot set one.
75
- const { linkOrigin: _linkOrigin, ...rest } = command;
76
+ const { linkOrigin: _linkOrigin, delegatedFrom: _delegatedFrom, ...rest } = command;
77
return { ...rest, ...provenance };
78
}
79
case "message.dispatch":
@@ -108,6 +109,9 @@ function existingThreadIdsForCommand(
109
case "delegated_task.wake-policy":
110
case "delegated_task.completion-delivery.acknowledge":
111
case "delegated_task.completion-delivery.dispose":
112
+ case "delegated_task.remote.request":
113
+ case "delegated_task.remote.complete":
114
+ case "delegated_task.remote.stop":
115
return [command.parentThreadId];
116
case "thread.created.record":
117
return command.parentThreadId === command.targetThreadId
@@ -155,12 +159,20 @@ export interface ThreadManagementWaitInput {
159
readonly threadId: ThreadId;
160
readonly runId?: RunId;
161
readonly timeoutMs: number;
162
+ /**
163
+ * Also wait until the thread's own delegated work settles: an ended run
164
+ * still owes the thread's answer while a child, a background task or a
165
+ * completion delivery will wake it again, as a delegated task's result does.
166
+ */
167
+ readonly untilDelegatedWorkSettled?: boolean;
168
}
169
170
export interface ThreadManagementWaitResult {
171
readonly threadId: ThreadId;
172
readonly run: OrchestrationV2Run | null;
173
readonly timedOut: boolean;
174
+ /** With `untilDelegatedWorkSettled`, once settled: the run with the thread's final answer. */
175
+ readonly resultRun?: OrchestrationV2Run;
176
}
177
178
export interface ThreadManagementInterruptInput {
@@ -899,29 +911,73 @@ const make = Effect.gen(function* () {
911
isTerminalRunStatus(run.status) && (yield* orchestrator.restartContinuationPending(run));
912
return { run, pending, settled: isTerminalRunStatus(run.status) && !pending };
913
});
902
- const initial = yield* outcome(target.runs);
903
- if (initial.settled) {
904
- return { threadId: input.threadId, run: initial.run, timedOut: false };
905
- }
914
+ const untilDelegatedWorkSettled = input.untilDelegatedWorkSettled === true;
915
+ const delegatedWorkResult = Effect.gen(function* () {
916
+ const records = yield* getProjectThreadRecords(
917
+ input,
918
+ ["runs", "messages", "subagents", "providerThreads"],
919
+ { messageRoles: ["user"] },
920
+ );
921
+ const progress = delegatedTaskProgress(records);
922
+ // A thread rolled back past all its work, with nothing left running, has no answer to wait for.
923
+ if (
924
+ progress.resultRun === undefined &&
925
+ records.runs.every((run) => isTerminalRunStatus(run.status))
926
+ ) {
927
+ return latestRun(records);
928
+ }
929
+ if (progress.state !== "result_available") return undefined;
930
+ const pending = yield* orchestrator
931
+ .delegatedTaskResultPending(input.threadId)
932
+ .pipe(Effect.mapError(loadError));
933
+ return pending ? undefined : progress.resultRun;
934
+ });
935
+ const evaluate = Effect.fn("orchestrationV2.threadManagement.evaluate")(function* (
936
+ runs: ReadonlyArray<OrchestrationV2Run>,
937
+ ) {
938
+ const current = yield* outcome(runs);
939
+ if (!current.settled || !untilDelegatedWorkSettled) {
940
+ return { ...current, resultRun: undefined };
941
+ }
942
+ const resultRun = yield* delegatedWorkResult;
943
+ return { ...current, settled: resultRun !== undefined, resultRun };
944
+ });
945
+ const settledResult = (current: Effect.Success<ReturnType<typeof evaluate>>) => ({
946
+ threadId: input.threadId,
947
+ run: current.run,
948
+ timedOut: !current.settled,
949
+ ...(current.resultRun === undefined ? {} : { resultRun: current.resultRun }),
950
+ });
951
+ const initial = yield* evaluate(target.runs);
952
+ if (initial.settled) return settledResult(initial);
953
954
// A declined continuation records no event, so its effect settling wakes
955
// the wait too.
956
const wait = Stream.merge(
910
- Stream.merge(
911
- orchestrator.streamStoredEventsFrom({
912
- threadId: input.threadId,
913
- afterSequence,
914
- eventType: "run.updated",
915
- }),
916
- orchestrator.streamStoredEventsFrom({
917
- threadId: input.threadId,
918
- afterSequence,
919
- eventType: "thread.deleted",
920
- }),
957
+ Stream.mergeAll(
958
+ (
959
+ [
960
+ "run.updated",
961
+ "thread.deleted",
962
+ // What delegated work reads besides runs: tasks and their
963
+ // deliveries, and a provider thread's background tasks.
964
+ ...(untilDelegatedWorkSettled
965
+ ? (["subagent.updated", "provider-thread.updated"] as const)
966
+ : []),
967
+ ] as const
968
+ ).map((eventType) =>
969
+ orchestrator.streamStoredEventsFrom({
970
+ threadId: input.threadId,
971
+ afterSequence,
972
+ eventType,
973
+ }),
974
+ ),
975
+ { concurrency: "unbounded" },
976
).pipe(
977
Stream.mapError(loadError),
978
Stream.filter(
979
(stored) =>
980
+ untilDelegatedWorkSettled ||
981
stored.event.type !== "run.updated" ||
982
stored.event.payload.id === selectedRun.id ||
983
stored.event.payload.restartContinuationOfRunId !== undefined,
@@ -933,7 +989,7 @@ const make = Effect.gen(function* () {
989
).pipe(
990
Stream.mapEffect(() =>
991
getProjectThreadRecords(input, ["runs"]).pipe(
936
- Effect.flatMap((current) => outcome(current.runs)),
992
+ Effect.flatMap((current) => evaluate(current.runs)),
993
),
994
),
995
Stream.filter((current) => current.settled),
@@ -941,14 +997,11 @@ const make = Effect.gen(function* () {
997
Effect.timeoutOption(Duration.millis(Math.max(1, input.timeoutMs))),
998
);
999
const waited = Option.flatten(yield* wait);
944
- if (Option.isSome(waited)) {
945
- return { threadId: input.threadId, run: waited.value.run, timedOut: false };
946
- }
1000
+ if (Option.isSome(waited)) return settledResult(waited.value);
1001
// The run may have reached a terminal status while the timeout was
1002
// winning the race; the final projection read decides what actually
1003
// happened, so only a still-active run counts as timed out.
950
- const final = yield* outcome((yield* getProjectThreadRecords(input, ["runs"])).runs);
951
- return { threadId: input.threadId, run: final.run, timedOut: !final.settled };
1004
+ return settledResult(yield* evaluate((yield* getProjectThreadRecords(input, ["runs"])).runs));
1005
});
1006
1007
const settleAfterRun: ThreadManagementServiceShape["settleAfterRun"] = Effect.fn(
@@ -1175,7 +1228,42 @@ const make = Effect.gen(function* () {
1228
> = [];
1229
const stoppedChildThreadIds = new Set<ThreadId>();
1230
for (const task of subagents) {
1178
- if (task.origin !== "app_owned" || task.childThreadId === null) continue;
1231
+ if (task.origin !== "app_owned") continue;
1232
+ if (task.childThreadId === null) {
1233
+ // A task in a linked environment ends here; its follower then stops it there.
1234
+ // One with its result keeps it, but its thread there may run follow-up work.
1235
+ if (task.remoteChild === undefined) continue;
1236
+ const commandId = CommandId.make(`${input.commandId}:stop:${task.id}`);
1237
+ yield* dispatch(
1238
+ task.result === null
1239
+ ? {
1240
+ type: "delegated_task.remote.complete",
1241
+ commandId,
1242
+ parentThreadId: input.threadId,
1243
+ taskId: task.id,
1244
+ status: "interrupted",
1245
+ result:
1246
+ input.reason === undefined
1247
+ ? "Stopped with its parent."
1248
+ : `Stopped with its parent: ${input.reason}`,
1249
+ }
1250
+ : {
1251
+ type: "delegated_task.remote.stop",
1252
+ commandId,
1253
+ parentThreadId: input.threadId,
1254
+ taskId: task.id,
1255
+ },
1256
+ ).pipe(
1257
+ Effect.catch((error) =>
1258
+ Effect.logWarning("Unable to stop a delegated task", {
1259
+ parentThreadId: input.threadId,
1260
+ taskId: task.id,
1261
+ error,
1262
+ }).pipe(Effect.andThen(Effect.sync(() => failures.push(error)))),
1263
+ ),
1264
+ );
1265
+ continue;
1266
+ }
1267
const threadId = task.childThreadId;
1268
// Follow-up tasks reuse a child thread; walk its subtree only once.
1269
if (stoppedChildThreadIds.has(threadId)) continue;
apps/server/src/orchestration-v2/runtimeLayer.test.ts
+1
@@ -614,6 +614,7 @@ const layerSharedApplicationDataPlaneTest = Layer.mergeAll(
614
repositoryIdentityResolved: false,
615
}),
616
request: () => Effect.void,
617
+ readRepositoryIdentity: () => Effect.succeed(null),
618
getAvailable: () =>
619
Effect.succeed({
620
repositoryIdentity: null,
apps/server/src/peer/PeerForwarding.test.ts
+13
-6
@@ -32,6 +32,7 @@ import * as ProviderRegistry from "../provider/ProviderRegistry.ts";
32
import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts";
33
import * as SecretRequests from "../secrets/SecretRequests.ts";
34
import * as ServerSettings from "../serverSettings.ts";
35
+import * as RemoteDelegation from "./RemoteDelegation.ts";
36
import * as McpHttpServer from "../mcp/McpHttpServer.ts";
37
import * as McpInvocationContext from "../mcp/McpInvocationContext.ts";
38
import { liveThreadShell } from "../mcp/McpToolAccess.testkit.ts";
@@ -228,6 +229,7 @@ const serveBox = (seen: Ref.Ref<Seen>, linkSession: Ref.Ref<string>) =>
229
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
230
Layer.provide(ServerSettings.layerTest()),
231
Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
232
+ Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
233
),
234
);
235
@@ -296,12 +298,17 @@ const makeLaptop = Effect.gen(function* () {
298
} as never),
299
}),
300
),
299
- Layer.provide(Layer.mock(ProviderRegistry.ProviderRegistry)({})),
300
- Layer.provide(Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({})),
301
- Layer.provide(Layer.mock(ScheduledTaskService.ScheduledTaskService)({})),
302
- Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
303
- Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
304
- Layer.provide(ServerSettings.layerTest()),
301
+ Layer.provide(
302
+ Layer.mergeAll(
303
+ Layer.mock(ProviderRegistry.ProviderRegistry)({}),
304
+ Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({}),
305
+ Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
306
+ Layer.mock(ProjectService.ProjectService)({}),
307
+ Layer.mock(SecretRequests.SecretRequests)({}),
308
+ ServerSettings.layerTest(),
309
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
310
+ ),
311
+ ),
312
Layer.fresh,
313
);
314
const here = yield* Layer.build(layerHere);
apps/server/src/peer/PeerForwarding.ts
+55
-2
@@ -2,6 +2,10 @@ import {
2
type EnvironmentId,
3
OrchestratorMcpFailure,
4
type OrchestratorMcpEnvironmentLinksResult,
5
+ OrchestratorMcpThreadInterruptInput,
6
+ OrchestratorMcpThreadInterruptResult,
7
+ OrchestratorMcpThreadReadInput,
8
+ OrchestratorMcpThreadReadResult,
9
OrchestratorMcpThreadWaitInput,
10
OrchestratorMcpThreadWaitResult,
11
} from "@t3tools/contracts";
@@ -51,6 +55,18 @@ export class PeerForwarding extends Context.Service<
55
environmentId: EnvironmentId,
56
params: Tool.Parameters<T>,
57
) => Effect.Effect<Tool.Success<T>, OrchestratorMcpFailure>;
58
+ /** `t3_thread_read` there. */
59
+ readonly readThread: (
60
+ scope: Scope,
61
+ environmentId: EnvironmentId,
62
+ input: OrchestratorMcpThreadReadInput,
63
+ ) => Effect.Effect<OrchestratorMcpThreadReadResult, OrchestratorMcpFailure>;
64
+ /** `t3_thread_interrupt` there. */
65
+ readonly interruptThread: (
66
+ scope: Scope,
67
+ environmentId: EnvironmentId,
68
+ input: OrchestratorMcpThreadInterruptInput,
69
+ ) => Effect.Effect<OrchestratorMcpThreadInterruptResult, OrchestratorMcpFailure>;
70
/** `t3_thread_wait` there, in pieces short enough to survive any route. */
71
readonly waitForThread: (
72
scope: Scope,
@@ -132,6 +148,30 @@ const make = Effect.gen(function* () {
148
});
149
});
150
151
+ const readThread: PeerForwarding["Service"]["readThread"] = (scope, environmentId, input) =>
152
+ forward<OrchestratorMcpThreadReadResult>(
153
+ scope,
154
+ "t3_thread_read",
155
+ OrchestratorMcpThreadReadInput,
156
+ OrchestratorMcpThreadReadResult,
157
+ environmentId,
158
+ input,
159
+ );
160
+
161
+ const interruptThread: PeerForwarding["Service"]["interruptThread"] = (
162
+ scope,
163
+ environmentId,
164
+ input,
165
+ ) =>
166
+ forward<OrchestratorMcpThreadInterruptResult>(
167
+ scope,
168
+ "t3_thread_interrupt",
169
+ OrchestratorMcpThreadInterruptInput,
170
+ OrchestratorMcpThreadInterruptResult,
171
+ environmentId,
172
+ input,
173
+ );
174
+
175
const waitForThread: PeerForwarding["Service"]["waitForThread"] = Effect.fn(
176
"PeerForwarding.waitForThread",
177
)(function* (scope, environmentId, input) {
@@ -148,7 +188,14 @@ const make = Effect.gen(function* () {
188
OrchestratorMcpThreadWaitInput,
189
OrchestratorMcpThreadWaitResult,
190
environmentId,
151
- { threadId: input.threadId, ...(runId === undefined ? {} : { runId }), timeoutMs: chunk },
191
+ {
192
+ threadId: input.threadId,
193
+ ...(runId === undefined ? {} : { runId }),
194
+ timeoutMs: chunk,
195
+ ...(input.untilDelegatedWorkSettled === undefined
196
+ ? {}
197
+ : { untilDelegatedWorkSettled: input.untilDelegatedWorkSettled }),
198
+ },
199
);
200
remaining -= chunk;
201
if (!result.timedOut || remaining <= 0) return result;
@@ -189,7 +236,13 @@ const make = Effect.gen(function* () {
236
},
237
);
238
192
- return PeerForwarding.of({ call, waitForThread, links: listLinks });
239
+ return PeerForwarding.of({
240
+ call,
241
+ readThread,
242
+ interruptThread,
243
+ waitForThread,
244
+ links: listLinks,
245
+ });
246
});
247
248
export const layer = Layer.effect(PeerForwarding, make);
apps/server/src/peer/PeerLinks.testkit.ts
+7
-9
@@ -152,15 +152,13 @@ export const layerLinkingEnvironment = (descriptor: ExecutionEnvironmentDescript
152
PeerMcpClient.layer.pipe(
153
Layer.provideMerge(PeerLinks.layer),
154
Layer.provideMerge(Sqlite.layerMemory),
155
- Layer.provide(
156
- Layer.mergeAll(
157
- ServerSecretStore.layer,
158
- FetchHttpClient.layer,
159
- Layer.succeed(ServerEnvironment.ServerEnvironment, {
160
- getEnvironmentId: Effect.succeed(descriptor.environmentId),
161
- getDescriptor: Effect.succeed(descriptor),
162
- }),
163
- ),
155
+ Layer.provide(Layer.mergeAll(ServerSecretStore.layer, FetchHttpClient.layer)),
156
+ // Services that act for this environment, such as delegation, name it too.
157
+ Layer.provideMerge(
158
+ Layer.succeed(ServerEnvironment.ServerEnvironment, {
159
+ getEnvironmentId: Effect.succeed(descriptor.environmentId),
160
+ getDescriptor: Effect.succeed(descriptor),
161
+ }),
162
),
163
Layer.provide(ServerConfig.layerTest(process.cwd(), { prefix: "t3-peer-link-here-" })),
164
Layer.provideMerge(NodeServices.layer),
apps/server/src/peer/RemoteDelegation.test.ts
new
+1697
@@ -0,0 +1,1697 @@
1
+import * as DocumentText from "../provider/DocumentText.ts";
2
+import { NodeHttpServer } from "@effect/platform-node";
3
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
4
+import * as NodeServices from "@effect/platform-node/NodeServices";
5
+import {
6
+ CommandId,
7
+ EventId,
8
+ MessageId,
9
+ NodeId,
10
+ type OrchestrationV2Run,
11
+ ProjectId,
12
+ ProviderDriverKind,
13
+ ProviderInstanceId,
14
+ ProviderThreadId,
15
+ type Project,
16
+ type RepositoryIdentity,
17
+ RunId,
18
+ ThreadId,
19
+ TurnItemId,
20
+} from "@t3tools/contracts";
21
+import { expect, it } from "@effect/vitest";
22
+import * as Context from "effect/Context";
23
+import * as DateTime from "effect/DateTime";
24
+import * as Deferred from "effect/Deferred";
25
+import * as Effect from "effect/Effect";
26
+import * as Layer from "effect/Layer";
27
+import * as Option from "effect/Option";
28
+import * as Queue from "effect/Queue";
29
+import * as Ref from "effect/Ref";
30
+import * as Schedule from "effect/Schedule";
31
+import * as Stream from "effect/Stream";
32
+import * as SubscriptionRef from "effect/SubscriptionRef";
33
+import type * as SqlClient from "effect/sql/SqlClient";
34
+import { McpSchema, McpServer } from "effect/ai";
35
+
36
+import * as ServerConfig from "../config.ts";
37
+import * as McpHttpServer from "../mcp/McpHttpServer.ts";
38
+import * as McpInvocationContext from "../mcp/McpInvocationContext.ts";
39
+import { idleThreadProjection, liveThreadShell } from "../mcp/McpToolAccess.testkit.ts";
40
+import { CodexProviderCapabilitiesV2 } from "../orchestration-v2/Adapters/CodexAdapterV2.ts";
41
+import * as EventSink from "../orchestration-v2/EventSink.ts";
42
+import * as Orchestrator from "../orchestration-v2/Orchestrator.ts";
43
+import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts";
44
+import type * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
45
+import * as ProviderAdapterRegistry from "../orchestration-v2/ProviderAdapterRegistry.ts";
46
+import * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
47
+import * as ThreadLaunch from "../orchestration-v2/ThreadLaunchService.ts";
48
+import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts";
49
+import * as ProviderReplayHarness from "../orchestration-v2/testkit/ProviderReplayHarness.ts";
50
+import * as SqlitePersistence from "../persistence/Sqlite.ts";
51
+import * as ManagedProjectFolders from "../project/ManagedProjectFolders.ts";
52
+import * as ProjectService from "../project/ProjectService.ts";
53
+import * as RepositoryIdentityResolver from "../project/RepositoryIdentityResolver.ts";
54
+import * as ProviderRegistry from "../provider/ProviderRegistry.ts";
55
+import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts";
56
+import * as SecretRequests from "../secrets/SecretRequests.ts";
57
+import * as ServerSettings from "../serverSettings.ts";
58
+import * as CommandReceiptStore from "../orchestration-v2/CommandReceiptStore.ts";
59
+import * as SourceControlRepositoryService from "../sourceControl/SourceControlRepositoryService.ts";
60
+import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
61
+import * as PeerForwarding from "./PeerForwarding.ts";
62
+import * as PeerLinks from "./PeerLinks.ts";
63
+import { descriptorOf, layerLinkingEnvironment, linkTo, servePeer } from "./PeerLinks.testkit.ts";
64
+import * as RemoteDelegation from "./RemoteDelegation.ts";
65
+
66
+// The laptop's agent delegates a task to the box through a link. The box is
67
+// its real /mcp behind real OAuth, with one thread the test finishes; the
68
+// laptop is its real orchestrator and toolkits. The parent here wakes as it
69
+// would for a local child.
70
+
71
+const laptop = descriptorOf("environment-laptop", "Laptop");
72
+const box = descriptorOf("environment-box", "Box");
73
+const boxProject = ProjectId.make("project:box");
74
+const instanceId = ProviderInstanceId.make("codex");
75
+const driver = ProviderDriverKind.make("codex");
76
+const modelSelection = { instanceId, model: "gpt-5.4" };
77
+
78
+type LaunchedWith = Pick<
79
+ ThreadLaunch.ThreadLaunchInput,
80
+ "modelSelection" | "runtimeMode" | "interactionMode"
81
+>;
82
+
83
+/** The thread the box launches for the task, which the test finishes. */
84
+interface BoxThread {
85
+ readonly launched: Ref.Ref<ThreadId | null>;
86
+ /** The link session that launched it, as the box stamps it. */
87
+ readonly linkOrigin: Ref.Ref<{ readonly sessionId: string; readonly label: string } | null>;
88
+ /** The parent the launch names, so the thread there can link back to it. */
89
+ readonly delegatedFrom: Ref.Ref<ThreadLaunch.ThreadLaunchInput["delegatedFrom"] | null>;
90
+ /** The model and modes it was launched with. */
91
+ readonly launchedWith: Ref.Ref<LaunchedWith | null>;
92
+ /** The first message the thread there was launched with. */
93
+ readonly message: Ref.Ref<string | null>;
94
+ readonly status: Ref.Ref<OrchestrationV2Run["status"]>;
95
+ readonly reply: Ref.Ref<string | null>;
96
+ readonly error: Ref.Ref<string | null>;
97
+ readonly laterError: Ref.Ref<string | null>;
98
+ /** A later run's reply, after the task's own, as a follow-up message would leave. */
99
+ readonly laterReply: Ref.Ref<string | null>;
100
+ /** The run each wait asked for, in order. */
101
+ readonly waitedFor: Ref.Ref<ReadonlyArray<RunId | undefined>>;
102
+ /** The thread's run ends with a task of its own still running, whose result wakes it again. */
103
+ readonly nested: Ref.Ref<boolean>;
104
+ /** Completed once a wait there blocks on that task. */
105
+ readonly nestedWaiting: Deferred.Deferred<void>;
106
+ /** That task settled and the run it woke answered, with `laterReply`. */
107
+ readonly nestedSettled: Deferred.Deferred<void>;
108
+ /** Waiting there fails with this, as a thread deleted there does. */
109
+ readonly gone: Ref.Ref<boolean>;
110
+ readonly interrupted: Ref.Ref<number>;
111
+ /** What each interrupt or stop there did, once per command id. */
112
+ readonly stops: Ref.Ref<ReadonlyArray<"interrupt" | "thread.stop" | "delegated-tasks">>;
113
+ /** The launch starts no run, as one recorded before its run was kept. */
114
+ readonly runless: Ref.Ref<boolean>;
115
+ /** Completed on the first interrupt there. */
116
+ readonly interruptedOnce: Deferred.Deferred<void>;
117
+ readonly finished: Deferred.Deferred<void>;
118
+ /** While set, reading the thread there waits: completed once a read starts, released by `releaseRead`. */
119
+ readonly holdRead: Ref.Ref<boolean>;
120
+ readonly readStarted: Deferred.Deferred<void>;
121
+ readonly releaseRead: Deferred.Deferred<void>;
122
+ readonly holdFirstStop: Ref.Ref<boolean>;
123
+ readonly stopStarted: Deferred.Deferred<void>;
124
+ readonly releaseStop: Deferred.Deferred<void>;
125
+ /** Messages sent to the thread there after its launch, each starting a later run. */
126
+ readonly sent: Ref.Ref<ReadonlyArray<string>>;
127
+ /** Runs as the launch there is answered, before the laptop hears back. */
128
+ readonly afterLaunch: Ref.Ref<Effect.Effect<void>>;
129
+}
130
+
131
+const makeBoxThread = Effect.gen(function* () {
132
+ return {
133
+ launched: yield* Ref.make<ThreadId | null>(null),
134
+ linkOrigin: yield* Ref.make<{ readonly sessionId: string; readonly label: string } | null>(
135
+ null,
136
+ ),
137
+ delegatedFrom: yield* Ref.make<ThreadLaunch.ThreadLaunchInput["delegatedFrom"] | null>(null),
138
+ launchedWith: yield* Ref.make<LaunchedWith | null>(null),
139
+ message: yield* Ref.make<string | null>(null),
140
+ status: yield* Ref.make<OrchestrationV2Run["status"]>("running"),
141
+ reply: yield* Ref.make<string | null>("Working…"),
142
+ error: yield* Ref.make<string | null>(null),
143
+ laterError: yield* Ref.make<string | null>(null),
144
+ laterReply: yield* Ref.make<string | null>(null),
145
+ waitedFor: yield* Ref.make<ReadonlyArray<RunId | undefined>>([]),
146
+ nested: yield* Ref.make(false),
147
+ nestedWaiting: yield* Deferred.make<void>(),
148
+ nestedSettled: yield* Deferred.make<void>(),
149
+ gone: yield* Ref.make(false),
150
+ interrupted: yield* Ref.make(0),
151
+ stops: yield* Ref.make<ReadonlyArray<"interrupt" | "thread.stop" | "delegated-tasks">>([]),
152
+ runless: yield* Ref.make(false),
153
+ interruptedOnce: yield* Deferred.make<void>(),
154
+ finished: yield* Deferred.make<void>(),
155
+ holdRead: yield* Ref.make(false),
156
+ readStarted: yield* Deferred.make<void>(),
157
+ releaseRead: yield* Deferred.make<void>(),
158
+ holdFirstStop: yield* Ref.make(false),
159
+ stopStarted: yield* Deferred.make<void>(),
160
+ releaseStop: yield* Deferred.make<void>(),
161
+ sent: yield* Ref.make<ReadonlyArray<string>>([]),
162
+ afterLaunch: yield* Ref.make<Effect.Effect<void>>(Effect.void),
163
+ } satisfies BoxThread;
164
+});
165
+
166
+/** The box's projects: more than a page, with this repository's last. */
167
+const boxProjects: ReadonlyArray<Project> = [
168
+ ...Array.from({ length: 120 }, (_, index) => ({
169
+ id: ProjectId.make(`project:box-other-${index}`),
170
+ title: `other ${index}`,
171
+ workspaceRoot: `/srv/other-${index}`,
172
+ repositoryIdentity: null,
173
+ defaultModelSelection: null,
174
+ scripts: [],
175
+ createdAt: "2026-10-01T00:00:00.000Z",
176
+ updatedAt: "2026-10-01T00:00:00.000Z",
177
+ deletedAt: null,
178
+ })),
179
+ {
180
+ id: boxProject,
181
+ title: "app",
182
+ workspaceRoot: "/srv/app",
183
+ repositoryIdentity: {
184
+ canonicalKey: "github.com/acme/app",
185
+ locator: {
186
+ source: "git-remote",
187
+ remoteName: "origin",
188
+ remoteUrl: "git@github.com:acme/app.git",
189
+ },
190
+ },
191
+ defaultModelSelection: null,
192
+ scripts: [],
193
+ createdAt: "2026-10-01T00:00:00.000Z",
194
+ updatedAt: "2026-10-01T00:00:00.000Z",
195
+ deletedAt: null,
196
+ },
197
+];
198
+
199
+const serveBox = (thread: BoxThread) => {
200
+ return servePeer(box, boxToolkitLayer(thread));
201
+};
202
+
203
+const boxRunId = RunId.make("run:box");
204
+const boxLaterRunId = RunId.make("run:box-later");
205
+
206
+const boxToolkitLayer = (thread: BoxThread) => {
207
+ const runId = boxRunId;
208
+ const interrupts = new Set<string>();
209
+ const shellOf = (threadId: ThreadId) =>
210
+ Effect.gen(function* () {
211
+ if ((yield* Ref.get(thread.launched)) !== threadId) return null;
212
+ const linkOrigin = yield* Ref.get(thread.linkOrigin);
213
+ return {
214
+ ...liveThreadShell(threadId, { runtimeMode: "full-access" }),
215
+ projectId: boxProject,
216
+ ...(linkOrigin === null ? {} : { linkOrigin }),
217
+ };
218
+ });
219
+ const runOf = (status: OrchestrationV2Run["status"]) =>
220
+ ({
221
+ id: runId,
222
+ threadId: ThreadId.make("thread:box"),
223
+ ordinal: 1,
224
+ status,
225
+ modelSelection,
226
+ requestedAt: DateTime.makeUnsafe(0),
227
+ startedAt: DateTime.makeUnsafe(0),
228
+ completedAt: null,
229
+ }) as unknown as OrchestrationV2Run;
230
+ const projectionOf = (threadId: ThreadId) =>
231
+ Effect.gen(function* () {
232
+ const shell = yield* shellOf(threadId);
233
+ const status = yield* Ref.get(thread.status);
234
+ const runless = yield* Ref.get(thread.runless);
235
+ return shell === null
236
+ ? (null as never)
237
+ : { ...idleThreadProjection(shell), runs: runless ? [] : [runOf(status)] };
238
+ });
239
+ // One record per command id, as its receipt replays a repeat.
240
+ const recordStop = (commandId: string, kind: "interrupt" | "thread.stop" | "delegated-tasks") =>
241
+ Effect.gen(function* () {
242
+ if (interrupts.has(`${kind}:${commandId}`)) return;
243
+ interrupts.add(`${kind}:${commandId}`);
244
+ yield* Ref.update(thread.stops, (seen) => [...seen, kind]);
245
+ if (kind !== "delegated-tasks") {
246
+ yield* Ref.update(thread.interrupted, (count) => count + 1);
247
+ yield* Deferred.succeed(thread.interruptedOnce, undefined);
248
+ }
249
+ });
250
+ const layerBoxThreads = Layer.mock(ThreadManagement.ThreadManagementService)({
251
+ getThreadShell: shellOf,
252
+ getProjectThreadRecords: (input) => projectionOf(input.threadId),
253
+ getThreadRecords: (threadId) => projectionOf(threadId),
254
+ waitForThread: (input) =>
255
+ Effect.gen(function* () {
256
+ yield* Ref.update(thread.waitedFor, (seen) => [...seen, input.runId]);
257
+ // A thread with no run has nothing to wait for.
258
+ if (yield* Ref.get(thread.runless)) {
259
+ return { threadId: input.threadId, run: null, timedOut: false };
260
+ }
261
+ if (yield* Ref.get(thread.gone)) {
262
+ return yield* new ThreadManagement.ThreadManagementThreadNotFoundError({
263
+ projectId: boxProject,
264
+ threadId: input.threadId,
265
+ });
266
+ }
267
+ const done = yield* Deferred.await(thread.finished).pipe(
268
+ Effect.timeoutOption(input.timeoutMs),
269
+ );
270
+ // Only a waiter that asks waits past the run for the thread's own task.
271
+ if (
272
+ Option.isSome(done) &&
273
+ input.untilDelegatedWorkSettled === true &&
274
+ (yield* Ref.get(thread.nested))
275
+ ) {
276
+ yield* Deferred.succeed(thread.nestedWaiting, undefined);
277
+ const settled = yield* Deferred.await(thread.nestedSettled).pipe(
278
+ Effect.timeoutOption(input.timeoutMs),
279
+ );
280
+ return {
281
+ threadId: input.threadId,
282
+ run: { id: runId, status: yield* Ref.get(thread.status) } as OrchestrationV2Run,
283
+ timedOut: Option.isNone(settled),
284
+ ...(Option.isSome(settled)
285
+ ? { resultRun: { id: boxLaterRunId, status: "completed" } as OrchestrationV2Run }
286
+ : {}),
287
+ };
288
+ }
289
+ // Unpinned, a wait reports the latest run: a later one once there is one.
290
+ const later = input.runId === undefined && (yield* Ref.get(thread.laterReply)) !== null;
291
+ return {
292
+ threadId: input.threadId,
293
+ run: {
294
+ id: later ? boxLaterRunId : runId,
295
+ status: later ? "completed" : yield* Ref.get(thread.status),
296
+ } as OrchestrationV2Run,
297
+ timedOut: Option.isNone(done),
298
+ };
299
+ }),
300
+ getTimelinePage: (threadId, options) =>
301
+ Effect.gen(function* () {
302
+ if (yield* Ref.get(thread.holdRead)) {
303
+ yield* Deferred.succeed(thread.readStarted, undefined);
304
+ yield* Deferred.await(thread.releaseRead);
305
+ }
306
+ const reply = yield* Ref.get(thread.reply);
307
+ const later = yield* Ref.get(thread.laterReply);
308
+ const error = yield* Ref.get(thread.error);
309
+ const laterError = yield* Ref.get(thread.laterError);
310
+ // One item per page, with errors available only in the activity view.
311
+ const replies = [
312
+ ...(reply === null
313
+ ? []
314
+ : [
315
+ {
316
+ id: TurnItemId.make("item:reply"),
317
+ runId,
318
+ text: reply,
319
+ type: "assistant_message",
320
+ },
321
+ ]),
322
+ ...(error === null
323
+ ? []
324
+ : [{ id: TurnItemId.make("item:error"), runId, text: error, type: "error" }]),
325
+ ...(later === null
326
+ ? []
327
+ : [
328
+ {
329
+ id: TurnItemId.make("item:later-reply"),
330
+ runId: boxLaterRunId,
331
+ text: later,
332
+ type: "assistant_message",
333
+ },
334
+ ]),
335
+ ...(laterError === null
336
+ ? []
337
+ : [
338
+ {
339
+ id: TurnItemId.make("item:later-error"),
340
+ runId: boxLaterRunId,
341
+ text: laterError,
342
+ type: "error",
343
+ },
344
+ ]),
345
+ ].map((entry, position) => ({ ...entry, position }));
346
+ const visible =
347
+ options.itemId === undefined
348
+ ? replies.filter(
349
+ (entry) => options.view === "activity" || entry.type === "assistant_message",
350
+ )
351
+ : replies.filter((entry) => entry.id === options.itemId);
352
+ const matching = visible
353
+ .filter((entry) => entry.position > (options.afterPosition ?? -1))
354
+ .slice(0, 1);
355
+ return {
356
+ items: matching.map(({ id, runId: itemRunId, text, position, type }) => ({
357
+ position,
358
+ visibility: "local" as const,
359
+ sourceThreadId: threadId,
360
+ sourceItemId: id,
361
+ item: {
362
+ id,
363
+ threadId,
364
+ runId: itemRunId,
365
+ nodeId: null,
366
+ providerThreadId: null,
367
+ providerTurnId: null,
368
+ nativeItemRef: null,
369
+ parentItemId: null,
370
+ ordinal: 1,
371
+ status: "completed" as const,
372
+ title: null,
373
+ startedAt: DateTime.makeUnsafe(0),
374
+ completedAt: DateTime.makeUnsafe(0),
375
+ updatedAt: DateTime.makeUnsafe(0),
376
+ ...(type === "error"
377
+ ? { type, failure: { message: text } }
378
+ : {
379
+ type: "assistant_message" as const,
380
+ messageId: MessageId.make(`message:${id}`),
381
+ text,
382
+ streaming: false,
383
+ }),
384
+ } as never,
385
+ })),
386
+ totalItems: replies.length,
387
+ hasMore:
388
+ options.itemId === undefined &&
389
+ matching.length > 0 &&
390
+ visible.some((entry) => entry.position > matching.at(-1)!.position),
391
+ };
392
+ }),
393
+ interruptThread: (input) =>
394
+ recordStop(input.commandId, "interrupt").pipe(
395
+ Effect.as({ type: "interrupt_requested", run: runOf("running") } as never),
396
+ ),
397
+ dispatch: (command) =>
398
+ command.type === "thread.stop"
399
+ ? recordStop(command.commandId, "thread.stop").pipe(
400
+ Effect.tap(() =>
401
+ Effect.gen(function* () {
402
+ if (!(yield* Ref.getAndSet(thread.holdFirstStop, false))) return;
403
+ yield* Deferred.succeed(thread.stopStarted, undefined);
404
+ yield* Deferred.await(thread.releaseStop);
405
+ }),
406
+ ),
407
+ Effect.as({ sequence: 0, storedEvents: [] } as never),
408
+ )
409
+ : Effect.die(`The box does not expect ${command.type}`),
410
+ stopDelegatedTasks: (input) => recordStop(input.commandId, "delegated-tasks"),
411
+ sendToThread: (input) =>
412
+ Ref.update(thread.sent, (seen) => [...seen, input.text]).pipe(
413
+ Effect.as({
414
+ run: { id: boxLaterRunId, status: "running" },
415
+ delivery: "started",
416
+ } as never),
417
+ ),
418
+ });
419
+ const layerBoxLaunches = Layer.mock(ThreadLaunch.ThreadLaunchService)({
420
+ launch: (input) =>
421
+ Ref.get(thread.runless).pipe(
422
+ Effect.flatMap((runless) =>
423
+ Ref.set(thread.launched, input.threadId!).pipe(
424
+ Effect.andThen(Ref.set(thread.linkOrigin, input.linkOrigin ?? null)),
425
+ Effect.andThen(Ref.set(thread.delegatedFrom, input.delegatedFrom ?? null)),
426
+ Effect.andThen(Ref.set(thread.message, input.initialMessage?.text ?? null)),
427
+ Effect.andThen(
428
+ Ref.set(thread.launchedWith, {
429
+ modelSelection: input.modelSelection,
430
+ runtimeMode: input.runtimeMode,
431
+ interactionMode: input.interactionMode,
432
+ }),
433
+ ),
434
+ Effect.andThen(Effect.flatten(Ref.get(thread.afterLaunch))),
435
+ Effect.as({
436
+ threadId: input.threadId,
437
+ projection: {
438
+ thread: {
439
+ id: input.threadId,
440
+ projectId: input.projectId,
441
+ title: input.title,
442
+ modelSelection: input.modelSelection,
443
+ },
444
+ runs:
445
+ input.initialMessage?.messageId && !runless
446
+ ? [
447
+ {
448
+ id: runId,
449
+ status: "running",
450
+ userMessageId: input.initialMessage.messageId,
451
+ },
452
+ ]
453
+ : [],
454
+ },
455
+ resumed: false,
456
+ } as unknown as ThreadLaunch.ThreadLaunchResult),
457
+ ),
458
+ ),
459
+ ),
460
+ });
461
+ return Layer.merge(
462
+ McpHttpServer.layerOrchestratorToolkit,
463
+ McpHttpServer.layerProjectRegistration,
464
+ ).pipe(
465
+ Layer.provide(DocumentText.layer.pipe(Layer.provideMerge(NodeServices.layer))),
466
+ Layer.provide(NodeCrypto.layer),
467
+ Layer.provide(layerBoxThreads),
468
+ Layer.provide(layerBoxLaunches),
469
+ Layer.provide(Layer.mock(RemoteDelegation.RemoteDelegation)({})),
470
+ Layer.provide(Layer.mock(PeerForwarding.PeerForwarding)({})),
471
+ Layer.provide(
472
+ Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({ namedProjectsRoot: "/p" }),
473
+ ),
474
+ Layer.provide(Layer.mock(GitVcsDriver.GitVcsDriver)({})),
475
+ Layer.provide(Layer.mock(SourceControlRepositoryService.SourceControlRepositoryService)({})),
476
+ Layer.provide(
477
+ ServerConfig.layerTest(process.cwd(), { prefix: "t3-remote-delegation-box-" }).pipe(
478
+ Layer.provide(NodeServices.layer),
479
+ ),
480
+ ),
481
+ Layer.provide(Layer.mock(ProviderRegistry.ProviderRegistry)({})),
482
+ Layer.provide(Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({})),
483
+ Layer.provide(Layer.mock(ScheduledTaskService.ScheduledTaskService)({})),
484
+ Layer.provide(
485
+ Layer.mock(ProjectService.ProjectService)({
486
+ getById: () => Effect.succeedNone,
487
+ // More than a page, so finding the project with this repository pages.
488
+ listPage: ({ cursor, limit }) =>
489
+ Effect.succeed({
490
+ projects: boxProjects.slice(cursor, cursor + limit),
491
+ nextCursor: cursor + limit < boxProjects.length ? cursor + limit : null,
492
+ }),
493
+ }),
494
+ ),
495
+ Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
496
+ Layer.provide(ServerSettings.layerTest()),
497
+ Layer.provide(NodeServices.layer),
498
+ );
499
+};
500
+
501
+const mcpClient = McpSchema.McpServerClient.of({
502
+ clientId: 1,
503
+ protocolVersion: "2025-06-18",
504
+ clientCapabilities: {},
505
+ clientInfo: { name: "remote-delegation", version: "1" },
506
+ initializePayload: {
507
+ protocolVersion: "2025-06-18",
508
+ capabilities: {},
509
+ clientInfo: { name: "remote-delegation", version: "1" },
510
+ },
511
+ getClient: Effect.die("unused"),
512
+});
513
+
514
+const adapter = {
515
+ instanceId,
516
+ driver,
517
+ getCapabilities: () => Effect.succeed(CodexProviderCapabilitiesV2),
518
+ planSelectionTransition: () => Effect.succeed({ type: "apply_on_next_turn" as const }),
519
+ openSession: () => Effect.die("No provider process needed"),
520
+} as ProviderAdapter.ProviderAdapterV2["Service"];
521
+
522
+/**
523
+ * The laptop: a real orchestrator (in-memory SQLite) whose parent thread has
524
+ * a live run, the real orchestrator toolkit, and RemoteDelegation. Built in
525
+ * its own scope so a test can tear it down and build it again on the same
526
+ * database, as a restart does.
527
+ */
528
+const makeLaptop = (
529
+ database: Context.Context<SqlClient.SqlClient>,
530
+ offers: SubscriptionRef.SubscriptionRef<
531
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
532
+ >,
533
+ /** The laptop's links from before a restart, which keep their sessions there. */
534
+ kept?: Context.Context<Layer.Success<ReturnType<typeof layerLinkingEnvironment>>>,
535
+) =>
536
+ Effect.gen(function* () {
537
+ const linking = kept ?? (yield* layerLinkingEnvironment(laptop).pipe(Layer.build));
538
+ const layerDatabase = Layer.succeedContext(database);
539
+ const layerOrchestrator = Layer.mergeAll(
540
+ layerDatabase,
541
+ ProjectionStore.layer.pipe(Layer.provide(layerDatabase)),
542
+ ProviderReplayHarness.layerWithRegistry(
543
+ { name: "remote-delegation-laptop" },
544
+ ProviderAdapterRegistry.layerFromAdapters([adapter]),
545
+ { databaseLayer: layerDatabase, runEffectWorker: false },
546
+ ),
547
+ ).pipe(
548
+ Layer.provide(
549
+ Layer.succeed(ProviderContinuationRequests.ProviderContinuationRequests, {
550
+ offer: (request) => SubscriptionRef.update(offers, (seen) => [...seen, request]),
551
+ take: Effect.never,
552
+ }),
553
+ ),
554
+ );
555
+ const layerThreads = ThreadManagement.layer.pipe(
556
+ Layer.provide(CommandReceiptStore.layer.pipe(Layer.provide(layerDatabase))),
557
+ Layer.provideMerge(Layer.merge(layerOrchestrator, ServerSettings.layerTest())),
558
+ );
559
+ const layerHere = McpHttpServer.layerOrchestratorToolkit.pipe(
560
+ Layer.provideMerge(McpServer.McpServer.layer),
561
+ Layer.provideMerge(
562
+ RemoteDelegation.layer.pipe(
563
+ Layer.provideMerge(PeerForwarding.layer),
564
+ Layer.provide(
565
+ Layer.mock(ProjectService.ProjectService)({
566
+ // A cold enrichment cache: the project itself reports no identity yet.
567
+ getById: () =>
568
+ Effect.succeedSome({
569
+ workspaceRoot: "/home/me/app",
570
+ repositoryIdentity: null,
571
+ } as never),
572
+ }),
573
+ ),
574
+ Layer.provide(
575
+ Layer.mock(RepositoryIdentityResolver.RepositoryIdentityResolver)({
576
+ resolve: (cwd) =>
577
+ Effect.succeed(
578
+ cwd === "/home/me/app"
579
+ ? ({ canonicalKey: "github.com/acme/app" } as RepositoryIdentity)
580
+ : null,
581
+ ),
582
+ }),
583
+ ),
584
+ ),
585
+ ),
586
+ Layer.provide(Layer.succeedContext(linking)),
587
+ Layer.provide(NodeCrypto.layer),
588
+ Layer.provideMerge(layerThreads),
589
+ Layer.provide(Layer.mock(ProviderRegistry.ProviderRegistry)({})),
590
+ Layer.provide(Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({})),
591
+ Layer.provide(Layer.mock(ScheduledTaskService.ScheduledTaskService)({})),
592
+ Layer.provide(Layer.mock(ProjectService.ProjectService)({})),
593
+ Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
594
+ Layer.provide(Layer.mock(ThreadLaunch.ThreadLaunchService)({})),
595
+ Layer.provide(Layer.mock(GitVcsDriver.GitVcsDriver)({})),
596
+ Layer.fresh,
597
+ );
598
+ const here = yield* Layer.build(layerHere);
599
+ const server = Context.get(here, McpServer.McpServer);
600
+ return {
601
+ links: Context.get(linking, PeerLinks.PeerLinks),
602
+ orchestrator: Context.get(here, Orchestrator.OrchestratorV2),
603
+ remote: Context.get(here, RemoteDelegation.RemoteDelegation),
604
+ threads: Context.get(here, ThreadManagement.ThreadManagementService),
605
+ projections: Context.get(here, ProjectionStore.ProjectionStoreV2),
606
+ sink: Context.get(here, EventSink.EventSinkV2),
607
+ call: (name: string, args: Record<string, unknown>, scope = parentScope) =>
608
+ server
609
+ .callTool({ name, arguments: args })
610
+ .pipe(
611
+ Effect.provideService(McpInvocationContext.McpInvocationContext, scope),
612
+ Effect.provideService(McpSchema.McpServerClient, mcpClient),
613
+ ),
614
+ };
615
+ });
616
+
617
+const parentThreadId = ThreadId.make("thread:laptop-parent");
618
+const parentRunId = RunId.make("run:laptop-parent");
619
+const parentRootNode = NodeId.make("node:laptop-parent:root");
620
+const parentScope: McpInvocationContext.McpInvocationScope = {
621
+ environmentId: laptop.environmentId,
622
+ requestNamespace: "provider-session:laptop-parent",
623
+ thread: {
624
+ threadId: parentThreadId,
625
+ providerSessionId: "provider-session:laptop-parent",
626
+ providerInstanceId: instanceId,
627
+ },
628
+ client: undefined,
629
+ capabilities: new Set(["orchestration"]),
630
+ issuedAt: 1,
631
+};
632
+
633
+/** The laptop's parent thread, mid-turn when its agent delegates. */
634
+const seedParent = (laptopEnv: Effect.Success<ReturnType<typeof makeLaptop>>) =>
635
+ Effect.gen(function* () {
636
+ const now = yield* DateTime.now;
637
+ const providerThreadId = ProviderThreadId.make("provider-thread:laptop-parent");
638
+ yield* laptopEnv.orchestrator.dispatch({
639
+ type: "thread.create",
640
+ createdBy: "user",
641
+ creationSource: "web",
642
+ commandId: CommandId.make("command:create:laptop-parent"),
643
+ threadId: parentThreadId,
644
+ projectId: ProjectId.make("project:laptop"),
645
+ title: "Laptop parent",
646
+ modelSelection,
647
+ runtimeMode: "full-access",
648
+ interactionMode: "default",
649
+ branch: null,
650
+ worktreePath: null,
651
+ });
652
+ yield* laptopEnv.sink.write({
653
+ commandId: CommandId.make("command:seed:laptop-parent"),
654
+ events: [
655
+ {
656
+ id: EventId.make("event:seed-provider-thread:laptop-parent"),
657
+ type: "provider-thread.updated",
658
+ threadId: parentThreadId,
659
+ driver,
660
+ providerInstanceId: instanceId,
661
+ occurredAt: now,
662
+ payload: {
663
+ id: providerThreadId,
664
+ driver,
665
+ providerInstanceId: instanceId,
666
+ providerSessionId: null,
667
+ appThreadId: parentThreadId,
668
+ ownerNodeId: parentRootNode,
669
+ nativeThreadRef: { driver, nativeId: "native:laptop-parent", strength: "strong" },
670
+ nativeConversationHeadRef: null,
671
+ status: "active",
672
+ firstRunOrdinal: 1,
673
+ lastRunOrdinal: 1,
674
+ handoffIds: [],
675
+ forkedFrom: null,
676
+ createdAt: now,
677
+ updatedAt: now,
678
+ },
679
+ },
680
+ {
681
+ id: EventId.make("event:seed-node:laptop-parent"),
682
+ type: "node.updated",
683
+ threadId: parentThreadId,
684
+ runId: parentRunId,
685
+ nodeId: parentRootNode,
686
+ driver,
687
+ providerInstanceId: instanceId,
688
+ occurredAt: now,
689
+ payload: {
690
+ id: parentRootNode,
691
+ threadId: parentThreadId,
692
+ runId: parentRunId,
693
+ parentNodeId: null,
694
+ rootNodeId: parentRootNode,
695
+ kind: "root_turn",
696
+ status: "running",
697
+ countsForRun: true,
698
+ providerThreadId,
699
+ providerTurnId: null,
700
+ nativeItemRef: null,
701
+ runtimeRequestId: null,
702
+ checkpointScopeId: null,
703
+ startedAt: now,
704
+ completedAt: null,
705
+ },
706
+ },
707
+ {
708
+ id: EventId.make("event:seed-run:laptop-parent"),
709
+ type: "run.updated",
710
+ threadId: parentThreadId,
711
+ runId: parentRunId,
712
+ nodeId: parentRootNode,
713
+ providerInstanceId: instanceId,
714
+ occurredAt: now,
715
+ payload: {
716
+ id: parentRunId,
717
+ threadId: parentThreadId,
718
+ ordinal: 1,
719
+ providerInstanceId: instanceId,
720
+ modelSelection,
721
+ providerThreadId,
722
+ userMessageId: MessageId.make("message:seed-user:laptop-parent"),
723
+ rootNodeId: parentRootNode,
724
+ activeAttemptId: null,
725
+ status: "running",
726
+ requestedAt: now,
727
+ startedAt: now,
728
+ completedAt: null,
729
+ checkpointId: null,
730
+ contextHandoffId: null,
731
+ },
732
+ },
733
+ ],
734
+ });
735
+ });
736
+
737
+const delegateToBox = (laptopEnv: Effect.Success<ReturnType<typeof makeLaptop>>) =>
738
+ laptopEnv
739
+ .call("delegate_task", {
740
+ task: "Run the full suite on the box.",
741
+ target: {
742
+ environmentId: box.environmentId,
743
+ providerInstanceId: instanceId,
744
+ model: "gpt-5.4",
745
+ },
746
+ mode: "async",
747
+ clientRequestId: "suite-on-box",
748
+ })
749
+ .pipe(
750
+ Effect.map((result) => {
751
+ expect(result.isError, JSON.stringify(result.content)).toBe(false);
752
+ return result.structuredContent as {
753
+ taskId: NodeId;
754
+ status: string;
755
+ childThreadId: null;
756
+ remoteChild: { environmentId: string; threadId: ThreadId; label: string };
757
+ };
758
+ }),
759
+ );
760
+
761
+/** Waits until the task here has the result its thread there ended with. */
762
+const taskResult = (laptopEnv: Effect.Success<ReturnType<typeof makeLaptop>>, taskId: NodeId) =>
763
+ laptopEnv.orchestrator
764
+ .streamStoredEventsFrom({
765
+ threadId: parentThreadId,
766
+ afterSequence: 0,
767
+ eventType: "subagent.updated",
768
+ })
769
+ .pipe(
770
+ Stream.filter(
771
+ (stored) =>
772
+ stored.event.type === "subagent.updated" &&
773
+ stored.event.payload.id === taskId &&
774
+ stored.event.payload.result !== null,
775
+ ),
776
+ Stream.runHead,
777
+ Effect.map((stored) =>
778
+ Option.isSome(stored) && stored.value.event.type === "subagent.updated"
779
+ ? stored.value.event.payload
780
+ : undefined,
781
+ ),
782
+ );
783
+
784
+it.effect("a task delegated to the box wakes the laptop's parent when it ends there", () =>
785
+ Effect.scoped(
786
+ Effect.gen(function* () {
787
+ const thread = yield* makeBoxThread;
788
+ const b = yield* serveBox(thread);
789
+ const offers = yield* SubscriptionRef.make<
790
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
791
+ >([]);
792
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
793
+ const a = yield* makeLaptop(database, offers);
794
+ yield* linkTo(a.links, b, "full-access");
795
+ yield* seedParent(a);
796
+
797
+ const delegated = yield* delegateToBox(a);
798
+ expect(delegated).toMatchObject({
799
+ status: "running",
800
+ childThreadId: null,
801
+ remoteChild: { environmentId: box.environmentId, label: "Box" },
802
+ });
803
+ // The box launched it in the project with the same repository.
804
+ expect(yield* Ref.get(thread.launched)).toBe(delegated.remoteChild.threadId);
805
+ // ...naming the parent here, so the thread there links back to it.
806
+ expect(yield* Ref.get(thread.delegatedFrom)).toEqual({
807
+ environmentId: laptop.environmentId,
808
+ threadId: parentThreadId,
809
+ title: "Laptop parent",
810
+ });
811
+ // A retry with the same key launches nothing new and records nothing new.
812
+ const retried = yield* delegateToBox(a);
813
+ expect(retried.taskId).toBe(delegated.taskId);
814
+ expect((yield* a.orchestrator.getThreadProjection(parentThreadId)).subagents).toHaveLength(1);
815
+
816
+ yield* Ref.set(thread.reply, "All 412 tests pass on the box.");
817
+ yield* Ref.set(thread.status, "completed");
818
+ yield* Deferred.succeed(thread.finished, undefined);
819
+ const task = yield* taskResult(a, delegated.taskId);
820
+ expect(task).toMatchObject({ status: "completed", result: "All 412 tests pass on the box." });
821
+ // The parent's live run claims the result, as for a child here.
822
+ const parentRun = (yield* a.orchestrator.getThreadProjection(parentThreadId)).runs.find(
823
+ (run) => run.id === parentRunId,
824
+ );
825
+ expect(parentRun?.delegatedCompletion?.delivery?.taskIds).toEqual([delegated.taskId]);
826
+ // The wake is offered after the result commits, so the result can be seen first.
827
+ const offered = yield* SubscriptionRef.changes(offers).pipe(
828
+ Stream.filter((seen) => seen.some((offer) => offer.threadId === parentThreadId)),
829
+ Stream.runHead,
830
+ );
831
+ expect(Option.isSome(offered)).toBe(true);
832
+
833
+ const status = yield* a.call("task_status", { taskId: delegated.taskId });
834
+ expect(status.structuredContent).toMatchObject({
835
+ status: "completed",
836
+ summary: "All 412 tests pass on the box.",
837
+ });
838
+ }),
839
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
840
+);
841
+
842
+it.effect("a task named only by environment inherits the parent's model, within the link", () =>
843
+ Effect.scoped(
844
+ Effect.gen(function* () {
845
+ const thread = yield* makeBoxThread;
846
+ const b = yield* serveBox(thread);
847
+ const offers = yield* SubscriptionRef.make<
848
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
849
+ >([]);
850
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
851
+ const a = yield* makeLaptop(database, offers);
852
+ // The parent runs with full access; the link allows less.
853
+ yield* linkTo(a.links, b, "auto-accept-edits");
854
+ yield* seedParent(a);
855
+
856
+ const result = yield* a.call("delegate_task", {
857
+ task: "Run the suite on the box.",
858
+ target: { environmentId: box.environmentId },
859
+ });
860
+ expect(result.isError, JSON.stringify(result.content)).toBe(false);
861
+ // The parent's model, and the link's modes rather than the parent's.
862
+ expect(yield* Ref.get(thread.launchedWith)).toEqual({
863
+ modelSelection,
864
+ runtimeMode: "auto-accept-edits",
865
+ interactionMode: "default",
866
+ });
867
+
868
+ // Asking for more than the link allows is still refused there.
869
+ const broader = yield* a.call("delegate_task", {
870
+ task: "Run the suite on the box.",
871
+ target: { environmentId: box.environmentId },
872
+ runtimeMode: "full-access",
873
+ clientRequestId: "broader",
874
+ });
875
+ expect(broader.isError).toBe(true);
876
+ }),
877
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
878
+);
879
+
880
+it.effect("refuses worktree isolation for a task there before launching anything", () =>
881
+ Effect.scoped(
882
+ Effect.gen(function* () {
883
+ const thread = yield* makeBoxThread;
884
+ const b = yield* serveBox(thread);
885
+ const offers = yield* SubscriptionRef.make<
886
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
887
+ >([]);
888
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
889
+ const a = yield* makeLaptop(database, offers);
890
+ yield* linkTo(a.links, b, "auto");
891
+ yield* seedParent(a);
892
+
893
+ const result = yield* a.call("delegate_task", {
894
+ task: "Run the suite on the box.",
895
+ target: { environmentId: box.environmentId },
896
+ isolation: "worktree",
897
+ });
898
+ expect(result.isError).toBe(true);
899
+ expect(JSON.stringify(result.content)).toContain("isolation");
900
+ expect(yield* Ref.get(thread.launched)).toBeNull();
901
+ }),
902
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
903
+);
904
+
905
+it.effect("follows an open task again after the laptop restarts", () =>
906
+ Effect.scoped(
907
+ Effect.gen(function* () {
908
+ const thread = yield* makeBoxThread;
909
+ const b = yield* serveBox(thread);
910
+ const offers = yield* SubscriptionRef.make<
911
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
912
+ >([]);
913
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
914
+ // The laptop before the restart delegates, then goes away.
915
+ const delegated = yield* Effect.scoped(
916
+ Effect.gen(function* () {
917
+ const before = yield* makeLaptop(database, offers);
918
+ yield* linkTo(before.links, b, "full-access");
919
+ yield* seedParent(before);
920
+ return yield* delegateToBox(before);
921
+ }),
922
+ );
923
+ // The task finishes on the box while the laptop is down.
924
+ yield* Ref.set(thread.reply, "Finished while you were away.");
925
+ yield* Ref.set(thread.status, "completed");
926
+ yield* Deferred.succeed(thread.finished, undefined);
927
+
928
+ const after = yield* makeLaptop(database, offers);
929
+ // The link lives in the laptop's own store, so it needs linking again here.
930
+ yield* linkTo(after.links, b, "full-access");
931
+ yield* after.remote.start();
932
+ const task = yield* taskResult(after, delegated.taskId);
933
+ expect(task).toMatchObject({ status: "completed", result: "Finished while you were away." });
934
+ }),
935
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
936
+);
937
+
938
+it.effect("fails the task when the box revokes the link, and cancel interrupts it there", () =>
939
+ Effect.scoped(
940
+ Effect.gen(function* () {
941
+ const thread = yield* makeBoxThread;
942
+ const b = yield* serveBox(thread);
943
+ const offers = yield* SubscriptionRef.make<
944
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
945
+ >([]);
946
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
947
+ const a = yield* makeLaptop(database, offers);
948
+ yield* linkTo(a.links, b, "full-access");
949
+ yield* seedParent(a);
950
+
951
+ const cancelled = yield* delegateToBox(a);
952
+ const cancel = yield* a.call("task_cancel", {
953
+ taskId: cancelled.taskId,
954
+ reason: "Not needed",
955
+ });
956
+ expect(cancel.structuredContent).toEqual({
957
+ taskId: cancelled.taskId,
958
+ status: "cancel_requested",
959
+ });
960
+ // Cancelling stops the thread there as Stop does: its queue and its own tasks too.
961
+ expect(yield* Ref.get(thread.stops)).toEqual(["thread.stop", "delegated-tasks"]);
962
+ expect(yield* taskResult(a, cancelled.taskId)).toMatchObject({ status: "cancelled" });
963
+
964
+ // Cancelling again, once the result is in, still stops what came after it there.
965
+ const again = yield* a.call("task_cancel", {
966
+ taskId: cancelled.taskId,
967
+ clientRequestId: "cancel-again",
968
+ });
969
+ expect(again.structuredContent).toEqual({ taskId: cancelled.taskId, status: "cancelled" });
970
+ expect(yield* Ref.get(thread.interrupted)).toBe(2);
971
+ // ...and a retry of that cancel stops nothing new.
972
+ yield* a.call("task_cancel", { taskId: cancelled.taskId, clientRequestId: "cancel-again" });
973
+ expect(yield* Ref.get(thread.interrupted)).toBe(2);
974
+
975
+ // A second task, then the box revokes the link before it ends.
976
+ const revoked = yield* a
977
+ .call("delegate_task", {
978
+ task: "Another one.",
979
+ target: {
980
+ environmentId: box.environmentId,
981
+ providerInstanceId: instanceId,
982
+ model: "gpt-5.4",
983
+ },
984
+ clientRequestId: "second",
985
+ })
986
+ .pipe(Effect.map((result) => result.structuredContent as { taskId: NodeId }));
987
+ const [session] = yield* b.linkedSessions;
988
+ yield* b.auth.revokeSession(session!.sessionId);
989
+ yield* Deferred.succeed(thread.finished, undefined);
990
+ const failed = yield* taskResult(a, revoked.taskId);
991
+ expect(failed?.status).toBe("failed");
992
+ expect(failed?.result).toBe(
993
+ "The linked environment no longer accepts this link. It may have been revoked there; link it again.",
994
+ );
995
+ }),
996
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
997
+);
998
+
999
+it.effect("a task's result is its own run's whole last reply, not a later run's", () =>
1000
+ Effect.scoped(
1001
+ Effect.gen(function* () {
1002
+ const thread = yield* makeBoxThread;
1003
+ const b = yield* serveBox(thread);
1004
+ const offers = yield* SubscriptionRef.make<
1005
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1006
+ >([]);
1007
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1008
+ const a = yield* makeLaptop(database, offers);
1009
+ yield* linkTo(a.links, b, "full-access");
1010
+ yield* seedParent(a);
1011
+
1012
+ const result = yield* a.call("delegate_task", {
1013
+ task: "Review the diff.",
1014
+ role: "review",
1015
+ target: { environmentId: box.environmentId },
1016
+ clientRequestId: "review-on-box",
1017
+ });
1018
+ expect(result.isError, JSON.stringify(result.content)).toBe(false);
1019
+ const { taskId } = result.structuredContent as { taskId: NodeId };
1020
+ // The role reaches the thread there, as it does a child here.
1021
+ expect(yield* Ref.get(thread.message)).toBe(
1022
+ "Act as the review sub-agent for this task.\n\nReview the diff.",
1023
+ );
1024
+
1025
+ // A reply longer than one read, then a later run's reply on the same thread.
1026
+ const long = "x".repeat(45_000);
1027
+ yield* Ref.set(thread.reply, long);
1028
+ yield* Ref.set(thread.laterReply, "Someone else asked a follow-up.");
1029
+ yield* Ref.set(thread.status, "completed");
1030
+ yield* Deferred.succeed(thread.finished, undefined);
1031
+ const task = yield* taskResult(a, taskId);
1032
+ expect(task?.status).toBe("completed");
1033
+ expect(task?.result).toBe(long);
1034
+ // Every wait was for the run the launch started.
1035
+ const waits = yield* Ref.get(thread.waitedFor);
1036
+ expect(waits.length).toBeGreaterThan(0);
1037
+ expect(waits.every((runId) => runId === boxRunId)).toBe(true);
1038
+ }),
1039
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1040
+);
1041
+
1042
+it.effect("a task whose thread there waits on its own task ends with the answer after it", () =>
1043
+ Effect.scoped(
1044
+ Effect.gen(function* () {
1045
+ const thread = yield* makeBoxThread;
1046
+ const b = yield* serveBox(thread);
1047
+ const offers = yield* SubscriptionRef.make<
1048
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1049
+ >([]);
1050
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1051
+ const a = yield* makeLaptop(database, offers);
1052
+ yield* linkTo(a.links, b, "full-access");
1053
+ yield* seedParent(a);
1054
+ const delegated = yield* delegateToBox(a);
1055
+
1056
+ // The task's run there ends after delegating a review of its own.
1057
+ yield* Ref.set(thread.nested, true);
1058
+ yield* Ref.set(thread.reply, "Started a review; I will answer when it reports.");
1059
+ yield* Ref.set(thread.status, "completed");
1060
+ yield* Deferred.succeed(thread.finished, undefined);
1061
+ const first = yield* Effect.raceFirst(
1062
+ Deferred.await(thread.nestedWaiting).pipe(Effect.as("waiting there" as const)),
1063
+ taskResult(a, delegated.taskId).pipe(Effect.as("completed here" as const)),
1064
+ );
1065
+ expect(first).toBe("waiting there");
1066
+
1067
+ // The review reports and wakes the thread there, whose next run answers.
1068
+ yield* Ref.set(thread.laterReply, "The review found two issues; both are fixed.");
1069
+ yield* Deferred.succeed(thread.nestedSettled, undefined);
1070
+ expect(yield* taskResult(a, delegated.taskId)).toMatchObject({
1071
+ status: "completed",
1072
+ result: "The review found two issues; both are fixed.",
1073
+ });
1074
+ }),
1075
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1076
+);
1077
+
1078
+it.effect("the same key from another provider session is another task", () =>
1079
+ Effect.scoped(
1080
+ Effect.gen(function* () {
1081
+ const thread = yield* makeBoxThread;
1082
+ const b = yield* serveBox(thread);
1083
+ const offers = yield* SubscriptionRef.make<
1084
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1085
+ >([]);
1086
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1087
+ const a = yield* makeLaptop(database, offers);
1088
+ yield* linkTo(a.links, b, "full-access");
1089
+ yield* seedParent(a);
1090
+
1091
+ const first = yield* delegateToBox(a);
1092
+ const later = yield* a.call(
1093
+ "delegate_task",
1094
+ {
1095
+ task: "Run the full suite on the box.",
1096
+ target: { environmentId: box.environmentId },
1097
+ clientRequestId: "suite-on-box",
1098
+ },
1099
+ { ...parentScope, requestNamespace: "provider-session:laptop-parent-2" },
1100
+ );
1101
+ expect(later.isError, JSON.stringify(later.content)).toBe(false);
1102
+ const second = later.structuredContent as {
1103
+ taskId: NodeId;
1104
+ remoteChild: { threadId: ThreadId };
1105
+ };
1106
+ expect(second.taskId).not.toBe(first.taskId);
1107
+ expect(second.remoteChild.threadId).not.toBe(first.remoteChild.threadId);
1108
+ expect((yield* a.orchestrator.getThreadProjection(parentThreadId)).subagents).toHaveLength(2);
1109
+ }),
1110
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1111
+);
1112
+
1113
+it.effect.each([null, "Working before the provider failed."])(
1114
+ "reports the failed remote run's error instead of its earlier reply (%s)",
1115
+ (reply) =>
1116
+ Effect.scoped(
1117
+ Effect.gen(function* () {
1118
+ const thread = yield* makeBoxThread;
1119
+ const b = yield* serveBox(thread);
1120
+ const offers = yield* SubscriptionRef.make<
1121
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1122
+ >([]);
1123
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1124
+ const a = yield* makeLaptop(database, offers);
1125
+ yield* linkTo(a.links, b, "full-access");
1126
+ yield* seedParent(a);
1127
+ const delegated = yield* delegateToBox(a);
1128
+ yield* Ref.set(thread.reply, reply);
1129
+ const error = "Provider failed: authentication expired on the destination.";
1130
+ yield* Ref.set(thread.error, error);
1131
+ yield* Ref.set(thread.status, "failed");
1132
+ yield* Deferred.succeed(thread.finished, undefined);
1133
+ expect(yield* taskResult(a, delegated.taskId)).toMatchObject({
1134
+ status: "failed",
1135
+ result: error,
1136
+ });
1137
+ const status = yield* a.call("task_status", { taskId: delegated.taskId });
1138
+ expect(status.structuredContent).toMatchObject({
1139
+ status: "failed",
1140
+ summary: error,
1141
+ latestTerminalSummary: error,
1142
+ });
1143
+ const offered = yield* SubscriptionRef.changes(offers).pipe(
1144
+ Stream.filter((seen) => seen.some((offer) => offer.threadId === parentThreadId)),
1145
+ Stream.runHead,
1146
+ );
1147
+ expect(Option.isSome(offered)).toBe(true);
1148
+ }),
1149
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1150
+);
1151
+
1152
+it.effect.each([false, true])(
1153
+ "ignores later-run errors and reads the failed run's full error (ownError=%s)",
1154
+ (ownError) =>
1155
+ Effect.scoped(
1156
+ Effect.gen(function* () {
1157
+ const thread = yield* makeBoxThread;
1158
+ const b = yield* serveBox(thread);
1159
+ const offers = yield* SubscriptionRef.make<
1160
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1161
+ >([]);
1162
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1163
+ const a = yield* makeLaptop(database, offers);
1164
+ yield* linkTo(a.links, b, "full-access");
1165
+ yield* seedParent(a);
1166
+ const delegated = yield* delegateToBox(a);
1167
+ yield* Ref.set(thread.reply, null);
1168
+ const error = `Provider failed: ${"detail ".repeat(10_000)}end of error.`;
1169
+ if (ownError) yield* Ref.set(thread.error, error);
1170
+ yield* Ref.set(thread.laterReply, "A later user run answered.");
1171
+ yield* Ref.set(thread.laterError, "Another run's provider error.");
1172
+ yield* Ref.set(thread.status, "failed");
1173
+ yield* Deferred.succeed(thread.finished, undefined);
1174
+ expect(yield* taskResult(a, delegated.taskId)).toMatchObject({
1175
+ status: "failed",
1176
+ result: ownError
1177
+ ? error
1178
+ : "(The thread in the linked environment ended without a reply.)",
1179
+ });
1180
+ expect(yield* Ref.get(thread.waitedFor)).toEqual([boxRunId]);
1181
+ }),
1182
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1183
+);
1184
+
1185
+it.effect("keeps a successful remote reply despite an error item in the run's activity", () =>
1186
+ Effect.scoped(
1187
+ Effect.gen(function* () {
1188
+ const thread = yield* makeBoxThread;
1189
+ const b = yield* serveBox(thread);
1190
+ const offers = yield* SubscriptionRef.make<
1191
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1192
+ >([]);
1193
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1194
+ const a = yield* makeLaptop(database, offers);
1195
+ yield* linkTo(a.links, b, "full-access");
1196
+ yield* seedParent(a);
1197
+ const delegated = yield* delegateToBox(a);
1198
+ yield* Ref.set(thread.reply, "Recovered and completed the task.");
1199
+ yield* Ref.set(thread.error, "A recoverable tool error.");
1200
+ yield* Ref.set(thread.status, "completed");
1201
+ yield* Deferred.succeed(thread.finished, undefined);
1202
+ expect(yield* taskResult(a, delegated.taskId)).toMatchObject({
1203
+ status: "completed",
1204
+ result: "Recovered and completed the task.",
1205
+ });
1206
+ }),
1207
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1208
+);
1209
+
1210
+it.effect("fails the task when its thread there is gone, or the link here is", () =>
1211
+ Effect.scoped(
1212
+ Effect.gen(function* () {
1213
+ const thread = yield* makeBoxThread;
1214
+ const b = yield* serveBox(thread);
1215
+ const offers = yield* SubscriptionRef.make<
1216
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1217
+ >([]);
1218
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1219
+ const a = yield* makeLaptop(database, offers);
1220
+ yield* linkTo(a.links, b, "full-access");
1221
+ yield* seedParent(a);
1222
+
1223
+ yield* Ref.set(thread.gone, true);
1224
+ const gone = yield* delegateToBox(a);
1225
+ const failed = yield* taskResult(a, gone.taskId);
1226
+ expect(failed?.status).toBe("failed");
1227
+ expect(failed?.result).toContain("was not found");
1228
+
1229
+ // The link is forgotten here while the task runs there.
1230
+ yield* Ref.set(thread.gone, false);
1231
+ const forgotten = yield* a
1232
+ .call("delegate_task", {
1233
+ task: "Another one.",
1234
+ target: { environmentId: box.environmentId },
1235
+ clientRequestId: "forgotten",
1236
+ })
1237
+ .pipe(Effect.map((result) => result.structuredContent as { taskId: NodeId }));
1238
+ yield* a.links.unlink(box.environmentId);
1239
+ yield* Ref.set(thread.status, "completed");
1240
+ yield* Deferred.succeed(thread.finished, undefined);
1241
+ const unlinked = yield* taskResult(a, forgotten.taskId);
1242
+ expect(unlinked?.status).toBe("failed");
1243
+ expect(unlinked?.result).toContain("not linked to");
1244
+ }),
1245
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1246
+);
1247
+
1248
+it.effect("cancel ends the task here even when the link is gone", () =>
1249
+ Effect.scoped(
1250
+ Effect.gen(function* () {
1251
+ const thread = yield* makeBoxThread;
1252
+ const b = yield* serveBox(thread);
1253
+ const offers = yield* SubscriptionRef.make<
1254
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1255
+ >([]);
1256
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1257
+ const a = yield* makeLaptop(database, offers);
1258
+ yield* linkTo(a.links, b, "full-access");
1259
+ yield* seedParent(a);
1260
+
1261
+ const delegated = yield* delegateToBox(a);
1262
+ yield* a.links.unlink(box.environmentId);
1263
+ const cancel = yield* a.call("task_cancel", { taskId: delegated.taskId });
1264
+ expect(cancel.structuredContent).toEqual({
1265
+ taskId: delegated.taskId,
1266
+ status: "cancel_requested",
1267
+ });
1268
+ const task = yield* taskResult(a, delegated.taskId);
1269
+ expect(task?.status).toBe("cancelled");
1270
+ expect(task?.result).toContain("could not be stopped in Box");
1271
+ expect(yield* Ref.get(thread.interrupted)).toBe(0);
1272
+ }),
1273
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1274
+);
1275
+
1276
+it.effect("a parent stopped while the task's result is read still stops its thread there", () =>
1277
+ Effect.scoped(
1278
+ Effect.gen(function* () {
1279
+ const thread = yield* makeBoxThread;
1280
+ const b = yield* serveBox(thread);
1281
+ const offers = yield* SubscriptionRef.make<
1282
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1283
+ >([]);
1284
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1285
+ const a = yield* makeLaptop(database, offers);
1286
+ yield* linkTo(a.links, b, "full-access");
1287
+ yield* seedParent(a);
1288
+ const delegated = yield* delegateToBox(a);
1289
+
1290
+ // The task's run ends there, and while the follower reads its reply,
1291
+ // the parent here is stopped: more work may follow that run there.
1292
+ yield* Ref.set(thread.holdRead, true);
1293
+ yield* Ref.set(thread.reply, "Done there.");
1294
+ yield* Ref.set(thread.status, "completed");
1295
+ yield* Deferred.succeed(thread.finished, undefined);
1296
+ yield* Deferred.await(thread.readStarted);
1297
+ yield* a.threads.stopDelegatedTasks({
1298
+ threadId: parentThreadId,
1299
+ commandId: CommandId.make("command:stop:laptop-parent-mid-read"),
1300
+ });
1301
+ yield* Deferred.succeed(thread.releaseRead, undefined);
1302
+
1303
+ // The Stop's result stands, and the thread there is still stopped.
1304
+ expect(yield* taskResult(a, delegated.taskId)).toMatchObject({ status: "interrupted" });
1305
+ yield* Deferred.await(thread.interruptedOnce);
1306
+ expect(yield* Ref.get(thread.stops)).toContain("thread.stop");
1307
+ }),
1308
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1309
+);
1310
+
1311
+it.effect("a stop the box refuses because the parent was lowered ends instead of retrying", () =>
1312
+ Effect.scoped(
1313
+ Effect.gen(function* () {
1314
+ const thread = yield* makeBoxThread;
1315
+ const b = yield* serveBox(thread);
1316
+ const offers = yield* SubscriptionRef.make<
1317
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1318
+ >([]);
1319
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1320
+ const a = yield* makeLaptop(database, offers);
1321
+ yield* linkTo(a.links, b, "full-access");
1322
+ yield* seedParent(a);
1323
+ const delegated = yield* delegateToBox(a);
1324
+
1325
+ // The parent is lowered below the full-access thread there, then stopped.
1326
+ yield* a.orchestrator.dispatch({
1327
+ type: "thread.runtime-mode.set",
1328
+ commandId: CommandId.make("command:lower:laptop-parent"),
1329
+ threadId: parentThreadId,
1330
+ runtimeMode: "approval-required",
1331
+ });
1332
+ yield* a.threads.stopDelegatedTasks({
1333
+ threadId: parentThreadId,
1334
+ commandId: CommandId.make("command:stop:laptop-parent-lowered"),
1335
+ });
1336
+
1337
+ // The box refuses that stop; the follower records it as settled and
1338
+ // stops, so nothing retries it, now or after a restart.
1339
+ const settled = yield* a.orchestrator
1340
+ .streamStoredEventsFrom({
1341
+ threadId: parentThreadId,
1342
+ afterSequence: 0,
1343
+ eventType: "subagent.updated",
1344
+ })
1345
+ .pipe(
1346
+ Stream.filter(
1347
+ (stored) =>
1348
+ stored.event.type === "subagent.updated" &&
1349
+ stored.event.payload.id === delegated.taskId &&
1350
+ stored.event.payload.remoteChild?.stoppedThere === true,
1351
+ ),
1352
+ Stream.runHead,
1353
+ );
1354
+ expect(Option.isSome(settled)).toBe(true);
1355
+ expect(yield* Ref.get(thread.stops)).toEqual([]);
1356
+ expect(yield* a.projections.getOpenRemoteDelegatedTasks).toEqual([]);
1357
+ }),
1358
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1359
+);
1360
+
1361
+it.effect("stopping the parent stops its task there", () =>
1362
+ Effect.scoped(
1363
+ Effect.gen(function* () {
1364
+ const thread = yield* makeBoxThread;
1365
+ const b = yield* serveBox(thread);
1366
+ const offers = yield* SubscriptionRef.make<
1367
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1368
+ >([]);
1369
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1370
+ const a = yield* makeLaptop(database, offers);
1371
+ yield* linkTo(a.links, b, "full-access");
1372
+ yield* seedParent(a);
1373
+
1374
+ const delegated = yield* delegateToBox(a);
1375
+ // What the delegated-tasks.stop effect runs once the parent's Stop commits.
1376
+ yield* a.threads.stopDelegatedTasks({
1377
+ threadId: parentThreadId,
1378
+ commandId: CommandId.make("command:stop:laptop-parent"),
1379
+ reason: "User stopped",
1380
+ });
1381
+ expect(yield* taskResult(a, delegated.taskId)).toMatchObject({
1382
+ status: "interrupted",
1383
+ result: "Stopped with its parent: User stopped",
1384
+ });
1385
+ // The follower sees it ended here and stops it there.
1386
+ yield* Deferred.await(thread.interruptedOnce);
1387
+ expect(yield* Ref.get(thread.interrupted)).toBe(1);
1388
+ }),
1389
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1390
+);
1391
+
1392
+/** A follower retry schedule the test steps: each failed attempt is offered, then waits for `retry`. */
1393
+const steppedRetries = Effect.gen(function* () {
1394
+ const failed = yield* Queue.unbounded<void>();
1395
+ const retry = yield* Queue.unbounded<void>();
1396
+ const schedule = Schedule.forever.pipe(
1397
+ Schedule.tap(() => Queue.offer(failed, undefined).pipe(Effect.andThen(Queue.take(retry)))),
1398
+ );
1399
+ return { failed, retry, schedule };
1400
+});
1401
+
1402
+/** Waits until the task here records that the `stopCount`th Stop after its result reached there. */
1403
+const stoppedThere = (
1404
+ laptopEnv: Effect.Success<ReturnType<typeof makeLaptop>>,
1405
+ taskId: NodeId,
1406
+ // `null` for a cancel's stop, which carries no count.
1407
+ stopCount: number | null = 1,
1408
+) =>
1409
+ laptopEnv.orchestrator
1410
+ .streamStoredEventsFrom({
1411
+ threadId: parentThreadId,
1412
+ afterSequence: 0,
1413
+ eventType: "subagent.updated",
1414
+ })
1415
+ .pipe(
1416
+ Stream.filter(
1417
+ (stored) =>
1418
+ stored.event.type === "subagent.updated" &&
1419
+ stored.event.payload.id === taskId &&
1420
+ stored.event.payload.remoteChild?.stoppedThere === true &&
1421
+ stored.event.payload.remoteChild.stopCount === (stopCount ?? undefined),
1422
+ ),
1423
+ Stream.runHead,
1424
+ Effect.map((stored) =>
1425
+ Option.isSome(stored) && stored.value.event.type === "subagent.updated"
1426
+ ? stored.value.event.payload
1427
+ : undefined,
1428
+ ),
1429
+ );
1430
+
1431
+it.effect("stopping the parent stops follow-up work on a task there that has its result", () =>
1432
+ Effect.scoped(
1433
+ Effect.gen(function* () {
1434
+ const thread = yield* makeBoxThread;
1435
+ const b = yield* serveBox(thread);
1436
+ const offers = yield* SubscriptionRef.make<
1437
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1438
+ >([]);
1439
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1440
+ const a = yield* makeLaptop(database, offers);
1441
+ yield* a.remote.start();
1442
+ yield* linkTo(a.links, b, "full-access");
1443
+ yield* seedParent(a);
1444
+ const delegated = yield* delegateToBox(a);
1445
+ yield* Ref.set(thread.reply, "All green.");
1446
+ yield* Ref.set(thread.status, "completed");
1447
+ yield* Deferred.succeed(thread.finished, undefined);
1448
+ expect(yield* taskResult(a, delegated.taskId)).toMatchObject({
1449
+ status: "completed",
1450
+ result: "All green.",
1451
+ });
1452
+
1453
+ // The parent sends the thread there a follow-up, which starts a run there.
1454
+ const sent = yield* a.call("t3_thread_send", {
1455
+ environmentId: box.environmentId,
1456
+ threadId: delegated.remoteChild.threadId,
1457
+ message: "Now run the slow suite too.",
1458
+ });
1459
+ expect(sent.isError, JSON.stringify(sent.content)).toBe(false);
1460
+ expect(yield* Ref.get(thread.sent)).toEqual(["Now run the slow suite too."]);
1461
+ expect(yield* Ref.get(thread.interrupted)).toBe(0);
1462
+
1463
+ yield* a.threads.stopDelegatedTasks({
1464
+ threadId: parentThreadId,
1465
+ commandId: CommandId.make("command:stop:laptop-parent-after-result"),
1466
+ });
1467
+ // The thread there is stopped as Stop does, and the task keeps its result.
1468
+ const task = yield* stoppedThere(a, delegated.taskId);
1469
+ expect(yield* Ref.get(thread.stops)).toEqual(["thread.stop", "delegated-tasks"]);
1470
+ expect(task).toMatchObject({ status: "completed", result: "All green." });
1471
+ expect(yield* a.projections.getOpenRemoteDelegatedTasks).toEqual([]);
1472
+
1473
+ // A second Stop owes a second stop there, not a replay of the first.
1474
+ yield* a.threads.stopDelegatedTasks({
1475
+ threadId: parentThreadId,
1476
+ commandId: CommandId.make("command:stop:laptop-parent-again"),
1477
+ });
1478
+ expect(yield* stoppedThere(a, delegated.taskId, 2)).toMatchObject({ status: "completed" });
1479
+ expect(yield* Ref.get(thread.interrupted)).toBe(2);
1480
+ }),
1481
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1482
+);
1483
+
1484
+it.effect("a delayed Stop acknowledgement leaves a newer Stop owed", () =>
1485
+ Effect.scoped(
1486
+ Effect.gen(function* () {
1487
+ const thread = yield* makeBoxThread;
1488
+ const b = yield* serveBox(thread);
1489
+ const offers = yield* SubscriptionRef.make<
1490
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1491
+ >([]);
1492
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1493
+ const a = yield* makeLaptop(database, offers);
1494
+ yield* a.remote.start();
1495
+ yield* linkTo(a.links, b, "full-access");
1496
+ yield* seedParent(a);
1497
+ const delegated = yield* delegateToBox(a);
1498
+ yield* Ref.set(thread.reply, "All green.");
1499
+ yield* Ref.set(thread.status, "completed");
1500
+ yield* Deferred.succeed(thread.finished, undefined);
1501
+ yield* taskResult(a, delegated.taskId);
1502
+
1503
+ yield* Ref.set(thread.holdFirstStop, true);
1504
+ yield* a.threads.stopDelegatedTasks({
1505
+ threadId: parentThreadId,
1506
+ commandId: CommandId.make("command:stop:delayed-first"),
1507
+ });
1508
+ yield* Deferred.await(thread.stopStarted);
1509
+ // Work starts after the first Stop landed there, but before its acknowledgement returns.
1510
+ yield* a.call("t3_thread_send", {
1511
+ environmentId: box.environmentId,
1512
+ threadId: delegated.remoteChild.threadId,
1513
+ message: "Run another check.",
1514
+ });
1515
+ yield* a.threads.stopDelegatedTasks({
1516
+ threadId: parentThreadId,
1517
+ commandId: CommandId.make("command:stop:delayed-second"),
1518
+ });
1519
+ const pending = yield* a.threads.getThreadRecords(parentThreadId, ["subagents"]);
1520
+ expect(
1521
+ pending.subagents.find((task) => task.id === delegated.taskId)?.remoteChild,
1522
+ ).toMatchObject({ stoppedThere: false, stopCount: 2 });
1523
+ yield* Deferred.succeed(thread.releaseStop, undefined);
1524
+ expect(yield* stoppedThere(a, delegated.taskId, 2)).toMatchObject({
1525
+ status: "completed",
1526
+ result: "All green.",
1527
+ });
1528
+ expect(yield* Ref.get(thread.interrupted)).toBe(2);
1529
+ expect(yield* a.projections.getOpenRemoteDelegatedTasks).toEqual([]);
1530
+ }),
1531
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1532
+);
1533
+
1534
+it.effect("a Stop on a task that has its result reaches there after a restart", () =>
1535
+ Effect.scoped(
1536
+ Effect.gen(function* () {
1537
+ const thread = yield* makeBoxThread;
1538
+ const b = yield* serveBox(thread);
1539
+ const offers = yield* SubscriptionRef.make<
1540
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1541
+ >([]);
1542
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1543
+ const linking = yield* layerLinkingEnvironment(laptop).pipe(Layer.build);
1544
+ // The laptop records the Stop, then goes away before its follower sends it.
1545
+ const delegated = yield* Effect.scoped(
1546
+ Effect.gen(function* () {
1547
+ const before = yield* makeLaptop(database, offers, linking);
1548
+ yield* linkTo(before.links, b, "full-access");
1549
+ yield* seedParent(before);
1550
+ const task = yield* delegateToBox(before);
1551
+ yield* Ref.set(thread.status, "completed");
1552
+ yield* Deferred.succeed(thread.finished, undefined);
1553
+ yield* taskResult(before, task.taskId);
1554
+ yield* before.threads.stopDelegatedTasks({
1555
+ threadId: parentThreadId,
1556
+ commandId: CommandId.make("command:stop:laptop-parent-before-restart"),
1557
+ });
1558
+ return task;
1559
+ }),
1560
+ );
1561
+ expect(yield* Ref.get(thread.interrupted)).toBe(0);
1562
+
1563
+ const after = yield* makeLaptop(database, offers, linking);
1564
+ expect(yield* after.projections.getOpenRemoteDelegatedTasks).toEqual([
1565
+ { parentThreadId, taskId: delegated.taskId },
1566
+ ]);
1567
+ yield* after.remote.start();
1568
+ expect(yield* stoppedThere(after, delegated.taskId)).toMatchObject({ status: "completed" });
1569
+ expect(yield* Ref.get(thread.stops)).toEqual(["thread.stop", "delegated-tasks"]);
1570
+ }),
1571
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1572
+);
1573
+
1574
+it.effect("a parent stopped while the box is unreachable still stops its task there", () =>
1575
+ Effect.scoped(
1576
+ Effect.gen(function* () {
1577
+ const thread = yield* makeBoxThread;
1578
+ const b = yield* serveBox(thread);
1579
+ const offers = yield* SubscriptionRef.make<
1580
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1581
+ >([]);
1582
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1583
+ const retries = yield* steppedRetries;
1584
+ const a = yield* makeLaptop(database, offers).pipe(
1585
+ Effect.provideService(RemoteDelegation.FollowRetrySchedule, retries.schedule),
1586
+ );
1587
+ yield* linkTo(a.links, b, "full-access");
1588
+ yield* seedParent(a);
1589
+ // The box sleeps as soon as the task is there, so its follower's first attempt fails.
1590
+ yield* Ref.set(
1591
+ thread.afterLaunch,
1592
+ Ref.set(b.descriptor, descriptorOf("environment-elsewhere", "Elsewhere")),
1593
+ );
1594
+ const delegated = yield* delegateToBox(a);
1595
+ yield* Queue.take(retries.failed);
1596
+ // The parent is stopped meanwhile.
1597
+ yield* a.threads.stopDelegatedTasks({
1598
+ threadId: parentThreadId,
1599
+ commandId: CommandId.make("command:stop:laptop-parent-offline"),
1600
+ });
1601
+ expect(yield* taskResult(a, delegated.taskId)).toMatchObject({ status: "interrupted" });
1602
+
1603
+ // Once the box is back, the follower's next attempt stops the task there.
1604
+ yield* Ref.set(b.descriptor, box);
1605
+ yield* Queue.offer(retries.retry, undefined);
1606
+ yield* Deferred.await(thread.interruptedOnce);
1607
+ expect(yield* Ref.get(thread.interrupted)).toBe(1);
1608
+ }),
1609
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1610
+);
1611
+
1612
+it.effect("a task cancelled while the box is unreachable is stopped there after a restart", () =>
1613
+ Effect.scoped(
1614
+ Effect.gen(function* () {
1615
+ const thread = yield* makeBoxThread;
1616
+ const b = yield* serveBox(thread);
1617
+ const offers = yield* SubscriptionRef.make<
1618
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1619
+ >([]);
1620
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1621
+ // Its links outlive the restart, so the box knows it as the same link session.
1622
+ const linking = yield* layerLinkingEnvironment(laptop).pipe(Layer.build);
1623
+ // The laptop cancels while the box sleeps, then restarts before it wakes.
1624
+ const delegated = yield* Effect.scoped(
1625
+ Effect.gen(function* () {
1626
+ const before = yield* makeLaptop(database, offers, linking);
1627
+ yield* linkTo(before.links, b, "full-access");
1628
+ yield* seedParent(before);
1629
+ const task = yield* delegateToBox(before);
1630
+ yield* Ref.set(b.descriptor, descriptorOf("environment-elsewhere", "Elsewhere"));
1631
+ yield* before.call("task_cancel", { taskId: task.taskId });
1632
+ expect(yield* taskResult(before, task.taskId)).toMatchObject({ status: "cancelled" });
1633
+ return task;
1634
+ }),
1635
+ );
1636
+ expect(yield* Ref.get(thread.interrupted)).toBe(0);
1637
+
1638
+ yield* Ref.set(b.descriptor, box);
1639
+ const after = yield* makeLaptop(database, offers, linking);
1640
+ yield* after.remote.start();
1641
+ yield* Deferred.await(thread.interruptedOnce);
1642
+ // Once the stop is recorded, nothing is owed there any more.
1643
+ yield* stoppedThere(after, delegated.taskId, null);
1644
+ expect(yield* after.projections.getOpenRemoteDelegatedTasks).toEqual([]);
1645
+ expect(yield* Ref.get(thread.stops)).toEqual(["thread.stop", "delegated-tasks"]);
1646
+ // The result here is still the cancel's.
1647
+ expect(yield* taskResult(after, delegated.taskId)).toMatchObject({ status: "cancelled" });
1648
+ }),
1649
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1650
+);
1651
+
1652
+it.effect("a task whose thread there has no run ends with its last reply", () =>
1653
+ Effect.scoped(
1654
+ Effect.gen(function* () {
1655
+ const thread = yield* makeBoxThread;
1656
+ const b = yield* serveBox(thread);
1657
+ const offers = yield* SubscriptionRef.make<
1658
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1659
+ >([]);
1660
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1661
+ const a = yield* makeLaptop(database, offers);
1662
+ yield* linkTo(a.links, b, "full-access");
1663
+ yield* seedParent(a);
1664
+ // As a task recorded before its run was kept, whose thread there is idle.
1665
+ yield* Ref.set(thread.runless, true);
1666
+ yield* Ref.set(thread.reply, "Done before it was followed.");
1667
+
1668
+ const delegated = yield* delegateToBox(a);
1669
+ expect(yield* taskResult(a, delegated.taskId)).toMatchObject({
1670
+ status: "completed",
1671
+ result: "Done before it was followed.",
1672
+ });
1673
+ // One look, not a loop.
1674
+ expect(yield* Ref.get(thread.waitedFor)).toEqual([undefined]);
1675
+ }),
1676
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1677
+);
1678
+
1679
+it.effect("a local task runs in this thread's project", () =>
1680
+ Effect.scoped(
1681
+ Effect.gen(function* () {
1682
+ const offers = yield* SubscriptionRef.make<
1683
+ ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
1684
+ >([]);
1685
+ const database = yield* SqlitePersistence.layerMemory.pipe(Layer.build);
1686
+ const a = yield* makeLaptop(database, offers);
1687
+ yield* seedParent(a);
1688
+
1689
+ const result = yield* a.call("delegate_task", {
1690
+ task: "Run it here.",
1691
+ target: { projectId: "project:elsewhere" },
1692
+ });
1693
+ expect(result.isError).toBe(true);
1694
+ expect(JSON.stringify(result.content)).toContain("invalid_request");
1695
+ }),
1696
+ ).pipe(Effect.provide(NodeHttpServer.layerTest)),
1697
+);
apps/server/src/peer/RemoteDelegation.ts
new
+801
@@ -0,0 +1,801 @@
1
+import {
2
+ CommandId,
3
+ type EnvironmentId,
4
+ NodeId,
5
+ OrchestratorMcpFailure,
6
+ type OrchestratorMcpDelegateTaskInput,
7
+ type OrchestratorMcpTaskCancelResult,
8
+ type OrchestratorMcpThreadTimelineItem,
9
+ type OrchestrationV2RemoteTaskChild,
10
+ type OrchestrationV2Subagent,
11
+ type ProjectId,
12
+ type ProviderInstanceId,
13
+ ProviderDriverKind,
14
+ type RunId,
15
+ type ThreadId,
16
+} from "@t3tools/contracts";
17
+import * as Context from "effect/Context";
18
+import * as Crypto from "effect/Crypto";
19
+import * as Duration from "effect/Duration";
20
+import * as Effect from "effect/Effect";
21
+import * as Layer from "effect/Layer";
22
+import * as Option from "effect/Option";
23
+import * as Schedule from "effect/Schedule";
24
+import * as Scope from "effect/Scope";
25
+import * as Stream from "effect/Stream";
26
+import type * as Tool from "effect/ai/Tool";
27
+
28
+import type * as McpInvocationContext from "../mcp/McpInvocationContext.ts";
29
+import { ProjectToolkit } from "../mcp/toolkits/project/tools.ts";
30
+import {
31
+ resolveInteractionMode,
32
+ resolveRuntimeMode,
33
+ taskPrompt,
34
+} from "../mcp/delegatedTaskModes.ts";
35
+import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts";
36
+import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts";
37
+import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
38
+import * as ProjectService from "../project/ProjectService.ts";
39
+import * as RepositoryIdentityResolver from "../project/RepositoryIdentityResolver.ts";
40
+import { forkParked } from "../serverActivation.ts";
41
+import * as PeerForwarding from "./PeerForwarding.ts";
42
+import * as PeerLinks from "./PeerLinks.ts";
43
+
44
+/** How long one follow of a remote task waits on its thread there before checking again. */
45
+const FOLLOW_WAIT_MS = 10 * 60 * 1_000;
46
+/** A linked environment that stops answering is retried, backing off to this. */
47
+const FOLLOW_MAX_BACKOFF = Duration.minutes(5);
48
+/** How a follower retries; tests step it by hand. */
49
+export const FollowRetrySchedule = Context.Reference<Schedule.Schedule<unknown>>(
50
+ "t3/peer/RemoteDelegation/FollowRetrySchedule",
51
+ {
52
+ defaultValue: () =>
53
+ Schedule.exponential(Duration.seconds(2)).pipe(
54
+ Schedule.modifyDelay(({ duration }) =>
55
+ Effect.succeed(Duration.min(duration, FOLLOW_MAX_BACKOFF)),
56
+ ),
57
+ ),
58
+ },
59
+);
60
+
61
+type ThreadScope = McpInvocationContext.McpThreadInvocationScope;
62
+
63
+/**
64
+ * `delegate_task` to a linked environment. The task's child is an ordinary
65
+ * thread there, launched through the link; the parent here records the task
66
+ * like a local one, without a child thread, and a follower completes it when
67
+ * the thread there ends, so the parent wakes as it would for a local child.
68
+ */
69
+export class RemoteDelegation extends Context.Service<
70
+ RemoteDelegation,
71
+ {
72
+ readonly delegate: (
73
+ scope: ThreadScope,
74
+ input: OrchestratorMcpDelegateTaskInput & {
75
+ readonly target: NonNullable<OrchestratorMcpDelegateTaskInput["target"]> & {
76
+ readonly environmentId: EnvironmentId;
77
+ };
78
+ },
79
+ ) => Effect.Effect<{ readonly taskId: NodeId }, OrchestratorMcpFailure>;
80
+ /**
81
+ * Stops the task's thread there, then completes it here as cancelled. A
82
+ * task that already has its result keeps it; its thread there is still
83
+ * stopped, as cancelling a local task stops follow-up work on its child.
84
+ */
85
+ readonly cancel: (
86
+ scope: ThreadScope,
87
+ task: OrchestrationV2Subagent,
88
+ input: {
89
+ readonly reason?: string | undefined;
90
+ readonly clientRequestId?: string | undefined;
91
+ },
92
+ ) => Effect.Effect<OrchestratorMcpTaskCancelResult, OrchestratorMcpFailure>;
93
+ /**
94
+ * Follows every open remote task until it ends, including after a
95
+ * restart, and a finished one again when a Stop here owes it a stop there.
96
+ */
97
+ readonly start: () => Effect.Effect<void, never, Scope.Scope>;
98
+ }
99
+>()("t3/peer/RemoteDelegation") {}
100
+
101
+/** The other side refused because the thread there runs above this caller's modes. */
102
+const isModeRefusal = (error: OrchestratorMcpFailure) =>
103
+ error.code === "runtime_mode_escalation_denied" ||
104
+ error.code === "interaction_mode_escalation_denied";
105
+
106
+/**
107
+ * Refusals that following again cannot change: the link was revoked, expired
108
+ * or forgotten, or the thread or run there is gone. Anything else (the other
109
+ * machine asleep, a dropped route) is worth retrying.
110
+ */
111
+const isFinal = (error: OrchestratorMcpFailure) =>
112
+ error.code === "capability_denied" ||
113
+ error.code === "thread_not_found" ||
114
+ error.code === "run_not_found";
115
+
116
+const make = Effect.gen(function* () {
117
+ const followRetry = yield* FollowRetrySchedule;
118
+ const forwarding = yield* PeerForwarding.PeerForwarding;
119
+ const links = yield* PeerLinks.PeerLinks;
120
+ const threads = yield* ThreadManagement.ThreadManagementService;
121
+ const projections = yield* ProjectionStore.ProjectionStoreV2;
122
+ const projects = yield* ProjectService.ProjectService;
123
+ const repositoryIdentities = yield* RepositoryIdentityResolver.RepositoryIdentityResolver;
124
+ const crypto = yield* Crypto.Crypto;
125
+ const hereId = yield* ServerEnvironment.ServerEnvironment.pipe(
126
+ Effect.flatMap((environment) => environment.getEnvironmentId),
127
+ );
128
+ // Followers live as long as this service, so shutting down stops them.
129
+ const followers = yield* Scope.Scope;
130
+
131
+ // One follower runs per open task and holds what it read across a wait of
132
+ // up to FOLLOW_WAIT_MS, so it reads its own task, never the parent's whole
133
+ // task list: a parent with thousands of tasks made every restart decode
134
+ // that list once per open task at the same time and ran out of heap.
135
+ const readTask = (parentThreadId: ThreadId, taskId: NodeId) =>
136
+ threads
137
+ .getThreadRecords(parentThreadId, ["subagents"], { subagentIds: [taskId] })
138
+ .pipe(Effect.map(({ thread, subagents }) => ({ thread, task: subagents[0] })));
139
+
140
+ /** The peer's project with this thread's repository, or the one the caller named. */
141
+ const resolveRemoteProject = Effect.fn("RemoteDelegation.resolveRemoteProject")(function* (
142
+ scope: ThreadScope,
143
+ environmentId: EnvironmentId,
144
+ parentProjectId: ProjectId,
145
+ requested: ProjectId | undefined,
146
+ ) {
147
+ if (requested !== undefined) return requested;
148
+ const here = yield* projects.getById(parentProjectId).pipe(
149
+ Effect.map(Option.getOrUndefined),
150
+ Effect.orElseSucceed(() => undefined),
151
+ );
152
+ // The project's own identity is a one-minute cache that reads blank when
153
+ // cold, so resolve it here, as the other side's t3_project_list does.
154
+ const key =
155
+ here === undefined
156
+ ? undefined
157
+ : (yield* repositoryIdentities.resolve(here.workspaceRoot))?.canonicalKey;
158
+ if (key === undefined) {
159
+ return yield* new OrchestratorMcpFailure({
160
+ code: "target_required",
161
+ message: "Pass target.projectId: this thread's project has no repository to match there.",
162
+ });
163
+ }
164
+ const matches: Array<{ readonly id: ProjectId; readonly title: string }> = [];
165
+ let cursor: number | null = 0;
166
+ while (cursor !== null) {
167
+ const listed: Tool.Success<typeof ProjectToolkit.tools.t3_project_list> =
168
+ yield* forwarding.call(scope, ProjectToolkit.tools.t3_project_list, environmentId, {
169
+ cursor,
170
+ limit: 100,
171
+ });
172
+ matches.push(
173
+ ...listed.projects.filter((project) => project.repositoryIdentity?.canonicalKey === key),
174
+ );
175
+ cursor = listed.nextCursor;
176
+ }
177
+ if (matches.length === 1) return matches[0]!.id;
178
+ return yield* new OrchestratorMcpFailure({
179
+ code: "invalid_request",
180
+ message:
181
+ matches.length === 0
182
+ ? `No project there has this repository (${key}). Pass target.projectId; t3_project_list with this environmentId lists them. To bring the repository there, use t3_project_clone and then t3_project_create with this environmentId.`
183
+ : `Several projects there have this repository: ${matches.map((project) => `${project.title} (${project.id})`).join(", ")}. Pass target.projectId.`,
184
+ });
185
+ });
186
+
187
+ const delegate: RemoteDelegation["Service"]["delegate"] = Effect.fn("RemoteDelegation.delegate")(
188
+ function* (scope, input) {
189
+ const parent = yield* threads.getThreadRecords(scope.thread.threadId, ["runs"]).pipe(
190
+ Effect.mapError(
191
+ () =>
192
+ new OrchestratorMcpFailure({
193
+ code: "thread_not_found",
194
+ message: "The calling thread was not found.",
195
+ }),
196
+ ),
197
+ );
198
+ const parentRun = parent.runs
199
+ .filter(ThreadManagement.isActiveRun)
200
+ .toSorted((left, right) => right.ordinal - left.ordinal)[0];
201
+ if (
202
+ parentRun === undefined ||
203
+ parentRun.rootNodeId === null ||
204
+ parentRun.providerInstanceId !== scope.thread.providerInstanceId
205
+ ) {
206
+ return yield* new OrchestratorMcpFailure({
207
+ code: "parent_not_active",
208
+ message: "Delegated tasks require an active run owned by this MCP provider session.",
209
+ });
210
+ }
211
+ const parentNodeId = parentRun.rootNodeId;
212
+ const { target } = input;
213
+ // A worktree there would branch from a commit this checkout has and the
214
+ // other may not, so a remote task runs in that project's checkout.
215
+ if (input.isolation === "worktree") {
216
+ return yield* new OrchestratorMcpFailure({
217
+ code: "invalid_request",
218
+ message:
219
+ 'A task in a linked environment runs in that project\'s checkout; isolation "worktree" is not supported there. Omit isolation, or use t3_thread_launch with environmentId and a worktree workspaceStrategy.',
220
+ });
221
+ }
222
+ // The provider and model inherit as they do for a task here. Another
223
+ // provider there has no model to inherit, so the caller names one.
224
+ const inherited = parent.thread.modelSelection;
225
+ const instanceId = target.providerInstanceId ?? inherited.instanceId;
226
+ const model =
227
+ target.model ?? (instanceId === inherited.instanceId ? inherited.model : undefined);
228
+ if (model === undefined) {
229
+ return yield* new OrchestratorMcpFailure({
230
+ code: "target_required",
231
+ message: "Pass target.model from orchestrator_capabilities with this environmentId.",
232
+ });
233
+ }
234
+ const options =
235
+ target.options ??
236
+ (instanceId === inherited.instanceId && model === inherited.model
237
+ ? inherited.options
238
+ : undefined);
239
+ // Modes asked for are checked against this thread. Omitted ones are left
240
+ // to the other side, which inherits this thread's modes capped by the
241
+ // link's access, so a narrower link still takes the task.
242
+ const runtimeMode =
243
+ input.runtimeMode === undefined || input.runtimeMode === "inherit"
244
+ ? undefined
245
+ : yield* resolveRuntimeMode(parent.thread.runtimeMode, input.runtimeMode);
246
+ const interactionMode =
247
+ input.interactionMode === undefined || input.interactionMode === "inherit"
248
+ ? undefined
249
+ : yield* resolveInteractionMode(parent.thread.interactionMode, input.interactionMode);
250
+ const projectId = yield* resolveRemoteProject(
251
+ scope,
252
+ target.environmentId,
253
+ parent.thread.projectId,
254
+ target.projectId,
255
+ );
256
+ // One key for the launch there and the record here, so a retry finds both.
257
+ // Both are scoped to the provider session, as every key a caller passes is:
258
+ // the forwarder scopes the launch's, and the record's names it.
259
+ const key = input.clientRequestId ?? (yield* crypto.randomUUIDv4().pipe(Effect.orDie));
260
+ const task = taskPrompt(input);
261
+ const launched = yield* forwarding.call(
262
+ scope,
263
+ ProjectToolkit.tools.t3_thread_launch,
264
+ target.environmentId,
265
+ {
266
+ projectId,
267
+ title: input.title ?? parent.thread.title,
268
+ modelSelection: { instanceId, model, ...(options === undefined ? {} : { options }) },
269
+ ...(runtimeMode === undefined ? {} : { runtimeMode }),
270
+ ...(interactionMode === undefined ? {} : { interactionMode }),
271
+ message: task,
272
+ clientRequestId: `delegate:${scope.thread.threadId}:${key}`,
273
+ // The thread there shows it is this thread's subagent, with a way back.
274
+ delegatedFrom: {
275
+ environmentId: hereId,
276
+ threadId: parent.thread.id,
277
+ title: parent.thread.title,
278
+ },
279
+ },
280
+ );
281
+ const link = yield* links.get(target.environmentId).pipe(
282
+ Effect.map(Option.getOrUndefined),
283
+ Effect.orElseSucceed(() => undefined),
284
+ );
285
+ const commandId = CommandId.make(
286
+ `command:mcp:${encodeURIComponent(scope.requestNamespace)}:remote-delegate:${encodeURIComponent(key)}`,
287
+ );
288
+ const remoteChild: OrchestrationV2RemoteTaskChild = {
289
+ environmentId: target.environmentId,
290
+ threadId: launched.threadId,
291
+ label: link?.label ?? target.environmentId,
292
+ ...(launched.runId === null ? {} : { runId: launched.runId }),
293
+ };
294
+ const recorded = yield* threads
295
+ .dispatch({
296
+ type: "delegated_task.remote.request",
297
+ commandId,
298
+ parentThreadId: scope.thread.threadId,
299
+ parentRunId: parentRun.id,
300
+ parentNodeId,
301
+ task,
302
+ ...(input.title === undefined ? {} : { title: input.title }),
303
+ // The driver runs there; this side only labels the task with it.
304
+ driver: ProviderDriverKind.make("remote"),
305
+ modelSelection: launched.modelSelection,
306
+ remoteChild,
307
+ completionWake: input.mode === "wait" ? "settled_only" : "always",
308
+ })
309
+ .pipe(
310
+ // The cause goes to the log; the caller learns only that recording failed.
311
+ Effect.tapError((cause) =>
312
+ Effect.logWarning("remote-delegation.record-failed", {
313
+ parentThreadId: scope.thread.threadId,
314
+ cause,
315
+ }),
316
+ ),
317
+ Effect.mapError(
318
+ () =>
319
+ new OrchestratorMcpFailure({
320
+ code: "orchestration_error",
321
+ message: "Unable to record the delegated task.",
322
+ }),
323
+ ),
324
+ // Nothing here follows a thread the task was never recorded for, so stop it there.
325
+ // A crash between the launch and this record still leaves it running there
326
+ // until a retry with the same clientRequestId records it.
327
+ Effect.tapError(() =>
328
+ stopThere(followScope(scope.thread, remoteChild), remoteChild, "stop").pipe(
329
+ Effect.ignoreCause({ log: true }),
330
+ ),
331
+ ),
332
+ );
333
+ const taskEvent = recorded.storedEvents.find(
334
+ (stored) => stored.event.type === "subagent.updated",
335
+ );
336
+ const taskId =
337
+ taskEvent?.event.type === "subagent.updated"
338
+ ? taskEvent.event.payload.id
339
+ : // A replayed request recorded the task the first time.
340
+ yield* threads.getThreadRecords(scope.thread.threadId, ["subagents"]).pipe(
341
+ Effect.map(
342
+ ({ subagents }) =>
343
+ subagents.find((task) => task.remoteChild?.threadId === launched.threadId)?.id,
344
+ ),
345
+ Effect.orElseSucceed(() => undefined),
346
+ );
347
+ if (taskId === undefined) {
348
+ return yield* new OrchestratorMcpFailure({
349
+ code: "orchestration_error",
350
+ message: "The delegated task was not recorded.",
351
+ });
352
+ }
353
+ yield* followOne(scope.thread.threadId, taskId).pipe(Effect.forkIn(followers));
354
+ return { taskId };
355
+ },
356
+ );
357
+
358
+ /**
359
+ * Completes `task` here with its thread there's final state. Each attempt is its own
360
+ * command, so a failed one never blocks the next; a report refused because the task already
361
+ * has its result (a cancel, a Stop or an earlier report) is done. `stoppedThere` records that
362
+ * nothing is left to stop there, even on a task that already has its result.
363
+ */
364
+ const complete = Effect.fn("RemoteDelegation.complete")(function* (
365
+ parentThreadId: ThreadId,
366
+ taskId: NodeId,
367
+ status: "completed" | "failed" | "cancelled" | "interrupted",
368
+ result: string,
369
+ stoppedThere: "ran-out" | "stopped" | undefined,
370
+ stopCount?: number,
371
+ ) {
372
+ const attempt = yield* crypto.randomUUIDv4().pipe(Effect.orDie);
373
+ yield* threads
374
+ .dispatch({
375
+ type: "delegated_task.remote.complete",
376
+ commandId: CommandId.make(`command:remote-task-complete:${taskId}:${attempt}`),
377
+ parentThreadId,
378
+ taskId,
379
+ status,
380
+ result,
381
+ ...(stoppedThere === undefined ? {} : { stoppedThere }),
382
+ ...(stopCount === undefined ? {} : { stopCount }),
383
+ })
384
+ .pipe(
385
+ Effect.catch((error) =>
386
+ readTask(parentThreadId, taskId).pipe(
387
+ Effect.flatMap(({ task }) => (task?.result != null ? Effect.void : Effect.fail(error))),
388
+ ),
389
+ ),
390
+ );
391
+ });
392
+
393
+ /**
394
+ * How this environment reaches a task's thread there: as the parent
395
+ * thread, under one namespace per parent, so a stop sent again after a
396
+ * restart or a dropped route is recorded there once.
397
+ */
398
+ const followScope = (
399
+ parent: { readonly threadId: ThreadId; readonly providerInstanceId: ProviderInstanceId },
400
+ remote: OrchestrationV2RemoteTaskChild,
401
+ ): ThreadScope => ({
402
+ environmentId: hereId,
403
+ requestNamespace: `remote-task:${parent.threadId}`,
404
+ thread: {
405
+ threadId: parent.threadId,
406
+ providerSessionId: `remote-task:${remote.threadId}`,
407
+ providerInstanceId: parent.providerInstanceId,
408
+ },
409
+ client: undefined,
410
+ capabilities: new Set(["orchestration"]),
411
+ issuedAt: 0,
412
+ });
413
+
414
+ /**
415
+ * Stops the task's own thread there as its Stop button does: its running turn, queued
416
+ * messages, pull request watches and delegated tasks. `key` names the stop (the follower
417
+ * sends one, each cancel its own), and each is recorded there once however often it is sent.
418
+ */
419
+ const stopThere = (
420
+ scope: ThreadScope,
421
+ remote: OrchestrationV2RemoteTaskChild,
422
+ key: string,
423
+ reason?: string,
424
+ ) =>
425
+ forwarding
426
+ .interruptThread(scope, remote.environmentId, {
427
+ threadId: remote.threadId,
428
+ stop: true,
429
+ ...(reason === undefined ? {} : { reason }),
430
+ clientRequestId: `${key}:${remote.threadId}`,
431
+ })
432
+ .pipe(Effect.asVoid);
433
+
434
+ /**
435
+ * The last reply `runId` gave on the task's thread there, which is its
436
+ * result, read whole however long it is. A failed run prefers its error
437
+ * from the activity view over an earlier reply, without taking another run's.
438
+ */
439
+ const lastReply = Effect.fn("RemoteDelegation.lastReply")(function* (
440
+ scope: ThreadScope,
441
+ remote: OrchestrationV2RemoteTaskChild,
442
+ runId: RunId | null,
443
+ failed = false,
444
+ ) {
445
+ let reply: OrchestratorMcpThreadTimelineItem | undefined;
446
+ let error: OrchestratorMcpThreadTimelineItem | undefined;
447
+ let afterPosition: number | undefined;
448
+ while (true) {
449
+ const read = yield* forwarding.readThread(scope, remote.environmentId, {
450
+ threadId: remote.threadId,
451
+ view: failed ? "activity" : "messages",
452
+ limit: 100,
453
+ ...(afterPosition === undefined ? {} : { afterPosition }),
454
+ });
455
+ reply =
456
+ read.items.findLast(
457
+ (item) => item.type === "assistant_message" && (runId === null || item.runId === runId),
458
+ ) ?? reply;
459
+ if (failed) {
460
+ error =
461
+ read.items.findLast(
462
+ (item) => item.type === "error" && (runId === null || item.runId === runId),
463
+ ) ?? error;
464
+ }
465
+ if (!read.hasMore || read.nextPosition === null) break;
466
+ afterPosition = read.nextPosition;
467
+ }
468
+ reply = error ?? reply;
469
+ if (reply === undefined) return undefined;
470
+ let text = reply.text ?? "";
471
+ let textOffset = reply.textTruncated ? (reply.nextTextOffset ?? null) : null;
472
+ while (textOffset !== null) {
473
+ const rest = yield* forwarding.readThread(scope, remote.environmentId, {
474
+ threadId: remote.threadId,
475
+ itemId: reply.itemId,
476
+ textOffset,
477
+ maxCharsPerItem: 50_000,
478
+ });
479
+ const part = rest.items[0];
480
+ if (part === undefined) break;
481
+ text += part.text ?? "";
482
+ textOffset = part.textTruncated ? (part.nextTextOffset ?? null) : null;
483
+ }
484
+ return text;
485
+ });
486
+
487
+ /**
488
+ * Why following a task can never succeed, if that is what `error` means.
489
+ * The far side's message already says what was refused and what to do; a
490
+ * link forgotten here only reads as a bad request, so it is named.
491
+ */
492
+ const finalReason = Effect.fn("RemoteDelegation.finalReason")(
493
+ function* (parentThreadId: ThreadId, taskId: NodeId, error: OrchestratorMcpFailure) {
494
+ if (isFinal(error)) return error.message;
495
+ if (error.code !== "invalid_request") return undefined;
496
+ const { task } = yield* readTask(parentThreadId, taskId);
497
+ const environmentId = task?.remoteChild?.environmentId;
498
+ if (environmentId === undefined) return error.message;
499
+ const link = yield* links.get(environmentId);
500
+ return Option.isSome(link) ? undefined : error.message;
501
+ },
502
+ Effect.orElseSucceed(() => undefined),
503
+ );
504
+
505
+ /** A task's thread there that ended without a reply. */
506
+ const noReply = "(The thread in the linked environment ended without a reply.)";
507
+
508
+ /**
509
+ * Waits for the task's run there to end, completes the task here, and stops it there if it
510
+ * ended here first. A revoked, expired or forgotten link, or a thread or run gone there,
511
+ * fails the task with nothing left to stop; anything else (the other machine asleep, a
512
+ * dropped route) is retried with back-off, and so is completing.
513
+ */
514
+ const follow = (parentThreadId: ThreadId, taskId: NodeId): Effect.Effect<void> =>
515
+ followOnce(parentThreadId, taskId).pipe(
516
+ // `false` means it is still running there: follow again straight away.
517
+ Effect.repeat({ while: (done) => !done }),
518
+ Effect.catchTags({
519
+ OrchestratorMcpFailure: Effect.fn("RemoteDelegation.followFailed")(function* (error) {
520
+ const reason = yield* finalReason(parentThreadId, taskId, error);
521
+ if (reason === undefined) return yield* error;
522
+ // Gone there, or no link to reach it by: nothing left to stop there.
523
+ const { task } = yield* readTask(parentThreadId, taskId);
524
+ const stopCount = task?.remoteChild?.stopCount;
525
+ yield* complete(parentThreadId, taskId, "failed", reason, "stopped", stopCount);
526
+ }),
527
+ }),
528
+ Effect.retry(followRetry),
529
+ Effect.ignoreCause({ log: true }),
530
+ );
531
+
532
+ /**
533
+ * One wait on the task's thread there; true once the task here is done.
534
+ * A task completed here first (cancelled, or its parent stopped) is
535
+ * stopped there, and done once that stop is recorded here.
536
+ */
537
+ const followOnce = Effect.fn("RemoteDelegation.followOnce")(function* (
538
+ parentThreadId: ThreadId,
539
+ taskId: NodeId,
540
+ ) {
541
+ const sequence = yield* threads.getThreadEventSequence(parentThreadId);
542
+ const { thread, task } = yield* readTask(parentThreadId, taskId);
543
+ if (task?.remoteChild === undefined) return true;
544
+ const remote = task.remoteChild;
545
+ const scope = followScope(
546
+ { threadId: parentThreadId, providerInstanceId: thread.providerInstanceId },
547
+ remote,
548
+ );
549
+ // Ended here, maybe while this follower backed off from an unreachable
550
+ // machine or before a restart: it still has to be stopped there. So
551
+ // does one its parent here was stopped after, for what followed there.
552
+ if (task.result !== null) {
553
+ if (
554
+ remote.stoppedThere === false ||
555
+ ((task.status === "cancelled" || task.status === "interrupted") &&
556
+ remote.stoppedThere !== true)
557
+ ) {
558
+ const key = remote.stopCount === undefined ? "stop" : `stop-${remote.stopCount}`;
559
+ yield* stopThere(scope, remote, key).pipe(
560
+ // Its thread there now runs above what this side may touch, say
561
+ // because the parent here was lowered since; no retry changes that.
562
+ Effect.catchIf(isModeRefusal, (error) =>
563
+ Effect.logWarning("A linked environment refused to stop a delegated task", {
564
+ taskId,
565
+ reason: error.message,
566
+ }),
567
+ ),
568
+ );
569
+ yield* complete(
570
+ parentThreadId,
571
+ taskId,
572
+ terminalStatus(task.status),
573
+ task.result,
574
+ "stopped",
575
+ remote.stopCount,
576
+ );
577
+ return yield* settled(parentThreadId, taskId);
578
+ }
579
+ return true;
580
+ }
581
+ const endedHere = threads
582
+ .streamStoredEventsFrom({
583
+ threadId: parentThreadId,
584
+ afterSequence: sequence,
585
+ eventType: "subagent.updated",
586
+ })
587
+ .pipe(
588
+ Stream.filter(
589
+ (stored) =>
590
+ stored.event.type === "subagent.updated" &&
591
+ stored.event.payload.id === taskId &&
592
+ stored.event.payload.result !== null,
593
+ ),
594
+ Stream.runHead,
595
+ Effect.flatMap((ended) =>
596
+ Option.isSome(ended) ? Effect.succeed({ endedHere: true } as const) : Effect.never,
597
+ ),
598
+ );
599
+ const waited = yield* forwarding
600
+ .waitForThread(scope, remote.environmentId, {
601
+ threadId: remote.threadId,
602
+ ...(remote.runId === undefined ? {} : { runId: remote.runId }),
603
+ timeoutMs: FOLLOW_WAIT_MS,
604
+ // A thread there whose run ended may still be waiting on its own
605
+ // tasks to wake it for the answer, which a task here waits for too.
606
+ // An older peer ignores this and reports the run alone.
607
+ untilDelegatedWorkSettled: true,
608
+ })
609
+ .pipe(Effect.raceFirst(endedHere));
610
+ // The next look reads the result and stops it there.
611
+ if ("endedHere" in waited) return false;
612
+ if (waited.timedOut) return false;
613
+ // A task recorded without its run waits on the thread's latest; a
614
+ // thread there with none has nothing left to wait for.
615
+ if (waited.runId === null) {
616
+ const reply = yield* lastReply(scope, remote, null);
617
+ yield* complete(
618
+ parentThreadId,
619
+ taskId,
620
+ reply === undefined ? "failed" : "completed",
621
+ reply ?? "The thread in the linked environment has no run to follow.",
622
+ "ran-out",
623
+ );
624
+ return yield* settled(parentThreadId, taskId);
625
+ }
626
+ if (!isTerminal(waited.status)) return false;
627
+ const resultRun = waited.resultRun ?? {
628
+ runId: remote.runId ?? waited.runId,
629
+ status: waited.status,
630
+ };
631
+ const result = yield* lastReply(scope, remote, resultRun.runId, resultRun.status === "failed");
632
+ yield* complete(
633
+ parentThreadId,
634
+ taskId,
635
+ terminalStatus(resultRun.status),
636
+ result ?? noReply,
637
+ "ran-out",
638
+ );
639
+ return yield* settled(parentThreadId, taskId);
640
+ });
641
+
642
+ /**
643
+ * Whether the task is done here after the follower reported its run ran
644
+ * out there. A cancel or Stop that landed while the reply was read keeps
645
+ * its result, and still owes a stop there for what may follow the run;
646
+ * the next look sends it.
647
+ */
648
+ const settled = (parentThreadId: ThreadId, taskId: NodeId) =>
649
+ readTask(parentThreadId, taskId).pipe(
650
+ Effect.map(({ task }) => task?.remoteChild?.stoppedThere === true),
651
+ );
652
+
653
+ const following = new Map<NodeId, { again: boolean }>();
654
+
655
+ /**
656
+ * `follow`, at most once per task. Asked again while it runs, say by a
657
+ * Stop here on a task that already has its result, it looks once more
658
+ * before it ends, so that stop is not missed.
659
+ */
660
+ const followOne = (parentThreadId: ThreadId, taskId: NodeId) =>
661
+ Effect.suspend(() => {
662
+ const running = following.get(taskId);
663
+ if (running !== undefined) {
664
+ running.again = true;
665
+ return Effect.void;
666
+ }
667
+ const state = { again: false };
668
+ following.set(taskId, state);
669
+ return follow(parentThreadId, taskId).pipe(
670
+ // Checked and released in one step, so a request between them is never lost.
671
+ Effect.repeat({
672
+ while: () => {
673
+ if (state.again) {
674
+ state.again = false;
675
+ return true;
676
+ }
677
+ following.delete(taskId);
678
+ return false;
679
+ },
680
+ }),
681
+ Effect.ensuring(
682
+ Effect.sync(() => {
683
+ if (following.get(taskId) === state) following.delete(taskId);
684
+ }),
685
+ ),
686
+ );
687
+ });
688
+
689
+ const cancel: RemoteDelegation["Service"]["cancel"] = Effect.fn("RemoteDelegation.cancel")(
690
+ function* (scope, task, input) {
691
+ const remote = task.remoteChild;
692
+ if (remote === undefined) {
693
+ return yield* new OrchestratorMcpFailure({
694
+ code: "task_not_found",
695
+ message: `Delegated task ${task.id} is not remote.`,
696
+ });
697
+ }
698
+ const { reason } = input;
699
+ const there = followScope(scope.thread, remote);
700
+ // A later cancel stops what started there since; a retry of this one, nothing new.
701
+ const key = `cancel:${encodeURIComponent(scope.requestNamespace)}:${
702
+ input.clientRequestId ?? (yield* crypto.randomUUIDv4().pipe(Effect.orDie))
703
+ }`;
704
+ if (task.result !== null) {
705
+ // Best effort: the result stands whether or not the stop gets there.
706
+ yield* stopThere(there, remote, key, reason).pipe(
707
+ Effect.andThen(
708
+ complete(
709
+ task.threadId,
710
+ task.id,
711
+ terminalStatus(task.status),
712
+ task.result,
713
+ "stopped",
714
+ remote.stopCount,
715
+ ),
716
+ ),
717
+ Effect.ignoreCause({ log: true }),
718
+ );
719
+ return {
720
+ taskId: task.id,
721
+ status:
722
+ task.status === "completed" || task.status === "failed" || task.status === "interrupted"
723
+ ? task.status
724
+ : "cancelled",
725
+ } satisfies OrchestratorMcpTaskCancelResult;
726
+ }
727
+ // A link that is gone or a machine that is down still cancels the task
728
+ // here; its follower keeps trying to stop it there, across restarts.
729
+ const unstopped = yield* stopThere(there, remote, key, reason).pipe(
730
+ Effect.as(undefined),
731
+ Effect.catch((error) => Effect.succeed(error.message)),
732
+ );
733
+ const cancelled = reason === undefined ? "Cancelled." : `Cancelled: ${reason}`;
734
+ yield* complete(
735
+ task.threadId,
736
+ task.id,
737
+ "cancelled",
738
+ unstopped === undefined
739
+ ? cancelled
740
+ : `${cancelled} It could not be stopped in ${remote.label} and may still run there: ${unstopped}`,
741
+ unstopped === undefined ? "stopped" : undefined,
742
+ remote.stopCount,
743
+ ).pipe(
744
+ Effect.tapError((cause) =>
745
+ Effect.logWarning("remote-delegation.cancel-record-failed", { taskId: task.id, cause }),
746
+ ),
747
+ Effect.mapError(
748
+ () =>
749
+ new OrchestratorMcpFailure({
750
+ code: "orchestration_error",
751
+ message: "Unable to record the cancellation.",
752
+ }),
753
+ ),
754
+ );
755
+ return {
756
+ taskId: task.id,
757
+ status: "cancel_requested",
758
+ } satisfies OrchestratorMcpTaskCancelResult;
759
+ },
760
+ );
761
+
762
+ const start: RemoteDelegation["Service"]["start"] = () =>
763
+ forkParked(
764
+ Effect.gen(function* () {
765
+ // A finished task's follower has ended, so a Stop here that owes its
766
+ // thread there a stop starts it again. Started before the scan below;
767
+ // a Stop that slips between the two stays owed for the next start.
768
+ yield* Stream.runForEach(threads.streamDomainEvents, (event) =>
769
+ event.type === "subagent.updated" && event.payload.remoteChild?.stoppedThere === false
770
+ ? followOne(event.threadId, event.payload.id).pipe(Effect.forkIn(followers))
771
+ : Effect.void,
772
+ ).pipe(
773
+ Effect.ignoreCause({ log: true }),
774
+ Effect.forkIn(followers, { startImmediately: true }),
775
+ );
776
+ const open = yield* projections.getOpenRemoteDelegatedTasks;
777
+ yield* Effect.forEach(
778
+ open,
779
+ ({ parentThreadId, taskId }) => followOne(parentThreadId, taskId),
780
+ {
781
+ concurrency: "unbounded",
782
+ discard: true,
783
+ },
784
+ );
785
+ }).pipe(Effect.ignoreCause({ log: true })),
786
+ );
787
+
788
+ return RemoteDelegation.of({ delegate, cancel, start });
789
+});
790
+
791
+const isTerminal = (status: string) =>
792
+ status === "completed" ||
793
+ status === "failed" ||
794
+ status === "cancelled" ||
795
+ status === "interrupted" ||
796
+ status === "rolled_back";
797
+
798
+const terminalStatus = (status: string): "completed" | "failed" | "cancelled" | "interrupted" =>
799
+ status === "completed" || status === "failed" || status === "interrupted" ? status : "cancelled";
800
+
801
+export const layer = Layer.effect(RemoteDelegation, make);
apps/server/src/project/ProjectEnrichmentService.ts
+10
@@ -50,6 +50,9 @@ export class ProjectEnrichmentService extends Context.Service<
50
readonly peek: (workspaceRoot: string) => Effect.Effect<ProjectEnrichment>;
51
readonly request: (workspaceRoot: string) => Effect.Effect<void>;
52
readonly getAvailable: (workspaceRoot: string) => Effect.Effect<ProjectEnrichment>;
53
+ readonly readRepositoryIdentity: (
54
+ workspaceRoot: string,
55
+ ) => Effect.Effect<RepositoryIdentity | null>;
56
readonly invalidate: (workspaceRoots: Iterable<string>) => Effect.Effect<void>;
57
readonly subscribeChanges: Effect.Effect<
58
PubSub.Subscription<ProjectEnrichmentChange>,
@@ -271,6 +274,12 @@ export const make = Effect.fn("ProjectEnrichmentService.make")(function* (
274
return available;
275
});
276
277
+ const readRepositoryIdentity: ProjectEnrichmentService["Service"]["readRepositoryIdentity"] =
278
+ Effect.fn("ProjectEnrichmentService.readRepositoryIdentity")(function* (workspaceRoot) {
279
+ const resolved = yield* Cache.get(repositoryIdentityCache, workspaceRoot);
280
+ return Exit.isSuccess(resolved) ? resolved.value : null;
281
+ });
282
+
283
const invalidate: ProjectEnrichmentService["Service"]["invalidate"] = Effect.fn(
284
"ProjectEnrichmentService.invalidate",
285
)(function* (workspaceRoots) {
@@ -294,6 +303,7 @@ export const make = Effect.fn("ProjectEnrichmentService.make")(function* (
303
peek,
304
request,
305
getAvailable,
306
+ readRepositoryIdentity,
307
invalidate,
308
subscribeChanges: PubSub.subscribe(changes),
309
});
apps/server/src/project/ProjectService.ts
+29
@@ -132,6 +132,17 @@ export class ProjectService extends Context.Service<
132
options?: { readonly includeDeleted?: boolean },
133
) => Effect.Effect<Option.Option<Project>, ProjectOperationError>;
134
readonly snapshot: Effect.Effect<ProjectSnapshot, ProjectOperationError>;
135
+ /**
136
+ * A page of active projects in creation order, each with its repository
137
+ * identity resolved, so a caller can match projects by repository.
138
+ */
139
+ readonly listPage: (input: {
140
+ readonly cursor: number;
141
+ readonly limit: number;
142
+ }) => Effect.Effect<
143
+ { readonly projects: ReadonlyArray<Project>; readonly nextCursor: number | null },
144
+ ProjectOperationError
145
+ >;
146
readonly getShell: (
147
projectId: ProjectId,
148
) => Effect.Effect<Option.Option<OrchestrationProjectShell>, ProjectOperationError>;
@@ -557,6 +568,23 @@ export const make = Effect.gen(function* () {
568
} satisfies ProjectSnapshot;
569
});
570
571
+ const listPage: ProjectService["Service"]["listPage"] = Effect.fn("ProjectService.listPage")(
572
+ function* ({ cursor, limit }) {
573
+ const rows = (yield* snapshot).projects.filter((project) => project.deletedAt === null);
574
+ const projects = yield* Effect.forEach(
575
+ rows.slice(cursor, cursor + limit),
576
+ (project) =>
577
+ project.repositoryIdentity !== null
578
+ ? Effect.succeed(project)
579
+ : projectEnrichment
580
+ .readRepositoryIdentity(project.workspaceRoot)
581
+ .pipe(Effect.map((repositoryIdentity) => ({ ...project, repositoryIdentity }))),
582
+ { concurrency: 8 },
583
+ );
584
+ return { projects, nextCursor: cursor + limit < rows.length ? cursor + limit : null };
585
+ },
586
+ );
587
+
588
return ProjectService.of({
589
create,
590
bootstrap,
@@ -565,6 +593,7 @@ export const make = Effect.gen(function* () {
593
getById,
594
getByWorkspaceRoot,
595
snapshot,
596
+ listPage,
597
getShell,
598
listShells,
599
});
apps/server/src/provider/AgentContextBudget.test.ts
+2
@@ -23,6 +23,7 @@ import { ThreadLaunchService } from "../orchestration-v2/ThreadLaunchService.ts"
23
import { ThreadManagementService } from "../orchestration-v2/ThreadManagementService.ts";
24
import { ThreadSearch } from "../orchestration-v2/ThreadSearch.ts";
25
import { PeerForwarding } from "../peer/PeerForwarding.ts";
26
+import { RemoteDelegation } from "../peer/RemoteDelegation.ts";
27
import { PreviewManager } from "../preview/Manager.ts";
28
import { PreviewBrowser } from "../preview/PreviewBrowser.ts";
29
import { ManagedProjectFolders } from "../project/ManagedProjectFolders.ts";
@@ -58,6 +59,7 @@ const toolHandlerServices = Layer.mergeAll(
59
Layer.mock(ProviderAdapterRegistryV2)({}),
60
Layer.mock(ProviderRegistry)({}),
61
Layer.mock(PullRequestReviewGuideService)({}),
62
+ Layer.mock(RemoteDelegation)({}),
63
Layer.mock(ScheduledTaskService)({}),
64
Layer.mock(SecretRequests)({}),
65
ServerConfig.layerTest(process.cwd(), { prefix: "t3-agent-context-budget-" }),
apps/server/src/provider/agentContextBudget.json
+1
-1
@@ -1,5 +1,5 @@
1
{
2
"claudeSystemAppendBytes": 5086,
3
"codexAdditionalContextBytes": 5638,
4
- "mcpToolListJsonBytes": 44232
4
+ "mcpToolListJsonBytes": 44745
5
}
apps/server/src/relay/AgentAwarenessRelay.test.ts
+1
@@ -267,6 +267,7 @@ const makeTestRelay = Effect.fnUntraced(function* (
267
delete: unused,
268
getByWorkspaceRoot: unused,
269
snapshot: Effect.succeed({ projects: [] } as never),
270
+ listPage: unused,
271
getShell: unused,
272
listShells: unused,
273
getById: () =>
apps/server/src/server.ts
+7
@@ -68,6 +68,7 @@ import * as ProjectSettingsOverrideSweep from "./provider/ProjectSettingsOverrid
68
import * as TerminalManager from "./terminal/Manager.ts";
69
import * as McpHttpServer from "./mcp/McpHttpServer.ts";
70
import * as PeerForwarding from "./peer/PeerForwarding.ts";
71
+import * as RemoteDelegation from "./peer/RemoteDelegation.ts";
72
import * as PeerLinks from "./peer/PeerLinks.ts";
73
import * as PeerMcpClient from "./peer/PeerMcpClient.ts";
74
import * as McpSessionRegistry from "./mcp/McpSessionRegistry.ts";
@@ -730,10 +731,16 @@ const layerMakeRoutes = Layer.mergeAll(
731
Layer.provide(ProviderAdapterRegistry.layerFromProviderInstanceRegistry),
732
Layer.provide(McpOAuth.layerMcpClientAuthenticator),
733
),
734
+ // Follows delegated tasks running in linked environments, including after a restart.
735
+ Layer.effectDiscard(
736
+ RemoteDelegation.RemoteDelegation.pipe(Effect.flatMap((remote) => remote.start())),
737
+ ),
738
).pipe(
739
Layer.provide(
740
PullRequestReviewGuideService.layer.pipe(Layer.provide(PullRequestReviewGuides.layer)),
741
),
742
+ // delegate_task to a linked environment, from /mcp and the follower above.
743
+ Layer.provide(RemoteDelegation.layer.pipe(Layer.provide(ProjectionStoreV2.layer))),
744
// Share the service so HTTP/WS clients single-flight reads and invalidate each other's cached patches.
745
Layer.provide(layerPullRequestService),
746
// The same activity instance RunExecutionService reports to, by layer memoization.
apps/web/src/components/ChatView.tsx
+45
-8
@@ -138,6 +138,7 @@ import {
138
import { type LegendListRef } from "@legendapp/list/react";
139
import { useWorkspaceMutationRefresh } from "../hooks/useWorkspaceMutationRefresh";
140
import { DEFAULT_INTERACTION_MODE, type ChatMessage } from "../types";
141
+import { buildThreadRouteParams } from "../threadRoutes";
142
import { useTheme } from "../hooks/useTheme";
143
import { writeTextToClipboard } from "../hooks/useCopyToClipboard";
144
import { subscribeSnapShotComposerFocus } from "../lib/desktopSnapShot";
@@ -231,6 +232,7 @@ import { resolveProviderSkillsForCwd } from "@t3tools/client-runtime/providerSki
232
import { vcsEnvironment } from "../state/vcs";
233
import {
234
type EnvironmentPresentation,
235
+ useEnvironment,
236
useEnvironmentProviders,
237
useEnvironments,
238
usePrimaryEnvironment,
@@ -829,7 +831,47 @@ export default function ChatView(props: ChatViewProps) {
831
messages: serverProjection.messages,
832
parentSubagents: workflowOpeningParentProjection?.projection.subagents ?? null,
833
});
832
- const parentThreadLink =
834
+ // A linked environment's agent may have delegated this thread from there.
835
+ const delegatedFrom = activeThread?.delegatedFrom ?? null;
836
+ const delegatedFromEnvironment = useEnvironment(delegatedFrom?.environmentId ?? null);
837
+ const delegatedFromRef =
838
+ delegatedFrom === null
839
+ ? null
840
+ : scopeThreadRef(delegatedFrom.environmentId, delegatedFrom.threadId);
841
+ // The title it had at delegation, until this client sees the parent itself.
842
+ const delegatedFromThread = useQuietThreadShell(delegatedFromRef);
843
+ const parentThreadLink = (() => {
844
+ if (parentSubagentThreadRef !== null) {
845
+ return {
846
+ title: parentSubagentThread?.title ?? "Parent thread",
847
+ open: (): void => {
848
+ void navigate({
849
+ to: "/$environmentId/$threadId",
850
+ params: buildThreadRouteParams(parentSubagentThreadRef),
851
+ });
852
+ },
853
+ };
854
+ }
855
+ if (delegatedFrom === null || delegatedFromRef === null) return null;
856
+ const parentRef = delegatedFromRef;
857
+ return {
858
+ title: delegatedFromThread?.title ?? delegatedFrom.title,
859
+ environmentLabel: delegatedFromEnvironment?.label ?? activeThread?.linkOrigin?.label ?? "",
860
+ // Only an environment this client is connected to can open the parent.
861
+ ...(delegatedFromEnvironment === null
862
+ ? {}
863
+ : {
864
+ open: (): void => {
865
+ void navigate({
866
+ to: "/$environmentId/$threadId",
867
+ params: buildThreadRouteParams(parentRef),
868
+ });
869
+ },
870
+ }),
871
+ };
872
+ })();
873
+ // The header's breadcrumb opens a parent in this environment only.
874
+ const headerParentThreadLink =
875
parentSubagentThreadRef === null
876
? null
877
: {
@@ -2328,7 +2370,6 @@ export default function ChatView(props: ChatViewProps) {
2370
handleSwitchCheckoutToThread,
2371
handleSwitchCheckoutToThreadStable,
2372
isRestoringThreadBranch,
2331
- onOpenRelatedThread,
2373
onOpenRelatedThreadStable,
2374
sendStandaloneCommand,
2375
setBranchMismatchDismissTick,
@@ -3161,7 +3202,7 @@ export default function ChatView(props: ChatViewProps) {
3202
activeThreadTitle={activeThread.title}
3203
activeThreadLinkOrigin={activeThreadShell?.linkOrigin?.label ?? null}
3204
activeProject={activeProject ?? null}
3164
- parentThreadLink={parentThreadLink}
3205
+ parentThreadLink={headerParentThreadLink}
3206
onOpenThread={onOpenRelatedThreadStable}
3207
rightPanelOpen={inlineRightPanelOwnsTitleBar}
3208
onNewThreadInProject={handleNewThreadInActiveProjectStable}
@@ -3381,11 +3422,7 @@ export default function ChatView(props: ChatViewProps) {
3422
modelLabel={providerSubagentModelLabel}
3423
effortLabel={providerSubagentEffortLabel}
3424
status={providerSubagentStatus}
3384
- onOpenParent={
3385
- parentThreadLink
3386
- ? () => onOpenRelatedThread(parentThreadLink.threadId)
3387
- : null
3388
- }
3425
+ onOpenParent={parentThreadLink?.open ?? null}
3426
/>
3427
) : null}
3428
{!composerMounted ? null : (
apps/web/src/components/LegacySidebar.tsx
+15
-3
@@ -98,6 +98,7 @@ import { makeWorkspaceFileDropHandlers } from "./chat/workspaceFileDrop";
98
import {
99
readThreadShell,
100
useProjects,
101
+ useDelegatedUnderParent,
102
useThreadShells,
103
useThreadShellsForProjectRefs,
104
waitForProjectRemoval,
@@ -1124,6 +1125,7 @@ function useProjectThreads(project: SidebarProjectSnapshot) {
1125
(settings) => settings.sidebarThreadSortOrder,
1126
);
1127
const sidebarThreads = useThreadShellsForProjectRefs(project.memberProjectRefs);
1128
+ const delegatedUnderParent = useDelegatedUnderParent();
1129
const threadLastVisitedAts = useUiStateStore(
1130
useShallow((state) =>
1131
sidebarThreads.map(
@@ -1168,7 +1170,7 @@ function useProjectThreads(project: SidebarProjectSnapshot) {
1170
]),
1171
);
1172
const visibleProjectThreads = sortThreads(
1171
- filterSidebarV2VisibleThreads(sidebarThreads, null),
1173
+ filterSidebarV2VisibleThreads(sidebarThreads, null, delegatedUnderParent),
1174
threadSortOrder,
1175
);
1176
const projectStatus = resolveProjectStatusIndicator(
@@ -3121,6 +3123,7 @@ function useSortedLegacySidebarProjects(input: {
3123
sidebarProjectSortOrder,
3124
} = input;
3125
const sidebarThreads = useThreadShells();
3126
+ const delegatedUnderParent = useDelegatedUnderParent();
3127
const sidebarProjectByKey = new Map(
3128
sidebarProjects.map((project) => [project.projectKey, project] as const),
3129
);
@@ -3128,7 +3131,11 @@ function useSortedLegacySidebarProjects(input: {
3131
...project,
3132
id: project.projectKey,
3133
}));
3131
- const sortableThreads = filterSidebarV2VisibleThreads(sidebarThreads, null).map((thread) => {
3134
+ const sortableThreads = filterSidebarV2VisibleThreads(
3135
+ sidebarThreads,
3136
+ null,
3137
+ delegatedUnderParent,
3138
+ ).map((thread) => {
3139
const physicalKey =
3140
projectPhysicalKeyByScopedRef.get(
3141
scopedProjectKey(scopeProjectRef(thread.environmentId, thread.projectId)),
@@ -3171,6 +3178,7 @@ function useLegacySidebarThreads(input: {
3178
expandedThreadListsByProject,
3179
} = input;
3180
const sidebarThreads = useThreadShells();
3181
+ const delegatedUnderParent = useDelegatedUnderParent();
3182
const projectExpandedById = useUiStateStore((store) => store.projectExpandedById);
3183
const sidebarThreadByKey = new Map(
3184
sidebarThreads.map(
@@ -3201,7 +3209,11 @@ function useLegacySidebarThreads(input: {
3209
}
3210
const visibleSidebarThreadKeys = sortedProjects.flatMap((project) => {
3211
const projectThreads = sortThreads(
3204
- filterSidebarV2VisibleThreads(threadsByProjectKey.get(project.projectKey) ?? [], null),
3212
+ filterSidebarV2VisibleThreads(
3213
+ threadsByProjectKey.get(project.projectKey) ?? [],
3214
+ null,
3215
+ delegatedUnderParent,
3216
+ ),
3217
sidebarThreadSortOrder,
3218
);
3219
const projectExpanded = resolveProjectExpanded(
apps/web/src/components/Sidebar.logic.test.ts
+5
-1
@@ -854,7 +854,7 @@ describe("sortSidebarV2ProjectGroups", () => {
854
];
855
856
expect(
857
- sortSidebarV2ProjectGroups(projects, threads, "updated_at").map(
857
+ sortSidebarV2ProjectGroups(projects, threads, "updated_at", new Set()).map(
858
(project) => project.projectKey,
859
),
860
).toEqual(["logical-newer", "logical-older"]);
@@ -1306,6 +1306,7 @@ describe("resolveSidebarRouteReveal", () => {
1306
routeKey: hiddenKey,
1307
isSearching: false,
1308
scopedProjectKeys,
1309
+ delegatedUnderParent: new Set(),
1310
findThread,
1311
}),
1312
).toEqual({ pendingKey: hiddenKey, widensScope: true });
@@ -1319,6 +1320,7 @@ describe("resolveSidebarRouteReveal", () => {
1320
routeKey: hiddenKey,
1321
isSearching: false,
1322
scopedProjectKeys,
1323
+ delegatedUnderParent: new Set(),
1324
findThread,
1325
}),
1326
).toEqual({ pendingKey: null, widensScope: false });
@@ -1334,6 +1336,7 @@ describe("resolveSidebarRouteReveal", () => {
1336
routeKey,
1337
isSearching: false,
1338
scopedProjectKeys,
1339
+ delegatedUnderParent: new Set(),
1340
findThread,
1341
});
1342
resolve("environment-test:unlisted");
@@ -1347,6 +1350,7 @@ describe("resolveSidebarRouteReveal", () => {
1350
routeKey: hiddenKey,
1351
isSearching: true,
1352
scopedProjectKeys,
1353
+ delegatedUnderParent: new Set(),
1354
findThread,
1355
}),
1356
).toEqual({ pendingKey: hiddenKey, widensScope: false });
apps/web/src/components/Sidebar.logic.ts
+20
-6
@@ -1,4 +1,5 @@
1
import { resolveThreadWorkingStartedAt } from "@t3tools/client-runtime/state/models";
2
+import { isShownUnderParent } from "@t3tools/client-runtime/state/threads";
3
import { backgroundWorkHoldsCompletion } from "@t3tools/shared/orchestrationV2PendingBackgroundWork";
4
import { threadPullRequestSearchTerms } from "@t3tools/shared/threadPullRequests";
5
import * as React from "react";
@@ -580,16 +581,27 @@ export function resolveSidebarRowThreadId(
581
return thread?.id ?? threadId;
582
}
583
584
+/**
585
+ * `delegatedUnderParent` holds the tasks linked environments run for a thread
586
+ * the sidebar lists, by thread key; they show under that thread, as subagents do.
587
+ */
588
export function filterSidebarV2VisibleThreads<
584
- T extends Pick<SidebarThreadSummary, "archivedAt" | "lineage"> & {
585
- environmentId: string;
589
+ T extends Pick<SidebarThreadSummary, "archivedAt" | "environmentId" | "id" | "lineage"> & {
590
projectId: string;
591
},
588
->(threads: readonly T[], scopedProjectKeys: ReadonlySet<string> | null): T[] {
592
+>(
593
+ threads: readonly T[],
594
+ scopedProjectKeys: ReadonlySet<string> | null,
595
+ delegatedUnderParent: ReadonlySet<string>,
596
+): T[] {
597
return threads.filter(
598
(thread) =>
599
thread.archivedAt === null &&
592
- !isSidebarSubagentThread(thread) &&
600
+ !isShownUnderParent(
601
+ { environmentId: thread.environmentId, threadId: thread.id },
602
+ thread.lineage,
603
+ delegatedUnderParent,
604
+ ) &&
605
(scopedProjectKeys === null ||
606
scopedProjectKeys.has(`${thread.environmentId}:${thread.projectId}`)),
607
);
@@ -1299,15 +1311,17 @@ export function sortLogicalProjectsForSidebar<
1311
1312
export function sortSidebarV2ProjectGroups<
1313
TProject extends LogicalSidebarProject,
1302
- TThread extends ScopedSidebarThread & Pick<SidebarThreadSummary, "lineage">,
1314
+ TThread extends ScopedSidebarThread &
1315
+ Pick<SidebarThreadSummary, "environmentId" | "id" | "lineage">,
1316
>(
1317
projects: readonly TProject[],
1318
threads: readonly TThread[],
1319
sortOrder: SidebarProjectSortOrder,
1320
+ delegatedUnderParent: ReadonlySet<string>,
1321
): TProject[] {
1322
return sortLogicalProjectsForSidebar(
1323
projects,
1310
- filterSidebarV2VisibleThreads(threads, null),
1324
+ filterSidebarV2VisibleThreads(threads, null, delegatedUnderParent),
1325
sortOrder,
1326
);
1327
}
apps/web/src/components/Sidebar.tsx
+18
-2
@@ -127,6 +127,7 @@ import {
127
import {
128
readThreadShell,
129
useAllEnvironmentProjectSnapshotsReady,
130
+ useDelegatedUnderParent,
131
useProjects,
132
useServerConfigs,
133
useQuietThreadShells,
@@ -310,6 +311,8 @@ type SidebarOptimisticDrop = {
311
interface SidebarThreadPartitionInput {
312
readonly threads: readonly EnvironmentThreadShell[];
313
readonly scopedProjectKeys: ReadonlySet<string> | null;
314
+ /** Tasks linked environments run for a listed thread; they show under it. */
315
+ readonly delegatedUnderParent: ReadonlySet<string>;
316
readonly serverConfigs: ReadonlyMap<EnvironmentId, EnvironmentServerConfig>;
317
readonly optimisticDrop: SidebarOptimisticDrop | null;
318
readonly workingShelfEnabled: boolean;
@@ -371,6 +374,7 @@ function useSidebarThreads(input: {
374
readonly serverConfigs: ReadonlyMap<EnvironmentId, EnvironmentServerConfig>;
375
readonly optimisticDrop: SidebarOptimisticDrop | null;
376
readonly threads: readonly EnvironmentThreadShell[];
377
+ readonly delegatedUnderParent: ReadonlySet<string>;
378
readonly routeRowThreadKey: string | null;
379
}) {
380
const {
@@ -379,6 +383,7 @@ function useSidebarThreads(input: {
383
serverConfigs,
384
optimisticDrop,
385
threads,
386
+ delegatedUnderParent,
387
routeRowThreadKey,
388
} = input;
389
const workingShelfEnabled = useClientSettings((s) => s.sidebarWorkingShelfEnabled);
@@ -417,6 +422,7 @@ function useSidebarThreads(input: {
422
const partition = partitionSidebarThreads({
423
threads,
424
scopedProjectKeys,
425
+ delegatedUnderParent,
426
serverConfigs,
427
optimisticDrop,
428
workingShelfEnabled,
@@ -520,9 +526,16 @@ function useSidebarThreads(input: {
526
}
527
528
function partitionSidebarThreads(input: SidebarThreadPartitionInput) {
523
- const { threads, scopedProjectKeys, serverConfigs, optimisticDrop, workingShelfEnabled } = input;
529
+ const {
530
+ threads,
531
+ scopedProjectKeys,
532
+ delegatedUnderParent,
533
+ serverConfigs,
534
+ optimisticDrop,
535
+ workingShelfEnabled,
536
+ } = input;
537
const preciseNow = new Date().toISOString();
525
- const visible = filterSidebarV2VisibleThreads(threads, scopedProjectKeys);
538
+ const visible = filterSidebarV2VisibleThreads(threads, scopedProjectKeys, delegatedUnderParent);
539
const inboxObservation = inboxReturns.observe(workingShelfEnabled ? threads : null);
540
const pinned: EnvironmentThreadShell[] = [];
541
const active: EnvironmentThreadShell[] = [];
@@ -791,6 +804,7 @@ export default function Sidebar({ routeReveal }: { routeReveal: SidebarRouteReve
804
projectGroupByScopeKey,
805
projectScopeItems,
806
} = useSidebarLookups();
807
+ const delegatedUnderParent = useDelegatedUnderParent();
808
const router = useRouter();
809
const { isMobile, setOpenMobile } = useSidebar();
810
const keybindings = useAtomValue(primaryServerKeybindingsAtom);
@@ -996,6 +1010,7 @@ export default function Sidebar({ routeReveal }: { routeReveal: SidebarRouteReve
1010
routeKey: routeRowThreadKey,
1011
isSearching: isSearchingThreads,
1012
scopedProjectKeys: chosenScopeProjectKeys,
1013
+ delegatedUnderParent,
1014
findThread: (key) => threads.find((candidate) => threadShellKey(candidate) === key),
1015
});
1016
const projectScopeKey = revealWidensScope ? null : chosenProjectScopeKey;
@@ -1137,6 +1152,7 @@ export default function Sidebar({ routeReveal }: { routeReveal: SidebarRouteReve
1152
serverConfigs,
1153
optimisticDrop,
1154
threads,
1155
+ delegatedUnderParent,
1156
routeRowThreadKey,
1157
});
1158
apps/web/src/components/ThreadNotificationCoordinator.badge.browser.test.ts
+15
@@ -45,6 +45,19 @@ vi.mock(import("../state/presentation"), async (original) => {
45
},
46
};
47
});
48
+vi.mock(import("../state/threads"), async (original) => {
49
+ const actual = await original();
50
+ return {
51
+ ...actual,
52
+ environmentThreadShells: {
53
+ ...actual.environmentThreadShells,
54
+ pendingSubagentRequestsAtom: (() => noRequestsAtom) as never,
55
+ get delegatedUnderParentAtom() {
56
+ return noDelegatedAtom as never;
57
+ },
58
+ },
59
+ };
60
+});
61
vi.mock(import("../hooks/useSettings"), async (original) => ({
62
...(await original()),
63
subscribeClientSettings: ((listener: () => void) => {
@@ -68,6 +81,8 @@ import { startThreadNotifications } from "./ThreadNotificationCoordinator";
81
let registry: AtomRegistry.AtomRegistry;
82
const shellAtom = Atom.family((_id: string) => Atom.make<unknown>(null));
83
const environmentIdsAtom = Atom.make<ReadonlyArray<string>>([]);
84
+const noRequestsAtom = Atom.make(new Map());
85
+const noDelegatedAtom = Atom.make<ReadonlySet<string>>(new Set<string>());
86
state.shells = { set: (id, value) => registry.set(shellAtom(id), value) };
87
88
class TestNotification extends EventTarget {
apps/web/src/components/ThreadNotificationCoordinator.tsx
+31
-4
@@ -3,7 +3,7 @@ import {
3
type PendingSubagentRequest,
4
presentThreadShell,
5
} from "@t3tools/client-runtime/state/models";
6
-import { pendingSubagentRequestsByThread } from "@t3tools/client-runtime/state/threads";
6
+import { isShownUnderParent } from "@t3tools/client-runtime/state/threads";
7
import type { AnyRouter } from "@tanstack/react-router";
8
import type { EnvironmentId, OrchestrationV2ThreadShell, ThreadId } from "@t3tools/contracts";
9
import type { ClientSettings } from "@t3tools/contracts/settings";
@@ -20,6 +20,7 @@ import { getClientSettings, subscribeClientSettings } from "../hooks/useSettings
20
import { isWindowsPlatform } from "../lib/utils";
21
import { environmentSummaries } from "../state/presentation";
22
import { environmentShell } from "../state/shell";
23
+import { environmentThreadShells } from "../state/threads";
24
import {
25
hasDesktopNotifications,
26
hasNotificationSound,
@@ -173,10 +174,22 @@ export function startThreadNotifications(
174
) => {
175
const previous = entry.previous;
176
const next = new Map<ThreadId, NotificationState>();
176
- const subagentRequests = pendingSubagentRequestsByThread(threads);
177
+ // A parent here also hears of what its tasks on linked environments ask.
178
+ const subagentRequests = registry.get(
179
+ environmentThreadShells.pendingSubagentRequestsAtom(environmentId),
180
+ );
181
+ const delegatedUnderParent = registry.get(environmentThreadShells.delegatedUnderParentAtom);
182
const changed: Array<[NotificationState | undefined, NotificationState]> = [];
183
for (const rawThread of threads) {
179
- if (rawThread.lineage.relationshipToParent === "subagent") continue;
184
+ if (
185
+ isShownUnderParent(
186
+ { environmentId, threadId: rawThread.id },
187
+ rawThread.lineage,
188
+ delegatedUnderParent,
189
+ )
190
+ ) {
191
+ continue;
192
+ }
193
const prior = previous.get(rawThread.id);
194
const subagentRequest = subagentRequests.get(rawThread.id) ?? null;
195
if (prior?.raw === rawThread && prior.subagentRequest === subagentRequest) {
@@ -227,10 +240,11 @@ export function startThreadNotifications(
240
if (state) present(environmentId, state, kind);
241
}),
242
};
243
+ let threads: ReadonlyArray<OrchestrationV2ThreadShell> | null = null;
244
const unsubscribeShell = registry.subscribe(
245
environmentShell.stateValueAtom(environmentId),
246
(shell) => {
233
- const threads =
247
+ threads =
248
shell.status === "live" && Option.isSome(shell.snapshot)
249
? shell.snapshot.value.threads
250
: null;
@@ -243,8 +257,21 @@ export function startThreadNotifications(
257
},
258
{ immediate: true },
259
);
260
+ const reobserve = () => {
261
+ if (threads !== null) observeThreads(environmentId, entry, threads);
262
+ };
263
+ const unsubscribeRequests = registry.subscribe(
264
+ environmentThreadShells.pendingSubagentRequestsAtom(environmentId),
265
+ reobserve,
266
+ );
267
+ const unsubscribeDelegated = registry.subscribe(
268
+ environmentThreadShells.delegatedUnderParentAtom,
269
+ reobserve,
270
+ );
271
entry.unsubscribe = () => {
272
unsubscribeShell();
273
+ unsubscribeRequests();
274
+ unsubscribeDelegated();
275
entry.gate.clear();
276
};
277
return entry;
apps/web/src/components/chat/MessagesTimeline.tsx
+12
-4
@@ -237,9 +237,12 @@ interface MessagesTimelineProps {
237
onOpenThread: (threadId: OrchestrationV2TurnItem["threadId"]) => void;
238
renderHtmlRender?: TimelineRowSharedState["renderHtmlRender"];
239
turnItemSource?: TimelineRowSharedState["turnItemSource"];
240
+ /** The thread this one is a subagent of; `open` is absent when it cannot be opened from here. */
241
parentThreadLink?: {
241
- readonly threadId: ThreadId;
242
readonly title: string;
243
+ /** Where it runs, when that is another environment. */
244
+ readonly environmentLabel?: string;
245
+ readonly open?: () => void;
246
} | null;
247
workflowOpening?: WorkflowOpening | null;
248
onForkFromRun?: (input: {
@@ -1093,10 +1096,15 @@ const ConversationTimeline = memo(function ConversationTimeline({
1096
<div className="chat-content-lane pt-1 sm:pt-2">
1097
<TimelineSystemDivider
1098
label="Subagent of"
1096
- detail={parentThreadLink.title}
1099
+ detail={
1100
+ parentThreadLink.environmentLabel === undefined
1101
+ ? parentThreadLink.title
1102
+ : `${parentThreadLink.title} on ${parentThreadLink.environmentLabel}`
1103
+ }
1104
icon={BotIcon}
1098
- actionLabel="Open parent thread"
1099
- onAction={() => onOpenThread(parentThreadLink.threadId)}
1105
+ {...(parentThreadLink.open === undefined
1106
+ ? {}
1107
+ : { actionLabel: "Open parent thread", onAction: parentThreadLink.open })}
1108
/>
1109
</div>
1110
</div>
apps/web/src/components/chat/ThreadRelationshipsControl.tsx
+91
-2
@@ -32,8 +32,10 @@ import {
32
isProviderNativeSubagentThread,
33
NodeId,
34
type EnvironmentId,
35
+ type OrchestrationV2RemoteTaskChild,
36
type OrchestrationV2Subagent,
37
type OrchestrationV2ThreadShell,
38
+ type ServerProvider,
39
type ThreadId,
40
} from "@t3tools/contracts";
41
import { deriveSubagentElapsedMs } from "@t3tools/shared/orchestrationTiming";
@@ -61,7 +63,7 @@ import {
63
useThreadProjection,
64
useThreadRelationshipShells,
65
} from "../../state/entities";
64
-import { useEnvironmentProviders } from "../../state/environments";
66
+import { useEnvironment, useEnvironmentProviders } from "../../state/environments";
67
import { threadEnvironment } from "../../state/threads";
68
import { orchestrationEnvironment } from "../../state/orchestration";
69
import { useAtomCommand } from "../../state/use-atom-command";
@@ -217,6 +219,74 @@ function currentSubagent<Agent extends RuntimeSubagent>(
219
};
220
}
221
222
+/**
223
+ * A task delegated to a linked environment. It has no thread here, so it opens
224
+ * the thread there, when this client is connected to that environment.
225
+ */
226
+function RemoteSubagentRow(props: {
227
+ readonly agent: OrchestrationV2Subagent & {
228
+ readonly remoteChild: OrchestrationV2RemoteTaskChild;
229
+ };
230
+ readonly provider: ServerProvider | undefined;
231
+}) {
232
+ const navigate = useNavigate();
233
+ const environment = useEnvironment(props.agent.remoteChild.environmentId);
234
+ const { remoteChild } = props.agent;
235
+ const status = props.agent.status;
236
+ const failed = status === "failed";
237
+ const title = relationshipThreadTitle({
238
+ title: props.agent.title ?? "Subagent",
239
+ isSubagent: true,
240
+ });
241
+ return (
242
+ <li className="group relative flex h-8 items-center rounded-lg">
243
+ <Tooltip>
244
+ <TooltipTrigger
245
+ delay={200}
246
+ render={
247
+ <ThreadDetailsControl
248
+ size="sm"
249
+ variant="ghost"
250
+ part="row"
251
+ disabled={environment === null}
252
+ onClick={() =>
253
+ void navigate({
254
+ to: "/$environmentId/$threadId",
255
+ params: buildThreadRouteParams(
256
+ scopeThreadRef(remoteChild.environmentId, remoteChild.threadId),
257
+ ),
258
+ })
259
+ }
260
+ />
261
+ }
262
+ >
263
+ <ThreadRelationshipIcon
264
+ driver={props.agent.driver}
265
+ provider={props.provider}
266
+ fallbackIcon={BotIcon}
267
+ status={status}
268
+ />
269
+ <span className="min-w-0 flex-1">
270
+ <span className="block truncate text-left text-sm font-medium leading-4 text-foreground/85">
271
+ {title}
272
+ </span>
273
+ </span>
274
+ <span
275
+ className={`shrink-0 text-2xs ${failed ? "text-destructive" : "text-muted-foreground"}`}
276
+ >
277
+ on {remoteChild.label} · {threadRelationshipStatusLabel(status)}
278
+ </span>
279
+ </TooltipTrigger>
280
+ <TooltipPopup side="left">
281
+ {environment === null
282
+ ? `Runs on ${remoteChild.label}. Connect to it to open the thread there.`
283
+ : `Open on ${remoteChild.label}`}
284
+ </TooltipPopup>
285
+ </Tooltip>
286
+ </li>
287
+ );
288
+}
289
+
290
export function ThreadRelationshipsPanel(props: {
291
readonly environmentId: EnvironmentId;
292
readonly threadId: ThreadId;
@@ -332,12 +402,17 @@ export function ThreadRelationshipsPanel(props: {
402
{ id: "active", label: null, rows: active, expanded: true },
403
{ id: "previous", label: "Previous agents", rows: previous, expanded: false },
404
];
405
+ // Tasks running in a linked environment have no thread here; they get their own rows.
406
+ const remoteSubagents = (projection?.subagents ?? []).filter(
407
+ (agent): agent is OrchestrationV2Subagent & { remoteChild: OrchestrationV2RemoteTaskChild } =>
408
+ agent.remoteChild !== undefined,
409
+ );
410
const runningCount =
411
(projection?.subagents.filter(
412
(agent) => agent.childThreadId === null && agent.status === "running",
413
).length ?? 0) + active.filter(({ edge }) => edge.status === "running").length;
414
340
- if (relationshipRows.length === 0 && runningCount === 0) {
415
+ if (relationshipRows.length === 0 && runningCount === 0 && remoteSubagents.length === 0) {
416
return null;
417
}
418
@@ -700,6 +775,20 @@ export function ThreadRelationshipsPanel(props: {
775
}
776
</ThreadLineageGroup>
777
))}
778
+ {remoteSubagents.length > 0 ? (
779
+ <ThreadLineageRowList hiddenCount={0} onShowMore={() => {}}>
780
+ {remoteSubagents.map((agent) => (
781
+ <RemoteSubagentRow
782
+ key={agent.id}
783
+ agent={agent}
784
+ // Its provider instance belongs to the environment it runs in.
785
+ provider={providersByEnvironment
786
+ .get(agent.remoteChild.environmentId)
787
+ ?.find((entry) => entry.instanceId === agent.providerInstanceId)}
788
+ />
789
+ ))}
790
+ </ThreadLineageRowList>
791
+ ) : null}
792
</ThreadDetailsSection>
793
);
794
}
apps/web/src/components/chat/V2LifecycleRow.tsx
+32
-4
@@ -3,6 +3,9 @@ import { AgentElapsed } from "./AgentElapsed";
3
import { projectedSubagentsToRuntime } from "@t3tools/client-runtime/state/subagentRuntime";
4
import type { ReactNode } from "react";
5
import { useThreadShell, useProject } from "../../state/entities";
6
+import { useEnvironment } from "../../state/environments";
7
+import { buildThreadRouteParams } from "../../threadRoutes";
8
+import { useNavigate } from "@tanstack/react-router";
9
import { SubagentTooltipContent } from "./SubagentTooltipContent";
10
import { useAtomValue } from "@effect/atom-react";
11
import { scopeThreadRef, scopeProjectRef } from "@t3tools/client-runtime/environment";
@@ -21,6 +24,7 @@ import {
24
ProviderDriverKind,
25
type OrchestrationV2Notification,
26
type OrchestrationV2TurnItem,
27
+ type OrchestrationV2RemoteTaskChild,
28
type OrchestrationV2Subagent,
29
type ProviderInstanceId,
30
type ServerProvider,
@@ -199,6 +203,7 @@ export function V2LifecycleRow(props: {
203
startedAt={item.startedAt}
204
completedAt={item.completedAt}
205
threadId={item.childThreadId}
206
+ remote={item.remoteChild}
207
onOpenThread={props.onOpenThread}
208
/>
209
);
@@ -398,6 +403,8 @@ function SubagentTimelineLink(props: {
403
readonly startedAt: DateTime.Utc | null;
404
readonly completedAt: DateTime.Utc | null;
405
readonly threadId: ThreadId | null;
406
+ /** The thread in a linked environment that runs this task, when it runs there. */
407
+ readonly remote?: OrchestrationV2RemoteTaskChild | undefined;
408
readonly onOpenThread: (threadId: ThreadId) => void;
409
readonly event?: {
410
readonly status: OrchestrationV2TurnItem["status"] | null;
@@ -409,7 +416,21 @@ function SubagentTimelineLink(props: {
416
environmentThreadDetails.threadAtom(props.parentRef),
417
(thread) => thread?.projection.subagents.find((agent) => agent.id === props.subagentId) ?? null,
418
);
419
+ const remote = props.remote ?? agent?.remoteChild;
420
+ const remoteEnvironment = useEnvironment(remote?.environmentId ?? null);
421
+ const navigate = useNavigate();
422
const threadId = props.threadId;
423
+ // A task in a linked environment opens there, if this client is connected to it.
424
+ const open =
425
+ threadId !== null
426
+ ? () => props.onOpenThread(threadId)
427
+ : remote !== undefined && remoteEnvironment !== null
428
+ ? () =>
429
+ void navigate({
430
+ to: "/$environmentId/$threadId",
431
+ params: buildThreadRouteParams(scopeThreadRef(remote.environmentId, remote.threadId)),
432
+ })
433
+ : null;
434
const liveStatus = agent?.status ?? props.status;
435
const status = props.event ? props.event.status : liveStatus;
436
const statusLabel = props.event?.label ?? subagentStatusVisual(liveStatus).label;
@@ -434,7 +455,14 @@ function SubagentTimelineLink(props: {
455
status={status ?? undefined}
456
/>
457
<span className="min-w-0 flex-1">
437
- <span className="block truncate text-xs font-medium text-foreground">{props.title}</span>
458
+ <span className="flex items-baseline gap-2">
459
+ <span className="min-w-0 truncate text-xs font-medium text-foreground">
460
+ {props.title}
461
+ </span>
462
+ {remote !== undefined ? (
463
+ <span className="shrink-0 text-xs text-muted-foreground">on {remote.label}</span>
464
+ ) : null}
465
+ </span>
466
<span
467
className={cn(
468
"block text-2xs leading-relaxed",
@@ -460,7 +488,7 @@ function SubagentTimelineLink(props: {
488
<span className="shrink-0 text-xs text-muted-foreground tabular-nums">
489
{props.event ? props.event.timestamp : <SubagentElapsed agent={timing} />}
490
</span>
463
- {threadId !== null ? (
491
+ {open !== null ? (
492
<ChevronRightIcon
493
aria-hidden
494
className="size-3.5 shrink-0 text-muted-foreground/60 transition-colors group-hover/subagent:text-foreground"
@@ -475,7 +503,7 @@ function SubagentTimelineLink(props: {
503
<TooltipTrigger
504
delay={200}
505
render={
478
- threadId === null ? (
506
+ open === null ? (
507
<div data-v2-item-type="subagent" aria-description={statusLabel} className={className}>
508
{content}
509
</div>
@@ -485,7 +513,7 @@ function SubagentTimelineLink(props: {
513
data-v2-item-type="subagent"
514
aria-label={`Open ${props.title}`}
515
aria-description={statusLabel}
488
- onClick={() => props.onOpenThread(threadId)}
516
+ onClick={open}
517
className={cn(
518
className,
519
"cursor-pointer transition-colors hover:bg-accent/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring/70",
apps/web/src/components/sidebar/routeReveal.ts
+5
-3
@@ -52,16 +52,18 @@ export function resolveSidebarRouteReveal<T extends RevealableThread>(input: {
52
readonly routeKey: string | null;
53
readonly isSearching: boolean;
54
readonly scopedProjectKeys: ReadonlySet<string> | null;
55
+ readonly delegatedUnderParent: ReadonlySet<string>;
56
readonly findThread: (key: string) => T | undefined;
57
}): { readonly pendingKey: string | null; readonly widensScope: boolean } {
57
- const { reveal, routeKey, isSearching, scopedProjectKeys, findThread } = input;
58
+ const { reveal, routeKey, isSearching, scopedProjectKeys, delegatedUnderParent, findThread } =
59
+ input;
60
const pendingKey = pendingSidebarRouteReveal(reveal, routeKey);
61
// Search results replace the thread list; the reveal waits for it to return.
62
const thread = pendingKey === null || isSearching ? undefined : findThread(pendingKey);
63
const widensScope =
64
thread !== undefined &&
65
scopedProjectKeys !== null &&
64
- filterSidebarV2VisibleThreads([thread], scopedProjectKeys).length === 0 &&
65
- filterSidebarV2VisibleThreads([thread], null).length === 1;
66
+ filterSidebarV2VisibleThreads([thread], scopedProjectKeys, delegatedUnderParent).length === 0 &&
67
+ filterSidebarV2VisibleThreads([thread], null, delegatedUnderParent).length === 1;
68
return { pendingKey, widensScope };
69
}
apps/web/src/hooks/useSidebarProjectGroups.ts
+3
-2
@@ -2,7 +2,7 @@ import { orderItemsByPreferredIds, sortSidebarV2ProjectGroups } from "../compone
2
import { getProjectOrderKey, selectProjectGroupingSettings } from "../logicalProject";
3
import { buildSidebarProjectSnapshots } from "../sidebarProjectGrouping";
4
import { useEnvironmentIdentities, usePrimaryEnvironmentId } from "../state/environments";
5
-import { useProjects, useQuietThreadShells } from "../state/entities";
5
+import { useDelegatedUnderParent, useProjects, useQuietThreadShells } from "../state/entities";
6
import { legacyProjectCwdPreferenceKey, useUiStateStore } from "../uiStateStore";
7
import { useClientSettings } from "./useSettings";
8
@@ -11,6 +11,7 @@ export function useSidebarProjectGroups() {
11
// Activity order lags a running thread's streaming ticks until its next
12
// real change; reading every tick re-rendered the whole sidebar with it.
13
const threads = useQuietThreadShells();
14
+ const delegatedUnderParent = useDelegatedUnderParent();
15
const projectOrder = useUiStateStore((store) => store.projectOrder);
16
const sortOrder = useClientSettings((s) => s.sidebarProjectSortOrder);
17
const groupingSettings = useClientSettings(selectProjectGroupingSettings);
@@ -35,5 +36,5 @@ export function useSidebarProjectGroups() {
36
primaryEnvironmentId,
37
resolveEnvironmentLabel: (environmentId) => labels.get(environmentId) ?? null,
38
});
38
- return sortSidebarV2ProjectGroups(unsortedGroups, threads, sortOrder);
39
+ return sortSidebarV2ProjectGroups(unsortedGroups, threads, sortOrder, delegatedUnderParent);
40
}
apps/web/src/state/entities.ts
+5
@@ -112,6 +112,11 @@ export function useAllEnvironmentProjectSnapshotsReady(): boolean {
112
return useAtomValue(allEnvironmentProjectSnapshotsReadyAtom);
113
}
114
115
+/** Tasks linked environments run for a listed thread, by thread key; lists show them under it. */
116
+export function useDelegatedUnderParent(): ReadonlySet<string> {
117
+ return useAtomValue(environmentThreadShells.delegatedUnderParentAtom);
118
+}
119
+
120
export function useThreadShellsForProjectRefs(
121
refs: ReadonlyArray<ScopedProjectRef>,
122
): ReadonlyArray<EnvironmentThreadShell> {
docs/internals/remote.md
+9
@@ -117,6 +117,15 @@ shared access declarations, not tool by tool:
117
Reads are not fenced, and a client's own `thread.create` can never carry
118
`linkOrigin`.
119
120
+**A delegated task can run in a linked environment.** Its child is then an
121
+ordinary thread there, so the parent here records the task without a child
122
+thread of its own (`remoteChild` instead of `childThreadId`). A follower in
123
+[`RemoteDelegation`](../../apps/server/src/peer/RemoteDelegation.ts) waits on
124
+that thread and completes the task with `delegated_task.remote.complete`. That
125
+internal command reuses the parent half of a local finalize, so the parent
126
+wakes the same way. Open remote tasks are followed again at startup, which is
127
+also what keeps restart recovery from treating them as abandoned provider work.
128
+
129
The link is routing, not isolation: an agent the link starts runs as the
130
receiving environment's user. **A full-access link is therefore not fenced**:
131
its agents can already do anything that user can, so the fence would only stop
docs/user/remote-access.md
+7
@@ -269,6 +269,13 @@ it. From a terminal, use
269
removes it here.
270
- Links last 30 days. Link again with a new pairing code to renew one.
271
272
+An agent can also hand a task to a linked machine with `delegate_task`: it runs
273
+there as an ordinary thread, in the project with the same repository (or the
274
+one `target.projectId` names), and this thread wakes with its result when it
275
+ends, as for any delegated task. It keeps following the task across restarts.
276
+If the other machine revokes the link, or the link is removed here, the task
277
+fails with that reason.
278
+
279
## Manage or revoke access
280
281
On the host, **Settings → Sharing & access** lets authorized administrators create
evals/mcp-tool-use/run.test.ts
+1
-1
@@ -17,7 +17,7 @@ import {
17
shellRequest,
18
t3SystemAppend,
19
} from "./run.ts";
20
-import { taskPrompt } from "../../apps/server/src/mcp/OrchestratorMcpService.ts";
20
+import { taskPrompt } from "../../apps/server/src/mcp/delegatedTaskModes.ts";
21
22
it("grades Codex shell and subagent calls with the shared rules", () => {
23
const calls = [
evals/mcp-tool-use/run.ts
+1
-1
@@ -26,7 +26,7 @@ import { Tool } from "effect/ai";
26
import * as McpSchema from "effect/ai/McpSchema";
27
import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
28
29
-import { taskPrompt } from "../../apps/server/src/mcp/OrchestratorMcpService.ts";
29
+import { taskPrompt } from "../../apps/server/src/mcp/delegatedTaskModes.ts";
30
import * as McpInvocationContext from "../../apps/server/src/mcp/McpInvocationContext.ts";
31
import { advertisedJsonSchema } from "../../apps/server/src/mcp/advertisedJsonSchema.ts";
32
import { ORCHESTRATOR_MCP_RUNNING_TASK_NEXT } from "@t3tools/contracts";
packages/client-runtime/src/state/models.ts
+3
@@ -148,6 +148,8 @@ export interface EnvironmentThreadShell {
148
readonly lineage: OrchestrationV2ThreadShell["lineage"];
149
readonly forkedFrom: OrchestrationV2ThreadShell["forkedFrom"];
150
readonly linkOrigin: OrchestrationV2ThreadShell["linkOrigin"] | null;
151
+ /** The thread in a linked environment that delegated this one, if one did. */
152
+ readonly delegatedFrom: OrchestrationV2ThreadShell["delegatedFrom"] | null;
153
readonly activeProviderThreadId: OrchestrationV2ThreadShell["activeProviderThreadId"];
154
readonly latestRun: ThreadRunSummary | null;
155
readonly runtime: ThreadRuntimeSummary | null;
@@ -300,6 +302,7 @@ export function presentThreadShell(
302
lineage: thread.lineage,
303
forkedFrom: thread.forkedFrom,
304
linkOrigin: thread.linkOrigin ?? null,
305
+ delegatedFrom: thread.delegatedFrom ?? null,
306
activeProviderThreadId: thread.activeProviderThreadId,
307
latestRun,
308
runtime,
packages/client-runtime/src/state/threadShell.test.ts
+146
@@ -215,6 +215,152 @@ describe("v2 thread shell lists", () => {
215
registry.dispose();
216
});
217
218
+ it("lists a task a linked environment runs for a listed thread under that thread", () => {
219
+ const { registry, threads, snapshotAtom, catalogValueAtom } = makeHarness([
220
+ environmentId,
221
+ remoteEnvironmentId,
222
+ ]);
223
+ const parent = v2ThreadShell;
224
+ const task = {
225
+ ...v2ThreadShell,
226
+ id: ThreadId.make("remote-task"),
227
+ creationSource: "mcp" as const,
228
+ status: "running" as const,
229
+ activityRunStatus: "running" as const,
230
+ delegatedFrom: { environmentId, threadId: parent.id, title: parent.title },
231
+ };
232
+ const helper = {
233
+ ...task,
234
+ id: ThreadId.make("remote-helper"),
235
+ delegatedFrom: undefined,
236
+ lineage: {
237
+ ...task.lineage,
238
+ parentThreadId: task.id,
239
+ relationshipToParent: "subagent" as const,
240
+ },
241
+ };
242
+ const approval = {
243
+ id: RuntimeRequestId.make("cat-file"),
244
+ kind: "command" as const,
245
+ createdAt: v2Now,
246
+ };
247
+ registry.set(snapshotAtom(environmentId), { ...v2ShellSnapshot, threads: [parent] });
248
+ registry.set(snapshotAtom(remoteEnvironmentId), {
249
+ ...v2ShellSnapshot,
250
+ threads: [task, helper],
251
+ });
252
+ const parentRef = { environmentId, threadId: parent.id };
253
+ const inputs = threads.childThreadInputsAtom(parentRef);
254
+ const disposeNavigation = registry.mount(threads.navigationThreadShellsAtom);
255
+ const disposeParent = registry.mount(threads.threadShellAtom(parentRef));
256
+ const disposeInputs = registry.mount(inputs);
257
+ const listed = () =>
258
+ registry
259
+ .get(threads.navigationThreadShellsAtom)
260
+ .map((thread) => `${thread.environmentId}/${thread.id}`);
261
+ expect(listed()).toEqual([`${environmentId}/${parent.id}`]);
262
+
263
+ // The helper the task started there asks for approval: the parent here hears of it.
264
+ registry.set(snapshotAtom(remoteEnvironmentId), {
265
+ ...v2ShellSnapshot,
266
+ threads: [task, { ...helper, pendingRuntimeRequest: approval }],
267
+ });
268
+ expect(registry.get(threads.threadShellAtom(parentRef))?.pendingSubagentRequest).toBe(
269
+ "approval",
270
+ );
271
+ expect(registry.get(inputs).map((thread) => `${thread.environmentId}/${thread.id}`)).toEqual([
272
+ `${remoteEnvironmentId}/${helper.id}`,
273
+ ]);
274
+
275
+ // A task whose parent is gone there is listed on its own, as is one whose
276
+ // parent's environment is switched off.
277
+ registry.set(snapshotAtom(environmentId), { ...v2ShellSnapshot, threads: [] });
278
+ expect(listed()).toEqual([`${remoteEnvironmentId}/${task.id}`]);
279
+ // Archiving the parent here leaves the task there unarchived, so it is listed on its own.
280
+ registry.set(snapshotAtom(environmentId), {
281
+ ...v2ShellSnapshot,
282
+ threads: [{ ...parent, archivedAt: v2Now }],
283
+ });
284
+ expect(listed()).toEqual([`${remoteEnvironmentId}/${task.id}`]);
285
+ registry.set(snapshotAtom(environmentId), { ...v2ShellSnapshot, threads: [parent] });
286
+ expect(listed()).toEqual([`${environmentId}/${parent.id}`]);
287
+ const catalog = registry.get(catalogValueAtom);
288
+ const entries = new Map(catalog.entries);
289
+ entries.set(environmentId, { ...entries.get(environmentId)!, enabled: false });
290
+ registry.set(catalogValueAtom, { ...catalog, entries });
291
+ expect(listed()).toEqual([`${remoteEnvironmentId}/${task.id}`]);
292
+ disposeInputs();
293
+ disposeParent();
294
+ disposeNavigation();
295
+ registry.dispose();
296
+ });
297
+
298
+ it("brings an approval up a chain of tasks across three environments to its root", () => {
299
+ const thirdEnvironmentId = EnvironmentId.make("third-environment-v2");
300
+ const { registry, threads, snapshotAtom } = makeHarness([
301
+ environmentId,
302
+ remoteEnvironmentId,
303
+ thirdEnvironmentId,
304
+ ]);
305
+ const root = v2ThreadShell;
306
+ const running = {
307
+ creationSource: "mcp" as const,
308
+ status: "running" as const,
309
+ activityRunStatus: "running" as const,
310
+ };
311
+ const task = {
312
+ ...v2ThreadShell,
313
+ ...running,
314
+ id: ThreadId.make("remote-task"),
315
+ delegatedFrom: { environmentId, threadId: root.id, title: root.title },
316
+ };
317
+ const nestedTask = {
318
+ ...v2ThreadShell,
319
+ ...running,
320
+ id: ThreadId.make("third-task"),
321
+ delegatedFrom: { environmentId: remoteEnvironmentId, threadId: task.id, title: task.title },
322
+ };
323
+ // A task the middle one delegates back to the root's own environment.
324
+ const returningTask = {
325
+ ...nestedTask,
326
+ id: ThreadId.make("returning-task"),
327
+ };
328
+ const approval = {
329
+ id: RuntimeRequestId.make("cat-file"),
330
+ kind: "command" as const,
331
+ createdAt: v2Now,
332
+ };
333
+ registry.set(snapshotAtom(environmentId), { ...v2ShellSnapshot, threads: [root] });
334
+ registry.set(snapshotAtom(remoteEnvironmentId), { ...v2ShellSnapshot, threads: [task] });
335
+ registry.set(snapshotAtom(thirdEnvironmentId), {
336
+ ...v2ShellSnapshot,
337
+ threads: [{ ...nestedTask, pendingRuntimeRequest: approval }],
338
+ });
339
+ const rootRef = { environmentId, threadId: root.id };
340
+ const taskRef = { environmentId: remoteEnvironmentId, threadId: task.id };
341
+ const disposeRoot = registry.mount(threads.threadShellAtom(rootRef));
342
+ const disposeTask = registry.mount(threads.threadShellAtom(taskRef));
343
+ expect(registry.get(threads.threadShellAtom(taskRef))?.pendingSubagentRequest).toBe("approval");
344
+ expect(registry.get(threads.threadShellAtom(rootRef))?.pendingSubagentRequest).toBe("approval");
345
+
346
+ // Once it is answered, neither stays flagged.
347
+ registry.set(snapshotAtom(thirdEnvironmentId), {
348
+ ...v2ShellSnapshot,
349
+ threads: [nestedTask],
350
+ });
351
+ expect(registry.get(threads.threadShellAtom(rootRef))?.pendingSubagentRequest).toBeNull();
352
+
353
+ // Environments that delegate to each other still settle on the root's flag.
354
+ registry.set(snapshotAtom(environmentId), {
355
+ ...v2ShellSnapshot,
356
+ threads: [root, { ...returningTask, pendingRuntimeRequest: approval }],
357
+ });
358
+ expect(registry.get(threads.threadShellAtom(rootRef))?.pendingSubagentRequest).toBe("approval");
359
+ disposeTask();
360
+ disposeRoot();
361
+ registry.dispose();
362
+ });
363
+
364
it.each([
365
{ reason: "switched-off", state: { enabled: false } },
366
{
packages/client-runtime/src/state/threadShell.ts
+185
-36
@@ -45,6 +45,20 @@ const isChildRunLive = (
45
thread.status === "running" ||
46
thread.status === "waiting";
47
48
+/**
49
+ * Whether a thread shows under its parent rather than in thread lists: a
50
+ * subagent, or a task a linked environment delegated here whose parent the
51
+ * client lists (`delegatedUnderParent`, by thread key). A task whose parent
52
+ * the client cannot list stays in the lists, so its work is never out of reach.
53
+ */
54
+export function isShownUnderParent(
55
+ ref: ScopedThreadRef,
56
+ lineage: OrchestrationV2ThreadShell["lineage"],
57
+ delegatedUnderParent: ReadonlySet<string>,
58
+): boolean {
59
+ return lineage.relationshipToParent === "subagent" || delegatedUnderParent.has(threadKey(ref));
60
+}
61
+
62
/** Provider-native
63
subagents ask on their parent, so they are skipped. */
64
function subagentRequest(thread: OrchestrationV2ThreadShell): PendingSubagentRequest | null {
@@ -52,7 +66,7 @@ function subagentRequest(thread: OrchestrationV2ThreadShell): PendingSubagentReq
66
if (
67
kind === undefined ||
68
kind === "auth_refresh" ||
55
- thread.lineage.relationshipToParent !== "subagent" ||
69
+ (thread.lineage.relationshipToParent !== "subagent" && thread.delegatedFrom === undefined) ||
70
isProviderNativeSubagentThread(thread) ||
71
!isChildRunLive(thread)
72
) {
@@ -61,28 +75,51 @@ function subagentRequest(thread: OrchestrationV2ThreadShell): PendingSubagentReq
75
return kind === "user_input" ? "user_input" : "approval";
76
}
77
64
-export function pendingSubagentRequestsByThread(
78
+/**
79
+ * The threads to flag for a subagent's live question or approval, up its
80
+ * subagent chain. `delegated` are tasks this environment's threads delegated
81
+ * to linked environments, with what each one, or its own subagents, asks.
82
+ */
83
+function pendingSubagentRequestsByThread(
84
threads: ReadonlyArray<OrchestrationV2ThreadShell>,
85
+ delegated: ReadonlyArray<{
86
+ readonly parentThreadId: ThreadId;
87
+ readonly request: PendingSubagentRequest;
88
+ }> = [],
89
): ReadonlyMap<ThreadId, PendingSubagentRequest> {
90
const requests = new Map<ThreadId, PendingSubagentRequest>();
91
let byId: ReadonlyMap<ThreadId, OrchestrationV2ThreadShell> | undefined;
69
- for (const child of threads) {
70
- const request = subagentRequest(child);
71
- if (request === null) continue;
92
+ const flag = (
93
+ firstParentId: ThreadId | null,
94
+ request: PendingSubagentRequest,
95
+ seen: Set<ThreadId>,
96
+ ) => {
97
byId ??= new Map(threads.map((thread) => [thread.id, thread] as const));
73
- const seen = new Set<ThreadId>([child.id]);
74
- let current: OrchestrationV2ThreadShell | undefined = child;
75
- while (current?.lineage.relationshipToParent === "subagent") {
76
- const parentId: ThreadId | null = current.lineage.parentThreadId;
77
- if (parentId === null || seen.has(parentId)) break;
98
+ let parentId = firstParentId;
99
+ while (parentId !== null && !seen.has(parentId)) {
100
seen.add(parentId);
101
if (requests.get(parentId) !== "approval") requests.set(parentId, request);
80
- current = byId.get(parentId);
102
+ const parent = byId.get(parentId);
103
+ parentId =
104
+ parent?.lineage.relationshipToParent === "subagent" ? parent.lineage.parentThreadId : null;
105
}
106
+ };
107
+ for (const child of threads) {
108
+ if (child.lineage.relationshipToParent !== "subagent") continue;
109
+ const request = subagentRequest(child);
110
+ if (request !== null) flag(child.lineage.parentThreadId, request, new Set([child.id]));
111
}
112
+ for (const task of delegated) flag(task.parentThreadId, task.request, new Set());
113
return requests.size === 0 ? EMPTY_SUBAGENT_REQUESTS : requests;
114
}
115
116
+const sameRequests = (
117
+ left: ReadonlyMap<ThreadId, PendingSubagentRequest>,
118
+ right: ReadonlyMap<ThreadId, PendingSubagentRequest>,
119
+) =>
120
+ left.size === right.size &&
121
+ [...right].every(([threadId, request]) => left.get(threadId) === request);
122
+
123
export function childThreadInputsTitle(
124
children: ReadonlyArray<Pick<EnvironmentThreadShell, "hasPendingApprovals">>,
125
): string {
@@ -177,16 +214,75 @@ export function createEnvironmentThreadShellAtoms(input: {
214
}).pipe(Atom.withLabel(`environment-thread-index:${environmentId}`)),
215
);
216
180
- const pendingSubagentRequestsAtom = Atom.family((environmentId: EnvironmentId) => {
217
+ // What an environment's own subagents ask. Kept apart from the tasks other
218
+ // environments run for it, so two environments delegating to each other
219
+ // never read each other's totals.
220
+ const localSubagentRequestsAtom = Atom.family((environmentId: EnvironmentId) => {
221
let previous = EMPTY_SUBAGENT_REQUESTS;
222
return Atom.make((get) => {
223
const next = pendingSubagentRequestsByThread(get(environmentThreadsAtom(environmentId)));
184
- if (
185
- next.size === previous.size &&
186
- [...next].every(([threadId, request]) => previous.get(threadId) === request)
187
- ) {
188
- return previous;
224
+ if (sameRequests(previous, next)) return previous;
225
+ previous = next;
226
+ return next;
227
+ }).pipe(Atom.withLabel(`environment-local-subagent-requests:${environmentId}`));
228
+ });
229
+
230
+ // Flags for environments whose threads delegated tasks, counting what each task
231
+ // or anything it delegated on asks. Each pass settles one more hop of a chain;
232
+ // flags only grow, so environments delegating to each other settle too.
233
+ const delegatedSubagentRequestsAtom = Atom.make((get) => {
234
+ const tasksByDelegator = new Map<
235
+ EnvironmentId,
236
+ Array<{
237
+ readonly runsIn: EnvironmentId;
238
+ readonly thread: OrchestrationV2ThreadShell;
239
+ readonly parentThreadId: ThreadId;
240
+ }>
241
+ >();
242
+ for (const runsIn of enabledEnvironmentIds(get(input.catalogValueAtom))) {
243
+ for (const thread of get(environmentThreadsAtom(runsIn))) {
244
+ const from = thread.delegatedFrom;
245
+ if (from === undefined || from.environmentId === runsIn) continue;
246
+ const task = { runsIn, thread, parentThreadId: from.threadId };
247
+ const tasks = tasksByDelegator.get(from.environmentId);
248
+ if (tasks === undefined) tasksByDelegator.set(from.environmentId, [task]);
249
+ else tasks.push(task);
250
}
251
+ }
252
+ let flags = new Map<EnvironmentId, ReadonlyMap<ThreadId, PendingSubagentRequest>>();
253
+ const requestsOf = (environmentId: EnvironmentId) =>
254
+ flags.get(environmentId) ?? get(localSubagentRequestsAtom(environmentId));
255
+ for (let changed = tasksByDelegator.size > 0; changed;) {
256
+ changed = false;
257
+ const next = new Map(flags);
258
+ for (const [environmentId, tasks] of tasksByDelegator) {
259
+ const delegated = tasks.flatMap(({ runsIn, thread, parentThreadId }) => {
260
+ const own = subagentRequest(thread);
261
+ const nested = requestsOf(runsIn).get(thread.id);
262
+ const request = own === "approval" ? own : (nested ?? own);
263
+ return request === null ? [] : [{ parentThreadId, request }];
264
+ });
265
+ if (delegated.length === 0) continue;
266
+ const requests = pendingSubagentRequestsByThread(
267
+ get(environmentThreadsAtom(environmentId)),
268
+ delegated,
269
+ );
270
+ if (sameRequests(requestsOf(environmentId), requests)) continue;
271
+ next.set(environmentId, requests);
272
+ changed = true;
273
+ }
274
+ flags = next;
275
+ }
276
+ return flags;
277
+ }).pipe(Atom.withLabel("environment-delegated-subagent-requests"));
278
+
279
+ const pendingSubagentRequestsAtom = Atom.family((environmentId: EnvironmentId) => {
280
+ let previous = EMPTY_SUBAGENT_REQUESTS;
281
+ return Atom.make((get) => {
282
+ const next =
283
+ get(delegatedSubagentRequestsAtom).get(environmentId) ??
284
+ get(localSubagentRequestsAtom(environmentId));
285
+ if (sameRequests(previous, next)) return previous;
286
previous = next;
287
return next;
288
}).pipe(Atom.withLabel(`environment-pending-subagent-requests:${environmentId}`));
@@ -280,30 +376,47 @@ export function createEnvironmentThreadShellAtoms(input: {
376
});
377
378
// Child approvals and questions are hidden with their sidebar rows. Read their
283
- // shell summaries, without subscribing to every child transcript.
379
+ // shell summaries, without subscribing to every child transcript. A task
380
+ // delegated to a linked environment is a child too, with its own subagents.
381
const childThreadInputsAtomFamily = Atom.family((key: string) => {
285
- const ref = parseThreadKey(key);
382
let previous: ReadonlyArray<EnvironmentThreadShell> = [];
383
return Atom.make((get) => {
288
- const children = new Map<ThreadId, OrchestrationV2ThreadShell[]>();
289
- for (const thread of get(environmentThreadsAtom(ref.environmentId))) {
290
- const parent = thread.lineage.parentThreadId;
291
- if (parent === null || thread.lineage.relationshipToParent !== "subagent") continue;
292
- const siblings = children.get(parent);
293
- if (siblings) siblings.push(thread);
294
- else children.set(parent, [thread]);
384
+ const children = new Map<
385
+ string,
386
+ Array<{ environmentId: EnvironmentId; thread: OrchestrationV2ThreadShell }>
387
+ >();
388
+ const addChild = (
389
+ parent: ScopedThreadRef,
390
+ environmentId: EnvironmentId,
391
+ thread: OrchestrationV2ThreadShell,
392
+ ) => {
393
+ const siblings = children.get(threadKey(parent));
394
+ if (siblings) siblings.push({ environmentId, thread });
395
+ else children.set(threadKey(parent), [{ environmentId, thread }]);
396
+ };
397
+ for (const environmentId of enabledEnvironmentIds(get(input.catalogValueAtom))) {
398
+ for (const thread of get(environmentThreadsAtom(environmentId))) {
399
+ const parent = thread.lineage.parentThreadId;
400
+ if (parent !== null && thread.lineage.relationshipToParent === "subagent") {
401
+ addChild({ environmentId, threadId: parent }, environmentId, thread);
402
+ } else if (thread.delegatedFrom !== undefined) {
403
+ addChild(thread.delegatedFrom, environmentId, thread);
404
+ }
405
+ }
406
}
296
- const subagentRequests = get(pendingSubagentRequestsAtom(ref.environmentId));
297
- const seen = new Set<ThreadId>([ref.threadId]);
298
- const pending = [ref.threadId];
407
+ const seen = new Set<string>([key]);
408
+ const pending = [key];
409
const next: EnvironmentThreadShell[] = [];
410
for (const parent of pending) {
301
- for (const child of children.get(parent) ?? []) {
302
- if (seen.has(child.id)) continue;
303
- seen.add(child.id);
304
- pending.push(child.id);
305
- if (subagentRequest(child) !== null) {
306
- next.push(scopedThread(ref.environmentId, child, subagentRequests));
411
+ for (const { environmentId, thread } of children.get(parent) ?? []) {
412
+ const childKey = threadKey({ environmentId, threadId: thread.id });
413
+ if (seen.has(childKey)) continue;
414
+ seen.add(childKey);
415
+ pending.push(childKey);
416
+ if (subagentRequest(thread) !== null) {
417
+ next.push(
418
+ scopedThread(environmentId, thread, get(pendingSubagentRequestsAtom(environmentId))),
419
+ );
420
}
421
}
422
}
@@ -313,6 +426,7 @@ export function createEnvironmentThreadShellAtoms(input: {
426
previous.length === next.length &&
427
previous.every(
428
(thread, index) =>
429
+ thread.environmentId === next[index]?.environmentId &&
430
thread.id === next[index]?.id &&
431
thread.title === next[index]?.title &&
432
thread.hasPendingApprovals === next[index]?.hasPendingApprovals,
@@ -402,14 +516,47 @@ export function createEnvironmentThreadShellAtoms(input: {
516
return next;
517
}).pipe(Atom.withLabel("environment-quiet-thread-shell-list"));
518
519
+ let previousDelegatedUnderParent: ReadonlySet<string> = new Set();
520
+ const delegatedUnderParentAtom = Atom.make((get) => {
521
+ const environmentIds = new Set(enabledEnvironmentIds(get(input.catalogValueAtom)));
522
+ const next = new Set<string>();
523
+ for (const environmentId of environmentIds) {
524
+ for (const thread of get(environmentThreadsAtom(environmentId))) {
525
+ const parent = thread.delegatedFrom;
526
+ if (
527
+ parent !== undefined &&
528
+ environmentIds.has(parent.environmentId) &&
529
+ // An archived parent leaves navigation; its task there stays listed on its own.
530
+ get(environmentThreadIndexAtom(parent.environmentId)).get(parent.threadId)?.archivedAt ===
531
+ null
532
+ ) {
533
+ next.add(threadKey({ environmentId, threadId: thread.id }));
534
+ }
535
+ }
536
+ }
537
+ if (
538
+ next.size === previousDelegatedUnderParent.size &&
539
+ [...next].every((key) => previousDelegatedUnderParent.has(key))
540
+ ) {
541
+ return previousDelegatedUnderParent;
542
+ }
543
+ previousDelegatedUnderParent = next;
544
+ return next;
545
+ }).pipe(Atom.withLabel("environment-delegated-under-parent"));
546
+
547
let previousNavigationShells: ReadonlyArray<EnvironmentThreadShell> = [];
548
const navigationThreadShellsAtom = Atom.make((get) => {
549
const next: EnvironmentThreadShell[] = [];
550
+ const underParent = get(delegatedUnderParentAtom);
551
for (const environmentId of enabledEnvironmentIds(get(input.catalogValueAtom))) {
552
const subagentRequests = get(pendingSubagentRequestsAtom(environmentId));
553
for (const thread of get(environmentThreadsAtom(environmentId))) {
411
- if (thread.archivedAt !== null || thread.lineage.relationshipToParent === "subagent")
554
+ if (
555
+ thread.archivedAt !== null ||
556
+ isShownUnderParent({ environmentId, threadId: thread.id }, thread.lineage, underParent)
557
+ ) {
558
continue;
559
+ }
560
next.push(scopedThread(environmentId, thread, subagentRequests));
561
}
562
}
@@ -427,6 +574,8 @@ export function createEnvironmentThreadShellAtoms(input: {
574
threadShellsAtom,
575
quietThreadShellsAtom,
576
navigationThreadShellsAtom,
577
+ delegatedUnderParentAtom,
578
+ pendingSubagentRequestsAtom,
579
threadShellsForProjectRefsAtom: (refs: ReadonlyArray<ScopedProjectRef>) =>
580
threadShellsForProjectRefsAtomFamily(projectRefCollectionKey(refs)),
581
threadShellAtom: (ref: ScopedThreadRef) => threadShellAtomFamily(threadKey(ref)),
packages/contracts/src/orchestrationV2.ts
+98
@@ -19,6 +19,7 @@ import {
19
GuestShareId,
20
IsoDateTime,
21
MessageId,
22
+ EnvironmentId,
23
NodeId,
24
ForwardCompatibleUnion,
25
ForwardCompatibleUnionArray,
@@ -126,6 +127,17 @@ export type OrchestrationV2LinkOrigin = typeof OrchestrationV2LinkOrigin.Type;
127
export const linkOriginIsFenced = (origin: OrchestrationV2LinkOrigin) =>
128
origin.access !== "full-access";
129
130
+/**
131
+ * The thread in a linked environment that delegated this one, when it did:
132
+ * this thread is that parent's subagent, run here instead of there.
133
+ */
134
+export const OrchestrationV2DelegatedFrom = Schema.Struct({
135
+ environmentId: EnvironmentId,
136
+ threadId: ThreadId,
137
+ title: Schema.String,
138
+});
139
+export type OrchestrationV2DelegatedFrom = typeof OrchestrationV2DelegatedFrom.Type;
140
+
141
export const OrchestrationV2NativeRefStrength = Schema.Literals(["strong", "weak", "none"]);
142
export type OrchestrationV2NativeRefStrength = typeof OrchestrationV2NativeRefStrength.Type;
143
@@ -438,6 +450,7 @@ export const OrchestrationV2AppThread = Schema.Struct({
450
activeProviderThreadId: Schema.NullOr(ProviderThreadId),
451
historyOrigin: Schema.optional(OrchestrationV2ThreadHistoryOrigin),
452
linkOrigin: Schema.optional(OrchestrationV2LinkOrigin),
453
+ delegatedFrom: Schema.optional(OrchestrationV2DelegatedFrom),
454
lineage: OrchestrationV2AppThreadLineage,
455
forkedFrom: Schema.NullOr(
456
Schema.Union([
@@ -812,6 +825,32 @@ export type OrchestrationV2SubagentWorkflow = typeof OrchestrationV2SubagentWork
825
*/
826
const DedupedBodyMarker = Schema.optionalKey(Schema.Literal(true));
827
828
+/**
829
+ * Where an app-owned task runs when it runs in a linked environment instead
830
+ * of in a child thread here: that environment and the ordinary thread it runs
831
+ * as there. Such a task has no `childThreadId`.
832
+ */
833
+export const OrchestrationV2RemoteTaskChild = Schema.Struct({
834
+ environmentId: EnvironmentId,
835
+ threadId: ThreadId,
836
+ label: Schema.String,
837
+ /** The run there that carries the task; absent on tasks recorded before it was kept. */
838
+ runId: Schema.optional(RunId),
839
+ /**
840
+ * Nothing is left to stop there: a stop reached it, was refused for good, or the thread
841
+ * or link is gone. A run ending there by itself sets it too, unless the task here was
842
+ * cancelled or stopped and still owes a stop, which its follower keeps sending across
843
+ * restarts. `false`: a Stop here owes one to a task that already had its result.
844
+ */
845
+ stoppedThere: Schema.optional(Schema.Boolean),
846
+ /**
847
+ * Stops asked for here once the task had its result. The count names the
848
+ * one owed, so each reaches the thread there once however often it is sent.
849
+ */
850
+ stopCount: Schema.optional(NonNegativeInt),
851
+});
852
+export type OrchestrationV2RemoteTaskChild = typeof OrchestrationV2RemoteTaskChild.Type;
853
+
854
export const OrchestrationV2Subagent = Schema.Struct({
855
id: NodeId,
856
threadId: ThreadId,
@@ -823,6 +862,7 @@ export const OrchestrationV2Subagent = Schema.Struct({
862
providerInstanceId: ProviderInstanceId,
863
providerThreadId: Schema.NullOr(ProviderThreadId),
864
childThreadId: Schema.NullOr(ThreadId),
865
+ remoteChild: Schema.optional(OrchestrationV2RemoteTaskChild),
866
nativeTaskRef: Schema.NullOr(OrchestrationV2ProviderRef),
867
prompt: Schema.String,
868
title: Schema.NullOr(Schema.String),
@@ -1663,6 +1703,7 @@ export const OrchestrationV2TurnItem = Schema.Union([
1703
driver: ProviderDriverKind,
1704
providerInstanceId: ProviderInstanceId,
1705
childThreadId: Schema.NullOr(ThreadId),
1706
+ remoteChild: Schema.optional(OrchestrationV2RemoteTaskChild),
1707
prompt: Schema.String,
1708
progress: Schema.optional(Schema.String),
1709
result: Schema.NullOr(Schema.String),
@@ -1967,6 +2008,7 @@ export const OrchestrationV2ThreadShell = Schema.Struct({
2008
activeProviderThreadId: Schema.NullOr(ProviderThreadId),
2009
historyOrigin: Schema.optional(OrchestrationV2ThreadHistoryOrigin),
2010
linkOrigin: Schema.optional(OrchestrationV2LinkOrigin),
2011
+ delegatedFrom: Schema.optional(OrchestrationV2DelegatedFrom),
2012
latestRunId: Schema.NullOr(RunId),
2013
latestRunRequestedAt: Schema.optional(Schema.NullOr(Schema.DateTimeUtc)),
2014
latestRunStartedAt: Schema.optional(Schema.NullOr(Schema.DateTimeUtc)),
@@ -2496,6 +2538,7 @@ export const OrchestrationV2TurnItemJson = Schema.Union([
2538
driver: ProviderDriverKind,
2539
providerInstanceId: ProviderInstanceId,
2540
childThreadId: Schema.NullOr(ThreadId),
2541
+ remoteChild: Schema.optional(OrchestrationV2RemoteTaskChild),
2542
prompt: Schema.String,
2543
progress: Schema.optional(Schema.String),
2544
result: Schema.NullOr(Schema.String),
@@ -2801,6 +2844,8 @@ export const OrchestrationV2Command = Schema.Union([
2844
worktreePath: Schema.NullOr(TrimmedNonEmptyString),
2845
/** Only the server sets this; a client's thread.create never carries one. */
2846
linkOrigin: Schema.optional(OrchestrationV2LinkOrigin),
2847
+ /** Only the server sets this, with `linkOrigin`, for a linked environment's delegated task. */
2848
+ delegatedFrom: Schema.optional(OrchestrationV2DelegatedFrom),
2849
importedNativeThread: Schema.optional(
2850
Schema.Struct({
2851
ref: Schema.Struct({
@@ -3287,6 +3332,59 @@ const OrchestrationV2InternalCommand = Schema.Union([
3332
}),
3333
),
3334
}),
3335
+ /**
3336
+ * Records a delegated task that runs in a linked environment: the task, its
3337
+ * node and its turn item on the parent, as `delegated_task.request` does,
3338
+ * without a child thread here. `remoteChild` is the thread already launched
3339
+ * there. The ids derive from `commandId`, so a retry records nothing new.
3340
+ */
3341
+ Schema.Struct({
3342
+ type: Schema.Literal("delegated_task.remote.request"),
3343
+ commandId: CommandId,
3344
+ parentThreadId: ThreadId,
3345
+ parentRunId: RunId,
3346
+ parentNodeId: NodeId,
3347
+ task: TrimmedNonEmptyString,
3348
+ title: Schema.optional(TrimmedNonEmptyString),
3349
+ driver: ProviderDriverKind,
3350
+ modelSelection: ModelSelection,
3351
+ remoteChild: OrchestrationV2RemoteTaskChild,
3352
+ completionWake: Schema.optional(Schema.Literals(["always", "settled_only"])),
3353
+ }),
3354
+ /**
3355
+ * Completes a delegated task that ran in a linked environment, with what its
3356
+ * thread there ended as. The parent wakes exactly as for a child here. A
3357
+ * task that already has a result keeps it; `stoppedThere` is still recorded,
3358
+ * and without it (a Stop or cancel here) the task owes a stop there instead.
3359
+ */
3360
+ Schema.Struct({
3361
+ type: Schema.Literal("delegated_task.remote.complete"),
3362
+ commandId: CommandId,
3363
+ parentThreadId: ThreadId,
3364
+ taskId: NodeId,
3365
+ status: Schema.Literals(["completed", "failed", "cancelled", "interrupted"]),
3366
+ result: Schema.String,
3367
+ /**
3368
+ * `ran-out`: the run there ended by itself; `stopped`: a stop from here reached it. Either
3369
+ * sets `remoteChild.stoppedThere` on a task this report completes. On a task already
3370
+ * cancelled or stopped here only `stopped` does, since a run that ended by itself leaves
3371
+ * the stop owed for whatever follows it.
3372
+ */
3373
+ stoppedThere: Schema.optional(Schema.Literals(["ran-out", "stopped"])),
3374
+ /** The stop generation this report acknowledges; absent for the original unnumbered stop. */
3375
+ stopCount: Schema.optional(NonNegativeInt),
3376
+ }),
3377
+ /**
3378
+ * Owes a stop to the thread there of a remote task that already has its result, as Stop on
3379
+ * a parent stops a finished child here. The task keeps its status, result and completion
3380
+ * delivery; its follower sends the stop and reports it with `delegated_task.remote.complete`.
3381
+ */
3382
+ Schema.Struct({
3383
+ type: Schema.Literal("delegated_task.remote.stop"),
3384
+ commandId: CommandId,
3385
+ parentThreadId: ThreadId,
3386
+ taskId: NodeId,
3387
+ }),
3388
Schema.Struct({
3389
type: Schema.Literal("checkpoint.rollback.fail"),
3390
commandId: CommandId,
packages/contracts/src/orchestratorMcp.ts
+26
-1
@@ -111,6 +111,18 @@ export const OrchestratorMcpTarget = Schema.Struct({
111
"Options from `orchestrator_capabilities`, such as {effort:'max'}. Given values override inherited. [] or {} clears.",
112
}),
113
),
114
+ environmentId: Schema.optional(
115
+ EnvironmentId.annotate({
116
+ description:
117
+ "Linked environment to run in. Provider and model default to yours; others come from `orchestrator_capabilities` with this `environmentId`.",
118
+ }),
119
+ ),
120
+ projectId: Schema.optional(
121
+ ProjectId.annotate({
122
+ description:
123
+ "With `environmentId`: its project to run in. Default: the one with this project's repository.",
124
+ }),
125
+ ),
126
});
127
export type OrchestratorMcpTarget = typeof OrchestratorMcpTarget.Type;
128
@@ -191,7 +203,12 @@ const OrchestratorMcpRunningTaskNext = Schema.Literal(ORCHESTRATOR_MCP_RUNNING_T
203
204
export const OrchestratorMcpDelegateTaskResult = Schema.Struct({
205
taskId: NodeId,
194
- childThreadId: ThreadId,
206
+ /** Null for a task that runs in a linked environment; see `remoteChild`. */
207
+ childThreadId: Schema.NullOr(ThreadId),
208
+ /** The linked environment and thread a remote task runs as. */
209
+ remoteChild: Schema.optional(
210
+ Schema.Struct({ environmentId: EnvironmentId, threadId: ThreadId, label: Schema.String }),
211
+ ),
212
link: Schema.optional(Schema.String),
213
childRunId: Schema.NullOr(RunId),
214
childNodeId: NodeId,
@@ -503,6 +520,12 @@ export const OrchestratorMcpThreadWaitInput = Schema.Struct({
520
threadId: ThreadId,
521
runId: Schema.optional(RunId),
522
timeoutMs: Schema.optional(Schema.Finite),
523
+ untilDelegatedWorkSettled: Schema.optional(
524
+ Schema.Boolean.annotate({
525
+ description:
526
+ "Also wait for its delegated and background tasks and their completions to settle. `resultRun` then names the run with its final answer.",
527
+ }),
528
+ ),
529
});
530
export type OrchestratorMcpThreadWaitInput = typeof OrchestratorMcpThreadWaitInput.Type;
531
@@ -512,6 +535,8 @@ export const OrchestratorMcpThreadWaitResult = Schema.Struct({
535
status: OrchestratorMcpThreadStatus,
536
timedOut: Schema.Boolean,
537
next: Schema.optional(OrchestratorMcpRunningTaskNext),
538
+ /** With untilDelegatedWorkSettled, once settled: the run whose reply is the thread's result. */
539
+ resultRun: Schema.optional(Schema.Struct({ runId: RunId, status: OrchestrationV2RunStatus })),
540
});
541
export type OrchestratorMcpThreadWaitResult = typeof OrchestratorMcpThreadWaitResult.Type;
542