From b2e134a15e957c124df0b819c75752fac6f8622f Mon Sep 17 00:00:00 2001 From: Julius Marminge Date: Thu, 22 Oct 2026 00:32:10 +0000 Subject: [PATCH 1/5] docs(mcp): orchestrator MCP doc points at the toolkit and covers scheduled tasks The doc said the server exposes eleven orchestration tools, but OrchestratorToolkit registers seventeen and the doc never mentioned recurring scheduling. Drop the hardcoded count, link the toolkit as the authoritative list, note that t3_thread_launch belongs to the project toolkit, and add a short note on the scheduled-task tools. Co-Authored-By: Claude Opus 5.5 --- .../orchestrator-mcp-server.md | 22 ++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/orchestration-v2/orchestrator-mcp-server.md b/docs/orchestration-v2/orchestrator-mcp-server.md index 5f312b61bd2aa..f41056756d124 100644 --- a/docs/orchestration-v2/orchestrator-mcp-server.md +++ b/docs/orchestration-v2/orchestrator-mcp-server.md @@ -11,8 +11,9 @@ agent can use this endpoint to: - create one or more ordinary top-level T3 threads; - list a project's threads and incrementally read any thread; - rename threads, regenerate titles, and link or unlink pull requests; -- send or steer follow-up messages; and -- wait for or interrupt ordinary thread runs. +- send or steer follow-up messages; +- wait for or interrupt ordinary thread runs; and +- schedule recurring work that runs without an active turn. These are T3 orchestration operations, not provider-native sub-agent APIs. Delegated tasks always create a T3 child thread and run. The child receives @@ -192,7 +193,12 @@ provider selection model-visible without allowing a request that cannot run. ## Tool Surface -The server exposes eleven orchestration tools. +`OrchestratorToolkit` in +[`toolkits/orchestrator/tools.ts`](../../apps/server/src/mcp/toolkits/orchestrator/tools.ts) +is the authoritative list of orchestration tools. The sections below cover +delegation and thread tools. `t3_thread_launch` is documented with them but +registered by the project toolkit in +[`toolkits/project/tools.ts`](../../apps/server/src/mcp/toolkits/project/tools.ts). ### `orchestrator_capabilities` @@ -445,6 +451,16 @@ Without `runId`, it selects the newest interruptible run. A terminal run is returned unchanged, and a thread with no active provider turn returns `no_active_run`. +### Scheduled tasks + +`schedule_task`, `list_scheduled_tasks`, `update_scheduled_task`, and +`delete_scheduled_task` manage recurring work in the app scheduler. A schedule +runs its prompt on an interval, at a fixed local time, or on each webhook +request, even when no turn is active. In the caller's project, runs post into +the calling thread by default, so an orchestrator sees every trigger; +otherwise each run launches a fresh thread. Pausing uses +`update_scheduled_task` with `enabled: false`; deletion is permanent. + ## Delegated Task Lifecycle The MCP server is a command ingress into V2. It does not call provider adapters From a29438ea97fa041c0784f3969cdf5bd4bd64594b Mon Sep 17 00:00:00 2001 From: Julius Marminge Date: Thu, 22 Oct 2026 00:36:00 +0000 Subject: [PATCH 2/5] docs(mcp): scheduled-task note states webhook gates, server time zone, and unbound runs Co-Authored-By: Claude Opus 5.5 --- docs/orchestration-v2/orchestrator-mcp-server.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/orchestration-v2/orchestrator-mcp-server.md b/docs/orchestration-v2/orchestrator-mcp-server.md index f41056756d124..f0055d5e586f5 100644 --- a/docs/orchestration-v2/orchestrator-mcp-server.md +++ b/docs/orchestration-v2/orchestrator-mcp-server.md @@ -455,11 +455,14 @@ returned unchanged, and a thread with no active provider turn returns `schedule_task`, `list_scheduled_tasks`, `update_scheduled_task`, and `delete_scheduled_task` manage recurring work in the app scheduler. A schedule -runs its prompt on an interval, at a fixed local time, or on each webhook -request, even when no turn is active. In the caller's project, runs post into -the calling thread by default, so an orchestrator sees every trigger; -otherwise each run launches a fresh thread. Pausing uses -`update_scheduled_task` with `enabled: false`; deletion is permanent. +runs its prompt on an interval, at a fixed time in the server's local time +zone, or on each qualifying webhook request, even when no turn is active. +Signature checks, filters, and dedupe can skip a webhook request. For a task +in the caller's project, runs post into the calling thread by default, so an +orchestrator sees every trigger. With `bindToCurrentThread: false`, or for a +task in another project, each run launches a fresh thread in the task's +project. Pausing uses `update_scheduled_task` with `enabled: false`; deletion +is permanent. ## Delegated Task Lifecycle From 5e586c9e17e3e63daecf622d4bea57bf28b7900d Mon Sep 17 00:00:00 2001 From: Julius Marminge Date: Thu, 22 Oct 2026 03:06:15 +0000 Subject: [PATCH 3/5] docs(mcp): scheduled-task note warns that unsigned webhook URLs trigger runs Co-Authored-By: Claude Opus 5.5 --- docs/orchestration-v2/orchestrator-mcp-server.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/orchestration-v2/orchestrator-mcp-server.md b/docs/orchestration-v2/orchestrator-mcp-server.md index f0055d5e586f5..fd6d56af4f0fb 100644 --- a/docs/orchestration-v2/orchestrator-mcp-server.md +++ b/docs/orchestration-v2/orchestrator-mcp-server.md @@ -457,6 +457,7 @@ returned unchanged, and a thread with no active provider turn returns `delete_scheduled_task` manage recurring work in the app scheduler. A schedule runs its prompt on an interval, at a fixed time in the server's local time zone, or on each qualifying webhook request, even when no turn is active. +Without a signature, anyone with the webhook URL can trigger a run. Signature checks, filters, and dedupe can skip a webhook request. For a task in the caller's project, runs post into the calling thread by default, so an orchestrator sees every trigger. With `bindToCurrentThread: false`, or for a From 551f891efbb4d5a8ca1ee57560f6b4eac800676d Mon Sep 17 00:00:00 2001 From: Julius Marminge Date: Thu, 22 Oct 2026 03:29:24 +0000 Subject: [PATCH 4/5] docs: clarify scheduled task thread binding defaults --- docs/orchestration-v2/orchestrator-mcp-server.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/orchestration-v2/orchestrator-mcp-server.md b/docs/orchestration-v2/orchestrator-mcp-server.md index fd6d56af4f0fb..1bfaf09fb8870 100644 --- a/docs/orchestration-v2/orchestrator-mcp-server.md +++ b/docs/orchestration-v2/orchestrator-mcp-server.md @@ -458,12 +458,13 @@ returned unchanged, and a thread with no active provider turn returns runs its prompt on an interval, at a fixed time in the server's local time zone, or on each qualifying webhook request, even when no turn is active. Without a signature, anyone with the webhook URL can trigger a run. -Signature checks, filters, and dedupe can skip a webhook request. For a task -in the caller's project, runs post into the calling thread by default, so an -orchestrator sees every trigger. With `bindToCurrentThread: false`, or for a -task in another project, each run launches a fresh thread in the task's -project. Pausing uses `update_scheduled_task` with `enabled: false`; deletion -is permanent. +Signature checks, filters, and dedupe can skip a webhook request. +`bindToCurrentThread` defaults to `true` only when the caller has a thread in +the task's project; otherwise it defaults to `false`. Bound runs post into +that thread; unbound runs each launch a fresh thread in the task's project. +Explicit `bindToCurrentThread: true` without a caller thread in that project +is rejected. Pausing uses `update_scheduled_task` with `enabled: false`; +deletion is permanent. ## Delegated Task Lifecycle From a732067e4d0e19dfab61bd5bf19e6acf165106b0 Mon Sep 17 00:00:00 2001 From: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com> Date: Mon, 2 Nov 2026 18:05:36 -0800 Subject: [PATCH 5/5] docs(mcp): scheduled task updates go through schedule_task Co-Authored-By: Claude Opus 5.5 --- docs/orchestration-v2/orchestrator-mcp-server.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/orchestration-v2/orchestrator-mcp-server.md b/docs/orchestration-v2/orchestrator-mcp-server.md index 04c6de2838ba6..915fa59ab22d0 100644 --- a/docs/orchestration-v2/orchestrator-mcp-server.md +++ b/docs/orchestration-v2/orchestrator-mcp-server.md @@ -466,8 +466,9 @@ returned unchanged, and a thread with no active provider turn returns ### Scheduled tasks -`schedule_task`, `list_scheduled_tasks`, `update_scheduled_task`, and -`delete_scheduled_task` manage recurring work in the app scheduler. A schedule +`schedule_task`, `list_scheduled_tasks`, and `delete_scheduled_task` manage +recurring work in the app scheduler; `schedule_task` with a `scheduledTaskId` +updates an existing task. A schedule runs its prompt on an interval, at a fixed time in the server's local time zone, or on each qualifying webhook request, even when no turn is active. Without a signature, anyone with the webhook URL can trigger a run. @@ -476,7 +477,7 @@ Signature checks, filters, and dedupe can skip a webhook request. the task's project; otherwise it defaults to `false`. Bound runs post into that thread; unbound runs each launch a fresh thread in the task's project. Explicit `bindToCurrentThread: true` without a caller thread in that project -is rejected. Pausing uses `update_scheduled_task` with `enabled: false`; +is rejected. Pausing uses `schedule_task` with `scheduledTaskId` and `enabled: false`; deletion is permanent. ## Delegated Task Lifecycle