feat(mcp): add create_and_run_session tool

[yonch]

Adds a create_and_run_session MCP tool that combines session creation and prompt execution into a single call, simplifying orchestrator workflows.

---

Note

Medium Risk
Adds a new session/execution entrypoint that changes orchestrator workflows and error handling around session creation vs. prompt execution; failures could leave partially-created sessions or unexpected executor behavior if not well tested.

Overview
Adds a new MCP tool, create_and_run_session, that creates a session and immediately starts a coding-agent execution in that session, returning both the session_id and execution_id plus serialized session/execution details.

The tool validates non-empty prompts, resolves/scope-checks workspace_id, normalizes the requested executor, and includes a fallback error path that still returns the created session_id if execution startup fails (to avoid orphaned sessions). Orchestrator-mode tool exposure is updated via tests to include create_and_run_session.

^{Reviewed by Cursor Bugbot for commit 1f9ce11. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Juanlucasbg]

Aggressive review summary — PR #3368

134-line addition to crates/mcp/src/task_server/tools/sessions.rs exposing a new MCP tool create_and_run_session that combines the existing create_session + run_session_prompt into one call. Verdict: clean — recommend merge.

Why the change is correct

The two-step orchestration is exactly what every MCP caller has to write today: POST /api/sessions → take the returned session_id → POST /api/sessions/{id}/follow-up. Bundling it removes a roundtrip and an error path from every caller.

The implementation gates correctly:

• prompt.trim() rejected if empty.
• resolve_workspace_id + scope_allows_workspace enforce the orchestrator-MCP workspace scope.
• normalize_executor_name validates the executor up front before creating the session — so a typo in the executor name doesn't leave an orphaned session.
• name is trimmed, with empty trimmed → None.

Findings

• Adversarial — PASS: The notable design choice is the failure-after-step-1 path:

  // Session was created but prompt failed. Return the session_id
  // so callers can retry with run_session_prompt instead of
  // accumulating orphaned sessions.

  This is the right call — atomic creation isn't possible across two HTTP endpoints, so exposing the orphaned session_id lets the caller decide (retry, delete, or surface to user). The error payload also includes a note explaining the recovery flow. Strong.
• Structural — PASS: Mirrors the existing run_session_prompt and create_session shape. Reuses FollowUpPayload, ExecutorConfigPayload, serialize_execution_process, session_summary. Well-integrated.
• Security — PASS: Goes through the same scope_allows_workspace gate as the individual tools. No new auth surface.
• Conventions — PASS: #[tool(description=...)] macro with a clear description. Test in mod.rs updated to include the new tool name.

NITs

• Hardcoded None for model_id / agent_id / reasoning_id (lines 281-285 in the diff). PR feat(mcp): expose model_id, agent_id, reasoning_id on start_workspace #3382 added these as parameters on start_workspace's schema. The maintainer should pick a consistent surface — either expose them on this new tool too, or document the tradeoff (e.g. "use start_workspace if you need model overrides; this tool is for default-config sessions").
• No test for the new tool itself, only its presence in the tool list. A #[tokio::test] that drives the tool via the MCP client (or at minimum unit-tests the request validation paths: empty prompt, bad executor, scope-denied workspace) would lock the contract.
• Two roundtrips: this is an MCP tool ⇒ HTTP layer; the two send_json calls go to localhost. Negligible. Could in principle be folded into a single backend endpoint (POST /api/sessions/create-and-run), but that's a larger change and out of scope.

Verdict

Approve.

— Reviewed by automated single-pass review (MCP convenience tool; full 4-tool battery skipped — implementation mirrors existing tools, error recovery for partial failure is well-designed).