Skip to content

Commit d372d3d

Browse files
fjooordclaude
andcommitted
fix(server): agents can see a thread's pending background work
t3_thread_list and t3_thread_read reported a thread as completed while it still waited on a subagent, an awaited command or monitor, or another thread, so an agent could not tell it from a thread that was done. The sidebar shows these threads as Waiting from the shell's blockedOnThreadWait and pendingBackgroundTasks. List and read results now carry both fields from the thread shell. Each task exposes taskId, kind, description, awaited, and a subagent's childThreadId, and leaves out provider-internal links. Both fields are optional in the contract, so results forwarded from older linked environments still decode. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent bbdc7dc commit d372d3d

6 files changed

Lines changed: 141 additions & 3 deletions

File tree

‎apps/server/src/mcp/OrchestratorMcpService.activity.test.ts‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,19 @@ it("readThread preserves caller access errors and prefers activity-run status ov
165165
? Effect.die("A failed caller read must not reach the target")
166166
: Effect.succeed(
167167
threadId === parentThreadId
168-
? (projection.thread as unknown as OrchestrationV2ThreadShell)
168+
? ({
169+
...projection.thread,
170+
blockedOnThreadWait: true,
171+
pendingBackgroundTasks: [
172+
{
173+
taskId: "task-subagent",
174+
kind: "subagent",
175+
parentTaskId: "task-parent",
176+
providerInstanceId: parentInstanceId,
177+
childThreadId,
178+
},
179+
],
180+
} as unknown as OrchestrationV2ThreadShell)
169181
: null,
170182
),
171183
getProjectThreadRecords: (input) =>
@@ -197,6 +209,10 @@ it("readThread preserves caller access errors and prefers activity-run status ov
197209
expect(result.thread.status).toBe("running");
198210
expect(result.thread.latestRunId).toBe(cancelledRunId);
199211
expect(result.thread.activeRunId).toBe(activeRunId);
212+
expect(result.thread.blockedOnThreadWait).toBe(true);
213+
expect(result.thread.pendingBackgroundTasks).toEqual([
214+
{ taskId: "task-subagent", kind: "subagent", childThreadId },
215+
]);
200216

201217
callerUnavailable = true;
202218
const denied = yield* service

‎apps/server/src/mcp/OrchestratorMcpService.test.ts‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3528,16 +3528,30 @@ describe("OrchestratorMcpService thread list", () => {
35283528
capabilities: new Set(["orchestration"]),
35293529
issuedAt: 1,
35303530
};
3531-
const shell = (id: string, projectId: string, snoozed: boolean) => ({
3531+
const shell = (id: string, projectId: string, snoozed: boolean, waiting = false) => ({
35323532
...liveThreadShell(ThreadId.make(id)),
35333533
projectId: ProjectId.make(projectId),
35343534
status: "completed" as const,
35353535
snoozedUntil: snoozed ? DateTime.makeUnsafe("2099-01-01T00:00:00Z") : null,
3536+
blockedOnThreadWait: waiting,
3537+
pendingBackgroundTasks: waiting
3538+
? [
3539+
{
3540+
taskId: "task-subagent",
3541+
kind: "subagent" as const,
3542+
description: "Review the diff",
3543+
parentTaskId: "task-parent",
3544+
providerInstanceId: ProviderInstanceId.make("codex"),
3545+
childThreadId: ThreadId.make("thread:b-child"),
3546+
},
3547+
{ taskId: "task-tests", kind: "command" as const, awaited: true as const },
3548+
]
3549+
: [],
35363550
});
35373551
const shells = [
35383552
shell("thread:a-snoozed", "project:a", true),
35393553
shell("thread:a-awake", "project:a", false),
3540-
shell("thread:b-snoozed", "project:b", true),
3554+
shell("thread:b-snoozed", "project:b", true, true),
35413555
];
35423556
const service = layerOrchestratorService.pipe(
35433557
Layer.provide(
@@ -3581,6 +3595,24 @@ describe("OrchestratorMcpService thread list", () => {
35813595
["thread:b-snoozed", "project:b"],
35823596
],
35833597
);
3598+
assert.deepStrictEqual(
3599+
listed.threads.map((thread) => [thread.blockedOnThreadWait, thread.pendingBackgroundTasks]),
3600+
[
3601+
[false, []],
3602+
[
3603+
true,
3604+
[
3605+
{
3606+
taskId: "task-subagent",
3607+
kind: "subagent",
3608+
description: "Review the diff",
3609+
childThreadId: ThreadId.make("thread:b-child"),
3610+
},
3611+
{ taskId: "task-tests", kind: "command", awaited: true },
3612+
],
3613+
],
3614+
],
3615+
);
35843616
}).pipe(Effect.provide(service)),
35853617
);
35863618
});

‎apps/server/src/mcp/OrchestratorMcpService.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -783,6 +783,24 @@ function threadSnooze(
783783
};
784784
}
785785

786+
// Provider-internal links (parentTaskId, providerInstanceId) stay out of agent results.
787+
function threadBackgroundWork(
788+
thread: Pick<OrchestrationV2ThreadShell, "blockedOnThreadWait" | "pendingBackgroundTasks">,
789+
): Required<Pick<OrchestratorMcpThreadListItem, "blockedOnThreadWait" | "pendingBackgroundTasks">> {
790+
return {
791+
blockedOnThreadWait: thread.blockedOnThreadWait === true,
792+
pendingBackgroundTasks: (thread.pendingBackgroundTasks ?? []).map((task) => ({
793+
taskId: task.taskId,
794+
kind: task.kind,
795+
...(task.description === undefined ? {} : { description: task.description }),
796+
...(task.awaited === undefined ? {} : { awaited: task.awaited }),
797+
...(task.kind === "subagent" && task.childThreadId !== undefined
798+
? { childThreadId: task.childThreadId }
799+
: {}),
800+
})),
801+
};
802+
}
803+
786804
function threadPullRequests(
787805
links: OrchestrationV2ThreadShell["pullRequests"],
788806
): OrchestratorMcpThreadPullRequest[] {
@@ -818,6 +836,7 @@ function listItemFromShell(
818836
pullRequests: threadPullRequests(shell.pullRequests),
819837
...threadSettlement(shell),
820838
...threadSnooze(shell, nowMs),
839+
...threadBackgroundWork(shell),
821840
parentThreadId: shell.lineage.parentThreadId,
822841
relationshipToParent: shell.lineage.relationshipToParent,
823842
itemCount: shell.visibleItemCount,
@@ -871,6 +890,7 @@ function threadDetail(
871890
archived: projection.thread.archivedAt !== null,
872891
...threadSettlement(projection.thread),
873892
...threadSnooze(shell, nowMs),
893+
...threadBackgroundWork(shell),
874894
createdAt: DateTime.formatIso(projection.thread.createdAt),
875895
updatedAt: DateTime.formatIso(projection.thread.updatedAt),
876896
};

‎docs/orchestration-v2/orchestrator-mcp-server.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -422,6 +422,12 @@ client's `effectiveSnoozed`, so agents and the sidebar agree: a snoozed thread
422422
wakes early only when it has a pending request or fails after snoozing. Completed
423423
runs, background wakes, and delegated completions keep it snoozed.
424424

425+
They also report `blockedOnThreadWait` and `pendingBackgroundTasks`, the shell
426+
fields behind the sidebar's Waiting label, so an agent can tell a `completed`
427+
thread that still waits on background work from one that is done. A subagent or
428+
`background_task` holds the thread. A command or monitor holds it only with
429+
`awaited: true`, since agents often leave a dev server running.
430+
425431
### `t3_thread_update`
426432

427433
Updates metadata for the calling thread or any other thread in the environment.

‎packages/contracts/src/orchestratorMcp.test.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,57 @@ import * as Schema from "effect/Schema";
44
import {
55
OrchestratorMcpDelegateTaskInput,
66
OrchestratorMcpDelegateTaskResult,
7+
OrchestratorMcpThreadDetail,
8+
OrchestratorMcpThreadListItem,
79
} from "./orchestratorMcp.ts";
810

911
const decodeDelegateTaskInput = Schema.decodeUnknownSync(OrchestratorMcpDelegateTaskInput);
1012
const decodeDelegateTaskResult = Schema.decodeUnknownSync(OrchestratorMcpDelegateTaskResult);
13+
const decodeThreadListItem = Schema.decodeUnknownSync(OrchestratorMcpThreadListItem);
14+
const decodeThreadDetail = Schema.decodeUnknownSync(OrchestratorMcpThreadDetail);
1115

1216
describe("orchestrator MCP contracts", () => {
17+
it("decodes thread results from a linked environment that predates background work", () => {
18+
const listItem = {
19+
threadId: "thread-1",
20+
projectId: "project-1",
21+
title: "Fix the build",
22+
createdBy: "user",
23+
creationSource: "web",
24+
status: "completed",
25+
latestRunId: null,
26+
providerInstanceId: "codex",
27+
model: "gpt-5.4",
28+
runtimeMode: "full-access",
29+
interactionMode: "default",
30+
linkedPullRequest: null,
31+
settled: false,
32+
settledAt: null,
33+
snoozed: false,
34+
snoozedUntil: null,
35+
parentThreadId: null,
36+
relationshipToParent: null,
37+
itemCount: 0,
38+
createdAt: "2026-01-01T00:00:00.000Z",
39+
updatedAt: "2026-01-01T00:00:00.000Z",
40+
};
41+
const detail = {
42+
...listItem,
43+
activeRunId: null,
44+
titleRegeneration: null,
45+
branch: null,
46+
worktreePath: null,
47+
runCount: 0,
48+
pendingRequestCount: 0,
49+
archived: false,
50+
};
51+
52+
for (const decoded of [decodeThreadListItem(listItem), decodeThreadDetail(detail)]) {
53+
expect(decoded.blockedOnThreadWait).toBeUndefined();
54+
expect(decoded.pendingBackgroundTasks).toBeUndefined();
55+
}
56+
});
57+
1358
it("decodes cross-provider delegated task requests and durable results", () => {
1459
const request = decodeDelegateTaskInput({
1560
task: "Inspect the workspace and report the result.",

‎packages/contracts/src/orchestratorMcp.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -360,6 +360,17 @@ export const OrchestratorMcpThreadPullRequest = Schema.Struct({
360360
});
361361
export type OrchestratorMcpThreadPullRequest = typeof OrchestratorMcpThreadPullRequest.Type;
362362

363+
/** Background work still open on the thread, as its provider reported it. */
364+
export const OrchestratorMcpThreadBackgroundTask = Schema.Struct({
365+
taskId: TrimmedNonEmptyString,
366+
kind: Schema.Literals(["subagent", "command", "monitor", "background_task"]),
367+
description: Schema.optional(TrimmedNonEmptyString),
368+
/** The agent waits on this command or monitor. Other kinds always hold the thread. */
369+
awaited: Schema.optional(Schema.Literal(true)),
370+
childThreadId: Schema.optional(ThreadId),
371+
});
372+
export type OrchestratorMcpThreadBackgroundTask = typeof OrchestratorMcpThreadBackgroundTask.Type;
373+
363374
export const OrchestratorMcpThreadListItem = Schema.Struct({
364375
threadId: ThreadId,
365376
projectId: ProjectId,
@@ -379,6 +390,10 @@ export const OrchestratorMcpThreadListItem = Schema.Struct({
379390
settledAt: Schema.NullOr(IsoDateTime),
380391
snoozed: Schema.Boolean,
381392
snoozedUntil: Schema.NullOr(IsoDateTime),
393+
/** Absent from linked environments that predate it. */
394+
blockedOnThreadWait: Schema.optional(Schema.Boolean),
395+
/** Absent from linked environments that predate it. */
396+
pendingBackgroundTasks: Schema.optional(Schema.Array(OrchestratorMcpThreadBackgroundTask)),
382397
parentThreadId: Schema.NullOr(ThreadId),
383398
relationshipToParent: Schema.NullOr(Schema.Literals(["fork", "subagent"])),
384399
itemCount: NonNegativeInt,
@@ -459,6 +474,10 @@ export const OrchestratorMcpThreadDetail = Schema.Struct({
459474
settledAt: Schema.NullOr(IsoDateTime),
460475
snoozed: Schema.Boolean,
461476
snoozedUntil: Schema.NullOr(IsoDateTime),
477+
/** Absent from linked environments that predate it. */
478+
blockedOnThreadWait: Schema.optional(Schema.Boolean),
479+
/** Absent from linked environments that predate it. */
480+
pendingBackgroundTasks: Schema.optional(Schema.Array(OrchestratorMcpThreadBackgroundTask)),
462481
createdAt: IsoDateTime,
463482
updatedAt: IsoDateTime,
464483
});

0 commit comments

Comments
 (0)