feat(ext-tasks): example pair + docs riders (slice C)

examples/ext-tasks-server (port 8645, server + client bins, both
live-verified):
- crunch: 2s long-runner — declared client gets a task handle and
  task_wait polls at the server's pollIntervalMs to the result;
  undeclared client blocks ~2s for the synchronous answer (progressive
  enhancement contrast in one walkthrough)
- deploy: mid-task elicited approval — input_required → tasks/update →
  'deployed billing-api ✅'; the tool body is byte-identical MRTR code
  that works under both execution models

EXAMPLES.md: pairing row + feature row + counts (54 active; count-vs-
rows sweep green). Gate/CI step builds the example; fixed the step's
cargo invocation (--bins cannot repeat — single trailing flag covers
all selected packages; caught by the gate run itself).

Full ci-gates.sh all green.

Author: hortovanyi

.github/workflows/ci.yml

@@ -71,7 +71,7 @@ jobs:
       - name: 2026 client example (pairs with minimal-server)
         run: cargo build -p streamable-http-client
       - name: Client-using examples (not in default-members)
-        run: cargo build -p mrtr-elicitation-server --bins -p bilingual-fleet-client
+        run: cargo build -p mrtr-elicitation-server -p bilingual-fleet-client -p ext-tasks-server --bins
       - name: Tasks extension (SEP-2663, opt-in feature)
         run: cargo test -p turul-mcp-server --no-default-features --features http,sse,ext-tasks --test ext_tasks_2026
       - name: Extension crates standalone

CHANGELOG.md

