fix(server): schedule_task no longer tells agents every run returns to their thread

[tiliakoos]

Problem

Since #15219, schedule_task without bindToCurrentThread posts runs into the calling thread only when the task is in that thread's own project; anywhere else each run launches a fresh thread, and an explicit true is rejected. The field's published description and the orchestration instructions still tell agents runs return to this thread by default, so an agent scheduling into another project tells the user results will arrive here, and they don't. Closes #16185.

Change

Text only, no behaviour change; in the contracts it is an annotation, and the schema type is unchanged. The field description and its JSDoc in packages/contracts/src/orchestratorMcp.ts, and the sentence in T3_CODE_ORCHESTRATION_INSTRUCTIONS, now state the default scheduleTask applies, in the terms the schedule_task tool description already uses. The instructions constant is shared by every provider's path, so one edit covers them all.

The triage also points at #15699 (docs) and #15913 (telemetry), which carry the same older assumption. They are open pull requests of their own, so they are left alone here.

Scope and approval

Triaged bug #16185, confirmed on main with these files named: #16185 (comment)

Verification

• vp test run apps/server/src/mcp/toolkits/orchestrator/tools.test.ts packages/provider-core/src/server/orchestrationInstructions.test.ts: the two new tests fail on main (2 failed, 10 passed) and pass with the change (12 passed). One reads the schema through Tool.getJsonSchema(ScheduleTaskTool), which is what McpHttpServer serves as the tool's inputSchema; the other reads the instructions constant.

• The text agents receive, printed from the same two sources.

  Before:

  bindToCurrentThread: True (default) posts each run into this thread; false creates a fresh top-level thread per run.
  instructions: By default runs return to the current thread, which suits orchestrating: each trigger arrives here and you delegate or dedupe; set `bindToCurrentThread=false` only when the user wants a fresh thread for every run.
  

  After:

  bindToCurrentThread: In this thread's project, true (the default) posts each run into this thread and false creates a fresh top-level thread per run. In another project, or without a calling thread, each run launches a fresh thread and true is rejected.
  instructions: In this thread's project, runs return to the current thread by default, which suits orchestrating: each trigger arrives here and you delegate or dedupe; set `bindToCurrentThread=false` only when the user wants a fresh thread for every run. A task scheduled into another project launches a fresh thread for every run.
  

• The new text matches scheduleTask in apps/server/src/mcp/OrchestratorMcpService.ts: input.bindToCurrentThread ?? (parent !== undefined && parent.thread.projectId === projectId), with invalid_request for an explicit true without a calling thread or in another project.

• vp lint and vp fmt --check on the four files, and the @t3tools/contracts and server typechecks, pass.

• Not checked: an agent reading the new text in a running app. Nothing but the text changes.

Claude Opus 5.5 via T3 Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[macroscopeapp]

Approvability

Verdict: Approved at f62ac0b

Macroscope's review found this PR approvable — This is a narrowly scoped guidance and schema-description correction with tests; the scheduler’s actual default behavior and implementation are unchanged. Its only runtime effect is improving agent instructions for cross-project scheduling, with no new capability or production-side effect.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

Pre-merge checks failed. Please resolve the failing checks before merging.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Advanced
• Run ID: 1e9a8fe1-d2a4-4cca-91a2-19a892bb72e7

📥 Commits

Reviewing files that changed from the base of the PR and between 611132c and f62ac0b.

📒 Files selected for processing (4)

• apps/server/src/mcp/toolkits/orchestrator/tools.test.ts
• apps/server/src/provider/T3OrchestrationInstructions.test.ts
• apps/server/src/provider/T3OrchestrationInstructions.ts
• packages/contracts/src/orchestratorMcp.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The bindToCurrentThread schema description and orchestration instructions now distinguish scheduled runs in the calling thread’s project from runs in another project or without a calling thread. Tests check the updated guidance.

Changes

Scheduled task thread-default guidance

Layer / File(s)	Summary
Update thread-default guidance and tests packages/contracts/src/orchestratorMcp.ts, apps/server/src/provider/T3OrchestrationInstructions.ts, apps/server/src/mcp/toolkits/orchestrator/tools.test.ts, apps/server/src/provider/T3OrchestrationInstructions.test.ts	The schema description and orchestration instructions state that runs in the calling thread’s project use that thread by default. Runs in another project or without a calling thread launch a fresh thread per run. Tests check the updated descriptions.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~5 minutes

Change: Other · Severity of issue fixed: Low

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to f62ac

The updated guidance matches the existing scheduling behavior, and no material merge risk remains.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore (reviewers only)

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Approvability		The pull request changes agent instructions in apps/server/src/provider/T3OrchestrationInstructions.ts. The changed T3_CODE_ORCHESTRATION_INSTRUCTIONS text is consumed by Codex, Claude, Pi, and AC…	This pull request needs a maintainer's review. Review the revised schedule_task guidance in apps/server/src/provider/T3OrchestrationInstructions.ts before approval.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Issue #16185 requires agent-facing documentation to describe the project-dependent default for bindToCurrentThread. The schema test checks the generated ScheduleTaskTool input schema. The updated …
Out of Scope Changes check		The reported changes are limited to the bindToCurrentThread documentation, the shared orchestration instruction text, and tests for those two outputs. Each change supports issue #16185. No unrelated…
Description check		The description includes complete Problem, Change, Scope and approval, and Verification sections. It explains the behavior mismatch, the text-only fix, the linked issue and approval, focused test resu…
Title check		The title clearly summarizes the main change: correcting agent-facing guidance so schedule_task no longer incorrectly says every run returns to the current thread.

Full details: Approvability

Explanation

The pull request changes agent instructions in apps/server/src/provider/T3OrchestrationInstructions.ts. The changed T3_CODE_ORCHESTRATION_INSTRUCTIONS text is consumed by Codex, Claude, Pi, and ACP provider prompts. This matches the rule that changes to agent instructions require maintainer review.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}