Skip to content

Commit 52d4d3f

Browse files
committed
fix(server): keep delegated review rounds on the task API
1 parent e8545b2 commit 52d4d3f

7 files changed

Lines changed: 46 additions & 7 deletions

File tree

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1510,6 +1510,8 @@ const make = Effect.gen(function* () {
15101510
),
15111511
),
15121512
);
1513+
// Published task results stay terminal. Later child-thread messages do not
1514+
// reopen the task, so cancelling it must not interrupt those separate runs.
15131515
if (isTerminalTaskStatus(current.status)) {
15141516
yield* disposeCompletionDelivery;
15151517
return {

‎apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1651,6 +1651,14 @@ describe("orchestrator MCP toolkit", () => {
16511651
taskId: delegated.taskId,
16521652
status: "completed",
16531653
});
1654+
expect(
1655+
(yield* orchestrator.getThreadProjection(parentThreadId)).subagents.find(
1656+
(task) => task.id === delegated.taskId,
1657+
),
1658+
).toMatchObject({
1659+
result: delegatedResult,
1660+
completionDelivery: { state: "disposed" },
1661+
});
16541662
expect(
16551663
(yield* orchestrator.getThreadProjection(delegated.childThreadId)).runs.find(
16561664
(run) => run.id === activeChildFollowup.runId,

‎apps/server/src/mcp/toolkits/orchestrator/tools.test.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { Tool } from "effect/unstable/ai";
44
import {
55
CreateThreadsTool,
66
DelegateTaskTool,
7+
OrchestratorToolkit,
78
ScheduleTaskTool,
89
ThreadUpdateTool,
910
} from "./tools.ts";
@@ -17,6 +18,16 @@ describe("orchestrator MCP tool guidance", () => {
1718
assert.include(DelegateTaskTool.description ?? "", "waitTimedOut");
1819
assert.include(DelegateTaskTool.description ?? "", "does not cancel the child");
1920
assert.include(DelegateTaskTool.description ?? "", "keep that taskId");
21+
assert.include(DelegateTaskTool.description ?? "", "call delegate_task again");
22+
assert.include(DelegateTaskTool.description ?? "", "childThreadId is backing storage");
23+
assert.include(
24+
OrchestratorToolkit.tools.t3_thread_send.description ?? "",
25+
"Do not use a delegated task's childThreadId to start another review round",
26+
);
27+
assert.include(
28+
OrchestratorToolkit.tools.task_cancel.description ?? "",
29+
"without interrupting later child-thread runs",
30+
);
2031
});
2132

2233
it("documents wait timeout as a parent budget, not a child failure", () => {

‎apps/server/src/mcp/toolkits/orchestrator/tools.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ const OrchestratorCapabilitiesTool = Tool.make("orchestrator_capabilities", {
5757

5858
export const DelegateTaskTool = Tool.make("delegate_task", {
5959
description:
60-
"Delegate one task to a T3-owned child agent/subagent of THIS thread and run it with only the supplied task prompt, without copying parent conversation history. Choose providers and models from orchestrator_capabilities, which uses the same live catalog as the composer. Prefer native subagent tools for same-provider work only when they support the chosen model. Use this for any model missing from the native tool, including same-provider work, for cross-provider work, or for explicitly T3-owned child tasks. The childThreadId is backing storage, not an ordinary top-level thread. Provider, model, model options (see orchestrator_capabilities), runtime mode, and interaction mode inherit unless target overrides them. Prefer mode='async' for long work; mode='wait' blocks until completion or timeout. timeoutMs on mode=wait is only the parent's wait budget and does not cancel the child. waitTimedOut on that wait call means the timeout fired; keep that taskId and read status on later task_status. An async child's completion wakes this thread through a notification, steered into active turns where supported or queued otherwise, so end the turn instead of polling or spawning watchers; use task_status only when the result is needed mid-turn.",
60+
"Delegate one task to a T3-owned child agent/subagent of THIS thread and run it with only the supplied task prompt, without copying parent conversation history. Choose providers and models from orchestrator_capabilities, which uses the same live catalog as the composer. Prefer native subagent tools for same-provider work only when they support the chosen model. Use this for any model missing from the native tool, including same-provider work, for cross-provider work, or for explicitly T3-owned child tasks. For every T3 delegated review round, call delegate_task again with the original brief, prior findings, responses, and unresolved objections in the task prompt. Track each round by its own taskId and use a distinct clientRequestId per round, stable across retries of that round. The childThreadId is backing storage, not the target for starting another delegated review round through t3_thread_send. Provider, model, model options (see orchestrator_capabilities), runtime mode, and interaction mode inherit unless target overrides them. Prefer mode='async' for long work; mode='wait' blocks until completion or timeout. timeoutMs on mode=wait is only the parent's wait budget and does not cancel the child. waitTimedOut on that wait call means the timeout fired; keep that taskId and read status on later task_status. An async child's completion wakes this thread through a notification, steered into active turns where supported or queued otherwise, so end the turn instead of polling or spawning watchers; use task_status only when the result is needed mid-turn.",
6161
parameters: OrchestratorMcpDelegateTaskInput,
6262
success: OrchestratorMcpDelegateTaskResult,
6363
failure: OrchestratorMcpFailure,
@@ -70,7 +70,7 @@ export const DelegateTaskTool = Tool.make("delegate_task", {
7070

7171
const TaskStatusTool = Tool.make("task_status", {
7272
description:
73-
"Read a T3-owned delegated task created by this parent thread. childRunId identifies the original delegated run. workState distinguishes working, waiting_for_children, and result_available; a completed turn with live nested work is not a completed task. summary is the final task result, including provider errors on failure, and remains stable after publication. hasPendingChildRuns reports later queued or executing turns; latestTerminal* provides later non-monitor turn results. Reading a terminal result acknowledges its automatic parent delivery.",
73+
"Read a T3-owned delegated task created by this parent thread. childRunId identifies the original delegated run. workState distinguishes working, waiting_for_children, and result_available; a completed turn with live nested work is not a completed task. summary is the final task result, including provider errors on failure, and remains stable after publication. hasPendingChildRuns reports later queued or executing turns in the backing child thread, even after the task is terminal; it does not reopen the task or extend task_cancel to those turns. latestTerminal* provides later non-monitor turn results. Reading a terminal result acknowledges its automatic parent delivery.",
7474
parameters: OrchestratorMcpTaskStatusInput,
7575
success: OrchestratorMcpDelegateTaskResult,
7676
failure: OrchestratorMcpFailure,
@@ -84,7 +84,7 @@ const TaskStatusTool = Tool.make("task_status", {
8484

8585
const TaskCancelTool = Tool.make("task_cancel", {
8686
description:
87-
"Request interruption of an active T3-owned delegated task and dispose its automatic parent delivery. Completed task results remain available.",
87+
"Request interruption of an active T3-owned delegated task and dispose its automatic parent delivery. For a terminal task, return its existing status and dispose delivery without interrupting later child-thread runs, even when task_status reports hasPendingChildRuns=true. Published task results remain available. Use t3_thread_interrupt for a later active run.",
8888
parameters: OrchestratorMcpTaskCancelInput,
8989
success: OrchestratorMcpTaskCancelResult,
9090
failure: OrchestratorMcpFailure,
@@ -200,7 +200,7 @@ export const ThreadUpdateTool = Tool.make("t3_thread_update", {
200200

201201
const ThreadSendTool = Tool.make("t3_thread_send", {
202202
description:
203-
"Send a message to a T3 thread in the calling project. mode='auto' starts an idle thread, steers a fully active turn, or queues behind a turn that is not yet steerable. Use queue for a separate follow-up turn, steer for an in-flight update, or restart to interrupt-and-restart the active turn. clientRequestId makes retries idempotent.",
203+
"Send a message to a T3 thread in the calling project. Do not use a delegated task's childThreadId to start another review round here; use delegate_task with the full review context and a new clientRequestId for that round. Thread messages do not create a new delegated task or reopen a completed task. mode='auto' starts an idle thread, steers a fully active turn, or queues behind a turn that is not yet steerable. Use queue for a separate follow-up turn, steer for an in-flight update, or restart to interrupt-and-restart the active turn. clientRequestId makes retries idempotent.",
204204
parameters: OrchestratorMcpThreadSendInput,
205205
success: OrchestratorMcpThreadSendResult,
206206
failure: OrchestratorMcpFailure,

‎apps/server/src/provider/T3OrchestrationInstructions.test.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,11 @@ describe("T3 orchestration provider instructions", () => {
1313
assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, "ordinary top-level T3 conversations");
1414
assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, "Never use them merely");
1515
assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, "cross-provider");
16+
assert.include(T3_CODE_ORCHESTRATION_INSTRUCTIONS, "call `delegate_task` again");
17+
assert.include(
18+
T3_CODE_ORCHESTRATION_INSTRUCTIONS,
19+
"Do not use `t3_thread_send` on `childThreadId`",
20+
);
1621
});
1722

1823
it("documents structured schedules instead of JSON strings", () => {

‎apps/server/src/provider/T3OrchestrationInstructions.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ export const T3_CODE_ORCHESTRATION_INSTRUCTIONS = `
66
77
The \`t3-code\` MCP server provides app-owned orchestration. Treat these concepts distinctly:
88
9-
- A delegated task/subagent is child work owned by the current thread. Use \`orchestrator_capabilities\` to discover the current provider/model IDs from the same live catalog as the composer, including configured custom models. Do not treat a native tool's model list as the full list of available subagent models. Prefer native subagent tools for same-provider work only when they support the chosen model. Use \`delegate_task\` with that provider instance and model when native tools cannot, including for same-provider work. Also use \`delegate_task\` for cross-provider or explicitly T3-owned child tasks. Retain each returned \`taskId\`, and use \`task_status\` or \`task_cancel\` to manage it. The returned \`childThreadId\` is backing storage for the subagent; do not replace delegation with ordinary thread creation.
9+
- A delegated task/subagent is child work owned by the current thread. Use \`orchestrator_capabilities\` to discover the current provider/model IDs from the same live catalog as the composer, including configured custom models. Do not treat a native tool's model list as the full list of available subagent models. Prefer native subagent tools for same-provider work only when they support the chosen model. Use \`delegate_task\` with that provider instance and model when native tools cannot, including for same-provider work. Also use \`delegate_task\` for cross-provider or explicitly T3-owned child tasks. Retain each returned \`taskId\`, and use \`task_status\` or \`task_cancel\` to manage it. The returned \`childThreadId\` is backing storage for the subagent, not the target for starting another delegated review round.
1010
- \`t3_thread_launch\` and \`create_threads\` create ordinary top-level T3 conversations. Use them only when the user explicitly asks for separate/new/top-level threads or conversations. Never use them merely because the user said "subagent" or requested parallel delegated work.
11+
- For every T3 delegated review round, call \`delegate_task\` again. Include the original brief, prior findings, responses, and unresolved objections in each new task prompt. Track each round by its own \`taskId\`. Use a distinct \`clientRequestId\` per round, stable across retries of that round. Do not use \`t3_thread_send\` on \`childThreadId\` to continue a delegated review.
1112
- \`schedule_task\` creates persistent recurring work in the app scheduler. Pass \`schedule\` as a structured object, never as JSON text: \`{"type":"interval","everyMs":3600000}\` for an interval, or \`{"type":"fixed_time","timeOfDay":"09:00","weekdays":[1,2,3,4,5]}\` for a wall-clock schedule. By default runs return to the current thread; set \`bindToCurrentThread=false\` only when the user wants a fresh thread for every run. After scheduling, report the returned cadence and next run time.
1213
1314
### Choose the workspace before starting a new thread

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

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,14 @@ that driver; an explicit `providerInstanceId` is honored exactly and fails
228228
when unavailable. Selecting a different provider without a model uses that
229229
provider's first advertised model.
230230

231+
Each delegated review round uses a new `delegate_task` call with the original brief,
232+
prior findings, responses, and unresolved objections. Track each round by its own `taskId` and use
233+
a distinct `clientRequestId` per round, stable across retries of that round.
234+
`childThreadId` is backing storage, not a target for another review round through
235+
`t3_thread_send`. Ordinary thread messaging remains available for user-requested
236+
conversations; it does not reopen a completed task. There is no task-level follow-up
237+
API for preserving the same reviewer session.
238+
231239
Delegation requires an active parent run owned by the MCP credential's
232240
provider session. The request becomes the V2 command
233241
`delegated_task.request`.
@@ -272,8 +280,12 @@ the published task result.
272280
### `task_cancel`
273281

274282
Interrupts the currently active task run through the normal V2 `run.interrupt`
275-
command. Native background work between turns currently has no interruptible run. It is idempotent for terminal tasks and accepts an optional cancellation
276-
reason. Use `t3_thread_interrupt` to interrupt a later follow-up run.
283+
command and disposes automatic parent delivery. Native background work between
284+
turns currently has no interruptible run. For a terminal task, it returns the
285+
existing status and disposes delivery without interrupting later child-thread runs,
286+
even when `task_status` reports `hasPendingChildRuns: true`. Published task results
287+
remain available. It accepts an optional cancellation reason. Use
288+
`t3_thread_interrupt` to stop a later active run.
277289

278290
### `create_threads`
279291

0 commit comments

Comments
 (0)