@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`ext-tasks-server` example pair (2026-06-12, SEP-2663 — slice C).** Task-electing server (port 8645: `crunch` long-runner + `deploy` with mid-task elicited approval) and a client walkthrough bin driving the full lifecycle — task handle → `task_wait` polling at the server's `pollIntervalMs` → `input_required` → `tasks/update` → completed, plus the progressive-enhancement contrast (the same tool blocks ~2s and answers synchronously for an undeclared client). Live-verified end to end; EXAMPLES.md pairing row + counts (54 active); built by the client-using-examples gate step.
 - **Tasks-extension client surface (2026-06-12, SEP-2663 — slice B).** New opt-in `ext-tasks` feature on `turul-mcp-client`: `declared_capabilities.ext_tasks = true` declares `io.modelcontextprotocol/tasks` in every 2026 request's `_meta` `clientCapabilities.extensions`; `call_tool_or_task(name, args)` returns `ToolCallOutcome::Completed | Task` (the server is the sole decider — the typed union replaces guessing); `task_get`/`task_update`/`task_cancel` bind the lifecycle methods; `task_wait` polls to a terminal status honoring the server's `pollIntervalMs` (clamped 50ms–30s). The strict BP-1 parser is untouched — plain `call_tool` still rejects unknown `resultType`s; only the ext-aware path accepts `"task"`. 4 real-server e2e tests (`ext_tasks_e2e_2026.rs`, gates + CI): task→poll→completed, sync fallback for undeclared clients, `task_update` resuming an `input_required` task, cancel-to-cancelled; revert-and-fail recorded (suppressing the capability emission fails the task-outcome test with a sync result).
 - **Tasks-extension server runtime (2026-06-12, SEP-2663 — closes driver gap G1).** New opt-in `ext-tasks` feature on `turul-mcp-server` (off by default per SEP-2133): `.with_ext_tasks(store)` advertises `io.modelcontextprotocol/tasks` in `server/discover`'s `capabilities.extensions` and registers `tasks/get`/`tasks/update`/`tasks/cancel`; `.ext_task_tool(tool)` / `.ext_task_tool_required(tool)` mark tools for task election — a request whose per-request `_meta` `clientCapabilities.extensions` declares the extension gets a durable `CreateTaskResult` (UUIDv4 bearer-grade id, store written BEFORE the response) with a spawned worker; undeclared requests run synchronously (progressive enhancement) or, for `_required` tools, get `-32003` with the upstream `data.requiredCapabilities.extensions` shape. **MRTR bridge**: a task tool returning `McpError::InputRequired` parks its task in `input_required`; `tasks/update` validates response keys against outstanding requests (partial delivery keeps it parked) and resumes the worker with the responses injected through the same session-extension keys as the sync retry leg — tool code is identical under both execution models. `tasks/cancel` is cooperative (aborts the worker, drops input waiters, acks terminal tasks). `notifications/tasks` rides `subscriptions/listen`: the transport honors a `taskIds` filter iff the extension is advertised (keyed off the capability map — no transport dependency on the ext crate), echoes it in the ack, and delivers per-taskId. `turul-mcp-ext-tasks` gains the `TaskStore` trait + `TaskState` + `InMemoryTaskStore` (no tokio in the public API). 9 wire e2e tests (`ext_tasks_2026.rs`, wired into gates + CI); revert-and-fail recorded. Dispatcher design recorded in ADR-028 (2026-06-12 entry).
 - **`turul-mcp-ext-apps` 0.1.0 scaffold (2026-06-12, SEP-1865).** Spec-neutral extension crate binding the MCP-side Apps surface: extension identifier `io.modelcontextprotocol/ui` (the ADR-028 table's `/apps` guess corrected against upstream), client capability (`UiClientCapabilities.mimeTypes` + the `text/html;profile=mcp-app` HTML-views gate), tool `_meta.ui` (`UiToolMeta`: `resourceUri`, `visibility` model/app), and UI-resource `_meta.ui` (`UiResourceMeta`: CSP domain lists, sandbox permissions, dedicated origin, `prefersBorder`). The host↔view iframe protocol is deliberately not bound (app/host SDK scope). Vendored spec pinned at `modelcontextprotocol/ext-apps@ca1d2989`; 5 wire-shape compliance tests.

Cargo.toml

@@ -33,6 +33,7 @@ members = [
   "examples/derive-macro-server",
   "examples/dynamic-tools-server",
   "examples/elicitation-server",
+  "examples/ext-tasks-server",
   "examples/function-macro-server",
   "examples/function-resource-server",
   "examples/lambda-mcp-client",

EXAMPLES.md

@@ -1,6 +1,6 @@
 # MCP Framework Examples
 
-This document provides a comprehensive overview of all **53 active examples** in the MCP Framework (plus `examples/archived/` — grown by 5 in the 2026-06-12 archive slice, see `docs/plans/2026-07-28-examples-review.md`), organized by learning progression from basic concepts to advanced implementations.
+This document provides a comprehensive overview of all **54 active examples** in the MCP Framework (plus `examples/archived/` — grown by 5 in the 2026-06-12 archive slice, see `docs/plans/2026-07-28-examples-review.md`), organized by learning progression from basic concepts to advanced implementations.
 
 **✅ All active examples compile under their lane's CI gates** (2026-07-28 default lane
 + per-manifest 2025-11-25 pins). Per-example functional re-verification against the
@@ -17,6 +17,7 @@ lane** — run the server first, then point the client at it.
 |---|---|---|---|
 | `streamable-http-client` | **2026-07-28** | `minimal-server` (port 8641); point at `notification-server` (port 8005) for live subscription deliveries | The canonical 2026 stateless pair: `connect()` negotiation, discover retention, `call_tool`, request-scoped progress, and the ack-first `subscriptions_listen` stream |
 | `mrtr-elicitation-client` (in `mrtr-elicitation-server`) | **2026-07-28** | `mrtr-elicitation-server` (port 8642) | The MRTR round trip: `input_required` → answer → `call_tool_with_input_responses` |
+| `ext-tasks-client` (in `ext-tasks-server`) | **2026-07-28** | `ext-tasks-server` (port 8645) | SEP-2663 task lifecycle: `call_tool_or_task` → poll → `tasks/update` → completed; sync fallback for undeclared clients |
 | `bilingual-fleet-client` | **both** | any mix (demo: `minimal-server` + `client-initialise-server`) | One binary sweeping a mixed 2025/2026 fleet — per-connection negotiation |
 | `streamable-http-client-2025-11-25` | 2025-11-25 | `client-initialise-server` (alternatives: any 2025-pinned server) | Hand-parsed 2025 POST SSE framing |
 | `client-initialise-report` | 2025-11-25 (wire-pinned) | `client-initialise-server` | Raw-wire lifecycle compliance probe |
@@ -73,7 +74,7 @@ cargo run -p minimal-server
 | **function-resource-server** | 8008 | ✅ VALIDATED | Function-based resources | Resource function patterns |
 | **session-aware-resource-server** | 8008 | ✅ VALIDATED | Session-aware resources (2025-11-25 pinned) | Session context integration on the stateful lane |
 
-## 🟢 **FEATURE-SPECIFIC SERVERS** (13 examples) - Specialized MCP Features
+## 🟢 **FEATURE-SPECIFIC SERVERS** (14 examples) - Specialized MCP Features
 
 | Example | Port | Status | Description | Key Features |
 |---------|------|--------|-------------|--------------|
@@ -88,6 +89,7 @@ cargo run -p minimal-server
 | **mrtr-elicitation-server** | 8642 | ✅ VALIDATED | MRTR elicitation round trip (2026) | `InputRequired` → retry with `inputResponses`; paired client bin |
 | **origin-policy-server** | 8643 | ✅ VALIDATED | Origin validation / DNS-rebinding (2026) | `OriginPolicy` default/AllowList/Disabled; 403 matrix verified live |
 | **header-bound-tools-server** | 8644 | ✅ VALIDATED | SEP-2243 header-bound tool params (2026) | `x-mcp-header` → `Mcp-Param-*` mirroring; -32001 contract verified live |
+| **ext-tasks-server** | 8645 | ✅ VALIDATED | Tasks extension (SEP-2663, 2026) | Task election + polling + `tasks/update` mid-task input; paired client bin; live-verified |
 | **oauth-resource-server** | 8080 | ✅ VALIDATED | OAuth 2.1 Resource Server (RFC 9728) | JWKS Bearer validation, PRM well-known routes, `--required-scope` → 403 insufficient_scope |
 | **dynamic-tools-server** | 8484 | ✅ VALIDATED | Dynamic tool registration (2025-pinned) | `ToolRegistry` + `notifications/tools/list_changed` on the stateful lane |
 
@@ -180,7 +182,7 @@ These examples demonstrate MCP 2025-11-25 type construction without starting a s
 
 ## 🚨 **COMPREHENSIVE VALIDATION RESULTS**
 
-### ✅ **ALL 53 ACTIVE EXAMPLES COMPILE UNDER THEIR LANE'S CI GATES**
+### ✅ **ALL 54 ACTIVE EXAMPLES COMPILE UNDER THEIR LANE'S CI GATES**
 **0.4.0 branch (MCP 2026-07-28 default, 2025-11-25 opt-in) — last reconciled 2026-06-12.**
 The per-example functional verification ledger lives in
 `docs/plans/2026-07-28-examples-review.md`; the 2026-06-12 migrate slice
@@ -189,7 +191,7 @@ re-verified its six examples live on the wire.
 - **Getting Started** - 5 examples (all tool creation levels)
 - **Session Storage** - 3 examples (SQLite, PostgreSQL, DynamoDB)
 - **Resource Servers** - 6 examples (session-aware resources)
-- **Feature-Specific** - 13 examples (prompts, sampling, elicitation, MRTR, origin policy, header binding, OAuth RS, etc.)
+- **Feature-Specific** - 14 examples (prompts, sampling, elicitation, MRTR, tasks extension, origin policy, header binding, OAuth RS, etc.)
 - **Advanced/Composite** - audit-trail, pagination, icon showcase
 - **Session & State** - stateful-server + session-aware-resource-server (2025-pinned) and the storage-backend trio
 - **Client Examples** - see the pairs table above (9 pairing rows)
@@ -210,7 +212,7 @@ re-verified its six examples live on the wire.
 - **Live-verified**: migrated and new examples were verified by running them and executing their own printed commands
 
 ### 📊 **Statistics**
-- **Total Examples**: 53 active (29 archived in `examples/archived/`)
+- **Total Examples**: 54 active (29 archived in `examples/archived/`)
 - **Session state (2025-pinned lane)**: stateful-server, session-aware-resource-server, and the logging/session test fixtures demonstrate cross-request session state on the opt-in lane; 2026-default examples use request-scoped context or app-owned storage instead
 - **Client-Server Pairs**: 9 pairing-table rows validating communication patterns
 - **Task Support**: 3 examples demonstrating MCP 2025-11-25 task lifecycle (InMemory storage)

examples/ext-tasks-server/Cargo.toml

@@ -0,0 +1,31 @@
+# Uses the ext-tasks features of both server and client, so it stays out of
+# default-members (like the other client-using examples) and is built by an
+# explicit gate step.
+[package]
+name = "ext-tasks-server"
+version = "0.4.0"
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+
+[dependencies]
+turul-mcp-server = { workspace = true, features = ["ext-tasks"] }
+turul-mcp-protocol.workspace = true
+turul-mcp-builders.workspace = true
+turul-mcp-ext-tasks.workspace = true
+turul-mcp-client = { workspace = true, features = ["ext-tasks"] }
+async-trait.workspace = true
+tokio.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true
+serde_json.workspace = true
+
+[[bin]]
+name = "ext-tasks-server"
+path = "src/main.rs"
+test = false
+
+[[bin]]
+name = "ext-tasks-client"
+path = "src/client.rs"
+test = false

examples/ext-tasks-server/README.md

@@ -0,0 +1,87 @@
+# Tasks Extension (`io.modelcontextprotocol/tasks`, SEP-2663)
+
+Durable poll handles instead of blocking on long-running tool calls — the
+2026-07-28 replacement for the 2025 core task lifecycle (no `tasks/list`, no
+blocking `tasks/result`; polling via `tasks/get`, mid-task input via the new
+`tasks/update`).
+
+```bash
+cargo run -p ext-tasks-server                              # server, port 8645
+cargo run -p ext-tasks-server --bin ext-tasks-client       # client walkthrough
+```
+
+## What the walkthrough shows (live-verified)
+
+```text
+→ crunch(7) with the extension declared
+← task 45588cc8… (Working, pollIntervalMs 500) — polling…
+← completed: "49"
+
+→ deploy(billing-api)
+← task 72434fe1… — polling for the approval request…
+← input_required: Approve deployment of billing-api?
+→ tasks/update: approved = true
+← completed: "deployed billing-api ✅"
+
+→ crunch(3) WITHOUT declaring the extension
+← synchronous (blocked ~2s): "9"
+```
+
+## The lifecycle
+
+1. **Declare** — the client puts `io.modelcontextprotocol/tasks` in every
+   request's `_meta` `clientCapabilities.extensions`
+   (`declared_capabilities.ext_tasks = true`). The server advertises the same
+   in `server/discover`.
+2. **Elect** — the server is the sole decider: a task-electing tool answers a
+   declared client with `CreateTaskResult` (`resultType: "task"`), durably
+   stored before the response. Undeclared clients get the ordinary
+   synchronous result — same tool, progressive enhancement.
+3. **Poll** — `tasks/get` until terminal, honoring `pollIntervalMs`
+   (`McpClient::task_wait` does this).
+4. **Mid-task input** — `deploy` returns `McpError::InputRequired` exactly
+   like a synchronous MRTR tool; under task election the runtime parks the
+   task in `input_required` and `tasks/update` resumes it. **Tool code is
+   identical under both execution models.**
+5. **Terminal** — `completed` carries the result the sync call would have
+   returned; `failed` carries the JSON-RPC error; `tasks/cancel` is
+   cooperative.
+
+## Server side
+
+```rust
+McpServer::builder()
+    .with_ext_tasks(Arc::new(InMemoryTaskStore::new()))  // advertises + registers tasks/*
+    .ext_task_tool(CrunchTool::new())                    // elect when declared, sync otherwise
+    .ext_task_tool(DeployTool::new())
+    // .ext_task_tool_required(...)                      // -32003 when undeclared
+```
+
+Requires the `ext-tasks` cargo feature on `turul-mcp-server` (extensions are
+off by default per SEP-2133).
+
+## Client side
+
+```rust
+let mut config = ClientConfig::default();
+config.declared_capabilities.ext_tasks = true;
+// ...
+match client.call_tool_or_task("crunch", json!({"n": 7})).await? {
+    ToolCallOutcome::Task(t) => {
+        let done = client.task_wait(&t.task.fields.task_id).await?;
+    }
+    ToolCallOutcome::Completed(r) => { /* server chose sync */ }
+}
+```
+
+Requires the `ext-tasks` cargo feature on `turul-mcp-client`.
+
+## See also
+
+- `mrtr-elicitation-server` — the synchronous MRTR round trip the `deploy`
+  tool also works under
+- `crates/turul-mcp-server/tests/ext_tasks_2026.rs` — the wire contract suite
+  (incl. `-32003` for required tools and `taskIds`-filtered
+  `notifications/tasks` over `subscriptions/listen`)
+- `tasks-e2e-inmemory-server` — the 2025-11-25 core task lifecycle this
+  extension replaces (kept on the pinned 2025 lane)

examples/ext-tasks-server/src/client.rs

@@ -0,0 +1,115 @@
+//! # Tasks Extension Client (SEP-2663)
+//!
+//! The client leg against `ext-tasks-server`:
+//!
+//! 1. Declare the extension (`declared_capabilities.ext_tasks = true`).
+//! 2. `call_tool_or_task("crunch")` → a task handle; `task_wait` polls
+//!    (honoring `pollIntervalMs`) to the completed result.
+//! 3. `call_tool_or_task("deploy")` → the task parks in `input_required`;
+//!    answer the elicited approval via `task_update`; poll to completion.
+//! 4. The same `crunch` from an UNDECLARED client → ordinary synchronous
+//!    result (progressive enhancement).
+
+use serde_json::json;
+use turul_mcp_client::transport::HttpTransport;
+use turul_mcp_client::{ClientConfig, McpClient, McpVersion, ToolCallOutcome};
+use turul_mcp_ext_tasks::DetailedTask;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env().unwrap_or_else(|_| "warn".into()),
+        )
+        .init();
+
+    let url = std::env::args()
+        .nth(1)
+        .unwrap_or_else(|| "http://127.0.0.1:8645/mcp".to_string());
+    println!("Connecting to {url} (start it with: cargo run -p ext-tasks-server)");
+
+    let mut config = ClientConfig::default();
+    config.declared_capabilities.ext_tasks = true;
+    let client = McpClient::new(Box::new(HttpTransport::new(&url)?), config);
+    client.connect().await?;
+    if client.negotiated_version().await != Some(McpVersion::V2026_07_28) {
+        println!("Peer is not a 2026-07-28 server — the Tasks extension needs the 2026 wire.");
+        return Ok(());
+    }
+
+    // 1. Long-running call → durable task handle, poll to completion.
+    println!("\n→ crunch(7) with the extension declared");
+    match client
+        .call_tool_or_task("crunch", json!({ "n": 7 }))
+        .await?
+    {
+        ToolCallOutcome::Task(task) => {
+            println!(
+                "← task {} ({:?}, pollIntervalMs {:?}) — polling…",
+                task.task.fields.task_id, task.task.status, task.task.fields.poll_interval_ms
+            );
+            let done = client.task_wait(&task.task.fields.task_id).await?;
+            if let DetailedTask::Completed { result, .. } = done {
+                println!("← completed: {}", result["content"][0]["text"]);
+            }
+        }
+        ToolCallOutcome::Completed(r) => println!("← completed synchronously: {r:?}"),
+    }
+
+    // 2. Mid-task input: deploy parks in input_required until tasks/update.
+    println!("\n→ deploy(billing-api)");
+    let ToolCallOutcome::Task(task) = client
+        .call_tool_or_task("deploy", json!({ "service": "billing-api" }))
+        .await?
+    else {
+        println!("← unexpectedly synchronous");
+        return Ok(());
+    };
+    let task_id = task.task.fields.task_id.clone();
+    println!("← task {task_id} — polling for the approval request…");
+    loop {
+        let t = client.task_get(&task_id).await?;
+        match &t {
+            DetailedTask::InputRequired { input_requests, .. } => {
+                let msg = input_requests
+                    .get("approval")
+                    .and_then(|r| serde_json::to_value(r).ok())
+                    .and_then(|v| {
+                        v.pointer("/params/message")
+                            .and_then(|m| m.as_str().map(String::from))
+                    })
+                    .unwrap_or_default();
+                println!("← input_required: {msg}");
+                println!("→ tasks/update: approved = true");
+                client
+                    .task_update(
+                        &task_id,
+                        json!({ "approval": { "action": "accept", "content": { "approved": true } } }),
+                    )
+                    .await?;
+                break;
+            }
+            t if t.status().is_terminal() => break,
+            _ => tokio::time::sleep(std::time::Duration::from_millis(100)).await,
+        }
+    }
+    let done = client.task_wait(&task_id).await?;
+    if let DetailedTask::Completed { result, .. } = done {
+        println!("← completed: {}", result["content"][0]["text"]);
+    }
+
+    // 3. Progressive enhancement: an UNDECLARED client gets the sync result.
+    println!("\n→ crunch(3) WITHOUT declaring the extension");
+    let plain = McpClient::new(Box::new(HttpTransport::new(&url)?), ClientConfig::default());
+    plain.connect().await?;
+    match plain.call_tool_or_task("crunch", json!({ "n": 3 })).await? {
+        ToolCallOutcome::Completed(r) => {
+            let v = serde_json::to_value(&r)?;
+            println!("← synchronous (blocked ~2s): {}", v["content"][0]["text"]);
+        }
+        ToolCallOutcome::Task(_) => println!("← BUG: task handle for an undeclared client"),
+    }
+
+    println!("\nDone — task ids are durable handles; re-run tasks/get any time before TTL.");
+    Ok(())
+}