@devries-cameron20 / t3code Mirror · read-only / commits / 594f1ce2eb
Fork 0

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

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

Synced Nov 22, 14:30 UTC

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